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