@suss/resolution 0.1.0 → 0.1.1

package/README.md

@@ -19,7 +19,14 @@ factory in TypeScript.
 
 ```
 func(f)                     f is a function
+objectValue(o)              o is an object written out literally
+writtenValue(x)             x is an expression written out in source
+                            rather than a name for one
+holdsProperty(o, n, x)      object o holds x under the name n
+readsProperty(x, o, n)      x is the expression o.n
 binds(x, y)                 the name x is declared as y
+endsHolding(x, y)           the name x is written more than once and
+                            holds y once the writes have run
 paramOf(f, k, p)            p is f's parameter at position k
 returnsValue(f, v)          f returns v
 bodyCalls(f, c)             f's body calls c
@@ -40,6 +47,52 @@ match.
 
 Node identity is the adapter's business. The rules only join on it.
 
+## What comes out
+
+```
+comesTo(x, z)               following x arrives at the value z
+resolves(x, z)              comesTo narrowed to functions
+isWrittenAs(x, z)           x is written as the expression z
+comesFrom(x, m, n)          following x arrives at m's export n
+callsInto(f, m, n)          calling f ends up calling m's n
+```
+
+`resolves` is the question most callers ask. `comesTo` is the one
+underneath it, and it can answer with an object, since a chain has to
+pass through objects for `routes.list` to reach what `list` holds.
+
+`isWrittenAs` follows the same names to the expression a value is
+written as, whatever kind of expression that turns out to be. A GraphQL
+document is neither a function nor an object, so `comesTo` never
+reaches one.
+
+`comesFrom` answers the direction `comesTo` cannot. Every `comesTo`
+chain ends at something written out in the source being read, so a name
+for a library's own function ends nowhere: the library's body is not
+here. `comesFrom` follows the same aliases, imports and barrels and
+answers with the module and the name that module exports.
+
+`callsInto` puts that together with the calls a function makes. A
+project writes its own decorator that calls `Resolver()` and applies
+that one to its classes, and the class is a resolver even though nothing
+about it says `Resolver`. Several answers for one function is the normal
+case rather than an ambiguity, since a wrapper composing two library
+decorators applies both, so a caller asks whether the one it cares about
+is among them.
+
+One relation comes out for the rules' own use rather than for callers:
+
+```
+objectOf(x, obj)            x stands for the object literal obj
+```
+
+An object arrives two ways, through a name or as what a factory call
+returns, and `objectOf` names that step so the rule for `routes.list`
+and the rule for `make(body).handle` are the same rule. A factory call
+gets an `objectOf` answer without getting a `comesTo` answer, since a
+factory call usually is the wrapper and answering with the function it
+returns would fight the unwrapping answer.
+
 ## Why rules and not a walker
 
 Each rule describes one hop. The chains people write are longer than
@@ -49,19 +102,20 @@ barrel re-exporting a wrapper. The engine composes what it has, so those
 work without being named.
 
 The corollary is where to look when something comes back empty. Suspect
-the facts before the rules. A production service once declared 91
-handlers and resolved 11; the fix was one condition in fact extraction,
-and the rules found the other 79 unchanged.
+the facts before the rules. Against one production service suss
+resolved 11 handlers and missed most of what the template declared. The
+fix was one condition in fact extraction, and the existing rules found
+the rest unchanged.
 
 ## What is not modelled
 
 **A handler passed as one property of a config.** `make({ body:
 handler })`, where the factory reads `opts.body`, does not resolve. A
-rule for it was tried and taken out: production wrappers read several
-callbacks off the same config (a log extractor, an error builder, the
-handler), the rule made each one a candidate for the whole call, and
-ambiguity nulled out sixty handlers that used to resolve. Saying which
-property is the handler takes something structure does not carry,
+rule for it was tried and taken out: a wrapper often reads several
+callbacks off the same config object, the rule made each one a
+candidate for the whole call, and the resulting ambiguity nulled out
+handlers that used to resolve. Saying which property is the handler
+takes something structure does not carry,
 either "the only property called" (which needs negation) or a pack
 naming the property. Until one of those exists, this shape stays
 unresolved on purpose.
@@ -69,8 +123,27 @@ unresolved on purpose.
 **An element of an array.** `all[0]` has no fact for what an array
 holds.
 
-**Reassignment.** A name assigned twice resolves to the first
-assignment rather than to both or to neither.
+**Which write a read sees, once control flow decides it.** A name
+written twice in a module's own statement list is answered: those
+statements run once each, top to bottom, so the last write is what
+anything importing the name gets, and the adapter says so with
+`endsHolding`. A write inside a branch, a loop, or a function body is a
+different claim, and the adapter stays quiet. The name then comes to
+nothing, which is the answer until there are control-flow facts to
+reason over.
+
+Answering it in general is reaching definitions, per use rather than
+per name. That needs facts saying which statement follows which and
+which branch each sits on, and no adapter emits any today.
+
+The adapter picking the write rather than a rule picking it is a cost
+decision. Ordering writes inside the rules means asking which writes
+have no later write, negation says that in one line, and this
+evaluator has to throw its last fixpoint away and start over whenever a
+rule set uses negation. The store evaluates after every wave of facts,
+so one negated rule turned a 66 second run on the Saleor dashboard into
+one that had not finished in ten minutes. Source order is something
+every adapter already knows.
 
 **Ambiguity is the caller's problem.** When the rules reach two
 different functions the store returns nothing, since picking one would

package/dist/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ANSWER_RELATIONS: () => ANSWER_RELATIONS,
+  RESOLUTION_QUESTIONS: () => RESOLUTION_QUESTIONS,
   RESOLUTION_RULES: () => RESOLUTION_RULES
 });
 module.exports = __toCommonJS(index_exports);
@@ -35,6 +37,16 @@ var RESOLUTION_RULES = [
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
     [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
   ),
+  // A name written more than once holds the value the last write left
+  // there, and `binds` says nothing about it. The adapter works out
+  // which write that is, in its own language's terms, and stays quiet
+  // when control flow decides. A name it stays quiet about comes to no
+  // value, which is the answer.
+  (0, import_datalog.rule)(
+    "comesTo",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("endsHolding", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
+  ),
   // An import comes to what the module exports under that name.
   (0, import_datalog.rule)(
     "comesTo",
@@ -67,15 +79,37 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m2"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("value"))
     ]
   ),
-  // Reading a property comes to what the object holds under that name.
-  // `comesTo` in the middle is what lets the object arrive through an
-  // alias, an import, or a factory call.
+  // The object an expression stands for. A name arrives at one by
+  // following `comesTo` through aliases and imports. A factory call
+  // arrives at one through what the function it calls returns; the
+  // call itself is given no `comesTo`, since a factory call usually IS
+  // the wrapper and answering with the raw returned function would
+  // fight the unwraps answer.
+  (0, import_datalog.rule)(
+    "objectOf",
+    [(0, import_datalog.variable)("o"), (0, import_datalog.variable)("obj")],
+    [(0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("o"), (0, import_datalog.variable)("obj")), (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("obj"))]
+  ),
+  (0, import_datalog.rule)(
+    "objectOf",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("obj")],
+    [
+      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")),
+      (0, import_datalog.lit)("returnsValue", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("ret")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("ret"), (0, import_datalog.variable)("obj")),
+      (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("obj"))
+    ]
+  ),
+  // Reading a property comes to what the object holds under that name,
+  // whichever way the object arrived: `routes.list` off a name, or
+  // `make(body).handle` off a call.
   (0, import_datalog.rule)(
     "comesTo",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
     [
       (0, import_datalog.lit)("readsProperty", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("o"), (0, import_datalog.variable)("n")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("o"), (0, import_datalog.variable)("obj")),
+      (0, import_datalog.lit)("objectOf", (0, import_datalog.variable)("o"), (0, import_datalog.variable)("obj")),
       (0, import_datalog.lit)("holdsProperty", (0, import_datalog.variable)("obj"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held")),
       (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("held"), (0, import_datalog.variable)("z"))
     ]
@@ -153,23 +187,6 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("h"))
     ]
   ),
-  // A property read off a call: `make(body).handle`. The call itself is
-  // not given a `comesTo`, since a factory call usually IS the wrapper
-  // and answering with the raw returned function would fight the
-  // unwraps answer. Only the property read narrows enough to be safe.
-  (0, import_datalog.rule)(
-    "comesTo",
-    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
-    [
-      (0, import_datalog.lit)("readsProperty", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("r"), (0, import_datalog.variable)("n")),
-      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")),
-      (0, import_datalog.lit)("returnsValue", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("ret")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("ret"), (0, import_datalog.variable)("obj")),
-      (0, import_datalog.lit)("holdsProperty", (0, import_datalog.variable)("obj"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("held"), (0, import_datalog.variable)("z"))
-    ]
-  ),
   // Wrapper transparency, declared: a pack says this callee wraps
   // argument k, whatever its implementation looks like. The callee has
   // to have been imported from the library the pack named, so a local
@@ -186,6 +203,57 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("h"))
     ]
   ),
+  // Where a name comes from, when what it names lives outside the
+  // source being read. `comesTo` ends at something written out, so it
+  // never reaches a library's own function, and a project's alias of a
+  // library name has no answer at all. This follows the same aliases
+  // and barrels in the other direction and answers with the module and
+  // the name that module exports.
+  (0, import_datalog.rule)(
+    "comesFrom",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
+    [(0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))]
+  ),
+  (0, import_datalog.rule)(
+    "comesFrom",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
+    [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("comesFrom", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))]
+  ),
+  (0, import_datalog.rule)(
+    "comesFrom",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
+    [
+      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m2"), (0, import_datalog.variable)("n2")),
+      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m2"), (0, import_datalog.variable)("n2"), (0, import_datalog.variable)("value")),
+      (0, import_datalog.lit)("comesFrom", (0, import_datalog.variable)("value"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))
+    ]
+  ),
+  // Calling f ends up calling the name n that module m exports. One hop
+  // is f's own body, including the closures it declares; the other hop
+  // is a function f's body calls, so a wrapper of a wrapper answers
+  // with what the innermost one reaches.
+  //
+  // Several answers for one function is the normal case, not an
+  // ambiguity: a project decorator that composes two library decorators
+  // applies both. A caller asks whether a particular (m, n) is among
+  // them.
+  (0, import_datalog.rule)(
+    "callsInto",
+    [(0, import_datalog.variable)("f"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
+    [
+      (0, import_datalog.lit)("bodyCallsDeep", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("c")),
+      (0, import_datalog.lit)("comesFrom", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))
+    ]
+  ),
+  (0, import_datalog.rule)(
+    "callsInto",
+    [(0, import_datalog.variable)("f"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
+    [
+      (0, import_datalog.lit)("bodyCallsDeep", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("c")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("g")),
+      (0, import_datalog.lit)("callsInto", (0, import_datalog.variable)("g"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))
+    ]
+  ),
   // The question callers ask: what a value comes to, narrowed to the
   // functions. Objects appear in the middle of chains and never in an
   // answer.
@@ -193,9 +261,80 @@ var RESOLUTION_RULES = [
     "resolves",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
     [(0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")), (0, import_datalog.lit)("func", (0, import_datalog.variable)("z"))]
+  ),
+  // Following a name to the expression it is written as. A separate
+  // relation rather than a widening of `comesTo`, so a caller asking
+  // the older question never sees a new answer: a factory call already
+  // has an unwrapping answer, and letting it also answer with itself
+  // would make that pair ambiguous.
+  //
+  // The two seeds are the two ways an expression can be written out. An
+  // object literal is one of them, and it is the shape a generated
+  // GraphQL document takes.
+  (0, import_datalog.rule)("isWrittenAs", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("writtenValue", (0, import_datalog.variable)("x"))]),
+  (0, import_datalog.rule)("isWrittenAs", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("x"))]),
+  (0, import_datalog.rule)(
+    "isWrittenAs",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("isWrittenAs", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "isWrittenAs",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("endsHolding", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("isWrittenAs", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "isWrittenAs",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [
+      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")),
+      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("value")),
+      (0, import_datalog.lit)("isWrittenAs", (0, import_datalog.variable)("value"), (0, import_datalog.variable)("z"))
+    ]
   )
 ];
+var RESOLUTION_QUESTIONS = [
+  (0, import_datalog.rule)(
+    "wantedResolves",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("wanted", (0, import_datalog.variable)("x")), (0, import_datalog.lit)("resolves", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "wantedComesTo",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("wanted", (0, import_datalog.variable)("x")), (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "wantedComesTo",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("wantedOrigin", (0, import_datalog.variable)("x")), (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "wantedIsWrittenAs",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("wanted", (0, import_datalog.variable)("x")), (0, import_datalog.lit)("isWrittenAs", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "wantedComesFrom",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
+    [(0, import_datalog.lit)("wantedOrigin", (0, import_datalog.variable)("x")), (0, import_datalog.lit)("comesFrom", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))]
+  ),
+  (0, import_datalog.rule)(
+    "wantedCallsInto",
+    [(0, import_datalog.variable)("g"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
+    [
+      (0, import_datalog.lit)("wantedOrigin", (0, import_datalog.variable)("x")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("g")),
+      (0, import_datalog.lit)("callsInto", (0, import_datalog.variable)("g"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))
+    ]
+  )
+];
+var ANSWER_RELATIONS = [
+  ...new Set(RESOLUTION_QUESTIONS.map((r) => r.head.relation))
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ANSWER_RELATIONS,
+  RESOLUTION_QUESTIONS,
   RESOLUTION_RULES
 });

package/dist/index.d.cts

@@ -5,5 +5,25 @@ import * as _suss_datalog from '@suss/datalog';
  * rules onto these before evaluating.
  */
 declare const RESOLUTION_RULES: _suss_datalog.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 holds 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: _suss_datalog.Rule[];
+/** The relations `RESOLUTION_QUESTIONS` answers into. */
+declare const ANSWER_RELATIONS: string[];
 
-export { RESOLUTION_RULES };
+export { ANSWER_RELATIONS, RESOLUTION_QUESTIONS, RESOLUTION_RULES };

package/dist/index.d.ts

@@ -5,5 +5,25 @@ import * as _suss_datalog from '@suss/datalog';
  * rules onto these before evaluating.
  */
 declare const RESOLUTION_RULES: _suss_datalog.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 holds 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: _suss_datalog.Rule[];
+/** The relations `RESOLUTION_QUESTIONS` answers into. */
+declare const ANSWER_RELATIONS: string[];
 
-export { RESOLUTION_RULES };
+export { ANSWER_RELATIONS, RESOLUTION_QUESTIONS, RESOLUTION_RULES };

package/dist/index.js

@@ -11,6 +11,16 @@ var RESOLUTION_RULES = [
     [v("x"), v("z")],
     [lit("binds", v("x"), v("y")), lit("comesTo", v("y"), v("z"))]
   ),
+  // A name written more than once holds the value the last write left
+  // there, and `binds` says nothing about it. The adapter works out
+  // which write that is, in its own language's terms, and stays quiet
+  // when control flow decides. A name it stays quiet about comes to no
+  // value, which is the answer.
+  rule(
+    "comesTo",
+    [v("x"), v("z")],
+    [lit("endsHolding", v("x"), v("y")), lit("comesTo", v("y"), v("z"))]
+  ),
   // An import comes to what the module exports under that name.
   rule(
     "comesTo",
@@ -43,15 +53,37 @@ var RESOLUTION_RULES = [
       lit("moduleExport", v("m2"), v("n"), v("value"))
     ]
   ),
-  // Reading a property comes to what the object holds under that name.
-  // `comesTo` in the middle is what lets the object arrive through an
-  // alias, an import, or a factory call.
+  // The object an expression stands for. A name arrives at one by
+  // following `comesTo` through aliases and imports. A factory call
+  // arrives at one through what the function it calls returns; the
+  // call itself is given no `comesTo`, since a factory call usually IS
+  // the wrapper and answering with the raw returned function would
+  // fight the unwraps answer.
+  rule(
+    "objectOf",
+    [v("o"), v("obj")],
+    [lit("comesTo", v("o"), v("obj")), lit("objectValue", v("obj"))]
+  ),
+  rule(
+    "objectOf",
+    [v("r"), v("obj")],
+    [
+      lit("call", v("r"), v("c")),
+      lit("comesTo", v("c"), v("f")),
+      lit("returnsValue", v("f"), v("ret")),
+      lit("comesTo", v("ret"), v("obj")),
+      lit("objectValue", v("obj"))
+    ]
+  ),
+  // Reading a property comes to what the object holds under that name,
+  // whichever way the object arrived: `routes.list` off a name, or
+  // `make(body).handle` off a call.
   rule(
     "comesTo",
     [v("x"), v("z")],
     [
       lit("readsProperty", v("x"), v("o"), v("n")),
-      lit("comesTo", v("o"), v("obj")),
+      lit("objectOf", v("o"), v("obj")),
       lit("holdsProperty", v("obj"), v("n"), v("held")),
       lit("comesTo", v("held"), v("z"))
     ]
@@ -129,23 +161,6 @@ var RESOLUTION_RULES = [
       lit("comesTo", v("a"), v("h"))
     ]
   ),
-  // A property read off a call: `make(body).handle`. The call itself is
-  // not given a `comesTo`, since a factory call usually IS the wrapper
-  // and answering with the raw returned function would fight the
-  // unwraps answer. Only the property read narrows enough to be safe.
-  rule(
-    "comesTo",
-    [v("x"), v("z")],
-    [
-      lit("readsProperty", v("x"), v("r"), v("n")),
-      lit("call", v("r"), v("c")),
-      lit("comesTo", v("c"), v("f")),
-      lit("returnsValue", v("f"), v("ret")),
-      lit("comesTo", v("ret"), v("obj")),
-      lit("holdsProperty", v("obj"), v("n"), v("held")),
-      lit("comesTo", v("held"), v("z"))
-    ]
-  ),
   // Wrapper transparency, declared: a pack says this callee wraps
   // argument k, whatever its implementation looks like. The callee has
   // to have been imported from the library the pack named, so a local
@@ -162,6 +177,57 @@ var RESOLUTION_RULES = [
       lit("comesTo", v("a"), v("h"))
     ]
   ),
+  // Where a name comes from, when what it names lives outside the
+  // source being read. `comesTo` ends at something written out, so it
+  // never reaches a library's own function, and a project's alias of a
+  // library name has no answer at all. This follows the same aliases
+  // and barrels in the other direction and answers with the module and
+  // the name that module exports.
+  rule(
+    "comesFrom",
+    [v("x"), v("m"), v("n")],
+    [lit("imports", v("x"), v("m"), v("n"))]
+  ),
+  rule(
+    "comesFrom",
+    [v("x"), v("m"), v("n")],
+    [lit("binds", v("x"), v("y")), lit("comesFrom", v("y"), v("m"), v("n"))]
+  ),
+  rule(
+    "comesFrom",
+    [v("x"), v("m"), v("n")],
+    [
+      lit("imports", v("x"), v("m2"), v("n2")),
+      lit("moduleExport", v("m2"), v("n2"), v("value")),
+      lit("comesFrom", v("value"), v("m"), v("n"))
+    ]
+  ),
+  // Calling f ends up calling the name n that module m exports. One hop
+  // is f's own body, including the closures it declares; the other hop
+  // is a function f's body calls, so a wrapper of a wrapper answers
+  // with what the innermost one reaches.
+  //
+  // Several answers for one function is the normal case, not an
+  // ambiguity: a project decorator that composes two library decorators
+  // applies both. A caller asks whether a particular (m, n) is among
+  // them.
+  rule(
+    "callsInto",
+    [v("f"), v("m"), v("n")],
+    [
+      lit("bodyCallsDeep", v("f"), v("c")),
+      lit("comesFrom", v("c"), v("m"), v("n"))
+    ]
+  ),
+  rule(
+    "callsInto",
+    [v("f"), v("m"), v("n")],
+    [
+      lit("bodyCallsDeep", v("f"), v("c")),
+      lit("comesTo", v("c"), v("g")),
+      lit("callsInto", v("g"), v("m"), v("n"))
+    ]
+  ),
   // The question callers ask: what a value comes to, narrowed to the
   // functions. Objects appear in the middle of chains and never in an
   // answer.
@@ -169,8 +235,79 @@ var RESOLUTION_RULES = [
     "resolves",
     [v("x"), v("z")],
     [lit("comesTo", v("x"), v("z")), lit("func", v("z"))]
+  ),
+  // Following a name to the expression it is written as. A separate
+  // relation rather than a widening of `comesTo`, so a caller asking
+  // the older question never sees a new answer: a factory call already
+  // has an unwrapping answer, and letting it also answer with itself
+  // would make that pair ambiguous.
+  //
+  // The two seeds are the two ways an expression can be written out. An
+  // object literal is one of them, and it is the shape a generated
+  // GraphQL document takes.
+  rule("isWrittenAs", [v("x"), v("x")], [lit("writtenValue", v("x"))]),
+  rule("isWrittenAs", [v("x"), v("x")], [lit("objectValue", v("x"))]),
+  rule(
+    "isWrittenAs",
+    [v("x"), v("z")],
+    [lit("binds", v("x"), v("y")), lit("isWrittenAs", v("y"), v("z"))]
+  ),
+  rule(
+    "isWrittenAs",
+    [v("x"), v("z")],
+    [lit("endsHolding", v("x"), v("y")), lit("isWrittenAs", v("y"), v("z"))]
+  ),
+  rule(
+    "isWrittenAs",
+    [v("x"), v("z")],
+    [
+      lit("imports", v("x"), v("m"), v("n")),
+      lit("moduleExport", v("m"), v("n"), v("value")),
+      lit("isWrittenAs", v("value"), v("z"))
+    ]
   )
 ];
+var RESOLUTION_QUESTIONS = [
+  rule(
+    "wantedResolves",
+    [v("x"), v("z")],
+    [lit("wanted", v("x")), lit("resolves", v("x"), v("z"))]
+  ),
+  rule(
+    "wantedComesTo",
+    [v("x"), v("z")],
+    [lit("wanted", v("x")), lit("comesTo", v("x"), v("z"))]
+  ),
+  rule(
+    "wantedComesTo",
+    [v("x"), v("z")],
+    [lit("wantedOrigin", v("x")), lit("comesTo", v("x"), v("z"))]
+  ),
+  rule(
+    "wantedIsWrittenAs",
+    [v("x"), v("z")],
+    [lit("wanted", v("x")), lit("isWrittenAs", v("x"), v("z"))]
+  ),
+  rule(
+    "wantedComesFrom",
+    [v("x"), v("m"), v("n")],
+    [lit("wantedOrigin", v("x")), lit("comesFrom", v("x"), v("m"), v("n"))]
+  ),
+  rule(
+    "wantedCallsInto",
+    [v("g"), v("m"), v("n")],
+    [
+      lit("wantedOrigin", v("x")),
+      lit("comesTo", v("x"), v("g")),
+      lit("callsInto", v("g"), v("m"), v("n"))
+    ]
+  )
+];
+var ANSWER_RELATIONS = [
+  ...new Set(RESOLUTION_QUESTIONS.map((r) => r.head.relation))
+];
 export {
+  ANSWER_RELATIONS,
+  RESOLUTION_QUESTIONS,
   RESOLUTION_RULES
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Language-neutral rules for following a value to the function it comes down to.",
   "keywords": [
@@ -53,6 +53,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@suss/datalog": "0.1.0"
+    "@suss/datalog": "0.1.1"
   }
 }