aontu 0.52.0 → 0.53.0

package/src/val/CopyFuncVal.ts

@@ -13,7 +13,6 @@ import {
 
 import { makeNilErr } from '../err'
 
-import { NilVal } from '../val/NilVal'
 
 
 import {
@@ -66,6 +65,13 @@ class CopyFuncVal extends FuncBaseVal {
         // console.log('WALK', val)
         val.mark.type = false
         val.mark.hide = false
+        // `copy()` CLEARS IDENTITY (G4 phase 1, clearing rule 2),
+        // consistent with its clearing of the marks: a copy of an
+        // entity is a second value shaped like it, and leaving the id
+        // on would merge the copy straight back into the original —
+        // making `copy()` a no-op for exactly the values it exists to
+        // detach.
+        val.entity = undefined
         return val
       })
     }

package/src/val/Decimal.ts

@@ -176,6 +176,21 @@ class Decimal {
   }
 
 
+  // D6 -- EXACT MULTIPLICATION. Multiply the coefficients, ADD the
+  // scales: (a/10^s)(b/10^t) is ab/10^(s+t), with no alignment step and
+  // no rounding mode, exactly as add() has none.
+  //
+  // The result leaves the budget far more readily than a sum does --
+  // scales add rather than taking the maximum, and coefficient digits
+  // add too -- so squaring a value at half the budget is already over
+  // it. Every caller must test with decimalOverBudget() and report
+  // `decimal_budget`, for the same reason add()'s callers must: at the
+  // limit, refusing is the only answer that is not a rounded one.
+  multiply(peer: Decimal): Decimal {
+    return new Decimal(this.unscaled * peer.unscaled, this.scale + peer.scale)
+  }
+
+
   // Exact ceiling and floor, for `upper()`/`lower()`. Coefficient
   // arithmetic only -- Math.ceil of this value would mean rounding it to
   // binary64 first, which for a leaf that exists to escape binary64 is

package/src/val/DeprecateFuncVal.ts

@@ -0,0 +1,84 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// The deprecation mark (G3 phase 4,
+// docs/capability-review/g3-subsumption-evolution.md): a function-form
+// builtin, `deprecate(x, m)`, that unifies EXACTLY as `x` while the
+// record `m` rides the result through meets. The record's keys are
+// msg, use and since — all optional, all strings; `use` is a path
+// spelled as a STRING, because a live reference would resolve and
+// unify, which is not wanted. Boolean ValMarks cannot hold a record,
+// so the Val carries one optional field (Val.deprecation), propagated
+// by the same channel as the marks (propagateMarks) and rendered back
+// reparseably by canon (canonRiders).
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { FuncBaseVal } from './FuncBaseVal'
+
+
+// The record's whole vocabulary. Other keys are DROPPED, not carried:
+// the record is a contract the tooling reads (vet, the LSP tag, the
+// breaking downgrade), and a bag of free-form keys would be a second,
+// unspecified metadata channel.
+const DEPRECATION_KEYS = ['msg', 'use', 'since']
+
+
+class DeprecateFuncVal extends FuncBaseVal {
+  isDeprecateFunc = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new DeprecateFuncVal(spec)
+  }
+
+  funcname() {
+    return 'deprecate'
+  }
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    let out = args[0] ?? makeNilErr(ctx, 'arg', this)
+
+    // A nil ARGUMENT is returned unchanged, never marked: marking it
+    // makes the bag's marked-child skip drop it (the type()/hide()
+    // lesson — refusal over corruption, D7).
+    if (out.isNil) {
+      return out
+    }
+
+    out = out.clone(ctx)
+
+    const record: Record<string, string> = {}
+    const m: any = args[1]
+    if (true === m?.isMap && null != m.peg) {
+      for (const key of DEPRECATION_KEYS) {
+        const v = m.peg[key]
+        if (true === v?.isScalar && 'string' === typeof v.peg) {
+          record[key] = v.peg
+        }
+      }
+    }
+    out.deprecation = record
+
+    return out
+  }
+} /* node:coverage ignore next 6 */
+
+
+export {
+  DeprecateFuncVal,
+}

package/src/val/DisjunctVal.ts

