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

package/dist-engine-src/src/schema_registry.rs

@@ -0,0 +1,294 @@
+use std::collections::BTreeMap;
+
+use serde_json::Value as JsonValue;
+
+use crate::live_state::LiveStateRow;
+use crate::live_state::{LiveStateFilter, LiveStateReader, LiveStateScanRequest};
+use crate::schema::schema_key_from_definition;
+use crate::{LixError, NullableKeyFilter, GLOBAL_VERSION_ID};
+
+const REGISTERED_SCHEMA_KEY: &str = "lix_registered_schema";
+
+/// Engine2 schema visibility boundary.
+///
+/// SQL planning receives a schema snapshot from live state. System schemas are
+/// seeded as ordinary `lix_registered_schema` rows during initialization, so
+/// runtime schema visibility has one source of truth.
+pub(crate) struct SchemaRegistry;
+
+impl SchemaRegistry {
+    pub(crate) fn new() -> Self {
+        Self
+    }
+
+    /// Loads schema definitions visible for SQL planning at `version_id`.
+    pub(crate) async fn visible_schemas<R>(
+        &self,
+        live_state: &R,
+        version_id: &str,
+    ) -> Result<Vec<JsonValue>, LixError>
+    where
+        R: LiveStateReader + ?Sized,
+    {
+        let mut schemas = BTreeMap::new();
+        for row in live_state
+            .scan_rows(&LiveStateScanRequest {
+                filter: LiveStateFilter {
+                    schema_keys: vec![REGISTERED_SCHEMA_KEY.to_string()],
+                    version_ids: vec![version_id.to_string()],
+                    file_ids: vec![NullableKeyFilter::Null],
+                    include_tombstones: false,
+                    ..LiveStateFilter::default()
+                },
+                ..LiveStateScanRequest::default()
+            })
+            .await?
+            .into_iter()
+            .filter(|row| version_scoped_schema_row_is_visible(row, version_id))
+        {
+            let Some((key, schema)) = decode_registered_schema_row(&row)? else {
+                continue;
+            };
+            upsert_latest_schema(&mut schemas, key, schema);
+        }
+        Ok(schemas.into_values().map(|(_, schema)| schema).collect())
+    }
+}
+
+fn version_scoped_schema_row_is_visible(row: &LiveStateRow, requested_version_id: &str) -> bool {
+    requested_version_id == GLOBAL_VERSION_ID || !row.global
+}
+
+fn upsert_latest_schema(
+    schemas: &mut BTreeMap<String, (crate::schema::SchemaKey, JsonValue)>,
+    key: crate::schema::SchemaKey,
+    schema: JsonValue,
+) {
+    let should_replace = schemas
+        .get(&key.schema_key)
+        .is_none_or(|(existing, _)| !schema_key_is_older(&key, existing));
+    if should_replace {
+        schemas.insert(key.schema_key.clone(), (key, schema));
+    }
+}
+
+fn schema_key_is_older(
+    candidate: &crate::schema::SchemaKey,
+    existing: &crate::schema::SchemaKey,
+) -> bool {
+    match (candidate.version_number(), existing.version_number()) {
+        (Some(candidate_version), Some(existing_version)) => candidate_version < existing_version,
+        _ => candidate.schema_version < existing.schema_version,
+    }
+}
+
+fn decode_registered_schema_row(
+    row: &LiveStateRow,
+) -> Result<Option<(crate::schema::SchemaKey, JsonValue)>, LixError> {
+    if row.schema_key != REGISTERED_SCHEMA_KEY {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!(
+                "expected lix_registered_schema row, got schema_key={}",
+                row.schema_key
+            ),
+        ));
+    }
+
+    let Some(snapshot_content) = row.snapshot_content.as_deref() else {
+        return Ok(None);
+    };
+
+    let snapshot: JsonValue = serde_json::from_str(snapshot_content).map_err(|err| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("invalid registered schema snapshot JSON: {err}"),
+        )
+    })?;
+    let schema = snapshot.get("value").cloned().ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "registered schema snapshot missing value",
+        )
+    })?;
+    let key = schema_key_from_definition(&schema)?;
+    Ok(Some((key, schema)))
+}
+
+#[cfg(test)]
+mod tests {
+    use async_trait::async_trait;
+    use serde_json::json;
+
+    use super::*;
+    use crate::live_state::LiveStateRowRequest;
+    use crate::GLOBAL_VERSION_ID;
+
+    #[tokio::test]
+    async fn visible_schemas_are_loaded_from_registered_schema_rows() {
+        let registry = SchemaRegistry::new();
+
+        let schemas = registry
+            .visible_schemas(
+                &RowsLiveStateReader::new(vec![
+                    registered_schema_row("lix_registered_schema", "1"),
+                    registered_schema_row("lix_key_value", "1"),
+                ]),
+                "global",
+            )
+            .await
+            .expect("schema visibility should load");
+
+        assert!(schemas.iter().any(|schema| {
+            schema.get("x-lix-key").and_then(JsonValue::as_str) == Some("lix_registered_schema")
+        }));
+        assert!(schemas.iter().any(|schema| {
+            schema.get("x-lix-key").and_then(JsonValue::as_str) == Some("lix_key_value")
+        }));
+    }
+
+    #[tokio::test]
+    async fn visible_schemas_include_registered_schema_rows() {
+        let registry = SchemaRegistry::new();
+
+        let schemas = registry
+            .visible_schemas(
+                &RowsLiveStateReader::new(vec![registered_schema_row(
+                    "engine2_dynamic_schema",
+                    "1",
+                )]),
+                "global",
+            )
+            .await
+            .expect("schema visibility should load");
+
+        assert!(schemas.iter().any(|schema| {
+            schema.get("x-lix-key").and_then(JsonValue::as_str) == Some("engine2_dynamic_schema")
+        }));
+    }
+
+    #[tokio::test]
+    async fn visible_schemas_ignore_projected_global_schema_rows_for_version_scope() {
+        let registry = SchemaRegistry::new();
+        let mut global_only = registered_schema_row("global_only_schema", "1");
+        global_only.global = true;
+        global_only.version_id = "main".to_string();
+
+        let schemas = registry
+            .visible_schemas(&RowsLiveStateReader::new(vec![global_only]), "main")
+            .await
+            .expect("schema visibility should load");
+
+        assert!(schemas.is_empty());
+    }
+
+    #[tokio::test]
+    async fn visible_schemas_are_empty_when_no_schema_rows_are_visible() {
+        let registry = SchemaRegistry::new();
+
+        let schemas = registry
+            .visible_schemas(&RowsLiveStateReader::new(Vec::new()), "global")
+            .await
+            .expect("schema visibility should load");
+
+        assert!(schemas.is_empty());
+    }
+
+    struct RowsLiveStateReader {
+        rows: Vec<LiveStateRow>,
+    }
+
+    impl RowsLiveStateReader {
+        fn new(rows: Vec<LiveStateRow>) -> Self {
+            Self { rows }
+        }
+    }
+
+    #[async_trait]
+    impl LiveStateReader for RowsLiveStateReader {
+        async fn scan_rows(
+            &self,
+            request: &LiveStateScanRequest,
+        ) -> Result<Vec<LiveStateRow>, LixError> {
+            Ok(self
+                .rows
+                .iter()
+                .filter(|row| {
+                    request.filter.schema_keys.is_empty()
+                        || request.filter.schema_keys.contains(&row.schema_key)
+                })
+                .filter(|row| {
+                    request.filter.version_ids.is_empty()
+                        || request.filter.version_ids.contains(&row.version_id)
+                })
+                .cloned()
+                .collect())
+        }
+
+        async fn load_row(
+            &self,
+            request: &LiveStateRowRequest,
+        ) -> Result<Option<LiveStateRow>, LixError> {
+            Ok(self
+                .rows
+                .iter()
+                .find(|row| {
+                    row.schema_key == request.schema_key
+                        && row.version_id == request.version_id
+                        && row.entity_id == request.entity_id
+                })
+                .cloned())
+        }
+    }
+
+    fn registered_schema_row(schema_key: &str, schema_version: &str) -> LiveStateRow {
+        LiveStateRow {
+            entity_id: registered_schema_entity_id(schema_key, schema_version),
+            file_id: None,
+            schema_key: REGISTERED_SCHEMA_KEY.to_string(),
+            schema_version: "1".to_string(),
+            version_id: GLOBAL_VERSION_ID.to_string(),
+            metadata: None,
+            change_id: Some("change-registered-schema".to_string()),
+            commit_id: None,
+            global: true,
+            untracked: true,
+            created_at: "2026-04-23T00:00:00Z".to_string(),
+            updated_at: "2026-04-23T01:00:00Z".to_string(),
+            snapshot_content: Some(
+                json!({
+                    "value": {
+                        "x-lix-key": schema_key,
+                        "x-lix-version": schema_version,
+                        "type": "object",
+                        "properties": {
+                            "id": { "type": "string" }
+                        },
+                        "required": ["id"],
+                        "additionalProperties": false
+                    }
+                })
+                .to_string(),
+            ),
+        }
+    }
+
+    fn registered_schema_entity_id(
+        schema_key: &str,
+        schema_version: &str,
+    ) -> crate::entity_identity::EntityIdentity {
+        crate::entity_identity::EntityIdentity::from_primary_key_paths(
+            &json!({
+                "value": {
+                    "x-lix-key": schema_key,
+                    "x-lix-version": schema_version,
+                }
+            }),
+            &[
+                vec!["value".to_string(), "x-lix-key".to_string()],
+                vec!["value".to_string(), "x-lix-version".to_string()],
+            ],
+        )
+        .expect("registered schema identity should derive")
+    }
+}

