@polycode-projects/the-mechanical-code-talker 4.0.1 → 4.1.1

package/src/domain/router/resolver.mjs

@@ -11,15 +11,20 @@
 // grammar doesn't carry, and a rescue path when the NL parse selects an out-of-set
 // capability).
 //
-// Entity binding is delegated to `resolveObject` (ask.mjs); an ambiguous or no-match term
-// is an honest refuse, never a guess.
+// Entity binding is delegated to `resolveObject` (ask.mjs) for code-graph slots, and to
+// `resolveMemoryTerm` (below) for a slot whose registry kind is KINDS.MemoryTerm — the
+// conversational-memory graph's own binding oracle. An ambiguous or no-match term is an
+// honest refuse, never a guess, on both paths.
 
 import { parseQuery } from "../ask.mjs";
 import { SUPERLATIVE_EXTREMES } from "../ask-vocab.mjs";
 import { buildSkosConceptView } from "../skos-view.mjs";
+import { normFactTerm } from "../hash.mjs";
 import { edgesOfKind } from "../codegraph.mjs";
+import { EXPRESSION_PALETTE } from "../sprite-expressions.mjs";
+import { sizeScaleFor } from "../sprite-size.mjs";
 import {
-  capabilities, capabilityByName, preconditionsOf, effectsOf, PRECOND,
+  capabilities, capabilityByName, parametersOf, preconditionsOf, effectsOf, PRECOND, KINDS, MEMORY_KINDS,
 } from "./registry.mjs";
 import { hallucinationsIn } from "./call-validator.mjs";
 
