Orchestrator Run Ledger (DOCS-ORCH-34-001)

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

Last updated: 2025-11-25

Purpose

Immutable record of every DAG run and step execution for audit, replay, and offline export.

tenant, runId, dagId, dagVersion, runToken, traceId
status (running|completed|failed|cancelled)
inputsHash, outputsHash (overall)
startedUtc, endedUtc, durationMs
steps[]:
- stepId, status, attempt, startedUtc, endedUtc, durationMs
- inputsHash, outputsHash, logsRef, metricsRef, errorCode, retryable
events[] (optional): ordered list of significant events with timestamp, type, message, actor

PostgreSQL table partitioned by tenant; indexes on (tenant, dagId, runId), (tenant, status, startedUtc).
Artifacts/logs referenced by content hash; stored separately (object storage/RustFS).
Append-only updates; run status transitions are monotonic.

NDJSON export sorted by startedUtc, then runId; includes steps/events inline.
Exports include manifest with hash and count for determinism.

Metrics derived from ledger: run counts, durations, failure rates, retry counts.
Trace links preserved via stored traceId.

Runs never mutated or deleted; cancellation recorded as an event.
Access is tenant-scoped; admin queries require orchestrator:admin.
Replay tokens can be derived from inputsHash + dagVersion; consumers must log rationale when replaying.