@suss/resolution 0.30.0 → 0.31.1

package/dist/index.d.cts

@@ -312,6 +312,62 @@ interface SpannedNode<N> {
  */
 declare function nodeOfKey<N extends SpannedNode<N>>(rootsByFile: ReadonlyMap<string, N>, key: string): N | null;
 
+/**
+ * packWords.ts: the facts a pack states about its own library.
+ *
+ * Nothing in a source file says that `Account.find(id)` gives back one
+ * Account, or that entering `httpx.Client()` gives back the client it
+ * built. The library knows, the pack writes it down, and an adapter puts
+ * it in the store. Every adapter did that with a loop of its own, so
+ * 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`.
+ */
+
+/** A method on a class reaching `base` gives back one of that class. */
+interface GivesBackOne {
+    base: string;
+    method: string;
+}
+/** The same, for a library that takes the class at position `argument` instead of as the receiver. */
+interface GivesBackOneOfArgument extends GivesBackOne {
+    argument: number;
+}
+/** The same again, for the bare function `module` exports under `name`. */
+interface GivesBackOneOfImport {
+    module: string;
+    name: string;
+    argument: number;
+}
+/** Entering one of `module`'s `name` gives back that same object. */
+interface EntersAsSelf {
+    module: string;
+    name: string;
+}
+/** Calling `callee` out of `module` gives back its argument at `argument`. */
+interface UnwrapsByName {
+    callee: string;
+    argument: number;
+    module: string;
+}
+/** A field given a call of `module`'s `name` declares an association. */
+interface AssociationConstructor {
+    module: string;
+    name: string;
+}
+/** What a run's packs say about their own libraries, in one language-neutral shape. */
+interface PackWords {
+    givesBackOne?: ReadonlyArray<GivesBackOne>;
+    givesBackOneOfArgument?: ReadonlyArray<GivesBackOneOfArgument>;
+    givesBackOneOfImport?: ReadonlyArray<GivesBackOneOfImport>;
+    entersAsSelf?: ReadonlyArray<EntersAsSelf>;
+    unwrapsByName?: ReadonlyArray<UnwrapsByName>;
+    associationConstructor?: ReadonlyArray<AssociationConstructor>;
+}
+/** Put a run's pack declarations in the store, so the shared rules can read them. */
+declare function addPackWords(db: Database, words: PackWords): void;
+
 /**
  * The rules an adapter evaluates, and how a question is put to them.
  *
@@ -334,11 +390,24 @@ declare const ASKING_RELATIONS: readonly string[];
  * reaches it. Built once per language and kept, because the rewrite
  * does not depend on the facts.
  *
+ * The questions asked under an allocation site are left out, which
+ * drops every rule behind them, so a caller that never mentions a
+ * context pays nothing for the second closure.
+ *
  * `SUSS_RESOLUTION_ON_DEMAND=0` runs the same rules unrestricted. Both
  * settings give the same answers; they differ in how much never gets
  * derived at all.
  */
 declare function resolutionProgram(languageRules?: readonly Rule[]): OnDemandRules;
+/**
+ * The same rules with the three questions under an allocation site
+ * added, which is what `askResolutionUnder` evaluates.
+ *
+ * Running both programs over one database costs the context-free one
+ * its resume state, so a caller with many context-free questions and a
+ * few under a site is better off asking the context-free ones first.
+ */
+declare function resolutionUnderProgram(languageRules?: readonly Rule[]): OnDemandRules;
 /**
  * What a caller takes back once it has read an answer: the question and
  * every relation derived under it. Empty when nothing is demand-driven,
@@ -357,6 +426,59 @@ declare function queryFacts(program: OnDemandRules): readonly string[];
  * question, which is how each adapter reads a project.
  */
 declare function askResolution(db: Database, keys: Iterable<string>, asking?: string, program?: OnDemandRules): void;
+/**
+ * How many rows the joins may read for one question under a site.
+ *
+ * The biggest question a project could answer read 200k rows on the
+ * largest public corpus target and 600k on the regression fixtures. A
+ * question that cannot be answered walks every node under every context
+ * and reads that much per rule, round after round, without settling.
+ * The gap is wide enough for thirty times the biggest healthy question,
+ * which is a few seconds before the walk is given up on.
+ */
+declare const UNDER_QUESTION_ROW_BUDGET = 20000000;
+/**
+ * How many rows the joins may read for every under-question a run asks,
+ * together.
+ *
+ * The per-question budget stops one question walking forever. It says
+ * nothing about how many questions a project asks, and a value read
+ * under every site of a class built in seventy places is seventy
+ * questions, each a fixpoint of its own. Twenty of those at the
+ * per-question limit is seven minutes, which is a hang however well
+ * each behaved on its own.
+ *
+ * This is two runaway questions' worth, or sixty-six of the biggest
+ * one measured. Past it a run keeps the context-free answer.
+ */
+declare const UNDER_RUN_ROW_BUDGET = 40000000;
+/** Whether a question was worked through, or given up on a budget. */
+type UnderOutcome = "answered" | "abandoned";
+/** What the under-questions of one run have cost it so far. */
+interface UnderSpend {
+    rows: number;
+    asked: number;
+    abandoned: number;
+    skipped: number;
+}
+/**
+ * What the under-questions of this database have cost, for a caller
+ * reporting on a run.
+ */
+declare function underQuestionSpend(db: Database): Readonly<UnderSpend>;
+/**
+ * `askResolution` for a value read under one allocation site. Each pair
+ * is a question of its own, so asking about a value under two sites is
+ * two rows, and asking the same pair twice costs nothing.
+ *
+ * A question that runs past `questionBudget`, or one asked after the
+ * run has spent `runBudget` on questions before it, is abandoned: the
+ * rows it added come back out, the answer relations stay as empty as
+ * they were, and the caller is told so it can keep the context-free
+ * answer instead. The pair stays marked as asked either way, so nobody
+ * pays for it twice.
+ */
+declare function askResolutionUnder(db: Database, pairs: Iterable<readonly [string, string]>, program?: OnDemandRules, questionBudget?: number, runBudget?: number): UnderOutcome;
 
 /**
  * The result shape a why session hands back, shared by every language
@@ -418,22 +540,58 @@ interface ExplainResolvedKeyOptions {
 declare function explainResolvedKey(options: ExplainResolvedKeyOptions): WhyExplained | null;
 
 /**
- * The single-answer policy shared by every 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.
+ * 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.
  *
  * 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 caller that can only use one answer takes `singleAnswers`; one with
+ * something to say about a value written two ways takes `answersByKey`.
  */
 
-/** The one answer each key settles on, once a key's match against itself is dropped. */
+/** 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>;
 
+/**
+ * Reading an answer that was asked for under one allocation site.
+ *
+ * The context-free readers take a key and get everything the rules
+ * settled it on. These take a key and a site, and get what the value is
+ * when the receiver behind it is the one that site made, so two clients
+ * of one class answer apart here and together context-free.
+ *
+ * Nothing is derived until `askResolutionUnder` has put the pair as a
+ * question, the same way the context-free readers need `askResolution`.
+ */
+
+/** Every expression the value was written as under this site. */
+declare function isWrittenAsUnder(db: Database, key: string, site: string): string[];
+/** Every function or object the value comes down to under this site. */
+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[];
+/**
+ * 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.
+ */
+declare function writtenValueUnder(db: Database, key: string, site: string): 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
+ * under.
+ */
+declare function allocationSitesOf(db: Database, cls: string): string[];
+
 /**
  * What a name written more than once comes down to.
  *
@@ -483,13 +641,29 @@ interface NameWrite {
  */
 declare function valueLeftByWrites(writes: readonly NameWrite[], ordered: boolean): string | null;
 
+type Ask = (keys: readonly string[]) => void;
 /**
  * The single expression a value was written as, once the caller has
  * asked the rules about `key`. A call to a project function is asked
  * about as well, through `ask`, so the answer is what that function
  * returns rather than the call itself.
  */
-declare function writtenValueOf(db: Database, key: string, ask: (keys: readonly string[]) => void): string | null;
+declare function writtenValueOf(db: Database, key: string, ask: Ask, relation?: string): 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
+ * the site rather than reading as the same nothing as a chain that went
+ * nowhere.
+ */
+declare function writtenValuesOf(db: Database, key: string, ask: Ask, relation?: string): string[];
+/**
+ * The one expression each key was written as, for a caller with several
+ * keys at once. Keys the rules settled on nothing, or on more than one
+ * expression, are left out. One round of asking covers them all, which
+ * is what a caller gets here that a loop over `writtenValueOf` would
+ * not.
+ */
+declare function writtenValuesByKey(db: Database, keys: readonly string[], ask: Ask, relation?: string): Map<string, string>;
 
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
@@ -501,23 +675,35 @@ declare const VALUE_STEP: _suss_datalog.Term;
  */
 declare const NAMESPACE_IMPORT_NAME = "*";
 declare const NAMESPACE_IMPORT: _suss_datalog.Term;
+/**
+ * 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.
+ */
+declare const NAMESPACE_MEMBER_RULE = "namespace member";
+/**
+ * The label on the `contains` rule that walks a class's ancestry.
+ * `explain` says a name came from a base class when it fired.
+ */
+declare const BASE_CLASS_RULE = "base class";
+/** A step from an instance to the class it is one of. */
+declare const INSTANCE_STEP: _suss_datalog.Term;
 /** 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. */
+declare const NO_CONTEXT_NAME = "none";
+declare const NO_CONTEXT: _suss_datalog.Term;
 /**
- * The rules every language adapter shares. Concatenate a language's own
- * rules onto these before evaluating.
- *
- * Every construct states its hops once, as `stepsTo(x, y, kind)`, which
- * says x leads to y. A value step goes to the value x is written as, and a
- * result step runs the call x is and goes to what that call handed back.
- * `reaches` is the closure of those steps, and a walk counts as a result
- * walk once it has run a call anywhere along it.
+ * Rules with a `stepsTo` twin for each hop among them.
  *
- * Each question is that one closure with its own stopping condition, so
- * adding a construct is one step and every question gets it, and adding
- * a question is a stopping condition and no steps at all.
+ * `reaches` reads `stepsTo` and `reachesUnder` reads `hop`. A rule
+ * passing one through to the other would look tidier and costs far
+ * more: the demand for `stepsTo` is one of the largest relations a run
+ * derives, and every row of it would be copied into a demand for `hop`
+ * whether or not anybody asked about a context. A language that states
+ * a hop of its own passes it through here for the same reason.
  */
-declare const RESOLUTION_RULES: _suss_datalog.Rule[];
+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
@@ -535,8 +721,17 @@ declare const RESOLUTION_RULES: _suss_datalog.Rule[];
  * 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: _suss_datalog.Rule[];
+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.
+ *
+ * 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
+ * mentions a context would otherwise carry a thousand rewritten rules
+ * it can never fire, and the engine reads every rule once a round.
+ */
+declare const UNDER_ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, ASKING_RELATIONS, type CalleeOutcome, type CaseFiles, type ChainReads, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, type NameReads, type NameWrite, type OrderedWrite, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, type SpannedNode, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, askResolution, calleeOutcomeOf, calleeOutcomes, checkFactContract, couldBeSettled, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, nodeOfKey, placeholderValues, queryFacts, renderExplanation, resolutionProgram, singleAnswers, startsAtName, valueLeftByWrites, writesRunInOrder, writtenSourcesOf, writtenValueOf };
+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 };

