@axiom-lattice/pg-stores 3.3.3 → 3.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "3.3.3",
+  "version": "3.3.4",
   "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": "6.3.3",
-    "@axiom-lattice/protocols": "4.7.1"
+    "@axiom-lattice/core": "6.4.0",
+    "@axiom-lattice/protocols": "4.8.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/PostgreSQLPluginDeploymentStore.test.ts

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, beforeAll, describe, expect, it } from "@jest/globals";
+import { Pool } from "pg";
+import type { PluginDeployment } from "@axiom-lattice/protocols";
+
+import { MigrationManager } from "../migrations/migration";
+import {
+  createPluginDeployments,
+  dropPluginDeploymentAuthToken,
+} from "../migrations/plugin_deployment_migration";
+import { PostgreSQLPluginDeploymentStore } from "../stores/PostgreSQLPluginDeploymentStore";
+
+const databaseUrl = process.env.TEST_DATABASE_URL;
+const describeIfDatabase = databaseUrl ? describe : describe.skip;
+
+function record(
+  tenantId: string,
+  pluginType: string,
+  overrides: Partial<PluginDeployment> = {},
+): PluginDeployment {
+  const now = new Date().toISOString();
+  return {
+    id: randomUUID(),
+    tenantId,
+    pluginType,
+    pluginVersion: "1.0.0",
+    mode: "onDemand",
+    status: "running",
+    provider: "microsandbox-remote",
+    sandboxName: `plugin-${pluginType}`,
+    port: 8080,
+    idleTimeoutMs: 600_000,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+describeIfDatabase("PostgreSQLPluginDeploymentStore", () => {
+  let pool: Pool;
+  let store: PostgreSQLPluginDeploymentStore;
+  const tenantId = `plugin-deploy-${randomUUID()}`;
+  const otherTenantId = `plugin-deploy-${randomUUID()}`;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    const mm = new MigrationManager(pool);
+    mm.register(createPluginDeployments);
+    mm.register(dropPluginDeploymentAuthToken);
+    await mm.migrate();
+    store = new PostgreSQLPluginDeploymentStore({ pool });
+  });
+
+  afterAll(async () => {
+    await pool.query("DELETE FROM lattice_plugin_deployments WHERE tenant_id = ANY($1)", [
+      [tenantId, otherTenantId],
+    ]);
+    await pool.end();
+  });
+
+  it("upserts and gets a deployment", async () => {
+    const saved = await store.upsert(record(tenantId, "weather"));
+    expect(saved.pluginType).toBe("weather");
+
+    const got = await store.get(tenantId, "weather");
+    expect(got?.pluginType).toBe("weather");
+    expect(await store.get(tenantId, "missing")).toBeUndefined();
+  });
+
+  it("preserves id and createdAt on conflict while applying mutable fields", async () => {
+    const first = await store.upsert(record(tenantId, "conflict", { status: "requested" }));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    const second = await store.upsert({
+      ...record(tenantId, "conflict"),
+      id: randomUUID(),
+      status: "running",
+      pluginVersion: "2.0.0",
+    });
+    expect(second.id).toBe(first.id);
+    expect(second.createdAt).toBe(first.createdAt);
+    expect(second.status).toBe("running");
+    expect(second.pluginVersion).toBe("2.0.0");
+    expect(second.updatedAt).not.toBe(first.updatedAt);
+  });
+
+  it("maps NULL optional columns to undefined", async () => {
+    await store.upsert(record(tenantId, "nulls"));
+    const got = await store.get(tenantId, "nulls");
+    expect(got?.endpoint).toBeUndefined();
+    expect(got?.imageRef).toBeUndefined();
+    expect(got?.lastHealthAt).toBeUndefined();
+    expect(got?.lastError).toBeUndefined();
+  });
+
+  it("patches allowed fields and returns undefined for missing rows", async () => {
+    await store.upsert(record(tenantId, "patch"));
+    const updated = await store.updateStatus(tenantId, "patch", {
+      status: "paused",
+      mode: "alwaysOn",
+      endpoint: "srv:1",
+      imageRef: "img:1",
+      lastHealthAt: "2026-01-02T00:00:00.000Z",
+      lastError: "boom",
+      pluginVersion: "1.2.0",
+      provider: "opensandbox",
+      sandboxName: "plugin-patch-2",
+      port: 9090,
+      idleTimeoutMs: 1000,
+    });
+    expect(updated?.status).toBe("paused");
+    expect(updated?.mode).toBe("alwaysOn");
+    expect(updated?.endpoint).toBe("srv:1");
+    expect(updated?.imageRef).toBe("img:1");
+    expect(updated?.lastHealthAt).toBe("2026-01-02T00:00:00.000Z");
+    expect(updated?.lastError).toBe("boom");
+    expect(updated?.pluginVersion).toBe("1.2.0");
+    expect(updated?.provider).toBe("opensandbox");
+    expect(updated?.sandboxName).toBe("plugin-patch-2");
+    expect(updated?.port).toBe(9090);
+    expect(updated?.idleTimeoutMs).toBe(1000);
+
+    expect(await store.updateStatus(tenantId, "nope", { status: "paused" })).toBeUndefined();
+  });
+
+  it("isolates tenants, lists ordered by plugin type, and deletes", async () => {
+    await store.upsert(record(tenantId, "list-b"));
+    await store.upsert(record(tenantId, "list-a"));
+    await store.upsert(record(otherTenantId, "list-a"));
+
+    const listed = (await store.listByTenant(tenantId)).filter((entry) =>
+      entry.pluginType.startsWith("list-"),
+    );
+    expect(listed.map((entry) => entry.pluginType)).toEqual(["list-a", "list-b"]);
+    expect((await store.listByTenant(otherTenantId)).every((entry) => entry.tenantId === otherTenantId)).toBe(true);
+
+    expect(await store.delete(tenantId, "list-a")).toBe(true);
+    expect(await store.delete(tenantId, "list-a")).toBe(false);
+  });
+});

