@spfn/core 0.3.0-beta.3 → 0.3.0-beta.30

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { env } from '@spfn/core/config';
+import { env, registry } from '@spfn/core/config';
 import { existsSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
 import { parse } from 'dotenv';
@@ -13,6 +13,7 @@ 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';
@@ -354,9 +355,10 @@ function parseEnvFile(filePath) {
   return parse(readFileSync(filePath, "utf-8"));
 }
 function loadEnv(options = {}) {
+  const nodeEnvAtEntry = process.env.NODE_ENV;
   const {
     cwd = process.cwd(),
-    nodeEnv = process.env.NODE_ENV || "local",
+    nodeEnv = nodeEnvAtEntry || "local",
     server = true,
     debug = false,
     override = false
@@ -386,8 +388,30 @@ function loadEnv(options = {}) {
     envLogger.debug(`Loaded env files: ${loadedFiles.join(", ")}`);
     envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);
   }
+  warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, options.nodeEnv, nodeEnv);
   return { loadedFiles, loadedKeys };
 }
+function warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, explicitNodeEnv, resolvedNodeEnv) {
+  if (nodeEnvAtEntry || explicitNodeEnv) {
+    return;
+  }
+  const declared = process.env.NODE_ENV;
+  if (!declared) {
+    envLogger.warn(
+      `NODE_ENV is not set anywhere; env files were resolved for "${resolvedNodeEnv}". Set NODE_ENV in the process environment to choose the file set.`
+    );
+    return;
+  }
+  if (declared === resolvedNodeEnv) {
+    return;
+  }
+  if (!existsSync(resolve(cwd, `.env.${declared}`))) {
+    return;
+  }
+  envLogger.warn(
+    `.env.${declared} was NOT loaded: NODE_ENV was not set when the process started, so env files were resolved for "${resolvedNodeEnv}" before a file declared NODE_ENV=${declared}. Set NODE_ENV in the process environment, not in a .env file.`
+  );
+}
 
 // src/server/dotenv-loader.ts
 var warned = false;
