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

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

@@ -1,16 +1,115 @@
-use std::collections::BTreeSet;
+use std::{collections::BTreeSet, fmt, ops::Deref, sync::Arc};
 
+use crate::catalog::SchemaPlanId;
 use crate::entity_identity::EntityIdentity;
-use crate::live_state::LiveStateRow;
-use crate::tracked_state::TrackedStateRow;
+use crate::json_store::JsonRef;
+use crate::live_state::MaterializedLiveStateRow;
+use crate::tracked_state::MaterializedTrackedStateRow;
 use crate::untracked_state::MaterializedUntrackedStateRow;
-use crate::RowMetadata;
+use crate::LixError;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use serde_json::Value as JsonValue;
 
-/// Incoming state row before transaction hydration.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct TransactionJson {
+    value: Arc<JsonValue>,
+    normalized: Arc<str>,
+}
+
+impl TransactionJson {
+    pub(crate) fn from_value(value: JsonValue, context: &str) -> Result<Self, LixError> {
+        let normalized: Arc<str> = serde_json::to_string(&value)
+            .map_err(|error| {
+                LixError::new(
+                    LixError::CODE_UNKNOWN,
+                    format!("{context} failed to serialize as normalized JSON: {error}"),
+                )
+            })?
+            .into();
+        Ok(Self {
+            value: Arc::new(value),
+            normalized,
+        })
+    }
+
+    pub(crate) fn from_value_unchecked(value: JsonValue) -> Self {
+        Self::from_value(value, "transaction JSON")
+            .expect("serializing serde_json::Value should not fail")
+    }
+
+    #[cfg(test)]
+    pub(crate) fn from_value_for_test(value: JsonValue) -> Self {
+        Self::from_value(value, "test transaction JSON").expect("test JSON should normalize")
+    }
+
+    pub(crate) fn from_parts(value: Arc<JsonValue>, normalized: Arc<str>) -> Self {
+        Self { value, normalized }
+    }
+
+    pub(crate) fn value(&self) -> &JsonValue {
+        self.value.as_ref()
+    }
+
+    pub(crate) fn normalized(&self) -> &str {
+        self.normalized.as_ref()
+    }
+
+    pub(crate) fn into_parts(self) -> (Arc<JsonValue>, Arc<str>) {
+        (self.value, self.normalized)
+    }
+}
+
+impl Deref for TransactionJson {
+    type Target = JsonValue;
+
+    fn deref(&self) -> &Self::Target {
+        self.value()
+    }
+}
+
+impl PartialEq<JsonValue> for TransactionJson {
+    fn eq(&self, other: &JsonValue) -> bool {
+        self.value() == other
+    }
+}
+
+impl PartialEq<TransactionJson> for JsonValue {
+    fn eq(&self, other: &TransactionJson) -> bool {
+        self == other.value()
+    }
+}
+
+impl fmt::Display for TransactionJson {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.normalized())
+    }
+}
+
+impl Serialize for TransactionJson {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        self.value.serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for TransactionJson {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let value = JsonValue::deserialize(deserializer)?;
+        Self::from_value(value, "transaction JSON").map_err(serde::de::Error::custom)
+    }
+}
+
+/// State row accepted at the transaction write boundary.
 ///
-/// Write frontends produce this shape after decoding their own surface. The
-/// transaction later assigns generated fields and turns it into a
-/// `StagedStateRow`.
+/// External SQL/provider code must parse any textual JSON before constructing
+/// this type. The transaction receives `TransactionJson`, applies schema
+/// defaults and identity derivation, then prepares JSON refs in
+/// `PreparedStateRow` without serializing already-normalized JSON again.
 ///
 /// SQL providers stage semantic rows, not final storage rows. INSERT providers
 /// may omit defaulted snapshot fields and leave `entity_id` unset when the
@@ -20,14 +119,13 @@ use crate::RowMetadata;
 /// existing row. Raw `lix_state` snapshot updates are replacement writes, not
 /// implicit patches.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
