@checkstack/backend 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @checkstack/backend
 
+## 0.8.2
+
+### Patch Changes
+
+- 302cd3f: fix: resilient startup routing + /health and /ready endpoints
+
+  Three fixes that together eliminate startup-race errors during boot and
+  hot-reload, plus a new readiness API for plugins.
+
+  1. **TrieRouter swap (root cause).** Hono's default `SmartRouter` freezes
+     its matcher on the first request — any later `app.add()` throws
+     `MESSAGE_MATCHER_IS_ALREADY_BUILT`. Plugins register routes during
+     `init()` (and at runtime via `loadSinglePlugin`), so an early request
+     during boot would silently lock the matcher with only the module-load
+     routes, and every later route registration would fail. The backend
+     now uses `TrieRouter`, which is incremental — routes can be added at
+     any time, including after thousands of requests have been served.
+     This also future-proofs runtime plugin install.
+
+  2. **Init gating + fail-loud.** Non-bypass requests now `await` an
+     `initPromise` (with a 30s timeout that returns 503 + Retry-After) so
+     no traffic reaches Hono before plugins finish registering routes.
+     Init failures crash the process via `process.exit(1)` so docker/k8s
+     restart cleanly instead of silently serving a half-initialized
+     backend.
+
+  3. **`/assets/*` fall-through.** The production frontend asset handler
+     now calls `next()` instead of `c.notFound()` on miss, so
+     plugin-asset routes registered later (`/assets/plugins/:pluginName/*`)
+     actually get a chance to match.
+
+  ### New: platform endpoints under `/.checkstack/*`
+
+  - `GET /.checkstack/health` — liveness, always 200 once the process is up.
+  - `GET /.checkstack/ready` — readiness, 503 until init completes and all
+    critical probes pass; 200 otherwise. Returns `{ ready, checks: [...] }`
+    with per-probe status, message/error and duration.
+
+  The leading `.checkstack/` prefix namespaces platform-level endpoints
+  away from plugin `/api/*`, runtime frontend assets, and the SPA wildcard,
+  leaving room for additional operator endpoints in the future.
+
+  ### New: plugin readiness API
+
+  Plugins can contribute readiness probes via the new
+  `coreServices.readinessRegistry` service:
+
+  ```ts
+  registerInit({
+    deps: { readiness: coreServices.readinessRegistry },
+    async init({ readiness }) {
+      readiness.register({
+        name: "queue.connected",
+        critical: true,
+        check: async () => ({
+          ok: pool.isConnected(),
+          message: pool.isConnected() ? undefined : "queue pool not connected",
+        }),
+      });
+    },
+  });
+  ```
+
+  Probes run in parallel, throwing probes are reported as `ok: false`,
+  and non-critical probes don't block readiness.
+
+- Updated dependencies [302cd3f]
+  - @checkstack/backend-api@0.14.1
+  - @checkstack/cache-api@0.2.3
+  - @checkstack/queue-api@0.2.17
+  - @checkstack/signal-backend@0.2.2
+  - @checkstack/api-docs-common@0.1.10
+  - @checkstack/auth-common@0.6.4
+  - @checkstack/common@0.7.0
+  - @checkstack/drizzle-helper@0.0.4
+  - @checkstack/signal-common@0.2.0
+
 ## 0.8.1
 
 ### Patch Changes

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "checkstack": {
     "type": "backend"
   },
   "type": "module",
   "scripts": {
     "dev": "bun --env-file=../../.env --watch src/index.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo -b",
     "generate": "bun --env-file=../../.env run drizzle-kit generate",
     "lint": "bun run lint:code",
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
     "@checkstack/api-docs-common": "0.1.10",
-    "@checkstack/auth-common": "0.6.3",
-    "@checkstack/backend-api": "0.13.1",
+    "@checkstack/auth-common": "0.6.4",
+    "@checkstack/backend-api": "0.14.0",
     "@checkstack/common": "0.7.0",
     "@checkstack/drizzle-helper": "0.0.4",
-    "@checkstack/cache-api": "0.2.1",
-    "@checkstack/queue-api": "0.2.15",
-    "@checkstack/signal-backend": "0.2.0",
+    "@checkstack/cache-api": "0.2.2",
+    "@checkstack/queue-api": "0.2.16",
+    "@checkstack/signal-backend": "0.2.1",
     "@checkstack/signal-common": "0.2.0",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
@@ -41,7 +41,7 @@
     "@types/bun": "latest",
     "@checkstack/tsconfig": "0.0.5",
     "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.21",
+    "@checkstack/test-utils-backend": "0.1.22",
     "drizzle-kit": "^0.31.10"
   }
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 import type { Server } from "bun";
 import { type Context, Hono } from "hono";
