aontu 0.52.1 → 0.54.0

package/src/unify.ts

@@ -8,8 +8,10 @@ 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'
 
 import {
   Lang
@@ -26,27 +28,27 @@ import {
 } from './val/top'
 
 
-// Per-pass revisit bound: how many times one (Val, path) pair may be
-// re-unified within a single fixpoint pass before the evaluator calls it
-// non-convergence (`unify_cycle`). The old false positive here -- a
-// legal model with more than MAXCYCLE sibling conjunct terms at one
-// path, each re-running the TOP self-unify -- is fixed by the per-pass
-// memo below (_tcc/_tpi); test/spec/budget.tsv drives 1200 sibling
-// terms through both engines as the regression guard.
-const MAXCYCLE = 999
-
-// Structural recursion budget: how deep `unite` may nest before the
-// evaluator reports `unify_cycle`. SHARED LANGUAGE SURFACE -- Go's
-// maxUniteDepth (go/unify.go) carries the same number, and
-// test/spec/budget.tsv pins the boundary in both, so changing it is a
-// spec-visible change in both ports at once.
+// The evaluation budgets live on the context (ctx.budget: passes,
+// revisits, depth), defaulted there to the shared spec-visible
+// constants test/spec/budget.tsv pins in both ports (9 / 999 / 1000)
+// and configurable through the trust profile (G5, docs/trust.md) —
+// deterministically: a budget is an integer count of engine events,
+// never wall-clock.
 //
-// Why 1000: the whole shared suite peaks at 603 (the deliberately
-// extreme 1200-sibling-term fixture; ordinary documents are two orders
-// below), and V8 exhausts its call stack somewhere past depth ~1500 in
-// this evaluator. 1000 sits above every real document and below the
-// host limit, so the budget -- not the host -- decides the verdict.
-const MAXDEPTH = 1000
+// Why the revisit default is 999: how many times one (Val, path) pair
+// may be re-unified within a single fixpoint pass before the evaluator
+// calls it non-convergence (`unify_cycle`). The old false positive here
+// -- a legal model with many sibling conjunct terms at one path, each
+// re-running the TOP self-unify -- is fixed by the per-pass memo below
+// (_tcc/_tpi); test/spec/budget.tsv drives 1200 sibling terms through
+// both engines as the regression guard.
+//
+// Why the depth default is 1000: the whole shared suite peaks at 603
+// (the deliberately extreme 1200-sibling-term fixture; ordinary
+// documents are two orders below), and V8 exhausts its call stack
+// somewhere past depth ~1500 in this evaluator. 1000 sits above every
+// real document and below the host limit, so the budget -- not the
+// host -- decides the verdict.
 
 // Charge a DIRECT `Val.unify` recursion to the same depth budget that
 // `unite` enforces. Function and operator arguments evaluate through
@@ -59,7 +61,7 @@ const MAXDEPTH = 1000
 const withDepth = (
   ctx: AontuContext, a: any, b: any, run: () => any
 ): any => {
-  if (MAXDEPTH <= ctx._depth.n) {
+  if (ctx.budget.depth <= ctx._depth.n) {
     return makeNilErr(ctx, 'unify_cycle', a, b)
   }
   ctx._depth.n++
@@ -89,14 +91,46 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
     if (a === b) {
       if (a.done) return a
     }
-    else if (b !== undefined && b !== null) {
+    // ... and NOT on an instrumented run (G7 provenance). Both arms
+    // below answer with one operand and never reach the recorder at
+    // the tail, so an equal pair — two positions of one entity that
+    // agree, a clone meeting its source — contributed silently and
+    // `why` named one site where the Go port, whose recorder wraps the
+    // whole dispatcher, named both. Instrumented runs pay the slow
+    // path knowingly; uninstrumented ones pay one undefined check.
+    else if (b !== undefined && b !== null && undefined === ctx.prov) {
       if (a.done && b.done) {
-        if (a.id === b.id) return a
+        if (a.id === b.id) {
+          // The deprecation record survives the fast path (G3).
+          if (null == a.deprecation && null != b.deprecation) {
+            a.deprecation = b.deprecation
+          }
+          return a
+        }
         if (a.constructor === b.constructor && a.peg === b.peg
             && !a.isNil && !b.isNil
             && !a.isMap && !a.isList
             && !a.isConjunct && !a.isDisjunct
-            && !a.isRef && !a.isPref && !a.isFunc && !a.isExpect) {
+            && !a.isRef && !a.isPref && !a.isFunc && !a.isExpect
+            // 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) {
+            a.deprecation = b.deprecation
+          }
           return a
         }
       }
@@ -119,7 +153,7 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
   // NOTE: if this error occurs "unreasonably", attemp to avoid unnecesary unification
   // See for example PrefVal peg.id equality inspection.
   const sawCount = ctx.seen[saw] ?? 0
-  if (MAXDEPTH <= ctx._depth.n) {
+  if (ctx.budget.depth <= ctx._depth.n) {
     // Structural recursion budget. Without it, deep nesting exhausts the
     // V8 call stack and the catch-all below reports a RangeError as
     // `internal` — a verdict that depends on the host's stack size
@@ -128,7 +162,7 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
     // makes it a stated budget error, like the pass budget.
     out = makeNilErr(ctx, 'unify_cycle', a, b)
   }
-  else if (MAXCYCLE < sawCount) {
+  else if (ctx.budget.revisits < sawCount) {
     // console.log('SAW', sawCount, saw, a?.id, a?.canon, b?.id, b?.canon, ctx.cc)
     out = makeNilErr(ctx, 'unify_cycle', a, b)
   }
@@ -184,14 +218,36 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
         || b.isVar
         || b.isFunc
         || b.isExpect
+        // The refer residual (G4 phase 2) DRIVES, like the other
+        // residuals here: its peer is a plain string, which knows
+        // nothing about entity addresses, so letting the string drive
+        // dropped the address and left the constraint standing.
+        || b.isRefer
+        // An operator holding a HOLE (G8 phase 3) drives for the same
+        // reason: its peer is what FILLS it, and a scalar asked to
+        // unify with `_ + 2` sees an operator rather than a hole and
+        // refuses it on kind. Narrow to placeheld operators on
+        // 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'
       }
@@ -251,6 +307,29 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
 
   ctx.explain && explainClose(te, out)
 
+  // The provenance record (G7 phase 3), at the one place every meet
+  // passes through — the same reason the deprecation rider below lives
+  // here. Off by default: an uninstrumented run pays this one property
+  // load, and an instrumented one pays site materialisation knowingly.
+  if (undefined !== ctx.prov) {
+    ctx.prov.record(ctx.path, a, b, out)
+  }
+
+  // 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
+  // warns about, so it rides here, at the one place all meets pass
+  // through. First record wins; TOP and nil stay clean (TOP is the
+  // unit, and an error needs no deprecation).
+  if (null != out && true === (out as any).isVal &&
+    !out.isTop && !out.isNil && null == out.deprecation) {
+    const dep = (null != a ? a.deprecation : undefined) ??
+      (null != b ? b.deprecation : undefined)
+    if (null != dep) {
+      out.deprecation = dep
+    }
+  }
+
   return out
 }
 
@@ -285,6 +364,72 @@ function residuePaths(v: Val, max: number): string[] {
 }
 
 
+// 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.
+//
+// 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.
+//
+// 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
+  }
+  // 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
+}
+
+
 class Unify {
   root: Val
   res: Val
@@ -339,27 +484,96 @@ class Unify {
       // keyed by ref canon + source site, shared across all passes.
       ; (uctx as any).snapmap = 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)
 
       // NOTE: if true === res.done already, then this loop never needs to run.
-      let maxcc = 9 // 99
+      let maxcc = uctx.budget.passes
       let prevCanon: string | undefined = undefined
+      let lastCanon: string | undefined = undefined
+      let settle = false
       for (; this.cc < maxcc && DONE !== res.dc; this.cc++) {
         // console.log('CC', this.cc, res.canon)
         uctx.cc = this.cc
         uctx.seen = {}
-        res = unite(te ? uctx.clone({ explain: ec(te, 'run') }) : uctx, res, top(), 'unify')
 
-        if (0 < uctx.err.length) {
-          break
+        // THE STAGING RULE (G8 phase 0,
+        // docs/capability-review/g8-generation.md), stated once, here,
+        // for every value whose answer depends on WHERE IT IS. Such a
+        // value residuates while the model is still moving and fires on
+        // the first pass whose input is IDENTICAL to the previous
+        // pass's input: nothing moved, so nothing will move it again,
+        // and the position it reports is the position it ends at.
+        //
+        // Why the whole model and not the value's own path. A spread, a
+        // reference or a `move` can place a value under a path it has
+        // already been driven at and THEN change what encloses it --
+        // `move` hides its source one pass AFTER it copies it, and a
+        // `key()` that answered on the strength of its path alone would
+        // answer for the ghost. Stability of the model is the only
+        // signal that says every such rearrangement is finished.
+        uctx.settle = settle
+
+        // Snapshot BEFORE the final pass (the loop condition has
+        // already established the tree is not done), so exhaustion can
+        // tell "still refining" from "stable residue" below. Taken at
+        // the final pass's ENTRY rather than the previous pass's exit
+        // — the same value when the budget allows two passes, and the
+        // only possible value when the trust profile sets passes to 1,
+        // where the old placement (cc === maxcc - 2, never true) made
+        // exhaustion silent, exactly the truncation docs/trust.md
+        // forbids. `lastCanon` IS that entry canon whenever a previous
+        // pass rendered one, so this costs nothing extra.
+        if (this.cc === maxcc - 1) {
+          prevCanon = lastCanon ?? res.canon
         }
 
-        // Snapshot the second-to-last pass's result, so exhaustion can
-        // tell "still refining" from "stable residue" below. Only paid
-        // by models still unresolved this late.
-        if (this.cc === maxcc - 2 && DONE !== res.dc) {
-          prevCanon = res.canon
+        res = unite(te ? uctx.clone({ explain: ec(te, 'run') }) : uctx, res, top(), 'unify')
+
+        // MULTI-ERROR COLLECTION (G2 phase 6): the pass loop CONTINUES
+        // past an erroring pass, so independent failures a later pass
+        // would reach are collected in the same run — the break that
+        // stood here made every multi-error report truncated at the
+        // first erroring pass.
+        //
+        // What controls the cascade the design feared: a nil is
+        // ABSORBING (unite's isNil arms return the existing nil, no new
+        // error), so one failure stays ONE NilVal however many later
+        // meets touch it — a reference resolving to a failed target
+        // takes the same nil identity, which is exactly what lets the
+        // report layer dedup by identity. The probes that established
+        // this (fan-in refs, spread templates, disjunct trials, nested
+        // conjuncts) are pinned as vet.tsv's multi-* rows in both
+        // ports.
+
+        // 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
+        // never rendered at all: canon walks references, and the only
+        // trees that close a cycle are hand-built ones (the pass loop
+        // is what a test drives them through), which converge in one
+        // pass and must not be walked to decide a question that no
+        // longer arises.
+        if (DONE !== res.dc) {
+          const nowCanon = res.canon
+          settle = undefined !== lastCanon && lastCanon === nowCanon
+          lastCanon = nowCanon
         }
 
         uctx = uctx.clone({ root: res })
@@ -389,7 +603,7 @@ class Unify {
 
     this.res = res
   }
-} /* node:coverage ignore next 9 */
+} /* node:coverage ignore next 10 */
 
 
 
@@ -398,4 +612,5 @@ export {
   Unify,
   unite,
   withDepth,
+  applyFlows,
 }

package/src/utility.ts

@@ -25,6 +25,80 @@ function propagateMarks(source: Val, target: Val): void {
 }
 
 
+// Collect every value in the tree carrying the deprecation record (G3
+// phase 4), with its path — the one walk behind vet's `deprecated`
+// warnings and the LSP's Deprecated tags. The record travels on meets
+// (the unite rider) and clones, so this sees the declaration and every
+// use resolving through it. The non-Val guard is for a bag's raw peg
+// entries, which degenerate parses can leave behind.
+function collectDeprecations(
+  root: Val): Array<{ val: Val, path: string[] }> {
+  const out: Array<{ val: Val, path: string[] }> = []
+  walkBagVals(root, (v: any, path) => {
+    if (null != v.deprecation) {
+      out.push({ val: v, path })
+    }
+  })
+  return out
+}
+
+
+// Visit every Val reachable through bag children, with its path — the
+// walk under collectDeprecations and vet's default-validity lint. The
+// non-Val guard is for a bag's raw peg entries, which degenerate
+// parses can leave behind (pinned by the collect-deprecations direct
+// test, ts/test/coverage3.test.ts).
+function walkBagVals(
+  root: Val, fn: (v: Val, path: string[]) => void): void {
+  const walk = (v: any, path: string[]): void => {
+    if (null == v || true !== v.isVal) {
+      return
+    }
+    fn(v, path)
+    if ((true === v.isMap || true === v.isList) && null != v.peg) {
+      for (const k of Object.keys(v.peg)) {
+        walk(v.peg[k], [...path, k])
+      }
+    }
+  }
+  walk(root, [])
+}
+
+
+// The one-line prose for a deprecation record, shared by vet's warning
+// findings and the LSP's tagged diagnostics.
+function deprecationMessage(d: Record<string, string>): string {
+  const msg = 'string' === typeof d.msg ? d.msg : ''
+  return 'deprecated' + ('' === msg ? '' : ': ' + msg) +
+    ('string' === typeof d.use ? ' (use ' + d.use + ')' : '') +
+    ('string' === typeof d.since ? ' (since ' + d.since + ')' : '')
+}
+
+
+// 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.
+//
+// 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 = v.canon
+  const d = v.deprecation
+  if (null == d) {
+    return c
+  }
+  const keys = Object.keys(d).sort()
+  const rec = keys.map((k) =>
+    JSON.stringify(k) + ':' + JSON.stringify(d[k])).join(',')
+  return 'deprecate(' + c + ('' === rec ? '' : ',{' + rec + '}') + ')'
+}
+
+
 function formatPath(path: Val | string[], absolute?: boolean) {
   let parts: string[]
   if (Array.isArray(path)) {
@@ -188,12 +262,16 @@ function items(o: any) {
   else {
     return []
   }
-} /* node:coverage ignore next 15 */
+} /* node:coverage ignore next 18 */
 
 
 export {
   items,
   propagateMarks,
+  canonRiders,
+  collectDeprecations,
+  walkBagVals,
+  deprecationMessage,
   formatPath,
   walk,
   WalkApply,