@suss/extractor 0.33.1 → 0.34.0

package/dist/index.d.ts

@@ -1,17 +1,17 @@
-import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, RequestSpellingMetadata, BehavioralSummary, Predicate, TypeShape, RenderNode, BoundaryBinding, WrapperReference, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, RequestSpellingMetadata, BehavioralSummary, Predicate, ValueRef, TypeShape, RenderNode, ProvenanceSlot, BoundaryBinding, WrapperReference, TestMetadata, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 import { z } from 'zod';
 
 /**
- * What a unit reads out of what it was given.
+ * What a unit reads out of its inputs.
  *
  * A summary already describes this, but only as a chain of `derived` nodes
  * nested one inside the next, which anyone who wants the list has to walk
  * themselves. The `path` on an input reference is empty, so querying the
  * field that looks like the answer gives nothing back.
  *
- * This module flattens that into the list directly: everything a unit reaches
- * for through its inputs, once each, in the order somebody would say them out
- * loud. It goes on the summary as `inputReads`.
+ * This module flattens those chains into a list of everything a unit reads
+ * through its inputs, once each, sorted by input and then by path. The list
+ * goes on the summary as `inputReads`.
  */
 
 /** One thing a unit read, and the way it reached it. */
@@ -31,10 +31,10 @@ interface InputRead {
  * is a parameter. The call site has the literals and no library; the
  * helper body has the library and no literals.
  *
- * A pack asks here for the helper to be read once, over the whole
- * project, before any file is walked. What comes back says what the
- * body does in terms of the helper's own parameters, and the pack turns
- * that into the patterns and recognizers it used to take as config.
+ * A pack asks for the helper to be read once, over the whole project,
+ * before any file is walked. What comes back says what the body does in
+ * terms of the helper's own parameters, and the pack turns that into
+ * discovery patterns and invocation recognizers.
  */
 
 /**
@@ -45,8 +45,8 @@ interface InputRead {
  */
 type HelperValue = 
 /**
- * A string, with `{N}` standing where parameter N was interpolated.
- * A literal with no interpolation is the literal itself.
+ * A string, with `{N}` wherever parameter N was interpolated. A
+ * literal with no interpolation comes back unchanged.
  */
 {
     as: "text";
@@ -83,11 +83,11 @@ interface HelperSink {
 }
 /** A function the project declares, as the index read it. */
 interface ProjectHelper {
-    /** What the declaration calls it, which is what a call site writes. */
+    /** The declared name, which is the name call sites use. */
     name: string;
     /** Absolute path of the file declaring it. */
     file: string;
-    /** Its parameters, in order, by name. */
+    /** Parameter names in declaration order. */
     parameters: string[];
     /**
      * Parameters some caller handed this pack's own value to. Empty when
@@ -100,11 +100,11 @@ interface ProjectHelper {
 /**
  * How the index picks out which of the project's functions to read.
  *
- * `subject` starts at a call site: a function the project hands one of
- * this pack's own values to is a helper of this pack's, whatever the
+ * `subject` starts at a call site: a function the project passes one of
+ * this pack's own values to is one of the pack's helpers, whatever the
  * helper's file imports. `text` starts at the body, for a pack whose
  * library is reached over the wire and has no import to look for. Both
- * come from the library itself, which is the bar `requiresImport` meets.
+ * searches use only facts about the library, as `requiresImport` does.
  */
 type HelperSearch = {
     by: "subject";
@@ -117,30 +117,30 @@ interface HelperDeclarations {
     discovery?: DiscoveryPattern[];
     invocationRecognizers?: InvocationRecognizer[];
 }
-/** A pack's standing request to have the project's helpers read. */
+/** A pack's request to have the project's helpers read before extraction. */
 interface ProjectHelpers {
     find: HelperSearch;
     /**
-     * Turned into patterns and recognizers before the first file is
-     * walked. It is handed data, never an AST, so a pack that declares
-     * one still runs on any adapter that implements the reading.
+     * Called once, before the first file is walked, to turn the helpers
+     * into patterns and recognizers. It receives data and never an AST, so
+     * a pack that declares it runs on any adapter that reads helpers.
      */
     declare(helpers: readonly ProjectHelper[]): HelperDeclarations;
 }
 
 /**
- * The `PatternPack` interface, which is what a framework pack gives a language
- * adapter. The pack says WHAT to look for (which import, which call, which
- * decorator); the adapter knows HOW to find that in its language's AST.
+ * The `PatternPack` interface a framework pack hands to a language adapter.
+ * The pack describes what to look for (an import, a call, a decorator), and
+ * the adapter finds it in its own language's syntax tree.
  *
- * Everything here is data, never code. A pack describes a library once and any
- * adapter that understands these patterns can apply it. If you want a pack to
- * compute something, the answer is usually another declarative field here.
+ * Most of a pack is data, so one pack description works with any adapter
+ * that reads these patterns. When a pack needs to compute something, the
+ * usual fix is another declarative field here. The function hooks
+ * (`subUnits`, `discoverUnits` and the recognizers) cover what data cannot.
  *
- * The sections run in the order an adapter uses them: discovery finds candidate
- * code units, terminals describe how a unit finishes, contract reading and
- * input mapping describe what it declares and takes in, and response property
- * semantics say which property is the body and which is the status.
+ * Sections follow the order an adapter uses them. The pack patterns
+ * reference at https://suss.sh/packs/patterns shows each variant with the
+ * code it matches.
  */
 
 type DiscoveryMatch = {
@@ -165,21 +165,18 @@ type DiscoveryMatch = {
      *  Unset means any method call (or bare call for globals). */
     methodFilter?: string[];
     /**
-     * Method names on the import that produce a client-equivalent instance,
-     * so variables initialized from those calls also act as discovery
-     * subjects. axios uses `axios.create({...})` to build a baseURL-bound
-     * instance; declaring `factoryMethods: ["create"]` lets the adapter
-     * treat `api.get(...)` (where `api = axios.create(...)`) the same as
-     * `axios.get(...)`.
+     * Methods on the import that build a client instance. A variable
+     * initialized from one of these calls is a client too, so with
+     * `factoryMethods: ["create"]`, `api.get(...)` after
+     * `api = axios.create(...)` matches the same as `axios.get(...)`.
      */
     factoryMethods?: string[];
     /**
-     * The property of the factory call's config object that every
-     * request through the instance is sent under, `baseURL` for axios.
-     * Both sides of a boundary have to read one route the same way,
-     * and a spec's `servers[0].url` already goes in front of the
-     * provider's paths, so a base written here goes in front of the
-     * consumer's.
+     * The option on the factory call's config that sets a base path for
+     * every request through the instance, `baseURL` for axios. The
+     * adapter puts it in front of each call's path, so the consumer's
+     * route lines up with a spec whose `servers[0].url` adds the same
+     * prefix to the provider's paths.
      */
     basePathOption?: string;
     /**
@@ -190,88 +187,54 @@ type DiscoveryMatch = {
     callable?: boolean;
 } | {
     /**
-     * A constructor or factory call that takes a configuration object
-     * containing a resolver map, which is how code-first GraphQL servers
-     * are usually written. The map is two levels deep: outer keys are
-     * GraphQL type names (`Query`, `Mutation`, `Subscription`, or
-     * object-type names like `User`), and inner keys are field names
-     * whose values are resolver functions.
+     * A constructor or factory call whose config object contains a
+     * two-level resolver map, the usual way to write a code-first GraphQL
+     * server. Outer keys are type names and inner keys are field names:
      *
-     * Example (Apollo Server v4):
      * ```ts
-     * new ApolloServer({
-     *   typeDefs,
-     *   resolvers: {
-     *     Query:    { users: async () => {...} },
-     *     Mutation: { createUser: async (_, {input}) => {...} },
-     *     User:     { fullName: (parent) => `${parent.first} ${parent.last}` },
-     *   },
-     * });
+     * new ApolloServer({ typeDefs, resolvers: { Query: { users: async () => {...} } } });
      * ```
      *
-     * Each inner function becomes one discovered unit whose binding
-     * semantics is `graphql-resolver(typeName, fieldName)`. Both
-     * `new Ctor(cfg)` and `ctor(cfg)` match, because Apollo's standalone
-     * server uses `new` and yoga uses a bare call.
+     * Each inner function becomes one unit bound as
+     * `graphql-resolver(typeName, fieldName)`. Both `new Ctor(cfg)` and
+     * `ctor(cfg)` match, since Apollo's standalone server uses `new` and
+     * yoga uses a bare call.
      */
     type: "resolverMap";
     importModule: string;
     importName: string;
     /**
-     * The property on the config object that contains the resolver map.
-     * This is the library's own config key, so the pack has to give it and
-     * the adapter ships no default. Apollo, yoga, and graphql-tools all
-     * spell it `"resolvers"`.
+     * The config property that contains the resolver map. The key belongs
+     * to the library, so the adapter has no default. Apollo, yoga and
+     * graphql-tools all use `"resolvers"`.
      */
     mapProperty: string;
     /**
-     * GraphQL types whose fields we DON'T treat as resolvers. This is the
-     * opt-out for meta-types like `Subscription` that we may want to handle
-     * differently later. Leave it unset to discover every type.
+     * Types whose fields are not discovered as resolvers, such as
+     * `Subscription`. Leave it unset to discover every type.
      */
     excludeTypes?: string[];
 } | {
     /**
      * A consumer-side GraphQL hook call, the way Apollo Client and urql
-     * are normally used. Each call to one of the listed hooks becomes
-     * a `client`-kind code unit whose binding semantics is
-     * `graphql-operation(operationType, operationName?)`.
+     * are normally used. Each call to a listed hook becomes a `client`
+     * unit bound as `graphql-operation(operationType, operationName?)`.
      *
-     * The document argument can be written several ways: an inline
-     * `gql`-tagged template, a const binding (in this module or imported
-     * from another one), a `.graphql` or `.gql` file import, or a
-     * generated `TypedDocumentNode` object literal from graphql-codegen
-     * client-preset. When the document body cannot be read statically,
-     * the operation header falls back to the `TypedDocumentNode` type
-     * arguments. A document that still cannot be resolved shows up on the
-     * summary as `metadata.graphql.unresolvedDocument`, so the boundary is
-     * kept rather than dropped.
-     *
-     * Example:
-     * ```ts
-     * import { gql, useQuery } from "@apollo/client";
-     * const GET_USER = gql`query GetUser($id: ID!) { user(id: $id) { id } }`;
-     * function UserPage({ id }) {
-     *   const { data } = useQuery(GET_USER, { variables: { id } });
-     *   ...
-     * }
-     * ```
-     *
-     * The adapter records the operation name and type on the
-     * DiscoveredUnit's `operationInfo`, and binding construction uses that
-     * to emit `graphql-operation(...)`. The per-hook `operationType`
-     * wins when the document header cannot be read, the same way
-     * `graphqlImperativeCall.methods` does.
+     * The document can be an inline `gql` template, a const in this
+     * module or an imported one, a `.graphql` or `.gql` file import, or a
+     * `TypedDocumentNode` from graphql-codegen. When the body cannot be
+     * read, the operation header comes from the `TypedDocumentNode` type
+     * arguments. A document that still cannot be resolved is kept on the
+     * summary as `metadata.graphql.unresolvedDocument`, so the boundary
+     * stays.
      */
     type: "graphqlHookCall";
     importModule: string;
     /**
-     * Hooks to match on that import, each mapped to the operation type it
-     * performs (`useQuery` to query, `useMutation` to mutation,
-     * `useSubscription` to subscription). That mapping supplies the
-     * operation type when the document body cannot be read statically.
-     * Each hook is reported as `kind = "client"` unless a pack overrides
-     * that through the enclosing `DiscoveryPattern.kind`.
+     * Hooks on that import, each with the operation type it performs
+     * (`useQuery` performs a query). The type is used when the document's
+     * header cannot be read. A matched call is a `client` unit unless the
+     * enclosing `DiscoveryPattern.kind` says otherwise.
      */
     hooks: Array<{
         hookName: string;
@@ -279,21 +242,17 @@ type DiscoveryMatch = {
     }>;
 } | {
     /**
-     * An imperative Apollo-Client-style call: `client.query({ query })`,
-     * `client.mutate({ mutation })`, `client.subscribe({ query })`. This is
-     * separate from hook calls because the document is on a config-object
-     * property rather than the first positional argument.
+     * An imperative Apollo Client call: `client.query({ query })`,
+     * `client.mutate({ mutation })` or `client.subscribe({ query })`. The
+     * document is on a config property instead of the first argument,
+     * which is why this is separate from `graphqlHookCall`.
      *
-     * Discovery only fires when the named constructor (usually
-     * `ApolloClient`) is imported, because otherwise any object at all
-     * with a `query` method would look like a match.
-     *
-     * Each entry in `methods` specifies the method called on the client
-     * (`"query"`, `"mutate"`, or `"subscribe"`) and the config-object
-     * property that contains the gql document
-     * (`"query"`, `"mutation"`, and `"query"` respectively). The method
-     * name decides the operation type when the gql document's header is
-     * anonymous. When the document has a name, its header wins.
+     * Discovery fires only when the named constructor (usually
+     * `ApolloClient`) is imported, since otherwise any object with a
+     * `query` method would match. Each `methods` entry gives the method,
+     * the config property with the document on it, and the operation type
+     * to use when the document's header is anonymous. A named header takes
+     * precedence.
      */
     type: "graphqlImperativeCall";
     importModule: string;
@@ -305,41 +264,29 @@ type DiscoveryMatch = {
     }>;
 } | {
     /**
-     * Treats a TypeScript package's public export surface as a
-     * boundary. The adapter reads `package.json` at `packageJsonPath`,
-     * resolves each reachable entry point (root `.` and any sub-path
-     * `exports`), follows barrel re-exports, and emits one discovered
-     * unit per exported function. Those units are the provider side of
-     * an in-process `function-call` boundary.
-     *
-     * The bindings this produces have the identity
-     * `{ transport: "in-process",
-     *    semantics: { name: "function-call",
-     *                 package: <pkg.name>,
-     *                 exportPath: [...] },
-     *    recognition: <pack.name> }`.
-     *
-     * A sub-path export is identified as, for example,
-     * `@suss/behavioral-ir/schemas::BehavioralSummarySchema`, giving
-     * `exportPath = ["schemas", "BehavioralSummarySchema"]`. A root export
-     * leaves the sub-path segment out.
+     * A TypeScript package's public exports, as the provider side of an
+     * in-process `function-call` boundary. The adapter reads
+     * `package.json`, resolves each entry point (the root `.` and any
+     * sub-path in `exports`), follows barrel re-exports, and emits one
+     * unit per exported function.
      *
-     * As of v0 this resolves the `types`, `default`, and `import`
-     * conditions on `exports`, and falls back to `types`, `main`, `module`
-     * when there is no `exports` field. Pattern exports (`./utils/*`) and
-     * `development` conditions are not handled yet.
+     * Each binding is keyed by package and export path, so
+     * `@suss/behavioral-ir/schemas::BehavioralSummarySchema` has
+     * `exportPath = ["schemas", "BehavioralSummarySchema"]`. The `types`,
+     * `default` and `import` conditions are resolved, with `types`, `main`
+     * and `module` as the fallback when there is no `exports` field.
+     * Pattern exports (`./utils/*`) and `development` conditions are not.
      */
     type: "packageExports";
     /**
      * Absolute path to the package's `package.json`. Left out when
-     * `workspaces` is set, since the workspace decides the list.
+     * `workspaces` is set, since the workspace manifest lists the packages.
      */
     packageJsonPath?: string;
     /**
-     * One pattern for every package the workspace declares. The pack
-     * cannot list the packages, because they belong to the project
-     * rather than to any library, so the adapter reads the workspace
-     * manifest and applies this pattern once per package it finds.
+     * Apply the pattern to every package the workspace declares. Those
+     * packages belong to the project, so the pack cannot list them; the
+     * adapter reads the workspace manifest and applies the pattern to each.
      */
     workspaces?: true;
     /**
@@ -355,113 +302,113 @@ type DiscoveryMatch = {
     excludeNames?: string[];
 } | {
     /**
-     * Class methods with a particular decorator, on classes with a
-     * particular class-level decorator. NestJS-style frameworks work this
-     * way: resolvers, handlers, and controllers are declared by decorator
-     * rather than by registering a function in an object literal.
-     *
-     * Discovery only fires when `classDecorator` and each
-     * `methodDecorators` entry come from `importModule`, so a user-defined
-     * decorator that happens to share a name will not match.
-     *
-     * For a NestJS GraphQL pack:
-     * `{ importModule: "@nestjs/graphql",
-     *    classDecorator: "Resolver",
-     *    methodDecorators: ["Query", "Mutation", "ResolveField",
-     *                       "Subscription"] }`
+     * The public exports of one module the project lists in `suss.json`,
+     * read the way `packageExports` reads a package's entry points: one
+     * unit per exported function, class methods surfaced, barrels
+     * followed. Each binding is keyed `fn:<module>::<exportName>`. The
+     * adapter writes these patterns from the module list, so no pack
+     * declares one.
+     */
+    type: "moduleSurface";
+    /** The module's name, as `suss.json` gives it. */
+    module: string;
+    /** Absolute paths of the files whose exports are the surface. */
+    publicFiles: string[];
+} | {
+    /**
+     * Methods with one of `methodDecorators` on a class with one of
+     * `classDecorators`, the way NestJS declares resolvers. At least one
+     * method decorator has to be imported from `importModule`, so a
+     * project decorator that only shares a name does not match. A NestJS
+     * GraphQL pack sets `classDecorators: ["Resolver"]` and
+     * `methodDecorators: ["Query", "Mutation", "ResolveField", "Subscription"]`.
      *
-     * The adapter fills in `DiscoveredUnit.resolverInfo` so the binding
-     * comes out as `graphql-resolver(typeName, fieldName)`.
-     * `typeName` resolves from `methodDecoratorTypeMap` when the
-     * method decorator is in it, and otherwise from the class
-     * decorator's first argument (`@Resolver(() => User)` gives
-     * `"User"`). `fieldName` comes from the method decorator's `{ name }`
-     * option when that is set, and otherwise from the method name.
+     * The binding comes out as `graphql-resolver(typeName, fieldName)`.
+     * `typeName` comes from `methodDecoratorTypeMap` when the method
+     * decorator is in it, and otherwise from the class decorator's first
+     * argument (`@Resolver(() => User)` gives `"User"`). `fieldName` comes
+     * from the method decorator's `{ name }` option, or the method name.
      */
     type: "decoratedMethod";
     /**
-     * The module a decorator has to be imported from before discovery will
-     * fire. Codebases sometimes re-export a framework decorator wrapped
-     * with extra metadata of their own, and checking one module would miss
-     * those. Pass an array of acceptable modules and any one of them
-     * matching is enough.
+     * The modules a decorator may be imported from. A project that wraps
+     * a framework decorator and re-exports it needs its own module listed
+     * too. Any one module in the list matching is enough.
      */
     importModule: string | string[];
     /**
-     * Class decorators to recognise. The first one that appears on a class
-     * is the one typeName is read from; the rest are fallbacks for
-     * codebases with several wrapper styles. A pack ships only what its own
-     * framework declares here, and takes a project's own wrappers through
-     * its options instead.
+     * Class decorators to match. The first one found on a class supplies
+     * `typeName`, and the rest are fallbacks for projects with several
+     * wrapper styles. A pack lists only its own framework's decorators and
+     * takes a project's wrappers through its options.
      */
     classDecorators: string[];
     methodDecorators: string[];
     /**
-     * Maps a method decorator to the type its field belongs to, for the
-     * decorators that settle it. NestJS puts `@Query` on the root
-     * `Query` type and `@Mutation` on `Mutation` no matter what the class
-     * says, so an entry here wins over the class decorator's argument.
+     * Maps a method decorator to the type its field belongs to. NestJS
+     * puts `@Query` on the root `Query` type whatever the class says, so an
+     * entry here takes precedence over the class decorator's argument.
      *
-     * When the map leaves a decorator out and the class decorator gives no
-     * type either, nothing here works out which type owns the field. The
-     * binding then goes out with no type and pairs with nothing, instead
-     * of claiming a field the schema does not have.
+     * When neither the map nor the class decorator gives a type, the
+     * binding goes out with no type and pairs with nothing. That is safer
+     * than claiming a field the schema does not have.
      */
     methodDecoratorTypeMap: Record<string, string>;
 } | {
     /**
-     * NestJS-style REST controller discovery: a class decorated with
-     * `@Controller(pathPrefix?)`, and methods decorated with
-     * `@Get(subpath?)`, `@Post`, `@Put`, `@Delete`, and so on. The
-     * decorator's NAME is what determines the HTTP method, through
-     * `methodDecoratorRouteMap`. The route path is the class decorator's
-     * first argument joined with a slash to the method decorator's first
-     * argument, and both of those are optional.
+     * A NestJS-style REST controller: a class decorated with
+     * `@Controller(prefix?)` and methods decorated with `@Get(subpath?)`,
+     * `@Post` and so on. The method decorator's name gives the HTTP method
+     * through `methodDecoratorRouteMap`. The path is the class decorator's
+     * first argument joined to the method decorator's, and both are
+     * optional. The binding comes out as `rest(method, path)`.
      *
-     * Wrapper decorators are tolerated the same way as in
-     * `decoratedMethod`: at least one method-route decorator has to come
-     * from the framework module, but class decorators
-     * are matched by name alone, so a project's own wrapper around the
-     * framework's decorator matches once the project lists it in the
-     * pack's options.
-     *
-     * The adapter fills in `DiscoveredUnit.routeInfo` so the binding comes
-     * out as `rest(method, path)`.
+     * At least one route decorator on a method has to be imported from
+     * `importModule`. Class decorators match by name alone, so a project's
+     * own wrapper matches once the project lists it in the pack's options.
      */
     type: "decoratedRoute";
     importModule: string | string[];
     classDecorators: string[];
     /**
-     * Maps a decorator to an HTTP method. NestJS uses one decorator per
-     * verb (`@Get`, `@Post`, `@Put`, `@Delete`, `@Patch`, `@Options`,
-     * `@Head`, `@All`), and other frameworks may do the same. The values
-     * become the `method` field on the REST binding, and `"*"` is fine for
-     * a catch-all decorator.
+     * Decorator name to HTTP method, one entry per verb decorator. The
+     * value becomes the REST binding's `method`; use `"*"` for a
+     * catch-all decorator such as NestJS's `@All`.
      */
     methodDecoratorRouteMap: Record<string, string>;
+    /**
+     * The status the framework sends when a handler returns without
+     * stating one, keyed by method decorator, for the decorators whose
+     * status differs from the response terminals' `defaultStatusCode`.
+     * NestJS sends 201 for `@Post`.
+     */
+    defaultStatusCodes?: Record<string, number>;
+    /**
+     * A method decorator, imported from `importModule`, whose first
+     * argument sets the status of every response the handler returns
+     * without stating its own, NestJS's `@HttpCode(204)`. It wins over
+     * `defaultStatusCodes`.
+     */
+    statusCodeDecorator?: string;
+    /**
+     * The call that puts one path in front of every route the
+     * application serves, NestJS's `app.setGlobalPrefix("api")`.
+     */
+    globalPrefix?: GlobalPrefixCall;
 } | {
     /**
-     * Loop expansion: a `for-of` loop over a literal array of
-     * route specs is treated as if each element were an inline
-     * registration. Used for patterns like:
+     * A `for-of` loop over a literal array of route specs, read as one
+     * inline registration per element:
      *
-     *   const routes = [
-     *     { method: "get", path: "/users", handler: getUsers },
-     *     ...
-     *   ];
-     *   for (const r of routes) app[r.method](r.path, r.handler);
-     *
-     * `elementShape` declares which keys on each element give the method,
-     * the path, and the handler. The loop body has to contain at least
-     * one call expression that references the
-     * loop variable, which filters out unrelated loops. Nothing else
-     * about that call is checked.
-     *
-     * An iterable that resolves to an `ArrayLiteralExpression`, inline or
-     * bound to a `const` one hop away, gets expanded. Cross-file and
-     * computed iterables are outside v0.
+     * ```ts
+     * const routes = [{ method: "get", path: "/users", handler: getUsers }];
+     * for (const r of routes) app[r.method](r.path, r.handler);
+     * ```
      *
-     * Pack-author docs: `design/proposals/dynamic-registration.md`.
+     * `elementShape` says which keys give the method, path and handler.
+     * The loop body has to contain a call that uses the loop variable,
+     * which filters out unrelated loops. The array can be inline or a
+     * `const` one hop away. An array from another file is not expanded.
      */
     type: "registrationLoop";
     elementShape: {
@@ -483,33 +430,26 @@ type DiscoveryMatch = {
     };
 } | {
     /**
-     * Helper-call expansion: one function call at the user's site is
-     * treated as if it were N inline registrations, with the call's
-     * arguments substituted into a template per registration. Used
-     * for calls like `registerCrud(app, 'users', userHandlers)` that
-     * `registrationCall` discovery cannot see today.
-     *
-     * Each entry in `registrations` describes one virtual route
-     * the helper produces. `pathTemplate` and `handlerArg` use
-     * `{N}` placeholders that resolve to the call's positional
-     * arguments. `{N}` substitutes the argument's literal value
-     * (for string-literal args) or its source text (for
-     * non-literal args, with the slot marked opaque). `{N}.prop`
-     * reads `prop` from the argument's resolved object.
-     *
-     * `importModule` optionally narrows matches to helpers imported from
-     * one specific module, which helps when two packages happen to export
-     * a function with the same name.
+     * A helper call read as several inline registrations, with the call's
+     * arguments substituted into a template for each. It covers helpers
+     * like `registerCrud(app, "users", userHandlers)`, which
+     * `registrationCall` cannot see.
      *
-     * Pack-author docs: `design/proposals/dynamic-registration.md`.
+     * Each `registrations` entry is one route the helper produces.
+     * `pathTemplate` and `handlerArg` use `{N}` for the call's Nth
+     * argument: its value when it is a string literal, and otherwise its
+     * source text with the slot marked opaque. `{N}.prop` reads `prop` from
+     * the argument's resolved object. `importModule` narrows matches to a
+     * helper imported from that module, for when two packages export the
+     * same name.
      */
     type: "registrationTemplate";
     helperName: string;
     importModule?: string;
     /**
-     * Which argument is the routable, so a route the helper writes
-     * keys on the same app as one written beside it and the
-     * middleware registered there covers it too.
+     * Which argument is the routable. A route the helper registers then
+     * belongs to the same app as a route written beside the call, and the
+     * middleware registered on that app applies to it too.
      */
     subject?: {
         argument: number;
@@ -523,32 +463,23 @@ type DiscoveryMatch = {
     }>;
 } | {
     /**
-     * Routes declared as JSX elements, the way client-side routers
-     * write them: an element imported from the router library whose
-     * attributes give a URL path pattern and the element it
-     * renders. Covers the tree form (route elements nested inside
-     * one another, child paths joining the parent's, index routes
-     * taking the parent's path) and the object-array form (a
-     * factory call whose first argument is an array of route
-     * objects using the same property names).
+     * Routes declared as JSX elements, the way client-side routers write
+     * them. It reads the tree form, where a child path joins its parent's
+     * and an index route takes its parent's path, and the object form,
+     * where a factory call takes an array of route objects with the same
+     * property names. The pack supplies every name, and the adapter only
+     * walks JSX and arrays.
      *
-     * The pack says what its library exports: the route element, the
-     * path, element, and index attributes, and any factories that
-     * take an array of route objects. The adapter walks JSX and arrays,
-     * and knows none of those names itself.
-     *
-     * Each route with a readable path becomes one unit whose target
-     * is the component the element attribute references, resolved
-     * only when the reference is a single identifier. A route whose
-     * component cannot be read is still reported, as a boundary with
-     * nothing behind it. A route whose path cannot be read gets no path
-     * and reports that in a gap instead of guessing at one.
+     * Each route with a readable path becomes one unit whose target is the
+     * component its element attribute references, when that reference is
+     * a single identifier. A route whose component cannot be read is still
+     * reported, as a boundary with nothing behind it. A route whose path
+     * cannot be read gets no path and a gap saying why.
      */
     type: "jsxElementRoute";
     /**
-     * Module(s) the route element and factories must be imported
-     * from. Exact module specifiers, matched against the file's
-     * import declarations; aliased imports are followed.
+     * Modules the route element and factories must be imported from,
+     * matched exactly. An aliased import still matches.
      */
     importModule: string | string[];
     /** The route element's exported name. */
@@ -578,12 +509,10 @@ type DiscoveryMatch = {
      */
     routeObjectFactories?: string[];
     /**
-     * Factory functions that turn JSX route elements into the route
-     * objects the library consumes. The elements themselves are read
-     * by the JSX walk wherever they appear, so a route-object factory
-     * handed one of these calls has nothing more to add. Listing them
-     * here is what stops that case from being reported as an
-     * unreadable route array.
+     * Factory functions that turn JSX route elements into route objects.
+     * The JSX walk already reads those elements wherever they appear.
+     * Listing the factory keeps a route-object factory that is handed one
+     * of these calls from being reported as an unreadable route array.
      */
     elementsFactories?: string[];
     /**
@@ -594,23 +523,17 @@ type DiscoveryMatch = {
     method: string;
 } | {
     /**
-     * Consumer side of the package-export boundary. Scans source files for
-     * imports of the listed packages and records every call site,
-     * emitting one `caller`-kind unit per enclosing
-     * function. The bindings this produces are
-     * `function-call { package, exportPath }`, which match the provider
-     * summaries `packageExports` produces.
-     *
-     * `packages` lists exact package names to track imports of, possibly
-     * with a sub-path such as `"@suss/behavioral-ir/schemas"`. Pass
-     * several package names to track a family at
-     * once. Imports of any other package are ignored.
+     * The consumer side of the package-export boundary. The adapter finds
+     * imports of the listed packages, records every call site, and emits
+     * one `caller` unit per enclosing function, bound as
+     * `function-call { package, exportPath }` to pair with the providers
+     * `packageExports` finds.
      *
-     * As of v0 this covers named and default imports. Namespace imports
-     * (`import * as X from`) are not tracked yet. Re-imports within
-     * the consumer repo (consumer A imports from consumer B which
-     * re-exports from pkg) produce units against the intermediate rather
-     * than the original, because full symbol resolution is not built yet.
+     * `packages` takes exact package names, with a sub-path where needed,
+     * such as `"@suss/behavioral-ir/schemas"`. Named and default imports
+     * are tracked. Namespace imports (`import * as X`) are not yet. When a
+     * file in the consumer's repo re-exports the package and another file
+     * imports it from there, the unit binds to that intermediate file.
      */
     type: "packageImport";
     /** Left out when `workspaces` is set. */
@@ -621,7 +544,61 @@ type DiscoveryMatch = {
      * side of the package-export boundary, whichever two they are.
      */
     workspaces?: true;
-};
+} | TestCaseMatch;
+/**
+ * Test cases written as nested calls, the way vitest, jest and mocha
+ * write them: `describe("orders", () => { it("cancels", () => ...) })`.
+ * Each case becomes a unit named by its title path, the suite titles
+ * then its own, joined with ` > `. A title the adapter cannot read as a
+ * string keeps its source text and is recorded as unresolved.
+ */
+interface TestCaseMatch {
+    type: "testCase";
+    style: "block";
+    /** The module the runner's functions are imported from, e.g. "vitest". */
+    importModule: string;
+    /** The functions that open a group of cases, e.g. ["describe", "suite"]. */
+    suiteNames: string[];
+    /** The functions that declare one case, e.g. ["it", "test"]. */
+    caseNames: string[];
+    /**
+     * Modifiers that mean the case does not run, written after a suite
+     * or case name: `it.skip`, `describe.todo`. A case under a skipped
+     * suite is skipped too.
+     */
+    skipModifiers: string[];
+    /**
+     * Modifiers that take arguments of their own and return the function
+     * to call, such as `it.skipIf(condition)`. The case called through one
+     * is read like any other.
+     */
+    argumentModifiers: string[];
+    /**
+     * Modifiers that take a table and declare one case per row, such as
+     * `it.each(rows)`. The runner fills the title in per row, so the case
+     * is read once, under the title as written, and that title is
+     * recorded as unresolved.
+     */
+    rowModifiers: string[];
+    /**
+     * How the runner replaces something before a case runs. `object` is
+     * the runner's helper object, imported from `importModule`.
+     * `moduleMethods` replace a whole module given its specifier
+     * (`vi.mock("./orders.js")`), and `memberMethods` replace one member
+     * given the object and the member's name (`vi.spyOn(orders, "cancel")`).
+     */
+    mocks?: {
+        object: string;
+        moduleMethods: string[];
+        memberMethods: string[];
+    };
+    /**
+     * Walk only these files, matched on whole path segments from the end,
+     * so `src/orders.test.ts` matches `/repo/pkg/src/orders.test.ts`. Left
+     * out, every file that imports the runner is walked.
+     */
+    files?: string[];
+}
 type BindingExtraction = {
     method: {
         type: "fromRegistration";
@@ -657,11 +634,9 @@ type BindingExtraction = {
         property: string;
     } | {
         /**
-         * The route path comes from where the file is on disk, which is how
-         * Next.js and React Router describe their routes. The pack spells
-         * out its own convention here, because the adapter knows
-         * about files and the pack knows what the framework does with their
-         * names.
+         * The route path comes from where the file is on disk, the way
+         * Next.js and React Router describe routes. The pack gives the
+         * framework's filename convention, and the adapter applies it.
          *
          * `app/api/orders/[id]/route.ts` under `{ root: "app",
          * dropBasenames: ["route"], dynamic: "brackets" }` comes out as
@@ -707,8 +682,8 @@ type BindingExtraction = {
  * `decoratorArgument` reads the argument off the same decorator the
  * match selected the handler by, so `@EventPattern("order.placed")`
  * gives "order.placed". `literal` is for a wire whose channel the
- * library fixes. `unstated` says the wire is known and the channel is
- * not, which pairs the way a null channel always has.
+ * library fixes. `unstated` means the wire is known and the channel is
+ * not, and it pairs the same as a null channel.
  */
 type ChannelSource = {
     from: "decoratorArgument";
@@ -721,15 +696,10 @@ type ChannelSource = {
 };
 /**
  * A binding the pattern states outright, for a boundary the match
- * cannot read from the source.
- *
- * `bindingExtraction` speaks REST and nothing else, so a declarative
- * pack whose boundary is a queue or a topic had nowhere to say so and
- * was pushed into a callback, which pack health then reports as an
- * ast-link. This is the same vocabulary `DiscoveredCustomUnit` already
- * has, declared instead of returned. Message bus only for now; the
- * design note in the proposals directory says what comes next and why
- * the rest stays put.
+ * cannot read from the source. `bindingExtraction` only covers REST, so
+ * a declarative pack for a queue or a topic states its binding here
+ * instead of writing a callback. The fields are the ones a
+ * `DiscoveredCustomUnit` returns. Only the message bus is supported.
  */
 type DeclaredBinding = {
     semantics: "message-bus";
@@ -789,6 +759,40 @@ interface WrapperMethodRegistration extends WrapperFunctionShape {
      */
     arity?: number;
 }
+/**
+ * A call on the application object that puts one path in front of
+ * every route, with the path as its first argument. The adapter reads
+ * it in whichever file makes it, and applies the prefix to every route
+ * the pattern finds when all such calls in the run agree on it.
+ */
+interface GlobalPrefixCall {
+    /** The method on the application object, NestJS's `setGlobalPrefix`. */
+    method: string;
+    /**
+     * How the application object is made: `NestFactory.create(...)`, where
+     * `NestFactory` is imported from `@nestjs/core`. A call on anything
+     * else is not read, including a parameter some caller passes anything
+     * else to.
+     */
+    application: {
+        importModule: string;
+        importName: string;
+        factory: string;
+    };
+    /**
+     * The routes the prefix leaves out, listed under `option` on the
+     * object the call takes second. An entry is a path, or an object with
+     * the path under `pathKey` and the method under `methodKey`, written
+     * as a member of the library's method enum. `methods` maps each
+     * member's number to its verb, with `*` for every verb.
+     */
+    exclude?: {
+        option: string;
+        pathKey: string;
+        methodKey: string;
+        methods: Record<number, string>;
+    };
+}
 /** A wrapper handed to the routable's constructor as an option. */
 interface WrapperOptionRegistration extends WrapperFunctionShape {
     /** The option the wrapper is under, e.g. "defaultHook". */
@@ -804,22 +808,17 @@ interface DiscoveryPattern {
     /** A binding the pattern states outright. See `DeclaredBinding`. */
     binding?: DeclaredBinding;
     /**
-     * How the routable this pattern discovers (Express's `Router()`,
-     * Hono's `new Hono()`, and similar) can itself be mounted onto
-     * another one under a path prefix, as in Express's
-     * `app.use(prefix, router)` or Hono's `app.route(prefix, sub)`.
-     * This only means anything when `match.type` is `"registrationCall"`,
-     * because mount discovery reuses that match's `importModule` and
-     * `importName` to work out which variables in a file are the routable
-     * that a mount call is being made on.
+     * How the routable this pattern discovers (Express's `Router()`, Hono's
+     * `new Hono()`) is mounted on another under a path prefix, as in
+     * `app.use(prefix, router)` or `app.route(prefix, sub)`. It only applies
+     * when `match.type` is `"registrationCall"`, since mount discovery uses
+     * that match's `importModule` and `importName` to find the routables.
      *
-     * When set, the adapter composes the mount's prefix into the path
-     * of every route discovered on the mounted value, whether it is
-     * declared in the mounting file or, by following the mounted value
-     * through an import, in whichever file declares it. A mount whose
+     * The adapter adds the prefix to every route on the mounted value, in
+     * the mounting file or in the file an import leads to. A mount whose
      * prefix is not a string literal, or whose target the resolution store
-     * cannot follow to a concrete value, contributes nothing, and the routes
-     * under it keep the path they were written with.
+     * cannot follow, adds nothing, and its routes keep the path they were
+     * written with.
      */
     mount?: {
         /** Method name that registers a sub-router at a prefix, e.g. "use" or "route". */
@@ -844,22 +843,14 @@ interface DiscoveryPattern {
      */
     wraps?: WrapperRegistration;
     /**
-     * This pattern only runs against files that import one of these module
-     * specifiers, or a sub-path of one. An empty array means no gate at all
-     * (the pattern is dispatched against
-     * every file). Leaving it undefined does the same, but pack authors
-     * SHOULD write it out, because `[]` is the deliberate
-     * "match every file" choice, usually because the pattern keys on
-     * something other than imports. The fetch runtime does that, since it
-     * matches global `fetch(...)` calls.
-     *
-     * Matching is by prefix on the import module specifier. An entry of
-     * `"@nestjs/graphql"` matches `from "@nestjs/graphql"` and
-     * `from "@nestjs/graphql/dist/foo"` and any other sub-path.
+     * Run this pattern only on files that import one of these module
+     * specifiers or a sub-path of one, so `"@nestjs/graphql"` also matches
+     * `"@nestjs/graphql/dist/foo"`. An empty array runs it on every file, the
+     * same as leaving it unset. Write `[]` out when that is deliberate, as
+     * the fetch runtime does for global `fetch(...)` calls.
      *
-     * This pre-filter is only there for speed. The closure walk and the other
-     * post-passes can still reach every loaded file through symbol
-     * resolution.
+     * The gate only saves time. The closure walk and the passes after
+     * discovery can still reach every loaded file through symbol resolution.
      */
     requiresImport?: string[];
 }
@@ -869,13 +860,10 @@ type TerminalMatch = {
 } | {
     type: "returnStatement";
     /**
-     * Skip ReturnStatements whose returned expression is a CallExpression
-     * (or NewExpression). For frameworks where `return reply.send(...)`
-     * also lands as a `parameterMethodCall` match on the inner call,
-     * this stops the same `return reply.send(...)` producing two
-     * terminals, one from the wrapping returnStatement and one from
-     * the inner method-call chain. Bare returns (`return user`,
-     * `return { id }`, `return await fn()`) still match.
+     * Skip a return whose value is a call or `new` expression. Set it when
+     * a `parameterMethodCall` terminal already matches the inner call, so
+     * `return reply.send(...)` produces one terminal instead of two.
+     * Returns like `return user` and `return await fn()` still match.
      */
     excludeCallReturns?: boolean;
 } | {
@@ -896,22 +884,16 @@ type TerminalMatch = {
     type: "functionCall";
     functionName: string;
     /**
-     * Only match when the name was imported from one of these modules.
-     * The field works exactly like a DiscoveryPattern's gate, matching by
-     * prefix: "react-router" also matches "react-router/server".
+     * Only match when the name was imported from one of these modules,
+     * by prefix, the same as `DiscoveryPattern.requiresImport`.
      *
-     * Set it whenever the function belongs to a library, because matching
-     * on a bare name picks up every function with that name in the
-     * user's project too. `json` is a common name for a project's own
-     * response helper, and reading a library's argument order into one
-     * of those gives you a confident wrong answer.
-     *
-     * Leave it unset only when the function belongs to no library at all.
-     * A pack should generally not target a project's own helper. Declare
-     * the envelope structure instead, with a `returnShape` terminal, and
-     * the adapter follows a returned call into the project and reads
-     * the helper's parameters. That covers a helper whatever it is called
-     * and whatever order its arguments come in.
+     * Set it whenever the function belongs to a library. A bare name also
+     * matches the project's own functions, and `json` is a common name
+     * for a project's response helper. Reading a library's argument order
+     * into one of those gives a confident wrong answer. To cover a project
+     * helper, declare the envelope with a `returnShape` terminal instead:
+     * the adapter follows a returned call into the project and reads the
+     * helper's parameters, whatever the helper is called.
      */
     requiresImport?: string[];
 } | {
@@ -924,26 +906,21 @@ type TerminalMatch = {
     type: "jsxReturn";
 } | {
     /**
-     * A synthetic terminal for the implicit fall-through at the end of a
-     * function body. It fires when the function's last statement is
-     * neither a `ReturnStatement` nor a `ThrowStatement`, which
-     * covers the common case of handler and effect bodies that run
-     * side effects and return `undefined` implicitly. Without this,
-     * handler summaries come out with `transitions: []` because
-     * `findTerminals` has nothing to match. A pack that always expects
-     * explicit returns (HTTP handlers) should leave this out of
-     * its terminals. A pack for callback bodies (React handlers,
-     * `useEffect` bodies, Node `.on(...)` callbacks) should include it.
+     * The implicit fall-through at the end of a function body. It fires
+     * when the last statement is neither a return nor a throw, which is
+     * how most event handlers and effect bodies end. Without it, such a
+     * summary comes out with no transitions. Packs for callback bodies
+     * (React handlers, `useEffect`, Node `.on(...)`) include it, and HTTP
+     * handler packs that expect explicit returns leave it out.
      */
     type: "functionFallthrough";
 } | {
     /**
      * A call to the parameter at this position, `next()` inside a
-     * middleware. Nothing declares this in a pack: the adapter builds
-     * it from `DiscoveryPattern.wraps.continuationParam`, so a
-     * wrapper's path that hands control on ends in a `delegate`
-     * output and a path that responds first does not. That is how
-     * composition tells the two apart.
+     * middleware. Packs do not declare it; the adapter builds it from
+     * `DiscoveryPattern.wraps.continuationParam`. A wrapper path that
+     * hands control on then ends in a `delegate` output, and composition
+     * uses that to tell it from a path that responds first.
      */
     type: "parameterCall";
     parameterPosition: number;
@@ -981,10 +958,21 @@ interface TerminalExtraction {
     defaultStatusCode?: number;
 }
 interface TerminalPattern {
-    /** What kind of output this terminal produces: "response", "throw", "return", "render", "delegate" */
-    kind: "response" | "throw" | "return" | "render" | "delegate";
+    /**
+     * What kind of output this terminal produces. An `exit` terminal ends
+     * the process, so a path that reaches one goes no further, and the
+     * status code it extracts is the exit code.
+     */
+    kind: "response" | "throw" | "return" | "render" | "delegate" | "exit";
     match: TerminalMatch;
     extraction: TerminalExtraction;
+    /**
+     * Read in every unit, whichever pack discovered it, the way an
+     * invocation recognizer is. A runtime's own way of ending the process,
+     * `process.exit(n)`, ends a route handler and a helper alike, and the
+     * pack that declares it discovers no units of its own.
+     */
+    inEveryUnit?: boolean;
     /**
      * On a throw terminal: the framework turns the thrown status into
      * the wire response, so a resolved status makes the output a
@@ -1007,9 +995,8 @@ interface ContractPattern {
     };
     /**
      * The properties an endpoint states its HTTP method and path under.
-     * Both ts-rest and zod-openapi happen to spell them `method` and
-     * `path`, but they are the library's words, so the pack says them
-     * and the adapter reads whatever it is told.
+     * The names belong to the library, so the pack supplies them. ts-rest
+     * and zod-openapi both use `method` and `path`.
      */
     methodProperty: string;
     pathProperty: string;
@@ -1073,33 +1060,23 @@ type InputMappingPattern = {
     wholeParamRole?: string;
 } | {
     /**
-     * Emit one `Input` per declared parameter, in source order, using the
-     * parameter's name as its role, or `defaultRole` when set. Used by the
-     * reachable-closure pass for internal library functions, where no
-     * framework declares a set of roles, so the name a caller sees IS
-     * the role. Destructured parameters are captured the
-     * same way `objectParam` captures them, so `(ctx, { userId })`
-     * gives two inputs, `ctx` and `userId`.
+     * One input per declared parameter, in source order, with the
+     * parameter's name as its role unless `defaultRole` is set. The
+     * reachable-closure pass uses it for internal library functions,
+     * where no framework assigns roles. Destructured parameters work as
+     * in `objectParam`, so `(ctx, { userId })` gives `ctx` and `userId`.
      */
     type: "allPositional";
     defaultRole?: string;
 } | {
     /**
-     * Decorator-driven parameter mapping, NestJS-style. For each declared
-     * parameter, the adapter reads the parameter's first decorator and
-     * looks its name up in `decoratorRoleMap`.
-     * A decorator that matches gives the parameter that role. One that
-     * matches nothing falls back to `defaultRole`, or is skipped when
-     * `defaultRole` is unset.
-     *
-     * For `@nestjs/graphql` resolvers:
-     * `{ "Args": "args", "Parent": "parent",
-     *    "Context": "context", "Info": "info" }`.
-     *
-     * Decorators are matched by name alone, so if several frameworks
-     * define `@Args`, all of them map. Packs that need to
-     * tell them apart by import module can add that later, once there
-     * is a use case worth the cost.
+     * NestJS-style parameter decorators. The adapter looks up each
+     * parameter's first decorator in `decoratorRoleMap`. A match gives the
+     * role, and a parameter that matches nothing gets `defaultRole` or is
+     * skipped. For `@nestjs/graphql` resolvers the map is
+     * `{ Args: "args", Parent: "parent", Context: "context", Info: "info" }`.
+     * Decorators match by name alone, so every framework's `@Args` maps
+     * the same way.
      */
     type: "decoratedParams";
     decoratorRoleMap: Record<string, string>;
@@ -1138,31 +1115,57 @@ interface ResponsePropertyMapping {
  * say so.
  */
 interface TransparentWrapper {
-    /** Callee text as written, e.g. "Sentry.wrapHandler". */
-    callee: string;
-    /** Which argument the wrapped function is passed as. */
-    argument: number;
     /**
-     * The module the callee has to have been imported from. Without it a
-     * local object spelled the same way would be taken for the library.
+     * The module that exports the wrapper, e.g. "@sentry/aws-serverless".
+     * A call matches whatever the project calls the import, and a local
+     * function spelled the same way does not match.
      */
     module: string;
+    /** The name the module exports the wrapper under, e.g. "wrapHandler". */
+    name: string;
+    /** Which argument the wrapped function is passed as. */
+    argument: number;
+}
+/**
+ * A library decorator that fills the parameter it decorates. The library
+ * builds the value, so nothing in the project describes it, and the
+ * decorator call is the only thing that says what the parameter is.
+ */
+interface ParameterSupplier {
+    /** The module that exports the decorator, e.g. "@nestjs/typeorm". */
+    module: string;
+    /** The name the module exports the decorator under. */
+    name: string;
+}
+/**
+ * A command-line parser a runtime or library provides, and where its
+ * settings say which flags a command takes. `parseArgs({ args, options })`
+ * from `node:util` is one: its options object lists every flag, and
+ * nothing else in the command's body ever spells them.
+ */
+interface ArgumentParser {
+    /** The module that exports the parser, e.g. `"node:util"`. */
+    module: string;
+    /** The name the module exports it under, e.g. `"parseArgs"`. */
+    name: string;
+    /** Which argument the settings object is passed as. */
+    argument: number;
+    /** The settings key the command-line arguments are passed under, e.g. `"args"`. */
+    argsKey: string;
+    /** The settings key whose object has one key per flag, e.g. `"options"`. */
+    optionsKey: string;
 }
 interface PatternPack {
     name: string;
     /**
-     * Pack version stamp, which feeds the cache invalidation key. Bump on
-     * any change that affects discovered units / extracted summaries.
-     * Format is opaque to the adapter, so semver or a content hash both
-     * work.
+     * The pack's version, part of the cache key. Change it whenever a change
+     * affects discovered units or summaries; any string works.
      *
-     * Optional, because whoever loads the pack knows more about it than
-     * the pack does. The CLI folds a hash of the file it loaded and of
-     * the config it passed into this stamp, so a pack run through the CLI
-     * invalidates on an edit whether or not it declares a version. A host
-     * that builds packs some other way takes on that responsibility itself.
-     * A pack with nothing to stamp comes out as `"unset"`, and a warm cache
-     * will then serve results for code that has since changed.
+     * It is optional because the CLI hashes the pack file it loaded and the
+     * config it passed into the key, so an edit invalidates the cache
+     * whether or not the version moved. A host that loads packs another way
+     * has to do that itself. A pack with nothing to stamp is keyed as
+     * `"unset"`, and a warm cache then serves stale results after an edit.
      */
     version?: string;
     /**
@@ -1196,18 +1199,12 @@ interface PatternPack {
      */
     requestSpelling?: RequestSpellingMetadata;
     /**
-     * Transport (wire protocol) used in the `BoundaryBinding.transport`
-     * of discovered units. Every pack has to say what its transport is
-     * rather than falling back on a hardcoded HTTP default. "What transport
-     * does this pack cover?" is a question every pack should have to
-     * answer, and requiring the field stops a later pack (React, GraphQL,
-     * Lambda-invoke, queues) from quietly inheriting an HTTP-shaped default
-     * that does not fit it.
-     *
-     * The pack's `name` separately fills in `BoundaryBinding.recognition`
-     * on the summaries, so `{ transport, recognition }` come from
-     * the pack directly and the adapter derives `semantics` from the
-     * discovery pattern's binding-extraction rules.
+     * The transport written into `BoundaryBinding.transport` on discovered
+     * units, such as `"http"` or `"in-process"`. It is required so a pack
+     * for React, queues or Lambda invocation never inherits an HTTP default
+     * that does not fit it. The pack's `name` fills in
+     * `BoundaryBinding.recognition`, and the adapter derives `semantics`
+     * from the discovery pattern's binding extraction.
      */
     protocol: string;
     /**
@@ -1225,137 +1222,57 @@ interface PatternPack {
      */
     failureDelivery?: FailureDelivery;
     /**
-     * Synthesize extra code units out of a parent unit's body, for when one
-     * construct the user wrote implicitly spawns several units the runtime
-     * schedules. Used when a framework's runtime
-     * schedules callbacks that aren't visible as top-level declarations:
-     * React event handlers on JSX elements, React `useEffect` bodies,
-     * Node `emitter.on("event", handler)`, class-component lifecycle
-     * methods, and similar.
-     *
-     * `ctx` is typed `unknown` here because the extractor has no
-     * knowledge of which adapter is driving it; each language adapter
-     * defines its own context type (`TsSubUnitContext` in
-     * `@suss/adapter-typescript`, say) with the primitives a pack needs to
-     * walk the parent's AST. Packs import and cast to the adapter
-     * context they were written against, and that cast is how a pack says
-     * out loud that it requires the TypeScript adapter.
+     * Build extra code units from a parent unit's body, for callbacks the
+     * runtime schedules that are not top-level declarations: React event
+     * handlers on JSX elements, `useEffect` bodies, Node `emitter.on(...)`
+     * handlers. Each returned unit goes through the same extraction as a
+     * discovered one and gets its own summary. Set `terminals` or
+     * `inputMapping` on a sub-unit when it differs from the pack's defaults.
      *
-     * Returned units are fed through the adapter's extraction pipeline
-     * the same way top-level discovered units are, so each becomes its
-     * own `BehavioralSummary`. Put per-unit `terminals` and `inputMapping`
-     * on the `DiscoveredUnit` when a sub-unit is written differently from
-     * the parent pack's defaults.
+     * `ctx` is `unknown` because each adapter defines its own context type
+     * (`TsSubUnitContext` in `@suss/adapter-typescript`) with the primitives
+     * for walking the parent's syntax tree. A pack casts to the context it
+     * was written against, which ties the pack to that adapter.
      */
     subUnits?: (parent: DiscoveredSubUnitParent, ctx: unknown) => DiscoveredSubUnit[];
     /**
-     * A top-level discovery callback the pack supplies. It is to discovery
-     * what `subUnits` is to sub-units: when a framework's convention does
-     * not fit one of the data-driven `DiscoveryMatch` variants (REST
-     * registration, decorator-based controllers, named-export shapes,
-     * etc.), the pack ships its own walker here. The adapter calls it
-     * once per source file alongside the data-driven dispatch.
+     * The pack's own top-level discovery, for a convention none of the
+     * `DiscoveryMatch` variants fits, such as React's component-export
+     * heuristic or Storybook's `.stories.tsx` files. Keeping those in the
+     * pack leaves the `DiscoveryMatch` union to patterns any pack can share.
+     * The adapter calls it once per source file beside the data-driven
+     * discovery, and the units it returns go through the normal pipeline
+     * with the same per-unit overrides.
      *
-     * Use this for framework-specific patterns that do not generalize:
-     * React's component-export heuristic (PascalCase plus a JSX return),
-     * Vue's `.vue` SFC slots, Solid's component conventions, Storybook's
-     * `.stories.tsx` file convention. Those are all legitimate conventions,
-     * but baking each one into the central `DiscoveryMatch` union forces
-     * every unrelated pack to know about them. Callbacks leave the central
-     * union for the generic primitives and let each pack own its own
-     * conventions.
-     *
-     * `ctx` is typed `unknown` for the same reason as in `subUnits`: each
-     * adapter ships its own context primitive (`TsDiscoveryContext` in
-     * `@suss/adapter-typescript`) and a pack casts to whichever one it was
-     * written against. That cast is how the pack says it requires the TS
-     * adapter.
-     *
-     * The units you return go through the adapter's normal pipeline. They
-     * get their terminals and effects extracted, sub-units synthesized, and
-     * summaries assembled exactly as units from data-driven discovery
-     * do. Per-unit `terminals` and `inputMapping` overrides on
-     * `DiscoveredUnit` work the same way too.
-     *
-     * **Cross-pack dedup.** When this callback discovers a unit at the
-     * same `(func, kind)` as a unit from another pack's data-driven
-     * discovery, the adapter's cross-pack claim dedup keeps whichever
-     * claimed it first. The order packs appear in the framework list is
-     * what decides precedence.
+     * `ctx` is `unknown` for the same reason as in `subUnits`
+     * (`TsDiscoveryContext` in `@suss/adapter-typescript`). When this finds
+     * a unit at the same function and kind as another pack's discovery, the
+     * pack that comes first in the framework list claims it.
      */
     discoverUnits?: (sourceFile: unknown, ctx: unknown) => DiscoveredCustomUnit[];
     /**
-     * Per-call-site recognizers that emit typed `Effect`s alongside the
-     * generic `invocation` effect the adapter already captures.
-     *
-     * **Scope contract.** The adapter walks every CallExpression in
-     * the function body and dispatches to every registered recognizer
-     * for each call. Walking skips nested function bodies (those are
-     * their own units with their own recognizer dispatch). The walk is
-     * INDEPENDENT of the existing invocation-effect walker, which is
-     * deliberately narrow (it only captures
-     * `invocation` effects from bare expression statements and container
-     * composition, to avoid double-counting calls that already become
-     * terminals). Recognizers do not have that problem, so they fire on
-     * every call regardless of position, including
-     * `const x = await fn(...)` initializers and nested call args
-     * (which the invocation walker skips). This independence means
-     * recognizer authors can rely on seeing every call in scope.
-     *
-     * **Cross-pack visibility.** Recognizers fire regardless of which pack
-     * discovered the enclosing function, so
-     * `@suss/framework-prisma`'s recognizer can fire on Prisma calls
-     * inside an `@suss/framework-express` handler. Pack authors don't
-     * need to coordinate.
-     *
-     * **Emission contract.** Returning effects ADDS them to the enclosing
-     * default-branch transition, and the generic `invocation` effect is
-     * kept either way (typed effects live alongside the raw
-     * call capture, so inspect can still render the callee text and
-     * arguments while the checker pairs on the typed form). Return `null`
-     * or `[]` for no match.
+     * Per-call recognizers that emit typed `Effect`s beside the generic
+     * `invocation` effect. The adapter calls each one on every call in the
+     * function body, whichever pack discovered the function, and skips
+     * nested functions, which are units of their own. Calls the invocation
+     * walk skips, such as `const x = await fn(...)` initializers, are included.
      *
-     * **Dedup is the recognizer's responsibility.** The dispatcher does
-     * not dedupe across calls. A recognizer that wants to fire
-     * once per identifier, to collapse reads bound to a const used N
-     * times, has to track that state itself across invocations.
-     *
-     * **Exceptions are caught and logged.** A recognizer that throws gets
-     * logged to stderr with the file path and line number, and is skipped
-     * for that one call while the extraction carries on. A buggy
-     * recognizer will not crash the run.
-     *
-     * `call` is the language adapter's call-expression handle (opaque
-     * here; ts-morph `CallExpression` in `@suss/adapter-typescript`).
-     * `ctx` is the adapter's recognizer context (source file, an
-     * `extractArgs()` helper that reuses the adapter's own EffectArg
-     * builder). A recognizer casts both to the adapter context it was
-     * written against, which is the same way `subUnits` says a pack
-     * requires the TypeScript adapter.
+     * Returned effects are added to the enclosing default transition, and
+     * the `invocation` effect stays. Return `null` or `[]` for no match.
+     * Nothing dedupes across calls, so a recognizer that should fire once
+     * per identifier tracks that itself. One that throws is logged with its
+     * file and line and skipped for that call. `call` and `ctx` are the
+     * adapter's own types, which a recognizer casts to as `subUnits` does.
      */
     invocationRecognizers?: InvocationRecognizer[];
     /**
-     * Optional pack-level import gate. When set, the adapter's
-     * pre-filter only considers this pack applicable to source files
-     * whose imports include at least one of the listed modules
-     * (matched by prefix, so `"@aws-sdk/client-sqs"` matches that module
-     * and any `"@aws-sdk/client-sqs/sub-path"`).
-     *
-     * Useful for recognizer-only packs that target a specific library:
-     * `@suss/framework-aws-sqs` declares `["@aws-sdk/client-sqs"]`,
-     * `@suss/framework-prisma` declares `["@prisma/client"]`. Without
-     * a gate, a recognizer-only pack walks every file in the project. That
-     * is correct but wasteful in a large monorepo where most files never
-     * import the library.
-     *
-     * A discovery-pattern pack already has a per-pattern `requiresImport`
-     * on `DiscoveryPattern`. This is the pack-level version of that, for a
-     * pack whose ONLY mechanism is recognizers and which has no discovery.
-     *
-     * Empty or undefined means no gate, so the pack walks every file (the
-     * default for universal recognizers like `@suss/runtime-node`'s
-     * process-surface and env-var recognizers, since `process.*` is
-     * available without importing anything).
+     * A pack-level import gate: the pack applies only to files that import
+     * one of these modules, matched by prefix. A pack with only recognizers
+     * uses it the way a discovery pattern uses its own `requiresImport`;
+     * `@suss/framework-prisma` declares `["@prisma/client"]`. Without a gate
+     * the pack walks every file, which gives the same result and is slow in
+     * a large monorepo. Leave it empty for recognizers that apply
+     * everywhere, such as `process.env` reads, which need no import.
      */
     requiresImport?: string[];
     /**
@@ -1368,6 +1285,16 @@ interface PatternPack {
      * ordinary import would.
      */
     generatedModuleMarkers?: string[];
+    /**
+     * The directories this library's code generator writes to, as the
+     * project's own configuration says, for a generator that leaves no
+     * marker file. Given the directory of a file that imports by relative
+     * path, it returns the output directories the configuration governing
+     * that file gives. An import into one counts as the gated package, the
+     * same as a directory with a marker in it, even before the generator
+     * has run.
+     */
+    generatedModuleDirs?: (fromDir: string) => readonly string[];
     /**
      * Functions the project itself wrote in front of this library, read
      * once across the whole project before any file is walked. What the
@@ -1376,14 +1303,13 @@ interface PatternPack {
      */
     projectHelpers?: ProjectHelpers;
     /**
-     * Environment variables the pack's library reads from inside
-     * node_modules, where no walk ever looks. Declaring them keeps the
-     * checker from telling a template that a variable is unused when the
-     * library reads it on every invocation. The adapter emits one marker
-     * summary per entry whose `module` some project file imports, and
-     * the runtime-config pairing consults the markers before it accuses.
-     * The module match is a specifier prefix, so one entry covers a
-     * scoped family like `@aws-lambda-powertools/`.
+     * Environment variables the library reads from inside node_modules,
+     * where no walk looks. Without them the checker would report a variable
+     * in a template as unused when the library reads it on every invocation.
+     * The adapter emits one marker summary per entry whose `module` some
+     * project file imports, and runtime-config pairing checks the markers
+     * before reporting. `module` matches as a prefix, so one entry covers a
+     * family like `@aws-lambda-powertools/`.
      */
     libraryEnvVars?: Array<{
         /** Module-specifier prefix the library's imports start with. */
@@ -1394,16 +1320,18 @@ interface PatternPack {
         names?: string[];
     }>;
     /**
-     * Library wrappers that return the function they wrapped. The adapter
-     * works this out on its own for a factory inside the project by reading
-     * its body. A library wrapper's body is not there to read, so the
-     * pack has to say it: a call to `callee` resolves to its
-     * `argument`-th argument.
-     *
-     * `callee` matches the call expression text as written, e.g.
-     * `"Sentry.wrapHandler"`.
+     * Library wrappers that return the function they were handed. A call to
+     * the `name` that `module` exports resolves to its `argument`-th
+     * argument. See `TransparentWrapper`.
      */
     transparentWrappers?: TransparentWrapper[];
+    /**
+     * Parameter decorators whose call is the value a container passes
+     * in. A constructor parameter written `@InjectRepository(User) repo`
+     * then reads as that call, and a pack can match `this.repo.find()` by
+     * the decorator it came from.
+     */
+    parameterSuppliers?: ParameterSupplier[];
     /**
      * Objects whose properties are the process environment, written as
      * the dotted path the code spells, e.g. `"process.env"`. The adapter
@@ -1412,6 +1340,27 @@ interface PatternPack {
      * parameter gets its reads reported at the calls that named them.
      */
     environmentObjects?: string[];
+    /**
+     * The process's output streams, written the same way, e.g.
+     * `"process.stdout"`. The adapter follows each one into the helpers
+     * it is passed to, so a write through a stream parameter can say
+     * which stream it goes to.
+     */
+    streamObjects?: string[];
+    /**
+     * Dotted paths a program assigns its exit code to without ending
+     * there, e.g. `"process.exitCode"`. The value assigned, and the
+     * argument of a call an `exit` terminal matches, are where the adapter
+     * starts when it works out which functions' returns become the code.
+     */
+    exitCodeWrites?: string[];
+    /**
+     * Command-line parsers, read in every unit whichever pack found it.
+     * Each flag a call to one declares becomes an input read of `--flag`
+     * off the parameter the call hands its arguments from, so a command's
+     * intent can list its flags under `receives`.
+     */
+    argumentParsers?: ArgumentParser[];
     /**
      * How this library's client object is constructed, so an operation
      * summary can say which endpoint its calls go to. Each entry is a
@@ -1466,41 +1415,26 @@ interface PatternPack {
         workspace: string;
     }>;
     /**
-     * Per-property-access recognizers, the counterpart to
-     * `invocationRecognizers`. Use these for patterns that read a value
-     * through property access without invoking it: `process.env.X`
-     * env-var reads, `Date.now()`-style time reads (which is actually a
-     * call, see invocationRecognizers), bare `module.constant` reads.
-     *
-     * A recognizer here is handed a property access, a call, or a tagged
-     * template, and guards its own shapes. The tagged template is there
-     * for a library that takes its whole argument as one, the way
-     * `prisma.$queryRaw` and `gql` do.
-     *
-     * The scope rules are the same as for invocationRecognizers: it fires
-     * on every such node in the function body and skips nested function
-     * bodies. The emission contract is the same, so effects land on the
-     * enclosing default-branch transition.
-     *
-     * The arguments are opaque here and narrowed by the adapter, for the
-     * same reason as in invocationRecognizers.
+     * Per-access recognizers, the counterpart to `invocationRecognizers` for
+     * values read without a call, such as `process.env.X`. A recognizer is
+     * handed a property access, a call or a tagged template, and checks the
+     * node itself. The tagged template covers libraries that take a whole
+     * template as one argument, like `prisma.$queryRaw` and `gql`. Scope,
+     * emission and argument types follow the `invocationRecognizers` rules.
      */
     accessRecognizers?: AccessRecognizer[];
     /**
-     * What the pack wrote as data rather than as code, for the health
-     * report. Absent for a pack written as a hand-rolled walk, which is
-     * itself the thing the report says.
+     * What the pack wrote as data, for the pack health report. A pack
+     * written as a hand-rolled walk leaves it out, and the report says so.
      */
     declarations?: PackDeclarations;
 }
 /**
- * The price a pack paid for what it matches, so the migration onto the
- * declared surface can be measured rather than asserted.
- *
- * Expressiveness is bought link by link: a link answered with data is
- * inspectable, serializable and runs on any adapter, while a link
- * answered with a function is code that only its own language runs.
- * Both are allowed, and the report says which is which.
+ * How much of what a pack matches is declared as data and how much is
+ * code, counted for the pack health report. A link given as data can be
+ * inspected, serialized and run by any adapter. A link given as a
+ * function only runs in its own language. Both are allowed, and the
+ * report counts each kind.
  */
 interface PackDeclarations {
     declarations: DeclaredMatch[];
@@ -1523,22 +1457,19 @@ interface DeclaredMatch {
     example: string | null;
 }
 /**
- * Per-call-site recognizer hook. See `PatternPack.invocationRecognizers`
- * for the contract and threading model.
+ * Per-call recognizer hook. `PatternPack.invocationRecognizers` says when
+ * it is called and what it returns.
  */
 type InvocationRecognizer<TCtx = unknown> = (call: unknown, ctx: TCtx) => Effect[] | null;
 /**
- * Per-property-access recognizer hook. See
- * `PatternPack.accessRecognizers` for the contract and threading model.
+ * Per-access recognizer hook. `PatternPack.accessRecognizers` says when
+ * it is called and what it returns.
  */
 type AccessRecognizer<TCtx = unknown> = (access: unknown, ctx: TCtx) => Effect[] | null;
 /**
- * The bare minimum a `subUnits` hook needs to know about the parent code
- * unit it is working inside. `func` is left opaque here because each
- * language adapter brands its own FunctionRoot type. This interface lives in
- * the extractor only so `PatternPack` can refer to it, and the adapter-level
- * context types like `TsSubUnitContext` narrow `func` to a concrete AST
- * handle.
+ * The parent unit a `subUnits` hook works inside. `func` is opaque because
+ * each adapter has its own function-root type; adapter context types such
+ * as `TsSubUnitContext` narrow it.
  */
 interface DiscoveredSubUnitParent {
     /** Handle to the parent's function body. Opaque at extractor level. */
@@ -1549,15 +1480,11 @@ interface DiscoveredSubUnitParent {
     kind: string;
 }
 /**
- * What a pack's `discoverUnits` hook returns for each top-level unit it
- * finds. It is to discovery what `DiscoveredSubUnit` is to sub-units. The
- * adapter widens these into its own internal `DiscoveredUnit` type, which has
- * adapter-specific fields like `routeInfo` and `packageExportInfo` on it, and
- * then runs them through the normal extraction pipeline.
- *
- * Pack authors only ever see opaque handles: `func` is whatever the adapter's
- * primitive returned, and the adapter narrows it to its concrete
- * function-root type (`FunctionRoot` in `@suss/adapter-typescript`).
+ * One top-level unit a pack's `discoverUnits` hook found. The adapter
+ * widens it into its own internal unit type and runs it through the
+ * normal extraction pipeline. `func` is whatever the adapter's primitive
+ * returned, and the adapter narrows it to its function-root type
+ * (`FunctionRoot` in `@suss/adapter-typescript`).
  */
 interface DiscoveredCustomUnit {
     /** Function body handle, opaque here. */
@@ -1567,10 +1494,9 @@ interface DiscoveredCustomUnit {
     /** Discovered name (e.g. "UserCard"). */
     name: string;
     /**
-     * The unit's callable identity, when the pack states one: the module
-     * it lives in and the name it goes by there. A server action is the
-     * case, so intent and the keyed pairing pass can refer to it. The
-     * adapter puts both on the unit's function-call binding.
+     * The module the unit is exported from and its export name, when the
+     * pack states them. Server actions use this so intent and keyed pairing
+     * can refer to them. The adapter puts both on the function-call binding.
      */
     functionCallInfo?: {
         module: string;
@@ -1587,19 +1513,15 @@ interface DiscoveredCustomUnit {
      */
     inputMapping?: InputMappingPattern;
     /**
-     * REST route identity for units a callback discovers against an
-     * external manifest (a SAM/CFN template's `Events` block, an infra
-     * routing declaration, and so on) rather than an in-code registration.
-     * When set, the adapter builds a `rest` binding from `(method, path)`,
-     * the same binding a NestJS controller gets from decorator-derived
-     * `routeInfo`, and the discoverUnits callback never has to reach into
-     * the adapter's binding machinery. Either half is null when the
-     * source does not state it, and a binding missing one pairs with
-     * nothing.
+     * The REST route for a unit found through an external manifest, such as
+     * a SAM template's `Events` block, instead of an in-code registration.
+     * The adapter builds a `rest` binding from it, the same one a NestJS
+     * controller gets. Leave either half null when the source does not
+     * state it; a binding missing one pairs with nothing.
      *
-     * One function bound to several routes emits one DiscoveredCustomUnit
-     * per route. The adapter's per-file claim dedup keys on
-     * `(func, kind, method, path)`, so all of those variants survive.
+     * A function bound to several routes returns one unit per route. The
+     * per-file claim dedup keys on function, kind, method and path, so all
+     * of them are kept.
      */
     routeInfo?: {
         method: string | null;
@@ -1645,9 +1567,8 @@ interface DiscoveredCustomUnit {
     metadata?: Record<string, unknown>;
 }
 /**
- * What a pack's `subUnits` hook returns per synthesized child. The
- * adapter pipes each of these through the same extraction + assembly
- * pipeline used for top-level-discovered units.
+ * One child unit a pack's `subUnits` hook built. The adapter extracts and
+ * assembles it the same way as a top-level unit.
  */
 interface DiscoveredSubUnit {
     /** Function body handle, opaque here. */
@@ -1681,8 +1602,8 @@ interface DiscoveredSubUnit {
  * again.
  *
  * The `Cond` type parameter is the language's own handle for a condition
- * expression (a ts-morph Expression for TypeScript, a tree-sitter node for a
- * language added later). The engine passes it through untouched for a caller
+ * expression (a ts-morph Expression in TypeScript, a tree-sitter node in
+ * Python and Ruby). The engine passes it through untouched for a caller
  * to parse afterwards, and never looks inside it.
  */
 /** Where a condition came from, in terms of what that branch's body does. */
@@ -1723,18 +1644,18 @@ interface CaseGroup<Cond> {
     readonly body: StatementBlock<Cond>;
 }
 /**
- * What every lowered statement has on it, whichever construct it is.
+ * The fields every lowered statement has, whichever construct it is.
  *
  * The lowering works `exitKind` out by scanning the statement's own
  * subtree for a return or a throw, skipping every nested function body.
  *
  * `callbacks` is the bodies of the functions this statement passes to
- * calls it makes, as far as the language counts those as running for the
+ * calls it makes, when the language treats those as running for the
  * enclosing unit. The engine walks them on the same path as the
  * statement, so their branches are the unit's branches. Their `return`
- * is not the unit's, so a path that ends inside one continues past the
- * statement. A lowering that leaves the field out behaves as it did
- * before there was one.
+ * does not leave the unit, so a path that ends inside one continues past
+ * the statement. When a lowering leaves the field out, no callback bodies
+ * are walked.
  */
 interface LoweredStatementParts<Cond> {
     readonly exitKind: ExitKind;
@@ -1765,7 +1686,7 @@ type StructuredStatement<Cond = unknown> = (LoweredStatementParts<Cond> & {
     readonly kind: "try";
     readonly tryBody: StatementBlock<Cond>;
     readonly catchBody: StatementBlock<Cond> | null;
-    /** Here only so it can be validated. A finally that exits, or that contains a terminal the caller gave us, is not modeled, and its own conditions are never enumerated. */
+    /** Kept only for validation. The engine does not model a finally that exits or contains one of the caller's terminals, and never enumerates its conditions. */
     readonly finallyBody: StatementBlock<Cond> | null;
 }) | (LoweredStatementParts<Cond> & {
     readonly kind: "exit";
@@ -1780,14 +1701,14 @@ type StructuredStatement<Cond = unknown> = (LoweredStatementParts<Cond> & {
  * value in.
  *
  * A reader that returns `T | null` makes null mean three things at once: the
- * source left the value out, the source states it and the reader could not
+ * source left the value out, the source wrote it and the reader could not
  * evaluate it, or several candidates matched and the reader picked none.
- * Each needs something different said about it on the summary, and the type
- * does not show which the reader meant, so every new reader decides it again
- * and some of them decide wrong.
+ * Each needs a different note on the summary, and `T | null` does not show
+ * which case happened, so every new reader has to choose again and some
+ * choose wrong.
  *
  * The rule that turns a reading into a claim, a library default, or a gap
- * lives in the summary builder in this package and is not exported.
+ * is in the summary builder in this package and is not exported.
  */
 /** Where in a file a value is written, as byte offsets into that file. */
 interface SourceRange {
@@ -1830,9 +1751,9 @@ declare const absentReading: Reading<never>;
  */
 declare function unreadableReading<T>(reason: string, range: SourceRange): Reading<T>;
 /**
- * Several values could be right and the reader picked none. Keeping the
- * candidates leaves what was found available to whoever later teaches the
- * reader how to choose, and every step afterwards keeps them too.
+ * Several values could be right and the reader picked none. The candidates
+ * are kept through every later step, so code that can choose among them
+ * still has them.
  *
  * The range is where somebody should look to see the ambiguity. An ambiguity
  * often spans more than one place (two mounts of one router, in two files),
@@ -1843,8 +1764,7 @@ declare function ambiguousReading<T>(candidates: readonly T[], reason: string, r
 /**
  * A reading paired with what the library does when the source says nothing.
  * Only a pack may supply that default, so the value a summary claims for an
- * unstated field is library-defined and lives in the pack alongside
- * everything else the pack already declares.
+ * unstated field always comes from a pack's declaration about the library.
  */
 interface DefaultedReading<T> {
     /** What the source said. */
@@ -1871,9 +1791,8 @@ declare function mapReading<T, U>(reading: Reading<T>, f: (value: T) => U): Read
  *
  * `f` runs on each of an ambiguous reading's candidates too, and the ones
  * that do read come back as the candidates of an ambiguous reading with the
- * same reason. That way the alternatives stay next to the chosen value all
- * the way to the summary, instead of being dropped at the first step
- * that reads further.
+ * same reason. The alternatives reach the summary instead of being dropped
+ * at the first step that reads further.
  */
 declare function andThenReading<T, U>(reading: Reading<T>, f: (value: T, range: SourceRange) => Reading<U>): Reading<U>;
 /**
@@ -1888,10 +1807,10 @@ interface ChosenReading<T> {
      */
     reading: Reading<T>;
     /**
-     * The readings the choice passed over that nobody could resolve. A later
-     * reading supplying the value does not settle what an earlier one said
-     * and could not be read, so these still go to the
-     * builder and their reasons still reach the summary.
+     * The unreadable or ambiguous readings the choice passed over. A later
+     * reading that supplies the value does not settle an earlier one that
+     * could not be read, so these still go to the builder and their reasons
+     * reach the summary.
      */
     passedOver: readonly Reading<T>[];
 }
@@ -1909,32 +1828,29 @@ declare function firstWrittenReading<T>(readings: readonly Reading<T>[]): Chosen
  * parameters that decide what each of the handler's parameters is, and
  * that has to be settled before there is a summary field to fill in.
  *
- * This applies no default and gives no reason, so most of what a summary
- * says must not be written from it. Hand the reading to the
- * builder instead, and the fixed rule gets applied to it once, somewhere
- * review can see it.
+ * This applies no default and gives no reason, so most summary fields must
+ * not be written from it. Pass the reading to the builder instead, which
+ * applies the one rule for readings in a place a reviewer can find.
  *
  * The identity fields of a boundary binding are the exception, and the path
- * this reads is one of them. A binding either says where a unit is or says
- * nothing and pairs with nothing, and no pack declares a
- * default for what a boundary is called, so the value the builder would
- * put there is the value this gives back. Hand the reading over as well and
- * the reason still becomes a gap.
+ * is one of them. No pack declares a default for what a boundary is called,
+ * so the builder would write the same value this returns. Pass the reading
+ * to the builder as well, so its reason still becomes a gap.
  */
 declare function valueToReadFurtherFrom<T>(reading: Reading<T>): T | null;
 
 /**
- * composeWrappers.ts: what a unit does once the code registered around
- * it is folded in.
+ * Folds the code registered around a unit, such as middleware, into what
+ * the unit does.
  *
  * A wrapper is a meta-function: it takes a unit and returns a unit. The
  * call to its continuation comes through as a `delegate` transition, so
  * a path that ends before that call is a response the caller gets
  * instead of the unit's own, and a path that reaches it hands the
- * request on without responding. The responses go beside the unit's own
- * outcomes and the pass-throughs go nowhere, because the unit's
- * outcomes already say what happens on them. The package README works
- * the example through and says what composition does not read.
+ * request on without responding. The responses are added beside the
+ * unit's own outcomes. The pass-throughs are dropped, because the unit's
+ * outcomes already say what happens on them. This package's DESIGN.md
+ * works through an example and lists what composition does not read.
  */
 
 /**
@@ -1951,6 +1867,57 @@ interface ComposeOptions {
  */
 declare function composeWrappers(summaries: readonly BehavioralSummary[], options?: ComposeOptions): BehavioralSummary[];
 
+/**
+ * The modules a project lists in `suss.json`, as every adapter reads them.
+ *
+ * A module is a name, a root folder, and the files whose exports other
+ * modules are meant to call. The CLI reads the list and hands it to the
+ * adapter with absolute paths. Which file is public when the list does not
+ * say is a fact about the language, so each adapter settles that first.
+ * The rest is the same in all three adapters: which module a file belongs
+ * to, the module stamped on each summary, and the part of the cache key
+ * that makes an edit to the list run discovery again.
+ */
+
+/** The recognition on every module export's binding, in each language. */
+declare const MODULE_SURFACE_RECOGNITION = "modules";
+interface DeclaredModule {
+    readonly name: string;
+    /** Absolute. Every file under it belongs to the module. */
+    readonly root: string;
+    /**
+     * Absolute. The files whose exports are the module's public surface.
+     * Left out when `suss.json` does not say, and then the adapter's
+     * convention for its language decides.
+     */
+    readonly public?: readonly string[];
+}
+/** A module whose public files are settled. An empty list means it has none. */
+interface SettledModule extends DeclaredModule {
+    readonly public: readonly string[];
+}
+/**
+ * Each module with its public files. A module `suss.json` gave files for
+ * keeps them. Otherwise the language's candidates are tried, and only the
+ * ones on disk are kept. A candidate is a path relative to the module's
+ * root, with `{name}` standing for the module's name, as in `index.ts`
+ * or `../{name}.rb`.
+ */
+declare function settleModules(modules: readonly DeclaredModule[] | undefined, candidates: readonly string[]): SettledModule[];
+/**
+ * The module a file belongs to. A public file belongs to its module even
+ * when it is outside the root, as a Ruby `lib/billing.rb` is next to
+ * `lib/billing/`. Otherwise the deepest root that contains the file
+ * wins, so a module nested inside another's folder keeps its own files.
+ */
+declare function moduleOfFile(modules: readonly SettledModule[], file: string): SettledModule | undefined;
+/**
+ * Writes each summary's module onto its location. `root` is the directory
+ * a shortened `location.file` is relative to, when the adapter has
+ * already shortened it.
+ */
+declare function stampModules(summaries: readonly BehavioralSummary[], modules: readonly SettledModule[], root: string | undefined): void;
+
 /**
  * Which branch an effect belongs to.
  *
@@ -1961,8 +1928,8 @@ declare function composeWrappers(summaries: readonly BehavioralSummary[], option
  * attributes effects to branches reads from here, so they all decide
  * it the same way.
  *
- * Neither test is enough alone, and the README beside this file says
- * why with the two shapes that go wrong.
+ * Neither test is enough alone. This package's DESIGN.md shows the two
+ * cases where one test on its own gets the branch wrong.
  */
 
 /**
@@ -1982,7 +1949,26 @@ declare function guardsHoldOn(preconditions: readonly RawCondition[] | undefined
 declare function runsBefore(effectLine: number, terminalEndLine: number): boolean;
 
 /**
- * moduleImports.ts: writing `metadata.moduleImports` on a summary set.
+ * Marks the summaries whose return becomes the process's exit code, as
+ * `metadata.process.exitCodeFrom: "return"`, and clears the mark from
+ * every other one.
+ *
+ * Every adapter works the functions out once per run and calls this over
+ * every summary the run hands back, reused ones included. The chain runs
+ * from the file that sets the code into files that never record that
+ * file as a dependency, so a mark a cache kept could otherwise outlive an
+ * edit to the entry file.
+ */
+
+/**
+ * `returnsTheCode` contains function keys, the absolute file and the
+ * function's span as `declarationKey` writes them. A summary whose file
+ * was shortened is resolved against `workspaceRoot` first.
+ */
+declare function markReturnsAsExitCode(summaries: readonly BehavioralSummary[], returnsTheCode: ReadonlySet<string>, workspaceRoot?: string): void;
+
+/**
+ * Writes `metadata.moduleImports` on a set of summaries.
  *
  * 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
@@ -1999,15 +1985,14 @@ declare function runsBefore(effectLine: number, terminalEndLine: number): boolea
 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.
+ * Builds 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 would report one read as
- * several. The calls those statements make go on the same unit, so the
- * closure can reach the functions behind them.
+ * and a service often reads its configuration there. Walking unit bodies
+ * 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
+ * would report one read as several. The calls those statements make go on
+ * the same unit, so the closure can reach the functions behind them.
  *
  * The one default branch has a `void` terminal, because module
  * initialization returns to nobody. Every adapter builds it the same way.
@@ -2028,12 +2013,9 @@ interface ModuleInitOptions {
 declare function moduleInitStructure(options: ModuleInitOptions): RawCodeStructure;
 
 /**
- * Small helpers for pattern packs that are built the same way.
- *
- * The pack interface is deliberately declarative: a PatternPack is a data
- * object the adapter interprets, and most differences between frameworks are
- * best expressed that way. A few patterns, though, repeat word for word
- * across packs, and this module collects those so they are written once.
+ * Builders for the pack entries that several packs would otherwise copy
+ * word for word. A pack is still a data object the adapter interprets;
+ * these functions only write that data out.
  */
 
 /**
@@ -2042,15 +2024,14 @@ declare function moduleInitStructure(options: ModuleInitOptions): RawCodeStructu
  * like.
  *
  * Each `importNames` entry produces one DiscoveryPattern, because a library
- * usually exposes both a default export and a named export that each produce
- * the routable instance (Express has `express()` and
- * `Router()`, Fastify has `fastify()` and `Fastify`). The binding
- * extraction, method from the registration and path from position 0, is
- * the same for every HTTP server framework we support.
+ * usually exports more than one function that makes the routable instance
+ * (Express has `express()` and `Router()`, Fastify has `fastify()` and
+ * `Fastify`). The binding extraction, method from the registration and
+ * path from position 0, is the same for every supported HTTP framework.
  *
- * Callers still pass the `methods` list themselves, because frameworks
- * support different HTTP verbs. Fastify includes `.head` and `.options`;
- * Express historically does not by default.
+ * Callers pass the `methods` list themselves, because frameworks accept
+ * different verbs: Fastify has `.head` and `.options`, and Express does
+ * not by default.
  *
  * @example
  *   discovery: httpRouteDiscovery({
@@ -2077,7 +2058,7 @@ declare function httpRouteDiscovery(opts: {
  * handlers: middleware, error handlers, validation hooks.
  *
  * A wrapper becomes a unit of its own, summarized like any other, so
- * these entries carry no `bindingExtraction` and no registration chain.
+ * these entries have no `bindingExtraction` and no registration chain.
  * Their `match` is there for the import and the imported name, which is
  * how wrapper discovery works out which variables in a file are the
  * routable. One entry per (import name, wrapper shape) pair, since a
@@ -2095,7 +2076,7 @@ declare function wrapperDiscovery(opts: {
  * placeholders for the call's positional arguments.
  */
 interface RegistrationHelper {
-    /** What the helper is called, as the project's code writes it. */
+    /** The helper's name as the project's code writes it. */
     helperName: string;
     /** The file declaring it, so a same-named function elsewhere is left alone. */
     importModule?: string;
@@ -2122,9 +2103,8 @@ interface RegistrationHelper {
  */
 declare function registrationHelperDiscovery(helpers: readonly RegistrationHelper[], kind?: string): DiscoveryPattern[];
 /**
- * The standing request an HTTP pack makes to have the project's own
- * route helpers read, so what each one registers is a fact about the
- * code rather than something the project restates in config.
+ * Asks for the project's own route helpers to be read, so what each one
+ * registers comes from the code instead of being restated in config.
  */
 declare function routeHelperIndex(opts: {
     importModule: string;
@@ -2136,8 +2116,8 @@ declare function routeHelperIndex(opts: {
 /**
  * The payload behind a `JSON.stringify(...)` call, or the argument
  * unchanged when it is anything else. A producer serializes its message
- * before sending it, and the shape worth comparing across the boundary
- * is what went in, not the string that came out.
+ * before sending it, so the value compared across the boundary is the
+ * object that went into the string.
  */
 declare function unwrapJsonStringify(body: EffectArg | null): EffectArg | null;
 
@@ -2145,13 +2125,12 @@ declare function unwrapJsonStringify(body: EffectArg | null): EffectArg | null;
  * Option declarations more than one pack takes.
  *
  * A pack exports `optionsSchema` beside its factory, and the CLI parses
- * a `-f pack=config.json` file against it before the factory runs, so a
- * key nobody declared is refused by name instead of read as nothing.
+ * a `-f pack=config.json` file against it before the factory runs, so an
+ * undeclared key is refused by name instead of being silently ignored.
  *
- * Four packs accept `storageSystem` and three accept `scope`. A copy
- * per pack is how one of them ends up allowing a value the others
- * reject, which is what happened when two doc comments named
- * `"postgres"` and the union allowed only `"postgresql"`.
+ * Four packs accept `storageSystem` and three accept `scope`, so each
+ * option is declared once here. With a copy per pack, one pack can end up
+ * accepting a value the others reject.
  */
 
 /**
@@ -2175,9 +2154,9 @@ declare const scopeOption: z.ZodString;
  * A call the project has declared to be its own dispatcher, which both
  * message-bus packs take under `producers`.
  *
- * `receiver` is the type rather than the variable: a service keeps its
- * dispatcher in a field, a closure or a constructor parameter, and the
- * type is the only thing stable across all three.
+ * `receiver` is a type name because a service may keep its dispatcher in
+ * a field, a closure or a constructor parameter, and the type is the same
+ * in all three.
  */
 declare const configuredCallOption: z.ZodObject<{
     module: z.ZodString;
@@ -2197,14 +2176,14 @@ declare const configuredCallOption: z.ZodObject<{
  * Nothing here touches a language-specific AST node. A language adapter
  * lowers its own tree into `StructuredStatement` and hands that over.
  *
- * Constructs a lowering declines to model come back as thrown
- * `PathBudgetExceeded` or `UnmodeledFlow`, and the caller falls back to
+ * On a construct it does not model, or on too many paths, the engine throws
+ * `UnmodeledFlow` or `PathBudgetExceeded`, and the caller falls back to
  * enclosure conditions plus an opaque conjunct instead of guessing.
  */
 
 /** The cap on how many paths to enumerate. Past it the caller falls back to degraded conditions. */
 declare const MAX_PATHS = 256;
-/** A construct the lowering step will not model safely, such as switch and case rules the enumeration does not cover. Callers catch this and degrade. */
+/** A construct the engine does not model, such as a stray break in a switch clause or a finally that exits. Callers catch this and degrade. */
 declare class UnmodeledFlow extends Error {
 }
 /** The path budget was exceeded. Callers catch this and degrade. */
@@ -2215,11 +2194,11 @@ interface StructuredPathConditionsInput<Cond, Terminal> {
     statements: StatementBlock<Cond>;
     /**
      * Every StructuredStatement reachable from `statements`, mapped to the
-     * terminals the caller gave us that sit directly at that node: its own
-     * position (a return, throw, or opaque leaf) or, for a branching
-     * construct, its header or test expression. A lowering builds this at the
-     * same time as the tree, so the engine never walks a raw source AST to
-     * find where a terminal lives.
+     * caller's terminals found directly at that node: at its own position
+     * (a return, throw, or opaque leaf) or, for a branching construct, in
+     * its header or test expression. A lowering builds this at the same
+     * time as the tree, so the engine never walks a raw source AST to find
+     * where a terminal is.
      */
     terminalsByStmt: ReadonlyMap<StructuredStatement<Cond>, readonly Terminal[]>;
 }
@@ -2239,11 +2218,10 @@ interface StructuredPathConditionsResult<Cond, Terminal> {
  */
 declare function enumerateStructuredPaths<Cond, Terminal>(input: StructuredPathConditionsInput<Cond, Terminal>): StructuredPathConditionsResult<Cond, Terminal>;
 /**
- * Enumerate, and when the engine gives up say so instead of throwing. Each
- * terminal comes back reachable under one condition nobody can read, which
- * keeps everything the caller already knew about it. A caller that can do
- * better, by walking the terminal's own ancestors for the conditions that
- * enclose it, should.
+ * Enumerate, and when the engine gives up, report why instead of throwing.
+ * Each terminal comes back reachable under one opaque marker condition, so
+ * no terminal is lost. A caller that can walk a terminal's own ancestors
+ * for the conditions that enclose it should use those instead.
  */
 declare function enumerateOrDegrade<Cond, Terminal>(input: StructuredPathConditionsInput<Cond, Terminal>, terminals: Iterable<Terminal>): StructuredPathConditionsResult<Cond, Terminal> & {
     /** Why the engine gave up, or null when it read the whole body. */
@@ -2256,12 +2234,10 @@ declare function enumerateOrDegrade<Cond, Terminal>(input: StructuredPathConditi
  * for a path without it.
  *
  * `readPredicate` turns the language's own expression handle into a
- * predicate. Without one every condition stays opaque, which is what a
- * caller that has no reader gets.
+ * predicate. Without it every condition comes back with `structured: null`.
  */
 declare function sharedGatingConditions<Cond>(paths: readonly (readonly ConditionInfo<Cond>[])[] | undefined, readPredicate?: (expression: Cond) => Predicate): RawCondition[];
 
-/** Anything with a stable id, which is what these key on. */
 interface Identified {
     readonly id: number;
 }
@@ -2271,7 +2247,7 @@ declare class IdSet<T extends Identified> implements Iterable<T> {
     constructor(nodes?: Iterable<T>);
     add(node: T): this;
     has(node: T): boolean;
-    /** The node this set was built with, which is the caller's own handle for it. */
+    /** The wrapper that was added, which may be a different object from `node`. */
     get(node: T): T | undefined;
     get size(): number;
     [Symbol.iterator](): Iterator<T>;
@@ -2287,23 +2263,59 @@ declare class IdMap<T extends Identified, V> implements Iterable<[T, V]> {
 }
 
 /**
- * nodeWalk.ts: the one recursion the adapters use to read a declaration
- * wherever the language allows it to be written.
+ * The enclosing definition of a tree-sitter node, kept for as long as
+ * its parse is.
+ *
+ * A fact key includes the function a node is written in, so an adapter
+ * looks it up for every read it keys, and each step up the tree is a call
+ * into tree-sitter's wasm module that builds a fresh wrapper. A parse tree
+ * does not change once it is built, so each result is kept in a WeakMap
+ * keyed on the tree. The results go when the tree does, and a parse made
+ * in a later run starts with nothing kept.
  *
- * A declaration goes where a statement goes, and every language has more
- * places for a statement than a reader remembers to list. So an adapter
- * does not list the containers it descends into. It walks every named
- * child and says only which nodes keep their own body, because that set
- * is short and a grammar's own vocabulary already names it.
+ * Only this read is kept. Keeping each node's children and fields too
+ * cost more memory than it saved time.
  */
-/** A parse tree, however a grammar spells one. */
+/** What the reader needs from a parse tree node. */
+interface ParsedNode<T> {
+    readonly id: number;
+    readonly type: string;
+    readonly tree: object;
+    readonly parent: T | null;
+}
+/** The nearest ancestor of each node whose type is one of `types`, read once per parse. */
+declare class EnclosingNodes<T extends ParsedNode<T>> {
+    private readonly types;
+    private readonly byTree;
+    constructor(types: ReadonlySet<string>);
+    /**
+     * The nearest ancestor of one of the types, or null when there is none.
+     * Every node passed on the way up has the same result, so each one is
+     * kept, and a later read from a sibling stops one step up.
+     */
+    of(node: T): T | null;
+    private keptFor;
+}
+
+/**
+ * The recursion the adapters use to find a declaration wherever the
+ * language allows one to be written.
+ *
+ * A declaration can go anywhere a statement can, and every language has
+ * more places for a statement than anyone remembers to list. So an adapter
+ * does not list the containers to descend into. The walk visits every
+ * named child, and the adapter only lists the nodes whose body belongs to
+ * what they declare, because that list is short and the grammar already
+ * has a node type for each.
+ */
+/** The one thing the walk needs from a parse tree node. */
 interface WalkableNode<T> {
     readonly namedChildren: ReadonlyArray<T | null>;
 }
 /**
  * Returned by `into` for a node whose children the walk should leave
- * unread, such as one whose body belongs to what it declares. A symbol,
- * so it cannot collide with whatever a caller carries.
+ * unread, such as one whose body belongs to what it declares. It is a
+ * symbol so it cannot collide with any value a caller passes down.
  */
 declare const SKIP_CHILDREN: unique symbol;
 /** What a walk does at each node it reaches. */
@@ -2330,6 +2342,60 @@ declare function walkDescendants<T extends WalkableNode<T>, C>(root: T, carried:
 /** The deepest directory containing every file, or undefined when they share no absolute root. */
 declare function commonDirectoryOf(files: ReadonlyArray<string>): string | undefined;
 
+/**
+ * Which files a test pack reads. `suss extract --intent` hands a test
+ * pack the files the PRDs list under `coveredBy`, written the way the
+ * author wrote them, usually from the repository root. An adapter walks
+ * absolute paths, so an entry matches a file on whole path segments from
+ * the end: `tests/test_orders.py` matches `/repo/api/tests/test_orders.py`
+ * and not `/repo/api/tests/other_test_orders.py`. Every adapter's test
+ * discovery goes through this, so the three languages agree on it.
+ */
+/** Whether the file is on the list. Every file is when there is no list. */
+declare function isListedTestFile(file: string, listed: readonly string[] | undefined): boolean;
+/**
+ * Whether a file's base name matches one of the runner's patterns, where
+ * `*` matches any run of characters: `test_*.py` or `*_spec.rb`.
+ */
+declare function matchesTestFileName(file: string, patterns: readonly string[]): boolean;
+
+/**
+ * Turns the places a value's walk ended into the value references a
+ * transition records, the same way for every adapter.
+ *
+ * The walk itself is in `@suss/resolution`. What an input is depends on
+ * the language and the framework, and so does reading a literal or
+ * quoting the source, so the adapter says those three things. The order
+ * they are tried in, and what a place that is none of them becomes, is
+ * decided here.
+ */
+
+/** One place a walk ended, as much of it as this needs. */
+interface WalkEnd {
+    /** The key of the member the walk ended at. */
+    readonly key: string;
+    /** The properties read off it on the way to the value, outermost first. */
+    readonly path: readonly string[];
+    /** A read at a key the source computes on the way, or null for none. */
+    readonly computedAt: string | null;
+    /** The language's own conversions on the way to the value, outermost first. */
+    readonly conversions: readonly string[];
+    readonly end: {
+        readonly is: string;
+    };
+}
+/** What only the adapter can say about a place a walk ended. */
+interface SourceSpelling<L extends WalkEnd> {
+    /** The input the place is, or null when it is not one. */
+    inputOf(leaf: L): ValueRef | null;
+    /** The literal the written value at a key is, or undefined for anything else. */
+    literalAt(key: string): string | number | boolean | null | undefined;
+    /** The source written at a key, or null when the key is not a node. */
+    textAt(key: string): string | null;
+}
+/** Every place a value's walk ended, as distinct value references. */
+declare function sourceRefsOf<L extends WalkEnd>(leaves: readonly L[], spelling: SourceSpelling<L>): ValueRef[];
+
 /**
  * The small surface every language adapter implements, whatever that
  * language's own tooling looks like underneath.
@@ -2342,9 +2408,8 @@ declare function commonDirectoryOf(files: ReadonlyArray<string>): string | undef
 
 interface LanguageAdapter {
     /**
-     * Extract summaries from a specific list of files. Returns a
-     * Promise so an implementation can do concurrent I/O during
-     * discovery without bottlenecking on synchronous reads.
+     * Summaries for the listed files. It is async so an implementation can
+     * read files concurrently during discovery.
      */
     extractFromFiles(filePaths: string[]): Promise<BehavioralSummary[]>;
     /** Extract summaries from every source file the adapter's project knows about. */
@@ -2352,23 +2417,22 @@ interface LanguageAdapter {
 }
 
 /**
- * adapterStamp.ts: the language-neutral half of an adapter's cache key.
+ * The language-neutral half of an adapter's cache key.
  *
- * An adapter's own version.ts calls `createAdapterStamp` with its own
+ * Each adapter calls `createAdapterStamp` once, 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.
+ * the life of the process. The stamp hashes the adapter's dist file and
+ * every analysis package shipped with it (this package, `@suss/resolution`,
+ * `@suss/datalog`, `@suss/behavioral-ir`). A release that changes any of
+ * them invalidates an older cache, and so does a local rebuild, with no
+ * version bump. Running from source leaves no dist file to hash, so that
+ * mode turns the cache off. This package's DESIGN.md describes the cache.
  */
+
 /**
  * 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.
+ * a hash that changes whenever the code does. `source` means no bundle was
+ * found, so a cache key built from this stamp cannot tell two builds apart.
  */
 type AdapterCodeStamp = {
     kind: "bundle";
@@ -2376,24 +2440,22 @@ type AdapterCodeStamp = {
 } | {
     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).
+     * A cache key for this adapter and its packs. It is the same across
+     * processes for the same inputs, and changes when a pack's version, the
+     * adapter's version, or the adapter's dist file changes.
      */
     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.
+     * Returns `cacheDir`, or null when this process loaded the adapter from
+     * source, since then one build cannot be told from another. The first
+     * null in a process also prints the reason to stderr.
      */
     declineWhenRunFromSource(cacheDir: string | null): string | null;
 }
@@ -2410,7 +2472,7 @@ declare function createAdapterStamp(config: {
 /**
  * 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.
+ * it, as happens when running from source.
  */
 declare function computeDistHashFrom(dir: string): string;
 /**
@@ -2429,19 +2491,40 @@ declare function computeContentHash(paths: readonly string[]): string;
  * 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.
+ * A file that cannot be read is hashed as absent, where
+ * `computeContentHash` would return an empty stamp. These files belong
+ * to the project, so a missing one is a change the next run should see.
  */
 declare function projectFileStamp(paths: readonly string[]): string;
+/**
+ * The run options that change what an extraction writes. An adapter passes
+ * every one it takes, and leaves out the ones it does not have.
+ */
+interface ExtractionConfig {
+    gapHandling?: "strict" | "permissive" | "silent" | undefined;
+    /** Whether a summary is written for each function a unit reaches. */
+    includeReachable?: boolean | undefined;
+    /** The directory a stored summary's `location.file` is relative to. */
+    workspaceRoot?: string | undefined;
+    /** The directory a stored summary's id measures its file from. */
+    projectRoot?: string | undefined;
+    /** The directories an absolute import was resolved against. */
+    importRoots?: readonly string[] | undefined;
+    /** The modules the project lists, which decide which units discovery finds. */
+    modules?: readonly SettledModule[] | undefined;
+}
+/**
+ * The run options as one part of the cache key, so a run never reads an
+ * entry that a run with other options wrote. Every adapter builds this part
+ * here, which keeps the three keys from drifting apart.
+ */
+declare function extractionConfigStamp(config: ExtractionConfig): 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
+ * on the files this run walks, so the digest is computed per run rather
  * than once per adapter.
  */
 declare function runDigest(packsDigest: string, packs: ReadonlyArray<{
@@ -2451,36 +2534,33 @@ declare function runDigest(packsDigest: string, packs: ReadonlyArray<{
 /**
  * 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.
+ * A run reuses the previous run's summaries whole when nothing changed,
+ * and per file when some files did. The entry directory's name is a hash
+ * of the schema version, the adapter and packs digest, and the config
+ * path, so two builds that disagree on any of them never read each
+ * other's entry. The manifest inside records a stamp and content hash per
+ * file, the files each summary belongs to, and for each of those files the
+ * other files its walk read. An adapter can store its own data on a file's
+ * record through `meta`, which the cache never reads. The package's
+ * design notes describe the cache in full.
  */
 
 /**
- * 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.
+ * How many entries a cache directory keeps. Two lets a pair of builds
+ * alternate, as on a branch switch or an adapter rebuild and revert,
+ * without either losing its entry, and keeps a directory to two manifests.
  */
 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.
+ * summaries, and a change to any of them re-extracts this file. `claims`
+ * are the units this file's walk claimed. A partial run replays them
+ * before walking anything, so the same pack wins each unit as before.
+ * `meta` is whatever else the adapter needs to check this file again on
+ * a partial run, such as a route's mount prefixes. A file marked
+ * `cacheable: false` depends on something the cache cannot tie to files,
+ * and is re-extracted on every partial run.
  */
 interface RootRecord<Meta = unknown> {
     path: string;
@@ -2493,15 +2573,31 @@ interface RootRecord<Meta = unknown> {
     meta: Meta;
     /** Packs that applied to the file, re-checked on a partial run. */
     packs: string[];
+    /** The files this file imports, in the order the adapter's loader found them. */
+    imports?: 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.
+ * What an adapter worked out about one unit of its own, such as the calls
+ * one function body makes. `file` is the file the unit is in and `deps`
+ * the other files that went into `data`. A partial run hands the record
+ * back while `file` and every one of `deps` hash the same, so the adapter
+ * can skip the work that produced it. The cache never reads `data`.
  */
-interface CacheAttribution<Meta = unknown> {
+interface UnitRecord<Data = unknown> {
+    key: string;
+    file: string;
+    deps: string[];
+    data: Data;
+}
+/**
+ * Which files each summary belongs to. `summaries[i]` is reused while at
+ * least one file in `owners[i]` is. An empty list marks a summary built
+ * over the whole run, which a partial run always recomputes.
+ */
+interface CacheAttribution<Meta = unknown, UnitData = unknown> {
     roots: RootRecord<Meta>[];
     owners: string[][];
+    units?: UnitRecord<UnitData>[];
 }
 /** Reported by `lookup`: what the cache decided, and why. */
 interface CacheDiagnostic {
@@ -2537,34 +2633,42 @@ type CacheLookup = {
     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.
+ * What a `files-changed` miss can still reuse. `validRoots` are the files
+ * whose hashes and recorded dependencies are unchanged. The caller can
+ * drop more of them, such as a file whose mount prefix no longer matches,
+ * before calling `reuse`. `reuse` returns the summaries that belong to at
+ * least one remaining file, in stored order, with their owners, so the
+ * caller can merge them and write the result back.
  */
-interface PartialPlan<Meta = unknown> {
+interface PartialPlan<Meta = unknown, UnitData = unknown> {
     /** Paths whose content hash differs, plus paths new to the set. */
     changed: Set<string>;
     removed: Set<string>;
+    /**
+     * The stored import list of every file whose content is unchanged, when
+     * no file joined or left the set, since either can move where an import
+     * resolves. Empty otherwise.
+     */
+    resolvedImports: Map<string, string[]>;
     roots: Map<string, RootRecord<Meta>>;
     validRoots: Set<string>;
     rootsDeclined: number;
+    /** Unit records whose file and deps are all unchanged, by key. */
+    validUnits: Map<string, UnitRecord<UnitData>>;
     reuse(valid: ReadonlySet<string>): {
         summaries: BehavioralSummary[];
         owners: string[][];
     };
     allSummaries(): BehavioralSummary[];
     /** The stored attribution decoded, for a write that changes nothing. */
-    attribution(): CacheAttribution<Meta>;
+    attribution(): CacheAttribution<Meta, UnitData>;
 }
-interface CacheLayer<Meta = unknown> {
+interface CacheLayer<Meta = unknown, UnitData = 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.
+     * The lookup behind `tryHit`, with the reason for a miss. It stats the
+     * files, and reads only those changed shortly before, to hash them.
      */
     lookup(input: CacheInput): Promise<CacheLookup>;
     /**
@@ -2572,33 +2676,39 @@ interface CacheLayer<Meta = unknown> {
      * 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>;
+    plan(input: CacheInput): Promise<PartialPlan<Meta, UnitData> | 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.
+     * Save a fresh extraction's summaries against this file list, so a later
+     * `lookup` with the same files returns them. Without `attribution` the
+     * entry can only be reused whole.
      */
-    write(input: CacheInput, summaries: BehavioralSummary[], attribution?: CacheAttribution<Meta>): Promise<void>;
+    write(input: CacheInput, summaries: BehavioralSummary[], attribution?: CacheAttribution<Meta, UnitData>): 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.
+     * A file whose change invalidates the whole entry, such as a tsconfig or
+     * a project manifest. 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.
+ * A cache layer rooted at `cacheDir`. With `null`, every lookup misses and
+ * `write` does nothing, for a one-shot extract where the cache would only
+ * add time.
+ */
+declare function createCacheLayer<Meta = unknown, UnitData = unknown>(cacheDir: string | null): CacheLayer<Meta, UnitData>;
+
+/**
+ * Whether a write after `statAt` could leave this file's mtime and size
+ * where the stat saw them, because its last change was that recent.
  */
-declare function createCacheLayer<Meta = unknown>(cacheDir: string | null): CacheLayer<Meta>;
+declare function stampMayMissAWrite(stat: {
+    mtimeMs: number;
+    ctimeMs: number;
+}, statAt: number): boolean;
 
 /**
  * The extraction funnel, shared across languages.
@@ -2606,10 +2716,9 @@ declare function createCacheLayer<Meta = unknown>(cacheDir: string | null): Cach
  * "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.
+ * Each stage records its own row, so the CLI never works the counts out
+ * from a second copy of the pre-filter's logic that could drift from the
+ * first.
  *
  * TypeScript, Python and Ruby all build one of these, though only
  * TypeScript gates files by import specifier today. A pack with no gate
@@ -2620,9 +2729,9 @@ declare function createCacheLayer<Meta = unknown>(cacheDir: string | null): Cach
 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.
+     * The version stamp the pack declares, or null when it declares none.
+     * 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;
     /**
@@ -2644,11 +2753,10 @@ interface PackFunnel {
      */
     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.
+     * Gate specifiers that do not resolve from the project. A non-empty
+     * list usually means the target project's dependencies are not
+     * installed. Packs that resolve symbols then stop working while packs
+     * with a textual gate still run, and nothing else in the report shows it.
      */
     unresolvedGates: string[];
     /** Files the pre-filter selected for this pack. */
@@ -2707,9 +2815,9 @@ interface PackFunnel {
     /**
      * 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.
+     * no declared-pattern system at all. Unlike the counts, this comes from
+     * the pack's definition and not from the run. It is reported so the
+     * move of packs onto declared patterns can be measured.
      */
     declarations: PackDeclarations | null;
 }
@@ -2724,11 +2832,10 @@ interface ExtractionReport {
      * 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.
+     * Without this list, a module whose barrel chain overflowed the call
+     * stack looks the same as a module that exports 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[];
     /**
@@ -2737,10 +2844,9 @@ interface ExtractionReport {
      */
     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.
+     * Reassigned names the run stated no value for, because control flow
+     * decides which write a reader sees. Across a large corpus, the count
+     * shows how much a scoped reaching-definitions analysis would recover.
      */
     reassignedNamesUnstated: number;
 }
@@ -2754,7 +2860,7 @@ type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery"
  * that looked and found nothing.
  */
 interface PackFailure {
-    /** The hook that threw, called what a pack author would call it. */
+    /** The hook that threw, by the name a pack author uses for it. */
     hook: string;
     /** The file the pack was reading. */
     file: string;
@@ -2774,9 +2880,9 @@ interface PackTally {
 }
 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.
+ * Record that a pack's hook threw, and return one line a caller can print.
+ * The failure also goes on the tally, so the pack's counts do not look
+ * like those of a pack that found nothing.
  */
 declare function recordPackFailure(tally: PackTally | undefined, failure: {
     pack: string;
@@ -2796,8 +2902,8 @@ declare function tallyUnit(tallies: Map<string, PackTally>, recognition: string
  * 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.
+ * records the pack that recognised it, so grouping on that credits each
+ * summary to its pack however late it was built.
  */
 interface SummaryCounts {
     bound: number;
@@ -2822,6 +2928,25 @@ declare function buildUngatedExtractionReport(args: {
     summaries: ReadonlyArray<BehavioralSummary>;
 }): ExtractionReport;
 
+/**
+ * Parses a process keeps between runs of one project, by file.
+ *
+ * The Python and Ruby adapters parse every file on every run, because
+ * facts are emitted over the whole project. A process that reads the same
+ * project after every edit hands a run one of these, and a file whose text
+ * is the same as last time gets last time's tree back. The trees are
+ * WASM memory the garbage collector cannot see, so a tree that is replaced
+ * or whose file went away is handed to `release`.
+ */
+declare class KeptParses<T> {
+    private readonly release;
+    private readonly byFile;
+    constructor(release?: (value: T) => void);
+    parse(file: string, source: string, make: (source: string) => Promise<T>): Promise<T>;
+    /** Lets go of every file not in this run. */
+    keepOnly(files: Iterable<string>): void;
+}
+
 /**
  * Checks that tell you a pack is probably not working.
  *
@@ -2834,8 +2959,8 @@ declare function buildUngatedExtractionReport(args: {
  * 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.
+ * works the same way, so the check is one comparison run over a list of
+ * stage pairs instead of one check written per stage.
  */
 
 /** One thing that looks wrong, reported the way the dogfood invariants are. */
@@ -2869,13 +2994,13 @@ interface HealthCheck {
     violations: HealthViolation[];
 }
 /**
- * What one pack paid for what it matches.
+ * How much of one pack is data and how much is code (#542).
  *
- * 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.
+ * 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 runs only on the
+ * adapter whose tree it reads. All three are allowed, and this counts
+ * each kind.
  */
 interface PackGradient {
     pack: string;
@@ -2906,16 +3031,13 @@ declare function evaluatePackHealth(report: ExtractionReport): HealthCheck[];
 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.
+ * Wall time per named phase of an adapter run, so the CLI can print
+ * "extract took 17s, of which 11s was in the reachable closure" without
+ * a profiler. It is cheap enough to leave on, and a phase that never
+ * runs adds nothing.
  *
- * 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.
+ * Everything stays in one process and goes to stdout, so there is no
+ * OpenTelemetry dependency for consumers to inherit.
  */
 interface TimingReport {
     totalMs: number;
@@ -2928,48 +3050,34 @@ interface TimingReport {
 interface Timer {
     /** Run `fn`, accumulate wall time under `label`, return its result. */
     time<T>(label: string, fn: () => T): T;
-    /** Async variant: same accumulation rule. */
+    /** The same as `time`, for an async `fn`. */
     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).
- */
+/** Each adapter run gets its own timer, so two runs at once never mix their phases. */
 declare function createTimer(): Timer;
-/** Null implementation for callers that opt out of timing entirely. */
+/** A timer that runs `fn` and records nothing, for callers that do not want timing. */
 declare function noopTimer(): Timer;
 
 /**
- * The vocabulary a language adapter implements so that any declared
- * pack runs on it.
+ * The vocabulary a language adapter implements so that any declared pack
+ * runs on it. A pack is data, so the adapter has to turn "did this module
+ * declare the method" into a yes or no about a particular program, and
+ * these interfaces are everything a pack can ask of it.
  *
- * A pack is data, so something has to turn "did this module declare the
- * method" into a yes or no about a particular program. That is the
- * adapter's job, and these interfaces are the whole of what a pack can
- * ask for. An adapter implements them once and every pack runs there,
- * which is what lets one pack drive several languages.
- *
- * They live here rather than beside the builders that produce them,
- * because an adapter needs this and none of the rest: the TypeScript
- * adapter imports these types and no runtime code from
- * `@suss/recognize`. Python and Ruby will want the same.
+ * They are in this package rather than beside the builders in
+ * `@suss/recognize`, so an adapter imports the types without that
+ * package's runtime code. Only the TypeScript adapter implements them.
  *
  * Nothing here mentions a syntax tree. A pack that needs the tree goes
  * through `@suss/recognize/ast`, a separate import so that reaching for
  * it shows up in a diff and in the pack health report.
  */
 /**
- * How a pack pins down the receiver a call is on.
- *
- * The migration plan for #542 lists four more: `factoryMade` (`app =
- * express()`), `imported`, `anchored` (a chain read from its anchor
- * call), `inherits` (a Ruby or Python receiver matched by ancestry) and
- * `global` (`process.env`, bare `fetch`). Each arrives as a member here
- * with an entry in every adapter's dispatch table. The README beside
- * this file says which starts are not receiver-shaped at all.
+ * How a pack pins down the receiver a call is on. The recognize package's
+ * DESIGN.md lists the origins not built yet (#542) and the places a match
+ * can start that are not receivers.
  */
 type ReceiverOrigin = DeclaredBy | ConstructedFrom;
 /**
@@ -3003,29 +3111,41 @@ interface ConstructedFrom {
     readonly named?: readonly string[];
 }
 
+/**
+ * What a reader returns for a name nothing in the source settles.
+ * `"nothing"` returns null, and `"reference"` returns the name of the
+ * value to look up instead.
+ */
 type UnsettledName = "nothing" | "reference";
 /**
  * One value a call states, as the questions a pack can ask about it.
  *
- * `CallOps` reaches a call beside the one in hand, and this reaches the
- * values that are not calls. A library that takes one request object
- * puts everything the call is doing inside it, sometimes as a list and
- * sometimes as a string in a little language of the library's own, and
- * a pack that reads those is handed this rather than the adapter's own
- * node. So the rule it writes runs wherever the ops do.
+ * `CallOps` reaches the calls around the one in hand, and this reaches the
+ * values that are not calls. A library that takes one request object puts
+ * everything the call does inside it, as a list or as a string in the
+ * library's own query language. A pack that reads those gets this instead
+ * of the adapter's node, so its rule runs on any adapter with the ops.
  */
 interface ValueOps {
     /** The text of the string the source wrote, or null for anything else. */
     text(): string | null;
     /**
-     * What this value is called, when the source names it rather than
-     * writing it out. A queue URL is nearly always
+     * The name of this value, when the source refers to it by name instead
+     * of writing it out. A queue URL is nearly always
      * `process.env.ORDERS_QUEUE_URL`, so the value only exists at deploy
-     * time and the env var's name is what both sides of the boundary
-     * agree on. `"reference"` gives that name back, `"nothing"` gives
-     * null for anything the source does not settle.
+     * time and both sides of the boundary use the env var's name.
+     * `"reference"` returns that name, and `"nothing"` returns null for
+     * anything the source does not settle.
      */
     name(unsettled: UnsettledName): string | null;
+    /**
+     * Every string this value can be, when the source limits it to a
+     * few. `` `record.${op}` `` with `op` typed `"a" | "b"` is
+     * `record.a` and `record.b`. Null when part of it could be anything,
+     * or when there are more than `cap`. An adapter that has not
+     * implemented this leaves it out, and a reader has only `name`.
+     */
+    names?(cap: number): readonly string[] | null;
     /**
      * The yes or no the source wrote here, or null for anything else. A
      * library that asks which fields a call wants states them as a map of
@@ -3061,16 +3181,17 @@ interface ValueOps {
      * a call is null rather than being dropped, so the two lists stay in
      * step.
      *
-     * What a hole comes to is the pack's to say. This says what was
-     * there, so a query that hands over a table object can still be read.
+     * What a hole means is up to the pack. This only reports what was
+     * written there, so a query that interpolates a table object can still
+     * be read.
      */
     holes(): readonly (CallOps | null)[];
     /**
      * The same holes as values, in the same order, for a reader that
      * wants what the source settled a hole to rather than what call was
-     * written there. A table kept in a module constant is the case: the
-     * hole is a name, not a call, so `holes` gives null for it and this
-     * gives the constant.
+     * written there. A table name kept in a module constant needs this:
+     * the hole is a name, so `holes` gives null for it and this gives the
+     * constant.
      *
      * An adapter that has not implemented this leaves it out, and a
      * reader then has only the calls.
@@ -3097,7 +3218,7 @@ interface ValueEntry {
  *
  * Two members give back another `CallOps`, which is how these questions
  * reach a call next to this one. A chain of calls and a command object
- * are both these same questions asked one step along, so neither needed
+ * are both these same questions asked one step along, so neither needs
  * a question of its own.
  */
 interface CallOps {
@@ -3106,11 +3227,9 @@ interface CallOps {
     /** Whether the receiver came from where the origin says. */
     receiverIsFrom(origin: ReceiverOrigin): boolean;
     /**
-     * Whether the call itself came from where the origin says, which is
-     * the same question asked of the callee rather than of what it was
-     * called on. `new GetCommand(...)` is the case: a pack that steps to
-     * an argument asks this of it before reading anything, so it never
-     * reads an argument that was never the one.
+     * Whether the callee itself came from where the origin says. A pack
+     * that steps to an argument such as `new GetCommand(...)` asks this
+     * first, so it never reads a command from some other library.
      */
     isFrom(origin: ReceiverOrigin): boolean;
     /** How many arguments the call passes. */
@@ -3132,6 +3251,23 @@ interface CallOps {
      * class, the same as any other call.
      */
     argument(index: number): CallOps | null;
+    /**
+     * Said by a chain that steps to the arguments of every call it sees,
+     * before it reads the first one: at every call the walk visits, it
+     * will read the arguments from `first` through `last`, or to the end
+     * when `last` is left out. An adapter that asks a separate question
+     * for each read can ask about all of them at once. Leaving it out
+     * changes how fast a run is and nothing else.
+     */
+    readingArguments?(first: number, last?: number): void;
+    /**
+     * Said by a chain before it asks what made a receiver: at every call
+     * the walk visits whose method is one of `methods`, spelled as the
+     * source spells it, it will ask about the receiver. An adapter can
+     * then ask about all of them at once, and leaving it out changes only
+     * how fast a run is.
+     */
+    readingReceivers?(methods: ReadonlySet<string>): void;
     /**
      * The call the callee itself was written as, or null when nothing
      * wrote it as one. A class a factory made is the case: `new
@@ -3154,7 +3290,7 @@ interface CallOps {
      */
     parameterReadsAt?(index: number): readonly string[] | null;
     /**
-     * What a named property of the object an argument states says. A
+     * One property of the object literal passed at this position. A
      * property bag is not a call, so nothing else here reaches into one.
      */
     propertyAt(index: number, property: string, unsettled: UnsettledName): string | null;
@@ -3167,13 +3303,42 @@ interface CallOps {
     valueAt(index: number): ValueOps | null;
     /**
      * The one call behind the receiver the origin accepts, however many
-     * name, construction, or query hops separate them. Mongoose's
-     * `model(...)` behind a document is the picture. Null when nothing
+     * name, construction, or query hops separate them, such as Mongoose's
+     * `model(...)` behind a document. Null when nothing
      * behind the receiver matches, when two distinct calls do (picking
      * one would depend on the order facts arrived), and for an origin
      * kind with no construction to hand back.
      */
     anchorCall?(origin: ReceiverOrigin): CallOps | null;
+    /**
+     * The class the argument in this position refers to, or null when it
+     * refers to none the run declares. An ORM that takes an entity class,
+     * `InjectRepository(Order)`, keeps the table on the class itself.
+     */
+    classAt?(index: number): ClassOps | null;
+    /**
+     * Said by a recognizer about an effect it built from this call: the
+     * value the call states for each column the effect writes or picks
+     * rows by. The adapter asks where each value came from and records it
+     * on the transition. Leaving it out changes only that record.
+     */
+    statesSlots?(effect: Effect, slots: readonly StatedSlot[]): void;
+}
+/** A column an effect writes or picks rows by, and the value stated for it. */
+interface StatedSlot {
+    readonly slot: "field" | "selector";
+    readonly name: string;
+    readonly value: ValueOps;
+}
+/** One class a call refers to, as the questions a pack can ask about it. */
+interface ClassOps {
+    /** The name the class is declared under, or null when it has none. */
+    name(): string | null;
+    /**
+     * The one decorator call on the class that the origin accepts, such
+     * as `@Entity("orders")`. Null when none does, or when two do.
+     */
+    decorator(origin: ReceiverOrigin): CallOps | null;
 }
 /**
  * The property an adapter puts its ops on, in the context it hands a
@@ -3194,26 +3359,27 @@ interface AstCapableOps extends CallOps {
 }
 
 /**
- * The assembly engine: a `RawCodeStructure` from a language adapter goes in,
- * a `BehavioralSummary` comes out. The package README explains where that step
- * fits in the pipeline.
+ * The assembly engine. A language adapter hands over a `RawCodeStructure`,
+ * and `assembleSummary` turns it into a `BehavioralSummary`. The package
+ * README explains where that step fits in the pipeline.
  *
- * Two things surprise people reading this file. First, `RawCodeStructure` and
- * the raw types around it are the contract every adapter and pack implements,
- * so a field added here is a change to that contract. Second, this is the only
- * module allowed to turn a `Reading` into a claim on a summary; adapters hand
- * readings over uncollapsed and the rule for collapsing them lives here.
+ * `RawCodeStructure` and the raw types around it are the contract every
+ * adapter and pack implements, so adding a field here changes that
+ * contract. This is also the only module that turns a `Reading` into a
+ * claim on a summary. Adapters pass readings over uncollapsed, and the rule
+ * for collapsing them is below.
  */
 
 interface RawParameter {
     name: string;
     position: number;
     /**
-     * What the parameter is for, in the library's own vocabulary. When the
-     * adapter could not tell, this is null rather than a guess, and the reason
-     * goes in `readings`.
+     * What the parameter is for, in the library's own vocabulary. Null when
+     * the adapter could not tell, with the reason in `readings`.
      */
     role: string | null;
+    /** Which field of the role's value the parameter is, when the library hands over one field. */
+    field?: string;
     typeText: string | null;
 }
 interface RawCondition {
@@ -3223,7 +3389,7 @@ interface RawCondition {
     source: ConditionSource;
 }
 interface RawTerminal {
-    kind: "response" | "throw" | "return" | "render" | "delegate" | "emit" | "void";
+    kind: "response" | "throw" | "return" | "render" | "delegate" | "emit" | "void" | "exit";
     statusCode: {
         type: "literal";
         value: number;
@@ -3302,7 +3468,7 @@ type RawEffect = {
     callee: string;
     args: EffectArg[];
     async: boolean;
-    /** Empty means the call always fires, not that nobody looked. */
+    /** An empty list means the call is not under any guard, so it always fires. */
     preconditions?: RawCondition[];
 } | {
     type: "emission";
@@ -3320,6 +3486,8 @@ interface RawBranch {
      * `RawEffect` conversion that `effects` goes through.
      */
     extraEffects?: Effect[];
+    /** Where the values in the slots of `extraEffects` came from. */
+    provenance?: RawProvenance[];
     location: {
         start: number;
         end: number;
@@ -3340,6 +3508,17 @@ interface RawBranch {
      */
     bodyShapeReading?: DefaultedReading<TypeShape>;
 }
+/**
+ * Where the value in one slot came from, keyed by the effect object an
+ * adapter put in `extraEffects`. Assembly folds repeated effects, so it
+ * works out each effect's position only once the list is final.
+ */
+interface RawProvenance {
+    effect: Effect;
+    slot: ProvenanceSlot["slot"];
+    name: string;
+    from: ValueRef[];
+}
 interface RawDependencyCall {
     name: string;
     assignedTo: string | null;
@@ -3420,14 +3599,14 @@ interface RawCodeStructure {
     bodyContent?: BodyContent;
     dependencyCalls: RawDependencyCall[];
     /**
-     * Reads the adapter saw in the body that never flow into a condition
-     * or an output value, a render tree's `props.title` say. Merged into
-     * `inputReads` beside the derived ones.
+     * Reads the adapter saw in the body that never flow into a condition or
+     * an output value, such as a render tree's `props.title`. They are merged
+     * into `inputReads` with the ones derived from conditions and outputs.
      */
     extraInputReads?: InputRead[];
     declaredContract: RawDeclaredContract | null;
-    /** The property a consumer goes through to get at the body, `data` for
-     * axios say, so the checker can unwrap it without knowing each pack. */
+    /** The property a consumer reads the body through, such as `data` for
+     * axios, so the checker can unwrap it without a rule per pack. */
     bodyAccessors?: string[];
     /** The same, for the status: `status` for fetch and for axios. */
     statusAccessors?: string[];
@@ -3451,6 +3630,8 @@ interface RawCodeStructure {
     wrappers?: WrapperReference[];
     /** Where a REST pack's handlers read each part of the request, from the pack. */
     requestSpelling?: RequestSpellingMetadata;
+    /** What a test pack found about a `test` unit: whether it is skipped, and what it replaces with a mock. */
+    test?: TestMetadata;
     /** The extractor cannot derive this. An adapter that has the SDL and knows
      * which field the resolver serves fills it in. */
     graphqlDeclaredContract?: GraphqlDeclaredContract;
@@ -3508,4 +3689,4 @@ declare function rawConditionToPredicate(c: RawCondition): Predicate;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-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, type WrapperMethodRegistration, type WrapperOptionRegistration, type WrapperRegistration, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, buildUngatedExtractionReport, commonDirectoryOf, 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 };
+export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type ArgumentParser, 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 ClassOps, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DeclaredModule, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, EnclosingNodes, type ExitKind, type ExtractionConfig, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type GlobalPrefixCall, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, KeptParses, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_PATHS, MODULE_SURFACE_RECOGNITION, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type ParameterSupplier, type ParsedNode, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawProvenance, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, SKIP_CHILDREN, type SettledModule, type SourceRange, type SourceSpelling, type StatedSlot, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TestCaseMatch, type Timer, type TimingReport, type TransparentWrapper, type UnitRecord, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkEnd, type WalkableNode, type WrapperMethodRegistration, type WrapperOptionRegistration, type WrapperRegistration, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, buildUngatedExtractionReport, commonDirectoryOf, composeWrappers, computeContentHash, computeDistHashFrom, configuredCallOption, createAdapterStamp, createCacheLayer, createPackTallies, createTimer, detectGaps, effectToIR, emptyTally, enumerateOrDegrade, enumerateStructuredPaths, evaluatePackHealth, extractionConfigStamp, firstWrittenReading, formatPackHealth, guardsHoldOn, httpRouteDiscovery, isListedTestFile, makeTransitionId, mapReading, markReturnsAsExitCode, matchesTestFileName, moduleInitStructure, moduleOfFile, noopTimer, packGradients, paramToInput, projectFileStamp, rawConditionToPredicate, recordPackFailure, registrationHelperDiscovery, routeHelperIndex, runDigest, runsBefore, scopeOption, settleModules, sharedGatingConditions, sourceRefsOf, stampMayMissAWrite, stampModuleImports, stampModules, storageSystemOption, summaryCountsByPack, tallyUnit, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };