Orchestrator Event Envelope (draft)

Status: draft for ORCH-SVC-38-101 (pending ORCH-SVC-37-101 approval)

Goals

• Single, provenance-rich envelope for policy/export/job lifecycle events.
• Idempotent across retries and transports (Notifier bus, webhooks, SSE/WS streams).
• Tenant/project isolation and offline-friendly replays.

Envelope

{
  "schemaVersion": "orch.event.v1",
  "eventId": "urn:orch:event:...",            // UUIDv7 or ULID
  "eventType": "job.failed|job.completed|pack_run.log|pack_run.artifact|policy.updated|export.completed",
  "occurredAt": "2025-11-19T12:34:56Z",
  "idempotencyKey": "orch-{eventType}-{jobId}-{attempt}",
  "correlationId": "corr-...",                 // propagated from producer
  "tenantId": "...",
  "projectId": "...",                          // optional but preferred
  "actor": {
    "subject": "service/worker-sdk-go",        // who emitted the event
    "scopes": ["orch:quota", "orch:backfill"]
  },
  "job": {
    "id": "job_018f...",
    "type": "pack-run|ingest|export|policy-simulate",
    "runId": "run_018f...",                    // for pack runs / sims
    "attempt": 3,
    "leaseId": "lease_018f...",
    "taskRunnerId": "tr_018f...",
    "status": "completed|failed|running|canceled",
    "reason": "user_cancelled|retry_backoff|quota_paused",
    "payloadDigest": "sha256:...",
    "artifacts": [
      {"uri": "s3://...", "digest": "sha256:...", "mime": "application/json"}
    ]
  },
  "metrics": {
    "durationSeconds": 12.345,
    "logStreamLagSeconds": 0.8,
    "backoffSeconds": 30
  },
  "notifier": {
    "channel": "orch.jobs",
    "delivery": "dsse",
    "replay": {"ordinal": 5, "total": 12}
  }
}

Idempotency rules

• eventId globally unique; idempotencyKey dedupe per channel.
• Emit once per state transition; retries reuse the same eventId/idempotencyKey.

Provenance

• Always include tenantId and projectId (if available).
• Carry correlationId from upstream producers and taskRunnerId from leasing bridge.
• Include actor.scopes when events are triggered via elevated tokens (orch:quota, orch:backfill).

Transport bindings

• Notifier bus: DSSE-wrapped envelope; subject orch.event and eventType.
• Webhooks: HMAC with X-Orchestrator-Signature (sha256), replay-safe via idempotencyKey.
• SSE/WS: stream per tenantId filtered by projectId; client dedupe via eventId.

Backlog & follow-ups

• Align field names with ORCH-SVC-37-101 once finalized.
• Add examples for policy/export events and pack-run log/manifest payloads.
• Document retry/backoff semantics in Notify/Console subscribers.