@suss/adapter-typescript 0.0.1 → 0.1.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Node, CallExpression, SourceFile, Project, Expression } from 'ts-morph';
-import { RawCondition, DiscoveryPattern, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, TerminalPattern, RawBranch, RawDeclaredContract, ContractPattern, ResponsePropertyMapping, RawTerminal } from '@suss/extractor';
-import { BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+import { Node, SourceFile, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Expression } from 'ts-morph';
+import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
+import { BehavioralSummary, MessageBusSemantics, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 
 /**
  * Reported by `lookup`. Surfaces what the cache decided and, for
@@ -92,17 +92,74 @@ interface ExtractionReport {
 }
 type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery" | "assembly";
 
+declare class ResolutionStore {
+    private readonly db;
+    private readonly table;
+    private readonly fullyExtracted;
+    private readonly seededValues;
+    private readonly gateAnswers;
+    private resolvedBySource;
+    private comesToBySource;
+    private stale;
+    constructor(wrappers?: TransparentWrapper[]);
+    /**
+     * The function `value` resolves to, or null when no chain reaches
+     * one. The result is a ts-morph node in whatever file the function
+     * actually lives.
+     *
+     * Facts come in waves: extract the file the value lives in, ask, and
+     * only widen to the files it imports when the answer is still
+     * missing. A value that resolves without leaving its own file costs
+     * one file of extraction, not the whole import closure.
+     */
+    resolveCallable(value: Node): Node | null;
+    /**
+     * The object literal `value` ends up being, or null. The route a
+     * registration call names often lives on a shared object built in
+     * another file, and this is how discovery reads it back.
+     */
+    resolveObject(value: Node): Node | null;
+    private resolveByWaves;
+    /**
+     * Facts for the queried value itself. File extraction only reaches
+     * values that hang off exports, and a query can be rooted anywhere:
+     * a registration call passes `routes.provision` as an argument, and
+     * nothing else ever emits facts for that expression.
+     */
+    private seedValue;
+    private lookupObject;
+    /**
+     * Whether `file` reaches any of `packages` through its imports,
+     * following project-local re-export chains.
+     *
+     * A walk rather than a rule: the answer is one boolean per file, and
+     * deriving the full reachable-module relation for every file in a
+     * large repo costs far more than the question is worth.
+     */
+    importsTransitively(sourceFile: SourceFile, packages: string[]): boolean;
+    /**
+     * The one function this value resolves to. Several rules can reach
+     * the same answer, which is fine, but reaching two different
+     * functions means the rules cannot tell which one the value is, and
+     * picking whichever landed in the relation first would make the
+     * answer depend on the order facts arrived in. Ambiguity is nothing.
+     */
+    private lookup;
+    /**
+     * Run the rules to fixpoint and index `resolves` by its source, so
+     * a lookup is a map hit rather than a scan of every derived tuple.
+     */
+    private derive;
+    /** Emit a file's facts, unless some earlier query already did. */
+    private extractFile;
+}
+
 type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
 /**
  * Public API — returns RawCondition[] with structured: null.
  * Use collectAncestorConditionInfos when you need the Expression nodes.
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
-/**
- * Public API — returns RawCondition[] with structured: null.
- * Use collectEarlyReturnConditionInfos when you need the Expression nodes.
- */
-declare function collectEarlyReturns(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
 
 interface ClientCallSite {
     callExpression: CallExpression;
@@ -116,6 +173,21 @@ interface DiscoveredUnit {
     callSite?: ClientCallSite;
     /** The discovery pattern that produced this unit. Set by discoverUnits. */
     pattern?: DiscoveryPattern;
+    /**
+     * Terminal patterns for this unit's body, when a discoverUnits
+     * callback attached them (`DiscoveredCustomUnit.terminals`). A pack
+     * whose units follow more than one output convention declares the
+     * common one at pack level and attaches the other per unit.
+     * `extractCodeStructure` falls back to the pack-level `terminals`
+     * when unset.
+     */
+    terminals?: TerminalPattern[];
+    /**
+     * Input mapping for this unit, when a discoverUnits callback attached
+     * one (`DiscoveredCustomUnit.inputMapping`). Falls back to the
+     * pack-level `inputMapping` when unset.
+     */
+    inputMapping?: InputMappingPattern;
     /**
      * Populated by `resolverMap`-style discovery (GraphQL code-first).
      * The adapter uses it to build a `graphql-resolver` binding directly,
@@ -201,6 +273,17 @@ interface DiscoveredUnit {
         method: string;
         path: string;
     };
+    /**
+     * Populated by a pack's `discoverUnits` callback for a message-bus
+     * consumer whose channel the code names (a handler factory whose
+     * config carries the expected subject). The adapter uses it to build
+     * a `message-bus` binding directly, which pairs with producers
+     * sending on the same channel.
+     */
+    channelInfo?: {
+        messageBus: MessageBusSemantics["messageBus"];
+        channel: string;
+    };
     /**
      * Metadata merged onto the assembled summary's `metadata` field.
      * Populated when a pack's `discoverUnits` callback stamps provenance
@@ -214,7 +297,7 @@ interface DiscoveredUnit {
  * Discover code units in `sourceFile` by running all patterns.
  * Deduplicates entries with the same function node and kind.
  */
-declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[]): DiscoveredUnit[];
+declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore): DiscoveredUnit[];
 
 interface TimingReport {
     totalMs: number;
@@ -308,20 +391,58 @@ interface TypeScriptAdapter {
 }
 declare function createTypeScriptAdapter(config: TypeScriptAdapterConfig): TypeScriptAdapter;
 
+interface FoundTerminal {
+    node: Node;
+    terminal: RawTerminal;
+    /**
+     * The return this terminal came from: a ReturnStatement, or the body
+     * of an arrow that returns without writing `return`. Absent when the
+     * terminal is not a return at all, as a throw is not.
+     *
+     * The matcher is the only thing that knows, because `node` is
+     * wherever the matcher stopped looking, which differs by matcher.
+     * Anything downstream that guessed instead got it wrong.
+     */
+    source?: Node;
+}
+
+/**
+ * Walk every descendant of `func` and try each pattern in order (first match
+ * wins per node). Returns all matched terminals across the whole function.
+ *
+ * Descends into nested function expressions / arrows so a unit whose
+ * terminal output is produced inside a Promise executor or `.then`
+ * callback (`res.json(data)` on the unit's own `res` parameter) is still
+ * discovered. Inside a nested function only escaping terminals are
+ * matched — see `NESTED_ESCAPING_MATCH_TYPES`.
+ */
+declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers): FoundTerminal[];
+
 /**
  * Extract all raw branches from a function, composing:
- *   1. findTerminals — locate terminal nodes
- *   2. collectEarlyReturnConditionInfos — prior guard clauses
- *   3. collectAncestorConditionInfos — enclosing branch conditions
- *   4. parseConditionExpression — Expression → Predicate
- *   5. extractInvocationEffects — bare expression-statement calls
- *      (Phase 1.5b — attaches to the default branch so handler /
- *      useEffect bodies carry their side-effect set)
+ *   1. findTerminals, to locate terminal nodes
+ *   2. computePathConditions, for the conditions on each path (CFG
+ *      enumeration; declined shapes degrade to sound
+ *      under-specification)
+ *   3. parseConditionExpression, turning an Expression into a Predicate
+ *   4. extractInvocationEffects, for bare expression-statement calls,
+ *      attached to the default branch so handler and useEffect bodies
+ *      carry their side-effect set
  *
  * `isDefault` is true when the branch has no conditions, or all
- * conditions come from early returns/throws.
+ * conditions come from early returns or throws.
  */
-declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawBranch[];
+/**
+ * The branches a function produces, alongside the terminals they came
+ * from. A caller that wants to know which returns went unclaimed needs
+ * the terminals, and searching for them a second time costs about as
+ * much as this whole pass.
+ */
+interface RawBranchResult {
+    branches: RawBranch[];
+    terminals: FoundTerminal[];
+}
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawBranchResult;
 
 /**
  * A Project covering `rootDir`, for a codebase with no tsconfig to read.
@@ -334,6 +455,53 @@ declare function createProjectWithoutTsconfig(rootDir: string): {
 /** The nearest tsconfig or jsconfig at or above `startDir`, or null. */
 declare function findNearestTsconfig(startDir: string): string | null;
 
+/**
+ * A call a project names as its own dispatcher.
+ *
+ * `receiver` is the type name, not the variable: a service holds its
+ * dispatcher in a field, a closure, or a constructor parameter, and
+ * only the type is stable across those.
+ */
+interface ConfiguredCallSpec {
+    /** Module the receiver's type is declared in. */
+    module: string;
+    /** Type name of the receiver, as exported from that module. */
+    receiver: string;
+    /** Method that performs the send. */
+    method: string;
+    /** Argument index carrying the subject. */
+    subjectArg: number;
+    /**
+     * Argument index carrying the message body. Left out when the
+     * method takes no single body argument (a batch method takes a
+     * list of entries), and then the read carries no body.
+     */
+    bodyArg?: number;
+}
+interface ConfiguredCallRead {
+    /** The subject the call names, always a string the source states. */
+    subject: string;
+    /** The body argument's extracted shape, or null when none applies. */
+    body: EffectArg | null;
+    /** Source text of the callee, for the effect's `callee` field. */
+    callee: string;
+}
+/** The parts of a recognizer context this helper needs. */
+interface ConfiguredCallContext {
+    sourceFile: SourceFile;
+    extractArgs(): EffectArg[];
+}
+/**
+ * Read `call` as the configured send, or answer null.
+ *
+ * A subject that is not a string the source states (a variable built
+ * at runtime, a template with substitutions, a computed key) answers
+ * null, and the pack emits nothing. Naming a channel we cannot read
+ * would pair a producer against the wrong consumer, which is worse
+ * than not seeing the producer at all.
+ */
+declare function readConfiguredCall(call: CallExpression, ctx: ConfiguredCallContext, spec: ConfiguredCallSpec): ConfiguredCallRead | null;
+
 interface ContractReadResult {
     declaredContract: RawDeclaredContract;
     boundaryBinding: BoundaryBinding | null;
@@ -379,6 +547,25 @@ interface TsDiscoveryContext {
         func: FunctionRoot;
         isDefault: boolean;
     }>;
+    /**
+     * For an export whose declaration is a call to one of `callees`,
+     * read the string a property of the call's config object holds:
+     * `export const handler = createEventHandler({ expected: "a.b" }, ...)`
+     * with `{ callees: ["createEventHandler"], argIndex: 0, property:
+     * "expected" }` answers `"a.b"`.
+     *
+     * The config argument is usually an object literal at the call site;
+     * a variable or import is followed to the literal it resolves to.
+     * `as const` and parentheses around the property value are peeled.
+     * Anything but a string literal underneath (a computed subject, a
+     * template, a call) answers null — the caller attaches nothing
+     * rather than guessing.
+     */
+    exportedCallConfigString(sourceFile: SourceFile, exportName: string, spec: {
+        callees: string[];
+        argIndex: number;
+        property: string;
+    }): string | null;
     /**
      * Walk a function's body for return statements whose value is a
      * JSX element / fragment / self-closing tag. Returns true on the
@@ -391,7 +578,7 @@ interface TsDiscoveryContext {
      */
     hasJsxReturn(func: FunctionRoot): boolean;
 }
-declare function createTsDiscoveryContext(): TsDiscoveryContext;
+declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
 
 /**
  * Parse a ts-morph Expression into a structured Predicate.
@@ -405,6 +592,8 @@ declare function createTsDiscoveryContext(): TsDiscoveryContext;
  */
 declare function parseConditionExpression(expr: Expression, depth?: number): Predicate | null;
 
+declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
+
 interface BranchFieldAccesses {
     /** Terminal location (start, end lines) — used to match back to transitions */
     terminalLocation: {
@@ -505,24 +694,7 @@ interface TsJsxAttributeLocation {
 }
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
-interface FoundTerminal {
-    node: Node;
-    terminal: RawTerminal;
-}
-
-/**
- * Walk every descendant of `func` and try each pattern in order (first match
- * wins per node). Returns all matched terminals across the whole function.
- *
- * Descends into nested function expressions / arrows so a unit whose
- * terminal output is produced inside a Promise executor or `.then`
- * callback (`res.json(data)` on the unit's own `res` parameter) is still
- * discovered. Inside a nested function only escaping terminals are
- * matched — see `NESTED_ESCAPING_MATCH_TYPES`.
- */
-declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers): FoundTerminal[];
-
-declare const ADAPTER_VERSION = "0.1.0";
+declare const ADAPTER_VERSION = "0.2.0";
 /**
  * Compute a cache-friendly identity for an adapter+packs combination.
  * Stable across processes given the same inputs; bumps when any pack
@@ -534,4 +706,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExtractionReport, type FoundTerminal, type FunctionRoot, type PackFunnel, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, collectEarlyReturns, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, parseConditionExpression, readContract, readContractForClientCall, resolveSubject };
+export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExtractionReport, type FoundTerminal, type FunctionRoot, type PackFunnel, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, isImportedFrom, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, resolveSubject };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Node, CallExpression, SourceFile, Project, Expression } from 'ts-morph';
-import { RawCondition, DiscoveryPattern, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, TerminalPattern, RawBranch, RawDeclaredContract, ContractPattern, ResponsePropertyMapping, RawTerminal } from '@suss/extractor';
-import { BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+import { Node, SourceFile, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, Project, Expression } from 'ts-morph';
+import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, EffectArg, RawDeclaredContract, ContractPattern, ResponsePropertyMapping } from '@suss/extractor';
+import { BehavioralSummary, MessageBusSemantics, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 
 /**
  * Reported by `lookup`. Surfaces what the cache decided and, for
@@ -92,17 +92,74 @@ interface ExtractionReport {
 }
 type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery" | "assembly";
 
+declare class ResolutionStore {
+    private readonly db;
+    private readonly table;
+    private readonly fullyExtracted;
+    private readonly seededValues;
+    private readonly gateAnswers;
+    private resolvedBySource;
+    private comesToBySource;
+    private stale;
+    constructor(wrappers?: TransparentWrapper[]);
+    /**
+     * The function `value` resolves to, or null when no chain reaches
+     * one. The result is a ts-morph node in whatever file the function
+     * actually lives.
+     *
+     * Facts come in waves: extract the file the value lives in, ask, and
+     * only widen to the files it imports when the answer is still
+     * missing. A value that resolves without leaving its own file costs
+     * one file of extraction, not the whole import closure.
+     */
+    resolveCallable(value: Node): Node | null;
+    /**
+     * The object literal `value` ends up being, or null. The route a
+     * registration call names often lives on a shared object built in
+     * another file, and this is how discovery reads it back.
+     */
+    resolveObject(value: Node): Node | null;
+    private resolveByWaves;
+    /**
+     * Facts for the queried value itself. File extraction only reaches
+     * values that hang off exports, and a query can be rooted anywhere:
+     * a registration call passes `routes.provision` as an argument, and
+     * nothing else ever emits facts for that expression.
+     */
+    private seedValue;
+    private lookupObject;
+    /**
+     * Whether `file` reaches any of `packages` through its imports,
+     * following project-local re-export chains.
+     *
+     * A walk rather than a rule: the answer is one boolean per file, and
+     * deriving the full reachable-module relation for every file in a
+     * large repo costs far more than the question is worth.
+     */
+    importsTransitively(sourceFile: SourceFile, packages: string[]): boolean;
+    /**
+     * The one function this value resolves to. Several rules can reach
+     * the same answer, which is fine, but reaching two different
+     * functions means the rules cannot tell which one the value is, and
+     * picking whichever landed in the relation first would make the
+     * answer depend on the order facts arrived in. Ambiguity is nothing.
+     */
+    private lookup;
+    /**
+     * Run the rules to fixpoint and index `resolves` by its source, so
+     * a lookup is a map hit rather than a scan of every derived tuple.
+     */
+    private derive;
+    /** Emit a file's facts, unless some earlier query already did. */
+    private extractFile;
+}
+
 type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
 /**
  * Public API — returns RawCondition[] with structured: null.
  * Use collectAncestorConditionInfos when you need the Expression nodes.
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
-/**
- * Public API — returns RawCondition[] with structured: null.
- * Use collectEarlyReturnConditionInfos when you need the Expression nodes.
- */
-declare function collectEarlyReturns(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
 
 interface ClientCallSite {
     callExpression: CallExpression;
@@ -116,6 +173,21 @@ interface DiscoveredUnit {
     callSite?: ClientCallSite;
     /** The discovery pattern that produced this unit. Set by discoverUnits. */
     pattern?: DiscoveryPattern;
+    /**
+     * Terminal patterns for this unit's body, when a discoverUnits
+     * callback attached them (`DiscoveredCustomUnit.terminals`). A pack
+     * whose units follow more than one output convention declares the
+     * common one at pack level and attaches the other per unit.
+     * `extractCodeStructure` falls back to the pack-level `terminals`
+     * when unset.
+     */
+    terminals?: TerminalPattern[];
+    /**
+     * Input mapping for this unit, when a discoverUnits callback attached
+     * one (`DiscoveredCustomUnit.inputMapping`). Falls back to the
+     * pack-level `inputMapping` when unset.
+     */
+    inputMapping?: InputMappingPattern;
     /**
      * Populated by `resolverMap`-style discovery (GraphQL code-first).
      * The adapter uses it to build a `graphql-resolver` binding directly,
@@ -201,6 +273,17 @@ interface DiscoveredUnit {
         method: string;
         path: string;
     };
+    /**
+     * Populated by a pack's `discoverUnits` callback for a message-bus
+     * consumer whose channel the code names (a handler factory whose
+     * config carries the expected subject). The adapter uses it to build
+     * a `message-bus` binding directly, which pairs with producers
+     * sending on the same channel.
+     */
+    channelInfo?: {
+        messageBus: MessageBusSemantics["messageBus"];
+        channel: string;
+    };
     /**
      * Metadata merged onto the assembled summary's `metadata` field.
      * Populated when a pack's `discoverUnits` callback stamps provenance
@@ -214,7 +297,7 @@ interface DiscoveredUnit {
  * Discover code units in `sourceFile` by running all patterns.
  * Deduplicates entries with the same function node and kind.
  */
-declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[]): DiscoveredUnit[];
+declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore): DiscoveredUnit[];
 
 interface TimingReport {
     totalMs: number;
@@ -308,20 +391,58 @@ interface TypeScriptAdapter {
 }
 declare function createTypeScriptAdapter(config: TypeScriptAdapterConfig): TypeScriptAdapter;
 
+interface FoundTerminal {
+    node: Node;
+    terminal: RawTerminal;
+    /**
+     * The return this terminal came from: a ReturnStatement, or the body
+     * of an arrow that returns without writing `return`. Absent when the
+     * terminal is not a return at all, as a throw is not.
+     *
+     * The matcher is the only thing that knows, because `node` is
+     * wherever the matcher stopped looking, which differs by matcher.
+     * Anything downstream that guessed instead got it wrong.
+     */
+    source?: Node;
+}
+
+/**
+ * Walk every descendant of `func` and try each pattern in order (first match
+ * wins per node). Returns all matched terminals across the whole function.
+ *
+ * Descends into nested function expressions / arrows so a unit whose
+ * terminal output is produced inside a Promise executor or `.then`
+ * callback (`res.json(data)` on the unit's own `res` parameter) is still
+ * discovered. Inside a nested function only escaping terminals are
+ * matched — see `NESTED_ESCAPING_MATCH_TYPES`.
+ */
+declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers): FoundTerminal[];
+
 /**
  * Extract all raw branches from a function, composing:
- *   1. findTerminals — locate terminal nodes
- *   2. collectEarlyReturnConditionInfos — prior guard clauses
- *   3. collectAncestorConditionInfos — enclosing branch conditions
- *   4. parseConditionExpression — Expression → Predicate
- *   5. extractInvocationEffects — bare expression-statement calls
- *      (Phase 1.5b — attaches to the default branch so handler /
- *      useEffect bodies carry their side-effect set)
+ *   1. findTerminals, to locate terminal nodes
+ *   2. computePathConditions, for the conditions on each path (CFG
+ *      enumeration; declined shapes degrade to sound
+ *      under-specification)
+ *   3. parseConditionExpression, turning an Expression into a Predicate
+ *   4. extractInvocationEffects, for bare expression-statement calls,
+ *      attached to the default branch so handler and useEffect bodies
+ *      carry their side-effect set
  *
  * `isDefault` is true when the branch has no conditions, or all
- * conditions come from early returns/throws.
+ * conditions come from early returns or throws.
  */
-declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawBranch[];
+/**
+ * The branches a function produces, alongside the terminals they came
+ * from. A caller that wants to know which returns went unclaimed needs
+ * the terminals, and searching for them a second time costs about as
+ * much as this whole pass.
+ */
+interface RawBranchResult {
+    branches: RawBranch[];
+    terminals: FoundTerminal[];
+}
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawBranchResult;
 
 /**
  * A Project covering `rootDir`, for a codebase with no tsconfig to read.
@@ -334,6 +455,53 @@ declare function createProjectWithoutTsconfig(rootDir: string): {
 /** The nearest tsconfig or jsconfig at or above `startDir`, or null. */
 declare function findNearestTsconfig(startDir: string): string | null;
 
+/**
+ * A call a project names as its own dispatcher.
+ *
+ * `receiver` is the type name, not the variable: a service holds its
+ * dispatcher in a field, a closure, or a constructor parameter, and
+ * only the type is stable across those.
+ */
+interface ConfiguredCallSpec {
+    /** Module the receiver's type is declared in. */
+    module: string;
+    /** Type name of the receiver, as exported from that module. */
+    receiver: string;
+    /** Method that performs the send. */
+    method: string;
+    /** Argument index carrying the subject. */
+    subjectArg: number;
+    /**
+     * Argument index carrying the message body. Left out when the
+     * method takes no single body argument (a batch method takes a
+     * list of entries), and then the read carries no body.
+     */
+    bodyArg?: number;
+}
+interface ConfiguredCallRead {
+    /** The subject the call names, always a string the source states. */
+    subject: string;
+    /** The body argument's extracted shape, or null when none applies. */
+    body: EffectArg | null;
+    /** Source text of the callee, for the effect's `callee` field. */
+    callee: string;
+}
+/** The parts of a recognizer context this helper needs. */
+interface ConfiguredCallContext {
+    sourceFile: SourceFile;
+    extractArgs(): EffectArg[];
+}
+/**
+ * Read `call` as the configured send, or answer null.
+ *
+ * A subject that is not a string the source states (a variable built
+ * at runtime, a template with substitutions, a computed key) answers
+ * null, and the pack emits nothing. Naming a channel we cannot read
+ * would pair a producer against the wrong consumer, which is worse
+ * than not seeing the producer at all.
+ */
+declare function readConfiguredCall(call: CallExpression, ctx: ConfiguredCallContext, spec: ConfiguredCallSpec): ConfiguredCallRead | null;
+
 interface ContractReadResult {
     declaredContract: RawDeclaredContract;
     boundaryBinding: BoundaryBinding | null;
@@ -379,6 +547,25 @@ interface TsDiscoveryContext {
         func: FunctionRoot;
         isDefault: boolean;
     }>;
+    /**
+     * For an export whose declaration is a call to one of `callees`,
+     * read the string a property of the call's config object holds:
+     * `export const handler = createEventHandler({ expected: "a.b" }, ...)`
+     * with `{ callees: ["createEventHandler"], argIndex: 0, property:
+     * "expected" }` answers `"a.b"`.
+     *
+     * The config argument is usually an object literal at the call site;
+     * a variable or import is followed to the literal it resolves to.
+     * `as const` and parentheses around the property value are peeled.
+     * Anything but a string literal underneath (a computed subject, a
+     * template, a call) answers null — the caller attaches nothing
+     * rather than guessing.
+     */
+    exportedCallConfigString(sourceFile: SourceFile, exportName: string, spec: {
+        callees: string[];
+        argIndex: number;
+        property: string;
+    }): string | null;
     /**
      * Walk a function's body for return statements whose value is a
      * JSX element / fragment / self-closing tag. Returns true on the
@@ -391,7 +578,7 @@ interface TsDiscoveryContext {
      */
     hasJsxReturn(func: FunctionRoot): boolean;
 }
-declare function createTsDiscoveryContext(): TsDiscoveryContext;
+declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
 
 /**
  * Parse a ts-morph Expression into a structured Predicate.
@@ -405,6 +592,8 @@ declare function createTsDiscoveryContext(): TsDiscoveryContext;
  */
 declare function parseConditionExpression(expr: Expression, depth?: number): Predicate | null;
 
+declare function isImportedFrom(identifier: Node, expectedModule: string): boolean;
+
 interface BranchFieldAccesses {
     /** Terminal location (start, end lines) — used to match back to transitions */
     terminalLocation: {
@@ -505,24 +694,7 @@ interface TsJsxAttributeLocation {
 }
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
-interface FoundTerminal {
-    node: Node;
-    terminal: RawTerminal;
-}
-
-/**
- * Walk every descendant of `func` and try each pattern in order (first match
- * wins per node). Returns all matched terminals across the whole function.
- *
- * Descends into nested function expressions / arrows so a unit whose
- * terminal output is produced inside a Promise executor or `.then`
- * callback (`res.json(data)` on the unit's own `res` parameter) is still
- * discovered. Inside a nested function only escaping terminals are
- * matched — see `NESTED_ESCAPING_MATCH_TYPES`.
- */
-declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers): FoundTerminal[];
-
-declare const ADAPTER_VERSION = "0.1.0";
+declare const ADAPTER_VERSION = "0.2.0";
 /**
  * Compute a cache-friendly identity for an adapter+packs combination.
  * Stable across processes given the same inputs; bumps when any pack
@@ -534,4 +706,4 @@ declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExtractionReport, type FoundTerminal, type FunctionRoot, type PackFunnel, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, collectEarlyReturns, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, parseConditionExpression, readContract, readContractForClientCall, resolveSubject };
+export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExtractionReport, type FoundTerminal, type FunctionRoot, type PackFunnel, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, isImportedFrom, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, resolveSubject };