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

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

@@ -0,0 +1,215 @@
+use crate::entity_identity::EntityIdentity;
+use crate::json_store::JsonRef;
+
+/// Physical append/locality unit for commit metadata and derived commit SQL
+/// surfaces.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub(crate) struct Commit {
+    pub(crate) id: String,
+    pub(crate) change_id: String,
+    pub(crate) parent_ids: Vec<String>,
+    pub(crate) author_account_ids: Vec<String>,
+    pub(crate) created_at: String,
+    pub(crate) change_pack_count: u32,
+    pub(crate) membership_pack_count: u32,
+}
+
+impl Commit {
+    pub(crate) fn as_ref(&self) -> StoredCommitRef<'_> {
+        StoredCommitRef {
+            id: &self.id,
+            change_id: &self.change_id,
+            parent_ids: &self.parent_ids,
+            author_account_ids: &self.author_account_ids,
+            created_at: &self.created_at,
+            change_pack_count: self.change_pack_count,
+            membership_pack_count: self.membership_pack_count,
+        }
+    }
+}
+
+/// Zero-copy view of stored [`Commit`] bytes.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct StoredCommitRef<'a> {
+    pub(crate) id: &'a str,
+    pub(crate) change_id: &'a str,
+    pub(crate) parent_ids: &'a [String],
+    pub(crate) author_account_ids: &'a [String],
+    pub(crate) created_at: &'a str,
+    pub(crate) change_pack_count: u32,
+    pub(crate) membership_pack_count: u32,
+}
+
+/// Zero-copy view of a logical commit supplied before physical packing.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct CommitDraftRef<'a> {
+    pub(crate) id: &'a str,
+    pub(crate) change_id: &'a str,
+    pub(crate) parent_ids: &'a [String],
+    pub(crate) author_account_ids: &'a [String],
+    pub(crate) created_at: &'a str,
+}
+
+/// Logical entity mutation fact stored in a commit change pack.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub(crate) struct Change {
+    pub(crate) id: String,
+    pub(crate) entity_id: EntityIdentity,
+    pub(crate) schema_key: String,
+    pub(crate) file_id: Option<String>,
+    pub(crate) snapshot_ref: Option<JsonRef>,
+    pub(crate) metadata_ref: Option<JsonRef>,
+    pub(crate) created_at: String,
+}
+
+/// Read-boundary view of a commit-store change with JSON refs resolved.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct MaterializedChange {
+    pub(crate) id: String,
+    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<String>,
+    pub(crate) created_at: String,
+}
+
+/// Commit-store change plus the physical pack that owns its JSON payloads.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct LocatedChange {
+    pub(crate) record: Change,
+    pub(crate) source_commit_id: String,
+    pub(crate) source_pack_id: u32,
+}
+
+impl Change {
+    pub(crate) fn as_ref(&self) -> ChangeRef<'_> {
+        ChangeRef {
+            id: &self.id,
+            entity_id: &self.entity_id,
+            schema_key: &self.schema_key,
+            file_id: self.file_id.as_deref(),
+            snapshot_ref: self.snapshot_ref.as_ref(),
+            metadata_ref: self.metadata_ref.as_ref(),
+            created_at: &self.created_at,
+        }
+    }
+}
+
+/// Zero-copy view of [`Change`].
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct ChangeRef<'a> {
+    pub(crate) id: &'a str,
+    pub(crate) entity_id: &'a EntityIdentity,
+    pub(crate) schema_key: &'a str,
+    pub(crate) file_id: Option<&'a str>,
+    pub(crate) snapshot_ref: Option<&'a JsonRef>,
+    pub(crate) metadata_ref: Option<&'a JsonRef>,
+    pub(crate) created_at: &'a str,
+}
+
+/// Logical scan request for the `lix_change` SQL surface over commit_store.
+#[derive(Debug, Clone, Default)]
+pub(crate) struct ChangeScanRequest {
+    pub(crate) limit: Option<usize>,
+}
+
+/// Commit-local physical pack of newly authored change payloads.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub(crate) struct ChangePack {
+    pub(crate) commit_id: String,
+    pub(crate) pack_id: u32,
+    pub(crate) changes: Vec<Change>,
+}
+
+impl ChangePack {
+    pub(crate) fn as_view(&self) -> ChangePackView<'_> {
+        ChangePackView {
+            commit_id: &self.commit_id,
+            pack_id: self.pack_id,
+            changes: &self.changes,
+        }
+    }
+}
+
+/// Zero-copy view for a decoded [`ChangePack`].
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct ChangePackView<'a> {
+    pub(crate) commit_id: &'a str,
+    pub(crate) pack_id: u32,
+    pub(crate) changes: &'a [Change],
+}
+
+/// Storage location of an existing change payload.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub(crate) struct ChangeLocator {
+    pub(crate) source_commit_id: String,
+    pub(crate) source_pack_id: u32,
+    pub(crate) source_ordinal: u32,
+    pub(crate) change_id: String,
+}
+
+impl ChangeLocator {
+    pub(crate) fn as_ref(&self) -> ChangeLocatorRef<'_> {
+        ChangeLocatorRef {
+            source_commit_id: &self.source_commit_id,
+            source_pack_id: self.source_pack_id,
+            source_ordinal: self.source_ordinal,
+            change_id: &self.change_id,
+        }
+    }
+}
+
+/// Zero-copy view of [`ChangeLocator`].
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct ChangeLocatorRef<'a> {
+    pub(crate) source_commit_id: &'a str,
+    pub(crate) source_pack_id: u32,
+    pub(crate) source_ordinal: u32,
+    pub(crate) change_id: &'a str,
+}
+
+/// Exact lookup entry for a derived-surface-visible change id.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub(crate) enum ChangeIndexEntry {
+    CommitHeader {
+        commit_id: String,
+        change_id: String,
+    },
+    PackedChange {
+        locator: ChangeLocator,
+    },
+}
+
+/// Commit-local physical pack of adopted/shared membership locators.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub(crate) struct MembershipPack {
+    pub(crate) commit_id: String,
+    pub(crate) pack_id: u32,
+    pub(crate) members: Vec<ChangeLocator>,
+}
+
+impl MembershipPack {
+    pub(crate) fn as_view(&self) -> MembershipPackView<'_> {
+        MembershipPackView {
+            commit_id: &self.commit_id,
+            pack_id: self.pack_id,
+            members: &self.members,
+        }
+    }
+}
+
+/// Zero-copy view for a decoded [`MembershipPack`].
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct MembershipPackView<'a> {
+    pub(crate) commit_id: &'a str,
+    pub(crate) pack_id: u32,
+    pub(crate) members: &'a [ChangeLocator],
+}
+
+/// Locators produced while staging a commit.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct StagedCommitStoreCommit {
+    pub(crate) authored_locators: Vec<ChangeLocator>,
+    pub(crate) adopted_locators: Vec<ChangeLocator>,
+}

