@axiom-lattice/pg-stores 3.1.0 → 3.1.2

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");
+  });
+});

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

@@ -0,0 +1,114 @@
+import { describe, expect, it, jest } from "@jest/globals";
+import type { PoolClient } from "pg";
+
+const registeredMigrationNames: string[] = [];
+
+jest.mock("@axiom-lattice/core", () => ({}));
+
+jest.mock("pg", () => ({
+  Pool: class Pool {},
+}));
+
+jest.mock("../migrations/migration", () => ({
+  MigrationManager: class MigrationManager {
+    register(migration: { name: string }): void {
+      registeredMigrationNames.push(migration.name);
+    }
+
+    async migrate(): Promise<void> {
+      throw new Error("stop after migrations");
+    }
+  },
+}));
+
+import { createPgStoreConfig } from "../createPgStoreConfig";
+import { createProjectRoomTables } from "../migrations/project_room_migration";
+
+function normalizeSql(sql: string): string {
+  return sql.replace(/\s+/g, " ").trim();
+}
+
+describe("project room migration", () => {
+  it("has a globally unique identity and is centrally registered before migration", async () => {
+    expect(createProjectRoomTables.version).toBe(172);
+    expect(createProjectRoomTables.name).toBe("create_project_room_tables");
+
+    registeredMigrationNames.length = 0;
+    await expect(createPgStoreConfig("postgres://unused")).rejects.toThrow("stop after migrations");
+
+    expect(registeredMigrationNames).toContain("create_project_room_tables");
+    expect(registeredMigrationNames.filter((name) => name === "create_project_room_tables")).toHaveLength(1);
+  });
+
+  it("creates the four tables with their checks, uniqueness rules, and query indexes", async () => {
+    const statements: string[] = [];
+    const client = {
+      query: async (sql: string) => {
+        statements.push(normalizeSql(sql));
+        return { rows: [] };
+      },
+    } as unknown as PoolClient;
+
+    await createProjectRoomTables.up(client);
+    const sql = statements.join("\n");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_rooms");
+    expect(sql).toContain("PRIMARY KEY (tenant_id, id)");
+    expect(sql).toContain("UNIQUE (tenant_id, project_id, type)");
+    expect(sql).toContain("CHECK (type IN ('main'))");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_memberships");
+    expect(sql).toContain("CHECK (role IN ('owner', 'admin', 'member', 'viewer'))");
+    expect(sql).toContain("CHECK (status IN ('active', 'removed'))");
+    expect(sql).toContain("UNIQUE (tenant_id, project_id, user_id)");
+    expect(sql).toContain("idx_lattice_project_memberships_project");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_bot_memberships");
+    expect(sql).toContain("CHECK (role IN ('coordinator', 'specialist'))");
+    expect(sql).toContain("CHECK (status IN ('active', 'paused', 'removed'))");
+    expect(sql).toContain("UNIQUE (tenant_id, project_id, assistant_id)");
+    expect(sql).toContain("idx_lattice_project_bot_memberships_project");
+    expect(sql).toContain("idx_lattice_project_bot_memberships_room");
+    expect(sql).toContain("UNIQUE INDEX IF NOT EXISTS uq_lattice_project_bot_memberships_coordinator");
+    expect(sql).toContain("ON lattice_project_bot_memberships (tenant_id, project_id) WHERE role = 'coordinator' AND status IN ('active', 'paused')");
+    expect(sql).toContain("UNIQUE INDEX IF NOT EXISTS uq_lattice_project_bot_memberships_mention");
+    expect(sql).toContain("ON lattice_project_bot_memberships (tenant_id, room_id, mention_name) WHERE status IN ('active', 'paused')");
+
+    expect(sql).toContain("CREATE TABLE IF NOT EXISTS lattice_project_room_messages");
+    expect(sql).toContain("author JSONB NOT NULL");
+    expect(sql).toContain("content JSONB NOT NULL");
+    expect(sql).toContain("mentions JSONB NOT NULL DEFAULT '[]'::jsonb");
+    expect(sql).toContain("CHECK (source IN ('user', 'agent', 'task', 'routine', 'system'))");
+    expect(sql).toContain("UNIQUE INDEX IF NOT EXISTS uq_lattice_project_room_messages_idempotency");
+    expect(sql).toContain("ON lattice_project_room_messages (tenant_id, room_id, idempotency_key) WHERE idempotency_key IS NOT NULL");
+    expect(sql).toContain("idx_lattice_project_room_messages_room_created");
+    expect(sql).toContain("ON lattice_project_room_messages (tenant_id, room_id, created_at DESC, id DESC)");
+    expect(sql).not.toMatch(/REFERENCES\s/i);
+  });
+
+  it("drops indexes and tables in reverse dependency order", async () => {
+    const statements: string[] = [];
+    const client = {
+      query: async (sql: string) => {
+        statements.push(normalizeSql(sql));
+        return { rows: [] };
+      },
+    } as unknown as PoolClient;
+
+    await createProjectRoomTables.down?.(client);
+
+    expect(statements).toEqual([
+      "DROP INDEX IF EXISTS idx_lattice_project_room_messages_room_created",
+      "DROP INDEX IF EXISTS uq_lattice_project_room_messages_idempotency",
+      "DROP TABLE IF EXISTS lattice_project_room_messages",
+      "DROP INDEX IF EXISTS idx_lattice_project_bot_memberships_room",
+      "DROP INDEX IF EXISTS idx_lattice_project_bot_memberships_project",
+      "DROP INDEX IF EXISTS uq_lattice_project_bot_memberships_mention",
+      "DROP INDEX IF EXISTS uq_lattice_project_bot_memberships_coordinator",
+      "DROP TABLE IF EXISTS lattice_project_bot_memberships",
+      "DROP INDEX IF EXISTS idx_lattice_project_memberships_project",
+      "DROP TABLE IF EXISTS lattice_project_memberships",
+      "DROP TABLE IF EXISTS lattice_project_rooms",
+    ]);
+  });
+});

