@spfn/core 0.3.0-beta.1 → 0.3.0-beta.11

package/dist/server/index.js

@@ -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;
@@ -1076,6 +1101,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 +1339,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 +1353,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 +1475,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 +1486,7 @@ function buildStartupConfig(config, timeouts) {
     },
     healthCheck: healthCheckEnabled ? {
       enabled: true,
+      corePath: CORE_HEALTH_PATH,
       path: healthCheckPath,
       detailed: healthCheckDetailed
     } : { enabled: false },
@@ -1467,6 +1505,378 @@ function buildStartupConfig(config, timeouts) {
   };
 }
 
+// src/route/route-builder.ts
+var RouteBuilder = class _RouteBuilder {
+  _method;
+  _path;
+  _input;
+  _interceptor;
+  _middlewares;
+  _skipMiddlewares;
+  _contract;
+  /**
+   * 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;
+    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 });
+  }
+  /**
+   * 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,
+      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(routes, packageRouters = [], globalMiddlewares = [], contractVersion = null) {
+  return {
+    routes,
+    _routes: routes,
+    _packageRouters: packageRouters,
+    _globalMiddlewares: globalMiddlewares,
+    _contractVersion: contractVersion,
+    packages(routers) {
+      const newPackageRouters = [...this._packageRouters, ...routers];
+      for (const pkgRouter of routers) {
+        if (pkgRouter._packageRouters?.length > 0) {
+          newPackageRouters.push(...pkgRouter._packageRouters);
+        }
+      }
+      return createRouterInstance(
+        this.routes,
+        newPackageRouters,
+        this._globalMiddlewares,
+        this._contractVersion
+      );
+    },
+    use(middlewares) {
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        [...this._globalMiddlewares, ...middlewares],
+        this._contractVersion
+      );
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        this._globalMiddlewares,
+        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 defineRouter(routes) {
+  return createRouterInstance(routes);
+}
+
+// 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 +1919,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 +1969,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 +2015,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 +2099,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) {
@@ -1791,6 +2275,20 @@ 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/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,19 +2296,38 @@ 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;
+}
+function collectJobs(router, prefix = "") {
+  return collectJobEntries(router, prefix).map((entry) => entry.job);
 }
-var jobLogger2 = logger.child("@spfn/core:job");
+var jobLogger3 = logger.child("@spfn/core:job");
 function getEventQueueName(eventName) {
   return `event:${eventName}`;
 }
@@ -1831,11 +2348,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 +2361,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 +2372,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 +2451,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 +2465,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 +2500,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 +2530,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 +2538,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 +2839,45 @@ 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;
+}
 
 // src/server/validation.ts
 function validateServerConfig(config) {
@@ -2333,10 +2926,12 @@ 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();
@@ -2400,8 +2995,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 +3013,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,
@@ -2961,6 +3576,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 +3602,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 +3723,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
    */
@@ -3184,6 +3828,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