@nanobpm/urban 0.39.0 → 0.40.1

package/src/runtime/core/logger.test.ts

@@ -0,0 +1,221 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  createLogger,
+  formatLogLine,
+  formatLogRecord,
+  levelEnabled,
+  LOG_LEVELS,
+  parseLogLevel,
+  type LogFields,
+  type LogLevel,
+} from "./logger.ts";
+
+type Rec = { level: LogLevel; msg: string; fields?: LogFields };
+
+function recorder() {
+  const records: Rec[] = [];
+  const sink = (level: LogLevel, msg: string, fields?: LogFields) => {
+    records.push({ level, msg, fields });
+  };
+  return { records, sink };
+}
+
+test("per-level methods forward the level and message to the sink", () => {
+  const { records, sink } = recorder();
+  const log = createLogger(sink);
+  log.debug("d");
+  log.info("i");
+  log.warn("w");
+  log.error("e");
+  assert.deepEqual(
+    records.map((r) => [r.level, r.msg]),
+    [
+      ["debug", "d"],
+      ["info", "i"],
+      ["warn", "w"],
+      ["error", "e"],
+    ],
+  );
+});
+
+test("the callable form still works for back-compat", () => {
+  const { records, sink } = recorder();
+  const log = createLogger(sink);
+  log("info", "hello", { a: 1 });
+  assert.equal(records.length, 1);
+  assert.equal(records[0].level, "info");
+  assert.equal(records[0].msg, "hello");
+  assert.deepEqual({ ...records[0].fields }, { a: 1 });
+});
+
+test("a context-free line carries no fields object", () => {
+  const { records, sink } = recorder();
+  createLogger(sink).info("plain");
+  assert.deepEqual(records, [{ level: "info", msg: "plain", fields: undefined }]);
+});
+
+test("child() bindings are merged into every record", () => {
+  const { records, sink } = recorder();
+  const log = createLogger(sink).child({ jobType: "charge", jobKey: "7" });
+  log.info("started");
+  log.warn("retrying", { attempt: 2 });
+  assert.deepEqual({ ...records[0].fields }, { jobType: "charge", jobKey: "7" });
+  assert.deepEqual({ ...records[1].fields }, { jobType: "charge", jobKey: "7", attempt: 2 });
+});
+
+test("per-call fields win over bound context on key clash", () => {
+  const { records, sink } = recorder();
+  createLogger(sink).child({ attempt: 1 }).info("x", { attempt: 9 });
+  assert.deepEqual({ ...records[0].fields }, { attempt: 9 });
+});
+
+test("child() accumulates bindings down a chain and does not mutate the parent", () => {
+  const { records, sink } = recorder();
+  const base = createLogger(sink).child({ app: "demo" });
+  const child = base.child({ jobKey: "1" });
+  base.info("base");
+  child.info("child");
+  assert.deepEqual({ ...records[0].fields }, { app: "demo" });
+  assert.deepEqual({ ...records[1].fields }, { app: "demo", jobKey: "1" });
+});
+
+test("parseLogLevel is case-insensitive and falls back for unknown/absent input", () => {
+  assert.equal(parseLogLevel("DEBUG"), "debug");
+  assert.equal(parseLogLevel("  Warn "), "warn");
+  assert.equal(parseLogLevel(undefined), "info");
+  assert.equal(parseLogLevel("verbose"), "info");
+  assert.equal(parseLogLevel("verbose", "debug"), "debug");
+});
+
+test("levelEnabled gates records below the configured minimum", () => {
+  assert.equal(levelEnabled("debug", "info"), false);
+  assert.equal(levelEnabled("info", "info"), true);
+  assert.equal(levelEnabled("error", "warn"), true);
+  assert.equal(levelEnabled("warn", "error"), false);
+});
+
+test("LOG_LEVELS is ordered from most to least verbose", () => {
+  assert.deepEqual([...LOG_LEVELS], ["debug", "info", "warn", "error"]);
+});
+
+test("formatLogRecord emits ts/level/msg plus flattened fields", () => {
+  const rec = JSON.parse(formatLogRecord("info", "charged", { amount: 10, currency: "EUR" }, 1234));
+  assert.deepEqual(rec, { ts: 1234, level: "info", msg: "charged", amount: 10, currency: "EUR" });
+});
+
+test("formatLogLine appends exactly one trailing newline", () => {
+  const line = formatLogLine("warn", "x", undefined, 1);
+  assert.ok(line.endsWith("\n"));
+  assert.equal(line.indexOf("\n"), line.length - 1);
+  assert.deepEqual(JSON.parse(line), { ts: 1, level: "warn", msg: "x" });
+});
+
+test("formatLogRecord reserves ts/level/msg — a same-named field cannot shadow them", () => {
+  const rec = JSON.parse(formatLogRecord("error", "real", { ts: 0, level: "info", msg: "fake", ok: true }, 999));
+  assert.deepEqual(rec, { ts: 999, level: "error", msg: "real", ok: true });
+});
+
+test("formatLogRecord serializes a bigint field as its string form", () => {
+  const rec = JSON.parse(formatLogRecord("info", "job", { jobKey: 9007199254740993n }, 5));
+  assert.equal(rec.jobKey, "9007199254740993");
+});
+
+test("formatLogRecord never throws on an unserializable (circular) field", () => {
+  const circular: Record<string, unknown> = {};
+  circular.self = circular;
+  const rec = JSON.parse(formatLogRecord("info", "loop", { circular }, 7));
+  assert.deepEqual(rec, { ts: 7, level: "info", msg: "loop", fieldsError: "unserializable log fields" });
+});
+
+test("formatLogRecord never throws when enumerating a field throws (getter/proxy trap)", () => {
+  const hostile = new Proxy(
+    {},
+    {
+      ownKeys() {
+        throw new Error("trap");
+      },
+    },
+  );
+  const rec = JSON.parse(formatLogRecord("warn", "boom", hostile, 8));
+  assert.deepEqual(rec, { ts: 8, level: "warn", msg: "boom", fieldsError: "unserializable log fields" });
+});
+
+test("formatLogRecord writes an untrusted __proto__ field key as a plain own property", () => {
+  // JSON.parse builds a genuine own "__proto__" property (unlike the `{ __proto__: … }` literal,
+  // which sets the prototype) — the untrusted-key case the null-prototype record must survive.
+  const fields: LogFields = JSON.parse('{"__proto__":{"polluted":true}}');
+  const rec = JSON.parse(formatLogRecord("info", "hardened", fields, 3));
+  assert.equal(rec.ts, 3);
+  assert.equal(rec.msg, "hardened");
+  assert.deepEqual(Object.getOwnPropertyDescriptor(rec, "__proto__")?.value, { polluted: true });
+});
+
+test("child() with an untrusted __proto__ binding key does not pollute Object.prototype", () => {
+  const { records, sink } = recorder();
+  const bindings: LogFields = JSON.parse('{"__proto__":{"polluted":true}}');
+  createLogger(sink).child(bindings).info("x");
+  const fields = records[0].fields ?? {};
+  assert.deepEqual(Object.getOwnPropertyDescriptor(fields, "__proto__")?.value, { polluted: true });
+});
+
+test("an untrusted __proto__ per-call field with no bound context still merges into a null-proto bag", () => {
+  // The no-bindings merge path must normalize too, so a custom sink that later spreads the bag can't
+  // be tripped by the magic prototype setter. JSON.parse builds a genuine own "__proto__" key.
+  const { records, sink } = recorder();
+  const fields: LogFields = JSON.parse('{"__proto__":{"polluted":true}}');
+  createLogger(sink).info("x", fields);
+  const merged = records[0].fields;
+  assert.ok(merged !== undefined);
+  assert.equal(Object.getPrototypeOf(merged), null);
+  assert.deepEqual(Object.getOwnPropertyDescriptor(merged, "__proto__")?.value, { polluted: true });
+});
+
+test("a log call never throws when a hostile fields object defeats the merge", () => {
+  // A Proxy whose ownKeys trap throws breaks mergeFields before it can reach the sink; the emit guard
+  // must degrade to a field-free error line rather than propagate into the caller.
+  const { records, sink } = recorder();
+  const hostile = new Proxy(
+    {},
+    {
+      ownKeys() {
+        throw new Error("trap");
+      },
+    },
+  );
+  assert.doesNotThrow(() => createLogger(sink).info("boom", hostile));
+  assert.equal(records.length, 1);
+  assert.equal(records[0].msg, "boom");
+  assert.deepEqual({ ...records[0].fields }, { fieldsError: "unmergeable log fields" });
+});
+
+test("a log call never throws when the sink itself throws", () => {
+  const throwingSink = () => {
+    throw new Error("sink down");
+  };
+  assert.doesNotThrow(() => createLogger(throwingSink).info("x", { a: 1 }));
+});
+
+test("child() never throws when the added bindings are hostile — degrades to the parent context", () => {
+  // A Proxy whose ownKeys trap throws would break the Object.assign merge in child(); like emit(),
+  // child() must not propagate into the caller. It degrades to a child bound to just the parent
+  // context, and that child still logs normally with its inherited bindings.
+  const { records, sink } = recorder();
+  const hostile = new Proxy(
+    {},
+    {
+      ownKeys() {
+        throw new Error("trap");
+      },
+    },
+  );
+  const parent = createLogger(sink).child({ orderId: "o1" });
+  let child: ReturnType<typeof parent.child> | undefined;
+  assert.doesNotThrow(() => {
+    child = parent.child(hostile);
+  });
+  child?.info("shipped");
+  assert.equal(records.length, 1);
+  assert.equal(records[0].msg, "shipped");
+  assert.deepEqual({ ...records[0].fields }, { orderId: "o1" });
+});