@@ -13,7 +13,7 @@ import {
 
 import { AontuContext } from '../ctx'
 
-import { makeNilErr } from '../err'
+import { AontuError, descErr, makeNilErr } from '../err'
 import { unite } from '../unify'
 
 import {
@@ -30,8 +30,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'
 
 
@@ -102,6 +102,7 @@ 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]
@@ -117,9 +118,60 @@ 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
@@ -128,6 +180,33 @@ class DisjunctVal extends JunctionVal {
 
     // // // 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++) {
@@ -150,10 +229,14 @@ class DisjunctVal extends JunctionVal {
       }
 
       // // // console.log('DISJUNCT-unify-D', this.id, oval.map(v => v.canon))
-
-      oval = oval.filter(v => !v.isNil)
     }
 
+    // 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) {
@@ -164,6 +247,14 @@ class DisjunctVal extends JunctionVal {
     }
     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,7 +268,11 @@ class DisjunctVal extends JunctionVal {
   }
 
 
-  rankPrefs(ctx: AontuContext) {
+  // Answers the sole surviving preference when ranking collapsed the
+  // disjunction to one -- which the RECURSIVE call below consumes to
+  // lift a nested disjunct's winner into this one. Undefined when
+  // more than one alternative survives, so the type says both.
+  rankPrefs(ctx: AontuContext): PrefVal | undefined {
     let lastpref: PrefVal | undefined = undefined
     let lastprefI = -1
 
@@ -214,7 +309,7 @@ class DisjunctVal extends JunctionVal {
         }
       }
       else if (v.isDisjunct) {
-        let subrank: any = v.rankPrefs(ctx)
+        const subrank = (v as DisjunctVal).rankPrefs(ctx)
         if (subrank instanceof PrefVal) {
           this.peg[vI] = subrank
           lastpref = subrank
@@ -231,6 +326,8 @@ class DisjunctVal extends JunctionVal {
     if (1 === this.peg.length && this.peg[0] instanceof PrefVal) {
       return this.peg[0]
     }
+
+    return undefined
   }
 
 
@@ -246,35 +343,49 @@ 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)
 
-      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
+      return (0 < prefs.length ? prefs[0] : this.peg[0]).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,
+}

package/src/val/ExpectVal.ts

@@ -16,7 +16,6 @@ import {
 import { unite } from '../unify'
 
 import {
-  propagateMarks,
   explainOpen,
   ec,
   explainClose,
@@ -35,6 +34,21 @@ class ExpectVal extends FeatureVal {
   parent?: Val
   key?: string
 
+  // An expectation canons as THE EXPECTATION ITSELF -- the peg the peer
+  // must satisfy. Val.canon's default was the empty string, which
+  // rendered a key with no value (`{"r":}`): text that is not a document
+  // and could not be reparsed, breaking canon's round-trip contract in
+  // both engines (issue #43).
+  //
+  // Not `top`, which was the first fix here and was wrong. An ExpectVal
+  // is created for EVERY peer-introduced non-generable key, not just for
+  // `&:` spread children -- `m:{x:1} m:{y:string}` makes one at `y` with
+  // no spread in sight -- so rendering `top` erased the `string` and the
+  // canon reparsed into a document that accepts values the original
+  // rejects. A canon that silently drops a constraint is worse than one
+  // that fails to parse. Go's ExpectVal.Canon renders the same peg.
+  get canon() { return this.peg.canon }
+
   constructor(
     spec: ValSpec,
     ctx?: AontuContext
@@ -42,21 +56,42 @@ class ExpectVal extends FeatureVal {
     super(spec, ctx)
   }
 
+  // PURE, deliberately (the unequal-spread crosswire, BUGS.md §6-§7).
+  // The old body accumulated `this.peer` IN PLACE, which was invisible
+  // while an expectation only ever lived at one destination -- but the
+  // spread-combination meet (MapVal.unify's 'map-self' unite) bakes an
+  // ExpectVal INTO the combined template, and a path-independent
+  // template is SHARED across every destination (spreadClone tier 1).
+  // One stateful node in a shared template unified each sibling's own
+  // data with the next sibling's ($.w.y.r: "Cannot unify value: 6 with
+  // value: 5", both values sibling data). An expectation now answers
+  // with a NEW node when it must keep accumulated state, so a shared
+  // template's expect stays exactly what was written.
   unify(peer: Val, ctx: AontuContext): Val {
     const te = ctx.explain && explainOpen(ctx, ctx.explain, 'Expect', this, peer)
 
-    let out = this
+    let out: Val = this
 
     if (!peer.isTop) {
-      this.peer = undefined === this.peer ? peer :
+      const acc = undefined === this.peer ? peer :
         unite(te ? ctx.clone({ explain: ec(te, 'PEER') }) : ctx, this.peer, peer, 'expect-peer')
 
       const peeru =
-        unite(te ? ctx.clone({ explain: ec(te, 'EXPECT') }) : ctx, this.peer, this.peg, 'expect-self')
+        unite(te ? ctx.clone({ explain: ec(te, 'EXPECT') }) : ctx, acc, this.peg, 'expect-self')
 
       if (peeru.isGenable) {
         out = peeru
       }
+      else {
+        // Still an expectation: carry the accumulated peer forward in a
+        // fresh node stored at THIS destination by the caller, leaving
+        // `this` -- possibly a shared template's child -- untouched.
+        const e = new ExpectVal({ peg: this.peg }, ctx)
+        e.key = this.key
+        e.parent = this.parent
+        e.peer = acc
+        out = e
+      }
     }
 
     out.dc = DONE
@@ -68,8 +103,10 @@ class ExpectVal extends FeatureVal {
 
 
   gen(ctx: AontuContext) {
-    // Unresolved expect cannot be generated, so always an error.
-    let nil = makeNilErr(
+    // Unresolved expect cannot be generated, so always an error. The
+    // CALL is the point -- it records the failure on ctx -- and there
+    // is no value to bind: generation answers nothing.
+    makeNilErr(
       ctx,
       'expect',
       this.peg,

package/src/val/FeatureVal.ts

@@ -40,7 +40,7 @@ abstract class FeatureVal extends Val {
     descErr(nerr, ctx)
     ctx?.adderr(nerr)
 
-    if (null == ctx || !ctx?.collect) {
+    if (null == ctx || !ctx.collect) {
       const aerr = new AontuError(nerr.msg, [nerr])
       throw aerr
     }