@lix-js/sdk 0.6.0-preview.1 → 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/error.rs

@@ -0,0 +1,313 @@
+use serde_json::{json, Value as JsonValue};
+
+/// Structured error type surfaced by Lix to every SDK binding.
+///
+/// Carries a machine-readable [`code`](Self::code), a human-readable
+/// [`message`](Self::message), and an optional [`hint`](Self::hint)
+/// suggesting how to recover. Hints follow the Postgres/rustc convention:
+/// `message` states what went wrong in factual terms, and `hint` offers a
+/// possible fix when one is known.
+///
+/// ```
+/// use lix_engine::LixError;
+///
+/// let err = LixError::new(
+///     "LIX_ERROR_UNSUPPORTED_WRITE_EXPRESSION",
+///     "json(...) is not supported",
+/// )
+/// .with_hint("use lix_json('...') instead");
+///
+/// assert_eq!(err.hint(), Some("use lix_json('...') instead"));
+/// ```
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LixError {
+    pub code: String,
+    pub message: String,
+    pub hint: Option<String>,
+    pub details: Option<JsonValue>,
+}
+
+impl LixError {
+    /// True fallback — use when no more specific category fits. Producing
+    /// sites should prefer the categorized codes below whenever possible;
+    /// the SDK contract is that `LIX_ERROR_UNKNOWN` is the *last* resort,
+    /// never the default.
+    pub const CODE_UNKNOWN: &'static str = "LIX_ERROR_UNKNOWN";
+
+    /// SQL text could not be parsed.
+    pub const CODE_PARSE_ERROR: &'static str = "LIX_PARSE_ERROR";
+
+    /// A SQL function name could not be resolved.
+    pub const CODE_UDF_NOT_FOUND: &'static str = "LIX_UDF_NOT_FOUND";
+
+    /// A SQL expression or function argument had an incompatible type.
+    pub const CODE_TYPE_MISMATCH: &'static str = "LIX_TYPE_MISMATCH";
+
+    /// A Lix JSON path argument used another dialect's path language instead
+    /// of Lix's canonical variadic key/index segments.
+    pub const CODE_INVALID_JSON_PATH: &'static str = "LIX_INVALID_JSON_PATH";
+
+    /// SQL syntax belongs to another dialect and is outside the Lix SQL
+    /// surface.
+    pub const CODE_DIALECT_UNSUPPORTED: &'static str = "LIX_DIALECT_UNSUPPORTED";
+
+    /// SQL parameters could not be bound to placeholders.
+    pub const CODE_BINDING_ERROR: &'static str = "LIX_BINDING_ERROR";
+
+    /// A caller supplied an invalid SQL parameter value or parameter list.
+    pub const CODE_INVALID_PARAM: &'static str = "LIX_INVALID_PARAM";
+
+    /// A SQL table or view name could not be resolved.
+    pub const CODE_TABLE_NOT_FOUND: &'static str = "LIX_TABLE_NOT_FOUND";
+
+    /// A SQL column name could not be resolved in the available projection.
+    pub const CODE_COLUMN_NOT_FOUND: &'static str = "LIX_COLUMN_NOT_FOUND";
+
+    /// A SQL write violated a primary-key, unique, NOT NULL, or other
+    /// relational constraint.
+    pub const CODE_CONSTRAINT_VIOLATION: &'static str = "LIX_CONSTRAINT_VIOLATION";
+
+    /// A SQL write targeted a read-only internal/component surface.
+    pub const CODE_READ_ONLY: &'static str = "LIX_ERROR_READ_ONLY";
+
+    /// A history table was queried without an explicit commit/version range.
+    pub const CODE_HISTORY_FILTER_REQUIRED: &'static str = "LIX_HISTORY_FILTER_REQUIRED";
+
+    /// SQL syntax is valid, but the feature is intentionally outside the Lix
+    /// SQL surface.
+    pub const CODE_UNSUPPORTED_SQL: &'static str = "LIX_UNSUPPORTED_SQL";
+
+    /// SQL planning succeeded far enough to produce a physical runtime shape
+    /// that the current engine target cannot execute safely.
+    pub const CODE_UNSUPPORTED_SQL_RUNTIME_PLAN: &'static str = "LIX_UNSUPPORTED_SQL_RUNTIME_PLAN";
+
+    /// Storage/backend IO failed while executing an operation.
+    pub const CODE_STORAGE_ERROR: &'static str = "LIX_STORAGE_ERROR";
+
+    /// An internal engine invariant failed.
+    pub const CODE_INTERNAL_ERROR: &'static str = "LIX_INTERNAL_ERROR";
+
+    /// Write-time failure where user data did not conform to a registered
+    /// schema (type mismatch, missing required field, pattern violation,
+    /// additionalProperties, etc.). Raised from the JSON-Schema validator
+    /// run over a candidate row's snapshot.
+    pub const CODE_SCHEMA_VALIDATION: &'static str = "LIX_ERROR_SCHEMA_VALIDATION";
+
+    /// A foreign-key constraint could not be satisfied. Covers both the
+    /// insert-side "no matching target row" failure and the delete-side
+    /// "still referenced" (restrict) failure.
+    pub const CODE_FOREIGN_KEY: &'static str = "LIX_ERROR_FOREIGN_KEY";
+
+    /// A row references a non-null `file_id` that has no matching `lix_file`
+    /// descriptor in the same effective version scope.
+    pub const CODE_FILE_NOT_FOUND: &'static str = "LIX_ERROR_FILE_NOT_FOUND";
+
+    /// A primary-key or `x-lix-unique` constraint was violated — another
+    /// row already owns the value(s) for the declared pointer group.
+    pub const CODE_UNIQUE: &'static str = "LIX_ERROR_UNIQUE";
+
+    /// An `INSERT ... VALUES (...)` expression is not supported by the
+    /// public write surface (e.g. `json(...)`, subqueries, arbitrary SQL
+    /// expressions). Users should wrap inline JSON with `lix_json(...)`.
+    pub const CODE_UNSUPPORTED_WRITE_EXPRESSION: &'static str =
+        "LIX_ERROR_UNSUPPORTED_WRITE_EXPRESSION";
+
+    /// The schema JSON itself (the *definition*, not a row against it) is
+    /// malformed — a missing `x-lix-key`, a JSON-Pointer without the
+    /// leading slash, a reserved-namespace collision, or any other
+    /// meta-schema validation failure.
+    pub const CODE_SCHEMA_DEFINITION: &'static str = "LIX_ERROR_SCHEMA_DEFINITION";
+
+    /// The logical Lix handle/session has been closed and cannot run further
+    /// operations. Close is a resource-release lifecycle boundary, not a
+    /// durability boundary.
+    pub const CODE_CLOSED: &'static str = "LIX_ERROR_CLOSED";
+
+    /// A merge found incompatible changes to the same tracked-state identity.
+    pub const CODE_MERGE_CONFLICT: &'static str = "LIX_MERGE_CONFLICT";
+
+    /// A caller referenced a version id that has no matching version ref.
+    pub const CODE_VERSION_NOT_FOUND: &'static str = "LIX_VERSION_NOT_FOUND";
+
+    /// A staged row's storage scope flags disagree, such as a global row not
+    /// using the reserved global version id.
+    pub const CODE_INVALID_STORAGE_SCOPE: &'static str = "LIX_ERROR_INVALID_STORAGE_SCOPE";
+
+    /// Merge graph analysis found multiple equally valid merge bases.
+    pub const CODE_AMBIGUOUS_MERGE_BASE: &'static str = "LIX_AMBIGUOUS_MERGE_BASE";
+
+    /// A merge request is well-formed but nonsensical for the commit graph,
+    /// such as merging a version into itself.
+    pub const CODE_INVALID_MERGE: &'static str = "LIX_INVALID_MERGE";
+
+    pub fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
+        Self {
+            code: code.into(),
+            message: message.into(),
+            hint: None,
+            details: None,
+        }
+    }
+
+    pub fn unknown(message: impl Into<String>) -> Self {
+        Self::new("LIX_ERROR_UNKNOWN", message)
+    }
+
+    pub fn version_not_found(
+        version_id: impl Into<String>,
+        operation: impl Into<String>,
+        role: impl Into<String>,
+    ) -> Self {
+        let version_id = version_id.into();
+        let operation = operation.into();
+        let role = role.into();
+        Self::new(
+            Self::CODE_VERSION_NOT_FOUND,
+            format!("version '{version_id}' was not found"),
+        )
+        .with_details(json!({
+            "version_id": version_id,
+            "operation": operation,
+            "role": role,
+        }))
+    }
+
+    pub fn ambiguous_merge_base(
+        left_commit_id: impl Into<String>,
+        right_commit_id: impl Into<String>,
+        candidates: Vec<String>,
+    ) -> Self {
+        let left_commit_id = left_commit_id.into();
+        let right_commit_id = right_commit_id.into();
+        Self::new(
+            Self::CODE_AMBIGUOUS_MERGE_BASE,
+            format!("ambiguous merge base between '{left_commit_id}' and '{right_commit_id}'"),
+        )
+        .with_details(json!({
+            "left_commit_id": left_commit_id,
+            "right_commit_id": right_commit_id,
+            "candidates": candidates,
+        }))
+    }
+
+    pub fn invalid_self_merge(version_id: impl Into<String>) -> Self {
+        let version_id = version_id.into();
+        Self::new(
+            Self::CODE_INVALID_MERGE,
+            format!("cannot merge version '{version_id}' into itself"),
+        )
+        .with_details(json!({
+            "operation": "merge_version",
+            "target_version_id": version_id,
+            "source_version_id": version_id,
+        }))
+    }
+
+    /// Attach a hint to this error. Consumers render hints alongside the
+    /// primary message (e.g. a CLI prints them as `hint: <text>`).
+    ///
+    /// ```
+    /// use lix_engine::LixError;
+    ///
+    /// let err = LixError::new("CODE", "boom").with_hint("try this");
+    /// assert_eq!(err.hint(), Some("try this"));
+    /// ```
+    pub fn with_hint(mut self, hint: impl Into<String>) -> Self {
+        self.hint = Some(hint.into());
+        self
+    }
+
+    /// Attach machine-readable details to this error.
+    pub fn with_details(mut self, details: JsonValue) -> Self {
+        self.details = Some(details);
+        self
+    }
+
+    /// Return the attached hint, if any.
+    ///
+    /// Returns `None` when no hint was attached at the error's producer
+    /// site. This is the accessor SDK consumers should prefer over
+    /// reading the `hint` field directly — it returns `Option<&str>`,
+    /// avoiding the need for `.as_deref()` at the call site.
+    ///
+    /// ```
+    /// use lix_engine::LixError;
+    ///
+    /// let without_hint = LixError::new("CODE", "boom");
+    /// assert_eq!(without_hint.hint(), None);
+    ///
+    /// let with_hint = LixError::new("CODE", "boom").with_hint("fix it");
+    /// assert_eq!(with_hint.hint(), Some("fix it"));
+    /// ```
+    pub fn hint(&self) -> Option<&str> {
+        self.hint.as_deref()
+    }
+
+    pub fn message_with_hint(&self) -> String {
+        match self.hint() {
+            Some(hint) => format!("{}\nhint: {hint}", self.message),
+            None => self.message.clone(),
+        }
+    }
+
+    pub fn format(&self) -> String {
+        let mut s = format!("code: {}\nmessage: {}", self.code, self.message);
+        if let Some(hint) = &self.hint {
+            s.push_str(&format!("\nhint: {hint}"));
+        }
+        s
+    }
+}
+
+impl std::fmt::Display for LixError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.format())
+    }
+}
+
+impl std::error::Error for LixError {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn format_without_hint_omits_hint_line() {
+        let err = LixError::new("LIX_ERROR_FOO", "something went wrong");
+        assert_eq!(
+            err.format(),
+            "code: LIX_ERROR_FOO\nmessage: something went wrong"
+        );
+        assert!(err.hint.is_none());
+    }
+
+    #[test]
+    fn format_with_hint_appends_hint_line() {
+        let err = LixError::new("LIX_ERROR_FOO", "something went wrong").with_hint("try the fix");
+        assert_eq!(
+            err.format(),
+            "code: LIX_ERROR_FOO\nmessage: something went wrong\nhint: try the fix"
+        );
+    }
+
+    #[test]
+    fn with_hint_is_chainable_and_replaces_prior_hint() {
+        let err = LixError::new("LIX_ERROR_FOO", "desc")
+            .with_hint("first")
+            .with_hint("second");
+        assert_eq!(err.hint.as_deref(), Some("second"));
+    }
+
+    #[test]
+    fn new_defaults_hint_to_none() {
+        let err = LixError::new("CODE", "desc");
+        assert_eq!(err.hint, None);
+    }
+
+    #[test]
+    fn unknown_defaults_hint_to_none() {
+        let err = LixError::unknown("desc");
+        assert_eq!(err.code, "LIX_ERROR_UNKNOWN");
+        assert_eq!(err.hint, None);
+    }
+}

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

@@ -0,0 +1,3 @@
+pub(crate) fn stable_content_fingerprint_hex(data: &[u8]) -> String {
+    blake3::hash(data).to_hex().to_string()
+}