aontu 0.50.1 → 0.52.0

package/src/val/UpperFuncVal.ts

@@ -15,7 +15,8 @@ import { makeNilErr } from '../err'
 
 import { NilVal } from '../val/NilVal'
 import { ScalarKindVal } from '../val/ScalarKindVal'
-import { makeScalar } from '../val/valutil'
+import { makeScalarLike } from '../val/valutil'
+import { Decimal } from '../val/Decimal'
 
 
 
@@ -43,14 +44,30 @@ class UpperFuncVal extends FuncBaseVal {
 
 
   resolve(ctx: AontuContext | undefined, args: Val[]) {
-    const oldpeg = args?.[0].peg
+    // A missing argument (`upper()`) must produce an invalid-arg error
+    // value, as the Go port does — reading .peg off nothing threw a
+    // TypeError that the unifier could only report as an opaque
+    // internal error.
+    const arg = args?.[0]
+    const oldpeg = arg?.peg
     const peg = 'string' === typeof oldpeg ? oldpeg.toUpperCase() :
       'number' === typeof oldpeg ? Math.ceil(oldpeg) :
-        undefined
+        // 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
     const out = this.place(
       null == peg ?
         makeNilErr(ctx, 'invalid-arg', this) :
-        makeScalar(peg)
+        // The ceiling keeps the ARGUMENT's kind (upper(2) is an integer
+        // 2, upper(1.1) is a number 2) — the function must not narrow
+        // number to integer, and this also makes the actual result kind
+        // agree with the superior() advertised below.
+        makeScalarLike(peg, arg)
     )
     return out
   }
@@ -64,7 +81,7 @@ class UpperFuncVal extends FuncBaseVal {
       })) :
       super.superior()
   }
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/val/Val.ts

