stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
18246cd74c244be1fe11ad73613b674e23563bcf
git.stella-ops.org/docs/modules/jobengine/job-export-contract.md

2.7 KiB
Raw Blame History

Orchestrator → Findings Ledger Export Contract

Status: Available (2025-12-03) Scope: defines the deterministic payload Orchestrator emits for job/run exports that Findings Ledger ingests for provenance (LEDGER-34-101).

Payload shape

{
  "runId": "uuid",                 // job/run correlation id
  "jobType": "string",             // e.g., mirror-build, policy-sim, scan
  "artifactHash": "sha256:...",    // CAS digest of primary artifact
  "policyHash": "sha256:...",      // optional; policy bundle hash
  "startedAt": "2025-12-02T00:00:00Z",
  "completedAt": "2025-12-02T00:05:30Z",
  "status": "succeeded|failed|canceled",
  "manifestPath": "cas://.../manifest.json",  // DSSE or CAS path
  "logsPath": "cas://.../logs.ndjson",
  "tenantId": "string",
  "environment": "prod|stage|dev",
  "idempotencyKey": "sha256:...",   // runId+artifactHash
  "signatures": [ { "type": "dsse", "keyId": "...", "signature": "..." } ]
}

Determinism & ordering

  • Entries sorted by runId when streamed; pagination stable via runId, startedAt ascending.
  • idempotencyKey = sha256(runId + artifactHash + tenantId); duplicate submissions are rejected with 409.
  • Timestamps UTC ISO-8601; no clock-skew correction performed by Ledger.

Transport

  • REST: POST /internal/jobengine/exports (Orchestrator) → Findings Ledger ingest queue.
  • Events: orchestrator.export.created carries the same payload; consumers must verify DSSE before persistence.

Validation rules (Ledger side)

  • Require DSSE signature (Ed25519) when signatures present; fail closed if verification fails.
  • Enforce presence of runId, artifactHash, startedAt, status.
  • Hash fields must match ^sha256:[A-Fa-f0-9]{64}$.
  • Allowed status transitions: pending→running→succeeded/failed/canceled; replays only allowed when idempotencyKey matches existing record.

Mapping to Findings Ledger

  • Stored in collection/table orchestrator_exports with index (artifactHash, runId) and TTL optional on logs if configured.
  • Timeline entry type ledger_export references runId, artifactHash, policyHash, manifestPath, logsPath, DSSE envelope digest, and idempotencyKey.
  • Cross-links: bundleId (if mirror build) or scanId (if scan job) may be added as optional fields; Ledger treats them as opaque strings.

Security / scopes

  • Required scope: orchestrator:exports:write for producer; Ledger ingress validates tenant headers and scope.
  • Max payload: 1 MiB; logs must be CAS/DSSE referenced, not inline.

Offline/air-gap considerations

  • CAS/DSSE paths must resolve within offline kit bundles; no external URIs permitted.
  • Deterministic ordering + idempotency allow replay without side effects; Ledger rejects writes when DSSE or hash mismatch.