aontu 0.62.0 → 0.63.0

package/src/lower.ts

@@ -1,29 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE DECLARATION LOWERING (docs/design/RENDER.0.md D5, D6, P5): the
-// one place in the renderer where "a new language is data" does not
-// hold. A `%record` becoming `export interface X {` or `type X struct
-// {` is a per-language-family function here, selected by the profile's
-// `lowering` field and parameterised by the profile's data -- the
-// indent, the comment forms, the string quote and its escape table, the
-// identifier rules and the type forms. Two families ship, `typescript`
-// and `go`; a third language with declarations is a change here, in
-// both ports (go/lower.go is the twin, function for function).
-//
-// Everything produced is PIECES -- lines at a depth, blanks -- that the
-// fragment fold then turns into bytes, so a lowered declaration and a
-// fragment take the same path to the file: one indent rule, one
-// terminator rule, nothing trimmed.
-//
-// THE PARITY GUARDS (G9 section 3), each a rule both ports keep: case
-// conversion is ASCII-only, and a code point at or above U+0080 rides
-// into the current word verbatim, never split and never converted;
-// string escaping is one pass, per code point, through the profile's
-// table, keyed by decimal code point, with a control character the
-// table does not name spelled as a \u escape; a reserved word is
-// matched by exact equality on the converted name; parenthesisation is
-// by `prec`/`childPrec`; numbers go through `exactJSON`; nothing here
-// sorts, and nothing iterates a map.
 
 import { exactJSON } from './exactjson'
 import type { RenderLoss } from './render'
