aontu 0.53.0 → 0.55.0

package/src/subsume.ts

@@ -32,6 +32,7 @@ import {
   constraintAdmitsScalar,
 } from './val/ConstraintVal'
 import { kindSubsumes } from './val/ScalarKindVal'
+import { prefixMeet } from './val/PathVal'
 import { prefInnerPeg } from './val/PrefVal'
 
 
@@ -360,6 +361,22 @@ export function subsumeNode(
     return 'no'
   }
 
+  // Container kinds (docs/design/PATHS.0.md): `map()` subsumes every
+  // map and itself, `list()` every list. The unit literals (`{}`,
+  // `[]`) already subsume through the container rules; only the kind
+  // former needs an arm.
+  if (true === (g as any)?.isContainerKind) {
+    const ga: any = g
+    const sa: any = s
+    if ((true === ga.isMapKind && (true === sa?.isMap || true === sa?.isMapKind))
+      || (true === ga.isListKind && (true === sa?.isList || true === sa?.isListKind))) {
+      return 'yes'
+    }
+    record(state, 'compat_narrowed', path, g, s,
+      'the general container kind admits no such value')
+    return 'no'
+  }
+
   // Constraint residuals.
   if (true === g?.isConstraint) {
     if (true === s?.isConstraint) {
@@ -396,8 +413,14 @@ export function subsumeNode(
   }
 
   // Concrete scalars subsume only themselves (identity compares kind
-  // as well as value).
+  // as well as value) -- except paths, whose meet is the prefix rule
+  // (ADR-016): a prefix admits every extension of itself, so it
+  // subsumes one, exactly as the meet answers the longer.
   if (true === g?.isScalar) {
+    if (true === g.isPath && true === (s as any)?.isPath &&
+      prefixMeet(g.peg, (s as any).peg) === (s as any).peg) {
+      return 'yes'
+    }
     if (true === s?.isScalar && true === g.same?.(s)) {
       return 'yes'
     }
@@ -431,13 +454,29 @@ export function subsumeNode(
       (v: any, k: string) => v.peg[Number(k)])
   }
 
-  // The ladder above is total in practice: every evaluated former is a
-  // scalar, kind, constraint, map, list, disjunct, or top, or is caught
-  // by admission (pref) or unresolved (ref, var, conjunct, expect,
-  // func). The arm is kept because "in practice" is evaluation's
-  // property, not this walk's, and a future value class (or a nil, see
-  // the top rule) must land on an honest `undecided`, not fall out of
-  // the walk with no answer.
+  // THE LADDER IS NOT TOTAL, and the formers that fall past it are the
+  // ones the evaluator MEANS to leave standing: a recursion, a
+  // relation and its graph atom, a `refer()` target constraint. None
+  // of them describes a set of values a structural walk can compare,
+  // so `undecided` is the honest answer for two DIFFERENT ones.
+  //
+  // For two IDENTICAL ones it is not. REFLEXIVITY IS A LAW -- every
+  // value admits itself -- and identity is the HASH FORM, the same
+  // rule the unresolved branch above applies and for the same reason:
+  // it costs nothing, because it runs only where the answer would
+  // otherwise be `undecided`. Without it a document that declares a
+  // relation, shares a template by reference or alias, or recurses did
+  // not subsume ITSELF, so `breaking` on the idiom the language exists
+  // for hard-failed and had to run --allow-undecided, which masks the
+  // genuine undecideds it exists to surface (use-cases/BUGS.md 64,
+  // and 28 before it).
+  //
+  // A NIL is the exception, and the reason the law is spelled here
+  // rather than in `unresolved`: a nil is not a value, so it admits
+  // nothing, itself included.
+  if (true !== g?.isNil && true !== s?.isNil && hcanon(g) === hcanon(s)) {
+    return 'yes'
+  }
   record(state, 'sub_unresolved', path, g, s,
     'no subsumption rule covers this pair of value formers')
   return 'undecided'
@@ -510,11 +549,21 @@ function subsumeBag(
   }
 
   // Spread templates: a path-dependent template's meaning depends on
-  // where it lands, which no structural comparison can decide.
+  // where it lands, which no structural comparison can decide -- UNLESS
+  // the two templates are the same template. REFLEXIVITY IS A LAW and
+  // identity is the HASH FORM (the same rule the unresolved branch of
+  // subsumeNode applies): two byte-identical templates admit the same
+  // set wherever they land, so a document with a reference- or
+  // alias-valued template subsumes itself, and the comparison either
+  // side of the template is decided on its own merits rather than
+  // dragged to `undecided` (use-cases/BUGS.md 64). Where they are NOT
+  // identical, nothing structural can decide them and the fold stands.
   const gcj = g.spread?.cj
   const scj = s.spread?.cj
   if (null != gcj || null != scj) {
-    if (true === gcj?.isPathDependent || true === scj?.isPathDependent) {
+    const sameTemplate = null != gcj && null != scj && hcanon(gcj) === hcanon(scj)
+    if (!sameTemplate &&
+      (true === gcj?.isPathDependent || true === scj?.isPathDependent)) {
       record(state, 'sub_path_dependent_spread', path, gcj ?? g, scj ?? s,
         'a path-dependent spread template cannot be compared structurally')
       worse('undecided')

package/src/unify.ts

@@ -8,6 +8,7 @@ import { AontuContext } from './ctx'
 import { DONE } from './type'
 
 import { makeNilErr } from './err'
+import { findAt } from './val/ReferFuncVal'
 
 import { NilVal } from './val/NilVal'
 import { hasPlace } from './val/PlaceVal'
@@ -111,13 +112,20 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
             && !a.isMap && !a.isList
             && !a.isConjunct && !a.isDisjunct
             && !a.isRef && !a.isPref && !a.isFunc && !a.isExpect
-            // NOT two TOPs (G4 phase 1): every top has the same
-            // (absent) peg, so this path treated any two as the same
-            // value — true of the unit itself, false of a unit
-            // CARRYING AN IDENTITY, and `id(x) & id(y)` is two of
-            // those. The slow path answers the same thing for two
-            // plain tops, and refuses the pair for two named ones.
-            && !a.isTop && !b.isTop) {
+            // NOT two TOPs: every top has the same (absent) peg, so
+            // this path would treat any two as the same value and
+            // return one of them whole — dropping a rider the other
+            // carries. The slow path answers the same thing for two
+            // plain tops, so nothing is lost by declining the shortcut.
+            && !a.isTop && !b.isTop
+            // NOT two rel residuals (RELATIONS P1) for the same
+            // reason: a settled rel is DONE with an absent peg, so
+            // any two matched here — dropping one side's type and
+            // held constraints. RelVal.unify merges them instead.
+            // NOT two graph atoms (P2) either: acyclic() and
+            // inverse(x) share a constructor and an absent peg
+            // without being the same declaration.
+            && !a.isRel && !a.isGraphAtom && !a.isRecurse) {
           // The deprecation record survives the fast path too (G3):
           // `deprecate(5) & 5` short-circuits here.
           if (null == a.deprecation && null != b.deprecation) {
@@ -222,14 +230,24 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
         // purpose -- every other operator meets its peer the way it
         // always has, through the conjunct fold that drives it.
         || (b.isOp && hasPlace(b))
+        // A graph atom DRIVES (RELATIONS P2): its peer is the value
+        // it rides beside -- a container, a rel, a scalar -- and none
+        // of them know the atom; the atom knows to residuate.
+        || b.isGraphAtom
+        // The recursive residual DRIVES for the same reason: its peer
+        // is the concrete structure it expands against.
+        || b.isRecurse
       ) {
         out = b.unify(a, te ? ctx.clone({ explain: ec(te, 'BW') }) : ctx)
         unified = true
         why = 'bv'
       }
       // Exactly equal scalars (not caught by early fast-path — e.g.
-      // because a or b isn't .done yet).
-      else if (a.constructor === b.constructor && a.peg === b.peg) {
+      // because a or b isn't .done yet). Rel residuals are excluded
+      // exactly as in the fast path: their pegs are equally absent
+      // without the values being the same relation.
+      else if (a.constructor === b.constructor && a.peg === b.peg
+        && !a.isRel && !a.isGraphAtom && !a.isRecurse) {
         out = update(a, b)
         why = 'up'
       }
@@ -297,24 +315,6 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
     ctx.prov.record(ctx.path, a, b, out)
   }
 
-  // The IDENTITY survives every meet (G4 phase 1), by the same
-  // channel and for the same reason as the deprecation record below.
-  // TWO DIFFERENT NAMES on one node is a contradiction, not a merge:
-  // one node cannot be two entities, and the error names both sites.
-  if (null != out && true === (out as any).isVal && !out.isNil) {
-    const ae = null != a ? a.entity : undefined
-    const be = null != b ? b.entity : undefined
-    if (null != ae && null != be && ae !== be) {
-      out = makeNilErr(ctx, 'id_conflict', a, b)
-    }
-    else if (!out.isTop) {
-      const e = ae ?? be
-      if (null != e) {
-        out.entity = e
-      }
-    }
-  }
-
   // The deprecation record survives EVERY meet (G3 phase 4): the
   // boolean marks have their own sweeps (ConjunctVal, the bag walks),
   // but a record lost in one meet shape is a use the tooling never
@@ -364,99 +364,69 @@ function residuePaths(v: Val, max: number): string[] {
 }
 
 
-// IDENTITY-MERGE (G4 phase 1): every node in one evaluation carrying
-// the same id is unified with every other. Declaring two nodes the
-// same entity MEANS unifying them, so this is not a lookup table —
-// it is a meet, and a contradiction between two declarations is an
-// ordinary conflict naming both sites.
+// THE TYPE FLOW, APPLIED (G4 phase 2). `refer(t)` unifies `t` INTO the
+// node it addresses, which is a write at a position the meet is not
+// currently at -- the one non-local effect in the evaluator.
 //
-// Run once per fixpoint pass, after the pass's own unification: a
-// position picks up the representative, the representative picks up
-// the position, and the two converge across passes exactly as chained
-// references do, inside the same `maxcc` bound.
+// It cannot be only a write made during the pass. A pass BUILDS a new
+// tree from the old one, and `ctx.root` during pass N is pass N-1's
+// result; a subtree rebuilt by pass N (which is exactly what happens
+// when the link sits inside its own target, or when two nodes link at
+// each other) drops a write made into the previous one. So each flow is
+// also RECORDED, keyed by the target's path, and re-applied to the
+// pass's own result here.
 //
-// The tree stays a TREE. Every declared position holds the merged
-// value and generation emits it at each path — duplication, as
-// references generate today. Identity adds addressing, not a new
-// shape.
-// The ctx DESCENDS with the walk, so the merge's meet happens at the
-// position's own path: a contribution `$.b.k` picked up from `$.a.k`
-// is recorded against `$.b.k`, which is where a reader asking `why`
-// stands. Merging under the root ctx instead filed every contribution
-// at the top and left the positions themselves with an empty record —
-// and the Go port, whose bag loops derive the base from the value's
-// own path, already answered the useful way.
-function mergeEntities(ctx: AontuContext, root: Val): Val {
-  const reg: Map<string, Val> = (ctx as any).entities
-
-  // COLLECT, then APPLY — the same walk twice, not two walks. A single
-  // pass merges each position into the representative as it meets it,
-  // which leaves the positions it already passed holding the pre-merge
-  // value: `a: id(x) & {k:1}` kept `{k:1}` while `b: id(x) & {j:2}`
-  // became `{j:2,k:1}`, and the two sites disagreed about what the one
-  // entity is. The representative is therefore settled over the WHOLE
-  // tree before any position is written.
-  //
-  // `write` is which half is running. One function rather than two
-  // because the two halves differ in three lines and agree in the walk
-  // — and a walk written twice is a walk that drifts.
-  const walk = (node: any, seen: Set<any>, nctx: AontuContext,
-    write: boolean): any => {
-    if (null == node || true !== node.isVal) {
-      return node
-    }
-
-    const name = (node as any).entity
-    if (null != name) {
-      if (write) {
-        // The SUBSTITUTION happens before the seen-guard, not after.
-        // Two positions of one entity hold the SAME object once a pass
-        // has merged them, so a guard that ran first would visit the
-        // first position, replace it with a newer representative, and
-        // then skip the second as already-seen — leaving it on the
-        // older value. That is exactly what a `refer(t)` flow
-        // produces: it writes a new representative mid-pass, and every
-        // position must take it.
-        const rep: any = reg.get(name)
-        if (null != rep && rep !== node) {
-          node = rep
-        }
-      }
-      else {
-        const rep = reg.get(name)
-        reg.set(name, null == rep || rep === node ? node :
-          unite(nctx, node, rep, 'entity'))
-      }
-    }
-
-    // The guard bounds the DESCENT, which is all it was ever for: a
-    // unified tree is a graph, and a subtree is worth walking once.
-    if (seen.has(node)) {
-      return node
-    }
-    seen.add(node)
-
-    if ((true === node.isMap || true === node.isList) && null != node.peg) {
-      for (const k of Object.keys(node.peg)) {
-        const out = walk(node.peg[k], seen, nctx.descend(k), write)
-        if (write) {
-          node.peg[k] = out
-        }
-      }
-    }
-    return node
-  }
-
-  walk(root, new Set(), ctx, false)
-
-  // NOTHING TO APPLY. The collect half is also the "does this document
-  // use identity at all?" answer, so a document that never says `id()`
-  // pays for one walk per pass rather than two — and the writing half
-  // never runs over a tree it cannot change.
-  if (0 === reg.size) {
+// Keyed by PATH, so there is no registry of names to collide in
+// (ADR-014) -- the key is the position the address resolved to, and
+// re-uniting the same type at the same position is idempotent, which is
+// what makes replaying every recorded flow every pass correct rather
+// than merely cheap.
+//
+// The pass loop is its only caller; it is EXPORTED for the test that
+// pins the unresolved-path guard below (see there).
+function applyFlows(ctx: AontuContext, root: Val): Val {
+  const flows: Map<string, Val> | undefined = (ctx as any).referflows
+  // NOTHING TO APPLY is the common case -- a document with no links
+  // pays one property load per pass, and the walk never runs.
+  if (null == flows || 0 === flows.size) {
     return root
   }
-  return walk(root, new Set(), ctx, true)
+  // Sorted, so two flows landing at overlapping positions arrive in the
+  // same order in both ports.
+  for (const key of [...flows.keys()].sort()) {
+    const path = key.split('\x00')
+    // The SHARED resolver, the one `refer` itself uses: a second
+    // descent written here would be a second answer to "what does this
+    // path name", and the two would drift (the Go twin calls the same
+    // findAt, arm for arm -- ADR-001).
+    //
+    // A RECORDED PATH THAT NO LONGER RESOLVES is skipped rather than
+    // refused: the record outliving its position is a question about
+    // the tree, and the link that named it answers it
+    // (test/spec/refer.tsv, `flow-target-moved-away`).
+    //
+    // NO DOCUMENT REACHES IT: a record is written only for a path that
+    // HAD resolved, and unification never takes a node back out of the
+    // tree — `move` copies and hides its source rather than removing
+    // it, which is the one rearrangement that looked like it would
+    // (probed in both ports: the flow still resolves on every pass,
+    // `flow-lands-then-its-parent-moves`). The guard is the contract
+    // for a rearrangement that does, and it is pinned by a direct call
+    // (`apply-flows-skips-a-record-that-stops-resolving` in
+    // ts/test/coverage3.test.ts) rather than by an ignore marker: node's
+    // `coverage ignore` drops LINES, and the gate reads BRANCH records,
+    // which survive it. The Go twin in go/unify.go can use the marker
+    // because that gate counts statements.
+    const found = findAt(root, path)
+    if (undefined === found) {
+      continue
+    }
+    const { parent, key: pkey, val: node } = found
+    const merged = unite(ctx.descend(pkey as string), node,
+      flows.get(key) as Val, 'refer-flow')
+    parent.peg[pkey as string] = merged
+  }
+  return root
 }
 
 
@@ -514,11 +484,17 @@ class Unify {
       // keyed by ref canon + source site, shared across all passes.
       ; (uctx as any).snapmap = new Map()
 
-      // The identity registry (G4 phase 1): id -> the representative
-      // value every position with that id has been merged into. Same
-      // lifetime and placement as the ref-spread snapshot map above —
-      // one evaluation, one set of entities.
-      ; (uctx as any).entities = new Map()
+      // The RECORDED TYPE FLOWS (G4 phase 2): target path -> the type
+      // `refer(t)` unified into it, replayed onto each pass's result by
+      // applyFlows. Seeded HERE, on the unify root, for the reason the
+      // snapshot map above is: a descended context is Object.create'd
+      // from its parent, so a `??=` in the descendant would make its
+      // OWN map and the root would never see what was recorded.
+      ; (uctx as any).referflows = new Map()
+
+      // The re-entrancy guard for those flows: the set of target paths
+      // a flow is currently inside. Same placement, same reason.
+      ; (uctx as any)._referflow = new Set()
 
       const explain = null == ctx?.explain ? undefined : ctx?.explain
       const te = explain && explainOpen(uctx, explain, 'root', res)
@@ -582,9 +558,10 @@ class Unify {
         // conjuncts) are pinned as vet.tsv's multi-* rows in both
         // ports.
 
-        // The identity merge, after the pass's own unification: the
-        // positions this pass produced are what there is to merge.
-        res = mergeEntities(uctx, res)
+        // The recorded type flows, re-applied to the tree THIS pass
+        // built: a pass rebuilds subtrees, and a flow written into the
+        // previous pass's tree does not survive that.
+        res = applyFlows(uctx, res)
 
         // The staging signal for the NEXT pass, rendered here rather
         // than at the top of the loop so a model that is FINISHED is
@@ -635,5 +612,5 @@ export {
   Unify,
   unite,
   withDepth,
-  mergeEntities,
+  applyFlows,
 }

package/src/utility.ts

@@ -75,78 +75,19 @@ function deprecationMessage(d: Record<string, string>): string {
 }
 
 
-// SPREAD TEMPLATES MAY NOT STAMP ONE ID ONTO EVERY CHILD (G4 phase
-// 1, clearing rule 3). `&: id(svc/thing) & {…}` says that every child
-// of the bag IS the entity `svc/thing`, and the identity merge then
-// unifies all of them into one another: an author who wrote a
-// per-child template would get a single merged blob, and any two
-// children that disagreed about a field would fail at a site that
-// explains nothing.
+// The canonical form of a value, wrapped in the RIDER it carries —
+// the deprecation record (G3 phase 4) — reparseably, so
+// `deprecate(x, m)` survives canon. Bags render their children through
+// this (MapVal/ListVal canon), which is where a marked FIELD — the
+// realistic case — lives.
 //
-// A PATH-DEPENDENT argument is allowed, and is how the author says
-// what they meant: `&: id(key()) & {…}` names each child distinctly,
-// resolved per destination by the existing spreadClone machinery.
-// Duck-typed on the `isIdFunc` flag rather than imported: this file
-// is below the Val classes, and the identity function sits above
-// them.
-function constantIdFunc(v: any, seen?: Set<any>): any {
-  if (null == v || true !== v.isVal) {
-    return undefined
-  }
-  const s = seen ?? new Set()
-  if (s.has(v)) {
-    return undefined
-  }
-  s.add(v)
-
-  if (true === v.isIdFunc && true !== v.isPathDependent) {
-    return v
-  }
-
-  const peg = v.peg
-  if (null != peg && 'object' === typeof peg) {
-    for (const k of Object.keys(peg)) {
-      const found = constantIdFunc(peg[k], s)
-      if (undefined !== found) {
-        return found
-      }
-    }
-  }
-  return constantIdFunc(v.spread?.cj, s)
-}
-
-
-// The IDENTITY wrapper (G4 phase 1): `id("svc/auth")&{…}`, written
-// as the conjunct an author writes, so canon reparses to the same
-// entity. This deliberately differs from the type/hide MARKS, which
-// canon drops (test/spec/marks.tsv, row `type-canon`): identity is
-// semantic content, and G6's canon-hash must see it — two documents
-// that disagree about which entity a node IS do not mean the same
-// thing and must not hash alike.
-//
-// The name is JSON-quoted whatever it spells: `-` is not a bare-text
-// character (test/spec/op-chars.tsv pins `a:6-2` as a parse error), so
-// an unquoted `id(team-pay)` would not reparse.
-function canonEntity(v: Val): string {
-  const c = v.canon
-  const e = v.entity
-  return null == e ? c : 'id(' + JSON.stringify(e) + ')&' + c
-}
-
-
-// The canonical form of a value, wrapped in the RIDERS it carries —
-// the identity (G4 phase 1) and the deprecation record (G3 phase 4) —
-// reparseably, so `id(name) & x` and `deprecate(x, m)` survive canon.
-// Bags render their children through this (MapVal/ListVal canon),
-// which is where a marked FIELD — the realistic case — lives.
-//
-// The riders render HERE and not in the value's own `canon` for the
+// The rider renders HERE and not in the value's own `canon` for the
 // same reason the guard at the MapVal call site tests the isVal flag:
 // a bag's canon recursion visits each child once, and a child that
 // wrapped itself as well would render its subtree twice per level —
 // 2^depth on a nested document.
 function canonRiders(v: Val): string {
-  const c = canonEntity(v)
+  const c = v.canon
   const d = v.deprecation
   if (null == d) {
     return c
@@ -327,7 +268,6 @@ function items(o: any) {
 export {
   items,
   propagateMarks,
-  constantIdFunc,
   canonRiders,
   collectDeprecations,
   walkBagVals,