aontu 0.61.0 → 0.63.0

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 {

package/src/val/arith.ts

@@ -1,61 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
 
-// THE ARITHMETIC FAMILY -- add, sub, mul, div, mod, rem.
-//
-// The review's finding I: "Arithmetic stops at `+`", so "prod gets
-// double the replicas" is inexpressible and Kubernetes quantity strings
-// silently CONCATENATE ("500m" + "500m" is "500m500m"). The design
-// pre-registered the semantics these functions must have
-// (docs/capability-review/g8-generation.md, "Arithmetic semantics,
-// pre-registered") and the boundary that keeps `-` `*` `/` `%`
-// reserved: maths arrives as functions or not at all.
-//
-// THE FAMILY IS NUMERIC, WHICH IS WHAT MAKES `add` MORE THAN A SYNONYM
-// FOR `+`. The operator is polymorphic -- concatenation for strings,
-// disjunction for booleans, addition for numbers -- and that is why the
-// quantity strings above concatenate instead of failing. `add("500m",
-// "500m")` is a located error, because a function named for a numeric
-// operation has no business inventing a string. So the two spellings
-// mean different things, and both are kept.
-//
-// Everything else here is the number tower's existing law, applied to
-// five more operations (docs/design/number-model.md):
-//
-//   R5 CONTAGION      no operation introduces a kind narrower than its
-//                     operands, so an integer result needs integer
-//                     operands.
-//   D6 EXACT LADDER   integer < biginteger < bigdecimal. A mixed exact
-//                     operation promotes to the WIDEST operand, is
-//                     computed exactly, and never demotes.
-//   FLOAT IS OFF IT   binary64 mixed with either big leaf is a hard
-//                     error in both operand orders, because promotion
-//                     either way throws away exactness the document
-//                     asked for by writing `0d`.
-//   NO ROUNDING       an exact result that will not store is refused,
-//                     never rounded to fit.
-//
-// and three refusals this file adds, which the pre-registration named:
-//
-//   div/mod/rem by ZERO is a hard error in every kind. A ground-truth
-//   language has no business manufacturing infinity, and Aontu cannot
-//   even write one down -- an overflowing literal is a `not_number`
-//   error nil -- so propagating one would invent a value no generated
-//   JSON could carry.
-//
-//   A NON-FINITE FLOAT RESULT is a located error. This one was already
-//   reachable through `+` and reported as neither: `1.0e308+1.0e308`
-//   crashed TypeScript with `[aontu/internal]` and leaked Go's raw
-//   `json: unsupported value: +Inf` with no code at all (use-cases/
-//   BUGS.md 39). PlusOpVal and its Go twin now go through the same
-//   check.
-//
-//   DIVISION IS NOT CLOSED OVER THE DECIMAL LEAF, so div/mod/rem refuse
-//   a bigdecimal operand rather than rounding one third to fit. See
-//   `inexact_divide`'s hint: scale to integers, which is the money wire
-//   convention anyway, or accept a float.
-
-
 import type { Val } from '../type'
 
 import { AontuContext } from '../ctx'
@@ -105,9 +50,6 @@ function unpref(v: any): any {
 
 
 function arithKind(v: any): ArithKind | undefined {
-  // Every caller hands a driven Val (an operand past the signature
-  // gate, or a bag member from the aggregate fold), so scalarhood is
-  // the one question -- a container member lands here.
   if (true !== v?.isScalar) {
     return undefined
   }
@@ -124,8 +66,6 @@ function arithKind(v: any): ArithKind | undefined {
 }
 
 
-// An exact-ladder operand as an exact integer. Only reached for the two
-// integral leaves; an `integer` peg is integral by construction.
 function asInteger(v: any, k: ArithKind): bigint {
   return 'biginteger' === k ? v.peg : BigInt(v.peg)
 }
@@ -136,12 +76,6 @@ function asDecimal(v: any, k: ArithKind): Decimal {
 }
 
 
-// The whole family, in one function, because every rule above is a rule
-// about ARITHMETIC and not about any one operation. `node` is the value
-// the error is located at -- the call, or the `+` op.
-// `attempt` is the name the ERROR reports, which is the operation
-// except when a fold borrows one: `sum` adds, but a bad member is the
-// author's `sum` call and must say so.
 function arith(
   ctx: AontuContext | undefined,
   op: ArithOp,
@@ -156,11 +90,6 @@ function arith(
   const ak = arithKind(av)
   const bk = arithKind(bv)
 
-  // A non-numeric operand is not something to wait for: `resolve` is
-  // only reached once every argument has settled, so a kind, a map, a
-  // string or a boolean here is the author's mistake and is named as
-  // one. (`+` differs, and must: it has answers for strings and
-  // booleans.)
   if (undefined === ak || undefined === bk) {
     return makeNilErr(ctx, 'invalid-arg', node, undefined, name)
   }
@@ -187,9 +116,6 @@ function arith(
 }
 
 
-// IEEE-754 binary64, with the JSON-superset constraint still biting: an
-// infinite or NaN result is a located error rather than a value, because
-// there is no way to write one down and no JSON that could carry it.
 function floatArith(
   ctx: AontuContext | undefined,
   op: ArithOp,
@@ -210,10 +136,6 @@ function floatArith(
             // Truncated remainder, sign following the DIVIDEND, which is
             // what JavaScript's `%` and Go's math.Mod both give...
             'rem' === op ? x % y :
-              // ...and the floored modulus, sign following the DIVISOR,
-              // built from it. Adding the divisor back moves a remainder
-              // whose sign disagrees into agreement, and leaves an exact
-              // zero alone.
               flooredMod(x % y, y)
 
   return Number.isFinite(out) ?
@@ -247,11 +169,6 @@ function integerArith(
     'add' === op ? x + y :
       'sub' === op ? x - y :
         'mul' === op ? x * y :
-          // TRUNCATION TOWARD ZERO, stated once here rather than left to
-          // whichever host `/` each port happens to call: div(-7, 2) is
-          // -3, not -4. BigInt division truncates, and so does Go's
-          // big.Int.Quo (its Div floors, which is why the Go twin must
-          // not use it).
           'div' === op ? x / y :
             'rem' === op ? x % y :
               flooredModBig(x % y, y)
@@ -262,11 +179,6 @@ function integerArith(
     return new BigIntegerVal({ peg: out })
   }
 
-  // The result faces the SAME storage contract R1 puts on a literal --
-  // integral, inside the int64 window, and exactly representable in
-  // binary64 -- because Go's int64 holds results TypeScript's double
-  // cannot, and without a shared test a document would resolve in one
-  // port and round in the other.
   return isIntegerStorable(out) ?
     new IntegerVal({ peg: Number(out) }) :
     makeNilErr(ctx, 'inexact_integer_sum', node, undefined, name,
@@ -290,10 +202,6 @@ function decimalArith(
   y: Decimal
 ): Val {
   if (divides(op)) {
-    // EXACT DECIMAL DIVISION IS NOT CLOSED: one third has no finite
-    // decimal form, so a `div` over this leaf either rounds -- the one
-    // thing the leaf exists to refuse -- or refuses. It refuses, and the
-    // hint names both ways out.
     return makeNilErr(ctx, 'inexact_divide', node, undefined, name)
   }
 

package/src/val/caserange.ts

@@ -0,0 +1,53 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+
+// The half-open code-point span [lo, hi) a (start, len) selects over a
+// string of `n` code points.
+export function caseSpan(n: number, start: number, len: number): [number, number] {
+  const span = len < 0 ? n : len
+
+  if (0 <= start) {
+    const lo = Math.min(start, n)
+    return [lo, Math.min(lo + span, n)]
+  }
+
+  const hi = Math.max(0, n + start)
+  return [Math.max(0, hi - span), hi]
+}
+
+
+// `text` with the selected run cased. Outside the run the source is
+// returned verbatim, code point for code point.
+export function caseRange(
+  text: string, start: number, len: number, up: boolean
+): string {
+  const cps = Array.from(text)
+  const [lo, hi] = caseSpan(cps.length, start, len)
+  if (hi <= lo) {
+    return text
+  }
+  const mid = cps.slice(lo, hi).join('')
+  return cps.slice(0, lo).join('') +
+    (up ? mid.toUpperCase() : mid.toLowerCase()) +
+    cps.slice(hi).join('')
+}
+
+
+export function rangeArg(v: any): number | undefined {
+  if (null == v) {
+    return undefined
+  }
+  const p = (true === v?.isScalar) ? v.peg : undefined
+  if ('number' === typeof p && Number.isInteger(p)) {
+    return p
+  }
+  // A biginteger index is an index: a position in a string is small by
+  // construction, or it is not an index at all.
+  if ('bigint' === typeof p) {
+    const n = Number(p)
+    if (Number.isSafeInteger(n)) {
+      return n
+    }
+  }
+  return NaN
+}

package/src/val/members.ts

@@ -1,23 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
 
-// THE MEMBERS OF A BAG, as every fold and every generator over a bag
-// sees them (use-cases/BUGS.md §79; G9 phase 0 item 4). A member is a
-// child that generation would EMIT: a hide()- or type()-marked child
-// is not one, an alias declaration is not one, and an optional key
-// whose value generates nothing -- an unfilled `y?: string`, an absent
-// optional subtree -- is not one. `each`, `emit`, `filter`, `pick`,
-// `join` and the aggregates read a bag through this one function, so a
-// value the document withholds from its output is withheld from every
-// text and every total the document computes from it: a hidden field
-// that reached generated source through `join` is the defect this
-// closes, and it was one behaviour in both ports because each verb
-// had its own enumeration and none of them asked the mark.
-//
-// Maps list their members in code-point key order (../keyorder.ts),
-// lists in index order -- the one order canon, generation and the Go
-// port agree on (BUGS.md §62). Twin of bagMembers in go/members.go.
-
 import type { Val } from '../type'
 import { AontuContext } from '../ctx'
 import { cmpCodePoint } from '../keyorder'
@@ -37,12 +20,6 @@ function bagMembers(data: any, ctx: AontuContext): Member[] | undefined {
     Object.keys(data.peg).sort(cmpCodePoint) :
     (data.peg as Val[]).map((_v: Val, i: number) => '' + i)
 
-  // A member marked while its bag is not was marked in its own right,
-  // and is left out as generation leaves it out. Under a MARKED bag
-  // every child carries the mark (hide() and type() mark to the
-  // leaves), so there the mark says nothing about the member and every
-  // child is one -- the members of a hidden bag are what the bag
-  // holds, exactly as a reference to it lifts them.
   const lifted = true === data.mark.hide || true === data.mark.type
 
   const out: Member[] = []

package/src/val/numcmp.ts

@@ -1,20 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-/*
- * Exact cross-leaf numeric comparison for the constraint algebra
- * (docs/reference-language.md, "The constraint algebra"): order is a
- * property of the number line, not the leaf, so a bound must compare an
- * integer, a float, a biginteger and a bigdecimal EXACTLY, with no
- * rounding anywhere. Every finite binary64 is exactly a rational —
- * mant * 2^exp — and 2^-k = 5^k * 10^-k, so every leaf converts
- * losslessly to a signed scaled-decimal (unscaled / 10^scale) and
- * comparison is bigint arithmetic. The Go mirror is numcmp.go.
- *
- * The scaled forms built here are comparison-internal: they are never
- * stored, never rendered, and deliberately NOT subject to the exact
- * leaves' 4096-digit budget (a float's exact expansion can need ~770
- * digits and that is fine for a compare).
- */
 
 import { Decimal } from './Decimal'
 
@@ -26,7 +11,7 @@ import { Decimal } from './Decimal'
 type Scaled = {
   inf?: 1 | -1
   unscaled: bigint     // signed
-  scale: number        // value = unscaled / 10^scale, scale >= 0
+  scale: number
 }
 
 
@@ -54,8 +39,6 @@ function scaledOfFloat(f: number): Scaled {
   const expBits = Number((bits >> 52n) & 0x7ffn)
   const frac = bits & 0xfffffffffffffn
 
-  // Normal: implicit leading bit, exponent bias 1023 plus the 52
-  // fraction bits. Subnormal: no implicit bit, fixed exponent -1074.
   let mant: bigint
   let exp: number
   if (0 === expBits) {
@@ -94,7 +77,6 @@ function pow10(n: number): bigint {
 }
 
 
-// Exact three-way comparison of two scaled decimals.
 function cmpScaled(a: Scaled, b: Scaled): number {
   const ai = a.inf ?? 0
   const bi = b.inf ?? 0
@@ -113,16 +95,11 @@ function cmpScaled(a: Scaled, b: Scaled): number {
 }
 
 
-// Exact three-way comparison of two numeric leaf Vals, any leaves.
 function cmpNumeric(a: any, b: any): number {
   return cmpScaled(scaledOfNumeric(a), scaledOfNumeric(b))
 }
 
 
-// Lexical comparison by Unicode CODE POINTS — not UTF-16 code units,
-// which order astral-plane text differently. Go compares strings
-// byte-wise in UTF-8, which IS code-point order, so this is the side
-// that must adapt (a Phase 0 decision, docs/reference-language.md).
 function cmpCodePoints(a: string, b: string): number {
   let ai = 0
   let bi = 0
@@ -141,9 +118,6 @@ function cmpCodePoints(a: string, b: string): number {
 }
 
 
-// The tower order integer < float < biginteger < bigdecimal, used when
-// two endpoints at the SAME point meet: the survivor is the
-// tower-lowest spelling (docs/reference-language.md, bounds ruling 2).
 function towerRank(v: any): number {
   return v.isBigDecimal ? 3 : v.isBigInteger ? 2 :
     v.isInteger ? 0 : 1

package/src/val/numkind.ts

@@ -1,154 +1,42 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-/*
- * Numeric kind classification, shared by every site that turns a raw
- * JavaScript number into an IntegerVal or a NumberVal (the aontu val
- * rule, rawToVal, VarVal, the `+` operator, upper()/lower()). Keeping
- * the test in one place stops those sites from drifting apart, and
- * stops them drifting from the Go port (see isIntegerKind in
- * go/lang.go).
- *
- * This module deliberately imports nothing: IntegerVal itself needs the
- * test for its constructor guard, so any import here risks a cycle.
- */
 
-
-// The int64 range, as exact float64 bounds. -2^63 and 2^63 are both
-// exactly representable; 2^63-1 is NOT (it rounds up to 2^63), which is
-// why the upper bound is exclusive and 0x7fffffffffffffff correctly
-// falls outside.
 const INT64_MIN = -9223372036854775808.0
 const INT64_LIMIT = 9223372036854775808.0
 
 
-// True when a numeric literal has *integer* kind. All three conditions
-// must hold:
-//   (a) the source text, when there is any, contains no '.'
-//   (b) the value is integral
-//   (c) the value lies within the int64 range
-//
-// The range test is written against the float64 bounds rather than as
-// `n === Number(BigInt(n))` or Go's `n == float64(int64(n))`: converting
-// an out-of-range float64 to int64 is implementation-defined in Go, and
-// that accident is exactly what the two ports used to disagree about.
-//
-// `src` is undefined at construction sites with no source text (raw
-// values from an implicit top-level list, or a $var binding); there
-// condition (a) is vacuous and (b)+(c) decide.
 function isIntegerKind(n: number, src?: string): boolean {
   if (null != src && src.includes('.')) {
     return false
   }
-  // Number.isInteger is false for NaN and both infinities, so a
-  // non-finite value never reaches the range test.
   return Number.isInteger(n) && INT64_MIN <= n && n < INT64_LIMIT
 }
 
 
-// The same int64 window, exactly, for values that were computed as
-// bigints and have not been through a double yet.
 const INT64_MIN_EXACT = -9223372036854775808n
 const INT64_LIMIT_EXACT = 9223372036854775808n
 
 
-// D6 -- THE STORAGE CONTRACT FOR AN EXACTLY COMPUTED INTEGER.
-//
-// `integer + integer` is computed exactly (in bigint here, in checked
-// int64 in Go) and the exact answer is only then offered to the integer
-// leaf, which accepts it when it is integral (a bigint always is),
-// within the int64 window, AND exactly representable in binary64.
-//
-// The binary64 half is the parity-critical one. Go's int64 can hold sums
-// this port's double cannot -- 2^53+1 among them -- so a test written
-// only against the int64 window would let Go store `9007199254740993`
-// while TypeScript silently stored `...992`. The round-trip through
-// Number() is that test: it is true exactly when nothing was lost. Both
-// ports must refuse the same sums, which is why this is the shared
-// contract and not a local convenience.
-//
-// Refusal, not rounding: a sum that fails here is a located error whose
-// hint points at `0d` for an exact integer, per R1's own storage rule
-// applied to a result rather than a literal.
 function isIntegerStorable(n: bigint): boolean {
   return INT64_MIN_EXACT <= n && n < INT64_LIMIT_EXACT &&
     isExactInBinary64(n)
 }
 
 
-// The binary64 half of the storage contract, on its own: true when an
-// exact integer survives a round trip through a double unchanged.
-//
-// D7's literal rule needs exactly this half and NOT the int64 window --
-// 10^20 is outside int64 and is still a perfectly good float-kind value,
-// because it lands exactly on a binary64. THE RULE IS EXACTNESS, NOT
-// MAGNITUDE: `0x10000000000000000000000000000000` is 2^124, a power of
-// two, so it is exact and stays a value, while the very much smaller
-// `0x7fffffffffffffff` (2^63-1) is not and is refused.
-//
-// It is factored out rather than reimplemented so a LITERAL and a
-// COMPUTED SUM cannot disagree about what "exact" means: both ask this
-// one function, in both ports.
-//
-// The Number.isFinite guard is what makes it total. A bigint far beyond
-// binary64's range converts to Infinity, and BigInt(Infinity) THROWS --
-// so a literal like 10^400 (which the lexer already turns into a
-// non-finite `not_number`) would crash the test rather than fail it.
 function isExactInBinary64(n: bigint): boolean {
   const d = Number(n)
   return Number.isFinite(d) && BigInt(d) === n
 }
 
 
-// D7 -- LOSSY INTEGER LITERALS ARE REFUSED.
-//
-// True when `src` is an integer-source literal whose exact value cannot
-// be held in binary64, so storing it would silently substitute a
-// DIFFERENT number. Aontu refuses instead: the caller turns this into a
-// located parse error whose hint names the escape (`0d<digits>`).
-//
-// WHICH LITERALS ARE IN SCOPE. An integer-source literal is one that
-// denotes an exact integer:
-//
-//   - plain decimal digits (`9007199254740993`), with the landed `_`
-//     separator rule;
-//   - a base-prefixed run (`0x…`, `0o…`, `0b…`);
-//   - either of those with a NON-NEGATIVE exponent (`1e21`), which still
-//     denotes an integer.
-//
-// Everything else is out of scope and unchanged. A `.` in the source
-// makes it a float literal by R1, so it is not an integer source at all;
-// a NEGATIVE exponent (`2e-1`, `1e-400`) denotes a fraction, and testing
-// those for binary64 exactness would refuse `2e-1` -- 0.2 is not exactly
-// representable either -- which is emphatically not what D7 is about.
-// The `0d` family never reaches here: it has its own matcher and its own
-// exact leaves.
-//
-// The value is re-derived from the SOURCE TEXT rather than read off the
-// lexed double `n`, because that double is the rounded value this rule
-// exists to detect; comparing it with itself would always agree. `n` is
-// passed only for the fast path, which is why the signature mirrors
-// isIntegerKind's.
 function isLossyIntegerLiteral(n: number, src?: string): boolean {
-  // No source text (a raw value from an implicit top-level list, a $var
-  // binding) means there is no literal to judge -- the same way R1's
-  // "no `.` in the source" condition is vacuous at those sites.
   if (null == src) {
     return false
   }
 
-  // FAST PATH, and the one every ordinary document takes: below 2^53
-  // every integer is representable, so an integer literal whose ROUNDED
-  // value is strictly inside that window cannot have had a different
-  // exact value -- a different integer would be at least 1 away, and
-  // rounding here is accurate to half a unit. This runs at every numeric
-  // literal in every parse, so it must not allocate a bigint (2^53+1 has
-  // rounded value 2^53 and is deliberately NOT inside the window).
   if (Number.isInteger(n) && -POW53 < n && n < POW53) {
     return false
   }
-  // A `.` makes it a float source (R1), out of scope: checked here, and
-  // not left to the patterns below, so the other common literal shape
-  // also leaves without touching a regexp.
   if (-1 !== src.indexOf('.')) {
     return false
   }
@@ -163,13 +51,9 @@ function isLossyIntegerLiteral(n: number, src?: string): boolean {
       return false
     }
     const coeff = BigInt(stripSep(dec[2]))
-    // Zero at any exponent is zero, and zero is exact -- test it before
-    // the exponent bound, which would otherwise refuse `0e500`.
     if (0n === coeff) {
       return false
     }
-    // Beyond this the value cannot be finite in binary64, so it cannot
-    // be exact either -- and 10n ** BigInt(exp) must not be built.
     if (MAX_EXPONENT < exp) {
       return true
     }
@@ -183,9 +67,6 @@ function isLossyIntegerLiteral(n: number, src?: string): boolean {
     exact = BigInt('0' + base[2].toLowerCase() + stripSep(base[3]))
   }
 
-  // The sign is irrelevant to exactness (binary64 is sign-symmetric) and
-  // is anyway lexed as the unary prefix, but accept it so the test does
-  // not depend on that.
   return !isExactInBinary64(exact)
 }
 
@@ -195,9 +76,6 @@ function isLossyIntegerLiteral(n: number, src?: string): boolean {
 const DEC_INT_LITERAL_RE =
   /^([-+]?)([0-9](?:_?[0-9])*)(?:[eE]([-+]?[0-9](?:_?[0-9])*))?$/
 
-// `[+-]? 0(x|o|b) digits`. Hex digits are the widest set, and a bad
-// digit for the base simply makes BigInt throw -- which cannot happen,
-// since the lexer only produced a token for a well-formed run.
 const BASE_INT_LITERAL_RE =
   /^([-+]?)0([xXoObB])([0-9a-fA-F](?:_?[0-9a-fA-F])*)$/
 
@@ -215,38 +93,11 @@ function stripSep(s: string): string {
 }
 
 
-// THE SINGLE RENDERING OF AN INTEGER-KIND PEG. Every site that turns one
-// into text must call this -- so that "how many rendering sites are there?"
-// is answerable by grepping this function's callers.
-//
-// That question has been answered wrongly twice. Issue #21 was the
-// divergence where TypeScript printed 2^60 as 1152921504606847000, a
-// DIFFERENT integer that merely rounds to the same double, because a JS
-// number's toString emits the shortest decimal that round-trips (at most 17
-// significant digits) while Go printed the exact value from its int64. It
-// was closed having fixed the two sites known at the time, canon and
-// generate. A differential audit then found a THIRD (`+`'s string
-// coercion) and, while fixing that, a FOURTH (a variable used as a path
-// segment). Both were the same one-character mistake -- `String(peg)` or
-// `'' + peg` on a JS number -- at a site nobody had enumerated.
-//
-// BigInt is exact here by construction: an integer-kind peg is integral and
-// inside the int64 window (isIntegerKind, enforced by IntegerVal's
-// constructor), so the conversion cannot throw or lose anything. Below 2^53
-// nothing moves -- BigInt(n).toString() === String(n) for every safe
-// integer, and both give "0" for negative zero.
-//
-// FLOAT KIND MUST NOT COME HERE. A float's shortest form IS the right
-// answer and is what Go prints too (1e21 -> "1e+21"), so a caller must
-// select on kind, not merely on the peg being a JS number.
 function integerDigits(peg: number): string {
   return BigInt(peg).toString()
 } /* node:coverage ignore next 13 */
 
 
-// The window bounds stay module-local: they are the rules' working
-// parts, not API, and every caller wants isIntegerKind or
-// isIntegerStorable.
 export {
   integerDigits,
   isExactInBinary64,

package/src/val/valutil.ts

@@ -13,7 +13,6 @@ import { Decimal } from './Decimal'
 import { isIntegerKind } from './numkind'
 
 
-// TODO: move to FuncBaseVal
 export function makeScalar(scalar: any): ScalarVal {
   const st = typeof scalar
   const spec = { peg: scalar }
@@ -36,21 +35,6 @@ export function makeScalar(scalar: any): ScalarVal {
 }
 
 
-// Like makeScalar, but for a numeric result that must not narrow the
-// kind of the value it was derived from (kind contagion: upper(2) is an
-// integer 2, upper(1.1) is a number 2). `like` is the source Val whose
-// kind is being carried over; anything that is not integer kind — and
-// any result that has left the int64 range — yields a NumberVal.
-//
-// The two EXACT leaves need no `like`: unlike integer and float, which
-// share the JavaScript `number` type and so can only be told apart by
-// the value they came from, a bigint is a biginteger and a Decimal is a
-// bigdecimal. Carrying the kind is automatic because the exact result
-// types ARE the kinds — an exact ceiling of a bigdecimal is a Decimal,
-// so upper(0d1.1) is bigdecimal 0d2.0 and upper(0d5) is biginteger 0d5.
-//
-// makeScalar keeps its own contract (every number becomes a NumberVal)
-// for callers that have no kind to preserve.
 export function makeScalarLike(scalar: any, like: any): ScalarVal {
   if ('bigint' === typeof scalar) {
     return new BigIntegerVal({ peg: scalar })