aontu 0.60.0 → 0.62.0

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

@@ -34,6 +34,12 @@ 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.
   name?: string
@@ -70,8 +76,10 @@ export function agentsMd(
   // 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 +115,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 + '`.',

package/src/allow.ts

@@ -0,0 +1,316 @@
+/* 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'
+import { anchorAt } from './vet'
+import type { VetFinding } from './vet'
+import { evalFailure, nearestKey, pathParts } from './query'
+import { includeOpts } from './utility'
+import type { IncludeOptions } from './utility'
+
+
+// Where the roles map lives when the caller does not say.
+export const ALLOW_AT = '$.roles'
+
+
+export type AllowVerdict = 'allowed' | 'refused' | 'error'
+
+
+// What decided one path: the entry that covers it, the entry that
+// intersects it, nothing at all, or a role the model does not declare.
+export type AllowReason = 'allow' | 'deny' | 'uncovered' | 'no_role'
+
+
+export type AllowDecision = {
+  path: string          // the asked path, normalised: `$.a.b`
+  allowed: boolean
+  reason: AllowReason
+  by?: string           // the deciding entry's path in the role model
+  pattern?: string      // that entry's text, as the author wrote it
+}
+
+
+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[]
+}
+
+
+export type AllowOptions = IncludeOptions & {
+  // Where the role model came from: relative loads resolve against
+  // its directory, and a finding's site names it.
+  path?: string
+  // The path of the roles map inside the model (default `$.roles`).
+  at?: string
+}
+
+
+// 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
+// subtree entries to allow, and optionally one to deny.
+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
+    ? '&: ' + ROLE_SHAPE
+    : keys.join(': ') + ': { &: ' + ROLE_SHAPE + ' }'
+}
+
+
+// `$.a.b` for a segment list, `$` for none: the spelling every report
+// uses for a path, whatever the caller wrote.
+function pathText(parts: string[]): string {
+  return '$' + (0 < parts.length ? '.' + parts.join('.') : '')
+}
+
+
+// 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 {
+    code,
+    class: 'reference',
+    severity: 'error',
+    path,
+    message,
+    sites: [],
+    ...(null == note ? {} : { note }),
+  }
+}
+
+
+type Entry = {
+  parts: string[]
+  text: string
+  by: string
+}
+
+
+// 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 } {
+  const entries: Entry[] = []
+  for (let i = 0; i < list.peg.length; i++) {
+    const el: any = list.peg[i]
+    const before = ctx.err.length
+    const text: string = true === el.isString ? el.peg : el.gen(ctx)
+    if (before < ctx.err.length) {
+      const err: any = ctx.err[before]
+      return { entries, finding: finding(err.why, `${by}.${i}`, err.msg) }
+    }
+    entries.push({ parts: pathParts(text), text, by: `${by}.${i}` })
+  }
+  return { entries }
+}
+
+
+// One segment of an entry against one segment of a path: `*` matches
+// any key, anything else matches itself.
+function segmentMatches(pattern: string, segment: string): boolean {
+  return '*' === pattern || pattern === segment
+}
+
+
+// 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++) {
+    if (!segmentMatches(entry[i], path[i])) {
+      return false
+    }
+  }
+  return true
+}
+
+
+// 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)
+}
+
+
+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 }
+    }
+  }
+  for (const a of allows) {
+    if (covers(a.parts, parts)) {
+      return { path, allowed: true, reason: 'allow', by: a.by, pattern: a.text }
+    }
+  }
+  return { path, allowed: false, reason: 'uncovered' }
+}
+
+
+function errorReport(role: string, f: VetFinding): AllowReport {
+  return { verdict: 'error', role, paths: [], findings: [f] }
+}
+
+
+// Evaluate the role model, select the role, and decide every path.
+export function allow(
+  src: string, role: string, paths: string[], opts?: AllowOptions,
+): AllowReport {
+  const options = opts ?? {}
+  const at = pathText(pathParts(options.at ?? ALLOW_AT))
+
+  const aontu = new Aontu(includeOpts(options))
+  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) {
+    return errorReport(role, evalFailure(ctx))
+  }
+  const root: any = aontu.unify(
+    new ConjunctVal({ peg: [model, shape] }, ctx), undefined, ctx)
+  if (0 < ctx.err.length || true === root.isNil) {
+    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)) {
+    const near = nearestKey(role, Object.keys(roles.peg))
+    return {
+      verdict: 'refused',
+      role,
+      paths: paths.map((p) => ({
+        path: pathText(pathParts(p)), allowed: false, reason: 'no_role',
+      })),
+      findings: [finding(
+        'no_path',
+        atRole,
+        `The role ${role} is not declared at ${at} in this document.`,
+        null == near ? undefined : `did you mean ${near}?`)],
+    }
+  }
+  const node: any = roles.peg[role]
+
+  const allows = readEntries(node.peg.allow, `${atRole}.allow`, ctx)
+  if (null != allows.finding) {
+    return errorReport(role, allows.finding)
+  }
+  const denies = readEntries(node.peg.deny, `${atRole}.deny`, ctx)
+  if (null != denies.finding) {
+    return errorReport(role, denies.finding)
+  }
+
+  const decisions = paths.map((p) => decide(p, allows.entries, denies.entries))
+
+  // Nothing asked is nothing allowed: a gate that answered `allowed`
+  // to an empty question would let a caller that dropped its
+  // arguments through.
+  const allowed = 0 < decisions.length && decisions.every((d) => d.allowed)
+
+  return {
+    verdict: allowed ? 'allowed' : 'refused',
+    role,
+    paths: decisions,
+    findings: [],
+  }
+}

package/src/aontu.ts

@@ -22,6 +22,10 @@ import { get, why } from './query'
 import { patch } from './patch'
 import { diff } from './diff'
 import { agentsMd } from './agentsmd'
+import { allow } from './allow'
+export type {
+  AllowDecision, AllowOptions, AllowReason, AllowReport, AllowVerdict,
+} from './allow'
 import { graphOf } from './graph'
 import { relationCheck, relationErrors } from './relation'
 import { view, viewSet, viewTree } from './view'
@@ -38,7 +42,7 @@ export type { LintFinding, FormatReport, FormatOptions } from './format'
 // 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.60.0'
+const VERSION = '0.62.0'
 
 
 // A module file's VALUE, as far as it goes. COLLECTED, not raised: a
@@ -475,6 +479,11 @@ export {
   patch,
   diff,
   agentsMd,
+
+  // The role gate (docs/design/ALLOW.0.md): may a role modify a
+  // subtree, by a role model that is itself an aontu document. The
+  // question an agent asks before `set`.
+  allow,
   graphOf,
   relationCheck,
   view,