@polycode-projects/the-mechanical-code-talker 4.1.0 → 4.1.1

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

@@ -48,6 +48,8 @@ import { worldProvenanceTag } from "../../domain/worlds-pack.mjs";
 import { resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain } from "../../domain/sprite-map.mjs";
 import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /** A live, shared mud world several characters can each act in. `worldPayload`
  *  is `{ name, facts, rules, opening }` — the same shape adventure-browser-
@@ -60,7 +62,7 @@ import { createTurnSession } from "./turn-session.mjs";
  *  are minted, fewer leaves the ones nobody is playing out of the world
  *  altogether.
  *
- *  Returns `{ memoryDir, windows, snapshot }`. `windows` is a plain object
+ *  Returns `{ memoryDir, graph, windows, snapshot }`. `windows` is a plain object
  *  keyed by character id, each value `{ character, turn, autoplayTick,
  *  visitedRoomIds, turnsTaken, isOutOfPlay, outOfPlayReason }`. `snapshot()` is
  *  the one OMNISCIENT read this module exposes — the central world map's own
@@ -270,7 +272,7 @@ export async function createMudSession(worldPayload, { characters = [], epoch =
     return claims.length;
   }
 
-  return { memoryDir, windows, snapshot, applyEdit, wave, claimCharacters };
+  return { memoryDir, graph, windows, snapshot, applyEdit, wave, claimCharacters };
 }
 
 /** `count` entries drawn at random from `roster`, in random order, without
@@ -351,22 +353,41 @@ export function worldFactsForCast(facts, characters) {
   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
-// resolution or the digest/affordance/knowledge readers its room view and
-// chat pills already need — the same reach-through-the-global posture
-// adventure-browser-entry.mjs's own globalThis.tmctAdventure takes.
-globalThis.tmctMud = {
-  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,
-};
+// Several characters, one world, so a line has to say who is speaking:
+// `tmct.turn(line, { as: "mole-1" })` routes to that character's own window,
+// which owns its private focus/last and its own fog of war. Everything else a
+// window does — a scripted autoplayTick, its visited rooms, whether it is
+// still in play — stays on `tmct.session.windows[id]`, because those are
+// per-character state rather than questions anyone could ask in words.
+//
+// `tmct.page` keeps the sprite resolution and the digest/affordance/knowledge
+// readers the room view and chat pills render from, the roster helpers that
+// decide which animals this visit is played with, the two predicate lists the
+// P2P layer checks against, and the SKOS neighbourhood behind the edit mode's
+// cursor pills — none of which is `.toString()`-splice-safe.
+publishTmctSurface({
+  open: createMudSession,
+  turn: (line, options, session) => {
+    const character = options?.as;
+    const characterWindow = character ? session.windows[character] : null;
+    if (!characterWindow) {
+      return {
+        answer: `say which character is speaking — tmct.turn(line, { as: "${Object.keys(session.windows)[0] || "mole-1"}" })`,
+        end: false, record: null, plan: null, research: null,
+      };
+    }
+    return characterWindow.turn(line);
+  },
+  ask: graphAsk,
+  plan: enginePlan,
+  page: {
+    pickMudRoster, expandMudRoster, mintedCharacterFacts, worldFactsForCast,
+    resolveSpriteForClass, SPRITE_REGISTRY, classAncestorChain, resolveSpriteAsset,
+    foldWorldState, worldActionRows, worldDigestRows, roomAffordances,
+    personKnowledgeLines, personKnownFoodLines,
+    diggableDirections, castInRoom, displayNameOf, isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase,
+    roomKindOf,
+    isMudStatePredicate, P2P_PREDICATES,
+    relatedForTerm,
+  },
+});

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

@@ -34,7 +34,7 @@ import { planToPddl } from "../../services/plan-pddl.mjs";
 import { createTurnSession } from "./turn-session.mjs";
 // Re-exported so the page can register a CDN-loaded wink-nlp pair before the
 // first teach, the same seam chat-browser-entry.mjs exposes as
-// tmctChat.registerWinkModel — see wink-model.mjs's own header. The hanoi
+// tmct.page.registerWinkModel — see wink-model.mjs's own header. The hanoi
 // lesson's own "moving a disk onto a target makes the disk rest on the
 // target" sentence needs a REAL lemmatiser (verbLemma reduces "moving" to
 // "move" to match the taught "move onto" action family) — without it, that
@@ -44,10 +44,12 @@ import { createTurnSession } from "./turn-session.mjs";
 // model because their own gameplay never asks a taught rule to reduce a
 // verb; the hanoi lesson is the first live session here that does.
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /** A live in-memory towers-of-hanoi session this page's live controls AND
- *  chat dock can both drive. Returns `{ memoryDir, sessionId, diskCount,
- *  maxDepth, plan, turn }`. `plan` is the puzzle's freshly solved plan (the
+ *  chat dock can both drive. Returns `{ memoryDir, sessionId, graph,
+ *  diskCount, maxDepth, plan, turn }`. `plan` is the puzzle's freshly solved plan (the
  *  same shape chat.mjs's planLaneAnswer returns, enriched with
  *  `becauseText` — see `turn()` below), or null when `maxDepth` was too low
  *  to find one (an honest miss, not an error: `turn()`'s own answer text
@@ -84,13 +86,18 @@ export async function createPlanSession({ diskCount = 3, maxDepth = DEFAULT_GAME
     if (r.plan) plan = r.plan;
   }
 
-  return { memoryDir, sessionId, diskCount, maxDepth, plan, turn: session.turn };
+  return { memoryDir, sessionId, graph, diskCount, maxDepth, plan, turn: session.turn };
 }
 
-// Re-exported so the page's own rendering script (plan-viz.mjs's inlined
-// script) never has to duplicate board layout or PDDL/OWL-RDF formatting —
-// the same posture adventure-browser-entry.mjs/spider-fly-browser-entry.mjs
-// take re-exporting their own engines' pure helpers.
-globalThis.tmctPlan = {
-  createPlanSession, computeBlocksLayout, planToPageData, renderInputsFromPlan, planToPddl, registerWinkModel,
-};
+// `tmct.page` keeps the board layout and the PDDL/OWL-RDF formatting the
+// page's own script draws with, plus the wink seam the hanoi lesson needs
+// registered before its first teach. Note that `tmct.plan(...)` here is the
+// CAPABILITY planner, not the puzzle solver: a typed "solve it" is a
+// conversational turn like any other, so the page reaches the hanoi plan
+// through `tmct.turn("solve it", { maxDepth })` and reads `.plan` off it.
+publishTmctSurface({
+  open: createPlanSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: { computeBlocksLayout, planToPageData, renderInputsFromPlan, planToPddl, registerWinkModel },
+});

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

@@ -39,6 +39,8 @@ import { groundTextToFacts } from "./ingest-browser-entry.mjs";
 import { openPersistedStore } from "./idb-persist.mjs";
 import { digestTermFromPayloadBrowser } from "./digest-client.mjs";
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { enginePlan } from "./engine-surface.mjs";
 import { exportFactsJsonl } from "./memory-stats.mjs";
 
 // The Fact individual's first-write-wins timestamp, read straight off the
@@ -247,6 +249,7 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
 
   return {
     memoryDir,
+    graph,
     chatSessionId,
     ingestSessionId,
     sessionIds,
@@ -327,8 +330,22 @@ export function createResearchSession({ seedPayload = null, vocabSeeded = false,
   };
 }
 
-globalThis.tmctResearch = {
-  createResearchSession, researchSnapshot, exportFactsJsonl,
-  registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider,
-  normFactTerm, vocabExampleHint, openPersistedStore,
-};
+// This page's ask is already source-scoped: `tmct.ask(q, { sources })` keeps
+// the checked source keys and runs the same factAnswer/factReadBack cascade
+// the ledger dock runs, so a visitor can see the answer change as they tick
+// sources off. `tmct.page` keeps the provider and wink seams the page
+// registers, the run snapshot its timeline reads, its persisted store and its
+// JSONL export.
+publishTmctSurface({
+  open: createResearchSession,
+  ask: async (request, options, session) => {
+    const { text, miss } = await session.ask(request, options);
+    return { answer: text, data: null, miss };
+  },
+  plan: enginePlan,
+  page: {
+    researchSnapshot, exportFactsJsonl,
+    registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider,
+    normFactTerm, vocabExampleHint, openPersistedStore,
+  },
+});

package/src/surfaces/web/spider-fly-browser-entry.mjs

@@ -44,6 +44,8 @@
 // them back (hand-written pathfinding over has-exit-* facts, not the taught
 // action-rule DSL), so nothing here depends on them being loaded.
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import {
   createInMemoryStore, normFactTerm, appendFacts, loadMemory, readFactRows,
@@ -137,6 +139,16 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
     initial: { turn: 0, agents: initialAgents, activeWebs: [] },
     taxonomyRows,
 
+    /** The board as a graph, as of the last refresh. Every tick moves the
+     *  pieces, so a caller putting a question to it calls `refreshGraph()`
+     *  first — which is exactly what `turn()` below already does. */
+    get graph() { return graph; },
+
+    /** Rebuild the board graph from the store's current rows. Exposed so a
+     *  question asked outside the chat dock (tmct.ask) reads this turn's
+     *  positions and not last turn's, the same way a typed one does. */
+    refreshGraph: refreshWorldGraph,
+
     /** Run one real engine turn directly. Returns spider-fly.mjs's own
      *  { turn, agents, ecology } shape unmodified. */
     async tick() {
@@ -189,16 +201,23 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
   };
 }
 
