aontu 0.52.0 → 0.53.0

package/dist/lang.js

@@ -3,6 +3,12 @@
 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");
 const debug_1 = require("@tabnas/debug");
 const multisource_1 = require("@tabnas/multisource");
@@ -10,6 +16,8 @@ const multisource_1 = require("@tabnas/multisource");
 const file_1 = require("@tabnas/multisource/resolver/file");
 const pkg_1 = require("@tabnas/multisource/resolver/pkg");
 const mem_1 = require("@tabnas/multisource/resolver/mem");
+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,6 +49,16 @@ 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 IdFuncVal_1 = require("./val/IdFuncVal");
+const ReferFuncVal_1 = require("./val/ReferFuncVal");
+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 PrefFuncVal_1 = require("./val/PrefFuncVal");
@@ -201,6 +219,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 +292,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: {
@@ -316,6 +350,71 @@ help isolate the syntax error.`,
         above: ConstraintVal_1.AboveConstraintVal,
         below: ConstraintVal_1.BelowConstraintVal,
         neq: ConstraintVal_1.NeqConstraintVal,
+        // G1 phase 2: pattern membership, over the portable subset both
+        // host regex engines agree on (nonPortableRe in ConstraintVal.ts).
+        re: ConstraintVal_1.ReConstraintVal,
+        // G1 phase 3: the sizing atoms. Both are properties of a CONTAINER
+        // (or, for length, of a string) rather than comparisons against a
+        // value, which is why `unique` is the one built-in taking no
+        // argument at all.
+        length: ConstraintVal_1.LengthConstraintVal,
+        unique: ConstraintVal_1.UniqueConstraintVal,
+        // G1 phase 5: Band B. `must` is the one atom the algebra does not
+        // reason about -- it is checked against the finished value and
+        // 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 1: the identity mark. Written as a conjunct
+        // (`id(svc/auth) & {…}`), it resolves to the unit carrying the
+        // name, and every node in one evaluation with that name is
+        // unified with every other.
+        id: IdFuncVal_1.IdFuncVal,
+        // G4 phase 2: the checked, typed, LINK-shaped reference. A
+        // constraint on a string field: the string must be an entity
+        // address, the address must resolve, and the optional argument
+        // flows INTO the target. The field keeps the string.
+        refer: ReferFuncVal_1.ReferFuncVal,
+        // 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,
     };
     // A dangling operator (`a:1|`, `a:$`, `a:*` at end of input) leaves
     // null/undefined unfilled terms. Junction ops drop them (so `a:1&`
@@ -324,6 +423,106 @@ 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. Shared by the `func(...)` handler and by the pipe,
+    // which is the same call with one more argument on the front — so
+    // the arity check, the comma-group rule and the raw-value conversion
+    // are stated once and both spellings get all three.
+    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,
+                };
+                // The CALL AS WRITTEN rides the refusal (G8 phase 4): a pipe
+                // rebuilds `x |> upper()` as `upper(x)`, and the arity it fails
+                // on here is the arity of a call one argument short of the one
+                // the author actually wrote.
+                nil._callname = fname;
+                nil._callterms = argterms;
+                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 });
+        // The call as written, for the pipe to rebuild from. Parse-time
+        // only: nothing downstream reads it, and a clone does not carry it.
+        //
+        // NOT on a constraint atom that BUILT: an atom with its argument
+        // list complete is a residual, not a call waiting for a subject,
+        // and `1 |> neq(2,3)` is asking for `1 & neq(2,3)` -- which is
+        // what `&` is for. (An atom the arity check REFUSED still carries
+        // it, on the nil above: `1 |> min()` is `min(1)`, and that is a
+        // call waiting for a subject.) The Go port cannot rebuild a built
+        // atom at all -- its residual keeps no atom name -- so this is
+        // also what keeps the two ports answering the same thing.
+        if (true !== val.isConstraint) {
+            val._callname = fname;
+            val._callterms = argterms;
+        }
+        return val;
+    };
+    // The argument terms `f(...)` would have been written with, had the
+    // piped value been written into it. A comma group is one raw-array
+    // term: for a POSITIONAL function the group is separate arguments,
+    // so the piped value joins them; for a constraint atom the group IS
+    // the argument list, so the piped value joins the list instead.
+    const pipeTerms = (call, val) => {
+        const written = call._callterms;
+        const group = 1 === written.length && Array.isArray(written[0]) ?
+            written[0] : written;
+        if (0 === group.length) {
+            return [val];
+        }
+        return true === POSITIONAL_ARG_FUNCS[call._callname] ?
+            [val, ...group] : [[val, ...group]];
+    };
     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),
@@ -394,22 +593,51 @@ help isolate the syntax error.`,
                 return incompleteNil(r, ctx);
             return addsite(val, r, ctx);
         },
