@webpieces/core-util 0.4.806 → 0.4.808

package/src/mcp/DtoSchema.d.ts

@@ -1,64 +1,56 @@
-import 'reflect-metadata';
-export type DtoClass = abstract new (...args: any[]) => unknown;
-/** The element type of an array or the value type of a map; TypeScript erases both at runtime. */
-export type DtoElementType = 'string' | 'number' | 'integer' | 'boolean' | DtoClass;
+/**
+ * The JSON Schema subset webpieces publishes on its API boundaries, and the ONE runtime validator of
+ * it.
+ *
+ * ## Nothing here reads reflect-metadata any more
+ *
+ * Until #984 this file also carried `@WpDto`, `@WpDtoField`, `WpDtoFieldOptions`,
+ * `WpDtoMapFieldOptions`, `WpMcpHeader`, `@WpResponseDto` and `DtoSchemaBuilder` — a second, runtime
+ * spelling of facts the TypeScript compiler already holds. #983 measured the two against each other
+ * and found the compiler reproduces every one of those arguments byte for byte, so they are deleted
+ * rather than deprecated (`.claude/rules/no-backwards-compat.md`): a schema is now BUILT at build
+ * time from the source by `@webpieces/api-doc-model`, and the runtime is HANDED the result.
+ *
+ * What survives is the schema itself, a builder for the boundaries that construct one by hand, and a
+ * validator that reads the schema instead of a decorator.
+ */
 /** Runtime values accepted at the DTO validation boundary. */
 export type DtoValue = object | string | number | boolean | null;
-/** Additive field metadata; the scalar/object type itself comes from `design:type`. */
-export declare class WpDtoFieldOptions {
-    readonly description: string;
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    readonly required: boolean;
-    /** Required for arrays because TypeScript erases their element type. */
-    readonly arrayItems?: DtoElementType | undefined;
-    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
-    readonly integer: boolean;
-    readonly minimum?: number | undefined;
-    readonly maximum?: number | undefined;
-    readonly enumValues?: readonly [string, ...string[]] | undefined;
-    /** MCP 2026 SEP-2243 header mirrored as `Mcp-Param-{name}`. */
-    readonly mcpHeader?: WpMcpHeader | undefined;
-    constructor(description: string, 
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    required: boolean, 
-    /** Required for arrays because TypeScript erases their element type. */
-    arrayItems?: DtoElementType | undefined, 
-    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
-    integer?: boolean, minimum?: number | undefined, maximum?: number | undefined, enumValues?: readonly [string, ...string[]] | undefined, 
-    /** MCP 2026 SEP-2243 header mirrored as `Mcp-Param-{name}`. */
-    mcpHeader?: WpMcpHeader | undefined);
-}
 /**
- * Names the `x-mcp-header` a primitive tool parameter is mirrored into (`Mcp-Param-{name}`). A class,
- * not a bare string, so the 8th `WpDtoFieldOptions` argument can never be mistaken for a map value
- * type (maps use `WpDtoMapFieldOptions`).
+ * One JSON Schema `type`. `null` is a member because NULLABLE is expressed as `["string", "null"]`,
+ * which is how JSON Schema says "present, and may hold null" — a different wire document from an
+ * ABSENT property, and one the reflect-metadata runtime could neither see nor write down.
  */
-export declare class WpMcpHeader {
-    readonly name: string;
-    constructor(name: string);
-}
+export type ApiJsonSchemaType = 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
 /**
- * Field metadata for a typed map such as `Record<string, string>` or `Record<string, SomeDto>`.
- * Keys are open strings; every VALUE must match `mapValues`. The value type is explicit for the same
- * reason `arrayItems` is: TypeScript erases it, and a `Record` reflects as plain `Object`.
+ * The DISCRIMINATOR of a {@link ApiJsonSchema.oneOf} — which property narrows the union, and what
+ * each of its values names.
+ *
+ * The shape MIRRORS what `OpenApiGenerator`'s `SchemaRenderer` already emits for the same union
+ * (`propertyName` + `mapping`), because a union has exactly ONE published spelling in this repo and
+ * the OpenAPI renderer is the reference implementation of it. The one difference is what a mapping
+ * VALUE holds: OpenAPI maps a value to `#/components/schemas/ScheduledWindow`, and an MCP tool
+ * schema is INLINE and has no `$ref` to point at, so it maps to the branch's type NAME.
+ *
+ * `mapping` is DOCUMENTATION for the reader. {@link ApiJsonSchemaValidator} never narrows with it:
+ * it selects the branch whose own `enum` carries the value, so the accepted request and the
+ * published document cannot disagree about which branch a value means.
  */
