@polycode-projects/the-mechanical-code-talker 1.0.9 → 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

@@ -20,7 +20,7 @@ Tiers 0, 1, 2, and 4 each closed in one pass. Tier 3 took 7 passes to track down
 turned up one genuinely important correctness bug alongside a batch of routing fixes. Full
 per-cycle detail is in `HANDOVER.md`'s "The dialogue-flow playtest loop" section.
 
-`npm test` is green at **1352** (up from 1258 at the start of this session). v1.0.7 is
+`npm test` is green at **1355** (up from 1258 at the start of this session). v1.0.7 is
 published (0.9.11 → 1.0.0 → 1.0.7 across an earlier session; the exact release chain and
 file:line detail are in `HANDOVER.md`). Nothing has pushed since, so the local version sits at
 1.0.9 per the bump-at-push-time policy.
@@ -34,6 +34,41 @@ Test count across the session's later stretch:
 | Tier 5 (teach + recall + reasoning in dialogue), 5 cycles | 1307 → 1328 |
 | 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
 
@@ -62,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
@@ -984,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.0.9",
+  "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

@@ -1474,6 +1474,112 @@ const SOME_A_FEW_RE = /^(some|a few)\s+([\w-]+)\s+are\s+([\w-]+)$/i;
  *  the ambiguity a fully free-form multi-word subject would otherwise have. */
 const UNKNOWN_SUBJECT_RE = /^(every\s+|each\s+|all\s+|a\s+|an\s+)?([\w-]+(?:\s+[\w-]+)?)\s+(?:is|are)\s+(?:an?\s+)?([\w-]+)$/i;
 