package/src/__tests__/PostgreSQLProjectRoomStore.test.ts

@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type { Pool } from "pg";
+
+import { PostgreSQLProjectRoomStore } from "../stores/PostgreSQLProjectRoomStore";
+
+const query = jest.fn();
+const pool = { query } as unknown as Pool;
+const now = new Date("2026-08-30T12:00:00.000Z");
+const row = {
+  id: "room-1", tenant_id: "tenant-1", workspace_id: "workspace-1", project_id: "project-1",
+  type: "main", name: "Main", created_at: now, updated_at: now,
+};
+
+describe("PostgreSQLProjectRoomStore", () => {
+  beforeEach(() => query.mockReset());
+
+  it("atomically ensures the persisted winner without changing its semantic fields", async () => {
+    query.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLProjectRoomStore({ pool });
+
+    await expect(store.ensureMainRoom({
+      id: "candidate", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", name: "Candidate",
+    })).resolves.toEqual({
+      id: "room-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1",
+      type: "main", name: "Main", createdAt: now, updatedAt: now,
+    });
+
+    const [sql, params] = query.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("ON CONFLICT (tenant_id, project_id, type)");
+    expect(sql).toContain("SET updated_at = lattice_project_rooms.updated_at");
+    expect(sql).toContain("RETURNING");
+    expect(params).toEqual(["candidate", "tenant-1", "workspace-1", "project-1", "main", "Candidate"]);
+  });
+
+  it("uses exact tenant filters when finding the main room", async () => {
+    query.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLProjectRoomStore({ pool });
+    await expect(store.getMainRoom("tenant-1", "project-1")).resolves.toMatchObject({ id: "room-1" });
+    expect(query.mock.calls[0][0]).toContain("WHERE tenant_id = $1 AND project_id = $2 AND type = 'main'");
+    expect(query.mock.calls[0][1]).toEqual(["tenant-1", "project-1"]);
+  });
+
+  it("rejects malformed rows", async () => {
+    query.mockResolvedValueOnce({ rows: [{ ...row, type: "side" }] });
+    const store = new PostgreSQLProjectRoomStore({ pool });
+    await expect(store.getMainRoom("tenant-1", "project-1")).rejects.toThrow("Invalid project room row");
+  });
+});