package/dist-engine-src/src/common/identity.rs

@@ -13,10 +13,7 @@ macro_rules! canonical_identity_type {
         impl $name {
             pub fn new(value: impl Into<String>) -> Result<Self, LixError> {
                 let value = value.into();
-                if value.is_empty() {
-                    return Err(LixError::unknown(format!("{} must be non-empty", $label)));
-                }
-                Ok(Self(value))
+                validate_non_empty_identity_value($label, value).map(Self)
             }
 
             pub fn as_str(&self) -> &str {
@@ -113,9 +110,22 @@ canonical_identity_type!(EntityId, "entity_id");
 canonical_identity_type!(FileId, "file_id");
 canonical_identity_type!(VersionId, "version_id");
 canonical_identity_type!(CanonicalSchemaKey, "schema_key");
-canonical_identity_type!(CanonicalSchemaVersion, "schema_version");
 canonical_identity_type!(CanonicalPluginKey, "plugin_key");
 
+pub(crate) fn validate_non_empty_identity_value(
+    label: &str,
+    value: impl Into<String>,
+) -> Result<String, LixError> {
+    let value = value.into();
+    if value.is_empty() {
+        return Err(LixError::new(
+            LixError::CODE_INVALID_PARAM,
+            format!("{label} must be non-empty"),
+        ));
+    }
+    Ok(value)
+}
+
 pub(crate) fn json_pointer_get<'a>(
     value: &'a serde_json::Value,
     pointer: &[String],

package/dist-engine-src/src/common/json_pointer.rs

@@ -0,0 +1,67 @@
+use crate::LixError;
+
+pub(crate) 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()
+}
+
+pub(crate) 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 top_level_property_name(pointer: &str) -> Result<Option<String>, LixError> {
+    if pointer.is_empty() {
+        return Ok(None);
+    }
+    if !pointer.starts_with('/') {
+        return Err(LixError::new(
+            LixError::CODE_SCHEMA_DEFINITION,
+            format!("invalid JSON pointer '{pointer}'"),
+        ));
+    }
+    let segment = pointer[1..].split('/').next().unwrap_or_default();
+    Ok(Some(decode_json_pointer_segment(segment)?))
+}
+
+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 != '~' {
+            out.push(ch);
+            continue;
+        }
+        match chars.next() {
+            Some('0') => out.push('~'),
+            Some('1') => out.push('/'),
+            _ => {
+                return Err(LixError::new(
+                    LixError::CODE_SCHEMA_DEFINITION,
+                    "invalid JSON pointer escape",
+                ))
+            }
+        }
+    }
+    Ok(out)
+}