+/** ISA-family predicates (mirrors the private ISA_PREDICATES set defined near
+ *  memoryFacts, below, at module scope — both are simple top-level consts
+ *  evaluated once at load time, so referencing either from a function defined
+ *  earlier in this file is safe: no function here actually RUNS until well
+ *  after the whole module has finished loading). Named again here, right by
+ *  its one caller, so isGroundedByFact reads standalone. */
+const MINT_ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
+
+/** Small CLOSED set of generic English root nouns that count as always-
+ *  grounded anchor terms for the mint-fallbacks below (operator refinement,
+ *  2026-07-09) — deliberately NOT added to lexicon-core.json itself (that
+ *  file stays the curated ~180-word CODE vocabulary; these are ordinary-
+ *  English root nouns with no code meaning at all, confirmed absent from it
+ *  today). Their only job is to give a user who hits the "both sides
+ *  ungrounded" decline (groundingSuggestionMiss, below) an honest, guessable
+ *  way in: ground one brand-new term via one of THESE words first ("every
+ *  zorp is a thing"), then chain the other new term off the now-grounded one. */
+const GENERIC_ANCHOR_NOUNS = new Set(["thing", "concept", "object", "entity"]);
+
+/** Shared fact-groundedness primitive (Feature A mint-extension, point 2):
+ *  true when `term` already appears as the SUBJECT or OBJECT of a previously
+ *  taught isa-family fact (rdfs:subClassOf/rdf:type) in memory. A term minted
+ *  by EITHER mint-fallback below (this session, or an earlier one — this
+ *  reads persisted memory, not session-scoped state) is exactly as legitimate
+ *  an anchor for a NEW fact as a static lexicon-core.json word — the whole
+ *  point of this extension is letting new vocabulary compound turn over turn
+ *  ("every cache is a store" mints "store"; "every store is a container" then
+ *  needs "store" to read as known even though it's not in the static lexicon
+ *  at all). Read-only, reuses memoryFacts' plain read path (existence only —
+ *  no trust-ranking needed here) and normFactTerm's own normalization, so a
+ *  fact-grounded term matches under the EXACT spelling teachFact itself stored
+ *  it under. Failure-tolerated: no memory dir / no match → false, never a
+ *  guessed "yes". */
+async function isGroundedByFact(term, memoryDir) {
+  if (!memoryDir) return false;
+  const raw = String(term ?? "").trim();
+  if (!raw) return false;
+  const { normFactTerm } = await import("./memory/core.mjs");
+  const t = normFactTerm(raw);
+  if (!t) return false;
+  // TAUGHT-only (same discipline factReadBack's own cax-sco/scm-sco proof
+  // chase already uses, above, for the identical reason: the bulk background
+  // corpus band (ConceptNet, trust 0.7, seeded by the thousands on a fresh
+  // repo) mentions ordinary English words like "store"/"container" constantly
+  // — treating THOSE as "grounded" would silently reopen the general lexicon
+  // bypass this whole feature is deliberately narrow to avoid. Only what the
+  // OPERATOR actually taught (or a prior `tmct syllogise` entailment) anchors
+  // a term here. factRows (not memoryFacts) is used specifically because it's
+  // the one read path that carries sourceTypes for this filter.
+  const rows = await factRows(memoryDir);
+  const isTaught = (f) => !f.sourceTypes?.includes("corpus") && !f.sourceTypes?.includes("web");
+  return rows.some((f) => MINT_ISA_PREDICATES.has(f.predicate) && isTaught(f) && (f.subject === t || f.object === t));
+}
+
+/** Shared "is this term grounded in ANY sense" aggregate (Feature A mint-
+ *  extension, point 2's named shared helper) — a static lexicon word (any
+ *  part of speech, via `classify`), a GENERIC_ANCHOR_NOUNS root, OR a term
+ *  already anchored by a previously taught isa-family fact (isGroundedByFact,
+ *  above). Used by unknownObjectFallback's subject/object groundedness checks
+ *  below, where no part-of-speech branching follows — just "known or not".
+ *  (unknownSubjectFallback's own object-known check, above/below, stays
+ *  narrower and NOUN-specific — see its own comment — so an object that's
+ *  merely a known ADJECTIVE doesn't get misrouted into the class/subClassOf
+ *  branch instead of the property branch.) */
+async function isGroundedTerm(term, lex, memoryDir) {
+  const raw = String(term ?? "").trim();
+  if (!raw) return false;
+  if (GENERIC_ANCHOR_NOUNS.has(raw.toLowerCase())) return true;
+  const { classify } = await import("./grammar/lexicon.mjs");
+  if (classify(raw, lex)) return true;
+  return isGroundedByFact(raw, memoryDir);
+}
+
+/** The "both sides ungrounded" grounding NUDGE (operator refinement,
+ *  2026-07-09): reuses teachSuggestion's own "compute a hint, APPEND it to
+ *  the existing honest-miss message, never replace/silently guess" pattern
+ *  (see its docblock, above, and the "did"/"why" append-style construction in
+ *  teachLane's own final decline, below) for a DIFFERENT decline case —
+ *  rather than mint a relationship between two brand-new terms (a real
+ *  fabrication risk, unknownObjectFallback's own explicit safety guard,
+ *  below), teachLane's final honest-miss text gets an EXTRA appended nudge
+ *  whenever the declined payload fit the "X is/are Y" shape
+ *  (UNKNOWN_SUBJECT_RE) but NEITHER side is grounded — an honest, actionable
+ *  way in: ground one side via a GENERIC_ANCHOR_NOUNS root first ("every zorp
+ *  is a thing"), then chain the other off the now-grounded term. Deliberately
+ *  APPENDED rather than a replacement/short-circuit: a "both sides
+ *  ungrounded" is/are sentence with a KNOWN subject on one side (e.g. "module
+ *  is banana") never reaches this at all (isGroundedTerm(subject) is true, so
+ *  the very first return below fires) — that stays unknownObjectFallback's
+ *  own mint territory, entirely unaffected here. Returns "" (message
+ *  unchanged) whenever the payload doesn't fit the shape, or at least one
+ *  side IS already grounded — a DIFFERENT, more specific reason it declined,
+ *  where this nudge would be actively unhelpful noise. */
+async function ungroundedPairHint(payload, lexicon, memoryDir) {
+  if (!memoryDir) return "";
+  const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
+  if (!m) return "";
+  const [, , subjectRaw, objectRaw] = m;
+  const { loadLexicon } = await import("./grammar/lexicon.mjs");
+  const lex = lexicon || loadLexicon();
+  if (await isGroundedTerm(subjectRaw, lex, memoryDir)) return "";
+  if (await isGroundedTerm(objectRaw, lex, memoryDir)) return "";
+  return ` I don't know "${subjectRaw}" or "${objectRaw}" yet. Try grounding one first, e.g. `
+    + `"every ${subjectRaw} is a thing", then "every ${objectRaw} is a ${subjectRaw}".`;
+}
+
 /** The unknown-SUBJECT direct-write fallback (point 1 + point 2's bare-property
  *  extension): tried ONLY after the real ACE grammar (assertTurn) has already
  *  had its turn and declined. Declines itself (returns null, never a guess)
@@ -1485,18 +1591,25 @@ const UNKNOWN_SUBJECT_RE = /^(every\s+|each\s+|all\s+|a\s+|an\s+)?([\w-]+(?:\s+[
  *    - X is actually a KNOWN lexicon word — then the ACE grammar's own miss was
  *      a real structural/vocabulary problem elsewhere (e.g. Y itself unknown as
  *      the WRONG part of speech), never silently reinterpreted through this
- *      narrow exception;
- *    - Y resolves as NEITHER a known noun NOR a known adjective — the OBJECT
- *      must still be a term tmct actually knows; an unknown Y stays an honest
- *      miss (never a guess), exactly like the pre-existing "monkey is an
- *      animal" case.
- *  Y resolving as a NOUN writes rdfs:subClassOf (mirrors the ACE grammar's own
- *  subClassOf/typeAssertion pattern); Y resolving as an ADJECTIVE (and not also
- *  a noun) writes mgx:hasProperty (mirrors the wrapped "remember that X is
- *  deprecated" property frame — reused here for the bare/unwrapped form too,
- *  since the free pass is about the SUBJECT, not about the "remember that"
- *  wrapper). Only the "every" determiner records a quantifier (point 3: "a"/
- *  bare/"your" read as one specific entity, not a class-level generalization). */
+ *      narrow exception. (NOTE: this stays a STATIC-lexicon-only check,
+ *      deliberately not widened to isGroundedTerm — a subject that's grounded
+ *      only via a PRIOR taught fact, not the static lexicon, is precisely the
+ *      case unknownObjectFallback, below, owns instead.)
+ *    - Y resolves as NEITHER a known noun NOR a known adjective NOR a term
+ *      already grounded by a prior taught fact / a GENERIC_ANCHOR_NOUNS root
+ *      (Feature A mint-extension, point 2 — a term minted by
+ *      unknownObjectFallback, below, reads exactly as known here as any
+ *      lexicon word) — the OBJECT must still be a term tmct actually knows;
+ *      an unknown Y stays an honest miss (never a guess), exactly like the
+ *      pre-existing "monkey is an animal" case.
+ *  Y resolving as a NOUN (or fact-/anchor-grounded) writes rdfs:subClassOf
+ *  (mirrors the ACE grammar's own subClassOf/typeAssertion pattern); Y
+ *  resolving as an ADJECTIVE (and not also a noun) writes mgx:hasProperty
+ *  (mirrors the wrapped "remember that X is deprecated" property frame —
+ *  reused here for the bare/unwrapped form too, since the free pass is about
+ *  the SUBJECT, not about the "remember that" wrapper). Only the "every"
+ *  determiner records a quantifier (point 3: "a"/bare/"your" read as one
+ *  specific entity, not a class-level generalization). */
 async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }) {
   if (!memoryDir) return null;
   const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
@@ -1507,7 +1620,12 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }
   // A known X's own ACE miss is a real miss — never silently reinterpreted here.
   if (classify(subjectRaw, lex)) return null;
   const quantifier = /^every$/i.test((det || "").trim()) ? "every" : "";
-  if (lookupNoun(lex, objectRaw)) {
+  // Point 2 (mint-extension): a PRIOR turn's minted term, or a
+  // GENERIC_ANCHOR_NOUNS root, grounds Y just as legitimately as a static
+  // lexicon noun — both are always treated as class-level (never property),
+  // consistent with unknownObjectFallback (below) always minting a CLASS.
+  if (lookupNoun(lex, objectRaw) || GENERIC_ANCHOR_NOUNS.has(String(objectRaw).toLowerCase())
+    || (await isGroundedByFact(objectRaw, memoryDir))) {
     return teachFact(memoryDir, sessionId, {
       subject: subjectRaw, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier,
     });
@@ -1522,6 +1640,67 @@ async function unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon }
   return null; // Y unknown too — decline honestly, never guess
 }
 
+/** The unknown-OBJECT mint fallback (Feature A, 2026-07-09 operator-authorized
+ *  vocabulary-growth extension): the MIRROR of unknownSubjectFallback, above —
+ *  same "X is/are Y" payload shape (UNKNOWN_SUBJECT_RE, reused verbatim,
+ *  never a second regex for the identical shape), tried as a SIBLING call
+ *  right after unknownSubjectFallback in teachLane (below), but firing on the
+ *  OPPOSITE asymmetry: SUBJECT already grounded (a real lexicon-core.json
+ *  word of ANY part of speech, a GENERIC_ANCHOR_NOUNS root, OR a term a PRIOR
+ *  turn already minted via either fallback — isGroundedTerm, shared with this
+ *  check) and OBJECT completely ungrounded. Mints the object as a new
+ *  class-level concept (rdfs:subClassOf, same predicate/quantifier machinery
+ *  teachFact/unknownSubjectFallback already use) so ordinary conversation can
+ *  build up new vocabulary turn over turn: "every cache is a store" (subject
+ *  "cache" grounded via the static lexicon) mints "store"; a LATER "every
+ *  store is a container" then finds "store" grounded via the fact just
+ *  minted (not the static lexicon at all) and mints "container" the same way.
+ *
+ *  GATED ON A GENUINE UNIVERSAL QUANTIFIER ("every"/"each"/"all" — never bare/
+ *  "a"/"an"/"your"): minting a NEW CLASS-LEVEL CONCEPT is inherently a general
+ *  claim about a class, the same "every"/bare distinction unknownSubjectFallback's
+ *  own docblock already draws (point 3) between a class generalization and a
+ *  claim about ONE specific entity. This is load-bearing, not cosmetic: a bare
+ *  "module is banana" (a KNOWN lexicon subject, an unrecognized bare object,
+ *  NO determiner at all) is a pinned regression — it must stay a plain honest
+ *  miss, never silently minted — and a WRAPPED "remember that X is <adjective>"
+ *  (also determiner-less at the subject) must keep falling through to
+ *  TEACH_PROPERTY_RE's own, more permissive arbitrary-adjective path
+ *  unimpeded. Requiring the determiner keeps this fallback's mint exactly as
+ *  narrow as the vocabulary-growth feature actually needs (every required
+ *  test case in this feature's own spec phrases the mint sentence with
+ *  "every"), without swallowing either of those pre-existing shapes.
+ *
+ *  The critical safety guard (operator's own stated worry, mirrored from
+ *  unknownSubjectFallback's docblock): this must NEVER silently mint when
+ *  BOTH sides are ungrounded ("every zorp is a florp" — two brand-new,
+ *  never-seen terms with no relation to each other tmct actually knows) —
+ *  declines here (null), and teachLane's own final honest-miss text picks up
+ *  an appended grounding NUDGE for exactly this case (ungroundedPairHint,
+ *  above) — never a silent guess, never a silent hard-swallowed decline
+ *  either. Any OTHER decline (subject ungrounded + object grounded — not this
+ *  fallback's asymmetry; or both grounded — already known, nothing to mint;
+ *  or no genuine universal quantifier) falls through as a plain null,
+ *  letting the ordinary teachLane cascade (property teach, then the generic
+ *  honest-miss text) continue unaffected. */
+async function unknownObjectFallback(payload, { memoryDir, sessionId, lexicon }) {
+  if (!memoryDir) return null;
+  const m = String(payload).trim().match(UNKNOWN_SUBJECT_RE);
+  if (!m) return null;
+  const [, det, subjectRaw, objectRaw] = m;
+  if (!/^(?:every|each|all)$/i.test((det || "").trim())) return null; // class-level mint needs a real universal quantifier
+  const { loadLexicon } = await import("./grammar/lexicon.mjs");
+  const lex = lexicon || loadLexicon();
+  const subjectGrounded = await isGroundedTerm(subjectRaw, lex, memoryDir);
+  if (!subjectGrounded) return null; // ungrounded subject isn't this fallback's asymmetry — never a guessed mint
+  const objectGrounded = await isGroundedTerm(objectRaw, lex, memoryDir);
+  if (objectGrounded) return null; // object already known — nothing to mint
+  const quantifier = /^every$/i.test((det || "").trim()) ? "every" : "";
+  return teachFact(memoryDir, sessionId, {
+    subject: subjectRaw, predicate: SUBCLASS_PREDICATE, object: objectRaw, quantifier,
+  });
+}
+
 // ---- 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"
