aontu 0.59.0 → 0.61.0

package/src/format.ts

@@ -26,6 +26,7 @@ import { Aontu } from './aontu'
 import { failureFinding } from './vet'
 import type { VetFinding } from './vet'
 import type { Resolver } from './type'
+import { desugarTemplate, resugarTemplate, templateOutputs } from './template'
 
 
 // The packing budget (§3.1). It decides which of two legal spellings
@@ -46,6 +47,12 @@ export type FormatOptions = {
   // Report the style findings of §4 -- key case, repeated shapes --
   // beside the text. The formatter never acts on them.
   lint?: boolean
+  // THE SOURCE IS A GENERATOR, and this is its marker
+  // (docs/design/TEMPLATE.0.md; FMT.0.md §3.14). The file is desugared,
+  // formatted and resugared, so `text` is a template again -- the aontu
+  // in the agreed form, indented after the marker, and every line of
+  // output exactly where it was.
+  template?: string
 }
 
 // A style finding (§4): what the formatter points at and never
@@ -183,6 +190,10 @@ type Node = {
 
   // The source index of the node's first token: the lint's positions.
   at?: number
+
+  // The node begins a line of the target's own file (§3.14), so it has
+  // no one-line form and every container holding it opens.
+  held?: boolean
 }
 
 const BINARY: Record<string, boolean> = { '#E&': true, '#E|': true, '#E+': true }
