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

package/src/services/mud-turn.mjs

@@ -1,28 +1,28 @@
 // mud-turn.mjs — one acting character's whole turn in a mud world: investigate
-// the room it stands in, walk toward food it actually knows about, and (only
-// when that walk has nowhere to go) roll for digging out of the room's
-// frontier. The split mirrors spider-fly.mjs / spider-fly-turn.mjs: adventure
-// .mjs owns the read/fold/write primitives, this file owns the per-tick
-// decisions that drive them. Nothing here writes a fact of its own — every
-// change goes out through runWorldCommand, recordTold or recordExamined.
+// the room it stands in, walk toward food it actually knows about, roll for
+// digging out of the room's frontier, and (when none of that came to anything)
+// set off for a room it has never stood in. The split mirrors spider-fly.mjs /
+// spider-fly-turn.mjs: adventure.mjs owns the read/fold/write primitives, this
+// file owns the per-tick decisions that drive them. Nothing here writes a fact
+// of its own — every change goes out through runWorldCommand, recordTold,
+// recordExamined or recordMassDrain.
 //
 // Every roll is seeded from (character, turn, room, decision name) through
 // fnv1a32/mulberry32, so a run reproduces exactly from its inputs. The world
 // layer writes no bare Math.random anywhere, and this file keeps that.
 //
-// Three things the design leaves open, settled here:
+// Four things the design leaves open, settled here:
 //
-// A character moves once per turn. The directed walk and the edge rolls draw
-// on the same budget, so the edge rolls only run when the walk found nowhere
-// to go. A walk that stepped reached the next room on a known path; it did not
-// reach an edge.
+// A character moves once per turn. The directed walk, the edge rolls and the
+// explore step draw on the same budget, in that order, so each only runs when
+// the one before it came up empty. A walk that stepped reached the next room on
+// a known path; it did not reach an edge.
 //
-// There are two separate reasons to dig — "each available dig direction
-// (including down)" and "each edge direction, to keep following the edge
-// toward food" — and both cash out as a dig. They are kept apart by candidate
-// set, which is what the "(including down)" aside marks. The first ranges over
-// every exit-less direction, vertical ones included, and is plain exploration.
-// The second ranges over the four lateral directions only: the frontier of the
+// There are two separate reasons to dig — plain exploration, and following
+// the level's own frontier toward food — and both cash out as a dig. They are
+// kept apart by candidate set. The first ranges over every direction the
+// room's kind allows and no exit already covers, vertical ones included. The
+// second ranges over the lateral part of that same set: the frontier of the
 // level the character already stands on. So a lateral direction draws two
 // independent rolls and gets dug more often than a vertical one.
 //
@@ -31,22 +31,37 @@
 // the one case where an exit is worth a gamble and the walk still had nothing
 // to follow. A character that knows about no food at all rolls nothing: that
 // silence is the honest miss, and it holds all the way down.
+//
+// A turn that found nothing to do anywhere above ends on the explore step, and
+// that step is a different claim from the food walk. It never guesses where
+// food is. It reads which rooms this character has itself stood in — its own
+// placement history, written turn by turn — and steps toward the nearest one it
+// has not. "I have not been down there yet" is something an animal genuinely
+// knows about itself, so acting on it invents nothing; without it a character
+// that digs itself into a quiet corner stands there for the rest of the run.
+//
+// The two limits that make that stop being a treadmill live elsewhere:
+// adventure.mjs bounds how far from the origin a dig may reach, so the set of
+// rooms to explore is finite, and every turn charges mass. An animal really out
+// of world eventually starves, which is an ending, not a freeze.
 
 import { mulberry32 } from "../domain/seeded-random.mjs";
 import { fnv1a32 } from "../domain/hash.mjs";
 import { bfsLevels } from "../domain/planning.mjs";
 import { loadMemory, readFactRows } from "../adapters/memory/core.mjs";
