aontu 0.61.0 → 0.63.0

package/src/val/ContainerKindVal.ts

@@ -1,21 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// CONTAINER KINDS (docs/design/PATHS.0.md). `{}` and `[]` are the
-// container UNITS: they admit any map (or list) AND generate empty
-// when nothing arrives. `map()` and `list()` are the container KINDS
-// proper: they admit exactly the same values and default to NOTHING,
-// as `string` does -- the spelling of "this must be a map, and it
-// must be supplied", which the unit cannot say because an unmet unit
-// silently manufactures its empty value.
-//
-// The vacuous call is the kind; the literal is the unit. That is the
-// whole convention, and it is why neither function takes arguments:
-// element constraints already belong to the spreads (`{&: V}`,
-// `[&: V]`), and a second spelling of them here would drift.
-//
-// No null/top/nil arms, as RelVal records: unite's dispatch ladder
-// absorbs those peers before any Val's own unify is consulted, and
-// FuncBaseVal returns a done resolution directly against a top peer.
 
 import type {
   Val,
@@ -53,8 +37,6 @@ class MapKindVal extends FeatureVal {
     if (true === p.isMapKind) {
       return this
     }
-    // The unit's own refusal code: a kind mismatch here is the same
-    // fact `{} & 1` reports, and two codes for one fact would drift.
     return makeNilErr(ctx, 'map', this, peer)
   }
 

package/src/val/CopyFuncVal.ts

@@ -1,7 +1,6 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
-
 import type {
   Val,
   ValSpec,
@@ -14,7 +13,6 @@ import {
 import { makeNilErr } from '../err'
 
 
-
 import {
   walk
 } from '../utility'
@@ -58,18 +56,15 @@ class CopyFuncVal extends FuncBaseVal {
       makeNilErr(ctx, 'invalid-arg', this) :
       val.clone(ctx)
 
-    // console.log('CR', out)
 
     if (!out.isRef) {
       walk(out, (_key: string | number | undefined, val: Val) => {
-        // console.log('WALK', val)
         val.mark.type = false
         val.mark.hide = false
         return val
       })
     }
 
-    // console.log('COPY-RESOLVE', ctx.cc, val, out)
 
     return out
   }

package/src/val/Decimal.ts

@@ -1,79 +1,15 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-/*
- * The exact base-10 decimal value behind the `bigdecimal` leaf, and the
- * parser for the `0d` literal family that reaches both exact leaves.
- *
- * A Decimal is a coefficient and a scale:
- *
- *   value = unscaled / 10^scale
- *
- * with `unscaled` a native bigint and `scale` a plain integer. Every
- * operation here is EXACT: aontu's whole numeric operator surface
- * (`+`, `upper()`, `lower()`, unary minus) is exact, so no rounding
- * context, precision or rounding mode exists anywhere in this file --
- * addition aligns scales and adds coefficients, and ceiling/floor is
- * coefficient arithmetic that never lets a float64 near the value.
- * Where an exact answer will not fit the budget the answer is refused,
- * never rounded (see decimalOverBudget).
- *
- * D4 -- ONE VALUE, ONE RENDERING. In a unifier canon must be a function
- * of the value, so scale is presentation and not identity: `0d0.10`,
- * `0d0.1` and `0d1e-1` are the same lattice point and must render
- * identically. A Decimal therefore NORMALISES IN ITS CONSTRUCTOR --
- * every Decimal in existence is in minimal form, which is what makes
- * `equals` a two-field comparison and `same()` correct without any
- * pointer identity (D2).
- *
- * The minimal form keeps ONE decimal place at the bottom. `0d` names the
- * numeric FAMILY, not the leaf, so an integral bigdecimal that rendered
- * as `0d1000` would reparse as a biginteger -- a kind-flipping canon of
- * exactly the sort R4's `.0` suffix exists to prevent. So `0d1e3` canons
- * as `0d1000.0`, and scale is never reduced below 1.
- *
- * Go mirror (D8): a struct of (coeff *big.Int, scale int32) normalised
- * by the same rule -- strip trailing zeros while scale > 1, then raise
- * the scale to 1 when it is lower, zero always at scale 1.
- */
-
-
-// D6 -- THE EXACTNESS BUDGET, enforced at parse.
-//
-// Both halves are needed and the scale half is the load-bearing one: a
-// coefficient-only check never fires for `0d1e1000000000`, whose
-// coefficient is one digit, yet plain-form rendering of that value would
-// have to materialise a gigabyte of zeros (and overflow the Go port's
-// int32 scale field) without any arithmetic having occurred.
-//
-// A literal over either bound is a located error, never a rounded or
-// expanded value: this language does not round, so the only honest
-// answer at the limit is refusal.
+
 const DECIMAL_COEFFICIENT_BUDGET = 4096
 const DECIMAL_SCALE_BUDGET = 4096
 
 
-// Powers of ten as bigints, memoised: normalisation of an
-// exponent-bearing literal needs one per parse.
 function pow10(n: number): bigint {
   return 10n ** BigInt(n)
 }
 
 
-// True when a decimal's SOURCE form is over either budget bound.
-//
-// Every route that builds a Decimal from text must ask this BEFORE
-// constructing one, because normalising an over-budget value is itself
-// the resource event the bound exists to prevent: the constructor folds
-// a negative scale by multiplying the coefficient by 10^-scale, so
-// `1e1000000000` would try to build a billion-digit bigint.
-//
-// Written once and used by both routes -- the `0d` literal and the
-// exact-input API -- because the Go port bounds both (NewBigDecimal
-// shares the literal path's checker) and a TypeScript route that did not
-// would be a silent cross-port divergence as well as a hazard.
-//
-// `scale` may be Infinity or NaN when the exponent digits overflow a JS
-// number; the comparison is written so that either answers "over".
 function overBudget(coeffDigits: number, scale: number): boolean {
   return DECIMAL_COEFFICIENT_BUDGET < coeffDigits ||
     !(Math.abs(scale) <= DECIMAL_SCALE_BUDGET)
@@ -88,7 +24,6 @@ function coeffDigits(unscaled: bigint): number {
 
 
 class Decimal {
-  // value = unscaled / 10^scale, always in minimal form (see above).
   readonly unscaled: bigint
 
   // Always >= 1: an integral bigdecimal keeps one decimal place so its
@@ -100,9 +35,6 @@ class Decimal {
     let s = Math.trunc(scale)
 
     if (0n === u) {
-      // R2/D5: there is no negative zero here to begin with (a bigint
-      // has one zero), and every zero is the same lattice point, so it
-      // takes the one canonical form `0d0.0`.
       s = 1
     }
     else {
@@ -148,26 +80,11 @@ class Decimal {
   }
 
 
-  // Exact negation, keeping the leaf. -0 folds to 0 (D5) because the
-  // normalising constructor sends every zero to the same form.
   negate(): Decimal {
     return new Decimal(-this.unscaled, this.scale)
   }
 
 
-  // D6 -- EXACT ADDITION. Align the scales, add the coefficients. That
-  // is the entire algorithm: there is no rounding mode to consult and no
-  // precision to run out of, which is why `0d0.1 + 0d0.2` is exactly
-  // `0d0.3` here and 0.30000000000000004 in binary64.
-  //
-  // The work is bounded because both operands are within the parse-time
-  // budget, so alignment can inflate a coefficient only by the scale
-  // span. The RESULT, however, can be over budget even when both
-  // operands are inside it (`0d1e4000 + 0d1e-4000` needs 8001
-  // coefficient digits), so every caller must test the result with
-  // decimalOverBudget() and report `decimal_budget` rather than store
-  // it. Refusal is the only honest answer at the limit: rounding to fit
-  // is exactly what this leaf exists to prevent.
   add(peer: Decimal): Decimal {
     const scale = this.scale < peer.scale ? peer.scale : this.scale
     const a = this.unscaled * pow10(scale - this.scale)
@@ -176,34 +93,11 @@ class Decimal {
   }
 
 
-  // D6 -- EXACT MULTIPLICATION. Multiply the coefficients, ADD the
-  // scales: (a/10^s)(b/10^t) is ab/10^(s+t), with no alignment step and
-  // no rounding mode, exactly as add() has none.
-  //
-  // The result leaves the budget far more readily than a sum does --
-  // scales add rather than taking the maximum, and coefficient digits
-  // add too -- so squaring a value at half the budget is already over
-  // it. Every caller must test with decimalOverBudget() and report
-  // `decimal_budget`, for the same reason add()'s callers must: at the
-  // limit, refusing is the only answer that is not a rounded one.
   multiply(peer: Decimal): Decimal {
     return new Decimal(this.unscaled * peer.unscaled, this.scale + peer.scale)
   }
 
 
-  // Exact ceiling and floor, for `upper()`/`lower()`. Coefficient
-  // arithmetic only -- Math.ceil of this value would mean rounding it to
-  // binary64 first, which for a leaf that exists to escape binary64 is
-  // no answer at all.
-  //
-  // The leaf is kept (R5 contagion): the result is a bigdecimal whose
-  // value happens to be integral, so it keeps the one decimal place the
-  // family marker requires -- `upper(0d1.1)` is `0d2.0`, not `0d2`.
-  //
-  // Neither can leave the exactness budget: with scale >= 1 the integer
-  // part drops `scale` digits and normalisation adds one back, so the
-  // coefficient never grows. That is why these return a Decimal
-  // directly while add() makes its caller check.
   ceil(): Decimal {
     return new Decimal(this.intPart(1n), 0)
   }
@@ -214,11 +108,6 @@ class Decimal {
   }
 
 
-  // The integer part, stepped one in the direction of `dir` when a
-  // remainder of that sign was discarded. bigint division truncates
-  // toward zero and the remainder carries the dividend's sign, so
-  // truncation already IS the floor of a positive and the ceiling of a
-  // negative; only the other half of each case needs the step.
   private intPart(dir: bigint): bigint {
     const p = pow10(this.scale)
     const q = this.unscaled / p
@@ -232,11 +121,6 @@ class Decimal {
   }
 
 
-  // Plain digits, no `0d` marker: `1000.0`, `-0.1`. Plain form at every
-  // magnitude, never scientific -- the budget is what makes that safe.
-  // This is also the rendering string concatenation will want in Phase 4
-  // (`"q" + 0d0.1` is `"q0.1"`), which is why the marker lives in
-  // `canon()` and not here.
   toString(): string {
     const neg = this.unscaled < 0n
     let d = (neg ? -this.unscaled : this.unscaled).toString()
@@ -256,11 +140,6 @@ class Decimal {
   }
 
 
-  // Exact-input construction for library consumers (D8). A JS `number`
-  // argument is already rounded before this library could inspect it, so
-  // the exact leaves are reachable only from a bigint or from text.
-  // Accepts `[+-]?digits[.digits][(e|E)[+-]digits]`, with or without the
-  // `0d` marker, and no `_` separators (those are literal syntax).
   static fromString(src: string): Decimal {
     const m = /^([-+]?)(?:0[dD])?([0-9]+)(?:\.([0-9]+))?(?:[eE]([-+]?[0-9]+))?$/
       .exec(src)
@@ -271,11 +150,6 @@ class Decimal {
     const exp = null == m[4] ? 0 : Number(m[4])
     const scale = frac.length - exp
 
-    // The same bound the `0d` literal obeys (D6). Without it this API
-    // route reached the resource exhaustion the budget exists to
-    // prevent -- `fromString('1e1000000000')` would normalise by
-    // building a billion-digit coefficient -- and disagreed with the Go
-    // port, whose NewBigDecimal shares the literal path's checker.
     if (overBudget(m[2].length + frac.length, scale)) {
       throw new Error('decimal-budget: ' + src)
     }
@@ -286,63 +160,15 @@ class Decimal {
 }
 
 
-// D6 -- THE BUDGET APPLIES TO RESULTS, NOT JUST LITERALS. True when a
-// Decimal produced by arithmetic is over either bound and so must be
-// refused with `decimal_budget`.
-//
-// The test is applied to the NORMAL form -- the representation the value
-// is actually stored and rendered in -- rather than to some minimal
-// re-derived source form. That keeps the rule cheap and mechanical
-// enough for the Go port to mirror exactly (count the coefficient's
-// digits, read the scale), and it bounds precisely the thing the bound
-// exists to bound: the digits plain-form rendering will have to
-// materialise.
-//
-// One consequence is worth naming: a literal is budget-checked on its
-// SOURCE form, so an extreme literal whose normal form is wider than its
-// source (`0d1e4096` -- one written digit, 4098 normalised ones) parses
-// but cannot take part in arithmetic. Both bounds are deliberately far
-// beyond any real document, and the alternative -- re-deriving a minimal
-// form per operation -- only moves the same edge somewhere else
-// (`0d100e4096` has minimal scale -4098, over the bound its source form
-// was under), at the cost of a second normal form that both ports would
-// then have to agree on digit for digit.
 function decimalOverBudget(d: Decimal): boolean {
   return overBudget(coeffDigits(d.unscaled), d.scale)
 }
 
 
-// D3 -- THE `0d` LITERAL.
-//
-//   0[dD] digits [ . digits ] [ (e|E) [+-] digits ]
-//
-// with single `_` separators between digits, exactly as the landed
-// separator rule allows for ordinary numbers (`[0-9](?:_?[0-9])*` admits
-// `1_000` and refuses `1__0`, `_1`, `1_`).
-//
-// LEAF BY SOURCE, mirroring R1's precedent that the source text and not
-// the value decides the kind: digits only is a biginteger, a `.` or an
-// exponent anywhere makes it a bigdecimal. So `0d5` is a biginteger and
-// `0d1e3` is a bigdecimal whose value happens to be integral.
-//
-// THE SIGN IS NOT PART OF THIS PATTERN, though it is part of the D3
-// grammar: `-0d5` is read as the existing unary-minus prefix applied to
-// `0d5` (see negative-prefix in lang.ts), exactly as `-1.5` already is.
-// Aontu's lexer runs regexp value matchers BEFORE the fixed-token
-// matcher, so a `[-+]?` here would claim the `+` of `0d1 +0d2` as a
-// literal sign and silently turn an addition into an implicit list --
-// while plain `1 +2` stayed an addition. The sign belongs to the same
-// operator for both, which is also what keeps `0d-5` rejected.
-//
-// Kept RE2-compatible (no lookaround, no backreferences) so the Go port
-// can use the byte-identical pattern.
 const BIG_LITERAL_RE =
   /^0[dD]([0-9](?:_?[0-9])*)(?:\.([0-9](?:_?[0-9])*))?(?:[eE]([-+]?[0-9](?:_?[0-9])*))?/
 
 
-// The outcome of reading a `0d` literal: one of the two exact leaves, or
-// a budget refusal. `undefined` is impossible for text the matcher above
-// claimed, and is reported as an error rather than guessed at.
 type BigLiteral =
   { leaf: 'biginteger', int: bigint } |
   { leaf: 'bigdecimal', dec: Decimal } |
@@ -354,8 +180,6 @@ function stripSep(s: string): string {
 }
 
 
-// Read a `0d` literal from the groups of BIG_LITERAL_RE:
-//   1 integer digits, 2 fraction digits, 3 exponent.
 function readBigLiteral(m: RegExpExecArray | (string | undefined)[]): BigLiteral {
   const intd = stripSep(m[1] as string)
   const fracd = null == m[2] ? undefined : stripSep(m[2])
@@ -366,18 +190,10 @@ function readBigLiteral(m: RegExpExecArray | (string | undefined)[]): BigLiteral
     return { leaf: 'biginteger', int: BigInt(intd) }
   }
 
-  // The exponent is read as a plain number on purpose: a 4000-digit
-  // exponent lands on Infinity, whose absolute value is over budget, so
-  // the refusal below fires without any bigint ever being built.
   const exp = undefined === expd ? 0 : Number(expd)
   const fracLen = undefined === fracd ? 0 : fracd.length
   const scale = fracLen - exp
 
-  // The budget is checked on the SOURCE form, before normalisation:
-  // normalising `0d1e1000000000` is itself the resource event the bound
-  // exists to prevent. Coefficient digits are counted as written
-  // (leading zeros included) so the two ports need not agree on any
-  // cleverer rule.
   if (overBudget(intd.length + fracLen, scale)) {
     return { leaf: 'error', code: 'decimal_budget' }
   }

package/src/val/DeprecateFuncVal.ts

@@ -1,15 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// The deprecation mark (G3 phase 4,
-// docs/capability-review/g3-subsumption-evolution.md): a function-form
-// builtin, `deprecate(x, m)`, that unifies EXACTLY as `x` while the
-// record `m` rides the result through meets. The record's keys are
-// msg, use and since — all optional, all strings; `use` is a path
-// spelled as a STRING, because a live reference would resolve and
-// unify, which is not wanted. Boolean ValMarks cannot hold a record,
-// so the Val carries one optional field (Val.deprecation), propagated
-// by the same channel as the marks (propagateMarks) and rendered back
-// reparseably by canon (canonRiders).
 
 import type {
   Val,

package/src/val/DisjunctVal.ts

@@ -1,7 +1,6 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
-
 import type {
   Val,
   ValSpec,
@@ -36,8 +35,6 @@ import { PrefVal, prefInnerPeg } from '../val/PrefVal'
 import { JunctionVal } from '../val/JunctionVal'
 
 
-
-// TODO: move main logic to op/disjunct
 class DisjunctVal extends JunctionVal {
   isDisjunct = true
   isGenable = true
@@ -45,7 +42,6 @@ class DisjunctVal extends JunctionVal {
 
   prefsRanked = false
 
-  // TODO: sites from normalization of orginal Disjuncts, as well as child pegs
   constructor(
     spec: {
       peg: Val[]
@@ -79,65 +75,18 @@ class DisjunctVal extends JunctionVal {
       }
     }
 
-    // // // console.log('DISJUNCT-unify-A', this.id, this.canon)
 
     let done = true
 
     let oval: Val[] = []
 
-    // Conjunction (&) distributes over disjunction (|).
-    //
-    // Each member is tried against peer in isolation: if that trial
-    // produces any errors, the member fails and is marked with a NilVal.
-    // Previously this used `ctx?.clone({err: []})` per member - a
-    // per-iteration context clone (two Object.creates) just to hold a
-    // throwaway error array. For schemas with many disjunctions
-    // (e.g. `*true | boolean`, `method: GET | PUT | ...`) this was the
-    // single largest source of clones in the unify hot path.
-    //
-    // Swap-and-restore avoids the clone: the existing ctx's err array
-    // is saved, replaced with a fresh array for each trial, then
-    // restored. ctx mutation is scoped to this loop and fully undone
-    // before return.
     const savedErr = ctx.err
     const savedTrialMode = ctx._trialMode
-    // THE SANDBOX MUST NOT OUTLIVE THE TRIAL AS AN OWN PROPERTY.
-    // Contexts are made with Object.create(parent) and CACHED per
-    // (parent, key) by AontuContext.descend, so `err` and `_trialMode`
-    // are normally INHERITED -- and assigning them here, the restore
-    // included, creates own properties that shadow the ancestor on
-    // every later pass. A child that has run a trial of its own then
-    // cannot see the trial its PARENT is running: makeNilErr allocates
-    // a real NilVal instead of TRIAL_NIL, the refusal lands on the
-    // meet's real error list, and the losing member is kept as though
-    // it had survived -- with the nil inside it. A vet run then
-    // reported the conflicts of arms that should have dropped out, and
-    // called the document invalid where it is incomplete.
-    //
-    // So the restore DELETES what was inherited rather than writing it
-    // back. Both arms of both guards are live: the root meet context
-    // has an own `err`, a descended child does not, and `_trialMode`
-    // is own exactly when a disjunction is tried inside another
-    // disjunction's trial on the same context.
     const ownErr = Object.prototype.hasOwnProperty.call(ctx, 'err')
     const ownTrialMode =
       Object.prototype.hasOwnProperty.call(ctx, '_trialMode')
-    // A MEMBER'S TYPE FLOW IS PART OF THAT MEMBER. `refer(t)`/`rel(t)`
-    // assert `t` on ANOTHER node, and the assertion may only take
-    // effect if the member that makes it survives: committing every
-    // member's flow puts `t_A & t_B` on the target, which no reading
-    // of `A | B` licenses and which leaves the target MORE constrained
-    // than either alternative. The flow record is therefore staged per
-    // trial, like `ctx.err`, and only the survivors' records are
-    // merged into the real one below.
     const savedFlows: Map<string, Val> | undefined = (ctx as any).referflows
     const staged: (Map<string, Val> | undefined)[] = []
-    // C1-inner: tell `makeNilErr` to return TRIAL_NIL in this scope
-    // instead of allocating per-failure NilVals. Save/restore so
-    // nested DisjunctVal trials (and the outer non-trial code) are
-    // not affected. The restore lives in `finally`: if a trial throws,
-    // leaving ctx._trialMode=true would collapse every subsequent real
-    // error in this ctx to the shared TRIAL_NIL sentinel.
     ctx._trialMode = true
     let gate: number[] | undefined = undefined
     try {
@@ -153,10 +102,6 @@ class DisjunctVal extends JunctionVal {
         oval[vI] = unite(te ? ctx.clone({ explain: ec(te, 'DIST:' + vI) }) : ctx, v, peer, 'dj-peer')
 
         if (0 < trialErr.length) {
-          // C1: failed-trial marker is never user-visible — it just
-          // signals "this disjunct member doesn't match" and is
-          // filtered out before the result is built. Use the shared
-          // sentinel instead of allocating a fresh NilVal per trial.
           oval[vI] = TRIAL_NIL
         }
         else if (v instanceof PrefVal &&
@@ -171,23 +116,6 @@ class DisjunctVal extends JunctionVal {
         done = done && DONE === oval[vI].dc
       }
 
-      // THE ADMISSION GATE (ADR-004). A peer that meets a preference
-      // INSIDE a disjunction must be admitted by the disjunction: by
-      // some sibling alternative (whose own trial above already
-      // answers that), or by the preferred value itself (the pref
-      // branch's own admitted set). The pref's kind gate alone used to
-      // decide, so a same-kind concrete peer replaced the default with
-      // the alternatives never consulted -- `k:*'auto'|'literal'|'data'`
-      // plus `k:'autoo'` answered "autoo", and `*8080|(integer&neq(80))`
-      // admitted 80 (use-cases/BUGS.md §1-2). An inadmissible override
-      // now fails the pref member's trial, and when every member is
-      // gone the meet is the existing `empty` refusal.
-      //
-      // SCALAR preferred values only, exactly the kind gate's own
-      // boundary (test/spec/pref.tsv, "THE GATE IS A SCALAR GATE"): a
-      // structural or kind-peg default stays ungated. A deliberately
-      // open default remains spellable as `*x|top` -- the top branch
-      // admits every override (the apidef machine-emitted idiom).
       if (undefined !== gate) {
         for (const gI of gate) {
           let admitted = false
@@ -232,20 +160,6 @@ class DisjunctVal extends JunctionVal {
 
     // // // console.log('DISJUNCT-unify-B', this.id, oval.map(v => v.canon))
 
-    // A PREFERENCE CONJOINED WITH A DISJUNCTION IS A PREFERENCE ON THE
-    // ALTERNATIVE IT NAMES: `(A|B) & *A` is `*A|B`, the same value the
-    // direct spelling `*A|B` denotes. Distribution carries the peer to
-    // each member, and a scalar preference meeting a concrete same-kind
-    // member is replaced BY that member (the kind gate) -- so the
-    // preference simply vanished, and `specversion: ("1.0"|"1.1") &
-    // *"1.0"`, the enum-with-default written the other way round, held
-    // no default at all. The old generation fold hid it by folding the
-    // members together; ADR-007 does not, and a disjunction that has
-    // lost its default is not the value the author wrote.
-    //
-    // A preference naming no alternative is dropped, as it is today: it
-    // has nothing to prefer, and the default-validity lint is what
-    // reports that shape.
     if (true === (peer as any).isPref) {
       const want: any = prefInnerPeg(peer as PrefVal)
       for (let vI = 0; vI < oval.length; vI++) {
@@ -279,17 +193,6 @@ class DisjunctVal extends JunctionVal {
             continue
           }
 
-          // TWO PREFERENCES OVER ONE VALUE ARE ONE PREFERENCE, and
-          // the lower rank is the one that generates: `*1 | **1` is
-          // `*1`. Ranking folds EQUAL ranks (R2); this folds the rest,
-          // which R5 stopped discarding.
-          //
-          // A PLAIN arm holding that same value is NOT a duplicate of
-          // it and must not be folded away: it is the sibling that
-          // ADMITS an override under ADR-004's gate, which is the
-          // whole point of writing `*x | x`. Folding it turned that
-          // idiom's own default into a `pref_not_instance` finding,
-          // and `*top | top` is pinned as its control.
           const a: any = oval[vI]
           const b: any = oval[kI]
           if (true === a.isPref && true === b.isPref
@@ -308,10 +211,6 @@ class DisjunctVal extends JunctionVal {
       // // // console.log('DISJUNCT-unify-D', this.id, oval.map(v => v.canon))
     }
 
-    // THE SURVIVORS' FLOWS, AND ONLY THEIRS. Members knocked out by
-    // the trial, by the admission gate or by the dedup above are all
-    // nil here, so this runs after every one of those and before the
-    // filter that drops them.
     if (undefined !== savedFlows) {
       for (let vI = 0; vI < staged.length; vI++) {
         const st = staged[vI]
@@ -342,13 +241,6 @@ class DisjunctVal extends JunctionVal {
     }
     else {
       out = new DisjunctVal({ peg: oval }, ctx)
-      // A NARROWED DISJUNCTION IS STILL THAT DISJUNCTION. The meet mints
-      // a fresh value, which used to arrive unsited and file-less -- so
-      // every finding naming a disjunction that had met anything
-      // pointed at row -1 with no file, and an agent handed the report
-      // had nowhere to go (the review's finding F). `place` copies the
-      // whole site, position and url together, which is what tells the
-      // report which document it came from.
       this.place(out)
     }
 
@@ -363,24 +255,6 @@ class DisjunctVal extends JunctionVal {
   }
 
 
-  // RANK ORDERS THE SURVIVORS, IT DOES NOT DISCARD AT PARSE (ADR-011
-  // R5, docs/design/DEFAULTS.0.md). Every rank is KEPT here, and
-  // generation takes the lowest-rank preference still standing -- so
-  // eliminating the lower arm PROMOTES the next instead of taking the
-  // whole ladder with it. This ran once, before the member trials,
-  // and discarded every arm but the lowest: `*1 | **2` met by
-  // `neq(1)` lost the default entirely and refused, where the ladder
-  // exists precisely to answer 2. Rank is a preference order over
-  // WHAT SURVIVES, which is not knowable until the trials have run.
-  //
-  // Only EQUAL ranks fold, because two defaults at one rank are one
-  // decision: compatible pegs merge, and a disagreement is the
-  // `pref_rank_clash` refusal (R2), which belongs to the whole
-  // disjunction -- there is no alternative to fall back to.
-  //
-  // Answers the sole surviving preference when the disjunction holds
-  // exactly one -- which the RECURSIVE call below consumes to lift a
-  // nested disjunct's winner into this one -- or the clash refusal.
   rankPrefs(ctx: AontuContext): Val | undefined {
     // The kept index per rank, so an equal-rank twin folds into the
     // arm already standing for that rank.
@@ -435,7 +309,6 @@ class DisjunctVal extends JunctionVal {
   }
 
 
-
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     let out = (super.clone(ctx, spec) as DisjunctVal)
     return out
@@ -447,25 +320,6 @@ class DisjunctVal extends JunctionVal {
   }
 
 
-  // AN UNRESOLVED DISJUNCTION IS NOT A VALUE (ADR-007).
-  //
-  // Generation used to FOLD the surviving members together with unify
-  // and emit the result. That answer is in no branch of the
-  // disjunction: `({x:1}|{y:2}) & {z:3}` generated `{x:1,y:2,z:3}`, a
-  // map the model never admits, and `1|2` died as a scalar_value
-  // CONFLICT -- the conflict of the fold, not of anything the author
-  // wrote. The second half is what made vet decorative: vet's
-  // incompleteness check keeps incomplete-class findings, so a missing
-  // required enum field (`role: 'a'|'b'` with no data) arrived as a
-  // conflict, was filtered out, and vetted VALID with zero findings
-  // (use-cases/BUGS.md §13, the review's finding C).
-  //
-  // What remains after unification is what the model still admits, so
-  // more than one surviving alternative means the truth is not yet
-  // settled -- incomplete, the same class a bare `string` residue
-  // answers, and the same answer CUE gives for a non-concrete export.
-  // A preference resolves it (that is what `*` is for), and so does a
-  // single surviving member.
   gen(ctx: AontuContext) {
     if (0 < this.peg.length) {
       // Ranking may not have run when gen is reached without a prior
@@ -477,12 +331,6 @@ class DisjunctVal extends JunctionVal {
 
       const prefs = this.peg.filter((v: Val) => v instanceof PrefVal)
 
-      // ALTERNATIVES THAT GENERATE THE SAME VALUE ARE RESOLVED
-      // (ADR-007's rule, asked at the moment it matters): `[] | [&:
-      // T]` met by an empty list keeps both arms -- they differ as
-      // SCHEMAS, which is what stops the dedup collapsing the
-      // template away (BUGS.md §52 regime 4) -- but both generate
-      // the empty list, and one generated value is one value.
       if (0 === prefs.length && 1 < this.peg.length) {
         const gctx = ctx.clone({ err: [], collect: true })
         let firstOut: any
@@ -516,9 +364,6 @@ class DisjunctVal extends JunctionVal {
         return undefined
       }
 
-      // THE LOWEST-RANK SURVIVOR (R5). Ranking no longer discards the
-      // weaker arms, so the choice is made here, over what is left:
-      // `*1 | **2` answers 1, and answers 2 once `*1` is gone.
       let best: any = this.peg[0]
       if (0 < prefs.length) {
         best = prefs[0]
@@ -536,8 +381,6 @@ class DisjunctVal extends JunctionVal {
 } /* node:coverage ignore next 8 */
 
 
-
-
 export {
   DisjunctVal,
 }