aontu 0.52.1 → 0.53.0

package/src/val/FilterFuncVal.ts

@@ -0,0 +1,154 @@
+/* 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,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+import { MapVal } from './MapVal'
+import { ListVal } from './ListVal'
+import { FuncBaseVal, trialUnify } from './FuncBaseVal'
+import { repathInstance } from './Val'
+import { fillPlace } from './PlaceVal'
+
+
+class FilterFuncVal extends FuncBaseVal {
+  isFilterFunc = true
+
+  // THE STAGING RULE (G8 phase 0). A subset of a bag that is still
+  // being merged into is a subset of the wrong bag.
+  staged = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+  funcname() {
+    return 'filter'
+  }
+
+
+  // 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
+  }
+
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const ready = this.driveStagedArgs(ctx, 1)
+
+    if (!ready || !ctx.settle) {
+      return this.residuate(peer, ctx)
+    }
+
+    return super.unify(peer, ctx)
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    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)
+      const met = trialUnify(kctx, child.clone(kctx), test)
+      return undefined !== met && met.canon === child.canon
+    }
+
+    if (true === data?.isMap) {
+      const peg: Record<string, Val> = {}
+      for (const key of Object.keys(data.peg)) {
+        const kctx = ctx.descend(key)
+        if (keeps(data.peg[key], kctx)) {
+          peg[key] = data.peg[key].clone(kctx)
+        }
+      }
+      return new MapVal({ peg }, ctx)
+    }
+
+    if (true === data?.isList) {
+      const peg: Val[] = []
+      for (const el of data.peg as Val[]) {
+        // 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))
+        }
+      }
+      return new ListVal({ peg }, ctx)
+    }
+
+    return makeNilErr(ctx, 'filter_data', this)
+  }
+
+} /* node:coverage ignore next 5 */
+
+
+export {
+  FilterFuncVal,
+}

package/src/val/FuncBaseVal.ts

