@suss/resolution 0.33.1 → 0.34.0

package/dist/index.d.ts

@@ -68,6 +68,23 @@ declare function calleeOutcomeOf(db: Database, key: string, program?: OnDemandRu
 declare function couldBeSettled(db: Database, key: string): boolean;
 declare function writtenSourcesOf(db: Database, key: string): string[];
 
+/**
+ * classMember.ts: how an adapter spells a member that only the class
+ * itself has, and none of its instances, such as a Ruby class method or a
+ * TypeScript static.
+ *
+ * Ruby and TypeScript let a class and its instances each have a member of
+ * the same name. An adapter records the class's own member under this
+ * spelling of the name, and spells a read the same way when the read is
+ * off the class itself. A read off an instance keeps the plain name, so
+ * each read finds its own member and never the other. The spelling is the
+ * one YARD and JSDoc give a class member, `Api.create` beside `Api#create`.
+ */
+/** The name a class records its own member `name` under. */
+declare function classMemberName(name: string): string;
+/** The member name a class spelling was made from, or null for a plain name. */
+declare function classMemberOf(name: string): string | null;
+
 /** The tuples of one relation, as strings, which is all a case compares. */
 type FactsOf = (relation: string) => string[][];
 interface ContractCase {
@@ -103,6 +120,262 @@ declare function checkFactContract(sources: Readonly<Record<string, CaseFiles>>,
     problem: string;
 }[]>;
 
+/**
+ * The types a value is declared as, for a caller that wants the class
+ * of a name the source gives no type.
+ *
+ * A parameter nobody annotated still has a type when the callers that
+ * pass it do. The rules follow each argument back to a declaration,
+ * through as many unannotated helpers as the chain has, and report
+ * every type they reach. Whether two of those are one type depends on
+ * what each key refers to, which the adapter knows, so the keys come
+ * back as found. The DESIGN says which callers are checked.
+ */
+
+/**
+ * Each type key the value is declared as, or none when a caller passes
+ * it something no declaration types. A caller passing on a parameter of
+ * its own that nothing types makes no claim.
+ */
+declare function declaredTypesOf(db: Database, key: string, program?: OnDemandRules): string[];
+
+/**
+ * What each piece of an adapter's work depended on, so a cache can tell
+ * which pieces a later run may reuse.
+ *
+ * An adapter runs each piece of work, one file's discovery or one
+ * function's scan, inside `charging`. Every question the work puts to the
+ * rules is charged to it as the values the question demanded, derived or
+ * answered. A question asked a second time is answered from the database,
+ * so what it touched the first time is kept per key and charged again.
+ * Syntax read straight out of another file is charged as that file, and a
+ * lookup in an index built over every file is charged with what it gave
+ * back. `FactLog` then says whose facts changed between two runs.
+ */
+
+/** What one piece of work depended on. */
+interface Dependencies {
+    /** Files whose syntax the work read directly. */
+    readonly files: Set<string>;
+    /** Values the rules asked about, derived or answered for the work, and keys it placed on a summary. */
+    readonly values: Set<string>;
+    /** Lookups in indexes built over every file, by what was looked up, with a hash of what came back. */
+    readonly checks: Map<string, number>;
+}
+declare function noDependencies(): Dependencies;
+declare class DependencyLedger {
+    private readonly files;
+    private readonly fileByValue;
+    private readonly valuesByAsked;
+    private readonly active;
+    constructor(files: Iterable<string>);
+    /** The file a key starts with, or is, or null for a value that is neither. */
+    fileOf(value: string): string | null;
+    private findFile;
+    /** Run `work`, charging everything it asks and reads to `into`. */
+    charging<T>(into: Dependencies, work: () => T): T;
+    /** `charging` for work that awaits. Nothing else may run until it settles. */
+    chargingAsync<T>(into: Dependencies, work: () => Promise<T>): Promise<T>;
+    private readonly hashByValue;
+    /** Dependencies as a cache stores them. The same values come up in many charges, so each is hashed once. */
+    store(dependencies: Dependencies): StoredDependencies;
+    /** Charge a file whose syntax the work read directly. */
+    readFile(file: string): void;
+    /** Charge the file of a node the work read the syntax of. */
+    readKey(key: string): void;
+    /** Charge a key whose facts the work's result depends on without asking about it, such as a callee whose span goes on a summary. */
+    touchKey(key: string): void;
+    /**
+     * Charge a lookup in an index built over every file, such as methods by
+     * name. `id` has to be enough for a later run to look again, and `found`
+     * describes what came back.
+     */
+    looked(id: string, found: string): void;
+    /**
+     * The keys one evaluation asked about for the first time, and every
+     * value the rules asked about or derived on the way to the answer.
+     */
+    evaluated(asking: string, keys: readonly string[], values: ReadonlySet<string>): void;
+    /** Keys asked about again, whose answers are already in the database. */
+    reasked(asking: string, keys: readonly string[]): void;
+    private chargeValues;
+}
+/**
+ * A map built over every file whose lookups report what was looked up
+ * and what came back, so work that reads it by name is charged for it.
+ */
+declare class WatchedMap<K, V> extends Map<K, V> {
+    private readonly seen;
+    constructor(entries: Iterable<readonly [K, V]>, seen: (key: K, value: V | undefined) => void);
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+}
+/** A 32-bit FNV-1a hash, for storing many strings compactly where a collision only costs a re-read. */
+declare function hashString(text: string): number;
+/** Hashes as one string of eight hex digits each, which JSON stores in less space than a list of numbers. */
+declare function packHashes(hashes: Iterable<number>): string;
+declare function unpackHashes(packed: string): number[];
+/** Dependencies as a cache stores them: files and values by hash, lookups by id. */
+interface StoredDependencies {
+    readonly files: string;
+    readonly values: string;
+    readonly checks: readonly (readonly [string, number])[];
+}
+/** One stored record for work that was partly reused and partly done again. */
+declare function mergeStoredDependencies(one: StoredDependencies, other: StoredDependencies): StoredDependencies;
+/** What changed between the run that stored some dependencies and this one. */
+interface Changes {
+    /** Hashes of the files whose content changed. */
+    readonly files: ReadonlySet<number>;
+    /** Hashes of the values whose facts changed. */
+    readonly values: ReadonlySet<number>;
+    /** The lookup stored under `id`, made again in this run, or null when this run cannot make it. */
+    lookAgain(id: string): string | null;
+}
+/**
+ * Whether stored dependencies still describe this run: none of their
+ * files changed, no fact about any of their values changed, and every
+ * lookup comes back the same.
+ */
+declare function stillValid(stored: StoredDependencies, changes: Changes): boolean;
+/** What one file's facts were, stored so a later run can tell whose facts changed. */
+interface StoredFacts {
+    /** For each value in the rows this file emitted on its own, its hash followed by a hash of those rows. */
+    readonly own: string;
+    /** For each key of this file in a row that joins files, its hash followed by a hash of those rows. */
+    readonly joined: string;
+}
+/**
+ * The rows a run emitted file by file, and the rows that join files,
+ * which an adapter adds once every file is in. A cache stores a digest of
+ * the rows each key appears in, and the next run compares. A key whose
+ * rows changed is one whose facts changed. That includes a key in a file
+ * nobody edited, such as a constant reference that a definition in a new
+ * place now binds instead. Names are left out: every way one file reaches
+ * into another goes through a key, and a name like `params` is in the
+ * rows of nearly every file.
+ */
+declare class FactLog {
+    private readonly db;
+    private readonly ledger;
+    private readonly ranges;
+    private readonly joinedRanges;
+    private opened;
+    constructor(db: Database, ledger: DependencyLedger);
+    /** Call before a file emits its own rows. */
+    startFile(): void;
+    /** Call after the file emitted its own rows. */
+    endFile(file: string): void;
+    /** Call before rows that join files are added. There may be several such stretches. */
+    startJoined(): void;
+    endJoined(): void;
+    private fileOf;
+    /** Every row added in a stretch, skipping the answers a question adds, which are not facts. */
+    private rowsIn;
+    private readonly atomHashes;
+    /**
+     * An atom's hash as written, and with its node offsets left out, so a
+     * row that mentions a key next to another hashes the same after an edit
+     * shifts the other. Work that used the other key has it among its own
+     * values, and is checked on it.
+     */
+    private hashesOf;
+    /** Each key in a row, with a hash of the row as seen from that key: the key as written, every other key loose. */
+    private hashesByKey;
+    /** Digests of one file's own rows, by each key in them. */
+    private ownDigests;
+    /** Digests of the rows that join files, by each key in them, grouped by that key's file. */
+    private joinedDigests;
+    /**
+     * Each file's facts to store. `unchanged` lists the files whose content
+     * hashed the same as when `previous` was stored, so their own rows are
+     * taken from there instead of being read again.
+     */
+    stored(files: readonly string[], previous: ReadonlyMap<string, StoredFacts>, unchanged: ReadonlySet<string>): Map<string, StoredFacts>;
+    /** The hashes of every value whose facts changed since `previous` was stored. `changed` lists the files whose content changed. */
+    changedValues(changed: ReadonlySet<string>, previous: ReadonlyMap<string, StoredFacts>): Set<number>;
+}
+
+/**
+ * Which records of a stored cache entry a run can replay, for an adapter
+ * that stores one record per file: what the file's discovery depended
+ * on, and what the walk found for each function written in the file.
+ *
+ * A function's walk record is valid while nothing it depended on changed.
+ * A file's discovery record is valid while nothing its discovery depended
+ * on changed and the walk records of the functions its units start from
+ * are valid too, since those units' summaries carry what the walk placed
+ * on them.
+ */
+
+/** What the walk found for one function, and what that depended on. */
+interface StoredWalkRecord<Scan, Summary> {
+    readonly key: string;
+    readonly dependencies: StoredDependencies;
+    readonly scan: Scan;
+    /** A reached function's summary before parameter gaps were added. Absent for a function a unit starts from. */
+    readonly summary?: Summary;
+}
+/** The parts of a file's record every adapter stores. */
+interface StoredFileRecord<Scan, Summary> {
+    readonly discovery: StoredDependencies;
+    readonly walked: readonly StoredWalkRecord<Scan, Summary>[];
+    readonly facts: StoredFacts;
+}
+/** The file a node key is written in. */
+declare function fileOfKey(key: string): string;
+declare class EntryReuse<Scan, Summary, Record extends StoredFileRecord<Scan, Summary>> {
+    readonly records: ReadonlyMap<string, Record>;
+    readonly changedFiles: ReadonlySet<string>;
+    private readonly changes;
+    /** The keys of the functions a file's units start from. */
+    private readonly seedsOf;
+    private readonly walks;
+    private readonly walkValid;
+    private readonly discoveryValid;
+    constructor(records: ReadonlyMap<string, Record>, changedFiles: ReadonlySet<string>, changes: Changes, 
+    /** The keys of the functions a file's units start from. */
+    seedsOf: (record: Record) => Iterable<string>);
+    /** The walk record for a function, when nothing it depended on changed. */
+    walkOf(key: string): StoredWalkRecord<Scan, Summary> | undefined;
+    /** The record of a file whose discovery can be replayed. */
+    discoveryOf(file: string): Record | undefined;
+}
+/**
+ * The walk records to store, by the file each function is written in.
+ * A replayed scan keeps its stored dependencies, with anything the run
+ * added for it, such as a summary built again, merged in.
+ */
+declare function walkRecordsByFile<Scan, Summary>(args: {
+    scans: ReadonlyMap<string, Scan>;
+    charges: ReadonlyMap<string, Dependencies>;
+    beforeGaps: ReadonlyMap<string, Summary>;
+    replayed: (key: string) => StoredWalkRecord<Scan, Summary> | undefined;
+    store: (dependencies: Dependencies) => StoredDependencies;
+    merge: (one: StoredDependencies, other: StoredDependencies) => StoredDependencies;
+}): Map<string, StoredWalkRecord<Scan, Summary>[]>;
+/**
+ * The records an entry's roots carry, when every root has one and no
+ * file was added or removed since. An added or removed file can change
+ * what a name binds to and which file a path leads to, which no record
+ * says, so the run starts over instead.
+ */
+declare function recordsToReplay<Record extends {
+    readonly discovery: unknown;
+}>(roots: ReadonlyMap<string, {
+    readonly meta: unknown;
+}>, changed: ReadonlySet<string>, removed: ReadonlySet<string>): Map<string, Record> | null;
+
+/**
+ * The functions whose return becomes the process's exit code, for an
+ * adapter that found the values ending up as the code itself: the
+ * argument an exit call hands over, or what is assigned to the code.
+ * DESIGN.md says how the walk gets from a value to a function.
+ */
+
+/** Each function key a call at or reached from one of these values invokes. */
+declare function exitCodeFunctions(db: Database, sinks: readonly string[], program?: OnDemandRules): Set<string>;
+
 /**
  * Turn a witness proof over the resolution rules into the chain a
  * person reads: which value led to which, one reason per hop, with the
@@ -172,6 +445,17 @@ declare function explainResolutionProof(proof: Proof, options: ExplainOptions):
  */
 declare function renderExplanation(explanation: ResolutionExplanation, describe: DescribeAtom): string[];
 
+/**
+ * The files each file in a run depends on, read from `importsFile`.
+ *
+ * No rule reads that relation. An adapter states it, and the run lists
+ * each file's dependencies from it, which is what a cache invalidates a
+ * summary by and what a checker rebuilds the module graph from.
+ */
+
+/** Each importing file's imported files, both spelled by `displayPathOf`. */
+declare function importedFilesByFile(db: Database, displayPathOf: (file: string) => string): Map<string, string[]>;
+
 /**
  * Mount composition, shared between adapters. An adapter states one
  * fact per mount call, `mounted(child, parent, prefix)`, however its
@@ -322,7 +606,7 @@ declare function nodeOfKey<N extends SpannedNode<N>>(rootsByFile: ReadonlyMap<st
  * each new word had to be written three times. `addPackWords` is the one
  * loop; an adapter maps its own pack type onto `PackWords` and calls it.
  *
- * The field names match the fact vocabulary at the top of `index.ts`.
+ * Each field has the name of the relation it adds, as DESIGN.md lists it.
  */
 
 /** A method on a class reaching `base` gives back one of that class. */
@@ -345,17 +629,22 @@ interface EntersAsSelf {
     module: string;
     name: string;
 }
-/** Calling `callee` out of `module` gives back its argument at `argument`. */
+/** Calling the `name` that `module` exports gives back its argument at `argument`. */
 interface UnwrapsByName {
-    callee: string;
-    argument: number;
     module: string;
+    name: string;
+    argument: number;
 }
 /** A field given a call of `module`'s `name` declares an association. */
 interface AssociationConstructor {
     module: string;
     name: string;
 }
+/** A parameter decorated with a call of `module`'s `name` takes its value from that call. */
+interface SuppliesParameter {
+    module: string;
+    name: string;
+}
 /** What a run's packs say about their own libraries, in one language-neutral shape. */
 interface PackWords {
     givesBackOne?: ReadonlyArray<GivesBackOne>;
@@ -364,10 +653,46 @@ interface PackWords {
     entersAsSelf?: ReadonlyArray<EntersAsSelf>;
     unwrapsByName?: ReadonlyArray<UnwrapsByName>;
     associationConstructor?: ReadonlyArray<AssociationConstructor>;
+    /** Methods that hand back the object they are called on, by name. */
+    returnsReceiver?: ReadonlyArray<string>;
+    suppliesParameter?: ReadonlyArray<SuppliesParameter>;
 }
 /** Put a run's pack declarations in the store, so the shared rules can read them. */
 declare function addPackWords(db: Database, words: PackWords): void;
 
+/**
+ * Whether a value leaves the expressions it is read in: returned, handed
+ * to a call, given to another name or object, and so on, each from one
+ * fact an adapter states about the read. A router reader asks it about an
+ * app its own function builds, since a mount on an app nothing can reach
+ * serves nothing. DESIGN.md lists the facts and says why a method call
+ * gets a relation of its own.
+ *
+ * The rules cannot say "no read passes it on", because the demand rewrite
+ * refuses negation. So a caller asks the positive question and treats a
+ * missing row as the value staying put. A read with no fact behind it
+ * looks the same as no read, which is why every spelling needs a fact.
+ */
+
+/** What a caller asks through, `askResolution(db, keys, USES_QUESTION)`, to learn where the value at each key goes. */
+declare const USES_QUESTION = "wantedUses";
+/** What the reads of one value do with it. */
+interface ValueUses {
+    /** Whether some read passes it on, or calls it. */
+    passedOn: boolean;
+    /** The methods called on it, `use` for `app.use(...)`, each once. */
+    methodsCalled: readonly string[];
+}
+/** What the rules derived for one key, read after the question was asked. */
+declare function readUses(db: Database, key: string): ValueUses;
+/**
+ * Whether a value stays in the function that built it: nothing passes it
+ * on or calls it, and every method called on it is one of `ownMethods`.
+ * A router reader passes the methods its pack registers routes and mounts
+ * with, since any other method, `listen` say, may serve the app.
+ */
+declare function staysInItsFunction(uses: ValueUses, ownMethods: ReadonlySet<string>): boolean;
+
 /**
  * The rules an adapter evaluates, and how a question is put to them.
  *
@@ -414,6 +739,18 @@ declare function resolutionUnderProgram(languageRules?: readonly Rule[]): OnDema
  * since then the answers themselves are what clearing would remove.
  */
 declare function queryFacts(program: OnDemandRules): readonly string[];
+/** Tell whoever observes `db` that work read what `key` refers to around the rules. */
+declare function noteKeyRead(db: Database, key: string): void;
+/** Tell whoever observes `db` about a lookup in an index built over every file. */
+declare function noteLookup(db: Database, id: string, found: string): void;
+/** Whether anybody observes `db`, for a lookup whose description costs something to build. */
+declare function isObserved(db: Database): boolean;
+/**
+ * Tell `observer` about every question put to `db` until the returned
+ * function is called. One observer per database; a second replaces the
+ * first.
+ */
+declare function observeDemand(db: Database, observer: DependencyLedger): () => void;
 /**
  * Ask about these values, derive, and take the question back.
  *
@@ -519,7 +856,10 @@ interface WhyExplained {
     stats: ExplainStats;
 }
 interface ExplainResolvedKeyOptions {
-    /** The facts the session extracted. Read, never written to. */
+    /**
+     * The facts the session extracted. The proof pass derives into them,
+     * so nothing else may evaluate rules over this database.
+     */
     db: Database;
     /** The resolution rules plus whatever the language adds to them. */
     rules: Rule[];
@@ -532,6 +872,13 @@ interface ExplainResolvedKeyOptions {
     maxDepth?: number;
     phrases?: Record<string, StepPhrase>;
 }
+/**
+ * The rules a proof of `resolves` can use. A proof pass runs without
+ * demand, over every fact it was given, and the rules under an
+ * allocation site join each site against every value when nothing
+ * narrows them, so they are left out.
+ */
+declare function proofRules(rules: readonly Rule[]): Rule[];
 /**
  * Why `key` resolves to what it does: the witness proof, flattened to
  * the chain and rendered. Null when the key resolves to nothing or to
@@ -540,26 +887,114 @@ interface ExplainResolvedKeyOptions {
 declare function explainResolvedKey(options: ExplainResolvedKeyOptions): WhyExplained | null;
 
 /**
- * What counts as an answer to a question shaped `[key, answer]`, such as
- * `wantedIsWrittenAs` or `wantedSubjectWritten`. A call is written as
- * itself, so a call asked about directly always matches its own key; that
- * row is dropped before the count so one other answer settles it instead
- * of counting as two.
+ * The one reader for an answer the rules derived, such as `wantedResolves`
+ * or `wantedIsWrittenAs`. Adapters and the readers in this package read
+ * every answer through it, so a policy is applied in one place and a new
+ * policy is one edit.
  *
- * A placeholder write, `client = None` before a guard fills it in, is
- * set aside the same way when the key has any other answer. A key
- * written only as a placeholder keeps it.
+ * A placeholder write, `client = None` before a guard fills it in, is set
+ * aside when the key has another answer. A member a subclass overrides is
+ * set aside when the key reads it through that subclass; the demand
+ * rewrite refuses negation, so that happens here rather than in a rule.
+ * A written-as question also sets aside a key's match against itself,
+ * since a call is written as itself. A function does come to itself, so
+ * the other questions keep that row. DESIGN.md has the detail.
+ */
+
+/** Where the rules list, for a read asked about, the members a nearer declaration overrides. */
+interface OverrideRelations {
+    /** `[read, object, member]`: the object contains a member overriding this one. */
+    readonly overridden: string;
+    /** `[read, object, member]`: every member the read finds on each object. */
+    readonly found: string;
+}
+/**
+ * Every answer `key` has in a `[key, answer]` relation, in the order the
+ * rows arrive, with placeholders and overridden members set aside. The
+ * read goes through the relation's index on the key, so a caller asking
+ * about one key pays for that key's rows and nothing else.
+ */
+declare function answersFor(db: Database, relation: string, key: string, overrides?: OverrideRelations): string[];
+/** `answersFor`, for a written-as question, with the key's match against itself set aside. */
+declare function writtenAnswersFor(db: Database, relation: string, key: string): string[];
+/**
+ * Every function that calling this value runs: what the value resolves
+ * to, and what a factory returned when the value was assigned from a
+ * call. The two are settled together, so an override found through one
+ * sets aside the member the other found.
+ */
+declare function resolvedFunctions(db: Database, key: string): string[];
+/** The one function calling this value runs, or null when it settles on none or on several. */
+declare function settledFunction(db: Database, key: string): string | null;
+
+/**
+ * Where a value came from, read from the rows `wantedSource` derives.
  *
- * A caller that can only use one answer takes `singleAnswers`; one with
- * something to say about a value written two ways takes `answersByKey`.
+ * The rules give the chain as steps. This rebuilds the walk from the
+ * value outward and hands back each place it ended, with the properties
+ * read off that place on the way to the value. Saying what an ending
+ * means (an input, a literal, a call the walk could not follow) is the
+ * adapter's job, since each language spells a parameter and a literal
+ * its own way. DESIGN.md has the rules and the reasons.
  */
 
-/** Every answer each key has, in the order the rows arrive, with the two drops above applied. */
-declare function answersByKey(rows: Iterable<Tuple>, placeholders?: ReadonlySet<string>): Map<string, string[]>;
-/** The one answer each key settles on, for a caller that treats several as none. */
-declare function singleAnswers(rows: Iterable<Tuple>, placeholders?: ReadonlySet<string>): Map<string, string>;
-/** The keys an adapter marked `placeholderValue`, for passing to `singleAnswers`. */
-declare function placeholderValues(db: Database): ReadonlySet<string>;
+/** What the walk ended at. */
+type SourceEnd = 
+/** A parameter of the function `of`. The walk never goes on to the callers. */
+{
+    is: "parameter";
+    of: string;
+}
+/** A name imported from a module no file in the run defines. */
+ | {
+    is: "import";
+    module: string;
+    name: string;
+}
+/** A call whose result the walk could not follow. */
+ | {
+    is: "call";
+}
+/** An expression written out in the source, such as a literal. */
+ | {
+    is: "written";
+}
+/** Anything else with no step out of it. */
+ | {
+    is: "other";
+};
+/** One place a value's walk ended. */
+interface SourceLeaf {
+    /** The key of the chain member the walk ended at. */
+    key: string;
+    /** The properties read off it on the way to the value, outermost first. */
+    path: string[];
+    /**
+     * The read nearest the value that takes an entry at a key the source
+     * computes, or null when the way there reads none. The path leaves
+     * that key out, so a caller that needs the whole path stops here.
+     */
+    computedAt: string | null;
+    /** The language's own conversions on the way to the value, outermost first. */
+    conversions: string[];
+    end: SourceEnd;
+}
+/**
+ * How far the walk goes. `wantedSource` follows a call into what its
+ * function returns. `wantedInputRead` follows a name to what it was
+ * written as and a read to what it was read off, and stops at a call,
+ * which is enough to say which input a guard tests.
+ */
+type SourceQuestion = "wantedSource" | "wantedInputRead";
+/** Ask where each value came from, and read where each walk ended. */
+declare function askSources(db: Database, keys: readonly string[], program?: OnDemandRules, question?: SourceQuestion): Map<string, SourceLeaf[]>;
+/**
+ * Every place the walk from `key` ended, for a store that has already
+ * asked `wantedSource` about it. A parameter always ends the walk, even
+ * when a step leads on from it, since the step goes into the caller's
+ * code or a declared type rather than to the value.
+ */
+declare function sourceLeavesOf(db: Database, key: string): SourceLeaf[];
 
 /**
  * Reading an answer that was asked for under one allocation site.
@@ -579,12 +1014,16 @@ declare function isWrittenAsUnder(db: Database, key: string, site: string): stri
 declare function comesToUnder(db: Database, key: string, site: string): string[];
 /** Every object the value refers to under this site, sites included. */
 declare function objectOfUnder(db: Database, key: string, site: string): string[];
+/** Puts each `[key, site]` pair to the rules, the way `askResolutionUnder` does. */
+type AskUnder = (pairs: ReadonlyArray<readonly [string, string]>) => void;
 /**
  * The single expression the value was written as under this site, under
  * the policy the context-free reader applies: two answers are ambiguity,
- * and ambiguity is nothing.
+ * and ambiguity is nothing. A value written as a fallback reads as the
+ * fallback, as `writtenValueOf` reads it, so `a or b` means the same
+ * thing whichever path asked. `ask` puts the fallback's own question.
  */
-declare function writtenValueUnder(db: Database, key: string, site: string): string | null;
+declare function writtenValueUnder(db: Database, key: string, site: string, ask: AskUnder): string | null;
 /**
  * Every site a class was made at, once `askResolution` has asked
  * `wantedSites` about it. These are the sites to put a value question
@@ -649,6 +1088,19 @@ type Ask = (keys: readonly string[]) => void;
  * returns rather than the call itself.
  */
 declare function writtenValueOf(db: Database, key: string, ask: Ask, relation?: string): string | null;
+/**
+ * The fallback, `a or b`, that a value was written as, when the rules
+ * found several expressions and every one of them came through that
+ * fallback. A value reader then reads the fallback whole, and its own
+ * `or` decides: a branch it cannot read makes no claim, and two branches
+ * it can read both count. `writtenValuesOf` still lists the branches, for
+ * a caller that wants each one.
+ *
+ * When one fallback is inside another, the outer one is returned. Null
+ * when no fallback covers all of them, as for a name that two plain
+ * writes leave with two values.
+ */
+declare function fallbackWrittenAs(db: Database, key: string, ask: Ask): string | null;
 /**
  * Every expression a value was written as. More than one is a value with
  * more than one possible source, which a caller says something about at
@@ -675,6 +1127,14 @@ declare const VALUE_STEP: _suss_datalog.Term;
  */
 declare const NAMESPACE_IMPORT_NAME = "*";
 declare const NAMESPACE_IMPORT: _suss_datalog.Term;
+/** The name a default import records itself under, `import React from "react"`. */
+declare const DEFAULT_IMPORT_NAME = "default";
+/**
+ * The module an adapter records a global under, with the global's full
+ * dotted name: `Object.assign` in JavaScript. A pack word keys on it the
+ * way it keys on any other import.
+ */
+declare const GLOBAL_MODULE = "global";
 /**
  * The label on the `comesFrom` rule for a member read off a whole-module
  * import. `explain` tells that proof from the two import ones by it.
@@ -685,8 +1145,27 @@ declare const NAMESPACE_MEMBER_RULE = "namespace member";
  * `explain` says a name came from a base class when it fired.
  */
 declare const BASE_CLASS_RULE = "base class";
+/**
+ * The label on the `hop` rule that takes a name hop. `explain` gives the
+ * name hop's own reason for that step, since this rule adds nothing to it.
+ */
+declare const NAME_HOP_RULE = "name hop";
 /** A step from an instance to the class it is one of. */
 declare const INSTANCE_STEP: _suss_datalog.Term;
+/**
+ * The last column of `storesProperty`: whether the write went through the
+ * receiver, keyed on the method that wrote it, or through a name, keyed on
+ * the name. DESIGN.md says why the two cannot share a key.
+ */
+declare const RECEIVER_STORE_NAME = "receiver";
+declare const NAMED_STORE_NAME = "name";
+/**
+ * The last column for a write the adapter does not place on an object:
+ * one through a parameter or a property read, or one of several writes
+ * that never settle. The rules that put a store on an object match the
+ * other two kinds, so these rows only say where a value went.
+ */
+declare const UNPLACED_STORE_NAME = "unplaced";
 /** A step to what running the call x is handed back. */
 declare const RESULT_STEP: _suss_datalog.Term;
 /** The context a value read outside every allocation site is read under. */
@@ -704,28 +1183,11 @@ declare const NO_CONTEXT: _suss_datalog.Term;
  */
 declare function alsoSteps(rules: readonly Rule[]): Rule[];
 declare const RESOLUTION_RULES: Rule[];
-/**
- * The questions a caller asks, written as rules. Two facts say somebody
- * is asking: `wanted(x)` for what a value is, and `wantedOrigin(x)` for
- * where a name came from. Each answer relation contains the pairs for the
- * values somebody asked about, keyed by the value asked about, which is
- * the key the caller looks up by anyway.
- *
- * Written down rather than left to each caller because the engine reads
- * them. `deriveOnDemand` follows a chain only as far as one of these
- * questions reaches it, and a caller that answered its own questions by
- * scanning a relation would give the engine nothing to work from.
- *
- * The two asking facts are kept apart because they pull on different
- * rules. Following a name back to its library goes through every call
- * the value's function makes, so a caller that only wants to know what a
- * handler resolves to should not pay for that.
- */
 declare const RESOLUTION_QUESTIONS: Rule[];
 /** The relations `RESOLUTION_QUESTIONS` answers into. */
 declare const ANSWER_RELATIONS: string[];
 /**
- * The three of those a caller asks under one allocation site.
+ * The ones of those a caller asks under one allocation site.
  *
  * They are listed apart because leaving them out of what a program has
  * to answer drops the whole second closure from it. A run that never
@@ -734,4 +1196,4 @@ declare const ANSWER_RELATIONS: string[];
  */
 declare const UNDER_ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, ASKING_RELATIONS, type AssociationConstructor, BASE_CLASS_RULE, type CalleeOutcome, type CaseFiles, type ChainReads, type ContractCase, type ContractOptions, type DescribeAtom, type EntersAsSelf, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type GivesBackOne, type GivesBackOneOfArgument, type GivesBackOneOfImport, INSTANCE_STEP, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, NAMESPACE_MEMBER_RULE, NO_CONTEXT, NO_CONTEXT_NAME, type NameReads, type NameWrite, type OrderedWrite, type PackWords, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, type SpannedNode, type StepContext, type StepPhrase, UNDER_ANSWER_RELATIONS, UNDER_QUESTION_ROW_BUDGET, UNDER_RUN_ROW_BUDGET, type UnderOutcome, type UnwrapsByName, VALUE_STEP, type ValueLocation, type WhyExplained, addPackWords, agreedMountPrefix, allocationSitesOf, alsoSteps, answersByKey, askResolution, askResolutionUnder, calleeOutcomeOf, calleeOutcomes, checkFactContract, comesToUnder, couldBeSettled, explainResolutionProof, explainResolvedKey, isWrittenAsUnder, joinMountedPath, mountPathsOf, nodeOfKey, objectOfUnder, placeholderValues, queryFacts, renderExplanation, resolutionProgram, resolutionUnderProgram, singleAnswers, startsAtName, underQuestionSpend, valueLeftByWrites, writesRunInOrder, writtenSourcesOf, writtenValueOf, writtenValueUnder, writtenValuesByKey, writtenValuesOf };
+export { ANSWER_RELATIONS, ASKING_RELATIONS, type AskUnder, type AssociationConstructor, BASE_CLASS_RULE, type CalleeOutcome, type CaseFiles, type ChainReads, type Changes, type ContractCase, type ContractOptions, DEFAULT_IMPORT_NAME, type Dependencies, DependencyLedger, type DescribeAtom, type EntersAsSelf, EntryReuse, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, FactLog, type FactsOf, GLOBAL_MODULE, type GivesBackOne, type GivesBackOneOfArgument, type GivesBackOneOfImport, INSTANCE_STEP, type MountEdge, type MountEdges, NAMED_STORE_NAME, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, NAMESPACE_MEMBER_RULE, NAME_HOP_RULE, NO_CONTEXT, NO_CONTEXT_NAME, type NameReads, type NameWrite, type OrderedWrite, type PackWords, RECEIVER_STORE_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, type SourceEnd, type SourceLeaf, type SourceQuestion, type SpannedNode, type StepContext, type StepPhrase, type StoredDependencies, type StoredFacts, type StoredFileRecord, type StoredWalkRecord, type SuppliesParameter, UNDER_ANSWER_RELATIONS, UNDER_QUESTION_ROW_BUDGET, UNDER_RUN_ROW_BUDGET, UNPLACED_STORE_NAME, USES_QUESTION, type UnderOutcome, type UnwrapsByName, VALUE_STEP, type ValueLocation, type ValueUses, WatchedMap, type WhyExplained, addPackWords, agreedMountPrefix, allocationSitesOf, alsoSteps, answersFor, askResolution, askResolutionUnder, askSources, calleeOutcomeOf, calleeOutcomes, checkFactContract, classMemberName, classMemberOf, comesToUnder, couldBeSettled, declaredTypesOf, exitCodeFunctions, explainResolutionProof, explainResolvedKey, fallbackWrittenAs, fileOfKey, hashString, importedFilesByFile, isObserved, isWrittenAsUnder, joinMountedPath, mergeStoredDependencies, mountPathsOf, noDependencies, nodeOfKey, noteKeyRead, noteLookup, objectOfUnder, observeDemand, packHashes, proofRules, queryFacts, readUses, recordsToReplay, renderExplanation, resolutionProgram, resolutionUnderProgram, resolvedFunctions, settledFunction, sourceLeavesOf, startsAtName, staysInItsFunction, stillValid, underQuestionSpend, unpackHashes, valueLeftByWrites, walkRecordsByFile, writesRunInOrder, writtenAnswersFor, writtenSourcesOf, writtenValueOf, writtenValueUnder, writtenValuesByKey, writtenValuesOf };