-// cellId/parseCellId/DIRECTION_DELTA/visibleCells/DEFAULT_VISION_RADIUS are
-// re-exported so the page's own rendering script (spider-fly-viz.mjs) never
-// has to duplicate grid geometry or the vision-radius default: reconstructing
-// a spider's remaining silk-thread path from its returned direction list, and
-// computing the POV overlay's visible-cell mask, both need them.
-// pillsForSpiderFly/oneStepDirectionBetween are re-exported so the same page
-// can build its own dynamic deception-pill container without duplicating
-// spider-fly-turn.mjs's own pill logic.
-globalThis.tmctSpiderFly = {
-  createSpiderFlySession, normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
-  cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
-  pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG, registerWinkModel,
-};
+// `tmct.page` is grid geometry and sprite resolution — the two things on this
+// page the engine has no plain-English form for. Reconstructing a spider's
+// remaining silk-thread path from its returned direction list and masking the
+// POV overlay's visible cells both need the raw cell math; the deception pills
+// need spider-fly-turn.mjs's own pill logic.
+publishTmctSurface({
+  open: createSpiderFlySession,
+  // The board moves every tick, so a question rebuilds the graph first —
+  // the same refresh a typed turn does before it dispatches.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
+  plan: enginePlan,
+  page: {
+    normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
+    cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
+    pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG, registerWinkModel,
+  },
+});

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

@@ -25,9 +25,11 @@ import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { SPRITE_FACTS_PROVENANCE } from "../../domain/sprite-facts.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /** A live in-memory chat session seeded with the embedded sprite-facts rows.
- *  Returns { memoryDir, sessionId, factCount, turn }. */
+ *  Returns { memoryDir, sessionId, graph, factCount, turn }. */
 export async function createSpriteCatalogSession({ factRows = [] } = {}) {
   const memoryDir = createInMemoryStore();
   await appendFacts(memoryDir, factRows.map((f) => ({
@@ -43,13 +45,20 @@ export async function createSpriteCatalogSession({ factRows = [] } = {}) {
   return {
     memoryDir,
     sessionId,
+    graph,
     factCount: factRows.length,
     turn: session.turn,
   };
 }
 
-// registerWinkModel is re-exported so the page's own inline script can hand in
-// the self-hosted wink pair (./vendor/wink.js) exactly the way chat.html/
-// ledger.html/plan.html register theirs — the bundle itself never imports
-// wink-nlp (wink-model.mjs's own header explains why).
-globalThis.tmctSprites = { createSpriteCatalogSession, registerWinkModel, normFactTerm, extractSceneItems };
+// `tmct.page` keeps the wink seam (the page hands in the self-hosted pair from
+// ./vendor/wink.js, exactly the way chat.html/ledger.html/plan.html register
+// theirs — the bundle itself never imports wink-nlp), the term normalizer, and
+// the scene composer's parser, which reads a typed line into drawable items
+// rather than answering anything.
+publishTmctSurface({
+  open: createSpriteCatalogSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: { registerWinkModel, normFactTerm, extractSceneItems },
+});

package/src/surfaces/web/tmct-surface.mjs

@@ -0,0 +1,147 @@
+// tmct-surface.mjs — the one contract every demo page has with the engine.
+//
+// Each browser entry used to publish its own bag of primitives under its own
+// name (tmctChat, tmctMud, tmctLedger, tmctSpiderFly, ...), so a visitor
+// reading one page's source met a different wall of raw functions on every
+// page, wired together by hand. mud-browser-entry.mjs's own header stated the
+// reason for its 25: "so mud-viz.mjs's own inlined script never duplicates
+// sprite resolution or the digest/affordance/knowledge readers". Right
+// instinct, wrong unit — the page still had to know 25 names to say one
+// sentence.
+//
+// This publishes ONE `globalThis.tmct` instead, and every page reaches the
+// engine the same way:
+//
+//   await tmct.open(...)     open this page's session
+//   tmct.session             the live session, once opened
+//   await tmct.turn(line)    one conversational turn, the dock's entry point
+//   await tmct.ask(request)  one grounded question, prose plus its evidence
+//   await tmct.plan(request) one compound request, planned over what's loaded
+//
+// Whatever a page still needs that has NO plain-English form lives on
+// `tmct.page` — canvas geometry, sprite templates, a wink model to register, a
+// digest structure table. The split is the point: `tmct.ask(...)` is tmct
+// answering, `tmct.page.cellId(...)` is this page drawing. A reader can tell
+// them apart at a glance, which is exactly what eleven flat bags made
+// impossible.
+//
+// `ask` and `plan` are supplied per page rather than fixed here, because what
+// a page can ground a question against genuinely differs: code-explorer holds
+// a code graph, spider-fly holds a live board projected into one, the ledger
+// dock holds a memory store and no graph at all. A page that supplies neither
+// gets an honest refusal naming why, never a guess — the same promise the
+// engine itself makes.
+
+const NO_SESSION = "no session is open on this page yet — await tmct.open() first";
+
+// The demo ledger page carries TWO bundles at once: the committed
+// question-only one inlined into the HTML (memory-ask-browser-entry.mjs) and
+// the demo site's own full turn engine as a separate script tag
+// (ledger-browser-entry.mjs). Both publish this surface, and which one the
+// browser runs first is not something either can promise. So the
+// question-only one publishes as a `fallback` and the full engine always
+// wins, whichever order they load in. Registered globally rather than
+// module-locally because the two bundles carry their own copy of this module.
+const FALLBACK = Symbol.for("tmct.surface.fallback");
+
+/**
+ * `publishTmctSurface({ open, ask, plan, turn, page, target })` installs
+ * `target.tmct` (default `globalThis`) and returns it.
+ *
+ * `open(...args)` is the page's own session factory and is the only required
+ * argument — `createChatSession`, `createMudSession`, `createPlanSession` and
+ * the rest, called with whatever arguments they already take. Its result
+ * becomes `tmct.session`.
+ *
+ * `turn(line, options, session)` (optional) overrides how a line reaches the
+ * session. The default calls `session.turn(line, options)`, which is every
+ * page but mud — mud runs several characters over one world, so it routes on
+ * `{ as: character }` to that character's own window.
+ *
+ * `ask(request, options, session)` and `plan(request, options, session)`
+ * (optional) are the page's grounded-question and capability-planner routes.
+ * Left out, the matching verb refuses and says which route the page does have.
+ * Every verb takes the same `(what, options)` shape, so the research page's
+ * source-scoped `tmct.ask(q, { sources })` reads like the plan page's
+ * `tmct.turn("solve it", { maxDepth })`.
+ *
+ * `page` is the residual bag: this page's own rendering helpers, reachable as
+ * `tmct.page.*`.
+ *
+ * `fallback: true` publishes only where no fuller surface is standing, and
+ * yields to one that arrives later — the ledger page's two bundles.
+ */
+export function publishTmctSurface({
+  open, ask = null, plan = null, turn = null, page = {}, fallback = false, target = globalThis,
+} = {}) {
+  if (typeof open !== "function") {
+    throw new Error("publishTmctSurface: `open` must be this page's session factory");
+  }
+  const standing = target.tmct;
+  if (fallback && standing && !standing[FALLBACK]) return standing;
+  let session = null;
+
+  const liveSession = () => {
+    if (!session) throw new Error(NO_SESSION);
+    return session;
+  };
+
+  const surface = {
+    // Variadic, so each page's factory keeps the signature it already has —
+    // adventure and mud both take the world payload first, then their options.
+    async open(...args) {
+      session = await open(...args);
+      return session;
+    },
+
+    get session() { return session; },
+
+    async turn(line, options) {
+      const live = liveSession();
+      if (turn) return turn(line, options, live);
+      // Not every page holds a conversation. The ingest page grounds pasted
+      // prose into facts and answers nothing, so it says so rather than
+      // failing on a method it never had.
+      if (typeof live.turn !== "function") {
+        return {
+          answer: "this page runs no conversational turn — see tmct.session for what it does run",
+          end: false, record: null, plan: null, research: null,
+        };
+      }
+      return live.turn(line, options);
+    },
+
+    async ask(request, options) {
+      if (!ask) {
+        return {
+          answer: "this page has no separate ask route — it answers questions through tmct.turn()",
+          data: undefined,
+          miss: true,
+        };
+      }
+      return ask(request, options, liveSession());
+    },
+
+    async plan(request, options) {
+      if (!plan) {
+        return {
+          refused: true,
+          why: "this page's bundle carries no capability planner",
+          driver: null, calls: [], composed: null, observed: null,
+        };
+      }
+      return plan(request, options, liveSession());
+    },
+
+    page,
+
+    /** True where this is the question-only stand-in rather than a page's full
+     *  engine. The ledger page reads it to tell its two docks apart: the live
+     *  one teaches, the stand-in only answers. */
+    fallback,
+  };
+
+  surface[FALLBACK] = fallback;
+  target.tmct = surface;
+  return surface;
+}

package/src/surfaces/web/turn-session.mjs

@@ -55,8 +55,11 @@ function turnErrorFallback(message) {
  * grow a visited-rooms set, bump a turn tally). Never runs on a throw: none
  * of the nine originals touch their own state when `runTurn` itself failed.
  *
- * Returns `{ memoryDir, sessionId, turn, focus, last, planState,
- * setPlanState, researchState, setResearchState }`. `turn(line, callArgs)`
+ * Returns `{ memoryDir, sessionId, graph, turn, focus, last, planState,
+ * setPlanState, researchState, setResearchState }`. `graph` is the one this
+ * session was built over, exposed so a caller can put a question to the same
+ * graph its turns run against (engine-surface.mjs's `graphAsk`) without
+ * holding a second reference to it. `turn(line, callArgs)`
  * resolves to `{ answer, end, record, plan, research }` — the union of every
  * field any of the nine originals reads; a caller ignores what it doesn't
  * need. `research` is passed through undefined/null/a queue snapshot exactly
@@ -109,6 +112,7 @@ export function createTurnSession({
   return {
     memoryDir,
     sessionId,
+    graph,
     get focus() { return focus; },
     get last() { return last; },
     get planState() { return planState; },

package/src/tools/server.mjs

@@ -50,7 +50,7 @@ export const TOOLS = HOT_TOOLS.map(({ name, agentDescription, inputSchema }) =>
   inputSchema,
 }));
 
-async function runHandler(name, args, { config, source = defaultSource, tel = null, ingest = null, memoryBackend = null } = {}) {
+async function runHandler(name, args, { config, source = defaultSource, tel = null, ingest = null, memoryBackend = null, graph: suppliedGraph = null } = {}) {
   // Reject an unknown tool BEFORE touching the graph — an unknown name never
   // triggers a load. hasOwn, so an inherited name ("constructor", "toString")
   // is unknown rather than a callable found on the prototype chain.
@@ -64,13 +64,20 @@ async function runHandler(name, args, { config, source = defaultSource, tel = nu
   // conversational memory store (tmct_export) prefers it over re-deriving a
   // backend from config when one is supplied; every other caller leaves it null
   // and gets today's re-derive-from-config behaviour unchanged.
-  if (handle.ownsGraphLoad) return handle(args, { config, source, tel, ingest, memoryBackend });
-  const graph = await loadGraph(config, source);
+  if (handle.ownsGraphLoad) return handle(args, { config, source, tel, ingest, memoryBackend, graph: suppliedGraph });
+  // `graph` is the third seam of the same kind: a caller that ALREADY holds a
+  // parsed graph hands it over instead of making the tool layer load one. A
+  // browser session is the case that needs it — its graph is built in memory
+  // (a seed payload, or a live board projected through worldRelationGraphPayload)
+  // and there is no config or file behind it to load from.
+  const graph = suppliedGraph || await loadGraph(config, source);
   // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json). Passed to
   // createGraphService so svc.snippet()/svc.context() are usable directly, and on to the
-  // handlers that do their own safe source reads.
-  const repoRoot = dirname(dirname(config.graphFile));
-  const svc = createGraphService(graph, { sourceAccess: true, repoRoot, readFile, tel, ask });
+  // handlers that do their own safe source reads. A supplied graph has no repo on
+  // disk behind it, so those reads are off rather than pointed at a path that
+  // isn't there.
+  const repoRoot = config?.graphFile ? dirname(dirname(config.graphFile)) : null;
+  const svc = createGraphService(graph, { sourceAccess: Boolean(repoRoot), repoRoot, readFile, tel, ask });
   return handle(args, { graph, svc, config, repoRoot, memoryBackend });
 }