aontu 0.52.0 → 0.53.0

package/src/ctx.ts

@@ -21,6 +21,11 @@ type AontuContextConfig = {
   cc?: number
   err?: any[] // Omit<NilVal[], "push">
   explain?: any[] | boolean | null
+
+  // The provenance recorder (G7 phase 3), or absent for an
+  // uninstrumented run. Shared by reference down every descend, as the
+  // error list is, so one run has one record.
+  prov?: any
   fs?: any
   path?: string[]
   root?: Val
@@ -41,6 +46,26 @@ class AontuContext {
   path: string[]  // Path to current Val.
   vc: number  // Val counter to create unique val ids.
   cc: number = -1
+
+  // THE STAGING RULE (G8 phase 0,
+  // docs/capability-review/g8-generation.md). A value whose answer
+  // depends on WHERE IT IS -- `key()` today, the generation
+  // combinators next -- must not answer while anything is still
+  // moving it: resolved early it reports the position it was WRITTEN
+  // at rather than the one it ends up at. Such a value RESIDUATES
+  // while this is false, and fires exactly once on the pass where it
+  // is true.
+  //
+  // The pass loop (ts/src/unify.ts) sets it on the first pass whose
+  // input tree is IDENTICAL to the previous pass's: everything that
+  // was going to move has moved, and what is left is the staged
+  // values themselves, which is precisely the moment they may answer.
+  // It replaces a `ctx.cc < 3` pass count in KeyFuncVal -- a magic
+  // number, right for the documents it was tuned on and silently
+  // wrong for anything that took a fourth pass to place a value. The
+  // comment it replaces said as much: "this delay makes keys in
+  // spreads and refs work, but it is a hack - find a better way".
+  settle: boolean = false
   vars: Record<string, Val> = {}
   src?: string
   fs?: FST
@@ -50,6 +75,25 @@ class AontuContext {
 
   collect: boolean
 
+  // THE COMPLETENESS PROBE (the review's finding C). vet detects
+  // residue by GENERATING the anchored meet and keeping the
+  // incomplete-class failures. Generation honours the OUTPUT marks --
+  // `type()` and `hide()` say "do not emit this" -- so a `--at` anchor
+  // sitting under a mark generated nothing at all, reported nothing,
+  // and vetted VALID for data missing a required field, while the same
+  // anchor without the mark answered incomplete (use-cases/BUGS.md
+  // §14). A mark is a decision about OUTPUT; it is not a statement
+  // about what the data must satisfy, and `--at` names the truth to
+  // validate against explicitly. Under this flag the generation walk
+  // descends through marked values; nothing else changes, and no
+  // output is produced from a probe run -- only its findings are read.
+  probe: boolean = false
+
+  // The provenance recorder (G7 phase 3), or undefined for an
+  // uninstrumented run. Inherited by every descended and cloned
+  // context through the prototype chain, so one run has one record.
+  prov?: any
+
   // errlist: Omit<NilVal[], "push">  // Nil error log of current unify.
   err: any[]
   explain: any[] | null
@@ -71,6 +115,29 @@ class AontuContext {
   _pathTrie: Map<number, Map<string, { idx: number, path: string[] }>>
   _pathidxNext: { n: number }
 
+  // Current `unite` recursion depth, checked against the depth budget
+  // (ts/src/unify.ts). Held in a shared mutable box, like _pathidxNext,
+  // because clone() uses Object.create: the box is inherited by
+  // reference, so a nested clone's increments are visible to the frame
+  // that will decrement them. The Go port keeps the same counter
+  // directly on its Ctx pointer (go/unify.go, maxUniteDepth).
+  _depth: { n: number }
+
+  // The evaluation budgets (G5 trust profile, docs/trust.md): integer
+  // counts of engine events, never wall-clock. Always present, defaults
+  // from the shared spec-visible constants (test/spec/budget.tsv), so
+  // the hot-path reads in unify.ts are plain property loads. Inherited
+  // by clone() through the prototype chain. `revisits` is NOT profile
+  // surface (the Go port has no revisit counter to configure — see
+  // TrustBudget in type.ts); it is carried here so unify.ts reads one
+  // budget object, at its fixed spec constant.
+  budget: { passes: number, revisits: number, depth: number }
+
+  // The include manifest sink (G5, docs/trust.md): every include the
+  // resolver reads is recorded here as { path, capability }, and
+  // Aontu.parse() sorts and dedups it onto the result's `deps`.
+  manifest: { path: string, capability: string }[]
+
   // Trial mode: set by DisjunctVal.unify while each member is tried
   // against the peer. When true, makeNilErr returns the shared
   // TRIAL_NIL sentinel instead of allocating a fresh NilVal, and
@@ -94,6 +161,7 @@ class AontuContext {
     this.src = cfg.src
 
     this.collect = cfg.collect ?? null != cfg.err
+    this.prov = cfg.prov
 
     this.err = cfg.err ?? []
     this.explain = Array.isArray(cfg.explain) ? cfg.explain : null
@@ -116,10 +184,23 @@ class AontuContext {
     this._pathmap = new Map()
     this._pathTrie = new Map()
     this._pathidxNext = { n: 1 }  // 0 reserved for the root path
+    this._depth = { n: 0 }
     this._pathidx = 0
 
+    this.manifest = []
+
     this.opts = DEFAULT_OPTS()
     this.addopts(cfg.opts)
+
+    // Budget defaults are the shared spec-visible constants
+    // (test/spec/budget.tsv pins the boundaries in both ports); the
+    // trust profile may lower or raise them, deterministically.
+    const budget = (this.opts as any).trust?.budget ?? {}
+    this.budget = {
+      passes: budget.passes ?? 9,
+      revisits: 999,
+      depth: budget.depth ?? 1000,
+    }
   }
 
 

package/src/diff.ts

@@ -0,0 +1,196 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// PATH-ADDRESSED DIFF (G7 phase 6,
+// docs/capability-review/g7-machine-access.md): what changed, at which
+// paths, between two documents — the dyff-style answer, which
+// deterministic canon makes possible without phantom noise. Two
+// documents that mean the same thing canon the same way, so a diff of
+// canons reports semantic change and not reformatting.
+//
+// The text compared is the HASH FORM (G6's `hcanon`), not the plain
+// canon, for the reason G6 gives: canon drops closedness and the
+// type/hide marks, so a canon diff calls `close({a:1})` and `{a:1}`
+// identical. A false "changed" costs a needless read; a false
+// "unchanged" is a change nobody reviewed, which is the one direction
+// that must not happen.
+//
+// WHETHER a change is BREAKING is a different question, and it belongs
+// to G3: `subsume` and `breaking` answer it with the lattice's own
+// rules. This verb answers "what moved", which is what a reviewer
+// reads first and what an agent needs before it can ask the other
+// question at all.
+
+import { Aontu } from './aontu'
+import type { TrustOptions } from './type'
+import { anchorAt } from './vet'
+import type { VetFinding } from './vet'
+import { cmpCodePoint } from './keyorder'
+import { hcanon } from './hcanon'
+import { evalFailure } from './query'
+
+
+export type DiffKind = 'added' | 'removed' | 'changed'
+
+export type DiffChange = {
+  kind: DiffKind
+  // The canon on each side, absent where there is no value.
+  left?: string
+  path: string
+  right?: string
+}
+
+export type DiffReport = {
+  changes: DiffChange[]
+  findings: VetFinding[]
+  ok: boolean
+  // True when nothing moved: the two documents mean the same thing.
+  same: boolean
+}
+
+export type DiffOptions = {
+  leftPath?: string
+  rightPath?: string
+  // Compare at this path of both documents, rather than at the root.
+  at?: string
+
+  // The trust profile this run evaluates under (G5, docs/trust.md).
+  // The source arrives from a caller, so the caller must be able to
+  // say what it may reach: without this the include chain is the
+  // default one, and `@"x.js"` is arbitrary code execution in the
+  // evaluating process. A server passes `{include:'none'}`.
+  trust?: TrustOptions
+}
+
+
+function pathText(parts: string[]): string {
+  return '$' + (0 < parts.length ? '.' + parts.join('.') : '')
+}
+
+
+// Both sides of one node — never both absent: keys come from the
+// union of the two bags, and list indices run to the longer side, so
+// every walk has at least one value. Bags of the SAME kind recurse,
+// which is what makes the report path-addressed rather than one line
+// saying the whole document changed; everything else compares text.
+function walk(
+  left: any, right: any, parts: string[], out: DiffChange[]): void {
+  if (null == left) {
+    out.push({ kind: 'added', path: pathText(parts), right: hcanon(right) })
+    return
+  }
+  if (null == right) {
+    out.push({ kind: 'removed', left: hcanon(left), path: pathText(parts) })
+    return
+  }
+
+  const bothMaps = true === left.isMap && true === right.isMap
+  const bothLists = true === left.isList && true === right.isList
+  if (bothMaps || bothLists) {
+    // The bag's OWN attributes, at pseudo-keys under it: a recursing
+    // bag never compares its own text, so what the children do not
+    // carry has to be compared here. The spread is part of what a bag
+    // MEANS; so are closedness and the marks, which is exactly why the
+    // hash form spells them (G6).
+    const lc = null == left.spread.cj ? undefined : hcanon(left.spread.cj)
+    const rc = null == right.spread.cj ? undefined : hcanon(right.spread.cj)
+    if (lc !== rc) {
+      out.push({
+        kind: null == lc ? 'added' : null == rc ? 'removed' : 'changed',
+        ...(null == lc ? {} : { left: lc }),
+        path: pathText(parts.concat('&')),
+        ...(null == rc ? {} : { right: rc }),
+      })
+    }
+    flag(left.closed, right.closed, parts, 'closed', out)
+    flag(left.mark?.type, right.mark?.type, parts, 'type', out)
+    flag(left.mark?.hide, right.mark?.hide, parts, 'hide', out)
+
+    const keys = bothMaps
+      ? [...new Set([
+        ...Object.keys(left.peg), ...Object.keys(right.peg),
+      ])].sort(cmpCodePoint)
+      : [...new Set([
+        ...Object.keys(left.peg), ...Object.keys(right.peg),
+      ])].sort((a, b) => Number(a) - Number(b))
+    for (const k of keys) {
+      walk(left.peg[k], right.peg[k], parts.concat(k), out)
+    }
+    return
+  }
+
+  const lh = hcanon(left)
+  const rh = hcanon(right)
+  if (lh !== rh) {
+    out.push({ kind: 'changed', left: lh, path: pathText(parts), right: rh })
+  }
+}
+
+
+// One boolean attribute of a bag, as a pseudo-key: `$.a.&closed` says
+// the map at `$.a` was closed (or opened) without saying anything
+// about its keys.
+function flag(
+  left: any, right: any, parts: string[], name: string,
+  out: DiffChange[]): void {
+  const l = true === left
+  const r = true === right
+  if (l !== r) {
+    out.push({
+      kind: 'changed',
+      left: String(l),
+      path: pathText(parts.concat('&' + name)),
+      right: String(r),
+    })
+  }
+}
+
+
+function evalSide(
+  aontu: Aontu, src: string, path: string | undefined, at: string | undefined,
+): { node?: any, finding?: VetFinding } {
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == path ? undefined : { path }
+  const root: any = aontu.unify(src, parseOpts, ctx)
+  if (0 < ctx.err.length) {
+    // The query surface's own fold: a document that does not stand up
+    // has no meaning to compare, and the engine's diagnosis is the
+    // report.
+    return { finding: evalFailure(ctx) }
+  }
+  const node: any = null == at ? root : anchorAt(root, at)
+  if (null == node) {
+    return {
+      finding: {
+        code: 'no_path',
+        class: 'reference',
+        severity: 'error',
+        path: at as string,
+        message: `The path ${at} names nothing in this document.`,
+        sites: [],
+      },
+    }
+  }
+  return { node }
+}
+
+
+// Diff two documents. Each is evaluated on its own — a document that
+// does not stand up has no meaning to compare, and the report says so
+// rather than diffing a wreck.
+export function diff(
+  leftSrc: string, rightSrc: string, opts?: DiffOptions): DiffReport {
+  const options = opts ?? {}
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+
+  const l = evalSide(aontu, leftSrc, options.leftPath, options.at)
+  const r = evalSide(aontu, rightSrc, options.rightPath, options.at)
+  const findings = [l.finding, r.finding].filter(Boolean) as VetFinding[]
+  if (0 < findings.length) {
+    return { changes: [], findings, ok: false, same: false }
+  }
+
+  const changes: DiffChange[] = []
+  walk(l.node, r.node, [], changes)
+  return { changes, findings: [], ok: true, same: 0 === changes.length }
+}

package/src/err.ts

@@ -15,6 +15,39 @@ import { hints } from './hints'
 const { errmsg, strinject } = util
 
 
+// COLOUR IS A DECISION ABOUT THE DESTINATION, not about the message.
+// Every error frame hardcoded the ANSI escapes, so a piped report and
+// a `--jsonl` answer carried terminal control codes into whatever read
+// them -- a log file, a CI annotation, an agent's parser (the review's
+// finding F).
+//
+// NO_COLOR (no-color.org: set, to anything, means no colour) turns them
+// off everywhere, library callers included. The CLI additionally turns
+// them off when its stderr is not a terminal, through setColor: a
+// library cannot see the destination, and a caller who has one is the
+// only one who can say.
+let COLOR: boolean | undefined
+
+function setColor(on: boolean | undefined): void {
+  COLOR = on
+}
+
+function colorActive(): boolean {
+  if (null != COLOR) {
+    return COLOR
+  }
+  // `globalThis` always exists; `process` need not (this library runs
+  // in a browser too), so the optional chain starts at the part that
+  // can actually be missing -- and stays a CHAIN rather than becoming
+  // an `if`, because the browser arm is unreachable from any test this
+  // suite can run and ADR-002 does not accept an arm nothing takes.
+  // Set-but-EMPTY is the documented exception and does not disable
+  // colour (no-color.org).
+  const no = (globalThis as any).process?.env?.NO_COLOR
+  return null == no || '' === no
+}
+
+
 function getHint(why: any, details?: Record<string, any>): string | undefined {
   if (hints[why]) {
     let txt = hints[why]
@@ -61,10 +94,19 @@ function descErr<NILS extends NilVal | NilVal[]>(
       let v1: any = err.primary
       let v2: any = err.secondary
 
-      let v1src = resolveSrc(v1, errctx, 'primary')
-      let v2src = resolveSrc(v2, errctx, 'secondary')
+      let v1src = resolveSrc(v1, errctx)
+      let v2src = resolveSrc(v2, errctx)
 
-      let path = ['$', ...err.path].filter((p: any) => null != p && '' != p)
+      // STRICT `!==` against the empty string. The loose `!=` here dropped
+      // the list index 0, because `'' != 0` is FALSE in JavaScript ('' and
+      // 0 are both coerced to 0): `a:[1]&[2]` reported its conflict at
+      // `$.a` while `a:[1,5]&[1,6]` reported `$.a.1`, so the one index a
+      // reader is most likely to meet was the one silently erased, and a
+      // nested `a:[[1]]&[[2]]` lost both segments (issue #37). Numeric
+      // segments arrive here as numbers, so only `===`/`!==` compares them
+      // for what they are. `null != p` stays loose on purpose -- it is the
+      // idiomatic null-and-undefined test.
+      let path = ['$', ...err.path].filter((p: any) => null != p && '' !== p)
 
       // '$' is neither null nor '', so the filter always leaves it.
       let valpath = path.join('.')
@@ -74,7 +116,7 @@ function descErr<NILS extends NilVal | NilVal[]>(
 
       err.msg = [
         errmsg({
-          color: { active: true },
+          color: { active: colorActive() },
           name: 'aontu',
           code: err.why,
           txts: {
@@ -90,7 +132,7 @@ function descErr<NILS extends NilVal | NilVal[]>(
 
         (null != v1 && errmsg({
           // TODO: color should come from jsonic config
-          color: { active: true, line: '\x1b[34m' },
+          color: { active: colorActive(), line: '\x1b[34m' },
           txts: {
             msg: 'Cannot ' + attempt + ' value: ' + v1.canon +
               (null == v2 ? '' : ' with value: ' + v2.canon), // + ' #' + err.id,
@@ -106,7 +148,7 @@ function descErr<NILS extends NilVal | NilVal[]>(
 
         (null != v2 && errmsg({
           // TODO: color should come from jsonic config
-          color: { active: true, line: '\x1b[34m' },
+          color: { active: colorActive(), line: '\x1b[34m' },
           txts: {
             msg: 'Cannot ' + attempt + ' value: ' + v2.canon +
               ' with value: ' + v1.canon, // + ' #' + err.id,
@@ -144,7 +186,7 @@ function resolveFile(url: string | undefined) {
 }
 
 
-function resolveSrc(v: Val, errctx: ErrContext | undefined, position: string) {
+function resolveSrc(v: Val, errctx: ErrContext | undefined) {
   let src: string | undefined = undefined
   const url = v?.site.url
 
@@ -201,7 +243,7 @@ class AontuError extends Error {
   }
 
   errs: () => NilVal[]
-} /* node:coverage ignore next 9 */
+} /* node:coverage ignore next 11 */
 
 
 export {
@@ -209,4 +251,6 @@ export {
   makeNilErr,
   descErr,
   AontuError,
+  setColor,
+  colorActive,
 }

package/src/graph.ts

@@ -0,0 +1,135 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE DERIVED STRUCTURES (G4 phase 3,
+// docs/capability-review/g4-identity-relations.md): an evaluated
+// document has, besides its value, a GRAPH — an entity index (id → the
+// tree paths that hold it) and an edge set (the checked links, each
+// from one entity to one address).
+//
+// G4's deliverable is that these exist and are DETERMINISTIC. What is
+// built on them — impact analysis ("what reaches svc/auth?"),
+// reachability, context-window-sized entity slices — is a traversal,
+// and its exposure as verbs and projections belongs to G7. Relation
+// properties (acyclicity, inverse consistency) are G4 phase 5's, and
+// consume exactly this edge set.
+
+import type { Val } from './type'
+
+import { cmpCodePoint } from './keyorder'
+
+
+export type EntityEntry = {
+  // The id, as `id(name)` spelled it.
+  id: string
+  // Every tree path that holds this entity, in code-point order. More
+  // than one is the normal case: the merge puts the entity's value at
+  // every position that declared it.
+  paths: string[]
+}
+
+export type Edge = {
+  // The entity the link is INSIDE — the nearest identified ancestor,
+  // or '' for a link outside every entity. This is the
+  // entity/component distinction: a node without an id is a component
+  // of its nearest identified ancestor.
+  from: string
+  // The RELATION: the nearest map key on the way down from the entity,
+  // so a link inside a list (`dependsOn: [&: refer(), svc/auth]`) is an
+  // edge under `dependsOn` rather than under `0`.
+  key: string
+  // The address, as the link spells it.
+  to: string
+  // Where the link is, as a `$.dotted.path`, so a report can point at
+  // it.
+  at: string
+}
+
+export type Graph = {
+  entities: EntityEntry[]
+  edges: Edge[]
+}
+
+
+const formatPath = (path: string[]): string =>
+  0 === path.length ? '$' : '$.' + path.join('.')
+
+
+// The nearest map key on the path below an entity: list indices are
+// positions within a relation, not relations of their own. Digits-only
+// segments are the indices, which is exactly how the rest of the engine
+// spells them.
+const relationKey = (tail: string[]): string => {
+  for (let i = tail.length - 1; 0 <= i; i--) {
+    if (!/^[0-9]+$/.test(tail[i])) {
+      return tail[i]
+    }
+  }
+  return ''
+}
+
+
+// The graph of an evaluated tree. Walks POSITIONS, not values: two
+// positions of one entity share a value object after the merge, so a
+// walk guarded by object identity would find the entity once and miss
+// every other place it is declared. The guard is therefore the
+// ancestor chain — which is what a cycle actually is.
+export function graphOf(root: Val): Graph {
+  const byId = new Map<string, string[]>()
+  const edges: Edge[] = []
+
+  const visit = (
+    node: any, path: string[], entity: string, tail: string[],
+    ancestors: Set<any>
+  ): void => {
+    if (null == node || true !== node.isVal || ancestors.has(node)) {
+      return
+    }
+
+    let inside = entity
+    let below = tail
+    const name = node.entity
+    if (null != name) {
+      let paths = byId.get(name)
+      if (undefined === paths) {
+        paths = []
+        byId.set(name, paths)
+      }
+      paths.push(formatPath(path))
+      // A nested entity is not a component of the one above it: the
+      // key path restarts at the identified node.
+      inside = name
+      below = []
+    }
+
+    const link = node.link
+    if (null != link) {
+      edges.push({
+        from: inside,
+        key: relationKey(below),
+        to: link,
+        at: formatPath(path),
+      })
+    }
+
+    if ((true === node.isMap || true === node.isList) && null != node.peg) {
+      ancestors.add(node)
+      for (const k of Object.keys(node.peg)) {
+        visit(node.peg[k], [...path, k], inside, [...below, k], ancestors)
+      }
+      ancestors.delete(node)
+    }
+  }
+
+  visit(root, [], '', [], new Set())
+
+  // DETERMINISTIC by construction, not by luck: ids in code-point
+  // order, each id's paths in code-point order, edges by the position
+  // they are written at (which is unique — one link, one place).
+  const entities: EntityEntry[] = [...byId.keys()]
+    .sort(cmpCodePoint)
+    .map((id) => ({ id, paths: (byId.get(id) as string[]).sort(cmpCodePoint) }))
+
+  edges.sort((a, b) => cmpCodePoint(a.at, b.at))
+
+  return { entities, edges }
+}