vouchington-tooling 0.33.0 → 0.34.0

package/README.md

@@ -8,11 +8,16 @@ GitHub Actions policy checks and compiler host freshness with bounded build sett
 [`config-inventory`](../../docs/config-inventory.md) collects environment, dynamic-configuration,
 and package-manager evidence using caller-owned file roles and policies.
 
+[`finite-enum-ripple`](../../docs/finite-enum-ripple.md) compares finite TypeScript declarations,
+route configuration, routed pages, and factory calls. Consumers supply every tracked-file role,
+declaration name, route label, factory pattern, and exception.
+
 ```bash
 npm install vouchington-tooling
 # optional, only if you import vouchington-tooling/sql-ast
 npm install @libpg-query/parser
-# optional, only if you import vouchington-tooling/contract-schema
+# optional, if you import vouchington-tooling/contract-schema, finite-enum-ripple,
+# or post-publication-inventory
 # (classic compiler API; typescript@7's package root is version-only)
 npm install @typescript/typescript6
 # optional, only if you use the Vitest reporter export
@@ -474,6 +479,138 @@ aliases; `options.onRouteError` enables lenient response and request extraction.
 does not cache programs or depend on the caller's repository layout. OpenAPI document assembly
 remains a separate `openapi-document` call.
 
+`options.onAmbiguousAttribution` optionally emits facts for response calls lexically inside handler
+functions registered to multiple routes, plus inline response calls within those handlers. Facts
+are delivered after discovery succeeds, ordered by normalized source location; each callback gets
+its own copy of the sorted route list. It recognizes direct property handlers on `const`
+object-literal receivers, shorthand properties, immutable aliases, and inline handlers. Mutable
+receivers whose properties may be reassigned, variable receivers without object-literal initializers,
+and non-identifier receiver expressions fail closed for attribution.
+Direct identifier assignment, identifier writes through array/object destructuring or loop targets,
+identifier updates, and dot-property assignment or updates make that binding ineligible for attribution.
+Computed receiver-property writes, `delete`, runtime reflection, and other indirect mutation are not
+analyzed. Named helper calls are not followed transitively: for example, an
+emission inside `emit(ctx)` is not attributed when a registered `shared(ctx)` handler calls
+`emit(ctx)`. The callback does not change the discovered contract result.
+
+Query contracts (`apiQuery`) carry requiredness. A top-level parameter descriptor type may include
+`required: true` (inline or through an intersection such as `{ readonly required: true }`); the
+extracted descriptor then has `required: true` and the OpenAPI parameter emits `required: true`,
+otherwise `required: false`. `required` must be the literal `true`; `false`, `boolean`, optional, or
+non-literal values fail as a malformed query parameter, as do `required` together with `default` and
+`required` on `csv-array` `items`.
+
+`discoverRequestValidationFacts({ program, sourceFiles, validators, factories, executedCallbacks })`
+reports, per registered route (`METHOD:/template`), the route `kind` and `source`, every configured
+validator call its handlers reach (`validatorSites`), every configured handler-factory call
+(`factorySites`), and the raw request carriers the handlers read (`carrierReads`). It reports
+facts only; which routes must validate and what counts as covered stay with the caller.
+
+```ts
+import { discoverRequestValidationFacts } from 'vouchington-tooling/api-contract-discovery'
+
+const facts = discoverRequestValidationFacts({
+  program,
+  sourceFiles,
+  validators: [
+    {
+      module: 'lib/validation.ts', // resolved declaration path suffix, or a package specifier
+      exportName: 'validateInput',
+      operationArgument: 1,
+      carriers: { kind: 'input-object', argument: 2 }, // or { kind: 'fixed', carriers, optionCarriers }
+    },
+  ],
+  factories: [
+    {
+      module: 'lib/factory.ts',
+      exportName: 'createThingHandler',
+      optionsArgument: 0,
+      operationProperty: 'operation',
+      carriers: ['path', 'body'],
+    },
+  ],
+  executedCallbacks: [
+    {
+      module: 'lib/admit.ts',
+      exportName: 'admitWork',
+      argument: 0,
+      properties: ['beforeCapacity'],
+    },
+  ],
+})
+```
+
+A call matches only when its callee resolves, through aliases, re-exports and path mappings, to the
+configured export of a declaration file matching `module` (`.d.ts`, `.d.mts` and `.d.cts` suffixes
+are ignored when comparing, and the configured `module` may be written with or without a `.ts`,
+`.mts`, `.cts`, `.js`, `.mjs` or `.cjs` extension, so `lib/validation.js` matches `lib/validation.ts`
+and `lib/validation.d.ts`); import specifier text and same-named local functions never match.
+Operation keys resolve through literals, `const`s (including imported ones), `as const`,
+`satisfies`, helper parameters bound to static arguments, and, for factories, the option property
+including spread `const` objects; anything else, including a name with no symbol, gives
+`operation: null` with `unresolvedReason`. Each validated carrier reports `origins`, the request
+carriers (`path`, `query`, `body`, `header`) its value derives from, traced through calls, followed
+helper returns, branches, logical operands, spreads and earlier assignments; `unresolved` is set
+when part of the value depends on an unbound parameter. An unconditional reassignment of the
+identifier itself earlier in the same function body (not inside a branch, loop or `try`) replaces
+the earlier origins, conditional reassignments merge, and property writes such as `x.limit = n`
+always add; an assignment on a statically dead path (`if (false)`) is ignored. A destructured
+local traces only the property or element it binds (`const { chosen } = pair`), resolved through
+object and array literals, `const`s and followed helper returns (also awaited), and falls back to the
+whole initializer when it cannot be selected (rest, computed key, spread, unknown source).
+A destructured handler context parameter (`({ query, params, request }) => ...`) binds each member
+to its carrier. A helper parameter that is reassigned is not trusted as the bound operation key:
+only a lone unconditional reassignment is used, anything else gives `operation: null`.
+Generator functions are not followed, because calling one does not run its body.
+Fixed-carrier validators report the carrier itself as their origin.
+
+An input-object validator's input is resolved through `const` objects and spreads with
+last-write-wins semantics, like the factory option resolver. When it cannot be fully resolved (a
+non-literal input, a spread of something that is not a resolvable `const` object, a cyclic spread,
+or a computed property name), `carriers` lists what was found and the site sets
+`unresolvedCarriers` to the reason, so a consumer must not treat `carriers` as complete. A `const`
+object (input or factory options) with a property write before the use (`o.p = x`, `o[k] = x`,
+`delete o.p`, `o.n++`, `Object.assign(o, ...)`) is unresolvable too, and a factory then reports
+`operation: null`.
+
+`conditional` is true under `if`/ternary branches, the right of `&&`/`||`/`??`, `switch` cases,
+loop bodies, `catch` and `finally`. Handlers are walked into function declarations and `const`
+function expressions in `sourceFiles`, and only through bindings that are never reassigned (`let`
+and reassigned bindings are not trusted as handlers). A callback passed to a followed helper is
+followed only when the helper runs it, and is conditional unless it is invoked directly from the
+helper's own body outside any condition. Known limit: the invocations of an inline callback are
+found only in the callback's own source file, so a callback passed to a helper declared in another
+file (`withTx(ctx, async () => { validateInput(...) })`) is not walked. Inline callback properties of an `executedCallbacks` host,
+written as identifiers or string literals, are walked as executed and take only the condition of
+the call to the configured host, never how its implementation invokes them. Configured validator
+and factory implementations are never entered, but their callee and arguments are still walked for
+nested validator sites and reads; only reads that build a validator's input are left out, including
+reads inside a followed helper that only prepares that input. Validators evaluated while a handler is
+built (registration time) are not sites: only the walk of the handler reports validators. A handler a
+helper returns under a runtime branch (`if (flag) return ctx => ...`) reports `conditional: true`. Factory
+sites are reported for factory calls whose returned handler is a registration-time value (a route
+registration argument, a module `const` used as one, or a helper-returned handler); a factory call
+inside a handler body, such as a discarded `createThingHandler(options);`, is not a factory site.
+A factory site is also found through a module `const` initialized by a factory call that a handler
+calls (`const handler = createThingHandler({...})`, then `handler(ctx)`). Like validator sites,
+`FactorySite.conditional` is true when the site is reached only under a condition, and a site
+reached both ways is reported unconditional. A template-literal operation key folds to a string
+when every substitution resolves (literals, `const`s, bound parameters); otherwise it is `null`.
+
+Pass the `program` you already built: the function uses it as given and never builds its own.
+Helpers are followed only within `sourceFiles`, so pass every file that declares a followed helper,
+not just the route files; a helper declared elsewhere is not entered, which silently yields empty
+`origins` rather than an error. An omitted optional or defaulted helper argument contributes no
+origin and is not `unresolved`; an omitted required argument is `unresolved`. Per-call caches make
+repeated helpers cheap, so a 700-route program completes in seconds once the program exists.
+
+Each `carrierReads` entry has `access`: `key` for a static key (`ctx.query.limit`, destructured
+names, a resolvable `ctx.query[name]`), `computed` for a non-static key (`ctx.query[name]`, a
+computed destructuring key; `key: null`), and `whole` for the carrier used as a value
+(`consume(ctx.query)`, `{ ...ctx.params }`, `return ctx.headers`, a rest element) or a body read
+such as `ctx.request.json()` (`key: null`). A `const` alias of a carrier is not itself a read; its
+uses are.
+
 Version one recognizes literal-key `apiResponse`, `apiNoContent`, `apiOpenApiRawResponse`,
 `apiRequest`, `apiRequestContract`, `apiNoRequestBody`, `apiQuery`, and `apiHeaders` markers inside
 `app.route(...).get/post/put/patch/delete(...)` handlers. It also inspects unmarked `ctx.json`,
@@ -579,6 +716,29 @@ the dedicated process group to exit after the direct child closes so descendants
 `isProcessGroupAlive` and `waitForProcessGroupExit` are also available when callers need the same
 process-group probe and bounded-drain semantics outside a browser session.
 
+### Contract schema type queries
+
+`getExportedTypeFacts` and `getCallRowTypeFacts` use an existing TypeScript `Program` from the
+`contract-schema` subpath. Every request must also pass `typescript`, the same TypeScript compiler
+API instance that created that `Program`. The source-file recognition check is a compatibility
+guard, and callers remain responsible for pairing the same compiler instance; the query uses the
+supplied API for compiler operations. Pass the exact `SourceFile.fileName`, an exported name or exact call
+expression text, and only the property names and exported comparison types the consumer needs.
+Facts include the displayed type, whether it is `any`, requested property displays, and requested
+assignability booleans. `defaultTypeParameterIndex` selects an exported generic default;
+direct defaults and direct references to preceding defaults are supported. Dependent composite
+defaults and uninstantiated generic type declarations used as assignability targets fail with an
+instruction to export and select a named instantiated type. Generic function values remain valid
+compiler-backed comparison targets. Default lookup uses an outer class, interface, or type-alias
+parameter list when present; otherwise it uses the first checker-visible call or construct
+signature, never a hidden implementation or a later overload.
+`rowSource: 'typeArgument'` selects a call's explicit type argument, while
+`rowSource: 'awaitedRows'` selects `Awaited<ReturnType>.rows[number]`.
+Call results are source ordered and include one-based line and column. An absent call returns an
+empty array so the consumer can enforce its own cardinality; a selected call missing its requested
+row type fails with a descriptive error. The package does not choose source files, expected
+properties, or contract policy.
+
 ## Workflow skills outside plugins
 
 The package ships a flat union of canonical workflow, testing, and database skills at
@@ -717,3 +877,23 @@ block, escaped and length-bounded like CI failures, and other entries are ignore
 TypeScript and route rows from Markdown. Callers configure declaration names and
 runbook headings, then compare the returned data using their own route policy.
 See the [API contract](docs/basic-auth-doc-sync.md).
+
+## Publication writer inventory facts
+
+`vouchington-tooling/post-publication-inventory` exports
+`analyzePostPublicationWriterSource(source, fileName, options)`. It returns five booleans for an
+approved capture-helper call, a capture opt-out, writes through a configured entity table,
+generated relation writes, and eligibility-table writes. Consumers supply every module, symbol,
+property, receiver, and table name through `PostPublicationWriterSourceOptions` and retain their
+inventory schema, tracked files, exceptions, and diagnostics.
+
+This preserves source-inventory heuristics, rather than proving runtime execution or SQL safety.
+Capture imports/calls are name-based and order-independent; relation-variable appends are
+order-sensitive. DML recognition examines literal/template text. Static table matching lowercases
+the extracted name; dynamic literal table matching preserves case. Malformed TypeScript uses the
+compiler's recovery tree. An argument-free append returns no relation fact.
+Pass TypeScript source (`.ts` or `.mts`); the parser uses TypeScript mode even if the file name ends
+in `.tsx`. Template expressions join their static fragments for DML matching, while DML prefixes
+for generated-table facts come from templates rather than ordinary quoted strings. Dynamic
+eligibility-table matching expects an unquoted literal immediately after the DML prefix and does
+not recognize `DELETE FROM ONLY`.

package/dist/api-contract-discovery/index.d.mts

@@ -27,5 +27,8 @@ export type { BackendRequestContract } from './request-contract-types.mts';
 export type { BackendQueryContract, BackendQueryContractRegistry } from './query-contract-types.mts';
 export type { HeaderContract, HeaderContractRegistry } from './header-contract-types.mts';
 export type { RegisteredRoute } from './registered-route-catalog.mts';
-export type { RouteDiscoveryError, DiscoverApiResponseContractsOptions, } from './response-contract-lenient.mts';
+export type { AmbiguousAttributionFact, RouteDiscoveryError, DiscoverApiResponseContractsOptions, } from './response-contract-lenient.mts';
 export type { DiscoverApiRequestContractsOptions } from './request-contract-lenient.mts';
+export { discoverRequestValidationFacts } from './request-validation-facts.mts';
+export type { RequestValidationFactsInput } from './request-validation-facts.mts';
+export type { Carrier, CarrierRead, ExecutedCallbackConfig, FactoryConfig, FactorySite, RouteValidationFacts, ValidatorConfig, ValidatorSite, ValidatorSiteCarrier, } from './request-validation-types.mts';

package/dist/api-contract-discovery/index.mjs

@@ -24,3 +24,4 @@ export { discoverApiQueryContracts } from './query-contract-registry.mjs';
 export { discoverApiHeaderContracts } from './header-contract-registry.mjs';
 export { discoverRegisteredRoutes, routeShape } from './registered-route-catalog.mjs';
 export { responseStatusCodesForContract } from './response-contract-status.mjs';
+export { discoverRequestValidationFacts } from './request-validation-facts.mjs';

package/dist/api-contract-discovery/protocol-analysis-cache.d.mts

@@ -0,0 +1,21 @@
+import ts from '../contract-schema/typescript-api.mts';
+export type Assignment = {
+    node: ts.BinaryExpression;
+    direct: boolean;
+    start: number;
+};
+/**
+ * Memoized protocol-proof results for one analysis run. Nodes are immutable, so every entry stays
+ * valid for the run; callers create one per run and drop it afterwards.
+ */
+export type ProtocolCache = {
+    /** Plain assignments per owning function (or source file), grouped by the symbol they write. */
+    assignments: Map<ts.Node, Map<ts.Symbol, Assignment[]>>;
+    /** Symbols written (assigned, updated, or looped over) anywhere in a source file. */
+    writtenSymbols: Map<ts.SourceFile, Set<ts.Symbol | undefined>>;
+    /** Whether a function is a supported protocol callback. */
+    supported: Map<ts.Node, boolean>;
+    /** Executable call expressions of a source file. */
+    calls: Map<ts.SourceFile, ts.CallExpression[]>;
+};
+export declare const createProtocolCache: () => ProtocolCache;

package/dist/api-contract-discovery/protocol-analysis-cache.mjs

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export const createProtocolCache = () => ({
+    assignments: new Map(),
+    writtenSymbols: new Map(),
+    supported: new Map(),
+    calls: new Map(),
+});

package/dist/api-contract-discovery/protocol-callback-invocation.d.mts

@@ -1,5 +1,6 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 type FunctionNode = ts.FunctionLikeDeclaration;
 /** Proves callback consumption through concrete helper bodies, without executing nested closures. */
-export declare function isSupportedProtocolCallback(fn: FunctionNode, checker: ts.TypeChecker): boolean;
+export declare function isSupportedProtocolCallback(fn: FunctionNode, checker: ts.TypeChecker, cache?: ProtocolCache): boolean;
 export {};

package/dist/api-contract-discovery/protocol-callback-invocation.mjs

@@ -7,8 +7,16 @@ import { callbackBindingReplaced, callbackOptionsEscape } from './protocol-callb
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 import { createProtocolCallbackValueResolver, isProtocolCallbackFunction as functionNode, protocolCallbackSourceCalls, protocolCallbackHasWrittenBindings, } from './protocol-callback-values.mjs';
 /** Proves callback consumption through concrete helper bodies, without executing nested closures. */
-export function isSupportedProtocolCallback(fn, checker) {
-    if (!fn.body || fn.asteriskToken || protocolCallbackHasWrittenBindings(fn, checker))
+export function isSupportedProtocolCallback(fn, checker, cache) {
+    const known = cache?.supported.get(fn);
+    if (known !== undefined)
+        return known;
+    const supported = proveProtocolCallback(fn, checker, cache);
+    cache?.supported.set(fn, supported);
+    return supported;
+}
+function proveProtocolCallback(fn, checker, cache) {
+    if (!fn.body || fn.asteriskToken || protocolCallbackHasWrittenBindings(fn, checker, cache))
         return false;
     const resolver = createProtocolCallbackValueResolver(checker);
     const { resolve, symbol } = resolver;
@@ -20,7 +28,7 @@ export function isSupportedProtocolCallback(fn, checker) {
             invalidated ||= callbackOptionsEscape(call, env, fn, resolver);
             return false;
         }
-        if (protocolCallbackHasWrittenBindings(callee.node, checker)) {
+        if (protocolCallbackHasWrittenBindings(callee.node, checker, cache)) {
             invalidated = true;
             return false;
         }
@@ -86,7 +94,7 @@ export function isSupportedProtocolCallback(fn, checker) {
     const call = argument.parent;
     if (!ts.isCallExpression(call) && !ts.isNewExpression(call)) {
         const owner = enclosingFunction(fn);
-        if (owner && isSupportedProtocolCallback(owner, checker))
+        if (owner && isSupportedProtocolCallback(owner, checker, cache))
             return body(owner.body, new Map(), new Set([owner]), false);
         return protocolCallbackSourceCalls(fn).some((candidate) => potentiallyExecuted(candidate) &&
             ((registeredHandler(candidate) &&

package/dist/api-contract-discovery/protocol-callback-values.d.mts

@@ -1,4 +1,5 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 type FunctionNode = ts.FunctionLikeDeclaration;
 export type CallbackValue = {
     node: ts.Node;
@@ -13,5 +14,5 @@ export declare function createProtocolCallbackValueResolver(checker: ts.TypeChec
     symbol: (node: ts.Node) => ts.Symbol | undefined;
     property: (value: CallbackValue | undefined, name: string, seen: Set<ts.Node>) => CallbackValue | undefined;
 };
-export declare function protocolCallbackHasWrittenBindings(fn: FunctionNode, checker: ts.TypeChecker): boolean;
+export declare function protocolCallbackHasWrittenBindings(fn: FunctionNode, checker: ts.TypeChecker, cache?: ProtocolCache): boolean;
 export {};

package/dist/api-contract-discovery/protocol-callback-values.mjs

@@ -108,7 +108,7 @@ export function createProtocolCallbackValueResolver(checker) {
     }
     return { resolve, symbol, property };
 }
-export function protocolCallbackHasWrittenBindings(fn, checker) {
-    return ((ts.isFunctionDeclaration(fn) && hasBindingWrite(fn, checker)) ||
-        runtimeParameters(fn).some((parameter) => hasBindingWrite(parameter, checker)));
+export function protocolCallbackHasWrittenBindings(fn, checker, cache) {
+    return ((ts.isFunctionDeclaration(fn) && hasBindingWrite(fn, checker, cache)) ||
+        runtimeParameters(fn).some((parameter) => hasBindingWrite(parameter, checker, cache)));
 }

package/dist/api-contract-discovery/protocol-execution-path.d.mts

@@ -1,3 +1,4 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 /** Proves execution up to an optional handler whose registered binding is already established. */
-export declare function executableProtocolPath(node: ts.Node, checker: ts.TypeChecker, boundHandler?: ts.Node): boolean;
+export declare function executableProtocolPath(node: ts.Node, checker: ts.TypeChecker, boundHandler?: ts.Node, cache?: ProtocolCache): boolean;

package/dist/api-contract-discovery/protocol-execution-path.mjs

@@ -3,12 +3,12 @@ import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs'
 import { potentiallyExecuted } from './protocol-executable-path.mjs';
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 /** Proves execution up to an optional handler whose registered binding is already established. */
-export function executableProtocolPath(node, checker, boundHandler) {
+export function executableProtocolPath(node, checker, boundHandler, cache) {
     if (!potentiallyExecuted(node))
         return false;
     let fn = enclosingFunction(node);
     while (fn && fn !== boundHandler) {
-        if (!potentiallyExecuted(fn) || !isSupportedProtocolCallback(fn, checker))
+        if (!potentiallyExecuted(fn) || !isSupportedProtocolCallback(fn, checker, cache))
             return false;
         fn = enclosingFunction(fn);
     }

package/dist/api-contract-discovery/protocol-http-context-callers.d.mts

@@ -1,6 +1,7 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 /** Use the same actual invocation sites for context admission and caller emission coverage. */
-export declare function httpContextInvocations(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker): {
+export declare function httpContextInvocations(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker, cache?: ProtocolCache): {
     registered: boolean;
     callers: ts.CallExpression[];
 };

package/dist/api-contract-discovery/protocol-http-context-callers.mjs

@@ -5,15 +5,21 @@ import { registeredHandler } from './protocol-callback-registration.mjs';
 import { executableProtocolPath } from './protocol-execution-path.mjs';
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 /** Use the same actual invocation sites for context admission and caller emission coverage. */
-export function httpContextInvocations(fn, checker) {
+export function httpContextInvocations(fn, checker, cache) {
     const resolver = createProtocolCallbackValueResolver(checker);
-    const calls = [];
-    function visit(node) {
-        if (ts.isCallExpression(node) && executableProtocolPath(node, checker))
-            calls.push(node);
-        ts.forEachChild(node, visit);
+    const sourceFile = fn.getSourceFile();
+    let calls = cache?.calls.get(sourceFile);
+    if (!calls) {
+        const found = [];
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && executableProtocolPath(node, checker, undefined, cache))
+                found.push(node);
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        calls = found;
+        cache?.calls.set(sourceFile, calls);
     }
-    visit(fn.getSourceFile());
     const registered = calls.some((call) => registeredHandler(call) &&
         call.arguments.some((argument) => resolver.resolve(argument, new Map())?.node === fn));
     const callers = calls.filter((call) => {

package/dist/api-contract-discovery/query-contract-extraction.mjs

@@ -1,10 +1,24 @@
 import ts from '../contract-schema/typescript-api.mjs';
 import { contractError } from './response-contract-registration.mjs';
-import { optionalNumberLiteral, optionalStringLiteral, requiredBooleanLiteral, requiredNumberLiteral, requiredPropertyType, requiredStringLiteral, stringTuple, } from './query-contract-literals.mjs';
+import { optionalNumberLiteral, declaresProperty, optionalTrueLiteral, optionalStringLiteral, requiredBooleanLiteral, requiredNumberLiteral, requiredPropertyType, rejectUnresolvedType, requiredStringLiteral, stringTuple, } from './query-contract-literals.mjs';
 export function extractQueryParameterDescriptor(type, checker, sourceFile, node, parameterName) {
-    const fail = (detail) => {
+    rejectUnresolvedType(type, failure(sourceFile, node, parameterName));
+    const descriptor = extractDescriptorShape(type, checker, sourceFile, node, parameterName);
+    if (!optionalTrueLiteral(type, 'required', checker, failure(sourceFile, node, parameterName))) {
+        return descriptor;
+    }
+    if (declaresProperty(type, 'default')) {
+        failure(sourceFile, node, parameterName)('required cannot be combined with default');
+    }
+    return { ...descriptor, required: true };
+}
+function failure(sourceFile, node, parameterName) {
+    return (detail) => {
         throw contractError(sourceFile, node, `Malformed query parameter "${parameterName}": ${detail}`);
     };
+}
+function extractDescriptorShape(type, checker, sourceFile, node, parameterName) {
+    const fail = failure(sourceFile, node, parameterName);
     const kind = requiredStringLiteral(type, 'kind', checker, fail);
     const description = optionalStringLiteral(type, 'description', checker, node, fail);
     const options = description === undefined ? {} : { description };
@@ -55,7 +69,10 @@ export function extractQueryParameterDescriptor(type, checker, sourceFile, node,
         if (requiredBooleanLiteral(type, 'explode', checker, fail) !== false)
             fail('explode must be false');
         const itemType = requiredPropertyType(type, 'items', checker, fail);
-        const items = extractQueryParameterDescriptor(itemType, checker, sourceFile, node, `${parameterName}[]`);
+        rejectUnresolvedType(itemType, fail);
+        if (declaresProperty(itemType, 'required'))
+            fail('array items cannot be required');
+        const items = extractDescriptorShape(itemType, checker, sourceFile, node, `${parameterName}[]`);
         if (items.kind === 'string' || items.kind === 'enum') {
             return { kind, items, style: 'form', explode: false, ...options };
         }

package/dist/api-contract-discovery/query-contract-literals.d.mts

@@ -5,4 +5,9 @@ export declare function requiredNumberLiteral(type: ts.Type, name: string, check
 export declare function requiredBooleanLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): boolean;
 export declare function optionalStringLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, node: ts.Node, fail: (detail: string) => never): string | undefined;
 export declare function optionalNumberLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, node: ts.Node, fail: (detail: string) => never): number | undefined;
+export declare function optionalTrueLiteral(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): boolean;
+/** True when the type, or any member of a union type, declares the property. */
+export declare function declaresProperty(type: ts.Type, name: string): boolean;
 export declare function stringTuple(type: ts.Type, name: string, checker: ts.TypeChecker, fail: (detail: string) => never): readonly string[];
+/** Fails when the type, or any union/intersection constituent, is conditional or generic. */
+export declare function rejectUnresolvedType(type: ts.Type, fail: (detail: string) => never): void;

package/dist/api-contract-discovery/query-contract-literals.mjs

@@ -42,6 +42,25 @@ export function optionalNumberLiteral(type, name, checker, node, fail) {
     const value = checker.getTypeOfSymbolAtLocation(property, location);
     return value.isNumberLiteral() ? value.value : fail(`requires literal ${name}`);
 }
+export function optionalTrueLiteral(type, name, checker, fail) {
+    const property = type.getProperty(name);
+    if (!property) {
+        if (declaresProperty(type, name))
+            return fail(`${name} must be present on every union member`);
+        return false;
+    }
+    if (property.flags & ts.SymbolFlags.Optional)
+        return fail(`${name} must be literal when present`);
+    const value = requiredPropertyType(type, name, checker, fail);
+    const isTrue = value.flags & ts.TypeFlags.BooleanLiteral && checker.typeToString(value) === 'true';
+    return isTrue ? true : fail(`${name} must be the literal true`);
+}
+/** True when the type, or any member of a union type, declares the property. */
+export function declaresProperty(type, name) {
+    if (type.getProperty(name))
+        return true;
+    return type.isUnion() && type.types.some((member) => member.getProperty(name) !== undefined);
+}
 export function stringTuple(type, name, checker, fail) {
     const value = requiredPropertyType(type, name, checker, fail);
     if (!checker.isTupleType(value))
@@ -52,3 +71,13 @@ export function stringTuple(type, name, checker, fail) {
     }
     return values.map((item) => item.value);
 }
+/** Fails when the type, or any union/intersection constituent, is conditional or generic. */
+export function rejectUnresolvedType(type, fail) {
+    if (type.flags & (ts.TypeFlags.Conditional | ts.TypeFlags.Instantiable)) {
+        fail('descriptor must not contain unresolved conditional or generic types');
+    }
+    if (type.isUnionOrIntersection()) {
+        for (const member of type.types)
+            rejectUnresolvedType(member, fail);
+    }
+}

package/dist/api-contract-discovery/registered-route-binding-writes.d.mts

@@ -1,3 +1,4 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 /** Helper and factory parameter bindings must remain unchanged in their declaring source. */
-export declare function hasBindingWrite(declaration: ts.FunctionDeclaration | ts.ParameterDeclaration, checker: ts.TypeChecker): boolean;
+export declare function hasBindingWrite(declaration: ts.FunctionDeclaration | ts.ParameterDeclaration, checker: ts.TypeChecker, cache?: ProtocolCache): boolean;

package/dist/api-contract-discovery/registered-route-binding-writes.mjs

@@ -1,12 +1,7 @@
 import ts from '../contract-schema/typescript-api.mjs';
-/** Helper and factory parameter bindings must remain unchanged in their declaring source. */
-export function hasBindingWrite(declaration, checker) {
-    if (!declaration.name)
-        return false;
-    if (!ts.isIdentifier(declaration.name))
-        return true;
-    const binding = checker.getSymbolAtLocation(declaration.name);
-    let written = false;
+/** Every symbol assigned, updated, or looped over in the source file, found in one scan. */
+function writtenSymbols(sourceFile, checker) {
+    const written = new Set();
     const referencesBinding = (node) => {
         // Index expressions and computed property names read their keys, not write them.
         // inspect still visits these expressions separately to detect nested side-effect writes.
@@ -16,8 +11,8 @@ export function hasBindingWrite(declaration, checker) {
             referencesBinding(node.expression);
             return;
         }
-        if (ts.isIdentifier(node) && checker.getSymbolAtLocation(node) === binding)
-            written = true;
+        if (ts.isIdentifier(node))
+            written.add(checker.getSymbolAtLocation(node));
         node.forEachChild(referencesBinding);
     };
     const inspect = (node) => {
@@ -33,6 +28,20 @@ export function hasBindingWrite(declaration, checker) {
             referencesBinding(node.initializer);
         node.forEachChild(inspect);
     };
-    inspect(declaration.getSourceFile());
+    inspect(sourceFile);
     return written;
 }
+/** Helper and factory parameter bindings must remain unchanged in their declaring source. */
+export function hasBindingWrite(declaration, checker, cache) {
+    if (!declaration.name)
+        return false;
+    if (!ts.isIdentifier(declaration.name))
+        return true;
+    const sourceFile = declaration.getSourceFile();
+    let written = cache?.writtenSymbols.get(sourceFile);
+    if (!written) {
+        written = writtenSymbols(sourceFile, checker);
+        cache?.writtenSymbols.set(sourceFile, written);
+    }
+    return written.has(checker.getSymbolAtLocation(declaration.name));
+}

package/dist/api-contract-discovery/registered-route-handler-analysis.d.mts

@@ -2,5 +2,11 @@ import ts from '../contract-schema/typescript-api.mts';
 export type HandlerProof = {
     node: ts.FunctionLikeDeclaration;
     bindings: Map<ts.Symbol, ts.Expression>;
+    /** Set under `executableReturns` when a runtime branch selects the handler. */
+    conditional?: boolean;
 };
-export declare function handlerNodes(argument: ts.Expression, checker: ts.TypeChecker, parameterBindings?: Map<ts.Symbol, ts.Expression>, active?: Set<ts.Node>, staticProof?: boolean, proofs?: HandlerProof[]): ts.Node[];
+export declare function handlerNodes(argument: ts.Expression, checker: ts.TypeChecker, parameterBindings?: Map<ts.Symbol, ts.Expression>, active?: Set<ts.Node>, staticProof?: boolean, proofs?: HandlerProof[], 
+/** Ignore `let`, `var` and reassigned bindings; always on under `staticProof`. */
+stableBindings?: boolean, 
+/** Ignore returned values on statically dead paths, and mark runtime-branch ones conditional. */
+executableReturns?: boolean): ts.Node[];