aontu 0.62.0 → 0.63.0

package/grammar/aontu.abnf

@@ -80,18 +80,20 @@ func      = name %s"(" ws [ value *( ws %s"," ws value ) ws ] %s")"
 
 ; ORDER MATTERS where one name is a prefix of another: `refer` is
 ; listed before `re`, and `rem` before `re` as well.
-name      = %s"above" / %s"acyclic" / %s"add" / %s"below" / %s"close"
-          / %s"copy" / %s"deprecate" / %s"div"
+name      = %s"abnf" / %s"above" / %s"acyclic" / %s"add" / %s"below" / %s"close"
+          / %s"copyfiles" / %s"copy" / %s"deprecate" / %s"div"
           / %s"each" / %s"emit" / %s"esc" / %s"filter" / %s"greatest"
           / %s"hide"
           / %s"inverse" / %s"join" / %s"key" / %s"least"
-          / %s"length" / %s"list" / %s"lower" / %s"map" / %s"match"
-          / %s"max" / %s"min" / %s"mod" / %s"move"
+          / %s"length" / %s"listitems" / %s"list" / %s"lower" / %s"map" / %s"match"
+          / %s"maybe" / %s"max" / %s"min" / %s"mod" / %s"move"
           / %s"mul" / %s"must"
           / %s"neq"
-          / %s"open" / %s"pack" / %s"path" / %s"pick" / %s"pref"
-          / %s"refer" / %s"rel" / %s"rem" / %s"rep" / %s"re" / %s"split"
+          / %s"open" / %s"pack" / %s"parse" / %s"path" / %s"pick" / %s"pref"
+          / %s"refer" / %s"rel" / %s"rem" / %s"rep" / %s"re" / %s"sort" / %s"split"
           / %s"super"
+          / %s"content" / %s"file" / %s"folder" / %s"fragment" / %s"inject"
+          / %s"line" / %s"nom" / %s"project" / %s"slot" / %s"translate"
           / %s"sub" / %s"sum"
           / %s"type"
           / %s"unique" / %s"upper" / %s"usc"

package/grammar/aontu.gbnf

@@ -81,15 +81,15 @@ element ::= spread | value
 func ::= name "(" ws ( value ( ws "," ws value )* ws )? ")"
 
 name ::=
-    "above" | "acyclic" | "add" | "below" | "close" | "copy" | "deprecate" | "div"
+    "content" | "file" | "folder" | "fragment" | "inject" | "line" | "nom" | "project" | "slot" | "translate" | "abnf" | "above" | "acyclic" | "add" | "below" | "close" | "copyfiles" | "copy" | "deprecate" | "div"
   | "each" | "emit" | "esc" | "filter" | "greatest"
   | "hide"
   | "inverse" | "join" | "key" | "least"
-  | "length" | "list" | "lower" | "map" | "match" | "max" | "min" | "mod" | "move"
+  | "length" | "listitems" | "list" | "lower" | "map" | "match" | "maybe" | "max" | "min" | "mod" | "move"
   | "mul" | "must"
   | "neq"
-  | "open" | "pack" | "path" | "pick" | "pref" | "refer" | "rel" | "rem" | "rep" | "re"
-  | "split" | "super"
+  | "open" | "pack" | "parse" | "path" | "pick" | "pref" | "refer" | "rel" | "rem" | "rep" | "re"
+  | "sort" | "split" | "super"
   | "sub" | "sum"
   | "type"
   | "unique" | "upper" | "usc"

package/grammar/aontu.lark

@@ -62,15 +62,15 @@ element: spread
 
 func: name "(" [value ("," value)*] ")"
 
-name: "above" | "acyclic" | "add" | "below" | "close" | "copy" | "deprecate" | "div"
+name: "content" | "file" | "folder" | "fragment" | "inject" | "line" | "nom" | "project" | "slot" | "translate" | "abnf" | "above" | "acyclic" | "add" | "below" | "close" | "copyfiles" | "copy" | "deprecate" | "div"
     | "each" | "emit" | "esc" | "filter" | "greatest"
     | "hide"
     | "inverse" | "join" | "key" | "least"
-    | "length" | "list" | "lower" | "map" | "match" | "max" | "min" | "mod" | "move"
+    | "length" | "listitems" | "list" | "lower" | "map" | "match" | "maybe" | "max" | "min" | "mod" | "move"
     | "mul" | "must"
     | "neq"
