git.stella-ops.org/docs/schemas/artifacts.md

Artifacts Schema (DOCS-ORCH-34-004)

Last updated: 2025-11-25

Purpose

Describe artifact kinds produced by Orchestrator runs and how they are stored, hashed, and referenced.

Artifact kinds

• log: NDJSON log fragment for a step/run.
• metrics: Prometheus/OpenMetrics snapshot for a step/run.
• output: arbitrary task output (JSON, NDJSON, binary), content-addressed.
• manifest: bundle manifest listing artifacts and hashes.

Schema (common fields)

{
  "kind": "log|metrics|output|manifest",
  "tenant": "acme",
  "dagId": "string",
  "runId": "string",
  "stepId": "string",
  "contentType": "application/json",
  "hash": "sha256:<hex>",
  "size": 1234,
  "createdUtc": "2025-11-25T00:00:00Z",
  "traceId": "optional",
  "encryption": "none|aes256-gcm",
  "compression": "none|gzip"
}

Storage rules

• Content-addressed by sha256 (lowercase hex). Filenames may use <hash>; metadata kept in Mongo with tenant scoping.
• Immutable; new versions create new hashes.
• Optional encryption: AES-256-GCM with keys from Authority secretRef; never store keys alongside artifacts.
• Compression optional (gzip) but hash is computed on compressed bytes; record compression.

Access & security

• Tenant-scoped reads; artifacts cannot be shared across tenants.
• No secrets stored; redact before writing. Logs/metrics already redacted at source.
• Access control enforced via orchestrator scopes; audit log every download/export.

Offline posture

• Artifacts may be exported as tarball with manifest (manifest kind) that lists hash, size, compression/encryption flags.
• Imports verify manifest hash and per-artifact hash before accepting.

Determinism

• Hash and size recorded at creation; manifests sorted by kind, then dagId, runId, stepId, hash.
• Timestamps UTC ISO-8601; NDJSON ordering stable.