@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/api/readiness.js

@@ -0,0 +1,98 @@
+// Readiness probe: runs a set of checks in parallel with a per-check timeout
+// and aggregates into a single result. Used by /health/ready when the caller
+// wires DB / Redis / Dispatcher — any of those down drops the probe to 503
+// so load balancers stop routing new traffic even while `lifecycle.state()`
+// is still "ready".
+//
+// Design:
+//   - Every check produces a `ReadinessCheckResult` — no thrown errors leak.
+//   - Timeout is enforced per-check, not per-probe, so a single hung dependency
+//     can't starve siblings of their budget.
+//   - Checks run in parallel — the probe is called on every kubelet/ALB poll,
+//     so total latency must stay ≈ slowest check, not sum.
+import { pingDatabase } from "../db/queries/raw-sql.js";
+import { getAllConsumerProgress } from "../pipeline/event-dispatcher.js";
+const DEFAULT_TIMEOUT_MS = 2_000;
+export function createReadinessProbe(checks, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return async () => {
+        const results = await Promise.all(checks.map((check) => runOne(check, timeoutMs)));
+        return {
+            ok: results.every((r) => r.ok),
+            checks: results,
+        };
+    };
+}
+async function runOne(check, timeoutMs) {
+    const start = performance.now();
+    let timer;
+    try {
+        await Promise.race([
+            check.run(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+                // Don't keep the event loop alive on a hung probe during shutdown.
+                timer.unref?.();
+            }),
+        ]);
+        return {
+            name: check.name,
+            ok: true,
+            latencyMs: Math.round(performance.now() - start),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name: check.name,
+            ok: false,
+            latencyMs: Math.round(performance.now() - start),
+            error: message,
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+// --- Standard checks --------------------------------------------------------
+export function dbPingCheck(db) {
+    return {
+        name: "db",
+        run: async () => {
+            await pingDatabase(db);
+        },
+    };
+}
+export function redisPingCheck(redis) {
+    return {
+        name: "redis",
+        run: async () => {
+            const reply = await redis.ping();
+            if (reply !== "PONG")
+                throw new Error(`unexpected PING reply: ${reply}`);
+        },
+    };
+}
+// Lag-Check für den Async-Event-Dispatcher. Liest HWM + Consumer-Cursor aus
+// der DB — kein extra Redis/Runtime-State. Fail-Schwelle ist in EventIds
+// (bigint), weil das die natürliche Einheit ist (events sind monoton id'd).
+// Ein Tuning-Beispiel: maxLagEvents = 1_000 bedeutet "wenn die Projection
+// mehr als 1k Events hinter HWM ist, stoppe neue Traffic-Zuweisung".
+export function dispatcherLagCheck(db, consumerNames, maxLagEvents) {
+    return {
+        name: "dispatcher_lag",
+        run: async () => {
+            // skip: no registered consumers means no dispatcher active — lag check has
+            // nothing to measure. Not a failure mode, just a no-op.
+            if (consumerNames.length === 0)
+                return;
+            const progress = await getAllConsumerProgress(db, consumerNames);
+            for (const p of progress) {
+                if (p.lag > maxLagEvents) {
+                    throw new Error(`consumer "${p.name}" lag=${p.lag} exceeds threshold ${maxLagEvents}`);
+                }
+            }
+        },
+    };
+}

package/dist/api/redis-sse-broker.d.ts

@@ -0,0 +1,13 @@
+import { type SseBroker } from "./sse-broker.js";
+export type RedisSseBrokerOptions = {
+    readonly redisUrl: string;
+};
+export type RedisSseBroker = SseBroker & {
+    close(): Promise<void>;
+};
+export declare function isRedisSseBroker(broker: SseBroker): broker is RedisSseBroker;
+export declare function createDefaultSseBroker(env?: Record<string, string | undefined>): {
+    readonly sseBroker: SseBroker;
+    readonly ownedRedisSseBroker: RedisSseBroker | undefined;
+};
+export declare function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroker;

package/dist/api/redis-sse-broker.js

@@ -0,0 +1,138 @@
+import { createRedisPubSubSignal } from "../redis/pubsub-signal.js";
+import { createSseBroker } from "./sse-broker.js";
+// Channel namespace for cross-replica fanout (fw#2625). Every pod publishes
+// here and every pod's psubscribe listens here, so a push on one instance
+// reaches SSE clients connected to any other instance without a shared
+// cursor — Pub/Sub for connected-client fanout, the event-store's shared
+// cursor stays the mechanism for "read every event exactly once".
+const CHANNEL_PREFIX = "kumiko:sse:ch:";
+const INVALIDATION_PREFIX = "kumiko:sse:inval:";
+const PSUBSCRIBE_PATTERN = "kumiko:sse:*";
+// The one property RedisSseBroker adds over SseBroker — cheap and reliable
+// to narrow on, so callers that only hold an SseBroker (e.g. a test that
+// pulled it back out of a generic ServerOptions.sseBroker slot) can tell
+// which lifecycle they own without an unsound `as` cast.
+export function isRedisSseBroker(broker) {
+    return "close" in broker;
+}
+// Single decision point for "which SseBroker should a caller default to
+// when it doesn't inject its own": REDIS_URL present → cross-replica
+// Redis-backed broker, absent → the in-memory one. Both buildServer and
+// runProdApp must funnel through this rather than each deciding on their
+// own — runProdApp doing exactly that (building an in-memory broker
+// unconditionally, then passing it in as ServerOptions.sseBroker) is why
+// fw#2625's fanout fix (fw#2630) shipped without ever taking effect in
+// production: an explicit ServerOptions.sseBroker always wins in
+// buildServer, so its own REDIS_URL-based default never ran.
+export function createDefaultSseBroker(env = process.env) {
+    const redisUrl = env["REDIS_URL"];
+    const ownedRedisSseBroker = redisUrl ? createRedisSseBroker({ redisUrl }) : undefined;
+    return { sseBroker: ownedRedisSseBroker ?? createSseBroker(), ownedRedisSseBroker };
+}
+function isSseEvent(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.type === "string" &&
+        typeof value.data === "object" &&
+        value.data !== null);
+}
+// Invalidation payload: `1` means userwide, `{ keptSessionId }` spares that
+// one session (all-except-session), `{ scope: "sessions", sessionIds }` /
+// `{ scope: "pat-tokens", tokenIds }` narrow to those credentials. A newer
+// scope payload NEVER carries a `keptSessionId` key, by construction —
+// that's what makes it safe for an older pod (which only ever reads
+// `keptSessionId`) to treat any of these as userwide instead of silently
+// sparing something it doesn't understand: fail-closed on a mixed rolling
+// deploy. Anything malformed also falls back to userwide.
+function parseInvalidationScope(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return { kind: "user" };
+    const record = payload;
+    if ("scope" in record) {
+        const { scope } = record;
+        if (scope === "sessions") {
+            const sessionIds = readNonEmptyStringArray(record["sessionIds"]);
+            if (sessionIds)
+                return { kind: "sessions", sessionIds };
+        }
+        if (scope === "pat-tokens") {
+            const tokenIds = readNonEmptyStringArray(record["tokenIds"]);
+            if (tokenIds)
+                return { kind: "pat-tokens", tokenIds };
+        }
+        return { kind: "user" };
+    }
+    if ("keptSessionId" in record) {
+        const { keptSessionId } = record;
+        if (typeof keptSessionId === "string" && keptSessionId.length > 0) {
+            return { kind: "all-except-session", keptSessionId };
+        }
+        return { kind: "user" };
+    }
+    return { kind: "user" };
+}
+function readNonEmptyStringArray(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    return value.every((v) => typeof v === "string") ? value : undefined;
+}
+// Mirror of parseInvalidationScope's wire shapes. "sessions"/"pat-tokens"
+// deliberately never include a `keptSessionId` key — see the parser comment.
+function encodeInvalidationScope(scope) {
+    if (scope === undefined || scope.kind === "user")
+        return 1;
+    if (scope.kind === "all-except-session")
+        return { keptSessionId: scope.keptSessionId };
+    if (scope.kind === "sessions")
+        return { scope: "sessions", sessionIds: scope.sessionIds };
+    return { scope: "pat-tokens", tokenIds: scope.tokenIds };
+}
+// Transport layer around a local `createSseBroker()` — all client/listener
+// state lives in `inner`, this only moves events across the Redis wire via
+// the shared PubSubSignal. `pushToChannel`/`publishAccessInvalidation` never
+// call `inner` directly: they publish, and the signal's message handler
+// below calls `inner` for BOTH the publishing pod and every other pod, so
+// there's exactly one delivery path regardless of which instance receives
+// the request.
+export function createRedisSseBroker(opts) {
+    const inner = createSseBroker();
+    const signal = createRedisPubSubSignal({
+        redisUrl: opts.redisUrl,
+        channelPattern: PSUBSCRIBE_PATTERN,
+        label: "sse-broker",
+    });
+    signal.onMessage((channel, payload) => {
+        if (channel.startsWith(CHANNEL_PREFIX)) {
+            if (!isSseEvent(payload)) {
+                console.error(`[kumiko:sse-broker] dropping malformed event on "${channel}"`);
+                // skip: malformed payload already logged above, nothing to deliver
+                return;
+            }
+            inner.pushToChannel(channel.slice(CHANNEL_PREFIX.length), payload);
+            // skip: channel already routed to the SSE-event branch above, the
+            // invalidation branch below is mutually exclusive with this one
+            return;
+        }
+        if (channel.startsWith(INVALIDATION_PREFIX)) {
+            inner.publishAccessInvalidation(channel.slice(INVALIDATION_PREFIX.length), parseInvalidationScope(payload));
+        }
+    });
+    return {
+        addClient: inner.addClient,
+        removeClient: inner.removeClient,
+        getClientCount: inner.getClientCount,
+        getTotalClientCount: inner.getTotalClientCount,
+        subscribeAccessInvalidation: inner.subscribeAccessInvalidation,
+        pushToChannel(channel, event) {
+            signal.publish(`${CHANNEL_PREFIX}${channel}`, event);
+        },
+        // fw#1601: this is the security-critical call — a revoked session's
+        // stream must close on every replica, not just the one that observed
+        // the revocation event. Publishing (rather than calling inner directly,
+        // like the in-memory broker does) is what makes that true here.
+        publishAccessInvalidation(userId, scope) {
+            signal.publish(`${INVALIDATION_PREFIX}${userId}`, encodeInvalidationScope(scope));
+        },
+        close: signal.close,
+    };
+}

package/dist/api/request-context.d.ts

@@ -0,0 +1,34 @@
+import { type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import type { AgentRisk } from "@cosmicdrift/kumiko-types/handlers";
+export type RequestContextData = {
+    readonly requestId: string;
+    readonly correlationId: string;
+    readonly causationId?: string;
+    readonly signal?: AbortSignal;
+    readonly ip?: string;
+    readonly userAgent?: string;
+    readonly locale?: string;
+    readonly feature?: string;
+    readonly handler?: string;
+    readonly startedAt?: number;
+    readonly writeOrigin?: WriteOrigin;
+    readonly entryHandler?: {
+        readonly qn: string;
+        readonly risk: AgentRisk;
+    };
+};
+export declare const requestContext: {
+    run<T>(data: RequestContextData, fn: () => T): T;
+    get(): RequestContextData | undefined;
+    generateId(): string;
+};
+export declare function runWithOrigin<T>(origin: {
+    readonly feature?: string;
+    readonly handler?: string;
+    readonly entryHandler?: {
+        readonly qn: string;
+        readonly risk: AgentRisk;
+    };
+}, fn: () => T): T;
+export declare function runAsDirectCallEntry<T>(fn: () => T): T;
+export declare function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T;

package/dist/api/request-context.js

@@ -0,0 +1,60 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isPersonalDataGated } from "@cosmicdrift/kumiko-types/event-store-types";
+import { generateId } from "../utils/index.js";
+const storage = new AsyncLocalStorage();
+export const requestContext = {
+    run(data, fn) {
+        return storage.run(data, fn);
+    },
+    get() {
+        return storage.getStore();
+    },
+    generateId() {
+        return generateId();
+    },
+};
+// Enter a scope that attributes every event written inside it. Keeps the
+// surrounding request's ids so correlation survives, and mints fresh ones
+// when there is no surrounding request (job-runner, event-dispatcher) —
+// requestId/correlationId are mandatory, `get()` may be undefined.
+export function runWithOrigin(origin, fn) {
+    const current = requestContext.get();
+    const requestId = current?.requestId ?? requestContext.generateId();
+    return requestContext.run({
+        ...current,
+        requestId,
+        correlationId: current?.correlationId ?? requestId,
+        feature: origin.feature,
+        handler: origin.handler,
+        // The outermost dispatch wins — a nested ctx.write/writeAs must not
+        // overwrite the entry handler that the irreversible-operation gate reads.
+        entryHandler: current?.entryHandler ?? origin.entryHandler,
+    }, fn);
+}
+// Clears entryHandler so the next dispatch inside fn becomes the new entry —
+// used by dispatchToolCall so the invoked tool handler, not the surrounding
+// turn/approve handler, is what the irreversible-operation gate sees.
+export function runAsDirectCallEntry(fn) {
+    const current = requestContext.get();
+    if (!current)
+        return fn();
+    const { entryHandler: _entryHandler, ...rest } = current;
+    return requestContext.run(rest, fn);
+}
+// An ungated origin never mints a scope: seeds and boot writes keep their missing context.
+export function runWithWriteOrigin(origin, fn) {
+    const current = requestContext.get();
+    if (!isPersonalDataGated(origin)) {
+        if (!current?.writeOrigin)
+            return fn();
+        const { writeOrigin: _writeOrigin, ...rest } = current;
+        return requestContext.run(rest, fn);
+    }
+    const requestId = current?.requestId ?? requestContext.generateId();
+    return requestContext.run({
+        ...current,
+        requestId,
+        correlationId: current?.correlationId ?? requestId,
+        writeOrigin: origin,
+    }, fn);
+}

package/dist/api/request-id-middleware.d.ts

@@ -0,0 +1,37 @@
+import type { Context, Next } from "hono";
+import { type ClientIpResolver } from "./client-ip.js";
+import { type RequestContextData } from "./request-context.js";
+/**
+ * Builds the RequestContextData record for a raw Fetch Request — requestId
+ * (client-supplied + sanitized, or generated), correlationId (mirrors
+ * requestId unless the client set its own), the underlying abort signal,
+ * and the client IP/User-Agent. Extracted out of `buildRequestContextData`
+ * so call-sites that only have a `Request` (no Hono `Context`) — e.g.
+ * server-runtime's static-fallback page-head resolver, which runs outside
+ * Hono's router entirely — can still populate the same AsyncLocalStorage
+ * record via `requestContext.run(...)`.
+ */
+export declare function buildRequestContextDataFromRequest(req: Request, options?: {
+    readonly resolver?: ClientIpResolver;
+    readonly socketAddress?: string;
+}): RequestContextData;
+/**
+ * Builds the RequestContextData record for a Hono request. Thin wrapper
+ * around `buildRequestContextDataFromRequest(c.req.raw)` — kept as its own
+ * export because most call-sites (server.ts's httpRoute→systemQuery mount,
+ * `requestIdMiddleware` below) already hold a Hono `Context`.
+ */
+export declare function buildRequestContextData(c: Context, resolver?: ClientIpResolver): RequestContextData;
+/**
+ * Assigns a requestId + correlationId to every request and wraps execution
+ * in AsyncLocalStorage. Runs BEFORE auth — both ids are available even for
+ * 401 responses.
+ *
+ * correlationId defaults to the requestId if the client didn't set
+ * `x-correlation-id` — clients that don't care about cross-service tracing
+ * still get sensible single-request correlation for free.
+ */
+export declare function requestIdMiddleware(options?: {
+    readonly resolver?: ClientIpResolver;
+    readonly trustedProxyHops?: number;
+}): (c: Context, next: Next) => Promise<void>;

package/dist/api/request-id-middleware.js

@@ -0,0 +1,112 @@
+import { resolveHeaderLocale } from "../i18n/request-locale.js";
+import { LOCALE_HEADER_NAME } from "./api-constants.js";
+import { createClientIpResolver, extractSocketAddress, } from "./client-ip.js";
+import { requestContext } from "./request-context.js";
+// Fallback for the few call-sites that build a RequestContextData without a
+// caller-configured resolver (e.g. an internal system-query mount reached
+// before requestIdMiddleware ran). trustedProxyHops 0 matches the framework
+// default; callers that care about the real hop count pass their own
+// resolver instead — see requestIdMiddleware(options).
+const FALLBACK_CLIENT_IP_RESOLVER = createClientIpResolver(0, "requestIdMiddleware");
+const REQUEST_ID_HEADER = "X-Request-ID";
+const CORRELATION_ID_HEADER = "X-Correlation-ID";
+// requestId/correlationId flow unvalidated into append-only event-store
+// metadata (e.g. sessions:revoke-all-for-user) — cap shape at the trust
+// boundary so a client can't smuggle an oversized/control-char payload into
+// permanent, replayed, DSGVO-exported storage via a client-set header.
+const SAFE_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+function sanitizeClientId(value) {
+    return value !== undefined && SAFE_ID_RE.test(value) ? value : undefined;
+}
+// Request.headers.get() returns `string | null` (Fetch API); Hono's
+// c.req.header() normalizes that to `string | undefined`. Match Hono's
+// contract here so both builders return the exact same RequestContextData
+// shape regardless of which one a call-site uses.
+function header(req, name) {
+    return req.headers.get(name) ?? undefined;
+}
+/**
+ * Builds the RequestContextData record for a raw Fetch Request — requestId
+ * (client-supplied + sanitized, or generated), correlationId (mirrors
+ * requestId unless the client set its own), the underlying abort signal,
+ * and the client IP/User-Agent. Extracted out of `buildRequestContextData`
+ * so call-sites that only have a `Request` (no Hono `Context`) — e.g.
+ * server-runtime's static-fallback page-head resolver, which runs outside
+ * Hono's router entirely — can still populate the same AsyncLocalStorage
+ * record via `requestContext.run(...)`.
+ */
+export function buildRequestContextDataFromRequest(req, options) {
+    const requestId = sanitizeClientId(header(req, REQUEST_ID_HEADER)) ?? requestContext.generateId();
+    const correlationId = sanitizeClientId(header(req, CORRELATION_ID_HEADER)) ?? requestId;
+    // The Fetch Request's `signal` aborts when the client disconnects (mobile
+    // back-press, tab close). We propagate it through requestContext so
+    // framework internals can honour cancellation at long-running checkpoints.
+    const signal = req.signal;
+    // Client IP for per-IP rate limiting — resolved via the shared
+    // trustedProxyHops-aware resolver. Always set for
+    // an HTTP request; falls back to "unknown" rather than skipping the
+    // ip-bucket (see createClientIpResolver).
+    const resolver = options?.resolver ?? FALLBACK_CLIENT_IP_RESOLVER;
+    const ip = resolver.resolve({
+        header: (name) => header(req, name),
+        socketAddress: options?.socketAddress,
+    });
+    const userAgent = header(req, "user-agent");
+    // Runs before auth-middleware, so this reaches public routes too (e.g.
+    // signup-request) — that's the whole point: the active UI locale must
+    // survive to anonymous callers, not just authenticated ones.
+    const locale = resolveHeaderLocale({
+        headerLocale: header(req, LOCALE_HEADER_NAME),
+        acceptLanguage: header(req, "accept-language"),
+    });
+    return {
+        requestId,
+        correlationId,
+        startedAt: performance.now(),
+        ...(signal ? { signal } : {}),
+        ip,
+        ...(userAgent !== undefined ? { userAgent } : {}),
+        ...(locale !== undefined ? { locale } : {}),
+    };
+}
+/**
+ * Builds the RequestContextData record for a Hono request. Thin wrapper
+ * around `buildRequestContextDataFromRequest(c.req.raw)` — kept as its own
+ * export because most call-sites (server.ts's httpRoute→systemQuery mount,
+ * `requestIdMiddleware` below) already hold a Hono `Context`.
+ */
+export function buildRequestContextData(c, resolver) {
+    // Older Hono / adapter combos may leave c.req.raw unset even though it's
+    // typed as Request — degrade to a bare id pair (no signal/ip/ua/locale)
+    // instead of letting req.headers.get() throw on every request.
+    if (!c.req.raw) {
+        const requestId = requestContext.generateId();
+        return { requestId, correlationId: requestId, startedAt: performance.now() };
+    }
+    return buildRequestContextDataFromRequest(c.req.raw, {
+        resolver,
+        socketAddress: extractSocketAddress(c.env),
+    });
+}
+/**
+ * Assigns a requestId + correlationId to every request and wraps execution
+ * in AsyncLocalStorage. Runs BEFORE auth — both ids are available even for
+ * 401 responses.
+ *
+ * correlationId defaults to the requestId if the client didn't set
+ * `x-correlation-id` — clients that don't care about cross-service tracing
+ * still get sensible single-request correlation for free.
+ */
+export function requestIdMiddleware(options) {
+    // Created once per middleware mount (not per request) so the warn-once
+    // flag in the resolver actually fires only once per server boot.
+    const resolver = options?.resolver ??
+        createClientIpResolver(options?.trustedProxyHops ?? 0, "requestIdMiddleware");
+    return async (c, next) => {
+        const data = buildRequestContextData(c, resolver);
+        c.header(REQUEST_ID_HEADER, data.requestId);
+        c.header(CORRELATION_ID_HEADER, data.correlationId);
+        c.set("requestId", data.requestId);
+        await requestContext.run(data, () => next());
+    };
+}

package/dist/api/route-registrars.d.ts

@@ -0,0 +1,24 @@
+import type { Hono } from "hono";
+import type { DbConnection } from "../db/connection.js";
+import type { Lifecycle } from "../lifecycle/index.js";
+import type { Meter } from "../observability/index.js";
+import type { EventConsumer } from "../pipeline/event-dispatcher.js";
+export declare const DEFAULT_MAX_REQUEST_BYTES = 1048576;
+export declare function registerBodyLimit(app: Hono, maxBytes: number): void;
+export type MetricsRouteOptions = {
+    readonly token?: string;
+    readonly path?: string;
+};
+export declare function registerMetricsRoute(app: Hono, meter: Meter, options: MetricsRouteOptions): void;
+export declare function registerVersionRoute(app: Hono): void;
+export type HealthRoutesOptions = {
+    readonly lifecycle?: Lifecycle;
+    readonly readiness?: {
+        readonly db?: DbConnection;
+        readonly redis?: import("ioredis").Redis;
+        readonly consumers?: readonly EventConsumer[];
+        readonly timeoutMs?: number;
+        readonly maxDispatcherLag?: bigint;
+    };
+};
+export declare function registerHealthRoutes(app: Hono, options: HealthRoutesOptions): void;

package/dist/api/route-registrars.js

@@ -0,0 +1,133 @@
+// Route-level wiring that buildServer used to inline. Extracted so
+// server.ts stays a composition-of-named-steps rather than 500 lines of
+// branches. Every registrar takes the Hono app + whatever state it
+// actually reads — no monolithic `options` parameter, because these
+// helpers exist to make each step's dependencies visible at the call-site.
+import { bodyLimit } from "hono/body-limit";
+import { serializeOpenMetrics } from "../observability/index.js";
+import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "./api-constants.js";
+import { createReadinessProbe, dbPingCheck, dispatcherLagCheck, redisPingCheck, } from "./readiness.js";
+// --- Body size limit ------------------------------------------------------
+export const DEFAULT_MAX_REQUEST_BYTES = 1_048_576;
+// Cap every /api/* request body by default — a new route needs no entry
+// anywhere to be covered, it inherits the limit from being registered under
+// /api at all. Routes with their own size contract (currently just uploads)
+// opt out explicitly via BODY_LIMIT_OPT_OUT_PATHS in api-constants.ts;
+// forgetting an opt-out entry only over-limits a route, forgetting to add a
+// new route to an allowlist used to leave it unlimited — that inversion is
+// the point. `maxBytes <= 0` disables the limit entirely — only useful when
+// a reverse-proxy caps upstream or tests want raw passthrough.
+export function registerBodyLimit(app, maxBytes) {
+    // skip: opt-out path — caller passed `maxBytes: 0`, so no middleware
+    // is attached (upstream cap via reverse-proxy is expected). Not a bug
+    // suppression, an intentional disable.
+    if (maxBytes <= 0)
+        return;
+    const limit = bodyLimit({ maxSize: maxBytes });
+    app.use("/api/*", async (c, next) => {
+        if (BODY_LIMIT_OPT_OUT_PATHS.has(c.req.path))
+            return next();
+        return limit(c, next);
+    });
+}
+// Timing-safe string compare — equal-length strings compare every byte
+// regardless of where they diverge; different lengths return false without
+// iterating. Prevents side-channel leaks on the Bearer-token check.
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+// Type-guard: duck-types the meter on `snapshot()`. An alternative
+// Prometheus-compatible meter (future OTLP bridge) works without an
+// explicit union — if it exposes `snapshot()` it's serialisable.
+function isPrometheusMeter(m) {
+    return typeof m.snapshot === "function"; // @cast-boundary schema-walk
+}
+// Mount `/metrics` (or the caller-supplied path). Takes just the Meter —
+// not the whole ObservabilityProvider — because that's the only field
+// this route reads. Bearer-token optional — without one, scraping is
+// open, fine for a private cluster.
+export function registerMetricsRoute(app, meter, options) {
+    const metricsPath = options.path ?? "/metrics";
+    const expectedToken = options.token;
+    app.get(metricsPath, async (c) => {
+        if (expectedToken !== undefined) {
+            const header = c.req.header("authorization") ?? "";
+            const prefix = "Bearer ";
+            if (!header.startsWith(prefix))
+                return c.text("unauthorized", 401);
+            const provided = header.slice(prefix.length);
+            if (!constantTimeEqual(provided, expectedToken))
+                return c.text("unauthorized", 401);
+        }
+        if (!isPrometheusMeter(meter)) {
+            return c.text("metrics endpoint requires a PrometheusMeter — wrap the observability provider around createPrometheusMeter()", 503);
+        }
+        const body = serializeOpenMetrics(meter);
+        c.header("Content-Type", "application/openmetrics-text; version=1.0.0; charset=utf-8");
+        return c.body(body);
+    });
+}
+// --- /version ---------------------------------------------------------------
+// Anonymous endpoint that returns build-identity. Used by ops tooling
+// (prod-version.sh) and the Telegram deploy notification so nobody needs
+// kubectl + crictl on the master to see the deployed version.
+//
+// BUILD_VERSION + BUILD_TIME are passed through from the Dockerfile
+// (ARG → ENV) — fall back to "dev" / "unknown" when built locally
+// without build-args.
+export function registerVersionRoute(app) {
+    const version = process.env["BUILD_VERSION"] ?? "dev";
+    const buildTime = process.env["BUILD_TIME"] ?? "unknown";
+    app.get(Routes.version, (c) => c.json({
+        version,
+        buildTime,
+        node: process.env["NODE_ENV"] ?? "development",
+    }));
+}
+// Mount both health probes:
+//   /health — always, trivial 200 with `{status:"ok"}` (liveness)
+//   /health/ready — only when a lifecycle is wired. Short-circuits to
+//                   503 during drain; otherwise runs dependency checks
+//                   (DB/Redis/Dispatcher-lag) in parallel with a per-check
+//                   timeout.
+export function registerHealthRoutes(app, options) {
+    app.get(Routes.health, (c) => c.json({ status: "ok" }));
+    // skip: no lifecycle wired → /health/ready stays absent by design.
+    // Without lifecycle we'd have no way to flip the probe to 503 on
+    // drain — `/health` alone is enough for a test/dev process.
+    if (!options.lifecycle)
+        return;
+    const lifecycle = options.lifecycle;
+    const readiness = options.readiness;
+    const readinessChecks = [];
+    if (readiness?.db)
+        readinessChecks.push(dbPingCheck(readiness.db));
+    if (readiness?.redis)
+        readinessChecks.push(redisPingCheck(readiness.redis));
+    if (readiness?.maxDispatcherLag !== undefined &&
+        readiness.db &&
+        readiness.consumers &&
+        readiness.consumers.length > 0) {
+        readinessChecks.push(dispatcherLagCheck(readiness.db, readiness.consumers.map((c) => c.name), readiness.maxDispatcherLag));
+    }
+    const probe = createReadinessProbe(readinessChecks, { timeoutMs: readiness?.timeoutMs });
+    app.get(Routes.healthReady, async (c) => {
+        const state = lifecycle.state();
+        if (state !== "ready") {
+            return c.json({ status: "not_ready", state, uptimeSec: lifecycle.uptimeSec() }, 503);
+        }
+        const result = await probe();
+        return c.json({
+            status: result.ok ? "ready" : "not_ready",
+            state,
+            uptimeSec: lifecycle.uptimeSec(),
+            checks: result.checks,
+        }, result.ok ? 200 : 503);
+    });
+}