@polycode-projects/the-mechanical-code-talker 5.0.4 → 5.0.6

package/README.md

@@ -27,6 +27,7 @@ derive by rule from both. Every answer is either grounded or an honest miss.
 | `data/` | seed data assets: sprites, phrasebook, games, response templates |
 | `ontology/` | the software ontology (`tmct-core.ttl`) and memory shapes, in Turtle |
 | `scripts/` | build, check, and maintenance scripts (`npm run` targets live here) |
+| `infra/` | the AWS CDK app that provisions the deployed site and its OIDC/deploy roles |
 | `examples/` | runnable example scripts and fixture repos used by the README's own examples and the test suite |
 | `demo/` | standalone demo scripts (e.g. the agentic-loop demo) |
 | `electron/` | the Electron desktop app wrapper |
@@ -37,7 +38,7 @@ derive by rule from both. Every answer is either grounded or an honest miss.
 | `reports/` | benchmark write-ups (`BENCHMARK_*.md`) and `PAGE_WEIGHTS.md` — see the root `STATUS.md` for the one-page summary these feed |
 | `playtests/` | numbered playtest session logs, one edge found and fixed per entry |
 | `archive/` | delivered `PLAN_*.md`/`BENCHMARK_*.md` docs, kept for history |
-| `public/` | the built demo site — a gitignored output of `npm run demo:build`, never hand-edited |
+| `public/` | the demo site: the hand-written home page, the eleven about pages, the shared stylesheet and the model/screenshot assets. The demo pages and browser bundles beside them are gitignored build outputs of `npm run demo:build` |
 
 `node_modules/` (dependencies) and dotfiles/hidden tooling directories are omitted above.
 
