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