@suss/adapter-typescript 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -1,209 +1,11 @@
 import { SourceFile, Node, FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, CallExpression, PropertyAccessExpression, TaggedTemplateExpression, Project, ImportDeclaration, Symbol, Expression, NewExpression, Identifier } from 'ts-morph';
-import { PackDeclarations, TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, configuredCallOption, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
-import { BehavioralSummary, MessageBusSemantics, DeployableUnit, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+import { TransparentWrapper, RawCondition, DiscoveryPattern, TerminalPattern, InputMappingPattern, EffectArg, CallOps, LanguageAdapter, PatternPack, ExtractorOptions, TimingReport, CacheDiagnostic, ExtractionReport, InvocationRecognizer, AccessRecognizer, RawCodeStructure, RawTerminal, RawBranch, configuredCallOption, RawDeclaredContract, ContractPattern, AstCapableOps, ResponsePropertyMapping } from '@suss/extractor';
+export { EmptyStage, ExtractionReport, PackFunnel, Timer, TimingReport, computeContentHash } from '@suss/extractor';
+import { MessageBusSemantics, DeployableUnit, UnfollowedCall, BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
 import { z } from 'zod';
+import { ExplainStats, WhyExplained, ValueLocation } from '@suss/resolution';
+export { ExplainStats, ValueLocation, WhyExplained } from '@suss/resolution';
 import { Proof, Atom } from '@suss/datalog';
-import { ResolutionExplanation } from '@suss/resolution';
-
-/**
- * cache.ts: the on-disk extraction cache.
- *
- * A run reuses the previous one's summaries whole when nothing
- * changed, and per file when some files did. The entry directory is
- * named after everything that has to agree before any reuse is sound:
- * schema version, adapter version and code hash, pack versions, the
- * extraction config stamp and the tsconfig path. Inside it, the
- * manifest records a stamp and content hash per file, each summary's
- * owning files, and per owning file the other files its walk read, so
- * a change to any of those re-extracts the owner instead of serving a
- * stale answer. The full design, including what per-file reuse can
- * and cannot promise, is in this package's README.
- */
-
-/** Reported by `lookup`: what the cache decided, and why. */
-interface CacheDiagnostic {
-    kind: "hit" | "miss" | "partial";
-    /**
-     * Reason the lookup missed (only set when kind === "miss").
-     * `key-changed` means the cache directory contains 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";
-    /** Set when kind === "partial". */
-    partial?: {
-        filesChanged: number;
-        filesRemoved: number;
-        rootsReused: number;
-        rootsReextracted: number;
-        rootsDeclined: number;
-        summariesReused: number;
-    };
-}
-/**
- * Result of a cache lookup. A hit gives back the whole summary set; a miss
- * says why, so a caller can render the reason.
- */
-type CacheLookup = {
-    kind: "hit";
-    summaries: BehavioralSummary[];
-    diagnostic: CacheDiagnostic;
-} | {
-    kind: "miss";
-    diagnostic: CacheDiagnostic;
-};
-
-/** 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 serve 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 it
-     * always discovers nothing, and that tells you nothing about whether
-     * it is working.
-     */
-    discovers: boolean;
-    /**
-     * Whether the pack has any 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.
-     */
-    gates: string[];
-    /**
-     * Gate specifiers that do not resolve from the tsconfig. Non-empty
-     * here usually means the target project's dependencies are not
-     * installed, which stops symbol-resolution packs while leaving
-     * textual-gate packs working, so the run half-succeeds in a way
-     * nothing else surfaces.
-     */
-    unresolvedGates: string[];
-    /** Files the pre-filter selected for this pack. */
-    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 tells you nothing, since it discovers nothing by
-     * design, and neither does its candidate-file count, 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
-     * comes after 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 credit this pack for finding them. */
-    summariesBound: number;
-    /**
-     * Bound summaries on the provider side of their boundary.
-     *
-     * Kept apart from the count below because a provider that produced
-     * no transitions is a different problem from a client that produced
-     * none.
-     */
-    providerSummaries: number;
-    /**
-     * Summaries with at least one transition, of any role. A provider's
-     * transitions say what it does with a request and a client's say what
-     * it expects back, so a pack whose summaries have none has bound
-     * something and described nothing either way.
-     */
-    summariesWithBehavior: number;
-    /**
-     * Where one of this pack's hooks threw. Every count above is a floor
-     * while this is non-empty.
-     */
-    failures: PackFailure[];
-    /**
-     * Registration helpers this pack's config asked for that no call in
-     * the run matched. The helper belongs to the project, so a spelling
-     * that matches nothing is a config mistake with no other symptom: the
-     * routes go missing and every count reads the same as a project
-     * without them.
-     */
-    helpersUnmatched: string[];
-    /**
-     * What the pack wrote as data rather than as code, or null for a pack
-     * written as a hand-rolled walk. This is the one thing in the funnel
-     * that no run produces: it is the pack's own shape, and it is here so
-     * the migration onto the declared surface can be measured.
-     */
-    declarations: PackDeclarations | null;
-}
-interface ExtractionReport {
-    /** Files in the tsconfig include set, or null when the caller supplied a Project. */
-    filesInProject: number | null;
-    /** Files the bootstrap loaded and the extract walked. */
-    filesWalked: number;
-    packs: PackFunnel[];
-    summaries: number;
-    /**
-     * Files whose exports the checker could not follow, so the run read
-     * them as exporting nothing.
-     *
-     * Without this the artifact cannot tell the two apart: a module whose
-     * barrel chain outran the call stack and a module that really does
-     * export nothing both produce no summaries and exit 0.
-     * Anything reachable only through these files is missing, and every
-     * count below is a floor while this is non-empty.
-     */
-    filesWithUnreadableExports: string[];
-    /**
-     * The first stage whose count was zero, when the run produced
-     * nothing. Null when the run produced summaries.
-     */
-    emptyStage: EmptyStage | null;
-    /**
-     * Reassigned names the run stated nothing for, because control flow
-     * decides which write a reader sees. Each is a value resolution the
-     * facts decline; the count across a large corpus says whether scoped
-     * reaching definitions is worth writing.
-     */
-    reassignedNamesUnstated: number;
-}
-type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery" | "assembly";
-/**
- * A pack's hook throwing on one file.
- *
- * The run continues 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 looks the same as a pack
- * that looked and found nothing.
- */
-interface PackFailure {
-    /** The hook that threw, called what a pack author would call 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 {
@@ -222,8 +24,8 @@ interface FileSetQuery {
  * files reach any of a set of packages, which a per-file import check
  * misses whenever a local barrel re-exports the SDK.
  *
- * Facts are extracted per file on demand and only along the module
- * edges a query follows, so cost tracks how indirect the code is.
+ * A query extracts the modules the rules ask for while answering it,
+ * so the files a question reads do not depend on what was asked before.
  */
 
 interface ExplainCallableOptions {
@@ -232,14 +34,6 @@ interface ExplainCallableOptions {
     /** How many derived nodes deep the proof walk goes; see `proofOf`. */
     maxDepth?: number;
 }
-/** What one witness re-evaluation cost, said rather than hidden. */
-interface ExplainStats {
-    /** Facts the demand walk had extracted, which the proof pass reran. */
-    baseFacts: number;
-    /** Facts the exhaustive pass derived on top of those. */
-    derivedFacts: number;
-    evaluateMs: number;
-}
 interface ExplainedResolution {
     /** The node the value comes down to. */
     target: Node;
@@ -263,7 +57,7 @@ declare class ResolutionStore {
      * extraction elsewhere cannot change an entry.
      */
     private readonly exportTables;
-    /** Files the most recent wave walk entered, for the memo to keep. */
+    /** Files the most recent query read, for the memo to keep. */
     private lastQueryWalked;
     private readonly declarations;
     private readonly graph;
@@ -286,10 +80,10 @@ declare class ResolutionStore {
     resolveCallableSources(value: Node, alsoFrom?: SourceFile): Node[];
     /**
      * The witness proof behind `resolveCallable`'s answer. Resolves the
-     * value first, which walks files and extracts facts in the usual
-     * waves, then re-evaluates the rules over those base facts under the
-     * witness algebra and rebuilds the proof of the answer. Null when
-     * the value does not resolve at all.
+     * value first, which extracts the files the question demands, then
+     * re-evaluates the rules over those base facts under the witness
+     * algebra and rebuilds the proof of the answer. Null when the value
+     * does not resolve at all.
      */
     explainCallable(value: Node, options?: ExplainCallableOptions): ExplainedResolution | null;
     resolveObject(value: Node): Node | null;
@@ -313,10 +107,8 @@ declare class ResolutionStore {
      */
     subjectCandidateCountOf(value: Node, importModule: string, importName: string): number;
     /**
-     * The single-answer policy over the written-value walk, then the
-     * origin check on the one candidate. A candidate failing the check
-     * is settled refusal rather than a reason to widen: its own file's
-     * import facts are already in, and more files only add candidates.
+     * The single-answer policy over the written-value chain, then the
+     * origin check on the one candidate.
      */
     private lookupSubjectConstruction;
     /**
@@ -348,8 +140,8 @@ declare class ResolutionStore {
         path: string[];
     }>;
     /**
-     * The batched form: one demand set, one derivation, one widening
-     * walk shared by every value. A discovery pass asks about every
+     * The batched form: one demand set, one derivation, one round of
+     * extraction shared by every value. A discovery pass asks about every
      * callee in a file, and per-value queries would re-pay demand
      * clearing and re-derivation once per call site.
      */
@@ -365,14 +157,22 @@ declare class ResolutionStore {
      */
     private sharedDeclarationFor;
     private lookupImportOrigins;
+    private lookupImportedNames;
+    private askAbout;
     /**
-     * Null tells the walk to keep widening. A value that landed in a
-     * package returns empty instead, because a library's own body is not
-     * here to read and widening would never find anything.
+     * Extract the seed files, then every module the rules ask for, until
+     * they ask for nothing new. The files a question reads are then fixed
+     * by the question alone, so its answer does not depend on what an
+     * earlier question left in the store.
      */
-    private lookupImportedNames;
-    private resolveByWaves;
-    private walkForAnswer;
+    private extractDemanded;
+    /**
+     * Module keys the rules are waiting on. Demand facts are cleared
+     * between queries, so the demand relations contain this query's
+     * alone; the unrestricted program has none, and follows the imports
+     * of the files read this round instead.
+     */
+    private demandedModules;
     /**
      * The question and the chain that settled it are dropped. The files
      * the query extracted stay, since the next query reads the same facts.
@@ -380,6 +180,13 @@ declare class ResolutionStore {
      */
     private forgetQuery;
     private wantValue;
+    private wantExportsOf;
+    /**
+     * Discovery walks the table in order, and the rounds derive it in
+     * the order files arrived. Deriving it again from the demand alone,
+     * over the loaded closure, orders it by the file's own statements.
+     */
+    private rederiveExportsOf;
     /**
      * File extraction only reaches values hanging off exports, and a query
      * can be rooted anywhere, so the queried value gets its own facts.
@@ -398,10 +205,10 @@ declare class ResolutionStore {
     /**
      * Read these files' facts now, before anything asks a question.
      *
-     * A query widens along the imports of the file it starts in, which
-     * is where a value's definition is. What a caller passed is the other
+     * A query follows the imports of the file it starts in, which is
+     * where a value's definition is. What a caller passed is the other
      * direction, so a question about a parameter is answered only by
-     * files the walk never reaches on its own.
+     * files the query never reaches on its own.
      */
     extractFiles(sourceFiles: Iterable<SourceFile>): void;
     /**
@@ -411,28 +218,23 @@ declare class ResolutionStore {
      */
     filesImportingTransitively(fileSets: ReadonlyArray<FileSetQuery>): ReadonlyArray<ReadonlySet<SourceFile>>;
     /**
-     * The calls behind a receiver that `matches` accepts, walked out in
-     * waves the way every question is. The wave ends as soon as one file
-     * yields a match, and the caller applies the single-answer policy to
-     * the set; the resolution README's anchor section says why the rules
-     * cannot rank a nearer call above a farther one.
+     * The calls behind a receiver that `matches` accepts. The caller
+     * applies the single-answer policy to the set; the resolution
+     * README's anchor section says why the rules cannot rank a nearer
+     * call above a farther one.
      */
     anchorCallsOf(value: Node, matches: (call: Node) => boolean): Node[];
     /**
      * Every name a module exports and the values behind each, with
-     * re-export chains flattened by the rules. The frontier follows
+     * re-export chains flattened by the rules. The demand follows
      * re-export targets only, so a barrel of barrels extracts its own
      * chain and nothing beside it, to any depth.
      */
     exportsOf(sourceFile: SourceFile): Map<string, Node[]>;
     private collectExports;
-    /** Module keys this file re-exports from, read off its own facts. */
-    private reExportTargetsOf;
     /**
-     * Null keeps the wave walk widening; any candidate at all ends it,
-     * since more files can only add candidates, never take one away. The
-     * single-answer policy stays with the callers: picking one of two
-     * would make the result depend on the order the facts came in.
+     * The single-answer policy stays with the callers: a value with two
+     * sources is something to say at the site, not something to pick from.
      */
     private lookupSources;
     private derive;
@@ -454,44 +256,6 @@ type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | M
  */
 declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
 
-/**
- * unfollowedCall.ts: naming the calls the reachable closure stops at.
- *
- * The closure follows a call by resolving its callee to a function with a
- * body. When that fails the edge is dropped, and a unit whose body is full
- * of dropped edges produces the same empty summary as a unit that does
- * nothing. This module says which kind of stop a call site is, and which
- * kinds are worth leaving a gap for.
- *
- * The README beside this file explains where that line is drawn, and why
- * a call into a dependency stays on the other side of it.
- */
-
-/**
- * Why the walk stopped.
- *
- * `noBody` states a shape and nothing else: a method on an interface, an
- * abstract method, an ambient declaration. `unsettledValue` is declared
- * as something other than a function, with something in it that could
- * not be read. `multipleSources` reaches two different functions, so no
- * single body can be followed. `outsideRun` is a declaration in a
- * dependency, whose source this run never read. `noDeclaration` is a
- * callee nothing declares, which is what a call on an untyped value
- * comes to. `callerSupplied` is a parameter of the function being
- * scanned, so the call runs whatever its caller handed in.
- * `multipleReceivers` is a registration whose receiver comes down to
- * more than one thing, so nothing says which one it registers on.
- */
-type UnfollowedReason = "noBody" | "unsettledValue" | "multipleSources" | "outsideRun" | "noDeclaration" | "callerSupplied" | "multipleReceivers";
-/** One call the walk met and could not follow. */
-interface UnfollowedCall {
-    /** The callee as the source writes it, `this.dao.getEditions` say. */
-    readonly callee: string;
-    readonly reason: UnfollowedReason;
-    /** How many things the walk reached where it needed one. */
-    readonly candidates?: number;
-}
-
 interface ClientCallSite {
     callExpression: CallExpression;
     /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
@@ -717,23 +481,6 @@ interface ExpandedRegistrations {
  */
 declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[], resolution?: ResolutionStore, mountPrefixes?: MountPrefixIndex, expandedElsewhere?: ExpandedRegistrations): DiscoveredUnit[];
 
-interface TimingReport {
-    totalMs: number;
-    phases: Array<{
-        label: string;
-        durationMs: number;
-        calls: number;
-    }>;
-}
-interface Timer {
-    /** Run `fn`, accumulate wall time under `label`, return its result. */
-    time<T>(label: string, fn: () => T): T;
-    /** Async variant: same accumulation rule. */
-    timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
-    /** Snapshot of all accumulated phases, ordered by total time descending. */
-    report(): TimingReport;
-}
-
 /**
  * Nested function nodes a pack claimed as sub-units. The unit-body
  * walkers stop at these so the sub-unit's behavior isn't double-counted
@@ -741,6 +488,21 @@ interface Timer {
  */
 type DescentBarriers = ReadonlySet<Node>;
 
+/**
+ * invocationEffects.ts: capture every call in a unit's body as an
+ * `invocation` RawEffect, wherever the call is written: a statement of
+ * its own, an argument, an element of a literal, an arm of a ternary,
+ * the receiver of a method chain. Which calls a summary keeps is
+ * decided in assembly by node identity, so no position needs a rule of
+ * its own here.
+ *
+ * The walk descends into nested arrows and function expressions, since
+ * their calls are behavior of the enclosing unit, and stops at named
+ * nested declarations, pack-declared sub-unit boundaries and
+ * decorators. The README beside this file says how the effects are
+ * ordered and what `async` means.
+ */
+
 /**
  * Context handed to TypeScript-adapter access recognizers: sister
  * to TsInvocationRecognizerContext but for property-access nodes.
@@ -1193,23 +955,7 @@ interface WhySessionOptions {
     /** The project root, which paths in every answer come out relative to. */
     dir: string;
 }
-/** A value or function said the way an answer prints it. */
-interface ValueLocation {
-    name: string;
-    /** Relative to the session root when under it, absolute otherwise. */
-    file: string;
-    line: number;
-}
-interface WhyExplained {
-    explanation: ResolutionExplanation;
-    /** The chain's atoms, each said in source terms. */
-    chain: string[];
-    /** The chain and its reasons as printable lines. */
-    lines: string[];
-    target: ValueLocation;
-    stats: ExplainStats;
-}
-declare class WhySession {
+declare class TypeScriptWhySession {
     private readonly project;
     private readonly store;
     private readonly root;
@@ -1254,87 +1000,6 @@ declare function exportedDeclarationsOf(sourceFile: SourceFile, resolution: Reso
  */
 declare function resolveAliasedSymbol(symbol: Symbol): Symbol | undefined;
 
-/**
- * Checks that tell you a pack is probably not working.
- *
- * The funnel shows where a run's counts dropped to zero. These checks
- * ask something narrower of each pack on its own: did this pack lose
- * everything at some stage, when the stage before it had something?
- *
- * A pack that finds nothing in a codebase that does not use its library
- * is working correctly, so a count of zero on its own is never the
- * signal. What makes zero a signal is the count before it. A pack whose
- * import gate picked forty files and whose discovery then found no unit
- * in any of them said "look here" and failed to look. Every later stage
- * works the same way, which is why these checks are one comparison run
- * over a list of pairs rather than one check written per stage.
- */
-
-/** One thing that looks wrong, reported the way the dogfood invariants are. */
-interface HealthViolation {
-    label: string;
-    detail: string;
-}
-interface HealthCheck {
-    /** The property being checked, as something either true or false. */
-    name: string;
-    /**
-     * The short word this check reports under, kebab-case.
-     *
-     * It is the first column of every line the check prints, so a reader
-     * works out what it means once and recognises it after that. `name`
-     * is written as an assertion and would read backwards over a list of
-     * things failing it.
-     */
-    code: 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[];
-}
-/**
- * What one pack paid for what it matches.
- *
- * Expressiveness is bought link by link, and #542 asks for the price to
- * be printed. A pack with every link written as data runs on any
- * adapter with the executor ops. A link written as a function runs only
- * where its own language does, and one that reads the syntax tree is
- * the floor. All three are allowed, and this says which is which.
- */
-interface PackGradient {
-    pack: string;
-    /** Links written as data, across every declaration. */
-    dataLinks: number;
-    /** Links written as a function, as "declaration.question". */
-    functionLinks: string[];
-    /** Links whose function reads the adapter's own syntax tree. */
-    astLinks: string[];
-    /** Declarations shipped without a line of code to run against them. */
-    withoutExample: string[];
-}
-/**
- * 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. It is required because
- * no single choice suits every caller: a CLI run prints what the person
- * who started it can act on, while a run a pack author is reading wants
- * both kinds.
- */
-declare function formatPackHealth(checks: ReadonlyArray<HealthCheck>, audiences: ReadonlyArray<HealthCheck["audience"]>): string;
-
 /**
  * Parse a ts-morph Expression into a structured Predicate.
  * Returns null when the expression can't be decomposed cleanly.
@@ -1580,35 +1245,30 @@ declare function createTsSubUnitContext(): TsSubUnitContext;
  */
 declare function workspaceRootFor(anchor: string): string;
 
-declare const ADAPTER_VERSION = "0.2.1";
 /**
- * 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
- * locate a file gets the same "no stamp" result as a run from source
- * rather than a hash of a shorter list.
+ * version.ts: this adapter's own half of the cache key.
  *
- * The caller resolves the paths, because where a specifier resolves to
- * depends on which package is asking.
+ * `ADAPTER_VERSION` is the hand-bumped semver. Bump it on any change
+ * that affects extraction output: IR shape, discovery semantics,
+ * terminal classification, anything that would invalidate previously
+ * cached summaries. `createAdapterStamp` (from `@suss/extractor`) folds
+ * it together with a hash of this adapter's own loaded code, so a
+ * rebuilt dev build invalidates the cache even when nobody remembered
+ * to bump the constant. See that package's README for the full design.
  */
-declare function computeContentHash(paths: readonly string[]): string;
+
+declare const ADAPTER_VERSION = "0.2.1";
 /**
  * Compute a cache-friendly identity for an adapter+packs combination.
- * Stable across processes given the same inputs; bumps when any pack
- * 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 as much in the digest rather than leaving the
- * adapter out of it. Nothing writes under that digest today, and a key
- * that says "source" cannot be mistaken for one built from the code.
  */
 declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
     name: string;
     version?: string;
 }>): string;
 
-export { ADAPTER_VERSION, type Accessed, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExplainCallableOptions, type ExplainStats, type ExplainedResolution, type ExtractionReport, type FoundTerminal, type FunctionRoot, type HealthCheck, type HealthViolation, type ImportScanOptions, type ObservedStubCall, type PackFunnel, type PackGradient, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type Timer, type TimingReport, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, type ValueLocation, type WhyExplained, WhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, computeContentHash, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, evaluatePackHealth, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, formatPackHealth, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };
+export { ADAPTER_VERSION, type Accessed, type ClientCallSite, type ConfiguredCallContext, type ConfiguredCallRead, type ConfiguredCallSpec, type ContractReadResult, type DiscoveredUnit, type ExplainCallableOptions, type ExplainedResolution, type FoundTerminal, type FunctionRoot, type ImportScanOptions, type ObservedStubCall, type ReadNameOptions, ResolutionStore, type StubCallEvidence, type StubEvidenceOptions, type TsDiscoveryContext, type TsInvocationRecognizerContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, TypeScriptWhySession, type WhySessionOptions, accessContextFor, buildProjectHelperIndex, callOpsFor, collectAncestorBranches, collectClientFieldAccesses, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, exportedDeclarationsOf, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, functionTargetOf, importDeclarationsOf, importedNamesOf, importedRootsOf, invocationContextFor, isImportedFrom, methodDeclaredIn, namedImportsOf, parseConditionExpression, readConfiguredCall, readContract, readContractForClientCall, readName, resolveAliasedSymbol, resolveSubject, rootIdentifier, stubEvidence, stubEvidenceIn, workspaceRootFor };