Add one-shot v18-to-v19 retained substrate migration

[flyingrobots]

Problem

Existing v18 consumers can have blob-backed retained state that the v19 tree-backed storage boundary correctly rejects with HANDLE_TARGET_TYPE_MISMATCH. API migration alone is insufficient: linking v19 before migrating the retained substrate can allow a concurrent v19 append to strand an authoritative v18 writer.

This is a v19 release blocker, but it must not add legacy compatibility code to the production runtime.

Required work

• Implement the one-shot migrator under scripts/v18-to-v19/.
• Move any legacy v18 decoding or compatibility logic needed by the operation into that script directory.
• Keep the normal v19 runtime tree-backed and free of legacy read branches.
• Detect an unmigrated v18 substrate before any v19 writer append and return an actionable typed obstruction that names the migration command.
• Rehearse against a disposable repository copy before touching an authoritative ref.
• Translate the retained v18 representation through published git-cas APIs.
• Preserve semantic identity, ordering, timestamps, and application-owned metadata.
• Make the operation idempotent, resumable, and compare-and-swap guarded.
• Keep the original chain reachable under an additive recovery ref until verification succeeds.
• Verify v19 reopen, read, append, remember-equivalent scan, and repository health after migration.

Acceptance criteria

• All legacy decoding used for migration lives under scripts/v18-to-v19/; no legacy compatibility reader is added to production source.
• An untouched v18 fixture fails closed before mutation with an actionable run-the-migrator obstruction.
• Dry-run and rehearsal modes produce a complete plan without moving the authoritative ref.
• Migration produces tree-backed v19 handles without deleting or rewriting the source chain.
• Interrupted migration resumes safely and repeated execution is idempotent.
• Concurrent writer movement is detected and leaves the authoritative ref unchanged.
• Migrated state passes semantic equivalence, reopen, read, append, and recovery checks on v19.
• Documentation makes the one-time migration step mandatory before enabling v19 for a retained v18 store.

Do not release v19 until this script and its fixture-based proof are complete.

[coderabbitai]

🔗 Related PRs

#106 - Advance v18 release-candidate evidence [merged]
#108 - Plan post-v18 release handoff and next goalpost [merged]
#726 - Move graph exports behind v19 public API boundary [merged]
#751 - feat(materialize): add retained CAS materialization handles [merged]
#764 - Adopt persistent Git object sessions and close them safely [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[flyingrobots]

Release decision: this is a v19 blocker. Do not release v19 until legacy v18 retained stores are detected before mutation and the migration path passes fixture-based semantic equivalence, reopen, append, interruption, and compare-and-swap recovery tests. The earlier outside-v19 classification is superseded.