@polycode-projects/the-mechanical-code-talker 2.8.0 → 2.8.3

package/README.md

@@ -120,10 +120,11 @@ tmct> /exit
 
 **[Try it live in your browser →](https://polycode-projects.gitlab.io/the-mechanical-code-talker/)**
 is a real, interactive chat demo running client-side. Your browser runs the
-actual query engine against a small example codebase, no server, no install.
-The page leads with the **memory ledger**: every fact as a readable sentence,
-drill by clicking the terms inside them, and an in-page chat whose answers
-focus the ledger.
+actual query engine, no server, no install. The page opens with a live chat
+you can talk to directly, then embeds the **memory ledger** (every fact as a
+readable sentence, drill by clicking the terms inside them), a Towers-of-Hanoi
+plan replayed move by move, and the two live games above — spider-fly and the
+text adventure — each with a link to open it full-screen.
 
 From a clone, two build scripts regenerate that demo so you can check it
 offline before it deploys. The example graph, the ledger page, and the
@@ -183,7 +184,7 @@ resolves to a real graph traversal or declines cleanly:
   (*because/although/while*), conditionals, and false-premise flags ("why
   does X still import Y" when it no longer does).
 
-The full catalog with measured coverage lives in `CAPABILITIES_2.0.3.md` and
+The full catalog with measured coverage lives in `CAPABILITIES_2.7.12.md` and
 the `BENCHMARK_*.md` reports.
 
 **Response finishing.** Before an answer prints, it is segmented into typed
@@ -371,7 +372,7 @@ the plan as a self-contained animated page (see "Two more surfaces" above).
 
 ## Play a game with it
 
-Two games run inside an ordinary chat session, no setup.
+Three games run inside an ordinary chat session, no setup.
 
 **Guess the number.** Say `I'm thinking of a number between 1 and 100` and
 tmct guesses by narrowing an interval — answer `higher`, `lower`, or
@@ -393,6 +394,19 @@ a blocked action declines by name, and one of the household moves on its own
 schedule whether you are there to see it or not. The full worked mystery is
 pinned step by step in `test/corpus/games/adventure.jsonl`.
 
+**Two agents, planning against each other.** Say `play spider and fly` (or
+`watch the spider and the fly`) and tmct runs both sides itself — neither is
+player-controlled. A spider hunts a fly across a 10×10 web; each side only
+believes what it can currently see (`vision_radius`, tunable), a fly wanders
+when nothing threatens it and evades when something does, a spider avoids
+other spiders, chases what it believes it sees, and builds a web when it
+holds position. Mass is real: both sides waste away each turn they don't
+eat, and a spider gains exactly the mass of what it catches. You can address
+either side directly (`@spider the fly is east`) to feed it a belief — true
+or false — and watch a wrong assertion mislead it for as long as the real
+target stays out of sight. `tmct.toml`'s `[games.spider-fly]` table tunes
+every rate; the full mechanic is pinned in `test/corpus/games/spider-fly.jsonl`.
+
 ## Learning on a miss
 
 A question tmct cannot ground is still an honest miss — but on the cleanest
@@ -1035,18 +1049,18 @@ service. The LLM agent stays outside tmct, as the no-LLM ethos requires.
 
 ## Measuring it
 
-What the 2.0.3 cycle measured, on 2026-07-16. Each figure links to its method
-and carries, in the same row, the caveat that changes what it means. The full
-tables, judge scores, and transcripts are in the linked write-ups.
+What the 2.7.11/2.7.12 cycle measured, on 2026-07-19. Each figure links to its
+method and carries, in the same row, the caveat that changes what it means.
+The full tables, judge scores, and transcripts are in the linked write-ups.
 
-| What it does | Result (2.0.3) | Read the number with this | Method |
+| What it does | Result (2.7.12) | Read the number with this | Method |
 |---|---|---|---|
-| Multi-hop entailment | 219/219 chat cases and 80/80 kernel cases, 0% fabrication, all six bands pass | 50 of the 219 greens (23%) are graded against a declared floor, not the classical answer. INF-C2's 20/20 grades that the engine answers contradictory memory without fabricating, never that it detects the clash. | `BENCHMARK_INFERENCE_2.0.3.md` |
-| Tool-call planning | 56/56 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. All 11 C2 cases pass, so the ladder now has more headroom than the case set exercises. | `BENCHMARK_AGENT_2.0.3.md` |
-| Groundedness | Every answer carries a source, and an empty graph reports itself empty (`bootstrap-empty` 2.000/2). Judge-scored groundedness 1.857/2 over 98 cases. | The 1.857 is judged (`claude-haiku-4-5-20251001`, `judge-prompt-v1`) at N=1 over 9 of 23 construction shapes, so read it as indicative. The judge runs in the offline eval harness, never in the product. | `BENCHMARK_CEFR_ENGLISH_2.0.3.md` |
-| Abstention (the honest miss) | 0% fabrication across 299 inference rows and 0% hallucination across 168 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `BENCHMARK_INFERENCE_2.0.3.md`, `BENCHMARK_AGENT_2.0.3.md` |
-| Determinism | Byte-identical on rerun, 0 verdict changes across 299 inference rows against the prior cycle, a 109-case replay in 877ms at $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.0.3.md`, `CAPABILITIES_2.0.3.md` |
-| Dialogue robustness (role and polarity) | An adversarial persona sweep could not force a single role or polarity inversion in 55 probes — active/passive, forward/reverse, negation and the converse trap all compiled to the correct canonical shape | The same five-frame sweep (~200 probes) surfaced 25 dialogue dead-ends, eight of them confidently wrong, all from words dropped before the parser rather than from the reasoning. | `BENCHMARK_CONVERSATION_2.0.3.md` |
+| Multi-hop entailment | 379/379 chat cases and 100/100 kernel cases, 0% fabrication, all bands pass | The case set is unchanged from 2.6.0 (same templates, same counts) — the one real move this cycle is INF-4's ceiling-graded count dropping 35→30, five cases that now pass as genuine capability instead of against the declared honest-miss floor. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Tool-call planning | 68/68 cases, 100% plan-completion, 100% result-completion, 0% hallucination, every rung A0→C2 | Goal driver. 2.6.0 gated at TOOL-7 (62/66, 94%) — this cycle's router uplift (a guarded RECOVER step, a tied-candidate composer) cleared it, a real capability move, not a ruler change. | `BENCHMARK_AGENT_2.7.12.md` |
+| Groundedness | Every answer carries a source, and an empty graph reports itself empty. Judge-scored mean 1.809/2 over 138 cases, 5 hard fails, 136/138 tier-1. | Judged (`claude-haiku-4-5-20251001`, `judge-prompt-v2`) at N=1. The judge prompt moved v1→v2 since 2.6.0, so this is a measurement, not a clean lever comparison against the prior cycle. The judge runs in the offline eval harness, never in the product. | `BENCHMARK_CEFR_ENGLISH_2.7.12.md` |
+| Abstention (the honest miss) | 0% fabrication across 479 inference rows (379 chat + 100 kernel) and 0% hallucination across 272 agent rows | Structural, not a tuned threshold. tmct abstains because nothing matched, so the rows test a property of a no-model design rather than a score. | `BENCHMARK_INFERENCE_2.7.12.md`, `BENCHMARK_AGENT_2.7.12.md` |
+| Determinism | Byte-identical on rerun — a 379-case `--replay` clean across 2 runs, no LLM, no network, $0 per turn | A property of the no-model pipeline. | `BENCHMARK_INFERENCE_2.7.12.md` |
+| Dialogue robustness (persona sweep) | A 6-persona sweep (textbook logician, casual newcomer, new developer, adversarial sceptic, returning user, planning user) fixed 25 of the prior cycle's 29 routed findings (21 clean, 4 with a residual noted); 4 remain broken, 2 in a shape distinct from the original complaint | Free exploration across all six personas surfaced roughly 60 fresh findings beyond the ratchet check — the single highest-signal pattern: tmct's own suggested repair text was itself frequently broken when followed verbatim (since fixed, see `HANDOVER.md`). | `BENCHMARK_CONVERSATION_2.7.11.md` |
 
 Three offline benchmark rigs live in a clone (they are not in the npm
 package). Each replays a committed case set through the real product and

package/corpus/tier2/generate.mjs

@@ -665,6 +665,7 @@ export const CORPUSES = {
       ["hope", "/r/IsA", "emotion"], ["hope", "/r/CapableOf", "inspire_action"],
       ["surprise", "/r/IsA", "emotion"], ["surprise", "/r/CapableOf", "cause_astonishment"],
       ["pride", "/r/IsA", "emotion"], ["pride", "/r/CapableOf", "bring_satisfaction"],
+      ["sad", "/r/IsA", "emotion"],
       ["name", "/r/UsedFor", "identifying_a_person"], ["name", "/r/PartOf", "identity"],
       ["song", "/r/HasA", "word"], ["song", "/r/UsedFor", "entertaining"],
       ["music", "/r/HasA", "song"], ["music", "/r/CapableOf", "bring_joy"],

package/corpus/tier2/human.jsonl

@@ -622,6 +622,7 @@
 {"start":"/c/en/surprise","rel":"/r/CapableOf","end":"/c/en/cause_astonishment","weight":1,"surfaceText":"[[surprise]] CapableOf [[cause astonishment]]"}
 {"start":"/c/en/pride","rel":"/r/IsA","end":"/c/en/emotion","weight":1,"surfaceText":"[[pride]] IsA [[emotion]]"}
 {"start":"/c/en/pride","rel":"/r/CapableOf","end":"/c/en/bring_satisfaction","weight":1,"surfaceText":"[[pride]] CapableOf [[bring satisfaction]]"}
+{"start":"/c/en/sad","rel":"/r/IsA","end":"/c/en/emotion","weight":1,"surfaceText":"[[sad]] IsA [[emotion]]"}
 {"start":"/c/en/name","rel":"/r/UsedFor","end":"/c/en/identifying_a_person","weight":1,"surfaceText":"[[name]] UsedFor [[identifying a person]]"}
 {"start":"/c/en/name","rel":"/r/PartOf","end":"/c/en/identity","weight":1,"surfaceText":"[[name]] PartOf [[identity]]"}
 {"start":"/c/en/song","rel":"/r/HasA","end":"/c/en/word","weight":1,"surfaceText":"[[song]] HasA [[word]]"}

package/corpus/tier2/manifest.json

@@ -67,9 +67,9 @@
         "tool": "corpus/tier2/generate.mjs"
       },
       "file": "human.jsonl",
-      "facts": 664,
-      "bytes": 81430,
-      "sha256": "040e6d1f6761a29a080f7825ff8aae60caf879125c1f7a1480340ef04129bcd5",
+      "facts": 665,
+      "bytes": 81540,
+      "sha256": "7710c88c4c96a73fbbae19fe1989b0be40fed5ed40205016e90cc221bcb79607",
       "license": "MPL-2.0"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.8.0",
+  "version": "2.8.3",
   "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.",
@@ -137,6 +137,7 @@
     "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:plan-bundle": "node scripts/build-plan-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/corpus/sprite-large-template-files.mjs

@@ -23,6 +23,7 @@ import { fileURLToPath } from "node:url";
 import { join, dirname } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { expandMaterialReferences } from "../../domain/sprite-materials.mjs";
+import { expandExpressionReferences } from "../../domain/sprite-expressions.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** The sprite-tier template directory (data, not code) — every *.toml file
@@ -41,7 +42,10 @@ export const SPRITE_LARGE_TEMPLATES_DIR = join(HERE, "..", "..", "..", "data", "
  *  never go blank because one hand-authored sprite has a typo.
  *  test/adapters/sprite-large-template-files.test.mjs parses the real files
  *  directly (not through this lenient loader) so a broken file still fails a
- *  test loudly. */
+ *  test loudly. Material references expand first, expression references
+ *  second — the two indirections are independent (a template can carry
+ *  either, both, or neither) so the order between them never matters to the
+ *  result, only that both run before a template reaches a caller. */
 export function readSpriteLargeTemplateFiles(dir = SPRITE_LARGE_TEMPLATES_DIR) {
   let files;
   try {
@@ -58,5 +62,5 @@ export function readSpriteLargeTemplateFiles(dir = SPRITE_LARGE_TEMPLATES_DIR) {
       continue; // one malformed file never takes the others down
     }
   }
-  return expandMaterialReferences(templates);
+  return expandExpressionReferences(expandMaterialReferences(templates));
 }

package/src/domain/game-config.mjs

@@ -18,10 +18,13 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     spiderMassDecrementPerTurn: 0.5,
     flyInitialMass: 10,
     flyMassDecrementPerTurn: 1,
-    visionRadius: 4,
+    spiderVisionRadius: 4,
+    flyVisionRadius: 4,
     eggHatchDelayTurns: 3,
     flySpawnIntervalTurns: 3,
-    eggsEatenThreshold: 2,
+    eggLayMassThreshold: 25,
+    eggHatchCount: 2,
+    minHatchlingMass: 3,
     webDurationTurns: 10,
   }),
   guessNumber: Object.freeze({
@@ -42,10 +45,13 @@ const SPIDER_FLY_KEY_MAP = Object.freeze({
   spider_mass_decrement_per_turn: "spiderMassDecrementPerTurn",
   fly_initial_mass: "flyInitialMass",
   fly_mass_decrement_per_turn: "flyMassDecrementPerTurn",
-  vision_radius: "visionRadius",
+  spider_vision_radius: "spiderVisionRadius",
+  fly_vision_radius: "flyVisionRadius",
   egg_hatch_delay_turns: "eggHatchDelayTurns",
   fly_spawn_interval_turns: "flySpawnIntervalTurns",
-  eggs_eaten_threshold: "eggsEatenThreshold",
+  egg_lay_mass_threshold: "eggLayMassThreshold",
+  egg_hatch_count: "eggHatchCount",
+  min_hatchling_mass: "minHatchlingMass",
   web_duration_turns: "webDurationTurns",
 });
 

package/src/domain/hanoi-lesson.mjs

@@ -0,0 +1,53 @@
+// hanoi-lesson.mjs — the one pure generator behind the taught towers-of-hanoi
+// lesson: data/games/hanoi-3.txt's own content, generalized from a fixed
+// 3-disk puzzle to any disk count. Pure, no imports — both
+// scripts/build-demo-site.mjs (the static initial embed) and
+// src/surfaces/web/plan-browser-entry.mjs (the live re-solve a visitor's
+// disk-count control triggers) read the SAME sentence sequence from here, so
+// neither can drift from data/games/hanoi-3.txt's own taught shape.
+//
+// Every sentence is emitted the way `tmct import --file` actually teaches
+// one — split down to ONE fact per sentence, the exact granularity
+// import-file.mjs's own splitSentencesPreservingPaths would produce from the
+// committed file's body — not grouped multi-sentence lines, so each array
+// entry maps 1:1 onto a single runTurn() call.
+//
+// Always 3 pegs (peg-a/b/c); only the disk count varies. The pairwise
+// "smaller than" facts are EVERY pair, not just adjacent ones — the taught
+// relation is stored as given and never chased transitively (see the
+// "scale" variation documented in hanoi-3.txt itself), so a partial pairing
+// would leave some disks with no legal move.
+
+/** The taught lesson for an N-disk puzzle: the class/individual/ordering
+ *  facts, the action rule, the render hints, the starting stack (largest at
+ *  the bottom of peg-a, smallest on top), and the goal + solve trigger —
+ *  one sentence per array entry, in teaching order. `diskCount` is floored
+ *  and clamped to at least 1. */
+export function hanoiLessonSentences(diskCount = 3, { goalPeg = "peg-c" } = {}) {
+  const n = Math.max(1, Math.floor(Number(diskCount) || 1));
+  const disks = Array.from({ length: n }, (_, i) => `disk-${i + 1}`);
+  const pegs = ["peg-a", "peg-b", "peg-c"];
+  const sentences = [];
+
+  sentences.push("a disk is a kind of game piece.");
+  sentences.push("a peg is a kind of place.");
+  for (const d of disks) sentences.push(`${d} is a disk.`);
+  for (const p of pegs) sentences.push(`${p} is a peg.`);
+  for (let i = 0; i < n; i += 1) {
+    for (let j = i + 1; j < n; j += 1) sentences.push(`${disks[i]} is smaller than ${disks[j]}.`);
+  }
+  sentences.push("you can move a disk onto a peg.");
+  sentences.push("you can move a disk onto a disk.");
+  sentences.push("to move a disk onto a target, nothing may rest on the disk.");
+  sentences.push("to move a disk onto a target, nothing may rest on the target.");
+  sentences.push("to move a disk onto a disk, the disk must be smaller than the target.");
+  sentences.push("moving a disk onto a target makes the disk rest on the target.");
+  sentences.push("a disk renders as a block.");
+  sentences.push("a peg renders as a slot.");
+  for (let i = 0; i < n - 1; i += 1) sentences.push(`${disks[i]} rests on ${disks[i + 1]}.`);
+  sentences.push(`${disks[n - 1]} rests on peg-a.`);
+  sentences.push(`the goal is that every disk rests on ${goalPeg}.`);
+  sentences.push("solve it.");
+
+  return sentences;
+}

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

@@ -86,6 +86,22 @@ export const DIRECTION_DELTA = Object.freeze({
   west: Object.freeze({ dx: -1, dy: 0 }),
 });
 
+/** The single compass direction from `fromCell` to `toCell` when `toCell`
+ *  sits EXACTLY one cardinal step away (DIRECTION_DELTA) — null for the same
+ *  cell, a diagonal, or any multi-step gap, so a caller never overstates
+ *  "adjacent". The one shared primitive both the engine's own plan-driven
+ *  facing (spider-fly.mjs) and the chat dock's deception pills
+ *  (spider-fly-turn.mjs's pillsForSpiderFly) need — defined once here so
+ *  neither has to re-derive it, and so the engine layer never has to import
+ *  the chat-turn layer to get it (spider-fly-turn.mjs already imports
+ *  spider-fly.mjs; the reverse would cycle). */
+export function oneStepDirectionBetween(fromCell, toCell) {
+  for (const [direction, { dx, dy }] of Object.entries(DIRECTION_DELTA)) {
+    if (fromCell.x + dx === toCell.x && fromCell.y + dy === toCell.y) return direction;
+  }
+  return null;
+}
+
 /** The world's seed taxonomy (PLAN_SPIDER_FLY.md §7): enough for the
  *  ontology-to-sprite worked example (a poodle sprite, a sheepdog falling
  *  back to the generic dog sprite) to run on the default persona, no

package/src/domain/sprite-expressions.mjs

@@ -0,0 +1,120 @@
+// sprite-expressions.mjs — the shared face-fragment scheme the sprite tier's
+// mgx:feels parameter draws from, one small dot/curve-eyes-plus-mouth
+// drawing per curated emotion word, mirroring sprite-materials.mjs's own
+// by-name-reference shape exactly: a frozen palette of raw treatment data,
+// and a pure expand function that turns a short by-name reference in a
+// template's own [parameters.emotion.values] table into the full
+// substitution — so a face fragment is authored ONCE here and referenced by
+// name from every data/sprites-large/*-with-emotion.toml file, rather than
+// six-plus files each hand-copying the same eyes-and-mouth paths.
+//
+// The one real difference from a material treatment: a hex triple needs no
+// context to drop into a template's placeholder, but a face fragment does —
+// classes vary enough in head geometry (a dog's head circle is
+// cx=7 cy=9 r=3.6, a cat's is cx=9 cy=9.4 r=4.4, a person's is
+// cx=12 cy=6.6 r=3.3) that one universal anchor position would misplace the
+// eyes on at least one of them. So EXPRESSION_PALETTE's own fragments are
+// authored in a UNIT face — eyes and mouth drawn as if the head were a
+// radius-1 circle centred on the origin — and expandExpressionReferences
+// wraps the matched fragment in `<g transform="translate({cx} {cy})
+// scale({scale})">` using the SAME template's own required `[face]` table
+// (cx/cy/scale) to place and size it for that one class's real head. A
+// template with a [parameters.emotion] table but no [face] table is left
+// unexpanded (spriteTemplateProblems flags the pairing as a real problem —
+// see sprite-templates.mjs — this function itself stays defensive, never
+// throws on a malformed template).
+//
+// Every fragment uses a fixed dark ink colour rather than currentColor —
+// a face needs to read against ANY body fill (a gold lamp's flame stays a
+// fixed amber for the same reason: what the face/flame looks like doesn't
+// come from what the body is made of or coloured).
+//
+// Convention for every future `*-with-emotion.toml` file (content-authoring
+// agents: read this before copying the shape) — `{{FACE}}` is always the
+// LAST child before `</svg>`, so the resolved face fragment paints over
+// the body/highlight shapes beneath it, never the reverse.
+
+/** The dark ink colour every face fragment draws its eyes/mouth in,
+ *  regardless of the sprite's own body fill — the same fixed-colour
+ *  reasoning lamp.toml's flame already uses (sprite-templates.mjs's own
+ *  header explains the precedent). */
+const FACE_INK = "#000000";
+
+/** One `<g>`-ready fragment per curated emotion word, dot/curve eyes plus a
+ *  mouth curve, authored in a unit face (radius 1, centred on the origin) —
+ *  expandExpressionReferences positions and scales it per class. Distinct
+ *  by more than mouth curvature alone: scared/surprised both open wide, but
+ *  scared's mouth stays a small tense "o" while surprised's is a large
+ *  dropped-jaw oval; calm's eyes are closed contented arcs where happy's
+ *  are open dots, so no two of the six collapse into the same read at a
+ *  glance. */
+export const EXPRESSION_PALETTE = Object.freeze({
+  happy:
+    `<circle cx="-0.4" cy="-0.15" r="0.11" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.15" r="0.11" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<path d="M -0.4 0.35 Q 0 0.68 0.4 0.35" fill="none" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`,
+  sad:
+    `<circle cx="-0.4" cy="-0.1" r="0.1" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.1" r="0.1" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<path d="M -0.38 0.55 Q 0 0.3 0.38 0.55" fill="none" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`,
+  angry:
+    `<path d="M -0.58 -0.32 L -0.22 -0.16" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`
+    + `<path d="M 0.58 -0.32 L 0.22 -0.16" stroke="${FACE_INK}" stroke-width="0.09" stroke-linecap="round" opacity="0.85"/>`
+    + `<circle cx="-0.32" cy="-0.02" r="0.09" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.32" cy="-0.02" r="0.09" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<path d="M -0.36 0.5 L 0.36 0.42" stroke="${FACE_INK}" stroke-width="0.1" stroke-linecap="round" opacity="0.85"/>`,
+  scared:
+    `<circle cx="-0.4" cy="-0.12" r="0.2" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="-0.4" cy="-0.12" r="0.07" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.12" r="0.2" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="0.4" cy="-0.12" r="0.07" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0" cy="0.42" r="0.09" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`,
+  surprised:
+    `<circle cx="-0.38" cy="-0.12" r="0.17" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="-0.38" cy="-0.12" r="0.06" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<circle cx="0.38" cy="-0.12" r="0.17" fill="none" stroke="${FACE_INK}" stroke-width="0.07" opacity="0.85"/>`
+    + `<circle cx="0.38" cy="-0.12" r="0.06" fill="${FACE_INK}" opacity="0.85"/>`
+    + `<ellipse cx="0" cy="0.42" rx="0.16" ry="0.22" fill="${FACE_INK}" opacity="0.7"/>`,
+  calm:
+    `<path d="M -0.5 -0.1 Q -0.4 -0.2 -0.3 -0.1" fill="none" stroke="${FACE_INK}" stroke-width="0.08" stroke-linecap="round" opacity="0.85"/>`
+    + `<path d="M 0.3 -0.1 Q 0.4 -0.2 0.5 -0.1" fill="none" stroke="${FACE_INK}" stroke-width="0.08" stroke-linecap="round" opacity="0.85"/>`
+    + `<path d="M -0.3 0.4 Q 0 0.5 0.3 0.4" fill="none" stroke="${FACE_INK}" stroke-width="0.08" stroke-linecap="round" opacity="0.85"/>`,
+});
+
+/** The mgx:feels property name every emotion-bearing template's
+ *  `[parameters.emotion]` table names — sprite-templates.mjs never needs
+ *  to know this constant exists (it reads `param.property` generically),
+ *  this module only uses it to recognise which parameter table is ITS OWN
+ *  to expand, the same role sprite-materials.mjs's `param.placeholders`
+ *  shape check plays for a material table. */
+const FEELS_PROPERTY = "mgx:feels";
+
+/**
+ * Every `[parameters.emotion].values` string entry, in every template,
+ * expanded from a curated emotion-word KEY (e.g. "happy") to the full
+ * `<g transform="translate(cx cy) scale(scale)">…</g>` substitution for
+ * THIS template's own required `[face]` table — but only for a template
+ * whose `[parameters.emotion]` table names `mgx:feels` as its property
+ * (sprite-templates.mjs's `param.property`) and that also carries a
+ * `[face]` table; a template missing either is left alone (defensive, never
+ * throws — spriteTemplateProblems is what flags that pairing as a real
+ * authoring mistake). A values entry naming no known palette word is left
+ * as the plain string it was, the same never-guess posture
+ * expandMaterialReferences already uses for an unknown treatment name.
+ * Pure; `templates` is read only.
+ */
+export function expandExpressionReferences(templates, palette = EXPRESSION_PALETTE) {
+  return (templates || []).map((t) => {
+    const emotion = t?.parameters?.emotion;
+    if (!emotion?.property || emotion.property !== FEELS_PROPERTY) return t;
+    if (!emotion.placeholder || !emotion.values || !t.face) return t;
+    const { cx, cy, scale } = t.face;
+    const values = {};
+    for (const [key, value] of Object.entries(emotion.values)) {
+      values[key] = typeof value === "string" && palette[value]
+        ? `<g transform="translate(${cx} ${cy}) scale(${scale})">${palette[value]}</g>`
+        : value;
+    }
+    return { ...t, parameters: { ...t.parameters, emotion: { ...emotion, values } } };
+  });
+}

package/src/domain/sprite-templates.mjs

@@ -96,20 +96,31 @@ function fillFromValue(svg, param, value) {
   return null;
 }
 
-/** Fill a parameterized template's `svg` from the first of its own
- *  `[parameters.*]` whose observed property value maps to a substitution —
- *  or null when no property fact names a mapped value (never a guess). */
-function parameterizedFill(template, propertyFacts) {
+/** Fill a parameterized template's `svg` from EVERY one of its own
+ *  `[parameters.*]` whose observed property value maps to a substitution,
+ *  accumulating each successful fill onto the RUNNING svg string rather
+ *  than stopping at the first hit — so a template declaring both e.g.
+ *  `[parameters.material]` and `[parameters.emotion]` fills both dimensions
+ *  in one pass, one parameter's substitution never undoing another's.
+ *  Returns null when not even one parameter filled (never a guess, and
+ *  never a half-filled template with a leftover placeholder token) — the
+ *  caller (resolveAtTerm) falls through to a less specific template exactly
+ *  as it did before this function tried more than one dimension. */
+function parameterizedFillAll(template, propertyFacts) {
+  let svg = template.svg;
+  let filledCount = 0;
   for (const param of Object.values(template.parameters || {})) {
     const values = param?.values || {};
     const hit = (propertyFacts || []).find(
       (f) => f.predicate === param.property && Object.prototype.hasOwnProperty.call(values, f.object),
     );
     if (!hit) continue;
-    const filled = fillFromValue(template.svg, param, values[hit.object]);
-    if (filled) return filled;
+    const filled = fillFromValue(svg, param, values[hit.object]);
+    if (!filled) continue;
+    svg = filled;
+    filledCount += 1;
   }
-  return null;
+  return filledCount > 0 ? svg : null;
 }
 
 /** Resolve ONE class term (no ancestor walk here — the caller repeats this
@@ -123,7 +134,7 @@ function resolveAtTerm(term, propertyFacts, templates) {
   if (matched) return matched.svg;
   for (const t of candidates) {
     if (t.match || !t.parameters) continue;
-    const filled = parameterizedFill(t, propertyFacts);
+    const filled = parameterizedFillAll(t, propertyFacts);
     if (filled) return filled;
   }
   const plain = candidates.find((t) => !t.match && !t.parameters);
@@ -174,7 +185,12 @@ export function resolveSpriteAsset(className, factRows, propertyFacts, templates
  *  names a `property` and exactly one of `placeholder`/`placeholders` (every
  *  token named appears in `svg`), its `values` map is non-empty and every
  *  entry matches the shape its own `placeholder`/`placeholders` choice
- *  expects, and a `[match]` table names both `property` and `value`. */
+ *  expects, a `[match]` table names both `property` and `value`, and
+ *  `[face]`/`[parameters.emotion]` are always declared TOGETHER — a face
+ *  anchor with nothing to select it, or an emotion parameter with nowhere to
+ *  position its face fragment, is a real authoring mistake either way
+ *  (sprite-expressions.mjs's own header explains why the face fragment
+ *  needs the pairing). */
 export function spriteTemplateProblems(template) {
   const problems = [];
   const t = template || {};
@@ -218,5 +234,11 @@ export function spriteTemplateProblems(template) {
   if (t.match && (!t.match.property || t.match.value === undefined)) {
     problems.push("match is missing property or value");
   }
+  if (t.face && !t.parameters?.emotion) {
+    problems.push("face is declared without parameters.emotion — a face anchor with nothing to select it is dead data");
+  }
+  if (t.parameters?.emotion && !t.face) {
+    problems.push("parameters.emotion is declared without a face — an emotion parameter needs its own [face] anchor to position the fragment it fills");
+  }
   return problems;
 }