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

package/ROADMAP.md

@@ -70,6 +70,92 @@ next-session pickup material, not yet started.
 `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.
 
+**`PLAN_TAUGHT_RELATIONS.md` Phase 1 — DONE (2026-07-09)**: Item 1 (relational fact teach,
+`RELATION_FACT_TEACH_RE` — "ahab is the father of john" mints an ordinary Fact via
+`generalVerbPredicate`, reused verbatim) and Item 5 (adjective-mint, `unknownAdjectiveFallback` —
+"the cache is bespoke" / "TaskController is bespoke" mint `mgx:hasProperty`) both landed in
+`src/chat.mjs`. Query-side readback for Item 1 needed zero new machinery ("what do you know about
+X" / "does X <role> Y" both already confirm it); Item 5's own groundedness guard needed tightening
+beyond the original design to avoid reopening the pinned "module is banana" regression — see
+`PLAN_TAUGHT_RELATIONS.md`'s "Phase 1 — DONE" note for the full adjustment, plus a sharper,
+live-confirmed restatement of that doc's Verification finding 4 (`isConversational`'s ≤3-word gate
+pre-empts the teach lane entirely for a short bare sentence, not just its decline text — flagged,
+not fixed, still out of scope). `npm test` 1371 → 1377.
+
+**`PLAN_TAUGHT_RELATIONS.md` Phase 6, KERNEL half — DONE (2026-07-09)**: `findReachableSet`
+(`src/planning.mjs`), a sibling of `findActionPath` with no `isGoal` at all — every state reachable
+from the start within `maxDepth` is a result, not just one goal. Shares only the frontier-seeding
+step with `findActionPath`; the expand loops stayed independent (halting/accumulation semantics
+differ enough to make a shared core more complex, not less). Proven against a toy graph with a real
+cycle and a same-length two-path convergence. `test/planning.test.mjs`, 5 new tests. The WIRING half
+(teach-shape recognizer + query-dispatcher branch, both in `chat.mjs`) is deliberately deferred,
+kernel-only per this task's own scoping — see `PLAN_TAUGHT_RELATIONS.md`/`HANDOVER.md` for detail.
+
+**`PLAN_TAUGHT_RELATIONS.md` Phase 2 — DONE (2026-07-09)**: closes Item 1's own live-found
+query-side gap ("is ahab the father of john" now resolves directly) and Item 2 (relation alias/union
+query-side chase — a taught "father ⊑ parent" alias lets "is ahab a parent of john" resolve off the
+father fact). One new recognizer (`RELATION_FACT_YESNO_RE`) and one new local helper
+(`relationFactsFor`) in `factReadBack`, tried BEFORE `ISA_ASK_RE` gets a chance at the overlapping
+shape. The teach-side "kind of"/"type of" fix (`stripKindOf`) is a genuine one-liner.
+`test/chat-taught-relations.test.mjs` (new file), 4 tests. `npm test` 1382 → 1386. Phase 4 (compose2
+rule, next in this plan's build order) reuses `relationFactsFor` as its own per-hop edge lookup.
+
+**`PLAN_TAUGHT_RELATIONS.md` Phase 4 — DONE (2026-07-09)**: Item 3 (fixed-hop `compose2` composition
+rule — "a grandparent is a parent of a parent" teaches a Rule, and "is ahab a grandparent of
+ishmael" resolves via a hop-counted `findActionPath` search over the taught father facts,
+alias-chased through "parent" via Phase 2's own `relationFactsFor`). The hop-counting discipline
+(`{ entity, hopsTaken }` state, `isGoal` requiring exactly 2 hops) is live-verified load-bearing: a
+1-hop and a 3-hop path through the SAME father/parent edges both correctly decline in the same store
+where the genuine 2-hop pair resolves yes. Full family-tree chain (two father facts + the alias + the
+compose2 rule) live-verified end-to-end via the piped CLI. `test/chat-taught-relations.test.mjs`
+extended with 5 more tests (9 total). `npm test` 1386 → 1391.
+
+**`PLAN_TAUGHT_RELATIONS.md` Phase 5 — DONE (2026-07-09)**: Item 4 (property-filtered composition
+rule — "a grandfather is a grandparent who is male" teaches a `filter`-kind Rule). Required
+refactoring Phase 2/4's `relAsk` dispatcher's three inline steps into one recursive closure,
+`resolveRelationChase`, so a filter rule's base resolves GENERICALLY — the function calling itself —
+whether the base is a plain taught relation or another Rule (e.g. compose2), never assuming which.
+A hit requires both the base chase to resolve AND the subject to carry the taught property
+(`mgx:hasProperty`); live-verified both failure modes separately (base fails outright vs. base holds
+but the property filter correctly excludes the candidate) plus a filter whose base is a plain
+relation (not a compose2 rule at all), proving the genericity. `test/chat-taught-relations.test.mjs`
+extended with 4 more tests (13 total). `npm test` 1391 → 1395.
+
+**`PLAN_TAUGHT_RELATIONS.md` Phase 6 — DONE (2026-07-09), WIRING half — the plan's build is now
+COMPLETE, all six items.** Item 6 (recursive/reachability rule — "a descendant is a parent, or a
+parent of a descendant" teaches a `recursive`-kind Rule; "list the descendants of ahab" enumerates
+the full reachability set via `findReachableSet`, the kernel half already shipped, reused unchanged).
+The query side is the one genuine kind-change among all six items (a reachability-SET enumeration,
+not a yes/no chase), landed as a sibling of Phase 5's `resolveRelationChase` rather than a fourth
+branch inside it — mirroring `findActionPath`/`findReachableSet`'s own sibling split at the kernel
+level. Cycle safety (two individuals mutually taught as each other's parent) and a malformed
+self-reference teach attempt (guarded for free by the teach regex's own backreference) both
+live-verified. `test/chat-taught-relations.test.mjs` extended with 5 more tests, including one
+comprehensive ALL-SIX-items integration test (18 total). `npm test` 1395 → 1400. **Nothing remains
+outstanding from `PLAN_TAUGHT_RELATIONS.md`'s original six-item scope.**
+
+**INFBENCH re-measured against 1.3.1** (measurement-only dispatch, 2026-07-09): `INFBENCH_1.3.1.md`
+finds the ladder unchanged, byte-for-byte, since `1.3.0` — the four `PLAN_TAUGHT_RELATIONS.md`
+phases that completed the plan (alias/union, `compose2`, property-filter, recursive/reachability
+wiring) don't touch any band, confirmed by a zero-diff row comparison of both runs' raw product
+files plus a direct check that no INFBENCH case's premises/query ever reach the new relational-teach
+phrasing. Still gated at INF-B1 (33% completion), unchanged for a fourth consecutive measured
+version — an honest, expected result given the new surface and the ladder measure different things.
+
+**`PLAN_TAUGHT_RELATIONS.md` live-testing follow-up — DONE (2026-07-09)**: the operator live-tested
+the full family-tree example end-to-end and found two real gaps, both fixed in `src/chat.mjs`. Gap 1:
+a recognized-but-unsatisfied relational query used to fall to the GENERIC structural wall instead of
+naming the relation — fixed by distinguishing "relation/rule name never taught" from "name known, this
+pair's chase came up short" right in the `(a0)` block, each with its own specific decline text. Gap 2:
+the REVERSE query shape ("who is the grandparent of john") didn't exist at all — new recognizer
+`RELATION_WHO_ASK_RE` + a new `(a0.2)` block in `factReadBack`, re-deriving `resolveRelationChase`'s
+same resolution logic (direct/alias/compose2/filter) walked backward from the object, reusing
+`findReachableSet` unmodified for the compose2 reverse hop-chase. Live-verified the operator's own
+repro exactly: "who is the grandparent of ishmael" → ahab (full 2-hop derivation cited); "who is the
+grandparent of john" → an honest empty (never a wrong guess). `test/chat-taught-relations.test.mjs`
+extended with 8 more tests (26 total). `npm test` 1400 → 1408, zero regressions. **Nothing remains
+outstanding from `PLAN_TAUGHT_RELATIONS.md`.**
+
 ### Shipped this session
 
 - **Tier 5** found 12 routing/recognition fixes across teach and recall: article/head-word gaps

package/package.json

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

@@ -1380,6 +1380,79 @@ const OWNS_TEACH_RE = /^([A-Za-z][\w'-]*(?:\s+[A-Z][\w'-]*)?)\s+(?:owns|maintain
  *  the yes/no readers below answer either phrasing identically. */
 const OWNS_PASSIVE_TEACH_RE = /^(.+?)\s+(?:is|are|was|were)\s+owned\s+by\s+([A-Za-z][\w'-]*(?:\s+[A-Z][\w'-]*)?)[.!?]*$/i;
 
+/** "<Name> is the <role> of <Name>" — the relational-fact teach declarative
+ *  (PLAN_TAUGHT_RELATIONS.md Item 1, Phase 1): a NAMED relationship between
+ *  two entities ("ahab is the father of john"), grouped here with the other
+ *  relational/possessive teach shapes above (ownership) since it's tried on
+ *  the SAME ownSrc in teachLane, right after OWNS_PASSIVE_TEACH_RE and before
+ *  SOME_A_FEW_RE — unconditionally ahead of generalVerbTeach's own call site,
+ *  so GENERAL_VERB_ANYWHERE_EXCLUDE_RE never gets a say. The literal "the" +
+ *  bare role-noun + "of" anchor is deliberate: PLAN_TAUGHT_RELATIONS.md's
+ *  Item 3 (a future, not-yet-implemented "a <rule> is a <relation> of a
+ *  <relation>" composition-rule teach shape) uses an INDEFINITE "a"/"an" in
+ *  the same slot instead, so the two shapes structurally can never collide —
+ *  this regex must keep requiring literal "the", never "a"/"an", so any
+ *  future Item 3 work stays disjoint from this one. Subject/object each use
+ *  the SAME 1-2-token name-capture convention OWNS_TEACH_RE's own subject/
+ *  owner already use. */
+const RELATION_FACT_TEACH_RE =
+  /^([\w'-]+(?:\s+[A-Z][\w'-]*)?)\s+(?:is|are|was|were)\s+the\s+([a-z][\w-]*)\s+of\s+([\w'-]+(?:\s+[A-Z][\w'-]*)?)[.!?]*$/i;
+
+/** "a <name> is a <base1> of a <base2>" — the fixed-hop COMPOSITION-RULE teach
+ *  declarative (PLAN_TAUGHT_RELATIONS.md Item 3, Phase 4): "a grandparent is a
+ *  parent of a parent" teaches a RULE (mgx:ruleKind "compose2"), never a Fact —
+ *  the query side chases it via a hop-counted findActionPath search (see
+ *  teachLane's own call site below and factReadBack's relational-query
+ *  dispatcher). Both slots use an INDEFINITE article ("a"/"an"), the
+ *  structural anchor that keeps this shape disjoint from Item 1's
+ *  RELATION_FACT_TEACH_RE just above: that regex requires a literal "the" +
+ *  a lone role word with no second "of"-clause; this one requires "a"/"an" in
+ *  BOTH determiner slots plus a second relation-name word after "of" — the
+ *  two can never both match the same input (re-verified against the real
+ *  regexes, not just the design doc's own claim). m[1] = the new rule name
+ *  ("grandparent"), m[2]/m[3] = the two base relation names ("parent",
+ *  "parent" — may differ, e.g. an out-of-scope "an aunt is a sibling of a
+ *  parent"). */
+const COMPOSE2_RULE_TEACH_RE =
+  /^an?\s+([a-z][\w-]*)\s+(?:is|are)\s+an?\s+([a-z][\w-]*)\s+of\s+an?\s+([a-z][\w-]*)[.!?]*$/i;
+
+/** "a <name> is a <base> who is <property>" — the PROPERTY-FILTERED
+ *  composition-rule teach declarative (PLAN_TAUGHT_RELATIONS.md Item 4,
+ *  Phase 5): "a grandfather is a grandparent who is male" teaches a RULE
+ *  (mgx:ruleKind "filter"), never a Fact. `m[1]` = the new rule name
+ *  ("grandfather"), `m[2]` = the base rule/relation name ("grandparent" —
+ *  may itself resolve as EITHER a plain taught relation OR another Rule,
+ *  e.g. a compose2 rule; the query-side dispatcher below handles either
+ *  generically, never assuming which), `m[3]` = the property literal
+ *  ("male"). Structurally disjoint from COMPOSE2_RULE_TEACH_RE (anchored on
+ *  a literal "who", never "of" a second time) and from
+ *  RECURSIVE_RULE_TEACH_RE below (anchored on "or", never "who") — the three
+ *  rule-teach shapes are told apart purely by their own distinct anchor
+ *  word ("of" only / "who" / "or … of … <same name>"), re-verified against
+ *  the real regexes, not just this claim. */
+const FILTER_RULE_TEACH_RE =
+  /^an?\s+([a-z][\w-]*)\s+(?:is|are)\s+an?\s+([a-z][\w-]*)\s+who\s+(?:is|are)\s+([a-z][\w-]*)[.!?]*$/i;
+
+/** "a <name> is a <baseCase>, or a <recStep> of a <name>" — the
+ *  RECURSIVE/REACHABILITY rule teach declarative (PLAN_TAUGHT_RELATIONS.md
+ *  Item 6, Phase 6): "a descendant is a parent, or a parent of a
+ *  descendant" teaches a RULE (mgx:ruleKind "recursive"), never a Fact. The
+ *  rule's OWN name reappears inside its own definition — the `\1`
+ *  backreference requires the recursive slot's trailing name to be the
+ *  LITERAL SAME word as `m[1]`, so a mismatched/malformed self-reference
+ *  ("a descendant is a parent, or a parent of a person") simply never
+ *  matches this regex at all — an honest structural decline, not a runtime
+ *  guess. `m[1]` = the new rule name ("descendant"), `m[2]` = the base-case
+ *  relation ("parent", hop zero), `m[3]` = the recursive step's first-hop
+ *  relation ("parent" again in the illustration, though `m[2]`/`m[3]` are
+ *  independently captured and need not be identical to each other — only
+ *  `m[1]`'s OWN name must recur at the end). Query side is a genuine
+ *  KIND-CHANGE (reachability-SET enumeration via `findReachableSet`,
+ *  src/planning.mjs) from items 3/4's single-target search — see the
+ *  RECURSIVE_LIST_ASK_RE query recognizer, below. */
+const RECURSIVE_RULE_TEACH_RE =
+  /^an?\s+([a-z][\w-]*)\s+(?:is|are)\s+an?\s+([a-z][\w-]*),?\s+or\s+an?\s+([a-z][\w-]*)\s+of\s+an?\s+\1[.!?]*$/i;
+
 /** "<X> is <adjective>" — the property teach payload (wrapper-REQUIRED): a lazy
  *  subject and a single bare complement word. Never matches the "is a <noun>"
  *  membership shape (that stays the ACE grammar's), so "remember that cache is
@@ -1701,6 +1774,99 @@ async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon })
   });
 }
 
+/** The adjective-MINT fallback (PLAN_TAUGHT_RELATIONS.md Item 1's sibling
+ *  design, Item 5, Phase 1): "mary is female" / "the cache is bespoke" — a
+ *  brand-new adjective with no lexicon entry at all, on a SUBJECT that's
+ *  already grounded (by ANY of the same senses isGroundedTerm already tests
+ *  for unknownObjectFallback, OR a bare Capitalized name-shaped token, the
+ *  exact convention OWNS_TEACH_RE's own bare-form gate uses). Deliberately
+ *  its own standalone function, tried ALONGSIDE unknownSubjectFallback rather
+ *  than nested inside it: unknownSubjectFallback's own very first line
+ *  (`classify(subjectRaw, lex)` truthy -> immediate `return null`) exists to
+ *  hand a KNOWN subject's ACE miss back as a real miss — precisely the case
+ *  this fallback needs to keep working for ("the cache is bespoke" — "cache"
+ *  is a known lexicon noun), so nesting this inside that early-return would
+ *  make it unreachable.
+ *
+ *  GROUNDING — property-specific, NOT unknownObjectFallback's class-mint
+ *  guard: no "every"-quantifier gate at all. A property claim is about ONE
+ *  entity, never a quantified class claim (unknownSubjectFallback's own
+ *  point 3 precedent: property assertions never carry a quantifier even
+ *  under "every"). So the guard here is SUBJECT-side only — isGroundedTerm,
+ *  OR a bare Capitalized token — and the OBJECT (the new adjective) is never
+ *  required to be independently grounded (minting it is the entire point).
+ *  UNKNOWN_SUBJECT_RE's own determiner alternation has no "the" (only
+ *  every/each/all/a/an), so a leading "the" rides into the subject capture
+ *  itself ("the cache") rather than being split off as a determiner — the
+ *  SAME leading-article strip normFactTerm (memory/core.mjs) applies before
+ *  storage is applied here too, purely for the groundedness check, so this
+ *  recognizes exactly the head noun ("cache") teachFact will actually store
+ *  under. Branch order mirrors unknownSubjectFallback's own noun-then-
+ *  adjective order: declines (null) first when the OBJECT already resolves
+ *  as a known NOUN or a fact-grounded CLASS term, so a genuine class-
+ *  membership sentence is never misread as a property. Matches
+ *  UNKNOWN_SUBJECT_RE verbatim (the same regex unknownObjectFallback already
+ *  reuses) and writes HAS_PROPERTY_PREDICATE, no quantifier, ever.
+ *
+ *  Sits strictly UPSTREAM of the pre-existing TEACH_PROPERTY_RE gap (the
+ *  wrapped-only surface that mints ANY bare complement word with zero
+ *  grounding check at all, e.g. "remember that zorp is florpy" —
+ *  Verification finding 3, PLAN_TAUGHT_RELATIONS.md): this fallback does not
+ *  close that gap (out of scope, a deliberate separate operator decision),
+ *  only adds a properly-grounded alternative ahead of it.
+ *
+ *  IMPLEMENTATION ADJUSTMENT found live (not in the original plan text): a
+ *  bare "module is banana" (a KNOWN lexicon-noun subject, NO article, NO
+ *  capitalization, an unrecognized bare object) is an EXISTING pinned
+ *  regression (test/chat-teach-quantifier.test.mjs, test/wiring-facts.test.mjs
+ *  — both from unknownObjectFallback's own commit 901528f) that must stay a
+ *  plain honest miss. unknownObjectFallback's own mint is guarded against
+ *  this exact shape by requiring a genuine "every/each/all" quantifier — but
+ *  a property claim never carries one (this function's whole premise), so a
+ *  plain "subject grounded via the static lexicon alone" test would
+ *  re-open precisely that regression for the property case instead. The
+ *  fix: a subject grounded ONLY by a bare static-lexicon match (no article,
+ *  no capitalization) does NOT qualify on its own — an article (stripped
+ *  above into `bareSubject`), a capitalized name-shape, or a PRIOR-TAUGHT
+ *  fact anchor (isGroundedByFact) each stand in as the "this is a deliberate
+ *  entity reference, not ordinary bare prose" signal a quantifier would
+ *  otherwise provide. "the cache is bespoke" and "Mary is female" both carry
+ *  one of those signals (the leading "the", and capitalization,
+ *  respectively); "module is banana" carries none. */
+async function unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon }) {
+  if (!memoryDir) return null;
+  const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
+  if (!m) return null;
+  const [, , subjectRaw, objectRaw] = m;
+  const { loadLexicon, lookupNoun, classify } = await import("./grammar/lexicon.mjs");
+  const lex = lexicon || loadLexicon();
+  // Y already a known NOUN or a fact-grounded CLASS term — a genuine class-
+  // membership sentence, unknownSubjectFallback/unknownObjectFallback's own
+  // territory (already had first refusal on it) — never misread as a property.
+  if (lookupNoun(lex, objectRaw) || GENERIC_ANCHOR_NOUNS.has(String(objectRaw).toLowerCase())
+    || (await isGroundedByFact(objectRaw, memoryDir))) return null;
+  // Subject-side groundedness — strip a leading "the"/"a"/"an" first
+  // (normFactTerm's own article-strip, mirrored here) so "the cache" checks
+  // groundedness under its real head noun "cache", the same spelling
+  // teachFact will actually normalize and store.
+  const bareSubject = subjectRaw.replace(/^(?:the|an?)\s+/i, "").trim() || subjectRaw;
+  const hadArticle = bareSubject !== subjectRaw;
+  const capitalized = /^[A-Z]/.test(bareSubject);
+  const factGrounded = await isGroundedByFact(bareSubject, memoryDir);
+  const genericAnchor = GENERIC_ANCHOR_NOUNS.has(bareSubject.toLowerCase());
+  // A bare (no article, no capitalization) subject grounded ONLY via the
+  // static lexicon is exactly the pinned "module is banana" shape — see this
+  // function's own docblock. Requires the article/capitalization/prior-fact
+  // signal ALONGSIDE (not instead of) lexicon groundedness before an
+  // article-only subject qualifies.
+  const lexiconGrounded = hadArticle && classify(bareSubject, lex) != null;
+  const subjectGrounded = capitalized || factGrounded || genericAnchor || lexiconGrounded;
+  if (!subjectGrounded) return null; // no deliberate-entity signal — never a guessed mint
+  return teachFact(memoryDir, sessionId, {
+    subject: subjectRaw, predicate: HAS_PROPERTY_PREDICATE, object: objectRaw,
+  });
+}
+
 // ---- BUG 3 (2026-07-09, operator-authorized generalizing — "I don't know
 // where that ban came from, overturn it. build it."): general verb-to-
 // predicate teaching. "remember tony has a hat" / "remember margo eats ribs"
@@ -1942,8 +2108,22 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
   // a "your" appearing mid-sentence; applied to both the bare and the
   // remember-wrapped surface.
   const stripYour = (s) => (s == null ? s : s.replace(/^your\s+/i, "a "));
-  const raw = stripYour(rawInput);
-  const wrapped = stripYour(wrappedInput);
+  // "X is a KIND OF Y" / "X is a TYPE OF Y" (PLAN_TAUGHT_RELATIONS.md Item 2,
+  // Phase 2): the teach-side half of this item is a ONE-LINE normalization,
+  // not new storage — "a father is a kind of parent" reaches NEITHER
+  // UNKNOWN_SUBJECT_RE nor BARE_DECLARATIVE_RE nor TEACH_PROPERTY_RE today,
+  // because every one of those regexes requires a SINGLE-token object and
+  // "kind of parent" is three tokens (Verification finding 1). Stripping the
+  // "kind/type of" run down to a bare "a "/"an " immediately after the
+  // is/are/was/were copula — BEFORE any teach regex ever sees the sentence —
+  // recognition stays exactly as closed as before (still only "X is a Y",
+  // just one more determiner-phrase spelling of "a"), no new mint path, no
+  // new predicate: "a father is a kind of parent" normalizes to "a father is
+  // a parent", which unknownSubjectFallback already stores as
+  // father ⊑ parent today (finding 2: "parent" is already a lexicon noun).
+  const stripKindOf = (s) => (s == null ? s : s.replace(/\b(is|are|was|were)\s+(?:an?\s+)?(?:kind|type)\s+of\s+/i, "$1 a "));
+  const raw = stripKindOf(stripYour(rawInput));
+  const wrapped = stripKindOf(stripYour(wrappedInput));
 
   // PRONOUN-SUBJECT GUARD — tried against BOTH surfaces (bare and remember-
   // wrapped; trailing punctuation stripped the same way the OWNS/SOME_A_FEW
@@ -1987,6 +2167,102 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
     if (stored) return stored;
   }
 
+  // RELATIONAL FACT — "<Name> is the <role> of <Name>" (PLAN_TAUGHT_RELATIONS.md
+  // Item 1, Phase 1). Grouped with the other relational/possessive teach shapes
+  // just above (both ownership forms), tried on the SAME ownSrc, unconditionally
+  // ahead of generalVerbTeach's own call site below so
+  // GENERAL_VERB_ANYWHERE_EXCLUDE_RE never gets a say. Predicate minting reuses
+  // generalVerbPredicate VERBATIM (no sibling function) — implementation-agnostic
+  // to part of speech, so a role noun like "father" mints mgx:father the same
+  // way a general verb would; an ordinary Fact, no new storage shape.
+  const rel = ownSrc.match(RELATION_FACT_TEACH_RE);
+  if (rel && memoryDir && !QUESTION_LEAD_RE.test(ownSrc)) {
+    const stored = await teachFact(memoryDir, sessionId, {
+      subject: rel[1], predicate: await generalVerbPredicate(rel[2]), object: rel[3],
+    });
+    if (stored) return stored;
+  }
+
+  // COMPOSE2 RULE TEACH — "a <name> is a <base1> of a <base2>"
+  // (PLAN_TAUGHT_RELATIONS.md Item 3, Phase 4): stores a RULE (appendRule,
+  // kind "compose2"), never a Fact — tried right after item 1's relational
+  // fact above, on the SAME ownSrc, disjoint from it by determiner alone (see
+  // COMPOSE2_RULE_TEACH_RE's own docblock). The query-side hop-counted chase
+  // lives in factReadBack's relational-query dispatcher.
+  const compose2 = ownSrc.match(COMPOSE2_RULE_TEACH_RE);
+  if (compose2 && memoryDir && !QUESTION_LEAD_RE.test(ownSrc)) {
+    try {
+      const { appendRule, RULE_KIND_COMPOSE2 } = await import("./memory/core.mjs");
+      const { id } = await appendRule(memoryDir, {
+        name: compose2[1],
+        kind: RULE_KIND_COMPOSE2,
+        slots: { base1: compose2[2], base2: compose2[3] },
+        provenance: teachProvenanceTag(sessionId, new Date().toISOString()),
+      });
+      if (id) {
+        return {
+          text: `noted — remembered: a ${compose2[1]} is a ${compose2[2]} of a ${compose2[3]}`,
+          via: "assert", miss: false,
+        };
+      }
+    } catch { /* malformed slots — fall through to the ordinary honest-miss cascade */ }
+  }
+
+  // FILTER RULE TEACH — "a <name> is a <base> who is <property>"
+  // (PLAN_TAUGHT_RELATIONS.md Item 4, Phase 5): stores a RULE (appendRule,
+  // kind "filter"), never a Fact — tried right after item 3's compose2
+  // block above, same ownSrc, disjoint from it by anchor word alone
+  // ("who", never a second "of" — see FILTER_RULE_TEACH_RE's own docblock).
+  // The query-side generic base-then-property chase lives in factReadBack's
+  // relational-query dispatcher (resolveRelation's own "filter" branch).
+  const filterRule = ownSrc.match(FILTER_RULE_TEACH_RE);
+  if (filterRule && memoryDir && !QUESTION_LEAD_RE.test(ownSrc)) {
+    try {
+      const { appendRule, RULE_KIND_FILTER } = await import("./memory/core.mjs");
+      const { id } = await appendRule(memoryDir, {
+        name: filterRule[1],
+        kind: RULE_KIND_FILTER,
+        slots: { base: filterRule[2], property: filterRule[3] },
+        provenance: teachProvenanceTag(sessionId, new Date().toISOString()),
+      });
+      if (id) {
+        return {
+          text: `noted — remembered: a ${filterRule[1]} is a ${filterRule[2]} who is ${filterRule[3]}`,
+          via: "assert", miss: false,
+        };
+      }
+    } catch { /* malformed slots — fall through to the ordinary honest-miss cascade */ }
+  }
+
+  // RECURSIVE RULE TEACH — "a <name> is a <baseCase>, or a <recStep> of a
+  // <name>" (PLAN_TAUGHT_RELATIONS.md Item 6, Phase 6): stores a RULE
+  // (appendRule, kind "recursive"), never a Fact. Tried alongside the other
+  // rule-teach shapes above, on the same ownSrc — RECURSIVE_RULE_TEACH_RE's
+  // own `\1` backreference already guarantees a malformed/mismatched
+  // self-reference never matches at all, so no extra validation is needed
+  // here beyond appendRule's own slot-presence check. The query-side
+  // reachability-SET enumeration (a genuine kind-change from the other two
+  // rule kinds' single-target search) lives in factReadBack's own
+  // RECURSIVE_LIST_ASK_RE dispatch, below.
+  const recursiveRule = ownSrc.match(RECURSIVE_RULE_TEACH_RE);
+  if (recursiveRule && memoryDir && !QUESTION_LEAD_RE.test(ownSrc)) {
+    try {
+      const { appendRule, RULE_KIND_RECURSIVE } = await import("./memory/core.mjs");
+      const { id } = await appendRule(memoryDir, {
+        name: recursiveRule[1],
+        kind: RULE_KIND_RECURSIVE,
+        slots: { baseCase: recursiveRule[2], recStep: recursiveRule[3] },
+        provenance: teachProvenanceTag(sessionId, new Date().toISOString()),
+      });
+      if (id) {
+        return {
+          text: `noted — remembered: a ${recursiveRule[1]} is a ${recursiveRule[2]}, or a ${recursiveRule[3]} of a ${recursiveRule[1]}`,
+          via: "assert", miss: false,
+        };
+      }
+    } catch { /* malformed slots — fall through to the ordinary honest-miss cascade */ }
+  }
+
   // "some Xs are Ys" / "a few Xs are Ys" (Feature A) — the plural class-
   // membership quantifier shape. ACE has no quantifier-phrase pattern at all
   // (parseAce never even attempts a fit), so this is ALWAYS a direct write,
@@ -2109,6 +2385,15 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
     // narrowing rules (the "both sides ungrounded" safety guard, etc.).
     const objectFallback = await unknownObjectFallback(payload, { memoryDir, sessionId, lexicon });
     if (objectFallback) return objectFallback;
+    // ADJECTIVE-MINT fallback (PLAN_TAUGHT_RELATIONS.md Item 5, Phase 1): tried
+    // right after unknownObjectFallback declines, so a grounded subject (static
+    // lexicon, a prior taught fact, or a bare Capitalized name) can mint a
+    // brand-new adjective's property fact. See unknownAdjectiveFallback's own
+    // docblock for the exact narrowing rules (the "both sides ungrounded"
+    // safety guard, and why this must be a standalone function rather than
+    // nested inside unknownSubjectFallback).
+    const adjectiveFallback = await unknownAdjectiveFallback(payload, { memoryDir, sessionId, lexicon });
+    if (adjectiveFallback) return adjectiveFallback;
     // PROPERTY teach — "remember/note that <X> is <adjective>": wrapper-REQUIRED
     // (a bare "X is deprecated" is never silently reified), and only after the
     // ACE grammar declined (unknown words / not the membership shape), so a
@@ -2899,6 +3184,22 @@ function predicatePhrase(predicate) {
 }
 const factPhrase = (f) => `${f.subject} ${predicatePhrase(f.predicate)} ${f.object}`;
 
+/** The mechanical INVERSE of generalVerbPredicate: recovers the bare role/verb
+ *  word a taught relational Fact's predicate was minted from ("mgx:father" ->
+ *  "father"), or null for a predicate that isn't the "mgx:<word>" mint shape at
+ *  all (a curated predicate like mgx:hasProperty/mgx:ownedBy/mgx:hasA never
+ *  names a chaseable relation, so callers below simply never match it against
+ *  a queried relation name). PLAN_TAUGHT_RELATIONS.md Phase 2/4's own shared
+ *  substrate: factReadBack's relational-query dispatcher (RELATION_FACT_YESNO_RE)
+ *  uses this to enumerate "which already-taught fact-predicates touch this
+ *  (subject, object) pair" without hand-rolling a second lemma table — the
+ *  SAME "mgx:<lemma>" shape generalVerbPredicate mints is simply read backward,
+ *  synchronously (no lemmatizer round-trip needed to go this direction). */
+function relationRoleWord(predicate) {
+  const m = /^mgx:([a-z][\w-]*)$/i.exec(String(predicate || ""));
+  return m ? m[1].toLowerCase() : null;
+}
+
 // ---- BUG 1 fix (2026-07-08): "what is a tree used for" filters to JUST the
 // UsedFor facts, instead of grammar.mjs's meta-whatis template's lazy tail
 // swallowing "tree used for" whole as one literal term (a guaranteed
@@ -3110,6 +3411,67 @@ async function synonymsOf(term) {
   return index.get(String(term || "").trim().toLowerCase()) || [];
 }
 
+/** "is/are/was/were <X> the/a/an <role> of <Y>" — the RELATIONAL-QUERY yes/no
+ *  reader (PLAN_TAUGHT_RELATIONS.md Phase 2, item 1's own query-side gap +
+ *  item 2's alias chase + Phase 4 item 3's compose2-rule chase, all three
+ *  dispatched from ONE recognizer — see factReadBack's own relAsk block for
+ *  the full 3-step lookup: direct fact, alias-chased fact, then compose2 rule).
+ *  Deliberately tried BEFORE ISA_ASK_RE gets a chance at this shape (see
+ *  factReadBack's own placement, ahead of ISA_ASK_RE's match site): "is ahab a
+ *  parent of john" ALSO fits ISA_ASK_RE's own "a"/"an" determiner alternation
+ *  (backtracking "parent of john" into ISA_ASK_RE's single free-form object
+ *  capture) — checked live, ISA_ASK_RE's own block always returns (a hit or an
+ *  explicit `return null`), so whichever regex's block runs FIRST wins the
+ *  shape outright; this is the same "add a more specific recognizer earlier in
+ *  the cascade" precedent WHO_OWNS_RE/ISA_ASK_RE themselves already set
+ *  relative to the more general readers below them. Accepts "the" (item 1's
+ *  own literal-"the" direct-fact query, "is ahab the father of john") AND
+ *  "a"/"an" (item 2/4's alias-chase and rule-chase queries, which need the
+ *  indefinite article since the relation/rule name being asked about is
+ *  itself often the more general or composed one) — the determiner carries no
+ *  write-time collision risk here the way RELATION_FACT_TEACH_RE vs
+ *  COMPOSE2_RULE_TEACH_RE's determiner split does, because this is a READ-side
+ *  reader with a single unified dispatcher, not two competing WRITE shapes.
+ *  Structurally disjoint from plain ISA_ASK_RE/OWNS_PASSIVE_YESNO_RE shapes
+ *  that have no trailing " of <Y>" clause at all (verified: "is a module a
+ *  component" — no "of" clause — never matches this regex; see this file's
+ *  own PLAN_TAUGHT_RELATIONS.md "Phase 2 — DONE" note for the full collision
+ *  analysis). */
+const RELATION_FACT_YESNO_RE =
+  /^(?:is|are|was|were)\s+([\w'-]+(?:\s+[A-Z][\w'-]*)?)\s+(?:the|an?)\s+([a-z][\w-]*)\s+of\s+([\w'-]+(?:\s+[A-Z][\w'-]*)?)[?.!\s]*$/i;
+
+/** "who is the grandparent of john" — the REVERSE relational-query reader
+ *  (Gap 2, live-tested 2026-07-09, PLAN_TAUGHT_RELATIONS.md follow-up).
+ *  RELATION_FACT_YESNO_RE just above needs BOTH subject and object (a yes/no
+ *  for one named pair); this is the missing mirror shape — given a relation
+ *  name and only the OBJECT, find every SUBJECT that satisfies it. Shares
+ *  RELATION_FACT_YESNO_RE's own "the"/"a"/"an" determiner alternation (same
+ *  reasoning: "who is the father of john" is a direct-name query, "who is a
+ *  parent of john" is an alias/rule-name query — no write-time collision risk
+ *  here either, this is a read-side reader). Structurally disjoint from
+ *  WHO_OWNS_RE ("who owns/maintains …", a different verb entirely) and from
+ *  AUTHOR_WHO_IS_RE (no trailing " of <Y>" clause at all, and gated to a
+ *  would-miss git-authorship lane that declines silently on a non-author
+ *  name, verified live). Dispatch lives in factReadBack's own (a0.2) block,
+ *  below — a `resolveRelationChaseReverse` closure re-deriving the SAME
+ *  resolution logic as (a0)'s `resolveRelationChase` (direct fact, alias via
+ *  findIsaChain, compose2 via a reverse hop-counted chase, filter via a
+ *  recursive base-then-property chase), walked backward from the object. */
+const RELATION_WHO_ASK_RE =
+  /^who\s+(?:is|are)\s+(?:the|an?)\s+([a-z][\w-]*)\s+of\s+([\w'-]+(?:\s+[A-Z][\w'-]*)?)[?.!\s]*$/i;
+
+/** "list the descendants of ahab" — the REACHABILITY-SET list query
+ *  (PLAN_TAUGHT_RELATIONS.md Item 6, Phase 6's wiring half): a genuine
+ *  KIND-CHANGE from RELATION_FACT_YESNO_RE just above — every entity
+ *  reachable from the named start entity through a taught `recursive` Rule,
+ *  not a single yes/no. `m[1]` = the rule's PLURAL name ("descendants",
+ *  singularized via singularizeSurface before the findRuleByName lookup —
+ *  the same naive plural fold SOME_A_FEW_RE's own teach-side surface already
+ *  uses elsewhere in this file), `m[2]` = the start entity ("ahab"). Dispatch
+ *  lives in factReadBack's own (a0.5) block, below — findRuleByName +
+ *  findReachableSet (src/planning.mjs), never a yes/no answer. */
+const RECURSIVE_LIST_ASK_RE = /^list\s+(?:the\s+|all\s+)?([a-z][\w-]*)\s+of\s+([\w'-]+(?:\s+[A-Z][\w'-]*)?)[?.!\s]*$/i;
+
 /** "is a module a component" — the yes/no vocabulary form the graph grammar
  *  doesn't parse; checked against the isa-family fact predicates only. */
 const ISA_ASK_RE = /^(?:is|are)\s+(?:an?\s+)?(.+?)\s+(?:a\s+kind\s+of|a\s+type\s+of|an?)\s+(.+?)[?.!\s]*$/i;
@@ -3561,8 +3923,11 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
     // not just the live playtest transcript. Excluded explicitly: ISA_ASK_RE
     // matches take the SAME priority here they get in the non-empty-rows
     // path below, and a leading "there" is existential, never a real named
-    // subject a property claim would name.
-    if (!ISA_ASK_RE.test(qHedge)) {
+    // subject a property claim would name. RELATION_FACT_YESNO_RE (Phase 2/4)
+    // gets the SAME exclusion for the SAME reason — "is ahab a parent of
+    // john" with truly zero facts remembered is an honest miss on the
+    // relational reader below, never a bogus adjective teach-offer here.
+    if (!ISA_ASK_RE.test(qHedge) && !RELATION_FACT_YESNO_RE.test(qHedge)) {
       const emptyIsAdj = qHedge.match(IS_ADJECTIVE_YESNO_RE);
       if (emptyIsAdj) {
         const rawSubject = emptyIsAdj[1].trim();
@@ -3610,6 +3975,472 @@ async function factReadBack(memoryDir, query, envelope, miss, graph = null, focu
     return renderMany(hits);
   }
 
+  // (a0) RELATIONAL FACT / ALIAS-CHASE / RULE-CHASE yes/no — "is/are/was/
+  // were <X> the/a/an <role> of <Y>" (PLAN_TAUGHT_RELATIONS.md Phase 2 item
+  // 1's own query-side gap + item 2's alias chase + Phase 4 item 3's
+  // hop-counted compose2 chase + Phase 5 item 4's property-filtered chase,
+  // all dispatched from ONE recognizer, tried BEFORE ISA_ASK_RE gets a
+  // chance at this shape — see RELATION_FACT_YESNO_RE's own docblock for why
+  // placement, not regex disjointness, keeps this ahead of ISA_ASK_RE). The
+  // actual dispatch lives in resolveRelationChase, below (a recursive
+  // closure, not four independent branches):
+  //   (i)  DIRECT — a fact already taught under the queried role word exactly
+  //        ("is ahab the father of john" against a literal mgx:father fact —
+  //        Phase 1's own live-found gap, closed here).
+  //   (ii) ALIAS CHASE (item 2) — the SAME candidate list, widened: any fact
+  //        connecting this exact (subject, object) pair whose OWN role word
+  //        reaches the queried name via a TAUGHT rdfs:subClassOf chain over
+  //        relation-NAME strings (findIsaChain, reused completely unmodified,
+  //        maxHops:2, corpus-excluded — the identical isTaught discipline the
+  //        cax-sco/scm-sco class-term proof chase below already uses, just
+  //        walked over relation names instead of class names).
+  //   (iii) COMPOSE2 RULE CHASE (Phase 4 item 3) — the queried name may itself
+  //        be an already-taught Rule (findRuleByName), not a plain relation at
+  //        all: a hop-counted findActionPath search over { entity, hopsTaken }
+  //        states, dispatching base1's edges at hop 0 and base2's edges at hop
+  //        1, requiring EXACTLY hopsTaken === 2 at the goal — never just
+  //        entity === target at any depth (the load-bearing nuance: a
+  //        coincidental 1-hop or 3-hop path through the SAME edge relation
+  //        must NOT falsely satisfy a rule that must be exactly 2 hops).
+  //   (iv) FILTER RULE CHASE (Phase 5 item 4) — the queried name may be a
+  //        `filter`-kind Rule: recursively resolve its OWN base (step i/ii OR
+  //        iii again, generic over which the base turns out to be — the same
+  //        function calls itself), then require the SUBJECT also carry the
+  //        taught property (mgx:hasProperty, a plain Fact lookup).
+  // (i) and (ii) share one candidate list (relationFactsFor); (iii)/(iv) reuse
+  // the SAME list-builder as their per-hop edge lookup, so all four steps
+  // agree on what "a fact under relation X" means. No hit at any step → null,
+  // the honest miss stands (never a guessed "no" — the same OWA discipline
+  // every other yes/no reader in this function follows).
+  const relAsk = qHedge.match(RELATION_FACT_YESNO_RE);
+  if (relAsk) {
+    const rawSubject = relAsk[1].trim();
+    const subject = IS_ADJECTIVE_PRONOUN_RE.test(rawSubject) ? (focusLabel || null) : rawSubject;
+    const relationName = relAsk[2].trim().toLowerCase();
+    const object = relAsk[3].trim();
+    if (subject) {
+      const isTaughtRow = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
+      const aliasSubClassEdges = rows
+        .filter((f) => f.predicate === SUBCLASS_PREDICATE && isTaughtRow(f))
+        .map((f) => [f.subject, f.object]);
+      const { findIsaChain: chaseAlias } = await import("./syllogise.mjs");
+      // Shared alias-chase substrate (item 2): every stored Fact whose
+      // predicate resolves — directly, or via a TAUGHT rdfs:subClassOf chain
+      // over relation-NAME strings, never corpus noise — to `name`. Reused for
+      // BOTH the direct/alias yes-no readback just below AND the compose2
+      // hop-search's per-hop edge lookup further down, so the two never
+      // disagree on what "a fact under relation X" means.
+      const relationFactsFor = (name) => {
+        const target = String(name || "").trim().toLowerCase();
+        const out = [];
+        for (const f of rows) {
+          const role = relationRoleWord(f.predicate);
+          if (!role) continue;
+          if (role === target) { out.push({ fact: f, aliasFacts: [] }); continue; }
+          const chain = chaseAlias(role, new Set([target]), [], aliasSubClassEdges, { maxHops: 2 });
+          if (!chain) continue;
+          const aliasFacts = chain.map((step) => rows.find(
+            (r) => r.predicate === SUBCLASS_PREDICATE && r.subject === step.subject && r.object === step.object,
+          ));
+          if (aliasFacts.every(Boolean)) out.push({ fact: f, aliasFacts });
+        }
+        return out;
+      };
+      // Generic relation-NAME resolver (PLAN_TAUGHT_RELATIONS.md Phase 5's
+      // own genericity requirement) — the SAME "what kind of thing is this
+      // name" dispatch §3 designs, made explicitly RECURSIVE so a Rule's
+      // own base can be EITHER a plain taught relation (terminal — steps
+      // i/ii, direct fact or alias chase) OR ANOTHER Rule (compose2's
+      // hop-counted chase, step iii; filter's own base-then-property chase,
+      // Phase 5 item 4, step iv). Returns `{ citation: string[] }` on a
+      // genuine hit, or null on an honest miss — never a guessed "no", the
+      // same OWA discipline every other yes/no reader in this function
+      // follows. Recursion is naturally bounded (§3.3): a filter rule's
+      // base is always either a plain relation (case a, terminal) or
+      // another rule (case b, one dispatch level deeper) — FILTER_RULE_TEACH_RE
+      // never lets a rule name its OWN name as its own base, so no cycle
+      // guard is needed at THIS dispatch level (the search kernels
+      // underneath — findActionPath — carry their own `seen`-set safety
+      // regardless).
+      const resolveRelationChase = async (name, subjectTerm, objectTerm) => {
+        const target = String(name || "").trim().toLowerCase();
+        // (i)+(ii): direct hit or alias-chased hit for this exact (subject,
+        // object) pair under the queried relation name.
+        const sv = factTermVariants(normFactTerm, subjectTerm);
+        const ov = factTermVariants(normFactTerm, objectTerm);
+        const pairHits = relationFactsFor(target).filter((e) => sv.has(e.fact.subject) && ov.has(e.fact.object));
+        if (pairHits.length) {
+          const hit = pairHits.slice().sort((a, b) => byTrust(a.fact, b.fact))[0];
+          return { citation: [renderFactLine(hit.fact), ...hit.aliasFacts.map(
+            (af) => `${factPhrase(af)}${af.provenance ? ` (source: ${af.provenance})` : ""}`,
+          )] };
+        }
+        // The queried name may itself be a taught RULE. findRuleByName is
+        // the SAME lookup §2/§3's own genericity design uses ("what kind of
+        // thing is X") — no per-rule-name branch, just a class/kind check.
+        const {
+          loadMemory, findRuleByName, RULE_KIND_PROP: ruleKindProp,
+          RULE_KIND_COMPOSE2: composeKind, RULE_KIND_FILTER: filterKind,
+        } = await import("./memory/core.mjs");
+        const memory = await loadMemory(memoryDir);
+        const rule = findRuleByName(memory, target);
+        const ruleKind = rule?.attributes?.find((a) => a.prop === ruleKindProp)?.value;
+        // (iii) COMPOSE2 RULE CHASE (Phase 4 item 3) — a hop-counted
+        // findActionPath search over { entity, hopsTaken } states,
+        // dispatching base1's edges at hop 0 and base2's edges at hop 1,
+        // requiring EXACTLY hopsTaken === 2 at the goal — never just
+        // entity === target at any depth.
+        if (rule && ruleKind === composeKind) {
+          const base1 = rule.attributes.find((a) => a.prop === "mgx:ruleBase1")?.value;
+          const base2 = rule.attributes.find((a) => a.prop === "mgx:ruleBase2")?.value;
+          const startEntity = normFactTerm(subjectTerm);
+          const targetEntity = normFactTerm(objectTerm);
+          if (!base1 || !base2 || !startEntity || !targetEntity) return null;
+          const { findActionPath } = await import("./planning.mjs");
+          const applyActions = (state) => {
+            if (state.hopsTaken >= 2) return [];
+            const relName = state.hopsTaken === 0 ? base1 : base2;
+            return relationFactsFor(relName)
+              .filter((e) => e.fact.subject === state.entity)
+              .map((e) => ({ action: e, nextState: { entity: e.fact.object, hopsTaken: state.hopsTaken + 1 } }));
+          };
+          const isGoal = (state) => state.hopsTaken === 2 && state.entity === targetEntity;
+          const stateKey = (state) => `${state.entity}#${state.hopsTaken}`;
+          const found = findActionPath({ entity: startEntity, hopsTaken: 0 }, isGoal, applyActions, { maxDepth: 2, stateKey });
+          if (!found) return null;
+          const seenAlias = new Set();
+          const parts = [];
+          for (const e of found.actions) {
+            parts.push(renderFactLine(e.fact));
+            for (const af of e.aliasFacts) {
+              const key = af.id || `${af.subject}|${af.predicate}|${af.object}`;
+              if (seenAlias.has(key)) continue;
+              seenAlias.add(key);
+              parts.push(`${factPhrase(af)}${af.provenance ? ` (source: ${af.provenance})` : ""}`);
+            }
+          }
+          return { citation: parts };
+        }
+        // (iv) FILTER RULE CHASE (Phase 5 item 4) — recursively resolve the
+        // base (a plain relation OR another rule — this SAME function,
+        // generic over which one it turns out to be), then filter by
+        // whether the SUBJECT carries the property literal
+        // (mgx:hasProperty, a plain Fact lookup over the already-loaded
+        // `rows`). A base chase that fails declines here too (never a
+        // guess); a base chase that succeeds but whose subject lacks the
+        // taught property declines as well — the filter correctly EXCLUDES
+        // that candidate rather than silently ignoring the property clause.
+        if (rule && ruleKind === filterKind) {
+          const base = rule.attributes.find((a) => a.prop === "mgx:ruleBase1")?.value;
+          const property = rule.attributes.find((a) => a.prop === "mgx:ruleFilterProperty")?.value;
+          if (!base || !property) return null;
+          const baseHit = await resolveRelationChase(base, subjectTerm, objectTerm);
+          if (!baseHit) return null;
+          const subjectEntity = normFactTerm(subjectTerm);
+          const propertyNorm = normFactTerm(property);
+          const propHit = rows.find(
+            (f) => f.predicate === HAS_PROPERTY_PREDICATE && f.subject === subjectEntity && normFactTerm(f.object) === propertyNorm,
+          );
+          if (!propHit) return null; // base relation holds, but the property filter excludes this candidate
+          return { citation: [...baseHit.citation, renderFactLine(propHit)] };
+        }
+        return null; // no remembered fact, alias, or rule (of any kind) reaches this
+      };
+      const hit = await resolveRelationChase(relationName, subject, object);
+      if (hit) return { text: `yes — ${hit.citation.join("; ")}`, replace: true };
+      // Gap 1 fix (live-tested 2026-07-09, PLAN_TAUGHT_RELATIONS.md follow-up):
+      // this used to `return null` unconditionally on any miss here — the
+      // SHAPE was already recognized (subject/relation/object all parsed
+      // successfully), so an ordinary `null` fell all the way through
+      // factReadBack's cascade to runTurn's GENERIC structural wall
+      // ("couldn't parse this as a graph question…"), which doesn't even
+      // mention the relation the user actually asked about. Distinguish two
+      // real cases, both rendered HERE (never deferred to the generic wall):
+      // (1) the relation/rule NAME itself was never taught at all — no fact
+      // or alias reaches it under any spelling, AND no Rule is stored under
+      // it either; (2) the name IS known, but THIS specific (subject,
+      // object) pair's chase came up short (e.g. a 2-hop rule with only 1
+      // hop of facts taught, or an unrelated pair) — an honest, specific
+      // decline that NAMES the relation, never a guessed "no".
+      const { loadMemory: loadMemForMiss, findRuleByName: findRuleByNameForMiss } = await import("./memory/core.mjs");
+      const memoryForMiss = await loadMemForMiss(memoryDir);
+      const nameKnown = relationFactsFor(relationName).length > 0
+        || !!findRuleByNameForMiss(memoryForMiss, relationName);
+      if (!nameKnown) {
+        return { text: `I don't know a relation or rule called '${relationName}' yet.`, replace: true };
+      }
+      return {
+        text: `I know the '${relationName}' relation, but I can't confirm ${subject} is the ${relationName} of ${object} from what you've told me.`,
+        replace: true,
+      };
+    }
+  }
+
+  // (a0.2) RELATION "WHO" REVERSE ASK — "who is the/a/an <relation> of <Y>"
+  // (Gap 2, live-tested 2026-07-09, PLAN_TAUGHT_RELATIONS.md follow-up):
+  // every relational-query recognizer built so far (RELATION_FACT_YESNO_RE,
+  // the (a0) block just above) requires BOTH subject and object — a yes/no
+  // answer for one named pair. This is the REVERSE shape: given a relation
+  // name and an OBJECT, find every SUBJECT that satisfies it. Re-derives
+  // relationFactsFor/resolveRelationChase's SAME resolution logic (never
+  // duplicating the SEARCH kernels themselves — findIsaChain, findReachableSet
+  // — only the small, cheap, pure list-builder around them), for the SAME
+  // reason (a0.5)'s own list block re-derives relationFactsFor rather than
+  // sharing it with (a0): RELATION_WHO_ASK_RE and RELATION_FACT_YESNO_RE never
+  // both match the same query (one starts with "who", the other with
+  // "is/are/was/were"), so the two blocks never run in the same call.
+  const whoAsk = qHedge.match(RELATION_WHO_ASK_RE);
+  if (whoAsk) {
+    const relationName = whoAsk[1].trim().toLowerCase();
+    const rawObject = whoAsk[2].trim();
+    const object = IS_ADJECTIVE_PRONOUN_RE.test(rawObject) ? (focusLabel || null) : rawObject;
+    if (object) {
+      const isTaughtRow = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
+      const aliasSubClassEdges = rows
+        .filter((f) => f.predicate === SUBCLASS_PREDICATE && isTaughtRow(f))
+        .map((f) => [f.subject, f.object]);
+      const { findIsaChain: chaseAliasWho } = await import("./syllogise.mjs");
+      // Same candidate-list shape as (a0)'s own relationFactsFor — every
+      // stored Fact whose predicate resolves, directly or via a TAUGHT
+      // rdfs:subClassOf chain over relation-NAME strings, to `name`.
+      const relationFactsForWho = (name) => {
+        const target = String(name || "").trim().toLowerCase();
+        const out = [];
+        for (const f of rows) {
+          const role = relationRoleWord(f.predicate);
+          if (!role) continue;
+          if (role === target) { out.push({ fact: f, aliasFacts: [] }); continue; }
+          const chain = chaseAliasWho(role, new Set([target]), [], aliasSubClassEdges, { maxHops: 2 });
+          if (!chain) continue;
+          const aliasFacts = chain.map((step) => rows.find(
+            (r) => r.predicate === SUBCLASS_PREDICATE && r.subject === step.subject && r.object === step.object,
+          ));
+          if (aliasFacts.every(Boolean)) out.push({ fact: f, aliasFacts });
+        }
+        return out;
+      };
+      const {
+        loadMemory: loadMemWho, findRuleByName: findRuleByNameWho, RULE_KIND_PROP: ruleKindPropWho,
+        RULE_KIND_COMPOSE2: composeKindWho, RULE_KIND_FILTER: filterKindWho,
+      } = await import("./memory/core.mjs");
+      const memoryWho = await loadMemWho(memoryDir);
+      // Generic REVERSE relation-NAME resolver — the mirror image of (a0)'s
+      // resolveRelationChase: given a relation/rule name and a FIXED OBJECT,
+      // return every { subject, citation } pair that satisfies it, instead of
+      // a single yes/no for a fixed (subject, object) pair. Recursion is
+      // bounded the SAME way (a0)'s own chase is (§3.3): a filter rule's base
+      // is always either a plain relation (terminal) or another rule (one
+      // level deeper), never itself.
+      const resolveRelationChaseReverse = async (name, objectTerm) => {
+        const target = String(name || "").trim().toLowerCase();
+        const ov = factTermVariants(normFactTerm, objectTerm);
+        // (i)+(ii): every direct/alias-chased fact under this name whose
+        // object matches the target — one result per distinct subject (the
+        // highest-trust fact when more than one reaches the same subject).
+        const directHits = relationFactsForWho(target).filter((e) => ov.has(e.fact.object));
+        if (directHits.length) {
+          const bySubject = new Map();
+          for (const e of directHits) {
+            if (!bySubject.has(e.fact.subject)) bySubject.set(e.fact.subject, []);
+            bySubject.get(e.fact.subject).push(e);
+          }
+          return [...bySubject.entries()].map(([subj, hits]) => {
+            const hit = hits.slice().sort((a, b) => byTrust(a.fact, b.fact))[0];
+            return {
+              subject: subj,
+              citation: [renderFactLine(hit.fact), ...hit.aliasFacts.map(
+                (af) => `${factPhrase(af)}${af.provenance ? ` (source: ${af.provenance})` : ""}`,
+              )],
+            };
+          });
+        }
+        const rule = findRuleByNameWho(memoryWho, target);
+        const ruleKind = rule?.attributes?.find((a) => a.prop === ruleKindPropWho)?.value;
+        // (iii) COMPOSE2 REVERSE CHASE — the same hop-counted search (a0)'s
+        // forward chase uses, walked BACKWARD: seed from the TARGET object,
+        // reverse-hop via base2's edges first (the SECOND forward hop,
+        // closest to the object), then base1's edges (the FIRST forward
+        // hop) — swapping which side of each fact is queried (object instead
+        // of subject) rather than building a new search kernel. Enumerates
+        // every subject reachable at EXACTLY 2 reverse hops (never just
+        // "reachable within budget" — the same exact-hop-count discipline
+        // (a0)'s own isGoal uses), via findReachableSet (already proven
+        // cycle-safe by item 6's own reachability-list wiring, (a0.5) below).
+        if (rule && ruleKind === composeKindWho) {
+          const base1 = rule.attributes.find((a) => a.prop === "mgx:ruleBase1")?.value;
+          const base2 = rule.attributes.find((a) => a.prop === "mgx:ruleBase2")?.value;
+          const targetEntity = normFactTerm(objectTerm);
+          if (!base1 || !base2 || !targetEntity) return [];
+          const { findReachableSet: findReachableSetWho } = await import("./planning.mjs");
+          const applyActionsRev = (state) => {
+            if (state.hopsTaken >= 2) return [];
+            const relName = state.hopsTaken === 0 ? base2 : base1;
+            return relationFactsForWho(relName)
+              .filter((e) => e.fact.object === state.entity)
+              .map((e) => ({ action: e, nextState: { entity: e.fact.subject, hopsTaken: state.hopsTaken + 1 } }));
+          };
+          const stateKeyRev = (state) => `${state.entity}#${state.hopsTaken}`;
+          const reached = findReachableSetWho(
+            { entity: targetEntity, hopsTaken: 0 }, applyActionsRev, { maxDepth: 2, stateKey: stateKeyRev },
+          );
+          return reached.filter((r) => r.node.hopsTaken === 2).map(({ node, path }) => {
+            const seenAlias = new Set();
+            const parts = [];
+            // path.actions was accumulated walking BACKWARD from the object
+            // (base2's edge first, base1's edge second) — reversed here so
+            // the citation reads in the natural subject-to-object order
+            // ("ahab fathers john; …; john fathers ishmael"), matching (a0)'s
+            // own forward-chase citation order rather than exposing the
+            // reverse-walk's internal accumulation order to the user.
+            for (const e of path.actions.slice().reverse()) {
+              parts.push(renderFactLine(e.fact));
+              for (const af of e.aliasFacts) {
+                const key = af.id || `${af.subject}|${af.predicate}|${af.object}`;
+                if (seenAlias.has(key)) continue;
+                seenAlias.add(key);
+                parts.push(`${factPhrase(af)}${af.provenance ? ` (source: ${af.provenance})` : ""}`);
+              }
+            }
+            return { subject: node.entity, citation: parts };
+          });
+        }
+        // (iv) FILTER REVERSE CHASE — reverse-chase the base (recursively,
+        // same as the forward filter chase — this SAME function calls
+        // itself), then filter the resulting subjects by whether EACH
+        // carries the taught property.
+        if (rule && ruleKind === filterKindWho) {
+          const base = rule.attributes.find((a) => a.prop === "mgx:ruleBase1")?.value;
+          const property = rule.attributes.find((a) => a.prop === "mgx:ruleFilterProperty")?.value;
+          if (!base || !property) return [];
+          const baseHits = await resolveRelationChaseReverse(base, objectTerm);
+          const propertyNorm = normFactTerm(property);
+          const out = [];
+          for (const bh of baseHits) {
+            const subjectEntity = normFactTerm(bh.subject);
+            const propHit = rows.find(
+              (f) => f.predicate === HAS_PROPERTY_PREDICATE && f.subject === subjectEntity && normFactTerm(f.object) === propertyNorm,
+            );
+            if (propHit) out.push({ subject: bh.subject, citation: [...bh.citation, renderFactLine(propHit)] });
+          }
+          return out;
+        }
+        return []; // no remembered fact, alias, or rule (of any kind) reaches this
+      };
+      const hits = await resolveRelationChaseReverse(relationName, object);
+      if (hits.length) {
+        const lines = hits.map((h) => `${h.subject} — ${h.citation.join("; ")}`);
+        return { text: lines.join("\n"), replace: true };
+      }
+      // Gap 1's SAME two-case honest-miss discipline, mirrored for the
+      // reverse shape: is the relation/rule name known at all, or known but
+      // empty for this particular object?
+      const nameKnownWho = relationFactsForWho(relationName).length > 0
+        || !!findRuleByNameWho(memoryWho, relationName);
+      if (!nameKnownWho) {
+        return { text: `I don't know a relation or rule called '${relationName}' yet.`, replace: true };
+      }
+      return {
+        text: `I don't know anyone who is the ${relationName} of ${object} from what you've told me.`,
+        replace: true,
+      };
+    }
+  }
+
+  // (a0.5) RECURSIVE-RULE REACHABILITY LIST — "list the <plural> of <X>"
+  // (PLAN_TAUGHT_RELATIONS.md Item 6, Phase 6's wiring half): a genuine
+  // KIND-CHANGE from the yes/no dispatcher just above — REACHABILITY-SET
+  // enumeration (every node ever reached), not single-target search.
+  // Dispatches to a `recursive`-kind taught Rule via the SAME "what kind of
+  // thing is this name" lookup (findRuleByName) the yes/no dispatcher uses,
+  // then calls findReachableSet (src/planning.mjs, Phase 6's own kernel
+  // half, landed unmodified here) seeded from baseCase's taught edges for
+  // the start entity, stepping via recStep's edges at every further hop.
+  // Renders each result with its own derivation path, mirroring the yes/no
+  // chain-citation style above (renderFactLine + interleaved alias-fact
+  // citations, deduped). No hit at all → null, the honest miss stands.
+  const listAsk = qHedge.match(RECURSIVE_LIST_ASK_RE);
+  if (listAsk) {
+    const ruleName = singularizeSurface(listAsk[1].trim().toLowerCase());
+    const rawSubject = listAsk[2].trim();
+    const subject = IS_ADJECTIVE_PRONOUN_RE.test(rawSubject) ? (focusLabel || null) : rawSubject;
+    if (subject) {
+      const {
+        loadMemory, findRuleByName, RULE_KIND_PROP: ruleKindProp, RULE_KIND_RECURSIVE: recKind,
+      } = await import("./memory/core.mjs");
+      const memory = await loadMemory(memoryDir);
+      const rule = findRuleByName(memory, ruleName);
+      const ruleKind = rule?.attributes?.find((a) => a.prop === ruleKindProp)?.value;
+      if (rule && ruleKind === recKind) {
+        const baseCase = rule.attributes.find((a) => a.prop === "mgx:ruleBaseCase")?.value;
+        const recStep = rule.attributes.find((a) => a.prop === "mgx:ruleRecStep")?.value;
+        const startEntity = normFactTerm(subject);
+        if (baseCase && recStep && startEntity) {
+          const isTaughtRow = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
+          const aliasSubClassEdges = rows
+            .filter((f) => f.predicate === SUBCLASS_PREDICATE && isTaughtRow(f))
+            .map((f) => [f.subject, f.object]);
+          const { findIsaChain: chaseAlias } = await import("./syllogise.mjs");
+          // Same alias-chase substrate the yes/no dispatcher's own
+          // relationFactsFor uses (re-derived here rather than shared across
+          // the two `if` blocks, which never run in the same call — one
+          // regex or the other matches, never both).
+          const relationFactsForList = (name) => {
+            const target = String(name || "").trim().toLowerCase();
+            const out = [];
+            for (const f of rows) {
+              const role = relationRoleWord(f.predicate);
+              if (!role) continue;
+              if (role === target) { out.push({ fact: f, aliasFacts: [] }); continue; }
+              const chain = chaseAlias(role, new Set([target]), [], aliasSubClassEdges, { maxHops: 2 });
+              if (!chain) continue;
+              const aliasFacts = chain.map((step) => rows.find(
+                (r) => r.predicate === SUBCLASS_PREDICATE && r.subject === step.subject && r.object === step.object,
+              ));
+              if (aliasFacts.every(Boolean)) out.push({ fact: f, aliasFacts });
+            }
+            return out;
+          };
+          // hop 0 (the base case) uses baseCase's edges; every hop after
+          // that uses recStep's edges — a plain hop counter would need to
+          // fold into the state-identity key (defeating dedup-by-node), so
+          // the dedup key is the ENTITY alone (stateKey below): once a node
+          // is reached via its SHORTEST path, a longer alternate path to the
+          // same node is correctly pruned, never re-recorded or re-expanded
+          // (this is also what makes a genuine cycle in the taught edges —
+          // e.g. two individuals mutually taught as each other's parent —
+          // terminate safely: the cyclic-back node is already `seen`).
+          const { findReachableSet } = await import("./planning.mjs");
+          const applyActions = (state) => {
+            const relName = state.hop === 0 ? baseCase : recStep;
+            return relationFactsForList(relName)
+              .filter((e) => e.fact.subject === state.entity)
+              .map((e) => ({ action: e, nextState: { entity: e.fact.object, hop: state.hop + 1 } }));
+          };
+          const stateKey = (state) => state.entity;
+          const results = findReachableSet({ entity: startEntity, hop: 0 }, applyActions, { maxDepth: 20, stateKey });
+          if (results.length) {
+            const lines = results.map(({ node, path }) => {
+              const seenAlias = new Set();
+              const parts = [];
+              for (const e of path.actions) {
+                parts.push(renderFactLine(e.fact));
+                for (const af of e.aliasFacts) {
+                  const key = af.id || `${af.subject}|${af.predicate}|${af.object}`;
+                  if (seenAlias.has(key)) continue;
+                  seenAlias.add(key);
+                  parts.push(`${factPhrase(af)}${af.provenance ? ` (source: ${af.provenance})` : ""}`);
+                }
+              }
+              return `${node.entity} — ${parts.join("; ")}`;
+            });
+            return { text: lines.join("\n"), replace: true };
+          }
+        }
+      }
+      return null; // no taught recursive rule of this name reaches anything — honest miss
+    }
+  }
+
   // (a) FORWARD membership — "is an X a Y". X's fact-subject candidates are the
   // term itself (a class word) AND, when it resolves in the graph, its class-noun
   // (an instance) — so "is app/lib/a.mjs a component" answers off "module …".

