@spfn/core 0.3.0-beta.2 → 0.3.0-beta.21

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { env } from '@spfn/core/config';
+import { env, registry } from '@spfn/core/config';
 import { existsSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
 import { parse } from 'dotenv';
@@ -11,11 +11,13 @@ import { setDefaultSafeFetchPolicy } from '@spfn/core/security';
 import { streamSSE } from 'hono/streaming';
 import { randomBytes, createHash } from 'crypto';
 import { Agent, setGlobalDispatcher } from 'undici';
-import { initDatabase, getDatabase, hasMigrationTargets, collectMigrationStatus, countPendingMigrations, pendingMigrationTargets, formatPendingMigrations, pendingMigrationsSummary, RUN_MIGRATIONS_HINT, migrationTargets, closeDatabase } from '@spfn/core/db';
+import { initDatabase, getDatabase, hasMigrationTargets, collectMigrationStatus, countPendingMigrations, pendingMigrationTargets, formatPendingMigrations, pendingMigrationsSummary, RUN_MIGRATIONS_HINT, closeDatabase, migrationTargets } from '@spfn/core/db';
 import { initCache, getCache, closeCache } from '@spfn/core/cache';
+import { FormatRegistry, Type } from '@sinclair/typebox';
 import { serve } from '@hono/node-server';
 import PgBoss from 'pg-boss';
 import { networkInterfaces } from 'os';
+import { pathToFileURL } from 'url';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -353,9 +355,10 @@ function parseEnvFile(filePath) {
   return parse(readFileSync(filePath, "utf-8"));
 }
 function loadEnv(options = {}) {
+  const nodeEnvAtEntry = process.env.NODE_ENV;
   const {
     cwd = process.cwd(),
-    nodeEnv = process.env.NODE_ENV || "local",
+    nodeEnv = nodeEnvAtEntry || "local",
     server = true,
     debug = false,
     override = false
@@ -385,8 +388,30 @@ function loadEnv(options = {}) {
     envLogger.debug(`Loaded env files: ${loadedFiles.join(", ")}`);
     envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);
   }
+  warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, options.nodeEnv, nodeEnv);
   return { loadedFiles, loadedKeys };
 }
+function warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, explicitNodeEnv, resolvedNodeEnv) {
+  if (nodeEnvAtEntry || explicitNodeEnv) {
+    return;
+  }
+  const declared = process.env.NODE_ENV;
+  if (!declared) {
+    envLogger.warn(
+      `NODE_ENV is not set anywhere; env files were resolved for "${resolvedNodeEnv}". Set NODE_ENV in the process environment to choose the file set.`
+    );
+    return;
+  }
+  if (declared === resolvedNodeEnv) {
+    return;
+  }
+  if (!existsSync(resolve(cwd, `.env.${declared}`))) {
+    return;
+  }
+  envLogger.warn(
+    `.env.${declared} was NOT loaded: NODE_ENV was not set when the process started, so env files were resolved for "${resolvedNodeEnv}" before a file declared NODE_ENV=${declared}. Set NODE_ENV in the process environment, not in a .env file.`
+  );
+}
 
 // src/server/dotenv-loader.ts
 var warned = false;
@@ -619,6 +644,12 @@ async function authorizeEvents(subject, requestedEvents, authConfig) {
   }
   return allowed;
 }
+
+// src/event/sse/paths.ts
+var DEFAULT_SSE_STREAM_PATH = "/events/stream";
+function sseTokenPath(streamPath) {
+  return streamPath.replace(/\/[^/]+$/, "/token");
+}
 function hashToken(token) {
   return createHash("sha256").update(token).digest("hex");
 }
@@ -1076,6 +1107,12 @@ async function runMigrationBootGate(config, cwd = process.cwd()) {
   );
 }
 
+// src/server/namespace.ts
+var CORE_NAMESPACE = "/_core";
+var CORE_HEALTH_PATH = `${CORE_NAMESPACE}/health`;
+var CORE_TIME_PATH = `${CORE_NAMESPACE}/time`;
+var LEGACY_HEALTH_PATH = "/health";
+
 // src/server/shutdown-manager.ts
 var DEFAULT_HOOK_TIMEOUT = 1e4;
 var DEFAULT_HOOK_ORDER = 100;
@@ -1308,7 +1345,7 @@ async function readMigrationHealth() {
     targets: migrationTargets(snapshot.status)
   };
 }