@@ -608,7 +619,7 @@ function pairHead(node: Node, tight: boolean): string {
 // lines. `tight` is the inline form of a pair, `a:1`, used inside a
 // container; a statement's pair is `a: 1`.
 function inline(node: Node, tight: boolean): string | undefined {
-  if (undefined !== node.trail) {
+  if (undefined !== node.trail || node.held) {
     return undefined
   }
   switch (node.t) {
@@ -744,6 +755,15 @@ class Writer {
     return this.lines.slice(mark).concat([this.line]).map(rtrim).join('\n') + '\n'
   }
 
+  // A blank line above the line at an index: the gap of §3.8, opened
+  // once the statement below it turns out to be a tree. Never at the
+  // top of the page, and never a second time.
+  gap(at: number): void {
+    if (0 < at && '' !== this.lines[at - 1]) {
+      this.lines.splice(at, 0, '')
+    }
+  }
+
   // The lines since a mark replaced by a text: the spelling before,
   // where a rewrite did not pass its check.
   replace(mark: number, text: string): void {
@@ -776,29 +796,57 @@ function rtrim(s: string): string {
 // body of a plain map that is itself the value of a statement) a pair
 // is laid out by §3.4, which may repeat its key; anywhere else -- a
 // list, an operand, an argument -- by §3.5 alone.
-function emitBody(w: Writer, body: Node[], indent: number, stmt: Stmt | undefined): void {
+function emitBody(
+  w: Writer, body: Node[], indent: number, stmt: Stmt | undefined, root?: boolean
+): void {
   let pending = false
   let count = 0
+  // Where the run being written begins: a statement, with the comments
+  // standing directly above it, so that the gap below opens ABOVE the
+  // comments rather than between them and what they describe. A blank
+  // line ends a run -- comments across a gap belong to what is above.
+  let head = 0
+  let noted = false
   for (const node of body) {
     if ('blank' === node.t) {
       pending = 0 < count
       continue
     }
+    const gapped = pending
     w.open(indent, pending)
+    if (gapped || !noted) {
+      head = w.mark()
+    }
     pending = false
     count++
     if ('comment' === node.t) {
+      noted = true
       w.text(node.text!)
       continue
     }
+    noted = false
+    const from = w.mark()
     if (undefined !== stmt && 'pair' === node.t) {
       emitStatement(w, node, indent, stmt, '')
-      continue
     }
-    const e = chain(node)
-    emitValue(w, e, indent)
-    if (undefined !== e.trail) {
-      w.text(' ' + e.trail)
+    else {
+      const e = chain(node)
+      emitValue(w, e, indent)
+      if (undefined !== e.trail) {
+        w.text(' ' + e.trail)
+      }
+    }
+    // A TOP-LEVEL STATEMENT WRITTEN AS A TREE STANDS APART (§3.8). A
+    // document states several things -- a service, then its entities,
+    // then its errors -- and where one of them is a tree rather than a
+    // line, the eye finds it by the space around it. What counts as a
+    // tree is measured rather than guessed: the statement took more
+    // than one line to write. So `a: 1` beside `b: 2` is left alone,
+    // and this rule cannot fire below the root, where a blank line is
+    // the author's (§3.8) and nothing else.
+    if (root && from < w.mark()) {
+      w.gap(head)
+      pending = true
     }
   }
 }
@@ -1282,7 +1330,7 @@ function emitAt(nodes: Node[], indent: number): string {
 function emit(root: Node[], meet: Meet | undefined): string {
   const w = new Writer()
   emitBody(w, undefined === meet ? root : mergeRuns(root), 0,
-    undefined === meet ? undefined : { meet, covered: false })
+    undefined === meet ? undefined : { meet, covered: false }, true)
   return w.finish()
 }
 
@@ -1516,13 +1564,66 @@ function checkFinding(path: string | undefined, expected: string, actual: string
   }
 }
 
+// THE TARGET'S OWN LINES ARE HELD ON LINES OF THEIR OWN (§3.14). The
+// desugaring is line for line, so a line of output is known by the
+// offset it begins at, and the node beginning there -- the quoted
+// string the desugaring wrote -- is marked. From there on it has no
+// one-line form, so every container holding it opens, and no two lines
+// of the generated file are ever packed onto one.
+function holdOutput(nodes: Node[], at: Set<number>): void {
+  for (const node of nodes) {
+    if (undefined !== node.at && at.has(node.at)) {
+      node.held = true
+    }
+    holdOutput(node.body ?? [], at)
+    holdOutput(node.args ?? [], at)
+    holdOutput(node.inner ?? [], at)
+    holdOutput(node.items ?? [], at)
+    if (undefined !== node.value) {
+      holdOutput([node.value], at)
+    }
+  }
+}
+
+
+// The offsets the flagged lines of a document begin at.
+function outputAt(doc: string, flags: boolean[]): Set<number> {
+  const at = new Set<number>()
+  let off = 0
+  const lines = doc.split('\n')
+  for (let k = 0; k < lines.length; k++) {
+    if (flags[k]) {
+      at.add(off)
+    }
+    off += lines[k].length + 1
+  }
+  return at
+}
+
+
+// A finding's column in the TEMPLATE rather than in the document it
+// carries (§3.14): the marker and its one space stand before the aontu
+// on every line the resugaring writes. Every finding is on such a
+// line -- the two rules point at a key or at a container, and a line of
+// output is a bare string, which is neither.
+function shiftFindings(findings: LintFinding[], mark: string | undefined): LintFinding[] {
+  return undefined === mark ? findings :
+    findings.map((f) => ({ ...f, col: f.col + mark.length + 1 }))
+}
+
+
 // Format one document. The text is the agreed form of the source;
 // `changed` says whether it differs from what was given, which is
 // what `--check` and `--list` report.
 export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks): FormatReport {
   const text = lf(src)
+  // A GENERATOR IS FORMATTED AS THE DOCUMENT IT CARRIES (§3.14): the
+  // template surface's two transforms stand either side of the
+  // formatter, and between them is what happens to any other document.
+  const mark = opts?.template
+  const doc = undefined === mark ? text : desugarTemplate(text, mark)
   const toks: Tok[] = []
-  const parsed = parseDoc(text, opts?.path, toks)
+  const parsed = parseDoc(doc, opts?.path, toks)
   if (undefined !== parsed.errors) {
     return { verdict: 'error', errors: parsed.errors }
   }
@@ -1531,6 +1632,9 @@ export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks):
   if (reader.deep) {
     return { verdict: 'error', errors: [depthFinding()] }
   }
+  if (undefined !== mark) {
+    holdOutput(root, outputAt(doc, templateOutputs(text, mark)))
+  }
   // The syntactic tier first, checked against the parse tree; then the
   // lawful tier over it, each rewrite checked by the meet.
   const plain = emit(root, undefined)
@@ -1542,9 +1646,10 @@ export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks):
     }
   }
   const out = emit(root, hooks?.meet ?? sameByMeet)
+  const done = undefined === mark ? out : resugarTemplate(out, mark)
   return {
-    verdict: 'formatted', text: out, changed: out !== src,
-    findings: opts?.lint ? lintOf(root, text) : [],
+    verdict: 'formatted', text: done, changed: done !== src,
+    findings: opts?.lint ? shiftFindings(lintOf(root, doc), mark) : [],
   }
 }
 

package/src/hcanon.ts

@@ -16,6 +16,13 @@
 // (test/spec/hcanon.tsv). User-facing canon is UNCHANGED — hcanon is a
 // separate rendering.
 //
+// An ALIAS REFERENCE left standing in a spread template renders its
+// EXPANSION through this same walk rather than through the reference's
+// own canon, so a close() or a mark on the aliased value survives into
+// the hash. Without that the wrappers above are absent exactly where
+// the alias filter has already erased the declaration that carried
+// them (BUGS.md §60).
+//
 // The marks PROPAGATE to every descendant at unification (walkMark), so
 // a wrapper is emitted only where a mark STARTS: the walk carries the
 // inherited marks down and a child whose mark the parent already
@@ -49,10 +56,12 @@ type HMarks = {
 // One node's rendering, carrying the marks the ANCESTORS already
 // wrapped. Bags and junctions recurse structurally (their canon getters
 // render children through plain canon, which would drop a nested
-// close); everything else — scalars, kinds, funcs, refs, constraints —
-// delegates to its own canon, whose text is already in cross-port
-// parity. The non-Val arm mirrors MapVal.canon's raw-peg fallback and
-// is unreachable through an evaluated tree (direct-tested, ADR-002).
+// close), and so does an expanded alias reference, for the reason its
+// own arm gives. Everything else — scalars, kinds, funcs, constraints,
+// and a reference with nothing to expand — delegates to its own canon,
+// whose text is already in cross-port parity. The non-Val arm mirrors
+// MapVal.canon's raw-peg fallback and is unreachable through an
+// evaluated tree (direct-tested, ADR-002).
 function render(v: any, inh: HMarks): string {
   if (true !== v?.isVal) {
     return String(v)
@@ -106,6 +115,25 @@ function render(v: any, inh: HMarks): string {
   else if (true === v.isConjunct || true === v.isDisjunct) {
     s = junctionText(v, true === v.isConjunct ? '&' : '|', inner)
   }
+  // AN EXPANDED ALIAS REFERENCE IS RENDERED, NOT DELEGATED (BUGS.md
+  // §60). A reference standing after unification is one inside a
+  // spread template, and `RefVal.canon` answers with the EXPANSION's
+  // plain canon -- which drops exactly what this renderer exists to
+  // keep. The declaration carrying `close()` or a mark is erased by
+  // the alias filter above, so a `close()` lost here is lost from the
+  // hash entirely: `%A = close({n:string})` and `%A = {n:string}`,
+  // used as `box: [&: %A]`, hashed to ONE STRING while refusing and
+  // admitting `{n:"x",z:1}` respectively -- a change of meaning the
+  // pin reported as no change, in the unsafe direction. Recursing
+  // through `inner` is what makes the alias form and its longhand
+  // twin agree again, which is ALIASES.0.md §4's own requirement.
+  //
+  // A reference with NO expansion still spells its name: a plain
+  // `$.A` names a key the hash form still carries in full, and the
+  // knot of a recursive alias inside its own template never gets one.
+  else if (true === v.isRef && undefined !== v.expansion) {
+    s = render(v.expansion, inner)
+  }
   else {
     s = v.canon
   }

package/src/std.ts

@@ -186,6 +186,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   k: "prim"
   prim: "string" | "int" | "bigint" | "float" | "decimal" | "bool" | "null" | "any"
 })
+
 %ref = close({ k:"ref" name:%name unit?:string })
 %leaf = %prim | %ref | %text
 
@@ -208,6 +209,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
 })
 
 %member = close({ name:%name value?:string | number doc?:%doc x?:{} })
+
 %param = close({
   name: %name
   type: %type
@@ -221,12 +223,14 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
 %inline = string & re("^[^\n\r]*$") | %ref
 %line = close({ k:"line" at:*0 | integer & min(0) & max(64) of:[&: %inline] })
 %blank = close({ k:"blank" n:*1 | integer & min(1) & max(16) })
+
 %raw = close({
   k: "raw"
   at: *0 | integer & min(0) & max(64)
   text: string
   reindent: *true | boolean
 })
+
 %piece = %line | %blank | %raw | string & re("^[^\n\r]*$")
 %frag = close({ k:"frag" of:[&: %piece] })
 %body = %frag | close({ k:"abstract" })
@@ -241,7 +245,9 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   check?: [&: %check]
   x?: {}
 })
+
 %enum = close({ k:"enum" name:%name doc?:%doc members:[&: %member] x?:{} })
+
 %alias = close({
   k: "alias"
   name: %name
@@ -250,6 +256,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   check?: [&: %check]
   x?: {}
 })
+
 %const = close({
   k: "const"
   name: %name
@@ -258,6 +265,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   value: string | number | boolean | null
   x?: {}
 })
+
 %func = close({
   k: "func"
   name: %name

package/src/template.ts

@@ -24,12 +24,22 @@
 // comment, and derives for a language this table has never seen: the
 // caller passes the token.
 //
-// A MARKER IS RECOGNISED AFTER LEADING WHITESPACE AND KEEPS ITS OWN
-// INDENTATION (D2). That is what lets a template be written exactly
-// where its output appears (D7): a body line is verbatim, so a line
-// indented two spaces in the template is indented two spaces in the
-// generated file, and the marker lines around it are indented to match
-// the code they sit in rather than to the aontu they carry.
+// A MARKER IS RECOGNISED AFTER LEADING WHITESPACE, AND THE INDENTATION
+// THE RESUGARING WRITES IS THE AONTU'S (D2, amended 2026-09-07). An
+// output line is verbatim -- a line indented two spaces in the template
+// is indented two spaces in the generated file (D7) -- and that is the
+// half a reader of the TARGET needs. The other half is the document:
+// the marker lines carry a tree, and a tree nobody can see the shape of
+// is the one thing this surface took away. So the marker stands at the
+// left margin and the aontu is indented AFTER it, which `aontu fmt`
+// (FMT.0.md M-BM-'3.14) is what writes.
+//
+// Reading is unchanged and stays generous: a marker after leading
+// whitespace is a marker, and its own indentation still counts toward
+// the aontu it carries, so a template written the other way desugars to
+// the same document. What changes is the spelling the round trip
+// answers, and `template --check` names the difference as the drift it
+// is.
 //
 // THE SUGAR IS THE FIXPOINT OF THE TWO TRANSFORMS (D6), and that is
 // the whole of the resugaring's safety. A canonical line that looks
@@ -128,13 +138,19 @@ function indentOf(line: string): number {
 }
 
 
-// The line without its indentation or its trailing spaces and tabs.
-function trimLine(line: string): string {
+// The line without its trailing spaces and tabs.
+function trimEnd(line: string): string {
   let end = line.length
   while (0 < end && (' ' === line[end - 1] || '\t' === line[end - 1])) {
     end--
   }
-  return line.slice(indentOf(line), end)
+  return line.slice(0, end)
+}
+
+
+// The line without its indentation or its trailing spaces and tabs.
+function trimLine(line: string): string {
+  return trimEnd(line).slice(indentOf(line))
 }
 
 
@@ -159,12 +175,15 @@ function readLine(line: string, marker: string): Line {
   // The block form's closer is part of the marker, not of the aontu.
   // A block marker line that never closes is not a marker line: the
   // language's own parser would not read it as a comment either.
+  // Only the TRAILING space goes: what stands between the opener and
+  // the aontu is the aontu's indentation, exactly as it is for a line
+  // marker, and the one-space rule below takes the marker's own.
   if (isBlock(marker)) {
     const end = body.lastIndexOf(BLOCK_CLOSE)
     if (end < 0) {
       return { marker: false, indent: '', text: line }
     }
-    body = trimLine(body.slice(0, end))
+    body = trimEnd(body.slice(0, end))
   }
   // ONE SPACE AFTER THE MARKER IS THE MARKER'S, so `//- x: 1` carries
   // `x: 1` and the resugaring writes the space back. A marker written
@@ -273,19 +292,40 @@ function resugarTemplate(src: string, marker?: string): string {
     if (undefined !== target && desugarTemplate(target, mark) === trimLine(line)) {
       return target
     }
-    const cut = indentOf(line)
-    const text = line.slice(cut)
-    const open = line.slice(0, cut) + mark
+    // THE MARKER STANDS AT THE LEFT MARGIN and the line's indentation
+    // is written after it, so the aontu's own shape is on the page.
+    // The one space is the marker's, which the reading takes back.
+    const text = trimEnd(line)
     const close = isBlock(mark) ? ' ' + BLOCK_CLOSE : ''
-    return '' === text ? open + close : open + ' ' + text + close
+    return '' === text ? mark + close : mark + ' ' + text + close
   })
   return out.join('\n') + (tail ? '\n' : '')
-} /* node:coverage ignore next 8 */
+}
+
+
+// WHICH LINES OF THE DESUGARED DOCUMENT ARE THE TARGET'S. The
+// desugaring is line for line, so this is one flag per line of what
+// `desugarTemplate` returns: true where the template's line was not a
+// marker, and so where the document's line is one quoted line of the
+// generated file.
+//
+// `aontu fmt` reads it (FMT.0.md M-BM-'3.14) to hold those lines on lines of
+// their own. A body element is a string like any other, and the packing
+// budget would put three of them on one line -- which is aontu where
+// three lines of output were, and a generator that writes them as one.
+function templateOutputs(src: string, marker: string): boolean[] {
+  const lines = src.split('\n')
+  if (1 < lines.length && '' === lines[lines.length - 1]) {
+    lines.pop()
+  }
+  return lines.map((line) => !readLine(line, marker).marker)
+} /* node:coverage ignore next 9 */
 
 
 export {
   desugarTemplate,
   resugarTemplate,
+  templateOutputs,
   markerFor,
   DEFAULT_MARKER,
 }

package/src/val/RecurseVal.ts

@@ -204,6 +204,17 @@ function bumpRecurse(v: any, xc: number): void {
     v.xc = Math.max(v.xc, xc)
     return
   }
+  // A RAW REFERENCE TO A RECURSIVE TARGET IS THE RECURSION, minted or
+  // not -- the same reading containsRecurseOf already takes, and the
+  // reason bound 2 was inert. A freshly cloned level holds the
+  // definition's references UNRESOLVED, so this walk found no
+  // residual to stamp and `xc` read 0 at every expansion, in the
+  // healthy form too. The seed rides on the reference and the
+  // residual minted from it starts there (ts/src/val/RefVal.ts).
+  if (true === v.isRef) {
+    v.rxc = Math.max(v.rxc ?? 0, xc)
+    return
+  }
   const peg: any = v.peg
   if (true === v.isMap && null != peg) {
     for (const k of Object.keys(peg)) {

package/src/val/RefVal.ts

@@ -107,6 +107,15 @@ class RefVal extends FeatureVal {
   // after unification (see `canon` below). Not a ValSpec field: it is
   // a rendering of the settled tree, never a parse-time property.
   expansion: Val | undefined = undefined
+
+  // THE RECURSION SEED (use-cases/BUGS.md §57). A reference that names
+  // a recursive definition IS the fixpoint reference; it mints a
+  // RecurseVal when it resolves. bumpRecurse stamps the expansion
+  // depth here, because a freshly cloned level holds the definition's
+  // references UNRESOLVED and so has no residual to stamp -- which is
+  // why the design's second termination bound read 0 at every
+  // expansion. The minted residual starts from this.
+  rxc: number = 0
   prefix: boolean = false
 
   constructor(
@@ -329,7 +338,7 @@ class RefVal extends FeatureVal {
         out = makeNilErr(ctx, 'path_cycle', this)
       }
       else {
-        const rec: any = new RecurseVal({ target } as any, ctx)
+        const rec: any = new RecurseVal({ target, xc: this.rxc } as any, ctx)
         rec.site = this.site
         rec.path = [...this.path]
         out = rec
@@ -610,7 +619,8 @@ class RefVal extends FeatureVal {
         // residual is the resolved form, exactly as at the prefix
         // positions inside the definition.
         else if (null != out && !snap && containsRecurseOf(out, this.peg as any)) {
-          const rec: any = new RecurseVal({ target: [...this.peg] } as any, ctx)
+          const rec: any = new RecurseVal(
+            { target: [...this.peg], xc: this.rxc } as any, ctx)
           rec.site = this.site
           rec.path = [...this.path]
           out = rec
@@ -829,6 +839,10 @@ class RefVal extends FeatureVal {
       ...(spec || {})
     }) as RefVal)
     out.expansion = this.expansion
+    // The recursion seed travels with the clone: a spread template is
+    // cloned per destination, and each clone's residual must start
+    // where the level it came from left off.
+    out.rxc = this.rxc
     return out
   }
 

package/src/val/ReferFuncVal.ts

@@ -290,13 +290,25 @@ class ReferVal extends FeatureVal {
   // resolved string should take.
   settle(ctx: AontuContext, site: Val): Val {
     if (undefined === this.addr) {
-      // NOT DONE, unlike `string` or `min(1)`. A refer without an
-      // address has not done its work — it exists to check one — and
-      // the pass loop must keep offering it the chance. The cost is
-      // that a SCHEMA mentioning a link never resolves either, so
-      // `type({from: refer($.std.Port)})` is not expressible today;
-      // G4 phase 4 records why, and what it would take.
-      this.dc = 0
+      // DONE while unmet, as `string` and `min(1)` are, and as RelVal
+      // has been since it was written (see its constructor). An
+      // ADDRESS-LESS refer has nothing to check yet and nothing to
+      // refuse: it is its own settled residual, and the meet
+      // re-activates it the moment a value arrives, because map
+      // merges build the conjunct regardless.
+      //
+      // NOT-DONE here used to be justified as keeping the pass loop
+      // offering the refer a chance -- but that is the job of the
+      // OTHER pending branch below, where an address exists and its
+      // target has not appeared. This branch has no address to
+      // resolve, so staying not-done bought nothing and cost the
+      // schema idiom: a `type()` body holding a link never settled,
+      // so its mark never transferred, so generation could not skip
+      // the marked subtree and raised `mapval_no_gen` naming the
+      // definition. `type({p: integer})`, `type({p: path()})` and
+      // `type({p: min(1)})` all settled; only a link did not
+      // (aontu-lang/aontu#172, G4 phase 4's recorded cost).
+      this.dc = DONE
       return this
     }
     // The address is a TREE PATH, resolved from the link's own
@@ -477,11 +489,13 @@ class RelVal extends FeatureVal {
     super(spec, ctx)
     this.tval = (spec as any).tval ?? top()
     this.held = (spec as any).held
-    // DONE while unmet, deliberately -- the property refer() lacks and
-    // G4 phase 4 records the cost of: a type() body holding a rel()
+    // DONE while unmet, deliberately: a type() body holding a rel()
     // must SETTLE, or the schema idiom (`dependsOn?: rel($.T)` inside
     // a vocabulary) leaves the type unresolved and every reference to
-    // it deferring forever. An unmet rel is its own settled residual,
+    // it deferring forever. This was the property refer() lacked --
+    // G4 phase 4 recorded the cost -- until 2026-09-07, when an
+    // address-less refer was given it too (#172); the two now settle
+    // by the same rule, which is what the shared reasoning below is. An unmet rel is its own settled residual,
     // like `min(1)`; the meet re-activates it whenever a value
     // arrives, because map merges build the conjunct regardless.
     this.dc = DONE