@webpieces/api-doc-model 0.4.806 → 0.4.808

package/src/model/ApiDocModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiDocModel.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/model/ApiDocModel.ts"],"names":[],"mappings":"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","sourcesContent":["import { TypeRef } from './TypeRef';\n\n/**\n * The model classes. Every one of them is a CLASS with an explicit constructor per `CLAUDE.md` §1 —\n * these are data-only structures, and a renderer (#982) builds nothing, it only reads.\n *\n * Nothing in this file imports anything but {@link TypeRef}: the package depends on `typescript` and\n * NOTHING else, so it can be pointed at any upstream project's contract. One app-specific import\n * here would end that, which is why `responsibilities.md` states the constraint rather than leaving\n * it to be discovered.\n */\n\n/** A type the extractor could not represent. RECORDED, never dropped — #982's guard needs a name. */\nexport class UnmappedType {\n    constructor(\n        /** The verbatim TypeScript type text, e.g. `Map<string, Widget>`. */\n        readonly typeText: string,\n        /** Pointer-style location: `path/to/File.ts:12:5`. */\n        readonly location: string,\n        /** Why it could not be mapped, in one sentence a renderer can print. */\n        readonly reason: string,\n    ) {}\n}\n\n/** The DERIVED discriminator of a union — never invented, only observed. See {@link DocumentedType}. */\nexport class UnionDiscriminator {\n    constructor(\n        /** The property every branch carries. */\n        readonly propertyName: string,\n        /** branch type name -> the single string literal that branch's property holds. */\n        readonly branchValues: ReadonlyMap<string, string>,\n    ) {}\n}\n\n/** One field of one DTO. */\nexport class DocumentedField {\n    constructor(\n        readonly name: string,\n        readonly type: TypeRef,\n        /**\n         * OPTIONAL (`name?: string`) — the property may be ABSENT. Distinguished from\n         * {@link nullable} on purpose: `{}` and `{name: null}` are different wire documents, and a\n         * renderer that conflates them emits a schema that rejects one of them.\n         */\n        readonly optional: boolean,\n        /** NULLABLE (`name: string | null`) — the property is present and may hold `null`. */\n        readonly nullable: boolean,\n        /** The JSDoc body, links flattened. Empty string when undocumented. */\n        readonly description: string,\n        /**\n         * The `@mcp` block tag — an OPTIONAL agent-facing override. Undefined means \"no override\",\n         * and a renderer falls back to {@link description}; the fallback is NOT applied here so a\n         * renderer can tell a deliberate agent-facing sentence from a reused human one.\n         */\n        readonly mcpDescription: string | undefined,\n        /** The `@format` tag, lifted onto the SCALAR (on an array, onto the ITEM). */\n        readonly format: string | undefined,\n        /** `@WpMin(n)` — numeric fields only; anything else is a build failure. */\n        readonly min: number | undefined,\n        /** `@WpMax(n)` — numeric fields only; anything else is a build failure. */\n        readonly max: number | undefined,\n        /**\n         * The `@mcpHeader <token>` JSDoc tag — the MCP 2026 SEP-2243 header this PRIMITIVE field is\n         * mirrored into (`Mcp-Param-{token}`). Undefined for every field that is not mirrored, which\n         * is nearly all of them.\n         *\n         * It is documentation and therefore lives in JSDoc, next to the sentence describing the\n         * field, rather than in a decorator argument. The runtime spells it `WpMcpHeader` inside\n         * `@WpDtoField`; the two are proved identical by the equivalence gate (#983) before #984\n         * deletes the decorator spelling.\n         */\n        readonly mcpHeader: string | undefined,\n    ) {}\n}\n\n/** One named type reachable from a contract: an object DTO, a string-literal enum, or a union. */\nexport class DocumentedType {\n    constructor(\n        readonly name: string,\n        readonly description: string,\n        /** Object shape. Empty for an enum or a union. */\n        readonly fields: readonly DocumentedField[],\n        /** Set for a string-literal union that has a name. */\n        readonly enumValues: readonly string[],\n        /** Set for a union of named object types. */\n        readonly unionRefNames: readonly string[],\n        /** Set only when EVERY branch carries the same property typed as one string literal. */\n        readonly discriminator: UnionDiscriminator | undefined,\n        /** An index signature (`[k: string]: X`) — the OPEN-MAP half of an object that also has fields. */\n        readonly indexSignatureValue: TypeRef | undefined,\n    ) {}\n}\n\n/** `@Endpoint(httpMethod, path, operation, kind, options?)`'s LAST argument, as a document sees it. */\nexport class DocumentedEndpointOptions {\n    constructor(\n        readonly formPost: boolean,\n        /** `calledBy` — REQUIRED by the decorator for `external`, absent otherwise. */\n        readonly calledBy: string | undefined,\n        readonly callerKind: string | undefined,\n    ) {}\n}\n\n/**\n * The `@WpMcpTool(...)` declaration, when the method carries one — the TWO facts the source cannot\n * otherwise state, and nothing else.\n *\n * `description` is deliberately NOT read off the decorator. The method's JSDoc is the description, for\n * the agent and for the partner alike, byte-identical: two authored copies of one paragraph is the\n * two-spellings shim, and its failure mode is concrete — the partner reads the JSDoc in the OpenAPI\n * document while the agent reads the decorator string in `tools/list`, and they drift the first time\n * somebody edits one. (The field still exists on the decorator; #984 deletes it across its 29 call\n * sites. Nothing here reads it, so nothing here depends on a field that is about to disappear.)\n *\n * The three side-effect hints are not read either: they are COMPUTED from the endpoint's `operation`\n * by `mcpHintsForOperation` in `@webpieces/core-util`, which is the one place that mapping lives.\n * `READ | WRITE_IDEMPOTENT | WRITE` already says whether repeating a call is safe, so a hand-declared\n * hint would be a second answer to a question the contract has answered.\n */\nexport class DocumentedMcpTool {\n    constructor(\n        /**\n         * The STABLE protocol name. Deliberately independent of the method name, because renaming a\n         * method must not break a saved agent workflow.\n         */\n        readonly name: string,\n    ) {}\n}\n\n/**\n * ONE credential of an api-key regime, PARSED — `{ in: 'header', name: 'x-api-key' }` or\n * `{ in: 'bearer' }`.\n *\n * Parsed rather than left as source text because it is the one auth argument a renderer must turn\n * into a STRUCTURE: an OpenAPI `securityScheme` is `{type: apiKey, in, name}` or\n * `{type: http, scheme: bearer}`, and those are different documents. A renderer handed the string\n * `\"{ in: 'header', name: 'x-api-key' }\"` would have to parse TypeScript to emit either one, which\n * is this package's job and not a renderer's.\n */\nexport class DocumentedApiKeyCredential {\n    constructor(\n        /** `header` or `bearer`, verbatim from the declaration. */\n        readonly location: string,\n        /** The header name. Undefined for `bearer`, whose location IS `Authorization`. */\n        readonly name: string | undefined,\n        /** The prose a docs site renders on its authorization card. */\n        readonly description: string | undefined,\n    ) {}\n}\n\n/** `@WpAuthApiKey(regime, credentials)`, parsed. See {@link DocumentedApiKeyCredential}. */\nexport class DocumentedApiKey {\n    constructor(\n        readonly regime: string,\n        /**\n         * Every credential the regime requires, IN DECLARATION ORDER. They are an AND — all of them\n         * are presented together — and the order is the order a published document lists them in.\n         */\n        readonly credentials: readonly DocumentedApiKeyCredential[],\n    ) {}\n}\n\n/** WHICH credential an endpoint demands — `@WpAuthPublic`, `@WpAuthJwt`, … — verbatim from the source. */\nexport class DocumentedAuth {\n    constructor(\n        /** The decorator name as written, e.g. `WpAuthJwt`. */\n        readonly decorator: string,\n        /** Every argument's text, verbatim and in order. Empty for `@WpAuthPublic()`. */\n        readonly argumentTexts: readonly string[],\n        /**\n         * The PARSED api-key declaration, set only for `@WpAuthApiKey`. Every other decorator's\n         * argument is prose or a role list that a document quotes rather than restructures, so\n         * {@link argumentTexts} is all they need — see {@link DocumentedApiKeyCredential} for why\n         * this one is different.\n         */\n        readonly apiKey: DocumentedApiKey | undefined,\n    ) {}\n}\n\n/** One `@Endpoint` method of one contract. */\nexport class DocumentedEndpoint {\n    constructor(\n        readonly methodName: string,\n        /**\n         * `GET` or `POST`, constant-folded from `@Endpoint`'s FIRST argument. A document cannot be\n         * written without it — the verb is the key an operation hangs under in `paths`.\n         */\n        readonly httpMethod: string,\n        /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */\n        readonly path: string,\n        /**\n         * `read` | `write-idempotent` | `write`, verbatim. The SIDE-EFFECT contract, which is\n         * independent of the verb: webpieces POSTs a read. A renderer publishes it rather than\n         * inferring safety from the verb, which for this framework would be wrong.\n         */\n        readonly operation: string,\n        /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */\n        readonly kind: string,\n        /**\n         * `{ hidden: true }` — this method is absent from the CUSTOMER document. It stays in the\n         * private one, and in the MCP one when it is a tool. WHICH documents the CONTRACT feeds at\n         * all is a different, class-level decision; see {@link ApiDocModel.apiTypes}.\n         */\n        readonly hidden: boolean,\n        /** `{ openWorld: true }` — this operation may touch systems outside this service. */\n        readonly openWorld: boolean,\n        readonly options: DocumentedEndpointOptions,\n        readonly auth: DocumentedAuth | undefined,\n        readonly mcpTool: DocumentedMcpTool | undefined,\n        /** `@WpMcpAuthJwt(...)`'s argument text, when present. */\n        readonly mcpAuthText: string | undefined,\n        /** `@MaskLog({...})` — field name -> mask mode. */\n        readonly maskLog: ReadonlyMap<string, string>,\n        readonly description: string,\n        /** The `@mcp` override. See {@link DocumentedField.mcpDescription}. */\n        readonly mcpDescription: string | undefined,\n        readonly request: TypeRef | undefined,\n        readonly response: TypeRef | undefined,\n    ) {}\n}\n\n/** ONE extraction pass over ONE contract file. Both #982's renderers read exactly this. */\nexport class ApiDocModel {\n    constructor(\n        /** The contract class name, e.g. `SaveApi`. */\n        readonly contractName: string,\n        /**\n         * WHICH generated documents this contract feeds — `svc-to-svc`, `external-customer`, `mcp`,\n         * verbatim from `@ApiType(...)`, defaulting to `svc-to-svc` alone when it declares nothing.\n         *\n         * A named list rather than a falsy default, because the grant has to be the TOKEN: a default\n         * that reached customers would publish a contract whose author typed nothing about it.\n         */\n        readonly apiTypes: readonly string[],\n        /** `@ApiPath(...)`, constant-folded. */\n        readonly basePath: string,\n        /** The JSDoc on the contract class, links flattened. */\n        readonly description: string,\n        readonly endpoints: readonly DocumentedEndpoint[],\n        /** Every named type reachable from the endpoints, by name. A `$ref` target for a renderer. */\n        readonly types: ReadonlyMap<string, DocumentedType>,\n        /** Everything that could not be represented — recorded, not dropped. */\n        readonly unmapped: readonly UnmappedType[],\n    ) {}\n}\n"]}
+{"version":3,"file":"ApiDocModel.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/model/ApiDocModel.ts"],"names":[],"mappings":"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","sourcesContent":["import { TypeRef } from './TypeRef';\n\n/**\n * The model classes. Every one of them is a CLASS with an explicit constructor per `CLAUDE.md` §1 —\n * these are data-only structures, and a renderer (#982) builds nothing, it only reads.\n *\n * Nothing in this file imports anything but {@link TypeRef}: the package depends on `typescript` and\n * NOTHING else, so it can be pointed at any upstream project's contract. One app-specific import\n * here would end that, which is why `responsibilities.md` states the constraint rather than leaving\n * it to be discovered.\n */\n\n/** A type the extractor could not represent. RECORDED, never dropped — #982's guard needs a name. */\nexport class UnmappedType {\n    constructor(\n        /** The verbatim TypeScript type text, e.g. `Map<string, Widget>`. */\n        readonly typeText: string,\n        /** Pointer-style location: `path/to/File.ts:12:5`. */\n        readonly location: string,\n        /** Why it could not be mapped, in one sentence a renderer can print. */\n        readonly reason: string,\n    ) {}\n}\n\n/** The DERIVED discriminator of a union — never invented, only observed. See {@link DocumentedType}. */\nexport class UnionDiscriminator {\n    constructor(\n        /** The property every branch carries. */\n        readonly propertyName: string,\n        /** branch type name -> the single string literal that branch's property holds. */\n        readonly branchValues: ReadonlyMap<string, string>,\n    ) {}\n}\n\n/** One field of one DTO. */\nexport class DocumentedField {\n    constructor(\n        readonly name: string,\n        readonly type: TypeRef,\n        /**\n         * OPTIONAL (`name?: string`) — the property may be ABSENT. Distinguished from\n         * {@link nullable} on purpose: `{}` and `{name: null}` are different wire documents, and a\n         * renderer that conflates them emits a schema that rejects one of them.\n         */\n        readonly optional: boolean,\n        /** NULLABLE (`name: string | null`) — the property is present and may hold `null`. */\n        readonly nullable: boolean,\n        /** The JSDoc body, links flattened. Empty string when undocumented. */\n        readonly description: string,\n        /**\n         * The `@mcp` block tag — an OPTIONAL agent-facing override. Undefined means \"no override\",\n         * and a renderer falls back to {@link description}; the fallback is NOT applied here so a\n         * renderer can tell a deliberate agent-facing sentence from a reused human one.\n         */\n        readonly mcpDescription: string | undefined,\n        /** The `@format` tag, lifted onto the SCALAR (on an array, onto the ITEM). */\n        readonly format: string | undefined,\n        /** `@WpMin(n)` — numeric fields only; anything else is a build failure. */\n        readonly min: number | undefined,\n        /** `@WpMax(n)` — numeric fields only; anything else is a build failure. */\n        readonly max: number | undefined,\n        /**\n         * The `@mcpHeader <token>` JSDoc tag — the MCP 2026 SEP-2243 header this PRIMITIVE field is\n         * mirrored into (`Mcp-Param-{token}`). Undefined for every field that is not mirrored, which\n         * is nearly all of them.\n         *\n         * It is documentation and therefore lives in JSDoc, next to the sentence describing the\n         * field, rather than in a decorator argument — and since #984 it is the only spelling of the\n         * fact at all.\n         */\n        readonly mcpHeader: string | undefined,\n    ) {}\n}\n\n/** One named type reachable from a contract: an object DTO, a string-literal enum, or a union. */\nexport class DocumentedType {\n    constructor(\n        readonly name: string,\n        readonly description: string,\n        /** Object shape. Empty for an enum or a union. */\n        readonly fields: readonly DocumentedField[],\n        /** Set for a string-literal union that has a name. */\n        readonly enumValues: readonly string[],\n        /** Set for a union of named object types. */\n        readonly unionRefNames: readonly string[],\n        /** Set only when EVERY branch carries the same property typed as one string literal. */\n        readonly discriminator: UnionDiscriminator | undefined,\n        /** An index signature (`[k: string]: X`) — the OPEN-MAP half of an object that also has fields. */\n        readonly indexSignatureValue: TypeRef | undefined,\n    ) {}\n}\n\n/** `@Endpoint(httpMethod, path, operation, kind, options?)`'s LAST argument, as a document sees it. */\nexport class DocumentedEndpointOptions {\n    constructor(\n        readonly formPost: boolean,\n        /** `calledBy` — REQUIRED by the decorator for `external`, absent otherwise. */\n        readonly calledBy: string | undefined,\n        readonly callerKind: string | undefined,\n    ) {}\n}\n\n/**\n * The `@WpMcpTool('search_stores')` declaration, when the method carries one — the ONE fact the\n * source cannot otherwise state, and nothing else.\n *\n * `description` used to sit on the decorator too. The method's JSDoc is the description, for the\n * agent and for the partner alike, byte-identical: two authored copies of one paragraph is the\n * two-spellings shim, and its failure mode is concrete — the partner reads the JSDoc in the OpenAPI\n * document while the agent reads the decorator string in `tools/list`, and they drift the first time\n * somebody edits one. #984 deleted it, which left the decorator holding one field, so it takes the\n * name as a plain string.\n *\n * The three side-effect hints are COMPUTED from the endpoint's `operation` by `mcpHintsForOperation`\n * in `@webpieces/core-util`, which is the one place that mapping lives — `READ | WRITE_IDEMPOTENT |\n * WRITE` already says whether repeating a call is safe, so a hand-declared hint would be a second\n * answer to a question the contract has answered. `openWorldHint` is `@Endpoint`'s `openWorld`.\n */\nexport class DocumentedMcpTool {\n    constructor(\n        /**\n         * The STABLE protocol name. Deliberately independent of the method name, because renaming a\n         * method must not break a saved agent workflow.\n         */\n        readonly name: string,\n    ) {}\n}\n\n/**\n * ONE credential of an api-key regime, PARSED — `{ in: 'header', name: 'x-api-key' }` or\n * `{ in: 'bearer' }`.\n *\n * Parsed rather than left as source text because it is the one auth argument a renderer must turn\n * into a STRUCTURE: an OpenAPI `securityScheme` is `{type: apiKey, in, name}` or\n * `{type: http, scheme: bearer}`, and those are different documents. A renderer handed the string\n * `\"{ in: 'header', name: 'x-api-key' }\"` would have to parse TypeScript to emit either one, which\n * is this package's job and not a renderer's.\n */\nexport class DocumentedApiKeyCredential {\n    constructor(\n        /** `header` or `bearer`, verbatim from the declaration. */\n        readonly location: string,\n        /** The header name. Undefined for `bearer`, whose location IS `Authorization`. */\n        readonly name: string | undefined,\n        /** The prose a docs site renders on its authorization card. */\n        readonly description: string | undefined,\n    ) {}\n}\n\n/** `@WpAuthApiKey(regime, credentials)`, parsed. See {@link DocumentedApiKeyCredential}. */\nexport class DocumentedApiKey {\n    constructor(\n        readonly regime: string,\n        /**\n         * Every credential the regime requires, IN DECLARATION ORDER. They are an AND — all of them\n         * are presented together — and the order is the order a published document lists them in.\n         */\n        readonly credentials: readonly DocumentedApiKeyCredential[],\n    ) {}\n}\n\n/** WHICH credential an endpoint demands — `@WpAuthPublic`, `@WpAuthJwt`, … — verbatim from the source. */\nexport class DocumentedAuth {\n    constructor(\n        /** The decorator name as written, e.g. `WpAuthJwt`. */\n        readonly decorator: string,\n        /** Every argument's text, verbatim and in order. Empty for `@WpAuthPublic()`. */\n        readonly argumentTexts: readonly string[],\n        /**\n         * The PARSED api-key declaration, set only for `@WpAuthApiKey`. Every other decorator's\n         * argument is prose or a role list that a document quotes rather than restructures, so\n         * {@link argumentTexts} is all they need — see {@link DocumentedApiKeyCredential} for why\n         * this one is different.\n         */\n        readonly apiKey: DocumentedApiKey | undefined,\n    ) {}\n}\n\n/** One `@Endpoint` method of one contract. */\nexport class DocumentedEndpoint {\n    constructor(\n        readonly methodName: string,\n        /**\n         * `GET` or `POST`, constant-folded from `@Endpoint`'s FIRST argument. A document cannot be\n         * written without it — the verb is the key an operation hangs under in `paths`.\n         */\n        readonly httpMethod: string,\n        /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */\n        readonly path: string,\n        /**\n         * `read` | `write-idempotent` | `write`, verbatim. The SIDE-EFFECT contract, which is\n         * independent of the verb: webpieces POSTs a read. A renderer publishes it rather than\n         * inferring safety from the verb, which for this framework would be wrong.\n         */\n        readonly operation: string,\n        /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */\n        readonly kind: string,\n        /**\n         * `{ hidden: true }` — this method is absent from the CUSTOMER document. It stays in the\n         * private one, and in the MCP one when it is a tool. WHICH documents the CONTRACT feeds at\n         * all is a different, class-level decision; see {@link ApiDocModel.apiTypes}.\n         */\n        readonly hidden: boolean,\n        /** `{ openWorld: true }` — this operation may touch systems outside this service. */\n        readonly openWorld: boolean,\n        readonly options: DocumentedEndpointOptions,\n        readonly auth: DocumentedAuth | undefined,\n        readonly mcpTool: DocumentedMcpTool | undefined,\n        /** `@WpMcpAuthJwt(...)`'s argument text, when present. */\n        readonly mcpAuthText: string | undefined,\n        /** `@MaskLog({...})` — field name -> mask mode. */\n        readonly maskLog: ReadonlyMap<string, string>,\n        readonly description: string,\n        /** The `@mcp` override. See {@link DocumentedField.mcpDescription}. */\n        readonly mcpDescription: string | undefined,\n        readonly request: TypeRef | undefined,\n        readonly response: TypeRef | undefined,\n    ) {}\n}\n\n/** ONE extraction pass over ONE contract file. Both #982's renderers read exactly this. */\nexport class ApiDocModel {\n    constructor(\n        /** The contract class name, e.g. `SaveApi`. */\n        readonly contractName: string,\n        /**\n         * WHICH generated documents this contract feeds — `svc-to-svc`, `external-customer`, `mcp`,\n         * verbatim from `@ApiType(...)`, defaulting to `svc-to-svc` alone when it declares nothing.\n         *\n         * A named list rather than a falsy default, because the grant has to be the TOKEN: a default\n         * that reached customers would publish a contract whose author typed nothing about it.\n         */\n        readonly apiTypes: readonly string[],\n        /** `@ApiPath(...)`, constant-folded. */\n        readonly basePath: string,\n        /** The JSDoc on the contract class, links flattened. */\n        readonly description: string,\n        readonly endpoints: readonly DocumentedEndpoint[],\n        /** Every named type reachable from the endpoints, by name. A `$ref` target for a renderer. */\n        readonly types: ReadonlyMap<string, DocumentedType>,\n        /** Everything that could not be represented — recorded, not dropped. */\n        readonly unmapped: readonly UnmappedType[],\n    ) {}\n}\n"]}

