78 lines
2.3 KiB
Markdown
78 lines
2.3 KiB
Markdown
# 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`
|