@axiom-lattice/pg-stores 3.1.0 → 3.1.2

package/src/stores/PostgreSQLChannelInstallationStore.ts

@@ -4,8 +4,7 @@ import {
   ChannelInstallation,
   ChannelInstallationStore,
   ChannelInstallationType,
-  CreateChannelInstallationRequest,
-  LarkChannelInstallationConfig,
+  CreateChannelInstallationInput,
   UpdateChannelInstallationRequest,
 } from "@axiom-lattice/protocols";
 import { MigrationManager } from "../migrations/migration";
@@ -179,12 +178,13 @@ export class PostgreSQLChannelInstallationStore
   async createInstallation(
     tenantId: string,
     installationId: string,
-    data: CreateChannelInstallationRequest,
+    data: CreateChannelInstallationInput,
   ): Promise<ChannelInstallation> {
     await this.ensureInitialized();
 
     const now = new Date();
-    const encryptedConfig = this.encryptSecrets(data.config as unknown as Record<string, unknown>);
+    const config = { ...data.config };
+    const encryptedConfig = this.encryptSecrets(config);
 
     await this.pool.query(
       `
@@ -211,7 +211,7 @@ export class PostgreSQLChannelInstallationStore
       tenantId,
       channel: data.channel,
       name: data.name,
-      config: data.config,
+      config,
       enabled: data.enabled ?? true,
       fallbackAgentId: data.fallbackAgentId,
       rejectWhenNoBinding: data.rejectWhenNoBinding ?? true,
@@ -308,7 +308,7 @@ export class PostgreSQLChannelInstallationStore
         typeof row.config === "string"
           ? JSON.parse(row.config)
           : row.config,
-      ) as unknown as LarkChannelInstallationConfig,
+      ),
       enabled: row.enabled,
       fallbackAgentId: row.fallback_agent_id || undefined,
       rejectWhenNoBinding: row.reject_when_no_binding,
@@ -322,18 +322,9 @@ export class PostgreSQLChannelInstallationStore
   ): Record<string, unknown> {
     return {
       ...config,
-      appSecret:
-        typeof config.appSecret === "string"
-          ? encrypt(config.appSecret)
-          : config.appSecret,
-      verificationToken:
-        typeof config.verificationToken === "string"
-          ? encrypt(config.verificationToken)
-          : config.verificationToken,
-      encryptKey:
-        typeof config.encryptKey === "string"
-          ? encrypt(config.encryptKey)
-          : config.encryptKey,
+      ...(typeof config.appSecret === "string" ? { appSecret: encrypt(config.appSecret) } : {}),
+      ...(typeof config.verificationToken === "string" ? { verificationToken: encrypt(config.verificationToken) } : {}),
+      ...(typeof config.encryptKey === "string" ? { encryptKey: encrypt(config.encryptKey) } : {}),
     };
   }
 
@@ -342,18 +333,9 @@ export class PostgreSQLChannelInstallationStore
   ): Record<string, unknown> {
     return {
       ...config,
-      appSecret:
-        typeof config.appSecret === "string"
-          ? decrypt(config.appSecret)
-          : config.appSecret,
-      verificationToken:
-        typeof config.verificationToken === "string"
-          ? decrypt(config.verificationToken)
-          : config.verificationToken,
-      encryptKey:
-        typeof config.encryptKey === "string"
-          ? decrypt(config.encryptKey)
-          : config.encryptKey,
+      ...(typeof config.appSecret === "string" ? { appSecret: decrypt(config.appSecret) } : {}),
+      ...(typeof config.verificationToken === "string" ? { verificationToken: decrypt(config.verificationToken) } : {}),
+      ...(typeof config.encryptKey === "string" ? { encryptKey: decrypt(config.encryptKey) } : {}),
     };
   }
 }

package/src/stores/PostgreSQLProjectBotMembershipStore.ts

@@ -0,0 +1,199 @@
+import type {
+  ProjectBotMembership,
+  ProjectBotMembershipStatus,
+  ProjectBotMembershipStore,
+  ProjectBotRole,
+} from "@axiom-lattice/protocols";
+import type { Pool, PoolClient } from "pg";
+
+type BotMembershipRow = {
+  id: unknown; tenant_id: unknown; workspace_id: unknown; project_id: unknown; room_id: unknown;
+  assistant_id: unknown; role: unknown; title: unknown; responsibility: unknown; mention_name: unknown;
+  status: unknown; room_thread_id: unknown; joined_at: unknown; updated_at: unknown;
+};
+type PostgreSQLError = { code?: unknown; constraint?: unknown };
+type ConstraintConflict = "coordinator_conflict" | "mention_conflict";
+
+const columns = "id, tenant_id, workspace_id, project_id, room_id, assistant_id, role, title, responsibility, mention_name, status, room_thread_id, joined_at, updated_at";
+
+/** Indicates that a new bot membership ID already exists in the tenant. */
+export class ProjectBotMembershipIdConflictError extends Error {
+  /** Creates an accurate tenant-scoped membership ID collision error. */
+  constructor(tenantId: string, id: string) {
+    super(`Project bot membership ID '${id}' already exists in tenant '${tenantId}'`);
+    this.name = "ProjectBotMembershipIdConflictError";
+  }
+}
+
+function isDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+function isRole(value: unknown): value is ProjectBotRole {
+  return value === "coordinator" || value === "specialist";
+}
+function isStatus(value: unknown): value is ProjectBotMembershipStatus {
+  return value === "active" || value === "paused" || value === "removed";
+}
+function mapRow(row: BotMembershipRow): ProjectBotMembership {
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string" || typeof row.workspace_id !== "string"
+    || typeof row.project_id !== "string" || typeof row.room_id !== "string" || typeof row.assistant_id !== "string"
+    || !isRole(row.role) || typeof row.title !== "string"
+    || (row.responsibility !== null && typeof row.responsibility !== "string")
+    || typeof row.mention_name !== "string" || !isStatus(row.status) || typeof row.room_thread_id !== "string"
+    || !isDate(row.joined_at) || !isDate(row.updated_at)) {
+    throw new Error("Invalid project bot membership row");
+  }
+  return {
+    id: row.id, tenantId: row.tenant_id, workspaceId: row.workspace_id, projectId: row.project_id,
+    roomId: row.room_id, assistantId: row.assistant_id, role: row.role, title: row.title,
+    ...(row.responsibility === null ? {} : { responsibility: row.responsibility }),
+    mentionName: row.mention_name, status: row.status, roomThreadId: row.room_thread_id,
+    joinedAt: row.joined_at, updatedAt: row.updated_at,
+  };
+}
+function isUniqueViolation(error: unknown): error is PostgreSQLError {
+  return typeof error === "object" && error !== null && "code" in error
+    && (error as PostgreSQLError).code === "23505";
+}
+function constraintConflict(error: unknown): ConstraintConflict | undefined {
+  if (!isUniqueViolation(error) || typeof error.constraint !== "string") return undefined;
+  if (error.constraint === "uq_lattice_project_bot_memberships_coordinator") return "coordinator_conflict";
+  if (error.constraint === "uq_lattice_project_bot_memberships_mention") return "mention_conflict";
+  return undefined;
+}
+async function rollback(client: PoolClient): Promise<void> {
+  try { await client.query("ROLLBACK"); } catch { /* preserve the original outcome */ }
+}
+
+/** Persists tenant-isolated project bot roster memberships in PostgreSQL. */
+export class PostgreSQLProjectBotMembershipStore implements ProjectBotMembershipStore {
+  /** Creates a store using an externally managed shared pool. */
+  constructor(options: { pool: Pool }) { this.pool = options.pool; }
+  private readonly pool: Pool;
+
+  /** Lists retained memberships in stable join order. */
+  async list(tenantId: string, projectId: string): Promise<ProjectBotMembership[]> {
+    const result = await this.pool.query<BotMembershipRow>(
+      `SELECT ${columns} FROM lattice_project_bot_memberships WHERE tenant_id = $1 AND project_id = $2 ORDER BY joined_at ASC, id ASC`,
+      [tenantId, projectId],
+    );
+    return result.rows.map(mapRow);
+  }
+
+  /** Finds a membership by tenant-scoped ID. */
+  async findById(tenantId: string, id: string): Promise<ProjectBotMembership | null> {
+    const result = await this.pool.query<BotMembershipRow>(
+      `SELECT ${columns} FROM lattice_project_bot_memberships WHERE tenant_id = $1 AND id = $2`, [tenantId, id],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  /** Finds an assistant's durable membership in a tenant-scoped project. */
+  async findByAssistant(tenantId: string, projectId: string, assistantId: string): Promise<ProjectBotMembership | null> {
+    const result = await this.pool.query<BotMembershipRow>(
+      `SELECT ${columns} FROM lattice_project_bot_memberships WHERE tenant_id = $1 AND project_id = $2 AND assistant_id = $3`,
+      [tenantId, projectId, assistantId],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  /** Inserts a new membership or reactivates the assistant's durable membership atomically. */
+  async save(input: Omit<ProjectBotMembership, "joinedAt" | "updatedAt">): Promise<
+    { kind: "created" | "updated" | "reactivated"; membership: ProjectBotMembership } | { kind: ConstraintConflict }
+  > {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${input.tenantId}:${input.projectId}`]);
+      const existingResult = await client.query<BotMembershipRow>(
+        `SELECT ${columns} FROM lattice_project_bot_memberships WHERE tenant_id = $1 AND project_id = $2 AND assistant_id = $3 FOR UPDATE`,
+        [input.tenantId, input.projectId, input.assistantId],
+      );
+      const existing = existingResult.rows[0] ? mapRow(existingResult.rows[0]) : undefined;
+      let result;
+      if (existing) {
+        result = await client.query<BotMembershipRow>(
+          `UPDATE lattice_project_bot_memberships
+           SET role = $3, title = $4, responsibility = $5, mention_name = $6, status = 'active',
+               updated_at = GREATEST(date_trunc('milliseconds', updated_at) + interval '1 millisecond', date_trunc('milliseconds', clock_timestamp()))
+           WHERE tenant_id = $1 AND id = $2 RETURNING ${columns}`,
+          [input.tenantId, existing.id, input.role, input.title, input.responsibility ?? null, input.mentionName],
+        );
+      } else {
+        const idResult = await client.query<{ id: unknown }>(
+          "SELECT id FROM lattice_project_bot_memberships WHERE tenant_id = $1 AND id = $2", [input.tenantId, input.id],
+        );
+        if (idResult.rows.length > 0) throw new ProjectBotMembershipIdConflictError(input.tenantId, input.id);
+        result = await client.query<BotMembershipRow>(
+          `INSERT INTO lattice_project_bot_memberships
+           (id, tenant_id, workspace_id, project_id, room_id, assistant_id, role, title, responsibility, mention_name, status, room_thread_id, joined_at, updated_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, 'active', $11, date_trunc('milliseconds', clock_timestamp()), date_trunc('milliseconds', clock_timestamp()))
+           RETURNING ${columns}`,
+          [input.id, input.tenantId, input.workspaceId, input.projectId, input.roomId, input.assistantId,
+            input.role, input.title, input.responsibility ?? null, input.mentionName, input.roomThreadId],
+        );
+      }
+      const membership = mapRow(result.rows[0]);
+      await client.query("COMMIT");
+      return { kind: existing === undefined ? "created" : existing.status === "removed" ? "reactivated" : "updated", membership };
+    } catch (error) {
+      await rollback(client);
+      const conflict = constraintConflict(error);
+      if (conflict) return { kind: conflict };
+      if (isUniqueViolation(error) && error.constraint === "lattice_project_bot_memberships_pkey") {
+        throw new ProjectBotMembershipIdConflictError(input.tenantId, input.id);
+      }
+      throw error;
+    } finally { client.release(); }
+  }
+
+  /** Applies a mutable-field patch with project serialization and millisecond-safe optimistic concurrency. */
+  async update(input: {
+    tenantId: string;
+    id: string;
+    patch: Partial<Pick<ProjectBotMembership, "role" | "title" | "responsibility" | "mentionName" | "status">>;
+    expectedUpdatedAt: Date;
+  }): Promise<
+    { kind: "updated"; membership: ProjectBotMembership }
+    | { kind: "not_found" | "conflict" | ConstraintConflict }
+  > {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const identity = await client.query<{ project_id: unknown }>(
+        "SELECT project_id FROM lattice_project_bot_memberships WHERE tenant_id = $1 AND id = $2", [input.tenantId, input.id],
+      );
+      if (!identity.rows[0]) { await client.query("COMMIT"); return { kind: "not_found" }; }
+      if (typeof identity.rows[0].project_id !== "string") throw new Error("Invalid project bot membership row");
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${input.tenantId}:${identity.rows[0].project_id}`]);
+      const locked = await client.query<BotMembershipRow>(
+        `SELECT ${columns} FROM lattice_project_bot_memberships WHERE tenant_id = $1 AND id = $2 FOR UPDATE`,
+        [input.tenantId, input.id],
+      );
+      if (!locked.rows[0]) { await client.query("COMMIT"); return { kind: "not_found" }; }
+      const existing = mapRow(locked.rows[0]);
+      if (existing.updatedAt.getTime() !== input.expectedUpdatedAt.getTime()) {
+        await client.query("COMMIT"); return { kind: "conflict" };
+      }
+      const candidate = { ...existing, ...input.patch };
+      const updated = await client.query<BotMembershipRow>(
+        `UPDATE lattice_project_bot_memberships
+         SET role = $4, title = $5, responsibility = $6, mention_name = $7, status = $8,
+             updated_at = GREATEST(date_trunc('milliseconds', updated_at) + interval '1 millisecond', date_trunc('milliseconds', clock_timestamp()))
+         WHERE tenant_id = $1 AND id = $2 AND date_trunc('milliseconds', updated_at) = $3
+         RETURNING ${columns}`,
+        [input.tenantId, input.id, input.expectedUpdatedAt, candidate.role, candidate.title,
+          candidate.responsibility ?? null, candidate.mentionName, candidate.status],
+      );
+      if (!updated.rows[0]) { await client.query("COMMIT"); return { kind: "conflict" }; }
+      const membership = mapRow(updated.rows[0]);
+      await client.query("COMMIT");
+      return { kind: "updated", membership };
+    } catch (error) {
+      await rollback(client);
+      const conflict = constraintConflict(error);
+      if (conflict) return { kind: conflict };
+      throw error;
+    } finally { client.release(); }
+  }
+}

package/src/stores/PostgreSQLProjectMembershipStore.ts

@@ -0,0 +1,140 @@
+import type {
+  ProjectHumanRole, ProjectMembership, ProjectMembershipMutationResult, ProjectMembershipStore,
+} from "@axiom-lattice/protocols";
+import type { Pool, PoolClient } from "pg";
+
+type MembershipRow = {
+  id: unknown; tenant_id: unknown; project_id: unknown; user_id: unknown;
+  role: unknown; status: unknown; joined_at: unknown; updated_at: unknown;
+};
+type DuplicateError = { code?: unknown; constraint?: unknown };
+
+/** Indicates that a tenant/project/user membership already exists. */
+export class DuplicateProjectMembershipError extends Error {
+  constructor() { super("Project membership already exists for tenant, project, and user"); this.name = "DuplicateProjectMembershipError"; }
+}
+
+/** Indicates that a membership ID already exists in the tenant. */
+export class ProjectMembershipIdConflictError extends Error {
+  constructor() { super("Project membership ID already exists for tenant"); this.name = "ProjectMembershipIdConflictError"; }
+}
+
+function isDate(value: unknown): value is Date { return value instanceof Date && !Number.isNaN(value.getTime()); }
+function isRole(value: unknown): value is ProjectHumanRole { return value === "owner" || value === "admin" || value === "member" || value === "viewer"; }
+function isStatus(value: unknown): value is "active" | "removed" { return value === "active" || value === "removed"; }
+function mapRow(row: MembershipRow): ProjectMembership {
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string" || typeof row.project_id !== "string"
+    || typeof row.user_id !== "string" || !isRole(row.role) || !isStatus(row.status)
+    || !isDate(row.joined_at) || !isDate(row.updated_at)) throw new Error("Invalid project membership row");
+  return { id: row.id, tenantId: row.tenant_id, projectId: row.project_id, userId: row.user_id,
+    role: row.role, status: row.status, joinedAt: row.joined_at, updatedAt: row.updated_at };
+}
+function isDuplicate(error: unknown): error is DuplicateError {
+  return typeof error === "object" && error !== null && "code" in error
+    && (error as DuplicateError).code === "23505";
+}
+function mapDuplicate(error: unknown): never {
+  if (isDuplicate(error) && typeof error.constraint === "string"
+    && error.constraint.includes("project_id_user_id")) throw new DuplicateProjectMembershipError();
+  if (isDuplicate(error)) throw new ProjectMembershipIdConflictError();
+  throw error;
+}
+const columns = "id, tenant_id, project_id, user_id, role, status, joined_at, updated_at";
+
+/** Persists tenant-isolated human project memberships in PostgreSQL. */
+export class PostgreSQLProjectMembershipStore implements ProjectMembershipStore {
+  /** Creates a store using an externally managed pool; the pool is not migrated or closed. */
+  constructor(options: { pool: Pool }) { this.pool = options.pool; }
+  private readonly pool: Pool;
+
+  /** Lists memberships in stable joined-time and ID order. */
+  async list(tenantId: string, projectId: string): Promise<ProjectMembership[]> {
+    const result = await this.pool.query<MembershipRow>(`SELECT ${columns} FROM lattice_project_memberships WHERE tenant_id = $1 AND project_id = $2 ORDER BY joined_at ASC, id ASC`, [tenantId, projectId]);
+    return result.rows.map(mapRow);
+  }
+  /** Finds a membership by exact tenant, project, and user identity. */
+  async findByUser(tenantId: string, projectId: string, userId: string): Promise<ProjectMembership | null> {
+    const result = await this.pool.query<MembershipRow>(`SELECT ${columns} FROM lattice_project_memberships WHERE tenant_id = $1 AND project_id = $2 AND user_id = $3`, [tenantId, projectId, userId]);
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+  /** Inserts a membership and maps database uniqueness errors to stable typed errors. */
+  async create(input: Omit<ProjectMembership, "joinedAt" | "updatedAt">): Promise<ProjectMembership> {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${input.tenantId}:${input.projectId}`]);
+      const result = await client.query<MembershipRow>(`INSERT INTO lattice_project_memberships (id, tenant_id, project_id, user_id, role, status, joined_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6, date_trunc('milliseconds', clock_timestamp()), date_trunc('milliseconds', clock_timestamp())) RETURNING ${columns}`, [input.id, input.tenantId, input.projectId, input.userId, input.role, input.status]);
+      const membership = mapRow(result.rows[0]);
+      await client.query("COMMIT");
+      return membership;
+    } catch (error) {
+      try { await client.query("ROLLBACK"); } catch { /* preserve original failure */ }
+      return mapDuplicate(error);
+    } finally { client.release(); }
+  }
+
+  /** Atomically creates the first active owner while serializing the project scope. */
+  async createInitialOwner(input: Omit<ProjectMembership, "role" | "status" | "joinedAt" | "updatedAt">): Promise<{ kind: "created" | "existing"; membership: ProjectMembership } | { kind: "already_initialized" }> {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${input.tenantId}:${input.projectId}`]);
+      const existingResult = await client.query<MembershipRow>(`SELECT ${columns} FROM lattice_project_memberships WHERE tenant_id = $1 AND project_id = $2 FOR UPDATE`, [input.tenantId, input.projectId]);
+      if (existingResult.rows.length > 0) {
+        const existing = existingResult.rows.map(mapRow).find((item) => item.userId === input.userId && item.role === "owner" && item.status === "active");
+        await client.query("COMMIT");
+        return existing ? { kind: "existing", membership: existing } : { kind: "already_initialized" };
+      }
+      const idResult = await client.query("SELECT id FROM lattice_project_memberships WHERE tenant_id = $1 AND id = $2", [input.tenantId, input.id]);
+      if (idResult.rows.length > 0) throw new ProjectMembershipIdConflictError();
+      const inserted = await client.query<MembershipRow>(`INSERT INTO lattice_project_memberships (id, tenant_id, project_id, user_id, role, status, joined_at, updated_at) VALUES ($1, $2, $3, $4, 'owner', 'active', date_trunc('milliseconds', clock_timestamp()), date_trunc('milliseconds', clock_timestamp())) RETURNING ${columns}`, [input.id, input.tenantId, input.projectId, input.userId]);
+      const membership = mapRow(inserted.rows[0]);
+      await client.query("COMMIT");
+      return { kind: "created", membership };
+    } catch (error) {
+      try { await client.query("ROLLBACK"); } catch { /* preserve original failure */ }
+      if (isDuplicate(error)) return mapDuplicate(error);
+      throw error;
+    }
+    finally { client.release(); }
+  }
+
+  /** Updates a role under a project lock with exact timestamp and owner safeguards. */
+  async updateRole(input: { tenantId: string; id: string; role: ProjectHumanRole; expectedUpdatedAt: Date }): Promise<ProjectMembershipMutationResult> {
+    return this.mutate(input.tenantId, input.id, input.expectedUpdatedAt, input.role, false);
+  }
+  /** Marks a membership removed under a project lock with exact timestamp and owner safeguards. */
+  async remove(input: { tenantId: string; id: string; expectedUpdatedAt: Date }): Promise<ProjectMembershipMutationResult> {
+    return this.mutate(input.tenantId, input.id, input.expectedUpdatedAt, undefined, true);
+  }
+  private async mutate(tenantId: string, id: string, expected: Date, role: ProjectHumanRole, remove: false): Promise<ProjectMembershipMutationResult>;
+  private async mutate(tenantId: string, id: string, expected: Date, role: undefined, remove: true): Promise<ProjectMembershipMutationResult>;
+  private async mutate(tenantId: string, id: string, expected: Date, role: ProjectHumanRole | undefined, remove: boolean): Promise<ProjectMembershipMutationResult> {
+    const client: PoolClient = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const identity = await client.query<{ project_id: unknown }>("SELECT project_id FROM lattice_project_memberships WHERE tenant_id = $1 AND id = $2", [tenantId, id]);
+       if (!identity.rows[0] || typeof identity.rows[0].project_id !== "string") { await client.query("COMMIT"); return { kind: "not_found" }; }
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${tenantId}:${identity.rows[0].project_id}`]);
+      const activeRows = await client.query<MembershipRow>(`SELECT ${columns} FROM lattice_project_memberships WHERE tenant_id = $1 AND project_id = $2 AND status = 'active' FOR UPDATE`, [tenantId, identity.rows[0].project_id]);
+      const lockedMemberships = activeRows.rows.map(mapRow);
+      let current = lockedMemberships.find((membership) => membership.id === id);
+      if (!current) {
+        const target = await client.query<MembershipRow>(`SELECT ${columns} FROM lattice_project_memberships WHERE tenant_id = $1 AND id = $2 FOR UPDATE`, [tenantId, id]);
+        if (!target.rows[0]) { await client.query("COMMIT"); return { kind: "not_found" }; }
+        current = mapRow(target.rows[0]);
+      }
+      if (current.updatedAt.getTime() !== expected.getTime()) { await client.query("COMMIT"); return { kind: "conflict" }; }
+      if (current.role === "owner" && current.status === "active" && (remove || role !== "owner")) {
+        const owners = lockedMemberships.filter((membership) => membership.id !== id && membership.role === "owner");
+        if (owners.length === 0) { await client.query("COMMIT"); return { kind: "last_owner" }; }
+      }
+      const result = await client.query<MembershipRow>(remove
+        ? `UPDATE lattice_project_memberships SET status = 'removed', updated_at = GREATEST(date_trunc('milliseconds', updated_at) + interval '1 millisecond', date_trunc('milliseconds', clock_timestamp())) WHERE tenant_id = $1 AND id = $2 AND date_trunc('milliseconds', updated_at) = $3 RETURNING ${columns}`
+        : `UPDATE lattice_project_memberships SET role = $4, updated_at = GREATEST(date_trunc('milliseconds', updated_at) + interval '1 millisecond', date_trunc('milliseconds', clock_timestamp())) WHERE tenant_id = $1 AND id = $2 AND date_trunc('milliseconds', updated_at) = $3 RETURNING ${columns}`, remove ? [tenantId, id, expected] : [tenantId, id, expected, role]);
+      if (!result.rows[0]) { await client.query("COMMIT"); return { kind: "conflict" }; }
+      await client.query("COMMIT"); return { kind: remove ? "removed" : "updated", membership: mapRow(result.rows[0]) };
+    } catch (error) { try { await client.query("ROLLBACK"); } catch { /* preserve original failure */ } throw error; }
+    finally { client.release(); }
+  }
+}

