aontu 0.52.1 → 0.53.0

package/src/val/Val.ts

@@ -8,6 +8,8 @@ import {
   Site
 } from '../site'
 
+import { INNER_OF, WRITTEN } from '../provenance'
+
 
 type ValMark = {
   type: boolean,
@@ -22,6 +24,21 @@ type ValSpec = {
   mark?: Partial<ValMark>,
   kind?: any,
 
+  // THE PER-DESTINATION INSTANTIATION FLAG (ADR-005). A generator's
+  // template is cloned once per destination, and every clone must be
+  // a full instance: nothing path-dependent may be shared between two
+  // destinations, or the first destination's resolution answers for
+  // them all. The default clone shares inner structure deliberately
+  // (`peg: this.peg` below — the move()/copy() ghost rows in
+  // test/spec/func.tsv pin that sharing), so instantiation asks for
+  // depth explicitly: `dup: true` makes FuncBaseVal, PrefVal and
+  // OpBaseVal clone their inner Vals too, and the bag/junction clones
+  // carry the flag down. Set by pack/each template instantiation,
+  // filter condition testing, and spread application (MapVal/
+  // ListVal.spreadClone) — never by the residuation or ref-resolution
+  // clones, whose sharing is pinned behaviour.
+  dup?: boolean,
+
 
   row?: number,
   col?: number,
@@ -63,6 +80,17 @@ const EMPTY_ERR: any[] = Object.freeze([]) as unknown as any[]
 let ID = 1000
 
 
+// A fresh Val id, for the one carrier that cannot take the one its
+// class fixes: TopVal pins `id = 0` (there is only one top), and the
+// identity mark (G4 phase 1) resolves to a top that must NOT collide
+// with it — the fast path in `unite` returns early on two done Vals
+// with the same id, which would drop an identity before the rider
+// could carry it.
+export function nextValId(): number {
+  return ID++
+}
+
+
 abstract class Val {
   // Type-discriminator flags: defaults live on Val.prototype (see
   // bottom of this file). Each subclass overrides only its own
@@ -134,6 +162,37 @@ abstract class Val {
     hide: false,
   }
 
+  // The deprecation record (G3 phase 4, `deprecate(x, m)`): boolean
+  // marks cannot hold a message, a replacement path and a version, so
+  // the Val carries one optional record. Keys are the three the
+  // builtin defines (msg, use, since), all optional, values strings;
+  // `use` is a path spelled as a STRING — a live reference would
+  // resolve and unify, which is not wanted. Propagated through meets
+  // by propagateMarks and carried by clone, exactly as the boolean
+  // marks are.
+  deprecation?: Record<string, string>
+
+  // The IDENTITY (G4 phase 1, `id(name)`): the entity this value IS.
+  // A separate slot for the same reason the deprecation record has
+  // one — a boolean ValMark cannot hold a name — and carried through
+  // meets by the same rider in `unite`. Unlike the marks, canon
+  // RENDERS it: identity is semantic content, and G6's hash must see
+  // it.
+  entity?: string
+
+  // The LINK (G4 phase 2/3): the entity address a `refer` resolved to,
+  // stamped on the string it answers. The string IS the value — a
+  // link, not an embedding — so nothing downstream could otherwise
+  // tell a checked link from a literal that happens to look like one,
+  // and the edge set (ts/src/graph.ts) is exactly the set of these.
+  link?: string
+
+  // The GRAPH of an evaluated document (G4 phase 3): the entity index
+  // and the edge set, stamped on the result by Aontu.unify the way the
+  // include manifest is. Absent on every Val that is not a unify
+  // result.
+  graph?: any
+
   // Actual native value.
   peg: any = undefined
 
@@ -225,11 +284,71 @@ abstract class Val {
     out.site.row = spec?.row ?? this.site.row
     out.site.col = spec?.col ?? this.site.col
     out.site.url = spec?.url ?? this.site.url
+    // THE SPAN TRAVELS WITH THE POSITION. Copying row and col but not
+    // the extent would leave a site that names a place and denies it has
+    // any width — internally inconsistent, and it made the two ports
+    // disagree on every derived value (the shared subsume rows caught
+    // it). Safe because the span is VERIFIABLE: a consumer reads the
+    // document at (row, col, len) and refuses when it does not match
+    // `src`, so a span that has stopped describing its value is
+    // detectable rather than believed. See ts/src/site.ts.
+    //
+    // Read from `this.site`, never from the spec: ValSpec.src is a
+    // DIFFERENT field — ScalarVal's literal spelling, kept so `$.a.0x0`
+    // addresses the key `0x0` — and reading it here would put a path
+    // segment where a source span belongs.
+    //
+    // UNCONDITIONAL, as the Go twin is (clonePath, go/clone.go). A
+    // guard dropping the span when the spec relocates the value was
+    // written first and the coverage gate refused it as dead: nothing
+    // clones to a new row or column. Should a relocating caller ever
+    // appear it must drop both fields — an extent belongs to a place,
+    // and the text at a new one is not this value's to claim.
+    out.site.len = this.site.len
+    out.site.src = this.site.src
 
     out.mark = Object.assign({}, this.mark, fullspec.mark ?? {})
     out.mark.type = this.mark.type && (fullspec.mark?.type ?? true)
     out.mark.hide = this.mark.hide && (fullspec.mark?.hide ?? true)
 
+    // The two IDENTITY riders travel together, under one test: the
+    // entity a value IS, and the address a resolved link POINTS AT.
+    // One guard rather than two because the pair is what a clone
+    // either carries or does not — and because a second test for the
+    // link alone would be a branch no document takes, the reference
+    // clone catching the pending residual before it ever resolves.
+    if (null != this.entity || null != this.link) {
+      out.entity = this.entity
+      out.link = this.link
+    }
+    if (null != this.deprecation) {
+      out.deprecation = this.deprecation
+    }
+
+    // PROVENANCE TRAVELS WITH THE CLONE, exactly as the site does, and
+    // for the same reason: a clone of a value the author wrote IS that
+    // written value somewhere else, and it carries the author's site,
+    // so it can be pointed at. Without this a default reaching a
+    // `pack()`-generated child, or a shape carried by a `$ref`, was
+    // invisible to `why` -- which answered "nothing met at this path"
+    // over a value it had just printed (the review's finding E). See
+    // WRITTEN in ts/src/provenance.ts; the mark is only ever set by an
+    // instrumented run, so this is one undefined read otherwise.
+    if (true === (this as any)[WRITTEN]) {
+      (out as any)[WRITTEN] = true
+    }
+    // AND SO DOES BEING PART OF SOMETHING. A clone of a disjunction's
+    // member is still that member of that written disjunction, and the
+    // whole statement is what the author needs shown -- otherwise a
+    // default reaching a generated child reports `*"info"` and
+    // `string` as two contributions at two columns, where the author
+    // wrote `*info | string` once. A number, deliberately: a Val
+    // holding another Val as an own property is a cycle through the
+    // tree. See INNER_OF in ts/src/provenance.ts.
+    if (null != (this as any)[INNER_OF]) {
+      (out as any)[INNER_OF] = (this as any)[INNER_OF]
+    }
+
     return out
   }
 
@@ -237,8 +356,17 @@ abstract class Val {
   // Shallow clone for spread constraints: creates a new Val with the
   // correct path context but shares non-path-dependent children.
   // Override in MapVal/ListVal to avoid deep-cloning simple children.
+  //
+  // A FULL INSTANCE (`dup`, ADR-005): a spread constraint is applied
+  // once per destination child, and each application must own its
+  // path-dependent innards — a bare clone shared a call's arguments
+  // and a preference's inner value across destinations, so a spread
+  // like `&: id(key(0)) & $.schema.C` resolved its one shared key()
+  // at the first child it met (use-cases/BUGS.md §12's id_name form).
   spreadClone(ctx: AontuContext): Val {
-    return this.clone(ctx)
+    const out = this.clone(ctx, { dup: true })
+    repathInstance(out, out.path)
+    return out
   }
 
 
@@ -278,10 +406,26 @@ abstract class Val {
   }
 
 
+  // PUT A MINTED VALUE WHERE THIS ONE STANDS: the site travels, and so
+  // does provenance, because the two answer one question. A narrowed
+  // disjunction, a lifted kind, a resolved reference -- each is a
+  // value the engine built from a value the author wrote, standing
+  // where that one stood. Carrying the site and withholding the mark
+  // would let `why` print a value, know the line it came from, and
+  // still answer "nothing met at this path" (the review's finding E).
+  // See WRITTEN and INNER_OF in ts/src/provenance.ts.
   place(v: Val) {
     v.site.row = this.site.row
     v.site.col = this.site.col
     v.site.url = this.site.url
+    v.site.len = this.site.len
+    v.site.src = this.site.src
+    if (true === (this as any)[WRITTEN]) {
+      (v as any)[WRITTEN] = true
+    }
+    if (null != (this as any)[INNER_OF]) {
+      (v as any)[INNER_OF] = (this as any)[INNER_OF]
+    }
     return v
   }
 
@@ -431,6 +575,64 @@ Object.assign(Val.prototype, {
 })
 
 
+// THE INSTANCE PATH NORMALISATION (ADR-005), the TS mirror of the Go
+// port's setPaths (go/clone.go): assign every value in a freshly
+// instantiated template the path the PARSER would have given it at the
+// instance's destination. A deep instance clone (`dup`) copies values
+// whose stored parse paths are argument-shaped — a func argument has
+// no key of its own, a spread template lives under a '&' segment — and
+// Val.clone's ctx-cut cannot rebase those: it derives the child path
+// from the driving ctx alone and drops the segments in between, which
+// is how a nested list spread inside a close()d template lost its
+// parent key and every finding under it named the wrong path (the
+// 06-k8s use case's env findings). One canonical walk instead:
+// bag children descend by key (numeric for a list element, as the
+// parser records them), a spread constraint sits under '&' with its
+// content at the bag's own path, and junction members, operator
+// operands, function arguments and a preference's value all sit AT
+// their holder's path — exactly the parse-time shape.
+function repathInstance(v: any, path: string[]): void {
+  if (true !== v?.isVal) {
+    return
+  }
+  v.path = path
+
+  const peg = v.peg
+
+  if (true === v.isBag) {
+    const spread = v.spread?.cj
+    if (null != spread && true === spread.isVal) {
+      // The spread's CONTENT is pathed at the bag (its fields land on
+      // the bag's children); only its ROOT carries the '&' segment —
+      // the same two steps as the Go twin's setPaths.
+      repathInstance(spread, path)
+      spread.path = [...path, '&']
+    }
+    if (true === v.isList) {
+      for (let i = 0; i < peg.length; i++) {
+        // Numeric, as the parser records list positions: a numeric
+        // segment is what tells key() an element is not a keyed
+        // position (KeyFuncVal.resolve, `positioned`).
+        repathInstance(peg[i], [...path, i as unknown as string])
+      }
+    }
+    else {
+      for (const k of Object.keys(peg)) {
+        repathInstance(peg[k], [...path, k])
+      }
+    }
+  }
+  else if (Array.isArray(peg)) {
+    for (const t of peg) {
+      repathInstance(t, path)
+    }
+  }
+  else if (true === peg?.isVal) {
+    repathInstance(peg, path)
+  }
+}
+
+
 function inspectpeg(peg: any, d: number) {
   const indent = '  '.repeat(d)
   return pretty(Array.isArray(peg) ?
@@ -474,5 +676,6 @@ export {
   DONE,
   SPREAD,
   EMPTY_ERR,
-  empty
+  empty,
+  repathInstance,
 }

package/src/val/VarVal.ts

@@ -24,7 +24,6 @@ import {
 
 
 import { StringVal } from './StringVal'
-import { NilVal } from './NilVal'
 import { FeatureVal } from './FeatureVal'
 import { NullVal } from './NullVal'
 import { BooleanVal } from './BooleanVal'

package/src/val/arith.ts

@@ -0,0 +1,316 @@
+/* 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'
+import { makeNilErr } from '../err'
+
+import { IntegerVal } from './IntegerVal'
+import { NumberVal } from './NumberVal'
+import { BigIntegerVal } from './BigIntegerVal'
+import { BigDecimalVal } from './BigDecimalVal'
+import { Decimal, decimalOverBudget } from './Decimal'
+import { isIntegerStorable } from './numkind'
+
+
+type ArithOp = 'add' | 'sub' | 'mul' | 'div' | 'mod' | 'rem'
+
+// The three that divide, and therefore the three that can be handed a
+// zero divisor and cannot answer over the decimal leaf.
+function divides(op: ArithOp): boolean {
+  return 'div' === op || 'mod' === op || 'rem' === op
+}
+
+
+// The numeric leaves, told apart by their own flags rather than by the
+// JavaScript type of the peg: `integer` and `float` share `number`.
+type ArithKind = 'integer' | 'float' | 'biginteger' | 'bigdecimal'
+
+const EXACT_RANK: Record<string, number> = {
+  integer: 1,
+  biginteger: 2,
+  bigdecimal: 3,
+}
+
+
+function isBig(k: ArithKind): boolean {
+  return 'biginteger' === k || 'bigdecimal' === k
+}
+
+
+// A pref operand contributes its preferred value, and therefore that
+// value's kind too -- the same rule `+` applies.
+function unpref(v: any): any {
+  while (v?.isPref) {
+    v = v.peg
+  }
+  return v
+}
+
+
+function arithKind(v: any): ArithKind | undefined {
+  if (!(v?.isVal && v.isScalar)) {
+    return undefined
+  }
+  if (v.isBigInteger) {
+    return 'biginteger'
+  }
+  if (v.isBigDecimal) {
+    return 'bigdecimal'
+  }
+  if (v.isInteger) {
+    return 'integer'
+  }
+  return 'number' === typeof v.peg ? 'float' : 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)
+}
+
+
+function asDecimal(v: any, k: ArithKind): Decimal {
+  return 'bigdecimal' === k ? v.peg : new Decimal(asInteger(v, k), 0)
+}
+
+
+// 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,
+  node: Val,
+  a: Val,
+  b: Val,
+  attempt?: string
+): Val {
+  const name = attempt ?? op
+  const av: any = unpref(a)
+  const bv: any = unpref(b)
+  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)
+  }
+
+  // A big leaf never silently becomes a binary float, in EITHER operand
+  // order. The error names both leaves in operand order.
+  if (('float' === ak && isBig(bk)) || (isBig(ak) && 'float' === bk)) {
+    return makeNilErr(ctx, 'exact_float_mix', node, undefined, name,
+      { left: ak, right: bk })
+  }
+
+  if ('float' === ak || 'float' === bk) {
+    return floatArith(ctx, op, name, node, av.peg, bv.peg)
+  }
+
+  const rank = EXACT_RANK[bk] < EXACT_RANK[ak] ? EXACT_RANK[ak] : EXACT_RANK[bk]
+
+  if (EXACT_RANK.bigdecimal === rank) {
+    return decimalArith(ctx, op, name, node, asDecimal(av, ak), asDecimal(bv, bk))
+  }
+
+  return integerArith(ctx, op, name, node, asInteger(av, ak),
+    asInteger(bv, bk), EXACT_RANK.biginteger === rank)
+}
+
+
+// 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,
+  name: string,
+  node: Val,
+  x: number,
+  y: number
+): Val {
+  if (divides(op) && 0 === y) {
+    return makeNilErr(ctx, 'divide_by_zero', node, undefined, name)
+  }
+
+  const out =
+    'add' === op ? x + y :
+      'sub' === op ? x - y :
+        'mul' === op ? x * y :
+          'div' === op ? x / y :
+            // 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) ?
+    new NumberVal({ peg: out }) :
+    makeNilErr(ctx, 'float_overflow', node, undefined, name)
+}
+
+
+function flooredMod(rem: number, y: number): number {
+  return 0 !== rem && (rem < 0) !== (y < 0) ? rem + y : rem
+}
+
+
+// The exact integral leaves. Both compute in bigint, so nothing passes
+// through binary64 and nothing rounds; only the storage test at the end
+// differs, because `biginteger` is unbounded and `integer` is not.
+function integerArith(
+  ctx: AontuContext | undefined,
+  op: ArithOp,
+  name: string,
+  node: Val,
+  x: bigint,
+  y: bigint,
+  big: boolean
+): Val {
+  if (divides(op) && 0n === y) {
+    return makeNilErr(ctx, 'divide_by_zero', node, undefined, name)
+  }
+
+  const out =
+    '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)
+
+  if (big) {
+    // Unbounded and exact: nothing to check, and no demotion to
+    // `integer` however small the result.
+    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,
+      { sum: out.toString() })
+}
+
+
+function flooredModBig(rem: bigint, y: bigint): bigint {
+  return 0n !== rem && (rem < 0n) !== (y < 0n) ? rem + y : rem
+}
+
+
+// The decimal leaf. Addition, subtraction and multiplication are exact
+// coefficient arithmetic and land here; division does not, and says so.
+function decimalArith(
+  ctx: AontuContext | undefined,
+  op: ArithOp,
+  name: string,
+  node: Val,
+  x: Decimal,
+  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)
+  }
+
+  const out =
+    'add' === op ? x.add(y) :
+      'sub' === op ? x.add(y.negate()) :
+        x.multiply(y)
+
+  // The budget applies to RESULTS as well as literals: an exact answer
+  // too wide to hold is refused, never rounded to fit.
+  return decimalOverBudget(out) ?
+    makeNilErr(ctx, 'decimal_budget', node, undefined, name) :
+    new BigDecimalVal({ peg: out })
+} /* node:coverage ignore next 9 */
+
+
+export type {
+  ArithOp,
+}
+
+export {
+  arith,
+}