Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions atomic-cli/src/commands/doctor.rs
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,20 @@ pub enum DoctorCommands {
/// Use `--dry-run` to diagnose without writing anything.
#[command(name = "reconcile-working-copy")]
ReconcileWorkingCopy(ReconcileWorkingCopy),

/// Migrate the repository to native span recording.
///
/// Durably requires the `span-range-graph` version 3 capability so new
/// records are span-based. This is a metadata-only transition: existing
/// changes stay graph-origin and remain fully readable (mixed operation
/// is supported), and legacy span-capability version 2 repositories are
/// raised in place. The migration is journaled as a repository-scoped
/// Repair operation with a verified receipt and is idempotent — an
/// already-migrated repository journals nothing. The capability is
/// one-way once span changes exist: run this command again to re-raise
/// the lease if it is ever removed.
#[command(name = "migrate-spans")]
MigrateSpans(MigrateSpans),
}

/// Read-only working-copy consistency check.
Expand All @@ -123,6 +137,14 @@ pub struct ReconcileWorkingCopy {
pub dry_run: bool,
}

/// Journaled migration of the repository to native span recording.
#[derive(Debug, Args, Default)]
pub struct MigrateSpans {
/// Report the current span-capability state without writing anything.
#[arg(long)]
pub dry_run: bool,
}

/// Atomically rebuild graph-derived native indexes.
#[derive(Debug, Args, Default)]
pub struct RepairNativeIndexes {}
Expand Down Expand Up @@ -248,6 +270,7 @@ impl Command for Doctor {
DoctorCommands::MaterializeCrdt(cmd) => cmd.run(),
DoctorCommands::Check(cmd) => cmd.run(),
DoctorCommands::ReconcileWorkingCopy(cmd) => cmd.run(),
DoctorCommands::MigrateSpans(cmd) => cmd.run(),
}
}
}
Expand Down Expand Up @@ -400,6 +423,92 @@ impl Command for ReconcileWorkingCopy {
}
}

impl Command for MigrateSpans {
fn run(&self) -> CliResult<()> {
use atomic_core::pristine::{CapabilityTxnT, SPAN_RANGE_CAPABILITY};
if self.dry_run {
let repo = require_repository_readonly(None)?;
let version = repo
.pristine()
.read_txn()
.map_err(|error| {
CliError::Repository(atomic_repository::RepositoryError::Database(
error.to_string(),
))
})?
.required_capability_version(SPAN_RANGE_CAPABILITY.id())
.map_err(|error| {
CliError::Repository(atomic_repository::RepositoryError::Database(
error.to_string(),
))
})?;
describe_span_capability_state(version);
return Ok(());
}
let repo = match require_repository_for_native_repair(None) {
Ok(repo) => repo,
Err(error) => {
print_warning(&format!(
"The span migration is unavailable because repository authority cannot be opened: {error}"
));
return Err(error);
}
};
print_info("Migrating the repository to native span recording...");
match repo.migrate_span_capability() {
Ok(outcome) => {
if outcome.already_migrated {
print_success(
"Repository already requires span-range-graph v3; nothing to do.",
);
} else {
let previous = match outcome.previous {
None => "not required".to_string(),
Some(version) => format!("v{version}"),
};
let journaled = outcome
.operation
.map(|operation| format!("; journaled as Repair operation {operation}"))
.unwrap_or_default();
print_success(&format!(
"Span recording enabled (span-range-graph {previous} \u{2192} v3){journaled}."
));
print_hint(
"Existing changes stay graph-origin and remain fully readable; new \
records are span-based. The capability is one-way once span changes \
exist; run this command again to re-raise the lease if it is ever \
removed.",
);
}
Ok(())
}
Err(error) => {
print_warning(&format!(
"The span migration refused before any capability row moved: {error}"
));
Err(CliError::Repository(error))
}
}
}
}

