# 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.