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

package/src/planning.mjs

@@ -1,35 +1,6 @@
-// planning.mjs — a domain-agnostic bounded state-space search primitive
-// (PLAN_HANOI.md's Phase 2 kernel, landed ahead of the phased plan as a
-// standalone proof that the mechanism works, per the operator's own framing:
-// "generalizing findIsaChain from 'walk pre-loaded class edges' to 'walk
-// on-demand successor states' is a moderate, in-house-idiom-consistent
-// extension, not a foreign paradigm").
-//
-// `src/syllogise.mjs`'s `findIsaChain` is, in shape, already a bounded rooted
-// BFS path search: it walks a FIXED, pre-loaded edge list (`typeEdges`/
-// `subClassEdges`) from a start node to a target set, frontier-expansion
-// style, checking the frontier for a hit BEFORE extending it one hop further,
-// stopping the instant a target is reached or the hop budget is exhausted.
-//
-// Real planning (Hanoi, or anything with actions) needs the same shape over a
-// state space where successors are NOT pre-loaded — they are generated ON
-// DEMAND by applying an action to the CURRENT state. `findActionPath` below
-// is that generalization: same frontier/seen-set/check-then-extend/shortest-
-// path discipline as `findIsaChain`, but the "edges" come from calling the
-// caller-supplied `applyActions(state)` fresh at every expansion, instead of
-// looking them up in a fixed array.
-//
-// Deliberately NOT sharing code with `findIsaChain` itself: that function's
-// edge lists are pre-built ONCE into a `Map` before the search loop even
-// starts (`subSucc`, `syllogise.mjs:291-296`) — a real, load-bearing
-// optimization for its domain (static edges, looked up many times) that does
-// not apply here (successors are computed fresh, never looked up twice for
-// the same state). Extracting a "shared" BFS core would either lose that
-// optimization or force `findActionPath` to fake a static edge list, so this
-// lands as an independent sibling, following the same DISCIPLINE, not the
-// same code path. `findIsaChain` itself is untouched by this file.
-//
-// Pure, no I/O, deterministic given a deterministic `applyActions`.
+// planning.mjs — a domain-agnostic bounded state-space search primitive,
+// generalizing syllogise.mjs's findIsaChain (fixed pre-loaded edges) to
+// on-demand successor generation via applyActions(state). Pure, no I/O.
 
 /** Default state-identity key: plain values compare by `String()`, plain
  *  objects by a stable-ish `JSON.stringify` (good enough for a toy/plain-
@@ -40,15 +11,8 @@ function defaultStateKey(state) {
   return String(state);
 }
 
-/** The one-hop expansion of `startState` into an initial frontier of
- *  `{ state, actions, states }` path-entries — IDENTICAL in both
- *  `findActionPath` and `findReachableSet` below (seeding a frontier from a
- *  start state has no goal/accumulation semantics to differ on: it is pure
- *  "call `applyActions` once, wrap each result"), so this one small step is
- *  genuinely, safely shared rather than duplicated verbatim in both
- *  functions. See the file-header note above `findActionPath` for why the
- *  REST of the two functions' bodies are deliberately NOT merged the same
- *  way. */
+/** One-hop expansion of `startState` into an initial frontier — shared by
+ *  findActionPath and findReachableSet below. */
 function seedFrontier(startState, applyActions) {
   const frontier = [];
   for (const { action, nextState } of applyActions(startState) || []) {
@@ -58,50 +22,17 @@ function seedFrontier(startState, applyActions) {
 }
 
 /**
- * Bounded, cycle-safe, shortest-path-first breadth-first search over a state
- * space whose successors are generated ON DEMAND, not pre-loaded.
- *
- *   - `startState` — any value; identity for cycle-detection is derived via
- *     `stateKey` (default: `String()`/`JSON.stringify()`).
- *   - `isGoal(state) -> boolean` — goal predicate, checked BEFORE a state is
- *     expanded (never after — see the hop-counting discipline below).
- *   - `applyActions(state) -> Array<{ action, nextState }>` — the caller's
- *     domain logic: given the CURRENT state, the legal (action, resulting-
- *     state) pairs reachable in exactly one step. Called fresh every time a
- *     state is expanded; nothing is precomputed or cached across calls.
- *   - `opts.maxDepth` (default 50) — hop budget, mirrors `findIsaChain`'s
- *     `maxHops`: the frontier is checked for the goal AT every depth up to
- *     and including `maxDepth`, but never extended past it (check-then-
- *     extend — `findIsaChain`'s own comment on this exact off-by-one:
- *     "the frontier is checked AT every length up to and including maxHops,
- *     never one hop beyond it").
- *   - `opts.stateKey(state) -> string` — override the default identity key
- *     when `startState`/successor states are richer than a plain
- *     string/number/JSON-able object.
- *
- * Returns `{ actions: [...], states: [startState, ...,goalState] }` on
- * success (the full action sequence AND the resulting state at each step, so
- * a caller can actually execute the plan, not just know one exists), or
- * `null` when no path reaches a goal state within `maxDepth` — an honest
- * miss, never a guessed/truncated path.
- *
- * Cycle-safe via a `seen` state-key set (this function's direct precedent:
- * `findIsaChain`'s own `seen` set, `syllogise.mjs:311`) — a state is only
- * ever expanded once, the first (shortest) path to reach it, so a domain
- * with cycles (two states that can reach each other) still terminates and
- * still returns the correct shortest path, never loops.
+ * Bounded, cycle-safe, shortest-path-first BFS over a state space whose
+ * successors are generated on demand via `applyActions(state)`, checked
+ * against `isGoal` before each expansion up to `opts.maxDepth` hops.
+ * Returns `{ actions, states }` (the full plan) or `null` on an honest miss.
  */
 export function findActionPath(startState, isGoal, applyActions, { maxDepth = 50, stateKey = defaultStateKey } = {}) {
   if (isGoal(startState)) return { actions: [], states: [startState] };
 
   let frontier = seedFrontier(startState, applyActions);
 
-  // depth counts the LENGTH of the paths currently in `frontier` (1 at the
-  // first check) — exactly `findIsaChain`'s own "hop counts the LENGTH of the
-  // paths currently in frontier" discipline. Check-then-extend, and never
-  // extend past maxDepth: the frontier is checked at every depth up to and
-  // including maxDepth, never one hop beyond it (the off-by-one findIsaChain
-  // itself once had and fixed — not reintroduced here).
+  // Check-then-extend: never extend past maxDepth.
   const seen = new Set([stateKey(startState)]);
   for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
     for (const entry of frontier) if (isGoal(entry.state)) return { actions: entry.actions, states: entry.states };
@@ -122,91 +53,18 @@ export function findActionPath(startState, isGoal, applyActions, { maxDepth = 50
   return null;
 }
 
-// ---------------------------------------------------------------------------
-// findReachableSet — PLAN_TAUGHT_RELATIONS.md, Item 6 (recursive/reachability
-// rules) kernel half. Query-side need: "list every X reachable from Y" (e.g.
-// "list the descendants of ahab") is REACHABILITY-SET ENUMERATION, not
-// single-goal search — checked against `findActionPath` above's own body:
-// it returns the INSTANT the first goal-satisfying state is found (the
-// `for (const entry of frontier) if (isGoal(entry.state)) return …` line),
-// so there is no way to keep it running to collect every reachable node
-// without changing both its halting condition (early-return vs. never-
-// return-early) AND its return shape (one path vs. every path) — a
-// genuinely new function, not a parameter tweak, per the plan's own
-// analysis.
-//
-// Code-sharing decision (asked for explicitly, decided fresh here rather
-// than copying the plan doc's framing verbatim): the file-header reasoning
-// for why `findActionPath` is an independent SIBLING of `findIsaChain`
-// (lines 1-32) is "pre-built static edge maps vs. on-demand successor
-// generation don't share an implementation, only a discipline." That
-// reasoning does NOT distinguish `findActionPath` from `findReachableSet`
-// — both call the caller's `applyActions(state)` fresh at every expansion;
-// neither pre-builds anything. So on the file's own stated logic, these two
-// are legitimately closer to each other than either is to `findIsaChain`,
-// and it's worth asking whether MORE sharing is warranted here specifically
-// — not just repeating the same verdict by default.
-//
-// Having written both bodies out, the answer is: share the one step that is
-// truly identical (`seedFrontier` above — a single `applyActions(startState)`
-// call with no goal/accumulation semantics to differ on), but keep the main
-// expand-loop bodies independent. The reason isn't "different edge
-// generation" this time — it's that the two loops' HALTING and RESULT-
-// COLLECTION semantics are irreducibly different: `findActionPath` returns
-// the instant ANY frontier entry satisfies `isGoal`, discarding the rest of
-// the frontier and every state it hasn't reached yet; `findReachableSet`
-// never returns early, has no predicate at all, and must keep every
-// newly-seen state (not just one) across the entire bounded search. Forcing
-// both through one shared "expand a frontier" core would mean threading an
-// optional `isGoal` (or a sentinel "never" predicate) AND an accumulator
-// mode through a single function — that parameter surface would itself
-// recreate the complexity the merge was meant to remove, for a savings of
-// roughly the ~10-line inner loop. Given the file's own established
-// precedent of favoring readable independent siblings over cleverly
-// parameterized cores, and that the one truly shared step already isn't
-// duplicated (`seedFrontier`), landing this as an independent sibling
-// remains the right call — just not for the identical reason `findIsaChain`
-// vs. `findActionPath` had.
 /**
- * Bounded, cycle-safe breadth-first ENUMERATION of every state reachable
- * from `startState` within `maxDepth` hops — the reachability-set sibling of
- * `findActionPath`'s single-goal search.
- *
- *   - `startState`, `applyActions`, `opts.maxDepth`, `opts.stateKey` — same
- *     meaning and defaults as `findActionPath` (see above); successors are
- *     generated ON DEMAND by calling `applyActions(state)` fresh at every
- *     expansion, nothing precomputed or cached.
- *   - Deliberately NO `isGoal` parameter: every state reachable from
- *     `startState` (EXCLUDING `startState` itself — the start is where you
- *     already are, not a reachable result) within the hop budget is a
- *     result, not just one goal-satisfying state.
- *
- * Returns an array of `{ node, path: { actions, states } }` — one entry per
- * distinct reachable state, `path` mirroring `findActionPath`'s own
- * `{ actions, states }` return shape (the action sequence AND intermediate
- * states from `startState` to that node), so a caller gets "how did we get
- * here" for every reachable node, not just one. Returns `[]` (never
- * `null`/`undefined`) when nothing is reachable within budget — reachability
- * enumeration has no "miss" case the way single-goal search does; an empty
- * result set is itself the honest, complete answer.
- *
- * Cycle-safe via the same `seen` state-key convention as `findActionPath`: a
- * state is recorded (and expanded) only the FIRST time it is reached, so the
- * shortest path to it is what gets stored, and a state reachable by two
- * different routes (or sitting inside a genuine cycle) is reported exactly
- * once, never duplicated, and never causes an infinite loop.
+ * Bounded, cycle-safe BFS enumeration of every state reachable from
+ * `startState` within `maxDepth` hops (no `isGoal` — excludes `startState`
+ * itself). Shares seedFrontier with findActionPath but keeps its own
+ * expand-loop (collect-everything vs. early-return-on-first-hit). Returns
+ * `[{ node, path: { actions, states } }]`, `[]` when nothing is reachable.
  */
 export function findReachableSet(startState, applyActions, { maxDepth = 50, stateKey = defaultStateKey } = {}) {
   let frontier = seedFrontier(startState, applyActions);
 
   const seen = new Set([stateKey(startState)]);
   const results = [];
-  // Single combined loop (not findActionPath's check-then-separate-extend):
-  // there is no per-iteration early return to protect here, so recording a
-  // newly-seen state and deciding whether to expand it past it can live in
-  // the same pass without losing any of findActionPath's check-then-extend
-  // discipline — a state discovered exactly at maxDepth is still recorded
-  // (it IS reachable within budget) but is never expanded past it.
   for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
     const next = [];
     for (const entry of frontier) {

package/src/prose-nlp.mjs

@@ -1,21 +1,8 @@
 // prose-nlp.mjs — the OPTIONAL wink-nlp lemma loader behind prose.mjs's LEMMA layer.
-//
-// Kept SEPARATE from ask-nlp.mjs (its own `proseLemma` export shape) rather than an
-// import of that ask-engine surface — but both now share the neutral leaf loader
-// src/wink-model.mjs, so the wink model is resolved in ONE place. The former ~20
-// duplicated createRequire lines are gone; the coupling this file avoids is to
-// ask-nlp.mjs's export shape, not to a leaf model loader.
-//
-// BOUNDARY (same as ask-nlp.mjs, hard): Node-only path, never inlined into the
-// viewer bundle. prose.mjs is itself never inlined by viz.mjs's askSource(), so
-// nothing browser-side can reach this module. The wink pair is loaded lazily (Node
-// createRequire fallback, or the browser registration seam), failure cached as null:
-// a checkout without the optional deps simply builds no lemma layer (honestly
-// absent), it never throws.
-//
-// Determinism: wink's lemmatiser is a fixed trained model with no sampling — the
-// same token always yields the same lemma across runs and processes, which is what
-// lets the lemma layer meet the "byte-identical proseIndex across builds" contract.
+// Node-only, never inlined into the viewer bundle; loaded lazily and cached, so a
+// checkout without the optional deps builds no lemma layer (honestly absent),
+// never throws. Wink's lemmatiser is deterministic (no sampling), which is what
+// keeps the built proseIndex byte-identical across builds.
 
 import { winkInstance } from "./wink-model.mjs";
 

package/src/prose.mjs

@@ -1,35 +1,11 @@
-// prose.mjs — the second-pass prose extraction + cross-reference index (PLAN_PROSE_INDEX.md).
-//
-// Deterministic, zero-model-calls, zero dependencies: pure string transforms + a plain-object
-// inverted index over data graph-build.mjs's typed pass has already produced (identifier names,
-// captured doc text). Two token sources, one combined set per individual:
-//   1. identifier decomposition — names are often literal sentence fragments
-//      ("calculateTotalPriceIncludingTax" -> calculate/total/price/including/tax); splitting
-//      them turns every symbol/module name into free-text search surface for zero extra cost.
-//   2. prose literals — docstrings/doc-comments already captured as the `doc` attribute.
-//      Python (extract_ast.py) and JS/TS (jsts_tsc.mjs's firstDocLine) already populate this;
-//      C#/Java's PRIMARY extractors (cs_roslyn.mjs, java_javaparser.mjs) shell out to compiled
-//      Roslyn/JavaParser binaries — adding doc capture there means modifying and rebuilding
-//      external .NET/JVM tooling, not a JS-side change. Deliberately deferred (PLAN_PROSE_INDEX.md
-//      backlog); this pass consumes whatever `doc` is already present, regardless of source
-//      language, so C#/Java modules still get identifier-decomposition tokens today.
-//
-// Tokenizer pattern (stopwords, length bounds, per-doc token cap) mirrors marginalia's
-// app/lib/text-index.mjs — a proven lexical-inverted-index tokenizer for the same "search by
-// keyword, no embeddings, no stemmer dependency" problem, adapted for code identifiers.
-//
-// Storage: (a) a `prose_tokens` attribute (space-joined, deduped, sorted) on each individual —
-// the graph stays self-describing, works if a consumer only has one individual in hand; AND
-// (b) a real inverted index (word -> [individual ids]) built from those same tokens and
-// attached as `entities.proseIndex` — an O(1) word lookup for consumers (resolveObject-style
-// fuzzy object-term resolution, scoreModules-style lexical boosting) instead of scanning every
-// individual's attributes. Both are derived from the identical token set, so they can never
-// disagree; (b) is just (a) inverted once, cheaply, at build time.
+// prose.mjs — the second-pass prose extraction + cross-reference index.
+// Deterministic, no model calls: tokenizes each individual's decomposed name
+// plus any captured `doc` text into a combined set, stored both as a
+// `prose_tokens` attribute (self-describing) and inverted into
+// `entities.proseIndex` (word -> ids) for O(1) lookup.
 
-// Exported (as of PLAN_COMPLETIONS.md Stage 0) so src/completions/group.mjs can filter
-// splitIdentifierWords' output (which, unlike tokenizeProse, does NOT apply this list — it's
-// built for code identifiers, where stopword-shaped fragments are rare) down to real content
-// words before using it as a text-clustering similarity signal.
+// Exported so src/completions/group.mjs can filter splitIdentifierWords'
+// output (which doesn't apply this list itself) down to real content words.
 export const STOPWORDS = new Set(
   ("a an and or but the of to in on at for with from by as is are was were be been being " +
     "it its this that these those i you he she they we me my your our do does did not no " +
@@ -38,7 +14,7 @@ export const STOPWORDS = new Set(
     "where why how").split(/\s+/),
 );
 
-const MAX_TOKEN_LEN = 40;    // drops hash-like/garbage tokens (marginalia text-index.mjs)
+const MAX_TOKEN_LEN = 40;    // drops hash-like/garbage tokens
 const MAX_TOKENS_PER_DOC = 120; // bounds cost on a pathologically long docstring/name
 
 /** Split an identifier or a path-like name into lowercase word tokens.
@@ -81,17 +57,10 @@ export function proseTokensFor({ name, doc } = {}) {
   return [...set].sort();
 }
 
-/** Second pass (PLAN_PROSE_INDEX.md): attach a `prose_tokens` attribute to every
- *  individual in `individuals`, deriving tokens from its name and captured prose text.
- *  Class-aware source selection: Module/Function/Method/Class/Attribute/GlobalVariable use
- *  `label` (a real identifier/path — decomposable, e.g. "calculateTotalPrice") + a `doc`
- *  attribute if present (docstring/doc-comment). Commit is different: its `label` is a
- *  truncated SHA (hex noise if decomposed, e.g. "e6a9419567f7" -> "9419567" garbage) — skip
- *  decomposing it and tokenize its `message` attribute instead, which is the real prose
- *  (commit messages are often the richest free text in the whole graph). Mutates and
- *  returns the same array — safe to call once after the typed individuals are built.
- *  `enabled=false` is a no-op (the disable path `TMCT_PROSE_INDEX=0` in a graph writer), so
- *  the core typed graph is never affected by turning this pass off. */
+/** Attach a `prose_tokens` attribute to every individual, from its (decomposed)
+ *  name and captured doc text — except Commit, whose `label` is a truncated
+ *  SHA, not a decomposable identifier: it tokenizes `message` instead. Mutates
+ *  and returns the same array; `enabled=false` is a no-op. */
 export function attachProseTokens(individuals, { enabled = true } = {}) {
   if (!enabled) return individuals;
   for (const ind of individuals) {
@@ -130,8 +99,7 @@ export function buildProseIndex(individuals) {
  *  tokenized the same way as a docstring), ranked by overlap count (most shared words
  *  first). This is the integration point for ask.mjs's resolveObject (fuzzy object-term
  *  resolution beyond exact/substring match) and codegraph.mjs's scoreModules (a lexical
- *  boost source) — see PLAN_PROSE_INDEX.md for the exact call-site recommendation; not
- *  wired into either file here to avoid colliding with concurrent work on them.
+ *  boost source); not wired into either file here.
  *  `proseIndex` is `entities.proseIndex` (buildProseIndex's output). */
 export function lookupByProseTokens(proseIndex, query, { limit = 10 } = {}) {
   const queryTokens = [...new Set([...splitIdentifierWords(query), ...tokenizeProse(query)])];
@@ -148,28 +116,12 @@ export function lookupByProseTokens(proseIndex, query, { limit = 10 } = {}) {
     .map(([id, score]) => ({ id, score }));
 }
 
-/** OPT-IN read accessor for codegraph.mjs's `proseLayers` locate signal (this file's index
- *  build is unchanged — this only READS the layers the pre-pass already wrote). Given a query
- *  `token`, return the individual ids reachable through the NORMALISED prose layers
- *  (spell-corrected / canonical-schema-term / stem / lemma) stored under
- *  `proseIndex["tmct:layers"]` — the same normalised layers ask.mjs's resolveObject consults,
- *  here surfaced for the locate SCORER so a task-text word that only overlaps a module via a
- *  normalised form still resolves.
- *
- *  Layer shape consumed (an inverted index keyed by the NORMALISED token, mirroring the verbatim
- *  top level, just normalised):
- *    proseIndex["tmct:layers"] = { <layerName>: { <normalisedToken>: [id, …] }, … }
- *  A posting may be a plain id array or `{ ids: [...] }` — both are tolerated. The raw query
- *  token is looked up directly against every layer's keys, so a token whose surface form is
- *  already a canonical/stem/lemma/spell-corrected key hits; the accessor never itself normalises
- *  the query (it owns no normaliser — those live in the concurrent ask/prose-nlp surface), so it
- *  can never disagree with the build's normalisation, only under-fire safely.
- *
- *  Returns { ids, via }: `ids` a deduped, sorted (stable/deterministic) id list; `via` the
- *  sorted layer names that produced them, joined with "+", for a scorer's provenance — or null
- *  when nothing hit. Absent / malformed / pre-layers `proseIndex` → { ids: [], via: null }: a
- *  safe no-op, so the opt-in flag degrades to nothing on a graph indexed before layers existed.
- *  Accepts either a `proseIndex` object or a parsed graph (reads its `.proseIndex`). */
+/** Read accessor for the NORMALISED prose layers (spell-corrected /
+ *  canonical-schema-term / stem / lemma) under `proseIndex["tmct:layers"] =
+ *  { layerName: { normalisedToken: [id, …] } }`, so a query word that only
+ *  overlaps a module via a normalised form still resolves. Returns
+ *  { ids, via } (deduped/sorted ids, the layer names that matched); a safe
+ *  no-op `{ ids: [], via: null }` on an absent/pre-layers proseIndex. */
 export function proseLayerHits(proseIndex, token) {
   const src = proseIndex && (proseIndex["tmct:layers"] ? proseIndex : proseIndex.proseIndex);
   const layers = src && src["tmct:layers"];

package/src/providers/bootstrap.mjs

@@ -1,6 +1,5 @@
 // The BOOTSTRAP reference provider — the empty/degenerate graph a fresh repo
-// "contains" before anything is indexed. archive/PLAN_REPOSITORY_INTERFACE.md deliverable
-// 2: "bootstrap returns honest empties".
+// "contains" before anything is indexed.
 //
 // It implements every Repository-Interface service over the empty bootstrap
 // payload (src/source.mjs emptyEntities): every id-taking service returns

package/src/providers/fixture.mjs

@@ -1,6 +1,5 @@
 // The FIXTURE reference provider — a small, real, self-contained code graph that
-// implements every Repository-Interface service. archive/PLAN_REPOSITORY_INTERFACE.md
-// deliverable 2: "the executable specification an external producer reads first".
+// implements every Repository-Interface service.
 //
 // It is a degenerate provider in the sense that its graph is tiny and its source
 // bodies are absent (snippet/context answer NO_SOURCE) — but every OTHER service

package/src/providers/graph-service.mjs

@@ -1,5 +1,4 @@
 // The reference Repository-Interface service over a parsed code graph.
-// archive/PLAN_REPOSITORY_INTERFACE.md — "the executable specification".
 //
 // createGraphService(graph) returns a typed service object implementing EVERY
 // service in src/repository-interface.mjs over the `{ individuals, byId,
@@ -67,14 +66,10 @@ function groupMetaForKind(graph, kind) {
 const CONTEXT_BODY_MAX_LINES = 200; // mirrors server.mjs's SNIPPET_MAX_LINES for the source-capable body sections
 const CONTEXT_INLINE_CALLEE_LOC = 120; // mirrors server.mjs's INLINE_CALLEE_LOC budget
 
-/** The fs-dependent half of context()'s bundle — anchor / exemplar / inlined-callee body
- *  TEXT — layered on top of renderGraphOnlyBundle's pure sections when the provider is
- *  source-capable. Mirrors server.mjs's buildContextBundle body sections (same shape, same
- *  safe readSpanSafe/sliceSpan primitives from Item 1) but lives here because it needs fs,
- *  which codegraph.mjs deliberately never touches. Read failures degrade silently (an
- *  omitted section), matching buildContextBundle's own graceful-degradation behavior —
- *  this is a best-effort enrichment on top of an already-real graph-only hit, not a new
- *  failure mode. Returns "" when nothing could be rendered. */
+/** The fs-dependent half of context()'s bundle — anchor/exemplar/inlined-callee body TEXT —
+ *  layered on top of renderGraphOnlyBundle's pure sections when source-capable. Read
+ *  failures degrade silently (an omitted section, never a throw). Returns "" when nothing
+ *  could be rendered. */
 async function renderSourceBodies(plan, mask, { readFile, repoRoot }) {
   if (!plan.moduleLabel) return "";
   let lines = null;
@@ -123,17 +118,14 @@ async function renderSourceBodies(plan, mask, { readFile, repoRoot }) {
  * @param {object} graph  a parseEntities() result
  * @param {object} [opts]
  * @param {boolean} [opts.sourceAccess=false]  whether source services (snippet, context) read
- *   real fs bodies. When true, `repoRoot` + `readFile` are REQUIRED (a programmer error to
- *   omit either — this module stays fs-free otherwise, "pure graph queries, no fs" by default;
- *   fs is an explicit INJECTED capability, never an ambient import).
+ *   real fs bodies. When true, `repoRoot` + `readFile` are required (fs is an injected
+ *   capability, never an ambient import).
  * @param {string} [opts.repoRoot]  absolute repo root; required when sourceAccess is true.
- * @param {Function} [opts.readFile]  async (path, encoding) => string, e.g. node:fs/promises'
- *   readFile; required when sourceAccess is true.
- * @param {object|null} [opts.tel]  an optional telemetry sink ({ record(fields) }, e.g. from
- *   telemetry.mjs's createTelemetry). When present, every service is wrapped ONCE here to time
- *   it and record `{ tool: "ri.<name>", perf: { ms_total }, response: { ok, count } }` — counts
- *   only, never raw text/body. Null (the default) skips the wrapping loop entirely — zero
- *   overhead, and fixtureProvider()/bootstrapProvider() (which pass no tel) are unaffected.
+ * @param {Function} [opts.readFile]  async (path, encoding) => string; required when
+ *   sourceAccess is true.
+ * @param {object|null} [opts.tel]  an optional telemetry sink ({ record(fields) }). When
+ *   present, every service is wrapped once to time it and record counts only, never raw
+ *   text/body.
  * @returns the typed service object
  */
 export function createGraphService(graph, { sourceAccess = false, repoRoot = null, readFile = null, tel = null } = {}) {
@@ -192,7 +184,7 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
       const bases = inherits
         .filter((e) => e.subject === classId)
         .map((e) => byId.get(e.object) ? toIndividual(byId.get(e.object)) : { id: e.object, label: e.objectLabel || e.object, class: "Class", attributes: [] });
-      // transitive reverse inheritance closure (who extends this)
+      // transitive reverse inheritance closure
       const childrenOf = new Map();
       for (const e of inherits) {
         if (!childrenOf.has(e.object)) childrenOf.set(e.object, []);
@@ -256,9 +248,7 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
       const ind = resolveId(id);
       if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
       const meta = groupMetaForKind(graph, kind);
-      // edge order is stable/memoized (edgesOfKind's own docblock in codegraph.mjs) — a plain
-      // slice after filter/map is a safe, backward-compatible pagination: an omitted `limit`
-      // leaves the full list untouched (limit=undefined → slice(offset) → everything from offset).
+      // edge order is stable/memoized; an omitted `limit` leaves the full list untouched.
       let edges = edgesOfKind(graph, kind)
         .filter((e) => e.subject === id)
         .map((e) => toEdge(e, meta));
@@ -274,11 +264,8 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
       return hit({ total, levels });
     },
 
-    // NOTE: async (returns Promise<Result>) — real source reads (node:fs/promises) are
-    // inherently async, and unlike the pure graph services above, a caller of a
-    // source-reaching service should always `await` it regardless of whether THIS
-    // particular provider happens to be source-capable (awaiting a non-Promise value is a
-    // safe no-op, so this is backward-compatible for a caller that already awaits).
+    // Async (returns Promise<Result>): callers should always await a source-reaching
+    // service regardless of whether this provider happens to be source-capable.
     async snippet(id) {
       const ind = resolveId(id);
       if (!ind) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: id });
@@ -296,18 +283,13 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
         });
         return hit({ path: site.path, span: { start: site.start, end: site.end }, body: sliced.text });
       } catch (e) {
-        // A path-traversal ToolError or any other read failure both land here — honestly,
-        // never a throw (the interface's error contract: a clean miss is a value).
         return miss(MISS_REASONS.NO_SOURCE, { term: id, detail: `could not read ${site.path}: ${e?.message || e}` });
       }
     },
 
-    // INTERFACE_VERSION 1.1.0 (2d): context() is now a graph-only HIT for any resolvable
-    // symbol — contextPlan/sizeBundle/renderGraphOnlyBundle are pure graph queries, so a
-    // graph-only provider (no working tree) can genuinely answer with siblings/registration/
-    // globals/tests/exports/insertion-region, everything EXCEPT anchor/exemplar/inlined-callee
-    // body TEXT. Only an unresolvable symbol still misses (UNRESOLVED_TERM). A source-capable
-    // provider layers the body sections on top via renderSourceBodies (below).
+    // A graph-only HIT for any resolvable symbol (siblings/registration/globals/tests/
+    // exports/insertion-region), everything except anchor/exemplar/inlined-callee body TEXT.
+    // A source-capable provider layers the body sections on top via renderSourceBodies.
     async context(symbol, { depth = "auto" } = {}) {
       const { match } = resolveSymbol(graph, String(symbol ?? ""));
       if (!match) return miss(MISS_REASONS.UNRESOLVED_TERM, { term: String(symbol ?? "") });
@@ -389,14 +371,9 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
       return hit({ commits });
     },
 
-    // Ranked lexical search, mirroring codegraph.mjs's renderSearch/searchSymbols semantics
-    // instead of the old flat substring filter: module-mode (no kind, or kind="module") ranks
-    // via searchModulesRanked/scoreModules (path + defined-symbol + import-proximity scoring),
-    // symbol-mode (kind names a symbol kind) ranks via scoreSymbolsRanked. name/decorator
-    // filters apply in SYMBOL mode only — module mode never supported them in codegraph.mjs
-    // either (renderSearch's module branch ignores both beyond the "was anything specified"
-    // check), so this does not invent a new filter semantic. Results are capped at
-    // `limit` (default SEARCH_LIMIT), sliced after the full ranked array is computed.
+    // Ranked lexical search: module-mode (no kind, or kind="module") ranks via
+    // searchModulesRanked; symbol-mode (kind names a symbol kind) ranks via
+    // scoreSymbolsRanked, with name/decorator filters. Results capped at `limit`.
     search(query, { kind = "", name = "", decorator = "", limit = SEARCH_LIMIT, offset = 0 } = {}) {
       const rawQuery = String(query || "");
       const k = String(kind || "").trim().toLowerCase();
@@ -411,8 +388,8 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
         const tokens = rawQuery.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
         rankedInds = scoreSymbolsRanked(graph, tokens, { kind: k, decFilter: dec, nameRe }).map((s) => s.ind);
       } else {
-        // label→individual, scoped to this call (no persistent cache) — maps searchModulesRanked's
-        // `path` labels (a copy of the label, not the live individual) back to real Individuals.
+        // label -> individual, scoped to this call: maps searchModulesRanked's path labels
+        // back to real Individuals.
         const byLabel = new Map();
         for (const i of graph.individuals) if ((i.class || "") === "Module") byLabel.set(i.label, i);
         rankedInds = searchModulesRanked(graph, rawQuery)
@@ -429,11 +406,8 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
     },
   };
 
-  // Optional telemetry (Item 3.2): when `tel` is supplied, wrap every RI service ONCE here at
-  // construction — never per-method by hand — to time it and record COUNTS only (never raw
-  // text/body; see responseCounts below and telemetry.mjs's redact() as a second net). When
-  // `tel` is null (the default), this loop does not run at all: zero overhead, and
-  // fixtureProvider()/bootstrapProvider() (which pass no `tel`) are completely unaffected.
+  // Optional telemetry: wrap every RI service once here to time it and record counts only,
+  // never raw text/body. `tel` null (the default) skips the wrapping loop entirely.
   if (tel) {
     for (const name of SERVICES) {
       const orig = svc[name];
@@ -441,10 +415,7 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
       svc[name] = (...args) => {
         const t0 = performance.now();
         const result = orig.apply(svc, args);
-        // snippet/context are ASYNC (Promise<Result>) — record after settling, still return a
-        // promise; every other service is synchronous — record immediately, return the value
-        // as-is. Detected at the ACTUAL call (not a static per-service list) so this is correct
-        // even if a future service's sync/async-ness varies by branch.
+        // snippet/context are async; record after settling but still return a promise.
         if (result && typeof result.then === "function") {
           return result.then((r) => {
             recordTelemetry(tel, name, performance.now() - t0, r);
@@ -468,10 +439,8 @@ function recordTelemetry(tel, name, ms, result) {
   } catch { /* telemetry must never break the caller's turn */ }
 }
 
-/** Counts only, never raw text/body: { ok, count } — count is the sum of every array-valued
- *  field's length under result.value (edges.length, results.length, candidates.length, …), a
- *  single generic aggregate rather than guessing each service's own field names. A miss
- *  records its reason (a closed-set token, not free text) instead of a count. */
+/** Counts only, never raw text/body: { ok, count } — count sums every array-valued field's
+ *  length under result.value. A miss records its reason instead of a count. */
 function responseCounts(result) {
   if (!result || typeof result !== "object" || result.ok !== true) {
     return { ok: false, reason: result?.miss?.reason || null };

package/src/repository-interface.mjs

@@ -1,6 +1,6 @@
 // The Repository Interface — tmct's OWNED, versioned contract between "interpret
 // the query" (tmct, the brittle side) and "ask the graph for truth" (a provider,
-// the stable side). archive/PLAN_REPOSITORY_INTERFACE.md.
+// the stable side).
 //
 // tmct defines and versions this shape; a provider (seonix, a fixture, a browser
 // page) IMPLEMENTS it over its native graph. Both sides already agree on the
@@ -17,7 +17,7 @@
 
 /** SemVer of the interface. Additive-by-default: new services / optional args are
  *  minor bumps; the suite for version N stays green under N+1. A breaking change
- *  is a new MAJOR with its own suite (see the versioning policy in the plan). */
+ *  is a new MAJOR with its own suite. */
 export const INTERFACE_VERSION = "1.1.0";
 
 /** The OWL vocabulary the types are grounded in. */
@@ -275,15 +275,13 @@ export const REPOSITORY_INTERFACE = Object.freeze({
     context: {
       group: "source", args: { symbol: "string", depth: "min|auto|full?" },
       result: "{ text: string, tier: string } (a sized edit bundle) — Promise<Result>",
-      // INTERFACE_VERSION 1.1.0 (2026-07): NARROWED miss contract — context() used to
-      // unconditionally miss(NO_SOURCE) (its whole edit bundle was implemented as fs-only).
       // contextPlan/sizeBundle/renderGraphOnlyBundle are pure graph queries, so a graph-only
-      // provider (sourceAccess:false) now returns a REAL HIT for any resolvable symbol —
+      // provider (sourceAccess:false) returns a REAL HIT for any resolvable symbol —
       // siblings, registration, class members, __all__/re-exports, insertion region, covering
       // tests, co-change — everything except anchor/exemplar/inlined-callee BODY TEXT, which
-      // still needs a source-capable provider. NO_SOURCE is consequently no longer a miss
-      // reason context() can return (dropped from the list below) — the only remaining miss is
-      // an unresolvable symbol.
+      // still needs a source-capable provider. NO_SOURCE is therefore not a miss reason
+      // context() can return (not in the list below) — the only remaining miss is an
+      // unresolvable symbol.
       misses: ["UNRESOLVED_TERM"], concurrency: CONCURRENT_SAFE,
       purpose: "The composed edit bundle (exemplar, siblings, registration, insertion region). A graph-only provider returns the graph-only sections as a real hit; a source-capable provider (sourceAccess:true, repoRoot, readFile) additionally includes the anchor/exemplar/inlined-callee body text.",
       note: "ASYNC (returns Promise<Result>) — see snippet's note; source-capable rendering is fs I/O.",