-export declare class WpDtoMapFieldOptions {
-    readonly description: string;
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    readonly required: boolean;
-    readonly mapValues: DtoElementType;
-    constructor(description: string, 
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    required: boolean, mapValues: DtoElementType);
-}
-export declare class WpDtoFieldMetadata {
-    readonly propertyKey: string;
-    readonly options: WpDtoFieldOptions | WpDtoMapFieldOptions;
-    constructor(propertyKey: string, options: WpDtoFieldOptions | WpDtoMapFieldOptions);
+export declare class ApiJsonSchemaDiscriminator {
+    /** The property every branch declares as exactly one string literal, e.g. `kind`. */
+    propertyName: string;
+    /** discriminator value -> the branch's TYPE NAME (MCP is inline: there is no `$ref`). */
+    mapping: Record<string, string>;
+    constructor(
+    /** The property every branch declares as exactly one string literal, e.g. `kind`. */
+    propertyName: string, 
+    /** discriminator value -> the branch's TYPE NAME (MCP is inline: there is no `$ref`). */
+    mapping: Record<string, string>);
 }
 /** The JSON Schema subset emitted for Webpieces API DTOs. */
 export declare class ApiJsonSchema {
-    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    /** One type, or `[T, "null"]` for a nullable field. */
+    type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[];
     description?: string;
     properties?: Record<string, ApiJsonSchema>;
     required?: string[];
@@ -68,9 +60,60 @@ export declare class ApiJsonSchema {
     enum?: string[];
     minimum?: number;
     maximum?: number;
+    /**
+     * The branches of a union, INLINE (MCP tool schemas have no `$ref`), in declaration order.
+     *
+     * A union is legal NESTED, inside a property. It is NOT legal at the ROOT of a tool's parameter
+     * schema — both the OpenAI and the Anthropic function-calling APIs reject a top-level
+     * `oneOf`/`anyOf`/`allOf`, and because a server sends its whole tool list on every request, one
+     * such tool makes EVERY request 400. That is refused at build time by the `no-root-union-api-type`
+     * rule, before a contract can be published at all.
+     */
+    oneOf?: readonly ApiJsonSchema[];
+    /**
+     * Set ONLY when every branch carries the same property typed as one string literal — DERIVED,
+     * never invented. A union TypeScript itself cannot narrow is published as a bare {@link oneOf},
+     * because claiming a narrowing the source does not have is worse than admitting there is none.
+     */
+    discriminator?: ApiJsonSchemaDiscriminator;
     /** MCP 2026 SEP-2243 schema extension consumed by the official SDK. */
     'x-mcp-header'?: string;
-    constructor(type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array');
+    constructor(type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[]);
+    /**
+     * The non-`null` member of the type, which is the one that decides how a value is checked.
+     *
+     * These three are STATIC and not instance methods on purpose: an instance method would put a
+     * function on the structural type, and this class is handed straight to the MCP SDK, whose
+     * parameter types are index-signature JSON objects that a class carrying methods no longer
+     * satisfies. It stays a data-only structure (`CLAUDE.md` §1) and the helpers live beside it.
+     */
+    static baseTypeOf(schema: ApiJsonSchema): ApiJsonSchemaType | undefined;
+    /** True when the schema was widened with `"null"`, i.e. the property may hold `null`. */
+    static allowsNull(schema: ApiJsonSchema): boolean;
+    /**
+     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:
+     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is
+     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.
+     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.
+     */
+    static isClosed(schema: ApiJsonSchema): boolean;
+}
+/**
+ * Builds the CLOSED object schema a hand-written runtime boundary validates against — `@WpStream`'s
+ * two event schemas are the whole of its client list today.
+ *
+ * It exists because the alternative spellings are both worse: a decorator that re-states the field
+ * types the compiler already knows is exactly what #984 deleted, and a bare object literal is what
+ * `CLAUDE.md` §3 forbids. A generated schema never comes through here — it is read from the build's
+ * own artifact.
+ */
+export declare class ObjectSchemaBuilder {
+    private readonly schema;
+    private readonly requiredNames;
+    constructor();
+    required(name: string, type: ApiJsonSchema): this;
+    optional(name: string, type: ApiJsonSchema): this;
+    build(): ApiJsonSchema;
 }
 /** A validation result safe to show to an API caller/model. */
 export declare class DtoValidationFailure {
@@ -81,35 +124,42 @@ export declare class DtoValidationFailure {
     /** JSON path of the offending value, e.g. `$.address.city`. */
     field: string, message: string);
 }
-/** Marks a request/response class as a schema-bearing DTO, including intentionally empty DTOs. */
-export declare function WpDto(): ClassDecorator;
-/** Adds documentation and runtime-only shape facts to a DTO property. */
-export declare function WpDtoField(options: WpDtoFieldOptions | WpDtoMapFieldOptions): PropertyDecorator;
-/** Declares an async API method's response DTO because reflection sees Promise, not its generic. */
-export declare function WpResponseDto(responseDto: () => DtoClass): MethodDecorator;
-/** Builds and validates the same DTO schema used for MCP input and structured output. */
-export declare class DtoSchemaBuilder {
-    requestClassOf(apiClass: Function, methodName: string): DtoClass;
-    responseClassOf(apiClass: Function, methodName: string): DtoClass;
+/**
+ * Validates a value against an {@link ApiJsonSchema} — the ONE runtime narrowing boundary for MCP
+ * tool arguments, MCP structured output and typed stream events.
+ *
+ * It reads the SCHEMA, which is the same object the build published to agents, so a document that
+ * says a field is required and a server that accepts it missing cannot disagree. The predecessor
+ * walked reflect-metadata instead, which meant the published document and the accepted request were
+ * derived from two different declarations.
+ */
+export declare class ApiJsonSchemaValidator {
+    validate(schema: ApiJsonSchema, value: DtoValue): DtoValidationFailure | undefined;
+    private validateAt;
     /**
-     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:
-     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is
-     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.
-     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.
+     * A union, validated BY DISCRIMINATOR.
+     *
+     * The discriminator property is read FIRST and the branch chosen from it, so a value naming no
+     * branch is reported as what it is — `$.window.kind must be one of: scheduled | asap`, naming the
+     * field that is wrong and the values it may hold. Trying every branch and reporting "no branch
+     * matched" tells a caller nothing they can act on: it names neither the offending property nor
+     * the legal values, and it hides a branch that matched on `kind` and failed three levels down.
+     *
+     * The branch is selected by the branches' own `enum`s, never by
+     * {@link ApiJsonSchemaDiscriminator.mapping} — the branches ARE the schema, so selection and
+     * validation read one source and cannot disagree.
      */
-    isClosedSchema(schema: ApiJsonSchema): boolean;
-    build(dtoClass: DtoClass): ApiJsonSchema;
-    validate(dtoClass: DtoClass, value: DtoValue): DtoValidationFailure | undefined;
-    private buildAt;
-    private fieldSchema;
-    private validateOptions;
-    private itemSchema;
-    private validateMcpHeaders;
-    private validateAt;
-    private validateField;
+    private validateUnion;
+    /**
+     * A union with NO discriminator — one TypeScript itself cannot narrow. Every branch is tried and
+     * the value accepted when one matches. There is no better report when none does: the source does
+     * not narrow, so no property can honestly be named as the wrong one.
+     */
+    private validateAnyBranch;
+    /** The string literals ONE branch declares for the discriminator property. */
+    private static branchValuesOf;
+    private validateObject;
     private validateArray;
-    private validateMap;
-    private validateElement;
-    private fields;
-    private requireDto;
+    private validateString;
+    private validateNumber;
 }