aontu 0.55.0 → 0.57.0

package/src/hints.ts

@@ -192,6 +192,8 @@ const hints: Record<string, string> = {
   view_kind_unknown: 'The figure kind is not one the verb draws. The kinds are tree, matrix,\ngraph, layer, sets, layers, ladder and poset; the note lists them.',
 
   view_profile_unknown: 'The figure kind does not render into the profile asked for: there is no\ntext form of a node-link drawing and no Mermaid form of a matrix. The\nnote lists the profiles the kind declares; the first is its default.',
+
+  format_check: 'The formatted text is not the same document, so nothing was written.\nThis is a formatter defect: please report it, with the source.',
   view_style_profile: 'Each profile has ONE way to carry the meaning of a figure\'s marks:\nSGR escapes for text, CSS classes for svg. Asking for the other one is\na usage error rather than a silent no-op. `none` works everywhere.',
   view_style_unknown: 'The styles are none, ansi and css, plus `auto` at the command line,\nwhich the command resolves before the library runs: whether the\ndestination is a terminal is not something a library can see.',
 
@@ -220,11 +222,33 @@ const hints: Record<string, string> = {
 
   match_none: 'No pattern matched, and there is no default. `match` tries each\npattern in the order written and takes the first the value unifies\nwith; the value {value} unified with none of {tried}. Add a trailing\ndefault — the argument after the last pair — if the rest was meant\nto be allowed.\n \nExamples:\n  match(1, integer, ok)             -> "ok"   # The first pattern matches;\n  match(x, integer, ok, other)      -> "other"  # ... or the default does;\n  match(x, integer, ok)             -> nil    # ... but nothing here does.',
 
+  emit_data: 'The first argument to emit() is not a bag. `emit` visits the\nchildren of its SELECTION, so the selection has to have children: a\nlist of nodes, or a map whose values are the nodes.\n \nExamples:\n  emit([{k:1}], {match:{k:1},body:[a]})   -> [..]  # A list of nodes;\n  emit({x:{k:1}}, {match:{k:1},body:[a]}) -> [..]  # ... or a map of them;\n  emit(1, {match:{k:1},body:[a]})         -> nil   # ... but not a scalar.',
+
+  emit_table: 'The second argument to emit() is not a rule table. A table is a\nLIST of templates, tried in order; a single template may be written\nas the map itself, which is that list of one.\n \nExamples:\n  emit($.n, [{match:integer,body:[a]}]) -> [..]  # A table of rules;\n  emit($.n, {match:integer,body:[a]})   -> [..]  # ... or one rule alone;\n  emit($.n, integer)                    -> nil   # ... but not a value.',
+
+  emit_template: 'A template in an emit() table is not a rule. Every rule is a map\nnaming both a `match` — the pattern the node is tried against — and a\n`body`, the pieces to emit. A rule with no pattern would claim every\nnode by accident; one with no body would claim a node and emit\nnothing.\n \nExamples:\n  {match: {kind: sqs}, body: [a]}  # A rule;\n  {match: {kind: sqs}}             # ... but a pattern is not one;\n  {body: [a]}                      # ... nor is a body alone.',
+
+  emit_body: 'A template body in an emit() table is not a list. A body is the\nSEQUENCE of pieces the matched node emits, so it is written as a\nlist even when it holds one piece — which is what lets bodies\ncompose, since a body element that is itself a list splices.\n \nExamples:\n  {match: integer, body: [a]}    -> [..]  # One piece;\n  {match: integer, body: [a,b]}  -> [..]  # ... or several;\n  {match: integer, body: a}      -> nil   # ... but not a bare value.',
+
+  emit_ref: 'A template body names {ref}, and the node it matched cannot\nanswer it. Inside a body a relative reference is a field of the\nMATCHED NODE — `.pin` is that node\'s `pin` — so the node has to have\nthe field; the node was {value}. An absolute reference (`$.x`) reads\nthe document root instead, and is untouched.\n \nExamples:\n  {match:{pin:string}, body:[.pin]}  -> [..]  # A field of the node;\n  {match:{pin:string}, body:[$.z]}   -> [..]  # ... or the root;\n  {match:{pin:string}, body:[.port]} -> nil   # ... but not a field it\n                                             #     has not got.',
+
+  emit_none: 'No template matched a node, and there is no catch-all. `emit`\ntries each template in the order written and takes the first the\nnode unifies with; the node {value} unified with none of {tried}.\nAdd a template whose `match` is `any` — last, since the first match\nwins — if the rest of the selection was meant to be allowed.\n \nExamples:\n  emit([1], [{match:integer,body:[a]}])  -> [..]  # A pattern matches;\n  emit([x], [{match:any,body:[a]}])      -> [..]  # ... or a catch-all;\n  emit([x], [{match:integer,body:[a]}])  -> nil   # ... but nothing here.',
+
+  esc_variant: 'esc() and usc() were given a variant that names no convention.\nA variant names a CONVENTION rather than a language, because several\nlanguages share one and one language has several. The names are `sq`,\n`sql`, `shell`, `xml`, `uri` and `regex`; written with no variant at\nall it is the C escape, JSON canonical, which covers the double-quoted\nliteral of every C-family language.\n \nExamples:\n  esc(text)          -> ...   # C / JSON, the default;\n  esc(text, sq)      -> ...   # ... single-quoted C-family;\n  esc(text, pascal)  -> nil   # ... but that is not a convention.',
+
+  usc_malformed: 'usc() was given text the convention could not have produced,\nso there is nothing to read back out: a truncated code-point escape, an\nescape the convention does not define, or an escape character standing\nalone where the convention doubles it. `usc` is the LEFT inverse of\n`esc` and it is partial — every escaped value has an original, but not\nevery string is an escaped value.\n \nExamples:\n  usc(esc(text))     -> ...   # Whatever esc() wrote;\n  usc(text, sql)     -> ...   # ... in the same convention;\n  usc(text, shell)   -> nil   # ... but not in another one.',
+
+  rep_pattern: 'The pattern given to rep() is outside the portable subset. It is\nthe same subset re() takes — RE2-compatible, no backreferences, no\nlookaround — so one document has one regexp language rather than two,\nand so a generator running a pattern over model data cannot take\nexponential time doing it.\n \nExamples:\n  rep(s, "[:,]", " ")     -> ...   # A class;\n  rep(s, "(a)(b)", "$2$1") -> ...   # ... a group;\n  rep(s, "(?=a)", "x")    -> nil   # ... but not a lookahead.',
+
+  rep_sub: 'The substitution given to rep() names something the pattern has\nnot got. `$1` to `$9` are the numbered groups, `$&` is the whole match\nand `$$` is a literal `$`; a `$` naming anything else, or a group\nnumber the pattern does not have, is refused rather than expanded to\nnothing — a generator that writes a file with a hole in it and says\nnothing is the failure this refusal exists to close.\n \nExamples:\n  rep(s, "(a)", "[$1]")  -> ...   # A group the pattern has;\n  rep(s, "a", "$$")      -> ...   # ... a literal dollar;\n  rep(s, "a", "$1")      -> nil   # ... but not a group it has not.',
+
+  split_sep: 'The separator given to split() is neither a string nor a pattern.\nA plain string is a LITERAL and an `re(…)` argument is a pattern — the\nasymmetry with rep() is deliberate, since splitting is usually on a\nliteral, and it removes the trap where `split(v, ".")` silently cuts\nbetween every character.\n \nExamples:\n  split("a,b", ",")        -> [..]  # A literal separator;\n  split("a1b", re("[0-9]")) -> [..]  # ... or a pattern;\n  split("a,b", 1)          -> nil   # ... but not a number.',
+
   place_pair: 'Two placeholders met, and neither has a value to fill the other.\n`_` is a HOLE: it is filled by whatever the call is unified with, so\na call holding one needs a peer that does not. Give one side a\nvalue.\n \nExamples:\n  upper(_) & hello        -> "HELLO"  # The peer fills the hole;\n  _ + 2 & 1               -> 3        # ... whatever the call is;\n  upper(_) & lower(_)     -> nil      # ... but two holes fill nothing.',
 
 
   module_path: 'A module import is domain-shaped and carries a major, but its\npath cannot be a directory on every platform the toolchain runs on --\nso it is refused before anything is built from it. An element may not\nbe empty, may not begin or end with `.` (which is what forbids `..`),\nand may not be a reserved device name. These are Go\'s module-path\nrules, for Go\'s reason: a module path becomes a real directory.\n \nExamples:\n  @"corp.example/s@1"        -> {..} # An ordinary path is fine;\n  @"corp.example/../s@1"     -> nil  # ... `..` would escape the store;\n  @"corp.example/nul@1"      -> nil  # ... and Windows has no such file.',
-  module_missing: 'A module import names a module that is not in this project. A\nmodule is resolved from LOCAL stores only -- `aon_vendor/` beside the\nproject\'s mod.aon, then the user cache -- because evaluation never\ntouches the network. Fetching is a separate step, and the message\nnames it.\n \nExamples:\n  @"corp.example/s@1"        -> nil  # Not fetched: run aontu mod get;\n  @"./local.aon"             -> {..} # ... a local path is not a module;\n  @"corp.example/s@1#aon1-…" -> {..} # ... and a pin does not fetch it either.',
+  module_missing: 'A module import names a module that is not in this project. A\nmodule is resolved from LOCAL stores only -- `aontu_meta/vendor/` beside the\nproject\'s mod.aon, then the user cache -- because evaluation never\ntouches the network. Fetching is a separate step, and the message\nnames it.\n \nExamples:\n  @"corp.example/s@1"        -> nil  # Not fetched: run aontu mod get;\n  @"./local.aon"             -> {..} # ... a local path is not a module;\n  @"corp.example/s@1#aon1-…" -> {..} # ... and a pin does not fetch it either.',
 
   module_integrity: 'A module resolved locally does not have the MEANING it was pinned\nto. The pin is a canon-hash -- the hash of the module unified\nstandalone -- so it survives comments, formatting and refactoring and\nbreaks on any semantic change in the module\'s transitive closure.\nVerification is always local: the registry\'s annotation is advisory.\n \nExamples:\n  @"corp.example/s@1"        -> {..} # No pin, no check;\n  @"corp.example/s@1#aon1-x" -> nil  # ... a pin that disagrees refuses;\n  aontu hash <file>                  # ... and this is what it should be.',
 
@@ -513,6 +537,9 @@ const codeClasses: Record<string, string> = {
   view_profile_unknown: 'reference',
   view_style_profile: 'reference',
   view_style_unknown: 'reference',
+  // The formatter's self-check (docs/design/FMT.0.md): a report-layer
+  // code, class internal -- the formatter, not the document, is wrong.
+  format_check: 'internal',
   view_rows_exceeded: 'budget',
   view_line_break: 'parse',
   view_relation_ambiguous: 'reference',
@@ -544,6 +571,31 @@ const codeClasses: Record<string, string> = {
   filter_data: 'parse',
   match_none: 'conflict',
 
+  // G9 phase 6 -- the string builtins. All five are class `parse`:
+  // what is wrong is the CALL as written -- a variant that names no
+  // convention, a pattern outside the subset, a substitution naming a
+  // group that does not exist, a separator that is neither string nor
+  // pattern. `usc_malformed` is the odd one and still `parse`: the
+  // TEXT the call was given has no inverse, which is a fact about the
+  // argument rather than about any meet.
+  esc_variant: 'parse',
+  usc_malformed: 'parse',
+  rep_pattern: 'parse',
+  rep_sub: 'parse',
+  split_sep: 'parse',
+
+  // G9 phase 6 -- apply-templates. The four shape codes are class
+  // `parse`: what is wrong is the CALL as written -- a selection with
+  // no children, a table that is not one, a rule missing a half.
+  // `emit_none` is class `conflict` for `match_none`'s reason: the
+  // node and every pattern written for it disagreed.
+  emit_data: 'parse',
+  emit_table: 'parse',
+  emit_template: 'parse',
+  emit_body: 'parse',
+  emit_none: 'conflict',
+  emit_ref: 'conflict',
+
   // G8 phase 3 -- the placeholder. Class `conflict`: two values met
   // and neither could answer for the other, which is what every
   // conflict is.

package/src/jsonschema.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // JSON SCHEMA EXPORT (the review's finding I / SUPPORT.md act 2).
 //
@@ -75,6 +76,11 @@ export type SchemaOptions = {
   // its own directory.
   path?: string
   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[]
 }
 
 
@@ -501,7 +507,7 @@ function fromList(ctx: Ctx, path: string[], v: any): any {
 // The verb. Evaluate, anchor, walk, report.
 export function jsonSchema(src: string, options?: SchemaOptions): SchemaReport {
   const opts = options ?? {}
-  const aontu = new Aontu(null == opts.trust ? {} : { trust: opts.trust })
+  const aontu = new Aontu(includeOpts(opts))
 
   // COLLECT MODE, so a syntax error arrives on the context rather than
   // as a throw -- the same failure Go's `parseEntry` hands back as an

package/src/lang.ts

@@ -145,6 +145,10 @@ import { PackFuncVal } from './val/PackFuncVal'
 import { EachFuncVal } from './val/EachFuncVal'
 import { FilterFuncVal } from './val/FilterFuncVal'
 import { MatchFuncVal } from './val/MatchFuncVal'
+import { EmitFuncVal } from './val/EmitFuncVal'
+import {
+  EscFuncVal, UscFuncVal, RepFuncVal, SplitFuncVal,
+} from './val/StrFuncVal'
 import {
   AddFuncVal, SubFuncVal, MulFuncVal, DivFuncVal, ModFuncVal, RemFuncVal,
 } from './val/ArithFuncVal'
@@ -667,6 +671,25 @@ help isolate the syntax error.`,
     // the language does not grow a second. It is the primitive that
     // turns a bag of computed lines into a file.
     join: JoinFuncVal,
+
+    // G9 phase 6: apply-templates. One flat list of pieces from a
+    // selection and a RULE TABLE -- for each node, the first template
+    // whose `match` it unifies with, its `body` instantiated at that
+    // node. The dispatch is the engine's because a body referenced by
+    // path resolves its references at the definition site, and the
+    // relative resolution that does exist is a dot count that does not
+    // survive a second dispatch (docs/design/EMIT.0.md).
+    emit: EmitFuncVal,
+
+    // G9 phase 6: the string builtins the rule layer needs. `esc`
+    // makes a value safe inside a literal and `usc` reads it back;
+    // `rep` and `split` derive names from model data. All four are
+    // ordinary string functions -- they know nothing about generation,
+    // which is why they can land before the renderer does.
+    esc: EscFuncVal,
+    usc: UscFuncVal,
+    rep: RepFuncVal,
+    split: SplitFuncVal,
   }
 
 
@@ -1597,6 +1620,14 @@ help isolate the syntax error.`,
 // references, constraints, its own includes. Two extensions, and they
 // are the ones this project owns.
 //
+// `text` — the file's BYTES, as one string scalar. No parser is
+// chosen, so there is nothing for two ports to disagree about and
+// nothing in the file that can mean anything: `notes: @"notes.txt"`
+// is a document loading prose into a string. `.txt` is the only
+// extension here by default; `AontuOptions.textExt` (the CLI's
+// `--text-ext`) adds others, because which name a project keeps its
+// templates under is the project's business, not this table's.
+//
 // A FORMAT NAME — configuration DATA, parsed by that format's own
 // parser into the JSON value it denotes, which then becomes Aontu
 // values like any other data. Every one of these formats maps onto
@@ -1628,8 +1659,43 @@ const INCLUDE_KINDS: { [kind: string]: string } = {
   yaml: 'yaml',
   yml: 'yaml',
   ini: 'ini',
+
+  txt: 'text',
+}
+
+
+// WHAT AN EXTENSION MEANS, for this parse. The table is the fixed
+// part; `textExt` is the per-parse widening, and it wins over nothing
+// -- a host cannot re-read `.toml` as text, because an extension the
+// table already names has a meaning documents rely on. Undefined is
+// the refusal, and it is the ONE place that decides it: the resolver's
+// gate and the processor map both ask here, so a widening cannot reach
+// one and not the other.
+function includeFormat(
+  ext: string, textExt?: string[]): string | undefined {
+  const known = INCLUDE_KINDS[ext]
+  if (undefined !== known) {
+    return known
+  }
+  // NOT EVEN AS TEXT. `.js` is the extension ADR-012 singles out
+  // because multisource's own default EXECUTES it, and an extension
+  // this project refuses on purpose stays refused however a flag is
+  // spelled -- reading it is harmless, but a widening that can reach
+  // the one name the rule names is a widening whose limit nobody can
+  // state. Go's includeFormat holds the same list, and the two CLIs
+  // are diffed on `--text-ext js` because they once disagreed here.
+  if (REFUSED_EXT.has(ext)) {
+    return undefined
+  }
+  return textExt?.includes(ext) ? 'text' : undefined
 }
 
+
+// Extensions no widening may reach. `js` executes under multisource's
+// default processor; `''` is the no-extension fallback, which names no
+// file type at all.
+const REFUSED_EXT = new Set(['js', ''])
+
 // `.csv` IS DELIBERATELY ABSENT, and the reason is ADR-001 rather than
 // taste. The two ports' CSV parsers disagree about what a CSV file IS:
 // one answers header-keyed records with string fields, the other raw
@@ -1754,13 +1820,20 @@ const dataProcessor = (format: string) => (res: any) => {
   res.val = rawToVal(DATA_READERS[format](res.src, res.path))
 }
 
+// TEXT IS NOT PARSED. The bytes multisource read are the value, so
+// this is the one processor with no reader behind it -- which is why
+// a `.txt` include cannot fail on content, only on being unreadable.
+const textProcessor = (res: any) => {
+  res.val = new StringVal({ peg: res.src })
+}
+
 /**
  * The multisource processor map, built FROM the include table so the
  * two cannot drift: every extension the table names gets the reader
  * the table names for it, and the two kinds that are not in the table
  * refuse.
  */
-function includeProcessors(): { [kind: string]: any } {
+function includeProcessors(textExt?: string[]): { [kind: string]: any } {
   const map: { [kind: string]: any } = {
     // multisource's fallback for an extension no entry names, so it is
     // the one that catches whatever the resolver's gate did not.
@@ -1769,9 +1842,23 @@ function includeProcessors(): { [kind: string]: any } {
     js: refuseProcessor,
   }
   const source = makeJsonicProcessor()
+  const forKind = (kind: string) => {
+    const format = includeFormat(kind, textExt)
+    if ('source' === format) return source
+    if ('text' === format) return textProcessor
+    return dataProcessor(format as string)
+  }
   for (const kind of Object.keys(INCLUDE_KINDS)) {
-    const format = INCLUDE_KINDS[kind]
-    map[kind] = 'source' === format ? source : dataProcessor(format)
+    map[kind] = forKind(kind)
+  }
+  // A WIDENING NEVER OVERWRITES. `js` and the empty fallback refuse
+  // above and stay refusing: `--text-ext js` would otherwise turn the
+  // one extension ADR-012 singles out into a readable one, by a flag
+  // whose whole promise is that it chooses no parser.
+  for (const ext of textExt ?? []) {
+    if (undefined === map[ext]) {
+      map[ext] = textProcessor
+    }
   }
   return map
 }
@@ -1893,7 +1980,7 @@ function makeModelResolver(options: any) {
   // module legs do not: both state `kind: 'aon'` because what they
   // serve is Aontu source by construction, not by its spelling.
   const gateExtension = (path: string, full: string): void => {
-    if (undefined === INCLUDE_KINDS[extKindOf(full)]) {
+    if (undefined === includeFormat(extKindOf(full), options.textExt)) {
       refuseExtension(path, full)
     }
   }
@@ -2001,7 +2088,7 @@ function makeModelResolver(options: any) {
       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
+        // rooted profile sees the project's own `aontu_meta/vendor/` and
         // nothing else, which is what `root` means.
         ...(null == rootDir ? { cache: modCache(options) } : {}),
         eval: options.mod?.eval,
@@ -2308,7 +2395,7 @@ class Lang {
         // (BUGS §49b). Its `js` entry EXECUTES the file, which is not
         // something an extension should be able to ask for. And its
         // fallback hands any other file back as TEXT.
-        processor: includeProcessors()
+        processor: includeProcessors(this.opts.textExt)
       })
       .use(AontuJsonic)
   }

package/src/lsp.ts

@@ -21,7 +21,9 @@ import type { Val } from './type'
 import { Aontu, VERSION } from './aontu'
 import { getHint } from './err'
 import { collectNils } from './walk'
-import { collectDeprecations, deprecationMessage } from './utility'
+import { collectDeprecations, deprecationMessage,
+  includeOpts,
+} from './utility'
 import { why } from './query'
 import type { WhyConjunct } from './provenance'
 
@@ -84,13 +86,13 @@ type OutMessage = {
 // functions, syntax errors) produce diagnostics.
 function computeDiagnostics(
   src: string,
-  opts?: { vars?: Record<string, Val>, trust?: any }
+  opts?: { vars?: Record<string, Val>, trust?: any, textExt?: string[] }
 ): Diagnostic[] {
   // The trust profile (G5, docs/trust.md): the LSP is the
   // highest-exposure surface — merely OPENING a hostile .aon file in an
   // editor performs its reads — so the handler confines evaluation to
   // the workspace root and threads the profile through here.
-  const aontu = new Aontu(null == opts?.trust ? {} : { trust: opts.trust })
+  const aontu = new Aontu(includeOpts(opts ?? {}))
 
   let root: any
   let ac: any
@@ -525,13 +527,13 @@ const COMPLETION_KEYWORD = 14
 // between G4 phases 1/2 and G8 phase 1.
 const BUILTIN_FUNCS = [
   'above', 'acyclic', 'add', 'below', 'close', 'copy', 'deprecate', 'div',
-  'each',
+  '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', 're', 'refer', 'rel', 'rem', 'sub', 'sum', 'super', 'type', 'unique',
-  'upper',
+  'pref', 're', 'refer', 'rel', 'rem', 'rep', 'split', 'sub', 'sum',
+  'super', 'type', 'unique', 'upper', 'usc',
 ]
 
 // Scalar-kind and literal keywords.

package/src/mcp-server.ts

@@ -30,9 +30,9 @@ import type { McpRequest, McpResponse } from './mcp'
 import { VERSION } from './aontu'
 
 
-const USAGE = 'aontu-mcp - Aontu MCP server (stdio, NDJSON JSON-RPC)\n' +
+const USAGE = 'aontu mcp - Aontu MCP server (stdio, NDJSON JSON-RPC)\n' +
   '\n' +
-  '  aontu-mcp [--root <dir>]\n' +
+  '  aontu mcp [--root <dir>]\n' +
   '\n' +
   '  --root <dir>  Serve <name>Path file arguments and resolve\n' +
   '                @"..." includes, confined below <dir>\n' +
@@ -41,6 +41,7 @@ const USAGE = 'aontu-mcp - Aontu MCP server (stdio, NDJSON JSON-RPC)\n' +
 
 
 // The startup arguments. Parsed here rather than in bin/aontu-mcp.js
+// or the CLI's mcp verb
 // so the parsing is import-testable; unknown options REFUSE rather
 // than warn, because a server whose operator typo'd --root must not
 // come up quietly unconfined.

package/src/mcp.ts

@@ -459,6 +459,8 @@ const TOOLS: ToolDef[] = [
     name: 'view',
     description:
       'Draw a figure of the document as deterministic text. Kinds: ' +
+      'doc (the shape of the document itself), lattice (the value ' +
+      'lattice, with the document\'s own values placed on it), ' +
       'tree (the dependency tree of a relation), matrix (the ' +
       'dependency matrix, canon or partition order, --closure), graph ' +
       '(node-link, as mermaid, dot or er), layer (the architecture ' +
@@ -474,8 +476,8 @@ const TOOLS: ToolDef[] = [
       kind: {
         type: 'string',
         description:
-          'The figure to draw: tree (the default), matrix, graph, layer, ' +
-          'sets, layers or ladder',
+          'The figure to draw: tree (the default), doc, lattice, matrix, ' +
+          'graph, layer, sets, layers or ladder',
       },
       as: {
         type: 'string',
@@ -565,8 +567,8 @@ const TOOLS: ToolDef[] = [
     required: ['source'],
     docs: ['source'],
     check: (a) => {
-      const kinds = ['doc', 'tree', 'matrix', 'graph', 'layer', 'sets',
-        'layers', 'ladder']
+      const kinds = ['doc', 'lattice', 'tree', 'matrix', 'graph', 'layer',
+        'sets', 'layers', 'ladder']
       if (null != a.kind && !kinds.includes(a.kind)) {
         return `kind must be one of ${kinds.join(', ')}, not ${JSON.stringify(a.kind)}`
       }

package/src/mod-tool.ts

@@ -78,7 +78,7 @@ export type ModVerifyReport = {
 
 export type ModVendorReport = {
   verdict: 'ok' | 'missing'
-  // The modules materialised into `aon_vendor/`, sorted.
+  // The modules materialised into `aontu_meta/vendor/`, sorted.
   vendored: string[]
   // Locked modules present in no store, sorted.
   missing: string[]
@@ -193,7 +193,7 @@ function usableRef(mod: string): ModuleRef | undefined {
 function storeDir(
   root: string, ref: ModuleRef, hash: string, options: ModToolOptions,
 ): string | undefined {
-  const stores = [moduleDir(pathJoin(root, 'aon_vendor'), ref)]
+  const stores = [moduleDir(pathJoin(root, 'aontu_meta', 'vendor'), ref)]
   if (null != options.cache && '' !== hash) {
     stores.push(pathJoin(options.cache, hash))
   }
@@ -203,7 +203,7 @@ function storeDir(
 
 // The lockfile's entries, as written.
 function readLock(root: string): Record<string, ModLock> {
-  const file = pathJoin(root, 'mod-lock.aon')
+  const file = pathJoin(root, 'aontu_meta', 'mod-lock.aon')
   if (!existsSync(file)) {
     return {}
   }
@@ -335,7 +335,8 @@ export function modTidy(root: string, options: ModToolOptions): ModTidyReport {
   const uniqueUnevaluable = [...new Set(unevaluable)].sort()
   const held = 0 === uniqueMissing.length && 0 === uniqueUnevaluable.length
   if (held) {
-    writeFileSync(pathJoin(root, 'mod-lock.aon'),
+    mkdirSync(pathJoin(root, 'aontu_meta'), { recursive: true })
+    writeFileSync(pathJoin(root, 'aontu_meta', 'mod-lock.aon'),
       LOCK_HEADER + lockText(lock, options) + '\n')
   }
 
@@ -441,14 +442,14 @@ export function modVerify(root: string, options: ModToolOptions):
 }
 
 
-// `aontu mod vendor`: materialise the locked closure into `aon_vendor/`.
+// `aontu mod vendor`: materialise the locked closure into `aontu_meta/vendor/`.
 export function modVendor(root: string, options: ModToolOptions):
   ModVendorReport {
   const locked = readLock(root)
   const vendored: string[] = []
   const missing: string[] = []
 
-  const vendorRoot = pathJoin(root, 'aon_vendor')
+  const vendorRoot = pathJoin(root, 'aontu_meta', 'vendor')
 
   for (const mod of Object.keys(locked).sort()) {
     const ref = usableRef(mod)
@@ -593,13 +594,13 @@ function majorOf(version: string): string {
 
 
 // Every file of a module's source tree, relative and forward-slashed.
-// `aon_vendor/` is excluded: a published module carries its own
+// `aontu_meta/vendor/` is excluded: a published module carries its own
 // sources, not a copy of everyone else's -- a consumer resolves the
 // closure itself, and a nested vendor tree would publish the world.
 function layerFiles(dir: string, prefix = ''): string[] {
   const out: string[] = []
   for (const name of readdirSync(dir).sort()) {
-    if ('aon_vendor' === name) {
+    if ('aontu_meta' === name) {
       continue
     }
     const full = pathJoin(dir, name)

package/src/mod.ts

@@ -12,7 +12,7 @@
 //   local:   @"./fragment.aon"        <- unchanged, not a module
 //
 // EVALUATION NEVER TOUCHES THE NETWORK. Resolution reads local stores
-// only: `aon_vendor/` beside the project's `mod.aon`, then a
+// only: `aontu_meta/vendor/` beside the project's `mod.aon`, then a
 // content-addressed user cache keyed by canon-hash. Fetching is a
 // separate, explicit tool step, and a module that is in neither store
 // is an evaluation error that says so.
@@ -81,7 +81,7 @@ export function parseModuleRef(spec: string): ModuleRef | undefined {
 // `[A-Za-z0-9._-]` admits `..`, and `moduleDir` joins elements with
 // pathJoin, which CLEANS `..` rather than refusing it:
 //
-//   moduleDir('/store/aon_vendor', 'corp.example/../../etc/passwd@1')
+//   moduleDir('/store/aontu_meta/vendor', 'corp.example/../../etc/passwd@1')
 //     -> /store/etc/passwd@1
 //
 // `mod vendor` then copied a tree THERE, outside the project entirely,
@@ -168,9 +168,9 @@ export function moduleDir(store: string, ref: ModuleRef): string {
 // root being a directory holding a `mod.aon`. This used to answer with
 // the NEAREST one alone, and the plural is the fix, because a
 // VENDORED MODULE IS A PROJECT INSIDE A PROJECT. A module in
-// `aon_vendor/` carries its own `mod.aon`, which stopped the upward
+// `aontu_meta/vendor/` carries its own `mod.aon`, which stopped the upward
 // walk there, so a nested import resolved against the vendored
-// module's own directory: a tree with no `aon_vendor/` of its own, and
+// module's own directory: a tree with no `aontu_meta/vendor/` of its own, and
 // therefore a `module not fetched` for a dependency sitting flat
 // beside it in the CONSUMER's vendor tree — the only layout `mod
 // vendor` produces (use-cases/BUGS.md §31).
@@ -272,7 +272,7 @@ export function modCacheDirFor(
 
 export function lockHash(root: string, ref: ModuleRef, fs: ModuleFs):
   string | undefined {
-  const file = pathJoin(root, 'mod-lock.aon')
+  const file = pathJoin(root, 'aontu_meta', 'mod-lock.aon')
   if (!fs.existsSync(file)) {
     return undefined
   }
@@ -392,7 +392,7 @@ export function resolveModule(
     roots.map((r) => lockHash(r, ref, fs)).find((h) => null != h)
 
   const stores: string[] =
-    roots.map((r) => moduleDir(pathJoin(r, 'aon_vendor'), ref))
+    roots.map((r) => moduleDir(pathJoin(r, 'aontu_meta', 'vendor'), ref))
   if (null != options.cache && null != expect) {
     // Content-addressed: the cache is keyed by the hash, so a cache hit
     // is already the right MEANING before anything is read from it.

package/src/patch.ts

@@ -75,6 +75,12 @@ export type PatchOptions = {
   // The include capability this document evaluates under
   // (G5, docs/trust.md); vet's precedent.
   trust?: TrustOptions
+  // The extensions an include additionally reads as text (the CLI's
+  // --text-ext). It rides WITH the capability, never beside it: this
+  // verb threaded the capability and not the extension, so `set`
+  // refused an include -- and wrote nothing -- under a flag the bare
+  // command honoured.
+  textExt?: string[]
 }
 
 
@@ -578,6 +584,7 @@ export function patch(
   // the caller, "which file" is the whole question.
   const report: VetReport = vet(entrySrc, overlay, {
     trust: options.trust,
+    textExt: options.textExt,
     schemaPath: options.entryPath,
     dataPath: options.overlayPath,
     schemaUrl: options.entryPath,

package/src/query.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // THE QUERY SURFACE (G7 phase 1,
 // docs/capability-review/g7-machine-access.md): select one node of an
@@ -56,6 +57,11 @@ export type QueryOptions = {
   // extension -- but reading is enough.) A server passes
   // `{include:'none'}`.
   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[]
 }
 
 export type QueryReport = {
@@ -271,8 +277,7 @@ export function get(
   const options = opts ?? {}
   const view: QueryView = options.view ?? 'json'
 
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == options.path ? undefined : { path: options.path }
   const root: any = aontu.unify(src, parseOpts, ctx)
@@ -336,8 +341,7 @@ export type WhyReport = {
 export function why(
   src: string, path: string, opts?: QueryOptions): WhyReport {
   const options = opts ?? {}
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const prov = new Provenance()
   const ctx = aontu.ctx({ collect: true, prov })
   const parseOpts = null == options.path ? undefined : { path: options.path }

package/src/reach.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // REACHABILITY OVER THE LINK GRAPH (the review's finding J,
 // use-cases/REVIEW.md): "ship a transitive `reaches(a, b)` check verb".
@@ -60,6 +61,11 @@ export type ReachOptions = {
   // The include capability this document evaluates under (G5,
   // docs/trust.md).
   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[]
   // Follow only edges under this relation. Absent means follow every
   // edge, which is the whole graph and the commoner question.
   relation?: string
@@ -124,8 +130,7 @@ export function reachCheck(
   src: string, from: string, to: string, opts?: ReachOptions
 ): ReachReport {
   const options = opts ?? {}
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == options.path ? undefined : { path: options.path }
   const root: any = aontu.unify(src, parseOpts, ctx)

package/src/relation.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // RELATION GRAPH VERDICTS (RELATIONS.0.md §3.3, replacing the G4
 // phase 5 magic-key pass): acyclicity and inverse consistency over
@@ -70,6 +71,11 @@ export type RelationOptions = {
   // docs/trust.md). vet's precedent: the verb passes the profile the
   // caller asked for, and an absent option means today's default.
   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[]
 }
 
 
@@ -248,8 +254,7 @@ export function relationErrors(ctx: any, root: any): void {
 export function relationCheck(
   src: string, opts?: RelationOptions): RelationReport {
   const options = opts ?? {}
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == options.path ? undefined : { path: options.path }
   const root: any = aontu.unify(src, parseOpts, ctx)

package/src/sigdecl.ts

@@ -6,6 +6,6 @@
 // this copy is identical with the shared file.
 
 const SIGDECL: string =
-"# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number) : string\nlower(s: string|number) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t?: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\njoin(d: map|list, sep?: string) : string\n"
+"# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number) : string\nlower(s: string|number) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t?: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\njoin(d: map|list, sep?: string) : string\nesc(s: string, variant?: string) : string\nusc(s: string, variant?: string) : string\nrep(s: string, text p: string, text sub: string) : string\nsplit(s: string, sep: string|constraint) : list\nemit(s: map|list, template t: map|list) : list\n"
 
 export { SIGDECL }