# Internal: Manifest

## Purpose

Explain the session-progress and invocation-audit models implemented by
`internal/manifest`. Physical manifest placement belongs in
[Operations](../operations.md#local-state-layout).

## Session Manifest

`manifest.Manifest` records:

- 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

The model admits these stage states:

- `pending`
- `running`
- `succeeded`
- `failed`
- `skipped`
- `stale`
- `interrupted`

## Run Manifest

`manifest.RunManifest` is created for each invocation and records:

- 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

The application runner marks an executing stage running and then succeeded or
failed in both manifests, persisting each transition. On success it records
outputs, logs, generated configuration references, and metadata. A successful
forced rerun marks only succeeded downstream session-stage records stale.

When an already-succeeded stage is skipped, the invocation run manifest records
the `skip` action and reason. The session manifest deliberately retains its
existing succeeded record because it remains the cross-invocation progress
authority.

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.

## Implementation And Tests

- Models and transitions: `internal/manifest/manifest.go`,
  `internal/manifest/run_manifest.go`
- Persistence and validation: `internal/manifest/store.go`
- Package tests: `internal/manifest/*_test.go`
- Assembled execution behavior: `internal/app/runner_test.go`,
  `internal/app/run_stage_test.go`