@suss/adapter-typescript 0.0.2 → 0.1.1

package/dist/index.d.ts

@@ -1,54 +1,27 @@
-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 { SourceFile, Node, 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, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 
-/**
- * Reported by `lookup`. Surfaces what the cache decided and, for
- * partial-hits, the file-churn breakdown so callers can render a
- * diagnostic.
- */
+/** Reported by `lookup`: what the cache decided, and why. */
 interface CacheDiagnostic {
-    kind: "hit" | "partial-hit" | "miss";
-    /** Reason the lookup missed (only set when kind === "miss"). */
-    missReason?: "no-manifest" | "schema-mismatch" | "packs-changed" | "tsconfig-changed";
-    /**
-     * Counts describing the file churn that produced a partial hit.
-     * Only populated when kind === "partial-hit".
-     */
-    partial?: {
-        /** Cached summaries whose location.file is in the unchanged set. */
-        reusedSummaries: number;
-        /** Files the adapter needs to re-extract per-file from. */
-        filesToReExtract: number;
-        /** Files added to the include set since the cached run. */
-        addedFiles: number;
-        /** Files removed from the include set since the cached run. */
-        removedFiles: number;
-        /** Files whose mtime/size differs (excludes added/removed). */
-        changedFiles: number;
-    };
+    kind: "hit" | "miss";
+    /**
+     * Reason the lookup missed (only set when kind === "miss").
+     * `key-changed` means the cache directory holds entries, but none
+     * under this run's schema, adapter, packs and tsconfig path.
+     * `files-changed` means the include set is not the one the entry
+     * was written from.
+     */
+    missReason?: "no-manifest" | "key-changed" | "tsconfig-changed" | "files-changed";
 }
 /**
- * Result of a cache lookup. The adapter dispatches on `kind`:
- *
- *   - "hit"          — the entire summary set is valid; return it
- *                      verbatim, skip extraction.
- *   - "partial-hit"  — `kept` is correct as far as their location.file
- *                      went; re-extract `filesToExtract` per-file and
- *                      re-run the closure / rethrow passes over the
- *                      merged set.
- *   - "miss"         — manifest absent or coarse keys (schema, packs,
- *                      tsconfig) changed; full re-extract.
+ * Result of a cache lookup. A hit carries the whole summary set; a miss
+ * says why, so a caller can render the reason.
  */
 type CacheLookup = {
     kind: "hit";
     summaries: BehavioralSummary[];
     diagnostic: CacheDiagnostic;
-} | {
-    kind: "partial-hit";
-    kept: BehavioralSummary[];
-    filesToExtract: string[];
-    diagnostic: CacheDiagnostic;
 } | {
     kind: "miss";
     diagnostic: CacheDiagnostic;
@@ -57,6 +30,25 @@ type CacheLookup = {
 /** One pack's path through the funnel. */
 interface PackFunnel {
     pack: string;
+    /**
+     * What the pack calls this build of itself, or null when it declares
+     * nothing. The cache keys on it, so a pack that never changes its
+     * stamp can answer a later run with an earlier build's results.
+     */
+    version: string | null;
+    /**
+     * Whether the pack looks for units of its own at all. A pack made
+     * only of recognisers contributes effects to units other packs found,
+     * so discovering nothing is how it always behaves and says nothing
+     * about whether it is working.
+     */
+    discovers: boolean;
+    /**
+     * Whether the pack carries recognisers. Those fire inside units other
+     * packs discovered, so a pack made only of them contributes effects
+     * and never a summary.
+     */
+    recognizes: boolean;
     /**
      * Import specifiers that make a file relevant to this pack. Empty
      * for an ungated pack, which walks every file.
@@ -74,8 +66,51 @@ interface PackFunnel {
     candidateFiles: number;
     /** Units discovered across those files. */
     unitsDiscovered: number;
+    /**
+     * Unit bodies any pack walked in the files this pack's gate selected.
+     *
+     * This is what a recogniser pack had the chance to fire on. Its own
+     * discovery count says nothing, since it discovers nothing by design,
+     * and its candidate-file count says nothing either, because a
+     * recogniser only runs where some pack found a unit to walk.
+     */
+    unitsInGatedFiles: number;
+    /** Effects this pack's recognisers returned. */
+    effectsRecognized: number;
+    /**
+     * Units this pack kept. A unit an earlier pack already claimed is
+     * dropped here, so a pack can discover plenty and keep none when it
+     * sits behind a pack that recognises the same code.
+     */
+    unitsClaimed: number;
+    /**
+     * Units this pack discovered twice over. Cross-pack dedup is the
+     * point of the claim set, but a pack colliding with itself means its
+     * own discovery patterns overlap and one of the two is being thrown
+     * away without anybody deciding which.
+     */
+    selfCollisions: number;
     /** Summaries built from those units. */
     summariesProduced: number;
+    /** Summaries in the finished run that name this pack as what recognised them. */
+    summariesBound: number;
+    /**
+     * Bound summaries on the provider side of their boundary.
+     *
+     * Transitions say what a unit does with a request, which is a
+     * question only a provider answers. A consumer records what it reads
+     * back from the response instead, and that lives on the summary's
+     * metadata. Measuring a client pack against transitions would report
+     * every working one as extracting nothing.
+     */
+    providerSummaries: number;
+    /** Provider summaries carrying at least one transition. */
+    summariesWithBehavior: number;
+    /**
+     * Where one of this pack's hooks threw. Every count above is a floor
+     * while this is non-empty.
+     */
+    failures: PackFailure[];
 }
 interface ExtractionReport {
     /** Files in the tsconfig include set, or null when the caller supplied a Project. */
@@ -91,6 +126,165 @@ interface ExtractionReport {
     emptyStage: EmptyStage | null;
 }
 type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery" | "assembly";
+/**
+ * A pack's hook throwing on one file.
+ *
+ * The run carries on with the other files, so every count for that pack
+ * afterwards is a floor rather than a total. Somebody reading those
+ * counts has to be told, or a pack that broke reads the same as a pack
+ * that looked and found nothing.
+ */
+interface PackFailure {
+    /** The hook that threw, named as a pack author would know it. */
+    hook: string;
+    /** The file the pack was reading. */
+    file: string;
+    message: string;
+}
+
+/** One question: do these files reach any of these packages. */
+interface FileSetQuery {
+    sourceFiles: ReadonlyArray<SourceFile>;
+    packages: ReadonlyArray<string>;
+}
+
+declare class ResolutionStore {
+    private readonly db;
+    private readonly table;
+    private readonly fullyExtracted;
+    private readonly seededValues;
+    private readonly importedNames;
+    private readonly graph;
+    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;
+    /**
+     * The expression `value` is written as, or null. Unlike the other two
+     * questions this one does not care what kind of expression it lands
+     * on, so it answers for values that are neither functions nor
+     * objects: a GraphQL document held in a named constant in another
+     * file comes back as the template literal or tag call that built it.
+     *
+     * A value the code computes has no written form to report, so the
+     * answer is the computing expression itself and the caller gets
+     * nothing it can use, which is the point.
+     */
+    resolveWrittenValue(value: Node): Node | null;
+    /**
+     * The names from `modules` this value stands for. A value stands for
+     * a library name two ways, and a caller asking which library concept
+     * something is wants both:
+     *
+     *   - it is that name, under whatever local spelling. `import
+     *     { Controller as Resource }` makes `Resource` the library's
+     *     `Controller`.
+     *   - calling it calls that name. A project decorator written as
+     *     `(path) => Controller(path)` marks a controller, and so does
+     *     one written as `applyDecorators(Controller(path))`.
+     *
+     * Several names is the normal answer rather than an ambiguity, since
+     * a wrapper composing two library decorators applies both. The caller
+     * asks whether the name it cares about is among them.
+     *
+     * One wrapper is applied across hundreds of files, so the answer is
+     * memoized against the declaration it was asked about. Without that,
+     * every use site seeds a fresh value and pays another fixpoint.
+     */
+    importedNamesOf(value: Node, modules: string[]): string[];
+    /**
+     * The names from `modules` this value stands for, or null while the
+     * walk should keep widening.
+     *
+     * The distinction is what keeps the cost down. A value that has
+     * arrived at a package has nothing more to give, because a library's
+     * own body is not here to read, so a decorator from a library the
+     * caller did not ask about stops on the first wave rather than
+     * running out the import closure looking for a match it will never
+     * find. A value that has only arrived at another file in the project
+     * keeps going, since the wrapper it names is declared somewhere the
+     * walk has not reached yet.
+     */
+    private lookupImportedNames;
+    private resolveByWaves;
+    private walkForAnswer;
+    /**
+     * The answer has been read, so the question and the chain that
+     * answered it can go. What the query extracted stays: files are the
+     * expensive part and the next query reads the same facts.
+     *
+     * Nothing is owed after this. The rules have seen every fact the
+     * database holds and concluded what the demand still present asks
+     * for, which is none, so the next query starts from its own asking
+     * fact.
+     */
+    private forgetQuery;
+    /**
+     * Somebody asked about this value, which is what the rules follow
+     * chains for. Separate from `seedValue`, which only speaks for values
+     * that are expressions; a caller can ask about a declaration too, and
+     * the answer is still owed.
+     */
+    private wantValue;
+    /**
+     * 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;
+    /**
+     * Reaching two different expressions means the rules cannot tell
+     * which one the value is written as, and the same reasoning applies
+     * as for the other two questions: ambiguity is nothing. The value
+     * itself is not an answer, or every identifier would answer with
+     * itself the moment its chain went nowhere.
+     */
+    private lookupWritten;
+    /**
+     * For each set of files and packages, which of those files reach any
+     * of those packages through their imports, following project-local
+     * re-export chains.
+     */
+    filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
+    /**
+     * 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. */
+    private derive;
+    /**
+     * The second column of an answer relation, for the value asked about.
+     * The database indexes a column the first time somebody looks it up
+     * and keeps that index as facts arrive, so this is a map hit and the
+     * answers a query never asks about cost nothing.
+     */
+    private answersFor;
+    /** The trailing pair of a three-column answer relation, joined. */
+    private answerPairsFor;
+    /** Emit a file's facts, unless some earlier query already did. */
+    private extractFile;
+}
 
 type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
 /**
@@ -98,11 +292,6 @@ type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | M
  * 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;
@@ -110,12 +299,38 @@ interface ClientCallSite {
     methodName: string | null;
 }
 interface DiscoveredUnit {
-    func: FunctionRoot;
+    /**
+     * The function this unit is. Null when a registration announced a
+     * boundary and the handler it names comes from outside everything
+     * this run reads, in which case `announcedAt` is where the unit is
+     * and the summary describes a boundary with nothing behind it.
+     */
+    func: FunctionRoot | null;
+    /**
+     * The registration that announced a boundary whose handler was never
+     * reached. Set exactly when `func` is null, and the unit's location.
+     */
+    announcedAt?: Node;
     kind: string;
     name: string;
     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 +416,19 @@ 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;
+    };
+    /** The thing that gets deployed and runs this unit, when known. */
+    deployableUnit?: DeployableUnit;
     /**
      * Metadata merged onto the assembled summary's `metadata` field.
      * Populated when a pack's `discoverUnits` callback stamps provenance
@@ -214,7 +442,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;
@@ -240,7 +468,7 @@ interface Timer {
  */
 type DescentBarriers = ReadonlySet<Node>;
 
-declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, filePath: string, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawCodeStructure;
+declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawCodeStructure;
 interface TypeScriptAdapterConfig {
     tsConfigFilePath?: string;
     project?: Project;
@@ -284,13 +512,15 @@ interface TypeScriptAdapterConfig {
      */
     onExtractionReport?: (report: ExtractionReport) => void;
     /**
-     * On-disk cache directory for the coarse-key extraction cache.
-     * Pass an absolute path; defaults to `.suss/cache/` next to the
-     * tsconfig (or under cwd when no tsconfig path is supplied).
-     * Pass `null` to disable caching entirely. The cache stores one
-     * `manifest.json` keyed against (adapter version, pack versions,
-     * sorted file mtime/size stamps); on a warm run with no changes
-     * the lookup is stat-only and skips extraction.
+     * On-disk cache directory for the extraction cache. Pass an absolute
+     * path; defaults to `.suss/cache/` next to the tsconfig, and to no
+     * cache at all when no tsconfig path is supplied. Pass `null` to turn
+     * caching off. A warm run with nothing changed costs one stat per
+     * file and returns the previous run's summaries whole.
+     *
+     * A process that loaded the adapter from source gets no cache
+     * whatever this says, because a key made there cannot tell one build
+     * of the adapter from another.
      */
     cacheDir?: string | null;
 }
@@ -308,20 +538,68 @@ 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;
+    /**
+     * A test that also has to hold for this terminal to be the one that
+     * fires, on top of whatever the path to it required.
+     *
+     * One call site answers with more than one status when the status is
+     * written as a choice, and the arms are told apart by nothing else:
+     * they share a node, so the path engine gives them the same
+     * conditions.
+     */
+    whenAlso?: RawCondition;
+}
+
+/**
+ * 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 +612,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;
@@ -348,7 +673,7 @@ interface ContractReadResult {
  * Returns null if the handler wasn't registered with a contract or the contract
  * can't be resolved.
  */
-declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern): ContractReadResult | null;
+declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern, framework: string): ContractReadResult | null;
 /**
  * Resolve the contract for a consumer call site.
  *
@@ -356,7 +681,7 @@ declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern): C
  * call to find the contract, then extracts the endpoint definition for the
  * matched method name (e.g. "getUser").
  */
-declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern): ContractReadResult | null;
+declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern, framework: string): ContractReadResult | null;
 
 interface TsDiscoveryContext {
     /** Full filesystem path of the source file. Useful for excluding
@@ -379,6 +704,32 @@ interface TsDiscoveryContext {
         func: FunctionRoot;
         isDefault: boolean;
     }>;
+    /**
+     * For an export the project builds by calling a factory, the string a
+     * property of that call's config object holds:
+     * `export const handler = makeWidgetHandler({ subject: "a.b" }, ...)`
+     * with `{ property: "subject" }` answers `"a.b"`.
+     *
+     * Which function was called and which argument carried the config are
+     * questions the caller does not have to answer. Every object argument
+     * is read. Naming the callee or fixing the argument position narrows
+     * that, for a project whose factories would otherwise collide.
+     *
+     * Two arguments holding the property under different values answers
+     * null, since nothing says which one was meant.
+     *
+     * 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 +742,51 @@ interface TsDiscoveryContext {
      */
     hasJsxReturn(func: FunctionRoot): boolean;
 }
