Verification spike: issue #29 durable atomic skill-tree swap

[jon-devlapaz]

Verdict on #29 today

Mostly done for the safety invariant; still needed for consolidation and durable naming.

Post-#68 / closed-#26, the original silent TempDir drop on refresh replace is fixed. Tree replace paths (publish_staged_tree and its six callers) implement stage → live→backup → publish → restore-or-keep. Manifest pair writes and binary update follow the same “orphans are explicit” rule via independent keep() paths.

What remains open for #29:

• No shared helper — three parallel implementations (publish_staged_tree, manifest::write_atomic, update::replace_binary)
• No durable orphan names — recovery artifacts keep temp prefixes (.tink-update-*, .skills-manifest-backup-*, .tink-backup-*)
• library::deposit_at divergent repair — clear_path then install_local with no backup (residual data-loss class gap)

Full analysis: docs/issue-29-verification-spike.md

---

Call-site matrix

Site	Stage	Live→backup	Publish	Restore-or-keep	Overall
publish_staged_tree + 6 callers (refresh, rollback, manage_tink, library::promote, skillsets ×2)	✓	✓ (under temp)	✓	✓ keep()	Partial
install_local (Ready)	✓	N/A	✓	N/A	Partial (first install)
library::deposit_at (Divergent)	✗	✗	partial	✗	Missing
manifest::write_atomic	✓	✓ (temp file)	✓	✓ keep()	Partial
update::replace_binary	✓	✓ (temp file)	✓	✓ keep()	Partial (file shape)

Detailed inventory with file:line references is in the spike doc.

---

Residual risks

1. Recovery dirs/files are temp-named beside the destination — operator-visible but not .tink-orphan-* stable names
2. deposit_at divergent path deletes the library tree before reinstall with no recovery backup
3. Three independent swap implementations — drift risk
4. Concurrent target recreation during rollback window (documented; no lock)
5. Cross-filesystem rename (explicitly out of v1)

---

Recommended next implement slice (one PR)

publish_staged_tree only (~1 module):

1. Extract a private tree-swap helper implementing live→backup → publish → restore-or-keep
2. On rollback failure, rename backup to <dest-root>/.tink-orphan-<name>-<suffix> and name it in the error
3. One characterization test for orphan dir naming on double failure

Defer manifest/binary unification and deposit_at divergent repair to follow-up issues.

---

Changes in this PR

• Add docs/issue-29-verification-spike.md — full inventory, refreshed Refactor: durable atomic skill-tree swap (shared helper) #29 checklist (skill refresh can drop skill tree if post-swap restore fails #26 item marked done), gap matrix, test evidence
• Add manifest::tests::write_atomic_restores_manifest_when_lock_publish_fails
• Add update::tests::replace_binary_retains_recovery_backup_when_rollback_fails
• Note new coverage in docs/TESTING.md

Tests run

cargo test rollback_failure_retains_recovery_backup publish_staged_tree_restores_target_when_publish_fails write_atomic_restores_manifest_when_lock_publish_fails replace_binary_retains_recovery_backup_when_rollback_fails replace_binary_rolls_back_when_published_probe_fails
cargo test --workspace --all-targets --locked
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings

All passed on Linux x86_64.

Relates to #29