# 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.