@nanobpm/urban 0.40.2 → 0.41.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/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>`;
 }
@@ -1280,3 +1300,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/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.41.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)`);

package/src/openapi/spec.test.ts

@@ -12,6 +12,7 @@ import {
   parseSpec,
   resolveSchema,
   responseSchemaForStatus,
+  sharedRequestBodySchemas,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -333,6 +334,72 @@ test("validateValue enforces allOf (intersection), anyOf/oneOf (union) — match
   assert.ok(validateValue(doc, one, "x").length > 0); // matches NEITHER
 });
 
+test("validateValue: a failed oneOf discriminant names the shapes and surfaces the closest variant", () => {
+  // The Camunda-style discriminated request body: exactly one of two mutually-exclusive variants
+  // (mutual exclusion enforced by additionalProperties:false + a distinct required discriminant).
+  const byPr: OpenApiSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["pr"],
+    properties: { pr: { type: "string" }, maxRounds: { type: "integer" } },
+  };
+  const byUrl: OpenApiSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["url"],
+    properties: { url: { type: "string" }, maxRounds: { type: "integer" } },
+  };
+  const start: OpenApiSchema = { oneOf: [byPr, byUrl] };
+
+  // Neither discriminant supplied → matched 0. The summary must NAME the allowed shapes, and the
+  // closest variant's own issue must be surfaced (not just the opaque "matched 0").
+  const none = validateValue(doc, start, { maxRounds: 3 }, "body");
+  assert.ok(none.length > 0, "an empty discriminant is rejected");
+  assert.ok(
+    none.some((i) => /allowed:.*\{pr\}.*\|.*\{url\}/.test(i.message)),
+    `summary names the allowed shapes: ${JSON.stringify(none)}`,
+  );
+  assert.ok(
+    none.some((i) => i.path === "body/pr" && /required/.test(i.message)),
+    `closest variant's field issue is surfaced: ${JSON.stringify(none)}`,
+  );
+
+  // Both discriminants supplied → with additionalProperties:false, EACH variant rejects the other's
+  // field, so this is also "matches none" (the desirable strictness — a body can't smuggle both).
+  const both = validateValue(doc, start, { pr: "a/b#1", url: "http://x" }, "body");
+  assert.ok(
+    both.some((i) => /does not match any of the 2 allowed shapes/.test(i.message)),
+    `supplying both discriminants is rejected by the strict variants: ${JSON.stringify(both)}`,
+  );
+
+  // Exactly one discriminant → valid.
+  assert.equal(validateValue(doc, start, { pr: "a/b#1" }, "body").length, 0);
+
+  // `anyOf` no-match reporting mirrors `oneOf`: name the allowed shapes AND surface the closest
+  // variant's issues, so the improved diagnostics are guarded for the union branch too. Here a value
+  // matches NEITHER discriminated variant, and `{pr}` is the closest (its own field is the issue).
+  const anyStart: OpenApiSchema = { anyOf: [byPr, byUrl] };
+  const anyNone = validateValue(doc, anyStart, { maxRounds: 3 }, "body");
+  assert.ok(anyNone.length > 0, "a value matching no anyOf variant is rejected");
+  assert.ok(
+    anyNone.some((i) => /allowed:.*\{pr\}.*\|.*\{url\}/.test(i.message)),
+    `anyOf summary names the allowed shapes: ${JSON.stringify(anyNone)}`,
+  );
+  assert.ok(
+    anyNone.some((i) => i.path === "body/pr" && /required/.test(i.message)),
+    `anyOf surfaces the closest variant's field issue: ${JSON.stringify(anyNone)}`,
+  );
+
+  // The "matched more than one" branch: genuinely overlapping (non-exclusive) variants. A value that
+  // satisfies two shapes is ambiguous and must be reported as such.
+  const overlapping: OpenApiSchema = { oneOf: [{ type: "integer" }, { type: "integer", minimum: 10 }] };
+  const ambiguous = validateValue(doc, overlapping, 20, "n");
+  assert.ok(
+    ambiguous.some((i) => /must match exactly one of the 2 allowed shapes, but matched 2/.test(i.message)),
+    `ambiguous (multi-match) is reported: ${JSON.stringify(ambiguous)}`,
+  );
+});
+
 test("undeclaredPathParams flags path-template params with no declared parameter", () => {
   const drift: OpenApiDoc = {
     openapi: "3.0.0",
@@ -608,3 +675,30 @@ test("responseSchemaForStatus: a status-range ('2XX') covers concrete statuses i
   assert.equal(responseSchemaForStatus(entries, 200)?.type, "string"); // 2XX class → range schema
   assert.equal(responseSchemaForStatus(entries, 404)?.type, "object"); // outside 2XX → default
 });
+
+test("sharedRequestBodySchemas: flags a requestBody $ref reused across operations, ignores single-use", () => {
+  const jsonRef = (ref: string) => ({ requestBody: { content: { "application/json": { schema: { $ref: ref } } } } });
+  const doc: OpenApiDoc = {
+    openapi: "3.1.0",
+    components: {
+      schemas: {
+        StartVariables: { type: "object" },
+        FeatureAnswer: { type: "object" },
+      },
+    },
+    paths: {
+      // Two operations share the SAME loose body schema — the defect fingerprint.
+      "/convergence": { post: { operationId: "startConvergenceLoop", ...jsonRef("#/components/schemas/StartVariables") } },
+      "/fanout": { post: { operationId: "startPlanFanout", ...jsonRef("#/components/schemas/StartVariables") } },
+      // A distinct, single-use body — must NOT be flagged.
+      "/feature": { post: { operationId: "answerFeature", ...jsonRef("#/components/schemas/FeatureAnswer") } },
+      // An inline (non-$ref) body — no shared identity to compare, must NOT be flagged.
+      "/inline": { post: { operationId: "inlineBody", requestBody: { content: { "application/json": { schema: { type: "object" } } } } } },
+    },
+  };
+
+  const shared = sharedRequestBodySchemas(doc);
+  assert.equal(shared.length, 1, `only the reused ref is flagged: ${JSON.stringify(shared)}`);
+  assert.equal(shared[0].ref, "#/components/schemas/StartVariables");
+  assert.deepEqual(shared[0].operationIds, ["startConvergenceLoop", "startPlanFanout"]); // sorted
+});

package/src/openapi/spec.ts

@@ -338,6 +338,32 @@ export 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 function sharedRequestBodySchemas(doc: OpenApiDoc): { ref: string; operationIds: string[] }[] {
+  const byRef = new Map<string, string[]>();
+  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: { ref: string; operationIds: string[] }[] = [];
+  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: OpenApiDoc): string[] {
@@ -697,6 +723,36 @@ function matchesAnyType(declared: string[], value: unknown): boolean {
   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: OpenApiDoc, variant: OpenApiSchema): string {
+  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: OpenApiDoc, variants: OpenApiSchema[]): string {
+  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: ValidationIssue[][]): ValidationIssue[] {
+  let best: ValidationIssue[] | undefined;
+  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(
@@ -743,13 +799,47 @@ export function validateValue(
   if (schema.allOf) {
     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: ValidationIssue[][] = [];
+    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)}`,
+      });
     }
   }
 

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

@@ -90,12 +90,15 @@ test("GET / serves the renderer shell with the home marker", async () => {
   assert.equal(res.status, 200);
   assert.match(res.headers?.["content-type"] ?? "", /text\/html/);
   assert.match(res.body ?? "", /data-home="home"/);
-  // The runtime module is loaded by a *relative* src so it resolves against the
-  // document's mount path — works both at the origin root and under the Nano
-  // console's /console/app-view/<name>/ reverse proxy. A root-absolute
-  // "/app/runtime.js" would 404 against the console origin and never hydrate.
-  assert.match(res.body ?? "", /src="\.\/app\/runtime\.js"/);
-  assert.doesNotMatch(res.body ?? "", /src="\/app\/runtime\.js"/);
+  // The runtime module is loaded by a *relative*, *content-fingerprinted* src so it resolves
+  // against the document's mount path — works both at the origin root and under the Nano
+  // console's /console/app-view/<name>/ reverse proxy. A root-absolute path would 404 against
+  // the console origin; a non-fingerprinted URL would let a stale browser cache replay an old
+  // module after an upgrade (silently breaking every page action).
+  assert.match(res.body ?? "", /src="\.\/app\/runtime\.[0-9a-f]{8}\.js"/);
+  assert.doesNotMatch(res.body ?? "", /src="\/app\/runtime\./);
+  // The shell itself must never be pinned by the browser (it carries the current module hash).
+  assert.match(res.headers?.["cache-control"] ?? "", /no-cache/);
 });
 
 test("the API docs badge links via a document-relative href (proxy-safe)", async () => {
@@ -145,6 +148,31 @@ test("GET /app/runtime.js serves the renderer module", async () => {
   assert.match(res.body ?? "", /function apiUrl\(u\)/);
 });
 
+test("the fingerprinted runtime URL from the shell is served immutable; the shell references it", async () => {
+  // The shell's <script src> must point at a route the router actually serves, and that route
+  // must carry long-lived immutable caching (the URL is unique per content, so it can never go
+  // stale). This is the cache-bust that stops an upgraded app from replaying an old module.
+  const shell = await dispatch("GET", "/");
+  const m = (shell.body ?? "").match(/src="\.(\/app\/runtime\.[0-9a-f]{8}\.js)"/);
+  assert.ok(m, "shell must reference a fingerprinted runtime URL");
+  const res = await dispatch("GET", m![1]);
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /javascript/);
+  assert.match(res.body ?? "", /pc:refresh/);
+  assert.match(res.headers?.["cache-control"] ?? "", /immutable/);
+  assert.match(res.headers?.["cache-control"] ?? "", /max-age=31536000/);
+});
+
+test("the legacy /app/runtime.js URL still serves the module, but no-cache", async () => {
+  // Back-compat + defence in depth: an old cached shell (or any client) hitting the unhashed URL
+  // still gets the current bytes, and `no-cache` forces revalidation instead of a stale replay.
+  const res = await dispatch("GET", "/app/runtime.js");
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /javascript/);
+  assert.match(res.body ?? "", /pc:refresh/);
+  assert.match(res.headers?.["cache-control"] ?? "", /no-cache/);
+});
+
 test("the shell renders an API-docs badge only when an apiDocsPath is provided", async () => {
   const routes = createPagesRoutes(
     { pagesDir: "pages", homePage: "home", sourceName: "app", apiDocsPath: "/app/api-docs" },

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

@@ -73,9 +73,18 @@ export interface PagesDeps {
   cancel?(processInstanceKey: string): Promise<CancelInstanceResult>;
 }
 
-/** A JavaScript-body response (the renderer module served at /app/runtime.js). */
-function javascript(body: string, status = 200): { status: number; headers: Record<string, string>; body: string } {
-  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: string,
+  status = 200,
+  extraHeaders?: Record<string, string>,
+): { status: number; headers: Record<string, string>; body: string } {
+  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
@@ -130,15 +139,30 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
 
   const routes: Route[] = [];
   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) ───────────────────────────
@@ -422,7 +446,7 @@ function rendererShell(homePage: string, apiDocsPath?: string): string {
   // 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
@@ -446,7 +470,7 @@ function rendererShell(homePage: string, apiDocsPath?: string): string {
 </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>`;
 }
@@ -1328,3 +1352,25 @@ 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: string): string {
+  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/src/toolkit/gen.test.ts

@@ -257,3 +257,35 @@ test("collectArtifacts resolves an ABSOLUTE api.spec at its own path, not root-r
   const res = await collectArtifacts({ root: "/app", io });
   assert.ok(res.map((a) => a.path).includes("nano-generated/api-io.d.ts"));
 });
+
+test("runGen warns when a requestBody schema is shared across operations, but never fails", async () => {
+  const manifest = JSON.stringify({ id: "demo", data: { default: "app" }, api: { spec: "openapi.json" } });
+  const openapi = JSON.stringify({
+    openapi: "3.1.0",
+    components: { schemas: { StartVariables: { type: "object", properties: { pr: { type: "string" }, url: { type: "string" }, issue: { type: "string" } } } } },
+    paths: {
+      "/convergence": { post: { operationId: "startConvergenceLoop", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/StartVariables" } } } }, responses: { "200": {} } } },
+      "/fanout": { post: { operationId: "startPlanFanout", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/StartVariables" } } } }, responses: { "200": {} } } },
+    },
+  });
+  const io = memIO({ "/app/nano.app.json": manifest, "/app/openapi.json": openapi });
+  const res = await runGen({ root: "/app", io });
+
+  assert.equal(res.incomplete, false); // advisory only — gen still succeeds
+  assert.equal(res.warnings.length, 1, `one shared-body warning: ${JSON.stringify(res.warnings)}`);
+  assert.match(res.warnings[0], /StartVariables/);
+  assert.match(res.warnings[0], /startConvergenceLoop, startPlanFanout/);
+  // A clean spec (distinct bodies) produces no warning.
+  const clean = memIO({
+    "/app/nano.app.json": manifest,
+    "/app/openapi.json": JSON.stringify({
+      openapi: "3.1.0",
+      components: { schemas: { A: { type: "object" }, B: { type: "object" } } },
+      paths: {
+        "/a": { post: { operationId: "opA", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/A" } } } }, responses: { "200": {} } } },
+        "/b": { post: { operationId: "opB", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/B" } } } }, responses: { "200": {} } } },
+      },
+    }),
+  });
+  assert.deepEqual((await runGen({ root: "/app", io: clean })).warnings, []);
+});

package/src/toolkit/gen.ts

@@ -11,7 +11,7 @@ import { deriveWorkerBindings, type ModelSource } from "./derivers/worker-io.ts"
 import { deriveMeta } from "./derivers/meta.ts";
 import { deriveMessageBindings } from "./derivers/messages.ts";
 import { deriveApi } from "./derivers/api.ts";
-import { parseSpec } from "../openapi/spec.ts";
+import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.ts";
 import { deriveModels, type DerivedModels, type ModelError, MODEL_PROVENANCE } from "./models.ts";
 
 /** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
@@ -57,6 +57,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[];
 }
 
 function join(root: string, rel: string): string {
@@ -118,7 +121,7 @@ export async function collectArtifacts(opts: GenOptions): Promise<DerivedArtifac
 
 /** Internal: collect artifacts AND the model-derivation details (needed by `runGen` for the
  * incomplete signal + the provenance-scoped stale sweep). */
-async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifact[]; derived: DerivedModels }> {
+async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifact[]; derived: DerivedModels; warnings: string[] }> {
   const { root, io } = opts;
   const emitModels = opts.emitModels ?? true;
   const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
@@ -128,6 +131,7 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
   } = JSON.parse(await io.readText(manifestPath));
 
   const artifacts: DerivedArtifact[] = [];
+  const warnings: string[] = [];
 
   // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
   if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
@@ -164,15 +168,25 @@ async function collectAll(opts: GenOptions): Promise<{ artifacts: DerivedArtifac
     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: GenOptions & { check?: boolean }): Promise<GenResult> {
-  const { artifacts, derived } = await collectAll(opts);
+  const { artifacts, derived, warnings } = await collectAll(opts);
   const { root, io } = opts;
   const emitModels = opts.emitModels ?? true;
   const drift: string[] = [];
@@ -224,7 +238,7 @@ export async function runGen(opts: GenOptions & { check?: boolean }): Promise<Ge
     }
   }
 
-  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 };