@nanobpm/urban 0.39.0 → 0.40.1

package/README.md

@@ -100,6 +100,43 @@ The runtime has a single engine client, `SdkEngineClient`, backed by one
 selects the wire transport via `CAMUNDA_TRANSPORT`: `auto` (default) upgrades to
 Falcon on a Nano server and falls back to REST elsewhere.
 
+### Structured logging
+
+Every worker handler and API route delegate receives an `AppApi` whose `log` is a
+level-tagged structured logger (ADR 0061):
+
+```ts
+app.log.info("charge captured", { amount, currency });
+app.log.warn("retrying", { attempt });
+app.log.error("charge failed", { code });
+app.log.debug("gateway response", { raw });   // hidden unless URBAN_LOG_LEVEL=debug
+
+const orderLog = app.log.child({ orderId });    // bind context for a scope
+orderLog.info("shipped");                        // every line carries orderId
+```
+
+The runtime **auto-correlates**: a worker handler's `app.log` is pre-bound to
+`{ jobKey, jobType, processInstanceKey, elementId }` and a route delegate's to
+`{ method, path, operationId }`, so every line you emit is tied to its job/request
+for free.
+
+The `UrbanApp` handle returned by `runFromEnv`/`createUrbanApp` also carries an
+app-level `app.log` (no per-request correlation) for the entrypoint's boot/shutdown
+lines:
+
+```ts
+const app = await runFromEnv();
+app.log.info("started", { httpPort: app.httpPort });
+```
+
+Records are written as **NDJSON** — one JSON object per line,
+`{"ts":…,"level":…,"msg":…, …fields}` — with `warn`/`error` on stderr and
+`debug`/`info` on stdout. `URBAN_LOG_LEVEL` (default `info`) sets the minimum level.
+
+> **Custom hosts:** the `HostContext.log` sink now accepts `"debug"` in addition to
+> `"info" | "warn" | "error"`. A custom host that typed `log` with the narrower union must add a
+> `"debug"` branch to keep satisfying the contract — a breaking change for that surface only.
+
 ### Toolkit — derive artifacts (`urban gen`)
 
 ```ts

package/dist/openapi/spec.d.ts

@@ -2,7 +2,7 @@
  *  are ignored by the validator and fall back to `unknown` in the type emitter. */
 export interface OpenApiSchema {
     $ref?: string;
-    type?: string;
+    type?: string | string[];
     nullable?: boolean;
     enum?: unknown[];
     const?: unknown;
@@ -25,6 +25,21 @@ export interface OpenApiSchema {
     anyOf?: OpenApiSchema[];
     description?: string;
 }
+/**
+ * The declared JSON-Schema `type`(s) as a list, normalizing OpenAPI 3.0 (a single string) and
+ * 3.1 (a `string[]`) into one shape. Returns `[]` when no `type` keyword is present, so callers
+ * distinguish "typeless" (infer from other keywords) from "typed".
+ */
+export declare function schemaTypeList(schema: OpenApiSchema): string[];
+/** The declared non-"null" value types — what a 3.1 `type: [T, "null"]` permits as a value. */
+export declare function schemaValueTypes(schema: OpenApiSchema): string[];
+/** The first declared non-"null" value type (for single-type scalar logic), or `undefined`. */
+export declare function firstValueType(schema: OpenApiSchema): string | undefined;
+/** Whether the schema permits an explicit `null` — via OpenAPI 3.0 `nullable: true` or the 3.1
+ *  idiom `type: [..., "null"]`. */
+export declare function schemaAllowsNull(schema: OpenApiSchema): boolean;
+/** Whether the schema declares (permits) the given non-"null" value type. */
+export declare function schemaHasType(schema: OpenApiSchema, t: string): boolean;
 /**
  * Whether a schema describes an object shape. OpenAPI/JSON-Schema let the `type`
  * keyword be omitted when `properties`/`required`/`additionalProperties` already imply

package/dist/openapi/spec.js

@@ -8,9 +8,38 @@
 //
 // Scope: the ADR 0058 "supported profile" — JSON bodies, path/query parameters, a JSON
 // requestBody, response codes, and a JSON-Schema subset validator (type/required/enum/numeric &
-// string bounds/pattern/array & object shape/nullable/$ref). Exotic OpenAPI (callbacks, links,
-// XML, discriminated oneOf composition) is intentionally out of scope for this slice.
+// string bounds/pattern/array & object shape/nullable/$ref). The `type` keyword is read in both
+// OpenAPI 3.0 (a single string, `nullable: true` for null) and 3.1 (a `string[]`, e.g. the
+// `type: [T, "null"]` nullable idiom or a multi-type union) dialects. Exotic OpenAPI (callbacks,
+// links, XML, discriminated oneOf composition) is intentionally out of scope for this slice.
 import { parse as parseYaml } from "yaml";
+/**
+ * The declared JSON-Schema `type`(s) as a list, normalizing OpenAPI 3.0 (a single string) and
+ * 3.1 (a `string[]`) into one shape. Returns `[]` when no `type` keyword is present, so callers
+ * distinguish "typeless" (infer from other keywords) from "typed".
+ */
+export function schemaTypeList(schema) {
+    if (schema.type === undefined)
+        return [];
+    return Array.isArray(schema.type) ? schema.type : [schema.type];
+}
+/** The declared non-"null" value types — what a 3.1 `type: [T, "null"]` permits as a value. */
+export function schemaValueTypes(schema) {
+    return schemaTypeList(schema).filter((t) => t !== "null");
+}
+/** The first declared non-"null" value type (for single-type scalar logic), or `undefined`. */
+export function firstValueType(schema) {
+    return schemaValueTypes(schema)[0];
+}
+/** Whether the schema permits an explicit `null` — via OpenAPI 3.0 `nullable: true` or the 3.1
+ *  idiom `type: [..., "null"]`. */
+export function schemaAllowsNull(schema) {
+    return schema.nullable === true || schemaTypeList(schema).includes("null");
+}
+/** Whether the schema declares (permits) the given non-"null" value type. */
+export function schemaHasType(schema, t) {
+    return schemaValueTypes(schema).includes(t);
+}
 /**
  * Whether a schema describes an object shape. OpenAPI/JSON-Schema let the `type`
  * keyword be omitted when `properties`/`required`/`additionalProperties` already imply
@@ -19,9 +48,10 @@ import { parse as parseYaml } from "yaml";
  * the emitted type calls an object is the same body the validator shape-checks.
  */
 export function isObjectSchema(schema) {
-    if (schema.type === "object")
+    const valueTypes = schemaValueTypes(schema);
+    if (valueTypes.includes("object"))
         return true;
-    if (schema.type !== undefined)
+    if (valueTypes.length > 0)
         return false;
     return (schema.properties !== undefined ||
         schema.required !== undefined ||
@@ -494,8 +524,14 @@ function matchesType(declared, value) {
         return actual === "number" || actual === "integer";
     if (declared === "integer")
         return actual === "integer";
+    if (declared === "null")
+        return value === null;
     return actual === declared;
 }
+/** Whether `value` matches any of the declared value types (a 3.1 `type` list is a union). */
+function matchesAnyType(declared, value) {
+    return declared.some((t) => matchesType(t, value));
+}
 /** Validate `value` against `schema` (resolving local $refs against `doc`), returning every issue
  *  found (empty = valid). A pragmatic JSON-Schema subset; unknown keywords are ignored. */
 export function validateValue(doc, schemaIn, value, path = "") {
@@ -505,7 +541,7 @@ export function validateValue(doc, schemaIn, value, path = "") {
     const issues = [];
     const at = path || "(root)";
     if (value === null) {
-        if (schema.nullable === true || schema.type === "null")
+        if (schemaAllowsNull(schema))
             return issues;
         // enum/const may explicitly permit null even without `nullable`.
         if (schema.enum && schema.enum.some((e) => e === null))
@@ -514,14 +550,15 @@ export function validateValue(doc, schemaIn, value, path = "") {
             return issues;
         // Otherwise null is invalid for a typed schema, an object schema (properties/required imply
         // object), or an enum/const that doesn't list null. A truly empty schema ({}) allows anything.
+        const valueTypes = schemaValueTypes(schema);
         if (schema.enum) {
             issues.push({ path: at, message: `must be one of ${JSON.stringify(schema.enum)}` });
         }
         else if (schema.const !== undefined) {
             issues.push({ path: at, message: `must equal ${JSON.stringify(schema.const)}` });
         }
-        else if (schema.type) {
-            issues.push({ path: at, message: `expected ${schema.type}, got null` });
+        else if (valueTypes.length > 0) {
+            issues.push({ path: at, message: `expected ${valueTypes.join(",")}, got null` });
         }
         else if (isObjectSchema(schema)) {
             issues.push({ path: at, message: "expected object, got null" });
@@ -550,11 +587,15 @@ export function validateValue(doc, schemaIn, value, path = "") {
             issues.push({ path: at, message: `must match exactly one schema in oneOf (matched ${matched})` });
         }
     }
-    if (schema.type && !matchesType(schema.type, value)) {
-        issues.push({ path: at, message: `expected ${schema.type}, got ${typeOfValue(value)}` });
+    // `value` is non-null here (the null branch returned above), so match against the declared value
+    // types. Use the full `type` list — not `schemaValueTypes` — so a null-only schema (`["null"]`)
+    // still rejects non-null values instead of skipping the check on an empty value-type list.
+    const declaredTypes = schemaTypeList(schema);
+    if (declaredTypes.length > 0 && !matchesAnyType(declaredTypes, value)) {
+        issues.push({ path: at, message: `expected ${declaredTypes.join(",")}, got ${typeOfValue(value)}` });
         return issues; // the shape checks below assume the declared type held
     }
-    if (schema.type === "string" && typeof value === "string") {
+    if (schemaHasType(schema, "string") && typeof value === "string") {
         if (schema.minLength !== undefined && value.length < schema.minLength) {
             issues.push({ path: at, message: `shorter than minLength ${schema.minLength}` });
         }
@@ -578,7 +619,7 @@ export function validateValue(doc, schemaIn, value, path = "") {
             }
         }
     }
-    if ((schema.type === "number" || schema.type === "integer") && typeof value === "number") {
+    if ((schemaHasType(schema, "number") || schemaHasType(schema, "integer")) && typeof value === "number") {
         // OpenAPI 3.0 uses the boolean form (`exclusiveMinimum: true` makes `minimum` exclusive);
         // JSON Schema 2020-12 (OpenAPI 3.1) uses the numeric form (`exclusiveMinimum: <number>`).
         // Support both so specs in either dialect are validated, not silently under-checked.
@@ -603,7 +644,7 @@ export function validateValue(doc, schemaIn, value, path = "") {
             issues.push({ path: at, message: `must be < ${schema.exclusiveMaximum}` });
         }
     }
-    if (schema.type === "array" && Array.isArray(value)) {
+    if (schemaHasType(schema, "array") && Array.isArray(value)) {
         if (schema.minItems !== undefined && value.length < schema.minItems) {
             issues.push({ path: at, message: `fewer than minItems ${schema.minItems}` });
         }

package/dist/runtime/adapters/deno.js

@@ -16,6 +16,7 @@ import { existsSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { resolveModulePath } from "../core/module-path.js";
+import { formatLogRecord, levelEnabled, parseLogLevel } from "../core/logger.js";
 function sqliteParams(params) {
     return params.map((param) => {
         if (param === null ||
@@ -30,13 +31,28 @@ function sqliteParams(params) {
         throw new TypeError(`unsupported SQLite parameter type: ${typeof param}`);
     });
 }
+/** Read `URBAN_LOG_LEVEL` without requiring `--allow-env`. `Deno.env.get` throws when env access is
+ *  not granted, but an app that only logs shouldn't be forced to open env permission just to emit a
+ *  line — so treat a permission (or any) error as an unset value and let logging fall back to the
+ *  default `info` level. Logging must stay safe by default. */
+function readLogLevelEnv() {
+    try {
+        return Deno.env.get("URBAN_LOG_LEVEL");
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createDenoHost(opts = {}) {
     const cwd = opts.cwd ?? Deno.cwd();
     const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
     const log = opts.log ??
         ((level, msg, fields) => {
-            const line = fields ? `${msg} ${JSON.stringify(fields)}` : msg;
-            (level === "error" ? console.error : level === "warn" ? console.warn : console.log)(`[urban] ${line}`);
+            if (!levelEnabled(level, parseLogLevel(readLogLevelEnv())))
+                return;
+            // console.* appends the newline; NDJSON stays one object per line. warn/error → stderr.
+            const line = formatLogRecord(level, msg, fields, Date.now());
+            (level === "warn" || level === "error" ? console.error : console.log)(line);
         });
     return {
         runtime: "deno",

package/dist/runtime/adapters/node.js

@@ -18,6 +18,22 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { resolveModulePath } from "../core/module-path.js";
+import { formatLogLine, levelEnabled, parseLogLevel } from "../core/logger.js";
+/**
+ * The default host log sink: NDJSON to stdout (`debug`/`info`) and stderr (`warn`/`error`), gated by
+ * a minimum level read from `URBAN_LOG_LEVEL` (default `info`) per record so a level change takes
+ * effect without a restart. Writing straight to the stream (not `console.*`) keeps one JSON object
+ * per line so downstream tooling can ingest them (the Nano host does not yet parse or surface these
+ * lines — see ADR 0061).
+ */
+function makeNdjsonLog(minLevel) {
+    return (level, msg, fields) => {
+        if (!levelEnabled(level, parseLogLevel(minLevel())))
+            return;
+        const line = formatLogLine(level, msg, fields, Date.now());
+        (level === "warn" || level === "error" ? process.stderr : process.stdout).write(line);
+    };
+}
 function sqliteParams(params) {
     return params.map((param) => {
         if (param === null ||
@@ -84,11 +100,7 @@ function ensureConnectorHooks() {
 export function createNodeHost(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
-    const log = opts.log ??
-        ((level, msg, fields) => {
-            const line = fields ? `${msg} ${JSON.stringify(fields)}` : msg;
-            (level === "error" ? console.error : level === "warn" ? console.warn : console.log)(`[urban] ${line}`);
-        });
+    const log = opts.log ?? makeNdjsonLog(() => process.env.URBAN_LOG_LEVEL);
     return {
         runtime: "node",
         env: (name) => process.env[name],

package/dist/runtime/core/context.d.ts

@@ -21,6 +21,7 @@ export interface Mounted {
     describe?(): Record<string, unknown>;
 }
 import type { DataLayer } from "./modules/datasource.ts";
+import type { Logger } from "./logger.ts";
 /**
  * The surface injected into worker/trigger/surface handlers — the app's runtime API.
  * This is how a handler reaches the datasource (typed accessors), the engine, and host
@@ -40,5 +41,13 @@ export interface AppApi {
      */
     sdk?: EngineSdkClient;
     env(name: string): string | undefined;
-    log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
+    /**
+     * Structured logger (see {@link Logger}). Callable for back-compat
+     * (`log("info", msg, fields)`), but prefer the level methods and bound context:
+     * `app.log.info(msg, fields)`, `app.log.child({ … })`. The runtime hands worker
+     * handlers a logger already bound to the job's `{ jobKey, jobType,
+     * processInstanceKey, elementId }`, and operation delegates one bound to the
+     * request's `{ method, path, operationId }`, so lines self-correlate.
+     */
+    log: Logger;
 }

package/dist/runtime/core/host.d.ts

@@ -97,8 +97,15 @@ export interface HostContext {
      * a host that cannot provide one leaves provenance capture disabled (absent-safe).
      */
     createAsyncStore?<T>(): AsyncStore<T>;
-    /** Structured log sink. */
-    log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
+    /**
+     * Structured log sink. Adds `debug` below `info`; the host adapter owns filtering + encoding.
+     *
+     * NOTE: widening this level union to include `"debug"` is a **breaking change** for any custom
+     * `HostContext` implementation whose `log` was typed with the narrower `"info" | "warn" | "error"`
+     * union — such a host must add a `"debug"` branch to keep satisfying the contract. See the
+     * "Structured logging" custom-host note in the runtime README.
+     */
+    log(level: "debug" | "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
 }
 /** A job handed to a worker handler, plus the ack/fail callbacks. `In` types the process
  *  variables carried on the job; it defaults to an open record when a handler doesn't

package/dist/runtime/core/logger.d.ts

@@ -0,0 +1,69 @@
+/** Severity of a log record, from most to least verbose. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/** A structured context bag attached to a log record. Values should be JSON-serializable. */
+export type LogFields = Record<string, unknown>;
+/**
+ * The low-level output seam a {@link Logger} writes to. The host adapter supplies it and owns
+ * encoding (NDJSON), stream routing (warn/error → stderr, else stdout) and level filtering. `fields`
+ * is the merged bag (a logger's bound context overlaid with the per-call fields).
+ */
+export type LogSink = (level: LogLevel, msg: string, fields?: LogFields) => void;
+/**
+ * The logger surface injected as `AppApi.log`. Callable for back-compat (`log(level, msg, fields)`),
+ * with per-level methods and `child()` for bound context. Prefer the methods:
+ *
+ *   app.log.info("charge captured", { amount, currency });
+ *   const jobLog = app.log.child({ orderId });   // every line below carries orderId
+ *   jobLog.warn("retrying", { attempt });
+ */
+export interface Logger {
+    /** Back-compat callable form. Prefer `log.info(...)` etc. */
+    (level: LogLevel, msg: string, fields?: LogFields): void;
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    /** A logger that merges `bindings` into every record it emits (per-call fields win on key clash). */
+    child(bindings: LogFields): Logger;
+}
+/** Levels ordered by increasing severity; the index is the numeric threshold used for filtering. */
+export declare const LOG_LEVELS: readonly LogLevel[];
+/**
+ * Parse a min-level string (e.g. from `URBAN_LOG_LEVEL`) into a {@link LogLevel}, case-insensitively,
+ * falling back to `fallback` (default `"info"`) for an absent or unrecognized value.
+ */
+export declare function parseLogLevel(value: string | undefined, fallback?: LogLevel): LogLevel;
+/** True when a record at `level` should be emitted given the configured `min` level. */
+export declare function levelEnabled(level: LogLevel, min: LogLevel): boolean;
+/** A single structured log record, as serialized to NDJSON. Reserved keys (`ts`, `level`, `msg`)
+ *  lead; the flattened `fields` follow. A field named `ts`/`level`/`msg` cannot shadow a reserved
+ *  key (the reserved value wins), so correlation on those keys stays reliable. */
+export interface LogRecord {
+    /** Epoch milliseconds when the line was emitted. */
+    ts: number;
+    level: LogLevel;
+    msg: string;
+    [field: string]: unknown;
+}
+/**
+ * Encode one structured log record as a single-line JSON string (no trailing newline). The reserved
+ * `ts`/`level`/`msg` keys are written first and cannot be overwritten by a same-named field. Values
+ * that don't survive `JSON.stringify` (a `bigint`, a circular object) are coerced so a bad field
+ * never throws in the logging hot path or corrupts the stream. The whole build+encode path is
+ * guarded (not just `JSON.stringify`), so a field whose enumeration itself throws (e.g. a getter or
+ * Proxy trap) still yields a clean fallback line. The record is a null-prototype object so an
+ * untrusted field key like `__proto__` sets a plain own property rather than tripping the magic
+ * prototype setter.
+ */
+export declare function formatLogRecord(level: LogLevel, msg: string, fields: LogFields | undefined, now: number): string;
+/** {@link formatLogRecord} plus a trailing newline — one NDJSON line for a raw stream write. */
+export declare function formatLogLine(level: LogLevel, msg: string, fields: LogFields | undefined, now: number): string;
+/**
+ * Build a {@link Logger} over `sink`, optionally pre-bound to `bindings`. The returned value is a
+ * callable object: it forwards `log(level, msg, fields)` to the sink and exposes `debug/info/warn/
+ * error` plus `child()`. `bindings` is normalized into a null-prototype object (log field keys are
+ * user-controlled, so an untrusted key like `__proto__` must not trip the magic prototype setter),
+ * and `child(more)` returns a new logger whose bindings are `bindings` merged with `more` into a
+ * fresh null-prototype object, so bound context accumulates safely down a call chain.
+ */
+export declare function createLogger(sink: LogSink, bindings?: LogFields): Logger;

package/dist/runtime/core/logger.js

@@ -0,0 +1,134 @@
+// Structured logging for Urban apps. A worker handler and an API route delegate both receive an
+// `AppApi` whose `log` is a {@link Logger}: an ergonomic, level-tagged sink that emits structured
+// records (the host serializes them as NDJSON — one JSON object per line — to stdout/stderr).
+//
+// The value proposition over a bare `console.log`:
+//   • Levels: `debug` / `info` / `warn` / `error`, each `(msg, fields?)`.
+//   • Structured fields: pass a `{ … }` bag of context alongside the message rather than
+//     string-concatenating; it lands as JSON keys a log processor can filter on.
+//   • Bound context via `child(bindings)`: the runtime hands a worker handler a logger already
+//     bound to `{ jobKey, jobType, processInstanceKey, elementId }`, and an operation delegate one
+//     bound to `{ method, path, operationId }` — so every line a handler emits carries the
+//     correlation context for free. Authors can bind more with their own `child()`.
+//
+// This module is pure (no `node:*`, no `Deno`, no `globalThis` output): it turns level+msg+fields
+// into a call on an injected {@link LogSink}. The host adapter (node.ts / deno.ts) owns the sink —
+// NDJSON encoding, the stdout/stderr split, and level filtering — so the same Logger works in every
+// runtime and is trivially unit-testable with a fake sink. Kept `node:*`-free per the ADR 0052
+// core-purity invariant (core/purity.test.ts).
+/** Levels ordered by increasing severity; the index is the numeric threshold used for filtering. */
+export const LOG_LEVELS = ["debug", "info", "warn", "error"];
+function isLogLevel(v) {
+    return v === "debug" || v === "info" || v === "warn" || v === "error";
+}
+/**
+ * Parse a min-level string (e.g. from `URBAN_LOG_LEVEL`) into a {@link LogLevel}, case-insensitively,
+ * falling back to `fallback` (default `"info"`) for an absent or unrecognized value.
+ */
+export function parseLogLevel(value, fallback = "info") {
+    const v = value?.trim().toLowerCase();
+    return isLogLevel(v) ? v : fallback;
+}
+/** True when a record at `level` should be emitted given the configured `min` level. */
+export function levelEnabled(level, min) {
+    return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(min);
+}
+/** Merge bound context with per-call fields (per-call wins), omitting the `fields` key entirely when
+ *  the result is empty so a context-free line stays `{ level, msg }` clean. Always merges into a
+ *  null-prototype object — even on the no-bindings fast path — and returns `undefined` for an empty
+ *  bag: log field keys are user-controlled, so an untrusted key like `__proto__` must set a plain own
+ *  property rather than trip the magic prototype setter a normal `{}` inherits from `Object.prototype`
+ *  (same treatment as untrusted-key dictionaries elsewhere in this repo). Normalizing here — not just
+ *  in {@link formatLogRecord} — keeps the merged bag safe for any custom {@link LogSink} that later
+ *  spreads it into a plain object. */
+function mergeFields(bindings, fields) {
+    const boundKeys = Object.keys(bindings);
+    const callKeys = fields ? Object.keys(fields) : [];
+    if (boundKeys.length === 0 && callKeys.length === 0)
+        return undefined;
+    if (boundKeys.length === 0)
+        return Object.assign(Object.create(null), fields);
+    if (callKeys.length === 0)
+        return Object.assign(Object.create(null), bindings);
+    return Object.assign(Object.create(null), bindings, fields);
+}
+/**
+ * Encode one structured log record as a single-line JSON string (no trailing newline). The reserved
+ * `ts`/`level`/`msg` keys are written first and cannot be overwritten by a same-named field. Values
+ * that don't survive `JSON.stringify` (a `bigint`, a circular object) are coerced so a bad field
+ * never throws in the logging hot path or corrupts the stream. The whole build+encode path is
+ * guarded (not just `JSON.stringify`), so a field whose enumeration itself throws (e.g. a getter or
+ * Proxy trap) still yields a clean fallback line. The record is a null-prototype object so an
+ * untrusted field key like `__proto__` sets a plain own property rather than tripping the magic
+ * prototype setter.
+ */
+export function formatLogRecord(level, msg, fields, now) {
+    try {
+        const record = Object.create(null);
+        record.ts = now;
+        record.level = level;
+        record.msg = msg;
+        if (fields) {
+            for (const [k, v] of Object.entries(fields)) {
+                if (k === "ts" || k === "level" || k === "msg")
+                    continue;
+                record[k] = v;
+            }
+        }
+        return JSON.stringify(record, (_key, value) => (typeof value === "bigint" ? value.toString() : value));
+    }
+    catch {
+        // A field that can't be built or serialized (circular ref, throwing getter) must not break logging.
+        return JSON.stringify({ ts: now, level, msg, fieldsError: "unserializable log fields" });
+    }
+}
+/** {@link formatLogRecord} plus a trailing newline — one NDJSON line for a raw stream write. */
+export function formatLogLine(level, msg, fields, now) {
+    return `${formatLogRecord(level, msg, fields, now)}\n`;
+}
+/**
+ * Build a {@link Logger} over `sink`, optionally pre-bound to `bindings`. The returned value is a
+ * callable object: it forwards `log(level, msg, fields)` to the sink and exposes `debug/info/warn/
+ * error` plus `child()`. `bindings` is normalized into a null-prototype object (log field keys are
+ * user-controlled, so an untrusted key like `__proto__` must not trip the magic prototype setter),
+ * and `child(more)` returns a new logger whose bindings are `bindings` merged with `more` into a
+ * fresh null-prototype object, so bound context accumulates safely down a call chain.
+ */
+export function createLogger(sink, bindings = {}) {
+    const bound = Object.assign(Object.create(null), bindings);
+    const emit = (level, msg, fields) => {
+        try {
+            sink(level, msg, mergeFields(bound, fields));
+        }
+        catch {
+            // A log call must never throw into its caller. A hostile `fields` object (e.g. a Proxy whose
+            // `ownKeys` trap throws, defeating mergeFields before the sink's own formatLogRecord guard)
+            // or a throwing sink degrades to a best-effort, field-free line rather than break the handler.
+            try {
+                sink(level, msg, Object.assign(Object.create(null), { fieldsError: "unmergeable log fields" }));
+            }
+            catch {
+                // The sink itself is broken — nothing more we can safely do without re-throwing.
+            }
+        }
+    };
+    return Object.assign(emit, {
+        debug: (msg, fields) => emit("debug", msg, fields),
+        info: (msg, fields) => emit("info", msg, fields),
+        warn: (msg, fields) => emit("warn", msg, fields),
+        error: (msg, fields) => emit("error", msg, fields),
+        child: (more) => {
+            // child() must not throw even when `more` is hostile (e.g. a Proxy whose key enumeration
+            // throws), mirroring emit()'s "logging never throws" guarantee: degrade to a child bound to
+            // just the parent context rather than let the merge bubble into the worker/route handler.
+            let childBindings = bound;
+            try {
+                childBindings = Object.assign(Object.create(null), bound, more);
+            }
+            catch {
+                // `more` could not be enumerated/merged — keep the parent bindings, drop the bad additions.
+            }
+            return createLogger(sink, childBindings);
+        },
+    });
+}

package/dist/runtime/core/modules/api.js

@@ -15,7 +15,7 @@ import { errorMessage } from "../guards.js";
 import { MODULE_EXTENSION_CANDIDATES } from "../module-path.js";
 import { html, json, normalizeRoutePath } from "../router.js";
 import { resolveAppPath } from "./datasource.js";
-import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, responseSchemaForStatus, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
+import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, responseSchemaForStatus, schemaHasType, schemaValueTypes, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
@@ -146,28 +146,36 @@ function coerceParam(doc, schema, raw) {
     const s = resolveSchema(doc, schema);
     if (!s)
         return raw;
-    // Effective scalar type: the explicit `type`, else inferred from a typeless `const`/`enum` whose
-    // values are all numbers or all booleans. Without this, a typeless numeric/boolean const/enum
-    // param (whose generated type is a number/boolean literal) could never be satisfied by the wire
-    // string — every request would 400 against a type the runtime otherwise never produces.
-    let t = s.type;
-    if (t === undefined) {
+    // Which value types the schema permits coercion into: the explicit `type`(s), else inferred from a
+    // typeless `const`/`enum` whose values are all numbers or all booleans. Without the inference, a
+    // typeless numeric/boolean const/enum param (whose generated type is a number/boolean literal)
+    // could never be satisfied by the wire string — every request would 400 against a type the runtime
+    // otherwise never produces.
+    let valueTypes = schemaValueTypes(s);
+    if (valueTypes.length === 0) {
         if (typeof s.const === "number")
-            t = "number";
+            valueTypes = ["number"];
         else if (typeof s.const === "boolean")
-            t = "boolean";
+            valueTypes = ["boolean"];
         else if (Array.isArray(s.enum) && s.enum.length > 0) {
             if (s.enum.every((v) => typeof v === "number"))
-                t = "number";
+                valueTypes = ["number"];
             else if (s.enum.every((v) => typeof v === "boolean"))
-                t = "boolean";
+                valueTypes = ["boolean"];
         }
     }
-    if (t === "integer" || t === "number") {
+    // Coerce order-independently for OpenAPI 3.1 multi-type unions: a schema that *allows* number or
+    // boolean gets that coercion attempted regardless of where it sits in the `type` array (so
+    // `["string","integer"]` and `["integer","string"]` behave identically). Each attempt falls back
+    // to the raw string when it doesn't parse, preserving a value that only fits the union's `string`
+    // arm. Number is tried before boolean so a numeric-looking value in a `number|boolean` union
+    // becomes a number (`"true"`/`"false"` aren't numeric, so they still reach the boolean arm).
+    if (valueTypes.includes("integer") || valueTypes.includes("number")) {
         const n = Number(raw);
-        return raw.trim() !== "" && !Number.isNaN(n) ? n : raw;
+        if (raw.trim() !== "" && !Number.isNaN(n))
+            return n;
     }
-    if (t === "boolean") {
+    if (valueTypes.includes("boolean")) {
         if (raw === "true")
             return true;
         if (raw === "false")
@@ -438,7 +446,7 @@ export function mountApi(ctx, app) {
                         continue;
                     const values = Array.isArray(val) ? val : [val];
                     const ps = resolveSchema(d, p.schema);
-                    if (ps?.type === "array") {
+                    if (ps && schemaHasType(ps, "array")) {
                         // Repeated keys (?tag=a&tag=b) form the array; coerce + validate each item, then the
                         // whole array against the schema's array constraints (minItems, items, ...). The coerced
                         // array is what the delegate receives.
@@ -507,8 +515,14 @@ export function mountApi(ctx, app) {
         // required), so pass `undefined` to those handlers rather than leaking a parsed value through
         // a body-less type.
         const handlerBody = op.requestBodySchema !== undefined || op.requestBodyRequired ? body : undefined;
+        // Hand the delegate an AppApi whose `log` is bound to this request's correlation context, so its
+        // lines self-tag with `{ method, path, operationId }` without the author threading it.
+        const requestApp = {
+            ...app,
+            log: app.log.child({ method, path: op.path, operationId: op.operationId }),
+        };
         try {
-            const result = await handler({ req, params: coercedParams, query: coercedQuery, body: handlerBody }, app);
+            const result = await handler({ req, params: coercedParams, query: coercedQuery, body: handlerBody }, requestApp);
             if (!result)
                 return { status: 204 };
             const status = result.status ?? 200;