aontu 0.62.0 → 0.64.0

package/src/unify.ts

@@ -29,36 +29,6 @@ import {
 } from './val/top'
 
 
-// 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 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
-// `arg.unify(top(), ...)` rather than through the dispatcher, so without
-// this the counter stays flat while the JavaScript stack keeps growing:
-// a 1500-deep `upper(upper(...))` resolved in TypeScript while Go — which
-// routes its arguments through the counted dispatcher — reported
-// `unify_cycle`. Returns the budget nil instead of running when the
-// budget is spent.
 const withDepth = (
   ctx: AontuContext, a: any, b: any, run: () => any
 ): any => {
@@ -78,27 +48,10 @@ const withDepth = (
 // Vals should only have to unify downwards (in .unify) over Vals they understand.
 // and for complex Vals, TOP, which means self unify if not yet done
 const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
-  // Fast paths that don't recurse and so don't need cycle-detection:
-  // short-circuit before the saw-key build and seen-map lookup (which
-  // together cost ~2.5µs per call). Only return early when the result
-  // is already `done` — a non-done result would need the trailing
-  // top() unify below.
-  //
-  //   A6a: same ref, already done
-  //   A6b: different ref but same id + both done
-  //   P1:  exact-equal scalars that are already done (14% of calls
-  //        in foo-sdk, ~100% with a.done=true)
   if (a !== undefined && a !== null) {
     if (a === b) {
       if (a.done) return a
     }
-    // ... 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) {
@@ -113,19 +66,8 @@ 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: 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.isRefer
             && !a.isRel && !a.isGraphAtom && !a.isRecurse) {
           // The deprecation record survives the fast path too (G3):
           // `deprecate(5) & 5` short-circuits here.
@@ -138,6 +80,17 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
     }
   }
 
+  // ABSENCE IS THE UNIT OF THE MEET (ADR-034). The dispatch below is
+  // the LEFT operand's, so `&` commutes only if it is answered here.
+  if (null != a && null != b) {
+    if (true === a.isAbsent) {
+      return a.unify(b, ctx)
+    }
+    if (true === b.isAbsent) {
+      return b.unify(a, ctx)
+    }
+  }
+
   const te = ctx.explain && explainOpen(ctx, ctx.explain, 'unite', a, b)
 
   let out = a
@@ -155,16 +108,9 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
   // See for example PrefVal peg.id equality inspection.
   const sawCount = ctx.seen[saw] ?? 0
   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
-    // rather than on the document, which is exactly what the
-    // determinism clause forbids (docs/trust.md). Tripping here instead
-    // makes it a stated budget error, like the pass budget.
     out = makeNilErr(ctx, 'unify_cycle', a, b)
   }
   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)
   }
   else {
@@ -174,18 +120,6 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
     try {
       let unified = false
 
-      // Dispatch ladder. Structure note:
-      //   - `a == null` is degenerate (shouldn't happen in practice:
-      //     the top-level call seeds with a real Val). Kept for safety.
-      //   - TOP is the unit element: unifying with it returns the
-      //     other side. Handle both sides.
-      //   - Otherwise route by Val type. Complex Vals (Conjunct,
-      //     Disjunct, Ref, Pref, Func, Expect) have their own unify
-      //     that knows how to absorb the peer; prefer `a.unify` when
-      //     `a` is complex, else `b.unify` when `b` is complex. If
-      //     neither is complex and it's not a plain-scalar match, fall
-      //     through to the generic `a.unify` (concrete Val classes
-      //     each handle their own peer case).
       if (a == null) {
         out = b
         why = 'b'
@@ -219,18 +153,9 @@ 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))
+        // An op DRIVES while an operand has not decided (ADR-037).
+        || (b.isOp && (hasPlace(b) || b.holdsStaged))
         // 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.
@@ -243,10 +168,6 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
         unified = true
         why = 'bv'
       }
-      // Exactly equal scalars (not caught by early fast-path — e.g.
-      // 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)
@@ -263,18 +184,7 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
         why += 'N'
       }
 
-      // Any non-done top-level result self-unifies with TOP to ensure
-      // its children finish converging. Skipped when `unified` is true
-      // because the branch that set `out = X.unify(Y, ctx)` already
-      // ran that Val's own unify logic.
       if (!out.done && !unified) {
-        // Once per pass per (Val, path): within a single fixpoint pass
-        // nothing external to the subtree changes, so repeating the TOP
-        // self-unify — which conjunct folds otherwise trigger once per
-        // fold term — is pure re-work, and on large models (hundreds of
-        // sibling terms) the repeats trip the MAXCYCLE guard as a false
-        // positive. The path is part of the key: a shared Val can
-        // resolve path-dependent content differently per location.
         if (undefined !== ctx.cc
           && (out as any)._tcc === ctx.cc && (out as any)._tpi === ctx.pathidx) {
           why += 't'
@@ -290,12 +200,6 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
       }
     }
     catch (err: any) {
-      // This catch-all converts an unexpected exception into an 'internal'
-      // Nil so one bad node doesn't crash a whole unify. To avoid fully
-      // masking regressions, preserve the original error message (and a
-      // RangeError flag — i.e. stack overflow from runaway recursion) on
-      // the Nil's details so it surfaces in the formatted error rather
-      // than vanishing. See err.ts (descErr) for how details render.
       out = makeNilErr(ctx, 'internal', a, b, undefined, {
         error: String(err?.message ?? err),
         ...(err instanceof RangeError ? { overflow: true } : {}),
@@ -308,20 +212,10 @@ 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) ??
@@ -331,12 +225,6 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
     }
   }
 
