aontu 0.57.0 → 0.58.0

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/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
 }
 
 
@@ -123,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

@@ -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 || true === v.isEmitFunc ? 1 : Infinity
+    true === v.isFilterFunc || true === v.isEmitFunc ||
+    true === v.isFormFunc ? 1 : Infinity
 }
 
 

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
   }
 
 

package/src/val/Val.ts

@@ -11,6 +11,16 @@ import {
 import { INNER_OF, WRITTEN } from '../provenance'
 
 
+// THE DISPATCH RECORD (RENDER.0.md D11, P7): the address of the node
+// a rule matched, and the address of the rule that matched it -- the
+// table's own address and the rule's index in it, joined by `#`,
+// which no path holds.
+type EmitOrigin = {
+  node: string,
+  rule: string,
+}
+
+
 type ValMark = {
   type: boolean,
   hide: boolean,
@@ -168,6 +178,24 @@ abstract class Val {
   // and the edge set (ts/src/graph.ts) is exactly the set of these.
   link?: string
 
+  // THE READ ADDRESS (RENDER.0.md P7): the tree path a reference
+  // resolved this value AT, stamped where it was found. A resolved
+  // reference CLONES its target into the referring position, so a
+  // value that arrived by reference otherwise knows only where it came
+  // to rest -- and a trace saying a line came from `$.code.units.0`
+  // names the output, not the model. Written only by an instrumented
+  // run (AontuContext.reads), carried by clone and by the meet rider,
+  // exactly as the deprecation record is.
+  origin?: string
+
+  // THE DISPATCH THAT PRODUCED THIS PIECE (RENDER.0.md D11, P7): the
+  // node an `emit` matched and the rule it took, stamped on every
+  // piece the dispatch instantiated. The INNERMOST dispatch wins: a
+  // nested rule set splices its pieces into the outer result, and the
+  // rule that wrote a line is the one that wrote it. Written only by
+  // an instrumented run, and carried like `origin`.
+  emitted?: EmitOrigin
+
   // The GRAPH of an evaluated document (G4 phase 3): the edge set,
   // stamped on the result by Aontu.unify the way the include manifest
   // is. Absent on every Val that is not a unify result.
@@ -301,6 +329,18 @@ abstract class Val {
       out.deprecation = this.deprecation
     }
 
+    // THE RENDER RIDERS TRAVEL WITH THE CLONE (P7), for the reason the
+    // deprecation record does: a clone of a value read at `$.schema`
+    // was read at `$.schema`, and a clone of an emitted piece is still
+    // that dispatch's. Both are absent unless the run is instrumented,
+    // so this is two undefined reads otherwise.
+    if (null != this.origin) {
+      out.origin = this.origin
+    }
+    if (null != this.emitted) {
+      out.emitted = this.emitted
+    }
+
     // THE APPLY-ONCE MARK TRAVELS WITH THE CLONE. `_spr` records which
     // spread template has already been merged into this value, and the
     // bag loops read it to keep a template from being applied twice
@@ -670,10 +710,11 @@ function empty(o: any) {
     || (null != o && 'object' === typeof o && 0 === Object.keys(o).length)
     || false
   )
-} /* node:coverage ignore next 17 */
+} /* node:coverage ignore next 18 */
 
 
 export type {
+  EmitOrigin,
   ValMark,
   ValSpec,
 }

package/src/val/members.ts

@@ -0,0 +1,86 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+
+// THE MEMBERS OF A BAG, as every fold and every generator over a bag
+// sees them (use-cases/BUGS.md §79; G9 phase 0 item 4). A member is a
+// child that generation would EMIT: a hide()- or type()-marked child
+// is not one, an alias declaration is not one, and an optional key
+// whose value generates nothing -- an unfilled `y?: string`, an absent
+// optional subtree -- is not one. `each`, `emit`, `filter`, `pick`,
+// `join` and the aggregates read a bag through this one function, so a
+// value the document withholds from its output is withheld from every
+// text and every total the document computes from it: a hidden field
+// that reached generated source through `join` is the defect this
+// closes, and it was one behaviour in both ports because each verb
+// had its own enumeration and none of them asked the mark.
+//
+// Maps list their members in code-point key order (../keyorder.ts),
+// lists in index order -- the one order canon, generation and the Go
+// port agree on (BUGS.md §62). Twin of bagMembers in go/members.go.
+
+import type { Val } from '../type'
+import { AontuContext } from '../ctx'
+import { cmpCodePoint } from '../keyorder'
+import { empty } from './Val'
+import { bagGenable } from './BagVal'
+
+
+type Member = { key: string, val: Val }
+
+
+function bagMembers(data: any, ctx: AontuContext): Member[] | undefined {
+  if (true !== data?.isMap && true !== data?.isList) {
+    return undefined
+  }
+
+  const keys: string[] = true === data.isMap ?
+    Object.keys(data.peg).sort(cmpCodePoint) :
+    (data.peg as Val[]).map((_v: Val, i: number) => '' + i)
+
+  // A member marked while its bag is not was marked in its own right,
+  // and is left out as generation leaves it out. Under a MARKED bag
+  // every child carries the mark (hide() and type() mark to the
+  // leaves), so there the mark says nothing about the member and every
+  // child is one -- the members of a hidden bag are what the bag
+  // holds, exactly as a reference to it lifts them.
+  const lifted = true === data.mark.hide || true === data.mark.type
+
+  const out: Member[] = []
+  for (const key of keys) {
+    const val: any = data.peg[key]
+    if ((!lifted && (true === val.mark.hide || true === val.mark.type))
+      || data.aliasKeys.includes(key)) {
+      continue
+    }
+    if (data.optionalKeys.includes(key) && !filled(val, ctx)) {
+      continue
+    }
+    out.push({ key, val })
+  }
+  return out
+}
+
+
+// An optional child is a member when it generates something, decided
+// as BagVal.gen decides it: in an isolated collect context, so residue
+// inside an absent optional subtree is dropped rather than raised.
+function filled(val: any, ctx: AontuContext): boolean {
+  if (!bagGenable(val)) {
+    return false
+  }
+  const cval = val.gen(ctx.clone({ err: [], collect: true }))
+  return undefined !== cval && !empty(cval)
+}
+
+
+// The member values alone, for the verbs that do not need the keys.
+function memberVals(data: any, ctx: AontuContext): Val[] | undefined {
+  const members = bagMembers(data, ctx)
+  return undefined === members ? undefined : members.map((m) => m.val)
+} /* node:coverage ignore next 6 */
+
+
+export {
+  bagMembers,
+  memberVals,
+}