@axiom-lattice/local-stores 3.1.0 → 3.1.2

package/src/stores/LocalProjectStore.ts

@@ -9,7 +9,9 @@ import type {
   ProjectFilter,
   CreateProjectRequest,
   UpdateProjectRequest,
+  UpdateProjectCapabilityBundlesResult,
 } from "@axiom-lattice/protocols";
+import { assertGenericProjectConfig } from "@axiom-lattice/protocols";
 import { ensureTable, nowISO, parseISO } from "../database";
 
 const DDL = `
@@ -75,6 +77,7 @@ export class LocalProjectStore implements ProjectStore {
     id: string,
     data: CreateProjectRequest,
   ): Promise<Project> {
+    assertGenericProjectConfig(data.config);
     const now = nowISO();
     const kind = data.kind || "business";
 
@@ -85,22 +88,16 @@ export class LocalProjectStore implements ProjectStore {
          workspace_id = excluded.workspace_id,
          name = excluded.name,
          description = excluded.description,
-         config = excluded.config,
+         config = CASE
+           WHEN json_type(lt_projects.config, '$.capabilityBundleIds') IS NOT NULL
+           THEN json_set(COALESCE(excluded.config, '{}'), '$.capabilityBundleIds', json_extract(lt_projects.config, '$.capabilityBundleIds'))
+           ELSE excluded.config
+         END,
          kind = excluded.kind,
          updated_at = excluded.updated_at`,
     ).run(id, tenantId, workspaceId, data.name, data.description || null, data.config ? JSON.stringify(data.config) : null, kind, now, now);
 