fn describe_span_capability_state(version: Option<u32>) {
use atomic_core::pristine::SPAN_RANGE_CAPABILITY;
match version {
Some(minimum) if minimum == SPAN_RANGE_CAPABILITY.minimum_version() => print_success(
"Repository requires span-range-graph v3: native span recording is already enabled.",
),
Some(version) => print_warning(&format!(
"Repository requires legacy span-range-graph v{version}; \
`atomic doctor migrate-spans` would raise the lease to v3."
)),
None => print_info(
"Repository has no span capability: recorded changes are graph-origin. \
`atomic doctor migrate-spans` would enable native span recording.",
),
}
}

fn print_diagnosis(diagnosis: &atomic_repository::WorkingCopyRegistrationDiagnosis) {
print_info(&format!(
"Working copy {}: location {}; desired view {} ({}) at {}; observed {}; \
Expand Down Expand Up @@ -594,4 +703,10 @@ mod tests {
assert!(cmd.view.is_none());
assert!(!cmd.force);
}

#[test]
fn migrate_spans_defaults_to_apply() {
let cmd = MigrateSpans::default();
assert!(!cmd.dry_run);
}
}
202 changes: 202 additions & 0 deletions atomic-repository/src/repository/repair.rs
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,28 @@ pub struct NativeIndexRepairOutcome {
pub operation: Option<OperationId>,
}

/// Outcome of a span-capability migration (`atomic doctor migrate-spans`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SpanCapabilityMigrationOutcome {
/// The `span-range-graph` version observed before the migration.
pub previous: Option<u32>,
/// The journaled repository-scoped `Repair` operation, `None` when the
/// repository already required the current version.
pub operation: Option<OperationId>,
/// Whether the repository already required the current version.
pub already_migrated: bool,
}

/// Domain-tagged digest input for the observed span-capability row.
fn span_capability_digest_bytes(version: Option<u32>) -> [u8; 5] {
let mut bytes = [0u8; 5];
bytes[0] = u8::from(version.is_some());
if let Some(version) = version {
bytes[1..].copy_from_slice(&version.to_le_bytes());
}
bytes
}

/// Derive the graph-authoritative path-claim set: the complete closure
/// union across every view, topologically ordered change replay, the
/// recovered inode owners for every structural claimant, and the derived
Expand Down Expand Up @@ -748,6 +770,186 @@ impl Repository {
})
}

