58 lines
1.6 KiB
Markdown
58 lines
1.6 KiB
Markdown
# 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.
|