@axiom-lattice/local-stores 3.0.2 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/local-stores",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "description": "Local SQLite-based stores for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,8 +25,8 @@
     "@types/sql.js": "^1.4.11",
     "sql.js": "^1.14.1",
     "uuid": "^14.0.1",
-    "@axiom-lattice/core": "4.1.0",
-    "@axiom-lattice/protocols": "4.0.1"
+    "@axiom-lattice/core": "4.2.1",
+    "@axiom-lattice/protocols": "4.1.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/LocalCapabilityBundleStore.test.ts

@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, it } from "@jest/globals";
+import { tmpdir } from "os";
+import path from "path";
+
+import { closeDatabase, initDatabase } from "../database";
+import { LocalCapabilityBundleStore } from "../stores/LocalCapabilityBundleStore";
+import { LocalProjectStore } from "../stores/LocalProjectStore";
+
+const nextDbPath = (): string => path.join(
+  tmpdir(), `lt-capability-bundle-${Date.now()}-${Math.random().toString(36).slice(2)}.db`,
+);
+const input = {
+  key: "research",
+  name: "Research",
+  description: "Research tools",
+  capabilities: [{
+    id: "filesystem", type: "filesystem", name: "Filesystem", enabled: true,
+    config: { roots: ["/workspace"], policy: { write: false } },
+  }],
+};
+
+describe("LocalCapabilityBundleStore", () => {
+  let store: LocalCapabilityBundleStore;
+  let projectStore: LocalProjectStore;
+  let db: Awaited<ReturnType<typeof initDatabase>>;
+
+  beforeEach(async () => {
+    db = await initDatabase({ dbPath: nextDbPath() });
+    store = new LocalCapabilityBundleStore(db);
+    projectStore = new LocalProjectStore(db);
+  });
+  afterEach(() => closeDatabase());
+
+  it("supports tenant-scoped CRUD, bulk reads, and nested JSON round-trips", async () => {
+    const created = await store.create("tenant-1", input);
+    await store.create("tenant-2", input);
+    expect(created.id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(await store.listByTenant("tenant-1")).toHaveLength(1);
+    expect(await store.getById("tenant-2", created.id)).toBeNull();
+    expect(await store.getManyByIds("tenant-1", [created.id, "missing"])).toEqual([created]);
+    expect((await store.getById("tenant-1", created.id))?.capabilities).toEqual(input.capabilities);
+
+    const updated = await store.update("tenant-1", created.id, {
+      key: "analysis", name: "Analysis", capabilities: [{ ...input.capabilities[0], config: { depth: 2 } }],
+    });
+    expect(updated?.id).toBe(created.id);
+    expect(updated?.createdAt).toBe(created.createdAt);
+    expect(Number.isNaN(Date.parse(created.createdAt))).toBe(false);
+    expect(Number.isNaN(Date.parse(updated?.updatedAt ?? ""))).toBe(false);
+    expect(Date.parse(updated?.updatedAt ?? "")).toBeGreaterThanOrEqual(Date.parse(created.createdAt));
+    expect(await store.update("tenant-2", created.id, { name: "Nope" })).toBeNull();
+    expect("delete" in store).toBe(false);
+    await expect(store.deleteIfUnreferenced("tenant-1", created.id)).resolves.toBe("deleted");
+  });
+
+  it("returns defensive nested capability configuration values", async () => {
+    const created = await store.create("tenant-1", input);
+    const fetched = await store.getById("tenant-1", created.id);
+    const config = fetched?.capabilities[0].config as {
+      roots: string[];
+      policy: { write: boolean };
+    };
+
+    config.roots.push("/mutated");
+    config.policy.write = true;
+
+    expect((await store.getById("tenant-1", created.id))?.capabilities).toEqual(input.capabilities);
+  });
+
+  it("enforces tenant-local unique keys with a stable error", async () => {
+    await store.create("tenant-1", input);
+    await expect(store.create("tenant-1", input)).rejects.toThrow(
+      "Capability bundle key already exists for tenant",
+    );
+    await expect(store.create("tenant-2", input)).resolves.toMatchObject({ key: input.key });
+  });
+
+  it("advances the revision on rapid content updates", async () => {
+    jest.useFakeTimers().setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+    try {
+      const created = await store.create("tenant-1", input);
+      const first = await store.update("tenant-1", created.id, { name: "First" });
+      const second = await store.update("tenant-1", created.id, { name: "Second" });
+
+      expect(Date.parse(first!.updatedAt)).toBeGreaterThan(Date.parse(created.updatedAt));
+      expect(Date.parse(second!.updatedAt)).toBeGreaterThan(Date.parse(first!.updatedAt));
+      await expect(store.update("tenant-1", created.id, { name: "Rejected" })).resolves.toMatchObject({ name: "Rejected" });
+      await projectStore.createProject("tenant-1", "workspace", "project", { name: "Project" });
+      await expect(projectStore.updateCapabilityBundleIds("tenant-1", "project", [created.id], {
+        [created.id]: first!.updatedAt,
+      })).resolves.toEqual({ status: "bundle_conflict" });
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it("rejects an update when its expected revision is stale", async () => {
+    const created = await store.create("tenant-1", input);
+    await store.update("tenant-1", created.id, { name: "First" });
+    await expect(store.update("tenant-1", created.id, { name: "Stale", expectedUpdatedAt: created.updatedAt }))
+      .resolves.toEqual({ status: "conflict" });
+    await expect(store.getById("tenant-1", created.id)).resolves.toMatchObject({ name: "First" });
+  });
+
+  it("checks CAS tokens for no-op updates without changing the revision", async () => {
+    const created = await store.create("tenant-1", input);
+
+    await expect(store.update("tenant-1", created.id, { expectedUpdatedAt: "stale" }))
+      .resolves.toEqual({ status: "conflict" });
+    await expect(store.update("tenant-1", created.id, { expectedUpdatedAt: created.updatedAt }))
+      .resolves.toEqual(created);
+  });
+
+  it("conditionally deletes bundles only when no tenant project references them", async () => {
+    const created = await store.create("tenant-1", input);
+    await projectStore.createProject("tenant-1", "workspace", "project", { name: "Project" });
+    await projectStore.updateCapabilityBundleIds("tenant-1", "project", [created.id]);
+    await expect(store.deleteIfUnreferenced("tenant-1", created.id)).resolves.toBe("in_use");
+    await projectStore.updateCapabilityBundleIds("tenant-1", "project", []);
+    await expect(store.deleteIfUnreferenced("tenant-1", created.id)).resolves.toBe("deleted");
+    await expect(store.deleteIfUnreferenced("tenant-1", created.id)).resolves.toBe("not_found");
+  });
+
+  it("rejects a stale composition after its validated bundle is deleted", async () => {
+    const created = await store.create("tenant-1", input);
+    await projectStore.createProject("tenant-1", "workspace", "project", { name: "Project" });
+
+    await expect(store.getManyByIds("tenant-1", [created.id])).resolves.toHaveLength(1);
+    await expect(store.deleteIfUnreferenced("tenant-1", created.id)).resolves.toBe("deleted");
+    await expect(projectStore.updateCapabilityBundleIds("tenant-1", "project", [created.id]))
+      .resolves.toEqual({ status: "bundle_not_found" });
+    await expect(projectStore.getProjectById("tenant-1", "project"))
+      .resolves.toMatchObject({ config: undefined });
+  });
+
+  it("finds references only for the requested tenant", async () => {
+    const tenantOneBundle = await store.create("tenant-1", { ...input, key: "tenant-one" });
+    const tenantTwoBundle = await store.create("tenant-2", { ...input, key: "tenant-two" });
+    await projectStore.createProject("tenant-1", "workspace", "reference", { name: "Reference" });
+    await projectStore.updateCapabilityBundleIds("tenant-1", "reference", [tenantOneBundle.id]);
+    await projectStore.createProject("tenant-2", "workspace", "other", { name: "Other" });
+    await projectStore.updateCapabilityBundleIds("tenant-2", "other", [tenantTwoBundle.id]);
+    await expect(projectStore.isCapabilityBundleReferenced("tenant-1", tenantOneBundle.id)).resolves.toBe(true);
+    await expect(projectStore.isCapabilityBundleReferenced("tenant-1", tenantTwoBundle.id)).resolves.toBe(false);
+    await expect(projectStore.isCapabilityBundleReferenced("tenant-1", "missing")).resolves.toBe(false);
+  });
+
+  it("treats malformed project config JSON as having no bundle reference", async () => {
+    await projectStore.createProject("tenant-1", "workspace", "project", { name: "Project" });
+    db.prepare("UPDATE lt_projects SET config = ? WHERE tenant_id = ? AND id = ?")
+      .run("{malformed", "tenant-1", "project");
+
+    await expect(projectStore.isCapabilityBundleReferenced("tenant-1", "bundle-1")).resolves.toBe(false);
+  });
+
+  it.each(["null", "[]", "true", "7", '"config"'])(
+    "treats valid non-object project config JSON %s as having no bundle reference",
+    async (config) => {
+      await projectStore.createProject("tenant-1", "workspace", "project", { name: "Project" });
+      db.prepare("UPDATE lt_projects SET config = ? WHERE tenant_id = ? AND id = ?")
+        .run(config, "tenant-1", "project");
+
+      await expect(projectStore.isCapabilityBundleReferenced("tenant-1", "bundle-1")).resolves.toBe(false);
+    },
+  );
+
+  it("updates only capability bundle IDs while preserving unrelated config", async () => {
+    await projectStore.createProject("tenant-1", "workspace", "project", { name: "Project", config: { keep: true } });
+    const first = await store.create("tenant-1", { ...input, key: "b1" });
+    const second = await store.create("tenant-1", { ...input, key: "b2" });
+    const updated = await projectStore.updateCapabilityBundleIds("tenant-1", "project", [first.id, second.id]);
+    expect(updated).toMatchObject({ status: "updated", project: { config: { keep: true, capabilityBundleIds: [first.id, second.id] } } });
+    await expect(projectStore.updateCapabilityBundleIds("tenant-2", "project", [])).resolves.toEqual({ status: "project_not_found" });
+  });
+
+  it("rejects assignment when the reviewed bundle revision is stale", async () => {
+    const bundle = await store.create("tenant-1", input);
+    await projectStore.createProject("tenant-1", "workspace", "conflict", { name: "Conflict" });
+
+    await expect(projectStore.updateCapabilityBundleIds("tenant-1", "conflict", [bundle.id], { [bundle.id]: "stale" }))
+      .resolves.toEqual({ status: "bundle_conflict" });
+  });
+
+  it("rejects capability bundle references through generic project writes", async () => {
+    await expect(projectStore.createProject("tenant-1", "workspace", "project", {
+      name: "Project", config: { capabilityBundleIds: [] },
+    })).rejects.toMatchObject({ code: "INVALID_BUNDLE_CONFIG" });
+    await projectStore.createProject("tenant-1", "workspace", "project", {
+      name: "Project", config: { keep: true },
+    });
+    await expect(projectStore.updateProject("tenant-1", "project", {
+      config: { capabilityBundleIds: [] },
+    })).rejects.toMatchObject({ code: "INVALID_BUNDLE_CONFIG" });
+    await expect(projectStore.getProjectById("tenant-1", "project"))
+      .resolves.toMatchObject({ config: { keep: true } });
+  });
+
+  it("preserves capability bundle IDs when generic create upserts an assigned project", async () => {
+    const bundle = await store.create("tenant-1", input);
+    await projectStore.createProject("tenant-1", "workspace", "project", {
+      name: "Original",
+      config: { original: true },
+    });
+    await projectStore.updateCapabilityBundleIds("tenant-1", "project", [bundle.id]);
+
+    const upserted = await projectStore.createProject("tenant-1", "workspace-2", "project", {
+      name: "Upserted",
+      config: { replacement: true },
+    });
+
+    expect(upserted).toMatchObject({
+      workspaceId: "workspace-2",
+      name: "Upserted",
+      config: { replacement: true, capabilityBundleIds: [bundle.id] },
+    });
+  });
+});

package/src/__tests__/LocalEvalStore.test.ts

@@ -8,7 +8,7 @@
 import { describe, expect, it, beforeEach, afterEach } from "@jest/globals";
 import { tmpdir } from "os";
 import path from "path";
-import { initDatabase, closeDatabase, ensureTable } from "../database";
+import { initDatabase, closeDatabase, ensureTable, type DatabaseWrapper } from "../database";
 import { LocalEvalStore, DDL } from "../stores/LocalEvalStore";
 
 // sql.js persists to disk via DatabaseWrapper.save(), so each test needs a
@@ -21,9 +21,10 @@ const nextDbPath = () => {
 
 describe("LocalEvalStore project name uniqueness", () => {
   let store: LocalEvalStore;
+  let db: DatabaseWrapper;
 
   beforeEach(async () => {
-    const db = await initDatabase({ dbPath: nextDbPath() });
+    db = await initDatabase({ dbPath: nextDbPath() });
     store = new LocalEvalStore(db);
   });
 
@@ -93,4 +94,42 @@ describe("LocalEvalStore project name uniqueness", () => {
     const runs = db.prepare(`SELECT project_id FROM lt_eval_runs WHERE id = 'run-1'`).get() as { project_id: string };
     expect(runs.project_id).toBe("dup-new");
   });
+
+  it("deletes project suites, cases, runs, and results without affecting another project", async () => {
+    await store.createProject("tenant-1", "project-delete", {
+      name: "delete-me", judgeModelConfig: {}, targetServerConfig: {},
+    });
+    await store.createProject("tenant-1", "project-keep", {
+      name: "keep-me", judgeModelConfig: {}, targetServerConfig: {},
+    });
+    await store.createSuite("tenant-1", "project-delete", "suite-delete", { name: "delete-suite" });
+    await store.createSuite("tenant-1", "project-keep", "suite-keep", { name: "keep-suite" });
+    await store.createCase("tenant-1", "suite-delete", "case-delete", {
+      inputMessage: "delete", steps: [], outputType: "message_content", contentAssertion: "delete",
+    });
+    await store.createCase("tenant-1", "suite-keep", "case-keep", {
+      inputMessage: "keep", steps: [], outputType: "message_content", contentAssertion: "keep",
+    });
+    await store.createRun("tenant-1", "project-delete", "run-delete", { concurrency: 1, totalCases: 1 });
+    await store.createRun("tenant-1", "project-keep", "run-keep", { concurrency: 1, totalCases: 1 });
+    await store.createRunResult("tenant-1", "run-delete", "result-delete", {
+      suiteName: "delete-suite", caseId: "case-delete", pass: true, score: 100,
+    });
+    await store.createRunResult("tenant-1", "run-keep", "result-keep", {
+      suiteName: "keep-suite", caseId: "case-keep", pass: true, score: 100,
+    });
+
+    await expect(store.deleteProject("tenant-1", "project-delete")).resolves.toBe(true);
+
+    for (const table of ["lt_eval_projects", "lt_eval_suites", "lt_eval_cases", "lt_eval_runs", "lt_eval_run_results"]) {
+      const deleted = db.prepare(`SELECT COUNT(*) AS count FROM ${table} WHERE id LIKE '%delete'`).get() as { count: number };
+      const kept = db.prepare(`SELECT COUNT(*) AS count FROM ${table} WHERE id LIKE '%keep'`).get() as { count: number };
+      expect(deleted.count).toBe(0);
+      expect(kept.count).toBe(1);
+    }
+  });
+
+  it("returns false when deleting a project that does not exist", async () => {
+    await expect(store.deleteProject("tenant-1", "missing-project")).resolves.toBe(false);
+  });
 });

package/src/__tests__/LocalProjectStore.test.ts

@@ -6,7 +6,7 @@
  * getProjectsByWorkspace supports an optional kind filter.
  */
 
-import { describe, expect, it, beforeEach, afterEach } from "@jest/globals";
+import { describe, expect, it, beforeEach, afterEach, jest } from "@jest/globals";
 import { tmpdir } from "os";
 import path from "path";
 import { initDatabase, closeDatabase } from "../database";
@@ -19,11 +19,12 @@ const nextDbPath = () =>
 
 describe("LocalProjectStore project kind", () => {
   let store: LocalProjectStore;
+  let db: Awaited<ReturnType<typeof initDatabase>>;
   const tenantId = "t1";
   const workspaceId = "ws1";
 
   beforeEach(async () => {
-    const db = await initDatabase({ dbPath: nextDbPath() });
+    db = await initDatabase({ dbPath: nextDbPath() });
     store = new LocalProjectStore(db);
   });
 
@@ -81,6 +82,42 @@ describe("LocalProjectStore project kind", () => {
     expect(all).toHaveLength(2);
   });
 
+  it("preserves capability bundle IDs during generic config replacement", async () => {
+    await store.createProject(tenantId, workspaceId, "reserved", { name: "Reserved", config: { keep: true } });
+    db.exec("UPDATE lt_projects SET config = '{\"keep\":true,\"capabilityBundleIds\":[\"bundle-1\"]}' WHERE tenant_id = 't1' AND id = 'reserved'");
+
+    const updated = await store.updateProject(tenantId, "reserved", { config: { replacement: true } });
+
+    expect(updated?.config).toEqual({ replacement: true, capabilityBundleIds: ["bundle-1"] });
+  });
+
+  it("preserves an assignment made between the generic read and write", async () => {
+    await store.createProject(tenantId, workspaceId, "interleaved", {
+      name: "Interleaved",
+      config: { keep: true },
+    });
+    const originalPrepare = db.prepare.bind(db);
+    let injected = false;
+    jest.spyOn(db, "prepare").mockImplementation((sql) => {
+      if (!injected && sql.startsWith("UPDATE lt_projects SET config =")) {
+        injected = true;
+        originalPrepare(
+          "UPDATE lt_projects SET config = json_set(COALESCE(config, '{}'), '$.capabilityBundleIds', json(?)) WHERE tenant_id = ? AND id = ?",
+        ).run('["bundle-latest"]', tenantId, "interleaved");
+      }
+      return originalPrepare(sql);
+    });
+
+    const updated = await store.updateProject(tenantId, "interleaved", {
+      config: { replacement: true },
+    });
+
+    expect(updated?.config).toEqual({
+      replacement: true,
+      capabilityBundleIds: ["bundle-latest"],
+    });
+  });
+
   describe("multiple training projects per tenant/workspace", () => {
     it("allows multiple training projects in the same tenant/workspace", async () => {
       await store.createProject(tenantId, workspaceId, "t1", {

package/src/__tests__/LocalTaskWorkItemStore.test.ts

@@ -212,4 +212,111 @@ describe("LocalTaskWorkItemStore", () => {
       unlinkSync(dbPath);
     }
   });
+
+  it("queries bounded newest pending execution results with scope and reconciliation filtering", async () => {
+    const dbPath = path.join(
+      tmpdir(),
+      `lt-task-work-item-pending-test-${Date.now()}-${Math.random().toString(36).slice(2)}.db`,
+    );
+    try {
+      const db = await initDatabase({ dbPath });
+      const store = new LocalTaskWorkItemStore(db);
+      const pending = await Promise.all(["a", "b", "c"].map((suffix) => store.createIfAbsentByEventKey({
+        tenantId: "tenant-1", taskId: "task-1", eventKey: `execution-result:${suffix}`,
+        action: "execution_result", actor: "agent:worker",
+      })));
+      await store.create({
+        tenantId: "tenant-1", taskId: "task-1", action: "execution_result", actor: "agent:worker",
+      });
+      await store.createIfAbsentByEventKey({
+        tenantId: "tenant-1", taskId: "task-1", eventKey: "   ",
+        action: "execution_result", actor: "agent:worker",
+      });
+      for (const eventKey of [
+        "\t", "\n", "wrong-prefix:value", "execution-result:",
+        " execution-result:value", "execution-result: value", "execution-result:value\t",
+        "execution-result:non-breaking\u00a0space", "execution-result:next-line\u0085",
+        "execution-result:em-space\u2003", "execution-result:invalid/punctuation",
+      ]) {
+        await store.createIfAbsentByEventKey({
+          tenantId: "tenant-1", taskId: "task-1", eventKey,
+          action: "execution_result", actor: "agent:worker",
+        });
+      }
+      await store.createIfAbsentByEventKey({
+        tenantId: "tenant-1", taskId: "task-2", eventKey: "execution-result:other-task",
+        action: "execution_result", actor: "agent:worker",
+      });
+      await store.createIfAbsentByEventKey({
+        tenantId: "tenant-2", taskId: "task-1", eventKey: "execution-result:other-tenant",
+        action: "execution_result", actor: "agent:worker",
+      });
+      await store.createIfAbsentByEventKey({
+        tenantId: "tenant-1", taskId: "task-1",
+        eventKey: "execution-reconciled:execution-result:b", action: "execution_reconciled",
+        actor: "agent:owner", detail: { executionResultId: "execution-result:b" },
+      });
+      db.prepare("UPDATE lt_task_work_items SET created_at = ? WHERE action = ?")
+        .run("2026-01-01T00:00:00.000Z", "execution_result");
+
+      const result = await store.listPendingExecutionResults({
+        tenantId: "tenant-1", taskId: "task-1", limit: 2,
+      });
+      const expectedIds = pending
+        .filter((item) => item.eventKey !== "execution-result:b")
+        .map((item) => item.id)
+        .sort((left, right) => right.localeCompare(left))
+        .slice(0, 2);
+
+      expect(result.map((item) => item.id)).toEqual(expectedIds);
+    } finally {
+      closeDatabase();
+      unlinkSync(dbPath);
+    }
+  });
+
+  it.each([-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, Number.MAX_SAFE_INTEGER + 1, 1_001])(
+    "rejects invalid pending execution result limit %s",
+    async (limit) => {
+      const db = {
+        exec: jest.fn(), prepare: jest.fn().mockReturnValue({ all: jest.fn().mockReturnValue([]) }),
+      } as unknown as DatabaseWrapper;
+      const store = new LocalTaskWorkItemStore(db);
+      (db.prepare as jest.Mock).mockClear();
+
+      await expect(store.listPendingExecutionResults({
+        tenantId: "tenant-1", taskId: "task-1", limit,
+      })).rejects.toMatchObject({ name: "RangeError", code: "INVALID_LIMIT" });
+      expect(db.prepare).not.toHaveBeenCalled();
+    },
+  );
+
+  it("returns no pending execution results for limit zero without querying", async () => {
+    const db = {
+      exec: jest.fn(), prepare: jest.fn().mockReturnValue({ all: jest.fn().mockReturnValue([]) }),
+    } as unknown as DatabaseWrapper;
+    const store = new LocalTaskWorkItemStore(db);
+    (db.prepare as jest.Mock).mockClear();
+
+    await expect(store.listPendingExecutionResults({
+      tenantId: "tenant-1", taskId: "task-1", limit: 0,
+    })).resolves.toEqual([]);
+    expect(db.prepare).not.toHaveBeenCalled();
+  });
+
+  it("creates indexes supporting ordered pending and reconciliation lookups", () => {
+    const exec = jest.fn();
+    const db = {
+      exec, prepare: jest.fn().mockReturnValue({ all: jest.fn().mockReturnValue([]) }),
+    } as unknown as DatabaseWrapper;
+
+    new LocalTaskWorkItemStore(db);
+
+    expect(exec).toHaveBeenCalledWith(expect.stringContaining(
+      "(tenant_id, task_id, action, created_at DESC, id DESC)",
+    ));
+    expect(exec).toHaveBeenCalledWith(expect.stringMatching(
+      /json_extract\(detail, '\$\.executionResultId'\)[\s\S]+WHERE action = 'execution_reconciled'/,
+    ));
+  });
 });

package/src/__tests__/LocalThreadMessageQueueStore.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, it } from "@jest/globals";
+import path from "path";
+import { tmpdir } from "os";
+import { closeDatabase, initDatabase } from "../database";
+import { LocalThreadMessageQueueStore } from "../stores/LocalThreadMessageQueueStore";
+
+describe("LocalThreadMessageQueueStore scope isolation", () => {
+  let store: LocalThreadMessageQueueStore;
+
+  beforeEach(async () => {
+    const dbPath = path.join(tmpdir(), `lt-queue-${Date.now()}-${Math.random().toString(36).slice(2)}.db`);
+    store = new LocalThreadMessageQueueStore(await initDatabase({ dbPath }));
+  });
+
+  afterEach(() => closeDatabase());
+
+  it("keeps projectless reads and mutations isolated from a project sharing the thread", async () => {
+    const base = { threadId: "shared", tenantId: "tenant", assistantId: "assistant", workspaceId: "workspace" };
+    const projectless = await store.addMessage({ ...base, content: "projectless" });
+    const projected = await store.addMessage({ ...base, projectId: "project", content: "project" });
+    const scope = { tenantId: "tenant", assistantId: "assistant", workspaceId: "workspace", projectId: undefined };
+
+    expect((await store.getPendingMessages("shared", scope)).map((message) => message.id)).toEqual([projectless.id]);
+    expect(await store.getQueueSize("shared", scope)).toBe(1);
+    await store.markProcessing(projectless.id, undefined, scope);
+    expect((await store.getProcessingMessages("shared", scope)).map((message) => message.id)).toEqual([projectless.id]);
+    expect(await store.resetProcessingToPending("shared", scope)).toBe(1);
+    expect(await store.removeMessage(projected.id, scope)).toBe(false);
+    await store.clearMessages("shared", scope);
+    expect((await store.getPendingMessages("shared")).map((message) => message.id)).toEqual([projected.id]);
+  });
+
+  it("preserves nullable scope identity when discovering persisted unscoped rows", async () => {
+    const message = await store.addMessage({
+      threadId: "legacy",
+      tenantId: "tenant",
+      assistantId: "assistant",
+      content: "legacy",
+    });
+
+    const scope = { tenantId: "tenant", assistantId: "assistant", workspaceId: null, projectId: null };
+    expect(await store.getThreadsWithPendingMessages()).toEqual([{
+      tenantId: "tenant",
+      assistantId: "assistant",
+      threadId: "legacy",
+      workspaceId: null,
+      projectId: null,
+    }]);
+    expect(await store.getPendingMessages("legacy", scope)).toHaveLength(1);
+    await store.markProcessing(message.id, undefined, scope);
+    expect(await store.getProcessingMessages("legacy", scope)).toHaveLength(1);
+    expect(await store.removeMessage(message.id, scope)).toBe(true);
+    expect(await store.getProcessingMessages("legacy", scope)).toHaveLength(0);
+  });
+
+  it("atomically accepts no more than the bounded number of messages", async () => {
+    const params = {
+      threadId: "bounded",
+      tenantId: "tenant",
+      assistantId: "assistant",
+      workspaceId: null,
+      projectId: null,
+      content: "message",
+    };
+
+    const accepted = await Promise.all(
+      Array.from({ length: 5 }, (_, index) => store.addMessageIfCapacity({ ...params, id: `msg-${index}` }, 2)),
+    );
+
+    expect(accepted.filter(Boolean)).toHaveLength(2);
+    expect(await store.getQueueSize("bounded", {
+      tenantId: "tenant",
+      assistantId: "assistant",
+      workspaceId: null,
+      projectId: null,
+    })).toBe(2);
+  });
+});

package/src/createLocalStoreConfig.ts

@@ -37,6 +37,7 @@ import { LocalSkillStore } from "./stores/LocalSkillStore";
 import { LocalScheduleStorage } from "./stores/LocalScheduleStorage";
 import { LocalTaskStore } from "./stores/LocalTaskStore";
 import { LocalTaskWorkItemStore } from "./stores/LocalTaskWorkItemStore";
+import { LocalCapabilityBundleStore } from "./stores/LocalCapabilityBundleStore";
 
 export interface LocalStoreConfigOptions {
   /**
@@ -82,6 +83,7 @@ export async function createLocalStoreConfig(options: LocalStoreConfigOptions =
     schedule: new LocalScheduleStorage(db),
     task: new LocalTaskStore(db),
     taskWorkItem: new LocalTaskWorkItemStore(db),
+    capabilityBundle: new LocalCapabilityBundleStore(db),
     checkpoint: SqliteSaver.fromConnString(dbPath),
   };
 }

package/src/index.ts

@@ -48,4 +48,5 @@ export { LocalSkillStore } from "./stores/LocalSkillStore";
 export { LocalScheduleStorage } from "./stores/LocalScheduleStorage";
 export { LocalTaskStore } from "./stores/LocalTaskStore";
 export { LocalTaskWorkItemStore } from "./stores/LocalTaskWorkItemStore";
+export { LocalCapabilityBundleStore } from "./stores/LocalCapabilityBundleStore";
 export { InMemoryConversationStore } from "./stores/InMemoryConversationStore";

package/src/stores/LocalCapabilityBundleStore.ts

@@ -0,0 +1,53 @@
+import { randomUUID } from "crypto";
+import type { CapabilityBundle, CapabilityBundleDeleteResult, CapabilityBundleStore, InternalCreateCapabilityBundleInput, InternalUpdateCapabilityBundleInput } from "@axiom-lattice/protocols";
+import { DatabaseWrapper, ensureTable, nowISO, parseISO } from "../database";
+
+const DDL = `CREATE TABLE IF NOT EXISTS lt_capability_bundles (id TEXT NOT NULL, tenant_id TEXT NOT NULL, bundle_key TEXT NOT NULL, name TEXT NOT NULL, description TEXT, capabilities TEXT NOT NULL DEFAULT '[]', created_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY (tenant_id, id), UNIQUE (tenant_id, bundle_key)); CREATE INDEX IF NOT EXISTS idx_lt_capability_bundles_tenant ON lt_capability_bundles(tenant_id);`;
+type Row = { id: string; tenant_id: string; bundle_key: string; name: string; description: string | null; capabilities: string; created_at: string; updated_at: string };
+const duplicateMessage = "Capability bundle key already exists for tenant";
+function map(row: Row): CapabilityBundle { return { id: row.id, tenantId: row.tenant_id, key: row.bundle_key, name: row.name, description: row.description ?? undefined, capabilities: JSON.parse(row.capabilities), createdAt: parseISO(row.created_at).toISOString(), updatedAt: parseISO(row.updated_at).toISOString() }; }
+function isConstraint(error: unknown): boolean { return error instanceof Error && /UNIQUE constraint failed/.test(error.message); }
+function nextTimestamp(previous?: string): string { const now = Date.now(); const previousTime = previous ? Date.parse(previous) : Number.NaN; return new Date(Math.max(now, Number.isFinite(previousTime) ? previousTime + 1 : now)).toISOString(); }
+
+/**
+ * Persists tenant-scoped capability bundles in a shared local sql.js database.
+ *
+ * The constructor creates the required table and index idempotently. Database
+ * lifecycle remains owned by the caller through `initDatabase` and
+ * `closeDatabase`.
+ *
+ * @example
+ * ```ts
+ * const db = await initDatabase({ dbPath: "./lattice.db" });
+ * const store = new LocalCapabilityBundleStore(db);
+ * const bundles = await store.listByTenant("tenant-1");
+ * ```
+ */
+export class LocalCapabilityBundleStore implements CapabilityBundleStore {
+  /**
+   * Creates a capability bundle store over an initialized sql.js database.
+   *
+   * @param db - Shared local database wrapper used for persistence.
+   */
+  constructor(private readonly db: DatabaseWrapper) { ensureTable(db, DDL); }
+  async listByTenant(tenantId: string): Promise<CapabilityBundle[]> { return (this.db.prepare("SELECT * FROM lt_capability_bundles WHERE tenant_id = ? ORDER BY created_at").all(tenantId) as unknown as Row[]).map(map); }
+  async getById(tenantId: string, id: string): Promise<CapabilityBundle | null> { const row = this.db.prepare("SELECT * FROM lt_capability_bundles WHERE tenant_id = ? AND id = ?").get(tenantId, id) as unknown as Row | undefined; return row ? map(row) : null; }
+  async getManyByIds(tenantId: string, ids: string[]): Promise<CapabilityBundle[]> { return ids.flatMap((id) => { const row = this.db.prepare("SELECT * FROM lt_capability_bundles WHERE tenant_id = ? AND id = ?").get(tenantId, id) as unknown as Row | undefined; return row ? [map(row)] : []; }); }
+  async create(tenantId: string, input: InternalCreateCapabilityBundleInput): Promise<CapabilityBundle> { const now = nextTimestamp(); const id = randomUUID(); try { this.db.prepare("INSERT INTO lt_capability_bundles (id, tenant_id, bundle_key, name, description, capabilities, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)").run(id, tenantId, input.key, input.name, input.description ?? null, JSON.stringify(input.capabilities), now, now); } catch (error) { if (isConstraint(error)) throw new Error(duplicateMessage); throw error; } return (await this.getById(tenantId, id)) as CapabilityBundle; }
+  async update(tenantId: string, id: string, input: InternalUpdateCapabilityBundleInput): Promise<CapabilityBundle | { status: "conflict" } | null> { const existing = await this.getById(tenantId, id); if (!existing) return null; if (input.expectedUpdatedAt !== undefined && input.expectedUpdatedAt !== existing.updatedAt) return { status: "conflict" }; const fields: string[] = []; const values: unknown[] = []; const add = (field: string, value: unknown): void => { fields.push(`${field} = ?`); values.push(value); }; if (input.name !== undefined) add("name", input.name); if (Object.prototype.hasOwnProperty.call(input, "description")) add("description", input.description ?? null); if (input.capabilities !== undefined) add("capabilities", JSON.stringify(input.capabilities)); if (!fields.length) return existing; const now = nextTimestamp(existing.updatedAt); fields.push("updated_at = ?"); values.push(now, tenantId, id); try { if (input.expectedUpdatedAt !== undefined) { const result = this.db.prepare(`UPDATE lt_capability_bundles SET ${fields.join(", ")} WHERE tenant_id = ? AND id = ? AND updated_at = ?`).run(...values, input.expectedUpdatedAt); if (result.changes === 0) return { status: "conflict" }; } else { this.db.prepare(`UPDATE lt_capability_bundles SET ${fields.join(", ")} WHERE tenant_id = ? AND id = ?`).run(...values); } } catch (error) { if (isConstraint(error)) throw new Error(duplicateMessage); throw error; } return this.getById(tenantId, id); }
+  async deleteIfUnreferenced(tenantId: string, id: string): Promise<CapabilityBundleDeleteResult> {
+    const result = this.db.prepare(
+      `DELETE FROM lt_capability_bundles
+       WHERE tenant_id = ? AND id = ?
+       AND NOT EXISTS (
+         SELECT 1 FROM lt_projects
+         WHERE tenant_id = ?
+         AND json_type(config, '$.capabilityBundleIds') = 'array'
+         AND EXISTS (SELECT 1 FROM json_each(config, '$.capabilityBundleIds') WHERE value = ?)
+       )`,
+    ).run(tenantId, id, tenantId, id);
+    if (result.changes > 0) return "deleted";
+    if (await this.getById(tenantId, id)) return "in_use";
+    return "not_found";
+  }
+}