aontu 0.61.0 → 0.63.0

package/src/trim.ts

@@ -1,26 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// The trim reporter (G3 phase 6,
-// docs/capability-review/g3-subsumption-evolution.md): report REDUNDANT
-// map entries — entries whose removal leaves the evaluated result
-// unchanged, the spread-implied case included — as paths. Report-only,
-// deliberately: canon discards comments and layout, so REWRITING the
-// file needs G7's format-preserving patch surface; trim ships as a
-// reporter here and becomes an editor there.
-//
-// The test is EVALUATE-AND-COMPARE: for each candidate entry, re-parse
-// the source, delete the entry from the parsed tree, evaluate, and
-// compare canons. This subsumes the design's spread case — an entry a
-// spread template re-supplies evaluates to the same canon without its
-// explicit spelling — and is honest about everything the fixpoint can
-// see (references, templates, duplicate-key merges), where a purely
-// structural test would guess. A removal that ERRORS is not redundant:
-// the entry is load-bearing.
-//
-// Parsed trees are single-use (docs/reference-api.md), so every probe
-// is its own parse: one evaluation per candidate plus one for the
-// baseline. A reporter can afford that; an editor loop belongs to G7.
 
 import { Aontu } from './aontu'
 import { failureFinding } from './vet'
@@ -34,12 +14,6 @@ export type TrimReport = {
   verdict: TrimVerdict
   redundant: string[]
 
-  // WHY the run could not be made, in the same finding shape vet
-  // reports in (the review's finding F). An `error` verdict used to
-  // arrive with an empty report -- something is wrong with the
-  // document, and nothing about what -- which is the one answer a
-  // repair loop cannot act on. Present ONLY on an `error` verdict, so
-  // a clean report stays exactly the two fields it always was.
   errors?: VetFinding[]
 }
 
@@ -47,14 +21,8 @@ export type TrimOptions = {
   // Where the document CAME FROM, so a relative `@"file"` load inside
   // it resolves from its own directory (vet's schemaPath precedent).
   path?: string
-  // The include capability this document evaluates under (G5,
-  // docs/trust.md). vet's precedent: the verb passes the profile the
-  // caller asked for, and an absent option means today's default.
   trust?: TrustOptions
 
-  // Extensions additionally read as text (the CLI's `--text-ext`).
-  // Rides beside `trust` because it is the other half of what an
-  // include may read.
   textExt?: string[]
 }
 
@@ -64,14 +32,6 @@ function pathText(path: string[]): string {
 }
 
 
