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.

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 by local relative path and then remote key;
force converts differing local targets from conflicts to downloads.

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 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;
current/run_id.txt is the remote publish commit marker;
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

2.6 KiB Raw Blame History