@@ -148,11 +148,13 @@ abstract class Val {
 
   deps?: any
 
-  #ctx: any
+  // TS-private (as _site above): the `#` form emits downlevel helper
+  // functions whose branches no supported Node can execute.
+  private _ctx: any
 
   // TODO: Site needed in ctor
   constructor(spec: ValSpec, ctx?: AontuContext) {
-    this.#ctx = ctx
+    this._ctx = ctx
 
     this.peg = spec?.peg
 
@@ -179,7 +181,7 @@ abstract class Val {
 
 
   ctx() {
-    return this.#ctx
+    return this._ctx
   }
 
 
@@ -217,9 +219,12 @@ abstract class Val {
 
     out.dc = this.done ? DONE : out.dc
 
-    out.site.row = spec?.row ?? this.site.row ?? -1
-    out.site.col = spec?.col ?? this.site.col ?? -1
-    out.site.url = spec?.url ?? this.site.url ?? ''
+    // this.site is a lazy getter that always yields a Site, and Site's
+    // constructor coerces row/col to numbers and url to a string, so the
+    // spec value is the only one that can be absent.
+    out.site.row = spec?.row ?? this.site.row
+    out.site.col = spec?.col ?? this.site.col
+    out.site.url = spec?.url ?? this.site.url
 
     out.mark = Object.assign({}, this.mark, fullspec.mark ?? {})
     out.mark.type = this.mark.type && (fullspec.mark?.type ?? true)
@@ -427,7 +432,7 @@ function inspectpeg(peg: any, d: number) {
     ('{' +
       Object.entries(peg).map((n: any) =>
         '\n  ' + indent + n[0] + ': ' + // n[1].inspect(d)
-        (n[1].inspect(d) ?? '' + n[1])
+        n[1].inspect(d)
       ).join(',') +
       '\n' + indent + '}')
   )
@@ -448,7 +453,7 @@ function empty(o: any) {
     || (null != o && 'object' === typeof o && 0 === Object.keys(o).length)
     || false
   )
-}
+} /* node:coverage ignore next 16 */
 
 
 

package/src/val/VarVal.ts

@@ -30,6 +30,7 @@ import { NullVal } from './NullVal'
 import { BooleanVal } from './BooleanVal'
 import { NumberVal } from './NumberVal'
 import { IntegerVal } from './IntegerVal'
+import { isIntegerKind } from './numkind'
 
 
 import {
@@ -106,7 +107,12 @@ class VarVal extends FeatureVal {
           out = new BooleanVal({ peg: found })
         }
         else if ('number' === ft) {
-          out = Number.isInteger(found) ?
+          // A raw var binding carries no source text, so the integral +
+          // int64-range conditions decide the kind (same helper as the
+          // val rule and rawToVal).
+          // (ctx.vars is declared as Record<string, Val> but also
+          // carries raw scalars, which is what `ft` has just proven.)
+          out = isIntegerKind(found as unknown as number) ?
             new IntegerVal({ peg: found }) :
             new NumberVal({ peg: found })
         }
@@ -183,7 +189,7 @@ class VarVal extends FeatureVal {
 
     return undefined
   }
-}
+} /* node:coverage ignore next 6 */
 
 
 export {

package/src/val/numcmp.ts

@@ -0,0 +1,189 @@
+/* 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'
+
+
+// A comparison-internal exact rational with a power-of-ten denominator.
+// `inf` marks the two binary64 infinities, which some float leaf value
+// could in principle carry; NaN cannot reach a scalar (the parser has
+// no spelling for it) and is rejected by the atom constructors.
+type Scaled = {
+  inf?: 1 | -1
+  unscaled: bigint     // signed
+  scale: number        // value = unscaled / 10^scale, scale >= 0
+}
+
+
+const F64 = new DataView(new ArrayBuffer(8))
+
+
+// The exact scaled-decimal value of a finite or infinite binary64.
+function scaledOfFloat(f: number): Scaled {
+  if (Number.isInteger(f) && Math.abs(f) <= Number.MAX_SAFE_INTEGER) {
+    return { unscaled: BigInt(f), scale: 0 }
+  }
+  if (Infinity === f) {
+    return { inf: 1, unscaled: 0n, scale: 0 }
+  }
+  if (-Infinity === f) {
+    return { inf: -1, unscaled: 0n, scale: 0 }
+  }
+
+  F64.setFloat64(0, f)
+  const hi = BigInt(F64.getUint32(0))
+  const lo = BigInt(F64.getUint32(4))
+  const bits = (hi << 32n) | lo
+
+  const sign = (bits >> 63n) & 1n ? -1n : 1n
+  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) {
+    mant = frac
+    exp = -1074
+  }
+  else {
+    mant = frac | (1n << 52n)
+    exp = expBits - 1075
+  }
+
+  if (0 <= exp) {
+    return { unscaled: sign * (mant << BigInt(exp)), scale: 0 }
+  }
+  // mant * 2^-k == mant * 5^k / 10^k, exactly.
+  return { unscaled: sign * mant * 5n ** BigInt(-exp), scale: -exp }
+}
+
+
+// The exact scaled-decimal value of any numeric leaf Val.
+function scaledOfNumeric(v: any): Scaled {
+  if (v.isBigInteger) {
+    return { unscaled: v.peg as bigint, scale: 0 }
+  }
+  if (v.isBigDecimal) {
+    const d = v.peg as Decimal
+    return { unscaled: d.unscaled, scale: d.scale }
+  }
+  // integer and float leaves both hold a binary64.
+  return scaledOfFloat(v.peg as number)
+}
+
+
+function pow10(n: number): bigint {
+  return 10n ** BigInt(n)
+}
+
+
+// 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
+  if (0 !== ai || 0 !== bi) {
+    return ai < bi ? -1 : ai > bi ? 1 : 0
+  }
+  let au = a.unscaled
+  let bu = b.unscaled
+  if (a.scale < b.scale) {
+    au *= pow10(b.scale - a.scale)
+  }
+  else if (b.scale < a.scale) {
+    bu *= pow10(a.scale - b.scale)
+  }
+  return au < bu ? -1 : au > bu ? 1 : 0
+}
+
+
+// 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
+  while (ai < a.length && bi < b.length) {
+    const ac = a.codePointAt(ai) as number
+    const bc = b.codePointAt(bi) as number
+    if (ac !== bc) {
+      return ac < bc ? -1 : 1
+    }
+    ai += ac > 0xffff ? 2 : 1
+    bi += bc > 0xffff ? 2 : 1
+  }
+  const ar = a.length - ai
+  const br = b.length - bi
+  return ar < br ? -1 : ar > br ? 1 : 0
+}
+
+
+// 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
+}
+
+
+// True when the scaled value is integral (an exact whole number).
+function scaledIsIntegral(s: Scaled): boolean {
+  if (s.inf) {
+    return false
+  }
+  if (0 === s.scale) {
+    return true
+  }
+  const p = pow10(s.scale)
+  return 0n === s.unscaled % p
+}
+
+
+// The exact floor of a scaled value, as a bigint. Infinite inputs are
+// the caller's job to exclude.
+function scaledFloor(s: Scaled): bigint {
+  if (0 === s.scale) {
+    return s.unscaled
+  }
+  const p = pow10(s.scale)
+  const q = s.unscaled / p
+  // BigInt division truncates toward zero; floor rounds down.
+  return (s.unscaled < 0n && 0n !== s.unscaled % p) ? q - 1n : q
+} /* node:coverage ignore next 14 */
+
+
+export {
+  Scaled,
+  scaledOfFloat,
+  scaledOfNumeric,
+  cmpScaled,
+  cmpNumeric,
+  cmpCodePoints,
+  towerRank,
+  scaledIsIntegral,
+  scaledFloor,
+}

package/src/val/numkind.ts

@@ -0,0 +1,256 @@
+/* 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
+  }
+
+  let exact: bigint
+
+  const dec = DEC_INT_LITERAL_RE.exec(src)
+  if (null != dec) {
+    // A negative exponent does not denote an integer -- out of scope.
+    const exp = null == dec[3] ? 0 : Number(stripSep(dec[3]))
+    if (!(0 <= exp) || !Number.isFinite(exp)) {
+      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
+    }
+    exact = coeff * 10n ** BigInt(exp)
+  }
+  else {
+    const base = BASE_INT_LITERAL_RE.exec(src)
+    if (null == base) {
+      return false
+    }
+    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)
+}
+
+
+// `[+-]? digits [ (e|E) [+-] digits ]`, with the landed single-`_`-
+// between-digits separator rule. No `.`: that is a float source (R1).
+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])*)$/
+
+// Above this the value cannot be finite in binary64, so it cannot be
+// exact either, and 10n ** BigInt(exp) must not be built.
+const MAX_EXPONENT = 400
+
+// 2^53, the point at which the integers stop being contiguous in
+// binary64 and so the first magnitude at which a literal can be lossy.
+const POW53 = 9007199254740992
+
+
+function stripSep(s: string): string {
+  return -1 === s.indexOf('_') ? s : s.replace(/_/g, '')
+}
+
+
+// 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,
+  isIntegerKind,
+  isIntegerStorable,
+  isLossyIntegerLiteral,
+}

package/src/val/valutil.ts

@@ -3,9 +3,14 @@
 import { AontuError } from '../err'
 import { ScalarVal } from './ScalarVal'
 import { NumberVal } from './NumberVal'
+import { IntegerVal } from './IntegerVal'
 import { StringVal } from './StringVal'
 import { BooleanVal } from './BooleanVal'
 import { NullVal } from './NullVal'
+import { BigIntegerVal } from './BigIntegerVal'
+import { BigDecimalVal } from './BigDecimalVal'
+import { Decimal } from './Decimal'
+import { isIntegerKind } from './numkind'
 
 
 // TODO: move to FuncBaseVal
@@ -29,3 +34,34 @@ export function makeScalar(scalar: any): ScalarVal {
     throw new AontuError('Not a scalar: ' + scalar)
   }
 }
+
+
+// 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 })
+  }
+  if (scalar instanceof Decimal) {
+    return new BigDecimalVal({ peg: scalar })
+  }
+  if ('number' === typeof scalar &&
+    true === like?.isInteger &&
+    isIntegerKind(scalar)) {
+    return new IntegerVal({ peg: scalar })
+  }
+  return makeScalar(scalar)
+}