@cosmicdrift/kumiko-framework 0.381.0 → 0.383.0

package/agents/examples/api-worker-split.md

@@ -62,6 +62,14 @@ With only the API running, `read_orders` gains the row but
 `read_order_activity` stays empty. Start the worker and both the activity
 row and the `read_fulfillments` row appear.
 
+## Deferring a job
+
+`process-order` returns `context.defer(ms)` while the (simulated) carrier is busy. The job
+is re-run after `ms` on the same queue job: no retry attempt is used, no failure is logged
+or recorded, and the run log shows only the runs that actually executed. `maxDefers`
+(default 100) bounds it; beyond that the run fails. It needs a queued run: an inline boot
+gate throws.
+
 ## Test
 
 Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
@@ -125,6 +133,7 @@ import {
   fulfillmentEntity,
   orderActivityTable,
   orderEntity,
+  setCarrierRetryAfter,
   setOrderFulfillWrite,
 } from "../feature";
 
@@ -258,6 +267,44 @@ describe("api-worker-split", () => {
       await Promise.all([api.stop(), worker.stop()]);
     }
   });
+
+  test("a busy carrier defers the job without failing it, then the fulfillment lands", async () => {
+    const prefix = uniquePrefix();
+    const api = createApiEntrypoint({
+      registry: createRegistry([createApiWorkerSplitFeature()]),
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      jobs: { redisUrl: redisUrl(), queueNamePrefix: prefix },
+    });
+    const worker = createWorkerEntrypoint({
+      registry: createRegistry([createApiWorkerSplitFeature()]),
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl: redisUrl(),
+      queueNamePrefix: prefix,
+    });
+    setOrderFulfillWrite(makeDispatchSystemWrite(worker.dispatcher));
+    let busyChecks = 0;
+    setCarrierRetryAfter(() => {
+      busyChecks += 1;
+      return busyChecks === 1 ? 200 : 0;
+    });
+
+    await Promise.all([api.start(), worker.start()]);
+    try {
+      expect(await writeOrder(api, "Initech AG", 250)).toBe(true);
+      await waitFor(async () => {
+        const fulfillments = await selectMany<{ orderKey: string }>(testDb.db, fulfillmentTable, {
+          tenantId: adminUser.tenantId,
+        });
+        expect(fulfillments.some((row) => row.orderKey === "Initech AG")).toBe(true);
+      });
+      expect(busyChecks).toBe(2);
+    } finally {
+      setCarrierRetryAfter(() => 0);
+      await Promise.all([api.stop(), worker.stop()]);
+    }
+  });
 });
 ```
 
@@ -350,6 +397,13 @@ export function setOrderFulfillWrite(fn: FulfillWrite): void {
   fulfillWrite = fn;
 }
 
+let carrierRetryAfterMs: () => number = () => 0;
+
+/** Stand-in for a rate-limited carrier API: ms until it accepts work again, 0 when free. */
+export function setCarrierRetryAfter(fn: () => number): void {
+  carrierRetryAfterMs = fn;
+}
+
 // Job payloads arrive as `Record<string, unknown>` (JobHandlerFn) — an
 // unchecked `as string` cast here would let a missing/non-string field
 // through silently, writing `orderKey: undefined` / `label: "label-
@@ -389,6 +443,9 @@ export function createApiWorkerSplitFeature() {
           );
         }
         const { customerName } = processOrderPayloadSchema.parse(payload);
