@lix-js/sdk 0.5.0-preview.1 → 0.5.0

package/dist/state/writer.js

@@ -0,0 +1,62 @@
+import { sql } from "kysely";
+/**
+ * Runs a block of DML with a transaction-scoped writer identity and restores
+ * the previous value afterwards (nesting-safe).
+ *
+ * Many clients (for example rich‑text editors) need to react to external
+ * changes to the same document while suppressing their own writes to avoid
+ * feedback loops. The state API supports this by stamping a `writer_key`
+ * for each INSERT, UPDATE, and DELETE. Observers can then filter “not me”.
+ *
+ * This helper provides the single recommended way to pass the writer identity
+ * for a batch of mutations: it starts a transaction on the provided connection,
+ * sets the writer via `lix_set_writer_key(<writer|null>)`, executes your
+ * callback with a transaction-bound Kysely instance, and restores the previous
+ * writer (or NULL) in a finally block. The engine also clears the writer on
+ * COMMIT/ROLLBACK; the restore step handles nested usage gracefully.
+ *
+ * Use a session-scoped writer value (for example
+ * `flashtype:tiptap#<sessionId>`) so that two browser tabs don’t suppress each
+ * other’s updates. Do not set `writer_key` columns directly in DML — the engine
+ * manages them.
+ *
+ * @example
+ * // Upsert and delete with the same writer (editor persistence)
+ * await withWriterKey(db, 'flashtype:tiptap#<sessionId>', async (trx) => {
+ *   await trx
+ *     .insertInto('state')
+ *     .values({ file_id, version_id, entity_id, schema_key, plugin_key, schema_version, snapshot_content: snapshot as any })
+ *     .onConflict((oc) => oc.columns(['file_id','version_id','entity_id','schema_key']).doUpdateSet({ snapshot_content: snapshot as any }))
+ *     .execute();
+ *
+ *   await trx
+ *     .deleteFrom('state')
+ *     .where('file_id','=',fileId)
+ *     .where('version_id','=',versionId)
+ *     .where('entity_id','=',entityId)
+ *     .where('schema_key','=',schemaKey)
+ *     .execute();
+ * });
+ */
+export async function withWriterKey(db, writer, fn) {
+    const executeInTransaction = async (trx) => {
+        const prevRes = await sql `SELECT lix_get_writer_key()`.execute(trx);
+        const prevWriter = prevRes.rows?.[0]?.["lix_get_writer_key()"] ?? null;
+        await sql `SELECT lix_set_writer_key(${writer})`.execute(trx);
+        try {
+            return await fn(trx);
+        }
+        finally {
+            await sql `SELECT lix_set_writer_key(${prevWriter})`.execute(trx);
+        }
+    };
+    // If caller provided an open transaction, reuse it; otherwise open one.
+    const anyDb = db;
+    if (anyDb.isTransaction) {
+        return executeInTransaction(db);
+    }
+    else {
+        return db.transaction().execute(executeInTransaction);
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/state/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/state/writer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,EAAc,EACd,MAAqB,EACrB,EAAmC;IAEnC,MAAM,oBAAoB,GAAG,KAAK,EAAE,GAAe,EAAE,EAAE;QACtD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAA,6BAA6B,CAAC,OAAO,CAAC,GAAU,CAAC,CAAC;QAC3E,MAAM,UAAU,GACd,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAS,EAAE,CAAC,sBAAsB,CAAC,IAAI,IAAI,CAAC;QAE9D,MAAM,GAAG,CAAA,6BAA6B,MAAM,GAAG,CAAC,OAAO,CAAC,GAAU,CAAC,CAAC;QACpE,IAAI,CAAC;YACJ,OAAO,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;gBAAS,CAAC;YACV,MAAM,GAAG,CAAA,6BAA6B,UAAU,GAAG,CAAC,OAAO,CAAC,GAAU,CAAC,CAAC;QACzE,CAAC;IACF,CAAC,CAAC;IAEF,wEAAwE;IACxE,MAAM,KAAK,GAAG,EAGb,CAAC;IACF,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACzB,OAAO,oBAAoB,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;SAAM,CAAC;QACP,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACvD,CAAC;AACF,CAAC"}

package/dist/state-history/schema.d.ts

@@ -1,5 +1,5 @@
 import type { Selectable } from "kysely";
-import type { Lix } from "../lix/open-lix.js";
+import type { LixEngine } from "../engine/boot.js";
 /**
  * State history table interface for querying historical entity states.
  *
@@ -17,6 +17,8 @@ export interface StateHistoryTable {
     plugin_key: string;
     /** JSON content of the entity at this point in history */
     snapshot_content: Record<string, any>;
+    /** Optional change metadata associated with this historical state. */
+    metadata: Record<string, any> | null;
     /** Version of the schema used for this entity */
     schema_version: string;
     /**
@@ -63,6 +65,8 @@ export interface StateHistoryTable {
     depth: number;
 }
 export type StateHistoryView = Selectable<StateHistoryTable>;
-export declare function applyStateHistoryDatabaseSchema(lix: Pick<Lix, "sqlite" | "db">): void;
-export declare const STATE_HISTORY_VIEW_SQL = "\nCREATE VIEW IF NOT EXISTS state_history AS\nWITH\n\t-- Get all changes with their snapshots\n\tall_changes_with_snapshots AS (\n\t\tSELECT ic.id, ic.entity_id, ic.schema_key, ic.file_id, ic.plugin_key,\n\t\t\t   ic.schema_version, ic.created_at,\n\t\t\t   CASE \n\t\t\t     WHEN ic.snapshot_id = 'no-content' THEN NULL\n\t\t\t     ELSE json(s.content)\n\t\t\t   END AS snapshot_content \n\t\tFROM internal_change ic\n\t\tLEFT JOIN internal_snapshot s ON ic.snapshot_id = s.id\n\t),\n\t-- For state_history, we work with any commit_id, not just version heads\n\trequested_commits AS (\n\t\tSELECT DISTINCT c.id as commit_id\n\t\tFROM commit_all c\n\t\t-- This will be filtered by the WHERE clause in queries\n\t),\n\t-- Find all commits reachable from requested ones (including ancestors)\n\treachable_commits_from_requested(id, root_commit_id, depth) AS (\n\t\tSELECT commit_id, commit_id as root_commit_id, 0 as depth \n\t\tFROM requested_commits\n\t\tUNION\n\t\tSELECT ce.parent_id, r.root_commit_id, r.depth + 1\n\t\tFROM commit_edge_all ce \n\t\tJOIN reachable_commits_from_requested r ON ce.child_id = r.id\n\t\tWHERE ce.lixcol_version_id = 'global'\n\t),\n\t-- Get change set IDs for each commit\n\tcommit_changesets AS (\n\t\tSELECT \n\t\t\tc.id as commit_id,\n\t\t\tc.change_set_id as change_set_id,\n\t\t\trc.root_commit_id,\n\t\t\trc.depth as commit_depth\n\t\tFROM commit_all c\n\t\tJOIN reachable_commits_from_requested rc ON c.id = rc.id\n\t\tWHERE c.lixcol_version_id = 'global'\n\t),\n\t-- Find all change set elements in reachable commits\n\tcse_in_reachable_commits AS (\n\t\tSELECT cse.entity_id AS target_entity_id,\n\t\t\t   cse.file_id AS target_file_id,\n\t\t\t   cse.schema_key AS target_schema_key, \n\t\t\t   cse.change_id AS target_change_id,\n\t\t\t   cse.change_set_id AS cse_origin_change_set_id,\n\t\t\t   cc.commit_id AS origin_commit_id,\n\t\t\t   cc.root_commit_id,\n\t\t\t   cc.commit_depth,\n\t\t\t   cc.commit_id as depth_commit_id\n\t\tFROM change_set_element_all cse\n\t\tJOIN commit_changesets cc ON cse.change_set_id = cc.change_set_id\n\t\tWHERE cse.lixcol_version_id = 'global'\n\t),\n\t-- For each entity at each depth, find the latest change within that depth's commit\n\tlatest_change_per_entity_per_depth AS (\n\t\tSELECT \n\t\t\tr.target_entity_id,\n\t\t\tr.target_file_id,\n\t\t\tr.target_schema_key,\n\t\t\tr.root_commit_id,\n\t\t\tr.commit_depth,\n\t\t\tr.depth_commit_id,\n\t\t\tMAX(target_change.created_at) as latest_created_at\n\t\tFROM cse_in_reachable_commits r \n\t\tINNER JOIN all_changes_with_snapshots target_change ON r.target_change_id = target_change.id\n\t\tGROUP BY r.target_entity_id, r.target_file_id, r.target_schema_key, r.root_commit_id, r.commit_depth\n\t),\n\t-- Get the actual changes for each entity at each depth\n\tentity_states_at_depths AS (\n\t\tSELECT \n\t\t\ttarget_change.entity_id, \n\t\t\ttarget_change.schema_key, \n\t\t\ttarget_change.file_id,\n\t\t\ttarget_change.plugin_key, \n\t\t\ttarget_change.snapshot_content,\n\t\t\ttarget_change.schema_version,\n\t\t\tr.target_change_id,\n\t\t\tr.origin_commit_id,\n\t\t\tr.root_commit_id,\n\t\t\tlatest.commit_depth\n\t\tFROM latest_change_per_entity_per_depth latest\n\t\tINNER JOIN cse_in_reachable_commits r ON (\n\t\t\tlatest.target_entity_id = r.target_entity_id \n\t\t\tAND latest.target_file_id = r.target_file_id\n\t\t\tAND latest.target_schema_key = r.target_schema_key\n\t\t\tAND latest.root_commit_id = r.root_commit_id\n\t\t\tAND latest.commit_depth = r.commit_depth\n\t\t)\n\t\tINNER JOIN all_changes_with_snapshots target_change ON (\n\t\t\tr.target_change_id = target_change.id\n\t\t\tAND target_change.created_at = latest.latest_created_at\n\t\t)\n\t)\nSELECT \n\tesad.entity_id,\n\tesad.schema_key,\n\tesad.file_id,\n\tesad.plugin_key,\n\tesad.snapshot_content,\n\tesad.schema_version,\n\tesad.target_change_id as change_id,\n\tesad.origin_commit_id as commit_id,\n\tesad.root_commit_id as root_commit_id,\n\tesad.commit_depth as depth\nFROM entity_states_at_depths esad\nWHERE esad.snapshot_content IS NOT NULL  -- Exclude deletions for now\nORDER BY esad.entity_id, esad.commit_depth;\n";
+export declare function applyStateHistoryDatabaseSchema(args: {
+    engine: Pick<LixEngine, "sqlite">;
+}): void;
+export declare const STATE_HISTORY_VIEW_SQL = "\nCREATE VIEW IF NOT EXISTS state_history AS\nWITH\n\t-- Inline entity views to avoid preprocessor dependencies\n\t_commit_by_version AS (\n\t\tSELECT \n\t\t\tjson_extract(s.snapshot_content, '$.id') AS id,\n\t\t\tjson_extract(s.snapshot_content, '$.change_set_id') AS change_set_id,\n\t\t\ts.version_id AS lixcol_version_id\n\t\tFROM state_by_version AS s\n\t\tWHERE s.schema_key = 'lix_commit'\n\t\t\tAND s.snapshot_content IS NOT NULL\n\t),\n\t_change_set_element_by_version AS (\n\t\tSELECT\n\t\t\tjson_extract(s.snapshot_content, '$.change_set_id') AS change_set_id,\n\t\t\tjson_extract(s.snapshot_content, '$.change_id') AS change_id,\n\t\t\tjson_extract(s.snapshot_content, '$.entity_id') AS entity_id,\n\t\t\tjson_extract(s.snapshot_content, '$.schema_key') AS schema_key,\n\t\t\tjson_extract(s.snapshot_content, '$.file_id') AS file_id,\n\t\t\ts.version_id AS lixcol_version_id\n\t\tFROM state_by_version AS s\n\t\tWHERE s.schema_key = 'lix_change_set_element'\n\t\t\tAND s.snapshot_content IS NOT NULL\n\t),\n\t_commit_edge_by_version AS (\n\t\tSELECT\n\t\t\tjson_extract(s.snapshot_content, '$.parent_id') AS parent_id,\n\t\t\tjson_extract(s.snapshot_content, '$.child_id') AS child_id,\n\t\t\ts.version_id AS lixcol_version_id\n\t\tFROM state_by_version AS s\n\t\tWHERE s.schema_key = 'lix_commit_edge'\n\t\t\tAND s.snapshot_content IS NOT NULL\n\t),\n\n\t-- Get all changes with their snapshots\n\tall_changes_with_snapshots AS (\n\t\tSELECT ic.id, ic.entity_id, ic.schema_key, ic.file_id, ic.plugin_key,\n\t\t\t   ic.schema_version, ic.created_at,\n\t\t\t   CASE \n\t\t\t     WHEN ic.snapshot_id = 'no-content' THEN NULL\n\t\t\t     ELSE json(s.content)\n\t\t\t   END AS snapshot_content,\n\t\t\t   CASE\n\t\t\t     WHEN ic.metadata IS NULL THEN NULL\n\t\t\t     ELSE json(ic.metadata)\n\t\t\t   END AS metadata\n\t\tFROM lix_internal_change ic\n\t\tLEFT JOIN lix_internal_snapshot s ON ic.snapshot_id = s.id\n\t),\n\n\t-- Fast path for depth = 0 (no recursion, direct commit join)\n\tdepth0_entity_states AS (\n\t\tSELECT \n\t\t\tchg.entity_id,\n\t\t\tchg.schema_key,\n\t\t\tchg.file_id,\n\t\t\tchg.plugin_key,\n\t\t\tchg.snapshot_content,\n\t\t\tchg.metadata,\n\t\t\tchg.schema_version,\n\t\t\tcse.change_id AS target_change_id,\n\t\t\tc.id AS origin_commit_id,\n\t\t\tc.id AS root_commit_id,\n\t\t\t0 AS commit_depth\n\t\tFROM _change_set_element_by_version cse\n\t\tJOIN _commit_by_version c \n\t\t\tON cse.change_set_id = c.change_set_id \n\t\t\tAND c.lixcol_version_id = 'global'\n\t\tJOIN all_changes_with_snapshots chg \n\t\t\tON chg.id = cse.change_id\n\t\tWHERE cse.lixcol_version_id = 'global'\n\t),\n\n\t-- General path for depth > 0 (recursive, ancestors of requested commits)\n\trequested_commits AS (\n\t\tSELECT DISTINCT c.id as commit_id\n\t\tFROM _commit_by_version c\n\t),\n\treachable_commits_from_requested(id, root_commit_id, depth) AS (\n\t\tSELECT commit_id, commit_id as root_commit_id, 0 as depth \n\t\tFROM requested_commits\n\t\tUNION\n\t\tSELECT ce.parent_id, r.root_commit_id, r.depth + 1\n\t\tFROM _commit_edge_by_version ce \n\t\tJOIN reachable_commits_from_requested r ON ce.child_id = r.id\n\t\tWHERE ce.lixcol_version_id = 'global'\n\t),\n\tcommit_changesets AS (\n\t\tSELECT \n\t\t\tc.id as commit_id,\n\t\t\tc.change_set_id as change_set_id,\n\t\t\trc.root_commit_id,\n\t\t\trc.depth as commit_depth\n\t\tFROM _commit_by_version c\n\t\tJOIN reachable_commits_from_requested rc ON c.id = rc.id\n\t\tWHERE c.lixcol_version_id = 'global'\n\t),\n\tcse_in_reachable_commits AS (\n\t\tSELECT cse.entity_id AS target_entity_id,\n\t\t\t   cse.file_id AS target_file_id,\n\t\t\t   cse.schema_key AS target_schema_key, \n\t\t\t   cse.change_id AS target_change_id,\n\t\t\t   cse.change_set_id AS cse_origin_change_set_id,\n\t\t\t   cc.commit_id AS origin_commit_id,\n\t\t\t   cc.root_commit_id,\n\t\t\t   cc.commit_depth,\n\t\t\t   cc.commit_id as depth_commit_id\n\t\tFROM _change_set_element_by_version cse\n\t\tJOIN commit_changesets cc ON cse.change_set_id = cc.change_set_id\n\t\tWHERE cse.lixcol_version_id = 'global'\n\t),\n\tlatest_change_per_entity_per_depth AS (\n\t\tSELECT \n\t\t\tr.target_entity_id,\n\t\t\tr.target_file_id,\n\t\t\tr.target_schema_key,\n\t\t\tr.root_commit_id,\n\t\t\tr.commit_depth,\n\t\t\tr.depth_commit_id,\n\t\t\tMAX(target_change.created_at) as latest_created_at\n\t\tFROM cse_in_reachable_commits r \n\t\tINNER JOIN all_changes_with_snapshots target_change ON r.target_change_id = target_change.id\n\t\tGROUP BY r.target_entity_id, r.target_file_id, r.target_schema_key, r.root_commit_id, r.commit_depth\n\t),\n\tdepthN_entity_states AS (\n\t\tSELECT \n\t\t\ttarget_change.entity_id, \n\t\t\ttarget_change.schema_key, \n\t\t\ttarget_change.file_id,\n\t\t\ttarget_change.plugin_key, \n\t\t\ttarget_change.snapshot_content,\n\t\t\ttarget_change.metadata,\n\t\t\ttarget_change.schema_version,\n\t\t\tr.target_change_id,\n\t\t\tr.origin_commit_id,\n\t\t\tr.root_commit_id,\n\t\t\tlatest.commit_depth\n\t\tFROM latest_change_per_entity_per_depth latest\n\t\tINNER JOIN cse_in_reachable_commits r ON (\n\t\t\tlatest.target_entity_id = r.target_entity_id \n\t\t\tAND latest.target_file_id = r.target_file_id\n\t\t\tAND latest.target_schema_key = r.target_schema_key\n\t\t\tAND latest.root_commit_id = r.root_commit_id\n\t\t\tAND latest.commit_depth = r.commit_depth\n\t\t)\n\t\tINNER JOIN all_changes_with_snapshots target_change ON (\n\t\t\tr.target_change_id = target_change.id\n\t\t\tAND target_change.created_at = latest.latest_created_at\n\t\t)\n\t\tWHERE latest.commit_depth > 0\n\t)\n\nSELECT \n\tes.entity_id,\n\tes.schema_key,\n\tes.file_id,\n\tes.plugin_key,\n\tes.snapshot_content,\n\tes.metadata,\n\tes.schema_version,\n\tes.target_change_id as change_id,\n\tes.origin_commit_id as commit_id,\n\tes.root_commit_id as root_commit_id,\n\tes.commit_depth as depth,\n\t'global' as version_id\nFROM (\n\tSELECT * FROM depth0_entity_states\n\tUNION ALL\n\tSELECT * FROM depthN_entity_states\n) AS es\nWHERE es.snapshot_content IS NOT NULL  -- Exclude deletions for now\nORDER BY es.entity_id, es.commit_depth;\n";
 //# sourceMappingURL=schema.d.ts.map

package/dist/state-history/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/state-history/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IAEnB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAEhB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IAEnB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEtC,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAC;CA2Bd;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;AAE7D,wBAAgB,+BAA+B,CAC9C,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,GAC7B,IAAI,CAEN;AAGD,eAAO,MAAM,sBAAsB,8iIA8GlC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/state-history/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IAEnB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAEhB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IAEnB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEtC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAErC,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAC;CA2Bd;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;AAE7D,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACrD,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;CAClC,GAAG,IAAI,CAEP;AAID,eAAO,MAAM,sBAAsB,48LA6KlC,CAAC"}

package/dist/state-history/schema.js

@@ -1,10 +1,43 @@
-export function applyStateHistoryDatabaseSchema(lix) {
-    lix.sqlite.exec(STATE_HISTORY_VIEW_SQL);
+export function applyStateHistoryDatabaseSchema(args) {
+    args.engine.sqlite.exec(STATE_HISTORY_VIEW_SQL);
 }
-// Optimized to use materialized commit_edge_all and change_set_element_all from global version
+// Optimized to keep the generic history view, but add a fast path for depth=0
+// to avoid whole-graph recursion for common queries like "WHERE depth = 0".
 export const STATE_HISTORY_VIEW_SQL = `
 CREATE VIEW IF NOT EXISTS state_history AS
 WITH
+	-- Inline entity views to avoid preprocessor dependencies
+	_commit_by_version AS (
+		SELECT 
+			json_extract(s.snapshot_content, '$.id') AS id,
+			json_extract(s.snapshot_content, '$.change_set_id') AS change_set_id,
+			s.version_id AS lixcol_version_id
+		FROM state_by_version AS s
+		WHERE s.schema_key = 'lix_commit'
+			AND s.snapshot_content IS NOT NULL
+	),
+	_change_set_element_by_version AS (
+		SELECT
+			json_extract(s.snapshot_content, '$.change_set_id') AS change_set_id,
+			json_extract(s.snapshot_content, '$.change_id') AS change_id,
+			json_extract(s.snapshot_content, '$.entity_id') AS entity_id,
+			json_extract(s.snapshot_content, '$.schema_key') AS schema_key,
+			json_extract(s.snapshot_content, '$.file_id') AS file_id,
+			s.version_id AS lixcol_version_id
+		FROM state_by_version AS s
+		WHERE s.schema_key = 'lix_change_set_element'
+			AND s.snapshot_content IS NOT NULL
+	),
+	_commit_edge_by_version AS (
+		SELECT
+			json_extract(s.snapshot_content, '$.parent_id') AS parent_id,
+			json_extract(s.snapshot_content, '$.child_id') AS child_id,
+			s.version_id AS lixcol_version_id
+		FROM state_by_version AS s
+		WHERE s.schema_key = 'lix_commit_edge'
+			AND s.snapshot_content IS NOT NULL
+	),
+
 	-- Get all changes with their snapshots
 	all_changes_with_snapshots AS (
 		SELECT ic.id, ic.entity_id, ic.schema_key, ic.file_id, ic.plugin_key,
@@ -12,38 +45,62 @@ WITH
 			   CASE 
 			     WHEN ic.snapshot_id = 'no-content' THEN NULL
 			     ELSE json(s.content)
-			   END AS snapshot_content 
-		FROM internal_change ic
-		LEFT JOIN internal_snapshot s ON ic.snapshot_id = s.id
+			   END AS snapshot_content,
+			   CASE
+			     WHEN ic.metadata IS NULL THEN NULL
+			     ELSE json(ic.metadata)
+			   END AS metadata
+		FROM lix_internal_change ic
+		LEFT JOIN lix_internal_snapshot s ON ic.snapshot_id = s.id
+	),
+
+	-- Fast path for depth = 0 (no recursion, direct commit join)
+	depth0_entity_states AS (
+		SELECT 
+			chg.entity_id,
+			chg.schema_key,
+			chg.file_id,
+			chg.plugin_key,
+			chg.snapshot_content,
+			chg.metadata,
+			chg.schema_version,
+			cse.change_id AS target_change_id,
+			c.id AS origin_commit_id,
+			c.id AS root_commit_id,
+			0 AS commit_depth
+		FROM _change_set_element_by_version cse
+		JOIN _commit_by_version c 
+			ON cse.change_set_id = c.change_set_id 
+			AND c.lixcol_version_id = 'global'
+		JOIN all_changes_with_snapshots chg 
+			ON chg.id = cse.change_id
+		WHERE cse.lixcol_version_id = 'global'
 	),
-	-- For state_history, we work with any commit_id, not just version heads
+
+	-- General path for depth > 0 (recursive, ancestors of requested commits)
 	requested_commits AS (
 		SELECT DISTINCT c.id as commit_id
-		FROM commit_all c
-		-- This will be filtered by the WHERE clause in queries
+		FROM _commit_by_version c
 	),
-	-- Find all commits reachable from requested ones (including ancestors)
 	reachable_commits_from_requested(id, root_commit_id, depth) AS (
 		SELECT commit_id, commit_id as root_commit_id, 0 as depth 
 		FROM requested_commits
 		UNION
 		SELECT ce.parent_id, r.root_commit_id, r.depth + 1
-		FROM commit_edge_all ce 
+		FROM _commit_edge_by_version ce 
 		JOIN reachable_commits_from_requested r ON ce.child_id = r.id
 		WHERE ce.lixcol_version_id = 'global'
 	),
-	-- Get change set IDs for each commit
 	commit_changesets AS (
 		SELECT 
 			c.id as commit_id,
 			c.change_set_id as change_set_id,
 			rc.root_commit_id,
 			rc.depth as commit_depth
-		FROM commit_all c
+		FROM _commit_by_version c
 		JOIN reachable_commits_from_requested rc ON c.id = rc.id
 		WHERE c.lixcol_version_id = 'global'
 	),
-	-- Find all change set elements in reachable commits
 	cse_in_reachable_commits AS (
 		SELECT cse.entity_id AS target_entity_id,
 			   cse.file_id AS target_file_id,
@@ -54,11 +111,10 @@ WITH
 			   cc.root_commit_id,
 			   cc.commit_depth,
 			   cc.commit_id as depth_commit_id
-		FROM change_set_element_all cse
+		FROM _change_set_element_by_version cse
 		JOIN commit_changesets cc ON cse.change_set_id = cc.change_set_id
 		WHERE cse.lixcol_version_id = 'global'
 	),
-	-- For each entity at each depth, find the latest change within that depth's commit
 	latest_change_per_entity_per_depth AS (
 		SELECT 
 			r.target_entity_id,
@@ -72,14 +128,14 @@ WITH
 		INNER JOIN all_changes_with_snapshots target_change ON r.target_change_id = target_change.id
 		GROUP BY r.target_entity_id, r.target_file_id, r.target_schema_key, r.root_commit_id, r.commit_depth
 	),
-	-- Get the actual changes for each entity at each depth
-	entity_states_at_depths AS (
+	depthN_entity_states AS (
 		SELECT 
 			target_change.entity_id, 
 			target_change.schema_key, 
 			target_change.file_id,
 			target_change.plugin_key, 
 			target_change.snapshot_content,
+			target_change.metadata,
 			target_change.schema_version,
 			r.target_change_id,
 			r.origin_commit_id,
@@ -97,20 +153,28 @@ WITH
 			r.target_change_id = target_change.id
 			AND target_change.created_at = latest.latest_created_at
 		)
+		WHERE latest.commit_depth > 0
 	)
+
 SELECT 
-	esad.entity_id,
-	esad.schema_key,
-	esad.file_id,
-	esad.plugin_key,
-	esad.snapshot_content,
-	esad.schema_version,
-	esad.target_change_id as change_id,
-	esad.origin_commit_id as commit_id,
-	esad.root_commit_id as root_commit_id,
-	esad.commit_depth as depth
-FROM entity_states_at_depths esad
-WHERE esad.snapshot_content IS NOT NULL  -- Exclude deletions for now
-ORDER BY esad.entity_id, esad.commit_depth;
+	es.entity_id,
+	es.schema_key,
+	es.file_id,
+	es.plugin_key,
+	es.snapshot_content,
+	es.metadata,
+	es.schema_version,
+	es.target_change_id as change_id,
+	es.origin_commit_id as commit_id,
+	es.root_commit_id as root_commit_id,
+	es.commit_depth as depth,
+	'global' as version_id
+FROM (
+	SELECT * FROM depth0_entity_states
+	UNION ALL
+	SELECT * FROM depthN_entity_states
+) AS es
+WHERE es.snapshot_content IS NOT NULL  -- Exclude deletions for now
+ORDER BY es.entity_id, es.commit_depth;
 `;
 //# sourceMappingURL=schema.js.map

package/dist/state-history/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/state-history/schema.ts"],"names":[],"mappings":"AAuGA,MAAM,UAAU,+BAA+B,CAC9C,GAA+B;IAE/B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;AACzC,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GrC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/state-history/schema.ts"],"names":[],"mappings":"AA0GA,MAAM,UAAU,+BAA+B,CAAC,IAE/C;IACA,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;AACjD,CAAC;AAED,8EAA8E;AAC9E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6KrC,CAAC"}

package/dist/state-history/schema.test.js

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { test, expect } from "vitest";
 import { openLix } from "../lix/open-lix.js";
-import { createCheckpoint } from "../commit/create-checkpoint.js";
+import { createCheckpoint } from "../state/create-checkpoint.js";
 import { commitIsDescendantOf, commitIsAncestorOf, } from "../query-filter/index.js";
 import { ebEntity } from "../entity/index.js";
 test("query current state at head of version lineage", async () => {
@@ -21,12 +21,12 @@ test("query current state at head of version lineage", async () => {
         .execute();
     // Insert initial state (defaults to active version)
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
         snapshot_content: { value: "initial content" },
@@ -70,24 +70,24 @@ test("query state at specific depth in history", async () => {
         .execute();
     // Insert and modify entity multiple times
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
         snapshot_content: { value: "value0" },
     })
         .execute();
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "value1" } })
         .where("entity_id", "=", "paragraph0")
         .execute();
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "value2" } })
         .where("entity_id", "=", "paragraph0")
         .execute();
@@ -146,7 +146,7 @@ test("query state at specific commit", async () => {
             id: { type: "string" },
             value: { type: "string" },
         },
-        "x-lix-primary-key": ["id"],
+        "x-lix-primary-key": ["/id"],
     };
     await lix.db
         .insertInto("stored_schema")
@@ -251,12 +251,12 @@ test("query state at checkpoint using createCheckpoint API", async () => {
         .execute();
     // Insert initial state
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
         snapshot_content: { value: "checkpoint content" },
@@ -295,13 +295,13 @@ test("diff detection between current and checkpoint state", async () => {
         .execute();
     // Insert entity
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         snapshot_content: { value: "initial" },
     })
@@ -310,7 +310,7 @@ test("diff detection between current and checkpoint state", async () => {
     const checkpoint = await createCheckpoint({ lix });
     // Modify the same entity after checkpoint
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "modified" } })
         .where("entity_id", "=", "paragraph0")
         .execute();
@@ -361,12 +361,12 @@ test("deletion diff - entity exists at checkpoint but not current", async () =>
         .execute();
     // Insert entity
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
         schema_version: "1.0",
         snapshot_content: { value: "to be deleted" },
@@ -376,7 +376,7 @@ test("deletion diff - entity exists at checkpoint but not current", async () =>
     const checkpoint = await createCheckpoint({ lix });
     // Delete entity
     await lix.db
-        .deleteFrom("state_all")
+        .deleteFrom("state_by_version")
         .where("entity_id", "=", "paragraph0")
         .execute();
     const updatedVersion = await lix.db
@@ -426,12 +426,12 @@ test("insertion diff - entity exists current but not at checkpoint", async () =>
     const checkpoint = await createCheckpoint({ lix });
     // Insert entity after checkpoint
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
         schema_version: "1.0",
         snapshot_content: { value: "newly inserted" },
@@ -488,7 +488,7 @@ test("blame functionality - track entity changes over time", async () => {
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         snapshot_content: { value: "initial", author: "alice" },
     })
@@ -549,13 +549,13 @@ test("working change set diff - compare current vs checkpoints", async () => {
         .execute();
     // Insert initial entity
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "paragraph0",
         file_id: "f0",
         schema_key: "mock_schema",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         snapshot_content: { value: "checkpoint 1 content" },
     })
@@ -564,14 +564,14 @@ test("working change set diff - compare current vs checkpoints", async () => {
     const checkpoint1 = await createCheckpoint({ lix });
     // Modify and create second checkpoint
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "checkpoint 2 content" } })
         .where("entity_id", "=", "paragraph0")
         .execute();
     const checkpoint2 = await createCheckpoint({ lix });
     // Modify for current working state
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "working content" } })
         .where("entity_id", "=", "paragraph0")
         .execute();
@@ -624,12 +624,12 @@ test("query history between two commits using ancestor/descendant filters", asyn
         .execute();
     // Create a series of checkpoints with entity changes
     await lix.db
-        .insertInto("state_all")
+        .insertInto("state_by_version")
         .values({
         entity_id: "tracked-entity",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         version_id: lix.db.selectFrom("active_version").select("version_id"),
         snapshot_content: { value: "checkpoint 1 content" },
@@ -638,21 +638,21 @@ test("query history between two commits using ancestor/descendant filters", asyn
     const checkpoint1 = await createCheckpoint({ lix });
     // Modify and create checkpoint 2
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "checkpoint 2 content" } })
         .where("entity_id", "=", "tracked-entity")
         .execute();
     const checkpoint2 = await createCheckpoint({ lix });
     // Modify and create checkpoint 3
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "checkpoint 3 content" } })
         .where("entity_id", "=", "tracked-entity")
         .execute();
     const checkpoint3 = await createCheckpoint({ lix });
     // Modify and create checkpoint 4
     await lix.db
-        .updateTable("state_all")
+        .updateTable("state_by_version")
         .set({ snapshot_content: { value: "checkpoint 4 content" } })
         .where("entity_id", "=", "tracked-entity")
         .execute();
@@ -713,7 +713,7 @@ test.skip("parent_change_set_ids field shows correct parent relationships", asyn
         entity_id: "test-entity",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         snapshot_content: { value: "value0" },
     })
@@ -799,7 +799,7 @@ test("querying the history of the working change set", async () => {
         entity_id: "entity0",
         file_id: "f0",
         schema_key: "mock_schema",
-        plugin_key: "lix_own_entity",
+        plugin_key: "lix_sdk",
         schema_version: "1.0",
         snapshot_content: { value: "initial content" },
     })