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

package/src/domain/p2p/facts.mjs

@@ -0,0 +1,81 @@
+// domain/p2p/facts.mjs — the small set of new predicates the P2P layer
+// introduces on top of the existing memory store's triple shape, plus pure
+// constructors for each. Every one is a plain add-only fact, replicated the
+// same way any other fact is (appendFacts' own union-by-id behavior) — no
+// new CRDT primitive. Provenance uses the existing `ace:` tag shape
+// (`ace:p2p:<id>@<ts>`) so trust.mjs's own parser reads it with no changes
+// there: stripped of its `ace:` prefix it reads as `p2p:<id>@<ts>`, which
+// parses to { kind: "operator", sessionId: "p2p:<id>", createdAt: <ts> }.
+import { provenanceTagToSource } from "../memory/trust.mjs";
+
+export const WORLD_NAME_PREDICATE = "mgx:worldName";
+export const NODE_NAME_PREDICATE = "mgx:nodeName";
+export const PLAYED_BY_PREDICATE = "mgx:playedBy";
+export const WAVED_PREDICATE = "mgx:waved";
+
+export const P2P_PREDICATES = Object.freeze([
+  WORLD_NAME_PREDICATE,
+  NODE_NAME_PREDICATE,
+  PLAYED_BY_PREDICATE,
+  WAVED_PREDICATE,
+]);
+
+const provenanceFor = (id, timestamp) => `ace:p2p:${id}@${timestamp}`;
+
+export function worldNameFact(worldId, name, timestamp) {
+  return { subject: worldId, predicate: WORLD_NAME_PREDICATE, object: name, provenance: provenanceFor(worldId, timestamp) };
+}
+
+export function nodeNameFact(peerId, name, timestamp) {
+  return { subject: `peer:${peerId}`, predicate: NODE_NAME_PREDICATE, object: name, provenance: provenanceFor(peerId, timestamp) };
+}
+
+export function playedByFact(characterId, peerId, timestamp) {
+  return { subject: characterId, predicate: PLAYED_BY_PREDICATE, object: `peer:${peerId}`, provenance: provenanceFor(characterId, timestamp) };
+}
+
+export function waveFact(characterId, roomId, timestamp) {
+  return { subject: characterId, predicate: WAVED_PREDICATE, object: roomId, provenance: provenanceFor(`${characterId}-${roomId}`, timestamp) };
+}
+
+/** The newest asserted-at timestamp across every " | "-joined segment of a
+ *  fact's provenance — the correct read for "when was this most recently
+ *  true," since a repeat wave unions a fresh tag onto the SAME fact id
+ *  (same subject/predicate/object) rather than minting a new row. Returns
+ *  null if no segment parses to a timestamp at all. */
+export function latestProvenanceTimestamp(provenance) {
+  const tag = String(provenance || "");
+  if (!tag) return null;
+  let latest = null;
+  for (const segment of tag.split(" | ")) {
+    const source = provenanceTagToSource(segment);
+    const at = source?.createdAt ? Date.parse(source.createdAt) : NaN;
+    if (!Number.isNaN(at) && (latest === null || at > latest)) latest = at;
+  }
+  return latest;
+}
+
+/** "Currently waving" is a read-time recency question, never a retraction —
+ *  a wave fact older than the window just stops being read as current, with
+ *  nothing ever deleted from the graph. */
+export function isRecentWave(waveFactRow, nowMs, windowMs = 8000) {
+  const at = latestProvenanceTimestamp(waveFactRow?.provenance);
+  if (at === null) return false;
+  const age = nowMs - at;
+  return age >= 0 && age <= windowMs;
+}
+
+/** The latest-by-timestamp fact for a subject+predicate pair — the "current
+ *  value" read for an add-only, no-retraction fact like a node's own name
+ *  or which peer plays a character (first-claim-wins uses the OLDEST of
+ *  these instead; see playedByFact's own caller for that distinction). */
+export function latestFact(rows, subject, predicate) {
+  let best = null;
+  let bestAt = -Infinity;
+  for (const row of rows) {
+    if (row.subject !== subject || row.predicate !== predicate) continue;
+    const at = latestProvenanceTimestamp(row.provenance) ?? -Infinity;
+    if (at > bestAt) { best = row; bestAt = at; }
+  }
+  return best;
+}

package/src/domain/p2p/peer-id.mjs

