aontu 0.52.1 → 0.54.0

package/src/val/DisjunctVal.ts

@@ -13,7 +13,8 @@ import {
 
 import { AontuContext } from '../ctx'
 
-import { makeNilErr } from '../err'
+import { AontuError, descErr, makeNilErr } from '../err'
+import { exactJSON } from '../exactjson'
 import { unite } from '../unify'
 
 import {
@@ -30,8 +31,8 @@ import {
   top
 } from './top'
 
-import { NilVal, TRIAL_NIL } from '../val/NilVal'
-import { PrefVal } from '../val/PrefVal'
+import { TRIAL_NIL } from '../val/NilVal'
+import { PrefVal, prefInnerPeg } from '../val/PrefVal'
 import { JunctionVal } from '../val/JunctionVal'
 
 
@@ -70,7 +71,12 @@ class DisjunctVal extends JunctionVal {
     const te = ctx.explain && explainOpen(ctx, ctx.explain, 'Disjunct', this, peer)
 
     if (!this.prefsRanked) {
-      this.rankPrefs(ctx)
+      const ranked = this.rankPrefs(ctx)
+      // A clash between equal-rank defaults refuses for the whole
+      // disjunction (R2): the disagreement IS the answer.
+      if (null != ranked && ranked.isNil) {
+        return ranked
+      }
     }
 
     // // // console.log('DISJUNCT-unify-A', this.id, this.canon)
@@ -95,6 +101,16 @@ class DisjunctVal extends JunctionVal {
     // before return.
     const savedErr = ctx.err
     const savedTrialMode = ctx._trialMode
+    // A MEMBER'S TYPE FLOW IS PART OF THAT MEMBER. `refer(t)`/`rel(t)`
+    // assert `t` on ANOTHER node, and the assertion may only take
+    // effect if the member that makes it survives: committing every
+    // member's flow puts `t_A & t_B` on the target, which no reading
+    // of `A | B` licenses and which leaves the target MORE constrained
+    // than either alternative. The flow record is therefore staged per
+    // trial, like `ctx.err`, and only the survivors' records are
+    // merged into the real one below.
+    const savedFlows: Map<string, Val> | undefined = (ctx as any).referflows
+    const staged: (Map<string, Val> | undefined)[] = []
     // C1-inner: tell `makeNilErr` to return TRIAL_NIL in this scope
     // instead of allocating per-failure NilVals. Save/restore so
     // nested DisjunctVal trials (and the outer non-trial code) are
@@ -102,11 +118,16 @@ class DisjunctVal extends JunctionVal {
     // leaving ctx._trialMode=true would collapse every subsequent real
     // error in this ctx to the shared TRIAL_NIL sentinel.
     ctx._trialMode = true
+    let gate: number[] | undefined = undefined
     try {
       for (let vI = 0; vI < this.peg.length; vI++) {
         const v = this.peg[vI]
         const trialErr: any[] = []
         ctx.err = trialErr
+        if (undefined !== savedFlows) {
+          staged[vI] = new Map()
+          ;(ctx as any).referflows = staged[vI]
+        }
 
         oval[vI] = unite(te ? ctx.clone({ explain: ec(te, 'DIST:' + vI) }) : ctx, v, peer, 'dj-peer')
 
@@ -117,17 +138,96 @@ class DisjunctVal extends JunctionVal {
           // sentinel instead of allocating a fresh NilVal per trial.
           oval[vI] = TRIAL_NIL
         }
+        else if (v instanceof PrefVal &&
+          !(peer as any).isPref && !peer.isTop &&
+          true === (prefInnerPeg(v) as any).isScalar) {
+          // A candidate for the admission gate below: a non-pref,
+          // non-top peer met a scalar preference inside this
+          // disjunction.
+          ; (gate = gate ?? []).push(vI)
+        }
 
         done = done && DONE === oval[vI].dc
       }
+
+      // THE ADMISSION GATE (ADR-004). A peer that meets a preference
+      // INSIDE a disjunction must be admitted by the disjunction: by
+      // some sibling alternative (whose own trial above already
+      // answers that), or by the preferred value itself (the pref
+      // branch's own admitted set). The pref's kind gate alone used to
+      // decide, so a same-kind concrete peer replaced the default with
+      // the alternatives never consulted -- `k:*'auto'|'literal'|'data'`
+      // plus `k:'autoo'` answered "autoo", and `*8080|(integer&neq(80))`
+      // admitted 80 (use-cases/BUGS.md §1-2). An inadmissible override
+      // now fails the pref member's trial, and when every member is
+      // gone the meet is the existing `empty` refusal.
+      //
+      // SCALAR preferred values only, exactly the kind gate's own
+      // boundary (test/spec/pref.tsv, "THE GATE IS A SCALAR GATE"): a
+      // structural or kind-peg default stays ungated. A deliberately
+      // open default remains spellable as `*x|top` -- the top branch
+      // admits every override (the apidef machine-emitted idiom).
+      if (undefined !== gate) {
+        for (const gI of gate) {
+          let admitted = false
+          for (let kI = 0; kI < oval.length && !admitted; kI++) {
+            // Sibling alternatives only: a pref member cannot admit
+            // its own override (post-rankPrefs at most one pref
+            // stands at this level, so this is defensive).
+            admitted = kI !== gI && !oval[kI].isNil &&
+              !(this.peg[kI] as any).isPref
+          }
+          if (!admitted) {
+            const admitErr: any[] = []
+            ctx.err = admitErr
+            // The trial is against a CLONE: the preferred value must
+            // stay pristine for the surviving preference (the
+            // MatchFuncVal.resolve precedent).
+            const met = unite(ctx,
+              prefInnerPeg(this.peg[gI] as PrefVal).clone(ctx), peer,
+              'dj-admit')
+            if (0 < admitErr.length || met.isNil) {
+              oval[gI] = TRIAL_NIL
+            }
+          }
+        }
+      }
     }
     finally {
       ctx._trialMode = savedTrialMode
       ctx.err = savedErr
+      ;(ctx as any).referflows = savedFlows
     }
 
     // // // console.log('DISJUNCT-unify-B', this.id, oval.map(v => v.canon))
 
+    // A PREFERENCE CONJOINED WITH A DISJUNCTION IS A PREFERENCE ON THE
+    // ALTERNATIVE IT NAMES: `(A|B) & *A` is `*A|B`, the same value the
+    // direct spelling `*A|B` denotes. Distribution carries the peer to
+    // each member, and a scalar preference meeting a concrete same-kind
+    // member is replaced BY that member (the kind gate) -- so the
+    // preference simply vanished, and `specversion: ("1.0"|"1.1") &
+    // *"1.0"`, the enum-with-default written the other way round, held
+    // no default at all. The old generation fold hid it by folding the
+    // members together; ADR-007 does not, and a disjunction that has
+    // lost its default is not the value the author wrote.
+    //
+    // A preference naming no alternative is dropped, as it is today: it
+    // has nothing to prefer, and the default-validity lint is what
+    // reports that shape.
+    if (true === (peer as any).isPref) {
+      const want: any = prefInnerPeg(peer as PrefVal)
+      for (let vI = 0; vI < oval.length; vI++) {
+        const got: any = oval[vI]
+        if (!got.isNil && true !== got.isPref && got.same(want)) {
+          const wrapped = new PrefVal({ peg: got }, ctx)
+          wrapped.rank = (peer as PrefVal).rank
+          ;(peer as PrefVal).place(wrapped)
+          oval[vI] = wrapped
+        }
+      }
+    }
+
     // Remove duplicates, and normalize
     if (1 < oval.length) {
       for (let vI = 0; vI < oval.length; vI++) {
@@ -145,25 +245,80 @@ class DisjunctVal extends JunctionVal {
         for (let kI = vI + 1; kI < oval.length; kI++) {
           if (oval[kI].same(oval[vI])) {
             oval[kI] = TRIAL_NIL
+            continue
+          }
+
+          // TWO PREFERENCES OVER ONE VALUE ARE ONE PREFERENCE, and
+          // the lower rank is the one that generates: `*1 | **1` is
+          // `*1`. Ranking folds EQUAL ranks (R2); this folds the rest,
+          // which R5 stopped discarding.
+          //
+          // A PLAIN arm holding that same value is NOT a duplicate of
+          // it and must not be folded away: it is the sibling that
+          // ADMITS an override under ADR-004's gate, which is the
+          // whole point of writing `*x | x`. Folding it turned that
+          // idiom's own default into a `pref_not_instance` finding,
+          // and `*top | top` is pinned as its control.
+          const a: any = oval[vI]
+          const b: any = oval[kI]
+          if (true === a.isPref && true === b.isPref
+            && prefInnerPeg(a).same(prefInnerPeg(b))) {
+            if ((a as PrefVal).rank <= (b as PrefVal).rank) {
+              oval[kI] = TRIAL_NIL
+            }
+            else {
+              oval[vI] = TRIAL_NIL
+              break
+            }
           }
         }
       }
 
       // // // console.log('DISJUNCT-unify-D', this.id, oval.map(v => v.canon))
+    }
 
-      oval = oval.filter(v => !v.isNil)
+    // THE SURVIVORS' FLOWS, AND ONLY THEIRS. Members knocked out by
+    // the trial, by the admission gate or by the dedup above are all
+    // nil here, so this runs after every one of those and before the
+    // filter that drops them.
+    if (undefined !== savedFlows) {
+      for (let vI = 0; vI < staged.length; vI++) {
+        const st = staged[vI]
+        if (undefined === st || true === oval[vI]?.isNil) {
+          continue
+        }
+        for (const [k, fv] of st) {
+          const prev = savedFlows.get(k)
+          savedFlows.set(k, undefined === prev ? fv
+            : unite(ctx, prev, fv, 'refer-flow-record'))
+        }
+      }
     }
 
+    // Outside the 1<length block: a SINGLE-member disjunction (e.g. a
+    // rankPrefs collapse) whose one member fails the trial or the
+    // admission gate must reach the `empty` refusal below, not
+    // return the trial sentinel as if it were the answer.
+    oval = oval.filter(v => !v.isNil)
+
     let out: Val
 
     if (1 == oval.length) {
       out = oval[0]
     }
     else if (0 == oval.length) {
-      return makeNilErr(ctx, '|:empty', this, peer)
+      return makeNilErr(ctx, 'empty', this, peer)
     }
     else {
       out = new DisjunctVal({ peg: oval }, ctx)
+      // A NARROWED DISJUNCTION IS STILL THAT DISJUNCTION. The meet mints
+      // a fresh value, which used to arrive unsited and file-less -- so
+      // every finding naming a disjunction that had met anything
+      // pointed at row -1 with no file, and an agent handed the report
+      // had nowhere to go (the review's finding F). `place` copies the
+      // whole site, position and url together, which is what tells the
+      // report which document it came from.
+      this.place(out)
     }
 
     out.dc = done ? DONE : this.dc + 1
@@ -177,48 +332,61 @@ class DisjunctVal extends JunctionVal {
   }
 
 
-  rankPrefs(ctx: AontuContext) {
-    let lastpref: PrefVal | undefined = undefined
-    let lastprefI = -1
+  // RANK ORDERS THE SURVIVORS, IT DOES NOT DISCARD AT PARSE (ADR-011
+  // R5, docs/design/DEFAULTS.0.md). Every rank is KEPT here, and
+  // generation takes the lowest-rank preference still standing -- so
+  // eliminating the lower arm PROMOTES the next instead of taking the
+  // whole ladder with it. This ran once, before the member trials,
+  // and discarded every arm but the lowest: `*1 | **2` met by
+  // `neq(1)` lost the default entirely and refused, where the ladder
+  // exists precisely to answer 2. Rank is a preference order over
+  // WHAT SURVIVES, which is not knowable until the trials have run.
+  //
+  // Only EQUAL ranks fold, because two defaults at one rank are one
+  // decision: compatible pegs merge, and a disagreement is the
+  // `pref_rank_clash` refusal (R2), which belongs to the whole
+  // disjunction -- there is no alternative to fall back to.
+  //
+  // Answers the sole surviving preference when the disjunction holds
+  // exactly one -- which the RECURSIVE call below consumes to lift a
+  // nested disjunct's winner into this one -- or the clash refusal.
+  rankPrefs(ctx: AontuContext): Val | undefined {
+    // The kept index per rank, so an equal-rank twin folds into the
+    // arm already standing for that rank.
+    const atRank: Record<number, number> = {}
 
     // // // console.log('RP-A', this.peg.map((p: Val) => p.canon))
 
     for (let vI = 0; vI < this.peg.length; vI++) {
       const v = this.peg[vI]
+      let pref: PrefVal | undefined = undefined
+
       if (v instanceof PrefVal) {
-        if (null != lastpref) {
-          if (v.rank === lastpref.rank) {
-            const pref = v.unify(lastpref, ctx) as PrefVal
-            if (pref.isNil) {
-              return pref
-            }
-            else {
-              this.peg[lastprefI] = pref
-              lastpref = pref
-              this.peg[vI] = null
-            }
-            // return Nil.make(ctx, '|:prefs', lastpref, v, 'associate')
-          }
-          else if (v.rank < lastpref.rank) {
-            this.peg[lastprefI] = null
-            lastpref = v
-            lastprefI = vI
-          }
-          else {
-            this.peg[vI] = null
-          }
-        }
-        else {
-          lastpref = v
-          lastprefI = vI
-        }
+        pref = v
       }
       else if (v.isDisjunct) {
-        let subrank: any = v.rankPrefs(ctx)
+        const subrank = (v as DisjunctVal).rankPrefs(ctx)
+        if (null != subrank && subrank.isNil) {
+          return subrank
+        }
         if (subrank instanceof PrefVal) {
           this.peg[vI] = subrank
-          lastpref = subrank
-          lastprefI = vI
+          pref = subrank
+        }
+      }
+
+      if (undefined !== pref) {
+        const at = atRank[pref.rank]
+        if (undefined === at) {
+          atRank[pref.rank] = vI
+        }
+        else {
+          const folded = pref.unify(this.peg[at], ctx)
+          if (folded.isNil) {
+            return folded
+          }
+          this.peg[at] = folded
+          this.peg[vI] = null
         }
       }
     }
@@ -231,6 +399,8 @@ class DisjunctVal extends JunctionVal {
     if (1 === this.peg.length && this.peg[0] instanceof PrefVal) {
       return this.peg[0]
     }
+
+    return undefined
   }
 
 
@@ -246,35 +416,88 @@ class DisjunctVal extends JunctionVal {
   }
 
 
+  // AN UNRESOLVED DISJUNCTION IS NOT A VALUE (ADR-007).
+  //
+  // Generation used to FOLD the surviving members together with unify
+  // and emit the result. That answer is in no branch of the
+  // disjunction: `({x:1}|{y:2}) & {z:3}` generated `{x:1,y:2,z:3}`, a
+  // map the model never admits, and `1|2` died as a scalar_value
+  // CONFLICT -- the conflict of the fold, not of anything the author
+  // wrote. The second half is what made vet decorative: vet's
+  // incompleteness check keeps incomplete-class findings, so a missing
+  // required enum field (`role: 'a'|'b'` with no data) arrived as a
+  // conflict, was filtered out, and vetted VALID with zero findings
+  // (use-cases/BUGS.md §13, the review's finding C).
+  //
+  // What remains after unification is what the model still admits, so
+  // more than one surviving alternative means the truth is not yet
+  // settled -- incomplete, the same class a bare `string` residue
+  // answers, and the same answer CUE gives for a non-concrete export.
+  // A preference resolves it (that is what `*` is for), and so does a
+  // single surviving member.
   gen(ctx: AontuContext) {
-    // TODO: move this to main unify
-
-    // console.log('DJ-GEN', this.peg.map((p: any) => p.canon), ctx.err)
-
     if (0 < this.peg.length) {
+      // Ranking may not have run when gen is reached without a prior
+      // unify (a library caller generating a freshly parsed tree), and
+      // it is what guarantees at most one preference stands here.
+      if (!this.prefsRanked) {
+        this.rankPrefs(ctx)
+      }
 
-      let vals = this.peg.filter((v: Val) => v instanceof PrefVal)
-      // // // console.log('DJ-GEN-VALS-A', vals.map((p: any) => p.canon))
+      const prefs = this.peg.filter((v: Val) => v instanceof PrefVal)
+
+      // ALTERNATIVES THAT GENERATE THE SAME VALUE ARE RESOLVED
+      // (ADR-007's rule, asked at the moment it matters): `[] | [&:
+      // T]` met by an empty list keeps both arms -- they differ as
+      // SCHEMAS, which is what stops the dedup collapsing the
+      // template away (BUGS.md §52 regime 4) -- but both generate
+      // the empty list, and one generated value is one value.
+      if (0 === prefs.length && 1 < this.peg.length) {
+        const gctx = ctx.clone({ err: [], collect: true })
+        let firstOut: any
+        let allSame = true
+        for (let gI = 0; gI < this.peg.length && allSame; gI++) {
+          const gout = this.peg[gI].gen(gctx)
+          if (0 < gctx.err.length || undefined === gout) {
+            allSame = false
+          }
+          else if (0 === gI) {
+            firstOut = gout
+          }
+          else {
+            allSame = exactJSON(gout) === exactJSON(firstOut)
+          }
+        }
+        if (allSame) {
+          return firstOut
+        }
+      }
 
-      vals = 0 === vals.length ? this.peg : vals
+      if (0 === prefs.length && 1 < this.peg.length) {
+        const nerr = makeNilErr(ctx, 'disjunct_no_gen', this)
+        descErr(nerr, ctx)
+        ctx?.adderr(nerr)
 
-      let val = vals[0]
+        if (null == ctx || !ctx.collect) {
+          throw new AontuError(nerr.msg, [nerr])
+        }
 
-      // TODO: over unifies complex types like maps
-      // ({x:1}|{y:2})&{z:3} should be {"x":1,"z":3}|{"y":2,"z":3} not { x:1, z:3, y:2 }
-      for (let vI = 1; vI < vals.length; vI++) {
-        // Index `vals`, not `this.peg`: when the pref members are not the
-        // leading entries the two arrays differ, and folding against
-        // this.peg[vI] would unify the wrong (or a repeated) member.
-        let valnext = val.unify(vals[vI], ctx)
-        // // // console.log('DJ-GEN-VALS-NEXT', valnext.canon)
-        val = valnext
+        return undefined
       }
 
-      // console.log('DJ-GEN-VALS-B', val.canon)
-      const out = val.gen(ctx)
-      // console.log('DJ-GEN-VALS-C', out)
-      return out
+      // THE LOWEST-RANK SURVIVOR (R5). Ranking no longer discards the
+      // weaker arms, so the choice is made here, over what is left:
+      // `*1 | **2` answers 1, and answers 2 once `*1` is gone.
+      let best: any = this.peg[0]
+      if (0 < prefs.length) {
+        best = prefs[0]
+        for (const p of prefs) {
+          if ((p as PrefVal).rank < best.rank) {
+            best = p
+          }
+        }
+      }
+      return best.gen(ctx)
     }
 
     return super.gen(ctx)

package/src/val/EachFuncVal.ts

@@ -0,0 +1,133 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// GENERATION: `each(data, tmpl)` (G8 phase 1,
+// docs/capability-review/g8-generation.md). One element of the result
+// list per child of `data`, each of them that child met with `tmpl`.
+// Written with one argument, `each(m)` is a map's children as a list.
+//
+//   ports: {http: 80, https: 443}
+//   open: each($.ports, integer)   ->  [80, 443]
+//
+// ORDER IS FIXED, and fixed the way canon already fixes it: source
+// order for a list, sorted-key order for a map (`cmpCodePoint`, the
+// comparator `MapVal.canon` and the Go port's marshalling use). A
+// generated list whose order depended on insertion history would differ
+// between two runs of the same document, and between the two ports --
+// the one thing the shared spec exists to prevent.
+//
+// The element is the source child CLONED, not shared: it is a second
+// position holding that value, and a position is where path-dependent
+// content resolves. What the clone keeps is the identity, if the child
+// carries one (G4 phase 1) -- a listed entity is still that entity, and
+// the merge that follows is the point.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { unite } from '../unify'
+import { makeNilErr } from '../err'
+import { ListVal } from './ListVal'
+import { FuncBaseVal } from './FuncBaseVal'
+import { repathInstance } from './Val'
+import { fillPlace } from './PlaceVal'
+import { cmpCodePoint } from '../keyorder'
+
+
+// The children a data bag holds, in the order the result must carry
+// them, or the code naming what is wrong with the argument.
+function dataValues(data: Val | undefined): Val[] | string {
+  const d: any = data
+
+  if (true === d?.isMap) {
+    return Object.keys(d.peg).sort(cmpCodePoint).map((k: string) => d.peg[k])
+  }
+
+  if (true === d?.isList) {
+    return [...(d.peg as Val[])]
+  }
+
+  return 'each_data'
+}
+
+
+class EachFuncVal extends FuncBaseVal {
+  isEachFunc = true
+
+  // THE STAGING RULE, for the reason given in PackFuncVal.
+  staged = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+
+  funcname() {
+    return 'each'
+  }
+
+
+  // The template is not an argument to drive (see PackFuncVal.prepare).
+  prepare(_ctx: AontuContext, _args: Val[]) {
+    return null
+  }
+
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    // ONE argument is driven: the data. The template is not (see
+    // prepare above), and driveStagedArgs answers whether the data has
+    // settled -- the other half of "ready to fire".
+    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 vals = dataValues(args?.[0])
+    if ('string' === typeof vals) {
+      return makeNilErr(ctx, vals, this)
+    }
+
+    const tmpl: Val | undefined = args?.[1]
+    const peg: Val[] = []
+
+    for (let i = 0; i < vals.length; i++) {
+      const elctx = ctx.descend(String(i))
+      const el = vals[i].clone(elctx)
+      // The template is CLONED per element, never shared — a FULL
+      // instance to the leaves (`dup`, ADR-005): see PackFuncVal.resolve.
+      // `_` inside the template binds the source child (G8 phase 3),
+      // which for `each` is the element itself.
+      let inst: Val | undefined = undefined
+      if (undefined !== tmpl) {
+        inst = tmpl.clone(elctx, { dup: true })
+        repathInstance(inst, inst.path)
+      }
+      peg.push(undefined === inst ? el :
+        unite(elctx, el, fillPlace(inst, vals[i], elctx), 'each'))
+    }
+
+    return new ListVal({ peg }, ctx)
+  }
+
+} /* node:coverage ignore next 7 */
+
+
+export {
+  dataValues,
+  EachFuncVal,
+}