@@ -319,16 +320,19 @@ tmct> /exit
 
 **[Try it live in your browser →](https://tmct.polycode.co.uk/)**
 runs the actual query engine client-side. No server, no install. The landing
-page answers codebase questions live, and eight more pages each ground their
+page answers codebase questions live, and eleven more pages each ground their
 own domain: a full chat seeded with 63,470 facts (the same nine bands as
 `npm run init:xl`), the
 **memory ledger** (every fact as a readable sentence; drill by clicking the
 terms inside), and the **code explorer** (the same ledger UI refocused on a
 code graph, with a hint rail of suggested next questions). An **ingest
 page** turns pasted or dropped text into grounded facts and downloads them
-as canonical JSONL. The rest are a Towers-of-Hanoi plan replayed move by
-move, the spider-and-fly and text-adventure games, and a sprite gallery
-whose chat dock answers from 1,033 generated sprite facts. The chat page and
+as canonical JSONL, and a **research page** walks a stub wiki graph link by
+link. The rest are a Towers-of-Hanoi plan replayed move by move, the
+spider-and-fly and text-adventure games, a sprite gallery whose chat dock
+answers from 1,480 generated sprite facts, and two multi-agent worlds: a
+burrow that shares one world across browsers over WebRTC, and a Three.js
+town square where a wolf hunts goblins. The chat page and
 the ledger take the same paste-or-drop text in place; every page that holds
 a fact store exports it as JSONL.
 The site hosts its own copy of wink-nlp, ships its assets precompressed,
@@ -373,8 +377,8 @@ functions". Every suggestion resolves to a real answer.
 The identical page also runs as a plain hosted page over the demo code
 graph, with nothing to install:
 **[try it live →](https://tmct.polycode.co.uk/code.html)**.
-The desktop build below is for exploring your own repo or graph, which the
-hosted page cannot reach.
+The desktop build below is for exploring your own repo or graph: a browser page
+gets no filesystem access, so the hosted page reads the demo graph it ships with.
 
 Electron is a dev-only dependency and never ships in the npm package. Because
 `.npmrc` sets `ignore-scripts=true`, installing it does not fetch the runtime
@@ -659,7 +663,7 @@ now consults two shipped, lazily-loaded packs before giving up:
   triples into memory (provenance `child:conceptnet:kettle`, ranked below
   anything you teach) and answers from them; the next ask answers from
   memory directly.
-- `corpus/reference/`: 3,887 Simple English Wikipedia summaries. When the
+- `corpus/reference/`: 3,888 Simple English Wikipedia summaries. When the
   triples cannot answer, a matching article answers as a cited read-out
   (`source: reference article "Otter"…, CC BY-SA 4.0`).
 
@@ -712,7 +716,7 @@ the shipped `npm run example:*` demos) reads a graph but writes nothing back.
 
 The default persona also comes in three sizes: Small (~664 facts, the
 default), Medium (~1,608, `tmct init --persona-size medium`) and Large
-(~13,609, `--persona-size large`, deep enough to chain real multi-hop
+(~13,600, `--persona-size large`, deep enough to chain real multi-hop
 reasoning).
 
 ### Memory backends
@@ -935,6 +939,17 @@ provenance record. Most of its flags choose what gets seeded and where config is
                                in this repo picks it up with no flag needed
 ```
 
+`tmct index` is the producer side of the graph seam. It walks a repo's own source
+and writes the `.tmct/graph.json` that chat, serve and the CLI then read.
+
+```output:help:index
+  tmct index [--repo <abs>]    produce a code graph from a repo's OWN source (default: cwd):
+       [--no-history]          walk the tree, parse JS/TS with the TypeScript compiler
+                               API, read git history, and write <repo>/.tmct/graph.json —
+                               the artifact chat/serve/cli then read. --no-history skips
+                               the git passes (no commit/touches/cochange edges)
+```
+
 `tmct import` does the same activation as `tmct init`, but against a repo that is
 already set up. Its `--graph` flag works differently from the others: it appends to
 `tmct.toml`'s `graph_files` array instead of activating a bundle.
@@ -1055,6 +1070,15 @@ kill $SERVE_PID
        [--graph <path>]        the same thing. --graph names the graph file outright
        [--config <path>]       (repeatable), --config an alternate tmct.toml
   tmct cli digest '{…}'        architecture map + per-module context bundles
+  tmct --help                  show this help
+```
+
+The help closes with two notes on where a chat session runs and what it leaves
+behind:
+
+```output:help:notes
+On a terminal, chat opens the full-screen TUI; piped input gets the plain shell.
+In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/session-<id>.md.
 ```
 
 Two precedence chains apply across every command above, in this order:
@@ -1116,6 +1140,12 @@ graph_file = ".tmct/graph.json"
 # Extra graphs, merged alongside graph_file (ids that collide are auto-prefixed).
 graph_files = [".tmct/graph.json", ".tmct/legacy-graph.json"]
 
+[graph]
+# A chat session reads this repo's graph and writes nothing back into its
+# .tmct/: no session upsert, no transcript, no memory. The committed example
+# fixtures set it so `tmct chat --repo examples/<x>` can't rewrite them.
+read_only = false
+
 [corpus]
 # "tier1" (committed slice only, $0/offline, the default), "tier2" (also fetch
 # growable corpora at seed time), or "tier3" (also consult live sources per query).
@@ -1124,6 +1154,8 @@ tier = "tier1"
 [seed]
 enabled = true      # seed the committed corpus into .tmct/memory during init
 limit = 500         # cap the seeded fact count (definitional band first); unset = no cap
+capture_unknown_context = true   # keep the sentence around an unrecognized term
+unknown_context_limit = 200      # cap how many of those contexts are kept
 
 # One [extensions.<name>] table per bundle. A recognized name (human, seon,
 # conceptnet, human-medium, human-large, tier2-aws, tier2-python, tier2-java,
@@ -1177,7 +1209,6 @@ call_adjacency = true       # boost callers/callees of a matched symbol
 impl_of_interface = true    # boost an interface's implementations
 beam_search = true          # use beam search over the graph walk
 beam_width = 8
-embed_rank = false          # rerank by embedding similarity (off by default)
 prose_layers = 2            # how many prose-generation passes to run
 
 [tune.expansion]
@@ -1186,6 +1217,17 @@ nodes = 50                  # node budget for the walk
 q = 0.5                     # expansion breadth parameter
 depth = 3                   # max hops
 
+# Research-lane knobs (src/services/research.mjs).
+[research]
+fanout_limit = 8            # links followed per page
+max_depth = 3               # hops from the starting topic
+max_topics = 40             # topics visited in one crawl
+min_interval_ms = 1000      # politeness delay between fetches
+
+# Discourse record (src/domain/discourse.mjs).
+[discourse]
+max_referents = 12          # how many referents stay resolvable across turns
+
 [telemetry]
 enabled = false             # local-only counters; never phones home
 
@@ -1202,10 +1244,13 @@ spider_initial_mass = 15
 spider_mass_decrement_per_turn = 0.5   # lower = slower to starve
 fly_initial_mass = 10
 fly_mass_decrement_per_turn = 1
-vision_radius = 4                      # Chebyshev radius an agent can see other agents within
+spider_vision_radius = 4               # Chebyshev radius a spider sees other agents within
+fly_vision_radius = 4                  # the same radius for a fly
 egg_hatch_delay_turns = 3              # turns between a lay and its hatch
 fly_spawn_interval_turns = 3           # a new fly arrives every Nth turn
-eggs_eaten_threshold = 2               # flies eaten since the last egg before the next one lays
+egg_lay_mass_threshold = 25            # mass a spider must reach before it lays
+egg_hatch_count = 2                    # hatchlings per egg
+min_hatchling_mass = 3                 # mass a hatchling starts with
 web_duration_turns = 10                # turns a spider-built web stays active
 
 [games.guess-number]
@@ -1219,8 +1264,9 @@ max_depth = 300  # the "solve it" plan lane's search-depth cap (hanoi, river-cro
 
 ### Try it on an example graph
 
-tmct *consumes* a code graph at `<repo>/.tmct/graph.json`. It does not build
-one. Two ready-made example graphs live in `examples/` in this repo (clone the
+tmct reads a code graph at `<repo>/.tmct/graph.json`. `tmct index` builds one
+from a repo's own source, and any other producer can write the same file. Two
+ready-made example graphs live in `examples/` in this repo (clone the
 repo to use them; they are not in the published npm package), so you can see
 it answer real questions with no setup:
 
@@ -1402,7 +1448,7 @@ and transcripts are in the linked write-ups.
 | 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. | `archive/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 `NEXT.md`). | `archive/BENCHMARK_CONVERSATION_2.7.11.md` |
 
-Three offline benchmark rigs live in a clone (they are not in the npm
+Seven 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
 writes graded rows you can diff between runs:
 
@@ -1412,7 +1458,14 @@ writes graded rows you can diff between runs:
 - `npm run infbench` generates inference cases, then runs each through both
   drive points, the reasoning kernel and the chat surface;
 - `npm run agentbench:run` measures the tool-loop behaviour, and every
-  verdict carries a hallucination axis.
+  verdict carries a hallucination axis;
+- `npm run idxbench:run` grades how faithfully the code-index producer
+  restates source as a graph;
+- `npm run ingestbench:run` (with `ingestbench:judge`) grades text-to-facts
+  extraction;
+- `npm run researchbench:run` grades the research lane's link traversal
+  against a frozen stub wiki graph;
+- `npm run synthbench:code` grades deterministic code synthesis.
 
 The smallest real slice of each, the same invocations the test suite's
 bench-smoke lane replays:
@@ -1457,7 +1510,7 @@ tmct's vocabulary is grounded in published standards where they exist, and says
 Each alignment below is a triple in `ontology/tmct-core.ttl` and a test in
 `test/adapters/grammar-ontology.test.mjs`. `docs/references/` holds an entry per source: the
 edition, the retrieval date, the terms tmct uses, and what could not be verified.
-`PLAN_NORMATIVE.md` holds the reconciliation, one verdict per term.
+`archive/PLAN_NORMATIVE.md` holds the reconciliation, one verdict per term.
 
 ### The data model
 
@@ -1476,7 +1529,7 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 | [Attempto Controlled English](http://attempto.ifi.uzh.ch/site/docs/) | ACE 6.7, 2013 | The controlled-English fragment. tmct implements 9 of ACE's declarative sentence patterns. |
 | Kuhn, "A Survey and Classification of Controlled Natural Languages" | *Computational Linguistics* 40(1), 2014 | Where ACE sits among controlled languages. |
 | [ConceptNet](https://github.com/commonsense/conceptnet5/wiki/Relations) | slice pins 5.7.0 | The commonsense corpus. 25 relations are mirrored into `mgx:` and each cites its `/r/` origin. |
-| Damerau, *CACM* 7(3), 1964 · Levenshtein, *Soviet Physics Doklady* 10(8), 1966 | — | Fuzzy matching. `fuzzy.mjs` implements **Optimal String Alignment** — restricted Damerau-Levenshtein, which allows adjacent transposition but edits no substring twice. |
+| Damerau, *CACM* 7(3), 1964 · Levenshtein, *Soviet Physics Doklady* 10(8), 1966 | — | Fuzzy matching. `src/domain/interpret/fuzzy.mjs` implements **Optimal String Alignment** — restricted Damerau-Levenshtein, which allows adjacent transposition but edits no substring twice. |
 
 ### Reasoning and planning
 
@@ -1492,7 +1545,7 @@ edition, the retrieval date, the terms tmct uses, and what could not be verified
 
 | source | edition | what tmct uses it for |
 |---|---|---|
-| Jensen et al., "A Consensus Glossary of Temporal Database Concepts" | *SIGMOD Record* 23(1), 1994 | The time vocabulary. `mgx:utteranceTs` is valid time; `mgx:createdAt` is a transaction-time start. tmct is **not** bitemporal: `mgx:updatedAt` is an audit stamp, so tmct cannot answer what it believed last Tuesday. |
+| Jensen et al., "A Consensus Glossary of Temporal Database Concepts" | *SIGMOD Record* 23(1), 1994 | The time vocabulary. `mgx:utteranceTs` is valid time; `mgx:createdAt` is a transaction-time start. tmct is **not** bitemporal: `mgx:updatedAt` is an audit stamp, so "what did it believe last Tuesday" lands on the honest miss wall. |
 | RFC 9923, "The FNV Non-Cryptographic Hash Algorithm" | Informational, 2026 | FNV hashes the narrow non-fact-id pools (paraphrase keys, per-URL source ids, corpus dedupe). Fact ids are content-addressed with a **64-bit truncation of SHA-256**, so a fact id is collision-resistant at tmct's corpus sizes; tmct is still **not** a Merkle tree and offers no tamper-evidence. |
 | Green, Karvounarakis, Tannen, "Provenance Semirings" | PODS 2007 | The distinction tmct's docs keep: it records source annotation and PROV-style attribution, not how-provenance. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "5.0.4",
+  "version": "5.0.6",
   "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; indexes a repo on request (tmct index) or reads any producer's graph.",

package/src/adapters/memory/core.mjs

@@ -50,6 +50,7 @@ import {
   planRetraction, mergeRetractions, retractionFromWire, retractionWireFact,
   isRetractedRecord, RETRACTION_CLASS,
 } from "../../domain/memory/retraction.mjs";
+import { admittedNodes, stableRecordIds } from "../../domain/memory/causal-stability.mjs";
 import { assertIndividualValid } from "./shacl.mjs";
 
 // The rollup vocabulary and its tuning constants live with the compaction
@@ -70,6 +71,8 @@ export {
   retractedRecordIds, retractedAtOf, retractionWireFact, retractionFromWire,
 } from "../../domain/memory/retraction.mjs";
 
+export { admittedNodes, peersToConvince, stableRecordIds } from "../../domain/memory/causal-stability.mjs";
+
 export const MEMORY_DIR_REL = join(".tmct", "memory");
 export const MEMORY_GRAPH_REL = join(MEMORY_DIR_REL, "graph.json");
 
@@ -3189,6 +3192,56 @@ export async function appendRetractions(dir, wireFacts) {
   return { merged: incoming.length, removed };
 }
 
+/** What this store could retire, and the roster it has to convince first.
+ *
+ *  `roster` is the world's admission graph, folded to a set of node ids —
+ *  replicated, grow-only, and the same on every peer holding the same facts.
+ *  `retirable` is the tombstones every peer on that roster is known to hold.
+ *  `acknowledgedBy(nodeId)` is what supplies that evidence; nothing produces it
+ *  yet, so `retirable` reads empty and this is a report rather than a sweep.
+ *  Retiring nothing is the current behaviour, and it is the safe one: a
+ *  tombstone dropped one peer early lets that peer's copy resurrect a retracted
+ *  fact. See docs/references/papers/crdt.md. */
+export function retirableRetractions(memory, { self = "", acknowledgedBy = null } = {}) {
+  const roster = admittedNodes(readFactRows(memory));
+  const recordIds = [];
+  for (const ind of memory?.individuals || []) {
+    if (ind?.class === RETRACTION_CLASS && ind.id) recordIds.push(ind.id);
+  }
+  return { roster, retirable: stableRecordIds({ recordIds, roster, self, acknowledgedBy }) };
+}
+
+/** Drop named retraction records. Takes the ids rather than choosing them, so a
+ *  caller has to have run the stability rule and passed its answer; ids that are
+ *  not retraction records are skipped. Returns the ids that went. */
+export async function retireRetractions(dir, ids) {
+  const asked = new Set((ids || []).filter(Boolean));
+  const retired = [];
+  if (!asked.size) return { retired };
+  await mutateMemory(dir, (payload) => {
+    const drop = new Set();
+    payload.individuals = (payload.individuals || []).filter((ind) => {
+      if (ind?.class !== RETRACTION_CLASS || !asked.has(ind.id)) return true;
+      drop.add(ind.id);
+      return false;
+    });
+    if (!drop.size) return;
+    for (const id of drop) retired.push(id);
+    const idx = memoryIndexOf(payload);
+    if (idx) {
+      for (const id of drop) {
+        idx.individualsById.delete(id);
+        const groupId = factGroupId(id);
+        const held = (idx.retractionsByGroup.get(groupId) || []).filter((r) => !drop.has(r.id));
+        if (held.length) idx.retractionsByGroup.set(groupId, held);
+        else idx.retractionsByGroup.delete(groupId);
+      }
+    }
+    recountClasses(payload);
+  });
+  return { retired };
+}
+
 /** The trust floor a fact must clear before a differing object counts as a real
  *  contradiction (below it the fact is too weak to contradict anything). */
 const CONTRADICTION_TRUST_FLOOR = 0.5;

package/src/domain/ask.mjs

@@ -15,7 +15,7 @@
 // ask.mjs's own `touches`/`cochange` verbs answer one-hop structural edges
 // (mgx:touchedByCommit / mgx:changeCoupledWith).
 
-import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP } from "./codegraph.mjs";
+import { relationKind, impactClosure, moduleCountOf, normPath, packageCounts, modulesOf, HISTORY_CAP, NO_CODE_INDEX_NOTE } from "./codegraph.mjs";
 import { isTestPath } from "./module-paths.mjs";
 import {
   RELATIONS,
@@ -2491,9 +2491,7 @@ export function rephraseHint() {
  *  graph is UNKNOWN, not empty (see chat.mjs's noCodeGraph), so it keeps the
  *  index-shaped advice. */
 function touchesRephraseHint(graph = null) {
-  if (graph && moduleCountOf(graph) === 0) {
-    return "This store holds no code index, so it records no modules or commits to look through.";
-  }
+  if (graph && moduleCountOf(graph) === 0) return NO_CODE_INDEX_NOTE;
   return 'Try "who touched <a module that actually has commits>" or "/describe <module>" to see what\'s in the index.';
 }
 

package/src/domain/codegraph.mjs

@@ -57,6 +57,10 @@ export function moduleCountOf(graph) {
   return graph.individuals.filter((i) => (i.class || "") === "Module").length;
 }
 
+/** What a store with zero modules actually holds, said once so every lane that
+ *  has to decline for that reason declines in the same words. */
+export const NO_CODE_INDEX_NOTE = "This store holds no code index, so it records no modules or commits to look through.";
+
 // ---- relation-kind classifier (for impact + tests-coverage) -------------------
 
 const KINDS = ["imports", "calls", "defines", "tests", "touches", "contains", "inherits", "callsSymbol", "touchesSymbol"];
@@ -1360,7 +1364,13 @@ export function renderTestsFor(graph, ind) {
 }
 
 /** Source modules with no covering test module — a coverage gap view. Test
- *  modules (subjects of test edges, or test-named paths) are excluded. */
+ *  modules (subjects of test edges, or test-named paths) are excluded.
+ *
+ *  "Nothing is uncovered" and "I hold nothing to look at" are opposite
+ *  statements, so the empty survey has to say which one it means: with no
+ *  source module recorded there is no coverage claim to make at all, and the
+ *  full-coverage sentence would be an assertion about a repo this store has
+ *  never seen. */
 export function renderUntested(graph) {
   const covered = new Set();
   const testModules = new Set();
@@ -1368,14 +1378,18 @@ export function renderUntested(graph) {
     covered.add(e.object);
     testModules.add(e.subject);
   }
-  const untested = graph.individuals
-    .filter(
-      (i) =>
-        (i.class || "") === "Module" &&
-        !testModules.has(i.id) &&
-        !isTestPath(String(i.label).toLowerCase()) &&
-        !covered.has(i.id),
-    )
+  const sourceModules = graph.individuals.filter(
+    (i) => (i.class || "") === "Module"
+      && !testModules.has(i.id)
+      && !isTestPath(String(i.label).toLowerCase()),
+  );
+  if (!sourceModules.length) {
+    return moduleCountOf(graph) === 0
+      ? `no modules to check for test coverage in this index. ${NO_CODE_INDEX_NOTE}`
+      : "no source modules to check for test coverage in this index — only test modules are recorded.";
+  }
+  const untested = sourceModules
+    .filter((i) => !covered.has(i.id))
     .map((i) => i.label)
     .sort();
   if (!untested.length) return "every source module has at least one covering test module.";

package/src/domain/game-config.mjs

@@ -90,6 +90,21 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     // this is the one switch that turns that off (visionRadius: Infinity for
     // the food-only belief call) without any new belief machinery.
     foodVisionGated: true,
+    // Whether prey weigh the predator and the crumb in one score instead of
+    // running the evade rung ahead of the forage one. Off by default: strict
+    // priority is what ships, and the blend is the alternative a comparison
+    // run measures against it (scripts/compare-prey-decision.mjs).
+    blendPreyDecision: false,
+    // How much of that score belongs to keeping away from the predator, with
+    // the rest going to closing on food. 1 evades exactly as the priority
+    // chain does, 0 ignores the predator, and the middle takes a crumb that
+    // costs little distance. Read only when blendPreyDecision is on.
+    preyThreatWeight: 0.5,
+    // Whether the town-square lane accepts teaching. Its own knob rather than
+    // a share of the adventure one below: the board's sentence table is a
+    // different vocabulary, and a page checkbox on the town square should not
+    // have to set a key named after another surface.
+    teach: false,
   }),
   guessNumber: Object.freeze({
     defaultLo: 1,
@@ -161,6 +176,9 @@ const MUDIII_KEY_MAP = Object.freeze({
   max_prey_population: "maxPreyPopulation",
   max_food_items: "maxFoodItems",
   food_vision_gated: "foodVisionGated",
+  blend_prey_decision: "blendPreyDecision",
+  prey_threat_weight: "preyThreatWeight",
+  teach: "teach",
 });
 
 const ADVENTURE_KEY_MAP = Object.freeze({

package/src/domain/memory/causal-stability.mjs

@@ -0,0 +1,82 @@
+// memory/causal-stability.mjs — deciding when a replicated tombstone has been
+// held by enough peers to retire.
+//
+// A retraction record and a compaction summary both work by staying put: they
+// carry the ids they suppressed, and any peer that re-delivers one of those ids
+// gets refused. That is what makes a delete survive a sync over a grow-only
+// set. It also means the records accumulate, because nothing yet says when one
+// has done its job.
+//
+// The literature calls the missing rule CAUSAL STABILITY: a record is safe to
+// drop once every replica that could still send a conflicting copy has it. Two
+// inputs, and the mesh has one of them.
+//
+//   - The ROSTER. `node:<joiner> mgx:invitedBy node:<inviter>` is an ordinary
+//     replicated fact, so the set of node ids ever admitted to a world is a
+//     grow-only union every peer computes the same way. `admittedNodes` reads
+//     it. Grow-only is exactly right here: a roster that could shrink would let
+//     a forgotten node's stale copy back in.
+//   - The ACKNOWLEDGEMENT. Nothing yet records that a named node holds a named
+//     record. `stableRecordIds` takes it as an argument rather than inventing
+//     it, and answers "nothing is stable" when it is absent — which is the
+//     current answer, and the safe one.
+//
+// Every rule here errs the same way. Dropping a tombstone one peer short lets
+// that peer's copy resurrect a retracted fact, and that failure is silent,
+// late, and reads as the memory inventing something. Retiring nothing is
+// merely unbounded. So: an empty roster retires nothing, a member with no
+// acknowledgement retires nothing, and an unparseable input retires nothing.
+//
+// Pure: no clock, no counter, no arrival order. The answer is a function of the
+// fact set and the acknowledgement evidence handed in, which is the same
+// invariant every read-time resolver over the store has to meet.
+// docs/references/papers/crdt.md carries the full design and the options it
+// rejected.
+import { INVITED_BY_PREDICATE } from "../p2p/facts.mjs";
+
+/** The node ids a world has ever admitted, from its admission edges. Both ends
+ *  of each edge count: the joiner wrote the edge about itself, and it names the
+ *  node that let it in. Sorted, so two peers holding the same facts hand the
+ *  same roster to the rule below. */
+export function admittedNodes(rows) {
+  const nodes = new Set();
+  for (const row of rows || []) {
+    if (row?.predicate !== INVITED_BY_PREDICATE) continue;
+    if (row.subject) nodes.add(String(row.subject));
+    if (row.object) nodes.add(String(row.object));
+  }
+  return [...nodes].sort();
+}
+
+/** The roster this node has to convince before retiring anything: every
+ *  admitted node except itself. A node holding its own record proves nothing
+ *  about who else still has a copy. */
+export function peersToConvince(roster, self = "") {
+  const me = String(self || "");
+  return (roster || []).map(String).filter((id) => id && id !== me);
+}
+
+/**
+ * Which of `recordIds` every peer on the roster is known to hold.
+ *
+ * `acknowledgedBy(nodeId)` returns the record ids that node is known to hold.
+ * Nothing supplies it in the product yet, so it defaults to knowing nothing and
+ * the answer defaults to the empty set. That default is the gate: this rule
+ * cannot retire anything until something can show a peer holds a record.
+ *
+ * An empty roster answers with nothing too. A store with no admission edges has
+ * not shown it is alone; it has shown it does not know who else is out there,
+ * and a copy of it can be sitting in a closed browser tab.
+ */
+export function stableRecordIds({ recordIds = [], roster = [], self = "", acknowledgedBy = null } = {}) {
+  const peers = peersToConvince(roster, self);
+  if (!peers.length) return [];
+  if (typeof acknowledgedBy !== "function") return [];
+  const held = new Map();
+  for (const peer of peers) {
+    const ids = acknowledgedBy(peer);
+    held.set(peer, new Set([...(ids || [])].map(String)));
+  }
+  const candidates = [...new Set((recordIds || []).map(String).filter(Boolean))].sort();
+  return candidates.filter((id) => peers.every((peer) => held.get(peer).has(id)));
+}

package/src/domain/town-square-world.mjs

@@ -82,6 +82,42 @@ export function oneStepDirectionBetween(fromCell, toCell) {
   return null;
 }
 
+/** The eight points a facing may take, clockwise from north. The four
+ *  cardinals are DIRECTION_DELTA's own keys, and they are the only ones a STEP
+ *  can use — the grid has no diagonal exits. The four intercardinals are
+ *  turn-only, which is what a forty-five degree turn on the spot writes. */
+export const COMPASS_POINTS = Object.freeze([
+  "north", "northeast", "east", "southeast", "south", "southwest", "west", "northwest",
+]);
+
+/** `facing` turned `degrees` clockwise (a negative angle turns the other way),
+ *  landing on one of COMPASS_POINTS. Null when `facing` isn't a compass point
+ *  or the angle isn't a whole multiple of 45, so a caller refuses rather than
+ *  rounding a nonsense turn into a real one. Pure. */
+export function turnedFacing(facing, degrees) {
+  const at = COMPASS_POINTS.indexOf(String(facing ?? ""));
+  if (at < 0) return null;
+  if (!Number.isInteger(degrees) || degrees % 45 !== 0) return null;
+  const steps = degrees / 45;
+  return COMPASS_POINTS[(((at + steps) % 8) + 8) % 8];
+}
+
+/** The compass point directly behind `facing`, or null. Pure. */
+export function reverseFacing(facing) {
+  return turnedFacing(facing, 180);
+}
+
+/** The cell one step `direction` from `cell`, or null when `direction` names
+ *  no cardinal step or `cell` doesn't parse. Bounds and props are NOT checked
+ *  here: whether that cell can actually be entered is the exit table's answer,
+ *  and there is only one of those. Pure. */
+export function stepCellFrom(cell, direction) {
+  const at = parseCellId(cell);
+  const delta = DIRECTION_DELTA[String(direction ?? "")];
+  if (!at || !delta) return null;
+  return cellId(at.x + delta.dx, at.y + delta.dy);
+}
+
 // ---- the prop vocabulary ------------------------------------------------------
 
 /** The closed set of noun stems a prop id may use ("house-1" -> "house"). A

package/src/services/adventure-viz.mjs

@@ -92,7 +92,7 @@
 // an edit implies run through the browser bundle's own `session.applyEdit`
 // (adventure-browser-entry.mjs), never here — this module only renders and
 // reads.
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel, rowsForWorld, wordBeforeCursor } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson, embedScriptText, scenarioLabel, rowsForWorld, wordBeforeCursor, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import { createTicker, createSerialQueue } from "./viz-ticker.mjs";
 import { directedGridLayout } from "./viz-room-graph.mjs";
 import { worldDigestRows, roomAffordances, foldWorldState } from "./adventure.mjs";
@@ -628,7 +628,9 @@ ${THEME_TOKENS_CSS}
   body { margin: 0; background: var(--bg); color: var(--ink); font-family: ${SERIF_STACK}; font-size: 16px; line-height: 1.5; }
   .mono { font-family: ${MONO_STACK}; }
   main { max-width: 920px; margin: 0 auto; padding: 1.4rem 1.2rem 2.2rem; }
+  .visually-hidden { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .7rem; letter-spacing: .12em; text-transform: uppercase; color: var(--gilt); }
+  ${EYEBROW_LINKS_CSS}
   .titlebar { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; flex-wrap: wrap; margin: .3rem 0 1rem; }
   button { font: inherit; color: inherit; background: none; cursor: pointer; }
   button:focus-visible { outline: 2px solid var(--ink); outline-offset: 2px; }
@@ -993,8 +995,9 @@ ${THEME_TOKENS_CSS}
 </head>
 <body>
 <main>
+  <h1 class="visually-hidden">the adventure</h1>
   <div class="titlebar">
-    <div class="eyebrow">tmct &middot; the adventure</div>
+    <div class="eyebrow">${demoEyebrowHtml("adventure", "the adventure")}</div>
     <button id="editModeBtn" type="button" class="mode-toggle" disabled>edit the world</button>
   </div>
   <p class="page-note" id="pageNote">${escapeHtml(scenarioList[0].worldPayload.opening || "")}</p>

package/src/services/chat-page-viz.mjs

@@ -28,7 +28,7 @@
 // input. scripts/build-demo-site.mjs calls it directly and writes the result
 // to public/chat.html, after chat-browser.bundle.js/chat-seed.json already
 // exist (both built earlier in that same script, for the embedded widget).
-import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml } from "./viz-theme.mjs";
+import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
 import {
   SHARE_OVERLAY_CSS, shareOverlayHtml, shareStepStates, activeWaves, offerBlobIn, peerTerm,
   shareMessageFor, replyMessageFor, whatsAppShareUrl, isProbablyMobile, copyTextToClipboard, flashCopyTip,
@@ -498,7 +498,9 @@ ${THEME_TOKENS_CSS}
      get folded onto a second line by a wide one. */
   .topbar { flex: 0 0 auto; display: flex; align-items: center; gap: 1rem; padding: .55rem 1.1rem; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
   .brand { display: flex; align-items: baseline; gap: .55rem; }
+  .visually-hidden { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
   .eyebrow { font-family: ${MONO_STACK}; font-size: .78rem; letter-spacing: .08em; color: var(--muted); }
+  ${EYEBROW_LINKS_CSS}
   .legend { display: flex; gap: .8rem; margin-left: auto; font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); }
   .legend-item { display: inline-flex; align-items: center; gap: .32rem; white-space: nowrap; }
   .dot { width: 7px; height: 7px; border-radius: 50%; display: inline-block; }
@@ -691,9 +693,10 @@ ${SHARE_OVERLAY_CSS}
 <body>
 ${shareOverlayHtml({ withTape: true })}
   <div class="chatCol">
+    <h1 class="visually-hidden">talk to it</h1>
     <header class="topbar">
       <div class="brand">
-        <span class="eyebrow">the-mechanical-code-talker</span>
+        <span class="eyebrow">${demoEyebrowHtml("chat", "chat")}</span>
       </div>
       <div class="chrome">
         <span class="fact-pill" id="factPill" aria-live="polite"