@spfn/core 0.2.0-beta.9 → 0.3.0-beta.10

package/dist/server/index.js

@@ -1,18 +1,23 @@
 import { env } from '@spfn/core/config';
-import { config } from 'dotenv';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
+import { parse } from 'dotenv';
+import { logger } from '@spfn/core/logger';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
-import { registerRoutes } from '@spfn/core/route';
-import { ErrorHandler, RequestLogger } from '@spfn/core/middleware';
+import { registerRoutes, defineMiddleware } from '@spfn/core/route';
+import { ErrorHandler, RequestLogger, setRateLimitPolicies, setRateLimitFailClosedDefault, rateLimit } from '@spfn/core/middleware';
+import { setDefaultSafeFetchPolicy } from '@spfn/core/security';
 import { streamSSE } from 'hono/streaming';
-import { logger } from '@spfn/core/logger';
-import { initDatabase, getDatabase, closeDatabase } from '@spfn/core/db';
+import { randomBytes, createHash } from 'crypto';
+import { Agent, setGlobalDispatcher } from 'undici';
+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;
@@ -94,6 +99,11 @@ function formatError(error) {
     const stackLines = error.stack.split("\n").slice(1);
     lines.push(...stackLines);
   }
+  if (error.cause instanceof Error) {
+    lines.push(`Caused by: ${formatError(error.cause)}`);
+  } else if (error.cause !== void 0) {
+    lines.push(`Caused by: ${String(error.cause)}`);
+  }
   return lines.join("\n");
 }
 function formatContext(context) {
@@ -163,6 +173,19 @@ function formatConsole(metadata, colorize = true) {
   }
   return output;
 }
+function formatErrorCauseChain(error) {
+  const result = {
+    name: error.name,
+    message: error.message,
+    stack: error.stack
+  };
+  if (error.cause instanceof Error) {
+    result.cause = formatErrorCauseChain(error.cause);
+  } else if (error.cause !== void 0) {
+    result.cause = String(error.cause);
+  }
+  return result;
+}
 function formatJSON(metadata) {
   const obj = {
     timestamp: formatTimestamp(metadata.timestamp),
@@ -176,11 +199,7 @@ function formatJSON(metadata) {
     obj.context = metadata.context;
   }
   if (metadata.error) {
-    obj.error = {
-      name: metadata.error.name,
-      message: metadata.error.message,
-      stack: metadata.error.stack
-    };
+    obj.error = formatErrorCauseChain(metadata.error);
   }
   return JSON.stringify(obj);
 }
@@ -314,36 +333,186 @@ var init_formatters = __esm({
     };
   }
 });
