@nanobpm/urban 0.40.2 → 0.42.0

package/dist/cli.js

@@ -142,6 +142,13 @@ async function cmdGen(f) {
             console.error(`  • ${e.path}: ${e.message}`);
         return 1;
     }
+    // Non-fatal spec-hygiene advisories (e.g. a requestBody schema shared by >1 operation). Printed
+    // in both gen and check; never change the exit code.
+    if (res.warnings.length > 0) {
+        console.warn(`⚠ ${res.warnings.length} spec warning(s):`);
+        for (const w of res.warnings)
+            console.warn(`  • ${w}`);
+    }
     if (f.check) {
         if (res.drift.length === 0 && res.missingStubs.length === 0) {
             console.log(`✔ generated artifacts + handler stubs are up to date (${res.artifacts.length} checked)`);

package/dist/openapi/spec.d.ts

@@ -152,6 +152,19 @@ export declare function collectOperations(doc: OpenApiDoc): OperationInfo[];
  * fails loudly on an incoherent spec instead of shipping a mis-dispatching registry.
  */
 export declare function assertUniqueOperationIds(doc: OpenApiDoc): void;
+/** Groups of operationIds that name the SAME requestBody schema `$ref` as their JSON body,
+ *  keyed by that ref (only refs shared by two or more operations are returned, sorted). A single
+ *  request-body schema reused verbatim by multiple operations is the structural fingerprint of the
+ *  "one permissive schema standing in for what should be mutually-exclusive variants" defect: two
+ *  operations that genuinely want different shapes (e.g. `startConvergenceLoop` wants pr|url,
+ *  `startPlanFanout` wants issue|url) are forced to share one loose object, so neither can be
+ *  tightened without breaking the other. gen surfaces this as a non-fatal warning so an author can
+ *  split it into per-operation named variants + `oneOf` (the Camunda REST v2 pattern). Structural
+ *  only (pure, total) — the message is built by the caller. */
+export declare function sharedRequestBodySchemas(doc: OpenApiDoc): {
+    ref: string;
+    operationIds: string[];
+}[];
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export declare function operationsWithoutId(doc: OpenApiDoc): string[];

package/dist/openapi/spec.js

@@ -200,6 +200,33 @@ export function assertUniqueOperationIds(doc) {
             "it names the delegate module and the generated controller registry key.");
     }
 }
