aontu 0.52.1 → 0.54.0

package/dist/lang.js

@@ -3,13 +3,39 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Site = exports.Lang = void 0;
 // 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.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const jsonic_1 = require("@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`.
+const sig_1 = require("./sig");
+const json_1 = require("@tabnas/json");
+const toml_1 = require("@tabnas/toml");
+const jsonc_1 = require("@tabnas/jsonc");
+const json5_1 = require("@tabnas/json5");
+const yaml_1 = require("@tabnas/yaml");
+const ini_1 = require("@tabnas/ini");
 const debug_1 = require("@tabnas/debug");
 const multisource_1 = require("@tabnas/multisource");
 // TODO: @tabnas/multisource should support virtual fs
 const file_1 = require("@tabnas/multisource/resolver/file");
 const pkg_1 = require("@tabnas/multisource/resolver/pkg");
 const mem_1 = require("@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.
+const jsonic_2 = require("@tabnas/multisource/processor/jsonic");
+const std_1 = require("./std");
+const mod_1 = require("./mod");
 const expr_1 = require("@tabnas/expr");
 const path_1 = require("@tabnas/path");
 const type_1 = require("./type");
@@ -41,8 +67,19 @@ const CopyFuncVal_1 = require("./val/CopyFuncVal");
 const KeyFuncVal_1 = require("./val/KeyFuncVal");
 const TypeFuncVal_1 = require("./val/TypeFuncVal");
 const HideFuncVal_1 = require("./val/HideFuncVal");
+const DeprecateFuncVal_1 = require("./val/DeprecateFuncVal");
+const ReferFuncVal_1 = require("./val/ReferFuncVal");
+const GraphAtomVal_1 = require("./val/GraphAtomVal");
+const PackFuncVal_1 = require("./val/PackFuncVal");
+const EachFuncVal_1 = require("./val/EachFuncVal");
+const FilterFuncVal_1 = require("./val/FilterFuncVal");
+const MatchFuncVal_1 = require("./val/MatchFuncVal");
+const ArithFuncVal_1 = require("./val/ArithFuncVal");
+const AggFuncVal_1 = require("./val/AggFuncVal");
+const PlaceVal_1 = require("./val/PlaceVal");
 const MoveFuncVal_1 = require("./val/MoveFuncVal");
 const PathFuncVal_1 = require("./val/PathFuncVal");
+const ContainerKindVal_1 = require("./val/ContainerKindVal");
 const PrefFuncVal_1 = require("./val/PrefFuncVal");
 const CloseFuncVal_1 = require("./val/CloseFuncVal");
 const OpenFuncVal_1 = require("./val/OpenFuncVal");
@@ -84,6 +121,12 @@ function bigVal(res) {
 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 = function AontuLang(jsonic) {
     jsonic.use(asPlugin(path_1.Path));
     // Only # line comments are valid Aontu syntax (see
@@ -94,6 +137,35 @@ let AontuJsonic = function AontuLang(jsonic) {
         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 = 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_1.NilVal({ why: 'alias_in_path' }), r, ctx);
+                }
+            }
+        }
         return addsite(new RefVal_1.RefVal({ peg: terms, prefix }), r, ctx);
     };
     jsonic.options({ comment: { def: null } });
@@ -165,9 +237,41 @@ let AontuJsonic = function AontuLang(jsonic) {
             check: (lex) => {
                 // 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, ctx) => addsite(new RefVal_1.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;
                 }
@@ -201,6 +305,16 @@ let AontuJsonic = function AontuLang(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] : [];
         return v;
@@ -264,6 +378,12 @@ help isolate the syntax error.`,
                 },
                 // TODO: FIX: need a TOP instance to hold path
                 'top': { val: () => (0, top_1.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, ctx) => addsite(new PlaceVal_1.PlaceVal({}), r, ctx)
+                },
             }
         },
         map: {
@@ -304,6 +424,13 @@ help isolate the syntax error.`,
         move: MoveFuncVal_1.MoveFuncVal,
         path: PathFuncVal_1.PathFuncVal,
         pref: PrefFuncVal_1.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: ContainerKindVal_1.MapFuncVal,
+        list: ContainerKindVal_1.ListFuncVal,
         close: CloseFuncVal_1.CloseFuncVal,
         open: OpenFuncVal_1.OpenFuncVal,
         super: SuperFuncVal_1.SuperFuncVal,
@@ -330,6 +457,63 @@ help isolate the syntax error.`,
         // reported with the author's own message, never simplified and
         // never consulted for emptiness or subsumption.
         must: ConstraintVal_1.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_1.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_1.ReferFuncVal,
+        rel: ReferFuncVal_1.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: GraphAtomVal_1.AcyclicFuncVal,
+        inverse: GraphAtomVal_1.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_1.PackFuncVal,
+        each: EachFuncVal_1.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_1.FilterFuncVal,
+        match: MatchFuncVal_1.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: ArithFuncVal_1.AddFuncVal,
+        sub: ArithFuncVal_1.SubFuncVal,
+        mul: ArithFuncVal_1.MulFuncVal,
+        div: ArithFuncVal_1.DivFuncVal,
+        mod: ArithFuncVal_1.ModFuncVal,
+        rem: ArithFuncVal_1.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: AggFuncVal_1.SumFuncVal,
+        least: AggFuncVal_1.LeastFuncVal,
+        greatest: AggFuncVal_1.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: AggFuncVal_1.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: AggFuncVal_1.JoinFuncVal,
     };
     // A dangling operator (`a:1|`, `a:$`, `a:*` at end of input) leaves
     // null/undefined unfilled terms. Junction ops drop them (so `a:1&`
@@ -338,6 +522,68 @@ help isolate the syntax error.`,
     // resolve value" error (the Go port mirrors this in lang.go).
     const dropUnfilled = (terms) => terms.filter((t) => null != t);
     const incompleteNil = (r, ctx) => addsite(new NilVal_1.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, ctx, fname, argterms) => {
+        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 = new NilVal_1.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 = null == funcval ?
+            new NilVal_1.NilVal({ why: 'unknown_function' }) :
+            new funcval({ peg: args });
+        return val;
+    };
     let opmap = {
         'conjunct-infix': (r, ctx, _op, terms) => addsite(new ConjunctVal_1.ConjunctVal({ peg: dropUnfilled(terms) }), r, ctx),
         'disjunct-infix': (r, ctx, _op, terms) => addsite(new DisjunctVal_1.DisjunctVal({ peg: dropUnfilled(terms) }), r, ctx),
@@ -349,11 +595,47 @@ help isolate the syntax error.`,
         'star-prefix': (r, ctx, _op, terms) => {
             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 = terms[0];
+            if ((bag.isMap && '{' !== bag.site.src) ||
+                (bag.isList && '[' !== bag.site.src)) {
+                return addsite(new NilVal_1.NilVal({ why: 'pref_implicit_bag' }), r, ctx);
+            }
             return addsite(new PrefVal_1.PrefVal({ peg: terms[0] }), r, ctx);
         },
         'dollar-prefix': (r, ctx, _op, terms) => {
             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_1.RefVal &&
+                terms[0].peg.some((seg) => 'string' === typeof seg && ALIAS_RE.test(seg))) {
+                return addsite(new NilVal_1.NilVal({ why: 'alias_in_path' }), r, ctx);
+            }
             // $.a.b absolute path
             if (terms[0] instanceof RefVal_1.RefVal) {
                 terms[0].absolute = true;
@@ -412,50 +694,7 @@ help isolate the syntax error.`,
             let val = terms[1];
             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 = new NilVal_1.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_1.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)
@@ -560,6 +799,7 @@ help isolate the syntax error.`,
     const TX = jsonic.token.TX;
     const NR = jsonic.token.NR;
     const QM = jsonic.token.QM;
+    const VL = jsonic.token.VL;
     const OPTKEY = [TX, ST, NR];
     jsonic.rule('expr', (rs) => {
         rs.close([
@@ -658,6 +898,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? }
             r.node = valnode;
@@ -674,6 +921,7 @@ help isolate the syntax error.`,
         ])
             .bc((r, ctx) => {
             const optionalKeys = r.u.aontu_optional_keys ?? [];
+            const aliasKeys = r.u.aontu_alias_keys ?? [];
             let mo = r.node;
             // An elided value (`a:`) leaves a raw null/undefined that never
             // passed through the val rule. It is REFUSED rather than made a
@@ -733,12 +981,14 @@ help isolate the syntax error.`,
                 // TODO: needs addpath?
                 let mopv = new MapVal_1.MapVal({ peg: mop });
                 mopv.optionalKeys = optionalKeys;
+                mopv.aliasKeys = aliasKeys;
                 r.node =
                     addsite(new ConjunctVal_1.ConjunctVal({ peg: [mopv, ...mo.___merge] }), r, ctx);
             }
             else {
                 r.node = addsite(new MapVal_1.MapVal({ peg: mo }), r, ctx);
                 r.node.optionalKeys = optionalKeys;
+                r.node.aliasKeys = aliasKeys;
             }
             return undefined;
         })
@@ -860,6 +1110,31 @@ help isolate the syntax error.`,
         })
             .bc((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 = rule.o0;
+            if (null != ktkn && VL === ktkn.tin && ALIAS_RE.test('' + ktkn.src)) {
+                const holder = 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[type_1.SPREAD] =
                     (rule.node[type_1.SPREAD] || { o: rule.o0.src, v: [] });
@@ -896,7 +1171,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;
@@ -904,18 +1182,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 },
@@ -926,32 +1203,316 @@ help isolate the syntax error.`,
                 g: 'aontu-plain-pair-elem'
             }
         ])
-            .bc((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, ctx) => {
             // 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[type_1.SPREAD] =
                     (rule.node[type_1.SPREAD] || { o: rule.o0.src, v: [] });
                 rule.node[type_1.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 = rule.child.node;
+                if (null == v) {
+                    v = addsite(new NilVal_1.NilVal({ why: 'elided_value' }), rule, ctx);
+                    v.path = [...(rule.k?.path ?? []),
+                        '' + rule.node.length, key];
+                }
+                const mv = addsite(new MapVal_1.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;
         })
             .close([{ s: [CJ, CL], r: 'elem', b: 2, g: 'spread,json,more' }]);
         return rs;
     });
 };
-// 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 = {
+    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) {
+    const seg = full.match(/[^\\/]*$/)[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, ext) {
+    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) => {
+    // `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 = 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 = (() => {
+    const viaPlugin = (plugin) => {
+        const jsonic = jsonic_1.Jsonic.make().use(plugin);
+        return (src, fileName) => jsonic(src, { fileName });
+    };
+    const toml = viaPlugin(toml_1.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 = (0, json_1.make)();
+    return {
+        json: (src, fileName) => json.parse(src, { fileName }),
+        jsonc: viaPlugin(jsonc_1.Jsonc),
+        json5: viaPlugin(json5_1.Json5),
+        // Plain jsonic needs no plugin: it IS the base parser.
+        jsonic: (src, fileName) => (0, jsonic_1.Jsonic)(src, { fileName }),
+        toml: (src, fileName) => tomlDates(toml(src, fileName)),
+        yaml: viaPlugin(yaml_1.Yaml),
+        ini: viaPlugin(ini_1.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) {
+    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 = {};
+    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) => (res) => {
+    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() {
+    const map = {
+        // 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 = (0, jsonic_2.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) {
     const useRequire = options.require || require;
-    let memResolver = (0, mem_1.makeMemResolver)({
-        ...(options.resolver?.mem || {})
-    });
+    const capability = options.trust?.include ?? 'system';
+    const memCapability = 'object' === typeof capability && null != capability.mem;
+    const rootDir = 'object' === typeof capability &&
+        'string' === typeof capability.root
+        ? (0, node_path_1.resolve)(capability.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 = (0, mem_1.makeMemResolver)(memCapability
+        ? { ...capability.mem }
+        : { ...(options.resolver?.mem || {}) });
     // TODO: make this consistent with other resolvers
     let fileResolver = (0, file_1.makeFileResolver)((spec) => {
         return 'string' === typeof spec ? spec : spec?.peg;
@@ -960,6 +1521,110 @@ function makeModelResolver(options) {
         require: useRequire,
         ...(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) => {
+        try {
+            return (0, node_fs_1.realpathSync)(p);
+        }
+        catch {
+            const parent = (0, node_path_1.dirname)(p);
+            if (parent === p) {
+                return p;
+            }
+            return (0, node_path_1.join)(realpath(parent), (0, node_path_1.basename)(p));
+        }
+    };
+    const outsideRoot = (root, full) => {
+        const rootReal = realpath(root);
+        const fullReal = realpath(full);
+        return fullReal !== rootReal && !fullReal.startsWith(rootReal + node_path_1.sep);
+    };
+    // 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) => {
+        // 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 = 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, full) => {
+        const err = 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, full) => {
+        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) => {
+        const named = opts.mod?.cache;
+        return 'string' === typeof named ? named : (0, mod_1.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) => null == p || '' === p ? (0, node_path_1.resolve)('.') : (0, node_path_1.dirname)((0, node_path_1.resolve)(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) => {
+        const hostfs = ctx?.meta?.fs;
+        return null == hostfs ? { existsSync: node_fs_1.existsSync, readFileSync: node_fs_1.readFileSync } : {
+            existsSync: (p) => {
+                try {
+                    hostfs.statSync(p);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            readFileSync: (p, enc) => 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, path, cap) => {
+        const manifest = ctx?.meta?.aontu?.manifest;
+        if (Array.isArray(manifest)) {
+            manifest.push({ path, capability: cap });
+        }
+    };
     return function ModelResolver(spec, popts, rule, ctx, jsonic) {
         // The aontu val rule's ac has already wrapped every raw string node
         // as a StringVal, so spec is a Val here (or a raw object from a
@@ -970,50 +1635,169 @@ function makeModelResolver(options) {
         if (null == path || '' === path) {
             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_1.STD_SOURCES[path];
+        if (null != std) {
+            record(ctx, path, 'std');
+            return { found: true, path, full: path, kind: 'aon', src: std, search: [] };
+        }
         let search = [];
         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 : (0, mod_1.parseModuleRef)(path);
+        if (null != modref) {
+            const msmeta = ctx?.meta?.multisource;
+            const from = dirOf(null != msmeta?.path ? msmeta.path : popts?.path);
+            const found = (0, mod_1.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;
         }
         search = search.concat(res.search);
         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;
+            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);
+            if (null != options.trustWarn) {
+                options.trustWarn('pkg', res.full);
+            }
+            record(ctx, res.full, 'pkg');
             return res;
         }
         res.search = search.concat(res.search);
         return res;
     };
 }
-// 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 = {};
+for (const name in sig_1.funcSig) {
+    if (2 <= sig_1.funcSig[name].args.length && 'constraint' !== sig_1.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 = {
-    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) {
+    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 = {};
+for (const name in sig_1.funcSig) {
+    funcArity[name] = sigArity(sig_1.funcSig[name]);
+}
 // writtenArgCount counts the arguments as the AUTHOR wrote them.
 //
 // It cannot simply be terms.length: a comma group reaches the func-paren
@@ -1043,8 +1827,10 @@ function arityText(lo, hi) {
         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';
     }
@@ -1085,15 +1871,21 @@ function opCharHint(src) {
     return '';
 }
 function rawToVal(n) {
-    if (null == n) {
-        return new NullVal_1.NullVal({ peg: null });
-    }
-    if (true === n.isVal) {
+    if (true === n?.isVal) {
         return n;
     }
     if (Array.isArray(n)) {
         return new ListVal_1.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_1.NullVal({ peg: null });
+    }
     const t = typeof n;
     if ('string' === t) {
         return new StringVal_1.StringVal({ peg: n });
@@ -1108,14 +1900,20 @@ function rawToVal(n) {
     if ('boolean' === t) {
         return new BooleanVal_1.BooleanVal({ peg: n });
     }
-    if ('object' === t) {
-        const peg = {};
-        for (const k in n) {
-            peg[k] = rawToVal(n[k]);
-        }
-        return new MapVal_1.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 = {};
+    for (const k in n) {
+        peg[k] = rawToVal(n[k]);
     }
-    return new NilVal_1.NilVal({ why: 'parse_unknown' });
+    return new MapVal_1.MapVal({ peg });
 }
 class Lang {
     constructor(options) {
@@ -1135,11 +1933,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);
     }
@@ -1152,7 +1961,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?.manifest,
+            },
         };
         if (null != opts?.idcount) {
             this.idcount = opts.idcount;
@@ -1174,16 +1989,46 @@ class Lang {
             }
         }
         catch (e) {
-            if (e instanceof jsonic_1.JsonicError || 'JsonicError' === e.constructor.name) {
+            if ('include_denied' === e?.code || 'include_extension' === e?.code ||
+                mod_1.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_1.NilVal({
                     why: 'parse',
                     err: new NilVal_1.NilVal({
-                        why: 'syntax',
-                        msg: e.message + opCharHint(src),
+                        why: e.code,
+                        msg: e.message,
                         err: e,
                     })
                 });
             }
+            else if (e instanceof jsonic_1.JsonicError || 'JsonicError' === e.constructor.name) {
+                const syntax = new NilVal_1.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_1.NilVal({ why: 'parse', err: syntax });
+            }
             else {
                 throw e;
             }