package/dist-engine-src/src/common/metadata.rs

@@ -1,28 +1,33 @@
-use serde_json::Value as JsonValue;
-
 use crate::LixError;
 
-pub(crate) type RowMetadata = JsonValue;
-
 pub(crate) fn parse_row_metadata(
     value: &str,
     context: impl AsRef<str>,
-) -> Result<RowMetadata, LixError> {
-    let metadata = serde_json::from_str::<JsonValue>(value).map_err(|error| {
+) -> Result<String, LixError> {
+    let metadata = parse_row_metadata_value(value, context)?;
+    Ok(serde_json::to_string(&metadata).expect("serde_json::Value metadata serializes"))
+}
+
+pub(crate) fn parse_row_metadata_value(
+    value: &str,
+    context: impl AsRef<str>,
+) -> Result<serde_json::Value, LixError> {
+    let metadata = serde_json::from_str::<serde_json::Value>(value).map_err(|error| {
         LixError::new(
             "LIX_ERROR_INVALID_JSON",
             format!("{} metadata is invalid JSON: {error}", context.as_ref()),
         )
     })?;
-    validate_row_metadata(metadata, context)
+    validate_row_metadata(&metadata, context)?;
+    Ok(metadata)
 }
 
 pub(crate) fn validate_row_metadata(
-    metadata: RowMetadata,
+    metadata: &serde_json::Value,
     context: impl AsRef<str>,
-) -> Result<RowMetadata, LixError> {
+) -> Result<(), LixError> {
     if metadata.is_object() {
-        return Ok(metadata);
+        return Ok(());
     }
     Err(LixError::new(
         LixError::CODE_SCHEMA_VALIDATION,
@@ -30,6 +35,6 @@ pub(crate) fn validate_row_metadata(
     ))
 }
 
-pub(crate) fn serialize_row_metadata(metadata: &RowMetadata) -> String {
-    serde_json::to_string(metadata).expect("serde_json::Value metadata serializes")
+pub(crate) fn serialize_row_metadata(metadata: &String) -> String {
+    metadata.clone()
 }

package/dist-engine-src/src/common/mod.rs

@@ -2,6 +2,7 @@ pub(crate) mod error;
 pub(crate) mod fingerprint;
 pub(crate) mod fs_path;
 pub(crate) mod identity;
+pub(crate) mod json_pointer;
 pub(crate) mod metadata;
 pub(crate) mod types;
 pub(crate) mod wire;
@@ -12,12 +13,11 @@ pub(crate) use fs_path::{
     directory_ancestor_paths, directory_name_from_path, normalize_directory_path,
     normalize_path_segment, parent_directory_path, ParsedFilePath,
 };
-pub(crate) use identity::json_pointer_get;
-pub use identity::{
-    CanonicalPluginKey, CanonicalSchemaKey, CanonicalSchemaVersion, EntityId, FileId, VersionId,
-};
+pub(crate) use identity::{json_pointer_get, validate_non_empty_identity_value};
+pub use identity::{CanonicalPluginKey, CanonicalSchemaKey, EntityId, FileId, VersionId};
+pub(crate) use json_pointer::{format_json_pointer, parse_json_pointer, top_level_property_name};
 pub(crate) use metadata::{
-    parse_row_metadata, serialize_row_metadata, validate_row_metadata, RowMetadata,
+    parse_row_metadata, parse_row_metadata_value, serialize_row_metadata, validate_row_metadata,
 };
 pub use types::{LixNotice, NullableKeyFilter, SqlQueryResult, Value, WriteReceipt};
 pub use wire::{WireQueryResult, WireValue};