narratio/docs/internal/command-restore.md

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.