85 lines
2.3 KiB
Markdown
85 lines
2.3 KiB
Markdown
# Internal: Command Restore
|
|
|
|
## Purpose
|
|
Define the implemented `narratio session restore` command contract:
|
|
|
|
- committed remote current-state discovery;
|
|
- deterministic restore planning;
|
|
- safe local install semantics;
|
|
- durable restore reporting.
|
|
|
|
## Discovery Contract
|
|
|
|
Restore resolves remote committed state from the session publish current pointers:
|
|
|
|
- `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:
|
|
|
|
- remote list scope is the resolved session prefix;
|
|
- 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`.
|
|
|
|
Explicit exclusions from current remote state mapping:
|
|
|
|
- `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` installs last;
|
|
- downloads use sibling temp files plus atomic rename;
|
|
- manifest replacement is validated before rename;
|
|
- 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.
|
|
|
|
## Reporting Contract
|
|
|
|
- `--dry-run`: prints summary only; no local writes.
|
|
- non-dry-run: writes `reports/restore-latest.json`.
|
|
- report includes plan counts, per-action status, and execution failures.
|
|
|
|
## Invariants
|
|
|
|
- restore uses committed remote current state as authority;
|
|
- `current/run_id.txt` is the remote publish commit marker;
|
|
- restore does not execute pipeline stages.
|