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

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,227 @@
+// 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);
+}
+
+/** 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.
+ *
+ *   - `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 = 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
+  // 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;
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+}