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

package/dist/state/validate-state-mutation.test.js

@@ -1,7 +1,7 @@
 import { test, expect } from "vitest";
 import { openLix } from "../lix/open-lix.js";
 import { validateStateMutation } from "./validate-state-mutation.js";
-import { sql } from "kysely";
+import { Kysely, sql } from "kysely";
 import { createVersion } from "../version/create-version.js";
 test("throws if the schema is not a valid lix schema", async () => {
     const lix = await openLix({});
@@ -471,12 +471,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" },
@@ -542,12 +545,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" },
@@ -609,16 +615,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" },
@@ -717,12 +729,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"] },
@@ -764,6 +779,110 @@ test("allows null foreign key values", async () => {
         version_id: activeVersion.version_id,
     })).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,
+    };
+    // 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,
+    };
+    // 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({});
     // Insert a real change record into the change table
@@ -792,12 +911,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" },
@@ -1037,12 +1159,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" },
@@ -1210,19 +1335,38 @@ 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();
     // const activeVersion = await lix.db
@@ -1243,7 +1387,7 @@ test("should handle deletion validation for change sets referenced by versions",
         operation: "delete",
         entity_id: "cs_referenced",
         version_id: "global",
-    })).toThrowError(/Foreign key constraint violation.*Cannot delete entity.*referenced by.*lix_version/i);
+    })).toThrowError(/Foreign key constraint violation.*Cannot delete entity.*referenced by.*lix_commit/i);
 });
 test("should parse JSON object properties before validation", async () => {
     const lix = await openLix({});
@@ -1349,12 +1493,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" },
@@ -1439,12 +1586,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" },
@@ -1524,12 +1674,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" },
@@ -1614,12 +1767,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" },
@@ -1808,12 +1964,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" },
@@ -1885,12 +2044,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" },
@@ -1965,12 +2127,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" },
@@ -2021,4 +2186,674 @@ 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,
+        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,
+        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,
+        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,
+    };
+    // 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
+            .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 },
+            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,
+    };
+    // 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,
+    };
+    // 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,
+    };
+    // 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,
+    };
+    // 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,
+    };
+    // 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/);
+});
 //# sourceMappingURL=validate-state-mutation.test.js.map