aontu 0.53.0 → 0.55.0

package/src/val/RecurseVal.ts

@@ -0,0 +1,285 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE RECURSIVE RESIDUAL (docs/design/RECURSION.0.md): where RefVal's
+// prefix test used to answer `path_cycle` for a self-reference --
+// `$.Node` written anywhere inside `Node` -- it now answers this
+// value: a deferred reference carrying the target path, exactly as a
+// constraint atom carries its bound. No new syntax: the reference the
+// author wrote simply MEANS the fixpoint.
+//
+// The three moments of every residual:
+//
+// - At unification, EXPAND ONE LEVEL PER MEET WITH STRUCTURE: met by
+//   a map, list, or scalar, the residual clones the schema body one
+//   level -- per destination, under ADR-005's clone discipline -- and
+//   unifies the clone with the peer. The clone's own self-reference
+//   is again this residual, so each expansion consumes one level of
+//   concrete data; data is finite, so expansion terminates
+//   (structural descent), with the depth budget as the backstop
+//   (recursion_budget).
+// - In canon and the aon1- hash, SYMBOLIC: the residual prints as the
+//   reference the author wrote, so a recursive schema's canon is
+//   finite and round-trips, and the hash pins the mu-form rather than
+//   any unrolling.
+// - At generation, an unexpanded residual REFUSES with
+//   recursion_unexpanded. Guardedness is therefore EMERGENT: under
+//   `next?:` the refusal is isolated and the optional key drops;
+//   under `*null | $.Node` the preference generates; a REQUIRED
+//   recursive field with no data refuses at the instance.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  DONE,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { FeatureVal } from './FeatureVal'
+import { ConjunctVal } from './ConjunctVal'
+import { unite } from '../unify'
+import { propagateMarks, walk } from '../utility'
+
+
+class RecurseVal extends FeatureVal {
+  isRecurse = true
+  isGenable = true
+  // LAST in a conjunct fold, after even the graph atoms: the residual
+  // wants to see the assembled concrete structure it expands against.
+  cjo = 47000
+
+  // The target path, absolute from the root, as the reference spelled
+  // it.
+  target: string[]
+  // Expansion depth so far along this chain, charged against the
+  // depth budget (the T-1 backstop).
+  xc: number
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+    this.target = (spec as any).target ?? []
+    this.xc = (spec as any).xc ?? 0
+    // A settled residual: a type() body carrying one must settle, and
+    // an unmet recursion is its own value until data arrives.
+    this.dc = DONE
+  }
+
+  clone(ctx: AontuContext, spec?: ValSpec): Val {
+    const out: any = super.clone(ctx, spec)
+    out.target = this.target
+    out.xc = this.xc
+    return out
+  }
+
+  // The schema body the target names, from the ROOT: the fixpoint is
+  // over the finished definition, and the definition's own residual
+  // keeps it finite. When the root does not contain the target -- the
+  // residual was LIFTED out of its defining tree, as vet's anchored
+  // meet does -- fall back to ctx._fixroot, the settled tree the
+  // lifter kept for exactly this walk.
+  private body(ctx: AontuContext): Val | undefined {
+    return walkTarget(ctx.root, this.target)
+      ?? walkTarget((ctx as any)._fixroot, this.target)
+  }
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const p: any = peer
+
+    // The self-drive: nothing to advance -- the residual waits for
+    // structure. (A null/nil peer never arrives; unite's ladder
+    // absorbs both.)
+    if (null == peer || true === p.isTop) {
+      return this
+    }
+
+    // The same fixpoint twice is one fixpoint.
+    if (true === p.isRecurse) {
+      if (this.target.length === p.target.length
+        && this.target.every((s, i) => s === p.target[i])) {
+        return this
+      }
+      // Different targets -- mutual recursion meeting -- are BOTH
+      // held: each expands as data arrives, through the fold that
+      // keeps a conjunct's members separate.
+      const out = new ConjunctVal({ peg: [this, peer] }, ctx)
+      propagateMarks(this, out)
+      out.path = this.path
+      return out
+    }
+
+    // CONCRETE STRUCTURE: expand one level against it.
+    if (true === p.isMap || true === p.isList || true === p.isScalar) {
+      if (ctx.budget.depth <= this.xc) {
+        return makeNilErr(ctx, 'recursion_budget', this, peer, 'recurse',
+          { target: '$.' + this.target.join('.') })
+      }
+      const body = this.body(ctx)
+      if (undefined === body) {
+        // The definition has not assembled yet (an early pass): hold
+        // the peer beside the residual and try again when it has.
+        const out = new ConjunctVal({ peg: [this, peer] }, ctx)
+        propagateMarks(this, out)
+        out.path = this.path
+        return out
+      }
+      // ADR-005's clone discipline: the expansion is a per-destination
+      // instantiation, so the definition itself is never written
+      // into. The clone's type/hide marks are CLEARED at every depth,
+      // exactly as a plain reference copy clears them (concreteFlow's
+      // rule): the schema is hidden, the instances it expands into
+      // are the output.
+      // The clone is REBASED to the DRIVE path explicitly (spec.path;
+      // the Go twin passes cp(r.path), whose stored paths its clone
+      // arms keep clean): the default rebase slices the definition's
+      // path by the destination's length, which leaks definition
+      // segments into instance paths whenever the destination is
+      // shallower -- a residual carried inside a copied definition
+      // body (`chain: $.spec.Step` inside Policy, copied to a slot
+      // shallower than the definition) reported
+      // `$.payments_policy.Policy.chain.then.approver` for the
+      // finding Go placed at `$.payments_policy.chain.then.approver`.
+      // The drive path is also right under vet's anchored meet, which
+      // drives AT the anchor's own path (see vet.ts), so anchored
+      // findings land in the schema's namespace in both ports.
+      const level: any = body.clone(ctx, {
+        dup: true, path: [...ctx.path],
+      } as any)
+      walk(level, (_key: string | number | undefined, v: Val) => {
+        v.mark.type = false
+        v.mark.hide = false
+        return v
+      })
+      bumpRecurse(level, this.xc + 1)
+      return unite(ctx, level, peer, 'recurse-expand')
+    }
+
+    // Anything else -- a func still resolving, a reference, a
+    // constraint -- waits beside the residual.
+    const out = new ConjunctVal({ peg: [this, peer] }, ctx)
+    propagateMarks(this, out)
+    out.path = this.path
+    return out
+  }
+
+  get canon(): string {
+    return '$.' + this.target.join('.')
+  }
+
+  gen(ctx: AontuContext) {
+    // An unexpanded residual in a demanded position refuses;
+    // guardedness is emergent -- under an optional key the bag's
+    // isolated context swallows this and drops the key.
+    makeNilErr(ctx, 'recursion_unexpanded', this, undefined, 'recurse',
+      { target: '$.' + this.target.join('.') })
+    return undefined
+  }
+}
+
+
+// walkTarget descends a tree by the residual's absolute target path,
+// answering the definition node or undefined.
+function walkTarget(root: any, target: string[]): Val | undefined {
+  let node: any = root
+  for (const seg of target) {
+    node = node?.peg?.[seg]
+  }
+  return null != node && true === node.isVal ? node : undefined
+}
+
+
+// bumpRecurse stamps the expansion depth onto every residual inside a
+// freshly cloned level, so descent is charged along the chain.
+function bumpRecurse(v: any, xc: number): void {
+  if (null == v || true !== v.isVal) {
+    return
+  }
+  if (true === v.isRecurse) {
+    v.xc = Math.max(v.xc, xc)
+    return
+  }
+  const peg: any = v.peg
+  if (true === v.isMap && null != peg) {
+    for (const k of Object.keys(peg)) {
+      bumpRecurse(peg[k], xc)
+    }
+  }
+  else if (true === v.isList && Array.isArray(peg)) {
+    for (const e of peg) {
+      bumpRecurse(e, xc)
+    }
+  }
+  else if (true === v.isConjunct && Array.isArray(peg)) {
+    for (const e of peg) {
+      bumpRecurse(e, xc)
+    }
+  }
+  if (null != v.spread?.cj) {
+    bumpRecurse(v.spread.cj, xc)
+  }
+}
+
+
+// containsRecurseOf answers whether a definition holds a residual of
+// the given target -- i.e. the definition is (transitively) the
+// fixpoint that target names. A reference RESOLVING to such a
+// definition must itself answer the residual: cloned instead, every
+// reparse of a canon unrolled the schema one more level and canon
+// never converged.
+function containsRecurseOf(v: any, target: string[], depth?: number): boolean {
+  const d = depth ?? 0
+  if (null == v || true !== v.isVal || 8 < d) {
+    return false
+  }
+  if (true === v.isRecurse) {
+    return v.target.length === target.length
+      && v.target.every((s: string, i: number) => s === target[i])
+  }
+  // A RAW REFERENCE to the target IS the recursion, minted or not:
+  // the answer must not depend on whether the definition's own
+  // prefix position has been visited yet. Without this arm the
+  // answer was ORDER-DEPENDENT -- reparsing a generated canon puts
+  // the instance before the definition, its trailing `$.spec.Step`
+  // leaves resolved before `Step.then` had minted, and each resolve
+  // cloned one more unrolled level until the unify depth guard
+  // (unify_cycle) killed the document.
+  if (true === v.isRef && Array.isArray(v.peg)) {
+    if (v.peg.length === target.length
+      && v.peg.every((s: any, i: number) => s === target[i])) {
+      return true
+    }
+  }
+  const peg: any = v.peg
+  if (true === v.isMap && null != peg) {
+    for (const k of Object.keys(peg)) {
+      if (containsRecurseOf(peg[k], target, d + 1)) {
+        return true
+      }
+    }
+  }
+  else if ((true === v.isList || true === v.isConjunct || true === v.isDisjunct)
+    && Array.isArray(peg)) {
+    for (const e of peg) {
+      if (containsRecurseOf(e, target, d + 1)) {
+        return true
+      }
+    }
+  }
+  if (null != v.spread?.cj && containsRecurseOf(v.spread.cj, target, d + 1)) {
+    return true
+  }
+  return false
+} /* node:coverage ignore next 7 */
+
+
+export {
+  RecurseVal,
+  bumpRecurse,
+  containsRecurseOf,
+}

