@suss/adapter-python 0.33.1 → 0.34.0

package/dist/index.d.cts

@@ -1,9 +1,18 @@
-import { TypeShape, WrapperReference, BehavioralSummary } from '@suss/behavioral-ir';
+import { RequestSpellingMetadata, TypeShape, WrapperReference, BehavioralSummary } from '@suss/behavioral-ir';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as PyNode, Tree as PyTree } from 'web-tree-sitter';
 import { Database } from '@suss/datalog';
-import { RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
-import { WhyExplained } from '@suss/resolution';
+import { UnwrapsByName, WhyExplained } from '@suss/resolution';
+import { RawCodeStructure, ExtractorOptions, TimingReport, ExtractionReport, CacheDiagnostic, DeclaredModule, KeptParses } from '@suss/extractor';
+
+/**
+ * Loads the Python grammar into web-tree-sitter and parses a file.
+ *
+ * tree-sitter runs as WASM, so the adapter needs no native build step.
+ * The rest of the adapter reaches the parser only through this module
+ * and the node helpers in the `ast` module, so a different Python grammar would
+ * be a change here alone.
+ */
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -50,7 +59,7 @@ type ModuleResolution = {
     reason: "external" | "ambiguous" | "outsideRoots";
 };
 interface ModuleResolverOptions {
-    /** The directories an absolute dotted import is resolved against. We cannot see `sys.path` order, since that only exists at runtime. */
+    /** The directories an absolute dotted import is resolved against. Their order does not matter, because the order of `sys.path` exists only at run time. */
     roots: string[];
 }
 declare function resolveAbsoluteModule(dotted: string, options: ModuleResolverOptions): ModuleResolution;
@@ -64,52 +73,50 @@ declare function resolveRelativeModule(importingFile: string, spec: RelativeModu
 declare function resolveModule(importingFile: string, spec: RelativeModuleSpec, options: ModuleResolverOptions): ModuleResolution;
 
 /**
- * The Python adapter's own pattern-pack contract.
+ * The contract a Python pack is written against.
  *
- * This is deliberately not the TypeScript adapter's `PatternPack`. That type
- * dispatches its discovery variants through ts-morph-specific handlers, and
- * Python's two route shapes have no exact match in its union anyway. Match
- * shapes stay per-language until a second implementation shows what is actually
- * shared, and this is the per-language one for Python.
+ * It is separate from the TypeScript adapter's `PatternPack` on purpose. That
+ * type dispatches its discovery variants through handlers built on ts-morph,
+ * and Python's two kinds of route have no exact match in its union. Each
+ * language keeps its own match patterns until a second implementation shows
+ * which parts the two have in common.
  *
- * A pack is still plain data, following the same rule the TypeScript packs
- * follow: it describes what a library defines, never anything a project chose.
+ * A pack is plain data under the same rule the TypeScript packs follow: it
+ * describes what a library defines, and nothing a project chose.
  */
+
 interface PythonPack {
     name: string;
     /**
-     * Pack version stamp, which feeds the cache invalidation key. Bump on
-     * any change that affects discovered units or extracted summaries.
-     * The CLI folds a hash of the loaded pack file and its config into
-     * this stamp on top, so a pack run through the CLI invalidates on an
-     * edit whether or not it declares a version of its own.
+     * Part of the cache key. Bump it on any change that affects the units a
+     * pack discovers or the summaries it produces. The CLI also adds a hash
+     * of the loaded pack file and its config to the key, so a pack run
+     * through the CLI invalidates the cache on an edit whether or not it
+     * declares a version.
      */
     version?: string;
     /**
-     * Files under the project this pack reads that are not among the
-     * `.py` files a run walks, given the files the run is about to walk.
-     * Their content feeds the same cache key the pack's own config does,
-     * so an edit to one of them re-extracts instead of handing back the
-     * previous answer.
+     * Given the `.py` files a run is about to walk, returns the other files
+     * in the project this pack reads. Their content goes into the cache key
+     * along with the pack's config, so editing one of them re-extracts
+     * instead of returning the cached summaries.
      */
     discoveryInputs?: (files: readonly string[]) => string[];
     /** Wire protocol for the produced boundary bindings, e.g. "http". */
     protocol: string;
     discovery: PythonDiscoveryPattern[];
     /**
-     * Modules the project itself supplies, the wrappers a person names
-     * when configuring the pack. The library's own module is not one of
-     * these: it lives outside the project and would never resolve. The
-     * adapter checks each of these against the project's roots, because
-     * a wrapper that resolves to nothing does not match any decorator
-     * and never says why (#188).
+     * Wrapper modules around the library that a person lists when
+     * configuring the pack. The library's own module does not go here. The adapter
+     * reports each of these that no file in the run imports, since
+     * otherwise it would match no decorator and nothing would say why (#188).
      */
     projectModules?: string[];
     /** The callables the library gives a project for making a request. */
     clients?: PyClientCall[];
-    /** What the library's own database queries look like. The README says how one is matched. */
+    /** What the library's own database queries look like. DESIGN.md says how one is matched. */
     storage?: StoragePattern[];
-    /** Which of the library's calls give back one of a model class. The README says what a chain of them composes into. */
+    /** Which of the library's calls give back one of a model class. DESIGN.md says what a chain of them composes into. */
     models?: PyModelQueries[];
     /** Which of the library's classes return themselves from `__enter__`, so a `with` block gets the object itself. */
     contextManagers?: PyContextManager[];
@@ -117,12 +124,93 @@ interface PythonPack {
     rawSql?: RawSqlPattern[];
     /** The client objects the library hands a project, and the calls on one that reach the database. */
     sqlClients?: SqlClientPattern[];
+    /** Functions the library exports that hand back the argument at `argument`, such as a decorator that returns the function it was given. */
+    transparentWrappers?: UnwrapsByName[];
+    /**
+     * The objects the library puts the request on for a route to read,
+     * such as Flask's module-level `request`. A route is handed no
+     * parameter for them, so without this a value read off one is not
+     * known to come from the request.
+     */
+    requestObjects?: RequestObject[];
+    /** Where a route reads each part of the request, recorded on every route the pack finds. */
+    requestSpelling?: RequestSpellingMetadata;
+    /** How the library's test runner collects tests, so a PRD scenario can say which test covers it. */
+    tests?: PyTestCases[];
+}
+/**
+ * How a test runner finds tests and what it runs around each one. Every
+ * name here is one the runner itself defines or documents; a project's
+ * own conventions come through `files`, which lists the files to read.
+ * DESIGN.md says how the adapter reads each field.
+ */
+interface PyTestCases {
+    /** Base-name patterns of the files the runner collects, `*` matching any run of characters: `test_*.py`. */
+    filePatterns: string[];
+    /** What a test function or method name starts with: `test`. */
+    functionPrefix: string;
+    /** What a class of tests is named starting with: `Test`. */
+    classPrefix: string;
+    /** Base classes whose subclasses contain tests whatever the class is called, as dotted names: `unittest.TestCase`. */
+    caseBaseClasses: string[];
+    /** The functions and methods the runner calls before a test, by where they are written. */
+    setUp: PyTestSetUp;
+    /** Markers whose string arguments are the fixtures every test under them runs through, as dotted names: `pytest.mark.usefixtures`. */
+    usesFixtureMarkers: string[];
+    /** Decorators that declare a fixture, as dotted names: `pytest.fixture`. */
+    fixtureDecorators: string[];
+    /** The keyword on a fixture decorator that renames the fixture: `name`. */
+    fixtureNameKeyword: string;
+    /** The keyword on a fixture decorator that runs it before every test in its scope: `autouse`. */
+    autouseKeyword: string;
+    /** Files whose fixtures apply to every test under their directory: `conftest.py`. */
+    sharedFixtureFiles: string[];
+    /** Decorators that mark a test so it does not run, or runs expecting to fail, as dotted names: `pytest.mark.skip`. */
+    skipDecorators: string[];
+    /** The module or class variable the runner reads markers from for every test under it: `pytestmark`. */
+    markerVariable?: string;
+    /** Parameters the runner fills with something other than a fixture, which are never looked up: `self`, `request`. */
+    reservedParameters: string[];
+    /** How a test replaces something before it runs. */
+    mocks: PyTestMocks;
+    /** Read only these files, matched on whole path segments from the end. Left out, every collected file is read. */
+    files?: string[];
 }
 /**
- * A call talks to the database when the method behind it says it returns one
- * of the library's query types. Matching on the return rather than on the
- * import is what reads a project base class that wraps the library, which is
- * how the measured corpus writes every one of its queries.
+ * The setup a runner calls before a test, listed in the order it calls
+ * them. A method is looked for on the class and then on the project
+ * classes it extends, since the setup is often written on a base class.
+ */
+interface PyTestSetUp {
+    /** Functions in the test's module that run before any test in it: `setup_module`. */
+    module: string[];
+    /** Functions in the test's module that run before each test written as a function: `setup_function`. */
+    function: string[];
+    /** Methods of a class of tests that run before each test in it: `setup_class`, `setup_method`. */
+    testClass: string[];
+    /** Methods of a `caseBaseClasses` subclass that run before each test in it: `setUpClass`, `setUp`. */
+    caseClass: string[];
+}
+/**
+ * The calls that replace a module or a member for the length of a test.
+ * A patcher called with a dotted string replaces the object at that path,
+ * `patch("orders.service.cancel")`. Called with an object and a member
+ * name, it replaces that member, `patch.object(OrderService, "cancel")`.
+ */
+interface PyTestMocks {
+    /** Patchers imported from a library, as dotted names: `unittest.mock.patch`, `unittest.mock.patch.object`. */
+    patchers: string[];
+    /** Patchers a fixture hands the test, by the fixture's parameter name and the methods called on it. */
+    fixturePatchers: {
+        fixture: string;
+        methods: string[];
+    }[];
+}
+/**
+ * A call talks to the database when the method behind it declares that it
+ * returns one of the library's query types. Matching on the return type finds
+ * queries made through a project base class that wraps the library, where a
+ * match on the import would find none.
  */
 interface StoragePattern {
     /** The module a query type is imported from, `sqlalchemy.orm` for a Session. */
@@ -132,39 +220,37 @@ interface StoragePattern {
     /** Chain-ending methods that change what is stored. Anything else reads. */
     writes: string[];
     /**
-     * Methods on a query type that touch no rows of their own: one that runs
-     * a statement built elsewhere, `session.execute(stmt)`, whose own chain
-     * already records the work, and one that manages the session, `close`.
-     * A call to one of these records nothing.
+     * Methods on a query type that touch no rows of their own, and a call to
+     * one records nothing. `session.execute(stmt)` runs a statement whose own
+     * chain already records the work, and `close` manages the session.
      */
     recordsNothing?: string[];
     /**
-     * Methods whose keywords supply column values rather than pick rows,
-     * `values` in `update(User).where(id=1).values(name="x")`. Their
-     * keywords are reported as fields; every other call's keywords are the
-     * selector.
+     * Methods whose keywords supply column values instead of picking rows,
+     * `values` in `update(User).where(id=1).values(name="x")`. Their keywords
+     * are reported as fields, and every other call's keywords as the selector.
      */
     valueMethods?: string[];
     /**
-     * Functions the library exports that start a query on their own, for the
-     * case where a call site imports one rather than reaching it through a
-     * project class. `select(...)` in SQLAlchemy 2.0 is one.
+     * Functions the library exports that start a query on their own, such as
+     * SQLAlchemy 2.0's `select(...)`. A call site imports one directly instead
+     * of reaching it through a project class.
      */
     queryFunctions?: string[];
     /** Which database the library is talking to, for the boundary binding. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
 /**
- * What a library gives back when a call is passed one of a project's
- * model classes, so a method read off the result runs the one that
- * class declares. SQLAlchemy and SQLModel take the class as an argument,
- * `session.get(User, id)` and `select(User)`, rather than as the
- * receiver a Rails finder is called on.
+ * Which of a library's calls give back an instance of the project model
+ * class they were passed, so a method called on the result resolves to the
+ * one that class declares. SQLAlchemy and SQLModel take the class as an
+ * argument, as in `session.get(User, id)` and `select(User)`, where a Rails
+ * finder is called on the class itself.
  */
 interface PyModelQueries {
     /**
-     * The names a model's ancestry arrives at: a base class the library
-     * exports, `DeclarativeBase`, or the function that builds one,
+     * The names a model's base classes lead back to: a base class the
+     * library exports, `DeclarativeBase`, or the function that builds one,
      * `declarative_base`.
      */
     baseNames: string[];
@@ -172,16 +258,16 @@ interface PyModelQueries {
     givesBack: string[];
     /** Methods that take the model class and give back one of it, with the position it is written at. */
     entryMethods: PyModelEntryMethod[];
-    /** Functions the library exports that do the same, called on their own rather than read off a session. */
+    /** Functions the library exports that do the same, called on their own instead of on a session. */
     entryFunctions: PyModelEntryFunction[];
     /** The library's own constructors for a field that reaches another model. */
     relationships?: PyRelationshipConstructor[];
 }
 /**
- * `items: list[Item] = Relationship(...)`: the callable a model's field
- * is given to say it reaches another model, and where it comes from. A
- * project function spelled the same way is somebody else's, so the
- * import is what settles a match.
+ * The callable a model field is assigned from to say it points at another
+ * model, as in `items: list[Item] = Relationship(...)`, and where it is
+ * imported from. A match needs the import, so a project function with the
+ * same name does not count.
  */
 interface PyRelationshipConstructor {
     /** The module it is imported from, `sqlmodel` or `sqlalchemy.orm`. */
@@ -202,9 +288,9 @@ interface PyModelEntryFunction {
 }
 /**
  * The function a library gives a project for handing the database a
- * statement written as SQL, and where it comes from. SQLAlchemy exports
- * `text` from `sqlalchemy`. A local function of the same name is
- * somebody else's, so the import is what settles a match.
+ * statement written as SQL, and where it is imported from. SQLAlchemy
+ * exports `text` from `sqlalchemy`. A match needs the import, so a local
+ * function with the same name does not count.
  */
 interface RawSqlPattern {
     /** The module the function is imported from. */
@@ -216,13 +302,13 @@ interface RawSqlPattern {
 }
 /**
  * A client object a library hands a project, and the calls on one that
- * reach the database. `RawSqlPattern` matches a function the file
- * imported; this matches a method on a value whose class came out of
- * the library, which is how a client built in one module and called in
- * another still reads.
+ * reach the database. `RawSqlPattern` matches a function the file imported.
+ * This matches a method called on a value whose class comes from the
+ * library, so a client built in one module and called in another still
+ * matches.
  *
- * Every field here is the library's own: the module, the class names,
- * the method names, and where each method takes what it is given.
+ * Every field describes the library: the module, the class and method
+ * names, and where each method takes its input.
  */
 interface SqlClientPattern {
     /** The module the client class comes from, `google.cloud.bigquery`. */
@@ -231,9 +317,9 @@ interface SqlClientPattern {
     clientTypes: string[];
     /** The methods that hand the database a statement, and where each takes it. */
     statements?: SqlStatementCall[];
-    /** The methods that say which table rather than writing SQL, and what each does to it. */
+    /** The methods that take a table name instead of SQL, and what each does to the table. */
     tables?: SqlTableCall[];
-    /** The methods that hand back one of another library class, so a chain off one reaches its calls. */
+    /** The methods that return an instance of another of the library's classes, so a chain can continue through it. */
     handsBack?: SqlClientHandoff[];
     /** Which database the client is talking to, for the boundary binding. */
     storageSystem: string;
@@ -252,20 +338,20 @@ interface SqlStatementCall extends SqlCallArgument {
     /** The method name, `query`. */
     method: string;
     /**
-     * The keys down to the statement when it travels inside a dictionary
-     * rather than as the argument itself, the `["query", "query"]` of
+     * The keys to follow when the statement is passed inside a dictionary
+     * instead of as the argument itself: `["query", "query"]` for
      * `insert_job(configuration={"query": {"query": sql}})`.
      */
     path?: string[];
 }
-/** One method that says which table it works on, and what it does to it. */
+/** One method that takes the name of the table it works on, and what it does to that table. */
 interface SqlTableCall extends SqlCallArgument {
     /** The method name, `get_table`. */
     method: string;
     /** Whether the call changes what is stored. */
     kind: "read" | "write";
 }
-/** One method that hands back an object of another of the library's classes. */
+/** One method that returns an instance of another of the library's classes. */
 interface SqlClientHandoff {
     /** The method name, Airflow's `get_client`. */
     method: string;
@@ -276,10 +362,10 @@ interface SqlClientHandoff {
 }
 type PythonDiscoveryPattern = DecoratedClassRoute | DecoratedFunctionRoute;
 /**
- * A class whose `__enter__` gives back the object it was called on, so
- * `with X() as y` makes y the `X()` the block opened. Python
- * lets `__enter__` return anything, so only the library that wrote the
- * class can say this, and a pack declares it for its own classes alone.
+ * Classes whose `__enter__` returns the object it was called on, so
+ * `with X() as y` binds `y` to the `X()` the block opened. Python lets
+ * `__enter__` return anything, so only the library that wrote the class
+ * knows this, and a pack declares it only for its own library's classes.
  */
 interface PyContextManager {
     /** The module the classes come from, `httpx`. */
@@ -289,8 +375,8 @@ interface PyContextManager {
 }
 /**
  * The callables a library gives a project for making a request. A
- * function that calls one of them is a client of the boundary that call
- * states, and gets a unit bound to its method and path.
+ * function that calls one of them becomes a client unit, bound to the
+ * method and path that call is made with.
  */
 interface PyClientCall {
     type: "clientCall";
@@ -316,9 +402,9 @@ interface PyClientCall {
     response?: PyClientResponse;
 }
 /**
- * The members a library's response object gives a caller. A caller that
- * tests one of them is saying which statuses it handles, and the
- * checker compares that against what the other side produces.
+ * The members a library's response object gives a caller. A test on one of
+ * them shows which statuses the caller handles, and the checker compares
+ * that against what the other side sends.
  */
 interface PyClientResponse {
     /** Members whose value is the status code: `status_code`. */
@@ -330,62 +416,80 @@ interface PyClientResponse {
     /** Whether a refused request comes back as a response or raises where it was made. */
     failureDelivery?: "response" | "exception";
 }
+/** An object a module exports that a route reads the request off. */
+interface RequestObject {
+    module: string;
+    name: string;
+}
 /** Conventions both kinds of route share. Each one describes what the library does, never a project's choice. */
 interface RouteConventions {
-    /** How the library spells a path parameter. The README lists the syntaxes we know how to read. */
+    /** How the library writes a path parameter. DESIGN.md lists the syntaxes the adapter reads. */
     pathParamSyntax?: string;
     /** Set it only when the library itself binds an annotated local class to the request body. */
     annotatedClassIsRequestBody?: boolean;
     /**
-     * Callables the library uses to inject a parameter rather than read it
-     * off the request. FastAPI's `Depends` and `Security` are these: the
-     * server supplies the value and the client sends nothing, so a
-     * parameter defaulted to one of them is no part of the request however
-     * its annotation reads.
+     * Callables the library uses to inject a parameter instead of reading it
+     * off the request, such as FastAPI's `Depends` and `Security`. The server
+     * supplies the value and the client sends nothing, so a parameter
+     * defaulted to one of them is not part of the request, whatever its
+     * annotation says.
      */
     injectedParameterCallees?: string[];
     /**
-     * What the library serves when a composed path ends up with repeated
-     * slashes in it. Werkzeug serves the merged path and redirects
-     * the written one, so "merged" is what Flask needs; "kept" is the
-     * default and is what Starlette does.
+     * What the library serves when a composed path has repeated slashes.
+     * Werkzeug serves the merged path and redirects the written one, so Flask
+     * needs "merged". The default, "kept", matches Starlette.
      */
     pathRepeatedSlashes?: PathRepeatedSlashes;
-    /** The status the library returns for a declared response when the route does not give one. Library-defined. */
+    /** The status the library returns for a declared response when the route does not set one. */
     defaultStatusCode?: number;
     /**
      * Set it only when the library reads a status out of the tuple a handler
-     * returns, as Flask does with `return body, 201`. Without it
-     * the library default applies whatever the body returns, and a route
-     * that sets its own status would be reported at the default.
+     * returns, as Flask does with `return body, 201`. Without it, every return
+     * is reported at the library's default status, including a route that
+     * sets its own.
      */
     statusFromReturnedTuple?: boolean;
     /**
      * The library's own callables that end the request with a status, such
-     * as FastAPI's `HTTPException` and Flask's `abort`. Declaring them is
-     * also what makes a `raise` in a route body an outcome of its own: a
-     * raise the list does not cover comes out as a throw with no status,
-     * and one it does cover comes out as the response the library sends.
+     * as FastAPI's `HTTPException` and Flask's `abort`. A `raise` of one in a
+     * route body becomes the response the library sends. A raise of anything
+     * the list does not cover becomes a throw with no status.
      */
     responseStatusCalls?: PyStatusCall[];
     /**
-     * The library's own classes whose instance, when a body returns it, is
-     * the response the library sends, and where each takes the status:
-     * Starlette's `JSONResponse(status_code=...)`. A return of one says its
-     * own status; a return of anything else keeps the declared one.
+     * The library's own classes that are sent as the response when a body
+     * returns an instance, and where each takes the status, as in Starlette's
+     * `JSONResponse(status_code=...)`. Returning one gives that status, and
+     * returning anything else keeps the declared one.
      */
     responseConstructors?: PyStatusCall[];
     /** Unset means the library has no router mounting, and a route's decorator path is used as written. */
     routerComposition?: RouterComposition;
-    /** The ways the library runs a project's own function around a route. The README lists what each one covers. */
+    /**
+     * The callables that say which part of the request a parameter is read
+     * from, by the callee's name, written as the default or inside
+     * `Annotated[...]`: FastAPI's `x_tenant_id: str = Header()` is a header.
+     */
+    parameterSources?: Record<string, ParameterSource>;
+    /** The keyword those callables take a field's name under when it differs from the parameter's, FastAPI's `alias`. */
+    parameterAliasKeyword?: string;
+    /** The ways the library runs a project's own function around a route. DESIGN.md lists what each one covers. */
     wrappers?: PyWrapperForm[];
 }
+/** The part of the request a parameter declared with one callable is read from. */
+interface ParameterSource {
+    /** The role the parameter gets, `headers` for FastAPI's `Header`. */
+    role: string;
+    /** What the library writes in place of `_` in the field's name, `-` for a FastAPI header. */
+    underscoresAs?: string;
+}
 type PyWrapperForm = PyDependencyForm | PyDecoratedWrapperForm;
 /** Where a wrapper is registered, and which routes the registration reaches. */
 interface PyWrapperRegistrar {
     /** The constructor of the object the registration is written on, as the library exports it: `FastAPI`, `APIRouter`. */
     constructorName: string;
-    /** Where the constructor is imported from, when that is not the pattern's own `importModule`: `flask` for the app a flask-restx API is served by. */
+    /** Where the constructor is imported from, when that differs from the pattern's own `importModule`: `flask` for the app that serves a flask-restx API. */
     importModule?: string[];
     /**
      * `everyRoute` for the app, whose registration reaches every route of
@@ -395,13 +499,12 @@ interface PyWrapperRegistrar {
     covers: "everyRoute" | "ownRoutes";
 }
 /**
- * The library calls a project function before the handler, given as an
- * argument to one of its own callables: FastAPI's `Depends(get_user)`.
- * One may be written as a parameter default or inside `Annotated[...]`
- * on the route, or in a list under `keyword` on the route decorator or
- * on one of the registrars. The function runs before the handler and
- * ends the request by raising, so it is a wrapper whose every return
- * hands on.
+ * A project function the library calls before the handler, passed to one
+ * of the library's callables, as in FastAPI's `Depends(get_user)`. It can
+ * be written as a parameter default, inside `Annotated[...]` on the route,
+ * or in a list under `keyword` on the route decorator or a registrar. It
+ * ends a request only by raising, so every return passes control on to
+ * the route.
  */
 interface PyDependencyForm {
     type: "dependency";
@@ -412,11 +515,10 @@ interface PyDependencyForm {
     registrars: PyWrapperRegistrar[];
 }
 /**
- * A project function decorated with a method on the app or a router:
- * `@app.middleware("http")`, `@app.exception_handler(ValueError)`,
- * `@app.before_request`. What the decorated function's returns mean
- * depends on which of the three fields below is set; with none set,
- * every return hands the request on.
+ * A project function decorated with a method on the app or a router, such
+ * as `@app.middleware("http")` or `@app.before_request`. Which of the three
+ * optional fields below is set decides what the function's returns mean.
+ * With none set, every return passes the request on.
  */
 interface PyDecoratedWrapperForm {
     type: "decoratedWrapper";
@@ -430,17 +532,17 @@ interface PyDecoratedWrapperForm {
      */
     continuationParam?: number;
     /**
-     * Set when a value returned ends the request and only a bare return
-     * hands on. Flask's `before_request` works this way.
+     * Set when returning a value ends the request and only a bare return
+     * passes it on. Flask's `before_request` works this way.
      */
     returnedValueResponds?: boolean;
-    /** The position the library hands the raised exception at. Set on an error handler, which runs only when the handler raised. */
+    /** The parameter position the raised exception is passed at. Set on an exception handler, which runs only when the route raised. */
     throwParam?: number;
 }
 /**
- * One callable that ends the request, and where it takes the status.
- * A call may take it either way, so a pattern may state both, and the
- * keyword wins where an argument is written both ways.
+ * One callable that ends the request, and where it takes the status. A
+ * call can pass the status by keyword or by position, so a pattern can
+ * declare both. When a call writes both, the keyword is used.
  */
 interface PyStatusCall {
     /** The callee as the file imports it, module and name together, `fastapi.HTTPException`. */
@@ -453,9 +555,9 @@ interface PyStatusCall {
     defaultStatusCode?: number;
 }
 /**
- * A class has a decorator whose first string-literal argument is the route path,
- * and each method in its body named after an HTTP verb becomes its own unit,
- * with the verb taken from the method name.
+ * A route written as a class whose decorator takes the route path as its
+ * first argument. Each method in the class named after an HTTP verb becomes
+ * its own unit, with the verb taken from the method name.
  */
 interface DecoratedClassRoute extends RouteConventions {
     type: "decoratedClassRoute";
@@ -467,10 +569,10 @@ interface DecoratedClassRoute extends RouteConventions {
     verbMethodNames: Record<string, string>;
 }
 /**
- * A function has a decorator whose attribute name is the HTTP verb and whose
- * first string-literal argument is the route path, the `@app.get(path)`
- * convention. The object it hangs on may be imported, or built one hop away by
- * a call to something imported.
+ * A route written as a function decorated with `@app.get(path)`: the
+ * decorator's attribute name is the HTTP verb and its first argument is the
+ * route path. The object the decorator is called on can be imported, or
+ * built by a call to something imported.
  */
 interface DecoratedFunctionRoute extends RouteConventions {
     type: "decoratedFunctionRoute";
@@ -482,12 +584,12 @@ interface DecoratedFunctionRoute extends RouteConventions {
     statusCodeKeyword?: string;
 }
 /**
- * What a library calls the pieces of router mounting, so a route's served path
- * can be built from the literal prefixes written along the way: the router
- * constructor's own, the one at the call that mounts it, and, where the pack
- * says so, the prefix on the object the mount is called on. What each spelling
- * of a prefix means, and what makes a composition abstain, is the grid in the
- * adapter's README.
+ * The names a library gives the parts of router mounting, so a route's
+ * served path can be built from the prefixes written along the way: the
+ * router constructor's, the one on the call that mounts it, and, where the
+ * pack declares it, the one on the object the mount is called on. DESIGN.md
+ * has the tables for what each way of writing a prefix means and when a
+ * route abstains.
  */
 interface RouterComposition {
     /** Constructor whose call builds a mountable router, FastAPI's `APIRouter`. */
@@ -495,37 +597,36 @@ interface RouterComposition {
     /** Method that mounts a router onto the app, FastAPI's `include_router`. */
     includeMethodName: string;
     /**
-     * What the mount method calls its router parameter, FastAPI's `router`.
-     * A call that passes the router by keyword rather than by position is
-     * read through this. Unset reads the first argument only.
+     * The mount method's name for its router parameter, FastAPI's `router`,
+     * used to read a call that passes the router by keyword. Unset reads the
+     * first positional argument only.
      */
     routerKeyword?: string;
-    /** One keyword serves the constructor and the mount alike. A library that spells them apart needs two fields here. */
+    /** The prefix keyword, the same at the constructor and the mount. A library that uses two different keywords would need two fields here. */
     prefixKeyword: string;
-    /** Default "prefixes". */
+    /** Whether a prefix written at the mount goes in front of the constructor's ("prefixes") or replaces it ("replaces"). Default "prefixes". */
     mountPrefixEffect?: MountPrefixEffect;
-    /** Set it when the library works out a path for a router that gives no prefix. We cannot work that path out, so such routes abstain. */
+    /** Set it when the library makes up a path of its own for a router constructed with no prefix. The adapter cannot work that path out, so such routes abstain. */
     constructorPrefixRequired?: boolean;
-    /** Default "unreadable". The same setting covers the constructor and the mount. */
+    /** What a prefix written as `""`, `None`, `False` or `0` means: no prefix ("unstated"), or one the route has to abstain on ("unreadable"). Default "unreadable", at the constructor and the mount alike. */
     noValuePrefix?: NoValuePrefix;
-    /** Default "kept". */
+    /** Whether the library trims trailing slashes off a constructor's prefix. Default "kept". */
     constructorPrefixTrailingSlash?: PrefixTrailingSlash;
     /**
-     * Where the object the mount is called on states a prefix of its
-     * own, in front of everything the constructor and the mount state.
-     * Unset means it states none, which is FastAPI's behavior: an app
-     * serves a mounted router exactly where the two prefixes put it.
+     * Where the object the mount is called on states a prefix of its own,
+     * in front of everything the constructor and the mount state. Unset
+     * means it states none. That matches FastAPI, where an app serves a
+     * mounted router exactly where the two prefixes put it.
      */
     mountObjectPrefix?: MountObjectPrefix;
 }
 /**
- * The prefix the object a mount is called on states, and where it is
- * written. flask-restx needs both halves: `Api(prefix=...)` states one
- * on the object itself, and the Flask blueprint the `Api` was built
- * from states another with `Blueprint(name, __name__,
- * url_prefix=...)`. The library serves a route under the blueprint's
- * prefix, then the `Api`'s, then whatever the namespace and the route
- * say.
+ * Where the object a mount is called on states its prefix. flask-restx
+ * needs both fields: `Api(prefix=...)` states one on the object itself,
+ * and the Flask blueprint the `Api` was built from states another with
+ * `Blueprint(name, __name__, url_prefix=...)`. A route is served under
+ * the blueprint's prefix, then the `Api`'s, then the namespace's path and
+ * the route's own.
  */
 interface MountObjectPrefix {
     /** Keyword stating a prefix on the mount object's own construction (flask-restx's `Api(prefix=...)`). */
@@ -534,11 +635,10 @@ interface MountObjectPrefix {
     carrier?: MountObjectCarrier;
 }
 /**
- * An object handed to the mount object's constructor, one hop further
- * out, with a prefix of its own (the Flask blueprint behind an
- * `Api`). Naming it here is what lets the adapter tell that object
- * apart from the plain app that appears in the same argument position and
- * has no prefix at all.
+ * An object passed to the mount object's constructor that has a prefix of
+ * its own, such as the Flask blueprint an `Api` is built from. Declaring
+ * its constructor lets the adapter tell it apart from the plain app, which
+ * is passed in the same argument position and has no prefix.
  */
 interface MountObjectCarrier {
     /** Modules the carrier's constructor is imported from (Flask's `flask`). */
@@ -547,32 +647,28 @@ interface MountObjectCarrier {
     constructorName: string;
     /** Position of the carrier among the mount object's constructor arguments. */
     argumentIndex: number;
-    /** Keyword stating the carrier's prefix, at its construction and at its registration alike (Flask's `url_prefix`). */
+    /** The keyword for the carrier's prefix, at its construction and its registration alike (Flask's `url_prefix`). */
     prefixKeyword: string;
     /**
-     * Method handing the carrier to an already-built mount object
-     * (flask-restx's `init_app`, the application-factory spelling of
-     * `Api(blueprint)`). Unset means the constructor argument is the
-     * only way in.
+     * Method that passes the carrier to a mount object already built, as
+     * flask-restx's `init_app` does in an application factory in place of
+     * `Api(blueprint)`. Unset means the constructor argument is the only
+     * way to pass one.
      */
     handoffMethodName?: string;
     /**
-     * Method registering the carrier somewhere else (Flask's
-     * `register_blueprint`). The adapter reads it only to abstain: a
-     * registration restating the prefix, putting the carrier inside
-     * another carrier, or happening twice moves the served path
-     * somewhere the carrier's own construction no longer says.
+     * Method that registers the carrier somewhere else (Flask's
+     * `register_blueprint`). The adapter reads it only to decide when to
+     * abstain. A registration that restates the prefix, registers the
+     * carrier inside another carrier, or registers it twice serves the
+     * routes somewhere other than where the carrier's construction says.
      */
     registerMethodName: string;
 }
 type MountPrefixEffect = "prefixes" | "replaces";
 type PrefixTrailingSlash = "kept" | "trimmed";
 type NoValuePrefix = "unstated" | "unreadable";
-/**
- * Werkzeug serves the merged path and redirects the written one, so Flask
- * needs "merged". Starlette leaves the path as composed, so FastAPI keeps
- * the default.
- */
+/** Werkzeug merges repeated slashes, so Flask needs "merged". Starlette does not, so FastAPI keeps "kept". */
 type PathRepeatedSlashes = "kept" | "merged";
 
 /**
@@ -581,11 +677,11 @@ type PathRepeatedSlashes = "kept" | "merged";
  * whether that was an import, an assignment, a def, a parameter, or a `global`
  * or `nonlocal` redirect to another scope.
  *
- * It never has to be complete, because "I could not resolve this name" is a
- * legal answer everywhere a name is read. What it has to avoid is being wrong.
- * So it only binds names written directly in a body's own statement list. A
- * definition or import nested inside an `if`, `try`, or `with` block is not
- * found, and a read of it comes back unresolved rather than as a guess.
+ * Every reader of a name accepts an unresolved answer, so the binder can
+ * leave names out, and a wrong binding is what it avoids. It binds names
+ * written directly in a body's statement list, plus the statements of a
+ * `with` body. A definition or import nested inside an `if` or `try` is
+ * left out, and a read of it comes back unresolved instead of guessed.
  */
 
 type ScopeKind = "module" | "class" | "function";
@@ -625,7 +721,7 @@ type Binding = {
 } | {
     kind: "parameter";
 }
-/** The right-hand side, when there is one, so we can trace a decorator's base object one hop back to whatever constructed it. */
+/** The right-hand side, when there is one, so a reader can follow a name one hop back to what constructed it. */
  | {
     kind: "assignment";
     value: Node | null;
@@ -642,7 +738,7 @@ interface ModuleBinding {
     moduleScope: Scope;
     /** The scope a class_definition, a function_definition, or the module node opens, keyed by that node's id. */
     scopeFor: Map<number, Scope>;
-    /** The modules a `from X import *` pulls in. We cannot list what a wildcard brings in, so nothing expands them here. */
+    /** The modules a `from X import *` pulls in. The binder cannot list what a wildcard brings in, so nothing expands them here. */
     openImports: string[];
 }
 declare function bindModule(root: Node): ModuleBinding;
@@ -654,21 +750,35 @@ declare function bindModule(root: Node): ModuleBinding;
  */
 declare function resolveName(scope: Scope, name: string): Binding | null;
 
+/**
+ * Works out the prefix a route inherits from the routers it is mounted
+ * through, ahead of discovery. With `router = APIRouter(prefix="/items")`
+ * and `app.include_router(router, prefix="/api")`, a route on `router` is
+ * served under `/api/items`, a path its own file never states. A chain of
+ * routers mounted on routers adds a pair of prefixes per hop.
+ *
+ * Every prefix goes through `readPrefixKeyword` and comes back stated,
+ * unstated or unreadable. What each spelling means differs by library, so
+ * the pack declares it, and DESIGN.md has the tables. When a path cannot be
+ * settled, the route abstains: discovery keeps its name and gives it no
+ * path, so it pairs with nothing instead of with a guessed path.
+ */
+
 /** One file, already parsed and bound. `buildRouterIndex` takes a project as a list of these. */
 interface BoundPythonFile {
-    /** The absolute path, which is what module resolution joins on. */
+    /** The absolute path. Module resolution matches files on it. */
     file: string;
-    /** The path a gap refers to this file by, which a reader has to be able to open. */
+    /** The path a gap reason prints for this file, so a reader can open it. */
     displayPath: string;
     root: Node;
     module: ModuleBinding;
 }
 /**
- * What the object a decorator hangs on turns out to be. `notRouter` covers the
- * app itself and anything the index never saw constructed, so the decorator's
- * own path stands as written. `composed` gives the prefix to put in front of
- * that path. An `abstain` reason is written to follow "the router this route is
- * declared on ...".
+ * What the object a route decorator is called on turns out to be. `notRouter`
+ * covers the app itself and anything the index never saw constructed, and the
+ * decorator's own path is used as written. `composed` gives the prefix to put
+ * in front of that path. An `abstain` reason is worded to follow "the router
+ * this route is declared on ...".
  */
 type RoutePrefixResolution = {
     kind: "notRouter";
@@ -716,12 +826,14 @@ declare function buildRouterIndex(files: BoundPythonFile[], packs: PythonPack[],
 interface ImportedDefinition {
     /** The class_definition, or the value an assignment gave the name. */
     node: Node;
+    /** The file the definition is written in. */
+    file: string;
     /** The module scope of the file the definition is written in. */
     moduleScope: Scope;
     /** The scopes of that file, keyed by the node that opens each one. */
     scopeFor: Map<number, Scope>;
 }
-/** `scope` is where the name is read, which is what keys the import in the facts. */
+/** `scope` is where the name is read. The facts key an import on the file that reads it. */
 type ImportedDefinitionLookup = (scope: Scope, name: string) => ImportedDefinition | null;
 
 /**
@@ -733,11 +845,11 @@ type ImportedDefinitionLookup = (scope: Scope, name: string) => ImportedDefiniti
  */
 
 /**
- * `definitions` stores each converted class shape once, however many annotations
- * mention it. `scopeMaps` is here so a name written inside a referenced class's
- * body resolves too, not only one written at the annotation's use site; a class
- * read from another file brings that file's scopes along. `importedDefinition`
- * is absent when a caller reads one file on its own, and an imported name is
+ * `definitions` stores each converted class shape once, however many
+ * annotations mention it. `scopeMaps` lets a name written inside a
+ * referenced class's body resolve as well as one at the annotation, and a
+ * class read from another file adds that file's scopes. `importedDefinition`
+ * is null when a caller reads one file on its own, and an imported name is
  * then a ref by name and nothing more.
  */
 interface AnnotationContext {
@@ -747,7 +859,7 @@ interface AnnotationContext {
     /** The alias values being expanded, so `A = B` and `B = A` end rather than recurse. */
     expanding: Set<number>;
 }
-/** `scope` is where the annotation is written, which is how we tell a project-local class from an external name. */
+/** `scope` is where the annotation is written. Resolving the name there tells a project class apart from an external name. */
 declare function annotationToShape(typeNode: Node, scope: Scope, ctx: AnnotationContext): TypeShape;
 /** Exported so a decorator keyword that gives a class name reads the same way as that name written in annotation position. */
 declare function shapeFromName(name: string, scope: Scope, ctx: AnnotationContext): TypeShape;
@@ -757,7 +869,20 @@ interface Range {
     end: number;
 }
 
-/** An argument as written, plus its node so a reader can evaluate what it comes down to. */
+/**
+ * Works out which library a decorator comes from, for discovery.
+ *
+ * `@app.route("/x")` is two steps: the call that builds the decorator, and
+ * applying the result to the function. Discovery needs only the first, so
+ * `classifyDecorator` reads which name the callee resolved to and which
+ * module that name came from, and stops there.
+ *
+ * A decorator re-exported through a project wrapper is handled the same
+ * way the TypeScript packs handle one: the name is classified as an import
+ * of some module, and the pack lists every module it accepts.
+ */
+
+/** An argument as written, plus its node so a reader can evaluate it. */
 type DecoratorArg = DecoratorArgShape & {
     readonly node: Node;
 };
@@ -790,15 +915,15 @@ type DecoratorArgShape = {
     kind: "other";
 };
 interface DecoratorClassification {
-    /** The name as its source module exports it, not the local alias or attribute path it was written under. */
+    /** The name as its source module exports it, whatever alias or attribute path the file wrote it under. */
     importedName: string | null;
     /** The dotted module the name was imported from. It is null whenever `importedName` is null. */
     module: string | null;
-    /** The local variable an attribute decorator hangs on, `app` in `@app.get(...)`. */
+    /** The local variable an attribute decorator is called on, `app` in `@app.get(...)`. */
     objectName: string | null;
     args: DecoratorArg[];
     keywordArgs: Record<string, DecoratorArg>;
-    /** Where the decorator is written. Anything we read out of its arguments uses this as its provenance. */
+    /** Where the decorator is written. Anything read out of its arguments reports this as its location. */
     range: Range;
     /**
      * The module the decorator's object lives in, when the decorator was read
@@ -807,9 +932,9 @@ interface DecoratorClassification {
      */
     objectModule?: ModuleBinding;
     /**
-     * The call the rules say built the object this decorator hangs on. A
-     * router the index never saw under a name is looked up by this call
-     * instead, and a decorator on `self.router` has no name to look up.
+     * The call the rules say built the object this decorator is called on.
+     * The router index looks a router up by this call when it never saw the
+     * router under a name, as with a decorator on `self.router`.
      */
     subjectConstruction?: {
         key: string;
@@ -818,6 +943,13 @@ interface DecoratorClassification {
 }
 declare function classifyDecorator(decoratorNode: Node, module: ModuleBinding, facts?: Database): DecoratorClassification;
 
+/**
+ * Finds the calls in a body that talk to the database, and what each one
+ * does. A pack lists its library's query types, and a call chain matches
+ * when the method behind it declares that it returns one. DESIGN.md says
+ * why the match goes by return type.
+ */
+
 /**
  * What discovery uses for one file. `factsPath` is the path the facts were
  * keyed under, which is the absolute one, while a summary shows the short one.
@@ -826,7 +958,6 @@ interface StorageLookup {
     readonly facts: Database;
     readonly factsPath: string;
     readonly patterns: readonly StoragePattern[];
-    readonly definitionAt: (key: string) => Node | undefined;
     readonly couldMatch: ReadonlySet<string>;
     /** What a pack says about statements a project writes as SQL itself. */
     readonly rawSql?: readonly RawSqlPattern[];
@@ -835,15 +966,16 @@ interface StorageLookup {
 }
 
 /**
- * What a call's callee is: a function in this run the walk can step
- * into, or a reason it cannot.
+ * What a call's callee is: a function in this run that the walk can
+ * follow, or the reason it cannot.
  *
- * The rules in @suss/resolution decide it. Every language feature that
- * moves a value is a hop they already state, so nothing here reads a
- * name, an alias, an attribute, or an instance for itself.
+ * The rules in `@suss/resolution` settle the callee. They already follow
+ * a value through names, aliases, attributes and instances, so nothing
+ * here reads any of those itself.
  *
- * What is left is about files rather than values: a module before the
- * dot, and a name only a wildcard import could have brought in.
+ * This module handles the two cases that depend on files: a module
+ * written before the dot, and a name that only a wildcard import could
+ * have brought in.
  */
 
 /** A function in this run, and the export path its summary gets. */
@@ -859,16 +991,16 @@ interface ReachedFunction {
 /**
  * The project functions a library runs around a route, read from where
  * they are registered: a dependency on a route's parameter or decorator,
- * a dependency list on the app or a router, a function decorated with
- * `@app.middleware(...)` or `@app.exception_handler(...)`. Each one
- * becomes a unit of its own, and every route it reaches lists it, so the
- * extractor can fold its outcomes into the route's. The README says which
- * registrations are read and which are not.
+ * a dependency list on the app or a router, or a function decorated with
+ * `@app.middleware(...)` or `@app.exception_handler(...)`. Each becomes a
+ * unit of its own, and every route it reaches lists it, so the extractor
+ * can fold its outcomes into the route's. DESIGN.md, under "What runs
+ * around a route", lists which registrations are read.
  *
  * A registration on the app reaches every route of the pack in the run,
- * since an app is one per run for every pack that has one. A registration
- * on a router reaches the routes decorated on that same router object,
- * and nothing mounted onto it.
+ * because the run treats a pack's app as the only one. A registration on
+ * a router reaches the routes decorated on that same router object, and
+ * nothing mounted onto it.
  */
 
 interface WrapperIndexOptions {
@@ -894,6 +1026,7 @@ interface Registered {
     reference: WrapperReference;
     form: PyWrapperForm;
 }
+/** A wrapper form with the pattern and pack that declare it. */
 interface FormOf {
     pack: PythonPack;
     pattern: PythonDiscoveryPattern;
@@ -909,7 +1042,15 @@ declare class PythonWrapperIndex {
     private readonly ownRoutes;
     private readonly unitsByKey;
     private readonly unitsByFile;
+    /** Told about every registration, so a cache can repeat the ones a file's discovery made. */
+    onRegistered: ((target: ReachedFunction, declared: FormOf) => void) | null;
     constructor(options: WrapperIndexOptions, filesByPath: ReadonlyMap<string, BoundPythonFile>);
+    /**
+     * The same lookup `wrappersFor` noted under `id`, made again over this
+     * index, or null when `id` is not one of these.
+     */
+    lookAgain(id: string): string | null;
+    private noted;
     /** The project function a module-level name in this file refers to, or null for anything else. */
     functionCalled(file: string, name: string): ReachedFunction | null;
     register(covers: {
@@ -934,30 +1075,29 @@ declare class PythonWrapperIndex {
 }
 
 /**
- * Finds decorated routes and turns each one into a `RawCodeStructure`.
- *
- * Only decorated module-level functions and classes that are declared
- * unconditionally get discovered, the same boundary the binder in scope.ts
- * draws. Nothing here reads into a unit's body, so a route's summary comes out
- * with no branches at all, or with exactly one branch describing what an
- * annotation or a decorator keyword already states, such as a FastAPI
- * `response_model` or `status_code`, or a return annotation.
+ * Finds decorated routes and turns each one into a `RawCodeStructure`, and
+ * collects the client units for outgoing requests alongside them.
  *
- * That is enough to pair a route against a caller by method and path, and it
- * claims nothing about behavior nobody read.
+ * Every decorated definition in the file is classified, wherever it is
+ * written. One a pack's pattern accepts becomes a unit per HTTP method and
+ * per mount. The path is the decorator's first argument with the router
+ * prefixes in front of it. The status and body shape come from decorator
+ * keywords, the return annotation, and each return or raise in the body.
+ * A route that cannot be read keeps its name and gets no path, so it pairs
+ * with nothing.
  */
 
 interface DiscoveryOptions {
     packs: PythonPack[];
     /** Repo-relative or absolute path recorded on each summary's `location.file`. */
     filePath: string;
-    /** Without it, every route object looks like the app itself and paths stand as written. */
+    /** Without it, every route object is treated as the app itself and paths are used as written. */
     routerIndex?: RouterIndex;
     /** Under "strict" a route whose unit cannot be built stops the run instead of abstaining. */
     gapHandling?: ExtractorOptions["gapHandling"];
-    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
+    /** What a pack needs to decide that a call talks to the database. Absent when no pack declares storage. */
     storage?: StorageLookup | undefined;
-    /** The file's absolute path, which module resolution wants; `filePath` may be shortened for display. */
+    /** The file's absolute path, which module resolution needs. `filePath` may be shortened for display. */
     absoluteFile?: string | undefined;
     /** The project's facts, so the rules can say what an object no scope has a binding for was built by. */
     facts?: Database | undefined;
@@ -968,27 +1108,33 @@ interface DiscoveryOptions {
 }
 declare function discoverUnits(root: Node, module: ModuleBinding, options: DiscoveryOptions): RawCodeStructure[];
 
-/** Ask what these calls come down to, then derive. */
+/**
+ * Runs the shared resolution rules over this project's facts. The rules in
+ * `@suss/resolution` are the same ones the TypeScript adapter runs, so a
+ * Python value is followed the same way a TypeScript one is.
+ */
+
+/** Asks the rules to resolve these keys, and derives what follows. */
 declare function resolveCalls(db: Database, callKeys: readonly string[]): void;
 /**
  * The values an object contains under its own keys, in the order the source
  * writes them. Empty when nothing said what the object contains.
  */
 declare function containedValues(db: Database, objectKey: string): string[];
-/** What a call comes down to, when the rules settled it on an object. */
+/** The object a call returns, when the rules settled it on one. */
 declare function objectReturnedBy(db: Database, callKey: string): string | null;
 
 /**
- * values.ts: the facts @suss/resolution already joins, emitted for Python.
- * The relation names and shapes come from that package's own header, so a
- * Python value follows the same rules a TypeScript one does.
+ * Emits the value facts that the rules in @suss/resolution join, read from
+ * Python source. The relations are the ones that package defines, so a
+ * Python value is followed by the same rules as a TypeScript one.
  *
  * A name is keyed by the scope that binds it. A function's own names take
- * the function's key, so two handlers that both write `query` stay apart,
- * and a module's names take the file's key, which is what another file
- * imports back out. Every write to a name in one scope is collected in
- * source order and `valueLeftByWrites` says what the name comes down to,
- * so a reassigned name states one value or none rather than two.
+ * the function's key, so two handlers that both write `query` stay apart.
+ * A module's names take the file's key, and another file's import matches
+ * on that key. Every write to a name in one scope is collected in source
+ * order, and `valueLeftByWrites` decides what the name comes down to, so a
+ * reassigned name gets one value or none, never two.
  */
 
 /**
@@ -1015,21 +1161,27 @@ declare function nameKeyIn(filePath: string, enclosing: Node | null, name: strin
 declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
 
 /**
- * The session behind `suss ask why` on a Python project: a tree-sitter
- * parse of the asked-about source, a way to point at the expression
- * somebody spelled, and the witness proof of what it resolved to,
- * rendered through `@suss/resolution`'s phrases.
+ * The session behind `suss ask why` on a Python project. It finds the
+ * expression a question points at by file, line and text, and renders the
+ * witness proof of what that expression resolved to through the phrases
+ * in `@suss/resolution`.
  *
- * It parses every file under the root and emits the same value facts
- * `extractPythonProject` does, keeping a location for every fact key so
- * a proof's atoms can point back at source. A handle this session hands
- * back pairs a tree-sitter node with the file it came from, since a
- * node alone does not say which file parsed it.
+ * It parses every file under the root and records the same value facts
+ * and pack words `extractPythonProject` does, along with a location for
+ * every fact key, so each step of a proof can point back at the source. A
+ * handle pairs a tree-sitter node with its file, because a node alone
+ * does not say which file it was parsed from.
  */
 
 interface PythonWhySessionOptions {
     /** The project root, which paths in every answer come out relative to. */
     dir: string;
+    /** Directories an absolute import is resolved against. Read from `dir` when absent, the way `extractPythonProject` reads them. */
+    roots?: string[];
+    /** Roots the project directory does not show, such as a checked-out submodule. Added after the others. */
+    additionalRoots?: string[];
+    /** The packs the extraction ran with. A hop only a pack declares, such as `session.get(User, id)` giving back a User, is explained only when that pack is here. */
+    packs?: readonly PythonPack[];
 }
 /** A found node, paired with the file it was parsed from. */
 interface PythonValueHandle {
@@ -1054,8 +1206,8 @@ declare class PythonWhySession {
     findCallee(file: string, startLine: number, endLine: number, calleeText: string): PythonValueHandle | null;
     /**
      * Why `value` resolves to what it does: the witness proof, flattened
-     * to the chain and rendered. Null when the value does not resolve,
-     * which the caller says in its own words.
+     * to the chain and rendered. Null when the value does not resolve, and
+     * the caller then writes its own message.
      */
     explain(value: PythonValueHandle, options?: {
         maxDepth?: number;
@@ -1063,23 +1215,18 @@ declare class PythonWhySession {
     private locate;
     private rootOf;
     private pathOf;
-    /** A file path said relative to the root, or as given when it is outside the root. */
+    /** A file path relative to the root, or unchanged when it is outside the root. */
     private displayPath;
 }
 
 /**
- * The name is part of the key because the range is measured in lines, two
- * units can start on the same line, and `entry` is a set, so keying on the range
- * alone would drop one of them.
+ * The facts the module resolver adds to the shared store.
+ *
+ * `importsModule` records each module a file imports, as written, and
+ * `importsFile` the file an import resolved to. An import the resolver
+ * abstains on gets no file rather than a guessed one.
  */
-declare function unitKey(filePath: string, range: {
-    start: number;
-    end: number;
-}, name: string): string;
-declare function emitEntryFact(db: Database, filePath: string, range: {
-    start: number;
-    end: number;
-}, name: string): void;
+
 /**
  * Every import in the file, wherever it is written. Python code puts an import
  * inside a function to break a cycle between two modules, and a chain through
@@ -1087,17 +1234,74 @@ declare function emitEntryFact(db: Database, filePath: string, range: {
  */
 declare function emitModuleImportFacts(db: Database, filePath: string, module: ModuleBinding, resolverOptions: ModuleResolverOptions): void;
 
+/**
+ * The directories a Python project's absolute imports resolve against:
+ * the project directory, and the source directories it declares.
+ *
+ * A project that keeps its package under `src/` imports it as
+ * `orders.routes`, because installing the project puts `src/` on
+ * `sys.path`. suss cannot run the install, so it reads where
+ * `pyproject.toml` tells the build backend to look, and uses `src/`
+ * when that declares nothing and `src/` contains a package.
+ *
+ * An extra root cannot pick the wrong module, because the module
+ * resolver abstains when two roots both have a file for one import.
+ */
+interface UnreadManifest {
+    /** The file, relative to the project root. */
+    where: string;
+    /** Why it could not be read, in one line. */
+    reason: string;
+}
+interface PythonSourceRoots {
+    /** Absolute: the project directory first, then each source directory declared or found under it. */
+    roots: string[];
+    /** A manifest that might have declared a source directory and could not be read. */
+    unread: UnreadManifest[];
+}
+type TomlTable = Record<string, unknown>;
+type TomlFileRead = {
+    kind: "parsed";
+    value: unknown;
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+declare function readTomlFile(file: string): TomlFileRead;
+declare function tableAt(value: unknown, ...keys: string[]): TomlTable | null;
+declare function pythonSourceRoots(projectRoot: string): PythonSourceRoots;
+
+/**
+ * The entry point for a Python run. It discovers units, assembles their
+ * summaries in the shared IR, and emits the run's facts into one `Database`.
+ *
+ * Every file is parsed and bound first, and the value facts are emitted
+ * across all of them, before discovery runs on any file, because a mount in
+ * one file can refer to a router built in another. Each discovered unit
+ * goes through `@suss/extractor`'s `assembleSummary`, the same assembly the
+ * TypeScript adapter uses, so both languages share one gap detection. With
+ * a cache, a run after an edit replays the files and functions whose
+ * inputs did not change, through the records in `reuse.ts`.
+ */
+
 interface ExtractPythonOptions {
     /** Absolute paths of the files to parse and extract. */
     files: string[];
     packs: PythonPack[];
-    /** Directories an absolute import is resolved against. */
-    roots: string[];
+    /**
+     * Directories an absolute import is resolved against. When absent,
+     * they are read from `projectRoot`: the directory itself and the
+     * source directories its `pyproject.toml` declares, or `src/` when
+     * it contains a package.
+     */
+    roots?: string[];
+    /** Roots that cannot be found from the project directory, such as a checked-out submodule. Added after the others. */
+    additionalRoots?: string[];
     /** When set, `location.file` on each summary is relativized against this. */
     workspaceRoot?: string;
     /** The directory a summary's id measures its file from, when that differs from `workspaceRoot`. */
     projectRoot?: string;
-    /** As well as deciding how much of what nobody could read reaches a summary, "strict" lets a route that cannot be built stop the run. */
+    /** How much of what could not be read goes on a summary. "strict" also makes a route that cannot be built stop the run. */
     gapHandling?: ExtractorOptions["gapHandling"];
     /** Called once with the run's per-phase wall time, for `suss extract --timing`. */
     onTiming?: (report: TimingReport) => void;
@@ -1107,10 +1311,31 @@ interface ExtractPythonOptions {
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
     /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
     cacheDir?: string | null;
+    /** The modules the project lists in `suss.json`, with absolute paths. */
+    modules?: readonly DeclaredModule[];
+    /** Parses an earlier run in this process left, for a file whose text is unchanged. */
+    keptParses?: KeptPythonParses;
 }
+/** A file's tree and the scopes bound over it, as a later run can reuse them. */
+type KeptPythonParses = KeptParses<{
+    root: Node;
+    module: ModuleBinding;
+}>;
+/** A holder for parses between runs, which frees each tree it lets go of. */
+declare function keptPythonParses(): KeptPythonParses;
+/**
+ * Parses these files into `kept` before any run needs them. A run served
+ * whole from the cache parses nothing, so a process that keeps parses
+ * calls this while nobody is waiting.
+ */
+declare function parsePythonAhead(files: readonly string[], kept: KeptPythonParses): Promise<void>;
 interface ExtractPythonResult {
     summaries: BehavioralSummary[];
     facts: Database;
+    /** The roots absolute imports were resolved against. */
+    roots: string[];
+    /** A manifest that might have declared a source directory and could not be read. */
+    unreadManifests: UnreadManifest[];
 }
 /** One parsed file and the packs a run over it would load. */
 interface FileFactsOptions {
@@ -1133,19 +1358,19 @@ declare function extractPythonProject(options: ExtractPythonOptions): Promise<Ex
 declare function findPythonFiles(root: string): string[];
 
 /**
- * Evidence for drafting a project-wrapper dependency stub: every
- * import, anywhere in the project, of the asked module or one of its
- * submodules. A Python decorator pattern matches a wrapper's import
- * module exactly (see discovery.ts's `importModule.includes`), so a
- * stub covers one imported module at a time rather than one package,
- * and this groups by the exact module text a project writes.
+ * Every import in the project of a module or one of its submodules, for
+ * drafting a stub of a project's wrapper package.
+ *
+ * A discovery pattern matches a decorator's import module exactly, so a
+ * stub covers one imported module at a time. The sites are grouped by
+ * the module text as the project wrote it for that reason.
  *
- * This walks every node rather than going through the binder in
- * scope.ts, so an import inside an `if` or `try` still counts as
- * evidence even though the binder would not resolve a name through it.
+ * The walk visits every node instead of asking the binder, so an import
+ * inside an `if` or a `try` still counts here, even though the binder
+ * does not resolve a name through it.
  */
 interface PythonImportSite {
-    /** The name imported at this site, null for a bare `import module`, which binds the whole module rather than one name from it. */
+    /** The name imported at this site. Null for a bare `import module`, which binds the whole module. */
     name: string | null;
     file: string;
     line: number;
@@ -1167,13 +1392,13 @@ interface PythonImportEvidenceOptions {
 declare function pythonImportEvidence(options: PythonImportEvidenceOptions): Promise<PythonImportEvidence[]>;
 
 /**
- * version.ts: this adapter's own half of the cache key.
+ * The Python adapter's part of the extraction cache key.
  *
- * `ADAPTER_VERSION` is the hand-bumped semver. Bump it on any change
- * that affects extraction output: IR shape, discovery semantics,
- * terminal classification, anything that would invalidate previously
- * cached summaries.
+ * Bump `ADAPTER_VERSION` by hand on any change to what extraction
+ * produces, such as the IR it writes, what discovery finds, or how a
+ * terminal is classified. Summaries cached under the old version are
+ * then read again instead of reused.
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type FileFactsOptions, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type SqlCallArgument, type SqlClientHandoff, type SqlClientPattern, type SqlStatementCall, type SqlTableCall, type StoragePattern, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitEntryFact, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, readKey, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, unitKey };
+export { ADAPTER_VERSION, type AnnotationContext, type Binding, type BoundPythonFile, type DecoratedClassRoute, type DecoratedFunctionRoute, type DecoratorArg, type DecoratorClassification, type DiscoveryOptions, type ExtractPythonOptions, type ExtractPythonResult, type FileFactsOptions, type KeptPythonParses, type ModuleBinding, type ModuleResolution, type ModuleResolverOptions, type MountObjectCarrier, type MountObjectPrefix, type MountPrefixEffect, type NoValuePrefix, type ParameterSource, type PathRepeatedSlashes, type PrefixTrailingSlash, type PyModelEntryFunction, type PyModelEntryMethod, type PyModelQueries, type PyStatusCall, type PyTestCases, type PyTestMocks, type PyTestSetUp, type PythonDiscoveryPattern, type PythonImportEvidence, type PythonImportEvidenceOptions, type PythonImportSite, type PythonPack, type PythonSourceRoots, type PythonValueHandle, PythonWhySession, type PythonWhySessionOptions, type RawSqlPattern, type RelativeModuleSpec, type RequestObject, type RouteConventions, type RoutePrefixResolution, type RouterComposition, type RouterIndex, type Scope, type ScopeKind, type SqlCallArgument, type SqlClientHandoff, type SqlClientPattern, type SqlStatementCall, type SqlTableCall, type StoragePattern, type TomlFileRead, type TomlTable, type UnreadManifest, annotationToShape, bindModule, buildRouterIndex, classifyDecorator, containedValues, discoverUnits, emitModuleImportFacts, emitValueFacts, extractPythonProject, factsForFile, findPythonFiles, keptPythonParses, nameKeyIn, nodeId, objectReturnedBy, parsePython, parsePythonAhead, parsePythonSync, preloadPythonGrammar, pythonImportEvidence, pythonSourceRoots, readKey, readTomlFile, resolveAbsoluteModule, resolveCalls, resolveModule, resolveName, resolveRelativeModule, shapeFromName, tableAt };