carrick 0.3.53

package/sidecar/dist/src/type-inferrer.d.ts

@@ -0,0 +1,940 @@
+/**
+ * Type Inferrer - Scope-based type inference with payload unwrapping
+ *
+ * This module extracts types even when developers don't write explicit
+ * annotations. It uses span-based node lookup (no line windows) to target
+ * precise expressions provided by the Rust/LLM pipeline.
+ *
+ * Key feature: Agent-informed payload unwrapping
+ * - Extracts payload types from machinery wrappers (Response<T>, AxiosResponse<T>, etc.)
+ * - Supports union/intersection composition
+ * - Recursive unwrapping with depth limits
+ *
+ * Framework agnosticism: The LLM emits the payload subexpression directly (e.g.,
+ * the `users` in `res.json(users)`, `ctx.body = users`, `h.response(users)`, or
+ * `return users`). The sidecar resolves that node and reads its type — no
+ * framework-specific method-name lists live here. For payload-less handlers
+ * (redirects, 204s), the LLM emits null and we fall back to the containing
+ * function's return type.
+ */
+import { Project } from 'ts-morph';
+import type { InferRequestItem, InferResult, ExtractionConfig } from './types.js';
+/**
+ * Strongly-discriminating member names of HTTP transport machinery — the
+ * fetch/DOM `Response` & `Request`, a Node `http.ServerResponse`, a framework
+ * reply object. A type declared in a lib or `node_modules` origin that carries
+ * a subset of these is framework machinery, never a user contract: the
+ * PRODUCER-side structural mirror of the consumer `machineryIndicators`
+ * (ExtractionConfig), used to reject a wrapper envelope whose response field is
+ * a raw `Response` (carrick#371) instead of emitting it as a comparable type.
+ *
+ * Framework-agnostic by construction: no framework NAME appears here, only the
+ * shared HTTP-message surface. The names are deliberately the ones no
+ * JSON payload ever carries (`ok`, `redirected`, `bodyUsed`, `arrayBuffer`,
+ * `writeHead`, ...), so the origin gate + `MACHINERY_INDICATOR_THRESHOLD` never
+ * fire on real data. Kept in lockstep with the capture-seam mirror
+ * `capture/machinery.ts` (the seam forbids sharing a module across it, same as
+ * `BUILTIN_ANCHOR_SYMBOLS` mirrors `socket_io.rs`). Exported so a drift-guard
+ * test (`machinery-indicator-mirror.test.ts`) asserts the two sets stay equal.
+ */
+export declare const MACHINERY_MEMBER_INDICATORS: Set<string>;
+/**
+ * Options for TypeInferrer construction
+ */
+export interface TypeInferrerOptions {
+    /** The ts-morph Project instance */
+    project: Project;
+}
+/**
+ * TypeInferrer - Extracts types from source code, both explicit and inferred
+ *
+ * Usage:
+ *   const inferrer = new TypeInferrer({ project });
+ *   const result = inferrer.infer(requests, extractionConfig);
+ */
+export declare class TypeInferrer {
+    private readonly project;
+    constructor(options: TypeInferrerOptions);
+    /**
+     * Infer types for the given requests
+     *
+     * @param requests - Array of inference requests
+     * @param extractionConfig - Agent-generated extraction config for payload unwrapping
+     * @returns InferResult with inferred types or errors
+     */
+    infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig): InferResult;
+    /**
+     * Infer a single type from a request
+     */
+    private inferSingle;
+    /**
+     * Get or add a source file to the project
+     */
+    private getSourceFile;
+    private inferFunctionReturn;
+    /**
+     * Build a `function_return` inferred type from an already-resolved function
+     * node: unwrap `Promise<…>` / async-iterator transport, apply the extraction
+     * config to the awaited type, and expand a bare named return structurally.
+     * Extracted from `inferFunctionReturn` so the route-registration path
+     * (`inferResponseBody` following a handler) can reuse the exact same logic
+     * against the handler function instead of the containing function.
+     */
+    private buildFunctionReturnInferredType;
+    /**
+     * Infer a function's return type for the signature hint. Unlike
+     * `inferFunctionReturn`, this does NOT unwrap Promise or apply wrapper
+     * rules — a function that returns `Promise<AuthResult>` should show exactly
+     * that in its signature. Used by the function-signature collection pass.
+     */
+    private inferSignatureReturn;
+    /**
+     * Infer the type of a single named parameter. `is_explicit` reflects whether
+     * the parameter carries a source annotation; the type string is the
+     * compiler's view either way (so contextually-typed callback params resolve
+     * even without an annotation). Uses ts-morph's default `getText()` form,
+     * which keeps named types as names and bounds depth via the compiler's own
+     * truncation.
+     */
+    private inferFunctionParam;
+    /**
+     * Resolve a `function_param` locator against a function's parameter list.
+     * Three shapes, tried in order:
+     *
+     * 1. A parameter whose name matches exactly (`(payload) => …` ← "payload").
+     * 2. A parameter whose DESTRUCTURED BINDING PATTERN matches the locator
+     *    text under whitespace normalization (`({ time, run }) => …` ←
+     *    "{ time, run }") — the handler destructures the payload itself, so the
+     *    pattern's own type IS the payload type.
+     * 3. A named BINDING ELEMENT inside a destructured parameter
+     *    (`({ payload }) => …` ← "payload") — the payload is one property of an
+     *    envelope param, and the checker projects the element's type
+     *    (catalog-worker handlers: `params: { id, payload: Infer<…> }`).
+     *
+     * All three read the type off a node the checker has already instantiated,
+     * so generic wrappers (topic-map emitters, schema catalogs, channel handles)
+     * resolve without any named payload symbol existing anywhere.
+     */
+    private resolveParamTarget;
+    private inferResponseBody;
+    private inferCallResult;
+    private inferVariable;
+    private inferExpression;
+    private inferRequestBody;
+    private resolveCallResultTerminalNode;
+    private extractBindingFromCall;
+    private extractBindingNames;
+    private getPrimaryBindingNode;
+    private collectDefUseNodes;
+    private expressionUsesNames;
+    private isIdentifierUsage;
+    private isInFunctionScope;
+    /**
+     * Resolve the awaited type: `Promise<X>` / `PromiseLike<X>` / `Awaited<X>` →
+     * `X` at the type level (recursively, so `Awaited<Promise<X>>` → `X`); any
+     * non-thenable type passes through UNCHANGED.
+     *
+     * ts-morph 25.0.1 does not expose the compiler's `getAwaitedType` on its
+     * `Type` wrapper (only `AwaitableNode.isAwaited()` on AST nodes, which is
+     * unrelated), so we resolve structurally on the symbol/alias name instead of
+     * gating on the literal `'Promise'` symbol. This generalizes past `Promise<T>`
+     * to `PromiseLike<T>` and the `Awaited<T>` utility type without over-unwrapping:
+     * a non-thenable like `AsyncGenerator<T>` is NOT awaitable and is returned
+     * unchanged, so the `unwrapAsyncIterableType` step that runs right after still
+     * sees (and peels) the iterator wrapper as before.
+     */
+    private unwrapPromiseType;
+    /**
+     * `AsyncGenerator<T, …>` / `AsyncIterableIterator<T>` / `AsyncIterator<T>` /
+     * `Generator<T, …>` / `IterableIterator<T>` → `T` (the yield type) at the type
+     * level; any other type passes through. A GraphQL subscription resolver written
+     * as `async function* x(): AsyncGenerator<Order>` carries its contract in the
+     * yield position, so the iterator wrapper must be peeled the same way Promise is
+     * before structural expansion — otherwise the response contract resolves to the
+     * library `AsyncGenerator<…>` machinery instead of the bare `Order`.
+     */
+    private unwrapAsyncIterableType;
+    /** The "leave the type as it is" result every bail-out path shares. */
+    private noUnwrap;
+    /**
+     * Unwrap a type using the agent-generated ExtractionConfig.
+     */
+    private unwrapTypeWithConfig;
+    /**
+     * Core unwrapping implementation with ExtractionConfig rules.
+     *
+     * Requirements:
+     * 1. Exact wrapperSymbols match extracts (gated on originModuleGlobs when
+     *    the rule carries them — names like `Response` are shared by the DOM,
+     *    frameworks, and HTTP clients)
+     * 2. machineryIndicators only trigger unwrap if originModuleGlobs also match
+     * 3. Handle unions and intersections
+     * 4. Support recursive unwrapping with depth limits
+     * 5. A rule that matches but extracts nothing never blocks later rules;
+     *    only after every rule has run does an origin-verified match with no
+     *    recoverable payload collapse to `unknown`
+     */
+    private unwrapType;
+    /**
+     * Try to unwrap a type using a single ExtractionRule.
+     */
+    private tryUnwrapWithRule;
+    /**
+     * Extract the payload type from a matched wrapper. Returns null when the
+     * rule matched the wrapper but no payload is recoverable from generics or
+     * property paths — the caller decides what a payload-less match means
+     * (verified machinery collapses to `unknown` after every rule has run;
+     * a name-only match leaves the type untouched).
+     */
+    private extractPayloadFromWrapper;
+    /**
+     * True when a producer RESPONSE type IS or CONTAINS framework transport
+     * machinery (a fetch/DOM `Response`, a Node `ServerResponse`, a reply object)
+     * — the artifact behind carrick#371, where a wrapped handler's literal return
+     * envelope `{ response: Response; error?: undefined } | { ...; error: Error }`
+     * was captured as the response contract. Machinery is never a comparable
+     * contract, so a response path that resolves here abstains (honest `unknown`)
+     * rather than emit a concrete-but-false type.
+     *
+     * DETECTS, exactly (see `typeIsOrContainsMachinery`):
+     *   1. the type itself is machinery (`typeIsFrameworkMachinery`);
+     *   2. a union/intersection member is machinery (the envelope union);
+     *   3. a DIRECT property's type is machinery, ONE level of descent only
+     *      (`{ response: Response; error }`).
+     *
+     * DELIBERATELY NOT DETECTED — listed so this comment never overstates the
+     * guarantee (an overstated safety comment is what bit sibling PR #442). Each is
+     * a non-regression: it leaves the pre-existing verdict unchanged and never
+     * manufactures a new wrong one, tracked as a follow-up:
+     *   - machinery nested deeper than one property level (a property whose type
+     *     is itself a nested object wrapping the machinery);
+     *   - a property typed `Promise<Response>` (the property type is NOT awaited /
+     *     Promise-unwrapped before the machinery check);
+     *   - an array element type: `Response[]` is not descended to its element;
+     *   - `interface X extends Response` declared in USER source — the origin gate
+     *     is lib/`node_modules` only, so a user-declared subtype reads as a real
+     *     contract, not machinery;
+     *   - a function / call-signature return type: the response paths that call
+     *     this resolve a handler's RETURN (an envelope/object), never a function
+     *     value, so no call-signature descent happens here. The capture-seam
+     *     mirror `capture/machinery.ts` DOES descend call signatures — that is
+     *     where the wrapper-FUNCTION type the Infer fallback resolves is caught.
+     *
+     * The origin gate in `typeIsFrameworkMachinery` keeps a user object whose
+     * fields merely share a member name from tripping.
+     */
+    private typeIsOrContainsResponseMachinery;
+    private typeIsOrContainsMachinery;
+    /**
+     * True when `type` itself is an HTTP-machinery type: it structurally carries
+     * at least `MACHINERY_INDICATOR_THRESHOLD` of the strongly-discriminating
+     * `MACHINERY_MEMBER_INDICATORS`, AND its symbol is declared in a lib
+     * (`lib.dom.d.ts`, ...) or `node_modules` origin. Both gates are required —
+     * the indicator subset alone essentially never matches a JSON payload, and
+     * the origin gate makes certain a user's own local type sharing those member
+     * names is never mistaken for framework machinery (the advisor's guard).
+     */
+    private typeIsFrameworkMachinery;
+    /**
+     * True once the type carries at least `MACHINERY_INDICATOR_THRESHOLD` DISTINCT
+     * `MACHINERY_MEMBER_INDICATORS` (own + apparent). Deduplicates by name (own and
+     * apparent property lists overlap) and early-returns the moment the threshold
+     * is reached — the callers only need the boolean, never the full count.
+     */
+    private hasMachineryIndicatorThreshold;
+    /**
+     * True when the symbol is declared in a TypeScript lib file (`lib.*.d.ts`) or
+     * under `node_modules` — i.e. framework/runtime machinery, not user source.
+     * Works on a bare checkout: the DOM `Response`/`Request` resolve from the
+     * bundled `lib.dom.d.ts` even with no installed dependencies.
+     */
+    private symbolIsLibOrExternalOrigin;
+    /**
+     * Check if a type has machinery indicator properties/methods.
+     */
+    private typeHasMachineryIndicators;
+    /**
+     * Check if a symbol's declarations originate from modules matching the globs.
+     */
+    private symbolOriginatesFromModules;
+    /**
+     * Simple glob matching for module paths.
+     * Supports: exact match, a trailing "*" wildcard, and "package/*" patterns.
+     *
+     * Matches are segment-bounded: the glob names a package (or package
+     * subpath) under node_modules, and the match must end at a path-segment
+     * boundary — `got` matches `node_modules/got/...` but never
+     * `node_modules/got-scraping/...`. This matters because the exact-symbol
+     * origin gate routes shared names like `Response` through here.
+     */
+    private filePathMatchesModuleGlob;
+    /**
+     * Check if a type string is "useless" for payload purposes.
+     */
+    private isUselessType;
+    private unwrapExpressionNode;
+    /**
+     * If `node` is a `JSON.stringify(arg)` call, return the (expression-unwrapped)
+     * first argument so its type is read instead of the call's `string` result.
+     * Otherwise return `node` unchanged. Any non-`JSON.stringify` call, or a
+     * `JSON.stringify()` with no argument, is left alone.
+     */
+    private unwrapJsonStringifyArg;
+    private extractExplicitTypeFromAncestor;
+    /**
+     * Render an explicit annotation (`as T`, `<T>`, or a typed binding) as
+     * fully-structural text.
+     *
+     * `typeNode.getText()` keeps a named type as its bare identifier
+     * (`OrderView`, `Promise<Payment>`). A bare name is fine inside the source
+     * project but becomes a dangling reference in the cross-repo `.d.ts` bundle,
+     * which carries only alias lines and no source declarations — it resolves to
+     * `any` and the comparison reads `unverifiable`. Resolving the annotation to
+     * its `Type`, stripping `Promise<…>` at the type level, and expanding the
+     * object structurally (shared with `definition-resolver.ts`) lands the real
+     * shape (`{ id: string; currency: string }`) in the bundle so the consumer
+     * can actually be compared.
+     *
+     * Falls back to the bare annotation text when the resolved type can't be
+     * expanded to a structural form (primitives, library types, unresolvable
+     * references), so a non-object annotation behaves exactly as before.
+     */
+    private expandAnnotationTypeNode;
+    /**
+     * Producer-side analogue of `expandAnnotationTypeNode` that works from a
+     * resolved `Type` rather than a syntactic annotation node.
+     *
+     * `inferResponseBody`/`inferFunctionReturn` resolve a payload to a named
+     * object type (e.g. `Payment`), then render it with `typeText`, which keeps
+     * the bare name. In the source-less cross-repo `.d.ts` bundle that name is a
+     * dangling `export type <alias> = Payment;` → resolves to `any` →
+     * `unverifiable` → `compat = None`. Expanding the resolved object structurally
+     * lands the real members (`{ id: string; … }`) in the bundle so the producer
+     * can be compared. Mirror of #257's consumer-side fix; keeps the bare text for
+     * primitives, library types, and anything the expander leaves by name.
+     *
+     * `fallback` is the already-computed type text (post Promise/wrapper unwrap),
+     * preserved verbatim when expansion does not inline an object.
+     */
+    private expandResolvedTypeStructural;
+    /**
+     * Recover a response contract from a handler's own `return` statements when
+     * the resolved return type carries none.
+     *
+     * A file-based route `loader`/`action` almost never annotates its return: the
+     * payload goes through a helper — `json(payload)`, `reply(payload, opts)`,
+     * `wrap(request, json(payload))` — and the helper's result is transport, not
+     * contract. Two ways that collapses today:
+     *
+     *   * the helper is typed and returns machinery (`Promise<Response>`), so the
+     *     carrick#371 guard abstains and the manifest reads `unknown`;
+     *   * the helper comes from a package with no installed declaration (the
+     *     scanner reads a bare checkout), so it resolves to `any` and the whole
+     *     response reads `any`.
+     *
+     * In both, the contract is the helper's ARGUMENT — every framework that ships
+     * such a helper is generic over it. This walks the handler's returned
+     * expressions, descends through wrapper calls to the first argument that
+     * carries a payload, and unions the surviving branches. It is structural
+     * throughout: no helper, framework or package name is matched anywhere, and
+     * the recovery only runs where the existing path already had nothing.
+     *
+     * `statedOnly` is the guard for the unresolvable-callee case. A return type
+     * of `any` does not say the callee was a response helper, only that it could
+     * not be resolved, and on a bare checkout that is true of most imported
+     * callees: `return db.findMany({ where })` would otherwise report the query
+     * object as the endpoint's contract, which is a false contract and worse
+     * than `unknown`. With `statedOnly` set, only an argument the source
+     * annotates (`satisfies` / `as` / `<T>`) counts, because there the developer
+     * stated the contract. The machinery case leaves it clear: the callee is
+     * known transport, so its argument is the payload whatever its type.
+     *
+     * Returns `null` (a logged limitation, never a guess) when no returned
+     * expression yields an argument type this may read.
+     */
+    private recoverPayloadFromReturnStatements;
+    /**
+     * The expressions a function returns, excluding returns belonging to nested
+     * functions (a `.map(x => …)` callback returns a row, not the response).
+     * A concise arrow body is itself the returned expression.
+     */
+    private returnedExpressions;
+    /**
+     * The expressions that can carry this handler's response: its own returned
+     * expressions, plus the returned expressions of any function the handler
+     * hands DIRECTLY to a returned call (carrick#707).
+     *
+     * `return settle(...).then(ok => serialise(body), err => serialise(problem))`
+     * returns a call whose result is whatever the callbacks produce, so the
+     * callbacks' returns are this handler's returns as surely as its own. That
+     * shape is how a result-type API, a promise combinator or a matcher is
+     * written, and on a bare checkout the callee resolves to nothing, so the
+     * outer call's type says nothing at all.
+     *
+     * Only ONE level, and only from the returned call's own arguments. A
+     * callback nested deeper is inside an expression the handler computes, not
+     * an expression it returns — `return rows.map(r => …)` returns a row list,
+     * and reading the callback there would report a row as the response. Each
+     * flattened expression still has to pass the payload rule below, which no
+     * bare object literal does.
+     */
+    private responseReturnedExpressions;
+    /**
+     * The callees these returned expressions PROVE are response serialisers.
+     *
+     * A return type of `any` says the callee could not be resolved, not that it
+     * was a serialiser — the reason the unresolvable-callee case is otherwise
+     * restricted to arguments the source annotates. But a handler that writes
+     *
+     *     return f(problem, { status: 401 });
+     *     return f(payload);
+     *
+     * has stated what `f` is in its own source: a call that takes a body and,
+     * beside it, an HTTP status is a response serialiser, and nothing else is
+     * written that way. That is evidence the compiler does not need to resolve
+     * anything to see, so it survives the bare checkout CI scans, and it makes
+     * the second call's unannotated argument a payload rather than a guess.
+     *
+     * Three deliberate limits, each a negative test:
+     *  - only RETURNED expressions count. A handler may well call a logger with
+     *    `{ status: 500 }`; what it returns is what it serialises.
+     *  - the status-stating argument must sit at index >= 1. A status in FIRST
+     *    position is a field of the body (`{ status: 503, note }`), and reading
+     *    it as evidence would promote every callee that takes a status field.
+     *  - the evidence is per HANDLER, never cached across files. It says what
+     *    this handler does, and that is all it is used for.
+     *
+     * Callees are keyed by resolved symbol where one exists — an import alias
+     * resolves locally even when its module does not — and by callee text
+     * otherwise.
+     */
+    private calleesProvenSerialiser;
+    /**
+     * Stable identity for a call's callee within one file: its resolved symbol
+     * when the compiler has one, else the callee's source text.
+     */
+    private calleeIdentity;
+    /**
+     * The payload argument of a returned response-helper call, or `undefined`.
+     *
+     * Walks the call's arguments in source order: the first whose type reads as a
+     * contract wins; an argument that is itself a call is descended into, which is
+     * what recovers `wrap(request, json(payload))` — the transport wrapper's own
+     * first argument is the request, which never reads as a contract.
+     *
+     * A call whose sibling options object states a >= 400 status is an error
+     * branch and contributes nothing: the response contract of an endpoint is the
+     * shape it returns when it succeeds.
+     *
+     * `statedOnly` narrows what counts as a payload to an argument the source
+     * annotates; see `recoverPayloadFromReturnStatements`. It is lifted for a
+     * callee the handler's own returned calls PROVE is a serialiser
+     * (`calleesProvenSerialiser`): there the source has stated what the callee
+     * is, so its argument is the payload even unannotated.
+     */
+    private responseHelperPayloadNode;
+    /**
+     * True when a node's type reads as a response payload.
+     *
+     * Object-shaped only (an object literal, a named interface, an array of
+     * either, or a union containing one). A bare primitive argument is a
+     * redirect location, a status code or a body string — `redirectTo("/next")`
+     * must never report `"/next"` as the endpoint's contract. A stated
+     * `satisfies`/`as` annotation counts even when its declaration is missing:
+     * the source says what the contract is.
+     *
+     * Under `statedOnly` the annotation is the ONLY thing that counts, so an
+     * unresolvable callee's arguments never become a contract by accident.
+     */
+    private nodeCarriesPayloadContract;
+    /** Object, array-of-object, or a union/intersection containing one. */
+    private typeIsObjectShaped;
+    /**
+     * The `satisfies X` / `as X` / `<X>` annotation node on an expression, when
+     * the source states its type. `satisfies` is the shape a route uses to claim
+     * a shared response contract without widening the literal.
+     */
+    private statedTypeNodeOf;
+    /**
+     * True when an argument states a >= 400 status: an options object carrying
+     * `status`/`statusCode`, or a bare status code (`send(body, 404)`).
+     *
+     * Read from the AST first: `{ status: 400 }` in an argument position widens
+     * to `{ status: number }`, so the literal only survives syntactically. The
+     * type check behind it catches `as const` and hoisted option objects.
+     */
+    private statesErrorStatus;
+    /**
+     * The HTTP status an argument states, or `undefined`.
+     *
+     * Read from the AST first: `{ status: 400 }` in an argument position widens
+     * to `{ status: number }`, so the literal only survives syntactically. The
+     * type check behind it catches `as const` and hoisted option objects. Only
+     * values in the HTTP range count — an arbitrary number named `status` on a
+     * domain object (`{ status: 2 }`) states nothing about transport.
+     */
+    private statedStatusCode;
+    /**
+     * Peel the wrappers that do not change an expression's payload: parentheses
+     * and `await`. Unlike `unwrapExpressionNode` this KEEPS `as`/`satisfies`,
+     * because the annotation is exactly what the recovery wants to read.
+     */
+    private peelTransparentExpression;
+    /**
+     * The deterministic source symbol of a resolved type (`Payment` for a payload
+     * typed `Payment`), or `undefined` when there is no single user-defined
+     * symbol to anchor on. This is the same `getSymbol() || getAliasSymbol()` name
+     * the socket anchor already derives (`socket_io.rs`), filtered through
+     * `BUILTIN_ANCHOR_SYMBOLS` so TS/lib globals (`Promise`, `Array`, `Date`,
+     * primitives, …) never become an anchor. Used to populate
+     * `primary_type_symbol` so the manifest anchor no longer depends on the LLM.
+     */
+    private primaryTypeSymbol;
+    /**
+     * Declaration file (absolute path) of the anchor symbol
+     * `primaryTypeSymbol` reports for this type, or `undefined` when the type
+     * has no user-facing anchor or no source declaration. The scanner's
+     * pub/sub two-anchor arbitration (carrick#413) uses this to re-aim a
+     * demoted explicit bundle request: the bundler resolves a `SymbolRequest`
+     * only against declarations IN its `source_file`, so the request must
+     * point at the file that actually declares the tsc-witnessed payload type.
+     *
+     * Only declaration kinds the bundler's `validateSymbols` can resolve
+     * (interface, type alias, class, enum, function, variable) count. A
+     * symbol's declaration list can also contain re-export machinery — a
+     * barrel's `ExportSpecifier` (`export { Foo } from './foo'`) points at a
+     * file that does not DECLARE the type, and a request re-aimed there would
+     * fail validation, turning a resolvable explicit type into `unknown`.
+     * With no declaring node, no source is reported and the arbitration
+     * fails closed to the explicit anchor.
+     */
+    private primaryTypeSymbolSource;
+    /**
+     * The anchor a `satisfies X` / `as X` / `<X>` annotation states IN SOURCE:
+     * the name written at the annotation, where its type is declared, and the
+     * array levels wrapped around it (`satisfies Order[]` → `Order`, depth 1).
+     *
+     * carrick#768: reading the anchor off the RESOLVED type works for an
+     * interface, whose type carries its own symbol, and fails for
+     *
+     *     export type OrderBody = Inferred<typeof OrderSchema>;
+     *
+     * because the alias resolves to an instantiated type TypeScript keeps no
+     * alias symbol on, so `getSymbol()` answers the synthetic `__type`. The
+     * route then published a correct shape with no name, and
+     * `primary_type_symbol` is precisely how a reader gets from a route to the
+     * type its consumer imports. The annotation names it either way, so read
+     * the name from the AST and confirm it against the declaration it resolves
+     * to. This is the fallback for a resolved type that anchored nothing, never
+     * an override of one that did.
+     *
+     * Four things are rejected, so a name only anchors when it is genuinely the
+     * contract a consumer would import:
+     *  - a generic instantiation (`satisfies Envelope<Order>`) names the
+     *    WRAPPER, and a bare `Envelope` is not the payload;
+     *  - a name resolving to no type declaration — an import of a value, a
+     *    re-export the checker cannot follow — is not importable as a type;
+     *  - a declaration in the TypeScript default library, and every
+     *    `BUILTIN_ANCHOR_SYMBOLS` name, which describe machinery not contracts;
+     *  - an inline annotation (`satisfies { id: string }`), which names nothing.
+     */
+    private writtenAnchorOf;
+    /**
+     * Peel array levels off a resolved type: `TimelineEvent[]` → element
+     * `TimelineEvent`, depth 1. An array type's own symbol is `Array` (builtin,
+     * filtered), so without this a `T[]` payload has NO anchor and — worse — an
+     * explicit anchor bundled for the same alias silently drops the array-ness
+     * (#306: array-vs-scalar scored compatible). The element drives the anchor
+     * symbol; the depth is reported on the `InferredType` so the bundler's
+     * existing `array_depth` wrap (#248) can restore the `[]` levels on the
+     * explicit bundle. Depth is capped at the bundler's sane ceiling; a deeper
+     * type is treated as depth 0 rather than a runaway loop.
+     */
+    private unwrapArrayLevels;
+    /**
+     * Resolve the target node using the best available locator:
+     * 1. If span_start + span_end present → findNodeAtSpan (SWC byte offsets)
+     * 2. If expression_text present → findNodeByText (Gemini text + line)
+     * 3. Otherwise → undefined
+     */
+    /**
+     * carrick#695: the type of the RECEIVER of a member call, plus the two facts
+     * a role decision needs about it — which package declares that type, and what
+     * the invoked member returns.
+     *
+     * Nothing here classifies. A member call with a route-shaped literal
+     * (`x.verb("/lit", arg)`) is a route registration or a request depending on
+     * what `x` IS, and that is the only question this answers. The Rust driver
+     * maps the declaring package onto the detected framework / data-fetcher
+     * lists; the compiler layer names no library and applies no shape rule.
+     *
+     * A receiver that does not resolve reports its top type (`any`) with no
+     * package, so the caller can tell "unresolved" from "declared here": on a
+     * checkout with no installed dependencies EVERY dependency-typed receiver is
+     * `any`, and treating that as workspace-owned would invent a role.
+     */
+    private inferReceiverType;
+    /**
+     * The npm package name that declares a type, read off its declaration's file
+     * path. `undefined` when the type has no declaration to read (a top type, a
+     * primitive, an anonymous object literal) or when its declaration is not
+     * under a `node_modules` tree — a type the workspace itself declares.
+     *
+     * The LAST `node_modules` segment wins, which is what a nested or
+     * content-addressed store (`node_modules/.store/pkg@1.0.0/node_modules/pkg`)
+     * requires. Scoped names keep both segments.
+     */
+    private declaringPackageOf;
+    /**
+     * The awaited return type of the member invoked on the receiver. Reported as
+     * a fact next to the receiver; a caller that classified on it alone would be
+     * back to a shape rule (any async helper taking a path would match).
+     */
+    private memberReturnTypeOf;
+    /**
+     * A type's own name when it has one, else its printed form.
+     *
+     * The printed form of a type whose declaring module the use site does not
+     * import is `import("/abs/path/to/module").Name` — an absolute path that
+     * would be persisted and rendered. The name alone is both stable and the
+     * part a reader (or a package-list lookup) uses; anonymous types, top types
+     * and primitives have no name and keep their printed text.
+     */
+    private namedTypeLabel;
+    /**
+     * A type's own name, or `an unnamed branch` when it has none.
+     *
+     * Unlike `namedTypeLabel` this never falls back to the printed form, because
+     * its output reaches a reader as a provenance `detail`, and the printed form
+     * of a type whose declaring module the use site does not import is
+     * `import("/abs/path").Name`. The bar for a detail is "one scrubbed sentence,
+     * never an absolute path", so an anonymous branch is described rather than
+     * printed.
+     */
+    private pathFreeTypeLabel;
+    private resolveTargetNode;
+    /**
+     * Resolve to a CallExpression using the best available locator.
+     */
+    private resolveTargetCallExpression;
+    /**
+     * Resolve to a containing function using the best available locator.
+     */
+    private resolveContainingFunction;
+    /**
+     * Find the function whose declaration starts at (or within a couple of lines
+     * of) the given line. Used for signature inference, where the only locator is
+     * the function's start line as recorded by the scanner. Ties break toward the
+     * innermost (smallest) function. Returns undefined if nothing is close enough,
+     * to avoid binding to an unrelated function.
+     *
+     * The tolerance is one-directional in effect (carrick#766). Looking BACK is
+     * free: a function starting before the anchor is one the anchor sits inside
+     * or just after, which is what an anchor recorded on a signature or body line
+     * means. Looking FORWARD is how the anchor reaches a handler that starts a
+     * line or two into the registration or binding it names — and it is also how,
+     * unguarded, an anchor landing on a statement that declares no function
+     * (`export { action, loader };`) was answered by the NEXT declaration in the
+     * file. That answer is silent: nothing about it says it came from a
+     * neighbouring helper.
+     *
+     * So a forward candidate must be one the anchor line's own statement leads
+     * to: rejected when a statement begins at or after the anchor line and does
+     * not contain it. Nothing but trivia may sit between the anchor and the
+     * function it is taken to name. With no candidate left the caller abstains,
+     * which is the honest answer and the one a consumer check can act on.
+     */
+    private findFunctionByLine;
+    /**
+     * Walk up from a node to find its innermost containing function.
+     */
+    private findContainingFunctionForNode;
+    /**
+     * Follow a LINE-ONLY route-registration anchor to its handler function. The
+     * scanner sends a bare line number (no span/text) for a named-handler
+     * registration whose handler is declared away from the registration line
+     * (`InferLocator::Line`). Find a registration node — a call or object literal
+     * — that STARTS on that line and whose handler resolves, and return it.
+     * Structural (call with a function-typed arg, or handler-shaped object-literal
+     * property), no framework name-lists. Used only when the primary locator did
+     * not resolve a node, so no existing path changes.
+     */
+    private handlerAtLine;
+    /**
+     * The route registration on `line` together with the handler it references.
+     *
+     * `handlerAtLine` returns only the handler, but the route's DECLARED contract
+     * (a validation-schema object passed alongside the handler) lives on the
+     * registration node itself, so the schema anchors need both halves.
+     */
+    private registrationAtLine;
+    /**
+     * Follow a route-registration locator ONE indirection to the handler function.
+     *
+     * The scanner points the infer request at the registration site, but the
+     * type-bearing expression (the handler's return, or its first request read)
+     * lives inside the handler function, which the registration only *references*.
+     * This resolves that reference to the handler's `FunctionLike` node, purely
+     * structurally, in three shapes:
+     *
+     *  1. INLINE — the node is (or is inside) a call whose arguments include an
+     *     arrow/function expression: `app.post('/x', async (c) => { … })`. The
+     *     inline function IS the handler.
+     *  2. OBJECT-LITERAL HANDLER PROPERTY — the node is (or is inside) an object
+     *     literal with a `handler`-like property whose value is either an inline
+     *     function or an identifier bound to a function:
+     *     `{ method, path, handler: healthCheckHandler }`. Resolve that value.
+     *  3. IDENTIFIER ARGUMENT — the node is (or is inside) a call whose 2nd+
+     *     argument is an identifier bound to a function:
+     *     `app.get('/x', healthCheckHandler)`. Resolve that identifier.
+     *
+     * No framework name, method name, or property name beyond the generic
+     * `handler`-shaped key is hardcoded — the match is on node SHAPE (call with a
+     * function-typed arg / object literal with a function-valued property), which
+     * is what "route registration" structurally is across Express, Fastify, Hono,
+     * Koa, a hand-rolled registry array, etc. Returns undefined when the locator
+     * is not a registration shape, so every existing non-registration path is
+     * untouched.
+     */
+    private resolveRegisteredHandler;
+    /**
+     * Request-path gate for handler-following: return the handler function ONLY
+     * when the located node is ITSELF (after expression-unwrap) the registration
+     * — a call whose arguments include a handler function, or a route-registry
+     * object literal with a handler property. Unlike `resolveRegisteredHandler`,
+     * this does NOT walk up to an ancestor call, so a consumer's inner
+     * `JSON.stringify(payload)` (nested inside a `fetch(...)` that may carry other
+     * callbacks) is never mistaken for a registration and the existing consumer
+     * request paths stay exactly as they were.
+     */
+    private registrationHandlerAt;
+    /**
+     * The handler function referenced by a route-registration call: the first
+     * argument that is an inline function, or an identifier bound to a function
+     * (typically the 2nd+ arg — the path literal is not function-valued, so it is
+     * skipped naturally). No callee-name check: a call whose argument resolves to
+     * a function is structurally a registration regardless of the framework.
+     */
+    private handlerFromRegistrationCall;
+    /**
+     * The handler function carried by a route-registry object literal. Matches a
+     * property whose name is `handler`-shaped (case-insensitive `handler`) and
+     * whose value is an inline function or an identifier bound to a function.
+     */
+    private handlerFromObjectLiteral;
+    /**
+     * Resolve a node to a handler `FunctionLike`: an inline arrow/function
+     * expression is returned directly; an identifier is followed to its binding
+     * declaration (via the compiler's definition nodes) and returned when that
+     * declaration is — or initializes to — a function. Anything else (a path
+     * literal, an object, a non-function binding) yields undefined.
+     */
+    private asHandlerFunction;
+    /**
+     * Extract a `FunctionLike` from a declaration node the compiler resolved an
+     * identifier to: a function declaration is itself the function; a variable
+     * declaration / binding whose initializer is an inline function yields that
+     * function (`const h = async () => { … }`). Import/re-export shims are walked
+     * by ts-morph's `getDefinitionNodes`, so no manual import chasing is needed.
+     */
+    private functionFromDeclaration;
+    /**
+     * Scan a handler function body for the FIRST request-body read that carries a
+     * type, and return that type's structural text — or null when the body holds
+     * no typed request read.
+     *
+     * "Typed request read" is matched on SHAPE, never on a callee/method name:
+     *
+     *  A. a CALL that carries an explicit type argument — `c.req.json<T>()`,
+     *     `parseBody<T>(req)`; the first type argument is `T`; or
+     *  B. an expression with an explicit type annotation or cast in its immediate
+     *     binding context — `const b: T = …`, `req.body as T`.
+     *
+     * The body is walked in source order (`forEachDescendant` is a pre-order
+     * traversal), so the FIRST such read wins, mirroring "the request type lives
+     * at the first body read" without assuming which framework produced it.
+     * Returns null (not a spurious type) for a genuinely payload-less handler.
+     */
+    private inferRequestReadFromHandler;
+    /**
+     * Resolve a type-annotation/type-argument node to fully-structural text,
+     * dropping any `Promise<…>` wrapper (`c.req.json<T>()` returns `Promise<T>`,
+     * but the annotation node is `T` directly; the guard is harmless either way).
+     * Returns null when the node resolves to a useless/library type that carries
+     * no member shape, so the caller keeps scanning rather than locking onto
+     * `any`/`unknown`.
+     */
+    private structuralTextFromTypeNode;
+    /**
+     * Same reduction as `structuralTextFromTypeNode`, but starting from a resolved
+     * `Type` rather than a syntax node. `at` only supplies the scope the type is
+     * rendered in.
+     */
+    private structuralTextFromType;
+    /**
+     * The route registration a request's locator points AT, or undefined when it
+     * points at anything else.
+     *
+     * Deliberately strict: the located node must itself be the registration (a
+     * call registering a handler, or a route-registry object literal), never an
+     * ancestor of it, so an expression inside a handler is not mistaken for the
+     * route it belongs to. A locator that resolves nothing falls back to the
+     * registration on the request's line.
+     */
+    private routeRegistrationForRequest;
+    /**
+     * Anchor (b) on the response side: the success-status contract declared in the
+     * registration's schema, as an `InferredType` ready to return. Null when the
+     * registration declares no resolvable response schema, so the caller falls
+     * back to following the handler's return.
+     */
+    private declaredResponseInferredType;
+    /**
+     * The request contract of a route registration, in anchor order: the
+     * handler's parameter annotation (a), the registration's declared schema (b),
+     * then the first typed request read in the handler body (the pre-existing
+     * behaviour). The first anchor yielding a non-useless type wins; null means
+     * the route declares its request nowhere we can read.
+     */
+    private requestContractFromRegistration;
+    /**
+     * Anchor (a): the request contract declared on the handler's own signature.
+     *
+     * A typed request parameter (`request: CreateWidgetRequest` where that alias
+     * resolves to a request type parameterised with the body shape) exposes the
+     * contract as the `body` member of the parameter's type. Parameters are
+     * scanned in order and the first one carrying a non-useless `body` member
+     * wins; a reply/response parameter has no `body` member, and an unparameterised
+     * request type resolves `body` to `unknown`/`any`, which the useless-type
+     * guard rejects. So a handler that declares nothing yields null and the next
+     * anchor runs.
+     */
+    private requestBodyFromHandlerParams;
+    /**
+     * Anchor (b): the contract declared in the route's validation schema.
+     *
+     * `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).
+     */
+    private routeSchemaContractText;
+    /**
+     * The `schema` object literal carried by a route registration: scan the
+     * registration call's arguments (or the registry object literal itself) for a
+     * `schema` property whose value is an object literal.
+     */
+    private routeSchemaObject;
+    /**
+     * The success entry of a status-keyed response map (`{ 200: …, 4xx: … }`):
+     * exact `200` when present, else the lowest 2xx key. Returns undefined when
+     * the value is not a status-keyed map, so the caller reads it as the schema
+     * itself.
+     */
+    private successStatusEntry;
+    /**
+     * The payload type a schema entry declares.
+     *
+     * 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.
+     */
+    private schemaOutputTypeText;
+    /**
+     * Follow a schema REFERENCE call (`ref('CreateWidget')`) to the schema value
+     * it names.
+     *
+     * The ref function is produced by a registry-building call — `const { $ref } =
+     * build({ CreateWidget, Widget })` — so the registry is that call's first
+     * argument, and the referenced key is a property of it. Resolve the callee to
+     * its declaration, walk to the variable declaration it is bound in, and read
+     * the key off the builder argument's type. Returns undefined for anything
+     * that is not this shape.
+     */
+    private registrySchemaType;
+    /**
+     * 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
+     * unavailable (an uninstalled dependency resolves the schema to `any`), which
+     * must abstain rather than publish `any` as a contract.
+     */
+    private schemaOutputType;
+    /**
+     * Find a node by matching expression text near a target line.
+     *
+     * Strategy:
+     * 1. Get all descendant nodes within [lineNumber - searchRadius, lineNumber + searchRadius]
+     * 2. Normalize whitespace for comparison
+     * 3. Try exact match first (after normalization), prefer closest to target line
+     * 4. Fall back to substring match (LLM text in node text, or vice versa)
+     * 5. Return smallest matching node closest to target line
+     */
+    private findNodeByText;
+    /**
+     * Find a CallExpression by matching expression text near a target line.
+     */
+    private findCallExpressionByText;
+    /**
+     * Shared text-matching logic for node resolution.
+     * Normalizes whitespace once per candidate, then tries exact match,
+     * then substring match (preferring containing matches).
+     */
+    private matchByText;
+    /**
+     * Pick the best match from a set of candidate nodes:
+     * smallest range, then closest to target line.
+     */
+    private pickBestMatch;
+    /**
+     * Normalize whitespace for text comparison:
+     * collapse runs of whitespace into single spaces, trim.
+     *
+     * Also strips trailing commas before `}` `)` `]`: multi-line source
+     * literals carry them but the LLM's single-line locator print does not,
+     * and that one comma used to defeat exact AND containment matching for
+     * the payload and every enclosing node (#335). Applied symmetrically to
+     * node text and target, so both sides compare equal.
+     *
+     * Also strips the space left AFTER `(` `[` `{` by the collapse: a
+     * multi-line call whose arguments start on the next line normalizes to
+     * `f( x)` while the LLM's compact print is `f(x)`, and that one space
+     * defeated exact matching for the call and every enclosing node — the
+     * opening-delimiter mirror of the #335 trailing comma (#336). Symmetric
+     * for the same reason.
+     */
+    private normalizeWhitespace;
+    /**
+     * Format a human-readable location string for error messages.
+     */
+    private formatRequestLocation;
+    private findContainingFunctionBySpan;
+    private findNodeAtSpan;
+    private findCallExpressionAtSpan;
+    private unwrapPromise;
+    /**
+     * Unwrap a single `Promise<...>` / `PromiseLike<...>` type string, only when
+     * the inner text is bracket-balanced (so `Promise<A> | B` is left alone for
+     * the caller's union handling rather than mangled).
+     */
+    private unwrapPromiseText;
+    /**
+     * Split a type string on `|` at bracket depth 0. `=>` is not treated as a
+     * closing bracket.
+     */
+    private splitTopLevelUnion;
+    private isBracketBalanced;
+    private getNodeLocation;
+    private createInferredType;
+    private generateAlias;
+    private inferKindSuffix;
+    private log;
+    private logError;
+}