aontu 0.62.0 → 0.63.0

package/src/val/PathVal.ts

@@ -1,28 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// FIRST-CLASS PATHS (docs/design/PATHS.0.md). A PathVal is the value
-// `path(p)` captures: a tree address as DATA -- the spelling, never
-// the resolution. It is a scalar whose peg is the address string in
-// exactly the grammar `refer` reads (`$.a.b` from the root, `.b` from
-// the sibling scope, one more leading dot per parent step), which is
-// what lets a captured path meet the checking machinery unchanged.
-//
-// Meets are SYNTACTIC, by the PREFIX rule (amended, ADR-016): two
-// path values meet when one spells a prefix of the other -- same
-// anchor, the shorter's segments opening the longer's -- and the
-// result is the LONGER: a path can always be told more precisely.
-// Incomparable spellings refuse as any two unequal scalars do.
-// Resolving during a meet would make the meet depend on the value's
-// position, which is the property the staging machinery exists to
-// quarantine -- resolution stays the business of `refer`, `rel` and
-// the graph.
-//
-// The kind sits UNDER string (ScalarKindVal.KIND_PARENT), so `string`
-// admits a path value and the string constraints keep working; a
-// plain string LITERAL and a path value refuse each other, exactly as
-// the number tower's leaves do. A bare string is NEVER a path
-// (ADR-016): `path("...")` -- the call's own string argument -- is
-// the one conversion the language has.
 
 import type {
   Val,
@@ -41,10 +18,6 @@ import { ScalarVal } from './ScalarVal'
 import { ScalarKindVal, Path } from './ScalarKindVal'
 
 
-
-// A segment of a tree path: a map key or a list index. The same
-// grammar the rest of the engine spells keys with, and a leading digit
-// is legitimate because a list index is one.
 const ADDR_SEGMENT = /^[A-Za-z0-9_-]+$/
 
 export type Address = {
@@ -58,12 +31,6 @@ export type Address = {
 }
 
 
-// The address a string spells, or undefined when it does not spell
-// one. An address is a TREE PATH, in exactly the two spellings a
-// reference uses: `$.services.auth` from the root, `.auth` from the
-// link's own sibling scope. The tree is the only namespace -- which is
-// what makes a model instantiable more than once, each instance
-// resolving its relative links inside itself (ADR-014).
 export function parseAddress(s: string): Address | undefined {
   if ('$' === s) {
     // The whole document is not a relation's target: an address must
@@ -104,29 +71,11 @@ export function parseAddress(s: string): Address | undefined {
 }
 
 
-// The spelling string TEXT converts by, inside a `path(...)` call:
-// text that carries no anchor is RELATIVE (`"a.b"` is the address
-// `.a.b`), matching the raw form (`path(a.b)` captures `.a.b`). Only
-// the anchor is supplied -- the result still has to parse, so
-// malformed text (`""`, `"a..b"`, a bad `$` spelling) refuses as
-// before. The prefix is not applied to text that claims an anchor:
-// `"$x"` is a broken absolute address, not a relative one.
 export function textAddress(s: string): string {
   return ('$' === s[0] || '.' === s[0]) ? s : '.' + s
 }
 
 
-// The LONGER of two addresses when one spells a prefix of the other
-// (docs/design/PATHS.0.md, amended): same anchor -- absolute or the
-// same number of parent steps -- and the shorter's segments open the
-// longer's. The meet of two path values, and of a refer's address
-// with a later path peer: a path can always be told more precisely,
-// and the more precise spelling is the result. Undefined when the two
-// are not comparable, which refuses as any two unequal scalars do.
-// Both arguments must already be valid addresses: every caller hands
-// over a PathVal peg or a refer addrsrc, and both are validated at
-// capture or conversion -- the same trust `unify`'s own address arm
-// extends (`parseAddress(p.peg) as Address`).
 export function prefixMeet(a: string, b: string): string | undefined {
   const pa = parseAddress(a) as Address
   const pb = parseAddress(b) as Address
@@ -144,7 +93,6 @@ export function prefixMeet(a: string, b: string): string | undefined {
 }
 
 
-
 class PathVal extends ScalarVal {
   isPath = true
 
@@ -155,11 +103,6 @@ class PathVal extends ScalarVal {
     super({ peg: spec.peg, kind: Path }, ctx)
   }
 
-  // Two path values meet by the PREFIX rule (ADR-016): the longer
-  // when one opens the other, refusal otherwise. Exactly equal pegs
-  // are absorbed by unite's fast path before this runs, so the arm
-  // sees the unequal pairs; the winner carries both sides' marks, as
-  // the equal-scalar arm has always ratcheted them.
   unify(peer: Val, ctx: AontuContext): Val {
     const p: any = peer
     if (true === p.isPath) {
@@ -182,10 +125,6 @@ class PathVal extends ScalarVal {
     return 'path(' + this.peg + ')'
   }
 
-  // The super() ladder lifts a path value to its own kind, and the
-  // kind must render as `path()` -- the bare word `path` is an
-  // ordinary string. ScalarVal.superior would mint the plain
-  // ScalarKindVal, whose canon is the bare word.
   superior() {
     return this.place(new PathKindVal({}))
   }
@@ -193,11 +132,6 @@ class PathVal extends ScalarVal {
 } /* node:coverage ignore next 4 */
 
 
-// The path KIND, `path()`: admits every path value and defaults to
-// nothing, as `string` does. It does NOT promote (ADR-016): a bare
-// string meeting the kind refuses through the generic kind ladder,
-// exactly as `integer & "x"` does -- `path("...")` is the one string
-// conversion, and it happens at the call.
 class PathKindVal extends ScalarKindVal {
   isPathKind = true
 

package/src/val/PlaceVal.ts

@@ -1,25 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE PLACEHOLDER `_` (G8 phase 3,
-// docs/capability-review/g8-generation.md): a HOLE in a call, filled
-// by whatever the call is unified with.
-//
-//   x: {&: {m: _ + 2}}   x: a: m: 1     ->  a: m: 3
-//   greeting: upper(_) & hello          ->  "HELLO"
-//
-// WHY A HOLE AND NOT A FUNCTION PARAMETER. Aontu has no user-defined
-// functions and will not get them (G8's Boundary): a function value
-// crossing into the data plane is the step that makes a configuration
-// language a programming language. A hole is not a parameter -- it
-// cannot be named, passed, or partially applied. It says only "the
-// value that arrives here", which is what a template needs to compute
-// from the value it lands on.
-//
-// ALONE, `_` IS TOP WITH A MARK: it admits everything and is filled by
-// its peer, exactly as TOP is dropped by one. What makes it different
-// is that a CALL can see it, and a call that holds one waits for a
-// peer to fill it instead of resolving around it. Unfilled at
-// generation it is an error, as TOP is -- a hole is not a value.
 
 import type {
   Val,
@@ -72,17 +52,6 @@ class PlaceVal extends ValBase {
 }
 
 
-// A HOLE BELONGS TO ITS NEAREST ENCLOSING GENERATOR. A `_` inside a
-// generator's template (pack/each, arg 1), condition (filter, arg 1)
-// or rule table (emit, arg 1) is that generator's to bind — "_ is the
-// source child" — so neither the hole test nor the fill walk may cross
-// into those arguments from outside. Before this boundary, `close(pack(d, _ & t))` reported a
-// hole to the OUTER call, so an ordinary overlay statement was
-// absorbed into the template instead of merging with the generated
-// child (use-cases/BUGS.md §10), and an outer pack's fill pass
-// captured a NESTED pack's hole lexically, binding it to the outer
-// source (§34). The data argument (arg 0) is not a binding position,
-// so it stays visible: a hole there is an outer hole as before.
 function boundArgStart(v: any): number {
   return true === v.isPackFunc || true === v.isEachFunc ||
     true === v.isFilterFunc || true === v.isEmitFunc ||
@@ -90,10 +59,6 @@ function boundArgStart(v: any): number {
 }
 
 
-// Does this value CONTAIN a hole? Asked of a call before it resolves:
-// a call holding one must wait for a peer to fill it. Holes inside a
-// generator's own binding arguments are NOT this value's holes — see
-// boundArgStart above.
 function hasPlace(v: Val): boolean {
   if (true === (v as any).isPlace) {
     return true
@@ -125,18 +90,8 @@ function hasPlace(v: Val): boolean {
 }
 
 
-// The same tree with every hole filled by `fill`. Answers the value
-// UNCHANGED when it holds no hole, so a caller can test identity to
-// know whether anything was filled -- and so a tree with no hole is
-// never needlessly cloned. A nested generator's binding arguments are
-// left untouched (boundArgStart): those holes are the inner
-// generator's to fill with its OWN source children when it fires.
 function fillPlace(v: Val, fill: Val, ctx: AontuContext): Val {
   if (true === (v as any).isPlace) {
-    // A FILL IS A POSITION. The hole knows where it sits in the
-    // instance; the datum arriving in it does not, and inserted as it
-    // stands it keeps the paths it had at its SOURCE, so every finding
-    // under it names a path that does not exist.
     return fill.clone(ctx, { path: [...(v as any).path] })
   }
 

package/src/val/PlusOpVal.ts

@@ -18,6 +18,7 @@ import { IntegerVal } from '../val/IntegerVal'
 import { NumberVal } from '../val/NumberVal'
 import { StringVal } from '../val/StringVal'
 import { BooleanVal } from '../val/BooleanVal'
+import { ListVal } from '../val/ListVal'
 import { BigIntegerVal } from '../val/BigIntegerVal'
 import { BigDecimalVal } from '../val/BigDecimalVal'
 import { Decimal, decimalOverBudget } from '../val/Decimal'
@@ -33,20 +34,6 @@ type OpKind =
   'string' | 'boolean' | 'integer' | 'float' | 'biginteger' | 'bigdecimal'
 
 
-// D6 -- THE EXACT LADDER: integer < biginteger < bigdecimal. A mixed
-// operation between exact leaves promotes to the WIDEST operand and is
-// computed exactly, so `1 + 0d2` is a biginteger and `1 + 0d0.5` a
-// bigdecimal.
-//
-// `float` is deliberately absent: it is OFF the ladder, keeping only its
-// classic contagion against `integer`. Its absence from this table is
-// what makes the float-with-big pairs fall through to the hard error
-// below rather than promoting.
-//
-// Results NEVER demote: `0d5 + -0d2` stays a biginteger even though 3
-// would fit an int64. Demotion would make the result kind depend on the
-// values rather than on the operand kinds, and a document could then
-// change leaf under a value edit.
 const EXACT_RANK: Record<string, number> = {
   integer: 1,
   biginteger: 2,
@@ -59,13 +46,6 @@ function isBig(k: OpKind): boolean {
 }
 
 
-// Only concrete scalar operands are valid: anything else (kinds, maps,
-// lists, null, top, funcs) must not coerce — the JS `+` would leak
-// internals like "[object Object]" into output. A non-scalar operand
-// leaves the op unresolved, which generate() reports.
-//
-// A pref operand contributes its preferred value (`pref(1)+2`), and
-// therefore that value's kind too.
 function operand(v: any) {
   while (v?.isPref) {
     v = v.peg
@@ -99,14 +79,6 @@ function opkind(v: any): OpKind | undefined {
 }
 
 
-// THE TEXT `+` WOULD MAKE OF THIS OPERAND, or undefined if `+` would not
-// take it at all.
-//
-// `join` folds with `+` seeded with `""`, so every member goes through
-// concatenation's string branch — and this is the function that branch
-// calls. Exported so that the fold and the operator cannot drift into
-// two answers to "how does a number become text": there is one
-// rendering, `digits` below, and both reach it here.
 function plusText(v: Val): string | undefined {
   const o: any = operand(v)
   const k = opkind(o)
@@ -134,9 +106,25 @@ class PlusOpVal extends OpBaseVal {
   }
 
 
-  operate(ctx: AontuContext, args: Val[]) {
+  operate(ctx: AontuContext, args: Val[]): Val | undefined {
     const av: any = operand(args[0])
     const bv: any = operand(args[1])
+
+    // ABSENCE PROPAGATES (ADR-034).
+    if (true === av?.isAbsent) {
+      return av
+    }
+    if (true === bv?.isAbsent) {
+      return bv
+    }
+
+    // Lists concatenate (ADR-037).
+    if (true === av?.isList && true === bv?.isList) {
+      const peg: Val[] = [...av.peg, ...bv.peg].map(
+        (v: Val, i: number) => v.clone(ctx.descend(String(i))))
+      return new ListVal({ peg }, ctx)
+    }
+
     const ak = opkind(av)
     const bk = opkind(bv)
 
@@ -148,12 +136,6 @@ class PlusOpVal extends OpBaseVal {
       return new BooleanVal({ peg: av.peg || bv.peg })
     }
 
-    // STRING CONCATENATION RENDERS DIGITS, NOT KIND DECORATION. The `0d`
-    // marker is canon's way of naming the leaf and never belongs in a
-    // string, exactly as R4's `.0` float suffix does not ("q" + 0d0.1 is
-    // "q0.1", and "q" + 1.0 is "q1"). Decimal.toString() is that
-    // marker-free rendering, which is why canon() wraps it rather than
-    // the other way round.
     if ('string' === ak || 'string' === bk) {
       return new StringVal({ peg: digits(av, ak) + digits(bv, bk) })
     }
@@ -163,25 +145,11 @@ class PlusOpVal extends OpBaseVal {
       return undefined
     }
 
-    // FLOAT IS OFF THE EXACT LADDER, and mixing it with either big leaf
-    // is a hard error in BOTH operand orders: a big type never silently
-    // becomes a binary float. Promotion the other way is no better —
-    // binary64 cannot hold every exact value, so either direction throws
-    // away exactness the document explicitly asked for by writing `0d`.
-    // The error names both leaves in operand order.
     if (('float' === ak && isBig(bk)) || (isBig(ak) && 'float' === bk)) {
       return makeNilErr(ctx, 'exact_float_mix', this, undefined, 'add',
         { left: ak, right: bk })
     }
 
-    // Float with float or integer: unchanged R5 contagion, binary64
-    // addition, float result (`1 + 2.0` is `3.0`) -- but a sum that
-    // leaves binary64's finite range is NOT a value. Aontu is a JSON
-    // superset and there is no notation for an infinity, so one here
-    // used to escape as `[aontu/internal]` in TypeScript and as Go's
-    // raw `json: unsupported value: +Inf` with no code at all
-    // (use-cases/BUGS.md 39). The same check governs the arithmetic
-    // family (float_overflow, ts/src/val/arith.ts).
     if ('float' === ak || 'float' === bk) {
       const sum = av.peg + bv.peg
       return Number.isFinite(sum) ?
@@ -211,13 +179,6 @@ class PlusOpVal extends OpBaseVal {
       return new BigIntegerVal({ peg: sum })
     }
 
-    // INTEGER + INTEGER IS COMPUTED EXACTLY, then offered to the integer
-    // leaf under the same storage contract R1 applies to a literal.
-    // Adding through float64 (as this did) silently rounded sums of
-    // exact operands — 4503599627370496 + 4503599627370497 came back as
-    // …992 — which is precisely the corruption the tower refuses. The
-    // sum that will not fit is an error pointing at `0d`, not a rounded
-    // answer.
     return isIntegerStorable(sum) ?
       new IntegerVal({ peg: Number(sum) }) :
       makeNilErr(ctx, 'inexact_integer_sum', this, undefined, 'add',
@@ -232,19 +193,6 @@ class PlusOpVal extends OpBaseVal {
 }
 
 
-// The digits of an operand for string concatenation: no `0d` marker, no
-// R4 `.0` suffix — the plain rendering of the number, in every leaf.
-//
-// INTEGER KIND GOES THROUGH integerDigits. This was the THIRD site to
-// render an integer-kind peg with JavaScript's shortest round-tripping
-// form, so `"" + 1152921504606846976` produced "1152921504606847000" — a
-// different integer — where Go produced the exact digits. See #21 and
-// integerDigits, which exists so the set of such sites is greppable.
-//
-// The other leaves are already exact or already correct: a bigint
-// stringifies to its exact digits, a Decimal renders its own, and a FLOAT
-// must keep String() because its shortest form is the right answer and is
-// what Go prints too (`"a" + 1.0` is "a1").
 function digits(v: any, k: OpKind): string {
   return 'bigdecimal' === k ? v.peg.toString() :
     'integer' === k ? integerDigits(v.peg) :
@@ -252,16 +200,11 @@ function digits(v: any, k: OpKind): string {
 }
 
 
-// An exact-ladder operand as an exact integer. Only reached for the two
-// integral leaves; an `integer` peg is integral by construction, so
-// BigInt() is exact.
 function integer(v: any, k: OpKind): bigint {
   return 'biginteger' === k ? v.peg : BigInt(v.peg)
 }
 
 
-// An exact-ladder operand as a Decimal, for the promotion to bigdecimal.
-// Scale 0 normalises to the one decimal place the leaf keeps.
 function decimal(v: any, k: OpKind): Decimal {
   return 'bigdecimal' === k ? v.peg : new Decimal(integer(v, k), 0)
 } /* node:coverage ignore next 6 */

package/src/val/PrefFuncVal.ts

@@ -49,7 +49,6 @@ class PrefFuncVal extends FuncBaseVal {
       // Wrap every child val in a PrefVal
       out = walk(out, (_key: string | number | undefined, val: Val) => {
         let oval = val
-        // console.log('PREFVAL', _key, oval.canon, oval.constructor.name)
         if (
           val.isScalar
           || val.isPref

package/src/val/PrefVal.ts

@@ -27,11 +27,6 @@ import { trialUnify } from './FuncBaseVal'
 import { superOf } from './SuperFuncVal'
 
 
-// The innermost preferred value under every pref layer: the value a
-// preference of ANY rank ultimately defends, and the one generation
-// emits for it. Shared by the disjunct admission gate (DisjunctVal),
-// the defaulted-scrutinee rule (MatchFuncVal) and the effective-default
-// walk (subsume.ts) so "the default's value" cannot mean three things.
 function prefInnerPeg(v: Val): Val {
   let out: any = v
   while (true === out?.isPref) {
@@ -41,65 +36,16 @@ function prefInnerPeg(v: Val): Val {
 }
 
 
-// A CONTAINER DEFAULT IS LEAFWISE (ADR-011 R3,
-// docs/design/DEFAULTS.0.md): `*{p:1}` MEANS `{p: *1}` and `*[1]`
-// means `[*1]`, so there is no such thing as a preference whose
-// preferred value is a bag. Shape is not a value and takes no star --
-// key optionality, closedness and a `&:` spread template ride through
-// untouched; only the values a reader could override are defaulted.
-//
-// This is the rule `pref()` already had (its resolve walked and
-// wrapped every scalar child) and the star prefix did not, so the two
-// spellings of one operator disagreed: `pref({p:1}) & {q:2}` kept the
-// `p` default and `*{p:1} & {q:2}` dropped it. Both spellings and the
-// resolve-time case (`*$.shape`) come through here now, so they
-// cannot drift apart again. Wrapping the non-bag arm rather than
-// walking for scalars also closes the other half of that gap:
-// `pref(integer)` and `pref(min(3))` used to answer the bare value,
-// losing the preference outright.
 class PrefVal extends FeatureVal {
   isPref = true
   isGenable = true
   cjo = 30000
 
-  // The preferred value's own type: the yardstick for "did the peer say
-  // anything I did not already say?". A peer that resolves to this (or
-  // to the family gate below) leaves the preference standing.
-  // Both are assigned by resuper(), called from the constructor.
   superpeg!: Val
 
-  // THE GATE AN OVERRIDING PEER MUST PASS IS `superpeg` ITSELF — the
-  // preferred value's own KIND, not its family.
-  //
-  // A preference is a DEFAULT, so a concrete peer replaces it, but only
-  // where the peer is the same kind of thing: `*lower(1.1) & a` is a
-  // conflict, not an override. The number tower made `integer` and
-  // `float` disjoint siblings under `number`, and this gate used to
-  // widen to that family — so `*2.2 & 3` worked, and so did
-  // `*8080 & 3.5`. Those are ONE rule in two directions; no kind-based
-  // gate can keep the first and refuse the second.
-  //
-  // Refusing both is the choice, because the second is the documented
-  // default idiom: `port: *8080 | integer` accepted 3.5 in both ports,
-  // silently widening every key written that way from integer to
-  // number — the finding §6 of the 2026-08-21 status report calls the
-  // most consequential, precisely because docs/skill/examples.md
-  // teaches the idiom to agents.
-  //
-  // What the tightening costs is named rather than hidden: mixing the
-  // numeric leaves around a preference is now an error instead of a
-  // silent widening. `*1.5 & integer` used to answer `integer` and
-  // DISCARD a default that could never apply; it now says so.
 
   rank: number = 0
 
-  // THE OVERRIDE SPACE, NARROWED (ADR-011 R1). The second arm of the
-  // distribution -- `super(x) & every peer met so far` -- kept here as
-  // well as in `superpeg`, because resuper() recomputes the gate from
-  // the peg whenever the peg resolves and would otherwise widen it
-  // back to `super(x)`: a rank>=2 default, whose peg is itself a
-  // preference and so is re-driven, lost its narrowing that way and
-  // let a pinned `***false & false` be overridden by `true`.
   narrowed?: Val
 
   constructor(
@@ -107,45 +53,17 @@ class PrefVal extends FeatureVal {
     ctx?: AontuContext
   ) {
     super(spec, ctx)
-    // this.pref = spec.pref || spec.peg
 
-    // this.superpeg = makeSuper(spec.peg)
 
     if (spec.peg instanceof PrefVal) {
       this.rank = 1 + spec.peg.rank
     }
 
     this.resuper(ctx)
-    // console.log('PVC', this.peg.canon, this.superpeg.canon)
   }
 
 
-  // Recompute the type yardstick and the override gate from the current
-  // peg. Called again whenever the peg resolves (e.g. a ref).
-  //
-  // THE GATE IS super() (ADR-011 R4, docs/design/DEFAULTS.0.md). `*x`
-  // is sugar for `*x | super(x)`, so the type an overriding peer must
-  // pass is the one the long form spells out loud -- one function, not
-  // a second implementation that agrees with it on the common case.
-  // Two special cases retired with the switch: a KIND peg gated
-  // nothing (`*integer` was overridden by `"s"`) and a CONSTRAINT peg
-  // had no gate at all, both written when a kind's superior was top.
-  // `super(integer)` is `number`, so `7` still wins and `"s"` refuses.
   private resuper(ctx?: AontuContext) {
-    // THE RANK-UNIFORM MEET (ADR-004). The yardstick is the INNERMOST
-    // preferred value's kind, whatever the preference's rank: `**1.5`
-    // defends `float` exactly as `*1.5` does. The old rule read the
-    // immediate peg, and a rank>=2 peg is itself a PrefVal whose
-    // superior is top -- so ANY conjunct overrode a ranked default
-    // (`**1.5 & float` dropped the default and died as mapval_no_gen;
-    // `**2|integer` met by a bare `integer` lost the default the
-    // spelling exists to carry -- use-cases/BUGS.md §3), while the
-    // rank-1 spelling of the same document kept it. One rule, every
-    // rank. Pinned by test/spec/pref.tsv (pref-rank2-* rows, and the
-    // flipped pref-nested-concrete-wins).
-    // THE RANK-UNIFORM MEET (ADR-004) is unchanged: the yardstick is
-    // the INNERMOST preferred value, whatever the rank, so `**1.5`
-    // defends `float` exactly as `*1.5` does.
     let peg: any = this.peg
     while (true === peg?.isPref) {
       peg = peg.peg
@@ -161,14 +79,6 @@ class PrefVal extends FeatureVal {
   }
 
 
-  // The default, standing but NARROWED: `*integer & 7` is `*7`, which
-  // is what the long form answers (`(integer&7) | (number&7)` keeps
-  // the star on the arm that survived). The rank rides across -- a
-  // ladder rung that narrows is still that rung.
-  // The rank is REBUILT as nesting rather than stamped: canon renders
-  // one star per layer (`'*' + peg.canon`), so a rank set directly on
-  // a single layer would print `*x` for a rank-2 default and the
-  // document would no longer round-trip.
   private restand(met: Val, ctx: AontuContext): Val {
     let out: Val = met
     for (let rI = 0; rI <= this.rank; rI++) {
@@ -190,28 +100,10 @@ class PrefVal extends FeatureVal {
     if (!this.peg.done) {
       const resolved = unite(te ? ctx.clone({ explain: ec(te, 'RES') }) : ctx,
         this.peg, top(), 'pref/resolve')
-      // console.log('PREF-RESOLVED', this.peg.canon, '->', resolved)
       this.peg = resolved
       this.resuper(ctx)
     }
 
-    // A CONTAINER DEFAULT IS LEAFWISE IN EFFECT (ADR-011 R3), and it
-    // gets there through the meet above rather than through a rewrite.
-    // `*{p:1}` keeps its written shape -- canon prints `*{"p":1}` and
-    // reparses to itself, which a rewrite to `{p:*1}` would break, and
-    // an alternative still has a star for a disjunction to choose by.
-    // What makes it leafwise is that the two arms decide:
-    //
-    //   `& {q:2}`  the preferred value ITSELF admits the peer (maps
-    //              merge), so the default stands as `*{p:1,q:2}` and
-    //              `p` survives -- it used to be REPLACED outright.
-    //   `& {p:2}`  the preferred value refuses, so the gate answers:
-    //              `super({p:1})` is `{p:integer}`, which admits it.
-    //   `& "s"`    both arms are empty, so the whole default is --
-    //              a string used to override a map default silently.
-    //
-    // Which is every rule R3 asks for, with no bag ever standing where
-    // the author wrote a scalar and no canon that fails to round-trip.
 
     if (peer instanceof PrefVal) {
       why += 'pref-'
@@ -235,74 +127,22 @@ class PrefVal extends FeatureVal {
         why += 'rank-lose'
       }
       else {
-        // console.log('PREF-PEER',
-        //   this.peg.id, this.peg, this.peg.done,
-        //   peer.peg.id, peer.peg, peer.peg.done,
-        // )
 
         const peg = trialUnify(ctx, prefInnerPeg(this).clone(ctx),
           prefInnerPeg(peer))
 
-        // TWO DEFAULTS OF EQUAL RANK THAT CANNOT AGREE (ADR-011 R2):
-        // the refusal is about the DEFAULTS, not about the values they
-        // happen to hold, and its hint names the fix -- rank one of
-        // them. Compatible pegs still fold (`*1 & *integer` is `*1`),
-        // and identical ones collapse, so only a real disagreement
-        // reaches this arm. The three spellings of it -- `*1 & *7`,
-        // `(*1|integer) & *7` and `*1|*7` -- used to answer a value
-        // conflict, the newcomer, and the newcomer again.
         out = undefined === peg
           ? makeNilErr(ctx, 'pref_rank_clash', this, peer, 'unify')
           : this.restand(peg, ctx)
-        // console.log('PREF-RANK-SAME-OUT', peg, peg.done, out, out.done)
         why += 'rank-same'
       }
     }
     else if (!peer.isTop) {
       why += 'super-'
 
-      // THE MEET IS THE DESUGARING, DISTRIBUTED (ADR-011 R1,
-      // docs/design/DEFAULTS.0.md). `*x` stands for `*x | super(x)`,
-      // and a peer meets a disjunction arm by arm:
-      //
-      //     (x & peer)  |  (super(x) & peer)
-      //
-      // THE FIRST ARM DECIDES. When the preferred value itself still
-      // satisfies the peer the default STANDS -- `*1 & integer`,
-      // `*8080 & min(1024)`, `**2 & neq(1)`: the peer narrowed the
-      // type without ruling the default out, which is the whole point
-      // of writing one. Only when that arm is empty does the second
-      // answer, and that is the override. When BOTH are empty nothing
-      // remains of the disjunction the star stands for -- `empty`,
-      // the same refusal the written-out long form gives.
-      //
-      // The old rule asked instead whether the peer resolved to
-      // exactly `super(x)`, so any narrowing at all counted as an
-      // override: `*1 & integer` stood (the peer WAS the gate) but
-      // `*8080 & min(1024)` silently dropped the default and answered
-      // the bare constraint, and a rank ladder lost its weaker arm to
-      // the same rule the moment anything narrowed it.
-      //
-      // Trialled against a CLONE, on the innermost value (the
-      // rank-uniform meet): the preferred value must stay pristine for
-      // the arm that stands, and a failed trial must not leave its
-      // errors on the context -- the DisjunctVal admission gate's own
-      // precedent, and its mechanism.
       const met = trialUnify(ctx, prefInnerPeg(this).clone(ctx), peer)
 
       if (undefined !== met) {
-        // THE SECOND ARM IS CARRIED FORWARD, not discarded. It is the
-        // override space -- everything the peer would still admit
-        // INSTEAD of the default -- and meeting a peer narrows it just
-        // as it narrows the default: two successive meets compose to
-        // `(x & p1 & p2) | (super(x) & p1 & p2)`, which is the
-        // distribution over both. Dropping it let a constraint that
-        // arrived beside a default vanish: `r:*2` with `r:max(20)`
-        // stood as a bare `*2`, and `r:40` then overrode it through a
-        // gate that no longer remembered the bound.
-        //
-        // It cannot fail: the first arm succeeded, so `x & peer` has a
-        // value, and that value satisfies `super(x)` and `peer` both.
         const gate = unite(te ? ctx.clone({ explain: ec(te, 'GATE') }) : ctx,
           this.superpeg.clone(ctx), peer, 'pref-gate/' + this.id)
 
@@ -338,7 +178,6 @@ class PrefVal extends FeatureVal {
           : makeNilErr(ctx, 'empty', this, peer, 'unify')
 
 
-
       // }
     }
     else {
@@ -349,7 +188,6 @@ class PrefVal extends FeatureVal {
     // superior-unify (mirrored by PrefVal.Unify in go/pref.go).
     out.dc = DONE
 
-    // console.log('PREFVAL-OUT', why, this.canon, peer.canon, '->', out.canon, out.done)
 
     ctx.explain && explainClose(te, out)
 
@@ -372,27 +210,10 @@ class PrefVal extends FeatureVal {
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     let out = (super.clone(ctx, spec) as PrefVal)
 
-    // THE NARROWED OVERRIDE SPACE TRAVELS WITH THE COPY (ADR-011 R1).
-    // A default a meet has pinned stays pinned through a reference:
-    // without this, `T:{e:***false & false}` copied by `f:$.T` handed
-    // back a default whose gate had widened again to `boolean`, and
-    // `f:{e:true}` overrode a value the author had pinned. The Go
-    // twin carries the same two fields explicitly (clone.go).
     if (null != this.narrowed) {
       out.narrowed = this.narrowed
       out.superpeg = this.superpeg
     }
-    // THE PER-DESTINATION INSTANTIATION RULE (ADR-005). The default
-    // clone shares the preferred value (`peg: this.peg` in Val.clone)
-    // — a cloned pref spread template resolves its inner value at the
-    // template's own location, pinned behaviour. But a template
-    // INSTANCE must own it: with the peg shared, a rank-2 default
-    // (`**key(1) | string`) in a pack template resolved its one
-    // shared inner key() at the first destination and every child got
-    // the first child's key (use-cases/BUGS.md §9 — rank 1 escaped
-    // only because its unify builds a fresh PrefVal per meet). The
-    // superpeg yardstick from the shared peg still holds: the clone's
-    // innermost value is the same kind.
     if (true === spec?.dup && true === (this.peg as any)?.isVal) {
       out.peg = this.peg.clone(ctx, { dup: true })
     }