@suss/extractor 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,246 +1,5 @@
 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
@@ -464,10 +223,10 @@ type DiscoveryMatch = {
      *
      * 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)` gives `"User"`), or from
-     * `methodDecoratorTypeMap` when the class decorator has no
-     * argument. `fieldName` comes from the method decorator's `{ name }`
+     * `typeName` resolves from `methodDecoratorTypeMap` when the
+     * method decorator is in it, and otherwise from the class
+     * decorator's first argument (`@Resolver(() => User)` gives
+     * `"User"`). `fieldName` comes from the method decorator's `{ name }`
      * option when that is set, and otherwise from the method name.
      */
     type: "decoratedMethod";
@@ -489,10 +248,10 @@ type DiscoveryMatch = {
     classDecorators: string[];
     methodDecorators: string[];
     /**
-     * Maps a method decorator to the type its field belongs to when the
-     * class decorator does not say. NestJS puts `@Query` on the root
+     * Maps a method decorator to the type its field belongs to, for the
+     * decorators that settle it. NestJS puts `@Query` on the root
      * `Query` type and `@Mutation` on `Mutation` no matter what the class
-     * says, so those two settle it themselves.
+     * says, so an entry here wins over the class decorator's argument.
      *
      * When the map leaves a decorator out and the class decorator gives no
      * type either, nothing here works out which type owns the field. The
@@ -1053,6 +812,8 @@ type ResponsePropertyMeaning = {
 } | {
     type: "headers";
 };
+/** Whether a refused request comes back as a response or as an exception. */
+type FailureDelivery = "response" | "exception";
 interface ResponsePropertyMapping {
     /** Property or method name on the response (e.g. "ok", "status", "json") */
     name: string;
@@ -1121,6 +882,14 @@ interface PatternPack {
      * `.json()` into a structured IR construct instead of leaving it opaque.
      */
     responseSemantics?: ResponsePropertyMapping[];
+    /**
+     * How this client hands back a response the server refused. `fetch`
+     * returns one and the caller reads the status off it. axios and ky
+     * reject instead, so every non-2xx reaches the caller through a
+     * `catch` and there is no status for a guard to read. Defaults to
+     * `"response"`.
+     */
+    failureDelivery?: FailureDelivery;
     /**
      * Synthesize extra code units out of a parent unit's body, for when one
      * construct the user wrote implicitly spawns several units the runtime
@@ -1298,6 +1067,25 @@ interface PatternPack {
         importModule: string;
         importName: string;
         uriProperty: string;
+        /**
+         * How this constructor's cache option installs a fragment
+         * registry, for the library whose client can supply fragment
+         * definitions at run time. `cacheProperty` is the construction
+         * option the cache is passed in, `cacheConstructor` the cache
+         * class, and `registryProperty` the cache option that installs
+         * the registry. The adapter reads every construction and records
+         * whether a registry is configured, absent, or unreadable; a
+         * construction it cannot read counts as unreadable, never as
+         * absent.
+         */
+        fragmentRegistry?: {
+            cacheProperty: string;
+            cacheConstructor: {
+                importModule: string;
+                importName: string;
+            };
+            registryProperty: string;
+        };
     }>;
     /**
      * Which service a client talks to, keyed by the endpoint the
@@ -1474,6 +1262,255 @@ interface DiscoveredSubUnit {
     metadata?: Record<string, unknown>;
 }
 
+/**
+ * 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>;
+}
+/**
+ * What every lowered statement has on it, whichever construct it is.
+ *
+ * The lowering works `exitKind` out by scanning the statement's own
+ * subtree for a return or a throw, skipping every nested function body.
+ *
+ * `callbacks` is the bodies of the functions this statement passes to
+ * calls it makes, as far as the language counts those as running for the
+ * enclosing unit. The engine walks them on the same path as the
+ * statement, so their branches are the unit's branches. Their `return`
+ * is not the unit's, so a path that ends inside one continues past the
+ * statement. A lowering that leaves the field out behaves as it did
+ * before there was one.
+ */
+interface LoweredStatementParts<Cond> {
+    readonly exitKind: ExitKind;
+    readonly callbacks?: readonly StatementBlock<Cond>[];
+}
+/**
+ * One statement in the unit's control flow, already lowered out of the
+ * source language. `kind` says which construct it is, `condition` (where
+ * one applies) is the opaque test, and the block and group fields are its
+ * children. `LoweredStatementParts` describes the rest.
+ */
+type StructuredStatement<Cond = unknown> = (LoweredStatementParts<Cond> & {
+    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;
+}) | (LoweredStatementParts<Cond> & {
+    readonly kind: "switch";
+    /** Source order; at most one group has a null (default) condition. */
+    readonly groups: readonly CaseGroup<Cond>[];
+}) | (LoweredStatementParts<Cond> & {
+    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>;
+}) | (LoweredStatementParts<Cond> & {
+    readonly kind: "try";
+    readonly tryBody: StatementBlock<Cond>;
+    readonly catchBody: StatementBlock<Cond> | null;
+    /** Here only so it can be validated. A finally that exits, or that contains a terminal the caller gave us, is not modeled, and its own conditions are never enumerated. */
+    readonly finallyBody: StatementBlock<Cond> | null;
+}) | (LoweredStatementParts<Cond> & {
+    readonly kind: "exit";
+    readonly exit: "return" | "throw" | "break" | "continue";
+}) | (LoweredStatementParts<Cond> & {
+    /** Anything else: expression statements, declarations, and any statement the enumeration does not branch on. */
+    readonly kind: "opaque";
+});
+
+/**
+ * `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;
+
 /**
  * Small helpers for pattern packs that are built the same way.
  *
@@ -1865,13 +1902,23 @@ interface RawCodeStructure {
     bodyAccessors?: string[];
     /** The same, for the status: `status` for fetch and for axios. */
     statusAccessors?: string[];
+    /** The same, for the success flag: `ok` for fetch, nothing for axios. */
+    successAccessors?: string[];
+    /** Whether this client's non-2xx arrives as a response or a rejection. */
+    failureDelivery?: FailureDelivery;
     /** Left exactly as written, because the extractor does not depend on
      * graphql-js. The parsing happens at check time. */
     graphqlDocument?: string;
     graphqlSchemaSdl?: string;
+    /** The document this unit was read out of, when something else read out of
+     * the same document states what this one relies on. */
+    sourceDocumentLabel?: string;
     /** The extractor cannot derive this. An adapter that has the SDL and knows
      * which field the resolver serves fills it in. */
     graphqlDeclaredContract?: GraphqlDeclaredContract;
+    /** Fragment spreads in `graphqlDocument` with no definition in it, so a
+     * partially read document is marked rather than passed off as whole. */
+    graphqlUnresolvedFragments?: string[];
     /** 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?: {
@@ -1917,4 +1964,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 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, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };
+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, type FailureDelivery, IdMap, IdSet, type Identified, type InputMappingPattern, type InvocationRecognizer, type LanguageAdapter, type LoweredStatementParts, 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, unwrapJsonStringify, valueToReadFurtherFrom, writtenReading };