+        // THE PIPE `|>` (G8 phase 4): parse-time sugar and nothing else.
+        // `x |> f(a)` IS `f(x, a)` -- the piped value goes in as the FIRST
+        // argument, Elixir-style, because every Aontu call is data-first
+        // already (`close(x)`, `pack(data, tmpl)`) and a pipe must read the
+        // way the calls it replaces read. It never reaches a Val: by the
+        // time the tree exists the call is an ordinary call, which is why
+        // canon can never emit the token and the two ports' canon stay
+        // byte-identical without either knowing about it.
+        'pipe-infix': (r, ctx, _op, terms) => {
+            const val = terms[0];
+            const call = terms[1];
+            if (null == val || null == call)
+                return incompleteNil(r, ctx);
+            // The right-hand side is a CALL: either one the func handler
+            // already built, or one it refused for an arity the pipe is about
+            // to satisfy. Both carry what they were written as.
+            if (null != call._callname) {
+                return buildCall(r, ctx, call._callname, pipeTerms(call, val));
+            }
+            // ... or a bare NAME, which is the whole point of the short
+            // spelling: `x |> upper` is `upper(x)`. A bare word has already
+            // become a string VALUE by the time an infix operator sees it, so
+            // this is where a string becomes a call.
+            if (true === call?.isScalar && 'string' === typeof call.peg &&
+                null != funcMap[call.peg]) {
+                return buildCall(r, ctx, call.peg, [val]);
+            }
+            // Anything else is not a call, and a pipe into a non-call is a
+            // mistake in the source rather than a value.
+            return addsite(new NilVal_1.NilVal({ why: 'pipe_target' }), r, ctx);
+        },
         'func-paren': (r, ctx, _op, terms) => {
             let val = terms[1];
             const fname = terms[0];
             if ('' !== fname) {
-                const funcval = funcMap[fname];
-                const args = terms.slice(1);
-                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)
                 return incompleteNil(r, ctx);
-            const out = addsite(val, r, ctx);
+            // ... and the same for a GROUPING paren, whose value is passed
+            // straight through: `(([]%))` yielded a raw array, and addsite went
+            // on to write a site onto it, throwing a TypeError that escaped the
+            // unifier entirely ("Cannot set properties of undefined").
+            const out = addsite(rawToVal(val), r, ctx);
             return out;
         },
     };
@@ -423,6 +651,13 @@ help isolate the syntax error.`,
             'disjunct': {
                 infix: true, src: '|', left: 14_000_000, right: 15_000_000
             },
+            // G8 phase 4: the pipe. LOOSEST of all the infix operators, so
+            // `a & b |> f` pipes the whole meet and not just `b` -- a pipe
+            // reads as "and then", which is a statement about everything to
+            // its left. Kept in lock-step with the op table in go/lang.go.
+            'pipe-infix': {
+                infix: true, src: '|>', left: 12_000_000, right: 13_000_000
+            },
             'plus-infix': {
                 src: '+',
                 infix: true,
@@ -603,6 +838,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;
@@ -621,12 +863,56 @@ help isolate the syntax error.`,
             const optionalKeys = r.u.aontu_optional_keys ?? [];
             let mo = r.node;
             // An elided value (`a:`) leaves a raw null/undefined that never
