@polycode-projects/the-mechanical-code-talker 1.9.1 → 1.10.0

package/src/grammar/lexicon.mjs

@@ -1,5 +1,5 @@
 // grammar/lexicon.mjs — the declared lexicon behind tmct's ACE-OWL
-// sub-fragment parser (ROADMAP Phase 2, item 2; see ace.mjs). The lexicon is
+// sub-fragment parser (see ace.mjs). The lexicon is
 // LOAD-BEARING: the grammar is only deterministic because every noun, verb
 // (with any preposition), adjective (with its declared type) and proper name
 // is DECLARED — the parser never guesses a word's category. Undeclared words
@@ -13,9 +13,6 @@
 //
 // Namespace: every lexicon carries a `.ns` field (the CURIE prefix ace.mjs
 // stamps onto every term it mints) — always "tmct:" here (DEFAULT_NS).
-// ace.mjs and predicateOf() read it off the lexicon rather than hardcoding
-// the prefix inline, purely so a caller can supply its own already-namespaced
-// lexicon; tmct itself only ever runs the one namespace.
 //
 // Morphology is deliberately tiny and deterministic (no NLP dependency): a
 // suffix-fold for plurals/3rd-person-singular ("repositories"→repository,
@@ -154,26 +151,17 @@ export function loadLexicon(extra, ns = DEFAULT_NS) {
   return lex;
 }
 
-/** Noun lookup with plural folding; returns the entry ({lemma, property?}) or null.
- *  `opts.singularOnly` (set by ace.mjs's resolveNP for an "a"/"an" determiner —
- *  the only ACE determiners that are grammatically singular-ONLY) prunes the
- *  irregular-plural fold when the SAME surface word is ALSO declared as its own
- *  standalone noun (die/dice, person/people, tooth/teeth): a singular-only
- *  determiner is incompatible with the plural-fold reading but fully compatible
- *  with the standalone-singular reading, so that's the one grammar agreement
- *  allows. A general rule keyed on determiner agreement, not a per-word carve-out
- *  — see lookupNounCandidates below for the multi-candidate form this wraps. */
+/** Noun lookup with plural folding; returns the entry ({lemma, property?}) or
+ *  null. `opts.singularOnly` (an "a"/"an" determiner) prunes the irregular-
+ *  plural fold in favor of a standalone-singular entry when both exist for
+ *  the same surface word (die/dice, person/people). */
 export function lookupNoun(lexicon, word, opts = {}) {
   return lookupNounCandidates(lexicon, word, opts)[0] ?? null;
 }
 
