aontu 0.62.0 → 0.64.0

package/src/val/ListVal.ts

@@ -69,8 +69,6 @@ class ListVal extends BagVal {
               spread.v[0] :
             spread.v
 
-        // let tmv = Array.isArray(spread.v) ? spread.v : [spread.v]
-        // this.spread.cj = new ConjunctVal({ peg: tmv }, ctx)
       }
     }
   }
@@ -88,23 +86,10 @@ class ListVal extends BagVal {
     const TOP = top()
     peer = peer ?? TOP
 
-    // A sizing residual (`length`, `unique`) sorts AFTER containers in a
-    // conjunct so that it counts the MERGED list rather than the first
-    // fragment (SIZING_CJO in ConstraintVal.ts). That makes the list the
-    // accumulator and the constraint its peer, the reverse of the usual
-    // order — and the reading belongs to the constraint either way, so
-    // hand it straight back.
     if (true === (peer as any).isConstraint) {
       return peer.unify(this, ctx)
     }
 
-    // A DISJUNCT ALTERNATIVE MATCHES ITS OWN LENGTH (BUGS.md §52
-    // regime 4, the X-C3 adjudication): in a trial, a literal list
-    // with no spread admits only a peer list of the same length -- a
-    // spread makes it variadic. Outside trials the ordinary
-    // elementwise merge stands (two statements of one list are one
-    // list), so `[] | [&: T]` stops admitting every list through the
-    // empty arm while `a: [] a: [1]` still merges.
     if (true === ctx._trialMode && true === (peer as any).isList
       && null == this.spread.cj && null == (peer as any).spread.cj
       && this.peg.length !== (peer as any).peg.length) {
@@ -153,19 +138,6 @@ class ListVal extends BagVal {
 
         propagateMarks(this, child)
 
-        // APPLIED ONCE PER ELEMENT, the guard MapVal has carried since
-        // the spread was written: an element that already holds this
-        // template's contribution is progressed by self-unification
-        // instead of having the template met into it a second time.
-        // Re-applying is the identity for a template that has already
-        // RESOLVED, which is why the missing guard went unnoticed here
-        // — but a template that residuates (`&: {k: key(1)}`, G8 phase
-        // 0) is not yet a value to be idempotent about, so each pass
-        // conjoined another copy and the element's canon DOUBLED per
-        // pass. The old `ctx.cc < 3` key delay hid it by ending the
-        // growth at three passes; the staging rule waits for the model
-        // to settle, and a model whose canon doubles every pass never
-        // does.
         let oval: Val
         if (!spread_cj.isTop
           && (child as any)._spr === spreadId(spread_cj)) {
@@ -187,11 +159,6 @@ class ListVal extends BagVal {
           oval =
             child.isNil ? child :
                 key_spread_cj.isNil ? key_spread_cj :
-                  // The no-op meet is SKIPPED on the normal path (it is the
-                  // identity) but TAKEN while recording: a value written once
-                  // and never met is still a contribution the author wants
-                  // pointed at, and the Go port's unite sees that meet (G7
-                  // phase 4). Instrumented runs pay knowingly.
                   key_spread_cj.isTop && child.done && undefined === keyctx.prov
                     ? child :
                     child.isTop && key_spread_cj.done ? key_spread_cj :
@@ -281,13 +248,6 @@ class ListVal extends BagVal {
   }
 
 
-  // Spread clone: only deep-clone children that are path-dependent
-  // (isFunc, isRef). Share all other children directly.
-  // Spread clone: when all children are ScalarKindVal (simple type
-  // constraints like `string`, `number`), share them directly to avoid
-  // N x M allocations. ScalarKindVal is safe to share: it is immutable,
-  // always done, never path-dependent, and never has marks mutated.
-  // For anything more complex, fall back to full deep clone.
   spreadClone(ctx: AontuContext): Val {
     // B1: share directly when the spread tree has no path-dependent
     // leaves. See MapVal.spreadClone for rationale.
@@ -337,11 +297,6 @@ class ListVal extends BagVal {
       out.peg[entry[0]] =
         (entry[1] as any)?.isVal ? (entry[1] as Val).clone(ctx, {
           ...childspec,
-          // AN ELEMENT IS A POSITION, exactly as a map's child is
-          // (MapVal.clone). Without this an explicitly pathed clone
-          // rebased the list and left every element at its source
-          // path -- the Go twin descends by index (go/clone.go, the
-          // *ListVal arm of clonePathKind).
           path: [...out.path, entry[0]],
         }) : entry[1]
     }
@@ -352,36 +307,22 @@ class ListVal extends BagVal {
     out.closed = this.closed
     out.optionalKeys = [...this.optionalKeys]
 
-    // console.log('LISTVAL-CLONE', this.canon, '->', out.canon)
     return out
   }
 
 
   get canon() {
-    // console.log('LISTVAL-CANON', this.optionalKeys)
     let keys = Object.keys(this.peg)
     return '' +
-      // this.errcanon() +
       '[' +
       (this.spread.cj ? '&:' + this.spread.cj.canon +
         (0 < keys.length ? ',' : '') : '') +
-      // No optional-element rendering. A list HAS no optional elements to
-      // render: a key:value pair in list position contributes no element
-      // at all, in either spelling and whatever its key (issue #40), so
-      // nothing a source can write reaches this method with an optional
-      // key. The Go port's ListVal.Canon has no such arm either, and the
-      // two canons must agree -- a canon is round-trippable, and a marker
-      // on an element the grammar cannot produce would not reparse.
-      // canonRiders, not .canon: a deprecated element renders
-      // back as its `deprecate(x, m)` call, reparseably (G3).
       keys.map(k => canonRiders(this.peg[k])).join(',') +
       ']'
   }
 } /* node:coverage ignore next 8 */
 
 
-
-
 export {
   ListVal,
 }

package/src/val/LowerFuncVal.ts

@@ -19,7 +19,6 @@ import { Decimal } from '../val/Decimal'
 import { caseRange, rangeArg } from './caserange'
 
 
-
 import { FuncBaseVal } from './FuncBaseVal'
 
 
@@ -51,12 +50,6 @@ class LowerFuncVal extends FuncBaseVal {
     const arg = args?.[0]
     const oldpeg = arg?.peg
 
-    // THE RANGE (ts/src/val/caserange.ts): `start` names the first
-    // character of the run when it is zero or positive and the last
-    // when it is negative; `len` of -1, and the absent argument, are
-    // the source's length. Refused on a NUMBER, where a run of
-    // characters means nothing -- the numeric arm below is a ceiling,
-    // not a case mapping.
     const start = rangeArg(args?.[1])
     const len = rangeArg(args?.[2])
     const ranged = undefined !== start || undefined !== len
@@ -68,11 +61,6 @@ class LowerFuncVal extends FuncBaseVal {
     const peg = 'string' === typeof oldpeg ?
       caseRange(oldpeg, start ?? 0, len ?? -1, false) :
       'number' === typeof oldpeg ? Math.floor(oldpeg) :
-        // The exact leaves take an EXACT floor and keep their kind: a
-        // biginteger is already integral so it is its own floor, and a
-        // bigdecimal floors by coefficient arithmetic. Math.floor is not
-        // an option for either — it would round the value into binary64
-        // first, which is the loss the `0d` leaves exist to refuse.
         'bigint' === typeof oldpeg ? oldpeg :
           oldpeg instanceof Decimal ? oldpeg.floor() :
             undefined

package/src/val/MapVal.ts

@@ -39,20 +39,10 @@ import { cmpCodePoint } from '../keyorder'
 import { markSpread } from '../provenance'
 
 
-// Structural snapshots of ref spreads (see MapVal.unify), keyed by the
-// ref's canon + source site rather than object identity: spread
-// application clones templates (and the refs inside them) freely, and a
-// clone must find the snapshot its parse-origin ref captured on an early
-// pass. The map lives on the unify root ctx (see Unify), so it persists
-// across fixpoint passes and is GC'd with the run.
 function spreadSnapKey(cj: any): string {
   return cj.spelling + '~' + cj.site.row + ':' + cj.site.col
 }
 
-// Snapshot a path-dependent ref spread to its structural target once,
-// while inner key()/path() funcs in the target are still unresolved (see
-// the call site comments in MapVal.unify). Shared by the direct
-// application path and the deferred-spread early-snapshot walk.
 function snapshotRefSpread(cj: any, ctx: AontuContext): Val | undefined {
   let snapmap: Map<string, Val> | undefined = (ctx as any).snapmap
   if (undefined === snapmap) {
@@ -70,12 +60,6 @@ function snapshotRefSpread(cj: any, ctx: AontuContext): Val | undefined {
     // A ref to a type() resolves to its inner template — snapshot that,
     // so a type-wrapped ref behaves like a plain-map ref spread.
     if (tgt && (tgt as any).isTypeFunc) tgt = (tgt as any).peg?.[0]
-    // A pending type()/hide() CALL is not yet a value to snapshot
-    // (ADR-005, the same rule find's non-snap path defers on): cached
-    // here it resolves at every destination and STAMPS marks the
-    // clearing walk ran too early to clear -- a mutual recursive
-    // schema's members vanished from generation this way. No cache;
-    // retry once the wrapper has resolved at its own field.
     if (tgt && pendingMarkWrapper(tgt)) {
       return undefined
     }
@@ -119,12 +103,6 @@ class MapVal extends BagVal {
 
     if (spread) {
       if ('&' === spread.o) {
-        // Multiple same-level spreads arrive as an array and conjoin;
-        // an unequal spread arriving from ANOTHER statement meets this
-        // one in unify's spread combination below — sound since the
-        // combined template became stateless (pure ExpectVal, BUGS.md
-        // §6-§7): each child meets the combined constraint
-        // independently and children never meet each other's data.
         this.spread.cj =
           Array.isArray(spread.v) ?
             1 < spread.v.length ?
@@ -134,25 +112,9 @@ class MapVal extends BagVal {
       }
     }
 
-    // console.log('MAPVAL-ctor', this.type, spec)
   }
 
 
-  // NOTE: order of keys is not preserved!
-  // not possible in any case - consider {a,b} unify {b,a}
-  // ALIAS DECLARATIONS MUST SIT AT THE DOCUMENT ROOT. Stated on the
-  // VALUE rather than at the parse, because the parse cannot see it: an
-  // INCLUDED file's declarations are at the root of their own text, and
-  // only once the loaded map is placed does it become apparent that
-  // root is not the document's. `%name` is spelled as a reference from
-  // the document root, so an included file's own `%b` would otherwise
-  // reach the INCLUDER's `%b` -- cross-file capture, the hazard the
-  // sigil exists to prevent, one level up.
-  //
-  // P1 is single-file by construction; carrying a name ACROSS files is
-  // what `export` and the destructure are for (P2, not built), and this
-  // refusal is what keeps the two from being confused meanwhile. Pathed
-  // at the DECLARATION, which is what is wrong, not at the map.
   aliasDeclarationsAreRooted(ctx: AontuContext): Val | undefined {
     if (0 === this.aliasKeys.length || 0 === this.path.length) {
       return undefined
@@ -168,17 +130,10 @@ class MapVal extends BagVal {
     if (undefined !== arooted) {
       return arooted
     }
-    // console.log('MAPVAL-UNIFY', this.id, this.canon, peer.id, peer.canon)
 
     const TOP = top()
     peer = peer ?? TOP
 
-    // A sizing residual (`length`, `unique`) sorts AFTER containers in a
-    // conjunct so that it counts the MERGED map rather than the first
-    // fragment (SIZING_CJO in ConstraintVal.ts). That makes the map the
-    // accumulator and the constraint its peer, the reverse of the usual
-    // order — and the reading belongs to the constraint either way, so
-    // hand it straight back.
     if (true === (peer as any).isConstraint) {
       return peer.unify(this, ctx)
     }
@@ -197,10 +152,6 @@ class MapVal extends BagVal {
     out.spread.cj = this.spread.cj
     out.site = this.site
 
-    // A rel() peer DRIVES whichever side the fold hands it on: the
-    // relation constraint rewrites this container leaf by leaf
-    // (RELATIONS.0.md §3.2), exactly as a sizing residual takes the
-    // driver's seat above.
     if (true === (peer as any)?.isRel) {
       return peer.unify(this, te ? ctx.clone({ explain: ec(te, 'REL') }) : ctx)
     }
@@ -229,24 +180,6 @@ class MapVal extends BagVal {
       }
 
       if (!exit) {
-        // Combine two spread constraints. Identical templates (same canon)
-        // collapse to one: re-unifying them resolves key()/path() at the
-        // shared intermediate path, producing spurious values (f1bb1063).
-        // Distinct templates are unified in place — unite is idempotent,
-        // whereas deferring the distinct case into a fresh ConjunctVal (as
-        // f1bb1063 did) re-wraps every fixpoint pass, growing the conjunct
-        // without bound and non-terminating on real models (the apidef +
-        // sdkgen entity schemas each contribute a `&:` spread with name:key(),
-        // combined here). unite resolves key()/path() at each destination via
-        // spreadClone below, so nested + sibling key() cases stay correct
-        // (test/spec/spread-nested-key, spread-key-all).
-        //
-        // The combined template must stay STATELESS: this meet wraps a
-        // key present in only one side as an ExpectVal, the combined
-        // map is shared across destinations when path-independent
-        // (spreadClone tier 1), and a stateful expect accumulated the
-        // first sibling's data and met it into the next (BUGS.md
-        // §6-§7). ExpectVal.unify is pure for exactly this reason.
         out.spread.cj = null == out.spread.cj ? peer.spread.cj : (
           null == peer.spread.cj ? out.spread.cj :
             out.spread.cj.canon === peer.spread.cj.canon ? out.spread.cj :
@@ -256,32 +189,20 @@ class MapVal extends BagVal {
       }
     }
     else {
-      // console.log('MAPVAL-PEER-OTHER', this.id, this.canon, this.done, peer.id, peer.canon, peer.done)
     }
 
 
     if (!exit) {
       out.dc = this.dc + 1
 
-      // let newtype = this.type || peer.type
 
       let spread_cj = out.spread.cj ?? TOP
 
-      // Snapshot a path-dependent *ref* spread to its structural target
-      // once (while inner key()/path() funcs are still unresolved), so
-      // later fixpoint passes don't re-resolve the ref against the mutated
-      // tree and capture the target's own resolved key()/path() literals,
-      // which would leak the source key into the spread destination.
       if (spread_cj.isRef && (spread_cj as any).find) {
         const snap = snapshotRefSpread(spread_cj, ctx)
         if (snap) spread_cj = snap
       }
 
-      // A type() used as a spread applies as its inner template: emit the
-      // (constrained) values at each destination rather than marking the
-      // destination as a type. I.e. `&:type({k:key(),x:number})` behaves
-      // like the non-type spread `&:{k:key(),x:number}` — key() resolves
-      // to the destination key, kinds constrain, fields are emitted.
       if ((spread_cj as any).isTypeFunc) {
         spread_cj = (spread_cj as any).peg?.[0] ?? TOP
       }
@@ -293,15 +214,6 @@ class MapVal extends BagVal {
 
         propagateMarks(this, child)
 
-        // Apply the spread constraint ONCE per child (marked with the
-        // constraint's id below): the first application merges the
-        // template into the child (with key()/path() placeholders that
-        // resolve in place on later passes), so the constraint content
-        // is inside the child from then on and only self-unification is
-        // needed to progress it. Re-applying on every fixpoint pass and
-        // every conjunct-fold step is the identity (unite is idempotent)
-        // but costs O(keys) deep template clones per pass on large
-        // models — the dominant cost on generated-SDK model trees.
         let oval: Val
         // No `undefined !== child` here: propagateMarks above already
         // dereferenced it, so a missing child would have thrown there.
@@ -327,11 +239,6 @@ class MapVal extends BagVal {
           oval =
             child.isNil ? child :
                 key_spread_cj.isNil ? key_spread_cj :
-                  // The no-op meet is SKIPPED on the normal path (it is the
-                  // identity) but TAKEN while recording: a value written once
-                  // and never met is still a contribution the author wants
-                  // pointed at, and the Go port's unite sees that meet (G7
-                  // phase 4). Instrumented runs pay knowingly.
                   key_spread_cj.isTop && child.done && undefined === keyctx.prov
                     ? child :
                     child.isTop && key_spread_cj.done ? key_spread_cj :
@@ -369,9 +276,6 @@ class MapVal extends BagVal {
             out.optionalKeys.push(peerkey)
           }
 
-          // ... and so is an alias declaration, for the same reason:
-          // two statements for one map are one map, and a name declared
-          // in either is declared in the result.
           if (upeer.aliasKeys.includes(peerkey) && !out.aliasKeys.includes(peerkey)) {
             out.aliasKeys.push(peerkey)
           }
@@ -381,15 +285,6 @@ class MapVal extends BagVal {
           const peerctx = ctx.descend(peerkey)
 
           let oval = out.peg[peerkey] =
-            // A peer-only key is CARRIED, not met — except on an
-            // instrumented run, where the identity meet is taken so
-            // the recorder sees where the value came from. The Go port
-            // unites a genable peer-only child with TOP unconditionally
-            // (go/mapval.go), and the difference was invisible until
-            // G4's identity merge brought a peer whose children the
-            // recorder counts as WRITTEN: `why $.b.k` on two positions
-            // of one entity named the site in Go and answered "nothing
-            // met here" in TypeScript.
             undefined === child
               ? (undefined !== peerctx.prov && peerchild.isGenable
                 ? unite(peerctx, peerchild, TOP, 'map-peer-only')
@@ -407,14 +302,6 @@ class MapVal extends BagVal {
             if ((oval as any)._spr !== spreadId(spread_cj)) {
               let key_spread_cj = spread_cj.spreadClone(peerctx)
 
-              // A SPREAD IS A SPREAD FROM EITHER SIDE. The own-key loop
-              // above marks its template so `why` can say the
-              // contribution came from `&:` rather than from the key;
-              // this arm did not, so the SAME document reported the
-              // role or dropped it depending on whether the template
-              // and the keys were written in one statement or two --
-              // `services: &: {..}` plus `services: {web:{}}` took the
-              // peer path and lost `(spread)` (use-cases/BUGS.md §55).
               if (undefined !== peerctx.prov) {
                 markSpread(key_spread_cj)
               }
@@ -457,13 +344,6 @@ class MapVal extends BagVal {
       }
     }
 
-    // console.log(
-    //   'MAPVAL-OUT', out.canon,
-    //   '\n  SELF', this,
-    //   '\n  PEER', peer,
-    //   '\n  OUT', out,
-    //   '\n  FROM', (out as any).spread.cj
-    // )
 
     ctx.explain && explainClose(te, out)
 
@@ -471,20 +351,6 @@ class MapVal extends BagVal {
   }
 
 
-  // Spread clone: return a Val usable as the per-key spread constraint.
-  //
-  // Three tiers:
-  //   1. tree is path-independent (no RefVal/KeyFuncVal/PathFuncVal/
-  //      MoveFuncVal/SuperFuncVal anywhere below): return `this` directly.
-  //      Nothing in the unify path mutates the spread root, and no
-  //      child depends on its own stored .path, so sharing is safe.
-  //   2. top-level children are all ScalarKindVal: shallow clone
-  //      (share children, fresh MapVal wrapper).
-  //   3. otherwise: full deep clone via `this.clone(ctx)`.
-  //
-  // Tier 1 handles the foo-sdk common case of simple type-constraint
-  // spreads like `&:{active: *true | boolean, version: *'0.0.1' | string}`,
-  // which are cloned thousands of times per run.
   spreadClone(ctx: AontuContext): Val {
     if (!this.isPathDependent) return this
 
@@ -531,7 +397,6 @@ class MapVal extends BagVal {
     for (let entry of Object.entries(this.peg)) {
       out.peg[entry[0]] =
         (entry[1] as any)?.isVal ?
-          // (entry[1] as Val).clone(ctx, spec?.mark ? { mark: spec.mark } : {}) :
           (entry[1] as Val).clone(ctx, {
             mark: spec?.mark ?? {},
             path: [...out.path, entry[0]],
@@ -551,23 +416,12 @@ class MapVal extends BagVal {
     out.optionalKeys = [...this.optionalKeys]
     out.aliasKeys = [...this.aliasKeys]
 
-    // out.from = this.from
 
-    // console.log('MAPVAL-CLONE', this.canon, '->', out.canon)
     return out
   }
 
 
   get canon() {
-    // Keys are emitted in CODE POINT order so the canonical form is
-    // independent of insertion/unification order and matches the Go
-    // port. A bare .sort() is UTF-16 code-unit order, which puts an
-    // astral key ahead of everything in U+E000-U+FFFF -- see cmpCodePoint.
-    // An alias declaration is not part of the document, so canon does
-    // not render it: a document with aliases and the document with
-    // every alias written out longhand must produce the same text and
-    // therefore the same `aon1-` hash. That is the sharpest statement
-    // of what an alias IS -- a name for a value, and nothing more.
     let keys = Object.keys(this.peg)
       .filter(k => !this.aliasKeys.includes(k))
       .sort(cmpCodePoint)
@@ -583,11 +437,6 @@ class MapVal extends BagVal {
           JSON.stringify(k) +
           (this.optionalKeys.includes(k) ? '?' : '') +
           ':' +
-          // canonRiders, not .canon: a deprecated field renders
-          // back as its `deprecate(x, m)` call, reparseably (G3). The
-          // guard is the isVal FLAG, never the canon getter: computing
-          // canon in the guard and again in the render doubles the
-          // recursion per level, which is 2^depth on a nested document.
           (true === this.peg[k]?.isVal
             ? canonRiders(this.peg[k]) : this.peg[k])
         ])

package/src/val/MatchFuncVal.ts

@@ -1,37 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// GENERATION: `match(v, p1, r1, p2, r2, …, d?)` (G8 phase 2,
-// docs/capability-review/g8-generation.md). A BOUNDED conditional:
-// alternating pattern/result arguments and an optional trailing
-// default. The first pattern IN ARGUMENT ORDER that `v` unifies with
-// SELECTS its result, and the result is the answer.
-//
-// The design said the answer was `v & p & r` -- the scrutinee narrowed
-// by the arm rather than replaced by it. That cannot be what a match
-// is for: it makes every arm whose result is not already a `v` a
-// contradiction, and the design's own example
-// (`match($.tier, small, {cpu:1}, …)`, a string scrutinee and map
-// results) cannot be evaluated at all under it. A match MAPS a value
-// to another value; a document that wants the scrutinee kept can say
-// so, because the scrutinee is a value it can name.
-//
-//   size: match($.tier, small, {cpu:1}, large, {cpu:8}, {cpu:2})
-//
-// WHAT KEEPS IT FROM BECOMING A CONDITIONAL LANGUAGE. The scrutinee is
-// matched by UNIFIABILITY only: no boolean guards, no comparisons
-// beyond what the constraint atoms already are, no fallthrough (first
-// match wins, in a spec-pinned order), and no way to write a pattern
-// that is not an ordinary Aontu value. The whole form is total.
-//
-// NO MATCH AND NO DEFAULT IS AN ERROR, not an empty answer, and the
-// report names the patterns that were tried -- the admissible-
-// alternatives shape (G2's error contract). A default is how a
-// document says it meant to allow the rest.
-//
-// A RESULT IS NOT EVALUATED UNTIL IT IS SELECTED. Only the scrutinee
-// and the patterns are driven; an unselected result never runs, so a
-// broken arm nobody takes is not an error the document has to carry
-// (which multi-error collection, G2 phase 6, would otherwise report).
 
 import type {
   Val,
@@ -48,22 +16,6 @@ import { prefInnerPeg } from './PrefVal'
 import { FuncBaseVal, trialUnify } from './FuncBaseVal'
 
 
-// THE DEFAULTED-SCRUTINEE RULE (ADR-004, use-cases/BUGS.md §5). The
-// generation-effective view of a settled scrutinee: a preference — or
-// a disjunction carrying one — means "this value unless something
-// overrides it", and by resolve time the model has SETTLED (staging
-// rule), so nothing will. The value generation is about to emit is
-// therefore the value the patterns must be tested against. Testing
-// against the still-open preference instead let a pattern SELECT an
-// arm by overriding the default: `side_effect:*readonly|write|
-// destructive` beside `match(.side_effect, destructive, true, false)`
-// answered `true` while generating "readonly" next to it — a derived
-// value contradicting the very value it derives from, exit 0.
-// A pref-free scrutinee (open disjunction included) is untouched:
-// matching by unifiability is its documented meaning.
-// Exported for the multi-pref unit test (ADR-002, the subsumeNode
-// precedent): rankPrefs leaves a settled disjunct at most one pref, so
-// the min-rank scan below cannot be reached through a document.
 export function effectiveScrutinee(v: Val): Val {
   let out: any = v
   if (true === out?.isDisjunct && Array.isArray(out.peg)) {
@@ -71,10 +23,6 @@ export function effectiveScrutinee(v: Val): Val {
     if (0 === prefs.length) {
       return v
     }
-    // Generation picks the LOWEST rank (effectiveDefault in
-    // subsume.ts; `a:**1|*2` generates 2). rankPrefs leaves at most
-    // one pref standing in a settled disjunct, so the scan is
-    // defensive.
     out = prefs.reduce((a: any, b: any) => b.rank < a.rank ? b : a)
   }
   return prefInnerPeg(out)
@@ -84,9 +32,6 @@ export function effectiveScrutinee(v: Val): Val {
 class MatchFuncVal extends FuncBaseVal {
   isMatchFunc = true
 
-  // THE STAGING RULE (G8 phase 0). A scrutinee that is still being
-  // narrowed can match an EARLIER pattern than the one it will end up
-  // matching, and the arm a match takes is not a thing to guess at.
   staged = true
 
   constructor(
@@ -107,10 +52,6 @@ class MatchFuncVal extends FuncBaseVal {
   }
 
 
-  // The scrutinee is argument 0 and the patterns are the odd
-  // arguments; the results are the even ones after 0, and the last
-  // argument is a DEFAULT when the count is even. Written once, read
-  // by both the driver below and resolve.
   hasDefault() {
     return 0 === this.peg.length % 2
   }

package/src/val/MaybeFuncVal.ts

@@ -0,0 +1,86 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { unite } from '../unify'
+import { AbsentVal } from './AbsentVal'
+import { FuncBaseVal } from './FuncBaseVal'
+
+
+import {
+  top
+} from './top'
+
+
+class MaybeFuncVal extends FuncBaseVal {
+  isMaybeFunc = true
+
+  forgives = true
+
+  // A reference that has not resolved YET is not a reference to
+  // nothing (ADR-034).
+  staged = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+  funcname() {
+    return 'maybe'
+  }
+
+
+  // Null so the base drives nothing: it would drive on the CALLER's
+  // context, where NilVal.make records the miss before resolve runs.
+  prepare(_ctx: AontuContext, _args: Val[]) {
+    return null
+  }
+
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    if (!ctx.settle) {
+      return this.residuate(peer, ctx)
+    }
+
+    return super.unify(peer, ctx)
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    // Cloned rather than swapped and restored, which is the
+    // own-property hazard trialUnify documents at length.
+    const sink: Val[] = []
+    const actx = ctx.clone({ err: sink, collect: true })
+    const out = unite(actx, args[0], top(), 'maybe')
+
+    // ONLY a missing referent. A conflict inside the argument stays
+    // the document's error.
+    if (out.isNil && 'reference' === (out as any).class) {
+      return this.place(new AbsentVal({}, ctx))
+    }
+
+    for (const err of sink) {
+      ctx.adderr(err as any)
+    }
+
+    return out
+  }
+
+} /* node:coverage ignore next 6 */
+
+
+export {
+  MaybeFuncVal,
+}