Refresh CLI and internal restore documentation for current behavior
This commit is contained in:
21
docs/cli.md
21
docs/cli.md
@@ -40,14 +40,31 @@ Most session-aware commands accept:
|
||||
- `--campaign <id>`
|
||||
- `--campaign-file <campaign.yml>`
|
||||
- `--session <session.yml>`
|
||||
- `--previous-session-id <id>`
|
||||
- `--session-id <session_id>`
|
||||
- `--previous-session-id <session_id>`
|
||||
|
||||
Rules:
|
||||
|
||||
- `--campaign` and `--campaign-file` are mutually exclusive.
|
||||
- `--session` is not used by `session init`.
|
||||
- if both positional `<session_id>` 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: `... <session_id>`
|
||||
- compatibility flag: `... --session-id <session_id>`
|
||||
|
||||
When both are present, command parsing requires an exact match.
|
||||
|
||||
Commands with additional positionals keep their command-specific order:
|
||||
|
||||
- `run-stage <stage> <session_id>` or `run-stage <stage> --session-id <session_id>`
|
||||
- `session locks add <session_id> <source>` or `session locks add --session-id <session_id> <source>`
|
||||
- `session locks remove <session_id> <source>` or `session locks remove --session-id <session_id> <source>`
|
||||
|
||||
## 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`
|
||||
|
||||
@@ -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.<artifact_key>`
|
||||
- Previous-session source ID: `narratio.previous_session.artifact.<artifact_key>`
|
||||
|
||||
Configured and previous-session source IDs are validated by strict regex rules.
|
||||
- configured source ID format: `narratio.artifact.<artifact_key>`
|
||||
- previous-session source ID format: `narratio.previous_session.artifact.<artifact_key>`
|
||||
|
||||
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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user