@@ -1922,6 +2101,14 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
     // the exact narrowing rules (object must still be known, etc.).
     const fallback = await unknownSubjectFallback(payload, { memoryDir, sessionId, lexicon });
     if (fallback) return fallback;
+    // MIRROR mint fallback (Feature A, 2026-07-09 operator-authorized vocabulary-
+    // growth extension): the known-subject/unknown-object asymmetry — tried
+    // right after the unknown-subject case declines, so a subject the STATIC
+    // lexicon (or a prior taught fact) already grounds can mint a brand-new
+    // object term. See unknownObjectFallback's own docblock for the exact
+    // narrowing rules (the "both sides ungrounded" safety guard, etc.).
+    const objectFallback = await unknownObjectFallback(payload, { memoryDir, sessionId, lexicon });
+    if (objectFallback) return objectFallback;
     // 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
@@ -1980,9 +2167,14 @@ async function teachLane(query, { memoryDir, sessionId = "", lexicon = null }) {
       + "I can only teach facts using tmct's own code-vocabulary nouns (like module, class, function…), "
       + "not arbitrary new terms."
     : "";
+  // Grounding NUDGE (operator refinement, 2026-07-09): APPENDED, never a
+  // replacement, exactly like "did" above — see ungroundedPairHint's own
+  // docblock for why this is scoped to the "both sides ungrounded, fits the
+  // X is/are Y shape" case only.
+  const groundingHint = await ungroundedPairHint(payload, lexicon, memoryDir);
   return {
     text: `I couldn't store that —${why} I remember facts in the shape "every X is a Y", where X and Y are `
-      + `words I know.${did} Type /memory to see what I already remember.`,
+      + `words I know.${did}${groundingHint} Type /memory to see what I already remember.`,
     via: "teach-miss", miss: true,
   };
 }
@@ -3639,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;
@@ -3657,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;
+}