@zuplo/runtime 7.12.7 → 7.13.1

package/out/esm/mocks/index.js

@@ -22,5 +22,5 @@
  *  DEALINGS IN THE SOFTWARE.
  *--------------------------------------------------------------------------------------------*/
     
-import{F as p,K as c,N as u}from"../chunk-N2ZQITZD.js";import"../chunk-WIQFTAJL.js";import{a as d}from"../chunk-QGAJTUPE.js";import"../chunk-A3QGJZO7.js";import{aa as i}from"../chunk-RH345HSZ.js";import"../chunk-UKQQD2JN.js";import{a as o}from"../chunk-TYV53J3B.js";function w(l={request:new Request("https://api.example.com")}){let e=[];function t(s){e.push(Promise.resolve(s))}return o(t,"waitUntil"),{context:new a({event:{waitUntil:t},route:l.route,originalRequest:l.request}),invokeResponse:o(async()=>{await Promise.all(e)},"invokeResponse")}}o(w,"createMockContext");var g={path:"/",methods:["GET"],handler:{module:{},export:"default"},raw:o(()=>({}),"raw")},a=class extends EventTarget{static{o(this,"MockZuploContext")}#e;#t;contextId;requestId;log;route;custom;incomingRequestProperties;parentContext;analyticsContext;constructor({event:e,route:t=g,parentContext:n,originalRequest:r}){super(),this.requestId=crypto.randomUUID(),this.contextId=crypto.randomUUID(),this.log={info:i.console.info,log:i.console.log,debug:i.console.debug,warn:i.console.warn,error:i.console.error,setLogProperties:o(()=>{},"setLogProperties")},this.custom={},this.route=t,this.incomingRequestProperties={ip:"203.0.113.7",asn:1234,asOrganization:"ORGANIZATION",city:"Seattle",region:"Washington",regionCode:"WA",colo:"SEA",continent:"NA",country:"US",postalCode:"98004",metroCode:"SEA",latitude:void 0,longitude:void 0,timezone:void 0,httpProtocol:void 0,clientCert:void 0,clientMtlsVerificationStatus:void 0,clientMtlsVerificationReason:void 0,clientCertFingerprintSha256:void 0,clientCertNotBefore:void 0,clientCertNotAfter:void 0,clientCertIssuerDn:void 0,clientCertSubjectDn:void 0},this.parentContext=n,this.#e=e,this.#t=r,this.analyticsContext=new c(this.requestId)}waitUntil(e){this.#e.waitUntil(e)}invokeInboundPolicy(e,t){throw new Error("Not implemented")}invokeOutboundPolicy(e,t,n){throw new Error("Not implemented")}invokeRoute(e,t){throw new Error("Not implemented")}addResponseSendingHook(e){throw new Error("Not implemented")}addResponseSendingFinalHook(e){throw new Error("Not implemented")}addPreRequestHandler(e,t){let n;try{n=u.getContextExtensions(this)}catch{n=u.initialize(this,new d(this.#t??new Request("https://api.example.com")))}n.preRequestPhase??="active",p(this,n,e,t)}get preRequestHandlers(){let e;try{e=u.getContextExtensions(this)}catch{return[]}return(e.preRequestState?.entries??[]).map(t=>({policyName:t.policyName,name:t.name}))}addEventListener(e,t,n){let r=o(s=>{try{typeof t=="function"?t(s):t.handleEvent(s)}catch(m){throw this.log.error(`Error invoking event ${e}. See following logs for details.`),m}},"wrapped");super.addEventListener(e,r,n)}};export{a as MockZuploContext,w as createMockContext};
+import{G as p,L as c,O as u}from"../chunk-3CVOCJ3Y.js";import"../chunk-ZCJ5QBVD.js";import{a as d}from"../chunk-QGAJTUPE.js";import"../chunk-A3QGJZO7.js";import{aa as i}from"../chunk-FQIUJWH2.js";import"../chunk-UKQQD2JN.js";import{a as o}from"../chunk-TYV53J3B.js";function w(l={request:new Request("https://api.example.com")}){let e=[];function t(s){e.push(Promise.resolve(s))}return o(t,"waitUntil"),{context:new a({event:{waitUntil:t},route:l.route,originalRequest:l.request}),invokeResponse:o(async()=>{await Promise.all(e)},"invokeResponse")}}o(w,"createMockContext");var g={path:"/",methods:["GET"],handler:{module:{},export:"default"},raw:o(()=>({}),"raw")},a=class extends EventTarget{static{o(this,"MockZuploContext")}#e;#t;contextId;requestId;log;route;custom;incomingRequestProperties;parentContext;analyticsContext;constructor({event:e,route:t=g,parentContext:n,originalRequest:r}){super(),this.requestId=crypto.randomUUID(),this.contextId=crypto.randomUUID(),this.log={info:i.console.info,log:i.console.log,debug:i.console.debug,warn:i.console.warn,error:i.console.error,setLogProperties:o(()=>{},"setLogProperties")},this.custom={},this.route=t,this.incomingRequestProperties={ip:"203.0.113.7",asn:1234,asOrganization:"ORGANIZATION",city:"Seattle",region:"Washington",regionCode:"WA",colo:"SEA",continent:"NA",country:"US",postalCode:"98004",metroCode:"SEA",latitude:void 0,longitude:void 0,timezone:void 0,httpProtocol:void 0,clientCert:void 0,clientMtlsVerificationStatus:void 0,clientMtlsVerificationReason:void 0,clientCertFingerprintSha256:void 0,clientCertNotBefore:void 0,clientCertNotAfter:void 0,clientCertIssuerDn:void 0,clientCertSubjectDn:void 0},this.parentContext=n,this.#e=e,this.#t=r,this.analyticsContext=new c(this.requestId)}waitUntil(e){this.#e.waitUntil(e)}invokeInboundPolicy(e,t){throw new Error("Not implemented")}invokeOutboundPolicy(e,t,n){throw new Error("Not implemented")}invokeRoute(e,t){throw new Error("Not implemented")}addResponseSendingHook(e){throw new Error("Not implemented")}addResponseSendingFinalHook(e){throw new Error("Not implemented")}addPreRequestHandler(e,t){let n;try{n=u.getContextExtensions(this)}catch{n=u.initialize(this,new d(this.#t??new Request("https://api.example.com")))}n.preRequestPhase??="active",p(this,n,e,t)}get preRequestHandlers(){let e;try{e=u.getContextExtensions(this)}catch{return[]}return(e.preRequestState?.entries??[]).map(t=>({policyName:t.policyName,name:t.name}))}addEventListener(e,t,n){let r=o(s=>{try{typeof t=="function"?t(s):t.handleEvent(s)}catch(m){throw this.log.error(`Error invoking event ${e}. See following logs for details.`),m}},"wrapped");super.addEventListener(e,r,n)}};export{a as MockZuploContext,w as createMockContext};
 //# sourceMappingURL=index.js.map

package/out/esm/sdks/aws/index.js

@@ -22,5 +22,5 @@
  *  DEALINGS IN THE SOFTWARE.
  *--------------------------------------------------------------------------------------------*/
     
-import{Ia as a,Ja as l,Ka as c,La as o,Oa as p,Pa as y,Qa as m}from"../../chunk-RH345HSZ.js";import"../../chunk-UKQQD2JN.js";import{a as i}from"../../chunk-TYV53J3B.js";async function g(r,e){let t=typeof e.credentials=="function"?await e.credentials():e.credentials,n=r.method,d=n!=="GET"&&n!=="HEAD"&&r.body!=null?await r.arrayBuffer():null,s=await new o({method:n,url:r.url,headers:r.headers,body:d,accessKeyId:t.accessKeyId,secretAccessKey:t.secretAccessKey,sessionToken:t.sessionToken,service:e.service,region:e.region,signQuery:e.signQuery}).sign();return new Request(s.url.toString(),{method:s.method,headers:s.headers,body:s.body})}i(g,"signRequest");export{c as AwsClient,o as AwsV4Signer,p as fromTemporaryCredentials,y as fromWebToken,m as fromZuploIdentity,l as getAwsCredentialProvider,a as setAwsCredentialProvider,g as signRequest};
+import{Ia as a,Ja as l,Ka as c,La as o,Oa as p,Pa as y,Qa as m}from"../../chunk-FQIUJWH2.js";import"../../chunk-UKQQD2JN.js";import{a as i}from"../../chunk-TYV53J3B.js";async function g(r,e){let t=typeof e.credentials=="function"?await e.credentials():e.credentials,n=r.method,d=n!=="GET"&&n!=="HEAD"&&r.body!=null?await r.arrayBuffer():null,s=await new o({method:n,url:r.url,headers:r.headers,body:d,accessKeyId:t.accessKeyId,secretAccessKey:t.secretAccessKey,sessionToken:t.sessionToken,service:e.service,region:e.region,signQuery:e.signQuery}).sign();return new Request(s.url.toString(),{method:s.method,headers:s.headers,body:s.body})}i(g,"signRequest");export{c as AwsClient,o as AwsV4Signer,p as fromTemporaryCredentials,y as fromWebToken,m as fromZuploIdentity,l as getAwsCredentialProvider,a as setAwsCredentialProvider,g as signRequest};
 //# sourceMappingURL=index.js.map

package/out/types/index.d.ts

@@ -3331,7 +3331,7 @@ declare type BlockedModels1 = [ProviderAndModel_2, ...ProviderAndModel_2[]];
 export declare class BrownoutInboundPolicy extends InboundPolicy<BrownoutInboundPolicyOptions> {
   static readonly policyType = "brownout";
   crons: Cron[];
-  constructor(options: BrownoutInboundPolicyOptions, policyName: string);
+  constructor(rawOptions: BrownoutInboundPolicyOptions, policyName: string);
   handler(
     request: ZuploRequest,
     context: ZuploContext
@@ -4302,40 +4302,40 @@ declare interface CompatibilityFlags {
    */
   return501ForUnsupportedHttpMethods: boolean;
   /**
-   * Retired: still accepted in `compatibilityFlags`, with no effect.
+   * Whether OpenAPI schemas are validated by the specifications they declare:
+   * the arguments of `mcpServerHandler`'s tools and prompts, and the requests
+   * `request-validation-inbound` checks.
    *
-   * The MCP server handler's `initialize` returns `capabilities.tools: {}` for
-   * every project, without the non-standard `supported` and `available`
-   * fields this flag used to remove. Clients discover tools with
-   * `tools/list`. See `packages/runtime/specs/mcp-json-rpc.md`, MCPRPC-26 to
-   * MCPRPC-28.
+   * Before this flag: `mcpServerHandler` builds tool and prompt validators at
+   * runtime from `context.route.raw()` with Zod, exactly as before build-time
+   * schemas (specs/mcp-tool-schemas-legacy.md); the build generates nothing
+   * for MCP.
    *
-   * @deprecated The behavior is unconditional; listing the flag changes
-   * nothing.
-   */
-  removeMcpToolsCapabilityExtension: boolean;
-  /**
-   * Retired: still accepted in `compatibilityFlags`, with no effect.
+   * After this flag: The build generates each tool's and prompt's schemas and
+   * precompiled Ajv validators from the OpenAPI document, validated per the
+   * dialect and OpenAPI version they declare (specs/mcp-tool-schemas.md), and
+   * `prompts/list` also lists the arguments behind a prompt schema's `$ref`
+   * and `allOf`. `request-validation-inbound` validates with the same dialect,
+   * `format` and pattern rules, and keeps its parameter type coercion
+   * (specs/compat-improved-schema-validation.md).
+   */
+  improvedSchemaValidation: boolean;
+  /**
+   * Whether the MCP server handler writes path, query and header tool
+   * arguments into the route request by each OpenAPI parameter's `style`,
+   * `explode`, `allowReserved` and `content`.
    *
-   * For every project, when the request's `MCP-Protocol-Version` header is
-   * `2025-11-25` or later, a `tools/call` whose arguments fail the tool's
-   * `inputSchema` returns a result with `isError: true` and the validation
-   * message as text content, and the tool is not called. Earlier or missing
-   * protocol versions return a JSON-RPC `-32602` error. See
-   * `packages/runtime/specs/mcp-json-rpc.md`, MCPRPC-19 to MCPRPC-25.
+   * Before this flag: Query arrays repeat the name, query objects are JSON
+   * text, path values are `String()` then `encodeURIComponent`, and header
+   * values are stringified (an object becomes `[object Object]`). The
+   * parameter's `style`, `explode`, `allowReserved` and `content` are ignored.
    *
-   * @deprecated The behavior is unconditional; listing the flag changes
-   * nothing.
-   */
-  returnMcpToolInputErrorsAsToolResults: boolean;
-  /**
-   * Before this flag: MCP input schemas are converted to Zod and back to JSON
-   * Schema, and Zod may insert defaults or discard undeclared properties.
-   * After this flag: the MCP SDK validates JSON Schema directly, preserving
-   * constraints and input values. Defaults remain annotations. HTTP validation is unchanged.
-   * Opt in only on the JavaScript runtimes (workerd and Zeno).
+   * After this flag: Each parameter is serialized as the OpenAPI 3.1
+   * Style Examples table says, for example `rgb[R]=100&rgb[G]=200` for a
+   * `deepObject` and `.blue.black.brown` for a path `label`. Values are
+   * percent-encoded as UTF-8 and a space is `%20`.
    */
-  useMcpDirectSchemaValidation: boolean;
+  serializeMcpParametersByStyle: boolean;
   /**
    * Whether the MCP server handler rewrites tool names to follow the MCP tool
    * naming rule: 1 to 128 characters of `A-Z`, `a-z`, `0-9`, `_`, `-` and
@@ -4386,6 +4386,27 @@ declare interface CompatibilityFlags {
    * `_meta` is sent on every version.
    */
   omitMcpFieldsNewerThanNegotiatedVersion: boolean;
+  /**
+   * Whether built-in policies treat an empty or whitespace-only value for an
+   * optional string option as if the option were left out.
+   *
+   * `$env(VAR)` with `VAR` defined but empty reaches a policy as `""`, so this
+   * decides what an empty environment variable does to an optional option.
+   *
+   * Before this flag: Many policies reject `""`. Some fail every request with
+   * a `ConfigurationError` (for example `http-deprecation-outbound` `link`,
+   * `openmeter-inbound` `apiUrl`, `upstream-aws-service-auth-inbound`
+   * `roleSessionName`). Others fail at request time (an `authHeader` of `""`
+   * is not a valid header name). A few use a whitespace-only value as given
+   * (a `"   "` brownout `problem.title`).
+   *
+   * After this flag: Those options behave exactly as if they were left out,
+   * and their default applies. Options where an empty value means something,
+   * secrets, and options whose unset default grants more access keep their
+   * current behavior. `BLANK_IS_NOT_UNSET` in
+   * `policies/optional-string-options.spec.ts` lists them with the reason.
+   */
+  treatBlankOptionalStringOptionsAsUnset: boolean;
 }
 
 declare interface CompletionsFallbacks {
@@ -6239,7 +6260,12 @@ export declare class Handler {
     runtimeEnvironment: RuntimeEnvironment,
     event: ZuploEventContext
   ) => Promise<Response>;
-  handleError(err: Error, detail: string, request: Request): Response;
+  handleError(
+    err: Error,
+    detail: string,
+    request: Request,
+    event: ZuploEventContext
+  ): Response;
 }
 
 /**
@@ -15177,7 +15203,7 @@ export declare class UpstreamAwsFederatedAuthInboundPolicy extends InboundPolicy
   #private;
   static readonly policyType = "upstream-aws-federated-auth";
   constructor(
-    options: UpstreamAwsFederatedAuthInboundPolicyOptions,
+    rawOptions: UpstreamAwsFederatedAuthInboundPolicyOptions,
     policyName: string
   );
   handler(
@@ -15246,7 +15272,7 @@ export declare class UpstreamAwsServiceAuthInboundPolicy extends InboundPolicy<U
   #private;
   static readonly policyType = "upstream-aws-service-auth";
   constructor(
-    options: UpstreamAwsServiceAuthInboundPolicyOptions,
+    rawOptions: UpstreamAwsServiceAuthInboundPolicyOptions,
     policyName: string
   );
   handler(
@@ -15609,7 +15635,7 @@ export declare class UpstreamOAuthClientCredentialsInboundPolicy extends Inbound
   #private;
   static readonly policyType = "upstream-oauth-client-credentials";
   constructor(
-    options: UpstreamOAuthClientCredentialsInboundPolicyOptions,
+    rawOptions: UpstreamOAuthClientCredentialsInboundPolicyOptions,
     policyName: string
   );
   handler(
@@ -15685,7 +15711,7 @@ export declare interface UpstreamOAuthClientCredentialsInboundPolicyOptions {
 export declare class UpstreamZuploJwtAuthInboundPolicy extends InboundPolicy<UpstreamZuploJwtAuthInboundPolicyOptions> {
   static readonly policyType = "upstream-zuplo-jwt";
   constructor(
-    options: UpstreamZuploJwtAuthInboundPolicyOptions,
+    rawOptions: UpstreamZuploJwtAuthInboundPolicyOptions,
     policyName: string
   );
   /**
@@ -16278,7 +16304,7 @@ export declare class XmlToJsonOutboundPolicy extends OutboundPolicy<XmlToJsonPol
   static readonly policyType = "xml-to-json";
   private parser;
   private parseOnStatusCodes;
-  constructor(options: XmlToJsonPolicyOptions, policyName: string);
+  constructor(rawOptions: XmlToJsonPolicyOptions, policyName: string);
   handler(
     response: Response,
     request: ZuploRequest,

package/out/types/internal/index.d.ts

@@ -4,6 +4,19 @@ export declare interface ApiRuntimeConfig {
   urls: UrlConfig | undefined;
 }
 
+/** A generated schema as the assembler reads it. */
+declare interface AssemblableSchema {
+  /** The schema root as JSON, referencing shared components with `$ref`. */
+  schema: string;
+  /** The key of the table the root's `#/$defs/<name>` references resolve in. */
+  defs?: string;
+  /**
+   * The `$schema` the advertised root carries, when the schema is not JSON
+   * Schema 2020-12 (MCPSCHEMA-2, MCPSCHEMA-23).
+   */
+  dialect?: string;
+}
+
 /**
  * Assigns each tool a name that follows the MCP tool naming rule and is
  * unique among `names`, deterministically. `names` are the configured names
@@ -160,40 +173,40 @@ declare interface CompatibilityFlags {
    */
   return501ForUnsupportedHttpMethods: boolean;
   /**
-   * Retired: still accepted in `compatibilityFlags`, with no effect.
+   * Whether OpenAPI schemas are validated by the specifications they declare:
+   * the arguments of `mcpServerHandler`'s tools and prompts, and the requests
+   * `request-validation-inbound` checks.
    *
-   * The MCP server handler's `initialize` returns `capabilities.tools: {}` for
-   * every project, without the non-standard `supported` and `available`
-   * fields this flag used to remove. Clients discover tools with
-   * `tools/list`. See `packages/runtime/specs/mcp-json-rpc.md`, MCPRPC-26 to
-   * MCPRPC-28.
+   * Before this flag: `mcpServerHandler` builds tool and prompt validators at
+   * runtime from `context.route.raw()` with Zod, exactly as before build-time
+   * schemas (specs/mcp-tool-schemas-legacy.md); the build generates nothing
+   * for MCP.
    *
-   * @deprecated The behavior is unconditional; listing the flag changes
-   * nothing.
-   */
-  removeMcpToolsCapabilityExtension: boolean;
-  /**
-   * Retired: still accepted in `compatibilityFlags`, with no effect.
+   * After this flag: The build generates each tool's and prompt's schemas and
+   * precompiled Ajv validators from the OpenAPI document, validated per the
+   * dialect and OpenAPI version they declare (specs/mcp-tool-schemas.md), and
+   * `prompts/list` also lists the arguments behind a prompt schema's `$ref`
+   * and `allOf`. `request-validation-inbound` validates with the same dialect,
+   * `format` and pattern rules, and keeps its parameter type coercion
+   * (specs/compat-improved-schema-validation.md).
+   */
+  improvedSchemaValidation: boolean;
+  /**
+   * Whether the MCP server handler writes path, query and header tool
+   * arguments into the route request by each OpenAPI parameter's `style`,
+   * `explode`, `allowReserved` and `content`.
    *
-   * For every project, when the request's `MCP-Protocol-Version` header is
-   * `2025-11-25` or later, a `tools/call` whose arguments fail the tool's
-   * `inputSchema` returns a result with `isError: true` and the validation
-   * message as text content, and the tool is not called. Earlier or missing
-   * protocol versions return a JSON-RPC `-32602` error. See
-   * `packages/runtime/specs/mcp-json-rpc.md`, MCPRPC-19 to MCPRPC-25.
+   * Before this flag: Query arrays repeat the name, query objects are JSON
+   * text, path values are `String()` then `encodeURIComponent`, and header
+   * values are stringified (an object becomes `[object Object]`). The
+   * parameter's `style`, `explode`, `allowReserved` and `content` are ignored.
    *
-   * @deprecated The behavior is unconditional; listing the flag changes
-   * nothing.
+   * After this flag: Each parameter is serialized as the OpenAPI 3.1
+   * Style Examples table says, for example `rgb[R]=100&rgb[G]=200` for a
+   * `deepObject` and `.blue.black.brown` for a path `label`. Values are
+   * percent-encoded as UTF-8 and a space is `%20`.
    */
-  returnMcpToolInputErrorsAsToolResults: boolean;
-  /**
-   * Before this flag: MCP input schemas are converted to Zod and back to JSON
-   * Schema, and Zod may insert defaults or discard undeclared properties.
-   * After this flag: the MCP SDK validates JSON Schema directly, preserving
-   * constraints and input values. Defaults remain annotations. HTTP validation is unchanged.
-   * Opt in only on the JavaScript runtimes (workerd and Zeno).
-   */
-  useMcpDirectSchemaValidation: boolean;
+  serializeMcpParametersByStyle: boolean;
   /**
    * Whether the MCP server handler rewrites tool names to follow the MCP tool
    * naming rule: 1 to 128 characters of `A-Z`, `a-z`, `0-9`, `_`, `-` and
@@ -244,6 +257,27 @@ declare interface CompatibilityFlags {
    * `_meta` is sent on every version.
    */
   omitMcpFieldsNewerThanNegotiatedVersion: boolean;
+  /**
+   * Whether built-in policies treat an empty or whitespace-only value for an
+   * optional string option as if the option were left out.
+   *
+   * `$env(VAR)` with `VAR` defined but empty reaches a policy as `""`, so this
+   * decides what an empty environment variable does to an optional option.
+   *
+   * Before this flag: Many policies reject `""`. Some fail every request with
+   * a `ConfigurationError` (for example `http-deprecation-outbound` `link`,
+   * `openmeter-inbound` `apiUrl`, `upstream-aws-service-auth-inbound`
+   * `roleSessionName`). Others fail at request time (an `authHeader` of `""`
+   * is not a valid header name). A few use a whitespace-only value as given
+   * (a `"   "` brownout `problem.title`).
+   *
+   * After this flag: Those options behave exactly as if they were left out,
+   * and their default applies. Options where an empty value means something,
+   * secrets, and options whose unset default grants more access keep their
+   * current behavior. `BLANK_IS_NOT_UNSET` in
+   * `policies/optional-string-options.spec.ts` lists them with the reason.
+   */
+  treatBlankOptionalStringOptionsAsUnset: boolean;
 }
 
 /**
@@ -270,6 +304,12 @@ declare interface CorsPolicyConfiguration {
   exposeHeaders?: string[] | string;
 }
 
+/** Shared components by name, each as JSON. */
+declare type DefTable = Record<string, string>;
+
+/** The tables of a generated module, by the key a schema names. */
+declare type DefTables = Record<string, DefTable>;
+
 /**
  * Says how `name` breaks the MCP tool naming rule, or returns `undefined`
  * when it follows it. The reasons are customer-facing (build warnings).
@@ -324,6 +364,63 @@ declare const EventType: {
 
 declare type EventType = (typeof EventType)[keyof typeof EventType];
 
+/** How one component's value is recovered from flat arguments. */
+export declare interface FlatComponentPlan {
+  /** The component this plan assembles. */
+  component: InputComponentName;
+  /** How its value is recovered from the flat arguments. */
+  mode: InputComponentMode;
+  /**
+   * Top-level property names claimed by this component. Empty for a `spread`
+   * body that declares no properties of its own.
+   */
+  keys: string[];
+}
+
+/** A successfully computed flattening. */
+declare interface FlatInputPlan {
+  /** The JSON Schema to advertise as the tool's `inputSchema`. */
+  schema: Record<string, unknown>;
+  /**
+   * Operator-facing notes about anything that stayed nested even though the
+   * plan succeeded — a request body that could not be hoisted while its
+   * operation's parameters could. Each names the cause and the fix.
+   */
+  warnings: string[];
+  /** Per-component assembly plans, in advertised property order. */
+  components: FlatComponentPlan[];
+  /** Every top-level property name mapped to its owning component. */
+  routes: Map<string, InputComponentName>;
+  /** The component that absorbs unclaimed properties, when there is one. */
+  spread?: InputComponentName;
+  /**
+   * True when the flat schema's body part is not a verbatim copy of the body's
+   * properties: a root `allOf` was merged, or a `dependentRequired` was hoisted.
+   * The validator then also checks the routed body against the body's own,
+   * unchanged schema, so a mistake in the merge can never accept more than the
+   * customer's OpenAPI does.
+   */
+  reshapedBody: boolean;
+}
+
+/** Why a composite schema could not be flattened. */
+declare interface FlatInputRefusal {
+  /**
+   * Operator-facing explanation, including the fix. Logged at registration;
+   * never sent to an MCP client.
+   */
+  reason: string;
+}
+
+/** Result of {@link planFlatInput}: a plan, or the reason there isn't one. */
+declare type FlatInputResult =
+  | ({
+      ok: true;
+    } & FlatInputPlan)
+  | ({
+      ok: false;
+    } & FlatInputRefusal);
+
 /* Excluded from this release type: getIdForParameterSchema */
 
 /* Excluded from this release type: getIdForRefSchema */
@@ -332,6 +429,18 @@ declare type EventType = (typeof EventType)[keyof typeof EventType];
 
 /* Excluded from this release type: getRawOperationDataIdentifierName */
 
+/**
+ * The assembler of a generated module's tables for one `schemaRefs` setting.
+ * One per module and setting, so tools share parsed components.
+ *
+ * @param tables - the module's `defs`, or `undefined` when it has none
+ * @param mode - the handler's `schemaRefs`
+ */
+export declare function getSchemaAssembler(
+  tables: DefTables | undefined,
+  mode: SchemaRefs
+): SchemaAssembler;
+
 /**
  * @public
  */
@@ -804,6 +913,67 @@ declare interface IncomingRequestProperties {
   /* Excluded from this release type: clientCertSubjectDn */
 }
 
+/**
+ * How a component's value is assembled from the flat arguments.
+ *
+ * - `properties` — the component is an object whose declared property names
+ *   appear at the top level (`pathParams`, `queryParams`, `headers`, and a
+ *   flattened `body`).
+ * - `spread` — the component additionally absorbs every top-level property that
+ *   no other component claims. Only a flattened `body` does this, and only when
+ *   its own schema permits extra properties.
+ * - `wrapped` — the component is published as a single top-level property under
+ *   its own name, exactly as in the nested shape. Used for a request body that
+ *   cannot be flattened (an array, a string, a `oneOf`, ...).
+ */
+declare type InputComponentMode = "properties" | "spread" | "wrapped";
+
+/**
+ * Flattening of the composite tool input schema that `mcpServerHandler`
+ * generates for an OpenAPI operation.
+ *
+ * The generated validator models an operation's inputs as four components —
+ * `body`, `queryParams`, `pathParams`, `headers` (see `validator.ts`). Publishing
+ * that shape verbatim as a tool's `inputSchema` makes every argument nest one
+ * level deep, so a model has to send `{"body": {"query": "hoodie"}}` where both
+ * the MCP tool convention and Zuplo's own docs say `{"query": "hoodie"}`. Models
+ * send the flat form first, get a -32602, and retry — a wasted round trip on
+ * essentially every tool call.
+ *
+ * This module computes the *advertised* flat schema plus the routing table that
+ * maps each flat property back to the component it came from, so validation can
+ * still run each component's own schema unchanged. It works on the JSON Schema
+ * that `z.toJSONSchema` already produces for the composite, which keeps the
+ * published bytes for each leaf property identical to the nested shape.
+ *
+ * Nothing is flattened at all when it cannot be done without lying about what
+ * is accepted: a name collision between two components refuses the whole plan
+ * and the caller keeps the nested shape.
+ *
+ * A request body that is not a plain object (an array, a string, a `oneOf`) is
+ * NOT that case — it is a supported partial flattening. The parameters are
+ * hoisted and the body keeps its own `body` level, since there is nothing else
+ * that could honestly be done with it; the plan succeeds and carries a note
+ * saying why. Don't "fix" that into a full fallback.
+ *
+ * With `preserveJsonSchema` (the generated validators of
+ * `improvedSchemaValidation`) two body shapes that would otherwise stay
+ * nested are flattened, because the flat schema is then exactly what gets
+ * enforced: a root `allOf` of plain object schemas is merged into one object
+ * (FLAT-10, see `mergeAllOfBody`), and a `dependentRequired` over the body's
+ * own properties is copied to the flat root (FLAT-11). Both set
+ * `reshapedBody`, and the validator re-checks the routed body against its
+ * unchanged schema. A body whose root is the target of its own `$dynamicRef`
+ * (or 2019-09 `$recursiveRef`) recursion stays wrapped (see
+ * `dynamicRecursionProblem`).
+ */
+/** One of the four input channels a generated tool can declare. */
+export declare type InputComponentName =
+  | "body"
+  | "queryParams"
+  | "pathParams"
+  | "headers";
+
 /**
  * ISO 3166-1 Alpha-2 codes
  * @public
@@ -1077,6 +1247,21 @@ declare type JsonObject = {
 
 declare type JsonPrimitive = string | number | boolean | null;
 
+/**
+ * Reads prompt metadata from direct properties and, with `resolveReferences`,
+ * from unconditional `$ref` and `allOf` constraints.
+ *
+ * - With `improvedSchemaValidation`, the build runs it with
+ *   `resolveReferences` on a prompt's generated schema (mcp-tool-schemas
+ *   MCPSCHEMA-32, compat-improved-schema-validation SCHEMAVAL-2).
+ * - Without it, the legacy path runs it without `resolveReferences` on the
+ *   prompt validator's Zod-derived schema (mcp-tool-schemas-legacy).
+ */
+export declare function jsonSchemaToPromptArguments(
+  schema: object,
+  resolveReferences?: boolean
+): PromptArgument[];
+
 /**
  Matches any valid JSON value.
  @see `Jsonify` if you need to transform a type to one that is assignable to `JsonValue`.
@@ -1708,6 +1893,31 @@ declare interface ParameterDefinition extends ParameterBaseObject {
   in: string;
 }
 
+/**
+ * Computes the flat `inputSchema` for a composite tool input schema.
+ *
+ * @param composite - the JSON Schema for the nested composite (the object whose
+ * properties are `body` / `queryParams` / `pathParams` / `headers`)
+ * @param present - the components this operation actually declares
+ * @param preserveJsonSchema - the schemas are enforced as written by the
+ * generated validators, so a body keyword that has no flat equivalent keeps it
+ * wrapped, and FLAT-10 and FLAT-11 apply. `false` for the legacy Zod path.
+ * @returns the flattening plan, or the reason flattening was refused
+ *
+ * @example
+ * ```ts
+ * const result = planFlatInput(z.toJSONSchema(composite), ["body"]);
+ * if (result.ok) {
+ *   console.log(result.schema); // { type: "object", properties: { query: ... } }
+ * }
+ * ```
+ */
+export declare const planFlatInput: (
+  composite: Record<string, unknown>,
+  present: InputComponentName[],
+  preserveJsonSchema?: boolean
+) => FlatInputResult;
+
 /**
  * @public
  */
@@ -1760,6 +1970,13 @@ declare interface PreRequestHandlerApi {
   readonly signal: AbortSignal;
 }
 
+/** A named argument advertised by an MCP prompt. */
+export declare interface PromptArgument {
+  name: string;
+  description: string;
+  required: boolean;
+}
+
 /**
  * Generic type parameters for a request.
  * Extends RequestInitGeneric and adds query parameter typing.
@@ -1885,6 +2102,91 @@ export declare interface RouteData {
 
 /* Excluded from this release type: sanitizedIdentifierName */
 
+/** Builds the advertised schemas of one module, for one `schemaRefs` setting. */
+declare class SchemaAssembler {
+  private readonly tables;
+  readonly mode: SchemaRefs;
+  private readonly parsed;
+  private readonly refs;
+  private readonly recursive;
+  /** Per table: each component with its non-recursive references inlined. */
+  private readonly bodies;
+  /** Per table: the recursive components a body still references. */
+  private readonly needs;
+  private readonly assembled;
+  constructor(tables: DefTables, mode: SchemaRefs);
+  /**
+   * The schema a tool advertises, assembled on first call and cached.
+   *
+   * @param schema - the generated schema
+   * @param kind - the nested or flat `inputSchema`, or the `outputSchema`
+   */
+  assemble(schema: AssemblableSchema, kind: SchemaKind): object;
+  /**
+   * MCPSCHEMA-6: a `body` or output root that is only a `$ref` is replaced
+   * by its target. The generated root keeps the reference, so a component
+   * used as a body in many tools is not repeated in each.
+   */
+  private replaceRootRef;
+  private memo;
+  private parse;
+  private refsOf;
+  /**
+   * `defs` mode: the root with the components it reaches under `$defs`,
+   * sorted by name, as the build's own assembly wrote them before components
+   * were shared.
+   */
+  private withDefs;
+  /** Marks the components of `table` that sit on a reference cycle. */
+  private markRecursion;
+  private isRecursive;
+  /**
+   * `inline` mode: a reference to a component that does not reference itself
+   * (directly or through others) becomes the component. References on a cycle
+   * stay `$ref`s, with the cyclic components under `$defs`.
+   */
+  private inline;
+  /** The component with its non-recursive references inlined, shared. */
+  private body;
+  private needsOf;
+  /**
+   * Rewrites one schema: inlines references to non-recursive components, and
+   * writes the advertised form of `discriminator` (below). Subtrees that
+   * change nothing are returned as they are, so components are shared.
+   */
+  private walk;
+  private walkList;
+  /** Walks the keywords of an object that is not (or no longer) a `$ref`. */
+  private walkSiblings;
+  /**
+   * SV-15: a `discriminator.mapping` value names a component, which no longer
+   * resolves once references are inlined. An input drops the whole
+   * `discriminator`, as the Zod conversion of a union did; an output keeps
+   * `propertyName` and drops `mapping`.
+   */
+  private discriminator;
+}
+
+/**
+ * What a generated schema is. A nested `input` has a `body` property, a
+ * `flat` input has the body's properties in place of it, and an `output` is
+ * the response schema.
+ */
+declare type SchemaKind = "input" | "flat" | "output";
+
+/**
+ * Assembles the schemas `tools/list` advertises from the data the build
+ * generates (packages/runtime/specs/mcp-tool-schemas.md MCPSCHEMA-6).
+ *
+ * The generated module holds each shared component once, as a JSON string in a
+ * table, and every tool's schema as a root that points at the table with
+ * `#/$defs/<name>` references. A source that repeated each component in each
+ * tool grows with tools times components. Assembly happens on first use, per
+ * tool, and is cached; a component is parsed once however many tools use it.
+ */
+/** How an advertised schema carries shared components. */
+declare type SchemaRefs = "inline" | "defs";
+
 export declare function setGlobalZuploEventContext(
   event: ZuploEventContext
 ): void;
@@ -1898,6 +2200,25 @@ declare interface UrlConfig {
 
 declare type UserDataDefault = any;
 
+/**
+ * Whether a project's MCP tool schemas use the by-spec settings: validated per
+ * the JSON Schema dialect and OpenAPI version they declare, instead of the
+ * legacy Zod path built at runtime from `raw()` (mcp-tool-schemas-legacy).
+ *
+ * `improvedSchemaValidation` turns them on. This is the one place that
+ * reads the flag for tool schemas: the build (`packages/codegen/src/mcp-tool-schemas/`) calls it with the project's
+ * merged flags, and `mcpServerHandler` with
+ * `Environment.instance.build.COMPATIBILITY_FLAGS`. Both come from the same
+ * merged flags, so they always agree.
+ *
+ * @param flags - resolved compatibility flags (`COMPATIBILITY_FLAGS`, or the
+ * build's merged flags by name)
+ * @returns `true` when `improvedSchemaValidation` is `true`
+ */
+export declare function usesImprovedSchemaValidation(flags: {
+  readonly improvedSchemaValidation?: boolean;
+}): boolean;
+
 /**
  * @public
  */