vouchington-tooling 0.29.0 → 0.30.0

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

@@ -0,0 +1,53 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { associateHttpResponse } from './protocol-http-association.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { statusDominatesEmission } from './protocol-status-dominance.mjs';
+export function registerHttpProtocols(pending, contracts, checker, reject) {
+    const covered = new Set();
+    const groups = new Map();
+    for (const response of pending) {
+        const handler = enclosingFunction(response.call);
+        const group = groups.get(handler) ?? [];
+        group.push(response);
+        groups.set(handler, group);
+    }
+    for (const group of groups.values()) {
+        if (!group.some((response) => response.keys.length))
+            continue;
+        try {
+            const siblings = new Set(group.map((response) => response.symbol));
+            const associations = new Map(group.map((response) => [
+                response,
+                associateHttpResponse(response.call, response.symbol, checker, siblings),
+            ]));
+            const allStatuses = new Set([...associations.values()].flatMap((emissions) => [...emissions].filter(([, kind]) => kind === 'status').map(([call]) => call)));
+            const proven = new Set();
+            for (const [response, emissions] of associations) {
+                proveHttpEmissions(response, emissions, allStatuses);
+                for (const call of emissions.keys())
+                    proven.add(call);
+            }
+            // Every sibling must prove its own emissions before any group contract is published.
+            for (const response of group)
+                response.variants.forEach((variant, index) => contracts.set(response.keys[index], { ...variant, ...response.binding }));
+            for (const call of proven)
+                covered.add(call);
+        }
+        catch (error) {
+            for (const response of group)
+                if (response.keys.length)
+                    reject(response, error);
+        }
+    }
+    return covered;
+}
+function proveHttpEmissions(response, emissions, allStatuses) {
+    const statuses = new Set([...emissions].filter(([, kind]) => kind === 'status').map(([call]) => call));
+    const kinds = new Set(emissions.values());
+    const declaredBodyKinds = response.declaredBodyKinds;
+    if (!kinds.has('status') ||
+        [...declaredBodyKinds].some((kind) => !kinds.has(kind)) ||
+        [...kinds].some((kind) => kind !== 'status' && !declaredBodyKinds.has(kind)) ||
+        [...emissions].some(([call, kind]) => kind !== 'status' && !statusDominatesEmission(call, statuses, allStatuses)))
+        throw new Error('HTTP response variants require dominating status and associated body emissions');
+}

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

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function protocolMarker(expression: ts.Expression, checker: ts.TypeChecker): 'apiSseFrame' | 'apiOpenApiHttpResponse' | undefined;
+export declare function propertyType(type: ts.Type, name: string, checker: ts.TypeChecker): ts.Type;
+export declare function typeVariants(type: ts.Type): readonly ts.Type[];
+export declare function stringLiterals(type: ts.Type): string[];
+export declare function unwrapExpression(expression: ts.Expression): ts.Expression;
+export declare function enclosingFunction(node: ts.Node): ts.FunctionLikeDeclaration | undefined;

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