package/src/createPgStoreConfig.ts

@@ -87,6 +87,10 @@ import { addProjectRoomMessageRetentionIndex } from "./migrations/project_room_m
 import { createUserPushSubscriptions } from "./migrations/user_push_subscription_migration";
 import { createDistributedLeases } from "./migrations/distributed_lease_migration";
 import { createOutboxTable } from "./migrations/outbox_migration";
+import {
+  createPluginDeployments,
+  dropPluginDeploymentAuthToken,
+} from "./migrations/plugin_deployment_migration";
 import {
   createModelProvidersTable,
   createModelProviderModelsTable,
@@ -103,6 +107,7 @@ import { PostgreSQLUserPushSubscriptionStore } from "./stores/PostgreSQLUserPush
 import { PostgreSQLModelProviderStore } from "./stores/PostgreSQLModelProviderStore";
 import { PostgreSQLLeaseStore } from "./stores/PostgreSQLLeaseStore";
 import { PostgreSQLOutboxStore } from "./stores/PostgreSQLOutboxStore";
+import { PostgreSQLPluginDeploymentStore } from "./stores/PostgreSQLPluginDeploymentStore";
 
 export async function createPgStoreConfig(connectionString: string) {
   const pool = new Pool({ connectionString });
@@ -179,6 +184,8 @@ export async function createPgStoreConfig(connectionString: string) {
   mm.register(createDistributedLeases);        // v185
   mm.register(createOutboxTable);              // v187
   mm.register(addConnectionSecretFields);      // v188
+  mm.register(createPluginDeployments);        // v189
+  mm.register(dropPluginDeploymentAuthToken);  // v190
 
   await mm.migrate();
 
@@ -227,6 +234,7 @@ export async function createPgStoreConfig(connectionString: string) {
     userPushSubscription: new PostgreSQLUserPushSubscriptionStore(opts),
     lease: new PostgreSQLLeaseStore(opts),
     outbox: new PostgreSQLOutboxStore(opts),
+    pluginDeployment: new PostgreSQLPluginDeploymentStore(opts),
     vectorStoreProvider: new PGVectorStoreProvider(pool, connectionString),
     checkpoint,
   };

package/src/index.ts

@@ -80,6 +80,8 @@ export * from "./stores/PostgreSQLProjectBotMembershipStore";
 export * from "./stores/PostgreSQLProjectRoomMessageStore";
 export * from "./stores/PostgreSQLProjectRoomReadStateStore";
 export * from "./migrations/project_room_migration";
+export * from "./stores/PostgreSQLPluginDeploymentStore";
+export * from "./migrations/plugin_deployment_migration";
 
 export * from "./PGVectorStoreProvider";
 

package/src/migrations/plugin_deployment_migration.ts

@@ -0,0 +1,67 @@
+import type { Migration } from "./migration";
+
+/** Creates the durable plugin-deployment table. */
+export const createPluginDeployments: Migration = {
+  version: 189,
+  name: "create_plugin_deployments",
+  up: async (client) => {
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS lattice_plugin_deployments (
+        id VARCHAR(255) PRIMARY KEY,
+        tenant_id VARCHAR(255) NOT NULL,
+        plugin_type VARCHAR(255) NOT NULL,
+        plugin_version VARCHAR(255) NOT NULL,
+        mode VARCHAR(16) NOT NULL,
+        status VARCHAR(32) NOT NULL,
+        provider VARCHAR(64) NOT NULL,
+        sandbox_name VARCHAR(255) NOT NULL,
+        port INTEGER NOT NULL,
+        endpoint TEXT,
+        image_ref TEXT,
+        auth_token TEXT NOT NULL,
+        idle_timeout_ms INTEGER NOT NULL,
+        last_health_at TIMESTAMPTZ,
+        last_error TEXT,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        UNIQUE (tenant_id, plugin_type)
+      )
+    `);
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_lattice_plugin_deployments_tenant
+      ON lattice_plugin_deployments (tenant_id)
+    `);
+  },
+  down: async (client) => {
+    await client.query("DROP INDEX IF EXISTS idx_lattice_plugin_deployments_tenant");
+    await client.query("DROP TABLE IF EXISTS lattice_plugin_deployments");
+  },
+};
+
+/**
+ * Drops the now-unused `auth_token` column introduced by
+ * {@link createPluginDeployments}.
+ *
+ * Resident plugin hosts no longer receive a per-deployment bearer token; the
+ * sandbox service key plus loopback transport replace it. This is a separate
+ * migration (rather than editing v189 in place) because migration identity is
+ * the name: databases that already applied the released v189 keep its
+ * `auth_token NOT NULL` column, so the token removal must be applied as a new
+ * forward migration.
+ */
+export const dropPluginDeploymentAuthToken: Migration = {
+  version: 190,
+  name: "drop_plugin_deployment_auth_token",
+  up: async (client) => {
+    await client.query(`
+      ALTER TABLE lattice_plugin_deployments
+      DROP COLUMN IF EXISTS auth_token
+    `);
+  },
+  down: async (client) => {
+    await client.query(`
+      ALTER TABLE lattice_plugin_deployments
+      ADD COLUMN IF NOT EXISTS auth_token TEXT NOT NULL DEFAULT ''
+    `);
+  },
+};

package/src/stores/PostgreSQLPluginDeploymentStore.ts

@@ -0,0 +1,189 @@
+import type {
+  PluginDeployment,
+  PluginDeploymentStatus,
+  PluginDeploymentStore,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+type Row = {
+  id: unknown; tenant_id: unknown; plugin_type: unknown; plugin_version: unknown;
+  mode: unknown; status: unknown; provider: unknown; sandbox_name: unknown;
+  port: unknown; endpoint: unknown; image_ref: unknown;
+  idle_timeout_ms: unknown; last_health_at: unknown; last_error: unknown;
+  created_at: unknown; updated_at: unknown;
+};
+
+const columns =
+  "id, tenant_id, plugin_type, plugin_version, mode, status, provider, sandbox_name, " +
+  "port, endpoint, image_ref, idle_timeout_ms, last_health_at, last_error, " +
+  "created_at, updated_at";
+
+const statuses: readonly PluginDeploymentStatus[] = [
+  "requested",
+  "provisioning",
+  "running",
+  "paused",
+  "stopping",
+  "stopped",
+  "failed",
+];
+
+function isStatus(value: unknown): value is PluginDeploymentStatus {
+  return typeof value === "string" && (statuses as readonly string[]).includes(value);
+}
+
+function mapRow(row: Row): PluginDeployment {
+  if (
+    typeof row.id !== "string" ||
+    typeof row.tenant_id !== "string" ||
+    typeof row.plugin_type !== "string" ||
+    typeof row.plugin_version !== "string" ||
+    (row.mode !== "onDemand" && row.mode !== "alwaysOn") ||
+    !isStatus(row.status) ||
+    typeof row.provider !== "string" ||
+    typeof row.sandbox_name !== "string" ||
+    typeof row.port !== "number" ||
+    typeof row.idle_timeout_ms !== "number" ||
+    !(row.created_at instanceof Date) || Number.isNaN(row.created_at.getTime()) ||
+    !(row.updated_at instanceof Date) || Number.isNaN(row.updated_at.getTime())
+  ) {
+    throw new Error("Invalid plugin deployment row");
+  }
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    pluginType: row.plugin_type,
+    pluginVersion: row.plugin_version,
+    mode: row.mode,
+    status: row.status,
+    provider: row.provider,
+    sandboxName: row.sandbox_name,
+    port: row.port,
+    ...(typeof row.endpoint === "string" ? { endpoint: row.endpoint } : {}),
+    ...(typeof row.image_ref === "string" ? { imageRef: row.image_ref } : {}),
+    idleTimeoutMs: row.idle_timeout_ms,
+    ...(row.last_health_at instanceof Date && !Number.isNaN(row.last_health_at.getTime())
+      ? { lastHealthAt: row.last_health_at.toISOString() }
+      : {}),
+    ...(typeof row.last_error === "string" ? { lastError: row.last_error } : {}),
+    createdAt: row.created_at.toISOString(),
+    updatedAt: row.updated_at.toISOString(),
+  };
+}
+
+/** Persists tenant-scoped plugin deployments in PostgreSQL. */
+export class PostgreSQLPluginDeploymentStore implements PluginDeploymentStore {
+  /** Creates a store using an externally managed shared pool. */
+  constructor(options: { pool: Pool }) {
+    this.pool = options.pool;
+  }
+
+  private readonly pool: Pool;
+
+  /** Lists every deployment for a tenant, ordered by plugin type. */
+  async listByTenant(tenantId: string): Promise<PluginDeployment[]> {
+    const result = await this.pool.query<Row>(
+      `SELECT ${columns} FROM lattice_plugin_deployments WHERE tenant_id = $1 ORDER BY plugin_type`,
+      [tenantId],
+    );
+    return result.rows.map(mapRow);
+  }
+
+  /** Returns the deployment for a tenant + plugin type, or undefined. */
+  async get(tenantId: string, pluginType: string): Promise<PluginDeployment | undefined> {
+    const result = await this.pool.query<Row>(
+      `SELECT ${columns} FROM lattice_plugin_deployments WHERE tenant_id = $1 AND plugin_type = $2`,
+      [tenantId, pluginType],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : undefined;
+  }
+
+  /** Upserts a deployment keyed by tenant + plugin type, preserving the original id and createdAt. */
+  async upsert(deployment: PluginDeployment): Promise<PluginDeployment> {
+    const result = await this.pool.query<Row>(
+      `INSERT INTO lattice_plugin_deployments (${columns})
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
+       ON CONFLICT (tenant_id, plugin_type) DO UPDATE SET
+         plugin_version = EXCLUDED.plugin_version,
+         mode = EXCLUDED.mode,
+         status = EXCLUDED.status,
+         provider = EXCLUDED.provider,
+         sandbox_name = EXCLUDED.sandbox_name,
+         port = EXCLUDED.port,
+         endpoint = EXCLUDED.endpoint,
+         image_ref = EXCLUDED.image_ref,
+         idle_timeout_ms = EXCLUDED.idle_timeout_ms,
+         last_health_at = EXCLUDED.last_health_at,
+         last_error = EXCLUDED.last_error,
+         updated_at = NOW()
+       RETURNING ${columns}`,
+      [
+        deployment.id,
+        deployment.tenantId,
+        deployment.pluginType,
+        deployment.pluginVersion,
+        deployment.mode,
+        deployment.status,
+        deployment.provider,
+        deployment.sandboxName,
+        deployment.port,
+        deployment.endpoint ?? null,
+        deployment.imageRef ?? null,
+        deployment.idleTimeoutMs,
+        deployment.lastHealthAt ? new Date(deployment.lastHealthAt) : null,
+        deployment.lastError ?? null,
+        new Date(deployment.createdAt),
+        new Date(deployment.updatedAt),
+      ],
+    );
+    return mapRow(result.rows[0]);
+  }
+
+  /** Applies a partial update to mutable columns; returns undefined when no row exists. */
+  async updateStatus(
+    tenantId: string,
+    pluginType: string,
+    patch: Partial<Omit<PluginDeployment, "id" | "tenantId" | "pluginType">>,
+  ): Promise<PluginDeployment | undefined> {
+    const assignments: string[] = [];
+    const params: unknown[] = [];
+    const assign = (column: string, value: unknown): void => {
+      params.push(value);
+      assignments.push(`${column} = $${params.length}`);
+    };
+
+    if (patch.status !== undefined) assign("status", patch.status);
+    if (patch.mode !== undefined) assign("mode", patch.mode);
+    if (patch.endpoint !== undefined) assign("endpoint", patch.endpoint);
+    if (patch.imageRef !== undefined) assign("image_ref", patch.imageRef);
+    if (patch.idleTimeoutMs !== undefined) assign("idle_timeout_ms", patch.idleTimeoutMs);
+    if (patch.lastHealthAt !== undefined) assign("last_health_at", new Date(patch.lastHealthAt));
+    if (patch.lastError !== undefined) assign("last_error", patch.lastError);
+    if (patch.pluginVersion !== undefined) assign("plugin_version", patch.pluginVersion);
+    if (patch.provider !== undefined) assign("provider", patch.provider);
+    if (patch.sandboxName !== undefined) assign("sandbox_name", patch.sandboxName);
+    if (patch.port !== undefined) assign("port", patch.port);
+    assignments.push("updated_at = NOW()");
+
+    params.push(tenantId, pluginType);
+    const tenantParam = params.length - 1;
+    const pluginParam = params.length;
+
+    const result = await this.pool.query<Row>(
+      `UPDATE lattice_plugin_deployments SET ${assignments.join(", ")}
+       WHERE tenant_id = $${tenantParam} AND plugin_type = $${pluginParam}
+       RETURNING ${columns}`,
+      params,
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : undefined;
+  }
+
+  /** Deletes a deployment by tenant + plugin type; returns whether a row was removed. */
+  async delete(tenantId: string, pluginType: string): Promise<boolean> {
+    const result = await this.pool.query(
+      `DELETE FROM lattice_plugin_deployments WHERE tenant_id = $1 AND plugin_type = $2`,
+      [tenantId, pluginType],
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+}