snowflake-code-unit-registry 0.5.2__tar.gz → 0.5.4__tar.gz

{snowflake_code_unit_registry-0.5.2 → snowflake_code_unit_registry-0.5.4}/Cargo.lock

@@ -834,9 +834,9 @@ dependencies = [
 
 [[package]]
 name = "hyper"
-version = "1.8.1"
+version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ab2d4f250c3d7b1c9fcdff1cece94ea4e2dfbec68614f7b87cb205f24ca9d11"
+checksum = "6299f016b246a94207e63da54dbe807655bf9e00044f73ded42c3ac5305fbcca"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -848,7 +848,6 @@ dependencies = [
  "httparse",
  "itoa",
  "pin-project-lite",
- "pin-utils",
  "smallvec",
  "tokio",
  "want",
@@ -1204,9 +1203,9 @@ dependencies = [
 
 [[package]]
 name = "js-sys"
-version = "0.3.92"
+version = "0.3.94"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc4c90f45aa2e6eacbe8645f77fdea542ac97a494bcd117a67df9ff4d611f995"
+checksum = "2e04e2ef80ce82e13552136fabeef8a5ed1f985a96805761cbb9a2c34e7664d9"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -1257,9 +1256,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.183"
+version = "0.2.184"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
+checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
 
 [[package]]
 name = "libloading"
@@ -1617,12 +1616,6 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
-[[package]]
-name = "pin-utils"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
-
 [[package]]
 name = "portable-atomic"
 version = "1.13.1"
@@ -2101,7 +2094,7 @@ dependencies = [
 
 [[package]]
 name = "scai-error-derive"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "err_code",
  "heck",
@@ -2115,7 +2108,7 @@ dependencies = [
 
 [[package]]
 name = "scai-state-core"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "chrono",
  "err_code",
@@ -2140,7 +2133,7 @@ dependencies = [
 
 [[package]]
 name = "scai-state-csharp"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "interoptopus",
  "interoptopus_backend_csharp",
@@ -2151,7 +2144,7 @@ dependencies = [
 
 [[package]]
 name = "scai-state-node"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "napi",
  "napi-build",
@@ -2163,7 +2156,7 @@ dependencies = [
 
 [[package]]
 name = "scai-state-python"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "pyo3",
  "pythonize",
@@ -2874,9 +2867,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6523d69017b7633e396a89c5efab138161ed5aafcbc8d3e5c5a42ae38f50495a"
+checksum = "0551fc1bb415591e3372d0bc4780db7e587d84e2a7e79da121051c5c4b89d0b0"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -2887,9 +2880,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.65"
+version = "0.4.67"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d1faf851e778dfa54db7cd438b70758eba9755cb47403f3496edd7c8fc212f0"
+checksum = "03623de6905b7206edd0a75f69f747f134b7f0a2323392d664448bf2d3c5d87e"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -2897,9 +2890,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e3a6c758eb2f701ed3d052ff5737f5bfe6614326ea7f3bbac7156192dc32e67"
+checksum = "7fbdf9a35adf44786aecd5ff89b4563a90325f9da0923236f6104e603c7e86be"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -2907,9 +2900,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "921de2737904886b52bcbb237301552d05969a6f9c40d261eb0533c8b055fedf"
+checksum = "dca9693ef2bab6d4e6707234500350d8dad079eb508dca05530c85dc3a529ff2"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -2920,9 +2913,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a93e946af942b58934c604527337bad9ae33ba1d5c6900bbb41c2c07c2364a93"
+checksum = "39129a682a6d2d841b6c429d0c51e5cb0ed1a03829d8b3d1e69a011e62cb3d3b"
 dependencies = [
  "unicode-ident",
 ]
@@ -2963,9 +2956,9 @@ dependencies = [
 
 [[package]]
 name = "web-sys"
-version = "0.3.92"
+version = "0.3.94"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "84cde8507f4d7cfcb1185b8cb5890c494ffea65edbe1ba82cfd63661c805ed94"
+checksum = "cd70027e39b12f0849461e08ffc50b9cd7688d942c1c8e3c7b22273236b4dd0a"
 dependencies = [
  "js-sys",
  "wasm-bindgen",

{snowflake_code_unit_registry-0.5.2 → snowflake_code_unit_registry-0.5.4}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/scai-error-derive", "crates/scai-state-core", "crates/scai-state-python"]
 
 [workspace.package]
-version = "0.5.2"
+version = "0.5.4"
 edition = "2021"
 license = "SEE LICENSE IN LICENSE"
 repository = "https://github.com/snowflake-eng/scai-state"

{snowflake_code_unit_registry-0.5.2 → snowflake_code_unit_registry-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-code-unit-registry
-Version: 0.5.2
+Version: 0.5.4
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License

snowflake_code_unit_registry-0.5.4/crates/scai-state-core/schemas/history/README.md

@@ -0,0 +1,14 @@
+# Schema History
+
+Frozen snapshots of previous schema versions. Each snapshot captures the
+schema as it was *before* bumping to the next version, providing a reference
+for migration correctness and regression testing.
+
+This directory is currently empty — it will contain its first snapshot when
+`CURRENT_SCHEMA_VERSION` is bumped from 1 to 2.
+
+**Rules:**
+
+- Files are IMMUTABLE — never modify a frozen schema after it has been committed.
+- Naming: `code-unit.v{N}.schema.json` (snapshot of the schema that was current for version N).
+- See `schema-workflow.mdc` step 1 for when to create a snapshot.

{snowflake_code_unit_registry-0.5.2 → snowflake_code_unit_registry-0.5.4}/crates/scai-state-core/src/error.rs

@@ -168,6 +168,26 @@ pub enum Error {
         #[snafu(implicit)]
         location: snafu::Location,
     },
+
+    #[snafu(display(
+        "Schema version {document_version} is newer than supported version {supported_version}. \
+         Upgrade the library to read this document."
+    ))]
+    #[error_code(1020)]
+    SchemaVersionNewerThanSupported {
+        document_version: i64,
+        supported_version: i64,
+        #[snafu(implicit)]
+        location: snafu::Location,
+    },
+
+    #[snafu(display("Schema migration failed: {message}"))]
+    #[error_code(1021)]
+    SchemaMigrationError {
+        message: String,
+        #[snafu(implicit)]
+        location: snafu::Location,
+    },
 }
 
 impl ErrorTrace for Error {
@@ -234,7 +254,7 @@ pub struct TraceEntry {
 
 /// Bump this when adding or removing a variant.
 #[cfg(test)]
-const EXPECTED_VARIANT_COUNT: usize = 18;
+const EXPECTED_VARIANT_COUNT: usize = 20;
 
 /// Result type alias for SCAI state operations
 pub type Result<T> = std::result::Result<T, Error>;
@@ -302,6 +322,8 @@ mod tests {
     #[test_case(WriteSucceededRefreshFailedSnafu.into_error(Box::new(ValidationSnafu { message: "msg" }.build())) => 1015 ; "WriteSucceededRefreshFailed")]
     #[test_case(ScopedRefreshRequiresFullRefreshSnafu { message: "run" }.build() => 1016 ; "ScopedRefreshRequiresFullRefresh")]
     #[test_case(ScopedRefreshUnresolvedDependencySnafu { id: "id" }.build()      => 1017 ; "ScopedRefreshUnresolvedDependency")]
+    #[test_case(SchemaVersionNewerThanSupportedSnafu { document_version: 3i64, supported_version: 2i64 }.build() => 1020 ; "SchemaVersionNewerThanSupported")]
+    #[test_case(SchemaMigrationSnafu { message: "failed" }.build()              => 1021 ; "SchemaMigrationError")]
     fn error_code_is_stable(err: Error) -> i32 {
         err.error_code_i32()
     }

{snowflake_code_unit_registry-0.5.2 → snowflake_code_unit_registry-0.5.4}/crates/scai-state-core/src/lib.rs

@@ -9,6 +9,7 @@ pub mod error_trace;
 pub mod filter;
 pub mod generated;
 pub mod identity;
+pub mod migration;
 pub mod registry;
 pub mod validation;
 
@@ -43,5 +44,8 @@ pub use validation::ValidationIssue;
 pub use validation::ValidationIssueKind;
 pub use validation::ValidationReport;
 
+// Re-export migration constants
+pub use migration::CURRENT_SCHEMA_VERSION;
+
 // Re-export identity helpers
 pub use identity::generate_id;

snowflake_code_unit_registry-0.5.4/crates/scai-state-core/src/migration/mod.rs

@@ -0,0 +1,390 @@
+//! Schema version detection and document migration.
+//!
+//! Each code unit JSON file carries a `schemaVersion` integer. This module
+//! provides the migration pipeline that upgrades old documents to the current
+//! schema version using `serde_json::Value`-level transforms.
+//!
+//! ## Adding a new migration
+//!
+//! 1. Freeze `schemas/code-unit.schema.json` to `schemas/history/code-unit.vN.schema.json` (**before** editing the schema)
+//! 2. Edit the schema — make structural changes and set `schemaVersion.const` to N+1
+//! 3. Create `src/migration/versions/v{N}_to_v{N+1}.rs` with a `pub fn migrate(&mut Value) -> Result<()>`
+//! 4. Register the module and function in `src/migration/versions/mod.rs`
+//! 5. Update [`CURRENT_SCHEMA_VERSION`] to N+1
+//! 6. Add migration tests with sample documents and both schema files
+
+mod versions;
+
+use serde_json::Value;
+
+use crate::error::*;
+use versions::{MigrationFn, MIGRATIONS};
+
+/// JSON field name for the schema version indicator on every code unit document.
+pub const SCHEMA_VERSION_FIELD: &str = "schemaVersion";
+
+/// Current schema version supported by this library.
+///
+/// Must match the `schemaVersion.const` value in `schemas/code-unit.schema.json`.
+/// Guarded by `test_version_constant_matches_schema` — CI will fail if this
+/// drifts from the schema file.
+pub const CURRENT_SCHEMA_VERSION: i64 = 1;
+
+/// Extract the schema version from a raw JSON document.
+///
+/// - Returns `Ok(version)` when `schemaVersion` is a valid integer >= 1.
+/// - Returns `Ok(1)` when `schemaVersion` is absent (missing = v1).
+/// - Returns `Err(SchemaMigrationError)` when `schemaVersion` is present but not
+///   a positive integer.
+pub fn extract_version(doc: &Value) -> Result<i64> {
+    match doc.get(SCHEMA_VERSION_FIELD) {
+        None => Ok(1),
+        Some(v) => {
+            let version = v.as_i64().ok_or_else(|| {
+                SchemaMigrationSnafu {
+                    message: format!(
+                        "schemaVersion must be a positive integer, got: {}",
+                        truncated_display(v),
+                    ),
+                }
+                .build()
+            })?;
+            if version < 1 {
+                return SchemaMigrationSnafu {
+                    message: format!("schemaVersion must be >= 1, got: {version}",),
+                }
+                .fail();
+            }
+            Ok(version)
+        }
+    }
+}
+
+/// Migrate a document from its current version to [`CURRENT_SCHEMA_VERSION`].
+///
+/// - If the document is already at the current version, returns it unchanged.
+/// - If the document version is newer than supported, returns
+///   [`SchemaVersionNewerThanSupported`](Error::SchemaVersionNewerThanSupported).
+/// - If a migration step fails, returns [`SchemaMigrationError`](Error::SchemaMigrationError).
+/// - If the migration chain is incomplete (no path from old to current),
+///   returns [`SchemaMigrationError`](Error::SchemaMigrationError).
+pub fn migrate(doc: Value) -> Result<Value> {
+    migrate_with(doc, CURRENT_SCHEMA_VERSION, MIGRATIONS)
+}
+
+fn migrate_with(
+    mut doc: Value,
+    target_version: i64,
+    migrations: &[(i64, MigrationFn)],
+) -> Result<Value> {
+    let version = extract_version(&doc)?;
+
+    if version > target_version {
+        return SchemaVersionNewerThanSupportedSnafu {
+            document_version: version,
+            supported_version: target_version,
+        }
+        .fail();
+    }
+
+    if version == target_version {
+        return Ok(doc);
+    }
+
+    for &(from_ver, migrate_fn) in migrations {
+        if extract_version(&doc)? == from_ver {
+            migrate_fn(&mut doc).map_err(|e| {
+                SchemaMigrationSnafu {
+                    message: format!("v{} to v{}: {e}", from_ver, from_ver + 1),
+                }
+                .build()
+            })?;
+            set_version(&mut doc, from_ver + 1)?;
+        }
+    }
+
+    let final_version = extract_version(&doc)?;
+    if final_version != target_version {
+        return SchemaMigrationSnafu {
+            message: format!(
+                "Migration chain incomplete: document at v{version}, reached v{final_version}, \
+                 expected v{target_version}. Add missing migration functions.",
+            ),
+        }
+        .fail();
+    }
+
+    Ok(doc)
+}
+
+fn set_version(doc: &mut Value, version: i64) -> Result<()> {
+    let obj = doc.as_object_mut().ok_or_else(|| {
+        SchemaMigrationSnafu {
+            message: "document root must be a JSON object".to_string(),
+        }
+        .build()
+    })?;
+    obj.insert(SCHEMA_VERSION_FIELD.to_string(), Value::from(version));
+    Ok(())
+}
+
+fn truncated_display(v: &Value) -> String {
+    let s = v.to_string();
+    if s.len() > 50 {
+        format!("{}...", &s[..50])
+    } else {
+        s
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_version_constant_matches_schema() {
+        let schema_str = include_str!("../../schemas/code-unit.schema.json");
+        let schema: Value = serde_json::from_str(schema_str).unwrap();
+        let schema_version = schema["properties"][SCHEMA_VERSION_FIELD]["const"]
+            .as_i64()
+            .expect("schemaVersion.const must be an integer in the schema");
+        assert_eq!(
+            CURRENT_SCHEMA_VERSION, schema_version,
+            "CURRENT_SCHEMA_VERSION ({CURRENT_SCHEMA_VERSION}) does not match \
+             schema's schemaVersion.const ({schema_version}). Update the constant.",
+        );
+    }
+
+    #[test]
+    fn test_extract_version_present() {
+        let doc: Value = serde_json::json!({(SCHEMA_VERSION_FIELD): 2});
+        assert_eq!(extract_version(&doc).unwrap(), 2);
+    }
+
+    #[test]
+    fn test_extract_version_missing_defaults_to_1() {
+        let doc: Value = serde_json::json!({"id": "test"});
+        assert_eq!(extract_version(&doc).unwrap(), 1);
+    }
+
+    #[test]
+    fn test_extract_version_non_integer_rejects_with_error() {
+        let doc: Value = serde_json::json!({(SCHEMA_VERSION_FIELD): "not_a_number"});
+        let err = extract_version(&doc).unwrap_err();
+        assert_eq!(err.error_code_i32(), 1021);
+        assert!(err.to_string().contains("must be a positive integer"));
+    }
+
+    #[test]
+    fn test_extract_version_float_rejects_with_error() {
+        let doc: Value = serde_json::json!({(SCHEMA_VERSION_FIELD): 1.5});
+        let err = extract_version(&doc).unwrap_err();
+        assert_eq!(err.error_code_i32(), 1021);
+    }
+
+    #[test]
+    fn test_extract_version_non_positive_rejects_with_error() {
+        for &v in &[0, -5] {
+            let doc: Value = serde_json::json!({(SCHEMA_VERSION_FIELD): v});
+            let err = extract_version(&doc).unwrap_err();
+            assert_eq!(err.error_code_i32(), 1021, "schemaVersion={v}");
+            assert!(
+                err.to_string().contains("must be >= 1"),
+                "schemaVersion={v}"
+            );
+        }
+    }
+
+    #[test]
+    fn test_migrate_current_version_is_noop() {
+        let doc: Value =
+            serde_json::json!({(SCHEMA_VERSION_FIELD): CURRENT_SCHEMA_VERSION, "id": "test"});
+        let result = migrate(doc.clone()).unwrap();
+        assert_eq!(result, doc);
+    }
+
+    #[test]
+    fn test_migrate_future_version_rejected() {
+        let doc: Value = serde_json::json!({(SCHEMA_VERSION_FIELD): CURRENT_SCHEMA_VERSION + 1});
+        let err = migrate(doc).unwrap_err();
+        assert_eq!(err.error_code_i32(), 1020);
+        let msg = err.to_string();
+        assert!(
+            msg.contains("newer"),
+            "error message should mention 'newer': {msg}"
+        );
+    }
+
+    #[test]
+    fn test_migrate_non_integer_version_rejected() {
+        let doc: Value = serde_json::json!({(SCHEMA_VERSION_FIELD): "bad"});
+        let err = migrate(doc).unwrap_err();
+        assert_eq!(err.error_code_i32(), 1021);
+    }
+
+    #[test]
+    fn test_migrate_non_positive_version_rejected() {
+        for &v in &[0, -3] {
+            let doc: Value = serde_json::json!({(SCHEMA_VERSION_FIELD): v});
+            let err = migrate(doc).unwrap_err();
+            assert_eq!(err.error_code_i32(), 1021, "schemaVersion={v}");
+            assert!(
+                err.to_string().contains("must be >= 1"),
+                "schemaVersion={v}"
+            );
+        }
+    }
+
+    // ── Pipeline tests using test-only migration functions ─────────────
+    //
+    // Test schema versions:
+    //   v1 → v2: adds "addedInV2": "hello"
+    //   v2 → v3: renames "legacyField" → "renamedField"
+
+    /// v1→v2: adds a new field.
+    fn fake_v1_to_v2(doc: &mut Value) -> Result<()> {
+        if let Some(obj) = doc.as_object_mut() {
+            obj.insert("addedInV2".to_string(), Value::from("hello"));
+        }
+        Ok(())
+    }
+
+    /// v2→v3: renames a field.
+    fn fake_v2_to_v3(doc: &mut Value) -> Result<()> {
+        if let Some(obj) = doc.as_object_mut() {
+            if let Some(old) = obj.remove("legacyField") {
+                obj.insert("renamedField".to_string(), old);
+            }
+        }
+        Ok(())
+    }
+
+    /// Always fails — used to test error propagation.
+    fn fake_failing_migration(doc: &mut Value) -> Result<()> {
+        let _ = doc;
+        SchemaMigrationSnafu {
+            message: "simulated failure".to_string(),
+        }
+        .fail()
+    }
+
+    /// Full v1→v2→v3 chain.
+    fn full_chain() -> &'static [(i64, MigrationFn)] {
+        &[(1, fake_v1_to_v2), (2, fake_v2_to_v3)]
+    }
+
+    /// Minimal document at a given schema version.
+    fn doc_at_version(version: i64) -> Value {
+        serde_json::json!({
+            (SCHEMA_VERSION_FIELD): version,
+            "id": "unit-1"
+        })
+    }
+
+    /// v1 document with a field that v2→v3 will rename.
+    fn v1_doc_with_legacy_field() -> Value {
+        serde_json::json!({
+            (SCHEMA_VERSION_FIELD): 1,
+            "id": "unit-1",
+            "legacyField": "keep-me"
+        })
+    }
+
+    /// v1 document with extra fields to verify they survive migration.
+    fn v1_doc_with_extra_fields() -> Value {
+        serde_json::json!({
+            (SCHEMA_VERSION_FIELD): 1,
+            "id": "unit-1",
+            "customData": {"nested": true},
+            "tags": ["a", "b"]
+        })
+    }
+
+    #[test]
+    fn test_pipeline_single_step_v1_to_v2() {
+        let doc = doc_at_version(1);
+
+        let result = migrate_with(doc, 2, &[(1, fake_v1_to_v2)]).unwrap();
+
+        assert_eq!(result[SCHEMA_VERSION_FIELD], 2);
+        assert_eq!(result["addedInV2"], "hello");
+        assert_eq!(result["id"], "unit-1");
+    }
+
+    #[test]
+    fn test_pipeline_two_steps_v1_to_v3() {
+        let doc = v1_doc_with_legacy_field();
+
+        let result = migrate_with(doc, 3, full_chain()).unwrap();
+
+        assert_eq!(result[SCHEMA_VERSION_FIELD], 3);
+        assert_eq!(result["addedInV2"], "hello");
+        assert_eq!(result["renamedField"], "keep-me");
+        assert!(result.get("legacyField").is_none());
+    }
+
+    #[test]
+    fn test_pipeline_starts_from_middle_version() {
+        let doc = doc_at_version(2);
+
+        let result = migrate_with(doc, 3, full_chain()).unwrap();
+
+        assert_eq!(result[SCHEMA_VERSION_FIELD], 3);
+        assert!(
+            result.get("addedInV2").is_none(),
+            "v1→v2 should not have run"
+        );
+    }
+
+    #[test]
+    fn test_pipeline_incomplete_chain_reports_error() {
+        let doc = doc_at_version(1);
+
+        let err = migrate_with(doc, 3, &[(1, fake_v1_to_v2)]).unwrap_err();
+
+        assert_eq!(err.error_code_i32(), 1021);
+        assert!(err.to_string().contains("Migration chain incomplete"));
+        assert!(err.to_string().contains("reached v2"));
+        assert!(err.to_string().contains("expected v3"));
+    }
+
+    #[test]
+    fn test_pipeline_migration_failure_stops_chain() {
+        let chain: &[(i64, MigrationFn)] = &[(1, fake_failing_migration), (2, fake_v2_to_v3)];
+        let doc = doc_at_version(1);
+
+        let err = migrate_with(doc, 3, chain).unwrap_err();
+
+        assert_eq!(err.error_code_i32(), 1021);
+        assert!(err.to_string().contains("v1 to v2"));
+        assert!(err.to_string().contains("simulated failure"));
+    }
+
+    #[test]
+    fn test_pipeline_already_at_target_is_noop() {
+        let doc = doc_at_version(2);
+
+        let result = migrate_with(doc.clone(), 2, &[(1, fake_v1_to_v2)]).unwrap();
+
+        assert_eq!(result, doc);
+    }
+
+    #[test]
+    fn test_set_version_rejects_non_object_root() {
+        let mut doc = Value::from("not-an-object");
+        let err = set_version(&mut doc, 2).unwrap_err();
+        assert_eq!(err.error_code_i32(), 1021);
+        assert!(err.to_string().contains("must be a JSON object"));
+    }
+
+    #[test]
+    fn test_pipeline_preserves_unrelated_fields() {
+        let doc = v1_doc_with_extra_fields();
+
+        let result = migrate_with(doc, 3, full_chain()).unwrap();
+
+        assert_eq!(result["customData"]["nested"], true);
+        assert_eq!(result["tags"][0], "a");
+        assert_eq!(result["tags"][1], "b");
+    }
+}

snowflake_code_unit_registry-0.5.4/crates/scai-state-core/src/migration/versions/mod.rs

@@ -0,0 +1,32 @@
+//! Individual migration functions, one per schema version transition.
+//!
+//! Each migration lives in its own file named `v{N}_to_v{N+1}.rs` and
+//! exports a single public function:
+//!
+//! ```ignore
+//! pub fn migrate(doc: &mut Value) -> Result<()> { ... }
+//! ```
+//!
+//! ## Adding a new migration
+//!
+//! 1. Freeze the current schema to `schemas/history/code-unit.v{N}.schema.json` (**before** editing).
+//! 2. Create `migration/versions/v{N}_to_v{N+1}.rs`.
+//! 3. Implement `pub fn migrate(doc: &mut Value) -> Result<()>`.
+//! 4. Add `mod v{N}_to_v{N+1};` below.
+//! 5. Add `(N, v{N}_to_v{N+1}::migrate)` to [`MIGRATIONS`].
+//! 6. Bump [`CURRENT_SCHEMA_VERSION`](super::CURRENT_SCHEMA_VERSION).
+
+use serde_json::Value;
+
+use crate::error::*;
+
+pub(crate) type MigrationFn = fn(&mut Value) -> Result<()>;
+
+// ── Migration modules ──────────────────────────────────────────────────
+// mod v1_to_v2;
+
+/// Ordered migration chain. Each entry is `(from_version, migration_fn)`.
+/// A migration from version N always produces version N+1.
+pub(crate) const MIGRATIONS: &[(i64, MigrationFn)] = &[
+    // (1, v1_to_v2::migrate),
+];