@checkstack/backend 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @checkstack/backend
 
+## 0.13.0
+
+### Minor Changes
+
+- af6bda7: Fix plugin migrations failing on upgrade with `type "..." does not exist`.
+
+  Plugin migrations are schema-agnostic and rely on `search_path` to resolve
+  unqualified names into the plugin's schema (e.g. `plugin_healthcheck`). The
+  loader set `search_path` at the session level on the shared admin pool and
+  then called Drizzle's `migrate()`. Because `migrate()` runs all pending
+  migrations inside its own transaction, a `pg.Pool` could service that
+  transaction on a different physical connection than the one the `SET` ran on,
+  so the migration SQL executed against `public` instead.
+
+  This was invisible on a fresh database (every object is created within that
+  one transaction, so unqualified references still resolve), but broke upgrades:
+  the healthcheck plugin's new `health_check_state_transitions` migration
+  references the pre-existing `health_check_status` enum, which an earlier
+  migration created in the plugin schema. On a different pooled connection that
+  enum is not on the `public` `search_path`, so startup failed with
+  `type "health_check_status" does not exist` and the pod crash-looped.
+
+  Migrations now run on a single pinned pool connection: the loader checks out
+  one dedicated client, sets `search_path` on it, and binds the migrator to that
+  same client, mirroring the connection-affinity pattern already used by the
+  advisory-lock service. Every migration statement now runs under the intended
+  schema.
+
+  Boot was also restructured into two passes over the topologically-sorted
+  plugins: pass 1 runs every plugin's migrations, pass 2 runs every plugin's
+  `init()`. Previously the two were interleaved per plugin, so an
+  already-initialized plugin's background work (queue consumers, sweepers,
+  reactive-entity/event wiring) could compete for pool connections while a later
+  plugin was still migrating. Running all migrations first keeps the pool quiet
+  during migrations and removes that race entirely. The pinned connection and the
+  two-pass ordering are each independently sufficient for the fix above; together
+  they make boot robust regardless of what else touches the pool.
+
+## 0.12.0
+
+### Minor Changes
+
+- 270ef29: Fix automation provider actions and `secretEnv` script actions throwing in production.
+
+  The automation dispatch engine resolved provider-action dependencies (the integration connection store, the secret resolver) through a `getService` that was a throwing stub, so Jira / Teams / Webex actions and `secretEnv` script actions threw at execute time in production. The whole dispatch test suite stubbed `getService`, so the break was invisible.
+
+  Root cause: the plugin `env` exposed `registerService` but no resolver, so the dispatch path (the only context that resolves arbitrary cross-plugin refs outside an RPC handler) had nothing real to call.
+
+  Changes:
+
+  - `@checkstack/backend-api`: add `getService<S>(ref: ServiceRef<S>): Promise<S>` to the plugin `env` (`BackendPluginRegistry`). It resolves a service registered by any plugin through the real `ServiceRegistry` using the calling plugin's identity, and throws a clear error if the ref is not registered (never silently `undefined`). **NEW PLUGIN-AUTHOR CONTRACT**: `env.getService` is now available to resolve arbitrary cross-plugin service refs at init / afterPluginsReady time.
+  - `@checkstack/backend`: implement `env.getService` in both the plugin loader and the runtime single-plugin registration path, backed by `ServiceRegistry.get(ref, { pluginId })`.
+  - `@checkstack/automation-backend`: wire the dispatch `getService` to `env.getService` (was a throwing stub). This also activates run-wide provider-credential masking, because resolving the connection store / secret resolver now flows through the run's masking interceptor.
+
+  Also fixes a test-only seam where the `core/backend` test preload registered a no-op `registerRouter`, silently disabling oRPC router registration across the suite.
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/cache-api@0.3.7
+  - @checkstack/queue-api@0.3.7
+  - @checkstack/signal-backend@0.2.11
+
 ## 0.11.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -14,16 +14,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/api-docs-common": "0.1.14",
-    "@checkstack/auth-common": "0.7.1",
-    "@checkstack/backend-api": "0.17.1",
-    "@checkstack/common": "0.11.0",
+    "@checkstack/api-docs-common": "0.1.15",
+    "@checkstack/auth-common": "0.7.2",
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/common": "0.12.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/cache-api": "0.3.5",
-    "@checkstack/queue-api": "0.3.5",
-    "@checkstack/signal-backend": "0.2.9",
-    "@checkstack/signal-common": "0.2.4",
-    "@checkstack/pluginmanager-common": "0.2.3",
+    "@checkstack/cache-api": "0.3.6",
+    "@checkstack/queue-api": "0.3.6",
+    "@checkstack/signal-backend": "0.2.10",
+    "@checkstack/signal-common": "0.2.5",
+    "@checkstack/pluginmanager-common": "0.2.4",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
@@ -45,8 +45,8 @@
     "@types/bun": "latest",
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3",
-    "@checkstack/test-utils-backend": "0.1.30",
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/test-utils-backend": "0.1.31",
     "drizzle-kit": "^0.31.10"
   }
 }

