aontu 0.52.1 → 0.54.0

package/src/val/GraphAtomVal.ts

@@ -0,0 +1,264 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE GRAPH ATOMS (RELATIONS.0.md §3.3): `acyclic()` and
+// `inverse(name)`, conjoined at the same field as the `rel()` they
+// govern. Their model is the sizing atoms -- a property that cannot be
+// decided while information can still arrive is HELD during
+// unification and DECIDED at generation, where no more can.
+//
+// During unification they are lattice-inert: both properties are
+// global and non-monotone (one more edge can make an acyclic graph
+// cyclic), and the lattice guarantee -- more information never
+// falsifies what has been observed -- forbids a constraint that could
+// answer true and then false. So the atoms only RESIDUATE: they ride
+// the field through meets, dedup additively, appear in canon and reach
+// the `aon1-` hash, and REGISTER the declaration on the context. The
+// predicate they govern is the key they sit on, evaluation-global,
+// additive across declarations.
+//
+// The verdict lands at generation (relationVerdict,
+// ts/src/relation.ts) and is reported identically by the `relations`
+// verb -- one decision, two surfaces.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  DONE,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { FuncBaseVal } from './FuncBaseVal'
+import { FeatureVal } from './FeatureVal'
+import { unite } from '../unify'
+import { propagateMarks } from '../utility'
+
+
+// The declarations one evaluation accumulates: predicate -> what its
+// atoms said. Additive, exactly as two statements of one map are. The
+// map lives on the CONTEXT (created in the constructor, like the
+// _depth box), so every clone shares one registry.
+export type RelDecl = {
+  acyclic?: boolean
+  inverses: Set<string>
+}
+
+export function relDecls(ctx: any): Map<string, RelDecl> {
+  return ctx._reldecls
+}
+
+
+class GraphAtomVal extends FeatureVal {
+  isGraphAtom = true
+  isGenable = true
+  // AFTER rel() (45000): the atoms say nothing about the value.
+  cjo = 46000
+
+  akind: 'acyclic' | 'inverse'
+  invname?: string
+  // The value the atom rides on -- the sizing-constraint shape: the
+  // atom ABSORBS its fold neighbours (the rel, the container, another
+  // atom) and carries them, so the fold's pairwise walk still merges
+  // the value across it. Absent until the atom meets one.
+  held?: Val
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+    this.akind = (spec as any).akind ?? 'acyclic'
+    this.invname = (spec as any).invname
+    this.held = (spec as any).held
+    // A settled residual, like an unmet rel(): the bare atom is its
+    // own value, and a type() body carrying one must settle. Holding
+    // an unsettled value, it is exactly as done as the value.
+    this.dc = undefined === this.held || true === this.held.done
+      ? DONE : 0
+  }
+
+  clone(ctx: AontuContext, spec?: ValSpec): Val {
+    const out: any = super.clone(ctx, spec)
+    out.akind = this.akind
+    out.invname = this.invname
+    out.held = this.held
+    out.dc = this.dc
+    return out
+  }
+
+  // A rebuilt atom around a new held, at this atom's position.
+  private carry(ctx: AontuContext, held: Val): Val {
+    const out: any = new GraphAtomVal(
+      { akind: this.akind, invname: this.invname, held } as any, ctx)
+    propagateMarks(this, out)
+    out.site = this.site
+    out.path = this.path
+    return out
+  }
+
+  // The predicate is the key the atom sits on -- and a predicate is a
+  // D-1 NAME, by exactly fieldkey's rule: an atom landed anywhere
+  // else declares nothing. Registration is idempotent (the
+  // declaration set is a set) and happens at every drive, so
+  // whichever pass first sees the atom at its landed position records
+  // it.
+  register(ctx: AontuContext): void {
+    const seg = this.path[this.path.length - 1]
+    if ('string' !== typeof seg || !GRAPH_ATOM_NAME.test(seg)) {
+      return
+    }
+    const decls = relDecls(ctx)
+    let d = decls.get(seg)
+    if (undefined === d) {
+      d = { inverses: new Set() }
+      decls.set(seg, d)
+    }
+    if ('acyclic' === this.akind) {
+      d.acyclic = true
+    }
+    else if (undefined !== this.invname) {
+      d.inverses.add(this.invname)
+    }
+  }
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const p: any = peer
+    this.register(ctx)
+
+    // The self-drive: unite's tail calls unify(top) directly on any
+    // not-done result, and the held is what still has work to do.
+    // (A null/nil peer never arrives -- unite's ladder absorbs both.)
+    if (null == peer || true === p.isTop) {
+      if (undefined === this.held) {
+        return this
+      }
+      if (true === this.held.done) {
+        // Doneness is monotone, so recording it in place is safe --
+        // and without it the bag walk keeps asking and generation
+        // refuses a finished value.
+        this.dc = DONE
+        return this
+      }
+      // The self-drive refines IN PLACE (the MapVal top-peer
+      // pattern): a fresh atom per pass changes object identity, so
+      // spread apply-once stamps and the entity merge's fast paths
+      // stop holding, and the enclosing bags re-open every pass --
+      // the service catalog never converged.
+      const held = unite(ctx, this.held, undefined, 'atom-drive')
+      if (true === held.isNil) {
+        return held
+      }
+      this.held = held
+      if (true === held.done) {
+        this.dc = DONE
+      }
+      return this
+    }
+
+    // The SAME declaration twice is one declaration; their helds
+    // merge.
+    if (true === p.isGraphAtom &&
+      p.akind === this.akind && p.invname === this.invname) {
+      const held = undefined === this.held ? p.held
+        : undefined === p.held ? this.held
+          : unite(ctx, this.held, p.held, 'atom-dup')
+      if (undefined !== held && true === held.isNil) {
+        return held
+      }
+      return undefined === held ? this : this.carry(ctx, held)
+    }
+
+    // Anything else -- the rel, the container, a different atom -- is
+    // ABSORBED: the atom carries the value and the fold's pairwise
+    // walk merges across it.
+    const held = undefined === this.held ? peer
+      : unite(ctx, this.held, peer, 'atom-held')
+    return true === held.isNil ? held : this.carry(ctx, held)
+  }
+
+  get canon(): string {
+    const own = 'acyclic' === this.akind
+      ? 'acyclic()'
+      : 'inverse(' + JSON.stringify(this.invname) + ')'
+    return undefined === this.held ? own : this.held.canon + '&' + own
+  }
+
+  gen(ctx: AontuContext) {
+    // The atom is transparent at generation -- its verdict is global
+    // (relationVerdict), never a value at this field -- and a BARE
+    // atom is silent, exactly as an unmet rel() is.
+    return undefined === this.held ? undefined : this.held.gen(ctx)
+  }
+}
+
+
+// D-1 (docs/design/RELATIONS.0.md): the name grammar shared by entity
+// names, edge predicates and inverse names.
+const GRAPH_ATOM_NAME = /^[_a-zA-Z][-_a-zA-Z0-9]*$/
+
+
+class AcyclicFuncVal extends FuncBaseVal {
+  isAcyclicFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new AcyclicFuncVal(spec)
+  }
+
+  funcname() {
+    return 'acyclic'
+  }
+
+  resolve(ctx: AontuContext, _args: Val[]) {
+    const out: any = new GraphAtomVal({ akind: 'acyclic' } as any, ctx)
+    out.site = this.site
+    out.path = this.path
+    return out
+  }
+}
+
+
+class InverseFuncVal extends FuncBaseVal {
+  isInverseFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new InverseFuncVal(spec)
+  }
+
+  funcname() {
+    return 'inverse'
+  }
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const a: any = args[0]
+    // The mirroring predicate is a NAME -- D-1, spelled bare or
+    // quoted. A relation is a vocabulary term, not an address.
+    if (true !== a?.isScalar || 'string' !== typeof a.peg
+      || !GRAPH_ATOM_NAME.test(a.peg)) {
+      return makeNilErr(ctx, 'inverse_name', this, undefined, 'inverse')
+    }
+    const out: any = new GraphAtomVal(
+      { akind: 'inverse', invname: a.peg } as any, ctx)
+    out.site = this.site
+    out.path = this.path
+    return out
+  }
+} /* node:coverage ignore next 7 */
+
+
+export {
+  GraphAtomVal,
+  AcyclicFuncVal,
+  InverseFuncVal,
+}

