@axiom-lattice/pg-stores 3.1.16 → 3.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "3.1.16",
+  "version": "3.1.18",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,8 +25,8 @@
     "@langchain/core": "1.1.30",
     "pg": "^8.16.3",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "4.2.16",
-    "@axiom-lattice/protocols": "4.3.1"
+    "@axiom-lattice/core": "4.3.0",
+    "@axiom-lattice/protocols": "4.4.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/ChannelIdentityMappingStore.test.ts

@@ -1,6 +1,7 @@
 import { ChannelIdentityMappingStore } from "../stores/ChannelIdentityMappingStore";
 
 const mockQuery = jest.fn();
+const mockMigrate = jest.fn();
 
 jest.mock("pg", () => ({
   Pool: jest.fn().mockImplementation(() => ({
@@ -8,9 +9,17 @@ jest.mock("pg", () => ({
   })),
 }));
 
+jest.mock("../migrations/migration", () => ({
+  MigrationManager: jest.fn().mockImplementation(() => ({
+    register: jest.fn(),
+    migrate: mockMigrate,
+  })),
+}));
+
 describe("ChannelIdentityMappingStore", () => {
   beforeEach(() => {
     jest.clearAllMocks();
+    mockMigrate.mockResolvedValue(undefined);
   });
 
   it("creates and retrieves a mapping by external subject key", async () => {

package/src/__tests__/MenuStore.mcpApp.integration.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "@jest/globals";
+import { MenuStore } from "../stores/MenuStore";
+
+const databaseUrl = process.env.TEST_DATABASE_URL;
+const describeIfDatabase = databaseUrl ? describe : describe.skip;
+
+describeIfDatabase("MenuStore mcpApp content type (live PG)", () => {
+  it("persists an mcpApp menu item after the constraint is broadened", async () => {
+    const store = new MenuStore({ poolConfig: databaseUrl as string });
+    await store.initialize();
+    const tenantId = `menu-mcpapp-it-${Date.now()}`;
+    let createdId: string | undefined;
+    try {
+      const item = await store.create({
+        tenantId,
+        menuTarget: "workspace",
+        name: "Monitor",
+        sortOrder: 0,
+        contentType: "mcpApp",
+        contentConfig: { kind: "mcp", serverKey: "srv", resourceUri: "ui://srv/a.html" },
+      });
+      createdId = item.id;
+      expect(item.contentType).toBe("mcpApp");
+      expect(item.contentConfig).toEqual({ kind: "mcp", serverKey: "srv", resourceUri: "ui://srv/a.html" });
+    } finally {
+      if (createdId) {
+        try {
+          await store.delete(createdId);
+        } catch {
+          // best-effort cleanup
+        }
+      }
+      await store.dispose();
+    }
+  });
+});

package/src/__tests__/MenuStore.migrations.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, jest } from "@jest/globals";
+
+const registeredMigrationNames: string[] = [];
+
+jest.mock("@axiom-lattice/core", () => ({}));
+
+jest.mock("pg", () => ({
+  Pool: class Pool {},
+}));
+
+jest.mock("../migrations/migration", () => ({
+  MigrationManager: class MigrationManager {
+    register(migration: { name: string }): void {
+      registeredMigrationNames.push(migration.name);
+    }
+    async migrate(): Promise<void> {
+      throw new Error("stop after migrations");
+    }
+  },
+}));
+
+import { createPgStoreConfig } from "../createPgStoreConfig";
+import { addMcpAppContentType } from "../migrations/menu_items_add_mcp_app_type";
+
+describe("menu mcpApp content-type migration", () => {
+  it("has a free version and is centrally registered exactly once", async () => {
+    expect(addMcpAppContentType.version).toBe(181);
+    expect(addMcpAppContentType.name).toBe("add_mcp_app_content_type_to_menu_items");
+
+    registeredMigrationNames.length = 0;
+    await expect(createPgStoreConfig("postgres://unused")).rejects.toThrow("stop after migrations");
+
+    expect(registeredMigrationNames).toContain(addMcpAppContentType.name);
+    expect(
+      registeredMigrationNames.filter((n) => n === addMcpAppContentType.name)
+    ).toHaveLength(1);
+  });
+});

package/src/__tests__/PostgreSQLCapabilityBundleStore.test.ts

@@ -58,7 +58,7 @@ describe("PostgreSQLCapabilityBundleStore", () => {
     await expect(store.listByTenant("tenant-1")).resolves.toHaveLength(1);
     await expect(store.getById("tenant-1", row.id)).resolves.toMatchObject({ id: row.id });
     await expect(store.getManyByIds("tenant-1", [row.id])).resolves.toHaveLength(1);
-    const updated = await store.update("tenant-1", row.id, { name: "Updated" });
+    const updated = await store.update("tenant-1", row.id, { name: "Updated", expectedUpdatedAt: now.toISOString() });
     expect(updated).toMatchObject({ id: row.id, createdAt: now.toISOString(), name: "Updated" });
     expect("delete" in store).toBe(false);
 
@@ -73,17 +73,17 @@ describe("PostgreSQLCapabilityBundleStore", () => {
     })).rejects.toThrow("Capability bundle key already exists for tenant");
   });
 
-  it("normalizes PostgreSQL unique violations raised while updating a key", async () => {
+  it("normalizes PostgreSQL unique violations raised while updating a bundle", async () => {
     mockQuery.mockRejectedValueOnce(Object.assign(new Error("duplicate"), { code: "23505" }));
     const store = new PostgreSQLCapabilityBundleStore({ pool });
 
-    await expect(store.update("tenant-1", row.id, { key: "existing-key" })).rejects.toThrow(
+    await expect(store.update("tenant-1", row.id, { name: "Renamed", expectedUpdatedAt: now.toISOString() })).rejects.toThrow(
       "Capability bundle key already exists for tenant",
     );
   });
 
   it("uses exact updated_at CAS and distinguishes a stale update", async () => {
-    mockQuery.mockResolvedValueOnce({ rows: [] });
+    mockQuery.mockResolvedValueOnce({ rows: [] }).mockResolvedValueOnce({ rows: [{ id: row.id }] });
     const store = new PostgreSQLCapabilityBundleStore({ pool });
     await expect(store.update("tenant-1", row.id, { name: "Stale", expectedUpdatedAt: "2026-08-27T12:00:00.000Z" }))
       .resolves.toEqual({ status: "conflict" });
@@ -94,7 +94,10 @@ describe("PostgreSQLCapabilityBundleStore", () => {
   });
 
   it("checks CAS tokens for no-op updates", async () => {
-    mockQuery.mockResolvedValueOnce({ rows: [] }).mockResolvedValueOnce({ rows: [row] });
+    mockQuery
+      .mockResolvedValueOnce({ rows: [] })
+      .mockResolvedValueOnce({ rows: [{ id: row.id }] })
+      .mockResolvedValueOnce({ rows: [row] });
     const store = new PostgreSQLCapabilityBundleStore({ pool });
 
     await expect(store.update("tenant-1", row.id, { expectedUpdatedAt: "stale" }))
@@ -104,6 +107,22 @@ describe("PostgreSQLCapabilityBundleStore", () => {
     expect(mockQuery.mock.calls[0][0]).toContain("updated_at::text");
   });
 
+  it("refuses an update that omits the required expected revision", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ id: row.id }] });
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+
+    await expect(store.update("tenant-1", row.id, { name: "Unsaved" } as never))
+      .resolves.toEqual({ status: "conflict" });
+    expect(mockQuery.mock.calls[0][0]).toContain("SELECT id FROM lattice_capability_bundles");
+  });
+
+  it("returns null for a missing bundle when the expected revision is omitted", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [] });
+    const store = new PostgreSQLCapabilityBundleStore({ pool });
+
+    await expect(store.update("tenant-1", "missing", { name: "Unsaved" } as never)).resolves.toBeNull();
+  });
+
   it.each([
     [[], [], "not_found"],
     [[{ exists: 1 }], [], "in_use"],

package/src/createPgStoreConfig.ts

@@ -74,6 +74,7 @@ import { addShareOpenGrants } from "./migrations/add_share_open_grants";
 import { taskMigrations } from "./migrations/task_migration";
 import { createMenuItemsTable } from "./migrations/menu_items_migration";
 import { addFileContentType } from "./migrations/menu_items_add_file_type";
+import { addMcpAppContentType } from "./migrations/menu_items_add_mcp_app_type";
 import { createSharedResourcesTable } from "./migrations/shared_resources_migration";
 import { createCollectionsTable } from "./migrations/collection_migrations";
 import {
@@ -148,6 +149,7 @@ export async function createPgStoreConfig(connectionString: string) {
   mm.register(createMenuItemsTable);             // v134
   mm.register(createSharedResourcesTable);       // v135
   mm.register(addFileContentType);               // v136
+  mm.register(addMcpAppContentType);             // v181
   mm.register(createCollectionsTable);           // v137
   mm.register(createTaskWorkItemsMigration);      // v138
   mm.register(addWorkItemProjectFieldsMigration); // v140

package/src/index.ts

@@ -67,6 +67,7 @@ export * from "./stores/PostgreSQLEvalStore";
 export * from "./migrations/eval_migrations";
 export * from "./migrations/menu_items_migration";
 export * from "./migrations/menu_items_add_file_type";
+export * from "./migrations/menu_items_add_mcp_app_type";
 export * from "./migrations/collection_migrations";
 export * from "./stores/MenuStore";
 export * from "./stores/SharedResourceStore";

package/src/migrations/__tests__/menu_items_add_mcp_app_type.test.ts

@@ -0,0 +1,30 @@
+import type { PoolClient } from "pg";
+import { addMcpAppContentType } from "../menu_items_add_mcp_app_type";
+
+function recordingClient(): { client: PoolClient; queries: string[] } {
+  const queries: string[] = [];
+  const client = {
+    query: async (sql: string) => {
+      queries.push(sql);
+    },
+  } as unknown as PoolClient;
+  return { client, queries };
+}
+
+describe("addMcpAppContentType migration", () => {
+  it("broadens the constraint to include 'mcpApp'", async () => {
+    const { client, queries } = recordingClient();
+    await addMcpAppContentType.up(client);
+    const sql = queries.join("\n");
+    expect(sql).toContain("lattice_menu_items_content_type_check");
+    expect(sql).toContain("'mcpApp'");
+  });
+
+  it("down re-adds the previous set without 'mcpApp'", async () => {
+    const { client, queries } = recordingClient();
+    await addMcpAppContentType.down!(client);
+    const sql = queries.join("\n");
+    expect(sql).toContain("'file'");
+    expect(sql).not.toContain("'mcpApp'");
+  });
+});

package/src/migrations/menu_items_add_mcp_app_type.ts

@@ -0,0 +1,29 @@
+import { PoolClient } from "pg";
+import { Migration } from "./migration";
+
+export const addMcpAppContentType: Migration = {
+  version: 181,
+  name: "add_mcp_app_content_type_to_menu_items",
+  up: async (client: PoolClient) => {
+    await client.query(`
+      ALTER TABLE lattice_menu_items
+      DROP CONSTRAINT IF EXISTS lattice_menu_items_content_type_check
+    `);
+    await client.query(`
+      ALTER TABLE lattice_menu_items
+      ADD CONSTRAINT lattice_menu_items_content_type_check
+      CHECK (content_type IN ('agent', 'html', 'custom', 'file', 'mcpApp'))
+    `);
+  },
+  down: async (client: PoolClient) => {
+    await client.query(`
+      ALTER TABLE lattice_menu_items
+      DROP CONSTRAINT IF EXISTS lattice_menu_items_content_type_check
+    `);
+    await client.query(`
+      ALTER TABLE lattice_menu_items
+      ADD CONSTRAINT lattice_menu_items_content_type_check
+      CHECK (content_type IN ('agent', 'html', 'custom', 'file'))
+    `);
+  },
+};

package/src/stores/MenuStore.ts

@@ -10,6 +10,7 @@ import type {
 import { MigrationManager } from "../migrations/migration";
 import { createMenuItemsTable } from "../migrations/menu_items_migration";
 import { addFileContentType } from "../migrations/menu_items_add_file_type";
+import { addMcpAppContentType } from "../migrations/menu_items_add_mcp_app_type";
 
 export interface MenuStoreOptions {
   pool?: Pool;
@@ -58,6 +59,7 @@ export class MenuStore implements MenuRegistry {
     this.migrationManager = new MigrationManager(this.pool);
     this.migrationManager.register(createMenuItemsTable);
     this.migrationManager.register(addFileContentType);
+    this.migrationManager.register(addMcpAppContentType);
 
     if (options.autoMigrate !== false) {
       this.initialize().catch((error) => {

package/src/stores/PostgreSQLCapabilityBundleStore.ts

@@ -201,6 +201,10 @@ export class PostgreSQLCapabilityBundleStore implements CapabilityBundleStore {
     input: InternalUpdateCapabilityBundleInput,
   ): Promise<CapabilityBundle | { status: "conflict" } | null> {
     await this.ready();
+    const expectedUpdatedAt = input.expectedUpdatedAt;
+    if (typeof expectedUpdatedAt !== "string" || expectedUpdatedAt.trim().length === 0) {
+      return this.resolveCasMiss(tenantId, id);
+    }
     const fields: string[] = [];
     const values: unknown[] = [];
     const add = (field: string, value: unknown): void => {
@@ -215,39 +219,52 @@ export class PostgreSQLCapabilityBundleStore implements CapabilityBundleStore {
       add("capabilities", JSON.stringify(input.capabilities));
     }
     if (fields.length === 0) {
-      const expectedUpdatedAt = input.expectedUpdatedAt;
       const result = await this.pool.query<Row>(
         `SELECT id, tenant_id, bundle_key, name, description, capabilities, created_at, updated_at::text AS updated_at
          FROM lattice_capability_bundles
-         WHERE tenant_id = $1 AND id = $2${expectedUpdatedAt === undefined ? "" : " AND updated_at::text = $3"}`,
-        expectedUpdatedAt === undefined ? [tenantId, id] : [tenantId, id, expectedUpdatedAt],
+         WHERE tenant_id = $1 AND id = $2 AND updated_at::text = $3`,
+        [tenantId, id, expectedUpdatedAt],
       );
       if (result.rows[0]) return map(result.rows[0]);
-      return expectedUpdatedAt === undefined ? null : { status: "conflict" };
+      return this.resolveCasMiss(tenantId, id);
     }
 
-     const expectedUpdatedAt = input.expectedUpdatedAt;
-     values.push(tenantId, id);
-     if (expectedUpdatedAt !== undefined) values.push(expectedUpdatedAt);
-     const tenantParam = values.length - (expectedUpdatedAt === undefined ? 1 : 2);
-     const idParam = tenantParam + 1;
-     const revisionPredicate = expectedUpdatedAt === undefined ? "" : ` AND updated_at::text = $${values.length}`;
+    values.push(tenantId, id, expectedUpdatedAt);
+    const tenantParam = values.length - 2;
+    const idParam = tenantParam + 1;
+    const revisionParam = values.length;
     try {
       const result = await this.pool.query<Row>(
-         `UPDATE lattice_capability_bundles
-          SET ${fields.join(", ")}, updated_at = GREATEST(updated_at + interval '1 microsecond', clock_timestamp())
-          WHERE tenant_id = $${tenantParam} AND id = $${idParam}${revisionPredicate}
+        `UPDATE lattice_capability_bundles
+         SET ${fields.join(", ")}, updated_at = GREATEST(updated_at + interval '1 microsecond', clock_timestamp())
+         WHERE tenant_id = $${tenantParam} AND id = $${idParam} AND updated_at::text = $${revisionParam}
          RETURNING id, tenant_id, bundle_key, name, description, capabilities, created_at, updated_at::text AS updated_at`,
         values,
       );
-       if (result.rows[0]) return map(result.rows[0]);
-       return expectedUpdatedAt === undefined ? null : { status: "conflict" };
+      if (result.rows[0]) return map(result.rows[0]);
+      return this.resolveCasMiss(tenantId, id);
     } catch (error) {
       if (isDuplicate(error)) throw new Error(duplicateMessage);
       throw error;
     }
   }
 
+  /**
+   * Distinguishes a stale-revision CAS miss from a missing bundle.
+   *
+   * @returns `null` when no such bundle exists, otherwise a conflict marker.
+   */
+  private async resolveCasMiss(
+    tenantId: string,
+    id: string,
+  ): Promise<{ status: "conflict" } | null> {
+    const result = await this.pool.query<{ id: string }>(
+      "SELECT id FROM lattice_capability_bundles WHERE tenant_id = $1 AND id = $2",
+      [tenantId, id],
+    );
+    return result.rows[0] ? { status: "conflict" } : null;
+  }
+
   async deleteIfUnreferenced(tenantId: string, id: string): Promise<CapabilityBundleDeleteResult> {
     await this.ready();
     const client = await this.pool.connect();