aontu 0.62.0 → 0.63.0

package/src/val/SuperFuncVal.ts

@@ -1,16 +1,6 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
-// THE IMMEDIATE PARENT TYPE (docs/design/SUPER.0.md): super(x) answers
-// the type one step above its argument, structurally. The lattice
-// primitive Val.superior() stays what it always was -- the preference
-// override gate and query's kind lift -- and answers here only for the
-// forms it already served (scalars, kinds, top). Everything structural
-// is this file's walk: maps and lists lift child by child, preferences
-// unwrap, disjunctions distribute, constraints answer the kind they
-// constrain, and a recursion residual stays a symbolic call -- the
-// finite spelling of a lift that is itself recursive.
-
 import type {
   Val,
   ValSpec,
@@ -49,13 +39,6 @@ class SuperFuncVal extends FuncBaseVal {
   }
 
 
-  // A DIRECT residual rides the residuate path rather than resolving:
-  // the pending call IS the answer (SUPER.0.md, the phase boundary),
-  // printing as written and refusing at generation exactly as an
-  // unexpanded recursion does. Residuals met DURING descent are minted
-  // as pending child calls by superOf below; only the top-level
-  // argument needs the defer, or resolve would re-mint the same call
-  // inside one pass forever.
   deferResolve(_ctx: AontuContext, args?: Val[]): boolean {
     return true === (args?.[0] as any)?.isRecurse
   }
@@ -75,22 +58,11 @@ class SuperFuncVal extends FuncBaseVal {
 // caller drives arguments before resolve fires, so pending forms --
 // held conjuncts, unresolved references, holes -- never arrive).
 function superOf(ctx: AontuContext, v: any): Val {
-  // The residual's lift is itself recursive, so the finite answer is
-  // the symbolic call (SUPER.0.md): a fresh pending super() holding a
-  // clone of the residual, standing wherever the residual stood --
-  // the `next?` slot of a lifted recursive body prints
-  // `super($.Node)` and drops under an optional key at generation.
   if (true === v.isRecurse) {
     const call = new SuperFuncVal({ peg: [v.clone(ctx)] }, ctx)
     return v.place(call)
   }
 
-  // Maps and lists lift child by child. Shape is carried, not lifted:
-  // key optionality and closedness describe the container, and the
-  // spread template lifts so the result admits at the lifted level
-  // for future keys exactly as the original admitted at its own.
-  // A fresh bag (ADR-005 instantiation): type/hide marks are not
-  // copied -- the lift of a hidden definition is output.
   if (true === v.isMap) {
     const peg: Record<string, Val> = {}
     for (const k of Object.keys(v.peg)) {
@@ -115,9 +87,6 @@ function superOf(ctx: AontuContext, v: any): Val {
     return v.place(out)
   }
 
-  // The parent TYPE of a soft value is the parent of the value --
-  // softness does not survive typing. Deliberately NOT superpeg,
-  // whose top-for-a-kind answer is override-gate semantics.
   if (true === v.isPref) {
     return superOf(ctx, v.peg)
   }
@@ -145,11 +114,6 @@ function superOf(ctx: AontuContext, v: any): Val {
     return v.place(new DisjunctVal({ peg: arms }, ctx))
   }
 
-  // A constraint's parent is the kind it constrains: the absorbed
-  // leaf kind when it has one (integer & min(3) -> integer), else the
-  // domain its atoms compare in (min(3) -> number, min("a") ->
-  // string). length() constrains strings, lists and maps alike, so
-  // with neither it falls through to top.
   if (true === v.isConstraint) {
     if (null != v.kind) {
       return v.place(new ScalarKindVal({ peg: v.kind }))
@@ -163,12 +127,6 @@ function superOf(ctx: AontuContext, v: any): Val {
     return v.place(top())
   }
 
-  // The lattice primitive answers for the forms it always served:
-  // a concrete scalar lifts to its leaf kind, a kind to its parent,
-  // top to itself, and a NIL to itself -- which is how a failed
-  // argument stays the failure: `super(1 & 2)` reports the conflict
-  // rather than typing it. Where it has no meaningful answer (superior()
-  // defaults to top for features), top is the honest remainder.
   const sup = v.superior()
   if (null != sup && true !== (sup as any).isTop) {
     return sup

package/src/val/TopVal.ts

@@ -38,7 +38,6 @@ class TopVal extends Val {
   }
 
   same(peer: Val): boolean {
-    // return this === peer
     return peer.isTop
   }
 

package/src/val/TranslateFuncVal.ts

@@ -1,52 +1,5 @@
 /* Copyright (c) 2026 Richard Rodger, MIT License */
 
-// `translate` -- PER-CHARACTER SUBSTITUTION AND DELETION (SPIKE,
-// docs/design/JOSTRACA.0.md), after the `tr` command.
-//
-//   translate(s, from, to)   each character of `from` becomes the one
-//                            at the same position in `to`
-//   translate(s, from)       each character of `from` is deleted
-//
-// WHY IT IS NOT `rep`. `rep(s, pattern, sub)` matches a REGION and
-// substitutes text for it, so a per-character map is N calls over N
-// passes, each seeing the previous one's output -- and that composition
-// is wrong, not merely slow: `rep(rep(x, "a", "b"), "b", "a")` maps
-// every original `a` to `a` again. `translate` reads the source once
-// and consults a table, so `translate(x, "ab", "ba")` SWAPS them, which
-// is the operation `tr` exists for and the one a generator wants when
-// it rewrites a delimiter set or strips a character class.
-//
-// RANGES, as `tr` has them: `a-z` is every code point from `a` to `z`
-// inclusive, in both sets. A `-` first or last in a set is itself,
-// which is the only way to mean a literal one -- the sets take no
-// escape, because an aontu string literal has already processed its
-// own and a second escape layer over the first is a trap rather than a
-// feature. A descending range (`z-a`) is refused rather than read as
-// empty: it is always a mistake, and answering nothing for it hides it.
-//
-// A SHORT `to` PADS WITH ITS LAST CHARACTER, which is `tr`'s rule:
-// `translate(s, "abc", "x")` maps all three to `x`. An EMPTY or absent
-// `to` deletes instead, which is `tr -d`. Those are the same rule read
-// two ways -- there is no last character to pad with -- so the second
-// argument alone is deletion and needs no flag.
-//
-// A CHARACTER NAMED TWICE IN `from` TAKES ITS LAST MAPPING, because the
-// table is built left to right and a later entry overwrites an earlier.
-// `tr` does the same.
-//
-// CODE POINTS, NOT UTF-16 UNITS: one entry is one code point, so an
-// astral character maps as a unit and cannot be half-matched.
-//
-// NOT DONE, and deliberately: `tr`'s `-s` (squeeze repeats), `-c`
-// (complement) and its character classes (`[:alpha:]`). Each is a
-// second vocabulary on top of the sets, and none is needed by anything
-// the spike found. `re()` already spells a class for `rep`.
-//
-// SPIKE SCOPE. TypeScript only, so -- as with `nom` and the component
-// primitives -- deliberately absent from test/spec/signature.tsv,
-// BUILTIN_FUNCS and grammar/, all pinned in cross-port parity. Arity
-// and argument shape are refused here, and every refusal is
-// `invalid-arg`.
 
 import type {
   Val,
@@ -118,10 +71,7 @@ class TranslateFuncVal extends FuncBaseVal {
 
 
   resolve(ctx: AontuContext, args: Val[]): Val {
-    if (args.length < 2 || 3 < args.length) {
-      return makeNilErr(ctx, 'invalid-arg', this, undefined, 'arity')
-    }
-
+    // Arity is checked at parse (funcArity), so a body guard is dead.
     const src = textOf(args[0])
     if (undefined === src) {
       return makeNilErr(ctx, 'invalid-arg', this, args[0], 'src')

package/src/val/UpperFuncVal.ts

@@ -19,7 +19,6 @@ import { Decimal } from '../val/Decimal'
 import { caseRange, rangeArg } from './caserange'
 
 
-
 import { FuncBaseVal } from './FuncBaseVal'
 
 
@@ -51,12 +50,6 @@ class UpperFuncVal extends FuncBaseVal {
     const arg = args?.[0]
     const oldpeg = arg?.peg
 
-    // THE RANGE (ts/src/val/caserange.ts): `start` names the first
-    // character of the run when it is zero or positive and the last
-    // when it is negative; `len` of -1, and the absent argument, are
-    // the source's length. Refused on a NUMBER, where a run of
-    // characters means nothing -- the numeric arm below is a ceiling,
-    // not a case mapping.
     const start = rangeArg(args?.[1])
     const len = rangeArg(args?.[2])
     const ranged = undefined !== start || undefined !== len
@@ -68,11 +61,6 @@ class UpperFuncVal extends FuncBaseVal {
     const peg = 'string' === typeof oldpeg ?
       caseRange(oldpeg, start ?? 0, len ?? -1, true) :
       'number' === typeof oldpeg ? Math.ceil(oldpeg) :
-        // The exact leaves take an EXACT ceiling and keep their kind: a
-        // biginteger is already integral so it is its own ceiling, and a
-        // bigdecimal ceils by coefficient arithmetic. Math.ceil is not
-        // an option for either — it would round the value into binary64
-        // first, which is the loss the `0d` leaves exist to refuse.
         'bigint' === typeof oldpeg ? oldpeg :
           oldpeg instanceof Decimal ? oldpeg.ceil() :
             undefined

package/src/val/Val.ts

@@ -34,22 +34,6 @@ type ValSpec = {
   mark?: Partial<ValMark>,
   kind?: any,
 
-  // THE PER-DESTINATION INSTANTIATION FLAG (ADR-005). A generator's
-  // template is cloned once per destination, and every clone must be
-  // a full instance: nothing path-dependent may be shared between two
-  // destinations, or the first destination's resolution answers for
-  // them all. The default clone shares inner structure deliberately
-  // (`peg: this.peg` below — the move()/copy() ghost rows in
-  // test/spec/func.tsv pin that sharing), so instantiation asks for
-  // depth explicitly: `dup: true` makes FuncBaseVal, PrefVal and
-  // OpBaseVal clone their inner Vals too, and the bag/junction clones
-  // carry the flag down. Set by pack/each template instantiation,
-  // filter condition testing, spread application (MapVal/
-  // ListVal.spreadClone), and REFERENCE RESOLUTION of a target that
-  // holds no staged call, whose copy is a per-destination instance
-  // too (ADR-025) — never by the residuation clone, whose sharing is
-  // pinned behaviour, and never by a copy of something still being
-  // settled at its own site, which is what keeps the ghost rows.
   dup?: boolean,
 
 
@@ -72,7 +56,6 @@ type ValSpec = {
 }
 
 
-
 const DONE = -1
 
 const SPREAD = Symbol('spread')
@@ -84,12 +67,6 @@ const SPREAD = Symbol('spread')
 const EMPTY_ERR: any[] = Object.freeze([]) as unknown as any[]
 
 
-// Process-global, monotonic Val id source. Correctness only requires ids
-// to be unique within a single unify run (fast-path identity checks,
-// `same()`), which holds. It is NOT reset between generate() calls, so in
-// a long-running host (e.g. the LSP) it grows for the process lifetime;
-// that is acceptable — an id is a small number and is never used as a
-// memory key. TODO: switch to the per-run ctx.vc counter (see ctx.ts).
 let ID = 1000
 
 
@@ -100,6 +77,7 @@ abstract class Val {
   declare isVal: boolean
 
   declare isTop: boolean
+  declare isAbsent: boolean
   declare isNil: boolean
   declare isNull: boolean
   declare isMap: boolean
@@ -164,39 +142,12 @@ abstract class Val {
     hide: false,
   }
 
-  // The deprecation record (G3 phase 4, `deprecate(x, m)`): boolean
-  // marks cannot hold a message, a replacement path and a version, so
-  // the Val carries one optional record. Keys are the three the
-  // builtin defines (msg, use, since), all optional, values strings;
-  // `use` is a path spelled as a STRING — a live reference would
-  // resolve and unify, which is not wanted. Propagated through meets
-  // by propagateMarks and carried by clone, exactly as the boolean
-  // marks are.
   deprecation?: Record<string, string>
 
-  // The LINK (G4 phase 2/3): the tree address a `refer` resolved to,
-  // stamped on the string it answers. The string IS the value — a
-  // link, not an embedding — so nothing downstream could otherwise
-  // tell a checked link from a literal that happens to look like one,
-  // and the edge set (ts/src/graph.ts) is exactly the set of these.
   link?: string
 
-  // THE READ ADDRESS (RENDER.0.md P7): the tree path a reference
-  // resolved this value AT, stamped where it was found. A resolved
-  // reference CLONES its target into the referring position, so a
-  // value that arrived by reference otherwise knows only where it came
-  // to rest -- and a trace saying a line came from `$.code.units.0`
-  // names the output, not the model. Written only by an instrumented
-  // run (AontuContext.reads), carried by clone and by the meet rider,
-  // exactly as the deprecation record is.
   origin?: string
 
-  // THE DISPATCH THAT PRODUCED THIS PIECE (RENDER.0.md D11, P7): the
-  // node an `emit` matched and the rule it took, stamped on every
-  // piece the dispatch instantiated. The INNERMOST dispatch wins: a
-  // nested rule set splices its pieces into the outer result, and the
-  // rule that wrote a line is the one that wrote it. Written only by
-  // an instrumented run, and carried like `origin`.
   emitted?: EmitOrigin
 
   // The GRAPH of an evaluated document (G4 phase 3): the edge set,
@@ -222,7 +173,6 @@ abstract class Val {
   // functions whose branches no supported Node can execute.
   private _ctx: any
 
-  // TODO: Site needed in ctor
   constructor(spec: ValSpec, ctx?: AontuContext) {
     this._ctx = ctx
 
@@ -239,14 +189,11 @@ abstract class Val {
     // ctx.clone just to carry it.
     this.path = spec?.path ?? ctx?.path ?? []
 
-    // TODO: make this work
-    // this.id = spec?.id ?? (ctx ? ++ctx.vc : ++ID)
     this.id = ++ID
 
     this.mark.type = !!spec.mark?.type
     this.mark.hide = !!spec.mark?.hide
 
-    // console.log('BV', this.id, this.constructor.name, this.peg?.canon)
   }
 
 
@@ -295,26 +242,6 @@ abstract class Val {
     out.site.row = spec?.row ?? this.site.row
     out.site.col = spec?.col ?? this.site.col
     out.site.url = spec?.url ?? this.site.url
-    // THE SPAN TRAVELS WITH THE POSITION. Copying row and col but not
-    // the extent would leave a site that names a place and denies it has
-    // any width — internally inconsistent, and it made the two ports
-    // disagree on every derived value (the shared subsume rows caught
-    // it). Safe because the span is VERIFIABLE: a consumer reads the
-    // document at (row, col, len) and refuses when it does not match
-    // `src`, so a span that has stopped describing its value is
-    // detectable rather than believed. See ts/src/site.ts.
-    //
-    // Read from `this.site`, never from the spec: ValSpec.src is a
-    // DIFFERENT field — ScalarVal's literal spelling, kept so `$.a.0x0`
-    // addresses the key `0x0` — and reading it here would put a path
-    // segment where a source span belongs.
-    //
-    // UNCONDITIONAL, as the Go twin is (clonePath, go/clone.go). A
-    // guard dropping the span when the spec relocates the value was
-    // written first and the coverage gate refused it as dead: nothing
-    // clones to a new row or column. Should a relocating caller ever
-    // appear it must drop both fields — an extent belongs to a place,
-    // and the text at a new one is not this value's to claim.
     out.site.len = this.site.len
     out.site.src = this.site.src
 
@@ -332,11 +259,6 @@ abstract class Val {
       out.deprecation = this.deprecation
     }
 
-    // THE RENDER RIDERS TRAVEL WITH THE CLONE (P7), for the reason the
-    // deprecation record does: a clone of a value read at `$.schema`
-    // was read at `$.schema`, and a clone of an emitted piece is still
-    // that dispatch's. Both are absent unless the run is instrumented,
-    // so this is two undefined reads otherwise.
     if (null != this.origin) {
       out.origin = this.origin
     }
@@ -344,17 +266,6 @@ abstract class Val {
       out.emitted = this.emitted
     }
 
-    // THE APPLY-ONCE MARK TRAVELS WITH THE CLONE. `_spr` records which
-    // spread template has already been merged into this value, and the
-    // bag loops read it to keep a template from being applied twice
-    // (MapVal.unify, ListVal.unify). A clone that dropped it looked
-    // un-spread, so a REFERENCE resolving to a templated bag had the
-    // template applied a second time -- over the value the first
-    // application had already produced. With `n: key()` that meant
-    // meeting the answered `"x"` as though it were a map and asking
-    // `key()` again, which answered `"n"`: `$.a.b.f.x.n.n`, "n"
-    // against "x" (use-cases/BUGS.md §50). The Go port carries it and
-    // answered correctly; this is the canonical side catching up.
     if (null != (this as any)._spr) {
       ; (out as any)._spr = (this as any)._spr
     }
@@ -362,26 +273,9 @@ abstract class Val {
       ; (out as any)._sid = (this as any)._sid
     }
 
-    // PROVENANCE TRAVELS WITH THE CLONE, exactly as the site does, and
-    // for the same reason: a clone of a value the author wrote IS that
-    // written value somewhere else, and it carries the author's site,
-    // so it can be pointed at. Without this a default reaching a
-    // `pack()`-generated child, or a shape carried by a `$ref`, was
-    // invisible to `why` -- which answered "nothing met at this path"
-    // over a value it had just printed (the review's finding E). See
-    // WRITTEN in ts/src/provenance.ts; the mark is only ever set by an
-    // instrumented run, so this is one undefined read otherwise.
     if (true === (this as any)[WRITTEN]) {
       (out as any)[WRITTEN] = true
     }
-    // AND SO DOES BEING PART OF SOMETHING. A clone of a disjunction's
-    // member is still that member of that written disjunction, and the
-    // whole statement is what the author needs shown -- otherwise a
-    // default reaching a generated child reports `*"info"` and
-    // `string` as two contributions at two columns, where the author
-    // wrote `*info | string` once. A number, deliberately: a Val
-    // holding another Val as an own property is a cycle through the
-    // tree. See INNER_OF in ts/src/provenance.ts.
     if (null != (this as any)[INNER_OF]) {
       (out as any)[INNER_OF] = (this as any)[INNER_OF]
     }
@@ -390,16 +284,6 @@ abstract class Val {
   }
 
 
-  // Shallow clone for spread constraints: creates a new Val with the
-  // correct path context but shares non-path-dependent children.
-  // Override in MapVal/ListVal to avoid deep-cloning simple children.
-  //
-  // A FULL INSTANCE (`dup`, ADR-005): a spread constraint is applied
-  // once per destination child, and each application must own its
-  // path-dependent innards — a bare clone shared a call's arguments
-  // and a preference's inner value across destinations, so a spread
-  // like `&: {k: key(0)} & $.schema.C` resolved its one shared key()
-  // at the first child it met (use-cases/BUGS.md §12's id_name form).
   spreadClone(ctx: AontuContext): Val {
     const out = this.clone(ctx, { dup: true })
     repathInstance(out, out.path)
@@ -407,12 +291,6 @@ abstract class Val {
   }
 
 
-  // True if this Val's unification result depends on its own `path`
-  // — i.e. the tree contains a RefVal, KeyFuncVal, PathFuncVal,
-  // MoveFuncVal, or SuperFuncVal. Used by MapVal/ListVal.spreadClone
-  // to share the spread constraint across keys when it's safe.
-  // Lazy + cached: the answer is a function of the Val's immutable
-  // structure, so we compute once per Val.
   _isPathDependent?: boolean
   get isPathDependent(): boolean {
     if (this._isPathDependent !== undefined) return this._isPathDependent
@@ -443,13 +321,6 @@ abstract class Val {
   }
 
 
-  // A STAGED CALL STANDING ANYWHERE IN THIS VALUE (the `staged` flag,
-  // G8 phase 0). Such a call has not decided: its arguments are still
-  // being driven AT ITS OWN SITE, so a REFERENCE's copy shares it
-  // rather than owning a set of arguments it would drive at the
-  // referring position instead (RefVal.find, ADR-025). Not cached:
-  // unlike isPathDependent this is a fact about the value's current
-  // state, and the whole point is that it stops being true.
   get holdsStaged(): boolean {
     if (true === (this as any).staged) {
       return true
@@ -470,14 +341,6 @@ abstract class Val {
   }
 
 
-  // PUT A MINTED VALUE WHERE THIS ONE STANDS: the site travels, and so
-  // does provenance, because the two answer one question. A narrowed
-  // disjunction, a lifted kind, a resolved reference -- each is a
-  // value the engine built from a value the author wrote, standing
-  // where that one stood. Carrying the site and withholding the mark
-  // would let `why` print a value, know the line it came from, and
-  // still answer "nothing met at this path" (the review's finding E).
-  // See WRITTEN and INNER_OF in ts/src/provenance.ts.
   place(v: Val) {
     v.site.row = this.site.row
     v.site.col = this.site.col
@@ -493,25 +356,8 @@ abstract class Val {
     return v
   }
 
-  // CONTRACT: implementations should treat `this` and `peer` as
-  // immutable and return a new Val. KNOWN EXCEPTION: the MapVal/ListVal
-  // fast-path for a TOP peer returns and refines `this` in place (an
-  // intentional optimization for the fixpoint loop). The practical
-  // consequence is that a parsed/unified tree is SINGLE-USE — do not
-  // re-unify or re-generate the same Val, and do not share it across
-  // threads. The public Aontu.unify/generate entry points re-parse per
-  // call, so this only matters if you hold and reuse a Val yourself.
   unify(_peer: Val, _ctx: AontuContext): Val { return this }
 
-  // TODO: indicate marks in some way that is ignored by reparse.
-  // Need an annotation/taggins syntax? a:{}/type ?
-  // ABSTRACT: every concrete Val renders its own canonical form. There
-  // used to be an empty-string default here, and the one class relying
-  // on it (ExpectVal) was rendering a key with no value -- `{"r":}`,
-  // text that is not a document (issue #43). With that fixed, nothing
-  // reached the default, so it is declared rather than defaulted: a new
-  // Val that forgets `canon` is now a compile error instead of silently
-  // canoning as nothing.
   abstract get canon(): string
 
 
@@ -550,7 +396,6 @@ abstract class Val {
       ...Object.entries(this.mark).filter(n => n[1]).map(n => n[0]).sort()
     ].filter(n => null != n).join(','))
 
-    // let insp = this.inspection(inspect)
     let insp = this.inspection(1 + d)
     if (null != insp && '' != insp) {
       s.push('/' + insp)
@@ -587,16 +432,11 @@ abstract class Val {
 }
 
 
-// Prototype-level defaults for Val's type-discriminator flags.
-// Keeping these on the prototype (instead of per-instance class-field
-// initializers) removes ~35 property writes from every Val construction
-// and eliminates the corresponding hidden-class transitions. Subclasses
-// override only the flags that differ, via their own class-field
-// initializers (e.g. `MapVal.isMap = true`).
 Object.assign(Val.prototype, {
   isVal: true,
 
   isTop: false,
+  isAbsent: false,
   isNil: false,
   isNull: false,
   isMap: false,
@@ -639,22 +479,6 @@ Object.assign(Val.prototype, {
 })
 
 
-// THE INSTANCE PATH NORMALISATION (ADR-005), the TS mirror of the Go
-// port's setPaths (go/clone.go): assign every value in a freshly
-// instantiated template the path the PARSER would have given it at the
-// instance's destination. A deep instance clone (`dup`) copies values
-// whose stored parse paths are argument-shaped — a func argument has
-// no key of its own, a spread template lives under a '&' segment — and
-// Val.clone's ctx-cut cannot rebase those: it derives the child path
-// from the driving ctx alone and drops the segments in between, which
-// is how a nested list spread inside a close()d template lost its
-// parent key and every finding under it named the wrong path (the
-// 06-k8s use case's env findings). One canonical walk instead:
-// bag children descend by key (numeric for a list element, as the
-// parser records them), a spread constraint sits under '&' with its
-// content at the bag's own path, and junction members, operator
-// operands, function arguments and a preference's value all sit AT
-// their holder's path — exactly the parse-time shape.
 function repathInstance(v: any, path: string[]): void {
   if (true !== v?.isVal) {
     return
@@ -666,9 +490,6 @@ function repathInstance(v: any, path: string[]): void {
   if (true === v.isBag) {
     const spread = v.spread?.cj
     if (null != spread && true === spread.isVal) {
-      // The spread's CONTENT is pathed at the bag (its fields land on
-      // the bag's children); only its ROOT carries the '&' segment —
-      // the same two steps as the Go twin's setPaths.
       repathInstance(spread, path)
       spread.path = [...path, '&']
     }
@@ -704,7 +525,7 @@ function inspectpeg(peg: any, d: number) {
       '\n' + indent + ']') :
     ('{' +
       Object.entries(peg).map((n: any) =>
-        '\n  ' + indent + n[0] + ': ' + // n[1].inspect(d)
+        '\n  ' + indent + n[0] + ': ' +
         n[1].inspect(d)
       ).join(',') +
       '\n' + indent + '}')
@@ -720,16 +541,6 @@ function pretty(s: string) {
 }
 
 
-// THE STABLE IDENTITY OF A SPREAD TEMPLATE, across clones. Every Val
-// takes a fresh `id` when it is constructed, so the bag loops'
-// apply-once mark -- which records WHICH template has already been
-// merged into a value -- could never match after a clone: a reference
-// resolving to a templated bag clones the bag AND its template, and the
-// fresh template's id matched nothing, so the template was applied a
-// second time over the value the first application had produced
-// (use-cases/BUGS.md §50). The first call fixes the identity to the
-// original's own id; Val.clone carries `_sid`, so every clone of that
-// template answers with it.
 function spreadId(cj: any): number {
   return cj._sid ?? (cj._sid = cj.id)
 }

package/src/val/VarVal.ts

@@ -1,7 +1,6 @@
 /* Copyright (c) 2021-2023 Richard Rodger, MIT License */
 
 
-
 import type {
   Val,
   ValSpec,
@@ -22,7 +21,6 @@ import {
 } from '../ctx'
 
 
-
 import { StringVal } from './StringVal'
 import { FeatureVal } from './FeatureVal'
 import { NullVal } from './NullVal'
@@ -43,8 +41,6 @@ import { unite } from '../unify'
 import { top } from './top'
 
 
-// TODO: KEY, SELF, PARENT are reserved names - error
-
 class VarVal extends FeatureVal {
   isVar = true
 
@@ -64,8 +60,6 @@ class VarVal extends FeatureVal {
     let nameVal
 
     if (this.peg.isVal) {
-      // $.a.b.c - convert path to absolute
-      // if (this.peg instanceof RefVal) {
       if (this.peg.isRef) {
         this.peg.absolute = true
         nameVal = this.peg
@@ -80,16 +74,13 @@ class VarVal extends FeatureVal {
       }
     }
     else {
-      // TODO: how to pass row+col?
       nameVal = new StringVal({ peg: '' + this.peg }, ctx)
     }
 
-    // if (!(nameVal instanceof RefVal) && DONE === nameVal.dc) {
     if (!(nameVal.isRef) && DONE === nameVal.dc) {
       if (nameVal instanceof StringVal) {
         let found = ctx.vars[nameVal.peg]
 
-        // TODO: support complex values
         const ft = typeof found
         // Single ladder: a missing var must report `unknown_var` and not
         // fall through to the `invalid_var_kind` default below.
@@ -122,10 +113,6 @@ class VarVal extends FeatureVal {
           out = makeNilErr(ctx, 'invalid_var_kind', this, peer)
         }
 
-        // A non-TOP peer (e.g. a spread constraint unified against the
-        // var) applies to the RESOLVED value rather than being silently
-        // dropped (mirrors VarVal.Unify in go/varval — the resolved
-        // value unites with the peer).
         if (!out.isNil && null != peer && !peer.isTop) {
           out = unite(te ? ctx.clone({ explain: ec(te, 'VAL') }) : ctx,
             out, peer, 'var-val')
@@ -170,7 +157,6 @@ class VarVal extends FeatureVal {
       undefined
     )
 
-    // TODO: refactor to use Site
     nil.path = this.path
     nil.site.url = this.site.url
     nil.site.row = this.site.row
@@ -179,7 +165,6 @@ class VarVal extends FeatureVal {
     descErr(nil, ctx)
 
     if (ctx) {
-      // ctx.err.push(nil)
       ctx.adderr(nil)
     }
     else {