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

package/src/surfaces/web/mud-browser-entry.mjs

@@ -1,11 +1,13 @@
-// mud-browser-entry.mjs — the esbuild entry for mud.html's four-character,
+// mud-browser-entry.mjs — the esbuild entry for mud.html's multi-character,
 // one-shared-world browser session (public/mud-browser.bundle.js), mirroring
 // adventure-browser-entry.mjs's own session-factory shape. The difference is
 // the whole point of the mud demo: adventure-browser-entry.mjs drives ONE
-// player through one world; this file drives FOUR independent characters
-// through the SAME live world, over the SAME memoryDir.
+// player through one world; this file drives SEVERAL independent characters
+// through the SAME live world, over the SAME memoryDir. Which of the world's
+// animals are played is the caller's choice (pickMudRoster draws them fresh
+// each reset), never a fixed pair baked in here.
 //
-// What's shared across all four characters, and why: the store itself
+// What's shared across every character, and why: the store itself
 // (memoryDir) — mole-1's dig must be visible to vole-1's very next look — and
 // ONE planHolder.state, seeded once as "mud-garden is already live" the same
 // way adventure-browser-entry.mjs seeds it, since "is the world open" is a
@@ -22,41 +24,52 @@
 // page's chat dock); `autoplayTick(k)` runs mud-turn.mjs's runMudTurn — one
 // whole scripted turn (investigate, walk toward known food, dig at the
 // edge). The caller (mud-viz.mjs's own inlined script) is responsible for
-// SERIALIZING ticks across the four characters when more than one window is
+// SERIALIZING ticks across the characters when more than one window is
 // auto-playing at once — this file makes no ordering promise between two
 // concurrent calls into the same memoryDir, the same way two callers writing
 // into any shared store concurrently would need their own queue.
 import { runTurn } from "../../services/chat.mjs";
-import { createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows } from "../../adapters/memory/core.mjs";
+import {
+  createInMemoryStore, appendFacts, appendRule, loadMemory, readFactRows, removeFacts,
+} from "../../adapters/memory/core.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import {
   foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
   personKnowledgeLines, personKnownFoodLines,
+  diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
+  roomKindOf, isMudStatePredicate,
 } from "../../services/adventure.mjs";
+import { waveFact, playedByFact, P2P_PREDICATES } from "../../domain/p2p/facts.mjs";
+import { relatedForTerm } from "../../domain/skos-view.mjs";
 import { runMudTurn } from "../../services/mud-turn.mjs";
+import { parseMudEditorText, planMudEditorSync } from "../../services/mud-editor.mjs";
+import { mudSpeciesOf } from "../../domain/game-config.mjs";
 import { worldProvenanceTag } from "../../domain/worlds-pack.mjs";
 import { resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain } from "../../domain/sprite-map.mjs";
 import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
 
