@lix-js/sdk 0.6.0-preview.2 → 0.6.0-preview.4

package/dist-engine-src/src/transaction/normalization.rs

@@ -1,244 +1,200 @@
-use std::collections::BTreeMap;
+use std::sync::Arc;
 
 use serde_json::{Map as JsonMap, Value as JsonValue};
 
+use crate::catalog::{CatalogSnapshot, SchemaPlan, SchemaPlanId};
+use crate::common::format_json_pointer;
 use crate::common::normalize_path_segment;
+use crate::domain::Domain;
 use crate::entity_identity::{EntityIdentity, EntityIdentityError};
 use crate::functions::FunctionProviderHandle;
 use crate::schema::{
-    apply_schema_defaults_with_shared_runtime, is_seed_schema_key,
-    reject_unsupported_registered_schema_version, schema_from_registered_snapshot,
-    schema_key_from_definition, validate_lix_schema, validate_lix_schema_definition, SchemaKey,
+    is_seed_schema_key, schema_from_registered_snapshot, validate_lix_schema,
+    validate_lix_schema_definition,
 };
-use crate::transaction::types::StageRow;
+use crate::transaction::types::{PreparedRowFacts, TransactionJson, TransactionWriteRow};
 use crate::LixError;
 
 pub(crate) const REGISTERED_SCHEMA_KEY: &str = "lix_registered_schema";
 const DIRECTORY_DESCRIPTOR_SCHEMA_KEY: &str = "lix_directory_descriptor";
 const FILE_DESCRIPTOR_SCHEMA_KEY: &str = "lix_file_descriptor";
 
