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

package/src/state/validate-state-mutation.test.ts

@@ -2,9 +2,10 @@ import { test, expect } from "vitest";
 import { openLix } from "../lix/open-lix.js";
 import { validateStateMutation } from "./validate-state-mutation.js";
 import type { LixSchemaDefinition } from "../schema-definition/definition.js";
-import { sql } from "kysely";
+import { Kysely, sql } from "kysely";
 import { createVersion } from "../version/create-version.js";
-import type { ChangeSetElement } from "../change-set/schema.js";
+import type { LixChangeSetElement } from "../change-set/schema.js";
+import type { LixInternalDatabaseSchema } from "../database/schema.js";
 
 test("throws if the schema is not a valid lix schema", async () => {
 	const lix = await openLix({});
@@ -563,12 +564,15 @@ test("passes when foreign key references exist", async () => {
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -643,12 +647,15 @@ test("throws when foreign key reference does not exist", async () => {
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -719,16 +726,22 @@ test("handles multiple foreign keys", async () => {
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-			category_id: {
-				schemaKey: "category",
-				property: "id",
+			{
+				properties: ["category_id"],
+				references: {
+					schemaKey: "category",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -839,12 +852,15 @@ test("allows null foreign key values", async () => {
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: ["string", "null"] },
@@ -895,6 +911,124 @@ test("allows null foreign key values", async () => {
 	).not.toThrowError();
 });
 
+test("handles composite foreign keys", async () => {
+	const lix = await openLix({});
+
+	// Create a schema that uses composite primary key
+	const addressSchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "address",
+		"x-lix-primary-key": ["country", "postal_code", "street"],
+		properties: {
+			country: { type: "string" },
+			postal_code: { type: "string" },
+			street: { type: "string" },
+			city: { type: "string" },
+		},
+		required: ["country", "postal_code", "street", "city"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Create a schema that references the composite key
+	const deliverySchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "delivery",
+		"x-lix-primary-key": ["id"],
+		"x-lix-foreign-keys": [
+			{
+				properties: ["address_country", "address_postal", "address_street"],
+				references: {
+					schemaKey: "address",
+					properties: ["country", "postal_code", "street"],
+				},
+			},
+		],
+		properties: {
+			id: { type: "string" },
+			address_country: { type: "string" },
+			address_postal: { type: "string" },
+			address_street: { type: "string" },
+			package_id: { type: "string" },
+		},
+		required: [
+			"id",
+			"address_country",
+			"address_postal",
+			"address_street",
+			"package_id",
+		],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Store schemas
+	await lix.db
+		.insertInto("stored_schema")
+		.values([{ value: addressSchema }, { value: deliverySchema }])
+		.execute();
+
+	// Insert an address that will be referenced
+	await lix.db
+		.insertInto("state_all")
+		.values({
+			entity_id: "addr1",
+			file_id: "file1",
+			schema_key: "address",
+			plugin_key: "test_plugin",
+			version_id: lix.db.selectFrom("active_version").select("version_id"),
+			snapshot_content: {
+				country: "USA",
+				postal_code: "12345",
+				street: "123 Main St",
+				city: "Springfield",
+			},
+			schema_version: "1.0",
+		})
+		.execute();
+
+	const activeVersion = await lix.db
+		.selectFrom("active_version")
+		.select("version_id")
+		.executeTakeFirstOrThrow();
+
+	// This should pass - composite foreign key reference exists
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: deliverySchema,
+			snapshot_content: {
+				id: "delivery1",
+				address_country: "USA",
+				address_postal: "12345",
+				address_street: "123 Main St",
+				package_id: "pkg123",
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).not.toThrowError();
+
+	// This should fail - composite foreign key reference doesn't exist (wrong postal code)
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: deliverySchema,
+			snapshot_content: {
+				id: "delivery2",
+				address_country: "USA",
+				address_postal: "54321", // Wrong postal code
+				address_street: "123 Main St",
+				package_id: "pkg456",
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).toThrowError(
+		/Foreign key constraint violation.*address_country, address_postal, address_street.*referencing.*address.*country, postal_code, street/
+	);
+});
+
 test("foreign key referencing real SQL table (change.id)", async () => {
 	const lix = await openLix({});
 
@@ -926,12 +1060,15 @@ test("foreign key referencing real SQL table (change.id)", async () => {
 		type: "object",
 		"x-lix-version": "1.0",
 		"x-lix-key": "change_set_element_test",
-		"x-lix-foreign-keys": {
-			change_id: {
-				schemaKey: "lix_change",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["change_id"],
+				references: {
+					schemaKey: "lix_change",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			change_id: { type: "string" },
@@ -1216,12 +1353,15 @@ test("should prevent deletion when foreign keys reference the entity", async ()
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -1420,20 +1560,40 @@ test("should throw when entity_id is missing for delete operations", async () =>
 test("should handle deletion validation for change sets referenced by versions", async () => {
 	const lix = await openLix({});
 
-	// Create a change set
+	// Create change sets
 	await lix.db
 		.insertInto("change_set_all")
-		.values({ id: "cs_referenced", lixcol_version_id: "global" })
+		.values([
+			{ id: "cs_referenced", lixcol_version_id: "global" },
+			{ id: "cs_working", lixcol_version_id: "global" },
+		])
+		.execute();
+
+	// Create commits that reference the change sets
+	await lix.db
+		.insertInto("commit_all")
+		.values([
+			{
+				id: "commit_1",
+				change_set_id: "cs_referenced",
+				lixcol_version_id: "global",
+			},
+			{
+				id: "working_commit_1",
+				change_set_id: "cs_working",
+				lixcol_version_id: "global",
+			},
+		])
 		.execute();
 
-	// Create a version that references the change set
+	// Create a version that references the commits
 	await lix.db
 		.insertInto("version")
 		.values({
 			id: "v1",
 			name: "test_version",
-			change_set_id: "cs_referenced",
-			working_change_set_id: "cs_referenced",
+			commit_id: "commit_1",
+			working_commit_id: "working_commit_1",
 		})
 		.execute();
 
@@ -1460,7 +1620,7 @@ test("should handle deletion validation for change sets referenced by versions",
 			version_id: "global",
 		})
 	).toThrowError(
-		/Foreign key constraint violation.*Cannot delete entity.*referenced by.*lix_version/i
+		/Foreign key constraint violation.*Cannot delete entity.*referenced by.*lix_commit/i
 	);
 });
 
@@ -1586,12 +1746,15 @@ test("foreign key validation should fail when referenced entity exists in differ
 		"x-lix-key": "mock_post",
 		"x-lix-version": "1.0",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "mock_user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "mock_user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		type: "object",
 		properties: {
 			id: { type: "string" },
@@ -1690,12 +1853,15 @@ test("should allow self-referential foreign keys", async () => {
 		"x-lix-version": "1.0",
 		"x-lix-key": "mock_version",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			inherits_from_version_id: {
-				schemaKey: "mock_version", // Self-referential foreign key
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["inherits_from_version_id"],
+				references: {
+					schemaKey: "mock_version", // Self-referential foreign key
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			name: { type: "string" },
@@ -1789,12 +1955,15 @@ test("should allow self-referential foreign keys for update operations", async (
 		"x-lix-version": "1.0",
 		"x-lix-key": "mock_version",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			inherits_from_version_id: {
-				schemaKey: "mock_version",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["inherits_from_version_id"],
+				references: {
+					schemaKey: "mock_version",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			name: { type: "string" },
@@ -1890,12 +2059,15 @@ test("should prevent deletion when self-referential foreign keys reference the e
 		"x-lix-version": "1.0",
 		"x-lix-key": "mock_version",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			inherits_from_version_id: {
-				schemaKey: "mock_version",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["inherits_from_version_id"],
+				references: {
+					schemaKey: "mock_version",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			name: { type: "string" },
@@ -2078,7 +2250,7 @@ test("should prevent change set elements from referencing change sets defined in
 				entity_id: "dummy_entity_id",
 				file_id: "dummy_file_id",
 				schema_key: "dummy_schema_key",
-			} satisfies ChangeSetElement,
+			} satisfies LixChangeSetElement,
 			operation: "insert",
 			version_id: activeVersion.version_id, // But creating element in active version context
 		})
@@ -2114,12 +2286,15 @@ test("should prevent tracked entities from referencing untracked entities", asyn
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -2202,12 +2377,15 @@ test("should allow untracked entities to reference tracked entities", async () =
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -2290,12 +2468,15 @@ test("should allow untracked entities to reference other untracked entities", as
 		"x-lix-version": "1.0",
 		"x-lix-key": "post",
 		"x-lix-primary-key": ["id"],
-		"x-lix-foreign-keys": {
-			author_id: {
-				schemaKey: "user",
-				property: "id",
+		"x-lix-foreign-keys": [
+			{
+				properties: ["author_id"],
+				references: {
+					schemaKey: "user",
+					properties: ["id"],
+				},
 			},
-		},
+		],
 		properties: {
 			id: { type: "string" },
 			author_id: { type: "string" },
@@ -2351,3 +2532,777 @@ test("should allow untracked entities to reference other untracked entities", as
 	// This should PASS - untracked entity can reference another untracked entity
 	expect(() => validateStateMutation(validationArgs)).not.toThrow();
 });
+
+test("should detect and prevent cycles in commit graph when lix_debug is enabled", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_debug", value: "true" }],
+	});
+
+	// Get the commit edge schema
+	const commitEdgeSchema = await lix.db
+		.selectFrom("stored_schema")
+		.select("value")
+		.where("key", "=", "lix_commit_edge")
+		.executeTakeFirstOrThrow();
+
+	// Create a few change sets and commits
+	await lix.db
+		.insertInto("change_set_all")
+		.values([
+			{ id: "cs1", lixcol_version_id: "global" },
+			{ id: "cs2", lixcol_version_id: "global" },
+			{ id: "cs3", lixcol_version_id: "global" },
+		])
+		.execute();
+
+	await lix.db
+		.insertInto("commit_all")
+		.values([
+			{ id: "commit1", change_set_id: "cs1", lixcol_version_id: "global" },
+			{ id: "commit2", change_set_id: "cs2", lixcol_version_id: "global" },
+			{ id: "commit3", change_set_id: "cs3", lixcol_version_id: "global" },
+		])
+		.execute();
+
+	// Create edges: commit1 -> commit2 -> commit3
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values([
+			{
+				parent_id: "commit1",
+				child_id: "commit2",
+				lixcol_version_id: "global",
+			},
+			{
+				parent_id: "commit2",
+				child_id: "commit3",
+				lixcol_version_id: "global",
+			},
+		])
+		.execute();
+
+	// This should fail - creating commit3 -> commit1 would create a cycle
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: commitEdgeSchema.value as LixSchemaDefinition,
+			snapshot_content: {
+				parent_id: "commit3",
+				child_id: "commit1", // This would complete the cycle
+			},
+			operation: "insert",
+			version_id: "global",
+		})
+	).toThrowError(
+		/Cycle detected in commit graph.*New edge: commit3 -> commit1.*Cycle path: commit1 -> commit2 -> commit3 -> commit1/s
+	);
+
+	// This should also fail - self-loop
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: commitEdgeSchema.value as LixSchemaDefinition,
+			snapshot_content: {
+				parent_id: "commit1",
+				child_id: "commit1", // Self-referencing edge
+			},
+			operation: "insert",
+			version_id: "global",
+		})
+	).toThrowError(/Self-referencing edges are not allowed/);
+});
+
+test("should not check for cycles when lix_debug is disabled", async () => {
+	const lix = await openLix({
+		keyValues: [{ key: "lix_debug", value: "false" }],
+	});
+
+	// Get the commit edge schema
+	const commitEdgeSchema = await lix.db
+		.selectFrom("stored_schema")
+		.select("value")
+		.where("key", "=", "lix_commit_edge")
+		.executeTakeFirstOrThrow();
+
+	// Create a few change sets and commits
+	await lix.db
+		.insertInto("change_set_all")
+		.values([
+			{ id: "cs1", lixcol_version_id: "global" },
+			{ id: "cs2", lixcol_version_id: "global" },
+			{ id: "cs3", lixcol_version_id: "global" },
+		])
+		.execute();
+
+	await lix.db
+		.insertInto("commit_all")
+		.values([
+			{ id: "commit1", change_set_id: "cs1", lixcol_version_id: "global" },
+			{ id: "commit2", change_set_id: "cs2", lixcol_version_id: "global" },
+			{ id: "commit3", change_set_id: "cs3", lixcol_version_id: "global" },
+		])
+		.execute();
+
+	// Create edges: commit1 -> commit2 -> commit3
+	await lix.db
+		.insertInto("commit_edge_all")
+		.values([
+			{
+				parent_id: "commit1",
+				child_id: "commit2",
+				lixcol_version_id: "global",
+			},
+			{
+				parent_id: "commit2",
+				child_id: "commit3",
+				lixcol_version_id: "global",
+			},
+		])
+		.execute();
+
+	// This would create a cycle, but with lix_debug=false it won't be detected
+	// (This is intentional for performance - cycle detection is expensive)
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: commitEdgeSchema.value as LixSchemaDefinition,
+			snapshot_content: {
+				parent_id: "commit3",
+				child_id: "commit1", // This would complete the cycle
+			},
+			operation: "insert",
+			version_id: "global",
+		})
+	).not.toThrowError();
+});
+
+test("should validate foreign keys that reference changes in internal_change_in_transaction during transaction", async () => {
+	const lix = await openLix({});
+
+	// Create a simple mock schema that references a change
+	const mockChangeReferencingSchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "mock_change_reference",
+		"x-lix-primary-key": ["change_id"],
+		"x-lix-foreign-keys": [
+			{
+				properties: ["change_id"],
+				references: {
+					schemaKey: "lix_change",
+					properties: ["id"],
+				},
+			},
+		],
+		properties: {
+			change_id: { type: "string" },
+		},
+		required: ["change_id"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Store the mock schema
+	await lix.db
+		.insertInto("stored_schema")
+		.values({ value: mockChangeReferencingSchema })
+		.execute();
+
+	// Get active version
+	const activeVersion = await lix.db
+		.selectFrom("active_version")
+		.select("version_id")
+		.executeTakeFirstOrThrow();
+
+	await lix.db.transaction().execute(async (trx) => {
+		// Insert a key-value entity which creates a change in internal_change_in_transaction
+		await trx
+			.insertInto("key_value")
+			.values({
+				key: "test_key_for_change_reference",
+				value: "test_value",
+			})
+			.execute();
+
+		// Get the change ID that was just created in internal_change_in_transaction
+		const changes = await (trx as unknown as Kysely<LixInternalDatabaseSchema>)
+			.selectFrom("internal_change_in_transaction")
+			.select("id")
+			.where("entity_id", "=", "test_key_for_change_reference")
+			.where("schema_key", "=", "lix_key_value")
+			.execute();
+
+		expect(changes).toHaveLength(1);
+		const changeId = changes[0]!.id;
+
+		// This should NOT throw an error because the change exists in internal_change_in_transaction
+		// But currently it will throw because validation only checks the "change" table (internal_change)
+		// which doesn't include internal_change_in_transaction
+		expect(() =>
+			validateStateMutation({
+				lix: { sqlite: lix.sqlite, db: trx as any },
+				schema: mockChangeReferencingSchema,
+				snapshot_content: {
+					change_id: changeId,
+				},
+				operation: "insert",
+				version_id: activeVersion.version_id,
+			})
+		).not.toThrowError();
+	});
+});
+
+/**
+ * 🧪 Regression-guard for “versionless change FKs”
+ *
+ * Context from architecture discussion:
+ * ─────────────────────────────────────
+ * • `lix_change` rows are **version-agnostic** (no `version_id` column) and
+ *   append-only.  They form the immutable source-of-truth that every branch
+ *   materialises state from.
+ *
+ * • Therefore **any** version-scoped table is allowed to carry a foreign key
+ *   that points at `lix_change.id`, because the target row can never disappear
+ *   or mutate in a way that would break the reference.
+ *
+ * • The validator treats these targets specially: if the referenced schema’s
+ *   scope is `versionless`, it skips the usual “same version” check.
+ *
+ * What this test proves:
+ * ──────────────────────
+ * 1. A table that references `lix_change.id` can be inserted **in the global
+ *    context**.
+ * 2. The **same row** can also be inserted in an arbitrary branch
+ *    (`activeVersion.version_id`) without triggering a
+ *    “foreign-key constraint violation”.
+ *
+ * If either expectation starts failing, it means the validator has regressed
+ * and is once again enforcing version isolation for versionless targets—
+ * something we explicitly decided against.
+ */
+test("should allow foreign keys to changes from any version context", async () => {
+	const lix = await openLix({});
+
+	// Create a schema that references change.id (like change_author does)
+	const mockSchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "mock_schema",
+		"x-lix-primary-key": ["change_id"],
+		"x-lix-foreign-keys": [
+			{
+				properties: ["change_id"],
+				references: {
+					schemaKey: "lix_change",
+					properties: ["id"],
+				},
+			},
+		],
+		properties: {
+			change_id: { type: "string" },
+		},
+		required: ["change_id"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Store the schema
+	await lix.db
+		.insertInto("stored_schema")
+		.values({ value: mockSchema })
+		.execute();
+
+	const activeVersion = await lix.db
+		.selectFrom("active_version")
+		.select("version_id")
+		.executeTakeFirstOrThrow();
+
+	// First create a key-value entity to generate a real change
+	await lix.db
+		.insertInto("key_value")
+		.values({
+			key: "test_key_for_change_ref",
+			value: "test_value",
+		})
+		.execute();
+
+	// Get the change that was created
+	const changes = await lix.db
+		.selectFrom("change")
+		.where("entity_id", "=", "test_key_for_change_ref")
+		.where("schema_key", "=", "lix_key_value")
+		.selectAll()
+		.execute();
+
+	expect(changes).toHaveLength(1);
+	const realChangeId = changes[0]!.id;
+
+	// This should PASS because changes are versionless and can be referenced from global version
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockSchema,
+			snapshot_content: {
+				change_id: realChangeId,
+			},
+			operation: "insert",
+			version_id: "global",
+		})
+	).not.toThrowError();
+
+	// This should ALSO PASS because changes are versionless and can be referenced from any version
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockSchema,
+			snapshot_content: {
+				change_id: realChangeId,
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).not.toThrowError();
+});
+
+// State table foreign key tests
+test("should validate composite foreign keys referencing state table", async () => {
+	const lix = await openLix({});
+
+	// Create a schema that references state table with composite key (like entity_label does)
+	const mockStateReferenceSchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "mock_state_reference",
+		"x-lix-primary-key": ["entity_id", "schema_key", "file_id", "tag"],
+		"x-lix-foreign-keys": [
+			{
+				properties: ["entity_id", "schema_key", "file_id"],
+				references: {
+					schemaKey: "state",
+					properties: ["entity_id", "schema_key", "file_id"],
+				},
+			},
+		],
+		properties: {
+			entity_id: { type: "string" },
+			schema_key: { type: "string" },
+			file_id: { type: "string" },
+			tag: { type: "string" },
+		},
+		required: ["entity_id", "schema_key", "file_id", "tag"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Store the schema
+	await lix.db
+		.insertInto("stored_schema")
+		.values({ value: mockStateReferenceSchema })
+		.execute();
+
+	const activeVersion = await lix.db
+		.selectFrom("active_version")
+		.select("version_id")
+		.executeTakeFirstOrThrow();
+
+	// First create a state entity that can be referenced
+	await lix.db
+		.insertInto("state_all")
+		.values({
+			entity_id: "test_entity",
+			schema_key: "test_schema",
+			file_id: "test_file.json",
+			plugin_key: "test_plugin",
+			version_id: activeVersion.version_id,
+			snapshot_content: { id: "test_entity" },
+			schema_version: "1.0",
+		})
+		.execute();
+
+	// This should PASS - entity exists in state table
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockStateReferenceSchema,
+			snapshot_content: {
+				entity_id: "test_entity",
+				schema_key: "test_schema",
+				file_id: "test_file.json",
+				tag: "important",
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).not.toThrowError();
+
+	// This should FAIL - entity doesn't exist in state table
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockStateReferenceSchema,
+			snapshot_content: {
+				entity_id: "nonexistent_entity",
+				schema_key: "test_schema",
+				file_id: "test_file.json",
+				tag: "important",
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).toThrow(
+		/Foreign key constraint violation.*mock_state_reference.*\(entity_id, schema_key, file_id\).*state\.\(entity_id, schema_key, file_id\).*no matching record exists/
+	);
+});
+
+test("state foreign key references should respect version context", async () => {
+	const lix = await openLix({});
+
+	// Create a schema that references state table
+	const mockStateReferenceSchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "mock_state_reference",
+		"x-lix-primary-key": ["entity_id", "schema_key", "file_id", "tag"],
+		"x-lix-foreign-keys": [
+			{
+				properties: ["entity_id", "schema_key", "file_id"],
+				references: {
+					schemaKey: "state",
+					properties: ["entity_id", "schema_key", "file_id"],
+				},
+			},
+		],
+		properties: {
+			entity_id: { type: "string" },
+			schema_key: { type: "string" },
+			file_id: { type: "string" },
+			tag: { type: "string" },
+		},
+		required: ["entity_id", "schema_key", "file_id", "tag"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Store the schema
+	await lix.db
+		.insertInto("stored_schema")
+		.values({ value: mockStateReferenceSchema })
+		.execute();
+
+	// Create a second version
+	const version2 = await createVersion({
+		lix,
+		name: "version2",
+	});
+
+	// Get the main version
+	const mainVersion = await lix.db
+		.selectFrom("version")
+		.select("id")
+		.where("name", "=", "main")
+		.executeTakeFirstOrThrow();
+
+	// Create state entity in main version only
+	await lix.db
+		.insertInto("state_all")
+		.values({
+			entity_id: "main_only_entity",
+			schema_key: "test_schema",
+			file_id: "test.json",
+			plugin_key: "test_plugin",
+			version_id: mainVersion.id,
+			snapshot_content: { id: "main_only_entity" },
+			schema_version: "1.0",
+		})
+		.execute();
+
+	// Create state entity in version2 only
+	await lix.db
+		.insertInto("state_all")
+		.values({
+			entity_id: "version2_only_entity",
+			schema_key: "test_schema",
+			file_id: "test.json",
+			plugin_key: "test_plugin",
+			version_id: version2.id,
+			snapshot_content: { id: "version2_only_entity" },
+			schema_version: "1.0",
+		})
+		.execute();
+
+	// Reference from main version should only see main entities
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockStateReferenceSchema,
+			snapshot_content: {
+				entity_id: "main_only_entity",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				tag: "tag1",
+			},
+			operation: "insert",
+			version_id: mainVersion.id,
+		})
+	).not.toThrowError();
+
+	// Reference from main version to version2 entity should fail
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockStateReferenceSchema,
+			snapshot_content: {
+				entity_id: "version2_only_entity",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				tag: "tag2",
+			},
+			operation: "insert",
+			version_id: mainVersion.id,
+		})
+	).toThrow(/Foreign key constraint violation/);
+
+	// Reference from version2 should only see version2 entities
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockStateReferenceSchema,
+			snapshot_content: {
+				entity_id: "version2_only_entity",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				tag: "tag3",
+			},
+			operation: "insert",
+			version_id: version2.id,
+		})
+	).not.toThrowError();
+
+	// Reference from version2 to main entity should fail
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockStateReferenceSchema,
+			snapshot_content: {
+				entity_id: "main_only_entity",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				tag: "tag4",
+			},
+			operation: "insert",
+			version_id: version2.id,
+		})
+	).toThrow(/Foreign key constraint violation/);
+});
+
+test("state foreign key references should handle inherited entities", async () => {
+	const lix = await openLix({});
+
+	// Create a schema that references state table
+	const mockStateReferenceSchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "mock_state_reference",
+		"x-lix-primary-key": ["entity_id", "schema_key", "file_id", "tag"],
+		"x-lix-foreign-keys": [
+			{
+				properties: ["entity_id", "schema_key", "file_id"],
+				references: {
+					schemaKey: "state",
+					properties: ["entity_id", "schema_key", "file_id"],
+				},
+			},
+		],
+		properties: {
+			entity_id: { type: "string" },
+			schema_key: { type: "string" },
+			file_id: { type: "string" },
+			tag: { type: "string" },
+		},
+		required: ["entity_id", "schema_key", "file_id", "tag"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Store the schema
+	await lix.db
+		.insertInto("stored_schema")
+		.values({ value: mockStateReferenceSchema })
+		.execute();
+
+	// Get the main version
+	const mainVersion = await lix.db
+		.selectFrom("version")
+		.select("id")
+		.where("name", "=", "main")
+		.executeTakeFirstOrThrow();
+
+	// Create a state entity in main version
+	await lix.db
+		.insertInto("state_all")
+		.values({
+			entity_id: "shared_entity",
+			schema_key: "test_schema",
+			file_id: "test.json",
+			plugin_key: "test_plugin",
+			version_id: mainVersion.id,
+			snapshot_content: { id: "shared_entity", value: "original" },
+			schema_version: "1.0",
+		})
+		.execute();
+
+	// Create a child version that inherits from main
+	const childVersion = await createVersion({
+		lix,
+		name: "child_version",
+		inherits_from_version_id: mainVersion.id,
+	});
+
+	// The inherited entity should NOT be visible for foreign key validation
+	// because foreign keys only validate entities in the same version (not inherited)
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: mockStateReferenceSchema,
+			snapshot_content: {
+				entity_id: "shared_entity",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				tag: "from_child",
+			},
+			operation: "insert",
+			version_id: childVersion.id,
+		})
+	).toThrow(
+		/Foreign key constraint violation.*no matching record exists.*Note: Foreign key constraints only validate entities that exist in the version context/s
+	);
+});
+
+test("state foreign key with mixed single and composite properties", async () => {
+	const lix = await openLix({});
+
+	// Create a complex schema with multiple foreign keys
+	const complexSchema = {
+		type: "object",
+		"x-lix-version": "1.0",
+		"x-lix-key": "complex_reference",
+		"x-lix-primary-key": ["id"],
+		"x-lix-foreign-keys": [
+			{
+				// Composite foreign key to state
+				properties: ["entity_id", "schema_key", "file_id"],
+				references: {
+					schemaKey: "state",
+					properties: ["entity_id", "schema_key", "file_id"],
+				},
+			},
+			{
+				// Single property foreign key to change
+				properties: ["change_id"],
+				references: {
+					schemaKey: "lix_change",
+					properties: ["id"],
+				},
+			},
+		],
+		properties: {
+			id: { type: "string" },
+			entity_id: { type: "string" },
+			schema_key: { type: "string" },
+			file_id: { type: "string" },
+			change_id: { type: "string" },
+		},
+		required: ["id", "entity_id", "schema_key", "file_id", "change_id"],
+		additionalProperties: false,
+	} as const satisfies LixSchemaDefinition;
+
+	// Store the schema
+	await lix.db
+		.insertInto("stored_schema")
+		.values({ value: complexSchema })
+		.execute();
+
+	const activeVersion = await lix.db
+		.selectFrom("active_version")
+		.select("version_id")
+		.executeTakeFirstOrThrow();
+
+	// Create a state entity
+	await lix.db
+		.insertInto("state_all")
+		.values({
+			entity_id: "test_entity",
+			schema_key: "test_schema",
+			file_id: "test.json",
+			plugin_key: "test_plugin",
+			version_id: activeVersion.version_id,
+			snapshot_content: { id: "test_entity" },
+			schema_version: "1.0",
+		})
+		.execute();
+
+	// Create a key-value to generate a change
+	await lix.db
+		.insertInto("key_value")
+		.values({
+			key: "test_key",
+			value: "test_value",
+		})
+		.execute();
+
+	// Get the created change
+	const changes = await lix.db
+		.selectFrom("change")
+		.select("id")
+		.where("entity_id", "=", "test_key")
+		.execute();
+
+	expect(changes).toHaveLength(1);
+	const changeId = changes[0]!.id;
+
+	// This should PASS - both foreign keys are satisfied
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: complexSchema,
+			snapshot_content: {
+				id: "complex1",
+				entity_id: "test_entity",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				change_id: changeId,
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).not.toThrowError();
+
+	// This should FAIL - state foreign key not satisfied
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: complexSchema,
+			snapshot_content: {
+				id: "complex2",
+				entity_id: "nonexistent",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				change_id: changeId,
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).toThrow(/Foreign key constraint violation.*state/);
+
+	// This should FAIL - change foreign key not satisfied
+	expect(() =>
+		validateStateMutation({
+			lix,
+			schema: complexSchema,
+			snapshot_content: {
+				id: "complex3",
+				entity_id: "test_entity",
+				schema_key: "test_schema",
+				file_id: "test.json",
+				change_id: "nonexistent_change",
+			},
+			operation: "insert",
+			version_id: activeVersion.version_id,
+		})
+	).toThrow(/Foreign key constraint violation.*lix_change/);
+});