aontu 0.62.0 → 0.64.0

package/src/patch.ts

@@ -1,58 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// OVERLAY PATCH (G7 phase 5,
-// docs/capability-review/g7-machine-access.md): change a document by
-// APPENDING to an overlay, not by rewriting the file.
-//
-// This is the stage that needs no rewriter. An overlay entry is just
-// another conjunct, and unification is order-independent, so appending
-// `services: auth: owner: "identity-2"` to a second file and
-// evaluating both is exactly the same value as writing it into the
-// first — with no parsing of the target, no comment or layout damage,
-// and nothing to preserve. The spec pins that equivalence rather than
-// asserting it.
-//
-// What an overlay CANNOT do is change a PINNED value: the lattice
-// refuses 5 against 3, and the report says so with the pinning site,
-// which `why` then locates. That left the loop "set → conflict → why →
-// edit the pinning site" with its last step manual — and since the
-// commonest vet failure of all is "the data pins the wrong value",
-// `set` was unable to repair the very case it existed for.
-//
-// IN-PLACE REPLACE (`--in-place`) closes that. The G7 design deferred
-// it behind two prerequisites: an evaluated-path → contributing-span
-// map, and a comment-and-layout-preserving CST. The first now exists —
-// `why` is that map, and sites carry `len` and `src` since a site was
-// given an extent. The second turns out NOT to be needed for the case
-// that matters, and the reason is worth stating: a CST is what you need
-// to RE-SERIALISE a document, and a targeted span splice serialises
-// nothing. It replaces `len` code units at one offset and leaves every
-// other byte — every comment, every blank line, every alignment space —
-// exactly as the author left it, because it never looks at them.
-//
-// What makes the splice safe rather than merely plausible is that the
-// site carries `src`, the text it claims to cover. The span is VERIFIED
-// against it before a byte is written, so the corrupting arithmetic
-// this repository has already shipped once — `port: 0x1F` reporting
-// canon `"31"` at column 7, and `(col, canon.length)` writing
-// `port: 5x1F` — cannot be reached: `0x1F` is four code units and says
-// so, and if the text at the span is anything else the edit is refused
-// rather than guessed.
-//
-// Replace is never WORSE than append. Where the value is not a single
-// editable literal in this overlay — a spread template governing other
-// keys, a reference whose site is the `$` and not the target, two
-// statements pinning the same path, a literal in an included file — the
-// splice is refused and the assignment is APPENDED exactly as it would
-// have been without the flag, plus one `warning` finding naming the
-// case and the site it came from. Warnings never move a verdict, so
-// `--in-place` cannot turn a run that would have succeeded into one
-// that fails; it can only rewrite where rewriting is safe, and explain
-// itself where it is not.
-//
-// The verdict is G2's, unchanged: `vet(entry, overlay)` already asks
-// exactly the right question — does this document hold against that
-// truth, and if not, where — so `set` adds a writer, not a report.
 
 import { vet } from './vet'
 import type { TrustOptions } from './type'
@@ -67,19 +14,10 @@ export type PatchOptions = {
   // them resolve from their own directories (vet's precedent).
   entryPath?: string
   overlayPath?: string
-  // Rewrite a pinned literal where the author wrote it, instead of
-  // appending a line that contradicts it. Opt-in: appending is
-  // non-destructive and in-place editing is not, so the caller says
-  // which one they meant.
   inPlace?: boolean
   // The include capability this document evaluates under
   // (G5, docs/trust.md); vet's precedent.
   trust?: TrustOptions
-  // The extensions an include additionally reads as text (the CLI's
-  // --text-ext). It rides WITH the capability, never beside it: this
-  // verb threaded the capability and not the extension, so `set`
-  // refused an include -- and wrote nothing -- under a flag the bare
-  // command honoured.
   textExt?: string[]
 }
 