@@ -0,0 +1,50 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export function protocolMarker(expression, checker) {
+    const symbol = checker.getSymbolAtLocation(expression);
+    const resolved = symbol && (symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol);
+    const name = resolved?.name;
+    return name === 'apiSseFrame' || name === 'apiOpenApiHttpResponse' ? name : undefined;
+}
+export function propertyType(type, name, checker) {
+    const property = checker.getPropertyOfType(type, name);
+    const declaration = property?.valueDeclaration ?? property?.declarations?.[0];
+    if (!property || !declaration)
+        throw new Error(`Protocol contract requires ${name}`);
+    return checker.getTypeOfSymbolAtLocation(property, declaration);
+}
+export function typeVariants(type) {
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never))
+        throw new Error('Protocol contract requires concrete variants');
+    return type.isUnion() ? type.types : [type];
+}
+export function stringLiterals(type) {
+    return typeVariants(type).map((variant) => {
+        if (!(variant.flags & ts.TypeFlags.StringLiteral))
+            throw new Error('Protocol contract requires literal names and media types');
+        const value = variant.value;
+        if (!value || /[\r\n]/.test(value))
+            throw new Error('Protocol contract requires nonempty single-line names');
+        return value;
+    });
+}
+export function unwrapExpression(expression) {
+    if (ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isTypeAssertionExpression(expression) ||
+        ts.isNonNullExpression(expression) ||
+        ts.isAwaitExpression(expression))
+        return unwrapExpression(expression.expression);
+    return expression;
+}
+export function enclosingFunction(node) {
+    let current = node.parent;
+    while (current) {
+        if (ts.isArrowFunction(current) ||
+            ts.isFunctionExpression(current) ||
+            ts.isFunctionDeclaration(current) ||
+            ts.isMethodDeclaration(current))
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}

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

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Proves an executable lexical path containing at least one opaque callback escape. */
+export declare function opaqueProtocolCallbackPath(node: ts.Node, checker: ts.TypeChecker): boolean;

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

@@ -0,0 +1,107 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { callbackOptionsEscape } from './protocol-callback-mutations.mjs';
+import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
+import { potentiallyExecuted } from './protocol-executable-path.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { callbackArgumentBindings } from './protocol-callback-argument-bindings.mjs';
+import { createProtocolCallbackValueResolver, isProtocolCallbackFunction as functionNode, } from './protocol-callback-values.mjs';
+function implementedFunction(node) {
+    return functionNode(node) && !!node.body;
+}
+/** Proves an executable lexical path containing at least one opaque callback escape. */
+export function opaqueProtocolCallbackPath(node, checker) {
+    if (!potentiallyExecuted(node))
+        return false;
+    const functions = [];
+    for (let fn = enclosingFunction(node); fn; fn = enclosingFunction(fn))
+        functions.push(fn);
+    if (!functions.length ||
+        functions.some((fn) => !fn.body || fn.asteriskToken || !potentiallyExecuted(fn)))
+        return false;
+    let opaque = false;
+    for (const fn of functions) {
+        if (isSupportedProtocolCallback(fn, checker))
+            continue;
+        if (!escapesToOpaque(fn, checker))
+            return false;
+        opaque = true;
+    }
+    return opaque;
+}
+function escapesToOpaque(callback, checker) {
+    const resolver = createProtocolCallbackValueResolver(checker);
+    function opaque(call, env) {
+        const implementation = resolver.resolve(call.expression, env);
+        if (implementation && functionNode(implementation.node) && implementation.node.body)
+            return false;
+        const declaration = checker.getResolvedSignature(call)?.declaration;
+        return !declaration || !('body' in declaration && declaration.body);
+    }
+    function executableCallsite(call) {
+        const callbackAncestors = new Set();
+        for (let fn = enclosingFunction(callback); fn; fn = enclosingFunction(fn))
+            callbackAncestors.add(fn);
+        for (let fn = enclosingFunction(call); fn; fn = enclosingFunction(fn))
+            if (!fn.body ||
+                fn.asteriskToken ||
+                !potentiallyExecuted(fn) ||
+                (!callbackAncestors.has(fn) && !isSupportedProtocolCallback(fn, checker)))
+                return false;
+        return true;
+    }
+    function scanBody(fn, env, active) {
+        const chain = new Set([...active, fn]);
+        let escaped = false;
+        function visit(node) {
+            if (escaped || !potentiallyExecuted(node))
+                return;
+            if (ts.isFunctionLike(node))
+                return;
+            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                const forwards = callbackOptionsEscape(node, env, callback, resolver);
+                if (forwards && opaque(node, env)) {
+                    escaped = true;
+                    return;
+                }
+                const target = forwards ? resolver.resolve(node.expression, env) : undefined;
+                if (target &&
+                    implementedFunction(target.node) &&
+                    !target.node.asteriskToken &&
+                    !chain.has(target.node)) {
+                    const next = callbackArgumentBindings(target.node, node, env, target.env, checker, resolver);
+                    if (!next || scanBody(target.node, next, chain))
+                        escaped = true;
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(fn.body);
+        return escaped;
+    }
+    function sourceCalls(source) {
+        let escaped = false;
+        function visit(node) {
+            if (escaped || !potentiallyExecuted(node))
+                return;
+            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                if (!executableCallsite(node))
+                    return;
+                const forwards = callbackOptionsEscape(node, new Map(), callback, resolver);
+                if (forwards && opaque(node, new Map())) {
+                    escaped = true;
+                    return;
+                }
+                const target = forwards ? resolver.resolve(node.expression, new Map()) : undefined;
+                if (target && implementedFunction(target.node) && !target.node.asteriskToken) {
+                    const next = callbackArgumentBindings(target.node, node, new Map(), target.env, checker, resolver);
+                    if (!next || scanBody(target.node, next, new Set()))
+                        escaped = true;
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(source);
+        return escaped;
+    }
+    return sourceCalls(callback.getSourceFile());
+}

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

@@ -0,0 +1,5 @@
+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;
+/** 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

@@ -0,0 +1,72 @@
+import { basename, dirname, resolve as resolvePath } from 'node:path';
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { writtenPlatformSymbols } from './protocol-platform-writes.mjs';
+const standardLibrary = dirname(resolvePath(ts.getDefaultLibFilePath({})));
+const platformWrites = new WeakMap();
+const compilerLibraries = new WeakMap();
+/** Records the actual caller compiler's library identities, including another installation. */
+export function registerPlatformCompilerLibraries(program) {
+    const checker = program.getTypeChecker();
+    if (!compilerLibraries.has(checker)) {
+        const libraries = new Set(program.getSourceFiles().filter((file) => program.isSourceFileDefaultLibrary(file)));
+        compilerLibraries.set(checker, libraries);
+        platformWrites.set(checker, writtenPlatformSymbols(program.getSourceFiles(), checker, libraries));
+    }
+}
+function standardDeclaration(declaration, timer, checker) {
+    const source = declaration.getSourceFile();
+    if (!source.isDeclarationFile)
+        return false;
+    const file = resolvePath(source.fileName);
+    const libraries = compilerLibraries.get(checker);
+    if (libraries
+        ? libraries.has(source)
+        : dirname(file) === standardLibrary && /^lib(?:\.[\w.-]+)?\.d\.ts$/.test(basename(file)))
+        return true;
+    return (timer &&
+        /\/node_modules\/@types\/node\/(?:web-globals\/)?timers\.d\.ts$/.test(file.replaceAll('\\', '/')));
+}
+function platformSymbol(expression, checker, seen = new Set()) {
+    const value = unwrapExpression(expression);
+    if (!ts.isIdentifier(value))
+        return undefined;
+    const symbol = checker.getSymbolAtLocation(value);
+    if (!symbol || seen.has(symbol))
+        return undefined;
+    seen.add(symbol);
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+        const target = checker.getAliasedSymbol(symbol);
+        if (seen.has(target))
+            return undefined;
+        return target;
+    }
+    const declaration = symbol.valueDeclaration;
+    if (declaration &&
+        ts.isVariableDeclaration(declaration) &&
+        declaration.initializer &&
+        ts.isVariableDeclarationList(declaration.parent) &&
+        declaration.parent.flags & ts.NodeFlags.Const)
+        return platformSymbol(declaration.initializer, checker, seen);
+    return symbol;
+}
+/** Recognizes only callback APIs supplied by the compiler's standard libraries or Node typings. */
+export function platformCallbackArgument(node, checker) {
+    if (ts.isCallExpression(node) && node.questionDotToken)
+        return undefined;
+    const argument = node.arguments?.[0];
+    if (!argument || ts.isSpreadElement(argument))
+        return undefined;
+    const symbol = platformSymbol(node.expression, checker);
+    if (!symbol?.declarations?.length)
+        return undefined;
+    const timer = symbol.name === 'setInterval' || symbol.name === 'setTimeout';
+    if (!(timer ? ts.isCallExpression(node) : symbol.name === 'Promise' && ts.isNewExpression(node)))
+        return undefined;
+    const writes = platformWrites.get(checker) ?? writtenPlatformSymbols([node.getSourceFile()], checker);
+    if (writes.has(symbol))
+        return undefined;
+    return symbol.declarations.every((declaration) => standardDeclaration(declaration, timer, checker))
+        ? argument
+        : undefined;
+}

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

@@ -0,0 +1,5 @@
+import ts from '../contract-schema/typescript-api.mts';
+export declare function literalStrings(expression: ts.Expression | undefined, checker: ts.TypeChecker): readonly string[] | undefined;
+export declare function globalTarget(expression: ts.Expression, checker: ts.TypeChecker, seen?: Set<ts.Symbol>): ts.Expression | undefined;
+export declare function mutatorKind(call: ts.CallExpression, checker: ts.TypeChecker, libraries: ReadonlySet<ts.SourceFile> | undefined): 'defineProperty' | 'set' | 'assign' | undefined;
+export declare function sourceKeys(source: ts.Expression, checker: ts.TypeChecker): readonly string[] | undefined;

package/dist/api-contract-discovery/protocol-platform-mutation-targets.mjs

@@ -0,0 +1,89 @@
+import { basename, dirname, resolve as resolvePath } from 'node:path';
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+const standardLibrary = dirname(resolvePath(ts.getDefaultLibFilePath({})));
+function isStandardDeclaration(declaration, libraries) {
+    const source = declaration.getSourceFile();
+    const file = resolvePath(source.fileName);
+    return libraries
+        ? libraries.has(source)
+        : source.isDeclarationFile &&
+            dirname(file) === standardLibrary &&
+            /^lib(?:\.[\w.-]+)?\.d\.ts$/.test(basename(file));
+}
+export function literalStrings(expression, checker) {
+    if (!expression)
+        return undefined;
+    const strings = new Set();
+    function visit(type) {
+        if (type.isUnion())
+            return type.types.every(visit);
+        if (type.flags & ts.TypeFlags.StringLiteral) {
+            strings.add(type.value);
+            return true;
+        }
+        if (type.flags &
+            (ts.TypeFlags.String | ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter))
+            return false;
+        return true;
+    }
+    return visit(checker.getTypeAtLocation(expression)) ? [...strings] : undefined;
+}
+export function globalTarget(expression, checker, seen = new Set()) {
+    const value = unwrapExpression(expression);
+    if (!ts.isIdentifier(value))
+        return undefined;
+    const symbol = checker.getSymbolAtLocation(value);
+    if (!symbol || seen.has(symbol))
+        return undefined;
+    seen.add(symbol);
+    if (value.text === 'globalThis')
+        return symbol.declarations?.length ? undefined : value;
+    if (symbol.name === 'global' &&
+        symbol.declarations?.some((declaration) => {
+            const source = declaration.getSourceFile();
+            return (ts.isVariableDeclaration(declaration) &&
+                source.isDeclarationFile &&
+                resolvePath(source.fileName)
+                    .replaceAll('\\', '/')
+                    .endsWith('/node_modules/@types/node/globals.d.ts'));
+        }))
+        return value;
+    const declaration = symbol.valueDeclaration;
+    return declaration && ts.isVariableDeclaration(declaration) && declaration.initializer
+        ? globalTarget(declaration.initializer, checker, seen)
+        : undefined;
+}
+export function mutatorKind(call, checker, libraries) {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression))
+        return undefined;
+    const owner = callee.expression.text;
+    const method = callee.name.text;
+    if (!((owner === 'Object' && ['defineProperty', 'assign'].includes(method)) ||
+        (owner === 'Reflect' && method === 'set')))
+        return undefined;
+    const ownerSymbol = checker.getSymbolAtLocation(callee.expression);
+    const methodSymbol = checker.getSymbolAtLocation(callee.name);
+    if (!ownerSymbol?.declarations?.length ||
+        !methodSymbol?.declarations?.length ||
+        !ownerSymbol.declarations.every((declaration) => isStandardDeclaration(declaration, libraries)) ||
+        !methodSymbol.declarations.every((declaration) => isStandardDeclaration(declaration, libraries)))
+        return undefined;
+    return method;
+}
+export function sourceKeys(source, checker) {
+    const keys = new Set();
+    function visit(type) {
+        if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter))
+            return false;
+        if (type.isUnion())
+            return type.types.every(visit);
+        if (type.getStringIndexType())
+            return false;
+        for (const property of type.getProperties())
+            keys.add(property.name);
+        return true;
+    }
+    return visit(checker.getTypeAtLocation(unwrapExpression(source))) ? [...keys] : undefined;
+}

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

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Records global timer and Promise writes, including calls to standard property mutators. */
+export declare function writtenPlatformSymbols(files: readonly ts.SourceFile[], checker: ts.TypeChecker, libraries?: ReadonlySet<ts.SourceFile>): Set<ts.Symbol>;

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

