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.
Analyze stage outputs are persisted as kind=scriptorium_artifact with source_id=narratio.artifact.<name> for configured artifact identity.

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

3.5 KiB Raw Blame History