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

package/src/file/schema.ts

@@ -1,18 +1,18 @@
 import { handleFileInsert, handleFileUpdate } from "./file-handlers.js";
-import { materializeFileData } from "./materialize-file-data.js";
-import { materializeFileDataAtChangeset } from "./materialize-file-data-at-changeset.js";
+import { materializeFileDataAtCommit } from "./materialize-file-data-at-commit.js";
 import type {
 	LixSchemaDefinition,
 	FromLixSchemaDefinition,
 } from "../schema-definition/definition.js";
 import type { Lix } from "../lix/open-lix.js";
+import { materializeFileData } from "./materialize-file-data.js";
 
 export function applyFileDatabaseSchema(
 	lix: Pick<Lix, "sqlite" | "db" | "plugin" | "hooks">
 ): void {
 	lix.sqlite.createFunction({
 		name: "handle_file_insert",
-		arity: 6,
+		arity: 7,
 		xFunc: (_ctx: number, ...args: any[]) => {
 			// Parse metadata if it's a JSON string (SQLite converts objects to strings)
 			let metadata = args[3];
@@ -31,9 +31,10 @@ export function applyFileDatabaseSchema(
 					path: args[1],
 					data: args[2],
 					metadata: metadata,
+					hidden: Boolean(args[4]),
 				},
-				versionId: args[4],
-				untracked: Boolean(args[5]),
+				versionId: args[5],
+				untracked: Boolean(args[6]),
 			});
 			return result;
 		},
@@ -42,7 +43,7 @@ export function applyFileDatabaseSchema(
 
 	lix.sqlite.createFunction({
 		name: "handle_file_update",
-		arity: 6,
+		arity: 7,
 		xFunc: (_ctx: number, ...args: any[]) => {
 			// Parse metadata if it's a JSON string (SQLite converts objects to strings)
 			let metadata = args[3];
@@ -61,9 +62,10 @@ export function applyFileDatabaseSchema(
 					path: args[1],
 					data: args[2],
 					metadata: metadata,
+					hidden: Boolean(args[4]),
 				},
-				versionId: args[4],
-				untracked: Boolean(args[5]),
+				versionId: args[5],
+				untracked: Boolean(args[6]),
 			});
 			return result;
 		},
@@ -88,18 +90,18 @@ export function applyFileDatabaseSchema(
 	});
 
 	lix.sqlite.createFunction({
-		name: "materialize_file_data_at_changeset",
+		name: "materialize_file_data_at_commit",
 		arity: 5,
 		deterministic: false,
 		xFunc: (_ctx: number, ...args: any[]) => {
-			return materializeFileDataAtChangeset({
+			return materializeFileDataAtCommit({
 				lix,
 				file: {
 					id: args[0],
 					path: args[1],
 					metadata: args[4],
 				},
-				changeSetId: args[2],
+				rootCommitId: args[2],
 				depth: args[3],
 			});
 		},
@@ -107,53 +109,111 @@ export function applyFileDatabaseSchema(
 
 	lix.sqlite.exec(`
   CREATE VIEW IF NOT EXISTS file AS
-	SELECT
-		json_extract(snapshot_content, '$.id') AS id,
-		json_extract(snapshot_content, '$.path') AS path,
-		materialize_file_data(
-			json_extract(snapshot_content, '$.id'), 
-			json_extract(snapshot_content, '$.path'), 
-			version_id,
-			json_extract(snapshot_content, '$.metadata')
-		) AS data,
-		json_extract(snapshot_content, '$.metadata') AS metadata,
-		inherited_from_version_id AS lixcol_inherited_from_version_id,
-		created_at AS lixcol_created_at,
-		updated_at AS lixcol_updated_at,
-		change_id AS lixcol_change_id,
-		untracked AS lixcol_untracked
-	FROM state
-	WHERE schema_key = 'lix_file_descriptor';
+        WITH latest_file_change AS (
+            SELECT 
+                fd.entity_id as file_id,
+                -- Get the latest change across all entities in this file
+                (SELECT s.change_id 
+                 FROM state s 
+                 WHERE s.file_id = fd.entity_id
+                 ORDER BY s.updated_at DESC 
+                 LIMIT 1) as latest_change_id,
+                -- Get the latest change_set that contains any change for this file
+                (SELECT cse.change_set_id
+                 FROM change_set_element cse
+                 INNER JOIN state s ON s.change_id = cse.change_id
+                 WHERE s.file_id = fd.entity_id
+                 ORDER BY s.updated_at DESC
+                 LIMIT 1
+                ) as latest_change_set_id
+            FROM state fd
+            WHERE fd.schema_key = 'lix_file_descriptor'
+        )
+        SELECT
+                json_extract(fd.snapshot_content, '$.id') AS id,
+                json_extract(fd.snapshot_content, '$.path') AS path,
+                materialize_file_data(
+                        json_extract(fd.snapshot_content, '$.id'),
+                        json_extract(fd.snapshot_content, '$.path'),
+                        (SELECT version_id FROM active_version),
+                        json_extract(fd.snapshot_content, '$.metadata')
+                ) AS data,
+                json_extract(fd.snapshot_content, '$.metadata') AS metadata,
+                json_extract(fd.snapshot_content, '$.hidden') AS hidden,
+                fd.entity_id AS lixcol_entity_id,
+                'lix_file_descriptor' AS lixcol_schema_key,
+                fd.entity_id AS lixcol_file_id,  -- For files, file_id equals entity_id
+                fd.inherited_from_version_id AS lixcol_inherited_from_version_id,
+                -- Use the latest change info from any entity in the file
+                lc.latest_change_id AS lixcol_change_id,
+                (SELECT created_at FROM change WHERE id = lc.latest_change_id) AS lixcol_created_at,
+                (SELECT created_at FROM change WHERE id = lc.latest_change_id) AS lixcol_updated_at,
+                lc.latest_change_set_id AS lixcol_commit_id,
+                fd.untracked AS lixcol_untracked
+        FROM state fd
+        JOIN latest_file_change lc ON lc.file_id = fd.entity_id
+        WHERE fd.schema_key = 'lix_file_descriptor';
 
   CREATE VIEW IF NOT EXISTS file_all AS
-	SELECT
-		json_extract(snapshot_content, '$.id') AS id,
-		json_extract(snapshot_content, '$.path') AS path,
-		materialize_file_data(
-			json_extract(snapshot_content, '$.id'), 
-			json_extract(snapshot_content, '$.path'), 
-			version_id,
-			json_extract(snapshot_content, '$.metadata')
-		) AS data,
-		json_extract(snapshot_content, '$.metadata') AS metadata,
-		version_id AS lixcol_version_id,
-		inherited_from_version_id AS lixcol_inherited_from_version_id,
-		created_at AS lixcol_created_at,
-		updated_at AS lixcol_updated_at,
-		change_id AS lixcol_change_id,
-		untracked AS lixcol_untracked
-	FROM state_all
-	WHERE schema_key = 'lix_file_descriptor';
+        WITH latest_file_change AS (
+            SELECT 
+                fd.entity_id as file_id,
+                fd.version_id,
+                -- Get the latest change across all entities in this file for this version
+                (SELECT s.change_id 
+                 FROM state_all s 
+                 WHERE s.file_id = fd.entity_id
+                   AND s.version_id = fd.version_id
+                 ORDER BY s.updated_at DESC 
+                 LIMIT 1) as latest_change_id,
+                -- Get the latest change_set that contains any change for this file
+                (SELECT cse.change_set_id
+                 FROM change_set_element cse
+                 INNER JOIN state_all s ON s.change_id = cse.change_id
+                 WHERE s.file_id = fd.entity_id
+                   AND s.version_id = fd.version_id
+                 ORDER BY s.updated_at DESC
+                 LIMIT 1
+                ) as latest_change_set_id
+            FROM state_all fd
+            WHERE fd.schema_key = 'lix_file_descriptor'
+        )
+        SELECT
+                json_extract(fd.snapshot_content, '$.id') AS id,
+                json_extract(fd.snapshot_content, '$.path') AS path,
+                materialize_file_data(
+                        json_extract(fd.snapshot_content, '$.id'),
+                        json_extract(fd.snapshot_content, '$.path'),
+                        fd.version_id,
+                        json_extract(fd.snapshot_content, '$.metadata')
+                ) AS data,
+                json_extract(fd.snapshot_content, '$.metadata') AS metadata,
+                json_extract(fd.snapshot_content, '$.hidden') AS hidden,
+                fd.entity_id AS lixcol_entity_id,
+                'lix_file_descriptor' AS lixcol_schema_key,
+                fd.entity_id AS lixcol_file_id,  -- For files, file_id equals entity_id
+                fd.version_id AS lixcol_version_id,
+                fd.inherited_from_version_id AS lixcol_inherited_from_version_id,
+                -- Use the latest change info from any entity in the file
+                lc.latest_change_id AS lixcol_change_id,
+                (SELECT created_at FROM change WHERE id = lc.latest_change_id) AS lixcol_created_at,
+                (SELECT created_at FROM change WHERE id = lc.latest_change_id) AS lixcol_updated_at,
+                lc.latest_change_set_id AS lixcol_commit_id,
+                fd.untracked AS lixcol_untracked
+        FROM state_all fd
+        JOIN latest_file_change lc ON lc.file_id = fd.entity_id AND lc.version_id = fd.version_id
+        WHERE fd.schema_key = 'lix_file_descriptor';
 
 
   CREATE TRIGGER IF NOT EXISTS file_insert
   INSTEAD OF INSERT ON file
   BEGIN
       SELECT handle_file_insert(
-        COALESCE(NEW.id, nano_id()),
+        COALESCE(NEW.id, lix_nano_id()),
         NEW.path,
         NEW.data,
         NEW.metadata,
+        COALESCE(NEW.hidden, 0),
         (SELECT version_id FROM active_version),
         COALESCE(NEW.lixcol_untracked, 0)
       );
@@ -167,6 +227,7 @@ export function applyFileDatabaseSchema(
         NEW.path,
         NEW.data,
         NEW.metadata,
+        COALESCE(NEW.hidden, OLD.hidden),
         (SELECT version_id FROM active_version),
         COALESCE(NEW.lixcol_untracked, 0)
       );
@@ -192,10 +253,11 @@ export function applyFileDatabaseSchema(
   INSTEAD OF INSERT ON file_all
   BEGIN
       SELECT handle_file_insert(
-        COALESCE(NEW.id, nano_id()),
+        COALESCE(NEW.id, lix_nano_id()),
         NEW.path,
         NEW.data,
         NEW.metadata,
+        COALESCE(NEW.hidden, 0),
         COALESCE(NEW.lixcol_version_id, (SELECT version_id FROM active_version)),
         COALESCE(NEW.lixcol_untracked, 0)
       );
@@ -209,6 +271,7 @@ export function applyFileDatabaseSchema(
         NEW.path,
         NEW.data,
         NEW.metadata,
+        COALESCE(NEW.hidden, OLD.hidden),
         COALESCE(NEW.lixcol_version_id, OLD.lixcol_version_id),
         COALESCE(NEW.lixcol_untracked, 0)
       );
@@ -234,19 +297,23 @@ export function applyFileDatabaseSchema(
   SELECT
     json_extract(snapshot_content, '$.id') AS id,
     json_extract(snapshot_content, '$.path') AS path,
-    materialize_file_data_at_changeset(
+    materialize_file_data_at_commit(
       json_extract(snapshot_content, '$.id'),
       json_extract(snapshot_content, '$.path'),
-      change_set_id,
+      root_commit_id,
       depth,
       json_extract(snapshot_content, '$.metadata')
     ) AS data,
     json_extract(snapshot_content, '$.metadata') AS metadata,
+    json_extract(snapshot_content, '$.hidden') AS hidden,
+    entity_id AS lixcol_entity_id,
+    'lix_file_descriptor' AS lixcol_schema_key,
     file_id AS lixcol_file_id,
     plugin_key AS lixcol_plugin_key,
     schema_version AS lixcol_schema_version,
     change_id AS lixcol_change_id,
-    change_set_id AS lixcol_change_set_id,
+    commit_id AS lixcol_commit_id,
+    root_commit_id AS lixcol_root_commit_id,
     depth AS lixcol_depth
   FROM state_history
   WHERE schema_key = 'lix_file_descriptor';
@@ -271,6 +338,7 @@ export const LixFileDescriptorSchema = {
 			type: "object",
 			nullable: true,
 		},
+		hidden: { type: "boolean", "x-lix-generated": true },
 	},
 	required: ["id", "path"],
 	additionalProperties: false,
@@ -280,8 +348,38 @@ LixFileDescriptorSchema satisfies LixSchemaDefinition;
 /**
  * The file descriptor type representing the stored metadata for a file.
  *
- * This contains the file's identity and metadata but not the actual file content.
- * The file content (data) is materialized separately by aggregating entities from plugins.
+ * This is the underlying entity stored in the database with schema_key 'lix_file_descriptor'.
+ * It contains only the file's identity and metadata - NOT the actual file content.
+ *
+ * ```
+ * ┌─────────────────────────────────────────┐
+ * │         LixFileDescriptor               │
+ * │    (schema_key: 'lix_file_descriptor')  │
+ * ├─────────────────────────────────────────┤
+ * │ • id: string (file identifier)          │
+ * │ • path: string (e.g., "/docs/README.md")│
+ * │ • metadata: object | null               │
+ * │ • hidden: boolean                       │
+ * └─────────────────────────────────────────┘
+ *               ↓
+ *     Stored in state/state_all table
+ *               ↓
+ * ┌─────────────────────────────────────────┐
+ * │ File content entities are stored        │
+ * │ separately with file_id = descriptor.id │
+ * │                                         │
+ * │ • JSON properties (mock_json_property)  │
+ * │ • Markdown blocks (markdown_block)      │
+ * │ • CSV rows (csv_row)                    │
+ * │ • etc...                                │
+ * └─────────────────────────────────────────┘
+ * ```
+ *
+ * Key points:
+ * - File descriptors are just metadata - they don't contain file data
+ * - The actual file content is stored as separate entities linked by file_id
+ * - File views aggregate the descriptor + content entities into a complete file
+ * - Changes to file content don't update the descriptor (and vice versa)
  */
 export type LixFileDescriptor = FromLixSchemaDefinition<
 	typeof LixFileDescriptorSchema
@@ -291,9 +389,38 @@ export type LixFileDescriptor = FromLixSchemaDefinition<
  * Complete file type combining the descriptor with materialized data.
  *
  * Uses "Lix" prefix to avoid collision with JavaScript's built-in File type.
- * This represents the full file as seen in views, combining:
- * - LixFileDescriptor: stored metadata (id, path, metadata)
- * - data: materialized file content from plugin entities
+ *
+ * IMPORTANT: File views are projections over multiple entities, not just the file descriptor.
+ * However, they expose schema_key as 'lix_file_descriptor' to maintain foreign key integrity.
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │                        File View                            │
+ * │               (schema_key: 'lix_file_descriptor')           │
+ * │                                                             │
+ * │  ┌─────────────────────────┐   ┌─────────────────────────┐ │
+ * │  │   File Descriptor       │   │   Plugin Entities       │ │
+ * │  │ (lix_file_descriptor)   │   │                         │ │
+ * │  ├─────────────────────────┤   ├─────────────────────────┤ │
+ * │  │ • id                    │   │ • JSON properties       │ │
+ * │  │ • path                  │ + │ • Markdown blocks       │ │
+ * │  │ • metadata              │   │ • CSV rows              │ │
+ * │  │ • hidden                │   │ • Future: thumbnails    │ │
+ * │  └─────────────────────────┘   └─────────────────────────┘ │
+ * │                    ↓                       ↓                │
+ * │              ┌─────────────────────────────────┐           │
+ * │              │    Materialized as LixFile      │           │
+ * │              │  • All descriptor fields        │           │
+ * │              │  • data: Uint8Array (from       │           │
+ * │              │    plugin entities)             │           │
+ * │              └─────────────────────────────────┘           │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * This projection approach means:
+ * - File views aggregate changes from ALL entities within the file
+ * - The 'data' field is dynamically materialized from plugin entities
+ * - A single file view row represents multiple underlying entities
  */
 export type LixFile = LixFileDescriptor & {
 	data: Uint8Array;

package/src/hooks/create-hooks.ts

@@ -1,3 +1,5 @@
+import type { Change } from "../change/index.js";
+
 /**
  * Lix hooks system for listening to database lifecycle events.
  *
@@ -25,35 +27,7 @@ export type LixHooks = {
 	 * unsubscribe();
 	 * ```
 	 */
-	onStateCommit: (handler: () => void) => () => void;
-
-	/**
-	 * Listen to file change events.
-	 *
-	 * Note: This API will become redundant once subscriptions are implemented.
-	 *
-	 * Fires when a file is inserted, updated, or deleted in the database.
-	 * Useful for updating UI, triggering re-parsing, or synchronizing external systems.
-	 *
-	 * @param handler - Function to call when a file changes
-	 * @returns Unsubscribe function to remove the listener
-	 *
-	 * @example
-	 * ```typescript
-	 * const unsubscribe = lix.hooks.onFileChange((fileId, operation) => {
-	 *   console.log(`File ${fileId} was ${operation}`);
-	 *   if (operation === 'updated') {
-	 *     reloadEditor(fileId);
-	 *   }
-	 * });
-	 *
-	 * // Later, remove the listener
-	 * unsubscribe();
-	 * ```
-	 */
-	onFileChange: (
-		handler: (fileId: string, operation: "inserted" | "updated") => void
-	) => () => void;
+	onStateCommit: (handler: (data: { changes: Change[] }) => void) => () => void;
 
 	/**
 	 * Internal method for emitting events.
@@ -77,21 +51,14 @@ export function createHooks(): LixHooks {
 	const eventTarget = new EventTarget();
 
 	return {
-		onStateCommit(handler: () => void): () => void {
-			eventTarget.addEventListener("state_commit", handler);
-			return () => eventTarget.removeEventListener("state_commit", handler);
-		},
-
-		onFileChange(
-			handler: (fileId: string, operation: "inserted" | "updated") => void
-		): () => void {
+		onStateCommit(handler: (data: { changes: Change[] }) => void): () => void {
 			const wrappedHandler = (event: Event) => {
 				const customEvent = event as CustomEvent;
-				handler(customEvent.detail.fileId, customEvent.detail.operation);
+				handler(customEvent.detail);
 			};
-			eventTarget.addEventListener("file_change", wrappedHandler);
+			eventTarget.addEventListener("state_commit", wrappedHandler);
 			return () =>
-				eventTarget.removeEventListener("file_change", wrappedHandler);
+				eventTarget.removeEventListener("state_commit", wrappedHandler);
 		},
 
 		_emit(eventType: string, data?: any): void {

package/src/index.ts

@@ -2,7 +2,10 @@ export * from "./account/index.js";
 export * from "./change/index.js";
 export * from "./change-author/index.js";
 export * from "./change-set/index.js";
+export * from "./commit/index.js";
 export * from "./database/index.js";
+export * from "./deterministic/index.js";
+export * from "./entity/index.js";
 export * from "./entity-views/index.js";
 export * from "./file/index.js";
 export * from "./hooks/create-hooks.js";

package/src/key-value/index.ts

@@ -1 +1 @@
-export { LixKeyValueSchema, type KeyValue } from "./schema.js";
+export { LixKeyValueSchema, type LixKeyValue as KeyValue } from "./schema.js";

package/src/key-value/schema.test.ts

@@ -1,6 +1,7 @@
 import { expect, test } from "vitest";
 import { openLix } from "../lix/open-lix.js";
 import { createVersion } from "../version/create-version.js";
+import { sql } from "kysely";
 
 test("inserts, updates, deletes are handled", async () => {
 	const lix = await openLix({});
@@ -88,7 +89,7 @@ test("arbitrary json is allowed", async () => {
 	expect(viewAfterInsert).toEqual(kvs);
 });
 
-test.todo("view should show changes across versions", async () => {
+test("view should show changes across versions", async () => {
 	const lix = await openLix({});
 
 	// creating a new version
@@ -129,7 +130,7 @@ test.todo("view should show changes across versions", async () => {
 		lix,
 		id: "versionB",
 		name: "versionB",
-		changeSet: { id: versionAAfterKvInsert.change_set_id },
+		commit_id: versionAAfterKvInsert.commit_id,
 	});
 
 	const kvAfterInsertInVersionB = await lix.db
@@ -177,3 +178,103 @@ test.todo("view should show changes across versions", async () => {
 		},
 	]);
 });
+
+test("can update individual JSON properties using SQLite JSON functions", async () => {
+	const lix = await openLix({});
+
+	// Insert a complex JSON object
+	await lix.db
+		.insertInto("key_value")
+		.values({
+			key: "test_config",
+			value: {
+				enabled: true,
+				settings: {
+					theme: "dark",
+					language: "en",
+					notifications: true,
+				},
+				features: ["feature1", "feature2"],
+				count: 42,
+			},
+		})
+		.execute();
+
+	// First check the initial insert worked
+	const initialValue = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select("value")
+		.executeTakeFirst();
+
+	expect(initialValue?.value).toBeDefined();
+
+	// Update a single nested property using json_set
+	await lix.db
+		.updateTable("key_value")
+		.set({
+			value: sql`json_set(value, '$.settings.theme', 'light')`,
+		})
+		.where("key", "=", "test_config")
+		.execute();
+
+	const afterThemeUpdate = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select("value")
+		.executeTakeFirst();
+
+	expect(afterThemeUpdate?.value).toMatchObject({
+		enabled: true,
+		settings: {
+			theme: "light", // Changed
+			language: "en",
+			notifications: true,
+		},
+		features: ["feature1", "feature2"],
+		count: 42,
+	});
+
+	// Update multiple properties at once
+	await lix.db
+		.updateTable("key_value")
+		.set({
+			value: sql`json_set(value, '$.enabled', false, '$.count', 100, '$.settings.notifications', false)`,
+		})
+		.where("key", "=", "test_config")
+		.execute();
+
+	const afterMultiUpdate = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select("value")
+		.executeTakeFirst();
+
+	expect(afterMultiUpdate?.value).toMatchObject({
+		enabled: 0, // Changed - SQLite stores false as 0
+		settings: {
+			theme: "light",
+			language: "en",
+			notifications: 0, // Changed - SQLite stores false as 0
+		},
+		features: ["feature1", "feature2"],
+		count: 100, // Changed
+	});
+
+	// Read specific properties using JSON operators
+	const specificProps = await lix.db
+		.selectFrom("key_value")
+		.where("key", "=", "test_config")
+		.select([
+			sql<boolean>`value ->> '$.enabled'`.as("enabled"),
+			sql<string>`value ->> '$.settings.theme'`.as("theme"),
+			sql<number>`value ->> '$.count'`.as("count"),
+		])
+		.executeTakeFirst();
+
+	expect(specificProps).toEqual({
+		enabled: 0, // SQLite returns 0 for false
+		theme: "light",
+		count: 100,
+	});
+});

package/src/key-value/schema.ts

@@ -1,14 +1,16 @@
-import type { SqliteWasmDatabase } from "sqlite-wasm-kysely";
 import type {
 	LixSchemaDefinition,
 	FromLixSchemaDefinition,
 } from "../schema-definition/definition.js";
 import { JSONTypeSchema } from "../schema-definition/json-type.js";
 import { createEntityViewsIfNotExists } from "../entity-views/entity-view-builder.js";
+import type { Lix } from "../index.js";
 
-export function applyKeyValueDatabaseSchema(sqlite: SqliteWasmDatabase): void {
+export function applyKeyValueDatabaseSchema(
+	lix: Pick<Lix, "sqlite" | "db">
+): void {
 	return createEntityViewsIfNotExists({
-		lix: { sqlite },
+		lix,
 		schema: LixKeyValueSchema,
 		overrideName: "key_value",
 		pluginKey: "lix_own_entity",
@@ -16,6 +18,12 @@ export function applyKeyValueDatabaseSchema(sqlite: SqliteWasmDatabase): void {
 	});
 }
 
+/**
+ * Schema definition for key-value pairs in Lix.
+ *
+ * Key-value pairs provide a flexible storage mechanism for configuration,
+ * settings, and metadata within a Lix instance.
+ */
 export const LixKeyValueSchema = {
 	"x-lix-key": "lix_key_value",
 	"x-lix-version": "1.0",
@@ -30,8 +38,61 @@ export const LixKeyValueSchema = {
 } as const;
 LixKeyValueSchema satisfies LixSchemaDefinition;
 
-// Pure business logic type (inferred from schema)
-export type KeyValue = FromLixSchemaDefinition<typeof LixKeyValueSchema> & {
+/**
+ * Represents a key-value pair in Lix.
+ *
+ * The value can be any JSON-serializable type (string, number, boolean, object, array, null).
+ *
+ * **Important SQLite Limitation with Boolean Values:**
+ * SQLite does not have a native boolean type. When storing JSON values:
+ * - `true` is stored as `1`
+ * - `false` is stored as `0`
+ *
+ * This is a fundamental limitation of SQLite's JSON implementation. There is no way
+ * to distinguish between a boolean `true` and the number `1` after retrieval.
+ *
+ * When querying boolean values, use loose equality (`==`) or handle the numeric representation.
+ *
+ * @example
+ * ```typescript
+ * // Inserting key-value pairs
+ * await lix.db.insertInto("key_value").values({
+ *   key: "lix_sync_enabled",
+ *   value: true  // Will be stored as 1 in SQLite
+ * }).execute();
+ *
+ * await lix.db.insertInto("key_value").values({
+ *   key: "lix_server_url",
+ *   value: "https://api.example.com"
+ * }).execute();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Querying boolean values
+ * const result = await lix.db
+ *   .selectFrom("key_value")
+ *   .where("key", "=", "lix_sync_enabled")
+ *   .select("value")
+ *   .executeTakeFirst();
+ *
+ * // result.value will be 1 (not true)
+ * const isEnabled = result?.value == true; // Use loose equality
+ * // or
+ * const isEnabled = result?.value === 1; // Check for numeric value
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Common Lix system keys
+ * // "lix_id" - Unique identifier for the Lix instance
+ * // "lix_name" - Human-readable name for the Lix instance
+ * // "lix_server_url" - URL of the sync server
+ * // "lix_deterministic_mode" - Boolean flag for deterministic ID generation
+ * // "lix_telemetry" - Telemetry setting ("on" or "off")
+ * ```
+ */
+export type LixKeyValue = FromLixSchemaDefinition<typeof LixKeyValueSchema> & {
 	// override the value to any to allow any JSON type (instead of unknown which is annoying)
 	value: any;
 };