package/dist/index.d.ts

@@ -312,6 +312,62 @@ interface SpannedNode<N> {
  */
 declare function nodeOfKey<N extends SpannedNode<N>>(rootsByFile: ReadonlyMap<string, N>, key: string): N | null;
 
+/**
+ * packWords.ts: the facts a pack states about its own library.
+ *
+ * Nothing in a source file says that `Account.find(id)` gives back one
+ * Account, or that entering `httpx.Client()` gives back the client it
+ * built. The library knows, the pack writes it down, and an adapter puts
+ * it in the store. Every adapter did that with a loop of its own, so
+ * 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`.
+ */
+
+/** A method on a class reaching `base` gives back one of that class. */
+interface GivesBackOne {
+    base: string;
+    method: string;
+}
+/** The same, for a library that takes the class at position `argument` instead of as the receiver. */
+interface GivesBackOneOfArgument extends GivesBackOne {
+    argument: number;
+}
+/** The same again, for the bare function `module` exports under `name`. */
+interface GivesBackOneOfImport {
+    module: string;
+    name: string;
+    argument: number;
+}
+/** Entering one of `module`'s `name` gives back that same object. */
+interface EntersAsSelf {
+    module: string;
+    name: string;
+}
+/** Calling `callee` out of `module` gives back its argument at `argument`. */
+interface UnwrapsByName {
+    callee: string;
+    argument: number;
+    module: string;
+}
+/** A field given a call of `module`'s `name` declares an association. */
+interface AssociationConstructor {
+    module: string;
+    name: string;
+}
+/** What a run's packs say about their own libraries, in one language-neutral shape. */
+interface PackWords {
+    givesBackOne?: ReadonlyArray<GivesBackOne>;
+    givesBackOneOfArgument?: ReadonlyArray<GivesBackOneOfArgument>;
+    givesBackOneOfImport?: ReadonlyArray<GivesBackOneOfImport>;
+    entersAsSelf?: ReadonlyArray<EntersAsSelf>;
+    unwrapsByName?: ReadonlyArray<UnwrapsByName>;
+    associationConstructor?: ReadonlyArray<AssociationConstructor>;
+}
+/** Put a run's pack declarations in the store, so the shared rules can read them. */
+declare function addPackWords(db: Database, words: PackWords): void;
+
 /**
  * The rules an adapter evaluates, and how a question is put to them.
  *
@@ -334,11 +390,24 @@ declare const ASKING_RELATIONS: readonly string[];
  * reaches it. Built once per language and kept, because the rewrite
  * does not depend on the facts.
  *
+ * The questions asked under an allocation site are left out, which
+ * drops every rule behind them, so a caller that never mentions a
+ * context pays nothing for the second closure.
+ *
  * `SUSS_RESOLUTION_ON_DEMAND=0` runs the same rules unrestricted. Both
  * settings give the same answers; they differ in how much never gets
  * derived at all.
  */
 declare function resolutionProgram(languageRules?: readonly Rule[]): OnDemandRules;
+/**
+ * The same rules with the three questions under an allocation site
+ * added, which is what `askResolutionUnder` evaluates.
+ *
+ * Running both programs over one database costs the context-free one
+ * its resume state, so a caller with many context-free questions and a
+ * few under a site is better off asking the context-free ones first.
+ */
+declare function resolutionUnderProgram(languageRules?: readonly Rule[]): OnDemandRules;
 /**
  * What a caller takes back once it has read an answer: the question and
  * every relation derived under it. Empty when nothing is demand-driven,
@@ -357,6 +426,59 @@ declare function queryFacts(program: OnDemandRules): readonly string[];
  * question, which is how each adapter reads a project.
  */
 declare function askResolution(db: Database, keys: Iterable<string>, asking?: string, program?: OnDemandRules): void;
+/**
+ * How many rows the joins may read for one question under a site.
+ *
+ * The biggest question a project could answer read 200k rows on the
+ * largest public corpus target and 600k on the regression fixtures. A
+ * question that cannot be answered walks every node under every context
+ * and reads that much per rule, round after round, without settling.
+ * The gap is wide enough for thirty times the biggest healthy question,
+ * which is a few seconds before the walk is given up on.
+ */
+declare const UNDER_QUESTION_ROW_BUDGET = 20000000;
+/**
+ * How many rows the joins may read for every under-question a run asks,
+ * together.
+ *
+ * The per-question budget stops one question walking forever. It says
+ * nothing about how many questions a project asks, and a value read
+ * under every site of a class built in seventy places is seventy
+ * questions, each a fixpoint of its own. Twenty of those at the
+ * per-question limit is seven minutes, which is a hang however well
+ * each behaved on its own.
+ *
+ * This is two runaway questions' worth, or sixty-six of the biggest
+ * one measured. Past it a run keeps the context-free answer.
+ */
+declare const UNDER_RUN_ROW_BUDGET = 40000000;
+/** Whether a question was worked through, or given up on a budget. */
+type UnderOutcome = "answered" | "abandoned";
+/** What the under-questions of one run have cost it so far. */
+interface UnderSpend {
+    rows: number;
+    asked: number;
+    abandoned: number;
+    skipped: number;
+}
+/**
+ * What the under-questions of this database have cost, for a caller
+ * reporting on a run.
+ */
+declare function underQuestionSpend(db: Database): Readonly<UnderSpend>;
+/**
+ * `askResolution` for a value read under one allocation site. Each pair
+ * is a question of its own, so asking about a value under two sites is
+ * two rows, and asking the same pair twice costs nothing.
+ *
+ * A question that runs past `questionBudget`, or one asked after the
+ * run has spent `runBudget` on questions before it, is abandoned: the
+ * rows it added come back out, the answer relations stay as empty as
+ * they were, and the caller is told so it can keep the context-free
+ * answer instead. The pair stays marked as asked either way, so nobody
+ * pays for it twice.
+ */
+declare function askResolutionUnder(db: Database, pairs: Iterable<readonly [string, string]>, program?: OnDemandRules, questionBudget?: number, runBudget?: number): UnderOutcome;
 
 /**
  * The result shape a why session hands back, shared by every language
@@ -418,22 +540,58 @@ interface ExplainResolvedKeyOptions {
 declare function explainResolvedKey(options: ExplainResolvedKeyOptions): WhyExplained | null;
 
 /**
- * The single-answer policy shared by every 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.
+ * 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.
  *
  * 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 caller that can only use one answer takes `singleAnswers`; one with
+ * something to say about a value written two ways takes `answersByKey`.
  */
 
-/** The one answer each key settles on, once a key's match against itself is dropped. */
+/** 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>;
 
+/**
+ * Reading an answer that was asked for under one allocation site.
+ *
+ * The context-free readers take a key and get everything the rules
+ * settled it on. These take a key and a site, and get what the value is
+ * when the receiver behind it is the one that site made, so two clients
+ * of one class answer apart here and together context-free.
+ *
+ * Nothing is derived until `askResolutionUnder` has put the pair as a
+ * question, the same way the context-free readers need `askResolution`.
+ */
+
+/** Every expression the value was written as under this site. */
+declare function isWrittenAsUnder(db: Database, key: string, site: string): string[];
+/** Every function or object the value comes down to under this site. */
+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[];
+/**
+ * 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.
+ */
+declare function writtenValueUnder(db: Database, key: string, site: string): 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
+ * under.
+ */
+declare function allocationSitesOf(db: Database, cls: string): string[];
+
 /**
  * What a name written more than once comes down to.
  *
@@ -483,13 +641,29 @@ interface NameWrite {
  */
 declare function valueLeftByWrites(writes: readonly NameWrite[], ordered: boolean): string | null;
 
+type Ask = (keys: readonly string[]) => void;
 /**
  * The single expression a value was written as, once the caller has
  * asked the rules about `key`. A call to a project function is asked
  * about as well, through `ask`, so the answer is what that function
  * returns rather than the call itself.
  */
-declare function writtenValueOf(db: Database, key: string, ask: (keys: readonly string[]) => void): string | null;
+declare function writtenValueOf(db: Database, key: string, ask: Ask, relation?: string): 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
+ * the site rather than reading as the same nothing as a chain that went
+ * nowhere.
+ */
+declare function writtenValuesOf(db: Database, key: string, ask: Ask, relation?: string): string[];
+/**
+ * The one expression each key was written as, for a caller with several
+ * keys at once. Keys the rules settled on nothing, or on more than one
+ * expression, are left out. One round of asking covers them all, which
+ * is what a caller gets here that a loop over `writtenValueOf` would
+ * not.
+ */
+declare function writtenValuesByKey(db: Database, keys: readonly string[], ask: Ask, relation?: string): Map<string, string>;
 
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
@@ -501,23 +675,35 @@ declare const VALUE_STEP: _suss_datalog.Term;
  */
 declare const NAMESPACE_IMPORT_NAME = "*";
 declare const NAMESPACE_IMPORT: _suss_datalog.Term;
+/**
+ * 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.
+ */
+declare const NAMESPACE_MEMBER_RULE = "namespace member";
+/**
+ * The label on the `contains` rule that walks a class's ancestry.
+ * `explain` says a name came from a base class when it fired.
+ */
+declare const BASE_CLASS_RULE = "base class";
+/** A step from an instance to the class it is one of. */
+declare const INSTANCE_STEP: _suss_datalog.Term;
 /** 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. */
+declare const NO_CONTEXT_NAME = "none";
+declare const NO_CONTEXT: _suss_datalog.Term;
 /**
- * The rules every language adapter shares. Concatenate a language's own
- * rules onto these before evaluating.
- *
- * Every construct states its hops once, as `stepsTo(x, y, kind)`, which
- * says x leads to y. A value step goes to the value x is written as, and a
- * result step runs the call x is and goes to what that call handed back.
- * `reaches` is the closure of those steps, and a walk counts as a result
- * walk once it has run a call anywhere along it.
+ * Rules with a `stepsTo` twin for each hop among them.
  *
- * Each question is that one closure with its own stopping condition, so
- * adding a construct is one step and every question gets it, and adding
- * a question is a stopping condition and no steps at all.
+ * `reaches` reads `stepsTo` and `reachesUnder` reads `hop`. A rule
+ * passing one through to the other would look tidier and costs far
+ * more: the demand for `stepsTo` is one of the largest relations a run
+ * derives, and every row of it would be copied into a demand for `hop`
+ * whether or not anybody asked about a context. A language that states
+ * a hop of its own passes it through here for the same reason.
  */
-declare const RESOLUTION_RULES: _suss_datalog.Rule[];
+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
@@ -535,8 +721,17 @@ declare const RESOLUTION_RULES: _suss_datalog.Rule[];
  * 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: _suss_datalog.Rule[];
+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.
+ *
+ * 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
+ * mentions a context would otherwise carry a thousand rewritten rules
+ * it can never fire, and the engine reads every rule once a round.
+ */
+declare const UNDER_ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, ASKING_RELATIONS, type CalleeOutcome, type CaseFiles, type ChainReads, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, type NameReads, type NameWrite, type OrderedWrite, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, type SpannedNode, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, askResolution, calleeOutcomeOf, calleeOutcomes, checkFactContract, couldBeSettled, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, nodeOfKey, placeholderValues, queryFacts, renderExplanation, resolutionProgram, singleAnswers, startsAtName, valueLeftByWrites, writesRunInOrder, writtenSourcesOf, writtenValueOf };
+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 };