@axiom-lattice/pg-stores 3.1.1 → 3.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "3.1.1",
+  "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.1",
-    "@axiom-lattice/protocols": "4.1.1"
+    "@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__/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,

package/src/__tests__/PostgreSQLProjectBotMembershipStore.test.ts

@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type { Pool } from "pg";
+
+import {
+  PostgreSQLProjectBotMembershipStore,
+  ProjectBotMembershipIdConflictError,
+} from "../stores/PostgreSQLProjectBotMembershipStore";
+
+const query = jest.fn();
+const pool = { query } as unknown as Pool;
+const now = new Date("2026-08-30T12:00:00.000Z");
+const row = {
+  id: "bot-1", tenant_id: "tenant-1", workspace_id: "workspace-1", project_id: "project-1",
+  room_id: "room-1", assistant_id: "assistant-1", role: "coordinator", title: "Lead",
+  responsibility: "Coordinate", mention_name: "lead", status: "active", room_thread_id: "thread-1",
+  joined_at: now, updated_at: now,
+};
+
+function transactionPool(clientQuery: jest.Mock): Pool {
+  return { connect: jest.fn().mockResolvedValue({ query: clientQuery, release: jest.fn() }) } as unknown as Pool;
+}
+
+describe("PostgreSQLProjectBotMembershipStore", () => {
+  beforeEach(() => query.mockReset());
+
+  it("lists by joined time and finds with exact tenant scopes", async () => {
+    query.mockResolvedValueOnce({ rows: [row] }).mockResolvedValueOnce({ rows: [row] }).mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLProjectBotMembershipStore({ pool });
+    await expect(store.list("tenant-1", "project-1")).resolves.toHaveLength(1);
+    await expect(store.findById("tenant-1", "bot-1")).resolves.toMatchObject({ id: "bot-1" });
+    await expect(store.findByAssistant("tenant-1", "project-1", "assistant-1")).resolves.toMatchObject({ assistantId: "assistant-1" });
+    expect(query.mock.calls[0][0]).toContain("ORDER BY joined_at ASC, id ASC");
+    expect(query.mock.calls[1][1]).toEqual(["tenant-1", "bot-1"]);
+    expect(query.mock.calls[2][1]).toEqual(["tenant-1", "project-1", "assistant-1"]);
+  });
+
+  it("reactivates the durable assistant membership without replacing immutable fields", async () => {
+    const updated = { ...row, role: "specialist", title: "Builder", responsibility: null, mention_name: "builder", updated_at: new Date(now.getTime() + 1) };
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({}).mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [row] })
+      .mockResolvedValueOnce({ rows: [updated] }).mockResolvedValueOnce({});
+    const store = new PostgreSQLProjectBotMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.save({
+      id: "candidate", tenantId: "tenant-1", workspaceId: "other", projectId: "project-1", roomId: "other-room",
+      assistantId: "assistant-1", role: "specialist", title: "Builder", mentionName: "builder", status: "removed", roomThreadId: "other-thread",
+    })).resolves.toEqual({ kind: "updated", membership: expect.objectContaining({ id: "bot-1", roomThreadId: "thread-1", status: "active" }) });
+    expect(clientQuery.mock.calls.map((call) => String(call[0]))).toEqual([
+      "BEGIN", expect.stringContaining("pg_advisory_xact_lock"), expect.stringContaining("FOR UPDATE"),
+      expect.stringContaining("UPDATE lattice_project_bot_memberships"), "COMMIT",
+    ]);
+    expect(clientQuery.mock.calls[3][1]).toEqual(["tenant-1", "bot-1", "specialist", "Builder", null, "builder"]);
+  });
+
+  it("inserts a new active membership and maps candidate ID collisions", async () => {
+    const inserted = { ...row, role: "specialist" };
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({}).mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] }).mockResolvedValueOnce({ rows: [inserted] }).mockResolvedValueOnce({});
+    const store = new PostgreSQLProjectBotMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.save({
+      id: "bot-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      assistantId: "assistant-1", role: "specialist", title: "Lead", responsibility: "Coordinate", mentionName: "lead", status: "paused", roomThreadId: "thread-1",
+    })).resolves.toEqual({ kind: "created", membership: expect.objectContaining({ status: "active" }) });
+    expect(clientQuery.mock.calls[4][0]).toContain("date_trunc('milliseconds', clock_timestamp())");
+    expect(clientQuery.mock.calls[4][1]).toEqual(["bot-1", "tenant-1", "workspace-1", "project-1", "room-1", "assistant-1", "specialist", "Lead", "Coordinate", "lead", "thread-1"]);
+
+    const collisionQuery = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [] }).mockResolvedValueOnce({ rows: [{ id: "bot-1" }] });
+    const collisionStore = new PostgreSQLProjectBotMembershipStore({ pool: transactionPool(collisionQuery) });
+    await expect(collisionStore.save({
+      id: "bot-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      assistantId: "assistant-2", role: "specialist", title: "Bot", mentionName: "bot", status: "active", roomThreadId: "thread-2",
+    })).rejects.toBeInstanceOf(ProjectBotMembershipIdConflictError);
+  });
+
+  it.each([
+    ["uq_lattice_project_bot_memberships_coordinator", "coordinator_conflict"],
+    ["uq_lattice_project_bot_memberships_mention", "mention_conflict"],
+  ] as const)("maps known save constraint %s without leaking SQL errors", async (constraint, kind) => {
+    const clientQuery = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] }).mockRejectedValueOnce(Object.assign(new Error("raw sql"), { code: "23505", constraint }));
+    const store = new PostgreSQLProjectBotMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.save({
+      id: "bot-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      assistantId: "assistant-1", role: "coordinator", title: "Lead", mentionName: "lead", status: "active", roomThreadId: "thread-1",
+    })).resolves.toEqual({ kind });
+  });
+
+  it("updates mutable fields with exact monotonic millisecond CAS", async () => {
+    const updated = { ...row, status: "removed", updated_at: new Date(now.getTime() + 1) };
+    const clientQuery = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [{ project_id: "project-1" }] })
+      .mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [row] }).mockResolvedValueOnce({ rows: [updated] }).mockResolvedValueOnce({});
+    const store = new PostgreSQLProjectBotMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.update({ tenantId: "tenant-1", id: "bot-1", patch: { status: "removed" }, expectedUpdatedAt: now }))
+      .resolves.toEqual({ kind: "updated", membership: expect.objectContaining({ status: "removed" }) });
+    const updateCall = clientQuery.mock.calls[4] as [string, unknown[]];
+    expect(updateCall[0]).toContain("GREATEST(date_trunc('milliseconds', updated_at) + interval '1 millisecond'");
+    expect(updateCall[0]).toContain("date_trunc('milliseconds', updated_at) = $3");
+    expect(updateCall[1]).toEqual(["tenant-1", "bot-1", now, "coordinator", "Lead", "Coordinate", "lead", "removed"]);
+  });
+
+  it("returns not_found and CAS conflict without writing", async () => {
+    const absent = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [] }).mockResolvedValueOnce({});
+    await expect(new PostgreSQLProjectBotMembershipStore({ pool: transactionPool(absent) }).update({ tenantId: "tenant-1", id: "missing", patch: {}, expectedUpdatedAt: now }))
+      .resolves.toEqual({ kind: "not_found" });
+    const stale = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [{ project_id: "project-1" }] })
+      .mockResolvedValueOnce({}).mockResolvedValueOnce({ rows: [row] }).mockResolvedValueOnce({});
+    await expect(new PostgreSQLProjectBotMembershipStore({ pool: transactionPool(stale) }).update({ tenantId: "tenant-1", id: "bot-1", patch: {}, expectedUpdatedAt: new Date(0) }))
+      .resolves.toEqual({ kind: "conflict" });
+    expect(stale.mock.calls.some((call) => String(call[0]).startsWith("UPDATE"))).toBe(false);
+  });
+
+  it("strictly rejects malformed persisted rows", async () => {
+    query.mockResolvedValueOnce({ rows: [{ ...row, status: "invalid" }] });
+    await expect(new PostgreSQLProjectBotMembershipStore({ pool }).list("tenant-1", "project-1"))
+      .rejects.toThrow("Invalid project bot membership row");
+  });
+});

