diff --git a/atomic-cli/src/commands/doctor.rs b/atomic-cli/src/commands/doctor.rs index 853b1d4a..9f68ccaf 100644 --- a/atomic-cli/src/commands/doctor.rs +++ b/atomic-cli/src/commands/doctor.rs @@ -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. @@ -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 {} @@ -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(), } } } @@ -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) { + 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 {}; \ @@ -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); + } } diff --git a/atomic-repository/src/repository/repair.rs b/atomic-repository/src/repository/repair.rs index 448e268e..1827c993 100644 --- a/atomic-repository/src/repository/repair.rs +++ b/atomic-repository/src/repository/repair.rs @@ -123,6 +123,28 @@ pub struct NativeIndexRepairOutcome { pub operation: Option, } +/// 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, + /// The journaled repository-scoped `Repair` operation, `None` when the + /// repository already required the current version. + pub operation: Option, + /// 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) -> [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 @@ -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 { + 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| 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) -> 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 diff --git a/atomic-repository/tests/span_capability_migration.rs b/atomic-repository/tests/span_capability_migration.rs new file mode 100644 index 00000000..d9476797 --- /dev/null +++ b/atomic-repository/tests/span_capability_migration.rs @@ -0,0 +1,156 @@ +//! `doctor migrate-spans`: raising an existing repository to native spans. + +use atomic_core::change::ChangeHeader; +use atomic_core::operation::{EffectReceiptKind, OperationKind, OperationScope}; +use atomic_core::pristine::{ + CapabilityMutTxnT, CapabilityTxnT, GraphTxnT, MutTxnT, OperationTxnT, SPAN_RANGE_CAPABILITY, +}; +use atomic_repository::{RecordOptions, Repository, StatusOptions}; + +fn record_options() -> RecordOptions { + RecordOptions::new() + .with_all(true) + .save_to_store(true) + .apply_after_record(true) +} + +fn span_capability_version(repo: &Repository) -> Option { + repo.pristine() + .read_txn() + .unwrap() + .required_capability_version(SPAN_RANGE_CAPABILITY.id()) + .unwrap() +} + +#[test] +fn migrate_enables_span_recording_on_a_graph_only_repository() { + use atomic_core::pristine::span_patch_storage::SpanPatchReadTxn; + + let temp = tempfile::tempdir().unwrap(); + let repo = Repository::init(temp.path()).unwrap(); + let working_copy = repo.require_working_copy_id().unwrap(); + let path = temp.path().join("file.txt"); + + // Graph-origin history recorded before the migration. + std::fs::write(&path, b"one\ntwo\n").unwrap(); + repo.add(working_copy, "file.txt", Default::default()) + .unwrap(); + repo.record( + working_copy, + ChangeHeader::new("graph origin"), + record_options(), + ) + .unwrap(); + assert_eq!(span_capability_version(&repo), None); + + let outcome = repo.migrate_span_capability().unwrap(); + assert_eq!(outcome.previous, None); + assert!(!outcome.already_migrated); + let operation_id = outcome.operation.expect("migration journals an operation"); + assert_eq!(span_capability_version(&repo), Some(3)); + + // The journal carries the capability lease, a verified receipt, and the + // repository head. + { + let txn = repo.pristine().read_txn().unwrap(); + let operation = txn.get_operation(operation_id).unwrap().unwrap(); + assert_eq!(operation.payload().kind, OperationKind::Repair); + assert!(operation.payload().working_copy.is_none()); + assert_eq!(operation.payload().delta.metadata.len(), 1); + assert!(operation + .payload() + .delta + .metadata + .iter() + .any(|transition| transition.expected_new + == atomic_core::operation::MetadataValue::Sequence(3))); + let receipts = txn.get_effect_receipts(operation_id).unwrap(); + assert!(receipts + .iter() + .any(|receipt| receipt.payload().kind == EffectReceiptKind::Verified)); + assert!(txn + .get_operation_heads(OperationScope::Repository) + .unwrap() + .as_slice() + .contains(&operation_id)); + } + + // Graph-origin content stays readable and the working copy is clean. + assert!(repo + .status(working_copy, StatusOptions::default()) + .unwrap() + .is_clean()); + + // New records after the migration take the span path. + std::fs::write(&path, b"ONE\ntwo\n").unwrap(); + let edit = repo + .record( + working_copy, + ChangeHeader::new("span edit"), + record_options(), + ) + .unwrap(); + { + let txn = repo.pristine().read_txn().unwrap(); + let id = txn.get_internal(edit.hash()).unwrap().unwrap(); + assert!(txn.span_change_indexed(id).unwrap()); + } + assert!(repo + .status(working_copy, StatusOptions::default()) + .unwrap() + .is_clean()); + assert_eq!(std::fs::read(&path).unwrap(), b"ONE\ntwo\n"); + + // Idempotent: a migrated repository journals nothing. + let again = repo.migrate_span_capability().unwrap(); + assert!(again.already_migrated); + assert_eq!(again.operation, None); + assert_eq!(span_capability_version(&repo), Some(3)); +} + +#[test] +fn migrate_raises_a_legacy_span_capability_version_two_repository() { + let temp = tempfile::tempdir().unwrap(); + let repo = Repository::init(temp.path()).unwrap(); + let working_copy = repo.require_working_copy_id().unwrap(); + { + let mut txn = repo.pristine().write_txn().unwrap(); + txn.put_required_capability_exact(SPAN_RANGE_CAPABILITY.id(), 2) + .unwrap(); + txn.commit().unwrap(); + } + let path = temp.path().join("file.txt"); + std::fs::write(&path, b"one\n").unwrap(); + repo.add(working_copy, "file.txt", Default::default()) + .unwrap(); + + // Version 2 refuses recording until it is migrated. + let error = repo + .record( + working_copy, + ChangeHeader::new("refused on v2"), + record_options(), + ) + .unwrap_err(); + assert!( + error.to_string().contains("migration"), + "unexpected refusal: {error}" + ); + + let outcome = repo.migrate_span_capability().unwrap(); + assert_eq!(outcome.previous, Some(2)); + assert!(!outcome.already_migrated); + assert_eq!(span_capability_version(&repo), Some(3)); + + // Recording works after the raise. + repo.record( + working_copy, + ChangeHeader::new("record on v3"), + record_options(), + ) + .unwrap(); + assert!(repo + .status(working_copy, StatusOptions::default()) + .unwrap() + .is_clean()); +}