-function createHealthCheckHandler(detailed) {
+function createHealthCheckHandler(detailed, infrastructure) {
   return async (c) => {
     const shutdownManager = getShutdownManager();
     if (shutdownManager.isShuttingDown()) {
@@ -1322,23 +1359,29 @@ function createHealthCheckHandler(detailed) {
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     if (detailed) {
+      const databaseDisabled = infrastructure?.database === false;
+      const redisDisabled = infrastructure?.redis === false;
       let dbStatus = "unknown";
       let dbError;
-      try {
-        const db = getDatabase();
+      if (databaseDisabled) {
+        dbStatus = "disabled";
+      } else {
         try {
-          await db.execute("SELECT 1");
-          dbStatus = "connected";
+          const db = getDatabase();
+          try {
+            await db.execute("SELECT 1");
+            dbStatus = "connected";
+          } catch (error) {
+            dbStatus = "error";
+            dbError = error instanceof Error ? error.message : String(error);
+          }
         } catch (error) {
-          dbStatus = "error";
-          dbError = error instanceof Error ? error.message : String(error);
+          dbStatus = "not_initialized";
+          dbError = "Database not available";
         }
-      } catch (error) {
-        dbStatus = "not_initialized";
-        dbError = "Database not available";
       }
-      const redis = getCache();
-      let redisStatus = redis ? "unknown" : "not_initialized";
+      const redis = redisDisabled ? null : getCache();
+      let redisStatus = redisDisabled ? "disabled" : redis ? "unknown" : "not_initialized";
       let redisError;
       if (redis) {
         try {
@@ -1438,7 +1481,7 @@ function buildStartupConfig(config, timeouts) {
   const middlewareConfig = config.middleware ?? {};
   const healthCheckConfig = config.healthCheck ?? {};
   const healthCheckEnabled = healthCheckConfig.enabled !== false;
-  const healthCheckPath = healthCheckConfig.path ?? "/health";
+  const healthCheckPath = healthCheckConfig.path;
   const healthCheckDetailed = healthCheckConfig.detailed ?? env.NODE_ENV === "development";
   return {
     middleware: {
@@ -1449,6 +1492,7 @@ function buildStartupConfig(config, timeouts) {
     },
     healthCheck: healthCheckEnabled ? {
       enabled: true,
+      corePath: CORE_HEALTH_PATH,
       path: healthCheckPath,
       detailed: healthCheckDetailed
     } : { enabled: false },
@@ -1467,6 +1511,438 @@ function buildStartupConfig(config, timeouts) {
   };
 }
 
+// src/route/route-builder.ts
+var RouteBuilder = class _RouteBuilder {
+  _method;
+  _path;
+  _input;
+  _interceptor;
+  _middlewares;
+  _skipMiddlewares;
+  _contract;
+  _effect;
+  _summary;
+  /**
+   * Create a new RouteBuilder with copied properties and optional overrides
+   */
+  clone(overrides) {
+    const builder = new _RouteBuilder();
+    builder._method = this._method;
+    builder._path = this._path;
+    builder._input = overrides?.input ?? this._input;
+    builder._interceptor = overrides?.interceptor ?? this._interceptor;
+    builder._middlewares = overrides?.middlewares ?? this._middlewares;
+    builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
+    builder._contract = overrides?.contract ?? this._contract;
+    builder._effect = overrides?.effect ?? this._effect;
+    builder._summary = overrides?.summary ?? this._summary;
+    return builder;
+  }
+  /**
+   * Define input schemas
+   *
+   * @example
+   * ```ts
+   * route.get('/users/:id')
+   *   .input({
+   *     params: Type.Object({ id: Type.String() }),
+   *     query: Type.Object({ page: Type.Number() }),
+   *     headers: Type.Object({ authorization: Type.String() })
+   *   })
+   *   .handler(async (c) => {
+   *     const { params, query, headers } = await c.data();
+   *     // params = { id: string }
+   *     // query = { page: number }
+   *     // headers = { authorization: string }
+   *   })
+   * ```
+   */
+  input(input) {
+    return this.clone({ input });
+  }
+  /**
+   * Define fields injected by interceptors
+   *
+   * These fields are:
+   * - Available in the handler (merged with input)
+   * - Excluded from client types (codegen uses only input)
+   * - Not validated by route input schema (injected by middleware)
+   *
+   * Use this when middleware/interceptors add fields to the request
+   * before it reaches the handler.
+   *
+   * @example
+   * ```ts
+   * // Auth interceptor injects crypto key fields
+   * route.post('/_auth/login')
+   *   .input({
+   *     body: Type.Object({
+   *       email: Type.String(),
+   *       password: Type.String()
+   *     })
+   *   })
+   *   .interceptor({
+   *     body: Type.Object({
+   *       publicKey: Type.String(),
+   *       keyId: Type.String(),
+   *       fingerprint: Type.String()
+   *     })
+   *   })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     // body type: { email, password, publicKey, keyId, fingerprint }
+   *     // Client only sees: { email, password }
+   *     return loginService(body);
+   *   });
+   * ```
+   */
+  interceptor(interceptor) {
+    return this.clone({ interceptor });
+  }
+  /**
+   * Add middlewares to the route
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  middleware(middlewares) {
+    return this.clone({ middlewares });
+  }
+  /**
+   * Add middlewares to the route (alias for `.middleware()`)
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  use(middlewares) {
+    return this.middleware(middlewares);
+  }
+  /**
+   * Skip server-level named middlewares
+   *
+   * Useful for public endpoints that should bypass auth or rate limiting
+   *
+   * @param middlewareNames - Array of middleware names to skip, or '*' to skip all
+   *
+   * @example
+   * ```ts
+   * // Skip specific middlewares
+   * route.get('/status')
+   *   .skip(['auth', 'rateLimit'])
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   *
+   * // Skip only auth (still apply rate limiting)
+   * route.get('/public-data')
+   *   .skip(['auth'])
+   *   .handler(async (c) => { ... });
+   *
+   * // Skip all middlewares
+   * route.get('/public-health')
+   *   .skip('*')
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   * ```
+   */
+  skip(middlewareNames) {
+    return this.clone({ skipMiddlewares: middlewareNames });
+  }
+  /**
+   * Publish this route as a versioned contract operation
+   *
+   * Marks the route as a promise to clients that are compiled and deployed
+   * separately from the server — a mobile app, an external API consumer.
+   * The `@spfn/core:contract` generator writes every contracted route into
+   * `contracts/current.json`, and the build refuses a change that would break
+   * an already-released client.
+   *
+   * Routes without `.contract()` are unaffected: they simply do not appear in
+   * the contract. A web client needs nothing here — it derives its types from
+   * the router in the same build.
+   *
+   * @example
+   * ```ts
+   * export const getUser = route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .contract({
+   *     since: '1.2.0',
+   *     auth: 'clientProofV1',
+   *     requiresSession: true,
+   *     response: Type.Object({
+   *       id: Type.String(),
+   *       name: Type.String(),
+   *       email: Type.Optional(Type.String()),
+   *     }),
+   *   })
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  contract(contract) {
+    return this.clone({ contract });
+  }
+  /**
+   * Declare what invoking this route does
+   *
+   * Read by a command surface (`@spfn/core/surface`, `@spfn/core/ops`),
+   * which announces it in its manifest so a machine caller can tell a read
+   * from a write before it calls — `spfn ops call` asks for `--yes` before a
+   * `destructive` command. A surface built with `defineSurface` refuses an
+   * app command that does not declare one; on `/_ops` it is optional.
+   *
+   * Nothing else reads it: codegen, the route map, and the contract are
+   * unaffected, and a route outside any surface simply carries it.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .input({ body: PageAddBody })
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  effect(effect) {
+    return this.clone({ effect });
+  }
+  /**
+   * Describe this route in one line for a command surface's manifest
+   *
+   * A surface announces it beside the command in `spfn ops list` and
+   * `--describe`, and refuses one that is empty or longer than 500
+   * characters. Codegen, the route map, and the contract ignore it. On a
+   * module command the module's own summary wins.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  summary(summary) {
+    return this.clone({ summary });
+  }
+  /**
+   * Define handler function
+   *
+   * Response type is automatically inferred from the return value.
+   * Use helper methods like `c.created()`, `c.paginated()` for proper type inference.
+   *
+   * @example
+   * ```ts
+   * // Direct return - type inferred from data
+   * route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { params } = await c.data();
+   *     return await getUser(params.id); // Type: User
+   *   })
+   *
+   * // Using c.created() - returns data with 201 status, type preserved
+   * route.post('/users')
+   *   .input({ body: Type.Object({ name: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     return c.created(await createUser(body)); // Type: User
+   *   })
+   *
+   * // Using c.paginated() - returns PaginatedResult<T>
+   * route.get('/users')
+   *   .handler(async (c) => {
+   *     const users = await getUsers();
+   *     return c.paginated(users, 1, 20, 100); // Type: PaginatedResult<User>
+   *   })
+   *
+   * // Using c.noContent() - returns void
+   * route.delete('/users/:id')
+   *   .handler(async (c) => {
+   *     await deleteUser(params.id);
+   *     return c.noContent(); // Type: void
+   *   })
+   *
+   * // Using c.json() - returns Response (type inference lost)
+   * // Use only when you need custom status codes not covered by helpers
+   * route.get('/custom')
+   *   .handler(async (c) => {
+   *     return c.json({ data }, 418); // Type: Response
+   *   })
+   * ```
+   */
+  handler(fn) {
+    return {
+      method: this._method,
+      path: this._path,
+      input: this._input,
+      interceptor: this._interceptor,
+      middlewares: this._middlewares,
+      skipMiddlewares: this._skipMiddlewares,
+      contract: this._contract,
+      ...this._effect !== void 0 ? { effect: this._effect } : {},
+      ...this._summary !== void 0 ? { summary: this._summary } : {},
+      handler: fn,
+      _input: {},
+      _interceptor: {},
+      _response: {}
+    };
+  }
+};
+function createMethodRoute(method) {
+  return (path) => {
+    const builder = new RouteBuilder();
+    builder._method = method;
+    builder._path = path;
+    return builder;
+  };
+}
+var route = {
+  get: createMethodRoute("GET"),
+  post: createMethodRoute("POST"),
+  put: createMethodRoute("PUT"),
+  patch: createMethodRoute("PATCH"),
+  delete: createMethodRoute("DELETE")
+};
+
+// src/route/router.ts
+function createRouterInstance(state2) {
+  return {
+    routes: state2.routes,
+    _routes: state2.routes,
+    _packageRouters: state2.packageRouters,
+    _globalMiddlewares: state2.globalMiddlewares,
+    _contractVersion: state2.contractVersion,
+    _publishesRouteMap: state2.publishesRouteMap,
+    packages(routers) {
+      const newPackageRouters = [...state2.packageRouters, ...routers];
+      for (const pkgRouter of routers) {
+        if (pkgRouter._packageRouters?.length > 0) {
+          newPackageRouters.push(...pkgRouter._packageRouters);
+        }
+      }
+      assertDistinctSurfaces(newPackageRouters);
+      return createRouterInstance({ ...state2, packageRouters: newPackageRouters });
+    },
+    use(middlewares) {
+      return createRouterInstance({
+        ...state2,
+        globalMiddlewares: [...state2.globalMiddlewares, ...middlewares]
+      });
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return createRouterInstance({ ...state2, contractVersion: version });
+    }
+  };
+}
+function assertContractVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(version)) {
+    throw new Error(
+      `contractVersion("${version}") is not a version of the form major.minor.patch. The released snapshot is named from this value and releases are compared by it.`
+    );
+  }
+}
+function assertDistinctSurfaces(packageRouters) {
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const router of packageRouters) {
+    const namespace = router._surfaceNamespace;
+    if (namespace === void 0) {
+      continue;
+    }
+    if (namespaces.has(namespace)) {
+      throw new Error(
+        `.packages() mounts two command surfaces on "${namespace}". Both serve ${namespace}/_manifest, so the second one's commands would answer while no manifest lists them. Mount one router per namespace.`
+      );
+    }
+    namespaces.add(namespace);
+  }
+}
+function defineRouter(routes) {
+  return createRouterInstance({
+    routes,
+    packageRouters: [],
+    globalMiddlewares: [],
+    contractVersion: null,
+    publishesRouteMap: true
+  });
+}
+
+// src/route/validation.ts
+FormatRegistry.Set(
+  "email",
+  (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+);
+FormatRegistry.Set(
+  "uri",
+  (value) => /^https?:\/\/.+/.test(value)
+);
+FormatRegistry.Set(
+  "uuid",
+  (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+);
+FormatRegistry.Set(
+  "date",
+  (value) => /^\d{4}-\d{2}-\d{2}$/.test(value)
+);
+FormatRegistry.Set(
+  "date-time",
+  (value) => !isNaN(Date.parse(value))
+);
+
+// src/server/server-time.ts
+var CORE_TIME_OPERATION_ID = "core.time";
+var ServerTimeResponseSchema = Type.Object({
+  serverTimeMillis: Type.Integer()
+}, { additionalProperties: false });
+var systemServerClock = {
+  now: () => Date.now()
+};
+function createCoreTimeRoute(clock = systemServerClock) {
+  return route.get(CORE_TIME_PATH).skip("*").contract({
+    since: "0.3.0",
+    auth: "none",
+    requiresSession: false,
+    response: ServerTimeResponseSchema
+  }).handler(async (c) => {
+    const response = {
+      serverTimeMillis: clock.now()
+    };
+    c.raw.header("Cache-Control", "no-store");
+    return response;
+  });
+}
+var CORE_TIME_ROUTE = createCoreTimeRoute();
+function createCoreTimeRouter(clock) {
+  return defineRouter({
+    [CORE_TIME_OPERATION_ID]: createCoreTimeRoute(clock)
+  });
+}
+
 // src/server/create-server.ts
 var rateLimitApplied = /* @__PURE__ */ new WeakSet();
 async function createServer(config) {
@@ -1509,12 +1985,16 @@ async function createAutoConfiguredApp(config) {
   applyDefaultMiddleware(app, config, enableLogger, enableCors);
   await applyProxyGuard(app, config);
   applyRateLimit(config);
+  registerCoreTimeEndpoint(app, config);
   if (Array.isArray(config?.use)) {
     config.use.forEach((mw) => app.use("*", mw));
   }
-  registerHealthCheckEndpoint(app, config);
+  registerCoreHealthEndpoint(app, config);
   await executeBeforeRoutesHook(app, config);
-  await loadAppRoutes(app, config);
+  const appRoutes = await loadAppRoutes(app, config);
+  registerMovedHealthSignpost(app, config, appRoutes);
+  warnOnShadowedOptInPath(config, appRoutes);
+  warnOnCoreNamespaceRoutes(appRoutes);
   await registerSSEEndpoint(app, config);
   await executeAfterRoutesHook(app, config);
   if (enableErrorHandler) {
@@ -1555,7 +2035,10 @@ async function applyProxyGuard(app, config) {
       serverLogger.warn("Proxy-guard nonce: cache module unavailable \u2014 using in-memory store (single instance only)");
     }
   }
-  const autoSkip = [config?.healthCheck?.path ?? "/health"];
+  const autoSkip = [CORE_HEALTH_PATH, CORE_TIME_PATH, LEGACY_HEALTH_PATH];
+  if (config?.healthCheck?.path) {
+    autoSkip.push(config.healthCheck.path);
+  }
   if (config?.events) {
     autoSkip.push(config.eventsConfig?.path ?? "/events/stream");
   }
@@ -1598,15 +2081,79 @@ function applyOutboundFetch(config) {
   const policy = config?.outboundFetch ?? { blockPrivateIps: env.SAFE_FETCH_BLOCK_PRIVATE_IPS };
   setDefaultSafeFetchPolicy(policy);
 }
-function registerHealthCheckEndpoint(app, config) {
+function resolveHealthCheck(config) {
   const healthCheckConfig = config?.healthCheck ?? {};
-  const healthCheckEnabled = healthCheckConfig.enabled !== false;
-  const healthCheckPath = healthCheckConfig.path ?? "/health";
-  const healthCheckDetailed = healthCheckConfig.detailed ?? process.env.NODE_ENV === "development";
-  if (healthCheckEnabled) {
-    app.get(healthCheckPath, createHealthCheckHandler(healthCheckDetailed));
-    serverLogger.debug(`Health check endpoint enabled at ${healthCheckPath}`);
+  return {
+    enabled: healthCheckConfig.enabled !== false,
+    // No default. An unset `path` means the endpoint answers at
+    // CORE_HEALTH_PATH and nowhere else — a default here is what used to put
+    // it on /health without anyone asking.
+    path: healthCheckConfig.path,
+    detailed: healthCheckConfig.detailed ?? process.env.NODE_ENV === "development"
+  };
+}
+function registerCoreTimeEndpoint(app, config) {
+  registerRoutes(app, createCoreTimeRouter(config?.serverTime?.clock));
+  serverLogger.debug(`Server time endpoint enabled at ${CORE_TIME_PATH}`);
+}
+function registerCoreHealthEndpoint(app, config) {
+  const { enabled, path, detailed } = resolveHealthCheck(config);
+  if (!enabled) {
+    return;
+  }
+  const handler = createHealthCheckHandler(detailed, config?.infrastructure);
+  app.get(CORE_HEALTH_PATH, handler);
+  serverLogger.debug(`Health check endpoint enabled at ${CORE_HEALTH_PATH}`);
+  if (path && path !== CORE_HEALTH_PATH) {
+    app.get(path, handler);
+    serverLogger.debug(`Health check endpoint also answering at ${path}, as configured`);
+  }
+}
+function registerMovedHealthSignpost(app, config, appRoutes) {
+  const { enabled, path } = resolveHealthCheck(config);
+  if (!enabled || path === LEGACY_HEALTH_PATH) {
+    return;
+  }
+  if (appRoutes.some((r) => r.method === "GET" && r.path === LEGACY_HEALTH_PATH)) {
+    return;
   }
+  let warned2 = false;
+  app.get(LEGACY_HEALTH_PATH, (c) => {
+    if (!warned2) {
+      warned2 = true;
+      serverLogger.warn(
+        `\u26A0\uFE0F  GET ${LEGACY_HEALTH_PATH} is answering 410: @spfn/core no longer serves it. Point your readiness probe, Dockerfile HEALTHCHECK and load balancer at ${CORE_HEALTH_PATH}, or restore this path with healthCheck({ path: '${LEGACY_HEALTH_PATH}' }). This notice is removed in the next release.`
+      );
+    }
+    return c.json({
+      error: "health endpoint moved",
+      movedTo: CORE_HEALTH_PATH,
+      detail: `@spfn/core no longer serves ${LEGACY_HEALTH_PATH}. Point your readiness probe, Dockerfile HEALTHCHECK and load balancer at ${CORE_HEALTH_PATH}, or restore this path with healthCheck({ path: '${LEGACY_HEALTH_PATH}' }).`
+    }, 410);
+  });
+}
+function warnOnShadowedOptInPath(config, appRoutes) {
+  const { enabled, path } = resolveHealthCheck(config);
+  if (!enabled || !path || path === CORE_HEALTH_PATH) {
+    return;
+  }
+  const shadowed = appRoutes.filter((r) => r.method === "GET" && r.path === path);
+  if (shadowed.length === 0) {
+    return;
+  }
+  serverLogger.warn(
+    `\u26A0\uFE0F  ${shadowed.map((r) => r.name).join(", ")} never runs: GET ${path} is served by the built-in health endpoint, which healthCheck({ path }) asked for and which is registered before app routes. Drop that option, or move the route to a path your app owns.`
+  );
+}
+function warnOnCoreNamespaceRoutes(appRoutes) {
+  const inside = appRoutes.filter((r) => r.path === CORE_NAMESPACE || r.path.startsWith(`${CORE_NAMESPACE}/`));
+  if (inside.length === 0) {
+    return;
+  }
+  const names = inside.map((r) => `${r.name} (${r.method} ${r.path})`).join(", ");
+  serverLogger.warn(
+    `\u26A0\uFE0F  ${names} never runs: ${CORE_NAMESPACE}/ belongs to @spfn/core and its endpoints are registered before app routes. Move the route to a path your app owns.`
+  );
 }
 async function executeBeforeRoutesHook(app, config) {
   if (config?.lifecycle?.beforeRoutes) {
@@ -1618,9 +2165,12 @@ async function loadAppRoutes(app, config) {
   if (config?.routes) {
     const routes = registerRoutes(app, config.routes, config.middlewares);
     logRegisteredRoutes(routes, debug);
-  } else if (debug) {
+    return routes;
+  }
+  if (debug) {
     serverLogger.warn("\u26A0\uFE0F  No routes configured. Use defineServerConfig().routes() to register routes.");
   }
+  return [];
 }
 function logRegisteredRoutes(routes, debug) {
   if (routes.length === 0) {
@@ -1647,8 +2197,9 @@ async function registerSSEEndpoint(app, config) {
     return;
   }
   const eventsConfig = config.eventsConfig ?? {};
-  const streamPath = eventsConfig.path ?? "/events/stream";
+  const streamPath = eventsConfig.path ?? DEFAULT_SSE_STREAM_PATH;
   const authConfig = eventsConfig.auth;
+  assertEventContractServed(config.events._contract, streamPath, !!authConfig?.enabled);
   const debug = isDebugMode(config);
   let tokenManager;
   if (authConfig?.enabled) {
@@ -1671,7 +2222,7 @@ async function registerSSEEndpoint(app, config) {
       ttl: authConfig.tokenTtl,
       store
     });
-    const tokenPath = streamPath.replace(/\/[^/]+$/, "/token");
+    const tokenPath = sseTokenPath(streamPath);
     const mwHandlers = resolveEndpointMiddlewares(config).map((mw) => mw.handler);
     const getSubject = authConfig.getSubject ?? ((c) => c.get("auth")?.userId ?? null);
     app.on(["POST"], [tokenPath], ...mwHandlers, async (c) => {
@@ -1700,6 +2251,23 @@ async function registerSSEEndpoint(app, config) {
     });
   }
 }
+function assertEventContractServed(contract, streamPath, authEnabled) {
+  if (!contract) {
+    return;
+  }
+  const contractPath = contract.streamPath ?? DEFAULT_SSE_STREAM_PATH;
+  if (contractPath !== streamPath) {
+    throw new Error(
+      `SSE event router contract declares streamPath ${contractPath} but .events() registers ${streamPath}; the contract would describe a path the server does not serve`
+    );
+  }
+  const servedAuth = authEnabled ? "tokenExchange" : "none";
+  if (contract.auth !== servedAuth) {
+    throw new Error(
+      `SSE event router contract declares auth ${contract.auth} but .events() serves auth ${servedAuth}; the contract would describe an auth mode the server does not serve`
+    );
+  }
+}
 function isDebugMode(config) {
   return config?.debug ?? process.env.NODE_ENV === "development";
 }
@@ -1791,6 +2359,31 @@ function shouldSweepOrphanSchedules() {
   return getBossConfig()?.sweepOrphanSchedules ?? false;
 }
 
+// src/job/queue-policy.ts
+function resolveQueuePolicy(job2) {
+  if (job2.options?.policy) {
+    return job2.options.policy;
+  }
+  if (job2.runOnce || job2.options?.singletonKey) {
+    return "exclusive";
+  }
+  return "standard";
+}
+
+// src/job/retry-options.ts
+function toPgBossRetryOptions(options) {
+  return {
+    retryLimit: options?.retryLimit ?? 3,
+    retryDelay: Math.ceil((options?.retryDelay ?? 1e3) / 1e3),
+    // Exponential backoff by default — a failed cohort (e.g. a provider 429)
+    // would otherwise all retry at the same fixed offset (thundering herd).
+    retryBackoff: options?.retryBackoff ?? true
+  };
+}
+
+// src/job/job-builder.ts
+logger.child("@spfn/core:job");
+
 // src/job/job-router.ts
 function isJobDef(value) {
   return value !== null && typeof value === "object" && "name" in value && "handler" in value && "send" in value && "run" in value;
@@ -1798,29 +2391,44 @@ function isJobDef(value) {
 function isJobRouter(value) {
   return value !== null && typeof value === "object" && "jobs" in value && "_jobs" in value;
 }
-function collectJobs(router, prefix = "") {
-  const jobs = [];
+function defineJobRouter(jobs) {
+  return {
+    jobs,
+    _jobs: jobs
+  };
+}
+function mergeJobRouters(base, extra) {
+  for (const key of Object.keys(extra.jobs)) {
+    if (key in base.jobs) {
+      throw new Error(
+        `jobs(): key "${key}" is already registered by an earlier .jobs() call; rename it or nest it under a domain router`
+      );
+    }
+  }
+  return defineJobRouter({ ...base.jobs, ...extra.jobs });
+}
+function collectJobEntries(router, prefix = "") {
+  const entries = [];
   for (const [key, value] of Object.entries(router.jobs)) {
-    const name = prefix ? `${prefix}.${key}` : key;
+    const path = prefix ? `${prefix}.${key}` : key;
     if (isJobRouter(value)) {
-      jobs.push(...collectJobs(value, name));
+      entries.push(...collectJobEntries(value, path));
     } else if (isJobDef(value)) {
-      jobs.push(value);
+      entries.push({ key: path, job: value });
     }
   }
-  return jobs;
+  return entries;
 }
-var jobLogger2 = logger.child("@spfn/core:job");
+function collectJobs(router, prefix = "") {
+  return collectJobEntries(router, prefix).map((entry) => entry.job);
+}
+var jobLogger3 = logger.child("@spfn/core:job");
 function getEventQueueName(eventName) {
   return `event:${eventName}`;
 }
 function getDefaultJobOptions(options) {
   return {
-    retryLimit: options?.retryLimit ?? 3,
-    retryDelay: options?.retryDelay ?? 1e3,
-    // Exponential backoff by default — a failed cohort (e.g. a provider 429)
-    // would otherwise all retry at the same fixed offset (thundering herd).
-    retryBackoff: options?.retryBackoff ?? true,
+    ...toPgBossRetryOptions(options),
     expireInSeconds: options?.expireInSeconds ?? 300
   };
 }
@@ -1831,11 +2439,12 @@ async function registerJobs(router) {
       "pg-boss not initialized. Call initBoss() before registerJobs()"
     );
   }
+  assertUniqueJobNames(router);
   const jobs = collectJobs(router);
   const clearOnStart = shouldClearOnStart();
-  jobLogger2.info(`Registering ${jobs.length} job(s)...`);
+  jobLogger3.info(`Registering ${jobs.length} job(s)...`);
   if (clearOnStart) {
-    jobLogger2.info("Clearing existing jobs before registration...");
+    jobLogger3.info("Clearing existing jobs before registration...");
     for (const job2 of jobs) {
       await boss.deleteAllJobs(job2.name);
       if (job2.subscribedEvent) {
@@ -1843,7 +2452,7 @@ async function registerJobs(router) {
         await boss.deleteAllJobs(eventQueue);
       }
     }
-    jobLogger2.info("Existing jobs cleared");
+    jobLogger3.info("Existing jobs cleared");
   }
   await Promise.all(jobs.map((job2) => registerJob(job2)));
   for (const job2 of jobs) {
@@ -1854,42 +2463,77 @@ async function registerJobs(router) {
   if (shouldSweepOrphanSchedules()) {
     await sweepOrphanSchedules(boss);
   }
-  jobLogger2.info("All jobs registered successfully");
+  jobLogger3.info("All jobs registered successfully");
+}
+function assertUniqueJobNames(router) {
+  const keysByName = /* @__PURE__ */ new Map();
+  for (const { key, job: job2 } of collectJobEntries(router)) {
+    const existingKey = keysByName.get(job2.name);
+    if (existingKey) {
+      throw new Error(
+        `registerJobs(): job name "${job2.name}" is defined twice (keys "${existingKey}" and "${key}"); job names are pg-boss queue names and must be unique`
+      );
+    }
+    keysByName.set(job2.name, key);
+  }
 }
 var registeredCronNames = /* @__PURE__ */ new Set();
 async function sweepOrphanSchedules(boss) {
   if (registeredCronNames.size === 0) {
-    jobLogger2.debug("No cron jobs declared; skipping orphan schedule sweep");
+    jobLogger3.debug("No cron jobs declared; skipping orphan schedule sweep");
     return;
   }
   try {
     const schedules = await boss.getSchedules();
     const orphans = schedules.filter((schedule) => !registeredCronNames.has(schedule.name));
     if (orphans.length === 0) {
-      jobLogger2.debug("No orphan schedules found");
+      jobLogger3.debug("No orphan schedules found");
       return;
     }
     await Promise.all(orphans.map(async (orphan) => {
       try {
         await boss.unschedule(orphan.name, orphan.key);
-        jobLogger2.info(`Removed orphan schedule: ${orphan.name}`);
+        jobLogger3.info(`Removed orphan schedule: ${orphan.name}`);
       } catch (error) {
-        jobLogger2.error(`Failed to remove orphan schedule: ${orphan.name}`, {
+        jobLogger3.error(`Failed to remove orphan schedule: ${orphan.name}`, {
           error: error instanceof Error ? error.message : String(error)
         });
       }
     }));
   } catch (error) {
-    jobLogger2.error("Orphan schedule sweep failed", {
+    jobLogger3.error("Orphan schedule sweep failed", {
       error: error instanceof Error ? error.message : String(error)
     });
   }
 }
-async function ensureQueue(boss, queueName) {
-  await boss.createQueue(queueName);
+async function ensureQueue(boss, queueName, policy) {
+  await boss.createQueue(queueName, { policy });
+  const existing = await boss.getQueue(queueName);
+  if (!existing || existing.policy === policy) {
+    return;
+  }
+  if (shouldClearOnStart()) {
+    await boss.deleteQueue(queueName);
+    await boss.createQueue(queueName, { policy });
+    jobLogger3.info(`[Queue:${queueName}] policy ${existing.policy} \u2192 ${policy} (recreated: clearOnStart)`);
+    return;
+  }
+  jobLogger3.error(
+    `[Queue:${queueName}] policy mismatch: the queue exists as "${existing.policy}" but its jobs require "${policy}". Delete the queue in a quiet window (getBoss().deleteQueue('${queueName}') drops its job rows) or set clearOnStart in development; until then singletonKey/runOnce on this queue do not deduplicate`
+  );
+}
+function createQueueEnsurer(boss, policy) {
+  const ensured = /* @__PURE__ */ new Set();
+  return async (queueName) => {
+    if (ensured.has(queueName)) {
+      return;
+    }
+    ensured.add(queueName);
+    await ensureQueue(boss, queueName, policy);
+  };
 }
 async function executeJobHandler(job2, pgBossJob) {
-  jobLogger2.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
+  jobLogger3.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
   const startTime = Date.now();
   try {
     if (job2.inputSchema) {
@@ -1898,13 +2542,13 @@ async function executeJobHandler(job2, pgBossJob) {
       await job2.handler();
     }
     const duration = Date.now() - startTime;
-    jobLogger2.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
+    jobLogger3.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
       jobId: pgBossJob.id,
       duration
     });
   } catch (error) {
     const duration = Date.now() - startTime;
-    jobLogger2.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
+    jobLogger3.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
       jobId: pgBossJob.id,
       duration,
       error: error instanceof Error ? error.message : String(error)
@@ -1912,8 +2556,8 @@ async function executeJobHandler(job2, pgBossJob) {
     throw error;
   }
 }
-async function registerWorker(boss, job2, queueName) {
-  await ensureQueue(boss, queueName);
+async function registerWorker(boss, job2, queueName, ensureQueueOnce) {
+  await ensureQueueOnce(queueName);
   const batchSize = job2.options?.batchSize ?? 1;
   const pollingIntervalSeconds = job2.options?.pollingIntervalSeconds ?? env.JOB_POLLING_INTERVAL_SECONDS;
   await boss.work(
@@ -1947,28 +2591,28 @@ function connectEventToQueue(boss, job2, queueName) {
   eventDef._registerJobQueue(queueName, async (queue, payload) => {
     await boss.send(queue, payload, getDefaultJobOptions(job2.options));
   });
-  jobLogger2.debug(`[Job:${job2.name}] Connected to event: ${job2.subscribedEvent}`);
+  jobLogger3.debug(`[Job:${job2.name}] Connected to event: ${job2.subscribedEvent}`);
 }
-async function registerCronSchedule(boss, job2) {
+async function registerCronSchedule(boss, job2, ensureQueueOnce) {
   if (!job2.cronExpression) {
     return;
   }
-  jobLogger2.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
-  await ensureQueue(boss, job2.name);
+  jobLogger3.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
+  await ensureQueueOnce(job2.name);
   await boss.schedule(
     job2.name,
     job2.cronExpression,
     {},
     getDefaultJobOptions(job2.options)
   );
-  jobLogger2.info(`[Job:${job2.name}] Cron scheduled: ${job2.cronExpression}`);
+  jobLogger3.info(`[Job:${job2.name}] Cron scheduled: ${job2.cronExpression}`);
 }
-async function queueRunOnceJob(boss, job2) {
+async function queueRunOnceJob(boss, job2, ensureQueueOnce) {
   if (!job2.runOnce) {
     return;
   }
-  jobLogger2.debug(`[Job:${job2.name}] Queuing runOnce job`);
-  await ensureQueue(boss, job2.name);
+  jobLogger3.debug(`[Job:${job2.name}] Queuing runOnce job`);
+  await ensureQueueOnce(job2.name);
   await boss.send(
     job2.name,
     {},
@@ -1977,7 +2621,7 @@ async function queueRunOnceJob(boss, job2) {
       singletonKey: `runOnce:${job2.name}`
     }
   );
-  jobLogger2.info(`[Job:${job2.name}] runOnce job queued`);
+  jobLogger3.info(`[Job:${job2.name}] runOnce job queued`);
 }
 async function registerJob(job2) {
   const boss = getBoss();
@@ -1985,15 +2629,16 @@ async function registerJob(job2) {
     throw new Error("pg-boss not initialized");
   }
   const queueName = job2.subscribedEvent ? getEventQueueName(job2.subscribedEvent) : job2.name;
-  jobLogger2.debug(`Registering job: ${job2.name}`, {
+  jobLogger3.debug(`Registering job: ${job2.name}`, {
     queueName,
     subscribedEvent: job2.subscribedEvent
   });
-  await registerWorker(boss, job2, queueName);
+  const ensureQueueOnce = createQueueEnsurer(boss, resolveQueuePolicy(job2));
+  await registerWorker(boss, job2, queueName, ensureQueueOnce);
   connectEventToQueue(boss, job2, queueName);
-  await registerCronSchedule(boss, job2);
-  await queueRunOnceJob(boss, job2);
-  jobLogger2.debug(`Job registered: ${job2.name}`);
+  await registerCronSchedule(boss, job2, ensureQueueOnce);
+  await queueRunOnceJob(boss, job2, ensureQueueOnce);
+  jobLogger3.debug(`Job registered: ${job2.name}`);
 }
 var wsLogger = logger.child("@spfn/core:ws");
 function isOriginAllowed(origin, allowList) {
@@ -2285,6 +2930,89 @@ function printBanner(options) {
   }
   console.log("");
 }
+var PORT_DEFAULTS = {
+  server: 8790
+};
+var HOST_DEFAULT = "localhost";
+var CONFIG_FILE_NAMES = [
+  "spfn.config.js",
+  "spfn.config.mjs"
+];
+async function loadAppConfig(cwd = process.cwd()) {
+  for (const fileName of CONFIG_FILE_NAMES) {
+    const fullPath = join(cwd, fileName);
+    if (!existsSync(fullPath)) {
+      continue;
+    }
+    try {
+      const module = await import(pathToFileURL(fullPath).href);
+      return module.default ?? {};
+    } catch (error) {
+      console.warn(
+        `\u26A0\uFE0F  ${fileName} could not be imported \u2014 falling back to defaults for ports and host. ${error instanceof Error ? error.message : String(error)}`
+      );
+      return {};
+    }
+  }
+  return {};
+}
+function resolveServerAddress(config, deprecated = {}, env6 = process.env) {
+  return {
+    port: readPort(env6.SPFN_PORT) ?? config.ports?.server ?? deprecated.port ?? PORT_DEFAULTS.server,
+    host: env6.SPFN_HOST || config.host || deprecated.host || HOST_DEFAULT
+  };
+}
+function readPort(value) {
+  if (!value) {
+    return void 0;
+  }
+  const port = Number(value);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : void 0;
+}
+logger.child("@spfn/core:env-registry");
+function validateAllEnv(registries) {
+  const errors = [];
+  const warnings = [];
+  for (const registry of registries) {
+    const result = registry.validateAll();
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+// src/server/env-boot-check.ts
+function runEnvBootCheck(config) {
+  const result = validateAllEnv([registry, ...config.env?.registries ?? []]);
+  const errors = uniqueByMessage(result.errors);
+  const warnings = uniqueByMessage(result.warnings);
+  for (const warning of warnings) {
+    serverLogger.warn(`Environment: ${warning.message}`);
+  }
+  if (errors.length > 0) {
+    serverLogger.error(
+      `Environment validation failed (${errors.length}):
+` + errors.map((error) => `  - ${error.message}`).join("\n")
+    );
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+function uniqueByMessage(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  return entries.filter((entry) => {
+    const id = `${entry.key}
+${entry.message}`;
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
+}
 
 // src/server/validation.ts
 function validateServerConfig(config) {
@@ -2333,14 +3061,20 @@ var TIMEOUTS = {
   REDIS_CLOSE: 5e3};
 var CONFIG_FILE_PATHS = [
   ".spfn/server/server.config.mjs",
+  ".spfn/server/server.config.js",
   ".spfn/server/server.config",
   "src/server/server.config",
   "src/server/server.config.ts"
 ];
+var AUTHORED_CONFIG_PATH = "src/server/server.config.ts";
 var processHandlersRegistered = false;
 async function startServer(config) {
   loadEnv();
   const finalConfig = await loadAndMergeConfig(config);
+  if (!runEnvBootCheck(finalConfig).valid) {
+    serverLogger.error("Refusing to start: fix the environment variables listed above.");
+    process.exit(1);
+  }
   const { host, port, debug } = finalConfig;
   validateServerConfig(finalConfig);
   if (!host || !port) {
@@ -2400,8 +3134,7 @@ async function startServer(config) {
     throw error;
   }
 }
-async function loadAndMergeConfig(config) {
-  const cwd = process.cwd();
+async function loadAndMergeConfig(config, cwd = process.cwd()) {
   let fileConfig = {};
   let loadedConfigPath = null;
   for (const configPath of CONFIG_FILE_PATHS) {
@@ -2419,16 +3152,37 @@ async function loadAndMergeConfig(config) {
   }
   if (loadedConfigPath) {
     serverLogger.debug(`Loaded configuration from ${loadedConfigPath}`);
+  } else if (existsSync(join(cwd, AUTHORED_CONFIG_PATH))) {
+    serverLogger.warn(
+      `\u26A0\uFE0F  ${AUTHORED_CONFIG_PATH} exists but no configuration was loaded, so this server is running on defaults: no middlewares, no routes and no infrastructure settings from it. Run "spfn build" so the compiled config lands in .spfn/server/.`
+    );
   } else {
     serverLogger.debug("No configuration file found, using defaults");
   }
+  const appConfig = await loadAppConfig(cwd);
+  warnOnDeprecatedAddress(config, fileConfig);
+  const address = resolveServerAddress(appConfig, {
+    port: config?.port ?? fileConfig?.port,
+    host: config?.host ?? fileConfig?.host
+  });
   return {
     ...fileConfig,
     ...config,
-    port: config?.port ?? fileConfig?.port ?? env.PORT,
-    host: config?.host ?? fileConfig?.host ?? env.HOST
+    port: address.port,
+    host: address.host
   };
 }
+function warnOnDeprecatedAddress(config, fileConfig) {
+  const used = [
+    (config?.port ?? fileConfig?.port) !== void 0 ? ".port()" : null,
+    (config?.host ?? fileConfig?.host) !== void 0 ? ".host()" : null
+  ].filter(Boolean);
+  if (used.length > 0) {
+    serverLogger.warn(
+      `\u26A0\uFE0F  ${used.join(" and ")} in server.config is deprecated and will be removed. Move the address to spfn.config.js \u2014 \`ports: { next, server }\` and \`host\` \u2014 so the Dockerfile, the compose file and next.config can read the same value.`
+    );
+  }
+}
 function getInfrastructureConfig(config) {
   return {
     database: config.infrastructure?.database !== false,
@@ -2811,6 +3565,9 @@ function createServerlessApp(config) {
 }
 async function buildServerlessApp(rawConfig) {
   loadEnv();
+  if (!runEnvBootCheck(rawConfig ?? {}).valid) {
+    throw new Error("Environment validation failed \u2014 the missing or invalid keys are logged above.");
+  }
   const config = withServerlessDefaults(rawConfig);
   warnIfJobsConfigured(config);
   await initInfrastructure(config);
@@ -2961,6 +3718,20 @@ var ServerConfigBuilder = class {
   /**
    * Register background jobs router
    *
+   * May be called once per domain router: repeated calls **merge** into one
+   * router, the way `.routes()` composes. Calling it several times used to
+   * keep only the last router and register nothing else, without warning.
+   *
+   * The pg-boss `config` is per server, so pass it on one call only.
+   *
+   * Two names can collide, and both fail loudly:
+   * - a router **key** present in two calls throws here, at config time;
+   * - two jobs sharing a **`job.name`** (the pg-boss queue name) throw in
+   *   `registerJobs()` at boot, before any queue or worker is created.
+   *
+   * @throws if a router key was already registered by an earlier call
+   * @throws if `config` is given when an earlier call already gave one
+   *
    * @example
    * ```typescript
    * import { job, defineJobRouter } from '@spfn/core/job';
@@ -2973,12 +3744,18 @@ var ServerConfigBuilder = class {
    *
    * export default defineServerConfig()
    *   .routes(appRouter)
-   *   .jobs(jobRouter)
+   *   .jobs(jobRouter, { clearOnStart: isDev })   // config on one call only
+   *   .jobs(billingJobRouter)                     // merged, not replaced
    *   .build();
    * ```
    */
   jobs(router, config) {
-    this.config.jobs = router;
+    if (config && this.config.jobsConfig) {
+      throw new Error(
+        "jobs(): pg-boss config was already given by an earlier .jobs() call; pass it once"
+      );
+    }
+    this.config.jobs = this.config.jobs ? mergeJobRouters(this.config.jobs, router) : router;
     if (config) {
       this.config.jobsConfig = config;
     }
@@ -3088,6 +3865,15 @@ var ServerConfigBuilder = class {
     this.config.healthCheck = healthCheck;
     return this;
   }
+  /**
+   * Supply the clock used by the built-in `GET /_core/time` capability.
+   * Production servers normally keep the default `Date.now()` clock; this is
+   * exposed so tests can assert an exact wire value without replacing globals.
+   */
+  serverTime(serverTime) {
+    this.config.serverTime = serverTime;
+    return this;
+  }
   /**
    * Configure infrastructure initialization
    */
@@ -3110,6 +3896,25 @@ var ServerConfigBuilder = class {
     this.config.migrations = migrations;
     return this;
   }
+  /**
+   * Hand the app's env registries to the boot check
+   *
+   * `@spfn/core`'s own registry is always checked; the registries given here
+   * are checked with it, before the server listens.
+   *
+   * @example
+   * ```typescript
+   * import { envRegistry } from '@/server/config/env.config';
+   *
+   * export default defineServerConfig()
+   *     .env({ registries: [envRegistry] })
+   *     .build();
+   * ```
+   */
+  env(env6) {
+    this.config.env = env6;
+    return this;
+  }
   /**
    * Register workflow router for workflow orchestration
    *
@@ -3184,6 +3989,6 @@ function defineServerConfig() {
   return new ServerConfigBuilder();
 }
 
-export { PendingMigrationsError, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
+export { CORE_HEALTH_PATH, CORE_NAMESPACE, CORE_TIME_OPERATION_ID, CORE_TIME_PATH, CORE_TIME_ROUTE, PendingMigrationsError, ServerTimeResponseSchema, createCoreTimeRoute, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map