eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Align internal documentation and maintained examples

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-09 21:50:21 +00:00
parent bd2d5e2496
commit e7319ea016
26 changed files with 416 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/internal/command-restore.md
View File

@@ -1,21 +1,20 @@
# Internal: Command Restore
## Purpose
Define the implemented `narratio session restore` command contract:
- committed remote current-state discovery;
- deterministic restore planning;
- safe local install semantics;
- durable restore reporting.
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
Restore resolves remote committed state from the session publish current pointers:
- `current/run_id.txt` (required, non-empty);
- `current/manifest.json` (required, decodable).
Current-state discovery uses shared artifacts-level mechanics and validates identity against the resolved request config:
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.
@@ -34,26 +33,11 @@ Planner behavior:
- remote list scope is the resolved session prefix;
- remote-to-local mapping is traversal-safe;
- actions are sorted deterministically by local relative path.
- actions are sorted by local relative path and then remote key;
- force converts differing local targets from conflicts to downloads.
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 files are planned separately through `previouscache.BuildPlan` when configured previous-session requirements exist.
Previous-cache files are planned separately through `previouscache.BuildPlan`
when configured previous-session requirements exist.
## Execution Contract
@@ -73,8 +57,9 @@ Audio restore path:
## Reporting Contract
- `--dry-run`: prints summary only; no local writes.
- non-dry-run: writes `reports/restore-latest.json`.
- 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
@@ -82,3 +67,15 @@ Audio restore path:
- 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`