vouchington-tooling 0.29.0 → 0.30.0

package/README.md

@@ -34,9 +34,6 @@ vouchington runner-port-policy
 vouchington runner-port-policy --file ./policy.json
 vouchington runner-port-policy --reserved 2200
 vouchington with-host-lock --name expensive-build --timeout-seconds 60 -- make build
-vouchington agent-harness-config dump
-vouchington agent-harness-config check --global
-vouchington agent-harness-config apply --global --repo /path/to/checkout
 vouchington gha-runtime-audit --pr-workflow CI --push-workflow '/^Main CI \\(.+\\)$/'
 vouchington require-up-to-date --remote origin --branch main
 vouchington gitleaks-directory-scan --config .gitleaks.toml
@@ -199,11 +196,6 @@ import {
 import { initSqlAst, extractCreateTableMetadata } from 'vouchington-tooling/sql-ast'
 import { splitSqlStatements, stripSqlComments } from 'vouchington-tooling/sql-scanner'
 import { auditCiJobRuntime } from 'vouchington-tooling/gha-runtime-audit'
-import {
-  applyHarnessConfig,
-  checkHarnessConfig,
-  dumpHarnessPolicy,
-} from 'vouchington-tooling/agent-harness-config'
 import {
   inspectHarnessEnvironment,
   selectHarnessSession,
@@ -374,14 +366,8 @@ summaries and quoted attributes; it is not a general HTML validator or sanitizer
 the input or infers semantic relevance, cost, schema conformance, or failure causes. The existing
 `markdownSectionBetweenHeadings` API retains its original boundary behavior.
 
-`agent-harness-config` merges classifier-auto and sandbox keys into Claude, Codex, Grok, and Cursor
-config files. See [docs/agent-harness-config.md](./docs/agent-harness-config.md). `--global` updates
-home-directory configs; `--repo` updates a checkout. It does not copy allowlists, hooks, or plugins.
-Grok uses `permission_mode = "auto"` plus `auto_mode.enabled` and `default_auto_mode` so the
-classifier stays available in plan mode; its defined sandbox profile still requires
-`--sandbox workspace-write` at launch. Cursor uses global `approvalMode = "auto-review"`;
-`unrestricted` disables the sandbox. Repo checks surface user-level trust or mode prerequisites
-instead of claiming that repo files alone activate them.
+Machine-wide agent configuration now belongs to [vouchington-machines](https://github.com/vouchington/vouchington-machines/blob/main/docs/agent-config.md).
+Use its `configure-agents.sh` and `diagnose-agents.sh`; project hooks and MCP configuration remain in their checkouts.
 
 `agent-harness-identity` inspects the four harness environment signals without choosing a winner.
 Callers supply their own precedence to `selectHarnessSession`, keeping product-specific identity
@@ -470,6 +456,68 @@ Version one recognizes literal-key `apiResponse`, `apiNoContent`, `apiOpenApiRaw
 `ctx.setStatus`, and static `Content-Type` setters. The input source files and TypeScript checker
 are the source representation; the adapter does not parse or discover a repository on its own.
 
+Error-only 405 routes require a terminal throw on the handler's own context. Named handlers and
+imported wrappers are followed through compiler declarations; conditional, caught, recursive,
+fallthrough, and callback-only throws do not prove an error-only route. Empty `never[]` contracts
+render as arrays with no items, and `Record<string, never>` renders as a closed empty object.
+Standalone `never` and `any` remain unsupported contracts.
+
+Caller-owned `apiSseFrame(key, { event, data })` markers expose literal event names and concrete
+payloads from the frames actually written by a route, including callbacks passed to a handler
+factory. SSE responses keep a string body schema and describe each payload under the media
+type's `x-sse-events` map. Callback arguments require a concrete helper invocation path; ignored,
+declaration-only, deferred, or rewritten callbacks fail closed. Callback options passed to a callee
+without a concrete implementation also fail closed. Opaque callback escape checks include array and
+tuple containers, nested object properties, and literal array spreads. Factory callbacks must execute
+from the returned request handler; registration-time invocations do not prove a request emission. Compiler-resolved platform timers
+and Promise executors supply invocation paths using the caller Program's actual standard-library
+identities; shadowed, custom, or reassigned platform APIs do not. Mutation checks recognize Node's
+compiler-declared `global` as well as `globalThis`. Fluent route registrations retain their method. Stable named
+handlers and called local helpers are followed within their declaring source file. Ordinary response,
+request, query, and header markers also require callback invocation before route attribution.
+Broad names, unknown root payloads, executable unmarked frames through stream aliases, and
+conditional or mutable-context status changes fail closed. Called SSE helpers inherit the proven
+request context and its status at the invocation; mutually exclusive complete status branches retain
+their separate responses. Explicit SSE statuses must be integers from 100 through 599.
+Unconditional blocks preserve the last proven status setter; conditional or foreign overwrites fail closed.
+Indirect `setStatus.call`, `apply`, and `bind` forms fail closed instead of assuming status 200.
+Ambiguous caller contexts fail closed. A raw stream failure invalidates all
+selected SSE rows, including when only one protocol variant was requested. Object-literal wrapper
+receivers fail closed for marked frames because their properties can mutate; raw wrapper writes
+are matched to the original stream, including proven helper-parameter forwarding, overloaded helper
+implementations, and literal bracket
+methods. Compiler-resolved `Reflect.apply` calls use their actual receiver and payload.
+Unsupported computed methods on that receiver fail closed. Byte-bearing
+stream `end` calls and streams used as pipe destinations are raw emissions; empty terminal cleanup
+is preserved. Replacing a selected stream's `write` implementation invalidates its frame evidence.
+Binding a selected stream's `write` or `end` method fails closed because the bound
+method can escape the proven emission path. A callback that captures
+the route's stream or HTTP context and escapes to a callee without a concrete implementation can
+write undocumented bytes, so the affected response contracts fail closed. Uncalled local callbacks,
+dead branches, and implemented helpers that ignore their callback preserve the proven contracts.
+Cataloged SSE routes with only extracted non-SSE variants retain an unavailable event-stream
+possibility alongside those responses until the extracted variants describe the stream.
+
+Caller-owned `apiOpenApiHttpResponse(key, response)` markers bind a constant opaque response
+carrying optional readonly `apiHttpResponseVariants` metadata. Each concrete union variant has
+`status` and `bodyKind`; content variants also have `mediaType` and `body`. Discovery associates
+the marked variable's status and body emissions without reading or replacing response bytes.
+A status setter must dominate each body emission, including separate branches; constant context
+aliases are followed, assigned mutable context aliases and object-literal context wrappers fail closed,
+and helper parameters must resolve to the registered caller's unchanged response context.
+Helper-owned contracts also account for response emissions in their proven caller scopes.
+Indirect response `call`, `apply`, and `bind` forms fail closed, including borrowed context receivers.
+SSE frames and branded content variants reject body-forbidden 1xx, 204, 205, and 304 statuses.
+Literal bracket response methods have the same emission checks as property methods. Unrelated raw emissions
+remain unavailable. Separate branded response branches are checked together, and the nearest
+proven status setter for each body must belong to that response. Observed content and bodyless
+emissions must match the complete metadata union, including an empty response in the `else` branch
+of a positive body check. Exact requested protocol rows are selected before
+other payloads, media types, or statuses are validated. In lenient mode, incomplete marker evidence
+keeps every selected sibling unavailable. Explicit 400 content variants also include the framework's
+JSON error schema independently of their own media type. Explicit bodyless 400 metadata also
+retains that framework JSON possibility and fails closed on the conflicting body kinds.
+
 Fork diagnostics use a caller-selected `recordDirectory` in both the worker setup file and the
 main-process reporter. Call `registerForkExitSentinel({ recordDirectory })` once per fork, then
 update `setCurrentForkExitModule` and `setCurrentForkExitProject` around tests. Construct

package/dist/api-contract-discovery/header-contract-registry.mjs

@@ -1,8 +1,10 @@
 import ts from '../contract-schema/typescript-api.mjs';
+import { registerPlatformCompilerLibraries } from './protocol-platform-callbacks.mjs';
 import { contractError } from './response-contract-registration.mjs';
 import { parseHeaderContract } from './header-contract-parser.mjs';
 import { collectHandlerBindings, enclosingRouteBinding, visit, } from './response-contract-route-analysis.mjs';
 export function discoverApiHeaderContracts(program, sourceFiles, knownResponseRoutes) {
+    registerPlatformCompilerLibraries(program);
     const checker = program.getTypeChecker();
     const bindings = collectHandlerBindings(sourceFiles, checker);
     const contracts = new Map();

package/dist/api-contract-discovery/protocol-body-status.d.mts

@@ -0,0 +1,2 @@
+/** RFC 9110 sections 6.4.1 and 15.3.6 prohibit content at these response statuses. */
+export declare function statusForbidsBody(status: number): boolean;

package/dist/api-contract-discovery/protocol-body-status.mjs

@@ -0,0 +1,4 @@
+/** RFC 9110 sections 6.4.1 and 15.3.6 prohibit content at these response statuses. */
+export function statusForbidsBody(status) {
+    return (status >= 100 && status < 200) || status === 204 || status === 205 || status === 304;
+}

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

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { CallbackBindings, createProtocolCallbackValueResolver } from './protocol-callback-values.mts';
+/** Binds literal callback parameters, declining unsupported destructuring shapes. */
+export declare function callbackArgumentBindings(fn: ts.FunctionLikeDeclaration, call: ts.CallExpression | ts.NewExpression, env: CallbackBindings, captured: CallbackBindings, checker: ts.TypeChecker, resolver: ReturnType<typeof createProtocolCallbackValueResolver>): Map<ts.Symbol, {
+    node: ts.Node;
+    env: CallbackBindings;
+}> | undefined;

package/dist/api-contract-discovery/protocol-callback-argument-bindings.mjs

@@ -0,0 +1,33 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+/** Binds literal callback parameters, declining unsupported destructuring shapes. */
+export function callbackArgumentBindings(fn, call, env, captured, checker, resolver) {
+    const next = new Map(captured);
+    for (const [index, parameter] of runtimeParameters(fn).entries()) {
+        const argument = call.arguments?.[index];
+        if (!argument)
+            continue;
+        if (ts.isSpreadElement(argument))
+            return undefined;
+        if (ts.isIdentifier(parameter.name)) {
+            next.set(checker.getSymbolAtLocation(parameter.name), { node: argument, env });
+        }
+        else {
+            if (!ts.isObjectBindingPattern(parameter.name))
+                return undefined;
+            const value = resolver.resolve(argument, env);
+            for (const element of parameter.name.elements) {
+                const key = element.propertyName ?? element.name;
+                if (!ts.isIdentifier(element.name) ||
+                    element.dotDotDotToken ||
+                    element.initializer ||
+                    !(ts.isIdentifier(key) || ts.isStringLiteral(key)))
+                    return undefined;
+                const bound = resolver.property(value, key.text, new Set());
+                if (bound)
+                    next.set(checker.getSymbolAtLocation(element.name), bound);
+            }
+        }
+    }
+    return next;
+}

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

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.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 {};

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

@@ -0,0 +1,103 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { invokedResult, registeredHandler } from './protocol-callback-registration.mjs';
+import { platformCallbackArgument } from './protocol-platform-callbacks.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
+import { callbackBindingReplaced, callbackOptionsEscape } from './protocol-callback-mutations.mjs';
+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))
+        return false;
+    const resolver = createProtocolCallbackValueResolver(checker);
+    const { resolve, symbol } = resolver;
+    let invalidated = false;
+    function consumed(call, env, active, returned = false) {
+        const platform = platformCallbackArgument(call, checker);
+        const callee = resolve(platform ?? call.expression, env);
+        if (!callee || !functionNode(callee.node) || !callee.node.body || callee.node.asteriskToken) {
+            invalidated ||= callbackOptionsEscape(call, env, fn, resolver);
+            return false;
+        }
+        if (protocolCallbackHasWrittenBindings(callee.node, checker)) {
+            invalidated = true;
+            return false;
+        }
+        if (callee.node === fn)
+            return !returned;
+        if (active.has(callee.node))
+            return false;
+        const chain = new Set([...active, callee.node]);
+        if (platform)
+            return body(callee.node.body, callee.env, chain, false);
+        const next = new Map(callee.env);
+        runtimeParameters(callee.node).forEach((parameter, index) => {
+            const argument = call.arguments[index];
+            const target = symbol(parameter.name);
+            if (argument && !ts.isSpreadElement(argument))
+                next.set(target, { node: argument, env });
+        });
+        return body(callee.node.body, next, chain, returned || invokedResult(call));
+    }
+    function body(content, env, active, returned) {
+        let found = false;
+        let replaced = false;
+        function visit(node) {
+            if (found || replaced || !potentiallyExecuted(node))
+                return;
+            if (functionNode(node))
+                return;
+            if (callbackBindingReplaced(node, env, fn, resolver)) {
+                replaced = true;
+                invalidated = true;
+                return;
+            }
+            if ((ts.isCallExpression(node) || ts.isNewExpression(node)) &&
+                consumed(node, env, active, returned && ts.isReturnStatement(node.parent)) &&
+                (!returned || ts.isReturnStatement(node.parent))) {
+                found = true;
+                return;
+            }
+            if (returned && ts.isReturnStatement(node) && node.expression) {
+                const value = resolve(node.expression, env);
+                if (value &&
+                    functionNode(value.node) &&
+                    value.node.body &&
+                    !value.node.asteriskToken &&
+                    !active.has(value.node) &&
+                    body(value.node.body, value.env, new Set([...active, value.node]), false)) {
+                    found = true;
+                    return;
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(content);
+        return found && !invalidated;
+    }
+    let argument = fn;
+    while (ts.isPropertyAssignment(argument.parent) ||
+        ts.isObjectLiteralExpression(argument.parent) ||
+        ts.isParenthesizedExpression(argument.parent) ||
+        ts.isAsExpression(argument.parent) ||
+        ts.isNonNullExpression(argument.parent))
+        argument = argument.parent;
+    const call = argument.parent;
+    if (!ts.isCallExpression(call) && !ts.isNewExpression(call)) {
+        const owner = enclosingFunction(fn);
+        if (owner && isSupportedProtocolCallback(owner, checker))
+            return body(owner.body, new Map(), new Set([owner]), false);
+        return protocolCallbackSourceCalls(fn).some((candidate) => potentiallyExecuted(candidate) &&
+            ((registeredHandler(candidate) &&
+                candidate.arguments.some((value) => resolve(value, new Map())?.node === fn)) ||
+                consumed(candidate, new Map(), new Set())));
+    }
+    if (!potentiallyExecuted(call))
+        return false;
+    if (ts.isCallExpression(call) && call.expression === argument)
+        return true;
+    if (argument === fn && ts.isCallExpression(call) && registeredHandler(call))
+        return true;
+    return (!!call.arguments?.includes(argument) && consumed(call, new Map(), new Set()));
+}

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

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { CallbackBindings, createProtocolCallbackValueResolver } from './protocol-callback-values.mts';
+export declare function callbackBindingReplaced(node: ts.Node, env: CallbackBindings, fn: ts.FunctionLikeDeclaration, resolver: ReturnType<typeof createProtocolCallbackValueResolver>): boolean;
+/** An opaque callee may replace a callback stored in a forwarded options object. */
+export declare function callbackOptionsEscape(node: ts.CallExpression | ts.NewExpression, env: CallbackBindings, fn: ts.FunctionLikeDeclaration, resolver: ReturnType<typeof createProtocolCallbackValueResolver>): boolean;

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

@@ -0,0 +1,42 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+export function callbackBindingReplaced(node, env, fn, resolver) {
+    const { resolve, symbol } = resolver;
+    const write = ts.isDeleteExpression(node)
+        ? node.expression
+        : ts.isBinaryExpression(node) &&
+            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment
+            ? node.left
+            : undefined;
+    if (!write)
+        return false;
+    let root = unwrapExpression(write);
+    while (ts.isPropertyAccessExpression(root) || ts.isElementAccessExpression(root))
+        root = unwrapExpression(root.expression);
+    return (ts.isIdentifier(root) && env.has(symbol(root))) || resolve(write, env)?.node === fn;
+}
+/** An opaque callee may replace a callback stored in a forwarded options object. */
+export function callbackOptionsEscape(node, env, fn, resolver) {
+    function contains(value, bindings, seen = new Set()) {
+        const resolved = resolver.resolve(value, bindings);
+        if (!resolved || seen.has(resolved.node))
+            return false;
+        seen.add(resolved.node);
+        if (resolved.node === fn)
+            return true;
+        if (ts.isArrayLiteralExpression(resolved.node))
+            return resolved.node.elements.some((element) => contains(ts.isSpreadElement(element) ? element.expression : element, resolved.env, seen));
+        if (!ts.isObjectLiteralExpression(resolved.node))
+            return false;
+        return resolved.node.properties.some((member) => member === fn ||
+            (ts.isPropertyAssignment(member)
+                ? contains(member.initializer, resolved.env, seen)
+                : ts.isShorthandPropertyAssignment(member) &&
+                    (() => {
+                        const target = resolver.property(resolved, member.name.text, new Set());
+                        return !!target && contains(target.node, target.env, seen);
+                    })()));
+    }
+    return !!node.arguments?.some((argument) => contains(argument, env));
+}

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

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function registeredHandler(call: ts.CallExpression): boolean;
+export declare function invokedResult(call: ts.CallExpression | ts.NewExpression): boolean;

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

@@ -0,0 +1,27 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+export function registeredHandler(call) {
+    const method = unwrapExpression(call.expression);
+    if (!ts.isPropertyAccessExpression(method) ||
+        !['get', 'post', 'put', 'patch', 'delete', 'head', 'options'].includes(method.name.text))
+        return false;
+    let receiver = method.expression;
+    while (ts.isCallExpression(receiver) && ts.isPropertyAccessExpression(receiver.expression)) {
+        if (receiver.expression.name.text === 'route')
+            return true;
+        receiver = receiver.expression.expression;
+    }
+    return false;
+}
+export function invokedResult(call) {
+    let node = call;
+    while (ts.isParenthesizedExpression(node.parent) ||
+        ts.isAsExpression(node.parent) ||
+        ts.isNonNullExpression(node.parent) ||
+        ts.isAwaitExpression(node.parent))
+        node = node.parent;
+    const parent = node.parent;
+    return (ts.isCallExpression(parent) &&
+        (parent.expression === node ||
+            (registeredHandler(parent) && parent.arguments.includes(node))));
+}

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

@@ -0,0 +1,17 @@
+import ts from '../contract-schema/typescript-api.mts';
+type FunctionNode = ts.FunctionLikeDeclaration;
+export type CallbackValue = {
+    node: ts.Node;
+    env: CallbackBindings;
+};
+export type CallbackBindings = ReadonlyMap<ts.Symbol, CallbackValue>;
+export declare function isProtocolCallbackFunction(node: ts.Node): node is FunctionNode;
+/** Resolves stable named uses in outer statements and directly registered inline handlers. */
+export declare function protocolCallbackSourceCalls(fn: FunctionNode): ts.CallExpression[];
+export declare function createProtocolCallbackValueResolver(checker: ts.TypeChecker): {
+    resolve: (node: ts.Node, env: CallbackBindings, seen?: Set<ts.Node>) => CallbackValue | undefined;
+    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 {};

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

@@ -0,0 +1,114 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { registeredHandler } from './protocol-callback-registration.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { hasBindingWrite } from './registered-route-binding-writes.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+export function isProtocolCallbackFunction(node) {
+    return ts.isFunctionLike(node) && 'body' in node;
+}
+/** Resolves stable named uses in outer statements and directly registered inline handlers. */
+export function protocolCallbackSourceCalls(fn) {
+    const declaration = fn.parent;
+    if (!ts.isFunctionDeclaration(fn) &&
+        (!ts.isVariableDeclaration(declaration) ||
+            !ts.isIdentifier(declaration.name) ||
+            !ts.isVariableDeclarationList(declaration.parent) ||
+            !(declaration.parent.flags & ts.NodeFlags.Const)))
+        return [];
+    const calls = [];
+    function visit(node) {
+        if (isProtocolCallbackFunction(node) &&
+            !(ts.isCallExpression(node.parent) &&
+                registeredHandler(node.parent) &&
+                node.parent.arguments.includes(node)))
+            return;
+        if (ts.isCallExpression(node))
+            calls.push(node);
+        ts.forEachChild(node, visit);
+    }
+    visit(fn.getSourceFile());
+    return calls;
+}
+function literalName(node) {
+    return ts.isIdentifier(node) || ts.isStringLiteral(node) ? node.text : undefined;
+}
+export function createProtocolCallbackValueResolver(checker) {
+    function symbol(node) {
+        const found = checker.getSymbolAtLocation(node);
+        return found?.flags && found.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(found)
+            : found;
+    }
+    function property(value, name, seen) {
+        if (!value ||
+            !ts.isObjectLiteralExpression(value.node) ||
+            value.node.properties.some(ts.isSpreadAssignment))
+            return undefined;
+        const member = value.node.properties.find((item) => item.name && literalName(item.name) === name);
+        if (member && ts.isPropertyAssignment(member))
+            return resolve(member.initializer, value.env, seen);
+        if (member && ts.isShorthandPropertyAssignment(member)) {
+            const target = checker.getShorthandAssignmentValueSymbol(member);
+            return target ? declaration(target, value.env, seen) : undefined;
+        }
+        return member && isProtocolCallbackFunction(member)
+            ? { node: member, env: value.env }
+            : undefined;
+    }
+    function declaration(target, env, seen) {
+        const bound = env.get(target);
+        if (bound)
+            return resolve(bound.node, bound.env, seen);
+        const implemented = target.declarations?.find((item) => isProtocolCallbackFunction(item) && item.body);
+        if (implemented)
+            return { node: implemented, env };
+        const node = target.valueDeclaration;
+        if (!node || seen.has(node))
+            return undefined;
+        seen.add(node);
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isVariableDeclarationList(node.parent) &&
+            node.parent.flags & ts.NodeFlags.Const)
+            return resolve(node.initializer, env, seen);
+        if (ts.isBindingElement(node) && ts.isObjectBindingPattern(node.parent)) {
+            const owner = node.parent.parent;
+            const name = literalName(node.propertyName ?? node.name);
+            if (name &&
+                ts.isVariableDeclaration(owner) &&
+                owner.initializer &&
+                ts.isVariableDeclarationList(owner.parent) &&
+                owner.parent.flags & ts.NodeFlags.Const)
+                return property(resolve(owner.initializer, env, seen), name, seen);
+        }
+        return undefined;
+    }
+    function resolve(node, env, seen = new Set()) {
+        if (ts.isExpression(node))
+            node = unwrapExpression(node);
+        if (seen.has(node))
+            return undefined;
+        seen.add(node);
+        if (isProtocolCallbackFunction(node) ||
+            ts.isObjectLiteralExpression(node) ||
+            ts.isArrayLiteralExpression(node))
+            return { node, env };
+        if (ts.isIdentifier(node)) {
+            const target = symbol(node);
+            return target ? declaration(target, env, seen) : undefined;
+        }
+        if (ts.isPropertyAccessExpression(node)) {
+            const member = property(resolve(node.expression, env, seen), node.name.text, seen);
+            if (member)
+                return member;
+            const target = symbol(node.name);
+            return target ? declaration(target, env, seen) : undefined;
+        }
+        return undefined;
+    }
+    return { resolve, symbol, property };
+}
+export function protocolCallbackHasWrittenBindings(fn, checker) {
+    return ((ts.isFunctionDeclaration(fn) && hasBindingWrite(fn, checker)) ||
+        runtimeParameters(fn).some((parameter) => hasBindingWrite(parameter, checker)));
+}

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

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function unsupportedContextAlias(node: ts.VariableDeclaration, context: ts.Symbol, checker: ts.TypeChecker): boolean;
+export declare function unsupportedContextAssignment(node: ts.Node, context: ts.Symbol, checker: ts.TypeChecker): boolean;

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

@@ -0,0 +1,20 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+export function unsupportedContextAlias(node, context, checker) {
+    if (!node.initializer)
+        return false;
+    const receiver = expressionReceiver(node.initializer, checker);
+    return (receiver?.root === context &&
+        (receiver.path.length === 0 ||
+            (receiver.path.length === 1 && receiver.path[0] === 'response')) &&
+        (!ts.isIdentifier(node.name) ||
+            !ts.isVariableDeclarationList(node.parent) ||
+            !(node.parent.flags & ts.NodeFlags.Const)));
+}
+export function unsupportedContextAssignment(node, context, checker) {
+    if (!ts.isBinaryExpression(node) || node.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+        return false;
+    const receiver = expressionReceiver(node.right, checker);
+    return (receiver?.root === context &&
+        (receiver.path.length === 0 || (receiver.path.length === 1 && receiver.path[0] === 'response')));
+}

package/dist/api-contract-discovery/protocol-contract-extraction.d.mts

@@ -0,0 +1,9 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type ExtractedResponseContract } from '../contract-schema/index.mts';
+import type { DiscoverApiResponseContractsOptions } from './response-contract-lenient.mts';
+import type { BackendResponseContract } from './response-contract-types.mts';
+export declare function extractSseEvents(type: ts.Type, checker: ts.TypeChecker, source: string, options: DiscoverApiResponseContractsOptions | undefined): {
+    eventName: string;
+    contract: ExtractedResponseContract;
+}[];
+export declare function extractHttpVariants(type: ts.Type, checker: ts.TypeChecker, source: string, options: DiscoverApiResponseContractsOptions | undefined, selectRow: (index: number) => boolean): Omit<BackendResponseContract, 'method' | 'routeTemplate'>[];

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

@@ -0,0 +1,87 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { extractContractSchema } from '../contract-schema/index.mjs';
+import { propertyType, stringLiterals, typeVariants } from './protocol-marker-analysis.mjs';
+import { noContentContract } from './response-contract-registration.mjs';
+import { statusForbidsBody } from './protocol-body-status.mjs';
+export function extractSseEvents(type, checker, source, options) {
+    return typeVariants(type).flatMap((variant) => {
+        const names = stringLiterals(propertyType(variant, 'event', checker));
+        const contract = concretePayload(propertyType(variant, 'data', checker), checker, source, options);
+        return names.map((eventName) => ({ eventName, contract }));
+    });
+}
+export function extractHttpVariants(type, checker, source, options, selectRow) {
+    const carrier = propertyType(type, 'apiHttpResponseVariants', checker);
+    const variants = typeVariants(carrier).filter((variant) => !(variant.flags & ts.TypeFlags.Undefined));
+    if (variants.length === 0)
+        throw new Error('HTTP response requires concrete variants');
+    let row = 0;
+    const selections = variants.map((variant) => {
+        const rawMedia = rawPropertyType(variant, 'mediaType', checker);
+        const rawKind = rawPropertyType(variant, 'bodyKind', checker);
+        const count = rawKind?.isStringLiteral() && rawKind.value === 'none'
+            ? 1
+            : rawMedia?.isUnion()
+                ? rawMedia.types.length
+                : 1;
+        const selected = Array.from({ length: count }, () => selectRow(row++));
+        return selected;
+    });
+    return variants.flatMap((variant, index) => {
+        const selected = selections[index];
+        if (!selected.some(Boolean))
+            return [];
+        const status = propertyType(variant, 'status', checker);
+        if (!(status.flags & ts.TypeFlags.NumberLiteral))
+            throw new Error('HTTP response requires a literal status');
+        const value = status.value;
+        if (!Number.isInteger(value) || value < 100 || value > 599)
+            throw new Error('HTTP response status is invalid');
+        const kinds = stringLiterals(propertyType(variant, 'bodyKind', checker));
+        if (kinds.length !== 1)
+            throw new Error('HTTP response requires one concrete body kind per variant');
+        const statusCodes = [value];
+        if (kinds[0] === 'none')
+            return [
+                {
+                    ...noContentContract(source),
+                    statusCodes,
+                    statusKnowledge: 'explicit',
+                    bodyKind: 'none',
+                    mediaTypeKnowledge: 'none',
+                    ...(value === 400 ? { includeDefaultError: true } : {}),
+                },
+            ];
+        if (kinds[0] !== 'content')
+            throw new Error('HTTP response body kind is invalid');
+        if (statusForbidsBody(value))
+            throw new Error(`HTTP status ${value} forbids response content`);
+        const contract = concretePayload(propertyType(variant, 'body', checker), checker, source, options);
+        return stringLiterals(propertyType(variant, 'mediaType', checker)).flatMap((mediaType, index) => selected[index]
+            ? [
+                {
+                    ...contract,
+                    statusCodes,
+                    statusKnowledge: 'explicit',
+                    bodyKind: 'content',
+                    mediaType,
+                    mediaTypeKnowledge: 'known',
+                    ...(value === 400 ? { includeDefaultError: true } : {}),
+                },
+            ]
+            : []);
+    });
+}
+function concretePayload(type, checker, source, options) {
+    const contract = extractContractSchema(type, checker, source, options);
+    if (contract.schema.root.type === 'unknown')
+        throw new Error('Protocol payload must have a concrete root');
+    return contract;
+}
+function rawPropertyType(type, name, checker) {
+    const property = checker.getPropertyOfType(type, name);
+    const declaration = property?.valueDeclaration ?? property?.declarations?.[0];
+    return property && declaration
+        ? checker.getTypeOfSymbolAtLocation(property, declaration)
+        : undefined;
+}

package/dist/api-contract-discovery/protocol-contract-keys.d.mts

@@ -0,0 +1 @@
+export declare function nextProtocolKey(contracts: ReadonlyMap<string, unknown>, key: string): string;

package/dist/api-contract-discovery/protocol-contract-keys.mjs

@@ -0,0 +1,8 @@
+export function nextProtocolKey(contracts, key) {
+    if (!contracts.has(key))
+        return key;
+    let index = 2;
+    while (contracts.has(`${key}#protocol-${index}`))
+        index++;
+    return `${key}#protocol-${index}`;
+}

package/dist/api-contract-discovery/protocol-contract-registry.d.mts

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type DiscoverApiResponseContractsOptions } from './response-contract-lenient.mts';
+import { type HandlerBindings } from './response-contract-route-analysis.mts';
+import type { BackendResponseContract } from './response-contract-types.mts';
+export declare function discoverProtocolContracts(sourceFiles: readonly ts.SourceFile[], checker: ts.TypeChecker, bindings: HandlerBindings, contracts: Map<string, BackendResponseContract>, options: DiscoverApiResponseContractsOptions | undefined, requestedKeys?: ReadonlySet<string>): Set<ts.CallExpression>;