package/src/__tests__/PostgreSQLProjectMembershipStore.test.ts

@@ -0,0 +1,235 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type { Pool } from "pg";
+
+import {
+  DuplicateProjectMembershipError,
+  ProjectMembershipIdConflictError,
+  PostgreSQLProjectMembershipStore,
+} from "../stores/PostgreSQLProjectMembershipStore";
+
+const query = jest.fn();
+const pool = { query } as unknown as Pool;
+const now = new Date("2026-08-30T12:00:00.000Z");
+const membership = {
+  id: "member-1", tenant_id: "tenant-1", project_id: "project-1", user_id: "user-1",
+  role: "owner", status: "active", joined_at: now, updated_at: now,
+};
+
+function transactionPool(clientQuery: jest.Mock): Pool {
+  return { connect: jest.fn().mockResolvedValue({ query: clientQuery, release: jest.fn() }) } as unknown as Pool;
+}
+
+describe("PostgreSQLProjectMembershipStore", () => {
+  beforeEach(() => query.mockReset());
+
+  it("lists deterministically and finds by exact tenant/project/user", async () => {
+    query.mockResolvedValueOnce({ rows: [membership] }).mockResolvedValueOnce({ rows: [membership] });
+    const store = new PostgreSQLProjectMembershipStore({ pool });
+    await expect(store.list("tenant-1", "project-1")).resolves.toHaveLength(1);
+    await expect(store.findByUser("tenant-1", "project-1", "user-1")).resolves.toMatchObject({ id: "member-1" });
+    expect(query.mock.calls[0][0]).toContain("ORDER BY joined_at ASC, id ASC");
+    expect(query.mock.calls[1][0]).toContain("tenant_id = $1 AND project_id = $2 AND user_id = $3");
+  });
+
+  it("maps membership and tenant-wide ID unique violations accurately", async () => {
+    const firstClientQuery = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({})
+      .mockRejectedValueOnce(Object.assign(new Error("duplicate"), { code: "23505", constraint: "lattice_project_memberships_tenant_id_project_id_user_id_key" }));
+    const store = new PostgreSQLProjectMembershipStore({ pool: transactionPool(firstClientQuery) });
+    await expect(store.create({ ...membership, joinedAt: undefined as never, updatedAt: undefined as never })).rejects.toBeInstanceOf(DuplicateProjectMembershipError);
+
+    const secondClientQuery = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({})
+      .mockRejectedValueOnce(Object.assign(new Error("duplicate"), { code: "23505", constraint: "lattice_project_memberships_pkey" }));
+    const secondStore = new PostgreSQLProjectMembershipStore({ pool: transactionPool(secondClientQuery) });
+    await expect(secondStore.create({ ...membership, id: "same", joinedAt: undefined as never, updatedAt: undefined as never })).rejects.toBeInstanceOf(ProjectMembershipIdConflictError);
+  });
+
+  it("serializes ordinary creates with the project membership write lock", async () => {
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({ rows: [membership] })
+      .mockResolvedValueOnce({});
+    const release = jest.fn();
+    const store = new PostgreSQLProjectMembershipStore({
+      pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool,
+    });
+
+    await expect(store.create({ ...membership, joinedAt: undefined as never, updatedAt: undefined as never }))
+      .resolves.toMatchObject({ id: "member-1" });
+    expect(clientQuery.mock.calls.map((call) => String(call[0]))).toEqual([
+      "BEGIN",
+      expect.stringContaining("pg_advisory_xact_lock"),
+      expect.stringContaining("INSERT INTO"),
+      "COMMIT",
+    ]);
+    expect(release).toHaveBeenCalled();
+    expect(clientQuery.mock.calls[2][0]).toContain("date_trunc('milliseconds', clock_timestamp())");
+  });
+
+  it("rolls back and releases an ordinary create transaction on failure", async () => {
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({})
+      .mockRejectedValueOnce(new Error("broken"));
+    const release = jest.fn();
+    const store = new PostgreSQLProjectMembershipStore({
+      pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool,
+    });
+
+    await expect(store.create({ ...membership, joinedAt: undefined as never, updatedAt: undefined as never }))
+      .rejects.toThrow("broken");
+    expect(clientQuery.mock.calls.map((call) => call[0])).toContain("ROLLBACK");
+    expect(release).toHaveBeenCalled();
+  });
+
+  it("initializes only an empty project under its deterministic advisory lock", async () => {
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [membership] })
+      .mockResolvedValueOnce({});
+    const store = new PostgreSQLProjectMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.createInitialOwner({ id: "member-1", tenantId: "tenant-1", projectId: "project-1", userId: "user-1" })).resolves.toEqual({ kind: "created", membership: expect.objectContaining({ id: "member-1" }) });
+    expect(clientQuery.mock.calls.map((call) => String(call[0]))).toEqual(expect.arrayContaining(["BEGIN", expect.stringContaining("pg_advisory_xact_lock"), expect.stringContaining("SELECT"), expect.stringContaining("INSERT INTO"), "COMMIT"]));
+    expect(clientQuery.mock.calls[2][0]).toContain("FOR UPDATE");
+  });
+
+  it.each(["create", "createInitialOwner"] as const)("rolls back malformed returning rows before commit for %s", async (operation) => {
+    const malformed = { ...membership, role: "bad" };
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT" || sql === "ROLLBACK") return Promise.resolve({});
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      if (sql.includes("project_id") && sql.includes("FOR UPDATE")) return Promise.resolve({ rows: [] });
+      if (sql.startsWith("SELECT id FROM")) return Promise.resolve({ rows: [] });
+      if (sql.includes("INSERT INTO")) return Promise.resolve({ rows: [malformed] });
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const release = jest.fn();
+    const store = new PostgreSQLProjectMembershipStore({ pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool });
+    const result = operation === "create"
+      ? store.create({ ...membership, joinedAt: undefined as never, updatedAt: undefined as never })
+      : store.createInitialOwner({ id: membership.id, tenantId: membership.tenant_id, projectId: membership.project_id, userId: membership.user_id });
+    await expect(result).rejects.toThrow("Invalid project membership row");
+    expect(clientQuery.mock.calls.map((call) => call[0])).toContain("ROLLBACK");
+    expect(clientQuery.mock.calls.map((call) => call[0])).not.toContain("COMMIT");
+    expect(release).toHaveBeenCalled();
+  });
+
+  it("rolls back and releases an initialization transaction on failure", async () => {
+    const release = jest.fn();
+    const clientQuery = jest.fn().mockResolvedValueOnce({}).mockResolvedValueOnce({}).mockRejectedValueOnce(new Error("broken"));
+    const transaction = { query: clientQuery, release };
+    const store = new PostgreSQLProjectMembershipStore({ pool: { connect: jest.fn().mockResolvedValue(transaction) } as unknown as Pool });
+    await expect(store.createInitialOwner({ id: "member-1", tenantId: "tenant-1", projectId: "project-1", userId: "user-1" })).rejects.toThrow("broken");
+    expect(clientQuery.mock.calls.map((call) => call[0])).toContain("ROLLBACK");
+    expect(release).toHaveBeenCalled();
+  });
+
+  it("maps an initial-owner tenant-wide ID collision", async () => {
+    const clientQuery = jest.fn()
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({})
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [] })
+      .mockRejectedValueOnce(Object.assign(new Error("duplicate"), { code: "23505", constraint: "lattice_project_memberships_pkey" }));
+    const store = new PostgreSQLProjectMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.createInitialOwner({ id: "member-1", tenantId: "tenant-1", projectId: "project-1", userId: "user-1" })).rejects.toBeInstanceOf(ProjectMembershipIdConflictError);
+    expect(clientQuery.mock.calls.map((call) => call[0])).toContain("ROLLBACK");
+  });
+
+  it("returns not_found without updating an absent membership", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("project_id FROM")) return Promise.resolve({ rows: [] });
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const store = new PostgreSQLProjectMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.updateRole({ tenantId: "tenant-1", id: "member-1", role: "admin", expectedUpdatedAt: now })).resolves.toEqual({ kind: "not_found" });
+  });
+
+  it("returns last_owner without updating the sole active owner", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("project_id FROM")) return Promise.resolve({ rows: [membership] });
+      if (sql.includes("active")) return Promise.resolve({ rows: [] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      if (sql.includes("FOR UPDATE")) return Promise.resolve({ rows: [membership] });
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const store = new PostgreSQLProjectMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.remove({ tenantId: "tenant-1", id: "member-1", expectedUpdatedAt: now })).resolves.toEqual({ kind: "last_owner" });
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).trimStart().startsWith("UPDATE"))).toBe(false);
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).includes("active") && String(call[0]).includes("FOR UPDATE"))).toBe(true);
+  });
+
+  it("uses exact updated_at CAS for a successful role update", async () => {
+    const otherOwner = { ...membership, id: "member-2", user_id: "user-2" };
+    const updated = { ...membership, role: "admin", updated_at: new Date("2026-08-30T12:00:00.001Z") };
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("project_id FROM")) return Promise.resolve({ rows: [membership] });
+      if (sql.includes("active")) return Promise.resolve({ rows: [membership, otherOwner] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      if (sql.includes("UPDATE")) return Promise.resolve({ rows: [updated] });
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const store = new PostgreSQLProjectMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.updateRole({ tenantId: "tenant-1", id: "member-1", role: "admin", expectedUpdatedAt: now })).resolves.toMatchObject({ kind: "updated", membership: { role: "admin" } });
+    const updateCall = clientQuery.mock.calls.find((call) => String(call[0]).trimStart().startsWith("UPDATE")) as [string, unknown[]];
+    expect(updateCall[1]).toContain(now);
+    expect(updateCall[1]).toEqual(["tenant-1", "member-1", now, "admin"]);
+    expect(updateCall[0]).toContain("date_trunc('milliseconds', updated_at) = $3");
+    expect(updateCall[0]).toContain("date_trunc('milliseconds', clock_timestamp())");
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).includes("active") && String(call[0]).includes("FOR UPDATE"))).toBe(true);
+  });
+
+  it("uses monotonic millisecond revision SQL for removal", async () => {
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT") return Promise.resolve({});
+      if (sql.includes("project_id FROM")) return Promise.resolve({ rows: [membership] });
+      if (sql.includes("active")) return Promise.resolve({ rows: [membership, { ...membership, id: "member-2" }] });
+      if (sql.includes("UPDATE")) return Promise.resolve({ rows: [{ ...membership, status: "removed", updated_at: new Date(now.getTime() + 1) }] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const store = new PostgreSQLProjectMembershipStore({ pool: transactionPool(clientQuery) });
+    await expect(store.remove({ tenantId: "tenant-1", id: "member-1", expectedUpdatedAt: now })).resolves.toMatchObject({ kind: "removed", membership: { status: "removed" } });
+    const updateCall = clientQuery.mock.calls.find((call) => String(call[0]).trimStart().startsWith("UPDATE")) as [string, unknown[]];
+    expect(updateCall[0]).toContain("GREATEST(date_trunc('milliseconds', updated_at) + interval '1 millisecond', date_trunc('milliseconds', clock_timestamp()))");
+    expect(updateCall[0]).toContain("date_trunc('milliseconds', updated_at) = $3");
+    expect(updateCall[1]).toEqual(["tenant-1", "member-1", now]);
+  });
+
+  it.each(["updateRole", "remove"] as const)("validates every locked active row before %s", async (operation) => {
+    const malformed = { ...membership, id: "member-2", role: "invalid" };
+    const clientQuery = jest.fn().mockImplementation((sql: string) => {
+      if (sql === "BEGIN" || sql === "COMMIT" || sql === "ROLLBACK") return Promise.resolve({});
+      if (sql.includes("project_id FROM")) return Promise.resolve({ rows: [membership] });
+      if (sql.includes("pg_advisory_xact_lock")) return Promise.resolve({});
+      if (sql.includes("status = 'active'") && sql.includes("FOR UPDATE")) {
+        return Promise.resolve({ rows: [membership, malformed] });
+      }
+      throw new Error(`unexpected SQL: ${sql}`);
+    });
+    const release = jest.fn();
+    const store = new PostgreSQLProjectMembershipStore({
+      pool: { connect: jest.fn().mockResolvedValue({ query: clientQuery, release }) } as unknown as Pool,
+    });
+
+    const result = operation === "updateRole"
+      ? store.updateRole({ tenantId: "tenant-1", id: "member-1", role: "admin", expectedUpdatedAt: now })
+      : store.remove({ tenantId: "tenant-1", id: "member-1", expectedUpdatedAt: now });
+    await expect(result).rejects.toThrow("Invalid project membership row");
+    expect(clientQuery.mock.calls.map((call) => call[0])).toContain("ROLLBACK");
+    expect(clientQuery.mock.calls.some((call) => String(call[0]).trimStart().startsWith("UPDATE"))).toBe(false);
+    expect(release).toHaveBeenCalled();
+  });
+
+  it("rejects malformed membership rows", async () => {
+    query.mockResolvedValueOnce({ rows: [{ ...membership, role: "invalid" }] });
+    const store = new PostgreSQLProjectMembershipStore({ pool });
+    await expect(store.list("tenant-1", "project-1")).rejects.toThrow("Invalid project membership row");
+  });
+});