package/src/val/HideFuncVal.ts

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

package/src/val/JunctionVal.ts

@@ -33,7 +33,30 @@ 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 } : {}))
+    // A JUNCTION'S MEMBERS SIT AT THE JUNCTION'S OWN POSITION. That is
+    // the rule `repathInstance` (Val.ts) states for the instance walk
+    // -- a conjunct's members occupy the conjunct's position, which is
+    // what `A & B` means -- and it holds for every clone, not only for
+    // marked ones.
+    //
+    // Val.clone's ctx cut cannot derive it: MapVal.clone hands a child
+    // its path through the SPEC rather than by descending the ctx, so
+    // a member left to the cut takes the DRIVING context's path -- the
+    // map's -- and loses the field key it sits under. A conjunct
+    // member reached through a reference into a position at least as
+    // deep as its definition then carried the entity's path, and every
+    // reader of `Val.path` was told the wrong position: a rel()-minted
+    // link took the ENTITY's key as its predicate, so `inverse(n)`
+    // looked for a mirror under a relation nobody declared and
+    // reported a written mirror missing.
+    //
+    // The instantiation flag still descends with the mark (ADR-005).
+    // Go states the same invariant directly (go/clone.go, cloneAt), so
+    // this restores parity rather than inventing a behaviour.
+    const childspec: any = spec?.mark || spec?.dup ?
+      { mark: spec?.mark, dup: spec?.dup, path: out.path }
+      : { path: out.path }
+    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 })