@@ -64,6 +69,25 @@ export const UNMAPPED_KINDS = Object.freeze({
 // via resolveMemoryTerm, the memory-graph sibling of resolveObject's code-graph binding.
 export const NOT_NL_REACHABLE = Object.freeze({});
 
+/** The property predicate sprite-size.mjs reads a size word off. Used to PROBE
+ *  its own closed scale table instead of restating it here: a word is a size
+ *  word exactly when it moves the scale away from 1. */
+const SIZE_FACT_PREDICATE = "mgx:hasProperty";
+
+/** The sprite frame's two OPTIONAL slots, read straight out of the request.
+ *  Both vocabularies are the real ones — sprite-expressions.mjs's own palette
+ *  and sprite-size.mjs's own scale table (probed, not copied) — so a word
+ *  either module gains is a word this frame gains. A request naming neither
+ *  fills neither, and the sprite resolves plain. */
+function spriteSlots(request) {
+  const slots = {};
+  for (const word of String(request).toLowerCase().match(/[a-z]+/g) || []) {
+    if (!slots.expression && Object.hasOwn(EXPRESSION_PALETTE, word)) slots.expression = word;
+    if (!slots.size && sizeScaleFor([{ predicate: SIZE_FACT_PREDICATE, object: word }]) !== 1) slots.size = word;
+  }
+  return slots;
+}
+
 // ---- imperative intent FRAMES (fills what the relational grammar and command register
 // both miss). regex -> { topic, arg | noArg }. Ordered: first match wins.
 export const FRAMES = Object.freeze([
@@ -86,10 +110,19 @@ export const FRAMES = Object.freeze([
   { 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.
+  // related to X". Its `term` slot is declared KINDS.MemoryTerm in the registry,
+  // so resolveOne binds it through resolveMemoryTerm (below) rather than the
+  // code graph's resolveObject — the registry kind, not this table, decides.
   { re: /\bsynonyms?\b|\banother\s+word\s+for\b|\brelated\s+(?:words?|concepts?|to)\b/i, topic: "related", arg: "term" },
+  // tmct_sprite: the sprite surface over the memory graph's own world facts —
+  // "the large sprite for a happy spider", "what does a hungry fly look like",
+  // "show me the spider icon". Its `class` slot is the second KINDS.MemoryTerm
+  // one, so it binds the same way tmct_related's `term` does. `slots` is what
+  // makes this frame different: it fills the two OPTIONAL args itself.
+  {
+    re: /\bsprite\b|\bicon\b|\bavatar\b|\bpicture\s+of\b|\bwhat\s+does\s+.+\s+look\s+like\b/i,
+    topic: "sprite", arg: "class", slots: spriteSlots,
+  },
   { 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" },
 ]);
@@ -132,13 +165,17 @@ const STOP = new Set([
   "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",
+  "sprite", "sprites", "icon", "icons", "avatar", "avatars", "picture", "pictures", "image", "images", "looks",
 ]);
 
 /** Pull one entity token from a request (imperative-frame slot-filling). Prefer a
- *  path/dotted/CamelCase token, else the last non-stopword identifier. "" if none. */
-export function extractEntity(request) {
+ *  path/dotted/CamelCase token, else the last non-stopword identifier. "" if none.
+ *  `alreadyBound` holds the words a frame's own slot-filler has already claimed
+ *  (the sprite frame's expression/size), so they can't also be read as the entity. */
+export function extractEntity(request, alreadyBound = null) {
   const tokens = String(request).match(/[A-Za-z_][A-Za-z0-9_./-]*/g) || [];
-  const pool = tokens.filter((t) => !STOP.has(t.toLowerCase()));
+  const claimed = alreadyBound || new Set();
+  const pool = tokens.filter((t) => !STOP.has(t.toLowerCase()) && !claimed.has(t.toLowerCase()));
   const strong = pool.filter((t) => /[./]/.test(t) || /^[A-Z][a-z]/.test(t) || /\.[a-z]+$/.test(t));
   const pick = strong.length ? strong : pool;
   return pick.length ? pick[pick.length - 1] : "";
@@ -187,13 +224,14 @@ export function mapFrame(request) {
     const cap = backwardChain(f.topic);
     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);
-    // 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).
+    // A frame's own OPTIONAL slots, filled from the request's vocabulary before
+    // the entity is read, so a word a slot claimed can't also be read as the entity.
+    const slots = f.slots ? f.slots(request) : null;
+    const term = f.arg === "query"
+      ? searchQuery(request)
+      : extractEntity(request, slots ? new Set(Object.values(slots)) : null);
     return {
-      name: cap.name, arg: f.arg, term, topic: f.topic, source: "frame", memoryTerm: f.arg === "term",
+      name: cap.name, arg: f.arg, term, topic: f.topic, source: "frame", slots,
       why: [`imperative frame => goal (knows ${f.topic} ?${f.arg})`, `backward-chain => ${cap.name}`],
     };
   }
@@ -215,24 +253,41 @@ 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. */
+/** Resolve a term against the conversational-memory graph — the memory-graph
+ *  sibling of resolveObject, for a slot whose registry kind is KINDS.MemoryTerm.
+ *  Two tiers, tried in order, both EXACT after normFactTerm (no fuzzy tier — a
+ *  near-miss is a miss, never a guess):
+ *    1. "memory-concept" — the SKOS concept view (skos-view.mjs) mints a
+ *       concept for the term, i.e. the store holds synonym/related facts for it;
+ *    2. "memory-fact-term" — the term appears as the subject or object of any
+ *       stored fact row (a world-fact term: a room, a game agent, a taught
+ *       individual).
+ *  Same `{ match, ambiguous }` shape resolveObject returns, so resolveOne's
+ *  generic binding step treats both oracles the same way: `match.label` is the
+ *  RAW queried term (not a canonicalised prefLabel), because a memory tool's
+ *  own lookup (e.g. relatedForTerm) re-derives its rows 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 facts for at all is an honest
+ *  miss. `rows` is a loadMemory+readFactRows payload — the same trust-bearing
+ *  rows skosRelatedAnswer (chat.mjs) and the memory tool handlers 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" };
+  if (view.conceptIdForTerm(t)) return { match: { label: t, class: "skos:Concept" }, ambiguous: false, tier: "memory-concept" };
+  const n = normFactTerm(t);
+  if (n && rows.some((r) => normFactTerm(r.subject) === n || normFactTerm(r.object) === n)) {
+    return { match: { label: t, class: KINDS.MemoryTerm }, ambiguous: false, tier: "memory-fact-term" };
+  }
+  return { match: null };
+}
+
+/** True when capability `capName`'s slot with arg key `arg` is declared a
+ *  memory-graph kind (KINDS.MemoryTerm) — the registry-driven switch between
+ *  the two binding oracles: resolveMemoryTerm for memory slots, the code
+ *  graph's resolveObject for everything else. */
+export function isMemoryTermSlot(capName, arg) {
+  return parametersOf(capName).some((p) => p.arg === arg && MEMORY_KINDS.includes(p.kind));
 }
 
 // ---- the full single-call resolver (async — binds + grounds) -----------------
@@ -328,27 +383,29 @@ 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 (code graph) or, for a memoryTerm slot, resolveMemoryTerm
-  // (the memory graph's SKOS concept view) — the two binding oracles never mix on one pick.
+  // we bind via resolveObject (code graph) or, for a KINDS.MemoryTerm slot (the
+  // registry's own declaration, read through isMemoryTermSlot), resolveMemoryTerm —
+  // 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 = pick.memoryTerm
+    const memoryBound = isMemoryTermSlot(pick.name, pick.arg);
+    const r = memoryBound
       ? (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)`
+      return REFUSE(memoryBound
+        ? `the memory graph holds no facts mentioning "${term}" (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)
+    // resolveMemoryTerm's exact-match tiers have no code-graph tests-edge notion, so
+    // the sibling tie-check only applies on the code-graph resolution path.
+    const sibling = (!memoryBound && !r.ambiguous)
       ? (r.candidates || []).find((c) => testModuleTie(ctx.graph, r.match, c))
       : null;
     if (r.ambiguous || sibling) {
@@ -360,10 +417,15 @@ export async function resolveOne(request, declaredNames, ctx, { execute = true }
       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, pick.memoryTerm
-      ? `resolveMemoryTerm: "${term}" mints a memory-graph SKOS concept (tier ${r.tier})`
+    // The frame's own optional slots ride alongside the bound entity — declared
+    // params of the same capability, so hallucinationsIn still validates them.
+    input = { [pick.arg]: r.match.label, ...(pick.slots || {}) };
+    why = [...why, memoryBound
+      ? `resolveMemoryTerm: "${term}" binds in the memory graph (${r.match.class || "?"}, tier ${r.tier})`
       : `resolveObject: "${term}" => ${r.match.label} (${r.match.class || "?"}, tier ${r.tier})`];
+    if (pick.slots && Object.keys(pick.slots).length) {
+      why = [...why, `frame slots bound from the request's own vocabulary: ${Object.entries(pick.slots).map(([k, v]) => `${k}=${v}`).join(", ")}`];
+    }
   }
 
   const call = { name: pick.name, input };

package/src/domain/scene-compose.mjs

@@ -0,0 +1,117 @@
+// scene-compose.mjs — the sprite catalog's "there is a…" box: which real
+// catalog classes a free-typed sentence names, and with which of that class's
+// own material labels.
+//
+// Naming a class is the engine's own job. This module segments the sentence
+// into candidate spans and hands each one to ask.mjs's resolveObject — the same
+// resolver the chat lanes use — over a graph whose individuals are the caller's
+// real classes. So the caller owns where a name might start and stop, and
+// nothing else: casing, leading articles and grain words come from the
+// resolver's own tiers, and a span carrying a word the index has no reading for
+// declines there rather than resolving past it.
+//
+// It lives in domain/ rather than beside the page that draws the scene because
+// the page's browser bundle needs it: routing through the real resolver means
+// the parser can't be spliced into the page as self-contained text any more.
+
+import { resolveObject } from "./ask.mjs";
+import { parseEntities } from "./codegraph.mjs";
+
+/** `text`'s lowercase word runs, the unit class names are matched against —
+ *  punctuation never fuses two real words into one token nor splits one real
+ *  word into two. */
+export function tokenizeSceneText(text) {
+  const tokens = [];
+  const re = /[A-Za-z]+/g;
+  let m;
+  while ((m = re.exec(String(text ?? "")))) tokens.push({ word: m[0].toLowerCase() });
+  return tokens;
+}
+
+const sceneClassGraphCache = new WeakMap();
+
+/** The `classIndex`'s own class names as a resolvable graph, one individual per
+ *  class, plus the longest class name's word count (the widest span worth
+ *  offering the resolver). Cached per index object: a page builds its index once
+ *  at load and then composes on every keystroke. */
+function sceneClassGraph(classIndex) {
+  const cached = sceneClassGraphCache.get(classIndex);
+  if (cached) return cached;
+  const names = Object.keys(classIndex).filter((name) => String(name).trim());
+  const built = {
+    graph: parseEntities({
+      individuals: names.map((name) => ({ id: `sprite-class:${name}`, label: name, class: "Class" })),
+      objectProperties: [],
+    }),
+    longestClassWordCount: names.reduce((max, name) => Math.max(max, name.trim().split(/\s+/).length), 0),
+  };
+  sceneClassGraphCache.set(classIndex, built);
+  return built;
+}
+
+/** The one resolver tier the composer draws on. Composing paints a picture, and
+ *  painting the wrong sprite is a silent lie the visitor can't audit, so only an
+ *  exact-grade resolution (resolveObject's tier 1, which its own leading-article
+ *  and grain-word retries reach too) earns a swatch. The containment and fuzzy
+ *  tiers below it read "wood" as the food class and "glass" as grass — right for
+ *  a question the engine answers in words and cites, wrong for a picture drawn
+ *  without comment. */
+const SCENE_EXACT_TIER = 1;
+
+/** The catalog class named by the longest still-unclaimed token span starting at
+ *  `start`, as `{className, wordCount}`, or null when the resolver grounds none
+ *  of them. Spans are offered widest-first, so a multi-word class name ("body of
+ *  water") always wins the position it starts at over a shorter class that would
+ *  otherwise fragment it. An ambiguous resolution is a miss: a span that reads as
+ *  several real classes names none of them. */
+function resolveSpanToClass(graph, classIndex, tokens, used, start, longestClassWordCount) {
+  const widest = Math.min(longestClassWordCount, tokens.length - start);
+  for (let wordCount = widest; wordCount >= 1; wordCount -= 1) {
+    let free = true;
+    for (let k = 0; k < wordCount && free; k += 1) free = !used[start + k];
+    if (!free) continue;
+    const span = tokens.slice(start, start + wordCount).map((t) => t.word).join(" ");
+    const resolved = resolveObject(graph, span);
+    const label = resolved?.match?.label;
+    if (!label || resolved.ambiguous || resolved.tier !== SCENE_EXACT_TIER) continue;
+    if (Object.prototype.hasOwnProperty.call(classIndex, label)) return { className: label, wordCount };
+  }
+  return null;
+}
+
+/** Every real catalog class the free-typed `text` names, in the order each first
+ *  appears, paired with the real material label (one of that SAME class's own
+ *  swatch labels — never another class's, never a fabricated one) immediately
+ *  preceding it, or `null`. `classIndex` is `{className: {materials}}` with
+ *  `materials` keyed by lowercase label (sprites.html's own client-side
+ *  `buildClassIndexFromDom` output, or an equivalent test fixture) — a class name
+ *  absent from `classIndex` can never match, and a modifier word that isn't one
+ *  of ITS matched class's own material labels is silently dropped rather than
+ *  guessed at, the same honest-miss posture an unrecognized class name gets (an
+ *  unmatched word, e.g. "red" before a lamp with no red material, is never an
+ *  error, just silently not drawn). Pure. */
+export function extractSceneItems(text, classIndex) {
+  const index = classIndex || {};
+  const { graph, longestClassWordCount } = sceneClassGraph(index);
+  if (!longestClassWordCount) return [];
+  const tokens = tokenizeSceneText(text);
+  const used = new Array(tokens.length).fill(false);
+  const items = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    if (used[i]) continue;
+    const hit = resolveSpanToClass(graph, index, tokens, used, i, longestClassWordCount);
+    if (!hit) continue;
+    let materialLabel = null;
+    if (i > 0 && !used[i - 1]) {
+      const materials = index[hit.className]?.materials || {};
+      const prevWord = tokens[i - 1].word;
+      if (Object.prototype.hasOwnProperty.call(materials, prevWord)) {
+        materialLabel = prevWord;
+        used[i - 1] = true;
+      }
+    }
+    for (let k = 0; k < hit.wordCount; k += 1) used[i + k] = true;
+    items.push({ className: hit.className, materialLabel });
+  }
+  return items;
+}

package/src/domain/spider-fly-world.mjs

@@ -207,6 +207,42 @@ export function worldMetaRow() {
   return { world: WORLD_NAME, kind: "meta", opening: WORLD_OPENING };
 }
 
+/** The class an agent id names — "spider-2" -> "spider", "fly-10" -> "fly",
+ *  "egg-1" -> "egg" — the one regex every caller that needs an individual's
+ *  kind from its id string shares. Self-contained (no outer refs),
+ *  `.toString()`-splice safe. */
+export function agentKindOf(id) {
+  return String(id).replace(/-\d+$/, "");
+}
+
+/** Every live id of `kind` among `agents`, sorted. `agents` is either a
+ *  plain `{ id: ... }` roster (runSpiderFlyTick's/foldSpiderFlyState's own
+ *  agents map, already excluding anything dead) or a `Map` keyed by id
+ *  (foldSpiderFlyState's own `state.placements`, which still carries a dead
+ *  individual's last-known cell) — pass the matching `state.removed` Set as
+ *  `removed` in the Map case to exclude those; omit it for a plain roster
+ *  that has no such concept. Pure. */
+export function liveIdsOfKind(agents, kind, removed = null) {
+  const re = new RegExp(`^${kind}-\\d+$`);
+  const ids = agents instanceof Map ? [...agents.keys()] : Object.keys(agents || {});
+  return ids.filter((id) => re.test(id) && !(removed && removed.has(id))).sort();
+}
+
+/** True for a web individual's own id ("web-3") — a spider-built web is
+ *  placed via mgx:currently-in exactly like a live agent, but it is never
+ *  one. */
+export function isWebIndividualId(id) {
+  return /^web-\d+$/.test(id);
+}
+
+/** Whether `id` belongs on a rendered agent roster built from `state`
+ *  (foldSpiderFlyState's own shape): live (not in `state.removed`) and not a
+ *  web individual. The one world rule a browser-side snapshot needs to skip
+ *  the same two things every renderer of `state.placements` must skip. */
+export function isLiveRenderableAgent(id, state) {
+  return !state.removed.has(id) && !isWebIndividualId(id);
+}
+
 /** A minimal, inert rule-row family, so scripts/build-worlds-pack.mjs's
  *  shared validator ("every world needs at least one rule row") passes.
  *  src/services/spider-fly.mjs never reads these back: grid movement is

package/src/domain/sprite-request.mjs

@@ -0,0 +1,156 @@
+// sprite-request.mjs — one sprite request ("the large sprite for a happy
+// spider") resolved to markup PLUS the chain that found it. This is the pure
+// core the tmct_sprite tool handler wraps and the spider-and-fly page splices,
+// so the page and the tool answer the same question with the same code instead
+// of two hand-kept call sites drifting apart.
+//
+// Every collaborator is INJECTED rather than imported — sprite-templates.mjs's
+// resolveSpriteAsset, sprite-map.mjs's classAncestorChain, sprite-size.mjs's
+// sizeScaleFor, sprite-expressions.mjs's EXPRESSION_PALETTE. Same reason
+// spider-fly-viz.mjs's threadCellsForSpiderPlan takes its grid geometry as an
+// argument: a function with no module-scope references survives `.toString()`
+// splicing into a page script, and the browser already holds its own copies of
+// those primitives on window.tmct.
+//
+// The resolution CHAIN is derived by OBSERVATION, never by re-implementing
+// sprite-templates.mjs's specificity order. At each term of the ancestor chain
+// the same resolver is asked to resolve that ONE term against an empty
+// registry, so "did this level match" is answered by the real resolver rather
+// than by a copy of its rules that can drift out of step with it. Whether a
+// requested expression was actually honoured is observed the same way: resolve
+// once with the mgx:feels fact and once without, and compare.
+//
+// The two optional slots carry two different senses:
+//   - `expression` becomes an `mgx:feels` fact, the parameter every
+//     *-with-emotion template selects on.
+//   - `size` becomes an `mgx:hasProperty` fact and resolves to a numeric render
+//     SCALE (sprite-size.mjs's own closed scale table). It is the taught size of
+//     the thing being drawn, not a choice of template tier — the caller picks
+//     the tier by which template set it hands in.
+//
+// Nothing here refuses. A caller that needs a miss wall (the tool does) reads
+// `fellBackToRoot` / `expressionApplied` / `sizeKnown` / `expressionKnown` and
+// decides; a caller that wants today's fall-through-to-the-root-sprite
+// behaviour (the page does) just reads `svg`.
+
+/**
+ * Resolve `request` (`{ class, expression?, size? }`) against a template set.
+ *
+ * `deps` carries the injected collaborators and the state to resolve against:
+ * `resolveSpriteAsset` (required), `templates`, `spriteRegistry`, `factRows`
+ * (the taxonomy rows the ancestor walk reads), `rootFallback`, `instanceKey`,
+ * and — for the reported chain and vocabulary checks — `classAncestorChain`,
+ * `sizeScaleFor` and `expressionPalette`. Omit any of the last three and the
+ * fields they feed come back `null` rather than guessed.
+ *
+ * Returns `{ class, expression, size, svg, scale, sizeKnown, expressionKnown,
+ * expressionApplied, rootFallback, fellBackToRoot, chain, matched }`. Pure.
+ */
+export function resolveSpriteRequest(request, deps) {
+  const FEELS_PREDICATE = "mgx:feels";
+  const PROPERTY_PREDICATE = "mgx:hasProperty";
+
+  const className = String((request && request.class) || "").trim();
+  const expression = String((request && request.expression) || "").trim();
+  const size = String((request && request.size) || "").trim();
+
+  const options = deps || {};
+  const resolveAsset = options.resolveSpriteAsset;
+  if (typeof resolveAsset !== "function") {
+    throw new TypeError("resolveSpriteRequest needs deps.resolveSpriteAsset");
+  }
+  const templates = options.templates || [];
+  const registry = options.spriteRegistry || {};
+  const factRows = options.factRows || [];
+  const rootFallback = options.rootFallback || "animal";
+  const walkAncestors = options.classAncestorChain;
+  const scaleFor = options.sizeScaleFor;
+  const palette = options.expressionPalette;
+
+  const propertyFacts = [];
+  if (expression) propertyFacts.push({ predicate: FEELS_PREDICATE, object: expression });
+  if (size) propertyFacts.push({ predicate: PROPERTY_PREDICATE, object: size });
+
+  const assetOptions = { rootFallback };
+  if (options.instanceKey) assetOptions.instanceKey = options.instanceKey;
+  const svg = resolveAsset(className, factRows, propertyFacts, templates, registry, assetOptions);
+
+  // One resolve of a SINGLE term against an empty registry and its own root:
+  // the real resolver's answer to "does this level of the chain match", with no
+  // ancestor walk and no fall-through of its own.
+  const templateAt = (term) => resolveAsset(term, [], propertyFacts, templates, {}, { rootFallback: term });
+  const carriedByRegistry = (term) => Object.prototype.hasOwnProperty.call(registry, term);
+
+  // The template that produced `hit` at `term`: a fully-specific variant and a
+  // plain class template both hand their `svg` through untouched, so equality
+  // finds them; a parameterized template's substitutions change the string, and
+  // it is the only remaining candidate shape resolveAtTerm can have used.
+  const templateBehind = (term, hit) => {
+    const candidates = templates.filter((t) => t && Array.isArray(t.classes) && t.classes.indexOf(term) >= 0);
+    const authored = candidates.find((t) => t.svg === hit);
+    const template = authored || candidates.find((t) => !t.match && t.parameters) || null;
+    if (!template) return null;
+    return {
+      classes: template.classes.slice(),
+      parameters: Object.keys(template.parameters || {}).sort(),
+      match: template.match || null,
+    };
+  };
+
+  let chain = null;
+  let matched = null;
+  if (typeof walkAncestors === "function") {
+    chain = [];
+    for (const term of walkAncestors(className, factRows)) {
+      const hit = templateAt(term);
+      chain.push({ term, template: Boolean(hit), registry: carriedByRegistry(term) });
+      if (hit) {
+        matched = { term, via: "template", hops: chain.length - 1, root: false, template: templateBehind(term, hit) };
+        break;
+      }
+      if (carriedByRegistry(term)) {
+        matched = { term, via: "registry", hops: chain.length - 1, root: false, template: null };
+        break;
+      }
+    }
+    if (!matched) {
+      const rootHit = templateAt(rootFallback);
+      chain.push({ term: rootFallback, template: Boolean(rootHit), registry: carriedByRegistry(rootFallback), root: true });
+      matched = {
+        term: rootFallback,
+        via: rootHit ? "template" : "registry",
+        hops: chain.length - 1,
+        root: true,
+        template: rootHit ? templateBehind(rootFallback, rootHit) : null,
+      };
+    }
+  }
+
+  // Compared without the instance-id namespacing, which rewrites gradient ids
+  // and would make two otherwise identical resolutions look different.
+  const plainSvg = options.instanceKey
+    ? resolveAsset(className, factRows, propertyFacts, templates, registry, { rootFallback })
+    : svg;
+  const withoutExpression = expression
+    ? resolveAsset(className, factRows, propertyFacts.filter((f) => f.predicate !== FEELS_PREDICATE), templates, registry, { rootFallback })
+    : null;
+
+  return {
+    class: className,
+    expression: expression || null,
+    size: size || null,
+    svg,
+    scale: typeof scaleFor === "function" ? scaleFor(propertyFacts) : 1,
+    sizeKnown: size && typeof scaleFor === "function"
+      ? scaleFor([{ predicate: PROPERTY_PREDICATE, object: size }]) !== 1
+      : null,
+    expressionKnown: expression && palette
+      ? Object.prototype.hasOwnProperty.call(palette, expression)
+      : null,
+    expressionApplied: expression ? plainSvg !== withoutExpression : null,
+    rootFallback,
+    fellBackToRoot: matched ? Boolean(matched.root) : null,
+    chain,
+    matched,
+  };
+}