aontu 0.52.0 → 0.53.0

package/src/lang.ts

@@ -3,6 +3,19 @@
 
 // import { performance } from 'node:perf_hooks'
 
+// Named imports, not `import * as`: the namespace form makes tsc emit
+// the __importStar downlevel helper, whose branches no supported Node
+// takes (the same rule cli.ts records). Aliased because `Path` is
+// already the @tabnas/path plugin below.
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import {
+  basename as pathBasename,
+  dirname as pathDirname,
+  join as pathJoin,
+  resolve as pathResolve,
+  sep as pathSep,
+} from 'node:path'
+
 import {
   Jsonic,
   Tabnas,
@@ -34,6 +47,9 @@ import {
   makeMemResolver
 } from '@tabnas/multisource/resolver/mem'
 
+import { STD_SOURCES } from './std'
+import { parseModuleRef, resolveModule, modCacheDir } from './mod'
+
 import {
   Expr,
   Op,
@@ -96,6 +112,20 @@ import { CopyFuncVal } from './val/CopyFuncVal'
 import { KeyFuncVal } from './val/KeyFuncVal'
 import { TypeFuncVal } from './val/TypeFuncVal'
 import { HideFuncVal } from './val/HideFuncVal'
+import { DeprecateFuncVal } from './val/DeprecateFuncVal'
+import { IdFuncVal } from './val/IdFuncVal'
+import { ReferFuncVal } from './val/ReferFuncVal'
+import { PackFuncVal } from './val/PackFuncVal'
+import { EachFuncVal } from './val/EachFuncVal'
+import { FilterFuncVal } from './val/FilterFuncVal'
+import { MatchFuncVal } from './val/MatchFuncVal'
+import {
+  AddFuncVal, SubFuncVal, MulFuncVal, DivFuncVal, ModFuncVal, RemFuncVal,
+} from './val/ArithFuncVal'
+import {
+  SumFuncVal, LeastFuncVal, GreatestFuncVal, PickFuncVal,
+} from './val/AggFuncVal'
+import { PlaceVal } from './val/PlaceVal'
 import { MoveFuncVal } from './val/MoveFuncVal'
 import { PathFuncVal } from './val/PathFuncVal'
 import { PrefFuncVal } from './val/PrefFuncVal'
@@ -108,6 +138,10 @@ import {
   AboveConstraintVal,
   BelowConstraintVal,
   NeqConstraintVal,
+  ReConstraintVal,
+  LengthConstraintVal,
+  UniqueConstraintVal,
+  MustConstraintVal,
 } from './val/ConstraintVal'
 
 
@@ -283,6 +317,16 @@ let AontuJsonic: Plugin = function AontuLang(jsonic: Jsonic) {
     v.site.row = null == r.o0 ? -1 : r.o0.rI
     v.site.col = null == r.o0 ? -1 : r.o0.cI
     v.site.url = ctx.meta.multisource ? ctx.meta.multisource.path : ''
+    // The source text, from the SAME token the row and column above
+    // come from. jsonic has carried it all along; not reading it is
+    // what left a site uneditable (ts/src/site.ts).
+    //
+    // A TOKEN WITH NO TEXT IS NO SPAN, in both ports, and the extent is
+    // DERIVED from the text rather than read from the token's own `len`
+    // — so the Go twin, whose token has no len field, computes the
+    // identical number with utf16Len and nothing has to be kept in step.
+    v.site.src = null == r.o0 ? '' : r.o0.src
+    v.site.len = '' === v.site.src ? -1 : v.site.src.length
     // A keyed rule always carries a path array; a keyless one has none.
     v.path = r.k ? [...r.k.path] : []
 
@@ -361,6 +405,14 @@ help isolate the syntax error.`,
 
         // TODO: FIX: need a TOP instance to hold path
         'top': { val: () => top() },
+
+        // G8 phase 3: the placeholder. A BARE `_` is the hole; `"_"`
+        // quoted, and any longer bare word containing it, stay text.
+        // Reserving it is a breaking change, pinned by place.tsv.
+        '_': {
+          val: (r: Rule, ctx: JsonicContext) =>
+            addsite(new PlaceVal({}), r, ctx)
+        },
       }
     },
 
@@ -420,6 +472,82 @@ help isolate the syntax error.`,
     above: AboveConstraintVal,
     below: BelowConstraintVal,
     neq: NeqConstraintVal,
+
+    // G1 phase 2: pattern membership, over the portable subset both
+    // host regex engines agree on (nonPortableRe in ConstraintVal.ts).
+    re: 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: LengthConstraintVal,
+    unique: 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: MustConstraintVal,
+
+    // G3 phase 4: the deprecation mark. Unification-transparent; the
+    // record rides the result (Val.deprecation) and canon renders the
+    // call back (canonRiders).
+    deprecate: DeprecateFuncVal,
+
+    // G4 phase 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,
+
+    // 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,
+
+    // G8 phase 1: the generation combinators. `pack` makes one keyed
+    // child per child of its data, `each` one list element; both clone
+    // their template per destination exactly as a spread does, and both
+    // wait for the model to settle before they fire (the staging rule,
+    // G8 phase 0).
+    pack: PackFuncVal,
+    each: EachFuncVal,
+
+    // G8 phase 2: selection. `filter` keeps the children of a bag that
+    // unify with a condition; `match` picks the first arm whose
+    // pattern the scrutinee unifies with. Both select by
+    // UNIFIABILITY, tried in trial mode, so neither adds a predicate
+    // language to the one the lattice already is.
+    filter: FilterFuncVal,
+    match: MatchFuncVal,
+
+    // The arithmetic family (the review's finding I). Maths beyond `+`
+    // arrives as FUNCTIONS — `-` `*` `/` `%` stay reserved — and the
+    // family is numeric where the operator is polymorphic, which is
+    // what makes `add` more than a second spelling of `+`: it refuses
+    // the string concatenation that silently answers `"500m" + "500m"`.
+    // Every rule they obey is in ts/src/val/arith.ts.
+    add: AddFuncVal,
+    sub: SubFuncVal,
+    mul: MulFuncVal,
+    div: DivFuncVal,
+    mod: ModFuncVal,
+    rem: RemFuncVal,
+
+    // Aggregation over a finite, settled bag (the review's finding I).
+    // `least` and `greatest` rather than min and max, which are already
+    // the atoms for a lower and an upper BOUND -- an aggregate over a
+    // set and a bound on a value must not share a spelling.
+    sum: SumFuncVal,
+    least: LeastFuncVal,
+    greatest: GreatestFuncVal,
+
+    // Projection, which is what lets the aggregates reach a bag of
+    // RECORDS: `sum(pick($.lines, amountCents))`. Not a clever `each`
+    // template -- `each` MEETS each child, and a meet cannot select.
+    pick: PickFuncVal,
   }
 
 
@@ -433,6 +561,117 @@ help isolate the syntax error.`,
   const incompleteNil = (r: Rule, ctx: JsonicContext) =>
     addsite(new NilVal({ why: 'incomplete_expression' }), r, ctx)
 
+  // Build a call from a NAME and the argument terms as the author
+  // wrote them. 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: Rule, ctx: JsonicContext,
+    fname: string, argterms: any[]): any => {
+    const funcval = funcMap[fname]
+
+    // Arity is known for every built-in, so a surplus or missing
+    // argument is a mistake in the SOURCE, refused here where the
+    // author can see it (issue #51). It was previously left to each
+    // function to notice or not: the two ports disagreed on `upper()`
+    // and on `close()`, and `min(1,2)` noticed nothing at all -- it
+    // built a constraint that merely refused to generate later, with a
+    // message about the map rather than about the call.
+    //
+    // Counted BEFORE the rawToVal pass below, which is what makes the
+    // count possible: a comma group arrives as a RAW array and a
+    // written list literal as a ListVal, and rawToVal turns the first
+    // into the second.
+    const arity = funcArity[fname]
+    if (null != arity) {
+      const got = writtenArgCount(argterms)
+      if (got < arity[0] || (-1 !== arity[1] && got > arity[1])) {
+        // details is assigned AFTER construction: the NilVal
+        // constructor does not read it from its spec (only NilVal.make
+        // does), so passing it in the spec left the hint's
+        // {func}/{want}/{got} placeholders un-injected and printed
+        // literally.
+        const nil: any = new NilVal({ why: 'func_arity' })
+        nil.details = {
+          func: fname,
+          want: arityText(arity[0], arity[1]),
+          got: '' + got,
+        }
+        // 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: any = null == funcval ?
+      new 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: any, val: any): any[] => {
+    const written: any[] = 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: any = {
     'conjunct-infix': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) =>
       addsite(new ConjunctVal({ peg: dropUnfilled(terms) }), r, ctx),
@@ -512,21 +751,55 @@ help isolate the syntax error.`,
       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: Rule, ctx: JsonicContext, _op: Op, terms: any) => {
+      const val = terms[0]
+      const call: any = 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({ why: 'pipe_target' }), r, ctx)
+    },
+
     'func-paren': (r: Rule, ctx: JsonicContext, _op: Op, terms: any) => {
       let val = terms[1]
       const fname = terms[0]
+
       if ('' !== fname) {
-        const funcval = funcMap[fname]
-        const args = terms.slice(1)
-        val = null == funcval ?
-          new NilVal({ why: 'unknown_function' }) :
-          new funcval({
-            peg: args
-          })
+        val = buildCall(r, ctx, fname, terms.slice(1))
       }
       // `a:()` — grouping parens with nothing inside.
       if (null == val) return incompleteNil(r, ctx)
-      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
     },
   }
