# 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
```jsonc
{
  "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.