@suss/adapter-ruby 0.35.1 → 0.37.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import { Database } from '@suss/datalog';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
-import { TypeShape, RequestSpellingMetadata, Effect, BehavioralSummary } from '@suss/behavioral-ir';
+import { MessageBusTechnology, TypeShape, RequestSpellingMetadata, Effect, BehavioralSummary } from '@suss/behavioral-ir';
+import { DeclaredEntryPoint, RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { UnwrapsByName, WhyExplained } from '@suss/resolution';
-import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { Value } from '@suss/values';
 
 /**
@@ -284,6 +284,12 @@ interface AncestorLookup {
      * file is visible without a file of its own.
      */
     localDefinition?(qualifiedName: string): ReachedBody[] | null;
+    /**
+     * The blocks any file in the run defines under a name, consulted after
+     * `localDefinition` and before the path convention. The path convention
+     * then only finds a class the run did not read.
+     */
+    definedInRun?(qualifiedName: string): Promise<ReachedBody[] | null>;
 }
 /**
  * Every block a file defines under `qualifiedName`, or null when no file
@@ -352,9 +358,22 @@ interface RubyPack {
      * cache key, so editing one of them forces a re-extract.
      */
     discoveryInputs?: (files: readonly string[]) => string[];
+    /**
+     * Files the library renders through ERB when the app boots, such as
+     * Rails' `config/database.yml`, as absolute paths. The adapter reads
+     * each one as the Ruby in its tags, run when the app loads, so a read of
+     * `ENV` there goes on a load-time unit for the file.
+     */
+    bootTemplates?: () => string[];
     /** Wire protocol for the boundary bindings the pack produces, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
+    /**
+     * The methods a deploy manifest says the platform calls in a file,
+     * given the file's absolute path. The adapter builds the units on each
+     * method it finds by name, and the call walk starts there.
+     */
+    entryPoints?: (file: string) => DeclaredEntryPoint[];
     /** The calls the library offers a project for making a request. */
     clients?: RbClientCall[];
     /** The library's model calls that read or write the database. */
@@ -378,12 +397,69 @@ interface RubyPack {
     inflections?: RbInflections;
     /** Methods the library offers that hand back the argument at `argument`, keyed on the module the callee comes from. */
     transparentWrappers?: UnwrapsByName[];
+    /**
+     * Methods the library adds to every object, nil included, that hand
+     * back the receiver or nil when it is blank, such as ActiveSupport's
+     * `presence`. A read followed by one of these and `||` has a fallback.
+     */
+    blankToNil?: string[];
     /** How the library builds test records from named factories. */
     factories?: RbFactories[];
     /** How a class-based test runner declares tests, as Minitest does. */
     testClasses?: RbTestClasses[];
     /** How the library writes a test, so each one becomes a `test` unit a PRD scenario can list under `coveredBy`. */
     tests?: RbTestCases[];
+    /** How the library runs a method later in a worker, and the calls that enqueue it. */
+    jobs?: RbJobPattern[];
+}
+/**
+ * A background job library. A job's method becomes a `consumer` unit on
+ * a message-bus channel, and a call that enqueues it becomes a message
+ * send to that channel. DESIGN.md says how the adapter reads each kind.
+ */
+type RbJobPattern = RbJobClasses | RbMailers;
+/**
+ * Job classes with one method the worker runs, as ActiveJob and Sidekiq
+ * write them: `ReportJob.perform_later(id)` runs `ReportJob#perform(id)`.
+ * The channel is the class, with the queue the class declares in front.
+ */
+interface RbJobClasses {
+    type: "jobClasses";
+    messageBus: MessageBusTechnology;
+    /** Library bases a job class extends, as a project writes them: `ActiveJob::Base`. */
+    baseClasses: string[];
+    /** Library modules a job class includes: `Sidekiq::Job`. */
+    modules: string[];
+    /** The instance method the worker runs: `perform`. */
+    performMethod: string;
+    /** The class methods that enqueue a job, each with the position its first job argument is at: `perform_in` takes the delay first. */
+    enqueueMethods: Record<string, number>;
+    /** Class methods that return the job with options set, so an enqueue can be called on their result: `set`. */
+    optionMethods: string[];
+    /** The class-body calls that declare the job's queue. */
+    queueDeclarations: RbQueueDeclaration[];
+}
+/** A class-body call that declares a job's queue, and where it takes the queue. */
+interface RbQueueDeclaration {
+    /** `queue_as`, or `sidekiq_options`. */
+    call: string;
+    /** Where the call takes the queue: positionally for `queue_as :exports`, or under a keyword for `sidekiq_options queue: "push"`. */
+    queue: RbArgumentPlace;
+}
+/**
+ * Mailers, as ActionMailer writes them: every public instance method is
+ * a message, and `UserMailer.welcome(user).deliver_later` enqueues
+ * `UserMailer#welcome(user)`. The channel is `UserMailer.welcome`.
+ */
+interface RbMailers {
+    type: "mailers";
+    messageBus: MessageBusTechnology;
+    /** Library bases a mailer extends: `ActionMailer::Base`. */
+    baseClasses: string[];
+    /** The calls on a built message that enqueue it: `deliver_later`. */
+    enqueueMethods: string[];
+    /** Class methods that return the mailer with parameters set, so the message can be built on their result: `with`. */
+    optionMethods: string[];
 }
 /**
  * Tests written as nested blocks, the way RSpec writes them:
@@ -954,6 +1030,62 @@ interface RbFormatSwitch {
     /** The format that accepts every request, `any` for Rails. */
     matchesEvery?: string;
 }
