carrick 0.3.70 → 0.3.72

package/sidecar/dist/src/type-inferrer.js

@@ -861,7 +861,7 @@ export class TypeInferrer {
             if (atLine) {
                 const requestType = this.requestContractFromRegistration(atLine.registration, atLine.handler);
                 if (requestType) {
-                    return this.createInferredType(request, requestType, true, this.getNodeLocation(atLine.handler), undefined, undefined);
+                    return this.declaredRequestInferredType(request, requestType, this.getNodeLocation(atLine.handler));
                 }
             }
             return null;
@@ -879,7 +879,7 @@ export class TypeInferrer {
         if (registrationHandler) {
             const requestType = this.requestContractFromRegistration(this.unwrapExpressionNode(located), registrationHandler);
             if (requestType) {
-                return this.createInferredType(request, requestType, true, this.getNodeLocation(registrationHandler), undefined, undefined);
+                return this.declaredRequestInferredType(request, requestType, this.getNodeLocation(registrationHandler));
             }
             // A genuinely payload-less handler (no typed request read): do NOT fall
             // through to read the registration call's return type, which would emit a
@@ -912,7 +912,7 @@ export class TypeInferrer {
             if (declared) {
                 this.log(`Route registration at ${request.file_path}:${request.line_number} declares its ` +
                     'request contract; using the declaration over the located expression');
-                return this.createInferredType(request, declared, true, this.getNodeLocation(declaredAt.handler), undefined, undefined);
+                return this.declaredRequestInferredType(request, declared, this.getNodeLocation(declaredAt.handler));
             }
         }
         // A text locator (Gemini `expression_text` + `expression_line`, as opposed
@@ -966,6 +966,21 @@ export class TypeInferrer {
                 }
             }
         }
+        // carrick#1101: the locator landed on a validated read — a call inside a
+        // registered handler whose type IS the parsed output of a body schema that
+        // the enclosing registration declares. That value is what the handler
+        // receives, not what a caller sends, so publish the schema's input. Only a
+        // direct call is read this way: a value that went through a serialiser or
+        // a variable hop is left to the path below, so a consumer body forwarded
+        // from inside a handler keeps its own type.
+        if (node === unwrapped && Node.isCallExpression(node)) {
+            const validatedRead = this.validatedReadRequestContract(node);
+            if (validatedRead) {
+                this.log(`Request locator at ${request.file_path}:${request.line_number} is a validated read ` +
+                    "of its registration's body schema; publishing the schema's input");
+                return this.declaredRequestInferredType(request, validatedRead, this.getNodeLocation(node));
+            }
+        }
         const payloadType = node.getType();
         let typeString = typeText(payloadType, node);
         let isExplicit = false;
@@ -3126,12 +3141,13 @@ export class TypeInferrer {
     //      of that parameter's type;
     //  (b) a validation-schema object passed alongside the handler — `{ schema:
     //      { body: ref('CreateWidget'), response: { 200: ref('Widget') } } }` —
-    //      whose entries reference schema VALUES that carry their parsed output
-    //      type.
+    //      whose entries reference schema VALUES that declare their input and
+    //      output types.
     //
     // Both are read structurally: (a) is "the `body` member of a parameter's
     // type", (b) is "a `schema` property on a registration argument, whose
-    // entries resolve to a value whose `parse` returns the contract". No
+    // entries resolve to a value that declares its types" (the body reads the
+    // input, the response the output; carrick#1101). No
     // framework, library, or method-name list is involved — a framework whose
     // request object exposes `body` and whose route options carry `schema` is
     // read the same way regardless of which one it is.
@@ -3160,13 +3176,13 @@ export class TypeInferrer {
      * back to following the handler's return.
      */
     declaredResponseInferredType(request, registration) {
-        const declared = this.routeSchemaContractText(registration, 'response');
+        const declared = this.routeSchemaContract(registration, 'response');
         if (!declared) {
             return null;
         }
         this.log(`Route registration at ${request.file_path}:${request.line_number} declares its ` +
             'response schema; using the declared contract');
-        return this.createInferredType(request, declared, true, this.getNodeLocation(registration), undefined, undefined);
+        return this.createInferredType(request, declared.text, true, this.getNodeLocation(registration), undefined, undefined);
     }
     /**
      * The request contract of a route registration, in anchor order: the
@@ -3176,8 +3192,23 @@ export class TypeInferrer {
      * the route declares its request nowhere we can read.
      */
     requestContractFromRegistration(registration, handler) {
-        return (this.declaredRequestContract(registration, handler) ??
-            this.inferRequestReadFromHandler(handler));
+        const declared = this.declaredRequestContract(registration, handler);
+        if (declared) {
+            return declared;
+        }
+        const read = this.inferRequestReadFromHandler(handler);
+        return read ? { text: read } : null;
+    }
+    /**
+     * An explicit request `InferredType` for a contract the route declares,
+     * carrying the provenance the reading recorded.
+     */
+    declaredRequestInferredType(request, contract, location) {
+        const inferred = this.createInferredType(request, contract.text, true, location, undefined, undefined);
+        if (contract.provenance && contract.provenance.length > 0) {
+            inferred.any_provenance = contract.provenance;
+        }
+        return inferred;
     }
     /**
      * The request contract a route DECLARES, in anchor order: the handler's
@@ -3191,9 +3222,12 @@ export class TypeInferrer {
      * own locator authoritative when a route declares nothing.
      */
     declaredRequestContract(registration, handler) {
-        return (this.requestBodyFromHandlerParams(handler) ??
-            this.routeSchemaContractText(registration, 'body') ??
-            this.validatedBodyContractText(registration));
+        const annotated = this.requestBodyFromHandlerParams(handler);
+        if (annotated) {
+            return { text: annotated };
+        }
+        return (this.routeSchemaContract(registration, 'body') ??
+            this.validatedBodyContract(registration));
     }
     /**
      * Anchor (a): the request contract declared on the handler's own signature.
@@ -3246,8 +3280,9 @@ export class TypeInferrer {
      * The shape is a CALL among the registration's arguments whose own arguments
      * are a request part and a schema value. Neither the middleware's name nor
      * the schema library is checked: the part is read off the string literal, and
-     * the schema is whatever exposes a parsed output (`schemaOutputTypeText`) —
-     * the same test anchor (b) already applies to a `schema: { body: … }` object.
+     * the schema is whatever declares its types (`schemaContract`) — the same
+     * test anchor (b) already applies to a `schema: { body: … }` object. The
+     * contract is the schema's INPUT, what a caller sends (carrick#1101).
      *
      * `REQUEST_BODY_PARTS` is HTTP vocabulary for how a body is carried, not a
      * framework list. A middleware bound to any other part (`query`, `param`,
@@ -3255,10 +3290,26 @@ export class TypeInferrer {
      * at all is not read: publishing a query schema as the request contract would
      * be the same confident-and-wrong answer this anchor exists to remove.
      */
-    validatedBodyContractText(registration) {
+    validatedBodyContract(registration) {
+        for (const candidate of this.middlewareBodySchemaValues(registration)) {
+            const declared = this.schemaContract(candidate, 'input');
+            if (declared) {
+                return declared;
+            }
+        }
+        return null;
+    }
+    /**
+     * The values a registration's validator middleware binds to a body part, in
+     * argument order: every non-literal argument of a middleware call that names
+     * a `REQUEST_BODY_PARTS` part. Whether each one IS a schema is the reader's
+     * question (`schemaContract`), not this walk's.
+     */
+    middlewareBodySchemaValues(registration) {
         if (!Node.isCallExpression(registration)) {
-            return null;
+            return [];
         }
+        const values = [];
         for (const argument of registration.getArguments()) {
             const middleware = this.unwrapExpressionNode(argument);
             if (!Node.isCallExpression(middleware)) {
@@ -3267,21 +3318,58 @@ export class TypeInferrer {
             const middlewareArgs = middleware
                 .getArguments()
                 .map((arg) => this.unwrapExpressionNode(arg));
-            const parts = middlewareArgs.filter((arg) => Node.isStringLiteral(arg));
-            if (parts.length === 0) {
+            const bindsBody = middlewareArgs.some((arg) => Node.isStringLiteral(arg) &&
+                REQUEST_BODY_PARTS.has(arg.getLiteralValue().toLowerCase()));
+            if (!bindsBody) {
+                continue;
+            }
+            values.push(...middlewareArgs.filter((arg) => !Node.isStringLiteral(arg)));
+        }
+        return values;
+    }
+    /**
+     * The request contract behind a VALIDATED READ: a call inside a registered
+     * handler whose type is exactly the parsed output of a body schema the
+     * enclosing registration declares (carrick#1101).
+     *
+     * The read's own type is what validation hands the handler, the schema's
+     * output, so a locator that lands on it would publish the output as the
+     * request. The registration is found by walking the read's ancestors to each
+     * call or registry object whose handler contains the read and which declares
+     * a body schema (anchor (b) or (b2)). The match is on the printed type: only
+     * a read whose structural text equals that schema's output is substituted, so
+     * any other expression in the handler (a query read, a payload of a different
+     * shape) keeps its own type.
+     */
+    validatedReadRequestContract(read) {
+        let readText;
+        for (const ancestor of read.getAncestors()) {
+            if (!Node.isCallExpression(ancestor) &&
+                !Node.isObjectLiteralExpression(ancestor)) {
                 continue;
             }
-            if (!parts.some((part) => REQUEST_BODY_PARTS.has(part.getLiteralValue().toLowerCase()))) {
+            const handler = this.registrationHandlerAt(ancestor);
+            if (!handler ||
+                read.getStart() < handler.getStart() ||
+                read.getEnd() > handler.getEnd()) {
                 continue;
             }
-            for (const candidate of middlewareArgs) {
-                if (Node.isStringLiteral(candidate)) {
+            const schemaValues = [
+                ...this.routeSchemaEntryValues(ancestor, 'body'),
+                ...this.middlewareBodySchemaValues(ancestor),
+            ];
+            for (const value of schemaValues) {
+                const output = this.schemaContract(value, 'output');
+                if (!output) {
                     continue;
                 }
-                const declared = this.schemaOutputTypeText(candidate);
-                if (declared) {
-                    return declared;
+                if (readText === undefined) {
+                    readText = this.structuralTextFromType(read.getType(), read);
+                }
+                if (readText !== output.text) {
+                    continue;
                 }
+                return this.schemaContract(value, 'input');
             }
         }
         return null;
@@ -3291,29 +3379,43 @@ export class TypeInferrer {
      *
      * `part` is `'body'` for the request contract and `'response'` for the
      * response contract; a `response` entry keyed by status code resolves to its
-     * success entry. Returns null when the registration carries no schema, when
-     * the entry references something whose parsed output cannot be resolved, or
-     * when the schema is a plain JSON-schema literal (whose own object type is
-     * the JSON-Schema document, not the payload — emitting that would be worse
-     * than abstaining).
+     * success entry. The body reads the schema's input and the response its
+     * output (carrick#1101). Returns null when the registration carries no
+     * schema, when the entry references something whose declared types cannot be
+     * resolved, or when the schema is a plain JSON-schema literal (whose own
+     * object type is the JSON-Schema document, not the payload — emitting that
+     * would be worse than abstaining).
+     */
+    routeSchemaContract(registration, part) {
+        const [value] = this.routeSchemaEntryValues(registration, part);
+        if (!value) {
+            return null;
+        }
+        return this.schemaContract(value, part === 'body' ? 'input' : 'output');
+    }
+    /**
+     * The value a route `schema` object declares for `part`, as a zero- or
+     * one-element list: the `body` entry itself, or the success entry of a
+     * status-keyed `response` map.
      */
-    routeSchemaContractText(registration, part) {
+    routeSchemaEntryValues(registration, part) {
         const schemaObject = this.routeSchemaObject(registration);
         if (!schemaObject) {
-            return null;
+            return [];
         }
         const entry = schemaObject.getProperty(part);
         if (!entry || !Node.isPropertyAssignment(entry)) {
-            return null;
+            return [];
         }
         const initializer = entry.getInitializer();
         if (!initializer) {
-            return null;
+            return [];
         }
-        const value = part === 'response'
-            ? (this.successStatusEntry(initializer) ?? initializer)
-            : initializer;
-        return this.schemaOutputTypeText(value);
+        return [
+            part === 'response'
+                ? (this.successStatusEntry(initializer) ?? initializer)
+                : initializer,
+        ];
     }
     /**
      * The `schema` object literal carried by a route registration: scan the
@@ -3379,17 +3481,36 @@ export class TypeInferrer {
         return best?.node;
     }
     /**
-     * The payload type a schema entry declares.
+     * The payload type a schema entry declares, read in `direction`.
      *
      * The entry is either a REFERENCE call — `ref('CreateWidget')`, a
      * name-to-schema indirection whose registry is the argument the ref function
-     * was built from — or the schema value itself. Either way the payload is the
-     * schema's parsed output: the return type of its `parse` method (the shape
-     * every schema value exposes as its public validate-and-return API), falling
-     * back to a declared `_output` member. A value with neither is not a schema
-     * and yields null.
+     * was built from — or the schema value itself. A value that declares no type
+     * in either direction is not a schema and yields null.
+     *
+     * `output` is the parsed value (`schemaOutputType`). `input` is what a caller
+     * sends (`schemaInputType`), and a schema that declares no input member reads
+     * its output instead, which is the whole of what is knowable about it.
+     *
+     * The input is decided member by member (carrick#1105). A member whose input
+     * is `any`/`unknown` where the output is concrete is what a coercion declares
+     * (it accepts any value and parses it into, say, a number). A top type in a
+     * published contract disqualifies the whole row downstream, so THAT member
+     * prints its output type, keeps the input key's optionality, and is recorded
+     * as `coerced_input` provenance. Every other member keeps its input, so a
+     * defaulted key beside a coerced one stays optional to send.
+     *
+     * Limits, each logged where it bites:
+     *  - the position walk is bounded (`walkTypePositions`), so a top type below
+     *    the bound is not compared and prints as the input declares it;
+     *  - a coerced position that cannot be substituted (its output is absent or
+     *    differs across union branches, or the printer cannot reach it inside a
+     *    tuple, behind a cycle or past the expansion depth) makes the row fall
+     *    back to the whole parsed output with every coerced member labelled. That
+     *    was the answer before the per-member reading, and it never publishes an
+     *    `unknown`.
      */
-    schemaOutputTypeText(value) {
+    schemaContract(value, direction) {
         const node = this.unwrapExpressionNode(value);
         let schemaType;
         if (Node.isCallExpression(node)) {
@@ -3403,13 +3524,201 @@ export class TypeInferrer {
                 return null;
             }
         }
+        const location = this.getNodeLocation(node);
+        const where = `${location.file_path}:${location.start_line}`;
         const output = this.schemaOutputType(schemaType, node);
-        if (!output) {
-            this.log(`Route schema entry at ${this.getNodeLocation(node).file_path}:${this.getNodeLocation(node).start_line} declares no resolvable parsed output (schema library types unavailable, ` +
-                'or a plain JSON-Schema literal); leaving unresolved');
+        const input = direction === 'input' ? this.schemaInputType(schemaType, node) : undefined;
+        if (!output && !input) {
+            this.log(`Route schema entry at ${where} declares no resolvable type (schema library ` +
+                'types unavailable, or a plain JSON-Schema literal); leaving unresolved');
+            return null;
+        }
+        if (direction === 'output' || !input) {
+            if (direction === 'input') {
+                this.log(`Route schema entry at ${where} declares no input type; publishing its parsed output`);
+            }
+            const text = output ? this.structuralTextFromType(output, node) : null;
+            return text ? { text } : null;
+        }
+        const inputTop = this.topTypePositions(input, node, where);
+        const outputTop = output && inputTop.size > 0 ? this.topTypePositions(output, node, where) : undefined;
+        const coerced = outputTop
+            ? [...inputTop.entries()]
+                .filter(([position]) => !outputTop.has(position))
+                .sort(([a], [b]) => a.localeCompare(b))
+            : [];
+        if (!output || coerced.length === 0) {
+            const text = this.structuralTextFromType(input, node);
+            return text ? { text } : null;
+        }
+        const positions = coerced.map(([position]) => position || '<root>').join(', ');
+        const provenance = coerced.map(([position, kind]) => ({
+            path: position,
+            kind,
+            reason: 'coerced_input',
+            detail: `the schema accepts any value here and coerces it, so the published type ` +
+                `is what parsing produces, not a limit on what a caller may send`,
+        }));
+        const text = this.inputWithCoercedMembers(input, output, coerced.map(([position]) => position), node, where);
+        if (text) {
+            this.log(`Route schema entry at ${where} accepts any value at ${positions} on input; ` +
+                'publishing the parsed type there and the input everywhere else');
+            return { text, provenance };
+        }
+        const whole = this.structuralTextFromType(output, node);
+        if (!whole) {
             return null;
         }
-        return this.structuralTextFromType(output, node);
+        this.log(`Route schema entry at ${where} accepts any value at ${positions} on input, and not ` +
+            'every one could be substituted member by member; publishing its whole parsed output');
+        return { text: whole, provenance };
+    }
+    /**
+     * Print a schema's input with each coerced position replaced by the output's
+     * type at that position (carrick#1105). Null when any position cannot be
+     * substituted: its output is missing or differs across union branches, or
+     * the printer never reached it. A partial substitution would publish an
+     * `unknown`, so it is not an answer.
+     */
+    inputWithCoercedMembers(input, output, coerced, at, where) {
+        const wanted = new Set(coerced);
+        const types = new Map();
+        const ambiguous = new Set();
+        this.walkTypePositions(output, at, where, (type, position, unionPart) => {
+            // A union's parts share its position; the union itself is the type there.
+            if (wanted.has(position) && !unionPart) {
+                const seen = types.get(position);
+                if (!seen) {
+                    types.set(position, type);
+                }
+                else if (seen.compilerType !== type.compilerType) {
+                    ambiguous.add(position);
+                }
+            }
+            return true;
+        });
+        for (const position of ambiguous) {
+            types.delete(position);
+        }
+        const missing = coerced.filter((position) => !types.has(position));
+        if (missing.length > 0) {
+            this.log(`Route schema entry at ${where}: no single parsed type at ` +
+                `${missing.map((position) => position || '<root>').join(', ')} to substitute ` +
+                'for the coerced input');
+            return null;
+        }
+        const root = types.get('');
+        if (root) {
+            return this.structuralTextFromType(root, at);
+        }
+        const overrides = { types, applied: new Set(), at };
+        let text;
+        try {
+            text = expandTypeStructural(this.unwrapPromiseType(input), new Set(), 0, overrides);
+        }
+        catch {
+            return null;
+        }
+        const unreached = coerced.filter((position) => !overrides.applied.has(position));
+        if (unreached.length > 0) {
+            this.log(`Route schema entry at ${where}: the printer did not reach coerced ` +
+                `${unreached.join(', ')} (tuple, cycle or depth bound)`);
+            return null;
+        }
+        return this.isUselessType(text) ? null : text;
+    }
+    /**
+     * Member positions inside `root` that are `any` or `unknown`, keyed by the
+     * member-path notation the provenance entries use (`''` for the root,
+     * `sub.field`, `items<0>` for an array element). Union and intersection
+     * members share their parent's position, so `unknown | undefined` on an
+     * optional key reads as `unknown` there.
+     */
+    topTypePositions(root, at, where) {
+        const found = new Map();
+        this.walkTypePositions(root, at, where, (type, position) => {
+            if (type.isAny() || type.isUnknown()) {
+                found.set(position, type.isAny() ? 'any' : 'unknown');
+                return false;
+            }
+            return true;
+        });
+        return found;
+    }
+    /**
+     * Visit every member position of `root`, in the notation `topTypePositions`
+     * documents. `visit` returns false to stop descending below a position;
+     * `unionPart` is true when the type is a union or intersection part visited
+     * at its parent's position. Callables are not descended into.
+     *
+     * Bounded and cycle-safe. It only has to tell a schema's input apart from its
+     * output, so a subtree past the bound is not compared, and that is logged:
+     * a coercion below the bound prints as its input declares it.
+     */
+    walkTypePositions(root, at, where, visit) {
+        const MAX_DEPTH = 8;
+        const MAX_VISITED = 512;
+        const onPath = new Set();
+        let visited = 0;
+        let bounded = false;
+        const walk = (type, position, depth, unionPart) => {
+            if (depth > MAX_DEPTH || visited > MAX_VISITED) {
+                bounded = true;
+                return;
+            }
+            if (!visit(type, position, unionPart)) {
+                return;
+            }
+            const compilerType = type.compilerType;
+            if (onPath.has(compilerType)) {
+                return;
+            }
+            onPath.add(compilerType);
+            visited += 1;
+            try {
+                const parts = type.isUnion()
+                    ? type.getUnionTypes()
+                    : type.isIntersection()
+                        ? type.getIntersectionTypes()
+                        : undefined;
+                if (parts) {
+                    for (const part of parts) {
+                        walk(part, position, depth + 1, true);
+                    }
+                    return;
+                }
+                if (type.isArray()) {
+                    const element = type.getArrayElementType();
+                    if (element) {
+                        walk(element, `${position}<0>`, depth + 1, false);
+                    }
+                    return;
+                }
+                if (!type.isObject() || this.isCallableType(type)) {
+                    return;
+                }
+                for (const property of type.getProperties()) {
+                    let propertyType;
+                    try {
+                        propertyType = property.getTypeAtLocation(at);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const name = property.getName();
+                    walk(propertyType, position === '' ? name : `${position}.${name}`, depth + 1, false);
+                }
+            }
+            finally {
+                onPath.delete(compilerType);
+            }
+        };
+        walk(root, '', 0, false);
+        if (bounded) {
+            this.log(`Schema type at ${where} is deeper or wider than the position walk bound ` +
+                `(depth ${MAX_DEPTH}, ${MAX_VISITED} members); members past it are not ` +
+                'compared for coercion');
+        }
     }
     /**
      * Follow a schema REFERENCE call (`ref('CreateWidget')`) to the schema value
@@ -3479,8 +3788,9 @@ export class TypeInferrer {
     }
     /**
      * The parsed output type of a schema value: the return type of its `parse`
-     * method, else a declared `_output` member. Returns undefined when neither
-     * carries a usable type — including when the schema library's own types are
+     * method, else a declared `_output` member, else the Standard Schema member
+     * `~standard.types.output` (a library that exposes nothing else). Returns
+     * undefined when none carries a usable type — including when the schema library's own types are
      * unavailable (an uninstalled dependency resolves the schema to `any`), which
      * must abstain rather than publish `any` as a contract.
      */
@@ -3507,13 +3817,62 @@ export class TypeInferrer {
         const outputSymbol = schemaType.getProperty('_output');
         if (outputSymbol) {
             try {
-                return usable(outputSymbol.getTypeAtLocation(at));
+                const declared = usable(outputSymbol.getTypeAtLocation(at));
+                if (declared) {
+                    return declared;
+                }
             }
             catch {
-                return undefined;
+                // fall through to the Standard Schema member
             }
         }
-        return undefined;
+        return usable(this.standardSchemaType(schemaType, at, 'output'));
+    }
+    /**
+     * The input type of a schema value, what a caller may send (carrick#1101):
+     * the Standard Schema member `~standard.types.input`, else a declared
+     * `_input` member. Undefined when the schema declares neither.
+     *
+     * Unlike the output, an input of `unknown` is kept: it is a declared fact
+     * (a coercion accepts any value), and `schemaContract` decides what to
+     * publish for it. An `any` that is really an unresolved library still reads
+     * as no input, because an unresolved schema type has no members to read.
+     */
+    schemaInputType(schemaType, at) {
+        const standard = this.standardSchemaType(schemaType, at, 'input');
+        if (standard) {
+            return standard;
+        }
+        const inputSymbol = schemaType.getProperty('_input');
+        if (!inputSymbol) {
+            return undefined;
+        }
+        try {
+            return inputSymbol.getTypeAtLocation(at);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * `~standard.types.<side>` on a schema value: the Standard Schema
+     * specification's library-neutral statement of a schema's input and output
+     * types. `types` is declared optional, so its `undefined` is stripped before
+     * the side is read.
+     */
+    standardSchemaType(schemaType, at, side) {
+        try {
+            const standard = schemaType.getProperty('~standard');
+            const types = standard?.getTypeAtLocation(at).getProperty('types');
+            const member = types
+                ?.getTypeAtLocation(at)
+                .getNonNullableType()
+                .getProperty(side);
+            return member?.getTypeAtLocation(at);
+        }
+        catch {
+            return undefined;
+        }
     }
     /**
      * Find a node by matching expression text near a target line.

package/sidecar/dist/src/type-structural-expander.d.ts

@@ -28,22 +28,51 @@
  * `type-inferrer.ts` (consumer-side inference), so both paths emit the same
  * structural form rather than a dangling name.
  */
-import { type Type } from 'ts-morph';
+import { type Node, type Type } from 'ts-morph';
 /**
  * Bound on the structural-expansion recursion. Deep enough for every realistic
  * request/response shape; a backstop against pathological/recursive types the
  * cycle set somehow misses.
  */
 export declare const MAX_EXPANSION_DEPTH = 12;
+/**
+ * Types to print at named member positions instead of the walked type
+ * (carrick#1105).
+ *
+ * A validation schema's request contract is its INPUT, except at a member
+ * whose input is `unknown` and whose output is concrete (a coercion): that
+ * member prints the OUTPUT type. The substitution is per member, so it has to
+ * happen inside the walk, where the member is printed.
+ *
+ * Positions use the member-path notation of the provenance entries: `''` for
+ * the root, `sub.field` for a property (keyed by symbol name), `items<0>` for
+ * an array element; union and intersection members share their parent's
+ * position. The walk records every position it printed an override at in
+ * `applied`, so a caller can tell a substitution the walk could not reach (a
+ * tuple, a cycle, the depth backstop) from one it made.
+ *
+ * `at` is the node the member types are read at while walking toward an
+ * override. A library's inferred object type is a mapped type whose member
+ * declaration sits inside a generic, where the member reads as `any`; read at
+ * the schema's own node it is the instantiated type, the same read the
+ * caller's position walk makes.
+ */
+export interface MemberOverrides {
+    readonly types: ReadonlyMap<string, Type>;
+    readonly applied: Set<string>;
+    readonly at: Node;
+}
 /**
  * Recursively render a `Type` as fully-inlined structural text.
  *
  * Named object/interface types are expanded to their member structure;
  * primitives, literals, library types (`Date`, `Promise`, tuples, …) and
  * functions stay by name. The `seen` set (object type ids on the current
- * branch) breaks reference cycles; `depth` is a hard backstop.
+ * branch) breaks reference cycles; `depth` is a hard backstop. `overrides`
+ * substitutes a type at named member positions (`MemberOverrides`); without
+ * it the print is unchanged.
  */
-export declare function expandTypeStructural(type: Type, seen?: Set<number>, depth?: number): string;
+export declare function expandTypeStructural(type: Type, seen?: Set<number>, depth?: number, overrides?: MemberOverrides): string;
 /**
  * Non-expanded text for a type. Passes `undefined` as the enclosing node so
  * the compiler can't throw on an invalid node context (tuples and some