-    | "open" | "pack" | "path" | "pick" | "pref" | "refer" | "rel" | "rem" | "rep" | "re"
-    | "split" | "super"
+    | "open" | "pack" | "parse" | "path" | "pick" | "pref" | "refer" | "rel" | "rem" | "rep" | "re"
+    | "sort" | "split" | "super"
     | "sub" | "sum"
     | "type"
     | "unique" | "upper" | "usc"

package/grammar/aontu.tmLanguage.json

@@ -111,7 +111,7 @@
 
     "builtin": {
       "comment": "The engine's function registry. `func: name \"(\" ...` in aontu.lark — only these names can be called, so a call to anything else is deliberately left uncoloured rather than dressed up as valid. The prefix family is spelled longest-first (refer|rel|rem|re) to keep the intent legible; the trailing \\b already makes the order immaterial, since a short alternative that swallowed the stem fails the boundary and backtracks.",
-      "match": "\\b(above|acyclic|add|below|close|copy|deprecate|div|each|emit|esc|filter|greatest|hide|inverse|join|key|least|length|list|lower|map|match|max|min|mod|move|mul|must|neq|open|pack|path|pick|pref|refer|rel|rem|rep|re|split|sub|sum|super|type|unique|upper|usc)\\b(?=\\s*\\()",
+      "match": "\\b(abnf|above|acyclic|add|below|close|content|copyfiles|copy|deprecate|div|each|emit|esc|file|filter|folder|fragment|greatest|hide|inject|inverse|join|key|least|length|line|listitems|list|lower|map|match|maybe|max|min|mod|move|mul|must|neq|nom|open|pack|parse|path|pick|pref|project|refer|rel|rem|rep|re|slot|sort|split|sub|sum|super|translate|type|unique|upper|usc)\\b(?=\\s*\\()",
       "captures": {
         "1": { "name": "support.function.builtin.aontu" }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aontu",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "main": "dist/aontu.js",
   "type": "commonjs",
   "types": "dist/aontu.d.ts",
@@ -64,6 +64,8 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@tabnas/abnf": "0.4.13",
+    "@tabnas/bnf": "0.1.15",
     "@tabnas/debug": "0.3.2",
     "@tabnas/directive": "0.5.2",
     "@tabnas/expr": "0.5.5",
@@ -73,7 +75,7 @@
     "@tabnas/jsonc": "0.5.6",
     "@tabnas/jsonic": "0.6.2",
     "@tabnas/multisource": "0.5.2",
-    "@tabnas/parser": "0.8.7",
+    "@tabnas/parser": "0.9.7",
     "@tabnas/path": "0.3.2",
     "@tabnas/toml": "0.5.7",
     "@tabnas/yaml": "0.5.7"

package/src/agentsmd.ts

@@ -1,16 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// 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'
@@ -34,11 +24,6 @@ export type AgentsMdReport = {
 }
 
 export type AgentsMdOptions = {
-  // How deep the SHAPE line projects, default 2 (G11 phase 7). Two
-  // levels name the root keys and say `top` under them, which tells an
-  // agent what the document is ABOUT and nothing it can act on; a
-  // caller that wants the fields asks for them. The default is
-  // unchanged, because the stanza is spliced into a file people read.
   depth?: number
   // The name the stanza should call the document. The engine never
   // reads a file; the CLI passes what the author typed.
@@ -48,9 +33,6 @@ export type AgentsMdOptions = {
   // (G5, docs/trust.md); vet's precedent.
   trust?: TrustOptions
 
-  // Extensions additionally read as text (the CLI's `--text-ext`).
-  // Rides beside `trust` because it is the other half of what an
-  // include may read.
   textExt?: string[]
 }
 
@@ -70,12 +52,6 @@ export function agentsMd(
   }
 
   const keys = true === v.isMap ? Object.keys(v.peg).sort(cmpCodePoint) : []
-  // THE SHAPE IS A SECOND EVALUATION, and it runs under the same
-  // include options as the first. Taking `path` alone made it a
-  // narrower reader than the stanza around it: a document whose keys
-  // arrive through a `--text-ext` include listed those keys and then
-  // reported an EMPTY shape, because the read the shape came from
-  // refused the include the read above it had just honoured.
   const shape = get(src, '$', {
     view: 'types', depth: options.depth ?? 2,
     path: options.path, ...includeOpts(options),
@@ -128,11 +104,6 @@ export function agentsMd(
 }
 
 
-// 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)
@@ -141,12 +112,6 @@ export function agentsMdSplice(existing: string, stanza: string): string {
       ? 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++

package/src/alias.ts

@@ -1,44 +1,5 @@
 /* Copyright (c) 2021-2026 Richard Rodger, MIT License */
 
-// ALIAS EXPANSION FOR CANON. An alias is a name for a value, and
-// nothing more (docs/design/ALIASES.0.md §4): the declaration is
-// erased from generation, canon and the hash, and a reference resolves
-// to the value in place. One place a reference is NOT resolved in
-// place is a spread template -- `[&: %unit]`, `{&: {a: %u}}` -- because
-// a template applies to children that have not arrived, so it stands
-// in the settled tree as the reference it was written as. Canon has
-// erased the declaration, so the name alone would not reparse, and the
-// hash of `t: {&: %u}` would differ from the hash of `t: {&: integer}`,
-// which is the same document.
-//
-// This walk runs ONCE, after the last unification pass, and attaches
-// to every standing alias reference the value it names, which its
-// canon then renders instead of the name. The tree is not changed:
-// the reference still stands, still resolves at each destination, and
-// unification never reads the expansion.
-//
-// What a reference expands to. The ref-spread SNAPSHOT where one was
-// taken (MapVal.snapshotRefSpread: a path-dependent template captured
-// before its key()/path() resolved at the declaration), else the
-// declaration's settled value at the root. The snapshot is the
-// template the destinations actually saw; the settled value of
-// `%row = {name: key()}` is `{name: "%row"}`, the leak the snapshot
-// exists to prevent, and canon must not print it either.
-//
-// The knot. A recursive alias names itself inside its own template
-// (`%json = null | ... | [&: %json] | {&: %json}`). Its expansion
-// contains a reference to the name being expanded, and that reference
-// keeps its name: canon cannot spell the declaration it erased, and
-// an infinite unrolling is not a canon. Such a canon does not reparse
-// on its own -- the one place alias erasure and canon convergence
-// pull apart (use-cases/BUGS.md §82). Only the reference that closes
-// the cycle is left as a name; everything up to it expands.
-//
-// Every value is visited once (templates are shared across
-// destinations, and one declaration is reached through many
-// references), children in code-point key order, so the two ports
-// attach the same expansions in the same order and print one canon.
-// Twin of expandAliases in go/alias.go.
 
 import type { Val } from './type'
 

package/src/allow.ts

@@ -1,60 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE ROLE GATE: may an agent operating under a ROLE modify a SUBTREE?
-//
-// An agent about to change a model (`aontu set`, an overlay, a rewrite)
-// asks first, and the answer comes from a ROLE MODEL that is itself an
-// aontu document: one entry per role, each naming the subtrees the
-// role may modify and, optionally, the ones it may not. Roles are
-// arbitrary identifier strings -- `admin`, `dev`, `product`, `qa` --
-// and the model is whatever its author writes, so the rules of the
-// language (spreads, references, includes, `close()`) compose role
-// models the way they compose everything else.
-//
-// The shape of a role is aontu too. It is conjoined with the model at
-// evaluation, as a spread template over the roles map:
-//
-//   roles: { &: { allow: [&: Entry] deny?: [&: Entry] } }
-//   Entry = string & re("^[$]") & re("[^.]$")
-//
-// so a malformed role -- `allow: "$.a"`, `deny: [1]`, an entry that is
-// empty or does not start at the root or ends in a dot, a roles map
-// that is a number -- is refused by the engine with the engine's own
-// code and site, and this module never invents a finding shape of its
-// own. The shape is a VALUE the model meets, not text appended to it:
-// a model whose last line is an unclosed map or a dangling key would
-// swallow appended text, and the shape would then apply to nothing.
-// A role with no `allow` list allows nothing, because the template's
-// empty list is what the tree holds for it.
-//
-// The lists are read from the WRITTEN tree, not from the generated
-// document: a `hide()` mark keeps a list out of the output, and a gate
-// that read the output would let a hidden `deny` vanish -- the wrong
-// direction to be wrong in. Each entry must still be one concrete
-// string: a kind (`string`) or anything else that does not generate is
-// refused with the engine's `no_gen`.
-//
-// The rule is deliberately small, and it errs towards refusal:
-//
-//   - A path is ALLOWED when some `allow` entry is an ancestor of it or
-//     equal to it. Being allowed `$.services` allows `$.services.auth`
-//     and `$.services.auth.replicas`; it does not allow `$` -- a change
-//     at the root reaches every sibling too.
-//   - A path is REFUSED when any `deny` entry INTERSECTS it: an
-//     ancestor, itself, or a descendant. Denied `$.services.*.tier`
-//     refuses `$.services.auth.tier` (the denied node), and it refuses
-//     `$.services.auth` and `$.services` too, because a change at
-//     either could rewrite the tier. Deny wins over allow whatever the
-//     order the entries were written in.
-//   - `*` in an entry matches exactly one segment, any key. It is the
-//     only pattern character; everything else is a key or a list index
-//     compared for equality, as a reference compares them.
-//   - A role is ONE KEY of the roles map, looked up as written, and a
-//     role the map does not declare may modify nothing.
-//
-// The answer names the entry that decided it, as a path INTO THE ROLE
-// MODEL (`$.roles.dev.deny.0`), so `aontu why` can say who wrote the
-// rule and where.
 
 import { Aontu } from './aontu'
 import { ConjunctVal } from './val/ConjunctVal'
@@ -78,7 +23,7 @@ export type AllowReason = 'allow' | 'deny' | 'uncovered' | 'no_role'
 
 
 export type AllowDecision = {
-  path: string          // the asked path, normalised: `$.a.b`
+  path: string
   allowed: boolean
   reason: AllowReason
   by?: string           // the deciding entry's path in the role model
@@ -90,9 +35,6 @@ export type AllowReport = {
   verdict: AllowVerdict
   role: string
   paths: AllowDecision[]
-  // G2's finding shape, as every verb reports: empty when the verdict
-  // is `allowed`, the engine's own failure when it is `error`, and
-  // the `no_path` of an undeclared role beside the refusals.
   findings: VetFinding[]
 }
 
@@ -106,10 +48,6 @@ export type AllowOptions = IncludeOptions & {
 }
 
 
-// One entry: a string that starts at the root and does not end in a
-// dot. `re()` refuses a nested quantifier, so the two conditions are
-// two patterns rather than one grammar; an empty segment in the middle
-// is harmless, because the path split drops it as a reference does.
 const ENTRY = 'string & re("^[$]") & re("[^.]$")'
 
 // The shape every role must satisfy, in the language: a list of
@@ -117,10 +55,6 @@ const ENTRY = 'string & re("^[$]") & re("[^.]$")'
 const ROLE_SHAPE = `{ allow: [&: ${ENTRY}] deny?: [&: ${ENTRY}] }`
 
 
-// The shape document: a spread over the roles map at `at`, or -- when
-// the roles map IS the document -- a top-level spread. Keys are quoted
-// the way `aontu set` quotes an overlay line, so a segment may be a
-// word the grammar spells otherwise.
 function shapeSource(at: string): string {
   const keys = pathParts(at).map((p) => JSON.stringify(p))
   return 0 === keys.length
@@ -136,8 +70,6 @@ function pathText(parts: string[]): string {
 }
 
 
-// The finding shape `get` reports with, deliberately: the gate invents
-// no error format of its own.
 function finding(
   code: string, path: string, message: string, note?: string): VetFinding {
   return {
@@ -159,10 +91,6 @@ type Entry = {
 }
 
 
-// The entries of one list of the role, read from the tree. A concrete
-// string is taken as written, hidden or not; anything else is asked
-// to generate, which is where a kind or a hidden kind fails with the
-// engine's own code, and where a preference answers with its default.
 function readEntries(
   list: any, by: string, ctx: any,
 ): { entries: Entry[], finding?: VetFinding } {
@@ -188,9 +116,6 @@ function segmentMatches(pattern: string, segment: string): boolean {
 }
 
 
-// The two subtrees share a node: one is an ancestor of the other, or
-// they are the same. Checked over the shorter of the two, because the
-// longer one only says where inside the shared subtree it goes on.
 function intersects(entry: string[], path: string[]): boolean {
   const n = Math.min(entry.length, path.length)
   for (let i = 0; i < n; i++) {
@@ -202,9 +127,6 @@ function intersects(entry: string[], path: string[]): boolean {
 }
 
 
-// The entry is an ancestor of the path, or the path itself. A longer
-// entry names something INSIDE the asked subtree, and a change to the
-// subtree reaches its siblings, so it does not cover.
 function covers(entry: string[], path: string[]): boolean {
   return entry.length <= path.length && intersects(entry, path)
 }
@@ -214,9 +136,6 @@ function decide(asked: string, allows: Entry[], denies: Entry[]): AllowDecision
   const parts = pathParts(asked)
   const path = pathText(parts)
 
-  // Deny first, and any intersection refuses: an entry above the path
-  // forbids the whole subtree it is in, and one below it forbids the
-  // change that would rewrite it from above.
   for (const d of denies) {
     if (intersects(d.parts, parts)) {
       return { path, allowed: false, reason: 'deny', by: d.by, pattern: d.text }
@@ -247,14 +166,6 @@ export function allow(
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == options.path ? undefined : { path: options.path }
 
-  // The model MEETS the shape as data meets a schema under vet: both
-  // parsed, conjoined, and unified ONCE. A parsed tree is single-use,
-  // and a model evaluated on its own and then met again has already
-  // resolved its references against itself, so a registry written
-  // `roles: close({ &: $.Role ... })` would fail its second pass with
-  // a `$.Role` it cannot find. The shape is parsed FIRST: the context
-  // takes the last parsed document as its root and as the text an
-  // error frame excerpts, and both must be the model's.
   const shape = aontu.parse(shapeSource(at), undefined, ctx)
   const model = aontu.parse(src, parseOpts, ctx)
   if (0 < ctx.err.length) {
@@ -266,12 +177,6 @@ export function allow(
     return errorReport(role, evalFailure(ctx))
   }
 
-  // The shape made the roles map exist, so what can be missing is the
-  // ROLE -- and an undeclared role may modify nothing. That is the
-  // question's answer (refused), not a broken model (error), and the
-  // finding carries the nearest declared name. The role is one key,
-  // looked up as written: not a path, so a name may hold a dot, and
-  // an own key only, so a name the prototype has is not a role.
   const roles: any = anchorAt(root, at)
   const atRole = `${at}.${role}`
   if (!Object.prototype.hasOwnProperty.call(roles.peg, role)) {

package/src/aontu.ts

@@ -35,22 +35,9 @@ import { format, unifiedDiff } from './format'
 export type { LintFinding, FormatReport, FormatOptions } from './format'
 
 
-// VERSION is the Aontu npm package version, and mirrors
-// go/aontu.go's `Version` (which tracks the Go module version
-// separately — the two version series are independent).
-//
-// 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.62.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.
+const VERSION = '0.63.0'
+
+
 function genQuiet(val: any, aontu: Aontu): any {
   return val.gen(aontu.ctx({ collect: true }))
 }
@@ -64,25 +51,9 @@ 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: {
@@ -118,12 +89,6 @@ class Aontu {
   }
 
 
-  // Parse source into a matching Val AST, not yet unified.
-  //
-  // NOTE: the returned Val is SINGLE-USE — unify()/generate() refine the
-  // tree in place (see Val.unify), so do not unify or generate the same
-  // parsed Val more than once, and do not share it across threads. Call
-  // parse() again for a fresh tree.
   parse(src: string, opts?: AontuOptions, ac?: AontuContext): Val | undefined {
     let out: Val | undefined
     let errs: any[] = []
@@ -140,12 +105,6 @@ class Aontu {
       errs.push(out)
     }
     else {
-      // A version-control conflict marker is refused BEFORE the parse
-      // (issue #5). None of `<`, `=` or `>` is an aontu operator, so a
-      // marker line is ordinary text and `<<<<<<< HEAD` parsed happily
-      // into the two-string list ["<<<<<<<","HEAD"] -- an unresolved
-      // merge became a plausible document instead of an error, and the
-      // report of it read as a failed `<` operation.
       const marker = findConflictMarker(src)
       if (-1 !== marker.offset) {
         const nil: any = makeNilErr(ac, 'merge_conflict')
@@ -158,10 +117,6 @@ class Aontu {
 
     if (0 === errs.length) {
       out = runparse(src, this.lang, ac)
-      // 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
     }
@@ -207,10 +162,6 @@ class Aontu {
       out = uni.res
 
       out.deps = pval.deps
-      // THE DERIVED STRUCTURE (G4 phase 3): the edge set, computed
-      // once from the unified tree. Cheap on a document with no links
-      // — 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
@@ -222,19 +173,6 @@ class Aontu {
   }
 
 
-  // Generate output structure from source, which must parse and fully unify.
-  //
-  // The result is made of NATIVE values, and D9 puts two beyond what
-  // `JSON.stringify` can write: a `biginteger` (a `0d` literal with no
-  // fraction or exponent) generates as a native `bigint`, and a
-  // `bigdecimal` generates as a `Decimal`. Both are exact at any
-  // magnitude, which is the whole point of the leaves -- and both are
-  // confined to documents that opt in, so a `0d`-free document generates
-  // exactly what it always did.
-  //
-  // Serialise the result with `exactJSON` (exported alongside this
-  // class), NOT with `JSON.stringify`: the latter throws on a bigint and
-  // has no way to write exact digits as a JSON number.
   generate(src: string, opts?: any, ac?: AontuContext): any {
     try {
       let out = undefined
@@ -247,7 +185,6 @@ class Aontu {
       if (undefined !== pval && 0 === pval.err.length) {
 
         let uval = this.unify(pval, undefined, ac)
-        // console.log('AONTU-GENERATE-UVAL', uval.constructor, uval.mark)
 
         if (undefined !== uval && 0 === uval.err.length) {
 
@@ -255,23 +192,6 @@ class Aontu {
             : 0 < ac.err.length ? undefined
               : uval.gen(ac as any)
 
-          // The relation verdict (RELATIONS P2): declarations the
-          // graph atoms registered during unification are decided
-          // HERE, where no more information can arrive -- the sizing
-          // atoms' model. A violated declaration is a located
-          // evaluation error at the offending edge, and the generated
-          // value is discarded below.
-          //
-          // AFTER GENERATION, and only when generation SUCCEEDED. A
-          // document that cannot be generated has no finished model
-          // to have a graph verdict about: an unsettled disjunction
-          // leaves alternatives the graph walk cannot read, so a
-          // mirror the document writes is absent from the edge set
-          // and `inverse(n)` reports it missing -- a false finding,
-          // and one that buried the `disjunct_no_gen` that actually
-          // stopped the document. The check that a broken document is
-          // not blamed on its relations (`relations` verb, finding F)
-          // holds here too.
           if (!uval.isNil && 0 === ac.err.length) {
             relationErrors(ac as any, uval)
             if (0 < ac.err.length) {
@@ -333,17 +253,6 @@ function handleErrors(errs: any[], out: Val | undefined, ac: AontuContext) {
 }
 
 
-// Locate the first version-control conflict marker in a source, as a
-// 1-based row and column (offset -1 when there is none).
-//
-// The shape is git's, and it is matched exactly: SEVEN of `<`, `=` or `>`
-// at the very start of a line, then either the end of that line or a
-// space before the branch label. Requiring the run length and the line
-// start is what keeps a document that legitimately writes `a:"<<<<<<<"`,
-// or a row of `=` inside a string, from being refused -- the marker is
-// recognised as the artifact it is, not as a suspicious character.
-//
-// Kept byte-identical to findConflictMarker in go/lang.go.
 function findConflictMarker(src: string): {
   offset: number, row: number, col: number
 } {
@@ -444,17 +353,9 @@ export {
   util,
   formatExplain,
 
-  // D9 -- the generate contract. `exactJSON` is the supported way to
-  // turn `generate()` output into JSON when a document uses the exact
-  // leaves, and `Decimal` is the type a `bigdecimal` generates as (a
-  // `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,
 
@@ -464,10 +365,6 @@ export {
   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,
 
@@ -497,10 +394,6 @@ export {
   renderValue,
   renderProfile,
 
-  // The template surface (docs/design/TEMPLATE.0.md): the two text
-  // transforms behind `aontu template`, and the marker an extension
-  // names. Neither evaluates anything -- a template is a spelling of
-  // a generator, so the transforms are text in and text out.
   desugarTemplate,
   resugarTemplate,
   markerFor,