package/src/plugin-manager/core-services.ts

@@ -9,6 +9,7 @@ import {
   RpcClient,
   EventBus as IEventBus,
   AuthenticationStrategy,
+  createAdvisoryLockService,
 } from "@checkstack/backend-api";
 import { AuthApi } from "@checkstack/auth-common";
 import type { ServiceRegistry } from "../services/service-registry";
@@ -97,6 +98,16 @@ export function registerCoreServices({
     return createScopedDb(db, assignedSchema);
   });
 
+  // 1b. Advisory Lock Factory (server-global, backed by the shared admin
+  // pool). Session locks need connection affinity, so the service checks
+  // out a dedicated client per acquired lock and releases on the SAME
+  // client — the scoped per-query DB proxy can't provide that.
+  const advisoryLockService = createAdvisoryLockService(adminPool);
+  registry.registerFactory(
+    coreServices.advisoryLock,
+    () => advisoryLockService,
+  );
+
   // 2. Logger Factory
   registry.registerFactory(coreServices.logger, (metadata) => {
     return rootLogger.child({ plugin: metadata.pluginId });

package/src/plugin-manager/plugin-loader.getservice.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "bun:test";
+import {
+  createServiceRef,
+  createBackendPlugin,
+  type BackendPluginRegistry,
+  type ServiceRef,
+} from "@checkstack/backend-api";
+import type { AccessRule, PluginMetadata } from "@checkstack/common";
+import { ServiceRegistry } from "../services/service-registry";
+import { createExtensionPointManager } from "./extension-points";
+import { registerPlugin, type PluginLoaderDeps } from "./plugin-loader";
+import type { PendingInit } from "./types";
+import type { AnyContractRouter } from "@orpc/contract";
+
+/**
+ * Framework-level coverage for the plugin `env.getService`, the registry-backed
+ * resolver added so the automation dispatch path can resolve arbitrary
+ * cross-plugin refs (connection store, secret resolver) at execute time.
+ *
+ * Prior to this, `env` exposed `registerService` but NO resolver, so the
+ * dispatch engine stubbed `getService` with a throwing placeholder and every
+ * provider action threw in production. These tests assert `env.getService`
+ * resolves through the REAL `ServiceRegistry` and fails loudly on a missing
+ * ref (never silently `undefined`).
+ */
+
+function makeDeps(registry: ServiceRegistry): PluginLoaderDeps {
+  return {
+    registry,
+    pluginRpcRouters: new Map<string, unknown>(),
+    pluginHttpHandlers: new Map<string, (req: Request) => Promise<Response>>(),
+    extensionPointManager: createExtensionPointManager(),
+    registeredAccessRules: [] as (AccessRule & { pluginId: string })[],
+    getAllAccessRules: () => [],
+    db: {} as PluginLoaderDeps["db"],
+    pluginMetadataRegistry: new Map<string, PluginMetadata>(),
+    cleanupHandlers: new Map<string, Array<() => Promise<void>>>(),
+    pluginContractRegistry: new Map<string, AnyContractRouter>(),
+  };
+}
+
+/**
+ * Register a no-op plugin whose `register` callback captures the `env` so the
+ * test can call `env.getService` the same way a plugin would at init time.
+ */
+function captureEnv(deps: PluginLoaderDeps): BackendPluginRegistry {
+  let captured: BackendPluginRegistry | undefined;
+  const plugin = createBackendPlugin({
+    metadata: { pluginId: "consumer-plugin" },
+    register: (env) => {
+      captured = env;
+    },
+  });
+  const pendingInits: PendingInit[] = [];
+  registerPlugin({
+    backendPlugin: plugin,
+    pluginPath: "/virtual/consumer-plugin",
+    pendingInits,
+    providedBy: new Map<string, string>(),
+    deps,
+  });
+  if (!captured) throw new Error("env was not captured");
+  return captured;
+}
+
+describe("plugin env.getService", () => {
+  it("resolves a service registered by another plugin through the real ServiceRegistry", async () => {
+    const registry = new ServiceRegistry();
+    const ref = createServiceRef<{ ping: () => string }>("other.service");
+    const impl = { ping: () => "pong" };
+    registry.register(ref, impl);
+
+    const env = captureEnv(makeDeps(registry));
+    const resolved = await env.getService(ref);
+
+    expect(resolved).toBe(impl);
+    expect(resolved.ping()).toBe("pong");
+  });
+
+  it("resolves a service the SAME plugin registered via env.registerService", async () => {
+    const registry = new ServiceRegistry();
+    const env = captureEnv(makeDeps(registry));
+    const ref = createServiceRef<{ n: number }>("self.service");
+
+    env.registerService(ref, { n: 42 });
+    const resolved = await env.getService(ref);
+
+    expect(resolved.n).toBe(42);
+  });
+
+  it("throws a clear error (never undefined) when the ref is not registered", async () => {
+    const registry = new ServiceRegistry();
+    const env = captureEnv(makeDeps(registry));
+    const missing: ServiceRef<{ x: number }> =
+      createServiceRef<{ x: number }>("missing.service");
+
+    let error: unknown;
+    try {
+      await env.getService(missing);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain("missing.service");
+    // Consumer identity is THIS plugin (audit / scoped factories).
+    expect((error as Error).message).toContain("consumer-plugin");
+  });
+});

package/src/plugin-manager/plugin-loader.ts

@@ -1,9 +1,7 @@
-import { migrate } from "drizzle-orm/node-postgres/migrator";
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import path from "node:path";
 import fs from "node:fs";
 import type { Hono } from "hono";
-import { eq, and, sql } from "drizzle-orm";
+import { eq, and } from "drizzle-orm";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import {
   coreServices,
@@ -23,6 +21,8 @@ import { rootLogger } from "../logger";
 import type { ServiceRegistry } from "../services/service-registry";
 import { plugins } from "../schema";
 import { stripPublicSchemaFromMigrations } from "../utils/strip-public-schema";
+import { runPluginMigrations } from "../utils/run-plugin-migrations";
+import { adminPool } from "../db";
 import {
   discoverLocalPlugins,
   syncPluginsToDatabase,
@@ -149,6 +149,14 @@ export function registerPlugin({
       providedBy.set(ref.id, pluginId);
       rootLogger.debug(`   -> Registered service '${ref.id}'`);
     },
+    // Registry-backed resolver for arbitrary cross-plugin refs. The
+    // consumer identity is THIS plugin (`pluginId`), which is the correct
+    // audit identity for scoped factories. `registry.get` throws a clear
+    // error when the ref is unregistered, so a missing service (e.g. a
+    // connection store the automation dispatch path needs) fails loudly
+    // rather than silently resolving `undefined`.
+    getService: <T>(ref: ServiceRef<T>): Promise<T> =>
+      deps.registry.get(ref, { pluginId }),
     registerExtensionPoint: (ref, impl) => {
       deps.extensionPointManager.registerExtensionPoint(ref, impl);
     },
@@ -301,6 +309,17 @@ export async function loadPlugins({
   }
 
   // Phase 2: Initialize Plugins (Topological Sort)
+  //
+  // Done in two passes over the topologically-sorted plugins:
+  //   Pass 1 - run EVERY plugin's migrations.
+  //   Pass 2 - resolve deps + run EVERY plugin's init().
+  // Splitting the passes guarantees no plugin's init() (which may start
+  // background DB work - queue consumers, sweepers, reactive-entity/event
+  // wiring) is running while another plugin is still migrating. That
+  // interleaving is what could divert a migration onto a pooled connection
+  // without the plugin's search_path. `runPluginMigrations` pins a connection
+  // too, so each measure is independently sufficient; together they make boot
+  // robust regardless of what touches the pool.
   const logger = await deps.registry.get(coreServices.logger, {
     pluginId: "core",
   });
@@ -339,9 +358,9 @@ export async function loadPlugins({
   // pre-existing behavior and is preferable to a multi-second hang.
   deps.onApiRouteRegistered?.();
 
+  // Phase 2, pass 1: run every plugin's migrations BEFORE any plugin init.
   for (const id of sortedIds) {
     const p = pendingInits.find((x) => x.metadata.pluginId === id)!;
-    rootLogger.info(`🚀 Initializing ${p.metadata.pluginId}...`);
 
     try {
       /**
@@ -364,34 +383,32 @@ export async function loadPlugins({
        * causing "relation does not exist" errors since the tables are actually in
        * the plugin's schema (e.g., `plugin_maintenance.maintenances`).
        *
-       * ## Session-Level vs Transaction-Level search_path
+       * ## Why a pinned connection (not a session-level SET on the pool)
+       *
+       * The migration `search_path` MUST be set on the exact connection the
+       * migration statements run on. Setting it at the session level on the
+       * shared `adminPool` does not achieve that: `migrate()` runs all pending
+       * migrations inside its own transaction, which a `pg.Pool` may service on
+       * a *different* physical connection than the `SET` ran on. The migration
+       * SQL would then execute against `public`.
        *
-       * We use **session-level** `SET search_path` (not `SET LOCAL`) here because:
-       * - `migrate()` runs multiple statements and may manage its own transactions
-       * - `SET LOCAL` only persists within a single transaction
-       * - Session-level SET persists until explicitly changed or session ends
+       * `runPluginMigrations()` therefore checks out ONE dedicated client from
+       * the pool, sets `search_path` on it, and binds the migrator to that same
+       * client - the same connection-affinity pattern the advisory-lock service
+       * uses (see `advisory-lock.ts`). The bug this prevents is invisible on a
+       * fresh database (every object is created in one transaction, so
+       * unqualified references still resolve) but breaks UPGRADES: a new
+       * migration that references an enum an earlier migration created in the
+       * plugin schema fails with `type "..." does not exist`.
        *
        * ## Why This Doesn't Affect Runtime Queries
        *
        * After migrations complete, plugins receive their database via
        * `createScopedDb()` which wraps every query in a transaction with
        * `SET LOCAL search_path`. This ensures runtime queries always use the
-       * correct schema, regardless of the session-level search_path.
-       *
-       * ## Potential Hazards
-       *
-       * 1. **Error During Migration**: If a migration fails, the search_path may
-       *    remain set to that plugin's schema. The next plugin's migration would
-       *    fail visibly (wrong schema), which is better than silent data corruption.
-       *
-       * 2. **Parallel Migration Execution**: This code assumes sequential plugin
-       *    initialization (which is enforced by the topologically-sorted loop).
-       *    If migrations ever run in parallel, search_path conflicts would occur.
-       *
-       * 3. **Connection Pool Pollution**: `SET` without `LOCAL` affects the entire
-       *    session. However, we reset to `public` after each plugin's migrations,
-       *    and runtime queries use `SET LOCAL` anyway, so this is safe.
+       * correct schema.
        *
+       * @see runPluginMigrations in ../utils/run-plugin-migrations.ts
        * @see createScopedDb in ../utils/scoped-db.ts for runtime query isolation
        * @see getPluginSchemaName in @checkstack/drizzle-helper for schema naming
        * =======================================================================
@@ -411,29 +428,13 @@ export async function loadPlugins({
             `   -> Running migrations for ${p.metadata.pluginId} from ${migrationsFolder}`,
           );
 
-          // Create schema if it doesn't exist BEFORE running migrations.
-          // Without this, SET search_path to a non-existent schema causes
-          // PostgreSQL to fall back to 'public', creating tables in the wrong schema.
-          await deps.db.execute(
-            sql.raw(`CREATE SCHEMA IF NOT EXISTS "${migrationsSchema}"`),
-          );
-
-          // Set search_path to plugin schema before running migrations.
-          // Uses session-level SET (not SET LOCAL) because migrate() may run
-          // multiple statements across transaction boundaries.
-          // No 'public' fallback: schema is guaranteed to exist from CREATE above.
-          await deps.db.execute(
-            sql.raw(`SET search_path = "${migrationsSchema}"`),
-          );
-          // Drizzle migrate() requires NodePgDatabase, cast from SafeDatabase
-          await migrate(deps.db as NodePgDatabase<Record<string, unknown>>, {
+          // Run on a single pinned connection so the search_path we set is the
+          // one the migration statements actually execute under.
+          await runPluginMigrations({
+            pool: adminPool,
             migrationsFolder,
             migrationsSchema,
           });
-
-          // Reset search_path to public after migrations complete.
-          // This prevents search_path leaking into subsequent plugin migrations.
-          await deps.db.execute(sql.raw(`SET search_path = public`));
         } catch (error) {
           rootLogger.error(
             `❌ Failed migration of plugin ${p.metadata.pluginId}:`,
@@ -448,7 +449,25 @@ export async function loadPlugins({
           `   -> No migrations found for ${p.metadata.pluginId} (skipping)`,
         );
       }
+    } catch (error) {
+      rootLogger.error(
+        `❌ Critical error loading plugin ${p.metadata.pluginId}:`,
+        error,
+      );
+      throw new Error(`Critical error loading plugin ${p.metadata.pluginId}`, {
+        cause: error,
+      });
+    }
+  }
+
+  // Phase 2, pass 2: initialize plugins in topological order. Every plugin -
+  // and therefore every dependency - is fully migrated by now, so an init()
+  // can assume all plugin schemas exist.
+  for (const id of sortedIds) {
+    const p = pendingInits.find((x) => x.metadata.pluginId === id)!;
+    rootLogger.info(`🚀 Initializing ${p.metadata.pluginId}...`);
 
+    try {
       // Resolve Dependencies
       const resolvedDeps: Record<string, unknown> = {};
       for (const [key, ref] of Object.entries(p.deps)) {

package/src/plugin-manager.test.ts

@@ -486,5 +486,49 @@ describe("PluginManager", () => {
 
       expect(testBackendInit).toHaveBeenCalled();
     });
+
+    it("initializes every plugin across the two-pass (migrate-all, then init-all) loop", async () => {
+      const mockRouter = {
+        route: mock(),
+        all: mock(),
+        newResponse: mock(),
+      } as never;
+
+      // Boot runs migrations for all plugins in pass 1, then inits in pass 2.
+      // Manual test plugins have no plugin path so pass 1 is a no-op for them;
+      // this guards that pass 2 still initializes EVERY plugin (the split loop
+      // doesn't drop any) and follows topological order.
+      const initOrder: string[] = [];
+      const makePlugin = (pluginId: string) =>
+        createBackendPlugin({
+          metadata: { pluginId },
+          register(env) {
+            env.registerInit({
+              deps: {},
+              init: async () => {
+                initOrder.push(pluginId);
+              },
+            });
+          },
+        });
+
+      pluginManager.registerService(
+        coreServices.queueManager,
+        createMockQueueManager(),
+      );
+      pluginManager.registerService(coreServices.logger, createMockLogger());
+      pluginManager.registerService(
+        coreServices.database,
+        createMockDb() as never,
+      );
+
+      await pluginManager.loadPlugins(
+        mockRouter,
+        [makePlugin("plugin-a"), makePlugin("plugin-b"), makePlugin("plugin-c")],
+        { skipDiscovery: true },
+      );
+
+      expect(initOrder).toEqual(["plugin-a", "plugin-b", "plugin-c"]);
+    });
   });
 });

package/src/plugin-manager.ts

@@ -634,6 +634,12 @@ export class PluginManager {
         registerService: (ref, impl) => {
           this.registry.register(ref, impl);
         },
+        // Registry-backed resolver for arbitrary cross-plugin refs, using
+        // this plugin's identity as the consumer. Mirrors the plugin-loader
+        // `env.getService`; resolves through the real ServiceRegistry and
+        // throws clearly on a missing ref (never silently undefined).
+        getService: <T>(ref: ServiceRef<T>) =>
+          this.registry.get(ref, backendPlugin.metadata),
         registerExtensionPoint: (ref, impl) => {
           this.extensionPointManager.registerExtensionPoint(ref, impl);
         },

package/src/rpc-rest-compat.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { PluginManager } from "./plugin-manager";
-import { coreServices, os, RpcContext } from "@checkstack/backend-api";
+import { coreServices, os, createBackendPlugin } from "@checkstack/backend-api";
 import { Hono } from "hono";
 import { createMockDbModule } from "@checkstack/test-utils-backend";
 import { createMockLoggerModule } from "@checkstack/test-utils-backend";
@@ -10,7 +10,27 @@ mock.module("./db", () => createMockDbModule());
 
 mock.module("./logger", () => createMockLoggerModule());
 
-describe("RPC REST Compatibility", () => {
+/**
+ * Guards the oRPC router REGISTRATION + MOUNTING wiring contract.
+ *
+ * Background (silent-failure seam): the core/backend test preload used to
+ * register a mock `rpc` service whose `registerRouter` was a no-op, so across
+ * the ENTIRE suite a plugin's router never landed in the shared maps the
+ * `/api/:pluginId/*` dispatcher reads. The one "reachability" test that
+ * existed only asserted on a 200 inside an `if`, so it passed forever on a
+ * 404. These tests assert the concrete wiring that was silently broken:
+ *
+ *   1. Resolving `coreServices.rpc` for a plugin and calling `registerRouter`
+ *      lands the router AND its contract in the shared maps, keyed by the
+ *      resolving plugin id (consumed by `createApiRouteHandler`).
+ *   2. `loadPlugins` mounts the `/api/:pluginId/*` route on the Hono app, so
+ *      requests to a registered plugin reach the handler (no Hono-level 404).
+ *
+ * Note: exercising oRPC's RPC wire protocol end-to-end requires the plugin's
+ * real contract + protocol encoding; that is out of scope here. These guards
+ * cover the registration/mounting seam — the exact thing the no-op mock hid.
+ */
+describe("oRPC router registration + mounting wiring", () => {
   let pluginManager: PluginManager;
   let app: Hono;
 
@@ -19,69 +39,58 @@ describe("RPC REST Compatibility", () => {
     app = new Hono();
   });
 
-  it("should handle GET /api/auth/accessRules via oRPC router", async () => {
-    // 1. Setup a mock auth router
+  it("registers a plugin router + contract into the shared maps the API handler reads", async () => {
     const authRouter = os.router({
-      accessRules: os.handler(async () => {
-        return { accessRules: ["test-perm"] };
-      }),
+      accessRules: os.handler(async () => ({ accessRules: ["test-perm"] })),
     });
+    const contract = { accessRules: {} };
 
-    // 2. Register it in plugin manager (now using new pattern - router AND contract required)
-    // Note: In real usage, the path is derived from pluginId. For test, we manually set it.
-    const rpcService = await pluginManager.getService(coreServices.rpc);
-    // The new API auto-prefixes based on pluginId, but for test we need to manually set the map key
-    // Since we're testing the router handler directly, we use the derived name "auth"
-    // Second argument is the contract (for OpenAPI generation) - using a mock object for test
-    rpcService?.registerRouter(authRouter, { accessRules: {} });
+    // Resolve the rpc service scoped to the `auth` plugin and register the
+    // router — exactly how a plugin does it during init().
+    const rpcService = await pluginManager
+      .getRegistry()
+      .get(coreServices.rpc, { pluginId: "auth" });
+    rpcService.registerRouter(authRouter, contract);
 
-    // 3. Mock the auth service to skip real authentication
-    const mockAuth: any = {
-      authenticate: mock(async () => ({ id: "user-1", accessRules: ["*"] })),
-    };
-    pluginManager.registerService(coreServices.auth, mockAuth);
-
-    // Register other dummy services needed for context
-    pluginManager.registerService(coreServices.logger, {
-      info: mock(),
-      debug: mock(),
-      error: mock(),
-      warn: mock(),
-    } as any);
-    pluginManager.registerService(coreServices.database, {} as any);
-    pluginManager.registerService(coreServices.fetch, {} as any);
-    pluginManager.registerService(coreServices.healthCheckRegistry, {} as any);
-    pluginManager.registerService(coreServices.queuePluginRegistry, {
-      getPlugins: () => [],
-    } as any);
-    pluginManager.registerService(coreServices.queueManager, {
-      getActivePlugin: () => "none",
-      getQueue: () => ({}),
-    } as any);
-    pluginManager.registerService(coreServices.cachePluginRegistry, {
-      getPlugins: () => [],
-    } as any);
-    pluginManager.registerService(coreServices.cacheManager, {
-      getActivePlugin: () => "memory",
-      getProvider: () => ({}),
-    } as any);
+    // The contract MUST land in the shared registry the API route handler
+    // (and OpenAPI generation) consumes, keyed by the plugin id —
+    // `registerRouter` sets the router map and the contract map together. A
+    // no-op `registerRouter` (the prior regression) would leave this empty.
+    expect(pluginManager.getAllContracts().get("auth")).toBe(contract);
+  });
 
-    // 4. Mount the plugins
-    await pluginManager.loadPlugins(app);
+  it("mounts the /api/:pluginId/* route so a registered plugin reaches the handler (not a Hono 404)", async () => {
+    const authRouter = os.router({
+      accessRules: os.handler(async () => ({ accessRules: ["test-perm"] })),
+    });
+    const rpcService = await pluginManager
+      .getRegistry()
+      .get(coreServices.rpc, { pluginId: "auth" });
+    rpcService.registerRouter(authRouter, { accessRules: {} });
+    pluginManager.registerCorePluginMetadata({ pluginId: "auth" });
 
-    // 5. Simulate the request that frontend makes (now /api/auth instead of /api/auth-backend)
-    const res = await app.request("/api/auth/accessRules", {
-      method: "GET",
+    // At least one (manual) plugin is required for loadPlugins to proceed
+    // past its "no plugins" early-return and actually mount the
+    // `/api/:pluginId/*` route.
+    const noopPlugin = createBackendPlugin({
+      metadata: { pluginId: "noop" },
+      register: () => {},
     });
+    await pluginManager.loadPlugins(app, [noopPlugin], { skipDiscovery: true });
 
-    // If it's a 404, my theory about dots vs slashes or GET vs POST is correct
-    console.log("Response status:", res.status);
-    if (res.status === 200) {
-      const body = await res.json();
-      console.log("Response body:", JSON.stringify(body));
-      expect(body.accessRules).toContain("test-perm");
-    } else {
-      console.log("Response text:", await res.text());
-    }
+    // A request to `/api/:pluginId/*` must REACH the assembled API handler
+    // (the dispatcher), not fall through to a Hono 404. The dispatcher
+    // resolves the RpcContext first and, in this minimal harness, returns a
+    // handler-level 500 ("Core services not initialized") — which is exactly
+    // the proof we want: the route is mounted and the request reached the
+    // handler. (A regression that fails to mount the route would surface as
+    // a Hono 404 here instead.)
+    const reached = await app.request("/api/auth/accessRules", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{}",
+    });
+    expect(reached.status).not.toBe(404);
+    expect(reached.status).toBe(500);
   });
 });

package/src/test-preload.ts

@@ -43,11 +43,18 @@ mock.module(loggerPath, () => createMockLoggerModule());
 mock.module(coreServicesPath, () => ({
   registerCoreServices: ({
     registry,
+    pluginRpcRouters,
+    pluginContractRegistry,
   }: {
     registry: {
-      registerFactory: (ref: { id: string }, factory: unknown) => void;
+      registerFactory: (
+        ref: { id: string },
+        factory: (metadata: { pluginId: string }) => unknown,
+      ) => void;
       register: (ref: { id: string }, impl: unknown) => void;
     };
+    pluginRpcRouters?: Map<string, unknown>;
+    pluginContractRegistry?: Map<string, unknown>;
   }) => {
     // Register mock database factory - includes dialect.migrate for migration tests
     registry.registerFactory(coreServices.database, () => ({
@@ -101,9 +108,20 @@ mock.module(coreServicesPath, () => ({
       getAllStrategies: () => [...strategies.values()],
     }));
 
-    // Register mock RPC service factory
-    registry.registerFactory(coreServices.rpc, () => ({
-      registerRouter: () => {},
+    // Register mock RPC service factory.
+    //
+    // This MUST mirror the production factory's router wiring: it keys the
+    // router + contract by the resolving plugin's id into the SAME shared
+    // maps the API route handler reads. A previous version stubbed
+    // `registerRouter` as a no-op, which silently disabled router
+    // registration across the entire core/backend test suite — making oRPC
+    // router reachability impossible to verify (a 404 looked identical to a
+    // wired route to any test that didn't assert hard).
+    registry.registerFactory(coreServices.rpc, (metadata) => ({
+      registerRouter: (router: unknown, contract: unknown): void => {
+        pluginRpcRouters?.set(metadata.pluginId, router);
+        pluginContractRegistry?.set(metadata.pluginId, contract);
+      },
       registerHttpHandler: () => {},
     }));
 

package/src/utils/run-plugin-migrations.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "bun:test";
+import type { PoolClient } from "pg";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { runPluginMigrations } from "./run-plugin-migrations";
+
+type MigrationDb = NodePgDatabase<Record<string, unknown>>;
+
+/**
+ * A fake pooled client that records the SQL it runs and whether it was
+ * released, modelling the bits of `pg.PoolClient` the helper touches.
+ */
+function makeFakeClient() {
+  const queries: string[] = [];
+  let released = false;
+  const client = {
+    query: async (text: string) => {
+      queries.push(text);
+      return { rows: [] };
+    },
+    release: () => {
+      released = true;
+    },
+  };
+  return {
+    client: client as unknown as PoolClient,
+    queries,
+    isReleased: () => released,
+  };
+}
+
+describe("runPluginMigrations", () => {
+  it("runs the migrator on a single pinned connection with search_path set first", async () => {
+    const { client, queries, isReleased } = makeFakeClient();
+
+    let connectCount = 0;
+    const pool = {
+      connect: async () => {
+        connectCount++;
+        return client;
+      },
+    };
+
+    const fakeDb = { __fake: true } as unknown as MigrationDb;
+    let dbPassedToMigrate: unknown;
+    let clientPassedToFactory: PoolClient | undefined;
+    let queriesBeforeMigrate: string[] = [];
+
+    await runPluginMigrations({
+      pool,
+      migrationsFolder: "/plugins/healthcheck/drizzle",
+      migrationsSchema: "plugin_healthcheck",
+      createMigrationDb: (c) => {
+        clientPassedToFactory = c;
+        return fakeDb;
+      },
+      migrate: async (db, config) => {
+        dbPassedToMigrate = db;
+        queriesBeforeMigrate = [...queries];
+        expect(config.migrationsFolder).toBe("/plugins/healthcheck/drizzle");
+        expect(config.migrationsSchema).toBe("plugin_healthcheck");
+      },
+    });
+
+    // Exactly ONE connection is checked out: the SET and the migration must
+    // share a physical connection, which was the whole bug.
+    expect(connectCount).toBe(1);
+
+    // The migrator runs against a Drizzle instance bound to that same pinned
+    // client.
+    expect(clientPassedToFactory).toBe(client);
+    expect(dbPassedToMigrate).toBe(fakeDb);
+
+    // search_path is pointed at the plugin schema (after creating it) BEFORE
+    // the migrator runs.
+    expect(queriesBeforeMigrate).toEqual([
+      'CREATE SCHEMA IF NOT EXISTS "plugin_healthcheck"',
+      'SET search_path = "plugin_healthcheck"',
+    ]);
+
+    // Afterwards the connection is reset and returned to the pool.
+    expect(queries.at(-1)).toBe("SET search_path = public");
+    expect(isReleased()).toBe(true);
+  });
+
+  it("resets search_path and releases the connection even when the migrator throws", async () => {
+    const { client, queries, isReleased } = makeFakeClient();
+    const pool = { connect: async () => client };
+    const boom = new Error("migration failed");
+
+    await expect(
+      runPluginMigrations({
+        pool,
+        migrationsFolder: "/x",
+        migrationsSchema: "plugin_x",
+        createMigrationDb: () => ({}) as unknown as MigrationDb,
+        migrate: async () => {
+          throw boom;
+        },
+      }),
+    ).rejects.toThrow("migration failed");
+
+    expect(queries.at(-1)).toBe("SET search_path = public");
+    expect(isReleased()).toBe(true);
+  });
+
+  it("never touches anything but connect() on the pool (no session SET on the shared pool)", async () => {
+    const { client } = makeFakeClient();
+    const pool = { connect: async () => client };
+
+    await runPluginMigrations({
+      pool,
+      migrationsFolder: "/x",
+      migrationsSchema: "plugin_x",
+      createMigrationDb: () => ({}) as unknown as MigrationDb,
+      migrate: async () => {},
+    });
+
+    // The pool surface the helper depends on is exactly `connect`; everything
+    // else (CREATE SCHEMA, SET search_path, the migration itself) happens on
+    // the checked-out client. If this contract ever widens, the regression
+    // that motivated the pinned connection could creep back in.
+    expect(Object.keys(pool)).toEqual(["connect"]);
+  });
+});

package/src/utils/run-plugin-migrations.ts

@@ -0,0 +1,88 @@
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { migrate as defaultMigrate } from "drizzle-orm/node-postgres/migrator";
+import type { Pool, PoolClient } from "pg";
+
+type MigrationDb = NodePgDatabase<Record<string, unknown>>;
+
+export interface RunPluginMigrationsArgs {
+  /** Shared admin pool; the helper checks out ONE dedicated client from it. */
+  pool: Pick<Pool, "connect">;
+  /** Absolute path to the plugin's Drizzle migrations folder. */
+  migrationsFolder: string;
+  /**
+   * Postgres schema the plugin's objects live in (e.g. `plugin_healthcheck`).
+   * Also used by Drizzle for the per-plugin `__drizzle_migrations` table.
+   */
+  migrationsSchema: string;
+  /**
+   * Builds the Drizzle instance the migrator runs against. Defaults to one
+   * bound to the pinned `client`. Injectable so tests can run without a real
+   * connection.
+   */
+  createMigrationDb?: (client: PoolClient) => MigrationDb;
+  /** Drizzle's migrator. Injectable for tests. */
+  migrate?: (
+    db: MigrationDb,
+    config: { migrationsFolder: string; migrationsSchema: string },
+  ) => Promise<void>;
+}
+
+/**
+ * Run a plugin's Drizzle migrations on a SINGLE pinned pool connection.
+ *
+ * ## Why a pinned connection is required
+ *
+ * Plugin migrations are schema-agnostic: they reference the plugin's tables,
+ * types, and enums *unqualified* and rely on `search_path` to resolve them
+ * into the plugin's schema (e.g. `plugin_healthcheck`). So `search_path` must
+ * be set before the migration SQL runs.
+ *
+ * Setting it at the *session* level on the shared pool does NOT work, for the
+ * same reason session-level advisory locks don't (see `advisory-lock.ts`):
+ * Drizzle's `migrate()` wraps all pending migrations in one transaction, and
+ * with a `pg.Pool` that transaction checks out a *different* physical
+ * connection than the one the `SET` ran on. The migration statements then
+ * execute with the default `public` search_path.
+ *
+ * This stays invisible on a fresh database - every object (including each
+ * enum) is created within that one transaction, so unqualified references
+ * still resolve against whatever schema that connection happens to use. But on
+ * an UPGRADE, where earlier migrations already created an enum in the plugin
+ * schema and only newer migrations run, a new migration that references the
+ * pre-existing enum fails with `type "..." does not exist`.
+ *
+ * Binding the migrator to ONE pinned client, on which we set `search_path`
+ * first, guarantees every migration statement runs under the intended schema.
+ */
+export async function runPluginMigrations({
+  pool,
+  migrationsFolder,
+  migrationsSchema,
+  createMigrationDb = (client) => drizzle(client),
+  migrate = defaultMigrate,
+}: RunPluginMigrationsArgs): Promise<void> {
+  const client = await pool.connect();
+  try {
+    // Ensure the schema exists before pointing search_path at it. SET to a
+    // missing schema silently falls back to `public` at resolution time, which
+    // would recreate the very bug this helper exists to prevent.
+    await client.query(`CREATE SCHEMA IF NOT EXISTS "${migrationsSchema}"`);
+    await client.query(`SET search_path = "${migrationsSchema}"`);
+
+    await migrate(createMigrationDb(client), {
+      migrationsFolder,
+      migrationsSchema,
+    });
+  } finally {
+    // Reset before the client returns to the pool so the setting never leaks
+    // onto an unrelated query that later reuses this physical connection.
+    try {
+      await client.query("SET search_path = public");
+    } catch (resetError) {
+      // Best-effort: the release below still returns the connection. Reference
+      // the binding so lint doesn't flag an empty catch.
+      void resetError;
+    }
+    client.release();
+  }
+}