package/src/stores/PostgreSQLProjectRoomMessageStore.ts

@@ -0,0 +1,177 @@
+import type {
+  ProjectRoomMention,
+  ProjectRoomMessage,
+  ProjectRoomMessageAuthor,
+  ProjectRoomMessageSource,
+  ProjectRoomMessageStore,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+type MessageRow = {
+  id: unknown; tenant_id: unknown; workspace_id: unknown; project_id: unknown; room_id: unknown;
+  author: unknown; content: unknown; mentions: unknown; reply_to_message_id: unknown; source: unknown;
+  source_id: unknown; idempotency_key: unknown; created_at: unknown;
+};
+type PostgreSQLError = { code?: unknown; constraint?: unknown };
+
+const columns = "id, tenant_id, workspace_id, project_id, room_id, author, content, mentions, reply_to_message_id, source, source_id, idempotency_key, created_at";
+
+/** Indicates that a tenant-scoped room message ID already exists. */
+export class ProjectRoomMessageIdConflictError extends Error {
+  /** Creates an accurate tenant-scoped message ID collision error. */
+  constructor(tenantId: string, id: string) {
+    super(`Project room message ID '${id}' already exists in tenant '${tenantId}'`);
+    this.name = "ProjectRoomMessageIdConflictError";
+  }
+}
+
+/** Indicates that ordinary creation reused a room-scoped idempotency key. */
+export class DuplicateProjectRoomMessageIdempotencyKeyError extends Error {
+  /** Creates an accurate tenant and room-scoped idempotency collision error. */
+  constructor(tenantId: string, roomId: string, idempotencyKey: string) {
+    super(`Project room message idempotency key '${idempotencyKey}' already exists in tenant '${tenantId}' room '${roomId}'`);
+    this.name = "DuplicateProjectRoomMessageIdempotencyKeyError";
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  return Object.keys(value).every((key) => keys.includes(key));
+}
+function mapAuthor(value: unknown): ProjectRoomMessageAuthor | undefined {
+  if (!isRecord(value) || typeof value.type !== "string") return undefined;
+  if (value.type === "human" && hasOnlyKeys(value, ["type", "userId"]) && typeof value.userId === "string") return { type: "human", userId: value.userId };
+  if (value.type === "bot" && hasOnlyKeys(value, ["type", "membershipId", "assistantId"])
+    && typeof value.membershipId === "string" && typeof value.assistantId === "string") {
+    return { type: "bot", membershipId: value.membershipId, assistantId: value.assistantId };
+  }
+  if (value.type === "system" && hasOnlyKeys(value, ["type"])) return { type: "system" };
+  return undefined;
+}
+function mapMention(value: unknown): ProjectRoomMention | undefined {
+  if (!isRecord(value) || typeof value.type !== "string") return undefined;
+  if (value.type === "bot" && hasOnlyKeys(value, ["type", "membershipId"]) && typeof value.membershipId === "string") {
+    return { type: "bot", membershipId: value.membershipId };
+  }
+  if (value.type === "team" && hasOnlyKeys(value, ["type"])) return { type: "team" };
+  return undefined;
+}
+function isSource(value: unknown): value is ProjectRoomMessageSource {
+  return value === "user" || value === "agent" || value === "task" || value === "routine" || value === "system";
+}
+function mapRow(row: MessageRow): ProjectRoomMessage {
+  const author = mapAuthor(row.author);
+  const content = isRecord(row.content) && row.content.type === "text" && typeof row.content.text === "string"
+    && hasOnlyKeys(row.content, ["type", "text"]) ? { type: "text" as const, text: row.content.text } : undefined;
+  const mentions = Array.isArray(row.mentions) ? row.mentions.map(mapMention) : undefined;
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string" || typeof row.workspace_id !== "string"
+    || typeof row.project_id !== "string" || typeof row.room_id !== "string" || !author || !content || !mentions
+    || mentions.some((mention) => mention === undefined)
+    || (row.reply_to_message_id !== null && typeof row.reply_to_message_id !== "string") || !isSource(row.source)
+    || (row.source_id !== null && typeof row.source_id !== "string")
+    || (row.idempotency_key !== null && typeof row.idempotency_key !== "string")
+    || !(row.created_at instanceof Date) || Number.isNaN(row.created_at.getTime())) {
+    throw new Error("Invalid project room message row");
+  }
+  return {
+    id: row.id, tenantId: row.tenant_id, workspaceId: row.workspace_id, projectId: row.project_id,
+    roomId: row.room_id, author, content, mentions: mentions as ProjectRoomMention[],
+    ...(row.reply_to_message_id === null ? {} : { replyToMessageId: row.reply_to_message_id }),
+    source: row.source, ...(row.source_id === null ? {} : { sourceId: row.source_id }),
+    ...(row.idempotency_key === null ? {} : { idempotencyKey: row.idempotency_key }), createdAt: row.created_at,
+  };
+}
+function isUniqueViolation(error: unknown): error is PostgreSQLError {
+  return typeof error === "object" && error !== null && "code" in error
+    && (error as PostgreSQLError).code === "23505";
+}
+
+/** Persists tenant-isolated project room messages in PostgreSQL. */
+export class PostgreSQLProjectRoomMessageStore implements ProjectRoomMessageStore {
+  /** Creates a store using an externally managed shared pool. */
+  constructor(options: { pool: Pool }) { this.pool = options.pool; }
+  private readonly pool: Pool;
+
+  /** Creates a room message and maps known uniqueness failures to typed errors. */
+  async create(input: Omit<ProjectRoomMessage, "createdAt">): Promise<ProjectRoomMessage> {
+    try {
+      const result = await this.pool.query<MessageRow>(
+        `INSERT INTO lattice_project_room_messages
+         (id, tenant_id, workspace_id, project_id, room_id, author, content, mentions, reply_to_message_id, source, source_id, idempotency_key, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, date_trunc('milliseconds', clock_timestamp()))
+         RETURNING ${columns}`,
+        this.parameters(input),
+      );
+      return mapRow(result.rows[0]);
+    } catch (error) {
+      if (isUniqueViolation(error) && error.constraint === "lattice_project_room_messages_pkey") {
+        throw new ProjectRoomMessageIdConflictError(input.tenantId, input.id);
+      }
+      if (isUniqueViolation(error) && error.constraint === "uq_lattice_project_room_messages_idempotency") {
+        throw new DuplicateProjectRoomMessageIdempotencyKeyError(input.tenantId, input.roomId, input.idempotencyKey ?? "");
+      }
+      throw error;
+    }
+  }
+
+  /** Atomically creates or returns the canonical message for a room-scoped idempotency key. */
+  async createIdempotent(
+    input: Omit<ProjectRoomMessage, "createdAt"> & { idempotencyKey: string },
+  ): Promise<ProjectRoomMessage> {
+    try {
+      const result = await this.pool.query<MessageRow>(
+        `INSERT INTO lattice_project_room_messages
+         (id, tenant_id, workspace_id, project_id, room_id, author, content, mentions, reply_to_message_id, source, source_id, idempotency_key, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, date_trunc('milliseconds', clock_timestamp()))
+         ON CONFLICT (tenant_id, room_id, idempotency_key) WHERE idempotency_key IS NOT NULL
+         DO UPDATE SET idempotency_key = lattice_project_room_messages.idempotency_key
+         RETURNING ${columns}`,
+        this.parameters(input),
+      );
+      return mapRow(result.rows[0]);
+    } catch (error) {
+      if (isUniqueViolation(error) && error.constraint === "lattice_project_room_messages_pkey") {
+        throw new ProjectRoomMessageIdConflictError(input.tenantId, input.id);
+      }
+      throw error;
+    }
+  }
+
+  /** Lists messages newest first using an exclusive stable cursor and a clamped limit. */
+  async list(input: {
+    tenantId: string; roomId: string; before?: { createdAt: Date; id: string }; limit: number;
+  }): Promise<ProjectRoomMessage[]> {
+    if (input.before && (!(input.before.createdAt instanceof Date) || Number.isNaN(input.before.createdAt.getTime()))) {
+      throw new RangeError("Project room message cursor date is invalid");
+    }
+    const limit = Math.min(100, Math.max(1, Math.trunc(Number.isFinite(input.limit) ? input.limit : 1)));
+    const result = input.before
+      ? await this.pool.query<MessageRow>(
+        `SELECT ${columns} FROM lattice_project_room_messages
+         WHERE tenant_id = $1 AND room_id = $2 AND (created_at < $3 OR (created_at = $3 AND id < $4))
+         ORDER BY created_at DESC, id DESC LIMIT $5`,
+        [input.tenantId, input.roomId, input.before.createdAt, input.before.id, limit],
+      )
+      : await this.pool.query<MessageRow>(
+        `SELECT ${columns} FROM lattice_project_room_messages
+         WHERE tenant_id = $1 AND room_id = $2 ORDER BY created_at DESC, id DESC LIMIT $3`,
+        [input.tenantId, input.roomId, limit],
+      );
+    return result.rows.map(mapRow);
+  }
+
+  /** Finds a message by tenant-scoped ID. */
+  async findById(tenantId: string, id: string): Promise<ProjectRoomMessage | null> {
+    const result = await this.pool.query<MessageRow>(
+      `SELECT ${columns} FROM lattice_project_room_messages WHERE tenant_id = $1 AND id = $2`, [tenantId, id],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  private parameters(input: Omit<ProjectRoomMessage, "createdAt">): unknown[] {
+    return [input.id, input.tenantId, input.workspaceId, input.projectId, input.roomId, JSON.stringify(input.author), JSON.stringify(input.content),
+      JSON.stringify(input.mentions), input.replyToMessageId ?? null, input.source, input.sourceId ?? null, input.idempotencyKey ?? null];
+  }
+}