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

package/src/state-history/schema.test.ts

@@ -2,7 +2,7 @@
 import { test, expect } from "vitest";
 import { openLix } from "../lix/open-lix.js";
 import type { LixSchemaDefinition } from "../schema-definition/definition.js";
-import { createCheckpoint } from "../commit/create-checkpoint.js";
+import { createCheckpoint } from "../state/create-checkpoint.js";
 import {
 	commitIsDescendantOf,
 	commitIsAncestorOf,
@@ -29,12 +29,12 @@ test("query current state at head of version lineage", async () => {
 
 	// 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" },
@@ -85,12 +85,12 @@ test("query state at specific depth in history", async () => {
 
 	// 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" },
@@ -98,13 +98,13 @@ test("query state at specific depth in history", async () => {
 		.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();
@@ -172,7 +172,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
@@ -297,12 +297,12 @@ test("query state at checkpoint using createCheckpoint API", async () => {
 
 	// 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" },
@@ -348,13 +348,13 @@ test("diff detection between current and checkpoint state", async () => {
 
 	// 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" },
 		})
@@ -365,7 +365,7 @@ test("diff detection between current and checkpoint state", async () => {
 
 	// 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();
@@ -425,12 +425,12 @@ test("deletion diff - entity exists at checkpoint but not current", async () =>
 
 	// 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" },
@@ -442,7 +442,7 @@ test("deletion diff - entity exists at checkpoint but not current", async () =>
 
 	// Delete entity
 	await lix.db
-		.deleteFrom("state_all")
+		.deleteFrom("state_by_version")
 		.where("entity_id", "=", "paragraph0")
 		.execute();
 
@@ -501,12 +501,12 @@ test("insertion diff - entity exists current but not at checkpoint", async () =>
 
 	// 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" },
@@ -571,7 +571,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" },
 		})
@@ -642,13 +642,13 @@ test("working change set diff - compare current vs checkpoints", async () => {
 
 	// 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" },
 		})
@@ -659,7 +659,7 @@ test("working change set diff - compare current vs checkpoints", async () => {
 
 	// 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();
@@ -668,7 +668,7 @@ test("working change set diff - compare current vs checkpoints", async () => {
 
 	// 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();
@@ -734,12 +734,12 @@ test("query history between two commits using ancestor/descendant filters", asyn
 
 	// 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" },
@@ -750,7 +750,7 @@ test("query history between two commits using ancestor/descendant filters", asyn
 
 	// 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();
@@ -759,7 +759,7 @@ test("query history between two commits using ancestor/descendant filters", asyn
 
 	// 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();
@@ -768,7 +768,7 @@ test("query history between two commits using ancestor/descendant filters", asyn
 
 	// 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();
@@ -838,7 +838,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" },
 		})
@@ -939,7 +939,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" },
 		})

package/src/state-history/schema.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.
@@ -23,6 +23,9 @@ export interface StateHistoryTable {
 	/** 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;
 
@@ -101,16 +104,49 @@ export interface StateHistoryTable {
 
 export type StateHistoryView = Selectable<StateHistoryTable>;
 
-export function applyStateHistoryDatabaseSchema(
-	lix: Pick<Lix, "sqlite" | "db">
-): void {
-	lix.sqlite.exec(STATE_HISTORY_VIEW_SQL);
+export function applyStateHistoryDatabaseSchema(args: {
+	engine: Pick<LixEngine, "sqlite">;
+}): void {
+	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,
@@ -118,38 +154,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
 	),
-	-- For state_history, we work with any commit_id, not just version heads
+
+	-- 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'
+	),
+
+	-- 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,
@@ -160,11 +220,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,
@@ -178,14 +237,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,
@@ -203,19 +262,27 @@ 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;
 `;