vouchington-tooling 0.32.0 → 0.34.0

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

@@ -4,6 +4,9 @@ import { enclosingFunction } from './protocol-marker-analysis.mjs';
 import { expressionReceiver } from './protocol-write-receiver.mjs';
 import { hasBindingWrite } from './registered-route-binding-writes.mjs';
 import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { contextResponseMethod, methodAccess } from './protocol-http-method-access.mjs';
+import { reflectHttpResponseMethod } from './protocol-http-reflect.mjs';
+export { contextResponseMethod } from './protocol-http-method-access.mjs';
 /** A helper parameter is a response context only when every executable caller passes one. */
 export function httpHandlerContext(fn, checker, active = new Set()) {
     if (active.has(fn))
@@ -31,35 +34,6 @@ export function httpHandlerContext(fn, checker, active = new Set()) {
     const result = valid ? context : undefined;
     return result;
 }
-/** Literal bracket access is equivalent to property access for response methods. */
-export function contextResponseMethod(expression, context, checker, allowMutable = false) {
-    const access = methodAccess(expression);
-    if (!access)
-        return undefined;
-    const receiver = expressionReceiver(access.receiver, checker) ??
-        bracketResponseReceiver(access.receiver, checker);
-    if (receiver?.root !== context || (receiver.mutableAlias && !allowMutable))
-        return undefined;
-    if (receiver.path.length === 0)
-        return access.name;
-    if (receiver.path.length === 1 && receiver.path[0] === 'response')
-        return `response.${access.name}`;
-    return undefined;
-}
-function methodAccess(expression) {
-    if (ts.isPropertyAccessExpression(expression))
-        return { receiver: expression.expression, name: expression.name.text };
-    if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression))
-        return { receiver: expression.expression, name: expression.argumentExpression.text };
-    return undefined;
-}
-function bracketResponseReceiver(expression, checker) {
-    const access = methodAccess(expression);
-    if (!access || access.name !== 'response')
-        return undefined;
-    const receiver = expressionReceiver(access.receiver, checker);
-    return receiver && { ...receiver, path: [...receiver.path, 'response'] };
-}
 /** Follow only caller contexts already admitted by the actual-argument proof. */
 export function httpContextScopes(fn, checker) {
     const scopes = new Map();
@@ -84,6 +58,9 @@ export function httpContextScopes(fn, checker) {
 }
 /** Indirect methods cannot prove the declared status or body, including borrowed this receivers. */
 export function indirectHttpResponseMethod(call, context, checker) {
+    const reflected = reflectHttpResponseMethod(call, context, checker);
+    if (reflected)
+        return reflected;
     const outer = methodAccess(call.expression);
     if (!outer || !['call', 'apply', 'bind'].includes(outer.name))
         return undefined;

package/dist/api-contract-discovery/protocol-http-method-access.d.mts

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Literal bracket access is equivalent to property access for response methods. */
+export declare function contextResponseMethod(expression: ts.Expression, context: ts.Symbol, checker: ts.TypeChecker, allowMutable?: boolean): string | undefined;
+export declare function methodAccess(expression: ts.Expression): {
+    receiver: ts.LeftHandSideExpression;
+    name: string;
+} | undefined;
+/** Uses the existing canonical receiver plus literal response-property access. */
+export declare function httpContextReceiver(expression: ts.Expression, checker: ts.TypeChecker): import("./protocol-write-receiver.mts").WriteReceiver | undefined;

package/dist/api-contract-discovery/protocol-http-method-access.mjs

@@ -0,0 +1,34 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+/** Literal bracket access is equivalent to property access for response methods. */
+export function contextResponseMethod(expression, context, checker, allowMutable = false) {
+    const access = methodAccess(expression);
+    if (!access)
+        return undefined;
+    const receiver = httpContextReceiver(access.receiver, checker);
+    if (receiver?.root !== context || (receiver.mutableAlias && !allowMutable))
+        return undefined;
+    if (receiver.path.length === 0)
+        return access.name;
+    if (receiver.path.length === 1 && receiver.path[0] === 'response')
+        return `response.${access.name}`;
+    return undefined;
+}
+export function methodAccess(expression) {
+    if (ts.isPropertyAccessExpression(expression))
+        return { receiver: expression.expression, name: expression.name.text };
+    if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression))
+        return { receiver: expression.expression, name: expression.argumentExpression.text };
+    return undefined;
+}
+/** Uses the existing canonical receiver plus literal response-property access. */
+export function httpContextReceiver(expression, checker) {
+    const receiver = expressionReceiver(expression, checker);
+    if (receiver)
+        return receiver;
+    const access = methodAccess(expression);
+    if (!access || access.name !== 'response')
+        return undefined;
+    const parent = expressionReceiver(access.receiver, checker);
+    return parent && { ...parent, path: [...parent.path, 'response'] };
+}

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

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Both the actual invoked value and signature must belong to the compiler library. */
+export declare function standardReflectApply(call: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/** Reflected context emissions cannot prove the marked status or response body. */
+export declare function reflectHttpResponseMethod(call: ts.CallExpression, context: ts.Symbol, checker: ts.TypeChecker): string | undefined;

package/dist/api-contract-discovery/protocol-http-reflect.mjs

@@ -0,0 +1,45 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { standardCompilerDeclaration } from './protocol-platform-callbacks.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { contextResponseMethod, httpContextReceiver, methodAccess, } from './protocol-http-method-access.mjs';
+/** Both the actual invoked value and signature must belong to the compiler library. */
+export function standardReflectApply(call, checker) {
+    const access = methodAccess(unwrapExpression(call.expression));
+    const receiver = expressionReceiver(access?.receiver ?? call.expression, checker);
+    if (!receiver)
+        return false;
+    const path = [...receiver.path, ...(access ? [access.name] : [])];
+    if (path.join('.') !== 'apply')
+        return false;
+    if (!receiver.root.declarations?.every((value) => standardCompilerDeclaration(value, checker)))
+        return false;
+    const declaration = checker.getResolvedSignature(call)?.declaration;
+    if (!declaration || !ts.isFunctionDeclaration(declaration) || declaration.name?.text !== 'apply')
+        return false;
+    const namespace = declaration.parent.parent;
+    return (ts.isModuleDeclaration(namespace) &&
+        namespace.name.text === 'Reflect' &&
+        standardCompilerDeclaration(declaration, checker));
+}
+/** Reflected context emissions cannot prove the marked status or response body. */
+export function reflectHttpResponseMethod(call, context, checker) {
+    if (!standardReflectApply(call, checker))
+        return undefined;
+    const target = call.arguments[0];
+    const direct = target && contextResponseMethod(target, context, checker, true);
+    if (direct)
+        return direct;
+    const method = target && expressionReceiver(target, checker);
+    if (method?.root === context)
+        return method.path[0] === 'response' ? method.path.slice(0, 2).join('.') : method.path[0];
+    const receiver = call.arguments[1] && httpContextReceiver(call.arguments[1], checker);
+    const name = (target && methodAccess(target)?.name) ?? method?.path.at(-1);
+    if (receiver?.root !== context || !name)
+        return undefined;
+    return receiver.path.length === 0
+        ? name
+        : receiver.path.length === 1 && receiver.path[0] === 'response'
+            ? `response.${name}`
+            : undefined;
+}

package/dist/api-contract-discovery/protocol-http-response-mutations.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Branded metadata requires the dispatched response's body and status to remain intact. */
+export declare function mutatedHttpResponse(node: ts.Node, response: ts.Symbol, checker: ts.TypeChecker): boolean;

package/dist/api-contract-discovery/protocol-http-response-mutations.mjs

@@ -0,0 +1,31 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { contextResponseMethod } from './protocol-http-context.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+/** Branded metadata requires the dispatched response's body and status to remain intact. */
+export function mutatedHttpResponse(node, response, checker) {
+    const target = mutationTarget(node);
+    if (!target)
+        return false;
+    const receiver = expressionReceiver(target, checker);
+    const field = receiver?.root === response
+        ? receiver.path[0]
+        : contextResponseMethod(unwrapExpression(target), response, checker, true);
+    return ((field === 'body' || field === 'status') &&
+        (executableProtocolPath(node, checker) || opaqueProtocolCallbackPath(node, checker)));
+}
+function mutationTarget(node) {
+    if (ts.isBinaryExpression(node) &&
+        node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+        node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+        return node.left;
+    if (ts.isDeleteExpression(node))
+        return node.expression;
+    if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+        (node.operator === ts.SyntaxKind.PlusPlusToken ||
+            node.operator === ts.SyntaxKind.MinusMinusToken))
+        return node.operand;
+    return undefined;
+}

package/dist/api-contract-discovery/protocol-platform-callbacks.d.mts

@@ -1,5 +1,7 @@
 import ts from '../contract-schema/typescript-api.mts';
 /** Records the actual caller compiler's library identities, including another installation. */
 export declare function registerPlatformCompilerLibraries(program: ts.Program): void;
+/** Shares actual compiler-library identity with other standard API guards. */
+export declare function standardCompilerDeclaration(declaration: ts.Declaration, checker: ts.TypeChecker): boolean;
 /** Recognizes only callback APIs supplied by the compiler's standard libraries or Node typings. */
 export declare function platformCallbackArgument(node: ts.CallExpression | ts.NewExpression, checker: ts.TypeChecker): ts.Expression | undefined;

package/dist/api-contract-discovery/protocol-platform-callbacks.mjs

@@ -27,6 +27,10 @@ function standardDeclaration(declaration, timer, checker) {
     return (timer &&
         /\/node_modules\/@types\/node\/(?:web-globals\/)?timers\.d\.ts$/.test(file.replaceAll('\\', '/')));
 }
+/** Shares actual compiler-library identity with other standard API guards. */
+export function standardCompilerDeclaration(declaration, checker) {
+    return standardDeclaration(declaration, false, checker);
+}
 function platformSymbol(expression, checker, seen = new Set()) {
     const value = unwrapExpression(expression);
     if (!ts.isIdentifier(value))

package/dist/api-contract-discovery/protocol-sse-raw-writes.mjs

@@ -6,7 +6,8 @@ import { enclosingRouteBinding, visit, } from './response-contract-route-analysi
 import { expressionReceiver, sameWriteReceiver, } from './protocol-write-receiver.mjs';
 import { sseWriteInvocation } from './protocol-sse-write-access.mjs';
 import { isSourceLevelMutation, mutationAffectsSelectedStream, sseWriteMutation, } from './protocol-sse-write-mutations.mjs';
-import { actualReceivers, helperBindings, routeKey } from './protocol-sse-write-helpers.mjs';
+import { actualReceivers, helperBindings, opaqueCallReceivesSelectedStream, routeKey, } from './protocol-sse-write-helpers.mjs';
+import { writeAccess } from './protocol-sse-write-resolution.mjs';
 /** Reports unmarked writes on executable or opaque escaping paths to a selected frame's stream. */
 export function rejectRawSseWrites(files, checker, bindings, framedWrites, routes, reject) {
     const calls = [];
@@ -30,8 +31,14 @@ export function rejectRawSseWrites(files, checker, bindings, framedWrites, route
                     if (mutationNode.getSourceFile() === source && isSourceLevelMutation(mutationNode))
                         return true;
                     const candidate = enclosingRouteBinding(mutationNode, checker, bindings, false);
-                    return !!candidate && routeKey(candidate) === routeKey(binding);
-                }, (expression) => {
+                    if (candidate && routeKey(candidate) === routeKey(binding))
+                        return true;
+                    if (!candidate &&
+                        mutationNode.getSourceFile() === source &&
+                        opaqueProtocolCallbackPath(mutationNode, checker))
+                        return true;
+                    return helperBindings(mutationNode, calls, checker, bindings).some((helper) => routeKey(helper) === routeKey(binding));
+                }, (mutationNode) => helperBindings(mutationNode, calls, checker, bindings).length > 0, (expression) => {
                     const receiver = expressionReceiver(expression, checker);
                     return receiver && actualReceivers(receiver, binding, calls, checker, bindings);
                 }, (receiver) => actualReceivers(receiver, binding, calls, checker, bindings)))
@@ -39,7 +46,7 @@ export function rejectRawSseWrites(files, checker, bindings, framedWrites, route
             continue;
         }
         const access = sseWriteInvocation(node, checker);
-        if (!access || !access.rawBytes || !potentiallyExecuted(node))
+        if (!potentiallyExecuted(node))
             continue;
         const proven = executableProtocolPath(node, checker) || opaqueProtocolCallbackPath(node, checker);
         const helpers = helperBindings(node, calls, checker, bindings);
@@ -51,17 +58,39 @@ export function rejectRawSseWrites(files, checker, bindings, framedWrites, route
             const route = routes.get(routeKey(candidate));
             if (!route)
                 continue;
+            const receiver = access?.receiver && expressionReceiver(access.receiver, checker);
+            const actual = receiver ? actualReceivers(receiver, candidate, calls, checker, bindings) : [];
+            const framed = route.receivers.flatMap((value) => actualReceivers(value, candidate, calls, checker, bindings));
+            const bound = writeAccess(node.expression);
+            const boundReceiver = bound?.method === 'bind' && expressionReceiver(bound.receiver, checker);
+            const boundActual = boundReceiver
+                ? actualReceivers(boundReceiver, candidate, calls, checker, bindings)
+                : [];
+            const accessTargetsSelected = (access?.method === 'write' || access?.method === 'end') &&
+                actual.some((value) => value !== undefined &&
+                    framed.some((frame) => frame !== undefined && sameWriteReceiver(frame, value)));
+            const bindsSelectedMember = bound?.method === 'bind' &&
+                boundActual.some((value) => value !== undefined &&
+                    framed.some((frame) => frame !== undefined &&
+                        frame.root === value.root &&
+                        value.path.length > frame.path.length &&
+                        value.path.slice(0, frame.path.length).join('.') === frame.path.join('.')));
+            if (!accessTargetsSelected &&
+                !bindsSelectedMember &&
+                opaqueCallReceivesSelectedStream(node, route.receivers, candidate, calls, checker, bindings)) {
+                reject(node, candidate, route.keys);
+                continue;
+            }
+            if (!access || !access.rawBytes)
+                continue;
             if (!access.receiver) {
                 reject(node, candidate, route.keys);
                 continue;
             }
-            const receiver = expressionReceiver(access.receiver, checker);
             if (!receiver) {
                 reject(node, candidate, route.keys);
                 continue;
             }
-            const actual = actualReceivers(receiver, candidate, calls, checker, bindings);
-            const framed = route.receivers.flatMap((value) => actualReceivers(value, candidate, calls, checker, bindings));
             if (actual.some((value) => value === undefined ||
                 framed.some((frame) => frame === undefined || sameWriteReceiver(frame, value))))
                 reject(node, candidate, route.keys);

package/dist/api-contract-discovery/protocol-sse-write-helpers.d.mts

@@ -2,5 +2,6 @@ import ts from '../contract-schema/typescript-api.mts';
 import { type HandlerBindings, type RouteBinding } from './response-contract-route-analysis.mts';
 import { type WriteReceiver } from './protocol-write-receiver.mts';
 export declare function routeKey(binding: RouteBinding): string;
+export declare function opaqueCallReceivesSelectedStream(call: ts.CallExpression, selectedReceivers: readonly WriteReceiver[], binding: RouteBinding, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings): boolean;
 export declare function helperBindings(node: ts.Node, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings): RouteBinding[];
 export declare function actualReceivers(receiver: WriteReceiver, binding: RouteBinding, calls: readonly ts.CallExpression[], checker: ts.TypeChecker, bindings: HandlerBindings, active?: Set<ts.Symbol>): (WriteReceiver | undefined)[];

package/dist/api-contract-discovery/protocol-sse-write-helpers.mjs

@@ -1,10 +1,11 @@
 import ts from '../contract-schema/typescript-api.mjs';
 import { hasBindingWrite } from './registered-route-binding-writes.mjs';
+import { createProtocolCallbackValueResolver } from './protocol-callback-values.mjs';
 import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 import { executableProtocolPath } from './protocol-execution-path.mjs';
 import { enclosingRouteBinding, } from './response-contract-route-analysis.mjs';
-import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { expressionReceiver, sameWriteReceiver, } from './protocol-write-receiver.mjs';
 export function routeKey(binding) {
     return `${binding.method}:${binding.routeTemplate}`;
 }
@@ -22,13 +23,29 @@ function implementationDeclaration(declaration, checker) {
     }
     return undefined;
 }
+function implementationCall(call, checker) {
+    return (implementationDeclaration(checker.getResolvedSignature(call)?.declaration, checker) ??
+        createProtocolCallbackValueResolver(checker).resolve(call.expression, new Map())?.node);
+}
+export function opaqueCallReceivesSelectedStream(call, selectedReceivers, binding, calls, checker, bindings) {
+    const implementation = implementationCall(call, checker);
+    if (implementation && ts.isFunctionLike(implementation) && 'body' in implementation)
+        return false;
+    const framed = selectedReceivers.flatMap((receiver) => actualReceivers(receiver, binding, calls, checker, bindings));
+    return call.arguments.some((argument) => {
+        const receiver = expressionReceiver(argument, checker);
+        if (!receiver)
+            return false;
+        return actualReceivers(receiver, binding, calls, checker, bindings).some((value) => value === undefined ||
+            framed.some((frame) => frame === undefined || sameWriteReceiver(frame, value)));
+    });
+}
 export function helperBindings(node, calls, checker, bindings) {
     const fn = enclosingFunction(node);
     if (!fn || fn.asteriskToken)
         return [];
     return calls.flatMap((call) => {
-        if (implementationDeclaration(checker.getResolvedSignature(call)?.declaration, checker) !== fn ||
-            !executableProtocolPath(call, checker))
+        if (implementationCall(call, checker) !== fn || !executableProtocolPath(call, checker))
             return [];
         const binding = enclosingRouteBinding(call, checker, bindings, false);
         return binding ? [binding] : [];
@@ -50,8 +67,7 @@ export function actualReceivers(receiver, binding, calls, checker, bindings, act
         return [undefined];
     const index = runtimeParameters(fn).indexOf(declaration);
     const actuals = calls.flatMap((call) => {
-        if (implementationDeclaration(checker.getResolvedSignature(call)?.declaration, checker) !== fn ||
-            !executableProtocolPath(call, checker))
+        if (implementationCall(call, checker) !== fn || !executableProtocolPath(call, checker))
             return [];
         const callBinding = enclosingRouteBinding(call, checker, bindings, false);
         if (!callBinding || routeKey(callBinding) !== routeKey(binding))

package/dist/api-contract-discovery/protocol-sse-write-mutations.d.mts

@@ -5,5 +5,5 @@ export type SseWriteMutation = {
     receiver: ts.Expression;
 };
 export declare function sseWriteMutation(node: ts.Node): SseWriteMutation | undefined;
-export declare function mutationAffectsSelectedStream(mutations: readonly SseWriteMutation[], frameReceivers: readonly WriteReceiver[], checker: ts.TypeChecker, isSameRoute: (node: ts.Node) => boolean, resolveActual: (expression: ts.Expression) => readonly (WriteReceiver | undefined)[] | undefined, resolveFrame: (receiver: WriteReceiver) => readonly (WriteReceiver | undefined)[]): boolean;
+export declare function mutationAffectsSelectedStream(mutations: readonly SseWriteMutation[], frameReceivers: readonly WriteReceiver[], checker: ts.TypeChecker, isSameRoute: (node: ts.Node) => boolean, isInvokedHelper: (node: ts.Node) => boolean, resolveActual: (expression: ts.Expression) => readonly (WriteReceiver | undefined)[] | undefined, resolveFrame: (receiver: WriteReceiver) => readonly (WriteReceiver | undefined)[]): boolean;
 export declare function isSourceLevelMutation(node: ts.Node): boolean;

package/dist/api-contract-discovery/protocol-sse-write-mutations.mjs

@@ -1,5 +1,7 @@
 import ts from '../contract-schema/typescript-api.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
 import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
 import { sameWriteReceiver } from './protocol-write-receiver.mjs';
 import { writeAccess } from './protocol-sse-write-resolution.mjs';
 export function sseWriteMutation(node) {
@@ -18,10 +20,14 @@ export function sseWriteMutation(node) {
 function isAssignment(kind) {
     return kind >= ts.SyntaxKind.FirstAssignment && kind <= ts.SyntaxKind.LastAssignment;
 }
-export function mutationAffectsSelectedStream(mutations, frameReceivers, checker, isSameRoute, resolveActual, resolveFrame) {
+export function mutationAffectsSelectedStream(mutations, frameReceivers, checker, isSameRoute, isInvokedHelper, resolveActual, resolveFrame) {
     const framed = frameReceivers.flatMap(resolveFrame);
     return mutations.some(({ node, receiver }) => {
-        if ((!isSourceLevelMutation(node) && !executableProtocolPath(node, checker)) ||
+        if (!potentiallyExecuted(node) ||
+            (!isSourceLevelMutation(node) &&
+                !executableProtocolPath(node, checker) &&
+                !opaqueProtocolCallbackPath(node, checker) &&
+                !isInvokedHelper(node)) ||
             !isSameRoute(node))
             return false;
         const actual = resolveActual(receiver);

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[];