@polycode-projects/the-mechanical-code-talker 2.7.3 → 2.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.7.3",
+  "version": "2.7.5",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
@@ -135,6 +135,7 @@
     "roll": "node scripts/roll.mjs",
     "build:ask-bundle": "node scripts/build-ask-bundle.mjs",
     "build:chat-bundle": "node scripts/build-chat-bundle.mjs",
+    "build:spider-fly-bundle": "node scripts/build-spider-fly-bundle.mjs",
     "build:chat-seed": "node scripts/build-chat-seed.mjs",
     "build:demo-graph": "node scripts/build-demo-graph.mjs",
     "build:demo-pack": "node scripts/build-demo-pack.mjs",

package/src/adapters/memory/core.mjs

@@ -712,6 +712,7 @@ function sourceIdFor(desc) {
     case "teach": return { id: desc.sessionId ? `${TEACH_SOURCE_ID}:${desc.sessionId}` : TEACH_SOURCE_ID, type: "teach" };
     case "provider": return { id: `src:provider:${desc.name}`, type: "provider" };
     case "corpus": return { id: `src:corpus:${desc.name}`, type: "corpus" };
+    case "corpusWeak": return { id: `src:corpus-weak:${desc.name}`, type: "corpusWeak" };
     // One Source per pack article (the @revid stays in the article segment),
     // so two facts from the same article corroborate nothing extra.
     case "reference": return { id: `src:reference:${desc.pack}:${desc.article}`, type: "reference" };

package/src/domain/router/drive.mjs

@@ -6,20 +6,29 @@
 // build a { dispatch, resolve, graph } context against the repo's actual code
 // graph, then run a request through resolver -> planner -> goal-reasoner.
 //
-// Single-shot -> the resolver. A compound "... then ..."/"if ..."/"of the ...,
-// which are ..." request -> the planner, HTN-decomposed into an ordered call
-// sequence with a POP causal-link proof chain, then folded into ONE composed
-// answer via the same set-algebra the HTN method names (relative-filter ->
-// intersect; conditional -> fallback/guard). A refused WORLD goal ("make every
-// disk rest on peg-c") is tried against the taught capability records next
-// (runTaughtPlan — selected by backward chaining, grounded by pure simulation,
-// never dispatched). A request none of those ground escalates to the
-// closed-world goal-reasoner — a maintenance-invariant deduction
-// (coverage-gap / cochange-risk), never a keyword guess. Anything no stage
-// grounds is an honest refuse, the same "grounded or an honest miss" contract
-// as every other tmct answer path.
+// Single-shot -> the resolver. A single-shot bound argument that TIES between
+// two same-tier candidates (a source module and its own test module, the
+// graph's own `tests` edge — never a raw score tie alone) never picks one
+// arbitrarily: the resolver dispatches a read per tied candidate and refuses
+// with `candidateResults` carrying both, the enumerate-or-refuse discipline
+// the chat surface's own ambiguous-entity refusal already uses. A compound
+// "... then ..."/"if ..."/"of the ..., which are ..." request -> the planner,
+// HTN-decomposed into an ordered call sequence with a POP causal-link proof
+// chain, then folded into ONE composed answer via the same set-algebra the HTN
+// method names (relative-filter -> intersect; conditional -> fallback/guard).
+// A "<primary>, and if <it came up empty>, <fallback> instead" request
+// decomposes to the RECOVER method instead: the primary dispatches, its own
+// structured result is OBSERVED, and the fallback dispatches only when that
+// observation is empty (`recovered:true`) — never both, and never neither. A
+// refused WORLD goal ("make every disk rest on peg-c") is tried against the
+// taught capability records next (runTaughtPlan — selected by backward
+// chaining, grounded by pure simulation, never dispatched). A request none of
+// those ground escalates to the closed-world goal-reasoner — a maintenance-
+// invariant deduction (coverage-gap / cochange-risk), never a keyword guess.
+// Anything no stage grounds is an honest refuse, the same "grounded or an
+// honest miss" contract as every other tmct answer path.
 
-import { resolveOne, backwardChainWorld } from "./resolver.mjs";
+import { resolveOne, backwardChainWorld, resolveMemoryTerm } from "./resolver.mjs";
 import { plan, isMultiStep, decompose, MAX_STEPS } from "./planner.mjs";
 import { goalReason } from "./goal-reasoner.mjs";
 import { capabilities } from "./registry.mjs";
@@ -136,7 +145,12 @@ export async function runResolverPlan(request, tools, ctx) {
 
   const r = await resolveOne(request, tools, ctx, { execute: true });
   if (r.refused) {
-    return { calls: [], refused: true, terminated: true, proof: [], driver: ROUTER_DRIVER, why: r.reason };
+    return {
+      calls: [], refused: true, terminated: true, proof: [], driver: ROUTER_DRIVER, why: r.reason,
+      // the tied-candidate composer's answer: one dispatched read per tied
+      // candidate, riding the refusal rather than an arbitrary pick.
+      ...(r.candidateCalls ? { candidateResults: r.candidateCalls } : {}),
+    };
   }
   return {
     calls: [r.selected], refused: false, terminated: true, proof: r.proof,
@@ -232,10 +246,17 @@ export async function runTaughtPlan(request, tools, ctx) {
  *  agentbench's driver-resolver.mjs + driver-goal.mjs composition, with no
  *  agentbench/ dependency (agentbench/ is dev-only, never shipped). Returns a
  *  loopResult:
- *  `{ calls, refused, terminated, proof, why, driver, composed?, observed? }`. */
+ *  `{ calls, refused, terminated, proof, why, driver, composed?, observed?, candidateResults? }`.
+ *
+ *  A C1 refusal that already carries `candidateResults` (the tied-candidate
+ *  composer's enumerate-or-refuse answer) is TERMINAL — it stands as-is rather
+ *  than escalating further, the same way a grounded C1 answer stands. Escalating
+ *  it would silently trade a complete "both tied readings, dispatched" answer
+ *  for whatever the taught/goal lanes make of the same refusal (typically a
+ *  plainer refuse with no candidates at all). */
 export async function runCapabilityPlan(request, tools, ctx) {
   const c1 = await runResolverPlan(request, tools, ctx);
-  if (!c1.refused) return c1;
+  if (!c1.refused || c1.candidateResults) return c1;
   const taught = await runTaughtPlan(request, tools, ctx);
   if (taught) return taught.refused ? { ...taught, c1Why: c1.why } : taught;
   const c2 = await goalReason(request, tools, ctx, { driver: GOAL_DRIVER });
@@ -266,7 +287,11 @@ export async function runCapabilityPlan(request, tools, ctx) {
  *  an already-registered name is skipped) and runTaughtPlan simulates over the
  *  same store, re-reading it per request via ctx.readTaughtStore. The new
  *  registrations' unregister disposers ride the ctx as `ctx.disposers`; the
- *  caller runs them when the ctx is done. */
+ *  caller runs them when the ctx is done. The same `memoryDir` also opens
+ *  `ctx.resolveMemoryTerm` — resolveOne's binding oracle for a memoryTerm slot
+ *  (tmct_related's `term`), re-reading the store's fact rows per request
+ *  through resolveMemoryTerm (resolver.mjs), the memory-graph sibling of
+ *  `resolve` above. */
 export async function buildCapabilityPlanCtx({
   config, source, tel = null, graph = null, memoryDir = null,
   dispatchTool, isToolError = () => false, selectTool = null,
@@ -294,6 +319,7 @@ export async function buildCapabilityPlanCtx({
       const memory = await loadMemory(memoryDir);
       return { factRows: readFactRows(memory), ruleRows: readRuleRows(memory) };
     };
+    ctx.resolveMemoryTerm = async (term) => resolveMemoryTerm(readFactRows(await loadMemory(memoryDir)), term);
     ctx.disposers = registerTaughtActions(readRuleRows(await loadMemory(memoryDir)));
   }
   return ctx;

package/src/domain/router/planner.mjs

@@ -12,6 +12,13 @@ export const MAX_STEPS = 8;
 
 const PRONOUN_RE = /\b(?:it|its|them|those|these|that|their)\b/i;
 
+// The RECOVER method's check clause must itself name an EMPTY outcome (none/
+// nothing/no/not any/empty) — a closed, curated cue list, not a general "any if
+// clause is a guard" reading. This is what keeps METHOD 1b narrow: "X, and if Y,
+// Z instead" without an emptiness cue in Y falls through to plain sequencing
+// unchanged, exactly as it did before this method existed.
+const RECOVER_EMPTY_CUE_RE = /\bnone\b|\bnothing\b|\bno\b|\bnot\s+any\b|\bempty\b/i;
+
 /** HTN decomposition — turn a request into an ORDERED list of leaf sub-goals.
  *  Returns { method, segments:[{ text, role, thread }] }:
  *    - role "check"  — a conditional antecedent (a test whose call still emits)
@@ -34,6 +41,25 @@ export function decompose(request) {
     };
   }
 
+  // METHOD 1b — the RECOVER recipe: "<primary>, and if <the primary came up
+  // empty>, <fallback> [instead]". Unlike METHOD 1 (which always dispatches
+  // both sides and folds the answer), the check clause here names no separate
+  // call at all — it is read as an emptiness GUARD on the primary's own
+  // result, observed at execution rather than dispatched. Requires an
+  // emptiness cue in the check clause, so an ordinary "X, and if Y, Z instead"
+  // whose Y doesn't name an empty outcome keeps falling through to plain
+  // sequencing (METHOD 4), unchanged from before this method existed.
+  const recover = raw.match(/^(.+?),\s*(?:and\s+)?if\s+(.+?),\s*(.+?)(?:\s+instead)?$/i);
+  if (recover && RECOVER_EMPTY_CUE_RE.test(recover[2])) {
+    return {
+      method: "recover",
+      segments: [
+        { text: recover[1].trim(), role: "action", thread: false },
+        { text: recover[3].trim(), role: "action", thread: PRONOUN_RE.test(recover[3]) },
+      ],
+    };
+  }
+
   // METHOD 2 — the RELATIVE-FILTER recipe: "of the <set> <rel> X, which are <Y>".
   // Decomposes to [produce the <set> (the <rel> over X), filter it by <Y>].
   const rel = raw.match(/^of\s+the\s+(.+?),\s*which\s+(?:are\s+)?(.+?)$/i);
@@ -101,11 +127,15 @@ function rewriteCheck(text, lastEntity) {
 const refuse = (why, driver) => ({ calls: [], refused: true, terminated: true, proof: [], driver, why });
 
 /** Plan + execute a multi-step request. Returns a loopResult
- *    { calls, refused, terminated, proof, why, driver, observed }
+ *    { calls, refused, terminated, proof, why, driver, observed, recovered? }
  *  with a POP causal-link proof chain. Each step is monitored; a failed sub-goal stops the
- *  plan honestly. Bounded by MAX_STEPS.
+ *  plan honestly. Bounded by MAX_STEPS. A `recover` method OBSERVES its primary step's
+ *  own structured result before deciding the fallback: `recovered:true` marks a plan
+ *  whose fallback fired because the primary came up empty; a non-empty primary stops the
+ *  plan after just that one call (the fallback is never dispatched) and carries no
+ *  `recovered` key at all.
  *
- *  ctx: { dispatch(name,input)->{ok,text,resolved?}, resolve(term)->resolveObject } */
+ *  ctx: { dispatch(name,input)->{ok,text,resolved?,result?}, resolve(term)->resolveObject } */
 export async function plan(request, declaredNames, ctx, { driver = "resolver-0.8.0" } = {}) {
   const { method, segments } = decompose(request);
   if (segments.length > MAX_STEPS) {
@@ -117,6 +147,7 @@ export async function plan(request, declaredNames, ctx, { driver = "resolver-0.8
   const why = [`HTN method: ${method} — ${segments.length} sub-goal(s)`];
   let lastEntity = null; // the most-recent bound entity label (for anaphora threading)
   let steps = 0;
+  let recovered = false;
 
   for (let i = 0; i < segments.length; i += 1) {
     if (steps >= MAX_STEPS) return refuse("step budget exhausted mid-plan — escalate", driver);
@@ -127,7 +158,10 @@ export async function plan(request, declaredNames, ctx, { driver = "resolver-0.8
 
     const r = await resolveOne(text, declaredNames, ctx, { execute: true });
     if (r.refused) {
-      return refuse(`sub-goal ${i + 1} ("${text}") did not resolve: ${r.reason}`, driver);
+      return {
+        ...refuse(`sub-goal ${i + 1} ("${text}") did not resolve: ${r.reason}`, driver),
+        ...(r.candidateCalls ? { candidateResults: r.candidateCalls } : {}),
+      };
     }
 
     calls.push(r.selected);
@@ -140,6 +174,21 @@ export async function plan(request, declaredNames, ctx, { driver = "resolver-0.8
 
     if (r.resolved?.label) lastEntity = r.resolved.label;
     why.push(...(r.why || []).map((w) => `[${i + 1}] ${w}`));
+
+    // RECOVER's guard: OBSERVE the primary's own structured result (a fresh,
+    // read-only re-dispatch — the same idiom composeResult uses to fold a
+    // threaded plan) before deciding the fallback. A non-empty primary already
+    // answered the request, so the loop stops here — the fallback is never
+    // dispatched, closing the bug this method exists to fix (the primary used
+    // to double-emit because the guard was never actually observed). An empty
+    // primary marks the plan `recovered` and lets the fallback segment run.
+    if (method === "recover" && i === 0) {
+      const res = await ctx.dispatch(r.selected.name, r.selected.input || {});
+      const primaryEmpty = res.ok && Array.isArray(res.result) && res.result.length === 0;
+      why.push(`[guard] observed ${r.selected.name} => ${primaryEmpty ? "empty — recovering with the fallback" : "non-empty — the primary already answers this; no fallback dispatched"}`);
+      if (!primaryEmpty) break;
+      recovered = true;
+    }
   }
 
   return {
@@ -149,6 +198,7 @@ export async function plan(request, declaredNames, ctx, { driver = "resolver-0.8
     proof,
     driver,
     why,
+    ...(recovered ? { recovered: true } : {}),
     observed: `plan(${method}): ${calls.map((c) => c.name).join(" -> ")}`,
   };
 }

package/src/domain/router/resolver.mjs

@@ -16,6 +16,8 @@
 
 import { parseQuery } from "../ask.mjs";
 import { SUPERLATIVE_EXTREMES } from "../ask-vocab.mjs";
+import { buildSkosConceptView } from "../skos-view.mjs";
+import { edgesOfKind } from "../codegraph.mjs";
 import {
   capabilities, capabilityByName, preconditionsOf, effectsOf, PRECOND,
 } from "./registry.mjs";
@@ -56,10 +58,9 @@ export const UNMAPPED_KINDS = Object.freeze({
 
 // ---- capabilities the NL surface cannot reach today (named, not accidental) ---
 // A declared capability with no NL/command/frame path is a routing gap and must be tagged
-// here with the reason.
-export const NOT_NL_REACHABLE = Object.freeze({
-  tmct_related: "the SKOS synonym/related surface is served by the chat lane's own recogniser over the memory graph; a router frame for it needs memory-term binding, which resolveObject (code-graph-only) does not prove yet",
-});
+// here with the reason. Empty today: the synonym/related FRAME below reaches tmct_related
+// via resolveMemoryTerm, the memory-graph sibling of resolveObject's code-graph binding.
+export const NOT_NL_REACHABLE = Object.freeze({});
 
 // ---- imperative intent FRAMES (fills what the relational grammar and command register
 // both miss). regex -> { topic, arg | noArg }. Ordered: first match wins.
@@ -81,6 +82,12 @@ export const FRAMES = Object.freeze([
   { re: /\bmembers?\b|\bmethods?\s+of\b|\battributes?\s+of\b/i, topic: "members", arg: "class" },
   { re: /\bhistory\b|who\s+changed\b|commits?\s+(?:that\s+)?touch/i, topic: "history", arg: "symbol" },
   { re: /\bsignature\b/i, topic: "signature", arg: "symbol" },
+  // tmct_related: the SKOS synonym/related-concept surface over the memory graph
+  // — "another word for X" / "a synonym for X" / "synonyms of X" / "what's
+  // related to X". `arg: "term"` is the one memory-graph-bound slot in this
+  // table (see resolveMemoryTerm below); every other frame's arg binds against
+  // the code graph via ctx.resolve.
+  { re: /\bsynonyms?\b|\banother\s+word\s+for\b|\brelated\s+(?:words?|concepts?|to)\b/i, topic: "related", arg: "term" },
   { re: /\bdescribe\b|\bexplain\b|what\s+is\b|tell\s+me\s+about\b|definition\s+of\b/i, topic: "description", arg: "symbol" },
   { re: /\bsearch\b|\bfind\b|look\s+for\b/i, topic: "matches", arg: "query" },
 ]);
@@ -122,6 +129,7 @@ const STOP = new Set([
   "module", "modules", "class", "classes", "function", "functions", "symbol", "symbols",
   "untested", "blast", "radius", "change", "changes", "changing", "reach", "reaches", "affect", "affects",
   "explain", "edge", "edges", "graph", "outgoing", "site", "sites", "invoke", "invokes", "run", "runs", "execute", "executes",
+  "word", "words", "another", "synonym", "synonyms", "related", "relate", "relates", "like", "concept", "concepts",
 ]);
 
 /** Pull one entity token from a request (imperative-frame slot-filling). Prefer a
@@ -178,7 +186,14 @@ export function mapFrame(request) {
     if (!cap) continue;
     if (f.noArg) return { name: cap.name, noArg: true, topic: f.topic, source: "frame", why: [`imperative frame => goal (knows ${f.topic})`, `backward-chain => ${cap.name}`] };
     const term = f.arg === "query" ? searchQuery(request) : extractEntity(request);
-    return { name: cap.name, arg: f.arg, term, topic: f.topic, source: "frame", why: [`imperative frame => goal (knows ${f.topic} ?${f.arg})`, `backward-chain => ${cap.name}`] };
+    // memoryTerm: this slot binds against the memory graph's SKOS concept view
+    // (resolveMemoryTerm below), not the code graph resolveObject resolves
+    // every other frame's arg against — "term" is the one param kind this is
+    // true for (tmct_related's own memory-facts-gated param).
+    return {
+      name: cap.name, arg: f.arg, term, topic: f.topic, source: "frame", memoryTerm: f.arg === "term",
+      why: [`imperative frame => goal (knows ${f.topic} ?${f.arg})`, `backward-chain => ${cap.name}`],
+    };
   }
   return null;
 }
@@ -198,16 +213,37 @@ export function commandCapability(request, declaredNames, selectTool) {
   return { name: sel.name, input, source: "command", why: [`command register: "${String(request).trim().split(/\s+/)[0]}" => ${sel.name}`] };
 }
 
+/** Resolve a term against the memory graph's SKOS concept view
+ *  (skos-view.mjs's buildSkosConceptView) — the memory-graph sibling of
+ *  resolveObject, for a param whose precondition is memory-facts rather than
+ *  a code-graph `resolves`. Same `{ match, ambiguous }` shape resolveObject
+ *  returns, so resolveOne's generic binding step treats both the same way:
+ *  `match.label` is the RAW queried term (not the concept's canonicalised
+ *  prefLabel), because tmct_related's own lookup (relatedForTerm) re-derives
+ *  the concept from whatever term it's given — the bound call should carry
+ *  what the user actually asked about. No code-graph fallback: a term the
+ *  store holds no synonym/related facts for is an honest miss, never a guess.
+ *  `rows` is a loadMemory+readFactRows payload — the same trust-bearing rows
+ *  skosRelatedAnswer (chat.mjs) and tmct_related (the tool handler) read. */
+export function resolveMemoryTerm(rows, term) {
+  const t = String(term || "").trim();
+  if (!t) return { match: null };
+  const view = buildSkosConceptView(rows);
+  if (!view.conceptIdForTerm(t)) return { match: null };
+  return { match: { label: t, class: "skos:Concept" }, ambiguous: false, tier: "memory-concept" };
+}
+
 // ---- the full single-call resolver (async — binds + grounds) -----------------
 
 /** Build the glass-box proof chain for a grounded single call: its preconditions then the
- *  epistemic add-effect. Dispatch has succeeded, so `resolves` steps are ok. */
+ *  epistemic add-effect. Dispatch has succeeded, so `resolves`/`memoryFacts` steps are ok. */
 function proofFor(name, input) {
   const steps = [];
   for (const pre of preconditionsOf(name)) {
     if (pre.pred === PRECOND.graphLoaded) steps.push({ step: "precondition", pred: pre.pred, ok: true });
     else if (pre.pred === PRECOND.resolves) steps.push({ step: "precondition", pred: pre.pred, param: pre.param, value: input[pre.param] ?? null, ok: true });
     else if (pre.pred === PRECOND.anyPresent) steps.push({ step: "precondition", pred: pre.pred, params: pre.params, ok: pre.params.some((k) => input[k]) });
+    else if (pre.pred === PRECOND.memoryFacts) steps.push({ step: "precondition", pred: pre.pred, ok: true });
   }
   for (const eff of effectsOf(name).add) steps.push({ step: "effect", pred: eff.pred, topic: eff.topic, of: eff.of });
   return steps;
@@ -238,11 +274,29 @@ async function dispatchEachCandidate(pool, capName, arg, ctx, execute) {
   return results;
 }
 
+/** A tie the raw tier-3 SCORE never flags: a bare basename that binds to a source
+ *  module also names its own test module, because the graph's own `tests` edge
+ *  connects the two directly (not a filename guess — a real edge dispatchTool
+ *  already reads). resolveObject's scoring ranks the source module far ahead on
+ *  string similarity ("b" is an exact stem match; "b.test" is not), so this is
+ *  never `ambiguous:true` on its own, yet "b" genuinely names either reading. Two
+ *  individuals with no such edge are near-miss neighbours, not a genuine tie. */
+function testModuleTie(graph, matchInd, candidateInd) {
+  if (!graph || !matchInd || !candidateInd) return false;
+  return edgesOfKind(graph, "tests").some((e) =>
+    (e.subject === matchInd.id && e.object === candidateInd.id)
+    || (e.subject === candidateInd.id && e.object === matchInd.id));
+}
+
 /** Select a capability for a request and BIND its arguments — the full resolver.
  *  Order: command register -> NL parse -> imperative frame. Delegates entity binding to
  *  ctx.resolve and, unless `execute:false`, grounds it via ctx.dispatch. Returns
  *    { selected:{name,input}, proof, why, resolved, observed? }  — a grounded call
- *    { selected:null, refused:true, reason, candidateResults? }  — an honest refusal
+ *    { selected:null, refused:true, reason, candidateResults?, candidateCalls? } — an
+ *      honest refusal. candidateResults carries the FULL dispatched {candidate,result}
+ *      pair per tied reading; candidateCalls is its {name,input} call-only twin, the
+ *      shape a caller composes into a loopResult's own top-level `candidateResults`
+ *      (the tied-candidate composer's enumerate-or-refuse answer).
  *  Never emits an ungrounded / ambiguous / undeclared call. */
 export async function resolveOne(request, declaredNames, ctx, { execute = true } = {}) {
   const declared = new Set(declaredNames);
@@ -272,22 +326,42 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
   if (!declared.has(pick.name)) return REFUSE(`selected ${pick.name} but it is not in the declared toolset`);
 
   // A command pick already carries a bound input; an NL/frame pick carries a raw term
-  // we bind via resolveObject.
+  // we bind via resolveObject (code graph) or, for a memoryTerm slot, resolveMemoryTerm
+  // (the memory graph's SKOS concept view) — the two binding oracles never mix on one pick.
   let input = pick.input ? { ...pick.input } : {};
   let resolved = null;
   if (!pick.input && !pick.noArg) {
     const term = String(pick.term || "").trim();
     if (!term) return REFUSE(`the ${pick.topic} intent named no entity to bind`);
-    const r = ctx.resolve ? ctx.resolve(term) : { match: { label: term }, ambiguous: false };
-    if (!r || !r.match) return REFUSE(`"${term}" does not resolve to any graph entity (honest miss)`);
-    if (r.ambiguous) {
-      const pool = [r.match, ...(r.candidates || [])].slice(0, 4);
+    const r = pick.memoryTerm
+      ? (ctx.resolveMemoryTerm ? await ctx.resolveMemoryTerm(term) : { match: null })
+      : (ctx.resolve ? ctx.resolve(term) : { match: { label: term }, ambiguous: false });
+    if (!r || !r.match) {
+      return REFUSE(pick.memoryTerm
+        ? `"${term}" has no synonym/related facts in the memory graph (honest miss)`
+        : `"${term}" does not resolve to any graph entity (honest miss)`);
+    }
+    // A tied read: either resolveObject's own score-tie (r.ambiguous), or a same-tier
+    // candidate the graph's own `tests` edge ties to the match (a source module and
+    // its test module — a grain neither side's raw score alone reveals as tied).
+    // resolveMemoryTerm's SKOS concept view has no code-graph tests-edge notion, so the
+    // sibling tie-check only applies on the code-graph resolution path.
+    const sibling = (!pick.memoryTerm && !r.ambiguous)
+      ? (r.candidates || []).find((c) => testModuleTie(ctx.graph, r.match, c))
+      : null;
+    if (r.ambiguous || sibling) {
+      const pool = r.ambiguous ? [r.match, ...(r.candidates || [])].slice(0, 4) : [r.match, sibling];
       const candidateResults = await dispatchEachCandidate(pool, pick.name, pick.arg, ctx, execute);
-      return REFUSE(`"${term}" is ambiguous (${pool.map((m) => m.label).join(", ")}) — narrow it`, candidateResults ? { candidateResults } : undefined);
+      const extra = candidateResults
+        ? { candidateResults, candidateCalls: pool.map((c) => ({ name: pick.name, input: { [pick.arg]: c.label } })) }
+        : undefined;
+      return REFUSE(`"${term}" is ambiguous (${pool.map((m) => m.label).join(", ")}) — narrow it`, extra);
     }
     resolved = r.match;
     input = { [pick.arg]: r.match.label };
-    why = [...why, `resolveObject: "${term}" => ${r.match.label} (${r.match.class || "?"}, tier ${r.tier})`];
+    why = [...why, pick.memoryTerm
+      ? `resolveMemoryTerm: "${term}" mints a memory-graph SKOS concept (tier ${r.tier})`
+      : `resolveObject: "${term}" => ${r.match.label} (${r.match.class || "?"}, tier ${r.tier})`];
   }
 
   const call = { name: pick.name, input };

package/src/domain/sprite-map.mjs

@@ -0,0 +1,131 @@
+// sprite-map.mjs — the ontology-to-sprite mapping (PLAN_SPIDER_FLY.md §7): a
+// flat registry of small, original inline-SVG icons keyed on class name, and
+// the ancestor-walk resolver that maps ANY class down to whichever registered
+// ancestor is nearest — so a taxonomy can teach `poodle IsA dog` and
+// `sheepdog IsA dog` once, register a sprite only for `poodle` and `dog`, and
+// have `sheepdog` fall back to the generic dog sprite automatically.
+//
+// resolveSpriteForClass is styled after src/domain/ask.mjs's private
+// ancestorsOf (BFS, nearest-ancestor-first, a flat queue with `shift()`) but
+// walks generic rdfs:subClassOf fact-store edges (subject IsA object) rather
+// than ask.mjs's code-graph `inherits` edges — the two data shapes are
+// different graphs, so the walk is re-derived here rather than imported.
+//
+// SPRITE_REGISTRY follows the flat closed-vocabulary registry idiom this
+// project already uses elsewhere (SOURCE_PRIOR in domain/memory/trust.mjs,
+// EDGE_KIND_TO_TMCT in adapters/repository-interface.mjs): an
+// Object.freeze({...}) string-to-value map with a doc comment, keyed on the
+// same normFactTerm-normalized spelling the fact store already uses, so a
+// lookup never has to re-normalise its own keys before comparing.
+//
+// normFactTerm is imported from domain/hash.mjs directly, not
+// adapters/memory/core.mjs's re-export of it — this module lives in
+// src/domain/, and domain stays pure of src/adapters/ (test/estate/
+// import-layers.test.mjs enforces the direction).
+
+import { normFactTerm } from "./hash.mjs";
+
+const SUBJECT_TO_SUPERCLASS_PREDICATE = "rdfs:subClassOf";
+
+// Every value is a complete, self-contained <svg> string using
+// `fill="currentColor"`/`stroke="currentColor"` so the renderer colors an
+// icon with plain CSS (the spider's green accent, the fly's amber one — §9)
+// rather than baking a color into the markup. Small, geometric, hand-drawn
+// shapes only — no external asset files, no licence to track (§8's whole
+// point of dropping RPG-JS in favor of this).
+const SPIDER_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="10" r="3.4" fill="currentColor"/>'
+  + '<circle cx="12" cy="15.6" r="4.6" fill="currentColor"/>'
+  + '<g stroke="currentColor" stroke-width="1.1" fill="none" stroke-linecap="round">'
+  + '<path d="M9 8 L2 4"/><path d="M9 10 L1.5 9"/><path d="M9 12.5 L2 14"/><path d="M9 15.5 L3 19"/>'
+  + '<path d="M15 8 L22 4"/><path d="M15 10 L22.5 9"/><path d="M15 12.5 L22 14"/><path d="M15 15.5 L21 19"/>'
+  + "</g></svg>";
+
+const FLY_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="13.2" rx="3.2" ry="5" fill="currentColor"/>'
+  + '<circle cx="12" cy="7" r="2.6" fill="currentColor"/>'
+  + '<g fill="currentColor" opacity="0.55">'
+  + '<path d="M9 10 C3 6 2 4 3 2 C6 2 9 6 10.5 10 Z"/>'
+  + '<path d="M15 10 C21 6 22 4 21 2 C18 2 15 6 13.5 10 Z"/>'
+  + "</g></svg>";
+
+const EGG_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 2 C7 2 4 10 4 15.5 C4 20 7.6 22 12 22 '
+  + 'C16.4 22 20 20 20 15.5 C20 10 17 2 12 2 Z" fill="currentColor"/></svg>';
+
+const POODLE_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="13" cy="15" rx="6.4" ry="4.6" fill="currentColor"/>'
+  + '<circle cx="7" cy="8.5" r="4" fill="currentColor"/>'
+  + '<g fill="currentColor"><circle cx="4" cy="6" r="1.6"/><circle cx="7" cy="4.2" r="1.7"/><circle cx="10" cy="6" r="1.6"/></g>'
+  + '<rect x="18.5" y="14" width="2.2" height="6" rx="1.1" fill="currentColor"/>'
+  + '<circle cx="19.6" cy="13" r="1.5" fill="currentColor"/>'
+  + '<g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="9" y1="19.5" x2="9" y2="22"/><line x1="17" y1="19.5" x2="17" y2="22"/></g>'
+  + "</svg>";
+
+const DOG_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="13" cy="15" rx="6.4" ry="4.2" fill="currentColor"/>'
+  + '<circle cx="7" cy="9" r="3.6" fill="currentColor"/>'
+  + '<path d="M4.5 6.5 L2 3 L6 5 Z" fill="currentColor"/>'
+  + '<path d="M19 13 C22 12 22.5 15 20 16 Z" fill="currentColor"/>'
+  + '<g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="9" y1="19" x2="9" y2="22"/><line x1="17" y1="19" x2="17" y2="22"/></g>'
+  + "</svg>";
+
+// The generic fallback — deliberately the plainest shape in the set (an
+// unadorned four-legged blob) so it reads as "some animal" rather than
+// suggesting a species the taxonomy never named.
+const ANIMAL_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><ellipse cx="12" cy="13" rx="7" ry="4.4" fill="currentColor"/>'
+  + '<circle cx="12" cy="7" r="3.4" fill="currentColor"/>'
+  + '<g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="7" y1="17" x2="7" y2="21"/><line x1="17" y1="17" x2="17" y2="21"/></g>'
+  + "</svg>";
+
+/** The sprite registry: class name (normFactTerm-normalized) -> inline SVG
+ *  markup. `animal` is this world's declared root fallback (PLAN_SPIDER_FLY.md
+ *  §7 names "animal"/"object"/"plant" as the family of possible roots — a
+ *  spider-and-fly board only ever needs "animal") — resolveSpriteForClass
+ *  falls back to it once the ancestor walk exhausts with no closer hit. */
+export const SPRITE_REGISTRY = Object.freeze({
+  spider: SPIDER_SVG,
+  fly: FLY_SVG,
+  egg: EGG_SVG,
+  poodle: POODLE_SVG,
+  dog: DOG_SVG,
+  animal: ANIMAL_SVG,
+});
+
+/** Every direct rdfs:subClassOf superclass of `term`, from a flat fact-row
+ *  array (`{ subject, predicate, object }`, generic — the same shape both
+ *  the fact store and a plain taxonomy fixture already use). */
+function directSuperclassesOf(term, factRows) {
+  const out = [];
+  for (const row of factRows || []) {
+    if (row?.predicate !== SUBJECT_TO_SUPERCLASS_PREDICATE) continue;
+    if (normFactTerm(row.subject) !== term) continue;
+    out.push(normFactTerm(row.object));
+  }
+  return out;
+}
+
+/**
+ * Resolve a class name to a sprite: `className` itself if the registry
+ * carries it directly, otherwise the nearest rdfs:subClassOf ancestor
+ * (breadth-first, nearest first — styled after ask.mjs's own ancestorsOf)
+ * that the registry carries, otherwise `rootFallback` ("animal" by default —
+ * override it for a registry whose own declared root is "object" or "plant").
+ * Pure; `factRows` is read only, never mutated.
+ */
+export function resolveSpriteForClass(className, factRows, spriteRegistry, { rootFallback = "animal" } = {}) {
+  const start = normFactTerm(className);
+  const seen = new Set();
+  const queue = [start];
+  while (queue.length) {
+    const term = queue.shift();
+    if (seen.has(term)) continue;
+    seen.add(term);
+    if (Object.prototype.hasOwnProperty.call(spriteRegistry, term)) return spriteRegistry[term];
+    for (const parent of directSuperclassesOf(term, factRows)) {
+      if (!seen.has(parent)) queue.push(parent);
+    }
+  }
+  return spriteRegistry[rootFallback];
+}

package/src/services/adventure.mjs

@@ -799,6 +799,13 @@ export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "
         note: "ADVENTURE — an opening arrived mid-number-game; the slot holds one thing at a time",
       };
     }
+    if (slot?.spiderFly) {
+      return {
+        text: 'the spider-and-fly game is running — say "stop watching" to end it, then start the adventure.',
+        lane: "game-inform",
+        note: "ADVENTURE — an opening arrived mid-spider-fly-game; the slot holds one thing at a time",
+      };
+    }
     const planActive = slot && !slot.done
       && ((Array.isArray(slot.goals) && slot.goals.length) || (Array.isArray(slot.actions) && slot.actions.length));
     if (planActive) {

package/src/services/chat.mjs

@@ -53,6 +53,7 @@ import { getChildPackProvider } from "../adapters/corpus/child-pack.mjs";
 import { dialogueActForLane } from "../domain/dialogue-acts.mjs";
 import { relatedForTerm } from "../domain/skos-view.mjs";
 import { adventureTurn } from "./adventure.mjs";
+import { spiderFlyTurn } from "./spider-fly-turn.mjs";
 
 // Composition: the chat surface supplies the domain parser's default lemma/POS
 // adapter (the browser bundle's ask-nlp stub carries no factory, so this is a
@@ -12246,6 +12247,9 @@ function guessNumberTurn(line, { planHolder, env }) {
   if (state?.adventure) {
     return { text: 'we\'re mid-adventure — say "stop playing" to end it before a number game.', lane: "game-inform", note: "GAME — an opening arrived mid-adventure; the slot holds one thing at a time" };
   }
+  if (state?.spiderFly) {
+    return { text: 'the spider-and-fly game is running — say "stop watching" to end it before a number game.', lane: "game-inform", note: "GAME — an opening arrived mid-spider-fly-game; the slot holds one thing at a time" };
+  }
   const planActive = state && !state.done
     && ((Array.isArray(state.goals) && state.goals.length) || (Array.isArray(state.actions) && state.actions.length));
   if (planActive) {
@@ -12621,6 +12625,27 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     }
   }
 
+  // SPIDER-AND-FLY — the opener ("watch the spider and the fly"), the stop
+  // command, the addressed spatial teach-frame, the bare tick command, and
+  // (once a game is live) the game's own turns. Ordered AFTER the adventure
+  // lane for the same reason the adventure lane follows guess-the-number: an
+  // opening line would otherwise read as a declarative or an orientation ask.
+  {
+    const sfTurn = await spiderFlyTurn(workingLine, {
+      planHolder, memoryDir, env, cache: factRowsCache, isPlanFrameLine,
+    });
+    if (sfTurn) {
+      note(trace, `lane: ${sfTurn.note}`);
+      if (sfTurn.goal) note(trace, `goal: ${sfTurn.goal}`);
+      const result = plainTurn(workingLine, sfTurn.text, { via: "game", miss: !!sfTurn.miss, focus });
+      if (sfTurn.goal) result.goal = sfTurn.goal;
+      result.lane = sfTurn.lane;
+      const rec = withLast(result, sfTurn.goal ?? "watch the spider-and-fly game");
+      rec.planState = planHolder.state;
+      return rec;
+    }
+  }
+
   // Conversational layer next (greetings, thanks, help, bye, why/say-more) — these
   // resolve no entity and carry their own preserved `last`. Bypasses withLast (a
   // conversational turn is never finish()'d / never becomes a new `last`), so the