-            // passed through the val rule; make it an explicit NullVal.
+            // passed through the val rule. It is REFUSED rather than made a
+            // null (issue #48): a key with nothing after the colon is a
+            // mistake in the source, and turning it into a value made that
+            // mistake indistinguishable from a deliberate `a:null`.
+            //
+            // A colon chain (`a: b:1`) is not an elision -- the value is the
+            // nested pair, which the val rule does produce -- and neither is
+            // a trailing comma.
             for (const k in mo) {
                 if (null == mo[k] && '___merge' !== k) {
-                    mo[k] = addsite(new NullVal_1.NullVal({ peg: null }), r, ctx);
+                    // Pathed at the KEY, not at the enclosing map. addsite takes
+                    // the rule's path, which here is the map's, so the error
+                    // would otherwise name the container and leave the reader to
+                    // work out which key was elided.
+                    const en = addsite(new NilVal_1.NilVal({ why: 'elided_value' }), r, ctx);
+                    en.path = [...(r.k?.path ?? []), k];
+                    mo[k] = en;
+                    // An elided value under an OPTIONAL key stops being optional.
+                    // Optionality is about a value that may be absent at
+                    // GENERATE; it does not excuse a source that stops after the
+                    // colon. Left optional, the refusal was dropped with the key
+                    // and `a?:` generated `{}` -- a silent nothing, which is
+                    // worse than either the old null or the error.
+                    const oi = optionalKeys.indexOf(k);
+                    if (-1 !== oi) {
+                        optionalKeys.splice(oi, 1);
+                    }
                 }
             }
+            // ... and the OPTIONAL spelling, `a?:`, which does not leave a
+            // null behind to be found: its value never reaches the node at
+            // all, so the key is simply absent and the map generated without
+            // it. A key recorded as optional but missing from the node was
+            // written with nothing after its colon.
+            for (const k of optionalKeys) {
+                if (!(k in mo)) {
+                    mo[k] = addsite(new NilVal_1.NilVal({ why: 'elided_value' }), r, ctx);
+                }
+            }
+            // An elided SPREAD (`x:$obj&:` with nothing after the colon)
+            // refuses the whole map, not a key (issue #48). A spread is not a
+            // child, so a refusal stored in its place has nothing to attach
+            // to: `x:&:` has no children for the spread to apply to, and the
+            // map would generate as `{}` with the mistake silently gone.
+            // Refusing the container is what makes it visible at all.
+            const sp = mo[type_1.SPREAD];
+            if (sp && sp.v.some((sv) => null == sv)) {
+                r.node = addsite(new NilVal_1.NilVal({ why: 'elided_value' }), r, ctx);
+                return undefined;
+            }
             //  Handle defered conjuncts, e.g. `{x:1 @"foo"}`
             if (mo.___merge) {
                 let mop = { ...mo };
@@ -652,11 +938,15 @@ help isolate the syntax error.`,
             .bc((r, ctx) => {
             const optionalKeys = r.u.aontu_optional_keys ?? [];
             let ao = r.node;
-            // An elided element (`[,]`) is a raw null that never passed
-            // through the val rule; make it an explicit NullVal.
+            // An elided ELEMENT (`[,]`, `[1,,2]`) is refused for the same
+            // reason as an elided map value (issue #48). A trailing comma
+            // (`[1,]`) is not an elision and never reaches here.
             for (let i = 0; i < ao.length; i++) {
                 if (null == ao[i]) {
-                    ao[i] = addsite(new NullVal_1.NullVal({ peg: null }), r, ctx);
+                    // Pathed at the INDEX, for the same reason as the map case.
+                    const en = addsite(new NilVal_1.NilVal({ why: 'elided_value' }), r, ctx);
+                    en.path = [...(r.k?.path ?? []), '' + i];
+                    ao[i] = en;
                 }
             }
             // No ___merge arm here: the deferred map.merge that writes it
@@ -681,6 +971,47 @@ help isolate the syntax error.`,
             : key_token.src; // Was number, use original text
         r.u.key = key;
     };