package/src/__tests__/PostgreSQLProjectRoomMessageStore.test.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type { Pool } from "pg";
+
+import {
+  DuplicateProjectRoomMessageIdempotencyKeyError,
+  PostgreSQLProjectRoomMessageStore,
+  ProjectRoomMessageIdConflictError,
+} from "../stores/PostgreSQLProjectRoomMessageStore";
+
+const query = jest.fn();
+const pool = { query } as unknown as Pool;
+const now = new Date("2026-08-30T12:00:00.000Z");
+const row = {
+  id: "message-1", tenant_id: "tenant-1", workspace_id: "workspace-1", project_id: "project-1", room_id: "room-1",
+  author: { type: "human", userId: "user-1" }, content: { type: "text", text: "Hello" },
+  mentions: [{ type: "team" }], reply_to_message_id: null, source: "user", source_id: null,
+  idempotency_key: null, created_at: now,
+};
+
+describe("PostgreSQLProjectRoomMessageStore", () => {
+  beforeEach(() => query.mockReset());
+
+  it("creates with an explicit millisecond timestamp and exact parameters", async () => {
+    query.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLProjectRoomMessageStore({ pool });
+    await expect(store.create({
+      id: "message-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      author: { type: "human", userId: "user-1" }, content: { type: "text", text: "Hello" }, mentions: [{ type: "team" }], source: "user",
+    })).resolves.toMatchObject({ id: "message-1", createdAt: now });
+    expect(query.mock.calls[0][0]).toContain("date_trunc('milliseconds', clock_timestamp())");
+    expect(query.mock.calls[0][1]).toEqual(["message-1", "tenant-1", "workspace-1", "project-1", "room-1", JSON.stringify({ type: "human", userId: "user-1" }), JSON.stringify({ type: "text", text: "Hello" }), JSON.stringify([{ type: "team" }]), null, "user", null, null]);
+  });
+
+  it.each([
+    ["lattice_project_room_messages_pkey", ProjectRoomMessageIdConflictError],
+    ["uq_lattice_project_room_messages_idempotency", DuplicateProjectRoomMessageIdempotencyKeyError],
+  ])("maps ordinary create constraint %s", async (constraint, ErrorType) => {
+    query.mockRejectedValueOnce(Object.assign(new Error("raw sql"), { code: "23505", constraint }));
+    const store = new PostgreSQLProjectRoomMessageStore({ pool });
+    await expect(store.create({
+      id: "message-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      author: { type: "system" }, content: { type: "text", text: "Hello" }, mentions: [], source: "system", idempotencyKey: "key-1",
+    })).rejects.toBeInstanceOf(ErrorType);
+  });
+
+  it("returns the canonical row atomically for an idempotency conflict without semantic changes", async () => {
+    query.mockResolvedValueOnce({ rows: [{ ...row, id: "canonical", idempotency_key: "key-1" }] });
+    const store = new PostgreSQLProjectRoomMessageStore({ pool });
+    await expect(store.createIdempotent({
+      id: "candidate", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      author: { type: "system" }, content: { type: "text", text: "Different" }, mentions: [], source: "system", idempotencyKey: "key-1",
+    })).resolves.toMatchObject({ id: "canonical", content: { text: "Hello" } });
+    const [sql, params] = query.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("ON CONFLICT (tenant_id, room_id, idempotency_key) WHERE idempotency_key IS NOT NULL");
+    expect(sql).toContain("DO UPDATE SET idempotency_key = lattice_project_room_messages.idempotency_key");
+    expect(params[0]).toBe("candidate");
+  });
+
+  it("maps a candidate ID collision during idempotent creation", async () => {
+    query.mockRejectedValueOnce(Object.assign(new Error("duplicate"), { code: "23505", constraint: "lattice_project_room_messages_pkey" }));
+    const store = new PostgreSQLProjectRoomMessageStore({ pool });
+    await expect(store.createIdempotent({
+      id: "candidate", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      author: { type: "system" }, content: { type: "text", text: "Hello" }, mentions: [], source: "system", idempotencyKey: "key-1",
+    })).rejects.toBeInstanceOf(ProjectRoomMessageIdConflictError);
+  });
+
+  it("lists with exact descending cursor SQL and clamps the limit", async () => {
+    query.mockResolvedValueOnce({ rows: [row] }).mockResolvedValueOnce({ rows: [] });
+    const store = new PostgreSQLProjectRoomMessageStore({ pool });
+    await store.list({ tenantId: "tenant-1", roomId: "room-1", before: { createdAt: now, id: "message-2" }, limit: 500 });
+    expect(query.mock.calls[0][0]).toContain("created_at < $3 OR (created_at = $3 AND id < $4)");
+    expect(query.mock.calls[0][0]).toContain("ORDER BY created_at DESC, id DESC LIMIT $5");
+    expect(query.mock.calls[0][1]).toEqual(["tenant-1", "room-1", now, "message-2", 100]);
+    await store.list({ tenantId: "tenant-1", roomId: "room-1", limit: 0 });
+    expect(query.mock.calls[1][1]).toEqual(["tenant-1", "room-1", 1]);
+  });
+
+  it("rejects an invalid cursor date before querying", async () => {
+    const store = new PostgreSQLProjectRoomMessageStore({ pool });
+    await expect(store.list({ tenantId: "tenant-1", roomId: "room-1", before: { createdAt: new Date("bad"), id: "x" }, limit: 10 }))
+      .rejects.toThrow(RangeError);
+    expect(query).not.toHaveBeenCalled();
+  });
+
+  it("finds by exact tenant and ID", async () => {
+    query.mockResolvedValueOnce({ rows: [row] });
+    await expect(new PostgreSQLProjectRoomMessageStore({ pool }).findById("tenant-1", "message-1"))
+      .resolves.toMatchObject({ id: "message-1" });
+    expect(query.mock.calls[0][1]).toEqual(["tenant-1", "message-1"]);
+  });
+
+  it.each([
+    { author: { type: "human", userId: 1 } },
+    { content: { type: "html", text: "x" } },
+    { mentions: [{ type: "bot" }] },
+    { source: "external" },
+  ])("rejects malformed JSON or discriminants %#", async (patch) => {
+    query.mockResolvedValueOnce({ rows: [{ ...row, ...patch }] });
+    await expect(new PostgreSQLProjectRoomMessageStore({ pool }).findById("tenant-1", "message-1"))
+      .rejects.toThrow("Invalid project room message row");
+  });
+});