+import { DEFAULT_GAME_CONFIG, mudMassDrainPerTurn } from "../domain/game-config.mjs";
 import {
   foldWorldState, worldActionRows, runWorldCommand, recordTold, recordExamined,
-  personKnowledgeLines, objectClassChain,
+  recordMassDrain, personKnowledgeLines, objectClassChain, diggableDirections,
+  isOutOfPlay, outOfPlayReasonOf, outOfPlayPhrase, massDrainPerTurnOf,
 } from "./adventure.mjs";
 
 const FOOD_CLASS = "food";
 const LATERAL_DIRECTIONS = ["north", "south", "east", "west"];
-const ALL_DIRECTIONS = [...LATERAL_DIRECTIONS, "up", "down"];
-// Deep enough to cross a burrow several levels down without letting one
-// character's pathfinder walk a whole grown world every tick.
+// Deep enough to cross a whole burrow without letting one character's
+// pathfinder walk a whole grown world every tick.
 const WALK_SEARCH_DEPTH = 8;
+const SNAPSHOT_RE = /^(.+)@turn(\d+)$/;
 
 const EXIT_TOWARD_FOOD_CHANCE = 0.5;
 const EDGE_FOLLOW_DIG_CHANCE = 0.25;
@@ -116,6 +131,16 @@ function knownFood(rows, state, character) {
   return [...new Set(aboutTopics)].filter((thing) => isFood(rows, thing)).sort();
 }
 
+/** The food a character knows about that is still somewhere it could be
+ *  reached — on a floor, or in an open container. An eater's own claim about a
+ *  carrot ages out the moment it eats it, but a claim only ever HEARD stands
+ *  until somebody says otherwise, and that animal has no way to know the meal
+ *  is over. Anything deciding where to GO reads this list rather than the raw
+ *  one, or an animal spends the rest of the run crossing the burrow after
+ *  somebody else's meal. */
+const standingKnownFood = (rows, state, character) =>
+  knownFood(rows, state, character).filter((thing) => visibleRoomOf(rows, state, thing) !== null);
+
 const knownTopics = (rows, state, character) =>
   new Set(personKnowledgeLines(rows, state, character).aboutTopics);
 
@@ -132,20 +157,14 @@ const castIn = (state, room, exclude) => [...state.placements]
 
 /**
  * The first step of a shortest room-graph path from `here` to the nearest room
- * holding a food-classed thing `character` knows about, as
- * `{ direction, room, hops }`. Null when the character knows of no food, or
- * when none of it sits in a room reachable within the search depth — the
- * honest "I don't know where any food is", never a fallback wander.
+ * `wanted` accepts, as `{ direction, room, hops }`. Null when nothing within
+ * the search depth qualifies. Ties break on the room name, so a fork never
+ * turns on fact-row order. Rooms in `avoid` are neither entered nor routed
+ * through.
  */
-function stepTowardKnownFood(rows, state, character, here) {
-  const foodRooms = new Set(
-    knownFood(rows, state, character)
-      .map((thing) => visibleRoomOf(rows, state, thing))
-      .filter(Boolean),
-  );
-  if (!foodRooms.size || foodRooms.has(here)) return null;
-
+function firstStepToward(state, here, wanted, avoid = new Set()) {
   const successorsOf = (room) => [...(state.exits.get(room)?.entries() ?? [])]
+    .filter(([, target]) => !avoid.has(target))
     .map(([direction, target]) => ({ room: target, direction, from: room }));
 
   const cameFrom = new Map(); // room -> { via, from }
@@ -153,7 +172,7 @@ function stepTowardKnownFood(rows, state, character, here) {
   for (const level of bfsLevels(here, successorsOf, { maxDepth: WALK_SEARCH_DEPTH, keyOf: (item) => item.room })) {
     hops += 1;
     for (const item of level) cameFrom.set(item.room, { via: item.direction, from: item.from });
-    const goal = level.map((item) => item.room).filter((room) => foodRooms.has(room)).sort()[0];
+    const goal = level.map((item) => item.room).filter(wanted).sort()[0];
     if (!goal) continue;
     let room = goal;
     let firstStep = null;
@@ -168,15 +187,56 @@ function stepTowardKnownFood(rows, state, character, here) {
   return null;
 }
 
-// ---- the turn ----------------------------------------------------------------
+/**
+ * The first step toward the nearest room holding a food-classed thing
+ * `character` knows about. Null when the character knows of no food, or when
+ * none of it sits in a room reachable within the search depth — the honest
+ * "I don't know where any food is", never a fallback wander.
+ */
+function stepTowardKnownFood(rows, state, character, here) {
+  const foodRooms = new Set(
+    standingKnownFood(rows, state, character).map((thing) => visibleRoomOf(rows, state, thing)),
+  );
+  if (!foodRooms.size || foodRooms.has(here)) return null;
+  return firstStepToward(state, here, (room) => foodRooms.has(room));
+}
 
-/** A room's unexplored sides: every compass direction with no exit written
- *  from here yet. A room with none is fully mapped and has no edge to roll
- *  against. */
-const edgeDirectionsOf = (state, room) => {
-  const exits = state.exits.get(room);
-  return ALL_DIRECTIONS.filter((direction) => !exits?.has(direction));
-};
+/** Every room `character` has itself stood in: its base placement and every
+ *  @turnN snapshot of one, read over the world's OWN rows so a taught locative
+ *  can never write a visit that never happened. */
+function roomsStoodIn(rows, character) {
+  const visited = new Set();
+  for (const row of worldActionRows(rows)) {
+    if (row.predicate !== "mgx:currently-in") continue;
+    const snapshot = SNAPSHOT_RE.exec(row.subject);
+    if ((snapshot ? snapshot[1] : row.subject) !== character) continue;
+    visited.add(row.object);
+  }
+  return visited;
+}
+
+/** Every room a predator is standing in. An animal with nothing better to do
+ *  does not go and look into one: leaving them in would make the explore step a
+ *  funnel straight to the den, since the unvisited room nearest the burrow is
+ *  exactly where the fox lives. The den stays reachable by the food gamble
+ *  below, which is a gamble and is meant to be. */
+const predatorRooms = (rows, state) => new Set((rows || [])
+  .filter((r) => r.predicate === "mgx:is-predator" && r.object === "true")
+  .map((r) => state.placements.get(r.subject)?.object)
+  .filter(Boolean));
+
+/**
+ * The first step toward the nearest room `character` has never stood in. This
+ * is the one move that runs on the character's OWN history rather than on
+ * anything it knows about the world's contents — it says "I have not been that
+ * way yet", which is true whatever turns out to be there.
+ */
+function stepTowardUnvisitedRoom(rows, state, character, here) {
+  const visited = roomsStoodIn(rows, character);
+  return firstStepToward(state, here, (room) => !visited.has(room), predatorRooms(rows, state));
+}
+
+// ---- the turn ----------------------------------------------------------------
 
 /**
  * Run one acting character's whole turn against a live mud world.
@@ -186,13 +246,24 @@ const edgeDirectionsOf = (state, room) => {
  * turn. Room-mates are discovered from the fold, so the caller passes no cast
  * list.
  *
- * Returns `{ character, k, room, roomAfter, actions, learned, text, note }`.
- * `actions` is the machine-readable spine — one entry per sub-step that fired,
- * each `{ step, kind, ..., text, miss }` — and a sub-step whose precondition
- * did not hold this turn records `kind: "none"` with its reason rather than
- * dropping out silently or being narrated as a success.
+ * Returns `{ character, k, room, roomAfter, actions, learned, mass, text,
+ * note }`. `actions` is the machine-readable spine — one entry per sub-step
+ * that fired, each `{ step, kind, ..., text, miss }` — and a sub-step whose
+ * precondition did not hold this turn records `kind: "none"` with its reason
+ * rather than dropping out silently or being narrated as a success. `mass` is
+ * what the character weighs once this turn's drain is charged, or null when the
+ * world writes it no mass.
+ *
+ * A turn that ends the character's run also carries `outOfPlay: true` and
+ * `outOfPlayReason` ("eaten" or "starved"), and so does every turn after it.
+ *
+ * `mudConfig` is the resolved `mud` section of the game config — the fallback
+ * for the per-species mass drain a turn charges, used only when the world
+ * itself writes the character no `mgx:mass-drain-per-turn` fact.
  */
-export async function runMudTurn(character, { world, memoryDir, env, graph, cache, k = null } = {}) {
+export async function runMudTurn(character, {
+  world, memoryDir, env, graph, cache, k = null, mudConfig = DEFAULT_GAME_CONFIG.mud,
+} = {}) {
   const opened = await readWorld(memoryDir);
   const room = opened.state.placements.get(character)?.object ?? null;
   const turn = k ?? opened.state.turnCount + 1;
@@ -207,6 +278,15 @@ export async function runMudTurn(character, { world, memoryDir, env, graph, cach
       note: `MUD — ${character} has no placement fact; the turn is declined rather than guessed`,
     };
   }
+  if (isOutOfPlay(opened.state, character)) {
+    const reason = outOfPlayReasonOf(opened.state, character);
+    return {
+      character, k: turn, room: null, roomAfter: null, actions, learned: [],
+      outOfPlay: true, outOfPlayReason: reason,
+      text: `${outOfPlayPhrase(character, reason)}. It takes no more turns.`,
+      note: `MUD — ${character} is placed out of play (${reason}); the turn is declined, and every later one will be too`,
+    };
+  }
 
   const commandContext = { world, memoryDir, env, graph, cache, actingSubject: character };
   const runCommand = async (step, cmd, detail) => {
@@ -232,21 +312,39 @@ export async function runMudTurn(character, { world, memoryDir, env, graph, cach
     });
     moved = !res.miss;
   } else {
-    recordSkip(
-      "walk",
-      knownFood(walked.rows, walked.state, character).length
-        ? "no room it knows holds food is reachable from here"
-        : "it knows of no food to walk toward",
-      `the ${character} has nowhere it knows to walk to.`,
-    );
+    recordSkip("walk", walkSkipReason(walked.rows, walked.state, character), `the ${character} has nowhere it knows to walk to.`);
   }
 
   if (!moved) {
-    await rollAtEdge({ character, turn, memoryDir, runCommand, recordSkip });
+    const edge = await rollAtEdge({ character, turn, memoryDir, runCommand, recordSkip });
+    if (!edge.acted) await exploreUnvisited({ character, memoryDir, runCommand, recordSkip });
+  }
+
+  // The world's own word first: a `mgx:mass-drain-per-turn` fact on the
+  // character or its species is something a player can read and change, and the
+  // shipped config table is only what a world that writes none falls back to.
+  const writtenDrain = massDrainPerTurnOf(opened.rows, character);
+  const drained = await recordMassDrain(memoryDir, {
+    world,
+    subject: character,
+    drainPerTurn: writtenDrain === null ? mudMassDrainPerTurn(mudConfig, character) : writtenDrain,
+    cache,
+  });
+  if (drained.mass === null) {
+    notes.push(`MUD — mass: the world writes ${character} no mass, so a turn costs it nothing`);
+  } else {
+    notes.push(`MUD — mass: ${character} is down to ${drained.mass}${drained.starved ? " and starves" : ""}`);
   }
 
   const closed = await readWorld(memoryDir);
   const learned = [...knownTopics(closed.rows, closed.state, character)].filter((t) => !learnedBefore.has(t)).sort();
+  const texts = actions.map((a) => a.text).filter(Boolean);
+  if (drained.starved) texts.push(`the ${character} runs out of mass and starves. It takes no more turns.`);
+  // Read off the closed world rather than off the drain alone: a character can
+  // also end this turn eaten, by walking into the predator's room on it, and a
+  // caller watching for a fate should not have to know which of the two ways it
+  // was to find out that one happened.
+  const fate = outOfPlayReasonOf(closed.state, character);
   return {
     character,
     k: turn,
@@ -254,35 +352,86 @@ export async function runMudTurn(character, { world, memoryDir, env, graph, cach
     roomAfter: closed.state.placements.get(character)?.object ?? room,
     actions,
     learned,
-    text: actions.map((a) => a.text).filter(Boolean).join(" "),
+    mass: drained.mass,
+    ...(fate ? { outOfPlay: true, outOfPlayReason: fate } : {}),
+    text: texts.join(" "),
     note: notes.join("; "),
   };
 }
 
-/** Step one: ask a room-mate about food, examine something unexamined, then
- *  make one seeded attempt at take/put/eat. The ask and the examine write
- *  testimony, which never folds into the playable state; only the
- *  manipulation touches the world. */
+/** Why a turn's food walk took no step — three different situations, each
+ *  named on its own terms rather than collapsed into one shrug. */
+function walkSkipReason(rows, state, character) {
+  if (!knownFood(rows, state, character).length) return "it knows of no food to walk toward";
+  if (!standingKnownFood(rows, state, character).length) return "every food it knows about has already been eaten";
+  return "no room it knows holds food is reachable from here";
+}
+
+/** The last move of a turn that found nothing else to do: one step toward the
+ *  nearest room this character has never stood in. Reached only when the walk
+ *  took no step and the edge rolls fired nothing, so it never competes for the
+ *  move budget — and when every room within reach has already been walked, it
+ *  says so and the character stands still. */
+async function exploreUnvisited({ character, memoryDir, runCommand, recordSkip }) {
+  const { rows, state } = await readWorld(memoryDir);
+  const here = state.placements.get(character)?.object ?? null;
+  if (!here) return recordSkip("explore", "it has no position to set out from", "");
+  const step = stepTowardUnvisitedRoom(rows, state, character, here);
+  if (!step) {
+    return recordSkip(
+      "explore",
+      "it has already stood in every room it can reach",
+      `the ${character} has been everywhere this burrow goes.`,
+    );
+  }
+  return runCommand("explore", { pattern: "imperative", verb: "go", direction: step.direction }, {
+    direction: step.direction, toward: step.room, hops: step.hops, reason: "unvisited",
+  });
+}
+
+/** Step one: talk to a room-mate, examine something unexamined, then make one
+ *  seeded attempt at take/put/eat. Talking comes first, and an animal speaks
+ *  to a room-mate it has not met yet or that has food news for it. Once a
+ *  partner has neither, this one has nothing left to say and spends the step
+ *  on the room instead — two animals that stay put would otherwise trade the
+ *  same empty greeting every turn for the rest of the run. The talk and the
+ *  examine write testimony, which never folds into the playable state; only
+ *  the manipulation touches the world. */
 async function investigateRoom({ character, turn, room, memoryDir, cache, recordSkip, runCommand, actions, notes }) {
   const { rows, state } = await readWorld(memoryDir);
   const roomMates = castIn(state, room, character);
   const alreadyKnown = knownTopics(rows, state, character);
+  const foodNewsFrom = (mate) => knownFood(rows, state, mate).filter((thing) => !alreadyKnown.has(thing));
+  const worthSpeakingTo = roomMates.filter((mate) => !alreadyKnown.has(mate) || foodNewsFrom(mate).length);
 
-  const teller = pickSeeded(roomMates, character, turn, room, "ask-who");
+  const teller = pickSeeded(worthSpeakingTo, character, turn, room, "ask-who");
   if (!teller) {
-    recordSkip("investigate", "no other character stands here to ask", "");
+    recordSkip(
+      "investigate",
+      roomMates.length
+        ? `the ${character} has already heard everything the animals standing here can tell it about food`
+        : "no other character stands here to ask",
+      "",
+    );
   } else {
-    const tellerFood = knownFood(rows, state, teller);
-    const offers = tellerFood.filter((thing) => !alreadyKnown.has(thing));
-    const told = pickSeeded(offers, character, turn, room, `ask-${teller}`);
+    const told = pickSeeded(foodNewsFrom(teller), character, turn, room, `ask-${teller}`);
+    // Speaking to an animal is how this one comes to know it, and that note is
+    // the whole escape from the loop: a pair with no news left for each other
+    // drops out of worthSpeakingTo, and drops back in the moment either side
+    // learns a food the other has not heard of.
+    if (!alreadyKnown.has(teller)) {
+      await recordExamined(memoryDir, { observer: character, thing: teller, k: turn, cache });
+      alreadyKnown.add(teller);
+    }
     if (!told) {
-      recordSkip(
-        "investigate",
-        tellerFood.length
-          ? `the ${character} already knows every food the ${teller} could name`
-          : `the ${teller} knows of no food to share`,
-        "",
-      );
+      // Still a real exchange, and still narrated as one: an animal that meets
+      // another animal always says something. Only the testimony is missing,
+      // because the teller had nothing this one didn't already know.
+      actions.push({
+        step: "investigate", kind: "ask", teller, thing: null, miss: false,
+        text: `the ${character} greets the ${teller}, but hears nothing new about food.`,
+      });
+      notes.push(`MUD — talk: ${character} greeted ${teller}; ${teller} knows of no food to share`);
     } else {
       await recordTold(memoryDir, { asker: character, teller, thing: told, k: turn, cache });
       alreadyKnown.add(told);
@@ -323,9 +472,15 @@ async function manipulateSomething({ character, turn, room, memoryDir, runComman
   const { rows, state } = await readWorld(memoryDir);
   const chosen = MANIPULATIONS[Math.floor(rollFor(character, turn, room, "manipulate") * MANIPULATIONS.length)];
 
-  const looseHere = [...state.placements]
-    .filter(([, place]) => place.predicate === "mgx:located-in" && place.object === room)
+  // Everything the take verb would really accept here: loose on the floor, or
+  // sitting in an open container standing in this room. Reading only the floor
+  // made putting something into the basket a one-way trip, and in a room whose
+  // only food went into the basket that left nothing to take and nothing to
+  // eat for the rest of the run.
+  const withinReach = [...state.placements]
+    .filter(([, place]) => place.predicate === "mgx:located-in")
     .map(([thing]) => thing)
+    .filter((thing) => visibleRoomOf(rows, state, thing) === room)
     .sort();
   const carried = [...state.placements]
     .filter(([, place]) => place.predicate === "mgx:located-in" && place.object === character)
@@ -333,8 +488,8 @@ async function manipulateSomething({ character, turn, room, memoryDir, runComman
     .sort();
 
   if (chosen === "take") {
-    const target = pickSeeded(looseHere, character, turn, room, "take-what");
-    if (!target) return recordSkip("investigate", "nothing loose here to take", "");
+    const target = pickSeeded(withinReach, character, turn, room, "take-what");
+    if (!target) return recordSkip("investigate", "nothing here it could pick up", "");
     return runCommand("investigate", { pattern: "imperative", verb: "take", object: target }, { object: target });
   }
 
@@ -356,7 +511,7 @@ async function manipulateSomething({ character, turn, room, memoryDir, runComman
     );
   }
 
-  const edible = [...new Set([...looseHere, ...carried])].filter((thing) => isFood(rows, thing)).sort();
+  const edible = [...new Set([...withinReach, ...carried])].filter((thing) => isFood(rows, thing)).sort();
   const target = pickSeeded(edible, character, turn, room, "eat-what");
   if (!target) return recordSkip("investigate", "no food is within reach here", "");
   return runCommand("investigate", { pattern: "imperative", verb: "eat", object: target }, { object: target });
@@ -364,32 +519,54 @@ async function manipulateSomething({ character, turn, room, memoryDir, runComman
 
 /** Step three: the room's unexplored sides, one independent roll per reason
  *  per direction. Only reached on a turn whose walk took no step, so the move
- *  budget is still unspent. */
+ *  budget is still unspent. Reports `{ acted }` — whether a roll actually came
+ *  up — so the caller knows whether the turn still has a move to spend. */
 async function rollAtEdge({ character, turn, memoryDir, runCommand, recordSkip }) {
   const { rows, state } = await readWorld(memoryDir);
   const room = state.placements.get(character)?.object ?? null;
-  if (!room) return recordSkip("edge", "it has no position to roll from", "");
-  const edges = edgeDirectionsOf(state, room);
-  if (!edges.length) return recordSkip("edge", `the ${room} is mapped on every side`, "");
+  if (!room) {
+    recordSkip("edge", "it has no position to roll from", "");
+    return { acted: false };
+  }
 
-  const foodItKnows = knownFood(rows, state, character);
+  // The exit gamble runs before the dig rolls and whether or not this room can
+  // still be dug at all. A room mapped on every side its kind allows is
+  // exactly where a character with food somewhere else has nothing left but
+  // its existing exits to gamble on, so gating it behind a diggable direction
+  // stranded animals in a finished room for the rest of the run.
+  const foodItKnows = standingKnownFood(rows, state, character);
   const foodStandsHere = foodItKnows.some((thing) => visibleRoomOf(rows, state, thing) === room);
   if (foodItKnows.length && !foodStandsHere) {
     for (const direction of [...(state.exits.get(room)?.keys() ?? [])].sort()) {
       if (rollFor(character, turn, room, `exit-${direction}`) >= EXIT_TOWARD_FOOD_CHANCE) continue;
-      return runCommand("edge", { pattern: "imperative", verb: "go", direction }, { direction, reason: "exit-toward-food" });
+      await runCommand("edge", { pattern: "imperative", verb: "go", direction }, { direction, reason: "exit-toward-food" });
+      return { acted: true };
     }
   }
 
+  // The room's OWN kind decides which way a dig can go — there is nothing to
+  // tunnel sideways through above ground, the burrow runs one level deep, and
+  // past the world's dig boundary nothing is offered at all — so the candidate
+  // set is the dig verb's own, never a flat compass. A roll on a direction the
+  // verb would refuse spends the turn on a decline.
+  const edges = diggableDirections(rows, state, room);
+  if (!edges.length) {
+    recordSkip("edge", `there is nowhere left to dig from the ${room}`, "");
+    return { acted: false };
+  }
+
   for (const direction of edges.filter((d) => LATERAL_DIRECTIONS.includes(d))) {
     if (rollFor(character, turn, room, `edge-follow-${direction}`) >= EDGE_FOLLOW_DIG_CHANCE) continue;
-    return runCommand("edge", { pattern: "imperative", verb: "dig", direction }, { direction, reason: "edge-follow" });
+    await runCommand("edge", { pattern: "imperative", verb: "dig", direction }, { direction, reason: "edge-follow" });
+    return { acted: true };
   }
 
   for (const direction of edges) {
     if (rollFor(character, turn, room, `dig-${direction}`) >= EXPLORATORY_DIG_CHANCE) continue;
-    return runCommand("edge", { pattern: "imperative", verb: "dig", direction }, { direction, reason: "explore" });
+    await runCommand("edge", { pattern: "imperative", verb: "dig", direction }, { direction, reason: "explore" });
+    return { acted: true };
   }
 
-  return recordSkip("edge", `no roll came up at the ${room}'s edge`, "");
+  recordSkip("edge", `no roll came up at the ${room}'s edge`, "");
+  return { acted: false };
 }