@polycode-projects/the-mechanical-code-talker 1.12.0 → 2.0.2

package/src/{corpus → adapters/corpus}/conceptnet-map.toml

@@ -3,7 +3,7 @@
 #
 # One row per ConceptNet relation (the canonical closed set of 34 —
 # docs/references/schemas/conceptnet-relations.md is the reference list this
-# table is drift-checked against; test/corpus-conceptnet.test.mjs fails if the
+# table is drift-checked against; test/adapters/corpus-conceptnet.test.mjs fails if the
 # committed slice contains a relation with no row here).
 #
 # Fields:
@@ -13,11 +13,11 @@
 #   ace       which ACE-OWL pattern it maps to (docs/references/schemas/
 #             ace-owl-fragment.md): subClassOf | type | ObjectProperty |
 #             someValuesFrom | disjointWith | property | none
-#   predicate the predicate URI src/corpus/conceptnet.mjs emits into memory
+#   predicate the predicate URI src/adapters/corpus/conceptnet.mjs emits into memory
 #             facts (absent when ace = "none" — no fact is emitted)
 #   note      why, and what a "none" row is still good for
 #
-# Loader contract (src/corpus/conceptnet.mjs): a relation in the slice that is
+# Loader contract (src/adapters/corpus/conceptnet.mjs): a relation in the slice that is
 # MISSING here is an error (drift guard); a row with ace = "none" is a
 # deliberate non-emission, silently skipped by toFacts().
 
@@ -189,7 +189,7 @@ rel = "/r/RelatedTo"
 surface = "{start} is related to {end}"
 ace = "ObjectProperty"
 predicate = "mgx:relatedTo"
-note = "weakest, undirected association — re-examined 2026-07-12 (TOO_HARD_AUDIT.md): the surface template above was already fully authored, so the prior 'too vague for an axiom' exclusion was a design call dressed as a technical one, not a real blocker. Emitted at LOWER trust (src/corpus/conceptnet.mjs routes RelatedTo facts through the corpus-weak: provenance prefix -> SOURCE_PRIOR.corpusWeak, memory/trust.mjs) rather than either full-strength or excluded."
+note = "weakest, undirected association — re-examined 2026-07-12 (TOO_HARD_AUDIT.md): the surface template above was already fully authored, so the prior 'too vague for an axiom' exclusion was a design call dressed as a technical one, not a real blocker. Emitted at LOWER trust (src/adapters/corpus/conceptnet.mjs routes RelatedTo facts through the corpus-weak: provenance prefix -> SOURCE_PRIOR.corpusWeak, src/domain/memory/trust.mjs) rather than either full-strength or excluded."
 
 [[relation]]
 rel = "/r/Synonym"

package/src/{corpus → adapters/corpus}/conceptnet.mjs

@@ -1,7 +1,7 @@
 // corpus/conceptnet.mjs — the ConceptNet slice loader + memory seeder.
 //
 //   loadSlice(path?)        stream corpus/conceptnet/slice.jsonl → assertions
-//   loadMap(path?)          src/corpus/conceptnet-map.toml → Map(rel → row)
+//   loadMap(path?)          src/adapters/corpus/conceptnet-map.toml → Map(rel → row)
 //   toFacts(assertions,map) assertions → appendFact-shaped triples
 //   seedMemory(dir, opts)   write them into <dir>/.tmct/memory via appendFacts
 //
@@ -18,9 +18,9 @@ import { dirname, join } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { appendFacts, loadMemory, normFactTerm } from "../memory/core.mjs";
 
-const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 export const SLICE_FILE = join(PKG_ROOT, "corpus", "conceptnet", "slice.jsonl");
-export const MAP_FILE = join(PKG_ROOT, "src", "corpus", "conceptnet-map.toml");
+export const MAP_FILE = join(PKG_ROOT, "src", "adapters", "corpus", "conceptnet-map.toml");
 
 // The tier-1 curated Software-Engineering ontology (SEON): concepts.jsonl shares
 // ConceptNet's slice shape and loads through the same loadSlice/loadMap/toFacts path.

package/src/adapters/corpus/construction-banks.mjs