+import { TrieRouter } from "hono/router/trie-router";
 import { PluginManager } from "./plugin-manager";
 import { logger } from "hono/logger";
 import { migrate } from "drizzle-orm/node-postgres/migrator";
@@ -8,6 +9,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { rootLogger } from "./logger";
 import { coreServices, coreHooks } from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
 import { plugins } from "./schema";
 import { eq, and } from "drizzle-orm";
 import { PluginLocalInstaller } from "./services/plugin-installer";
@@ -52,9 +54,40 @@ import {
 
 import { cors } from "hono/cors";
 
-const app = new Hono();
+// IMPORTANT: TrieRouter (not the default SmartRouter).
+// SmartRouter freezes its matcher on the first incoming request — any later
+// app.add() throws "Can not add a route since the matcher is already built".
+// Plugins register routes asynchronously during init() and at runtime via
+// loadSinglePlugin(), so we need an incremental router.
+const app = new Hono({ router: new TrieRouter() });
 const pluginManager = new PluginManager();
 
+/**
+ * Init lifecycle state.
+ *
+ * `initialized` flips to true after the entire init() completes (Phases 1-3).
+ * It feeds the "core.init" readiness probe consumed by /ready.
+ *
+ * `initError` is populated when init throws; the process is then exited so
+ * the supervisor (docker/k8s) restarts us — we never serve a half-initialized
+ * backend.
+ *
+ * The HTTP request gate does NOT key off these flags directly. It awaits
+ * `pluginManager.routesReadyPromise`, which resolves earlier — right after
+ * `/api/:pluginId/*` is added to the root router and BEFORE `afterPluginsReady`
+ * runs — so cross-plugin RPC calls during plugin boot don't deadlock on
+ * themselves.
+ */
+let initError: Error | undefined;
+let initialized = false;
+
+/**
+ * Maximum time a request will wait for init to complete before falling back
+ * to a 503 Service Unavailable. Without this, a wedged plugin would hang
+ * health probes forever.
+ */
+const READY_WAIT_TIMEOUT_MS = 30_000;
+
 // WebSocket handler instance (initialized during init)
 let wsHandler: ReturnType<typeof createWebSocketHandler> | undefined;
 
@@ -82,6 +115,50 @@ app.use(
 );
 app.use("*", logger());
 
+// =============================================================================
+// PLATFORM ENDPOINTS — /.checkstack/*
+// =============================================================================
+//
+// All "platform-level" endpoints (probes, future operator hooks) live under
+// /.checkstack/* so they are clearly separated from plugin /api/*, runtime
+// frontend assets, and the SPA wildcard. The leading dot keeps them out of
+// any plugin URL space by construction.
+//
+// Health & readiness:
+//   - registered at module load; bypass the boot gate in `fetch()` so that
+//     orchestrators (Kubernetes, docker-compose) can probe a still-booting
+//     process.
+//   - /.checkstack/health = "process is alive"
+//   - /.checkstack/ready  = "plugins initialized and all critical probes pass"
+
+/** Liveness probe — answers as long as the process responds. */
+app.get("/.checkstack/health", (c) => c.json({ status: "ok" }));
+
+/**
+ * Readiness probe — aggregates plugin-contributed checks.
+ * - 503 while init is in flight or has failed
+ * - 503 if any critical probe is failing
+ * - 200 only when init completed AND all critical probes pass
+ */
+app.get("/.checkstack/ready", async (c) => {
+  if (initError) {
+    return c.json(
+      { ready: false, error: initError.message, checks: [] },
+      503,
+      { "Retry-After": "5" },
+    );
+  }
+  if (!initialized) {
+    return c.json(
+      { ready: false, reason: "initializing", checks: [] },
+      503,
+      { "Retry-After": "1" },
+    );
+  }
+  const snapshot = await pluginManager.getReadinessRegistry().evaluate();
+  return c.json(snapshot, snapshot.ready ? 200 : 503);
+});
+
 // SECURITY: Add missing standard security headers across all API responses
 app.use("/api/*", async (c, next) => {
   await next();
@@ -185,14 +262,16 @@ if (frontendDistPath && fs.existsSync(frontendDistPath)) {
   };
 
   // Serve static assets (JS, CSS, images, etc.)
-  app.get("/assets/*", async (c) => {
+  // Fall through to next() on miss so plugin-asset routes (registered later
+  // during init at /assets/plugins/:pluginName/*) get a chance to match.
+  app.get("/assets/*", async (c, next) => {
     const assetPath = c.req.path.replace("/assets/", "");
     const filePath = path.join(frontendDistPath, "assets", assetPath);
 
     if (fs.existsSync(filePath)) {
       return serveFile(c, filePath);
     }
-    return c.notFound();
+    return next();
   });
 
   // Serve vendor scripts (externalized React, react-router-dom, etc.)
@@ -441,16 +520,117 @@ const init = async () => {
     logger: rootLogger.child({ service: "WebSocket" }),
   });
 
+  // Register the core "init" readiness probe. Plugin-contributed probes are
+  // additive — see coreServices.readinessRegistry for the plugin-facing API.
+  pluginManager.getReadinessRegistry().register({
+    name: "core.init",
+    critical: true,
+    check: async () => ({ ok: initialized, message: initialized ? undefined : "init not complete" }),
+  });
+
   rootLogger.info("✅ Checkstack Core initialized.");
 };
 
-void init();
+/**
+ * Fire-and-forget init. We deliberately don't `await` at the top level so the
+ * server can answer /health and /ready while plugins are still loading;
+ * non-bypass requests are gated via `waitForRoutesReady()` below.
+ */
+// eslint-disable-next-line unicorn/prefer-top-level-await -- intentionally non-blocking; gates handled in waitForRoutesReady()
+void (async () => {
+  try {
+    await init();
+    initialized = true;
+  } catch (error: unknown) {
+    initError = new Error(extractErrorMessage(error, "init failed"));
+    rootLogger.error(
+      "❌ FATAL: Checkstack Core init failed; the process will exit so the supervisor can restart it.",
+      initError,
+    );
+    // Give the logger one tick to flush, then exit so docker/k8s restarts us.
+    // A half-initialized backend silently serves broken state — restart is
+    // strictly better than continuing. We disable the no-process-exit rule
+    // because this IS the canonical fail-fast pattern for a long-running
+    // server entrypoint.
+    setTimeout(() => {
+      // eslint-disable-next-line unicorn/no-process-exit -- intentional fail-fast on init failure
+      process.exit(1);
+    }, 50);
+  }
+})();
+
+/**
+ * Paths that bypass the boot gate. Platform endpoints under /.checkstack/*
+ * MUST be reachable while the backend is still booting so orchestrators can
+ * probe it. Everything else waits until plugin routes are registered.
+ */
+const BOOT_BYPASS_PREFIX = "/.checkstack/";
+
+/**
+ * Wait until plugin RPC routes are registered on the root router (resolved
+ * inside `loadPlugins` BEFORE Phase 2 / `afterPluginsReady`). Returns:
+ *   - undefined when routes are ready → caller should proceed to Hono.
+ *   - a 503 Response when init failed or the wait timed out.
+ *
+ * Why this gate, and why at this specific point:
+ *   - Earlier (before /api/:pluginId/* is added), an incoming request would
+ *     short-circuit through the SPA wildcard or 404 because the plugin route
+ *     simply doesn't exist yet on the router.
+ *   - Later (after full init), self-referencing RPC calls made from
+ *     `afterPluginsReady` would deadlock waiting for init to complete — so
+ *     we MUST open the gate before Phase 3 runs.
+ *   - `loadPlugins()` resolves `routesReadyPromise` immediately after
+ *     `registerApiRoute()`, which is the earliest point both conditions hold.
+ */
+async function waitForRoutesReady(): Promise<Response | undefined> {
+  if (initError) {
+    return Response.json(
+      { error: "Backend init failed", message: initError.message },
+      { status: 503, headers: { "Retry-After": "5" } },
+    );
+  }
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  // pluginManager.routesReadyPromise resolves from inside loadPlugins; it
+  // never rejects. The init catch handler logs + process.exit's separately.
+  const timedOut = await Promise.race([
+    pluginManager.routesReadyPromise.then(() => false),
+    new Promise<true>((resolve) => {
+      timeoutHandle = setTimeout(() => resolve(true), READY_WAIT_TIMEOUT_MS);
+    }),
+  ]);
+  if (timeoutHandle) clearTimeout(timeoutHandle);
+  if (timedOut) {
+    return Response.json(
+      { error: "Backend not ready", message: "boot timeout" },
+      { status: 503, headers: { "Retry-After": "5" } },
+    );
+  }
+  // Re-read after await — init may have rejected while we were waiting.
+  const errAfter = initError as Error | undefined;
+  if (errAfter) {
+    return Response.json(
+      { error: "Backend init failed", message: errAfter.message },
+      { status: 503, headers: { "Retry-After": "5" } },
+    );
+  }
+  return undefined;
+}
 
 // Custom fetch handler that handles WebSocket upgrades
 const fetch = async (
   req: Request,
   server: Server<ServerWsData>
 ): Promise<Response | undefined> => {
+  const url = new URL(req.url);
+
+  // Platform endpoints (/.checkstack/*) bypass the boot gate so orchestrators
+  // can poll a booting process. Everything else waits until plugin routes
+  // are registered on the root router (resolved before Phase 2 init runs).
+  if (!url.pathname.startsWith(BOOT_BYPASS_PREFIX)) {
+    const stalled = await waitForRoutesReady();
+    if (stalled) return stalled;
+  }
+
   // Set the server reference for WebSocket pub/sub after startup
   if (wsHandler && !server.upgrade) {
     // Server doesn't support WebSocket upgrade (shouldn't happen with Bun)
@@ -461,8 +641,6 @@ const fetch = async (
   // Cast is safe: signal handler only reads its own fields via connectionType guard
   wsHandler?.setServer(server as unknown as Server<WebSocketData>);
 
-  const url = new URL(req.url);
-
   // Handle WebSocket upgrade for signals
   if (url.pathname === "/api/signals/ws") {
     // Try to authenticate, but allow anonymous connections for broadcast signals

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

@@ -30,6 +30,10 @@ import {
   WebSocketRouteStoreImpl,
   createScopedWsRegistry,
 } from "../services/ws-route-registry";
+import {
+  CoreReadinessRegistry,
+  createScopedReadinessRegistry,
+} from "../services/readiness-registry";
 
 /**
  * Check if a PostgreSQL schema exists.
@@ -59,7 +63,11 @@ export function registerCoreServices({
   pluginRpcRouters: Map<string, unknown>;
   pluginHttpHandlers: Map<string, (req: Request) => Promise<Response>>;
   pluginContractRegistry: Map<string, unknown>;
-}): { collectorRegistry: CoreCollectorRegistry; wsStore: WebSocketRouteStoreImpl } {
+}): {
+  collectorRegistry: CoreCollectorRegistry;
+  wsStore: WebSocketRouteStoreImpl;
+  readinessRegistry: CoreReadinessRegistry;
+} {
   // 1. Database Factory (Scoped)
   registry.registerFactory(coreServices.database, async (metadata) => {
     const { pluginId, previousPluginIds } = metadata;
@@ -356,6 +364,17 @@ export function registerCoreServices({
     createScopedWsRegistry(globalWsStore, metadata.pluginId),
   );
 
+  // 11. Readiness Registry (Scoped Factory)
+  // Plugins contribute probes that are aggregated by the /ready endpoint.
+  const globalReadinessRegistry = new CoreReadinessRegistry();
+  registry.registerFactory(coreServices.readinessRegistry, () =>
+    createScopedReadinessRegistry(globalReadinessRegistry),
+  );
+
   // Return global registries for lifecycle cleanup
-  return { collectorRegistry: globalCollectorRegistry, wsStore: globalWsStore };
+  return {
+    collectorRegistry: globalCollectorRegistry,
+    wsStore: globalWsStore,
+    readinessRegistry: globalReadinessRegistry,
+  };
 }

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

@@ -56,6 +56,14 @@ export interface PluginLoaderDeps {
    * Map of pluginId -> contract for OpenAPI generation.
    */
   pluginContractRegistry: Map<string, AnyContractRouter>;
+  /**
+   * Called once `/api/:pluginId/*` is added to the root router and Phase 2
+   * (per-plugin init) is about to start. From this point on, plugin RPC
+   * routers come online incrementally as each plugin initializes — so
+   * self-referencing HTTP calls (e.g. RPC made from `afterPluginsReady`)
+   * can be allowed through the boot-time request gate without deadlocking.
+   */
+  onApiRouteRegistered?: () => void;
 }
 
 /**
@@ -295,6 +303,19 @@ export async function loadPlugins({
   });
   registerApiRoute(rootRouter, apiHandler);
 
+  // Routes are now registered on the root router. Signal readiness so the
+  // server can stop blocking incoming requests in `waitForInit()`. We open
+  // the gate here (BEFORE Phase 2 / Phase 3) so that:
+  //   - the static module-load endpoints (/api/plugins, /api/about, …) stop
+  //     hanging behind the boot gate;
+  //   - cross-plugin RPC calls made from `afterPluginsReady` can self-loop
+  //     through the HTTP server without deadlocking on init completion.
+  // Plugin RPC routers come online incrementally as each plugin's Phase 2
+  // init runs; requests targeting a not-yet-initialized plugin fall through
+  // to the api-router's "Plugin metadata not found" 500, which is the
+  // pre-existing behavior and is preferable to a multi-second hang.
+  deps.onApiRouteRegistered?.();
+
   for (const id of sortedIds) {
     const p = pendingInits.find((x) => x.metadata.pluginId === id)!;
     rootLogger.info(`🚀 Initializing ${p.metadata.pluginId}...`);

package/src/plugin-manager.ts

@@ -3,6 +3,7 @@ import { adminPool, db } from "./db";
 import { ServiceRegistry } from "./services/service-registry";
 import type { CoreCollectorRegistry } from "./services/collector-registry";
 import type { WebSocketRouteStoreImpl } from "./services/ws-route-registry";
+import type { CoreReadinessRegistry } from "./services/readiness-registry";
 import {
   BackendPlugin,
   ServiceRef,
@@ -54,7 +55,21 @@ export class PluginManager {
   // Global WebSocket route store for server-level routing
   private wsStore: WebSocketRouteStoreImpl;
 
+  // Global readiness registry — plugins contribute probes, /ready aggregates them
+  private readinessRegistry: CoreReadinessRegistry;
+
+  // Resolves once `/api/:pluginId/*` is registered on the root router and
+  // Phase 2 (per-plugin init) is starting. The HTTP server awaits this
+  // promise to know when it is safe to stop gating incoming requests.
+  // Held as a deferred so the listener (server) can be wired up before
+  // loadPlugins() runs.
+  private resolveRoutesReady!: () => void;
+  readonly routesReadyPromise: Promise<void>;
+
   constructor() {
+    this.routesReadyPromise = new Promise<void>((resolve) => {
+      this.resolveRoutesReady = resolve;
+    });
     const registries = registerCoreServices({
       registry: this.registry,
       adminPool,
@@ -64,6 +79,15 @@ export class PluginManager {
     });
     this.collectorRegistry = registries.collectorRegistry;
     this.wsStore = registries.wsStore;
+    this.readinessRegistry = registries.readinessRegistry;
+  }
+
+  /**
+   * Get the global readiness registry so the server-level /ready endpoint
+   * can aggregate plugin-contributed probes.
+   */
+  getReadinessRegistry(): CoreReadinessRegistry {
+    return this.readinessRegistry;
   }
 
   /**
@@ -124,8 +148,13 @@ export class PluginManager {
         pluginMetadataRegistry: this.pluginMetadataRegistry,
         cleanupHandlers: this.cleanupHandlers,
         pluginContractRegistry: this.pluginContractRegistry,
+        onApiRouteRegistered: () => this.resolveRoutesReady(),
       },
     });
+    // Defensive: if loadPlugins returned without ever calling the callback
+    // (e.g. zero plugins discovered and no api route registered), unblock
+    // the server gate anyway — by this point Hono is fully configured.
+    this.resolveRoutesReady();
   }
 
   /**

package/src/router-incremental.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "bun:test";
+import { Hono } from "hono";
+import { TrieRouter } from "hono/router/trie-router";
+
+/**
+ * Regression test for the "Hono router was already initialized" bug.
+ *
+ * Hono's default SmartRouter freezes its matcher on first request: any later
+ * `app.get/all/...` throws "Can not add a route since the matcher is already
+ * built". Plugins register routes during init() (and at runtime via
+ * loadSinglePlugin), so we use TrieRouter — which is incremental. If anyone
+ * ever swaps the router back to default, this test fails fast.
+ *
+ * See core/backend/src/index.ts where TrieRouter is wired up.
+ */
+describe("Hono router (TrieRouter) supports incremental route registration", () => {
+  it("accepts routes added after the first request", async () => {
+    const app = new Hono({ router: new TrieRouter() });
+    app.get("/early", (c) => c.text("early"));
+
+    // Trigger matcher build (this is what freezes SmartRouter).
+    const r1 = await app.fetch(new Request("http://x/early"));
+    expect(await r1.text()).toBe("early");
+
+    // Add a route AFTER the matcher is "built". On SmartRouter this throws.
+    app.get("/late", (c) => c.text("late"));
+
+    const r2 = await app.fetch(new Request("http://x/late"));
+    expect(r2.status).toBe(200);
+    expect(await r2.text()).toBe("late");
+  });
+
+  it("accepts a parameterized route added after a request", async () => {
+    const app = new Hono({ router: new TrieRouter() });
+    app.get("/seed", (c) => c.text("seed"));
+    await app.fetch(new Request("http://x/seed"));
+
+    // This is the actual production scenario: /api/:pluginId/* is registered
+    // inside loadPlugins() during init, well after the first request may have
+    // already been handled.
+    app.all("/api/:pluginId/*", (c) =>
+      c.json({ pluginId: c.req.param("pluginId") }),
+    );
+
+    const r = await app.fetch(new Request("http://x/api/healthcheck/foo"));
+    expect(r.status).toBe(200);
+    expect(await r.json()).toEqual({ pluginId: "healthcheck" });
+  });
+});

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

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, mock } from "bun:test";
+import {
+  CoreReadinessRegistry,
+  createScopedReadinessRegistry,
+} from "./readiness-registry";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+const mockLogger = createMockLogger();
+mock.module("../logger", () => ({
+  rootLogger: mockLogger,
+}));
+
+describe("CoreReadinessRegistry", () => {
+  let registry: CoreReadinessRegistry;
+
+  beforeEach(() => {
+    registry = new CoreReadinessRegistry();
+  });
+
+  it("starts empty", () => {
+    expect(registry.isEmpty()).toBe(true);
+  });
+
+  it("evaluates to ready=true with no probes", async () => {
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.checks).toHaveLength(0);
+  });
+
+  it("aggregates passing probes", async () => {
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: true }),
+    });
+    registry.register({
+      name: "queue",
+      check: async () => ({ ok: true }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.checks).toHaveLength(2);
+    expect(snapshot.checks.every((c) => c.ok)).toBe(true);
+  });
+
+  it("ready=false when a critical probe fails", async () => {
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: false, message: "down" }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.checks[0].message).toBe("down");
+  });
+
+  it("ready=true when only a non-critical probe fails", async () => {
+    registry.register({
+      name: "warmup",
+      critical: false,
+      check: async () => ({ ok: false }),
+    });
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: true }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(true);
+  });
+
+  it("treats thrown probes as failed and surfaces the error", async () => {
+    registry.register({
+      name: "boom",
+      check: async () => {
+        throw new Error("kaboom");
+      },
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.checks[0].ok).toBe(false);
+    expect(snapshot.checks[0].error).toBe("kaboom");
+  });
+
+  it("overwrites duplicate names with a warning", async () => {
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: false }),
+    });
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: true }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.checks).toHaveLength(1);
+    expect(snapshot.checks[0].ok).toBe(true);
+  });
+
+  it("runs probes in parallel (total time ~ slowest probe)", async () => {
+    const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+    registry.register({
+      name: "slow-1",
+      check: async () => {
+        await delay(50);
+        return { ok: true };
+      },
+    });
+    registry.register({
+      name: "slow-2",
+      check: async () => {
+        await delay(50);
+        return { ok: true };
+      },
+    });
+    const start = Date.now();
+    await registry.evaluate();
+    const elapsed = Date.now() - start;
+    // Sequential would be ~100ms; parallel should be ~50ms.
+    expect(elapsed).toBeLessThan(95);
+  });
+
+  it("scoped registry forwards register() to the global", () => {
+    const scoped = createScopedReadinessRegistry(registry);
+    scoped.register({ name: "x", check: async () => ({ ok: true }) });
+    expect(registry.isEmpty()).toBe(false);
+  });
+});