@@ -0,0 +1,92 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { unwrapExpression } from './protocol-marker-analysis.mjs';
+import { globalTarget, literalStrings, mutatorKind, sourceKeys, } from './protocol-platform-mutation-targets.mjs';
+const platformNames = ['setTimeout', 'setInterval', 'Promise'];
+/** Records global timer and Promise writes, including calls to standard property mutators. */
+export function writtenPlatformSymbols(files, checker, libraries) {
+    const written = new Set();
+    function mark(target, keys) {
+        const root = globalTarget(target, checker);
+        if (!root)
+            return;
+        const members = keys
+            ? keys.map((key) => checker.getPropertyOfType(checker.getTypeAtLocation(root), key))
+            : platformNames.map((name) => checker.getPropertyOfType(checker.getTypeAtLocation(root), name));
+        for (const member of members)
+            if (member && platformNames.includes(member.name))
+                written.add(member);
+    }
+    function target(node) {
+        if (ts.isElementAccessExpression(node)) {
+            const keys = literalStrings(node.argumentExpression, checker);
+            mark(node.expression, keys);
+            return;
+        }
+        if (ts.isPropertyAccessExpression(node)) {
+            const symbol = checker.getSymbolAtLocation(node.name);
+            if (globalTarget(node.expression, checker) && symbol && platformNames.includes(symbol.name))
+                written.add(symbol);
+            return;
+        }
+        const symbol = checker.getSymbolAtLocation(node);
+        if (symbol && platformNames.includes(symbol.name))
+            written.add(symbol);
+        if (ts.isObjectLiteralExpression(node) ||
+            ts.isArrayLiteralExpression(node) ||
+            ts.isPropertyAssignment(node) ||
+            ts.isSpreadAssignment(node) ||
+            ts.isSpreadElement(node))
+            ts.forEachChild(node, target);
+    }
+    function visit(node) {
+        if (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+            target(node.left);
+        if (ts.isDeleteExpression(node))
+            target(node.expression);
+        if (ts.isCallExpression(node)) {
+            const kind = mutatorKind(node, checker, libraries);
+            if (kind && node.arguments[0] && ts.isSpreadElement(node.arguments[0]))
+                for (const file of files)
+                    for (const binding of checker.getSymbolsInScope(file, ts.SymbolFlags.Value | ts.SymbolFlags.Alias)) {
+                        const symbol = binding.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(binding) : binding;
+                        if (platformNames.includes(symbol.name))
+                            written.add(symbol);
+                    }
+            if (kind === 'defineProperty' || kind === 'set') {
+                const receiver = node.arguments[0];
+                if (receiver && !ts.isSpreadElement(receiver))
+                    mark(receiver, literalStrings(node.arguments[1] && !ts.isSpreadElement(node.arguments[1])
+                        ? node.arguments[1]
+                        : undefined, checker));
+            }
+            else if (kind === 'assign') {
+                const receiver = node.arguments[0];
+                if (receiver && !ts.isSpreadElement(receiver) && globalTarget(receiver, checker)) {
+                    for (const source of node.arguments.slice(1)) {
+                        if (ts.isSpreadElement(source)) {
+                            const values = unwrapExpression(source.expression);
+                            if (ts.isArrayLiteralExpression(values)) {
+                                for (const value of values.elements)
+                                    if (ts.isSpreadElement(value))
+                                        mark(receiver, undefined);
+                                    else
+                                        mark(receiver, sourceKeys(value, checker));
+                            }
+                            else
+                                mark(receiver, undefined);
+                        }
+                        else
+                            mark(receiver, sourceKeys(source, checker));
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    for (const file of files)
+        if (!file.isDeclarationFile)
+            visit(file);
+    return written;
+}

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

@@ -0,0 +1,5 @@
+import type { RouteBinding } from './response-contract-route-analysis.mts';
+/** Whether requested protocol keys include a route binding, independent of its protocol variants. */
+export declare function protocolBindingRequested(binding: RouteBinding, requestedKeys?: ReadonlySet<string>): boolean;
+/** Maps one generated protocol key to its requested route spelling and exact variant suffix. */
+export declare function requestedProtocolKey(key: string, binding: RouteBinding, requestedKeys?: ReadonlySet<string>): string | undefined;

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

@@ -0,0 +1,45 @@
+import { routeShape } from './registered-route-catalog.mjs';
+/** Whether requested protocol keys include a route binding, independent of its protocol variants. */
+export function protocolBindingRequested(binding, requestedKeys) {
+    if (!requestedKeys)
+        return true;
+    return [...requestedKeys].some((key) => {
+        const requested = parseProtocolKey(key);
+        return requested && sameRoute(requested, binding);
+    });
+}
+/** Maps one generated protocol key to its requested route spelling and exact variant suffix. */
+export function requestedProtocolKey(key, binding, requestedKeys) {
+    if (!requestedKeys)
+        return key;
+    if (requestedKeys.size === 0)
+        return undefined;
+    const generated = parseProtocolKey(key);
+    if (!generated || !sameRoute(generated, binding))
+        return undefined;
+    const candidates = [];
+    for (const requestedKey of requestedKeys) {
+        const parsed = parseProtocolKey(requestedKey);
+        if (parsed?.suffix === generated.suffix && sameRoute(parsed, binding))
+            candidates.push({ key: requestedKey, parsed });
+    }
+    const exact = candidates.find((candidate) => candidate.parsed.base === generated.base);
+    return (exact ?? candidates.toSorted((left, right) => left.key.localeCompare(right.key))[0])?.key;
+}
+function parseProtocolKey(key) {
+    const suffixStart = key.indexOf('#');
+    const base = suffixStart < 0 ? key : key.slice(0, suffixStart);
+    const separator = base.indexOf(':');
+    if (separator <= 0)
+        return undefined;
+    return {
+        method: base.slice(0, separator),
+        routeTemplate: base.slice(separator + 1),
+        suffix: suffixStart < 0 ? '' : key.slice(suffixStart),
+        base,
+    };
+}
+function sameRoute(key, binding) {
+    return (key.method === binding.method &&
+        routeShape(key.routeTemplate) === routeShape(binding.routeTemplate));
+}

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

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mts';
+import { type HandlerBindings, type RouteBinding } from './response-contract-route-analysis.mts';
+export declare function sseCallerScope(functions: readonly ts.FunctionLikeDeclaration[], calls: readonly ts.CallExpression[], binding: RouteBinding, bindings: HandlerBindings, checker: ts.TypeChecker): {
+    paths: (ts.CallExpression | ts.NewExpression)[][];
+    contexts: Set<ts.Symbol>;
+    functions: ts.FunctionLikeDeclaration[];
+} | undefined;

package/dist/api-contract-discovery/protocol-sse-callers.mjs

@@ -0,0 +1,67 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { createProtocolCallbackValueResolver } from './protocol-callback-values.mjs';
+import { registeredHandler } from './protocol-callback-registration.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { enclosingFunction } from './protocol-marker-analysis.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { enclosingRouteBinding, } from './response-contract-route-analysis.mjs';
+export function sseCallerScope(functions, calls, binding, bindings, checker) {
+    const resolver = createProtocolCallbackValueResolver(checker);
+    const matches = calls.flatMap((call) => {
+        const fn = resolver.resolve(call.expression, new Map())?.node;
+        if (!fn ||
+            !functions.includes(fn) ||
+            !executableProtocolPath(call, checker))
+            return [];
+        const route = enclosingRouteBinding(call, checker, bindings, false);
+        return route?.method === binding.method && route.routeTemplate === binding.routeTemplate
+            ? [{ call, fn: fn }]
+            : [];
+    });
+    if (!matches.length)
+        return undefined;
+    const contexts = new Set();
+    const callerFunctions = new Set();
+    const paths = matches.map(({ call }) => {
+        const anchors = [call];
+        let fn = enclosingFunction(call);
+        let outer = fn;
+        while (fn) {
+            callerFunctions.add(fn);
+            let value = fn;
+            while (ts.isPropertyAssignment(value.parent) || ts.isObjectLiteralExpression(value.parent))
+                value = value.parent;
+            if (ts.isCallExpression(value.parent) || ts.isNewExpression(value.parent))
+                anchors.push(value.parent);
+            outer = fn;
+            fn = enclosingFunction(fn);
+        }
+        const name = outer && runtimeParameters(outer)[0]?.name;
+        const context = name && ts.isIdentifier(name) ? checker.getSymbolAtLocation(name) : undefined;
+        if (!outer ||
+            (name && !context) ||
+            !calls.some((node) => registeredHandler(node) &&
+                node.arguments.some((argument) => resolver.resolve(argument, new Map())?.node === outer)))
+            throw new Error('SSE helper must bind a registered caller context');
+        if (context)
+            contexts.add(context);
+        return anchors;
+    });
+    if (contexts.size > 1)
+        throw new Error('SSE helper has ambiguous caller contexts');
+    const context = [...contexts][0];
+    for (const { call, fn } of matches)
+        runtimeParameters(fn).forEach((parameter, index) => {
+            const argument = call.arguments[index];
+            const receiver = argument && expressionReceiver(argument, checker);
+            if (context &&
+                receiver?.root === context &&
+                receiver.path.length === 0 &&
+                !receiver.mutableAlias &&
+                ts.isIdentifier(parameter.name)) {
+                contexts.add(checker.getSymbolAtLocation(parameter.name));
+            }
+        });
+    return { paths, contexts, functions: [...callerFunctions] };
+}

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

@@ -0,0 +1,11 @@
+import ts from '../contract-schema/typescript-api.mts';
+import type { HandlerBindings, RouteBinding } from './response-contract-route-analysis.mts';
+export declare function sseEmission(call: ts.CallExpression, checker: ts.TypeChecker, calls: readonly ts.CallExpression[], binding: RouteBinding, bindings: HandlerBindings): {
+    write: ts.CallExpression;
+    receiver: import("./protocol-write-receiver.mts").WriteReceiver;
+    status: {
+        statusCodes?: readonly [number, ...number[]];
+        statusKnowledge: 'default' | 'explicit' | 'unknown';
+        unavailableReason?: string;
+    };
+};