@@ -0,0 +1,43 @@
+// corpus/construction-banks.mjs — the filesystem side of the construction-
+// grammar template banks: read data/templates/constructions/*.toml and hand
+// the raw parsed tables to the domain strategy
+// (interpret/strategies/constructions.mjs), which receives them via
+// setConstructionBanks — the strategy itself never touches the filesystem.
+
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+import { parse as parseToml } from "smol-toml";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The construction-bank directory (data, not code) — every *.toml file inside
+ *  is loaded, in filename order, so a future bank is a new committed file, not
+ *  an edit to this loader. */
+export const CONSTRUCTIONS_DIR = join(HERE, "..", "..", "..", "data", "templates", "constructions");
+
+/** Read every *.toml file in `dir` (sorted, deterministic) and return the raw
+ *  parsed tables concatenated: {relations:[...], constructions:[...]}. A
+ *  missing directory or an unparseable file is DEFENSIVE (per-file: a broken
+ *  file is skipped, not fatal to the others) — callers get whatever validly
+ *  parsed, never a thrown error from a data-authoring mistake. */
+export function readConstructionFiles(dir = CONSTRUCTIONS_DIR) {
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".toml")).sort();
+  } catch {
+    return { relations: [], constructions: [] };
+  }
+  const relations = [];
+  const constructions = [];
+  for (const file of files) {
+    let parsed;
+    try {
+      parsed = parseToml(readFileSync(join(dir, file), "utf8"));
+    } catch {
+      continue; // one malformed file never takes the others down
+    }
+    if (Array.isArray(parsed.relation)) relations.push(...parsed.relation);
+    if (Array.isArray(parsed.construction)) constructions.push(...parsed.construction);
+  }
+  return { relations, constructions };
+}

package/src/{corpus → adapters/corpus}/templates.mjs

@@ -15,7 +15,7 @@ import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { join, dirname } from "node:path";
 
-const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 export const TEMPLATES_FILE = join(PKG_ROOT, "data", "templates", "responses.jsonl");
 export const PHRASEBOOK_FILE = join(PKG_ROOT, "data", "phrasebook", "software-phrases.txt");
 

package/src/{embed.mjs → adapters/embed.mjs}

@@ -24,7 +24,7 @@ const CONFIG_FILE = "config.json";
 export function defaultEmbeddingsDir() {
   if (process.env.TMCT_EMBED_DIR) return process.env.TMCT_EMBED_DIR;
   const here = dirname(fileURLToPath(import.meta.url)); // packages/tmct/src
-  return join(here, "..", "..", "..", "vendor", "embeddings", "potion-base-8M");
+  return join(here, "..", "..", "..", "..", "vendor", "embeddings", "potion-base-8M");
 }
 
 // ---- safetensors (hand-rolled: u64le header length + JSON header + raw tensors) -------
@@ -167,13 +167,3 @@ export function loadEmbedder({ dir = defaultEmbeddingsDir() } = {}) {
   LOADED.set(dir, embedder);
   return embedder;
 }
