aontu 0.53.0 → 0.55.0

package/src/val/JunctionVal.ts

@@ -33,12 +33,29 @@ abstract class JunctionVal extends FeatureVal {
 
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     let out = (super.clone(ctx, spec) as JunctionVal)
-    // 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 } : {}
+    // 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/ListVal.ts

@@ -18,7 +18,6 @@ import { unite } from '../unify'
 import {
   propagateMarks,
   canonRiders,
-  constantIdFunc,
   explainOpen,
   ec,
   explainClose,
@@ -34,7 +33,7 @@ import {
 import { ConjunctVal } from './ConjunctVal'
 import { NilVal } from './NilVal'
 import { BagVal } from './BagVal'
-import { repathInstance } from './Val'
+import { repathInstance, spreadId } from './Val'
 import { markSpread } from '../provenance'
 
 
@@ -70,22 +69,6 @@ class ListVal extends BagVal {
               spread.v[0] :
             spread.v
 
-        // Clearing rule 3 (G4 phase 1): a CONSTANT id in the template
-        // would declare every child to be one entity. The refusal
-        // replaces the template, so it reaches every child and the
-        // bag itself (see the isNil arm where the spread is applied)
-        // as ONE nil identity — made here, once, rather than per
-        // pass, so the report names it once.
-        const idfn: any = constantIdFunc(this.spread.cj)
-        if (undefined !== idfn) {
-          const nil: any = new NilVal({ why: 'id_spread' }, ctx)
-          nil.site.row = idfn.site.row
-          nil.site.col = idfn.site.col
-          nil.site.url = idfn.site.url
-          nil.primary = idfn
-          this.spread.cj = nil
-        }
-
         // let tmv = Array.isArray(spread.v) ? spread.v : [spread.v]
         // this.spread.cj = new ConjunctVal({ peg: tmv }, ctx)
       }
@@ -96,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
 
@@ -109,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
@@ -144,21 +146,6 @@ class ListVal extends BagVal {
 
       let spread_cj = out.spread.cj || TOP
 
-      // The template REFUSED at construction (clearing rule 3, G4
-      // phase 1): the bag itself is that refusal. Returning the nil
-      // here rather than only letting it reach the children is what
-      // makes an EMPTY bag with a bad template an error too — there
-      // are no children to carry it.
-      //
-      // Narrow to THIS code on purpose. A nil spread from any other
-      // cause keeps its existing behaviour of driving every key
-      // (coverage3 `nil-spread-drives-every-key`): a template that has
-      // merely not resolved yet must not permanently kill the bag that
-      // holds it.
-      if ('id_spread' === (spread_cj as any).why) {
-        return spread_cj
-      }
-
       // Always unify children first
       for (let key in this.peg) {
         const keyctx = ctx.descend(key)
@@ -172,7 +159,7 @@ class ListVal extends BagVal {
         // 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 (`&: id(key(1))`, G8 phase
+        // — 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
@@ -181,11 +168,11 @@ class ListVal extends BagVal {
         // does.
         let oval: Val
         if (!spread_cj.isTop
-          && (child as any)._spr === (spread_cj as any).id) {
+          && (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 = (spread_cj as any).id
+          ; (oval as any)._spr = spreadId(spread_cj)
         }
         else {
           const key_spread_cj = spread_cj.spreadClone(keyctx)
@@ -212,7 +199,7 @@ class ListVal extends BagVal {
                         child, key_spread_cj, 'list-own')
 
           if (!spread_cj.isTop && !oval.isNil) {
-            ; (oval as any)._spr = (spread_cj as any).id
+            ; (oval as any)._spr = spreadId(spread_cj)
           }
         }
 
@@ -265,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)
       }

package/src/val/MapVal.ts

@@ -17,7 +17,6 @@ import { unite } from '../unify'
 import {
   propagateMarks,
   canonRiders,
-  constantIdFunc,
   walk,
   explainOpen,
   ec,
@@ -29,12 +28,13 @@ import { makeNilErr, AontuError } from '../err'
 import {
   top
 } from './top'
+import { pendingMarkWrapper } from './RefVal'
 
 
 import { ConjunctVal } from './ConjunctVal'
 import { NilVal } from './NilVal'
 import { BagVal } from './BagVal'
-import { repathInstance } from './Val'
+import { repathInstance, spreadId } from './Val'
 import { cmpCodePoint } from '../keyorder'
 import { markSpread } from '../provenance'
 
@@ -70,6 +70,15 @@ function snapshotRefSpread(cj: any, ctx: AontuContext): Val | undefined {
     // A ref to a type() resolves to its inner template — snapshot that,
     // so a type-wrapped ref behaves like a plain-map ref spread.
     if (tgt && (tgt as any).isTypeFunc) tgt = (tgt as any).peg?.[0]
+    // A pending type()/hide() CALL is not yet a value to snapshot
+    // (ADR-005, the same rule find's non-snap path defers on): cached
+    // here it resolves at every destination and STAMPS marks the
+    // clearing walk ran too early to clear -- a mutual recursive
+    // schema's members vanished from generation this way. No cache;
+    // retry once the wrapper has resolved at its own field.
+    if (tgt && pendingMarkWrapper(tgt)) {
+      return undefined
+    }
     // Only snapshot a found, path-dependent target. If the target is not
     // present yet (it may be introduced by a later conjunct/merge), do
     // NOT cache — retry on the next fixpoint pass.
@@ -122,22 +131,6 @@ class MapVal extends BagVal {
               new ConjunctVal({ peg: spread.v }, ctx) :
               spread.v[0] :
             spread.v
-
-        // Clearing rule 3 (G4 phase 1): a CONSTANT id in the template
-        // would declare every child to be one entity. The refusal
-        // replaces the template, so it reaches every child and the
-        // bag itself (see the isNil arm where the spread is applied)
-        // as ONE nil identity — made here, once, rather than per
-        // pass, so the report names it once.
-        const idfn: any = constantIdFunc(this.spread.cj)
-        if (undefined !== idfn) {
-          const nil: any = new NilVal({ why: 'id_spread' }, ctx)
-          nil.site.row = idfn.site.row
-          nil.site.col = idfn.site.col
-          nil.site.url = idfn.site.url
-          nil.primary = idfn
-          this.spread.cj = nil
-        }
       }
     }
 
@@ -147,7 +140,34 @@ class MapVal extends BagVal {
 
   // NOTE: order of keys is not preserved!
   // not possible in any case - consider {a,b} unify {b,a}
+  // ALIAS DECLARATIONS MUST SIT AT THE DOCUMENT ROOT. Stated on the
+  // VALUE rather than at the parse, because the parse cannot see it: an
+  // INCLUDED file's declarations are at the root of their own text, and
+  // only once the loaded map is placed does it become apparent that
+  // root is not the document's. `%name` is spelled as a reference from
+  // the document root, so an included file's own `%b` would otherwise
+  // reach the INCLUDER's `%b` -- cross-file capture, the hazard the
+  // sigil exists to prevent, one level up.
+  //
+  // P1 is single-file by construction; carrying a name ACROSS files is
+  // what `export` and the destructure are for (P2, not built), and this
+  // refusal is what keeps the two from being confused meanwhile. Pathed
+  // at the DECLARATION, which is what is wrong, not at the map.
+  aliasDeclarationsAreRooted(ctx: AontuContext): Val | undefined {
+    if (0 === this.aliasKeys.length || 0 === this.path.length) {
+      return undefined
+    }
+    const nv: any = new NilVal({ why: 'alias_not_toplevel' }, ctx)
+    nv.site = this.site
+    nv.path = [...this.path, this.aliasKeys[0]]
+    return nv
+  }
+
   unify(peer: Val, ctx: AontuContext): Val {
+    const arooted = this.aliasDeclarationsAreRooted(ctx)
+    if (undefined !== arooted) {
+      return arooted
+    }
     // console.log('MAPVAL-UNIFY', this.id, this.canon, peer.id, peer.canon)
 
     const TOP = top()
@@ -173,9 +193,18 @@ class MapVal extends BagVal {
 
     out.closed = this.closed
     out.optionalKeys = [...this.optionalKeys]
+    out.aliasKeys = [...this.aliasKeys]
     out.spread.cj = this.spread.cj
     out.site = this.site
 
+    // A rel() peer DRIVES whichever side the fold hands it on: the
+    // relation constraint rewrites this container leaf by leaf
+    // (RELATIONS.0.md §3.2), exactly as a sizing residual takes the
+    // driver's seat above.
+    if (true === (peer as any)?.isRel) {
+      return peer.unify(this, te ? ctx.clone({ explain: ec(te, 'REL') }) : ctx)
+    }
+
     if (peer instanceof MapVal) {
       if (!this.closed && peer.closed) {
         out = peer.unify(this, te ? ctx.clone({ explain: ec(te, 'PMC') }) : ctx) as MapVal
@@ -238,21 +267,6 @@ class MapVal extends BagVal {
 
       let spread_cj = out.spread.cj ?? TOP
 
-      // The template REFUSED at construction (clearing rule 3, G4
-      // phase 1): the bag itself is that refusal. Returning the nil
-      // here rather than only letting it reach the children is what
-      // makes an EMPTY bag with a bad template an error too — there
-      // are no children to carry it.
-      //
-      // Narrow to THIS code on purpose. A nil spread from any other
-      // cause keeps its existing behaviour of driving every key
-      // (coverage3 `nil-spread-drives-every-key`): a template that has
-      // merely not resolved yet must not permanently kill the bag that
-      // holds it.
-      if ('id_spread' === (spread_cj as any).why) {
-        return spread_cj
-      }
-
       // Snapshot a path-dependent *ref* spread to its structural target
       // once (while inner key()/path() funcs are still unresolved), so
       // later fixpoint passes don't re-resolve the ref against the mutated
@@ -292,11 +306,11 @@ class MapVal extends BagVal {
         // No `undefined !== child` here: propagateMarks above already
         // dereferenced it, so a missing child would have thrown there.
         if (!spread_cj.isTop
-          && (child as any)._spr === (spread_cj as any).id) {
+          && (child as any)._spr === spreadId(spread_cj)) {
           oval = child.done ? child :
             unite(te ? keyctx.clone({ explain: ec(te, 'KEY:' + key) }) : keyctx,
               child, TOP, 'map-own')
-          ; (oval as any)._spr = (spread_cj as any).id
+          ; (oval as any)._spr = spreadId(spread_cj)
         }
         else {
           const key_spread_cj = spread_cj.spreadClone(keyctx)
@@ -325,7 +339,7 @@ class MapVal extends BagVal {
                         child, key_spread_cj, 'map-own')
 
           if (!spread_cj.isTop && !oval.isNil) {
-            ; (oval as any)._spr = (spread_cj as any).id
+            ; (oval as any)._spr = spreadId(spread_cj)
           }
         }
 
@@ -355,6 +369,13 @@ class MapVal extends BagVal {
             out.optionalKeys.push(peerkey)
           }
 
+          // ... and so is an alias declaration, for the same reason:
+          // two statements for one map are one map, and a name declared
+          // in either is declared in the result.
+          if (upeer.aliasKeys.includes(peerkey) && !out.aliasKeys.includes(peerkey)) {
+            out.aliasKeys.push(peerkey)
+          }
+
           let child = out.peg[peerkey]
 
           const peerctx = ctx.descend(peerkey)
@@ -383,15 +404,27 @@ class MapVal extends BagVal {
             // Same apply-once discipline as the own-key loop: once the
             // constraint is merged into the value (marked with the
             // constraint's id), later passes only self-unify.
-            if ((oval as any)._spr !== (spread_cj as any).id) {
+            if ((oval as any)._spr !== spreadId(spread_cj)) {
               let key_spread_cj = spread_cj.spreadClone(peerctx)
 
+              // A SPREAD IS A SPREAD FROM EITHER SIDE. The own-key loop
+              // above marks its template so `why` can say the
+              // contribution came from `&:` rather than from the key;
+              // this arm did not, so the SAME document reported the
+              // role or dropped it depending on whether the template
+              // and the keys were written in one statement or two --
+              // `services: &: {..}` plus `services: {web:{}}` took the
+              // peer path and lost `(spread)` (use-cases/BUGS.md §55).
+              if (undefined !== peerctx.prov) {
+                markSpread(key_spread_cj)
+              }
+
               oval = out.peg[peerkey] =
                 unite(te ? peerctx.clone({ explain: ec(te, 'PSP:' + peerkey) }) : peerctx,
                   oval, key_spread_cj, 'map-peer-spread')
 
               if (!spread_cj.isTop && !oval.isNil) {
-                ; (oval as any)._spr = (spread_cj as any).id
+                ; (oval as any)._spr = spreadId(spread_cj)
               }
             }
           }
@@ -401,6 +434,12 @@ class MapVal 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: the kind knows to
+        // admit this map, and this map knows nothing about kinds.
+        out = peer.unify(this, ctx) as any
+      }
       else if (!peer.isTop) {
         out = makeNilErr(ctx, 'map', this, peer)
       }
@@ -479,6 +518,7 @@ class MapVal extends BagVal {
 
     out.closed = this.closed
     out.optionalKeys = [...this.optionalKeys]
+    out.aliasKeys = [...this.aliasKeys]
 
     return out
   }
@@ -509,6 +549,7 @@ class MapVal extends BagVal {
 
     out.closed = this.closed
     out.optionalKeys = [...this.optionalKeys]
+    out.aliasKeys = [...this.aliasKeys]
 
     // out.from = this.from
 
@@ -522,7 +563,14 @@ class MapVal extends BagVal {
     // independent of insertion/unification order and matches the Go
     // port. A bare .sort() is UTF-16 code-unit order, which puts an
     // astral key ahead of everything in U+E000-U+FFFF -- see cmpCodePoint.
-    let keys = Object.keys(this.peg).sort(cmpCodePoint)
+    // An alias declaration is not part of the document, so canon does
+    // not render it: a document with aliases and the document with
+    // every alias written out longhand must produce the same text and
+    // therefore the same `aon1-` hash. That is the sharpest statement
+    // of what an alias IS -- a name for a value, and nothing more.
+    let keys = Object.keys(this.peg)
+      .filter(k => !this.aliasKeys.includes(k))
+      .sort(cmpCodePoint)
     return '' +
       // this.errcanon() +
       // (this.mark.type ? '<type>' : '') +

package/src/val/PathFuncVal.ts

@@ -1,5 +1,31 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
+// THE PATH CONSTRUCTOR (docs/design/PATHS.0.md). `path(p)` CAPTURES
+// `p` -- the one non-strict argument position in the language: every
+// other call reads its argument's value, this one reads its spelling.
+// `path($.a.b)` is the address `$.a.b` as a first-class value, not
+// the value found there; a plain reference (`$.a.b` alone) stays the
+// embedding it has always been.
+//
+// The capture happens in prepare(), which receives the argument
+// BEFORE the driving loop resolves it -- the same interception this
+// function always used, now kept instead of released: the RefVal's
+// spelling is read off its segments and the RefVal itself is never
+// driven, so no pass ever holds a resolvable reference here.
+//
+// `path()` with no argument is the path KIND (PathKindVal): the
+// vacuous constructor call is the kind, as `{}`-the-unit is to maps
+// -- see ContainerKindVal for the other half of that convention.
+//
+// A string argument is read by the ADDRESS grammar, not resolved as a
+// segment: `path("$.a")` is the same capture `path($.a)` is, and text
+// with no anchor is RELATIVE (`path("a.b")` is `path(.a.b)`, the
+// address the raw spelling captures). A COMPUTED argument -- an
+// expression, a reference to a string -- is the one shape that does
+// evaluate: the driven result converts by the same grammar at
+// resolve, which is what makes an address buildable (`refer() &
+// path("$.customers." + key())`) while a bare string still never IS
+// one (ADR-016): the conversion happens only inside this call.
 
 import type {
   Val,
@@ -12,8 +38,41 @@ import {
 
 import { makeNilErr } from '../err'
 
-import { RefVal } from '../val/RefVal'
 import { FuncBaseVal } from './FuncBaseVal'
+import { PathVal, PathKindVal, parseAddress, textAddress } from './PathVal'
+
+
+// The address a reference SPELLS, or undefined when its segments
+// cannot spell one (a variable segment, a parent step after the first
+// named segment). Leading `.` entries in a relative ref's peg are
+// parent steps; the spelling is the same grammar refer reads, so one
+// address parser stays the single gate.
+function captureSpelling(rv: any): string | undefined {
+  const parts: string[] = []
+  let up = 0
+  let lead = true
+  for (const p of rv.peg) {
+    if ('string' !== typeof p) {
+      return undefined
+    }
+    if ('.' === p) {
+      if (!lead) {
+        return undefined
+      }
+      up++
+    }
+    else {
+      lead = false
+      parts.push(p)
+    }
+  }
+  if (0 === parts.length || (rv.absolute && 0 < up)) {
+    return undefined
+  }
+  return rv.absolute ?
+    '$.' + parts.join('.') :
+    '.'.repeat(up + 1) + parts.join('.')
+}
 
 
 class PathFuncVal extends FuncBaseVal {
@@ -41,37 +100,66 @@ class PathFuncVal extends FuncBaseVal {
 
 
   prepare(ctx: AontuContext, args: Val[]) {
-    let arg = args[0]
-
     if (0 === this.prepared) {
-      // A missing argument (`path()`) must produce an invalid-arg error
-      // value, as the Go port does -- reading .isScalar off nothing threw
-      // a TypeError that the unifier could only report as an opaque
-      // internal error. Same discipline breach, and same fix, as the one
-      // UpperFuncVal records; path() was missed in that sweep.
+      this.prepared++
+
+      const arg: any = args[0]
+
+      // The kind form: no argument to capture.
       if (null == arg) {
-        arg = makeNilErr(ctx, 'invalid-arg', this)
+        return []
       }
-      else if (arg.isScalar) {
-        arg = this.place(new RefVal({ peg: [arg], absolute: false }))
+
+      // The captured spelling, from a reference's segments or from a
+      // string literal read as address text. Both go through
+      // parseAddress, so what capture admits and what refer reads
+      // cannot drift. Anything else -- an expression, a reference to
+      // a string -- is left for the driving loop, and resolve
+      // converts the driven result below.
+      let spelling: string | undefined
+      if (true === arg.isRef) {
+        spelling = captureSpelling(arg)
       }
-      else if (!arg.isRef) {
-        arg = makeNilErr(ctx, 'invalid-arg', this)
+      else if (true === arg.isScalar && 'string' === typeof arg.peg) {
+        spelling = textAddress(arg.peg)
+      }
+      else {
+        return args
       }
-    }
 
-    args[0] = arg
+      if (undefined === spelling || undefined === parseAddress(spelling)) {
+        return [makeNilErr(ctx, 'path_address', this, arg)]
+      }
 
-    this.prepared++
+      return [new PathVal({ peg: spelling }, ctx)]
+    }
 
     return args
   }
 
 
   resolve(ctx: AontuContext, args: Val[]) {
-    let out = args[0] ?? makeNilErr(ctx, 'arg', this)
-
-    return out
+    if (0 === args.length) {
+      const out = new PathKindVal({}, ctx)
+      out.site = this.site
+      out.path = this.path
+      return out
+    }
+    const arg: any = args[0]
+    if (true === arg.isPath || true === arg.isNil) {
+      return arg
+    }
+    // The COMPUTED argument, driven by the loop above: a string
+    // converts by the address grammar, exactly as a literal does at
+    // capture; anything else was never a path expression.
+    if (true === arg.isScalar && 'string' === typeof arg.peg) {
+      const spelling = textAddress(arg.peg)
+      if (undefined === parseAddress(spelling)) {
+        return makeNilErr(ctx, 'path_address', this, arg)
+      }
+      return new PathVal({ peg: spelling }, ctx)
+    }
+    return makeNilErr(ctx, 'invalid-arg', this)
   }
 
 } /* node:coverage ignore next 6 */