aontu 0.61.0 → 0.63.0

package/src/val/EachFuncVal.ts

@@ -1,26 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// GENERATION: `each(data, tmpl)` (G8 phase 1,
-// docs/capability-review/g8-generation.md). One element of the result
-// list per child of `data`, each of them that child met with `tmpl`.
-// Written with one argument, `each(m)` is a map's children as a list.
-//
-//   ports: {http: 80, https: 443}
-//   open: each($.ports, integer)   ->  [80, 443]
-//
-// ORDER IS FIXED, and fixed the way canon already fixes it: source
-// order for a list, sorted-key order for a map (`cmpCodePoint`, the
-// comparator `MapVal.canon` and the Go port's marshalling use). A
-// generated list whose order depended on insertion history would differ
-// between two runs of the same document, and between the two ports --
-// the one thing the shared spec exists to prevent.
-//
-// The element is the source child CLONED, not shared: it is a second
-// position holding that value, and a position is where path-dependent
-// content resolves. What the clone keeps is the identity, if the child
-// carries one (G4 phase 1) -- a listed entity is still that entity, and
-// the merge that follows is the point.
-
 import type {
   Val,
   ValSpec,
@@ -30,7 +9,6 @@ import {
   AontuContext,
 } from '../ctx'
 
-import { unite } from '../unify'
 import { makeNilErr } from '../err'
 import { ListVal } from './ListVal'
 import { FuncBaseVal } from './FuncBaseVal'
@@ -39,19 +17,11 @@ import { fillPlace } from './PlaceVal'
 import { memberVals } from './members'
 
 
-// The members a data bag holds, in the order the result must carry
-// them -- what generation would emit (./members.ts, BUGS.md §79) --
-// or the code naming what is wrong with the argument.
-function dataValues(data: Val | undefined, ctx: AontuContext): Val[] | string {
-  const vals = memberVals(data, ctx)
-  return undefined === vals ? 'each_data' : vals
-}
-
-
 class EachFuncVal extends FuncBaseVal {
   isEachFunc = true
 
-  // THE STAGING RULE, for the reason given in PackFuncVal.
+  // THE STAGING RULE, for the reason given in PackFuncVal: the data
+  // is not settled merely by being `done` once.
   staged = true
 
   constructor(
@@ -62,7 +32,6 @@ class EachFuncVal extends FuncBaseVal {
   }
 
 
-
   funcname() {
     return 'each'
   }
@@ -76,8 +45,7 @@ class EachFuncVal extends FuncBaseVal {
 
   unify(peer: Val, ctx: AontuContext): Val {
     // 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".
+    // prepare above).
     if (!this.stagedReady(peer, ctx, 1)) {
       return this.residuate(peer, ctx)
     }
@@ -87,37 +55,28 @@ class EachFuncVal extends FuncBaseVal {
 
 
   resolve(ctx: AontuContext, args: Val[]) {
-    const vals = dataValues(args?.[0], ctx)
-    if ('string' === typeof vals) {
-      return makeNilErr(ctx, vals, this)
+    const vals = memberVals(args?.[0], ctx)
+    if (undefined === vals) {
+      return makeNilErr(ctx, 'each_data', this)
     }
 
-    const tmpl: Val | undefined = args?.[1]
+    // 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))
-      const el = vals[i].clone(elctx)
-      // The template is CLONED per element, never shared — a FULL
-      // instance to the leaves (`dup`, ADR-005): see PackFuncVal.resolve.
-      // `_` inside the template binds the source child (G8 phase 3),
-      // which for `each` is the element itself.
-      let inst: Val | undefined = undefined
-      if (undefined !== tmpl) {
-        inst = tmpl.clone(elctx, { dup: true })
-        repathInstance(inst, inst.path)
-      }
-      peg.push(undefined === inst ? el :
-        unite(elctx, el, fillPlace(inst, vals[i], elctx), 'each'))
+      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 7 */
+} /* node:coverage ignore next 6 */
 
 
 export {
-  dataValues,
   EachFuncVal,
 }

package/src/val/EmitFuncVal.ts

@@ -1,86 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// TRANSFORMATION: `emit(select, table)` (G9 phase 6,
-// docs/design/EMIT.0.md). Apply-templates, with the dispatch in the
-// engine and none of it in user space.
-//
-//   emit($.services, [
-//     {match: {kind: sqs}, body: [`listen(` + .pin + `)`]}
-//     {match: {kind: http}, body: [`serve(` + .path + `)`]}
-//   ])
-//
-// For every node of `select`, in order, the first template whose
-// `match` the node unifies with is taken and its `body` instantiated
-// AGAINST THAT NODE. The result is one flat list.
-//
-// WHY THIS CANNOT BE WRITTEN IN THE DOCUMENT (EMIT.0.md, "What it
-// takes"). A rule table held as a value cannot be dispatched against:
-// a body referenced by path resolves its relative references AT THE
-// DEFINITION SITE, and the positional resolution that does exist is a
-// dot COUNT that does not survive being consumed by a second dispatch.
-// The builtin instantiates a body at the node it matched -- a NAMED
-// origin -- which is the whole capability.
-//
-// THE BODY'S RELATIVE REFERENCES ARE BOUND TO THE NODE. `.pin` inside
-// a body is the matched node's `pin`, and `_` is the node itself, as
-// it is in every other generator. The binding is done HERE rather than
-// left to path resolution: a relative path is a COUNT taken wherever
-// the value comes to rest, and the nodes of a computed selection
-// (`filter(...)`) come to rest nowhere -- there is no position for a
-// count to be taken from. An ABSOLUTE reference is untouched and still
-// reads the document root.
-//
-// The binding stops at a nested generator's own binding argument
-// (boundArgStart): a rule table nested in a body is the INNER emit's
-// to bind, so `.x` inside it is the inner node. What crosses the
-// boundary is the nested call's SELECTOR, which is argument 0 and is
-// bound here -- the selector is the channel.
-//
-// THE RESULT IS FLAT, and that is a constraint rather than a
-// convenience: the fragment algebra is flat because the nested
-// spelling refuses even a valid instance in both ports, so a dispatch
-// returning a tree would undo that ruling. A body element that is
-// itself a list SPLICES, which is what makes a nested emit compose.
-//
-// A VALUE REACHES THE BODY THROUGH `replace`, NOT A DELIMITER
-// (docs/design/TEMPLATE.0.md D3, D4; RENDER.0.md P6). A template may
-// carry a `replace` map whose key is an exact string the body already
-// holds as ordinary target text and whose value is evaluated against
-// the matched node, and an `esc` naming the convention every value is
-// escaped by -- the C/JSON escape when absent, `none` the one opt-out.
-// Three rules: a single left-to-right scan of a literal line taking
-// the longest key at each position; a substituted value is never
-// re-scanned, so no value can introduce a key; and a template's
-// replacements touch its own literal text only, never a result spliced
-// in from a nested dispatch. Two checks run on the template before any
-// node: a key inside another key (replace_overlap) and a key the body
-// does not hold (replace_unused). There is no hole syntax, and that is
-// the point: any inline delimiter is somebody's syntax.
-//
-// NO MATCH IS AN ERROR (`emit_none`). XSLT's built-in rule copies an
-// unhandled node's string value into the result, which for code output
-// means model data landing silently in the middle of a source file.
-// That is the single worst default in the prior art and it is refused.
-// An EMPTY selection, by contrast, emits nothing -- which is the whole
-// conditional mechanism, and why no `when` directive exists.
-//
-// A NAMED TABLE IS A PLACEHELD `emit` (`%wire = emit(_, T)`). A table
-// written at a document position is DRIVEN there, so its bodies'
-// relative references resolve against wherever it sits and miss;
-// nothing in the language holds a value unevaluated at such a
-// position, and what does hold one is a CALL's template argument.
-// `emit(.listen, %wire)` follows the reference and reads the table out
-// of the placeheld call; `.listen & %wire` fills the hole. Both are
-// the same dispatch, and it is what lets a rule set name ITSELF.
-//
-// TERMINATION IS THE SELECTION'S. Unlike `pack` and `each`, this one
-// recurses -- a nested model walked into nested output is the
-// capability the rule layer exists to add -- so the bound is not "it
-// cannot call itself" but "each dispatch descends into a finite bag
-// that already exists, and a selection that empties emits nothing". A
-// rule set that walks into itself WITHOUT descending is charged to the
-// depth budget and refused as `unify_cycle`, like any other runaway
-// descent.
 
 import type {
   Val,
@@ -106,12 +25,6 @@ import { plusText } from './PlusOpVal'
 import { bagMembers } from './members'
 
 
-// One entry of the rule table: the pattern to try, the body to
-// instantiate, and -- TEMPLATE.0.md D3 and D4 -- the `replace` map and
-// the `esc` convention its values take, with the literal spots of the
-// body the replacements are written into. A table is a LIST of these;
-// a single template map is that list of one, told apart by kind,
-// exactly as match() tells its patterns apart.
 type Template = {
   match: Val,
   body: Val,
@@ -125,8 +38,8 @@ type Template = {
 
 
 // One literal string of a body: element `i`, and within a map element
-// the `of` index or the `text` key, with the text itself.
-type LitSpot = { i: number, of?: number, text?: boolean, s: string }
+// the `n` index or the `text` key, with the text itself.
+type LitSpot = { i: number, n?: number, text?: boolean, s: string }
 
 
 // What is wrong with a table, with the detail the message carries.
@@ -148,15 +61,6 @@ function isRefusal(x: any): x is Refusal {
 function tableTemplates(table: Val | undefined): Template[] | Refusal {
   const t: any = table
 
-  // A NAMED TABLE IS A PLACEHELD `emit`, and its table is the table.
-  // A table written at a document position is DRIVEN there -- a body's
-  // relative references resolve against wherever it sits and miss --
-  // so the position that holds one unevaluated is the one position the
-  // language already never drives: a call's template argument.
-  // `%wire = emit(_, [ … ])` is that position with the selection left
-  // open, and it reads as what it is, an apply-templates waiting for
-  // its nodes: `emit(.listen, %wire)` passes them, `.listen & %wire`
-  // fills the hole, and both are the same dispatch.
   if (true === t?.isEmitFunc) {
     return tableTemplates(t.peg[1])
   }
@@ -186,12 +90,6 @@ function tableTemplates(table: Val | undefined): Template[] | Refusal {
 }
 
 
-// One rule. Both keys are required: a template with no pattern would
-// match everything by accident, and one with no body would emit
-// nothing while claiming a node. The two optional keys -- a `replace`
-// map and an `esc` naming the convention its values are escaped by,
-// `none` the one opt-out -- are the template's shape too, and D3's two
-// static checks run here, on the template alone, before any node.
 function oneTemplate(m: any, idx: number): Template | Refusal {
   const match: Val = m.peg.match
   const body: any = m.peg.body
@@ -235,12 +133,6 @@ function textOf(v: any): string | undefined {
 }
 
 
-// The literal strings of a body -- a string element, and the strings
-// written directly in a map element's `of` list or `text` -- which are
-// the text the template wrote. A string an expression or a nested
-// dispatch computes is not one: D3's third rule (a spliced result is
-// finished) and its second (a substituted value is never re-scanned)
-// both follow from substituting at these spots and nowhere else.
 function literalSpots(elems: Val[]): LitSpot[] {
   const out: LitSpot[] = []
   elems.forEach((el: any, i: number) => {
@@ -252,12 +144,12 @@ function literalSpots(elems: Val[]): LitSpot[] {
     if (true !== el?.isMap) {
       return
     }
-    const of: any = el.peg.of
-    if (true === of?.isList) {
-      (of.peg as any[]).forEach((p: any, j: number) => {
+    const chunks: any = el.peg.n
+    if (true === chunks?.isList) {
+      (chunks.peg as any[]).forEach((p: any, j: number) => {
         const ps = textOf(p)
         if (undefined !== ps) {
-          out.push({ i, of: j, s: ps })
+          out.push({ i, n: j, s: ps })
         }
       })
     }
@@ -270,11 +162,6 @@ function literalSpots(elems: Val[]): LitSpot[] {
 }
 
 
-// D3's two static checks, on the template alone and before any node:
-// a key inside another is ambiguous whatever the order
-// (replace_overlap), and a key no literal holds means the template
-// drifted from its map (replace_unused). Keys are visited in code
-// point order, so both ports name the same pair.
 function checkReplace(keys: string[], lits: LitSpot[]): Refusal | undefined {
   const sorted = [...keys].sort(cmpCodePoint)
   for (const a of sorted) {
@@ -293,10 +180,6 @@ function checkReplace(keys: string[], lits: LitSpot[]): Refusal | undefined {
 }
 
 
-// D3's first two rules as one scan: at each position the longest key
-// that matches is taken and its value written out whole, and the scan
-// moves past the KEY -- the value is never looked at again, so no
-// value can introduce a key.
 function substitute(text: string, pairs: Pair[]): string {
   let out = ''
   let i = 0
@@ -315,11 +198,6 @@ function substitute(text: string, pairs: Pair[]): string {
 }
 
 
-// The instance with the template's literal text at element `i`
-// rewritten through the pairs -- on the fresh instance, where the
-// structure is exactly the template's, and before any binding, so a
-// value written in is never scanned again and a spliced result is
-// never touched.
 function substituted(
   inst: Val, i: number, lits: LitSpot[], pairs: Pair[], ctx: AontuContext
 ): Val {
@@ -328,8 +206,8 @@ function substituted(
       continue
     }
     const sv = new StringVal({ peg: substitute(l.s, pairs) }, ctx)
-    if (undefined !== l.of) {
-      (inst as any).peg.of.peg[l.of] = sv
+    if (undefined !== l.n) {
+      (inst as any).peg.n.peg[l.n] = sv
     }
     else if (true === l.text) {
       (inst as any).peg.text = sv
@@ -374,14 +252,6 @@ function bindNode(v: any, node: Val, ctx: AontuContext, fail: Fail): Val {
       return v
     }
     const out = found.clone(ctx)
-    // A RELATIVE REFERENCE IS A READ TOO (RENDER.0.md P7), and the one
-    // read no reference resolution sees: the binding answers it here,
-    // from the matched node, rather than letting a path resolve at a
-    // position the body never occupies. Without this a nested rule set
-    // whose selection is `.handlers` reported its nodes at the address
-    // they came to rest, which is in the OUTPUT. A node carries an
-    // address only under an instrumented run, which is what makes the
-    // second test the whole guard.
     if (null == (out as any).origin && null != (node as any).origin) {
       ; (out as any).origin = (node as any).origin +
         (v.peg as string[]).map((seg: string) => '.' + seg).join('')
@@ -430,12 +300,6 @@ function bindNode(v: any, node: Val, ctx: AontuContext, fail: Fail): Val {
 }
 
 
-// The field of `node` a reference names, or undefined when it names
-// none. Only a chain of plain NAMES is a field: a parent step has no
-// answer at a node that is an origin rather than a position, and a
-// variable segment is not a name until something resolves it -- both
-// are refused here rather than left to resolve somewhere else, which
-// is the failure mode the binding exists to remove.
 function nodeField(ref: any, node: Val): Val | undefined {
   let cur: any = node
   for (const seg of ref.peg as any[]) {
@@ -455,21 +319,6 @@ function nodeField(ref: any, node: Val): Val | undefined {
 }
 
 
-// The address of one matched node: its own read address when it has
-// one, else the SELECTION's read address and the node's key under it
-// -- a selection is read once and walked, so its members carry no read
-// of their own.
-//
-// A COMPUTED SELECTION HAS NO ADDRESS, AND THE TRACE SAYS SO: an empty
-// node. `filter(...)` builds a bag no path in the document names, and
-// the only other thing to report is where the bag came to REST -- a
-// position inside a template instance, which is not in the document,
-// and which the two ports number differently. Publishing that would
-// have made the trace a parity break as well as a fiction. The rule
-// address answers the same way: `<table>#<index>` for a table a
-// reference reached, and `#<index>` alone for one written inline at the
-// call site, which has no address of its own. `#` is in no path, so a
-// rule's address can never be read as one.
 function nodeAddr(sel: string | undefined, key: string, node: any): string {
   if (null != node.origin) {
     return node.origin
@@ -534,22 +383,11 @@ class EmitFuncVal extends FuncBaseVal {
 
 
   resolve(ctx: AontuContext, args: Val[]) {
-    // THE MEMBERS WITH THEIR KEYS, read through the one helper every
-    // fold reads a bag by (./members.ts): source order for a list,
-    // sorted-key order for a map, a hidden child and an unfilled
-    // optional left out. The KEY is what the trace addresses a node by
-    // -- it is the node's key IN THE SELECTION, which is the only
-    // thing a walk of a computed bag knows about where a node sits.
     const nodes = bagMembers(args?.[0], ctx)
     if (undefined === nodes) {
       return makeNilErr(ctx, 'emit_data', this)
     }
 
-    // A NAMED TABLE IS REACHED BY REFERENCE, and the reference -- not
-    // the table -- is what is followed. Followed HERE rather than in
-    // the staged drive, which waits for a SETTLED target: a table is a
-    // template, a template holding a hole never settles, and waiting
-    // for one would mean the dispatch never fires.
     let table: any = args?.[1]
     if (true === table?.isRef) {
       table = table.unify(top(), ctx)
@@ -560,10 +398,6 @@ class EmitFuncVal extends FuncBaseVal {
       return this.refuse(ctx, templates)
     }
 
-    // THE TRACE'S TWO ADDRESSES (RENDER.0.md D11, P7), computed once
-    // per dispatch and only when the run is instrumented: the table's
-    // own, which every rule of it is numbered under, and the
-    // selection's, which every node of it is keyed under.
     const rec = undefined !== ctx.reads
     const tableAddr = rec ? ((table as any)?.origin ?? '') : ''
     const selAddr = rec ? (args?.[0] as any)?.origin : undefined
@@ -582,11 +416,6 @@ class EmitFuncVal extends FuncBaseVal {
       const fail: Fail = {}
       let mark: EmitOrigin | undefined = undefined
       if (rec) {
-        // THE NODE KEEPS ITS ADDRESS (P7). A body passes the node on
-        // through `_`, and a nested rule set dispatching over it can
-        // then say where it came from -- otherwise the node arrives as
-        // an element of a list the body wrote, and the only address
-        // left is where that list came to rest.
         const naddr = nodeAddr(selAddr, member.key, node)
         if ('' !== naddr && null == (node as any).origin) {
           ; (node as any).origin = naddr
@@ -643,14 +472,6 @@ class EmitFuncVal extends FuncBaseVal {
   }
 
 
-  // The replacement pairs for one node: the template's `replace` map
-  // instantiated at the node -- bound, filled and driven as a body is
-  // -- each value as text by the one number-to-text rule (`plusText`,
-  // the rule `+` and `join` share), escaped by the template's
-  // convention unless that is `none`, and sorted longest key first so
-  // the scan takes the longest match at every position (D3's first
-  // rule). A value that is not text, or has not settled, is
-  // replace_value.
   replacements(ctx: AontuContext, node: Val, tmpl: Template, fail: Fail): Pair[] | undefined {
     if (undefined === tmpl.replace) {
       return undefined
@@ -676,13 +497,6 @@ class EmitFuncVal extends FuncBaseVal {
   }
 
 
-  // Instantiate one body at the node and SPLICE its pieces into the
-  // output. A full instance to the leaves (`dup`, ADR-005), because a
-  // bare clone shares the inner structure of any call in the body and
-  // the first node's resolution would answer for every node; the
-  // template's replacements written into the instance's literal text;
-  // then the two bindings, relative references and the hole, both to
-  // the node.
   instantiate(ctx: AontuContext, node: Val, tmpl: Template,
     out: Val[], fail: Fail, mark?: EmitOrigin): void {
     const pairs = this.replacements(ctx, node, tmpl, fail)
@@ -700,24 +514,10 @@ class EmitFuncVal extends FuncBaseVal {
       }
       let piece = fillPlace(bindNode(inst, node, elctx, fail), node, elctx)
 
-      // A NESTED DISPATCH IS DRIVEN HERE, not left for the next pass.
-      // Its selection is bound and the model has settled, so it has
-      // everything it needs -- and it must answer NOW, because what
-      // makes the result flat is splicing its pieces into this one.
-      // Left standing, a nested `emit` resolved a pass later, as a
-      // list INSIDE the list, and the fragment algebra is flat.
-      // Through `unite` rather than by hand: a rule set that walks
-      // into itself for ever is charged to the depth budget and
-      // refused as `unify_cycle`, like any other runaway descent.
       if (!piece.done) {
         piece = unite(elctx, piece, top(), 'emit')
       }
 
-      // THE INNERMOST DISPATCH OWNS THE PIECE (P7). A body element
-      // that is a nested rule set has already stamped what it emitted,
-      // and those pieces are spliced into this result here: the rule
-      // that WROTE a line is the one the trace names, so a stamp is
-      // written only where there is none.
       const at = out.length
       splice(piece, out)
       if (undefined !== mark) {

package/src/val/ExpectVal.ts

@@ -34,22 +34,6 @@ class ExpectVal extends FeatureVal {
   parent?: Val
   key?: string
 
-  // An expectation canons as THE EXPECTATION ITSELF -- the peg the peer
-  // must satisfy. Val.canon's default was the empty string, which
-  // rendered a key with no value (`{"r":}`): text that is not a document
-  // and could not be reparsed, breaking canon's round-trip contract in
-  // both engines (issue #43).
-  //
-  // Not `top`, which was the first fix here and was wrong. An ExpectVal
-  // is created for EVERY peer-introduced non-generable key, not just for
-  // `&:` spread children -- `m:{x:1} m:{y:string}` makes one at `y` with
-  // no spread in sight -- so rendering `top` erased the `string` and the
-  // canon reparsed into a document that accepts values the original
-  // rejects. A canon that silently drops a constraint is worse than one
-  // that fails to parse. Go's ExpectVal.Canon renders the same peg.
-  //
-  // Which is why `peg` is kept the WHOLE expectation as peers arrive
-  // (BUGS.md §48) rather than only what was first written: see unify.
   get canon() { return this.peg.canon }
 
   constructor(
@@ -59,41 +43,15 @@ class ExpectVal extends FeatureVal {
     super(spec, ctx)
   }
 
-  // PURE, deliberately (the unequal-spread crosswire, BUGS.md §6-§7).
-  // The old body accumulated `this.peer` IN PLACE, which was invisible
-  // while an expectation only ever lived at one destination -- but the
-  // spread-combination meet (MapVal.unify's 'map-self' unite) bakes an
-  // ExpectVal INTO the combined template, and a path-independent
-  // template is SHARED across every destination (spreadClone tier 1).
-  // One stateful node in a shared template unified each sibling's own
-  // data with the next sibling's ($.w.y.r: "Cannot unify value: 6 with
-  // value: 5", both values sibling data). An expectation now answers
-  // with a NEW node when it must keep accumulated state, so a shared
-  // template's expect stays exactly what was written.
   unify(peer: Val, ctx: AontuContext): Val {
     const te = ctx.explain && explainOpen(ctx, ctx.explain, 'Expect', this, peer)
 
     let out: Val = this
 
     if (!peer.isTop) {
-      // THE PEER MEETS THE WHOLE EXPECTATION. `peg` already carries
-      // every peer met so far (see below), so meeting the incoming peer
-      // against the ACCUMULATED `peer` first -- as this did -- refused
-      // against only the atom that happened to reject. A conflict with
-      // `peg` is a conflict with the accumulation too, since peg
-      // subsumes it, so nothing stops being refused: only the sentence
-      // changes, to the residual the error's own hint promises
-      // (BUGS.md §48).
       const peeru =
         unite(te ? ctx.clone({ explain: ec(te, 'EXPECT') }) : ctx, peer, this.peg, 'expect-self')
 
-      // Accumulated for the `expect` finding's operand. Computed BEFORE
-      // the escape below, where it has always been: an expectation that
-      // escapes still passed through here, and moving it after the
-      // escape leaves the accumulating arm reachable only by a node
-      // that both carries an accumulation AND fails to escape -- which
-      // the suite never produces, so it reads as dead code against the
-      // ADR-002 gate. Go's ExpectVal.Unify keeps the same order.
       const acc = undefined === this.peer ? peer :
         unite(te ? ctx.clone({ explain: ec(te, 'PEER') }) : ctx, this.peer, peer, 'expect-peer')
 
@@ -101,26 +59,6 @@ class ExpectVal extends FeatureVal {
         out = peeru
       }
       else {
-        // Still an expectation: carry the accumulated peer forward in a
-        // fresh node stored at THIS destination by the caller, leaving
-        // `this` -- possibly a shared template's child -- untouched.
-        //
-        // THE MEET IS THE NEW PEG (BUGS.md §48). An expectation that
-        // has met a peer without being freed by it stands for `peg &
-        // peer` from then on -- that is what a later peer must satisfy,
-        // and what canon has to state. Rebuilding from the ORIGINAL peg
-        // dropped the peer everywhere the node was later copied (the
-        // bag re-wrap, Val.clone), so `b:{z:1} b:{u8:min(0)}
-        // a:$.b.u8&max(15)` -- whose reference resolves a pass late, so
-        // `max(15)` arrives as a peer -- canoned as `min(0)`. That text
-        // reparses into a document admitting 20, which the original
-        // rejects, and hashed differently in each port. Storing the
-        // meet in `peg` needs no new field and no carrying: every copy
-        // site already preserves `peg`.
-        //
-        // Purity is untouched -- this is a NEW node, so a shared
-        // template's own expectation keeps the peg it was written with
-        // (§6-§7).
         const e = new ExpectVal({ peg: peeru }, ctx)
         e.key = this.key
         e.parent = this.parent

package/src/val/FilterFuncVal.ts

@@ -1,35 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// GENERATION: `filter(data, cond)` (G8 phase 2,
-// docs/capability-review/g8-generation.md). The children of `data`
-// that unify with `cond`, keys preserved for a map and order for a
-// list; the children that do not are DROPPED, not refused.
-//
-//   debugged: filter($.services, {debug: true})
-//   sidecars: pack($.debugged, {image: "acme/debug:1.0"})
-//
-// A CHILD IS KEPT WHEN THE CONDITION CHANGES NOTHING: the meet
-// succeeds AND its answer is the child itself, which is to say the
-// child ALREADY satisfies the condition. Mere unifiability is not the
-// test, and cannot be: a map is open, so `{p:2}` unifies with
-// `{debug:true}` perfectly well by GAINING the key -- and a filter
-// that keeps everything that could be made to match keeps everything.
-// The design named unifiability; its own example
-// (`filter($.services, {debug:true})`) is unsatisfiable under it.
-//
-// There is no predicate language here and there will not be one:
-// `cond` is an ordinary Aontu value, so the constraint atoms compose
-// with it for free (`filter($.deploy, {replicas: min(3)})`), and a
-// document that can filter can be read by anything that can read a
-// document.
-//
-// A FAILED CHILD IS AN ANSWER, not an error. The meet runs in TRIAL
-// MODE -- the mechanism disjunction already uses to try each member
-// against a peer (trialUnify in FuncBaseVal) -- so a child that does
-// not match costs nothing and reports nothing.
-//
-// TOTALITY. `filter` iterates a finite, settled bag and cannot call
-// itself, exactly as `pack` and `each` cannot.
 
 import type {
   Val,
@@ -72,15 +42,6 @@ class FilterFuncVal extends FuncBaseVal {
   }
 
 
-  // Neither argument is driven by the base: `unify` below drives the
-  // DATA by hand, because a staged func must advance the argument it
-  // is waiting on every pass rather than only on the one it fires.
-  //
-  // The CONDITION is not driven at all, and that is deliberate: it is
-  // a template, tested against each child at that child's position,
-  // so it may hold a `_` (G8 phase 3, the child it is being tested
-  // against) or a relative reference — neither of which has an answer
-  // at the call site. Driving it there would freeze both.
   prepare(_ctx: AontuContext, _args: Val[]) {
     return null
   }
@@ -99,19 +60,7 @@ class FilterFuncVal extends FuncBaseVal {
     const data: any = args[0]
     const cond: Val = args[1]
 
-    // The trial is run against CLONES: `unite` refines a bag in place,
-    // and a child that failed the test must reach the result -- when
-    // it passes -- exactly as it was written.
-    //
-    // Canon is the comparison because canon is what "the same value"
-    // MEANS in this language: it is the form the two ports agree on,
-    // the form `aontu diff` compares, and the form a hash is taken of.
     const keeps = (child: Val, kctx: AontuContext): boolean => {
-      // `_` inside the condition binds the child being tested (G8
-      // phase 3), so a condition can be about the child as a whole
-      // rather than only about its shape. The condition is cloned as
-      // a FULL instance per trial (`dup`, ADR-005) — a bare clone
-      // shares call/pref innards across trials (see PackFuncVal).
       const inst = cond.clone(kctx, { dup: true })
       repathInstance(inst, inst.path)
       const test = fillPlace(inst, child, kctx)
@@ -136,10 +85,6 @@ class FilterFuncVal extends FuncBaseVal {
     if (true === data?.isList) {
       const peg: 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
-        // lands rather than where it came from.
         const ectx = ctx.descend(String(peg.length))
         if (keeps(el, ectx)) {
           peg.push(el.clone(ectx))