-function loadEnvFiles() {
-  const cwd = process.cwd();
-  const nodeEnv = process.env.NODE_ENV || "development";
-  const envFiles = [
-    ".env.server.local",
-    ".env.server",
-    `.env.${nodeEnv}.local`,
-    nodeEnv !== "test" ? ".env.local" : null,
-    `.env.${nodeEnv}`,
-    ".env"
-  ].filter((file) => file !== null);
-  for (const file of envFiles) {
-    const filePath = resolve(cwd, file);
-    if (existsSync(filePath)) {
-      config({ path: filePath });
+var envLogger = logger.child("@spfn/core:env-loader");
+function getEnvFiles(nodeEnv, server) {
+  const files = [
+    ".env",
+    `.env.${nodeEnv}`
+  ];
+  if (nodeEnv !== "test") {
+    files.push(".env.local");
+  }
+  files.push(`.env.${nodeEnv}.local`);
+  if (server) {
+    files.push(".env.server");
+  }
+  return files;
+}
+function parseEnvFile(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return parse(readFileSync(filePath, "utf-8"));
+}
+function loadEnv(options = {}) {
+  const nodeEnvAtEntry = process.env.NODE_ENV;
+  const {
+    cwd = process.cwd(),
+    nodeEnv = nodeEnvAtEntry || "local",
+    server = true,
+    debug = false,
+    override = false
+  } = options;
+  const envFiles = getEnvFiles(nodeEnv, server);
+  const loadedFiles = [];
+  const existingKeys = new Set(Object.keys(process.env));
+  const merged = {};
+  for (const fileName of envFiles) {
+    const filePath = resolve(cwd, fileName);
+    const parsed = parseEnvFile(filePath);
+    if (parsed === null) {
+      continue;
+    }
+    loadedFiles.push(fileName);
+    Object.assign(merged, parsed);
+  }
+  const loadedKeys = [];
+  for (const [key, value] of Object.entries(merged)) {
+    if (!override && existingKeys.has(key)) {
+      continue;
     }
+    process.env[key] = value;
+    loadedKeys.push(key);
+  }
+  if (debug && loadedFiles.length > 0) {
+    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;
+function loadEnvFiles() {
+  if (!warned) {
+    warned = true;
+    console.warn(
+      '[SPFN] loadEnvFiles() is deprecated. Use loadEnv() from "@spfn/core/env/loader" instead.'
+    );
+  }
+  loadEnv();
+}
+
+// src/event/sse/bounded-writer.ts
+function createBoundedWriter(stream, maxQueue, onClose) {
+  const pending = [];
+  let flushing = false;
+  let closed = false;
+  const flush = async () => {
+    if (flushing || closed) {
+      return;
+    }
+    flushing = true;
+    while (pending.length > 0 && !closed) {
+      const frame = pending.shift();
+      try {
+        await stream.writeSSE(frame);
+      } catch (err) {
+        flushing = false;
+        onClose(err instanceof Error ? err.message : String(err));
+        return;
+      }
+    }
+    flushing = false;
+  };
+  return {
+    enqueue(frame) {
+      if (closed) {
+        return;
+      }
+      pending.push(frame);
+      if (pending.length > maxQueue) {
+        onClose("outbound queue overflow (slow consumer)");
+        return;
+      }
+      void flush();
+    },
+    close() {
+      closed = true;
+      pending.length = 0;
+    },
+    get queued() {
+      return pending.length;
+    }
+  };
+}
+
+// src/event/sse/handler.ts
 var sseLogger = logger.child("@spfn/core:sse");
-function createSSEHandler(router, config2 = {}) {
+var frameCache = /* @__PURE__ */ new WeakMap();
+function serializeFrame(eventName, payload) {
+  if (payload === null || typeof payload !== "object") {
+    return JSON.stringify({ event: eventName, data: payload });
+  }
+  let byEvent = frameCache.get(payload);
+  if (!byEvent) {
+    byEvent = /* @__PURE__ */ new Map();
+    frameCache.set(payload, byEvent);
+  }
+  let serialized = byEvent.get(eventName);
+  if (serialized === void 0) {
+    serialized = JSON.stringify({ event: eventName, data: payload });
+    byEvent.set(eventName, serialized);
+  }
+  return serialized;
+}
+var DEFAULT_MAX_QUEUE = 1e3;
+function createSSEHandler(router, config = {}, tokenManager) {
   const {
-    pingInterval = 3e4
-    // headers: customHeaders = {},  // Reserved for future use
-  } = config2;
+    // 10s — keep-alive가 중간 프록시(GCP LB/nginx)의 idle 타임아웃(흔히 ~15-30s)보다 자주 와야
+    // 첫 ping 전 침묵 구간에 연결이 끊기지 않는다. 30s 기본은 idle 타임아웃보다 길어 SSE가
+    // 데이터 없는 동안 끊기던 문제가 있었다.
+    pingInterval = 1e4,
+    auth: authConfig,
+    maxQueue = DEFAULT_MAX_QUEUE
+  } = config;
   return async (c) => {
-    const eventsParam = c.req.query("events");
-    if (!eventsParam) {
+    const subject = await authenticateToken(c, tokenManager);
+    if (subject === false) {
+      return c.json({ error: "Missing token parameter" }, 401);
+    }
+    if (subject === null) {
+      return c.json({ error: "Invalid or expired token" }, 401);
+    }
+    if (subject) {
+      c.set("sseSubject", subject);
+    }
+    const requestedEvents = parseRequestedEvents(c);
+    if (!requestedEvents) {
       return c.json({ error: "Missing events parameter" }, 400);
     }
-    const requestedEvents = eventsParam.split(",").map((e) => e.trim());
     const validEventNames = router.eventNames;
     const invalidEvents = requestedEvents.filter((e) => !validEventNames.includes(e));
     if (invalidEvents.length > 0) {
@@ -353,62 +522,94 @@ function createSSEHandler(router, config2 = {}) {
         validEvents: validEventNames
       }, 400);
     }
+    const allowedEvents = await authorizeEvents(subject, requestedEvents, authConfig);
+    if (allowedEvents === null) {
+      return c.json({ error: "Not authorized for any requested events" }, 403);
+    }
     sseLogger.debug("SSE connection requested", {
-      events: requestedEvents,
+      events: allowedEvents,
+      subject: subject || void 0,
       clientIp: c.req.header("x-forwarded-for") || c.req.header("x-real-ip")
     });
+    c.header("X-Accel-Buffering", "no");
     return streamSSE(c, async (stream) => {
       const unsubscribes = [];
       let messageId = 0;
-      for (const eventName of requestedEvents) {
+      let connectionDead = false;
+      let pingTimer;
+      let writer;
+      let onClosed;
+      const cleanup = (reason) => {
+        if (connectionDead) return;
+        connectionDead = true;
+        clearInterval(pingTimer);
+        unsubscribes.forEach((fn) => fn());
+        writer?.close();
+        onClosed?.();
+        sseLogger.info("SSE dead connection cleaned up", {
+          events: allowedEvents,
+          reason
+        });
+      };
+      writer = createBoundedWriter(stream, maxQueue, (reason) => {
+        sseLogger.warn("SSE connection closed", { events: allowedEvents, reason });
+        cleanup(reason);
+      });
+      writer.enqueue({
+        event: "connected",
+        data: JSON.stringify({
+          subscribedEvents: allowedEvents,
+          timestamp: Date.now()
+        })
+      });
+      for (const eventName of allowedEvents) {
         const eventDef = router.events[eventName];
         if (!eventDef) {
           continue;
         }
         const unsubscribe = eventDef.subscribe((payload) => {
+          if (connectionDead) return;
+          if (subject && authConfig?.filter?.[eventName]) {
+            if (!authConfig.filter[eventName](subject, payload)) {
+              return;
+            }
+          }
           messageId++;
-          const message = {
-            event: eventName,
-            data: payload
-          };
           sseLogger.debug("SSE sending event", {
             event: eventName,
             messageId
           });
-          void stream.writeSSE({
+          writer.enqueue({
             id: String(messageId),
             event: eventName,
-            data: JSON.stringify(message)
+            data: serializeFrame(eventName, payload)
           });
         });
         unsubscribes.push(unsubscribe);
       }
       sseLogger.info("SSE connection established", {
-        events: requestedEvents,
+        events: allowedEvents,
         subscriptionCount: unsubscribes.length
       });
-      await stream.writeSSE({
-        event: "connected",
-        data: JSON.stringify({
-          subscribedEvents: requestedEvents,
-          timestamp: Date.now()
-        })
-      });
-      const pingTimer = setInterval(() => {
-        void stream.writeSSE({
+      pingTimer = setInterval(() => {
+        if (connectionDead) return;
+        writer.enqueue({
           event: "ping",
           data: JSON.stringify({ timestamp: Date.now() })
         });
       }, pingInterval);
       const abortSignal = c.req.raw.signal;
-      while (!abortSignal.aborted) {
-        await stream.sleep(pingInterval);
+      if (!abortSignal.aborted && !connectionDead) {
+        await new Promise((resolve2) => {
+          const onAbort = () => resolve2();
+          abortSignal.addEventListener("abort", onAbort, { once: true });
+          onClosed = () => {
+            abortSignal.removeEventListener("abort", onAbort);
+            resolve2();
+          };
+        });
       }
-      clearInterval(pingTimer);
-      unsubscribes.forEach((fn) => fn());
-      sseLogger.info("SSE connection closed", {
-        events: requestedEvents
-      });
+      cleanup();
     }, async (err) => {
       sseLogger.error("SSE stream error", {
         error: err.message
@@ -416,30 +617,765 @@ function createSSEHandler(router, config2 = {}) {
     });
   };
 }
-function createHealthCheckHandler(detailed) {
+async function authenticateToken(c, tokenManager) {
+  if (!tokenManager) {
+    return void 0;
+  }
+  const token = c.req.query("token");
+  if (!token) {
+    return false;
+  }
+  return await tokenManager.verify(token);
+}
+function parseRequestedEvents(c) {
+  const eventsParam = c.req.query("events");
+  if (!eventsParam) {
+    return null;
+  }
+  return eventsParam.split(",").map((e) => e.trim());
+}
+async function authorizeEvents(subject, requestedEvents, authConfig) {
+  if (!subject || !authConfig?.authorize) {
+    return requestedEvents;
+  }
+  const allowed = await authConfig.authorize(subject, requestedEvents);
+  if (allowed.length === 0) {
+    return null;
+  }
+  return allowed;
+}
+function hashToken(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+var InMemoryTokenStore = class {
+  tokens = /* @__PURE__ */ new Map();
+  async set(token, data) {
+    this.tokens.set(hashToken(token), data);
+  }
+  async consume(token) {
+    const key = hashToken(token);
+    const data = this.tokens.get(key);
+    if (!data) {
+      return null;
+    }
+    this.tokens.delete(key);
+    return data;
+  }
+  async cleanup() {
+    const now = Date.now();
+    for (const [key, data] of this.tokens) {
+      if (data.expiresAt <= now) {
+        this.tokens.delete(key);
+      }
+    }
+  }
+};
+var CacheTokenStore = class {
+  constructor(cache2) {
+    this.cache = cache2;
+  }
+  prefix = "sse:token:";
+  async set(token, data) {
+    const ttlSeconds = Math.max(1, Math.ceil((data.expiresAt - Date.now()) / 1e3));
+    await this.cache.set(
+      this.prefix + hashToken(token),
+      JSON.stringify(data),
+      "EX",
+      ttlSeconds
+    );
+  }
+  async consume(token) {
+    const key = this.prefix + hashToken(token);
+    let raw = null;
+    if (this.cache.getdel) {
+      raw = await this.cache.getdel(key);
+    } else {
+      raw = await this.cache.get(key);
+      if (raw) {
+        await this.cache.del(key);
+      }
+    }
+    if (!raw) {
+      return null;
+    }
+    return JSON.parse(raw);
+  }
+  async cleanup() {
+  }
+};
+var SSETokenManager = class {
+  store;
+  ttl;
+  cleanupTimer = null;
+  constructor(config) {
+    this.ttl = config?.ttl ?? 3e4;
+    this.store = config?.store ?? new InMemoryTokenStore();
+    const cleanupInterval = config?.cleanupInterval ?? 6e4;
+    this.cleanupTimer = setInterval(() => void this.store.cleanup(), cleanupInterval);
+    this.cleanupTimer.unref();
+  }
+  /**
+   * How long an issued token stays valid, in milliseconds.
+   *
+   * Exposed so a caller that has to report an expiry to its client computes the same
+   * number this manager stamps on the token, instead of assuming the default.
+   */
+  get ttlMs() {
+    return this.ttl;
+  }
+  /**
+   * Issue a new one-time-use token for the given subject
+   */
+  async issue(subject) {
+    const token = randomBytes(32).toString("hex");
+    await this.store.set(token, {
+      subject,
+      expiresAt: Date.now() + this.ttl
+    });
+    return token;
+  }
+  /**
+   * Verify and consume a token
+   * @returns subject string if valid, null if invalid/expired/already consumed
+   */
+  async verify(token) {
+    const data = await this.store.consume(token);
+    if (!data || data.expiresAt <= Date.now()) {
+      return null;
+    }
+    return data.subject;
+  }
+  /**
+   * Cleanup timer and resources
+   */
+  destroy() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+};
+var transportLogger = logger.child("@spfn/core:event-transport");
+var DEFAULT_CHANNEL_PREFIX = "spfn:sse:";
+var SUBSCRIBER_QUIT_TIMEOUT_MS = 5e3;
+var PUBLISH_TIMEOUT_MS = 5e3;
+var SUBSCRIBE_TIMEOUT_MS = 5e3;
+var WARN_THROTTLE_MS = 3e4;
+var PUBLISH_BREAKER_COOLDOWN_MS = 1e4;
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve2(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
+var warnThrottle = /* @__PURE__ */ new Map();
+function throttledWarn(key, message, fields) {
+  const now = Date.now();
+  const entry = warnThrottle.get(key);
+  if (entry && now - entry.last < WARN_THROTTLE_MS) {
+    entry.suppressed++;
+    return;
+  }
+  transportLogger.warn(message, entry && entry.suppressed > 0 ? { ...fields, suppressedSinceLast: entry.suppressed } : fields);
+  warnThrottle.set(key, { last: now, suppressed: 0 });
+}
+var STATE_KEY = Symbol.for("@spfn/core:event-transport");
+var state = globalThis[STATE_KEY] ??= {
+  pubSubCache: void 0,
+  subscriber: void 0,
+  channelPrefix: void 0,
+  wired: /* @__PURE__ */ new Map()
+};
+function resolveChannelPrefix(override) {
+  return override ?? process.env.SPFN_SSE_CHANNEL_PREFIX ?? DEFAULT_CHANNEL_PREFIX;
+}
+function createRedisPubSubCache(client, channelPrefix, onSubscriber) {
+  let subscriber;
+  const handlers = /* @__PURE__ */ new Map();
+  let degradedUntil = 0;
+  const ensureSubscriber = () => {
+    if (subscriber) {
+      return subscriber;
+    }
+    subscriber = client.duplicate();
+    onSubscriber?.(subscriber);
+    subscriber.on("message", (channel, raw) => {
+      const handler = handlers.get(channel);
+      if (!handler) {
+        return;
+      }
+      let payload;
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        transportLogger.warn("Pub/sub message parse failed \u2014 dropped", { channel });
+        return;
+      }
+      void handler(payload);
+    });
+    subscriber.on("error", (err) => {
+      throttledWarn("subscriber-error", "Pub/sub subscriber error", { error: err.message });
+    });
+    return subscriber;
+  };
+  const subscriberHealthy = () => !!subscriber && (subscriber.status === void 0 || subscriber.status === "ready");
+  const deliverLocal = (channel, message) => {
+    const handler = handlers.get(channel);
+    if (handler) {
+      void handler(message);
+    }
+  };
+  return {
+    publish: async (name, message) => {
+      const channel = channelPrefix + name;
+      let serialized;
+      try {
+        serialized = JSON.stringify(message ?? null);
+      } catch (err) {
+        transportLogger.warn("Pub/sub payload serialization failed \u2014 local delivery only", {
+          channel,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        deliverLocal(channel, message ?? null);
+        return;
+      }
+      if (serialized === void 0) {
+        transportLogger.warn("Pub/sub payload not serializable (function/symbol) \u2014 local delivery only", {
+          channel
+        });
+        deliverLocal(channel, message ?? null);
+        return;
+      }
+      const ready = client.status === void 0 || client.status === "ready";
+      const now = Date.now();
+      if (!ready || degradedUntil > 0 && now < degradedUntil) {
+        deliverLocal(channel, JSON.parse(serialized));
+        return;
+      }
+      if (degradedUntil > 0) {
+        degradedUntil = now + PUBLISH_TIMEOUT_MS;
+      }
+      try {
+        await withTimeout(client.publish(channel, serialized), PUBLISH_TIMEOUT_MS, "pub/sub publish");
+        degradedUntil = 0;
+        if (!subscriberHealthy()) {
+          throttledWarn("subscriber-down", "Subscriber connection down \u2014 same-pod local fallback", {
+            channel
+          });
+          deliverLocal(channel, JSON.parse(serialized));
+        }
+      } catch (err) {
+        degradedUntil = Date.now() + PUBLISH_BREAKER_COOLDOWN_MS;
+        throttledWarn("publish-failed", "Pub/sub publish failed \u2014 local delivery only", {
+          channel,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        deliverLocal(channel, JSON.parse(serialized));
+      }
+    },
+    subscribe: async (name, handler) => {
+      const channel = channelPrefix + name;
+      const sub = ensureSubscriber();
+      try {
+        await withTimeout(sub.subscribe(channel), SUBSCRIBE_TIMEOUT_MS, "pub/sub subscribe");
+      } catch (err) {
+        if (handlers.size === 0 && subscriber === sub) {
+          subscriber = void 0;
+          void sub.quit?.().catch(() => void 0);
+        }
+        throw err;
+      }
+      handlers.set(channel, handler);
+    }
+  };
+}
+async function wireEventRouterCache(router, options = {}) {
+  if (options.multiInstance === false) {
+    const events2 = router.events;
+    const stillRedis = Object.keys(events2).filter((k) => state.wired.has(events2[k].name)).length;
+    if (stillRedis > 0) {
+      transportLogger.warn("multiInstance:false has no effect on events already wired to redis by another router", {
+        redisWired: stillRedis
+      });
+    } else {
+      transportLogger.info("Event transport: in-process (multiInstance disabled)");
+    }
+    return "in-process";
+  }
+  const pubSubCache = await resolvePubSubCache(options.channelPrefix);
+  if (!pubSubCache) {
+    transportLogger.info("Event transport: in-process (no cache configured)");
+    return "in-process";
+  }
+  const events = router.events;
+  let wired = 0;
+  let degraded = 0;
+  let alreadyWired = 0;
+  for (const key of Object.keys(events)) {
+    const event = events[key];
+    if (state.wired.has(event.name)) {
+      alreadyWired++;
+      continue;
+    }
+    try {
+      await event.useCache(pubSubCache);
+      state.wired.set(event.name, event);
+      wired++;
+    } catch (err) {
+      degraded++;
+      transportLogger.warn("Event cache wiring failed \u2014 staying in-process for this event", {
+        event: event.name,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  if (wired + alreadyWired === 0) {
+    transportLogger.warn("Event transport: redis configured but no event wired \u2014 running in-process", {
+      total: Object.keys(events).length,
+      degraded
+    });
+    return "in-process";
+  }
+  transportLogger.info("Event transport: redis (cross-pod fan-out)", {
+    total: Object.keys(events).length,
+    wired,
+    degraded,
+    alreadyWired
+  });
+  return "redis";
+}
+async function resolvePubSubCache(channelPrefix) {
+  const resolvedPrefix = resolveChannelPrefix(channelPrefix);
+  if (state.pubSubCache) {
+    if (state.channelPrefix !== resolvedPrefix) {
+      transportLogger.warn("Conflicting channelPrefix ignored \u2014 the transport prefix is process-global (first wiring wins).", {
+        active: state.channelPrefix,
+        ignored: resolvedPrefix
+      });
+    }
+    return state.pubSubCache;
+  }
+  let client;
+  try {
+    const { getCache: getCache2 } = await import('@spfn/core/cache');
+    client = getCache2();
+  } catch {
+    return void 0;
+  }
+  if (!client) {
+    return void 0;
+  }
+  if (!channelPrefix && !process.env.SPFN_SSE_CHANNEL_PREFIX) {
+    transportLogger.warn(
+      "Event fan-out is on the default channel prefix (spfn:sse:). Apps sharing one Redis must set channelPrefix or SPFN_SSE_CHANNEL_PREFIX to avoid cross-app leakage."
+    );
+  }
+  state.channelPrefix = resolvedPrefix;
+  state.pubSubCache = createRedisPubSubCache(
+    client,
+    resolvedPrefix,
+    (connection) => {
+      state.subscriber = connection;
+    }
+  );
+  return state.pubSubCache;
+}
+async function closeEventTransport() {
+  const subscriber = state.subscriber;
+  for (const event of state.wired.values()) {
+    event._resetCache?.();
+  }
+  state.subscriber = void 0;
+  state.pubSubCache = void 0;
+  state.channelPrefix = void 0;
+  state.wired.clear();
+  if (!subscriber?.quit) {
+    return;
+  }
+  await Promise.race([
+    subscriber.quit().catch(() => void 0),
+    new Promise((resolve2) => {
+      const timer = setTimeout(resolve2, SUBSCRIBER_QUIT_TIMEOUT_MS);
+      timer.unref?.();
+    })
+  ]);
+}
+var serverLogger = logger.child("@spfn/core:server");
+
+// src/server/migration-gate.ts
+var SNAPSHOT_TTL_MS = 3e4;
+var cache = null;
+var PendingMigrationsError = class extends Error {
+  targets;
+  constructor(message, targets) {
+    super(message);
+    this.name = "PendingMigrationsError";
+    this.targets = targets;
+  }
+};
+function resetMigrationSnapshot() {
+  cache = null;
+}
+async function inspect(cwd, db) {
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (!hasMigrationTargets(cwd)) {
+    return { state: "skipped", checkedAt, reason: "no function package or project migrations found" };
+  }
+  let database = db;
+  if (!database) {
+    try {
+      database = getDatabase();
+    } catch {
+      return { state: "skipped", checkedAt, reason: "no database initialized" };
+    }
+  }
+  try {
+    const status = await collectMigrationStatus(database, cwd);
+    return { state: "ok", checkedAt, status, pending: countPendingMigrations(status) };
+  } catch (error) {
+    return {
+      state: "unavailable",
+      checkedAt,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function getMigrationSnapshot(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const ttl = options.ttlMs ?? SNAPSHOT_TTL_MS;
+  const now = Date.now();
+  if (!options.force && cache && cache.cwd === cwd && now - cache.at < ttl) {
+    return cache.value;
+  }
+  const value = await inspect(cwd, options.db);
+  cache = { at: now, cwd, value };
+  return value;
+}
+function pendingIsAllowed(config) {
+  return config?.migrations?.allowPending ?? env.SPFN_ALLOW_PENDING_MIGRATIONS === true;
+}
+async function runMigrationBootGate(config, cwd = process.cwd()) {
+  const snapshot = await getMigrationSnapshot({ cwd, force: true });
+  if (snapshot.state === "skipped") {
+    serverLogger.debug(`Migration gate skipped: ${snapshot.reason}`);
+    return snapshot;
+  }
+  if (snapshot.state === "unavailable") {
+    serverLogger.warn(
+      `Could not verify migration status: ${snapshot.reason}. Starting anyway \u2014 run \`pnpm spfn db status\` to check.`
+    );
+    return snapshot;
+  }
+  const targets = pendingMigrationTargets(snapshot.status);
+  if (targets.length === 0) {
+    serverLogger.debug("Migration gate passed: database is up to date");
+    return snapshot;
+  }
+  const lines = formatPendingMigrations(targets);
+  const summary = pendingMigrationsSummary(targets);
+  if (pendingIsAllowed(config)) {
+    serverLogger.warn(`Starting with pending migrations \u2014 ${summary}`);
+    lines.forEach((line) => serverLogger.warn(`  ${line}`));
+    serverLogger.warn(`  Requests hitting the missing columns will fail. ${RUN_MIGRATIONS_HINT}`);
+    return snapshot;
+  }
+  serverLogger.error(`Refusing to start: ${summary}`);
+  lines.forEach((line) => serverLogger.error(`  ${line}`));
+  serverLogger.error(`  ${RUN_MIGRATIONS_HINT}`);
+  serverLogger.error("  To start anyway: SPFN_ALLOW_PENDING_MIGRATIONS=true (or `spfn dev --allow-pending-migrations`)");
+  throw new PendingMigrationsError(
+    `${summary}. ${RUN_MIGRATIONS_HINT}, or set SPFN_ALLOW_PENDING_MIGRATIONS=true to start anyway.`,
+    targets.map((target) => target.name)
+  );
+}
+
+// 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;
+var DRAIN_POLL_INTERVAL = 500;
+var ShutdownManager = class {
+  state = "running";
+  hooks = [];
+  operations = /* @__PURE__ */ new Map();
+  operationCounter = 0;
+  /**
+   * Register a shutdown hook
+   *
+   * Hooks run in order during shutdown, after all tracked operations drain.
+   * Each hook has its own timeout — failure does not block subsequent hooks.
+   *
+   * @example
+   * shutdown.onShutdown('ai-service', async () => {
+   *     await aiService.cancelPending();
+   * }, { timeout: 30000, order: 10 });
+   */
+  onShutdown(name, handler, options) {
+    this.hooks.push({
+      name,
+      handler,
+      timeout: options?.timeout ?? DEFAULT_HOOK_TIMEOUT,
+      order: options?.order ?? DEFAULT_HOOK_ORDER
+    });
+    this.hooks.sort((a, b) => a.order - b.order);
+    serverLogger.debug(`Shutdown hook registered: ${name}`, {
+      order: options?.order ?? DEFAULT_HOOK_ORDER,
+      timeout: `${options?.timeout ?? DEFAULT_HOOK_TIMEOUT}ms`
+    });
+  }
+  /**
+   * Track a long-running operation
+   *
+   * During shutdown (drain phase), the process waits for ALL tracked
+   * operations to complete before proceeding with cleanup.
+   *
+   * If shutdown has already started, the operation is rejected immediately.
+   *
+   * @returns The operation result (pass-through)
+   *
+   * @example
+   * const result = await shutdown.trackOperation(
+   *     'ai-generate',
+   *     aiService.generate(prompt)
+   * );
+   */
+  async trackOperation(name, operation) {
+    if (this.state !== "running") {
+      throw new Error(`Cannot start operation '${name}': server is shutting down`);
+    }
+    const id = `${name}-${++this.operationCounter}`;
+    this.operations.set(id, {
+      name,
+      startedAt: Date.now()
+    });
+    serverLogger.debug(`Operation tracked: ${id}`, {
+      activeOperations: this.operations.size
+    });
+    try {
+      return await operation;
+    } finally {
+      this.operations.delete(id);
+      serverLogger.debug(`Operation completed: ${id}`, {
+        activeOperations: this.operations.size
+      });
+    }
+  }
+  /**
+   * Whether the server is shutting down
+   *
+   * Use this to reject new work early (e.g., return 503 in route handlers).
+   */
+  isShuttingDown() {
+    return this.state !== "running";
+  }
+  /**
+   * Number of currently active tracked operations
+   */
+  getActiveOperationCount() {
+    return this.operations.size;
+  }
+  /**
+   * Mark shutdown as started immediately
+   *
+   * Call this at the very beginning of the shutdown sequence so that:
+   * - Health check returns 503 right away
+   * - trackOperation() rejects new work
+   * - isShuttingDown() returns true
+   */
+  beginShutdown() {
+    if (this.state !== "running") {
+      return;
+    }
+    this.state = "draining";
+    serverLogger.info("Shutdown manager: state set to draining");
+  }
+  /**
+   * Execute the full shutdown sequence
+   *
+   * 1. State → draining (reject new operations)
+   * 2. Wait for all tracked operations to complete (drain)
+   * 3. Run shutdown hooks in order
+   * 4. State → closed
+   *
+   * @param drainTimeout - Max time to wait for operations to drain (ms)
+   */
+  async execute(drainTimeout) {
+    if (this.state === "closed") {
+      serverLogger.warn("ShutdownManager.execute() called but already closed");
+      return;
+    }
+    this.state = "draining";
+    serverLogger.info("Shutdown manager: draining started", {
+      activeOperations: this.operations.size,
+      registeredHooks: this.hooks.length,
+      drainTimeout: `${drainTimeout}ms`
+    });
+    await this.drain(drainTimeout);
+    await this.executeHooks();
+    this.state = "closed";
+    serverLogger.info("Shutdown manager: all hooks executed");
+  }
+  // ========================================================================
+  // Private
+  // ========================================================================
+  /**
+   * Wait for all tracked operations to complete, up to drainTimeout
+   */
+  async drain(drainTimeout) {
+    if (this.operations.size === 0) {
+      serverLogger.info("Shutdown manager: no active operations, drain skipped");
+      return;
+    }
+    serverLogger.info(`Shutdown manager: waiting for ${this.operations.size} operations to drain...`);
+    const deadline = Date.now() + drainTimeout;
+    while (this.operations.size > 0 && Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      const ops = Array.from(this.operations.values()).map((op) => ({
+        name: op.name,
+        elapsed: `${Math.round((Date.now() - op.startedAt) / 1e3)}s`
+      }));
+      serverLogger.info("Shutdown manager: drain in progress", {
+        activeOperations: this.operations.size,
+        remainingTimeout: `${Math.round(remaining / 1e3)}s`,
+        operations: ops
+      });
+      await sleep(Math.min(DRAIN_POLL_INTERVAL, remaining));
+    }
+    if (this.operations.size > 0) {
+      const abandoned = Array.from(this.operations.values()).map((op) => op.name);
+      serverLogger.warn("Shutdown manager: drain timeout \u2014 abandoning operations", {
+        abandoned
+      });
+    } else {
+      serverLogger.info("Shutdown manager: all operations drained successfully");
+    }
+  }
+  /**
+   * Execute registered shutdown hooks in order
+   */
+  async executeHooks() {
+    if (this.hooks.length === 0) {
+      return;
+    }
+    serverLogger.info(`Shutdown manager: executing ${this.hooks.length} hooks...`);
+    for (const hook of this.hooks) {
+      serverLogger.debug(`Shutdown hook [${hook.name}] starting (timeout: ${hook.timeout}ms)`);
+      try {
+        await withTimeout2(
+          hook.handler(),
+          hook.timeout,
+          `Shutdown hook '${hook.name}' timeout after ${hook.timeout}ms`
+        );
+        serverLogger.info(`Shutdown hook [${hook.name}] completed`);
+      } catch (error) {
+        serverLogger.error(
+          `Shutdown hook [${hook.name}] failed`,
+          error
+        );
+      }
+    }
+  }
+};
+var instance = null;
+function getShutdownManager() {
+  if (!instance) {
+    instance = new ShutdownManager();
+  }
+  return instance;
+}
+function resetShutdownManager() {
+  instance = null;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function withTimeout2(promise, timeout, message) {
+  let timeoutId;
+  return Promise.race([
+    promise.finally(() => {
+      if (timeoutId) clearTimeout(timeoutId);
+    }),
+    new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(message));
+      }, timeout);
+    })
+  ]);
+}
+
+// src/server/helpers.ts
+async function readMigrationHealth() {
+  const snapshot = await getMigrationSnapshot();
+  if (snapshot.state !== "ok") {
+    return {
+      status: "unknown",
+      pending: 0,
+      checkedAt: snapshot.checkedAt,
+      targets: [],
+      reason: snapshot.reason
+    };
+  }
+  return {
+    status: snapshot.pending > 0 ? "pending" : "up_to_date",
+    pending: snapshot.pending,
+    checkedAt: snapshot.checkedAt,
+    targets: migrationTargets(snapshot.status)
+  };
+}
+function createHealthCheckHandler(detailed, infrastructure) {
   return async (c) => {
+    const shutdownManager = getShutdownManager();
+    if (shutdownManager.isShuttingDown()) {
+      return c.json({
+        status: "shutting_down",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }, 503);
+    }
     const response = {
       status: "ok",
       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 {
@@ -462,11 +1398,32 @@ function createHealthCheckHandler(detailed) {
       };
       const hasErrors = dbStatus === "error" || dbStatus === "not_initialized" || redisStatus === "error";
       response.status = hasErrors ? "degraded" : "ok";
+      response.migrations = await readMigrationHealth();
     }
     const statusCode = response.status === "ok" ? 200 : 503;
     return c.json(response, statusCode);
   };
 }
+function resolveEndpointMiddlewares(config) {
+  const candidates = [
+    ...config.middlewares ?? [],
+    ...config.routes?._globalMiddlewares ?? []
+  ];
+  for (const pkgRouter of config.routes?._packageRouters ?? []) {
+    candidates.push(...pkgRouter._globalMiddlewares ?? []);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return candidates.filter((mw) => {
+    if (!mw.name) {
+      return true;
+    }
+    if (seen.has(mw.name)) {
+      return false;
+    }
+    seen.add(mw.name);
+    return true;
+  });
+}
 function applyServerTimeouts(server, timeouts) {
   if ("timeout" in server) {
     server.timeout = timeouts.request;
@@ -474,52 +1431,68 @@ function applyServerTimeouts(server, timeouts) {
     server.headersTimeout = timeouts.headers;
   }
 }
-function getTimeoutConfig(config2) {
+function getTimeoutConfig(config) {
   return {
-    request: config2?.request ?? env.SERVER_TIMEOUT,
-    keepAlive: config2?.keepAlive ?? env.SERVER_KEEPALIVE_TIMEOUT,
-    headers: config2?.headers ?? env.SERVER_HEADERS_TIMEOUT
+    request: config?.request ?? env.SERVER_TIMEOUT,
+    keepAlive: config?.keepAlive ?? env.SERVER_KEEPALIVE_TIMEOUT,
+    headers: config?.headers ?? env.SERVER_HEADERS_TIMEOUT
   };
 }
-function getShutdownTimeout(config2) {
-  return config2?.timeout ?? env.SHUTDOWN_TIMEOUT;
+function getShutdownTimeout(config) {
+  return config?.timeout ?? env.SHUTDOWN_TIMEOUT;
 }
-function buildMiddlewareOrder(config2) {
+function getFetchTimeoutConfig(config) {
+  return {
+    connect: config?.connect ?? env.FETCH_CONNECT_TIMEOUT,
+    headers: config?.headers ?? env.FETCH_HEADERS_TIMEOUT,
+    body: config?.body ?? env.FETCH_BODY_TIMEOUT
+  };
+}
+function applyGlobalFetchTimeouts(timeouts) {
+  const agent = new Agent({
+    connect: { timeout: timeouts.connect },
+    headersTimeout: timeouts.headers,
+    bodyTimeout: timeouts.body
+  });
+  setGlobalDispatcher(agent);
+}
+function buildMiddlewareOrder(config) {
   const order = [];
-  const middlewareConfig = config2.middleware ?? {};
+  const middlewareConfig = config.middleware ?? {};
   const enableLogger = middlewareConfig.logger !== false;
   const enableCors = middlewareConfig.cors !== false;
   const enableErrorHandler = middlewareConfig.errorHandler !== false;
   if (enableLogger) order.push("RequestLogger");
   if (enableCors) order.push("CORS");
-  config2.use?.forEach((_, i) => order.push(`Custom[${i}]`));
-  if (config2.beforeRoutes) order.push("beforeRoutes hook");
+  config.use?.forEach((_, i) => order.push(`Custom[${i}]`));
+  if (config.beforeRoutes) order.push("beforeRoutes hook");
   order.push("Routes");
-  if (config2.afterRoutes) order.push("afterRoutes hook");
+  if (config.afterRoutes) order.push("afterRoutes hook");
   if (enableErrorHandler) order.push("ErrorHandler");
   return order;
 }
-function buildStartupConfig(config2, timeouts) {
-  const middlewareConfig = config2.middleware ?? {};
-  const healthCheckConfig = config2.healthCheck ?? {};
+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: {
       logger: middlewareConfig.logger !== false,
       cors: middlewareConfig.cors !== false,
       errorHandler: middlewareConfig.errorHandler !== false,
-      custom: config2.use?.length ?? 0
+      custom: config.use?.length ?? 0
     },
     healthCheck: healthCheckEnabled ? {
       enabled: true,
+      corePath: CORE_HEALTH_PATH,
       path: healthCheckPath,
       detailed: healthCheckDetailed
     } : { enabled: false },
     hooks: {
-      beforeRoutes: !!config2.beforeRoutes,
-      afterRoutes: !!config2.afterRoutes
+      beforeRoutes: !!config.beforeRoutes,
+      afterRoutes: !!config.afterRoutes
     },
     timeout: {
       request: `${timeouts.request}ms`,
@@ -527,23 +1500,396 @@ function buildStartupConfig(config2, timeouts) {
       headers: `${timeouts.headers}ms`
     },
     shutdown: {
-      timeout: `${config2.shutdown?.timeout ?? env.SHUTDOWN_TIMEOUT}ms`
+      timeout: `${config.shutdown?.timeout ?? env.SHUTDOWN_TIMEOUT}ms`
     }
   };
 }
-var serverLogger = logger.child("@spfn/core:server");
+
+// 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
-async function createServer(config2) {
+var rateLimitApplied = /* @__PURE__ */ new WeakSet();
+async function createServer(config) {
+  applyOutboundFetch(config);
   const cwd = process.cwd();
   const appPath = join(cwd, "src", "server", "app.ts");
   const appJsPath = join(cwd, "src", "server", "app");
   if (existsSync(appPath) || existsSync(appJsPath)) {
-    return await loadCustomApp(appPath, appJsPath, config2);
+    return await loadCustomApp(appPath, appJsPath, config);
   }
-  return await createAutoConfiguredApp(config2);
+  return await createAutoConfiguredApp(config);
 }
-async function loadCustomApp(appPath, appJsPath, config2) {
+async function loadCustomApp(appPath, appJsPath, config) {
   const actualPath = existsSync(appPath) ? appPath : appJsPath;
   const appModule = await import(actualPath);
   const appFactory = appModule.default;
@@ -551,15 +1897,16 @@ async function loadCustomApp(appPath, appJsPath, config2) {
     throw new Error("app.ts must export a default function that returns a Hono app");
   }
   const app = await appFactory();
-  if (config2?.routes) {
-    const routes = registerRoutes(app, config2.routes, config2.middlewares);
-    logRegisteredRoutes(routes, config2?.debug ?? false);
+  applyRateLimit(config);
+  if (config?.routes) {
+    const routes = registerRoutes(app, config.routes, config.middlewares);
+    logRegisteredRoutes(routes, config?.debug ?? false);
   }
   return app;
 }
-async function createAutoConfiguredApp(config2) {
+async function createAutoConfiguredApp(config) {
   const app = new Hono();
-  const middlewareConfig = config2?.middleware ?? {};
+  const middlewareConfig = config?.middleware ?? {};
   const enableLogger = middlewareConfig.logger !== false;
   const enableCors = middlewareConfig.cors !== false;
   const enableErrorHandler = middlewareConfig.errorHandler !== false;
@@ -569,52 +1916,195 @@ async function createAutoConfiguredApp(config2) {
       await next();
     });
   }
-  applyDefaultMiddleware(app, config2, enableLogger, enableCors);
-  if (Array.isArray(config2?.use)) {
-    config2.use.forEach((mw) => app.use("*", mw));
-  }
-  registerHealthCheckEndpoint(app, config2);
-  await executeBeforeRoutesHook(app, config2);
-  await loadAppRoutes(app, config2);
-  registerSSEEndpoint(app, config2);
-  await executeAfterRoutesHook(app, config2);
+  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));
+  }
+  registerCoreHealthEndpoint(app, config);
+  await executeBeforeRoutesHook(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) {
-    app.onError(ErrorHandler());
+    app.onError(ErrorHandler({ onError: config?.middleware?.onError }));
   }
   return app;
 }
-function applyDefaultMiddleware(app, config2, enableLogger, enableCors) {
+function applyDefaultMiddleware(app, config, enableLogger, enableCors) {
   if (enableLogger) {
     app.use("*", RequestLogger());
   }
   if (enableCors) {
-    const corsOptions = config2?.cors !== false ? config2?.cors : void 0;
+    const corsOptions = config?.cors !== false ? config?.cors : void 0;
     app.use("*", cors(corsOptions));
   }
 }
-function registerHealthCheckEndpoint(app, config2) {
-  const healthCheckConfig = config2?.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}`);
+async function applyProxyGuard(app, config) {
+  const proxyGuardConfig = config?.proxyGuard;
+  const mode = proxyGuardConfig?.mode ?? "off";
+  if (mode === "off") {
+    return;
+  }
+  const { createProxyGuard, createCacheNonceStore, createInMemoryNonceStore } = await import('@spfn/core/middleware');
+  let nonceStore;
+  if (proxyGuardConfig?.nonce) {
+    try {
+      const { getCache: getCache2 } = await import('@spfn/core/cache');
+      const cache2 = getCache2();
+      if (cache2) {
+        nonceStore = createCacheNonceStore(cache2);
+        serverLogger.info("Proxy-guard nonce replay rejection: cache (Redis/Valkey)");
+      } else {
+        nonceStore = createInMemoryNonceStore();
+        serverLogger.info("Proxy-guard nonce replay rejection: in-memory (single instance only \u2014 use a cache for multi-instance)");
+      }
+    } catch {
+      nonceStore = createInMemoryNonceStore();
+      serverLogger.warn("Proxy-guard nonce: cache module unavailable \u2014 using in-memory store (single instance only)");
+    }
+  }
+  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");
+  }
+  if (config?.websockets) {
+    autoSkip.push(config.websocketsConfig?.path ?? "/ws");
+  }
+  const skipPaths = [...proxyGuardConfig?.skipPaths ?? [], ...autoSkip];
+  app.use("*", createProxyGuard({
+    mode,
+    secret: proxyGuardConfig?.secret,
+    previousSecrets: proxyGuardConfig?.previousSecrets,
+    windowMs: proxyGuardConfig?.windowMs,
+    allowedOrigins: proxyGuardConfig?.allowedOrigins,
+    maxBodyBytes: proxyGuardConfig?.maxBodyBytes,
+    nonceStore,
+    nonceFailClosed: proxyGuardConfig?.nonceFailClosed,
+    skipPaths
+  }));
+  serverLogger.info(`\u2713 Proxy-guard enabled (mode: ${mode})`);
+}
+function applyRateLimit(config) {
+  const rl = config?.rateLimit;
+  setRateLimitPolicies(rl?.policies);
+  setRateLimitFailClosedDefault(env.RATE_LIMIT_FAIL_CLOSED);
+  const enabled = (rl?.mode ?? env.RATE_LIMIT_MODE) === "on";
+  if (!enabled || !config || rateLimitApplied.has(config)) {
+    return;
+  }
+  rateLimitApplied.add(config);
+  const defaultPolicy = {
+    limit: rl?.default?.limit ?? env.RATE_LIMIT_DEFAULT_LIMIT,
+    windowMs: rl?.default?.windowMs ?? env.RATE_LIMIT_DEFAULT_WINDOW_MS,
+    failClosed: rl?.default?.failClosed ?? env.RATE_LIMIT_FAIL_CLOSED
+  };
+  const globalRateLimit = defineMiddleware("rateLimit", rateLimit(defaultPolicy));
+  config.middlewares = [globalRateLimit, ...config.middlewares ?? []];
+  serverLogger.info(`\u2713 Rate limit default enabled (${defaultPolicy.limit} per ${defaultPolicy.windowMs}ms)`);
+}
+function applyOutboundFetch(config) {
+  const policy = config?.outboundFetch ?? { blockPrivateIps: env.SAFE_FETCH_BLOCK_PRIVATE_IPS };
+  setDefaultSafeFetchPolicy(policy);
+}
+function resolveHealthCheck(config) {
+  const healthCheckConfig = config?.healthCheck ?? {};
+  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, config2) {
-  if (config2?.lifecycle?.beforeRoutes) {
-    await config2.lifecycle.beforeRoutes(app);
+async function executeBeforeRoutesHook(app, config) {
+  if (config?.lifecycle?.beforeRoutes) {
+    await config.lifecycle.beforeRoutes(app);
   }
 }
-async function loadAppRoutes(app, config2) {
-  const debug = isDebugMode(config2);
-  if (config2?.routes) {
-    const routes = registerRoutes(app, config2.routes, config2.middlewares);
+async function loadAppRoutes(app, config) {
+  const debug = isDebugMode(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) {
@@ -631,78 +2121,174 @@ function logRegisteredRoutes(routes, debug) {
   serverLogger.info(`\u2713 Routes registered (${routes.length}):
 ${routeLines}`);
 }
-async function executeAfterRoutesHook(app, config2) {
-  if (config2?.lifecycle?.afterRoutes) {
-    await config2.lifecycle.afterRoutes(app);
+async function executeAfterRoutesHook(app, config) {
+  if (config?.lifecycle?.afterRoutes) {
+    await config.lifecycle.afterRoutes(app);
   }
 }
-function registerSSEEndpoint(app, config2) {
-  if (!config2?.events) {
+async function registerSSEEndpoint(app, config) {
+  if (!config?.events) {
     return;
   }
-  const eventsConfig = config2.eventsConfig ?? {};
-  const path = eventsConfig.path ?? "/events/stream";
-  const debug = isDebugMode(config2);
-  app.get(path, createSSEHandler(config2.events, eventsConfig));
+  const eventsConfig = config.eventsConfig ?? {};
+  const streamPath = eventsConfig.path ?? "/events/stream";
+  const authConfig = eventsConfig.auth;
+  const debug = isDebugMode(config);
+  let tokenManager;
+  if (authConfig?.enabled) {
+    let store = authConfig.store;
+    if (!store) {
+      try {
+        const { getCache: getCache2 } = await import('@spfn/core/cache');
+        const cache2 = getCache2();
+        if (cache2) {
+          store = new CacheTokenStore(cache2);
+          if (debug) {
+            serverLogger.info("SSE token store: cache (Redis/Valkey)");
+          }
+        }
+      } catch {
+      }
+    }
+    const externalManager = typeof authConfig.tokenManager === "function" ? authConfig.tokenManager() : authConfig.tokenManager;
+    tokenManager = externalManager ?? new SSETokenManager({
+      ttl: authConfig.tokenTtl,
+      store
+    });
+    const tokenPath = streamPath.replace(/\/[^/]+$/, "/token");
+    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) => {
+      const subject = getSubject(c);
+      if (!subject) {
+        return c.json({ error: "Unable to identify subject" }, 401);
+      }
+      const token = await tokenManager.issue(subject);
+      return c.json({ token });
+    });
+    if (debug) {
+      serverLogger.info(`\u2713 SSE token endpoint registered at POST ${tokenPath}`);
+    }
+  }
+  const transport = await wireEventRouterCache(config.events, {
+    multiInstance: eventsConfig.multiInstance,
+    channelPrefix: eventsConfig.channelPrefix
+  });
+  app.get(streamPath, createSSEHandler(config.events, eventsConfig, tokenManager));
   if (debug) {
-    const eventNames = config2.events.eventNames;
-    serverLogger.info(`\u2713 SSE endpoint registered at ${path}`, {
-      events: eventNames
+    const eventNames = config.events.eventNames;
+    serverLogger.info(`\u2713 SSE endpoint registered at ${streamPath}`, {
+      events: eventNames,
+      auth: !!authConfig?.enabled,
+      transport
     });
   }
 }
-function isDebugMode(config2) {
-  return config2?.debug ?? process.env.NODE_ENV === "development";
+function isDebugMode(config) {
+  return config?.debug ?? process.env.NODE_ENV === "development";
 }
 var jobLogger = logger.child("@spfn/core:job");
-var bossInstance = null;
-var bossConfig = null;
+function requiresSSLWithoutVerification(connectionString) {
+  try {
+    const url = new URL(connectionString);
+    const sslmode = url.searchParams.get("sslmode");
+    return sslmode === "require" || sslmode === "prefer";
+  } catch {
+    return false;
+  }
+}
+function stripSslModeFromUrl(connectionString) {
+  const url = new URL(connectionString);
+  url.searchParams.delete("sslmode");
+  return url.toString();
+}
+var BOSS_KEY = Symbol.for("spfn:boss-instance");
+var CONFIG_KEY = Symbol.for("spfn:boss-config");
+var g = globalThis;
+function getBossInstance() {
+  return g[BOSS_KEY] ?? null;
+}
+function setBossInstance(instance2) {
+  g[BOSS_KEY] = instance2;
+}
+function getBossConfig() {
+  return g[CONFIG_KEY] ?? null;
+}
+function setBossConfig(config) {
+  g[CONFIG_KEY] = config;
+}
 async function initBoss(options) {
-  if (bossInstance) {
+  const existing = getBossInstance();
+  if (existing) {
     jobLogger.warn("pg-boss already initialized, returning existing instance");
-    return bossInstance;
+    return existing;
   }
   jobLogger.info("Initializing pg-boss...");
-  bossConfig = options;
+  setBossConfig(options);
+  const needsSSL = requiresSSLWithoutVerification(options.connectionString);
   const pgBossOptions = {
-    connectionString: options.connectionString,
+    // pg 드라이버가 URL의 sslmode=require를 verify-full로 해석해서
+    // ssl 옵션을 무시하므로, URL에서 sslmode를 빼고 ssl 객체만 전달
+    connectionString: needsSSL ? stripSslModeFromUrl(options.connectionString) : options.connectionString,
     schema: options.schema ?? "spfn_queue",
     maintenanceIntervalSeconds: options.maintenanceIntervalSeconds ?? 120
   };
+  if (needsSSL) {
+    pgBossOptions.ssl = { rejectUnauthorized: false };
+  }
   if (options.monitorIntervalSeconds !== void 0 && options.monitorIntervalSeconds >= 1) {
     pgBossOptions.monitorIntervalSeconds = options.monitorIntervalSeconds;
   }
-  bossInstance = new PgBoss(pgBossOptions);
-  bossInstance.on("error", (error) => {
+  const boss = new PgBoss(pgBossOptions);
+  boss.on("error", (error) => {
     jobLogger.error("pg-boss error:", error);
   });
-  await bossInstance.start();
+  await boss.start();
+  setBossInstance(boss);
   jobLogger.info("pg-boss started successfully");
-  return bossInstance;
+  return boss;
 }
 function getBoss() {
-  return bossInstance;
+  return getBossInstance();
 }
 async function stopBoss() {
-  if (!bossInstance) {
+  const boss = getBossInstance();
+  if (!boss) {
     return;
   }
   jobLogger.info("Stopping pg-boss...");
   try {
-    await bossInstance.stop({ graceful: true, timeout: 3e4 });
+    await boss.stop({ graceful: true, timeout: 3e4 });
     jobLogger.info("pg-boss stopped gracefully");
   } catch (error) {
     jobLogger.error("Error stopping pg-boss:", error);
     throw error;
   } finally {
-    bossInstance = null;
-    bossConfig = null;
+    setBossInstance(null);
+    setBossConfig(null);
   }
 }
 function shouldClearOnStart() {
-  return bossConfig?.clearOnStart ?? false;
+  return getBossConfig()?.clearOnStart ?? false;
+}
+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;
@@ -710,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;
 }
-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}`;
 }
@@ -730,6 +2335,9 @@ 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,
     expireInSeconds: options?.expireInSeconds ?? 300
   };
 }
@@ -740,58 +2348,147 @@ 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) {
         const eventQueue = getEventQueueName(job2.subscribedEvent);
         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) {
+    if (job2.cronExpression) {
+      registeredCronNames.add(job2.name);
+    }
+  }
+  if (shouldSweepOrphanSchedules()) {
+    await sweepOrphanSchedules(boss);
+  }
+  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) {
+    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) {
+      jobLogger3.debug("No orphan schedules found");
+      return;
+    }
+    await Promise.all(orphans.map(async (orphan) => {
+      try {
+        await boss.unschedule(orphan.name, orphan.key);
+        jobLogger3.info(`Removed orphan schedule: ${orphan.name}`);
+      } catch (error) {
+        jobLogger3.error(`Failed to remove orphan schedule: ${orphan.name}`, {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }));
+  } catch (error) {
+    jobLogger3.error("Orphan schedule sweep failed", {
+      error: error instanceof Error ? error.message : String(error)
+    });
   }
-  for (const job2 of jobs) {
-    await registerJob(job2);
+}
+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;
   }
-  jobLogger2.info("All jobs registered successfully");
+  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 ensureQueue(boss, queueName) {
-  await boss.createQueue(queueName);
+async function executeJobHandler(job2, pgBossJob) {
+  jobLogger3.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
+  const startTime = Date.now();
+  try {
+    if (job2.inputSchema) {
+      await job2.handler(pgBossJob.data);
+    } else {
+      await job2.handler();
+    }
+    const duration = Date.now() - startTime;
+    jobLogger3.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
+      jobId: pgBossJob.id,
+      duration
+    });
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    jobLogger3.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
+      jobId: pgBossJob.id,
+      duration,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    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(
     queueName,
-    { batchSize: 1 },
-    async (jobs) => {
-      for (const pgBossJob of jobs) {
-        jobLogger2.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
-        const startTime = Date.now();
-        try {
-          if (job2.inputSchema) {
-            await job2.handler(pgBossJob.data);
-          } else {
-            await job2.handler();
-          }
-          const duration = Date.now() - startTime;
-          jobLogger2.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`, {
-            jobId: pgBossJob.id,
-            duration,
-            error: error instanceof Error ? error.message : String(error)
-          });
-          throw error;
+    { batchSize, pollingIntervalSeconds },
+    async (pgBossJobs) => {
+      if (batchSize <= 1) {
+        await executeJobHandler(job2, pgBossJobs[0]);
+        return;
+      }
+      const results = await Promise.allSettled(
+        pgBossJobs.map((pgBossJob) => executeJobHandler(job2, pgBossJob))
+      );
+      const failedIds = [];
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === "rejected") {
+          failedIds.push(pgBossJobs[i].id);
         }
       }
+      if (failedIds.length > 0) {
+        await boss.fail(queueName, failedIds);
+      }
     }
   );
 }
@@ -803,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,
     {},
@@ -833,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();
@@ -841,15 +2538,271 @@ 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) {
+  if (!allowList) {
+    return true;
+  }
+  if (!origin) {
+    return true;
+  }
+  return allowList.has(origin);
+}
+async function attachWSHandler(server, router, config = {}, tokenManager) {
+  const WebSocketServer = await loadWSServer();
+  const {
+    pingInterval = 3e4,
+    path = "/ws",
+    maxPayload = 1048576,
+    maxBufferedBytes = 1048576,
+    maxConnections = 1e4,
+    maxConnectionsPerSubject = 0,
+    allowedOrigins,
+    auth: authConfig
+  } = config;
+  const originAllowList = allowedOrigins && allowedOrigins.length > 0 ? new Set(allowedOrigins) : null;
+  if (authConfig?.enabled && !tokenManager) {
+    throw new Error(
+      "WebSocket auth.enabled=true requires a tokenManager. Pass tokenManager or use .websockets(router, { auth: { enabled: true } }) via startServer."
+    );
+  }
+  const wss = new WebSocketServer({ server, path, maxPayload });
+  const clients = /* @__PURE__ */ new Set();
+  const subjectCounts = /* @__PURE__ */ new Map();
+  wss.on("connection", (ws, req) => {
+    if (!isOriginAllowed(req.headers?.origin, originAllowList)) {
+      wsLogger.warn("WebSocket rejected: disallowed origin", { origin: req.headers?.origin });
+      ws.close(1008, "Origin not allowed");
+      return;
+    }
+    if (clients.size >= maxConnections) {
+      ws.close(1013, "Server at capacity");
+      return;
+    }
+    clients.add(ws);
+    ws.on("close", () => clients.delete(ws));
+    handleConnection(ws, req, router, authConfig, tokenManager, {
+      pingInterval,
+      maxBufferedBytes,
+      maxConnectionsPerSubject,
+      subjectCounts
+    }).catch((err) => {
+      wsLogger.error("WebSocket connection handler error", err);
+      if (ws.readyState === 1) ws.close(1011, "Internal server error");
+    });
+  });
+  wss.on("error", (err) => {
+    wsLogger.error("WebSocket server error", err);
+  });
+  wsLogger.info(`\u2713 WebSocket endpoint registered at ${path}`, {
+    events: router.eventNames,
+    auth: !!authConfig?.enabled
+  });
+  return () => new Promise((resolve2, reject) => {
+    for (const client of clients) {
+      client.close(1001, "Server shutting down");
+    }
+    clients.clear();
+    wss.close((err) => {
+      if (err) reject(err);
+      else resolve2();
+    });
+  });
+}
+async function handleConnection(ws, req, router, authConfig, tokenManager, opts) {
+  const { pingInterval, maxBufferedBytes, maxConnectionsPerSubject, subjectCounts } = opts;
+  let pingTimer;
+  let connectionUnsubscribes = [];
+  let subscribedEvents = [];
+  ws.on("close", () => {
+    clearInterval(pingTimer);
+    connectionUnsubscribes.forEach((fn) => fn());
+    if (subscribedEvents.length > 0)
+      wsLogger.info("WebSocket connection closed", { events: subscribedEvents });
+  });
+  const url = parseURL(req);
+  if (!url) {
+    ws.close(1002, "Invalid request URL");
+    return;
+  }
+  const subject = await resolveSubject(url, authConfig?.enabled ? tokenManager : void 0);
+  if (subject === false) {
+    ws.close(4001, "Missing token");
+    return;
+  }
+  if (subject === null) {
+    ws.close(4001, "Invalid or expired token");
+    return;
+  }
+  const requestedEvents = parseRequestedEvents2(url, router.eventNames);
+  if (requestedEvents.length === 0) {
+    ws.close(4e3, "No valid event names specified");
+    return;
+  }
+  const allowedEvents = await resolveAllowedEvents(subject, requestedEvents, authConfig);
+  if (allowedEvents === null) {
+    ws.close(4003, "Not authorized for any requested events");
+    return;
+  }
+  if (maxConnectionsPerSubject > 0 && typeof subject === "string") {
+    const current = subjectCounts.get(subject) ?? 0;
+    if (current >= maxConnectionsPerSubject) {
+      ws.close(1013, "Too many connections for this subject");
+      return;
+    }
+    subjectCounts.set(subject, current + 1);
+    ws.on("close", () => {
+      const remaining = (subjectCounts.get(subject) ?? 1) - 1;
+      if (remaining <= 0) subjectCounts.delete(subject);
+      else subjectCounts.set(subject, remaining);
+    });
+  }
+  subscribedEvents = allowedEvents;
+  wsLogger.info("WebSocket connection established", {
+    events: allowedEvents,
+    subject: subject ?? void 0
+  });
+  const connection = createConnection(ws, maxBufferedBytes);
+  connectionUnsubscribes = subscribeEvents(ws, router, allowedEvents, subject, authConfig, maxBufferedBytes);
+  if (ws.readyState !== 1) {
+    connectionUnsubscribes.forEach((fn) => fn());
+    connectionUnsubscribes = [];
+    return;
+  }
+  ws.on("message", (data) => {
+    onClientMessage(data, router, connection, subject).catch((err) => wsLogger.error("Unhandled message error", err));
+  });
+  if (pingInterval > 0) {
+    ws.isAlive = true;
+    ws.on("pong", () => {
+      ws.isAlive = true;
+    });
+    pingTimer = setInterval(() => {
+      if (ws.readyState !== 1) return;
+      if (ws.isAlive === false) {
+        ws.terminate();
+        return;
+      }
+      ws.isAlive = false;
+      ws.ping();
+    }, pingInterval);
+  }
+  connection.send("__connected", {
+    subscribedEvents: allowedEvents,
+    timestamp: Date.now()
+  });
+}
+function parseURL(req) {
+  try {
+    return new URL(req.url ?? "/", "ws://localhost");
+  } catch {
+    return null;
+  }
+}
+async function resolveSubject(url, tokenManager) {
+  if (!tokenManager) {
+    return void 0;
+  }
+  const token = url.searchParams.get("token");
+  if (!token) {
+    return false;
+  }
+  return await tokenManager.verify(token);
+}
+function parseRequestedEvents2(url, validEventNames) {
+  const eventsParam = url.searchParams.get("events");
+  if (!eventsParam) {
+    return [];
+  }
+  return eventsParam.split(",").map((e) => e.trim()).filter((e) => validEventNames.includes(e));
+}
+async function resolveAllowedEvents(subject, requestedEvents, authConfig) {
+  if (!subject || !authConfig?.authorize) {
+    return requestedEvents;
+  }
+  const allowed = await authConfig.authorize(subject, requestedEvents);
+  return allowed.length === 0 ? null : allowed;
+}
+function safeSend(ws, frame, maxBufferedBytes) {
+  if (ws.readyState !== 1) return;
+  if (ws.bufferedAmount > maxBufferedBytes) {
+    ws.close(1013, "Send buffer overflow");
+    return;
+  }
+  try {
+    ws.send(JSON.stringify(frame));
+  } catch {
+  }
+}
+function createConnection(ws, maxBufferedBytes) {
+  return {
+    send: (type, payload) => safeSend(ws, { type, data: payload }, maxBufferedBytes),
+    close: (code, reason) => ws.close(code, reason)
+  };
+}
+function subscribeEvents(ws, router, allowedEvents, subject, authConfig, maxBufferedBytes) {
+  const unsubscribes = [];
+  for (const eventName of allowedEvents) {
+    const eventDef = router.events[eventName];
+    if (!eventDef) continue;
+    const unsubscribe = eventDef.subscribe((payload) => {
+      if (ws.readyState !== 1) return;
+      if (subject && authConfig?.filter?.[eventName]) {
+        if (!authConfig.filter[eventName](subject, payload)) return;
+      }
+      safeSend(ws, { type: eventName, data: payload }, maxBufferedBytes);
+    });
+    unsubscribes.push(unsubscribe);
+  }
+  return unsubscribes;
+}
+async function onClientMessage(data, router, connection, subject) {
+  let message;
+  try {
+    message = JSON.parse(data.toString());
+  } catch {
+    return;
+  }
+  const { type, data: payload } = message;
+  if (!type) return;
+  const handler = router.messages[type];
+  if (!handler) return;
+  try {
+    await handler({ payload, subject, ws: connection });
+  } catch (err) {
+    wsLogger.error(`WebSocket message handler error: ${type}`, err);
+  }
+}
+function resolveWSServerCtor(mod) {
+  return mod.WebSocketServer ?? mod.Server ?? mod.default?.WebSocketServer ?? mod.default?.Server;
+}
+async function loadWSServer() {
+  let mod;
+  try {
+    mod = await import('ws');
+  } catch {
+    throw new Error(
+      '@spfn/core WebSocket support requires the "ws" package.\nInstall it with: pnpm add ws'
+    );
+  }
+  const WSS = resolveWSServerCtor(mod);
+  if (typeof WSS !== "function") {
+    throw new Error(
+      "WebSocketServer not found in ws module. Ensure ws@^8 is installed: pnpm add ws"
+    );
+  }
+  return WSS;
 }
 function getNetworkAddress() {
   const nets = networkInterfaces();
@@ -886,18 +2839,57 @@ 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(config2) {
-  if (config2.port !== void 0) {
-    if (!Number.isInteger(config2.port) || config2.port < 0 || config2.port > 65535) {
+function validateServerConfig(config) {
+  if (config.port !== void 0) {
+    if (!Number.isInteger(config.port) || config.port < 0 || config.port > 65535) {
       throw new Error(
-        `Invalid port: ${config2.port}. Port must be an integer between 0 and 65535.`
+        `Invalid port: ${config.port}. Port must be an integer between 0 and 65535.`
       );
     }
   }
-  if (config2.timeout) {
-    const { request, keepAlive, headers } = config2.timeout;
+  if (config.timeout) {
+    const { request, keepAlive, headers } = config.timeout;
     if (request !== void 0 && (request < 0 || !Number.isFinite(request))) {
       throw new Error(`Invalid timeout.request: ${request}. Must be a positive number.`);
     }
@@ -913,16 +2905,16 @@ function validateServerConfig(config2) {
       );
     }
   }
-  if (config2.shutdown?.timeout !== void 0) {
-    const timeout = config2.shutdown.timeout;
+  if (config.shutdown?.timeout !== void 0) {
+    const timeout = config.shutdown.timeout;
     if (timeout < 0 || !Number.isFinite(timeout)) {
       throw new Error(`Invalid shutdown.timeout: ${timeout}. Must be a positive number.`);
     }
   }
-  if (config2.healthCheck?.path) {
-    if (!config2.healthCheck.path.startsWith("/")) {
+  if (config.healthCheck?.path) {
+    if (!config.healthCheck.path.startsWith("/")) {
       throw new Error(
-        `Invalid healthCheck.path: "${config2.healthCheck.path}". Must start with "/".`
+        `Invalid healthCheck.path: "${config.healthCheck.path}". Must start with "/".`
       );
     }
   }
@@ -931,19 +2923,19 @@ var DEFAULT_MAX_LISTENERS = 15;
 var TIMEOUTS = {
   SERVER_CLOSE: 5e3,
   DATABASE_CLOSE: 5e3,
-  REDIS_CLOSE: 5e3,
-  PRODUCTION_ERROR_SHUTDOWN: 1e4
-};
+  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(config2) {
-  loadEnvFiles();
-  const finalConfig = await loadAndMergeConfig(config2);
+async function startServer(config) {
+  loadEnv();
+  const finalConfig = await loadAndMergeConfig(config);
   const { host, port, debug } = finalConfig;
   validateServerConfig(finalConfig);
   if (!host || !port) {
@@ -957,10 +2949,17 @@ async function startServer(config2) {
   };
   try {
     await initializeInfrastructure(finalConfig);
+    await runMigrationBootGate(finalConfig);
     const app = await createServer(finalConfig);
     const server = startHttpServer(app, host, port);
+    let wsCleanup;
+    if (finalConfig.websockets) {
+      wsCleanup = await initializeWebSocket(server, app, finalConfig);
+    }
     const timeouts = getTimeoutConfig(finalConfig.timeout);
     applyServerTimeouts(server, timeouts);
+    const fetchTimeouts = getFetchTimeoutConfig(finalConfig.fetchTimeout);
+    applyGlobalFetchTimeouts(fetchTimeouts);
     logServerTimeouts(timeouts);
     printBanner({
       mode: debug ? "Development" : "Production",
@@ -968,7 +2967,7 @@ async function startServer(config2) {
       port
     });
     logServerStarted(debug, host, port, finalConfig, timeouts);
-    const shutdownServer = createShutdownHandler(server, finalConfig, shutdownState);
+    const shutdownServer = createShutdownHandler(server, finalConfig, shutdownState, wsCleanup);
     const shutdown = createGracefulShutdown(shutdownServer, finalConfig, shutdownState);
     registerProcessHandlers(shutdown);
     const serverInstance = {
@@ -977,11 +2976,6 @@ async function startServer(config2) {
       config: finalConfig,
       close: async () => {
         serverLogger.info("Manual server shutdown requested");
-        if (shutdownState.isShuttingDown) {
-          serverLogger.warn("Shutdown already in progress, ignoring manual close request");
-          return;
-        }
-        shutdownState.isShuttingDown = true;
         await shutdownServer();
       }
     };
@@ -1001,8 +2995,7 @@ async function startServer(config2) {
     throw error;
   }
 }
-async function loadAndMergeConfig(config2) {
-  const cwd = process.cwd();
+async function loadAndMergeConfig(config, cwd = process.cwd()) {
   let fileConfig = {};
   let loadedConfigPath = null;
   for (const configPath of CONFIG_FILE_PATHS) {
@@ -1020,31 +3013,52 @@ async function loadAndMergeConfig(config2) {
   }
   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,
-    ...config2,
-    port: config2?.port ?? fileConfig?.port ?? env.PORT,
-    host: config2?.host ?? fileConfig?.host ?? env.HOST
+    ...config,
+    port: address.port,
+    host: address.host
   };
 }
-function getInfrastructureConfig(config2) {
+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: config2.infrastructure?.database !== false,
-    redis: config2.infrastructure?.redis !== false
+    database: config.infrastructure?.database !== false,
+    redis: config.infrastructure?.redis !== false
   };
 }
-async function initializeInfrastructure(config2) {
-  if (config2.lifecycle?.beforeInfrastructure) {
+async function initializeInfrastructure(config) {
+  if (config.lifecycle?.beforeInfrastructure) {
     serverLogger.debug("Executing beforeInfrastructure hook...");
-    await config2.lifecycle.beforeInfrastructure(config2);
+    await config.lifecycle.beforeInfrastructure(config);
   }
-  const infraConfig = getInfrastructureConfig(config2);
+  const infraConfig = getInfrastructureConfig(config);
   if (infraConfig.database) {
     serverLogger.debug("Initializing database...");
-    await initDatabase(config2.database);
+    await initDatabase(config.database);
   } else {
     serverLogger.debug("Database initialization disabled");
   }
@@ -1054,11 +3068,11 @@ async function initializeInfrastructure(config2) {
   } else {
     serverLogger.debug("Redis initialization disabled");
   }
-  if (config2.lifecycle?.afterInfrastructure) {
+  if (config.lifecycle?.afterInfrastructure) {
     serverLogger.debug("Executing afterInfrastructure hook...");
-    await config2.lifecycle.afterInfrastructure();
+    await config.lifecycle.afterInfrastructure();
   }
-  if (config2.jobs) {
+  if (config.jobs) {
     const dbUrl = env.DATABASE_URL;
     if (!dbUrl) {
       throw new Error(
@@ -1068,22 +3082,22 @@ async function initializeInfrastructure(config2) {
     serverLogger.debug("Initializing pg-boss...");
     await initBoss({
       connectionString: dbUrl,
-      ...config2.jobsConfig
+      ...config.jobsConfig
     });
     serverLogger.debug("Registering jobs...");
-    await registerJobs(config2.jobs);
+    await registerJobs(config.jobs);
   }
-  if (config2.workflows) {
-    const infraConfig2 = getInfrastructureConfig(config2);
+  if (config.workflows) {
+    const infraConfig2 = getInfrastructureConfig(config);
     if (!infraConfig2.database) {
       throw new Error(
         "Workflows require database connection. Ensure database is enabled in infrastructure config."
       );
     }
     serverLogger.debug("Initializing workflow engine...");
-    config2.workflows._init(
+    config.workflows._init(
       getDatabase(),
-      config2.workflowsConfig
+      config.workflowsConfig
     );
     serverLogger.info("Workflow engine initialized");
   }
@@ -1096,8 +3110,52 @@ function startHttpServer(app, host, port) {
     hostname: host
   });
 }
-function logMiddlewareOrder(config2) {
-  const middlewareOrder = buildMiddlewareOrder(config2);
+async function initializeWebSocket(server, app, config) {
+  const wsRouter = config.websockets;
+  const wsConfig = config.websocketsConfig ?? {};
+  const authConfig = wsConfig.auth;
+  const wsPath = wsConfig.path ?? "/ws";
+  const debug = config.debug ?? process.env.NODE_ENV === "development";
+  let tokenManager;
+  if (authConfig?.enabled) {
+    let store = authConfig.store;
+    if (!store) {
+      try {
+        const { getCache: getCache2 } = await import('@spfn/core/cache');
+        const cache2 = getCache2();
+        if (cache2) {
+          store = new CacheTokenStore(cache2);
+          if (debug) serverLogger.info("WS token store: cache (Redis/Valkey)");
+        }
+      } catch {
+      }
+    }
+    const externalManager = typeof authConfig.tokenManager === "function" ? authConfig.tokenManager() : authConfig.tokenManager;
+    tokenManager = externalManager ?? new SSETokenManager({
+      ttl: authConfig.tokenTtl,
+      store
+    });
+    const tokenPath = wsPath.replace(/\/[^/]+$/, "/token");
+    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) => {
+      const subject = getSubject(c);
+      if (!subject) {
+        return c.json({ error: "Unable to identify subject" }, 401);
+      }
+      const token = await tokenManager.issue(subject);
+      return c.json({ token });
+    });
+    if (debug) serverLogger.info(`\u2713 WS token endpoint registered at POST ${tokenPath}`);
+  }
+  await wireEventRouterCache(wsRouter, {
+    multiInstance: wsConfig.multiInstance,
+    channelPrefix: wsConfig.channelPrefix
+  });
+  return await attachWSHandler(server, wsRouter, wsConfig, tokenManager);
+}
+function logMiddlewareOrder(config) {
+  const middlewareOrder = buildMiddlewareOrder(config);
   serverLogger.debug("Middleware execution order", {
     order: middlewareOrder
   });
@@ -1109,8 +3167,8 @@ function logServerTimeouts(timeouts) {
     headers: `${timeouts.headers}ms`
   });
 }
-function logServerStarted(debug, host, port, config2, timeouts) {
-  const startupConfig = buildStartupConfig(config2, timeouts);
+function logServerStarted(debug, host, port, config, timeouts) {
+  const startupConfig = buildStartupConfig(config, timeouts);
   serverLogger.info("Server started successfully", {
     mode: debug ? "development" : "production",
     host,
@@ -1118,65 +3176,84 @@ function logServerStarted(debug, host, port, config2, timeouts) {
     config: startupConfig
   });
 }
-function createShutdownHandler(server, config2, shutdownState) {
+function createShutdownHandler(server, config, shutdownState, wsCleanup) {
   return async () => {
     if (shutdownState.isShuttingDown) {
       serverLogger.debug("Shutdown already in progress for this instance, skipping");
       return;
     }
     shutdownState.isShuttingDown = true;
-    serverLogger.debug("Closing HTTP server...");
-    let timeoutId;
-    await Promise.race([
-      new Promise((resolve2, reject) => {
-        server.close((err) => {
-          if (timeoutId) clearTimeout(timeoutId);
-          if (err) {
-            serverLogger.error("HTTP server close error", err);
-            reject(err);
-          } else {
-            serverLogger.info("HTTP server closed");
-            resolve2();
-          }
-        });
-      }),
-      new Promise((_, reject) => {
-        timeoutId = setTimeout(() => {
-          reject(new Error(`HTTP server close timeout after ${TIMEOUTS.SERVER_CLOSE}ms`));
-        }, TIMEOUTS.SERVER_CLOSE);
-      })
-    ]).catch((error) => {
-      if (timeoutId) clearTimeout(timeoutId);
-      serverLogger.warn("HTTP server close timeout, forcing shutdown", error);
-    });
-    if (config2.jobs) {
-      serverLogger.debug("Stopping pg-boss...");
+    const shutdownTimeout = getShutdownTimeout(config.shutdown);
+    const shutdownManager = getShutdownManager();
+    shutdownManager.beginShutdown();
+    serverLogger.info("Phase 1: Closing HTTP server (stop accepting new connections)...");
+    await closeHttpServer(server);
+    if (wsCleanup) {
+      serverLogger.info("Phase 1.5: Closing WebSocket server...");
+      try {
+        await wsCleanup();
+        serverLogger.info("WebSocket server closed");
+      } catch (error) {
+        serverLogger.error("WebSocket server close failed", error);
+      }
+    }
+    if (config.jobs) {
+      serverLogger.info("Phase 2: Stopping pg-boss...");
       try {
         await stopBoss();
+        serverLogger.info("pg-boss stopped");
       } catch (error) {
         serverLogger.error("pg-boss stop failed", error);
       }
     }
-    if (config2.lifecycle?.beforeShutdown) {
-      serverLogger.debug("Executing beforeShutdown hook...");
+    const drainTimeout = Math.floor(shutdownTimeout * 0.8);
+    serverLogger.info(`Phase 3: Draining tracked operations (timeout: ${drainTimeout}ms)...`);
+    await shutdownManager.execute(drainTimeout);
+    if (config.lifecycle?.beforeShutdown) {
+      serverLogger.info("Phase 4: Executing beforeShutdown lifecycle hook...");
       try {
-        await config2.lifecycle.beforeShutdown();
+        await config.lifecycle.beforeShutdown();
       } catch (error) {
-        serverLogger.error("beforeShutdown hook failed", error);
+        serverLogger.error("beforeShutdown lifecycle hook failed", error);
       }
     }
-    const infraConfig = getInfrastructureConfig(config2);
+    serverLogger.info("Phase 5: Closing infrastructure...");
+    const infraConfig = getInfrastructureConfig(config);
     if (infraConfig.database) {
-      serverLogger.debug("Closing database connections...");
       await closeInfrastructure(closeDatabase, "Database", TIMEOUTS.DATABASE_CLOSE);
     }
     if (infraConfig.redis) {
-      serverLogger.debug("Closing Redis connections...");
+      await closeEventTransport();
       await closeInfrastructure(closeCache, "Redis", TIMEOUTS.REDIS_CLOSE);
     }
     serverLogger.info("Server shutdown completed");
   };
 }
+async function closeHttpServer(server) {
+  let timeoutId;
+  await Promise.race([
+    new Promise((resolve2, reject) => {
+      server.close((err) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        if (err) {
+          serverLogger.error("HTTP server close error", err);
+          reject(err);
+        } else {
+          serverLogger.info("HTTP server closed");
+          resolve2();
+        }
+      });
+    }),
+    new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`HTTP server close timeout after ${TIMEOUTS.SERVER_CLOSE}ms`));
+      }, TIMEOUTS.SERVER_CLOSE);
+    })
+  ]).catch((error) => {
+    if (timeoutId) clearTimeout(timeoutId);
+    serverLogger.warn("HTTP server close timeout, forcing shutdown", error);
+  });
+}
 async function closeInfrastructure(closeFn, name, timeout) {
   let timeoutId;
   try {
@@ -1196,14 +3273,14 @@ async function closeInfrastructure(closeFn, name, timeout) {
     serverLogger.error(`${name} close failed or timed out`, error);
   }
 }
-function createGracefulShutdown(shutdownServer, config2, shutdownState) {
+function createGracefulShutdown(shutdownServer, config, shutdownState) {
   return async (signal) => {
     if (shutdownState.isShuttingDown) {
       serverLogger.warn(`${signal} received but shutdown already in progress, ignoring`);
       return;
     }
     serverLogger.info(`${signal} received, starting graceful shutdown...`);
-    const shutdownTimeout = getShutdownTimeout(config2.shutdown);
+    const shutdownTimeout = getShutdownTimeout(config.shutdown);
     let timeoutId;
     try {
       await Promise.race([
@@ -1231,31 +3308,8 @@ function createGracefulShutdown(shutdownServer, config2, shutdownState) {
     }
   };
 }
-function handleProcessError(errorType, shutdown) {
-  const isProduction = env.NODE_ENV === "production";
-  const isDevelopment = env.NODE_ENV === "development";
-  if (isDevelopment || process.env.WATCH_MODE === "true") {
-    serverLogger.info("Exiting immediately for clean restart");
-    process.exit(1);
-  } else if (isProduction) {
-    serverLogger.info(`Attempting graceful shutdown after ${errorType}`);
-    const forceExitTimer = setTimeout(() => {
-      serverLogger.error(`Forced exit after ${TIMEOUTS.PRODUCTION_ERROR_SHUTDOWN}ms - graceful shutdown did not complete`);
-      process.exit(1);
-    }, TIMEOUTS.PRODUCTION_ERROR_SHUTDOWN);
-    shutdown(errorType).then(() => {
-      clearTimeout(forceExitTimer);
-      serverLogger.info("Graceful shutdown completed, exiting");
-      process.exit(0);
-    }).catch((shutdownError) => {
-      clearTimeout(forceExitTimer);
-      serverLogger.error("Graceful shutdown failed", shutdownError);
-      process.exit(1);
-    });
-  } else {
-    serverLogger.info("Exiting immediately");
-    process.exit(1);
-  }
+function handleProcessError(errorType) {
+  serverLogger.warn(`${errorType} occurred - server continues running. Check logs above for details.`);
 }
 function registerProcessHandlers(shutdown) {
   if (processHandlersRegistered) {
@@ -1290,7 +3344,7 @@ function registerProcessHandlers(shutdown) {
     } else {
       serverLogger.error("Uncaught exception", error);
     }
-    handleProcessError("UNCAUGHT_EXCEPTION", shutdown);
+    handleProcessError("UNCAUGHT_EXCEPTION");
   });
   process.on("unhandledRejection", (reason, promise) => {
     if (reason instanceof Error) {
@@ -1308,25 +3362,89 @@ function registerProcessHandlers(shutdown) {
         promise
       });
     }
-    handleProcessError("UNHANDLED_REJECTION", shutdown);
+    handleProcessError("UNHANDLED_REJECTION");
   });
   serverLogger.debug("Process-level shutdown handlers registered successfully");
 }
-async function cleanupOnFailure(config2) {
+async function cleanupOnFailure(config) {
   try {
     serverLogger.debug("Cleaning up after initialization failure...");
-    const infraConfig = getInfrastructureConfig(config2);
+    const infraConfig = getInfrastructureConfig(config);
     if (infraConfig.database) {
       await closeInfrastructure(closeDatabase, "Database", TIMEOUTS.DATABASE_CLOSE);
     }
     if (infraConfig.redis) {
+      await closeEventTransport();
       await closeInfrastructure(closeCache, "Redis", TIMEOUTS.REDIS_CLOSE);
     }
+    resetShutdownManager();
     serverLogger.debug("Cleanup completed");
   } catch (cleanupError) {
     serverLogger.error("Cleanup failed", cleanupError);
   }
 }
+function getInfrastructure(config) {
+  return {
+    database: config?.infrastructure?.database !== false,
+    redis: config?.infrastructure?.redis !== false
+  };
+}
+function withServerlessDefaults(config) {
+  if (!config) {
+    return config;
+  }
+  return {
+    ...config,
+    database: {
+      ...config.database,
+      healthCheck: { enabled: false, ...config.database?.healthCheck }
+    }
+  };
+}
+function warnIfJobsConfigured(config) {
+  if (config?.jobs) {
+    serverLogger.warn(
+      "Jobs are configured but this is a serverless target: the in-process pg-boss worker is NOT started here, so enqueued jobs will not be processed on this deployment. Drain the queue from a scheduled endpoint (e.g. Vercel Cron \u2192 a route that processes a batch) or run jobs on an always-on target."
+    );
+  }
+}
+async function initInfrastructure(config) {
+  const infra = getInfrastructure(config);
+  if (infra.database) {
+    await initDatabase(config?.database);
+  }
+  if (infra.redis) {
+    await initCache();
+  }
+}
+var appPromise;
+function createServerlessApp(config) {
+  if (!appPromise) {
+    appPromise = buildServerlessApp(config);
+  }
+  return appPromise;
+}
+async function buildServerlessApp(rawConfig) {
+  loadEnv();
+  const config = withServerlessDefaults(rawConfig);
+  warnIfJobsConfigured(config);
+  await initInfrastructure(config);
+  return createServer(config);
+}
+function resetServerlessApp() {
+  appPromise = void 0;
+}
+async function provisionInfrastructure(config) {
+  loadEnv();
+  if (config?.lifecycle?.beforeInfrastructure) {
+    await config.lifecycle.beforeInfrastructure(config);
+  }
+  await initInfrastructure(config);
+  if (config?.lifecycle?.afterInfrastructure) {
+    await config.lifecycle.afterInfrastructure();
+  }
+  serverLogger.info("Provisioning complete");
+}
 
 // src/server/config-builder.ts
 function collectHooks(lifecycles, key) {
@@ -1387,12 +3505,56 @@ var ServerConfigBuilder = class {
     this.config.middlewares = middlewares;
     return this;
   }
+  /**
+   * Configure proxy-guard (verify trusted-proxy signature + origin → clientType)
+   */
+  proxyGuard(proxyGuard) {
+    this.config.proxyGuard = proxyGuard;
+    return this;
+  }
+  /**
+   * Configure rate limiting: an optional global default limiter plus the named
+   * policies that `rateLimitPolicy(name, fallback)` tags resolve against.
+   *
+   * @example
+   * ```typescript
+   * .rateLimit({
+   *     mode: 'on',
+   *     default: { limit: 100, windowMs: 60_000 },
+   *     policies: { 'auth-login': { limit: 5, windowMs: 60_000 } },
+   * })
+   * ```
+   */
+  rateLimit(rateLimit2) {
+    this.config.rateLimit = rateLimit2;
+    return this;
+  }
+  /**
+   * Configure the SSRF policy for outbound `safeFetch` calls (webhooks,
+   * callbacks). Private/reserved IPs are blocked by default.
+   *
+   * @example
+   * ```typescript
+   * .outboundFetch({ allowHosts: ['hooks.slack.com'] })
+   * ```
+   */
+  outboundFetch(outboundFetch) {
+    this.config.outboundFetch = outboundFetch;
+    return this;
+  }
   /**
    * Register define-route based router
    *
-   * Automatically applies:
-   * - Global middlewares from router._globalMiddlewares (via .use())
-   * - Package routers from router._packageRouters (via .packages())
+   * Router-level middleware (`.use()`) and package routers (`.packages()`) travel
+   * with the router itself and are applied by `registerRoutes` when the routes are
+   * mounted — this method only records which router to mount.
+   *
+   * It deliberately does **not** copy `router._globalMiddlewares` into
+   * `config.middlewares`: that copy used to make `registerRoutes` see the same
+   * middleware twice (once from the config list, once from the router it was
+   * handed) and attach both to every route. Middleware that verifies a JWT survives
+   * running twice; middleware that consumes one-shot state — a nonce replay ledger —
+   * rejects its own request the second time round.
    *
    * @example
    * ```typescript
@@ -1403,34 +3565,31 @@ var ServerConfigBuilder = class {
    * .use([authMiddleware]);
    *
    * export default defineServerConfig()
-   *   .routes(appRouter)  // middlewares auto-applied
+   *   .routes(appRouter)  // .use() middleware applied once, at registration
    *   .build();
    * ```
    */
   routes(router) {
     this.config.routes = router;
-    const allGlobalMiddlewares = [];
-    if (router._globalMiddlewares?.length > 0) {
-      allGlobalMiddlewares.push(...router._globalMiddlewares);
-    }
-    if (router._packageRouters?.length > 0) {
-      for (const pkgRouter of router._packageRouters) {
-        if (pkgRouter._globalMiddlewares?.length > 0) {
-          allGlobalMiddlewares.push(...pkgRouter._globalMiddlewares);
-        }
-      }
-    }
-    if (allGlobalMiddlewares.length > 0) {
-      this.config.middlewares = [
-        ...this.config.middlewares || [],
-        ...allGlobalMiddlewares
-      ];
-    }
     return this;
   }
   /**
    * 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';
@@ -1443,14 +3602,20 @@ 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, config2) {
-    this.config.jobs = router;
-    if (config2) {
-      this.config.jobsConfig = config2;
+  jobs(router, config) {
+    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;
     }
     return this;
   }
@@ -1482,10 +3647,44 @@ var ServerConfigBuilder = class {
    * .events(eventRouter, { path: '/sse' })
    * ```
    */
-  events(router, config2) {
+  events(router, config) {
     this.config.events = router;
-    if (config2) {
-      this.config.eventsConfig = config2;
+    if (config) {
+      this.config.eventsConfig = config;
+    }
+    return this;
+  }
+  /**
+   * Register WebSocket router for bidirectional real-time communication
+   *
+   * Enables type-safe WebSocket connections with:
+   * - Server→client event push (via defineEvent + emit)
+   * - Client→server message handling (via messages in defineWSRouter)
+   *
+   * @example
+   * ```typescript
+   * // src/server/ws.ts
+   * export const wsRouter = defineWSRouter({
+   *     events: { userUpdated, notification },
+   *     messages: {
+   *         ping: ({ ws }) => ws.send('pong', {}),
+   *     },
+   * });
+   *
+   * // server.config.ts
+   * export default defineServerConfig()
+   *     .websockets(wsRouter)              // → WS /ws
+   *     .websockets(wsRouter, {
+   *         path: '/realtime',             // custom path
+   *         auth: { enabled: true },       // token authentication
+   *     })
+   *     .build();
+   * ```
+   */
+  websockets(router, config) {
+    this.config.websockets = router;
+    if (config) {
+      this.config.websocketsConfig = config;
     }
     return this;
   }
@@ -1524,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
    */
@@ -1531,6 +3739,21 @@ var ServerConfigBuilder = class {
     this.config.infrastructure = infrastructure;
     return this;
   }
+  /**
+   * Configure the migration boot gate
+   *
+   * @example
+   * ```typescript
+   * // A harness that applies migrations itself, after the server is up
+   * export default defineServerConfig()
+   *     .migrations({ allowPending: true })
+   *     .build();
+   * ```
+   */
+  migrations(migrations) {
+    this.config.migrations = migrations;
+    return this;
+  }
   /**
    * Register workflow router for workflow orchestration
    *
@@ -1551,10 +3774,10 @@ var ServerConfigBuilder = class {
    *     .build();
    * ```
    */
-  workflows(router, config2) {
+  workflows(router, config) {
     this.config.workflows = router;
-    if (config2) {
-      this.config.workflowsConfig = config2;
+    if (config) {
+      this.config.workflowsConfig = config;
     }
     return this;
   }
@@ -1605,6 +3828,6 @@ function defineServerConfig() {
   return new ServerConfigBuilder();
 }
 
-export { createServer, defineServerConfig, loadEnvFiles, 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