aontu 0.61.0 → 0.63.0

package/src/val/AggFuncVal.ts

@@ -1,47 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// AGGREGATION, PROJECTION AND THE STRING FOLD: `sum(d)`, `least(d)`,
-// `greatest(d)`, `pick(d, k)` and `join(d, sep?)`.
-//
-// 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,
@@ -59,6 +17,7 @@ import { StringVal } from './StringVal'
 import { FuncBaseVal } from './FuncBaseVal'
 import { arith } from './arith'
 import { cmpNumeric } from './numcmp'
+import { cmpCodePoint } from '../keyorder'
 import { memberVals } from './members'
 import { plusText } from './PlusOpVal'
 
@@ -66,12 +25,6 @@ import { plusText } from './PlusOpVal'
 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).
-// The members of the bag a fold reads: what generation would emit
-// (./members.ts, BUGS.md §79), in the one map-key order (BUGS.md §62).
 function bagChildren(data: any, ctx: AontuContext): Val[] | undefined {
   return memberVals(data, ctx)
 }
@@ -80,9 +33,6 @@ function bagChildren(data: any, ctx: AontuContext): Val[] | 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
@@ -97,21 +47,11 @@ class AggFuncVal extends FuncBaseVal {
   }
 
 
-  // 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
   }
@@ -137,9 +77,6 @@ class AggFuncVal extends FuncBaseVal {
     }
 
     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)
@@ -192,28 +129,6 @@ function unpref(v: any): any {
 }
 
 
-// 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
 
@@ -293,56 +208,159 @@ class PickFuncVal extends FuncBaseVal {
 }
 
 
+// `pick`'s rule, plus: the empty string is the member itself, which is
+// how a keyless descending sort is spelled.
+function projectorName(key: any): [string, boolean] {
+  if (null == key || null == key.peg) {
+    return ['', true]
+  }
+  if ('string' === typeof key.peg) {
+    return [key.peg, true]
+  }
+  if ('number' === typeof key.peg && key.isInteger) {
+    return [String(key.peg), true]
+  }
+  return ['', false]
+}
+
+
+function fieldOf(child: any, name: string): Val | undefined {
+  return true === child?.isMap ? child.peg[name] :
+    true === child?.isList ? child.peg[Number(name)] :
+      undefined
+}
+
+
+const SORT_DIRECTIONS: Record<string, number> = { asc: 1, desc: -1 }
+
+
+function directionOf(v: any): number | undefined {
+  if (null == v || null == v.peg) {
+    return 1
+  }
+  return 'string' === typeof v.peg ? SORT_DIRECTIONS[v.peg] : undefined
+}
+
+
+// Text by code point, numbers by the exact comparator, nothing else.
+function sortDomain(u: any): 'text' | 'number' | undefined {
+  if (true !== u?.isVal || true !== u.isScalar || true === u.isNull) {
+    return undefined
+  }
+  if ('string' === typeof u.peg) {
+    return 'text'
+  }
+  return 'boolean' === typeof u.peg ? undefined : 'number'
+}
+
+
+type SortRow = { idx: number, val: Val, key: any }
+
+
+class SortFuncVal extends FuncBaseVal {
+  isSortFunc = true
+
+  // The bag must settle before it is ordered, exactly as it must
+  // before it is projected.
+  staged = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+  funcname() {
+    return 'sort'
+  }
+
+
+  // The base drives no argument: the DATA is driven by hand below, and
+  // the projector is a bare word 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], ctx)
+
+    if (undefined === children) {
+      return this.place(makeNilErr(ctx, 'aggregate_data', this, undefined,
+        'sort'))
+    }
+
+    const [name, nameok] = projectorName(args?.[1])
+
+    if (!nameok) {
+      return this.place(makeNilErr(ctx, 'invalid-arg', this, undefined,
+        'sort'))
+    }
+
+    const dir = directionOf(args?.[2])
+
+    if (undefined === dir) {
+      return this.place(makeNilErr(ctx, 'sort_dir', this, undefined, 'sort',
+        { dir: (args[2] as any).canon }))
+    }
+
+    const rows: SortRow[] = []
+    let domain: 'text' | 'number' | undefined = undefined
+
+    for (const child of children) {
+      const at: any = '' === name ? child : fieldOf(child, name)
+
+      if (null == at) {
+        return this.place(makeNilErr(ctx, 'sort_key', this, undefined, 'sort',
+          { key: name }))
+      }
+
+      const u = unpref(at)
+      const found = sortDomain(u)
+
+      if (undefined === found ||
+        (undefined !== domain && found !== domain)) {
+        return this.place(makeNilErr(ctx, 'sort_domain', this, undefined,
+          'sort', { member: u.canon }))
+      }
+
+      domain = found
+      rows.push({ idx: rows.length, val: child, key: u })
+    }
+
+    // The source index breaks every tie, so the order is TOTAL and
+    // neither port's sort algorithm can reorder equals.
+    rows.sort((a, b) => {
+      const c = 'text' === domain ?
+        cmpCodePoint(a.key.peg as string, b.key.peg as string) :
+        cmpNumeric(a.key, b.key)
+      return 0 === c ? a.idx - b.idx : dir * c
+    })
+
+    const peg: Val[] = rows.map(
+      (r, i) => r.val.clone(ctx.descend(String(i))))
+
+    return this.place(new ListVal({ peg }, ctx))
+  }
+}
+
 