/// Migrate the repository to native span recording by durably requiring
/// the `span-range-graph` version 3 capability.
///
/// This is a metadata-only transition: existing changes remain
/// graph-origin and stay fully readable, and records after the migration
/// are span-based (mixed operation is supported). Legacy span
/// repositories on version 2 are raised in place; version 1 rows use an
/// ambiguous pre-release metadata envelope this build refuses at open,
/// so such a repository can never reach this method.
///
/// The transition is journaled as a repository-scoped `Repair` operation
/// carrying the capability lease (absent or the observed version raised
/// to version 3) with a same-transaction verified receipt, so an
/// interrupted process leaves either nothing or a complete journal
/// entry. The migration is idempotent: an already-migrated repository is
/// a successful no-op that journals nothing.
pub fn migrate_span_capability(
&self,
) -> Result<SpanCapabilityMigrationOutcome, RepositoryError> {
use atomic_core::operation::{MetadataTarget, MetadataTransition, MetadataValue};
use atomic_core::pristine::{CapabilityMutTxnT, CapabilityTxnT, SPAN_RANGE_CAPABILITY};

let minimum = SPAN_RANGE_CAPABILITY.minimum_version();
let no_op = |previous: Option<u32>| SpanCapabilityMigrationOutcome {
previous,
operation: None,
already_migrated: true,
};

// Cheap read-only observation first: an already-migrated repository
// must not journal anything.
let observed = self
.pristine
.read_txn()
.map_err(pristine_error)?
.required_capability_version(SPAN_RANGE_CAPABILITY.id())
.map_err(pristine_error)?;
if observed == Some(minimum) {
return Ok(no_op(observed));
}
Self::refuse_unmigratable_span_row(observed)?;

let common = self.try_lock_common_operation()?;
let mut txn = common.begin_write_immediate()?;
let parent = self.ensure_repository_anchor_in_txn(
&mut txn,
&RepoStateRef {
view: None,
working_copy: None,
git: None,
},
)?;

// Re-observe inside the committing transaction: the lease below is
// written against the same snapshot that journals it.
let current = txn
.required_capability_version(SPAN_RANGE_CAPABILITY.id())
.map_err(pristine_error)?;
if current == Some(minimum) {
txn.abort()
.map_err(|error| RepositoryError::Database(error.to_string()))?;
return Ok(no_op(current));
}
Self::refuse_unmigratable_span_row(current)?;

let before_digest = Hash::of(&canonical_tagged_bytes(
b"repair:span-migration:before",
&span_capability_digest_bytes(current),
));
let durable = txn
.put_required_capability(SPAN_RANGE_CAPABILITY)
.map_err(pristine_error)?;
if durable != minimum {
return Err(RepositoryError::Database(format!(
"span capability lease raised to version {durable}, expected {minimum}"
)));
}
let after = txn
.required_capability_version(SPAN_RANGE_CAPABILITY.id())
.map_err(pristine_error)?;
if after != Some(minimum) {
return Err(RepositoryError::Database(format!(
"span capability lease observed {after:?} after the raise, expected {minimum}"
)));
}
let after_digest = Hash::of(&canonical_tagged_bytes(
b"repair:span-migration:after",
&span_capability_digest_bytes(after),
));

let operation = Operation::new(OperationPayload {
parents: vec![parent],
kind: OperationKind::Repair,
relation: None,
working_copy: None,
before: RepoStateRef {
view: None,
working_copy: None,
git: None,
},
delta: RepoStateDelta {
after: RepoStateRef {
view: None,
working_copy: None,
git: None,
},
metadata: vec![MetadataTransition {
target: MetadataTarget::Capability {
id: SPAN_RANGE_CAPABILITY.id().to_string(),
},
expected_old: current
.map(|version| MetadataValue::Sequence(u64::from(version)))
.unwrap_or(MetadataValue::Absent),
expected_new: MetadataValue::Sequence(u64::from(minimum)),
}],
effects: Vec::new(),
},
git_observed: Vec::new(),
evidence: vec![before_digest, after_digest],
actor: ActorRef::System {
name: "doctor-migrate-spans".to_string(),
},
timestamp_ms: super::operation::current_operation_timestamp_ms(),
lossy: Vec::new(),
})
.map_err(codec_error)?;
txn.put_operation(&operation).map_err(pristine_error)?;
txn.compare_and_set_operation_heads(
OperationScope::Repository,
&[parent],
&[operation.id()],
)
.map_err(pristine_error)?;
let verified = super::operation::deterministic_effect_receipt(
&operation,
None,
atomic_core::operation::EffectReceiptKind::Verified,
None,
None,
)?;
txn.append_effect_receipt(&verified)
.map_err(pristine_error)?;
txn.commit()
.map_err(|error| RepositoryError::Database(error.to_string()))?;
Ok(SpanCapabilityMigrationOutcome {
previous: current,
operation: Some(operation.id()),
already_migrated: false,
})
}

/// Refuse span-capability rows this migration cannot raise. Only the
/// current version and the legacy version 2 (raise in place) are
/// migratable; version 1 uses the ambiguous pre-release envelope.
fn refuse_unmigratable_span_row(observed: Option<u32>) -> Result<(), RepositoryError> {
use atomic_core::pristine::SPAN_RANGE_CAPABILITY;
/// The last pre-release span capability version this build can raise.
const LEGACY_MIGRATABLE_VERSION: u32 = 2;
match observed {
None => Ok(()),
Some(1) => Err(RepositoryError::InvalidOperation {
message: "span-range-graph version 1 uses the ambiguous pre-release metadata \
envelope this build refuses at open; it needs manual recovery, not \
this migration"
.into(),
}),
Some(version)
if version == SPAN_RANGE_CAPABILITY.minimum_version()
|| version == LEGACY_MIGRATABLE_VERSION =>
{
Ok(())
}
Some(version) => Err(RepositoryError::InvalidOperation {
message: format!(
"span-range-graph version {version} is not a migratable span capability row"
),
}),
}
}

/// Undo a previously-journaled path-claims repair (CB-13A follow-up
/// R3): restore the complete old table captured in the repair's plan
/// evidence under fresh leases. The CURRENT live table must be
Expand Down
Loading
Loading