aontu 0.57.0 → 0.59.0

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,
@@ -34,9 +44,12 @@ type ValSpec = {
   // depth explicitly: `dup: true` makes FuncBaseVal, PrefVal and
   // OpBaseVal clone their inner Vals too, and the bag/junction clones
   // carry the flag down. Set by pack/each template instantiation,
-  // filter condition testing, and spread application (MapVal/
-  // ListVal.spreadClone) — never by the residuation or ref-resolution
-  // clones, whose sharing is pinned behaviour.
+  // filter condition testing, spread application (MapVal/
+  // ListVal.spreadClone), and REFERENCE RESOLUTION of a target that
+  // holds no staged call, whose copy is a per-destination instance
+  // too (ADR-025) — never by the residuation clone, whose sharing is
+  // pinned behaviour, and never by a copy of something still being
+  // settled at its own site, which is what keeps the ghost rows.
   dup?: boolean,
 
 
@@ -168,6 +181,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 +332,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
@@ -400,6 +443,33 @@ abstract class Val {
   }
 
 
+  // A STAGED CALL STANDING ANYWHERE IN THIS VALUE (the `staged` flag,
+  // G8 phase 0). Such a call has not decided: its arguments are still
+  // being driven AT ITS OWN SITE, so a REFERENCE's copy shares it
+  // rather than owning a set of arguments it would drive at the
+  // referring position instead (RefVal.find, ADR-025). Not cached:
+  // unlike isPathDependent this is a fact about the value's current
+  // state, and the whole point is that it stops being true.
+  get holdsStaged(): boolean {
+    if (true === (this as any).staged) {
+      return true
+    }
+    const peg: any = this.peg
+    if (Array.isArray(peg)) {
+      for (let i = 0; i < peg.length; i++) {
+        if (true === peg[i]?.isVal && peg[i].holdsStaged) return true
+      }
+    }
+    else if (null != peg && 'object' === typeof peg) {
+      for (const k in peg) {
+        if (true === peg[k]?.isVal && peg[k].holdsStaged) return true
+      }
+    }
+    const spreadCj = (this as any).spread?.cj as Val | undefined
+    return true === spreadCj?.isVal && (spreadCj as any).holdsStaged
+  }
+
+
   // PUT A MINTED VALUE WHERE THIS ONE STANDS: the site travels, and so
   // does provenance, because the two answer one question. A narrowed
   // disjunction, a lifted kind, a resolved reference -- each is a
@@ -670,10 +740,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,
+}