@@ -0,0 +1,32 @@
+// domain/p2p/peer-id.mjs — pure id/name generation for the P2P layer. No
+// network, no DOM; safe to import from both a Node test and a browser
+// bundle. World/peer ids are UUIDs, generated client-side and never seen by
+// any server. Display names are two words drawn from the same closed-world
+// lexicon that grounds every taught fact, so a name a player sees on screen
+// is always a real word this build's vocabulary already recognizes.
+import { loadLexicon } from "../grammar/lexicon.mjs";
+
+const fallbackId = (prefix) => `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+export function generatePeerId() {
+  return globalThis.crypto?.randomUUID?.() ?? fallbackId("peer");
+}
+
+export function generateWorldId() {
+  return globalThis.crypto?.randomUUID?.() ?? fallbackId("world");
+}
+
+/** Two distinct words drawn from the lexicon's own noun list — a mnemonic
+ *  label, not a credential. `random` is injectable for deterministic tests;
+ *  defaults to Math.random. Callers add a numeric suffix themselves if a
+ *  live collision turns up among currently-connected peers — this function
+ *  never guesses at uniqueness on its own. */
+export function generateDisplayName(random = Math.random) {
+  const words = [...loadLexicon().nouns.keys()];
+  if (words.length < 2) return "guest-guest";
+  const pick = () => words[Math.floor(random() * words.length)];
+  const first = pick();
+  let second = pick();
+  while (second === first) second = pick();
+  return `${first}-${second}`;
+}

package/src/domain/p2p/provenance-relabel.mjs

@@ -0,0 +1,26 @@
+// domain/p2p/provenance-relabel.mjs — rewrites a fact's outgoing provenance
+// tag before it's broadcast to peers, so "who taught this" reads as a node
+// name rather than a local session id. Only teach/operator-kind tags are
+// touched; a mud world/testimony tag is already attributed to the world or
+// the character that made it, not the person at the keyboard, and rewriting
+// it would lose information rather than add it.
+import { provenanceTagToSource } from "../memory/trust.mjs";
+
+const RELABELED_KINDS = new Set(["teach", "operator"]);
+
+/** `provenance` may already be a " | "-joined union of several tags (the
+ *  same fact taught more than once, from different sources) — relabel each
+ *  segment independently and rejoin, so a segment this peer didn't author
+ *  passes through untouched. */
+export function relabelForBroadcast(provenance, myDisplayName, timestamp) {
+  const tag = String(provenance || "");
+  if (!tag) return tag;
+  return tag
+    .split(" | ")
+    .map((segment) => {
+      const source = provenanceTagToSource(segment);
+      if (!source || !RELABELED_KINDS.has(source.kind)) return segment;
+      return `teach:peer:${myDisplayName}@${timestamp}`;
+    })
+    .join(" | ");
+}

package/src/domain/p2p/sync-filter.mjs

@@ -0,0 +1,31 @@
+// domain/p2p/sync-filter.mjs — which rows of an already-loaded fact store
+// are worth syncing to a new joiner. Every peer's page ships the identical
+// build-time seed, so those rows already share the same content-addressed
+// ids before any network traffic happens; sending them again is pure waste.
+// What actually needs syncing is the delta: whatever a person or a peer
+// actually added since boot.
+import { provenanceTagToSource } from "../memory/trust.mjs";
+
+const CHAT_SYNCABLE_KINDS = new Set(["teach", "operator"]);
+
+/** chat.html: every fact a human (locally or via a peer) actually taught or
+ *  asserted — never a row from the shipped corpus. */
+export function chatSyncableFacts(rows) {
+  return rows.filter((row) => {
+    const source = provenanceTagToSource(row.provenance);
+    return source ? CHAT_SYNCABLE_KINDS.has(source.kind) : false;
+  });
+}
+
+/** mud.html: every fact that isn't part of the bare, unsuffixed world seed —
+ *  a move, a dig, a piece of testimony, or one of the P2P layer's own new
+ *  predicates (world/node names, character claims, waves). `isMudStatePredicate`
+ *  is injected rather than imported from adventure.mjs directly, so this
+ *  module never needs to know that file's internal predicate names — the
+ *  caller (whoever wires the mud room) supplies it, typically
+ *  `adventure.mjs`'s own exported predicate check, extended to also accept
+ *  this module's own P2P predicates via `extraPredicates`. */
+export function mudSyncableFacts(rows, isMudStatePredicate, extraPredicates = []) {
+  const extra = new Set(extraPredicates);
+  return rows.filter((row) => extra.has(row.predicate) || isMudStatePredicate(row.predicate));
+}

package/src/domain/p2p/wire.mjs

@@ -0,0 +1,123 @@
+// domain/p2p/wire.mjs — pure message shapes and blob encoding for the P2P
+// layer. Two kinds of payload: an "invite blob" carried in a URL or pasted
+// by hand (a base64url-encoded JSON envelope holding one SDP string), and
+// plain JSON messages sent over an already-open DataChannel. Nothing here
+// touches the network or WebRTC itself — src/adapters/p2p/webrtc-transport.mjs
+// owns the connection, src/services/p2p-room.mjs owns what these messages mean.
+
+const INVITE_KINDS = new Set(["offer", "reply"]);
+
+function toBase64Url(str) {
+  const b64 = typeof btoa === "function" ? btoa(str) : Buffer.from(str, "utf8").toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function fromBase64Url(b64url) {
+  let b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  while (b64.length % 4) b64 += "=";
+  return typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("utf8");
+}
+
+/** Encode one invite envelope — an offer (from the sharer) or a reply (from
+ *  the joiner) — into a URL-safe string. An offer carries the world id and
+ *  name so a fresh joiner can be shown them before connecting; a reply only
+ *  needs to carry the answer SDP back to the inviter. */
+export function encodeInviteBlob({ kind, sdp, world, worldName }) {
+  if (!INVITE_KINDS.has(kind)) throw new Error(`encodeInviteBlob: unknown kind "${kind}"`);
+  if (typeof sdp !== "string" || !sdp) throw new Error("encodeInviteBlob: sdp is required");
+  const envelope = kind === "offer" ? { v: 1, kind, sdp, world, worldName } : { v: 1, kind, sdp };
+  return toBase64Url(JSON.stringify(envelope));
+}
+
+/** Decode a blob produced by encodeInviteBlob. Never throws — a malformed,
+ *  truncated, or foreign-shaped blob returns { error } instead, so the UI can
+ *  show a specific message ("this invite looks cut short") rather than an
+ *  uncaught exception or a silent no-op. */
+export function decodeInviteBlob(blobString) {
+  if (typeof blobString !== "string" || !blobString.trim()) return { error: "empty" };
+  let json;
+  try {
+    json = fromBase64Url(blobString.trim());
+  } catch {
+    return { error: "truncated" };
+  }
+  let envelope;
+  try {
+    envelope = JSON.parse(json);
+  } catch {
+    return { error: "truncated" };
+  }
+  if (!envelope || typeof envelope !== "object") return { error: "malformed" };
+  if (envelope.v !== 1) return { error: "unsupported-version" };
+  if (!INVITE_KINDS.has(envelope.kind)) return { error: "malformed" };
+  if (typeof envelope.sdp !== "string" || !envelope.sdp) return { error: "malformed" };
+  if (envelope.kind === "offer" && (typeof envelope.world !== "string" || !envelope.world)) {
+    return { error: "malformed" };
+  }
+  return { value: envelope };
+}
+
+const ROOM_MESSAGE_TYPES = new Set([
+  "hello",
+  "peer-list",
+  "intro-offer",
+  "intro-answer",
+  "sync-request",
+  "sync-response",
+  "op",
+]);
+
+export function helloMessage({ peerId, displayName }) {
+  return { type: "hello", peerId, displayName };
+}
+
+export function peerListMessage({ peers }) {
+  return { type: "peer-list", peers };
+}
+
+export function introOfferMessage({ from, to, sdp }) {
+  return { type: "intro-offer", from, to, sdp };
+}
+
+export function introAnswerMessage({ from, to, sdp }) {
+  return { type: "intro-answer", from, to, sdp };
+}
+
+export function syncRequestMessage() {
+  return { type: "sync-request" };
+}
+
+export function syncResponseMessage({ facts }) {
+  return { type: "sync-response", facts };
+}
+
+export function opMessage({ from, facts }) {
+  return { type: "op", from, facts };
+}
+
+/** Structural validation only — the front door for anything a peer sends
+ *  over an open channel. Returns true/false rather than throwing, so a room
+ *  can drop a malformed message from a misbehaving or out-of-date peer
+ *  instead of crashing on it. */
+export function isValidRoomMessage(msg) {
+  if (!msg || typeof msg !== "object" || !ROOM_MESSAGE_TYPES.has(msg.type)) return false;
+  switch (msg.type) {
+    case "hello":
+      return typeof msg.peerId === "string" && msg.peerId.length > 0 && typeof msg.displayName === "string";
+    case "peer-list":
+      return Array.isArray(msg.peers)
+        && msg.peers.every((p) => p && typeof p.peerId === "string" && typeof p.displayName === "string");
+    case "intro-offer":
+    case "intro-answer":
+      return typeof msg.from === "string" && typeof msg.to === "string"
+        && typeof msg.sdp === "string" && msg.sdp.length > 0;
+    case "sync-request":
+      return true;
+    case "sync-response":
+      return Array.isArray(msg.facts);
+    case "op":
+      return typeof msg.from === "string" && Array.isArray(msg.facts);
+    default:
+      return false;
+  }
+}

package/src/domain/reference-pack.mjs

@@ -35,25 +35,49 @@ export function isReferenceIndexEntry(e) {
     && Number.isInteger(e.r) && e.r > 0;
 }
 
-/** A shard row: {term, title, text, summary, url, revid, isa?}. */
+/** A shard row: {term, title, text, summary, url, revid, isa?, source?,
+ *  licence?}. `source`/`licence` are optional per-entry overrides of the
+ *  citation's source name and licence line (renderReferenceAnswer, below) —
+ *  absent on every real Simple English Wikipedia row the build pipeline
+ *  emits, present only on a hand-added synthetic entry (e.g. a demo/test
+ *  term) whose citation must name its OWN real source, not Wikipedia's. */
 export function isReferenceArticleRow(row) {
   if (!row || typeof row !== "object") return false;
   for (const field of ["term", "title", "text", "summary", "url"]) {
     if (typeof row[field] !== "string" || !row[field]) return false;
   }
   if (!Number.isInteger(row.revid) || row.revid <= 0) return false;
-  if (row.isa !== undefined && (typeof row.isa !== "string" || !row.isa)) return false;
+  for (const field of ["isa", "source", "licence"]) {
+    if (row[field] !== undefined && (typeof row[field] !== "string" || !row[field])) return false;
+  }
   return true;
 }
 
+/** The default citation source/licence — every article the build pipeline
+ *  (scripts/fetch-reference-pack.mjs) emits from the pinned Simple English
+ *  Wikipedia dump carries neither field, so this is what renderReferenceAnswer
+ *  falls back to for the overwhelming majority of rows. */
+export const DEFAULT_REFERENCE_SOURCE = "Simple English Wikipedia";
+export const DEFAULT_REFERENCE_LICENCE = "CC BY-SA 4.0";
+
 /** The cited answer for a clean miss the pack could ground: the article's
- *  summary with its title, licence and revision-pinned URL always visible,
- *  then the grain cue. Without the cue a reader has to recognize the source
- *  name to tell this apart from a fact read out of their own graph — both
- *  answer the same "what is X" question in the same voice. */
+ *  summary with its title, licence and source always visible, then the grain
+ *  cue. Without the cue a reader has to recognize the source name to tell
+ *  this apart from a fact read out of their own graph — both answer the same
+ *  "what is X" question in the same voice.
+ *
+ *  The source/licence line reads the article's OWN `source`/`licence` fields
+ *  when present, falling back to the Wikipedia defaults otherwise — every
+ *  real pack row renders byte-identically to before this existed. Wikipedia's
+ *  revision-pinned `?oldid=` query is a convention of that source alone, so it
+ *  is only appended when the article is citing the default source; a
+ *  non-Wikipedia entry's own `url` is shown bare. */
 export function renderReferenceAnswer(term, article) {
+  const source = article.source ?? DEFAULT_REFERENCE_SOURCE;
+  const licence = article.licence ?? DEFAULT_REFERENCE_LICENCE;
+  const url = source === DEFAULT_REFERENCE_SOURCE ? `${article.url}?oldid=${article.revid}` : article.url;
   return `${term} — ${article.summary} (source: reference article "${article.title}", `
-    + `Simple English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`
+    + `${source}, ${licence} — ${url})`
     + ` ${GENERAL_VOCABULARY_CUE}`;
 }
 

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

@@ -122,7 +122,7 @@ export const SEED_TAXONOMY = Object.freeze([
 ]);
 
 export const WORLD_OPENING =
-  "a spider waits in its web; a fly drifts in from the edge of the board. Neither is yours to move — watch, or address one by name in chat.";
+  "a spider waits in its web; a fly drifts in from the edge of the board. Neither is yours to move. Watch, or address one by name in chat.";
 
 /** Every fact row the shipped world source carries: cell typing, grid
  *  adjacency (mgx:has-exit-<direction>), the web block (mgx:in-web) and the

package/src/domain/sprite-map.mjs

@@ -96,9 +96,17 @@ const FURNITURE_SVG =
   + '<rect x="4" y="8" width="3" height="12" fill="currentColor"/>'
   + '<rect x="17" y="8" width="3" height="12" fill="currentColor"/></svg>';
 
+// A drawstring parcel: the plainest "some small thing you could pick up"
+// shape in the set. The body-plus-shackle outline this replaced drew a
+// padlock, which reads as "restricted" rather than "unidentified" — the
+// wrong thing to say about an object whose class simply has no sprite yet.
+// Matches the silhouette data/sprites/portable-icon.toml already draws, so
+// the same class looks the same whichever tier answers.
 const PORTABLE_SVG =
-  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="5" y="9" width="14" height="11" rx="1.5" fill="currentColor"/>'
-  + '<path d="M9 9 V6.5 A3 3 0 0 1 15 6.5 V9" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>';
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 6 C7.5 6 5 9.4 5 13.4 C5 17.7 8.1 20 12 20 '
+  + 'C15.9 20 19 17.7 19 13.4 C19 9.4 16.5 6 12 6 Z" fill="currentColor"/>'
+  + '<path d="M9.4 6.4 C9.9 4.6 10.8 3.4 12 3.4 C13.2 3.4 14.1 4.6 14.6 6.4" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/>'
+  + '<ellipse cx="9.8" cy="11.6" rx="1.6" ry="2.1" fill="currentColor" opacity="0.28"/></svg>';
 
 const PERSON_SVG =
   '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'

package/src/domain/sprite-templates.mjs

@@ -21,12 +21,14 @@
 //     substitution (e.g. `black = "#22201d"`). A value with no entry in that
 //     map is not a match for this template at all — it falls through to a
 //     less specific one, never a guessed/invented substitution.
-//   - a fully-specific hand-authored VARIANT — `{class}-with-{property}-
-//     {value}.toml` (e.g. a hypothetical `dog-with-colour-black.toml`, not
-//     authored this pass) — carries the same `classes` as the class it
-//     specializes, plus a `[match]` table (`property`, `value`) naming the
-//     exact fact it requires, so it outranks the parameterized template
-//     when both would otherwise apply.
+//   - a fully-specific hand-authored VARIANT — carries the same `classes`
+//     as the class it specializes, plus a `[match]` table (`property`,
+//     `value`) naming the exact fact it requires, so it outranks the
+//     parameterized template when both would otherwise apply. The filename
+//     is free-form and reads `{class}-{what it shows}` in practice
+//     (`portrait-round.toml` for mgx:hasProperty = round,
+//     `bear-facing-left.toml` for mgx:faces = left) — the `[match]` table,
+//     never the name, is what selects it.
 //
 // A parameterized template's `[parameters.<name>]` table comes in two
 // shapes, picked by which of `placeholder`/`placeholders` it declares:

