@axiom-lattice/local-stores 2.0.10 → 3.0.0

package/src/stores/LocalTaskStore.ts

@@ -14,6 +14,13 @@ import type {
 import { ensureTable, nowISO, parseISO } from "../database";
 import { randomUUID } from "crypto";
 
+const MAX_CANONICAL_TASK_TIME = "9999-12-31T23:59:59.999Z";
+const NEXT_UPDATED_AT_SQL = `updated_at = CASE
+  WHEN strftime('%Y-%m-%dT%H:%M:%fZ', updated_at) = updated_at AND updated_at >= ?
+    THEN strftime('%Y-%m-%dT%H:%M:%fZ', updated_at, '+0.001 seconds')
+  ELSE ?
+END`;
+
 const DDL = `
 CREATE TABLE IF NOT EXISTS lt_tasks (
   id TEXT NOT NULL,
@@ -105,6 +112,11 @@ function mapRowToTask(row: TaskRow): TaskItem {
   };
 }
 
+function nextISO(previous: Date | string): string {
+  const previousMs = new Date(previous).getTime();
+  return new Date(Math.max(Date.now(), previousMs + 1)).toISOString();
+}
+
 export class LocalTaskStore implements TaskStore {
   private db: DatabaseWrapper;
 
@@ -134,7 +146,7 @@ export class LocalTaskStore implements TaskStore {
   async create(
     params: CreateTaskRequest & { tenantId: string; ownerType: string; ownerId: string },
   ): Promise<TaskItem> {
-    const id = randomUUID();
+    const id = params.id ?? randomUUID();
     const now = nowISO();
 
     this.db.prepare(
@@ -219,8 +231,8 @@ export class LocalTaskStore implements TaskStore {
     if (!existing) return null;
 
     const now = nowISO();
-    const setClauses: string[] = ['updated_at = ?'];
-    const values: unknown[] = [now];
+    const setClauses: string[] = [NEXT_UPDATED_AT_SQL];
+    const values: unknown[] = [now, now];
 
     if (updates.title !== undefined) { setClauses.push('title = ?'); values.push(updates.title); }
     if (updates.description !== undefined) { setClauses.push('description = ?'); values.push(updates.description); }
@@ -230,7 +242,9 @@ export class LocalTaskStore implements TaskStore {
     if (updates.metadata !== undefined) { setClauses.push('metadata = ?'); values.push(JSON.stringify(updates.metadata)); }
     if (updates.parentId !== undefined) { setClauses.push('parent_id = ?'); values.push(updates.parentId); }
     if (updates.sourceId !== undefined) { setClauses.push('source_id = ?'); values.push(updates.sourceId); }
-    if (updates.context !== undefined) { setClauses.push('context = ?'); values.push(JSON.stringify(updates.context)); }
+    if (updates.context !== undefined) {
+      setClauses.push('context = ?'); values.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
     if (updates.ownerType !== undefined) { setClauses.push('owner_type = ?'); values.push(updates.ownerType); }
     if (updates.ownerId !== undefined) { setClauses.push('owner_id = ?'); values.push(updates.ownerId); }
     if (updates.requireReview !== undefined) { setClauses.push('require_review = ?'); values.push(updates.requireReview ? 1 : 0); }
@@ -243,11 +257,198 @@ export class LocalTaskStore implements TaskStore {
 
     if (setClauses.length === 1) return existing;
 
-    values.push(tenantId, id);
-    this.db.prepare(
-      `UPDATE lt_tasks SET ${setClauses.join(', ')} WHERE tenant_id = ? AND id = ?`,
+    values.push(tenantId, id, MAX_CANONICAL_TASK_TIME);
+    const result = this.db.prepare(
+      `UPDATE lt_tasks SET ${setClauses.join(', ')} WHERE tenant_id = ? AND id = ? AND updated_at <> ?`,
+    ).run(...values);
+    if (result.changes === 0) return null;
+
+    return this.getById(tenantId, id);
+  }
+
+  /**
+   * 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> {
+    const now = nowISO();
+    const setClauses: string[] = [NEXT_UPDATED_AT_SQL];
+    const values: unknown[] = [now, now];
+
+    if (updates.title !== undefined) { setClauses.push('title = ?'); values.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push('description = ?'); values.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push('status = ?'); values.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push('priority = ?'); values.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push('due_date = ?'); values.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push('metadata = ?'); values.push(JSON.stringify(updates.metadata)); }
+    if (updates.parentId !== undefined) { setClauses.push('parent_id = ?'); values.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push('source_id = ?'); values.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push('context = ?'); values.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push('owner_type = ?'); values.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push('owner_id = ?'); values.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push('require_review = ?'); values.push(updates.requireReview ? 1 : 0); }
+    if (updates.dependencies !== undefined) { setClauses.push('dependencies = ?'); values.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push('result = ?'); values.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push('failure_reason = ?'); values.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push('workspace_id = ?'); values.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push('project_id = ?'); values.push(updates.projectId); }
+    if (updates.files !== undefined) { setClauses.push('files = ?'); values.push(JSON.stringify(updates.files)); }
+
+    const statusClause = blockedStatuses.length > 0
+      ? ` AND status NOT IN (${blockedStatuses.map(() => "?").join(", ")})`
+      : "";
+    values.push(tenantId, id, MAX_CANONICAL_TASK_TIME, ...blockedStatuses);
+    const result = this.db.prepare(
+      `UPDATE lt_tasks SET ${setClauses.join(', ')} WHERE tenant_id = ? AND id = ? AND updated_at <> ?${statusClause}`,
+    ).run(...values);
+    if (result.changes === 0) return null;
+    return this.getById(tenantId, id);
+  }
+
+  /** 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> {
+    if (expectedStatuses.length === 0) return null;
+
+    const now = nowISO();
+    const setClauses: string[] = [NEXT_UPDATED_AT_SQL];
+    const values: unknown[] = [now, now];
+    if (updates.title !== undefined) { setClauses.push('title = ?'); values.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push('description = ?'); values.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push('status = ?'); values.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push('priority = ?'); values.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push('due_date = ?'); values.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push('metadata = ?'); values.push(JSON.stringify(updates.metadata)); }
+    if (updates.parentId !== undefined) { setClauses.push('parent_id = ?'); values.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push('source_id = ?'); values.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push('context = ?'); values.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push('owner_type = ?'); values.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push('owner_id = ?'); values.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push('require_review = ?'); values.push(updates.requireReview ? 1 : 0); }
+    if (updates.dependencies !== undefined) { setClauses.push('dependencies = ?'); values.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push('result = ?'); values.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push('failure_reason = ?'); values.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push('workspace_id = ?'); values.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push('project_id = ?'); values.push(updates.projectId); }
+    if (updates.files !== undefined) { setClauses.push('files = ?'); values.push(JSON.stringify(updates.files)); }
+
+    values.push(tenantId, id, MAX_CANONICAL_TASK_TIME, ...expectedStatuses);
+    const result = this.db.prepare(
+      `UPDATE lt_tasks SET ${setClauses.join(', ')} WHERE tenant_id = ? AND id = ? AND updated_at <> ? AND status IN (${expectedStatuses.map(() => "?").join(", ")})`,
     ).run(...values);
+    if (result.changes === 0) return 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> {
+    if (expectedStatuses.length === 0) return null;
+    const expectedIso = new Date(expectedUpdatedAt).toISOString();
+    if (expectedIso === MAX_CANONICAL_TASK_TIME) return null;
+    const setClauses: string[] = ["updated_at = ?"];
+    const values: unknown[] = [nextISO(expectedIso)];
+    if (updates.title !== undefined) { setClauses.push('title = ?'); values.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push('description = ?'); values.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push('status = ?'); values.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push('priority = ?'); values.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push('due_date = ?'); values.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push('metadata = ?'); values.push(JSON.stringify(updates.metadata)); }
+    if (updates.parentId !== undefined) { setClauses.push('parent_id = ?'); values.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push('source_id = ?'); values.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push('context = ?'); values.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push('owner_type = ?'); values.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push('owner_id = ?'); values.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push('require_review = ?'); values.push(updates.requireReview ? 1 : 0); }
+    if (updates.dependencies !== undefined) { setClauses.push('dependencies = ?'); values.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push('result = ?'); values.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push('failure_reason = ?'); values.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push('workspace_id = ?'); values.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push('project_id = ?'); values.push(updates.projectId); }
+    if (updates.files !== undefined) { setClauses.push('files = ?'); values.push(JSON.stringify(updates.files)); }
 
+    values.push(tenantId, id, ...expectedStatuses, expectedIso);
+    const result = this.db.prepare(
+      `UPDATE lt_tasks SET ${setClauses.join(', ')} WHERE tenant_id = ? AND id = ? AND status IN (${expectedStatuses.map(() => "?").join(", ")}) AND updated_at = ?`,
+    ).run(...values);
+    if (result.changes === 0) return null;
+    return this.getById(tenantId, id);
+  }
+
+  /** 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> {
+    if (expectedStatuses.length === 0) return null;
+    const expectedIso = new Date(expectedUpdatedAt).toISOString();
+    if (expectedIso === MAX_CANONICAL_TASK_TIME) return null;
+    const parentExpectedIso = new Date(expectedParentUpdatedAt).toISOString();
+    const setClauses: string[] = ["updated_at = ?"];
+    const values: unknown[] = [nextISO(expectedIso)];
+    if (updates.title !== undefined) { setClauses.push('title = ?'); values.push(updates.title); }
+    if (updates.description !== undefined) { setClauses.push('description = ?'); values.push(updates.description); }
+    if (updates.status !== undefined) { setClauses.push('status = ?'); values.push(updates.status); }
+    if (updates.priority !== undefined) { setClauses.push('priority = ?'); values.push(updates.priority); }
+    if (updates.dueDate !== undefined) { setClauses.push('due_date = ?'); values.push(updates.dueDate); }
+    if (updates.metadata !== undefined) { setClauses.push('metadata = ?'); values.push(JSON.stringify(updates.metadata)); }
+    if (updates.parentId !== undefined) { setClauses.push('parent_id = ?'); values.push(updates.parentId); }
+    if (updates.sourceId !== undefined) { setClauses.push('source_id = ?'); values.push(updates.sourceId); }
+    if (updates.context !== undefined) {
+      setClauses.push('context = ?'); values.push(updates.context === null ? null : JSON.stringify(updates.context));
+    }
+    if (updates.ownerType !== undefined) { setClauses.push('owner_type = ?'); values.push(updates.ownerType); }
+    if (updates.ownerId !== undefined) { setClauses.push('owner_id = ?'); values.push(updates.ownerId); }
+    if (updates.requireReview !== undefined) { setClauses.push('require_review = ?'); values.push(updates.requireReview ? 1 : 0); }
+    if (updates.dependencies !== undefined) { setClauses.push('dependencies = ?'); values.push(JSON.stringify(updates.dependencies)); }
+    if (updates.result !== undefined) { setClauses.push('result = ?'); values.push(updates.result); }
+    if (updates.failureReason !== undefined) { setClauses.push('failure_reason = ?'); values.push(updates.failureReason); }
+    if (updates.workspaceId !== undefined) { setClauses.push('workspace_id = ?'); values.push(updates.workspaceId); }
+    if (updates.projectId !== undefined) { setClauses.push('project_id = ?'); values.push(updates.projectId); }
+    if (updates.files !== undefined) { setClauses.push('files = ?'); values.push(JSON.stringify(updates.files)); }
+
+    values.push(tenantId, id, ...expectedStatuses, expectedIso, parentId, parentExpectedIso);
+    const result = this.db.prepare(
+      `UPDATE lt_tasks AS child SET ${setClauses.join(', ')}
+       WHERE tenant_id = ? AND id = ?
+         AND status IN (${expectedStatuses.map(() => "?").join(", ")})
+         AND updated_at = ?
+         AND EXISTS (
+           SELECT 1 FROM lt_tasks AS parent
+           WHERE parent.tenant_id = child.tenant_id AND parent.id = ? AND parent.updated_at = ?
+         )`,
+    ).run(...values);
+    if (result.changes === 0) return null;
     return this.getById(tenantId, id);
   }
 

package/src/stores/LocalTaskWorkItemStore.ts

@@ -7,6 +7,7 @@ import type {
   TaskWorkItemStore,
   TaskWorkItem,
   CreateWorkItemRequest,
+  CreateWorkItemIfAbsentRequest,
   TaskWorkItemListFilter,
 } from "@axiom-lattice/protocols";
 import { ensureTable, nowISO, parseISO } from "../database";
@@ -42,6 +43,7 @@ interface WorkItemRow {
   attempt: number | null;
   workspace_id: string | null;
   project_id: string | null;
+  event_key: string | null;
   created_at: string;
 }
 
@@ -58,6 +60,7 @@ function mapRowToWorkItem(row: WorkItemRow): TaskWorkItem {
     attempt: row.attempt ?? undefined,
     workspaceId: row.workspace_id ?? undefined,
     projectId: row.project_id ?? undefined,
+    eventKey: row.event_key ?? undefined,
     createdAt: parseISO(row.created_at),
   };
 }
@@ -68,8 +71,19 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
   constructor(db: DatabaseWrapper) {
     this.db = db;
     ensureTable(db, DDL);
-    this.db.exec(`ALTER TABLE lt_task_work_items ADD COLUMN workspace_id TEXT;`);
-    this.db.exec(`ALTER TABLE lt_task_work_items ADD COLUMN project_id TEXT;`);
+    this.ensureColumn("lt_task_work_items", "workspace_id", "workspace_id TEXT");
+    this.ensureColumn("lt_task_work_items", "project_id", "project_id TEXT");
+    this.ensureColumn("lt_task_work_items", "event_key", "event_key TEXT");
+    this.db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_task_work_items_event_key
+      ON lt_task_work_items (tenant_id, task_id, event_key);`);
+  }
+
+  /** Add a column if it does not exist (SQLite version compatible). */
+  private ensureColumn(table: string, column: string, ddl: string): void {
+    const cols = this.db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+    if (!cols.some((c) => c.name === column)) {
+      this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+    }
   }
 
   async create(params: CreateWorkItemRequest): Promise<TaskWorkItem> {
@@ -95,18 +109,48 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
     return mapRowToWorkItem(row!);
   }
 