-/// Transaction-local schema catalog used while raw writes are staged.
-///
-/// Normalization has to happen before rows are keyed in the staged-write map:
-/// defaults may fill primary-key fields and primary keys may derive the final
-/// entity id. The catalog starts with session-visible schemas and is updated as
-/// pending `lix_registered_schema` rows are staged, so later rows in the same
-/// transaction can target newly registered schemas.
-#[derive(Debug, Clone, Default)]
-pub(crate) struct TransactionSchemaCatalog {
-    schemas_by_key: BTreeMap<SchemaCatalogKey, JsonValue>,
-}
-
-impl TransactionSchemaCatalog {
-    pub(crate) fn from_visible_schemas(visible_schemas: &[JsonValue]) -> Result<Self, LixError> {
-        let mut catalog = Self::default();
-        for schema in visible_schemas {
-            let key = schema_key_from_definition(schema)?;
-            catalog.insert_schema(key, schema.clone());
-        }
-        Ok(catalog)
-    }
-
-    pub(crate) fn schema(&self, schema_key: &str, schema_version: &str) -> Option<&JsonValue> {
-        self.schemas_by_key.get(&SchemaCatalogKey {
-            schema_key: schema_key.to_string(),
-            schema_version: schema_version.to_string(),
-        })
-    }
-
-    pub(crate) fn insert_schema(&mut self, key: SchemaKey, schema: JsonValue) {
-        self.schemas_by_key
-            .insert(SchemaCatalogKey::from_schema_key(key), schema);
-    }
-
-    pub(crate) fn contains(&self, schema_key: &str, schema_version: &str) -> bool {
-        self.schemas_by_key.contains_key(&SchemaCatalogKey {
-            schema_key: schema_key.to_string(),
-            schema_version: schema_version.to_string(),
-        })
-    }
-
-    #[cfg(test)]
-    pub(crate) fn len(&self) -> usize {
-        self.schemas_by_key.len()
-    }
-
-    pub(crate) fn schema_by_key(&self, schema_key: &str) -> Option<&JsonValue> {
-        self.schemas_by_key
-            .iter()
-            .find_map(|(key, schema)| (key.schema_key == schema_key).then_some(schema))
-    }
-
-    pub(crate) fn schema_key_by_key(&self, schema_key: &str) -> Option<SchemaCatalogKey> {
-        self.schemas_by_key
-            .keys()
-            .find(|key| key.schema_key == schema_key)
-            .cloned()
-    }
-
-    pub(crate) fn schemas(&self) -> impl Iterator<Item = (&SchemaCatalogKey, &JsonValue)> {
-        self.schemas_by_key.iter()
-    }
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct NormalizedTransactionWriteRow {
+    pub(crate) row: TransactionWriteRow,
+    pub(crate) snapshot: Option<TransactionJson>,
+    pub(crate) schema_plan_id: SchemaPlanId,
+    pub(crate) facts: PreparedRowFacts,
 }
 
 /// Normalizes one incoming row into a row with final snapshot/entity identity.
 ///
-/// This is the canonical schema-semantics boundary for staged writes. It owns
+/// This is the canonical schema-semantics boundary for transaction writes. It owns
 /// schema default application, primary-key identity derivation, and explicit
 /// identity mismatch validation. SQL providers should not pre-derive primary
-/// keys for schemas that can be normalized here; they should stage decoded
+/// keys for schemas that can be normalized here; they should pass decoded
 /// snapshots and let this layer complete them.
 ///
 /// This function intentionally does not assign timestamps, change ids, or
-/// commit ids; those are transaction hydration fields handled by staging after
-/// semantic normalization has produced the final identity.
-pub(crate) fn normalize_stage_row(
-    mut row: StageRow,
-    schema_catalog: &mut TransactionSchemaCatalog,
+/// commit ids; those are prepared-row fields assigned after semantic
+/// normalization has produced the final identity.
+pub(crate) fn normalize_transaction_write_row(
+    mut row: TransactionWriteRow,
+    schema_catalog: &mut CatalogSnapshot,
     functions: FunctionProviderHandle,
-) -> Result<StageRow, LixError> {
-    validate_stage_row_schema_identity(&row)?;
+) -> Result<NormalizedTransactionWriteRow, LixError> {
+    validate_transaction_write_row_schema_identity(&row)?;
 
-    let Some(schema) = schema_catalog
-        .schema(&row.schema_key, &row.schema_version)
-        .cloned()
-    else {
+    let Some((schema_plan_id, schema_plan)) = schema_catalog.plan_for_key(&row.schema_key) else {
         return Err(LixError::new(
             LixError::CODE_SCHEMA_DEFINITION,
             format!(
-                "schema '{}' version '{}' is not visible to this transaction",
-                row.schema_key, row.schema_version
+                "schema '{}' is not visible to this transaction",
+                row.schema_key
             ),
         ));
     };
 
-    if let Some(snapshot_content) = row.snapshot_content.as_deref() {
-        let mut snapshot = parse_snapshot_object(snapshot_content, &row)?;
-        apply_defaults(&mut snapshot, &schema, &row, functions)?;
-        normalize_filesystem_descriptor_snapshot(&row, &mut snapshot)?;
+    let normalized_snapshot = if let Some(snapshot) = row.snapshot.take() {
+        let (mut snapshot, normalized) = snapshot_object_from_transaction_json(snapshot, &row)?;
+        let defaults_changed = apply_defaults(&mut snapshot, schema_plan, &row, functions)?;
+        let descriptor_changed = normalize_filesystem_descriptor_snapshot(&row, &mut snapshot)?;
         let snapshot = JsonValue::Object(snapshot);
-        row.entity_id = Some(resolve_entity_id(&row, &schema, &snapshot)?);
-        row.snapshot_content = Some(serde_json::to_string(&snapshot).map_err(|error| {
-            LixError::new(
-                LixError::CODE_UNKNOWN,
-                format!(
-                    "failed to serialize normalized snapshot_content for schema '{}' version '{}': {error}",
-                    row.schema_key, row.schema_version
-                ),
-            )
-        })?);
+        row.entity_id = Some(resolve_entity_id(&row, schema_plan, &snapshot)?);
+        if defaults_changed || descriptor_changed {
+            Some(TransactionJson::from_value(
+                snapshot,
+                "normalized transaction snapshot_content",
+            )?)
+        } else {
+            Some(TransactionJson::from_parts(Arc::new(snapshot), normalized))
+        }
     } else if row.entity_id.is_none() {
         return Err(LixError::new(
             LixError::CODE_SCHEMA_VALIDATION,
             format!(
-                "tombstone for schema '{}' version '{}' requires entity_id",
-                row.schema_key, row.schema_version
+                "tombstone for schema '{}' requires entity_id",
+                row.schema_key
             ),
         ));
-    }
+    } else {
+        None
+    };
 
     if row.schema_key == REGISTERED_SCHEMA_KEY {
-        remember_pending_registered_schema(row.snapshot_content.as_deref(), schema_catalog)?;
-    }
-
-    Ok(row)
+        if row.file_id.is_some() {
+            return Err(LixError::new(
+                LixError::CODE_SCHEMA_DEFINITION,
+                "lix_registered_schema rows must not be scoped to a file",
+            )
+            .with_hint("Schema definitions are scoped by version and durability only; write them with null file_id."));
+        }
+        let schema_domain =
+            Domain::schema_catalog(row.schema_scope_version_id().to_string(), row.untracked);
+        remember_pending_registered_schema(
+            normalized_snapshot.as_ref().map(TransactionJson::value),
+            schema_domain,
+            schema_catalog,
+        )?;
+    }
+
+    Ok(NormalizedTransactionWriteRow {
+        row,
+        snapshot: normalized_snapshot,
+        schema_plan_id,
+        facts: PreparedRowFacts::default(),
+    })
 }
 
-fn validate_stage_row_schema_identity(row: &StageRow) -> Result<(), LixError> {
+fn validate_transaction_write_row_schema_identity(
+    row: &TransactionWriteRow,
+) -> Result<(), LixError> {
     if row.schema_key.is_empty() {
         return Err(LixError::new(
             LixError::CODE_UNKNOWN,
-            "engine2 transaction staging requires non-empty schema_key",
-        ));
-    }
-    if row.schema_version.is_empty() {
-        return Err(LixError::new(
-            LixError::CODE_UNKNOWN,
-            "engine2 transaction staging requires non-empty schema_version",
+            "engine transaction staging requires non-empty schema_key",
         ));
     }
     Ok(())
 }
 
-fn parse_snapshot_object(
-    snapshot_content: &str,
-    row: &StageRow,
-) -> Result<JsonMap<String, JsonValue>, LixError> {
-    let snapshot = serde_json::from_str::<JsonValue>(snapshot_content).map_err(|error| {
-        LixError::new(
-            LixError::CODE_SCHEMA_VALIDATION,
-            format!(
-                "snapshot_content for schema '{}' version '{}' is invalid JSON: {error}",
-                row.schema_key, row.schema_version
-            ),
-        )
-    })?;
-    snapshot.as_object().cloned().ok_or_else(|| {
-        LixError::new(
+fn snapshot_object_from_transaction_json(
+    snapshot: TransactionJson,
+    row: &TransactionWriteRow,
+) -> Result<(JsonMap<String, JsonValue>, Arc<str>), LixError> {
+    let (snapshot, normalized) = snapshot.into_parts();
+    let snapshot = match Arc::try_unwrap(snapshot) {
+        Ok(snapshot) => snapshot,
+        Err(snapshot) => snapshot.as_ref().clone(),
+    };
+    match snapshot {
+        JsonValue::Object(snapshot) => Ok((snapshot, normalized)),
+        _ => Err(LixError::new(
             LixError::CODE_SCHEMA_VALIDATION,
             format!(
-                "snapshot_content for schema '{}' version '{}' must be a JSON object",
-                row.schema_key, row.schema_version
+                "snapshot_content for schema '{}' must be a JSON object",
+                row.schema_key
             ),
-        )
-    })
+        )),
+    }
 }
 
 fn apply_defaults(
     snapshot: &mut JsonMap<String, JsonValue>,
-    schema: &JsonValue,
-    row: &StageRow,
+    schema_plan: &SchemaPlan,
+    row: &TransactionWriteRow,
     functions: FunctionProviderHandle,
-) -> Result<(), LixError> {
-    apply_schema_defaults_with_shared_runtime(
-        snapshot,
-        schema,
-        functions,
-        &row.schema_key,
-        &row.schema_version,
-    )?;
-    Ok(())
+) -> Result<bool, LixError> {
+    schema_plan
+        .defaults
+        .apply(snapshot, functions, &row.schema_key)
 }
 
 fn normalize_filesystem_descriptor_snapshot(
-    row: &StageRow,
+    row: &TransactionWriteRow,
     snapshot: &mut JsonMap<String, JsonValue>,
-) -> Result<(), LixError> {
+) -> Result<bool, LixError> {
     match row.schema_key.as_str() {
         DIRECTORY_DESCRIPTOR_SCHEMA_KEY => normalize_directory_descriptor_snapshot(row, snapshot),
         FILE_DESCRIPTOR_SCHEMA_KEY => normalize_file_descriptor_snapshot(row, snapshot),
-        _ => Ok(()),
+        _ => Ok(false),
     }
 }
 
 fn normalize_directory_descriptor_snapshot(
-    row: &StageRow,
+    row: &TransactionWriteRow,
     snapshot: &mut JsonMap<String, JsonValue>,
-) -> Result<(), LixError> {
+) -> Result<bool, LixError> {
     let Some(name) = optional_string_field(snapshot, "name", row)? else {
-        return Ok(());
+        return Ok(false);
     };
     let normalized_name = normalize_path_segment(name)?;
+    if name == normalized_name {
+        return Ok(false);
+    }
     snapshot.insert("name".to_string(), JsonValue::String(normalized_name));
-    Ok(())
+    Ok(true)
 }
 
 fn normalize_file_descriptor_snapshot(
-    row: &StageRow,
+    row: &TransactionWriteRow,
     snapshot: &mut JsonMap<String, JsonValue>,
-) -> Result<(), LixError> {
+) -> Result<bool, LixError> {
     let Some(name) = optional_string_field(snapshot, "name", row)? else {
-        return Ok(());
+        return Ok(false);
     };
     let normalized_name = normalize_path_segment(name)?;
+    if name == normalized_name {
+        return Ok(false);
+    }
     snapshot.insert("name".to_string(), JsonValue::String(normalized_name));
-    Ok(())
+    Ok(true)
 }
 
 fn optional_string_field<'a>(
     snapshot: &'a JsonMap<String, JsonValue>,
     field: &str,
-    row: &StageRow,
+    row: &TransactionWriteRow,
 ) -> Result<Option<&'a str>, LixError> {
     let Some(value) = snapshot.get(field) else {
         return Ok(None);
@@ -247,38 +203,38 @@ fn optional_string_field<'a>(
         LixError::new(
             LixError::CODE_SCHEMA_VALIDATION,
             format!(
-                "snapshot_content for schema '{}' version '{}' field '{}' must be a string",
-                row.schema_key, row.schema_version, field
+                "snapshot_content for schema '{}' field '{}' must be a string",
+                row.schema_key, field
             ),
         )
     })
 }
 
 fn resolve_entity_id(
-    row: &StageRow,
-    schema: &JsonValue,
+    row: &TransactionWriteRow,
+    schema_plan: &SchemaPlan,
     snapshot: &JsonValue,
 ) -> Result<EntityIdentity, LixError> {
-    let Some(primary_key_paths) = primary_key_paths(schema)? else {
+    let Some(primary_key_paths) = schema_plan.primary_key.as_ref() else {
         return row.entity_id.clone().ok_or_else(|| {
             LixError::new(
                 LixError::CODE_SCHEMA_VALIDATION,
                 format!(
-                    "write for schema '{}' version '{}' requires entity_id because the schema has no x-lix-primary-key",
-                    row.schema_key, row.schema_version
+                    "write for schema '{}' requires entity_id because the schema has no x-lix-primary-key",
+                    row.schema_key
                 ),
             )
         });
     };
-    let derived = EntityIdentity::from_primary_key_paths(snapshot, &primary_key_paths)
-        .map_err(|error| entity_id_derivation_error(row, &primary_key_paths, error))?;
+    let derived = EntityIdentity::from_primary_key_paths(snapshot, primary_key_paths)
+        .map_err(|error| entity_id_derivation_error(row, primary_key_paths, error))?;
     if let Some(entity_id) = row.entity_id.as_ref() {
         if entity_id != &derived {
             return Err(LixError::new(
                 LixError::CODE_SCHEMA_VALIDATION,
                 format!(
-                    "entity_id '{}' does not match x-lix-primary-key derived entity_id '{}' for schema '{}' version '{}'",
-                    entity_id.as_string()?, derived.as_string()?, row.schema_key, row.schema_version
+                    "entity_id '{}' does not match x-lix-primary-key derived entity_id '{}' for schema '{}'",
+                    entity_id.as_json_array_text()?, derived.as_json_array_text()?, row.schema_key
                 ),
             ));
         }
@@ -286,72 +242,8 @@ fn resolve_entity_id(
     Ok(derived)
 }
 
-fn primary_key_paths(schema: &JsonValue) -> Result<Option<Vec<Vec<String>>>, LixError> {
-    let Some(primary_key) = schema.get("x-lix-primary-key") else {
-        return Ok(None);
-    };
-    let primary_key = primary_key.as_array().ok_or_else(|| {
-        LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            "schema x-lix-primary-key must be an array of JSON Pointers",
-        )
-    })?;
-    primary_key
-        .iter()
-        .enumerate()
-        .map(|(index, pointer)| {
-            let pointer = pointer.as_str().ok_or_else(|| {
-                LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!("schema x-lix-primary-key entry at index {index} must be a string"),
-                )
-            })?;
-            parse_json_pointer(pointer)
-        })
-        .collect::<Result<Vec<_>, _>>()
-        .map(Some)
-}
-
-fn parse_json_pointer(pointer: &str) -> Result<Vec<String>, LixError> {
-    if pointer.is_empty() {
-        return Ok(Vec::new());
-    }
-    if !pointer.starts_with('/') {
-        return Err(LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!("invalid JSON pointer '{pointer}'"),
-        ));
-    }
-    pointer[1..]
-        .split('/')
-        .map(decode_json_pointer_segment)
-        .collect()
-}
-
-fn decode_json_pointer_segment(segment: &str) -> Result<String, LixError> {
-    let mut out = String::new();
-    let mut chars = segment.chars();
-    while let Some(ch) = chars.next() {
-        if ch == '~' {
-            match chars.next() {
-                Some('0') => out.push('~'),
-                Some('1') => out.push('/'),
-                _ => {
-                    return Err(LixError::new(
-                        LixError::CODE_SCHEMA_DEFINITION,
-                        "invalid JSON pointer escape",
-                    ))
-                }
-            }
-        } else {
-            out.push(ch);
-        }
-    }
-    Ok(out)
-}
-
 fn entity_id_derivation_error(
-    row: &StageRow,
+    row: &TransactionWriteRow,
     primary_key_paths: &[Vec<String>],
     error: EntityIdentityError,
 ) -> LixError {
@@ -360,21 +252,20 @@ fn entity_id_derivation_error(
         EntityIdentityError::EmptyPrimaryKeyPath { index } => {
             format!("empty x-lix-primary-key pointer at index {index}")
         }
+        EntityIdentityError::EmptyPrimaryKeyValue { index } => {
+            let pointer = primary_key_paths
+                .get(index)
+                .map(|path| format_json_pointer(path))
+                .unwrap_or_else(|| format!("index {index}"));
+            format!("empty value at primary-key pointer '{pointer}'")
+        }
         EntityIdentityError::MissingPrimaryKeyValue { index } => {
             let pointer = format_json_pointer(&primary_key_paths[index]);
             format!("missing value at primary-key pointer '{pointer}'")
         }
-        EntityIdentityError::NullPrimaryKeyValue { index } => {
-            let pointer = format_json_pointer(&primary_key_paths[index]);
-            format!("null value at primary-key pointer '{pointer}'")
-        }
-        EntityIdentityError::EmptyPrimaryKeyValue { index } => {
-            let pointer = format_json_pointer(&primary_key_paths[index]);
-            format!("empty value at primary-key pointer '{pointer}'")
-        }
         EntityIdentityError::UnsupportedPrimaryKeyValue { index } => {
             let pointer = format_json_pointer(&primary_key_paths[index]);
-            format!("unsupported non-scalar value at primary-key pointer '{pointer}'")
+            format!("non-string value at primary-key pointer '{pointer}'")
         }
         EntityIdentityError::InvalidEncodedEntityIdentity => {
             "invalid encoded entity identity".to_string()
@@ -383,56 +274,38 @@ fn entity_id_derivation_error(
     LixError::new(
         LixError::CODE_SCHEMA_VALIDATION,
         format!(
-            "failed to derive entity_id for schema '{}' version '{}': {detail}",
-            row.schema_key, row.schema_version
+            "failed to derive entity_id for schema '{}': {detail}",
+            row.schema_key
         ),
     )
 }
 
-fn format_json_pointer(segments: &[String]) -> String {
-    if segments.is_empty() {
-        return String::new();
-    }
-    format!(
-        "/{}",
-        segments
-            .iter()
-            .map(|segment| segment.replace('~', "~0").replace('/', "~1"))
-            .collect::<Vec<_>>()
-            .join("/")
-    )
-}
-
 pub(crate) fn remember_pending_registered_schema(
-    snapshot_content: Option<&str>,
-    schema_catalog: &mut TransactionSchemaCatalog,
+    snapshot: Option<&JsonValue>,
+    domain: Domain,
+    schema_catalog: &mut CatalogSnapshot,
 ) -> Result<(), LixError> {
-    let Some(snapshot_content) = snapshot_content else {
+    let Some(snapshot) = snapshot else {
         return Err(LixError::new(
             LixError::CODE_SCHEMA_DEFINITION,
             "lix_registered_schema rows cannot be deleted yet; schema deletion is not supported",
         ));
     };
-    let snapshot = serde_json::from_str::<JsonValue>(snapshot_content).map_err(|error| {
-        LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!("pending registered schema snapshot_content is invalid JSON: {error}"),
-        )
-    })?;
-    let registered_schema_definition = schema_catalog
-        .schema(REGISTERED_SCHEMA_KEY, "1")
-        .cloned()
-        .ok_or_else(|| {
-        LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            "lix_registered_schema schema is not visible to this transaction",
-        )
-    })?;
-    if !snapshot.get("value").is_some_and(JsonValue::is_object) {
-        validate_lix_schema(&registered_schema_definition, &snapshot)?;
+    if let Some(schema) = snapshot.get("value") {
+        validate_lix_schema_definition(schema)?;
+    }
+    {
+        let registered_schema_definition = schema_catalog
+            .schema(REGISTERED_SCHEMA_KEY)
+            .ok_or_else(|| {
+                LixError::new(
+                    LixError::CODE_SCHEMA_DEFINITION,
+                    "lix_registered_schema schema is not visible to this transaction",
+                )
+            })?;
+        validate_lix_schema(registered_schema_definition, &snapshot)?;
     }
     let (key, schema) = schema_from_registered_snapshot(&snapshot)?;
-    reject_unsupported_registered_schema_version(&key)?;
     if is_seed_schema_key(&key.schema_key) {
         return Err(LixError::new(
             LixError::CODE_SCHEMA_DEFINITION,
@@ -443,26 +316,10 @@ pub(crate) fn remember_pending_registered_schema(
         ));
     }
     validate_lix_schema_definition(&schema)?;
-    validate_lix_schema(&registered_schema_definition, &snapshot)?;
-    schema_catalog.insert_schema(key, schema);
+    schema_catalog.insert_schema_for_domain(domain, key, schema)?;
     Ok(())
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
-pub(crate) struct SchemaCatalogKey {
-    pub(crate) schema_key: String,
-    pub(crate) schema_version: String,
-}
-
-impl SchemaCatalogKey {
-    pub(crate) fn from_schema_key(key: SchemaKey) -> Self {
-        Self {
-            schema_key: key.schema_key,
-            schema_version: key.schema_version,
-        }
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use serde_json::json;
@@ -474,18 +331,20 @@ mod tests {
     #[test]
     fn normalization_derives_entity_id_from_primary_key() {
         let mut catalog = catalog_with(vec![schema_with_default_id()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "normalization_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"entity-from-snapshot","value":"hello"}"#.to_string()),
+            snapshot: Some(snapshot_json(
+                r#"{"id":"entity-from-snapshot","value":"hello"}"#,
+            )),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
 
         assert_eq!(
-            row.entity_id.as_ref(),
+            row.row.entity_id.as_ref(),
             Some(&crate::entity_identity::EntityIdentity::single(
                 "entity-from-snapshot"
             ))
@@ -495,20 +354,19 @@ mod tests {
     #[test]
     fn normalization_applies_json_and_cel_defaults_before_identity_derivation() {
         let mut catalog = catalog_with(vec![schema_with_default_id()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "normalization_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{}"#)),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
-        let snapshot: JsonValue =
-            serde_json::from_str(row.snapshot_content.as_deref().unwrap()).unwrap();
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
+        let snapshot = normalized_snapshot(&row);
 
         assert_eq!(
-            row.entity_id.as_ref(),
+            row.row.entity_id.as_ref(),
             Some(&crate::entity_identity::EntityIdentity::single(
                 "uuid-default"
             ))
@@ -520,17 +378,16 @@ mod tests {
     #[test]
     fn normalization_applies_cel_defaults_from_snapshot_context() {
         let mut catalog = catalog_with(vec![schema_with_cel_field_default()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "cel_field_default_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"entity-1","name":"Sample"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"entity-1","name":"Sample"}"#)),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
-        let snapshot: JsonValue =
-            serde_json::from_str(row.snapshot_content.as_deref().unwrap()).unwrap();
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
+        let snapshot = normalized_snapshot(&row);
 
         assert_eq!(snapshot["slug"], "Sample-slug");
     }
@@ -538,17 +395,16 @@ mod tests {
     #[test]
     fn normalization_x_lix_default_overrides_json_default() {
         let mut catalog = catalog_with(vec![schema_with_overridden_default()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "overridden_default_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"entity-1"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"entity-1"}"#)),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
-        let snapshot: JsonValue =
-            serde_json::from_str(row.snapshot_content.as_deref().unwrap()).unwrap();
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
+        let snapshot = normalized_snapshot(&row);
 
         assert_eq!(snapshot["status"], "computed");
     }
@@ -556,17 +412,16 @@ mod tests {
     #[test]
     fn normalization_does_not_overwrite_explicit_null_with_default() {
         let mut catalog = catalog_with(vec![schema_with_nullable_default()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "nullable_default_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"entity-1","status":null}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"entity-1","status":null}"#)),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
-        let snapshot: JsonValue =
-            serde_json::from_str(row.snapshot_content.as_deref().unwrap()).unwrap();
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
+        let snapshot = normalized_snapshot(&row);
 
         assert_eq!(snapshot["status"], JsonValue::Null);
     }
@@ -574,17 +429,16 @@ mod tests {
     #[test]
     fn normalization_applies_timestamp_function_default() {
         let mut catalog = catalog_with(vec![schema_with_timestamp_default()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "timestamp_default_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"entity-1"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"entity-1"}"#)),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
-        let snapshot: JsonValue =
-            serde_json::from_str(row.snapshot_content.as_deref().unwrap()).unwrap();
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
+        let snapshot = normalized_snapshot(&row);
 
         assert_eq!(snapshot["created_at"], "1970-01-01T00:00:00.000Z");
     }
@@ -592,16 +446,15 @@ mod tests {
     #[test]
     fn normalization_surfaces_cel_default_errors() {
         let mut catalog = catalog_with(vec![schema_with_unknown_cel_default()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "unknown_cel_default_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"entity-1"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"entity-1"}"#)),
             ..base_stage_row()
         };
 
-        let error =
-            normalize_stage_row(row, &mut catalog, functions()).expect_err("default should fail");
+        let error = normalize_transaction_write_row(row, &mut catalog, functions())
+            .expect_err("default should fail");
 
         assert!(error.message.contains("failed to evaluate x-lix-default"));
         assert!(error.message.contains("unknown_cel_default_schema.slug"));
@@ -610,16 +463,15 @@ mod tests {
     #[test]
     fn normalization_rejects_entity_id_that_disagrees_with_primary_key() {
         let mut catalog = catalog_with(vec![schema_with_default_id()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: Some(crate::entity_identity::EntityIdentity::single("wrong-id")),
             schema_key: "normalization_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"right-id","value":"hello"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"right-id","value":"hello"}"#)),
             ..base_stage_row()
         };
 
-        let error =
-            normalize_stage_row(row, &mut catalog, functions()).expect_err("id mismatch fails");
+        let error = normalize_transaction_write_row(row, &mut catalog, functions())
+            .expect_err("id mismatch fails");
 
         assert!(error
             .message
@@ -627,22 +479,42 @@ mod tests {
     }
 
     #[test]
-    fn normalization_derives_opaque_entity_id_for_composite_primary_key() {
+    fn normalization_derives_json_array_entity_id_for_composite_primary_key() {
+        let mut catalog = catalog_with(vec![composite_key_schema()]);
+        let row = TransactionWriteRow {
+            entity_id: None,
+            schema_key: "composite_key_schema".to_string(),
+            snapshot: Some(snapshot_json(r#"{"namespace":"a~b","key":"1"}"#)),
+            ..base_stage_row()
+        };
+
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
+        let entity_id = row.row.entity_id.expect("composite entity id");
+        let projected_entity_id = entity_id
+            .as_json_array_text()
+            .expect("entity id should project");
+
+        assert_eq!(projected_entity_id, "[\"a~b\",\"1\"]");
+    }
+
+    #[test]
+    fn normalization_rejects_non_string_primary_key_values() {
         let mut catalog = catalog_with(vec![composite_key_schema()]);
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: None,
             schema_key: "composite_key_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"namespace":"a~b","key":"1"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"namespace":"a~b","key":1}"#)),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
-        let entity_id = row.entity_id.expect("composite entity id");
-        let projected_entity_id = entity_id.as_string().expect("entity id should project");
+        let error = normalize_transaction_write_row(row, &mut catalog, functions())
+            .expect_err("non-string primary key values should fail");
 
-        assert!(projected_entity_id.starts_with("pk:v1:"));
-        assert_ne!(projected_entity_id, "a~b~1");
+        assert_eq!(error.code, LixError::CODE_SCHEMA_VALIDATION);
+        assert!(error
+            .message
+            .contains("non-string value at primary-key pointer '/key'"));
     }
 
     #[test]
@@ -657,17 +529,17 @@ mod tests {
             &[vec!["namespace".to_string()], vec!["key".to_string()]],
         )
         .expect("identity should derive");
-        let row = StageRow {
+        let row = TransactionWriteRow {
             entity_id: Some(derived.clone()),
             schema_key: "composite_key_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(snapshot.to_string()),
+            snapshot: Some(transaction_json(snapshot.clone())),
             ..base_stage_row()
         };
 
-        let row = normalize_stage_row(row, &mut catalog, functions()).expect("normalize row");
+        let row =
+            normalize_transaction_write_row(row, &mut catalog, functions()).expect("normalize row");
 
-        assert_eq!(row.entity_id.as_ref(), Some(&derived));
+        assert_eq!(row.row.entity_id.as_ref(), Some(&derived));
     }
 
     #[test]
@@ -675,32 +547,29 @@ mod tests {
         let mut catalog = catalog_with(vec![seed_schema_definition(REGISTERED_SCHEMA_KEY)
             .expect("registered schema builtin")
             .clone()]);
-        let registered = StageRow {
+        let registered = TransactionWriteRow {
             entity_id: None,
             schema_key: REGISTERED_SCHEMA_KEY.to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(
-                json!({
-                    "value": dynamic_schema_definition(),
-                })
-                .to_string(),
-            ),
+            snapshot: Some(transaction_json(json!({
+                "value": dynamic_schema_definition(),
+            }))),
             ..base_stage_row()
         };
 
-        normalize_stage_row(registered, &mut catalog, functions()).expect("register schema");
+        normalize_transaction_write_row(registered, &mut catalog, functions())
+            .expect("register schema");
 
-        let dynamic = StageRow {
+        let dynamic = TransactionWriteRow {
             entity_id: None,
             schema_key: "dynamic_schema".to_string(),
-            schema_version: "1".to_string(),
-            snapshot_content: Some(r#"{"id":"dynamic-1"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"dynamic-1"}"#)),
             ..base_stage_row()
         };
-        let dynamic = normalize_stage_row(dynamic, &mut catalog, functions()).expect("dynamic row");
+        let dynamic = normalize_transaction_write_row(dynamic, &mut catalog, functions())
+            .expect("dynamic row");
 
         assert_eq!(
-            dynamic.entity_id.as_ref(),
+            dynamic.row.entity_id.as_ref(),
             Some(&crate::entity_identity::EntityIdentity::single("dynamic-1"))
         );
     }
@@ -712,43 +581,36 @@ mod tests {
             builtin_schema(DIRECTORY_DESCRIPTOR_SCHEMA_KEY),
         ]);
 
-        let file = StageRow {
+        let file = TransactionWriteRow {
             entity_id: None,
             schema_key: FILE_DESCRIPTOR_SCHEMA_KEY.to_string(),
-            snapshot_content: Some(
-                json!({
-                    "id": "file-cafe",
-                    "directory_id": null,
-                    "name": "Cafe\u{301}.txt",
-                })
-                .to_string(),
-            ),
+            snapshot: Some(transaction_json(json!({
+                "id": "file-cafe",
+                "directory_id": null,
+                "name": "Cafe\u{301}.txt",
+            }))),
             global: false,
             ..base_stage_row()
         };
-        let file = normalize_stage_row(file, &mut catalog, functions()).expect("normalize file");
-        let file_snapshot: JsonValue =
-            serde_json::from_str(file.snapshot_content.as_deref().unwrap()).unwrap();
+        let file = normalize_transaction_write_row(file, &mut catalog, functions())
+            .expect("normalize file");
+        let file_snapshot = normalized_snapshot(&file);
         assert_eq!(file_snapshot["name"], "Café.txt");
 
-        let directory = StageRow {
+        let directory = TransactionWriteRow {
             entity_id: None,
             schema_key: DIRECTORY_DESCRIPTOR_SCHEMA_KEY.to_string(),
-            snapshot_content: Some(
-                json!({
-                    "id": "dir-cafe",
-                    "parent_id": null,
-                    "name": "Cafe\u{301}",
-                })
-                .to_string(),
-            ),
+            snapshot: Some(transaction_json(json!({
+                "id": "dir-cafe",
+                "parent_id": null,
+                "name": "Cafe\u{301}",
+            }))),
             global: false,
             ..base_stage_row()
         };
-        let directory =
-            normalize_stage_row(directory, &mut catalog, functions()).expect("normalize directory");
-        let directory_snapshot: JsonValue =
-            serde_json::from_str(directory.snapshot_content.as_deref().unwrap()).unwrap();
+        let directory = normalize_transaction_write_row(directory, &mut catalog, functions())
+            .expect("normalize directory");
+        let directory_snapshot = normalized_snapshot(&directory);
         assert_eq!(directory_snapshot["name"], "Café");
     }
 
@@ -759,18 +621,15 @@ mod tests {
             builtin_schema(DIRECTORY_DESCRIPTOR_SCHEMA_KEY),
         ]);
 
-        let dot_segment = normalize_stage_row(
-            StageRow {
+        let dot_segment = normalize_transaction_write_row(
+            TransactionWriteRow {
                 entity_id: None,
                 schema_key: FILE_DESCRIPTOR_SCHEMA_KEY.to_string(),
-                snapshot_content: Some(
-                    json!({
-                        "id": "file-dotdot",
-                        "directory_id": null,
-                        "name": "..",
-                    })
-                    .to_string(),
-                ),
+                snapshot: Some(transaction_json(json!({
+                    "id": "file-dotdot",
+                    "directory_id": null,
+                    "name": "..",
+                }))),
                 global: false,
                 ..base_stage_row()
             },
@@ -780,18 +639,15 @@ mod tests {
         .expect_err("file descriptor name should reject dot segments");
         assert_eq!(dot_segment.code, "LIX_ERROR_PATH_DOT_SEGMENT");
 
-        let bidi = normalize_stage_row(
-            StageRow {
+        let bidi = normalize_transaction_write_row(
+            TransactionWriteRow {
                 entity_id: None,
                 schema_key: FILE_DESCRIPTOR_SCHEMA_KEY.to_string(),
-                snapshot_content: Some(
-                    json!({
-                        "id": "file-bidi",
-                        "directory_id": null,
-                        "name": "safe\u{202E}txt",
-                    })
-                    .to_string(),
-                ),
+                snapshot: Some(transaction_json(json!({
+                    "id": "file-bidi",
+                    "directory_id": null,
+                    "name": "safe\u{202E}txt",
+                }))),
                 global: false,
                 ..base_stage_row()
             },
@@ -801,18 +657,15 @@ mod tests {
         .expect_err("file descriptor name should reject bidi formatting characters");
         assert_eq!(bidi.code, "LIX_ERROR_PATH_INVALID_SEGMENT_CODE_POINT");
 
-        let zero_width = normalize_stage_row(
-            StageRow {
+        let zero_width = normalize_transaction_write_row(
+            TransactionWriteRow {
                 entity_id: None,
                 schema_key: DIRECTORY_DESCRIPTOR_SCHEMA_KEY.to_string(),
-                snapshot_content: Some(
-                    json!({
-                        "id": "dir-zero-width",
-                        "parent_id": null,
-                        "name": "zero\u{200D}width",
-                    })
-                    .to_string(),
-                ),
+                snapshot: Some(transaction_json(json!({
+                    "id": "dir-zero-width",
+                    "parent_id": null,
+                    "name": "zero\u{200D}width",
+                }))),
                 global: false,
                 ..base_stage_row()
             },
@@ -827,18 +680,15 @@ mod tests {
     fn normalization_keeps_file_descriptor_name_opaque() {
         let mut catalog = catalog_with(vec![builtin_schema(FILE_DESCRIPTOR_SCHEMA_KEY)]);
 
-        let row = normalize_stage_row(
-            StageRow {
+        let row = normalize_transaction_write_row(
+            TransactionWriteRow {
                 entity_id: None,
                 schema_key: FILE_DESCRIPTOR_SCHEMA_KEY.to_string(),
-                snapshot_content: Some(
-                    json!({
-                        "id": "file-opaque-name",
-                        "directory_id": null,
-                        "name": "foo.bar",
-                    })
-                    .to_string(),
-                ),
+                snapshot: Some(transaction_json(json!({
+                    "id": "file-opaque-name",
+                    "directory_id": null,
+                    "name": "foo.bar",
+                }))),
                 global: false,
                 ..base_stage_row()
             },
@@ -847,13 +697,28 @@ mod tests {
         )
         .expect("file descriptor name should be an opaque basename");
 
-        let snapshot: JsonValue =
-            serde_json::from_str(row.snapshot_content.as_deref().unwrap()).unwrap();
+        let snapshot = normalized_snapshot(&row);
         assert_eq!(snapshot["name"], "foo.bar");
     }
 
-    fn catalog_with(schemas: Vec<JsonValue>) -> TransactionSchemaCatalog {
-        TransactionSchemaCatalog::from_visible_schemas(&schemas).expect("catalog")
+    fn normalized_snapshot(row: &NormalizedTransactionWriteRow) -> &JsonValue {
+        row.snapshot
+            .as_ref()
+            .expect("normalized test row should have a snapshot")
+            .value()
+    }
+
+    fn catalog_with(schemas: Vec<JsonValue>) -> CatalogSnapshot {
+        let mut visible_schemas = schemas;
+        if visible_schemas.iter().any(|schema| {
+            schema.get("x-lix-key").and_then(JsonValue::as_str) == Some(FILE_DESCRIPTOR_SCHEMA_KEY)
+        }) && !visible_schemas.iter().any(|schema| {
+            schema.get("x-lix-key").and_then(JsonValue::as_str)
+                == Some(DIRECTORY_DESCRIPTOR_SCHEMA_KEY)
+        }) {
+            visible_schemas.push(builtin_schema(DIRECTORY_DESCRIPTOR_SCHEMA_KEY));
+        }
+        CatalogSnapshot::from_visible_schemas(&visible_schemas).expect("catalog")
     }
 
     fn builtin_schema(schema_key: &str) -> JsonValue {
@@ -862,15 +727,22 @@ mod tests {
             .clone()
     }
 
-    fn base_stage_row() -> StageRow {
-        StageRow {
+    fn transaction_json(value: JsonValue) -> TransactionJson {
+        TransactionJson::from_value_for_test(value)
+    }
+
+    fn snapshot_json(value: &str) -> TransactionJson {
+        transaction_json(serde_json::from_str(value).expect("test snapshot should parse"))
+    }
+
+    fn base_stage_row() -> TransactionWriteRow {
+        TransactionWriteRow {
             entity_id: Some(crate::entity_identity::EntityIdentity::single("entity-1")),
             schema_key: "normalization_schema".to_string(),
             file_id: None,
-            snapshot_content: Some(r#"{"id":"entity-1","value":"hello"}"#.to_string()),
+            snapshot: Some(snapshot_json(r#"{"id":"entity-1","value":"hello"}"#)),
             metadata: None,
             origin: None,
-            schema_version: "1".to_string(),
             created_at: None,
             updated_at: None,
             global: true,
@@ -884,7 +756,6 @@ mod tests {
     fn schema_with_default_id() -> JsonValue {
         json!({
             "x-lix-key": "normalization_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/id"],
             "type": "object",
             "properties": {
@@ -899,7 +770,6 @@ mod tests {
     fn schema_with_cel_field_default() -> JsonValue {
         json!({
             "x-lix-key": "cel_field_default_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/id"],
             "type": "object",
             "properties": {
@@ -915,7 +785,6 @@ mod tests {
     fn schema_with_overridden_default() -> JsonValue {
         json!({
             "x-lix-key": "overridden_default_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/id"],
             "type": "object",
             "properties": {
@@ -934,7 +803,6 @@ mod tests {
     fn schema_with_nullable_default() -> JsonValue {
         json!({
             "x-lix-key": "nullable_default_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/id"],
             "type": "object",
             "properties": {
@@ -952,7 +820,6 @@ mod tests {
     fn schema_with_timestamp_default() -> JsonValue {
         json!({
             "x-lix-key": "timestamp_default_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/id"],
             "type": "object",
             "properties": {
@@ -967,7 +834,6 @@ mod tests {
     fn schema_with_unknown_cel_default() -> JsonValue {
         json!({
             "x-lix-key": "unknown_cel_default_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/id"],
             "type": "object",
             "properties": {
@@ -982,7 +848,6 @@ mod tests {
     fn composite_key_schema() -> JsonValue {
         json!({
             "x-lix-key": "composite_key_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/namespace", "/key"],
             "type": "object",
             "properties": {
@@ -997,7 +862,6 @@ mod tests {
     fn dynamic_schema_definition() -> JsonValue {
         json!({
             "x-lix-key": "dynamic_schema",
-            "x-lix-version": "1",
             "x-lix-primary-key": ["/id"],
             "type": "object",
             "properties": {