-// Every (map, key) pair in a PARSED tree, parent-first. Candidates come
-// from the parse rather than the evaluation: an entry the fixpoint
-// erases or rewrites still has to be addressable for deletion. The
-// non-Val guard is for a bag's raw peg entries, which degenerate
-// parses can leave behind. Exported (with deleteAt and evalCanon) for
-// the direct unit tests (ADR-002, ts/test/coverage3.test.ts): the
-// defensive arms are unreachable through trimCheck, whose candidates
-// come from an identical parse.
 export function candidates(v: any, path: string[], out: string[][]): void {
   if (null == v || true !== v.isVal) {
     return
@@ -118,21 +78,12 @@ export function deleteAt(root: any, path: string[]): boolean {
 }
 
 
-// One evaluation: parse (deleting the entry at delPath, when given),
-// unify under collect, and answer the canon — or undefined when the
-// source does not stand up, which for the baseline is the caller's
-// error verdict and for a probe means "load-bearing".
 export function evalCanon(
   src: string, opts: TrimOptions, delPath?: string[],
   sink?: { ctx?: any, failed?: any }): string | undefined {
   const aontu = new Aontu(includeOpts(opts))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == opts.path ? undefined : { path: opts.path }
-  // WHY the run failed, for the one caller that reports it. The
-  // BASELINE run passes a sink and a probe does not: a probe's failure
-  // means "load-bearing", which is an answer rather than a fault, and
-  // reporting it would bury the one real finding under one entry's
-  // worth of noise per candidate.
   const fail = (failed?: any): undefined => {
     if (null != sink) {
       sink.ctx = ctx
@@ -158,10 +109,6 @@ export function evalCanon(
 }
 
 
-// The whole reporter: the baseline canon, then one probe per candidate
-// entry, parent-first — and a child of a redundant parent is SKIPPED,
-// because "remove the whole entry" already covers it and reporting
-// both would tell the author to delete the same text twice.
 export function trimCheck(src: string, opts?: TrimOptions): TrimReport {
   const options = opts ?? {}
 

package/src/type.ts

@@ -2,7 +2,6 @@
 
 import * as Fs from 'node:fs'
 
-// TODO: refactor these out
 
 import { Resolver } from '@tabnas/multisource'
 
@@ -13,35 +12,12 @@ import type { ValMark, ValSpec } from './val/Val'
 type FST = typeof Fs
 
 
-
-// The trust profile (G5, docs/trust.md): what an evaluation may read,
-// and how much work it may do. Trust is a property of the EVALUATION,
-// not the document -- a .aon file cannot request more capability -- and
-// the profile adds zero language syntax.
-//
-// The include capability:
-//   'none'            @"..." is always denied
-//   { mem: {...} }    a virtual file set only; nothing else resolves
-//   { root: '/dir' }  real files, realpath-confined below root;
-//                     no package resolution
-//   'system'          the full memory -> file -> package chain
-//                     (today's default, and the unconfined posture)
-//
-// Budgets are integer counts of engine events -- never wall-clock, which
-// would make identical inputs fail differently across machines (the
-// exact nondeterminism docs/trust.md forbids). The defaults are the
-// shared spec-visible constants pinned by test/spec/budget.tsv.
 type TrustInclude =
   | 'none'
   | 'system'
   | { mem: Record<string, string> }
   | { root: string }
 
-// Only the budgets BOTH ports can honour are profile surface: passes
-// and depth. The per-pair revisit bound (999) stays a TS-internal
-// constant — the Go dispatcher has no revisit counter (it is
-// depth-guarded), and a knob one port cannot implement would break the
-// parity contract (ADR-001) by construction.
 type TrustBudget = {
   passes?: number    // fixpoint passes (default 9)
   depth?: number     // structural recursion depth (default 1000)
@@ -53,21 +29,14 @@ type TrustOptions = {
 }
 
 type AontuOptions = {
-  src?: string    // Source text.
+  src?: string
   print?: number  // Print debug verbosity
-  resolver?: Resolver // Source resolver
+  resolver?: Resolver
   base?: string // Base path for resolver
   path?: string // Path of entry file
   debug?: boolean
   trace?: boolean
   fs?: FST
-  // errfs READS FOR THE ERROR RENDERER ONLY, never for resolution.
-  // A frame excerpts the file its arrow names, which means reading
-  // that file -- but handing the same reader to `fs` would change
-  // which leg the include RESOLVER takes (its file leg reads through
-  // the host filesystem when one is given, so a package hit can
-  // become a file hit), and a diagnostic must not move the boundary
-  // it is describing.
   errfs?: FST
   deps?: any
   log?: any
@@ -77,19 +46,8 @@ type AontuOptions = {
   explain?: any[]
   trust?: TrustOptions // Trust profile (G5, docs/trust.md)
 
-  // EXTENSIONS ADDITIONALLY READ AS TEXT, without their dots. `.txt`
-  // is read as text with no option at all; this widens that set for a
-  // host that keeps its prose in `.md`, its queries in `.sql`, or its
-  // templates under some name only it knows. The file's bytes become
-  // one string scalar -- no parser is chosen for it, which is what
-  // makes widening the set safe to offer.
   textExt?: string[]
 
-  // The staged-flip warning window (G5 phase 6, CLI only): under the
-  // default 'system' capability the CLI supplies these, and the
-  // resolver calls trustWarn for every resolution that escapes
-  // trustWarnRoot or goes through package resolution — naming the flag
-  // a future default will require. Not a stable embedding API.
   trustWarn?: (kind: 'escape' | 'pkg', path: string) => void
   trustWarnRoot?: string
 }
@@ -108,7 +66,6 @@ type ValMap = { [key: string]: Val }
 type ValList = Val[]
 
 
-
 type ErrContext = {
   src?: string,
   fs?: FST,

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,7 @@ 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.isRel && !a.isGraphAtom && !a.isRecurse) {
           // The deprecation record survives the fast path too (G3):
           // `deprecate(5) & 5` short-circuits here.
@@ -138,6 +79,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 +107,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 +119,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 +152,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 +167,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 +183,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 +199,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 +211,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 +224,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 +233,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)
@@ -377,7 +252,6 @@ function riders(a: any, b: any, to: any): void {
 
 
 function update(x: Val, _y: Val) {
-  // TODO: update x with y.site
   return x
 }
 
@@ -406,26 +280,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 +287,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 +347,6 @@ class Unify {
         })
       }
 
-      // TODO: messy
-      // uctx.seterr(this.err)
       uctx.err = this.err
       uctx.explain = this.explain
 
@@ -526,12 +354,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 +369,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 +395,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 +417,6 @@ class Unify {
 } /* node:coverage ignore next 10 */
 
 
-
-
 export {
   Unify,
   unite,