@axiom-lattice/pg-stores 3.1.0 → 3.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,8 +25,8 @@
     "@langchain/core": "1.1.30",
     "pg": "^8.16.3",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "4.2.0",
-    "@axiom-lattice/protocols": "4.1.0"
+    "@axiom-lattice/core": "4.2.2",
+    "@axiom-lattice/protocols": "4.1.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/ChannelBindingStore.test.ts

@@ -0,0 +1,122 @@
+import type { Pool } from "pg";
+import { DuplicateChannelBindingSubjectError } from "@axiom-lattice/protocols";
+import { ChannelBindingStore } from "../stores/ChannelBindingStore";
+
+const input = { channel: "room", channelInstallationId: "install-1", tenantId: "tenant-a",
+  senderId: "sender-1", agentId: "agent-1", threadId: "thread-1" };
+
+describe("ChannelBindingStore protected bindings", () => {
+  it("uses tenant-safe exact queries and excludes channels in SQL before pagination", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [] });
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    await store.findById("tenant-a", "binding-1");
+    await store.findBySubject(input);
+    await store.list({ tenantId: "tenant-a", excludeChannels: ["room"], limit: 50 });
+
+    expect(query.mock.calls[0][0]).toMatch(/id = \$1 AND tenant_id = \$2/);
+    expect(query.mock.calls[1][0]).not.toMatch(/enabled/);
+    expect(query.mock.calls[2][0]).toMatch(/channel <> ALL/);
+    expect(query.mock.calls[2][0].indexOf("channel <> ALL")).toBeLessThan(query.mock.calls[2][0].indexOf("LIMIT"));
+  });
+
+  it("parameterizes escaped installation-prefix exclusions before pagination", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [] });
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    await store.list({
+      tenantId: "tenant-a",
+      excludeInstallationIdPrefixes: ["room-internal:", "literal%_\\"],
+      limit: 50,
+    });
+    const [sql, values] = query.mock.calls[0];
+    expect(sql).toMatch(/channel_installation_id NOT LIKE \$\d+ ESCAPE '\\'/);
+    expect(sql.indexOf("NOT LIKE")).toBeLessThan(sql.indexOf("LIMIT"));
+    expect(values).toEqual(["tenant-a", "room-internal:%", "literal\\%\\_\\\\%", 50, 0]);
+  });
+
+  it.each(["room", "lark"])(
+    "persists thread id and maps one of two concurrent %s SQLSTATE 23505 creates",
+    async (channel) => {
+    const duplicate = Object.assign(new Error("duplicate"), {
+      code: "23505",
+      constraint: "lattice_channel_bindings_channel_channel_installation_id_te_key",
+    });
+    const row = {
+      id: "binding-1", channel: "room", channel_installation_id: "install-1",
+      tenant_id: "tenant-a", sender_id: "sender-1", agent_id: "agent-1",
+      thread_id: "thread-1", workspace_id: null, project_id: null, thread_mode: "fixed",
+      sender_display_name: null, sender_metadata: null, enabled: true,
+      created_at: new Date(), updated_at: new Date(),
+    };
+    const query = jest.fn()
+      .mockResolvedValueOnce({ rows: [row] })
+      .mockRejectedValueOnce(duplicate);
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    const subject = { ...input, channel };
+    const results = await Promise.allSettled([store.create(subject), store.create(subject)]);
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    expect((results.find((result) => result.status === "rejected") as PromiseRejectedResult).reason)
+      .toBeInstanceOf(DuplicateChannelBindingSubjectError);
+    expect(query.mock.calls[0][0]).toMatch(/thread_id/);
+    expect(query.mock.calls[0][1]).toContain("thread-1");
+    },
+  );
+
+  it("rethrows unrelated PostgreSQL unique violations", async () => {
+    const unrelated = Object.assign(new Error("duplicate id"), {
+      code: "23505", constraint: "lattice_channel_bindings_pkey",
+    });
+    const store = new ChannelBindingStore({
+      pool: { query: jest.fn().mockRejectedValue(unrelated) } as unknown as Pool,
+    });
+    await expect(store.create(input)).rejects.toBe(unrelated);
+  });
+
+  it("passes the requested initial enabled state to PostgreSQL", async () => {
+    const query = jest.fn().mockResolvedValue({ rows: [{ enabled: false }] });
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    await store.create({ ...input, enabled: false });
+    expect(query.mock.calls[0][0]).toMatch(/enabled/);
+    expect(query.mock.calls[0][1]).toContain(false);
+  });
+
+  it("uses tenant predicates for update and delete", async () => {
+    const row = {
+      id: "binding-1", channel: "lark", channel_installation_id: "install-1",
+      tenant_id: "tenant-a", sender_id: "sender-1", agent_id: "agent-2", thread_id: null,
+      workspace_id: null, project_id: null, thread_mode: "fixed", sender_display_name: null,
+      sender_metadata: null, enabled: true, created_at: new Date(), updated_at: new Date(),
+    };
+    const query = jest.fn().mockResolvedValueOnce({ rows: [row] }).mockResolvedValueOnce({ rows: [] });
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    await store.update("tenant-a", "binding-1", { agentId: "agent-2" });
+    await store.delete("tenant-a", "binding-1");
+    expect(query.mock.calls[0][0]).toMatch(/WHERE id = \$\d+ AND tenant_id = \$\d+/);
+    expect(query.mock.calls[1]).toEqual([
+      expect.stringMatching(/WHERE id = \$1 AND tenant_id = \$2/), ["binding-1", "tenant-a"],
+    ]);
+  });
+
+  it("rejects room imports before issuing SQL", async () => {
+    const query = jest.fn();
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    await expect(store.import("tenant-a", [{ ...input, channel: "lark" }, input])).rejects.toThrow(/room/i);
+    expect(query).not.toHaveBeenCalled();
+  });
+
+  it("rejects internal installation imports before issuing SQL", async () => {
+    const query = jest.fn();
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    await expect(store.import("tenant-a", [{
+      ...input, channel: "lark", channelInstallationId: "room-internal:project-1",
+    }])).rejects.toThrow(/internal/i);
+    expect(query).not.toHaveBeenCalled();
+  });
+
+  it("rejects cross-tenant imports before issuing SQL", async () => {
+    const query = jest.fn();
+    const store = new ChannelBindingStore({ pool: { query } as unknown as Pool });
+    await expect(store.import("tenant-a", [{ ...input, channel: "lark", tenantId: "tenant-b" }]))
+      .rejects.toThrow(/tenant mismatch/i);
+    expect(query).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/PostgreSQLCapabilityBundleStore.migrations.test.ts

@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it } from "@jest/globals";
+
+const recordedMigrationNames: string[] = [];
+const clientSql: string[] = [];
+let migrationError: Error | null = null;
+
+jest.mock("pg", () => {
+  const client = {
+    query: async (sql: string, params?: unknown[]) => {
+      clientSql.push(sql);
+      if (migrationError && sql.includes("CREATE TABLE IF NOT EXISTS lattice_capability_bundles")) {
+        throw migrationError;
+      }
+      if (sql.includes("information_schema.tables")) return { rows: [{ exists: true }] };
+      if (sql.includes("pg_index")) return { rows: [] };
+      if (sql.includes("INSERT INTO lattice_schema_migrations")) {
+        recordedMigrationNames.push(params?.[0] as string);
+      }
+      return { rows: [] };
+    },
+    release: () => undefined,
+  };
+  const pool = {
+    connect: async () => client,
+    query: async () => ({ rows: [] }),
+    end: async () => undefined,
+  };
+  return { Pool: function Pool() { return pool; } };
+});
+
+import { PostgreSQLCapabilityBundleStore } from "../stores/PostgreSQLCapabilityBundleStore";
+
+describe("PostgreSQLCapabilityBundleStore standalone migrations", () => {
+  beforeEach(() => {
+    recordedMigrationNames.length = 0;
+    clientSql.length = 0;
+    migrationError = null;
+  });
+
+  it("remains uninitialized with autoMigrate false until initialize applies its migration", async () => {
+    const store = new PostgreSQLCapabilityBundleStore({
+      poolConfig: "postgres://unused",
+      autoMigrate: false,
+    });
+
+    expect(clientSql).toEqual([]);
+    await store.initialize();
+
+    expect(recordedMigrationNames).toEqual(["create_capability_bundles_table"]);
+    expect(clientSql.some((sql) =>
+      sql.includes("CREATE TABLE IF NOT EXISTS lattice_capability_bundles")
+    )).toBe(true);
+    await store.dispose();
+  });
+
+  it("shares an eager migration rejection with initialize and operations without retrying", async () => {
+    migrationError = new Error("migration failed");
+    const store = new PostgreSQLCapabilityBundleStore({ poolConfig: "postgres://unused" });
+
+    await expect(store.initialize()).rejects.toThrow("migration failed");
+    await expect(store.listByTenant("tenant-1")).rejects.toThrow("migration failed");
+    expect(clientSql.filter((sql) =>
+      sql.includes("CREATE TABLE IF NOT EXISTS lattice_capability_bundles")
+    )).toHaveLength(1);
+    await store.dispose();
+  });
+});

package/src/__tests__/PostgreSQLCapabilityBundleStore.test.ts

@@ -0,0 +1,383 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type { Pool } from "pg";
+
+import { createCapabilityBundlesTable } from "../migrations/capability_bundle_migration";
+import { PostgreSQLCapabilityBundleStore } from "../stores/PostgreSQLCapabilityBundleStore";
+import { PostgreSQLProjectStore } from "../stores/PostgreSQLProjectStore";
+
+const mockQuery = jest.fn();
+const now = new Date("2026-08-27T12:00:00.000Z");
+const capabilities = [{
+  id: "filesystem",
+  type: "filesystem",
+  name: "Filesystem",
+  enabled: true,
+  config: { roots: ["/workspace"], policy: { write: false } },
+}];
+const row = {
+  id: "11111111-1111-4111-8111-111111111111",
+  tenant_id: "tenant-1",
+  bundle_key: "research",
+  name: "Research",
+  description: "Research tools",
+  capabilities,
+  created_at: now,
+  updated_at: now,
+};
+
+describe("PostgreSQLCapabilityBundleStore", () => {
+  const pool = { query: mockQuery } as unknown as Pool;
+
+  beforeEach(() => mockQuery.mockReset());
+
+  it("creates with a generated UUID and round-trips nested JSONB", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+    const result = await store.create("tenant-1", {
+      key: "research", name: "Research", description: "Research tools", capabilities,
+    });
+
+    const [sql, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("INSERT INTO lattice_capability_bundles");
+    expect(params[0]).toEqual(expect.stringMatching(/^[0-9a-f-]{36}$/));
+    expect(params.at(-1)).toBe(JSON.stringify(capabilities));
+    expect(result).toEqual({
+      id: row.id, tenantId: "tenant-1", key: "research", name: "Research",
+      description: "Research tools", capabilities, createdAt: now.toISOString(), updatedAt: now.toISOString(),
+    });
+  });
+
+  it("performs tenant-scoped list, single, bulk, and update queries", async () => {
+    mockQuery
+      .mockResolvedValueOnce({ rows: [row] })
+      .mockResolvedValueOnce({ rows: [row] })
+      .mockResolvedValueOnce({ rows: [row] })
+      .mockResolvedValueOnce({ rows: [{ ...row, name: "Updated", updated_at: new Date(now.getTime() + 1) }] });
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+
+    await expect(store.listByTenant("tenant-1")).resolves.toHaveLength(1);
+    await expect(store.getById("tenant-1", row.id)).resolves.toMatchObject({ id: row.id });
+    await expect(store.getManyByIds("tenant-1", [row.id])).resolves.toHaveLength(1);
+    const updated = await store.update("tenant-1", row.id, { name: "Updated" });
+    expect(updated).toMatchObject({ id: row.id, createdAt: now.toISOString(), name: "Updated" });
+    expect("delete" in store).toBe(false);
+
+    for (const call of mockQuery.mock.calls) expect(call[1]).toContain("tenant-1");
+  });
+
+  it("normalizes PostgreSQL unique violations to the stable conflict message", async () => {
+    mockQuery.mockRejectedValueOnce(Object.assign(new Error("duplicate"), { code: "23505" }));
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+    await expect(store.create("tenant-1", {
+      key: "research", name: "Research", capabilities,
+    })).rejects.toThrow("Capability bundle key already exists for tenant");
+  });
+
+  it("normalizes PostgreSQL unique violations raised while updating a key", async () => {
+    mockQuery.mockRejectedValueOnce(Object.assign(new Error("duplicate"), { code: "23505" }));
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+
+    await expect(store.update("tenant-1", row.id, { key: "existing-key" })).rejects.toThrow(
+      "Capability bundle key already exists for tenant",
+    );
+  });
+
+  it("uses exact updated_at CAS and distinguishes a stale update", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [] });
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+    await expect(store.update("tenant-1", row.id, { name: "Stale", expectedUpdatedAt: "2026-08-27T12:00:00.000Z" }))
+      .resolves.toEqual({ status: "conflict" });
+    const [sql, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("updated_at::text =");
+    expect(sql).toContain("GREATEST(updated_at + interval '1 microsecond', clock_timestamp())");
+    expect(params).toContain("2026-08-27T12:00:00.000Z");
+  });
+
+  it("checks CAS tokens for no-op updates", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [] }).mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+
+    await expect(store.update("tenant-1", row.id, { expectedUpdatedAt: "stale" }))
+      .resolves.toEqual({ status: "conflict" });
+    await expect(store.update("tenant-1", row.id, { expectedUpdatedAt: now.toISOString() }))
+      .resolves.toMatchObject({ id: row.id, updatedAt: now.toISOString() });
+    expect(mockQuery.mock.calls[0][0]).toContain("updated_at::text");
+  });
+
+  it.each([
+    [[], [], "not_found"],
+    [[{ exists: 1 }], [], "in_use"],
+    [[], [{ id: row.id }], "deleted"],
+  ])("atomically maps conditional delete status to %s", async (referenceRows, deleteRows, expected) => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("SELECT id FROM lattice_projects")) return Promise.resolve({ rows: [] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      if (sql.includes("SELECT 1 FROM lattice_projects")) return Promise.resolve({ rows: referenceRows });
+      if (sql.includes("DELETE FROM lattice_capability_bundles")) return Promise.resolve({ rows: deleteRows });
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const release = jest.fn();
+    const transactionPool = {
+      connect: jest.fn().mockResolvedValue({ query: clientQuery, release }),
+    } as unknown as Pool;
+    const store = new PostgreSQLCapabilityBundleStore({ pool: transactionPool });
+
+    await expect(store.deleteIfUnreferenced("tenant-1", row.id)).resolves.toBe(expected);
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).includes("pg_advisory_xact_lock"))).toBe(true);
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).includes("lattice_projects"))).toBe(true);
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).includes("DELETE FROM lattice_capability_bundles"))).toBe(expected !== "in_use");
+    expect(release).toHaveBeenCalled();
+  });
+
+  it("defines idempotent migration version 170 with the tenant index", async () => {
+    const query = jest.fn().mockResolvedValue({});
+    await createCapabilityBundlesTable.up({ query } as never);
+    const sql = query.mock.calls.map((call) => String(call[0])).join("\n");
+    expect(createCapabilityBundlesTable.version).toBe(170);
+    expect(createCapabilityBundlesTable.name).toBe("create_capability_bundles_table");
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_capability_bundles");
+    expect(sql).toContain("UNIQUE (tenant_id, bundle_key)");
+    expect(sql).toContain("CREATE INDEX IF NOT EXISTS");
+  });
+});
+
+describe("PostgreSQLProjectStore capability bundle references", () => {
+  beforeEach(() => mockQuery.mockReset());
+  it("rejects capability bundle references through generic project writes", async () => {
+    const store = new PostgreSQLProjectStore({ pool: { query: mockQuery } as unknown as Pool });
+
+    await expect(store.createProject("tenant-1", "workspace", "project", {
+      name: "Project", config: { capabilityBundleIds: [] },
+    })).rejects.toMatchObject({ code: "INVALID_BUNDLE_CONFIG" });
+    await expect(store.updateProject("tenant-1", "project", {
+      config: { capabilityBundleIds: [] },
+    })).rejects.toMatchObject({ code: "INVALID_BUNDLE_CONFIG" });
+    expect(mockQuery).not.toHaveBeenCalled();
+  });
+
+  it("preserves current-row capability bundle IDs during generic config replacement", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("FOR UPDATE")) return Promise.resolve({ rows: [{ config: { capabilityBundleIds: ["b1"] } }] });
+      if (sql.includes("UPDATE lattice_projects")) return Promise.resolve({ rows: [{ ...row, config: { replacement: true, capabilityBundleIds: ["b1"] } }] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const store = new PostgreSQLProjectStore({ pool: {
+      connect: jest.fn().mockResolvedValue({ query: clientQuery, release: jest.fn() }),
+    } as unknown as Pool });
+
+    await store.updateProject("tenant-1", row.id, { config: { replacement: true } });
+
+    const [sql, params] = clientQuery.mock.calls[5] as [string, unknown[]];
+    expect(sql).toContain("config ? 'capabilityBundleIds'");
+    expect(sql).toContain("config->'capabilityBundleIds'");
+    expect(sql).toContain("jsonb_build_object('capabilityBundleIds'");
+    expect(params).toContainEqual({ replacement: true });
+    expect(params).not.toContainEqual(expect.objectContaining({ capabilityBundleIds: expect.anything() }));
+  });
+
+  it("locks the project row before sorted preserved bundles during a generic update", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("FOR UPDATE")) return Promise.resolve({ rows: [{ config: { capabilityBundleIds: ["bundle-z", "bundle-a"] } }] });
+      if (sql.includes("UPDATE lattice_projects")) return Promise.resolve({ rows: [{ ...row, config: { replacement: true, capabilityBundleIds: ["bundle-z", "bundle-a"] } }] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const release = jest.fn();
+    const pool = {
+      query: mockQuery,
+      connect: jest.fn().mockResolvedValue({ query: clientQuery, release }),
+    } as unknown as Pool;
+    const store = new PostgreSQLProjectStore({ pool });
+
+    await expect(store.updateProject("tenant-1", row.id, { config: { replacement: true } }))
+      .resolves.toMatchObject({ config: { capabilityBundleIds: ["bundle-z", "bundle-a"] } });
+
+    expect(clientQuery.mock.calls.map((call) => String(call[0]))).toEqual([
+      "BEGIN",
+      expect.stringContaining("pg_advisory_xact_lock"),
+      expect.stringContaining("pg_advisory_xact_lock"),
+      expect.stringContaining("FOR UPDATE"),
+      expect.stringContaining("pg_advisory_xact_lock"),
+      expect.stringContaining("UPDATE lattice_projects"),
+      "COMMIT",
+    ]);
+    expect(clientQuery.mock.calls[4][1]).toEqual(["tenant-1", ["bundle-a", "bundle-z"]]);
+  });
+
+  it("locks generic create and preserves current-row capability bundle IDs on conflict", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("FOR UPDATE")) return Promise.resolve({ rows: [{ config: { capabilityBundleIds: ["b1"] } }] });
+      if (sql.includes("INSERT INTO lattice_projects")) return Promise.resolve({ rows: [{
+        ...row, workspace_id: "workspace-2", config: { replacement: true, capabilityBundleIds: ["b1"] },
+      }] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const store = new PostgreSQLProjectStore({ pool: {
+      connect: jest.fn().mockResolvedValue({ query: clientQuery, release: jest.fn() }),
+    } as unknown as Pool });
+
+    const result = await store.createProject("tenant-1", "workspace-2", row.id, {
+      name: "Upserted",
+      config: { replacement: true },
+    });
+
+    const [sql, params] = clientQuery.mock.calls[5] as [string, unknown[]];
+    expect(sql).toContain("lattice_projects.config ? 'capabilityBundleIds'");
+    expect(sql).toContain("lattice_projects.config->'capabilityBundleIds'");
+    expect(sql).toContain("RETURNING");
+    expect(params).not.toContainEqual(expect.objectContaining({ capabilityBundleIds: expect.anything() }));
+    expect(result.config).toEqual({ replacement: true, capabilityBundleIds: ["b1"] });
+  });
+
+  it("atomically merges capability bundle IDs and returns the updated row", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes(":project-mutations")) return Promise.resolve({});
+      if (sql.includes("FOR UPDATE") && sql.includes("lattice_projects")) return Promise.resolve({ rows: [{ id: "project-1" }] });
+      if (sql.includes("UPDATE lattice_projects")) return Promise.resolve({ rows: [{ ...row, config: { keep: true, capabilityBundleIds: ["b1"] } }] });
+      if (sql.includes("updated_at") && sql.includes("lattice_capability_bundles")) return Promise.resolve({ rows: [] });
+      if (sql.includes("SELECT id FROM lattice_projects")) return Promise.resolve({ rows: [{ id: "project-1" }] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const release = jest.fn();
+    const store = new PostgreSQLProjectStore({
+      pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool,
+    });
+    await expect(store.updateCapabilityBundleIds("tenant-1", "project-1", ["b1"])).resolves.toMatchObject({ status: "updated", project: { id: row.id } });
+    const [sql, params] = clientQuery.mock.calls[5] as [string, unknown[]];
+    expect(sql).toContain("COALESCE(config, '{}'::jsonb) || jsonb_build_object('capabilityBundleIds', $3::jsonb)");
+    expect(sql).toContain("lattice_capability_bundles");
+    expect(sql).toContain("RETURNING");
+    expect(params).toEqual(["project-1", "tenant-1", '["b1"]', ["b1"]]);
+    expect(String(clientQuery.mock.calls[2][0])).toContain("pg_advisory_xact_lock");
+    expect(clientQuery.mock.calls[2][1]).toEqual(["project-1", "tenant-1"]);
+    expect(String(clientQuery.mock.calls[4][0])).toContain("pg_advisory_xact_lock");
+    expect(release).toHaveBeenCalled();
+  });
+
+  it("locks referenced bundles while deleting a project", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes(":project-mutations")) return Promise.resolve({});
+      if (sql.includes("FOR UPDATE")) return Promise.resolve({ rows: [{ config: { capabilityBundleIds: [row.id] } }] });
+      if (sql.includes("unnest")) return Promise.resolve({});
+      if (sql.includes("DELETE FROM lattice_projects")) return Promise.resolve({ rowCount: 1 });
+      if (sql.includes(":project:")) return Promise.resolve({});
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const release = jest.fn();
+    const store = new PostgreSQLProjectStore({
+      pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool,
+    });
+
+    await expect(store.deleteProject("tenant-1", "project-1")).resolves.toBe(true);
+
+    expect(String(clientQuery.mock.calls[2][0])).toContain("pg_advisory_xact_lock");
+    expect(clientQuery.mock.calls[2][1]).toEqual(["project-1", "tenant-1"]);
+    expect(String(clientQuery.mock.calls[4][0])).toContain("unnest");
+    expect(clientQuery.mock.calls[4][1]).toEqual(["tenant-1", [row.id]]);
+    expect(String(clientQuery.mock.calls[5][0])).toContain("DELETE FROM lattice_projects");
+    expect(clientQuery).toHaveBeenCalledWith("COMMIT");
+    expect(release).toHaveBeenCalled();
+  });
+
+  it("locks matching project rows before the bundle during conditional deletion", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("ORDER BY id")) return Promise.resolve({ rows: [{ id: "project-1" }] });
+      if (sql.includes("FOR UPDATE")) return Promise.resolve({ rows: [{ id: "project-1" }] });
+      if (sql.includes("SELECT 1 FROM lattice_projects")) return Promise.resolve({ rows: [] });
+      if (sql.includes("DELETE FROM lattice_capability_bundles")) return Promise.resolve({ rows: [{ id: row.id }] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const release = jest.fn();
+    const pool = {
+      connect: jest.fn().mockResolvedValue({ query: clientQuery, release }),
+    } as unknown as Pool;
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+
+    await expect(store.deleteIfUnreferenced("tenant-1", row.id)).resolves.toBe("deleted");
+
+    expect(clientQuery.mock.calls.map((call) => String(call[0]))).toEqual([
+      "BEGIN",
+      expect.stringContaining("project-mutations"),
+      expect.stringContaining("lattice_projects"),
+      expect.stringContaining("pg_advisory_xact_lock"),
+      expect.stringContaining("lattice_projects"),
+      expect.stringContaining("pg_advisory_xact_lock"),
+      expect.stringContaining("SELECT 1 FROM lattice_projects"),
+      expect.stringContaining("DELETE FROM lattice_capability_bundles"),
+      "COMMIT",
+    ]);
+    expect(String(clientQuery.mock.calls[4][0])).toContain("FOR UPDATE");
+  });
+
+  it("rejects a revision that differs below JavaScript millisecond precision", async () => {
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [{ id: row.id, updated_at: "2026-08-27 12:00:00.123457+00" }] })
+      .mockResolvedValueOnce({});
+    const release = jest.fn();
+    const store = new PostgreSQLProjectStore({
+      pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool,
+    });
+
+    await expect(store.updateCapabilityBundleIds(
+      "tenant-1",
+      "project-1",
+      [row.id],
+      { [row.id]: "2026-08-27 12:00:00.123456+00" },
+    )).resolves.toEqual({ status: "bundle_conflict" });
+    expect(clientQuery).toHaveBeenCalledWith("ROLLBACK");
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).includes("UPDATE lattice_projects"))).toBe(false);
+  });
+
+  it.each([
+    [[], "project_not_found"],
+    [[{ id: "project-1" }], "bundle_not_found"],
+  ])("distinguishes an atomic update miss as %s", async (projectRows, status) => {
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: projectRows })
+      .mockResolvedValueOnce({});
+    const release = jest.fn();
+    const store = new PostgreSQLProjectStore({
+      pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool,
+    });
+
+    await expect(store.updateCapabilityBundleIds("tenant-1", "project-1", [row.id]))
+      .resolves.toEqual({ status });
+    expect(String(clientQuery.mock.calls[5][0])).toContain("lattice_projects");
+  });
+
+  it("uses a tenant-scoped JSONB array membership query", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ exists: 1 }] });
+    const store = new PostgreSQLProjectStore({ pool: { query: mockQuery } as unknown as Pool });
+    await expect(store.isCapabilityBundleReferenced("tenant-1", "bundle-1")).resolves.toBe(true);
+    const [sql, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("tenant_id = $1");
+    expect(sql).toContain("jsonb_typeof(config->'capabilityBundleIds') = 'array'");
+    expect(sql).toContain("COALESCE(config->'capabilityBundleIds', '[]'::jsonb) ? $2");
+    expect(params).toEqual(["tenant-1", "bundle-1"]);
+
+    mockQuery.mockResolvedValueOnce({ rows: [] });
+    await expect(store.isCapabilityBundleReferenced("tenant-2", "bundle-1")).resolves.toBe(false);
+  });
+});

package/src/__tests__/PostgreSQLChannelInstallationStore.test.ts

@@ -19,6 +19,22 @@ describe("PostgreSQLChannelInstallationStore", () => {
     jest.clearAllMocks();
   });
 
+  it("persists room installations with a plain record config", async () => {
+    const store = new PostgreSQLChannelInstallationStore({
+      pool: { query: mockQuery } as unknown as Pool,
+    });
+    mockQuery.mockResolvedValueOnce({ rows: [] });
+
+    await expect(store.createInstallation("tenant-a", "room-install", {
+      channel: "room",
+      config: {},
+    })).resolves.toMatchObject({
+      channel: "room",
+      config: {},
+    });
+    expect(mockQuery).toHaveBeenCalledWith(expect.stringContaining("INSERT INTO"), expect.arrayContaining(["room"]));
+  });
+
   it("retrieves and decrypts an installation by id", async () => {
     const store = new PostgreSQLChannelInstallationStore({
       pool: { query: mockQuery } as unknown as Pool,