@@ -544,6 +817,14 @@ help isolate the syntax error.`,
           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,
@@ -755,6 +1036,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? }
 
@@ -783,13 +1071,60 @@ help isolate the syntax error.`,
         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({ 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: any = addsite(new 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({ 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: any = (mo as any)[SPREAD]
+        if (sp && sp.v.some((sv: any) => null == sv)) {
+          r.node = addsite(new NilVal({ why: 'elided_value' }), r, ctx)
+          return undefined
+        }
+
         //  Handle defered conjuncts, e.g. `{x:1 @"foo"}`
         if (mo.___merge) {
           let mop = { ...mo }
@@ -826,11 +1161,15 @@ help isolate the syntax error.`,
 
         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({ peg: null }), r, ctx)
+            // Pathed at the INDEX, for the same reason as the map case.
+            const en: any = addsite(new NilVal({ why: 'elided_value' }), r, ctx)
+            en.path = [...(r.k?.path ?? []), '' + i]
+            ao[i] = en
           }
         }
 
@@ -865,6 +1204,51 @@ help isolate the syntax error.`,
   }
 
 
+  // 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: Rule): Record<string, any> => r.node as any
+
+  const snapshotPairSlot = (r: Rule, key: string) => {
+    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: Rule) => {
+    const slot: any = 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: RuleSpec) => {
     rs
       .open([
@@ -955,11 +1339,31 @@ 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'
         }
       ])
 
@@ -973,6 +1377,8 @@ help isolate the syntax error.`,
           rule.node[SPREAD].v.push(rule.child.node)
         }
 
+        restorePairSlot(rule)
+
         return undefined
       })
 
@@ -985,19 +1391,41 @@ help isolate the syntax error.`,
 
 
 
-// SECURITY: the default resolver reads any file/package the process can
-// reach — @"path" follows relative paths (`@"../../etc/passwd"`) and
-// symlinks with no containment check, and @"pkg" can require() arbitrary
-// installed modules. This is intentional for the CLI, but it means a
-// `.aon` source can read referenced files; the LSP uses this same
-// resolver, so treat opening an untrusted source as running it. Pass a
-// confined `options.resolver` to restrict reads in less-trusted contexts.
+// 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: any) {
   const useRequire = options.require || require
-
-  let memResolver = makeMemResolver({
-    ...(options.resolver?.mem || {})
-  })
+  const capability = options.trust?.include ?? 'system'
+
+  const memCapability =
+    'object' === typeof capability && null != (capability as any).mem
+  const rootDir: string | undefined =
+    'object' === typeof capability &&
+      'string' === typeof (capability as any).root
+      ? pathResolve((capability as any).root) : undefined
+
+  // Under the mem capability the CAPABILITY's file set is the whole
+  // world; otherwise the host-injected `options.resolver.mem` entries
+  // remain available under every capability but 'none' — they are
+  // host-provided, not document-requested, so confining them would
+  // confine the host against itself.
+  // THE BUNDLED VOCABULARY (G4 phase 4, ts/src/std.ts) rides the
+  // memory leg: served from the engine itself, so it needs neither the
+  // filesystem nor package resolution and is available under every
+  // capability but `none` — which denies every include outright, that
+  // being what `none` means. Host entries and the capability's own set
+  // WIN over it: a caller that supplies its own `std/system` gets the
+  // one it supplied.
+  let memResolver = makeMemResolver(memCapability
+    ? { ...(capability as any).mem }
+    : { ...(options.resolver?.mem || {}) })
 
   // TODO: make this consistent with other resolvers
   let fileResolver = makeFileResolver((spec: any) => {
@@ -1009,6 +1437,100 @@ function makeModelResolver(options: any) {
     ...(options.resolver?.pkg || {})
   })
 
+  // Confinement is realpath-then-prefix-check (docs/trust.md): the
+  // RESOLVED file's real path must sit below the root's real path, so a
+  // symlink inside the root pointing outside it is an escape, not a
+  // loophole. A path realpath cannot resolve falls back to the lexical
+  // form — the comparison is then against what the resolver actually
+  // read.
+  // Real fs, deliberately: `options.fs` is not a sandbox (it feeds
+  // parse text; the file leg reads through its own channel), so the
+  // containment check must see the same filesystem that leg read from.
+  // A path that does not (fully) exist cannot be realpath'd whole, and
+  // falling back to the LEXICAL form compares apples to oranges when
+  // the root itself sits behind a symlink -- on macOS a root under
+  // /var realpaths to /private/var, so a merely-missing file inside it
+  // reads as an escape. Realpath the deepest EXISTING ancestor and
+  // re-attach the rest, so both sides of the check are in real
+  // coordinates. (The MCP server's own confinement carries the twin of
+  // this rule; its CI failure is what found the shape.)
+  const realpath = (p: string): string => {
+    try {
+      return realpathSync(p)
+    }
+    catch {
+      const parent = pathDirname(p)
+      if (parent === p) {
+        return p
+      }
+      return pathJoin(realpath(parent), pathBasename(p))
+    }
+  }
+
+  const outsideRoot = (root: string, full: string): boolean => {
+    const rootReal = realpath(root)
+    const fullReal = realpath(full)
+    return fullReal !== rootReal && !fullReal.startsWith(rootReal + pathSep)
+  }
+
+  // A denial THROWS with the code; Lang.parse converts it to the
+  // parse-stage `include_denied` nil (the same shape a syntax failure
+  // takes). Raising beats injecting a nil value: a bare-member include
+  // (`@"denied.aon"` at the top of a file) MERGES into the enclosing
+  // map, and a nil contributes no keys, so an injected denial would
+  // vanish and leave a plausible, silently-partial document.
+  const deny = (path: string): never => {
+    // Only 'none' and 'root' can deny: the mem capability's misses are
+    // not-found (its set is the whole world), so there is no third arm.
+    const capname = 'none' === capability ? 'none' : 'root:' + rootDir
+    const err: any = new Error(
+      'include denied: ' + path + ' (capability: ' + capname + ')')
+    err.code = 'include_denied'
+    throw err
+  }
+
+  // The user cache: whatever the host named, else the platform rule
+  // (`modCacheDir`, ts/src/mod.ts) the tooling writes by.
+  const modCache = (opts: any): string | undefined => {
+    const named = opts.mod?.cache
+    return 'string' === typeof named ? named : modCacheDir()
+  }
+
+  // The directory an include is being resolved FROM: the source that
+  // holds it, or the entry path when the source is a string. Same base
+  // the file leg computes (resolvePathSpec in @tabnas/multisource).
+  const dirOf = (p: string | undefined): string =>
+    null == p || '' === p ? pathResolve('.') : pathDirname(pathResolve(p))
+
+  // The module store reader: the host's filesystem when one was
+  // injected, so a sandboxed evaluation stays in the filesystem the
+  // host gave it.
+  const modFs = (ctx: any): any => {
+    const hostfs = ctx?.meta?.fs
+    return null == hostfs ? { existsSync, readFileSync } : {
+      existsSync: (p: string) => {
+        try {
+          hostfs.statSync(p)
+          return true
+        }
+        catch {
+          return false
+        }
+      },
+      readFileSync: (p: string, enc: string) => hostfs.readFileSync(p, enc),
+    }
+  }
+
+  // The manifest sink rides the parse meta (Lang.parse seeds it, the
+  // multisource plugin's child-meta spread carries it to every nested
+  // include), so the recorded closure covers the whole include tree.
+  const record = (ctx: any, path: string, cap: string) => {
+    const manifest = ctx?.meta?.aontu?.manifest
+    if (Array.isArray(manifest)) {
+      manifest.push({ path, capability: cap })
+    }
+  }
+
   return function ModelResolver(
     spec: any,
     popts: any,
@@ -1028,10 +1550,64 @@ function makeModelResolver(options: any) {
       return { found: false, path: '' + (path ?? ''), search: [] }
     }
 
+    if ('none' === capability) {
+      deny(path)
+    }
+
+    // THE BUNDLED VOCABULARY (G4 phase 4, ts/src/std.ts): served from
+    // the engine itself, so it needs neither the filesystem nor package
+    // resolution and is available under every capability but `none` —
+    // checked just above, that being what `none` means. Matched against
+    // the name the author WROTE, before the memory leg, so the kind is
+    // stated rather than guessed from an extension the bare name does
+    // not have.
+    const std = STD_SOURCES[path]
+    if (null != std) {
+      record(ctx, path, 'std')
+      return { found: true, path, full: path, kind: 'aon', src: std, search: [] }
+    }
+
     let search: any = []
     let res = memResolver(path, popts, rule, ctx, jsonic)
     res.path = path
     if (res.found) {
+      record(ctx, res.full ?? path, 'mem')
+      return res
+    }
+
+    // THE MODULE LEG (G6 phase 2, ts/src/mod.ts): memory -> MODULE ->
+    // filesystem -> package. Memory stays FIRST so a sandbox and the
+    // spec suite can stub a module path without touching disk; a path
+    // that is not module-shaped falls straight through, so no existing
+    // include can be routed somewhere new by this.
+    const modref = memCapability ? undefined : parseModuleRef(path)
+    if (null != modref) {
+      const msmeta = (ctx as any)?.meta?.multisource
+      const from = dirOf(null != msmeta?.path ? msmeta.path : popts?.path)
+      const found = resolveModule(modref, from, modFs(ctx), {
+        // The user cache lives outside any confinement root, so it is
+        // consulted only when nothing confines this evaluation. A
+        // rooted profile sees the project's own `aon_vendor/` and
+        // nothing else, which is what `root` means.
+        ...(null == rootDir ? { cache: modCache(options) } : {}),
+        eval: options.mod?.eval,
+        depth: options.mod?.depth,
+      })
+      if (null != rootDir && outsideRoot(rootDir, found.full)) {
+        deny(path)
+      }
+      record(ctx, found.full, 'mod')
+      return {
+        found: true, path, full: found.full,
+        kind: 'aon', src: found.src, search: [],
+      }
+    }
+
+    if (memCapability) {
+      // A miss in the declared virtual set is NOT-FOUND, not denial:
+      // the allowed mechanism ran and missed. Denial is reserved for a
+      // capability refusing a mechanism outright.
+      res.search = search.concat(res.search)
       return res
     }
 
@@ -1040,14 +1616,42 @@ function makeModelResolver(options: any) {
     res = fileResolver(path, popts, rule, ctx, jsonic)
     res.path = path
     if (res.found) {
+      // `res.full` asserted non-null: a FOUND file resolution always
+      // carries the absolute path it read (and the pkg leg below is the
+      // same), so a runtime fallback arm would be dead code.
+      const full = res.full as string
+      if (null != rootDir && outsideRoot(rootDir, full)) {
+        deny(path)
+      }
+      // 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 as string)
+      }
+      record(ctx, res.full as string, 'pkg')
       return res
     }
 
@@ -1057,6 +1661,111 @@ function makeModelResolver(options: any) {
 }
 
 
+// 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: Record<string, boolean> = {
+  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: Record<string, [number, number]> = {
+  upper: [1, 1], lower: [1, 1], copy: [1, 1], pref: [1, 1],
+  super: [1, 1], type: [1, 1], hide: [1, 1], close: [1, 1],
+  open: [1, 1], move: [1, 1], path: [1, 1],
+  min: [1, 1], max: [1, 1], above: [1, 1], below: [1, 1], re: [1, 1],
+  length: [1, 1],
+  key: [0, 1],
+  // 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: any[]): number {
+  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: any = terms[0]
+    if (Array.isArray(t) && true !== (terms[0] as any).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: number, hi: number): string {
+  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
@@ -1115,12 +1824,6 @@ function rawToVal(n: any): Val {
     return new 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 as any).OP_MARK) {
-      return new NilVal({ why: 'parse_unknown' })
-    }
     const peg: Record<string, Val> = {}
     for (const k in n) {
       peg[k] = rawToVal(n[k])
@@ -1179,7 +1882,13 @@ class Lang {
       multisource: {
         path: opts?.path ?? this.opts.path,
         deps: (opts && opts.deps) || undefined
-      }
+      },
+      // The include-manifest sink (G5, docs/trust.md): the resolver
+      // records every resolved include here, and the plugin's
+      // child-meta spread carries the same array to nested includes.
+      aontu: {
+        manifest: (opts as any)?.manifest,
+      },
     }
 
     if (null != opts?.idcount) {
@@ -1207,16 +1916,49 @@ class Lang {
       }
     }
     catch (e: any) {
-      if (e instanceof 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({
           why: 'parse',
           err: new NilVal({
-            why: 'syntax',
-            msg: e.message + opCharHint(src),
+            why: e.code,
+            msg: e.message,
             err: e,
           })
         })
       }
+      else if (e instanceof JsonicError || 'JsonicError' === e.constructor.name) {
+        const syntax: any = new NilVal({
+          why: 'syntax',
+          msg: e.message + opCharHint(src),
+          err: e,
+        })
+        // THE POSITION TRAVELS WITH IT. The parser knows exactly where
+        // it stopped -- it draws a caret there -- and the rendered
+        // message carried the only copy, so `vet --format json`
+        // reported row -1, col -1 for a document whose fault the human
+        // renderer located to the character. A machine-readable report
+        // that says "somewhere in this file" is the one a repair loop
+        // can do nothing with. Both numbers are already 1-based here,
+        // which is the base a site uses (go/lang.go does the same).
+        if ('number' === typeof e.lineNumber) {
+          syntax.site.row = e.lineNumber
+        }
+        if ('number' === typeof e.columnNumber) {
+          syntax.site.col = e.columnNumber
+        }
+        val = new NilVal({ why: 'parse', err: syntax })
+      }
       else {
         throw e
       }