-declare function createTsDiscoveryContext(): TsDiscoveryContext;
+declare function createTsDiscoveryContext(resolution?: ResolutionStore): TsDiscoveryContext;
+
+/** One thing that looks wrong, in the same shape the dogfood invariants report. */
+interface HealthViolation {
+    label: string;
+    detail: string;
+}
+interface HealthCheck {
+    /** The property, as something that either holds or does not. */
+    name: string;
+    /**
+     * The heading printed when this check finds something.
+     *
+     * The property reads as an assertion, so printing `name` above the
+     * violations of it says "no pack collides with itself" and then lists
+     * a pack colliding with itself.
+     */
+    whenBroken: string;
+    /**
+     * Who the finding is addressed to.
+     *
+     * A `run` check found something about the code in front of it, and
+     * the person who started the run can do something about it: drop a
+     * pack, install a dependency, open an issue with the file that
+     * broke. A `pack` check found something about how a pack was built,
+     * which only whoever ships that pack can fix. Printing the second
+     * kind on every run would teach people to skim past the first.
+     */
+    audience: "run" | "pack";
+    violations: HealthViolation[];
+}
+/**
+ * Run every health check over one extraction report and return what
+ * fired, grouped by which check caught it.
+ */
+declare function evaluatePackHealth(report: ExtractionReport): HealthCheck[];
+/**
+ * The health checks that fired, as lines for a terminal.
+ *
+ * `audiences` is who the caller is printing for, and it is required
+ * because there is no answer that suits every caller: a CLI run prints
+ * what the person who started it can act on, and a run whose reader is
+ * a pack author wants both.
+ */
+declare function formatPackHealth(checks: ReadonlyArray<HealthCheck>, audiences: ReadonlyArray<HealthCheck["audience"]>): string;
 
 /**
  * Parse a ts-morph Expression into a structured Predicate.
@@ -405,6 +800,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,33 +902,35 @@ interface TsJsxAttributeLocation {
 }
 declare function createTsSubUnitContext(): TsSubUnitContext;
 
-interface FoundTerminal {
-    node: Node;
-    terminal: RawTerminal;
-}
-
+declare const ADAPTER_VERSION = "0.2.0";
 /**
- * Walk every descendant of `func` and try each pattern in order (first match
- * wins per node). Returns all matched terminals across the whole function.
+ * Content hash of the given files, in the order they arrive. Empty when
+ * the list is empty or a file cannot be read, so a caller that could not
+ * place a file gets the same "no stamp" answer as a run from source
+ * rather than a hash of a shorter list.
  *
- * 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`.
+ * The caller resolves the paths, because who a specifier resolves to
+ * depends on which package is asking.
  */
-declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers): FoundTerminal[];
-
-declare const ADAPTER_VERSION = "0.1.0";
+declare function computeContentHash(paths: readonly string[]): string;
 /**
  * Compute a cache-friendly identity for an adapter+packs combination.
  * Stable across processes given the same inputs; bumps when any pack
- * declares a new version, the adapter version changes, or the loaded
- * adapter dist file changes (dev-mode rebuild auto-invalidation).
+ * arrives with a new version stamp, the adapter version changes, or the
+ * loaded adapter dist file changes (dev-mode rebuild auto-invalidation).
+ *
+ * A pack's stamp is whatever the caller that loaded the pack put there.
+ * The adapter takes packs as plain objects and cannot tell where one
+ * came from, so folding the config and the code into the stamp is the
+ * loader's job.
+ *
+ * A source run says so in the digest rather than leaving the adapter
+ * out of it. Nothing writes under that digest today, and a key that
+ * names the mode cannot be mistaken for a key that named the code.
  */
 declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     name: string;
     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 HealthCheck, type HealthViolation, type PackFunnel, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, isImportedFrom, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, resolveSubject };