aontu 0.56.0 → 0.58.0

package/src/val/FilterFuncVal.ts

@@ -46,6 +46,10 @@ import { ListVal } from './ListVal'
 import { FuncBaseVal, trialUnify } from './FuncBaseVal'
 import { repathInstance } from './Val'
 import { fillPlace } from './PlaceVal'
+import { bagMembers } from './members'
+
+
+type Member = { key: string, val: Val }
 
 
 class FilterFuncVal extends FuncBaseVal {
@@ -83,9 +87,7 @@ class FilterFuncVal extends FuncBaseVal {
 
 
   unify(peer: Val, ctx: AontuContext): Val {
-    const ready = this.driveStagedArgs(ctx, 1)
-
-    if (!ready || !ctx.settle) {
+    if (!this.stagedReady(peer, ctx, 1)) {
       return this.residuate(peer, ctx)
     }
 
@@ -117,12 +119,15 @@ class FilterFuncVal extends FuncBaseVal {
       return undefined !== met && met.canon === child.canon
     }
 
+    // The candidates are the bag's MEMBERS -- what generation would
+    // emit (./members.ts, BUGS.md §79) -- so a hidden child is never
+    // selected into the result.
     if (true === data?.isMap) {
       const peg: Record<string, Val> = {}
-      for (const key of Object.keys(data.peg)) {
+      for (const { key, val } of bagMembers(data, ctx) as Member[]) {
         const kctx = ctx.descend(key)
-        if (keeps(data.peg[key], kctx)) {
-          peg[key] = data.peg[key].clone(kctx)
+        if (keeps(val, kctx)) {
+          peg[key] = val.clone(kctx)
         }
       }
       return new MapVal({ peg }, ctx)
@@ -130,7 +135,7 @@ class FilterFuncVal extends FuncBaseVal {
 
     if (true === data?.isList) {
       const peg: Val[] = []
-      for (const el of data.peg as Val[]) {
+      for (const { val: el } of bagMembers(data, ctx) as Member[]) {
         // The element context is the position it will END UP at, which
         // is its index in the RESULT: dropping the third of five moves
         // the fourth up, and a kept element must be pathed where it

package/src/val/FormFuncVal.ts

@@ -0,0 +1,119 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// TRANSFORMATION: `form(data, tmpl)` (G9 §4; docs/design/RENDER.0.md
+// D11 and P6). One element of the result list per child of `data`,
+// being `tmpl` instantiated at that position with `_` bound to the
+// source child. It REPLACES; it does not meet.
+//
+//   names: [web, auth]
+//   units: form($.names, {path: _ + ".ts"})  ->  [{path: "web.ts"}, {path: "auth.ts"}]
+//
+// WHY BESIDE `each`. `each($.ports, integer)` is a schema statement
+// and is monotone -- more information about the template narrows the
+// children -- so it is a lattice citizen, and a constructor is not.
+// The language draws this line twice already: `min`/`max` (bounds)
+// against `least`/`greatest` (aggregates), and `filter` (select by
+// unifiability) against `match` (choose a result). `each` is the
+// bound; `form` is the construction. `each` also carries the source
+// child's identity (its clone keeps the entity), where `form`'s
+// element IS the template.
+//
+// WHY IT EXISTS AT ALL: ORDER. `pick(pack(d, {f: t}), f)` maps too,
+// but it goes through a map and re-sorts to code-point order, and it
+// refuses a list of records outright (pack_key). A struct's fields, a
+// DDL's columns and a file's imports are lists whose order is the
+// model's, and silently alphabetising them is wrong output. `form`
+// reads its members through the one ordering helper `each` uses
+// (members.ts), so the two can never disagree about order -- source
+// order for a list, sorted-key order for a map -- and skips what
+// generation would not emit: a hidden child, an unfilled optional.
+//
+// It joins `boundArgStart` (PlaceVal.ts): a `_` inside its template
+// is ITS hole to bind, never an outer generator's. Forgetting that is
+// BUGS.md §34's silent failure -- every existing test passes and the
+// new combinator captures an outer generator's hole -- which is why
+// the shared spec's nesting rows exist.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+import { ListVal } from './ListVal'
+import { FuncBaseVal } from './FuncBaseVal'
+import { repathInstance } from './Val'
+import { fillPlace } from './PlaceVal'
+import { memberVals } from './members'
+
+
+class FormFuncVal extends FuncBaseVal {
+  isFormFunc = true
+
+  // THE STAGING RULE, for the reason given in PackFuncVal: the data
+  // is not settled merely by being `done` once.
+  staged = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+  funcname() {
+    return 'form'
+  }
+
+
+  // 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).
+    if (!this.stagedReady(peer, ctx, 1)) {
+      return this.residuate(peer, ctx)
+    }
+
+    return super.unify(peer, ctx)
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const vals = memberVals(args?.[0], ctx)
+    if (undefined === vals) {
+      return makeNilErr(ctx, 'form_data', this)
+    }
+
+    // Arity is checked at parse (funcArity), so the template is here.
+    const tmpl: Val = args[1]
+    const peg: Val[] = []
+
+    for (let i = 0; i < vals.length; i++) {
+      const elctx = ctx.descend(String(i))
+      // A FULL INSTANCE per element, to the leaves (`dup`, ADR-005),
+      // at the element's own position -- see PackFuncVal.resolve --
+      // with `_` bound to the source child and NOTHING met into it.
+      const inst = tmpl.clone(elctx, { dup: true })
+      repathInstance(inst, inst.path)
+      peg.push(fillPlace(inst, vals[i], elctx))
+    }
+
+    return new ListVal({ peg }, ctx)
+  }
+
+} /* node:coverage ignore next 6 */
+
+
+export {
+  FormFuncVal,
+}

package/src/val/FuncBaseVal.ts

@@ -139,6 +139,24 @@ class FuncBaseVal extends FeatureVal {
   }
 
 
+  // THE STAGED READINESS GATE, stated once for the generators that
+  // drive their own data argument. Such a func fires when the model
+  // has settled AND that argument is done -- EXCEPT when the argument
+  // is a HOLE and a PEER has arrived to fill it. `_` is never done: it
+  // is FILLED, and the peer is what fills it, so gating on doneness
+  // alone held every placeheld generator residual for ever and the
+  // fill in `unify` below was never reached (`["a"] & pack(_, {x:1})`
+  // was `*_no_gen`, while the unstaged `"hello" & upper(_)` filled as
+  // documented -- an undriven `_` makes an ordinary call's `pegdone`
+  // false, and a generator's prepare() forces it true). Against TOP
+  // there is nothing to fill with, so a placeheld generator waits
+  // exactly as the hole itself does.
+  stagedReady(peer: Val, ctx: AontuContext, count: number): boolean {
+    const ready = this.driveStagedArgs(ctx, count)
+    return (ready || (!peer.isTop && hasPlace(this))) && true === ctx.settle
+  }
+
+
   // THE PER-DESTINATION INSTANTIATION RULE (ADR-005). The default
   // clone shares the argument array AND the argument Vals — pinned
   // sharing for the move()/copy() ghost artifacts (test/spec/func.tsv,

package/src/val/MapVal.ts

@@ -46,7 +46,7 @@ import { markSpread } from '../provenance'
 // 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.canon + '~' + cj.site.row + ':' + cj.site.col
+  return cj.spelling + '~' + cj.site.row + ':' + cj.site.col
 }
 
 // Snapshot a path-dependent ref spread to its structural target once,
@@ -605,5 +605,6 @@ class MapVal extends BagVal {
 
 
 export {
-  MapVal
+  MapVal,
+  spreadSnapKey,
 }

package/src/val/PackFuncVal.ts

@@ -44,35 +44,39 @@ import { MapVal } from './MapVal'
 import { FuncBaseVal } from './FuncBaseVal'
 import { repathInstance } from './Val'
 import { fillPlace } from './PlaceVal'
+import { bagMembers } from './members'
 
 
 // The keys a data bag names, in the order the result must carry them,
 // or a code naming what is wrong with it. Shared with `each`, which
 // asks the same question of the same argument and answers it with the
 // values rather than the keys.
-function dataKeys(data: Val | undefined): string[] | string {
-  const d: any = data
+function dataKeys(data: Val | undefined, ctx: AontuContext): string[] | string {
+  // The candidates are the bag's MEMBERS -- what generation would
+  // emit (./members.ts, BUGS.md §79) -- so a hidden key, or a hidden
+  // name in a list of names, packs nothing.
+  const members = bagMembers(data, ctx)
+
+  if (undefined === members) {
+    return 'pack_data'
+  }
 
-  if (true === d?.isMap) {
-    return Object.keys(d.peg)
+  if (true === (data as any).isMap) {
+    return members.map((m) => m.key)
   }
 
-  if (true === d?.isList) {
-    const out: string[] = []
-    for (const el of d.peg as Val[]) {
-      const e: any = el
-      // A key is a NAME, and only a string is one. A number would
-      // key by position under another spelling, which is the failure
-      // mode the data-keyed rule exists to refuse.
-      if (true !== e?.isScalar || 'string' !== typeof e.peg) {
-        return 'pack_key'
-      }
-      out.push(e.peg)
+  const out: string[] = []
+  for (const { val } of members) {
+    const e: any = val
+    // A key is a NAME, and only a string is one. A number would
+    // key by position under another spelling, which is the failure
+    // mode the data-keyed rule exists to refuse.
+    if (true !== e?.isScalar || 'string' !== typeof e.peg) {
+      return 'pack_key'
     }
-    return out
+    out.push(e.peg)
   }
-
-  return 'pack_data'
+  return out
 }
 
 
@@ -114,9 +118,7 @@ class PackFuncVal extends FuncBaseVal {
     // 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) {
+    if (!this.stagedReady(peer, ctx, 1)) {
       return this.residuate(peer, ctx)
     }
 
@@ -125,7 +127,7 @@ class PackFuncVal extends FuncBaseVal {
 
 
   resolve(ctx: AontuContext, args: Val[]) {
-    const keys = dataKeys(args?.[0])
+    const keys = dataKeys(args?.[0], ctx)
     if ('string' === typeof keys) {
       return makeNilErr(ctx, keys, this)
     }

package/src/val/PlaceVal.ts

@@ -73,10 +73,10 @@ class PlaceVal extends ValBase {
 
 
 // A HOLE BELONGS TO ITS NEAREST ENCLOSING GENERATOR. A `_` inside a
-// generator's template (pack/each, arg 1) or condition (filter, arg 1)
-// is that generator's to bind — "_ is the source child" — so neither
-// the hole test nor the fill walk may cross into those arguments from
-// outside. Before this boundary, `close(pack(d, _ & t))` reported a
+// generator's template (pack/each, arg 1), condition (filter, arg 1)
+// or rule table (emit, arg 1) is that generator's to bind — "_ is the
+// source child" — so neither the hole test nor the fill walk may cross
+// into those arguments from outside. Before this boundary, `close(pack(d, _ & t))` reported a
 // hole to the OUTER call, so an ordinary overlay statement was
 // absorbed into the template instead of merging with the generated
 // child (use-cases/BUGS.md §10), and an outer pack's fill pass
@@ -85,7 +85,8 @@ class PlaceVal extends ValBase {
 // so it stays visible: a hole there is an outer hole as before.
 function boundArgStart(v: any): number {
   return true === v.isPackFunc || true === v.isEachFunc ||
-    true === v.isFilterFunc ? 1 : Infinity
+    true === v.isFilterFunc || true === v.isEmitFunc ||
+    true === v.isFormFunc ? 1 : Infinity
 }
 
 
@@ -183,10 +184,12 @@ function rebuild(v: Val, peg: any, ctx: AontuContext): Val {
   out.peg = peg
   out.dc = 0
   return out
-} /* node:coverage ignore next 8 */
+} /* node:coverage ignore next 10 */
 
 
 export {
+  boundArgStart,
+  rebuild,
   hasPlace,
   fillPlace,
   PlaceVal,

package/src/val/RefVal.ts

@@ -73,12 +73,40 @@ function pendingMarkWrapper(v: any): boolean {
 }
 
 
+// The child a term of the walk can supply for one path segment, or
+// undefined when it has none. A map or a list answers from its own
+// members; a PENDING type()/hide() answers from its argument's, because
+// the wrapper only marks and its argument is the structure the path
+// names (see the call sites in `find`).
+function markedChild(v: any, part: any): Val | undefined {
+  if (true === v?.isMap || true === v?.isList) {
+    return v.peg[part]
+  }
+  if (true === v?.isFunc
+    && (true === v.isHideFunc || true === v.isTypeFunc)
+    && (true === v.peg?.[0]?.isMap || true === v.peg?.[0]?.isList)) {
+    return v.peg[0].peg[part]
+  }
+  return undefined
+}
+
+
+// An alias name, whole: the sigil and an identifier (the lexer's
+// ALIAS_RE, anchored at both ends, for the canon spelling above).
+const ALIAS_NAME_RE = /^%[A-Za-z_][A-Za-z0-9_]*$/
+
+
 class RefVal extends FeatureVal {
   isRef = true
   isGenable = true
   cjo = 32500
 
   absolute: boolean = false
+
+  // The value an alias reference canons as, attached by expandAliases
+  // after unification (see `canon` below). Not a ValSpec field: it is
+  // a rendering of the settled tree, never a parse-time property.
+  expansion: Val | undefined = undefined
   prefix: boolean = false
 
   constructor(
@@ -220,7 +248,8 @@ class RefVal extends FeatureVal {
         }
 
         // same path
-        else if (this.canon === peer.canon) {
+        else if (this.spelling ===
+          (true === (peer as any).isRef ? (peer as any).spelling : peer.canon)) {
           out = this
         }
 
@@ -406,6 +435,45 @@ class RefVal extends FeatureVal {
               || true === (node as any).peg?.[0]?.isList)) {
             node = (node as any).peg[0].peg[part]
           }
+
+          // AND SO IS A CONJUNCT THAT STILL CARRIES ONE (issue #164).
+          // Two statements for one key meet, so a key written as
+          // `T: type({...})` twice is a CONJUNCT of two wrappers -- and
+          // one written once beside a plain `T: {...}` is a conjunct
+          // too. The arm above sees a wrapper only when it is the whole
+          // node, so a reference into such a key walked into the
+          // conjunct and stopped: the wrapper waited for its argument,
+          // the argument waited for the reference, and neither moved.
+          // The first referring child of every consumer stayed
+          // unresolved and generation reported mapval_no_gen at a path
+          // that names none of this, which is how a five-file schema
+          // spent its evening being bisected.
+          //
+          // The answer at a segment is the MEET of what each term
+          // supplies, so terms that have no such member are skipped and
+          // the rest are conjoined -- one term answers as itself, and
+          // the ordinary map arm answers once the fold has happened.
+          // Restricted to a conjunct that still holds a pending
+          // wrapper: every other conjunct folds on its own, and this
+          // walk exists only to break the wrapper's deadlock.
+          else if (true === (node as any).isConjunct
+            && Array.isArray((node as any).peg)
+            && pendingMarkWrapper(node)) {
+            const kids: Val[] = []
+            for (const term of (node as any).peg) {
+              const kid = markedChild(term, part)
+              if (undefined !== kid && null !== kid) {
+                kids.push(kid)
+              }
+            }
+            // No term has it YET. Not a miss: the conjunct is still
+            // folding, and the member may arrive with the fold.
+            if (0 === kids.length) {
+              break
+            }
+            node = 1 === kids.length ?
+              kids[0] : new ConjunctVal({ peg: kids }, ctx)
+          }
           else if (node.done) {
             nopath = true
             break;
@@ -464,6 +532,31 @@ class RefVal extends FeatureVal {
       else if (pI === refpath.length) {
         out = node
 
+        // THE READ IS RECORDED, AND THE VALUE STAMPED WITH WHERE IT
+        // WAS FOUND (RENDER.0.md P7). A resolved reference clones its
+        // target into the referring position, so without the stamp a
+        // value that arrived by reference knows only where it came to
+        // rest -- and `render --coverage` has nothing to measure the
+        // model against. Off unless the run is instrumented; the first
+        // address wins, and every reference to one node names the same
+        // address anyway.
+        if (undefined !== ctx.reads && null != node) {
+          // The root's own address is `$`, as the coverage walk spells
+          // it: a dot with nothing after it would match no path there.
+          const addr = '$' + refpath.map((seg: string) => '.' + seg).join('')
+          // AN ALIAS IS NOT A PATH. `%wire` names a value the document
+          // holds unevaluated and the tree never carries, so it is an
+          // address a rule can be reported AT and never a path coverage
+          // could call dead: it is stamped, and it is not in the set
+          // the model is measured against.
+          if (!refpath[0]?.startsWith('%')) {
+            ctx.reads.add(addr)
+          }
+          if (null == (node as any).origin) {
+            ; (node as any).origin = addr
+          }
+        }
+
         // A reference landing on another reference -- or on a FUNCTION,
         // whose arguments the chase now follows (issue #35) -- may be a
         // PROVEN mutual cycle (a: $.b, b: $.a; a: $.b, b: upper($.a)).
@@ -544,21 +637,38 @@ class RefVal extends FeatureVal {
 
           // console.log('FOUND-B', out)
 
+          // A REFERENCE LIFTS: the copy is concrete, its type and hide
+          // marks cleared to the leaves -- a marked target is what the
+          // author hid or typed, and a reference to it is the author
+          // asking for it in the open. EXCEPT the snapshot a staged
+          // verb takes of its data (`argsnap`: each, emit, filter,
+          // pack, pick, join, the aggregates), when the target itself
+          // is not marked: a member marked inside an unmarked bag was
+          // hidden IN ITS OWN RIGHT, and the verb's enumeration
+          // (ts/src/val/members.ts, BUGS.md §79) needs to see that
+          // mark to leave the member out, as generation does. A marked
+          // target lifts even there, or `each($.schema.entities, _)`
+          // under `schema: hide({...})` would see every entity as
+          // hidden, since hide() marks to the leaves.
+          const lifted = true !== (ctx as any).argsnap
+            || true === out.mark.type || true === out.mark.hide
+
           out = out.clone(ctx)
 
-          // if (this.mark.type || this.mark.hide) {
-          walk(out, (_key: string | number | undefined, val: Val) => {
-            val.mark.type = false
-            val.mark.hide = false
-            // THE LINK IS NOT CLEARED (G4 phase 3): a link says what a
-            // value POINTS AT, and a copy of a link points at the same
-            // thing. An ABSOLUTE address still names the same node from
-            // the copy; a RELATIVE one is read from the copy's own
-            // position, which is what makes a referenced model resolve
-            // its internal links inside the copy (ADR-014).
-            return val
-          })
-          //}
+          if (lifted) {
+            walk(out, (_key: string | number | undefined, val: Val) => {
+              val.mark.type = false
+              val.mark.hide = false
+              // THE LINK IS NOT CLEARED (G4 phase 3): a link says what
+              // a value POINTS AT, and a copy of a link points at the
+              // same thing. An ABSOLUTE address still names the same
+              // node from the copy; a RELATIVE one is read from the
+              // copy's own position, which is what makes a referenced
+              // model resolve its internal links inside the copy
+              // (ADR-014).
+              return val
+            })
+          }
 
           // onsole.log('FOUND-C', out)
         }
@@ -694,19 +804,58 @@ class RefVal extends FeatureVal {
       absolute: this.absolute,
       ...(spec || {})
     }) as RefVal)
+    out.expansion = this.expansion
     return out
   }
 
 
-  get canon() {
-    let str =
-      (this.absolute ? '$' : '') +
+  // THE NAME OF THE ALIAS THIS REFERENCE NAMES, or undefined for a
+  // path reference. `%u` is spelled internally as the root reference
+  // `$.%u` (docs/design/ALIASES.0.md: the name is a path into the
+  // declaration), so an alias reference is an absolute reference of
+  // one segment that is an alias name.
+  get aliasName(): string | undefined {
+    return this.absolute && 1 === this.peg.length &&
+      'string' === typeof this.peg[0] && ALIAS_NAME_RE.test(this.peg[0]) ?
+      this.peg[0] : undefined
+  }
+
+
+  // THE REFERENCE'S OWN SPELLING: the alias name, or the path. This is
+  // the reference's identity (the snapshot key of a ref spread, the
+  // same-path test in unify), which `canon` below is not once an
+  // expansion is attached.
+  get spelling(): string {
+    const name = this.aliasName
+    if (undefined !== name) {
+      return name
+    }
+    return (this.absolute ? '$' : '') +
       (0 < this.peg.length ? '.' : '') +
       // this.peg.join(this.sep)
       this.peg.map((p: any) => '.' === p ? '' :
         (p.isVal ? p.canon : '' + p))
         .join('.')
-    return str
+  }
+
+
+  get canon() {
+    // AN ALIAS REFERENCE CANONS AS THE VALUE IT NAMES. A reference left
+    // standing after unification is one inside a spread template
+    // (`[&: %u]`, `{&: {a: %u}}`): the template applies to children
+    // that have not arrived, so it is not resolved in place. Canon
+    // erases the declaration (an alias is a name for a value, and
+    // nothing more -- ALIASES.0.md §4), so the name alone would not
+    // reparse, and the hash of `t: {&: %u}` would differ from the hash
+    // of `t: {&: integer}`, which is the same document. The expansion
+    // is attached by expandAliases (ts/src/alias.ts) once the tree has
+    // settled; without one -- a parse-only tree, an unresolved name, or
+    // the KNOT of a recursive alias inside its own template -- the
+    // reference spells its name. Twin of RefVal.Canon in go/ref.go.
+    if (undefined !== this.expansion) {
+      return this.expansion.canon
+    }
+    return this.spelling
   }