-  // THE RENDER RIDERS SURVIVE EVERY MEET (RENDER.0.md P7), and here
-  // for the deprecation record's reason: a reference resolves by
-  // MEETING its target with the peer at the referring position, and an
-  // emitted piece meets the vocabulary's alternative before the fold
-  // ever sees it, so a record lost in one meet shape is a line the
-  // trace cannot name. Both are absent unless the run is instrumented.
   if (undefined !== ctx.reads &&
     null != out && true === (out as any).isVal && !out.isTop && !out.isNil) {
     riders(a, b, out)
@@ -346,18 +234,6 @@ const unite = (ctx: AontuContext, a: any, b: any, whence: string) => {
 }
 
 
-// The two P7 riders, carried from the operands to the result: the read
-// address a value was found at, and the dispatch that emitted it.
-// First record wins, as the deprecation record's does. Reached only
-// from an instrumented run (AontuContext.reads), so an ordinary meet
-// pays the one property load its call site makes and nothing else.
-//
-// AN OPERAND MAY BE ABSENT and reading through it is not a decision:
-// `unite` is called with no peer wherever a bag holds a key its peer
-// does not, and `Object(undefined)` is an empty object, so both riders
-// are read the same way whether the operand is there or not. Written
-// with a test first, that test had an arm no instrumented document
-// reached -- true of the reading, not of the engine.
 function riders(a: any, b: any, to: any): void {
   const av = Object(a)
   const bv = Object(b)
@@ -367,17 +243,10 @@ function riders(a: any, b: any, to: any): void {
       to.origin = org
     }
   }
-  if (null == to.emitted) {
-    const emt = av.emitted ?? bv.emitted
-    if (null != emt) {
-      to.emitted = emt
-    }
-  }
 }
 
 
 function update(x: Val, _y: Val) {
-  // TODO: update x with y.site
   return x
 }
 
@@ -406,26 +275,6 @@ 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
@@ -433,32 +282,8 @@ function applyFlows(ctx: AontuContext, root: Val): Val {
   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
@@ -517,8 +342,6 @@ class Unify {
         })
       }
 
-      // TODO: messy
-      // uctx.seterr(this.err)
       uctx.err = this.err
       uctx.explain = this.explain
 
@@ -526,12 +349,6 @@ 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
@@ -547,71 +364,23 @@ class Unify {
       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 = {}
 
-        // 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
         }
 
         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
@@ -621,16 +390,6 @@ class Unify {
         uctx = uctx.clone({ root: res })
       }
 
-      // The pass budget is spent AND the final pass still made
-      // progress: the model was cut off while converging, and no other
-      // error explains why. Silent truncation would surface later as
-      // ordinary incompleteness, so exhaustion is a semantic error of
-      // its own (class budget, docs/trust.md clause 2) -- retrying with
-      // a larger budget is a valid response to THIS code and useless
-      // for path_cycle or no_path. A STABLE residue (the final pass
-      // changed nothing -- e.g. a stuck `1+true`) is not a budget
-      // failure: it is ordinary incompleteness and stays silent here,
-      // surfacing at generate exactly as before.
       if (maxcc <= this.cc && DONE !== res.dc && 0 === uctx.err.length
         && undefined !== prevCanon && prevCanon !== res.canon) {
         makeNilErr(uctx, 'budget_passes', undefined, undefined, 'resolve', {
@@ -653,8 +412,6 @@ class Unify {
 } /* node:coverage ignore next 10 */
 
 
-
-
 export {
   Unify,
   unite,

package/src/utility.ts

@@ -1,18 +1,9 @@
 /* Copyright (c) 2023-2025 Richard Rodger, MIT License */
 
 
-
 import type { AontuOptions, TrustOptions, Val } from './type'
 
 
-// THE INCLUDE OPTIONS AN ENGINE HANDS ITS Aontu INSTANCE. Every verb
-// engine builds one, and until there were two such options each did it
-// inline -- `null == options.trust ? undefined : { trust: options.trust }`,
-// written out twelve times. That is fine while there is one option and
-// a latent bug the moment there are two: `textExt` had to reach the
-// same twelve places, and the one it missed refused a `.md` include
-// under a flag the bare command honoured. One function now, so a third
-// include option is threaded once.
 type IncludeOptions = {
   trust?: TrustOptions
   textExt?: string[]
@@ -27,11 +18,6 @@ function includeOpts(options: IncludeOptions): Partial<AontuOptions> {
 }
 
 
-// Default walk() depth limit. High enough that real configs are never
-// silently truncated (the old default of 32 dropped marks on deeply
-// nested refs/funcs → wrong output), while still bounding runaway or
-// accidentally-cyclic walks (walk has no cycle detection). Pass null for
-// truly unbounded.
 const WALK_DEFAULT_MAXDEPTH = 9999
 
 
@@ -47,12 +33,6 @@ 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[] }> = []
@@ -97,17 +77,6 @@ function deprecationMessage(d: Record<string, string>): string {
 }
 
 
-// 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