@axiom-lattice/pg-stores 2.0.9 → 3.0.0

package/src/stores/PostgreSQLTaskStore.ts

@@ -41,6 +41,58 @@ interface TaskRow {
   updated_at: string;
 }
 
+/**
+ * Advance the legacy VARCHAR task timestamp monotonically and store canonical UTC ISO text.
+ *
+ * The task table predates the timestamp-backed stores and persists `updated_at`
+ * as VARCHAR(50), so every arithmetic operand must be cast explicitly.
+ */
+function nextUpdatedAtSql(column = "updated_at"): string {
+  return `to_char(
+    date_trunc('milliseconds', GREATEST(
+      clock_timestamp(),
+      CASE
+        WHEN ${canonicalTimestampValidationSql(column)}
+          THEN ${column}::timestamptz + interval '1 millisecond'
+        ELSE clock_timestamp()
+      END
+    ))
+      AT TIME ZONE 'UTC',
+    'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'
+  )`;
+}
+
+function canonicalTimestampValidationSql(column: string, allowMaximum = false): string {
+  const year = `substring(${column} FROM 1 FOR 4)::integer`;
+  const month = `substring(${column} FROM 6 FOR 2)::integer`;
+  const day = `substring(${column} FROM 9 FOR 2)::integer`;
+  return `CASE
+    WHEN ${column} ~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$' THEN
+      ${allowMaximum ? "" : `${column} <> '9999-12-31T23:59:59.999Z' AND`}
+      ${year} BETWEEN 1 AND 9999
+      AND ${month} BETWEEN 1 AND 12
+      AND ${day} BETWEEN 1 AND CASE
+        WHEN ${month} = 2 THEN CASE
+          WHEN (${year} % 400 = 0) OR (${year} % 4 = 0 AND ${year} % 100 <> 0) THEN 29
+          ELSE 28
+        END
+        WHEN ${month} IN (4, 6, 9, 11) THEN 30
+        ELSE 31
+      END
+      AND substring(${column} FROM 12 FOR 2)::integer BETWEEN 0 AND 23
+      AND substring(${column} FROM 15 FOR 2)::integer BETWEEN 0 AND 59
+      AND substring(${column} FROM 18 FOR 2)::integer BETWEEN 0 AND 59
+    ELSE FALSE
+  END`;
+}
+
+function canonicalTimestampSnapshotSql(column: string, parameter: string, allowMaximum = false): string {
+  return `CASE WHEN ${canonicalTimestampValidationSql(column, allowMaximum)}
+    THEN ${column}::timestamptz = ${parameter}::timestamptz
+    ELSE FALSE
+  END`;
+}
+
 function parseTaskFiles(raw: unknown): TaskFileRef[] | undefined {
   if (!raw) return undefined;
   try {
@@ -148,7 +200,7 @@ export class PostgreSQLTaskStore implements TaskStore {
     params: CreateTaskRequest & { tenantId: string; ownerType: string; ownerId: string },
   ): Promise<TaskItem> {
     await this.ensureInitialized();
-    const id = uuidv4();
+    const id = params.id ?? uuidv4();
     const now = new Date().toISOString();
 
     await this.pool.query(
@@ -306,7 +358,7 @@ export class PostgreSQLTaskStore implements TaskStore {
     }
     if (updates.context !== undefined) {
       setClauses.push(`context = $${paramIndex++}`);
-      params.push(JSON.stringify(updates.context));
+      params.push(updates.context === null ? null : JSON.stringify(updates.context));
     }
     if (updates.ownerType !== undefined) {
       setClauses.push(`owner_type = $${paramIndex++}`);
@@ -345,16 +397,229 @@ export class PostgreSQLTaskStore implements TaskStore {
       return existing;
     }
 
-    setClauses.push(`updated_at = $${paramIndex++}`);
-    params.push(new Date().toISOString());
+    setClauses.push(`updated_at = ${nextUpdatedAtSql()}`);
 
     params.push(tenantId, id);
-    await this.pool.query(
-      `UPDATE lattice_tasks SET ${setClauses.join(", ")} WHERE tenant_id = $${paramIndex++} AND id = $${paramIndex++}`,
+    const result = await this.pool.query<TaskRow>(
+      `UPDATE lattice_tasks SET ${setClauses.join(", ")} WHERE tenant_id = $${paramIndex++} AND id = $${paramIndex++} AND updated_at <> '9999-12-31T23:59:59.999Z' RETURNING *`,
+      params,
+    );
+    return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
+  }
+
+  /**
+   * Atomically update a task unless its current status is blocked.
+   *
+   * @param tenantId Tenant identifier.
+   * @param id Task identifier.
+   * @param updates Partial task data to update.
+   * @param blockedStatuses Current statuses that prevent the update.
+   * @returns The updated task, or `null` when missing or blocked.
+   */
+  async updateIfStatusNotIn(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    blockedStatuses: TaskItem["status"][],
+  ): Promise<TaskItem | null> {
+    await this.ensureInitialized();
+    const setClauses: string[] = [];
+    const params: unknown[] = [];
+    let paramIndex = 1;
+
+    if (updates.title !== undefined) { setClauses.push(`title = $${paramIndex++}`); params.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push(`description = $${paramIndex++}`); params.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push(`status = $${paramIndex++}`); params.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push(`priority = $${paramIndex++}`); params.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push(`due_date = $${paramIndex++}`); params.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push(`metadata = $${paramIndex++}`); params.push(JSON.stringify(updates.metadata)); }
+    if (updates.files !== undefined) { setClauses.push(`files = $${paramIndex++}`); params.push(JSON.stringify(updates.files)); }
+    if (updates.parentId !== undefined) { setClauses.push(`parent_id = $${paramIndex++}`); params.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push(`source_id = $${paramIndex++}`); params.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push(`context = $${paramIndex++}`); params.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push(`owner_type = $${paramIndex++}`); params.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push(`owner_id = $${paramIndex++}`); params.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push(`require_review = $${paramIndex++}`); params.push(updates.requireReview); }
+    if (updates.dependencies !== undefined) { setClauses.push(`dependencies = $${paramIndex++}`); params.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push(`result = $${paramIndex++}`); params.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push(`failure_reason = $${paramIndex++}`); params.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push(`workspace_id = $${paramIndex++}`); params.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push(`project_id = $${paramIndex++}`); params.push(updates.projectId); }
+
+    setClauses.push(`updated_at = ${nextUpdatedAtSql()}`);
+    const tenantParam = paramIndex++;
+    const idParam = paramIndex++;
+    params.push(tenantId, id);
+    const blockedClause = blockedStatuses.length > 0
+      ? ` AND status <> ALL($${paramIndex}::text[])`
+      : "";
+    if (blockedStatuses.length > 0) params.push(blockedStatuses);
+
+    const result = await this.pool.query<TaskRow>(
+      `UPDATE lattice_tasks SET ${setClauses.join(", ")} WHERE tenant_id = $${tenantParam} AND id = $${idParam} AND updated_at <> '9999-12-31T23:59:59.999Z'${blockedClause} RETURNING *`,
+      params,
+    );
+    return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
+  }
+
+  /** Atomically update a task only when its current status is expected. */
+  async updateIfStatusIn(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    expectedStatuses: TaskItem["status"][],
+  ): Promise<TaskItem | null> {
+    await this.ensureInitialized();
+    if (expectedStatuses.length === 0) return null;
+
+    const setClauses: string[] = [];
+    const params: unknown[] = [];
+    let paramIndex = 1;
+    if (updates.title !== undefined) { setClauses.push(`title = $${paramIndex++}`); params.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push(`description = $${paramIndex++}`); params.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push(`status = $${paramIndex++}`); params.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push(`priority = $${paramIndex++}`); params.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push(`due_date = $${paramIndex++}`); params.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push(`metadata = $${paramIndex++}`); params.push(JSON.stringify(updates.metadata)); }
+    if (updates.files !== undefined) { setClauses.push(`files = $${paramIndex++}`); params.push(JSON.stringify(updates.files)); }
+    if (updates.parentId !== undefined) { setClauses.push(`parent_id = $${paramIndex++}`); params.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push(`source_id = $${paramIndex++}`); params.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push(`context = $${paramIndex++}`); params.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push(`owner_type = $${paramIndex++}`); params.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push(`owner_id = $${paramIndex++}`); params.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push(`require_review = $${paramIndex++}`); params.push(updates.requireReview); }
+    if (updates.dependencies !== undefined) { setClauses.push(`dependencies = $${paramIndex++}`); params.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push(`result = $${paramIndex++}`); params.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push(`failure_reason = $${paramIndex++}`); params.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push(`workspace_id = $${paramIndex++}`); params.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push(`project_id = $${paramIndex++}`); params.push(updates.projectId); }
+
+    setClauses.push(`updated_at = ${nextUpdatedAtSql()}`);
+    const tenantParam = paramIndex++;
+    const idParam = paramIndex++;
+    const statusesParam = paramIndex++;
+    params.push(tenantId, id, expectedStatuses);
+    const result = await this.pool.query<TaskRow>(
+      `UPDATE lattice_tasks SET ${setClauses.join(", ")} WHERE tenant_id = $${tenantParam} AND id = $${idParam} AND updated_at <> '9999-12-31T23:59:59.999Z' AND status = ANY($${statusesParam}::text[]) RETURNING *`,
       params,
     );
+    return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
+  }
 
-    return this.getById(tenantId, id);
+  /** Atomically update a task only when status and updatedAt match a read snapshot. */
+  async updateIfStatusAndUpdatedAt(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    expectedStatuses: TaskItem["status"][],
+    expectedUpdatedAt: Date | string,
+  ): Promise<TaskItem | null> {
+    await this.ensureInitialized();
+    if (expectedStatuses.length === 0) return null;
+    const expectedIso = new Date(expectedUpdatedAt).toISOString();
+    const setClauses: string[] = [];
+    const params: unknown[] = [];
+    let paramIndex = 1;
+    if (updates.title !== undefined) { setClauses.push(`title = $${paramIndex++}`); params.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push(`description = $${paramIndex++}`); params.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push(`status = $${paramIndex++}`); params.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push(`priority = $${paramIndex++}`); params.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push(`due_date = $${paramIndex++}`); params.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push(`metadata = $${paramIndex++}`); params.push(JSON.stringify(updates.metadata)); }
+    if (updates.files !== undefined) { setClauses.push(`files = $${paramIndex++}`); params.push(JSON.stringify(updates.files)); }
+    if (updates.parentId !== undefined) { setClauses.push(`parent_id = $${paramIndex++}`); params.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push(`source_id = $${paramIndex++}`); params.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push(`context = $${paramIndex++}`); params.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push(`owner_type = $${paramIndex++}`); params.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push(`owner_id = $${paramIndex++}`); params.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push(`require_review = $${paramIndex++}`); params.push(updates.requireReview); }
+    if (updates.dependencies !== undefined) { setClauses.push(`dependencies = $${paramIndex++}`); params.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push(`result = $${paramIndex++}`); params.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push(`failure_reason = $${paramIndex++}`); params.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push(`workspace_id = $${paramIndex++}`); params.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push(`project_id = $${paramIndex++}`); params.push(updates.projectId); }
+
+    setClauses.push(`updated_at = ${nextUpdatedAtSql()}`);
+    const tenantParam = paramIndex++;
+    const idParam = paramIndex++;
+    const statusesParam = paramIndex++;
+    const updatedAtParam = paramIndex++;
+    params.push(tenantId, id, expectedStatuses, expectedIso);
+    const result = await this.pool.query<TaskRow>(
+      `UPDATE lattice_tasks SET ${setClauses.join(", ")} WHERE tenant_id = $${tenantParam} AND id = $${idParam} AND status = ANY($${statusesParam}::text[]) AND ${canonicalTimestampSnapshotSql("updated_at", `$${updatedAtParam}`)} 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,
+    id: string,
+    updates: UpdateTaskRequest,
+    expectedStatuses: TaskItem["status"][],
+    expectedUpdatedAt: Date | string,
+    parentId: string,
+    expectedParentUpdatedAt: Date | string,
+  ): Promise<TaskItem | null> {
+    await this.ensureInitialized();
+    if (expectedStatuses.length === 0) return null;
+    const setClauses: string[] = [];
+    const params: unknown[] = [];
+    let paramIndex = 1;
+    if (updates.title !== undefined) { setClauses.push(`title = $${paramIndex++}`); params.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push(`description = $${paramIndex++}`); params.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push(`status = $${paramIndex++}`); params.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push(`priority = $${paramIndex++}`); params.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push(`due_date = $${paramIndex++}`); params.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push(`metadata = $${paramIndex++}`); params.push(JSON.stringify(updates.metadata)); }
+    if (updates.files !== undefined) { setClauses.push(`files = $${paramIndex++}`); params.push(JSON.stringify(updates.files)); }
+    if (updates.parentId !== undefined) { setClauses.push(`parent_id = $${paramIndex++}`); params.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push(`source_id = $${paramIndex++}`); params.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push(`context = $${paramIndex++}`); params.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push(`owner_type = $${paramIndex++}`); params.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push(`owner_id = $${paramIndex++}`); params.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push(`require_review = $${paramIndex++}`); params.push(updates.requireReview); }
+    if (updates.dependencies !== undefined) { setClauses.push(`dependencies = $${paramIndex++}`); params.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push(`result = $${paramIndex++}`); params.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push(`failure_reason = $${paramIndex++}`); params.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push(`workspace_id = $${paramIndex++}`); params.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push(`project_id = $${paramIndex++}`); params.push(updates.projectId); }
+
+    setClauses.push(`updated_at = ${nextUpdatedAtSql("child.updated_at")}`);
+    const tenantParam = paramIndex++;
+    const idParam = paramIndex++;
+    const statusesParam = paramIndex++;
+    const updatedAtParam = paramIndex++;
+    const parentIdParam = paramIndex++;
+    const parentUpdatedAtParam = paramIndex++;
+    params.push(
+      tenantId, id, expectedStatuses, new Date(expectedUpdatedAt).toISOString(),
+      parentId, new Date(expectedParentUpdatedAt).toISOString(),
+    );
+    const result = await this.pool.query<TaskRow>(
+      `UPDATE lattice_tasks AS child SET ${setClauses.join(", ")}
+       WHERE child.tenant_id = $${tenantParam} AND child.id = $${idParam}
+         AND child.status = ANY($${statusesParam}::text[])
+         AND ${canonicalTimestampSnapshotSql("child.updated_at", `$${updatedAtParam}`)}
+         AND EXISTS (
+           SELECT 1 FROM lattice_tasks AS parent
+           WHERE parent.tenant_id = child.tenant_id
+             AND parent.id = $${parentIdParam}
+             AND ${canonicalTimestampSnapshotSql("parent.updated_at", `$${parentUpdatedAtParam}`, true)}
+         )
+       RETURNING child.*`,
+      params,
+    );
+    return result.rows[0] ? mapRowToTask(result.rows[0]) : null;
   }
 
   async delete(tenantId: string, id: string): Promise<boolean> {

package/src/stores/PostgreSQLTaskWorkItemStore.ts

@@ -1,5 +1,5 @@
 import type { Pool } from "pg";
-import type { TaskWorkItemStore, TaskWorkItem, CreateWorkItemRequest, TaskWorkItemListFilter } from "@axiom-lattice/protocols";
+import type { TaskWorkItemStore, TaskWorkItem, CreateWorkItemRequest, CreateWorkItemIfAbsentRequest, TaskWorkItemListFilter } from "@axiom-lattice/protocols";
 import { v4 } from "uuid";
 
 export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
@@ -24,6 +24,36 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
     return this.rowToItem(result.rows[0]);
   }
 
+  /** Find an event by its tenant- and task-scoped key without pagination. */
+  async findByEventKey(tenantId: string, taskId: string, eventKey: string): Promise<TaskWorkItem | null> {
+    const result = await this.pool.query(
+      `SELECT * FROM lattice_task_work_items
+       WHERE tenant_id = $1 AND task_id = $2 AND event_key = $3`,
+      [tenantId, taskId, eventKey],
+    );
+    return result.rows[0] ? this.rowToItem(result.rows[0]) : null;
+  }
+
+  /** Atomically return an existing event or create it once. */
+  async createIfAbsentByEventKey(params: CreateWorkItemIfAbsentRequest): Promise<TaskWorkItem> {
+    const result = await this.pool.query(
+      `INSERT INTO lattice_task_work_items
+        (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id, event_key)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+       ON CONFLICT (tenant_id, task_id, event_key) WHERE event_key IS NOT NULL
+       DO UPDATE SET event_key = EXCLUDED.event_key
+       RETURNING *`,
+      [
+        v4(), params.tenantId, params.taskId, params.action, params.actor,
+        params.threadId || null, params.summary || null,
+        params.detail ? JSON.stringify(params.detail) : null,
+        params.attempt ?? null, params.workspaceId || null, params.projectId || null,
+        params.eventKey,
+      ],
+    );
+    return this.rowToItem(result.rows[0]);
+  }
+
   async list(filter: TaskWorkItemListFilter): Promise<TaskWorkItem[]> {
     let query = `SELECT * FROM lattice_task_work_items WHERE tenant_id = $1 AND task_id = $2`;
     const params: unknown[] = [filter.tenantId, filter.taskId];
@@ -32,8 +62,17 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
       query += ` AND action = $${params.length + 1}`;
       params.push(filter.action);
     }
+    if (filter.workspaceId) {
+      query += ` AND workspace_id = $${params.length + 1}`;
+      params.push(filter.workspaceId);
+    }
+    if (filter.projectId) {
+      query += ` AND project_id = $${params.length + 1}`;
+      params.push(filter.projectId);
+    }
 
-    query += ` ORDER BY created_at ASC`;
+    const order = filter.order === 'desc' ? 'DESC' : 'ASC';
+    query += ` ORDER BY created_at ${order}, id ${order}`;
 
     if (filter.limit) {
       query += ` LIMIT $${params.length + 1}`;
@@ -61,6 +100,7 @@ export class PostgreSQLTaskWorkItemStore implements TaskWorkItemStore {
       attempt: row.attempt as number | undefined,
       workspaceId: row.workspace_id as string | undefined,
       projectId: row.project_id as string | undefined,
+      eventKey: row.event_key == null ? undefined : row.event_key as string,
       createdAt: new Date(row.created_at as string),
     };
   }