-/** Every lexicon entry `word` could plausibly resolve to, ranked with the SAME
- *  top choice lookupNoun would return (opts.singularOnly applies identically)
- *  but without discarding a genuine alternate — e.g. the die/dice collision
- *  returns BOTH the `dice` and `die` entries (order depends on
- *  opts.singularOnly), a regular -s fold with both forms independently
- *  declared returns both. Additive: existing callers that only want the single
- *  best answer keep using lookupNoun untouched. */
+/** Every lexicon entry `word` could plausibly resolve to, ranked the same as
+ *  lookupNoun's top choice but without discarding a genuine alternate (e.g.
+ *  die/dice returns both entries). */
 export function lookupNounCandidates(lexicon, word, opts = {}) {
   const w = String(word ?? "").toLowerCase();
   const standalone = lexicon.nouns.get(w);
@@ -208,13 +196,7 @@ export function lookupVerb(lexicon, word) {
 }
 
 /** Every verb entry `word` could plausibly resolve to via foldCandidates,
- *  most-specific-fold-first (same order lookupVerb's single answer already
- *  used) — additive sibling of lookupNounCandidates, for a caller that wants
- *  to know about a genuine fold collision instead of only the first hit. In
- *  practice a verb fold rarely collides (unlike nouns' irregular-plural
- *  table), but the shape is symmetric with lookupNounCandidates on purpose —
- *  ace.mjs's multi-candidate relation search (parseRelationHits) reads
- *  whichever of the two a token's part of speech calls for. */
+ *  most-specific-fold-first — the verb sibling of lookupNounCandidates. */
 export function lookupVerbCandidates(lexicon, word) {
   const w = String(word ?? "").toLowerCase();
   const out = [];

package/src/graph-merge.mjs

@@ -1,5 +1,4 @@
-// graph-merge.mjs — multi-graph payload merging (the CLI/config unification
-// batch's multi-graph support). Used ONLY by source.mjs's fetchEntities when a
+// graph-merge.mjs — multi-graph payload merging. Used ONLY by source.mjs's fetchEntities when a
 // config carries more than one graph file (`config.graphFiles.length > 1`);
 // the single-graph path never calls this — that byte-identical guarantee
 // lives in source.mjs, not here.
@@ -8,7 +7,7 @@
 // ids as `mod:${relativePath}` (repo-relative), so two graphs describing
 // similarly-structured repos can collide. mergeEntityPayloads concatenates the
 // straightforward arrays (classes/vocabulary/objectProperties/individuals),
-// unions proseIndex (merging the id-array per word key), and — Option A, only
+// unions proseIndex (merging the id-array per word key), and — only
 // on an ACTUAL collision — prefixes the specific colliding ids (and every
 // in-payload reference to them: derived_from entries, mentions, edge subject/
 // object, proseIndex entries) with `<graphName>/`. Ids that never collide pass

package/src/hash.mjs

@@ -1,19 +1,11 @@
 // hash.mjs — the single home for tmct's content-address hash.
 //
-// FNV-1a 32-bit is deliberately home-grown (see archive/PLAN_DEPENDENCY_STRATEGY.md): it
-// must be synchronous, browser-safe, dependency-free, and — critically —
-// CROSS-VERSION STABLE, because fact ids are content-addressed by it and a fact's
-// id is its identity across the whole memory graph. Every library candidate fails
-// at least one of those; this eight-line function fails none. It lives here, once,
-// so the fact-id contract has exactly one definition.
-//
-// Two historical copies are reconciled here without changing a single output byte:
-//   - src/memory/core.mjs used the hex form for fact ids;
-//   - chatbench/graded.mjs used the integer form as a PRNG seed, with a redundant
-//     mid-loop `>>> 0`. That `>>> 0` was always a no-op: `^` and Math.imul both
-//     apply ToInt32 to their operands, so the 32-bit pattern is invariant between
-//     iterations whether the accumulator is stored signed or unsigned. The final
-//     `h >>> 0` therefore yields the same value either way — proven, not assumed.
+// FNV-1a 32-bit is deliberately home-grown: it must be synchronous, browser-safe,
+// dependency-free, and — critically — CROSS-VERSION STABLE, because fact ids are
+// content-addressed by it and a fact's id is its identity across the whole memory
+// graph. Every library candidate fails at least one of those; this eight-line
+// function fails none. It lives here, once, so the fact-id contract has exactly
+// one definition.
 
 /** FNV-1a 32-bit. Returns the unsigned 32-bit integer (0 … 2^32−1). */
 export function fnv1a32(str) {

package/src/index.mjs

@@ -1,14 +1,10 @@
 // @polycode-projects/the-mechanical-code-talker (tmct) — library entry point.
 //
-// tmct began as a whole-package lift of an earlier chat surface (see README
-// provenance). Internal module filenames and symbols were kept to preserve the
-// shape and its green test suite; the branding throughout is now `tmct`.
-//
 // This entry re-exports the adapter primitives a library consumer needs. The
-// clean chat/primitives split (ROADMAP item 13) is done: the movable
-// conversational grammar lives in src/interpret/ (normalization pre-pass, the
-// registered parsing strategies, the merge rule), while ask.mjs keeps the core
-// primitives (resolveObject, traverse, render) and the ask() orchestration.
+// movable conversational grammar lives in src/interpret/ (normalization
+// pre-pass, the registered parsing strategies, the merge rule), while
+// ask.mjs keeps the core primitives (resolveObject, traverse, render) and
+// the ask() orchestration.
 
 // Chat surface (also reachable as the `./chat` subpath export).
 export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
@@ -16,7 +12,7 @@ export { runChat, COMMANDS, answerCount, renderStats } from "./chat.mjs";
 // Grammar / NL-over-graph primitives.
 export { ask, resolveObject } from "./ask.mjs";
 
-// The interpretation pipeline (ROADMAP item 8): normalize once, run every
+// The interpretation pipeline: normalize once, run every
 // registered strategy (grammar, keyword-spot, …) over the text, merge same-class
 // results, surround distinct-class results — no graph access; pair it with ask()
 // or the primitives to answer. `interpret(text, ctx)` returns the full record
@@ -29,7 +25,7 @@ export { relationKind, impactClosure } from "./codegraph.mjs";
 // Tool dispatch (slash-commands and CLI tool calls route through here).
 export { dispatchTool } from "./server.mjs";
 
-// Conversational memory (ROADMAP item 9) — tmct's OWN OWL-labelled graph under
+// Conversational memory — tmct's OWN OWL-labelled graph under
 // .tmct/memory/, distinct from any provider-supplied code graph.
 export { loadMemory, appendUtterance, appendFact } from "./memory/core.mjs";
 export { retrieveBlocks, saveBlock, rankBlocks } from "./memory/blocks.mjs";

package/src/init.mjs

@@ -1,29 +1,17 @@
 // init.mjs — `tmct init`: the interface's onboarding surface.
 //
-// One command takes a bare directory (a user's repo, or a host package such as
-// seonix) to a WORKING tmct install: it creates the `.tmct/` artifact tree,
-// writes an externalised `tmct.toml` (the seonix.toml documented-config pattern),
-// seeds the committed tier-1 corpus into memory, and records provenance of what
-// it did. See ROADMAP Phase 8 ("Distribution: tmct init") and the Phase-4
-// corpus-tiering policy.
+// One command takes a bare directory to a WORKING tmct install: creates the `.tmct/`
+// artifact tree, writes an externalised `tmct.toml`, seeds the committed tier-1 corpus
+// into memory, and records provenance. Offline/deterministic/$0 (tiers 2-3 are additive
+// config, never run here); idempotent and non-destructive (a benign re-init never
+// throws); failure-tolerant seed (a missing/broken corpus degrades to unseeded, not a
+// crash).
 //
 //   initRepo(dir, { force?, seed?, env? }) → { created, config, seeded, ... }
 //
-// DESIGN RULES (load-bearing):
-//   - OFFLINE, DETERMINISTIC, $0. The seed is the tier-1 committed ConceptNet
-//     slice already in the tarball — no network, ever. The $0-offline default is
-//     inviolable (ROADMAP Phase 4); tiers 2-3 are additive config, never run here.
-//   - IDEMPOTENT and NON-DESTRUCTIVE. Safe to re-run. A benign re-init NEVER
-//     throws — it returns an honest result whose `message` says nothing changed.
-//     Existing `tmct.toml` and an existing seed are preserved unless `force`.
-//   - FAILURE-TOLERANT SEED. A missing/broken corpus degrades to an unseeded (but
-//     still initialised) repo — the directory scaffold and config always land.
-//
-// The seed marker + limit + prefer mirror src/chat.mjs's W3 bootstrap
-// (SEED_MARKER_REL / SEED_LIMIT / SEED_PREFER) ON PURPOSE: both write the same
-// `.tmct/memory/corpus-seed.json`, so whichever of `tmct init` and first-run
-// bootstrap happens first wins and the other short-circuits. They are re-declared
-// here (not imported) to keep init off chat.mjs's heavy module graph.
+// The seed marker/limit/prefer mirror chat.mjs's W3 bootstrap constants on purpose: both
+// write the same `.tmct/memory/corpus-seed.json`, so whichever runs first wins. Re-declared
+// here rather than imported, to keep init off chat.mjs's heavy module graph.
 
 import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -56,31 +44,11 @@ export function defaultConfig() {
   };
 }
 
-/** `tmct init --with-persona <name>` presets (Part 7 of the extension-pack
- *  batch; PLAN_SEED.md §2 flips which preset is the SHIPPED implicit
- *  default): a named bundle of `extensions`/`bias` overrides, written into
- *  tmct.toml alongside the plain defaults.
- *
- *  - `human` — the NEW implicit default (src/extensions.mjs's
- *    BUILTIN_EXTENSIONS already ships `human` active and `seon`/`conceptnet`
- *    inactive) made EXPLICIT: an empty `extensions` override (nothing to
- *    add — the builtin defaults already are this persona) plus an explicit
- *    `[bias] human = 1.0`, so a repo that asks for `--with-persona human`
- *    has a self-documenting tmct.toml rather than relying on an unstated
- *    implicit default — the exact same discipline `code` below already used
- *    for the OLD default.
- *  - `code` — TODAY'S OLD IMPLICIT DEFAULT, now something a repo must
- *    request explicitly: re-activates `seon`+`conceptnet` (both now
- *    shipped inactive) and sets their bias, for a caller (e.g. seonix's own
- *    code-domain chat surface) that still wants the software-domain seed.
- *  - `empty` — the advanced escape hatch (PLAN_SEED.md §7): deactivates the
- *    one bundle now active by default (`human`), leaving a repo genuinely
- *    empty of corpus facts for a consumer bringing its own ontology/lexicon/
- *    corpus. Does NOT reduce npm package size (§7's own documented caveat —
- *    `corpus/` ships unconditionally either way).
- *
- *  Kept minimal on purpose — this batch's job is the persona SEAM, not a
- *  curated library of presets. */
+/** `tmct init --with-persona <name>` presets: a named bundle of `extensions`/`bias`
+ *  overrides written into tmct.toml. `human` makes the implicit default explicit; `code`
+ *  re-activates the software-domain `seon`+`conceptnet` bundles; `empty` deactivates
+ *  `human`, leaving a repo genuinely empty of corpus facts. Kept minimal on purpose —
+ *  the persona seam, not a curated library of presets. */
 export const PERSONA_PRESETS = Object.freeze({
   human: { extensions: {}, bias: { human: 1.0 } },
   code: { extensions: { seon: { active: true }, conceptnet: { active: true } }, bias: { seon: 1.0, conceptnet: 1.0 } },
@@ -148,18 +116,12 @@ enabled = ${seed.enabled ? "true" : "false"}
 # To cap it, uncomment and set a number (definitional band first):
 ${seed.limit != null ? `limit = ${Number(seed.limit)}` : "# limit = 500"}
 `;
-  // [memory] backend — ONLY emitted when a caller actually supplies it (an
-  // explicit `tmct init --memory-backend <...>`, or a manual override); the
-  // plain zero-flag `tmct init` output stays BYTE-IDENTICAL to before this
-  // knob existed, same discipline as the extras block below. "default" is
-  // written out explicitly rather than omitted, so `--memory-backend default`
-  // leaves a self-documenting trace of the choice (mirrors --with-persona's
-  // own "make the default explicit" behaviour).
+  // [memory] backend — only emitted when a caller actually supplies it.
   let out = base;
   if (config.memory && config.memory.backend !== undefined) {
     out += `
 [memory]
-# Storage backend for taught facts + the memory graph (PLAN_SEED.md §6).
+# Storage backend for taught facts + the memory graph.
 # Precedence: --memory-backend flag > TMCT_MEMORY_BACKEND env > this file >
 # "default" (the built-in fallback).
 #   "default" — the flat OWL-labelled JSON file under .tmct/memory/. The default.
@@ -169,12 +131,7 @@ backend = ${JSON.stringify(config.memory.backend)}
 `;
   }
 
-  // Extension-pack / bias sections (src/extensions.mjs) — ONLY emitted when a
-  // caller actually supplies them (an explicit `--with-persona`, or a manual
-  // override); the plain zero-flag `tmct init` output stays BYTE-IDENTICAL to
-  // before this feature existed. Rendered via smol-toml's own stringify (not
-  // hand-written prose like the base file above) — a plain, uncommented
-  // config fragment is honest about being machine-written/round-tripped.
+  // Extension-pack / bias sections — only emitted when a caller supplies them.
   const extras = {};
   if (config.extensions !== undefined) extras.extensions = config.extensions;
   if (config.bias !== undefined) extras.bias = config.bias;
@@ -204,32 +161,20 @@ function seedRequested({ optSeed, configEnabled, env }) {
  *
  * @param {string} dir  target directory (a repo root, or a host package root).
  * @param {object} [opts]
- * @param {boolean} [opts.force]  re-write tmct.toml + re-record provenance even
- *   when the repo is already initialised (never deletes memory/seed data).
- * @param {boolean} [opts.seed]   force seeding on/off, overriding tmct.toml's
- *   `seed.enabled` (TMCT_NO_SEED still vetoes).
- * @param {object}  [opts.env]    environment (for TMCT_NO_SEED); defaults to
- *   process.env.
- * @param {object}  [opts.persona] a resolved PERSONA_PRESETS entry
- *   ({extensions?, bias?}) to merge into the FRESH config before it's written
- *   (Part 7, `tmct init --with-persona <name>`). Name -> preset resolution
- *   and unknown-name validation are the CALLER'S job (bin/tmct.mjs) — this
- *   only ever sees an already-resolved preset object (or nothing). Has no
- *   effect when tmct.toml already exists and `force` isn't set (the existing
- *   "preserve a user's tmct.toml" rule wins, same as `seed`/`corpus.tier`).
- * @param {string}  [opts.memoryBackend]  "default" | "memory" | "sqlite" — merged
- *   into the FRESH config's `[memory] backend` before it's written (same
- *   "fresh write only" rule as `persona`, above; `tmct init --memory-backend
- *   <...>` on an ALREADY-initialized repo is bin/tmct.mjs's own job, mirroring
- *   how `--graph` amends an existing tmct.toml post-hoc). Also selects which
- *   backend the corpus SEED below (step 3) writes into — src/memory/core.mjs's
- *   `openMemoryBackend`, the same resolver chat.mjs's createSession uses, so a
- *   seeded fact and a later chat-taught fact always land in the same store.
+ * @param {boolean} [opts.force]  re-write tmct.toml + re-record provenance even when
+ *   already initialised (never deletes memory/seed data).
+ * @param {boolean} [opts.seed]   force seeding on/off (TMCT_NO_SEED still vetoes).
+ * @param {object}  [opts.env]    environment (for TMCT_NO_SEED); defaults to process.env.
+ * @param {object}  [opts.persona] a resolved PERSONA_PRESETS entry ({extensions?, bias?})
+ *   merged into a FRESH config only; name resolution is the caller's job (bin/tmct.mjs).
+ * @param {string}  [opts.memoryBackend]  "default" | "memory" | "sqlite" — merged into a
+ *   FRESH config's `[memory] backend`, and selects which backend the corpus seed writes
+ *   into (via src/memory/core.mjs's openMemoryBackend).
  * @returns {Promise<{
  *   created: string[], config: object, seeded: boolean,
  *   alreadyInitialized: boolean, seedResult: (object|null), message: string
- * }>} `created` lists the ABSOLUTE paths this call brought into being (empty on a
- *   benign no-op re-init). Never throws on a benign re-init or a corpus failure.
+ * }>} `created` lists the absolute paths this call brought into being. Never throws on
+ *   a benign re-init or a corpus failure.
  */
 export async function initRepo(dir, { force = false, seed, env = process.env, persona = null, memoryBackend = null } = {}) {
   const root = resolve(dir);
@@ -255,11 +200,7 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
 
   // ---- 2. The externalised config (preserve an existing file unless force) ----
   let config = defaultConfig();
-  // Persona overrides (Part 7) apply ONLY to a FRESH write — an empty preset
-  // field (e.g. `code`'s `extensions: {}`) is a genuine no-op, never an
-  // explicit-empty-section write (renderTomlConfig only emits [extensions]/
-  // [bias] when the merged config actually carries a non-empty one — the
-  // plain zero-flag `tmct init` output stays byte-identical either way).
+  // Persona overrides apply only to a fresh write.
   if (persona) {
     if (persona.extensions && Object.keys(persona.extensions).length) config.extensions = persona.extensions;
     if (persona.bias && Object.keys(persona.bias).length) config.bias = persona.bias;
@@ -270,21 +211,11 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
     await writeFile(paths.toml, renderTomlConfig(config));
     if (!tomlPresent) created.push(paths.toml);
   } else {
-    // Honour the user's committed tmct.toml — read its knobs back so the returned
-    // config (and the seed decision) reflect what's actually on disk.
+    // Honour the user's committed tmct.toml — read its knobs back into the returned config.
     config = await readWrittenConfig(paths.toml, config);
   }
 
   // ---- 3. Seed the committed corpus (offline, failure-tolerant) ----
-  // DELIBERATE BUG FIX (this batch): `tmct init`'s zero-flag seed step used to
-  // seed ONLY the ConceptNet band, never the curated SEON ontology — unlike
-  // chat.mjs's own first-run bootstrap (seedBootstrapMemory), which has always
-  // seeded BOTH. Both now go through the SAME unified loop
-  // (src/extensions.mjs's resolveExtensions + seedActiveCorpusEntries), so
-  // `tmct init`'s seed matches chat's bootstrap exactly — this changes
-  // `initRepo`'s seeded fact COUNT (test/init.test.mjs's seed-count assertions
-  // were updated for the larger post-fix totals, deliberately, in the same
-  // commit as this fix).
   let seeded = false;
   let seedResult = null;
   let seedNote = "";
@@ -296,17 +227,8 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
   } else if ((await exists(paths.marker)) && !force) {
     seedNote = "seed skipped (already seeded — marker present)";
   } else {
-    // BUG FIX (found in review): this step used to call seedActiveCorpusEntries
-    // with the plain `root` string ALWAYS — Backend A only — regardless of
-    // `config.memory.backend`. A `tmct init --memory-backend sqlite` repo ended
-    // up with its corpus facts trapped in an inert .tmct/memory/graph.json that
-    // a sqlite-backend chat session (createSession, which IS backend-aware)
-    // createSession resolves it — src/memory/core.mjs's openMemoryBackend — so
-    // the seed lands in whichever backend `config.memory.backend` actually
-    // names. "memory" is skipped outright: it's an in-process-only store that
-    // vanishes the moment this one-shot init process exits, so seeding it is
-    // pure wasted work — a later `tmct chat --memory-backend memory` opens a
-    // brand new, unrelated in-memory store anyway.
+    // Seeds into whichever backend config.memory.backend names. "memory" is skipped
+    // outright: it's an in-process-only store that vanishes when this process exits.
     const backendChoice = String(config.memory?.backend || "").trim().toLowerCase();
     if (backendChoice === "memory") {
       seedNote = "seed skipped (memory backend is in-process only — nothing would persist past this command)";
@@ -316,22 +238,14 @@ export async function initRepo(dir, { force = false, seed, env = process.env, pe
       try {
         const { resolveExtensions, seedActiveCorpusEntries } = await import("./extensions.mjs");
         const { entries } = await resolveExtensions(root);
-        // `tmct.toml`'s `[seed] limit` knob is documented as capping the tier-1
-        // ConceptNet band specifically (the curated SEON ontology is small and
-        // always seeds whole) — so it overrides ONLY the resolved "conceptnet"
-        // entry's limit, exactly like the pre-fix single-corpus seed did.
+        // `[seed] limit` caps the tier-1 ConceptNet band specifically (SEON is small
+        // and always seeds whole).
         if (config.seed?.limit != null && entries.has("conceptnet")) {
           entries.set("conceptnet", { ...entries.get("conceptnet"), limit: Number(config.seed.limit) });
         }
         const { appended, skipped, total, perBundle } = await seedActiveCorpusEntries(memoryDir, entries);
-        // seedActiveCorpusEntries is failure-tolerant PER BUNDLE (a bad third-party
-        // pack never aborts the others) — but initRepo's own "FAILURE-TOLERANT
-        // SEED" contract is about the SEED AS A WHOLE degrading honestly. If every
-        // active bundle failed (e.g. the memory graph file itself is unwritable —
-        // see test/init.test.mjs "seed failure degrades"), re-throw the first
-        // bundle's error so the SAME outer catch below reports the familiar "seed
-        // skipped (corpus unavailable: …)" note, rather than claiming success with
-        // zero facts actually written.
+        // If every active bundle failed, re-throw the first error so the outer catch
+        // reports it, rather than claiming success with zero facts written.
         const bundleNames = Object.keys(perBundle);
         const allFailed = bundleNames.length > 0 && bundleNames.every((n) => perBundle[n].error);
         if (allFailed) throw new Error(perBundle[bundleNames[0]].error);
@@ -401,9 +315,8 @@ async function readWrittenConfig(tomlPath, base) {
       if (raw.seed.enabled !== undefined) cfg.seed.enabled = Boolean(raw.seed.enabled);
       if (raw.seed.limit !== undefined) cfg.seed.limit = Number(raw.seed.limit);
     }
-    // Sparse pass-through (src/extensions.mjs validates; this layer just carries
-    // the raw tables through unmodified, same discipline as toml-config.mjs's
-    // normalizeConfig).
+    // Sparse pass-through — src/extensions.mjs validates; this layer just carries the
+    // raw tables through unmodified.
     if (raw.extensions !== undefined) cfg.extensions = raw.extensions;
     if (raw.bias !== undefined) cfg.bias = raw.bias;
     if (raw.memory && raw.memory.backend !== undefined) {

package/src/interpret/fuzzy.mjs

@@ -1,22 +1,12 @@
-// interpret/fuzzy.mjs — the bounded-edit-distance fuzzy tier (two-level fuzzy,
-// 2026-07-02), extracted MOVE-only from ask.mjs (item 13). A reusable SERVICE the
-// strategies call, not a strategy itself: the keyword-spotting strategy's tier-3
-// vocabulary rewrite and resolveObject's tier-5 label pass both read editDistance/
-// fuzzyBound from here, and the "assuming you meant …" announcement discipline
-// (a unique within-bound hit is announced, a tie is refused or surfaced as
-// ambiguity, never a silently-broken guess) is enforced by the callers off these
-// primitives. Deliberately coupled to the curated vocab tables via explicit
-// imports — the fuzzy TARGETS are a closed, curated set, same ethos as the
-// tables themselves. Pure JS, no deps.
+// interpret/fuzzy.mjs — the bounded-edit-distance fuzzy tier, shared by the
+// keyword-spotting and object-resolution strategies. A distance tie is always
+// refused or surfaced as ambiguity, never broken by a guess.
 
 import { VERB_TO_KIND, ENTITY_TO_TYPE, MODIFIER_TO_KIND } from "../ask-vocab.mjs";
 import { STOPWORDS } from "./normalize.mjs";
 
-// ---- bounded edit distance — hand-rolled Damerau-Levenshtein (optimal string
-// alignment: substitution/insertion/deletion + adjacent transposition), bounded
-// with an early row-minimum exit. Fires only after every exact/curated tier
-// missed, and a distance TIE is refused (keyword) or surfaced as ambiguity
-// (object), never broken by a guess. ----
+// ---- bounded edit distance — hand-rolled Damerau-Levenshtein, bounded with an
+// early row-minimum exit ----
 
 /** Distance between a and b, or max+1 as soon as it provably exceeds `max`. */
 export function editDistance(a, b, max) {
@@ -52,13 +42,9 @@ export const VOCAB_WORDS = new Set(
     .flatMap((p) => p.split(" ")),
 );
 
-/** Fuzzy-correction TARGETS: verb-phrase and modifier constituents only, length ≥4.
- *  Entity nouns are deliberately excluded — real identifiers collide with them at
- *  distance ≤2 far too easily ("myfile" is 2 edits from "file", "caller" 2 from
- *  "calls"-family words), and entity-noun typos are already owned by the curated
- *  MISSPELLINGS table where such calls are made deliberately. Short constituents
- *  ("of", "to", "in", "on") are excluded for the same reason: at bound 1 half of
- *  English is adjacent to them. */
+/** Fuzzy-correction TARGETS: verb-phrase and modifier constituents only,
+ *  length ≥4. Entity nouns and short words are excluded — real identifiers
+ *  collide with them too easily at this distance bound. */
 const FUZZY_TARGET_WORDS = [...new Set(
   [...Object.keys(VERB_TO_KIND), ...Object.keys(MODIFIER_TO_KIND)]
     .flatMap((p) => p.split(" "))
@@ -79,13 +65,8 @@ export function fuzzyVocabWord(w) {
   return fuzzyMatchInSet(w, FUZZY_TARGET_WORDS, fuzzyBound(w));
 }
 
-/** GENERIC unique-within-bound fuzzy match of `w` against an arbitrary candidate
- *  list, or null — same discipline as fuzzyVocabWord/resolveObject's tier-5 pass
- *  (a distance tie between two distinct candidates is refused, never guessed),
- *  factored out so callers outside the ask/keyword pipeline (e.g. chat.mjs's
- *  conversational recognizers) can reuse the primitive without a bespoke
- *  target-list wrapper. `bound` defaults to fuzzyBound(w) but callers may pass a
- *  tighter budget (e.g. to keep short conversational tokens conservative). */
+/** Generic unique-within-bound fuzzy match of `w` against an arbitrary
+ *  candidate list, or null on a tie — never guessed. */
 export function fuzzyMatchInSet(w, candidates, bound = fuzzyBound(w)) {
   let best = bound + 1;
   let hit = null;

package/src/interpret/merge.mjs

@@ -1,33 +1,15 @@
-// interpret/merge.mjs — class-grouped merging of strategy results (ROADMAP item 8).
-// Grown from ask.mjs's original two-way merge ("one strategy hit -> use it; both
-// hit and agree -> use it; both hit and DISAGREE -> a genuine parse-level
-// ambiguity; neither hits -> the honest grammar miss") into a general rule over N
-// strategies and N result CLASSES:
-//
-//   · SAME-class candidates merge and rank — identical parses (sameParse) dedupe
-//     onto the highest-precedence strategy's candidate, exactly as the legacy
-//     merge returned "either" result on agreement; multiple DISTINCT parses
-//     surviving in the winning class are the legacy {ambiguousParse, candidates}
-//     surface, rendered by ask.mjs as "this could mean more than one thing: …".
-//   · DISTINCT-class groups produce the ambiguity SURROUND: the winning class
-//     answers, and each other class's best candidate is listed as an
-//     "if you mean X then …" line (alternateLines below) — the generalization of
-//     the engine's existing announced-correction shapes ("assuming you meant …").
-//
-// Winner selection is deterministic: the class holding the highest-confidence
-// candidate wins; a confidence tie goes to the earlier-registered strategy. The
-// two legacy strategies share one class ("graph-query"), so their merge reduces
-// exactly to the original behavior by construction.
+// interpret/merge.mjs — class-grouped merging of strategy results: same-class
+// candidates merge/rank (identical parses dedupe onto the highest-precedence
+// one; distinct ones surface as an honest {ambiguousParse} tie); distinct-class
+// groups surface each other's best candidate as an "if you mean X then …"
+// alternate. Winner = highest-confidence class, ties go to the
+// earlier-registered strategy.
 
 const DEFAULT_CONFIDENCE = 0.5;
 
-// "commit abc1234" and bare "abc1234" are the SAME term once resolveObject's
-// commit-sha tier strips the noun — the anchored strategy captures the noun inside
-// its object span while keyword-spot consumes it as the entity keyword, so without
-// this the two strategies would "disagree" over a word that names no different thing.
-// A leading DETERMINER is the same kind of non-difference (0.8.2 feel wave): the
-// anchored grammar captures "the logger" while keyword-spot captures "logger", and
-// the resulting "ambiguity" asked the user to choose between identical readings.
+// Term equality ignores a leading "commit " on a bare SHA and a leading
+// determiner ("the logger" == "logger") — surface differences the two
+// strategies otherwise disagree over despite meaning the same thing.
 const cmpTerm = (s) => String(s || "").trim().toLowerCase().replace(/\s+/g, " ")
   .replace(/^(?:the|a|an)\s+/, "")
   .replace(/^commit\s+(?=[0-9a-f]{7,40}$)/, "");