@@ -405,7 +429,15 @@ function loadEnvFiles() {
 function createBoundedWriter(stream, maxQueue, onClose) {
   const pending = [];
   let flushing = false;
+  let reserved = 0;
   let closed = false;
+  const overflows = () => {
+    if (pending.length + reserved <= maxQueue) {
+      return false;
+    }
+    onClose("outbound queue overflow (slow consumer)");
+    return true;
+  };
   const flush = async () => {
     if (flushing || closed) {
       return;
@@ -429,11 +461,19 @@ function createBoundedWriter(stream, maxQueue, onClose) {
         return;
       }
       pending.push(frame);
-      if (pending.length > maxQueue) {
-        onClose("outbound queue overflow (slow consumer)");
-        return;
+      if (!overflows()) {
+        void flush();
+      }
+    },
+    reserve() {
+      if (closed) {
+        return false;
       }
-      void flush();
+      reserved++;
+      return !overflows();
+    },
+    clearReserved() {
+      reserved = 0;
     },
     close() {
       closed = true;
@@ -444,6 +484,124 @@ function createBoundedWriter(stream, maxQueue, onClose) {
     }
   };
 }
+var registryLogger = logger.child("@spfn/core:sse");
+var SUBSCRIPTION_GRANTED = "subscription.granted";
+var SUBSCRIPTION_REVOKED = "subscription.revoked";
+function createConnectionRegistry() {
+  const bySubject = /* @__PURE__ */ new Map();
+  const pendingBySubject = /* @__PURE__ */ new Map();
+  const beginAdmission = (subject, signal) => {
+    const changes = [];
+    addToSet(pendingBySubject, subject, changes);
+    const end = endOnce(signal, () => removeFromSet(pendingBySubject, subject, changes));
+    return {
+      cancel: end,
+      open: (connection) => {
+        if (!end()) {
+          return false;
+        }
+        applyRecorded(connection, changes);
+        addToSet(bySubject, subject, connection);
+        return true;
+      }
+    };
+  };
+  const change = (kind, subject, eventName, match) => {
+    const pending = pendingBySubject.get(subject);
+    const connections = bySubject.get(subject);
+    pending?.forEach((changes) => changes.push({ kind, eventName, match }));
+    connections?.forEach((connection) => {
+      if (matchesRequest(match, connection.request)) {
+        (kind === "grant" ? grantOn : revokeOn)(connection, eventName);
+      }
+    });
+    if (!pending && !connections) {
+      registryLogger.debug("SSE subscription change for a subject with no open connection ignored", {
+        event: eventName,
+        subject
+      });
+    }
+  };
+  return {
+    beginAdmission,
+    remove: (connection) => {
+      if (connection.subject) {
+        removeFromSet(bySubject, connection.subject, connection);
+      }
+    },
+    /** Open connections only — a pending admission is not counted. */
+    count: (subject) => bySubject.get(subject)?.size ?? 0,
+    pendingCount: (subject) => pendingBySubject.get(subject)?.size ?? 0,
+    grant: (subject, eventName, match) => change("grant", subject, eventName, match),
+    revoke: (subject, eventName, match) => change("revoke", subject, eventName, match)
+  };
+}
+function endOnce(signal, remove) {
+  let ended = false;
+  const end = () => {
+    if (ended) {
+      return false;
+    }
+    ended = true;
+    signal.removeEventListener("abort", end);
+    remove();
+    return true;
+  };
+  signal.addEventListener("abort", end, { once: true });
+  if (signal.aborted) {
+    end();
+  }
+  return end;
+}
+function addToSet(map, key, value) {
+  const set = map.get(key) ?? /* @__PURE__ */ new Set();
+  set.add(value);
+  map.set(key, set);
+}
+function removeFromSet(map, key, value) {
+  const set = map.get(key);
+  set?.delete(value);
+  if (set?.size === 0) {
+    map.delete(key);
+  }
+}
+function matchesRequest(match, request) {
+  return match === void 0 || Object.entries(match.query).every(([field, value]) => Object.hasOwn(request.query, field) && request.query[field] === value);
+}
+function applyRecorded(connection, changes) {
+  changes.forEach(({ kind, eventName, match }) => {
+    if (!matchesRequest(match, connection.request)) {
+      return;
+    }
+    const [from, to] = kind === "grant" ? [connection.denied, connection.allowed] : [connection.allowed, connection.denied];
+    if (from.delete(eventName)) {
+      to.add(eventName);
+    }
+  });
+}
+function grantOn(connection, eventName) {
+  if (!connection.denied.has(eventName)) {
+    return;
+  }
+  connection.unsubscribes.set(eventName, connection.subscribe(eventName));
+  connection.denied.delete(eventName);
+  connection.allowed.add(eventName);
+  connection.notify(SUBSCRIPTION_GRANTED, eventName);
+}
+function revokeOn(connection, eventName) {
+  if (!connection.allowed.has(eventName)) {
+    return;
+  }
+  connection.unsubscribes.get(eventName)?.();
+  connection.unsubscribes.delete(eventName);
+  connection.allowed.delete(eventName);
+  connection.denied.add(eventName);
+  connection.notify(SUBSCRIPTION_REVOKED, eventName);
+}
+function unsubscribeAll(connection) {
+  connection.unsubscribes.forEach((unsubscribe) => unsubscribe());
+  connection.unsubscribes.clear();
+}
 
 // src/event/sse/handler.ts
 var sseLogger = logger.child("@spfn/core:sse");
@@ -474,125 +632,329 @@ function createSSEHandler(router, config = {}, tokenManager) {
     auth: authConfig,
     maxQueue = DEFAULT_MAX_QUEUE
   } = config;
-  return async (c) => {
-    const subject = await authenticateToken(c, tokenManager);
-    if (subject === false) {
-      return c.json({ error: "Missing token parameter" }, 401);
+  const registry = createConnectionRegistry();
+  registerSubscriptionControls(router, registry);
+  const streamConfig = { router, authConfig, registry, pingInterval, maxQueue };
+  const handler = async (c) => {
+    const admission = await admitConnection(c, streamConfig, tokenManager);
+    if (admission instanceof Response) {
+      return admission;
     }
-    if (subject === null) {
-      return c.json({ error: "Invalid or expired token" }, 401);
+    if (c.req.raw.signal.aborted) {
+      admission.pending?.cancel();
+      return new Response(null, { status: 499 });
     }
-    if (subject) {
-      c.set("sseSubject", subject);
+    c.header("X-Accel-Buffering", "no");
+    return streamSSE(c, (stream) => runStream(c, stream, admission, streamConfig), async (err) => {
+      sseLogger.error("SSE stream error", {
+        error: err.message
+      });
+    });
+  };
+  return Object.assign(handler, {
+    /** @internal Open registered connections of a subject (tests). */
+    _openConnections: (subject) => registry.count(subject),
+    /** @internal Connects of a subject still in admission (tests). */
+    _pendingAdmissions: (subject) => registry.pendingCount(subject)
+  });
+}
+function registerSubscriptionControls(router, registry) {
+  for (const eventName of router.eventNames) {
+    router.events[eventName]._registerSubscriptionControl({
+      grant: (subject, match) => registry.grant(subject, eventName, match),
+      revoke: (subject, match) => registry.revoke(subject, eventName, match)
+    });
+  }
+}
+async function admitConnection(c, config, tokenManager) {
+  const { router, authConfig, registry } = config;
+  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 requested = parseRequestedEvents(c);
+  if (!requested) {
+    return c.json({ error: "Missing events parameter" }, 400);
+  }
+  const validEventNames = router.eventNames;
+  const invalidEvents = requested.filter((e) => !validEventNames.includes(e));
+  if (invalidEvents.length > 0) {
+    return c.json({
+      error: "Invalid event names",
+      invalidEvents,
+      validEvents: validEventNames
+    }, 400);
+  }
+  return whilePending(
+    subject ? registry.beginAdmission(subject, c.req.raw.signal) : void 0,
+    () => authorizeConnection(c, router, authConfig, subject, requested)
+  );
+}
+async function whilePending(pending, check) {
+  let outcome;
+  try {
+    outcome = await check();
+    return outcome instanceof Response ? outcome : { ...outcome, pending };
+  } finally {
+    if (!outcome || outcome instanceof Response) {
+      pending?.cancel();
     }
-    const requestedEvents = parseRequestedEvents(c);
-    if (!requestedEvents) {
-      return c.json({ error: "Missing events parameter" }, 400);
+  }
+}
+async function authorizeConnection(c, router, authConfig, subject, requested) {
+  const authorized = await authorizeEvents(subject, requested, authConfig);
+  if (authorized === null) {
+    return c.json({ error: "Not authorized for any requested events" }, 403);
+  }
+  const request = { query: c.req.query(), headers: c.req.header() };
+  const resolved = await resolveConnectionPrincipal(subject, request, authConfig);
+  if (!resolved) {
+    return c.json({ error: "Principal could not be resolved" }, 403);
+  }
+  const allowed = subject ? await checkCanSubscribe(router, authorized, { subject, principal: resolved.principal, request }) : authorized;
+  const denied = requested.filter((e) => !allowed.includes(e));
+  sseLogger.debug("SSE connection requested", {
+    events: allowed,
+    deniedEvents: denied,
+    subject: subject || void 0,
+    clientIp: c.req.header("x-forwarded-for") || c.req.header("x-real-ip")
+  });
+  return { subject, requested, allowed, denied, request, principal: resolved.principal };
+}
+async function resolveConnectionPrincipal(subject, request, authConfig) {
+  if (!subject || !authConfig?.resolvePrincipal) {
+    return { principal: void 0 };
+  }
+  try {
+    return { principal: await authConfig.resolvePrincipal(subject, request) };
+  } catch {
+    sseLogger.warn("SSE principal could not be resolved \u2014 connection refused", { subject });
+    return null;
+  }
+}
+async function checkCanSubscribe(router, events, ctx) {
+  const verdicts = await Promise.all(events.map((eventName) => askCanSubscribe(eventName, router.events[eventName], ctx)));
+  return events.filter((_, i) => verdicts[i]);
+}
+async function askCanSubscribe(eventName, eventDef, ctx) {
+  if (!eventDef) {
+    return false;
+  }
+  if (!eventDef._canSubscribe) {
+    return true;
+  }
+  try {
+    return await eventDef._canSubscribe(ctx) === true;
+  } catch {
+    sseLogger.warn("SSE canSubscribe threw \u2014 event denied on this connection", {
+      event: eventName,
+      subject: ctx.subject
+    });
+    return false;
+  }
+}
+async function runStream(c, stream, admission, config) {
+  const { allowed, denied, subject, request } = admission;
+  let connectionDead = false;
+  let pingTimer;
+  let onClosed;
+  const cleanup = (reason) => {
+    if (connectionDead) return;
+    connectionDead = true;
+    clearInterval(pingTimer);
+    unsubscribeAll(connection);
+    config.registry.remove(connection);
+    writer.close();
+    onClosed?.();
+    sseLogger.info("SSE dead connection cleaned up", {
+      events: [...connection.allowed],
+      reason
+    });
+  };
+  const writer = createBoundedWriter(stream, config.maxQueue, (reason) => {
+    sseLogger.warn("SSE connection closed", { events: [...connection.allowed], reason });
+    cleanup(reason);
+  });
+  const hold = createFrameHold(writer);
+  const subscriberContext = {
+    router: config.router,
+    authConfig: config.authConfig,
+    subject,
+    request,
+    writeFrame: createFrameWriter(writer),
+    send: hold.send,
+    isDead: () => connectionDead
+  };
+  const connection = {
+    subject,
+    requested: admission.requested,
+    allowed: new Set(allowed),
+    denied: new Set(denied),
+    unsubscribes: /* @__PURE__ */ new Map(),
+    request,
+    subscribe: createEventSubscriber(subscriberContext),
+    notify: (frame, eventName) => {
+      if (connectionDead) return;
+      hold.send(() => writer.enqueue({ event: frame, data: JSON.stringify({ event: eventName }) }));
     }
-    const validEventNames = router.eventNames;
-    const invalidEvents = requestedEvents.filter((e) => !validEventNames.includes(e));
-    if (invalidEvents.length > 0) {
-      return c.json({
-        error: "Invalid event names",
-        invalidEvents,
-        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: allowedEvents,
-      subject: subject || void 0,
-      clientIp: c.req.header("x-forwarded-for") || c.req.header("x-real-ip")
+  };
+  if (admission.pending?.open(connection) === false) {
+    cleanup("aborted during admission");
+    return;
+  }
+  void openSubscriptions(connection, writer, hold, {
+    ...subscriberContext,
+    principal: admission.principal
+  });
+  pingTimer = setInterval(() => {
+    if (connectionDead) return;
+    hold.send(() => writer.enqueue({
+      event: "ping",
+      data: JSON.stringify({ timestamp: Date.now() })
+    }));
+  }, config.pingInterval);
+  await waitForDisconnect(c.req.raw.signal, () => connectionDead, (resolve2) => {
+    onClosed = resolve2;
+  });
+  cleanup();
+}
+async function openSubscriptions(connection, writer, hold, ctx) {
+  const connected = { subscribedEvents: [...connection.allowed], deniedEvents: [...connection.denied] };
+  const producing = connected.subscribedEvents.filter((eventName) => ctx.router.events[eventName]._initial);
+  if (!ctx.subject || producing.length === 0) {
+    enqueueConnected(writer, { ...connected, initial: [] });
+    subscribeAllowed(connection);
+    return;
+  }
+  hold.hold();
+  subscribeAllowed(connection);
+  const served = await produceInitialFrames(producing, ctx.router, {
+    subject: ctx.subject,
+    principal: ctx.principal,
+    request: ctx.request
+  });
+  if (ctx.isDead()) {
+    return;
+  }
+  enqueueConnected(writer, { ...connected, initial: served.map(({ eventName }) => eventName) });
+  served.forEach(({ eventName, frames }) => frames.forEach((data) => ctx.writeFrame(eventName, data)));
+  hold.release();
+}
+function enqueueConnected(writer, connected) {
+  writer.enqueue({
+    event: "connected",
+    data: JSON.stringify({ ...connected, timestamp: Date.now() })
+  });
+}
+function subscribeAllowed(connection) {
+  for (const eventName of connection.allowed) {
+    connection.unsubscribes.set(eventName, connection.subscribe(eventName));
+  }
+  sseLogger.info("SSE connection established", {
+    events: [...connection.allowed],
+    deniedEvents: [...connection.denied],
+    subscriptionCount: connection.unsubscribes.size
+  });
+}
+async function produceInitialFrames(events, router, ctx) {
+  const results = await Promise.all(events.map((eventName) => askInitial(eventName, router.events[eventName], ctx)));
+  return results.filter((frames) => frames !== null);
+}
+async function askInitial(eventName, eventDef, ctx) {
+  try {
+    const payloads = await eventDef._initial(ctx);
+    return { eventName, frames: payloads.map((payload) => serializeFrame(eventName, payload)) };
+  } catch {
+    sseLogger.warn("SSE initial frames could not be produced \u2014 none sent for this event", {
+      event: eventName,
+      subject: ctx.subject
     });
-    c.header("X-Accel-Buffering", "no");
-    return streamSSE(c, async (stream) => {
-      const unsubscribes = [];
-      let messageId = 0;
-      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++;
-          sseLogger.debug("SSE sending event", {
-            event: eventName,
-            messageId
-          });
-          writer.enqueue({
-            id: String(messageId),
-            event: eventName,
-            data: serializeFrame(eventName, payload)
-          });
-        });
-        unsubscribes.push(unsubscribe);
+    return null;
+  }
+}
+function createFrameHold(writer) {
+  let pending = null;
+  return {
+    send: (write) => {
+      if (!pending) {
+        write();
+      } else if (writer.reserve()) {
+        pending.push(write);
       }
-      sseLogger.info("SSE connection established", {
-        events: allowedEvents,
-        subscriptionCount: unsubscribes.length
-      });
-      pingTimer = setInterval(() => {
-        if (connectionDead) return;
-        writer.enqueue({
-          event: "ping",
-          data: JSON.stringify({ timestamp: Date.now() })
-        });
-      }, pingInterval);
-      const abortSignal = c.req.raw.signal;
-      if (!abortSignal.aborted && !connectionDead) {
-        await new Promise((resolve2) => {
-          const onAbort = () => resolve2();
-          abortSignal.addEventListener("abort", onAbort, { once: true });
-          onClosed = () => {
-            abortSignal.removeEventListener("abort", onAbort);
-            resolve2();
-          };
-        });
+    },
+    hold: () => {
+      pending = [];
+    },
+    release: () => {
+      const held = pending ?? [];
+      pending = null;
+      writer.clearReserved();
+      held.forEach((write) => write());
+    }
+  };
+}
+function createFrameWriter(writer) {
+  let messageId = 0;
+  return (eventName, data) => {
+    messageId++;
+    sseLogger.debug("SSE sending event", {
+      event: eventName,
+      messageId
+    });
+    writer.enqueue({ id: String(messageId), event: eventName, data });
+  };
+}
+async function waitForDisconnect(abortSignal, isDead, onServerClose) {
+  if (abortSignal.aborted || isDead()) {
+    return;
+  }
+  await new Promise((resolve2) => {
+    const onAbort = () => resolve2();
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    onServerClose(() => {
+      abortSignal.removeEventListener("abort", onAbort);
+      resolve2();
+    });
+  });
+}
+function createEventSubscriber(ctx) {
+  return (eventName) => {
+    const eventDef = ctx.router.events[eventName];
+    let active = true;
+    const unsubscribe = eventDef.subscribe((payload) => {
+      if (!active || ctx.isDead() || !passesFrameFilters(eventName, eventDef, payload, ctx)) {
+        return;
       }
-      cleanup();
-    }, async (err) => {
-      sseLogger.error("SSE stream error", {
-        error: err.message
-      });
+      const data = serializeFrame(eventName, payload);
+      ctx.send(() => ctx.writeFrame(eventName, data));
     });
+    return () => {
+      active = false;
+      unsubscribe();
+    };
   };
 }
+function passesFrameFilters(eventName, eventDef, payload, ctx) {
+  const globalFilter = ctx.authConfig?.filter?.[eventName];
+  if (ctx.subject && globalFilter && !globalFilter(ctx.subject, payload)) {
+    return false;
+  }
+  if (!eventDef._filter) {
+    return true;
+  }
+  try {
+    return eventDef._filter(payload, { subject: ctx.subject, request: ctx.request }) === true;
+  } catch {
+    sseLogger.warn("SSE event filter threw \u2014 frame dropped", { event: eventName, subject: ctx.subject });
+    return false;
+  }
+}
 async function authenticateToken(c, tokenManager) {
   if (!tokenManager) {
     return void 0;
@@ -608,7 +970,7 @@ function parseRequestedEvents(c) {
   if (!eventsParam) {
     return null;
   }
-  return eventsParam.split(",").map((e) => e.trim());
+  return [...new Set(eventsParam.split(",").map((e) => e.trim()))];
 }
 async function authorizeEvents(subject, requestedEvents, authConfig) {
   if (!subject || !authConfig?.authorize) {
@@ -620,6 +982,12 @@ async function authorizeEvents(subject, requestedEvents, authConfig) {
   }
   return allowed;
 }
+
+// src/event/sse/paths.ts
+var DEFAULT_SSE_STREAM_PATH = "/events/stream";
+function sseTokenPath(streamPath) {
+  return streamPath.replace(/\/[^/]+$/, "/token");
+}
 function hashToken(token) {
   return createHash("sha256").update(token).digest("hex");
 }
@@ -1080,6 +1448,7 @@ async function runMigrationBootGate(config, cwd = process.cwd()) {
 // src/server/namespace.ts
 var CORE_NAMESPACE = "/_core";
 var CORE_HEALTH_PATH = `${CORE_NAMESPACE}/health`;
+var CORE_TIME_PATH = `${CORE_NAMESPACE}/time`;
 var LEGACY_HEALTH_PATH = "/health";
 
 // src/server/shutdown-manager.ts
@@ -1480,6 +1849,448 @@ function buildStartupConfig(config, timeouts) {
   };
 }
 
+// src/route/route-builder.ts
+var RouteBuilder = class _RouteBuilder {
+  _method;
+  _path;
+  _input;
+  _interceptor;
+  _middlewares;
+  _skipMiddlewares;
+  _contract;
+  _effect;
+  _summary;
+  /**
+   * Create a new RouteBuilder with copied properties and optional overrides
+   */
+  clone(overrides) {
+    const builder = new _RouteBuilder();
+    builder._method = this._method;
+    builder._path = this._path;
+    builder._input = overrides?.input ?? this._input;
+    builder._interceptor = overrides?.interceptor ?? this._interceptor;
+    builder._middlewares = overrides?.middlewares ?? this._middlewares;
+    builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
+    builder._contract = overrides?.contract ?? this._contract;
+    builder._effect = overrides?.effect ?? this._effect;
+    builder._summary = overrides?.summary ?? this._summary;
+    return builder;
+  }
+  /**
+   * Define input schemas
+   *
+   * @example
+   * ```ts
+   * route.get('/users/:id')
+   *   .input({
+   *     params: Type.Object({ id: Type.String() }),
+   *     query: Type.Object({ page: Type.Number() }),
+   *     headers: Type.Object({ authorization: Type.String() })
+   *   })
+   *   .handler(async (c) => {
+   *     const { params, query, headers } = await c.data();
+   *     // params = { id: string }
+   *     // query = { page: number }
+   *     // headers = { authorization: string }
+   *   })
+   * ```
+   */
+  input(input) {
+    return this.clone({ input });
+  }
+  /**
+   * Define fields injected by interceptors
+   *
+   * These fields are:
+   * - Available in the handler (merged with input)
+   * - Excluded from client types (codegen uses only input)
+   * - Not validated by route input schema (injected by middleware)
+   *
+   * Use this when middleware/interceptors add fields to the request
+   * before it reaches the handler.
+   *
+   * @example
+   * ```ts
+   * // Auth interceptor injects crypto key fields
+   * route.post('/_auth/login')
+   *   .input({
+   *     body: Type.Object({
+   *       email: Type.String(),
+   *       password: Type.String()
+   *     })
+   *   })
+   *   .interceptor({
+   *     body: Type.Object({
+   *       publicKey: Type.String(),
+   *       keyId: Type.String(),
+   *       fingerprint: Type.String()
+   *     })
+   *   })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     // body type: { email, password, publicKey, keyId, fingerprint }
+   *     // Client only sees: { email, password }
+   *     return loginService(body);
+   *   });
+   * ```
+   */
+  interceptor(interceptor) {
+    return this.clone({ interceptor });
+  }
+  /**
+   * Add middlewares to the route
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  middleware(middlewares) {
+    return this.clone({ middlewares });
+  }
+  /**
+   * Add middlewares to the route (alias for `.middleware()`)
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  use(middlewares) {
+    return this.middleware(middlewares);
+  }
+  /**
+   * Skip server-level named middlewares
+   *
+   * Useful for public endpoints that should bypass auth or rate limiting
+   *
+   * @param middlewareNames - Array of middleware names to skip, or '*' to skip all
+   *
+   * @example
+   * ```ts
+   * // Skip specific middlewares
+   * route.get('/status')
+   *   .skip(['auth', 'rateLimit'])
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   *
+   * // Skip only auth (still apply rate limiting)
+   * route.get('/public-data')
+   *   .skip(['auth'])
+   *   .handler(async (c) => { ... });
+   *
+   * // Skip all middlewares
+   * route.get('/public-health')
+   *   .skip('*')
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   * ```
+   */
+  skip(middlewareNames) {
+    return this.clone({ skipMiddlewares: middlewareNames });
+  }
+  /**
+   * Publish this route as a versioned contract operation
+   *
+   * Marks the route as a promise to clients that are compiled and deployed
+   * separately from the server — a mobile app, an external API consumer.
+   * The `@spfn/core:contract` generator writes every contracted route into
+   * `contracts/current.json`, and the build refuses a change that would break
+   * an already-released client.
+   *
+   * Routes without `.contract()` are unaffected: they simply do not appear in
+   * the contract. A web client needs nothing here — it derives its types from
+   * the router in the same build.
+   *
+   * @example
+   * ```ts
+   * export const getUser = route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .contract({
+   *     since: '1.2.0',
+   *     auth: 'clientProofV1',
+   *     requiresSession: true,
+   *     response: Type.Object({
+   *       id: Type.String(),
+   *       name: Type.String(),
+   *       email: Type.Optional(Type.String()),
+   *     }),
+   *   })
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  contract(contract) {
+    return this.clone({ contract });
+  }
+  /**
+   * Declare what invoking this route does
+   *
+   * Read by a command surface (`@spfn/core/surface`, `@spfn/core/ops`),
+   * which announces it in its manifest so a machine caller can tell a read
+   * from a write before it calls — `spfn ops call` asks for `--yes` before a
+   * `destructive` command. A surface built with `defineSurface` refuses an
+   * app command that does not declare one; on `/_ops` it is optional.
+   *
+   * Nothing else reads it: codegen, the route map, and the contract are
+   * unaffected, and a route outside any surface simply carries it.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .input({ body: PageAddBody })
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  effect(effect) {
+    return this.clone({ effect });
+  }
+  /**
+   * Describe this route in one line for a command surface's manifest
+   *
+   * A surface announces it beside the command in `spfn ops list` and
+   * `--describe`, and refuses one that is empty or longer than 500
+   * characters. Codegen, the route map, and the contract ignore it. On a
+   * module command the module's own summary wins.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  summary(summary) {
+    return this.clone({ summary });
+  }
+  /**
+   * Define handler function
+   *
+   * Response type is automatically inferred from the return value.
+   * Use helper methods like `c.created()`, `c.paginated()` for proper type inference.
+   *
+   * @example
+   * ```ts
+   * // Direct return - type inferred from data
+   * route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { params } = await c.data();
+   *     return await getUser(params.id); // Type: User
+   *   })
+   *
+   * // Using c.created() - returns data with 201 status, type preserved
+   * route.post('/users')
+   *   .input({ body: Type.Object({ name: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     return c.created(await createUser(body)); // Type: User
+   *   })
+   *
+   * // Using c.paginated() - returns PaginatedResult<T>
+   * route.get('/users')
+   *   .handler(async (c) => {
+   *     const users = await getUsers();
+   *     return c.paginated(users, 1, 20, 100); // Type: PaginatedResult<User>
+   *   })
+   *
+   * // Using c.noContent() - returns void
+   * route.delete('/users/:id')
+   *   .handler(async (c) => {
+   *     await deleteUser(params.id);
+   *     return c.noContent(); // Type: void
+   *   })
+   *
+   * // Using c.json() - returns Response (type inference lost)
+   * // Use only when you need custom status codes not covered by helpers
+   * route.get('/custom')
+   *   .handler(async (c) => {
+   *     return c.json({ data }, 418); // Type: Response
+   *   })
+   * ```
+   */
+  handler(fn) {
+    return {
+      method: this._method,
+      path: this._path,
+      input: this._input,
+      interceptor: this._interceptor,
+      middlewares: this._middlewares,
+      skipMiddlewares: this._skipMiddlewares,
+      contract: this._contract,
+      ...this._effect !== void 0 ? { effect: this._effect } : {},
+      ...this._summary !== void 0 ? { summary: this._summary } : {},
+      handler: fn,
+      _input: {},
+      _interceptor: {},
+      _response: {}
+    };
+  }
+};
+function createMethodRoute(method) {
+  return (path) => {
+    const builder = new RouteBuilder();
+    builder._method = method;
+    builder._path = path;
+    return builder;
+  };
+}
+var route = {
+  get: createMethodRoute("GET"),
+  post: createMethodRoute("POST"),
+  put: createMethodRoute("PUT"),
+  patch: createMethodRoute("PATCH"),
+  delete: createMethodRoute("DELETE")
+};
+
+// src/route/router.ts
+function createRouterInstance(state2) {
+  const router = {
+    routes: state2.routes,
+    _routes: state2.routes,
+    _packageRouters: state2.packageRouters,
+    _globalMiddlewares: state2.globalMiddlewares,
+    _contractVersion: state2.contractVersion,
+    _publishesRouteMap: state2.publishesRouteMap,
+    packages(routers) {
+      const newPackageRouters = [...state2.packageRouters, ...routers];
+      for (const pkgRouter of routers) {
+        if (pkgRouter._packageRouters?.length > 0) {
+          newPackageRouters.push(...pkgRouter._packageRouters);
+        }
+      }
+      assertDistinctSurfaces(newPackageRouters);
+      return carryMarkers(router, createRouterInstance({ ...state2, packageRouters: newPackageRouters }));
+    },
+    use(middlewares) {
+      return carryMarkers(router, createRouterInstance({
+        ...state2,
+        globalMiddlewares: [...state2.globalMiddlewares, ...middlewares]
+      }));
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return carryMarkers(router, createRouterInstance({ ...state2, contractVersion: version }));
+    }
+  };
+  return router;
+}
+var MARKERS = ["_surfaceNamespace", "_stateManifest"];
+function carryMarkers(from, to) {
+  for (const marker of MARKERS) {
+    if (from[marker] !== void 0) {
+      Object.defineProperty(to, marker, { value: from[marker], enumerable: false });
+    }
+  }
+  return to;
+}
+function assertContractVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(version)) {
+    throw new Error(
+      `contractVersion("${version}") is not a version of the form major.minor.patch. The released snapshot is named from this value and releases are compared by it.`
+    );
+  }
+}
+function assertDistinctSurfaces(packageRouters) {
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const router of packageRouters) {
+    const namespace = router._surfaceNamespace;
+    if (namespace === void 0) {
+      continue;
+    }
+    if (namespaces.has(namespace)) {
+      throw new Error(
+        `.packages() mounts two command surfaces on "${namespace}". Both serve ${namespace}/_manifest, so the second one's commands would answer while no manifest lists them. Mount one router per namespace.`
+      );
+    }
+    namespaces.add(namespace);
+  }
+}
+function defineRouter(routes) {
+  return createRouterInstance({
+    routes,
+    packageRouters: [],
+    globalMiddlewares: [],
+    contractVersion: null,
+    publishesRouteMap: true
+  });
+}
+
+// src/route/validation.ts
+FormatRegistry.Set(
+  "email",
+  (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+);
+FormatRegistry.Set(
+  "uri",
+  (value) => /^https?:\/\/.+/.test(value)
+);
+FormatRegistry.Set(
+  "uuid",
+  (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+);
+FormatRegistry.Set(
+  "date",
+  (value) => /^\d{4}-\d{2}-\d{2}$/.test(value)
+);
+FormatRegistry.Set(
+  "date-time",
+  (value) => !isNaN(Date.parse(value))
+);
+
+// src/server/server-time.ts
+var CORE_TIME_OPERATION_ID = "core.time";
+var ServerTimeResponseSchema = Type.Object({
+  serverTimeMillis: Type.Integer()
+}, { additionalProperties: false });
+var systemServerClock = {
+  now: () => Date.now()
+};
+function createCoreTimeRoute(clock = systemServerClock) {
+  return route.get(CORE_TIME_PATH).skip("*").contract({
+    since: "0.3.0",
+    auth: "none",
+    requiresSession: false,
+    response: ServerTimeResponseSchema
+  }).handler(async (c) => {
+    const response = {
+      serverTimeMillis: clock.now()
+    };
+    c.raw.header("Cache-Control", "no-store");
+    return response;
+  });
+}
+var CORE_TIME_ROUTE = createCoreTimeRoute();
+function createCoreTimeRouter(clock) {
+  return defineRouter({
+    [CORE_TIME_OPERATION_ID]: createCoreTimeRoute(clock)
+  });
+}
+
 // src/server/create-server.ts
 var rateLimitApplied = /* @__PURE__ */ new WeakSet();
 async function createServer(config) {
@@ -1522,6 +2333,7 @@ async function createAutoConfiguredApp(config) {
   applyDefaultMiddleware(app, config, enableLogger, enableCors);
   await applyProxyGuard(app, config);
   applyRateLimit(config);
+  registerCoreTimeEndpoint(app, config);
   if (Array.isArray(config?.use)) {
     config.use.forEach((mw) => app.use("*", mw));
   }
@@ -1571,7 +2383,7 @@ async function applyProxyGuard(app, config) {
       serverLogger.warn("Proxy-guard nonce: cache module unavailable \u2014 using in-memory store (single instance only)");
     }
   }
-  const autoSkip = [CORE_HEALTH_PATH, LEGACY_HEALTH_PATH];
+  const autoSkip = [CORE_HEALTH_PATH, CORE_TIME_PATH, LEGACY_HEALTH_PATH];
   if (config?.healthCheck?.path) {
     autoSkip.push(config.healthCheck.path);
   }
@@ -1628,6 +2440,10 @@ function resolveHealthCheck(config) {
     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) {
@@ -1729,8 +2545,9 @@ async function registerSSEEndpoint(app, config) {
     return;
   }
   const eventsConfig = config.eventsConfig ?? {};
-  const streamPath = eventsConfig.path ?? "/events/stream";
+  const streamPath = eventsConfig.path ?? DEFAULT_SSE_STREAM_PATH;
   const authConfig = eventsConfig.auth;
+  assertEventContractServed(config.events._contract, streamPath, !!authConfig?.enabled);
   const debug = isDebugMode(config);
   let tokenManager;
   if (authConfig?.enabled) {
@@ -1753,7 +2570,7 @@ async function registerSSEEndpoint(app, config) {
       ttl: authConfig.tokenTtl,
       store
     });
-    const tokenPath = streamPath.replace(/\/[^/]+$/, "/token");
+    const tokenPath = sseTokenPath(streamPath);
     const mwHandlers = resolveEndpointMiddlewares(config).map((mw) => mw.handler);
     const getSubject = authConfig.getSubject ?? ((c) => c.get("auth")?.userId ?? null);
     app.on(["POST"], [tokenPath], ...mwHandlers, async (c) => {
@@ -1782,6 +2599,23 @@ async function registerSSEEndpoint(app, config) {
     });
   }
 }
+function assertEventContractServed(contract, streamPath, authEnabled) {
+  if (!contract) {
+    return;
+  }
+  const contractPath = contract.streamPath ?? DEFAULT_SSE_STREAM_PATH;
+  if (contractPath !== streamPath) {
+    throw new Error(
+      `SSE event router contract declares streamPath ${contractPath} but .events() registers ${streamPath}; the contract would describe a path the server does not serve`
+    );
+  }
+  const servedAuth = authEnabled ? "tokenExchange" : "none";
+  if (contract.auth !== servedAuth) {
+    throw new Error(
+      `SSE event router contract declares auth ${contract.auth} but .events() serves auth ${servedAuth}; the contract would describe an auth mode the server does not serve`
+    );
+  }
+}
 function isDebugMode(config) {
   return config?.debug ?? process.env.NODE_ENV === "development";
 }
@@ -1873,6 +2707,31 @@ function shouldSweepOrphanSchedules() {
   return getBossConfig()?.sweepOrphanSchedules ?? false;
 }
 
+// src/job/queue-policy.ts
+function resolveQueuePolicy(job2) {
+  if (job2.options?.policy) {
+    return job2.options.policy;
+  }
+  if (job2.runOnce || job2.options?.singletonKey) {
+    return "exclusive";
+  }
+  return "standard";
+}
+
+// src/job/retry-options.ts
+function toPgBossRetryOptions(options) {
+  return {
+    retryLimit: options?.retryLimit ?? 3,
+    retryDelay: Math.ceil((options?.retryDelay ?? 1e3) / 1e3),
+    // Exponential backoff by default — a failed cohort (e.g. a provider 429)
+    // would otherwise all retry at the same fixed offset (thundering herd).
+    retryBackoff: options?.retryBackoff ?? true
+  };
+}
+
+// src/job/job-builder.ts
+logger.child("@spfn/core:job");
+
 // src/job/job-router.ts
 function isJobDef(value) {
   return value !== null && typeof value === "object" && "name" in value && "handler" in value && "send" in value && "run" in value;
@@ -1880,29 +2739,44 @@ function isJobDef(value) {
 function isJobRouter(value) {
   return value !== null && typeof value === "object" && "jobs" in value && "_jobs" in value;
 }
-function collectJobs(router, prefix = "") {
-  const jobs = [];
+function defineJobRouter(jobs) {
+  return {
+    jobs,
+    _jobs: jobs
+  };
+}
+function mergeJobRouters(base, extra) {
+  for (const key of Object.keys(extra.jobs)) {
+    if (key in base.jobs) {
+      throw new Error(
+        `jobs(): key "${key}" is already registered by an earlier .jobs() call; rename it or nest it under a domain router`
+      );
+    }
+  }
+  return defineJobRouter({ ...base.jobs, ...extra.jobs });
+}
+function collectJobEntries(router, prefix = "") {
+  const entries = [];
   for (const [key, value] of Object.entries(router.jobs)) {
-    const name = prefix ? `${prefix}.${key}` : key;
+    const path = prefix ? `${prefix}.${key}` : key;
     if (isJobRouter(value)) {
-      jobs.push(...collectJobs(value, name));
+      entries.push(...collectJobEntries(value, path));
     } else if (isJobDef(value)) {
-      jobs.push(value);
+      entries.push({ key: path, job: value });
     }
   }
-  return jobs;
+  return entries;
+}
+function collectJobs(router, prefix = "") {
+  return collectJobEntries(router, prefix).map((entry) => entry.job);
 }
-var jobLogger2 = logger.child("@spfn/core:job");
+var jobLogger3 = logger.child("@spfn/core:job");
 function getEventQueueName(eventName) {
   return `event:${eventName}`;
 }
 function getDefaultJobOptions(options) {
   return {
-    retryLimit: options?.retryLimit ?? 3,
-    retryDelay: options?.retryDelay ?? 1e3,
-    // Exponential backoff by default — a failed cohort (e.g. a provider 429)
-    // would otherwise all retry at the same fixed offset (thundering herd).
-    retryBackoff: options?.retryBackoff ?? true,
+    ...toPgBossRetryOptions(options),
     expireInSeconds: options?.expireInSeconds ?? 300
   };
 }
@@ -1913,11 +2787,12 @@ async function registerJobs(router) {
       "pg-boss not initialized. Call initBoss() before registerJobs()"
     );
   }
+  assertUniqueJobNames(router);
   const jobs = collectJobs(router);
   const clearOnStart = shouldClearOnStart();
-  jobLogger2.info(`Registering ${jobs.length} job(s)...`);
+  jobLogger3.info(`Registering ${jobs.length} job(s)...`);
   if (clearOnStart) {
-    jobLogger2.info("Clearing existing jobs before registration...");
+    jobLogger3.info("Clearing existing jobs before registration...");
     for (const job2 of jobs) {
       await boss.deleteAllJobs(job2.name);
       if (job2.subscribedEvent) {
@@ -1925,7 +2800,7 @@ async function registerJobs(router) {
         await boss.deleteAllJobs(eventQueue);
       }
     }
-    jobLogger2.info("Existing jobs cleared");
+    jobLogger3.info("Existing jobs cleared");
   }
   await Promise.all(jobs.map((job2) => registerJob(job2)));
   for (const job2 of jobs) {
@@ -1936,42 +2811,77 @@ async function registerJobs(router) {
   if (shouldSweepOrphanSchedules()) {
     await sweepOrphanSchedules(boss);
   }
-  jobLogger2.info("All jobs registered successfully");
+  jobLogger3.info("All jobs registered successfully");
+}
+function assertUniqueJobNames(router) {
+  const keysByName = /* @__PURE__ */ new Map();
+  for (const { key, job: job2 } of collectJobEntries(router)) {
+    const existingKey = keysByName.get(job2.name);
+    if (existingKey) {
+      throw new Error(
+        `registerJobs(): job name "${job2.name}" is defined twice (keys "${existingKey}" and "${key}"); job names are pg-boss queue names and must be unique`
+      );
+    }
+    keysByName.set(job2.name, key);
+  }
 }
 var registeredCronNames = /* @__PURE__ */ new Set();
 async function sweepOrphanSchedules(boss) {
   if (registeredCronNames.size === 0) {
-    jobLogger2.debug("No cron jobs declared; skipping orphan schedule sweep");
+    jobLogger3.debug("No cron jobs declared; skipping orphan schedule sweep");
     return;
   }
   try {
     const schedules = await boss.getSchedules();
     const orphans = schedules.filter((schedule) => !registeredCronNames.has(schedule.name));
     if (orphans.length === 0) {
-      jobLogger2.debug("No orphan schedules found");
+      jobLogger3.debug("No orphan schedules found");
       return;
     }
     await Promise.all(orphans.map(async (orphan) => {
       try {
         await boss.unschedule(orphan.name, orphan.key);
-        jobLogger2.info(`Removed orphan schedule: ${orphan.name}`);
+        jobLogger3.info(`Removed orphan schedule: ${orphan.name}`);
       } catch (error) {
-        jobLogger2.error(`Failed to remove orphan schedule: ${orphan.name}`, {
+        jobLogger3.error(`Failed to remove orphan schedule: ${orphan.name}`, {
           error: error instanceof Error ? error.message : String(error)
         });
       }
     }));
   } catch (error) {
-    jobLogger2.error("Orphan schedule sweep failed", {
+    jobLogger3.error("Orphan schedule sweep failed", {
       error: error instanceof Error ? error.message : String(error)
     });
   }
 }
-async function ensureQueue(boss, queueName) {
-  await boss.createQueue(queueName);
+async function ensureQueue(boss, queueName, policy) {
+  await boss.createQueue(queueName, { policy });
+  const existing = await boss.getQueue(queueName);
+  if (!existing || existing.policy === policy) {
+    return;
+  }
+  if (shouldClearOnStart()) {
+    await boss.deleteQueue(queueName);
+    await boss.createQueue(queueName, { policy });
+    jobLogger3.info(`[Queue:${queueName}] policy ${existing.policy} \u2192 ${policy} (recreated: clearOnStart)`);
+    return;
+  }
+  jobLogger3.error(
+    `[Queue:${queueName}] policy mismatch: the queue exists as "${existing.policy}" but its jobs require "${policy}". Delete the queue in a quiet window (getBoss().deleteQueue('${queueName}') drops its job rows) or set clearOnStart in development; until then singletonKey/runOnce on this queue do not deduplicate`
+  );
+}
+function createQueueEnsurer(boss, policy) {
+  const ensured = /* @__PURE__ */ new Set();
+  return async (queueName) => {
+    if (ensured.has(queueName)) {
+      return;
+    }
+    ensured.add(queueName);
+    await ensureQueue(boss, queueName, policy);
+  };
 }
 async function executeJobHandler(job2, pgBossJob) {
-  jobLogger2.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
+  jobLogger3.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
   const startTime = Date.now();
   try {
     if (job2.inputSchema) {
@@ -1980,13 +2890,13 @@ async function executeJobHandler(job2, pgBossJob) {
       await job2.handler();
     }
     const duration = Date.now() - startTime;
-    jobLogger2.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
+    jobLogger3.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
       jobId: pgBossJob.id,
       duration
     });
   } catch (error) {
     const duration = Date.now() - startTime;
-    jobLogger2.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
+    jobLogger3.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
       jobId: pgBossJob.id,
       duration,
       error: error instanceof Error ? error.message : String(error)
@@ -1994,8 +2904,8 @@ async function executeJobHandler(job2, pgBossJob) {
     throw error;
   }
 }
-async function registerWorker(boss, job2, queueName) {
-  await ensureQueue(boss, queueName);
+async function registerWorker(boss, job2, queueName, ensureQueueOnce) {
+  await ensureQueueOnce(queueName);
   const batchSize = job2.options?.batchSize ?? 1;
   const pollingIntervalSeconds = job2.options?.pollingIntervalSeconds ?? env.JOB_POLLING_INTERVAL_SECONDS;
   await boss.work(
@@ -2029,28 +2939,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,
     {},
@@ -2059,7 +2969,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();
@@ -2067,15 +2977,16 @@ async function registerJob(job2) {
     throw new Error("pg-boss not initialized");
   }
   const queueName = job2.subscribedEvent ? getEventQueueName(job2.subscribedEvent) : job2.name;
-  jobLogger2.debug(`Registering job: ${job2.name}`, {
+  jobLogger3.debug(`Registering job: ${job2.name}`, {
     queueName,
     subscribedEvent: job2.subscribedEvent
   });
-  await registerWorker(boss, job2, queueName);
+  const ensureQueueOnce = createQueueEnsurer(boss, resolveQueuePolicy(job2));
+  await registerWorker(boss, job2, queueName, ensureQueueOnce);
   connectEventToQueue(boss, job2, queueName);
-  await registerCronSchedule(boss, job2);
-  await queueRunOnceJob(boss, job2);
-  jobLogger2.debug(`Job registered: ${job2.name}`);
+  await registerCronSchedule(boss, job2, ensureQueueOnce);
+  await queueRunOnceJob(boss, job2, ensureQueueOnce);
+  jobLogger3.debug(`Job registered: ${job2.name}`);
 }
 var wsLogger = logger.child("@spfn/core:ws");
 function isOriginAllowed(origin, allowList) {
@@ -2406,6 +3317,50 @@ function readPort(value) {
   const port = Number(value);
   return Number.isInteger(port) && port > 0 && port < 65536 ? port : void 0;
 }
+logger.child("@spfn/core:env-registry");
+function validateAllEnv(registries) {
+  const errors = [];
+  const warnings = [];
+  for (const registry of registries) {
+    const result = registry.validateAll();
+    errors.push(...result.errors);
+    warnings.push(...result.warnings);
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+// src/server/env-boot-check.ts
+function runEnvBootCheck(config) {
+  const result = validateAllEnv([registry, ...config.env?.registries ?? []]);
+  const errors = uniqueByMessage(result.errors);
+  const warnings = uniqueByMessage(result.warnings);
+  for (const warning of warnings) {
+    serverLogger.warn(`Environment: ${warning.message}`);
+  }
+  if (errors.length > 0) {
+    serverLogger.error(
+      `Environment validation failed (${errors.length}):
+` + errors.map((error) => `  - ${error.message}`).join("\n")
+    );
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+function uniqueByMessage(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  return entries.filter((entry) => {
+    const id = `${entry.key}
+${entry.message}`;
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
+}
 
 // src/server/validation.ts
 function validateServerConfig(config) {
@@ -2464,6 +3419,10 @@ var processHandlersRegistered = false;
 async function startServer(config) {
   loadEnv();
   const finalConfig = await loadAndMergeConfig(config);
+  if (!runEnvBootCheck(finalConfig).valid) {
+    serverLogger.error("Refusing to start: fix the environment variables listed above.");
+    process.exit(1);
+  }
   const { host, port, debug } = finalConfig;
   validateServerConfig(finalConfig);
   if (!host || !port) {
@@ -2954,6 +3913,9 @@ function createServerlessApp(config) {
 }
 async function buildServerlessApp(rawConfig) {
   loadEnv();
+  if (!runEnvBootCheck(rawConfig ?? {}).valid) {
+    throw new Error("Environment validation failed \u2014 the missing or invalid keys are logged above.");
+  }
   const config = withServerlessDefaults(rawConfig);
   warnIfJobsConfigured(config);
   await initInfrastructure(config);
@@ -3104,6 +4066,20 @@ var ServerConfigBuilder = class {
   /**
    * Register background jobs router
    *
+   * May be called once per domain router: repeated calls **merge** into one
+   * router, the way `.routes()` composes. Calling it several times used to
+   * keep only the last router and register nothing else, without warning.
+   *
+   * The pg-boss `config` is per server, so pass it on one call only.
+   *
+   * Two names can collide, and both fail loudly:
+   * - a router **key** present in two calls throws here, at config time;
+   * - two jobs sharing a **`job.name`** (the pg-boss queue name) throw in
+   *   `registerJobs()` at boot, before any queue or worker is created.
+   *
+   * @throws if a router key was already registered by an earlier call
+   * @throws if `config` is given when an earlier call already gave one
+   *
    * @example
    * ```typescript
    * import { job, defineJobRouter } from '@spfn/core/job';
@@ -3116,12 +4092,18 @@ var ServerConfigBuilder = class {
    *
    * export default defineServerConfig()
    *   .routes(appRouter)
-   *   .jobs(jobRouter)
+   *   .jobs(jobRouter, { clearOnStart: isDev })   // config on one call only
+   *   .jobs(billingJobRouter)                     // merged, not replaced
    *   .build();
    * ```
    */
   jobs(router, config) {
-    this.config.jobs = router;
+    if (config && this.config.jobsConfig) {
+      throw new Error(
+        "jobs(): pg-boss config was already given by an earlier .jobs() call; pass it once"
+      );
+    }
+    this.config.jobs = this.config.jobs ? mergeJobRouters(this.config.jobs, router) : router;
     if (config) {
       this.config.jobsConfig = config;
     }
@@ -3231,6 +4213,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
    */
@@ -3253,6 +4244,25 @@ var ServerConfigBuilder = class {
     this.config.migrations = migrations;
     return this;
   }
+  /**
+   * Hand the app's env registries to the boot check
+   *
+   * `@spfn/core`'s own registry is always checked; the registries given here
+   * are checked with it, before the server listens.
+   *
+   * @example
+   * ```typescript
+   * import { envRegistry } from '@/server/config/env.config';
+   *
+   * export default defineServerConfig()
+   *     .env({ registries: [envRegistry] })
+   *     .build();
+   * ```
+   */
+  env(env6) {
+    this.config.env = env6;
+    return this;
+  }
   /**
    * Register workflow router for workflow orchestration
    *
@@ -3327,6 +4337,6 @@ function defineServerConfig() {
   return new ServerConfigBuilder();
 }
 
-export { CORE_HEALTH_PATH, CORE_NAMESPACE, PendingMigrationsError, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
+export { CORE_HEALTH_PATH, CORE_NAMESPACE, CORE_TIME_OPERATION_ID, CORE_TIME_PATH, CORE_TIME_ROUTE, PendingMigrationsError, ServerTimeResponseSchema, createCoreTimeRoute, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map