package/src/runtime/core/logger.ts

@@ -0,0 +1,177 @@
+// 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).
+
+/** 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 const LOG_LEVELS: readonly LogLevel[] = ["debug", "info", "warn", "error"];
+
+function isLogLevel(v: unknown): v is LogLevel {
+  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: string | undefined, fallback: LogLevel = "info"): LogLevel {
+  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: LogLevel, min: LogLevel): boolean {
+  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: LogFields, fields?: LogFields): LogFields | undefined {
+  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);
+}
+
+/** 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 function formatLogRecord(level: LogLevel, msg: string, fields: LogFields | undefined, now: number): string {
+  try {
+    const record: LogRecord = 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: LogLevel, msg: string, fields: LogFields | undefined, now: number): string {
+  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: LogSink, bindings: LogFields = {}): Logger {
+  const bound: LogFields = Object.assign(Object.create(null), bindings);
+  const emit = (level: LogLevel, msg: string, fields?: LogFields): void => {
+    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: string, fields?: LogFields) => emit("debug", msg, fields),
+    info: (msg: string, fields?: LogFields) => emit("info", msg, fields),
+    warn: (msg: string, fields?: LogFields) => emit("warn", msg, fields),
+    error: (msg: string, fields?: LogFields) => emit("error", msg, fields),
+    child: (more: LogFields) => {
+      // 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: LogFields = 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/src/runtime/core/modules/actions.test.ts

@@ -1,4 +1,5 @@
 import { test } from "node:test";
+import { createLogger } from "../logger.ts";
 import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineClient, HostContext, HttpRequest } from "../host.ts";
@@ -42,7 +43,7 @@ function appFixture(over: Partial<AppApi> = {}): AppApi {
     data,
     engine,
     env: () => undefined,
-    log: () => {},
+    log: createLogger(() => {}),
     ...over,
   };
 }

package/src/runtime/core/modules/api.test.ts

@@ -1,4 +1,5 @@
 import { test } from "node:test";
+import { createLogger } from "../logger.ts";
 import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { AppManifest } from "../manifest.ts";
@@ -36,7 +37,7 @@ const engine: EngineClient = {
 const data = new DataLayer(new Map(), undefined, {});
 
 function appFixture(): AppApi {
-  return { manifest: { schemaVersion: 1, id: "t", name: "T" }, data, engine, env: () => undefined, log: () => {} };
+  return { manifest: { schemaVersion: 1, id: "t", name: "T" }, data, engine, env: () => undefined, log: createLogger(() => {}) };
 }
 
 const spec = JSON.stringify({
@@ -88,6 +89,7 @@ function build(
   specText = spec,
   env: (v: string) => string | undefined = () => undefined,
   existsPaths: string[] = [],
+  app: AppApi = appFixture(),
 ): Built {
   const imported: string[] = [];
   const logs: Array<{ level: string; msg: string }> = [];
@@ -114,7 +116,7 @@ function build(
   const manifest: AppManifest = { schemaVersion: 1, id: "t", name: "T" };
   if (api) Reflect.set(manifest, "api", api);
   const ctx: RuntimeContext = { root: "/app", manifest, engine, host };
-  const handle = mountApi(ctx, appFixture());
+  const handle = mountApi(ctx, app);
   const router = makeRouter(handle.routes);
   return { router: (r) => Promise.resolve(router(r)), imported, logs, handle };
 }
@@ -137,6 +139,40 @@ test("no api binding → no routes (no-op for actions-only apps)", () => {
   return router(req("GET", "/app/api/invoices/1")).then((res) => assert.equal(res.status, 404));
 });
 
+test("a delegate's app.log is bound to the request's correlation context", async () => {
+  const captured: Array<{ level: string; msg: string; fields?: Record<string, unknown> }> = [];
+  const capturingApp: AppApi = {
+    manifest: { schemaVersion: 1, id: "t", name: "T" },
+    data,
+    engine,
+    env: () => undefined,
+    log: createLogger((level, msg, fields) => {
+      captured.push({ level, msg, fields });
+    }),
+  };
+  const handler: OperationHandler = (_input, app) => {
+    app.log.info("creating invoice", { amount: 5 });
+    return { status: 201, body: { id: "i1", amount: 5 } };
+  };
+  const { router } = build(
+    { spec: "openapi.json", dir: "operations" },
+    { "/app/operations/createInvoice": { default: handler } },
+    spec,
+    () => undefined,
+    [],
+    capturingApp,
+  );
+  const res = await router(req("POST", "/app/api/invoices", { body: JSON.stringify({ id: "i1", amount: 5 }) }));
+  assert.equal(res.status, 201);
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].level, "info");
+  assert.equal(captured[0].msg, "creating invoice");
+  assert.deepEqual(
+    { ...captured[0].fields },
+    { method: "POST", path: "/invoices", operationId: "createInvoice", amount: 5 },
+  );
+});
+
 test("routes an operation to its delegate with validated params + body", async () => {
   const seen: unknown[] = [];
   const handler: OperationHandler = (input) => {
@@ -421,6 +457,87 @@ test("params/query are coerced to their schema type before reaching the delegate
   assert.deepEqual(got, { params: { id: 42 }, query: { verbose: true, tags: ["x", "y"] } });
 });
 
+test("3.1 nullable-typed params still coerce (type: [T, null]) and array-typed repeats still group", async () => {
+  // A param declared with the OpenAPI 3.1 nullable idiom must coerce on its value type exactly like
+  // the 3.0 single-type form — otherwise a `type: ["integer","null"]` query would reach the delegate
+  // as a raw string (and an array-typed nullable would reject repeats).
+  const spec = JSON.stringify({
+    openapi: "3.1.0",
+    paths: {
+      "/things/{id}": {
+        get: {
+          operationId: "getThing",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: ["integer", "null"] } },
+            { name: "tags", in: "query", schema: { type: ["array", "null"], items: { type: "string" } } },
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  let got: { params: Record<string, unknown>; query: Record<string, unknown> } | undefined;
+  const { router } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/operations/getThing": {
+        default: (i: { params: Record<string, unknown>; query: Record<string, unknown> }) => {
+          got = { params: i.params, query: i.query };
+          return { body: { ok: true } };
+        },
+      },
+    },
+    spec,
+  );
+  const res = await router(req("GET", "/app/api/things/7", { query: "tags=x&tags=y" }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(got, { params: { id: 7 }, query: { tags: ["x", "y"] } });
+});
+
+test("3.1 multi-type union params coerce order-independently (type array order doesn't matter)", async () => {
+  // A 3.1 union like `["string","integer"]` must coerce numeric-looking values to numbers regardless
+  // of where `integer`/`number` sits in the array — otherwise coercion is order-dependent and a
+  // `["string","integer"]` param would never enforce numeric bounds (it'd reach the delegate as a
+  // raw string), while `["integer","string"]` would. Non-numeric values still fall back to the
+  // string arm, and a `number|boolean` union coerces each token to its natural type.
+  const spec = JSON.stringify({
+    openapi: "3.1.0",
+    paths: {
+      "/u": {
+        get: {
+          operationId: "u",
+          parameters: [
+            { name: "a", in: "query", required: true, schema: { type: ["string", "integer"] } },
+            { name: "b", in: "query", required: true, schema: { type: ["integer", "string"] } },
+            { name: "c", in: "query", required: true, schema: { type: ["string", "integer"] } },
+            { name: "d", in: "query", required: true, schema: { type: ["number", "boolean"] } },
+            { name: "e", in: "query", required: true, schema: { type: ["number", "boolean"] } },
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  let got: { query: Record<string, unknown> } | undefined;
+  const { router } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/operations/u": {
+        default: (i: { query: Record<string, unknown> }) => {
+          got = { query: i.query };
+          return { body: { ok: true } };
+        },
+      },
+    },
+    spec,
+  );
+  const res = await router(req("GET", "/app/api/u", { query: "a=42&b=42&c=hello&d=3.5&e=true" }));
+  assert.equal(res.status, 200);
+  // a and b both coerce to 42 despite opposite type-array order; c stays a string (only fits the
+  // union's string arm); d coerces to a number, e to a boolean.
+  assert.deepEqual(got, { query: { a: 42, b: 42, c: "hello", d: 3.5, e: true } });
+});
+
 test("a typeless numeric const/enum query param coerces (so its number-literal type is satisfiable)", async () => {
   const enumSpec = JSON.stringify({
     openapi: "3.1.0",

package/src/runtime/core/modules/api.ts

@@ -29,6 +29,8 @@ import {
   parseSpec,
   resolveSchema,
   responseSchemaForStatus,
+  schemaHasType,
+  schemaValueTypes,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -249,24 +251,31 @@ export function apiDocsPath(manifest: unknown): string | undefined {
 function coerceParam(doc: OpenApiDoc, schema: OpenApiSchema | undefined, raw: string): unknown {
   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) {
-    if (typeof s.const === "number") t = "number";
-    else if (typeof s.const === "boolean") t = "boolean";
+  // 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") valueTypes = ["number"];
+    else if (typeof s.const === "boolean") valueTypes = ["boolean"];
     else if (Array.isArray(s.enum) && s.enum.length > 0) {
-      if (s.enum.every((v) => typeof v === "number")) t = "number";
-      else if (s.enum.every((v) => typeof v === "boolean")) t = "boolean";
+      if (s.enum.every((v) => typeof v === "number")) valueTypes = ["number"];
+      else if (s.enum.every((v) => typeof v === "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") return false;
   }
@@ -571,7 +580,7 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
           if (!p.schema) 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.
@@ -640,8 +649,17 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
     // 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: AppApi = {
+      ...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;
       // Optional response validation (dev by default): warn-only, never blocks the response.