-// THE FOLD TO A STRING: `join(coll, sep?)` -- G9 phase 2.
-//
-// The one primitive between a model and a generated file. A spread can
-// put a separator AFTER each element; putting one BETWEEN N elements is
-// a reduction over strings, and the language had none: `sum` is numeric,
-// `+` does not reduce a list, and indexed concatenation needs the arity
-// known in advance. So a generated SQL column list carried a trailing
-// comma and did not parse (use-cases/15-code-generation).
-//
-// IT FOLDS WITH `+` SEEDED WITH `""`, exactly as `sum` folds with `add`
-// seeded with `0`. That is not a figure of speech: the members are
-// rendered by `plusText`, which IS the function `+`'s string branch
-// calls, so the language keeps exactly one answer to "how does a number
-// become text" and the two cannot drift. `join(coll)` is therefore
-// concatenation and no `concat` is needed; `join(coll, "\n")` is lines
-// and no `lines` is needed. ONE BUILTIN, NOT A FAMILY.
-//
-// `split`/`words` is the inverse -- an input-PARSING operation with no
-// generation use -- and is deliberately absent.
-//
-// EMPTY IS `""`, concatenation's identity, the exact parallel of
-// `sum([]) == 0` and the opposite of `least([])`: a fold with an
-// identity can answer the empty bag, and one without has to refuse it.
-//
-// MEMBERS ARE VALIDATED BEFORE THE FOLD, which is the whole reason this
-// is not three lines. `+` with a string on the left RESIDUATES on a
-// container or a null rather than refusing (`"" + {b:1}` and `"x" +
-// null` both reach generation as `mapval_no_gen`), so folding blindly
-// would turn a bad member into a useless late error pointing at the
-// wrong thing. The three verdicts below are that check.
 type MemberVerdict = 'text' | 'never' | 'notyet'
 
 