@@ -97,13 +35,7 @@ export type PatchReplacement = {
 }
 
 export type PatchReport = {
-  // The overlay text as it would stand after the assignments: the
-  // existing text, with any in-place replacements applied, plus one
-  // appended line for each assignment that was not replaced. The caller
-  // writes it — an engine that touched the filesystem could not be used
-  // by a server, and the CLI is the one place that knows about files.
   overlay: string
-  // The appended lines alone, in order.
   appended: string[]
   // The in-place replacements made, in the order the assignments were
   // given (NOT the order they were applied to the text, which is
@@ -133,23 +65,12 @@ export function parseAssignment(
 }
 
 
-// The path-flattened conjunct one assignment becomes:
-// `$.a.b = 1` is `"a": "b": 1`. Keys are QUOTED — a segment may be a
-// word the grammar spells otherwise (`if`), a number, or a name with
-// a space in it, and quoting one key is the same value as writing it
-// bare.
 export function overlayLine(path: string, value: string): string {
   return pathParts(path).map((p) => JSON.stringify(p)).join(': ') +
     ': ' + value
 }
 
 
-// The character offset of a 1-based (row, col) in `src`, or -1 when the
-// text has no such position. Columns are UTF-16 code units, which is
-// what a site carries and what a JavaScript string index already is —
-// so this is the inverse of the site arithmetic, not a reinterpretation
-// of it (go/patch.go converts to a byte offset, because Go strings are
-// bytes; both address the same character).
 export function offsetAt(src: string, row: number, col: number): number {
   if (row < 1 || col < 1) {
     return -1
@@ -177,27 +98,9 @@ export function spanAt(
 }
 
 
-// DOES THE TEXT AT THIS SITE SAY WHAT THE SITE CLAIMS IT SAYS?
-//
-// The last check before a splice, and the one that makes the write
-// PROVABLE rather than argued. Exported so it can be exercised with a
-// site the engine would never produce — an out-of-range position, a
-// span over different text — which is the only way to test a guard whose
-// whole purpose is to catch a state the rest of the code says cannot
-// happen. (go/patch.go has the twin, tested the same way.)
 export function spanHolds(
   src: string, site: { row: number, col: number, len: number }, expect: string
 ): boolean {
-  // THE SITE'S OWN LENGTH IS PART OF ITS CLAIM, and is checked before
-  // the text is. A site whose `len` disagrees with the text it says it
-  // covers CONTRADICTS ITSELF, which is exactly the state this guard
-  // exists to catch — and a zero-length span would otherwise compare
-  // equal against nothing and then splice nothing, INSERTING the new
-  // value rather than replacing anything.
-  //
-  // Both ports compare in UTF-16 code units, which is what a site's
-  // `len` counts. That is free here and is not in Go, where a string is
-  // bytes (go/patch.go converts).
   if ('' === expect || site.len !== expect.length) {
     return false
   }
@@ -205,68 +108,17 @@ export function spanHolds(
 }
 
 
-// WHY IS THE VALUE AT THIS PATH WHAT IT IS, and is exactly one of the
-// answers a literal this overlay can edit in place?
-//
-// The four refusals below are not defensive padding; each is a real
-// document shape that the probe corpus produced, and each would corrupt
-// something different if the splice ran anyway:
-//
-//   - a SPREAD contribution's site is inside the template, which
-//     governs every other key too, so rewriting it there changes keys
-//     the author did not name;
-//   - a REFERENCE's site is the `$` that starts the path and has length
-//     1, so splicing over it writes the new value INTO the path
-//     expression (`$.base` becomes `5.base`) — and the value the author
-//     wants changed lives at the target anyway;
-//   - TWO literals at one path (a duplicate key, two files merged) give
-//     no single place to edit, and picking either silently is picking
-//     for the author;
-//   - a literal in an INCLUDED file is editable, but not by
-//     `--overlay <this file>`: the write would land in a document the
-//     caller did not name.
-//
-// A PREFERENCE is not refused here for the same reason it is not
-// replaced: appending already overrides a default correctly, so the
-// caller loses nothing by falling through to it.
 function editableLiteral(
   overlaySrc: string,
   path: string,
   overlayPath: string | undefined,
 ): { site: PatchReplacement | undefined, finding: VetFinding | undefined } {
-  // THE AUTHORITY IS THE OVERLAY TEXT ALONE, WITH INCLUDES DENIED.
-  //
-  // The splice happens in the text this function was handed, so what it
-  // has to establish is that the contribution is IN that text — and the
-  // site's `file` cannot establish it. Two ways it fails: a caller of
-  // the library API need not pass `overlayPath`, leaving nothing to
-  // compare against; and the Go port names the ENTRY document for an
-  // included value anyway (issue #66), so the comparison is the overlay
-  // against itself. Either way an included literal's (row, col, len,
-  // src) can COINCIDE with different text at the same coordinates here
-  // — an include holding `a: 42` at 1:4 and an overlay holding `x: 42`
-  // at 1:4 — and the span verification cannot tell them apart, because
-  // the text really does match. The splice then rewrites `x` while
-  // reporting a replacement of `$.a`, in both ports.
-  //
-  // Denying includes removes the ambiguity at its source rather than
-  // detecting it: what resolves is what this text says by itself. An
-  // overlay that loads other documents therefore cannot be edited in
-  // place at all — the conservative answer, and the assignment still
-  // appends. It costs nothing in the shape `set` is for, an overlay it
-  // owns and appends to, and it does not depend on file attribution, so
-  // both ports agree without waiting on #66.
   const alone = why(overlaySrc, path, {
     trust: { include: 'none' },
     ...(null == overlayPath ? {} : { path: overlayPath }),
   })
 
   if (true !== alone.ok || null == alone.record) {
-    // Nothing here BY ITSELF. Two very different reasons, and they earn
-    // different answers: the path may simply not be in this overlay, in
-    // which case appending is the whole of the answer and nothing has
-    // gone wrong — or it may be here only because something was loaded,
-    // which is the case above and has to say so.
     const withLoads = why(overlaySrc, path,
       null == overlayPath ? undefined : { path: overlayPath })
     if (true !== withLoads.ok || null == withLoads.record) {
@@ -290,14 +142,6 @@ function editableLiteral(
   // coverage gate says so, an arm nothing can take.
   const conjuncts: WhyConjunct[] = record.conjuncts
 
-  // A VALUE REACHED THROUGH A REFERENCE IS NOT THIS PATH'S TO EDIT.
-  // Provenance travels through clones now, so `n: $.base` against
-  // `base: 7` reports the literal `7` -- correctly, and at the site
-  // where it was written, which is `base`'s line and not `n`'s. A
-  // splice there would rewrite the REFERENT: every other reader of
-  // `$.base` changes with it, and the path the caller named does not
-  // move at all. The reference is what stands here, so the reference
-  // is what has to be edited, wherever it points.
   const refs = conjuncts.filter((c) => 'ref' === c.role)
   if (0 < refs.length) {
     return {
@@ -343,17 +187,6 @@ function editableLiteral(
 }
 
 
-// THE SPAN MUST CHECK OUT before anything splices. The refusal arm is
-// unreachable through `patch` since ADR-018: the pipe (`x: hello |>
-// upper`) was the one spelling that synthesised a contribution the
-// parser never sited, and denying includes means every WRITTEN
-// contribution's coordinates describe this text by construction. The
-// verification is kept rather than deleted — splicing without it would
-// corrupt the file (a contribution with no `src` would splice ZERO
-// characters, INSERTING the new value into the middle of a line) — and
-// this last step is its own exported seam so the refusal can be tested
-// directly, against conjuncts the engine would never produce, on the
-// same footing as `spanHolds` itself.
 export function verifiedSite(
   overlaySrc: string,
   path: string,
@@ -371,29 +204,6 @@ export function verifiedSite(
     return { site: undefined, finding }
   }
 
-  // DOES THE SPAN MEAN THE WHOLE CONTRIBUTION?
-  //
-  // This is the check that `role === 'literal'` looks like it makes and
-  // does not. A site names the TOKEN it points at, so a COMPOUND value
-  // reports its OPENING token while its canon is the whole thing:
-  // `min(1)` is a literal-role contribution whose src is `min`, `1+2`
-  // reports `1`, `$.k+1` reports `$`, `{b:1}` reports `{` and `[1,2]`
-  // reports `[`. Splicing over any of those writes the new value INTO
-  // the expression — `a: 5(1)`, `a: 5+2`, `a: 5.k+1` — which is the
-  // same class of corruption as the canon-length arithmetic, reached by
-  // a different route.
-  //
-  // Rather than enumerate the shapes (a list is a thing to be
-  // incomplete about), ASK THE ENGINE: parse `src` on its own and
-  // require the value it means to be the value the contribution
-  // contributed. That is exactly the property a splice needs — this
-  // text, alone, is this value — and it is decided by the same unifier
-  // that produced the contribution, so it cannot drift from it.
-  //
-  // It also gets the interesting case right without special-casing it:
-  // `0x1F` canons to `31`, which is not its own spelling, but IS the
-  // contribution's canon, so a hex literal is editable while `min` is
-  // not.
   const span = spanValue(one.src)
   if (null == span || span.canon !== one.canon) {
     return {
@@ -407,11 +217,6 @@ export function verifiedSite(
     }
   }
 
-  // AN ABSTRACT CONTRIBUTION IS NOT A PIN. `a: integer` and
-  // `a: above(0)` state a constraint, and appending already narrows
-  // them — that is the one case the status report notes `set` could
-  // always repair. Replacing them would silently DISCARD a constraint
-  // the author wrote, to no benefit, so this falls through to append.
   if (true !== span.concrete) {
     return {
       site: undefined,
@@ -436,21 +241,8 @@ export function verifiedSite(
 }
 
 
-// What does this source text mean ON ITS OWN, and is it a value rather
-// than a constraint? Undefined when it does not stand alone at all
-// (`$` from a path, an unbalanced `{`).
-//
-// The wrapper key is arbitrary and the document it makes is thrown
-// away; what is wanted is the unifier's own reading of the fragment.
 export function spanValue(
   src: string): { canon: string, concrete: boolean } | undefined {
-  // NO COLLECTING CONTEXT: `unify` THROWS on a source it cannot read,
-  // so a ctx.err check here is a branch nothing can reach — the catch
-  // below is the only path a bad fragment takes. (A first draft had
-  // both, and the coverage gate called the pair what it was.) What the
-  // nil test still earns is the fragment that PARSES and means nothing:
-  // `$` is a path with no target, and answers a nil rather than
-  // throwing.
   let canon: string
   try {
     const root: any = new Aontu().unify('v: ' + src)
@@ -477,11 +269,6 @@ export function spanValue(
 }
 
 
-// A refusal to replace, as a WARNING: the assignment still appends, so
-// nothing about the run got worse and the verdict must not move
-// (ts/src/vet.ts, "warnings never touch the verdict"). What the finding
-// adds is the reason, which is the whole value of asking for --in-place
-// over plain set.
 function notEditable(
   code: string, path: string, why: string, from: WhyConjunct[]
 ): VetFinding {
@@ -508,12 +295,6 @@ function notEditable(
 }
 
 
-// Append the assignments to the overlay and answer what the result
-// holds. The report's verdict is the vet verdict of the ENTRY against
-// the new overlay: `valid` when it holds and is concrete, `incomplete`
-// when nothing contradicts but the truth is not yet satisfied,
-// `invalid` when the overlay contradicts a pinned value, `error` when
-// the entry itself does not stand up.
 export function patch(
   entrySrc: string,
   overlaySrc: string,
@@ -555,9 +336,6 @@ export function patch(
         notes.push(found.finding)
       }
       if (null != found.site) {
-        // Two assignments naming the same path would splice the same
-        // span twice. The second is the one the author wrote last, so
-        // it wins — and the first is dropped rather than layered.
         const at = offsetAt(overlaySrc, found.site.row, found.site.col)
         const dup = edits.findIndex((e) => e.at === at)
         const edit = { at, len: found.site.from.length, to: a.value }
@@ -578,10 +356,6 @@ export function patch(
 
   const overlay = joinOverlay(applyEdits(overlaySrc, edits), appended)
 
-  // The file names ride as URLs as well as base paths, so a finding
-  // names the entry and the overlay rather than vet's generic
-  // `schema`/`data` labels — with two documents that both belong to
-  // the caller, "which file" is the whole question.
   const report: VetReport = vet(entrySrc, overlay, {
     trust: options.trust,
     textExt: options.textExt,
@@ -604,8 +378,6 @@ export function patch(
 }
 
 
-// Apply the collected splices back to front, so an earlier edit's
-// offset is never invalidated by a later one having already run.
 function applyEdits(
   src: string, edits: { at: number, len: number, to: string }[]
 ): string {
@@ -620,10 +392,6 @@ function applyEdits(
 }
 
 
-// One line per assignment, after whatever the overlay already said. A
-// trailing newline is kept when the file had one and added when it
-// did not: a file that does not end in a newline is still a file, and
-// appending to it must not join two entries into one line.
 function joinOverlay(overlaySrc: string, appended: string[]): string {
   if (0 === appended.length) {
     return overlaySrc

package/src/profile.ts

@@ -0,0 +1,42 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+
+import { Aontu } from './aontu'
+import { vet, failureFinding } from './vet'
+import { hcanon } from './hcanon'
+import { includeOpts } from './utility'
+
+import type { IncludeOptions } from './utility'
+import type { VetFinding } from './vet'
+
+
+export type ProfileOptions = IncludeOptions & {
+  // Where the document CAME FROM, so a relative `@"file"` load inside
+  // it resolves from its own directory.
+  path?: string
+}
+
+
+const PROFILE_VOCABULARY = '@"aontu:profile"'
+
+
+// A language declared as data, vetted, or the findings that refuse it.
+export function loadProfile(src: string, options?: ProfileOptions):
+  { profile?: any, errors?: VetFinding[] } {
+  const opts = options ?? {}
+  const aontu = new Aontu(includeOpts(opts))
+  const actx = aontu.ctx({ collect: true })
+  const root: any = aontu.unify(src, { path: opts.path, collect: true }, actx)
+  if (0 < actx.err.length || true === root?.isNil) {
+    return { errors: [failureFinding(actx, opts.path, root)] }
+  }
+  const report = vet(PROFILE_VOCABULARY, hcanon(root))
+  if ('valid' !== report.verdict) {
+    return { errors: report.findings }
+  }
+  // The meet: the vocabulary requires `lang`, so a value the vet
+  // admitted has a `Lang`.
+  const instance = new Aontu().generate(
+    PROFILE_VOCABULARY + '\naontu: Lang: ' + hcanon(root.peg.aontu.peg.Lang))
+  return { profile: instance.aontu.Lang }
+}

package/src/provenance.ts

@@ -1,33 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE PROVENANCE RECORDER (G7 phase 3,
-// docs/capability-review/g7-machine-access.md): what CONTRIBUTED to
-// the value at a path, in order, with the site each contribution was
-// written at. `why` is the positive twin of G2's error report — errors
-// explain what failed to unify, this explains what did.
-//
-// The recorder rides the CONTEXT and is off by default: `unite` pays
-// one property load on the normal path, and an instrumented run pays
-// site materialisation knowingly. It records at `unite` and nowhere
-// else, because that is the one place every meet passes through — the
-// same reason G3's deprecation rider lives there. A meet is where
-// information currently vanishes, so a meet is what to record.
-//
-// Contributions are the operands that were NOT produced by an earlier
-// meet at the same path: a value that a previous meet made is an
-// intermediate, not a source. Deduplicated by (path, val id) — ids are
-// unique per run — so fixpoint revisits across up to `maxcc` passes do
-// not multiply the record.
-//
-// Roles come from the operand itself, with no further instrumentation:
-// a reference is still a RefVal when it meets its peer (its canon is
-// the path it names), a preference is still a PrefVal (its canon is
-// the `*` form), and a spread-applied template is marked once where
-// the spread is applied. Precedence is spread > ref > pref > literal:
-// a preference INSIDE a spread template is a spread contribution,
-// which is what the author needs to be told.
-
-
 
 export type WhyRole = 'literal' | 'spread' | 'ref' | 'pref'
 
@@ -36,8 +8,6 @@ export type WhyRole = 'literal' | 'spread' | 'ref' | 'pref'
 export type WhySite = {
   col: number
   file: string
-  // The extent in UTF-16 code units, or -1 when unknown. The same
-  // field, and the same meaning, as VetSite.len (ts/src/vet.ts).
   len: number
   row: number
 }
@@ -46,20 +16,7 @@ export type WhyConjunct = {
   canon: string
   role: WhyRole
   site: WhySite
-  // The SOURCE TEXT this contribution was written as.
-  //
-  // `canon` is the value; `src` is the spelling. They are not the same
-  // thing, and the difference is the whole reason this record exists:
-  // `port: 0x1F` contributes canon `31` from source `0x1F`, so a reader
-  // told only the canon cannot find, verify or replace what was
-  // actually written. Empty when the contribution occupies no source —
-  // a value unification minted rather than a document wrote.
   src: string
-  // The PREFERENCE RANK, 0-based, when the contribution is one: `*x`
-  // is 0, `**x` is 1. Absent for anything else. The engine's own
-  // number (PrefVal.rank), so a reader arbitrating between ranked
-  // contributions -- the meet ladder -- need not count stars in a
-  // canon string.
   rank?: number
 }
 
@@ -75,77 +32,12 @@ export type WhyRecord = {
 export const FROM_SPREAD = '_fromSpread'
 
 
-// THE AUTHORED MARK, and it is a property of the VALUE rather than a
-// set of ids held beside it (the review's finding E). A contribution
-// is a value the author wrote, and the recorder used to decide that by
-// looking the operand's id up in a set stamped over the parsed tree --
-// which is true of the parsed tree and of nothing derived from it. So
-// every value that reached a path through a CLONE was dark: a default
-// flowing into a `pack()`-generated child, a shape carried by a `$ref`,
-// a value a spread template stamped. `why` answered "(no contributions:
-// nothing met at this path)" over a value it had just printed, with
-// exit 0 -- a false statement, and the one an audit surface may not
-// make (use-cases/BUGS.md §23, §24).
-//
-// A clone of a written value IS that written value, re-instantiated
-// somewhere else: it carries the author's site, so it can be pointed
-// at. Val.clone therefore carries this mark, exactly as it carries the
-// site -- provenance is part of the clone contract, not a recorder
-// bolted beside it. Values the engine MINTS (a kind lifted while a
-// disjunct trials its members, a fold's intermediate) are constructed
-// rather than cloned and stay unmarked, which is what keeps the record
-// to what the author can edit.
-//
-// The mark is only ever SET by an instrumented run (`why` calls
-// writtenFrom; nothing else does), so an ordinary evaluation pays one
-// undefined property read per clone.
 export const WRITTEN = '_written'
 
 
-// THE CONTAINER A VALUE IS PART OF, when the two stand at the SAME
-// path: a junction's members, a preference's inner value, a function's
-// arguments, an operator's operands. `*1|integer` is one thing the
-// author wrote, and `*1` is not a second thing beside it.
-//
-// The recorder already knew that where the container itself met
-// something -- contributing it marked its members `inside` and the
-// filter dropped them. But the container only appears as an operand
-// when the fixpoint happens to meet it whole; where it resolves
-// member-wise instead (a later sibling of a spread, a default reaching
-// a generated child) the members arrived alone and the record split
-// one written value into two contributions at two columns. Which
-// happened was decided by evaluation order, so `why` answered
-// differently for identical statements (use-cases/BUGS.md §22).
-//
-// So the relation is recorded as a fact about the DOCUMENT, at
-// stamping time, and an operand is reported as the outermost written
-// value it is part of. NOT set for a bag's children (they stand at
-// their own, deeper paths) nor for a conjunct's terms (a conjunct is
-// the statement that several things must all hold, and each term is
-// one of them -- which is exactly what the author needs shown).
 export const INNER_OF = '_innerOf'
 
 
-// Mark a spread clone and everything inside it, so a contribution
-// several levels down a template is still known to have come from the
-// template. ONLY on an instrumented run: the walk is O(template) per
-// key per pass, which is real money on a large model and buys nothing
-// when no one is recording.
-//
-// THE GUARD IS A CYCLE GUARD, NOT A "DONE" FLAG, and that distinction
-// is the whole of the review's finding E for sibling position. A
-// template is applied once per destination, and the fixpoint advances
-// values IN PLACE between those applications (AGENTS.md, the mutation
-// caveat): by the time the second key is spread, the template's
-// `replicas` child is no longer the disjunction the first key saw but
-// the value that meet produced. Skipping the walk because the
-// CONTAINER was already marked left every one of those replacements
-// unmarked, so `why` at the first sibling reported the written
-// `*1|integer` as one contribution and at the second reported `*1` and
-// `integer` as two -- identical statements, different answers, decided
-// by which key the fixpoint reached first (use-cases/BUGS.md §22).
-// Marking is idempotent, so re-walking costs a pass and changes
-// nothing where nothing moved.
 export function markSpread(v: any, seen?: Set<any>): void {
   const marked = seen ?? new Set<any>()
   if (null == v || true !== v.isVal || marked.has(v)) {
@@ -189,10 +81,6 @@ function samePathKids(v: any): any[] {
 }
 
 
-// Order contributions the way the document reads: by file, then row,
-// then column, with the canon as the last tiebreak so the order is
-// total even for two values written at the same position (which a
-// merged duplicate key can produce).
 function cmpSite(a: Contribution, b: Contribution): number {
   return a.site.file.localeCompare(b.site.file) ||
     a.site.row - b.site.row ||
@@ -231,20 +119,8 @@ type PathRecord = {
 export class Provenance {
   paths: Map<string, PathRecord> = new Map()
 
-  // id -> the written container it names, for INNER_OF. The mark on a
-  // value is the container's ID rather than the container itself: a
-  // Val holding another Val as an own property is a reference cycle
-  // through the tree, and enough of the engine walks a value's own
-  // properties that one is not safe to introduce.
   containers: Map<number, any> = new Map()
 
-  // Stamp the parsed tree with the AUTHORED mark: everything the
-  // author wrote, before unification starts. A value minted during
-  // unification — a kind lifted from a leaf while a disjunct trials
-  // its members, a fold's intermediate — is the engine's own work, not
-  // a contribution the author can be pointed at. A CLONE of a marked
-  // value keeps the mark (see WRITTEN above), because it is the same
-  // written value somewhere else. Called once, before unify, by `why`.
   writtenFrom(v: any): void {
     if (null == v || true !== v.isVal || true === v[WRITTEN]) {
       return
@@ -294,9 +170,6 @@ export class Provenance {
   }
 
   private contribute(rec: PathRecord, v: any): void {
-    // TOP is the unit element and a nil is a failure, neither of which
-    // is information the author wrote. A value an earlier meet MADE is
-    // an intermediate; the source that made it is already recorded.
     if (null == v || true !== v.isVal || true === v.isTop || true === v.isNil ||
       rec.made.has(v.id) || rec.seen.has(v.id)) {
       return
@@ -318,11 +191,6 @@ export class Provenance {
     if (true !== v[WRITTEN] && true !== v[FROM_SPREAD]) {
       return
     }
-    // A CONJUNCT is not one contribution, it is the statement that
-    // several must all hold — duplicate keys merged at parse, an
-    // explicit `a & b`. Its own site is nowhere (the merge has no
-    // source position), while its terms each have one, which is what
-    // the author needs to be shown.
     if (true === v.isConjunct && Array.isArray(v.peg)) {
       rec.seen.add(v.id)
       for (const term of v.peg) {
@@ -348,18 +216,6 @@ export class Provenance {
     })
   }
 
-  // THE VALUE THAT STANDS at a path is a contribution when nothing met
-  // there and the author wrote it. A meet is where information
-  // vanishes, so a meet is what the recorder watches -- but a
-  // generator PLACES a value without meeting anything, and `why` then
-  // answered "(no contributions: nothing met at this path)" over a
-  // value it had just printed. That is literally true and practically
-  // false: the author is asking where the value came from, and it came
-  // from somewhere they can be shown (use-cases/BUGS.md §23).
-  //
-  // Only when the record is otherwise EMPTY. Where something did meet,
-  // the standing value is that meet's result -- an intermediate, and
-  // the recorder's oldest rule is that a result is not a source.
   stands(path: string[], v: any): void {
     const key = path.join('.')
     const rec = this.paths.get(key)
@@ -369,50 +225,11 @@ export class Provenance {
     this.record(path, v, undefined, undefined)
   }
 
-  // The record at one path. Empty when nothing met there and nothing
-  // the author wrote stands there either — which is a true and useful
-  // answer rather than an error.
-  //
-  // ONLY WHOLE WRITTEN VALUES are contributions. A Val's own unify
-  // re-enters `unite` at the same path — a disjunct trials each member
-  // there, a constraint meets its atoms there — and those members are
-  // PARTS OF one written value, not further values beside it. That is
-  // settled BEFORE a member is ever pushed, by the INNER_OF fact
-  // stamped over the document (see `contribute`), which is why no
-  // filter runs here: a per-path "inside" set used to do it, and it
-  // could only work where the container itself happened to meet
-  // something at the same path — the order-dependence finding E
-  // records.
   at(path: string[]): WhyConjunct[] {
     const rec = this.paths.get(path.join('.'))
     if (null == rec) {
       return []
     }
-    // SOURCE ORDER, not meet order: the two are the same in simple
-    // cases and diverge with the fixpoint's fold order, which is an
-    // engine detail and a parity risk. Sites are parse data, identical
-    // in both ports, so ordering by them makes the record read as the
-    // document reads and pins it across implementations.
-    // ONE WRITTEN TOKEN IS ONE CONTRIBUTION, and the SITE is what
-    // identifies it -- not the val id, and not the canon.
-    //
-    // Not the id, because provenance travels through clones now: a
-    // written value and a clone of it are the same statement in the
-    // same place, and a path that met both would list it twice.
-    //
-    // Not the canon, because the same written value reaches a path at
-    // different stages of narrowing -- `3|(1|2)` as the author wrote
-    // it and `3|1|2` after a fold -- and both name one token.
-    //
-    // Not the role either: the role says how the value REACHED this
-    // path, not which value it is, and one written value can reach a
-    // path both ways (a template applied to a key whose value is also
-    // written there). Keeping the literal would throw away the more
-    // informative half, so the roles have a precedence.
-    //
-    // ONLY WHERE THE SITE IS REAL. An unsited contribution (row -1)
-    // cannot be told apart from another unsited one, so those are kept
-    // as they come rather than collapsed into whichever arrived first.
     const shown = new Map<string, Contribution>()
     const order = ['spread', 'ref', 'pref', 'literal']
     const out: Contribution[] = []