@webpieces/api-doc-model 0.4.803 → 0.4.805

package/src/model/ApiDocModel.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiDocModel = exports.DocumentedEndpoint = exports.DocumentedAuth = exports.DocumentedMcpTool = exports.DocumentedEndpointOptions = exports.DocumentedType = exports.DocumentedField = exports.UnionDiscriminator = exports.UnmappedType = void 0;
+exports.ApiDocModel = exports.DocumentedEndpoint = exports.DocumentedAuth = exports.DocumentedApiKey = exports.DocumentedApiKeyCredential = exports.DocumentedMcpTool = exports.DocumentedEndpointOptions = exports.DocumentedType = exports.DocumentedField = exports.UnionDiscriminator = exports.UnmappedType = void 0;
 /**
  * The model classes. Every one of them is a CLASS with an explicit constructor per `CLAUDE.md` §1 —
  * these are data-only structures, and a renderer (#982) builds nothing, it only reads.
@@ -53,6 +53,7 @@ class DocumentedField {
     format;
     min;
     max;
+    mcpHeader;
     constructor(name, type, 
     /**
      * OPTIONAL (`name?: string`) — the property may be ABSENT. Distinguished from
@@ -75,7 +76,18 @@ class DocumentedField {
     /** `@WpMin(n)` — numeric fields only; anything else is a build failure. */
     min, 
     /** `@WpMax(n)` — numeric fields only; anything else is a build failure. */
-    max) {
+    max, 
+    /**
+     * The `@mcpHeader <token>` JSDoc tag — the MCP 2026 SEP-2243 header this PRIMITIVE field is
+     * mirrored into (`Mcp-Param-{token}`). Undefined for every field that is not mirrored, which
+     * is nearly all of them.
+     *
+     * It is documentation and therefore lives in JSDoc, next to the sentence describing the
+     * field, rather than in a decorator argument. The runtime spells it `WpMcpHeader` inside
+     * `@WpDtoField`; the two are proved identical by the equivalence gate (#983) before #984
+     * deletes the decorator spelling.
+     */
+    mcpHeader) {
         this.name = name;
         this.type = type;
         this.optional = optional;
@@ -85,6 +97,7 @@ class DocumentedField {
         this.format = format;
         this.min = min;
         this.max = max;
+        this.mcpHeader = mcpHeader;
     }
 }
 exports.DocumentedField = DocumentedField;
@@ -118,7 +131,7 @@ class DocumentedType {
     }
 }
 exports.DocumentedType = DocumentedType;
-/** `@Endpoint(path, kind, options?)`'s third argument, as far as a document cares. */
+/** `@Endpoint(httpMethod, path, operation, kind, options?)`'s LAST argument, as a document sees it. */
 class DocumentedEndpointOptions {
     formPost;
     calledBy;
@@ -132,38 +145,108 @@ class DocumentedEndpointOptions {
     }
 }
 exports.DocumentedEndpointOptions = DocumentedEndpointOptions;
