@axiom-lattice/local-stores 3.1.0 → 3.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/local-stores",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "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.2.0",
-    "@axiom-lattice/protocols": "4.1.0"
+    "@axiom-lattice/core": "4.2.2",
+    "@axiom-lattice/protocols": "4.1.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/LocalCapabilityBundleStore.test.ts

@@ -0,0 +1,216 @@
+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__/LocalChannelBindingStore.test.ts

@@ -0,0 +1,183 @@
+import path from "path";
+import { tmpdir } from "os";
+import {
+  ChannelBindingMigrationConflictError,
+  DuplicateChannelBindingSubjectError,
+  type BindingMutablePatch,
+} from "@axiom-lattice/protocols";
+import { closeDatabase, initDatabase, type DatabaseWrapper } from "../database";
+import { LocalChannelBindingStore } from "../stores/LocalChannelBindingStore";
+import { ensureChannelBindingSubjectIndex } from "../stores/room-channel-binding-index";
+
+const dbPath = (): string => path.join(tmpdir(), `binding-${Date.now()}-${Math.random()}.db`);
+const input = (overrides: Record<string, unknown> = {}) => ({
+  channel: "room", channelInstallationId: "install-1", tenantId: "tenant-a",
+  senderId: "sender-1", agentId: "agent-1", threadId: "thread-1", ...overrides,
+});
+
+describe("LocalChannelBindingStore protected bindings", () => {
+  let db: DatabaseWrapper;
+  afterEach(() => closeDatabase());
+
+  it("preserves legacy duplicates and fails startup before creating the index", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    db.exec(`CREATE TABLE lt_channel_bindings (
+      id TEXT PRIMARY KEY, channel TEXT NOT NULL, channel_installation_id TEXT NOT NULL,
+      tenant_id TEXT NOT NULL, sender_id TEXT NOT NULL, agent_id TEXT NOT NULL, thread_id TEXT,
+      workspace_id TEXT, project_id TEXT, thread_mode TEXT NOT NULL DEFAULT 'fixed',
+      sender_display_name TEXT, sender_metadata TEXT, enabled INTEGER NOT NULL DEFAULT 1,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL)`);
+    db.exec(`INSERT INTO lt_channel_bindings
+      (id,channel,channel_installation_id,tenant_id,sender_id,agent_id,created_at,updated_at)
+      VALUES ('b','room','install-1','tenant-a','sender-1','agent-2','2026-01-02','2026-01-02'),
+             ('a','room','install-1','tenant-a','sender-1','agent-1','2026-01-01','2026-01-01')`);
+    let migrationError: unknown;
+    try {
+      new LocalChannelBindingStore(db);
+    } catch (error) {
+      migrationError = error;
+    }
+    expect(migrationError).toBeInstanceOf(ChannelBindingMigrationConflictError);
+    expect((migrationError as ChannelBindingMigrationConflictError).conflicts).toEqual([{
+      tenantId: "tenant-a", channel: "room", channelInstallationId: "install-1",
+      senderId: "sender-1", count: 2,
+    }]);
+    const duplicates = db.prepare("SELECT id FROM lt_channel_bindings ORDER BY id").all();
+    expect(duplicates).toEqual([{ id: "a" }, { id: "b" }]);
+    const indexes = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'idx_lt_cb_subject_unique'",
+    ).all();
+    expect(indexes).toHaveLength(0);
+  });
+
+  it("persists a disabled initial binding", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    await ensureChannelBindingSubjectIndex(db);
+    await expect(store.create(input({ enabled: false }))).resolves.toMatchObject({ enabled: false });
+  });
+
+  it("supports safe lookup, exclusion, thread persistence, and atomic duplicate create", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    for (let index = 0; index < 60; index += 1) await store.create(input({ senderId: `room-${index}` }));
+    const first = await store.create(input({ channel: "lark", senderId: "public-1" }));
+    await store.create(input({ channel: "slack", senderId: "public-2" }));
+    await store.update("tenant-a", first.id, { enabled: false });
+
+    await expect(store.findById("tenant-b", first.id)).resolves.toBeNull();
+    await expect(store.findBySubject({ ...input({ channel: "lark", senderId: "public-1" }) }))
+      .resolves.toMatchObject({ enabled: false, threadId: "thread-1" });
+    await expect(store.list({ tenantId: "tenant-a", excludeChannels: ["room"], limit: 50 }))
+      .resolves.toHaveLength(2);
+    await expect(store.export({ tenantId: "tenant-a" })).resolves.toHaveLength(2);
+    const results = await Promise.allSettled([
+      store.create(input({ senderId: "duplicate" })), store.create(input({ senderId: "duplicate" })),
+    ]);
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    expect((results.find((result) => result.status === "rejected") as PromiseRejectedResult).reason)
+      .toBeInstanceOf(DuplicateChannelBindingSubjectError);
+  });
+
+  it("excludes internal installation prefixes before SQLite pagination and export", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    for (let index = 0; index < 60; index += 1) {
+      await store.create(input({
+        channel: "lark", channelInstallationId: `room-internal:project-${index}`,
+        senderId: `mixed-${index}`,
+      }));
+    }
+    await store.create(input({ channel: "lark", channelInstallationId: "public-1", senderId: "public-1" }));
+    await store.create(input({ channel: "slack", channelInstallationId: "public-2", senderId: "public-2" }));
+    await expect(store.list({
+      tenantId: "tenant-a", excludeInstallationIdPrefixes: ["room-internal:"], limit: 50,
+    })).resolves.toHaveLength(2);
+    await expect(store.export({ tenantId: "tenant-a" })).resolves.toHaveLength(2);
+  });
+
+  it.each(["room", "lark"])("atomically enforces global %s subject uniqueness", async (channel) => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    const results = await Promise.allSettled([
+      store.create(input({ channel })), store.create(input({ channel })),
+    ]);
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    expect((results.find((result) => result.status === "rejected") as PromiseRejectedResult).reason)
+      .toBeInstanceOf(DuplicateChannelBindingSubjectError);
+  });
+
+  it("scopes update and delete by tenant and ignores runtime immutable fields", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    const created = await store.create(input({ channel: "lark" }));
+    await expect(store.update("tenant-b", created.id, { agentId: "agent-2" })).rejects.toThrow(/not found/i);
+    await store.update("tenant-a", created.id, {
+      agentId: "agent-2", channel: "room", tenantId: "tenant-b",
+    } as unknown as BindingMutablePatch);
+    await expect(store.findById("tenant-a", created.id)).resolves.toMatchObject({
+      channel: "lark", tenantId: "tenant-a", agentId: "agent-2",
+    });
+    await store.delete("tenant-b", created.id);
+    await expect(store.findById("tenant-a", created.id)).resolves.not.toBeNull();
+    await store.delete("tenant-a", created.id);
+    await expect(store.findById("tenant-a", created.id)).resolves.toBeNull();
+  });
+
+  it("does not rollback after commit when persistence fails", () => {
+    const saveError = new Error("disk full");
+    const exec = jest.fn();
+    const wrapper = {
+      exec,
+      prepare: jest.fn().mockReturnValue({ all: jest.fn().mockReturnValue([]) }),
+      save: jest.fn(() => { throw saveError; }),
+    } as unknown as DatabaseWrapper;
+
+    expect(() => ensureChannelBindingSubjectIndex(wrapper)).toThrow(saveError);
+    expect(exec.mock.calls.map(([sql]) => sql)).toEqual([
+      "BEGIN", "DROP INDEX IF EXISTS idx_lt_cb_room_subject",
+      expect.stringContaining("CREATE UNIQUE INDEX"),
+      expect.stringContaining("CREATE INDEX"), "COMMIT",
+    ]);
+  });
+
+  it("rolls back an uncommitted index failure and preserves the original error", () => {
+    const createError = new Error("index failure");
+    const exec = jest.fn((sql: string) => {
+      if (sql.includes("CREATE UNIQUE INDEX")) throw createError;
+    });
+    const wrapper = {
+      exec,
+      prepare: jest.fn().mockReturnValue({ all: jest.fn().mockReturnValue([]) }),
+      save: jest.fn(),
+    } as unknown as DatabaseWrapper;
+
+    expect(() => ensureChannelBindingSubjectIndex(wrapper)).toThrow(createError);
+    expect(exec).toHaveBeenLastCalledWith("ROLLBACK");
+    expect(wrapper.save).not.toHaveBeenCalled();
+  });
+
+  it("rejects room imports before the first write", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    await expect(store.import("tenant-a", [input({ channel: "lark" }), input()])).rejects.toThrow(/room/i);
+    await expect(store.list({ tenantId: "tenant-a" })).resolves.toHaveLength(0);
+  });
+
+  it("rejects internal installation imports before the first write", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    await expect(store.import("tenant-a", [input({
+      channel: "lark", channelInstallationId: "room-internal:project-1",
+    })])).rejects.toThrow(/internal/i);
+    await expect(store.list({ tenantId: "tenant-a" })).resolves.toHaveLength(0);
+  });
+
+  it("rejects cross-tenant imports before the first write", async () => {
+    db = await initDatabase({ dbPath: dbPath() });
+    const store = new LocalChannelBindingStore(db);
+    await expect(store.import("tenant-a", [input({ channel: "lark", tenantId: "tenant-b" })]))
+      .rejects.toThrow(/tenant mismatch/i);
+    await expect(store.list({ tenantId: "tenant-b" })).resolves.toHaveLength(0);
+  });
+});

