@suss/extractor 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,260 @@
-import { Effect, MessageBusSemantics, DeployableUnit, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, Predicate, BehavioralSummary, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+
+/**
+ * The language-neutral form the path engine walks: statement kind, condition
+ * handle, children, and exit kind. Each language's adapter lowers its own AST
+ * into this, and the path enumeration never touches a language-specific node
+ * 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
+ * to parse afterwards, and never looks inside it.
+ */
+/** Where a condition came from, in terms of what that branch's body does. */
+type ConditionSource = "explicit" | "earlyReturn" | "earlyThrow" | "catchBlock";
+/** Whether a statement's own subtree leaves the unit by returning or throwing. A throw anywhere beats a return anywhere. Never set for break or continue. */
+type ExitKind = "return" | "throw" | null;
+/**
+ * A test the engine passes through without looking inside: its display text
+ * plus the language's own expression handle. The handle is null for a
+ * synthetic condition, such as a loop's "some iteration of" marker or a
+ * switch group's disjunction text.
+ */
+interface ConditionHandle<Cond> {
+    readonly sourceText: string;
+    readonly expression: Cond | null;
+}
+/** One condition attached to a caller-visible transition. */
+interface ConditionInfo<Cond> {
+    readonly sourceText: string;
+    readonly polarity: "positive" | "negative";
+    readonly source: ConditionSource;
+    readonly expression: Cond | null;
+}
+/** A statement list: an if arm, a loop body, a try/catch/finally block. */
+type StatementBlock<Cond> = readonly StructuredStatement<Cond>[];
+/**
+ * One switch or match case group, already merged out of the language's own
+ * grammar (TypeScript stacks several empty-bodied labels on top of the
+ * clause that finally has a body, and the lowering step folds that
+ * into one group with a joined condition). `condition` is null for the
+ * default or wildcard group. `body` has any language-specific
+ * statement that ends a fallthrough (a trailing break) already stripped
+ * out, and `hasTrailingBreak` records whether one was there.
+ */
+interface CaseGroup<Cond> {
+    readonly condition: ConditionHandle<Cond> | null;
+    readonly hasTrailingBreak: boolean;
+    readonly body: StatementBlock<Cond>;
+}
+/**
+ * One statement in the unit's control flow, already lowered out of the
+ * source language. Every variant has the same four things on it:
+ * `kind` says which construct it is, `condition` (where
+ * one applies) is the opaque test, the block and group fields are its
+ * children, and `exitKind` is worked out by the lowering step (a deep
+ * scan of the statement's own subtree for a return or throw, skipping
+ * nested function bodies, the same scan every language needs in order to
+ * tell an early return from an early throw).
+ */
+type StructuredStatement<Cond = unknown> = {
+    readonly kind: "if";
+    readonly condition: ConditionHandle<Cond>;
+    readonly thenBody: StatementBlock<Cond>;
+    /** null when the source has no else/elif tail at all. */
+    readonly elseBody: StatementBlock<Cond> | null;
+    readonly exitKind: ExitKind;
+} | {
+    readonly kind: "switch";
+    /** Source order; at most one group has a null (default) condition. */
+    readonly groups: readonly CaseGroup<Cond>[];
+    readonly exitKind: ExitKind;
+} | {
+    readonly kind: "loop";
+    /** Display text for the loop header. The engine builds two synthetic conditions out of it: "some iteration of: ..." and "loop exited via ...: ...". */
+    readonly condition: ConditionHandle<Cond>;
+    readonly body: StatementBlock<Cond>;
+    readonly exitKind: ExitKind;
+} | {
+    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. */
+    readonly finallyBody: StatementBlock<Cond> | null;
+    readonly exitKind: ExitKind;
+} | {
+    readonly kind: "exit";
+    readonly exit: "return" | "throw" | "break" | "continue";
+    readonly exitKind: ExitKind;
+} | {
+    /** Anything else: expression statements, declarations, and any statement the enumeration does not branch on. */
+    readonly kind: "opaque";
+    readonly exitKind: ExitKind;
+};
+
+/**
+ * `Reading<T>`: what a reader found, in the four states a source can leave a
+ * 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
+ * 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.
+ *
+ * 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.
+ */
+/** Where in a file a value is written, as byte offsets into that file. */
+interface SourceRange {
+    start: number;
+    end: number;
+}
+/**
+ * What a reader found where a value could be. `written` is the only state
+ * with a value a summary may claim, and the other three each say something
+ * different about why there is no claim to make.
+ */
+type Reading<T> = {
+    kind: "written";
+    value: T;
+    range: SourceRange;
+} | {
+    kind: "absent";
+} | {
+    kind: "unreadable";
+    reason: string;
+    range: SourceRange;
+} | {
+    kind: "ambiguous";
+    candidates: readonly T[];
+    reason: string;
+    range: SourceRange;
+};
+/** The source gives this value, here, and the reader read it. */
+declare function writtenReading<T>(value: T, range: SourceRange): Reading<T>;
+/**
+ * The source says nothing where this value could be. A library that defines
+ * a default for it may still supply one, and the summary builder applies
+ * that default only when a pack declares it as data.
+ */
+declare const absentReading: Reading<never>;
+/**
+ * The source gives the value and the reader could not evaluate it. The
+ * reason is the sentence somebody reading the summary will see, so write it
+ * about what could not be read rather than about the code.
+ */
+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.
+ *
+ * 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),
+ * so give the site the reading was taken at, the same one an `unreadable`
+ * reading here would have given.
+ */
+declare function ambiguousReading<T>(candidates: readonly T[], reason: string, range: SourceRange): Reading<T>;
+/**
+ * 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.
+ */
+interface DefaultedReading<T> {
+    /** What the source said. */
+    reading: Reading<T>;
+    /**
+     * The value the library applies when the source gives none, as the pack
+     * declared it. Leave it out when the library defines no default, and then
+     * a source that says nothing gets no claim.
+     */
+    libraryDefault?: T;
+}
+/**
+ * The same reading with its value in another form. A written value goes
+ * through `f` and keeps its range. An ambiguous reading's candidates go
+ * through `f` too, so the alternatives end up in the same form as the
+ * chosen value would. Absent and unreadable readings pass through
+ * unchanged, since neither one has a value to convert.
+ */
+declare function mapReading<T, U>(reading: Reading<T>, f: (value: T) => U): Reading<U>;
+/**
+ * Read further from what this reading found. `f` runs on a written
+ * value with the range it was written at, so a step that turns out to
+ * be unreadable can say so against the same syntax.
+ *
+ * `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.
+ */
+declare function andThenReading<T, U>(reading: Reading<T>, f: (value: T, range: SourceRange) => Reading<U>): Reading<U>;
+/**
+ * Which of several readings a claim comes from, for a value a library lets
+ * a source give in more than one place.
+ */
+interface ChosenReading<T> {
+    /**
+     * The reading a claim comes from: the first that was written, or if none
+     * was, the first that failed to read, or absent when all of them were
+     * absent.
+     */
+    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.
+     */
+    passedOver: readonly Reading<T>[];
+}
+/**
+ * Choose among readings of the same value, taking the first that was
+ * written. Nothing is thrown away: whatever the choice passed over and
+ * could not read comes back next to it in `passedOver`, so a
+ * `response_model` nobody could read still lands as a gap even when the
+ * return annotation after it supplies the type.
+ */
+declare function firstWrittenReading<T>(readings: readonly Reading<T>[]): ChosenReading<T>;
+/**
+ * What a written reading found, for a reader that has to read further from
+ * it before anything is claimed. A route's path template gives the
+ * 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.
+ *
+ * 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.
+ */
+declare function valueToReadFurtherFrom<T>(reading: Reading<T>): T | null;
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
 
 type DiscoveryMatch = {
     type: "namedExport";
@@ -20,7 +276,7 @@ type DiscoveryMatch = {
     type: "clientCall";
     /** Module the client is imported from, or "global" for built-ins like fetch */
     importModule: string;
-    /** Named export or identifier — e.g. "initClient", "fetch" */
+    /** Named export or identifier, for example "initClient" or "fetch" */
     importName: string;
     /** If set, only match calls to these methods on the client (e.g. ["getUser"]).
      *  Unset means any method call (or bare call for globals). */
@@ -37,11 +293,11 @@ type DiscoveryMatch = {
 } | {
     /**
      * A constructor or factory call that takes a configuration object
-     * containing a resolver map — the idiomatic GraphQL code-first
-     * shape. The map is two levels deep: outer keys are GraphQL type
-     * names (`Query`, `Mutation`, `Subscription`, or object-type
-     * names like `User`); inner keys are field names whose values
-     * are resolver functions.
+     * 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.
      *
      * Example (Apollo Server v4):
      * ```ts
@@ -56,41 +312,42 @@ type DiscoveryMatch = {
      * ```
      *
      * Each inner function becomes one discovered unit whose binding
-     * semantics is `graphql-resolver(typeName, fieldName)`. Matches
-     * both `new Ctor(cfg)` and `ctor(cfg)` — Apollo's standalone
-     * server uses `new`, yoga uses a bare call.
+     * 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.
      */
     type: "resolverMap";
     importModule: string;
     importName: string;
     /**
-     * Name of the property on the config object that holds the
-     * resolver map. Defaults to `"resolvers"` when unset, matching
-     * Apollo / yoga / graphql-tools convention.
+     * 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"`.
      */
-    mapProperty?: string;
+    mapProperty: string;
     /**
-     * GraphQL type names whose fields we DON'T treat as resolvers —
-     * opt-out for meta-types like `Subscription` that we may want
-     * to handle differently later. Unset means discover every type.
+     * 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.
      */
     excludeTypes?: string[];
 } | {
     /**
-     * Consumer-side GraphQL hook call — the canonical Apollo Client
-     * and urql shape. Each call to one of the listed hooks becomes
+     * 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?)`.
      *
-     * The document argument resolves through several shapes: an inline
-     * `gql`-tagged template, a const binding (same module or imported
-     * from another module), a `.graphql` / `.gql` file import, and a
+     * 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 isn't statically readable,
+     * client-preset. When the document body cannot be read statically,
      * the operation header falls back to the `TypedDocumentNode` type
-     * arguments; a still-unresolvable document surfaces on the summary
-     * as `metadata.graphql.unresolvedDocument` rather than dropping the
-     * boundary.
+     * 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
@@ -102,21 +359,21 @@ type DiscoveryMatch = {
      * }
      * ```
      *
-     * The adapter records the operation name / type on the
-     * DiscoveredUnit's `operationInfo`; binding construction uses that
+     * 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`
-     * is authoritative when the document header can't be read (mirrors
-     * `graphqlImperativeCall.methods`).
+     * wins when the document header cannot be read, the same way
+     * `graphqlImperativeCall.methods` does.
      */
     type: "graphqlHookCall";
     importModule: string;
     /**
-     * Hooks to match on that import, each mapped to the operation
-     * type it performs (`useQuery` → query, `useMutation` → mutation,
-     * `useSubscription` → subscription). The mapping supplies the
-     * operation type when the document body isn't statically readable.
-     * Each hook is reported as `kind = "client"` by default; packs can
-     * override via the enclosing `DiscoveryPattern.kind`.
+     * 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: Array<{
         hookName: string;
@@ -124,22 +381,21 @@ type DiscoveryMatch = {
     }>;
 } | {
     /**
-     * Imperative Apollo-Client-style call — `client.query({ query })`,
-     * `client.mutate({ mutation })`, `client.subscribe({ query })`.
-     * Distinct from hook calls because the document lives on a
-     * config-object property rather than the first positional arg.
-     * Discovery is gated on an import of the named constructor
-     * (typically `ApolloClient`) to reduce false positives — any
-     * method-named "query" on a random object could look like this
-     * shape.
+     * 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.
+     *
+     * 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 name that gets
-     * called on the client (`"query"` / `"mutate"` / `"subscribe"`)
-     * and the config-object property that holds the gql document
-     * (`"query"` / `"mutation"` / `"query"` respectively). The
-     * method name drives the operation type (query / mutation /
-     * subscription) when the gql document's header is anonymous;
-     * a named document's header wins otherwise.
+     * 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.
      */
     type: "graphqlImperativeCall";
     importModule: string;
@@ -152,55 +408,53 @@ 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 — provider side of an in-process `function-call`
-     * boundary.
+     * 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.
      *
-     * Produced bindings carry identity
+     * The bindings this produces have the identity
      * `{ transport: "in-process",
      *    semantics: { name: "function-call",
      *                 package: <pkg.name>,
      *                 exportPath: [...] },
      *    recognition: <pack.name> }`.
      *
-     * Sub-path exports identify as e.g.
-     * `@suss/behavioral-ir/schemas::BehavioralSummarySchema` —
-     * `exportPath = ["schemas", "BehavioralSummarySchema"]`.
-     * Root exports omit the sub-path segment.
+     * 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.
      *
-     * v0 scope: resolves `types` / `default` / `import` conditions
-     * on `exports`, falls back to `types` + `main` + `module`
-     * when no `exports` field is set. Pattern exports (`./utils/*`)
-     * and `development`-conditional resolution are deferred.
+     * 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.
      */
     type: "packageExports";
     /** Absolute path to the package's `package.json`. */
     packageJsonPath: string;
     /**
-     * Restrict to these `exports` keys (without leading `./`).
-     * The root export is keyed `"."`. Unset means all resolvable
-     * sub-paths.
+     * Restrict to these `exports` keys (without the leading `./`). The
+     * root export is keyed `"."`. Leave it unset for every sub-path that
+     * resolves.
      */
     subPaths?: string[];
     /**
-     * Export names to skip — typically `["default"]` when a pack
-     * wants to treat default exports separately or not at all.
+     * Export names to skip, usually `["default"]` when a pack wants to
+     * treat default exports separately or ignore them.
      */
     excludeNames?: string[];
 } | {
     /**
-     * Class methods that carry a specific decorator, on classes that
-     * carry a specific class-level decorator. Used by NestJS-style
-     * frameworks where resolvers / handlers / controllers are
-     * declared by decorator, not by registering a function in an
-     * object literal.
+     * 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 gates on an `importModule` of `classDecorator` and
-     * each `methodDecorators` entry — random user-defined decorators
-     * with the same names won't trip the matcher.
+     * 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",
@@ -208,75 +462,73 @@ type DiscoveryMatch = {
      *    methodDecorators: ["Query", "Mutation", "ResolveField",
      *                       "Subscription"] }`
      *
-     * The adapter populates `DiscoveredUnit.resolverInfo` so the
-     * produced binding carries `graphql-resolver(typeName, fieldName)`.
+     * The adapter fills in `DiscoveredUnit.resolverInfo` so the binding
+     * comes out as `graphql-resolver(typeName, fieldName)`.
      * `typeName` resolves from the class decorator's first argument
-     * (`@Resolver(() => User)` → `"User"`), and from
+     * (`@Resolver(() => User)` gives `"User"`), or from
      * `methodDecoratorTypeMap` when the class decorator has no
-     * argument. `fieldName` reads the method decorator's `{ name }`
-     * option override when present, otherwise the method name.
+     * argument. `fieldName` comes from the method decorator's `{ name }`
+     * option when that is set, and otherwise from the method name.
      */
     type: "decoratedMethod";
     /**
-     * The module a pack-recognised decorator must be imported from
-     * for discovery to fire. Codebases sometimes wrap framework
-     * decorators in their own re-exports, composing the framework's
-     * decorator with extra metadata. When that happens, the
-     * import-module gate would miss them; pass an array of accepted
-     * modules and any one match suffices.
+     * 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.
      */
     importModule: string | string[];
     /**
-     * Class decorator names to recognise. The first entry that
-     * appears on a class wins for typeName extraction (the rest are
-     * fallbacks for codebases with multiple wrapper styles). A pack
-     * ships only what its own framework declares here and takes a
-     * project's wrappers through its options.
+     * 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.
      */
     classDecorators: string[];
     methodDecorators: string[];
     /**
-     * Method decorator name → the type its field hangs off when the
-     * class decorator names none. NestJS puts `@Query` on the root
-     * `Query` type and `@Mutation` on `Mutation` whatever the class
-     * says, so those two answer for themselves.
+     * Maps a method decorator to the type its field belongs to when the
+     * class decorator does not say. NestJS puts `@Query` on the root
+     * `Query` type and `@Mutation` on `Mutation` no matter what the class
+     * says, so those two settle it themselves.
      *
-     * A decorator the map leaves out has no answer of its own, and a
-     * class that names no type leaves the field's owner unread. The
-     * binding then names no type and pairs with nothing, rather than
-     * claiming a field the schema does not have.
+     * 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.
      */
     methodDecoratorTypeMap: Record<string, string>;
 } | {
     /**
-     * NestJS-style REST controller discovery. Class decorated with
-     * `@Controller(pathPrefix?)`; methods decorated with
-     * `@Get(subpath?)` / `@Post` / `@Put` / `@Delete` / etc. The
-     * decorator NAME determines the HTTP method via
-     * `methodDecoratorRouteMap`; the route path is the class
-     * decorator's first arg + the method decorator's first arg
-     * (slash-joined, both optional).
+     * 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.
      *
-     * Same wrapper-decorator tolerance as `decoratedMethod`: the
-     * import-module gate fires on at least one method-route
-     * decorator from the framework module, but class decorators
-     * match by name only, so a project-internal wrapper composing
-     * the framework's decorator matches once the project names it
-     * in the pack's options.
+     * 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 populates `DiscoveredUnit.routeInfo` so the
-     * produced binding carries `rest(method, path)`.
+     * The adapter fills in `DiscoveredUnit.routeInfo` so the binding comes
+     * out as `rest(method, path)`.
      */
     type: "decoratedRoute";
     importModule: string | string[];
     classDecorators: string[];
     /**
-     * Decorator name → HTTP method. NestJS uses one decorator per
-     * verb (`@Get` / `@Post` / `@Put` / `@Delete` / `@Patch` /
-     * `@Options` / `@Head` / `@All`); other frameworks may follow
-     * the same convention. The values become the `method` field on
-     * the produced REST binding; `"*"` is acceptable for catch-all
-     * decorators.
+     * 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.
      */
     methodDecoratorRouteMap: Record<string, string>;
 } | {
@@ -291,15 +543,15 @@ type DiscoveryMatch = {
      *   ];
      *   for (const r of routes) app[r.method](r.path, r.handler);
      *
-     * `elementShape` declares which keys on each element carry the
-     * method, path, and handler. The loop body is required to
-     * contain at least one call expression that references the
-     * loop variable (filters out unrelated loops); the call's
-     * shape itself is not checked beyond that.
+     * `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.
      *
-     * Iterables that resolve to an `ArrayLiteralExpression` (inline
-     * or single-hop `const`-bound) are expanded; cross-file or
-     * computed iterables are out of v0 scope.
+     * 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.
      *
      * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
      */
@@ -311,11 +563,11 @@ type DiscoveryMatch = {
     };
 } | {
     /**
-     * Helper-call expansion: a single function call at the user
-     * site is treated as if it were N inline registrations, with
-     * arguments substituted into per-registration templates. Used
-     * for patterns like `registerCrud(app, 'users', userHandlers)`
-     * that today's `registrationCall` discovery can't see.
+     * 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
@@ -325,9 +577,9 @@ type DiscoveryMatch = {
      * 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 a specific module — useful when two packages
-     * happen to export a function with the same name.
+     * `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.
      *
      * Pack-author docs: `docs/internal/proposals/dynamic-registration.md`.
      */
@@ -341,23 +593,94 @@ type DiscoveryMatch = {
     }>;
 } | {
     /**
-     * Consumer side of the package-export boundary. Scans source
-     * files for imports of the named packages and records every
-     * call site, emitting one `caller`-kind unit per enclosing
-     * function. Produced bindings carry
-     * `function-call { package, exportPath }` matching the
-     * provider summaries from `packageExports`.
+     * 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).
+     *
+     * 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.
+     */
+    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.
+     */
+    importModule: string | string[];
+    /** The route element's exported name. */
+    routeElement: string;
+    /** The attribute with the route's path pattern on it. */
+    pathAttribute: string;
+    /** The attribute with the JSX the route renders on it. */
+    elementAttribute: string;
+    /**
+     * The attribute that marks an index route, which renders at its
+     * parent's path. Leave it unset if the library has no index routes.
+     */
+    indexAttribute?: string;
+    /**
+     * The property with the routes nested under a route object on it,
+     * which is how the object form expresses what the JSX form expresses
+     * by nesting. Paths compose the same way in both. Leave it unset if
+     * the library's route objects do not nest.
+     */
+    childrenAttribute?: string;
+    /**
+     * Factory functions whose first argument is an array of route
+     * objects keyed by the same three attribute names. The array is read
+     * where it is written, or through the same value resolution the rest
+     * of discovery uses, so a `const` binding one hop away works the
+     * same as an inline literal.
+     */
+    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.
+     */
+    elementsFactories?: string[];
+    /**
+     * The HTTP method recorded on each route binding this produces. A page
+     * route serves navigations, and the pack has to say which method those
+     * use rather than the adapter assuming one.
+     */
+    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` is a list of exact package names (possibly with a
-     * sub-path, e.g. `"@suss/behavioral-ir/schemas"`) whose imports
-     * to track. Pass multiple package names to track a family at
+     * `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.
      *
-     * v0 scope: named imports + default imports. Namespace imports
-     * (`import * as X from`) are not yet tracked. Re-imports within
+     * 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,
-     * not the original — full symbol resolution is deferred.
+     * re-exports from pkg) produce units against the intermediate rather
+     * than the original, because full symbol resolution is not built yet.
      */
     type: "packageImport";
     packages: string[];
@@ -366,6 +689,13 @@ type BindingExtraction = {
     method: {
         type: "fromRegistration";
         position: "methodName" | number;
+        /**
+         * Registrations whose recorded method is something other than their
+         * own name uppercased, the way `.all` registers every method and is
+         * recorded as `"*"`. Anything missing from the map is recorded as
+         * its own name uppercased.
+         */
+        nameMap?: Record<string, string>;
     } | {
         type: "fromExportName";
     } | {
@@ -390,11 +720,11 @@ type BindingExtraction = {
         property: string;
     } | {
         /**
-         * The route path comes from where the file sits, which is how
-         * Next.js and React Router describe their routes. The pack
-         * spells out its own convention here, since 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, 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.
          *
          * `app/api/orders/[id]/route.ts` under `{ root: "app",
          * dropBasenames: ["route"], dynamic: "brackets" }` comes out as
@@ -403,14 +733,14 @@ type BindingExtraction = {
          */
         type: "fromFilename";
         /**
-         * Where a route path starts. The directories below it become
-         * the path; everything above it belongs to the project layout
-         * and is dropped.
+         * Where a route path starts. The directories below it become the
+         * path, and everything above it belongs to the project's own layout
+         * and gets dropped.
          */
         root: string;
         /**
-         * Filenames that say what a file is rather than adding a
-         * segment: `route`, `page`, `index`, `_index`.
+         * Filenames that say what kind of file it is rather than adding a
+         * path segment: `route`, `page`, `index`, `_index`.
          */
         dropBasenames?: string[];
         /**
@@ -424,8 +754,8 @@ type BindingExtraction = {
          */
         dropParenthesized?: boolean;
         /**
-         * Whether one filename holds the whole path with dots between
-         * the segments, as `routes/orders.$id.tsx` does.
+         * Whether one filename contains the whole path with dots between the
+         * segments, the way `routes/orders.$id.tsx` does.
          */
         flat?: boolean;
     } | {
@@ -443,22 +773,48 @@ interface DiscoveryPattern {
     match: DiscoveryMatch;
     bindingExtraction?: BindingExtraction;
     /**
-     * Files whose import declarations include any of these module
-     * specifiers (or sub-paths of them) get this pattern's discovery
-     * dispatch. Empty array = no gate (pattern is dispatched against
-     * every file). Undefined = treated as no gate, but pack authors
-     * SHOULD declare it explicitly — the `[]` form is the deliberate
-     * "match every file" choice (typically because the pattern keys on
-     * something other than imports — e.g. the fetch runtime matching
-     * global `fetch(...)` calls).
+     * 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.
      *
-     * Match semantics: prefix on the import module specifier. An entry
-     * `"@nestjs/graphql"` matches `from "@nestjs/graphql"` AND
-     * `from "@nestjs/graphql/dist/foo"` AND any other sub-path.
+     * 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
+     * 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.
+     */
+    mount?: {
+        /** Method name that registers a sub-router at a prefix, e.g. "use" or "route". */
+        method: string;
+        /** Argument position of the prefix string. */
+        prefixPosition: number;
+        /** Argument position of the mounted router/sub-app value. */
+        targetPosition: number;
+    };
+    /**
+     * 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.
      *
-     * Pre-filter is purely a perf optimisation: the closure walk and
-     * other post-passes still have access to every loaded file via
-     * symbol resolution.
+     * 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.
+     *
+     * 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.
      */
     requiresImport?: string[];
 }
@@ -471,8 +827,8 @@ type TerminalMatch = {
      * 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 prevents the same `return reply.send(...)` from producing
-     * two terminals — one from the wrapping returnStatement, one from
+     * 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.
      */
@@ -489,43 +845,43 @@ type TerminalMatch = {
     functionName: string;
     /**
      * Only match when the name was imported from one of these modules.
-     * Same name, shape, and prefix semantics as a DiscoveryPattern's
-     * gate: "react-router" also matches "react-router/server".
+     * The field works exactly like a DiscoveryPattern's gate, matching by
+     * prefix: "react-router" also matches "react-router/server".
      *
-     * Set it whenever the function belongs to a library, because
-     * matching a bare name claims every same-named function in the
+     * 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 produces a confident wrong answer.
+     * of those gives you a confident wrong answer.
      *
-     * Leave it unset only when the function is not a library's at all.
-     * A pack should generally not name a project's own helper: declare
-     * the envelope shape instead, through a `returnShape` terminal, and
+     * 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 helpers whatever they are
-     * named and in whichever argument order they were written.
+     * the helper's parameters. That covers a helper whatever it is called
+     * and whatever order its arguments come in.
      */
     requiresImport?: string[];
 } | {
     /**
-     * Return statement whose value is a JSX element or fragment. The
-     * root element/component name is recorded in RawTerminal.component.
-     * Used by React (and any other JSX-based framework pack) to
-     * classify component outputs as `render` terminals.
+     * A return statement whose value is a JSX element or fragment. The
+     * root element or component name is recorded in
+     * `RawTerminal.component`. React, and any other JSX-based framework
+     * pack, uses this to classify component output as a `render` terminal.
      */
     type: "jsxReturn";
 } | {
     /**
-     * Synthetic terminal for the implicit fall-through at the end of a
-     * function body. Fires when the function has no explicit
-     * `ReturnStatement` / `ThrowStatement` as its last statement —
-     * covers the common case of handler / effect bodies that execute
-     * side-effects and return `undefined` implicitly. Without this,
+     * 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. Packs that always expect
-     * explicit returns (HTTP handlers) shouldn't include this in
-     * their terminals; packs for callback bodies (React handlers,
-     * `useEffect` bodies, Node `.on(...)` callbacks) should.
+     * `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.
      */
     type: "functionFallthrough";
 };
@@ -568,15 +924,15 @@ interface TerminalPattern {
     extraction: TerminalExtraction;
 }
 interface ContractPattern {
-    /** How to find the contract object. Contracts are data structures, not code units,
-     *  so this is a simpler shape than DiscoveryPattern. */
+    /** How to find the contract object. A contract is a data structure rather
+     *  than a code unit, so this needs less than a DiscoveryPattern does. */
     discovery: {
         importModule: string;
         importName: string;
         registrationChain: string[];
     };
     responseExtraction: {
-        /** Property on the contract object that holds the responses map */
+        /** The property on the contract object with the responses map on it */
         property: string;
     };
     paramsExtraction?: {
@@ -606,14 +962,14 @@ type InputMappingPattern = {
      * Component props, React / Vue / Svelte-style: one parameter that
      * the caller destructures at will, with prop names only visible at
      * the call site. When the parameter is destructured, each bound
-     * name becomes its own Input with role equal to the name. When
-     * it's not destructured (e.g. `function X(props) {...}`), one
-     * Input is emitted with `wholeParamRole` (default `"props"`).
+     * name becomes its own Input with the name as its role. When it is
+     * not destructured (`function X(props) {...}`), a single Input comes
+     * out with `wholeParamRole`, which defaults to `"props"`.
      *
-     * Differs from `destructuredObject` in that prop names are not
-     * declared by the pack up-front — they are whatever the component
-     * author wrote. Differs from `singleObjectParam` in that the
-     * destructuring pattern is honored when present.
+     * This differs from `destructuredObject` because the pack does not
+     * declare the prop names up front; they are whatever the component
+     * author wrote. It differs from `singleObjectParam` because the
+     * destructuring pattern is respected when there is one.
      */
     type: "componentProps";
     paramPosition: number;
@@ -621,41 +977,42 @@ type InputMappingPattern = {
     wholeParamRole?: string;
 } | {
     /**
-     * Emit one `Input` per declared parameter, in source order, with
-     * `role = param name` (or `defaultRole` when set). Used by the
-     * reachable-closure pass for internal library functions — there
-     * is no framework-declared role space, so the caller-visible
-     * name IS the role. Captures destructured-parameter bindings the
-     * same way `destructuredObject` does, so `(ctx, { userId })`
-     * reads as two inputs: `ctx` and `userId`.
+     * 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 `destructuredObject` captures them, so `(ctx, { userId })`
+     * gives two inputs, `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 up its name in `decoratorRoleMap` —
-     * matched decorators map the parameter to that role; unmatched
-     * parameters fall back to `defaultRole` (or skip when unset).
+     * 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" }`.
      *
-     * Decorator gating is by name only — multiple frameworks
-     * defining `@Args` would all map. Packs that need to
-     * disambiguate by import module add it later when the use case
-     * justifies the cost.
+     * 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.
      */
     type: "decoratedParams";
     decoratorRoleMap: Record<string, string>;
     defaultRole?: string;
 };
 /**
- * What a property on the API response object semantically represents.
- * Declared in the pack so the adapter can resolve derived properties
- * (e.g. `.ok` → status range 200–299) at extraction time.
+ * What a property on the API response object means. The pack declares this so
+ * the adapter can work out a derived property at extraction time, the way
+ * `.ok` means a status somewhere in 200 to 299.
  */
 type ResponsePropertyMeaning = {
     type: "statusCode";
@@ -673,19 +1030,19 @@ interface ResponsePropertyMapping {
     name: string;
     /** How this member is accessed: property read or method call */
     access: "property" | "method";
-    /** What the value semantically represents */
+    /** What the value means */
     semantics: ResponsePropertyMeaning;
 }
 /**
- * A library wrapper whose result is the function it was handed. The
- * adapter works this out on its own for factories declared in the
- * project by reading their bodies. A library's body is not readable,
- * so the pack states it.
+ * A library wrapper that returns the function it was handed. For a factory
+ * declared inside the project, the adapter works this out on its own by
+ * reading the body. A library's body is not there to read, so the pack has to
+ * say so.
  */
 interface TransparentWrapper {
     /** Callee text as written, e.g. "Sentry.wrapHandler". */
     callee: string;
-    /** Which argument holds the wrapped function. */
+    /** Which argument the wrapped function is passed as. */
     argument: number;
     /**
      * The module the callee has to have been imported from. Without it a
@@ -705,9 +1062,9 @@ interface PatternPack {
      * 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 carries that responsibility
-     * itself. A pack with nothing to stamp reads as `"unset"`, and warm
-     * caches will answer for code that has since changed.
+     * 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.
      */
     version?: string;
     languages: string[];
@@ -717,29 +1074,29 @@ interface PatternPack {
     inputMapping: InputMappingPattern;
     /**
      * Transport (wire protocol) used in the `BoundaryBinding.transport`
-     * of discovered units. Every pack states its transport explicitly
-     * rather than leaning on a hardcoded HTTP default — "what 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 making the field required keeps future packs (React,
-     * GraphQL, Lambda-invoke, queues) from silently inheriting an
-     * HTTP-shaped default that doesn't fit.
+     * 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 populates `BoundaryBinding.recognition`
-     * on produced summaries — so `{ transport, recognition }` come from
-     * the pack directly, and `semantics` is derived by the adapter from
-     * the discovery pattern's binding-extraction rules.
+     * 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.
      */
     protocol: string;
     /**
-     * Semantics of properties on the API response object (consumer side).
-     * Tells the adapter how to resolve derived properties like `.ok` or
-     * `.json()` to structured IR constructs instead of leaving them opaque.
+     * What the properties on the API response object mean, consumer side.
+     * This tells the adapter how to turn a derived property like `.ok` or
+     * `.json()` into a structured IR construct instead of leaving it opaque.
      */
     responseSemantics?: ResponsePropertyMapping[];
     /**
-     * Synthesize additional code units from a parent unit's body —
-     * "one user-authored construct implicitly spawns multiple
-     * runtime-scheduled units." Used when a framework's runtime
+     * 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
@@ -747,53 +1104,53 @@ interface PatternPack {
      *
      * `ctx` is typed `unknown` here because the extractor has no
      * knowledge of which adapter is driving it; each language adapter
-     * defines its own context shape (e.g. `TsSubUnitContext` in
-     * `@suss/adapter-typescript`) with the primitives packs need to
+     * 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're written against — the cast is the explicit
-     * "this pack requires the TypeScript adapter" contract.
+     * context they were written against, and that cast is how a pack says
+     * out loud that it requires the TypeScript adapter.
      *
      * Returned units are fed through the adapter's extraction pipeline
      * the same way top-level discovered units are, so each becomes its
-     * own `BehavioralSummary`. Carry per-unit `terminals` and
-     * `inputMapping` on the `DiscoveredUnit` if the sub-unit's shape
-     * differs from the parent pack's defaults.
+     * own `BehavioralSummary`. Put per-unit `terminals` and `inputMapping`
+     * on the `DiscoveredUnit` when a sub-unit is written differently from
+     * the parent pack's defaults.
      */
     subUnits?: (parent: DiscoveredSubUnitParent, ctx: unknown) => DiscoveredSubUnit[];
     /**
-     * Pack-supplied top-level discovery callback. Sibling of `subUnits`
-     * for the discovery layer: when a framework's discovery convention
-     * doesn't fit one of the data-driven `DiscoveryMatch` variants (REST
+     * 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.
      *
-     * Use this for framework-specific shapes that don't generalize:
-     * React's component-export heuristic (PascalCase + JSX-return),
+     * 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. These are real conventions but
-     * baking each into the central `DiscoveryMatch` union forces every
-     * unrelated pack to know about them. Callbacks keep the central
-     * union for the generic primitives and let packs own their own
+     * `.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 `subUnits` — each
+     * `ctx` is typed `unknown` for the same reason as in `subUnits`: each
      * adapter ships its own context primitive (`TsDiscoveryContext` in
-     * `@suss/adapter-typescript`) and packs cast to whichever they're
-     * written against. The cast is the "I require the TS adapter"
-     * contract.
+     * `@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.
      *
-     * Returned units flow through the adapter's normal pipeline — they
-     * get terminals + effects extracted, sub-units synthesized, and
+     * 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` / `inputMapping` overrides on
-     * `DiscoveredUnit` work the same way.
+     * 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 cross-pack claim dedup in the adapter keeps the
-     * first claimant. Pack ordering in the framework list is the
-     * precedence signal.
+     * 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.
      */
     discoverUnits?: (sourceFile: unknown, ctx: unknown) => DiscoveredCustomUnit[];
     /**
@@ -804,77 +1161,77 @@ interface PatternPack {
      * 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 — the
-     * existing walker is intentionally narrow (only captures
-     * `invocation` effects from bare expression statements + container
+     * 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 don't have that concern; they fire on
+     * 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
+     * **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; the generic `invocation`
-     * effect is preserved either way (typed effects coexist with raw
-     * call capture so inspect rendering keeps callee text + args while
-     * the checker pairs on the typed shape). Returning `null` / `[]`
-     * is the no-match path.
+     * **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.
      *
-     * **Dedup is the recognizer's responsibility.** The dispatcher
-     * doesn't dedupe across calls. A recognizer that wants to fire
-     * once per identifier (e.g., to dedupe reads bound to a const
-     * that's used N times) tracks its own state across invocations.
+     * **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
-     * is logged to stderr with file path + line number and skipped
-     * for that call; the extraction continues. Buggy recognizers
-     * don't crash the run.
+     * **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). Recognizers cast both to the adapter context they're
-     * written against — same "this pack requires the TypeScript
-     * adapter" contract `subUnits` uses.
+     * 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.
      */
     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
-     * (prefix match — `"@aws-sdk/client-sqs"` matches that module
-     * AND any `"@aws-sdk/client-sqs/sub-path"`).
+     * (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, recognizer-only packs walk every file in the project —
-     * correct but wasted work on large monorepos where most files
-     * don't import the library.
+     * 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.
      *
-     * Discovery-pattern packs already have per-pattern `requiresImport`
-     * on `DiscoveryPattern`; this is the pack-level equivalent for
-     * packs whose ONLY mechanism is recognizers (no discovery).
+     * 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 / undefined means "no gate" — pack walks every file (the
-     * default for truly universal recognizers like `@suss/runtime-node`'s
-     * process-surface / env-var recognizers, since `process.*` is
-     * available without an import).
+     * 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).
      */
     requiresImport?: string[];
     /**
-     * Library wrappers whose result is the wrapped function. The adapter
-     * derives this automatically for project-local factories by reading
-     * their bodies; a library wrapper's body is not readable, so the
-     * pack states the judgment: a call to `callee` resolves to its
+     * 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.
@@ -882,21 +1239,21 @@ interface PatternPack {
      */
     transparentWrappers?: TransparentWrapper[];
     /**
-     * Per-property-access recognizers — sister to
-     * `invocationRecognizers` but firing on `PropertyAccessExpression`
+     * Per-property-access recognizers, the counterpart to
+     * `invocationRecognizers`, firing on `PropertyAccessExpression`
      * nodes rather than `CallExpression` nodes. 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, etc.
      *
-     * Same scope rules as invocationRecognizers — fires on every
-     * PropertyAccessExpression in the function body, skipping nested
-     * function bodies. Same emission contract: returned effects land
+     * The scope rules are the same as for invocationRecognizers: it fires
+     * on every PropertyAccessExpression in the function body and skips
+     * nested function bodies. The emission contract is the same, so effects
      * on the enclosing default-branch transition.
      *
-     * Same reasoning as invocationRecognizers for the opaque-arg /
-     * adapter-narrows pattern.
+     * The arguments are opaque here and narrowed by the adapter, for the
+     * same reason as in invocationRecognizers.
      */
     accessRecognizers?: AccessRecognizer[];
 }
@@ -911,12 +1268,12 @@ type InvocationRecognizer<TCtx = unknown> = (call: unknown, ctx: TCtx) => Effect
  */
 type AccessRecognizer<TCtx = unknown> = (access: unknown, ctx: TCtx) => Effect[] | null;
 /**
- * Minimal handle-shaped description of the parent code unit that
- * `subUnits` operates within. `func` is left opaque here — the
- * language adapter brands its own FunctionRoot type. This interface
- * lives in the extractor only so `PatternPack` can name it;
- * adapter-level context types (`TsSubUnitContext`) narrow `func` to
- * a concrete AST handle.
+ * 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.
  */
 interface DiscoveredSubUnitParent {
     /** Handle to the parent's function body. Opaque at extractor level. */
@@ -927,17 +1284,15 @@ interface DiscoveredSubUnitParent {
     kind: string;
 }
 /**
- * What a pack's `discoverUnits` hook returns per discovered top-level
- * unit. Mirrors `DiscoveredSubUnit` for the discovery layer — the
- * adapter widens these into its own internal `DiscoveredUnit` type
- * (which carries adapter-specific fields like `routeInfo`,
- * `packageExportInfo`, etc.) and pipes them through the normal
- * extraction pipeline.
+ * 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 stay in opaque-handle land — `func` is whatever the
- * adapter's primitive returns. Adapter-narrows this to its concrete
- * function-root type (e.g. `FunctionRoot` in
- * `@suss/adapter-typescript`).
+ * 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`).
  */
 interface DiscoveredCustomUnit {
     /** Function body handle, opaque here. */
@@ -959,15 +1314,15 @@ interface DiscoveredCustomUnit {
     /**
      * REST route identity for units a callback discovers against an
      * external manifest (a SAM/CFN template's `Events` block, an infra
-     * routing declaration, etc.) rather than an in-code registration.
-     * When set, the adapter builds a `rest` binding from `(method, path)`
-     * — the same binding NestJS controllers get via decorator-derived
-     * `routeInfo`, without the discoverUnits callback needing to reach
-     * into the adapter's binding machinery.
+     * 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.
      *
      * 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 the variants survive.
+     * per route. The adapter's per-file claim dedup keys on
+     * `(func, kind, method, path)`, so all of those variants survive.
      */
     routeInfo?: {
         method: string;
@@ -986,9 +1341,9 @@ interface DiscoveredCustomUnit {
         fieldName: string;
     };
     /**
-     * Message-bus channel identity for consumer units a callback
-     * discovers against a subject the code itself names (a handler
-     * factory whose config carries the expected subject). When set, the
+     * Message-bus channel identity for consumer units a callback discovers
+     * against a subject the code itself gives (a handler factory whose
+     * config states the subject it expects). When set, the
      * adapter builds a `message-bus` binding from `(messageBus, channel)`,
      * which pairs with producers sending on the same channel.
      */
@@ -1016,13 +1371,13 @@ interface DiscoveredSubUnit {
     /** Qualified name (e.g. "Counter.button.onClick"). */
     name: string;
     /**
-     * Terminal patterns to extract from this sub-unit's body. Defaults
-     * to `return` + `throw` when unset — fits handlers / effects cleanly.
+     * Terminal patterns to extract from this sub-unit's body. When unset it
+     * defaults to `return` and `throw`, which suits handlers and effects.
      */
     terminals?: TerminalPattern[];
     /**
-     * Input mapping for this sub-unit. Defaults to an empty positional
-     * mapping when unset — event handlers with one arg should pass
+     * Input mapping for this sub-unit. When unset it defaults to an empty
+     * positional mapping, so an event handler with one argument should pass
      * `{ type: "positionalParams", params: [{ position: 0, role: "event" }] }`.
      */
     inputMapping?: InputMappingPattern;
@@ -1034,20 +1389,29 @@ interface DiscoveredSubUnit {
 }
 
 /**
- * Build the `discovery` entries for an HTTP-server framework whose
- * handlers are registered via `app.get(path, handler)` /
- * `router.post(...)` / etc.
+ * 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.
+ */
+
+/**
+ * Build the `discovery` entries for an HTTP-server framework whose handlers
+ * are registered with `app.get(path, handler)`, `router.post(...)`, and the
+ * like.
  *
- * Each `importNames` entry produces one DiscoveryPattern — libraries
- * typically expose both a default export and a named export that both
- * produce the routable instance (e.g. Express has `express()` and
- * `Router()`; Fastify has `fastify()` and `Fastify`). The binding
- * extraction (method from registration, path from position 0) is
- * identical across every HTTP server framework we support.
+ * 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.
  *
- * Callers still supply the `methods` list directly: different
- * frameworks support different HTTP verbs (Fastify includes `.head` /
- * `.options`, Express historically does not by default).
+ * Callers still pass the `methods` list themselves, because frameworks
+ * support different HTTP verbs. Fastify includes `.head` and `.options`;
+ * Express historically does not by default.
  *
  * @example
  *   discovery: httpRouteDiscovery({
@@ -1062,19 +1426,160 @@ declare function httpRouteDiscovery(opts: {
     methods: readonly string[];
     /** Defaults to "handler". Override for packs that want a different kind. */
     kind?: string;
+    /**
+     * How this framework's routable can itself be mounted onto another
+     * one under a path prefix, so a route declared on the mounted value gets
+     * summarized with the prefix built into its path. See `DiscoveryPattern`.
+     */
+    mount?: DiscoveryPattern["mount"];
 }): DiscoveryPattern[];
 
+/**
+ * The path engine, written against `StructuredStatement` rather than any one
+ * language. Every control-flow path from entry to a terminal contributes its
+ * own conjunction of conditions, so a terminal you can reach along several
+ * paths becomes several entries instead of one branch with an invented
+ * conjunction, or none at all.
+ *
+ * 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
+ * enclosure conditions plus an opaque conjunct instead of guessing.
+ */
+
+/** 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. */
+declare class UnmodeledFlow extends Error {
+}
+/** The path budget was exceeded. Callers catch this and degrade. */
+declare class PathBudgetExceeded extends Error {
+}
+interface StructuredPathConditionsInput<Cond, Terminal> {
+    /** The unit's top-level statements, in source order. */
+    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.
+     */
+    terminalsByStmt: ReadonlyMap<StructuredStatement<Cond>, readonly Terminal[]>;
+}
+interface StructuredPathConditionsResult<Cond, Terminal> {
+    /** The paths to each terminal, keyed by the caller's own terminal handle. */
+    byTerminal: Map<Terminal, ConditionInfo<Cond>[][]>;
+    /** Condition lists for paths that fall through the end of the body. */
+    fallthrough: ConditionInfo<Cond>[][];
+}
+/**
+ * Work out the conditions on each path, for every StructuredStatement
+ * reachable from `input.statements`. Throws `PathBudgetExceeded` when the
+ * path count crosses the cap, or `UnmodeledFlow` when a switch or match
+ * turns up that the enumeration does not cover (a stray break, an unsafe
+ * fallthrough). The caller catches both and degrades to enclosure conditions
+ * plus an opaque conjunct, rather than claiming something it did not read.
+ */
+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.
+ */
+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. */
+    degraded: string | null;
+};
+
+/**
+ * The conditions every path to a terminal agrees on. A terminal reached more
+ * than one way keeps only the shared ones, so a condition is never claimed
+ * 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.
+ */
+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;
+}
+/** A set of nodes, compared by id. */
+declare class IdSet<T extends Identified> implements Iterable<T> {
+    private readonly byKey;
+    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. */
+    get(node: T): T | undefined;
+    get size(): number;
+    [Symbol.iterator](): Iterator<T>;
+}
+/** A map keyed by node, compared by id. */
+declare class IdMap<T extends Identified, V> implements Iterable<[T, V]> {
+    private readonly entries;
+    set(node: T, value: V): this;
+    get(node: T): V | undefined;
+    has(node: T): boolean;
+    get size(): number;
+    [Symbol.iterator](): Iterator<[T, V]>;
+}
+
+/**
+ * The small surface every language adapter implements, whatever that
+ * language's own tooling looks like underneath.
+ *
+ * Anything TypeScript-specific, such as the ts-morph Project a caller needs
+ * for corroborate's sandboxed execution, belongs on that adapter's own type
+ * rather than here. This interface never gets a field that mentions one
+ * particular language's tooling.
+ */
+
+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.
+     */
+    extractFromFiles(filePaths: string[]): Promise<BehavioralSummary[]>;
+    /** Extract summaries from every source file the adapter's project knows about. */
+    extractAll(): Promise<BehavioralSummary[]>;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+
 interface RawParameter {
     name: string;
     position: number;
-    role: string;
+    /**
+     * 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`.
+     */
+    role: string | null;
     typeText: string | null;
 }
 interface RawCondition {
     sourceText: string;
     structured: Predicate | null;
     polarity: "positive" | "negative";
-    source: "explicit" | "earlyReturn" | "earlyThrow" | "catchBlock";
+    source: ConditionSource;
 }
 interface RawTerminal {
     kind: "response" | "throw" | "return" | "render" | "delegate" | "emit" | "void";
@@ -1091,18 +1596,10 @@ interface RawTerminal {
     } | null;
     exceptionType: string | null;
     message: string | null;
-    /** For render terminals: the component being rendered */
     component: string | null;
-    /**
-     * For render terminals (JSX / component-tree output): the nested
-     * render tree if the pack's extractor can produce one. Flows
-     * through to `Output.render.root`. Absent when the extractor sees
-     * only the root element name or opted out of tree extraction.
-     */
+    /** Null when the pack read only the root element name, not the tree under it. */
     renderTree: RenderNode | null;
-    /** For delegate terminals: where control is passed */
     delegateTarget: string | null;
-    /** For emit terminals: the event/channel name */
     emitEvent: string | null;
     location: {
         start: number;
@@ -1110,22 +1607,9 @@ interface RawTerminal {
     };
 }
 /**
- * A structured capture of an invocation argument. Literal values
- * (string, number, boolean), object/array literals, template literals,
- * identifier references, and nested call expressions are all captured
- * as structured variants so readers can see *what* was passed even when
- * the runtime value isn't statically resolvable. `null` is reserved for
- * the rare case where the argument shape doesn't match any variant
- * (type assertions with computed operands, arithmetic, etc.) — the
- * caller still knows how many arguments the call had.
- *
- * Useful for recognising literal-string discriminators like
- * `findings.push({ kind: "scenarioCoverageGap" })` or
- * `dispatch({ type: "USER_LOGGED_IN" })` at the summary level, and for
- * preserving argument *shape* (`{ userId, count }`, `getUser(id)`) so
- * downstream consumers (AI agents, error-taxonomy tooling,
- * release-note generators) can reason about composition without
- * re-reading source.
+ * An invocation argument as the adapter read it. An argument that fits none of
+ * these variants, arithmetic for instance, comes through as null instead of
+ * being dropped, so a reader still knows how many arguments the call had.
  */
 type EffectArg = {
     kind: "string";
@@ -1142,39 +1626,19 @@ type EffectArg = {
 } | {
     kind: "array";
     items: EffectArg[];
-}
-/**
- * Template literal with interpolation (`` `Error: ${e.message}` ``).
- * The resolved runtime value is unknown, but the source text is
- * preserved so readers can see which variables compose it — useful
- * for log messages, computed keys, and dedup-style key builders.
- */
- | {
+} | {
     kind: "template";
     sourceText: string;
 }
 /**
- * Identifier reference — a bare variable (`userId`), a property-access
- * chain (`user.profile.email`, `process.env.DATABASE_URL`), or an
- * element-access chain (`config["host"]`). `name` holds the full
- * source text so readers can tell which binding flowed into the call
- * without inferring it from context. Identifiers that resolve to a
- * module-level `const` with a simple initializer (literal, process.env
- * access, etc.) are inlined to the initializer's EffectArg form so
- * closure-over-constants doesn't hide the actual value at call sites.
+ * A bare variable or a whole access chain, written out as it appears. An
+ * identifier bound to a module-level const with a simple initializer is
+ * replaced by that initializer, so a constant does not hide the value.
  */
  | {
     kind: "identifier";
     name: string;
-}
-/**
- * Nested call expression passed as an argument — `log(formatError(e))`,
- * `enqueue(buildPayload(ctx))`, inline composition. `callee` is the
- * source text of the call target; `args` recurses with bounded depth,
- * so `formatError(e)` reads as `{ callee: "formatError", args: [...] }`
- * rather than an opaque null.
- */
- | {
+} | {
     kind: "call";
     callee: string;
     args: EffectArg[];
@@ -1188,13 +1652,7 @@ type RawEffect = {
     callee: string;
     args: EffectArg[];
     async: boolean;
-    /**
-     * Ancestor if/switch/ternary conditions that gate reaching this
-     * call. Populated for calls nested inside conditional blocks or
-     * loop bodies; empty for top-level (always-fires) calls.
-     * Converts to `Effect.preconditions: Predicate[]` in the IR —
-     * same RawCondition → Predicate pipeline transitions use.
-     */
+    /** Empty means the call always fires, not that nobody looked. */
     preconditions?: RawCondition[];
 } | {
     type: "emission";
@@ -1208,14 +1666,8 @@ interface RawBranch {
     terminal: RawTerminal;
     effects: RawEffect[];
     /**
-     * Pre-typed `Effect`s emitted by `PatternPack.invocationRecognizers`.
-     * Bypass the `RawEffect → Effect` conversion that `effects` runs
-     * through — recognizers have full structural knowledge of what
-     * they're emitting (e.g. `interaction(class: "storage-access")` with
-     * binding identity + per-class fields/selector)
-     * and there's no narrower extractor-side representation worth
-     * round-tripping through. Concatenated with converted `effects` at
-     * `assembleSummary` time.
+     * Effects a recognizer built itself, already in IR form, so these skip the
+     * `RawEffect` conversion that `effects` goes through.
      */
     extraEffects?: Effect[];
     location: {
@@ -1223,14 +1675,20 @@ interface RawBranch {
         end: number;
     };
     isDefault: boolean;
+    /** The fields a consumer reads off a response inside this branch. */
+    expectedInput?: TypeShape | null;
     /**
-     * Shape of upstream data the code unit reads within this branch.
-     * Populated by the adapter for client/consumer code units: after
-     * branching on a response status, the consumer accesses fields on
-     * the response body — those accesses are collected into a TypeShape.
-     * The extractor copies this through to Transition.expectedInput.
+     * An adapter that passes its reading along uncollapsed sets this instead of
+     * `terminal.statusCode`. A status nobody wrote then becomes a claim only
+     * where a pack declared the default.
      */
-    expectedInput?: TypeShape | null;
+    statusCodeReading?: DefaultedReading<number>;
+    /**
+     * Set instead of `terminal.body.shape`, on the same terms.
+     * `terminal.body.typeText` is left alone, so a pack that gives the type as
+     * text and also reads its structure can do both.
+     */
+    bodyShapeReading?: DefaultedReading<TypeShape>;
 }
 interface RawDependencyCall {
     name: string;
@@ -1246,12 +1704,8 @@ interface RawDeclaredContract {
     framework: string;
     responses: Array<{
         statusCode: number;
-        /**
-         * Structured body schema the contract declares for this status code.
-         * Populated when the adapter can statically resolve the response schema
-         * (e.g. `c.type<T>()`'s type argument). Null when the contract exists
-         * but no body was declared or the schema form isn't yet supported.
-         */
+        /** Null means either the contract declared no body or suss could not read
+         * the schema form, and nothing here tells the two apart. */
         body?: TypeShape | null;
     }>;
     params?: Record<string, {
@@ -1259,54 +1713,33 @@ interface RawDeclaredContract {
         required: boolean;
     }>;
     /**
-     * Relationship between this declared contract and the `transitions[]`
-     * on the same summary:
-     *
-     *   - "derived": both are extracted from the same source data, so
-     *     comparing them against each other is tautological. Example: an
-     *     OpenAPI stub's contract and its transitions both come from the
-     *     operation's `responses` block. The cross-boundary checker
-     *     skips per-summary contract-consistency for these.
-     *
-     *   - "independent": the contract is a separate statement from the
-     *     transitions. Example: a ts-rest handler whose router declares
-     *     `responses` and whose implementation is a separate function;
-     *     a CFN stub whose `MethodResponses` and integration config are
-     *     independent template fields. Contract-consistency comparison
-     *     is meaningful.
-     *
-     * Defaults to "independent" when a pack doesn't say — safer to
-     * surface a spurious-but-investigable finding than to silently drop
-     * a real one.
+     * "derived" means the contract and the transitions both come from the same
+     * source, so comparing them proves nothing and the checker skips it. A pack
+     * that says nothing gets "independent", which risks a spurious finding
+     * rather than dropping a valid one.
      */
     provenance?: "derived" | "independent";
 }
 /**
- * What sits where a unit's body should be.
+ * What the adapter found where a unit's body should be. Downstream this is the
+ * difference between a summary that says nothing because there was nothing to
+ * say and one that says nothing because nobody could read the body.
  *
- *   - "absent": there is no body behind this declaration (an overload
- *     signature, an ambient declaration, an abstract method), so the
- *     pack read nothing about what the unit does.
- *   - "empty": a body with nothing in it. A summary that says nothing
- *     about it has described it completely.
- *   - "statements": a body with work in it, including a concise
- *     arrow's expression. A summary that says nothing about it has
- *     described none of it.
- *   - "elsewhere": the unit's body is not in what this run read. A
- *     route registered with a handler the caller supplies announces a
- *     boundary and names no function to look in, and the boundary is
- *     worth reporting with nothing behind it.
+ * "absent" is a declaration with no body at all, such as an overload
+ * signature. "empty" is a body with nothing in it, which an empty summary
+ * describes completely. "statements" is a body with work in it, which an empty
+ * summary describes none of. "elsewhere" is a body this run did not read: a
+ * route registered with a handler the caller supplies points at no function to
+ * go look in.
  */
 type BodyContent = "absent" | "empty" | "statements" | "elsewhere";
 interface RawCodeStructure {
-    /**
-     * The types this unit's shapes name rather than spell out. Carried
-     * onto the summary as `definitions`, so a reader following a name has
-     * somewhere to look.
-     */
+    /** Types the unit's shapes refer to by name instead of spelling out, so a
+     * reader who follows one of those names has somewhere to look. */
     definitions?: Record<string, TypeShape> | null;
     identity: {
         name: string;
+        nameKind?: "binding" | "label";
         kind: CodeUnitKind;
         file: string;
         range: {
@@ -1316,113 +1749,71 @@ interface RawCodeStructure {
         exportName: string | null;
         exportPath: string[] | null;
     };
-    /**
-     * Three-layer boundary description (`transport`, `semantics`,
-     * `recognition`). See `@suss/behavioral-ir`'s `BoundaryBinding`.
-     * Null when the unit participates in no cross-unit boundary —
-     * helpers, pure utilities, and anything the adapter can't place.
-     */
+    /** Null when the unit is not on any cross-unit boundary, which is the
+     * ordinary case for helpers and pure utilities. */
     boundaryBinding: BoundaryBinding | null;
-    /** The thing that gets deployed and runs this code, when known. */
     deployableUnit?: DeployableUnit;
     parameters: RawParameter[];
     branches: RawBranch[];
-    /**
-     * Return statements in the body that none of the pack's terminals
-     * matched. A handler shaped in a way the pack does not describe still
-     * returns something, and saying nothing about it reads the same as
-     * saying it does nothing.
-     */
+    /** Return statements no terminal in the pack matched. Leave this at zero and
+     * a handler the pack cannot describe looks like one that returns nothing. */
     unmatchedReturns?: number;
     /**
-     * What the adapter found where the unit's body should be. A summary
-     * with nothing in it means one of two different things, and only the
-     * adapter can say which: a body nobody could read, or a body with
-     * nothing in it to read. Adapters that do not say leave this unset,
-     * and everything downstream treats the summary as it did before.
+     * Only the adapter can tell a body nobody could read from a body with
+     * nothing in it, and an empty summary looks the same either way.
      */
     bodyContent?: BodyContent;
     dependencyCalls: RawDependencyCall[];
     declaredContract: RawDeclaredContract | null;
-    /**
-     * Names of pack-declared response properties whose semantics is `body`.
-     * For client units this records the accessor a consumer uses to reach the
-     * body (e.g. ["data"] for axios, ["body","json","text"] for fetch). Carried
-     * through to `summary.metadata.http.bodyAccessors` so the cross-boundary
-     * checker can unwrap consumer expectedInput correctly without knowing each
-     * pack. Flat here because this is the adapter→extractor plumbing contract;
-     * nesting under `http` happens when the summary is assembled.
-     */
+    /** 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. */
     bodyAccessors?: string[];
-    /**
-     * Names of pack-declared response properties whose semantics is
-     * `statusCode`. Same shape as `bodyAccessors` but for the status side —
-     * lets the checker recognise pack-specific names (e.g. fetch's `status`,
-     * axios's `status`, hypothetical `responseStatus`) when matching consumer
-     * branch conditions to provider transitions. Carried through to
-     * `summary.metadata.http.statusAccessors`.
-     */
+    /** The same, for the status: `status` for fetch and for axios. */
     statusAccessors?: string[];
-    /**
-     * Raw GraphQL document source attached to consumer-side graphql
-     * summaries (the inner text of a `useQuery(gql\`...\`)` call).
-     * Assembled into `summary.metadata.graphql.document` for the
-     * checker's pairing layer to parse. Deliberately untouched here —
-     * the extractor has no dependency on graphql-js; parsing happens
-     * at check time.
-     */
+    /** Left exactly as written, because the extractor does not depend on
+     * graphql-js. The parsing happens at check time. */
     graphqlDocument?: string;
-    /**
-     * Raw GraphQL schema SDL attached to provider-side resolver
-     * summaries. For schema-first stubs (AppSync), the SDL IS the
-     * schema. For code-first frameworks (Apollo Server), the SDL
-     * comes from the `typeDefs` config option when statically
-     * resolvable. Surfaced as `summary.metadata.graphql.schemaSdl`
-     * so the checker can use the return-type field set when pairing
-     * nested consumer selections.
-     */
     graphqlSchemaSdl?: string;
-    /**
-     * Declared contract derived from the SDL field for this resolver:
-     * `{ returnType, args, provenance, framework }`. Surfaced as
-     * `summary.metadata.graphql.declaredContract` so
-     * `checkGraphqlContractAgreement` can pair it against other
-     * sources declaring a contract for the same boundary.
-     *
-     * The extractor doesn't derive this — adapters that have the SDL
-     * AND know the (typeName, fieldName) of the resolver populate it.
-     * Today: the TS adapter does this for Apollo-style resolverMap
-     * discovery. NestJS GraphQL (decorator-based) is a follow-up.
-     */
-    graphqlDeclaredContract?: Record<string, unknown>;
-    /**
-     * Set on a consumer-side GraphQL summary whose document reference was
-     * recognized (an imported `TypedDocumentNode` from graphql-codegen,
-     * say) but whose body couldn't be read statically. Surfaced as
-     * `summary.metadata.graphql.unresolvedDocument` so the unreadable
-     * document is accounted for rather than silently dropped. `reference`
-     * is the identifier passed to the hook / imperative call; `reason`
-     * explains what defeated static resolution.
-     */
+    /** The extractor cannot derive this. An adapter that has the SDL and knows
+     * which field the resolver serves fills it in. */
+    graphqlDeclaredContract?: GraphqlDeclaredContract;
+    /** Set when a document reference was recognized but its body could not be
+     * read, so an unreadable document is accounted for instead of dropped. */
     graphqlUnresolvedDocument?: {
         reference: string;
         reason: string;
     };
     /**
-     * Set when the source does not state part of the boundary this unit
-     * sits on. The binding still goes out with that part left empty, so
-     * the unit pairs with nothing rather than with whatever a guess named,
-     * and this sentence tells a reader which part is missing and why.
-     *
-     * A statement about the reading rather than about the code, so it
-     * lands as an `unreadOutcome` gap and no checker holds it against the
-     * unit.
+     * Which part of the boundary the source does not state, and why. The binding
+     * still goes out with that part empty, so the unit pairs with nothing rather
+     * than with whatever a guess would have supplied. It comes out as an
+     * `unreadOutcome` gap, so no checker counts it against the unit.
      */
     unreadBinding?: string;
+    /**
+     * Readings the adapter passed along without collapsing. This module writes
+     * the reason for any that came back unreadable or ambiguous. Written and
+     * absent readings contribute nothing here, since what they found is already
+     * on the summary.
+     */
+    readings?: readonly Reading<unknown>[];
 }
 interface ExtractorOptions {
     gapHandling: "strict" | "permissive" | "silent";
 }
+/**
+ * The id for one branch's transition, built so that editing a handler does not
+ * churn it. Reordering branches, or adding an unrelated one, must leave the
+ * existing ids alone, otherwise `diffSummaries` reports "everything changed"
+ * every time somebody shuffles a handler around.
+ *
+ * The id combines the enclosing function name, the terminal kind, the status
+ * code (a literal value, the source text of a dynamic one, or "none"), and a
+ * short hash of the condition chain's source texts. Editing a branch's body
+ * without touching its guards or its status leaves the id alone, so a diff
+ * reports one changed transition instead of an add plus a remove. Change any
+ * of those signals and you get a new id.
+ */
 declare function makeTransitionId(functionName: string, branch: RawBranch): string;
 declare function assembleSummary(raw: RawCodeStructure, options?: ExtractorOptions): BehavioralSummary;
 declare function detectGaps(raw: RawCodeStructure, transitions: Transition[], options: ExtractorOptions): Gap[];
@@ -1431,4 +1822,4 @@ declare function terminalToOutput(terminal: RawTerminal): Output;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type BindingExtraction, type BodyContent, type ContractPattern, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExtractorOptions, type InputMappingPattern, type InvocationRecognizer, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type ResponsePropertyMapping, type ResponsePropertyMeaning, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };
+export { type AccessRecognizer, type BindingExtraction, type BodyContent, type CaseGroup, type ChosenReading, type ConditionHandle, type ConditionInfo, type ConditionSource, type ContractPattern, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type ExitKind, type ExtractorOptions, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, PathBudgetExceeded, type PatternPack, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawTerminal, type Reading, type ResponsePropertyMapping, type ResponsePropertyMeaning, type SourceRange, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TransparentWrapper, UnmodeledFlow, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, detectGaps, effectToIR, enumerateOrDegrade, enumerateStructuredPaths, firstWrittenReading, httpRouteDiscovery, makeTransitionId, mapReading, paramToInput, sharedGatingConditions, terminalToOutput, unreadableReading, valueToReadFurtherFrom, writtenReading };