@axiom-lattice/pg-stores 3.1.1 → 3.1.2

package/src/stores/ChannelBindingStore.ts

@@ -1,13 +1,16 @@
 import { Pool } from "pg";
 import type { PoolConfig } from "pg";
-import type {
-  Binding,
-  BindingRegistry,
-  CreateBindingInput,
+import {
+  DuplicateChannelBindingSubjectError,
+  type Binding, type BindingListParams, type BindingMutablePatch,
+  type BindingRegistry, type CreateBindingInput,
 } from "@axiom-lattice/protocols";
 import { MigrationManager } from "../migrations/migration";
 import { createChannelBindingsTable } from "../migrations/channel_bindings_migration";
 
+const BINDING_SUBJECT_CONSTRAINT =
+  "lattice_channel_bindings_channel_channel_installation_id_te_key";
+
 export interface ChannelBindingStoreOptions {
   pool?: Pool;
   poolConfig?: string | PoolConfig;
@@ -107,13 +110,33 @@ export class ChannelBindingStore implements BindingRegistry {
     return this.mapRowToBinding(result.rows[0]);
   }
 
-  async create(input: CreateBindingInput): Promise<Binding> {
+  async findById(tenantId: string, id: string): Promise<Binding | null> {
     await this.ensureInitialized();
     const result = await this.pool.query<BindingRow>(
+      "SELECT * FROM lattice_channel_bindings WHERE id = $1 AND tenant_id = $2",
+      [id, tenantId],
+    );
+    return result.rows[0] ? this.mapRowToBinding(result.rows[0]) : null;
+  }
+
+  async findBySubject(params: {
+    tenantId: string; channel: string; channelInstallationId: string; senderId: string;
+  }): Promise<Binding | null> {
+    await this.ensureInitialized();
+    const result = await this.pool.query<BindingRow>(`SELECT * FROM lattice_channel_bindings
+      WHERE tenant_id = $1 AND channel = $2 AND channel_installation_id = $3 AND sender_id = $4 LIMIT 1`,
+    [params.tenantId, params.channel, params.channelInstallationId, params.senderId]);
+    return result.rows[0] ? this.mapRowToBinding(result.rows[0]) : null;
+  }
+
+  async create(input: CreateBindingInput): Promise<Binding> {
+    await this.ensureInitialized();
+    try {
+      const result = await this.pool.query<BindingRow>(
       `INSERT INTO lattice_channel_bindings
          (channel, channel_installation_id, tenant_id, sender_id, agent_id,
-          thread_mode, sender_display_name, sender_metadata, workspace_id, project_id)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            thread_id, thread_mode, sender_display_name, sender_metadata, workspace_id, project_id, enabled)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
        RETURNING *`,
       [
         input.channel,
@@ -121,75 +144,58 @@ export class ChannelBindingStore implements BindingRegistry {
         input.tenantId,
         input.senderId,
         input.agentId,
+        input.threadId || null,
         input.threadMode || "fixed",
         input.senderDisplayName || null,
         input.senderMetadata ? JSON.stringify(input.senderMetadata) : null,
-        input.workspaceId || null,
-        input.projectId || null,
+         input.workspaceId || null,
+         input.projectId || null,
+         input.enabled ?? true,
       ],
-    );
-    return this.mapRowToBinding(result.rows[0]);
+      );
+      return this.mapRowToBinding(result.rows[0]);
+    } catch (error) {
+      if (isBindingSubjectConflict(error)) {
+        throw new DuplicateChannelBindingSubjectError();
+      }
+      throw error;
+    }
   }
 
-  async update(id: string, patch: Partial<Binding>): Promise<Binding> {
+  async update(tenantId: string, id: string, patch: BindingMutablePatch): Promise<Binding> {
     await this.ensureInitialized();
-    const existing = await this.pool.query<BindingRow>(
-      `SELECT * FROM lattice_channel_bindings WHERE id = $1`,
-      [id],
-    );
-    if (existing.rows.length === 0) {
-      throw new Error(`Binding ${id} not found`);
-    }
-
-    const row = existing.rows[0];
-    const updated = {
-      channel: patch.channel ?? row.channel,
-      channel_installation_id: patch.channelInstallationId ?? row.channel_installation_id,
-      sender_id: patch.senderId ?? row.sender_id,
-      agent_id: patch.agentId ?? row.agent_id,
-      thread_id: patch.threadId !== undefined ? patch.threadId : row.thread_id,
-      workspace_id: patch.workspaceId !== undefined ? patch.workspaceId : row.workspace_id,
-      project_id: patch.projectId !== undefined ? patch.projectId : row.project_id,
-      thread_mode: patch.threadMode ?? row.thread_mode,
-      sender_display_name: patch.senderDisplayName !== undefined
-        ? patch.senderDisplayName : row.sender_display_name,
-      sender_metadata: patch.senderMetadata !== undefined
-        ? patch.senderMetadata : row.sender_metadata,
-      enabled: patch.enabled ?? row.enabled,
-    };
-
     const result = await this.pool.query<BindingRow>(
       `UPDATE lattice_channel_bindings SET
-         channel = $1, channel_installation_id = $2, sender_id = $3,
-         agent_id = $4, thread_id = $5, workspace_id = $6, project_id = $7,
-         thread_mode = $8, sender_display_name = $9, sender_metadata = $10,
-         enabled = $11, updated_at = NOW()
-       WHERE id = $12
+         agent_id = COALESCE($1, agent_id),
+         thread_id = COALESCE($2, thread_id),
+         workspace_id = COALESCE($3, workspace_id),
+         project_id = COALESCE($4, project_id),
+         thread_mode = COALESCE($5, thread_mode),
+         sender_display_name = COALESCE($6, sender_display_name),
+         sender_metadata = COALESCE($7, sender_metadata),
+         enabled = COALESCE($8, enabled), updated_at = NOW()
+       WHERE id = $9 AND tenant_id = $10
        RETURNING *`,
       [
-        updated.channel, updated.channel_installation_id, updated.sender_id,
-        updated.agent_id, updated.thread_id, updated.workspace_id,
-        updated.project_id, updated.thread_mode, updated.sender_display_name,
-        updated.sender_metadata ? JSON.stringify(updated.sender_metadata) : null,
-        updated.enabled, id,
+        patch.agentId ?? null, patch.threadId ?? null, patch.workspaceId ?? null,
+        patch.projectId ?? null, patch.threadMode ?? null, patch.senderDisplayName ?? null,
+        patch.senderMetadata ? JSON.stringify(patch.senderMetadata) : null,
+        patch.enabled ?? null, id, tenantId,
       ],
     );
+    if (!result.rows[0]) throw new Error(`Binding ${id} not found`);
     return this.mapRowToBinding(result.rows[0]);
   }
 
-  async delete(id: string): Promise<void> {
+  async delete(tenantId: string, id: string): Promise<void> {
     await this.ensureInitialized();
-    await this.pool.query(`DELETE FROM lattice_channel_bindings WHERE id = $1`, [id]);
+    await this.pool.query(
+      `DELETE FROM lattice_channel_bindings WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId],
+    );
   }
 
-  async list(params: {
-    channel?: string;
-    agentId?: string;
-    tenantId: string;
-    channelInstallationId?: string;
-    limit?: number;
-    offset?: number;
-  }): Promise<Binding[]> {
+  async list(params: BindingListParams): Promise<Binding[]> {
     await this.ensureInitialized();
     const conditions: string[] = ["tenant_id = $1"];
     const values: unknown[] = [params.tenantId];
@@ -207,6 +213,14 @@ export class ChannelBindingStore implements BindingRegistry {
       conditions.push(`channel_installation_id = $${idx++}`);
       values.push(params.channelInstallationId);
     }
+    if (params.excludeChannels?.length) {
+      conditions.push(`channel <> ALL($${idx++}::text[])`);
+      values.push(params.excludeChannels);
+    }
+    for (const prefix of params.excludeInstallationIdPrefixes ?? []) {
+      conditions.push(`channel_installation_id NOT LIKE $${idx++} ESCAPE '\\'`);
+      values.push(`${escapeLikePattern(prefix)}%`);
+    }
 
     const limit = params.limit ?? 50;
     const offset = params.offset ?? 0;
@@ -222,7 +236,16 @@ export class ChannelBindingStore implements BindingRegistry {
     return result.rows.map((r) => this.mapRowToBinding(r));
   }
 
-  async import(bindings: CreateBindingInput[]): Promise<Binding[]> {
+  async import(tenantId: string, bindings: CreateBindingInput[]): Promise<Binding[]> {
+    if (bindings.some((binding) => binding.channel === "room")) {
+      throw new Error("Room bindings cannot be imported through the public store API");
+    }
+    if (bindings.some((binding) => binding.channelInstallationId.startsWith("room-internal:"))) {
+      throw new Error("Internal bindings cannot be imported through the public store API");
+    }
+    if (bindings.some((binding) => binding.tenantId !== tenantId)) {
+      throw new Error("Binding import tenant mismatch");
+    }
     const result: Binding[] = [];
     for (const input of bindings) {
       result.push(await this.create(input));
@@ -231,7 +254,13 @@ export class ChannelBindingStore implements BindingRegistry {
   }
 
   async export(params: { tenantId: string }): Promise<Binding[]> {
-    return this.list({ tenantId: params.tenantId, limit: 10000, offset: 0 });
+    return this.list({
+      tenantId: params.tenantId,
+      excludeChannels: ["room"],
+      excludeInstallationIdPrefixes: ["room-internal:"],
+      limit: 10000,
+      offset: 0,
+    });
   }
 
   private async ensureInitialized(): Promise<void> {
@@ -260,3 +289,14 @@ export class ChannelBindingStore implements BindingRegistry {
     };
   }
 }
+
+function isBindingSubjectConflict(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const pgError = error as { code?: unknown; constraint?: unknown };
+  return pgError.code === "23505"
+    && pgError.constraint === BINDING_SUBJECT_CONSTRAINT;
+}
+
+function escapeLikePattern(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}

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