package/src/services/adventure-editor.mjs

@@ -281,6 +281,14 @@ export function parseWorldEditorText(text, contextRows = []) {
 
 const tripleKey = (t) => `${t.subject} ${t.predicate} ${t.object}`;
 
+// The three flag predicates the renderer only ever writes a line for when they
+// read "true" ("Basket is a container."). A row saying "false" has no sentence
+// in this vocabulary, so it must not be diffable either — counted as editable
+// while being unrenderable, it sits in the diff's current set, matches nothing
+// the text can say, and gets retracted on the next clean parse: a fact the
+// player never saw, silently deleted by an edit somewhere else in the document.
+const TRUE_ONLY_FLAG_PREDICATES = ["mgx:is-container", "mgx:is-npc", "mgx:is-objective"];
+
 /** Every raw fact row this editor's "other" family (type/exits/container/
  *  puzzle — never placement/openness) is allowed to touch — the closed set
  *  planWorldEditorSync diffs against and the only rows a removal can ever
@@ -290,8 +298,8 @@ export function editableOtherRows(rows) {
     if (SNAPSHOT_RE.test(r.subject)) return false;
     if (r.predicate === "rdf:type") return true;
     if (EXIT_PREDICATE_RE.test(r.predicate)) return true;
-    return ["mgx:is-container", "mgx:is-npc", "mgx:is-objective", "mgx:unlocks-with", "mgx:acts-on-turn", "mgx:acts-toward"]
-      .includes(r.predicate);
+    if (TRUE_ONLY_FLAG_PREDICATES.includes(r.predicate)) return r.object === "true";
+    return ["mgx:unlocks-with", "mgx:acts-on-turn", "mgx:acts-toward"].includes(r.predicate);
   });
 }