package/src/val/ListVal.ts

@@ -17,6 +17,7 @@ import { unite } from '../unify'
 
 import {
   propagateMarks,
+  canonRiders,
   explainOpen,
   ec,
   explainClose,
@@ -32,6 +33,8 @@ import {
 import { ConjunctVal } from './ConjunctVal'
 import { NilVal } from './NilVal'
 import { BagVal } from './BagVal'
+import { repathInstance, spreadId } from './Val'
+import { markSpread } from '../provenance'
 
 
 class ListVal extends BagVal {
@@ -55,7 +58,10 @@ class ListVal extends BagVal {
     if (spread) {
       if ('&' === spread.o) {
 
-        // TODO: handle existing spread!
+        // Multiple same-level spreads conjoin; an unequal spread from
+        // another statement meets this one in unify's combination
+        // below (see the MapVal constructor note — the combined
+        // template is stateless, BUGS.md §6-§7).
         this.spread.cj =
           Array.isArray(spread.v) ?
             1 < spread.v.length ?
@@ -73,6 +79,12 @@ class ListVal extends BagVal {
   // NOTE: order of keys is not preserved!
   // not possible in any case - consider {a,b} unify {b,a}
   unify(peer: Val, ctx: AontuContext): Val {
+    // A rel() peer drives: the relation constraint rewrites this list
+    // leaf by leaf (RELATIONS.0.md §3.2); see the twin arm in MapVal.
+    if (true === (peer as any)?.isRel) {
+      return (peer as any).unify(this, ctx)
+    }
+
     const TOP = top()
     peer = peer ?? TOP
 
@@ -86,6 +98,19 @@ class ListVal extends BagVal {
       return peer.unify(this, ctx)
     }
 
+    // A DISJUNCT ALTERNATIVE MATCHES ITS OWN LENGTH (BUGS.md §52
+    // regime 4, the X-C3 adjudication): in a trial, a literal list
+    // with no spread admits only a peer list of the same length -- a
+    // spread makes it variadic. Outside trials the ordinary
+    // elementwise merge stands (two statements of one list are one
+    // list), so `[] | [&: T]` stops admitting every list through the
+    // empty arm while `a: [] a: [1]` still merges.
+    if (true === ctx._trialMode && true === (peer as any).isList
+      && null == this.spread.cj && null == (peer as any).spread.cj
+      && this.peg.length !== (peer as any).peg.length) {
+      return makeNilErr(ctx, 'list_length', this, peer)
+    }
+
     const te = ctx.explain && explainOpen(ctx, ctx.explain, 'List', this, peer)
     let done: boolean = true
     let exit = false
@@ -124,21 +149,63 @@ class ListVal extends BagVal {
       // Always unify children first
       for (let key in this.peg) {
         const keyctx = ctx.descend(key)
-        const key_spread_cj = spread_cj.spreadClone(keyctx)
         const child = this.peg[key]
 
         propagateMarks(this, child)
 
-        // child is non-nullish: propagateMarks above dereferences it.
-        out.peg[key] =
-          child.isNil ? child :
-              key_spread_cj.isNil ? key_spread_cj :
-                key_spread_cj.isTop && child.done ? child :
-                  child.isTop && key_spread_cj.done ? key_spread_cj :
-                    unite(te ? keyctx.clone({ explain: ec(te, 'PEG:' + key) }) : keyctx,
-                      child, key_spread_cj, 'list-own')
+        // APPLIED ONCE PER ELEMENT, the guard MapVal has carried since
+        // the spread was written: an element that already holds this
+        // template's contribution is progressed by self-unification
+        // instead of having the template met into it a second time.
+        // Re-applying is the identity for a template that has already
+        // RESOLVED, which is why the missing guard went unnoticed here
+        // — but a template that residuates (`&: {k: key(1)}`, G8 phase
+        // 0) is not yet a value to be idempotent about, so each pass
+        // conjoined another copy and the element's canon DOUBLED per
+        // pass. The old `ctx.cc < 3` key delay hid it by ending the
+        // growth at three passes; the staging rule waits for the model
+        // to settle, and a model whose canon doubles every pass never
+        // does.
+        let oval: Val
+        if (!spread_cj.isTop
+          && (child as any)._spr === spreadId(spread_cj)) {
+          oval = child.done ? child :
+            unite(te ? keyctx.clone({ explain: ec(te, 'PEG:' + key) }) : keyctx,
+              child, TOP, 'list-own')
+          ; (oval as any)._spr = spreadId(spread_cj)
+        }
+        else {
+          const key_spread_cj = spread_cj.spreadClone(keyctx)
+          // The spread mark the provenance recorder reads (G7 phase 3),
+          // as in MapVal: this is where a template becomes a per-element
+          // contribution. Instrumented runs only.
+          if (undefined !== keyctx.prov) {
+            markSpread(key_spread_cj)
+          }
 
-        done = (done && DONE === out.peg[key].dc)
+          // child is non-nullish: propagateMarks above dereferences it.
+          oval =
+            child.isNil ? child :
+                key_spread_cj.isNil ? key_spread_cj :
+                  // The no-op meet is SKIPPED on the normal path (it is the
+                  // identity) but TAKEN while recording: a value written once
+                  // and never met is still a contribution the author wants
+                  // pointed at, and the Go port's unite sees that meet (G7
+                  // phase 4). Instrumented runs pay knowingly.
+                  key_spread_cj.isTop && child.done && undefined === keyctx.prov
+                    ? child :
+                    child.isTop && key_spread_cj.done ? key_spread_cj :
+                      unite(te ? keyctx.clone({ explain: ec(te, 'PEG:' + key) }) : keyctx,
+                        child, key_spread_cj, 'list-own')
+
+          if (!spread_cj.isTop && !oval.isNil) {
+            ; (oval as any)._spr = spreadId(spread_cj)
+          }
+        }
+
+        out.peg[key] = oval
+
+        done = (done && DONE === oval.dc)
       }
 
       const allowedKeys: string[] = this.closed ? Object.keys(this.peg) : []
@@ -171,6 +238,9 @@ class ListVal extends BagVal {
 
           if (this.spread.cj) {
             let key_spread_cj = spread_cj.spreadClone(peerctx)
+            if (undefined !== peerctx.prov) {
+              markSpread(key_spread_cj)
+            }
 
             oval = out.peg[peerkey] =
               unite(te ? peerctx.clone({ explain: ec(te, 'PSP:' + peerkey) }) : peerctx,
@@ -182,6 +252,12 @@ class ListVal extends BagVal {
           done = (done && DONE === oval.dc)
         }
       }
+      else if (true === (peer as any).isContainerKind) {
+        // The container KIND delegates to its own arm, exactly as a
+        // scalar delegates to a ScalarKindVal peer (MapVal has the
+        // same arm).
+        out = peer.unify(this, ctx) as any
+      }
       else if (!peer.isTop) {
         out = makeNilErr(ctx, 'list', this, peer)
       }
@@ -226,7 +302,11 @@ class ListVal extends BagVal {
     }
 
     if (!allScalarKind) {
-      return this.clone(ctx)
+      // A full instance (`dup`, ADR-005), paths normalised to the
+      // destination: see Val.spreadClone and repathInstance.
+      const out = this.clone(ctx, { dup: true })
+      repathInstance(out, out.path)
+      return out
     }
 
     let out = (super.clone(ctx) as ListVal)
@@ -249,12 +329,16 @@ class ListVal extends BagVal {
 
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     let out = (super.clone(ctx, spec) as ListVal)
+    // The instantiation flag descends with the mark (ADR-005): a
+    // template's elements are part of the instance.
+    const childspec = spec?.mark || spec?.dup ?
+      { 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, spec?.mark ? { mark: spec.mark } : {}) : entry[1]
+        (entry[1] as any)?.isVal ? (entry[1] as Val).clone(ctx, childspec) : entry[1]
     }
     if (this.spread.cj) {
-      out.spread.cj = this.spread.cj.clone(ctx, spec?.mark ? { mark: spec.mark } : {})
+      out.spread.cj = this.spread.cj.clone(ctx, childspec)
     }
 
     out.closed = this.closed
@@ -280,7 +364,9 @@ class ListVal extends BagVal {
       // key. The Go port's ListVal.Canon has no such arm either, and the
       // two canons must agree -- a canon is round-trippable, and a marker
       // on an element the grammar cannot produce would not reparse.
-      keys.map(k => this.peg[k].canon).join(',') +
+      // canonRiders, not .canon: a deprecated element renders
+      // back as its `deprecate(x, m)` call, reparseably (G3).
+      keys.map(k => canonRiders(this.peg[k])).join(',') +
       ']'
   }
 } /* node:coverage ignore next 8 */

package/src/val/LowerFuncVal.ts

@@ -13,7 +13,6 @@ import {
 import { makeNilErr } from '../err'
 
 
-import { NilVal } from '../val/NilVal'
 import { ScalarKindVal } from '../val/ScalarKindVal'
 import { makeScalarLike } from '../val/valutil'
 import { Decimal } from '../val/Decimal'