+/**
+ * The methods a library runs on a wired class before the one that
+ * resolves the field. A hook that raises ends the field with that
+ * exception. A hook whose value is false or nil stops the field, and the
+ * resolver never runs. Any other value lets the field go on to the next
+ * hook, then to the resolver.
+ */
+interface RbResolverHooks {
+    /** The hook methods, in the order the library runs them. */
+    methods: string[];
+    /**
+     * True when the library takes a list's first element as the hook's
+     * answer, so `return false, payload` stops the field and returns the
+     * payload in its place.
+     */
+    answerIsListHead?: boolean;
+    /**
+     * The class the library raises when a hook listed here returns false
+     * with no payload. A hook not listed makes the field resolve to null
+     * instead. graphql-ruby raises for `authorized?` and returns null for
+     * `ready?`.
+     */
+    refusalRaises?: Record<string, string>;
+}
+/** How a library reads whether a field's value, or the items of a list it returns, can be null. */
+interface RbGraphqlNullability {
+    /** The keyword on a field or type call, and inside a list type, that says whether the value can be null. */
+    keyword: string;
+    /** The class-level call a wired class makes to say whether the field it resolves can be null. */
+    callName?: string;
+    /** Whether a field can be null when nothing says. */
+    nullableByDefault: boolean;
+    /** Whether a list's items can be null when the list type does not say. */
+    listItemsNullableByDefault: boolean;
+}
+/**
+ * A type the library generates from another one when a method is called
+ * on it, such as `CampaignType.connection_type`. In every name below,
+ * `{type}` is replaced with the wrapped type's GraphQL name, and a ref
+ * named `{type}` alone is the wrapped type.
+ */
+interface RbGraphqlTypeWrapper {
+    /** The name of the type the field returns. */
+    name: string;
+    /** Each type the wrapper generates, by name, with its fields. */
+    types: Record<string, Record<string, TypeShape>>;
+    /**
+     * Other types the method takes as keyword arguments, keyed by the ref
+     * name in `types` that each one replaces, with the library type used
+     * when the call passes none.
+     */
+    typeArguments?: Record<string, {
+        keyword: string;
+        fallback: string;
+    }>;
+}
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
@@ -970,11 +1102,27 @@ interface GraphqlObjectFields {
     fieldCallName: string;
     /** The DSL call declaring a referenced class's own return type. */
     typeCallName: string;
+    /** The keyword a field call can give its type under, in place of its second positional argument. */
+    typeKeyword?: string;
+    /** The class-level call that sets a type's GraphQL name, in place of the one `typeNameConvention` derives. */
+    typeNameCallName?: string;
+    /** How a field says its value can be null. Without it, a resolver's output says nothing about null. */
+    nullability?: RbGraphqlNullability;
+    /** Methods that, called on a type class, give a type the library generates from it, keyed by method name. */
+    typeWrappers?: Record<string, RbGraphqlTypeWrapper>;
+    /** Object types the library defines itself, which a generated type refers to, by name with their fields. */
+    libraryTypes?: Record<string, Record<string, TypeShape>>;
+    /** Classes whose instance, when a resolver returns one, the library reports as an error in place of the field's value. */
+    returnedErrorClassNames?: string[];
     argumentCallName: string;
     /** Keywords whose value is a class to read the declared contract from, one hop away. They are tried in the order listed. */
     wiringKeywords: string[];
     /** The method a wired class defines to resolve the field it is wired to. */
     resolverMethodName: string;
+    /** The keyword on a field call that says which of the type's own methods resolves it, in place of the method with the field's name. */
+    resolverMethodKeyword?: string;
+    /** The methods the library runs on a wired class before `resolverMethodName`, any of which can stop the field. */
+    resolverHooks?: RbResolverHooks;
     /** The library's own classes that a project's class chain ends at. */
     ancestryRootClassNames: string[];
     /** The keyword on an argument call that says whether the argument is required. */
@@ -1009,6 +1157,44 @@ interface GraphqlObjectFields {
     };
 }
 
