up

docs/schemas/artifacts.md

@@ -0,0 +1,49 @@
+# 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)
+```json
+{
+  "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.