66 lines
2.0 KiB
Markdown
66 lines
2.0 KiB
Markdown
# Internal: Command Restore
|
|
|
|
## Purpose
|
|
Document the implemented `narratio session restore` command contract:
|
|
- committed remote current-state discovery;
|
|
- deterministic restore plan classification;
|
|
- 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`.
|
|
|
|
## Plan Contract
|
|
Planner actions:
|
|
- `download`
|
|
- `skip_same`
|
|
- `conflict`
|
|
|
|
Plan behavior:
|
|
- remote list scope is the resolved session prefix;
|
|
- mapping to local paths 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 restore files are planned separately through `previouscache.BuildPlan` when configured previous-session requirements exist.
|
|
|
|
## Execution Contract
|
|
- non-manifest downloads happen before manifest install;
|
|
- `manifest.json` is installed last;
|
|
- downloads use sibling temp files + atomic rename;
|
|
- manifest replacement is validated before rename;
|
|
- failed installs do not roll back previously written files.
|
|
|
|
Audio restore path:
|
|
- uses `audio.MaterializeS3Audio`;
|
|
- integrates spool and S3 audio cache paths;
|
|
- supports cache hit reuse without object redownload.
|
|
|
|
## Reporting Contract
|
|
- dry-run: summary only (no writes).
|
|
- non-dry-run: writes `reports/restore-latest.json`.
|
|
- report captures plan counts, 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.
|