+/**
+ * The calls a body makes, as invocation effects. A call written under an
+ * `if` records that test as a precondition, and the IR treats a call
+ * with preconditions as one that does not always run.
+ */
+
+/** Methods the pack says the library defines, so a receiverless call to one of them is not project work. */
+type InheritedMethods = ReadonlySet<string>;
+/** An effect a reader built from the source, and the node it built it from. */
+interface EffectAt {
+    effect: Effect;
+    at: Node;
+}
+
+/**
+ * Background jobs: the method a worker runs later, and the calls that
+ * enqueue it.
+ *
+ * A class whose ancestry reaches one of a job pattern's base classes, or
+ * mixes in one of its modules, is a job. The method the worker runs
+ * becomes a `consumer` unit bound to a message-bus channel, and a call
+ * that enqueues the job becomes a `message-send` to that channel with the
+ * job's arguments. Both sides decide whether a class is a job through the
+ * same ancestry rules, so they agree on the channel. An enqueue whose job
+ * the rules do not settle is recorded with no channel, and the summary
+ * gets a gap for it. DESIGN.md has the spellings each kind reads.
+ */
+
+/** One job pattern, with the pack that declared it, which its effects and units are recognized as. */
+interface RbJobDeclaration {
+    readonly pattern: RbJobPattern;
+    readonly recognition: string;
+}
+interface RbJobOptions {
+    readonly facts: Database;
+    readonly declarations: readonly RbJobDeclaration[];
+}
+
 /**
  * Finds the calls in a Ruby body that read or write the database.
  *
@@ -1050,16 +1236,7 @@ declare function storageClaims(call: Node, file: string, options: RbStorageOptio
  * calls were read from, which the constant bindings are keyed on.
  * `enclosing` is the method the calls are in, or null outside one.
  */
-declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): Effect[];
-
-/**
- * The calls a body makes, as invocation effects. A call written under an
- * `if` records that test as a precondition, and the IR treats a call
- * with preconditions as one that does not always run.
- */
-
-/** Methods the pack says the library defines, so a receiverless call to one of them is not project work. */
-type InheritedMethods = ReadonlySet<string>;
+declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): EffectAt[];
 
 /**
  * The shared groups a run's test files define, and where each one is
@@ -1148,6 +1325,8 @@ interface BodyReadOptions {
     readonly facts?: Database | undefined;
     /** The storage patterns that decide whether a call reads or writes the database. Absent when no pack declares any. */
     readonly storage?: RbStorageOptions | undefined;
+    /** The job patterns that decide whether a call enqueues a background job. Absent when no pack declares any. */
+    readonly jobs?: RbJobOptions | undefined;
     /** The methods the run's packs declare their libraries define. Calls to them are left off an effect list. */
     readonly inheritedMethods?: InheritedMethods | undefined;
     /** The calls whose block the run's packs declare runs as part of the surrounding body. */
