Internal: Command Restore

Purpose

Explain the implemented restore discovery, planning, installation, and reporting flow in internal/app. User invocation belongs in CLI, and the operator recovery procedure and physical restore scope belong in Operations.

Restore is split into explicit phases so remote authority, local conflict policy, and filesystem mutation can be tested independently.

Discovery Contract

Discovery delegates current-state pointer and manifest loading to internal/artifacts, then validates the result against the resolved request:

campaign must match;
session ID must match.
run ID must match the pointer-selected committed run.

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:

a new-protocol restore uses only the selected commit's declared artifact set; each action carries that artifact's immutable key, checksum, size, and generation. Coherent legacy state remains on the isolated compatibility path;
remote-to-local mapping is traversal-safe;
actions are sorted by local relative path and then remote key;
force converts differing eligible regular files from conflicts to downloads; directories and other non-regular targets remain conflicts.

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;
each committed object is verified against its declared checksum, size, and generation before installation;
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 mode prints a summary and performs no local writes;
execution mode persists the canonical restore report described in Operations;
report includes plan counts, per-action status, and execution failures.

Invariants

restore uses committed remote current state as authority;
one restore or status inspection observes the single pointer-selected commit loaded at discovery; later pointer changes cannot add objects or substitute a different run into its plan;
a verified current/commit-pointer.json and its selected immutable commit establish new-protocol remote commitment; coherent legacy current/run_id.txt plus current/manifest.json remains read-only migration support;
restore does not execute pipeline stages.

Implementation And Tests

Discovery: internal/app/restore_discovery.go
Planning: internal/app/restore_plan.go, internal/previouscache
Execution: internal/app/restore_execute.go
Reporting and command coordination: internal/app/restore_report.go, internal/app/restore.go
Tests: internal/app/restore_discovery_test.go, internal/app/restore_plan_test.go, internal/app/restore_execution_test.go, internal/app/restore_workflow_test.go

3.4 KiB Raw Blame History