Skip to content

feat: add atomic doctor migrate-spans for existing repositories - #335

Open
geekgonecrazy wants to merge 1 commit into
devfrom
feat/doctor-migrate-spans
Open

geekgonecrazy wants to merge 1 commit into
devfrom
feat/doctor-migrate-spans

Conversation

@geekgonecrazy

@geekgonecrazy geekgonecrazy commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds atomic doctor migrate-spans — a command available in every standard build (not gated behind the experimental-span-import cargo feature, which only affects atomic git import --span) that migrates an existing repository to native span recording by durably requiring the span-range-graph v3 capability lease. Until now the only front doors to spans were git import --span (behind experimental-span-import) and silent adoption when pulling span changes from someone else; there was no supported way to deliberately enable spans on a normal repo.

What migration means

This is a metadata-only transition — no change bytes, graph rows, or views are touched:

  • Graph-only repo (no span capability) → raises the lease to span-range-graph v3. Existing changes stay graph-origin and remain fully readable; new records are span-based. Mixed operation is already proven by the existing mixed-fixture span tests (record_mixed_fixture etc.).
  • Legacy v2 span repo → raised in place. Previously these repositories were wedged: record refused with "span capability version 2 requires migration before recording" and importing new span changes refused with a matching error — but nothing performed the migration.
  • Already v3 → idempotent no-op that journals nothing.
  • v1 → refused with guidance. The v1 row uses the ambiguous pre-release metadata envelope (no released version ever wrote one — v0.21.0 predates spans, v0.22.0 shipped v3), and this build refuses to open such repositories at all, so the command can never reach them.

Safety

  • Journals a repository-scoped Repair operation (same recipe as repair_tree_bijection): the MetadataTarget::Capability lease (Absent/Some(2) → Some(3)), before/after evidence digests, CAS'd repository heads, and a same-transaction verified receipt — an interrupted process leaves either nothing or a complete journal entry.
  • The lease is re-observed inside the committing transaction (third-value check), and put_required_capability is raise-only, so a concurrent raise can never be lowered.
  • The capability is one-way once span changes exist; the command output says so and points at re-running the command as the recovery path.

CLI

atomic doctor migrate-spans [--dry-run]

--dry-run reports the current span-capability state (not required / legacy vN / v3) without writing anything.

Testing

  • New integration tests (atomic-repository/tests/span_capability_migration.rs):
    • graph-only repo: migrate → capability None → 3, journaled Repair op with lease + verified receipt + repository head; graph content still reads; post-migration record is span-indexed; second migrate is an idempotent no-op
    • legacy v2 repo: record refuses before migration, works after the raise
  • cargo test -p atomic-repository --lib: 1577 passed
  • cargo test -p atomic-cli --bin atomic: 2168 passed
  • Clippy (-p atomic-repository -p atomic-cli --all-targets): no new warnings; cargo fmt clean

Add `atomic doctor migrate-spans`, an un-flagged command that migrates an
existing repository to native span recording by durably requiring the
span-range-graph v3 capability lease.

The transition is metadata-only: existing changes stay graph-origin and
remain fully readable, records after the migration are span-based, and
mixed operation is supported (proven by the existing mixed-fixture span
tests). Legacy span repositories on capability version 2 are raised in
place; the ambiguous pre-release version 1 envelope is refused (this
build refuses to open such repositories anyway).

The migration journals a repository-scoped Repair operation carrying the
capability lease (absent or observed version raised to v3) with a
same-transaction verified receipt, so an interrupted process leaves
either nothing or a complete journal entry. An already-migrated
repository is an idempotent no-op that journals nothing.

`--dry-run` reports the current span-capability state without writing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant