aontu 0.52.1 → 0.54.0

package/src/lang.ts

@@ -3,6 +3,19 @@
 
 // import { performance } from 'node:perf_hooks'
 
+// Named imports, not `import * as`: the namespace form makes tsc emit
+// the __importStar downlevel helper, whose branches no supported Node
+// takes (the same rule cli.ts records). Aliased because `Path` is
+// already the @tabnas/path plugin below.
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import {
+  basename as pathBasename,
+  dirname as pathDirname,
+  join as pathJoin,
+  resolve as pathResolve,
+  sep as pathSep,
+} from 'node:path'
+
 import {
   Jsonic,
   Tabnas,
@@ -14,6 +27,20 @@ import {
 } from '@tabnas/jsonic'
 
 
+// THE CONFIG-FORMAT READERS (ADR-012). Each is a jsonic plugin for one
+// format, so an included `.toml` or `.yaml` is parsed by a real parser
+// for that format rather than guessed at by this one. `@tabnas/json` is
+// the strict RFC 8259 reader, used for `.json` and `.jsonld`.
+import { funcSig } from './sig'
+import type { FuncSig } from './sig'
+
+import { make as makeJsonParser } from '@tabnas/json'
+import { Toml } from '@tabnas/toml'
+import { Jsonc } from '@tabnas/jsonc'
+import { Json5 } from '@tabnas/json5'
+import { Yaml } from '@tabnas/yaml'
+import { Ini } from '@tabnas/ini'
+
 import { Debug } from '@tabnas/debug'
 
 import {
@@ -34,6 +61,21 @@ import {
   makeMemResolver
 } from '@tabnas/multisource/resolver/mem'
 
+// The Aontu-source processor, TAKEN RATHER THAN ALIASED. The obvious
+// spelling is the alias `aon: 'jsonic'`, which multisource resolves
+// through its own processor map -- but `jsonic` is a FORMAT NAME in
+// the include table now, so that alias resolved to the plain-jsonic
+// DATA reader and every `.aon` include was suddenly parsed without the
+// language in it. Naming the function leaves nothing to collide with.
+import {
+  makeJsonicProcessor,
+} from '@tabnas/multisource/processor/jsonic'
+
+import { STD_SOURCES } from './std'
+import {
+  parseModuleRef, resolveModule, modCacheDir, MODULE_REFUSAL_CODES,
+} from './mod'
+
 import {
   Expr,
   Op,
@@ -96,8 +138,23 @@ import { CopyFuncVal } from './val/CopyFuncVal'
 import { KeyFuncVal } from './val/KeyFuncVal'
 import { TypeFuncVal } from './val/TypeFuncVal'
 import { HideFuncVal } from './val/HideFuncVal'
+import { DeprecateFuncVal } from './val/DeprecateFuncVal'
+import { ReferFuncVal, RelFuncVal } from './val/ReferFuncVal'
+import { AcyclicFuncVal, InverseFuncVal } from './val/GraphAtomVal'
+import { PackFuncVal } from './val/PackFuncVal'
+import { EachFuncVal } from './val/EachFuncVal'
+import { FilterFuncVal } from './val/FilterFuncVal'
+import { MatchFuncVal } from './val/MatchFuncVal'
+import {
+  AddFuncVal, SubFuncVal, MulFuncVal, DivFuncVal, ModFuncVal, RemFuncVal,
+} from './val/ArithFuncVal'
+import {
+  SumFuncVal, LeastFuncVal, GreatestFuncVal, PickFuncVal, JoinFuncVal,
+} from './val/AggFuncVal'
+import { PlaceVal } from './val/PlaceVal'
 import { MoveFuncVal } from './val/MoveFuncVal'
 import { PathFuncVal } from './val/PathFuncVal'
+import { MapFuncVal, ListFuncVal } from './val/ContainerKindVal'
 import { PrefFuncVal } from './val/PrefFuncVal'
 import { CloseFuncVal } from './val/CloseFuncVal'
 import { OpenFuncVal } from './val/OpenFuncVal'
@@ -158,6 +215,13 @@ const CC_0 = 48
 const CC_d = 100
 const CC_D = 68
 
+// THE ALIAS SIGIL. `%` is part of an alias's name, so the name is one
+// lexeme wherever it appears and its meaning is decided by position:
+// a BINDING in key position (`%uint8: …` declares), a USE in value
+// position (`listen: %uint8` refers). docs/design/ALIASES.0.md §4.
+const CC_PCT = 37
+const ALIAS_RE = /^%[A-Za-z_][A-Za-z0-9_]*/
+
 let AontuJsonic: Plugin = function AontuLang(jsonic: Jsonic) {
 
   jsonic.use(asPlugin(Path))
@@ -169,6 +233,38 @@ let AontuJsonic: Plugin = function AontuLang(jsonic: Jsonic) {
   let dotRef = (r: Rule, ctx: JsonicContext, terms: any, prefix: boolean) => {
     terms = dropUnfilled(terms)
     if (0 === terms.length) return incompleteNil(r, ctx)
+
+    // AN ALIAS IS NOT A PATH SEGMENT. `$.%foo` is refused: the alias
+    // namespace and the path namespace are disjoint, and an alias is
+    // reached by writing `%foo` and only that.
+    //
+    // The engine spells an alias reference AS a root reference to the
+    // declaration -- which is what gives it order independence and a
+    // cycle check shared with paths -- but that is an implementation of
+    // the name, not a second way to write it. Left writable, the two
+    // spellings would drift apart the moment aliases stop being
+    // file-shaped, and `$.%b` inside an included file would reach the
+    // INCLUDER's `%b` rather than its own, which is exactly the
+    // cross-file capture the sigil exists to prevent.
+    // `%foo` lexes to the reference itself, so in `$.%foo` it arrives
+    // as a TERM rather than as a string segment -- both shapes are
+    // checked, since a quoted `$."%foo"` would arrive as the string.
+    // Terms here are always Vals -- dropUnfilled has removed the
+    // nulls, and the dot rules never hand over a raw string -- so the
+    // shapes are exactly three: a RefVal (peg is the segment array), a
+    // StringVal (peg is the segment), and anything else (a numeric or
+    // exact segment, which cannot be an alias name).
+    for (const t of terms) {
+      const segs: any[] =
+        Array.isArray(t.peg) ? t.peg :
+          ('string' === typeof t.peg ? [t.peg] : [])
+      for (const seg of segs) {
+        if ('string' === typeof seg && ALIAS_RE.test(seg)) {
+          return addsite(new NilVal({ why: 'alias_in_path' }), r, ctx)
+        }
+      }
+    }
+
     return addsite(new RefVal({ peg: terms, prefix }), r, ctx)
   }
 
@@ -243,9 +339,47 @@ let AontuJsonic: Plugin = function AontuLang(jsonic: Jsonic) {
       check: (lex: any) => {
         // Guard first, on char codes: this hook runs at every text
         // position, and the common case (any run that cannot be a `0d`
-        // literal) must cost two char reads and no allocation.
+        // literal or an alias) must cost two char reads and no
+        // allocation.
         const pnt = lex.pnt
         const src = lex.src
+
+        // AN ALIAS NAME IS CLAIMED WHOLE, for the same reason the `0d`
+        // run below is: the text matcher's ender regexp would otherwise
+        // carve `%uint8` at the `%` and emit the sigil as its own token,
+        // leaving a bare `uint8` behind -- which is exactly the capture
+        // the sigil exists to prevent. Claiming it here, before that
+        // ender runs, keeps the name one lexeme.
+        //
+        // The token's SOURCE is the whole `%name`, which is what makes
+        // the same lexeme work in both positions: jsonic keys a pair by
+        // the token's source text (`0d1: 5` yields the key `0d1`), so a
+        // declaration reads as the key `%uint8`, while a value position
+        // calls the function below and gets the reference.
+        if (CC_PCT === src.charCodeAt(pnt.sI)) {
+          const ares = ALIAS_RE.exec(lex.refwd())
+          if (null == ares) {
+            return undefined
+          }
+          const asrc = ares[0]
+          const atkn = lex.token(
+            '#VL',
+            // AN ALIAS REFERENCE IS A PATH REFERENCE. `%uint8` is
+            // `$.%uint8`: root-absolute, one segment, spelled with the
+            // sigil the declaration is spelled with. Everything the
+            // design asks of it -- order independence, alias-of-alias,
+            // redeclaration unifying, cycle refusal spanning both
+            // namespaces -- is then the reference machinery already in
+            // the language, not a second resolver beside it.
+            (r: Rule, ctx: JsonicContext) =>
+              addsite(new RefVal({ peg: [asrc], absolute: true }), r, ctx),
+            asrc,
+            pnt)
+          pnt.sI += asrc.length
+          pnt.cI += asrc.length
+          return { done: true, token: atkn }
+        }
+
         if (CC_0 !== src.charCodeAt(pnt.sI)) {
           return undefined
         }
@@ -287,6 +421,16 @@ let AontuJsonic: Plugin = function AontuLang(jsonic: Jsonic) {
     v.site.row = null == r.o0 ? -1 : r.o0.rI
     v.site.col = null == r.o0 ? -1 : r.o0.cI
     v.site.url = ctx.meta.multisource ? ctx.meta.multisource.path : ''
+    // The source text, from the SAME token the row and column above
+    // come from. jsonic has carried it all along; not reading it is
+    // what left a site uneditable (ts/src/site.ts).
+    //
+    // A TOKEN WITH NO TEXT IS NO SPAN, in both ports, and the extent is
+    // DERIVED from the text rather than read from the token's own `len`
+    // — so the Go twin, whose token has no len field, computes the
+    // identical number with utf16Len and nothing has to be kept in step.
+    v.site.src = null == r.o0 ? '' : r.o0.src
+    v.site.len = '' === v.site.src ? -1 : v.site.src.length
     // A keyed rule always carries a path array; a keyless one has none.
     v.path = r.k ? [...r.k.path] : []
 
@@ -365,6 +509,14 @@ help isolate the syntax error.`,
 
         // TODO: FIX: need a TOP instance to hold path
         'top': { val: () => top() },
+
+        // G8 phase 3: the placeholder. A BARE `_` is the hole; `"_"`
+        // quoted, and any longer bare word containing it, stay text.
+        // Reserving it is a breaking change, pinned by place.tsv.
+        '_': {
+          val: (r: Rule, ctx: JsonicContext) =>
+            addsite(new PlaceVal({}), r, ctx)
+        },
       }
     },
 
@@ -411,6 +563,14 @@ help isolate the syntax error.`,
     move: MoveFuncVal,
     path: PathFuncVal,
     pref: PrefFuncVal,
+
+    // First-class paths and the container kinds
+    // (docs/design/PATHS.0.md). `path(p)` CAPTURES a path as a value;
+    // `path()`, `map()` and `list()` are kinds -- the vacuous
+    // constructor call admits its values and defaults to nothing,
+    // where the container LITERALS `{}`/`[]` default to empty.
+    map: MapFuncVal,
+    list: ListFuncVal,
     close: CloseFuncVal,
     open: OpenFuncVal,
     super: SuperFuncVal,
@@ -441,6 +601,72 @@ help isolate the syntax error.`,
     // reported with the author's own message, never simplified and
     // never consulted for emptiness or subsumption.
     must: MustConstraintVal,
+
+    // G3 phase 4: the deprecation mark. Unification-transparent; the
+    // record rides the result (Val.deprecation) and canon renders the
+    // call back (canonRiders).
+    deprecate: DeprecateFuncVal,
+
+    // G4 phase 2: the checked, typed, LINK-shaped reference. A
+    // constraint on a string field: the string must be a TREE ADDRESS
+    // (`$.a.b` or `.b`), the address must resolve, and the optional
+    // argument flows INTO the target. The field keeps the string.
+    refer: ReferFuncVal,
+    rel: RelFuncVal,
+
+    // RELATIONS P2 (docs/design/RELATIONS.0.md §3.3): the graph
+    // atoms, conjoined at the field whose key is the predicate they
+    // govern. Lattice-inert; the verdict lands at generation.
+    acyclic: AcyclicFuncVal,
+    inverse: InverseFuncVal,
+
+    // G8 phase 1: the generation combinators. `pack` makes one keyed
+    // child per child of its data, `each` one list element; both clone
+    // their template per destination exactly as a spread does, and both
+    // wait for the model to settle before they fire (the staging rule,
+    // G8 phase 0).
+    pack: PackFuncVal,
+    each: EachFuncVal,
+
+    // G8 phase 2: selection. `filter` keeps the children of a bag that
+    // unify with a condition; `match` picks the first arm whose
+    // pattern the scrutinee unifies with. Both select by
+    // UNIFIABILITY, tried in trial mode, so neither adds a predicate
+    // language to the one the lattice already is.
+    filter: FilterFuncVal,
+    match: MatchFuncVal,
+
+    // The arithmetic family (the review's finding I). Maths beyond `+`
+    // arrives as FUNCTIONS — `-` `*` `/` `%` stay reserved — and the
+    // family is numeric where the operator is polymorphic, which is
+    // what makes `add` more than a second spelling of `+`: it refuses
+    // the string concatenation that silently answers `"500m" + "500m"`.
+    // Every rule they obey is in ts/src/val/arith.ts.
+    add: AddFuncVal,
+    sub: SubFuncVal,
+    mul: MulFuncVal,
+    div: DivFuncVal,
+    mod: ModFuncVal,
+    rem: RemFuncVal,
+
+    // Aggregation over a finite, settled bag (the review's finding I).
+    // `least` and `greatest` rather than min and max, which are already
+    // the atoms for a lower and an upper BOUND -- an aggregate over a
+    // set and a bound on a value must not share a spelling.
+    sum: SumFuncVal,
+    least: LeastFuncVal,
+    greatest: GreatestFuncVal,
+
+    // Projection, which is what lets the aggregates reach a bag of
+    // RECORDS: `sum(pick($.lines, amountCents))`. Not a clever `each`
+    // template -- `each` MEETS each child, and a meet cannot select.
+    pick: PickFuncVal,
+
+    // G9 phase 2: the fold to a STRING. `sum` folds with `add`; this
+    // folds with `+`, so it inherits the one number-to-text rule and
+    // the language does not grow a second. It is the primitive that
+    // turns a bag of computed lines into a file.
+    join: JoinFuncVal,
   }
 
 
@@ -454,6 +680,74 @@ help isolate the syntax error.`,
   const incompleteNil = (r: Rule, ctx: JsonicContext) =>
     addsite(new NilVal({ why: 'incomplete_expression' }), r, ctx)
 
+  // Build a call from a NAME and the argument terms as the author
+  // wrote them: the arity check, the comma-group rule and the
+  // raw-value conversion, stated once.
+  const buildCall = (r: Rule, ctx: JsonicContext,
+    fname: string, argterms: any[]): any => {
+    const funcval = funcMap[fname]
+
+    // Arity is known for every built-in, so a surplus or missing
+    // argument is a mistake in the SOURCE, refused here where the
+    // author can see it (issue #51). It was previously left to each
+    // function to notice or not: the two ports disagreed on `upper()`
+    // and on `close()`, and `min(1,2)` noticed nothing at all -- it
+    // built a constraint that merely refused to generate later, with a
+    // message about the map rather than about the call.
+    //
+    // Counted BEFORE the rawToVal pass below, which is what makes the
+    // count possible: a comma group arrives as a RAW array and a
+    // written list literal as a ListVal, and rawToVal turns the first
+    // into the second.
+    const arity = funcArity[fname]
+    if (null != arity) {
+      const got = writtenArgCount(argterms)
+      if (got < arity[0] || (-1 !== arity[1] && got > arity[1])) {
+        // details is assigned AFTER construction: the NilVal
+        // constructor does not read it from its spec (only NilVal.make
+        // does), so passing it in the spec left the hint's
+        // {func}/{want}/{got} placeholders un-injected and printed
+        // literally.
+        const nil: any = new NilVal({ why: 'func_arity' })
+        nil.details = {
+          func: fname,
+          want: arityText(arity[0], arity[1]),
+          got: '' + got,
+        }
+        return addsite(nil, r, ctx)
+      }
+    }
+
+    // rawToVal EVERY argument. A degenerate expression can hand this
+    // handler raw parse values rather than Vals -- `pref(1-3)` arrives
+    // as the plain numbers 1 and -3 -- and a func's peg is unified
+    // element by element, so a raw one reached `arg.unify(...)` and
+    // threw. The unifier's catch-all turned that into an `internal`
+    // verdict: a crash reported as a unification result (issue #49).
+    // The Go port has always converted here (asVal in evaluate).
+    // A comma group is ONE raw-array term (see writtenArgCount).
+    // For a function whose arguments are distinct POSITIONS —
+    // deprecate's value and record, pack's and each's data and template
+    // — the group is expanded back into them here, while a written list
+    // literal, already a ListVal, stays one argument. The constraint
+    // atoms make the same move in their own constructor (atomArgs,
+    // ConstraintVal.ts), which is why they are not in this set:
+    // `neq(1,2)` is one argument LIST, not two positions, and expanding
+    // it here would take the list away from the code that reads it.
+    let terms = argterms
+    if (true === POSITIONAL_ARG_FUNCS[fname] && 1 === terms.length &&
+      Array.isArray(terms[0])) {
+      terms = terms[0]
+    }
+    const args = terms.map(rawToVal)
+    const val: any = null == funcval ?
+      new NilVal({ why: 'unknown_function' }) :
+      new funcval({ peg: args })
+
+    return val
+  }
+
+
   let opmap: any = {
     'conjunct-infix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) =>
       addsite(new ConjunctVal({ peg: dropUnfilled(terms) }), r, ctx),
@@ -472,11 +766,50 @@ help isolate the syntax error.`,
 
     'star-prefix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) => {
       if (null == terms[0]) return incompleteNil(r, ctx)
+
+      // A PREFERENCE MARKS A VALUE, AND A BARE KEY IS NOT ONE.
+      // `*a: 1` has no braces, so the prefix took the whole IMPLICIT
+      // map as its operand and the document silently became
+      // `*{"a":1}` -- `*a: 1, b: 2` became a one-element LIST, losing
+      // `b` outright. Neither is anything the author wrote.
+      //
+      // The accident is confined to the first position of the implicit
+      // top-level map, which is the only place no brace has yet
+      // committed the rule to a map: `{*a: 1}` and `a: 1, *b: 2` are
+      // ALREADY parse errors. This makes the third spelling agree with
+      // them rather than inventing a meaning for it.
+      //
+      // A BRACED operand is untouched, and that is the whole of the
+      // distinction: `*{x:1}` and `*[1]` are the real spelling, they
+      // are what `*{x:1} | *{y:2}` needs, and the shared spec pins them
+      // (11 rows). The open token's own source text is what separates
+      // the two -- `{` or `[` for a braced bag, the first key or
+      // element for an implicit one.
+      const bag: any = terms[0]
+      if ((bag.isMap && '{' !== bag.site.src) ||
+        (bag.isList && '[' !== bag.site.src)) {
+        return addsite(new NilVal({ why: 'pref_implicit_bag' }), r, ctx)
+      }
+
       return addsite(new PrefVal({ peg: terms[0] }), r, ctx)
     },
 
     'dollar-prefix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) => {
       if (null == terms[0]) return incompleteNil(r, ctx)
+      // A refusal from the dot rule below (an alias used as a path
+      // segment) rides straight through: wrapping it in a VarVal would
+      // replace `alias_in_path` with a var whose peg is a nil.
+      if (terms[0]?.isNil) {
+        return terms[0]
+      }
+      // `$%foo` -- the sigil directly after the root -- reaches here
+      // as the alias reference rather than through the dot rule, and
+      // is refused for the same reason.
+      if (terms[0] instanceof RefVal &&
+        terms[0].peg.some((seg: any) =>
+          'string' === typeof seg && ALIAS_RE.test(seg))) {
+        return addsite(new NilVal({ why: 'alias_in_path' }), r, ctx)
+      }
       // $.a.b absolute path
       if (terms[0] instanceof RefVal) {
         terms[0].absolute = true
@@ -538,50 +871,7 @@ help isolate the syntax error.`,
       const fname = terms[0]
 
       if ('' !== fname) {
-        const funcval = funcMap[fname]
-        // Arity is known for every built-in, so a surplus or missing
-        // argument is a mistake in the SOURCE, refused here where the
-        // author can see it (issue #51). It was previously left to each
-        // function to notice or not: the two ports disagreed on `upper()`
-        // and on `close()`, and `min(1,2)` noticed nothing at all -- it
-        // built a constraint that merely refused to generate later, with
-        // a message about the map rather than about the call.
-        //
-        // Counted BEFORE the rawToVal pass below, which is what makes the
-        // count possible: a comma group arrives as a RAW array and a
-        // written list literal as a ListVal, and rawToVal turns the first
-        // into the second.
-        const arity = funcArity[fname]
-        if (null != arity) {
-          const got = writtenArgCount(terms.slice(1))
-          if (got < arity[0] || (-1 !== arity[1] && got > arity[1])) {
-            // details is assigned AFTER construction: the NilVal
-            // constructor does not read it from its spec (only
-            // NilVal.make does), so passing it in the spec left the
-            // hint's {func}/{want}/{got} placeholders un-injected and
-            // printed literally.
-            const nil: any = new NilVal({ why: 'func_arity' })
-            nil.details = {
-              func: fname,
-              want: arityText(arity[0], arity[1]),
-              got: '' + got,
-            }
-            return addsite(nil, r, ctx)
-          }
-        }
-        // rawToVal EVERY argument. A degenerate expression can hand this
-        // handler raw parse values rather than Vals -- `pref(1-3)` arrives
-        // as the plain numbers 1 and -3 -- and a func's peg is unified
-        // element by element, so a raw one reached `arg.unify(...)` and
-        // threw. The unifier's catch-all turned that into an `internal`
-        // verdict: a crash reported as a unification result (issue #49).
-        // The Go port has always converted here (asVal in evaluate).
-        const args = terms.slice(1).map(rawToVal)
-        val = null == funcval ?
-          new NilVal({ why: 'unknown_function' }) :
-          new funcval({
-            peg: args
-          })
+        val = buildCall(r, ctx, fname, terms.slice(1))
       }
       // `a:()` — grouping parens with nothing inside.
       if (null == val) return incompleteNil(r, ctx)
@@ -708,6 +998,8 @@ help isolate the syntax error.`,
 
   const QM = jsonic.token.QM
 
+  const VL = jsonic.token.VL
+
   const OPTKEY = [TX, ST, NR]
 
 
@@ -818,6 +1110,13 @@ help isolate the syntax error.`,
           valnode.site.row = st.rI
           valnode.site.col = st.cI
           valnode.site.url = ctx.meta.multisource && ctx.meta.multisource.path
+          // No `?? ''` and no empty-text arm here: this branch runs only
+          // for a rule that HAS an open token, and a token that opens a
+          // value always carries text — the coverage gate refuses both
+          // guards as dead. The unset case is the one above, where r.o0
+          // itself can be absent.
+          valnode.site.src = st.src
+          valnode.site.len = st.src.length
         }
         // else { ERROR? }
 
@@ -842,6 +1141,7 @@ help isolate the syntax error.`,
 
       .bc((r: Rule, ctx: JsonicContext) => {
         const optionalKeys = r.u.aontu_optional_keys ?? []
+        const aliasKeys = r.u.aontu_alias_keys ?? []
 
         let mo = r.node
 
@@ -908,6 +1208,7 @@ help isolate the syntax error.`,
           // TODO: needs addpath?
           let mopv = new MapVal({ peg: mop })
           mopv.optionalKeys = optionalKeys
+          mopv.aliasKeys = aliasKeys
 
           r.node =
             addsite(new ConjunctVal({ peg: [mopv, ...mo.___merge] }), r, ctx)
@@ -915,6 +1216,7 @@ help isolate the syntax error.`,
         else {
           r.node = addsite(new MapVal({ peg: mo }), r, ctx)
           r.node.optionalKeys = optionalKeys
+          r.node.aliasKeys = aliasKeys
         }
 
         return undefined
@@ -1065,6 +1367,33 @@ help isolate the syntax error.`,
       .bc((rule: Rule) => {
         // TRAVERSE PARENTS TO GET PATH
 
+        // A DECLARATION IS A PAIR WHOSE KEY IS AN ALIAS NAME. The lexer
+        // claims `%name` whole and hands it over as a #VL token whose
+        // SOURCE is the name, so the key TEXT alone cannot be the test:
+        // a quoted `"%a": 1` is an ordinary key that merely starts with
+        // the sigil, and erasing that would be wrong. The token is what
+        // separates them.
+        //
+        // Recorded on the enclosing map, never on the value, and that is
+        // the point: a reference COPIES the value it resolves to, so a
+        // mark riding the value would erase the referring field too.
+        // Being a property of the map is also what carries it through a
+        // meet, the way optional keys are carried.
+        const ktkn: any = rule.o0
+        if (null != ktkn && VL === ktkn.tin && ALIAS_RE.test('' + ktkn.src)) {
+          const holder: any = rule.parent
+          const aname = '' + ktkn.src
+
+          // Always recorded here; whether the map is ALLOWED to carry
+          // declarations is decided on the VALUE (MapVal.unify), not at
+          // the parse. 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.
+          holder.u.aontu_alias_keys = (holder.u.aontu_alias_keys || [])
+          holder.u.aontu_alias_keys.push(aname)
+        }
+
         if (rule.u.spread) {
           rule.node[SPREAD] =
             (rule.node[SPREAD] || { o: rule.o0.src, v: [] })
@@ -1110,7 +1439,10 @@ help isolate the syntax error.`,
           s: [QM, CL],
           c: (r) => r.prev.u.aontu_optional,
           p: 'val',
-          u: { spread: true, done: true, list: true, pair: true },
+          u: {
+            spread: true, done: true, list: true, pair: true,
+            aontu_optional_elem: true,
+          },
           a: (r) => {
             pairkey(r.prev)
             r.u.key = r.prev.u.key
@@ -1119,18 +1451,17 @@ help isolate the syntax error.`,
           g: 'aontu-optional-elem'
         },
 
-        // A PLAIN pair in list position, `[k:v]`. It contributes no
-        // element either -- a key:value pair is simply not a list element,
-        // which is the rule the optional form above already followed, and
-        // the two spellings must not disagree (issue #40).
-        //
-        // It needed an alt of its own because only a NON-NUMERIC key was
-        // already inert: jsonic writes the pair at `node[key]`, and the
-        // node is an array, so `[x:1]` set a property that never showed up
-        // (`length` stays 0) while `[0:1]` set an INDEX and became an
-        // element -- `[1:2]` even filling the gap with a null. That is the
-        // shape of a JavaScript array, not a decision about the language,
-        // and it made the two ports disagree on generate as well as canon.
+        // A PLAIN pair in list position IS A SINGLE-KEY MAP ELEMENT:
+        // `[a:1, b:2]` is `[{a:1}, {b:2}]` (the rule @tabnas/jsonic
+        // spells as `list.pair`). This REVERSES issue #40's "a pair is
+        // not an element": that rule was chosen because jsonic wrote
+        // the pair at `node[key]` -- an array PROPERTY that never
+        // showed up for a text key and an INDEX for a numeric one --
+        // and inert beat that incoherence. But inert was itself a
+        // silent drop: `x: [a:1, b:2]` evaluated to `x: []`, the
+        // author's data gone at exit 0. The element is built in the
+        // bc below, where the value is already a Val; the snapshot
+        // still neutralises jsonic's raw slot write first.
         {
           s: [OPTKEY, CL], p: 'val',
           u: { spread: true, done: true, list: true, pair: true },
@@ -1143,17 +1474,109 @@ help isolate the syntax error.`,
       ])
 
 
-      .bc((rule: Rule) => {
+      // NOTE: manually adjust path - the twin of the `pair` rule's hook
+      // above, and for the same reason, one layer down.
+      //
+      // Every alt above contributes NO element: a `&:` spread is a
+      // constraint on the elements, and a `k:v` pair in list position is
+      // simply not one (the `aontu-plain-pair-elem` note above). The array
+      // slot they briefly occupy is already given back by
+      // restorePairSlot. The PATH index was not: @tabnas/path's
+      // `@elem-ao` increments `r.k.index` for every elem rule it sees, so
+      // each of these stole an index and every later element's path was
+      // one too high — `[&: integer, 10, 20, "bad"]` reported the bad
+      // value at `$.l.3` while `aontu get $.l.2` returned it, and on a
+      // one-element list the path pointed off the end. Generation was
+      // never wrong, which is why nothing caught it: the array is right
+      // and only the labels on it were shifted (BUGS.md 44).
+      //
+      // Rewinding here rather than in the plugin keeps the plugin's rule
+      // ("in an array, the path property is the element index") true —
+      // these alts are the aontu-specific exceptions to what counts as an
+      // element, so the correction belongs with the grammar that
+      // introduces them. The child is re-pathed because the plugin has
+      // already stamped it with the index being given back: a spread
+      // takes the `'&'` segment its map twin takes, and a pair takes its
+      // key, as a map entry would.
+      .ao((r) => {
+        // A pair IS an element now, so it keeps the index @tabnas/path
+        // gave it, and its VALUE is pathed through both the index and
+        // the key (`[a: $.nope]` fails at $.l.0.a). Only the `&:`
+        // spread still contributes no element and gives its index back
+        // (BUGS.md 44).
+        if (0 < r.d && r.u.spread && !r.u.pair) {
+          r.k.index = r.k.index - 1
+
+          const seg = '&'
+          r.child.k.path = [...r.k.path, seg]
+          r.child.k.key = seg
+        }
+        else if (0 < r.d && r.u.pair) {
+          // The element's index is the array length: everything before
+          // it is already pushed, and the pair's own map is pushed at
+          // close. `r.k.index` is not usable here -- the path plugin
+          // counts only the elements it pushes itself, and this one is
+          // aontu's.
+          const seg = '' + r.u.key
+          r.child.k.path =
+            [...r.k.path, '' + (r.node?.length ?? 0), seg]
+          r.child.k.key = seg
+        }
+      })
+
+      .bc((rule: Rule, ctx: JsonicContext) => {
         // TRAVERSE PARENTS TO GET PATH
 
-        if (rule.u.spread) {
+        // Only the `&:` alternative is a SPREAD. All four alts above set
+        // `spread: true` -- it is what marks them as contributing no
+        // element -- so this guard needs the narrower test, and `pair`
+        // is what distinguishes a `k:v` in list position from a spread.
+        //
+        // Without it a pair BUILT the spread record, with `o` taken from
+        // its own key rather than '&': `[x:1, &:integer, "bad"]` left
+        // `{o:'x', v:[1, integer]}`, and ListVal's `'&' === spread.o`
+        // then discarded the real constraint -- so the element spread
+        // was silently dropped and the bad value generated (BUGS.md 46).
+        // A pair alone did it too: `[x:1, 10]` produced a spread record
+        // out of nothing.
+        if (rule.u.spread && !rule.u.pair) {
           rule.node[SPREAD] =
             (rule.node[SPREAD] || { o: rule.o0.src, v: [] })
           rule.node[SPREAD].v.push(rule.child.node)
         }
 
+        // The slot is given back BEFORE the element is added: the
+        // restore undoes jsonic's raw write (a property for a text
+        // key, an INDEX for a numeric one -- restoring length is what
+        // keeps `[1:2]` from padding with a null), and the push then
+        // appends cleanly after it.
         restorePairSlot(rule)
 
+        // THE SINGLE-KEY MAP ELEMENT, for both pair spellings. The
+        // value is a Val already (`p: 'val'`), so the map is built
+        // exactly as the map rule builds one -- and an elided value
+        // (`[a:]`) is refused exactly as the map rule refuses one
+        // (issue #48): a key with nothing after the colon is a
+        // mistake, not an empty value.
+        if (true === rule.u.pair) {
+          const key = '' + rule.u.key
+          let v: any = rule.child.node
+          if (null == v) {
+            v = addsite(new NilVal({ why: 'elided_value' }), rule, ctx)
+            v.path = [...(rule.k?.path ?? []),
+              '' + rule.node.length, key]
+          }
+          const mv: any = addsite(
+            new MapVal({ peg: { [key]: v } }), rule, ctx)
+          // `[a?: 1]` is `[{a?: 1}]`: the key is optional IN the
+          // element, so the two spellings stay one rule apart rather
+          // than two behaviours apart.
+          if (true === rule.u.aontu_optional_elem) {
+            mv.optionalKeys = [key]
+          }
+          rule.node.push(mv)
+        }
+
         return undefined
       })
 
@@ -1166,19 +1589,231 @@ help isolate the syntax error.`,
 
 
 
-// SECURITY: the default resolver reads any file/package the process can
-// reach — @"path" follows relative paths (`@"../../etc/passwd"`) and
-// symlinks with no containment check, and @"pkg" can require() arbitrary
-// installed modules. This is intentional for the CLI, but it means a
-// `.aon` source can read referenced files; the LSP uses this same
-// resolver, so treat opening an untrusted source as running it. Pass a
-// confined `options.resolver` to restrict reads in less-trusted contexts.
+// INCLUDE_KINDS IS THE RULE FOR WHAT AN INCLUDE MEANS (ADR-012,
+// use-cases/BUGS.md §49). An extension is on this list or it is not
+// read at all, and its entry says WHICH OF TWO THINGS the file is.
+//
+// `source` — Aontu, with everything the language has: types, defaults,
+// references, constraints, its own includes. Two extensions, and they
+// are the ones this project owns.
+//
+// A FORMAT NAME — configuration DATA, parsed by that format's own
+// parser into the JSON value it denotes, which then becomes Aontu
+// values like any other data. Every one of these formats maps onto
+// JSON, which is why one word covers them: a `.toml` file is a map of
+// scalars, lists and maps, and so is the `.aon` file that unifies with
+// it. What the format does NOT get is the language — a `&` in a YAML
+// file is a YAML anchor, not a spread key, because the YAML parser
+// reads it, not this one.
+//
+// The parsers are @tabnas's, one per format, and the Go port uses the
+// same ones (ADR-001): the two implementations agree because they are
+// running the same grammar, not because two hand-written readers were
+// kept in step.
+//
+// This table and go/source.go's includeKinds are the same table.
+const INCLUDE_KINDS: { [kind: string]: string } = {
+  aon: 'source',
+  aontu: 'source',
+
+  json: 'json',
+  // JSON-LD is JSON: a `@context` is a key like any other here, and
+  // what it MEANS is the vocabulary's business, not the reader's.
+  jsonld: 'json',
+  jsonc: 'jsonc',
+  json5: 'json5',
+  jsonic: 'jsonic',
+  jsc: 'jsonic',
+  toml: 'toml',
+  yaml: 'yaml',
+  yml: 'yaml',
+  ini: 'ini',
+}
+
+// `.csv` IS DELIBERATELY ABSENT, and the reason is ADR-001 rather than
+// taste. The two ports' CSV parsers disagree about what a CSV file IS:
+// one answers header-keyed records with string fields, the other raw
+// rows including the header, with numbers parsed. Admitting it would
+// admit a divergence into the one thing this project refuses to have
+// one in. Recorded in ADR-012 and pinned by file.tsv's load-ext-csv.
+
+// The multisource kind of a path: the LAST segment's extension, without
+// its dot, lowercased -- `''` for a name that has none. The rule is
+// @tabnas/multisource's own extKind (and Go's filepath.Ext), copied
+// rather than imported because it decides what a source IS: a dot in a
+// parent folder (`/my.app/conf`) must not read as an extension.
+function extKindOf(full: string): string {
+  const seg = (full.match(/[^\\/]*$/) as string[])[0]
+  return (seg.match(/\.([^.]*)$/) || ['', ''])[1].toLowerCase()
+}
+
+// The refusal message, naming the extension -- because the extension is
+// the whole reason, and a reader told only "not readable" has to guess
+// which part of the path the engine objected to. Byte-identical to Go's
+// extensionMsg.
+function extensionMsg(path: string, ext: string): string {
+  const which = '' === ext ? 'no extension' : 'extension: .' + ext
+  return 'include not readable: ' + path + ' (' + which + ')'
+}
+
+// THE RULE ALSO HOLDS FOR A RESOLVER THIS ENGINE DID NOT WRITE.
+// gateExtension refuses an unlisted extension inside makeModelResolver,
+// which is the default; a HOST may supply its own through
+// `AontuOptions.resolver`, and that one has never heard of
+// INCLUDE_KINDS. Without this the host's resolution would fall to
+// multisource's own default for an unnamed kind, which hands the file
+// back as TEXT — or, for `.js`, EXECUTES it. So the two roads end in
+// one place: whatever chose the source, an extension off the list is
+// refused with the same code and the same message.
+const refuseProcessor = (res: any) => {
+  // `full` is the one part a host resolution may leave out -- it is the
+  // path the resolver CHOSE, and a resolver that answers from something
+  // other than a filesystem need not have one. The written path always
+  // reaches here, so it is the fallback.
+  const err: any = new Error(extensionMsg(res.path, extKindOf(res.full ?? res.path)))
+  err.code = 'include_extension'
+  throw err
+}
+
+
+// ONE READER PER FORMAT, BUILT ONCE. These are stateless parsers and
+// building a jsonic instance is not free, so they are made at module
+// load rather than per include. The file name is passed through so a
+// syntax error inside an included `.toml` names the `.toml`.
+const DATA_READERS: { [format: string]: (src: string, fileName: string) => any } =
+  (() => {
+    const viaPlugin = (plugin: any) => {
+      const jsonic = Jsonic.make().use(plugin)
+      return (src: string, fileName: string) => jsonic(src, { fileName })
+    }
+    const toml = viaPlugin(Toml)
+    // The strict RFC 8259 reader is its own parser rather than a
+    // plugin, and it is `make().parse` rather than the module's bare
+    // `parse`: only the instance carries the meta bag, and without it
+    // a syntax error in an included `.json` says `<no-file>`.
+    const json = makeJsonParser()
+    return {
+      json: (src: string, fileName: string) => json.parse(src, { fileName }),
+      jsonc: viaPlugin(Jsonc),
+      json5: viaPlugin(Json5),
+      // Plain jsonic needs no plugin: it IS the base parser.
+      jsonic: (src: string, fileName: string) => Jsonic(src, { fileName }),
+      toml: (src: string, fileName: string) => tomlDates(toml(src, fileName)),
+      yaml: viaPlugin(Yaml),
+      ini: viaPlugin(Ini),
+    }
+  })()
+
+/**
+ * A TOML document with its dates as the TEXT they were written as.
+ *
+ * TOML HAS DATES AND JSON DOES NOT, so the reader cannot hand one over
+ * as itself: it answers with a marker object carrying the kind and the
+ * source text. The value that reaches a document is that TEXT, which is
+ * what a JSON document carries for a date anyway — and it is what the
+ * Go port produces too, from a `*TomlTime` holding those same two
+ * fields (`dataToValDepth`, go/source.go). Without this the same file
+ * is a nested map in one port and a string in the other, which is the
+ * class of divergence ADR-012 exists to stop.
+ *
+ * The guard is exact — one key, `__toml__`, holding a `kind` and a
+ * `src` string — so a document whose own data happens to use the name
+ * passes through untouched.
+ */
+function tomlDates(node: any): any {
+  if (Array.isArray(node)) {
+    return node.map(tomlDates)
+  }
+  if (null === node || 'object' !== typeof node) {
+    return node
+  }
+  const keys = Object.keys(node)
+  const mark = node.__toml__
+  if (1 === keys.length && '__toml__' === keys[0] && null != mark &&
+    'string' === typeof mark.kind && 'string' === typeof mark.src) {
+    return mark.src
+  }
+  const out: Record<string, any> = {}
+  for (const k of keys) {
+    out[k] = tomlDates(node[k])
+  }
+  return out
+}
+
+/**
+ * Read one included file as DATA in the named format.
+ *
+ * The parser hands back the JSON value the file denotes — plain maps,
+ * lists and scalars — and rawToVal turns that into Vals. THE
+ * CONVERSION HAPPENS HERE, not at the top level, because an include is
+ * usually not at the top level: `a: @"conf.toml"` puts the value under
+ * a key, where a raw JavaScript object is something the tree cannot
+ * unify with (the crash that was BUGS §49b).
+ */
+const dataProcessor = (format: string) => (res: any) => {
+  res.val = rawToVal(DATA_READERS[format](res.src, res.path))
+}
+
+/**
+ * The multisource processor map, built FROM the include table so the
+ * two cannot drift: every extension the table names gets the reader
+ * the table names for it, and the two kinds that are not in the table
+ * refuse.
+ */
+function includeProcessors(): { [kind: string]: any } {
+  const map: { [kind: string]: any } = {
+    // multisource's fallback for an extension no entry names, so it is
+    // the one that catches whatever the resolver's gate did not.
+    '': refuseProcessor,
+    // ... and the one upstream default that would EXECUTE the file.
+    js: refuseProcessor,
+  }
+  const source = makeJsonicProcessor()
+  for (const kind of Object.keys(INCLUDE_KINDS)) {
+    const format = INCLUDE_KINDS[kind]
+    map[kind] = 'source' === format ? source : dataProcessor(format)
+  }
+  return map
+}
+
+
+// SECURITY: under the DEFAULT ('system') include capability this
+// resolver reads any file the process can reach — @"path" follows
+// relative paths (`@"../../etc/passwd.aon"`) and symlinks — so treat
+// opening an untrusted source as reading your disk. It no longer RUNS
+// one: @"pkg" could require() an arbitrary installed module until
+// ADR-012, which refuses a `.js` entry point by the same rule that
+// refuses `.txt`. The trust profile (G5, docs/trust.md) is the
+// confinement surface: `trust.include` of
+// 'none', `{ mem }` or `{ root }` restricts what `@"..."` may resolve,
+// and a denied resolution is a deterministic parse-stage
+// `include_denied` error.
 function makeModelResolver(options: any) {
   const useRequire = options.require || require
-
-  let memResolver = makeMemResolver({
-    ...(options.resolver?.mem || {})
-  })
+  const capability = options.trust?.include ?? 'system'
+
+  const memCapability =
+    'object' === typeof capability && null != (capability as any).mem
+  const rootDir: string | undefined =
+    'object' === typeof capability &&
+      'string' === typeof (capability as any).root
+      ? pathResolve((capability as any).root) : undefined
+
+  // Under the mem capability the CAPABILITY's file set is the whole
+  // world; otherwise the host-injected `options.resolver.mem` entries
+  // remain available under every capability but 'none' — they are
+  // host-provided, not document-requested, so confining them would
+  // confine the host against itself.
+  // THE BUNDLED VOCABULARY (G4 phase 4, ts/src/std.ts) rides the
+  // memory leg: served from the engine itself, so it needs neither the
+  // filesystem nor package resolution and is available under every
+  // capability but `none` — which denies every include outright, that
+  // being what `none` means. Host entries and the capability's own set
+  // WIN over it: a caller that supplies its own `std/system` gets the
+  // one it supplied.
+  let memResolver = makeMemResolver(memCapability
+    ? { ...(capability as any).mem }
+    : { ...(options.resolver?.mem || {}) })
 
   // TODO: make this consistent with other resolvers
   let fileResolver = makeFileResolver((spec: any) => {
@@ -1190,6 +1825,121 @@ function makeModelResolver(options: any) {
     ...(options.resolver?.pkg || {})
   })
 
+  // Confinement is realpath-then-prefix-check (docs/trust.md): the
+  // RESOLVED file's real path must sit below the root's real path, so a
+  // symlink inside the root pointing outside it is an escape, not a
+  // loophole. A path realpath cannot resolve falls back to the lexical
+  // form — the comparison is then against what the resolver actually
+  // read.
+  // Real fs, deliberately: `options.fs` is not a sandbox (it feeds
+  // parse text; the file leg reads through its own channel), so the
+  // containment check must see the same filesystem that leg read from.
+  // A path that does not (fully) exist cannot be realpath'd whole, and
+  // falling back to the LEXICAL form compares apples to oranges when
+  // the root itself sits behind a symlink -- on macOS a root under
+  // /var realpaths to /private/var, so a merely-missing file inside it
+  // reads as an escape. Realpath the deepest EXISTING ancestor and
+  // re-attach the rest, so both sides of the check are in real
+  // coordinates. (The MCP server's own confinement carries the twin of
+  // this rule; its CI failure is what found the shape.)
+  const realpath = (p: string): string => {
+    try {
+      return realpathSync(p)
+    }
+    catch {
+      const parent = pathDirname(p)
+      if (parent === p) {
+        return p
+      }
+      return pathJoin(realpath(parent), pathBasename(p))
+    }
+  }
+
+  const outsideRoot = (root: string, full: string): boolean => {
+    const rootReal = realpath(root)
+    const fullReal = realpath(full)
+    return fullReal !== rootReal && !fullReal.startsWith(rootReal + pathSep)
+  }
+
+  // A denial THROWS with the code; Lang.parse converts it to the
+  // parse-stage `include_denied` nil (the same shape a syntax failure
+  // takes). Raising beats injecting a nil value: a bare-member include
+  // (`@"denied.aon"` at the top of a file) MERGES into the enclosing
+  // map, and a nil contributes no keys, so an injected denial would
+  // vanish and leave a plausible, silently-partial document.
+  const deny = (path: string): never => {
+    // Only 'none' and 'root' can deny: the mem capability's misses are
+    // not-found (its set is the whole world), so there is no third arm.
+    const capname = 'none' === capability ? 'none' : 'root:' + rootDir
+    const err: any = new Error(
+      'include denied: ' + path + ' (capability: ' + capname + ')')
+    err.code = 'include_denied'
+    throw err
+  }
+
+  // AN UNREADABLE EXTENSION THROWS, exactly as a denial does, and for
+  // the same reason: a bare-member include (`@"notes.txt"` at the top
+  // of a file) MERGES into the enclosing map, and a nil contributes no
+  // keys, so an injected refusal would vanish and leave a plausible,
+  // silently-partial document. Lang.parse turns the throw into the
+  // parse-stage `include_extension` nil.
+  const refuseExtension = (path: string, full: string): never => {
+    const err: any = new Error(extensionMsg(path, extKindOf(full)))
+    err.code = 'include_extension'
+    throw err
+  }
+
+  // The gate every leg that RESOLVES A NAME passes through. The std and
+  // module legs do not: both state `kind: 'aon'` because what they
+  // serve is Aontu source by construction, not by its spelling.
+  const gateExtension = (path: string, full: string): void => {
+    if (undefined === INCLUDE_KINDS[extKindOf(full)]) {
+      refuseExtension(path, full)
+    }
+  }
+
+  // The user cache: whatever the host named, else the platform rule
+  // (`modCacheDir`, ts/src/mod.ts) the tooling writes by.
+  const modCache = (opts: any): string | undefined => {
+    const named = opts.mod?.cache
+    return 'string' === typeof named ? named : modCacheDir()
+  }
+
+  // The directory an include is being resolved FROM: the source that
+  // holds it, or the entry path when the source is a string. Same base
+  // the file leg computes (resolvePathSpec in @tabnas/multisource).
+  const dirOf = (p: string | undefined): string =>
+    null == p || '' === p ? pathResolve('.') : pathDirname(pathResolve(p))
+
+  // The module store reader: the host's filesystem when one was
+  // injected, so a sandboxed evaluation stays in the filesystem the
+  // host gave it.
+  const modFs = (ctx: any): any => {
+    const hostfs = ctx?.meta?.fs
+    return null == hostfs ? { existsSync, readFileSync } : {
+      existsSync: (p: string) => {
+        try {
+          hostfs.statSync(p)
+          return true
+        }
+        catch {
+          return false
+        }
+      },
+      readFileSync: (p: string, enc: string) => hostfs.readFileSync(p, enc),
+    }
+  }
+
+  // The manifest sink rides the parse meta (Lang.parse seeds it, the
+  // multisource plugin's child-meta spread carries it to every nested
+  // include), so the recorded closure covers the whole include tree.
+  const record = (ctx: any, path: string, cap: string) => {
+    const manifest = ctx?.meta?.aontu?.manifest
+    if (Array.isArray(manifest)) {
+      manifest.push({ path, capability: cap })
+    }
+  }
+
   return function ModelResolver(
     spec: any,
     popts: any,
@@ -1209,10 +1959,69 @@ function makeModelResolver(options: any) {
       return { found: false, path: '' + (path ?? ''), search: [] }
     }
 
+    if ('none' === capability) {
+      deny(path)
+    }
+
+    // THE BUNDLED VOCABULARY (G4 phase 4, ts/src/std.ts): served from
+    // the engine itself, so it needs neither the filesystem nor package
+    // resolution and is available under every capability but `none` —
+    // checked just above, that being what `none` means. Matched against
+    // the name the author WROTE, before the memory leg, so the kind is
+    // stated rather than guessed from an extension the bare name does
+    // not have.
+    const std = STD_SOURCES[path]
+    if (null != std) {
+      record(ctx, path, 'std')
+      return { found: true, path, full: path, kind: 'aon', src: std, search: [] }
+    }
+
     let search: any = []
     let res = memResolver(path, popts, rule, ctx, jsonic)
     res.path = path
     if (res.found) {
+      // THE EXTENSION DECIDES HERE TOO. A virtual file set is still a
+      // file set: its keys carry extensions, and the same rule has to
+      // read them, or the mem capability becomes a way to include what
+      // the filesystem would refuse.
+      gateExtension(path, res.full ?? path)
+      record(ctx, res.full ?? path, 'mem')
+      return res
+    }
+
+    // THE MODULE LEG (G6 phase 2, ts/src/mod.ts): memory -> MODULE ->
+    // filesystem -> package. Memory stays FIRST so a sandbox and the
+    // spec suite can stub a module path without touching disk; a path
+    // that is not module-shaped falls straight through, so no existing
+    // include can be routed somewhere new by this.
+    const modref = memCapability ? undefined : parseModuleRef(path)
+    if (null != modref) {
+      const msmeta = (ctx as any)?.meta?.multisource
+      const from = dirOf(null != msmeta?.path ? msmeta.path : popts?.path)
+      const found = resolveModule(modref, from, modFs(ctx), {
+        // The user cache lives outside any confinement root, so it is
+        // consulted only when nothing confines this evaluation. A
+        // rooted profile sees the project's own `aon_vendor/` and
+        // nothing else, which is what `root` means.
+        ...(null == rootDir ? { cache: modCache(options) } : {}),
+        eval: options.mod?.eval,
+        depth: options.mod?.depth,
+      })
+      if (null != rootDir && outsideRoot(rootDir, found.full)) {
+        deny(path)
+      }
+      record(ctx, found.full, 'mod')
+      return {
+        found: true, path, full: found.full,
+        kind: 'aon', src: found.src, search: [],
+      }
+    }
+
+    if (memCapability) {
+      // A miss in the declared virtual set is NOT-FOUND, not denial:
+      // the allowed mechanism ran and missed. Denial is reserved for a
+      // capability refusing a mechanism outright.
+      res.search = search.concat(res.search)
       return res
     }
 
@@ -1221,14 +2030,47 @@ function makeModelResolver(options: any) {
     res = fileResolver(path, popts, rule, ctx, jsonic)
     res.path = path
     if (res.found) {
+      // `res.full` asserted non-null: a FOUND file resolution always
+      // carries the absolute path it read (and the pkg leg below is the
+      // same), so a runtime fallback arm would be dead code.
+      const full = res.full as string
+      if (null != rootDir && outsideRoot(rootDir, full)) {
+        deny(path)
+      }
+      // After the trust check, not before: a file outside the
+      // confinement root is denied whatever it is called, and answering
+      // "extension" there would say the file exists.
+      gateExtension(path, full)
+      // The warning window for the staged default flip (G5 phase 6):
+      // under 'system', the CLI supplies trustWarn and the entry root,
+      // and every resolution escaping that root names the flag a future
+      // default will require.
+      if (null == rootDir && null != options.trustWarn &&
+        null != options.trustWarnRoot &&
+        outsideRoot(options.trustWarnRoot, full)) {
+        options.trustWarn('escape', full)
+      }
+      record(ctx, full, 'file')
       return res
     }
 
     search = search.concat(res.search)
 
+    if (null != rootDir) {
+      // Package resolution is not part of the root capability; the
+      // miss stands as not-found with the searched paths listed.
+      res.search = search
+      return res
+    }
+
     res = pkgResolver(path, popts, rule, ctx, jsonic)
     res.path = path
     if (res.found) {
+      gateExtension(path, res.full as string)
+      if (null != options.trustWarn) {
+        options.trustWarn('pkg', res.full as string)
+      }
+      record(ctx, res.full as string, 'pkg')
       return res
     }
 
@@ -1238,27 +2080,62 @@ function makeModelResolver(options: any) {
 }
 
 
-// funcArity is the permitted WRITTEN argument count of each built-in, as
+// THE SIGNATURE REGISTRY (docs/design/SIGNATURES.0.md). The call
+// surface is DECLARED in test/spec/signature.tsv and parsed by the
+// signature grammar (ts/src/sig.ts) from the build-time-inlined copy;
+// the arity table and the positional set below are DERIVED from the
+// parsed registry (funcSig, ts/src/sig.ts), so the declaration is the
+// one source. go/func.go derives the same two tables from the same
+// text.
+// The functions whose comma-separated arguments are distinct POSITIONS
+// rather than one argument list. See the func-paren handler above: this
+// is the set whose comma group is expanded back into separate `peg`
+// entries. Derived: two or more declared argument slots, excluding the
+// residual producers (`constraint` results) -- the constraint atoms
+// make the same expansion in their own constructor (`atomArgs`,
+// ConstraintVal.ts, deliberately before the settled check), which is
+// why they are not in this set; `must` is the load-bearing example.
+// Arithmetic is here because `sub` is not commutative: `sub(a, b)`
+// reaching the engine as one two-element list would lose which is
+// which.
+const POSITIONAL_ARG_FUNCS: Record<string, boolean> = {}
+for (const name in funcSig) {
+  if (2 <= funcSig[name].args.length && 'constraint' !== funcSig[name].out) {
+    POSITIONAL_ARG_FUNCS[name] = true
+  }
+}
+
+
 // [min, max]; a max of -1 is unbounded. Every name in funcMap has an
 // entry, and the arity is a property of the language rather than of
-// either port -- go/func.go carries the same table.
-//
-// Nearly everything takes exactly one. The four exceptions earn their
-// place: key() names how many levels UP the path to read, defaulting to
-// the parent when omitted, neq takes a whole set of exclusions,
-// unique() is a property of the container rather than a comparison
-// against anything, so there is nothing for it to take, and must()
-// takes a check AND the author's message for when it fails.
-const funcArity: Record<string, [number, number]> = {
-  upper: [1, 1], lower: [1, 1], copy: [1, 1], pref: [1, 1],
-  super: [1, 1], type: [1, 1], hide: [1, 1], close: [1, 1],
-  open: [1, 1], move: [1, 1], path: [1, 1],
-  min: [1, 1], max: [1, 1], above: [1, 1], below: [1, 1], re: [1, 1],
-  length: [1, 1],
-  key: [0, 1],
-  unique: [0, 0],
-  neq: [1, -1],
-  must: [2, 2],
+// either port -- go/func.go derives the same table. A required slot
+// counts toward the minimum; a rest slot makes the maximum unbounded
+// and counts its group size (one, for a plain rest type) toward the
+// minimum, which is what gives `match` its floor of three and `neq`
+// its floor of one.
+function sigArity(sig: FuncSig): [number, number] {
+  let min = 0
+  let max = 0
+  for (const a of sig.args) {
+    if (true === a.rest) {
+      min += undefined === a.group ? 1 : a.group.length
+      max = -1
+    }
+    else {
+      if (true !== a.opt) {
+        min++
+      }
+      if (-1 !== max) {
+        max++
+      }
+    }
+  }
+  return [min, max]
+}
+
+const funcArity: Record<string, [number, number]> = {}
+for (const name in funcSig) {
+  funcArity[name] = sigArity(funcSig[name])
 }
 
 
@@ -1293,8 +2170,10 @@ function arityText(lo: number, hi: number): string {
     return 'one or more arguments'
   }
   if (lo !== hi) {
-    return 'no arguments or one'
+    return 0 === lo ? 'no arguments or one' : 'one argument or two'
   }
+  // The {0,0} arm returned with the container kinds and acyclic()
+  // (ADR-015): `map(1)` must not claim map takes exactly one.
   if (0 === hi) {
     return 'no arguments'
   }
@@ -1339,15 +2218,22 @@ function opCharHint(src: string): string {
 
 
 function rawToVal(n: any): Val {
-  if (null == n) {
-    return new NullVal({ peg: null })
-  }
-  if (true === n.isVal) {
+  if (true === n?.isVal) {
     return n
   }
   if (Array.isArray(n)) {
     return new ListVal({ peg: n.map(rawToVal) })
   }
+
+  // THE SCALAR ARMS ARE WHERE A CONFIG FILE BECOMES VALUES. Every
+  // format on the include table is read by its own parser into plain
+  // JavaScript -- a string, a number, a map -- and this is the walk
+  // that turns that into Vals (dataProcessor, ADR-012). The two arms
+  // above are the other caller: a raw expression TERM, which the
+  // expression grammar hands over already built.
+  if (null == n) {
+    return new NullVal({ peg: null })
+  }
   const t = typeof n
   if ('string' === t) {
     return new StringVal({ peg: n })
@@ -1362,14 +2248,20 @@ function rawToVal(n: any): Val {
   if ('boolean' === t) {
     return new BooleanVal({ peg: n })
   }
-  if ('object' === t) {
-    const peg: Record<string, Val> = {}
-    for (const k in n) {
-      peg[k] = rawToVal(n[k])
-    }
-    return new MapVal({ peg })
+  // AND EVERYTHING ELSE IS A MAP, with no arm after it because there is
+  // nothing after it. Every reader on the include table answers with
+  // the JSON kinds and no others -- probed, including the two that
+  // could plausibly escape them: a big integer comes back a `number`,
+  // and a TOML date is normalised to its text before it gets here. The
+  // one include that could hand over a function was `.js`, which
+  // ADR-012 refuses. `parse_unknown` lived here for that case and has
+  // no producer left in this port; the Go twin keeps its own, where the
+  // type switch really can be handed something unaccounted for.
+  const peg: Record<string, Val> = {}
+  for (const k in n) {
+    peg[k] = rawToVal(n[k])
   }
-  return new NilVal({ why: 'parse_unknown' })
+  return new MapVal({ peg })
 }
 
 
@@ -1401,11 +2293,22 @@ class Lang {
         // works. `.jsonic` is retired (no longer auto-resolved); the
         // default `['jsonic','jsc','json','js']` is overridden here.
         // (Upstream option name is the misspelled `implictExt`.)
+        //
+        // Only these two are SEARCHED for a bare `@"name"`; `.json` and
+        // `.jsonld` are read when NAMED, which is how a vendored
+        // vocabulary is always written.
         implictExt: ['aon', 'aontu'],
-        processor: {
-          aontu: 'jsonic',
-          aon: 'jsonic',
-        }
+        // ONE ENTRY PER EXTENSION THE TABLE NAMES, built from it (see
+        // includeProcessors) so the rule and its wiring cannot drift.
+        //
+        // The upstream defaults are REPLACED, not extended. Its `json`
+        // entry is what made that extension the one that crashed: it
+        // hands back a raw JS object where the aontu grammar produces
+        // Vals, and the tree then met a value it could not convert
+        // (BUGS §49b). Its `js` entry EXECUTES the file, which is not
+        // something an extension should be able to ask for. And its
+        // fallback hands any other file back as TEXT.
+        processor: includeProcessors()
       })
       .use(AontuJsonic)
   }
@@ -1421,7 +2324,13 @@ class Lang {
       multisource: {
         path: opts?.path ?? this.opts.path,
         deps: (opts && opts.deps) || undefined
-      }
+      },
+      // The include-manifest sink (G5, docs/trust.md): the resolver
+      // records every resolved include here, and the plugin's
+      // child-meta spread carries the same array to nested includes.
+      aontu: {
+        manifest: (opts as any)?.manifest,
+      },
     }
 
     if (null != opts?.idcount) {
@@ -1449,16 +2358,46 @@ class Lang {
       }
     }
     catch (e: any) {
-      if (e instanceof JsonicError || 'JsonicError' === e.constructor.name) {
+      if ('include_denied' === e?.code || 'include_extension' === e?.code ||
+        MODULE_REFUSAL_CODES.has(e?.code)) {
+        // A denied include (G5), an include whose extension is not read
+        // as Aontu source (ADR-012, INCLUDE_KINDS), and a module that is
+        // missing, fails its pin, or names a path that escapes its store
+        // (G6 phase 2) are refused the same way, for the same reason: the
+        // resolver THROWS so a bare-member include cannot vanish in the
+        // merge, and the code survives here as the parse-stage nil the
+        // registry pins (errcodes.tsv).
         val = new NilVal({
           why: 'parse',
           err: new NilVal({
-            why: 'syntax',
-            msg: e.message + opCharHint(src),
+            why: e.code,
+            msg: e.message,
             err: e,
           })
         })
       }
+      else if (e instanceof JsonicError || 'JsonicError' === e.constructor.name) {
+        const syntax: any = new NilVal({
+          why: 'syntax',
+          msg: e.message + opCharHint(src),
+          err: e,
+        })
+        // THE POSITION TRAVELS WITH IT. The parser knows exactly where
+        // it stopped -- it draws a caret there -- and the rendered
+        // message carried the only copy, so `vet --format json`
+        // reported row -1, col -1 for a document whose fault the human
+        // renderer located to the character. A machine-readable report
+        // that says "somewhere in this file" is the one a repair loop
+        // can do nothing with. Both numbers are already 1-based here,
+        // which is the base a site uses (go/lang.go does the same).
+        if ('number' === typeof e.lineNumber) {
+          syntax.site.row = e.lineNumber
+        }
+        if ('number' === typeof e.columnNumber) {
+          syntax.site.col = e.columnNumber
+        }
+        val = new NilVal({ why: 'parse', err: syntax })
+      }
       else {
         throw e
       }