-/** The `@WpMcpTool(...)` declaration, when the method carries one. */
+/**
+ * The `@WpMcpTool(...)` declaration, when the method carries one — the TWO facts the source cannot
+ * otherwise state, and nothing else.
+ *
+ * `description` is deliberately NOT read off the decorator. The method's JSDoc is the description, for
+ * the agent and for the partner alike, byte-identical: two authored copies of one paragraph is the
+ * two-spellings shim, and its failure mode is concrete — the partner reads the JSDoc in the OpenAPI
+ * document while the agent reads the decorator string in `tools/list`, and they drift the first time
+ * somebody edits one. (The field still exists on the decorator; #984 deletes it across its 29 call
+ * sites. Nothing here reads it, so nothing here depends on a field that is about to disappear.)
+ *
+ * The three side-effect hints are not read either: they are COMPUTED from the endpoint's `operation`
+ * by `mcpHintsForOperation` in `@webpieces/core-util`, which is the one place that mapping lives.
+ * `READ | WRITE_IDEMPOTENT | WRITE` already says whether repeating a call is safe, so a hand-declared
+ * hint would be a second answer to a question the contract has answered.
+ */
 class DocumentedMcpTool {
     name;
-    hints;
-    constructor(name, 
-    /** The tool hints an agent reads — `readOnly`, `destructive`, `idempotent`, `openWorld`. */
-    hints) {
+    constructor(
+    /**
+     * The STABLE protocol name. Deliberately independent of the method name, because renaming a
+     * method must not break a saved agent workflow.
+     */
+    name) {
         this.name = name;
-        this.hints = hints;
     }
 }
 exports.DocumentedMcpTool = DocumentedMcpTool;
+/**
+ * ONE credential of an api-key regime, PARSED — `{ in: 'header', name: 'x-api-key' }` or
+ * `{ in: 'bearer' }`.
+ *
+ * Parsed rather than left as source text because it is the one auth argument a renderer must turn
+ * into a STRUCTURE: an OpenAPI `securityScheme` is `{type: apiKey, in, name}` or
+ * `{type: http, scheme: bearer}`, and those are different documents. A renderer handed the string
+ * `"{ in: 'header', name: 'x-api-key' }"` would have to parse TypeScript to emit either one, which
+ * is this package's job and not a renderer's.
+ */
+class DocumentedApiKeyCredential {
+    location;
+    name;
+    description;
+    constructor(
+    /** `header` or `bearer`, verbatim from the declaration. */
+    location, 
+    /** The header name. Undefined for `bearer`, whose location IS `Authorization`. */
+    name, 
+    /** The prose a docs site renders on its authorization card. */
+    description) {
+        this.location = location;
+        this.name = name;
+        this.description = description;
+    }
+}
+exports.DocumentedApiKeyCredential = DocumentedApiKeyCredential;
+/** `@WpAuthApiKey(regime, credentials)`, parsed. See {@link DocumentedApiKeyCredential}. */
+class DocumentedApiKey {
+    regime;
+    credentials;
+    constructor(regime, 
+    /**
+     * Every credential the regime requires, IN DECLARATION ORDER. They are an AND — all of them
+     * are presented together — and the order is the order a published document lists them in.
+     */
+    credentials) {
+        this.regime = regime;
+        this.credentials = credentials;
+    }
+}
+exports.DocumentedApiKey = DocumentedApiKey;
 /** WHICH credential an endpoint demands — `@WpAuthPublic`, `@WpAuthJwt`, … — verbatim from the source. */
 class DocumentedAuth {
     decorator;
-    argumentText;
+    argumentTexts;
+    apiKey;
     constructor(
     /** The decorator name as written, e.g. `WpAuthJwt`. */
     decorator, 
-    /** Its argument text, verbatim, when it took one. Undefined for `@WpAuthPublic()`. */
-    argumentText) {
+    /** Every argument's text, verbatim and in order. Empty for `@WpAuthPublic()`. */
+    argumentTexts, 
+    /**
+     * The PARSED api-key declaration, set only for `@WpAuthApiKey`. Every other decorator's
+     * argument is prose or a role list that a document quotes rather than restructures, so
+     * {@link argumentTexts} is all they need — see {@link DocumentedApiKeyCredential} for why
+     * this one is different.
+     */
+    apiKey) {
         this.decorator = decorator;
-        this.argumentText = argumentText;
+        this.argumentTexts = argumentTexts;
+        this.apiKey = apiKey;
     }
 }
 exports.DocumentedAuth = DocumentedAuth;
 /** One `@Endpoint` method of one contract. */
 class DocumentedEndpoint {
     methodName;
+    httpMethod;
     path;
+    operation;
     kind;
     hidden;
+    openWorld;
     options;
     auth;
     mcpTool;
@@ -174,10 +257,29 @@ class DocumentedEndpoint {
     request;
     response;
     constructor(methodName, 
+    /**
+     * `GET` or `POST`, constant-folded from `@Endpoint`'s FIRST argument. A document cannot be
+     * written without it — the verb is the key an operation hangs under in `paths`.
+     */
+    httpMethod, 
     /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */
     path, 
+    /**
+     * `read` | `write-idempotent` | `write`, verbatim. The SIDE-EFFECT contract, which is
+     * independent of the verb: webpieces POSTs a read. A renderer publishes it rather than
+     * inferring safety from the verb, which for this framework would be wrong.
+     */
+    operation, 
     /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */
-    kind, hidden, options, auth, mcpTool, 
+    kind, 
+    /**
+     * `{ hidden: true }` — this method is absent from the CUSTOMER document. It stays in the
+     * private one, and in the MCP one when it is a tool. WHICH documents the CONTRACT feeds at
+     * all is a different, class-level decision; see {@link ApiDocModel.apiTypes}.
+     */
+    hidden, 
+    /** `{ openWorld: true }` — this operation may touch systems outside this service. */
+    openWorld, options, auth, mcpTool, 
     /** `@WpMcpAuthJwt(...)`'s argument text, when present. */
     mcpAuthText, 
     /** `@MaskLog({...})` — field name -> mask mode. */
@@ -185,9 +287,12 @@ class DocumentedEndpoint {
     /** The `@mcp` override. See {@link DocumentedField.mcpDescription}. */
     mcpDescription, request, response) {
         this.methodName = methodName;
+        this.httpMethod = httpMethod;
         this.path = path;
+        this.operation = operation;
         this.kind = kind;
         this.hidden = hidden;
+        this.openWorld = openWorld;
         this.options = options;
         this.auth = auth;
         this.mcpTool = mcpTool;
@@ -203,6 +308,7 @@ exports.DocumentedEndpoint = DocumentedEndpoint;
 /** ONE extraction pass over ONE contract file. Both #982's renderers read exactly this. */
 class ApiDocModel {
     contractName;
+    apiTypes;
     basePath;
     description;
     endpoints;
@@ -211,6 +317,14 @@ class ApiDocModel {
     constructor(
     /** The contract class name, e.g. `SaveApi`. */
     contractName, 
+    /**
+     * WHICH generated documents this contract feeds — `svc-to-svc`, `external-customer`, `mcp`,
+     * verbatim from `@ApiType(...)`, defaulting to `svc-to-svc` alone when it declares nothing.
+     *
+     * A named list rather than a falsy default, because the grant has to be the TOKEN: a default
+     * that reached customers would publish a contract whose author typed nothing about it.
+     */
+    apiTypes, 
     /** `@ApiPath(...)`, constant-folded. */
     basePath, 
     /** The JSDoc on the contract class, links flattened. */
@@ -220,6 +334,7 @@ class ApiDocModel {
     /** Everything that could not be represented — recorded, not dropped. */
     unmapped) {
         this.contractName = contractName;
+        this.apiTypes = apiTypes;
         this.basePath = basePath;
         this.description = description;
         this.endpoints = endpoints;

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}\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(path, kind, options?)`'s third argument, as far as a document cares. */\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/** The `@WpMcpTool(...)` declaration, when the method carries one. */\nexport class DocumentedMcpTool {\n    constructor(\n        readonly name: string,\n        /** The tool hints an agent reads — `readOnly`, `destructive`, `idempotent`, `openWorld`. */\n        readonly hints: ReadonlyMap<string, boolean>,\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        /** Its argument text, verbatim, when it took one. Undefined for `@WpAuthPublic()`. */\n        readonly argumentText: string | undefined,\n    ) {}\n}\n\n/** One `@Endpoint` method of one contract. */\nexport class DocumentedEndpoint {\n    constructor(\n        readonly methodName: string,\n        /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */\n        readonly path: string,\n        /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */\n        readonly kind: string,\n        readonly hidden: 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        /** `@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. 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"]}

package/src/render/McpRenderError.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The ONE failure type the MCP renderer throws. A render either produces a COMPLETE set of tool
+ * definitions or throws this — it never emits a schema with a hole in it.
+ *
+ * An empty JSON Schema means "anything", so a field the renderer could not give a shape to would be
+ * published to agents as an unconstrained parameter. That is the same green-build-publishes-a-
+ * shapeless-field defect `SchemaRenderer`'s unmapped guard exists to stop, and here it is a THROW
+ * because the MCP projection has no document-level place to collect them into: a tool list is a flat
+ * array, and a tool with one shapeless parameter is a tool an agent will call wrongly.
+ *
+ * It carries `location` and `cure` as FIELDS, per `.claude/review/error-output.md`, and hand-numbers
+ * nothing. It is a sibling of `ApiDocExtractionError` rather than the same class because the two
+ * failures have different cures: an extraction failure is answered by editing the CONTRACT, and a
+ * render failure by editing the contract OR by accepting that MCP's schema subset cannot carry that
+ * shape at all.
+ */
+export declare class McpRenderError extends Error {
+    /** `Contract.method` or `Dto.field` — the declaration to open, not a file offset. */
+    readonly location: string;
+    /** What to do instead, in one sentence. No numbering — the caller's renderer owns that. */
+    readonly cure: string;
+    constructor(message: string, 
+    /** `Contract.method` or `Dto.field` — the declaration to open, not a file offset. */
+    location: string, 
+    /** What to do instead, in one sentence. No numbering — the caller's renderer owns that. */
+    cure: string);
+}

package/src/render/McpRenderError.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpRenderError = void 0;
+/**
+ * The ONE failure type the MCP renderer throws. A render either produces a COMPLETE set of tool
+ * definitions or throws this — it never emits a schema with a hole in it.
+ *
+ * An empty JSON Schema means "anything", so a field the renderer could not give a shape to would be
+ * published to agents as an unconstrained parameter. That is the same green-build-publishes-a-
+ * shapeless-field defect `SchemaRenderer`'s unmapped guard exists to stop, and here it is a THROW
+ * because the MCP projection has no document-level place to collect them into: a tool list is a flat
+ * array, and a tool with one shapeless parameter is a tool an agent will call wrongly.
+ *
+ * It carries `location` and `cure` as FIELDS, per `.claude/review/error-output.md`, and hand-numbers
+ * nothing. It is a sibling of `ApiDocExtractionError` rather than the same class because the two
+ * failures have different cures: an extraction failure is answered by editing the CONTRACT, and a
+ * render failure by editing the contract OR by accepting that MCP's schema subset cannot carry that
+ * shape at all.
+ */
+class McpRenderError extends Error {
+    location;
+    cure;
+    constructor(message, 
+    /** `Contract.method` or `Dto.field` — the declaration to open, not a file offset. */
+    location, 
+    /** What to do instead, in one sentence. No numbering — the caller's renderer owns that. */
+    cure) {
+        super(`${message} (${location})`);
+        this.location = location;
+        this.cure = cure;
+        this.name = 'McpRenderError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.McpRenderError = McpRenderError;
+//# sourceMappingURL=McpRenderError.js.map

package/src/render/McpRenderError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpRenderError.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/render/McpRenderError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,cAAe,SAAQ,KAAK;IAIxB;IAEA;IALb,YACI,OAAe;IACf,qFAAqF;IAC5E,QAAgB;IACzB,2FAA2F;IAClF,IAAY;QAErB,KAAK,CAAC,GAAG,OAAO,KAAK,QAAQ,GAAG,CAAC,CAAC;QAJzB,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,SAAI,GAAJ,IAAI,CAAQ;QAGrB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACtD,CAAC;CACJ;AAZD,wCAYC","sourcesContent":["/**\n * The ONE failure type the MCP renderer throws. A render either produces a COMPLETE set of tool\n * definitions or throws this — it never emits a schema with a hole in it.\n *\n * An empty JSON Schema means \"anything\", so a field the renderer could not give a shape to would be\n * published to agents as an unconstrained parameter. That is the same green-build-publishes-a-\n * shapeless-field defect `SchemaRenderer`'s unmapped guard exists to stop, and here it is a THROW\n * because the MCP projection has no document-level place to collect them into: a tool list is a flat\n * array, and a tool with one shapeless parameter is a tool an agent will call wrongly.\n *\n * It carries `location` and `cure` as FIELDS, per `.claude/review/error-output.md`, and hand-numbers\n * nothing. It is a sibling of `ApiDocExtractionError` rather than the same class because the two\n * failures have different cures: an extraction failure is answered by editing the CONTRACT, and a\n * render failure by editing the contract OR by accepting that MCP's schema subset cannot carry that\n * shape at all.\n */\nexport class McpRenderError extends Error {\n    constructor(\n        message: string,\n        /** `Contract.method` or `Dto.field` — the declaration to open, not a file offset. */\n        readonly location: string,\n        /** What to do instead, in one sentence. No numbering — the caller's renderer owns that. */\n        readonly cure: string,\n    ) {\n        super(`${message} (${location})`);\n        this.name = 'McpRenderError';\n        Object.setPrototypeOf(this, new.target.prototype);\n    }\n}\n"]}

package/src/render/McpSchemaRenderer.d.ts

@@ -0,0 +1,79 @@
+import { ApiDocModel } from '../model/ApiDocModel';
+import { McpToolDefinition } from './McpToolDefinition';
+/**
+ * `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
+ *
+ * #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 deliberately reproduces `DtoSchemaBuilder`, defect-for-defect
+ *
+ * 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:
+ *
+ * - **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).
+ *
+ * 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.
+ */
+export declare class McpSchemaRenderer {
+    private readonly model;
+    constructor(model: ApiDocModel);
+    /** Every `@WpMcpTool` method of the contract, in declaration order. */
+    render(): readonly McpToolDefinition[];
+    private tool;
+    /**
+     * `operation` verbatim from the model, mapped back onto the REAL constant.
+     *
+     * A `switch` and not a cast, because the model carries the operation as a string and a cast would
+     * hand `mcpHintsForOperation` a value it has no case for — which, for a function whose three arms
+     * 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. */
+    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.
+     *
+     * 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.
+     */
+    private objectSchema;
+    /**
+     * 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.
+     */
+    private fieldSchema;
+    /**
+     * `@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
+     * declaration the server would reject at boot fails the document build instead.
+     */
+    private static assertHeaderFits;
+    /** One resolved type, with no field-level prose or constraints on it. */
+    private typeSchema;
+    /** A named type: a string enum becomes `enum`, an object DTO is INLINED (MCP has no `$ref`). */
+    private referencedSchema;
+    private static primitive;
+}