aontu 0.68.0 → 0.69.0

package/src/alias.ts

@@ -3,8 +3,208 @@
 
 import type { Val } from './type'
 
+import { makeNilErr } from './err'
+
 import { cmpCodePoint } from './keyorder'
 import { spreadSnapKey } from './val/MapVal'
+import { ALIAS_NAME, aliasSetItems } from './aliasname'
+
+
+const ALIAS_DECL_RE = new RegExp('^(' + ALIAS_NAME + ')[ \\t]*=(?!=)')
+
+// Whether the head IS a set is aliasSetItems's answer, not the shape's.
+const ALIAS_TAKE_RE = /^(\{[^}]*\})[ \t]*=[ \t]*@[ \t]*"([^"]*)"/
+
+
+type AliasBinding = {
+  name: string
+  row: number
+  col: number
+  decl: string
+  from: string    // the include a destructure took it from, '' if local
+}
+
+
+// THE NAMES A FILE BINDS, from its TEXT rather than its tree: an editor
+// asks while the document is half-written and would not parse.
+function aliasScope(src: string): AliasBinding[] {
+  const out: AliasBinding[] = []
+  const lines = src.split('\n')
+
+  for (let li = 0; li < lines.length; li++) {
+    const line = lines[li]
+    const lead = line.length - line.replace(/^[ \t]+/, '').length
+    const rest = line.substring(lead)
+    const decl = line.trim()
+
+    const dm = ALIAS_DECL_RE.exec(rest)
+    if (null != dm) {
+      out.push({ name: dm[1], row: li + 1, col: lead + 1, decl, from: '' })
+      continue
+    }
+
+    const tm = ALIAS_TAKE_RE.exec(rest)
+    const binds = null == tm ? undefined : aliasSetItems(tm[1])
+    if (null == tm || undefined === binds) {
+      continue
+    }
+
+    // The column is each item's own, so a set jumps to the name asked
+    // for rather than to the pattern.
+    let at = lead
+    for (const b of binds) {
+      at = line.indexOf(b.local, at)
+      out.push({ name: b.local, row: li + 1, col: at + 1, decl, from: tm[2] })
+      at += b.local.length
+    }
+  }
+
+  return out
+}
+
+
+// EVERY ALIAS REFERENCE NAMES A DECLARED NAME, whether or not anything
+// reaches it. Resolution is lazy, so a reference inside a template that
+// nothing instantiates is never tried and a misspelling compiles clean.
+// Whether a NAME is declared does not depend on what the tree holds, so
+// it is answered here instead. See docs/design/ALIASES.0.md
+function aliasErrors(ctx: any, root: Val): void {
+  if (true !== (root as any).isMap) {
+    return
+  }
+  const declared = new Set<string>((root as any).aliasKeys)
+  const seen = new Set<Val>()
+
+  const visit = (v: any): void => {
+    if (null == v || true !== v.isVal || seen.has(v)) {
+      return
+    }
+    seen.add(v)
+
+    if (true === v.isRef) {
+      const key: string | undefined = v.aliasKey
+      if (undefined !== key && !declared.has(key)) {
+        ctx.adderr(makeNilErr(ctx, 'no_path', v, undefined, 'resolve'))
+      }
+      return
+    }
+
+    if (true === v.isMap) {
+      for (const k of Object.keys(v.peg)) {
+        visit(v.peg[k])
+      }
+    }
+    else if (Array.isArray(v.peg)) {
+      for (const e of v.peg) {
+        visit(e)
+      }
+    }
+    else if (null != v.peg && true === v.peg.isVal) {
+      visit(v.peg)
+    }
+
+    if ((true === v.isMap || true === v.isList) && null != v.spread.cj) {
+      visit(v.spread.cj)
+    }
+  }
+
+  visit(root)
+} /* node:coverage ignore next 3 */
+
+
+// T-1 (ALIASES.0.md sections 7 and 9). Expansion TERMINATES -- no
+// parameters, no recursion, a finite name set -- but a name that names
+// names expands to the product of what they hold. The budget is on
+// EXPANDED SIZE and charged here, ahead of evaluation.
+function aliasBudget(ctx: any, root: Val): Val | undefined {
+  // A DOCUMENT THAT INCLUDES parses to a conjunct, not a map: the
+  // deferred terms are where an included file's names arrive, so the
+  // budget must see all of them, not only the first.
+  const maps: any[] = []
+  const gather = (v: any): void => {
+    if (true === v?.isMap) {
+      maps.push(v)
+    }
+    else if (true === v?.isConjunct && Array.isArray(v.peg)) {
+      for (const t of v.peg) {
+        gather(t)
+      }
+    }
+  }
+  gather(root)
+  if (0 === maps.length) {
+    return undefined
+  }
+  const decl: Record<string, Val> = {}
+  for (const m of maps) {
+    for (const k of m.aliasKeys) {
+      decl[k] = m.peg[k]
+    }
+  }
+  const limit: number = ctx.budget.alias
+  const size = new Map<string, number>()
+  const open = new Set<string>()
+  let over: Val | undefined = undefined
+
+  // A cycle is refused at resolution, which has not run yet, so a name
+  // already open costs nothing here rather than looping.
+  const nameSize = (key: string): number => {
+    if (size.has(key)) {
+      return size.get(key) as number
+    }
+    if (open.has(key) || !(key in decl)) {
+      return 0
+    }
+    open.add(key)
+    const n = valSize(decl[key])
+    open.delete(key)
+    size.set(key, n)
+    return n
+  }
+
+  const valSize = (v: any): number => {
+    if (true === v.isRef) {
+      const key: string | undefined = v.aliasKey
+      return undefined === key ? 1 : 1 + nameSize(key)
+    }
+    let n = 1
+    if (true === v.isMap) {
+      for (const k of Object.keys(v.peg)) {
+        n += valSize(v.peg[k])
+      }
+    }
+    else if (Array.isArray(v.peg)) {
+      for (const e of v.peg) {
+        n += valSize(e)
+      }
+    }
+    else if (null != v.peg && true === v.peg.isVal) {
+      n += valSize(v.peg)
+    }
+    if ((true === v.isMap || true === v.isList) && null != v.spread?.cj) {
+      n += valSize(v.spread.cj)
+    }
+    return limit < n ? limit + 1 : n
+  }
+
+  let total = 0
+  for (const m of maps) {
+    for (const k of Object.keys(m.peg)) {
+      if (!(k in decl)) {
+        total += valSize(m.peg[k])
+        if (limit < total) {
+          break
+        }
+      }
+    }
+  }
+
+  if (limit < total) {
+    over = makeNilErr(ctx, 'alias_budget', root, undefined, 'resolve')
+    ; (over as any).details = { budget: '' + limit }
+  }
+  return over
+}
 
 
 function expandAliases(root: Val, snapmap: Map<string, Val>): void {
@@ -21,21 +221,21 @@ function expandAliases(root: Val, snapmap: Map<string, Val>): void {
     seen.add(v)
 
     if (true === v.isRef) {
-      const name: string | undefined = v.aliasName
-      if (undefined === name) {
+      const key: string | undefined = v.aliasKey
+      if (undefined === key) {
         return
       }
       v.expansion = undefined
-      if (stack.includes(name)) {
+      if (stack.includes(key)) {
         return
       }
       const target: Val | undefined =
-        snapmap.get(spreadSnapKey(v)) ?? (root as any).peg[name]
+        snapmap.get(spreadSnapKey(v)) ?? (root as any).peg[key]
       if (null == target) {
         return
       }
       v.expansion = target
-      visit(target, [...stack, name])
+      visit(target, [...stack, key])
       return
     }
 
@@ -65,9 +265,17 @@ function expandAliases(root: Val, snapmap: Map<string, Val>): void {
   }
 
   visit(root, [])
-} /* node:coverage ignore next 5 */
+} /* node:coverage ignore next 13 */
 
 
 export {
+  aliasBudget,
+  aliasErrors,
+  aliasScope,
   expandAliases,
 }
+
+
+export type {
+  AliasBinding,
+}

package/src/aliasname.ts

@@ -0,0 +1,95 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+// ONE PATTERN FOR THE ALIAS NAME. See docs/design/ALIASES.0.md
+const ALIAS_NAME = '%[A-Za-z_][A-Za-z0-9_]*(?:-[A-Za-z0-9_]+)*'
+
+const ALIAS_RE = new RegExp('^' + ALIAS_NAME)
+
+const ALIAS_NAME_RE = new RegExp('^' + ALIAS_NAME + '$')
+
+// What `export` takes and a destructure heads with: `{%}` binds none.
+const ALIAS_ITEM =
+  '(' + ALIAS_NAME + ')(?:[ \\t]*:[ \\t]*(' + ALIAS_NAME + '))?'
+const ALIAS_SET =
+  '\\{[ \\t]*(?:%|' + ALIAS_ITEM +
+  '(?:[ \\t]*,[ \\t]*' + ALIAS_ITEM + ')*)[ \\t]*\\}'
+const ALIAS_SET_RE = new RegExp('^' + ALIAS_SET + '$')
+const ALIAS_ITEMS_RE = new RegExp(ALIAS_ITEM, 'g')
+
+// THE SHORTHAND: `{ %a %b }` is `{ a: %a, b: %b }`. Names only.
+const ALIAS_SHORTHAND =
+  '\\{\\s*' + ALIAS_NAME +
+  '(?:(?:\\s*,\\s*|\\s+)' + ALIAS_NAME + ')*\\s*\\}'
+const ALIAS_SHORTHAND_RE = new RegExp('^' + ALIAS_SHORTHAND)
+
+// A key carries the url of the file that declared the name.
+const ALIAS_SCOPE = '@'
+
+// THE ENGINE'S KEY NAMESPACE, refused to a source key.
+const RESERVED_KEY_PREFIX = '\u0000aontu_'
+
+// `export(...)` is read as a pair, its value under a key that changes
+// with each declaration, so a field of that name is the document's.
+const EXPORT_DECL_NAME = 'export'
+const EXPORT_HOLD_KEY = RESERVED_KEY_PREFIX + 'export@'
+let EXPORT_SEQ = 0
+
+function exportHoldKey(): string {
+  return EXPORT_HOLD_KEY + (++EXPORT_SEQ)
+}
+
+function isExportHoldKey(val: unknown): boolean {
+  return 'string' === typeof val && val.startsWith(EXPORT_HOLD_KEY)
+}
+
+
+type AliasBind = { local: string, remote: string }
+
+
+function aliasScopedKey(name: string, url: string): string {
+  return name + ALIAS_SCOPE + url
+}
+
+
+function aliasBareName(key: string): string {
+  const at = key.indexOf(ALIAS_SCOPE)
+  return -1 === at ? key : key.substring(0, at)
+}
+
+
+function aliasPathSegment(seg: string): string {
+  const name = aliasBareName(seg)
+  return ALIAS_NAME_RE.test(name) ? name : seg
+}
+
+
+// Undefined where the text is not a set; the wildcard answers EMPTY.
+function aliasSetItems(text: string): AliasBind[] | undefined {
+  if (!ALIAS_SET_RE.test(text)) {
+    return undefined
+  }
+  return Array.from(text.matchAll(ALIAS_ITEMS_RE),
+    (m) => ({ local: m[1], remote: m[2] ?? m[1] }))
+} /* node:coverage ignore next 22 */
+
+
+export {
+  ALIAS_NAME,
+  ALIAS_RE,
+  ALIAS_NAME_RE,
+  ALIAS_SET,
+  ALIAS_SHORTHAND_RE,
+  EXPORT_DECL_NAME,
+  RESERVED_KEY_PREFIX,
+  exportHoldKey,
+  isExportHoldKey,
+  aliasScopedKey,
+  aliasBareName,
+  aliasPathSegment,
+  aliasSetItems,
+}
+
+
+export type {
+  AliasBind,
+}

package/src/aontu.ts

@@ -28,6 +28,7 @@ export type {
 } from './allow'
 import { graphOf } from './graph'
 import { relationCheck, relationErrors } from './relation'
+import { aliasBudget, aliasErrors } from './alias'
 import { view, viewSet, viewTree } from './view'
 import { loadProfile } from './profile'
 import { desugarTemplate, resugarTemplate, markerFor } from './template'
@@ -35,7 +36,7 @@ import { format, unifiedDiff } from './format'
 export type { LintFinding, FormatReport, FormatOptions } from './format'
 
 
-const VERSION = '0.68.0'
+const VERSION = '0.69.0'
 
 
 function genQuiet(val: any, aontu: Aontu): any {
@@ -153,16 +154,28 @@ class Aontu {
     }
 
     if (null != pval && 0 === errs.length) {
-      let uni = new Unify(pval, this.lang, ac, src)
-      errs = uni.err
-
-      // Never nullish: Unify.res starts as the root Val, unite() returns a
-      // Val on every arm, and its catch-all turns a throwing node into an
-      // 'internal' NilVal.
-      out = uni.res
+      // T-1: EXPANDED SIZE IS CHARGED BEFORE EVALUATION, here rather
+      // than in generate, because an editor unifies on each keystroke
+      // and a document too big to evaluate must be turned away there
+      // too.
+      const over = aliasBudget(ac as any, pval)
+
+      if (undefined !== over) {
+        out = over
+        errs = [over]
+      }
+      else {
+        let uni = new Unify(pval, this.lang, ac, src)
+        errs = uni.err
+
+        // Never nullish: Unify.res starts as the root Val, unite() returns a
+        // Val on every arm, and its catch-all turns a throwing node into an
+        // 'internal' NilVal.
+        out = uni.res
+        out.graph = graphOf(out)
+      }
 
       out.deps = pval.deps
-      out.graph = graphOf(out)
       out.err = errs
       ac.root = out
     }
@@ -193,6 +206,7 @@ class Aontu {
               : uval.gen(ac as any)
 
           if (!uval.isNil && 0 === ac.err.length) {
+            aliasErrors(ac as any, uval)
             relationErrors(ac as any, uval)
             if (0 < ac.err.length) {
               out = undefined

package/src/aontumodel.ts

@@ -10,7 +10,7 @@ const AONTU_SCHEME = 'aontu:'
 const AONTU_SOURCES: Record<string, string> = {
   "aontu:lang/markdown": "# aontu:lang/markdown --- THE MARKDOWN PROFILE. The text profile plus\n# markdown's own two: the HTML comment form, and the template marker\n# its files carry.\n\n@\"aontu:profile\"\n\naontu: Lang: lang: \"markdown\"\naontu: Lang: indent: { unit:\" \" width:2 }\naontu: Lang: comment: block: { open:\"<!--\" close:\"-->\" }\naontu: Lang: template: { marker:\"<!---\" ext: [\"md\" \"markdown\"] }\n",
   "aontu:lang/text": "# aontu:lang/text --- THE TEXT PROFILE. Indentation and nothing else.\n# Every language without one of its own is read under it.\n\n@\"aontu:profile\"\n\naontu: Lang: { lang:\"text\" indent: { unit:\" \" width:2 } }\n",
-  "aontu:profile": "# aontu:profile --- THE PROFILE VOCABULARY. A language declared as\n# data: its name, its indentation, its comment forms and the marker its\n# generators carry. `aontu template` and `aontu fmt` read one through\n# --profile. EXPERIMENTAL, versioned by canon-hash later.\n\n%comment = close({ open?:string prefix?:string close?:string })\n\n%profile = close({\n  lang: string & length(min(1))\n  indent: close({\n    unit: *\" \"|string & length(min(1))\n    width: *2|integer & min(0) & max(16)\n  })\n  comment?: close({ line?:%comment block?:%comment doc?:%comment })\n  template?: close({\n    marker: string & length(min(1))\n    close?: string & length(min(1))\n    ext?: [&: string & re(\"^[A-Za-z0-9_+-]+$\")]\n  })\n})\n\n# Profile names the schema; Lang is where one lands. type() so naming\n# the schema neither generates it nor asks a document to fill it.\naontu: { Profile:type(%profile) Lang:%profile }\n",
+  "aontu:profile": "# aontu:profile --- THE PROFILE VOCABULARY. A language declared as\n# data: its name, its indentation, its comment forms and the marker its\n# generators carry. `aontu template` and `aontu fmt` read one through\n# --profile. EXPERIMENTAL, versioned by canon-hash later.\n\n%comment = close({ open?:string prefix?:string close?:string })\n\n%profile = close({\n  lang: string & length(min(1))\n  indent: close({\n    unit: *\" \"|string & length(min(1))\n    width: *2|integer & min(0) & max(16)\n  })\n  comment?: close({ line?:%comment block?:%comment doc?:%comment })\n  template?: close({\n    marker: string & length(min(1))\n    close?: string & length(min(1))\n    ext?: [&: string & re(\"^[A-Za-z0-9_+-]+$\")]\n  })\n})\n\n# Published: a name crosses only to a document that asks for it.\nexport({ %profile, %comment })\n\n# Profile names the schema; Lang is where one lands. type() so naming\n# the schema neither generates it nor asks a document to fill it.\naontu: { Profile:type(%profile) Lang:%profile }\n",
   "aontu:system": "# aontu:system --- the SYSTEM VOCABULARY. EXPERIMENTAL until the\n# distribution layer can version it by canon-hash.\n\naontu: System: {\n  Port: type({ direction: *in|out|inout protocol?:string })\n\n  Component: type({ ports?: { &: $.aontu.System.Port } })\n\n  # Written out rather than Component & { kind: service }: a reference\n  # to a type()-marked member does not survive the include.\n  Service: type({ kind:service ports?: { &: $.aontu.System.Port } })\n\n  # A grammar, not re(): the identifier shape is a quantified group\n  # holding a quantifier, which re() refuses. hide()n so a schema's\n  # grammar does not generate into the document it checks.\n  semverPreRelease: hide(\n    abnf(\n      `pre-release = pre-release-id *( \".\" pre-release-id )\npre-release-id = \"0\" [ *digit alnum-tail ]\n  / positive-digit *digit [ alnum-tail ] / alnum-tail\nalnum-tail = non-digit *id-char\nid-char = digit / non-digit\nnon-digit = letter / \"-\"\ndigit = \"0\" / positive-digit\npositive-digit = %x31-39\nletter = %x41-5A / %x61-7A\n`\n    )\n  )\n  semverBuild: hide(\n    abnf(\n      `build = build-id *( \".\" build-id )\nbuild-id = 1*id-char\nid-char = digit / non-digit\nnon-digit = letter / \"-\"\ndigit = \"0\" / positive-digit\npositive-digit = %x31-39\nletter = %x41-5A / %x61-7A\n`\n    )\n  )\n\n  # major minor patch pre-release build, tail defaulted.\n  Semver: type(\n    [\n      integer & min(0)\n      *0|(integer & min(0))\n      *0|(integer & min(0))\n      *\"\"|parse($.aontu.System.semverPreRelease)\n      *\"\"|parse($.aontu.System.semverBuild)\n    ] & length(5)\n  )\n}\n",
   "aontu:view": "# aontu:view --- the FIGURE VOCABULARY. EXPERIMENTAL until the\n# distribution layer can version it by canon-hash.\n\naontu: View: Figure: type({\n  kind: doc|lattice|tree|matrix|graph|layer|sets|layers\n    | ladder\n  out: string\n\n  # Every kind.\n  as?: text|mermaid|dot|er|svg\n  at?: string\n  maxRows?: integer & min(0)\n\n  # doc.\n  depth?: integer & min(0)\n\n  # tree, matrix, layer, graph.\n  relation?: string\n  relations?: [&: string]\n  roots?: [&: string]\n\n  # matrix.\n  order?: canon|partition\n  closure?: boolean\n\n  # graph, layer.\n  groupBy?: string\n  label?: string\n  layers?: [&: string]\n  edges?: upward|all|none\n\n  # sets, layers.\n  sets?: string\n  member?: string\n  universe?: string\n  minDegree?: integer & min(0)\n  maxCols?: integer & min(0)\n  minSize?: integer & min(0)\n})\n"
 }

package/src/ctx.ts

@@ -93,7 +93,9 @@ class AontuContext {
 
   _fixroot: any
 
-  budget: { passes: number, revisits: number, depth: number }
+  budget: {
+    passes: number, revisits: number, depth: number, alias: number
+  }
 
   // The include manifest sink (G5, docs/trust.md): every include the
   // resolver reads is recorded here as { path, capability }, and
@@ -153,6 +155,7 @@ class AontuContext {
       passes: budget.passes ?? 9,
       revisits: 999,
       depth: budget.depth ?? 1000,
+      alias: budget.alias ?? 1000000,
     }
   }
 

package/src/err.ts

@@ -1,6 +1,7 @@
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 
 
+import { aliasPathSegment } from './aliasname'
 import { sep } from 'node:path'
 
 import { util } from '@tabnas/jsonic'
@@ -71,7 +72,10 @@ function descErr<NILS extends NilVal | NilVal[]>(
       let v1src = resolveSrc(v1, errctx)
       let v2src = resolveSrc(v2, errctx)
 
-      let path = ['$', ...err.path].filter((p: any) => null != p && '' !== p)
+      // A list index is a number here, and only a key can be an alias.
+      let path = ['$', ...err.path.map((p: any) =>
+        'string' === typeof p ? aliasPathSegment(p) : p)]
+        .filter((p: any) => null != p && '' !== p)
 
       // '$' is neither null nor '', so the filter always leaves it.
       let valpath = path.join('.')
@@ -125,6 +129,20 @@ function descErr<NILS extends NilVal | NilVal[]>(
           col: v2.site.col,
         })),
 
+        // A NAME IS WHERE THE VALUE ENTERED THIS PATH, which is not
+        // where it is written (ALIASES.0.md A-1).
+        ...[v1, v2].map((v: any) => null != v?.site?.via && errmsg({
+          color: { active: colorActive(), line: '\x1b[34m' },
+          txts: {
+            msg: 'Value arrived through ' + v.site.via.name,
+            site: ''
+          },
+          smsg: 'used ' + v.site.via.name + ' here',
+          file: resolveFile(v.site.via.url),
+          src: resolveSrc({ site: v.site.via } as any, errctx),
+          row: v.site.via.row,
+          col: v.site.via.col,
+        })),
 
       ]
         .filter((n: any) => null != n && false !== n)

package/src/format.ts

@@ -6,6 +6,7 @@ import { failureFinding } from './vet'
 import type { VetFinding } from './vet'
 import type { Resolver } from './type'
 import { desugarTemplate, resugarTemplate, templateOutputs } from './template'
+import { ALIAS_RE, EXPORT_DECL_NAME, isExportHoldKey } from './aliasname'
 
 
 const BUDGET = 80
@@ -303,6 +304,19 @@ class Reader {
       this.i += 2
       return { t: 'spread', value: this.value(), at }
     }
+    // `export({ %a })` is ONE declaration lexed as a pair.
+    if (isExportHoldKey(this.T[this.i].val) &&
+      EXPORT_DECL_NAME === this.T[this.i].src && this.atKey()) {
+      const text = EXPORT_DECL_NAME + '(' + this.T[this.i + 2].src + ')'
+      this.i += 3
+      return { t: 'atom', text, at }
+    }
+    if (this.atKey() && ALIAS_RE.test('' + this.T[this.i].src) &&
+      this.T[this.i].src === this.T[this.i + 2]?.src) {
+      const text = '' + this.T[this.i].src
+      this.i += 3
+      return { t: 'atom', text, at }
+    }
     if (this.atKey()) {
       const tok = this.T[this.i]
       const opt = '#QM' === this.name(1)

package/src/hints.ts

@@ -189,6 +189,8 @@ const hints: Record<string, string> = {
 
   elided_value: 'A key or element was written with no value after the colon. An\nelided value is a mistake in the source rather than a null: write\n`null` if that is what was meant, or supply the value.\n \nExamples:\n  a:null  -> null  # An explicit null, which is a value;\n  a:      -> nil   # ... but nothing at all is not;\n  a: b:1  -> {..}  # A colon chain is not an elision;\n  [1,]    -> [1]   # ... nor is a trailing comma.',
 
+  alias_budget: 'Alias expansion is bounded but not small: a name that names names\nexpands to the product of what they hold, so twenty shallow\ndeclarations reach a million nodes. The expanded size is counted\nbefore evaluation and refused over the budget ({budget} nodes), so\nthe document is turned away rather than run until memory is gone.\n \nExpansion terminates whatever the budget: an alias takes no\nparameters, a cycle is refused, and a file declares finitely many\nnames. The budget is about SIZE, not about termination.\n \nRaise it with trust.budget.alias where the document is trusted and\nthe machine can hold the result.',
+  reserved_key: 'The \\u0000aontu_ key prefix belongs to the engine. A document\'s key\norder, its spreads and its alias declarations are held under keys in\nthat namespace, so a source key written there would land on one of\nthem. It is refused where it stands rather than silently replacing\nwhat the parser put there. No ordinary key needs the prefix: it\nbegins with a NUL, which only an escape can spell.\n \nExamples:\n  "\\u0000aontu_order": 1  -> nil   # The namespace is the engine\'s;\n  "aontu_order": 1        -> {..}  # ... without the NUL it is a key;\n  "___merge": 1           -> {..}  # ... and so is this.',
   alias_colon: 'An alias is declared with `=`: write `%name = value`. Until 0.57.0\nthe declaration was spelled with a colon, `%name: value`, and that\nform is refused rather than read as an ordinary key -- a document\nwritten for the old spelling fails here, at the declaration, instead\nof gaining a key named `%name` and a use that resolves to nothing.\n \nExamples:\n  %u8 = integer & min(0)  -> {..}  # Declares %u8, which a: %u8 uses;\n  %u8: integer            -> nil   # The form before 0.58.0, refused;\n  "%u8": 1                -> {..}  # A quoted key is an ordinary key.',
 
   bare_punct: 'A bare string holds letters, digits, `-` and `_`, and nothing else.\nThis one holds `{char}`, in `{text}`. Every other punctuation\ncharacter is either syntax or an error, never silently part of a\nstring: a value that needs one is written quoted, and a `>` or `<`\nthat was meant as a bound is written as min(x), max(x), above(x) or\nbelow(x).\n \nExamples:\n  a: team-payments  -> "team-payments"  # `-` and `_` are text;\n  a: 2026-09-05     -> "2026-09-05"     # ... digits included;\n  a: x=y            -> nil              # `=` is not;\n  a: "x=y"          -> "x=y"            # ... so quote it;\n  a: >10            -> nil              # Not an operator: write above(10).',
@@ -591,13 +593,40 @@ const hints: Record<string, string> = {
     '  listen: $.%port  -> nil  # Not a path segment.',
 
   'alias_not_toplevel':
-    'An alias declaration sits at the root of the document. A nested\n' +
-    '`x: { %a = 1 }` is refused because `%a` resolves from the root: the\n' +
-    'declaration would be erased from the output, being a declaration,\n' +
-    'and still unreachable by any reference, not being at the root.\n' +
-    'Where the declaration LANDS decides this, not where it was written,\n' +
-    'so an include spliced at the root may declare one and an include\n' +
-    'taken as a value may not.',
+    'An alias declaration written as a KEY sits at the root of the\n' +
+    'document. A nested `x: { %a = 1 }` is refused because `%a` resolves\n' +
+    'from the root: the declaration would be erased from the output,\n' +
+    'being a declaration, and still unreachable by any reference, not\n' +
+    'being at the root. Where the declaration LANDS decides this, not\n' +
+    'where it was written, so an include spliced at the root may declare\n' +
+    'one and an include taken as a value may not.\n' +
+    'To name a shape where it is used, write the declaration as a VALUE\n' +
+    'prefix instead: `x: %a = 1` is accepted at any depth, leaves the\n' +
+    'value alone, and declares `%a` for the document.',
+
+  'export_arg':
+    '`export` takes a SET OF ALIAS NAMES and nothing else: write\n' +
+    '`export({ %a, %b })`. A key already crosses a file boundary as a\n' +
+    'value, so a bare word names nothing `export` could publish, and a\n' +
+    'single name still stands in a set. The `{%}` wildcard is the\n' +
+    'importing side\'s: the publishing file chooses what it publishes.\n' +
+    ' \nExamples:\n' +
+    '  %u8 = integer\n' +
+    '  export({ %u8 })  -> published;\n' +
+    '  export({ u8 })   -> nil  # A key, not an alias;\n' +
+    '  export(%u8)      -> nil  # A set, even of one;\n' +
+    '  export({%})      -> nil  # The wildcard is the importer\'s.',
+
+  'import_not_exported':
+    'The file this name was asked of does not publish `{name}`. A name\n' +
+    'belongs to the file that declares it and crosses only where that\n' +
+    'file says so, which is what `export` is for: add the name to the\n' +
+    'other file\'s `export({ ... })`, or write the value in this one.\n' +
+    'The include still placed the file\'s values -- it is the NAME that\n' +
+    'did not cross.\n' +
+    ' \nExamples:\n' +
+    '  { %u8 } = @"types.aon"      -> bound, if types.aon exports %u8;\n' +
+    '  { %secret } = @"types.aon"  -> nil  # ... and refused if not.',
 
   'patch_assignment':
     'This is not a <path>=<value> assignment. The path is what stands\n' +
@@ -882,7 +911,11 @@ const codeClasses: Record<string, string> = {
   pref_implicit_bag: 'parse',
   alias_not_toplevel: 'parse',
   alias_in_path: 'parse',
+  alias_budget: 'budget',
+  reserved_key: 'parse',
   alias_colon: 'parse',
+  export_arg: 'parse',
+  import_not_exported: 'reference',
   bare_punct: 'parse',
   not_number: 'parse',
   negative: 'parse',