package/dist-engine-src/src/session/context.rs

@@ -0,0 +1,366 @@
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+use serde_json::Value as JsonValue;
+
+use crate::binary_cas::{BinaryCasContext, BlobDataReader};
+use crate::changelog::ChangelogContext;
+use crate::commit_graph::{CommitGraphContext, CommitGraphReader};
+use crate::entity_identity::EntityIdentity;
+use crate::functions::FunctionProviderHandle;
+use crate::json_store::JsonStoreContext;
+use crate::live_state::{LiveStateContext, LiveStateReader, LiveStateRowRequest};
+use crate::schema_registry::SchemaRegistry;
+use crate::sql2::{ChangelogQuerySource, SqlChangelogQuerySource, SqlExecutionContext};
+use crate::storage::{
+    ScopedStorageReader, StorageContext, StorageReadScope, StorageReadTransaction, StorageReader,
+};
+use crate::tracked_state::TrackedStateContext;
+use crate::transaction::{open_transaction, Transaction};
+use crate::version::{VersionContext, VersionRefReader};
+use crate::GLOBAL_VERSION_ID;
+use crate::{LixError, NullableKeyFilter};
+
+pub(crate) const WORKSPACE_VERSION_KEY: &str = "lix_workspace_version_id";
+
+#[derive(Clone)]
+pub(crate) enum SessionMode {
+    Pinned { version_id: String },
+    Workspace,
+}
+
+/// Session-context state for engine2 execution.
+///
+/// A session context pins the active version selector and shared execution
+/// services. Each call to `execute(...)` projects this state into a read-only
+/// SQL context or a transaction-owned write context.
+///
+/// Write transaction invariant: any engine2 operation that may write must enter
+/// through `SessionContext::with_write_transaction`. Reads that influence writes
+/// are only available from that transaction capability, not from session-level
+/// helpers.
+#[derive(Clone)]
+pub struct SessionContext {
+    pub(super) mode: SessionMode,
+    pub(super) storage: StorageContext,
+    pub(super) live_state: Arc<LiveStateContext>,
+    pub(super) tracked_state: Arc<TrackedStateContext>,
+    pub(super) binary_cas: Arc<BinaryCasContext>,
+    pub(super) changelog: Arc<ChangelogContext>,
+    pub(super) version_ctx: Arc<VersionContext>,
+    pub(super) schema_registry: Arc<SchemaRegistry>,
+    closed: Arc<AtomicBool>,
+}
+
+impl SessionContext {
+    pub(crate) async fn open_workspace(
+        storage: StorageContext,
+        live_state: Arc<LiveStateContext>,
+        tracked_state: Arc<TrackedStateContext>,
+        binary_cas: Arc<BinaryCasContext>,
+        changelog: Arc<ChangelogContext>,
+        version_ctx: Arc<VersionContext>,
+        schema_registry: Arc<SchemaRegistry>,
+    ) -> Result<Self, LixError> {
+        let session = Self::new(
+            SessionMode::Workspace,
+            storage,
+            live_state,
+            tracked_state,
+            binary_cas,
+            changelog,
+            version_ctx,
+            schema_registry,
+        );
+        session.active_version_id().await?;
+        Ok(session)
+    }
+
+    pub(crate) async fn open(
+        active_version_id: String,
+        storage: StorageContext,
+        live_state: Arc<LiveStateContext>,
+        tracked_state: Arc<TrackedStateContext>,
+        binary_cas: Arc<BinaryCasContext>,
+        changelog: Arc<ChangelogContext>,
+        version_ctx: Arc<VersionContext>,
+        schema_registry: Arc<SchemaRegistry>,
+    ) -> Result<Self, LixError> {
+        Ok(Self::new(
+            SessionMode::Pinned {
+                version_id: active_version_id,
+            },
+            storage,
+            live_state,
+            tracked_state,
+            binary_cas,
+            changelog,
+            version_ctx,
+            schema_registry,
+        ))
+    }
+
+    pub(super) fn new(
+        mode: SessionMode,
+        storage: StorageContext,
+        live_state: Arc<LiveStateContext>,
+        tracked_state: Arc<TrackedStateContext>,
+        binary_cas: Arc<BinaryCasContext>,
+        changelog: Arc<ChangelogContext>,
+        version_ctx: Arc<VersionContext>,
+        schema_registry: Arc<SchemaRegistry>,
+    ) -> Self {
+        Self::new_with_closed(
+            mode,
+            storage,
+            live_state,
+            tracked_state,
+            binary_cas,
+            changelog,
+            version_ctx,
+            schema_registry,
+            Arc::new(AtomicBool::new(false)),
+        )
+    }
+
+    pub(super) fn new_with_closed(
+        mode: SessionMode,
+        storage: StorageContext,
+        live_state: Arc<LiveStateContext>,
+        tracked_state: Arc<TrackedStateContext>,
+        binary_cas: Arc<BinaryCasContext>,
+        changelog: Arc<ChangelogContext>,
+        version_ctx: Arc<VersionContext>,
+        schema_registry: Arc<SchemaRegistry>,
+        closed: Arc<AtomicBool>,
+    ) -> Self {
+        Self {
+            mode,
+            storage,
+            live_state,
+            tracked_state,
+            binary_cas,
+            changelog,
+            version_ctx,
+            schema_registry,
+            closed,
+        }
+    }
+
+    /// Releases this logical session handle. This is a lifecycle boundary only:
+    /// successful writes are committed before their operation returns.
+    pub async fn close(&self) -> Result<(), LixError> {
+        self.closed.store(true, Ordering::SeqCst);
+        Ok(())
+    }
+
+    pub fn is_closed(&self) -> bool {
+        self.closed.load(Ordering::SeqCst)
+    }
+
+    pub(crate) fn closed_flag(&self) -> Arc<AtomicBool> {
+        Arc::clone(&self.closed)
+    }
+
+    pub(crate) fn ensure_open(&self) -> Result<(), LixError> {
+        if self.is_closed() {
+            return Err(closed_error());
+        }
+        Ok(())
+    }
+
+    /// Resolves the version this session should operate on right now.
+    ///
+    /// This is a read-path helper. Write flows must resolve the active version
+    /// through the transaction capability so the read is scoped to the
+    /// same backend transaction as the writes it influences.
+    ///
+    /// Pinned sessions are pure in-memory views over one version. Workspace
+    /// sessions read the shared workspace selector from untracked global
+    /// `lix_key_value` state so multiple open app sessions can observe the same
+    /// active workspace version.
+    pub async fn active_version_id(&self) -> Result<String, LixError> {
+        let mut transaction = self.storage.begin_read_transaction().await?;
+        let result = self
+            .active_version_id_from_reader(transaction.as_mut())
+            .await;
+        match result {
+            Ok(version_id) => {
+                transaction.rollback().await?;
+                Ok(version_id)
+            }
+            Err(error) => {
+                let _ = transaction.rollback().await;
+                Err(error)
+            }
+        }
+    }
+
+    pub(super) async fn active_version_id_from_reader<S>(
+        &self,
+        reader: &mut S,
+    ) -> Result<String, LixError>
+    where
+        S: StorageReader + ?Sized,
+    {
+        self.ensure_open()?;
+        match &self.mode {
+            SessionMode::Pinned { version_id } => Ok(version_id.clone()),
+            SessionMode::Workspace => self.load_workspace_version_id(reader).await,
+        }
+    }
+
+    async fn load_workspace_version_id<S>(&self, reader: &mut S) -> Result<String, LixError>
+    where
+        S: StorageReader + ?Sized,
+    {
+        let row = self
+            .live_state
+            .reader(&mut *reader)
+            .load_row(&LiveStateRowRequest {
+                schema_key: "lix_key_value".to_string(),
+                version_id: GLOBAL_VERSION_ID.to_string(),
+                entity_id: EntityIdentity::single(WORKSPACE_VERSION_KEY),
+                file_id: NullableKeyFilter::Null,
+            })
+            .await?
+            .ok_or_else(|| {
+                LixError::new(
+                    "LIX_ERROR_UNKNOWN",
+                    "workspace version selector is missing lix_key_value:lix_workspace_version_id",
+                )
+            })?;
+        let snapshot_content = row.snapshot_content.as_deref().ok_or_else(|| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                "workspace version selector is missing snapshot_content",
+            )
+        })?;
+        let snapshot = serde_json::from_str::<JsonValue>(snapshot_content).map_err(|error| {
+            LixError::new(
+                "LIX_ERROR_UNKNOWN",
+                format!("workspace version selector snapshot is invalid JSON: {error}"),
+            )
+        })?;
+        let version_id = snapshot
+            .get("value")
+            .and_then(JsonValue::as_str)
+            .filter(|value| !value.is_empty())
+            .ok_or_else(|| {
+                LixError::new(
+                    "LIX_ERROR_UNKNOWN",
+                    "workspace version selector value must be a non-empty string",
+                )
+            })?
+            .to_string();
+
+        let head = self
+            .version_ctx
+            .ref_reader(&mut *reader)
+            .load_head_commit_id(&version_id)
+            .await?;
+        if head.is_none() {
+            return Err(LixError::version_not_found(
+                version_id,
+                "load_workspace_version_id",
+                "workspace_selector",
+            ));
+        }
+
+        Ok(version_id)
+    }
+
+    pub(crate) async fn with_write_transaction<T, F>(&self, f: F) -> Result<T, LixError>
+    where
+        F: for<'tx> FnOnce(
+            &'tx mut Transaction,
+        ) -> Pin<Box<dyn Future<Output = Result<T, LixError>> + 'tx>>,
+    {
+        self.ensure_open()?;
+        let opened = open_transaction(
+            &self.mode,
+            self.storage.clone(),
+            Arc::clone(&self.live_state),
+            Arc::clone(&self.tracked_state),
+            Arc::clone(&self.binary_cas),
+            Arc::clone(&self.changelog),
+            Arc::clone(&self.version_ctx),
+            Arc::clone(&self.schema_registry),
+        )
+        .await?;
+        let mut transaction = opened.transaction;
+        let runtime_functions = opened.runtime_functions;
+
+        match f(&mut transaction).await {
+            Ok(value) => {
+                transaction.commit(&runtime_functions).await?;
+                Ok(value)
+            }
+            Err(error) => {
+                let _ = transaction.rollback().await;
+                Err(error)
+            }
+        }
+    }
+}
+
+fn closed_error() -> LixError {
+    LixError::new(LixError::CODE_CLOSED, "Lix handle is closed")
+        .with_hint("Open a new Lix handle before calling this method.")
+}
+
+/// Read-only SQL execution context derived from a session.
+///
+/// Write statements re-plan against `Transaction`; this context intentionally
+/// has no write stager.
+pub(super) struct SessionSqlExecutionContext<'a> {
+    pub(super) active_version_id: &'a str,
+    pub(super) read_store:
+        ScopedStorageReader<Box<dyn StorageReadTransaction + Send + Sync + 'static>>,
+    pub(super) live_state: Arc<LiveStateContext>,
+    pub(super) binary_cas: Arc<BinaryCasContext>,
+    pub(super) changelog: Arc<ChangelogContext>,
+    pub(super) version_ctx: Arc<VersionContext>,
+    pub(super) visible_schemas: Vec<JsonValue>,
+    pub(super) functions: FunctionProviderHandle,
+}
+
+impl SqlExecutionContext for SessionSqlExecutionContext<'_> {
+    fn active_version_id(&self) -> &str {
+        self.active_version_id
+    }
+
+    fn live_state(&self) -> Arc<dyn LiveStateReader> {
+        Arc::new(self.live_state.reader(self.read_store.clone())) as Arc<dyn LiveStateReader>
+    }
+
+    fn changelog_query_source(&self) -> SqlChangelogQuerySource {
+        let read_scope = StorageReadScope::new(self.read_store.clone());
+        ChangelogQuerySource {
+            changelog_reader: Arc::new(self.changelog.reader(read_scope.store())),
+            json_reader: JsonStoreContext::new().reader(read_scope.store()),
+        }
+    }
+
+    fn commit_graph(&self) -> Box<dyn CommitGraphReader> {
+        Box::new(CommitGraphContext::new(ChangelogContext::new()).reader(self.read_store.clone()))
+    }
+
+    fn version_ref(&self) -> Arc<dyn VersionRefReader> {
+        Arc::new(self.version_ctx.ref_reader(self.read_store.clone()))
+    }
+
+    fn functions(&self) -> FunctionProviderHandle {
+        self.functions.clone()
+    }
+
+    fn blob_reader(&self) -> Arc<dyn BlobDataReader> {
+        Arc::new(self.binary_cas.reader(self.read_store.clone())) as Arc<dyn BlobDataReader>
+    }
+
+    fn list_visible_schemas(&self) -> Result<Vec<JsonValue>, LixError> {
+        Ok(self.visible_schemas.clone())
+    }
+}