+/** Groups of operationIds that name the SAME requestBody schema `$ref` as their JSON body,
+ *  keyed by that ref (only refs shared by two or more operations are returned, sorted). A single
+ *  request-body schema reused verbatim by multiple operations is the structural fingerprint of the
+ *  "one permissive schema standing in for what should be mutually-exclusive variants" defect: two
+ *  operations that genuinely want different shapes (e.g. `startConvergenceLoop` wants pr|url,
+ *  `startPlanFanout` wants issue|url) are forced to share one loose object, so neither can be
+ *  tightened without breaking the other. gen surfaces this as a non-fatal warning so an author can
+ *  split it into per-operation named variants + `oneOf` (the Camunda REST v2 pattern). Structural
+ *  only (pure, total) — the message is built by the caller. */
+export function sharedRequestBodySchemas(doc) {
+    const byRef = new Map();
+    for (const op of collectOperations(doc)) {
+        const ref = op.requestBodySchema?.$ref;
+        if (typeof ref !== "string" || ref.length === 0)
+            continue;
+        const ids = byRef.get(ref) ?? [];
+        ids.push(op.operationId);
+        byRef.set(ref, ids);
+    }
+    const out = [];
+    for (const [ref, ids] of byRef) {
+        if (ids.length > 1)
+            out.push({ ref, operationIds: [...ids].sort() });
+    }
+    out.sort((a, b) => a.ref.localeCompare(b.ref));
+    return out;
+}
 /** "method path" pointers for every operation that declares no `operationId`. Such operations are
  *  unroutable (no delegate to bind), so the runtime mount logs them at `warn` and skips them. */
 export function operationsWithoutId(doc) {
@@ -532,6 +559,36 @@ function matchesType(declared, value) {
 function matchesAnyType(declared, value) {
     return declared.some((t) => matchesType(t, value));
 }
+/** A short, human-readable label for one `anyOf`/`oneOf` variant, so a composition failure can name
+ *  the allowed shapes instead of an opaque "matched 0". Prefers the variant's discriminant — its
+ *  `required` fields (e.g. `{pr}` vs `{url}`) — since that is exactly what a caller must choose
+ *  between; falls back to the declared type(s), else "object". */
+function variantLabel(doc, variant) {
+    const s = resolveSchema(doc, variant);
+    if (!s)
+        return "?";
+    const req = Array.isArray(s.required) ? s.required : [];
+    if (req.length > 0)
+        return `{${req.join(", ")}}`;
+    const types = schemaTypeList(s);
+    return types.length > 0 ? types.join("|") : "object";
+}
+/** The `(allowed: {pr} | {url})` suffix for a composition-failure summary message. */
+function variantSummary(doc, variants) {
+    return ` (allowed: ${variants.map((v) => variantLabel(doc, v)).join(" | ")})`;
+}
+/** When a `oneOf`/`anyOf` matched no variant, surface actionable detail: the issues of the variant
+ *  the value was CLOSEST to (fewest problems). For the discriminant case this is the shape the
+ *  caller meant, so its issues read like `pr: is required` / `url: is not an allowed property`
+ *  instead of a bare "matched 0". Ties resolve to the earliest variant (declaration order). */
+function closestVariantIssues(perVariant) {
+    let best;
+    for (const iss of perVariant) {
+        if (best === undefined || iss.length < best.length)
+            best = iss;
+    }
+    return best ?? [];
+}
 /** Validate `value` against `schema` (resolving local $refs against `doc`), returning every issue
  *  found (empty = valid). A pragmatic JSON-Schema subset; unknown keywords are ignored. */
 export function validateValue(doc, schemaIn, value, path = "") {
@@ -578,13 +635,48 @@ export function validateValue(doc, schemaIn, value, path = "") {
         for (const sub of schema.allOf)
             issues.push(...validateValue(doc, sub, value, path));
     }
-    if (schema.anyOf && !schema.anyOf.some((sub) => validateValue(doc, sub, value, path).length === 0)) {
-        issues.push({ path: at, message: "does not match any schema in anyOf" });
+    if (schema.anyOf) {
+        // `anyOf` needs only ONE match, so short-circuit on the first clean variant — `validateValue`
+        // runs on every request (params/query/body/response) and evaluating every variant for a large
+        // schema is needless work once we have a hit. Only when NO variant matches do we build the full
+        // per-variant issue list to name the allowed shapes and surface the closest variant's issues.
+        let anyMatched = false;
+        const perVariant = [];
+        for (const sub of schema.anyOf) {
+            const subIssues = validateValue(doc, sub, value, path);
+            if (subIssues.length === 0) {
+                anyMatched = true;
+                break;
+            }
+            perVariant.push(subIssues);
+        }
+        if (!anyMatched) {
+            issues.push({
+                path: at,
+                message: `does not match any of the ${schema.anyOf.length} allowed shapes${variantSummary(doc, schema.anyOf)}`,
+            });
+            issues.push(...closestVariantIssues(perVariant));
+        }
     }
     if (schema.oneOf) {
-        const matched = schema.oneOf.filter((sub) => validateValue(doc, sub, value, path).length === 0).length;
-        if (matched !== 1) {
-            issues.push({ path: at, message: `must match exactly one schema in oneOf (matched ${matched})` });
+        const perVariant = schema.oneOf.map((sub) => validateValue(doc, sub, value, path));
+        const matched = perVariant.filter((v) => v.length === 0).length;
+        if (matched === 0) {
+            // No variant matched: name the allowed shapes AND surface the closest variant's issues, so a
+            // discriminated body (e.g. exactly one of pr|url) fails with actionable detail, not "matched 0".
+            issues.push({
+                path: at,
+                message: `does not match any of the ${schema.oneOf.length} allowed shapes${variantSummary(doc, schema.oneOf)}`,
+            });
+            issues.push(...closestVariantIssues(perVariant));
+        }
+        else if (matched > 1) {
+            // Matched more than one: the shapes are not mutually exclusive for this value (usually a body
+            // that supplies two discriminants, or under-constrained variants). Report the ambiguity.
+            issues.push({
+                path: at,
+                message: `must match exactly one of the ${schema.oneOf.length} allowed shapes, but matched ${matched}${variantSummary(doc, schema.oneOf)}`,
+            });
         }
     }
     // `value` is non-null here (the null branch returned above), so match against the declared value

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

@@ -13,6 +13,33 @@ export interface ApiBinding {
      *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
     docs?: boolean | string;
 }
+/**
+ * Derive the ABSOLUTE spec + operations-server URLs the Swagger UI page should use, from the docs
+ * page's own address (`pageHref`), the mount-root-relative docs path (`docsBase`, e.g.
+ * `/app/api-docs`) and operations base (`apiBase`, e.g. `/app/api`).
+ *
+ * Why this can't be done server-side: the docs page can load at `<docsBase>` OR `<docsBase>/` (a
+ * trailing slash — reverse proxies and some webviews append one), and behind the Nano console
+ * proxy it carries a path prefix (`/console/app-view/<name>`). A document-relative spec URL or a
+ * relative `servers` entry resolves DIFFERENTLY depending on that trailing slash — which sent
+ * "Try it out" to `<mount>/app/api-docs/api/<op>` (a 404) instead of `<mount>/app/api/<op>`. The
+ * app never sees the proxy prefix, so `window.location` in the browser is the only place with the
+ * full mount path.
+ *
+ * We strip any trailing slash from the page path, then strip the known `docsBase` suffix to recover
+ * the (proxy-prefixed) mount root, and re-append `docsBase`/`apiBase` as ORIGIN-absolute URLs — so
+ * Swagger UI performs no further relative resolution and is immune to the trailing slash. When the
+ * page path doesn't end in `docsBase` (unexpected) or the href is malformed, we fall back to the
+ * document-relative `relSpec` and leave `servers` to the served spec (`server: null`).
+ *
+ * This runs in the browser: it is embedded verbatim into the docs page via `.toString()` so the
+ * shipped page and these unit tests exercise the exact same code (no drift). Keep it dependency-free
+ * and free of template literals / `${}` (it is interpolated into a template literal).
+ */
+export declare function deriveSwaggerUrls(pageHref: string, docsBase: string, apiBase: string, relSpec: string): {
+    specUrl: string;
+    server: string | null;
+};
 /** The `{ params, query, body }` contract a typed operation is generic over. `body` is optional so
  *  a generated request type for an operation without a required requestBody (its `body?` is
  *  optional/`undefined`) still satisfies the constraint — see the generated `operations.ts` /

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

@@ -28,10 +28,49 @@ const SWAGGER_UI_VERSION = "5.17.14";
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c);
 }
+/**
+ * Derive the ABSOLUTE spec + operations-server URLs the Swagger UI page should use, from the docs
+ * page's own address (`pageHref`), the mount-root-relative docs path (`docsBase`, e.g.
+ * `/app/api-docs`) and operations base (`apiBase`, e.g. `/app/api`).
+ *
+ * Why this can't be done server-side: the docs page can load at `<docsBase>` OR `<docsBase>/` (a
+ * trailing slash — reverse proxies and some webviews append one), and behind the Nano console
+ * proxy it carries a path prefix (`/console/app-view/<name>`). A document-relative spec URL or a
+ * relative `servers` entry resolves DIFFERENTLY depending on that trailing slash — which sent
+ * "Try it out" to `<mount>/app/api-docs/api/<op>` (a 404) instead of `<mount>/app/api/<op>`. The
+ * app never sees the proxy prefix, so `window.location` in the browser is the only place with the
+ * full mount path.
+ *
+ * We strip any trailing slash from the page path, then strip the known `docsBase` suffix to recover
+ * the (proxy-prefixed) mount root, and re-append `docsBase`/`apiBase` as ORIGIN-absolute URLs — so
+ * Swagger UI performs no further relative resolution and is immune to the trailing slash. When the
+ * page path doesn't end in `docsBase` (unexpected) or the href is malformed, we fall back to the
+ * document-relative `relSpec` and leave `servers` to the served spec (`server: null`).
+ *
+ * This runs in the browser: it is embedded verbatim into the docs page via `.toString()` so the
+ * shipped page and these unit tests exercise the exact same code (no drift). Keep it dependency-free
+ * and free of template literals / `${}` (it is interpolated into a template literal).
+ */
+export function deriveSwaggerUrls(pageHref, docsBase, apiBase, relSpec) {
+    try {
+        const loc = new URL(pageHref);
+        const path = loc.pathname.replace(/\/+$/, "");
+        if (path.length >= docsBase.length && path.slice(path.length - docsBase.length) === docsBase) {
+            const mount = loc.origin + path.slice(0, path.length - docsBase.length);
+            return { specUrl: mount + docsBase + "/openapi.json", server: mount + apiBase };
+        }
+    }
+    catch {
+        // Malformed href — fall through to the document-relative fallback below.
+    }
+    return { specUrl: relSpec, server: null };
+}
 /** The self-contained Swagger UI page. Static HTML: it renders even when the spec is momentarily
- *  unreadable (Swagger UI fetches `specUrl` itself and surfaces any load/parse error in-page),
- *  which keeps the docs route decoupled from spec-load failures. */
-function swaggerUiPage(title, specUrl) {
+ *  unreadable (on a fetch/parse failure it hands `specUrl` to Swagger UI, which surfaces the error
+ *  in-page), which keeps the docs route decoupled from spec-load failures. The client derives
+ *  absolute spec + server URLs from `window.location` via `deriveSwaggerUrls` so "Try it out"
+ *  targets the app regardless of a trailing slash on the docs URL or a reverse-proxy prefix. */
+function swaggerUiPage(title, specUrl, docsBase, apiBase) {
     const css = `https://cdn.jsdelivr.net/npm/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui.css`;
     const bundle = `https://cdn.jsdelivr.net/npm/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui-bundle.js`;
     return `<!doctype html>
@@ -47,7 +86,22 @@ function swaggerUiPage(title, specUrl) {
 <div id="swagger-ui"></div>
 <script src="${bundle}" crossorigin="anonymous"></script>
 <script>
-window.ui = SwaggerUIBundle({ url: ${JSON.stringify(specUrl)}, dom_id: '#swagger-ui', deepLinking: true });
+(function () {
+  var derive = ${deriveSwaggerUrls.toString()};
+  var urls = derive(window.location.href, ${JSON.stringify(docsBase)}, ${JSON.stringify(apiBase)}, ${JSON.stringify(specUrl)});
+  function boot(opts) { window.ui = SwaggerUIBundle(opts); }
+  fetch(urls.specUrl)
+    .then(function (r) { return r.ok ? r.json() : null; })
+    .then(function (spec) {
+      if (spec && urls.server) { spec.servers = [{ url: urls.server }]; }
+      boot(spec
+        ? { spec: spec, dom_id: '#swagger-ui', deepLinking: true }
+        : { url: urls.specUrl, dom_id: '#swagger-ui', deepLinking: true });
+    })
+    .catch(function () {
+      boot({ url: urls.specUrl, dom_id: '#swagger-ui', deepLinking: true });
+    });
+})();
 </script>
 </body>
 </html>`;
@@ -201,12 +255,13 @@ export function mountApi(ctx, app) {
     const dir = binding.dir ?? "operations";
     const surfaceEject = binding.eject === true;
     const specRoutePath = `${docsBase}/openapi.json`;
-    // The Swagger UI page is served at `docsBase` (no trailing slash — the slash variant 308-
-    // redirects onto it), so its browser-relative base is the PARENT directory. Hand Swagger UI a
-    // DOCUMENT-relative spec URL and `servers` entry so both rebase onto the app's mount root:
-    // correct at the origin root (CLI :3000) AND under the Nano console reverse proxy
-    // (/console/app-view/<name>/), where a root-absolute "/app/…" escapes the prefix and hits the
-    // console origin instead of the app (issue #151).
+    // Fallback values for the RAW served spec + docs page. The interactive Swagger UI computes
+    // ABSOLUTE spec + server URLs client-side from `window.location` (see `deriveSwaggerUrls`), which
+    // is immune to a trailing slash on the docs URL and to the Nano console reverse-proxy prefix
+    // (/console/app-view/<name>/). These document-relative values remain (a) the client's fallback
+    // when the page path unexpectedly doesn't end in `docsBase`, and (b) what a non-interactive
+    // consumer reading `openapi.json` directly sees. They still rebase onto the app's mount root
+    // rather than using a root-absolute "/app/…" that would escape the proxy prefix (issue #151).
     const lastSegment = (p) => p.split("/").filter(Boolean).pop() ?? "";
     const parentPath = (p) => {
         const parts = p.split("/").filter(Boolean);
@@ -217,8 +272,7 @@ export function mountApi(ctx, app) {
     const specDocUrl = `${lastSegment(docsBase)}/openapi.json`;
     // `servers` can only be relativized when the operations `base` shares the docs page's parent
     // directory (the default `${base}-docs` sibling). For a fully custom `docs` path under a
-    // different parent, keep the root-absolute base (works direct; try-it-out through the proxy is
-    // the documented limitation in #151).
+    // different parent, keep the root-absolute base for the raw spec.
     const serversUrl = parentPath(base) === parentPath(docsBase) ? lastSegment(base) : base;
     // Resolve + parse the spec lazily on first request and cache it (mirroring the lazy module load
     // pattern). A malformed/unreadable spec surfaces as a 500 on request — with the reason — rather
@@ -605,7 +659,7 @@ export function mountApi(ctx, app) {
         return json({ ...d, servers: [{ url: serversUrl }] });
     };
     const docsTitle = `${ctx.manifest.name ?? "App"} — API docs`;
-    const serveDocs = () => html(swaggerUiPage(docsTitle, specDocUrl));
+    const serveDocs = () => html(swaggerUiPage(docsTitle, specDocUrl, docsBase, base));
     // A permanent redirect for the trailing-slash variant (`${docsBase}/`). The router only does
     // exact matches for non-prefix routes, so without this a reverse proxy or browser that appends
     // a slash would 404 on the Swagger UI. 308 preserves the method and points at the canonical

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

@@ -26,9 +26,14 @@ import { html, json } from "../router.js";
 import { cancelInstanceReconciling } from "./cancel.js";
 import { apiDocsPath } from "./api.js";
 import { quoteIdent } from "./gateway.js";
-/** A JavaScript-body response (the renderer module served at /app/runtime.js). */
-function javascript(body, status = 200) {
-    return { status, headers: { "content-type": "text/javascript; charset=utf-8" }, body };
+/** A JavaScript-body response (the renderer module served at the fingerprinted
+ * `/app/runtime.<hash>.js`, and its `/app/runtime.js` back-compat route). */
+function javascript(body, status = 200, extraHeaders) {
+    return {
+        status,
+        headers: { "content-type": "text/javascript; charset=utf-8", ...extraHeaders },
+        body,
+    };
 }
 /** A SQL identifier guard — a table name must be a bare identifier *and* a known table
  * (checked against `schema()`), so `/app/data/:table` can never inject SQL. */
@@ -75,14 +80,29 @@ export function createPagesRoutes(opts, deps) {
     };
     const routes = [];
     const shell = html(rendererShell(homePage, opts.apiDocsPath));
+    // The shell must never be pinned by the browser: it carries the *current* fingerprinted
+    // runtime URL, so a stale shell would keep pointing at an old module hash. `no-cache` forces
+    // a revalidation on every load; the shell body is tiny, and the expensive module it references
+    // is what gets the long-lived immutable caching (via its content-hashed URL).
+    shell.headers = { ...shell.headers, "cache-control": "no-cache" };
     // ── the renderer shell + module ─────────────────────────────────────────
     routes.push({ method: "GET", path: "/", source: "surface:pages", handler: () => shell });
     routes.push({ method: "GET", path: "/index.html", source: "surface:pages", handler: () => shell });
+    // The fingerprinted module URL (referenced by the shell): unique per content, so cache it hard.
+    routes.push({
+        method: "GET",
+        path: RUNTIME_JS_PATH,
+        source: "surface:pages",
+        handler: () => javascript(RENDERER_JS, 200, { "cache-control": IMMUTABLE_CACHE }),
+    });
+    // Back-compat / defence in depth: the legacy unhashed URL keeps working, but is served
+    // `no-cache` so any client (or cached shell) that still requests it always revalidates and
+    // gets the current bytes instead of replaying a heuristically-cached older copy.
     routes.push({
         method: "GET",
         path: "/app/runtime.js",
         source: "surface:pages",
-        handler: () => javascript(RENDERER_JS),
+        handler: () => javascript(RENDERER_JS, 200, { "cache-control": "no-cache" }),
     });
     // ── GET /app/pages (index of available pages) ───────────────────────────
     // Powers multi-page navigation: a `nav` node with `items: "auto"` lists every
@@ -377,7 +397,7 @@ function rendererShell(homePage, apiDocsPath) {
     // UI for free). `target="_blank"` + hardened `rel` so the docs open without giving the docs
     // tab a handle back to this window (reverse-tabnabbing).
     //
-    // The href must be DOCUMENT-relative, exactly like the `./app/runtime.js` script tag below:
+    // The href must be DOCUMENT-relative, exactly like the `./app/runtime.<hash>.js` script tag below:
     // the shell is served at the app's mount root (always a trailing "/"), which is the origin
     // root for a direct run (CLI on :3000) but a path prefix under the Nano console's reverse
     // proxy (/console/app-view/<name>/). A root-absolute "/app/api-docs" would escape that prefix
@@ -400,7 +420,7 @@ function rendererShell(homePage, apiDocsPath) {
 </head>
 <body>${apiDocsBadge}
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
-  <script type="module" src="./app/runtime.js"></script>
+  <script type="module" src=".${RUNTIME_JS_PATH}"></script>
 </body>
 </html>`;
 }
@@ -454,7 +474,9 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-card h2 { font-size:1rem; margin:0 0 .75rem; }
 .pc-field { display:flex; flex-direction:column; gap:.25rem; margin-bottom:.6rem; }
 .pc-field label { font-size:.8rem; color:var(--nano-text-muted); }
-.pc-field input { padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+.pc-field input:not([type=checkbox]) { padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); }
+.pc-field-check label { display:flex; flex-direction:row; align-items:center; gap:.5rem; font-size:.9rem; color:var(--nano-text); cursor:pointer; }
+.pc-field-check input { width:auto; padding:0; accent-color:var(--nano-accent); cursor:pointer; }
 .pc-btn { padding:.5rem .9rem; border:0; border-radius:.4rem; background:var(--nano-accent); color:var(--nano-on-accent); font:inherit; cursor:pointer; }
 .pc-btn:disabled { opacity:.5; cursor:default; }
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
@@ -761,8 +783,24 @@ function renderActionForm(node) {
   const inputs = new Map();
   const fieldTypes = new Map();
   for (const f of p.fields || []) {
-    const kind = f.type === "number" ? "number" : "text";
+    const kind = f.type === "checkbox" ? "checkbox" : (f.type === "number" ? "number" : "text");
     fieldTypes.set(f.key, kind);
+    if (kind === "checkbox") {
+      // A boolean field renders a real checkbox; its default checked state comes
+      // from default/checked on the field (unset -> unchecked). We record that on
+      // the input's defaultChecked so a post-submit reset can restore it without a
+      // side map that could drift from the actual input.
+      const checked = f.default === true || f.checked === true;
+      const input = el("input", { type: "checkbox" });
+      input.defaultChecked = checked;
+      input.checked = checked;
+      inputs.set(f.key, input);
+      // Input-first, wrapped in the label so the whole row is a click target.
+      card.append(
+        el("div", { class: "pc-field pc-field-check" }, el("label", {}, input, " " + (f.label || f.key))),
+      );
+      continue;
+    }
     const attrs = { type: kind, placeholder: f.label || f.key };
     if (kind === "number") {
       attrs.inputmode = "numeric";
@@ -779,7 +817,11 @@ function renderActionForm(node) {
   btn.addEventListener("click", async () => {
     const variables = Object.create(null);
     for (const [k, input] of inputs) {
-      if (fieldTypes.get(k) === "number") {
+      if (fieldTypes.get(k) === "checkbox") {
+        // Always emit a real boolean (checked -> true / false), never a string,
+        // so a strict equality check on the action side sees the intended value.
+        variables[k] = input.checked === true;
+      } else if (fieldTypes.get(k) === "number") {
         const t = String(input.value).trim();
         // Blank → omit so the action-side default applies; a non-finite parse
         // (NaN/Infinity) is also omitted rather than smuggling a raw string
@@ -802,7 +844,12 @@ function renderActionForm(node) {
       msg.className = "pc-msg ok";
       msg.textContent = (p.action && p.action.successLabel) ||
         (res && res.processInstanceKey != null ? "Started (instance " + res.processInstanceKey + ")" : "Done");
-      for (const input of inputs.values()) input.value = "";
+      for (const [k, input] of inputs) {
+        // Text/number inputs clear; a checkbox resets to its declared default,
+        // read straight off the input's defaultChecked (no side map to drift).
+        if (fieldTypes.get(k) === "checkbox") input.checked = input.defaultChecked;
+        else input.value = "";
+      }
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
       msg.className = "pc-msg err"; msg.textContent = String(e.message || e);
@@ -1280,3 +1327,23 @@ async function renderPage() {
 window.addEventListener("hashchange", renderPage);
 renderPage();
 `;
+/** A tiny, dependency-free FNV-1a hash → 8 hex chars. Used to fingerprint the renderer
+ *  module's URL so a content change busts the browser cache. Environment-agnostic (no
+ *  `crypto` import) so the runtime stays loadable under Node, Deno, and the embedded host. */
+function fnv1aHex(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, "0");
+}
+// The renderer module is served at a *content-fingerprinted* URL. The shell references this exact
+// path, so whenever `RENDERER_JS` changes (e.g. an Urban upgrade in a marketplace/Studio update)
+// the URL changes with it and the browser fetches the new module instead of silently replaying a
+// heuristically-cached copy of the old one — the failure that made a "Cancel" button (and every
+// other page action) do nothing after an upgrade until a hard refresh. Because the URL is unique
+// per content, the response itself is served `immutable` with a one-year max-age.
+const RUNTIME_JS_HASH = fnv1aHex(RENDERER_JS);
+const RUNTIME_JS_PATH = `/app/runtime.${RUNTIME_JS_HASH}.js`;
+const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";

package/dist/runtime/index.d.ts

@@ -6,7 +6,8 @@ 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 { createLogger } from "./core/logger.ts";
+export type { Logger, LogLevel, LogFields, LogSink } 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/runtime/index.js

@@ -5,6 +5,9 @@ export { createUrbanApp } from "./core/runtime.js";
 export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.js";
 // Validation
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
+// Structured logging surface (see core/logger.ts): the shape of `AppApi.log`, plus `createLogger`
+// so consumers can build a Logger for a custom sink or a no-op test double (`createLogger(() => {})`).
+export { createLogger } from "./core/logger.js";
 // BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
 // error routed to an error boundary (ADR 0050), instead of a retryable failure.
 export { BpmnError, isBpmnError } from "./core/host.js";

package/dist/toolkit/gen.d.ts

@@ -42,6 +42,9 @@ export interface GenResult {
     incomplete: boolean;
     /** Per-file model-derivation errors (empty on success). */
     modelErrors: ModelError[];
+    /** Non-fatal spec-hygiene warnings (e.g. a requestBody schema shared by >1 operation). Empty on
+     *  a clean spec. Surfaced by the CLI but never fail gen/check — advisory only. */
+    warnings: string[];
 }
 declare function join(root: string, rel: string): string;
 declare function dirOf(p: string): string;

package/dist/toolkit/gen.js

@@ -9,7 +9,7 @@ import { deriveWorkerBindings } from "./derivers/worker-io.js";
 import { deriveMeta } from "./derivers/meta.js";
 import { deriveMessageBindings } from "./derivers/messages.js";
 import { deriveApi } from "./derivers/api.js";
-import { parseSpec } from "../openapi/spec.js";
+import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.js";
 import { deriveModels, MODEL_PROVENANCE } from "./models.js";
 function join(root, rel) {
     // Normalize Windows-style separators to forward slashes (GenIO uses forward slashes on all
@@ -68,6 +68,7 @@ async function collectAll(opts) {
     const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
     const manifest = JSON.parse(await io.readText(manifestPath));
     const artifacts = [];
+    const warnings = [];
     // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
     if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
         artifacts.push(...deriveMigrations(manifest));
@@ -101,13 +102,21 @@ async function collectAll(opts) {
         const opsDir = typeof manifest.api?.dir === "string" && manifest.api.dir.trim().length > 0
             ? manifest.api.dir.trim()
             : undefined;
-        artifacts.push(...deriveApi(parseSpec(specText), opsDir, manifest.api?.eject === true));
+        const doc = parseSpec(specText);
+        artifacts.push(...deriveApi(doc, opsDir, manifest.api?.eject === true));
+        // Non-fatal spec-hygiene: a requestBody schema reused by >1 operation can't be tightened into
+        // per-operation discriminated variants — flag it so the author can split it (never fail gen).
+        for (const { ref, operationIds } of sharedRequestBodySchemas(doc)) {
+            warnings.push(`requestBody schema ${ref} is shared by ${operationIds.length} operations ` +
+                `(${operationIds.join(", ")}). A single schema can't model per-operation discriminants — ` +
+                "consider splitting it into named variants + oneOf (additionalProperties:false) per operation.");
+        }
     }
-    return { artifacts: sortArtifacts(artifacts), derived };
+    return { artifacts: sortArtifacts(artifacts), derived, warnings };
 }
 /** Run the derivers and write artifacts (or, with `check`, report drift without writing). */
 export async function runGen(opts) {
-    const { artifacts, derived } = await collectAll(opts);
+    const { artifacts, derived, warnings } = await collectAll(opts);
     const { root, io } = opts;
     const emitModels = opts.emitModels ?? true;
     const drift = [];
@@ -160,7 +169,7 @@ export async function runGen(opts) {
             swept.push(rel);
         }
     }
-    return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors };
+    return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors, warnings };
 }
 export { dirOf, join as joinPath };
 /** Derive code-first models in-memory (no writes) — backs `urban derive --stdout`, the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.40.2",
+	"version": "0.42.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",

package/src/cli.ts

@@ -153,6 +153,12 @@ async function cmdGen(f: Flags): Promise<number> {
     for (const e of res.modelErrors) console.error(`  • ${e.path}: ${e.message}`);
     return 1;
   }
+  // Non-fatal spec-hygiene advisories (e.g. a requestBody schema shared by >1 operation). Printed
+  // in both gen and check; never change the exit code.
+  if (res.warnings.length > 0) {
+    console.warn(`⚠ ${res.warnings.length} spec warning(s):`);
+    for (const w of res.warnings) console.warn(`  • ${w}`);
+  }
   if (f.check) {
     if (res.drift.length === 0 && res.missingStubs.length === 0) {
       console.log(`✔ generated artifacts + handler stubs are up to date (${res.artifacts.length} checked)`);