aontu 0.61.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"
-          / %s"each" / %s"emit" / %s"esc" / %s"filter" / %s"form" / %s"greatest"
+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"
-  | "each" | "emit" | "esc" | "filter" | "form" | "greatest"
+    "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"
-    | "each" | "emit" | "esc" | "filter" | "form" | "greatest"
+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|form|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.61.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/skill/SKILL.md

@@ -19,6 +19,8 @@ Start here:
 
 - Every JSON document is an aontu document. Write JSON, then add
   what JSON cannot say.
+- [`tasks.md`](tasks.md) — the verb for a job, indexed by the word
+  you arrived with (ontology, schema, validate, model).
 - [`grammar-card.md`](grammar-card.md) — the whole surface on one
   page.
 - [`examples.md`](examples.md) — the JSON-superset ladder: plain
@@ -33,5 +35,11 @@ aontu vet schema.aon data.aon   # does this data satisfy that truth?
 aontu get $.a.b file.aon        # what does it say at a path?
 aontu why $.a.b file.aon        # why does that value hold?
 aontu set $.a.b=1 --entry file.aon --overlay over.aon
+aontu allow --role dev roles.aon $.a.b   # may this role change that subtree?
 aontu hash file.aon             # a pin that survives reformatting
 ```
+
+These four files also ship INSIDE the command, so they answer with no
+network and no checkout: `aontu help` lists the topics, `aontu help
+language` is the grammar card, and `aontu explain <code>` says what one
+refusal means.

package/skill/init/check.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+# check.sh --- the four questions to ask of a model. Run it after
+# every edit to model.aon or data.aon.
+#
+# `aontu help tasks` maps a job to a verb; `aontu explain <code>` says
+# what a refusal means; `aontu help language` is the whole grammar on
+# one page. None of them needs a network.
+set -eu
+
+AONTU="${AONTU:-aontu}"
+cd "$(dirname "$0")"
+
+# 1. Does the data satisfy the truth -- and did the check examine
+#    anything? --strict-coverage exits 1 on a check that constrained no
+#    value, which is the failure a passing gate hides.
+$AONTU vet --strict-coverage model.aon data.aon
+
+# 2. What does it say at a path?
+$AONTU get '$.entity.planet.table' data.aon
+
+# 3. Why does it say that? Every contribution, with the line it is on.
+$AONTU why '$.entity.planet.table' data.aon
+
+# 4. A pin for the truth: it survives reformatting and moves on any
+#    change of meaning.
+$AONTU hash model.aon
+
+echo "ok --- model.aon and data.aon agree"

package/skill/init/data.aon

@@ -0,0 +1,12 @@
+# data.aon --- an instance of the truth in model.aon. Edit it and run
+# check.sh: every change is checked against the model, and a change the
+# model refuses is named with the line it is on.
+entity: {
+  planet: {
+    table: "planets"
+    fields: {
+      name: { type: "string", required: true }
+      diameter: { type: "integer" }
+    }
+  }
+}

package/skill/init/model.aon

@@ -0,0 +1,19 @@
+# model.aon --- the truth. `aontu vet model.aon data.aon` asks whether
+# a document satisfies it.
+#
+# `&:` is the construct to learn first: it meets EVERY key of the map
+# it sits in, so one statement constrains every entity. A quoted "*" is
+# not a wildcard -- it is a key named `*`, it meets nothing, and a
+# schema written that way reports `valid` over data that violates it.
+# `aontu vet --strict-coverage` refuses to pass such a check.
+entity: {
+  &: {
+    table: string & re("^[a-z][a-z0-9_]*$")
+    fields: {
+      &: {
+        type: "string" | "integer" | "boolean"
+        required: *false | boolean
+      }
+    }
+  }
+}

package/skill/tasks.md

@@ -0,0 +1,151 @@
+# What do you want to do?
+
+The verb for a job, found by the word you arrived with. aontu's own
+vocabulary is on the right; yours is probably on the left.
+
+## Start from a document that works
+
+Nothing written yet? Do not invent the first document, edit one:
+
+```
+aontu init            # into the working directory
+aontu init model/     # or into a named one
+sh check.sh           # the four questions, on what was just written
+```
+
+`init` writes `model.aon` (an entity map constrained with `&:`),
+`data.aon` (an instance of it that holds) and `check.sh` (the four
+checks to run after every edit). It never overwrites: if any
+of the three already stands there, it refuses and writes none of them.
+
+## Describe a domain
+
+An **ontology**, a **schema**, a **data model**, a **contract** — in
+aontu these are all one thing: a document. Write the entities as a
+**map keyed by name**, and say what every entry must satisfy with the
+`&:` template:
+
+```
+entity: {
+  &: {
+    table:  string
+    fields: { &: { type: string, required: *false | boolean } }
+  }
+  planet: { table: "planets", fields: { name: { type: "string" } } }
+  moon:   { table: "moons",   fields: { name: { type: "string" } } }
+}
+```
+
+`&:` is the construct to reach for first, and the one most easily
+missed. It meets **every** key of the map it sits in. A quoted `"*"`
+is not a wildcard — it is a key named `*`, and a schema written that
+way constrains nothing while still reporting `valid`.
+
+Prefer a named map to a list unless the order is a fact (a migration
+sequence, a rule table tried in order). A key is an address, a name
+other parts can refer to, and a diff that shows one insertion instead
+of every following element renumbered.
+
+## Check data against a model
+
+```
+aontu vet model.aon data.aon
+```
+
+Exit `0` valid, `1` a contradiction, `3` incomplete (nothing
+contradicts, but the model is not yet satisfied), `4` the model does
+not stand up on its own. `--format json` for the machine-readable
+report, `--closed` to refuse keys the model does not declare,
+`--max-errors <n>` to cap the list.
+
+**Make the check prove it checked something.** A check that examined
+nothing answers exactly like one that passed:
+
+```
+aontu vet --coverage model.aon data.aon         # what did it examine?
+aontu vet --strict-coverage model.aon data.aon  # exit 1 if nothing
+```
+
+`--coverage` reports how many data leaves a declaration constrained,
+the data paths none did, and the declarations no data met.
+`--strict-coverage` exits 1 when the answer is nothing. The usual
+cause is the `"*"` mistake above: reach for `&:`.
+
+## Check the model is coherent with itself
+
+```
+aontu relations model.aon        # declared entity edges: targets resolve, no cycles
+aontu reaches planet moon model.aon   # does one entity reach another, at any remove?
+aontu trim --check model.aon     # entries whose removal changes nothing
+```
+
+## Check code against a model
+
+```
+aontu render --check src/ --profile go.aon model.aon
+```
+
+`render` writes code from the model; `--check` writes nothing and
+lists what on disk differs from what the model implies. That is the
+gate: the model is the truth, the code is the claim, and drift is a
+finding. `--coverage` reports the other direction — model paths no
+output consumed, and rendered declarations no rule produced.
+
+## Ask what a model says, and why
+
+```
+aontu get  $.entity.planet.table model.aon
+aontu why  $.entity.planet.table model.aon
+aontu get  $.entity --keys       model.aon
+aontu get  $.entity --types      model.aon
+```
+
+`why` names **every** contribution to a value, with the file and line
+each was written on. It is the first thing to run when a value is not
+what you expected, and the second thing to run when `vet` refuses.
+
+## Change a value without editing the file
+
+```
+aontu set '$.entity.planet.table=planet_v2' --entry model.aon --overlay local.aon
+```
+
+The change is checked before it is written; a change that contradicts
+a pinned value is refused, and the file is left alone.
+
+## Gate a change to the model itself
+
+```
+aontu subsume old.aon new.aon              # does the general admit every specific?
+aontu breaking --against git#HEAD~1 model.aon
+aontu hash model.aon                       # a pin that survives reformatting
+```
+
+## Hand a model to another agent
+
+```
+aontu agentsmd --write AGENTS.md model.aon
+```
+
+Splices a derived stanza — the pin, the root keys, the shape, and the
+commands spelled with paths that exist — between two markers, and
+leaves the rest of the file alone. Re-run it in the commit that
+changes the model.
+
+## When something refuses
+
+Read the code in the brackets, then look it up:
+
+```
+aontu explain no_scalar_unify
+```
+
+Every finding carries a `code`, a `class`, a `path` and the **two
+sites** that disagree — the value and the constraint it failed, each
+with its file and line. The class says what kind of answer it is:
+`conflict` (two things cannot both hold), `incomplete` (nothing is
+wrong yet, something is missing), `parse`, `reference`, `budget`.
+
+Full index: [`error-codes.md`](error-codes.md). The language on one
+page: [`grammar-card.md`](grammar-card.md). The worked ladder from
+plain JSON upward: [`examples.md`](examples.md).

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,6 +24,7 @@ export type AgentsMdReport = {
 }
 
 export type AgentsMdOptions = {
+  depth?: number
   // The name the stanza should call the document. The engine never
   // reads a file; the CLI passes what the author typed.
   name?: string
@@ -42,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[]
 }
 
@@ -64,14 +52,10 @@ 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: 2, path: options.path, ...includeOpts(options) })
+  const shape = get(src, '$', {
+    view: 'types', depth: options.depth ?? 2,
+    path: options.path, ...includeOpts(options),
+  })
 
   // 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.
@@ -107,6 +91,9 @@ export function agentsMd(
     '# change it without editing it',
     'aontu set ' + example + '=<value> --entry ' + name +
     ' --overlay overlay.aon',
+    '',
+    '# the language itself, offline: the whole grammar on one page',
+    'aontu help language',
     '```',
     '',
     'Regenerate this section with `aontu agentsmd ' + name + '`.',
@@ -117,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)
@@ -130,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'