82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
# Internal: Command Restore
|
|
|
|
## Purpose
|
|
|
|
Explain the implemented restore discovery, planning, installation, and
|
|
reporting flow in `internal/app`. User invocation belongs in
|
|
[CLI](../cli.md#session-restore), and the operator recovery procedure and
|
|
physical restore scope belong in
|
|
[Operations](../operations.md#restore-workflow).
|
|
|
|
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](../operations.md#restore-workflow);
|
|
- 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`
|