@@ -29,12 +29,53 @@ import {
 
 import { ConjunctVal } from '../val/ConjunctVal'
 import { FeatureVal } from '../val/FeatureVal'
+import { hasPlace, fillPlace } from '../val/PlaceVal'
+
+
+// A TRIAL meet: does `a` unify with `b`, and if so as what? Failure is
+// an ANSWER here rather than an error, which is exactly what
+// DisjunctVal already needs when it tries each member against a peer —
+// so this is that mechanism (`ctx._trialMode`, which makes makeNilErr
+// return the shared TRIAL_NIL instead of allocating and recording),
+// lent to the combinators that select by unifiability.
+//
+// The error list and the trial flag are saved and restored in a
+// `finally`: a trial that throws must not leave the surrounding
+// evaluation collapsing every later error into the sentinel.
+function trialUnify(ctx: AontuContext, a: Val, b: Val): Val | undefined {
+  const savedErr = ctx.err
+  const savedTrial = ctx._trialMode
+  const trialErr: any[] = []
+
+  ctx.err = trialErr
+  ctx._trialMode = true
+
+  let out: Val
+  try {
+    out = unite(ctx, a, b, 'trial')
+  }
+  finally {
+    ctx.err = savedErr
+    ctx._trialMode = savedTrial
+  }
+
+  return 0 < trialErr.length || out.isNil ? undefined : out
+}
 
 
 class FuncBaseVal extends FeatureVal {
   isFunc = true
   isGenable = true
 
+  // THE STAGING RULE (G8 phase 0, see AontuContext.settle). A func
+  // whose answer depends on WHERE IT IS -- `key()`, whose answer is a
+  // segment of its own path, and the generation combinators, whose
+  // data argument can still be merged into by a sibling -- sets this
+  // and residuates until the model stops moving. Everything else
+  // resolves as soon as its arguments are done, which is the rule that
+  // has always been here.
+  staged = false
+
   constructor(
     spec: ValSpec,
     ctx?: AontuContext
@@ -58,7 +99,118 @@ class FuncBaseVal extends FeatureVal {
   }
 
 
+  // Drive the first `count` arguments IN PLACE, every pass — not only
+  // on the settle pass. A staged func waits for the model to settle,
+  // and its own arguments are part of that model: leaving them
+  // standing until settle would guarantee the model was still moving
+  // when settle arrived. Answers whether they are all done, which is
+  // the other half of "ready to fire".
+  driveStagedArgs(ctx: AontuContext, count: number): boolean {
+    const TOP = top()
+    let alldone = true
+
+    // THE SNAPSHOT WAITS FOR THE SOURCE (the spread-then-pack defect,
+    // use-cases/BUGS.md pack-refs family). A reference resolving inside
+    // a staged argument is this argument's SNAPSHOT of its source, and
+    // the snapshot is not part of the tree: a spread-injected relative
+    // reference inside a too-early copy dangles at the argument's
+    // location (`.containerPort` rebased under the generator, where no
+    // root traversal reaches it) and the generator never fires. The
+    // `argsnap` flag makes RefVal.find defer until the target has
+    // finished resolving IN THE TREE — where its own spreads and
+    // relative references answer at their real location — and only then
+    // take the copy. Inherited by every descended ctx, so a reference
+    // anywhere in the argument subtree waits the same way.
+    const actx: AontuContext = ctx.clone({})
+    ; (actx as any).argsnap = true
+
+    for (let i = 0; i < count && i < this.peg.length; i++) {
+      const arg: Val = this.peg[i]
+      if (!arg.done) {
+        // Charged to the depth budget, as FuncBaseVal's own arg loop is:
+        // this recurses without going through `unite`.
+        this.peg[i] = withDepth(ctx, arg, TOP, () => arg.unify(TOP, actx))
+      }
+      alldone = alldone && true === this.peg[i].done
+    }
+
+    return alldone
+  }
+
+
+  // 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(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.
+      out.peg = this.peg.map((a: Val) => a.clone(ctx, { dup: true }))
+    }
+    return out
+  }
+
+
+  // The shape a staged func holds while it waits: not done, so the pass
+  // loop keeps going; unchanged against TOP, so nothing reads an answer
+  // it has not given; and collapsed against an identical twin at the
+  // same position, so `key() & key()` does not grow a conjunct per pass.
+  residuate(peer: Val, ctx: AontuContext): Val {
+    this.notdone()
+
+    if (peer.isTop || (peer.id === this.id)) {
+      // Cloned rather than returned: a driver that met the same object
+      // twice in one pass would charge the revisit budget and report
+      // `unify_cycle`.
+      return this.clone(ctx)
+    }
+
+    if (peer.isNil) {
+      return peer
+    }
+
+    if (peer.isFunc
+      && (peer as any).funcname() === this.funcname()
+      && peer.path.join('.') === this.path.join('.')
+      && peer.canon === this.canon) {
+      return this
+    }
+
+    return new ConjunctVal({ peg: [this, peer] }, ctx)
+  }
+
+
   unify(peer: Val, ctx: AontuContext): Val {
+    if (this.staged && !ctx.settle) {
+      return this.residuate(peer, ctx)
+    }
+
+    // THE PLACEHOLDER (G8 phase 3, see PlaceVal). A call holding a hole
+    // waits for a peer, and the peer is what fills it: the call is
+    // rebuilt with the hole replaced and resolved on the spot, so
+    // `upper(_) & hello` is `"HELLO"` and not `"HELLO" & "hello"` --
+    // the peer went INTO the call, it is not also a constraint on the
+    // way out.
+    if (!peer.isTop && !peer.isNil && this.id !== peer.id && hasPlace(this)) {
+      // TWO HOLES AND NOTHING TO FILL THEM. `upper(_) & lower(_)` has
+      // no value on either side, and picking one call to be the other's
+      // filling would be inventing an order the language does not have.
+      if (hasPlace(peer)) {
+        return makeNilErr(ctx, 'place_pair', this, peer)
+      }
+      return fillPlace(this, peer, ctx).unify(top(), ctx)
+    }
+
     const TOP = top()
     const te = ctx.explain && explainOpen(ctx, ctx.explain, 'Func:' + this.funcname(), this, peer)
 
@@ -123,7 +275,12 @@ class FuncBaseVal extends FeatureVal {
           const resolved = this.resolve(ctx, newpeg)
           // console.log('FUNC-RESOLVED', ctx.cc, resolved?.canon)
 
-          out = resolved.done && peer.isTop ? resolved :
+          // The TOP peer is DROPPED as the unit it is — unless it
+          // carries an identity (G4 phase 1), which is content rather
+          // than the unit: `id(x) & id(y)` resolves both sides to a
+          // top, and taking this shortcut would silently keep one
+          // name and lose the other instead of refusing the pair.
+          out = resolved.done && peer.isTop && null == peer.entity ? resolved :
             unite(te ? ctx.clone({ explain: ec(te, 'PEG') }) : ctx,
               resolved, peer, 'func-' + this.funcname() + '/' + this.id)
           propagateMarks(this, out)
@@ -132,6 +289,17 @@ class FuncBaseVal extends FeatureVal {
           out.site.row = this.site.row
           out.site.col = this.site.col
           out.site.url = this.site.url
+          // THE SPAN COMES WITH THE POSITION, always. Moving row and
+          // col onto the result while leaving its own text behind
+          // produced a site that contradicted itself: `close({...})`
+          // reported the call's column and the map's `{`, so reading
+          // the document at (row, col, len) found `c` where `src` said
+          // `{`. A consumer following the verification contract would
+          // refuse every such repair; one skipping it would edit the
+          // wrong token. Whatever the position names, the text names
+          // too. Twin: the same assignment in go/func.go.
+          out.site.len = this.site.len
+          out.site.src = this.site.src
           out.path = this.path
 
           why += 'pegdone'
@@ -144,6 +312,17 @@ class FuncBaseVal extends FeatureVal {
           out.site.row = this.site.row
           out.site.col = this.site.col
           out.site.url = this.site.url
+          // THE SPAN COMES WITH THE POSITION, always. Moving row and
+          // col onto the result while leaving its own text behind
+          // produced a site that contradicted itself: `close({...})`
+          // reported the call's column and the map's `{`, so reading
+          // the document at (row, col, len) found `c` where `src` said
+          // `{`. A consumer following the verification contract would
+          // refuse every such repair; one skipping it would edit the
+          // wrong token. Whatever the position names, the text names
+          // too. Twin: the same assignment in go/func.go.
+          out.site.len = this.site.len
+          out.site.src = this.site.src
           out.path = this.path
 
           why += 'top'
@@ -163,6 +342,17 @@ class FuncBaseVal extends FeatureVal {
           out.site.row = this.site.row
           out.site.col = this.site.col
           out.site.url = this.site.url
+          // THE SPAN COMES WITH THE POSITION, always. Moving row and
+          // col onto the result while leaving its own text behind
+          // produced a site that contradicted itself: `close({...})`
+          // reported the call's column and the map's `{`, so reading
+          // the document at (row, col, len) found `c` where `src` said
+          // `{`. A consumer following the verification contract would
+          // refuse every such repair; one skipping it would edit the
+          // wrong token. Whatever the position names, the text names
+          // too. Twin: the same assignment in go/func.go.
+          out.site.len = this.site.len
+          out.site.src = this.site.src
           out.path = this.path
 
           why += 'defer'
@@ -207,5 +397,6 @@ class FuncBaseVal extends FeatureVal {
 
 
 export {
+  trialUnify,
   FuncBaseVal,
 }

package/src/val/HideFuncVal.ts

@@ -15,8 +15,6 @@ import { makeNilErr } from '../err'
 
 import {
   walk,
-  explainOpen,
-  explainClose,
 } from '../utility'
 
 

package/src/val/IdFuncVal.ts

@@ -0,0 +1,91 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE IDENTITY MARK (G4 phase 1,
+// docs/capability-review/g4-identity-relations.md): `id(name)`
+// declares that the enclosing value is an independent ENTITY named
+// `name`, and every node in one evaluation carrying that name is
+// unified with every other.
+//
+// It is written as a conjunct — `id(svc/auth) & { … }` — so the
+// function itself resolves to the UNIT (top) carrying the name, and
+// the identity rides the meet onto the value, the same channel G3's
+// deprecation record uses. Declaring two nodes the same entity MEANS
+// unifying them, so a contradiction between them is a located error
+// naming both sites: the anti-`owl:sameAs`.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { FuncBaseVal } from './FuncBaseVal'
+import { TopVal } from './TopVal'
+import { nextValId } from './Val'
+
+
+// Letters, digits, `_`, `-`, `/` — and NO DOTS: a dot separates an
+// entity address from a sub-path (G4 phase 2), so a dotted id would
+// make `svc/auth.port` ambiguous between "the entity `svc/auth.port`"
+// and "the port of `svc/auth`".
+const ID_NAME = /^[A-Za-z0-9_/-]+$/
+
+
+// The name an argument spells, or undefined when it does not spell
+// one. A bare `svc/auth` parses as a string, as does `"svc/auth"`;
+// anything else — a number, a map, an unresolved reference — is not a
+// name, and saying so at once beats an entity nobody can address.
+export function idName(v: any): string | undefined {
+  if (true !== v?.isScalar || 'string' !== typeof v.peg) {
+    return undefined
+  }
+  return ID_NAME.test(v.peg) ? v.peg : undefined
+}
+
+
+class IdFuncVal extends FuncBaseVal {
+  isIdFunc = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new IdFuncVal(spec)
+  }
+
+  funcname() {
+    return 'id'
+  }
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const name = idName(args[0])
+    if (undefined === name) {
+      return makeNilErr(ctx, 'id_name', this, undefined, 'id')
+    }
+
+    // THE UNIT, carrying the identity: `id(x) & v` must be `v` with an
+    // identity, so the function resolves to what unifies with anything
+    // and lets the rider in `unite` do the stamping.
+    const out = new TopVal({}, ctx)
+    // NOT id 0: TopVal pins that, and `unite`'s fast path returns
+    // early for two done Vals sharing an id — which would drop one of
+    // two identities before the rider could refuse them.
+    out.id = nextValId()
+    out.entity = name
+    return out
+  }
+} /* node:coverage ignore next 6 */
+
+
+export {
+  IdFuncVal,
+}

package/src/val/JunctionVal.ts

@@ -33,7 +33,13 @@ abstract class JunctionVal extends FeatureVal {
 
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     let out = (super.clone(ctx, spec) as JunctionVal)
-    out.peg = this.peg.map((entry: Val) => entry.clone(ctx, spec?.mark ? { mark: spec.mark } : {}))
+    // The instantiation flag descends with the mark (ADR-005): a
+    // junction inside a template clones its members as instances (the
+    // instantiation sites re-path the whole clone afterwards — see
+    // repathInstance in Val.ts).
+    const childspec = spec?.mark || spec?.dup ?
+      { mark: spec?.mark, dup: spec?.dup } : {}
+    out.peg = this.peg.map((entry: Val) => entry.clone(ctx, childspec))
     return out
   }
 

package/src/val/KeyFuncVal.ts

@@ -12,7 +12,6 @@ import {
 } from '../ctx'
 
 import { StringVal } from '../val/StringVal'
-import { ConjunctVal } from '../val/ConjunctVal'
 
 
 
@@ -41,39 +40,13 @@ class KeyFuncVal extends FuncBaseVal {
   }
 
 
-  unify(peer: Val, ctx: AontuContext): Val {
-    // TODO: this delay makes keys in spreads and refs work, but it is a hack - find a better way.
-    let out: Val = this
-
-    if (ctx.cc < 3) {
-      this.notdone()
-
-      if (peer.isTop || (peer.id === this.id)) {
-        // TODO: clone needed to avoid triggering unify_cycle - find a better way
-        out = this.clone(ctx)
-      }
-      else if (peer.isNil) {
-        out = peer
-      }
-      else {
-        if (
-          peer.isKeyFunc
-          && peer.path.join('.') === this.path.join('.')
-          && peer.peg?.[0]?.peg === this.peg?.[0]?.peg
-        ) {
-          out = this
-        }
-        else {
-          out = new ConjunctVal({ peg: [this, peer] }, ctx)
-        }
-      }
-    }
-    else {
-      out = super.unify(peer, ctx)
-    }
-
-    return out
-  }
+  // `key()` is the first value to take THE STAGING RULE (G8 phase 0,
+  // see AontuContext.settle): its answer is a segment of its own path,
+  // so it must not answer while a spread, a reference or a `move` can
+  // still move it. It residuates until the model stops changing, and
+  // fires on the settle pass. The residuation itself is FuncBaseVal's,
+  // shared with the generation combinators.
+  staged = true
 
 
   resolve(ctx: AontuContext, _args: Val[]) {
@@ -113,7 +86,38 @@ class KeyFuncVal extends FuncBaseVal {
       }
     }
 
-    const key = this.path[this.path.length - (1 + move)] ?? ''
+    // THE PATH IS THE ONE IT IS BEING DRIVEN AT, not the one it
+    // remembers. `this.path` is a cache that the residuation clone
+    // refreshes each pass, and it is right for a key() the bag walk
+    // reaches directly -- but a key() nested inside a function or
+    // operator ARGUMENT is never reached that way: it is driven by its
+    // enclosing call, which re-paths nothing, so it kept the position
+    // the SOURCE TEXT put it at. Inside a template that is fatal: the
+    // source position of `&: {k: "x" + key()}` (or of `pack`'s
+    // template) is the template, not any of the destinations, and the
+    // parse-time path of a function argument is not a document
+    // position at all.
+    // A stored path is only usable if it IS one: a path segment that is
+    // not a key is not a position, and the parse-time path of a value
+    // written inside a function ARGUMENT carries exactly that -- the
+    // argument has no key, so its segment is not a string. Those values
+    // are also the ones the bag walk never re-paths (a call re-paths
+    // nothing it holds), which is why the stored path stays wrong
+    // forever rather than being refreshed on the next pass. For them
+    // the driving context is the only truth. For everything else the
+    // stored path stays authoritative, because a TRANSPLANTED value
+    // (move(), a shared clone) must answer for where it was put, not
+    // for whichever driver happened to reach it first.
+    let positioned = true
+    for (const seg of this.path) {
+      if ('string' !== typeof seg) {
+        positioned = false
+        break
+      }
+    }
+
+    const here = positioned ? this.path : ctx.path
+    const key = here[here.length - (1 + move)] ?? ''
     // console.log('KEY', this.path, move, key)
 
     out = new StringVal({ peg: key })