-    return {
-      id,
-      tenantId,
-      workspaceId,
-      name: data.name,
-      description: data.description,
-      config: data.config,
-      kind,
-      createdAt: parseISO(now),
-      updatedAt: parseISO(now),
-    };
+    return (await this.getProjectById(tenantId, id)) as Project;
   }
 
   async updateProject(
@@ -108,6 +105,7 @@ export class LocalProjectStore implements ProjectStore {
     id: string,
     updates: UpdateProjectRequest,
   ): Promise<Project | null> {
+    assertGenericProjectConfig(updates.config);
     const existing = await this.getProjectById(tenantId, id);
     if (!existing) return null;
 
@@ -123,8 +121,13 @@ export class LocalProjectStore implements ProjectStore {
       values.push(updates.description || null);
     }
     if (updates.config !== undefined) {
-      setClauses.push("config = ?");
-      values.push(updates.config ? JSON.stringify(updates.config) : null);
+      setClauses.push(`config = CASE
+        WHEN json_type(config, '$.capabilityBundleIds') IS NOT NULL
+        THEN json_set(json(?), '$.capabilityBundleIds', json_extract(config, '$.capabilityBundleIds'))
+        ELSE ?
+      END`);
+      const config = JSON.stringify(updates.config ?? {});
+      values.push(config, config);
     }
     if (updates.kind !== undefined) {
       setClauses.push("kind = ?");
@@ -152,6 +155,56 @@ export class LocalProjectStore implements ProjectStore {
     return result.changes > 0;
   }
 
+  async updateCapabilityBundleIds(tenantId: string, projectId: string, bundleIds: string[], expectedRevisions: Record<string, string> = {}): Promise<UpdateProjectCapabilityBundlesResult> {
+    const now = nowISO();
+    const result = this.db.prepare(
+      `UPDATE lt_projects
+       SET config = json_set(COALESCE(config, '{}'), '$.capabilityBundleIds', json(?)), updated_at = ?
+       WHERE tenant_id = ? AND id = ?
+        AND NOT EXISTS (
+          SELECT 1 FROM json_each(?) AS requested
+         WHERE NOT EXISTS (
+           SELECT 1 FROM lt_capability_bundles
+           WHERE tenant_id = ? AND id = requested.value
+          )
+        )
+        AND NOT EXISTS (
+          SELECT 1 FROM json_each(?) AS expected
+          WHERE EXISTS (
+            SELECT 1 FROM lt_capability_bundles
+            WHERE tenant_id = ? AND id = expected.key AND updated_at <> expected.value
+          )
+        )`,
+    ).run(JSON.stringify(bundleIds), now, tenantId, projectId, JSON.stringify(bundleIds), tenantId, JSON.stringify(expectedRevisions), tenantId);
+    if (result.changes > 0) {
+      const project = await this.getProjectById(tenantId, projectId);
+      return project ? { status: "updated", project } : { status: "project_not_found" };
+    }
+    const revisionMismatch = this.db.prepare(
+      "SELECT 1 FROM lt_capability_bundles WHERE tenant_id = ? AND id IN (SELECT key FROM json_each(?)) AND updated_at <> (SELECT value FROM json_each(?) WHERE key = lt_capability_bundles.id) LIMIT 1",
+    ).get(tenantId, JSON.stringify(expectedRevisions), JSON.stringify(expectedRevisions));
+    if (revisionMismatch) return { status: "bundle_conflict" };
+    return await this.getProjectById(tenantId, projectId)
+      ? { status: "bundle_not_found" }
+      : { status: "project_not_found" };
+  }
+
+  async isCapabilityBundleReferenced(tenantId: string, bundleId: string): Promise<boolean> {
+    const rows = this.db.prepare("SELECT config FROM lt_projects WHERE tenant_id = ?").all(tenantId) as unknown as Array<{ config: string | null }>;
+    return rows.some((row) => {
+      if (!row.config) return false;
+      let config: Record<string, unknown>;
+      try {
+        config = JSON.parse(row.config) as Record<string, unknown>;
+      } catch {
+        return false;
+      }
+      if (config === null || typeof config !== "object" || Array.isArray(config)) return false;
+      const ids = config.capabilityBundleIds;
+      return Array.isArray(ids) && ids.every((id) => typeof id === "string") && ids.includes(bundleId);
+    });
+  }
+
   /** 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 unknown as Array<{ name: string }>;

package/src/stores/LocalTaskStore.ts

@@ -10,11 +10,16 @@ import type {
   CreateTaskRequest,
   UpdateTaskRequest,
   TaskListFilter,
+  TaskDependentListQuery,
+  TaskMutationSnapshot,
 } from "@axiom-lattice/protocols";
 import { ensureTable, nowISO, parseISO } from "../database";
 import { randomUUID } from "crypto";
 
 const MAX_CANONICAL_TASK_TIME = "9999-12-31T23:59:59.999Z";
+const TASK_STATUSES: ReadonlySet<string> = new Set([
+  "pending", "in_progress", "review", "failed", "interrupted", "completed", "cancelled",
+]);
 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')
@@ -117,6 +122,11 @@ function nextISO(previous: Date | string): string {
   return new Date(Math.max(Date.now(), previousMs + 1)).toISOString();
 }
 
+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 class LocalTaskStore implements TaskStore {
   private db: DatabaseWrapper;
 
@@ -190,7 +200,8 @@ export class LocalTaskStore implements TaskStore {
     }
     if (filter.priority) { conditions.push('priority = ?'); params.push(filter.priority); }
     if (filter.workspaceId) { conditions.push('workspace_id = ?'); params.push(filter.workspaceId); }
-    if (filter.projectId) { conditions.push('project_id = ?'); params.push(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 = ?'); params.push(filter.projectId); }
     if (filter.parentId) { conditions.push('parent_id = ?'); params.push(filter.parentId); }
     if (filter.sourceId) { conditions.push('source_id = ?'); params.push(filter.sourceId); }
     if (filter.metadata) {
@@ -217,11 +228,39 @@ export class LocalTaskStore implements TaskStore {
     const offset = filter.offset || 0;
 
     const rows = this.db.prepare(
-      `SELECT * FROM lt_tasks WHERE ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+      `SELECT * FROM lt_tasks WHERE ${where} ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?`,
     ).all(...params, limit, offset) as unknown as TaskRow[];
     return rows.map(mapRowToTask);
   }
 
+  /** Lists exact project tasks containing a 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");
+    }
+    const rows = this.db.prepare(
+      `SELECT task.* FROM lt_tasks AS task
+       WHERE task.tenant_id = ? AND task.workspace_id = ? AND task.project_id = ?
+         AND task.status IN (${query.statuses.map(() => "?").join(", ")})
+         AND task.dependencies IS NOT NULL
+         AND json_valid(task.dependencies) = 1
+         AND json_type(CASE WHEN json_valid(task.dependencies)=1
+                            THEN task.dependencies ELSE '[]' END) = 'array'
+         AND EXISTS (
+           SELECT 1 FROM json_each(
+             CASE WHEN json_valid(task.dependencies)=1 THEN
+               CASE WHEN json_type(task.dependencies)='array' THEN task.dependencies ELSE '[]' END
+             ELSE '[]' END
+           ) AS dependency
+           WHERE dependency.type = 'text' AND dependency.value = ?
+         )
+       ORDER BY task.created_at DESC, task.id DESC LIMIT ? OFFSET ?`,
+    ).all(query.tenantId, query.workspaceId, query.projectId, ...query.statuses,
+      query.dependencyTaskId, query.limit, query.offset) as unknown as TaskRow[];
+    return rows.map(mapRowToTask);
+  }
+
   async update(
     tenantId: string,
     id: string,
@@ -400,6 +439,37 @@ export class LocalTaskStore implements TaskStore {
     return this.getById(tenantId, id);
   }
 
+  /** Atomically update only while status, timestamp, owner, and Project scope match. */
+  async updateIfSnapshot(
+    tenantId: string, id: string, updates: UpdateTaskRequest, snapshot: TaskMutationSnapshot,
+  ): Promise<TaskItem | null> {
+    const expectedIso = new Date(snapshot.updatedAt).toISOString();
+    if (expectedIso === MAX_CANONICAL_TASK_TIME) return null;
+    const setClauses = ["updated_at = ?"];
+    const values: unknown[] = [nextISO(expectedIso)];
+    const fields: Array<[keyof UpdateTaskRequest, string, boolean?]> = [
+      ["title", "title"], ["description", "description"], ["status", "status"], ["priority", "priority"],
+      ["dueDate", "due_date"], ["metadata", "metadata", 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"], ["files", "files", true],
+    ];
+    for (const [field, column, json] of fields) {
+      const value = updates[field];
+      if (value === undefined) continue;
+      setClauses.push(`${column} = ?`);
+      values.push(json && value !== null ? JSON.stringify(value) : field === "requireReview" ? (value ? 1 : 0) : value);
+    }
+    values.push(tenantId, id, snapshot.status, expectedIso, snapshot.ownerType, snapshot.ownerId,
+      snapshot.workspaceId, snapshot.projectId);
+    const result = this.db.prepare(
+      `UPDATE lt_tasks SET ${setClauses.join(", ")} WHERE tenant_id = ? AND id = ? AND status = ?
+        AND updated_at = ? AND owner_type = ? AND owner_id = ? AND workspace_id IS ? AND project_id IS ?`,
+    ).run(...values);
+    return result.changes === 0 ? null : this.getById(tenantId, id);
+  }
+
   /** Atomically update a child only when both child and parent snapshots match. */
   async updateIfStatusUpdatedAtAndParentUpdatedAt(
     tenantId: string,
@@ -458,4 +528,14 @@ export class LocalTaskStore implements TaskStore {
     ).run(tenantId, id);
     return result.changes > 0;
   }
+
+  /** Atomically delete only while status, timestamp, owner, and Project scope match. */
+  async deleteIfSnapshot(tenantId: string, id: string, snapshot: TaskMutationSnapshot): Promise<boolean> {
+    const result = this.db.prepare(
+      `DELETE FROM lt_tasks WHERE tenant_id = ? AND id = ? AND status = ? AND updated_at = ?
+        AND owner_type = ? AND owner_id = ? AND workspace_id IS ? AND project_id IS ?`,
+    ).run(tenantId, id, snapshot.status, new Date(snapshot.updatedAt).toISOString(), snapshot.ownerType,
+      snapshot.ownerId, snapshot.workspaceId, snapshot.projectId);
+    return result.changes > 0;
+  }
 }

package/src/stores/LocalTaskWorkItemStore.ts

@@ -9,10 +9,18 @@ import type {
   CreateWorkItemRequest,
   CreateWorkItemIfAbsentRequest,
   TaskWorkItemListFilter,
+  ProjectLifecycleEventQuery,
+  TaskMutationSnapshot,
 } from "@axiom-lattice/protocols";
+import { MAX_PENDING_EXECUTION_RESULTS_LIMIT } from "@axiom-lattice/protocols";
 import { ensureTable, nowISO, parseISO } from "../database";
 import { v4 as uuid } from "uuid";
 
+const PROJECT_LIFECYCLE_ACTIONS: ReadonlySet<string> = new Set([
+  "in_progress", "interrupted", "failed", "completed", "cancelled", "reassigned",
+]);
+
+
 const DDL = `
 CREATE TABLE IF NOT EXISTS lt_task_work_items (
   id TEXT NOT NULL,
@@ -47,6 +55,18 @@ interface WorkItemRow {
   created_at: string;
 }
 
+function parseDetail(raw: string | null): Record<string, unknown> | undefined {
+  if (!raw) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function mapRowToWorkItem(row: WorkItemRow): TaskWorkItem {
   return {
     id: row.id,
@@ -56,7 +76,7 @@ function mapRowToWorkItem(row: WorkItemRow): TaskWorkItem {
     actor: row.actor,
     threadId: row.thread_id ?? undefined,
     summary: row.summary ?? undefined,
-    detail: row.detail ? JSON.parse(row.detail) : undefined,
+    detail: parseDetail(row.detail),
     attempt: row.attempt ?? undefined,
     workspaceId: row.workspace_id ?? undefined,
     projectId: row.project_id ?? undefined,
@@ -65,6 +85,33 @@ function mapRowToWorkItem(row: WorkItemRow): TaskWorkItem {
   };
 }
 
+function assertAndCloneProjectLifecycleEvent(item: TaskWorkItem): TaskWorkItem {
+  let milliseconds: number;
+  try { milliseconds = Date.prototype.getTime.call(item.createdAt) as number; }
+  catch { throw new Error("Invalid project lifecycle event row"); }
+  if (!Number.isFinite(milliseconds) || typeof item.id !== "string" || item.id.length === 0
+    || typeof item.eventKey !== "string" || item.eventKey.length === 0) {
+    throw new Error("Invalid project lifecycle event row");
+  }
+  return { ...item, createdAt: new Date(milliseconds) };
+}
+
+function assertLifecyclePage(query: ProjectLifecycleEventQuery): number | null {
+  if (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > 100
+    || query.actions.length === 0
+    || query.actions.some((action) => !PROJECT_LIFECYCLE_ACTIONS.has(action))) {
+    throw new RangeError("Invalid project lifecycle event page");
+  }
+  if (!query.before) return null;
+  let milliseconds: number;
+  try { milliseconds = Date.prototype.getTime.call(query.before.createdAt) as number; }
+  catch { throw new RangeError("Invalid project lifecycle event cursor"); }
+  if (!Number.isFinite(milliseconds) || typeof query.before.id !== "string" || query.before.id.length === 0) {
+    throw new RangeError("Invalid project lifecycle event cursor");
+  }
+  return milliseconds;
+}
+
 export class LocalTaskWorkItemStore implements TaskWorkItemStore {
   private db: DatabaseWrapper;
 
@@ -76,6 +123,14 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
     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);`);
+    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_task_work_items_pending_order
+      ON lt_task_work_items (tenant_id, task_id, action, created_at DESC, id DESC);`);
+    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_task_work_items_reconciled_result
+      ON lt_task_work_items (tenant_id, task_id, json_extract(detail, '$.executionResultId'))
+      WHERE action = 'execution_reconciled';`);
+    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_task_work_items_project_lifecycle
+      ON lt_task_work_items (tenant_id, workspace_id, project_id, created_at DESC, id DESC)
+      WHERE event_key IS NOT NULL;`);
   }
 
   /** Add a column if it does not exist (SQLite version compatible). */
@@ -109,6 +164,31 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
     return mapRowToWorkItem(row!);
   }
 
+  /** Atomically inserts a work item by selecting one exact task snapshot. */
+  async createIfTaskSnapshot(
+    params: CreateWorkItemRequest,
+    snapshot: TaskMutationSnapshot,
+  ): Promise<TaskWorkItem | null> {
+    const id = uuid();
+    const result = 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, created_at)
+       SELECT ?, task.tenant_id, task.id, ?, ?, ?, ?, ?, ?, task.workspace_id, task.project_id, ?
+       FROM lt_tasks AS task
+       WHERE task.tenant_id = ? AND task.id = ? AND task.status = ? AND task.updated_at = ?
+          AND task.owner_type = ? AND task.owner_id = ? AND task.workspace_id IS ? AND task.project_id IS ?
+          AND ? IS task.workspace_id AND ? IS task.project_id`,
+    ).run(id, params.action, params.actor, params.threadId || null, params.summary || null,
+      params.detail ? JSON.stringify(params.detail) : null, params.attempt ?? null, nowISO(),
+      params.tenantId, params.taskId, snapshot.status, new Date(snapshot.updatedAt).toISOString(),
+      snapshot.ownerType, snapshot.ownerId, snapshot.workspaceId, snapshot.projectId,
+      params.workspaceId, params.projectId);
+    if (result.changes === 0) return null;
+    const row = this.db.prepare(`SELECT * FROM lt_task_work_items WHERE tenant_id = ? AND id = ?`)
+      .get(params.tenantId, id) as unknown as WorkItemRow | undefined;
+    return row ? mapRowToWorkItem(row) : null;
+  }
+
   /** 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(
@@ -154,4 +234,59 @@ export class LocalTaskWorkItemStore implements TaskWorkItemStore {
     ).all(...params, limit, offset) as unknown as WorkItemRow[];
     return rows.map(mapRowToWorkItem);
   }
+
+  /** List pending execution results using one bounded SQLite anti-join query. */
+  async listPendingExecutionResults(params: {
+    tenantId: string;
+    taskId: string;
+    limit: number;
+  }): Promise<TaskWorkItem[]> {
+    if (!Number.isSafeInteger(params.limit)
+      || params.limit < 0
+      || params.limit > MAX_PENDING_EXECUTION_RESULTS_LIMIT) {
+      const error = new RangeError(`limit must be a safe integer between 0 and ${MAX_PENDING_EXECUTION_RESULTS_LIMIT}`) as RangeError & {
+        code: "INVALID_LIMIT";
+      };
+      error.code = "INVALID_LIMIT";
+      throw error;
+    }
+    if (params.limit === 0) return [];
+    const rows = this.db.prepare(
+      `SELECT result.*
+       FROM lt_task_work_items AS result
+       WHERE result.tenant_id = ?
+         AND result.task_id = ?
+         AND result.action = 'execution_result'
+         AND substr(result.event_key, 1, 17) = 'execution-result:'
+         AND length(result.event_key) > 17
+         AND result.event_key NOT GLOB '*[^A-Za-z0-9._:-]*'
+         AND NOT EXISTS (
+           SELECT 1
+           FROM lt_task_work_items AS reconciled
+           WHERE reconciled.tenant_id = result.tenant_id
+             AND reconciled.task_id = result.task_id
+             AND reconciled.action = 'execution_reconciled'
+             AND json_extract(reconciled.detail, '$.executionResultId') = result.event_key
+         )
+       ORDER BY result.created_at DESC, result.id DESC
+       LIMIT ?`,
+    ).all(params.tenantId, params.taskId, params.limit) as unknown as WorkItemRow[];
+    return rows.map(mapRowToWorkItem);
+  }
+
+  /** Lists canonical project lifecycle events with an exclusive cursor. */
+  async listProjectLifecycleEvents(query: ProjectLifecycleEventQuery): Promise<TaskWorkItem[]> {
+    const cursorMilliseconds = assertLifecyclePage(query);
+    const cursor = cursorMilliseconds === null ? null : new Date(cursorMilliseconds).toISOString();
+    const rows = this.db.prepare(
+      `SELECT * FROM lt_task_work_items
+       WHERE tenant_id = ? AND workspace_id = ? AND project_id = ?
+         AND action IN (${query.actions.map(() => "?").join(", ")})
+         AND event_key IS NOT NULL AND event_key <> ''
+         AND (? IS NULL OR created_at < ? OR (created_at = ? AND id < ?))
+       ORDER BY created_at DESC, id DESC LIMIT ?`,
+    ).all(query.tenantId, query.workspaceId, query.projectId, ...query.actions,
+      cursor, cursor, cursor, query.before?.id ?? null, query.limit) as unknown as WorkItemRow[];
+    return rows.map(mapRowToWorkItem).map(assertAndCloneProjectLifecycleEvent);
+  }
 }