aontu 0.53.0 → 0.54.0

package/src/val/AggFuncVal.ts

@@ -1,7 +1,7 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// AGGREGATION AND PROJECTION: `sum(d)`, `least(d)`, `greatest(d)`
-// and `pick(d, k)`.
+// AGGREGATION, PROJECTION AND THE STRING FOLD: `sum(d)`, `least(d)`,
+// `greatest(d)`, `pick(d, k)` and `join(d, sep?)`.
 //
 // The review's finding I: "No aggregation. `length()` counts but
 // nothing sums: an invoice total, a fleet-wide resource budget, a quota
@@ -55,9 +55,12 @@ import {
 import { makeNilErr } from '../err'
 import { IntegerVal } from './IntegerVal'
 import { ListVal } from './ListVal'
+import { StringVal } from './StringVal'
 import { FuncBaseVal } from './FuncBaseVal'
 import { arith } from './arith'
 import { cmpNumeric } from './numcmp'
+import { cmpCodePoint } from '../keyorder'
+import { plusText } from './PlusOpVal'
 
 
 type AggOp = 'sum' | 'least' | 'greatest'
@@ -72,7 +75,14 @@ function bagChildren(data: any): Val[] | undefined {
     return data.peg as Val[]
   }
   if (true === data?.isMap) {
-    return Object.keys(data.peg).sort().map((k: string) => data.peg[k])
+    // THE ONE MAP-KEY ORDER (../keyorder.ts), not a bare `.sort()`:
+    // JavaScript compares by UTF-16 code unit, so an astral key's
+    // leading surrogate sorts BELOW U+E000-U+FFFF and `pick` answered
+    // in a different order from `each`, from canon, and from Go --
+    // which sorts UTF-8 bytes, i.e. code points. `pick` is the
+    // order-preserving projection, so that was one model producing two
+    // different generated files (BUGS.md 62).
+    return Object.keys(data.peg).sort(cmpCodePoint).map((k: string) => data.peg[k])
   }
   return undefined
 }
@@ -294,6 +304,222 @@ class PickFuncVal extends FuncBaseVal {
 }
 
 
