geneseed 3.14.0 → 3.16.0

package/js/lib/fs.mjs

@@ -4,9 +4,11 @@
  * These are definitions, not an adaptation of somebody else's. Every rule below was
  * originally MEASURED against CPython, because the generator these functions serve had to
  * emit bytes indistinguishable from a Python one; that second party is gone and the rules
- * are not. What holds them now is the recorded corpora under `tests/__snapshots__/`, which
- * compare this module's output byte for byte and can never be re-recorded — so a rule here
- * is a frozen fact about what this tool emits, and changing one is a product change.
+ * are not. The recorded corpora that compared this module's output byte for byte went with
+ * the former Python suite; what holds the rules now is `tests/unit/lib_primitives.test.mjs`
+ * (`isFile`/`isDir`), `tests/unit/hook_cli.test.mjs`'s platform-newline count (the stream
+ * funnels), and for the rest only the per-function provenance below. A rule here is still a
+ * frozen fact about what this tool emits, and changing one is a product change.
  *
  * ⚠ NONE OF THESE IS THE NODE DEFAULT, AND THAT IS THE ONE THING TO KNOW BEFORE EDITING ONE.
  * Each is a deliberate divergence from the obvious one-liner, and the obvious one-liner is
@@ -107,10 +109,10 @@ export function copyFile(src, dest) {
  * its caller different BYTES than the Python one: measured at 176 vs 171 for one `context`
  * run before this existed.
  *
- * `harness_golden.py` structurally cannot see the difference — `subprocess` decodes with
- * universal newlines on the way back, folding both shapes to `\n` before any cell compares
- * them, the same shape as the shim's exclusion from `golden.py`. So the gate for it is
- * `test_the_two_entry_points_agree_on_stdout_BYTES`, which captures raw bytes. Moved here
+ * The CLI matrix structurally cannot see the difference — every cell decodes stdout with
+ * universal newlines, folding both shapes to `\n` before anything compares them. So the gate
+ * for it is `tests/unit/hook_cli.test.mjs`'s `every newline the entry points write is the
+ * platform's`, which counts raw bytes. Moved here
  * from `js/hosts/hooks.mjs` in P5c, when `js/inspect/excludes.mjs` became the second caller: a translation
  * that exists twice is a translation that can be fixed once.
  */
@@ -167,10 +169,9 @@ export function withDiscardableStderr(fn) {
  * `emitGlobalInto`.
  *
  * The item it closes: a plain `--emit files` handed its caller 104 bytes where `python
- * build.py` handed over 105, and `tests/golden.py`'s `text=True` capture folds both to the
- * same string. `test_the_two_entry_points_agree_on_stdout_BYTES` grew a `build` row (through
- * `harness build`, which calls this `main` in-process) and a `rebuild-all` row, and those are
- * what can see it.
+ * build.py` handed over 105, and a `text=True` capture folds both to the same string.
+ * `tests/unit/hook_cli.test.mjs`'s newline test carries a `build` row (through `geneseed
+ * build`, which calls this `main` in-process), and that is what can see it.
  *
  * A Buffer chunk passes through untouched: `writeText` owns file bytes and nothing on this
  * path writes binary to a stream, so translating one would be corrupting data rather than

package/js/lib/json.mjs

@@ -5,8 +5,8 @@
  * These are definitions, not an adaptation of somebody else's; see `fs.mjs` for why the
  * measurements against CPython are recorded per function, and why NONE of these is the Node
  * default — the warning the retired `py` prefix used to carry now lives in each docblock.
- * A rule here is a frozen fact about what this tool emits — the corpora under
- * `tests/__snapshots__/` compare it byte for byte and can never be re-recorded.
+ * A rule here is a frozen fact about what this tool emits — the written-out tables in
+ * `tests/unit/lib_primitives.test.mjs` and `tests/unit/settings_jsonc.test.mjs` pin it.
  *
  * `JsonNumber` is why this module holds both the parser and the renderers: the wrapper is
  * created by `parseJson` and read by `formatValue`, `formatRepr`, `isTruthy` and `deepEquals`, so the
@@ -305,8 +305,8 @@ function escapeNonAscii(text) {
  * Indentation is what makes this tractable: passing `indent` switches Python's
  * separators from `(', ', ': ')` to `(',', ': ')`, which is exactly what
  * `JSON.stringify(v, null, 2)` emits. Verified rather than argued \u2014
- * `tests/test_opencode_extras_parity.py` compares both variants against Python over a
- * corpus of container shapes.
+ * the former Python suite compared both variants against Python over a corpus of container
+ * shapes; `tests/unit/lib_primitives.test.mjs` now pins only this writer's number spellings.
  */
 export function jsonDumpsIndent(value, { ensureAscii = true } = {}) {
   const text = JSON.stringify(value, null, 2);

package/js/lib/paths.mjs

@@ -22,7 +22,7 @@ const { X_OK } = constants;
  * BMP), and `str.lower()` is not `toLowerCase()` for a handful of characters.
  *
  * THE SEPARATOR CONVERSION IS NOT OPTIONAL, and it was missing until the byte-bearing
- * corpus in `tests/test_pure_function_parity.py` asked. `ntpath.normcase` is
+ * corpus in the former Python parity suite asked. `ntpath.normcase` is
  * `s.replace('/', '\\').lower()`, and `PurePath._str_normcase` gets the same conversion for
  * free because `Path` has already done it — so BOTH readings of the reference fold slashes
  * and this did not. Every sort call site feeds it `path.join` output or a bare `readdir`
@@ -50,7 +50,7 @@ export const normcase = process.platform === 'win32'
  * a directory depth, and `golden.py` compared CONTENT rather than order. It became visible
  * the first time a full path list was PRINTED \u2014 `geneseed validate -v` \u2014 against a real
  * skills tree that happens to contain both `skills/geneseed/` and `skills/geneseed-code-review/`.
- * `tests/test_maintainer_tools_parity.py` found it and died with the reference it compared
+ * The former Python maintainer-tools test found it and died with the reference it compared
  * against. What HOLDS it now is `tests/unit/maintainer_tools.test.mjs`, and specifically its
  * `theme files are visited in THIS platform's Path collation order` test: it re-derives Python's
  * `sorted(Path)` order for the running platform instead of replaying a recording, so it cannot
@@ -73,10 +73,14 @@ export function comparePaths(a, b) {
  * `_install_move_list` in `js/maintain/uninstall.mjs` \u2014 a CLI-level module that must not import the
  * web tree to reach it. Beside `normcase`, which is the thing it is actually about.
  * `js/web/api.mjs` re-exports it so its existing importers are unchanged.
+ *
+ * TRAILING SEPARATORS ARE STRIPPED FROM `parent` FIRST. A root is the one path whose canonical
+ * spelling ends in one — `D:\` and `/` — and splitting it leaves an empty last segment that no
+ * child's segment equals, so nothing was ever `within` a drive root or `/`.
  */
 export function within(child, parent) {
   const c = normcase(child).split(/[\\/]/);
-  const p = normcase(parent).split(/[\\/]/);
+  const p = normcase(parent).replace(/[\\/]+$/, '').split(/[\\/]/);
   return p.length <= c.length && p.every((seg, i) => c[i] === seg);
 }
 
@@ -86,7 +90,7 @@ export function within(child, parent) {
  * `Path` is `WindowsPath` on Windows and `PosixPath` everywhere else, and the two parsers
  * disagree about the two things below. A body that is right on one host is therefore wrong
  * on the other, which is exactly how this one passed a whole Windows suite and failed two
- * cases on the first Linux run of `tests/test_pure_function_parity.py`:
+ * cases on the first Linux run of the former Python pure-function parity suite:
  *
  *   * SEPARATORS. `ntpath` treats `\` and `/` alike; `posixpath` treats `\` as an ordinary
  *     filename character. `str(PurePosixPath('C:\\x\\bin\\'))` is that string VERBATIM —
@@ -100,8 +104,8 @@ export function within(child, parent) {
  * NOT reproduced, and named here rather than left as a gap nobody wrote down: `//` and
  * `///x` on WINDOWS, where `PureWindowsPath` answers `\\` and `\\\x` and this answers `\`
  * and `\x`. Those are incomplete UNC prefixes and matching them needs ntpath's share-name
- * parsing; both inputs are kept OUT of the corpus in `tests/test_pure_function_parity.py`
- * instead of sitting in it wrong.
+ * parsing; both inputs were kept OUT of the retired parity corpus instead of sitting in it
+ * wrong.
  *
  * The root's separators are still rewritten ONE AT A TIME, never `replace(/[\\/]+/g, sep)`:
  * a UNC root's leading pair is part of it, so collapsing runs turns `//server/share/x` into
@@ -143,7 +147,8 @@ export function toPlatformPath(s) {
  * `context` cell varies it, and changing it in this phase would be an ungated edit to a verb
  * that crossed three phases ago. Recorded in the spec's "Still owed" with this reproduction.
  *
- * Gated by a corpus in `tests/test_pure_function_parity.py`: no cell can vary the shape.
+ * It was gated by a corpus in the retired Python pure-function parity suite; nothing has
+ * replaced it, and no CLI test can vary the shape.
  */
 export function isAbsolutePath(s) {
   if (process.platform !== 'win32') return s.startsWith('/');
@@ -166,27 +171,21 @@ export function isAbsolutePath(s) {
  * PATH-removal refutation is aimed at, and the reason this is a real lookup rather than one
  * line of "we are node, we know where node is".
  *
- * The Windows half is the part with behaviour in it, and three of its four rules were
- * MEASURED against CPython 3.13 rather than assumed. `PATHEXT` supplies the suffixes, and the
+ * The Windows half is the part with behaviour in it, and its suffix rules were MEASURED
+ * against CPython 3.13 rather than assumed. `PATHEXT` supplies the suffixes, and the
  * returned path carries PATHEXT's OWN SPELLING of the extension rather than the file's
  * (`zzcmd.CMD` for a `zzcmd.cmd` on disk). An extension already in that set means the command
- * is spelled in full. An EMPTY PATH entry is not skipped either: `join('', cmd)` is a
- * relative path, and Python answers with one.
- *
- * THE FOURTH RULE IS THE CURRENT DIRECTORY, and it was measured on a machine that could not
- * see it. `shutil.which` prepends `os.curdir` to the search — even to a `path=` given
- * explicitly — when `_winapi.NeedCurrentDirectoryForExePath` says so, and that Win32 call
- * answers TRUE unless `NoDefaultCurrentDirectoryInExePath` is DEFINED in the environment.
- * Git Bash and this repo's developer machine both define it, so the reference answered None
- * there and the first draft's "the current directory is NOT prepended — it was until 3.12"
- * described an environment variable it had mistaken for a version change. GitHub's Windows
- * runner does not define it: the reference answered `.\\geneseed.CMD` for a `geneseed` looked
- * up beside the repo root, this returned null, and the parity corpus said so on the first CI
- * run. The variable is an INPUT, so it is read here rather than baked, and
- * `test_the_curdir_rule_agrees_in_both_environment_states` runs the corpus with it both ways.
- *
- * Gated as a pure function over a seeded directory in `tests/test_pure_function_parity.py`:
- * a cell can only ever observe the one answer this machine's PATH gives.
+ * is spelled in full.
+ *
+ * THE CURRENT DIRECTORY IS NEVER SEARCHED IMPLICITLY, and here this departs from
+ * `shutil.which` on purpose. The reference prepends `os.curdir` on Windows unless
+ * `NoDefaultCurrentDirectoryInExePath` is defined, and answers an EMPTY PATH entry (a
+ * trailing `;` is routine) with a cwd-relative path. Every caller SPAWNS what this returns —
+ * `git` from `upgrade`, `java` from `setup`, `node` from the doctor, `npm` from the web server
+ * — from whatever directory the user is in, so a `git.exe` committed to an untrusted clone ran
+ * the moment `geneseed upgrade` was typed inside it. Both routes are closed; a `.` the user
+ * wrote into PATH themselves is still honoured, because that is their choice and not ours.
+ * Gated in `tests/unit/lib_primitives.test.mjs`.
  */
 export function which(cmd, searchPath = null) {
   const win = process.platform === 'win32';
@@ -209,14 +208,9 @@ export function which(cmd, searchPath = null) {
   // then spawns. Measured: the corpus case with a posix-spelled directory was the one that
   // differed, and `path.join` had rewritten the whole path rather than appending to it.
   const joinRaw = (dir, name) => (
-    dir === '' || /[\\/]$/.test(dir) || (win && dir.endsWith(':'))
+    /[\\/]$/.test(dir) || (win && dir.endsWith(':'))
       ? dir + name : dir + path.sep + name);
-  const dirs = (searchPath ?? process.env.PATH ?? '').split(path.delimiter);
-  // `NeedCurrentDirectoryForExePath(cmd)`: TRUE — so `.` goes in FRONT — unless the variable
-  // is defined. Only reachable with a separator-free `cmd`, which is the only way execution
-  // gets this far. Inserted before the dedupe, exactly where `shutil.which` inserts it, so a
-  // PATH that already names `.` is searched once.
-  if (win && process.env.NoDefaultCurrentDirectoryInExePath === undefined) dirs.unshift('.');
+  const dirs = (searchPath ?? process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
   const seen = new Set();
   for (const dir of dirs) {
     const key = win ? dir.toLowerCase() : dir;

package/js/lib/proc.mjs

@@ -11,9 +11,9 @@
  * that module and six of its spawns used it, so the four spawn sites in `js/inspect/checks-authoring.mjs`,
  * `js/hosts/hooks.mjs`, `js/maintain/setup.mjs` and `js/hosts/link.mjs` each had to remember the flag on their
  * own. Two of them did not — and the miss is BYTE-INVISIBLE: a console window is not
- * something the CLI prints, so every recorded cell under `tests/__snapshots__/` stays green
- * while the windows pop. The property under test never reaches the comparison, which is why
- * a recorded corpus cannot be the gate here. A shared constant plus
+ * something the CLI prints, so every cell of `tests/golden.mjs --cli` stays green while the
+ * windows pop. The property under test never reaches the comparison, which is why a byte
+ * comparison cannot be the gate here. A shared constant plus
  * `tests/unit/spawn_hygiene.test.mjs` is what makes the next spawn site inherit the answer
  * instead of re-deciding it.
  *

package/js/lib/prompt.mjs

@@ -0,0 +1,132 @@
+/**
+ * The line-mode stdin readers — `ask`, `promptLine`, `confirm`, `askChoice` over one `readLine`.
+ *
+ * MOVED OUT OF `js/maintain/setup.mjs`, which is where the Python's own owner (`_harness_setup`)
+ * put them, because two callers that are not the wizard need them: `uninstall`'s `confirm` and
+ * the web server's npm prompt. Importing them from `setup.mjs` dragged the whole wizard closure
+ * — the driver, the doctor, the diff exporter — into `uninstall` and `web` for four functions
+ * whose only dependencies are fd 0, `printOut` and `parseIntStrict`.
+ */
+import { readSync } from 'node:fs';
+
+import { printOut } from './fs.mjs';
+import { parseIntStrict } from './text.mjs';
+
+/**
+ * `_harness_setup._ask` — `input(f"{prompt}{suffix}: ").strip()`, or the default at EOF.
+ *
+ * WHY IT READS A BYTE AT A TIME. Node has no synchronous line read: `readFileSync(0)` blocks
+ * until EOF rather than until Enter, so a wizard built on it would hang on a real terminal
+ * until the user pressed Ctrl-D. Reading fd 0 one byte at a time to the first `\n` is what
+ * `input()` does, and it is the only synchronous shape that stops where Enter stops. The
+ * body arrived in P5h inside `js/maintain/uninstall.mjs`'s `confirm`, moved to `setup` when that
+ * became the second caller, and lives here now that the callers outnumber the wizard;
+ * `confirm` is built on it exactly as `_confirm` is built on `_ask` in the Python.
+ *
+ * The EOF branch is the one a piped caller sees, and it agrees with Python by two different
+ * routes that happen to produce one answer: `input()` RAISES `EOFError` and the `except`
+ * returns the default, while a zero-length read here leaves `line` empty and `|| dflt` does
+ * the same. A partial line with no trailing newline is not EOF to either — Python returns
+ * the characters and so does this.
+ *
+ * `.trim()` is `str.strip()` in every case but U+FEFF, which JS counts as whitespace and
+ * Python does not; that is a standing item of this port and not this function's to settle.
+ */
+export function ask(prompt, dflt = '') {
+  const suffix = dflt ? ` [${dflt}]` : '';
+  // `input()` writes its prompt to stdout with no newline — nothing for `printOut` to
+  // translate, and it must NOT gain one.
+  process.stdout.write(`${prompt}${suffix}: `);
+  // `?? ''` because `readLine` reports EOF-with-nothing-read as null since P6h; `_ask`
+  // catches `EOFError` and returns the default, which is what the empty string produces
+  // here through `|| dflt`. The two routes to one answer are the docblock's own point.
+  const ans = (readLine() ?? '').trim();
+  return ans || dflt;
+}
+
+/**
+ * `input(prompt)` with EOF told apart from an empty line — `null` where Python RAISES.
+ *
+ * `ask` above cannot express that difference and does not need to: its EOF and its empty
+ * answer both mean "take the default". `_web_server.serve`'s npm prompt is the first
+ * caller where they differ, and they differ dangerously — `""` is in its accepted set, so
+ * a port that read EOF as an empty line would answer YES to "run npm install now?" on
+ * every non-interactive run. The reference catches `(EOFError, KeyboardInterrupt)` and
+ * answers "n"; this returns null so the caller can.
+ *
+ * No `.trim()`: `input()` does not strip, and both callers strip for themselves.
+ */
+export function promptLine(prompt) {
+  process.stdout.write(prompt);
+  return readLine();
+}
+
+/**
+ * Fd 0 to the first `\n`, dropping a `\r` before it — the CRLF a Windows console sends.
+ *
+ * THE BYTES ARE COLLECTED AND DECODED ONCE, and that is a fix rather than a style. The
+ * version this arrived as decoded EACH BYTE on its own — `buf.toString('utf8', 0, n)` inside
+ * the loop — which turns every multi-byte character into two or three U+FFFD. It was
+ * invisible for a phase because its only caller was `confirm`, whose answer is `y` or `n`;
+ * the wizard's first non-ASCII answer is what exposed it, and the corpus caught it on the
+ * first run. Scanning for the terminators a byte at a time is still correct: `\n` and `\r`
+ * are ASCII, and no continuation byte of a UTF-8 sequence is below 0x80.
+ */
+function readLine() {
+  const buf = Buffer.alloc(1);
+  const bytes = [];
+  let eof = false;
+  for (;;) {
+    let n = 0;
+    try { n = readSync(0, buf, 0, 1, null); } catch { eof = true; break; }
+    if (n === 0) { eof = true; break; }
+    if (buf[0] === 0x0a) break;
+    if (buf[0] !== 0x0d) bytes.push(buf[0]);
+  }
+  // NULL ONLY FOR THE EMPTY EOF, which is the one case `input()` raises on. A partial line
+  // with no trailing newline is not EOF to Python — it returns the characters — and the
+  // `bytes.length` test is what keeps that arm returning a string here too.
+  if (eof && bytes.length === 0) return null;
+  return Buffer.from(bytes).toString('utf8');
+}
+
+/** `_harness_setup._confirm` — `_ask` with a Y/n suffix; the default on an empty answer. */
+export function confirm(prompt, dflt = true) {
+  const ans = ask(`${prompt} (${dflt ? 'Y/n' : 'y/N'})`).toLowerCase();
+  return ans === '' ? dflt : ans[0] === 'y';
+}
+
+/**
+ * `_harness_setup._ask_choice` — a numbered menu; the chosen KEY, or the default.
+ *
+ * THREE THINGS ABOUT THE FALLBACK ORDER, all of them observable and none of them obvious:
+ *
+ *   * The key match lives in Python's `except ValueError`, so an answer that PARSES as an
+ *     integer never reaches it. `99` against a five-option menu returns the default; it does
+ *     not go looking for an option literally named `99`.
+ *   * An in-range index wins, a parsed out-of-range index falls to the default, and only an
+ *     UNPARSEABLE answer is matched against the keys. `parseIntStrict` is what separates the second
+ *     case from the third, and it is not `Number()` — see its own docblock.
+ *   * A default that is NOT in `options` falls back to option 1. It is reachable — a deployed
+ *     `.geneseed-theme` can name a theme this checkout no longer ships — and it used to throw,
+ *     mirroring the Python reference's `StopIteration`, which crashed `geneseed setup` before
+ *     its first question. The reference is gone, so there is nothing left to fail in step
+ *     with, and returning a key that is not on the menu would hand the build a stale value.
+ */
+export function askChoice(prompt, options, dflt) {
+  if (!options.some(([k]) => k === dflt)) dflt = options[0][0];
+  printOut(`\n${prompt}:\n`);
+  options.forEach(([key, desc], i) => {
+    const label = desc ? `${key} — ${desc}` : key;
+    printOut(`  ${i + 1}) ${label}${key === dflt ? '   (default)' : ''}\n`);
+  });
+  const defaultIdx = options.findIndex(([k]) => k === dflt);
+  const raw = ask('Choose', String(defaultIdx + 1));
+  const idx = parseIntStrict(raw);
+  if (idx !== null) {
+    if (idx >= 1 && idx <= options.length) return options[idx - 1][0];
+  } else {
+    for (const [key] of options) if (raw === key) return key;
+  }
+  return dflt;
+}

package/js/lib/text.mjs

@@ -9,6 +9,8 @@
  * set than `String.trim`'s, `parseIntStrict` accepts what `Number()` does not and rejects what
  * it does, and `percentDecode` leaves a bad escape alone where `decodeURIComponent` throws.
  */
+import path from 'node:path';
+
 /**
  * `len(s)` — CODE POINTS, where `String.length` counts UTF-16 units.
  *
@@ -50,8 +52,10 @@ export const padEndToWidth = (s, width) => s + ' '.repeat(Math.max(0, width - co
  * raw environment value do it — `js/ui/cli.mjs`'s `helpWidth` and `js/web/activity.mjs` wrap
  * the argument in `stripWhitespace` first.
  *
- * Gated by a corpus in `tests/test_pure_function_parity.py` — a primitive reproduction gets
- * one owner and a corpus, never a cell (P5c).
+ * Its own corpus retired with the Python suite — a primitive reproduction gets one owner and
+ * a corpus, never a cell (P5c) — so what reaches it now is only its callers' gates:
+ * `tests/unit/wizard.test.mjs`'s choice corpus and `tests/unit/web_daemon.test.mjs`'s
+ * non-integer port.
  */
 export function parseIntStrict(s) {
   if (typeof s !== 'string' || s === '') return null;
@@ -146,8 +150,8 @@ export function stripWhitespaceEnd(s) {
  * `Buffer.toString('utf-8')` substitutes U+FFFD for an undecodable sequence, which is
  * `errors='replace'`. The two decoders can disagree on HOW MANY replacement characters a
  * truncated multi-byte sequence yields — Python's maximal-subpart rule against WHATWG's —
- * and the corpus in `tests/test_pure_function_parity.py` is where that is measured rather
- * than assumed.
+ * and the former Python corpus is where that was measured rather than assumed; nothing
+ * measures it now.
  */
 const HEX_PAIR = /^[0-9A-Fa-f]{2}$/;
 
@@ -179,3 +183,13 @@ export function percentDecode(s) {
   return res;
 }
 
+/**
+ * `Path.relative_to(base).as_posix()` — `target` relative to `base`, always `/`-separated.
+ *
+ * Here, not in `js/build/emit-common.mjs`, because the hook path (`js/hosts/hooks-context.mjs`)
+ * needs it too and must not pay for the render module to get it; this module imports nothing
+ * but `node:path`. It had been defined four times.
+ */
+export function relPosix(base, target) {
+  return path.relative(base, target).split(path.sep).join('/');
+}

package/js/lib/udiff.mjs

@@ -4,8 +4,9 @@
  * WHY A HAND-WRITTEN MATCHER RATHER THAN A LIBRARY. The diff is the ENTIRE user-visible
  * payload of `geneseed diff`: the hunks in `--full` and in the exported improvements file
  * are this file's output and nothing else's. A generic JS diff would produce a CORRECT diff
- * and a DIFFERENT one, and `tests/__snapshots__/primitives/` compares the hunks character
- * for character, so "also a valid diff" fails every cell. The alignment below IS the
+ * and a DIFFERENT one, and the former Python suite's corpus compared the hunks character for
+ * character, so "also a valid diff" failed every case (today only the `diff/--full-…` CLI cell
+ * compares hunks, and only one; see `js/inspect/diff.mjs`). The alignment below IS the
  * specification of what this tool prints, and three of its choices are choices no other
  * algorithm makes:
  *

package/js/maintain/memory.mjs

@@ -17,12 +17,11 @@
  *     beside the cwd, then the global config dir — with `--memory` as the explicit override.
  *     `status` prints the answer of that same resolver, so the two agree about which store
  *     is "the" store.
- *   * THE RESERVED-NAME CHECK IS CASE-INSENSITIVE, WHICH THE ENDPOINT'S IS NOT. It compares
- *     `MEMORY` and `README` exactly. On a case-insensitive filesystem — which is every
- *     Windows install and the default macOS one — `rm memory` then resolves to the index
- *     file, passes the guard, and deletes the thing the agent reads at session start. This
- *     is a NARROWING of what the endpoint accepts, on a destructive path, and it is the one
- *     divergence in this file that is not about resolution.
+ *   * THE RESERVED-NAME CHECK IS CASE-INSENSITIVE, and the web endpoints use this one. On a
+ *     case-insensitive filesystem — every Windows install and the default macOS one — an
+ *     exact `MEMORY`/`README` compare let `rm memory` resolve to the index file, pass the
+ *     guard, and delete the thing the agent reads at session start. The endpoint once had
+ *     that exact compare; it now calls `memoryDelete` from here.
  *
  * `memoryDropIndex` is the hook module's, not a copy: writing the fact and unwriting its
  * index line are two halves of one format, and the half that writes lives there.

package/js/maintain/migrate.mjs

@@ -3,9 +3,10 @@
  *
  * P10d, AND IT IS NOT A PORT. Every other module here reproduces a Python original byte for
  * byte; this verb is new behaviour on both sides, written twice in the same change so that
- * `tests/harness_golden.py` — a CROSS-IMPLEMENTATION gate — has a reference side at all. A
- * Node-only verb would have nothing to compare against, and `test_every_entry_verb_is_a_real_
- * harness_subcommand` plus `test_the_matrix_covers_every_verb_it_claims` would both fail it.
+ * the former Python CLI matrix — a CROSS-IMPLEMENTATION gate — had a reference side at all. A
+ * Node-only verb would have had nothing to compare against, and that suite's `test_every_entry_
+ * verb_is_a_real_harness_subcommand` plus `test_the_matrix_covers_every_verb_it_claims` would
+ * both have failed it.
  *
  * WHAT IT IS NOT: `rebuild-all`. That was the first answer and it was checked before being
  * discarded, because the re-emit really is the same engine and is reused rather than rewritten