aontu 0.52.1 → 0.53.0

package/src/val/AggFuncVal.ts

@@ -0,0 +1,319 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// AGGREGATION AND PROJECTION: `sum(d)`, `least(d)`, `greatest(d)`
+// and `pick(d, k)`.
+//
+// The review's finding I: "No aggregation. `length()` counts but
+// nothing sums: an invoice total, a fleet-wide resource budget, a quota
+// roll-up -- all inexpressible." Use case 10 had to write totals by
+// hand and spot-check them with `must()`, which is a model asserting
+// what it should be able to COMPUTE.
+//
+//   total:   sum($.lines)                 # an invoice total
+//   cheapest: least($.quotes)             # ... and the extremes
+//   peak:    greatest($.hourly)
+//
+// A FOLD OVER A FINITE, SETTLED BAG IS AS TOTAL AS `each`. There is no
+// recursion here and no user-supplied step: the bag is the one the
+// model already holds, the operation is fixed, and the walk visits each
+// child exactly once. That is the whole reason these are built-ins
+// rather than a `fold` combinator -- a fold takes a function, and a
+// language with no user functions has none to take.
+//
+// THE NAMES ARE `least` AND `greatest`, NOT `min` AND `max`, because
+// those two are already the constraint atoms for a LOWER and UPPER
+// BOUND (`min(3)` means "at least 3"). An aggregate over a bag and a
+// bound on a value are different things and must not share a spelling;
+// least and greatest are the lattice's own words for the extremes of a
+// set, which is exactly what these compute.
+//
+// `sum` FOLDS WITH `add`, so the number tower's whole law comes with it
+// (arith.ts): the exact ladder, R5 contagion, the refusal to mix a
+// binary float with an exact leaf, and the refusal to store a result
+// that will not fit. A bag of integers sums to an integer; one integer
+// float among them makes the total a float; `0d` operands keep it
+// exact. And `sum([])` is `0` -- addition has an identity, which is
+// what makes the empty case answerable.
+//
+// `least`/`greatest` have NO identity to answer an empty bag with: the
+// least element of nothing is not a value, it is a question with no
+// answer, so an empty bag is a located `aggregate_empty` rather than an
+// invented zero or infinity. They compare with the tower's EXACT
+// comparator (numcmp), so an integer and a bigdecimal in one bag order
+// correctly rather than through binary64, and the winner is returned
+// with its own kind intact.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+import { IntegerVal } from './IntegerVal'
+import { ListVal } from './ListVal'
+import { FuncBaseVal } from './FuncBaseVal'
+import { arith } from './arith'
+import { cmpNumeric } from './numcmp'
+
+
+type AggOp = 'sum' | 'least' | 'greatest'
+
+
+// The children of a bag, in the order the aggregate sees them: source
+// order for a list, sorted-key order for a map -- `each`'s order, and
+// for the same reason (a map has no order of its own, so the language
+// picks one and states it).
+function bagChildren(data: any): Val[] | undefined {
+  if (true === data?.isList) {
+    return data.peg as Val[]
+  }
+  if (true === data?.isMap) {
+    return Object.keys(data.peg).sort().map((k: string) => data.peg[k])
+  }
+  return undefined
+}
+
+
+class AggFuncVal extends FuncBaseVal {
+  isAggFunc = true
+
+  // THE STAGING RULE (G8 phase 0). A total over a bag that is still
+  // being merged into is a total of the wrong bag -- the same reason
+  // `filter` and `each` wait.
+  staged = true
+
+  op: AggOp
+
+  constructor(
+    spec: ValSpec,
+    ctx: AontuContext | undefined,
+    op: AggOp
+  ) {
+    super(spec, ctx)
+    this.op = op
+  }
+
+
+  // NO `make` OVERRIDE, matching the other STAGED funcs (pack, each,
+  // filter, match): a staged call returns `residuate` before `unify`
+  // ever reaches the rebuild branch, so an override there would be
+  // unreachable code pretending to be a contract. The base's `make`
+  // raises `func:<name>` if that ever stops being true, which is the
+  // loud answer rather than a value that silently lost its operation.
+
+  funcname() {
+    return this.op
+  }
+
+
+  // The base does not drive the argument: `unify` drives it by hand,
+  // because a staged func must advance what it is waiting on every
+  // pass rather than only on the pass it fires.
+  prepare(_ctx: AontuContext, _args: Val[]) {
+    return null
+  }
+
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const ready = this.driveStagedArgs(ctx, 1)
+
+    if (!ready || !ctx.settle) {
+      return this.residuate(peer, ctx)
+    }
+
+    return super.unify(peer, ctx)
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const children = bagChildren(args?.[0])
+
+    if (undefined === children) {
+      return this.place(makeNilErr(ctx, 'aggregate_data', this, undefined,
+        this.op))
+    }
+
+    if ('sum' === this.op) {
+      // Zero is addition's identity, so an empty bag has an answer and
+      // it is an integer -- the narrowest kind, which the first real
+      // operand then widens under R5 exactly as `add(0, x)` would.
+      let total: Val = new IntegerVal({ peg: 0 })
+      for (const child of children) {
+        total = arith(ctx, 'add', this, total, child, this.op)
+        // A refusal inside the fold IS the answer: adding on past a
+        // non-numeric child or an overflow would report the wrong
+        // reason, or none.
+        if (true === (total as any).isNil) {
+          return this.place(total)
+        }
+      }
+      return this.place(total)
+    }
+
+    if (0 === children.length) {
+      return this.place(makeNilErr(ctx, 'aggregate_empty', this, undefined,
+        this.op))
+    }
+
+    const want = 'least' === this.op ? -1 : 1
+    let best: any = undefined
+    for (const child of children) {
+      const c: any = unpref(child)
+      if (!(c?.isVal && c.isScalar && 'string' !== typeof c.peg &&
+        'boolean' !== typeof c.peg && !c.isNull)) {
+        return this.place(makeNilErr(ctx, 'invalid-arg', this, undefined,
+          this.op))
+      }
+      // The EXACT comparator (numcmp), never binary64: a bigdecimal and
+      // an integer in one bag must order by their values and not by
+      // whatever their float images happen to be.
+      if (undefined === best || want === cmpNumeric(c, best)) {
+        best = c
+      }
+    }
+    // The winner is returned as itself, so it keeps its own kind: the
+    // least of a bag of bigdecimals is a bigdecimal.
+    return this.place(best.clone(ctx))
+  }
+}
+
+
+// A pref child contributes its preferred value, and therefore that
+// value's kind too -- the rule `+` and the arithmetic family apply to
+// operands, applied here to bag members.
+function unpref(v: any): any {
+  while (v?.isPref) {
+    v = v.peg
+  }
+  return v
+}
+
+
+// PROJECTION: `pick(d, k)` -- one element per child of `d`, being that
+// child's `k`.
+//
+// The other half of the review's finding I: "`_.field` is unspellable,
+// `filter` cannot see into lists, `unique()`-by-field is reserved but
+// absent -- so 'no two services share a port' and 'unique event ids'
+// cannot be said." Without it the aggregates above cannot reach the
+// case that motivated them, because `sum` needs a bag of NUMBERS and a
+// model holds a bag of RECORDS:
+//
+//   total: sum(pick($.lines, amountCents))
+//
+// IT IS NOT `each` WITH A CLEVER TEMPLATE. `each(d, t)` MEETS each
+// child with `t`, and a meet cannot select: `each($.lines, _.amount)`
+// asks for a child that is simultaneously the whole record and one of
+// its fields, which is why every spelling of it answers `no_path`.
+// Selection is a different operation and gets its own verb.
+//
+// A CHILD MISSING THE KEY IS AN ERROR, not a silently shorter list.
+// Skipping would make `sum(pick(...))` quietly total the wrong set of
+// records -- the failure mode an aggregate exists to prevent -- so the
+// refusal names the child (`pick_key`).
+class PickFuncVal extends FuncBaseVal {
+  isPickFunc = true
+
+  // The bag must settle before it is projected, exactly as it must
+  // before it is folded.
+  staged = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+  funcname() {
+    return 'pick'
+  }
+
+
+  // The base drives neither argument: the DATA is driven by hand below
+  // (a staged func must advance what it waits on every pass), and the
+  // KEY is a bare word, which the parser has already made a string.
+  prepare(_ctx: AontuContext, _args: Val[]) {
+    return null
+  }
+
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const ready = this.driveStagedArgs(ctx, 1)
+
+    if (!ready || !ctx.settle) {
+      return this.residuate(peer, ctx)
+    }
+
+    return super.unify(peer, ctx)
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const children = bagChildren(args?.[0])
+    const key: any = args?.[1]
+
+    if (undefined === children) {
+      return this.place(makeNilErr(ctx, 'aggregate_data', this, undefined,
+        'pick'))
+    }
+
+    // The key is a STRING for a map child and the decimal spelling of an
+    // index for a list child -- the same rule a reference segment
+    // follows, so `pick(d, 0)` and `$.d.0.x` agree about what `0` names.
+    const name = null == key?.peg ? undefined :
+      'string' === typeof key.peg ? key.peg :
+        'number' === typeof key.peg && key.isInteger ? String(key.peg) :
+          undefined
+
+    if (undefined === name) {
+      return this.place(makeNilErr(ctx, 'invalid-arg', this, undefined,
+        'pick'))
+    }
+
+    const peg: Val[] = []
+    for (const child of children) {
+      const c: any = child
+      const got =
+        true === c?.isMap ? c.peg[name] :
+          true === c?.isList ? c.peg[Number(name)] :
+            undefined
+      if (null == got) {
+        return this.place(makeNilErr(ctx, 'pick_key', this, undefined, 'pick',
+          { key: name }))
+      }
+      peg.push(got.clone(ctx.descend(String(peg.length))))
+    }
+    return this.place(new ListVal({ peg }, ctx))
+  }
+}
+
+
+// The three the registry names. Each is its operation and nothing else.
+class SumFuncVal extends AggFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'sum') }
+}
+
+class LeastFuncVal extends AggFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'least') }
+}
+
+class GreatestFuncVal extends AggFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx, 'greatest')
+  }
+} /* node:coverage ignore next 9 */
+
+
+export {
+  AggFuncVal,
+  PickFuncVal,
+  SumFuncVal,
+  LeastFuncVal,
+  GreatestFuncVal,
+}

