diff --git a/docs/cli.md b/docs/cli.md index 3efa400..6583c86 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -40,14 +40,31 @@ Most session-aware commands accept: - `--campaign ` - `--campaign-file ` - `--session ` -- `--previous-session-id ` +- `--session-id ` +- `--previous-session-id ` Rules: - `--campaign` and `--campaign-file` are mutually exclusive. - `--session` is not used by `session init`. +- if both positional `` and `--session-id` are provided, values must match. - `clean --all` cannot be combined with campaign/session selectors. +## Session ID Input Rules + +Session-aware commands accept one of these forms: + +- positional session ID: `... ` +- compatibility flag: `... --session-id ` + +When both are present, command parsing requires an exact match. + +Commands with additional positionals keep their command-specific order: + +- `run-stage ` or `run-stage --session-id ` +- `session locks add ` or `session locks add --session-id ` +- `session locks remove ` or `session locks remove --session-id ` + ## Command Reference ### `run` @@ -187,7 +204,7 @@ Options: Rules: - `--audio-dir` and `--audio-s3-prefix` are mutually exclusive. -- if campaign `session_template_file` is configured, `session init` renders it; +- if campaign `session_template_file` is configured, `session init` renders it. - generated session YAML must be concrete (no unresolved `{{ ... }}` placeholders). ### `session restore` diff --git a/docs/internal/artifacts.md b/docs/internal/artifacts.md index 387803a..7bec623 100644 --- a/docs/internal/artifacts.md +++ b/docs/internal/artifacts.md @@ -1,9 +1,10 @@ # Internal: Artifacts ## Purpose -Define canonical artifact IDs, runtime catalog behavior, and source resolution rules for stage execution and publish output selection. +Define canonical artifact IDs, runtime catalog behavior, source resolution rules, and shared current-state mechanics used by app and previous-cache code. ## Built-in Source IDs + - `narratio.transcript.base` -> `transcripts/base.json` (`merge`) - `narratio.transcript.polished` -> `transcripts/polished.json` (`polish`) - `narratio.transcript.final` -> `transcripts/final.json` (`normalize`) @@ -11,58 +12,101 @@ Define canonical artifact IDs, runtime catalog behavior, and source resolution r - `narratio.bounds.session` -> `artifacts/session_bounds.json` (`trim`) ## Configured and Previous-Session Sources -- Configured artifact source ID: `narratio.artifact.` -- Previous-session source ID: `narratio.previous_session.artifact.` -Configured and previous-session source IDs are validated by strict regex rules. +- configured source ID format: `narratio.artifact.` +- previous-session source ID format: `narratio.previous_session.artifact.` + +Both formats are validated by strict source-policy rules. ## Runtime Catalog + `ArtifactCatalog` tracks: -- `planned`: source registered for run context. -- `executable`: selected and enabled for analyze execution. -- `available`: local file exists and validated. + +- `planned`: source registered for run context; +- `executable`: selected and enabled for analyze execution; +- `available`: local file exists and validates; - `provenance`: availability source. Current provenance values: + - `generated.current_analyze_run` - `filesystem.disabled_artifact_output` - `manifest.inputs.previous_cache` - `current_session.previous_cache` ## Resolution Rules + Built-ins: + 1. manifest producer outputs (when present) -2. canonical session path fallback +2. canonical session-path fallback Configured sources (`narratio.artifact.*`): + - resolve only through runtime catalog availability. Previous-session sources (`narratio.previous_session.artifact.*`): -- resolve only from local `previous/` cache state. -- prefer manifest-backed previous input paths. + +- resolve only from local `previous/` cache state; +- prefer manifest-backed previous-input paths; - fallback to existing previous-cache filesystem paths. Validation by content type: -- transcript built-ins: JSON with top-level `segments` array. -- bounds built-in: valid JSON. + +- transcript built-ins: JSON with top-level `segments` array; +- bounds built-in: valid JSON; - configured/previous-session artifact files: non-empty text file. ## Previous Requirement Collection + `CollectPreviousArtifactRequirements`: + - scans enabled configured artifacts only; - extracts only canonical previous-session sources; - deduplicates by artifact key; -- merges required/optional (required wins); +- merges required and optional references (required wins); - returns deterministic ordering and source locations. +## Current-State Helpers + +Artifacts package owns shared remote current-state loading mechanics used by restore, status/validate checks, and previous-cache planning. + +Core helpers: + +- `LoadCurrentRunPointer` +- `LoadCurrentManifest` +- `LoadCurrentState` +- `ValidateCurrentStateIdentity` + +Typed missing-state errors: + +- `CurrentRunPointerMissingError` (`ErrCurrentRunPointerMissing`) +- `CurrentManifestMissingError` (`ErrCurrentManifestMissing`) + +Identity validation supports caller-provided expectations: + +- expected campaign; +- expected session ID; +- expected run ID, or pointer/manifest run-ID consistency check. + +Caller policy is intentionally outside artifacts helpers: + +- some callers fail on missing current state; +- some callers downgrade missing state to status/findings; +- some callers skip optional behavior when state is missing. + ## Key Path Helpers -`internal/artifacts/paths.go` defines canonical helpers for: + +`internal/artifacts/paths.go` and S3-key helpers define canonical helpers for: + - session/work/run paths; - previous-cache paths; - spool/cache paths; -- S3 key layout helpers for session/run/current pointers. +- S3 session/run/current-state key layout. ## Invariants -- Source ID formats are stable contracts. -- Resolution is deterministic and manifest-aware. -- Previous-session source resolution does not call remote storage in `analyze`; remote hydration is `prepare` responsibility. + +- source ID formats are stable contracts; +- artifact resolution is deterministic and manifest-aware; +- previous-session source resolution in `analyze` is local-only; +- remote current-state key construction remains centralized in artifacts helpers. diff --git a/docs/internal/command-restore.md b/docs/internal/command-restore.md index 66f4d1a..6b20bf5 100644 --- a/docs/internal/command-restore.md +++ b/docs/internal/command-restore.md @@ -1,65 +1,84 @@ # Internal: Command Restore ## Purpose -Document the implemented `narratio session restore` command contract: +Define the implemented `narratio session restore` command contract: + - committed remote current-state discovery; -- deterministic restore plan classification; +- deterministic restore planning; - safe local install semantics; - durable restore reporting. ## Discovery Contract -Restore discovers remote committed state using: -- `current/run_id.txt` (required, non-empty) -- `current/manifest.json` (required, decodable) -Discovered manifest identity must match requested `session_id` and `campaign`. +Restore resolves remote committed state from the session publish current pointers: -## Plan Contract -Planner actions: -- `download` -- `skip_same` -- `conflict` +- `current/run_id.txt` (required, non-empty); +- `current/manifest.json` (required, decodable). + +Current-state discovery uses shared artifacts-level mechanics and validates identity against the resolved request config: + +- campaign must match; +- session ID must match. + +Restore treats any missing or invalid remote current state as a command error. + +## Planning Contract + +Restore planner action kinds: + +- `download`; +- `skip_same`; +- `conflict`. + +Planner behavior: -Plan behavior: - remote list scope is the resolved session prefix; -- mapping to local paths is traversal-safe; +- remote-to-local mapping is traversal-safe; - actions are sorted deterministically by local relative path. Restore scope from current remote state: -- include `manifest.json` -- include `transcripts/**` -- include `artifacts/**` -- include `audio/**` only with `--include-audio` + +- include `manifest.json`; +- include `transcripts/**`; +- include `artifacts/**`; +- include `audio/**` only with `--include-audio`. Explicit exclusions from current remote state mapping: -- `current/**` -- `runs/**` -- `logs/**` -- `reports/**` -- `config/**` -- `inputs/**` -- `previous/**` -Previous-cache restore files are planned separately through `previouscache.BuildPlan` when configured previous-session requirements exist. +- `current/**`; +- `runs/**`; +- `logs/**`; +- `reports/**`; +- `config/**`; +- `inputs/**`; +- `previous/**`. + +Previous-cache files are planned separately through `previouscache.BuildPlan` when configured previous-session requirements exist. ## Execution Contract + +Execution order and safety: + - non-manifest downloads happen before manifest install; -- `manifest.json` is installed last; -- downloads use sibling temp files + atomic rename; +- `manifest.json` installs last; +- downloads use sibling temp files plus atomic rename; - manifest replacement is validated before rename; -- failed installs do not roll back previously written files. +- failed installs do not roll back files already written in the same execution. Audio restore path: + - uses `audio.MaterializeS3Audio`; - integrates spool and S3 audio cache paths; -- supports cache hit reuse without object redownload. +- supports cache-hit reuse without object redownload. ## Reporting Contract -- dry-run: summary only (no writes). + +- `--dry-run`: prints summary only; no local writes. - non-dry-run: writes `reports/restore-latest.json`. -- report captures plan counts, action status, and execution failures. +- report includes plan counts, per-action status, and execution failures. ## Invariants -- restore uses only committed remote current state as authority. -- `current/run_id.txt` is the remote commit marker. -- restore is a standalone command and does not run stages. + +- restore uses committed remote current state as authority; +- `current/run_id.txt` is the remote publish commit marker; +- restore does not execute pipeline stages.