81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# Internal: Manifest
|
|
|
|
## Purpose
|
|
Describe Narratio's durable execution state model for session-level and run-level manifests, including lifecycle transitions and persistence behavior.
|
|
|
|
## Inputs and outputs
|
|
Inputs:
|
|
- Session identity and run identity from app orchestration.
|
|
- Stage transition events and stage result payloads.
|
|
|
|
Outputs:
|
|
- Session manifest at `{workspace.root}/work/{campaign}/{session_id}/manifest.json`.
|
|
- Run manifest at `{workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/manifest.json`.
|
|
|
|
## Boundaries
|
|
Owns:
|
|
- Manifest schemas (`Manifest`, `RunManifest`, stage records, error records, input/artifact records).
|
|
- Stage status/action transition methods.
|
|
- Persistent store contract (`manifest.Store`) and local JSON store implementation.
|
|
|
|
Does not own:
|
|
- Stage implementation details.
|
|
- Path construction policy outside manifest file persistence calls.
|
|
- CLI command behavior.
|
|
|
|
## Config fields used
|
|
Manifest package itself does not read config directly.
|
|
|
|
Manifest identity fields are populated by app/stage orchestration from:
|
|
- `session.session_id`
|
|
- `session.campaign`
|
|
- `pipeline.workspace.root`
|
|
- `pipeline.storage.s3.*` (when archive/S3 identity is set)
|
|
|
|
## External adapters used
|
|
- No external service adapters.
|
|
- Uses local filesystem for persistence via `manifest.LocalStore`.
|
|
|
|
## State and manifest behavior
|
|
Session manifest model:
|
|
- Tracks durable per-session stage state and provenance (`pending`, `running`, `succeeded`, `failed`, `skipped`, `stale`, `interrupted`).
|
|
- Stores resolved inputs, durable artifacts, stage logs/config refs, and stage metadata.
|
|
|
|
Run manifest model:
|
|
- Tracks one invocation (`run_id`) with requested stages and force mode.
|
|
- Tracks per-stage action (`run` or `skip`) and per-stage status.
|
|
- Tracks overall run status (`running`, `succeeded`, `failed`).
|
|
|
|
Persistence behavior:
|
|
- Load validates required identity/timestamp fields and normalizes maps/records.
|
|
- Save updates `updated_at` and writes JSON atomically (temp file + rename).
|
|
- Session and run manifests are saved incrementally before/after stage transitions.
|
|
|
|
Relationship during execution:
|
|
- Runner updates both manifests for every stage transition.
|
|
- Session manifest is the durable pipeline-progress ledger.
|
|
- Run manifest is invocation history and audit record.
|
|
|
|
## Skip and resume behavior
|
|
- Resume and skip decisions are based on session-manifest stage statuses.
|
|
- `--force` reruns selected stages and marks downstream succeeded stages as `stale` in session manifest.
|
|
- Run manifest records whether each stage was executed or skipped in that invocation.
|
|
|
|
## Failure behavior
|
|
- Stage failure marks both manifests failed for that stage and records error messages/timestamps.
|
|
- Save failures are returned immediately and fail the command.
|
|
- Invalid/malformed manifest files fail load with explicit validation/decode errors.
|
|
|
|
## Tests to inspect before changing
|
|
- `internal/manifest/manifest_test.go`
|
|
- `internal/manifest/run_manifest_test.go`
|
|
- `internal/manifest/store_test.go`
|
|
- `internal/app/runner_test.go`
|
|
- `internal/app/run_control_test.go`
|
|
- `internal/app/resume_run_stage_test.go`
|
|
|
|
## Architectural invariants
|
|
- Session manifest is authoritative for stage progression across invocations.
|
|
- Run manifest is invocation-scoped and never replaces session manifest as progress authority.
|
|
- Manifest writes are atomic and deterministic (JSON + newline, temp rename pattern).
|