package/src/render/McpSchemaRenderer.d.ts

@@ -1,41 +1,81 @@
-import { ApiDocModel } from '../model/ApiDocModel';
-import { McpToolDefinition } from './McpToolDefinition';
+import { McpToolCatalog, McpToolDefinition } from '@webpieces/core-util';
+import { ApiDocModel, DocumentedEndpoint } from '../model/ApiDocModel';
+/** ONE `@WpMcpTool` the build could not give a schema, and why. See {@link McpSchemaRenderer.catalogOf}. */
+export declare class SkippedMcpTool {
+    /** The stable protocol name it declared. */
+    readonly name: string;
+    readonly contractName: string;
+    /** The render refusal, verbatim, including the declaration it points at. */
+    readonly reason: string;
+    constructor(
+    /** The stable protocol name it declared. */
+    name: string, contractName: string, 
+    /** The render refusal, verbatim, including the declaration it points at. */
+    reason: string);
+    toString(): string;
+}
+/** What one catalog render produced: the tools, and the ones it could not produce. */
+export declare class McpCatalogRender {
+    readonly catalog: McpToolCatalog;
+    readonly skipped: readonly SkippedMcpTool[];
+    constructor(catalog: McpToolCatalog, skipped: readonly SkippedMcpTool[]);
+}
 /**
- * `ApiDocModel` -> the MCP tool list, in exactly the shape `DtoSchemaBuilder` produces at boot from
- * reflect-metadata.
- *
- * ## Why this exists at all, and why it is READ-ONLY
+ * `ApiDocModel` -> the MCP tool list an agent is shown, and the server accepts calls against.
  *
- * #984 wants the MCP runtime off reflect-metadata, which deletes every erasure-repair argument of
- * `@WpDtoField` — `required`, `arrayItems`, `integer`, `minimum`, `maximum`, `enumValues`. That is a
- * behaviour change on a live protocol surface, and its failure mode is silent: a tool whose input
- * schema quietly loses a `required` entry or an `enum` starts failing agent calls at RUNTIME, not at
- * build. This renderer plus the equivalence spec beside it turn "the compiler can obviously replace
- * those arguments" from a plausible argument into a MEASURED one (#983).
+ * ## It is the ONLY source of an MCP schema
  *
- * ## It deliberately reproduces `DtoSchemaBuilder`, defect-for-defect
+ * It was written for #983 as a MEASUREMENT: it rendered the same `ApiJsonSchema` the reflect-metadata
+ * runtime built, so the two could be compared field by field. They matched for every DTO shape the
+ * runtime could build, which is what licensed #984 to delete `@WpDtoField` and its erasure-repair
+ * arguments — `required`, `arrayItems`, `integer`, `minimum`, `maximum`, `enumValues`, `mapValues`,
+ * `mcpHeader` — along with `DtoSchemaBuilder` itself. There is now one schema, built here, written to
+ * `mcp-tools.json` by `wp-openapi`, and read at boot by `McpToolRegistry`.
  *
- * Where MCP's `ApiJsonSchema` subset could express MORE than the runtime does, this renderer emits
- * what the RUNTIME emits, and the gate's report names the difference. Three concrete cases:
+ * ## Where it now goes FURTHER than the deleted runtime could
  *
- * - **NULLABLE is not rendered.** `ApiJsonSchema.type` holds one string, so `type: [T, "null"]` is
- *   not expressible in the type the runtime publishes. The compiler can SEE `externalId: string | null`
- *   and the runtime cannot; emitting it here would fail the gate on a difference that is a runtime
- *   capability GAP rather than an extractor bug, and hide the real mismatches under it.
- * - **A nested DTO is INLINED**, with the FIELD's prose on it, because `buildAt` inlines and then
- *   `fieldSchema` overwrites `description`. MCP has no `$ref`.
- * - **A bound on an ARRAY of numbers** is put on the ITEM, where OpenAPI puts it; the runtime cannot
- *   express it at all (`@WpDtoField` rejects numeric constraints on a non-`Number` field).
+ * The three reproductions #983 documented were runtime capability gaps, and two of them are closed:
  *
- * Making the comparison agree by WEAKENING it would destroy the only thing the gate is for, so every
- * one of those is a documented, deliberate reproduction rather than a relaxation.
+ * - **NULLABLE is rendered**, as `type: [T, "null"]`. `ApiJsonSchema.type` used to hold one string,
+ *   so the runtime could not write it down even where the compiler could see `externalId: string | null`
+ *   — and `{}` and `{externalId: null}` are different wire documents. `type` is now
+ *   `ApiJsonSchemaType | readonly ApiJsonSchemaType[]` and the union is emitted.
+ * - **A bound on an ARRAY of numbers** lands on the ITEM, where OpenAPI puts it. `@WpDtoField`
+ *   rejected numeric constraints on a non-`Number` field, so it had nowhere to go at all.
+ * - **A nested DTO is INLINED**, with the FIELD's prose on it — not a gap but the protocol: MCP tool
+ *   schemas are inline and have no `$ref`.
  */
 export declare class McpSchemaRenderer {
     private readonly model;
     constructor(model: ApiDocModel);
     /** Every `@WpMcpTool` method of the contract, in declaration order. */
     render(): readonly McpToolDefinition[];
-    private tool;
+    /**
+     * The tools of SEVERAL contracts as one catalog — the artifact a server boots from — plus every
+     * tool that could not be rendered and why.
+     *
+     * A catalog rather than a per-contract list because the protocol namespace is flat: two contracts
+     * declaring one tool name is a collision an agent would see, and {@link McpToolCatalog} refuses it
+     * here, at build time, rather than at somebody's boot.
+     *
+     * ## Why an unrenderable tool is REPORTED here rather than throwing
+     *
+     * Some shapes have no MCP schema at all — a recursive DTO, an undocumented tool, a request that
+     * is not a named object — and the first of those is a limit of the PROTOCOL rather than a defect
+     * in a contract that is otherwise perfectly good HTTP. (A DISCRIMINATED UNION used to be on this
+     * list and no longer is: #1009 taught `ApiJsonSchema` `oneOf`, so one publishes.) Such a
+     * tool was never servable: the reflect-metadata runtime refused it too, for its own reasons. So
+     * failing the whole document build over one would stop a repo publishing its OpenAPI over a tool
+     * nobody could ever have called.
+     *
+     * It is not silence either. The build NAMES every skipped tool with its reason, and
+     * `McpToolRegistry` REFUSES TO BOOT when a registered `@WpMcpTool` is missing from the catalog —
+     * which is the right place for that failure, because that is the process actually claiming to
+     * serve it.
+     */
+    static catalogOf(models: readonly ApiDocModel[]): McpCatalogRender;
+    /** ONE tool. Visible to {@link catalogOf}, which renders tool by tool so it can report one. */
+    tool(endpoint: DocumentedEndpoint): McpToolDefinition;
     /**
      * `operation` verbatim from the model, mapped back onto the REAL constant.
      *
@@ -44,27 +84,66 @@ export declare class McpSchemaRenderer {
      * are exhaustive, means falling off the end and publishing a tool with NO hints.
      */
     private static operationOf;
-    /** A tool's input/output schema: always a closed object, exactly as `DtoSchemaBuilder.build` is. */
+    /**
+     * A tool's input/output schema: always a CLOSED OBJECT, because MCP publishes objects — and
+     * because a union at the ROOT of a tool schema is refused by the function-calling APIs that
+     * consume it. Both OpenAI and Anthropic reject a top-level `oneOf`/`anyOf`/`allOf`, and a server
+     * sends its WHOLE tool list on every request, so one such tool makes every request 400 and bricks
+     * the session — not just that tool. Nested composition, inside a property, is fine.
+     *
+     * The build-time rule `no-root-union-api-type` refuses the same shape across every `@ApiPath`
+     * contract in the workspace, `@ApiType` or not. This is the renderer's own backstop, so a catalog
+     * can never carry one even if it is reached some other way.
+     */
     private rootSchema;
     private namedType;
     /**
-     * One object DTO. CLOSED (`additionalProperties: false`), `required` only when non-empty — both
-     * exactly as `DtoSchemaBuilder.buildAt` writes them, because that is what is being compared.
+     * One object DTO. CLOSED (`additionalProperties: false`), with `required` written only when it is
+     * non-empty, so an all-optional DTO carries no empty list.
      *
-     * The cycle stop is `parents`, and it THROWS rather than truncating, which is again what the
-     * runtime does: an inline schema cannot express a recursive DTO, and one that silently stopped a
-     * level down would publish a shape the server does not accept.
+     * The cycle stop is `parents`, and it THROWS rather than truncating: an inline schema cannot
+     * express a recursive DTO, and one that silently stopped a level down would publish a shape the
+     * server does not accept.
      */
     private objectSchema;
+    /**
+     * A UNION, as `oneOf` with its branches INLINE and its DERIVED discriminator.
+     *
+     * MCP tool schemas are JSON Schema 2020-12 — the same dialect OpenAPI 3.1 uses — so `oneOf` was
+     * never the obstacle; the obstacle was this repo's own subset, which had no spelling for it
+     * (#1009). The shape written here MIRRORS `SchemaRenderer.union` in `@webpieces/openapi-generator`
+     * branch for branch, because a union has ONE published spelling and that renderer is the
+     * reference implementation of it. The only difference is the absence of `$ref`: a tool schema is
+     * inline, so each branch is rendered in full and the discriminator maps to branch NAMES.
+     *
+     * `discriminator` is written ONLY when the model DERIVED one. A union TypeScript itself cannot
+     * narrow is published as a bare `oneOf` rather than with an invented discriminator — claiming a
+     * narrowing the source does not have is worse than admitting there is none.
+     */
+    private unionSchema;
+    /**
+     * A FIELD whose type is a union: the model registers `type X = A | B` as its OWN entry carrying
+     * the derived discriminator, while the field holds a bare list of branch names. Rendering that
+     * list directly would publish the `oneOf` and silently DROP the discriminator — the one part of a
+     * union a client needs to narrow on — so the alias is looked up by its branch list first. This is
+     * the same lookup `SchemaRenderer.namedUnion` does to emit its `$ref`.
+     */
+    private fieldUnion;
     /**
      * One FIELD: its type, then the prose and the constraints that hang off the field.
      *
-     * The ORDER matters and mirrors `fieldSchema`: the type is built first and `description` is
-     * written over whatever the type produced, so a nested DTO carries the FIELD's sentence rather
-     * than the DTO's. `@WpMin` / `@WpMax` land on the numeric LEAF — on an array, on the item — for
-     * the same reason `SchemaRenderer` puts them there: a `minimum` on an array means nothing.
+     * The ORDER matters: the type is built first and `description` is written over whatever the type
+     * produced, so a nested DTO carries the FIELD's sentence rather than the DTO's. `@WpMin` /
+     * `@WpMax` land on the numeric LEAF — on an array, on the item — for the same reason
+     * `SchemaRenderer` puts them there: a `minimum` on an array means nothing.
+     *
+     * NULLABLE widens the type to `[T, "null"]` and is deliberately NOT the same thing as OPTIONAL,
+     * which is an absent entry in the object's `required` list. `{}` and `{externalId: null}` are
+     * different wire documents, and an agent told only "optional" would send the wrong one.
      */
     private fieldSchema;
+    /** `T` -> `[T, "null"]`, refusing a field with no type at all rather than publishing `["null"]`. */
+    private static nullable;
     /**
      * `@mcpHeader` mirrors a PRIMITIVE parameter into `Mcp-Param-{name}` (MCP 2026 SEP-2243). The
      * three conditions are the runtime's, restated against the compiler's view of the field, so a

package/src/render/McpSchemaRenderer.js

@@ -1,40 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpSchemaRenderer = void 0;
+exports.McpSchemaRenderer = exports.McpCatalogRender = exports.SkippedMcpTool = void 0;
 const core_util_1 = require("@webpieces/core-util");
 const McpRenderError_1 = require("./McpRenderError");
-const McpToolDefinition_1 = require("./McpToolDefinition");
 /** RFC 9110 token, which is what an `Mcp-Param-{name}` header name has to be. */
 const HEADER_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** ONE `@WpMcpTool` the build could not give a schema, and why. See {@link McpSchemaRenderer.catalogOf}. */
+class SkippedMcpTool {
+    name;
+    contractName;
+    reason;
+    constructor(
+    /** The stable protocol name it declared. */
+    name, contractName, 
+    /** The render refusal, verbatim, including the declaration it points at. */
+    reason) {
+        this.name = name;
+        this.contractName = contractName;
+        this.reason = reason;
+    }
+    toString() {
+        return `${this.contractName}/${this.name}: ${this.reason}`;
+    }
+}
+exports.SkippedMcpTool = SkippedMcpTool;
+/** What one catalog render produced: the tools, and the ones it could not produce. */
+class McpCatalogRender {
+    catalog;
+    skipped;
+    constructor(catalog, skipped) {
+        this.catalog = catalog;
+        this.skipped = skipped;
+    }
+}
+exports.McpCatalogRender = McpCatalogRender;
 /**
- * `ApiDocModel` -> the MCP tool list, in exactly the shape `DtoSchemaBuilder` produces at boot from
- * reflect-metadata.
- *
- * ## Why this exists at all, and why it is READ-ONLY
+ * `ApiDocModel` -> the MCP tool list an agent is shown, and the server accepts calls against.
  *
- * #984 wants the MCP runtime off reflect-metadata, which deletes every erasure-repair argument of
- * `@WpDtoField` — `required`, `arrayItems`, `integer`, `minimum`, `maximum`, `enumValues`. That is a
- * behaviour change on a live protocol surface, and its failure mode is silent: a tool whose input
- * schema quietly loses a `required` entry or an `enum` starts failing agent calls at RUNTIME, not at
- * build. This renderer plus the equivalence spec beside it turn "the compiler can obviously replace
- * those arguments" from a plausible argument into a MEASURED one (#983).
+ * ## It is the ONLY source of an MCP schema
  *
- * ## It deliberately reproduces `DtoSchemaBuilder`, defect-for-defect
+ * It was written for #983 as a MEASUREMENT: it rendered the same `ApiJsonSchema` the reflect-metadata
+ * runtime built, so the two could be compared field by field. They matched for every DTO shape the
+ * runtime could build, which is what licensed #984 to delete `@WpDtoField` and its erasure-repair
+ * arguments — `required`, `arrayItems`, `integer`, `minimum`, `maximum`, `enumValues`, `mapValues`,
+ * `mcpHeader` — along with `DtoSchemaBuilder` itself. There is now one schema, built here, written to
+ * `mcp-tools.json` by `wp-openapi`, and read at boot by `McpToolRegistry`.
  *
- * Where MCP's `ApiJsonSchema` subset could express MORE than the runtime does, this renderer emits
- * what the RUNTIME emits, and the gate's report names the difference. Three concrete cases:
+ * ## Where it now goes FURTHER than the deleted runtime could
  *
- * - **NULLABLE is not rendered.** `ApiJsonSchema.type` holds one string, so `type: [T, "null"]` is
- *   not expressible in the type the runtime publishes. The compiler can SEE `externalId: string | null`
- *   and the runtime cannot; emitting it here would fail the gate on a difference that is a runtime
- *   capability GAP rather than an extractor bug, and hide the real mismatches under it.
- * - **A nested DTO is INLINED**, with the FIELD's prose on it, because `buildAt` inlines and then
- *   `fieldSchema` overwrites `description`. MCP has no `$ref`.
- * - **A bound on an ARRAY of numbers** is put on the ITEM, where OpenAPI puts it; the runtime cannot
- *   express it at all (`@WpDtoField` rejects numeric constraints on a non-`Number` field).
+ * The three reproductions #983 documented were runtime capability gaps, and two of them are closed:
  *
- * Making the comparison agree by WEAKENING it would destroy the only thing the gate is for, so every
- * one of those is a documented, deliberate reproduction rather than a relaxation.
+ * - **NULLABLE is rendered**, as `type: [T, "null"]`. `ApiJsonSchema.type` used to hold one string,
+ *   so the runtime could not write it down even where the compiler could see `externalId: string | null`
+ *   — and `{}` and `{externalId: null}` are different wire documents. `type` is now
+ *   `ApiJsonSchemaType | readonly ApiJsonSchemaType[]` and the union is emitted.
+ * - **A bound on an ARRAY of numbers** lands on the ITEM, where OpenAPI puts it. `@WpDtoField`
+ *   rejected numeric constraints on a non-`Number` field, so it had nowhere to go at all.
+ * - **A nested DTO is INLINED**, with the FIELD's prose on it — not a gap but the protocol: MCP tool
+ *   schemas are inline and have no `$ref`.
  */
 class McpSchemaRenderer {
     model;
@@ -51,6 +74,54 @@ class McpSchemaRenderer {
         }
         return tools;
     }
+    /**
+     * The tools of SEVERAL contracts as one catalog — the artifact a server boots from — plus every
+     * tool that could not be rendered and why.
+     *
+     * A catalog rather than a per-contract list because the protocol namespace is flat: two contracts
+     * declaring one tool name is a collision an agent would see, and {@link McpToolCatalog} refuses it
+     * here, at build time, rather than at somebody's boot.
+     *
+     * ## Why an unrenderable tool is REPORTED here rather than throwing
+     *
+     * Some shapes have no MCP schema at all — a recursive DTO, an undocumented tool, a request that
+     * is not a named object — and the first of those is a limit of the PROTOCOL rather than a defect
+     * in a contract that is otherwise perfectly good HTTP. (A DISCRIMINATED UNION used to be on this
+     * list and no longer is: #1009 taught `ApiJsonSchema` `oneOf`, so one publishes.) Such a
+     * tool was never servable: the reflect-metadata runtime refused it too, for its own reasons. So
+     * failing the whole document build over one would stop a repo publishing its OpenAPI over a tool
+     * nobody could ever have called.
+     *
+     * It is not silence either. The build NAMES every skipped tool with its reason, and
+     * `McpToolRegistry` REFUSES TO BOOT when a registered `@WpMcpTool` is missing from the catalog —
+     * which is the right place for that failure, because that is the process actually claiming to
+     * serve it.
+     */
+    // webpieces-disable no-function-outside-class -- static factory over this class
+    static catalogOf(models) {
+        const tools = [];
+        const skipped = [];
+        for (const model of models) {
+            const renderer = new McpSchemaRenderer(model);
+            for (const endpoint of model.endpoints) {
+                if (endpoint.mcpTool === undefined) {
+                    continue;
+                }
+                // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a per-tool render refusal is REPORTED, see the docstring
+                try {
+                    tools.push(renderer.tool(endpoint));
+                }
+                catch (err) {
+                    //const error = toError(err);
+                    if (!(err instanceof McpRenderError_1.McpRenderError))
+                        throw err;
+                    skipped.push(new SkippedMcpTool(endpoint.mcpTool.name, model.contractName, err.message));
+                }
+            }
+        }
+        return new McpCatalogRender(new core_util_1.McpToolCatalog(tools), skipped);
+    }
+    /** ONE tool. Visible to {@link catalogOf}, which renders tool by tool so it can report one. */
     tool(endpoint) {
         const where = `${this.model.contractName}.${endpoint.methodName}`;
         const description = endpoint.mcpDescription ?? endpoint.description;
@@ -61,7 +132,7 @@ class McpSchemaRenderer {
         if (endpoint.request === undefined || endpoint.response === undefined) {
             throw new McpRenderError_1.McpRenderError('an MCP tool has no declared request or response type', where, 'Declare both: one request parameter and a Promise<Response> return type.');
         }
-        return new McpToolDefinition_1.McpToolDefinition(endpoint.mcpTool.name, endpoint.methodName, description, (0, core_util_1.mcpHintsForOperation)(McpSchemaRenderer.operationOf(endpoint, where), endpoint.openWorld), this.rootSchema(endpoint.request, where, 'request'), this.rootSchema(endpoint.response, where, 'response'));
+        return new core_util_1.McpToolDefinition(endpoint.mcpTool.name, endpoint.methodName, description, (0, core_util_1.mcpHintsForOperation)(McpSchemaRenderer.operationOf(endpoint, where), endpoint.openWorld), this.rootSchema(endpoint.request, where, 'request'), this.rootSchema(endpoint.response, where, 'response'));
     }
     /**
      * `operation` verbatim from the model, mapped back onto the REAL constant.
@@ -83,13 +154,34 @@ class McpSchemaRenderer {
                 throw new McpRenderError_1.McpRenderError(`@Endpoint declares operation '${endpoint.operation}', which has no MCP hints`, where, `Use one of the exported constants: ${core_util_1.READ}, ${core_util_1.WRITE_IDEMPOTENT}, ${core_util_1.WRITE}.`);
         }
     }
-    /** A tool's input/output schema: always a closed object, exactly as `DtoSchemaBuilder.build` is. */
+    /**
+     * A tool's input/output schema: always a CLOSED OBJECT, because MCP publishes objects — and
+     * because a union at the ROOT of a tool schema is refused by the function-calling APIs that
+     * consume it. Both OpenAI and Anthropic reject a top-level `oneOf`/`anyOf`/`allOf`, and a server
+     * sends its WHOLE tool list on every request, so one such tool makes every request 400 and bricks
+     * the session — not just that tool. Nested composition, inside a property, is fine.
+     *
+     * The build-time rule `no-root-union-api-type` refuses the same shape across every `@ApiPath`
+     * contract in the workspace, `@ApiType` or not. This is the renderer's own backstop, so a catalog
+     * can never carry one even if it is reached some other way.
+     */
     rootSchema(ref, where, side) {
+        if (ref.kind === 'union') {
+            throw new McpRenderError_1.McpRenderError(`an MCP tool's ${side} is itself a union`, where, `Wrap it in a property of an object ${side} — a top-level oneOf is rejected by the ` +
+                'OpenAI and Anthropic function-calling APIs, and one such tool 400s every ' +
+                'request in the session.');
+        }
         if (ref.kind !== 'ref') {
             throw new McpRenderError_1.McpRenderError(`an MCP tool's ${side} is not a named DTO`, where, 'Give it a named interface or class. An inline or primitive ' +
                 `${side} has no object schema, and MCP publishes objects.`);
         }
-        return this.objectSchema(this.namedType(ref.refName, where), new Set());
+        const type = this.namedType(ref.refName, where);
+        if (type.unionRefNames.length > 0) {
+            throw new McpRenderError_1.McpRenderError(`an MCP tool's ${side} '${type.name}' is itself a union`, where, `Wrap it in a property of an object ${side} — a top-level oneOf is rejected by the ` +
+                'OpenAI and Anthropic function-calling APIs, and one such tool 400s every ' +
+                'request in the session.');
+        }
+        return this.objectSchema(type, new Set());
     }
     namedType(name, where) {
         const type = this.model.types.get(name);
@@ -99,12 +191,12 @@ class McpSchemaRenderer {
         return type;
     }
     /**
-     * One object DTO. CLOSED (`additionalProperties: false`), `required` only when non-empty — both
-     * exactly as `DtoSchemaBuilder.buildAt` writes them, because that is what is being compared.
+     * One object DTO. CLOSED (`additionalProperties: false`), with `required` written only when it is
+     * non-empty, so an all-optional DTO carries no empty list.
      *
-     * The cycle stop is `parents`, and it THROWS rather than truncating, which is again what the
-     * runtime does: an inline schema cannot express a recursive DTO, and one that silently stopped a
-     * level down would publish a shape the server does not accept.
+     * The cycle stop is `parents`, and it THROWS rather than truncating: an inline schema cannot
+     * express a recursive DTO, and one that silently stopped a level down would publish a shape the
+     * server does not accept.
      */
     objectSchema(type, parents) {
         if (parents.has(type.name)) {
@@ -112,7 +204,7 @@ class McpSchemaRenderer {
                 'inline and has no $ref to close a loop with.');
         }
         if (type.unionRefNames.length > 0) {
-            throw new McpRenderError_1.McpRenderError(`'${type.name}' is a union, which an MCP input schema cannot express`, type.name, 'Publish a single object shape to agents, or keep this contract off MCP.');
+            return this.unionSchema(type, parents);
         }
         if (type.indexSignatureValue !== undefined && type.fields.length > 0) {
             throw new McpRenderError_1.McpRenderError(`'${type.name}' has both named fields and an index signature`, type.name, 'Split the open map into a field of its own: a schema is either closed or a typed ' +
@@ -135,13 +227,70 @@ class McpSchemaRenderer {
         }
         return schema;
     }
+    /**
+     * A UNION, as `oneOf` with its branches INLINE and its DERIVED discriminator.
+     *
+     * MCP tool schemas are JSON Schema 2020-12 — the same dialect OpenAPI 3.1 uses — so `oneOf` was
+     * never the obstacle; the obstacle was this repo's own subset, which had no spelling for it
+     * (#1009). The shape written here MIRRORS `SchemaRenderer.union` in `@webpieces/openapi-generator`
+     * branch for branch, because a union has ONE published spelling and that renderer is the
+     * reference implementation of it. The only difference is the absence of `$ref`: a tool schema is
+     * inline, so each branch is rendered in full and the discriminator maps to branch NAMES.
+     *
+     * `discriminator` is written ONLY when the model DERIVED one. A union TypeScript itself cannot
+     * narrow is published as a bare `oneOf` rather than with an invented discriminator — claiming a
+     * narrowing the source does not have is worse than admitting there is none.
+     */
+    unionSchema(type, parents) {
+        const nested = new Set(parents);
+        nested.add(type.name);
+        const schema = new core_util_1.ApiJsonSchema();
+        schema.oneOf = type.unionRefNames.map((name) => this.objectSchema(this.namedType(name, type.name), nested));
+        if (type.description.trim() !== '') {
+            schema.description = type.description;
+        }
+        if (type.discriminator !== undefined) {
+            const mapping = {};
+            for (const branch of type.unionRefNames) {
+                const value = type.discriminator.branchValues.get(branch);
+                if (value !== undefined) {
+                    mapping[value] = branch;
+                }
+            }
+            schema.discriminator = new core_util_1.ApiJsonSchemaDiscriminator(type.discriminator.propertyName, mapping);
+        }
+        return schema;
+    }
+    /**
+     * A FIELD whose type is a union: the model registers `type X = A | B` as its OWN entry carrying
+     * the derived discriminator, while the field holds a bare list of branch names. Rendering that
+     * list directly would publish the `oneOf` and silently DROP the discriminator — the one part of a
+     * union a client needs to narrow on — so the alias is looked up by its branch list first. This is
+     * the same lookup `SchemaRenderer.namedUnion` does to emit its `$ref`.
+     */
+    fieldUnion(branchNames, where, parents) {
+        const key = branchNames.join(',');
+        for (const name of this.model.types.keys()) {
+            const candidate = this.model.types.get(name);
+            if (candidate.unionRefNames.length > 0 && candidate.unionRefNames.join(',') === key) {
+                return this.unionSchema(candidate, parents);
+            }
+        }
+        const schema = new core_util_1.ApiJsonSchema();
+        schema.oneOf = branchNames.map((name) => this.objectSchema(this.namedType(name, where), parents));
+        return schema;
+    }
     /**
      * One FIELD: its type, then the prose and the constraints that hang off the field.
      *
-     * The ORDER matters and mirrors `fieldSchema`: the type is built first and `description` is
-     * written over whatever the type produced, so a nested DTO carries the FIELD's sentence rather
-     * than the DTO's. `@WpMin` / `@WpMax` land on the numeric LEAF — on an array, on the item — for
-     * the same reason `SchemaRenderer` puts them there: a `minimum` on an array means nothing.
+     * The ORDER matters: the type is built first and `description` is written over whatever the type
+     * produced, so a nested DTO carries the FIELD's sentence rather than the DTO's. `@WpMin` /
+     * `@WpMax` land on the numeric LEAF — on an array, on the item — for the same reason
+     * `SchemaRenderer` puts them there: a `minimum` on an array means nothing.
+     *
+     * NULLABLE widens the type to `[T, "null"]` and is deliberately NOT the same thing as OPTIONAL,
+     * which is an absent entry in the object's `required` list. `{}` and `{externalId: null}` are
+     * different wire documents, and an agent told only "optional" would send the wrong one.
      */
     fieldSchema(owner, field, parents) {
         const where = `${owner.name}.${field.name}`;
@@ -163,8 +312,20 @@ class McpSchemaRenderer {
             McpSchemaRenderer.assertHeaderFits(field, schema, where);
             schema['x-mcp-header'] = field.mcpHeader;
         }
+        if (field.nullable) {
+            schema.type = McpSchemaRenderer.nullable(schema, where);
+        }
         return schema;
     }
+    /** `T` -> `[T, "null"]`, refusing a field with no type at all rather than publishing `["null"]`. */
+    // webpieces-disable no-function-outside-class -- private static mapping of this class
+    static nullable(schema, where) {
+        const base = core_util_1.ApiJsonSchema.baseTypeOf(schema);
+        if (base === undefined) {
+            throw new McpRenderError_1.McpRenderError('a nullable field has no other type', where, 'A field typed only `null` carries no information — give it a real type beside it.');
+        }
+        return [base, 'null'];
+    }
     /**
      * `@mcpHeader` mirrors a PRIMITIVE parameter into `Mcp-Param-{name}` (MCP 2026 SEP-2243). The
      * three conditions are the runtime's, restated against the compiler's view of the field, so a
@@ -203,7 +364,7 @@ class McpSchemaRenderer {
             case 'ref':
                 return this.referencedSchema(ref.refName, where, parents);
             case 'union':
-                throw new McpRenderError_1.McpRenderError('a union has no MCP input-schema shape', where, 'Publish one object shape to agents, or keep this method off MCP.');
+                return this.fieldUnion(ref.unionRefNames, where, parents);
             default:
                 throw new McpRenderError_1.McpRenderError(`no MCP schema for the declared type '${ref.unmappedText ?? '<unknown>'}'`, where, 'Give the field a shape the model can represent — a named DTO, an array of one, ' +
                     'a string-literal union, a Record, or a primitive.');