@checkstack/backend 0.15.0 → 0.16.0

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

@@ -63,6 +63,44 @@ function captureEnv(deps: PluginLoaderDeps): BackendPluginRegistry {
   return captured;
 }
 
+describe("registerPlugin pluginPath threading (migrations)", () => {
+  // Regression guard (#251): a manually-loaded plugin (e.g. the dev server's
+  // plugin-under-dev) must carry its on-disk path through to `pendingInits`,
+  // because the loader builds the Drizzle migrations folder as
+  // `<pluginPath>/drizzle`. Manual plugins historically got `pluginPath: ""`,
+  // so their migrations were silently skipped and a scaffolded plugin booted
+  // with no tables. The dev path now supplies the plugin's dir via
+  // `manualPluginPaths`; this asserts the value reaches `pendingInits`.
+  function registerWithPath(pluginPath: string): PendingInit[] {
+    const pendingInits: PendingInit[] = [];
+    const plugin = createBackendPlugin({
+      metadata: { pluginId: "widget" },
+      register: (env) => {
+        env.registerInit({ deps: {}, init: async () => {} });
+      },
+    });
+    registerPlugin({
+      backendPlugin: plugin,
+      pluginPath,
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+    return pendingInits;
+  }
+
+  it("threads a supplied pluginPath into the pending init (so migrations run)", () => {
+    const pending = registerWithPath("/repo/packages/widget-backend");
+    expect(pending).toHaveLength(1);
+    expect(pending[0]?.pluginPath).toBe("/repo/packages/widget-backend");
+  });
+
+  it("keeps an empty pluginPath when none is supplied (migrations skipped)", () => {
+    const pending = registerWithPath("");
+    expect(pending[0]?.pluginPath).toBe("");
+  });
+});
+
 describe("plugin env.getService", () => {
   it("resolves a service registered by another plugin through the real ServiceRegistry", async () => {
     const registry = new ServiceRegistry();

package/src/plugin-manager/plugin-loader.skip-naming.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import { createBackendPlugin } 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";
+import { rootLogger } from "../logger";
+
+/**
+ * Regression coverage for the "no register() export" skip diagnostic.
+ *
+ * A package declared `checkstack.type: "backend"` is inserted into the
+ * `plugins` table and loaded in Phase 1 via `pluginModule.default`. If that
+ * default export is missing (a host-consumed library mis-typed as a backend
+ * plugin, e.g. `@checkstack/signal-backend` before it was reclassified to
+ * `tooling`), `backendPlugin` is `undefined` and the loader skips it.
+ *
+ * Previously the skip warning rendered the opaque literal "unknown" because
+ * the only identifier source was `backendPlugin?.metadata?.pluginId`. These
+ * tests assert the package name / path from the database row is used as a
+ * fallback so the offending package is always identifiable, and that a valid
+ * plugin loads without any warning.
+ */
+
+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>(),
+  };
+}
+
+// A module whose `default` export is missing models a package mis-typed as a
+// backend plugin. `registerPlugin` accepts `BackendPlugin | undefined` precisely
+// because `pluginModule.default` can be `undefined` at runtime, so no cast is
+// needed to exercise the guard.
+const missingDefaultExport = undefined;
+
+describe("registerPlugin skip diagnostic", () => {
+  let warnSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(rootLogger, "warn").mockImplementation(() => rootLogger);
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it("names the package by its database-row name (never 'unknown') when the default export is missing", () => {
+    const pendingInits: PendingInit[] = [];
+
+    registerPlugin({
+      backendPlugin: missingDefaultExport,
+      pluginPath: "/workspace/core/signal-backend",
+      pluginName: "@checkstack/signal-backend",
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+
+    expect(pendingInits).toHaveLength(0);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = String(warnSpy.mock.calls[0]?.[0]);
+    expect(message).toContain("@checkstack/signal-backend");
+    expect(message).not.toContain("unknown");
+  });
+
+  it("falls back to the plugin path when no name is available", () => {
+    const pendingInits: PendingInit[] = [];
+
+    registerPlugin({
+      backendPlugin: missingDefaultExport,
+      pluginPath: "/workspace/core/mystery-backend",
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = String(warnSpy.mock.calls[0]?.[0]);
+    expect(message).toContain("/workspace/core/mystery-backend");
+    expect(message).not.toContain("unknown");
+  });
+
+  it("does not warn when a valid plugin with register() is registered", () => {
+    const pendingInits: PendingInit[] = [];
+    const plugin = createBackendPlugin({
+      metadata: { pluginId: "valid-plugin" },
+      register: () => {
+        // no-op: a valid plugin must not trigger the skip diagnostic.
+      },
+    });
+
+    registerPlugin({
+      backendPlugin: plugin,
+      pluginPath: "/workspace/core/valid-backend",
+      pluginName: "@checkstack/valid-backend",
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -71,27 +71,72 @@ export interface PluginLoaderDeps {
   onApiRouteRegistered?: () => void;
 }
 
+/**
+ * Resolves a human-identifiable name for a plugin module so diagnostics never
+ * render the opaque literal "unknown". Prefers the declared `pluginId`, then
+ * the package name from the database/discovery row, then the on-disk path.
+ */
+function resolvePluginIdentifier({
+  backendPlugin,
+  pluginName,
+  pluginPath,
+}: {
+  backendPlugin: BackendPlugin | undefined;
+  pluginName?: string;
+  pluginPath: string;
+}): string {
+  const pluginId = backendPlugin?.metadata?.pluginId;
+  if (pluginId) {
+    return pluginId;
+  }
+  if (pluginName) {
+    return pluginName;
+  }
+  if (pluginPath) {
+    return pluginPath;
+  }
+  return "unknown";
+}
+
 /**
  * Registers a single plugin - called during Phase 1.
  */
 export function registerPlugin({
   backendPlugin,
   pluginPath,
+  pluginName,
   pendingInits,
   providedBy,
   deps,
 }: {
-  backendPlugin: BackendPlugin;
+  /**
+   * The plugin module's default export. Typed as possibly `undefined` because
+   * a package mis-typed as `checkstack.type: "backend"` may have no default
+   * export at all (`pluginModule.default` is `undefined` at runtime); the guard
+   * below handles that case explicitly.
+   */
+  backendPlugin: BackendPlugin | undefined;
   pluginPath: string;
+  /**
+   * Package name of the plugin from its database/discovery row. Used so the
+   * "no register() export" diagnostic can name the offending package even when
+   * its module has no default export carrying `metadata.pluginId`.
+   */
+  pluginName?: string;
   pendingInits: PendingInit[];
   providedBy: Map<string, string>;
   deps: PluginLoaderDeps;
 }) {
   if (!backendPlugin || typeof backendPlugin.register !== "function") {
+    const identifier = resolvePluginIdentifier({
+      backendPlugin,
+      pluginName,
+      pluginPath,
+    });
     rootLogger.warn(
-      `Plugin ${
-        backendPlugin?.metadata?.pluginId || "unknown"
-      } is not using new API. Skipping.`,
+      `Plugin '${identifier}' has no backend register() export and was skipped. ` +
+        `If this package is a host-consumed library rather than a runtime plugin, ` +
+        `set its package.json "checkstack.type" to "tooling" so it is not discovered as a backend plugin.`,
     );
     return;
   }
@@ -201,11 +246,21 @@ export function registerPlugin({
 export async function loadPlugins({
   rootRouter,
   manualPlugins = [],
+  manualPluginPaths,
   skipDiscovery = false,
   deps,
 }: {
   rootRouter: Hono;
   manualPlugins?: BackendPlugin[];
+  /**
+   * Optional `pluginId -> on-disk plugin dir` map for manually-loaded
+   * plugins. When a manual plugin has an entry here, its Drizzle migrations
+   * (in `<dir>/drizzle`) are applied just like a discovered plugin's. The
+   * dev server passes the plugin's `CHECKSTACK_DEV_PLUGIN_PATH` here so a
+   * scaffolded plugin's tables exist on first boot; without it, manual
+   * plugins keep their historical `pluginPath: ""` (migrations skipped).
+   */
+  manualPluginPaths?: Map<string, string>;
   /** When true, skip filesystem plugin discovery (for testing) */
   skipDiscovery?: boolean;
   deps: PluginLoaderDeps;
@@ -286,6 +341,7 @@ export async function loadPlugins({
       registerPlugin({
         backendPlugin,
         pluginPath: plugin.path,
+        pluginName: plugin.name,
         pendingInits,
         providedBy,
         deps,
@@ -301,7 +357,10 @@ export async function loadPlugins({
   for (const backendPlugin of manualPlugins) {
     registerPlugin({
       backendPlugin,
-      pluginPath: "",
+      // Use the supplied dir (dev server passes the plugin's path so its
+      // migrations run); fall back to "" for manual plugins without one.
+      pluginPath:
+        manualPluginPaths?.get(backendPlugin.metadata.pluginId) ?? "",
       pendingInits,
       providedBy,
       deps,

package/src/plugin-manager.ts

@@ -197,11 +197,15 @@ export class PluginManager {
   async loadPlugins(
     rootRouter: Hono,
     manualPlugins: BackendPlugin[] = [],
-    options: { skipDiscovery?: boolean } = {}
+    options: {
+      skipDiscovery?: boolean;
+      manualPluginPaths?: Map<string, string>;
+    } = {}
   ) {
     await loadPluginsImpl({
       rootRouter,
       manualPlugins,
+      manualPluginPaths: options.manualPluginPaths,
       skipDiscovery: options.skipDiscovery,
       deps: {
         registry: this.registry,

package/src/services/collector-registry.ts

@@ -4,6 +4,7 @@ import type {
   TransportClient,
   RegisteredCollector,
 } from "@checkstack/backend-api";
+import { assertNoSecretTemplatableConflict } from "@checkstack/backend-api";
 import { rootLogger } from "../logger";
 
 /**
@@ -19,6 +20,14 @@ export class CoreCollectorRegistry {
   ): void {
     // Use fully-qualified ID: ownerPluginId.collectorId
     const qualifiedId = `${ownerPlugin.pluginId}.${collector.id}`;
+    // Load-time guard: a config field must not be both a secret and
+    // templatable (they resolve in separate ordered passes). Fail fast on a
+    // misconfigured collector rather than silently skipping one pass at run
+    // time.
+    assertNoSecretTemplatableConflict({
+      schema: collector.config.schema,
+      schemaName: `collector:${qualifiedId}`,
+    });
     if (this.collectors.has(qualifiedId)) {
       rootLogger.warn(
         `CollectorStrategy '${qualifiedId}' is already registered. Overwriting.`

package/src/services/dev-auth.test.ts

@@ -1,9 +1,26 @@
-import { describe, it, expect } from "bun:test";
-import { createDevAuthService } from "./dev-auth";
+import { describe, it, expect, mock } from "bun:test";
+
+// dev-auth signs/verifies S2S tokens via jwtService, which is backed by the
+// DB-bound KeyStore. Mock it so these stay pure unit tests (no DB): tokens are
+// modeled as `svc:<pluginId>` strings so we can assert the wiring without real
+// crypto.
+mock.module("./jwt", () => ({
+  jwtService: {
+    sign: async (payload: Record<string, unknown>) =>
+      `svc:${String(payload.service)}`,
+    verify: async (token: string) =>
+      token.startsWith("svc:") ? { service: token.slice(4) } : undefined,
+  },
+}));
+
+const { createDevAuthService } = await import("./dev-auth");
 
 describe("createDevAuthService", () => {
   it("authenticate() returns a stable RealUser identity", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
     const user = await svc.authenticate(new Request("http://x"));
     expect(user).toBeDefined();
     if (!user || user.type !== "user") {
@@ -22,6 +39,7 @@ describe("createDevAuthService", () => {
         { id: "catalog.system.read" },
         { id: "catalog.system.manage" },
       ],
+      pluginId: "dev",
     });
     const user = await svc.authenticate(new Request("http://x"));
     if (!user || user.type !== "user") throw new Error("expected RealUser");
@@ -33,7 +51,10 @@ describe("createDevAuthService", () => {
 
   it("re-reads access rules on each authenticate (rules registered later still apply)", async () => {
     const rules = [{ id: "first.rule" }];
-    const svc = createDevAuthService({ getAllAccessRules: () => rules });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => rules,
+      pluginId: "dev",
+    });
 
     const before = await svc.authenticate(new Request("http://x"));
     if (!before || before.type !== "user") throw new Error("expected RealUser");
@@ -45,20 +66,58 @@ describe("createDevAuthService", () => {
     expect(after.accessRules).toEqual(["first.rule", "second.rule"]);
   });
 
+  it("authenticate() honors real SERVICE tokens (S2S calls stay services, not the dev user)", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
+    // A backend-to-backend caller presents a token minted as `{ service: <id> }`.
+    const principal = await svc.authenticate(
+      new Request("http://x", {
+        headers: { Authorization: "Bearer svc:incident" },
+      }),
+    );
+    expect(principal).toEqual({ type: "service", pluginId: "incident" });
+  });
+
+  it("authenticate() falls back to the dev user for non-service tokens", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [{ id: "x" }],
+      pluginId: "dev",
+    });
+    const principal = await svc.authenticate(
+      new Request("http://x", {
+        headers: { Authorization: "Bearer not-a-real-token" },
+      }),
+    );
+    if (!principal || principal.type !== "user") {
+      throw new Error("expected RealUser");
+    }
+    expect(principal.id).toBe("dev-user");
+  });
+
   it("getAnonymousAccessRules returns an empty list (anonymous gets nothing in dev)", async () => {
     const svc = createDevAuthService({
       getAllAccessRules: () => [{ id: "x" }, { id: "y" }],
+      pluginId: "dev",
     });
     expect(await svc.getAnonymousAccessRules()).toEqual([]);
   });
 
-  it("getCredentials returns an empty headers object", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
-    expect(await svc.getCredentials()).toEqual({ headers: {} });
+  it("getCredentials mints a service token scoped to this plugin", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "notification",
+    });
+    const creds = await svc.getCredentials();
+    expect(creds.headers.Authorization).toBe("Bearer svc:notification");
   });
 
   it("checkResourceTeamAccess always grants", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
     expect(
       await svc.checkResourceTeamAccess({
         userId: "x",
@@ -72,7 +131,10 @@ describe("createDevAuthService", () => {
   });
 
   it("getAccessibleResourceIds returns the input list unfiltered", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
     expect(
       await svc.getAccessibleResourceIds({
         userId: "x",

package/src/services/dev-auth.ts

@@ -1,4 +1,5 @@
 import type { AuthService, RealUser } from "@checkstack/backend-api";
+import { jwtService } from "./jwt";
 
 /**
  * Dev-only auth service.
@@ -8,17 +9,37 @@ import type { AuthService, RealUser } from "@checkstack/backend-api";
  * synthetic user that has every registered access rule, so any procedure
  * (regardless of the access guards on it) authorizes.
  *
+ * IMPORTANT: real SERVICE tokens still resolve to a `ServiceUser`. dev-auth
+ * REPLACES the core auth factory, so without this passthrough every
+ * backend-to-backend call (and the service-only endpoints they hit, e.g.
+ * `notification.registerSubscriptionSpec` from a plugin's `afterPluginsReady`)
+ * would be authenticated as the synthetic USER and 403 with "for services
+ * only" - which fatally breaks app boot. Only non-service requests get the
+ * synthetic dev admin.
+ *
  * NEVER register this in production. The runtime gates installation
  * behind a `CHECKSTACK_DEV_AUTH=true` env var that we set explicitly in
  * the dev server entry point.
  *
  * The user identity is stable (`dev-user`) so plugin code that derives
  * UI / data from `user.id` behaves consistently across reloads.
+ *
+ * Note: app-principal tokens (automation `runAs`) are NOT specially handled
+ * here - in dev they fall through to the dev admin. That's a dev convenience;
+ * the bounded-principal enforcement is covered by unit/integration tests.
  */
 export function createDevAuthService({
   getAllAccessRules,
+  pluginId,
 }: {
   getAllAccessRules: () => Array<{ id: string }>;
+  /**
+   * The plugin this auth instance is scoped to (from the service-factory
+   * metadata). Used to mint S2S credentials as `{ service: pluginId }`, so
+   * service-only endpoints that check the caller's plugin (e.g. subscription
+   * spec ownership) accept the call - exactly like the production auth factory.
+   */
+  pluginId: string;
 }): AuthService {
   const devUser: RealUser = {
     type: "user",
@@ -31,15 +52,31 @@ export function createDevAuthService({
   };
 
   return {
-    async authenticate(_request) {
-      // Always grant every access rule the platform currently knows about.
-      // We resolve this lazily so rules registered by plugins after auth
-      // construction (the normal flow) still apply.
+    async authenticate(request) {
+      // Honor real service tokens so backend-to-backend calls (and the
+      // service-only endpoints they hit during boot) keep working.
+      const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+      if (token) {
+        const payload = await jwtService.verify(token);
+        if (payload && payload.service) {
+          return { type: "service" as const, pluginId: payload.service as string };
+        }
+      }
+      // Otherwise authenticate as the synthetic dev admin. Grant every access
+      // rule the platform currently knows about, resolved lazily so rules
+      // registered by plugins after auth construction still apply.
       devUser.accessRules = getAllAccessRules().map((r) => r.id);
       return devUser;
     },
     async getCredentials() {
-      return { headers: {} };
+      // Mint a real service token (as THIS plugin) so backend-to-backend calls
+      // authenticate as a SERVICE and pass service-only endpoints - including
+      // those that check the caller's plugin id (e.g. subscription-spec
+      // ownership) - matching production. Without this, S2S calls would carry
+      // no auth, be treated as the synthetic user, and 403 on service-only
+      // procedures (breaking boot).
+      const token = await jwtService.sign({ service: pluginId }, "5m");
+      return { headers: { Authorization: `Bearer ${token}` } };
     },
     async getAnonymousAccessRules() {
       // Anonymous users get nothing; the dev user is the only authenticated

package/src/services/health-check-registry.test.ts

@@ -8,6 +8,7 @@ import {
   Versioned,
   VersionedAggregated,
   aggregatedCounter,
+  configString,
 } from "@checkstack/backend-api";
 import { createMockLogger } from "@checkstack/test-utils-backend";
 import { z } from "zod";
@@ -80,6 +81,39 @@ describe("CoreHealthCheckRegistry", () => {
       expect(registry.getStrategy(qualifiedId)).toBe(mockStrategy1);
     });
 
+    it("throws at register time when a field is both secret and templatable", () => {
+      const conflictingStrategy: HealthCheckStrategy = {
+        id: "conflicting-strategy",
+        displayName: "Conflicting",
+        description: "Has a field that is both secret and templatable",
+        config: new Versioned({
+          version: 1,
+          schema: z.object({
+            timeout: z.number().default(30_000),
+            token: configString({ "x-secret": true, "x-templatable": true }),
+          }),
+        }),
+        result: new Versioned({
+          version: 1,
+          schema: z.record(z.string(), z.unknown()),
+        }),
+        aggregatedResult: new VersionedAggregated({
+          version: 1,
+          fields: { count: aggregatedCounter({}) },
+        }),
+        createClient: mock(() =>
+          Promise.resolve({
+            client: { exec: async () => ({}) },
+            close: () => {},
+          }),
+        ),
+        mergeResult: mock(() => ({})),
+      };
+      expect(() =>
+        registry.registerWithOwner(conflictingStrategy, mockOwner),
+      ).toThrow(/both/);
+    });
+
     it("should overwrite an existing strategy with the same qualified ID", () => {
       const overwritingStrategy: HealthCheckStrategy = {
         ...mockStrategy1,

package/src/services/health-check-registry.ts

@@ -2,6 +2,7 @@ import type { PluginMetadata } from "@checkstack/common";
 import {
   HealthCheckRegistry,
   HealthCheckStrategy,
+  assertNoSecretTemplatableConflict,
 } from "@checkstack/backend-api";
 import { rootLogger } from "../logger";
 
@@ -30,6 +31,12 @@ export class CoreHealthCheckRegistry {
     ownerPlugin: PluginMetadata,
   ): void {
     const qualifiedId = `${ownerPlugin.pluginId}.${strategy.id}`;
+    // Load-time guard: secret + templatable on one field is a config error
+    // (the two are resolved in separate ordered passes).
+    assertNoSecretTemplatableConflict({
+      schema: strategy.config.schema,
+      schemaName: `strategy:${qualifiedId}`,
+    });
     if (this.strategies.has(qualifiedId)) {
       rootLogger.warn(
         `HealthCheckStrategy '${qualifiedId}' is already registered. Overwriting.`,

package/src/services/service-registry.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "bun:test";
+import { createServiceRef } from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+import { ServiceRegistry } from "./service-registry";
+
+const metadata: PluginMetadata = { pluginId: "core" };
+
+describe("ServiceRegistry resolution precedence", () => {
+  it("resolves a factory before a plain instance for the same ref", async () => {
+    const ref = createServiceRef<string>("test.svc");
+    const registry = new ServiceRegistry();
+    registry.register(ref, "instance");
+    registry.registerFactory(ref, () => "factory");
+    // get() tries factories first — this is the long-standing behaviour the
+    // dev-auth fix relies on (see below).
+    expect(await registry.get(ref, metadata)).toBe("factory");
+  });
+
+  it("returns the registered instance when no factory exists", async () => {
+    const ref = createServiceRef<string>("test.svc.instance-only");
+    const registry = new ServiceRegistry();
+    registry.register(ref, "instance");
+    expect(await registry.get(ref, metadata)).toBe("instance");
+  });
+
+  // Regression guard (#251): the CHECKSTACK_DEV_AUTH bypass was dead code on
+  // the API path because the production auth FACTORY (registered by
+  // `registerCoreServices`) shadowed a dev auth INSTANCE registered via
+  // `registerService(coreServices.auth, …)` — `get()` resolves factories
+  // before instances, so the dev auth was never returned and every plugin
+  // API request 401ed. The fix registers the dev auth as a FACTORY so it
+  // wins. This test models that exact wiring on the auth ref.
+  it("dev auth registered as a factory overrides a pre-existing production auth factory", async () => {
+    const authRef = createServiceRef<{ kind: string }>("checkstack.auth");
+    const registry = new ServiceRegistry();
+
+    // Production setup: real auth registered as a factory.
+    const prodAuth = { kind: "production" };
+    registry.registerFactory(authRef, () => prodAuth);
+
+    // Sanity: before the dev override, get() returns the production factory.
+    expect((await registry.get(authRef, metadata)).kind).toBe("production");
+
+    // Dev path: register dev auth as a factory (NOT a plain instance).
+    const devAuth = { kind: "dev" };
+    registry.registerFactory(authRef, () => devAuth);
+
+    // The dev auth must now be what get() returns.
+    expect((await registry.get(authRef, metadata)).kind).toBe("dev");
+  });
+
+  it("a dev auth registered as a plain instance is (still) shadowed by a factory — documents why the fix uses a factory", async () => {
+    const authRef = createServiceRef<{ kind: string }>("checkstack.auth.legacy");
+    const registry = new ServiceRegistry();
+    registry.registerFactory(authRef, () => ({ kind: "production" }));
+    // This is the BUGGY shape the fix replaced: an instance is shadowed.
+    registry.register(authRef, { kind: "dev" });
+    expect((await registry.get(authRef, metadata)).kind).toBe("production");
+  });
+});