@polycode-projects/the-mechanical-code-talker 1.4.0 → 1.5.2

package/src/memory/core.mjs

@@ -33,6 +33,8 @@ import { dirname, join } from "node:path";
 import { proseTokensFor, buildProseIndex } from "../prose.mjs";
 import { fnv1aHex } from "../hash.mjs";
 import { computeTrust, sessionReliabilityFrom, TRUST_SCORE_PROP, TRUST_INPUTS_PROP } from "./trust.mjs";
+import { assertIndividualValid } from "./shacl.mjs";
+import { findActionPath, findReachableSet } from "../planning.mjs";
 
 export const MEMORY_DIR_REL = join(".tmct", "memory");
 export const MEMORY_GRAPH_REL = join(MEMORY_DIR_REL, "graph.json");
@@ -269,10 +271,18 @@ export async function loadMemory(dir) {
  *  Fact still carrying only the old mgx:factProvenance string gets its Sources +
  *  statedBy edges + trust materialised on the next write of any kind. Part B3's
  *  actor-level (session-scoped) Source reliability rides the SAME cycle, after
- *  migration (so it sees every Fact's Sources, migrated or not). */
+ *  migration (so it sees every Fact's Sources, migrated or not).
+ *
+ *  `fn` may be async (PLAN_AGENTS.md §2.1's SHACL ingest gate: appendFact/
+ *  appendRule build their candidate individual, `await assertIndividualValid`
+ *  it, and only then upsert — all inside `fn`, so a rejection throws before
+ *  ANY mutation of `payload` happens and this function's write is never
+ *  reached). `await fn(payload)` is a documented no-op for every existing
+ *  SYNC caller (appendUtterance(s), appendFacts) — awaiting a non-Promise
+ *  value just resolves to it, byte-identical behaviour to calling it plain. */
 async function mutateMemory(dir, fn) {
   const payload = await loadMemory(dir);
-  const out = fn(payload) ?? payload;
+  const out = (await fn(payload)) ?? payload;
   migrateLegacyProvenance(out);
   recomputeSourceReliability(out);
   out.proseIndex = buildProseIndex(out.individuals);
@@ -408,11 +418,22 @@ function statedByObjectsFor(payload, factId) {
 }
 
 /** Recompute + materialise a Fact's trust cache (mgx:trustScore + the auditable
- *  mgx:trustInputs). Called exactly where a statedBy edge could have changed. */
-function recomputeFactTrust(payload, fact, nowMs = Date.now()) {
+ *  mgx:trustInputs). Called exactly where a statedBy edge could have changed.
+ *  `trustOpts` (optional) is the entailed hook (trust.mjs `computeTrust`'s
+ *  `premiseTrusts`/`ruleConfidence`) — threaded through from appendFact/
+ *  appendFacts's own opts so a rule (e.g. syllogise.mjs's cax-dw) can make its
+ *  conclusion's trust premise-derived (`min(premiseTrusts) × ruleConfidence`)
+ *  instead of riding the bare entailed prior. Absent (the default, `{}`), this
+ *  is a no-op passthrough — every existing caller's score is byte-identical
+ *  (PLAN_INFERENCE_TESTING.md §4 stage 2's exit criterion). */
+function recomputeFactTrust(payload, fact, nowMs = Date.now(), trustOpts = {}) {
   const sourceIds = statedByObjectsFor(payload, fact.id);
   const createdAt = (fact.attributes || []).find((a) => a?.prop === CREATED_AT_PROP)?.value || "";
-  const { score, inputs } = computeTrust({ sourceIds, createdAt }, sourcesByIdMap(payload), { now: nowMs });
+  const { score, inputs } = computeTrust({ sourceIds, createdAt }, sourcesByIdMap(payload), {
+    now: nowMs,
+    ...(Array.isArray(trustOpts?.premiseTrusts) ? { premiseTrusts: trustOpts.premiseTrusts } : {}),
+    ...(typeof trustOpts?.ruleConfidence === "number" ? { ruleConfidence: trustOpts.ruleConfidence } : {}),
+  });
   setAttr(fact, TRUST_SCORE_PROP, "trustScore", String(score));
   setAttr(fact, TRUST_INPUTS_PROP, "trustInputs", JSON.stringify(inputs));
 }
@@ -420,8 +441,9 @@ function recomputeFactTrust(payload, fact, nowMs = Date.now()) {
 /** Reconcile a Fact's Sources + statedBy edges with its (unchanged, compat)
  *  mgx:factProvenance string, then recompute its trust. ADD-only over
  *  deterministic Source ids and upsertEdge's subject>object dedupe, so it is
- *  idempotent and NEVER re-keys the fact (its id still hashes only (s,p,o)). */
-function syncFactSources(payload, fact, nowMs = Date.now()) {
+ *  idempotent and NEVER re-keys the fact (its id still hashes only (s,p,o)).
+ *  `trustOpts` passes straight through to recomputeFactTrust (see there). */
+function syncFactSources(payload, fact, nowMs = Date.now(), trustOpts = {}) {
   const prov = (fact.attributes || []).find((a) => a?.prop === "mgx:factProvenance")?.value || "";
   // a Source's createdAt candidate is the FIRST stating fact's createdAt (its
   // "first seen"), falling back to now — first-write-wins keeps the earliest.
@@ -435,7 +457,7 @@ function syncFactSources(payload, fact, nowMs = Date.now()) {
       subject: fact.id, object: sid, subjectLabel: fact.label, objectLabel: sourceLabel(sid),
     });
   }
-  recomputeFactTrust(payload, fact, nowMs);
+  recomputeFactTrust(payload, fact, nowMs, trustOpts);
 }
 
 /** Lazy, idempotent migration of the legacy provenance union (step (b)): any
@@ -685,8 +707,17 @@ const factIdFor = (s, p, o) => `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
 /** Append one grammar-derived OWL triple, RDF-reified: a `Fact` individual
  *  carrying rdf:subject / rdf:predicate / rdf:object (+ provenance). The
  *  Phase-2 ACE parser's write point. Same (s,p,o) → same id → upsert, never a
- *  duplicate. Returns { id }. */
-export async function appendFact(dir, { subject, predicate, object, provenance = "", createdAt = "", quantifier = "" } = {}) {
+ *  duplicate. `premiseTrusts`/`ruleConfidence` (optional) engage trust.mjs's
+ *  entailed hook — see recomputeFactTrust; a rule-derived write (e.g.
+ *  syllogise.mjs) passes these, a plain taught/asserted write omits them and
+ *  is byte-identical to before.
+ *
+ *  PLAN_AGENTS.md 2.1's SHACL ingest gate: the candidate Fact individual is
+ *  validated against ontology/memory-shapes.ttl (memory/shacl.mjs) BEFORE
+ *  upsertIndividual runs -- a violation throws here, inside mutateMemory's
+ *  `fn`, so the write never happens (mutateMemory's atomic write is never
+ *  reached; the on-disk graph is untouched). Returns { id }. */
+export async function appendFact(dir, { subject, predicate, object, provenance = "", createdAt = "", quantifier = "", premiseTrusts, ruleConfidence } = {}) {
   const s = normFactTerm(subject);
   const p = normText(predicate);
   const o = normFactTerm(object);
@@ -695,7 +726,7 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
   const text = `${s} ${p} ${o}`;
   const tokens = proseTokensFor({ doc: text });
   const q = normText(quantifier);
-  await mutateMemory(dir, (payload) => {
+  await mutateMemory(dir, async (payload) => {
     const prior = payload.individuals.find((x) => x?.id === id);
     const priorProv = prior?.attributes?.find((a) => a?.prop === "mgx:factProvenance")?.value || "";
     // The mgx:factProvenance union stays BYTE-IDENTICAL (a compat shim readers
@@ -706,7 +737,7 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
     // plain re-teach, never SILENTLY erases an already-recorded quantifier).
     const priorQ = prior?.attributes?.find((a) => a?.prop === "mgx:factQuantifier")?.value || "";
     const qVal = q || priorQ;
-    upsertIndividual(payload, {
+    const candidate = {
       id, label: labelOf(text), class: FACT_CLASS,
       derived_from: [], mentions: [],
       attributes: [
@@ -719,10 +750,12 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
         ...(tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: tokens.join(" ") }] : []),
         ...(qVal ? [{ prop: "mgx:factQuantifier", key: "quantifier", value: qVal }] : []),
       ],
-    });
+    };
+    await assertIndividualValid(candidate); // the SHACL gate -- throws, never writes, on a violation
+    upsertIndividual(payload, candidate);
     // Derive Source individuals + statedBy edges from the provenance union and
     // (re)materialise this fact's trust — the live half of steps (b)/(c).
-    syncFactSources(payload, payload.individuals.find((x) => x?.id === id));
+    syncFactSources(payload, payload.individuals.find((x) => x?.id === id), undefined, { premiseTrusts, ruleConfidence });
     recountClasses(payload);
   });
   return { id };
@@ -743,6 +776,10 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
  *  same statedBy Source edges, same mgx:trustScore, same first-write-wins
  *  createdAt. Malformed facts (missing subject/predicate/object) are SKIPPED (a
  *  bad row never aborts a 6 k-fact seed), not thrown as appendFact does.
+ *  Each fact may also carry `premiseTrusts`/`ruleConfidence` (optional) —
+ *  appendFact's own entailed-hook passthrough, batched: syllogise.mjs's
+ *  materializing pass is this function's main caller, so this is the write
+ *  path a rule's conclusion trust actually rides (recomputeFactTrust, above).
  *  Returns { ids, appended, skipped } — ids one per applied fact (in order),
  *  appended = ids.length, skipped = malformed count. */
 export async function appendFacts(dir, facts) {
@@ -761,6 +798,8 @@ export async function appendFacts(dir, facts) {
       provenance: normText(f?.provenance),
       createdAt: f?.createdAt || "",
       quantifier: normText(f?.quantifier),
+      premiseTrusts: Array.isArray(f?.premiseTrusts) ? f.premiseTrusts : undefined,
+      ruleConfidence: typeof f?.ruleConfidence === "number" ? f.ruleConfidence : undefined,
     });
   }
   const ids = [];
@@ -770,6 +809,7 @@ export async function appendFacts(dir, facts) {
     const byId = new Map(payload.individuals.map((i) => [i?.id, i]));
     const touched = [];
     const seen = new Set();
+    const trustOptsById = new Map();
     for (const f of prepared) {
       const prior = byId.get(f.id);
       const priorProv = prior?.attributes?.find((a) => a?.prop === "mgx:factProvenance")?.value || "";
@@ -800,10 +840,19 @@ export async function appendFacts(dir, facts) {
       byId.set(f.id, ind);
       ids.push(f.id);
       if (!seen.has(f.id)) { seen.add(f.id); touched.push(f.id); }
+      // Last-prepared-row-wins per id for the trust hook opts (mirrors the
+      // provenance/quantifier/ind upsert above, which is also last-wins per id
+      // within one batch — a duplicate id inside the same call is rare, but
+      // when it happens the SAME single-write-per-id discipline applies here).
+      if (f.premiseTrusts !== undefined || f.ruleConfidence !== undefined) {
+        trustOptsById.set(f.id, { premiseTrusts: f.premiseTrusts, ruleConfidence: f.ruleConfidence });
+      }
     }
     // Reconcile each touched fact's Sources + trust once (add-only, idempotent),
-    // then recount classes a SINGLE time at the end.
-    for (const id of touched) syncFactSources(payload, byId.get(id));
+    // then recount classes a SINGLE time at the end. trustOptsById threads the
+    // entailed hook (recomputeFactTrust, above) per fact — absent for a fact
+    // that didn't declare premiseTrusts, so its trust is unchanged from before.
+    for (const id of touched) syncFactSources(payload, byId.get(id), undefined, trustOptsById.get(id));
     recountClasses(payload);
   });
   return { ids, appended: ids.length, skipped };
@@ -861,7 +910,12 @@ const ruleIdFor = (kind, name, slot1, slot2) => `rule:${fnv1aHex(`${kind}\0${nam
  *  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 }. */
+ *  ordinary Fact would.
+ *
+ *  PLAN_AGENTS.md 2.1's SHACL ingest gate: the candidate Rule individual is
+ *  validated against ontology/memory-shapes.ttl (memory/shacl.mjs) BEFORE
+ *  upsertIndividual runs, same discipline as appendFact -- a violation
+ *  throws before mutateMemory's write is ever reached. 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)}`);
@@ -873,14 +927,14 @@ export async function appendRule(dir, { name, kind, slots, provenance = "", crea
   }
   const id = ruleIdFor(kind, n, slotValues[0], slotValues[1]);
   const label = labelOf(`${n} = ${kind}(${slotValues.join(", ")})`);
-  await mutateMemory(dir, (payload) => {
+  await mutateMemory(dir, async (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, {
+    const candidate = {
       id, label, class: RULE_CLASS,
       derived_from: [], mentions: [],
       attributes: [
@@ -891,7 +945,9 @@ export async function appendRule(dir, { name, kind, slots, provenance = "", crea
         { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
         ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
       ],
-    });
+    };
+    await assertIndividualValid(candidate); // the SHACL gate -- throws, never writes, on a violation
+    upsertIndividual(payload, candidate);
     // 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.
@@ -915,6 +971,213 @@ export function findRuleByName(memory, name) {
   );
 }
 
+// ---- Relation chase (extracted from chat.mjs's (a0)/(a0.2) blocks,
+// PLAN_TAUGHT_RELATIONS.md Phase 2/4/5; PLAN_COMPLETIONS.md Stage 1
+// prerequisite) --------------------------------------------------------------
+//
+// `resolveRelationChase` and `resolveRelationChaseReverse` were originally
+// unexported closures inside chat.mjs's factReadBack, coupled to its own
+// local `rows`/`memoryDir`/`byTrust`/`renderFactLine`/`factPhrase`/
+// `factTermVariants` variables. Moved here — findRuleByName's natural
+// sibling, since this file already owns Rule storage/lookup — as plain,
+// standalone, importable functions so Stage 1's cross-group inference can
+// reuse the SAME resolution logic outside chat.mjs's dispatch context. The
+// closures they used to capture are now explicit parameters: `memory` (an
+// already-loaded loadMemory() payload — callers load it once, not per
+// recursive call) and a `helpers` bag carrying every chat.mjs-local piece
+// they relied on (`relationFactsFor`, `renderFactLine`, `factPhrase`,
+// `factTermVariants`, `byTrust`, the trust-bearing `rows` array, and
+// `HAS_PROPERTY_PREDICATE`). No other chat.mjs coupling remains — dynamic
+// imports of this file's own findRuleByName/RULE_KIND_* and of
+// planning.mjs's findActionPath/findReachableSet are now direct references/
+// static imports, since both now live alongside or are reachable from here
+// without a cycle (planning.mjs imports nothing).
+//
+// Behavior is unchanged from the original closures: same dispatch order
+// (direct/alias fact hit → compose2 rule chase → filter rule chase → honest
+// miss), same OWA discipline (null / [] on a miss, never a guessed "no").
+
+/**
+ * RELATION CHASE (chat.mjs's (a0) block) — given a relation/rule NAME and a
+ * fixed (subject, object) pair, resolve whether it holds: (i) a direct taught
+ * fact, (ii) the same pair reached via an alias-chased predicate (rdfs:subClassOf
+ * over relation-name strings, folded into `relationFactsFor`'s own candidate
+ * list), (iii) a hop-counted compose2 Rule chase (exactly 2 hops: base1 then
+ * base2), or (iv) a filter Rule chase (recursively resolve the base, then
+ * require the subject also carry the taught property). Returns
+ * `{ citation: string[] }` on a genuine hit, or null on an honest miss.
+ */
+export async function resolveRelationChase(memory, name, subjectTerm, objectTerm, helpers) {
+  const { relationFactsFor, renderFactLine, factPhrase, factTermVariants, byTrust, rows, HAS_PROPERTY_PREDICATE } = helpers;
+  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.
+  const rule = findRuleByName(memory, target);
+  const ruleKind = rule?.attributes?.find((a) => a.prop === RULE_KIND_PROP)?.value;
+  // (iii) COMPOSE2 RULE CHASE — 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.
+  if (rule && ruleKind === RULE_KIND_COMPOSE2) {
+    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 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 — recursively resolve the base (a plain relation OR
+  // another rule — this SAME function calls itself), then filter by whether
+  // the SUBJECT carries the property literal (mgx:hasProperty, a plain Fact
+  // lookup over the already-loaded `rows`).
+  if (rule && ruleKind === RULE_KIND_FILTER) {
+    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(memory, base, subjectTerm, objectTerm, helpers);
+    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
+}
+
+/**
+ * RELATION "WHO" REVERSE CHASE (chat.mjs's (a0.2) block) — the mirror image of
+ * 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
+ * resolveRelationChase's own filter chase is: a filter rule's base is always
+ * either a plain relation (terminal) or another rule (one level deeper), never
+ * itself.
+ */
+export async function resolveRelationChaseReverse(memory, name, objectTerm, helpers) {
+  const { relationFactsFor, renderFactLine, factPhrase, factTermVariants, byTrust, rows, HAS_PROPERTY_PREDICATE } = helpers;
+  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 = relationFactsFor(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 = findRuleByName(memory, target);
+  const ruleKind = rule?.attributes?.find((a) => a.prop === RULE_KIND_PROP)?.value;
+  // (iii) COMPOSE2 REVERSE CHASE — the same hop-counted search the 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, via
+  // findReachableSet.
+  if (rule && ruleKind === RULE_KIND_COMPOSE2) {
+    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 applyActionsRev = (state) => {
+      if (state.hopsTaken >= 2) return [];
+      const relName = state.hopsTaken === 0 ? base2 : base1;
+      return relationFactsFor(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 = findReachableSet(
+      { 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, matching the forward chase's
+      // own citation order rather than exposing the reverse-walk's internal
+      // accumulation order to the caller.
+      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 === RULE_KIND_FILTER) {
+    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(memory, base, objectTerm, helpers);
+    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
+}
+
 // ---- 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/memory/shacl.mjs

@@ -0,0 +1,114 @@
+// memory/shacl.mjs — the declarative SHACL-STYLE ingest gate for tmct's own
+// memory graph (PLAN_AGENTS.md §2.1 "Declarative SHACL ingest gate (c)").
+//
+// ontology/memory-shapes.ttl is the canonical, standards-based (SHACL/
+// Turtle) declarative SPEC for these three shapes — written first, kept as
+// the human-readable/auditable contract, modelled on marginalia's own
+// app/ontology/shapes.ttl. This file is a small, HAND-ROLLED validator that
+// implements exactly what that spec describes, in plain JS, against
+// memory/core.mjs's own {id, label, class, attributes} individual shape.
+//
+// Deliberately NOT wired to a real SHACL/RDF-JS engine. `shacl-engine` +
+// `rdf-ext` were tried first (the plan's named tooling, matching
+// marginalia's own choice) and rejected on measurement: shacl-engine
+// transitively pulls in `@comunica/query-sparql-rdfjs-lite` — a full
+// federated SPARQL query engine — across 560+ packages (~7700 added
+// package-lock.json lines), wildly disproportionate to tmct's "pure-JS,
+// minimal-deps" floor (5 runtime deps before this) and to what three closed,
+// bounded shapes actually need. `src/conformance.mjs` already proves this
+// project is comfortable with imperative shape assertions instead of a
+// general engine (a Repository-Interface contract-test suite, not a memory
+// gate — a DIFFERENT thing from this file, see its own header); this module
+// is the same discipline applied to memory-write validation. Keep
+// ontology/memory-shapes.ttl and this file in sync BY HAND when either shape
+// changes — the .ttl is documentation here, not machine-read.
+//
+// Every shape below is PERMISSIVE beyond memory/core.mjs's own existing
+// structural floor (appendFact/appendRule already throw before ever reaching
+// mutateMemory if subject/predicate/object or name/kind/slots are missing —
+// this gate mirrors, not tightens, that floor) and treats every OPTIONAL
+// attribute (provenance chief among them — appendFact's own signature
+// defaults `provenance` to `""`, and real call sites/tests legitimately omit
+// it, e.g. re-writing createdAt without re-asserting provenance) as OPTIONAL
+// here too: a violation only fires on genuine structural malformation, never
+// on a legitimately sparse-but-valid write or upsert of existing data.
+
+const MEMORY_CLASSES = new Set(["Utterance", "Fact", "Session", "Source", "Rule"]);
+const RULE_KINDS = new Set(["compose2", "filter", "recursive"]);
+
+// Mirrors core.mjs's own (unexported) RULE_SLOT_SPEC exactly — the single
+// source of truth for the closed compose2/filter/recursive shapes; kept in
+// sync by hand (both describe the SAME three rule kinds' slot pairs).
+const RULE_SLOT_PROPS = {
+  compose2: ["mgx:ruleBase1", "mgx:ruleBase2"],
+  filter: ["mgx:ruleBase1", "mgx:ruleFilterProperty"],
+  recursive: ["mgx:ruleBaseCase", "mgx:ruleRecStep"],
+};
+
+function attrValue(ind, prop) {
+  const a = (ind?.attributes || []).find((x) => x?.prop === prop);
+  return a ? String(a.value ?? "") : undefined;
+}
+
+const nonEmpty = (v) => typeof v === "string" && v.trim().length > 0;
+
+/** IndividualShape (ontology/memory-shapes.ttl's mgx:IndividualShape): every
+ *  memory node must carry a class from the closed memory-class vocabulary. */
+function checkIndividual(ind, violations) {
+  if (!ind?.class || !MEMORY_CLASSES.has(ind.class)) {
+    violations.push(`must have a class from the closed vocabulary Utterance | Fact | Session | Source | Rule (got ${JSON.stringify(ind?.class)})`);
+  }
+}
+
+/** FactShape (mgx:FactShape): the reified subject/predicate/object, each
+ *  present and non-empty; mgx:factProvenance, WHEN PRESENT, must be
+ *  non-empty (optional at this gate — see file header on why: appendFact's
+ *  own API allows an empty/omitted provenance). */
+function checkFact(ind, violations) {
+  for (const prop of ["rdf:subject", "rdf:predicate", "rdf:object"]) {
+    if (!nonEmpty(attrValue(ind, prop))) violations.push(`a Fact needs a non-empty ${prop}`);
+  }
+  const prov = attrValue(ind, "mgx:factProvenance");
+  if (prov !== undefined && !nonEmpty(prov)) violations.push("mgx:factProvenance, when present, must be non-empty");
+}
+
+/** RuleShape (mgx:RuleShape): a non-empty name; a kind from the closed
+ *  compose2 | filter | recursive vocabulary; and the matching pair of slots
+ *  for that declared kind, each present and non-empty (RULE_SLOT_PROPS
+ *  above). */
+function checkRule(ind, violations) {
+  if (!nonEmpty(attrValue(ind, "mgx:ruleName"))) violations.push("a Rule needs a non-empty mgx:ruleName");
+  const kind = attrValue(ind, "mgx:ruleKind");
+  if (!kind || !RULE_KINDS.has(kind)) {
+    violations.push(`a Rule's mgx:ruleKind must be one of compose2 | filter | recursive (got ${JSON.stringify(kind)})`);
+    return; // no declared kind to check slots against
+  }
+  for (const prop of RULE_SLOT_PROPS[kind]) {
+    if (!nonEmpty(attrValue(ind, prop))) violations.push(`a ${kind} Rule needs a non-empty ${prop}`);
+  }
+}
+
+/** Validate one memory individual ({id, label, class, attributes}) against
+ *  the shapes ontology/memory-shapes.ttl documents. Pure, synchronous, no
+ *  I/O. Returns { ok, violations: string[] }. */
+export function validateIndividual(ind) {
+  const violations = [];
+  checkIndividual(ind, violations);
+  if (ind?.class === "Fact") checkFact(ind, violations);
+  if (ind?.class === "Rule") checkRule(ind, violations);
+  return { ok: violations.length === 0, violations };
+}
+
+/** The ingest gate: throw a clear, aggregated error if `ind` violates the
+ *  shape contract, so a malformed Fact/Rule never reaches mutateMemory's
+ *  write. Synchronous (no engine/file I/O) — safe to `await` regardless (a
+ *  synchronous throw inside an async caller's body still rejects that
+ *  caller's promise correctly; a non-throwing sync return awaits to itself). */
+export function assertIndividualValid(ind) {
+  const r = validateIndividual(ind);
+  if (!r.ok) {
+    const e = new Error(`SHACL validation failed for ${ind?.class} "${ind?.id}": ${r.violations.join(" | ")}`);
+    e.violations = r.violations;
+    throw e;
+  }
+}

package/src/prose.mjs

@@ -26,7 +26,11 @@
 // individual's attributes. Both are derived from the identical token set, so they can never
 // disagree; (b) is just (a) inverted once, cheaply, at build time.
 
-const STOPWORDS = new Set(
+// Exported (as of PLAN_COMPLETIONS.md Stage 0) so src/completions/group.mjs can filter
+// splitIdentifierWords' output (which, unlike tokenizeProse, does NOT apply this list — it's
+// built for code identifiers, where stopword-shaped fragments are rare) down to real content
+// words before using it as a text-clustering similarity signal.
+export const STOPWORDS = new Set(
   ("a an and or but the of to in on at for with from by as is are was were be been being " +
     "it its this that these those i you he she they we me my your our do does did not no " +
     "yes if then else than so such can will would should could may might about into over " +