aontu 0.58.0 → 0.59.0

package/src/aontu.ts

@@ -38,7 +38,7 @@ export type { LintFinding, FormatReport, FormatOptions } from './format'
 // Kept in step with package.json by the `version` npm lifecycle script,
 // which runs on `npm version` / `npm run repo-bump`. version.test.ts
 // fails if the two ever drift.
-const VERSION = '0.58.0'
+const VERSION = '0.59.0'
 
 
 // A module file's VALUE, as far as it goes. COLLECTED, not raised: a
@@ -103,6 +103,7 @@ class Aontu {
   ctx(cfg?: AontuContextConfig): AontuContext {
     cfg = cfg ?? {}
     cfg.fs = cfg.fs ?? this.opts.fs
+    ;(cfg as any).errfs = (cfg as any).errfs ?? (this.opts as any).errfs
     // The trust profile rides the instance (its resolver is built once,
     // in the Lang constructor); the context needs it too, for the
     // budgets (G5, docs/trust.md).

package/src/cli.ts

@@ -603,7 +603,17 @@ function runFile(file: string, mode: Mode, trust: TrustArg): number {
   }
 
   const path = resolve(file)
-  const aontu = new Aontu({ path, ...trustOpts(trust, dirname(path)) })
+  // `fs` IS WHAT MAKES A FRAME EXCERPT THE FILE IT NAMES. Without it,
+  // err.ts's resolveSrc falls back to the ENTRY text, so a frame whose
+  // arrow says `lib/types.aon:2:6` printed the entry's line 2 under it
+  // -- a real file name over another file's line, which
+  // docs/reference-api.md forbids in the same words it uses to require
+  // the name.
+  const aontu = new Aontu({
+    path,
+    errfs: { existsSync, readFileSync },
+    ...trustOpts(trust, dirname(path)),
+  })
   const res = evalSource(aontu, src, mode)
   ;(res.ok ? process.stdout : process.stderr).write(res.text + '\n')
   return res.ok ? 0 : 1

package/src/ctx.ts

@@ -35,6 +35,7 @@ type AontuContextConfig = {
   // (Val.origin, Val.emitted), so one flag turns the whole record on.
   reads?: Set<string>
   fs?: any
+  errfs?: any
   path?: string[]
   root?: Val
   seen?: Record<string, number>
@@ -77,6 +78,8 @@ class AontuContext {
   vars: Record<string, Val> = {}
   src?: string
   fs?: FST
+  // The error renderer's own reader; see type.ts's `errfs`.
+  errfs?: FST
 
   seenI: number
   seen: Record<string, number>
@@ -199,6 +202,7 @@ class AontuContext {
     this.explain = Array.isArray(cfg.explain) ? cfg.explain : null
 
     this.fs = cfg.fs ?? null
+    this.errfs = cfg.errfs ?? null
 
     // Multiple unify passes will keep incrementing Val counter.
     this.vc = null == cfg.vc ? 1_000_000_000 : cfg.vc
@@ -320,6 +324,7 @@ class AontuContext {
     this.err = this.opts.err ?? this.err
     this.deps = this.opts.deps ?? this.deps
     this.fs = this.opts.fs ?? this.fs
+    this.errfs = (this.opts as any).errfs ?? this.errfs
     this.explain = this.opts.explain ?? this.explain
 
     this.src = ('string' === typeof this.opts.src ? this.opts.src : undefined) ?? this.src

package/src/err.ts

@@ -208,9 +208,12 @@ function resolveSrc(v: Val, errctx: ErrContext | undefined) {
     }
     else {
       try {
-        const fileExists = errctx?.fs?.existsSync(url)
+        // errfs first: the CLI gives the renderer a reader without
+        // giving the resolver one (type.ts, `errfs`).
+        const reader = errctx?.errfs ?? errctx?.fs
+        const fileExists = reader?.existsSync(url)
         if (fileExists) {
-          src = errctx?.fs?.readFileSync(url, 'utf8') ?? undefined
+          src = reader?.readFileSync(url, 'utf8') ?? undefined
         }
       }
       catch (fe: any) {
@@ -228,7 +231,7 @@ function resolveSrc(v: Val, errctx: ErrContext | undefined) {
     }
     else if (errctx) {
       src = 'SOURCE-NOT-FOUND:' + (null != url ? (' ' + url) : '') +
-        (null == errctx?.fs ? ' (NO-FS)' : '')
+        (null == (errctx?.errfs ?? errctx?.fs) ? ' (NO-FS)' : '')
     }
   }
 

package/src/lang.ts

@@ -807,6 +807,38 @@ help isolate the syntax error.`,
         // Handle defered conjuncts, where MapVal does not yet
         // exist, by creating ConjunctVal later.
         else {
+          // AN INCLUDE UNIFIES IN PLACE. multisource calls this hook at
+          // the `@`'s own source position, so `prev` holds exactly the
+          // pairs written BEFORE it. Folding the loaded map's keys in
+          // here -- host-so-far first, arriving value second -- is what
+          // inlining the loaded bytes at the `@` does, and mirrors
+          // go/lang.go's Map.Merge, which multisource-go drives one key
+          // at a time. A non-map load has no keys to fold and stays a
+          // deferred conjunct arm.
+          if (true === (cval as any)?.isMap) {
+            const lm: any = cval
+            for (const k of Object.keys(lm.peg)) {
+              const own = (prev as any)[k]
+              ;(prev as any)[k] = (null == own) ? lm.peg[k] :
+                (own?.isVal
+                  ? new ConjunctVal({ peg: [own, lm.peg[k]] })
+                  : lm.peg[k])
+            }
+            // The loaded map's spread joins THIS map's spread list at
+            // the `@`'s position: the parse pushes each `&:` onto the
+            // node as it is read, so `prev[SPREAD].v` already holds the
+            // spreads written before the `@` and nothing after it.
+            if (null != lm.spread?.cj) {
+              ;(prev as any)[SPREAD] =
+                ((prev as any)[SPREAD] || { o: '&', v: [] })
+              ;(prev as any)[SPREAD].v.push(lm.spread.cj)
+            }
+            prev.___optional = (prev.___optional || [])
+            for (const k of lm.optionalKeys) { prev.___optional.push(k) }
+            prev.___alias = (prev.___alias || [])
+            for (const k of lm.aliasKeys) { prev.___alias.push(k) }
+            return prev
+          }
           prev.___merge = (prev.___merge || [])
           prev.___merge.push(curr)
           return prev
@@ -1436,7 +1468,8 @@ help isolate the syntax error.`,
         // 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) {
+          if (null == mo[k] && '___merge' !== k &&
+            '___optional' !== k && '___alias' !== k) {
             // 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
@@ -1497,6 +1530,19 @@ help isolate the syntax error.`,
           mo[key] = en
         }
 
+        // Marks carried over from a map include folded in the merge
+        // hook above, applied here where the MapVal is built.
+        if (mo.___optional || mo.___alias) {
+          for (const k of (mo.___optional || [])) {
+            if (!optionalKeys.includes(k)) { optionalKeys.push(k) }
+          }
+          for (const k of (mo.___alias || [])) {
+            if (!aliasKeys.includes(k)) { aliasKeys.push(k) }
+          }
+          delete mo.___optional
+          delete mo.___alias
+        }
+
         //  Handle defered conjuncts, e.g. `{x:1 @"foo"}`
         if (mo.___merge) {
           let mop = { ...mo }

package/src/type.ts

@@ -61,6 +61,14 @@ type AontuOptions = {
   debug?: boolean
   trace?: boolean
   fs?: FST
+  // errfs READS FOR THE ERROR RENDERER ONLY, never for resolution.
+  // A frame excerpts the file its arrow names, which means reading
+  // that file -- but handing the same reader to `fs` would change
+  // which leg the include RESOLVER takes (its file leg reads through
+  // the host filesystem when one is given, so a package hit can
+  // become a file hit), and a diagnostic must not move the boundary
+  // it is describing.
+  errfs?: FST
   deps?: any
   log?: any
   idcount?: number
@@ -103,7 +111,8 @@ type ValList = Val[]
 
 type ErrContext = {
   src?: string,
-  fs?: FST
+  fs?: FST,
+  errfs?: FST
 } /* node:coverage ignore next 24 */
 
 export type {

package/src/val/DisjunctVal.ts

@@ -101,6 +101,27 @@ class DisjunctVal extends JunctionVal {
     // before return.
     const savedErr = ctx.err
     const savedTrialMode = ctx._trialMode
+    // THE SANDBOX MUST NOT OUTLIVE THE TRIAL AS AN OWN PROPERTY.
+    // Contexts are made with Object.create(parent) and CACHED per
+    // (parent, key) by AontuContext.descend, so `err` and `_trialMode`
+    // are normally INHERITED -- and assigning them here, the restore
+    // included, creates own properties that shadow the ancestor on
+    // every later pass. A child that has run a trial of its own then
+    // cannot see the trial its PARENT is running: makeNilErr allocates
+    // a real NilVal instead of TRIAL_NIL, the refusal lands on the
+    // meet's real error list, and the losing member is kept as though
+    // it had survived -- with the nil inside it. A vet run then
+    // reported the conflicts of arms that should have dropped out, and
+    // called the document invalid where it is incomplete.
+    //
+    // So the restore DELETES what was inherited rather than writing it
+    // back. Both arms of both guards are live: the root meet context
+    // has an own `err`, a descended child does not, and `_trialMode`
+    // is own exactly when a disjunction is tried inside another
+    // disjunction's trial on the same context.
+    const ownErr = Object.prototype.hasOwnProperty.call(ctx, 'err')
+    const ownTrialMode =
+      Object.prototype.hasOwnProperty.call(ctx, '_trialMode')
     // A MEMBER'S TYPE FLOW IS PART OF THAT MEMBER. `refer(t)`/`rel(t)`
     // assert `t` on ANOTHER node, and the assertion may only take
     // effect if the member that makes it survives: committing every
@@ -194,8 +215,18 @@ class DisjunctVal extends JunctionVal {
       }
     }
     finally {
-      ctx._trialMode = savedTrialMode
-      ctx.err = savedErr
+      if (ownTrialMode) {
+        ctx._trialMode = savedTrialMode
+      }
+      else {
+        delete (ctx as any)._trialMode
+      }
+      if (ownErr) {
+        ctx.err = savedErr
+      }
+      else {
+        delete (ctx as any).err
+      }
       ;(ctx as any).referflows = savedFlows
     }
 

package/src/val/FuncBaseVal.ts

@@ -46,6 +46,13 @@ import { hasPlace, fillPlace } from '../val/PlaceVal'
 function trialUnify(ctx: AontuContext, a: Val, b: Val): Val | undefined {
   const savedErr = ctx.err
   const savedTrial = ctx._trialMode
+  // Restored by DELETION where they were inherited, for the reason
+  // DisjunctVal.unify's own sandbox gives at length: contexts are
+  // Object.create(parent) and cached per (parent, key), so writing
+  // these back leaves own properties that shadow the ancestor and make
+  // a later trial invisible to the value running inside it.
+  const ownErr = Object.prototype.hasOwnProperty.call(ctx, 'err')
+  const ownTrial = Object.prototype.hasOwnProperty.call(ctx, '_trialMode')
   const trialErr: any[] = []
 
   ctx.err = trialErr
@@ -56,8 +63,18 @@ function trialUnify(ctx: AontuContext, a: Val, b: Val): Val | undefined {
     out = unite(ctx, a, b, 'trial')
   }
   finally {
-    ctx.err = savedErr
-    ctx._trialMode = savedTrial
+    if (ownErr) {
+      ctx.err = savedErr
+    }
+    else {
+      delete (ctx as any).err
+    }
+    if (ownTrial) {
+      ctx._trialMode = savedTrial
+    }
+    else {
+      delete (ctx as any)._trialMode
+    }
   }
 
   return 0 < trialErr.length || out.isNil ? undefined : out
@@ -158,22 +175,28 @@ class FuncBaseVal extends FeatureVal {
 
 
   // THE PER-DESTINATION INSTANTIATION RULE (ADR-005). The default
-  // clone shares the argument array AND the argument Vals — pinned
-  // sharing for the move()/copy() ghost artifacts (test/spec/func.tsv,
-  // ghost-*-innard-canon) — but a clone that is a template INSTANCE
-  // must own the full inner structure: with the args shared,
-  // `pack($.names, close({name: key()}))` resolved key() once inside
-  // the one shared inner map and stamped the FIRST child's key on
-  // every child (use-cases/BUGS.md §8). The `dup` spec flag asks for
-  // that depth; everything else keeps the sharing it has always had.
+  // clone shares the argument array AND the argument Vals — the
+  // residuation clone, which stays at one position and wants the
+  // sharing, and the reference copy of a target that still holds a
+  // staged call, which pins the move()/copy() ghost artifacts
+  // (test/spec/func.tsv, ghost-*-innard-canon; ADR-025) — but a clone
+  // that is an INSTANCE must own the full inner structure: with the
+  // args shared, `pack($.names, close({name: key()}))` resolved key()
+  // once inside the one shared inner map and stamped the FIRST
+  // child's key on every child (use-cases/BUGS.md §8). The `dup` spec
+  // flag asks for that depth; everything else keeps the sharing it
+  // has always had.
   clone(ctx: AontuContext, spec?: ValSpec): Val {
     const out = super.clone(ctx, spec) as FuncBaseVal
     if (true === spec?.dup && Array.isArray(this.peg)) {
       // Every argument is a Val by construction (the parser builds
       // them; make() rebuilds from driven Vals), as the Go twin's
-      // []Val typing states outright. The instantiation sites then
-      // normalise every path in the clone (repathInstance), so the
-      // argument-shaped parse paths never leak into an instance.
+      // []Val typing states outright. The generator and spread
+      // instantiation sites then normalise every path in the clone
+      // (repathInstance), so the argument-shaped parse paths never
+      // leak into an instance; the reference copy takes the paths
+      // this rebasing gives, which is what an absolute address in a
+      // copied model already expects (ADR-014).
       out.peg = this.peg.map((a: Val) => a.clone(ctx, { dup: true }))
     }
     return out

package/src/val/ListVal.ts

@@ -335,7 +335,15 @@ class ListVal extends BagVal {
       { mark: spec?.mark, dup: spec?.dup } : {}
     for (let entry of Object.entries(this.peg)) {
       out.peg[entry[0]] =
-        (entry[1] as any)?.isVal ? (entry[1] as Val).clone(ctx, childspec) : entry[1]
+        (entry[1] as any)?.isVal ? (entry[1] as Val).clone(ctx, {
+          ...childspec,
+          // AN ELEMENT IS A POSITION, exactly as a map's child is
+          // (MapVal.clone). Without this an explicitly pathed clone
+          // rebased the list and left every element at its source
+          // path -- the Go twin descends by index (go/clone.go, the
+          // *ListVal arm of clonePathKind).
+          path: [...out.path, entry[0]],
+        }) : entry[1]
     }
     if (this.spread.cj) {
       out.spread.cj = this.spread.cj.clone(ctx, childspec)

package/src/val/PlaceVal.ts

@@ -133,7 +133,11 @@ function hasPlace(v: Val): boolean {
 // generator's to fill with its OWN source children when it fires.
 function fillPlace(v: Val, fill: Val, ctx: AontuContext): Val {
   if (true === (v as any).isPlace) {
-    return fill
+    // A FILL IS A POSITION. The hole knows where it sits in the
+    // instance; the datum arriving in it does not, and inserted as it
+    // stands it keeps the paths it had at its SOURCE, so every finding
+    // under it names a path that does not exist.
+    return fill.clone(ctx, { path: [...(v as any).path] })
   }
 
   const peg: any = (v as any).peg

package/src/val/RefVal.ts

@@ -653,7 +653,31 @@ class RefVal extends FeatureVal {
           const lifted = true !== (ctx as any).argsnap
             || true === out.mark.type || true === out.mark.hide
 
-          out = out.clone(ctx)
+          // A REFERENCE'S COPY OWNS ITS ARGUMENTS (ADR-025). The copy
+          // is a per-destination instance exactly as a spread's or a
+          // generator's is, so ADR-005's rule holds here too: nothing
+          // path-dependent may be shared between two destinations, or
+          // the first destination's resolution answers for them all.
+          // The shallow clone shared a call's ARGUMENTS -- so
+          // `items: [&: $.entities.User]` over a `close({...})` target
+          // gave every element the one inner map, whose path each
+          // element rebased in turn, and the constraint that failed at
+          // element 2 reported element 0's path (use-cases GAP 8).
+          //
+          // A STAGED CALL IS THE EXCEPTION, because it has not decided
+          // yet. Its arguments are still being driven AT ITS OWN SITE
+          // (the staging rule, G8 phase 0), and a copy that owned them
+          // would drive its own set at the referring position instead:
+          // the relative `.side_effect` in a `match()` would read the
+          // referring field's siblings (use-cases/09-agent-tools), and
+          // an alias naming an `emit` rule table -- a template, which
+          // is exactly a value copied before it resolves -- would read
+          // its recursive `%w` as a self-reference. A staged call
+          // ANYWHERE in the target counts: what is referenced is
+          // usually the conjunct the call sits in, not the call.
+          // The copy shares what the source is still settling, and
+          // owns the rest.
+          out = out.clone(ctx, { dup: !out.holdsStaged })
 
           if (lifted) {
             walk(out, (_key: string | number | undefined, val: Val) => {

package/src/val/Val.ts

@@ -44,9 +44,12 @@ type ValSpec = {
   // depth explicitly: `dup: true` makes FuncBaseVal, PrefVal and
   // OpBaseVal clone their inner Vals too, and the bag/junction clones
   // carry the flag down. Set by pack/each template instantiation,
-  // filter condition testing, and spread application (MapVal/
-  // ListVal.spreadClone) — never by the residuation or ref-resolution
-  // clones, whose sharing is pinned behaviour.
+  // filter condition testing, spread application (MapVal/
+  // ListVal.spreadClone), and REFERENCE RESOLUTION of a target that
+  // holds no staged call, whose copy is a per-destination instance
+  // too (ADR-025) — never by the residuation clone, whose sharing is
+  // pinned behaviour, and never by a copy of something still being
+  // settled at its own site, which is what keeps the ghost rows.
   dup?: boolean,
 
 
@@ -440,6 +443,33 @@ abstract class Val {
   }
 
 
+  // A STAGED CALL STANDING ANYWHERE IN THIS VALUE (the `staged` flag,
+  // G8 phase 0). Such a call has not decided: its arguments are still
+  // being driven AT ITS OWN SITE, so a REFERENCE's copy shares it
+  // rather than owning a set of arguments it would drive at the
+  // referring position instead (RefVal.find, ADR-025). Not cached:
+  // unlike isPathDependent this is a fact about the value's current
+  // state, and the whole point is that it stops being true.
+  get holdsStaged(): boolean {
+    if (true === (this as any).staged) {
+      return true
+    }
+    const peg: any = this.peg
+    if (Array.isArray(peg)) {
+      for (let i = 0; i < peg.length; i++) {
+        if (true === peg[i]?.isVal && peg[i].holdsStaged) return true
+      }
+    }
+    else if (null != peg && 'object' === typeof peg) {
+      for (const k in peg) {
+        if (true === peg[k]?.isVal && peg[k].holdsStaged) return true
+      }
+    }
+    const spreadCj = (this as any).spread?.cj as Val | undefined
+    return true === spreadCj?.isVal && (spreadCj as any).holdsStaged
+  }
+
+
   // PUT A MINTED VALUE WHERE THIS ONE STANDS: the site travels, and so
   // does provenance, because the two answer one question. A narrowed
   // disjunction, a lifted kind, a resolved reference -- each is a