aontu 0.61.0 → 0.63.0

package/src/val/RecurseVal.ts

@@ -1,31 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE RECURSIVE RESIDUAL (docs/design/RECURSION.0.md): where RefVal's
-// prefix test used to answer `path_cycle` for a self-reference --
-// `$.Node` written anywhere inside `Node` -- it now answers this
-// value: a deferred reference carrying the target path, exactly as a
-// constraint atom carries its bound. No new syntax: the reference the
-// author wrote simply MEANS the fixpoint.
-//
-// The three moments of every residual:
-//
-// - At unification, EXPAND ONE LEVEL PER MEET WITH STRUCTURE: met by
-//   a map, list, or scalar, the residual clones the schema body one
-//   level -- per destination, under ADR-005's clone discipline -- and
-//   unifies the clone with the peer. The clone's own self-reference
-//   is again this residual, so each expansion consumes one level of
-//   concrete data; data is finite, so expansion terminates
-//   (structural descent), with the depth budget as the backstop
-//   (recursion_budget).
-// - In canon and the aon1- hash, SYMBOLIC: the residual prints as the
-//   reference the author wrote, so a recursive schema's canon is
-//   finite and round-trips, and the hash pins the mu-form rather than
-//   any unrolling.
-// - At generation, an unexpanded residual REFUSES with
-//   recursion_unexpanded. Guardedness is therefore EMERGENT: under
-//   `next?:` the refusal is isolated and the optional key drops;
-//   under `*null | $.Node` the preference generates; a REQUIRED
-//   recursive field with no data refuses at the instance.
 
 import type {
   Val,
@@ -78,12 +52,6 @@ class RecurseVal extends FeatureVal {
     return out
   }
 
-  // The schema body the target names, from the ROOT: the fixpoint is
-  // over the finished definition, and the definition's own residual
-  // keeps it finite. When the root does not contain the target -- the
-  // residual was LIFTED out of its defining tree, as vet's anchored
-  // meet does -- fall back to ctx._fixroot, the settled tree the
-  // lifter kept for exactly this walk.
   private body(ctx: AontuContext): Val | undefined {
     return walkTarget(ctx.root, this.target)
       ?? walkTarget((ctx as any)._fixroot, this.target)
@@ -92,9 +60,6 @@ class RecurseVal extends FeatureVal {
   unify(peer: Val, ctx: AontuContext): Val {
     const p: any = peer
 
-    // The self-drive: nothing to advance -- the residual waits for
-    // structure. (A null/nil peer never arrives; unite's ladder
-    // absorbs both.)
     if (null == peer || true === p.isTop) {
       return this
     }
@@ -105,9 +70,6 @@ class RecurseVal extends FeatureVal {
         && this.target.every((s, i) => s === p.target[i])) {
         return this
       }
-      // Different targets -- mutual recursion meeting -- are BOTH
-      // held: each expands as data arrives, through the fold that
-      // keeps a conjunct's members separate.
       const out = new ConjunctVal({ peg: [this, peer] }, ctx)
       propagateMarks(this, out)
       out.path = this.path
@@ -129,25 +91,6 @@ class RecurseVal extends FeatureVal {
         out.path = this.path
         return out
       }
-      // ADR-005's clone discipline: the expansion is a per-destination
-      // instantiation, so the definition itself is never written
-      // into. The clone's type/hide marks are CLEARED at every depth,
-      // exactly as a plain reference copy clears them (concreteFlow's
-      // rule): the schema is hidden, the instances it expands into
-      // are the output.
-      // The clone is REBASED to the DRIVE path explicitly (spec.path;
-      // the Go twin passes cp(r.path), whose stored paths its clone
-      // arms keep clean): the default rebase slices the definition's
-      // path by the destination's length, which leaks definition
-      // segments into instance paths whenever the destination is
-      // shallower -- a residual carried inside a copied definition
-      // body (`chain: $.spec.Step` inside Policy, copied to a slot
-      // shallower than the definition) reported
-      // `$.payments_policy.Policy.chain.then.approver` for the
-      // finding Go placed at `$.payments_policy.chain.then.approver`.
-      // The drive path is also right under vet's anchored meet, which
-      // drives AT the anchor's own path (see vet.ts), so anchored
-      // findings land in the schema's namespace in both ports.
       const level: any = body.clone(ctx, {
         dup: true, path: [...ctx.path],
       } as any)
@@ -173,9 +116,6 @@ class RecurseVal extends FeatureVal {
   }
 
   gen(ctx: AontuContext) {
-    // An unexpanded residual in a demanded position refuses;
-    // guardedness is emergent -- under an optional key the bag's
-    // isolated context swallows this and drops the key.
     makeNilErr(ctx, 'recursion_unexpanded', this, undefined, 'recurse',
       { target: '$.' + this.target.join('.') })
     return undefined
@@ -204,13 +144,6 @@ function bumpRecurse(v: any, xc: number): void {
     v.xc = Math.max(v.xc, xc)
     return
   }
-  // A RAW REFERENCE TO A RECURSIVE TARGET IS THE RECURSION, minted or
-  // not -- the same reading containsRecurseOf already takes, and the
-  // reason bound 2 was inert. A freshly cloned level holds the
-  // definition's references UNRESOLVED, so this walk found no
-  // residual to stamp and `xc` read 0 at every expansion, in the
-  // healthy form too. The seed rides on the reference and the
-  // residual minted from it starts there (ts/src/val/RefVal.ts).
   if (true === v.isRef) {
     v.rxc = Math.max(v.rxc ?? 0, xc)
     return
@@ -237,12 +170,6 @@ function bumpRecurse(v: any, xc: number): void {
 }
 
 
-// containsRecurseOf answers whether a definition holds a residual of
-// the given target -- i.e. the definition is (transitively) the
-// fixpoint that target names. A reference RESOLVING to such a
-// definition must itself answer the residual: cloned instead, every
-// reparse of a canon unrolled the schema one more level and canon
-// never converged.
 function containsRecurseOf(v: any, target: string[], depth?: number): boolean {
   const d = depth ?? 0
   if (null == v || true !== v.isVal || 8 < d) {
@@ -252,14 +179,6 @@ function containsRecurseOf(v: any, target: string[], depth?: number): boolean {
     return v.target.length === target.length
       && v.target.every((s: string, i: number) => s === target[i])
   }
-  // A RAW REFERENCE to the target IS the recursion, minted or not:
-  // the answer must not depend on whether the definition's own
-  // prefix position has been visited yet. Without this arm the
-  // answer was ORDER-DEPENDENT -- reparsing a generated canon puts
-  // the instance before the definition, its trailing `$.spec.Step`
-  // leaves resolved before `Step.then` had minted, and each resolve
-  // cloned one more unrolled level until the unify depth guard
-  // (unify_cycle) killed the document.
   if (true === v.isRef && Array.isArray(v.peg)) {
     if (v.peg.length === target.length
       && v.peg.every((s: any, i: number) => s === target[i])) {

package/src/val/RefVal.ts

@@ -1,7 +1,6 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
-
 import {
   walk,
   explainOpen,
@@ -42,22 +41,12 @@ import { BigIntegerVal } from './BigIntegerVal'
 import { BigDecimalVal } from './BigDecimalVal'
 
 
-
 // A path segment no spelling can produce, used when append meets a Val
 // class it has no rule for. A key cannot contain a NUL, so this can never
 // match, which turns a silent path-shortening bug into a visible miss.
 const UNSPELLABLE_SEGMENT = '\u0000unspellable'
 
 
-// Is this value an unresolved type()/hide() call — or a conjunct still
-// carrying one? A reference that lands on one must defer rather than
-// clone it (see the call site in `find`): the marks such a call will
-// stamp belong to the field it was WRITTEN at, and a clone resolving
-// at the reference's site re-applies them after the reference's
-// mark-clearing walk has already run. Only the two mark wrappers
-// qualify — every other pending call resolves to an unmarked value,
-// and the existing early-clone behaviour for those is pinned
-// (move()/copy() ghost rows, hole-filling conjuncts).
 function pendingMarkWrapper(v: any): boolean {
   if (true === v.isTypeFunc || true === v.isHideFunc) {
     return !v.done
@@ -108,13 +97,6 @@ class RefVal extends FeatureVal {
   // a rendering of the settled tree, never a parse-time property.
   expansion: Val | undefined = undefined
 
-  // THE RECURSION SEED (use-cases/BUGS.md §57). A reference that names
-  // a recursive definition IS the fixpoint reference; it mints a
-  // RecurseVal when it resolves. bumpRecurse stamps the expansion
-  // depth here, because a freshly cloned level holds the definition's
-  // references UNRESOLVED and so has no residual to stamp -- which is
-  // why the design's second termination bound read 0 at every
-  // expansion. The minted residual starts from this.
   rxc: number = 0
   prefix: boolean = false
 
@@ -139,14 +121,12 @@ class RefVal extends FeatureVal {
       this.append(spec.peg[pI])
     }
 
-    //console.log('RefVal', this.id, this.peg)
   }
 
 
   append(part: any) {
     let partval
 
-    // console.log('APPEND', part)
 
     if ('string' === typeof part) {
       partval = part
@@ -159,33 +139,16 @@ class RefVal extends FeatureVal {
     }
 
     else if (part instanceof IntegerVal) {
-      // partval = '' + part.peg
       partval = part.src
       this.peg.push(partval)
     }
 
-    // TODO: this is a bit of a hack, review
-    // Seems like a fundamental ambiguity?
-    // Resolved by path function
     else if (part instanceof NumberVal) {
-      // let partvals: string[] = part.peg.toFixed(11).replace(/(\.0)?0+$/, '$1').split('.')
       let partvals: string[] = part.src.split('.')
       this.peg.push(...partvals)
     }
 
-    // THE EXACT LEAVES ARE PATH TEXT LIKE ANY OTHER SPELLING. `0d1` as a
-    // segment addresses the key literally spelled `0d1` -- the same key
-    // `a:{0d1:7}` creates -- and is NOT the number 1, so it neither
-    // indexes a list nor reaches a key spelled `1`.
-    //
-    // Without these branches the part fell off the end of the chain and
-    // was SILENTLY DROPPED, so `$.a.0d0` resolved to `$.a` and handed back
-    // the CONTAINER. That is a wrong value, not a miss -- strictly worse
-    // than an error -- and it made `$.a.0d0` and `$.a.0d1` denote the same
-    // location.
     else if (part instanceof BigIntegerVal || part instanceof BigDecimalVal) {
-      // A bigdecimal splits on its point exactly as a float does, so
-      // `$.x.0d1.5` addresses two levels.
       this.peg.push(...part.src.split('.'))
     }
 
@@ -219,12 +182,6 @@ class RefVal extends FeatureVal {
       this.peg.push(...part.peg)
     }
 
-    // A closed chain, deliberately. Every branch above ends in a push, so
-    // an unhandled Val class used to fall through in SILENCE and shorten
-    // the path by one segment -- which is how the two exact leaves, added
-    // by the number tower, made references resolve to their own container.
-    // A segment that cannot be spelled is pushed as one that cannot match,
-    // so the reference misses loudly instead of succeeding wrongly.
     else {
       this.peg.push(UNSPELLABLE_SEGMENT)
     }
@@ -239,9 +196,6 @@ class RefVal extends FeatureVal {
 
     if (this.id !== peer.id) {
 
-      // TODO: not resolved when all Vals in path are done is an error
-      // as path cannot be found
-      // let resolved: Val | undefined = null == ctx ? this : ctx.find(this)
       let found: Val | undefined = this.find(ctx)
 
       // `?? this` makes resolved non-nullish, so an unresolved reference
@@ -275,21 +229,12 @@ class RefVal extends FeatureVal {
       out.dc = DONE === out.dc ? DONE : this.dc + 1
     }
 
-    // console.log('REFVAL-UNIFY-OUT', ctx.cc, this.id, this.canon, this.done, 'P=', peer.id, peer.canon, peer.done, '->', out.id, out.canon, out.done)
 
     explainClose(te, out)
     return out
   }
 
 
-  // `snap` is set by snapshotRefSpread (MapVal): a SPREAD snapshot
-  // wants the target's pre-resolution STRUCTURE — key()/path() still
-  // unresolved, to be re-resolved per destination — so the
-  // pending-mark-wrapper defer below must not apply to it. Deferring
-  // there made the snapshot wait until the target's own key() had
-  // resolved at the target, and the literal leaked into every
-  // destination (the exact failure the snapshot exists to prevent —
-  // test/spec/spread-type.tsv, spread-type-key-ref).
   find(ctx: AontuContext, snap?: boolean) {
     let out: Val | undefined = undefined
 
@@ -315,16 +260,8 @@ class RefVal extends FeatureVal {
 
     let refpath: string[] = []
     let pI = 0
-    // let descent = ''
 
     if (isprefixpath) {
-      // THE DETECTOR'S ANSWER IS A RESIDUAL (RECURSION.0.md): a
-      // self-reference under a guarded shape is the fixpoint the
-      // author wrote, so the prefix hit mints the recursive residual
-      // instead of refusing -- except the degenerate all-empty
-      // spelling (path("")), which names nothing and keeps its
-      // path_cycle. Only all-string paths recurse; anything else
-      // keeps the conservative refusal.
       let degenerate = 0 === this.path.length
       let target: string[] = []
       for (let i = 0; i < this.peg.length && !degenerate; i++) {
@@ -350,44 +287,16 @@ class RefVal extends FeatureVal {
 
       for (let pI = 0; pI < this.peg.length; pI++) {
         let part = this.peg[pI]
-        // An unspellable segment MISSES BEFORE ANY LOOKUP. The marker
-        // is NUL-prefixed because no spelling produces one, but a
-        // document can still hold a key spelled with an escaped NUL
-        // (`a:{"unspellable":7}`), and matching it would turn the
-        // silent path-shortening this marker exists to prevent into a
-        // different silent wrong value. The marker is a marker, never a
-        // lookup key.
         if (UNSPELLABLE_SEGMENT === part) {
           return makeNilErr(ctx, 'no_path', this)
         }
         if (part instanceof VarVal) {
-          // EVERY `$name` IN A PATH IS AN ORDINARY VARIABLE. `$KEY`,
-          // `$SELF` and `$PARENT` used to be intercepted here by name;
-          // they are gone (ADR-009). `key()` is the replacement for
-          // `$KEY` and answers where a value LANDS rather than where it
-          // was written, `$SELF.x` was only ever `$.x`, and `$PARENT.x`
-          // was only ever `.x`.
           {
             part = (part as VarVal).unify(top(), ctx)
             if (part.isNil) {
-              // TODO: var not found, so can't find path
               return
             }
             else {
-              // The resolved variable IS a path segment: $seg.r with
-              // seg="x" reads ...x.r (previously the coerced value was
-              // dropped, silently reading the path without it).
-              //
-              // Integer kind renders its EXACT digits -- the FOURTH site
-              // to get this wrong (see integerDigits and #21). `'' + peg`
-              // on a JS number gives the shortest round-tripping form, so
-              // a variable bound to 2^60 addressed the key
-              // "1152921504606847000" and missed the real one. Go's
-              // ref.go dispatches on kind here and was already correct.
-              //
-              // Every other kind is already right under `'' +`: a bigint
-              // and a Decimal stringify to exact digits, and a float must
-              // keep JS parity.
               parts.push(part.isInteger ?
                 integerDigits(part.peg as number) : '' + part.peg)
             }
@@ -419,9 +328,7 @@ class RefVal extends FeatureVal {
       if (null != node) {
         for (; pI < refpath.length; pI++) {
           let part = refpath[pI]
-          // console.log('PART', pI, part, node)
 
-          // descent += (' | ' + pI + '=' + node.canon) // Util.inspect(node))
 
           if (node.isMap) {
             node = node.peg[part]
@@ -429,15 +336,6 @@ class RefVal extends FeatureVal {
           else if (node.isList) {
             node = node.peg[part]
           }
-          // A PENDING MARK WRAPPER IS TRANSPARENT TO THE WALK: hide()
-          // and type() only mark, and their argument is the structure
-          // the path names. Without this, two sibling schemas in one
-          // hide() bag deadlock -- the wrapper waits for its argument,
-          // the argument's members wait for references that walk into
-          // the unresolved wrapper (BUGS.md §53's family; the
-          // recursive Policy/Step pair found it again). The found node
-          // is cloned and mark-cleared exactly as any reference target
-          // is, and the wrapper still marks its own field.
           else if (true === (node as any).isFunc
             && ((node as any).isHideFunc || (node as any).isTypeFunc)
             && (true === (node as any).peg?.[0]?.isMap
@@ -445,26 +343,6 @@ class RefVal extends FeatureVal {
             node = (node as any).peg[0].peg[part]
           }
 
-          // AND SO IS A CONJUNCT THAT STILL CARRIES ONE (issue #164).
-          // Two statements for one key meet, so a key written as
-          // `T: type({...})` twice is a CONJUNCT of two wrappers -- and
-          // one written once beside a plain `T: {...}` is a conjunct
-          // too. The arm above sees a wrapper only when it is the whole
-          // node, so a reference into such a key walked into the
-          // conjunct and stopped: the wrapper waited for its argument,
-          // the argument waited for the reference, and neither moved.
-          // The first referring child of every consumer stayed
-          // unresolved and generation reported mapval_no_gen at a path
-          // that names none of this, which is how a five-file schema
-          // spent its evening being bisected.
-          //
-          // The answer at a segment is the MEET of what each term
-          // supplies, so terms that have no such member are skipped and
-          // the rest are conjoined -- one term answers as itself, and
-          // the ordinary map arm answers once the fold has happened.
-          // Restricted to a conjunct that still holds a pending
-          // wrapper: every other conjunct folds on its own, and this
-          // walk exists only to break the wrapper's deadlock.
           else if (true === (node as any).isConjunct
             && Array.isArray((node as any).peg)
             && pendingMarkWrapper(node)) {
@@ -499,16 +377,6 @@ class RefVal extends FeatureVal {
         }
       }
 
-      // THE ANCHORED-MEET FALLBACK (vet --at): an absolute reference
-      // inside a lifted subtree names the SCHEMA's namespace, and the
-      // meet's root does not contain it. The settled schema root the
-      // lifter kept (AontuContext._fixroot; see RecurseVal.body) is
-      // the tree such a reference means. Without this, a recursion
-      // re-entering through a list spread died as no_path at the
-      // first element under vet --at, while the map-tail form (whose
-      // residual was minted during schema settling) worked; the Go
-      // port answers the anchored meet from settled structures and
-      // never sees the gap.
       const fixroot: any = (ctx as any)._fixroot
       if (this.absolute && null != fixroot
         && (nopath || pI !== refpath.length)) {
@@ -541,14 +409,6 @@ class RefVal extends FeatureVal {
       else if (pI === refpath.length) {
         out = node
 
-        // THE READ IS RECORDED, AND THE VALUE STAMPED WITH WHERE IT
-        // WAS FOUND (RENDER.0.md P7). A resolved reference clones its
-        // target into the referring position, so without the stamp a
-        // value that arrived by reference knows only where it came to
-        // rest -- and `render --coverage` has nothing to measure the
-        // model against. Off unless the run is instrumented; the first
-        // address wins, and every reference to one node names the same
-        // address anyway.
         if (undefined !== ctx.reads && null != node) {
           // The root's own address is `$`, as the coverage walk spells
           // it: a dot with nothing after it would match no path there.
@@ -566,58 +426,18 @@ class RefVal extends FeatureVal {
           }
         }
 
-        // A reference landing on another reference -- or on a FUNCTION,
-        // whose arguments the chase now follows (issue #35) -- may be a
-        // PROVEN mutual cycle (a: $.b, b: $.a; a: $.b, b: upper($.a)).
-        // Follow the chain and, if it returns to a node still open above
-        // it, report path_cycle now instead of deferring every pass and
-        // dying later as a spent budget. No proof (the chain leaves plain
-        // refs and calls, or ends) defers as before.
         if (null != out && ((out as any).isRef || (out as any).isFunc) &&
           this.detectRefCycle(ctx)) {
           out = makeNilErr(ctx, 'path_cycle', this)
         }
-        // A PENDING MARK WRAPPER IS NOT YET A VALUE TO COPY (ADR-005).
-        // A type()/hide() call still waiting for its argument — an
-        // alias reference inside a type() body, a generator inside a
-        // hide() — would be cloned here as the CALL, and the clone
-        // then resolves at the REFERENCE's site, stamping marks that
-        // the mark-clearing walk below has already run too early to
-        // clear. That is how a type-marked alias silently suppressed
-        // the referring field's emission (use-cases/BUGS.md §12), how
-        // `hide(pack(...))` leaked its mark onto downstream packs
-        // (§11), and how hide() around a computed field swallowed the
-        // value into a silent [] (§35b). Defer instead: the reference
-        // residuates until the wrapper has resolved at its OWN field,
-        // and the ordinary marked-value path below then clears the
-        // marks on the clone as documented. The move() reference
-        // (`_hide_found`) is exempt: a move TRANSPLANTS the pending
-        // call, and the ghost rows (test/spec/func.tsv) pin that its
-        // innards resolve at the destination.
         else if (null != out && !snap && !this.mark._hide_found &&
           pendingMarkWrapper(out)) {
           out = undefined
         }
-        // A STAGED ARGUMENT SNAPSHOTS A SETTLED SOURCE (the argsnap
-        // flag, set by driveStagedArgs). A generator's data argument is
-        // a copy OUTSIDE the tree, so anything in the target that still
-        // resolves against its own tree location — a spread-injected
-        // relative reference, a pending template — must finish there
-        // BEFORE the copy is taken: cloned earlier, the copy's rebased
-        // relative refs dangle under the generator and the model dies
-        // as *_no_gen with the generator never firing. Deferring here
-        // is exactly the documented staging rule: the generator waits
-        // for the source, then snapshots it whole.
         else if (null != out && !snap && true === (ctx as any).argsnap &&
           !out.done) {
           out = undefined
         }
-        // A REFERENCE TO A RECURSIVE DEFINITION IS THE FIXPOINT
-        // REFERENCE (RECURSION.0.md): resolving it to a clone
-        // unrolled the schema one level, and every reparse of a
-        // canon then unrolled one more -- canon never converged. The
-        // residual is the resolved form, exactly as at the prefix
-        // positions inside the definition.
         else if (null != out && !snap && containsRecurseOf(out, this.peg as any)) {
           const rec: any = new RecurseVal(
             { target: [...this.peg], xc: this.rxc } as any, ctx)
@@ -628,83 +448,31 @@ class RefVal extends FeatureVal {
         // Types and hidden values are cloned and made concrete
         else if (null != out) { //  && (out.mark.type || out.mark.hide)) {
 
-          // console.log('FOUND-A', out)
 
           if (this.mark.type || this.mark.hide) {
             out.mark.type = this.mark.type
             out.mark.hide = this.mark.hide
 
-            // walk(out, (_key: string | number | undefined, val: Val) => {
-            //   val.mark.type = this.mark.type
-            //   val.mark.hide = this.mark.hide
-            //   return val
-            // })
           }
 
           if (this.mark._hide_found) {
             out.mark.hide = true
           }
 
-          // console.log('FOUND-B', out)
-
-          // A REFERENCE LIFTS: the copy is concrete, its type and hide
-          // marks cleared to the leaves -- a marked target is what the
-          // author hid or typed, and a reference to it is the author
-          // asking for it in the open. EXCEPT the snapshot a staged
-          // verb takes of its data (`argsnap`: each, emit, filter,
-          // pack, pick, join, the aggregates), when the target itself
-          // is not marked: a member marked inside an unmarked bag was
-          // hidden IN ITS OWN RIGHT, and the verb's enumeration
-          // (ts/src/val/members.ts, BUGS.md §79) needs to see that
-          // mark to leave the member out, as generation does. A marked
-          // target lifts even there, or `each($.schema.entities, _)`
-          // under `schema: hide({...})` would see every entity as
-          // hidden, since hide() marks to the leaves.
+
           const lifted = true !== (ctx as any).argsnap
             || true === out.mark.type || true === out.mark.hide
 
-          // A REFERENCE'S COPY OWNS ITS ARGUMENTS (ADR-025). The copy
-          // is a per-destination instance exactly as a spread's or a
-          // generator's is, so ADR-005's rule holds here too: nothing
-          // path-dependent may be shared between two destinations, or
-          // the first destination's resolution answers for them all.
-          // The shallow clone shared a call's ARGUMENTS -- so
-          // `items: [&: $.entities.User]` over a `close({...})` target
-          // gave every element the one inner map, whose path each
-          // element rebased in turn, and the constraint that failed at
-          // element 2 reported element 0's path (use-cases GAP 8).
-          //
-          // A STAGED CALL IS THE EXCEPTION, because it has not decided
-          // yet. Its arguments are still being driven AT ITS OWN SITE
-          // (the staging rule, G8 phase 0), and a copy that owned them
-          // would drive its own set at the referring position instead:
-          // the relative `.side_effect` in a `match()` would read the
-          // referring field's siblings (use-cases/09-agent-tools), and
-          // an alias naming an `emit` rule table -- a template, which
-          // is exactly a value copied before it resolves -- would read
-          // its recursive `%w` as a self-reference. A staged call
-          // ANYWHERE in the target counts: what is referenced is
-          // usually the conjunct the call sits in, not the call.
-          // The copy shares what the source is still settling, and
-          // owns the rest.
           out = out.clone(ctx, { dup: !out.holdsStaged })
 
           if (lifted) {
             walk(out, (_key: string | number | undefined, val: Val) => {
               val.mark.type = false
               val.mark.hide = false
-              // THE LINK IS NOT CLEARED (G4 phase 3): a link says what
-              // a value POINTS AT, and a copy of a link points at the
-              // same thing. An ABSOLUTE address still names the same
-              // node from the copy; a RELATIVE one is read from the
-              // copy's own position, which is what makes a referenced
-              // model resolve its internal links inside the copy
-              // (ADR-014).
               return val
             })
           }
 
-          // onsole.log('FOUND-C', out)
         }
       }
     }
@@ -715,45 +483,7 @@ class RefVal extends FeatureVal {
   }
 
 
-  // Follow the chain of plain references from this node; true iff the
-  // chain revisits a node -- a PROVEN reference cycle, distinct from a
-  // merely unresolved reference. Detection is only on the resolution
-  // chain revisiting a node, never on syntactic shape: a chain that
-  // passes through a variable segment, a conjunct or any other non-ref
-  // value yields no proof and the ref defers as before.
-  //
-  // A FUNCTION is followed, through its arguments (issue #35). A
-  // function resolves only once every argument does, so a chain that
-  // reaches `b:upper($.a)` and out through `$.a` has proved the same
-  // dependency a bare `b:$.a` proves -- `a:$.b b:upper($.a)` is a cycle
-  // whichever link wears the call. Without this the shape exhausted the
-  // depth budget instead: a `unify_cycle`, which under the G5 taxonomy
-  // means "retry with more may help", where a proven structural cycle is
-  // FIX THE MODEL. A conjunct and a disjunct stay unfollowed for reasons
-  // that are not the same: a disjunct member may simply not be taken, so
-  // reaching one proves nothing; a conjunct would be sound to follow, and
-  // is left out only because nothing needs it yet.
-  //
-  // The Go port reaches the same verdict on this shape by a DIFFERENT
-  // arm, and that difference outlives this method: its clonePath re-paths
-  // a resolved clone to the referring site, so the inner `$.a` lands at
-  // path [a] and the plain isprefixpath test proves the cycle before any
-  // chase is needed. TypeScript's clone keeps the source paths. ADR-001
-  // asks for arm-for-arm correspondence, so the clone-path difference is
-  // worth closing on its own; it is wider than this issue and both ports
-  // now agree on the verdict and the code either way.
   detectRefCycle(ctx: AontuContext): boolean {
-    // Depth-first with an explicit ANCESTOR set, because a function may
-    // carry several reference arguments and the cycle can run through
-    // any one of them. The set holds the chain currently being walked,
-    // not every node ever walked: revisiting a node reached down a
-    // DIFFERENT branch is an ordinary shared reference (two keys reading
-    // one third key), and only revisiting one that is still open above
-    // us is a cycle.
-    //
-    // Identity is the RESOLVED PATH, not the RefVal instance: the same
-    // target can be reached through distinct ref instances, and it is
-    // returning to the same place that closes a loop.
     const chase = (ref: RefVal, ancestors: Set<string>): boolean => {
       const rp = ref.plainRefPath()
       if (null == rp) {
@@ -870,7 +600,6 @@ class RefVal extends FeatureVal {
     }
     return (this.absolute ? '$' : '') +
       (0 < this.peg.length ? '.' : '') +
-      // this.peg.join(this.sep)
       this.peg.map((p: any) => '.' === p ? '' :
         (p.isVal ? p.canon : '' + p))
         .join('.')
@@ -878,18 +607,6 @@ class RefVal extends FeatureVal {
 
 
   get canon() {
-    // AN ALIAS REFERENCE CANONS AS THE VALUE IT NAMES. A reference left
-    // standing after unification is one inside a spread template
-    // (`[&: %u]`, `{&: {a: %u}}`): the template applies to children
-    // that have not arrived, so it is not resolved in place. Canon
-    // erases the declaration (an alias is a name for a value, and
-    // nothing more -- ALIASES.0.md §4), so the name alone would not
-    // reparse, and the hash of `t: {&: %u}` would differ from the hash
-    // of `t: {&: integer}`, which is the same document. The expansion
-    // is attached by expandAliases (ts/src/alias.ts) once the tree has
-    // settled; without one -- a parse-only tree, an unresolved name, or
-    // the KNOT of a recursive alias inside its own template -- the
-    // reference spells its name. Twin of RefVal.Canon in go/ref.go.
     if (undefined !== this.expansion) {
       return this.expansion.canon
     }
@@ -906,7 +623,6 @@ class RefVal extends FeatureVal {
       undefined,
     )
 
-    // TODO: refactor to use Site pointer
     nil.path = this.path
     nil.site.url = this.site.url
     nil.site.row = this.site.row