aontu 0.61.0 → 0.63.0

package/src/ctx.ts

@@ -16,7 +16,6 @@ import {
 } from './err'
 
 
-
 type AontuContextConfig = {
   cc?: number
   err?: any[] // Omit<NilVal[], "push">
@@ -27,12 +26,6 @@ type AontuContextConfig = {
   // error list is, so one run has one record.
   prov?: any
 
-  // THE READ SET (RENDER.0.md P7), or absent for an uninstrumented
-  // run: every tree path a reference resolved to, in one shared set.
-  // It is what `render --coverage` measures the model against -- a
-  // path no read reached is model the transform never consumed -- and
-  // its presence is also what switches the two render riders on
-  // (Val.origin, Val.emitted), so one flag turns the whole record on.
   reads?: Set<string>
   fs?: any
   errfs?: any
@@ -56,24 +49,6 @@ class AontuContext {
   vc: number  // Val counter to create unique val ids.
   cc: number = -1
 
-  // THE STAGING RULE (G8 phase 0,
-  // docs/capability-review/g8-generation.md). A value whose answer
-  // depends on WHERE IT IS -- `key()` today, the generation
-  // combinators next -- must not answer while anything is still
-  // moving it: resolved early it reports the position it was WRITTEN
-  // at rather than the one it ends up at. Such a value RESIDUATES
-  // while this is false, and fires exactly once on the pass where it
-  // is true.
-  //
-  // The pass loop (ts/src/unify.ts) sets it on the first pass whose
-  // input tree is IDENTICAL to the previous pass's: everything that
-  // was going to move has moved, and what is left is the staged
-  // values themselves, which is precisely the moment they may answer.
-  // It replaces a `ctx.cc < 3` pass count in KeyFuncVal -- a magic
-  // number, right for the documents it was tuned on and silently
-  // wrong for anything that took a fourth pass to place a value. The
-  // comment it replaces said as much: "this delay makes keys in
-  // spreads and refs work, but it is a hack - find a better way".
   settle: boolean = false
   vars: Record<string, Val> = {}
   src?: string
@@ -86,18 +61,6 @@ class AontuContext {
 
   collect: boolean
 
-  // THE COMPLETENESS PROBE (the review's finding C). vet detects
-  // residue by GENERATING the anchored meet and keeping the
-  // incomplete-class failures. Generation honours the OUTPUT marks --
-  // `type()` and `hide()` say "do not emit this" -- so a `--at` anchor
-  // sitting under a mark generated nothing at all, reported nothing,
-  // and vetted VALID for data missing a required field, while the same
-  // anchor without the mark answered incomplete (use-cases/BUGS.md
-  // §14). A mark is a decision about OUTPUT; it is not a statement
-  // about what the data must satisfy, and `--at` names the truth to
-  // validate against explicitly. Under this flag the generation walk
-  // descends through marked values; nothing else changes, and no
-  // output is produced from a probe run -- only its findings are read.
   probe: boolean = false
 
   // The provenance recorder (G7 phase 3), or undefined for an
@@ -113,7 +76,6 @@ class AontuContext {
   err: any[]
   explain: any[] | null
 
-  // TODO: separate options and context!!!
   srcpath?: string
 
   deps: Record<string, any>
@@ -122,49 +84,15 @@ class AontuContext {
   _pathstr: string | undefined
   _pathidx: number | undefined
   _pathmap: Map<string, number>
-  // Trie keyed by (parentIdx, key) -> { idx, path }. Serves two
-  // jobs: (1) assign O(1) pathidx without rebuilding
-  // `path.join('\x00')` for cycle-detection; (2) cache the
-  // materialised path array so the same (parent, key) visited
-  // across fixpoint passes reuses one array instead of re-concat.
   _pathTrie: Map<number, Map<string, { idx: number, path: string[] }>>
   _pathidxNext: { n: number }
 
-  // Current `unite` recursion depth, checked against the depth budget
-  // (ts/src/unify.ts). Held in a shared mutable box, like _pathidxNext,
-  // because clone() uses Object.create: the box is inherited by
-  // reference, so a nested clone's increments are visible to the frame
-  // that will decrement them. The Go port keeps the same counter
-  // directly on its Ctx pointer (go/unify.go, maxUniteDepth).
   _depth: { n: number }
 
-  // The relation declarations this evaluation accumulates (RELATIONS
-  // P2): predicate -> what its graph atoms said. One Map per
-  // evaluation, created here and inherited by reference through
-  // clone()'s prototype chain, exactly as _depth's box is -- a clone
-  // made before the first registration must still share the registry.
   _reldecls: Map<string, { acyclic?: boolean, inverses: Set<string> }>
 
-  // The tree a recursive residual's target resolves against when the
-  // meet's own root does not contain it (RECURSION.0.md). Normally
-  // undefined: a residual expands by walking ctx.root, and the root
-  // holds the definition. An ANCHORED vet run meets a subtree LIFTED
-  // out of the settled schema, so `$.spec.Step` names nothing in the
-  // meet's root -- the residual held its peer forever and the data
-  // under it vetted VALID unchecked. Vet sets this to the settled
-  // schema root for anchored runs; RecurseVal.body falls back to it
-  // only when the root walk finds nothing. Inherited by clone()
-  // through the prototype chain.
   _fixroot: any
 
-  // The evaluation budgets (G5 trust profile, docs/trust.md): integer
-  // counts of engine events, never wall-clock. Always present, defaults
-  // from the shared spec-visible constants (test/spec/budget.tsv), so
-  // the hot-path reads in unify.ts are plain property loads. Inherited
-  // by clone() through the prototype chain. `revisits` is NOT profile
-  // surface (the Go port has no revisit counter to configure — see
-  // TrustBudget in type.ts); it is carried here so unify.ts reads one
-  // budget object, at its fixed spec constant.
   budget: { passes: number, revisits: number, depth: number }
 
   // The include manifest sink (G5, docs/trust.md): every include the
@@ -172,20 +100,8 @@ class AontuContext {
   // Aontu.parse() sorts and dedups it onto the result's `deps`.
   manifest: { path: string, capability: string }[]
 
-  // Trial mode: set by DisjunctVal.unify while each member is tried
-  // against the peer. When true, makeNilErr returns the shared
-  // TRIAL_NIL sentinel instead of allocating a fresh NilVal, and
-  // pushes TRIAL_NIL to ctx.err only once per trial (the caller's
-  // `trialErr.length > 0` check still signals failure). See err.ts.
   _trialMode?: boolean
 
-  // Per-parent descend cache: (key) -> already-descended child ctx.
-  // ~48% of descends in foo-sdk repeat the same (parent, key) pair
-  // (e.g. a MapVal.unify visits the same peer keys across fixpoint
-  // passes). The child's prototype chain, path, and pathidx are
-  // identical every time, and no code writes to a descended ctx
-  // between visits — nothing mutates per-child state — so the
-  // cached child is safe to reuse.
   _childCache?: Map<string, AontuContext>
 
 
@@ -258,9 +174,6 @@ class AontuContext {
     ctx.explain = Array.isArray(cfg.explain) ? cfg.explain : ctx.explain
 
     ctx._pathstr = undefined
-    // Path didn't move unless cfg.path was supplied, so pathidx stays
-    // valid in the common case. For cfg.path-override (4 calls per
-    // run, fixpoint advances) fall back to the join-based lookup.
     if (cfg.path !== undefined) {
       ctx._pathidx = undefined
     }
@@ -269,14 +182,6 @@ class AontuContext {
   }
 
   descend(key: string): AontuContext {
-    // C3: reuse the child ctx from a previous descend with the same
-    // (parent, key). Saves one Object.create + several property
-    // writes per hit; ~48% hit rate on foo-sdk.
-    //
-    // NB: must use hasOwnProperty here — plain `this._childCache`
-    // would walk the prototype chain and read the *parent's* cache
-    // (ctxs are created via Object.create(parent)), so keys would
-    // cross-contaminate between sibling branches.
     let childCache: Map<string, AontuContext> | undefined
     if (Object.prototype.hasOwnProperty.call(this, '_childCache')) {
       childCache = this._childCache
@@ -291,11 +196,6 @@ class AontuContext {
     const ctx = Object.create(this)
     ctx._pathstr = undefined
 
-    // Trie doubles as both pathidx assignment and path-array cache.
-    // (parent_pathidx, key) uniquely identifies a descended path,
-    // and is visited many times across fixpoint passes. Caching the
-    // materialised array lets descend share references instead of
-    // allocating a fresh concat every time.
     const parentIdx = this._pathidx!
     let childMap = this._pathTrie.get(parentIdx)
     if (childMap === undefined) {
@@ -329,7 +229,6 @@ class AontuContext {
 
     this.src = ('string' === typeof this.opts.src ? this.opts.src : undefined) ?? this.src
 
-    // TODO: rename srcpath to file
     this.srcpath = this.opts.path ?? this.srcpath
   }
 
@@ -351,7 +250,6 @@ class AontuContext {
 
 
   errmsg() {
-    // return this.errlist
     return this.err
       .map((err: any) => (err && (null == err.msg || '' === err.msg)
         ? (descErr(err, this), err.msg)
@@ -407,7 +305,6 @@ class AontuContext {
 } /* node:coverage ignore next 8 */
 
 
-
 export {
   AontuContext,
   AontuContextConfig

package/src/diff.ts

@@ -1,25 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// PATH-ADDRESSED DIFF (G7 phase 6,
-// docs/capability-review/g7-machine-access.md): what changed, at which
-// paths, between two documents — the dyff-style answer, which
-// deterministic canon makes possible without phantom noise. Two
-// documents that mean the same thing canon the same way, so a diff of
-// canons reports semantic change and not reformatting.
-//
-// The text compared is the HASH FORM (G6's `hcanon`), not the plain
-// canon, for the reason G6 gives: canon drops closedness and the
-// type/hide marks, so a canon diff calls `close({a:1})` and `{a:1}`
-// identical. A false "changed" costs a needless read; a false
-// "unchanged" is a change nobody reviewed, which is the one direction
-// that must not happen.
-//
-// WHETHER a change is BREAKING is a different question, and it belongs
-// to G3: `subsume` and `breaking` answer it with the lattice's own
-// rules. This verb answers "what moved", which is what a reviewer
-// reads first and what an agent needs before it can ask the other
-// question at all.
 
 import { Aontu } from './aontu'
 import type { TrustOptions } from './type'
@@ -44,7 +25,6 @@ export type DiffReport = {
   changes: DiffChange[]
   findings: VetFinding[]
   ok: boolean
-  // True when nothing moved: the two documents mean the same thing.
   same: boolean
 }
 
@@ -54,13 +34,6 @@ export type DiffOptions = {
   // Compare at this path of both documents, rather than at the root.
   at?: string
 
-  // The trust profile this run evaluates under (G5, docs/trust.md).
-  // The source arrives from a caller, so the caller must be able to
-  // say what it may reach: without this the include chain is the
-  // default one, and `@"../../etc/passwd.aon"` reads whatever the
-  // process can. (`@"x.js"` no longer executes -- ADR-012 refuses the
-  // extension -- but reading is enough.) A server passes
-  // `{include:'none'}`.
   trust?: TrustOptions
 
   // Extensions additionally read as text (the CLI's `--text-ext`).
@@ -75,11 +48,6 @@ function pathText(parts: string[]): string {
 }
 
 
-// Both sides of one node — never both absent: keys come from the
-// union of the two bags, and list indices run to the longer side, so
-// every walk has at least one value. Bags of the SAME kind recurse,
-// which is what makes the report path-addressed rather than one line
-// saying the whole document changed; everything else compares text.
 function walk(
   left: any, right: any, parts: string[], out: DiffChange[]): void {
   if (null == left) {
@@ -94,11 +62,6 @@ function walk(
   const bothMaps = true === left.isMap && true === right.isMap
   const bothLists = true === left.isList && true === right.isList
   if (bothMaps || bothLists) {
-    // The bag's OWN attributes, at pseudo-keys under it: a recursing
-    // bag never compares its own text, so what the children do not
-    // carry has to be compared here. The spread is part of what a bag
-    // MEANS; so are closedness and the marks, which is exactly why the
-    // hash form spells them (G6).
     const lc = null == left.spread.cj ? undefined : hcanon(left.spread.cj)
     const rc = null == right.spread.cj ? undefined : hcanon(right.spread.cj)
     if (lc !== rc) {
@@ -182,9 +145,6 @@ function evalSide(
 }
 
 
-// Diff two documents. Each is evaluated on its own — a document that
-// does not stand up has no meaning to compare, and the report says so
-// rather than diffing a wreck.
 export function diff(
   leftSrc: string, rightSrc: string, opts?: DiffOptions): DiffReport {
   const options = opts ?? {}

package/src/err.ts

@@ -17,17 +17,6 @@ import { hints } from './hints'
 const { errmsg, strinject } = util
 
 
-// COLOUR IS A DECISION ABOUT THE DESTINATION, not about the message.
-// Every error frame hardcoded the ANSI escapes, so a piped report and
-// a `--jsonl` answer carried terminal control codes into whatever read
-// them -- a log file, a CI annotation, an agent's parser (the review's
-// finding F).
-//
-// NO_COLOR (no-color.org: set, to anything, means no colour) turns them
-// off everywhere, library callers included. The CLI additionally turns
-// them off when its stderr is not a terminal, through setColor: a
-// library cannot see the destination, and a caller who has one is the
-// only one who can say.
 let COLOR: boolean | undefined
 
 function setColor(on: boolean | undefined): void {
@@ -38,13 +27,6 @@ function colorActive(): boolean {
   if (null != COLOR) {
     return COLOR
   }
-  // `globalThis` always exists; `process` need not (this library runs
-  // in a browser too), so the optional chain starts at the part that
-  // can actually be missing -- and stays a CHAIN rather than becoming
-  // an `if`, because the browser arm is unreachable from any test this
-  // suite can run and ADR-002 does not accept an arm nothing takes.
-  // Set-but-EMPTY is the documented exception and does not disable
-  // colour (no-color.org).
   const no = (globalThis as any).process?.env?.NO_COLOR
   return null == no || '' === no
 }
@@ -68,15 +50,6 @@ function makeNilErr(
   attempt?: string,
   details?: Record<string, any>
 ): NilVal {
-  // C1-inner: when a DisjunctVal trial is in progress, failures are
-  // transient markers — none of the NilVal fields (site, path,
-  // primary, secondary, details) ever surface to the user because
-  // DisjunctVal replaces the oval entry with TRIAL_NIL and filters
-  // by isNil. Allocating a fresh NilVal per failure (~60k per
-  // foo-sdk run from IntegerVal/BooleanVal/ScalarVal.unify et al.)
-  // is pure waste. Short-circuit to the shared sentinel; push once
-  // to ctx.err so the caller's `trialErr.length > 0` check still
-  // signals failure.
   if (ctx !== undefined && ctx._trialMode === true) {
     if (ctx.err.length === 0) ctx.err.push(TRIAL_NIL)
     return TRIAL_NIL
@@ -86,7 +59,6 @@ function makeNilErr(
 }
 
 
-// TODO: move to utility?
 function descErr<NILS extends NilVal | NilVal[]>(
   err: NILS | any,
   errctx?: ErrContext,
@@ -99,15 +71,6 @@ function descErr<NILS extends NilVal | NilVal[]>(
       let v1src = resolveSrc(v1, errctx)
       let v2src = resolveSrc(v2, errctx)
 
-      // STRICT `!==` against the empty string. The loose `!=` here dropped
-      // the list index 0, because `'' != 0` is FALSE in JavaScript ('' and
-      // 0 are both coerced to 0): `a:[1]&[2]` reported its conflict at
-      // `$.a` while `a:[1,5]&[1,6]` reported `$.a.1`, so the one index a
-      // reader is most likely to meet was the one silently erased, and a
-      // nested `a:[[1]]&[[2]]` lost both segments (issue #37). Numeric
-      // segments arrive here as numbers, so only `===`/`!==` compares them
-      // for what they are. `null != p` stays loose on purpose -- it is the
-      // idiomatic null-and-undefined test.
       let path = ['$', ...err.path].filter((p: any) => null != p && '' !== p)
 
       // '$' is neither null nor '', so the filter always leaves it.
@@ -133,7 +96,6 @@ function descErr<NILS extends NilVal | NilVal[]>(
         '\n',
 
         (null != v1 && errmsg({
-          // TODO: color should come from jsonic config
           color: { active: colorActive(), line: '\x1b[34m' },
           txts: {
             msg: 'Cannot ' + attempt + ' value: ' + v1.canon +
@@ -149,7 +111,6 @@ function descErr<NILS extends NilVal | NilVal[]>(
         })),
 
         (null != v2 && errmsg({
-          // TODO: color should come from jsonic config
           color: { active: colorActive(), line: '\x1b[34m' },
           txts: {
             msg: 'Cannot ' + attempt + ' value: ' + v2.canon +
@@ -169,7 +130,6 @@ function descErr<NILS extends NilVal | NilVal[]>(
         .filter((n: any) => null != n && false !== n)
         .join('\n')
 
-        // TODO: update jsonic errmsg to avoid multiple empty lines
         .replace(/\n\n/g, '\n')
 
     }

package/src/escape.ts

@@ -1,36 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE ESCAPE CONVENTIONS (G9 phase 6, docs/design/TEMPLATE.0.md D4).
-// `esc(s, variant?)` makes a string safe to place inside a literal of
-// the named convention, and `usc` reads it back out.
-//
-// A VARIANT NAMES A CONVENTION, NOT A LANGUAGE, and that is the whole
-// reason it is a variant rather than something a renderer knows:
-// several languages share one convention, and one language has
-// several -- a C-family literal escapes differently in each quote, and
-// SQL spells a literal one way and an identifier another.
-//
-// With no variant it is the C escape, JSON canonical, which covers
-// TypeScript, JavaScript, Java, C, C++, C#, Go, Rust, Swift, Kotlin,
-// Scala and JSON itself. That is why it is the default rather than a
-// lookup.
-//
-// EVERY CONVENTION IS SPELLED OUT HERE rather than borrowed from a
-// host function, and the reason is parity: `JSON.stringify` escapes
-// what Go's `encoding/json` does not (and the reverse), and
-// `encodeURIComponent` leaves `!'()*` alone where RFC 3986 does not.
-// A generated file must be byte-identical whichever engine wrote it,
-// so both ports carry this table and go/escape.go is its twin.
-//
-// `usc` IS THE LEFT INVERSE, AND IT IS PARTIAL. `usc(esc(s))` is `s`
-// for every `s`; `esc(usc(t))` is `t` only for canonically escaped
-// `t`, because several spellings escape to one value. Input with no
-// inverse -- a truncated `\u12`, an undefined `\q`, a lone `'` where
-// the convention doubles it -- is REFUSED (`usc_malformed`), never
-// passed through: a generator that reads a value back out of an
-// artifact and silently gets a different one is the failure this
-// whole pair exists to close.
-
 
 // The variant names, in the order the reference lists them. `none` is
 // not here: it is the absent argument, and the absent argument is the
@@ -38,15 +7,9 @@
 const ESC_VARIANTS = ['sq', 'sql', 'shell', 'xml', 'uri', 'regex']
 
 
-// The regex metacharacters, which are exactly the ones the pattern
-// subset admits as escaped-to-mean-themselves (RE_ESCAPE_PUNCT in
-// ConstraintVal). So `esc(s, regex)` always answers a pattern the
-// subset accepts, which is the point of having the variant at all.
 const ESC_REGEX_PUNCT = '\\.+*?()[]{}|^$/'
 
 
-// The five XML entities, in the order they must be APPLIED: `&` first,
-// or the ampersands of the other four are escaped a second time.
 const ESC_XML: [string, string][] = [
   ['&', '&'],
   ['<', '&lt;'],
@@ -56,10 +19,6 @@ const ESC_XML: [string, string][] = [
 ]
 
 
-// The characters RFC 3986 calls unreserved. Everything else is
-// percent-encoded, byte by byte of its UTF-8, with UPPERCASE hex --
-// the case the RFC prefers, pinned here because the two ports must
-// agree on it.
 const ESC_URI_UNRESERVED =
   'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~'
 
@@ -143,7 +102,6 @@ function unescC(src: string, quote: string): [string, boolean] {
 }
 
 
-// Four hex digits at `at`, or -1 when they are not four hex digits.
 function hex4(src: string, at: number): number {
   if (src.length < at + 4) { return -1 }
   let v = 0
@@ -286,10 +244,6 @@ function unescRegex(src: string): [string, boolean] {
 }
 
 
-// UTF-8 by hand, both ways, because the percent convention is defined
-// over BYTES and the two ports must produce the same ones. TextEncoder
-// would do for the forward direction; the reverse needs the error
-// behaviour spelled out, so both are here.
 function utf8Bytes(ch: string): number[] {
   const c = ch.codePointAt(0) as number
   if (0x80 > c) { return [c] }

package/src/exactjson.ts

@@ -1,62 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-/*
- * D9 -- THE EXACT JSON EMITTER.
- *
- * `generate()` returns NATIVE values, and once a document opts into the
- * exact leaves two of them are not things `JSON.stringify` can write: a
- * biginteger generates as a native `bigint`, and a bigdecimal generates
- * as a `Decimal`. `JSON.stringify` THROWS on a bigint ("Do not know how
- * to serialize a BigInt") and a `replacer` cannot rescue it, because a
- * replacer may only return another *value* -- everything it returns that
- * is not already a JSON primitive gets quoted, so the exact digits could
- * only come back as a JSON *string*, which is a different document.
- *
- * JSON itself was never the obstacle. A JSON number is arbitrary-
- * precision decimal TEXT: `{"x":9007199254740993}` is a perfectly legal
- * document that every conforming parser reads, and Go's `encoding/json`
- * already emits exactly that for a `*big.Int`. Only JavaScript's
- * serialiser stands in the way, so aontu ships its own.
- *
- * WHY THIS IS PUBLIC API and not a CLI internal: D9 promises that an
- * exact value reaches JSON as exact digits. A library consumer whose
- * document contains `0d9007199254740993` has no other supported way to
- * keep that promise -- hiding the only implementation behind the command
- * line would leave the contract unfulfillable from the library. The
- * `aontu` CLI consumes this same export (with `indent`), and so does the
- * shared suite's byte-exact `gens` mode, so there is exactly one set of
- * bytes to keep in step with the Go port.
- *
- * PARITY WITH GO. The output must match Go's
- * `json.Encoder` + `SetEscapeHTML(false)` (see specGens in
- * go/spec_test.go) byte for byte:
- *
- *   - Key order is the order `generate()` produced. Both ports already
- *     sort map keys (see the entries sort in BagVal.gen; Go's encoder
- *     sorts map keys), so neither has to sort again here.
- *   - Strings keep JavaScript's escaping, which is what the `gens` mode
- *     settled on when it turned Go's HTML escaping OFF so that `<`, `>`
- *     and `&` stay literal in both ports. U+2028/U+2029 are the one
- *     place JS and Go disagree by default -- Go escapes them, JS does
- *     not -- so they are escaped here too, which is both legal JSON and
- *     the safer output (it can be embedded in a JavaScript source).
- *   - Numbers keep JavaScript's `Number.prototype.toString` form, which
- *     is already what Go's encoder produces: fixed notation inside
- *     [1e-6, 1e21) and an unpadded, always-signed exponent outside it
- *     (`1e+21`, `1e-7`).
- *   - A bigint writes its digits; a Decimal writes its plain digit form
- *     (`1000.0`, `0.1`, `-1.5`) -- no `0d` marker, since that belongs to
- *     canon and is not JSON, but an integral bigdecimal keeps its `.0`
- *     so the JSON still shows a decimal. Go's `*Decimal.MarshalJSON`
- *     mirrors this.
- *
- * NOTE that byte-exact output CANNOT check the other half of D9: an
- * integral bigdecimal and a biginteger can serialise to different text,
- * but a biginteger and an ordinary integer serialise to the SAME text
- * while `generate()` returned the wrong runtime type. Canon pins the AST
- * kind, `gens` pins these bytes, and only the per-port API tests
- * (ts/test/exactjson.test.ts here) pin the returned object.
- */
 
 import { Decimal } from './val/Decimal'
 import { AontuError } from './err'
@@ -68,9 +11,6 @@ import { cmpCodePoint } from './keyorder'
 const LSPS_RE = new RegExp('[\u2028\u2029]', 'g')
 
 
-// JSON.stringify's `space` argument, normalised the way the spec does:
-// a number is clamped to 0..10 spaces, a string is truncated to 10
-// characters, anything else means "compact".
 function indentUnit(indent: number | string | undefined): string {
   if ('number' === typeof indent) {
     const n = Math.min(10, Math.floor(indent))
@@ -92,18 +32,11 @@ function quote(s: string): string {
 }
 
 
-// True for a value JSON.stringify omits from an object and writes as
-// `null` inside an array. generate() never produces one, but a consumer
-// splicing its own data into the result might.
 function skipped(v: any): boolean {
   return undefined === v || 'function' === typeof v || 'symbol' === typeof v
 }
 
 
-// `seen` tracks the containers on the CURRENT path only (added on entry,
-// removed on exit), so a shared subtree -- which unification can easily
-// produce -- serialises fine and only a true cycle is refused, exactly
-// as JSON.stringify does it.
 function emit(v: any, unit: string, pad: string, seen: Set<any>): string {
   if (null === v) {
     return 'null'
@@ -163,35 +96,6 @@ function emit(v: any, unit: string, pad: string, seen: Set<any>): string {
   else {
     const colon = '' === unit ? ':' : ': '
     const parts: string[] = []
-    // OWN enumerable keys, SORTED. A `for ... in` here would additionally
-    // walk the prototype chain.
-    //
-    // WHY THE SORT IS HERE AND NOT IN gen(). BagVal.gen already sorts map
-    // entries lexicographically -- and then writes them into a plain JS
-    // object, where ECMAScript throws that sort away. OrdinaryOwnPropertyKeys
-    // lists canonical ARRAY-INDEX keys first, in ascending NUMERIC order,
-    // and only then the remaining string keys in insertion order. So
-    // `{9:1,10:2}` came back out as 9 before 10, and `{"!":1,9:2}` put the
-    // digit key ahead of the punctuation one.
-    //
-    // This is not a V8 quirk and not a JSON.stringify quirk; it is the
-    // object's own key order, and it CANNOT be fixed upstream, because no
-    // JavaScript object can hold "10" before "9". The emitter is the last
-    // point that still has the freedom to choose, so it chooses here.
-    //
-    // The giveaway that it was never a design rule: only indices up to
-    // 2^32-2 are hoisted, so `{4294967295:1,4294967296:2,5:3}` emitted as
-    // 5, 4294967295, 4294967296 -- and TypeScript's own CANON, which builds
-    // text from a sorted list rather than from an object, was lexicographic
-    // all along. The port contradicted itself.
-    //
-    // Lexicographic by UTF-16 code unit, which is what `<` on JS strings
-    // does and what MapVal.canon/BagVal.gen already sort by. Go sorts map
-    // keys by UTF-8 byte, and the two orders agree on every key that stays
-    // inside the BMP; astral-plane keys are a separate, tracked divergence.
-    // CODE POINT order (cmpCodePoint), which is what Go's UTF-8 byte sort
-    // produces. A bare .sort() is UTF-16 code-unit order, which puts an
-    // astral key ahead of everything in U+E000-U+FFFF.
     for (const k of Object.keys(v).sort(cmpCodePoint)) {
       const cv = v[k]
       if (skipped(cv)) {
@@ -209,41 +113,6 @@ function emit(v: any, unit: string, pad: string, seen: Set<any>): string {
 }
 
 
-/**
- * Serialise a value produced by `Aontu.generate()` as JSON text,
- * preserving EXACT numbers.
- *
- * Use this instead of `JSON.stringify` on generated output. A document
- * that uses the `0d` exact leaves generates native `bigint` and
- * `Decimal` values; `JSON.stringify` throws on the first and mangles the
- * second, while this emitter writes both as raw JSON numbers with their
- * exact digits -- which is what the D9 generate contract promises, and
- * what the Go port's marshallers produce for the same document.
- *
- * ```ts
- * import { Aontu, exactJSON } from 'aontu'
- *
- * const out = new Aontu().generate('x:0d9007199254740993')
- * typeof out.x           // 'bigint'
- * exactJSON(out)         // '{"x":9007199254740993}'
- * exactJSON(out, 2)      // '{\n  "x": 9007199254740993\n}'
- * JSON.stringify(out)    // TypeError: Do not know how to serialize a BigInt
- * ```
- *
- * @param value   The value to serialise -- normally `generate()` output:
- *                `null`, booleans, numbers, strings, `bigint`,
- *                `Decimal`, arrays and plain objects. An object with a
- *                `toJSON` method is asked for its replacement first
- *                (`Decimal` is handled as a number before that check).
- * @param indent  Optional indentation, with `JSON.stringify`'s `space`
- *                semantics: a number of spaces (clamped to 0..10) or a
- *                literal string. Omitted or `0` gives COMPACT output
- *                (no spaces, no newlines) -- the form the shared spec
- *                suite's `gens` mode compares byte for byte.
- * @returns       The JSON text. Unlike `JSON.stringify` this always
- *                returns a string: a top-level `undefined` is `null`.
- * @throws        {AontuError} if the value contains a reference cycle.
- */
 function exactJSON(value: any, indent?: number | string): string {
   return emit(value, indentUnit(indent), '', new Set())
 } /* node:coverage ignore next 6 */