package/src/val/ArithFuncVal.ts

@@ -0,0 +1,108 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { FuncBaseVal } from './FuncBaseVal'
+import { arith } from './arith'
+import type { ArithOp } from './arith'
+
+
+// ONE CLASS FOR SIX FUNCTIONS, because every rule they obey is a rule
+// about arithmetic rather than about any one operation (see arith.ts).
+// Six near-identical classes would be six places for the exact ladder,
+// the zero divisor and the storage contract to drift apart, and the
+// number tower's whole point is that they cannot.
+//
+// The op is carried on the instance and answered by `funcname()`, which
+// is what canon renders and what an error names. The six one-line
+// subclasses below exist only because the parser's registry constructs
+// with `new funcval({peg: args})` and has nowhere to put a name; every
+// line of behaviour is here.
+class ArithFuncVal extends FuncBaseVal {
+  isArithFunc = true
+
+  // The operation this call performs. Carried on the instance because
+  // `make` rebuilds the value during residuation and must rebuild the
+  // SAME function.
+  op: ArithOp
+
+  constructor(
+    spec: ValSpec,
+    ctx: AontuContext | undefined,
+    op: ArithOp
+  ) {
+    super(spec, ctx)
+    this.op = op
+  }
+
+
+  // Rebuilt as its own class, carrying its own op: residuation must not
+  // turn a `sub` into a bare arithmetic call with no operation.
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new (this.constructor as any)(spec, undefined, this.op)
+  }
+
+  funcname() {
+    return this.op
+  }
+
+
+  resolve(ctx: AontuContext | undefined, args: Val[]) {
+    return this.place(arith(ctx, this.op, this, args?.[0], args?.[1]))
+  }
+
+
+  // NO superior() OVERRIDE, deliberately. An arithmetic call could only
+  // advertise a kind once both its operands were concrete scalars -- and
+  // at that point it has RESOLVED, so what `super()` sees is the result,
+  // whose own superior is already the right answer:
+  // `super(mul(2,3))` is `integer` and `super(mul(2,1.5))` is `float`,
+  // through the value rather than through a promise about it. The
+  // override was written and then removed as unreachable; the same is
+  // true of FuncVal.superior in the Go port.
+}
+
+
+// The six the registry names. Each is its operation and nothing else.
+class AddFuncVal extends ArithFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'add') }
+}
+
+class SubFuncVal extends ArithFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'sub') }
+}
+
+class MulFuncVal extends ArithFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'mul') }
+}
+
+class DivFuncVal extends ArithFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'div') }
+}
+
+class ModFuncVal extends ArithFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'mod') }
+}
+
+class RemFuncVal extends ArithFuncVal {
+  constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'rem') }
+} /* node:coverage ignore next 11 */
+
+
+export {
+  ArithFuncVal,
+  AddFuncVal,
+  SubFuncVal,
+  MulFuncVal,
+  DivFuncVal,
+  ModFuncVal,
+  RemFuncVal,
+}

