@suss/extractor 0.0.2 → 0.1.1

package/README.md

@@ -4,7 +4,7 @@ Assembly engine that turns raw language-adapter output into a `BehavioralSummary
 
 ## What this package is
 
-`@suss/extractor` is the core assembly layer of the suss pipeline. Language adapters (such as `@suss/adapter-typescript`) parse source code and produce a `RawCodeStructure` — a normalized, adapter-specific intermediate form. The extractor's `assembleSummary` function converts that structure into the final `BehavioralSummary` IR, handling condition polarity, terminal mapping, gap detection, confidence assessment, and `expectedInput` pass-through for client field tracking. It also exports the `RawCodeStructure` type, the `PatternPack` interface, and all related raw types so adapters can share a common contract.
+`@suss/extractor` is the core assembly layer of the suss pipeline. Language adapters (such as `@suss/adapter-typescript`) parse source code and produce a `RawCodeStructure`, a normalized, adapter-specific intermediate form. The extractor's `assembleSummary` function converts that structure into the final `BehavioralSummary` IR, handling condition polarity, terminal mapping, gap detection, confidence assessment, and `expectedInput` pass-through for client field tracking. It also exports the `RawCodeStructure` type, the `PatternPack` interface, and all related raw types so adapters can share a common contract.
 
 ## Where it sits in suss
 

package/dist/index.cjs

@@ -95,7 +95,8 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
     identity: {
       name: raw.identity.name,
       exportPath: raw.identity.exportPath,
-      boundaryBinding: raw.boundaryBinding ?? null
+      boundaryBinding: raw.boundaryBinding ?? null,
+      ...raw.deployableUnit !== void 0 ? { deployableUnit: raw.deployableUnit } : {}
     },
     inputs,
     transitions,
@@ -150,6 +151,34 @@ function detectGaps(raw, transitions, options) {
     return [];
   }
   const gaps = [];
+  if (raw.unmatchedReturns !== void 0 && raw.unmatchedReturns > 0) {
+    const count = raw.unmatchedReturns;
+    gaps.push({
+      // Not a contract violation: the handler may be answering
+      // correctly, in a shape nobody taught the pack.
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: count === 1 ? "One return in this function matches none of the terminal shapes this pack looks for, so what it produces is not described here" : `${count} returns in this function match none of the terminal shapes this pack looks for, so what they produce is not described here`
+    });
+  }
+  if (raw.unreadBinding !== void 0) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: raw.unreadBinding
+    });
+  }
+  const unreadBody = describeUnreadBody(raw);
+  if (unreadBody !== null) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: unreadBody
+    });
+  }
   if (raw.declaredContract) {
     const producedStatuses = new Set(
       transitions.flatMap((t) => {
@@ -189,7 +218,34 @@ function detectGaps(raw, transitions, options) {
   }
   return gaps;
 }
+function bodyWentUnread(raw) {
+  if (raw.bodyContent === "absent" || raw.bodyContent === "elsewhere") {
+    return true;
+  }
+  return raw.bodyContent === "statements" && raw.branches.length === 0;
+}
+function describeUnreadBody(raw) {
+  if (!bodyWentUnread(raw)) {
+    return null;
+  }
+  if (raw.bodyContent === "absent") {
+    return "This unit is a declaration with no body behind it, so nothing about what it does was read here";
+  }
+  if (raw.bodyContent === "elsewhere") {
+    return "The handler on this boundary comes from outside the code that registers it, so nothing about what it does was read here";
+  }
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return null;
+  }
+  return "Nothing this unit's body does matches a shape this pack looks for, so what it does is not described here";
+}
 function assessConfidence(raw) {
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return { source: "inferred_static", level: "low" };
+  }
+  if (bodyWentUnread(raw)) {
+    return { source: "inferred_static", level: "low" };
+  }
   let total = 0;
   let opaque = 0;
   for (const branch of raw.branches) {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Effect, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 
 type DiscoveryMatch = {
     type: "namedExport";
@@ -211,30 +211,42 @@ type DiscoveryMatch = {
      * The adapter populates `DiscoveredUnit.resolverInfo` so the
      * produced binding carries `graphql-resolver(typeName, fieldName)`.
      * `typeName` resolves from the class decorator's first argument
-     * (`@Resolver(() => User)` → `"User"`); when the class decorator
-     * has no argument it defaults to the operation kind (`"Query"`,
-     * `"Mutation"`, `"Subscription"`). `fieldName` reads the method
-     * decorator's `{ name }` option override when present, otherwise
-     * the method name.
+     * (`@Resolver(() => User)` → `"User"`), and from
+     * `methodDecoratorTypeMap` when the class decorator has no
+     * argument. `fieldName` reads the method decorator's `{ name }`
+     * option override when present, otherwise 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 (NestJS apps frequently
-     * declare `MetadataResolver` / `CoreResolver` factories that
-     * compose `@Resolver()` with extra metadata). When that happens,
-     * the import-module gate would miss them; pass an array of
-     * accepted modules and any one match suffices.
+     * 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.
      */
     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).
+     * 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.
      */
     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.
+     *
+     * 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.
+     */
+    methodDecoratorTypeMap: Record<string, string>;
 } | {
     /**
      * NestJS-style REST controller discovery. Class decorated with
@@ -248,10 +260,9 @@ type DiscoveryMatch = {
      * 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 project-internal wrappers
-     * (`@PublicController` / `@AuthedController` factories
-     * composing `@Controller()`) work without per-project pack
-     * config.
+     * 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.
      *
      * The adapter populates `DiscoveredUnit.routeInfo` so the
      * produced binding carries `rest(method, path)`.
@@ -374,7 +385,49 @@ type BindingExtraction = {
         type: "fromRegistration";
         position: number;
     } | {
+        type: "fromArgumentProperty";
+        position: number;
+        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.
+         *
+         * `app/api/orders/[id]/route.ts` under `{ root: "app",
+         * dropBasenames: ["route"], dynamic: "brackets" }` comes out as
+         * `/api/orders/{id}`, which pairs with an Express provider
+         * writing `/api/orders/:id`.
+         */
         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.
+         */
+        root: string;
+        /**
+         * Filenames that say what a file is rather than adding a
+         * segment: `route`, `page`, `index`, `_index`.
+         */
+        dropBasenames?: string[];
+        /**
+         * How the framework writes a parameter in a filename. Next.js
+         * uses `[id]`, React Router uses `$id`.
+         */
+        dynamic?: "brackets" | "dollarPrefix";
+        /**
+         * Whether a directory in parentheses organises files without
+         * appearing in the URL, as `app/(marketing)/about` does.
+         */
+        dropParenthesized?: boolean;
+        /**
+         * Whether one filename holds the whole path with dots between
+         * the segments, as `routes/orders.$id.tsx` does.
+         */
+        flat?: boolean;
     } | {
         type: "fromContract";
     } | {
@@ -487,6 +540,10 @@ interface TerminalExtraction {
     } | {
         from: "constructor";
         codes: Record<string, number>;
+    } | {
+        from: "argumentProperty";
+        position: number;
+        name: string;
     } | {
         from: "argumentConstructor";
         position: number;
@@ -619,17 +676,38 @@ interface ResponsePropertyMapping {
     /** What the value semantically represents */
     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.
+ */
+interface TransparentWrapper {
+    /** Callee text as written, e.g. "Sentry.wrapHandler". */
+    callee: string;
+    /** Which argument holds the wrapped function. */
+    argument: number;
+    /**
+     * The module the callee has to have been imported from. Without it a
+     * local object spelled the same way would be taken for the library.
+     */
+    module: string;
+}
 interface PatternPack {
     name: string;
     /**
-     * Pack version stamp — feeds the cache invalidation key. Bump on
+     * Pack version stamp, which feeds the cache invalidation key. Bump on
      * any change that affects discovered units / extracted summaries.
-     * Format is opaque to the adapter; semver is the obvious choice
-     * but a content hash, build SHA, or monotonic integer works too.
-     * Optional — packs that omit it use the literal string `"unset"`,
-     * which means cache entries from one process to the next aren't
-     * meaningfully versioned (suitable for development; production
-     * packs should declare a version).
+     * Format is opaque to the adapter, so semver or a content hash both
+     * work.
+     *
+     * Optional, because whoever loads the pack knows more about it than
+     * the pack does. The CLI folds a hash of the file it loaded and of
+     * the config it passed into this stamp, so a pack run through the CLI
+     * invalidates on an edit whether or not it declares a version. A host
+     * that builds packs some other way carries that responsibility
+     * itself. A pack with nothing to stamp reads as `"unset"`, and warm
+     * caches will answer for code that has since changed.
      */
     version?: string;
     languages: string[];
@@ -792,6 +870,17 @@ interface PatternPack {
      * available without an import).
      */
     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
+     * `argument`-th argument.
+     *
+     * `callee` matches the call expression text as written, e.g.
+     * `"Sentry.wrapHandler"`.
+     */
+    transparentWrappers?: TransparentWrapper[];
     /**
      * Per-property-access recognizers — sister to
      * `invocationRecognizers` but firing on `PropertyAccessExpression`
@@ -884,6 +973,31 @@ interface DiscoveredCustomUnit {
         method: string;
         path: string;
     };
+    /**
+     * GraphQL field identity for units a callback discovers against an
+     * external manifest rather than an in-code resolver map. AppSync
+     * routes a field to a Lambda in the deploy template, so the field is
+     * the boundary that code serves. When set, the adapter builds a
+     * `graphql-resolver` binding from `(typeName, fieldName)`, which
+     * pairs with the operations a client sends.
+     */
+    resolverInfo?: {
+        typeName: string;
+        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
+     * adapter builds a `message-bus` binding from `(messageBus, channel)`,
+     * which pairs with producers sending on the same channel.
+     */
+    channelInfo?: {
+        messageBus: MessageBusSemantics["messageBus"];
+        channel: string;
+    };
+    /** The thing that gets deployed and runs this unit, when known. */
+    deployableUnit?: DeployableUnit;
     /**
      * Metadata merged onto the resulting summary's `metadata` field.
      */
@@ -1167,6 +1281,23 @@ interface RawDeclaredContract {
      */
     provenance?: "derived" | "independent";
 }
+/**
+ * What sits where a unit's body should be.
+ *
+ *   - "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.
+ */
+type BodyContent = "absent" | "empty" | "statements" | "elsewhere";
 interface RawCodeStructure {
     identity: {
         name: string;
@@ -1186,8 +1317,25 @@ interface RawCodeStructure {
      * helpers, pure utilities, and anything the adapter can't place.
      */
     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.
+     */
+    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.
+     */
+    bodyContent?: BodyContent;
     dependencyCalls: RawDependencyCall[];
     declaredContract: RawDeclaredContract | null;
     /**
@@ -1254,6 +1402,17 @@ interface RawCodeStructure {
         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.
+     */
+    unreadBinding?: string;
 }
 interface ExtractorOptions {
     gapHandling: "strict" | "permissive" | "silent";
@@ -1266,4 +1425,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 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, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, Predicate, TypeShape, RenderNode, CodeUnitKind, BoundaryBinding, BehavioralSummary, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 
 type DiscoveryMatch = {
     type: "namedExport";
@@ -211,30 +211,42 @@ type DiscoveryMatch = {
      * The adapter populates `DiscoveredUnit.resolverInfo` so the
      * produced binding carries `graphql-resolver(typeName, fieldName)`.
      * `typeName` resolves from the class decorator's first argument
-     * (`@Resolver(() => User)` → `"User"`); when the class decorator
-     * has no argument it defaults to the operation kind (`"Query"`,
-     * `"Mutation"`, `"Subscription"`). `fieldName` reads the method
-     * decorator's `{ name }` option override when present, otherwise
-     * the method name.
+     * (`@Resolver(() => User)` → `"User"`), and from
+     * `methodDecoratorTypeMap` when the class decorator has no
+     * argument. `fieldName` reads the method decorator's `{ name }`
+     * option override when present, otherwise 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 (NestJS apps frequently
-     * declare `MetadataResolver` / `CoreResolver` factories that
-     * compose `@Resolver()` with extra metadata). When that happens,
-     * the import-module gate would miss them; pass an array of
-     * accepted modules and any one match suffices.
+     * 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.
      */
     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).
+     * 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.
      */
     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.
+     *
+     * 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.
+     */
+    methodDecoratorTypeMap: Record<string, string>;
 } | {
     /**
      * NestJS-style REST controller discovery. Class decorated with
@@ -248,10 +260,9 @@ type DiscoveryMatch = {
      * 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 project-internal wrappers
-     * (`@PublicController` / `@AuthedController` factories
-     * composing `@Controller()`) work without per-project pack
-     * config.
+     * 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.
      *
      * The adapter populates `DiscoveredUnit.routeInfo` so the
      * produced binding carries `rest(method, path)`.
@@ -374,7 +385,49 @@ type BindingExtraction = {
         type: "fromRegistration";
         position: number;
     } | {
+        type: "fromArgumentProperty";
+        position: number;
+        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.
+         *
+         * `app/api/orders/[id]/route.ts` under `{ root: "app",
+         * dropBasenames: ["route"], dynamic: "brackets" }` comes out as
+         * `/api/orders/{id}`, which pairs with an Express provider
+         * writing `/api/orders/:id`.
+         */
         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.
+         */
+        root: string;
+        /**
+         * Filenames that say what a file is rather than adding a
+         * segment: `route`, `page`, `index`, `_index`.
+         */
+        dropBasenames?: string[];
+        /**
+         * How the framework writes a parameter in a filename. Next.js
+         * uses `[id]`, React Router uses `$id`.
+         */
+        dynamic?: "brackets" | "dollarPrefix";
+        /**
+         * Whether a directory in parentheses organises files without
+         * appearing in the URL, as `app/(marketing)/about` does.
+         */
+        dropParenthesized?: boolean;
+        /**
+         * Whether one filename holds the whole path with dots between
+         * the segments, as `routes/orders.$id.tsx` does.
+         */
+        flat?: boolean;
     } | {
         type: "fromContract";
     } | {
@@ -487,6 +540,10 @@ interface TerminalExtraction {
     } | {
         from: "constructor";
         codes: Record<string, number>;
+    } | {
+        from: "argumentProperty";
+        position: number;
+        name: string;
     } | {
         from: "argumentConstructor";
         position: number;
@@ -619,17 +676,38 @@ interface ResponsePropertyMapping {
     /** What the value semantically represents */
     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.
+ */
+interface TransparentWrapper {
+    /** Callee text as written, e.g. "Sentry.wrapHandler". */
+    callee: string;
+    /** Which argument holds the wrapped function. */
+    argument: number;
+    /**
+     * The module the callee has to have been imported from. Without it a
+     * local object spelled the same way would be taken for the library.
+     */
+    module: string;
+}
 interface PatternPack {
     name: string;
     /**
-     * Pack version stamp — feeds the cache invalidation key. Bump on
+     * Pack version stamp, which feeds the cache invalidation key. Bump on
      * any change that affects discovered units / extracted summaries.
-     * Format is opaque to the adapter; semver is the obvious choice
-     * but a content hash, build SHA, or monotonic integer works too.
-     * Optional — packs that omit it use the literal string `"unset"`,
-     * which means cache entries from one process to the next aren't
-     * meaningfully versioned (suitable for development; production
-     * packs should declare a version).
+     * Format is opaque to the adapter, so semver or a content hash both
+     * work.
+     *
+     * Optional, because whoever loads the pack knows more about it than
+     * the pack does. The CLI folds a hash of the file it loaded and of
+     * the config it passed into this stamp, so a pack run through the CLI
+     * invalidates on an edit whether or not it declares a version. A host
+     * that builds packs some other way carries that responsibility
+     * itself. A pack with nothing to stamp reads as `"unset"`, and warm
+     * caches will answer for code that has since changed.
      */
     version?: string;
     languages: string[];
@@ -792,6 +870,17 @@ interface PatternPack {
      * available without an import).
      */
     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
+     * `argument`-th argument.
+     *
+     * `callee` matches the call expression text as written, e.g.
+     * `"Sentry.wrapHandler"`.
+     */
+    transparentWrappers?: TransparentWrapper[];
     /**
      * Per-property-access recognizers — sister to
      * `invocationRecognizers` but firing on `PropertyAccessExpression`
@@ -884,6 +973,31 @@ interface DiscoveredCustomUnit {
         method: string;
         path: string;
     };
+    /**
+     * GraphQL field identity for units a callback discovers against an
+     * external manifest rather than an in-code resolver map. AppSync
+     * routes a field to a Lambda in the deploy template, so the field is
+     * the boundary that code serves. When set, the adapter builds a
+     * `graphql-resolver` binding from `(typeName, fieldName)`, which
+     * pairs with the operations a client sends.
+     */
+    resolverInfo?: {
+        typeName: string;
+        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
+     * adapter builds a `message-bus` binding from `(messageBus, channel)`,
+     * which pairs with producers sending on the same channel.
+     */
+    channelInfo?: {
+        messageBus: MessageBusSemantics["messageBus"];
+        channel: string;
+    };
+    /** The thing that gets deployed and runs this unit, when known. */
+    deployableUnit?: DeployableUnit;
     /**
      * Metadata merged onto the resulting summary's `metadata` field.
      */
@@ -1167,6 +1281,23 @@ interface RawDeclaredContract {
      */
     provenance?: "derived" | "independent";
 }
+/**
+ * What sits where a unit's body should be.
+ *
+ *   - "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.
+ */
+type BodyContent = "absent" | "empty" | "statements" | "elsewhere";
 interface RawCodeStructure {
     identity: {
         name: string;
@@ -1186,8 +1317,25 @@ interface RawCodeStructure {
      * helpers, pure utilities, and anything the adapter can't place.
      */
     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.
+     */
+    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.
+     */
+    bodyContent?: BodyContent;
     dependencyCalls: RawDependencyCall[];
     declaredContract: RawDeclaredContract | null;
     /**
@@ -1254,6 +1402,17 @@ interface RawCodeStructure {
         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.
+     */
+    unreadBinding?: string;
 }
 interface ExtractorOptions {
     gapHandling: "strict" | "permissive" | "silent";
@@ -1266,4 +1425,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 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, assembleSummary, assessConfidence, detectGaps, effectToIR, httpRouteDiscovery, makeTransitionId, paramToInput, terminalToOutput };
+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 };

package/dist/index.js

@@ -64,7 +64,8 @@ function assembleSummary(raw, options = DEFAULT_OPTIONS) {
     identity: {
       name: raw.identity.name,
       exportPath: raw.identity.exportPath,
-      boundaryBinding: raw.boundaryBinding ?? null
+      boundaryBinding: raw.boundaryBinding ?? null,
+      ...raw.deployableUnit !== void 0 ? { deployableUnit: raw.deployableUnit } : {}
     },
     inputs,
     transitions,
@@ -119,6 +120,34 @@ function detectGaps(raw, transitions, options) {
     return [];
   }
   const gaps = [];
+  if (raw.unmatchedReturns !== void 0 && raw.unmatchedReturns > 0) {
+    const count = raw.unmatchedReturns;
+    gaps.push({
+      // Not a contract violation: the handler may be answering
+      // correctly, in a shape nobody taught the pack.
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: count === 1 ? "One return in this function matches none of the terminal shapes this pack looks for, so what it produces is not described here" : `${count} returns in this function match none of the terminal shapes this pack looks for, so what they produce is not described here`
+    });
+  }
+  if (raw.unreadBinding !== void 0) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: raw.unreadBinding
+    });
+  }
+  const unreadBody = describeUnreadBody(raw);
+  if (unreadBody !== null) {
+    gaps.push({
+      type: "unreadOutcome",
+      conditions: [],
+      consequence: "unknown",
+      description: unreadBody
+    });
+  }
   if (raw.declaredContract) {
     const producedStatuses = new Set(
       transitions.flatMap((t) => {
@@ -158,7 +187,34 @@ function detectGaps(raw, transitions, options) {
   }
   return gaps;
 }
+function bodyWentUnread(raw) {
+  if (raw.bodyContent === "absent" || raw.bodyContent === "elsewhere") {
+    return true;
+  }
+  return raw.bodyContent === "statements" && raw.branches.length === 0;
+}
+function describeUnreadBody(raw) {
+  if (!bodyWentUnread(raw)) {
+    return null;
+  }
+  if (raw.bodyContent === "absent") {
+    return "This unit is a declaration with no body behind it, so nothing about what it does was read here";
+  }
+  if (raw.bodyContent === "elsewhere") {
+    return "The handler on this boundary comes from outside the code that registers it, so nothing about what it does was read here";
+  }
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return null;
+  }
+  return "Nothing this unit's body does matches a shape this pack looks for, so what it does is not described here";
+}
 function assessConfidence(raw) {
+  if ((raw.unmatchedReturns ?? 0) > 0) {
+    return { source: "inferred_static", level: "low" };
+  }
+  if (bodyWentUnread(raw)) {
+    return { source: "inferred_static", level: "low" };
+  }
   let total = 0;
   let opaque = 0;
   for (const branch of raw.branches) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/extractor",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "type": "module",
   "description": "Framework-agnostic extraction pipeline that turns raw extractions into suss behavioral summaries.",
   "keywords": [
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.0.2"
+    "@suss/behavioral-ir": "0.1.1"
   },
   "devDependencies": {
     "tsup": "*",