@nanobpm/urban 0.39.0 → 0.40.1

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/derivers/api.js

@@ -8,7 +8,7 @@
 // the shared `openapi/spec.ts`, so types and runtime never drift.
 import { GENERATED_DIR } from "../artifact.js";
 import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "../api-dir.js";
-import { collectOperations, assertUniqueOperationIds, isObjectSchema, refName, } from "../../openapi/spec.js";
+import { collectOperations, assertUniqueOperationIds, isObjectSchema, refName, schemaAllowsNull, schemaTypeList, schemaValueTypes, } from "../../openapi/spec.js";
 /** Filenames of the emitted artifacts (siblings of worker-io.d.ts in nano-generated/). */
 export const API_BINDINGS_DTS = "api-io.d.ts";
 export const API_BINDINGS_TS = "operations.ts";
@@ -35,7 +35,7 @@ export function schemaToTs(schema, depth = 0) {
         const name = refName(schema.$ref);
         return name ? typeStem(name) : "unknown";
     }
-    const nullable = schema.nullable === true;
+    const nullable = schemaAllowsNull(schema);
     const wrap = (t) => (nullable ? `${t} | null` : t);
     if (Array.isArray(schema.enum) && schema.enum.length > 0) {
         return wrap(schema.enum.map((v) => JSON.stringify(v)).join(" | "));
@@ -51,7 +51,13 @@ export function schemaToTs(schema, depth = 0) {
     if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
         return wrap(schema.allOf.map((s) => schemaToTs(s, depth + 1)).join(" & "));
     }
-    switch (schema.type) {
+    // Value types, normalized from OpenAPI 3.0 (single string) or 3.1 (array, e.g. `[T, "null"]` or a
+    // multi-type union). `null` is stripped here and re-applied by `wrap` via `schemaAllowsNull`.
+    const valueTypes = schemaValueTypes(schema);
+    if (valueTypes.length > 1) {
+        return wrap(valueTypes.map((t) => tsForScalarType(t, schema, depth)).join(" | "));
+    }
+    switch (valueTypes[0]) {
         case "string":
             return wrap("string");
         case "integer":
@@ -59,20 +65,40 @@ export function schemaToTs(schema, depth = 0) {
             return wrap("number");
         case "boolean":
             return wrap("boolean");
-        case "null":
-            return "null";
         case "array":
             return wrap(`Array<${schemaToTs(schema.items, depth + 1)}>`);
         case "object":
             return wrap(objectToTs(schema, depth));
         default:
-            // No `type`: infer object-ness from object-only keywords (shared with the runtime
-            // validator via isObjectSchema so types and validation agree); otherwise unknown.
+            // No value type. A schema whose only declared type is "null" is exactly `null`; otherwise
+            // infer object-ness from object-only keywords (shared with the runtime validator via
+            // isObjectSchema so types and validation agree), else fall back to unknown.
+            if (schemaTypeList(schema).length > 0 && schemaValueTypes(schema).length === 0)
+                return "null";
             if (isObjectSchema(schema))
                 return wrap(objectToTs(schema, depth));
             return "unknown";
     }
 }
+/** The TS expression for a single (non-"null") JSON-Schema value type. Nullability is applied by
+ *  the caller's `wrap`, so this never emits `| null`. */
+function tsForScalarType(t, schema, depth) {
+    switch (t) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array":
+            return `Array<${schemaToTs(schema.items, depth + 1)}>`;
+        case "object":
+            return objectToTs(schema, depth);
+        default:
+            return "unknown";
+    }
+}
 function objectToTs(schema, depth) {
     const props = schema.properties ?? {};
     const required = new Set(schema.required ?? []);

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.1",
 	"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.13.0",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

package/src/openapi/spec.test.ts

@@ -208,6 +208,53 @@ test("isObjectSchema treats typeless property/required/additionalProperties sche
   assert.equal(isObjectSchema({}), false); // no shape keywords → not an object
 });
 
+test("isObjectSchema understands OpenAPI 3.1 nullable type-arrays", () => {
+  assert.equal(isObjectSchema({ type: ["object", "null"] }), true); // nullable object is an object
+  assert.equal(isObjectSchema({ type: ["string", "null"] }), false); // nullable scalar is not
+});
+
+test("validateValue accepts OpenAPI 3.1 nullable type-arrays (type: [T, null])", () => {
+  // The 3.1 idiom `type: [T, "null"]` must be treated exactly like 3.0 `nullable: true`: the value
+  // type is accepted, an explicit null is accepted, and a wrong type is still rejected.
+  const nullableStr: OpenApiSchema = { type: ["string", "null"] };
+  assert.deepEqual(validateValue(doc, nullableStr, "hi"), []);
+  assert.deepEqual(validateValue(doc, nullableStr, null), []);
+  assert.equal(validateValue(doc, nullableStr, 42).length, 1);
+
+  const nullableInt: OpenApiSchema = { type: ["integer", "null"] };
+  assert.deepEqual(validateValue(doc, nullableInt, 7), []);
+  assert.deepEqual(validateValue(doc, nullableInt, null), []);
+  assert.equal(validateValue(doc, nullableInt, "no").length, 1);
+});
+
+test("validateValue keeps bounds + multi-type unions under 3.1 type-arrays", () => {
+  // String bounds still apply to the string arm of a nullable string.
+  const bounded: OpenApiSchema = { type: ["string", "null"], minLength: 2 };
+  assert.deepEqual(validateValue(doc, bounded, "ok"), []);
+  assert.deepEqual(validateValue(doc, bounded, null), []);
+  assert.equal(validateValue(doc, bounded, "x").length, 1); // shorter than minLength
+
+  // A genuine multi-type union (no null) accepts any listed type, rejects others.
+  const strOrNum: OpenApiSchema = { type: ["string", "number"] };
+  assert.deepEqual(validateValue(doc, strOrNum, "a"), []);
+  assert.deepEqual(validateValue(doc, strOrNum, 1), []);
+  assert.equal(validateValue(doc, strOrNum, true).length, 1);
+  assert.equal(validateValue(doc, strOrNum, null).length, 1); // null not permitted without "null"
+});
+
+test("validateValue rejects non-null values for a null-only schema (type: [null] / type: null)", () => {
+  // A schema whose only declared type is "null" must accept null and reject everything else — the
+  // value-type list is empty, so the type check must fall back to the full `type` list.
+  const nullOnlyArr: OpenApiSchema = { type: ["null"] };
+  assert.deepEqual(validateValue(doc, nullOnlyArr, null), []);
+  assert.equal(validateValue(doc, nullOnlyArr, "x").length, 1);
+  assert.equal(validateValue(doc, nullOnlyArr, 0).length, 1);
+
+  const nullOnlyStr: OpenApiSchema = { type: "null" };
+  assert.deepEqual(validateValue(doc, nullOnlyStr, null), []);
+  assert.equal(validateValue(doc, nullOnlyStr, "x").length, 1);
+});
+
 test("validateValue shape-checks typeless object schemas (no type/runtime drift)", () => {
   // A schema with properties/required but no explicit `type: "object"` is emitted as an object
   // by schemaToTs, so the validator must shape-check it too — otherwise invalid bodies pass.

package/src/openapi/spec.ts

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

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