narratio/docs/internal/command-restore.md

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.