package/src/val/BagVal.ts

@@ -49,20 +49,90 @@ abstract class BagVal extends FeatureVal {
 
 
   handleExpectedVal(key: string, val: Val, parent: Val, ctx: AontuContext): Val {
-    if (val.isGenable) {
+    // A MARKED value is carried, never expected (ADR-005 era, BUGS.md
+    // §12's include form): a type()/hide()-marked child legitimately
+    // participates in unification without ever generating — that is
+    // the marks contract — so wrapping one as an expectation turned a
+    // schema field arriving through an include's map meet into a
+    // bogus `mapval_spread_required` naming a spread that exists in
+    // neither file. The bag's gen already skips marked children.
+    //
+    // An OPERATOR is carried too (BUGS.md §36): an expression is a
+    // computation that resolves by itself once its operands do — the
+    // bag's own-key loop drives it every pass — so `m:{y:.x+1}`
+    // arriving as a peer key must keep computing exactly as it does
+    // written inline. Wrapping it froze the op (an expectation only
+    // advances when a peer arrives) and the residue then reported the
+    // phantom `mapval_spread_required` naming a spread that exists
+    // nowhere. An op that truly never resolves is honest *_no_gen
+    // residue naming the expression itself.
+    if (val.isGenable || val.isOp || val.mark.type || val.mark.hide) {
       return val
     }
-    const expectVal = new ExpectVal({ peg: val }, ctx)
+    // An expectation baked into a combined spread template (the
+    // 'map-self' meet of two unequal templates) is re-wrapped FRESH, so
+    // key/parent name THIS bag and the template's own node is never
+    // stored at a destination.
+    const expectVal = new ExpectVal({ peg: val.isExpect ? val.peg : val }, ctx)
     expectVal.key = key
     expectVal.parent = parent
     return expectVal
   }
 
 
+  // TWO BAGS ARE THE SAME VALUE WHEN THEY HAVE THE SAME SHAPE. Val.same
+  // falls back to object IDENTITY, which no two separately built maps
+  // share -- so `x:*{a:1}|{a:number}` met by `x:{a:2}` left
+  // `{"a":2}|{"a":2}`, a disjunction of one value spelled twice, past
+  // the DisjunctVal dedup. Generation's old member FOLD hid that
+  // (folding a value with itself is that value); ADR-007 does not, and
+  // a disjunction whose alternatives are all the SAME value is
+  // resolved, not ambiguous. Canon prints the collapse too, which is
+  // the more honest text.
+  //
+  // Structural, and deliberately strict: container kind, closedness,
+  // the marks, the optional keys and the key set must all agree before
+  // the children are compared pairwise. Recursion terminates because a
+  // reference is not a bag -- RefVal keeps the identity comparison.
+  same(peer: any): boolean {
+    if (this === peer) {
+      return true
+    }
+    if (null == peer || true !== peer.isBag) {
+      return false
+    }
+    if (this.isMap !== peer.isMap ||
+      this.closed !== peer.closed ||
+      this.mark.type !== peer.mark.type ||
+      this.mark.hide !== peer.mark.hide) {
+      return false
+    }
+
+    const keys = Object.keys(this.peg)
+    if (keys.length !== Object.keys(peer.peg).length) {
+      return false
+    }
+    if (this.optionalKeys.length !== peer.optionalKeys.length ||
+      this.optionalKeys.some((k) => !peer.optionalKeys.includes(k))) {
+      return false
+    }
+
+    for (const k of keys) {
+      const mine: any = (this.peg as any)[k]
+      const theirs: any = (peer.peg as any)[k]
+      if (null == mine || null == theirs || !mine.same(theirs)) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+
   gen(ctx: AontuContext) {
     let out: any = this.isMap ? {} : []
 
-    if (this.mark.type || this.mark.hide) {
+    if ((this.mark.type || this.mark.hide) && true !== ctx?.probe) {
       return undefined
     }
 
@@ -83,7 +153,7 @@ abstract class BagVal extends FeatureVal {
       const p = item[0]
       const child = item[1]
 
-      if (child.mark.type || child.mark.hide) {
+      if ((child.mark.type || child.mark.hide) && true !== ctx?.probe) {
         continue
       }
 
@@ -114,6 +184,14 @@ abstract class BagVal extends FeatureVal {
         put(cval)
       }
 
+      // A CONJUNCT IS GENERABLE WHEN IT IS A SETTLED SIZING RESIDUE
+      // (the review's finding C, use-cases/BUGS.md §16). `length` and
+      // `unique` over a container keep the readings more members could
+      // still change, so `a: length(3) a:[1,2,3]` is a conjunct of the
+      // atom and the list right up to generation -- which is where the
+      // atom decides, in ConjunctVal.gen. Any OTHER conjunct is
+      // unresolved and falls through to the residue error below,
+      // exactly as before.
       else if (child.isScalar
         || child.isMap
         || child.isList
@@ -121,6 +199,7 @@ abstract class BagVal extends FeatureVal {
         || child.isRef
         || child.isDisjunct
         || child.isNil
+        || undefined !== sizingResidue(child)
       ) {
         // An optional child is generated in an isolated collect context so an
         // unresolved inner value (a bare type that survived unification, e.g.
@@ -184,3 +263,21 @@ abstract class BagVal extends FeatureVal {
 export {
   BagVal,
 }
+
+
+// A conjunct of exactly one sizing constraint and one container: the
+// shape ConstraintVal.admitContainer leaves when its reading is still
+// provisional, and the one ConjunctVal.gen knows how to finish. Kept
+// here rather than as a flag on the conjunct because it is a question
+// about the TERMS, and they can change until the meet converges.
+export function sizingResidue(v: any): { con: any, bag: any } | undefined {
+  if (true !== v?.isConjunct || 2 !== v.peg?.length) {
+    return undefined
+  }
+  const [a, b]: any[] = v.peg
+  const con = true === a?.isConstraint ? a :
+    true === b?.isConstraint ? b : undefined
+  const bag = true === a?.isConstraint ? b : a
+  return undefined !== con && (true === bag?.isMap || true === bag?.isList) ?
+    { con, bag } : undefined
+}

package/src/val/CloseFuncVal.ts

@@ -39,13 +39,21 @@ class CloseFuncVal extends FuncBaseVal {
 
 
   resolve(ctx: AontuContext, args: Val[]) {
-    const argval: any = args[0]
+    let argval: any = args[0]
 
     if (null == argval) {
       return makeNilErr(ctx, 'no_first_arg', this, undefined, 'close')
     }
 
     if (argval.isMap || argval.isList) {
+      // The in-place write is safe BECAUSE of the per-destination
+      // instantiation rule (ADR-005): everywhere a close() call is
+      // multiplied — a pack/each template, a spread constraint — the
+      // clone now owns its argument (`dup`), so `closed` lands on that
+      // instance alone. Cloning the bag here instead was tried and
+      // rejected: the re-path it implies corrupts the source
+      // attribution of children inside nested spread templates (the
+      // 06-k8s use case's env findings named the wrong path).
       (argval as BagVal).closed = true
       // console.log('CLOSED', argval.canon)
     }

package/src/val/ConjunctVal.ts

@@ -22,6 +22,7 @@ import {
 
 
 import { JunctionVal } from './JunctionVal'
+import { sizingResidue } from './BagVal'
 
 import {
   explainOpen,
@@ -215,6 +216,25 @@ class ConjunctVal extends JunctionVal {
 
 
   gen(ctx?: AontuContext) {
+    // A RESIDUATED SIZING ATOM DECIDES HERE (the review's finding C,
+    // use-cases/BUGS.md §16). `length`/`unique` over a container keep
+    // the readings that MORE MEMBERS COULD STILL CHANGE -- an upper
+    // bound satisfied, a lower bound violated, distinctness so far --
+    // rather than deciding against whatever the container held when it
+    // first settled (ConstraintVal.admitContainer). Generation is where
+    // no more members can arrive, so it is where the provisional
+    // reading becomes the verdict: the container generates if the atom
+    // is satisfied, and the atom's OWN refusal is raised if it is not.
+    //
+    // Without this the conjunct would report `conjunct` for a document
+    // whose only fault is a length -- the constraint's message is the
+    // one the author needs.
+    const residue = sizingResidue(this)
+    if (undefined !== residue) {
+      const settled: any = residue.con.settleContainer(residue.bag, ctx)
+      return true === settled?.isNil ? undefined : settled.gen(ctx)
+    }
+
     // Unresolved conjunct cannot be generated, so always an error.
     let nil = makeNilErr(
       ctx,