@axiom-lattice/local-stores 2.0.9 → 3.0.0

package/src/__tests__/LocalTaskWorkItemStore.test.ts

@@ -0,0 +1,215 @@
+import { tmpdir } from "os";
+import path from "path";
+import { unlinkSync } from "fs";
+import { closeDatabase, initDatabase, type DatabaseWrapper } from "../database";
+import { LocalTaskWorkItemStore } from "../stores/LocalTaskWorkItemStore";
+
+jest.mock("uuid", () => {
+  let id = 0;
+  return { v4: jest.fn(() => `test-id-${++id}`) };
+});
+
+const rows = [
+  {
+    id: "item-1",
+    tenant_id: "tenant-1",
+    task_id: "task-1",
+    action: "activity",
+    actor: "agent:a",
+    thread_id: null,
+    summary: null,
+    detail: null,
+    attempt: null,
+    workspace_id: null,
+    project_id: null,
+    created_at: "2026-01-02T00:00:00.000Z",
+  },
+];
+
+async function openTaskWorkItemStore(dbPath: string): Promise<LocalTaskWorkItemStore> {
+  const db = await initDatabase({ dbPath });
+  const exec = db.exec.bind(db);
+  jest.spyOn(db, "exec").mockImplementation((sql) => {
+    try {
+      exec(sql);
+    } catch (error) {
+      if (!(error instanceof Error) || !error.message.includes("duplicate column name")) {
+        throw error;
+      }
+    }
+  });
+  return new LocalTaskWorkItemStore(db);
+}
+
+describe("LocalTaskWorkItemStore", () => {
+  it("persists Markdown activity across store and database instances", async () => {
+    const dbPath = path.join(
+      tmpdir(),
+      `lt-task-work-item-test-${Date.now()}-${Math.random().toString(36).slice(2)}.db`,
+    );
+    try {
+      const firstStore = await openTaskWorkItemStore(dbPath);
+      const created = await firstStore.create({
+        tenantId: "tenant-1",
+        taskId: "task-1",
+        action: "activity",
+        actor: "agent:a",
+        detail: { markdown: "## Persisted update" },
+      });
+
+      closeDatabase();
+      const secondStore = await openTaskWorkItemStore(dbPath);
+      const persisted = await secondStore.list({
+        tenantId: "tenant-1",
+        taskId: "task-1",
+        order: "desc",
+        limit: 100,
+      });
+
+      expect(persisted).toHaveLength(1);
+      expect(persisted[0]).toMatchObject({
+        id: created.id,
+        taskId: created.taskId,
+        action: "activity",
+        detail: { markdown: "## Persisted update" },
+      });
+      expect(persisted[0].createdAt).toEqual(created.createdAt);
+    } finally {
+      closeDatabase();
+      unlinkSync(dbPath);
+    }
+  });
+
+  it("initializes an existing schema idempotently and preserves its event index", async () => {
+    const dbPath = path.join(
+      tmpdir(),
+      `lt-task-work-item-schema-test-${Date.now()}-${Math.random().toString(36).slice(2)}.db`,
+    );
+    try {
+      const db = await initDatabase({ dbPath });
+      db.exec(`
+        CREATE TABLE lt_task_work_items (
+          id TEXT NOT NULL,
+          tenant_id TEXT NOT NULL,
+          task_id TEXT NOT NULL,
+          action TEXT NOT NULL,
+          actor TEXT NOT NULL,
+          thread_id TEXT,
+          summary TEXT,
+          detail TEXT,
+          attempt INTEGER,
+          workspace_id TEXT,
+          project_id TEXT,
+          event_key TEXT,
+          created_at TEXT NOT NULL,
+          PRIMARY KEY (tenant_id, id)
+        );
+      `);
+
+      new LocalTaskWorkItemStore(db);
+      closeDatabase();
+      const reopenedDb = await initDatabase({ dbPath });
+      const reopenedStore = new LocalTaskWorkItemStore(reopenedDb);
+
+      const [first, second] = await Promise.all([
+        reopenedStore.createIfAbsentByEventKey({
+          tenantId: "tenant-1", taskId: "task-1", eventKey: "existing-schema:key",
+          action: "completion_evidence", actor: "agent:a",
+        }),
+        reopenedStore.createIfAbsentByEventKey({
+          tenantId: "tenant-1", taskId: "task-1", eventKey: "existing-schema:key",
+          action: "completion_evidence", actor: "agent:a",
+        }),
+      ]);
+
+      expect(second).toEqual(first);
+    } finally {
+      closeDatabase();
+      unlinkSync(dbPath);
+    }
+  });
+
+  it.each([
+    [undefined, "DESC"],
+    ["asc", "ASC"],
+    ["desc", "DESC"],
+  ] as const)("uses %s order as %s with deterministic IDs", async (order, sqlOrder) => {
+    const all = jest.fn().mockReturnValue(rows);
+    const prepare = jest.fn().mockReturnValue({ all });
+    const db = { exec: jest.fn(), prepare } as unknown as DatabaseWrapper;
+    const store = new LocalTaskWorkItemStore(db);
+
+    const result = await store.list({
+      tenantId: "tenant-1",
+      taskId: "task-1",
+      limit: 2,
+      ...(order && { order }),
+    });
+
+    expect(prepare).toHaveBeenLastCalledWith(expect.stringContaining(
+      `ORDER BY created_at ${sqlOrder}, id ${sqlOrder} LIMIT ? OFFSET ?`,
+    ));
+    expect(all).toHaveBeenCalledWith("tenant-1", "task-1", 2, 0);
+    expect(result.map((item) => item.id)).toEqual(["item-1"]);
+  });
+
+  it("filters by workspaceId and projectId", async () => {
+    const all = jest.fn().mockReturnValue(rows);
+    const prepare = jest.fn().mockReturnValue({ all });
+    const db = { exec: jest.fn(), prepare } as unknown as DatabaseWrapper;
+    const store = new LocalTaskWorkItemStore(db);
+
+    await store.list({
+      tenantId: "tenant-1",
+      taskId: "task-1",
+      workspaceId: "workspace-1",
+      projectId: "project-1",
+      order: "desc",
+      limit: 100,
+    });
+
+    expect(prepare).toHaveBeenLastCalledWith(expect.stringContaining(
+      "workspace_id = ? AND project_id = ? ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?",
+    ));
+    expect(all).toHaveBeenCalledWith(
+      "tenant-1", "task-1", "workspace-1", "project-1", 100, 0,
+    );
+  });
+
+  it("finds task-scoped event keys and atomically creates duplicates once", async () => {
+    const dbPath = path.join(
+      tmpdir(),
+      `lt-task-work-item-event-test-${Date.now()}-${Math.random().toString(36).slice(2)}.db`,
+    );
+    try {
+      const store = await openTaskWorkItemStore(dbPath);
+      const [first, second] = await Promise.all([
+        store.createIfAbsentByEventKey({
+          tenantId: "tenant-1", taskId: "task-1", eventKey: "evidence:key",
+          action: "completion_evidence", actor: "agent:a", summary: "first",
+        }),
+        store.createIfAbsentByEventKey({
+          tenantId: "tenant-1", taskId: "task-1", eventKey: "evidence:key",
+          action: "completion_evidence", actor: "agent:a", summary: "second",
+        }),
+      ]);
+      const otherTask = await store.createIfAbsentByEventKey({
+        tenantId: "tenant-1", taskId: "task-2", eventKey: "evidence:key",
+        action: "completion_evidence", actor: "agent:a",
+      });
+
+      expect(second).toEqual(first);
+      expect(first.summary).toBe("first");
+      expect(otherTask.id).not.toBe(first.id);
+      await expect(store.findByEventKey("tenant-1", "task-1", "evidence:key"))
+        .resolves.toEqual(first);
+      await expect(store.findByEventKey("tenant-1", "missing", "evidence:key"))
+        .resolves.toBeNull();
+      await expect(store.list({ tenantId: "tenant-1", taskId: "task-1" }))
+        .resolves.toHaveLength(1);
+    } finally {
+      closeDatabase();
+      unlinkSync(dbPath);
+    }
+  });
+});

