Added new internal documentation

docs/internal/manifest.md

@@ -0,0 +1,80 @@
+# 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).