@nanobpm/urban 0.39.0 → 0.40.0

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/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

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

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

@@ -560,7 +560,36 @@ function applyTheme(msg) {
     }
   }
 }
-if (window.parent && window.parent !== window) {
+// True when this app runs inside the Nano console's same-origin iframe (vs a
+// standalone CLI run). Gates the theme bridge below AND in-host link navigation:
+// embedded, a processExplorer link routes the console in place; standalone, the
+// link keeps its native new-window behavior. The same-origin probe matters: a
+// cross-origin framer is also window.parent, but postMessage to our own origin
+// would never reach it and hostNavigate would still preventDefault the link —
+// so a cross-origin embed must fall through to the native _blank anchor. Reading
+// parent.location.origin throws under the same-origin policy for a cross-origin
+// parent, so the try/catch is the origin gate.
+const NANO_EMBEDDED = (() => {
+  if (!window.parent || window.parent === window) return false;
+  try {
+    return window.parent.location.origin === window.location.origin;
+  } catch {
+    return false;
+  }
+})();
+
+// Ask the framing console to navigate in-host. Returns true when a message was
+// posted (embedded) so the caller can suppress the native anchor; false
+// standalone so it falls through to the new-window <a>. The payload is
+// structured (target + params), never a raw href — the console constructs its
+// own route, so app/row data can't smuggle a path or scheme across the boundary.
+function hostNavigate(target, params) {
+  if (!NANO_EMBEDDED) return false;
+  window.parent.postMessage({ type: "nano-navigate", target: target, params: params }, window.location.origin);
+  return true;
+}
+
+if (NANO_EMBEDDED) {
   window.addEventListener("message", (ev) => {
     // Same-origin proxy (posture A): only trust a message from the framing
     // parent AND from our own origin. ev.source alone is insufficient — a
@@ -675,8 +704,12 @@ function renderText(node) {
 //      non-empty key (after trimming surrounding whitespace) produces a link.
 //      Unknown link kinds fall back to plain text so an unrecognised schema
 //      can't render a broken anchor.
-// Both open in a new tab with rel=noopener noreferrer so the opened page can't
-// reach window.opener. Shared by the top-level grid and child grids.
+// The external linkField anchor always opens in a new tab (rel=noopener
+// noreferrer). The processExplorer anchor does too when the app runs
+// standalone, but when embedded in the console a plain click instead routes the
+// host's own explorer view in place via the nano-navigate postMessage bridge
+// (a modified/middle click keeps the new-tab behavior). Shared by the top-level
+// grid and child grids.
 function gridCell(col, row) {
   const text = row[col.field] == null ? "" : String(row[col.field]);
   if (col.linkField) {
@@ -697,7 +730,22 @@ function gridCell(col, row) {
       return el(
         "td",
         {},
-        el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text),
+        el("a", {
+          class: "pc-link",
+          href,
+          target: "_blank",
+          rel: "noopener noreferrer",
+          // Embedded in the console a plain primary click routes the host's
+          // explorer in place (via the nano-navigate bridge) instead of opening
+          // a new window. A non-primary button (middle/right = new-tab/context
+          // intent), a modified click (⌘/ctrl/shift/alt = new-tab intent) and
+          // any standalone run fall through to the native anchor above.
+          onclick: (ev) => {
+            if (ev.button !== 0) return;
+            if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
+            if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
+          },
+        }, text),
       );
     }
   }

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

@@ -33,6 +33,21 @@ function hasDecisionCapableSdk(sdk) {
 function isAppJobHandler(value) {
     return typeof value === "function";
 }
+/**
+ * Hand a handler an {@link AppApi} whose `log` is bound to the job's correlation context, so every
+ * line the handler emits self-tags with `{ jobKey, jobType, processInstanceKey, elementId }` without
+ * the author threading it. Undefined fields (e.g. a job dispatched without an instance) are omitted
+ * so the bound context stays clean. The rest of the API is shared by reference — only `log` is
+ * per-job.
+ */
+function withJobLog(app, job) {
+    const bindings = { jobKey: job.jobKey, jobType: job.jobType };
+    if (job.processInstanceKey !== undefined)
+        bindings.processInstanceKey = job.processInstanceKey;
+    if (job.elementId !== undefined)
+        bindings.elementId = job.elementId;
+    return { ...app, log: app.log.child(bindings) };
+}
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
@@ -114,7 +129,7 @@ export async function mountWorkers(ctx, app) {
             throw new Error(`worker "${jobType}": ${decl.handler} exports no handler for it ` +
                 `(expected handlers["${jobType}"], a named export, or a default function)`);
         }
-        const wrapped = (job) => runInJobContext({ instanceKey: job.processInstanceKey, elementId: job.elementId, jobType }, () => handler(job, app));
+        const wrapped = (job) => runInJobContext({ instanceKey: job.processInstanceKey, elementId: job.elementId, jobType }, () => handler(job, withJobLog(app, job)));
         const sub = await ctx.engine.registerWorker(jobType, wrapped, {
             workerName: `${ctx.manifest.id}:${jobType}`,
         });

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

@@ -2,6 +2,7 @@ import type { EngineClient, HostContext } from "./host.ts";
 import { type AppManifest } from "./manifest.ts";
 import type { TemplateSource } from "./modules/templates.ts";
 import { DataLayer } from "./modules/datasource.ts";
+import { type Logger } from "./logger.ts";
 import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { type SecurityPolicy } from "./modules/security.ts";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
@@ -56,6 +57,10 @@ export interface UrbanApp {
     stop(): Promise<void>;
     /** A structured snapshot of what is mounted. */
     inspect(): Record<string, unknown>;
+    /** An app-level structured {@link Logger} for the entrypoint (`main.ts`). It carries no
+     * per-request/per-job correlation (worker handlers and route delegates get a child logger bound
+     * to their job/request context via `AppApi.log`); use it for boot/shutdown lifecycle lines. */
+    readonly log: Logger;
     /** The provisioned data layer (available after start when `data` is mounted). */
     readonly data: DataLayer | undefined;
     readonly security: SecurityPolicy | undefined;

package/dist/runtime/core/runtime.js

@@ -8,6 +8,7 @@ import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
 import { provisionData, DataLayer } from "./modules/datasource.js";
 import { installExecStore } from "./execContext.js";
+import { createLogger } from "./logger.js";
 import { mountWorkers } from "./modules/workers.js";
 import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
@@ -48,6 +49,10 @@ export async function createUrbanApp(opts) {
         instanceTracking: opts.mount?.instanceTracking ?? true,
     };
     const ctx = { manifest, host, engine, root, templates: opts.templates };
+    // One app-level structured logger over the host sink, shared by the entrypoint (exposed as
+    // `app.log`) and the per-invocation `AppApi.log` (workers/route delegates `child()` it with their
+    // correlation context).
+    const appLog = createLogger((l, m, f) => host.log(l, m, f));
     // Install the ambient job-execution store once per process (idempotent) so worker dispatch can
     // stamp write-provenance onto DataLayer inserts. Absent-safe: a host without `createAsyncStore`
     // leaves provenance capture disabled.
@@ -99,6 +104,7 @@ export async function createUrbanApp(opts) {
     const app = {
         manifest,
         root,
+        log: appLog,
         get data() {
             return data;
         },
@@ -124,7 +130,7 @@ export async function createUrbanApp(opts) {
                     engine,
                     sdk: engineSdk(engine),
                     env: (n) => host.env(n),
-                    log: (l, m, f) => host.log(l, m, f),
+                    log: appLog,
                 };
                 if (flags.workers) {
                     const w = await mountWorkers(ctx, api);

package/dist/runtime/engine/nanosdk.d.ts

@@ -92,7 +92,7 @@ export interface NanoSdkClient {
     stopAllWorkers?(): void | Promise<void>;
     close?(): void | Promise<void>;
 }
-type Log = (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+type Log = (level: "debug" | "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
 /**
  * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
  * message, and user-task calls map one-to-one onto the SDK's client methods; workers

package/dist/runtime/index.d.ts

@@ -6,6 +6,7 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
+export type { Logger, LogLevel, LogFields } from "./core/logger.ts";
 export { BpmnError, isBpmnError } from "./core/host.ts";
 export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.ts";
 export type { ConnectorsHandle } from "./core/modules/connectors.ts";

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.39.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": {