package/src/database.ts

@@ -62,8 +62,9 @@ export class DatabaseWrapper {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   run(sql: string, ...params: any[]): RunResult {
     this.db.run(sql, params);
+    const changes = this.db.getRowsModified();
     this.save();
-    return new RunResult(this.db);
+    return new RunResult(changes);
   }
 
   /**
@@ -164,10 +165,11 @@ export class StatementWrapper {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   run(...params: any[]): RunResult {
     this.db.run(this.sql, params as BindParams);
+    const changes = this.db.getRowsModified();
     if (this.parent) {
       this.parent.save();
     }
-    return new RunResult(this.db);
+    return new RunResult(changes);
   }
 }
 
@@ -175,15 +177,15 @@ export class StatementWrapper {
  * Result of a run operation.
  */
 export class RunResult {
-  private db: SqlJsDatabase;
+  private modifiedRows: number;
 
-  constructor(db: SqlJsDatabase) {
-    this.db = db;
+  constructor(modifiedRows: number) {
+    this.modifiedRows = modifiedRows;
   }
 
   /** Number of rows modified by the last INSERT/UPDATE/DELETE. */
   get changes(): number {
-    return this.db.getRowsModified();
+    return this.modifiedRows;
   }
 }
 

package/src/stores/LocalA2AApiKeyStore.ts

@@ -19,7 +19,7 @@ CREATE TABLE IF NOT EXISTS lt_a2a_api_keys (
   key_value TEXT NOT NULL,
   tenant_id TEXT NOT NULL,
   project_id TEXT,
-  workspace_id TEXT,
+  assistant_ids TEXT,
   label TEXT,
   enabled INTEGER NOT NULL DEFAULT 1,
   created_at TEXT NOT NULL,
@@ -31,8 +31,8 @@ interface KeyRow {
   id: string;
   key_value: string;
   tenant_id: string;
-  project_id: string | null;
-  workspace_id: string | null;
+  project_id: string;
+  assistant_ids: string | null;
   label: string | null;
   enabled: number;
   created_at: string;
@@ -43,12 +43,49 @@ function generateApiKey(): string {
   return `a2a_${randomUUID().replace(/-/g, "")}`;
 }
 
+function parseAssistantIds(raw: string | null): string[] | undefined {
+  if (!raw) return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** SQLite-backed A2A API key persistence for local deployments. */
 export class LocalA2AApiKeyStore implements A2AApiKeyStore {
   private db: DatabaseWrapper;
 
   constructor(db: DatabaseWrapper) {
     this.db = db;
     ensureTable(db, DDL);
+    // Existing installs: add columns shipped after the original schema.
+    this.ensureColumn("lt_a2a_api_keys", "assistant_ids", "assistant_ids TEXT");
+    this.repairManagementIds();
+  }
+
+  /** 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}`);
+    }
+  }
+
+  private repairManagementIds(): void {
+    const rows = this.db.prepare(
+      `SELECT rowid, id FROM lt_a2a_api_keys`,
+    ).all() as Array<{ rowid: number; id: string | null }>;
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+    for (const row of rows) {
+      if (!row.id || !uuidPattern.test(row.id)) {
+        this.db.prepare(
+          `UPDATE lt_a2a_api_keys SET id = ? WHERE rowid = ?`,
+        ).run(randomUUID(), row.rowid);
+      }
+    }
   }
 
   async findByKey(key: string): Promise<A2AApiKeyRecord | null> {
@@ -63,6 +100,13 @@ export class LocalA2AApiKeyStore implements A2AApiKeyStore {
     return null;
   }
 
+  async findById(id: string): Promise<A2AApiKeyRecord | null> {
+    const row = this.db.prepare(
+      `SELECT * FROM lt_a2a_api_keys WHERE id = ?`,
+    ).get(id) as unknown as KeyRow | undefined;
+    return row ? mapRowToRecord(row) : null;
+  }
+
   async list(params: { tenantId?: string; limit?: number; offset?: number }): Promise<A2AApiKeyRecord[]> {
     const limit = params.limit || 100;
     const offset = params.offset || 0;
@@ -80,21 +124,20 @@ export class LocalA2AApiKeyStore implements A2AApiKeyStore {
   }
 
   async create(input: CreateA2AApiKeyInput): Promise<A2AApiKeyRecord> {
+    const id = randomUUID();
     const key = generateApiKey();
     const now = nowISO();
     this.db.prepare(
-      `INSERT INTO lt_a2a_api_keys (key_value, tenant_id, project_id, workspace_id, label, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`,
-    ).run(encrypt(key), input.tenantId, input.projectId || null, input.workspaceId || null, input.label || null, now, now);
-
-    const lastId = this.db.prepare(`SELECT last_insert_rowid() as id`).get() as { id: number };
+      `INSERT INTO lt_a2a_api_keys (id, key_value, tenant_id, project_id, assistant_ids, label, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(id, encrypt(key), input.tenantId, input.projectId, input.assistantIds ? JSON.stringify(input.assistantIds) : null, input.label || null, now, now);
 
     const record: A2AApiKeyRecord = {
-      id: String(lastId.id),
+      id,
       key,
       tenantId: input.tenantId,
       projectId: input.projectId,
-      workspaceId: input.workspaceId,
+      assistantIds: input.assistantIds,
       label: input.label,
       enabled: true,
       createdAt: parseISO(now),
@@ -151,8 +194,8 @@ export class LocalA2AApiKeyStore implements A2AApiKeyStore {
         map.set(key, {
           key,
           tenantId: row.tenant_id,
-          projectId: row.project_id || undefined,
-          workspaceId: row.workspace_id || undefined,
+          projectId: row.project_id,
+          assistantIds: parseAssistantIds(row.assistant_ids),
         });
       } catch { /* skip */ }
     }
@@ -167,8 +210,8 @@ function mapRowToRecord(row: KeyRow): A2AApiKeyRecord {
     id: row.id,
     key,
     tenantId: row.tenant_id,
-    projectId: row.project_id || undefined,
-    workspaceId: row.workspace_id || undefined,
+    projectId: row.project_id,
+    assistantIds: parseAssistantIds(row.assistant_ids),
     label: row.label || undefined,
     enabled: row.enabled === 1,
     createdAt: parseISO(row.created_at),

package/src/stores/LocalChannelInstallationStore.ts

@@ -99,15 +99,7 @@ export class LocalChannelInstallationStore implements ChannelInstallationStore {
     this.db.prepare(
       `INSERT INTO lt_channel_installations
        (id, tenant_id, channel, name, config, enabled, fallback_agent_id, reject_when_no_binding, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(id) DO UPDATE SET
-         channel = excluded.channel,
-         name = excluded.name,
-         config = excluded.config,
-         enabled = excluded.enabled,
-         fallback_agent_id = excluded.fallback_agent_id,
-         reject_when_no_binding = excluded.reject_when_no_binding,
-         updated_at = excluded.updated_at`,
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     ).run(
       installationId, tenantId, data.channel,
       data.name || null, JSON.stringify(data.config),

package/src/stores/LocalProjectStore.ts

@@ -6,6 +6,7 @@ import { DatabaseWrapper } from "../database";
 import type {
   ProjectStore,
   Project,
+  ProjectFilter,
   CreateProjectRequest,
   UpdateProjectRequest,
 } from "@axiom-lattice/protocols";
@@ -19,6 +20,7 @@ CREATE TABLE IF NOT EXISTS lt_projects (
   name TEXT NOT NULL,
   description TEXT,
   config TEXT,
+  kind TEXT DEFAULT 'business',
   created_at TEXT NOT NULL,
   updated_at TEXT NOT NULL,
   PRIMARY KEY (tenant_id, id)
@@ -33,6 +35,7 @@ interface ProjectRow {
   name: string;
   description: string | null;
   config: string | null;
+  kind: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -43,9 +46,16 @@ export class LocalProjectStore implements ProjectStore {
   constructor(db: DatabaseWrapper) {
     this.db = db;
     ensureTable(db, DDL);
+    this.ensureColumn("lt_projects", "kind", "kind TEXT DEFAULT 'business'");
   }
 
-  async getProjectsByWorkspace(tenantId: string, workspaceId: string): Promise<Project[]> {
+  async getProjectsByWorkspace(tenantId: string, workspaceId: string, filter?: ProjectFilter): Promise<Project[]> {
+    if (filter?.kind !== undefined) {
+      const rows = this.db.prepare(
+        `SELECT * FROM lt_projects WHERE tenant_id = ? AND workspace_id = ? AND kind = ? ORDER BY created_at DESC`,
+      ).all(tenantId, workspaceId, filter.kind) as unknown as ProjectRow[];
+      return rows.map(mapRowToProject);
+    }
     const rows = this.db.prepare(
       `SELECT * FROM lt_projects WHERE tenant_id = ? AND workspace_id = ? ORDER BY created_at DESC`,
     ).all(tenantId, workspaceId) as unknown as ProjectRow[];
@@ -66,17 +76,19 @@ export class LocalProjectStore implements ProjectStore {
     data: CreateProjectRequest,
   ): Promise<Project> {
     const now = nowISO();
+    const kind = data.kind || "business";
 
     this.db.prepare(
-      `INSERT INTO lt_projects (id, tenant_id, workspace_id, name, description, config, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `INSERT INTO lt_projects (id, tenant_id, workspace_id, name, description, config, kind, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(tenant_id, id) DO UPDATE SET
          workspace_id = excluded.workspace_id,
          name = excluded.name,
          description = excluded.description,
          config = excluded.config,
+         kind = excluded.kind,
          updated_at = excluded.updated_at`,
-    ).run(id, tenantId, workspaceId, data.name, data.description || null, data.config ? JSON.stringify(data.config) : null, now, now);
+    ).run(id, tenantId, workspaceId, data.name, data.description || null, data.config ? JSON.stringify(data.config) : null, kind, now, now);
 
     return {
       id,
@@ -85,6 +97,7 @@ export class LocalProjectStore implements ProjectStore {
       name: data.name,
       description: data.description,
       config: data.config,
+      kind,
       createdAt: parseISO(now),
       updatedAt: parseISO(now),
     };
@@ -113,6 +126,10 @@ export class LocalProjectStore implements ProjectStore {
       setClauses.push("config = ?");
       values.push(updates.config ? JSON.stringify(updates.config) : null);
     }
+    if (updates.kind !== undefined) {
+      setClauses.push("kind = ?");
+      values.push(updates.kind);
+    }
 
     if (setClauses.length === 0) return existing;
 
@@ -134,6 +151,14 @@ export class LocalProjectStore implements ProjectStore {
     ).run(tenantId, id);
     return result.changes > 0;
   }
+
+  /** 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 }>;
+    if (!cols.some((c) => c.name === column)) {
+      this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+    }
+  }
 }
 
 function mapRowToProject(row: ProjectRow): Project {
@@ -144,6 +169,7 @@ function mapRowToProject(row: ProjectRow): Project {
     name: row.name,
     description: row.description || undefined,
     config: row.config ? JSON.parse(row.config) as Record<string, unknown> : undefined,
+    kind: (row.kind || "business") as Project["kind"],
     createdAt: parseISO(row.created_at),
     updatedAt: parseISO(row.updated_at),
   };