package/src/__tests__/LocalChannelInstallationStore.test.ts

@@ -19,6 +19,16 @@ describe("LocalChannelInstallationStore", () => {
     closeDatabase();
   });
 
+  it("persists room installations with a plain record config", async () => {
+    await expect(store.createInstallation("tenant-a", "room-install", {
+      channel: "room",
+      config: {},
+    })).resolves.toMatchObject({
+      channel: "room",
+      config: {},
+    });
+  });
+
   it("rejects a duplicate id without changing the original installation", async () => {
     const original = await store.createInstallation("tenant-a", "install-1", {
       channel: "lark",
@@ -35,4 +45,17 @@ describe("LocalChannelInstallationStore", () => {
     ).rejects.toThrow();
     await expect(store.getInstallationById("install-1")).resolves.toEqual(original);
   });
+
+  it("does not update an installation owned by another tenant", async () => {
+    const original = await store.createInstallation("tenant-a", "install-1", {
+      channel: "lark",
+      name: "Original",
+      config: { appId: "app-1", appSecret: "secret-1" },
+    });
+
+    await expect(store.updateInstallation("tenant-b", "install-1", {
+      name: "Cross-tenant update",
+    })).resolves.toBeNull();
+    await expect(store.getInstallationById("install-1")).resolves.toEqual(original);
+  });
 });