-/** A live, shared mud world four characters can each act in. `worldPayload`
+/** A live, shared mud world several characters can each act in. `worldPayload`
  *  is `{ name, facts, rules, opening }` — the same shape adventure-browser-
  *  entry.mjs's own worldPayload takes, read once at build time through the
  *  real Node worlds-pack provider (see mud-viz.mjs's header for why: the
  *  world's canonical source is a Node-only gzipped JSONL shard the browser
- *  cannot read). `characters` is the roster this page drives (e.g.
- *  `["mole-1", "vole-1", "badger-1", "groundhog-1"]`) — every character
- *  already placed by the world's own seed facts.
+ *  cannot read). `characters` is the roster this page drives (e.g. the two
+ *  ids pickMudRoster drew this reset). The world is opened for exactly that
+ *  list (worldFactsForCast, below): more animals than mud-garden hand-authors
+ *  are minted, fewer leaves the ones nobody is playing out of the world
+ *  altogether.
  *
  *  Returns `{ memoryDir, windows, snapshot }`. `windows` is a plain object
  *  keyed by character id, each value `{ character, turn, autoplayTick,
- *  visitedRoomIds }`. `snapshot()` is the one OMNISCIENT read this module
- *  exposes — the central world map's own data source, never a per-window
- *  one. */
+ *  visitedRoomIds, turnsTaken, isOutOfPlay, outOfPlayReason }`. `snapshot()` is
+ *  the one OMNISCIENT read this module exposes — the central world map's own
+ *  data source, never a per-window one. */
 export async function createMudSession(worldPayload, { characters = [] } = {}) {
   const memoryDir = createInMemoryStore();
   const tag = worldProvenanceTag(worldPayload.name);
-  await appendFacts(memoryDir, worldPayload.facts.map((f) => ({
+  const seedFacts = worldFactsForCast(worldPayload.facts, characters);
+  await appendFacts(memoryDir, seedFacts.map((f) => ({
     subject: f.subject, predicate: f.predicate, object: f.object, provenance: tag,
   })));
   for (const rule of worldPayload.rules) {
@@ -70,11 +83,19 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
   // shipped "player" individual mud-garden deliberately has none of).
   const planHolder = { state: { adventure: { world: worldPayload.name } } };
   const graph = parseEntities({ individuals: [], objectProperties: [] });
+  // The world's own minted ids ("groundhog-1", "carrot-2") are declared as
+  // vocabulary inside the adventure lane itself, for the length of one world
+  // command — see adventure.mjs's own worldLexicon. This page hands over the
+  // plain core lexicon and lets the lane do it.
   const lexicon = loadLexicon();
 
-  async function roomOf(character) {
+  async function readWorld() {
     const rows = readFactRows(await loadMemory(memoryDir));
-    const state = foldWorldState(worldActionRows(rows));
+    return { rows, state: foldWorldState(worldActionRows(rows)) };
+  }
+
+  async function roomOf(character) {
+    const { state } = await readWorld();
     return state.placements.get(character)?.object ?? null;
   }
 
@@ -88,6 +109,11 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
     let focus = null;
     let last = null;
     const visitedRoomIds = new Set();
+    // This character's OWN turns, not the page's shared tick counter: two
+    // windows playing at different speeds, or one paused while the other
+    // runs, have genuinely different counts, and showing the shared one under
+    // both animals says something untrue about each.
+    let turnsTaken = 0;
     const startRoom = await roomOf(character);
     if (startRoom) visitedRoomIds.add(startRoom);
 
@@ -115,6 +141,7 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
         focus = result.focus;
         last = result.last;
         if ("planState" in result) planHolder.state = result.planState;
+        turnsTaken += 1;
         const here = await roomOf(character);
         if (here) visitedRoomIds.add(here);
         return { answer: result.answer, end: Boolean(result.end) };
@@ -130,6 +157,9 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
        *  dig-flourish triggers straight off `actions`. */
       async autoplayTick(k) {
         const result = await runMudTurn(character, { world: worldPayload.name, memoryDir, env: {}, graph, k });
+        // A turn that ended in starvation still happened, and still counts —
+        // only a DECLINED turn (no room to act in) leaves the tally alone.
+        if (result.room) turnsTaken += 1;
         if (result.roomAfter) visitedRoomIds.add(result.roomAfter);
         return result;
       },
@@ -137,6 +167,26 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
       /** This character's own discovered-room history — real fog of war,
        *  never merged with a sibling window's. */
       visitedRoomIds: () => [...visitedRoomIds],
+
+      /** How many turns THIS character has taken — its own scripted ticks and
+       *  its own typed commands, and nobody else's. */
+      turnsTaken: () => turnsTaken,
+
+      /** True once this character's run has ended — a predator ate it, or its
+       *  mass ran out. It takes no further turns and every command it gives
+       *  declines, so a caller can stop ticking it and say so on screen. */
+      async isOutOfPlay() {
+        const { state } = await readWorld();
+        return isOutOfPlay(state, character);
+      },
+
+      /** WHICH ending it was — "eaten" or "starved" — or null while it is still
+       *  playing. The two read nothing alike on screen, so a pane showing a
+       *  fate needs the reason, not just the fact. */
+      async outOfPlayReason() {
+        const { state } = await readWorld();
+        return outOfPlayReasonOf(state, character);
+      },
     };
   }
 
@@ -150,7 +200,155 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
     return { rows, state };
   }
 
-  return { memoryDir, windows, snapshot };
+  /** The world editor's own store sync: parse `text` (mud-editor.mjs's own
+   *  parseMudEditorText), plan the writes it implies, and apply them — scoped to
+   *  THIS world's provenance tag only. Returns `{ unrecognized, added, removed }`.
+   *
+   *  Two things this does that a fresh, unplayed world would not need.
+   *  Retractions run only when the WHOLE document parsed cleanly, so a half-typed
+   *  line is never read as "this fact is gone". And a fold-versioned write
+   *  (a placement, an openness, a mass) is stamped `subject@turnN` at one past
+   *  the world's own turn count, exactly the way every in-game action's commit
+   *  writes: the fold takes the newest turn, so an untagged row would sit at turn
+   *  zero and lose to the snapshot the last played turn already left behind —
+   *  the edit would look accepted and change nothing. */
+  async function applyEdit(text) {
+    const allRows = readFactRows(await loadMemory(memoryDir));
+    const worldRows = allRows.filter((r) => typeof r.provenance === "string" && r.provenance.indexOf(tag) === 0);
+    const state = foldWorldState(worldRows);
+    const { triples, unrecognized } = parseMudEditorText(text);
+    const { toAppend, toRemoveIds } = planMudEditorSync(worldRows, state, triples);
+    const editTurn = state.turnCount + 1;
+    if (toAppend.length) {
+      await appendFacts(memoryDir, toAppend.map((f) => ({
+        subject: f.kind === "other" ? f.subject : `${f.subject}@turn${editTurn}`,
+        predicate: f.predicate,
+        object: f.object,
+        provenance: f.kind === "other" ? tag : `${tag}:turn${editTurn}`,
+      })));
+    }
+    const removed = unrecognized.length === 0 && toRemoveIds.length
+      ? (await removeFacts(memoryDir, toRemoveIds)).removed.length
+      : 0;
+    return { unrecognized, added: toAppend.length, removed };
+  }
+
+  // Wall-clock resolution is 1ms, and both writers below are content-addressed
+  // by (subject, predicate, object) — a second wave from the same character in
+  // the same room is the SAME fact id, so it only registers as a change if its
+  // provenance tag differs. Two writes inside one tick would share a timestamp,
+  // share a tag, and the second would silently vanish. p2p-room.mjs nudges its
+  // own clock for exactly this reason; this is the same nudge for the writes
+  // that happen before a room exists.
+  let lastWriteMs = -Infinity;
+  function stampNow() {
+    const nudged = Math.max(Date.now(), lastWriteMs + 1);
+    lastWriteMs = nudged;
+    return new Date(nudged).toISOString();
+  }
+
+  /** `character` waves in whichever room it currently stands in — an ordinary
+   *  add-only fact, so a page with no network renders it exactly like a page
+   *  sharing the world with three others. Returns the room waved in, or null
+   *  when the character stands nowhere (out of play). Nothing is ever
+   *  retracted: "currently waving" is a recency read over this fact's own
+   *  provenance timestamp. */
+  async function wave(character) {
+    const here = await roomOf(character);
+    if (!here) return null;
+    await appendFacts(memoryDir, [waveFact(character, here, stampNow())]);
+    return here;
+  }
+
+  /** Claim `characters` for `peerId` — one add-only `mgx:playedBy` fact each.
+   *  Claims never overwrite: two peers claiming the same animal both write,
+   *  and every reader settles it the same way by taking the oldest claim. */
+  async function claimCharacters(characters, peerId) {
+    const at = stampNow();
+    const claims = (characters || []).map((character) => playedByFact(character, peerId, at));
+    if (claims.length) await appendFacts(memoryDir, claims);
+    return claims.length;
+  }
+
+  return { memoryDir, windows, snapshot, applyEdit, wave, claimCharacters };
+}
+
+/** `count` entries drawn at random from `roster`, in random order, without
+ *  repeats — which animals this visit is played with. Called fresh on every
+ *  reset, so the same page gives a different pairing each time and the world
+ *  never reads as one fixed cast. `random` is injectable so a caller can pin
+ *  the draw; the world engine itself still writes no randomness anywhere, and
+ *  this picks the players, never anything the world folds. */
+export function pickMudRoster(roster, { count = 2, random = Math.random } = {}) {
+  const pool = [...(roster || [])];
+  for (let i = pool.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(random() * (i + 1));
+    [pool[i], pool[j]] = [pool[j], pool[i]];
+  }
+  return pool.slice(0, Math.min(count, pool.length));
+}
+
+/** `roster` grown to `size` ids by numbering more instances of the species it
+ *  already names — "mole-2", "vole-3" — so a page can cast more animals than
+ *  the world hand-authors individuals for. The authored ids come first and
+ *  keep their own numbers; a minted id never collides with one. The species
+ *  round-robins, so the extras stay spread across the roster's animals rather
+ *  than piling ten moles into the garden. Pure. */
+export function expandMudRoster(roster, size) {
+  const ids = [...(roster || [])];
+  if (!ids.length) return ids;
+  const used = new Set(ids);
+  const species = [...new Set(ids.map(mudSpeciesOf))];
+  for (let instance = 1; ids.length < size; instance += 1) {
+    for (const kind of species) {
+      if (ids.length >= size) break;
+      const id = `${kind}-${instance}`;
+      if (used.has(id)) continue;
+      used.add(id);
+      ids.push(id);
+    }
+  }
+  return ids;
+}
+
+/** The facts that place `characters` the world's own `facts` never placed —
+ *  each one copied wholesale from an authored individual of the same species,
+ *  with the subject swapped. Copying rather than composing is what keeps a
+ *  minted animal an ORDINARY one: it arrives with the same type, the same
+ *  starting room and the same mass mud-garden gives its own mole, and it
+ *  picks up anything a later edit adds to that mole for free. A species the
+ *  world authors nobody of is skipped rather than guessed at. Pure. */
+export function mintedCharacterFacts(facts, characters) {
+  const rows = facts || [];
+  const placedIn = (subject) => rows.some((f) => f.subject === subject && f.predicate === "mgx:currently-in");
+  const minted = [];
+  for (const character of characters || []) {
+    if (placedIn(character) || minted.some((f) => f.subject === character)) continue;
+    const species = mudSpeciesOf(character);
+    const template = rows.find((f) => f.predicate === "mgx:currently-in" && mudSpeciesOf(f.subject) === species);
+    if (!template) continue;
+    for (const fact of rows) {
+      if (fact.subject !== template.subject) continue;
+      minted.push({ subject: character, predicate: fact.predicate, object: fact.object });
+    }
+  }
+  return minted;
+}
+
+/** `facts` opened for exactly `characters`: the playable animals nobody is
+ *  playing are left out of the world, and the characters the world authors
+ *  nobody for are minted in. The first half is what keeps the cast honest —
+ *  an authored animal nobody drives stands in its starting room for the whole
+ *  run, shows up in every room description and answers when talked to, all
+ *  without ever taking a turn. The fox, a den's resident mouse and every prop
+ *  are untouched: they are the world, not the cast. Pure. */
+export function worldFactsForCast(facts, characters) {
+  const rows = facts || [];
+  const cast = new Set(characters || []);
+  const uncast = new Set(rows
+    .filter((f) => f.predicate === "rdf:type" && f.object === "adventurer" && !cast.has(f.subject))
+    .map((f) => f.subject));
+  return rows.filter((f) => !uncast.has(f.subject)).concat(mintedCharacterFacts(rows, characters));
 }
 
 // Re-exported so mud-viz.mjs's own inlined script never duplicates sprite
@@ -158,7 +356,17 @@ export async function createMudSession(worldPayload, { characters = [] } = {}) {
 // chat pills already need — the same reach-through-the-global posture
 // adventure-browser-entry.mjs's own globalThis.tmctAdventure takes.
 globalThis.tmctMud = {
-  createMudSession, resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain, resolveSpriteAsset,
+  createMudSession, pickMudRoster, expandMudRoster, mintedCharacterFacts, worldFactsForCast,
+  resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain, resolveSpriteAsset,
   foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
   personKnowledgeLines, personKnownFoodLines,
+  diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
+  roomKindOf,
+  // The shared-world reach-throughs: which predicates carry live world state,
+  // and the P2P layer's own four. mud.html hands both to `mudSyncableFacts`,
+  // which is written to take the check rather than import the engine itself.
+  isMudStatePredicate, P2P_PREDICATES,
+  // The edit mode's own reach-throughs: the SKOS neighbourhood and the is-a
+  // chain its cursor-suggestion pills read, neither of which is splice-safe.
+  relatedForTerm,
 };

package/src/surfaces/web/p2p-browser-entry.mjs

@@ -0,0 +1,39 @@
+// p2p-browser-entry.mjs — the esbuild entry for public/vendor/p2p.js, the ONE
+// shared networking asset every page that joins a world imports at runtime.
+// Same arrangement as ./vendor/wink.js: an ESM module, same-origin, one cached
+// copy site-wide, imported dynamically by a page's own inline script rather
+// than bundled into each page's engine bundle.
+//
+// A page imports it LAZILY, off the boot path, so networking nobody asked for
+// never delays a first answer. The service worker precaches it anyway, which
+// is what lets two laptops on a LAN with no internet still invite each other
+// on a return visit.
+//
+// This module re-exports only; every rule lives in the layers below. The
+// memory core rides along because p2p-room.mjs merges through appendFacts, and
+// this asset therefore holds its own copy of that code separate from the page's
+// engine bundle. The two copies operate on the SAME handle object the page
+// passes in, and appendFacts rebuilds its lookup index from the payload on
+// every mutation, so neither copy can read the other's stale index.
+export {
+  createP2pRoom,
+  PRESENCE_SCOPE,
+  ROOM_IDLE,
+  ROOM_SHARING,
+  ROOM_ANSWERING,
+  ROOM_CONNECTING,
+  ROOM_CONNECTED,
+  ROOM_FAILED,
+} from "../../services/p2p-room.mjs";
+export { createTransport } from "../../adapters/p2p/webrtc-transport.mjs";
+export { generatePeerId, generateWorldId, generateDisplayName } from "../../domain/p2p/peer-id.mjs";
+export { chatSyncableFacts, mudSyncableFacts } from "../../domain/p2p/sync-filter.mjs";
+export { decodeInviteBlob, encodeInviteBlob } from "../../domain/p2p/wire.mjs";
+export {
+  latestProvenanceTimestamp,
+  isRecentWave,
+  latestFact,
+  NODE_NAME_PREDICATE,
+  WORLD_NAME_PREDICATE,
+  WAVED_PREDICATE,
+} from "../../domain/p2p/facts.mjs";