@@ -1473,9 +1652,9 @@ declare function rubyStubEvidence(options: RubyStubEvidenceOptions): Promise<Rub
 /**
  * Turns a Ruby DSL call's type argument into an IR type shape.
  *
- * The argument is only read when it is a literal constant, or a one-element
- * array wrapping one. A type written as a lambda or a method call abstains
- * rather than guessing at what it evaluates to.
+ * It reads a constant, a one-element array of one, or a wrapper method the
+ * pack declares called on one. A lambda or any other call abstains rather
+ * than guessing at what it evaluates to.
  */
 
 interface TypeReadContext {
@@ -1486,6 +1665,8 @@ interface TypeReadContext {
     scalars: Readonly<Record<string, TypeShape>>;
     scalarNamePrefixes: readonly string[];
     typeNameConvention: GraphqlTypeNameConvention;
+    /** The methods that turn a type into one the library generates, with that type's name, as `{type}Connection`. */
+    typeWrapperNames?: Readonly<Record<string, string>>;
 }
 /**
  * Returns null when the type cannot be read, and the field then abstains.
@@ -1507,4 +1688,4 @@ declare function typeShapeFromNode(node: Node, ctx: TypeReadContext): TypeShape
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantFileCache, type ConstantPathConvention, type ControllerActions, type ControllerRoute, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type KeptRubyParses, type LibraryException, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbExpectations, type RbFactories, type RbFactoryBuilder, type RbFormatSwitch, type RbInflections, type RbPredicateMatcher, type RbRawSqlPattern, type RbRowCall, type RbSharedInclude, type RbStatusCall, type RbStorageOptions, type RbStoragePattern, type RbTestCases, type RbTestClasses, type RbTestMocks, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bindEvaluator, bodyStatements, booleanLiteralValue, children, collectFileConstants, createConstantFileCache, createFileCache, discoverUnits, emitConstantBindings, emitValueFacts, evaluatedValue, extractRubyProject, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, keptRubyParses, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubyAhead, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, walkClasses, walkDefinitions };
+export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantFileCache, type ConstantPathConvention, type ControllerActions, type ControllerRoute, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type KeptRubyParses, type LibraryException, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbExpectations, type RbFactories, type RbFactoryBuilder, type RbFormatSwitch, type RbGraphqlNullability, type RbGraphqlTypeWrapper, type RbInflections, type RbJobClasses, type RbJobPattern, type RbMailers, type RbPredicateMatcher, type RbQueueDeclaration, type RbRawSqlPattern, type RbResolverHooks, type RbRowCall, type RbSharedInclude, type RbStatusCall, type RbStorageOptions, type RbStoragePattern, type RbTestCases, type RbTestClasses, type RbTestMocks, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bindEvaluator, bodyStatements, booleanLiteralValue, children, collectFileConstants, createConstantFileCache, createFileCache, discoverUnits, emitConstantBindings, emitValueFacts, evaluatedValue, extractRubyProject, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, keptRubyParses, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubyAhead, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, walkClasses, walkDefinitions };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { Database } from '@suss/datalog';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
-import { TypeShape, RequestSpellingMetadata, Effect, BehavioralSummary } from '@suss/behavioral-ir';
+import { MessageBusTechnology, TypeShape, RequestSpellingMetadata, Effect, BehavioralSummary } from '@suss/behavioral-ir';
+import { DeclaredEntryPoint, RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { UnwrapsByName, WhyExplained } from '@suss/resolution';
-import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { Value } from '@suss/values';
 
 /**
@@ -284,6 +284,12 @@ interface AncestorLookup {
      * file is visible without a file of its own.
      */
     localDefinition?(qualifiedName: string): ReachedBody[] | null;
+    /**
+     * The blocks any file in the run defines under a name, consulted after
+     * `localDefinition` and before the path convention. The path convention
+     * then only finds a class the run did not read.
+     */
+    definedInRun?(qualifiedName: string): Promise<ReachedBody[] | null>;
 }
 /**
  * Every block a file defines under `qualifiedName`, or null when no file
@@ -352,9 +358,22 @@ interface RubyPack {
      * cache key, so editing one of them forces a re-extract.
      */
     discoveryInputs?: (files: readonly string[]) => string[];
+    /**
+     * Files the library renders through ERB when the app boots, such as
+     * Rails' `config/database.yml`, as absolute paths. The adapter reads
+     * each one as the Ruby in its tags, run when the app loads, so a read of
+     * `ENV` there goes on a load-time unit for the file.
+     */
+    bootTemplates?: () => string[];
     /** Wire protocol for the boundary bindings the pack produces, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
+    /**
+     * The methods a deploy manifest says the platform calls in a file,
+     * given the file's absolute path. The adapter builds the units on each
+     * method it finds by name, and the call walk starts there.
+     */
+    entryPoints?: (file: string) => DeclaredEntryPoint[];
     /** The calls the library offers a project for making a request. */
     clients?: RbClientCall[];
     /** The library's model calls that read or write the database. */