package/src/planning.mjs

@@ -40,6 +40,23 @@ function defaultStateKey(state) {
   return String(state);
 }
 
+/** The one-hop expansion of `startState` into an initial frontier of
+ *  `{ state, actions, states }` path-entries — IDENTICAL in both
+ *  `findActionPath` and `findReachableSet` below (seeding a frontier from a
+ *  start state has no goal/accumulation semantics to differ on: it is pure
+ *  "call `applyActions` once, wrap each result"), so this one small step is
+ *  genuinely, safely shared rather than duplicated verbatim in both
+ *  functions. See the file-header note above `findActionPath` for why the
+ *  REST of the two functions' bodies are deliberately NOT merged the same
+ *  way. */
+function seedFrontier(startState, applyActions) {
+  const frontier = [];
+  for (const { action, nextState } of applyActions(startState) || []) {
+    frontier.push({ state: nextState, actions: [action], states: [startState, nextState] });
+  }
+  return frontier;
+}
+
 /**
  * Bounded, cycle-safe, shortest-path-first breadth-first search over a state
  * space whose successors are generated ON DEMAND, not pre-loaded.
@@ -77,10 +94,7 @@ function defaultStateKey(state) {
 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] });
-  }
+  let frontier = seedFrontier(startState, applyActions);
 
   // 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
@@ -107,3 +121,107 @@ export function findActionPath(startState, isGoal, applyActions, { maxDepth = 50
   }
   return null;
 }
+
+// ---------------------------------------------------------------------------
+// findReachableSet — PLAN_TAUGHT_RELATIONS.md, Item 6 (recursive/reachability
+// rules) kernel half. Query-side need: "list every X reachable from Y" (e.g.
+// "list the descendants of ahab") is REACHABILITY-SET ENUMERATION, not
+// single-goal search — checked against `findActionPath` above's own body:
+// it returns the INSTANT the first goal-satisfying state is found (the
+// `for (const entry of frontier) if (isGoal(entry.state)) return …` line),
+// so there is no way to keep it running to collect every reachable node
+// without changing both its halting condition (early-return vs. never-
+// return-early) AND its return shape (one path vs. every path) — a
+// genuinely new function, not a parameter tweak, per the plan's own
+// analysis.
+//
+// Code-sharing decision (asked for explicitly, decided fresh here rather
+// than copying the plan doc's framing verbatim): the file-header reasoning
+// for why `findActionPath` is an independent SIBLING of `findIsaChain`
+// (lines 1-32) is "pre-built static edge maps vs. on-demand successor
+// generation don't share an implementation, only a discipline." That
+// reasoning does NOT distinguish `findActionPath` from `findReachableSet`
+// — both call the caller's `applyActions(state)` fresh at every expansion;
+// neither pre-builds anything. So on the file's own stated logic, these two
+// are legitimately closer to each other than either is to `findIsaChain`,
+// and it's worth asking whether MORE sharing is warranted here specifically
+// — not just repeating the same verdict by default.
+//
+// Having written both bodies out, the answer is: share the one step that is
+// truly identical (`seedFrontier` above — a single `applyActions(startState)`
+// call with no goal/accumulation semantics to differ on), but keep the main
+// expand-loop bodies independent. The reason isn't "different edge
+// generation" this time — it's that the two loops' HALTING and RESULT-
+// COLLECTION semantics are irreducibly different: `findActionPath` returns
+// the instant ANY frontier entry satisfies `isGoal`, discarding the rest of
+// the frontier and every state it hasn't reached yet; `findReachableSet`
+// never returns early, has no predicate at all, and must keep every
+// newly-seen state (not just one) across the entire bounded search. Forcing
+// both through one shared "expand a frontier" core would mean threading an
+// optional `isGoal` (or a sentinel "never" predicate) AND an accumulator
+// mode through a single function — that parameter surface would itself
+// recreate the complexity the merge was meant to remove, for a savings of
+// roughly the ~10-line inner loop. Given the file's own established
+// precedent of favoring readable independent siblings over cleverly
+// parameterized cores, and that the one truly shared step already isn't
+// duplicated (`seedFrontier`), landing this as an independent sibling
+// remains the right call — just not for the identical reason `findIsaChain`
+// vs. `findActionPath` had.
+/**
+ * Bounded, cycle-safe breadth-first ENUMERATION of every state reachable
+ * from `startState` within `maxDepth` hops — the reachability-set sibling of
+ * `findActionPath`'s single-goal search.
+ *
+ *   - `startState`, `applyActions`, `opts.maxDepth`, `opts.stateKey` — same
+ *     meaning and defaults as `findActionPath` (see above); successors are
+ *     generated ON DEMAND by calling `applyActions(state)` fresh at every
+ *     expansion, nothing precomputed or cached.
+ *   - Deliberately NO `isGoal` parameter: every state reachable from
+ *     `startState` (EXCLUDING `startState` itself — the start is where you
+ *     already are, not a reachable result) within the hop budget is a
+ *     result, not just one goal-satisfying state.
+ *
+ * Returns an array of `{ node, path: { actions, states } }` — one entry per
+ * distinct reachable state, `path` mirroring `findActionPath`'s own
+ * `{ actions, states }` return shape (the action sequence AND intermediate
+ * states from `startState` to that node), so a caller gets "how did we get
+ * here" for every reachable node, not just one. Returns `[]` (never
+ * `null`/`undefined`) when nothing is reachable within budget — reachability
+ * enumeration has no "miss" case the way single-goal search does; an empty
+ * result set is itself the honest, complete answer.
+ *
+ * Cycle-safe via the same `seen` state-key convention as `findActionPath`: a
+ * state is recorded (and expanded) only the FIRST time it is reached, so the
+ * shortest path to it is what gets stored, and a state reachable by two
+ * different routes (or sitting inside a genuine cycle) is reported exactly
+ * once, never duplicated, and never causes an infinite loop.
+ */
+export function findReachableSet(startState, applyActions, { maxDepth = 50, stateKey = defaultStateKey } = {}) {
+  let frontier = seedFrontier(startState, applyActions);
+
+  const seen = new Set([stateKey(startState)]);
+  const results = [];
+  // Single combined loop (not findActionPath's check-then-separate-extend):
+  // there is no per-iteration early return to protect here, so recording a
+  // newly-seen state and deciding whether to expand it past it can live in
+  // the same pass without losing any of findActionPath's check-then-extend
+  // discipline — a state discovered exactly at maxDepth is still recorded
+  // (it IS reachable within budget) but is never expanded past it.
+  for (let depth = 1; depth <= maxDepth && frontier.length; depth += 1) {
+    const next = [];
+    for (const entry of frontier) {
+      const key = stateKey(entry.state);
+      if (seen.has(key)) continue; // already recorded via an earlier (shorter-or-equal) path
+      seen.add(key);
+      results.push({ node: entry.state, path: { actions: entry.actions, states: entry.states } });
+      if (depth === maxDepth) continue; // recorded, but budget exhausted — do not expand further
+      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 results;
+}