aontu 0.57.0 → 0.59.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/FuncBaseVal.ts

@@ -46,6 +46,13 @@ import { hasPlace, fillPlace } from '../val/PlaceVal'
 function trialUnify(ctx: AontuContext, a: Val, b: Val): Val | undefined {
   const savedErr = ctx.err
   const savedTrial = ctx._trialMode
+  // Restored by DELETION where they were inherited, for the reason
+  // DisjunctVal.unify's own sandbox gives at length: contexts are
+  // Object.create(parent) and cached per (parent, key), so writing
+  // these back leaves own properties that shadow the ancestor and make
+  // a later trial invisible to the value running inside it.
+  const ownErr = Object.prototype.hasOwnProperty.call(ctx, 'err')
+  const ownTrial = Object.prototype.hasOwnProperty.call(ctx, '_trialMode')
   const trialErr: any[] = []
 
   ctx.err = trialErr
@@ -56,8 +63,18 @@ function trialUnify(ctx: AontuContext, a: Val, b: Val): Val | undefined {
     out = unite(ctx, a, b, 'trial')
   }
   finally {
-    ctx.err = savedErr
-    ctx._trialMode = savedTrial
+    if (ownErr) {
+      ctx.err = savedErr
+    }
+    else {
+      delete (ctx as any).err
+    }
+    if (ownTrial) {
+      ctx._trialMode = savedTrial
+    }
+    else {
+      delete (ctx as any)._trialMode
+    }
   }
 
   return 0 < trialErr.length || out.isNil ? undefined : out
@@ -158,22 +175,28 @@ class FuncBaseVal extends FeatureVal {
 
 
   // 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,
-  // ghost-*-innard-canon) — but a clone that is a template INSTANCE
-  // must own the full inner structure: with the args shared,
-  // `pack($.names, close({name: key()}))` resolved key() once inside
-  // the one shared inner map and stamped the FIRST child's key on
-  // every child (use-cases/BUGS.md §8). The `dup` spec flag asks for
-  // that depth; everything else keeps the sharing it has always had.
+  // clone shares the argument array AND the argument Vals — the
+  // residuation clone, which stays at one position and wants the
+  // sharing, and the reference copy of a target that still holds a
+  // staged call, which pins the move()/copy() ghost artifacts
+  // (test/spec/func.tsv, ghost-*-innard-canon; ADR-025) — but a clone
+  // that is an INSTANCE must own the full inner structure: with the
+  // args shared, `pack($.names, close({name: key()}))` resolved key()
+  // once inside the one shared inner map and stamped the FIRST
+  // child's key on every child (use-cases/BUGS.md §8). The `dup` spec
+  // flag asks for that depth; everything else keeps the sharing it
+  // has always had.
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     const out = super.clone(ctx, spec) as FuncBaseVal
     if (true === spec?.dup && Array.isArray(this.peg)) {
       // Every argument is a Val by construction (the parser builds
       // them; make() rebuilds from driven Vals), as the Go twin's
-      // []Val typing states outright. The instantiation sites then
-      // normalise every path in the clone (repathInstance), so the
-      // argument-shaped parse paths never leak into an instance.
+      // []Val typing states outright. The generator and spread
+      // instantiation sites then normalise every path in the clone
+      // (repathInstance), so the argument-shaped parse paths never
+      // leak into an instance; the reference copy takes the paths
+      // this rebasing gives, which is what an absolute address in a
+      // copied model already expects (ADR-014).
       out.peg = this.peg.map((a: Val) => a.clone(ctx, { dup: true }))
     }
     return out

package/src/val/ListVal.ts

@@ -335,7 +335,15 @@ class ListVal extends BagVal {
       { mark: spec?.mark, dup: spec?.dup } : {}
     for (let entry of Object.entries(this.peg)) {
       out.peg[entry[0]] =
-        (entry[1] as any)?.isVal ? (entry[1] as Val).clone(ctx, childspec) : entry[1]
+        (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]
     }
     if (this.spread.cj) {
       out.spread.cj = this.spread.cj.clone(ctx, childspec)

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
 }
 
 
@@ -132,7 +133,11 @@ function hasPlace(v: Val): boolean {
 // generator's to fill with its OWN source children when it fires.
 function fillPlace(v: Val, fill: Val, ctx: AontuContext): Val {
   if (true === (v as any).isPlace) {
-    return fill
+    // A FILL IS A POSITION. The hole knows where it sits in the
+    // instance; the datum arriving in it does not, and inserted as it
+    // stands it keeps the paths it had at its SOURCE, so every finding
+    // under it names a path that does not exist.
+    return fill.clone(ctx, { path: [...(v as any).path] })
   }
 
   const peg: any = (v as any).peg

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,62 @@ class RefVal extends FeatureVal {
 
           // console.log('FOUND-B', out)
 
-          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
-          })
-          //}
+          // 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
+
+          // A REFERENCE'S COPY OWNS ITS ARGUMENTS (ADR-025). The copy
+          // is a per-destination instance exactly as a spread's or a
+          // generator's is, so ADR-005's rule holds here too: nothing
+          // path-dependent may be shared between two destinations, or
+          // the first destination's resolution answers for them all.
+          // The shallow clone shared a call's ARGUMENTS -- so
+          // `items: [&: $.entities.User]` over a `close({...})` target
+          // gave every element the one inner map, whose path each
+          // element rebased in turn, and the constraint that failed at
+          // element 2 reported element 0's path (use-cases GAP 8).
+          //
+          // A STAGED CALL IS THE EXCEPTION, because it has not decided
+          // yet. Its arguments are still being driven AT ITS OWN SITE
+          // (the staging rule, G8 phase 0), and a copy that owned them
+          // would drive its own set at the referring position instead:
+          // the relative `.side_effect` in a `match()` would read the
+          // referring field's siblings (use-cases/09-agent-tools), and
+          // an alias naming an `emit` rule table -- a template, which
+          // is exactly a value copied before it resolves -- would read
+          // its recursive `%w` as a self-reference. A staged call
+          // ANYWHERE in the target counts: what is referenced is
+          // usually the conjunct the call sits in, not the call.
+          // The copy shares what the source is still settling, and
+          // owns the rest.
+          out = out.clone(ctx, { dup: !out.holdsStaged })
+
+          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 +828,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
   }