@polycode-projects/the-mechanical-code-talker 2.7.11 → 2.7.13

package/corpus/worlds/manifest.json

@@ -3,8 +3,8 @@
   "generated": "by scripts/build-worlds-pack.mjs from corpus/worlds/src/",
   "counts": {
     "worlds": 2,
-    "facts": 527,
-    "rules": 14
+    "facts": 528,
+    "rules": 19
   },
   "budgets": {
     "sourceBytesPerWorld": 131072,
@@ -14,8 +14,8 @@
   "sources": [
     {
       "file": "src/ashcombe-hall.jsonl",
-      "bytes": 7481,
-      "sha256": "776634e8f7db704f2895ad1557cdcb79c28e14fe8fd4202ef1d0db9b4358ca91"
+      "bytes": 8458,
+      "sha256": "79332b0700a8c8289ca4d8b5a9cf3dcff4c869fb1b45a72dd291617f61bdd184"
     },
     {
       "file": "src/spider-fly.jsonl",
@@ -31,8 +31,8 @@
     },
     {
       "file": "shards/ashcombe-hall.jsonl.gz",
-      "bytes": 864,
-      "sha256": "468ba9ae859fc63094f5030648f07885e1e0785fb4e18e309cc4e6729c878ebf"
+      "bytes": 963,
+      "sha256": "d44e229d8f30dc43e8801443d426c315b43a6758adb11ad332c84e7108268746"
     },
     {
       "file": "shards/spider-fly.jsonl.gz",

package/corpus/worlds/src/ashcombe-hall.jsonl

@@ -33,6 +33,7 @@
 {"world":"ashcombe-hall","kind":"fact","subject":"portrait","predicate":"mgx:fixed-in","object":"drawing-room"}
 {"world":"ashcombe-hall","kind":"fact","subject":"key","predicate":"mgx:hidden-in","object":"portrait"}
 {"world":"ashcombe-hall","kind":"fact","subject":"letter","predicate":"mgx:hidden-in","object":"cabinet"}
+{"world":"ashcombe-hall","kind":"fact","subject":"letter","predicate":"mgx:is-objective","object":"true"}
 {"world":"ashcombe-hall","kind":"fact","subject":"housekeeper","predicate":"mgx:currently-in","object":"kitchen"}
 {"world":"ashcombe-hall","kind":"fact","subject":"cook","predicate":"mgx:currently-in","object":"kitchen"}
 {"world":"ashcombe-hall","kind":"fact","subject":"butler","predicate":"mgx:currently-in","object":"drawing-room"}
@@ -60,5 +61,10 @@
 {"world":"ashcombe-hall","kind":"rule","name":"give","ruleKind":"action-signature","slots":{"subjectClass":"portable","targetClass":"person"}}
 {"world":"ashcombe-hall","kind":"rule","name":"give","ruleKind":"action-effect","slots":{"predicate":"located-in","subjectRole":"subject","objectRole":"target"}}
 {"world":"ashcombe-hall","kind":"rule","name":"open","ruleKind":"action-signature","slots":{"subjectClass":"adventurer","targetClass":"furniture"}}
+{"world":"ashcombe-hall","kind":"rule","name":"open","ruleKind":"action-precond","slots":{"shape":"fact-value","predicate":"stands-locked-in","role":"target","scope":"any","negate":"true"}}
+{"world":"ashcombe-hall","kind":"rule","name":"open","ruleKind":"action-precond","slots":{"shape":"fact-value","predicate":"is-open","role":"target","scope":"any","value":"true","negate":"true"}}
+{"world":"ashcombe-hall","kind":"rule","name":"open","ruleKind":"action-effect","slots":{"predicate":"is-open","subjectRole":"target","value":"true"}}
 {"world":"ashcombe-hall","kind":"rule","name":"unlock","ruleKind":"action-signature","slots":{"subjectClass":"adventurer","targetClass":"furniture"}}
 {"world":"ashcombe-hall","kind":"rule","name":"close","ruleKind":"action-signature","slots":{"subjectClass":"adventurer","targetClass":"furniture"}}
+{"world":"ashcombe-hall","kind":"rule","name":"close","ruleKind":"action-precond","slots":{"shape":"fact-value","predicate":"is-open","role":"target","scope":"any","value":"true"}}
+{"world":"ashcombe-hall","kind":"rule","name":"close","ruleKind":"action-effect","slots":{"predicate":"is-open","subjectRole":"target","value":"false"}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.7.11",
+  "version": "2.7.13",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

package/src/adapters/memory/core.mjs

@@ -1287,10 +1287,18 @@ const RULE_SLOT_SPEC = {
   [RULE_KIND_ACTION_PRECOND]: [
     ["shape", "mgx:ruleActionPrecondShape"], ["predicate", "mgx:ruleActionPrecondPredicate"],
     ["role", "mgx:ruleActionPrecondRole"], ["scope", "mgx:ruleActionPrecondScope"],
+    // value/negate: the "fact-value" shape's literal-match and negation
+    // slots. Optional (RULE_SLOT_OPTIONAL below) — no-incoming/comparator
+    // preconds never set them.
+    ["value", "mgx:ruleActionPrecondValue"], ["negate", "mgx:ruleActionPrecondNegate"],
   ],
   [RULE_KIND_ACTION_EFFECT]: [
     ["predicate", "mgx:ruleActionEffectPredicate"], ["subjectRole", "mgx:ruleActionEffectSubject"],
-    ["objectRole", "mgx:ruleActionEffectObject"],
+    // objectRole/value: exactly one of these two must be set (enforced
+    // below, not by this per-slot spec) — a role-bound effect (Hanoi's
+    // "rest-on") supplies objectRole, a literal datatype effect (Ashcombe's
+    // is-open = "true") supplies value instead.
+    ["objectRole", "mgx:ruleActionEffectObject"], ["value", "mgx:ruleActionEffectValue"],
   ],
   // "the <left> may not be with the <right> without the <guard>" — each slot
   // names a class whose sole member src/domain/domain.mjs resolves at compile time.
@@ -1300,25 +1308,47 @@ const RULE_SLOT_SPEC = {
   ],
 };
 
+// Slots a kind's RULE_SLOT_SPEC lists but does NOT require non-empty — the
+// literal-effect/fact-value extension's slots, added after the original
+// four-kind design. A pre-existing rule never sets them, so it reads back
+// with these keys simply absent (readRuleRows defaults an absent slot to
+// ""), the same "not supplied" signal domain.mjs's compileDomain gives an
+// explicit "" — see optionalTerm there.
+const RULE_SLOT_OPTIONAL = {
+  [RULE_KIND_ACTION_PRECOND]: new Set(["value", "negate"]),
+  [RULE_KIND_ACTION_EFFECT]: new Set(["objectRole", "value"]),
+};
+
 // Content-addressed over (kind, name, ...slots in RULE_SLOT_SPEC order),
 // mirroring factIdFor's NUL-delimited discipline: identical rules upsert,
 // different ones coexist. For 2-slot kinds the joined string is byte-identical
 // to the historical (kind, name, slot1, slot2) template, so pre-existing rule
-// ids never change (pinned by test/adapters/memory-rules-action.test.mjs).
+// ids never change (pinned by test/adapters/memory-rules-action.test.mjs);
+// action-precond/action-effect ids shifted when their optional slots joined
+// the spec above (their own round-trip test asserts dedup behavior, never a
+// specific hash, so this was never a promise for those two kinds).
 const ruleIdFor = (kind, name, slotValues) => `rule:${fnv1aHex([kind, name, ...slotValues].join("\0"))}`;
 
 /** Append one taught RULE — a sibling of appendFact storing a `Rule`
  *  individual, same upsert/provenance/trust/SHACL discipline (neither
  *  pipeline ever checks `individual.class`). `slots` is the matching
- *  per-kind object (RULE_SLOT_SPEC above). Returns { id }. */
+ *  per-kind object (RULE_SLOT_SPEC above); a slot named in RULE_SLOT_OPTIONAL
+ *  may be omitted. Returns { id }. */
 export async function appendRule(dir, { name, kind, slots, provenance = "", createdAt = "" } = {}) {
   const spec = RULE_SLOT_SPEC[kind];
   if (!spec) throw new Error(`a rule kind must be one of ${RULE_KINDS.join(", ")}, got ${JSON.stringify(kind)}`);
   const n = normFactTerm(name);
   if (!n) throw new Error("a rule needs a name");
+  const optional = RULE_SLOT_OPTIONAL[kind] || new Set();
   const slotValues = spec.map(([slotKey]) => normFactTerm(slots?.[slotKey]));
-  if (slotValues.some((v) => !v)) {
-    throw new Error(`a ${kind} rule needs ${spec.map(([slotKey]) => slotKey).join(" + ")}`);
+  const missing = spec.filter(([slotKey], i) => !optional.has(slotKey) && !slotValues[i]);
+  if (missing.length) {
+    throw new Error(`a ${kind} rule needs ${missing.map(([slotKey]) => slotKey).join(" + ")}`);
+  }
+  if (kind === RULE_KIND_ACTION_EFFECT) {
+    const objectRole = slotValues[spec.findIndex(([k]) => k === "objectRole")];
+    const value = slotValues[spec.findIndex(([k]) => k === "value")];
+    if (!objectRole && !value) throw new Error(`a ${kind} rule needs an objectRole or a value`);
   }
   const id = ruleIdFor(kind, n, slotValues);
   const label = labelOf(`${n} = ${kind}(${slotValues.join(", ")})`);
@@ -1336,7 +1366,13 @@ export async function appendRule(dir, { name, kind, slots, provenance = "", crea
         { prop: "rdf:type", key: "type", value: "owl:NamedIndividual" },
         { prop: RULE_NAME_PROP, key: "ruleName", value: n },
         { prop: RULE_KIND_PROP, key: "ruleKind", value: kind },
-        ...spec.map(([slotKey, prop], i) => ({ prop, key: slotKey, value: slotValues[i] })),
+        // An optional slot left empty stores no attribute at all — the same
+        // "never supplied" shape a pre-extension Rule individual already has,
+        // rather than a wasted always-"" one.
+        ...spec
+          .map(([slotKey, prop], i) => ({ prop, key: slotKey, value: slotValues[i], skip: !slotValues[i] && optional.has(slotKey) }))
+          .filter((attr) => !attr.skip)
+          .map(({ skip, ...attr }) => attr),
         { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
         ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
       ],

package/src/adapters/memory/shacl.mjs

@@ -11,9 +11,13 @@ const RULE_KINDS = new Set([
   "action-signature", "action-precond", "action-effect", "action-constraint",
 ]);
 
-// Mirrors core.mjs's own (unexported) RULE_SLOT_SPEC exactly — the single
-// source of truth for the closed rule-kind shapes; kept in sync by hand
-// (both describe the same kinds' slots).
+// Mirrors the REQUIRED subset of core.mjs's own (unexported) RULE_SLOT_SPEC —
+// kept in sync by hand. Two kinds there also carry optional slots
+// (RULE_SLOT_OPTIONAL: action-precond's value/negate, action-effect's
+// objectRole/value) that deliberately do NOT appear here: this gate only
+// checks genuine malformation (the comment above), and "at least one of
+// objectRole/value" is a joint constraint core.mjs's own appendRule already
+// enforces at write time, not a per-slot presence check this shape can express.
 const RULE_SLOT_PROPS = {
   compose2: ["mgx:ruleBase1", "mgx:ruleBase2"],
   filter: ["mgx:ruleBase1", "mgx:ruleFilterProperty"],
@@ -23,9 +27,7 @@ const RULE_SLOT_PROPS = {
     "mgx:ruleActionPrecondShape", "mgx:ruleActionPrecondPredicate",
     "mgx:ruleActionPrecondRole", "mgx:ruleActionPrecondScope",
   ],
-  "action-effect": [
-    "mgx:ruleActionEffectPredicate", "mgx:ruleActionEffectSubject", "mgx:ruleActionEffectObject",
-  ],
+  "action-effect": ["mgx:ruleActionEffectPredicate", "mgx:ruleActionEffectSubject"],
   "action-constraint": [
     "mgx:ruleActionConstraintLeft", "mgx:ruleActionConstraintRight", "mgx:ruleActionConstraintGuard",
   ],

package/src/domain/domain.mjs

@@ -19,6 +19,15 @@ const attachPrefix = (predicate) => {
   return p.includes(":") ? p : `mgx:${p}`;
 };
 
+/** A genuinely-supplied optional slot (a literal precond/effect value): `""`,
+ *  `null` and `undefined` all read as "not supplied", the same signal a
+ *  never-taught slot and a readRuleRows-defaulted `""` both give. */
+const optionalTerm = (value) => {
+  if (value == null) return undefined;
+  const t = normTerm(value);
+  return t === "" ? undefined : t;
+};
+
 const rowSort = (a, b) =>
   a.subject.localeCompare(b.subject) ||
   a.predicate.localeCompare(b.predicate) ||
@@ -55,17 +64,32 @@ export function compileDomain(factRows, ruleRows) {
         targetClass: normTerm(slots.targetClass),
       });
     } else if (rule.kind === "action-precond") {
+      // value/negate are optional: absent in every no-incoming/comparator row
+      // taught so far, so their key is omitted rather than written as "" —
+      // an omitted key keeps a pre-existing precond's JSON.stringify sort
+      // form (and its precondHolds behavior) byte-identical to before this
+      // shape existed. normFactTerm/readRuleRows read a genuinely absent
+      // slot back as "", the same signal an explicit "" would give.
+      const value = optionalTerm(slots.value);
+      const negate = String(slots.negate) === "true" ? true : undefined;
       family.preconds.push({
         shape: normTerm(slots.shape),
         predicate: attachPrefix(slots.predicate),
         role: normTerm(slots.role),
         scope: normTerm(slots.scope),
+        ...(value !== undefined ? { value } : {}),
+        ...(negate !== undefined ? { negate } : {}),
       });
     } else if (rule.kind === "action-effect") {
+      // value is the literal-effect alternative to objectRole (a datatype
+      // write, e.g. mgx:is-open = "true", rather than a role binding) — same
+      // omit-when-absent discipline as the precond fields above.
+      const value = optionalTerm(slots.value);
       family.effects.push({
         predicate: attachPrefix(slots.predicate),
         subjectRole: normTerm(slots.subjectRole),
         objectRole: normTerm(slots.objectRole),
+        ...(value !== undefined ? { value } : {}),
       });
     } else if (rule.kind === "action-constraint") {
       family.constraints.push({
@@ -111,7 +135,11 @@ export function compileDomain(factRows, ruleRows) {
   };
   for (const action of actions) {
     for (const effect of action.effects) {
-      for (const role of [effect.subjectRole, effect.objectRole]) {
+      // A literal-valued effect (effect.value set) has no objectRole to bind
+      // — the literal IS the object, so objectRole (unused, "" when the
+      // teaching row never set it) never enters the class-membership check.
+      const roles = effect.value !== undefined ? [effect.subjectRole] : [effect.subjectRole, effect.objectRole];
+      for (const role of roles) {
         if (role !== "subject" && role !== "target") requireSoleMember(role, `an effect role of "${action.name}"`);
       }
     }
@@ -187,7 +215,13 @@ export function stateKeyFor(state) {
 const precondApplies = (precond, target, domain) =>
   precond.scope === "any" || (domain.classMembers[precond.scope] || []).includes(target);
 
-function precondHolds(precond, subject, target, state, domain) {
+/** A precondition on a fact ABOUT the role term itself (roleTerm as subject),
+ *  as opposed to "no-incoming"'s fact pointing AT the role term (roleTerm as
+ *  object). Datatype/state checks — a lock, an open/closed flag — read this
+ *  way: "does (roleTerm, predicate, value) exist", with `value` an existence
+ *  wildcard when omitted and `negate` flipping the sense ("must NOT exist"
+ *  covers "must not be locked", "must not already be open"). */
+export function precondHolds(precond, subject, target, state, domain) {
   const roleTerm = precond.role === "target" ? target : subject;
   if (precond.shape === "no-incoming") {
     return !state.some((r) => r.predicate === precond.predicate && r.object === roleTerm);
@@ -198,13 +232,21 @@ function precondHolds(precond, subject, target, state, domain) {
     return domain.ordering.some((r) =>
       r.subject === left && r.predicate === precond.predicate && r.object === right);
   }
+  if (precond.shape === "fact-value") {
+    const exists = state.some((r) => r.subject === roleTerm && r.predicate === precond.predicate
+      && (precond.value == null || r.object === precond.value));
+    return precond.negate ? !exists : exists;
+  }
   return false;
 }
 
 /** Ground an effect/constraint role word: "subject"/"target" bind the
  *  grounding pair; any other word is class-bound and binds the class's sole
- *  member — its companion semantics (compileDomain guarantees exactly one). */
-const roleBinding = (role, subject, target, domain) => {
+ *  member — its companion semantics (compileDomain guarantees exactly one).
+ *  Exported so a caller consulting one grounded precond/effect directly,
+ *  rather than running a full movesFromRules search, can still resolve an
+ *  effect's subject/object the same way the planner does. */
+export const roleBinding = (role, subject, target, domain) => {
   if (role === "subject") return subject;
   if (role === "target") return target;
   return (domain.classMembers[role] || [])[0];
@@ -213,12 +255,15 @@ const roleBinding = (role, subject, target, domain) => {
 const positionIn = (rows, term, predicate) =>
   rows.find((r) => r.subject === term && r.predicate === predicate)?.object;
 
-function applyEffects(effects, subject, target, state, domain) {
+export function applyEffects(effects, subject, target, state, domain) {
   let rows = state;
   let changed = false;
   for (const effect of effects) {
     const effSubject = roleBinding(effect.subjectRole, subject, target, domain);
-    const effObject = roleBinding(effect.objectRole, subject, target, domain);
+    // A literal-valued effect (a taught datatype flag) writes its value
+    // directly; a role-valued effect resolves objectRole through the
+    // grounding pair / class-bound member instead.
+    const effObject = effect.value !== undefined ? effect.value : roleBinding(effect.objectRole, subject, target, domain);
     const already = rows.some((r) =>
       r.subject === effSubject && r.predicate === effect.predicate && r.object === effObject);
     if (already) continue;

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

@@ -16,6 +16,19 @@ export const GRID_SIZE = 10;
 export const WEB_HOME = Object.freeze({ x: 2, y: 2 });
 export const WEB_RADIUS = 1;
 
+// A spider-built dynamic web (src/services/spider-fly.mjs's hasActiveWebAt)
+// stays active for this many turns past the turn it was built, mirroring the
+// static home zone's own always-on web without needing separate code paths.
+export const WEB_DURATION_TURNS = 10;
+
+// Spider mass mirrors a fly's own (src/services/spider-fly.mjs's
+// FLY_INITIAL_MASS/FLY_MASS_DECREMENT_PER_TURN): a spider starves like a fly
+// does, and gains exactly a fly's remaining mass on an eat. Heavier starting
+// mass than a single fly's worth on purpose — a spider that eats nothing for
+// a while has some runway before starving.
+export const SPIDER_INITIAL_MASS = 15;
+export const SPIDER_MASS_DECREMENT_PER_TURN = 1;
+
 export const cellId = (x, y) => `cell-${x}-${y}`;
 
 const CELL_ID_RE = /^cell-(\d+)-(\d+)$/;

package/src/domain/sprite-map.mjs

@@ -79,11 +79,53 @@ const ANIMAL_SVG =
   + '<g stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><line x1="7" y1="17" x2="7" y2="21"/><line x1="17" y1="17" x2="17" y2="21"/></g>'
   + "</svg>";
 
+// ---- the adventure world's own class family (PLAN_GAMES_UPLIFT_V2.md Part B)
+// — a room's floor plan, a piece of furniture, a portable, a person, the
+// player's own adventurer sprite, and a container. Ashcombe Hall's own
+// classes resolve to these directly (no ancestor walk needed, since the
+// shipped world has no rdfs:subClassOf chain at all yet); the walk stays
+// ready for a future world whose taxonomy goes deeper, the same "poodle IsA
+// dog" mechanism spider-fly already exercises.
+
+const ROOM_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="currentColor" stroke-width="1.6"/>'
+  + '<path d="M9 21 L9 13 A3 3 0 0 1 15 13 L15 21" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>';
+
+const FURNITURE_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="4" y="5" width="16" height="3" rx="1" fill="currentColor"/>'
+  + '<rect x="4" y="8" width="3" height="12" fill="currentColor"/>'
+  + '<rect x="17" y="8" width="3" height="12" fill="currentColor"/></svg>';
+
+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>';
+
+const PERSON_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'
+  + '<path d="M6 21 C6 15.5 8.7 13 12 13 C15.3 13 18 15.5 18 21 Z" fill="currentColor"/></svg>';
+
+// The adventurer is the player's own sprite — the same silhouette as `person`
+// plus a small satchel, so the one individual the player controls always
+// reads as visually distinct from the cast of NPCs sharing the room.
+const ADVENTURER_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'
+  + '<path d="M6 21 C6 15.5 8.7 13 12 13 C15.3 13 18 15.5 18 21 Z" fill="currentColor"/>'
+  + '<rect x="15.5" y="13.5" width="4.5" height="5" rx="1" fill="currentColor" opacity="0.6"/></svg>';
+
+const CONTAINER_SVG =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3" y="10" width="18" height="10" rx="1.2" fill="currentColor"/>'
+  + '<path d="M3 10 L5 5 H19 L21 10 Z" fill="currentColor" opacity="0.7"/>'
+  + '<rect x="10.6" y="9.4" width="2.8" height="2.2" rx="0.4" fill="currentColor" opacity="0.35"/></svg>';
+
 /** The sprite registry: class name (normFactTerm-normalized) -> inline SVG
  *  markup. `animal` is this world's declared root fallback (PLAN_SPIDER_FLY.md
  *  §7 names "animal"/"object"/"plant" as the family of possible roots — a
  *  spider-and-fly board only ever needs "animal") — resolveSpriteForClass
- *  falls back to it once the ancestor walk exhausts with no closer hit. */
+ *  falls back to it once the ancestor walk exhausts with no closer hit. The
+ *  adventure world's classes (room/furniture/portable/person/adventurer/
+ *  container) are a second, unrelated root family sharing the one flat table —
+ *  a board only ever resolves classes from its own world, so the two never
+ *  collide in practice. */
 export const SPRITE_REGISTRY = Object.freeze({
   spider: SPIDER_SVG,
   fly: FLY_SVG,
@@ -91,6 +133,12 @@ export const SPRITE_REGISTRY = Object.freeze({
   poodle: POODLE_SVG,
   dog: DOG_SVG,
   animal: ANIMAL_SVG,
+  room: ROOM_SVG,
+  furniture: FURNITURE_SVG,
+  portable: PORTABLE_SVG,
+  person: PERSON_SVG,
+  adventurer: ADVENTURER_SVG,
+  container: CONTAINER_SVG,
 });
 
 /** Every direct rdfs:subClassOf superclass of `term`, from a flat fact-row

package/src/services/adventure-autoplay.mjs

@@ -0,0 +1,192 @@
+// adventure-autoplay.mjs — a sibling layer over adventure.mjs (never edited
+// for this: this session's own in-flight rule-shape work owns that file)
+// that plays a loaded world by itself: infer a goal from one generic marker
+// fact, explore toward it, fetch it, and report an honest stall the moment no
+// further move is justified. It is a CALLER of the existing command
+// interpreter (adventureTurn), never a second one — every move it makes is
+// the same plain command string a human types ("go north", "take letter"),
+// executed through the identical turn a real chat session runs.
+//
+// The one hard constraint: auto-play only ever reasons over what it has
+// actually seen. `exposedRoomIds` is the set of rooms this auto-play run has
+// itself moved into (the opening room included from turn 0) — it is the sole
+// caller making every move, so it always knows this, and threads the set
+// forward turn to turn exactly like spider-fly.mjs threads its own agents
+// shape. `exposedFacts` turns that set into the actual filtered view: a fact
+// is exposed when its subject's CURRENT placement resolves into an exposed
+// room, when the subject is the player, or when the fact IS the world's
+// objective marker (told to the player unconditionally at turn 0, the same
+// way the opening line's prose already is). A hidden object's reveal falls
+// out of this automatically — no `mgx:hidden-in` special case is needed, the
+// placement-resolution walk already returns null for anything still hidden.
+//
+// The objective marker is one new, generic world-pack fact,
+// `{"subject":"letter","predicate":"mgx:is-objective","object":"true"}` —
+// deliberately not hard-coded to any one world. A world that ships no such
+// fact simply has nothing for this module to infer a goal toward.
+import { findActionPath } from "../domain/planning.mjs";
+import { loadMemory, readFactRows } from "../adapters/memory/core.mjs";
+import { foldWorldState, adventureTurn } from "./adventure.mjs";
+
+const SNAPSHOT_RE = /^(.+)@turn(\d+)$/;
+const baseSubjectOf = (subject) => SNAPSHOT_RE.exec(subject)?.[1] ?? subject;
+
+const isTypedRow = (rows, subject, type) =>
+  (rows || []).some((r) => r.subject === subject && r.predicate === "rdf:type" && r.object === type);
+
+/** The room a subject's CURRENT placement resolves into — a room resolves to
+ *  itself; an object placed directly in a room resolves to that room; an
+ *  object one containment hop inside an OPEN container resolves to the
+ *  container's own room; anything hidden, carried, or inside a closed
+ *  container resolves to nothing (null). This mirrors adventure.mjs's own
+ *  private `visibleRoomOf` exactly (that helper isn't exported, so the walk
+ *  is re-derived here against the same `foldWorldState` placements map,
+ *  never a second notion of visibility). */
+function roomOfSubject(subject, rows, state) {
+  if (isTypedRow(rows, subject, "room")) return subject;
+  const place = state.placements.get(subject);
+  if (!place || place.predicate === "mgx:hidden-in") return null;
+  if (place.predicate === "mgx:currently-in" || isTypedRow(rows, place.object, "room")) return place.object;
+  const holder = place.object;
+  if (holder === "player") return null; // carried, not resolvable to a room
+  if (!state.openness.get(holder)?.open) return null;
+  const holderPlace = state.placements.get(holder);
+  return holderPlace && holderPlace.predicate !== "mgx:hidden-in" ? holderPlace.object : null;
+}
+
+/**
+ * The subset of `allRows` this auto-play run may reason over, given the
+ * rooms it has actually moved into so far (`exposedRoomIds`). Pure — folds
+ * `allRows` itself rather than taking a precomputed state, so a caller never
+ * has to keep a fold in step with the exposure set by hand.
+ */
+export function exposedFacts(allRows, exposedRoomIds) {
+  const rows = allRows || [];
+  const state = foldWorldState(rows);
+  const exposed = new Set(exposedRoomIds || []);
+  return rows.filter((row) => {
+    if (baseSubjectOf(row.subject) === "player") return true;
+    if (row.predicate === "mgx:is-objective") return true;
+    const room = roomOfSubject(baseSubjectOf(row.subject), rows, state);
+    return room != null && exposed.has(room);
+  });
+}
+
+/** One hop per exposed room's own has-exit-* facts, sorted by direction name
+ *  for deterministic tie-breaking — the applyActions closure findActionPath
+ *  needs, built from the EXPOSED fold only, so a search over this graph can
+ *  never plan through an edge auto-play hasn't itself walked into. */
+function exposedExitApplyActions(exposedState) {
+  return (room) => {
+    const dirs = exposedState.exits.get(room);
+    if (!dirs) return [];
+    return [...dirs.keys()].sort().map((direction) => ({ action: direction, nextState: dirs.get(direction) }));
+  };
+}
+
+const unexposedExitsOf = (room, exposedState, exposed) =>
+  [...(exposedState.exits.get(room)?.entries() ?? [])].filter(([, target]) => !exposed.has(target));
+
+/**
+ * One auto-play tick over a live, loaded adventure: fold the world, infer a
+ * goal from the one generic objective marker under the exposure constraint,
+ * and execute exactly the one move that goal implies through `adventureTurn`
+ * — the same public entry point a real chat turn calls. Returns
+ * `{ turn, goal, plan, done, stalled, exposedRoomIds }`, mirroring
+ * spider-fly.mjs's own tick shape: `plan` is the remaining multi-step route a
+ * `findActionPath` search found this tick (or null when the move was a
+ * single, immediate step — an adjacent unexposed exit, or a take), `goal` is
+ * a short line describing what this tick did, `done` means the objective is
+ * now carried, `stalled` means no move could be justified without guessing.
+ */
+export async function runAdventureAutoplayTick(memoryDir, opts = {}) {
+  const { exposedRoomIds, planHolder, sessionId = "", env = {}, graph = null, cache = null } = opts;
+  const rows = readFactRows(await loadMemory(memoryDir));
+  const state = foldWorldState(rows);
+  const here = state.placements.get("player")?.object ?? null;
+  const exposed = new Set(exposedRoomIds || []);
+
+  if (!here) {
+    return {
+      turn: state.turnCount, goal: "stalled — no player position is written for this world.",
+      plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+    };
+  }
+  exposed.add(here);
+
+  const runCommand = (line) => adventureTurn(line, { planHolder, memoryDir, sessionId, env, graph, cache });
+
+  const exposedRows = exposedFacts(rows, exposed);
+  const exposedState = foldWorldState(exposedRows);
+  const objectiveId = exposedRows.find((r) => r.predicate === "mgx:is-objective" && r.object === "true")?.subject ?? null;
+
+  // Win: the objective is already carried — checked against the FULL fold,
+  // since what the player itself carries is always self-evidently known,
+  // the same unconditional "OR the subject is player" exposure the marker
+  // fact itself gets (worldDigestRows shows carried items regardless of
+  // room visibility too — carrying was never gated on being seen).
+  const carried = objectiveId
+    && state.placements.get(objectiveId)?.predicate === "mgx:located-in"
+    && state.placements.get(objectiveId)?.object === "player";
+  if (objectiveId && carried) {
+    return {
+      turn: state.turnCount, goal: `carrying the ${objectiveId} — the adventure is won.`,
+      plan: [], done: true, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  const objectiveRoom = objectiveId ? roomOfSubject(objectiveId, exposedRows, exposedState) : null;
+
+  if (objectiveId && objectiveRoom) {
+    if (objectiveRoom === here) {
+      await runCommand(`take ${objectiveId}`);
+      return {
+        turn: state.turnCount + 1, goal: `in the ${here} — taking the ${objectiveId}.`,
+        plan: null, done: false, stalled: false, exposedRoomIds: exposed,
+      };
+    }
+    const path = findActionPath(here, (room) => room === objectiveRoom, exposedExitApplyActions(exposedState));
+    if (!path || !path.actions.length) {
+      return {
+        turn: state.turnCount, goal: `stalled — no seen path from the ${here} to the ${objectiveRoom}.`,
+        plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+      };
+    }
+    await runCommand(`go ${path.actions[0]}`);
+    exposed.add(path.states[1]);
+    return {
+      turn: state.turnCount + 1, goal: `heading toward the ${objectiveRoom} for the ${objectiveId}.`,
+      plan: path.actions, done: false, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  // Explore: the objective either doesn't exist in this world, or its room
+  // isn't known yet. Prefer an immediate unexposed exit from here (the
+  // lowest-sorted direction); otherwise path toward the nearest exposed room
+  // that still has one.
+  const unexposedHere = unexposedExitsOf(here, exposedState, exposed).sort(([a], [b]) => a.localeCompare(b));
+  if (unexposedHere.length) {
+    const [direction, target] = unexposedHere[0];
+    await runCommand(`go ${direction}`);
+    exposed.add(target);
+    return {
+      turn: state.turnCount + 1, goal: `exploring — heading ${direction} into unseen ground.`,
+      plan: null, done: false, stalled: false, exposedRoomIds: exposed,
+    };
+  }
+
+  const hasUnexposedExit = (room) => unexposedExitsOf(room, exposedState, exposed).length > 0;
+  const path = findActionPath(here, hasUnexposedExit, exposedExitApplyActions(exposedState));
+  if (!path || !path.actions.length) {
+    return {
+      turn: state.turnCount, goal: "stalled — every reachable room is already explored, and no goal was ever found.",
+      plan: null, done: false, stalled: true, exposedRoomIds: exposed,
+    };
+  }
+  await runCommand(`go ${path.actions[0]}`);
+  exposed.add(path.states[1]);
+  return {
+    turn: state.turnCount + 1, goal: "exploring — backtracking toward unseen ground.",
+    plan: path.actions, done: false, stalled: false, exposedRoomIds: exposed,
+  };
+}