-
-/** Cosine similarity. Over L2-normalised vectors this is just the dot product, but the
- *  full form is kept so unnormalised test fixtures behave. 0 when either vector is zero. */
-export function cosine(a, b) {
-  let dot = 0, na = 0, nb = 0;
-  const n = Math.min(a.length, b.length);
-  for (let i = 0; i < n; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
-  if (na === 0 || nb === 0) return 0;
-  return dot / (Math.sqrt(na) * Math.sqrt(nb));
-}

package/src/{graph-build.mjs → adapters/graph-build.mjs}

@@ -1,6 +1,6 @@
-// graph-build.mjs  the PURE assembly of the typed `entities` payload from
+// graph-build.mjs — the PURE assembly of the typed `entities` payload from
 // already-parsed module + commit records. No subprocesses, no filesystem, no git:
-// data in, graph out  which is why tests build in-memory graphs through it, and
+// data in, graph out — which is why tests build in-memory graphs through it, and
 // why it is the write-path primitive conversation memory grows on (sessions.mjs
 // folds session records into the same shape).
 //
@@ -17,7 +17,7 @@
 //   seon:containsCodeEntity Class  -> Method/Attribute (class membership)
 //   mgx:subclassOf          Class  -> Class    (inheritance)
 
-import { attachProseTokens, buildProseIndex } from "./prose.mjs";
+import { attachProseTokens, buildProseIndex } from "./prose-tokens.mjs";
 
 const isTestPath = (p) =>
   p.startsWith("tests/") || /(^|\/)tests?\//.test(p) || /(^|\/)test_[^/]*\.py$/.test(p) || /\.tests(\.|$)/.test(p);
@@ -287,14 +287,14 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   const COCHANGE_MIN = 2;        // co-occur in ≥ N commits
   const COCHANGE_MAX_COMMIT = 50; // skip sweeping refactors (O(n²) noise)
   const COCHANGE_PER_NODE = 12;  // cap neighbours per module
-  const pairCount = new Map();   // "ab" (a<b lexical) -> count
+  const pairCount = new Map();   // "a\0b" (a<b lexical) -> count
   for (const c of commits) {
     const mods = [...new Set((c.files || []).filter((f) => modById.has(f)))];
     if (mods.length < 2 || mods.length > COCHANGE_MAX_COMMIT) continue;
     for (let i = 0; i < mods.length; i += 1) {
       for (let j = i + 1; j < mods.length; j += 1) {
         const [a, b] = mods[i] < mods[j] ? [mods[i], mods[j]] : [mods[j], mods[i]];
-        const key = `${a}${b}`;
+        const key = `${a}\0${b}`;
         pairCount.set(key, (pairCount.get(key) || 0) + 1);
       }
     }
@@ -302,7 +302,7 @@ export function buildEntities(modules, commits, { generatedAt = "", symbolHistor
   const cochangeEdges = [];
   const cochangePerNode = new Map();
   for (const [key, n] of [...pairCount.entries()].filter(([, c]) => c >= COCHANGE_MIN).sort((x, y) => y[1] - x[1])) {
-    const [a, b] = key.split("");
+    const [a, b] = key.split("\0");
     if ((cochangePerNode.get(a) || 0) >= COCHANGE_PER_NODE || (cochangePerNode.get(b) || 0) >= COCHANGE_PER_NODE) continue;
     cochangePerNode.set(a, (cochangePerNode.get(a) || 0) + 1);
     cochangePerNode.set(b, (cochangePerNode.get(b) || 0) + 1);

package/src/{memory → adapters/memory}/blocks.mjs

@@ -6,8 +6,8 @@
 
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { splitIdentifierWords, tokenizeProse } from "../prose.mjs";
-import { SOURCE_PRIOR } from "./trust.mjs";
+import { splitIdentifierWords, tokenizeProse } from "../prose-tokens.mjs";
+import { SOURCE_PRIOR } from "../../domain/memory/trust.mjs";
 
 // A block inherits its Source's trust (operator 1.0, corpus 0.7); retrieval
 // weights relevance × trust via a bounded factor (0.5 + trust, ~[0.5, 1.5]).

package/src/{memory → adapters/memory}/core.mjs

@@ -7,11 +7,24 @@
 
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 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 { proseTokensFor, buildProseIndex } from "../prose-tokens.mjs";
+import { fnv1aHex, normText, normFactTerm, normFactPredicate, factIdFor, factIdForTriple } from "../../domain/hash.mjs";
+
+// Fact identity (normalization + id derivation) lives in hash.mjs — the one
+// content-address contract — and is re-exported here so store consumers keep
+// a single import site for read/write plus identity.
+export { normFactTerm, normFactPredicate, factIdForTriple } from "../../domain/hash.mjs";
+import {
+  computeTrust, sessionReliabilityFrom, TRUST_SCORE_PROP, TRUST_INPUTS_PROP,
+  CREATED_AT_PROP, UPDATED_AT_PROP, provenanceTagToSource,
+} from "../../domain/memory/trust.mjs";
+
+// The createdAt/updatedAt vocabulary and the provenance-tag Source parser live
+// with the trust layer (they are its inputs); re-exported here so store
+// consumers keep one import site.
+export { CREATED_AT_PROP, UPDATED_AT_PROP, provenanceTagToSource } from "../../domain/memory/trust.mjs";
+import { NEG_PREDICATE_PREFIX, negatedPredicate } from "../../domain/memory/capability.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");
@@ -33,11 +46,6 @@ export const IN_REPLY_TO_PROP = "mgx:inReplyTo";
 export const DERIVED_FROM_PROP = "mgx:derivedFrom";        // umbrella: Fact → Source|Fact
 export const STATED_BY_PROP = "mgx:statedBy";              // a Source directly asserts a Fact
 export const CANONICALISED_FROM_PROP = "mgx:canonicalisedFrom"; // a canonical Fact ← its raw form
-export const CREATED_AT_PROP = "mgx:createdAt";           // first-write-wins ISO-8601 on every individual
-// For call sites that mutate an individual's own attributes without touching
-// an edge (upsertSession, recomputeFactTrust, recomputeSourceReliability),
-// where codegraph.mjs's derived-updatedAt rule alone can't see the change.
-export const UPDATED_AT_PROP = "mgx:updatedAt";
 export const SOURCE_RELIABILITY_PROP = "mgx:sourceReliability"; // actor-level (session-scoped) trust nudge on a Source, [0.5,1.5]
 
 // Bare (session-less) singleton Source ids — fallback for a provenance tag
@@ -48,7 +56,6 @@ export const TEACH_SOURCE_ID = "src:teach-chat";
 
 const ROLES = new Set(["visitor", "tmct"]);
 const LABEL_CAP = 48;    // utterance/fact labels stay skimmable in renders
-const TEXT_CAP = 2000;   // an utterance's stored text (a whole answer fits; a pasted book doesn't)
 
 /** The memory graph's vocabulary — documented in-payload exactly like
  *  graph-build.mjs documents the code graph's. */
@@ -85,6 +92,7 @@ const MEMORY_VOCABULARY = [
   { prop: TRUST_INPUTS_PROP, note: "JSON of the inputs the trust score was computed from (source-type multiset, corroboration count, createdAt, recency) — makes the score auditable" },
   { prop: "mgx:hasProseTokens", note: "prose tokens (prose.mjs tokenizer) backing the payload's proseIndex" },
   { prop: "mgx:sessionStarted", note: "session anchor: when the session started, ISO-8601" },
+  { prop: "rdf:predicate", prefix: NEG_PREDICATE_PREFIX, note: "a reified fact's predicate carries its POLARITY: mgxneg:capableOf is the negative twin of mgx:capableOf ('a penguin cannot fly'). Polarity cannot be a separate property — the fact id hashes (subject, predicate, object), so both polarities would share one id and union their statedBy edges (memory/capability.mjs)" },
 ];
 
 /** A fresh, empty memory payload — the buildEntities shape, plus the OWL/RDF
@@ -99,6 +107,7 @@ export function emptyMemory() {
       rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
       rdfs: "http://www.w3.org/2000/01/rdf-schema#",
       mgx: "urn:tmct:mgx#",
+      mgxneg: "urn:tmct:mgxneg#",
     },
     vocabulary: MEMORY_VOCABULARY.map((v) => ({ ...v })),
     classes: [],
@@ -580,7 +589,6 @@ async function mutateMemory(dir, fn) {
   return out;
 }
 
-const normText = (t) => String(t ?? "").replace(/\s+/g, " ").trim().slice(0, TEXT_CAP);
 const labelOf = (text) => (text.length > LABEL_CAP ? text.slice(0, LABEL_CAP - 1) + "…" : text);
 const nowIso = () => new Date().toISOString();
 
@@ -644,48 +652,6 @@ function upsertSource(payload, desc, createdAtCandidate) {
   return info.id;
 }
 
-/** Parse the "chat" shape both provenanceTag and teachProvenanceTag emit —
- *  `<source>[:<sessionId>][@<ts>]` — into { createdAt, sessionId? }. */
-function parseChatTagRest(rest) {
-  const at = rest.indexOf("@");
-  const beforeAt = at >= 0 ? rest.slice(0, at) : rest;
-  const createdAt = at >= 0 ? rest.slice(at + 1) : "";
-  const colon = beforeAt.indexOf(":");
-  const sessionId = colon >= 0 ? beforeAt.slice(colon + 1) : "";
-  return { createdAt, ...(sessionId ? { sessionId } : {}) };
-}
-
-/**
- * Parse one legacy provenance TAG into a Source descriptor over the closed
- * kind set:
- *   corpus:conceptnet /r/IsA   -> { kind:"corpus",   name:"conceptnet" }
- *   corpus-weak:conceptnet /r/RelatedTo -> { kind:"corpusWeak", name:"conceptnet" }
- *   ace:chat:<session>@<ts>    -> { kind:"operator",  createdAt:<ts>, sessionId:<session> }
- *   teach:chat:<session>@<ts>  -> { kind:"teach",     createdAt:<ts>, sessionId:<session> }
- *   web:<url> | url:<url>      -> { kind:"web",       url:<url> }
- *   extracted:<file-basename>  -> { kind:"extracted", name:<file-basename> }
- *   entailed:<rule>            -> { kind:"entailed",  rule:<rule> }
- * chat:/session: refs map to the operator; an unknown tag -> null (no Source).
- */
-export function provenanceTagToSource(tag) {
-  const t = String(tag || "").trim();
-  if (!t) return null;
-  const head = t.split(/\s+/)[0]; // drop trailing " /r/IsA" etc.
-  if (head.startsWith("corpus-weak:")) return { kind: "corpusWeak", name: head.slice("corpus-weak:".length) || "unknown" };
-  if (head.startsWith("corpus:")) return { kind: "corpus", name: head.slice("corpus:".length) || "unknown" };
-  if (head.startsWith("ace:")) return { kind: "operator", ...parseChatTagRest(head.slice("ace:".length)) };
-  if (head.startsWith("teach:")) {
-    // the chat teach lane's natural frames — chat.mjs's teachProvenanceTag
-    return { kind: "teach", ...parseChatTagRest(head.slice("teach:".length)) };
-  }
-  if (head.startsWith("web:")) return { kind: "web", url: head.slice("web:".length) };
-  if (head.startsWith("url:")) return { kind: "web", url: head.slice("url:".length) };
-  if (head.startsWith("extracted:")) return { kind: "extracted", name: head.slice("extracted:".length) || "unknown" };
-  if (head.startsWith("entailed:")) return { kind: "entailed", rule: head.slice("entailed:".length) };
-  if (head.startsWith("chat:") || head.startsWith("session:") || head.startsWith("operator")) return { kind: "operator" };
-  return null;
-}
-
 /** Map a payload's Source individuals into the { id: Source } shape computeTrust
  *  resolves against. */
 function sourcesByIdMap(payload) {
@@ -846,7 +812,7 @@ function upsertIndividual(payload, ind) {
  *  on the edge, first-write-wins over the same (subject,object) pair — mirrors
  *  `firstWriteCreatedAt`'s discipline: a re-upserted edge keeps its original creation time
  *  rather than resetting to "now" on every write. This is the only place in the codebase edges
- *  get a timestamp at all — `codegraph.mjs`'s `derivedUpdatedAt` reads it back. */
+ *  get a timestamp at all. */
 function upsertEdge(payload, { predicate, prop }, edge) {
   let group = payload.objectProperties.find((g) => g?.prop === prop);
   if (!group) {
@@ -986,33 +952,6 @@ export async function appendUtterances(dir, utterances) {
   return { ids };
 }
 
-/** Normalize a fact TERM (subject/object) so every writer converges on one
- *  spelling: ConceptNet's /c/en/foo_bar, tmct:Foo_bar, and bare "Foo bar" all
- *  become "foo bar". Also strips a leading "the"/"a"/"an" (idempotent — safe
- *  for storage too). The predicate is never normalized this way — its casing
- *  is meaningful controlled vocabulary. */
-export function normFactTerm(t) {
-  let s = normText(t);
-  s = s.replace(/^\/c\/[a-z]{2,3}\//i, "");
-  s = s.replace(/^[a-z][\w.-]*:/i, "");
-  s = s.replace(/_/g, " ").replace(/\s+/g, " ").trim();
-  s = s.replace(/^(?:the|an?)\s+/i, "");
-  return s.toLowerCase();
-}
-
-// A Fact is content-addressed by its NUL-delimited (s, p, o) — NUL never
-// occurs in a normalized term/predicate, so it's collision-proof unlike a
-// space. appendFact hashes the same `${s}\0${p}\0${o}` inline; keep both in sync.
-const factIdFor = (s, p, o) => `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
-
-/** Content-address a fact's id from (subject, predicate, object) without
- *  writing it — same contract as factIdFor. Lets a caller (e.g.
- *  syllogise.mjs's retraction machinery) name a not-yet-written fact's id
- *  deterministically, without an extra read. Pure, no I/O. */
-export function factIdForTriple(subject, predicate, object) {
-  return factIdFor(normFactTerm(subject), normText(predicate), normFactTerm(object));
-}
-
 /** Append one grammar-derived OWL triple, RDF-reified as a `Fact` individual.
  *  Same (s,p,o) -> same id -> upsert, never a duplicate. `premiseTrusts`/
  *  `ruleConfidence` optionally engage trust.mjs's entailed hook. Validated
@@ -1020,10 +959,10 @@ export function factIdForTriple(subject, predicate, object) {
  *  Returns { id }. */
 export async function appendFact(dir, { subject, predicate, object, provenance = "", createdAt = "", quantifier = "", premiseTrusts, ruleConfidence } = {}) {
   const s = normFactTerm(subject);
-  const p = normText(predicate);
+  const p = normFactPredicate(predicate);
   const o = normFactTerm(object);
   if (!s || !p || !o) throw new Error("a fact needs subject, predicate and object");
-  const id = `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
+  const id = factIdFor(s, p, o);
   const text = `${s} ${p} ${o}`;
   const tokens = proseTokensFor({ doc: text });
   const q = normText(quantifier);
@@ -1074,7 +1013,7 @@ export async function appendFacts(dir, facts) {
   let skipped = 0;
   for (const f of facts || []) {
     const s = normFactTerm(f?.subject);
-    const p = normText(f?.predicate);
+    const p = normFactPredicate(f?.predicate);
     const o = normFactTerm(f?.object);
     if (!s || !p || !o) { skipped += 1; continue; } // batch skips, never throws
     const text = `${s} ${p} ${o}`;
@@ -1206,7 +1145,7 @@ const RULE_SLOT_SPEC = {
     ["objectRole", "mgx:ruleActionEffectObject"],
   ],
   // "the <left> may not be with the <right> without the <guard>" — each slot
-  // names a class whose sole member src/domain.mjs resolves at compile time.
+  // names a class whose sole member src/domain/domain.mjs resolves at compile time.
   [RULE_KIND_ACTION_CONSTRAINT]: [
     ["left", "mgx:ruleActionConstraintLeft"], ["right", "mgx:ruleActionConstraintRight"],
     ["guard", "mgx:ruleActionConstraintGuard"],
@@ -1217,7 +1156,7 @@ const RULE_SLOT_SPEC = {
 // mirroring factIdFor's NUL-delimited discipline: identical rules upsert,
 // different ones coexist. For 2-slot kinds the joined string is byte-identical
 // to the historical (kind, name, slot1, slot2) template, so pre-existing rule
-// ids never change (pinned by test/memory-rules-action.test.mjs).
+// ids never change (pinned by test/adapters/memory-rules-action.test.mjs).
 const ruleIdFor = (kind, name, slotValues) => `rule:${fnv1aHex([kind, name, ...slotValues].join("\0"))}`;
 
 /** Append one taught RULE — a sibling of appendFact storing a `Rule`
@@ -1290,7 +1229,7 @@ export function findRulesByName(memory, name) {
 }
 
 /** Every taught Rule as a plain row {id, name, kind, slots, provenance} —
- *  the sibling of readFactRows, so consumers (src/domain.mjs) never touch
+ *  the sibling of readFactRows, so consumers (src/domain/domain.mjs) never touch
  *  raw individuals. Rules whose kind has no RULE_SLOT_SPEC entry are
  *  skipped (unreadable without a slot contract). Sorted by name, kind, id. */
 export function readRuleRows(memory) {
@@ -1322,9 +1261,10 @@ export function readRuleRows(memory) {
 // importable functions taking an already-loaded `memory` (a loadMemory()
 // payload — callers load it once, not per recursive call) and a `helpers`
 // bag (`relationFactsFor`, `renderFactLine`, `factPhrase`, `factTermVariants`,
-// `byTrust`, the trust-bearing `rows` array, and `HAS_PROPERTY_PREDICATE`),
-// so callers outside chat.mjs's own dispatch context can reuse the same
-// resolution logic.
+// `byTrust`, the trust-bearing `rows` array, `HAS_PROPERTY_PREDICATE`, and
+// the search kernels `findActionPath`/`findReachableSet` from planning.mjs —
+// injected so this store module never imports the domain layer), so callers
+// outside chat.mjs's own dispatch context can reuse the same resolution logic.
 //
 // Dispatch order: direct/alias fact hit → compose2 rule chase → filter rule
 // chase → honest miss (OWA discipline: null / [] on a miss, never a guessed
@@ -1337,7 +1277,7 @@ export function readRuleRows(memory) {
  * Rule chase. Returns `{ citation: string[] }` on a hit, 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 { relationFactsFor, renderFactLine, factPhrase, factTermVariants, byTrust, rows, HAS_PROPERTY_PREDICATE, findActionPath } = 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.
@@ -1413,7 +1353,7 @@ export async function resolveRelationChase(memory, name, subjectTerm, objectTerm
  * `{ subject, citation }` pair that satisfies it, instead of one yes/no.
  */
 export async function resolveRelationChaseReverse(memory, name, objectTerm, helpers) {
-  const { relationFactsFor, renderFactLine, factPhrase, factTermVariants, byTrust, rows, HAS_PROPERTY_PREDICATE } = helpers;
+  const { relationFactsFor, renderFactLine, factPhrase, factTermVariants, byTrust, rows, HAS_PROPERTY_PREDICATE, findReachableSet } = helpers;
   const target = String(name || "").trim().toLowerCase();
   const ov = factTermVariants(normFactTerm, objectTerm);
   // (i)+(ii): every direct/alias-chased fact under this name whose object
@@ -1582,8 +1522,12 @@ export const CAPABLE_OF_PREDICATE = "mgx:capableOf";
 /** Predicates whose real-world semantics allow many objects at once ("a dog
  *  has legs" AND "a dog has a tail"; "a bird can fly" AND "a bird can sing"),
  *  so a second object is a second fact, never a disagreement. A closed list:
- *  every predicate outside it keeps the full contradiction contract. */
-export const MULTI_VALUED_PREDICATES = new Set([HAS_A_PREDICATE, CAPABLE_OF_PREDICATE]);
+ *  every predicate outside it keeps the full contradiction contract. Each
+ *  entry's negative twin joins it — "a penguin cannot fly" and "a penguin
+ *  cannot sing" are two claims, not a self-contradiction. */
+export const MULTI_VALUED_PREDICATES = new Set(
+  [HAS_A_PREDICATE, CAPABLE_OF_PREDICATE].flatMap((p) => [p, negatedPredicate(p)]),
+);
 
 /** Facts that CONTRADICT: same (subject, predicate), different object, each
  *  above the trust floor. Returns groups (trust-desc) so callers surface both,

package/src/adapters/prose-tokens.mjs

@@ -0,0 +1,98 @@
+// prose-tokens.mjs — the adapters layer's own tokenizer, shared by every
+// adapter that writes prose tokens (the memory store, graph-build). Adapters
+// may not import the domain layer, while prose.mjs (the graph/ask side's
+// canonical tokenizer) is domain and may not import adapters — so this layer
+// carries its own copy of the primitives it stores tokens with. The two copies
+// must stay byte-identical: the parity suite in
+// test/adapters/prose-tokens.test.mjs pins every function here to its
+// prose.mjs twin, so a change to either side fails loudly until both move
+// together.
+
+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 " +
+    "under out up down off again more most some any all what which who whom whose when " +
+    "where why how").split(/\s+/),
+);
+
+const MAX_TOKEN_LEN = 40;    // drops hash-like/garbage tokens
+const MAX_TOKENS_PER_DOC = 120; // bounds cost on a pathologically long docstring/name
+
+/** Split an identifier or a path-like name into lowercase word tokens.
+ *  Handles camelCase, PascalCase, snake_case, kebab-case, dotted names, path
+ *  separators, and acronym runs ("HTTPSConnection" -> https/connection,
+ *  "parseXML" -> parse/xml). Filters single-character tokens (loop-variable noise). */
+export function splitIdentifierWords(raw) {
+  if (!raw) return [];
+  let s = String(raw).replace(/\.[A-Za-z0-9]+$/, ""); // strip a trailing file extension only
+  s = s
+    .replace(/[/\\]/g, " ")            // path separators
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")     // camelCase / word|Digit boundary
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")  // acronym run -> TitleCase (HTTPSConnection)
+    .replace(/([A-Za-z])([0-9])/g, "$1 $2")
+    .replace(/([0-9])([A-Za-z])/g, "$1 $2")
+    .replace(/[_\-.]+/g, " ");
+  return s.split(/\s+/).map((w) => w.toLowerCase()).filter((w) => w.length > 1 && w.length <= MAX_TOKEN_LEN);
+}
+
+/** Tokenize free prose (a docstring/doc-comment) — lowercase words, punctuation stripped,
+ *  common stopwords and single-/over-length tokens dropped, capped at MAX_TOKENS_PER_DOC. */
+export function tokenizeProse(text) {
+  if (!text) return [];
+  const out = [];
+  const seen = new Set();
+  for (const raw of String(text).toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length < 2 || raw.length > MAX_TOKEN_LEN || STOPWORDS.has(raw)) continue;
+    if (seen.has(raw)) continue;
+    seen.add(raw);
+    out.push(raw);
+    if (out.length >= MAX_TOKENS_PER_DOC) break;
+  }
+  return out;
+}
+
+/** The combined, deduped, sorted token set for one individual: its (decomposed) name
+ *  plus any captured doc text. Returns [] if there's nothing to index (never null). */
+export function proseTokensFor({ name, doc } = {}) {
+  const set = new Set([...splitIdentifierWords(name), ...tokenizeProse(doc)]);
+  return [...set].sort();
+}
+
+/** Attach a `prose_tokens` attribute to every individual, from its (decomposed)
+ *  name and captured doc text — except Commit, whose `label` is a truncated
+ *  SHA, not a decomposable identifier: it tokenizes `message` instead. Mutates
+ *  and returns the same array; `enabled=false` is a no-op. */
+export function attachProseTokens(individuals, { enabled = true } = {}) {
+  if (!enabled) return individuals;
+  for (const ind of individuals) {
+    const attrs = ind.attributes || [];
+    const isCommit = ind.class === "Commit";
+    const name = isCommit ? null : ind.label;
+    const doc = isCommit
+      ? attrs.find((a) => a.key === "message")?.value
+      : attrs.find((a) => a.key === "doc")?.value;
+    const tokens = proseTokensFor({ name, doc });
+    if (tokens.length) {
+      ind.attributes = [...(ind.attributes || []), { prop: "mgx:hasProseTokens", key: "prose_tokens", value: tokens.join(" ") }];
+    }
+  }
+  return individuals;
+}
+
+/** Build the inverted index (word -> sorted, deduped [individual ids]) from individuals
+ *  that already carry a `prose_tokens` attribute. Plain object, JSON-serializable —
+ *  this is what lands as the payload's `proseIndex`. */
+export function buildProseIndex(individuals) {
+  const index = Object.create(null);
+  for (const ind of individuals) {
+    const tokAttr = (ind.attributes || []).find((a) => a.key === "prose_tokens");
+    if (!tokAttr?.value) continue;
+    for (const word of tokAttr.value.split(" ")) {
+      if (!index[word]) index[word] = [];
+      index[word].push(ind.id);
+    }
+  }
+  for (const word of Object.keys(index)) index[word].sort();
+  return index;
+}

package/src/{providers → adapters/providers}/bootstrap.mjs

@@ -2,13 +2,13 @@
 // "contains" before anything is indexed.
 //
 // It implements every Repository-Interface service over the empty bootstrap
-// payload (src/source.mjs emptyEntities): every id-taking service returns
+// payload (src/adapters/source.mjs emptyEntities): every id-taking service returns
 // miss(UNRESOLVED_TERM) — there are no individuals — and every aggregate returns
 // an honest empty (stats.total = 0, untested.modules = [], …). Nothing throws.
 // This is the other end of the compatibility kit: the provider that has no data
 // must still CONFORM.
 
-import { parseEntities } from "../codegraph.mjs";
+import { parseEntities } from "../../domain/codegraph.mjs";
 import { emptyEntities } from "../source.mjs";
 import { createGraphService } from "./graph-service.mjs";
 

package/src/{providers → adapters/providers}/fixture.mjs

@@ -3,13 +3,13 @@
 //
 // It is a degenerate provider in the sense that its graph is tiny and its source
 // bodies are absent (snippet/context answer NO_SOURCE) — but every OTHER service
-// returns real graph truth. The contract suite (test/repository-interface.test.mjs)
+// returns real graph truth. The contract suite (test/adapters/repository-interface.test.mjs)
 // runs the whole compatibility kit against it.
 //
 // The payload is embedded (not read from test/) so this ships as a runnable spec
 // inside the library. Its shape is exactly a parseEntities() input.
 
-import { parseEntities } from "../codegraph.mjs";
+import { parseEntities } from "../../domain/codegraph.mjs";
 import { createGraphService } from "./graph-service.mjs";
 
 /** A compact but type-complete entities payload: modules, a class hierarchy
@@ -114,7 +114,7 @@ export function fixtureGraph() {
 /** The fixture provider: a Repository-Interface service over the small real graph.
  *  `opts` passes straight through to createGraphService — e.g. `{ sourceAccess: true,
  *  repoRoot, readFile }` to construct a source-capable fixture provider for testing
- *  (see test/repository-interface.test.mjs's third runConformance call, which is the
+ *  (see test/adapters/repository-interface.test.mjs's third runConformance call, which is the
  *  only thing that exercises the conformance kit's source-capable branch). */
 export function fixtureProvider(opts = {}) {
   return createGraphService(fixtureGraph(), opts);

package/src/{providers → adapters/providers}/graph-service.mjs

@@ -1,7 +1,7 @@
 // The reference Repository-Interface service over a parsed code graph.
 //
 // createGraphService(graph) returns a typed service object implementing EVERY
-// service in src/repository-interface.mjs over the `{ individuals, byId,
+// service in src/adapters/repository-interface.mjs over the `{ individuals, byId,
 // relations, … }` shape parseEntities() yields. Every method returns a typed
 // Result (hit/miss) — a clean miss is a value, never a throw. The two providers
 // tmct ships (fixture, bootstrap) are this same builder over a small real graph
@@ -25,9 +25,8 @@ import {
   sizeBundle,
   bundleMask,
   renderGraphOnlyBundle,
-} from "../codegraph.mjs";
+} from "../../domain/codegraph.mjs";
 import { readSpanSafe, sliceSpan } from "../source-slice.mjs";
-import { ask } from "../ask.mjs";
 import {
   hit,
   miss,
@@ -126,9 +125,14 @@ async function renderSourceBodies(plan, mask, { readFile, repoRoot }) {
  * @param {object|null} [opts.tel]  an optional telemetry sink ({ record(fields) }). When
  *   present, every service is wrapped once to time it and record counts only, never raw
  *   text/body.
+ * @param {Function} [opts.ask]  the natural-language answerer backing the `ask` service
+ *   (src/domain/ask.mjs's `ask` in the live wiring) — injected at construction like fs access,
+ *   never an ambient import. Constructing without it makes `.ask()` an honest
+ *   CAPABILITY_ABSENT miss, the same negotiation snippet/context use for missing
+ *   source access.
  * @returns the typed service object
  */
-export function createGraphService(graph, { sourceAccess = false, repoRoot = null, readFile = null, tel = null } = {}) {
+export function createGraphService(graph, { sourceAccess = false, repoRoot = null, readFile = null, tel = null, ask = null } = {}) {
   const byId = graph.byId;
   if (sourceAccess && (!repoRoot || typeof readFile !== "function")) {
     throw new TypeError(
@@ -401,6 +405,7 @@ export function createGraphService(graph, { sourceAccess = false, repoRoot = nul
     },
 
     ask(query) {
+      if (typeof ask !== "function") return miss(MISS_REASONS.CAPABILITY_ABSENT, "this provider was constructed without an ask answerer");
       const { content, tmct_ask } = ask(graph, String(query || ""));
       return hit({ content, tmct_ask });
     },

package/src/{source-slice.mjs → adapters/source-slice.mjs}

@@ -1,5 +1,5 @@
-// Shared, safe source-span slicing for the tool layer (src/server.mjs) and the
-// source-capable Repository Interface provider (src/providers/graph-service.mjs).
+// Shared, safe source-span slicing for the tool layer (src/tools/server.mjs) and the
+// source-capable Repository Interface provider (src/adapters/providers/graph-service.mjs).
 //
 // Two halves:
 //   - sliceSpan   — PURE. Given an in-memory `lines` array, extracts + line-numbers