@@ -378,12 +397,69 @@ interface RubyPack {
     inflections?: RbInflections;
     /** Methods the library offers that hand back the argument at `argument`, keyed on the module the callee comes from. */
     transparentWrappers?: UnwrapsByName[];
+    /**
+     * Methods the library adds to every object, nil included, that hand
+     * back the receiver or nil when it is blank, such as ActiveSupport's
+     * `presence`. A read followed by one of these and `||` has a fallback.
+     */
+    blankToNil?: string[];
     /** How the library builds test records from named factories. */
     factories?: RbFactories[];
     /** How a class-based test runner declares tests, as Minitest does. */
     testClasses?: RbTestClasses[];
     /** How the library writes a test, so each one becomes a `test` unit a PRD scenario can list under `coveredBy`. */
     tests?: RbTestCases[];
+    /** How the library runs a method later in a worker, and the calls that enqueue it. */
+    jobs?: RbJobPattern[];
+}
+/**
+ * A background job library. A job's method becomes a `consumer` unit on
+ * a message-bus channel, and a call that enqueues it becomes a message
+ * send to that channel. DESIGN.md says how the adapter reads each kind.
+ */
+type RbJobPattern = RbJobClasses | RbMailers;
+/**
+ * Job classes with one method the worker runs, as ActiveJob and Sidekiq
+ * write them: `ReportJob.perform_later(id)` runs `ReportJob#perform(id)`.
+ * The channel is the class, with the queue the class declares in front.
+ */
+interface RbJobClasses {
+    type: "jobClasses";
+    messageBus: MessageBusTechnology;
+    /** Library bases a job class extends, as a project writes them: `ActiveJob::Base`. */
+    baseClasses: string[];
+    /** Library modules a job class includes: `Sidekiq::Job`. */
+    modules: string[];
+    /** The instance method the worker runs: `perform`. */
+    performMethod: string;
+    /** The class methods that enqueue a job, each with the position its first job argument is at: `perform_in` takes the delay first. */
+    enqueueMethods: Record<string, number>;
+    /** Class methods that return the job with options set, so an enqueue can be called on their result: `set`. */
+    optionMethods: string[];
+    /** The class-body calls that declare the job's queue. */
+    queueDeclarations: RbQueueDeclaration[];
+}
+/** A class-body call that declares a job's queue, and where it takes the queue. */
+interface RbQueueDeclaration {
+    /** `queue_as`, or `sidekiq_options`. */
+    call: string;
+    /** Where the call takes the queue: positionally for `queue_as :exports`, or under a keyword for `sidekiq_options queue: "push"`. */
+    queue: RbArgumentPlace;
+}
+/**
+ * Mailers, as ActionMailer writes them: every public instance method is
+ * a message, and `UserMailer.welcome(user).deliver_later` enqueues
+ * `UserMailer#welcome(user)`. The channel is `UserMailer.welcome`.
+ */
+interface RbMailers {
+    type: "mailers";
+    messageBus: MessageBusTechnology;
+    /** Library bases a mailer extends: `ActionMailer::Base`. */
+    baseClasses: string[];
+    /** The calls on a built message that enqueue it: `deliver_later`. */
+    enqueueMethods: string[];
+    /** Class methods that return the mailer with parameters set, so the message can be built on their result: `with`. */
+    optionMethods: string[];
 }
 /**
  * Tests written as nested blocks, the way RSpec writes them:
@@ -954,6 +1030,62 @@ interface RbFormatSwitch {
     /** The format that accepts every request, `any` for Rails. */
     matchesEvery?: string;
 }