package/src/services/readiness-registry.ts

@@ -0,0 +1,103 @@
+import type {
+  ReadinessCheck,
+  ReadinessCheckResult,
+  ReadinessRegistry,
+} from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
+import { rootLogger } from "../logger";
+
+/**
+ * Snapshot returned to /ready callers.
+ */
+export interface ReadinessSnapshot {
+  ready: boolean;
+  checks: Array<{
+    name: string;
+    critical: boolean;
+    ok: boolean;
+    message?: string;
+    /** Set when the probe threw (treated as ok=false for critical checks). */
+    error?: string;
+    /** Wall-clock duration for the probe (milliseconds). */
+    durationMs: number;
+  }>;
+}
+
+/**
+ * Core implementation backing both `coreServices.readinessRegistry` (plugin-facing)
+ * and the `/ready` endpoint (server-facing). Plugins call `register`; the server
+ * calls `evaluate()`.
+ */
+export class CoreReadinessRegistry {
+  private checks: ReadinessCheck[] = [];
+
+  register(check: ReadinessCheck): void {
+    if (this.checks.some((c) => c.name === check.name)) {
+      rootLogger.warn(
+        `ReadinessRegistry: probe '${check.name}' is already registered. Overwriting.`,
+      );
+      this.checks = this.checks.filter((c) => c.name !== check.name);
+    }
+    this.checks.push(check);
+    rootLogger.debug(
+      `   -> Registered readiness probe '${check.name}' (critical=${check.critical ?? true})`,
+    );
+  }
+
+  /**
+   * Run every probe in parallel. Critical failures set `ready = false`.
+   * Throws are caught and reported as `ok: false`.
+   */
+  async evaluate(): Promise<ReadinessSnapshot> {
+    const results = await Promise.all(
+      this.checks.map(async (c) => {
+        const start = performance.now();
+        const critical = c.critical ?? true;
+        try {
+          const r: ReadinessCheckResult = await c.check();
+          return {
+            name: c.name,
+            critical,
+            ok: r.ok,
+            message: r.message,
+            durationMs: Math.round(performance.now() - start),
+          };
+        } catch (error) {
+          return {
+            name: c.name,
+            critical,
+            ok: false,
+            error: extractErrorMessage(error, String(error)),
+            durationMs: Math.round(performance.now() - start),
+          };
+        }
+      }),
+    );
+
+    const ready = results.every((r) => r.ok || !r.critical);
+    return { ready, checks: results };
+  }
+
+  /**
+   * Returns true while no probes are registered. Used to give a stable answer
+   * before plugins have had a chance to register their checks.
+   */
+  isEmpty(): boolean {
+    return this.checks.length === 0;
+  }
+}
+
+/**
+ * Plugin-facing scoped view (currently identical to the underlying registry —
+ * we intentionally don't namespace probe names by plugin so operators can read
+ * them at a glance, but plugins are encouraged to prefix their own names).
+ */
+export function createScopedReadinessRegistry(
+  global: CoreReadinessRegistry,
+): ReadinessRegistry {
+  return {
+    register(check: ReadinessCheck) {
+      global.register(check);
+    },
+  };
+}

package/tsconfig.json

@@ -2,5 +2,37 @@
   "extends": "@checkstack/tsconfig/backend.json",
   "include": [
     "src"
+  ],
+  "references": [
+    {
+      "path": "../api-docs-common"
+    },
+    {
+      "path": "../auth-common"
+    },
+    {
+      "path": "../backend-api"
+    },
+    {
+      "path": "../cache-api"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../drizzle-helper"
+    },
+    {
+      "path": "../queue-api"
+    },
+    {
+      "path": "../signal-backend"
+    },
+    {
+      "path": "../signal-common"
+    },
+    {
+      "path": "../test-utils-backend"
+    }
   ]
-}
+}