aontu 0.61.0 → 0.63.0

package/src/mcp.ts

@@ -1,29 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// THE MCP TOOL LIBRARY (G7 phase 6,
-// docs/capability-review/g7-machine-access.md; completed to the full
-// CLI verb surface by the use-case review's MCP recommendation,
-// use-cases/SUPPORT.md): the verbs an agent calls, over the Model
-// Context Protocol, as a transport-free library. The split follows
-// the LSP's (docs/lsp.md): this file is the protocol and the tools,
-// ts/src/mcp-server.ts is stdio and nothing else, and the whole thing
-// is testable without a socket.
-//
-// Every tool returns THE SAME JSON CONTRACT THE CLI PRINTS. That is
-// the point of the surface: an agent that has read `aontu vet
-// --format json` output knows what the `vet` tool answers, and a
-// report copied from one to the other is the same object. The tools
-// add no vocabulary of their own.
-//
-// The server evaluates under a CONFINED resolver (G5, docs/trust.md):
-// a caller hands source text, and text that could reach out through
-// `@"..."` is exactly what a server must not run unconfined. By
-// default every include is denied; a server started with
-// `--root <dir>` (ts/src/mcp-server.ts) resolves includes confined
-// below that root instead — the CLI's `--trust root:<dir>` posture —
-// and lets every document argument arrive as a `<name>Path` file
-// under the same root. The package-resolver leg is never enabled
-// here.
 
 import { readFileSync, realpathSync } from 'node:fs'
 import {
@@ -71,7 +47,6 @@ export type McpResponse = {
 }
 
 
-// JSON-RPC's own codes, the three a server this small can raise.
 const PARSE_ERROR = -32700
 const METHOD_NOT_FOUND = -32601
 const INVALID_PARAMS = -32602
@@ -91,13 +66,6 @@ export type ToolDef = {
   // Argument validation beyond "required and a string": the message
   // for a call that could not be made, or undefined for a good call.
   check?: (a: any) => string | undefined
-  // ENGINES THAT TAKE NO TRUST PROFILE (subsume, trimCheck,
-  // relationCheck, patch) build their own evaluators, so the served
-  // profile cannot ride into them as an argument the way it rides
-  // into vet or get. Their documents are PRE-PARSED under the profile
-  // by callTool instead (confinedParseFailure below), and `refuse` is
-  // the tool's own error report for a document that fails it. A tool
-  // whose engine takes `trust` directly declares no `refuse`.
   refuse?: (
     a: any, finding: VetFinding, trust: TrustOptions,
     paths: Record<string, string>) => any
@@ -106,22 +74,6 @@ export type ToolDef = {
 }
 
 
-// The trust profile a served evaluation runs under: no includes at
-// all — or, when the server was started with --root, includes
-// realpath-confined below that root (the CLI's `--trust root:<dir>`
-// semantics; docs/trust.md). The package-resolver leg is enabled by
-// neither.
-//
-// The profile is INJECTED into every tool by callTool rather than
-// applied by each tool for itself. That is deliberate: four of the six
-// original tools once called the library with no profile at all, so a
-// served `@"x.js"` was require()d in the server process, while the
-// module header claimed confinement. (That particular include is
-// refused outright now -- ADR-012 -- but a served document could still
-// read every file the server can.) A tool that must remember to
-// confine itself is a tool that eventually forgets, and the forgetting
-// is silent. With the profile arriving as an argument, a tool cannot
-// run unconfined without visibly discarding it.
 export function servedTrust(root?: string): TrustOptions {
   return null == root
     ? { include: 'none' }
@@ -133,17 +85,6 @@ function served(trust: TrustOptions): Aontu {
 }
 
 
-// DOES THIS DOCUMENT STAND UP UNDER THE SERVED PROFILE — or the
-// finding that says why not. This is the confinement gate for the
-// engines that take no trust profile, and parse is the whole include
-// story: `@"..."` resolves at parse time (ts/src/lang.ts), so a
-// document whose confined parse is clean either has no includes at
-// all (capability 'none') or resolves every one below the root — and
-// an engine that then re-resolves the same closure under the default
-// profile reads exactly the files the confined parse proved in
-// bounds. A parse that fails for any reason refuses the call: an
-// engine's own answer for a document this profile cannot read is not
-// an answer this server may compute.
 export function confinedParseFailure(
   src: string, trust: TrustOptions, path?: string
 ): VetFinding | undefined {
@@ -154,18 +95,6 @@ export function confinedParseFailure(
 }
 
 
-// Confinement is realpath-then-prefix-check, mirroring the include
-// resolver's own rule (ts/src/lang.ts, docs/trust.md): the file's
-// real path must sit below the root's real path, so a symlink inside
-// the root pointing outside it is an escape, not a loophole.
-//
-// A path that does not (fully) exist cannot be realpath'd whole, and
-// falling back to the LEXICAL form compares apples to oranges when the
-// root itself sits behind a symlink -- on macOS a root under /var
-// realpaths to /private/var, so a merely-missing file inside it read
-// as an escape instead of "cannot read" (the CI failure that bought
-// this comment). Realpath the deepest EXISTING ancestor and re-attach
-// the rest, so both sides of the prefix check are in real coordinates.
 function realpathOf(p: string): string {
   try {
     return realpathSync(p)
@@ -301,8 +230,6 @@ const TOOLS: ToolDef[] = [
     run: (a, trust, paths) => summaryOf(str(a.src), trust, paths.src),
   },
 
-  // The evolution and change verbs (the use-case review's "MCP is a
-  // read-only subset" gap, use-cases/09-agent-tools/README.md gap 11).
 
   {
     name: 'subsume',
@@ -419,11 +346,6 @@ const TOOLS: ToolDef[] = [
     },
     required: ['source'],
     docs: ['source'],
-    // The pre-parse finding rides `errors`, exactly where the engine
-    // puts its own reason for a document that does not stand up
-    // (ts/src/relation.ts, the review's finding F). NOT `findings`:
-    // RelationFinding is its own vocabulary (code, relation, at,
-    // detail) and a document with no graph has no graph findings.
     refuse: (_a, finding) =>
       ({ verdict: 'error', findings: [], errors: [finding] }),
     run: (a, _trust, paths) =>
@@ -644,9 +566,6 @@ const TOOLS: ToolDef[] = [
     },
     required: ['source'],
     docs: ['source'],
-    // The pre-parse finding rides `errors`, exactly where the engine
-    // puts its own reason for a document that does not stand up
-    // (ts/src/trim.ts, the review's finding F).
     refuse: (_a, finding) =>
       ({ verdict: 'error', redundant: [], errors: [finding] }),
     run: (a, _trust, paths) =>
@@ -784,15 +703,6 @@ function hashOf(
 }
 
 
-// ---------------------------------------------------------------------
-// THE BREAKING POLICY WRAPPER. Re-implemented from ts/src/cli.ts
-// (runBreaking and policyCompat) rather than extracted from it: cli.ts
-// owns the process-facing halves — files, git revisions, exit codes,
-// rendering — that a served tool must not import, and the policy
-// itself (which mode applies, which side is general, how verdicts
-// aggregate) is small enough that a shared home would be all seam.
-// cli.ts is the reference; a change there is a change here.
-
 type BreakingMode = 'backward' | 'forward' | 'full' | 'none'
 
 // Verdict aggregation: an error anywhere makes the run an error;
@@ -844,8 +754,6 @@ function policyCompatOf(
 }
 
 
-// The declared mode: the mode argument overrides the document's own
-// policy; neither means backward (v1-valid documents stay valid).
 function breakingMode(
   a: any, trust: TrustOptions, paths: Record<string, string>
 ): BreakingMode {
@@ -867,8 +775,6 @@ function breakingOf(
     new: { src: str(a.new), url: paths.new ?? 'new', path: paths.new },
   }
 
-  // backward: the NEW document is the general side — every old
-  // instance must still be admitted. forward: the old one is.
   const checks: Array<{
     general: typeof sides.old, specific: typeof sides.old
   }> = []
@@ -898,11 +804,6 @@ function breakingOf(
 }
 
 
-// ---------------------------------------------------------------------
-// The set tool: the CLI's `set` verb minus the filesystem — the patch
-// engine (ts/src/patch.ts) already answers with the new overlay text,
-// and the caller owns the write.
-
 // The assignments arrive structured ({path, value}) rather than as the
 // CLI's `<path>=<value>` spelling, and are re-joined for the engine's
 // parseAssignment — so the path must not smuggle a `=` that would move
@@ -937,12 +838,6 @@ function setError(overlay: string, finding: VetFinding): any {
 
 function setOf(
   a: any, trust: TrustOptions, paths: Record<string, string>): any {
-  // THE ASSIGNMENT VALUES ARE DOCUMENTS TOO: each one is appended (or
-  // spliced) into the overlay and evaluated there by the engine's
-  // final vet, so a value that smuggles an include — or a newline and
-  // then an include — gets the same confined pre-parse as the
-  // documents themselves, wrapped exactly as the engine's own
-  // spanValue wraps a fragment (ts/src/patch.ts).
   for (const x of a.assignments) {
     const denied = confinedParseFailure('v: ' + x.value, trust, paths.overlay)
     if (null != denied) {
@@ -960,13 +855,6 @@ function setOf(
 }
 
 
-// ---------------------------------------------------------------------
-// The tool list as MCP spells it: a name, a description, and a JSON
-// Schema for the arguments. With a served root, every document
-// property gains its `<name>Path` file alternative — and comes OFF the
-// `required` list, because JSON Schema's `required` cannot say "one of
-// the two"; callTool's own argument check still refuses a call that
-// carries neither.
 export function toolList(root?: string): any[] {
   return TOOLS.map((t) => {
     const properties: Record<string, any> = { ...t.properties }
@@ -1000,17 +888,6 @@ function refusal(text: string): any {
 }
 
 
-// One tool call. A tool that REFUSES (an invalid document, a path that
-// names nothing, a document the served profile cannot read) is not a
-// protocol error: it answers with its own report and `isError` false,
-// because the report IS the answer the agent asked for. `isError` is
-// reserved for a call that could not be made at all — an unknown tool,
-// a missing or malformed argument, a file argument the server cannot
-// serve.
-// `opts.tools` is injectable for the same reason the watch loop's
-// waiter is: the catch below is defensive code no document reaches --
-// every verb answers with a report rather than throwing -- and code
-// the suite cannot execute is code the ADR-002 floor cannot hold.
 export function callTool(
   name: string, args: any,
   opts?: { root?: string, tools?: ToolDef[] }): any {
@@ -1024,13 +901,6 @@ export function callTool(
   const a: any = { ...(args ?? {}) }
   const paths: Record<string, string> = {}
 
-  // THE FILE ALTERNATIVES (--root). A document that did not arrive as
-  // inline text may arrive as a `<name>Path` file — served only when
-  // the operator granted a root at startup, confined below it by the
-  // same realpath rule the include resolver applies, and recorded in
-  // `paths` so the engine resolves the file's own relative includes
-  // from its directory (the CLI's rule for a named file). Inline text
-  // wins when a caller sends both.
   for (const doc of tool.docs ?? []) {
     if ('string' === typeof a[doc]) {
       continue

package/src/mod-tool.ts

@@ -1,22 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// MODULE TOOLING (G6 phase 3, docs/capability-review/g6-distribution.md):
-// the LOCAL half — `aontu mod tidy`, `verify`, `vendor` and
-// `manifest`.
-//
-// Evaluation never touches the network, and neither does this: `tidy`
-// resolves versions and rewrites the lockfile from what is already in
-// the local stores, `verify` asks whether the stores still MEAN what
-// the lockfile pins and changes nothing, and `vendor` materialises the
-// locked closure into the project. Fetching and publishing are the
-// network half, and are not in this build (see the register).
-//
-// MINIMUM VERSION SELECTION, not a solver: each module declares the
-// MINIMUM version of each dependency it needs, and the selected version
-// is the maximum of those minima over the closure. Deterministic, and
-// deterministic without backtracking — the lockfile CONFIRMS the
-// resolution rather than determining it, which is why a tidy run can be
-// re-run to the same bytes.
 
 import {
   readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync,
@@ -37,11 +20,7 @@ export type ModLock = {
   mod: string
   // The selected version.
   v: string
-  // The canon-hash of the module as it is in the local store.
   canon: string
-  // The registry digest, carried over from a previous lockfile. Empty
-  // when nothing has ever fetched this module: the OCI pin is the
-  // registry's word, and only a fetch can hear it.
   oci: string
 }
 
@@ -49,22 +28,12 @@ export type ModTidyReport = {
   verdict: 'ok' | 'missing' | 'error'
   // The resolved closure, sorted by module.
   lock: ModLock[]
-  // Modules named by a dependency but present in no local store, sorted.
   missing: string[]
-  // Modules present in a store but which DO NOT EVALUATE standalone,
-  // sorted. A pin is what a module MEANS, so there is nothing to pin
-  // here and the lockfile is left alone.
   unevaluable: string[]
 }
 
 export type ModVerifyReport = {
-  // `ok` the lockfile covers what the project declares and every
-  // locked module still means what it pins; `mismatch` at least one
-  // does not; `unlocked` the lockfile does not cover the project's own
-  // dependencies; `missing` at least one locked module is not in any
-  // store. In that order of precedence, most specific first.
   verdict: 'ok' | 'mismatch' | 'unlocked' | 'missing'
-  // The locked modules that verified, sorted.
   verified: string[]
   // What the lockfile pins against what the store now means, for each
   // module that does not match, sorted by module.
@@ -85,19 +54,9 @@ export type ModVendorReport = {
 }
 
 
-// What the tooling needs from the engine, injected for the reason
-// ts/src/mod.ts's ModuleEval is: evaluating a module is what the
-// evaluator does, and the tooling is a caller of it rather than a
-// second implementation.
 export type ModToolEval = (src: string, path: string) =>
   {
     gen: any, hash: string, canon: string,
-    // DID IT STAND UP ON ITS OWN? A module that does not evaluate has
-    // no meaning to pin, and `canonHash` of the nil it collapses to is
-    // the SAME string for every such module -- so a lockfile written
-    // from one carries no information while looking exactly like one
-    // that does (use-cases/BUGS.md §31). `aontu hash` already refuses
-    // that file; `tidy` refuses it too, and this is what tells it.
     ok: boolean,
   }
 
@@ -134,10 +93,6 @@ function declaredDeps(file: string, options: ModToolOptions):
 }
 
 
-// Numeric-dotted version order: `1.10.0` is above `1.9.0`, which
-// STRING order gets wrong, and that is the whole reason this is not a
-// `<` on the text. A part that is not a number compares as text, after
-// every number — a pre-release tag is below no version and above none.
 export function versionCompare(a: string, b: string): number {
   const ap = a.split('.')
   const bp = b.split('.')
@@ -164,21 +119,6 @@ export function versionCompare(a: string, b: string): number {
 }
 
 
-// A dependency or lockfile key as a module ref this tooling may ACT
-// on, or undefined.
-//
-// Two ways to be unusable, one answer. A key that is not module-shaped
-// names nothing the resolver can find; a key that is shaped but whose
-// path cannot legally be a directory (`..` in it, a reserved device
-// name) must not be turned into one, which is the whole of the
-// traversal fix on this side. Both land in the caller's `missing`
-// bucket, because from the report's point of view they are the same
-// fact: the lockfile names something that cannot be resolved here.
-//
-// A STALE LOCKFILE IS THE REASON THIS EXISTS AT ALL. `resolveModule`
-// gates the evaluator, but `tidy`, `verify` and `vendor` read a
-// lockfile straight off disk -- one that may have been committed
-// before the gate existed -- so the gate has to be here too.
 function usableRef(mod: string): ModuleRef | undefined {
   const ref = parseModuleRef(mod)
   if (undefined === ref || undefined !== validateModulePath(ref.path)) {
@@ -230,21 +170,12 @@ function readLock(root: string): Record<string, ModLock> {
 }
 
 
-// The lockfile TEXT: canonical Aontu, one line, keys sorted. Built as
-// source and canonicalised by the engine rather than printed by hand,
-// so "canonical form" means what the language means by it and cannot
-// drift from it.
 export function lockText(entries: ModLock[], options: ModToolOptions): string {
   const parts = entries.map((e) =>
     JSON.stringify(e.mod) + ':{' +
     '"canon":' + JSON.stringify(e.canon) + ',' +
     '"oci":' + JSON.stringify(e.oci) + ',' +
     '"v":' + JSON.stringify(e.v) + '}')
-  // Canonicalised by the ENGINE rather than printed by hand, so
-  // "canonical form" means what the language means by it and cannot
-  // drift from it. For a map of scalars that canon is also JSON, which
-  // is what lets the resolver read a pin back without an evaluator
-  // (ts/src/mod.ts lockHash).
   return options.eval('{"lock":{' + parts.join(',') + '}}', 'mod-lock.aon').canon
 }
 
@@ -255,10 +186,6 @@ export function modTidy(root: string, options: ModToolOptions): ModTidyReport {
   const selected: Record<string, string> = {}
   const missing: string[] = []
 
-  // The closure, breadth-first from the project's own declarations. A
-  // module already selected at a version at least as high contributes
-  // nothing new, which is what makes this terminate without a cycle
-  // check: the selected version only ever rises.
   let frontier = declaredDeps(pathJoin(root, 'mod.aon'), options)
   for (; 0 < Object.keys(frontier).length;) {
     const next: Record<string, string> = {}
@@ -307,16 +234,8 @@ export function modTidy(root: string, options: ModToolOptions): ModTidyReport {
     const ref = usableRef(mod) as ModuleRef
     const dir = storeDir(root, ref, previous[mod]?.canon ?? '', options) as string
     const main = pathJoin(dir, mainOf(dir, options))
-    // RECOMPUTED, never carried over: the pin is what the module in
-    // this store MEANS, and a tidy that copied the old hash forward
-    // would pin what it used to mean.
     const got = existsSync(main) ?
       options.eval(readFileSync(main, 'utf8'), main) : undefined
-    // A NIL PIN IS WORSE THAN NO PIN. A module that does not stand up
-    // hashes to canonHash(nil) -- the same string for every broken
-    // module -- so writing it would put a plausible, uninformative
-    // pin in the lockfile and silently void the "breaks on any
-    // semantic change in the closure" contract (BUGS.md §31).
     if (null != got && !got.ok) {
       unevaluable.push(mod)
       continue
@@ -367,17 +286,6 @@ function mainOf(dir: string, options: ModToolOptions): string {
 }
 
 
-// `aontu mod verify`: does every locked module still MEAN what the
-// lockfile pins? Recompute and compare, and CHANGE NOTHING.
-//
-// The verb exists because `tidy` cannot answer this question. Tidy
-// recomputes and REWRITES by design -- a pin is what a module means
-// now -- so tampering with a vendored module and running tidy makes
-// the lockfile agree with the tampering, `verdict: ok`, and the next
-// evaluation passes. That is correct for the job tidy does and useless
-// as a gate, which left a CI job that tidies before evaluating with no
-// integrity protection at all (use-cases/BUGS.md §32). Verification is
-// a question; answering it must not be an edit.
 export function modVerify(root: string, options: ModToolOptions):
   ModVerifyReport {
   const locked = readLock(root)
@@ -385,17 +293,6 @@ export function modVerify(root: string, options: ModToolOptions):
   const mismatched: { mod: string, want: string, got: string }[] = []
   const missing: string[] = []
 
-  // NOTHING TO CHECK IS NOT A PASS. A project with no lockfile at all
-  // -- or one whose lockfile predates a dependency someone added --
-  // would otherwise verify clean, because the loop below walks what is
-  // LOCKED and there is nothing locked to walk. That is the same shape
-  // as the defect this verb exists to close: absence reading as
-  // agreement. Every dependency the project itself declares must be in
-  // the lockfile before the pins mean anything, and the repair is a
-  // tidy rather than a fetch. Transitive dependencies need no separate
-  // check: a locked module's own imports are resolved when its pin is
-  // recomputed, so one that is unreachable makes its DEPENDANT fail to
-  // evaluate and lands in `mismatched` below.
   const declared = declaredDeps(pathJoin(root, 'mod.aon'), options)
   const unlocked = Object.keys(declared)
     .filter((mod) => null == locked[mod]).sort()
@@ -417,10 +314,6 @@ export function modVerify(root: string, options: ModToolOptions):
       continue
     }
 
-    // A module that no longer stands up is not a match: it has no
-    // meaning to compare, and reporting `got: <hash of nil>` would
-    // print the same string for every broken module. The empty `got`
-    // says the store holds something that does not evaluate.
     const got = options.eval(readFileSync(main, 'utf8'), main)
     const want = locked[mod].canon
     if (got.ok && want === got.hash) {
@@ -464,17 +357,6 @@ export function modVendor(root: string, options: ModToolOptions):
       continue
     }
 
-    // WHY THERE IS NO CONTAINMENT CHECK ON `to`, at the one write site
-    // that copied a tree outside the project: `usableRef` above is the
-    // gate, and after it a store path CANNOT escape. Every element is
-    // non-empty and neither begins nor ends with `.`, so none is `.`
-    // or `..`; MODULE_RE's element class admits no `/`, no `\` and no
-    // leading slash, so no element can re-root the join. A second
-    // lexical check here would be unreachable code, which ADR-002 asks
-    // to be deleted rather than excluded -- so the invariant is pinned
-    // by a test that drives the escape through this verb instead.
-    // ANY NEW CALLER of moduleDir must go through usableRef too;
-    // `mod get` is the next one.
     const to = moduleDir(vendorRoot, ref)
     if (from !== to) {
       copyTree(from, to)
@@ -508,33 +390,10 @@ function copyTree(from: string, to: string): void {
 }
 
 
-// THE PUBLISH BOUNDARY (G6 phase 4,
-// docs/capability-review/g6-distribution.md). A module is an OCI
-// artifact, and what a publish PUSHES is a manifest: a config media
-// type, one layer holding the module's source tree, and annotations
-// carrying the module path, its version and its canon-hash.
-//
-// The push needs a registry, which this build does not have. Everything
-// the push would ASSERT is local, and that is what `aontu mod manifest`
-// answers: the exact artifact description, computed the way the
-// registry would be told it, plus the gate that decides whether it may
-// be minted at all.
-//
-// WHY THE ANNOTATION MATTERS MORE THAN THE BYTES. "Has the truth
-// changed?" is one annotation read and a string compare -- no download,
-// no parse -- because the canon-hash pins MEANING rather than text. A
-// consumer holding `aon1-oQs6…` can ask a registry index whether the
-// module still hashes to it, and a reformat, a comment or a file split
-// will not move it.
-
 // The config media type the design fixes: an Aontu module is not an
 // image, and the type is what tells a registry so.
 export const MODULE_CONFIG_MEDIA_TYPE = 'application/vnd.aontu.module.v1+json'
 
-// The canon-hash annotation. OCI asks a custom key to be the reverse
-// DNS of a domain its author controls, and the project's own home is
-// the only domain it has -- inventing an `aontu.dev` would be a claim
-// it cannot back. The two facts OCI already has keys for use those.
 export const MODULE_ANNOTATION_CANON = 'com.github.rjrodger.aontu.canon'
 export const MODULE_ANNOTATION_MAJOR = 'com.github.rjrodger.aontu.major'
 
@@ -549,9 +408,6 @@ export type ModManifestReport = {
   // The canon-hash of the module's entry file, evaluated standalone.
   canon: string
   config: string
-  // The layer's contents: every file of the source tree, relative,
-  // forward-slashed and sorted, so two implementations on two platforms
-  // describe the same layer.
   files: string[]
   annotations: Record<string, string>
   // What the module does not declare, sorted. A manifest cannot be
@@ -583,20 +439,12 @@ function modSelf(dir: string, options: ModToolOptions): ModSelf {
 }
 
 
-// The leading numeric component of a version, which is the major an
-// import spells. Empty when the version does not start with one: a
-// version whose major cannot be read cannot be published under a
-// module path, because the path is where the major lives.
 function majorOf(version: string): string {
   const m = /^(\d+)/.exec(version)
   return null == m ? '' : m[1]
 }
 
 
-// Every file of a module's source tree, relative and forward-slashed.
-// `aontu_meta/vendor/` is excluded: a published module carries its own
-// sources, not a copy of everyone else's -- a consumer resolves the
-// closure itself, and a nested vendor tree would publish the world.
 function layerFiles(dir: string, prefix = ''): string[] {
   const out: string[] = []
   for (const name of readdirSync(dir).sort()) {
@@ -688,16 +536,10 @@ export function modManifest(
     return report
   }
 
-  // A MAJOR BUMP IS WHERE BREAKING IS ALLOWED. The major lives in the
-  // module path, so a consumer of `@1` never sees `@2` unless it asks:
-  // checking compatibility across majors would forbid the one change
-  // the version scheme exists to express.
   if (majorOf(prior.version) !== major) {
     return report
   }
 
-  // Backward compatibility: the NEW version is the general side, so
-  // every instance the old one admitted must still be admitted.
   const gate = subsume(newSrc, readFileSync(priorMain, 'utf8'), {
     generalUrl: main,
     specificUrl: priorMain,