@suss/resolution 0.21.0 → 0.22.0

package/README.md

@@ -23,6 +23,8 @@ 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
+placeholderValue(x)         x is a written value a later write is
+                            expected to replace, such as None or nil
 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
@@ -97,6 +99,18 @@ 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.
 
+The closure is written with the walk so far first and the next hop after
+it: `reaches(x, z) <- reaches(x, y), stepsTo(y, z)`. The order matters
+under demand. Every question here asks about one value, and with the
+walk first, the demand stays on that value and each round extends the
+walks it already has by one hop. Written hop first, `reaches(x, z) <-
+stepsTo(x, y), reaches(y, z)`, a question about `x` becomes a question
+about every `y` a hop leads to, so the closure is derived from every
+value the walk passes through, and each new walk is joined back against
+every hop that lands on its start. Extracting the TypeScript adapter's
+own sources, the hop first order spent two seconds in the closure, and
+the walk first order spends forty milliseconds.
+
 ## What comes out
 
 ```
@@ -226,6 +240,30 @@ The construction end needs no fact of its own. Every call is already a
 `call` fact, a `new` expression included, and the join against
 `comesFrom` is what makes one of them a subject seed.
 
+A call is written as itself, the same base case that makes a class its
+own ancestor at the top of the chain. So when an adapter asks
+`wantedSubjectWritten` about a call directly, the answers include the
+call itself next to whatever the walk reaches. A call with one other
+answer would count as two and be refused as ambiguous. `singleAnswers`
+drops the row whose answer is its own key before counting, and every
+adapter reads the relation through it.
+
+A name written as a placeholder before a guard fills it in, `_client =
+None` at module level and `_client = make_client()` inside a getter, is
+two answers the same way. An adapter marks the placeholder write with
+`placeholderValue(x)` and passes those keys to `singleAnswers`, which
+sets them aside whenever the key has another answer. A name written only
+as a placeholder keeps that answer. The TypeScript store does the same
+for `null` and `undefined` in `sameConstructionAcrossWrites`.
+
+A name bound to a call is a separate case. Its one answer is the call,
+and the rule that says a call is written as what its callee returns
+only fires for the call itself, never for a name that reaches one. An
+adapter that wants the deeper answer asks `wantedSubject` a second
+time with the call as the subject and takes that answer. The
+TypeScript store does the same in `resolveWrittenValue` and in
+`subjectConstructionOf`, whenever a name resolves to a call.
+
 ## Explaining an answer
 
 Evaluate the same rules under `@suss/datalog`'s `witnesses` algebra and