+        // Busy is not a failure: ctx.defer re-runs the job later without burning a retry.
+        const retryAfterMs = carrierRetryAfterMs();
+        if (retryAfterMs > 0) return context.defer(retryAfterMs);
         const result = await fulfillWrite({
           handlerQn: "orders:write:fulfillment:create",
           payload: {

package/agents/examples/record-detail-layout.md

@@ -13,12 +13,12 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
 
 ## What it shows
 
-- `header` (title/subtitle/status) and `metrics` (labeled via `fieldLabels`)
+- `header` (title/subtitle/status) and `metrics` (each with its own i18n `label`)
   rendered from the columns of the screen's own query row
 - `layout.mode: "tabs"` with two `relatedList` tabs (order items, payments)
   and one `fields` tab (master data) — each `relatedList` runs its own query
 - boot-validator catching two common author mistakes: a `metrics` entry
-  without a `fieldLabels` override, and a `tabs` layout with fewer than two
+  with an empty `label`, and a `tabs` layout with fewer than two
   sections
 
 ## Source
@@ -43,7 +43,7 @@ bun test
 //     exactly as declared (column names, not literals)
 //   - relatedList columns collapse the string shorthand like entityList columns do
 //   - the boot-validator catches the two mistakes the projectionDetail tabs
-//     layout introduces: a metric without a fieldLabels entry, and a tabs
+//     layout introduces: a metric with an empty label, and a tabs
 //     layout with fewer than two sections
 
 import { describe, expect, test } from "bun:test";
@@ -82,7 +82,12 @@ describe("record-detail-layout showcase — registration", () => {
       subtitle: "orderNumber",
       status: "status",
     });
-    expect(screen.metrics).toEqual(["totalAmount", "outstandingAmount", "itemCount", "placedAt"]);
+    expect(screen.metrics?.map((metric) => metric.field)).toEqual([
+      "totalAmount",
+      "outstandingAmount",
+      "itemCount",
+      "placedAt",
+    ]);
   });
 
   test("layout.mode is tabs with two relatedList sections, one fields section, and one extension section", () => {
@@ -113,7 +118,7 @@ describe("record-detail-layout showcase — registration", () => {
 });
 
 describe("record-detail-layout showcase — boot-validator catches author mistakes", () => {
-  test("metric without a fieldLabels entry fails boot — no fallback to the raw column name", () => {
+  test("metric with an empty label fails boot — no fallback to the raw column name", () => {
     const broken = defineFeature("broken-order-desk", (r) => {
       r.queryHandler({
         name: "order:detail",
@@ -125,13 +130,11 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
         id: "order-detail",
         type: "projectionDetail",
         query: "broken-order-desk:query:order:detail",
-        metrics: ["totalAmount"],
+        metrics: [{ field: "totalAmount", label: "" }],
         layout: { sections: [{ title: "Details", fields: ["id"] }] },
       });
     });
-    expect(() => validateBoot([broken])).toThrow(
-      /metric "totalAmount" has no entry in fieldLabels/,
-    );
+    expect(() => validateBoot([broken])).toThrow(/metric "totalAmount" has no "label"/);
   });
 
   test("tabs with only one section fails boot", () => {
@@ -165,8 +168,8 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
 //   1. `header` renders the query row's customer/order/status columns above
 //      the layout — the identity a support agent scans first.
 //   2. `metrics` renders a labeled band of key numbers from the same row —
-//      labels come from `fieldLabels`, there is no fallback to the raw
-//      column name.
+//      each metric carries its own i18n `label`, there is no fallback to the
+//      raw column name.
 //   3. `layout.mode: "tabs"` splits the record into four tabs: two
 //      `relatedList` sections (own query, own pagination, mounts only when
 //      active), one `fields` section (master data from the detail row), and
@@ -238,13 +241,12 @@ export function createOrderDeskFeature(): FeatureDefinition {
       type: "projectionDetail",
       query: "order-desk:query:order:detail",
       header: { title: "customerName", subtitle: "orderNumber", status: "status" },
-      metrics: ["totalAmount", "outstandingAmount", "itemCount", "placedAt"],
-      fieldLabels: {
-        totalAmount: "order-desk.metric.totalAmount",
-        outstandingAmount: "order-desk.metric.outstandingAmount",
-        itemCount: "order-desk.metric.itemCount",
-        placedAt: "order-desk.metric.placedAt",
-      },
+      metrics: [
+        { field: "totalAmount", label: "order-desk.metric.totalAmount" },
+        { field: "outstandingAmount", label: "order-desk.metric.outstandingAmount" },
+        { field: "itemCount", label: "order-desk.metric.itemCount" },
+        { field: "placedAt", label: "order-desk.metric.placedAt" },
+      ],
       layout: {
         mode: "tabs",
         sections: [

package/agents/examples/screens-nav.md

@@ -49,6 +49,7 @@ import {
   isFieldsEditSection,
   normalizeEditField,
   normalizeListColumn,
+  sectionFieldSpecs,
   validateBoot as validateBootRaw,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
@@ -160,9 +161,9 @@ describe("screens-nav showcase — field specs", () => {
     if (!publishingSection || !isFieldsEditSection(publishingSection)) {
       throw new Error("expected fields section");
     }
-    const priceField = normalizeEditField(publishingSection.fields[0]!);
+    const priceField = normalizeEditField(sectionFieldSpecs(publishingSection)[0]!);
     expect(priceField.readOnly).toEqual({ field: "published", eq: true });
-    const authorField = normalizeEditField(basicsSection.fields[1]!);
+    const authorField = normalizeEditField(sectionFieldSpecs(basicsSection)[1]!);
     expect(authorField.visible).toEqual({ field: "published", eq: false });
   });
 });

package/agents/examples/writeform-section.md

@@ -55,6 +55,7 @@ import {
   createRegistry,
   createTextField,
   defineFeature,
+  sectionFieldSpecs,
   validateBoot as validateBootRaw,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
@@ -107,7 +108,7 @@ describe("writeform-section sample — registration", () => {
       throw new Error("expected an entityEdit fields section and a writeForm section");
     }
 
-    const editFields = editSection.fields.map(fieldName);
+    const editFields = sectionFieldSpecs(editSection).map(fieldName);
     const writeFormFields = detailSection.fields.map(fieldName);
     expect(writeFormFields).toEqual(editFields);
   });

package/dist/api/api-constants.d.ts

@@ -30,6 +30,7 @@ export declare const Routes: {
     readonly authInviteInfo: "/auth/invite-info";
     readonly files: "/files";
     readonly schema: "/schema";
+    readonly clientErrors: "/client-errors";
 };
 export declare const PUBLIC_API_PATHS: ReadonlySet<string>;
 export declare const NON_PUBLIC_API_PATHS: ReadonlySet<string>;

package/dist/api/api-constants.js

@@ -36,6 +36,7 @@ export const Routes = {
     authInviteInfo: "/auth/invite-info",
     files: "/files",
     schema: "/schema",
+    clientErrors: "/client-errors",
 };
 // Routes that must be reachable WITHOUT a valid JWT.
 // The auth middleware skips these paths.
@@ -61,6 +62,7 @@ export const PUBLIC_API_PATHS = new Set([
     `/api${Routes.health}`,
     `/api${Routes.healthReady}`,
     `/api${Routes.version}`,
+    `/api${Routes.clientErrors}`,
 ]);
 // Every other route in `Routes` — explicit, so a route can never fall
 // through to "public" by simply being absent from PUBLIC_API_PATHS. A

package/dist/api/auth-middleware.d.ts

@@ -33,6 +33,7 @@ export type AnonymousAccessResolved = AnonymousAccessConfig & {
     readonly tenantExists?: TenantExists;
     readonly resolverTrust?: "authoritative" | "fallback-only";
 };
+export declare function identifyOptionalSession(c: Context, jwt: JwtHelper): Promise<void>;
 export declare function authMiddleware(jwt: JwtHelper, options?: AuthMiddlewareOptions): (c: Context, next: Next) => Promise<Response | undefined>;
 export declare function getUser(c: Context): SessionUser;
 export declare function getAuthTransport(c: Context): AuthTransport | undefined;

package/dist/api/auth-middleware.js

@@ -5,6 +5,7 @@ import { createAnonymousUser } from "../engine/system-user.js";
 import { parseTenantId, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { isSessionRequiredApiPath, TENANT_HEADER_NAME } from "./api-constants.js";
 import { isForeignCookieOrigin } from "./origin-middleware.js";
+import { setRequestIdentity } from "./request-context.js";
 import { clearSessionCookies, getSessionCookies, hasDuplicateSessionCookie, } from "./session-cookies.js";
 const USER_KEY = "pipelineUser";
 const AUTH_TRANSPORT_KEY = "authTransport";
@@ -86,6 +87,20 @@ function extractToken(c) {
         return { token: bearerToken, transport: "bearer" };
     return { error: "missing" };
 }
+// Best-effort for public routes that only want to attribute the log line: a bad or absent token is ignored.
+export async function identifyOptionalSession(c, jwt) {
+    const extracted = extractToken(c);
+    // skip: without a token the report stays anonymous
+    if ("error" in extracted)
+        return;
+    try {
+        const payload = await jwt.verify(extracted.token);
+        setRequestIdentity({ tenantId: payload.tenantId, userId: payload.sub });
+    }
+    catch {
+        // skip: an unverifiable token only means the report stays anonymous
+    }
+}
 export function authMiddleware(jwt, options = {}) {
     const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus, foreignCookieOrigins, isTenantlessAnonymousWrite, } = options;
     // Fail loud at boot, not silently at request time: a tenantResolver
@@ -224,6 +239,7 @@ export function authMiddleware(jwt, options = {}) {
         if (lifecycleReject)
             return lifecycleReject;
         c.set(USER_KEY, user);
+        setRequestIdentity({ tenantId: user.tenantId, userId: user.id });
         c.set(AUTH_TRANSPORT_KEY, transport);
         if (payload.exp !== undefined)
             c.set(AUTH_TOKEN_EXPIRY_KEY, payload.exp);
@@ -266,6 +282,7 @@ async function handleVerifiedBearerUser(c, user, next, resolveTenantLifecycleSta
         });
     }
     c.set(USER_KEY, user);
+    setRequestIdentity({ tenantId: user.tenantId, userId: user.id });
     c.set(AUTH_TRANSPORT_KEY, "bearer");
     const lifecycleReject = await rejectIfTenantTeardown(c, user.tenantId, resolveTenantLifecycleStatus);
     if (lifecycleReject)

package/dist/api/auth-routes.d.ts

@@ -80,6 +80,7 @@ export type SignupConfig = {
     requestHandler: string;
     confirmHandler: string;
 };
+export declare function inMemoryLoginRateLimiterFallback(): LoginRateLimiter;
 export declare function createInMemoryLoginRateLimiter(maxAttempts?: number, windowMs?: number, { maxEntries, sweepThreshold, }?: {
     maxEntries?: number;
     sweepThreshold?: number;

package/dist/api/auth-routes.js

@@ -6,6 +6,7 @@ import { buildSessionRoles } from "../engine/membership-roles.js";
 import { createAnonymousUser, createSystemUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID, } from "../engine/types/index.js";
 import { NotFoundError, toKumikoError, toWriteErrorInfo } from "../errors/index.js";
+import { createFallbackLogger } from "../logging/index.js";
 import { assertUnreachable } from "../utils/index.js";
 import { parseRoles } from "../utils/serialization.js";
 import { Routes } from "./api-constants.js";
@@ -209,6 +210,15 @@ function requestMeta(c, resolver) {
     const userAgent = c.req.header("user-agent") ?? "unknown";
     return { ip, userAgent };
 }
+let warnedInMemoryLimiterInProduction = false;
+// Without Redis-backed limiters each replica counts on its own, so the effective limit scales with replica count.
+export function inMemoryLoginRateLimiterFallback() {
+    if (process.env["NODE_ENV"] === "production" && !warnedInMemoryLimiterInProduction) {
+        warnedInMemoryLimiterInProduction = true;
+        createFallbackLogger("auth-routes").warn("login/MFA rate limiter falls back to in-memory; limits are per replica");
+    }
+    return createInMemoryLoginRateLimiter();
+}
 // Default: in-memory fixed window. Fine for a single Node process; for
 // multi-process deployments, inject a Redis-backed LoginRateLimiter instead
 // so attempts can't be spread across replicas.
@@ -413,7 +423,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         // Default to in-memory limiter unless the caller opted out via null.
         const rateLimiter = config.loginRateLimit === null
             ? null
-            : (config.loginRateLimit ?? createInMemoryLoginRateLimiter());
+            : (config.loginRateLimit ?? inMemoryLoginRateLimiterFallback());
         api.post(Routes.authLogin, async (c) => {
             const raw = await c.req.json().catch(() => null);
             const parsed = LoginBody.safeParse(raw);
@@ -503,7 +513,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         const statusMap = config.mfaVerifyErrorStatusMap ?? {};
         const rateLimiter = config.mfaVerifyRateLimit === null
             ? null
-            : (config.mfaVerifyRateLimit ?? createInMemoryLoginRateLimiter());
+            : (config.mfaVerifyRateLimit ?? inMemoryLoginRateLimiterFallback());
         api.post(Routes.authMfaVerify, async (c) => {
             const raw = await c.req.json().catch(() => null);
             const parsed = MfaVerifyBody.safeParse(raw);
@@ -560,7 +570,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         const statusMap = config.mfaPreauthEnableStartErrorStatusMap ?? {};
         const rateLimiter = config.mfaPreauthEnableStartRateLimit === null
             ? null
-            : (config.mfaPreauthEnableStartRateLimit ?? createInMemoryLoginRateLimiter());
+            : (config.mfaPreauthEnableStartRateLimit ?? inMemoryLoginRateLimiterFallback());
         api.post(Routes.authMfaPreauthEnableStart, async (c) => {
             const raw = await c.req.json().catch(() => null);
             const parsed = MfaPreauthEnableStartBody.safeParse(raw);
@@ -610,7 +620,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         const statusMap = config.mfaPreauthConfirmErrorStatusMap ?? {};
         const rateLimiter = config.mfaPreauthConfirmRateLimit === null
             ? null
-            : (config.mfaPreauthConfirmRateLimit ?? createInMemoryLoginRateLimiter());
+            : (config.mfaPreauthConfirmRateLimit ?? inMemoryLoginRateLimiterFallback());
         api.post(Routes.authMfaPreauthConfirm, async (c) => {
             const raw = await c.req.json().catch(() => null);
             const parsed = MfaPreauthConfirmBody.safeParse(raw);

package/dist/api/client-error-route.d.ts

@@ -0,0 +1,12 @@
+import { type Context, Hono } from "hono";
+import type { Meter } from "../observability/types/index.ts";
+import type { RateLimitResolver } from "../rate-limit/resolver.ts";
+import { type ClientIpResolver } from "./client-ip.ts";
+export type ClientErrorRouteOptions = {
+    readonly resolver: RateLimitResolver | undefined;
+    readonly clientIpResolver: ClientIpResolver;
+    readonly meter?: Meter;
+    readonly now?: () => number;
+    readonly identifySession: (c: Context) => Promise<void>;
+};
+export declare function createClientErrorRoute(options: ClientErrorRouteOptions): Hono;

package/dist/api/client-error-route.js

@@ -0,0 +1,113 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import * as z from "zod";
+import { createFallbackLogger, scrubLogText } from "../logging/index.js";
+import { httpRouteRateLimit, respondRateLimited } from "../rate-limit/middleware.js";
+import { Routes } from "./api-constants.js";
+import { clientIpSourceFromHonoContext } from "./client-ip.js";
+const MAX_BODY_BYTES = 8 * 1024;
+const REPORTS_PER_WINDOW = 10;
+const WINDOW_SECONDS = 60;
+const clientErrorReportSchema = z.strictObject({
+    errorId: z.uuid(),
+    kind: z.enum(["render", "unhandled"]),
+    message: z.string().max(500),
+    stack: z.string().max(4000).optional(),
+    screen: z.string().max(200).optional(),
+    path: z.string().max(300).optional(),
+    buildVersion: z
+        .string()
+        .regex(/^[\w.+-]{1,64}$/)
+        .optional(),
+});
+// Query and fragment can carry tokens or personal data; only the route shape is useful for triage.
+function stripQueryAndFragment(path) {
+    return path.split(/[?#]/, 1)[0] ?? "";
+}
+const MAX_TRACKED_IPS = 10_000;
+// Without Redis there is no shared limiter; a per-process window still bounds log flooding.
+function inMemoryIpRateLimit(clientIpResolver, now) {
+    const windowMs = WINDOW_SECONDS * 1000;
+    const windows = new Map();
+    function evictExpired(nowMs) {
+        if (windows.size > MAX_TRACKED_IPS) {
+            for (const [ip, window] of windows) {
+                if (nowMs - window.startedAt >= windowMs)
+                    windows.delete(ip);
+            }
+        }
+        if (windows.size > MAX_TRACKED_IPS)
+            windows.clear();
+    }
+    return async (c, next) => {
+        const ip = clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
+        const nowMs = now();
+        evictExpired(nowMs);
+        const existing = windows.get(ip);
+        const window = existing && nowMs - existing.startedAt < windowMs ? existing : { count: 0, startedAt: nowMs };
+        window.count += 1;
+        windows.set(ip, window);
+        if (window.count > REPORTS_PER_WINDOW) {
+            const resetAtMs = window.startedAt + windowMs;
+            const decision = {
+                allowed: false,
+                limit: REPORTS_PER_WINDOW,
+                remaining: 0,
+                retryAfterSeconds: Math.max(1, Math.ceil((resetAtMs - nowMs) / 1000)),
+                windowSeconds: WINDOW_SECONDS,
+                resetAt: Temporal.Instant.fromEpochMilliseconds(resetAtMs),
+            };
+            return respondRateLimited(c, decision, `http:${ip}`);
+        }
+        await next();
+    };
+}
+export function createClientErrorRoute(options) {
+    const app = new Hono();
+    const logger = createFallbackLogger("client-errors");
+    const routePath = `/api${Routes.clientErrors}`;
+    if (options.resolver) {
+        app.post(Routes.clientErrors, httpRouteRateLimit({
+            resolver: options.resolver,
+            rateLimit: { per: "ip", limit: REPORTS_PER_WINDOW, windowSeconds: WINDOW_SECONDS },
+            routeKey: `POST ${routePath}`,
+            clientIpResolver: options.clientIpResolver,
+            ...(options.meter && { meter: options.meter }),
+        }));
+    }
+    else {
+        app.post(Routes.clientErrors, inMemoryIpRateLimit(options.clientIpResolver, options.now ?? Date.now));
+    }
+    app.post(Routes.clientErrors, bodyLimit({
+        maxSize: MAX_BODY_BYTES,
+        onError: (c) => c.json({ error: { code: "payload_too_large" } }, 413),
+    }), async (c) => {
+        let raw;
+        try {
+            raw = await c.req.json();
+        }
+        catch {
+            return c.json({ error: { code: "invalid_client_error_report" } }, 400);
+        }
+        const parsed = clientErrorReportSchema.safeParse(raw);
+        if (!parsed.success) {
+            return c.json({ error: { code: "invalid_client_error_report" } }, 400);
+        }
+        await options.identifySession(c);
+        const report = parsed.data;
+        logger.warn("client error", {
+            errorId: report.errorId,
+            kind: report.kind,
+            message: scrubLogText(report.message),
+            ...(report.stack !== undefined && { stack: scrubLogText(report.stack) }),
+            ...(report.screen !== undefined && { screen: scrubLogText(report.screen) }),
+            ...(report.path !== undefined && {
+                path: scrubLogText(stripQueryAndFragment(report.path)),
+            }),
+            ...(report.buildVersion !== undefined && { buildVersion: report.buildVersion }),
+        });
+        return c.body(null, 204);
+    });
+    return app;
+}

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

@@ -12,6 +12,8 @@ export type RequestContextData = {
     readonly locale?: string;
     readonly feature?: string;
     readonly handler?: string;
+    tenantId?: string;
+    userId?: string;
     readonly startedAt?: number;
     readonly writeOrigin?: WriteOrigin;
     readonly entryHandler?: {
@@ -25,6 +27,10 @@ export declare const requestContext: {
     get(): RequestContextData | undefined;
     generateId(): string;
 };
+export declare function setRequestIdentity(identity: {
+    tenantId: string;
+    userId?: string;
+}): void;
 export declare const readonlyRequestContext: Pick<typeof requestContext, "get">;
 export declare function runWithOrigin<T>(origin: {
     readonly feature?: string;

package/dist/api/request-context.js

@@ -13,6 +13,15 @@ export const requestContext = {
         return generateId();
     },
 };
+export function setRequestIdentity(identity) {
+    const store = storage.getStore();
+    // skip: outside a request scope there is no log context to enrich
+    if (!store)
+        return;
+    store.tenantId = identity.tenantId;
+    if (identity.userId !== undefined)
+        store.userId = identity.userId;
+}
 // Public view: `run` would let a caller replace the request scope (entryHandler,
 // writeOrigin), so only the read side is exposed through the /api barrel.
 export const readonlyRequestContext = {

package/dist/api/routes.js

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { streamSSE } from "hono/streaming";
 import { AccessDeniedError, reraiseAsKumikoError, serializeError, toKumikoError, ValidationError, } from "../errors/index.js";
-import { createFallbackLogger } from "../logging/index.js";
+import { createFallbackLogger, scrubLogText, scrubLogValue } from "../logging/index.js";
 import { isPlainObject } from "../utils/is-plain-object.js";
 import { stringifyJson } from "../utils/safe-json.js";
 import { Routes } from "./api-constants.js";
@@ -378,6 +378,9 @@ function isClientAbort(err) {
     const signal = requestContext.get()?.signal;
     return signal?.aborted === true && err.cause !== undefined && err.cause === signal.reason;
 }
+function scrubOptionalText(text) {
+    return text === undefined ? undefined : scrubLogText(text);
+}
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero
@@ -395,9 +398,9 @@ function logServerFault(err, requestId, type) {
         requestId,
         type: loggableType(type),
         code: err.code,
-        message: err.message,
-        cause: cause instanceof Error ? cause.message : cause,
-        stack: cause instanceof Error ? cause.stack : err.stack,
+        message: scrubLogText(err.message),
+        cause: cause instanceof Error ? scrubLogText(cause.message) : scrubLogValue(cause),
+        stack: scrubOptionalText(cause instanceof Error ? cause.stack : err.stack),
     });
 }
 // Same floor of 1 as the rate-limit middleware: "Retry-After: 0" invites an instant retry loop.

package/dist/api/server.js

@@ -31,8 +31,9 @@ import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-confi
 import { assertUnreachable, generateId } from "../utils/index.js";
 import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 import { NO_ROUTE_MATCH_HEADER_NAME, NON_PUBLIC_API_PATHS, PUBLIC_API_PATHS, Routes, } from "./api-constants.js";
-import { authMiddleware, getAuthTokenExpiry, getUser, } from "./auth-middleware.js";
+import { authMiddleware, getAuthTokenExpiry, getUser, identifyOptionalSession, } from "./auth-middleware.js";
 import { assertSessionCallbacksPaired, createAuthRoutes, } from "./auth-routes.js";
+import { createClientErrorRoute } from "./client-error-route.js";
 import { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
 import { csrfMiddleware } from "./csrf-middleware.js";
 import { collectEntityReadAccess } from "./entity-read-access.js";
@@ -511,6 +512,7 @@ export function buildServer(options) {
                 ...options.rateLimit.global,
                 resolver: rateLimitResolver,
                 clientIpResolver,
+                meter: observability.meter,
             });
             app.use("/api/*", globalRateLimitGuard);
         }
@@ -663,6 +665,13 @@ export function buildServer(options) {
             resolver: clientIpResolver,
         }));
     }
+    app.route("/api", createClientErrorRoute({
+        resolver: rateLimitResolver ??
+            (wrappedRedis ? createRateLimitResolver({ redis: wrappedRedis }) : undefined),
+        clientIpResolver,
+        meter: observability.meter,
+        identifySession: (c) => identifyOptionalSession(c, jwt),
+    }));
     app.route("/api", createApiRoutes(dispatcher, {
         ...(options.sseHeartbeatMs !== undefined ? { sseHeartbeatMs: options.sseHeartbeatMs } : {}),
     }));
@@ -785,6 +794,7 @@ export function buildServer(options) {
                         rateLimit: route.rateLimit,
                         routeKey: `${route.method} ${route.path}`,
                         clientIpResolver,
+                        meter: observability.meter,
                     }),
                 ]
                 : [];

package/dist/db/connection.d.ts

@@ -9,6 +9,9 @@ export type DbConnectionOptions = {
     readonly closeTimeoutSeconds?: number;
     readonly ssl?: PostgresDriverOptions["ssl"];
     readonly onNotice?: (notice: postgres.Notice) => void;
+    readonly statementTimeoutMs?: number;
+    readonly idleInTransactionSessionTimeoutMs?: number;
+    readonly lockTimeoutMs?: number;
 };
 export type CreateDbConnectionOptions = DbConnectionOptions & {
     readonly url: string;
@@ -19,7 +22,11 @@ export type DbConnectionHandle = {
     close: () => Promise<void>;
 };
 export declare const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
+export declare function openUnboundedSiblingPool(db: unknown): PgClient | undefined;
 export declare function createDbConnection({ url, ...options }: CreateDbConnectionOptions): DbConnectionHandle;
 export declare function dbConnectionOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
+export declare const DEFAULT_SERVER_STATEMENT_TIMEOUT_MS = 60000;
+export declare const DEFAULT_SERVER_IDLE_IN_TRANSACTION_TIMEOUT_MS = 300000;
+export declare function serverTimeoutOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
 export declare const DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX = 3;
 export declare function outsideTransactionPoolOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;