aontu 0.52.1 → 0.54.0

package/src/val/PrefVal.ts

@@ -11,21 +11,52 @@ import {
 
 import { AontuContext } from '../ctx'
 import { unite } from '../unify'
-import { AontuError } from '../err'
+import { AontuError, makeNilErr } from '../err'
 
 import {
   explainOpen,
   ec,
-  explainClose,
+  explainClose
 } from '../utility'
 
 
 import { top } from './top'
 
 import { FeatureVal } from './FeatureVal'
-import { ScalarKindVal, kindFamily } from './ScalarKindVal'
+import { trialUnify } from './FuncBaseVal'
+import { superOf } from './SuperFuncVal'
+
+
+// The innermost preferred value under every pref layer: the value a
+// preference of ANY rank ultimately defends, and the one generation
+// emits for it. Shared by the disjunct admission gate (DisjunctVal),
+// the defaulted-scrutinee rule (MatchFuncVal) and the effective-default
+// walk (subsume.ts) so "the default's value" cannot mean three things.
+function prefInnerPeg(v: Val): Val {
+  let out: any = v
+  while (true === out?.isPref) {
+    out = out.peg
+  }
+  return out
+}
 
 
+// A CONTAINER DEFAULT IS LEAFWISE (ADR-011 R3,
+// docs/design/DEFAULTS.0.md): `*{p:1}` MEANS `{p: *1}` and `*[1]`
+// means `[*1]`, so there is no such thing as a preference whose
+// preferred value is a bag. Shape is not a value and takes no star --
+// key optionality, closedness and a `&:` spread template ride through
+// untouched; only the values a reader could override are defaulted.
+//
+// This is the rule `pref()` already had (its resolve walked and
+// wrapped every scalar child) and the star prefix did not, so the two
+// spellings of one operator disagreed: `pref({p:1}) & {q:2}` kept the
+// `p` default and `*{p:1} & {q:2}` dropped it. Both spellings and the
+// resolve-time case (`*$.shape`) come through here now, so they
+// cannot drift apart again. Wrapping the non-bag arm rather than
+// walking for scalars also closes the other half of that gap:
+// `pref(integer)` and `pref(min(3))` used to answer the bare value,
+// losing the preference outright.
 class PrefVal extends FeatureVal {
   isPref = true
   isGenable = true
@@ -37,22 +68,40 @@ class PrefVal extends FeatureVal {
   // Both are assigned by resuper(), called from the constructor.
   superpeg!: Val
 
-  // The gate an overriding peer must pass. A preference is a DEFAULT, so
-  // a concrete peer replaces it -- but only within the preferred value's
-  // FAMILY: `*lower(1.1) & a` is a conflict, not an override.
+  // THE GATE AN OVERRIDING PEER MUST PASS IS `superpeg` ITSELF — the
+  // preferred value's own KIND, not its family.
+  //
+  // A preference is a DEFAULT, so a concrete peer replaces it, but only
+  // where the peer is the same kind of thing: `*lower(1.1) & a` is a
+  // conflict, not an override. The number tower made `integer` and
+  // `float` disjoint siblings under `number`, and this gate used to
+  // widen to that family — so `*2.2 & 3` worked, and so did
+  // `*8080 & 3.5`. Those are ONE rule in two directions; no kind-based
+  // gate can keep the first and refuse the second.
   //
-  // Family and not leaf, because the number tower made `integer` and
-  // `float` disjoint siblings under `number`. Gating on the leaf would
-  // turn `*lower(2.2) & 3` (a float default overridden by an integer)
-  // into an error, which is a tightening no document asked for; gating
-  // on the family keeps it working and makes the mirror case
-  // (`*2 & 3.0`, an error before the tower) work too. For every
-  // non-numeric value the family root IS the leaf, so this is the
-  // preferred value's type as before.
-  familypeg!: Val
+  // Refusing both is the choice, because the second is the documented
+  // default idiom: `port: *8080 | integer` accepted 3.5 in both ports,
+  // silently widening every key written that way from integer to
+  // number — the finding §6 of the 2026-08-21 status report calls the
+  // most consequential, precisely because docs/skill/examples.md
+  // teaches the idiom to agents.
+  //
+  // What the tightening costs is named rather than hidden: mixing the
+  // numeric leaves around a preference is now an error instead of a
+  // silent widening. `*1.5 & integer` used to answer `integer` and
+  // DISCARD a default that could never apply; it now says so.
 
   rank: number = 0
 
+  // THE OVERRIDE SPACE, NARROWED (ADR-011 R1). The second arm of the
+  // distribution -- `super(x) & every peer met so far` -- kept here as
+  // well as in `superpeg`, because resuper() recomputes the gate from
+  // the peg whenever the peg resolves and would otherwise widen it
+  // back to `super(x)`: a rank>=2 default, whose peg is itself a
+  // preference and so is re-driven, lost its narrowing that way and
+  // let a pinned `***false & false` be overridden by `true`.
+  narrowed?: Val
+
   constructor(
     spec: ValSpec,
     ctx?: AontuContext
@@ -66,45 +115,66 @@ class PrefVal extends FeatureVal {
       this.rank = 1 + spec.peg.rank
     }
 
-    this.resuper()
+    this.resuper(ctx)
     // console.log('PVC', this.peg.canon, this.superpeg.canon)
   }
 
 
   // Recompute the type yardstick and the override gate from the current
   // peg. Called again whenever the peg resolves (e.g. a ref).
-  private resuper() {
-    const peg: any = this.peg
-
-    // A preference whose peg is ITSELF a kind (`*integer`) constrains
-    // nothing: there is no type-of-a-type in this lattice, so any peer
-    // wins. (Pinned by test/spec/var.tsv:var-pref-kind-narrow. Before
-    // the tower this fell out of a ScalarKindVal's superior being top;
-    // now that a leaf kind lifts to `number`, it has to be said.)
-    if (true === peg.isScalarKind) {
-      this.superpeg = top()
-      this.familypeg = this.superpeg
-      return
+  //
+  // THE GATE IS super() (ADR-011 R4, docs/design/DEFAULTS.0.md). `*x`
+  // is sugar for `*x | super(x)`, so the type an overriding peer must
+  // pass is the one the long form spells out loud -- one function, not
+  // a second implementation that agrees with it on the common case.
+  // Two special cases retired with the switch: a KIND peg gated
+  // nothing (`*integer` was overridden by `"s"`) and a CONSTRAINT peg
+  // had no gate at all, both written when a kind's superior was top.
+  // `super(integer)` is `number`, so `7` still wins and `"s"` refuses.
+  private resuper(ctx?: AontuContext) {
+    // THE RANK-UNIFORM MEET (ADR-004). The yardstick is the INNERMOST
+    // preferred value's kind, whatever the preference's rank: `**1.5`
+    // defends `float` exactly as `*1.5` does. The old rule read the
+    // immediate peg, and a rank>=2 peg is itself a PrefVal whose
+    // superior is top -- so ANY conjunct overrode a ranked default
+    // (`**1.5 & float` dropped the default and died as mapval_no_gen;
+    // `**2|integer` met by a bare `integer` lost the default the
+    // spelling exists to carry -- use-cases/BUGS.md §3), while the
+    // rank-1 spelling of the same document kept it. One rule, every
+    // rank. Pinned by test/spec/pref.tsv (pref-rank2-* rows, and the
+    // flipped pref-nested-concrete-wins).
+    // THE RANK-UNIFORM MEET (ADR-004) is unchanged: the yardstick is
+    // the INNERMOST preferred value, whatever the rank, so `**1.5`
+    // defends `float` exactly as `*1.5` does.
+    let peg: any = this.peg
+    while (true === peg?.isPref) {
+      peg = peg.peg
     }
 
-    const sup: any = peg.superior()
-    this.superpeg = sup
-
-    // No optional chain: superior() is contractually non-null (every
-    // Val returns one, a NilVal returning itself), so guarding against
-    // nullish here would claim a possibility the type does not have.
-    if (true === sup.isScalarKind) {
-      const family = kindFamily(sup.peg)
-      // The gate stands in for the preferred value in any conflict it
-      // reports, so it must carry the same site and path as the type it
-      // widens -- otherwise NilVal.make picks a different primary and
-      // the error moves to the wrong path.
-      this.familypeg = family === sup.peg ?
-        sup : sup.place(new ScalarKindVal({ peg: family, path: sup.path }))
-    }
-    else {
-      this.familypeg = sup
+    const base = superOf(ctx as AontuContext, peg)
+
+    // A gate that a meet has already narrowed stays narrowed: the
+    // override space only ever shrinks.
+    this.superpeg = null == this.narrowed ? base
+      : unite(ctx as AontuContext, base, this.narrowed,
+        'pref-narrow/' + this.id)
+  }
+
+
+  // The default, standing but NARROWED: `*integer & 7` is `*7`, which
+  // is what the long form answers (`(integer&7) | (number&7)` keeps
+  // the star on the arm that survived). The rank rides across -- a
+  // ladder rung that narrows is still that rung.
+  // The rank is REBUILT as nesting rather than stamped: canon renders
+  // one star per layer (`'*' + peg.canon`), so a rank set directly on
+  // a single layer would print `*x` for a rank-2 default and the
+  // document would no longer round-trip.
+  private restand(met: Val, ctx: AontuContext): Val {
+    let out: Val = met
+    for (let rI = 0; rI <= this.rank; rI++) {
+      out = new PrefVal({ peg: out }, ctx)
     }
+    return this.place(out)
   }
 
 
@@ -122,9 +192,27 @@ class PrefVal extends FeatureVal {
         this.peg, top(), 'pref/resolve')
       // console.log('PREF-RESOLVED', this.peg.canon, '->', resolved)
       this.peg = resolved
-      this.resuper()
+      this.resuper(ctx)
     }
 
+    // A CONTAINER DEFAULT IS LEAFWISE IN EFFECT (ADR-011 R3), and it
+    // gets there through the meet above rather than through a rewrite.
+    // `*{p:1}` keeps its written shape -- canon prints `*{"p":1}` and
+    // reparses to itself, which a rewrite to `{p:*1}` would break, and
+    // an alternative still has a star for a disjunction to choose by.
+    // What makes it leafwise is that the two arms decide:
+    //
+    //   `& {q:2}`  the preferred value ITSELF admits the peer (maps
+    //              merge), so the default stands as `*{p:1,q:2}` and
+    //              `p` survives -- it used to be REPLACED outright.
+    //   `& {p:2}`  the preferred value refuses, so the gate answers:
+    //              `super({p:1})` is `{p:integer}`, which admits it.
+    //   `& "s"`    both arms are empty, so the whole default is --
+    //              a string used to override a map default silently.
+    //
+    // Which is every rule R3 asks for, with no bag ever standing where
+    // the author wrote a scalar and no canon that fails to round-trip.
+
     if (peer instanceof PrefVal) {
       why += 'pref-'
       if (this.id === peer.id) {
@@ -152,9 +240,20 @@ class PrefVal extends FeatureVal {
         //   peer.peg.id, peer.peg, peer.peg.done,
         // )
 
-        let peg = unite(te ? ctx.clone({ explain: ec(te, 'PREF-PEER') }) : ctx,
-          this.peg, peer.peg, 'pref-peer/' + this.id)
-        out = new PrefVal({ peg }, ctx)
+        const peg = trialUnify(ctx, prefInnerPeg(this).clone(ctx),
+          prefInnerPeg(peer))
+
+        // TWO DEFAULTS OF EQUAL RANK THAT CANNOT AGREE (ADR-011 R2):
+        // the refusal is about the DEFAULTS, not about the values they
+        // happen to hold, and its hint names the fix -- rank one of
+        // them. Compatible pegs still fold (`*1 & *integer` is `*1`),
+        // and identical ones collapse, so only a real disagreement
+        // reaches this arm. The three spellings of it -- `*1 & *7`,
+        // `(*1|integer) & *7` and `*1|*7` -- used to answer a value
+        // conflict, the newcomer, and the newcomer again.
+        out = undefined === peg
+          ? makeNilErr(ctx, 'pref_rank_clash', this, peer, 'unify')
+          : this.restand(peg, ctx)
         // console.log('PREF-RANK-SAME-OUT', peg, peg.done, out, out.done)
         why += 'rank-same'
       }
@@ -162,17 +261,84 @@ class PrefVal extends FeatureVal {
     else if (!peer.isTop) {
       why += 'super-'
 
-      out = unite(te ? ctx.clone({ explain: ec(te, 'SUPER') }) : ctx,
-        this.familypeg, peer, 'pref-super/' + this.id)
-
-      // The peer added nothing beyond a type the preferred value already
-      // satisfies (`*1 & integer`, `*1 & number`), so the preference
-      // stands. Anything else is a concrete override and wins.
-      if (out.same(this.superpeg) || out.same(this.familypeg)) {
-        out = this.peg
-        why += 'same'
+      // THE MEET IS THE DESUGARING, DISTRIBUTED (ADR-011 R1,
+      // docs/design/DEFAULTS.0.md). `*x` stands for `*x | super(x)`,
+      // and a peer meets a disjunction arm by arm:
+      //
+      //     (x & peer)  |  (super(x) & peer)
+      //
+      // THE FIRST ARM DECIDES. When the preferred value itself still
+      // satisfies the peer the default STANDS -- `*1 & integer`,
+      // `*8080 & min(1024)`, `**2 & neq(1)`: the peer narrowed the
+      // type without ruling the default out, which is the whole point
+      // of writing one. Only when that arm is empty does the second
+      // answer, and that is the override. When BOTH are empty nothing
+      // remains of the disjunction the star stands for -- `empty`,
+      // the same refusal the written-out long form gives.
+      //
+      // The old rule asked instead whether the peer resolved to
+      // exactly `super(x)`, so any narrowing at all counted as an
+      // override: `*1 & integer` stood (the peer WAS the gate) but
+      // `*8080 & min(1024)` silently dropped the default and answered
+      // the bare constraint, and a rank ladder lost its weaker arm to
+      // the same rule the moment anything narrowed it.
+      //
+      // Trialled against a CLONE, on the innermost value (the
+      // rank-uniform meet): the preferred value must stay pristine for
+      // the arm that stands, and a failed trial must not leave its
+      // errors on the context -- the DisjunctVal admission gate's own
+      // precedent, and its mechanism.
+      const met = trialUnify(ctx, prefInnerPeg(this).clone(ctx), peer)
+
+      if (undefined !== met) {
+        // THE SECOND ARM IS CARRIED FORWARD, not discarded. It is the
+        // override space -- everything the peer would still admit
+        // INSTEAD of the default -- and meeting a peer narrows it just
+        // as it narrows the default: two successive meets compose to
+        // `(x & p1 & p2) | (super(x) & p1 & p2)`, which is the
+        // distribution over both. Dropping it let a constraint that
+        // arrived beside a default vanish: `r:*2` with `r:max(20)`
+        // stood as a bare `*2`, and `r:40` then overrode it through a
+        // gate that no longer remembered the bound.
+        //
+        // It cannot fail: the first arm succeeded, so `x & peer` has a
+        // value, and that value satisfies `super(x)` and `peer` both.
+        const gate = unite(te ? ctx.clone({ explain: ec(te, 'GATE') }) : ctx,
+          this.superpeg.clone(ctx), peer, 'pref-gate/' + this.id)
+
+        // Unchanged on both counts is the SAME preference, returned as
+        // itself: minting a new one every pass would keep the fixpoint
+        // moving for ever.
+        if (met.same(prefInnerPeg(this)) && gate.same(this.superpeg)) {
+          out = this
+        }
+        else {
+          const stood = this.restand(met, ctx) as PrefVal
+          stood.narrowed = gate
+          stood.superpeg = gate
+          out = stood
+        }
+
+        why += 'stands'
+        explainClose(te, out)
+        out.dc = DONE
+        return out
       }
 
+      // The override arm is trialled too: its failure is not the
+      // answer, it is half of the reason the answer is `empty`, and a
+      // recorded `no_scalar_unify` would be the code the reader sees
+      // however the refusal is relabelled afterwards.
+      const over = trialUnify(ctx, this.superpeg.clone(ctx), peer)
+
+      out = undefined !== over ? over
+        // A peer that arrived already failed keeps its own refusal:
+        // that is its failure, not the default's.
+        : peer.isNil ? peer
+          : makeNilErr(ctx, 'empty', this, peer, 'unify')
+
+
+
       // }
     }
     else {
@@ -205,7 +371,31 @@ class PrefVal extends FeatureVal {
 
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     let out = (super.clone(ctx, spec) as PrefVal)
-    // out.pref = this.pref.clone(null, ctx)
+
+    // THE NARROWED OVERRIDE SPACE TRAVELS WITH THE COPY (ADR-011 R1).
+    // A default a meet has pinned stays pinned through a reference:
+    // without this, `T:{e:***false & false}` copied by `f:$.T` handed
+    // back a default whose gate had widened again to `boolean`, and
+    // `f:{e:true}` overrode a value the author had pinned. The Go
+    // twin carries the same two fields explicitly (clone.go).
+    if (null != this.narrowed) {
+      out.narrowed = this.narrowed
+      out.superpeg = this.superpeg
+    }
+    // THE PER-DESTINATION INSTANTIATION RULE (ADR-005). The default
+    // clone shares the preferred value (`peg: this.peg` in Val.clone)
+    // — a cloned pref spread template resolves its inner value at the
+    // template's own location, pinned behaviour. But a template
+    // INSTANCE must own it: with the peg shared, a rank-2 default
+    // (`**key(1) | string`) in a pack template resolved its one
+    // shared inner key() at the first destination and every child got
+    // the first child's key (use-cases/BUGS.md §9 — rank 1 escaped
+    // only because its unify builds a fresh PrefVal per meet). The
+    // superpeg yardstick from the shared peg still holds: the clone's
+    // innermost value is the same kind.
+    if (true === spec?.dup && true === (this.peg as any)?.isVal) {
+      out.peg = this.peg.clone(ctx, { dup: true })
+    }
     return out
   }
 
@@ -227,9 +417,10 @@ class PrefVal extends FeatureVal {
 
     return val.gen(ctx)
   }
-} /* node:coverage ignore next 6 */
+} /* node:coverage ignore next 7 */
 
 
 export {
   PrefVal,
+  prefInnerPeg,
 }