aontu 0.52.1 → 0.54.0

package/src/val/ScalarKindVal.ts

@@ -64,6 +64,15 @@ class BigDecimal { }
 // A ScalarKind for null.
 class Null { }
 
+// A ScalarKind for tree addresses (docs/design/PATHS.0.md): the value
+// a `path(p)` call captures. Sits UNDER string -- an address is a
+// string with more structure, so string-kinded schemas over address
+// fields keep admitting -- while staying a distinct leaf, so a plain
+// string literal and a path value refuse each other exactly as the
+// number tower's leaves do. Reached only by the `path()` builtin, as
+// the exact numeric leaves are reached only by `0d`.
+class Path { }
+
 
 // The immediate lattice parent of each kind marker. A marker absent from
 // this table sits directly under top (string, boolean, null -- and
@@ -75,6 +84,7 @@ const KIND_PARENT = new Map<any, any>([
   [Float, Number],
   [BigInteger, Number],
   [BigDecimal, Number],
+  [Path, String],
 ])
 
 
@@ -85,18 +95,6 @@ function kindParent(kind: any): any {
 }
 
 
-// The root of a kind marker's family: the highest ancestor below top.
-// Every numeric leaf answers `number`; a kind with no parent is its own
-// family root (string, boolean, null).
-function kindFamily(kind: any): any {
-  let root = kind
-  for (let k = KIND_PARENT.get(kind); null != k; k = KIND_PARENT.get(k)) {
-    root = k
-  }
-  return root
-}
-
-
 // True when `sub` is `sup`, or sits anywhere below it. The numeric
 // lattice is two deep today; walking the chain keeps this correct if it
 // ever deepens.
@@ -119,6 +117,7 @@ type ScalarConstructor =
   (typeof BigInteger) |
   (typeof BigDecimal) |
   (typeof Null) |
+  (typeof Path) |
   (typeof Integer.constructor)
 
 
@@ -228,9 +227,9 @@ export {
   Float,
   Integer,
   Null,
+  Path,
   ScalarConstructor,
   ScalarKindVal,
-  kindFamily,
   kindParent,
   kindSubsumes,
 }

package/src/val/SuperFuncVal.ts