-// Which of the three a value is.
-//
-// `text` -- `+` would take it, so the fold can.
-//
-// `never` -- a SETTLED value that will never become text: a map, a
-// list, a null. This is `join_member`, class `conflict`, and it names
-// the member rather than the call, because "one of these is not a
-// string" is only actionable if you are told which.
-//
-// `notyet` -- an unresolved kind, a top, a stable residue. NOT a join
-// failure at all: the call stays residual and generation reports
-// `mapval_no_gen`, class `incomplete`, exactly as docs/trust.md
-// requires ("a stable residue ... is ordinary incompleteness"). Getting
-// this split wrong in either direction is the defect that matters here:
-// refusing a residue makes `join` unusable inside a schema, and
-// deferring on a map makes a real error arrive as a shrug.
 function memberVerdict(v: any): MemberVerdict {
   const u = unpref(v)
   if (undefined !== plusText(u)) {
@@ -355,15 +373,6 @@ function memberVerdict(v: any): MemberVerdict {
 }
 
 
-// The separator is a STRING or it is nothing.
-//
-// A number would render perfectly well through `+`, and is still
-// refused: the separator is not a member of the fold, it is the
-// parameter naming the text between members, and `join(x, 5)` is far
-// likelier a mistake than an intent to separate with "5". `pick`'s key
-// argument draws the same line for the same reason. This is the
-// direction that can be loosened later without breaking a document;
-// the other direction cannot.
 function sepVerdict(v: any): MemberVerdict {
   const u = unpref(v)
   if (u?.isVal && u.isScalar) {
@@ -391,22 +400,6 @@ class JoinFuncVal extends FuncBaseVal {
   }
 
 
-  // A `make` OVERRIDE, WHERE ITS AggFuncVal SIBLINGS HAVE NONE, and the
-  // difference is worth stating because it is not arbitrary. `sum`,
-  // `pick` and the rest are staged and nothing more: they residuate
-  // before `unify` reaches the rebuild branch, so a `make` there would
-  // be unreachable code pretending to be a contract, and the base's
-  // `func:<name>` refusal is the loud answer if that ever changes.
-  //
-  // `join` is the first builtin that is BOTH staged AND defers its
-  // resolution (see `deferResolve`). A deferred call has settled
-  // arguments, so it does reach the rebuild branch, and without this it
-  // raised `func:join` on the first document with an unresolved member
-  // — where the Go port residuated and reported `mapval_no_gen`.
-  // Opposite answers on `join($.m, ",")` with `m: [string]`, caught by
-  // running both engines rather than by either test suite. `super` and
-  // bare `id`, the two other deferring calls, each carry the same
-  // override for the same reason.
   make(_ctx: AontuContext, spec: ValSpec): Val {
     return new JoinFuncVal(spec)
   }
@@ -426,10 +419,6 @@ class JoinFuncVal extends FuncBaseVal {
 
 
   unify(peer: Val, ctx: AontuContext): Val {
-    // BOTH arguments, unlike `pick`, which drives only its bag: `pick`'s
-    // key is a bare word the parser has already made a string, while a
-    // separator is an ordinary expression and `join($.rows, $.sep)` has
-    // to wait for it.
     const ready = this.driveStagedArgs(ctx, 2)
 
     if (!ready || !ctx.settle) {
@@ -440,10 +429,6 @@ class JoinFuncVal extends FuncBaseVal {
   }
 
 
-  // The `notyet` half of the verdict, taken before `resolve` runs: with
-  // arguments settled but a member still a kind, the call rides the
-  // ordinary args-not-done path and residuates, which is what makes an
-  // unresolved member ordinary incompleteness rather than a refusal.
   deferResolve(ctx: AontuContext, args?: Val[]): boolean {
     const children = bagChildren(args?.[0], ctx)
     if (undefined === children) {
@@ -467,28 +452,11 @@ class JoinFuncVal extends FuncBaseVal {
         'join'))
     }
 
-    // Arity is [1,2], so a second argument is present or the separator
-    // is the empty string -- which makes `join(coll)` concatenation.
-    // The separator's SHAPE is settled before resolve runs: the
-    // signature gate refuses every concrete non-string
-    // (docs/design/SIGNATURES.0.md; join(d: map|list, sep?: string)),
-    // and deferResolve holds the call while sepVerdict answers notyet
-    // -- so a present separator here is text.
     let sep = ''
     if (1 < args.length) {
       sep = unpref(args[1]).peg
     }
 
-    // NO NIL-MEMBER GUARD, WHERE `sum` HAS ONE, and the difference is
-    // the fold's shape rather than an oversight. `sum` folds with
-    // `arith`, which MINTS a nil part-way through — a non-numeric child
-    // or an overflow — so it has to stop and return it. `join` folds
-    // already-unified values, and a nil among a list's elements
-    // collapses the list before this call resolves: `join([least([])],
-    // ",")` reports `aggregate_empty` at the member's own path,
-    // `$.o.0`, and never reaches here. A guard was written, the
-    // ADR-002 gate found it unexecuted, and probing confirmed no
-    // spelling reaches it, so it is removed rather than excused.
     const parts: string[] = []
     for (const child of children) {
       const u: any = unpref(child)
@@ -500,16 +468,11 @@ class JoinFuncVal extends FuncBaseVal {
       parts.push(text)
     }
 
-    // Every part is already a string, so this IS the `+` fold seeded
-    // with `""` -- written as one concatenation because a loop of `+`
-    // over settled strings cannot differ from it, and because the Go
-    // twin's strings.Join must produce the same bytes.
     return this.place(new StringVal({ peg: parts.join(sep) }))
   }
 }
 
 
-// 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') }
 }
@@ -522,13 +485,14 @@ class GreatestFuncVal extends AggFuncVal {
   constructor(spec: ValSpec, ctx?: AontuContext) {
     super(spec, ctx, 'greatest')
   }
-} /* node:coverage ignore next 10 */
+} /* node:coverage ignore next 11 */
 
 
 export {
   AggFuncVal,
   JoinFuncVal,
   PickFuncVal,
+  SortFuncVal,
   SumFuncVal,
   LeastFuncVal,
   GreatestFuncVal,

package/src/val/ArithFuncVal.ts

@@ -15,17 +15,6 @@ 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
 
@@ -60,18 +49,9 @@ class ArithFuncVal extends FuncBaseVal {
   }
 
 
-  // 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') }
 }

package/src/val/BagVal.ts

@@ -30,15 +30,6 @@ abstract class BagVal extends FeatureVal {
   closed: boolean = false
   optionalKeys: string[] = []
 
-  // ALIAS DECLARATIONS, by key. `%uint8 = …` binds a name for this file
-  // and is not a field of the document: it does not generate and does
-  // not appear in canon, so a document using aliases and its expanded
-  // twin are the SAME document and hash identically
-  // (docs/design/ALIASES.0.md §4).
-  //
-  // Keyed on the map rather than marked on the value, because a
-  // reference copies the value it resolves to -- a mark riding the
-  // value would erase the referring field along with the declaration.
   aliasKeys: string[] = []
 
   spread = {
@@ -60,30 +51,9 @@ abstract class BagVal extends FeatureVal {
 
 
   handleExpectedVal(key: string, val: Val, parent: Val, ctx: AontuContext): Val {
-    // 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
     }
-    // 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
@@ -91,20 +61,6 @@ abstract class BagVal extends FeatureVal {
   }
 
 
-  // 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
@@ -118,11 +74,6 @@ abstract class BagVal extends FeatureVal {
       this.mark.hide !== peer.mark.hide) {
       return false
     }
-    // The SPREAD is part of the shape (BUGS.md §52 regime 4): `[]`
-    // and `[&: T]` share an empty key set, and calling them the same
-    // value collapsed the disjunction to its first arm before any
-    // data could pick -- the vacuous-schema hole. Two spreads are the
-    // same when their canons are.
     const scj: any = (this as any).spread?.cj
     const pcj: any = peer.spread?.cj
     if ((null == scj) !== (null == pcj) ||
@@ -158,12 +109,6 @@ abstract class BagVal extends FeatureVal {
       return undefined
     }
 
-    // Maps emit their keys in CODE POINT order so the generated output
-    // is independent of insertion/unification order and matches the Go
-    // port. Lists keep their numeric index order.
-    //
-    // The keys are String()-coerced because a list entry carries a
-    // numeric index here; the coercion is a no-op for every map key.
     let entries = items(this.peg)
     if (this.isMap) {
       entries = entries
@@ -214,22 +159,7 @@ 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 (bagGenable(child)) {
-        // An optional child is generated in an isolated collect context so an
-        // unresolved inner value (a bare type that survived unification, e.g.
-        // an absent optional sub-map's `field: string`) is dropped rather than
-        // raised: the optional subtree is simply omitted. Without isolation
-        // such inner errors pollute the shared ctx.err and make generate()
-        // throw even though the key is skipped below. Mirrors the
-        // optional-disjunct path above.
         const cctx = optional ? ctx.clone({ err: [], collect: true }) : ctx
 
         let cval = child.gen(cctx)
@@ -273,7 +203,6 @@ abstract class BagVal extends FeatureVal {
         break
       }
 
-      // else optional so we can ignore it
     }
 
     return out
@@ -304,13 +233,6 @@ export function sizingResidue(v: any): { con: any, bag: any } | undefined {
     { con, bag } : undefined
 }
 
-// bagGenable is the bag's generability whitelist. A graph atom
-// (RELATIONS P2) is exactly as generable as the value it carries: the
-// atom is transparent at generation, so wrapping a field's value in
-// acyclic() must not change whether the bag accepts it -- an unmet
-// rel() refuses required generation with or without the atom, and a
-// BARE atom generates nothing and is dropped, exactly as an unmet
-// rel() under an optional key is.
 export function bagGenable(child: any): boolean {
   if (true === child.isGraphAtom) {
     return undefined === child.held || bagGenable(child.held)
@@ -322,6 +244,7 @@ export function bagGenable(child: any): boolean {
     return true
   }
   return true === child.isScalar
+    || true === child.isAbsent
     || true === child.isMap
     || true === child.isList
     || true === child.isPref

package/src/val/BigDecimalVal.ts

@@ -22,15 +22,6 @@ import {
 } from '../utility'
 
 
-// The exact base-10 decimal leaf of the number tower, reached only by a
-// `0d` literal carrying a `.` or an exponent (`0d1.5`, `0d1e3`) or by
-// direct construction.
-//
-// Its peg is a Decimal -- an OBJECT, so unlike every other scalar leaf
-// its identity cannot be `===` on the peg. Two bigdecimals are the same
-// value when their NUMBERS are equal (D2), which normalisation at
-// construction reduces to a two-field comparison; `samePeg` and `unify`
-// below are the two places that must not forget it.
 class BigDecimalVal extends ScalarVal {
   isBigDecimal = true
 
@@ -40,10 +31,6 @@ class BigDecimalVal extends ScalarVal {
     spec: ValSpec,
     ctx?: AontuContext
   ) {
-    // Exact-input construction (D8): a Decimal, or a decimal literal as
-    // text (`'1.5'`, `'0d1e3'`). A JS `number` is deliberately NOT
-    // accepted -- binary64 has already rounded it, so `0.1` could never
-    // arrive exact.
     let peg = spec.peg
     if ('string' === typeof peg) {
       try {
@@ -78,9 +65,6 @@ class BigDecimalVal extends ScalarVal {
         peer.kind === this.kind &&
         this.peg.equals(peer.peg)
       ) {
-        // Same kind and equal NUMBER. Never `peer.peg === this.peg`:
-        // that is object identity, and `0d0.10 & 0d0.1` (two Decimals
-        // holding one value) has to succeed.
         out = this
       }
       else if (peer.isTop) {