aontu 0.53.0 → 0.55.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],
 ])
 
 
@@ -107,6 +117,7 @@ type ScalarConstructor =
   (typeof BigInteger) |
   (typeof BigDecimal) |
   (typeof Null) |
+  (typeof Path) |
   (typeof Integer.constructor)
 
 
@@ -216,6 +227,7 @@ export {
   Float,
   Integer,
   Null,
+  Path,
   ScalarConstructor,
   ScalarKindVal,
   kindParent,

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

@@ -52,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/Val.ts

@@ -80,17 +80,6 @@ const EMPTY_ERR: any[] = Object.freeze([]) as unknown as any[]
 let ID = 1000
 
 
-// A fresh Val id, for the one carrier that cannot take the one its
-// class fixes: TopVal pins `id = 0` (there is only one top), and the
-// identity mark (G4 phase 1) resolves to a top that must NOT collide
-// with it — the fast path in `unite` returns early on two done Vals
-// with the same id, which would drop an identity before the rider
-// could carry it.
-export function nextValId(): number {
-  return ID++
-}
-
-
 abstract class Val {
   // Type-discriminator flags: defaults live on Val.prototype (see
   // bottom of this file). Each subclass overrides only its own
@@ -172,25 +161,16 @@ abstract class Val {
   // marks are.
   deprecation?: Record<string, string>
 
-  // The IDENTITY (G4 phase 1, `id(name)`): the entity this value IS.
-  // A separate slot for the same reason the deprecation record has
-  // one — a boolean ValMark cannot hold a name — and carried through
-  // meets by the same rider in `unite`. Unlike the marks, canon
-  // RENDERS it: identity is semantic content, and G6's hash must see
-  // it.
-  entity?: string
-
-  // The LINK (G4 phase 2/3): the entity address a `refer` resolved to,
+  // 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 entity index
-  // and 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.
+  // 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.
@@ -311,20 +291,34 @@ abstract class Val {
     out.mark.type = this.mark.type && (fullspec.mark?.type ?? true)
     out.mark.hide = this.mark.hide && (fullspec.mark?.hide ?? true)
 
-    // The two IDENTITY riders travel together, under one test: the
-    // entity a value IS, and the address a resolved link POINTS AT.
-    // One guard rather than two because the pair is what a clone
-    // either carries or does not — and because a second test for the
-    // link alone would be a branch no document takes, the reference
-    // clone catching the pending residual before it ever resolves.
-    if (null != this.entity || null != this.link) {
-      out.entity = this.entity
+    // 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,
@@ -361,7 +355,7 @@ abstract class Val {
   // 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 `&: id(key(0)) & $.schema.C` resolved its one shared key()
+  // 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 {
     const out = this.clone(ctx, { dup: true })
@@ -656,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 {
@@ -671,7 +678,9 @@ export type {
   ValSpec,
 }
 
+
 export {
+  spreadId,
   Val,
   DONE,
   SPREAD,

package/src/val/arith.ts

@@ -105,7 +105,10 @@ function unpref(v: any): any {
 
 
 function arithKind(v: any): ArithKind | undefined {
-  if (!(v?.isVal && v.isScalar)) {
+  // Every caller hands a driven Val (an operand past the signature
+  // gate, or a bag member from the aggregate fold), so scalarhood is
+  // the one question -- a container member lands here.
+  if (true !== v?.isScalar) {
     return undefined
   }
   if (v.isBigInteger) {

package/src/vet.ts

@@ -146,8 +146,10 @@ export type VetOptions = {
   // Vet's whole job is to evaluate a document its caller did not
   // write, so the caller must be able to say what that document is
   // allowed to reach: without this the include chain is the default
-  // one, and `@"x.js"` in hostile data is arbitrary code execution in
-  // the validating process. A server passes `{include:'none'}`.
+  // one, and `@"../../etc/passwd.aon"` in hostile data reads whatever
+  // the validating process can. (`@"x.js"` no longer executes --
+  // ADR-012 refuses the extension -- but reading is enough.) A server
+  // passes `{include:'none'}`.
   trust?: TrustOptions
 }
 
@@ -571,7 +573,11 @@ export function anchorAt(root: any, at: string): Val | undefined {
 
 
 // The container inside a settled sizing residue, or the value itself.
-function throughResidue(v: any): any {
+// EXPORTED for the `doc` figure, which walks the same shape the anchor
+// does: a list still carrying a `unique()` is a list, and a drawing
+// that stopped at the residue would omit keys the document plainly
+// has.
+export function throughResidue(v: any): any {
   return sizingResidue(v)?.bag ?? v
 }
 
@@ -696,7 +702,18 @@ export function vet(
       findings: [findingOf(failure, { data: new Set([dataUrl]) })],
     }
   }
-  stampUrl(anchor, schemaUrl)
+  // STAMP THE WHOLE SETTLED SCHEMA, not just the lifted anchor.
+  // Without `--at` these are the same tree. With it, the anchor is a
+  // subtree and the rest of the schema is still REACHABLE from inside
+  // it -- a `%alias` declaration (`[&: %U]`, target `$.%U`) or a
+  // recursive residual's `$.spec.Step`, both of which the meet
+  // resolves through _fixroot (RefVal.find, RecurseVal.body). A node
+  // reached that way but never stamped carries no url, so its site
+  // named no file while excerpting the schema's text -- against the
+  // invariant that every site names the file whose text it shows
+  // (finding F, §25). stampUrl only fills a url that is EMPTY, so
+  // stamping the superset never renames a value read from an include.
+  stampUrl(schemaVal, schemaUrl)
   const dataUrls = stampUrl(dataVal, dataUrl)
   // The projection every site in this report goes through: roles by
   // url-set membership, names by how the caller reached each document.
@@ -820,6 +837,26 @@ export function vet(
       stampUrl(meetAnchor, schemaUrl)
     }
   }
+  else {
+    // A RECURSIVE residual inside the lifted anchor still names its
+    // definition by absolute path (`then?: $.spec.Step` -- the
+    // fixpoint, RECURSION.0.md), and the meet's root is the anchored
+    // subtree, which does not contain `$.spec`. Without a tree to
+    // walk, the residual held its peer forever and everything under a
+    // recursive field vetted VALID unchecked. The settled schema root
+    // is kept on the meet context for exactly that walk
+    // (AontuContext._fixroot; RecurseVal.body and RefVal.find fall
+    // back to it).
+    ; (ctx as any)._fixroot = schemaVal
+    // And the meet DRIVES AT the anchor's own path, so every finding
+    // minted live during it sits in the schema's namespace
+    // ($.spec.Step.then.approver), exactly where the findings carried
+    // on the settled anchor's stored paths already sit -- the Go port
+    // gets this for free from its clone discipline, and the shared
+    // anchored-vet rows pin the agreement.
+    ; (ctx as any).path = options.at.replace(/^\$\.?/, '')
+      .split('.').filter((s: string) => '' !== s)
+  }
   const pair = new ConjunctVal({ peg: [meetAnchor, dataVal] }, ctx)
   const unified: any = aontu.unify(pair, undefined, ctx)