+
+// THE FOLD TO A STRING: `join(coll, sep?)` -- G9 phase 2.
+//
+// The one primitive between a model and a generated file. A spread can
+// put a separator AFTER each element; putting one BETWEEN N elements is
+// a reduction over strings, and the language had none: `sum` is numeric,
+// `+` does not reduce a list, and indexed concatenation needs the arity
+// known in advance. So a generated SQL column list carried a trailing
+// comma and did not parse (use-cases/15-code-generation).
+//
+// IT FOLDS WITH `+` SEEDED WITH `""`, exactly as `sum` folds with `add`
+// seeded with `0`. That is not a figure of speech: the members are
+// rendered by `plusText`, which IS the function `+`'s string branch
+// calls, so the language keeps exactly one answer to "how does a number
+// become text" and the two cannot drift. `join(coll)` is therefore
+// concatenation and no `concat` is needed; `join(coll, "\n")` is lines
+// and no `lines` is needed. ONE BUILTIN, NOT A FAMILY.
+//
+// `split`/`words` is the inverse -- an input-PARSING operation with no
+// generation use -- and is deliberately absent.
+//
+// EMPTY IS `""`, concatenation's identity, the exact parallel of
+// `sum([]) == 0` and the opposite of `least([])`: a fold with an
+// identity can answer the empty bag, and one without has to refuse it.
+//
+// MEMBERS ARE VALIDATED BEFORE THE FOLD, which is the whole reason this
+// is not three lines. `+` with a string on the left RESIDUATES on a
+// container or a null rather than refusing (`"" + {b:1}` and `"x" +
+// null` both reach generation as `mapval_no_gen`), so folding blindly
+// would turn a bad member into a useless late error pointing at the
+// wrong thing. The three verdicts below are that check.
+type MemberVerdict = 'text' | 'never' | 'notyet'
+
+
+// Which of the three a value is.
+//
+// `text` -- `+` would take it, so the fold can.
+//
+// `never` -- a SETTLED value that will never become text: a map, a
+// list, a null. This is `join_member`, class `conflict`, and it names
+// the member rather than the call, because "one of these is not a
+// string" is only actionable if you are told which.
+//
+// `notyet` -- an unresolved kind, a top, a stable residue. NOT a join
+// failure at all: the call stays residual and generation reports
+// `mapval_no_gen`, class `incomplete`, exactly as docs/trust.md
+// requires ("a stable residue ... is ordinary incompleteness"). Getting
+// this split wrong in either direction is the defect that matters here:
+// refusing a residue makes `join` unusable inside a schema, and
+// deferring on a map makes a real error arrive as a shrug.
+function memberVerdict(v: any): MemberVerdict {
+  const u = unpref(v)
+  if (undefined !== plusText(u)) {
+    return 'text'
+  }
+  if (true === u?.isMap || true === u?.isList || true === u?.isNull) {
+    return 'never'
+  }
+  return 'notyet'
+}
+
+
+// The separator is a STRING or it is nothing.
+//
+// A number would render perfectly well through `+`, and is still
+// refused: the separator is not a member of the fold, it is the
+// parameter naming the text between members, and `join(x, 5)` is far
+// likelier a mistake than an intent to separate with "5". `pick`'s key
+// argument draws the same line for the same reason. This is the
+// direction that can be loosened later without breaking a document;
+// the other direction cannot.
+function sepVerdict(v: any): MemberVerdict {
+  const u = unpref(v)
+  if (u?.isVal && u.isScalar) {
+    return 'string' === typeof u.peg ? 'text' : 'never'
+  }
+  if (true === u?.isMap || true === u?.isList || true === u?.isNull) {
+    return 'never'
+  }
+  return 'notyet'
+}
+
+
+class JoinFuncVal extends FuncBaseVal {
+  isJoinFunc = true
+
+  // The bag must settle before it is folded, exactly as it must before
+  // it is summed or projected.
+  staged = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+  // A `make` OVERRIDE, WHERE ITS AggFuncVal SIBLINGS HAVE NONE, and the
+  // difference is worth stating because it is not arbitrary. `sum`,
+  // `pick` and the rest are staged and nothing more: they residuate
+  // before `unify` reaches the rebuild branch, so a `make` there would
+  // be unreachable code pretending to be a contract, and the base's
+  // `func:<name>` refusal is the loud answer if that ever changes.
+  //
+  // `join` is the first builtin that is BOTH staged AND defers its
+  // resolution (see `deferResolve`). A deferred call has settled
+  // arguments, so it does reach the rebuild branch, and without this it
+  // raised `func:join` on the first document with an unresolved member
+  // — where the Go port residuated and reported `mapval_no_gen`.
+  // Opposite answers on `join($.m, ",")` with `m: [string]`, caught by
+  // running both engines rather than by either test suite. `super` and
+  // bare `id`, the two other deferring calls, each carry the same
+  // override for the same reason.
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new JoinFuncVal(spec)
+  }
+
+
+  funcname() {
+    return 'join'
+  }
+
+
+  // The base does not drive: `unify` drives by hand, because a staged
+  // func must advance what it is waiting on every pass rather than only
+  // on the pass it fires.
+  prepare(_ctx: AontuContext, _args: Val[]) {
+    return null
+  }
+
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    // BOTH arguments, unlike `pick`, which drives only its bag: `pick`'s
+    // key is a bare word the parser has already made a string, while a
+    // separator is an ordinary expression and `join($.rows, $.sep)` has
+    // to wait for it.
+    const ready = this.driveStagedArgs(ctx, 2)
+
+    if (!ready || !ctx.settle) {
+      return this.residuate(peer, ctx)
+    }
+
+    return super.unify(peer, ctx)
+  }
+
+
+  // The `notyet` half of the verdict, taken before `resolve` runs: with
+  // arguments settled but a member still a kind, the call rides the
+  // ordinary args-not-done path and residuates, which is what makes an
+  // unresolved member ordinary incompleteness rather than a refusal.
+  deferResolve(_ctx: AontuContext, args?: Val[]): boolean {
+    const children = bagChildren(args?.[0])
+    if (undefined === children) {
+      // Not a bag at all: let `resolve` say so rather than waiting for
+      // a settling that has already happened.
+      return false
+    }
+    const sep = args?.[1]
+    if (undefined !== sep && 'notyet' === sepVerdict(sep)) {
+      return true
+    }
+    return children.some((c) => 'notyet' === memberVerdict(c))
+  }
+
+
+  resolve(ctx: AontuContext, args: Val[]) {
+    const children = bagChildren(args?.[0])
+
+    if (undefined === children) {
+      return this.place(makeNilErr(ctx, 'aggregate_data', this, undefined,
+        'join'))
+    }
+
+    // Arity is [1,2], so a second argument is present or the separator
+    // is the empty string -- which makes `join(coll)` concatenation.
+    // The separator's SHAPE is settled before resolve runs: the
+    // signature gate refuses every concrete non-string
+    // (docs/design/SIGNATURES.0.md; join(d: map|list, sep?: string)),
+    // and deferResolve holds the call while sepVerdict answers notyet
+    // -- so a present separator here is text.
+    let sep = ''
+    if (1 < args.length) {
+      sep = unpref(args[1]).peg
+    }
+
+    // NO NIL-MEMBER GUARD, WHERE `sum` HAS ONE, and the difference is
+    // the fold's shape rather than an oversight. `sum` folds with
+    // `arith`, which MINTS a nil part-way through — a non-numeric child
+    // or an overflow — so it has to stop and return it. `join` folds
+    // already-unified values, and a nil among a list's elements
+    // collapses the list before this call resolves: `join([least([])],
+    // ",")` reports `aggregate_empty` at the member's own path,
+    // `$.o.0`, and never reaches here. A guard was written, the
+    // ADR-002 gate found it unexecuted, and probing confirmed no
+    // spelling reaches it, so it is removed rather than excused.
+    const parts: string[] = []
+    for (const child of children) {
+      const u: any = unpref(child)
+      const text = plusText(u)
+      if (undefined === text) {
+        return this.place(makeNilErr(ctx, 'join_member', this, undefined,
+          'join', { member: String(u?.canon) }))
+      }
+      parts.push(text)
+    }
+
+    // Every part is already a string, so this IS the `+` fold seeded
+    // with `""` -- written as one concatenation because a loop of `+`
+    // over settled strings cannot differ from it, and because the Go
+    // twin's strings.Join must produce the same bytes.
+    return this.place(new StringVal({ peg: parts.join(sep) }))
+  }
+}
+
+
 // The three the registry names. Each is its operation and nothing else.
 class SumFuncVal extends AggFuncVal {
   constructor(spec: ValSpec, ctx?: AontuContext) { super(spec, ctx, 'sum') }
@@ -307,11 +533,12 @@ class GreatestFuncVal extends AggFuncVal {
   constructor(spec: ValSpec, ctx?: AontuContext) {
     super(spec, ctx, 'greatest')
   }
-} /* node:coverage ignore next 9 */
+} /* node:coverage ignore next 10 */
 
 
 export {
   AggFuncVal,
+  JoinFuncVal,
   PickFuncVal,
   SumFuncVal,
   LeastFuncVal,

package/src/val/BagVal.ts

@@ -30,6 +30,17 @@ abstract class BagVal extends FeatureVal {
   closed: boolean = false
   optionalKeys: string[] = []
 
+  // ALIAS DECLARATIONS, by key. `%uint8: …` binds a name for this file
+  // and is not a field of the document: it does not generate and does
+  // not appear in canon, so a document using aliases and its expanded
+  // twin are the SAME document and hash identically
+  // (docs/design/ALIASES.0.md §4).
+  //
+  // Keyed on the map rather than marked on the value, because a
+  // reference copies the value it resolves to -- a mark riding the
+  // value would erase the referring field along with the declaration.
+  aliasKeys: string[] = []
+
   spread = {
     cj: (undefined as Val | undefined),
   }
@@ -107,6 +118,17 @@ abstract class BagVal extends FeatureVal {
       this.mark.hide !== peer.mark.hide) {
       return false
     }
+    // The SPREAD is part of the shape (BUGS.md §52 regime 4): `[]`
+    // and `[&: T]` share an empty key set, and calling them the same
+    // value collapsed the disjunction to its first arm before any
+    // data could pick -- the vacuous-schema hole. Two spreads are the
+    // same when their canons are.
+    const scj: any = (this as any).spread?.cj
+    const pcj: any = peer.spread?.cj
+    if ((null == scj) !== (null == pcj) ||
+      (null != scj && null != pcj && scj.canon !== pcj.canon)) {
+      return false
+    }
 
     const keys = Object.keys(this.peg)
     if (keys.length !== Object.keys(peer.peg).length) {
@@ -157,6 +179,14 @@ abstract class BagVal extends FeatureVal {
         continue
       }
 
+      // An alias declaration contributes no field, and unlike a marked
+      // one it is skipped even under `probe`: the probe descends
+      // through output marks to check what a `--at` anchor really
+      // holds, and an alias is not part of the document at all.
+      if (this.aliasKeys.includes('' + p)) {
+        continue
+      }
+
       const optional = this.optionalKeys.includes('' + p)
 
       // Lists append compactly: a skipped element (hidden, dropped
@@ -192,15 +222,7 @@ abstract class BagVal extends FeatureVal {
       // atom decides, in ConjunctVal.gen. Any OTHER conjunct is
       // unresolved and falls through to the residue error below,
       // exactly as before.
-      else if (child.isScalar
-        || child.isMap
-        || child.isList
-        || child.isPref
-        || child.isRef
-        || child.isDisjunct
-        || child.isNil
-        || undefined !== sizingResidue(child)
-      ) {
+      else if (bagGenable(child)) {
         // An optional child is generated in an isolated collect context so an
         // unresolved inner value (a bare type that survived unification, e.g.
         // an absent optional sub-map's `field: string`) is dropped rather than
@@ -281,3 +303,30 @@ export function sizingResidue(v: any): { con: any, bag: any } | undefined {
   return undefined !== con && (true === bag?.isMap || true === bag?.isList) ?
     { con, bag } : undefined
 }
+
+// bagGenable is the bag's generability whitelist. A graph atom
+// (RELATIONS P2) is exactly as generable as the value it carries: the
+// atom is transparent at generation, so wrapping a field's value in
+// acyclic() must not change whether the bag accepts it -- an unmet
+// rel() refuses required generation with or without the atom, and a
+// BARE atom generates nothing and is dropped, exactly as an unmet
+// rel() under an optional key is.
+export function bagGenable(child: any): boolean {
+  if (true === child.isGraphAtom) {
+    return undefined === child.held || bagGenable(child.held)
+  }
+  // The recursive residual carries its own generation refusal
+  // (recursion_unexpanded), which names the schema and the site --
+  // the bag's generic residue error would bury both.
+  if (true === child.isRecurse) {
+    return true
+  }
+  return true === child.isScalar
+    || true === child.isMap
+    || true === child.isList
+    || true === child.isPref
+    || true === child.isRef
+    || true === child.isDisjunct
+    || true === child.isNil
+    || undefined !== sizingResidue(child)
+}

package/src/val/ConstraintVal.ts

@@ -544,6 +544,16 @@ function stringLeaf(v: any): boolean {
   return true === v?.isScalar && 'string' === typeof v.peg && v.isString
 }
 
+// The VALUE-admission widening of stringLeaf: a path value is a string
+// with more structure (path <: string, ADR-016), so the string-domain
+// constraints admit one -- `refer() & re("auth$")` must still check a
+// link whose value is now a path. The ARGUMENT sites keep the strict
+// test: a pattern, a bound or an exclusion is spelled with a plain
+// string, never a path.
+function stringishLeaf(v: any): boolean {
+  return stringLeaf(v) || (true === v?.isScalar && true === v.isPath)
+}
+
 
 // Scalar identity: leaf AND value, the lattice's own rule (1 and 1.0
 // are different scalars). Exact numeric comparison decides the value
@@ -552,6 +562,12 @@ function sameScalar(a: any, b: any): boolean {
   if (numericLeaf(a) && numericLeaf(b)) {
     return towerRank(a) === towerRank(b) && 0 === cmpNumeric(a, b)
   }
+  if (true === a?.isPath || true === b?.isPath) {
+    // Path identity is kind AND spelling (ADR-016): `neq(path($.x))`
+    // excludes exactly that address, and never a plain string that
+    // happens to spell it.
+    return true === a?.isPath && true === b?.isPath && a.peg === b.peg
+  }
   if (stringLeaf(a) && stringLeaf(b)) {
     return a.peg === b.peg
   }
@@ -745,7 +761,7 @@ class ConstraintVal extends FeatureVal {
       }
       let domain: 'number' | 'string' | undefined = undefined
       for (const a of args) {
-        const d = numericLeaf(a) ? 'number' : stringLeaf(a) ? 'string' : undefined
+        const d = numericLeaf(a) ? 'number' : stringishLeaf(a) ? 'string' : undefined
         if (null == d || (null != domain && d !== domain)) {
           return bad('invalid-arg')
         }
@@ -828,7 +844,7 @@ class ConstraintVal extends FeatureVal {
       return
     }
 
-    const domain = numericLeaf(a) ? 'number' : stringLeaf(a) ? 'string' : undefined
+    const domain = numericLeaf(a) ? 'number' : stringishLeaf(a) ? 'string' : undefined
     if (null == domain) {
       return bad('invalid-arg')
     }
@@ -852,7 +868,20 @@ class ConstraintVal extends FeatureVal {
     // residual is stable and the ladder is total.
     let out: Val
 
-    if (null != this.pending) {
+    // A rel residual or a graph atom HOLDS constraints for the value
+    // they stand for (RELATIONS P1/P2): hand the drive over before
+    // any settling, exactly as a container does, so `rel(t) & re(x)`
+    // reads the same in either order. Reached through the INCLUDE
+    // flow (a loaded schema's conjunct re-drives with the constraint
+    // on the left) -- inline documents route rel/atom peers through
+    // unite's b-drives first, which is why use-cases/12-relations
+    // refused without this arm while every inline row stayed green;
+    // pinned by constraint-hands-drive-to-rel-and-atom.
+    if (true === (peer as any)?.isRel
+      || true === (peer as any)?.isGraphAtom) {
+      out = (peer as any).unify(this, ctx)
+    }
+    else if (null != this.pending) {
       out = this.settle(peer, ctx)
     }
     else if (null != this.invalid) {
@@ -975,7 +1004,7 @@ class ConstraintVal extends FeatureVal {
       // Only a string among the scalars has a length, and it is counted
       // in CODE POINTS -- not UTF-16 units (this host's native count)
       // and not bytes (Go's). Iterating a string yields code points.
-      if (!stringLeaf(peer)) {
+      if (!stringishLeaf(peer)) {
         return this.fail(ctx, peer)
       }
       if (!stateAdmits(this.count, countVal([...peer.peg].length))) {
@@ -1710,7 +1739,7 @@ function constraintAdmitsScalar(
 // the count.
 function stateAdmits(s: ConstraintState, peer: any): boolean {
   const domainOf = numericLeaf(peer) ? 'number' :
-    stringLeaf(peer) ? 'string' : undefined
+    stringishLeaf(peer) ? 'string' : undefined
 
   if (null == s.domain) {
     // A sizing residual has no domain, and admits any scalar the sizing

package/src/val/ContainerKindVal.ts

@@ -0,0 +1,158 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// CONTAINER KINDS (docs/design/PATHS.0.md). `{}` and `[]` are the
+// container UNITS: they admit any map (or list) AND generate empty
+// when nothing arrives. `map()` and `list()` are the container KINDS
+// proper: they admit exactly the same values and default to NOTHING,
+// as `string` does -- the spelling of "this must be a map, and it
+// must be supplied", which the unit cannot say because an unmet unit
+// silently manufactures its empty value.
+//
+// The vacuous call is the kind; the literal is the unit. That is the
+// whole convention, and it is why neither function takes arguments:
+// element constraints already belong to the spreads (`{&: V}`,
+// `[&: V]`), and a second spelling of them here would drift.
+//
+// No null/top/nil arms, as RelVal records: unite's dispatch ladder
+// absorbs those peers before any Val's own unify is consulted, and
+// FuncBaseVal returns a done resolution directly against a top peer.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  DONE,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { makeNilErr } from '../err'
+
+import { FeatureVal } from './FeatureVal'
+import { FuncBaseVal } from './FuncBaseVal'
+
+
+class MapKindVal extends FeatureVal {
+  isContainerKind = true
+  isMapKind = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+    this.dc = DONE
+  }
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const p: any = peer
+    if (true === p.isMap) {
+      return peer
+    }
+    if (true === p.isMapKind) {
+      return this
+    }
+    // The unit's own refusal code: a kind mismatch here is the same
+    // fact `{} & 1` reports, and two codes for one fact would drift.
+    return makeNilErr(ctx, 'map', this, peer)
+  }
+
+  get canon() {
+    return 'map()'
+  }
+
+  same(peer: any): boolean {
+    return true === peer?.isMapKind
+  }
+
+} /* node:coverage ignore next 4 */
+
+
+class ListKindVal extends FeatureVal {
+  isContainerKind = true
+  isListKind = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+    this.dc = DONE
+  }
+
+  unify(peer: Val, ctx: AontuContext): Val {
+    const p: any = peer
+    if (true === p.isList) {
+      return peer
+    }
+    if (true === p.isListKind) {
+      return this
+    }
+    return makeNilErr(ctx, 'list', this, peer)
+  }
+
+  get canon() {
+    return 'list()'
+  }
+
+  same(peer: any): boolean {
+    return true === peer?.isListKind
+  }
+
+} /* node:coverage ignore next 4 */
+
+
+class MapFuncVal extends FuncBaseVal {
+  isMapFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new MapFuncVal(spec)
+  }
+
+  funcname() {
+    return 'map'
+  }
+
+  resolve(ctx: AontuContext, _args: Val[]) {
+    const out = new MapKindVal({}, ctx)
+    out.site = this.site
+    out.path = this.path
+    return out
+  }
+
+} /* node:coverage ignore next 4 */
+
+
+class ListFuncVal extends FuncBaseVal {
+  isListFunc = true
+
+  constructor(spec: ValSpec, ctx?: AontuContext) {
+    super(spec, ctx)
+  }
+
+  make(_ctx: AontuContext, spec: ValSpec): Val {
+    return new ListFuncVal(spec)
+  }
+
+  funcname() {
+    return 'list'
+  }
+
+  resolve(ctx: AontuContext, _args: Val[]) {
+    const out = new ListKindVal({}, ctx)
+    out.site = this.site
+    out.path = this.path
+    return out
+  }
+
+} /* node:coverage ignore next 8 */
+
+
+export {
+  MapKindVal,
+  ListKindVal,
+  MapFuncVal,
+  ListFuncVal,
+}

package/src/val/CopyFuncVal.ts

@@ -65,13 +65,6 @@ class CopyFuncVal extends FuncBaseVal {
         // console.log('WALK', val)
         val.mark.type = false
         val.mark.hide = false
-        // `copy()` CLEARS IDENTITY (G4 phase 1, clearing rule 2),
-        // consistent with its clearing of the marks: a copy of an
-        // entity is a second value shaped like it, and leaving the id
-        // on would merge the copy straight back into the original —
-        // making `copy()` a no-op for exactly the values it exists to
-        // detach.
-        val.entity = undefined
         return val
       })
     }