-pub(crate) struct StageRow {
+pub(crate) struct TransactionWriteRow {
     pub(crate) entity_id: Option<EntityIdentity>,
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
-    pub(crate) snapshot_content: Option<String>,
-    pub(crate) metadata: Option<RowMetadata>,
-    pub(crate) origin: Option<StageRowOrigin>,
-    pub(crate) schema_version: String,
+    pub(crate) snapshot: Option<TransactionJson>,
+    pub(crate) metadata: Option<TransactionJson>,
+    pub(crate) origin: Option<TransactionWriteOrigin>,
     pub(crate) created_at: Option<String>,
     pub(crate) updated_at: Option<String>,
     pub(crate) global: bool,
@@ -37,7 +135,7 @@ pub(crate) struct StageRow {
     pub(crate) version_id: String,
 }
 
-impl StageRow {
+impl TransactionWriteRow {
     pub(crate) fn schema_scope_version_id(&self) -> &str {
         if self.global {
             crate::GLOBAL_VERSION_ID
@@ -54,14 +152,14 @@ impl StageRow {
 /// but error messages should stay in the vocabulary of the logical operation
 /// when the caller did not write the physical state schema directly.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
-pub(crate) struct StageRowOrigin {
+pub(crate) struct TransactionWriteOrigin {
     pub(crate) surface: String,
-    pub(crate) operation: StageWriteOperation,
+    pub(crate) operation: TransactionWriteOperation,
     pub(crate) primary_key: Option<LogicalPrimaryKey>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
-pub(crate) enum StageWriteOperation {
+pub(crate) enum TransactionWriteOperation {
     Insert,
     Update,
     Delete,
@@ -73,9 +171,9 @@ pub(crate) struct LogicalPrimaryKey {
     pub(crate) values: Vec<String>,
 }
 
-/// Incoming file payload paired with staged filesystem rows.
+/// Incoming file payload paired with transaction write rows.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct StageFileData {
+pub(crate) struct TransactionFileData {
     pub(crate) file_id: String,
     pub(crate) version_id: String,
     pub(crate) untracked: bool,
@@ -88,55 +186,110 @@ pub(crate) struct StageFileData {
 /// changelog fact. The target commit references that existing change id and
 /// writes a target-version projection row without appending a copied change.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct StageAdoptedChange {
+pub(crate) struct TransactionAdoptedChange {
     pub(crate) version_id: String,
     pub(crate) change_id: String,
-    pub(crate) projected_row: TrackedStateRow,
+    pub(crate) projected_row: MaterializedTrackedStateRow,
+}
+
+/// One decoded write batch accepted by the transaction boundary.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum TransactionWrite {
+    Rows {
+        mode: TransactionWriteMode,
+        rows: Vec<TransactionWriteRow>,
+    },
+    RowsWithFileData {
+        mode: TransactionWriteMode,
+        rows: Vec<TransactionWriteRow>,
+        file_data: Vec<TransactionFileData>,
+        count: u64,
+    },
+    AdoptedChanges {
+        changes: Vec<TransactionAdoptedChange>,
+    },
 }
 
-/// One decoded write batch before transaction hydration.
+/// One decoded write batch after semantic normalization and JSON preparation.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) enum StageWrite {
+pub(crate) enum PreparedTransactionWrite {
     Rows {
-        mode: StageWriteMode,
-        rows: Vec<StageRow>,
+        mode: TransactionWriteMode,
+        rows: Vec<PreparedStateRow>,
     },
     RowsWithFileData {
-        mode: StageWriteMode,
-        rows: Vec<StageRow>,
-        file_data: Vec<StageFileData>,
+        mode: TransactionWriteMode,
+        rows: Vec<PreparedStateRow>,
+        file_data: Vec<TransactionFileData>,
         count: u64,
     },
     AdoptedChanges {
-        changes: Vec<StageAdoptedChange>,
+        rows: Vec<PreparedAdoptedStateRow>,
     },
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub(crate) enum StageWriteMode {
+pub(crate) enum TransactionWriteMode {
     Insert,
     Replace,
 }
 
-/// Result returned after staging a decoded write batch.
+/// Result returned after the transaction accepts a write batch.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct StageWriteOutcome {
+pub(crate) struct TransactionWriteOutcome {
     pub(crate) count: u64,
 }
 
-/// Transaction-hydrated state row.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct StageJson {
+    pub(crate) value: Arc<serde_json::Value>,
+    pub(crate) normalized: Arc<str>,
+    pub(crate) json_ref: JsonRef,
+}
+
+impl StageJson {
+    pub(crate) fn materialize(&self) -> String {
+        self.normalized.as_ref().to_string()
+    }
+}
+
+pub(crate) fn stage_json_from_value(
+    value: TransactionJson,
+    _context: &str,
+) -> Result<StageJson, LixError> {
+    let (value, normalized) = value.into_parts();
+    let json_ref = JsonRef::for_content(normalized.as_bytes());
+    Ok(StageJson {
+        value,
+        normalized,
+        json_ref,
+    })
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub(crate) struct PreparedRowFacts {
+    /// Placeholder for the next cut: row-derived constraint facts will be
+    /// computed once during normalization and consumed by validation.
+    pub(crate) _sealed: (),
+}
+
+/// Prepared state row owned by the transaction write buffer.
 ///
-/// This is the row form owned by a write transaction after generated fields
-/// have been assigned but before the rows are durably flushed.
+/// This is the first boundary that owns `StageJson`: JSON has been normalized
+/// and assigned a content-addressed `JsonRef`. Durable placement belongs to the
+/// JSON store at batch staging time, not row preparation time.
+/// Storage owners must receive only the ref-backed row forms derived from this
+/// type.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct StagedStateRow {
+pub(crate) struct PreparedStateRow {
+    pub(crate) schema_plan_id: SchemaPlanId,
+    pub(crate) facts: PreparedRowFacts,
     pub(crate) entity_id: EntityIdentity,
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
-    pub(crate) snapshot_content: Option<String>,
-    pub(crate) metadata: Option<RowMetadata>,
-    pub(crate) origin: Option<StageRowOrigin>,
-    pub(crate) schema_version: String,
+    pub(crate) snapshot: Option<StageJson>,
+    pub(crate) metadata: Option<StageJson>,
+    pub(crate) origin: Option<TransactionWriteOrigin>,
     pub(crate) created_at: String,
     pub(crate) updated_at: String,
     pub(crate) global: bool,
@@ -146,25 +299,16 @@ pub(crate) struct StagedStateRow {
     pub(crate) version_id: String,
 }
 
-impl StagedStateRow {
-    pub(crate) fn schema_scope_version_id(&self) -> &str {
-        if self.global {
-            crate::GLOBAL_VERSION_ID
-        } else {
-            self.version_id.as_str()
-        }
-    }
-}
-
 /// Transaction-hydrated projection for an adopted canonical change.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct StagedAdoptedStateRow {
+pub(crate) struct PreparedAdoptedStateRow {
+    pub(crate) schema_plan_id: SchemaPlanId,
+    pub(crate) facts: PreparedRowFacts,
     pub(crate) entity_id: EntityIdentity,
     pub(crate) schema_key: String,
     pub(crate) file_id: Option<String>,
-    pub(crate) snapshot_content: Option<String>,
-    pub(crate) metadata: Option<RowMetadata>,
-    pub(crate) schema_version: String,
+    pub(crate) snapshot: Option<StageJson>,
+    pub(crate) metadata: Option<StageJson>,
     pub(crate) created_at: String,
     pub(crate) updated_at: String,
     pub(crate) global: bool,
@@ -173,25 +317,16 @@ pub(crate) struct StagedAdoptedStateRow {
     pub(crate) version_id: String,
 }
 
-impl StagedAdoptedStateRow {
-    pub(crate) fn schema_scope_version_id(&self) -> &str {
-        if self.global {
-            crate::GLOBAL_VERSION_ID
-        } else {
-            self.version_id.as_str()
-        }
-    }
-}
-
-impl From<StagedStateRow> for LiveStateRow {
-    fn from(row: StagedStateRow) -> Self {
-        LiveStateRow {
+impl From<PreparedStateRow> for MaterializedLiveStateRow {
+    fn from(row: PreparedStateRow) -> Self {
+        let deleted = row.snapshot.is_none();
+        MaterializedLiveStateRow {
             entity_id: row.entity_id,
             schema_key: row.schema_key,
             file_id: row.file_id,
-            snapshot_content: row.snapshot_content,
-            metadata: row.metadata,
-            schema_version: row.schema_version,
+            snapshot_content: row.snapshot.map(|snapshot| snapshot.materialize()),
+            metadata: row.metadata.map(|metadata| metadata.materialize()),
+            deleted,
             created_at: row.created_at,
             updated_at: row.updated_at,
             global: row.global,
@@ -203,15 +338,15 @@ impl From<StagedStateRow> for LiveStateRow {
     }
 }
 
-impl From<&StagedStateRow> for LiveStateRow {
-    fn from(row: &StagedStateRow) -> Self {
-        LiveStateRow {
+impl From<&PreparedStateRow> for MaterializedLiveStateRow {
+    fn from(row: &PreparedStateRow) -> Self {
+        MaterializedLiveStateRow {
             entity_id: row.entity_id.clone(),
             schema_key: row.schema_key.clone(),
             file_id: row.file_id.clone(),
-            snapshot_content: row.snapshot_content.clone(),
-            metadata: row.metadata.clone(),
-            schema_version: row.schema_version.clone(),
+            snapshot_content: row.snapshot.as_ref().map(StageJson::materialize),
+            metadata: row.metadata.as_ref().map(StageJson::materialize),
+            deleted: row.snapshot.is_none(),
             created_at: row.created_at.clone(),
             updated_at: row.updated_at.clone(),
             global: row.global,
@@ -223,15 +358,16 @@ impl From<&StagedStateRow> for LiveStateRow {
     }
 }
 
-impl From<StagedAdoptedStateRow> for LiveStateRow {
-    fn from(row: StagedAdoptedStateRow) -> Self {
-        LiveStateRow {
+impl From<PreparedAdoptedStateRow> for MaterializedLiveStateRow {
+    fn from(row: PreparedAdoptedStateRow) -> Self {
+        let deleted = row.snapshot.is_none();
+        MaterializedLiveStateRow {
             entity_id: row.entity_id,
             schema_key: row.schema_key,
             file_id: row.file_id,
-            snapshot_content: row.snapshot_content,
-            metadata: row.metadata,
-            schema_version: row.schema_version,
+            snapshot_content: row.snapshot.map(|snapshot| snapshot.materialize()),
+            metadata: row.metadata.map(|metadata| metadata.materialize()),
+            deleted,
             created_at: row.created_at,
             updated_at: row.updated_at,
             global: row.global,
@@ -243,36 +379,15 @@ impl From<StagedAdoptedStateRow> for LiveStateRow {
     }
 }
 
-impl From<&StagedAdoptedStateRow> for LiveStateRow {
-    fn from(row: &StagedAdoptedStateRow) -> Self {
-        LiveStateRow {
-            entity_id: row.entity_id.clone(),
-            schema_key: row.schema_key.clone(),
-            file_id: row.file_id.clone(),
-            snapshot_content: row.snapshot_content.clone(),
-            metadata: row.metadata.clone(),
-            schema_version: row.schema_version.clone(),
-            created_at: row.created_at.clone(),
-            updated_at: row.updated_at.clone(),
-            global: row.global,
-            change_id: Some(row.change_id.clone()),
-            commit_id: Some(row.commit_id.clone()),
-            untracked: false,
-            version_id: row.version_id.clone(),
-        }
-    }
-}
-
-impl From<&StagedAdoptedStateRow> for StagedStateRow {
-    fn from(row: &StagedAdoptedStateRow) -> Self {
-        StagedStateRow {
+impl From<&PreparedAdoptedStateRow> for MaterializedLiveStateRow {
+    fn from(row: &PreparedAdoptedStateRow) -> Self {
+        MaterializedLiveStateRow {
             entity_id: row.entity_id.clone(),
             schema_key: row.schema_key.clone(),
             file_id: row.file_id.clone(),
-            snapshot_content: row.snapshot_content.clone(),
-            metadata: row.metadata.clone(),
-            origin: None,
-            schema_version: row.schema_version.clone(),
+            snapshot_content: row.snapshot.as_ref().map(StageJson::materialize),
+            metadata: row.metadata.as_ref().map(StageJson::materialize),
+            deleted: row.snapshot.is_none(),
             created_at: row.created_at.clone(),
             updated_at: row.updated_at.clone(),
             global: row.global,
@@ -284,15 +399,16 @@ impl From<&StagedAdoptedStateRow> for StagedStateRow {
     }
 }
 
-impl From<StagedStateRow> for MaterializedUntrackedStateRow {
-    fn from(row: StagedStateRow) -> Self {
+impl From<PreparedStateRow> for MaterializedUntrackedStateRow {
+    fn from(row: PreparedStateRow) -> Self {
+        let deleted = row.snapshot.is_none();
         MaterializedUntrackedStateRow {
             entity_id: row.entity_id,
             schema_key: row.schema_key,
             file_id: row.file_id,
-            snapshot_content: row.snapshot_content,
-            metadata: row.metadata,
-            schema_version: row.schema_version,
+            snapshot_content: row.snapshot.map(|snapshot| snapshot.materialize()),
+            metadata: row.metadata.map(|metadata| metadata.materialize()),
+            deleted,
             created_at: row.created_at,
             updated_at: row.updated_at,
             global: row.global,
@@ -310,23 +426,16 @@ impl From<StagedStateRow> for MaterializedUntrackedStateRow {
 pub(crate) struct StagedCommitMembers {
     pub(crate) commit_id: String,
     pub(crate) commit_change_id: String,
-    pub(crate) change_set_id: String,
     pub(crate) created_at: String,
     pub(crate) change_ids: BTreeSet<String>,
     pub(crate) allow_empty: bool,
 }
 
 impl StagedCommitMembers {
-    pub(crate) fn new(
-        commit_id: String,
-        commit_change_id: String,
-        change_set_id: String,
-        created_at: String,
-    ) -> Self {
+    pub(crate) fn new(commit_id: String, commit_change_id: String, created_at: String) -> Self {
         Self {
             commit_id,
             commit_change_id,
-            change_set_id,
             created_at,
             change_ids: BTreeSet::new(),
             allow_empty: false,