@@ -40,7 +16,7 @@ export type LowerCtx = {
 
 
 function ln(at: number, text: string): any {
-  return { k: 'line', at, of: [text] }
+  return { k: 'line', at, n: [text] }
 }
 
 const BLANK = { k: 'blank' }
@@ -64,12 +40,6 @@ function isASCII(c: string): boolean {
   return (c.codePointAt(0) as number) < 0x80
 }
 
-// THE ASCII WORD SPLITTER. Words break at `_`, `-` and space, at a
-// lower-to-upper boundary (`creditLimit`), at a letter-to-digit
-// boundary in either direction (`utf8String`), and before the last
-// capital of a capital run that a lower case letter follows
-// (`HTTPServer` is HTTP, Server). A code point at or above U+0080
-// rides into the current word and never starts, ends or converts one.
 export function splitWords(name: string): string[] {
   const words: string[] = []
   let cur = ''
@@ -126,7 +96,7 @@ export function capitalise(word: string, acronyms: string[]): string {
   return upperASCII(chars[0]) + chars.slice(1).join('')
 }
 
-// THE CASE STYLES of aontu:profile's %case, over the words.
+// THE CASE STYLES of aontu:render's %case, over the words.
 export function caseName(name: string, style: string, acronyms: string[]): string {
   if ('as-is' === style) {
     return name
@@ -152,14 +122,6 @@ export function caseName(name: string, style: string, acronyms: string[]): strin
   return lowerASCII(words[0]) + caps.slice(1).join('')
 }
 
-// An identifier in a ROLE (record, field, enum, member, const, func,
-// param, alias): the profile's case style for the role, then -- for
-// the names that become bare identifiers, declarations and parameters
-// -- the reserved-word rule on the converted name, exact equality, so
-// Go's `Type` is not `type`. A reserved name is renamed with a trailing
-// underscore and the report says so, since code that named the
-// original will not compile against the rename. A field is a property,
-// and a property may spell what its target's string form admits.
 export function ident(
   name: string, role: string, ctx: LowerCtx, path: string, bare: boolean
 ): string {
@@ -234,14 +196,6 @@ function form(ctx: LowerCtx, name: string): any {
   return ctx.profile.types?.[name] ?? { open: '', close: '', prec: 9, childPrec: 0 }
 }
 
-// An inner expression under a form, in parens when its precedence is
-// below the form's childPrec: TypeScript's `(string | null)[]`.
-//
-// A FORM ALWAYS CARRIES ITS childPrec, so there is nothing to fall back
-// to: the profile vocabulary declares it `*0`, so every type form of a
-// profile met with `aontu:profile` has one, and `form()`'s own fallback
-// spells it. The default lives in the model, which is the point of
-// putting it there.
 function under(inner: Expr, f: any): string {
   return inner.prec < f.childPrec ? '(' + inner.text + ')' : inner.text
 }
@@ -289,20 +243,18 @@ export function typeExpr(t: any, ctx: LowerCtx, path: string): Expr {
   }
   if ('list' === k) {
     const f = form(ctx, 'list')
-    return { text: f.open + under(typeExpr(t.of, ctx, path + '.of'), f) + f.close, prec: f.prec }
+    return { text: f.open + under(typeExpr(t.n, ctx, path + '.n'), f) + f.close, prec: f.prec }
   }
   if ('map' === k) {
     const f = form(ctx, 'map')
     const key = under(typeExpr(t.key, ctx, path + '.key'), f)
-    const of = under(typeExpr(t.of, ctx, path + '.of'), f)
-    // The two families spell a map differently between the key and
-    // the value: `map[K]V` and `Record<K, V>`.
+    const of = under(typeExpr(t.n, ctx, path + '.n'), f)
     const sep = 'go' === ctx.family ? ']' : ', '
     return { text: f.open + key + sep + of + f.close, prec: f.prec }
   }
   if ('opt' === k) {
     const f = form(ctx, 'opt')
-    return { text: f.open + under(typeExpr(t.of, ctx, path + '.of'), f) + f.close, prec: f.prec }
+    return { text: f.open + under(typeExpr(t.n, ctx, path + '.n'), f) + f.close, prec: f.prec }
   }
   if ('union' === k) {
     if ('go' === ctx.family) {
@@ -310,18 +262,18 @@ export function typeExpr(t: any, ctx: LowerCtx, path: string): Expr {
       return { text: prim(ctx, 'any'), prec: 9 }
     }
     const f = form(ctx, 'union')
-    const members = t.of.map((m: any, i: number) =>
-      under(typeExpr(m, ctx, path + '.of.' + i), f))
+    const members = t.n.map((m: any, i: number) =>
+      under(typeExpr(m, ctx, path + '.n.' + i), f))
     return { text: f.open + members.join(' | ') + f.close, prec: f.prec }
   }
   // lit
   if ('go' === ctx.family) {
-    const p = litPrim(t.of)
+    const p = litPrim(t.n)
     loss(ctx, path, 'lit', 'go has no literal type: ' + p)
     return { text: prim(ctx, p), prec: 9 }
   }
   const f = form(ctx, 'lit')
-  const lits = t.of.map((v: any) => literal(v, ctx))
+  const lits = t.n.map((v: any) => literal(v, ctx))
   return { text: f.open + lits.join(' | ') + f.close, prec: f.prec }
 }
 
@@ -358,8 +310,6 @@ function doc(d: any, at: number, ctx: LowerCtx): any[] {
   return out
 }
 
-// Every check a target's type system cannot enforce is tier-1 loss,
-// one entry per check, addressed at the check.
 function checks(list: any[] | undefined, path: string, ctx: LowerCtx): void {
   (list ?? []).forEach((c: any, i: number) => {
     loss(ctx, path + '.check.' + i, 'check',
@@ -409,7 +359,7 @@ function derivedImports(unit: any): any[] {
       }
       return
     }
-    for (const key of ['type', 'of', 'key', 'returns', 'fields', 'params']) {
+    for (const key of ['type', 'n', 'key', 'returns', 'fields', 'params']) {
       visit(t[key])
     }
   }
@@ -617,7 +567,7 @@ export function lowerDecl(decl: any, path: string, ctx: LowerCtx): any[] {
       out.push(ln(1, 'panic(' + quote('abstract', ctx.profile) + ')'))
     }
     else {
-      out.push(...nest(decl.body.of))
+      out.push(...nest(decl.body.n))
     }
     out.push('}')
   }
@@ -628,7 +578,7 @@ export function lowerDecl(decl: any, path: string, ctx: LowerCtx): any[] {
     }
     else {
       out.push('export function ' + name + '(' + sig + ')' + ret + ' {')
-      out.push(...nest(decl.body.of))
+      out.push(...nest(decl.body.n))
       out.push('}')
     }
   }

package/src/lsp-server.ts

@@ -1,22 +1,9 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// Aontu Language Server (stdio).
-//
-//   aontu-lsp
-//
-// Speaks LSP over stdio (JSON-RPC with Content-Length framing) and
-// publishes unification diagnostics as `.aontu` files are edited. This
-// binary is intentionally thin: all protocol logic lives in the reusable
-// library ./lsp (LspHandler + computeDiagnostics). See docs/lsp.md for
-// editor configuration.
 
 import { LspHandler, Message, OutMessage } from './lsp'
 
 
-// A byte-level LSP framing codec: feed it incoming chunks, give it a
-// handler, and it decodes Content-Length frames, dispatches them, and
-// writes framed replies. Kept transport-injectable (write/onExit) so it
-// can be unit-tested without real stdio.
 class FrameCodec {
   private buffer = Buffer.alloc(0)
 
@@ -84,9 +71,6 @@ class FrameCodec {
 }
 
 
-// The streams and exit are injectable (defaulting to real stdio) so the
-// full wiring is unit-testable — the same shape as the Go server's
-// serve(in, out, logw).
 function main(
   stdin: NodeJS.ReadableStream = process.stdin,
   write: (chunk: Buffer) => void = (chunk) => void process.stdout.write(chunk),

package/src/lsp.ts

@@ -1,20 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// Aontu Language Server library.
-//
-// This module is the reusable, transport-free core of the language
-// server, deliberately split from the process that serves it:
-//
-//   - `computeDiagnostics(src)` turns Aontu source into LSP diagnostics.
-//   - `LspHandler` implements the LSP message flow (document sync ->
-//     publishDiagnostics) over decoded JSON-RPC *objects*, with no
-//     stdin/stdout. It is fully unit-testable and embeddable.
-//   - the server (`lsp-server.ts`) is a thin stdio JSON-RPC loop that
-//     frames bytes and feeds decoded messages to an `LspHandler`.
-//
-// The Go port mirrors this split in go/lsp (library) and
-// go/cmd/aontu-lsp (server). Diagnostic messages are built the same way
-// in both so editors see identical text regardless of implementation.
 
 import type { Val } from './type'
 
@@ -34,18 +19,11 @@ const SEVERITY_WARNING = 2
 const SEVERITY_INFORMATION = 3
 const SEVERITY_HINT = 4
 
-// Reported to the client in the initialize response. It is the
-// ENGINE's version, not a number of the server's own: a separately
-// maintained one drifts, and had -- the server answered 0.1.0 against
-// a package at 0.52.1, so a client could not tell which engine it was
-// talking to (status-2026-08-21.md section 10).
 const LSP_VERSION = VERSION
 
 
-// Zero-based line / UTF-16 character offset (LSP Position).
 type Position = { line: number, character: number }
 
-// Inclusive-start, exclusive-end span (LSP Range).
 type Range = { start: Position, end: Position }
 
 // A single LSP diagnostic.
@@ -80,18 +58,10 @@ type OutMessage = {
 }
 
 
-// Compute LSP diagnostics for a unit of Aontu source. A valid document —
-// including a non-concrete schema such as `a:string` — returns an empty
-// array; only genuine errors (conflicts, unresolved references, unknown
-// functions, syntax errors) produce diagnostics.
 function computeDiagnostics(
   src: string,
   opts?: { vars?: Record<string, Val>, trust?: any, textExt?: string[] }
 ): Diagnostic[] {
-  // The trust profile (G5, docs/trust.md): the LSP is the
-  // highest-exposure surface — merely OPENING a hostile .aon file in an
-  // editor performs its reads — so the handler confines evaluation to
-  // the workspace root and threads the profile through here.
   const aontu = new Aontu(includeOpts(opts ?? {}))
 
   let root: any
@@ -114,12 +84,6 @@ function computeDiagnostics(
   const seen = new Set()
   const nils: any[] = collectNils(root, seen)
 
-  // Errors recorded on the context but not present in the tree — e.g. a
-  // budget_passes exhaustion nil, which is about the whole evaluation
-  // rather than any node — would otherwise be invisible here, and the
-  // trust contract forbids silent truncation (docs/trust.md clause 2).
-  // Tree nils are already on ctx.err too, so dedup by identity; the
-  // transient disjunct-trial sentinel never surfaces.
   for (const e of ac.err) {
     if (e?.isNil && '|:trial-nil' !== e.why && !seen.has(e)) {
       seen.add(e)
@@ -129,11 +93,6 @@ function computeDiagnostics(
 
   const out = nils.map(nilToDiagnostic)
 
-  // Deprecation tags (G3 phase 4): every sited value carrying the
-  // deprecate() record — the declaration and, because the record rides
-  // meets and reference clones, every use resolving through it — gets
-  // the native Deprecated tag (2) at Hint severity, so editors strike
-  // it through without shouting.
   for (const { val } of collectDeprecations(root)) {
     const v: any = val
     if (1 > (v.site?.row ?? -1) || 1 > (v.site?.col ?? -1)) {
@@ -187,38 +146,16 @@ function nilToDiagnostic(nil: any): Diagnostic {
 }
 
 
-// Length (UTF-16 units, like LSP characters) of the offending value's
-// SOURCE TEXT, used to size the diagnostic range (minimum 1).
 function labelLength(nil: any): number {
   return null == nil.primary ? 1 : siteExtent(nil.primary)
 }
 
 
-// The extent to underline for a value: its SOURCE TEXT's length, with
-// the canon as the fallback and 1 as the floor.
-//
-// CANON IS NOT SOURCE TEXT, which is the whole point of Site.len:
-// `0x1F` has canon `31`, so sizing by canon underlines two characters
-// of a four-character literal — hovering `0x1F` highlighted `0x` and
-// hovering `1F` answered nothing. The Go twin is the same fallback in
-// go/check.go (Problem.Len, ValueSpan.Len), in bytes there because it
-// is added to a byte offset before conversion.
-//
-// The fallback is for a value carrying no stamped span — one propagated
-// onto a result rather than written by a document — where canon is all
-// there is and an approximate underline beats none. A REPORT never
-// guesses this way: vet and why emit len only when it is known, because
-// there a wrong length is a corrupted document rather than a wonky
-// highlight.
 function siteExtent(v: any): number {
   const len = v?.site?.len
   if ('number' === typeof len && len > 0) {
     return len
   }
-  // CANON IS READ DEFENSIVELY, as every other reader here does: it is a
-  // getter that unifies, and a host-supplied value can throw from it
-  // (hover-refuses-bad-input). A hover that cannot measure a value
-  // still has to answer for the rest of the document.
   let c = ''
   try { c = v?.canon } catch { c = '' }
   return 'string' === typeof c && c.length > 0 ? c.length : 1
@@ -268,7 +205,6 @@ function parseErrorDiagnostic(err: any): Diagnostic {
 function initializeResult() {
   return {
     capabilities: {
-      // 1 = TextDocumentSyncKind.Full
       textDocumentSync: 1,
       hoverProvider: true,
       completionProvider: {},
@@ -282,14 +218,6 @@ function initializeResult() {
 }
 
 
-// signatureHelp: the declared signature of the ENCLOSING call, served
-// from the registry (docs/design/SIGNATURES.0.md). The enclosing call
-// is found lexically -- scan back from the cursor for the nearest
-// unclosed '(' and read the word before it; commas at that depth
-// count the active parameter, capped at the last slot so a rest tail
-// stays active for every excess argument. Strings are skipped so a
-// paren or comma inside one does not miscount, and the scan stops at
-// the line start, a call being one line in practice.
 function computeSignatureHelp(text: string, pos: any): any {
   // Position to offset, under the full-sync model: lines are exactly
   // the text's newlines.
@@ -344,21 +272,10 @@ function publishDiagnosticsMsg(uri: string, diagnostics: Diagnostic[]): OutMessa
 }
 
 
-// --- Hover ------------------------------------------------------------
-
 type MarkupContent = { kind: 'markdown' | 'plaintext', value: string }
 type Hover = { contents: MarkupContent, range?: Range }
 
 
-// Resolve the value under the cursor and describe it. Returns null when
-// the position is not over a value with a known source location. Because
-// hover reads the *unified* tree, a literal shows its resolved value and
-// kind (e.g. a reference target resolves to the value it points at).
-// HOVER PROVENANCE (G7 phase 7) is CONFIG-GATED and off by default:
-// the contributions that met at the hovered path, appended to the
-// value's own hover. Hover already re-unifies the whole document per
-// request, so an editor that asks for this pays a second instrumented
-// evaluation knowingly, and one that does not pays nothing.
 function provenanceMarkdown(
   src: string, path: string[], trust?: any): string {
   if (0 === path.length) {
@@ -372,10 +289,6 @@ function provenanceMarkdown(
 }
 
 
-// The contributions as hover markdown. Exported for the direct test
-// (ADR-002): a siteless contribution and a named file are both shapes
-// the record allows and no hover produces, hover evaluating one
-// unnamed document.
 export function contributionsMarkdown(conjuncts: WhyConjunct[]): string {
   if (0 === conjuncts.length) {
     return ''
@@ -388,12 +301,6 @@ export function contributionsMarkdown(conjuncts: WhyConjunct[]): string {
 }
 
 
-// HOVER RUNS UNDER THE SAME CAPABILITY AS DIAGNOSTICS. It used to
-// evaluate through `new Aontu()` -- the full system resolver -- BESIDE
-// confined diagnostics in the same server, so a workspace-confined
-// session still resolved an escaping include the moment a cursor rested
-// on it (use-cases/REVIEW.md finding G). One document, two postures, is
-// not a confinement.
 function computeHover(
   src: string, position: Position, provenance?: boolean,
   trust?: any): Hover | null {
@@ -450,16 +357,6 @@ function collectHoverCandidates(
   // one, canon otherwise. See siteExtent.
   const span = siteExtent(v)
   const spanSrc = 'string' === typeof v.site?.src ? v.site.src : ''
-  // Hover targets concrete values (scalars, kinds, refs, …), not
-  // containers: a map/list source span is not reliably reconstructable
-  // from a single site, and the same restriction in the Go port keeps
-  // hover behaviour identical across implementations. The walk still
-  // recurses into containers below to reach their leaf values. Canon is
-  // single-line, so its length approximates the on-line source span.
-  // Single-line is decided by the SOURCE TEXT when there is one: a
-  // multi-line token cannot be described by one line's start and end,
-  // and canon's newlines are not the token's. Falling back to canon
-  // keeps the old test for a value with no stamped span.
   const multiline = '' === spanSrc ? canon.includes('\n') : spanSrc.includes('\n')
   if (row >= 1 && col >= 1 && canon.length > 0 && !multiline &&
     !v.isMap && !v.isList) {
@@ -505,8 +402,6 @@ function valKind(val: any): string {
 }
 
 
-// --- Completion -------------------------------------------------------
-
 type CompletionItem = {
   label: string
   kind?: number   // LSP CompletionItemKind
@@ -519,21 +414,20 @@ import { funcSig, renderSig, renderSigArg } from './sig'
 const COMPLETION_FUNCTION = 3
 const COMPLETION_KEYWORD = 14
 
-// The built-in functions. Kept in sync with the engine by
-// `lsp.test.ts`, which asserts each is recognised and no others are.
-// The Go port derives its list from the engine's own name set
-// (`BuiltinFuncNames`, go/func.go), which is why a name added there
-// and forgotten here diverges silently — as `id` and `refer` did
-// between G4 phases 1/2 and G8 phase 1.
 const BUILTIN_FUNCS = [
-  'above', 'acyclic', 'add', 'below', 'close', 'copy', 'deprecate', 'div',
+  'abnf', 'above', 'acyclic', 'add', 'below', 'close', 'content', 'copy',
+  'copyfiles', 'deprecate',
+  'div',
   'each', 'emit', 'esc',
-  'filter', 'greatest',
-  'hide', 'inverse', 'join', 'key', 'least', 'length', 'list', 'lower',
-  'map', 'match', 'max', 'min', 'mod', 'move', 'mul', 'must', 'neq', 'open',
-  'pack', 'path', 'pick',
-  'pref', 're', 'refer', 'rel', 'rem', 'rep', 'split', 'sub', 'sum',
-  'super', 'type', 'unique', 'upper', 'usc',
+  'file', 'filter', 'folder', 'fragment', 'greatest',
+  'hide', 'inject', 'inverse', 'join', 'key', 'least', 'length', 'line',
+  'list', 'listitems', 'lower',
+  'map', 'match', 'max', 'maybe', 'min', 'mod', 'move', 'mul', 'must', 'neq',
+  'nom', 'open',
+  'pack', 'parse', 'path', 'pick',
+  'pref', 'project', 're', 'refer', 'rel', 'rem', 'rep', 'slot', 'sort',
+  'split', 'sub', 'sum',
+  'super', 'translate', 'type', 'unique', 'upper', 'usc',
 ]
 
 // Scalar-kind and literal keywords.
@@ -567,46 +461,11 @@ function computeCompletions(): CompletionItem[] {
 }
 
 
-// Transport-agnostic LSP message dispatcher. Consumes decoded JSON-RPC
-// messages and returns the messages to send back, tracking open document
-// text and recomputing diagnostics on open/change/close. Not safe for
-// concurrent use; drive it from a single loop (as the stdio server does).
-// A file:// uri's filesystem path, for the workspace-root confinement.
-// Percent-decoded; a non-file uri (or none) yields undefined.
-//
-// EXPORTED, inline as contributionsMarkdown is: part of the reusable
-// LSP library surface, and the twin of the package-visible uriToPath in
-// go/lsp/handler.go. Anything driving this module with its own
-// transport has to turn a client's uri into a path the same way the
-// confinement does, and the rules below are not guessable from outside.
-//
-// THE DRIVE-LETTER SLASH. A file uri names an absolute path after the
-// authority, so on Windows the standard spelling every editor sends is
-// file:///C:/Users/me/project — three slashes, and the third belongs to
-// the PATH. Stripping only `file://` leaves `/C:/Users/me/project`,
-// which is not a Windows path at all, so the workspace-root
-// confinement below compared real paths against nonsense and an editor
-// on Windows got no confinement it could rely on. Both ports carried
-// the defect identically (go/lsp/handler.go uriToPath), and no test
-// caught it because both ports' tests built the uri as `'file://' +
-// path` — two slashes, which is not what a client sends and which
-// accidentally produced a usable path.
-//
-// The leading slash is dropped only before a DRIVE LETTER, so a POSIX
-// path keeps the root it needs: file:///tmp/x stays /tmp/x.
 export function uriToPath(uri: unknown): string | undefined {
   if ('string' !== typeof uri || !uri.startsWith('file://')) {
     return undefined
   }
   const path = percentDecode(uri.slice('file://'.length))
-  // AN EMPTY PATH IS NOT A ROOT. `file://` on its own yields '', and
-  // '' is not nullish — so it won the `??` chain below and arrived as
-  // `{ include: { root: '' } }`, a confinement root that then resolves
-  // against the process working directory: the same client params made
-  // the server allow or deny an include depending on where it was
-  // started from. The Go twin never had it, because its chain tests
-  // `"" != folder` explicitly (go/lsp/handler.go). Answering undefined
-  // is what makes the two chains agree.
   if ('' === path) {
     return undefined
   }
@@ -614,23 +473,6 @@ export function uriToPath(uri: unknown): string | undefined {
 }
 
 
-// Percent-decoding that CANNOT THROW. `decodeURIComponent` raises a
-// URIError on a malformed escape (`%ZZ`), and this runs on a uri a
-// CLIENT sent — so a stray percent in a workspace path took the
-// exception straight out of the initialize handler, where the Go twin
-// swallowed the same failure and used the raw text
-// (go/lsp/handler.go). Two ports, two behaviours, for an input neither
-// of them controls.
-//
-// The agreement runs the other way for the SECOND way an escape can
-// fail to decode. `%FF` is well-formed and names a raw byte — a
-// perfectly good Linux filename — which Go produced and a JavaScript
-// string cannot hold at all, so the ports derived different workspace
-// roots for a uri a byte-oriented client really sends. Only one
-// direction is reachable from both languages, so Go now declines to
-// unescape a result that is not valid UTF-8 and both ports keep the
-// raw text. An undecodable path is still a path, and refusing to serve
-// a session over it helps nobody.
 function percentDecode(text: string): string {
   try {
     return decodeURIComponent(text)
@@ -655,12 +497,6 @@ class LspHandler {
   private shutdownOK = false
   private exited = false
 
-  // The trust profile evaluation runs under (G5, docs/trust.md):
-  // workspace-root confinement by default, set from the initialize
-  // params. An `initializationOptions.aontu.trust.include` of 'system',
-  // 'none' or { root } widens or narrows it explicitly. Undefined —
-  // no workspace root and no explicit option — falls back to today's
-  // unconfined behaviour, which single-file sessions rely on.
   private trust: any = undefined
 
   // Hover provenance (G7 phase 7): off unless an editor asks for it
@@ -687,10 +523,6 @@ class LspHandler {
           true === params.initializationOptions?.aontu?.provenance
         const explicit = params.initializationOptions?.aontu?.trust?.include
         if (null != explicit) {
-          // An explicit setting wins — validated, and an unrecognised
-          // value confines to NOTHING rather than silently widening:
-          // deny is the safe reading of a setting the server does not
-          // understand. The same rule as the Go handler.
           this.trust =
             'system' === explicit ? undefined :
               'none' === explicit ? { include: 'none' } :

package/src/mcp-server.ts

@@ -1,27 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// Aontu MCP server (stdio).
-//
-//   aontu-mcp [--root <dir>]
-//
-// Speaks the Model Context Protocol over stdio: newline-delimited
-// JSON-RPC 2.0, one message per line. This binary is intentionally
-// thin — every tool and every protocol decision lives in the reusable
-// library ./mcp, the same three-layer split the language server uses
-// (docs/lsp.md).
-//
-// NDJSON, not the LSP's Content-Length framing: MCP stdio transport
-// is line-delimited, and a server that invented its own framing would
-// not be reachable by any client.
-//
-// The one startup decision is the PATH CAPABILITY: `--root <dir>`
-// grants the served evaluation the CLI's `--trust root:<dir>` posture
-// — includes resolve confined below the root, and every tool's
-// document arguments accept `<name>Path` file alternatives, confined
-// the same way. Without it the server denies all includes and refuses
-// path arguments (./mcp). The root is realpath'd HERE, once, so the
-// confinement prefix the library compares against is the real
-// directory, not a spelling of it.
 
 import { realpathSync, statSync } from 'node:fs'
 
@@ -40,11 +18,6 @@ const USAGE = 'aontu mcp - aontu MCP server (stdio, NDJSON JSON-RPC)\n' +
   '                denies every include and refuses path arguments.\n'
 
 
-// The startup arguments. Parsed here rather than in bin/aontu-mcp.js
-// or the CLI's mcp verb
-// so the parsing is import-testable; unknown options REFUSE rather
-// than warn, because a server whose operator typo'd --root must not
-// come up quietly unconfined.
 export type ServerArgs = {
   root?: string
   help?: boolean
@@ -152,10 +125,6 @@ function main(
     return undefined
   }
 
-  // FAIL FAST on a root that is not a real directory: every later
-  // call would refuse anyway, but a misconfigured server that answers
-  // a thousand confusing refusals is worse than one that says so at
-  // startup.
   let root: string | undefined
   if (null != args.root) {
     try {