@@ -1,6 +1,16 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
+// THE IMMEDIATE PARENT TYPE (docs/design/SUPER.0.md): super(x) answers
+// the type one step above its argument, structurally. The lattice
+// primitive Val.superior() stays what it always was -- the preference
+// override gate and query's kind lift -- and answers here only for the
+// forms it already served (scalars, kinds, top). Everything structural
+// is this file's walk: maps and lists lift child by child, preferences
+// unwrap, disjunctions distribute, constraints answer the kind they
+// constrain, and a recursion residual stays a symbolic call -- the
+// finite spelling of a lift that is itself recursive.
+
 import type {
   Val,
   ValSpec,
@@ -12,6 +22,11 @@ import {
 
 
 import { FuncBaseVal } from './FuncBaseVal'
+import { MapVal } from './MapVal'
+import { ListVal } from './ListVal'
+import { DisjunctVal } from './DisjunctVal'
+import { ScalarKindVal } from './ScalarKindVal'
+import { top } from './top'
 
 
 class SuperFuncVal extends FuncBaseVal {
@@ -34,26 +49,135 @@ class SuperFuncVal extends FuncBaseVal {
   }
 
 
-  resolve(_ctx: AontuContext, args: Val[]) {
-    // super(x) is the lattice-superior of its ARGUMENT, not of the
-    // super() call itself: super(1) -> integer, super(1.5) -> number,
-    // super(a) -> string, super(true) -> boolean. Returning the
-    // function's own superior (top) is what made super() inert.
-    const arg: any = args?.[0]
-    if (arg?.isVal) {
-      const sup = arg.superior()
-      // Where the argument has no meaningful superior (superior()
-      // defaults to top), fall back to the previous behaviour.
-      if (null != sup && true !== sup.isTop) {
-        return this.place(sup)
+  // A DIRECT residual rides the residuate path rather than resolving:
+  // the pending call IS the answer (SUPER.0.md, the phase boundary),
+  // printing as written and refusing at generation exactly as an
+  // unexpanded recursion does. Residuals met DURING descent are minted
+  // as pending child calls by superOf below; only the top-level
+  // argument needs the defer, or resolve would re-mint the same call
+  // inside one pass forever.
+  deferResolve(_ctx: AontuContext, args?: Val[]): boolean {
+    return true === (args?.[0] as any)?.isRecurse
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    // One argument, always a Val: funcArity pins super at [1,1]
+    // before any resolve, and the parser builds arguments as Vals --
+    // a guarded fallback here is dead code under ADR-002.
+    return this.place(superOf(ctx, args[0]))
+  }
+
+}
+
+
+// superOf answers the immediate parent type of a RESOLVED value (the
+// caller drives arguments before resolve fires, so pending forms --
+// held conjuncts, unresolved references, holes -- never arrive).
+function superOf(ctx: AontuContext, v: any): Val {
+  // The residual's lift is itself recursive, so the finite answer is
+  // the symbolic call (SUPER.0.md): a fresh pending super() holding a
+  // clone of the residual, standing wherever the residual stood --
+  // the `next?` slot of a lifted recursive body prints
+  // `super($.Node)` and drops under an optional key at generation.
+  if (true === v.isRecurse) {
+    const call = new SuperFuncVal({ peg: [v.clone(ctx)] }, ctx)
+    return v.place(call)
+  }
+
+  // Maps and lists lift child by child. Shape is carried, not lifted:
+  // key optionality and closedness describe the container, and the
+  // spread template lifts so the result admits at the lifted level
+  // for future keys exactly as the original admitted at its own.
+  // A fresh bag (ADR-005 instantiation): type/hide marks are not
+  // copied -- the lift of a hidden definition is output.
+  if (true === v.isMap) {
+    const peg: Record<string, Val> = {}
+    for (const k of Object.keys(v.peg)) {
+      peg[k] = superOf(ctx, v.peg[k])
+    }
+    const out: any = new MapVal({ peg }, ctx)
+    out.optionalKeys = [...v.optionalKeys]
+    out.closed = v.closed
+    if (null != v.spread?.cj) {
+      out.spread.cj = superOf(ctx, v.spread.cj)
+    }
+    return v.place(out)
+  }
+
+  if (true === v.isList) {
+    const peg: Val[] = v.peg.map((e: Val) => superOf(ctx, e))
+    const out: any = new ListVal({ peg }, ctx)
+    out.closed = v.closed
+    if (null != v.spread?.cj) {
+      out.spread.cj = superOf(ctx, v.spread.cj)
+    }
+    return v.place(out)
+  }
+
+  // The parent TYPE of a soft value is the parent of the value --
+  // softness does not survive typing. Deliberately NOT superpeg,
+  // whose top-for-a-kind answer is override-gate semantics.
+  if (true === v.isPref) {
+    return superOf(ctx, v.peg)
+  }
+
+  // A choice lifts arm by arm: super(1|2) is integer, super(1|"a") is
+  // integer|string. An arm whose lift is top absorbs the whole answer
+  // -- a disjunct carrying top says nothing -- and duplicate lifts
+  // collapse so the common case answers as the one kind it is.
+  if (true === v.isDisjunct) {
+    const arms: Val[] = []
+    const seen: Record<string, boolean> = {}
+    for (const a of v.peg) {
+      const lift = superOf(ctx, a)
+      if (true === (lift as any).isTop) {
+        return v.place(top())
+      }
+      if (true !== seen[lift.canon]) {
+        seen[lift.canon] = true
+        arms.push(lift)
       }
     }
-    return this.place(this.superior())
+    if (1 === arms.length) {
+      return v.place(arms[0])
+    }
+    return v.place(new DisjunctVal({ peg: arms }, ctx))
   }
 
+  // A constraint's parent is the kind it constrains: the absorbed
+  // leaf kind when it has one (integer & min(3) -> integer), else the
+  // domain its atoms compare in (min(3) -> number, min("a") ->
+  // string). length() constrains strings, lists and maps alike, so
+  // with neither it falls through to top.
+  if (true === v.isConstraint) {
+    if (null != v.kind) {
+      return v.place(new ScalarKindVal({ peg: v.kind }))
+    }
+    if ('number' === v.domain) {
+      return v.place(new ScalarKindVal({ peg: Number }))
+    }
+    if ('string' === v.domain) {
+      return v.place(new ScalarKindVal({ peg: String }))
+    }
+    return v.place(top())
+  }
+
+  // The lattice primitive answers for the forms it always served:
+  // a concrete scalar lifts to its leaf kind, a kind to its parent,
+  // top to itself, and a NIL to itself -- which is how a failed
+  // argument stays the failure: `super(1 & 2)` reports the conflict
+  // rather than typing it. Where it has no meaningful answer (superior()
+  // defaults to top for features), top is the honest remainder.
+  const sup = v.superior()
+  if (null != sup && true !== (sup as any).isTop) {
+    return sup
+  }
+  return v.place(top())
 } /* node:coverage ignore next 6 */
 
 
 export {
   SuperFuncVal,
+  superOf,
 }

package/src/val/TopVal.ts

@@ -1,6 +1,5 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
-import { inspect } from 'node:util'
 
 import type {
   ValSpec,
@@ -53,7 +52,7 @@ class TopVal extends Val {
     return this
   }
 
-  clone(_ctx: AontuContext, _spec?: ValSpec) {
+  clone(_ctx: AontuContext, _spec?: ValSpec): Val {
     return this
   }
 

package/src/val/TypeFuncVal.ts

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

package/src/val/UpperFuncVal.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'

package/src/val/Val.ts

@@ -8,6 +8,8 @@ import {
   Site
 } from '../site'
 
+import { INNER_OF, WRITTEN } from '../provenance'
+
 
 type ValMark = {
   type: boolean,
@@ -22,6 +24,21 @@ type ValSpec = {
   mark?: Partial<ValMark>,
   kind?: any,
 
+  // THE PER-DESTINATION INSTANTIATION FLAG (ADR-005). A generator's
+  // template is cloned once per destination, and every clone must be
+  // a full instance: nothing path-dependent may be shared between two
+  // destinations, or the first destination's resolution answers for
+  // them all. The default clone shares inner structure deliberately
+  // (`peg: this.peg` below — the move()/copy() ghost rows in
+  // test/spec/func.tsv pin that sharing), so instantiation asks for
+  // depth explicitly: `dup: true` makes FuncBaseVal, PrefVal and
+  // OpBaseVal clone their inner Vals too, and the bag/junction clones
+  // carry the flag down. Set by pack/each template instantiation,
+  // filter condition testing, and spread application (MapVal/
+  // ListVal.spreadClone) — never by the residuation or ref-resolution
+  // clones, whose sharing is pinned behaviour.
+  dup?: boolean,
+
 
   row?: number,
   col?: number,
@@ -134,6 +151,28 @@ abstract class Val {
     hide: false,
   }
 
+  // The deprecation record (G3 phase 4, `deprecate(x, m)`): boolean
+  // marks cannot hold a message, a replacement path and a version, so
+  // the Val carries one optional record. Keys are the three the
+  // builtin defines (msg, use, since), all optional, values strings;
+  // `use` is a path spelled as a STRING — a live reference would
+  // resolve and unify, which is not wanted. Propagated through meets
+  // by propagateMarks and carried by clone, exactly as the boolean
+  // marks are.
+  deprecation?: Record<string, string>
+
+  // The LINK (G4 phase 2/3): the tree address a `refer` resolved to,
+  // stamped on the string it answers. The string IS the value — a
+  // link, not an embedding — so nothing downstream could otherwise
+  // tell a checked link from a literal that happens to look like one,
+  // and the edge set (ts/src/graph.ts) is exactly the set of these.
+  link?: string
+
+  // The GRAPH of an evaluated document (G4 phase 3): the edge set,
+  // stamped on the result by Aontu.unify the way the include manifest
+  // is. Absent on every Val that is not a unify result.
+  graph?: any
+
   // Actual native value.
   peg: any = undefined
 
@@ -225,11 +264,85 @@ abstract class Val {
     out.site.row = spec?.row ?? this.site.row
     out.site.col = spec?.col ?? this.site.col
     out.site.url = spec?.url ?? this.site.url
+    // THE SPAN TRAVELS WITH THE POSITION. Copying row and col but not
+    // the extent would leave a site that names a place and denies it has
+    // any width — internally inconsistent, and it made the two ports
+    // disagree on every derived value (the shared subsume rows caught
+    // it). Safe because the span is VERIFIABLE: a consumer reads the
+    // document at (row, col, len) and refuses when it does not match
+    // `src`, so a span that has stopped describing its value is
+    // detectable rather than believed. See ts/src/site.ts.
+    //
+    // Read from `this.site`, never from the spec: ValSpec.src is a
+    // DIFFERENT field — ScalarVal's literal spelling, kept so `$.a.0x0`
+    // addresses the key `0x0` — and reading it here would put a path
+    // segment where a source span belongs.
+    //
+    // UNCONDITIONAL, as the Go twin is (clonePath, go/clone.go). A
+    // guard dropping the span when the spec relocates the value was
+    // written first and the coverage gate refused it as dead: nothing
+    // clones to a new row or column. Should a relocating caller ever
+    // appear it must drop both fields — an extent belongs to a place,
+    // and the text at a new one is not this value's to claim.
+    out.site.len = this.site.len
+    out.site.src = this.site.src
 
     out.mark = Object.assign({}, this.mark, fullspec.mark ?? {})
     out.mark.type = this.mark.type && (fullspec.mark?.type ?? true)
     out.mark.hide = this.mark.hide && (fullspec.mark?.hide ?? true)
 
+    // The LINK rider travels with the clone: the address a resolved
+    // link POINTS AT is part of what the value is, and a copy of a
+    // link is still a link.
+    if (null != this.link) {
+      out.link = this.link
+    }
+    if (null != this.deprecation) {
+      out.deprecation = this.deprecation
+    }
+
+    // THE APPLY-ONCE MARK TRAVELS WITH THE CLONE. `_spr` records which
+    // spread template has already been merged into this value, and the
+    // bag loops read it to keep a template from being applied twice
+    // (MapVal.unify, ListVal.unify). A clone that dropped it looked
+    // un-spread, so a REFERENCE resolving to a templated bag had the
+    // template applied a second time -- over the value the first
+    // application had already produced. With `n: key()` that meant
+    // meeting the answered `"x"` as though it were a map and asking
+    // `key()` again, which answered `"n"`: `$.a.b.f.x.n.n`, "n"
+    // against "x" (use-cases/BUGS.md §50). The Go port carries it and
+    // answered correctly; this is the canonical side catching up.
+    if (null != (this as any)._spr) {
+      ; (out as any)._spr = (this as any)._spr
+    }
+    if (null != (this as any)._sid) {
+      ; (out as any)._sid = (this as any)._sid
+    }
+
+    // PROVENANCE TRAVELS WITH THE CLONE, exactly as the site does, and
+    // for the same reason: a clone of a value the author wrote IS that
+    // written value somewhere else, and it carries the author's site,
+    // so it can be pointed at. Without this a default reaching a
+    // `pack()`-generated child, or a shape carried by a `$ref`, was
+    // invisible to `why` -- which answered "nothing met at this path"
+    // over a value it had just printed (the review's finding E). See
+    // WRITTEN in ts/src/provenance.ts; the mark is only ever set by an
+    // instrumented run, so this is one undefined read otherwise.
+    if (true === (this as any)[WRITTEN]) {
+      (out as any)[WRITTEN] = true
+    }
+    // AND SO DOES BEING PART OF SOMETHING. A clone of a disjunction's
+    // member is still that member of that written disjunction, and the
+    // whole statement is what the author needs shown -- otherwise a
+    // default reaching a generated child reports `*"info"` and
+    // `string` as two contributions at two columns, where the author
+    // wrote `*info | string` once. A number, deliberately: a Val
+    // holding another Val as an own property is a cycle through the
+    // tree. See INNER_OF in ts/src/provenance.ts.
+    if (null != (this as any)[INNER_OF]) {
+      (out as any)[INNER_OF] = (this as any)[INNER_OF]
+    }
+
     return out
   }
 
@@ -237,8 +350,17 @@ abstract class Val {
   // Shallow clone for spread constraints: creates a new Val with the
   // correct path context but shares non-path-dependent children.
   // Override in MapVal/ListVal to avoid deep-cloning simple children.
+  //
+  // A FULL INSTANCE (`dup`, ADR-005): a spread constraint is applied
+  // once per destination child, and each application must own its
+  // path-dependent innards — a bare clone shared a call's arguments
+  // and a preference's inner value across destinations, so a spread
+  // like `&: {k: key(0)} & $.schema.C` resolved its one shared key()
+  // at the first child it met (use-cases/BUGS.md §12's id_name form).
   spreadClone(ctx: AontuContext): Val {
-    return this.clone(ctx)
+    const out = this.clone(ctx, { dup: true })
+    repathInstance(out, out.path)
+    return out
   }
 
 
@@ -278,10 +400,26 @@ abstract class Val {
   }
 
 
+  // PUT A MINTED VALUE WHERE THIS ONE STANDS: the site travels, and so
+  // does provenance, because the two answer one question. A narrowed
+  // disjunction, a lifted kind, a resolved reference -- each is a
+  // value the engine built from a value the author wrote, standing
+  // where that one stood. Carrying the site and withholding the mark
+  // would let `why` print a value, know the line it came from, and
+  // still answer "nothing met at this path" (the review's finding E).
+  // See WRITTEN and INNER_OF in ts/src/provenance.ts.
   place(v: Val) {
     v.site.row = this.site.row
     v.site.col = this.site.col
     v.site.url = this.site.url
+    v.site.len = this.site.len
+    v.site.src = this.site.src
+    if (true === (this as any)[WRITTEN]) {
+      (v as any)[WRITTEN] = true
+    }
+    if (null != (this as any)[INNER_OF]) {
+      (v as any)[INNER_OF] = (this as any)[INNER_OF]
+    }
     return v
   }
 
@@ -431,6 +569,64 @@ Object.assign(Val.prototype, {
 })
 
 
+// THE INSTANCE PATH NORMALISATION (ADR-005), the TS mirror of the Go
+// port's setPaths (go/clone.go): assign every value in a freshly
+// instantiated template the path the PARSER would have given it at the
+// instance's destination. A deep instance clone (`dup`) copies values
+// whose stored parse paths are argument-shaped — a func argument has
+// no key of its own, a spread template lives under a '&' segment — and
+// Val.clone's ctx-cut cannot rebase those: it derives the child path
+// from the driving ctx alone and drops the segments in between, which
+// is how a nested list spread inside a close()d template lost its
+// parent key and every finding under it named the wrong path (the
+// 06-k8s use case's env findings). One canonical walk instead:
+// bag children descend by key (numeric for a list element, as the
+// parser records them), a spread constraint sits under '&' with its
+// content at the bag's own path, and junction members, operator
+// operands, function arguments and a preference's value all sit AT
+// their holder's path — exactly the parse-time shape.
+function repathInstance(v: any, path: string[]): void {
+  if (true !== v?.isVal) {
+    return
+  }
+  v.path = path
+
+  const peg = v.peg
+
+  if (true === v.isBag) {
+    const spread = v.spread?.cj
+    if (null != spread && true === spread.isVal) {
+      // The spread's CONTENT is pathed at the bag (its fields land on
+      // the bag's children); only its ROOT carries the '&' segment —
+      // the same two steps as the Go twin's setPaths.
+      repathInstance(spread, path)
+      spread.path = [...path, '&']
+    }
+    if (true === v.isList) {
+      for (let i = 0; i < peg.length; i++) {
+        // Numeric, as the parser records list positions: a numeric
+        // segment is what tells key() an element is not a keyed
+        // position (KeyFuncVal.resolve, `positioned`).
+        repathInstance(peg[i], [...path, i as unknown as string])
+      }
+    }
+    else {
+      for (const k of Object.keys(peg)) {
+        repathInstance(peg[k], [...path, k])
+      }
+    }
+  }
+  else if (Array.isArray(peg)) {
+    for (const t of peg) {
+      repathInstance(t, path)
+    }
+  }
+  else if (true === peg?.isVal) {
+    repathInstance(peg, path)
+  }
+}
+
+
 function inspectpeg(peg: any, d: number) {
   const indent = '  '.repeat(d)
   return pretty(Array.isArray(peg) ?
@@ -454,14 +650,27 @@ function pretty(s: string) {
 }
 
 
+// THE STABLE IDENTITY OF A SPREAD TEMPLATE, across clones. Every Val
+// takes a fresh `id` when it is constructed, so the bag loops'
+// apply-once mark -- which records WHICH template has already been
+// merged into a value -- could never match after a clone: a reference
+// resolving to a templated bag clones the bag AND its template, and the
+// fresh template's id matched nothing, so the template was applied a
+// second time over the value the first application had produced
+// (use-cases/BUGS.md §50). The first call fixes the identity to the
+// original's own id; Val.clone carries `_sid`, so every clone of that
+// template answers with it.
+function spreadId(cj: any): number {
+  return cj._sid ?? (cj._sid = cj.id)
+}
+
 function empty(o: any) {
   return (
     (Array.isArray(o) && 0 === o.length)
     || (null != o && 'object' === typeof o && 0 === Object.keys(o).length)
     || false
   )
-} /* node:coverage ignore next 16 */
-
+} /* node:coverage ignore next 17 */
 
 
 export type {
@@ -469,10 +678,13 @@ export type {
   ValSpec,
 }
 
+
 export {
+  spreadId,
   Val,
   DONE,
   SPREAD,
   EMPTY_ERR,
-  empty
+  empty,
+  repathInstance,
 }

package/src/val/VarVal.ts

@@ -24,7 +24,6 @@ import {
 
 
 import { StringVal } from './StringVal'
-import { NilVal } from './NilVal'
 import { FeatureVal } from './FeatureVal'
 import { NullVal } from './NullVal'
 import { BooleanVal } from './BooleanVal'