+/**
+ * The methods a library runs on a wired class before the one that
+ * resolves the field. A hook that raises ends the field with that
+ * exception. A hook whose value is false or nil stops the field, and the
+ * resolver never runs. Any other value lets the field go on to the next
+ * hook, then to the resolver.
+ */
+interface RbResolverHooks {
+    /** The hook methods, in the order the library runs them. */
+    methods: string[];
+    /**
+     * True when the library takes a list's first element as the hook's
+     * answer, so `return false, payload` stops the field and returns the
+     * payload in its place.
+     */
+    answerIsListHead?: boolean;
+    /**
+     * The class the library raises when a hook listed here returns false
+     * with no payload. A hook not listed makes the field resolve to null
+     * instead. graphql-ruby raises for `authorized?` and returns null for
+     * `ready?`.
+     */
+    refusalRaises?: Record<string, string>;
+}
+/** How a library reads whether a field's value, or the items of a list it returns, can be null. */
+interface RbGraphqlNullability {
+    /** The keyword on a field or type call, and inside a list type, that says whether the value can be null. */
+    keyword: string;
+    /** The class-level call a wired class makes to say whether the field it resolves can be null. */
+    callName?: string;
+    /** Whether a field can be null when nothing says. */
+    nullableByDefault: boolean;
+    /** Whether a list's items can be null when the list type does not say. */
+    listItemsNullableByDefault: boolean;
+}
+/**
+ * A type the library generates from another one when a method is called
+ * on it, such as `CampaignType.connection_type`. In every name below,
+ * `{type}` is replaced with the wrapped type's GraphQL name, and a ref
+ * named `{type}` alone is the wrapped type.
+ */
+interface RbGraphqlTypeWrapper {
+    /** The name of the type the field returns. */
+    name: string;
+    /** Each type the wrapper generates, by name, with its fields. */
+    types: Record<string, Record<string, TypeShape>>;
+    /**
+     * Other types the method takes as keyword arguments, keyed by the ref
+     * name in `types` that each one replaces, with the library type used
+     * when the call passes none.
+     */
+    typeArguments?: Record<string, {
+        keyword: string;
+        fallback: string;
+    }>;
+}
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
@@ -970,11 +1102,27 @@ interface GraphqlObjectFields {
     fieldCallName: string;
     /** The DSL call declaring a referenced class's own return type. */
     typeCallName: string;
+    /** The keyword a field call can give its type under, in place of its second positional argument. */
+    typeKeyword?: string;
+    /** The class-level call that sets a type's GraphQL name, in place of the one `typeNameConvention` derives. */
+    typeNameCallName?: string;
+    /** How a field says its value can be null. Without it, a resolver's output says nothing about null. */
+    nullability?: RbGraphqlNullability;
+    /** Methods that, called on a type class, give a type the library generates from it, keyed by method name. */
+    typeWrappers?: Record<string, RbGraphqlTypeWrapper>;
+    /** Object types the library defines itself, which a generated type refers to, by name with their fields. */
+    libraryTypes?: Record<string, Record<string, TypeShape>>;
+    /** Classes whose instance, when a resolver returns one, the library reports as an error in place of the field's value. */
+    returnedErrorClassNames?: string[];
     argumentCallName: string;
     /** Keywords whose value is a class to read the declared contract from, one hop away. They are tried in the order listed. */
     wiringKeywords: string[];
     /** The method a wired class defines to resolve the field it is wired to. */
     resolverMethodName: string;
+    /** The keyword on a field call that says which of the type's own methods resolves it, in place of the method with the field's name. */
+    resolverMethodKeyword?: string;
+    /** The methods the library runs on a wired class before `resolverMethodName`, any of which can stop the field. */
+    resolverHooks?: RbResolverHooks;
     /** The library's own classes that a project's class chain ends at. */
     ancestryRootClassNames: string[];
     /** The keyword on an argument call that says whether the argument is required. */
@@ -1009,6 +1157,44 @@ interface GraphqlObjectFields {
     };
 }
 
+/**
+ * The calls a body makes, as invocation effects. A call written under an
+ * `if` records that test as a precondition, and the IR treats a call
+ * with preconditions as one that does not always run.
+ */
+
+/** Methods the pack says the library defines, so a receiverless call to one of them is not project work. */
+type InheritedMethods = ReadonlySet<string>;
+/** An effect a reader built from the source, and the node it built it from. */
+interface EffectAt {
+    effect: Effect;
+    at: Node;
+}
+
+/**
+ * Background jobs: the method a worker runs later, and the calls that
+ * enqueue it.
+ *
+ * A class whose ancestry reaches one of a job pattern's base classes, or
+ * mixes in one of its modules, is a job. The method the worker runs
+ * becomes a `consumer` unit bound to a message-bus channel, and a call
+ * that enqueues the job becomes a `message-send` to that channel with the
+ * job's arguments. Both sides decide whether a class is a job through the
+ * same ancestry rules, so they agree on the channel. An enqueue whose job
+ * the rules do not settle is recorded with no channel, and the summary
+ * gets a gap for it. DESIGN.md has the spellings each kind reads.
+ */
+
+/** One job pattern, with the pack that declared it, which its effects and units are recognized as. */
+interface RbJobDeclaration {
+    readonly pattern: RbJobPattern;
+    readonly recognition: string;
+}
+interface RbJobOptions {
+    readonly facts: Database;
+    readonly declarations: readonly RbJobDeclaration[];
+}
+
 /**
  * Finds the calls in a Ruby body that read or write the database.
  *
@@ -1050,16 +1236,7 @@ declare function storageClaims(call: Node, file: string, options: RbStorageOptio
  * calls were read from, which the constant bindings are keyed on.
  * `enclosing` is the method the calls are in, or null outside one.
  */
-declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): Effect[];
-
-/**
- * The calls a body makes, as invocation effects. A call written under an
- * `if` records that test as a precondition, and the IR treats a call
- * with preconditions as one that does not always run.
- */
-
-/** Methods the pack says the library defines, so a receiverless call to one of them is not project work. */
-type InheritedMethods = ReadonlySet<string>;
+declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): EffectAt[];
 
 /**
  * The shared groups a run's test files define, and where each one is
@@ -1148,6 +1325,8 @@ interface BodyReadOptions {
     readonly facts?: Database | undefined;
     /** The storage patterns that decide whether a call reads or writes the database. Absent when no pack declares any. */
     readonly storage?: RbStorageOptions | undefined;
+    /** The job patterns that decide whether a call enqueues a background job. Absent when no pack declares any. */
+    readonly jobs?: RbJobOptions | undefined;
     /** The methods the run's packs declare their libraries define. Calls to them are left off an effect list. */
     readonly inheritedMethods?: InheritedMethods | undefined;
     /** The calls whose block the run's packs declare runs as part of the surrounding body. */
@@ -1473,9 +1652,9 @@ declare function rubyStubEvidence(options: RubyStubEvidenceOptions): Promise<Rub
 /**
  * Turns a Ruby DSL call's type argument into an IR type shape.
  *
- * The argument is only read when it is a literal constant, or a one-element
- * array wrapping one. A type written as a lambda or a method call abstains
- * rather than guessing at what it evaluates to.
+ * It reads a constant, a one-element array of one, or a wrapper method the
+ * pack declares called on one. A lambda or any other call abstains rather
+ * than guessing at what it evaluates to.
  */
 
 interface TypeReadContext {
@@ -1486,6 +1665,8 @@ interface TypeReadContext {
     scalars: Readonly<Record<string, TypeShape>>;
     scalarNamePrefixes: readonly string[];
     typeNameConvention: GraphqlTypeNameConvention;
+    /** The methods that turn a type into one the library generates, with that type's name, as `{type}Connection`. */
+    typeWrapperNames?: Readonly<Record<string, string>>;
 }
 /**
  * Returns null when the type cannot be read, and the field then abstains.
@@ -1507,4 +1688,4 @@ declare function typeShapeFromNode(node: Node, ctx: TypeReadContext): TypeShape
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantFileCache, type ConstantPathConvention, type ControllerActions, type ControllerRoute, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type KeptRubyParses, type LibraryException, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbExpectations, type RbFactories, type RbFactoryBuilder, type RbFormatSwitch, type RbInflections, type RbPredicateMatcher, type RbRawSqlPattern, type RbRowCall, type RbSharedInclude, type RbStatusCall, type RbStorageOptions, type RbStoragePattern, type RbTestCases, type RbTestClasses, type RbTestMocks, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bindEvaluator, bodyStatements, booleanLiteralValue, children, collectFileConstants, createConstantFileCache, createFileCache, discoverUnits, emitConstantBindings, emitValueFacts, evaluatedValue, extractRubyProject, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, keptRubyParses, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubyAhead, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, walkClasses, walkDefinitions };
+export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantFileCache, type ConstantPathConvention, type ControllerActions, type ControllerRoute, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type KeptRubyParses, type LibraryException, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbExpectations, type RbFactories, type RbFactoryBuilder, type RbFormatSwitch, type RbGraphqlNullability, type RbGraphqlTypeWrapper, type RbInflections, type RbJobClasses, type RbJobPattern, type RbMailers, type RbPredicateMatcher, type RbQueueDeclaration, type RbRawSqlPattern, type RbResolverHooks, type RbRowCall, type RbSharedInclude, type RbStatusCall, type RbStorageOptions, type RbStoragePattern, type RbTestCases, type RbTestClasses, type RbTestMocks, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bindEvaluator, bodyStatements, booleanLiteralValue, children, collectFileConstants, createConstantFileCache, createFileCache, discoverUnits, emitConstantBindings, emitValueFacts, evaluatedValue, extractRubyProject, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, keptRubyParses, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubyAhead, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, walkClasses, walkDefinitions };