@polycode-projects/the-mechanical-code-talker 5.0.5 → 5.0.7

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,
@@ -36,7 +36,7 @@ import {
 import { provBucketFor } from "./ledger-viz.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
 import { sessionLogTimeOfDay, sessionLogHeaderMarkdown, sessionLogTurnMarkdown } from "./session-log-format.mjs";
-import { bandLabelFor, statsSummaryLine, clearSiteAssetCaches, fetchWithProgress, renderStatsPanelInto } from "./memory-panel-viz.mjs";
+import { bandLabelFor, statsSummaryLine, clearSiteAssetCaches, fetchWithProgress, loadSeedPayload, renderStatsPanelInto } from "./memory-panel-viz.mjs";
 
 const DEFAULT_TITLE = "the-mechanical-code-talker — talk to it";
 
@@ -446,7 +446,7 @@ export function transcriptMarkdown(turns, meta, headerMd, turnMd) {
  *  live digest-bank twin (see chat-browser-entry.mjs) rather than to a
  *  client-side digest panel of this page's own; an empty list degrades to the
  *  flat list exactly as before this page could digest at all. */
-export function renderChatHtml({ title = DEFAULT_TITLE, digestStructures = [], seedStamp = "" } = {}) {
+export function renderChatHtml({ title = DEFAULT_TITLE, digestStructures = [], seedStamp = "", seedBytes = 0 } = {}) {
   const digestStructuresJson = JSON.stringify(Array.isArray(digestStructures) ? digestStructures : []);
   const legendHtml = PROV_LEGEND.map(
     ([key, label]) => `<span class="legend-item"><i class="dot dot-${provKey(key)}"></i>${escapeHtml(label)}</span>`,
@@ -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; }
@@ -622,6 +624,15 @@ ${THEME_TOKENS_CSS}
      a pill like its neighbours, with the number itself at reading size. */
   .fact-pill { display: inline-flex; align-items: baseline; gap: .34rem; font-family: ${MONO_STACK}; font-size: .68rem; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); border: 1px solid var(--corpus-t1); border-radius: 99px; padding: .2rem .8rem; background: var(--corpus-soft); white-space: nowrap; }
   .fact-pill .fact-pill-value { font-size: .96rem; letter-spacing: 0; font-variant-numeric: tabular-nums; font-weight: 600; color: var(--ink); }
+  /* While the starter memory streams in, the pill says so and breathes. The
+     graph is a moving state: what it knows now is less than what it will know
+     in a moment, and a question asked mid-load gets answered against what has
+     actually arrived. */
+  .fact-pill[data-state="loading"] { animation: pill-breathe 1.6s ease-in-out infinite; }
+  .fact-pill[data-state="loading"] .fact-pill-value { font-size: .68rem; letter-spacing: .06em; text-transform: uppercase; font-weight: 600; }
+  .fact-pill[data-state="failed"] { border-color: var(--miss-t1, var(--corpus-t1)); }
+  @keyframes pill-breathe { 0%, 100% { opacity: 1; } 50% { opacity: .55; } }
+  @media (prefers-reduced-motion: reduce) { .fact-pill[data-state="loading"] { animation: none; } }
 
   .chrome { display: flex; align-items: center; gap: .4rem; flex-wrap: wrap; }
   .chrome-btn { font-family: ${SERIF_STACK}; font-size: .8rem; color: var(--muted); border: 1px solid var(--line); border-radius: 99px; padding: .22rem .75rem; background: var(--card); text-decoration: none; display: inline-flex; align-items: center; gap: .32rem; white-space: nowrap; line-height: 1.35; }
@@ -691,14 +702,15 @@ ${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"
+        <span class="fact-pill" id="factPill" aria-live="polite" data-state="loading"
           title="every fact this session's memory holds right now — the starter memory it shipped with plus anything you have taught, researched or ingested">
-          <span class="fact-pill-value" id="factPillValue">&mdash;</span> facts
+          <span class="fact-pill-value" id="factPillValue">loading</span><span id="factPillUnit"> starter memory&hellip;</span>
         </span>
         <button type="button" class="state-pill" id="statePill" data-tone="idle"
           title="the shared-world connection; click to open the network panel">
@@ -777,6 +789,7 @@ ${shareOverlayHtml({ withTape: true })}
   const statsSummaryLine = ${statsSummaryLine.toString()};
   const clearSiteAssetCaches = ${clearSiteAssetCaches.toString()};
   const fetchWithProgress = ${fetchWithProgress.toString()};
+  const loadSeedPayload = ${loadSeedPayload.toString()};
   const renderStatsPanelInto = ${renderStatsPanelInto.toString()};
   const createTicker = ${createTicker.toString()};
   const prefersReducedMotion = ${prefersReducedMotion.toString()};
@@ -808,7 +821,9 @@ ${shareOverlayHtml({ withTape: true })}
   const inputEl = el("composerInput");
   const sendBtn = el("composerSend");
   const statusEl = el("status");
+  const factPillEl = el("factPill");
   const factPillValueEl = el("factPillValue");
+  const factPillUnitEl = el("factPillUnit");
   const statsPanelEl = el("statsPanelStats");
   const researchedPanelEl = el("researchedPanel");
   const wikiModeFieldset = el("wikiMode");
@@ -1017,29 +1032,74 @@ ${shareOverlayHtml({ withTape: true })}
   // seed to hash (the desktop shell's own render).
   const SEED_STAMP = ${JSON.stringify(seedStamp)};
   const SEED_QUERY = SEED_STAMP ? "?b=" + SEED_STAMP : "";
+  // The exact byte count of the chat-seed.json this build shipped, measured by
+  // the builder. It is the denominator the progress percentage needs and the
+  // response itself cannot supply: over a compressed transfer Content-Length
+  // names the wire size, while the stream a reader drains yields decompressed
+  // bytes, so dividing one by the other would read past 100% within a second.
+  // Both numbers here are decompressed bytes, so the ratio is a real fraction
+  // of a real file, never an estimate against elapsed time.
+  const SEED_BYTES = ${Number(seedBytes) || 0};
 
   let seedPayload = null;
   let seedFacts = 0;
-  // One retry with a cache-busting query param: a CDN edge can serve a
-  // corrupted or truncated precompressed response (a transient bad cache
-  // entry, not a code defect — real bytes decompress fine, and the same URL
-  // fetched moments later is clean), and JSON.parse throwing is the only
-  // signal of that. The bust param forces a fresh fetch past that one entry.
+  let seedLoadedBytes = 0;
+  let seedTotalBytes = SEED_BYTES;
+  let seedPercentShown = -1;
+
+  /**
+   * What the starter memory is doing right now, published as tmct.seed for the
+   * page's own pill and for anything driving this page:
+   *
+   *   loading   the seed is still coming down (percent, when a real total exists)
+   *   indexing  it arrived and parsed; the session is being opened from it
+   *   ready     the session holds it — a question now grounds against the whole seed
+   *   failed    it did not arrive; this session starts empty, and says so
+   *   skipped   nothing was asked for (ingest's seed toggle, off)
+   *
+   * There is no moment before "ready" that the page refuses to speak: a
+   * question asked mid-load is answered against what the store actually holds
+   * at that moment, which is the open-world assumption doing its job. The
+   * phases exist so the page can SAY the graph is still growing, and so a test
+   * that asserts on seeded content can wait for the seed to be in.
+   */
+  function setSeedPhase(phase, extra) {
+    window.tmct.seed = Object.assign({ state: phase, facts: seedFacts }, extra || {});
+    renderFactPill();
+  }
+  setSeedPhase("loading");
+
+  function noteSeedBytes(loaded, total) {
+    seedLoadedBytes = loaded;
+    seedTotalBytes = total;
+    const percent = seedProgressPercent();
+    // One DOM write per whole percentage point, not one per streamed chunk.
+    if (percent === seedPercentShown) return;
+    seedPercentShown = percent;
+    renderFactPill();
+  }
+
+  /** The seed's real progress, 0-100, or null when no true total is known —
+   *  the pill then shows that it is loading and no number at all, rather than
+   *  a figure inferred from how long it has been going. */
+  function seedProgressPercent() {
+    if (!(seedTotalBytes > 0)) return null;
+    return Math.min(100, Math.floor((seedLoadedBytes / seedTotalBytes) * 100));
+  }
+
   async function fetchSeed() {
-    for (let attempt = 1; attempt <= 2; attempt++) {
-      try {
-        const bust = attempt === 1 ? "" : (SEED_QUERY ? "&" : "?") + "retry=1";
-        const blob = await fetchWithProgress("./chat-seed.json" + SEED_QUERY + bust, (loaded, total) => noteProgress("seed", loaded, total));
-        seedPayload = JSON.parse(await blob.text());
-        seedFacts = (seedPayload.individuals || []).filter((i) => i.class === "Fact").length;
-        return;
-      } catch (err) {
-        if (attempt === 2) {
-          seedPayload = null;
-          console.warn("tmct chat: chat-seed.json unavailable — starting unseeded", err);
-        }
-      }
+    const outcome = await loadSeedPayload(fetchWithProgress, "./chat-seed.json", SEED_QUERY, (loaded, total) => {
+      noteProgress("seed", loaded, total || SEED_BYTES);
+      noteSeedBytes(loaded, total || SEED_BYTES);
+    });
+    seedPayload = outcome.payload;
+    seedFacts = outcome.status.facts;
+    if (outcome.status.state === "failed") {
+      console.error("tmct chat: chat-seed.json unavailable — starting unseeded (" + outcome.status.error + ")");
+      setSeedPhase("failed", { error: outcome.status.error, attempts: outcome.status.attempts });
+      return;
     }
+    setSeedPhase("indexing", { attempts: outcome.status.attempts });
   }
   const cloneSeed = () => {
     if (!seedPayload) return null;
@@ -1151,7 +1211,7 @@ ${shareOverlayHtml({ withTape: true })}
       catch { return; }
     }
     lastStatsTotal = Number(stats.total || 0);
-    factPillValueEl.textContent = lastStatsTotal.toLocaleString();
+    renderFactPill();
     renderStatsPanelInto(statsPanelEl, stats, {
       bandLabel: bandLabelFor,
       onForget: persist ? forgetEverything : null,
@@ -1258,6 +1318,41 @@ ${shareOverlayHtml({ withTape: true })}
     return liveReference === "always" ? "always" : liveReference === "supplement" ? "supplement" : liveReference ? "on" : "off";
   }
 
+  /** The header pill, in whichever of its three states the page is in: the
+   *  starter memory still streaming in, the live fact count once there is one,
+   *  or a starter memory that never arrived. It is the same pill throughout —
+   *  the count it settles on replaces the loading words in place, so a visitor
+   *  watching it sees the memory arrive rather than a separate spinner
+   *  vanishing. */
+  function renderFactPill() {
+    const seedState = window.tmct.seed ? window.tmct.seed.state : "loading";
+    if (seedState === "loading") {
+      const percent = seedProgressPercent();
+      factPillEl.dataset.state = "loading";
+      factPillValueEl.textContent = percent === null ? "loading" : percent + "%";
+      factPillUnitEl.textContent = percent === null ? " starter memory\\u2026" : " of starter memory";
+      return;
+    }
+    // "ready" lands a moment before the first memoryStats read returns, and
+    // there is no count to show until it does. Holding the indexing words over
+    // that gap keeps the pill from flashing a zero it does not mean.
+    if (seedState === "indexing" || (seedState === "ready" && lastStatsTotal === null)) {
+      factPillEl.dataset.state = "loading";
+      factPillValueEl.textContent = "indexing";
+      factPillUnitEl.textContent = " " + seedFacts.toLocaleString() + " facts\\u2026";
+      return;
+    }
+    if (seedState === "failed" && lastStatsTotal === null) {
+      factPillEl.dataset.state = "failed";
+      factPillValueEl.textContent = "no";
+      factPillUnitEl.textContent = " starter memory";
+      return;
+    }
+    factPillEl.dataset.state = seedState === "failed" ? "failed" : "ready";
+    factPillValueEl.textContent = Number(lastStatsTotal || 0).toLocaleString();
+    factPillUnitEl.textContent = " facts";
+  }
+
   function renderStatus() {
     const seedPart = seedPayload
       ? "starter memory: " + seedFacts + " facts"
@@ -2320,6 +2415,9 @@ ${shareOverlayHtml({ withTape: true })}
     } else {
       await newSession();
     }
+    // The session now holds whatever the seed brought, so the phase settles
+    // here rather than when the bytes landed: "ready" means queryable.
+    if (window.tmct.seed.state !== "failed") setSeedPhase("ready");
     const stats = await window.tmct.page.memoryStats(window.tmct.session.memoryDir);
     if (savedRecord) restoredCount = stats.taught.length;
     const restoredNote = savedRecord

package/src/services/chat-session.mjs

@@ -40,6 +40,12 @@ export const SESSION_LOG_DIR = ".tmct";
 /** The base (no-focus) prompt. With a focus set the shell shows `tmct(label)>`. */
 export const PROMPT = "tmct> ";
 
+/** What a teach or a retract carries in a session that keeps nothing (--ephemeral,
+ *  tmct.toml's [graph] read_only, or the "memory" backend). */
+export const DISCARDED_WRITE_NOTE =
+  "(this session keeps nothing — the fact is gone when it ends. Run without --ephemeral, "
+  + "or on a stored backend, to keep it.)";
+
 // ---- repo-root resolution: default the target to the GIT ROOT, not raw cwd ----
 
 /** The git top-level for `cwd`, or null if not in a repo (or git is unavailable).
@@ -142,6 +148,12 @@ export async function createSession({
   // lifetime (four mud.html characters means four sessions, not one session
   // switching identity turn to turn).
   actingSubject,
+  // The session-log filesystem seam: mkdir/createWriteStream, injectable so a
+  // test can exercise the unwritable-log guard by rejecting at the seam
+  // itself rather than by making a real directory unwritable — chmod-based
+  // unwritability is invisible to a process running as root (CI's container
+  // user), which the real filesystem can't be made to enforce portably.
+  logFs = { mkdir, createWriteStream },
   // Marks a world already LIVE for this session, bypassing openAdventure's
   // "play <world>" opener — that opener requires a shipped "player"
   // individual (its own protection against mis-firing on a non-adventure
@@ -250,6 +262,8 @@ export async function createSession({
   // Ephemeral: keep config.graphFile pointing at the READ graph, but divert the
   // write base (repo → logs/memory/sessions) to a throwaway temp dir. The committed
   // target is never touched; the demo's memory simply doesn't persist across runs.
+  // The banner still names the repo the user asked about, not the scratch dir.
+  const readRepo = repo;
   if (ephemeral) repo = await mkdtemp(join(tmpdir(), "tmct-ephemeral-"));
 
   // Load the graph once up front — the banner needs the module count, and focus/`it`
@@ -286,12 +300,28 @@ export async function createSession({
   const sessionId = uuidv7();
   const logDir = join(repo, SESSION_LOG_DIR);
   const sessionsDir = join(repo, SESSIONS_DIR_REL);
-  await mkdir(logDir, { recursive: true });
-  await mkdir(sessionsDir, { recursive: true });
+  // Every session records what it answered, so an unwritable target is the end
+  // of the session. Say so once, in one place, whichever step hits it: the
+  // mkdir, the stream's open, or the header write below.
+  const unwritable = (e) => new Error(
+    `cannot write the session log under ${logDir} (${e?.code || e?.message || e}). `
+    + "Every session records what it answered, so chat needs write access there. "
+    + "Point --repo at a writable directory, or run with --ephemeral to keep the session in a temp dir.",
+  );
+  try {
+    await logFs.mkdir(logDir, { recursive: true });
+    await logFs.mkdir(sessionsDir, { recursive: true });
+  } catch (e) { throw unwritable(e); }
   const logFile = join(logDir, `session-${sessionId}.md`);
   const sidecarFile = join(sessionsDir, `session-${sessionId}.jsonl`);
-  const stream = createWriteStream(logFile, { flags: "a" });
-  const sidecar = createWriteStream(sidecarFile, { flags: "a" });
+  const stream = logFs.createWriteStream(logFile, { flags: "a" });
+  const sidecar = logFs.createWriteStream(sidecarFile, { flags: "a" });
+  // A stream with no "error" listener turns a failed open into an unhandled
+  // 'error' event, which is a raw Node stack trace and a dead process. The
+  // write callbacks below reject with the same error, so the listener only has
+  // to keep the event handled.
+  stream.on("error", () => {});
+  sidecar.on("error", () => {});
   // Awaited writes: each chunk is handed to the OS before the turn completes, so a
   // killed session keeps everything up to the last completed turn — in both files.
   const flush = (s, text) =>
@@ -300,8 +330,14 @@ export async function createSession({
   const writeSidecar = (obj) => flush(sidecar, JSON.stringify(obj) + "\n");
 
   const startIso = new Date().toISOString();
-  await writeLog(sessionLogHeaderMarkdown({ version, sessionId, startedAt: startIso, repo }));
-  await writeSidecar({ type: "session", id: sessionId, started: startIso, repo, tmctVersion: version });
+  try {
+    await writeLog(sessionLogHeaderMarkdown({ version, sessionId, startedAt: startIso, repo }));
+    await writeSidecar({ type: "session", id: sessionId, started: startIso, repo, tmctVersion: version });
+  } catch (e) {
+    stream.destroy();
+    sidecar.destroy();
+    throw unwritable(e);
+  }
 
   // Read-time graph upsert (sessions.mjs): after every turn, the session becomes /
   // stays a first-class Session individual in graph.json (crash-safe: turn n is in
@@ -357,12 +393,20 @@ export async function createSession({
   // entities (the degenerate trap). Both get orienting, non-over-promising banner
   // + greeting messaging rather than a silent dead-end.
   const noCodeGraph = moduleCount === 0;
+  // A discarding session must not say the conversation is kept. Ephemeral
+  // diverts every write to a temp dir and suppresses the graph upsert; the
+  // "memory" backend keeps the store in-process. Both end when the process does.
+  const discardsWrites = ephemeral || backendChoice === "memory";
+  const whereItGoes = discardsWrites
+    ? "nothing is written back — this session's facts and log are dropped when it ends"
+    : `the conversation is remembered to ${DEFAULT_GRAPH_REL} — log ${logFile}`;
   const bannerLines = [
     noCodeGraph
       // No code graph: honest, orienting messaging — never an error before the prompt.
-      ? `tmct chat — ${repo} — no code graph loaded — ${empty ? "starting empty" : "graph has no code entities"}; ` +
-        `the conversation is remembered to ${DEFAULT_GRAPH_REL} — log ${logFile}`
-      : `tmct chat — ${repo} — ${moduleCount} module(s) — log ${logFile}`,
+      ? `tmct chat — ${readRepo} — no code graph loaded — ${empty ? "starting empty" : "graph has no code entities"}; ` +
+        `${whereItGoes}`
+      : `tmct chat — ${readRepo} — ${moduleCount} module(s) — `
+        + (discardsWrites ? `${whereItGoes}` : `log ${logFile}`),
     // the honest seed line appears ONLY on the run that actually seeded — the count
     // is the TOTAL appended, split into the curated SEON ontology + the ConceptNet band
     // (+ any other active extension bundle, e.g. an activated tier-2 corpus).
@@ -429,7 +473,13 @@ export async function createSession({
         turns += 1;
         return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, prompt: promptFor(focus) };
       }
-      const { answer, record, focus: nextFocus, last: nextLast, end, narrate: nextNarrate, liveReference: nextLiveReference } = result;
+      const { record, focus: nextFocus, last: nextLast, end, narrate: nextNarrate, liveReference: nextLiveReference } = result;
+      // "noted — remembered" reports a durable write. In a session that keeps
+      // nothing it is the last word on a fact that dies with the process, so
+      // say where the fact actually went.
+      const answer = discardsWrites && (record.via === "assert" || record.via === "retract")
+        ? `${result.answer}\n${DISCARDED_WRITE_NOTE}`
+        : result.answer;
       focus = nextFocus;
       last = nextLast;
       if ("planState" in result) planState = result.planState;