+  /** Find an event by its tenant- and task-scoped key without pagination. */
+  async findByEventKey(tenantId: string, taskId: string, eventKey: string): Promise<TaskWorkItem | null> {
+    const row = this.db.prepare(
+      `SELECT * FROM lt_task_work_items WHERE tenant_id = ? AND task_id = ? AND event_key = ?`,
+    ).get(tenantId, taskId, eventKey) as unknown as WorkItemRow | undefined;
+    return row ? mapRowToWorkItem(row) : null;
+  }
+
+  /** Atomically return an existing event or create it once. */
+  async createIfAbsentByEventKey(params: CreateWorkItemIfAbsentRequest): Promise<TaskWorkItem> {
+    const id = uuid();
+    this.db.prepare(
+      `INSERT INTO lt_task_work_items (id, tenant_id, task_id, action, actor, thread_id, summary, detail, attempt, workspace_id, project_id, event_key, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (tenant_id, task_id, event_key) DO NOTHING`,
+    ).run(
+      id, 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, nowISO(),
+    );
+    const item = await this.findByEventKey(params.tenantId, params.taskId, params.eventKey);
+    if (!item) throw new Error("Task work item insert did not return a row");
+    return item;
+  }
+
   async list(filter: TaskWorkItemListFilter): Promise<TaskWorkItem[]> {
     const conditions: string[] = ['tenant_id = ?', 'task_id = ?'];
     const params: unknown[] = [filter.tenantId, filter.taskId];
 
     if (filter.action) { conditions.push('action = ?'); params.push(filter.action); }
+    if (filter.workspaceId) { conditions.push('workspace_id = ?'); params.push(filter.workspaceId); }
+    if (filter.projectId) { conditions.push('project_id = ?'); params.push(filter.projectId); }
 
     const where = conditions.join(' AND ');
     const limit = filter.limit || 100;
     const offset = filter.offset || 0;
+    const order = filter.order === 'asc' ? 'ASC' : 'DESC';
 
     const rows = this.db.prepare(
-      `SELECT * FROM lt_task_work_items WHERE ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      `SELECT * FROM lt_task_work_items WHERE ${where} ORDER BY created_at ${order}, id ${order} LIMIT ? OFFSET ?`,
     ).all(...params, limit, offset) as unknown as WorkItemRow[];
     return rows.map(mapRowToWorkItem);
   }