narratio/docs/internal/manifest.md

Internal: Manifest

Purpose

Define durable session state (manifest.json) and invocation state (runs/{run_id}/manifest.json) contracts.

Session Manifest

Path:

• {workspace.root}/work/{campaign}/{session_id}/manifest.json

Primary model (manifest.Manifest):

• identity (session_id, campaign, run_id)
• local path metadata (local_workdir, local_spool_dir)
• remote identity metadata (s3_bucket, s3_session_prefix, s3_run_prefix)
• inputs records
• durable artifacts records
• per-stage stages map

Stage status enum:

• pending
• running
• succeeded
• failed
• skipped
• stale
• interrupted

Run Manifest

Path:

• {workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/manifest.json

Run model (manifest.RunManifest):

• invocation identity and force flag
• requested stages
• per-stage action (run or skip)
• per-stage status
• overall run status (running, succeeded, failed)

Persistence Semantics

manifest.LocalStore:

• validates loaded documents;
• normalizes missing maps/stage records;
• writes atomically via temp file + rename;
• updates updated_at on save.

Execution Semantics

Runner updates both manifests per stage transition:

• mark running
• mark succeeded/failed/skipped
• persist logs/generated config refs and metadata

Session manifest is the authoritative stage-progress ledger across invocations. Run manifest is invocation-scoped audit state.

Invariants

• stage resume/skip decisions are session-manifest driven.
• force reruns stale downstream succeeded stages.
• run manifest does not replace session manifest as progress authority.