+    // A pair in LIST position writes its value at `node[key]` like any
+    // other pair, and the enclosing list's node is an ARRAY -- so a numeric
+    // key lands on an index and becomes an element, and may land on an
+    // index a real element already holds (`[5,0:1]`). Since the pair must
+    // contribute nothing (issue #40), the slot is photographed before the
+    // value is parsed and put back afterwards. Restoring beats deleting for
+    // exactly the overwrite case: deleting `[5,0:1]`'s index 0 would take
+    // the 5 with it, where restoring gives back the list the pair was
+    // never part of.
+    //
+    // `length` is saved too: writing past the end grows an array, and
+    // `[5,1?:9]` must be [5] again and not [5, <hole>].
+    // Typed as a string bag deliberately: the slot may be named by a
+    // non-numeric key (`[x:1]`), which the array type would refuse. Both
+    // helpers run only from the elem rule, whose node is the enclosing
+    // list, so neither guards against a non-array node — a guard there
+    // proved unreachable and dead code is worse than none.
+    const asSlots = (r) => r.node;
+    const snapshotPairSlot = (r, key) => {
+        const node = asSlots(r);
+        r.u.aontu_pair_slot = {
+            key,
+            had: Object.prototype.hasOwnProperty.call(node, key),
+            was: node[key],
+            len: node.length,
+        };
+    };
+    const restorePairSlot = (r) => {
+        const slot = r.u.aontu_pair_slot;
+        if (null == slot) {
+            return;
+        }
+        const node = asSlots(r);
+        if (slot.had) {
+            node[slot.key] = slot.was;
+        }
+        else {
+            delete node[slot.key];
+        }
+        node.length = slot.len;
+    };
     jsonic.rule('pair', (rs) => {
         rs
             .open([
@@ -756,10 +1087,30 @@ help isolate the syntax error.`,
                 a: (r) => {
                     pairkey(r.prev);
                     r.u.key = r.prev.u.key;
-                    r.parent.u.aontu_optional_keys = (r.parent.u.aontu_optional_keys || []);
-                    r.parent.u.aontu_optional_keys.push('' + r.u.key);
+                    snapshotPairSlot(r, '' + r.u.key);
                 },
                 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.
+            {
+                s: [OPTKEY, CL], p: 'val',
+                u: { spread: true, done: true, list: true, pair: true },
+                a: (r) => {
+                    pairkey(r);
+                    snapshotPairSlot(r, '' + r.u.key);
+                },
+                g: 'aontu-plain-pair-elem'
             }
         ])
             .bc((rule) => {
@@ -769,24 +1120,44 @@ help isolate the syntax error.`,
                     (rule.node[type_1.SPREAD] || { o: rule.o0.src, v: [] });
                 rule.node[type_1.SPREAD].v.push(rule.child.node);
             }
+            restorePairSlot(rule);
             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.
+// SECURITY: under the DEFAULT ('system') include capability this
+// resolver reads any file/package the process can reach — @"path"
+// follows relative paths (`@"../../etc/passwd"`) and symlinks, and
+// @"pkg" can require() arbitrary installed modules — so treat opening
+// an untrusted source as running it. 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;
@@ -795,6 +1166,91 @@ 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;
+    };
+    // 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
@@ -805,28 +1261,202 @@ 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) {
+            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);
+            }
+            // 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) {
+            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 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.
+const POSITIONAL_ARG_FUNCS = {
+    deprecate: true, pack: true, each: true, filter: true, match: true,
+    // Arithmetic takes two OPERANDS, and an operand is a position: `sub`
+    // is not commutative, so `sub(a, b)` reaching the engine as one
+    // two-element list would lose which is which.
+    add: true, sub: true, mul: true, div: true, mod: true, rem: true,
+    // The bag and the key are distinct positions.
+    pick: 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 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()
+// takes none (a property of the container) or a PROJECTOR key, must()
+// takes a check AND the author's message for when it fails, and the
+// arithmetic family takes two operands.
+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],
+    // THE ONE ARGUMENT IS A PROJECTOR: `unique(port)` says no two
+    // members share a `port`. The arity was reserved for it (finding I).
+    unique: [0, 1],
+    neq: [1, -1],
+    must: [2, 2],
+    deprecate: [1, 2],
+    id: [1, 1],
+    refer: [0, 1],
+    pack: [2, 2],
+    each: [1, 2],
+    filter: [2, 2],
+    // The scrutinee, then pattern/result pairs, then an optional
+    // default: three arguments at least, and any number above that.
+    match: [3, -1],
+    // Two operands, always. Arithmetic has no variadic reading that is
+    // not a fold, and a fold is the recursion this language refuses.
+    add: [2, 2], sub: [2, 2], mul: [2, 2],
+    div: [2, 2], mod: [2, 2], rem: [2, 2],
+    // One bag. The operation is fixed, so there is nothing else to pass:
+    // a fold's second argument is a FUNCTION, and this language has none
+    // to give it.
+    sum: [1, 1], least: [1, 1], greatest: [1, 1],
+    // The bag, and the key to take from each of its children.
+    pick: [2, 2],
+};
+// writtenArgCount counts the arguments as the AUTHOR wrote them.
+//
+// It cannot simply be terms.length: a comma group reaches the func-paren
+// handler as ONE term holding a raw array, so `upper("a","b")` and
+// `upper(["a","b"])` both arrive as a single argument. They are still
+// distinguishable, and that is what makes an arity check possible at
+// all -- the comma group is a RAW array, while a written list literal
+// has already been built into a ListVal by the list rule.
+function writtenArgCount(terms) {
+    if (1 === terms.length) {
+        // `terms[0]` is re-read rather than reusing a narrowed local:
+        // Array.isArray narrows an `any` to `any[]`, which then has no
+        // `isVal` to test.
+        const t = terms[0];
+        if (Array.isArray(t) && true !== terms[0].isVal) {
+            return t.length;
+        }
+    }
+    return terms.length;
+}
+// arityText renders a built-in's permitted count for the error message.
+// The fixed-arity case says "one" outright rather than counting: every
+// fixed arity in the table IS one, and a phrasing for a count no entry
+// carries would be untested prose pretending to be tested.
+function arityText(lo, hi) {
+    if (-1 === hi) {
+        return 'one or more arguments';
+    }
+    if (lo !== hi) {
+        return 0 === lo ? 'no arguments or one' : 'one argument or two';
+    }
+    // NO {0,0} ARM. `unique` was the only built-in taking none, and its
+    // one argument is now the projector the arity was reserved for
+    // (finding I), so a phrasing for a count no entry carries would be
+    // untested prose pretending to be tested -- the rule this function's
+    // header states. The arm returns with the table, if one ever does.
+    if (2 === hi) {
+        return 'exactly two arguments';
+    }
+    return 'exactly one argument';
+}
 // rawToVal converts a raw parse node (or raw elements inside one) into
 // the matching Val. Used for implicit top-level lists, whose nodes skip
 // the aontu val rule conversions (mirrors asVal in go/lang.go; like
@@ -883,12 +1513,6 @@ function rawToVal(n) {
         return new BooleanVal_1.BooleanVal({ peg: n });
     }
     if ('object' === t) {
-        // An expr-plugin internal (operator descriptor) leaking through a
-        // degenerate parse (`k2.b K:1`) is not data — reject it rather
-        // than emitting raw internals in generated output.
-        if (undefined !== n.OP_MARK) {
-            return new NilVal_1.NilVal({ why: 'parse_unknown' });
-        }
         const peg = {};
         for (const k in n) {
             peg[k] = rawToVal(n[k]);
@@ -932,7 +1556,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;
@@ -954,16 +1584,49 @@ class Lang {
             }
         }
         catch (e) {
-            if (e instanceof jsonic_1.JsonicError || 'JsonicError' === e.constructor.name) {
+            if ('include_denied' === e?.code ||
+                'module_missing' === e?.code || 'module_integrity' === e?.code ||
+                'module_depth' === e?.code) {
+                // A denied include (trust profile, G5): 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: include_denied, class parse).
+                // A denied include (G5) and a module that is missing or fails
+                // its pin (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;
             }