activity-core/docs/issue-core-emission-boundary.md

Issue-Core Emission Boundary

activity-core owns the decision to spawn a task and the audit trail that says why it spawned. It does not own downstream task lifecycle state after emission.

Current authoritative endpoint

The current authoritative boundary is the issue-core REST API:

POST {ISSUE_CORE_URL}/issues/

IssueCoreRestSink sends this payload:

{
  "title": "Run SBOM rescan for activity-core",
  "description": "",
  "target_repo": "activity-core",
  "priority": "medium",
  "labels": ["sbom", "security", "automated"],
  "due_in_days": null,
  "source_type": "rule",
  "source_id": "flag-stale-sbom",
  "triggering_event_id": "event-or-schedule-key",
  "activity_definition_id": "activity-definition-uuid"
}

The expected response contains issue_id and may include issue_url and backend. activity-core stores only the returned task reference in task_spawn_log; issue-core remains authoritative for task status, assignment, comments, closure, and cancellation.

REST versus NATS

Keep REST as the active emission contract until issue-core publishes and owns a durable NATS consumer for task-creation commands. NATS is still appropriate for event intake into activity-core, but task creation needs an acknowledged, idempotent command boundary. A future NATS sink must return or later correlate a task reference before it can replace IssueCoreRestSink.

Safe operating modes

• ISSUE_SINK_TYPE=null: dry-run/audit mode. Task specs are rendered and the workflow records synthetic null-* references. This is the current Railiance production setting.
• ISSUE_SINK_TYPE=rest: live task creation. Sink failures raise out of emit_tasks, so Temporal retries and the workflow history make failures visible.

Weekly SBOM staleness is safe to evaluate in dry-run mode because the rule contract is deterministic and tested. Do not enable it against the real REST sink until issue-core credentials, endpoint reachability, and duplicate-handling are verified in the target environment.

Verification

Local contract tests cover the rendered weekly SBOM task path and the REST payload shape:

uv run pytest tests/test_integration_event_bridge.py tests/test_issue_sink.py

For a live environment, run with ISSUE_SINK_TYPE=null first and confirm task_spawn_log contains the expected source id, condition, triggering event id, and synthetic task reference. Then switch to ISSUE_SINK_TYPE=rest only after a single known-safe rule match creates one issue-core task with the same fields.