@suss/extractor 0.21.1 → 0.22.1

package/dist/index.d.cts

@@ -1893,6 +1893,50 @@ declare function guardsHoldOn(preconditions: readonly RawCondition[] | undefined
  */
 declare function runsBefore(effectLine: number, terminalEndLine: number): boolean;
 
+/**
+ * moduleImports.ts: writing `metadata.moduleImports` on a summary set.
+ *
+ * Every adapter records the project files a summary's own file depends
+ * on, and a checker rebuilds the module graph from that field to find
+ * what runs inside a deployable unit. The adapters differ in where the
+ * edges come from (TypeScript resolves import declarations, Python
+ * resolves them through facts, Ruby has `require_relative` and constant
+ * references), so the stamp takes a lookup and leaves the source to them.
+ *
+ * The paths a lookup returns must be spelled the way `location.file` is,
+ * so both ends of the graph match. An empty list is stamped as one, which
+ * makes the file a leaf of the graph; undefined leaves the summary alone.
+ */
+
+declare function stampModuleImports(summaries: BehavioralSummary[], importsOf: (file: string) => Iterable<string> | undefined): void;
+
+/**
+ * moduleInit.ts: the raw structure for what a module does when it loads.
+ *
+ * A module's top-level statements run once, when it is first imported,
+ * and a service that reads its configuration there reads it there for
+ * good. Walking unit bodies alone never sees that read, so the read gets
+ * a unit of its own, one per file, named after the file, with no
+ * boundary. Attributing it to each handler in the file would report one
+ * read as several, and a file with no handler would still report nothing.
+ *
+ * The structure is one default branch whose terminal is `void`, because
+ * module initialization returns to nobody. Every adapter builds it the
+ * same way, so it lives here.
+ */
+
+interface ModuleInitOptions {
+    /** The unit name, which is the file's base name in every adapter. */
+    name: string;
+    file: string;
+    range: {
+        start: number;
+        end: number;
+    };
+    effects: Effect[];
+}
+declare function moduleInitStructure(options: ModuleInitOptions): RawCodeStructure;
+
 /**
  * Small helpers for pattern packs that are built the same way.
  *
@@ -2207,6 +2251,605 @@ interface LanguageAdapter {
     extractAll(): Promise<BehavioralSummary[]>;
 }
 
+/**
+ * adapterStamp.ts: the language-neutral half of an adapter's cache key.
+ *
+ * An adapter's own version.ts calls `createAdapterStamp` with its own
+ * `import.meta.url` and its hand-bumped version, and keeps the result for
+ * the life of the process. The stamp hashes the adapter's own dist file
+ * plus every analysis package it ships beside (this package,
+ * `@suss/resolution`, `@suss/datalog`, `@suss/behavioral-ir`), so a
+ * release that changes any of them invalidates an older cache, and a
+ * dev rebuild invalidates on its own with no version bump by hand.
+ * Running from source has no dist file to hash, and that mode declines
+ * to cache. The extraction cache's design is in this package's README.
+ */
+/**
+ * Whether this process can see the adapter's own code. `bundle` includes
+ * a hash that changes whenever the code does. `source` means nothing
+ * here could find it, so a cache key built from this stamp says nothing
+ * about the code that will produce the results.
+ */
+type AdapterCodeStamp = {
+    kind: "bundle";
+    hash: string;
+} | {
+    kind: "source";
+};
+/** What `createAdapterStamp` hands back to an adapter's own version.ts. */
+interface AdapterStamp {
+    /** The stamp for the running adapter, computed once per process. */
+    codeStamp(): AdapterCodeStamp;
+    /**
+     * Cache-friendly identity for this adapter plus its packs. 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).
+     */
+    packsDigest(packVersions: ReadonlyArray<{
+        name: string;
+        version?: string;
+    }>): string;
+    /**
+     * `cacheDir` unless this process loaded the adapter from source, where
+     * nothing can tell one build of it from another; then this returns
+     * null and, once per process, says why on stderr.
+     */
+    declineWhenRunFromSource(cacheDir: string | null): string | null;
+}
+/**
+ * Build the code stamp and packs digest for one adapter. `moduleUrl` has
+ * to be the calling module's own `import.meta.url`, so the stamp finds
+ * the dist file the adapter itself was loaded from rather than some
+ * other package's.
+ */
+declare function createAdapterStamp(config: {
+    moduleUrl: string;
+    version: string;
+}): AdapterStamp;
+/**
+ * The hash for a bundle directory: the bundle itself plus every analysis
+ * package that can be located. Empty when the directory has no bundle in
+ * it, which is what running from source looks like.
+ */
+declare function computeDistHashFrom(dir: string): string;
+/**
+ * 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.
+ *
+ * The caller resolves the paths, because where a specifier resolves to
+ * depends on which package is asking.
+ */
+declare function computeContentHash(paths: readonly string[]): string;
+/**
+ * Stamp for a set of project files a run reads without walking them: a
+ * SAM template, a workspace package.json. Both the paths and the
+ * content go in, so a file that moves counts as a change even when
+ * every byte in it stayed the same.
+ *
+ * A file that cannot be read stamps as absent rather than voiding the
+ * whole stamp, which is what `computeContentHash` does. These files
+ * belong to the project rather than to the installed tool: one of them
+ * being gone is a fact about the project the next run should notice,
+ * not a reason to stop telling runs apart.
+ */
+declare function projectFileStamp(paths: readonly string[]): string;
+/**
+ * The digest a run looks its cache entry up under. A pack may read
+ * project files that are not among the ones a run walks, a SAM template
+ * that decides which handlers exist for instance, so those belong in
+ * the key next to the pack's own config. Which files they are depends
+ * on the files this run walks, so the digest is settled per run rather
+ * than once per adapter.
+ */
+declare function runDigest(packsDigest: string, packs: ReadonlyArray<{
+    discoveryInputs?: (files: readonly string[]) => string[];
+}>, files: readonly string[]): string;
+
+/**
+ * The on-disk extraction cache, shared by every language adapter.
+ *
+ * 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 config file path. The manifest
+ * inside records a stamp and content hash per file, each summary's
+ * owning files, and per owning file the other files its walk read.
+ * An adapter attaches whatever it needs to a cached file's record
+ * through `meta`, which the cache stores and returns opaquely. The
+ * full design is in this package's README.
+ */
+
+/**
+ * How many keys' worth of entries a cache directory keeps. Two lets a
+ * pair of builds alternate (a branch switch, an adapter rebuild and a
+ * revert) without either losing its entry, and bounds a directory at
+ * twice one manifest.
+ */
+declare const MAX_ENTRIES = 2;
+/**
+ * What one walked file contributed to the run, and what its walk read.
+ * `deps` are the other files whose content went into this file's
+ * summaries; a change to any of them re-extracts this file. `claims`
+ * are the units this file's walk claimed, replayed before a partial
+ * run walks anything so precedence comes out the same. `meta` is
+ * whatever else the adapter needs to revalidate this file on a
+ * partial run (a route's mount prefixes, for instance); the cache
+ * never reads it. A file marked `cacheable: false` recorded a
+ * dependency the cache cannot pin to files, and is re-extracted on
+ * every partial run.
+ */
+interface RootRecord<Meta = unknown> {
+    path: string;
+    cacheable: boolean;
+    deps: string[];
+    claims: {
+        key: string;
+        pack: string;
+    }[];
+    meta: Meta;
+    /** Packs that applied to the file, re-checked on a partial run. */
+    packs: string[];
+}
+/**
+ * Which files each summary belongs to. `owners[i]` lists the walked
+ * files whose reuse keeps `summaries[i]` alive; an empty list marks a
+ * run-level summary that a partial run always recomputes.
+ */
+interface CacheAttribution<Meta = unknown> {
+    roots: RootRecord<Meta>[];
+    owners: string[][];
+}
+/** 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 config path.
+     * `files-changed` means the include set is not the one the entry
+     * was written from.
+     */
+    missReason?: "no-manifest" | "key-changed" | "config-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;
+};
+/**
+ * What a `files-changed` miss can still reuse. `validRoots` is the
+ * cache's own verdict from hashes and recorded dependencies; the
+ * caller may demote further (a mount prefix that no longer matches)
+ * before calling `reuse`. `reuse` returns the summaries owned by at
+ * least one surviving root, in stored order, with their owners, so
+ * the caller can merge them and write the result back.
+ */
+interface PartialPlan<Meta = unknown> {
+    /** Paths whose content hash differs, plus paths new to the set. */
+    changed: Set<string>;
+    removed: Set<string>;
+    roots: Map<string, RootRecord<Meta>>;
+    validRoots: Set<string>;
+    rootsDeclined: number;
+    reuse(valid: ReadonlySet<string>): {
+        summaries: BehavioralSummary[];
+        owners: string[][];
+    };
+    allSummaries(): BehavioralSummary[];
+    /** The stored attribution decoded, for a write that changes nothing. */
+    attribution(): CacheAttribution<Meta>;
+}
+interface CacheLayer<Meta = unknown> {
+    /** The summary list on a hit, null on a miss. */
+    tryHit(input: CacheInput): Promise<BehavioralSummary[] | null>;
+    /**
+     * The lookup behind `tryHit`, with the reason a miss missed. Costs
+     * stats alone: no file reads, no AST work.
+     */
+    lookup(input: CacheInput): Promise<CacheLookup>;
+    /**
+     * After a `files-changed` miss: hash what the stats said moved and
+     * work out which files' summaries survive. Null when the entry has
+     * no per-file layer to reuse, or no entry matches the key at all.
+     */
+    plan(input: CacheInput): Promise<PartialPlan<Meta> | null>;
+    /**
+     * Persist a fresh extraction's summaries to the cache, keyed
+     * against the same file list. Subsequent `lookup` calls with the
+     * same files return them. Without `attribution` the entry can only
+     * ever be reused whole.
+     */
+    write(input: CacheInput, summaries: BehavioralSummary[], attribution?: CacheAttribution<Meta>): Promise<void>;
+}
+interface CacheInput {
+    /** Absolute paths of every file the run walks. */
+    files: ReadonlyArray<string>;
+    adapterPacksDigest: string;
+    /**
+     * One file whose stamp guards the whole entry alongside the file
+     * list, such as a tsconfig or a project manifest. Optional because
+     * not every adapter has one.
+     */
+    configPath?: string;
+}
+/**
+ * Construct a cache layer rooted at `cacheDir`. Pass `null` to
+ * opt out of caching entirely, the returned layer's `tryHit`
+ * always misses and `write` is a no-op. Useful for one-shot
+ * extracts where caching adds latency without payoff.
+ */
+declare function createCacheLayer<Meta = unknown>(cacheDir: string | null): CacheLayer<Meta>;
+
+/**
+ * The extraction funnel, shared across languages.
+ *
+ * "Why did this run produce nothing" is always "at which stage did the
+ * count reach zero", so the report is a funnel: files in the tsconfig,
+ * files the import gates selected, units discovered, summaries built.
+ * Each row is recorded by the stage that owns it, because the
+ * alternative is the CLI re-deriving the pre-filter's decisions from a
+ * second copy of its logic, and a second copy drifting from the first
+ * is what made an entire pack family extract nothing in silence.
+ *
+ * TypeScript, Python and Ruby all build one of these, though only
+ * TypeScript gates files by import specifier today. A pack with no gate
+ * concept reports it the way TypeScript reports an ungated pack.
+ */
+
+/** 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 project. 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, or for a language whose packs have
+     * no declared-pattern system at all. 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 project's include set, or null when nothing states one separately from the walk. */
+    filesInProject: number | null;
+    /** Files the adapter 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;
+}
+/** Per-pack running counts, filled as the extract proceeds. */
+interface PackTally {
+    candidateFiles: number;
+    unitsDiscovered: number;
+    unitsInGatedFiles: number;
+    effectsRecognized: number;
+    unitsClaimed: number;
+    selfCollisions: number;
+    summariesProduced: number;
+    failures: PackFailure[];
+    /** Registration helpers from this pack's config that produced a unit. */
+    helpersMatched: Set<string>;
+}
+declare const emptyTally: () => PackTally;
+/**
+ * Record that a pack's hook threw, and phrase it in one sentence a caller
+ * can print. Both callers want the same wording, and a failure that only
+ * reached stderr left the counts looking like an empty pack.
+ */
+declare function recordPackFailure(tally: PackTally | undefined, failure: {
+    pack: string;
+    hook: string;
+    file: string;
+    error: unknown;
+}): string;
+declare function createPackTallies(packs: ReadonlyArray<{
+    name: string;
+}>): Map<string, PackTally>;
+/** Credit the pack whose name a raw unit's boundary binding gives as `recognition`. */
+declare function tallyUnit(tallies: Map<string, PackTally>, recognition: string | undefined): void;
+/**
+ * The summary-side funnel counts, per pack.
+ *
+ * These are read back off the finished run rather than tallied during
+ * it, because the summaries a pack is responsible for are not all built
+ * where the pack is in scope: wrapper expansion and sub-unit synthesis
+ * both add summaries after discovery has moved on. Every summary
+ * records what recognised it, so grouping on that gets each one back to
+ * the pack that owns it however late it arrived.
+ */
+interface SummaryCounts {
+    bound: number;
+    providers: number;
+    withBehavior: number;
+}
+declare function summaryCountsByPack(summaries: ReadonlyArray<BehavioralSummary>): Map<string, SummaryCounts>;
+/**
+ * An extraction report for an adapter with no gate stage of its own,
+ * the way TypeScript reports an ungated pack: every file is a
+ * candidate, and `unitsClaimed` tracks `unitsDiscovered` one for one
+ * because nothing dedups across packs yet.
+ */
+declare function buildUngatedExtractionReport(args: {
+    packs: ReadonlyArray<{
+        name: string;
+        version: string | null;
+        discovers: boolean;
+    }>;
+    tallies: ReadonlyMap<string, PackTally>;
+    filesWalked: number;
+    summaries: ReadonlyArray<BehavioralSummary>;
+}): ExtractionReport;
+
+/**
+ * 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[];
+}
+/** The gradient for every pack in a run that declared anything. */
+declare function packGradients(report: ExtractionReport): PackGradient[];
+/**
+ * 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;
+
+/**
+ * Lightweight phase-timing instrumentation.
+ *
+ * Measures wall time spent in named phases of an adapter run so the
+ * CLI can surface "extract took 17s, of which 11s was in the
+ * reachable closure" without engaging a profiler. Cheap enough to
+ * always be on; a phase that isn't entered contributes zero.
+ *
+ * Not OpenTelemetry: this is single-process, stdout-bound, and should
+ * not ship transitively to consumers. If suss ever becomes a
+ * long-running daemon (LSP / file-watcher), revisit then.
+ */
+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;
+}
+/**
+ * Build a fresh timer. Each adapter run gets its own, keeps
+ * concurrent extracts independent (irrelevant today, will matter if
+ * we add a server mode).
+ */
+declare function createTimer(): Timer;
+/** Null implementation for callers that opt out of timing entirely. */
+declare function noopTimer(): Timer;
+
 /**
  * The vocabulary a language adapter implements so that any declared
  * pack runs on it.
@@ -2757,4 +3400,4 @@ declare function rawConditionToPredicate(c: RawCondition): Predicate;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type AstCapableOps, type BindingExtraction, type BodyContent, type CallOps, type CaseGroup, type ChannelSource, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, type FailureDelivery, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, MAX_PATHS, type NodeVisitor, type OpsCarrier, type PackDeclarations, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, SKIP_CHILDREN, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkableNode, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, composeWrappers, configuredCallOption, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, guardsHoldOn, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, rawConditionToPredicate, registrationHelperDiscovery, routeHelperIndex, runsBefore, scopeOption, sharedGatingConditions, storageSystemOption, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };
+export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type AstCapableOps, type BindingExtraction, type BodyContent, type CacheAttribution, type CacheDiagnostic, type CacheInput, type CacheLayer, type CacheLookup, type CallOps, type CaseGroup, type ChannelSource, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, type ExitKind, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_PATHS, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, SKIP_CHILDREN, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type Timer, type TimingReport, type TransparentWrapper, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkableNode, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, buildUngatedExtractionReport, composeWrappers, computeContentHash, computeDistHashFrom, configuredCallOption, createAdapterStamp, createCacheLayer, createPackTallies, createTimer, detectGaps, effectToIR, emptyTally, enumerateOrDegrade, enumerateStructuredPaths, evaluatePackHealth, firstWrittenReading, formatPackHealth, guardsHoldOn, httpRouteDiscovery, makeTransitionId, mapReading, moduleInitStructure, noopTimer, packGradients, paramToInput, projectFileStamp, rawConditionToPredicate, recordPackFailure, registrationHelperDiscovery, routeHelperIndex, runDigest, runsBefore, scopeOption, sharedGatingConditions, stampModuleImports, storageSystemOption, summaryCountsByPack, tallyUnit, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };