@polycode-projects/the-mechanical-code-talker 1.2.0 → 1.3.0

package/README.md

@@ -127,6 +127,15 @@ Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
 arbitrary fact, like "margo eats ribs", and it mints a fact you can later ask
 about directly: "what does margo eat", or "does margo eat ribs".
 
+New vocabulary compounds as you teach it. "redis is a cache" mints "redis" as
+a class-level concept even though it was never in the built-in lexicon, and a
+later "every cache is a store" does the same for "store," the other way
+round, as long as one side of the sentence is already grounded. tmct never
+mints a fact between two totally ungrounded terms; it declines and nudges you
+to ground one side first. Quantified teaching works too: "some functions are
+risky" stores the quantifier, and a later "how many functions are risky"
+answers "A few."
+
 ### Provenance and trust
 
 Every fact and text block records **where it came from and when**. Sources are

package/ROADMAP.md

@@ -35,6 +35,40 @@ Test count across the session's later stretch:
 | Tier 6 (the messy real user), 5 cycles, run alongside a background test-suite health pass | 1328 → 1345 |
 | Compound-name resolution (multi-word queries to joined-token symbol names) | 1345 → 1352 |
 | Vocabulary-growth mirror fix — known-subject/unknown-object mint (`unknownObjectFallback`), so new terms compound turn over turn | 1352 → 1355 |
+| `findActionPath` (`src/planning.mjs`) — generic bounded on-demand-successor state-space search, `PLAN_HANOI.md`'s Phase 2 kernel, proven against a small toy graph; not wired into chat, Hanoi itself not started | 1355 → 1361 |
+
+**INFBENCH re-measured against 1.2.0** (measurement-only dispatch, 2026-07-09): `INFBENCH_1.2.0.md`
+confirms chat/INF-A2 now closes to 100% (the cax-sco/proof-chase win the STATUS banner above already
+claimed) but also finds chat/INF-C1 has flipped from an honest ceiling to a genuine 93%-fabrication
+regression, traced to the new general-verb-to-predicate query lane answering "no" on an absent fact
+instead of declining — a real correctness bug, separate from and cheaper than the still-gating
+INF-B1 (`cax-dw`) work.
+
+**INF-C1 fabrication FIXED (2026-07-09, follow-up dispatch)**: `GENERAL_VERB_YESNO_RE`'s no-hit
+branch (`src/chat.mjs`) now declines (`null`) instead of asserting a confident "no" when no taught
+fact matches the queried subject/predicate/object triple, falling through to the ordinary
+honest-miss cascade — same convention as `WHO_OWNS_RE`'s own no-hit branch. Re-ran `npm run
+infbench`: chat/INF-C1 is back to **93% completion / 0% fabrication**, its `0.8.2`-era honest
+ceiling, exactly as predicted (up from `1.2.0`'s 0% completion / 93% fabrication). Everything else
+in the ladder is unchanged — still gated at INF-B1 (33% completion), unaffected by this fix.
+`npm test` 1361 → 1362 (this fix's own contribution; see `HANDOVER.md` for the combined total
+alongside the concurrent Rule-storage dispatch).
+
+**`PLAN_TAUGHT_RELATIONS.md`** (research/design, 2026-07-09, nothing implemented): scopes teaching
+tmct brand-new relations and rules through ordinary chat (a Prolog-style family tree — father,
+parent, grandparent, descendant — none of it hardcoded, all of it taught), reusing
+`findActionPath` for the hop-counted relation chase and a new sibling kernel, `findReachableSet`,
+for open-ended enumeration. Live-testing while designing it surfaced real, already-shipped gaps:
+the "is a kind of" teach phrasing isn't accepted anywhere today, a "parent" example in the original
+scoping conversation only worked by an accidental lexicon collision, and a wrapped property-teach
+shape (`TEACH_PROPERTY_RE`) has no groundedness check at all, unlike the newer subject/object
+mint-fallback pair's explicit discipline. See `HANDOVER.md` for the full finding list; this is
+next-session pickup material, not yet started.
+
+**`PLAN_TAUGHT_RELATIONS.md` Phase 3 — DONE (2026-07-09)**: the Rule storage foundation landed in
+`src/memory/core.mjs` (`RULE_CLASS`, `appendRule`, `findRuleByName`) — pure plumbing, zero
+`chat.mjs` change, reusing the existing Source/trust pipeline unmodified. `npm test` 1361 → 1371.
+Phase 4 (compose2 query-side wiring) is next in that plan's build order.
 
 ### Shipped this session
 
@@ -63,6 +97,17 @@ Test count across the session's later stretch:
   hand-rolled copy of `WALL_MISS_RE` with the real export; and extracted a shared session-driver
   helper (`test/helpers/session.mjs`), replacing 11 near-duplicate `drive()`/`driveSession()`
   implementations. Full detail is in `HANDOVER.md`'s "Test-suite health pass" entry.
+- **Vocabulary-growth mirror fix.** New vocabulary used to grow one-directionally only: "redis is
+  a cache" could mint the unknown subject "redis" because the object "cache" was already a known
+  noun, but the reverse ("every cache is a store," subject known, object unknown) declined
+  outright. Added `unknownObjectFallback`, gated on a genuine universal quantifier ("every"/"each"/
+  "all") so it can't reopen the general lexicon bypass the existing bare/"a" shapes rely on. A term
+  minted by either direction now grounds a later sentence exactly like a lexicon word, using
+  taught-only groundedness checks that deliberately exclude the bulk ConceptNet corpus seed (the
+  corpus mentions ordinary English words constantly and must never silently count as "grounded").
+  When both sides are totally ungrounded, tmct still declines, but now with an actionable grounding
+  nudge instead of a bare "I couldn't store that." New coverage in
+  `test/chat-teach-quantifier.test.mjs`.
 - **Compound-name resolution**, from the operator's own worked example: "the payment system" now
   finds `PaymentSystem`, `payment-system`, a compound path like
   `westfield-payment-system/src/MyCode.cs`, and an interface-style name like
@@ -985,14 +1030,22 @@ minimal benchmark domains before anything domain-general is attempted:
   slot (`game`) threaded through `createSession`/`runTurn` exactly the way `focus` already is,
   kept deliberately separate from the `pending` pagination field since a game must survive an
   aside mid-play, unlike a listing remainder.
-
-Both docs converge on the SAME one genuinely new primitive neither doc found already built
+- `PLAN_TAUGHT_RELATIONS.md` — teaching tmct brand-new relations and rules through ordinary chat
+  (a taught Prolog-style family tree, none of the kinship vocabulary hardcoded), the first of the
+  three to need a successor function SYNTHESIZED from data the user taught in an earlier turn,
+  rather than hand-written per domain the way Hanoi's `legalMoves` and guess-number's
+  interval-update rule are. Its own enumeration capability ("list the descendants of X," no fixed
+  goal) needs a genuine new sibling kernel, `findReachableSet`, since `findActionPath` only ever
+  searches toward one goal.
+
+All three docs converged on the one genuinely new primitive none of them found already built
 anywhere in tmct: something that computes a SUCCESSOR STATE (apply a chosen action, produce the
 next graph/belief to reason over) — every existing traversal (`ancestorsOf`, `computeFind`,
-`findIsaChain` itself) is read-only. That primitive, plus a still-open recognition question (how
-tmct notices "the user wants goal-directed action" at all, and whether multi-step execution needs
-confirmation before running) is the real next-session scope — a dedicated design/implementation
-session, not a routing fix.
+`findIsaChain` itself) is read-only. That primitive now exists (`findActionPath`, `src/planning.mjs`,
+shipped this session — see "Shipped this session" above), proven against a small toy graph but not
+wired into any of the three domains yet. The remaining next-session scope is that wiring, plus a
+still-open recognition question: how tmct notices "the user wants goal-directed action" at all, and
+whether multi-step execution needs confirmation before running.
 
 ### The design horizon
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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/chat.mjs

@@ -3831,9 +3831,15 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
   // session): a taught general-verb fact ("margo eats ribs") answered back
   // directly. Yes/no form matches the taught triple EXACTLY (subject +
   // predicate + object, via the SAME factTermVariants/normFactTerm matching
-  // WHO_OWNS_RE just used above) — no match is an honest, closed-world "no",
-  // never a guess. Open form lists every stored fact row for {subject,
-  // predicate} regardless of object.
+  // WHO_OWNS_RE just used above) — a hit is a confident "yes". INFBENCH 1.2.0
+  // fix: a no-hit here used to synthesize a confident "no", but "no matching
+  // triple found after one lookup" is NOT a proof of absence (this project's
+  // OWA/honesty discipline — see PLAN_INFERENCE_TESTING.md) — it's
+  // indistinguishable from "I simply don't know". So a no-hit now returns
+  // null (declining), same as WHO_OWNS_RE's own no-hit above, falling through
+  // to the ordinary honest-miss cascade instead of fabricating a "no". Open
+  // form lists every stored fact row for {subject, predicate} regardless of
+  // object.
   const genYN = q.match(GENERAL_VERB_YESNO_RE);
   if (genYN && !GENERAL_VERB_ANYWHERE_EXCLUDE_RE.test(q)) {
     const [, subjectRaw, verbRaw, objectRaw] = genYN;
@@ -3849,10 +3855,7 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
           .filter((f) => f.predicate === predicate && subjVariants.has(f.subject) && objVariants.has(f.object))
           .sort(byTrust)[0];
         if (hit) return { text: `yes — ${renderFactLine(hit)}`, replace: true, generalVerbQuery: true };
-        return {
-          text: `no — no remembered fact says ${subject.toLowerCase()} ${predicatePhrase(predicate)} ${object}.`,
-          replace: true, generalVerbQuery: true,
-        };
+        return null; // no remembered fact — the honest miss stands (never a guessed "no")
       }
     }
   }

package/src/memory/core.mjs

@@ -41,6 +41,9 @@ export const UTTERANCE_CLASS = "Utterance";
 export const FACT_CLASS = "Fact";
 export const MEMORY_SESSION_CLASS = "Session";
 export const SOURCE_CLASS = "Source";
+// PLAN_TAUGHT_RELATIONS.md Phase 3: a taught RULE (a composed/filtered/
+// recursive relation-shape) — a sibling of Fact, never a taught concept itself.
+export const RULE_CLASS = "Rule";
 
 export const SAID_IN_SESSION_PROP = "mgx:saidInSession";
 export const IN_REPLY_TO_PROP = "mgx:inReplyTo";
@@ -75,6 +78,13 @@ const MEMORY_VOCABULARY = [
   { prop: "rdf:object", note: "reified fact: the triple's object term" },
   { prop: "mgx:factProvenance", note: "LEGACY COMPAT SHIM: the ' | '-joined provenance tag string a fact came from; the source-of-truth is now the mgx:statedBy edges derived from it" },
   { prop: "mgx:factQuantifier", note: "OPTIONAL: the quantifier word a plural class-membership teach used ('every'/'some'/'a few'), for literal recall by 'how many Xs are Ys' — never real cardinality counting" },
+  { prop: "mgx:ruleName", note: "a taught Rule's own name (e.g. 'grandparent') — the query-dispatcher's lookup key, PLAN_TAUGHT_RELATIONS.md §2/§3" },
+  { prop: "mgx:ruleKind", note: "a taught Rule's SHAPE tag — the closed vocabulary compose2 | filter | recursive (structural, like 'Fact'/'Rule' themselves, never a domain word)" },
+  { prop: "mgx:ruleBase1", note: "compose2: the first hop's base relation name; filter: the base rule/relation being filtered (same 'base relation' role in both kinds, so the name is shared)" },
+  { prop: "mgx:ruleBase2", note: "compose2 only: the second hop's base relation name" },
+  { prop: "mgx:ruleFilterProperty", note: "filter only: the property literal candidates are filtered by (an mgx:hasProperty-shaped Fact lookup)" },
+  { prop: "mgx:ruleBaseCase", note: "recursive only: the base-case relation name (hop zero)" },
+  { prop: "mgx:ruleRecStep", note: "recursive only: the self-referential recursive-step relation name" },
   { prop: CREATED_AT_PROP, note: "when an individual was FIRST written, ISO-8601 (first-write-wins on upsert); the audit 'when', the recency input to trust, the novelty signal" },
   { prop: DERIVED_FROM_PROP, predicate: "derivedFrom", note: "umbrella: a Fact derived from a Source (or another Fact). ext ref prov:wasDerivedFrom (UNVERIFIED-pending-web-check)" },
   { prop: STATED_BY_PROP, predicate: "statedBy", note: "subPropertyOf derivedFrom: a Source directly asserts this Fact (one edge per independent source — replaces the factProvenance union)" },
@@ -328,7 +338,7 @@ function upsertEdge(payload, { predicate, prop }, edge) {
 /** Recount `classes[]` from the individuals — every memory class stays counted
  *  and sampled the way graph-build.mjs counts the code classes. */
 function recountClasses(payload) {
-  const names = [MEMORY_SESSION_CLASS, UTTERANCE_CLASS, FACT_CLASS, SOURCE_CLASS];
+  const names = [MEMORY_SESSION_CLASS, UTTERANCE_CLASS, FACT_CLASS, SOURCE_CLASS, RULE_CLASS];
   payload.classes = payload.classes.filter((c) => !names.includes(c?.name));
   for (const name of names) {
     const of = payload.individuals.filter((i) => i?.class === name);
@@ -582,6 +592,112 @@ export async function appendFacts(dir, facts) {
   return { ids, appended: ids.length, skipped };
 }
 
+// ---- Rules (PLAN_TAUGHT_RELATIONS.md Phase 3: storage foundation) -----------
+// A taught RULE — a composed/filtered/recursive relation SHAPE, distinct from a
+// plain Fact triple. Same convention as a Fact's subject/predicate/object: every
+// slot is a plain string ATTRIBUTE, never an edge to a per-term individual.
+
+export const RULE_KIND_COMPOSE2 = "compose2";
+export const RULE_KIND_FILTER = "filter";
+export const RULE_KIND_RECURSIVE = "recursive";
+export const RULE_KINDS = Object.freeze([RULE_KIND_COMPOSE2, RULE_KIND_FILTER, RULE_KIND_RECURSIVE]);
+
+export const RULE_NAME_PROP = "mgx:ruleName";
+export const RULE_KIND_PROP = "mgx:ruleKind";
+
+// Per-kind slot contract: JS slot key -> the mgx: attribute it's written under.
+// filter's "base" slot deliberately reuses ruleBase1 (not a fresh "ruleBase") —
+// §3's own query-dispatcher design chases a filter rule's candidate set via
+// "ruleBase1's candidate set (step (a) or (b) again)", the exact same attribute
+// name compose2's first hop already uses, since both play the identical "base
+// relation this rule builds on" role. Order within each array is the (slot1,
+// slot2) order the content-address hash below uses — fixed and load-bearing.
+const RULE_SLOT_SPEC = {
+  [RULE_KIND_COMPOSE2]: [["base1", "mgx:ruleBase1"], ["base2", "mgx:ruleBase2"]],
+  [RULE_KIND_FILTER]: [["base", "mgx:ruleBase1"], ["property", "mgx:ruleFilterProperty"]],
+  [RULE_KIND_RECURSIVE]: [["baseCase", "mgx:ruleBaseCase"], ["recStep", "mgx:ruleRecStep"]],
+};
+
+// The rule-id contract, mirroring factIdFor's (:456) NUL-delimited discipline
+// exactly: content-addressed over (kind, name, slot1, slot2), so re-teaching an
+// IDENTICAL rule (same kind + name + slots) upserts, never duplicates; teaching
+// a DIFFERENT rule under the SAME name (different slots) hashes to a distinct
+// id — both individuals exist side by side, the same way two different Facts
+// sharing a subject are two distinct Fact individuals, never a silent overwrite.
+const ruleIdFor = (kind, name, slot1, slot2) => `rule:${fnv1aHex(`${kind}\0${name}\0${slot1}\0${slot2}`)}`;
+
+/** Append one taught RULE (compose2 | filter | recursive) — a sibling of
+ *  appendFact (:462) for the relation-composition shapes PLAN_TAUGHT_RELATIONS.md
+ *  items 3/4/6 need, storing a `Rule` individual instead of a `Fact`. Same
+ *  load→mutate→write discipline via mutateMemory, same content-addressed-id
+ *  upsert convention as appendFact.
+ *
+ *  { name, kind, slots, provenance = "", createdAt = "" }: `kind` is the ONE
+ *  closed vocabulary this store needs to know — compose2 | filter | recursive,
+ *  three STRUCTURAL tags describing the SHAPE of what was taught (never a
+ *  domain word, the same way "Fact"/"Rule" describe the store's own shape, not
+ *  what's stored in it). `slots` is the matching per-kind object (RULE_SLOT_SPEC
+ *  above). `name` and every slot value are normFactTerm-normalized, exactly like
+ *  a Fact's subject/object.
+ *
+ *  Provenance/trust ride the EXACT SAME syncFactSources/recomputeFactTrust
+ *  pipeline appendFact uses, unmodified — neither function ever checks
+ *  `individual.class`, so a Rule carrying the same mgx:factProvenance compat
+ *  attribute + CREATED_AT_PROP gets the same Source-derivation + trust score an
+ *  ordinary Fact would. 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 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 id = ruleIdFor(kind, n, slotValues[0], slotValues[1]);
+  const label = labelOf(`${n} = ${kind}(${slotValues.join(", ")})`);
+  await mutateMemory(dir, (payload) => {
+    const prior = payload.individuals.find((x) => x?.id === id);
+    const priorProv = prior?.attributes?.find((a) => a?.prop === "mgx:factProvenance")?.value || "";
+    // Same union-of-tags discipline as appendFact — the compat string stays
+    // byte-identical in spirit; the Source edges below are DERIVED from it.
+    const provs = [...new Set([...priorProv.split(" | "), normText(provenance)].filter(Boolean))];
+    const createdAtVal = firstWriteCreatedAt(prior, createdAt); // first-write-wins
+    upsertIndividual(payload, {
+      id, label, class: RULE_CLASS,
+      derived_from: [], mentions: [],
+      attributes: [
+        { 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] })),
+        { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
+        ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
+      ],
+    });
+    // Same Source-derivation + trust-materialisation call appendFact makes —
+    // syncFactSources/recomputeFactTrust only ever touch fact.attributes/id/
+    // label, never fact.class, so a Rule individual rides it unmodified.
+    syncFactSources(payload, payload.individuals.find((x) => x?.id === id));
+    recountClasses(payload);
+  });
+  return { id };
+}
+
+/** Genericity lookup for the future query-dispatcher (PLAN_TAUGHT_RELATIONS.md
+ *  §2's closing paragraph / §3 step (b)): "what kind of thing is name X" — scan
+ *  for the Rule individual whose mgx:ruleName matches, the SAME lookup serving
+ *  every taught rule name uniformly (no per-rule-name branch). This phase only
+ *  proves the stored shape supports the lookup correctly; Phase 4/5/6 build the
+ *  actual kind-dispatch (compose2/filter/recursive branching) on top of this.
+ *  Returns the raw individual, or undefined if no Rule has that name. */
+export function findRuleByName(memory, name) {
+  const n = normFactTerm(name);
+  return (memory?.individuals || []).find(
+    (i) => i?.class === RULE_CLASS && (i.attributes || []).find((a) => a?.prop === RULE_NAME_PROP)?.value === n,
+  );
+}
+
 // ---- Chat-facing seams (W4 fact lookup + contradiction) ---------------------
 // The W4 fact-lookup THREADING lives in chat.mjs (NOT here); these pure readers
 // are the seam it calls so the answer layer ranks candidates by relevance ×

package/src/planning.mjs

@@ -0,0 +1,109 @@
+// planning.mjs — a domain-agnostic bounded state-space search primitive
+// (PLAN_HANOI.md's Phase 2 kernel, landed ahead of the phased plan as a
+// standalone proof that the mechanism works, per the operator's own framing:
+// "generalizing findIsaChain from 'walk pre-loaded class edges' to 'walk
+// on-demand successor states' is a moderate, in-house-idiom-consistent
+// extension, not a foreign paradigm").
+//
+// `src/syllogise.mjs`'s `findIsaChain` is, in shape, already a bounded rooted
+// BFS path search: it walks a FIXED, pre-loaded edge list (`typeEdges`/
+// `subClassEdges`) from a start node to a target set, frontier-expansion
+// style, checking the frontier for a hit BEFORE extending it one hop further,
+// stopping the instant a target is reached or the hop budget is exhausted.
+//
+// Real planning (Hanoi, or anything with actions) needs the same shape over a
+// state space where successors are NOT pre-loaded — they are generated ON
+// DEMAND by applying an action to the CURRENT state. `findActionPath` below
+// is that generalization: same frontier/seen-set/check-then-extend/shortest-
+// path discipline as `findIsaChain`, but the "edges" come from calling the
+// caller-supplied `applyActions(state)` fresh at every expansion, instead of
+// looking them up in a fixed array.
+//
+// Deliberately NOT sharing code with `findIsaChain` itself: that function's
+// edge lists are pre-built ONCE into a `Map` before the search loop even
+// starts (`subSucc`, `syllogise.mjs:291-296`) — a real, load-bearing
+// optimization for its domain (static edges, looked up many times) that does
+// not apply here (successors are computed fresh, never looked up twice for
+// the same state). Extracting a "shared" BFS core would either lose that
+// optimization or force `findActionPath` to fake a static edge list, so this
+// lands as an independent sibling, following the same DISCIPLINE, not the
+// same code path. `findIsaChain` itself is untouched by this file.
+//
+// Pure, no I/O, deterministic given a deterministic `applyActions`.
+
+/** Default state-identity key: plain values compare by `String()`, plain
+ *  objects by a stable-ish `JSON.stringify` (good enough for a toy/plain-
+ *  object state; a caller with a richer state shape should pass its own
+ *  `stateKey` that canonicalizes the fields that actually matter). */
+function defaultStateKey(state) {
+  if (state && typeof state === "object") return JSON.stringify(state);
+  return String(state);
+}
+
+/**
+ * Bounded, cycle-safe, shortest-path-first breadth-first search over a state
+ * space whose successors are generated ON DEMAND, not pre-loaded.
+ *
+ *   - `startState` — any value; identity for cycle-detection is derived via
+ *     `stateKey` (default: `String()`/`JSON.stringify()`).
+ *   - `isGoal(state) -> boolean` — goal predicate, checked BEFORE a state is
+ *     expanded (never after — see the hop-counting discipline below).
+ *   - `applyActions(state) -> Array<{ action, nextState }>` — the caller's
+ *     domain logic: given the CURRENT state, the legal (action, resulting-
+ *     state) pairs reachable in exactly one step. Called fresh every time a
+ *     state is expanded; nothing is precomputed or cached across calls.
+ *   - `opts.maxDepth` (default 50) — hop budget, mirrors `findIsaChain`'s
+ *     `maxHops`: the frontier is checked for the goal AT every depth up to
+ *     and including `maxDepth`, but never extended past it (check-then-
+ *     extend — `findIsaChain`'s own comment on this exact off-by-one:
+ *     "the frontier is checked AT every length up to and including maxHops,
+ *     never one hop beyond it").
+ *   - `opts.stateKey(state) -> string` — override the default identity key
+ *     when `startState`/successor states are richer than a plain
+ *     string/number/JSON-able object.
+ *
+ * Returns `{ actions: [...], states: [startState, ...,goalState] }` on
+ * success (the full action sequence AND the resulting state at each step, so
+ * a caller can actually execute the plan, not just know one exists), or
+ * `null` when no path reaches a goal state within `maxDepth` — an honest
+ * miss, never a guessed/truncated path.
+ *
+ * Cycle-safe via a `seen` state-key set (this function's direct precedent:
+ * `findIsaChain`'s own `seen` set, `syllogise.mjs:311`) — a state is only
+ * ever expanded once, the first (shortest) path to reach it, so a domain
+ * with cycles (two states that can reach each other) still terminates and
+ * still returns the correct shortest path, never loops.
+ */
+export function findActionPath(startState, isGoal, applyActions, { maxDepth = 50, stateKey = defaultStateKey } = {}) {
+  if (isGoal(startState)) return { actions: [], states: [startState] };
+
+  let frontier = [];
+  for (const { action, nextState } of applyActions(startState) || []) {
+    frontier.push({ state: nextState, actions: [action], states: [startState, nextState] });
+  }
+
+  // depth counts the LENGTH of the paths currently in `frontier` (1 at the
+  // first check) — exactly `findIsaChain`'s own "hop counts the LENGTH of the
+  // paths currently in frontier" discipline. Check-then-extend, and never
+  // extend past maxDepth: the frontier is checked at every depth up to and
+  // including maxDepth, never one hop beyond it (the off-by-one findIsaChain
+  // itself once had and fixed — not reintroduced here).
+  const seen = new Set([stateKey(startState)]);
+  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
+    for (const entry of frontier) if (isGoal(entry.state)) return { actions: entry.actions, states: entry.states };
+    if (depth === maxDepth) break; // budget exhausted — do not extend further
+    const next = [];
+    for (const entry of frontier) {
+      const key = stateKey(entry.state);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      for (const { action, nextState } of applyActions(entry.state) || []) {
+        const nk = stateKey(nextState);
+        if (seen.has(nk)) continue;
+        next.push({ state: nextState, actions: [...entry.actions, action], states: [...entry.states, nextState] });
+      }
+    }
+    frontier = next;
+  }
+  return null;
+}