@axiom-lattice/pg-stores 3.1.0 → 3.1.2

package/src/stores/PostgreSQLProjectRoomStore.ts

@@ -0,0 +1,57 @@
+import type { ProjectRoom, ProjectRoomStore } from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+type ProjectRoomRow = {
+  id: unknown; tenant_id: unknown; workspace_id: unknown; project_id: unknown;
+  type: unknown; name: unknown; created_at: unknown; updated_at: unknown;
+};
+
+function isValidDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+
+function mapRow(row: ProjectRoomRow): ProjectRoom {
+  if (typeof row.id !== "string" || typeof row.tenant_id !== "string"
+    || typeof row.workspace_id !== "string" || typeof row.project_id !== "string"
+    || row.type !== "main" || typeof row.name !== "string"
+    || !isValidDate(row.created_at) || !isValidDate(row.updated_at)) {
+    throw new Error("Invalid project room row");
+  }
+  return {
+    id: row.id, tenantId: row.tenant_id, workspaceId: row.workspace_id,
+    projectId: row.project_id, type: "main", name: row.name,
+    createdAt: row.created_at, updatedAt: row.updated_at,
+  };
+}
+
+/** Persists tenant-isolated canonical project main rooms in PostgreSQL. */
+export class PostgreSQLProjectRoomStore implements ProjectRoomStore {
+  /** 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;
+
+  /** Creates or returns the single persisted main room for a project. */
+  async ensureMainRoom(input: {
+    id: string; tenantId: string; workspaceId: string; projectId: string; name: string;
+  }): Promise<ProjectRoom> {
+    const result = await this.pool.query<ProjectRoomRow>(
+      `INSERT INTO lattice_project_rooms
+       (id, tenant_id, workspace_id, project_id, type, name)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (tenant_id, project_id, type)
+       DO UPDATE SET updated_at = lattice_project_rooms.updated_at
+       RETURNING id, tenant_id, workspace_id, project_id, type, name, created_at, updated_at`,
+      [input.id, input.tenantId, input.workspaceId, input.projectId, "main", input.name],
+    );
+    return mapRow(result.rows[0]);
+  }
+
+  /** Finds a tenant-scoped project's main room, or returns null. */
+  async getMainRoom(tenantId: string, projectId: string): Promise<ProjectRoom | null> {
+    const result = await this.pool.query<ProjectRoomRow>(
+      "SELECT id, tenant_id, workspace_id, project_id, type, name, created_at, updated_at FROM lattice_project_rooms WHERE tenant_id = $1 AND project_id = $2 AND type = 'main'",
+      [tenantId, projectId],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+}

package/src/stores/PostgreSQLProjectStore.ts

@@ -5,11 +5,13 @@
 import { Pool } from "pg";
 import type { PoolConfig } from "pg";
 import {
+  assertGenericProjectConfig,
   ProjectStore,
   Project,
   ProjectFilter,
   CreateProjectRequest,
   UpdateProjectRequest,
+  UpdateProjectCapabilityBundlesResult,
 } from "@axiom-lattice/protocols";
 import { MigrationManager } from "../migrations/migration";
 import { createProjectsTable } from "../migrations/project_migrations";
@@ -218,37 +220,70 @@ export class PostgreSQLProjectStore implements ProjectStore {
     id: string,
     data: CreateProjectRequest
   ): Promise<Project> {
+    assertGenericProjectConfig(data.config);
     await this.ensureInitialized();
 
     const now = new Date();
     const kind = data.kind || "business";
 
-    await this.pool.query(
-      `
-      INSERT INTO lattice_projects (id, tenant_id, workspace_id, name, description, config, kind, created_at, updated_at)
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($1 || ':project-mutations', 0))",
+        [tenantId],
+      );
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($2 || ':project:' || $1, 0))",
+        [id, tenantId],
+      );
+      const existing = await client.query<{ config: Record<string, unknown> | null }>(
+        "SELECT config FROM lattice_projects WHERE id = $1 AND tenant_id = $2 FOR UPDATE",
+        [id, tenantId],
+      );
+      const ids = existing.rows[0]?.config?.capabilityBundleIds;
+      const bundleIds = Array.isArray(ids) && ids.every((bundleId) => typeof bundleId === "string")
+        ? [...ids].sort()
+        : [];
+      if (bundleIds.length > 0) {
+        await client.query(
+          `SELECT pg_advisory_xact_lock(hashtextextended($1 || ':' || bundle_id, 0))
+           FROM unnest($2::text[]) AS bundle_id
+           ORDER BY bundle_id`,
+          [tenantId, bundleIds],
+        );
+      }
+      const result = await client.query<{
+      id: string; tenant_id: string; workspace_id: string; name: string;
+      description: string | null; config: unknown | null; kind: string | null;
+      created_at: Date; updated_at: Date;
+      }>(
+      `INSERT INTO lattice_projects (id, tenant_id, workspace_id, name, description, config, kind, created_at, updated_at)
       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
       ON CONFLICT (id, tenant_id) DO UPDATE SET
         workspace_id = EXCLUDED.workspace_id,
         name = EXCLUDED.name,
         description = EXCLUDED.description,
-        config = EXCLUDED.config,
+        config = CASE
+          WHEN lattice_projects.config ? 'capabilityBundleIds'
+          THEN COALESCE(EXCLUDED.config, '{}'::jsonb)
+            || jsonb_build_object('capabilityBundleIds', lattice_projects.config->'capabilityBundleIds')
+          ELSE EXCLUDED.config
+        END,
         kind = EXCLUDED.kind,
         updated_at = EXCLUDED.updated_at
+      RETURNING id, tenant_id, workspace_id, name, description, config, kind, created_at, updated_at
     `,
       [id, tenantId, workspaceId, data.name, data.description || null, data.config || null, kind, now, now]
-    );
-
-    return {
-      id,
-      tenantId,
-      workspaceId,
-      name: data.name,
-      description: data.description,
-      config: data.config,
-      kind,
-      createdAt: now,
-      updatedAt: now,
-    };
+      );
+      await client.query("COMMIT");
+      return this.mapRowToProject(result.rows[0]);
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
   }
 
   /**
@@ -263,17 +298,12 @@ export class PostgreSQLProjectStore implements ProjectStore {
     id: string,
     updates: UpdateProjectRequest
   ): Promise<Project | null> {
+    assertGenericProjectConfig(updates.config);
     await this.ensureInitialized();
 
-    // Get existing project
-    const existing = await this.getProjectById(tenantId, id);
-    if (!existing) {
-      return null;
-    }
-
     // Build update query dynamically based on provided fields
     const updateFields: string[] = [];
-    const updateValues: any[] = [];
+    const updateValues: unknown[] = [];
     let paramIndex = 1;
 
     if (updates.name !== undefined) {
@@ -287,8 +317,14 @@ export class PostgreSQLProjectStore implements ProjectStore {
     }
 
     if (updates.config !== undefined) {
-      updateFields.push(`config = $${paramIndex++}`);
-      updateValues.push(updates.config || null);
+      const configParam = `$${paramIndex++}`;
+      updateFields.push(`config = CASE
+        WHEN config ? 'capabilityBundleIds'
+        THEN COALESCE(${configParam}::jsonb, '{}'::jsonb)
+          || jsonb_build_object('capabilityBundleIds', config->'capabilityBundleIds')
+        ELSE ${configParam}::jsonb
+      END`);
+      updateValues.push(updates.config);
     }
 
     if (updates.kind !== undefined) {
@@ -298,28 +334,63 @@ export class PostgreSQLProjectStore implements ProjectStore {
 
     if (updateFields.length === 0) {
       // No fields to update
-      return existing;
+      return await this.getProjectById(tenantId, id);
     }
 
     // Always update updated_at
     updateFields.push(`updated_at = $${paramIndex++}`);
     updateValues.push(new Date());
 
-    // Add id and tenant_id for WHERE clause
-    updateValues.push(id);
-    updateValues.push(tenantId);
-
-    await this.pool.query(
-      `
-      UPDATE lattice_projects
-      SET ${updateFields.join(", ")}
-      WHERE id = $${paramIndex} AND tenant_id = $${paramIndex + 1}
-    `,
-      updateValues
-    );
-
-    // Return updated project
-    return await this.getProjectById(tenantId, id);
+    updateValues.push(id, tenantId);
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($1 || ':project-mutations', 0))",
+        [tenantId],
+      );
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($2 || ':project:' || $1, 0))",
+        [id, tenantId],
+      );
+      const existing = await client.query<{ config: Record<string, unknown> | null }>(
+        "SELECT config FROM lattice_projects WHERE id = $1 AND tenant_id = $2 FOR UPDATE",
+        [id, tenantId],
+      );
+      if (!existing.rows[0]) {
+        await client.query("COMMIT");
+        return null;
+      }
+      const ids = existing.rows[0].config?.capabilityBundleIds;
+      const bundleIds = Array.isArray(ids) && ids.every((bundleId) => typeof bundleId === "string")
+        ? [...ids].sort()
+        : [];
+      if (bundleIds.length > 0) {
+        await client.query(
+          `SELECT pg_advisory_xact_lock(hashtextextended($1 || ':' || bundle_id, 0))
+           FROM unnest($2::text[]) AS bundle_id
+           ORDER BY bundle_id`,
+          [tenantId, bundleIds],
+        );
+      }
+      const result = await client.query<{
+        id: string; tenant_id: string; workspace_id: string; name: string;
+        description: string | null; config: unknown | null; kind: string | null;
+        created_at: Date; updated_at: Date;
+      }>(
+        `UPDATE lattice_projects SET ${updateFields.join(", ")}
+         WHERE id = $${paramIndex} AND tenant_id = $${paramIndex + 1}
+         RETURNING id, tenant_id, workspace_id, name, description, config, kind, created_at, updated_at`,
+        updateValues,
+      );
+      await client.query("COMMIT");
+      return this.mapRowToProject(result.rows[0]);
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
   }
 
   /**
@@ -327,15 +398,124 @@ export class PostgreSQLProjectStore implements ProjectStore {
    */
   async deleteProject(tenantId: string, id: string): Promise<boolean> {
     await this.ensureInitialized();
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($1 || ':project-mutations', 0))",
+        [tenantId],
+      );
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($2 || ':project:' || $1, 0))",
+        [id, tenantId],
+      );
+      const selected = await client.query<{ config: Record<string, unknown> | null }>(
+        "SELECT config FROM lattice_projects WHERE id = $1 AND tenant_id = $2 FOR UPDATE",
+        [id, tenantId],
+      );
+      if (!selected.rows[0]) {
+        await client.query("COMMIT");
+        return false;
+      }
+      const ids = selected.rows[0].config?.capabilityBundleIds;
+      const bundleIds = Array.isArray(ids) && ids.every((bundleId) => typeof bundleId === "string")
+        ? [...ids].sort()
+        : [];
+      if (bundleIds.length > 0) {
+        await client.query(
+          `SELECT pg_advisory_xact_lock(hashtextextended($1 || ':' || bundle_id, 0))
+           FROM unnest($2::text[]) AS bundle_id
+           ORDER BY bundle_id`,
+          [tenantId, bundleIds],
+        );
+      }
+      const result = await client.query(
+        "DELETE FROM lattice_projects WHERE id = $1 AND tenant_id = $2",
+        [id, tenantId],
+      );
+      await client.query("COMMIT");
+      return result.rowCount !== null && result.rowCount > 0;
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
 
-    const result = await this.pool.query(
-      `
-      DELETE FROM lattice_projects
-      WHERE id = $1 AND tenant_id = $2
-    `,
-      [id, tenantId]
-    );
+  async updateCapabilityBundleIds(tenantId: string, projectId: string, bundleIds: string[], expectedRevisions: Record<string, string> = {}): Promise<UpdateProjectCapabilityBundlesResult> {
+    await this.ensureInitialized();
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($1 || ':project-mutations', 0))",
+        [tenantId],
+      );
+      await client.query(
+        "SELECT pg_advisory_xact_lock(hashtextextended($2 || ':project:' || $1, 0))",
+        [projectId, tenantId],
+      );
+      await client.query(
+        "SELECT id FROM lattice_projects WHERE id = $1 AND tenant_id = $2 FOR UPDATE",
+        [projectId, tenantId],
+      );
+      if (bundleIds.length > 0) {
+        await client.query(
+          `SELECT pg_advisory_xact_lock(hashtextextended($1 || ':' || bundle_id, 0))
+           FROM unnest($2::text[]) AS bundle_id
+           ORDER BY bundle_id`,
+          [tenantId, [...bundleIds].sort()],
+        );
+        if (Object.keys(expectedRevisions).length > 0) {
+          const revisions = await client.query<{ id: string; updated_at: string }>("SELECT id, updated_at::text AS updated_at FROM lattice_capability_bundles WHERE tenant_id = $1 AND id = ANY($2::uuid[]) FOR UPDATE", [tenantId, bundleIds]);
+          if (revisions.rows.some((bundle) => expectedRevisions[bundle.id] !== undefined && expectedRevisions[bundle.id] !== bundle.updated_at)) {
+            await client.query("ROLLBACK");
+            return { status: "bundle_conflict" };
+          }
+        }
+      }
+      const result = await client.query(
+        `UPDATE lattice_projects
+         SET config = COALESCE(config, '{}'::jsonb) || jsonb_build_object('capabilityBundleIds', $3::jsonb), updated_at = NOW()
+         WHERE id = $1 AND tenant_id = $2
+         AND NOT EXISTS (
+           SELECT 1 FROM unnest($4::uuid[]) AS bundle_id
+           WHERE NOT EXISTS (
+             SELECT 1 FROM lattice_capability_bundles
+             WHERE tenant_id = $2 AND id = bundle_id
+           )
+         )
+         RETURNING id, tenant_id, workspace_id, name, description, config, kind, created_at, updated_at`,
+        [projectId, tenantId, JSON.stringify(bundleIds), bundleIds],
+      );
+      if (result.rows[0]) {
+        await client.query("COMMIT");
+        return { status: "updated", project: this.mapRowToProject(result.rows[0]) };
+      }
+      const project = await client.query(
+        "SELECT id FROM lattice_projects WHERE id = $1 AND tenant_id = $2",
+        [projectId, tenantId],
+      );
+      await client.query("COMMIT");
+      return project.rows.length > 0 ? { status: "bundle_not_found" } : { status: "project_not_found" };
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
 
-    return result.rowCount !== null && result.rowCount > 0;
+  async isCapabilityBundleReferenced(tenantId: string, bundleId: string): Promise<boolean> {
+    await this.ensureInitialized();
+    const result = await this.pool.query<{ exists: number }>(
+      `SELECT 1 AS exists FROM lattice_projects
+       WHERE tenant_id = $1
+       AND jsonb_typeof(config->'capabilityBundleIds') = 'array'
+       AND COALESCE(config->'capabilityBundleIds', '[]'::jsonb) ? $2
+       LIMIT 1`, [tenantId, bundleId],
+    );
+    return result.rows.length > 0;
   }
 }

package/src/stores/PostgreSQLTaskStore.ts

@@ -11,11 +11,18 @@ import type {
   UpdateTaskRequest,
   TaskListFilter,
   TaskFileRef,
+  TaskDependentListQuery,
+  TaskMutationSnapshot,
 } from "@axiom-lattice/protocols";
 import { MigrationManager } from "../migrations/migration";
-import { createTasksTable, addTaskFieldsMigration, addTaskProjectFieldsMigration, addFilesToTasks } from "../migrations/task_migration";
+import { createTasksTable, addTaskFieldsMigration, addTaskProjectFieldsMigration, addFilesToTasks, addTaskDependenciesGinIndex } from "../migrations/task_migration";
 import { v4 as uuidv4 } from "uuid";
 
+const TASK_STATUSES: ReadonlySet<string> = new Set([
+  "pending", "in_progress", "review", "failed", "interrupted", "completed", "cancelled",
+]);
+
+
 interface TaskRow {
   id: string;
   tenant_id: string;
@@ -131,6 +138,11 @@ function mapRowToTask(row: TaskRow): TaskItem {
   };
 }
 
+function assertPage(limit: number, offset = 0): void {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100
+    || !Number.isSafeInteger(offset) || offset < 0) throw new RangeError("Invalid task page");
+}
+
 export interface PostgreSQLTaskStoreOptions {
   pool?: Pool;
   poolConfig?: string | PoolConfig;
@@ -166,6 +178,7 @@ export class PostgreSQLTaskStore implements TaskStore {
     this.migrationManager.register(addTaskFieldsMigration);
     this.migrationManager.register(addTaskProjectFieldsMigration);
     this.migrationManager.register(addFilesToTasks);
+    this.migrationManager.register(addTaskDependenciesGinIndex);
 
     if (options.autoMigrate !== false) {
       this.initialize().catch((error) => {
@@ -274,7 +287,9 @@ export class PostgreSQLTaskStore implements TaskStore {
       conditions.push(`workspace_id = $${paramIndex++}`);
       params.push(filter.workspaceId);
     }
-    if (filter.projectId) {
+    if (filter.projectId === null) {
+      conditions.push("(project_id IS NULL OR project_id = '' OR project_id = 'default')");
+    } else if (filter.projectId !== undefined) {
       conditions.push(`project_id = $${paramIndex++}`);
       params.push(filter.projectId);
     }
@@ -301,12 +316,30 @@ export class PostgreSQLTaskStore implements TaskStore {
     const offset = filter.offset || 0;
 
     const result = await this.pool.query<TaskRow>(
-      `SELECT * FROM lattice_tasks WHERE ${where} ORDER BY created_at DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
+      `SELECT * FROM lattice_tasks WHERE ${where} ORDER BY created_at DESC, id DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
       [...params, limit, offset],
     );
     return result.rows.map((r) => mapRowToTask(r));
   }
 
+  /** Lists exact project tasks containing a JSON string dependency. */
+  async listDependents(query: TaskDependentListQuery): Promise<TaskItem[]> {
+    assertPage(query.limit, query.offset);
+    if (query.statuses.length === 0 || query.statuses.some((status) => !TASK_STATUSES.has(status))) {
+      throw new RangeError("Invalid task statuses");
+    }
+    await this.ensureInitialized();
+    const result = await this.pool.query<TaskRow>(
+      `SELECT * FROM lattice_tasks
+       WHERE tenant_id=$1 AND workspace_id=$2 AND project_id=$3
+         AND dependencies @> $4::jsonb AND status = ANY($5::text[])
+       ORDER BY created_at DESC, id DESC LIMIT $6 OFFSET $7`,
+      [query.tenantId, query.workspaceId, query.projectId, JSON.stringify([query.dependencyTaskId]),
+        query.statuses, query.limit, query.offset],
+    );
+    return result.rows.map(mapRowToTask);
+  }
+
   async update(
     tenantId: string,
     id: string,
@@ -558,6 +591,45 @@ export class PostgreSQLTaskStore implements TaskStore {
     return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
   }
 
+  /** Atomically update only while status, timestamp, owner, and Project scope match. */
+  async updateIfSnapshot(
+    tenantId: string, id: string, updates: UpdateTaskRequest, snapshot: TaskMutationSnapshot,
+  ): Promise<TaskItem | null> {
+    await this.ensureInitialized();
+    const setClauses: string[] = [];
+    const params: unknown[] = [];
+    let index = 1;
+    const fields: Array<[keyof UpdateTaskRequest, string, boolean?]> = [
+      ["title", "title"], ["description", "description"], ["status", "status"], ["priority", "priority"],
+      ["dueDate", "due_date"], ["metadata", "metadata", true], ["files", "files", true],
+      ["parentId", "parent_id"], ["sourceId", "source_id"], ["context", "context", true],
+      ["ownerType", "owner_type"], ["ownerId", "owner_id"], ["requireReview", "require_review"],
+      ["dependencies", "dependencies", true], ["result", "result"], ["failureReason", "failure_reason"],
+      ["workspaceId", "workspace_id"], ["projectId", "project_id"],
+    ];
+    for (const [field, column, json] of fields) {
+      const value = updates[field];
+      if (value === undefined) continue;
+      setClauses.push(`${column} = $${index++}`);
+      params.push(json && value !== null ? JSON.stringify(value) : value);
+    }
+    if (setClauses.length === 0) return this.getById(tenantId, id);
+    setClauses.push(`updated_at = ${nextUpdatedAtSql()}`);
+    const predicates = [tenantId, id, snapshot.status, new Date(snapshot.updatedAt).toISOString(), snapshot.ownerType,
+      snapshot.ownerId, snapshot.workspaceId, snapshot.projectId];
+    const placeholders = predicates.map(() => `$${index++}`);
+    params.push(...predicates);
+    const result = await this.pool.query<TaskRow>(
+      `UPDATE lattice_tasks SET ${setClauses.join(", ")}
+       WHERE tenant_id = ${placeholders[0]} AND id = ${placeholders[1]} AND status = ${placeholders[2]}
+         AND ${canonicalTimestampSnapshotSql("updated_at", placeholders[3])}
+          AND owner_type = ${placeholders[4]} AND owner_id = ${placeholders[5]}
+          AND workspace_id IS NOT DISTINCT FROM ${placeholders[6]}
+          AND project_id IS NOT DISTINCT FROM ${placeholders[7]} RETURNING *`, params,
+    );
+    return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
+  }
+
   /** Atomically update a child only when both child and parent snapshots match. */
   async updateIfStatusUpdatedAtAndParentUpdatedAt(
     tenantId: string,
@@ -631,6 +703,20 @@ export class PostgreSQLTaskStore implements TaskStore {
     return (result.rowCount ?? 0) > 0;
   }
 
+  /** Atomically delete only while status, timestamp, owner, and Project scope match. */
+  async deleteIfSnapshot(tenantId: string, id: string, snapshot: TaskMutationSnapshot): Promise<boolean> {
+    await this.ensureInitialized();
+    const result = await this.pool.query(
+      `DELETE FROM lattice_tasks WHERE tenant_id = $1 AND id = $2 AND status = $3
+       AND ${canonicalTimestampSnapshotSql("updated_at", "$4")}
+        AND owner_type = $5 AND owner_id = $6
+        AND workspace_id IS NOT DISTINCT FROM $7 AND project_id IS NOT DISTINCT FROM $8`,
+      [tenantId, id, snapshot.status, new Date(snapshot.updatedAt).toISOString(), snapshot.ownerType,
+        snapshot.ownerId, snapshot.workspaceId, snapshot.projectId],
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+
   async dispose(): Promise<void> {
     if (this.ownsPool && this.pool) {
       await this.pool.end();