@nanobpm/urban 0.38.0 → 0.40.0

package/dist/toolkit/gen.js

@@ -2,7 +2,7 @@
 // models, runs the pure derivers, and either writes the artifacts to disk (`urban gen`) or
 // compares them against what's on disk and reports drift (`urban gen --check`). The derivers stay
 // pure; all IO is confined here behind a tiny FS port so the same code runs on Node and Deno.
-import { isAbsolutePath, sortArtifacts } from "./artifact.js";
+import { GENERATED_DIR, isAbsolutePath, RUNTIME_MATERIALIZED_ARTIFACTS, sortArtifacts } from "./artifact.js";
 import { deriveMigrations } from "./derivers/migrations.js";
 import { deriveDomain } from "./derivers/domain.js";
 import { deriveWorkerBindings } from "./derivers/worker-io.js";
@@ -138,7 +138,29 @@ export async function runGen(opts) {
                 await io.remove(join(root, rel));
         }
     }
-    return { artifacts, drift, incomplete: derived.incomplete, modelErrors: derived.errors };
+    // Stale-artifact sweep of `nano-generated/` (clean break, nano-bpm#: gen owns its output dir).
+    // The dir is gitignored and fully codegen-owned, so any file this run did not (re)write is stale
+    // from a prior gen — a renamed or removed artifact (e.g. an old `data_sdk.ts`) whose orphan the
+    // app might still import. Remove it. The one exception is the runtime-materialized set: the SDK
+    // shims + the `urban data`/console dataops wrappers gen does NOT emit but the app needs at runtime
+    // (RUNTIME_MATERIALIZED_ARTIFACTS). Protect those by name. Write mode only; skipped when io.remove
+    // is absent (the sweep is best-effort, mirroring the `.bpmn` sweep above). NOT on `modelsOnly`
+    // (`urban derive`): that path derives only models, so `artifacts` carries no `nano-generated/*` and
+    // sweeping would wrongly wipe the type-contract outputs a prior `urban gen` wrote.
+    const swept = [];
+    if (!opts.check && !opts.modelsOnly && !derived.incomplete && io.remove) {
+        const keep = new Set(artifacts.map((a) => a.path).filter((p) => p.startsWith(`${GENERATED_DIR}/`)));
+        for (const name of RUNTIME_MATERIALIZED_ARTIFACTS)
+            keep.add(`${GENERATED_DIR}/${name}`);
+        for (const name of await io.listDir(join(root, GENERATED_DIR))) {
+            const rel = `${GENERATED_DIR}/${name}`;
+            if (keep.has(rel))
+                continue;
+            await io.remove(join(root, rel));
+            swept.push(rel);
+        }
+    }
+    return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors };
 }
 export { dirOf, join as joinPath };
 /** Derive code-first models in-memory (no writes) — backs `urban derive --stdout`, the

package/dist/toolkit/scaffold/operations.js

@@ -35,7 +35,9 @@ export function renderOperationStub(operationId, dir = DEFAULT_OPERATIONS_DIR) {
         `\n` +
         `export default defineOperation(${key}, async (input, app) => {\n` +
         `  // \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
-        `  // through the injected \`app\` API. Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
+        `  // through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
+        `  // auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
+        `  // Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
         `  throw new NotImplemented(${key});\n` +
         `});\n`);
 }

package/dist/toolkit/scaffold/workers.js

@@ -50,6 +50,8 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
         varsNote +
         `\n` +
         `  // Reach app state and services through the injected \`app\` API.\n` +
+        `  // Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
+        `  // { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
         `  throw new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
         `};\n` +
         `\n` +

package/dist/worker.d.ts

@@ -1,3 +1,4 @@
 export type { AppJobHandler } from "./runtime/core/modules/workers.ts";
 export type { EngineJob, JobHandler } from "./runtime/core/host.ts";
 export type { AppApi } from "./runtime/core/context.ts";
+export type { Logger, LogLevel, LogFields } from "./runtime/core/logger.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.38.0",
+	"version": "0.40.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -66,7 +66,7 @@
 		"@nanobpm/nano-sdk": "^1.2.3",
 		"@nanobpm/workflow": "^0.8.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.9.0",
+		"create-urban-app": "^0.12.0",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

package/src/cli.ts

@@ -171,6 +171,12 @@ async function cmdGen(f: Flags): Promise<number> {
   console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
   for (const a of res.artifacts) console.log(`  • ${a.path}`);
 
+  // Stale generated files removed from nano-generated/ (renamed/removed artifacts from a prior gen).
+  if (res.swept.length > 0) {
+    console.log(`✔ removed ${res.swept.length} stale generated file(s):`);
+    for (const p of res.swept) console.log(`  - ${p}`);
+  }
+
   // Write-once handler stubs scaffolded as part of generation (workers from the model, operation
   // delegates from the OpenAPI spec). Existing, human-owned stubs are kept verbatim.
   const created = [

package/src/runtime/adapters/deno.ts

@@ -17,6 +17,7 @@ import type {
   SqliteDb,
 } from "../core/host.ts";
 import { resolveModulePath } from "../core/module-path.ts";
+import { formatLogRecord, levelEnabled, parseLogLevel } from "../core/logger.ts";
 
 type SqliteParam = string | number | bigint | Uint8Array | null;
 
@@ -64,16 +65,28 @@ export interface DenoHostOptions {
   importNonce?: string;
 }
 
+/** 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(): string | undefined {
+  try {
+    return Deno.env.get("URBAN_LOG_LEVEL");
+  } catch {
+    return undefined;
+  }
+}
+
 export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
   const cwd = opts.cwd ?? Deno.cwd();
   const abs = (p: string) => (isAbsolute(p) ? p : resolve(cwd, p));
   const log: HostContext["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 {

package/src/runtime/adapters/node.ts

@@ -20,6 +20,22 @@ import type {
   WatchHandle,
 } from "../core/host.ts";
 import { resolveModulePath } from "../core/module-path.ts";
+import { formatLogLine, levelEnabled, parseLogLevel } from "../core/logger.ts";
+
+/**
+ * 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: () => string | undefined): HostContext["log"] {
+  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);
+  };
+}
 
 type SqliteParam = string | number | bigint | Uint8Array | null;
 
@@ -106,13 +122,7 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
   const cwd = opts.cwd ?? process.cwd();
   const abs = (p: string) => (isAbsolute(p) ? p : resolve(cwd, p));
   const log: HostContext["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}`,
-      );
-    });
+    opts.log ?? makeNdjsonLog(() => process.env.URBAN_LOG_LEVEL);
 
   return {
     runtime: "node",

package/src/runtime/core/context.ts

@@ -25,6 +25,7 @@ export interface Mounted {
 
 // AppApi is imported lazily to avoid a cycle; declared here as the injected handler surface.
 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.
@@ -45,5 +46,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/src/runtime/core/host.ts

@@ -106,8 +106,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

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,
   };
 }