aontu 0.52.1 → 0.53.0

package/skill/grammar-card.md

@@ -0,0 +1,57 @@
+# Aontu grammar card
+
+Everything the language spells, on one page. The published machine
+grammar is [`grammar/aontu.gbnf`](../grammar/aontu.gbnf) (and
+`aontu.lark`); this is its human twin.
+
+## Values
+
+| Write | Means |
+|-------|-------|
+| `{"a":1}`, `a: 1` | a map; keys may be bare or quoted |
+| `[1,2]` | a list |
+| `"s"`, `1`, `1.5`, `true`, `null` | scalars, as JSON |
+| `0d9007199254740993` | an EXACT number, at any magnitude |
+| `string integer number float boolean null` | kinds: any value of that kind |
+| `top` | anything at all; `nil` is the failure |
+
+## Combining
+
+| Write | Means |
+|-------|-------|
+| `a & b` | both must hold — the meet |
+| `a \| b` | either may hold — the join |
+| `*1 \| integer` | either, with `1` the DEFAULT a generation picks |
+| | the branch keeps its kind: a later `1.5` is refused, not admitted |
+| `x: 1` twice | the two meet; `1 & 2` is an error, `1 & integer` is `1` |
+| `$.a.b` | the value at that path of this document |
+| `1 + 2` | arithmetic on concrete numbers |
+
+## Maps that say more
+
+| Write | Means |
+|-------|-------|
+| `{&: {k: integer}}` | a TEMPLATE every key must satisfy |
+| `close({a:1})` | no key beyond those named |
+| `{a?: 1}` | optional: dropped if unresolved |
+| `hide(x)` | evaluated, then dropped from the output |
+| `type(x)` | a definition, not a value: it generates nothing |
+| `deprecate(x, {msg:"…"})` | still works, and says so |
+| `id(svc/auth) & x` | this value IS that entity; every node with the name unifies |
+| `refer(t) & "svc/auth"` | a checked LINK: the name must resolve, and `t` flows into it |
+
+## Constraints
+
+`min(n) max(n) above(n) below(n)` bound a number;
+`length(n)` and `unique()` bound a list or string;
+`re("^…$")` matches a string; `neq(v)` refuses one value;
+`must(cond, "why")` is the escape hatch.
+
+Bounds compose: `integer & min(1) & max(10)` is a range, and two
+ranges meet to their overlap.
+
+## Files
+
+`@"other.aon"` includes another document — it unifies in, it does not
+concatenate. (A constrained decoder is not given this: generated
+documents describe values, they do not load files.)

package/src/agentsmd.ts

@@ -0,0 +1,135 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE AGENTS.md STANZA (G7 phase 6,
+// docs/capability-review/g7-machine-access.md): generated FROM the
+// definition, so the prose entrypoint cannot drift from the formal
+// source it points at.
+//
+// A hand-written "here is where the config lives" paragraph is stale
+// the first time a key is renamed. This one is derived: the root keys
+// come from the document, the pin comes from G6's canon-hash, and the
+// commands are spelled with paths that exist. Re-running the verb
+// after an edit produces the stanza that edit implies.
+
+import { Aontu } from './aontu'
+import type { TrustOptions } from './type'
+import { canonHash } from './hcanon'
+import { get } from './query'
+import { evalFailure } from './query'
+import type { VetFinding } from './vet'
+import { cmpCodePoint } from './keyorder'
+
+
+// The markers an update rewrites between. A stanza outside them is
+// prose someone wrote, and is left alone.
+export const AGENTSMD_BEGIN = '<!-- aontu:begin -->'
+export const AGENTSMD_END = '<!-- aontu:end -->'
+
+
+export type AgentsMdReport = {
+  findings: VetFinding[]
+  ok: boolean
+  stanza: string
+}
+
+export type AgentsMdOptions = {
+  // The name the stanza should call the document. The engine never
+  // reads a file; the CLI passes what the author typed.
+  name?: string
+  path?: string
+  // The include capability this document evaluates under
+  // (G5, docs/trust.md); vet's precedent.
+  trust?: TrustOptions
+}
+
+
+// The stanza for one document.
+export function agentsMd(
+  src: string, opts?: AgentsMdOptions): AgentsMdReport {
+  const options = opts ?? {}
+  const name = options.name ?? 'the definition'
+
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == options.path ? undefined : { path: options.path }
+  const v: any = aontu.unify(src, parseOpts, ctx)
+  if (0 < ctx.err.length) {
+    return { findings: [evalFailure(ctx)], ok: false, stanza: '' }
+  }
+
+  const keys = true === v.isMap ? Object.keys(v.peg).sort(cmpCodePoint) : []
+  const shape = get(src, '$', { view: 'types', depth: 2, path: options.path })
+
+  // A REAL path, so the example command works as written: the first
+  // root key when there is one, the root itself when there is not.
+  const example = 0 < keys.length ? '$.' + keys[0] : '$'
+
+  const lines = [
+    AGENTSMD_BEGIN,
+    '## Ground truth: `' + name + '`',
+    '',
+    'The values below are DERIVED from `' + name + '`, an Aontu',
+    'definition. Do not restate them here — read them from the source,',
+    'which is the only copy that cannot go stale.',
+    '',
+    '- Pin: `' + canonHash(v) + '`',
+    '  (the canon-hash: it survives reformatting and moves on any',
+    '  change of meaning — `aontu hash ' + name + '` re-derives it)',
+    '- Top-level keys: ' +
+    (0 === keys.length ? '_none_' : keys.map((k) => '`' + k + '`').join(', ')),
+    '- Shape: `' + shape.out + '`',
+    '',
+    'How to work with it:',
+    '',
+    '```',
+    '# what does it say at a path?',
+    'aontu get ' + example + ' ' + name,
+    '',
+    '# why does that value hold?',
+    'aontu why ' + example + ' ' + name,
+    '',
+    '# does my document satisfy it?',
+    'aontu vet ' + name + ' mine.aon',
+    '',
+    '# change it without editing it',
+    'aontu set ' + example + '=<value> --entry ' + name +
+    ' --overlay overlay.aon',
+    '```',
+    '',
+    'Regenerate this section with `aontu agentsmd ' + name + '`.',
+    AGENTSMD_END,
+  ]
+
+  return { findings: [], ok: true, stanza: lines.join('\n') + '\n' }
+}
+
+
+// Splice the stanza into an existing document: replace what stands
+// between the markers, or append when there is nothing to replace. A
+// document is otherwise LEFT ALONE — the rest of an AGENTS.md is
+// someone's prose, and a generator that rewrote it would be a
+// generator nobody dared run twice.
+export function agentsMdSplice(existing: string, stanza: string): string {
+  const from = existing.indexOf(AGENTSMD_BEGIN)
+  const to = existing.indexOf(AGENTSMD_END)
+  if (from < 0 || to < from) {
+    const head = '' === existing || existing.endsWith('\n')
+      ? existing : existing + '\n'
+    return head + ('' === existing ? '' : '\n') + stanza
+  }
+  // Skip the end marker's line terminator, whatever it is, and only if
+  // it is there. The full note is on the Go twin (go/agentsmd.go): `+1`
+  // assumed one byte and got the CR of a CRLF document, leaving the LF
+  // to become a blank line on every regeneration -- and past the end of
+  // a document whose marker is its last content, where Go panicked and
+  // this side quietly did not.
+  let end = to + AGENTSMD_END.length
+  if ('\r' === existing[end]) {
+    end++
+  }
+  if ('\n' === existing[end]) {
+    end++
+  }
+  return existing.slice(0, from) + stanza + existing.slice(end)
+}

package/src/aontu.ts

@@ -12,7 +12,18 @@ import { MapVal } from './val/MapVal'
 import { Decimal } from './val/Decimal'
 import { exactJSON } from './exactjson'
 import { formatExplain } from './utility'
-import { makeNilErr, descErr, AontuError } from './err'
+import { makeNilErr, descErr, AontuError, setColor, colorActive } from './err'
+import { vet } from './vet'
+import { sarifReport } from './report-sarif'
+import { subsume } from './subsume'
+import { trimCheck } from './trim'
+import { hcanon, canonHash } from './hcanon'
+import { get, why } from './query'
+import { patch } from './patch'
+import { diff } from './diff'
+import { agentsMd } from './agentsmd'
+import { graphOf } from './graph'
+import { relationCheck } from './relation'
 
 
 // VERSION is the Aontu npm package version, and mirrors
@@ -22,7 +33,18 @@ import { makeNilErr, descErr, AontuError } from './err'
 // 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.52.1'
+const VERSION = '0.53.0'
+
+
+// A module file's VALUE, as far as it goes. COLLECTED, not raised: a
+// module file that does not stand up has no `mod.main` to read, and
+// the default entry name is the answer -- the resolution itself fails
+// later, on the file that is not there, rather than here on a metadata
+// read. That is what a collecting context does, so there is nothing to
+// catch: it answers what it could generate and records the rest.
+function genQuiet(val: any, aontu: Aontu): any {
+  return val.gen(aontu.ctx({ collect: true }))
+}
 
 
 class Aontu {
@@ -32,6 +54,42 @@ class Aontu {
 
   constructor(popts?: AontuOptions) {
     this.opts = popts ?? {}
+
+    // THE MODULE EVALUATOR (G6 phase 2, ts/src/mod.ts). Resolving a
+    // module import needs two answers that only evaluation can give:
+    // what a module file SAYS (its `mod.main`), and what a module
+    // MEANS (its canon-hash, for the integrity check). Injected here
+    // rather than imported there, because the resolver runs inside a
+    // parse that this class started, and the file it runs in cannot
+    // import this one without closing a cycle around the language.
+    //
+    // COLLECTED, not raised: a module that leans on consumer context
+    // (a `$.x` its importer supplies) does not stand up alone, and its
+    // hash is still the hash of what it says — that residue is part of
+    // the hashed meaning, which is why `hcanon` keeps it in textual
+    // form (docs/capability-review/g6-distribution.md).
+    ;(this.opts as any).mod = {
+      ...((this.opts as any).mod ?? {}),
+      eval: (this.opts as any).mod?.eval ?? ((src: string, path: string) => {
+        // One deeper: a module verified from inside a module
+        // verification is one more level of nesting, and the resolver
+        // refuses past its bound (MODULE_MAX_DEPTH in ts/src/mod.ts).
+        const inner = new Aontu({
+          ...this.opts,
+          mod: {
+            // Never absent: the assignment this closure is part of has
+            // already run by the time it is called.
+            ...(this.opts as any).mod,
+            eval: undefined,
+            depth: (((this.opts as any).mod?.depth ?? 0) as number) + 1,
+          },
+        } as any)
+        const ctx = inner.ctx({ collect: true })
+        const val = inner.unify(src, { path }, ctx)
+        return { gen: genQuiet(val, inner), hash: canonHash(val) }
+      }),
+    }
+
     this.lang = new Lang(this.opts)
   }
 
@@ -40,6 +98,11 @@ class Aontu {
   ctx(cfg?: AontuContextConfig): AontuContext {
     cfg = cfg ?? {}
     cfg.fs = cfg.fs ?? this.opts.fs
+    // 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).
+    cfg.opts = cfg.opts ?? {}
+    ; (cfg.opts as any).trust = (cfg.opts as any).trust ?? this.opts.trust
     const ac = new AontuContext(cfg)
     return ac
   }
@@ -85,7 +148,11 @@ class Aontu {
 
     if (0 === errs.length) {
       out = runparse(src, this.lang, ac)
-      out.deps = ac.deps
+      // The include MANIFEST (G5, docs/trust.md): the resolved include
+      // closure as `{ path, capability }`, sorted and deduplicated so
+      // it is deterministic — the "file set" of hermeticity clause 1
+      // made observable. Content hashing and pinning stay with G6.
+      out.deps = manifestOf(ac.manifest)
       ac.root = out
     }
 
@@ -130,6 +197,11 @@ class Aontu {
       out = uni.res
 
       out.deps = pval.deps
+      // THE DERIVED STRUCTURES (G4 phase 3): the entity index and the
+      // edge set, computed once from the unified tree. Cheap on a
+      // document with no identity — one guarded walk — and the thing
+      // impact analysis and the relation checks are traversals over.
+      out.graph = graphOf(out)
       out.err = errs
       ac.root = out
     }
@@ -266,12 +338,38 @@ function findConflictMarker(src: string): {
 }
 
 
+// Sort and deduplicate the raw manifest sink into the deterministic
+// include closure: by path then capability, code-point order, one entry
+// per (path, capability) pair.
+function manifestOf(
+  sink: { path: string, capability: string }[]
+): { path: string, capability: string }[] {
+  const seen = new Set<string>()
+  const out: { path: string, capability: string }[] = []
+  for (const dep of sink) {
+    const key = dep.path + ' ' + dep.capability
+    if (!seen.has(key)) {
+      seen.add(key)
+      out.push({ path: dep.path, capability: dep.capability })
+    }
+  }
+  // No equal case: entries were deduplicated on exactly this key.
+  out.sort((a, b) => {
+    const ka = a.path + ' ' + a.capability
+    const kb = b.path + ' ' + b.capability
+    return ka < kb ? -1 : 1
+  })
+  return out
+}
+
+
 // Perform parse of source code (minor customizations over Lang.parse).
 function runparse(src: string, lang: Lang, ctx: AontuContext): Val {
   const popts = {
     deps: ctx.deps,
     fs: ctx.fs,
-    path: ctx.opts.path
+    path: ctx.opts.path,
+    manifest: ctx.manifest,
   }
   let val
 
@@ -301,6 +399,8 @@ export {
   AontuOptions,
   AontuContext,
   AontuError,
+  setColor,
+  colorActive,
 
   Val,
   Lang,
@@ -314,6 +414,37 @@ export {
   // `biginteger` generates as the language's own `bigint`).
   exactJSON,
   Decimal,
+
+  // G2 phase 2 -- the validation verb. The engine only: the CLI verb
+  // and the text/JSON renderers are phase 3, the Go port phase 4.
+  // `sarifReport` (phase 5) is library API so an embedder can emit the
+  // interchange form without shelling out.
+  vet,
+  sarifReport,
+
+  // G3 -- subsumption as a first-class query: does the general value
+  // admit every instance the specific value admits? Three-valued, with
+  // G2-shaped findings (class `compat`).
+  subsume,
+  trimCheck,
+
+  // G6 -- the hash form and the canon-hash pin. `hcanon` is the
+  // unify-level canon plus the close()/type()/hide() wrappers that
+  // close its semantic gaps; `canonHash` is
+  // "aon1-" + base64url(SHA-256(UTF-8(hcanon(v)))).
+  hcanon,
+  canonHash,
+
+  // G7 -- the machine-facing query surface: select one node by path
+  // and render it, plainly (json/canon) or as a lattice ABSTRACTION
+  // (types/depth/keys) that subsumes the truth it summarises.
+  get,
+  why,
+  patch,
+  diff,
+  agentsMd,
+  graphOf,
+  relationCheck,
 }