package/src/val/RefVal.ts

@@ -22,6 +22,7 @@ import {
 import { AontuContext } from '../ctx'
 
 import { makeNilErr } from '../err'
+import { RecurseVal, containsRecurseOf } from './RecurseVal'
 import { unite } from '../unify'
 
 
@@ -279,15 +280,36 @@ class RefVal extends FeatureVal {
     // let descent = ''
 
     if (isprefixpath) {
-      // console.log('SELFPATH', selfpath, 'PEGPATH', pegpath)
-      out = makeNilErr(ctx, 'path_cycle', this)
+      // THE DETECTOR'S ANSWER IS A RESIDUAL (RECURSION.0.md): a
+      // self-reference under a guarded shape is the fixpoint the
+      // author wrote, so the prefix hit mints the recursive residual
+      // instead of refusing -- except the degenerate all-empty
+      // spelling (path("")), which names nothing and keeps its
+      // path_cycle. Only all-string paths recurse; anything else
+      // keeps the conservative refusal.
+      let degenerate = 0 === this.path.length
+      let target: string[] = []
+      for (let i = 0; i < this.peg.length && !degenerate; i++) {
+        if ('string' !== typeof this.peg[i] || '' === this.peg[i]) {
+          degenerate = true
+          break
+        }
+        target.push(this.peg[i] as string)
+      }
+      if (degenerate) {
+        out = makeNilErr(ctx, 'path_cycle', this)
+      }
+      else {
+        const rec: any = new RecurseVal({ target } as any, ctx)
+        rec.site = this.site
+        rec.path = [...this.path]
+        out = rec
+      }
     }
     else {
 
       let parts: string[] = []
 
-      let modes: string[] = []
-
       for (let pI = 0; pI < this.peg.length; pI++) {
         let part = this.peg[pI]
         // An unspellable segment MISSES BEFORE ANY LOOKUP. The marker
@@ -301,38 +323,13 @@ class RefVal extends FeatureVal {
           return makeNilErr(ctx, 'no_path', this)
         }
         if (part instanceof VarVal) {
-          let strval = (part as VarVal).peg
-          let name = strval ? '' + strval.peg : ''
-
-          if ('KEY' === name) {
-            if (pI === this.peg.length - 1) {
-              modes.push(name)
-            }
-            else {
-              // TODO: return a Nil explaining error
-              return
-            }
-          }
-
-          if ('SELF' === name) {
-            if (pI === 0) {
-              modes.push(name)
-            }
-            else {
-              // TODO: return a Nil explaining error
-              return
-            }
-          }
-          else if ('PARENT' === name) {
-            if (pI === 0) {
-              modes.push(name)
-            }
-            else {
-              // TODO: return a Nil explaining error
-              return
-            }
-          }
-          else if (0 === modes.length) {
+          // EVERY `$name` IN A PATH IS AN ORDINARY VARIABLE. `$KEY`,
+          // `$SELF` and `$PARENT` used to be intercepted here by name;
+          // they are gone (ADR-009). `key()` is the replacement for
+          // `$KEY` and answers where a value LANDS rather than where it
+          // was written, `$SELF.x` was only ever `$.x`, and `$PARENT.x`
+          // was only ever `.x`.
+          {
             part = (part as VarVal).unify(top(), ctx)
             if (part.isNil) {
               // TODO: var not found, so can't find path
@@ -367,15 +364,9 @@ class RefVal extends FeatureVal {
         refpath = parts
       }
       else {
-        // TODO: deprecate $KEY, etc
-        refpath = this.path.slice(
-          0,
-          (
-            modes.includes('SELF') ? 0 :
-              modes.includes('PARENT') ? -1 :
-                -1 // siblings
-          )
-        ).concat(parts)
+        // A relative reference reads from the SIBLING scope: drop this
+        // node's own key and append the written segments.
+        refpath = this.path.slice(0, -1).concat(parts)
       }
 
       let sep = '.'
@@ -383,29 +374,6 @@ class RefVal extends FeatureVal {
         .reduce(((a: string[], p: string) =>
           (p === sep ? a.length = a.length - 1 : a.push(p), a)), [])
 
-      if (modes.includes('KEY')) {
-        // STRINGIFY. A LIST index arrives here as a JS NUMBER (jsonic puts
-        // it in the path as one, and lang.ts copies the path wholesale),
-        // so `.$KEY` inside a list built a StringVal whose peg was the
-        // number 0 -- an ill-formed value, not a design choice: it canoned
-        // as a bare 0, generated a JSON number, satisfied `number` and
-        // failed `string`. Go stringifies, and key() already agreed with
-        // Go, so this port disagreed with itself.
-        //
-        // Coerced HERE, at the consumption site, rather than by
-        // normalising Val.path: the numeric segment originates in jsonic's
-        // own r.k.path and every other path consumer (find's descent,
-        // key(), the clone/spread machinery) already handles it.
-        let key = this.path[this.path.length - 2]
-        let sv = new StringVal({ peg: null == key ? '' : '' + key }, ctx)
-
-        // TODO: other props?
-        sv.dc = DONE
-        sv.path = this.path
-
-        return sv
-      }
-
       let node = ctx.root as Val
 
       let nopath = false
@@ -423,6 +391,21 @@ class RefVal extends FeatureVal {
           else if (node.isList) {
             node = node.peg[part]
           }
+          // A PENDING MARK WRAPPER IS TRANSPARENT TO THE WALK: hide()
+          // and type() only mark, and their argument is the structure
+          // the path names. Without this, two sibling schemas in one
+          // hide() bag deadlock -- the wrapper waits for its argument,
+          // the argument's members wait for references that walk into
+          // the unresolved wrapper (BUGS.md §53's family; the
+          // recursive Policy/Step pair found it again). The found node
+          // is cloned and mark-cleared exactly as any reference target
+          // is, and the wrapper still marks its own field.
+          else if (true === (node as any).isFunc
+            && ((node as any).isHideFunc || (node as any).isTypeFunc)
+            && (true === (node as any).peg?.[0]?.isMap
+              || true === (node as any).peg?.[0]?.isList)) {
+            node = (node as any).peg[0].peg[part]
+          }
           else if (node.done) {
             nopath = true
             break;
@@ -439,8 +422,41 @@ class RefVal extends FeatureVal {
         }
       }
 
-      // console.log('REFPATH', ctx.cc, pI, refpath, nopath, ctx.root, node)
-
+      // THE ANCHORED-MEET FALLBACK (vet --at): an absolute reference
+      // inside a lifted subtree names the SCHEMA's namespace, and the
+      // meet's root does not contain it. The settled schema root the
+      // lifter kept (AontuContext._fixroot; see RecurseVal.body) is
+      // the tree such a reference means. Without this, a recursion
+      // re-entering through a list spread died as no_path at the
+      // first element under vet --at, while the map-tail form (whose
+      // residual was minted during schema settling) worked; the Go
+      // port answers the anchored meet from settled structures and
+      // never sees the gap.
+      const fixroot: any = (ctx as any)._fixroot
+      if (this.absolute && null != fixroot
+        && (nopath || pI !== refpath.length)) {
+        nopath = false
+        pI = 0
+        let fnode: any = fixroot
+        for (; pI < refpath.length; pI++) {
+          const part = refpath[pI]
+          if (true === fnode.isMap || true === fnode.isList) {
+            fnode = fnode.peg[part]
+          }
+          else {
+            break
+          }
+          if (null == fnode) {
+            break
+          }
+        }
+        if (null != fnode && pI === refpath.length) {
+          node = fnode
+        }
+        else {
+          nopath = true
+        }
+      }
 
       if (nopath) {
         out = makeNilErr(ctx, 'no_path', this)
@@ -494,6 +510,18 @@ class RefVal extends FeatureVal {
           !out.done) {
           out = undefined
         }
+        // A REFERENCE TO A RECURSIVE DEFINITION IS THE FIXPOINT
+        // REFERENCE (RECURSION.0.md): resolving it to a clone
+        // unrolled the schema one level, and every reparse of a
+        // canon then unrolled one more -- canon never converged. The
+        // residual is the resolved form, exactly as at the prefix
+        // positions inside the definition.
+        else if (null != out && !snap && containsRecurseOf(out, this.peg as any)) {
+          const rec: any = new RecurseVal({ target: [...this.peg] } as any, ctx)
+          rec.site = this.site
+          rec.path = [...this.path]
+          out = rec
+        }
         // Types and hidden values are cloned and made concrete
         else if (null != out) { //  && (out.mark.type || out.mark.hide)) {
 
@@ -522,19 +550,12 @@ class RefVal extends FeatureVal {
           walk(out, (_key: string | number | undefined, val: Val) => {
             val.mark.type = false
             val.mark.hide = false
-            // REFERENCES DO NOT CARRY IDENTITY (G4 phase 1, clearing
-            // rule 1). The clone is a copy of an entity, not the
-            // entity: without this, `w:b:$.q.a & {y:2,z:3}` (row
-            // `ref-and-merge`, test/spec/ref.tsv) would push `y:2`
-            // back into `q.a` through the identity merge — pinned
-            // behaviour, silently changed by a mark the author never
-            // wrote at the reference site.
-            //
-            // The LINK is NOT cleared (G4 phase 3): an identity says
-            // what a value IS, so a copy must not be that entity; a
-            // link says what a value POINTS AT, and a copy of a link
-            // points at the same thing.
-            val.entity = undefined
+            // 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
           })
           //}
@@ -719,5 +740,6 @@ class RefVal extends FeatureVal {
 
 
 export {
+  pendingMarkWrapper,
   RefVal,
 }