@polycode-projects/the-mechanical-code-talker 0.3.0 → 0.5.0

package/src/memory/core.mjs

@@ -31,6 +31,8 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { proseTokensFor, buildProseIndex } from "../prose.mjs";
+import { fnv1aHex } from "../hash.mjs";
+import { computeTrust, TRUST_SCORE_PROP, TRUST_INPUTS_PROP } from "./trust.mjs";
 
 export const MEMORY_DIR_REL = join(".tmct", "memory");
 export const MEMORY_GRAPH_REL = join(MEMORY_DIR_REL, "graph.json");
@@ -38,10 +40,22 @@ export const MEMORY_GRAPH_REL = join(MEMORY_DIR_REL, "graph.json");
 export const UTTERANCE_CLASS = "Utterance";
 export const FACT_CLASS = "Fact";
 export const MEMORY_SESSION_CLASS = "Session";
+export const SOURCE_CLASS = "Source";
 
 export const SAID_IN_SESSION_PROP = "mgx:saidInSession";
 export const IN_REPLY_TO_PROP = "mgx:inReplyTo";
 
+// The provenance-link predicate family (PLAN_PROVENANCE_TRUST step (b)): one
+// umbrella object property with two workhorse subproperties, minted in the owned
+// mgx: namespace to match tmct-core.ttl's object-property style.
+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
+
+// The one deterministic operator Source id — the operator chatting to tmct.
+export const OPERATOR_SOURCE_ID = "src:operator-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)
@@ -59,7 +73,16 @@ const MEMORY_VOCABULARY = [
   { prop: "rdf:subject", note: "reified fact: the triple's subject term" },
   { prop: "rdf:predicate", note: "reified fact: the triple's predicate term" },
   { prop: "rdf:object", note: "reified fact: the triple's object term" },
-  { prop: "mgx:factProvenance", note: "where a fact came from (a session/turn ref, a corpus block id, an ACE parse)" },
+  { 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: 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)" },
+  { prop: CANONICALISED_FROM_PROP, predicate: "canonicalisedFrom", note: "subPropertyOf derivedFrom: a canonical Fact cleaned from a raw Block/Source, never replacing it" },
+  { prop: "mgx:sourceType", note: "a Source's kind: operator | provider | corpus | web | entailed (the trust-prior key)" },
+  { prop: "mgx:sourceUrl", note: "a web Source's URL" },
+  { prop: "mgx:sourceRule", note: "an entailed Source's rule id" },
+  { prop: TRUST_SCORE_PROP, note: "materialised trust cache in [0,1] — pure function of a fact's Sources + createdAt (memory/trust.mjs); invalidated when a statedBy edge is added" },
+  { 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" },
 ];
@@ -110,10 +133,14 @@ export async function loadMemory(dir) {
 }
 
 /** Fresh read → mutate → atomic write. Serialized per call; every public append
- *  goes through here so a concurrent reader never sees a torn store. */
+ *  goes through here so a concurrent reader never sees a torn store. The lazy,
+ *  idempotent legacy-provenance migration rides this same cycle (step (b)): any
+ *  Fact still carrying only the old mgx:factProvenance string gets its Sources +
+ *  statedBy edges + trust materialised on the next write of any kind. */
 async function mutateMemory(dir, fn) {
   const payload = await loadMemory(dir);
   const out = fn(payload) ?? payload;
+  migrateLegacyProvenance(out);
   out.proseIndex = buildProseIndex(out.individuals);
   await mkdir(dirname(memoryGraphFile(dir)), { recursive: true });
   await atomicWriteJson(memoryGraphFile(dir), out);
@@ -122,6 +149,152 @@ async function mutateMemory(dir, fn) {
 
 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();
+
+/** First-write-wins createdAt: keep the prior individual's timestamp if it has
+ *  one (records when a thing was FIRST learned, not when last touched), else the
+ *  candidate. */
+function firstWriteCreatedAt(prior, candidate) {
+  return prior?.attributes?.find((a) => a?.prop === CREATED_AT_PROP)?.value || candidate || nowIso();
+}
+
+/** Set (replace-or-append) one attribute on an individual by prop. */
+function setAttr(ind, prop, key, value) {
+  ind.attributes = (ind.attributes || []).filter((a) => a?.prop !== prop);
+  ind.attributes.push({ prop, key, value });
+}
+
+// ---- Sources (step (b)): first-class provenance individuals -----------------
+
+/** Deterministic Source id + type over the closed kind set. Returns null for an
+ *  unknown kind (an unmappable provenance tag → no Source, honestly). */
+function sourceIdFor(desc) {
+  switch (desc?.kind) {
+    case "operator": return { id: OPERATOR_SOURCE_ID, type: "operator" };
+    case "provider": return { id: `src:provider:${desc.name}`, type: "provider" };
+    case "corpus": return { id: `src:corpus:${desc.name}`, type: "corpus" };
+    case "web": return { id: `src:learned:web:${fnv1aHex(String(desc.url || ""))}`, type: "web", url: String(desc.url || "") };
+    case "entailed": return { id: `src:entailed:${desc.rule}`, type: "entailed", rule: String(desc.rule || "") };
+    default: return null;
+  }
+}
+
+const sourceLabel = (id) => String(id).replace(/^src:/, "");
+
+/** Upsert a Source individual (deterministic id → idempotent, edges never
+ *  dangle). createdAt is first-write-wins; a recovered @<ts> (desc.createdAt)
+ *  seeds it when present. Returns the Source id, or null for an unknown kind. */
+function upsertSource(payload, desc, createdAtCandidate) {
+  const info = sourceIdFor(desc);
+  if (!info) return null;
+  const prior = payload.individuals.find((i) => i?.id === info.id);
+  const created = firstWriteCreatedAt(prior, desc?.createdAt || createdAtCandidate);
+  upsertIndividual(payload, {
+    id: info.id, label: sourceLabel(info.id), class: SOURCE_CLASS,
+    derived_from: [], mentions: [],
+    attributes: [
+      { prop: "rdf:type", key: "type", value: "owl:NamedIndividual" },
+      { prop: "mgx:sourceType", key: "sourceType", value: info.type },
+      { prop: CREATED_AT_PROP, key: "createdAt", value: created },
+      ...(info.url ? [{ prop: "mgx:sourceUrl", key: "sourceUrl", value: info.url }] : []),
+      ...(info.rule ? [{ prop: "mgx:sourceRule", key: "sourceRule", value: info.rule }] : []),
+    ],
+  });
+  return info.id;
+}
+
+/**
+ * Parse one legacy provenance TAG into a Source descriptor over the closed kind
+ * set — the inverse the migration and the live write path both name Sources
+ * through. The tag formats are exactly what the writers produce:
+ *   corpus:conceptnet /r/IsA   → { kind:"corpus",   name:"conceptnet" }
+ *   ace:chat:<session>@<ts>    → { kind:"operator",  createdAt:<ts> }
+ *   web:<url> | url:<url>      → { kind:"web",       url:<url> }
+ *   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:")) return { kind: "corpus", name: head.slice("corpus:".length) || "unknown" };
+  if (head.startsWith("ace:")) {
+    const at = head.indexOf("@");
+    return { kind: "operator", createdAt: at >= 0 ? head.slice(at + 1) : "" };
+  }
+  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("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) {
+  const m = {};
+  for (const i of payload.individuals) if (i?.class === SOURCE_CLASS) m[i.id] = i;
+  return m;
+}
+
+/** The Source ids a Fact is statedBy, read off the edge group. */
+function statedByObjectsFor(payload, factId) {
+  const g = payload.objectProperties.find((x) => x?.prop === STATED_BY_PROP);
+  return (g?.examples || []).filter((e) => e?.subject === factId).map((e) => e.object);
+}
+
+/** 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()) {
+  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 });
+  setAttr(fact, TRUST_SCORE_PROP, "trustScore", String(score));
+  setAttr(fact, TRUST_INPUTS_PROP, "trustInputs", JSON.stringify(inputs));
+}
+
+/** 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()) {
+  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.
+  const factCreated = (fact.attributes || []).find((a) => a?.prop === CREATED_AT_PROP)?.value || new Date(nowMs).toISOString();
+  for (const tag of prov.split(" | ").filter(Boolean)) {
+    const desc = provenanceTagToSource(tag);
+    if (!desc) continue;
+    const sid = upsertSource(payload, desc, factCreated);
+    if (!sid) continue;
+    upsertEdge(payload, { predicate: "statedBy", prop: STATED_BY_PROP }, {
+      subject: fact.id, object: sid, subjectLabel: fact.label, objectLabel: sourceLabel(sid),
+    });
+  }
+  recomputeFactTrust(payload, fact, nowMs);
+}
+
+/** Lazy, idempotent migration of the legacy provenance union (step (b)): any
+ *  Fact that carries the string but has NO statedBy edge yet gets its Sources +
+ *  edges + trust materialised. The string is KEPT as a compat shim (readers on
+ *  chat.mjs still key on it). New writes stay reconciled via syncFactSources, so
+ *  in steady state this scan finds nothing and converges. */
+function migrateLegacyProvenance(payload) {
+  if (!Array.isArray(payload?.individuals) || !Array.isArray(payload?.objectProperties)) return;
+  const statedGroup = payload.objectProperties.find((g) => g?.prop === STATED_BY_PROP);
+  const haveEdge = new Set((statedGroup?.examples || []).map((e) => e.subject));
+  let changed = false;
+  const now = Date.now();
+  for (const ind of payload.individuals) {
+    if (ind?.class !== FACT_CLASS) continue;
+    if (haveEdge.has(ind.id)) continue; // already reconciled (live path or prior run)
+    const prov = (ind.attributes || []).find((a) => a?.prop === "mgx:factProvenance")?.value || "";
+    if (!prov) continue;
+    syncFactSources(payload, ind, now);
+    changed = true;
+  }
+  if (changed) recountClasses(payload);
+}
 
 /** Upsert an individual by id (replace-in-place keeps ordering stable). */
 function upsertIndividual(payload, ind) {
@@ -147,7 +320,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];
+  const names = [MEMORY_SESSION_CLASS, UTTERANCE_CLASS, FACT_CLASS, SOURCE_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);
@@ -164,6 +337,7 @@ function ensureSession(payload, sessionId, started = "") {
     derived_from: [], mentions: [],
     attributes: [
       { prop: "rdf:type", key: "type", value: "owl:NamedIndividual" },
+      { prop: CREATED_AT_PROP, key: "createdAt", value: started || nowIso() },
       ...(started ? [{ prop: "mgx:sessionStarted", key: "started", value: started }] : []),
     ],
   });
@@ -172,7 +346,7 @@ function ensureSession(payload, sessionId, started = "") {
 
 /** Build (don't write) one Utterance individual + its edges; shared by the
  *  single and batch append paths. Returns the utterance id. */
-function putUtterance(payload, { role, text, ts, sessionId, sessionStarted = "", parsed = null, replyTo = null }) {
+function putUtterance(payload, { role, text, ts, sessionId, sessionStarted = "", parsed = null, replyTo = null, createdAt = "" }) {
   if (!ROLES.has(role)) throw new Error(`utterance role must be "visitor" or "tmct", got ${JSON.stringify(role)}`);
   if (!sessionId) throw new Error("utterance needs a sessionId");
   const cleanTs = String(ts || "");
@@ -180,6 +354,8 @@ function putUtterance(payload, { role, text, ts, sessionId, sessionStarted = "",
   const id = `utt:${sessionId}#${cleanTs}#${role}`;
   const label = labelOf(cleanText) || (role === "visitor" ? "a-visitor-said" : "a-tmct-said");
   const tokens = proseTokensFor({ doc: cleanText });
+  const prior = payload.individuals.find((x) => x?.id === id);
+  const createdAtVal = firstWriteCreatedAt(prior, createdAt || cleanTs); // first-write-wins
   const ind = {
     id, label, class: UTTERANCE_CLASS,
     derived_from: [], mentions: [],
@@ -188,6 +364,7 @@ function putUtterance(payload, { role, text, ts, sessionId, sessionStarted = "",
       { prop: "mgx:utteranceRole", key: "role", value: role },
       { prop: "mgx:utteranceText", key: "text", value: cleanText },
       { prop: "mgx:utteranceTs", key: "ts", value: cleanTs },
+      { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
       ...(parsed != null ? [{ prop: "mgx:utteranceParsed", key: "parsed", value: JSON.stringify(parsed) }] : []),
       ...(tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: tokens.join(" ") }] : []),
     ],
@@ -235,16 +412,6 @@ export async function appendUtterances(dir, utterances) {
   return { ids };
 }
 
-/** FNV-1a 32-bit — a stable little content hash for fact ids (dedupe by triple). */
-function fnv1a(s) {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < s.length; i += 1) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  return (h >>> 0).toString(16).padStart(8, "0");
-}
-
 /** Normalize a fact TERM (subject/object) so every writer converges on one
  *  spelling and the graph stays queryable: ConceptNet's /c/en/foo_bar, a
  *  grammar's tmct:Foo_bar and a bare "Foo bar" all become "foo bar". The
@@ -262,18 +429,21 @@ export function normFactTerm(t) {
  *  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 = "" } = {}) {
+export async function appendFact(dir, { subject, predicate, object, provenance = "", createdAt = "" } = {}) {
   const s = normFactTerm(subject);
   const p = normText(predicate);
   const o = normFactTerm(object);
   if (!s || !p || !o) throw new Error("a fact needs subject, predicate and object");
-  const id = `fact:${fnv1a(`${s}${p}${o}`)}`;
+  const id = `fact:${fnv1aHex(`${s}${p}${o}`)}`;
   const text = `${s} ${p} ${o}`;
   const tokens = proseTokensFor({ doc: text });
   await mutateMemory(dir, (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
+    // still key on); the Source edges below are DERIVED from it, purely additive.
     const provs = [...new Set([...priorProv.split(" | "), normText(provenance)].filter(Boolean))];
+    const createdAtVal = firstWriteCreatedAt(prior, createdAt); // first-write-wins
     upsertIndividual(payload, {
       id, label: labelOf(text), class: FACT_CLASS,
       derived_from: [], mentions: [],
@@ -282,11 +452,82 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
         { prop: "rdf:subject", key: "subject", value: s },
         { prop: "rdf:predicate", key: "predicate", value: p },
         { prop: "rdf:object", key: "object", value: o },
+        { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
         ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
         ...(tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: tokens.join(" ") }] : []),
       ],
     });
+    // 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));
     recountClasses(payload);
   });
   return { id };
 }
+
+// ---- 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 ×
+// trust and cites provenance WITHOUT re-walking the graph shape.
+
+/**
+ * Resolve every reified Fact in a loaded memory payload into a row carrying its
+ * Source ids + source-type multiset, the legacy provenance string (compat), and
+ * the cached trust score. Pure. The exported seam the chat/answer layer consumes
+ * for trust-weighted fact ranking.
+ */
+export function readFactRows(memory) {
+  const individuals = memory?.individuals || [];
+  const sourcesById = new Map(individuals.filter((i) => i?.class === SOURCE_CLASS).map((i) => [i.id, i]));
+  const statedGroup = (memory?.objectProperties || []).find((g) => g?.prop === STATED_BY_PROP);
+  const byFact = new Map();
+  for (const e of statedGroup?.examples || []) {
+    if (!byFact.has(e.subject)) byFact.set(e.subject, []);
+    byFact.get(e.subject).push(e.object);
+  }
+  const rows = [];
+  for (const ind of individuals) {
+    if (ind?.class !== FACT_CLASS) continue;
+    const get = (k) => (ind.attributes || []).find((a) => a?.key === k)?.value || "";
+    const sourceIds = byFact.get(ind.id) || [];
+    const sourceTypes = sourceIds
+      .map((id) => (sourcesById.get(id)?.attributes || []).find((a) => a?.prop === "mgx:sourceType")?.value)
+      .filter(Boolean);
+    rows.push({
+      id: ind.id,
+      subject: get("subject"), predicate: get("predicate"), object: get("object"),
+      provenance: get("provenance"), // legacy compat string, verbatim
+      sourceIds, sourceTypes,
+      trust: Number((ind.attributes || []).find((a) => a?.prop === TRUST_SCORE_PROP)?.value) || 0,
+    });
+  }
+  return rows;
+}
+
+/** The trust floor a fact must clear before a differing object counts as a real
+ *  contradiction (below it the fact is too weak to contradict anything). */
+export const CONTRADICTION_TRUST_FLOOR = 0.5;
+
+/**
+ * Facts that CONTRADICT: same (subject, predicate), DIFFERENT object, each above
+ * the trust floor. Returns groups (each a [rows] sorted by trust desc) so the
+ * answer/inspection layer surfaces BOTH with their provenance and NEVER silently
+ * picks the higher-trust one. Same (s,p,o) from two writers is corroboration,
+ * not contradiction — one Fact id, N statedBy edges — so it never appears here.
+ */
+export function findContradictions(memory, { floor = CONTRADICTION_TRUST_FLOOR } = {}) {
+  const rows = readFactRows(memory).filter((r) => r.trust >= floor);
+  const byKey = new Map();
+  for (const r of rows) {
+    const key = `${r.subject} ${r.predicate}`;
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(r);
+  }
+  const out = [];
+  for (const group of byKey.values()) {
+    if (new Set(group.map((r) => r.object)).size > 1) {
+      out.push(group.slice().sort((a, b) => b.trust - a.trust || a.object.localeCompare(b.object)));
+    }
+  }
+  return out.sort((a, b) => `${a[0].subject} ${a[0].predicate}`.localeCompare(`${b[0].subject} ${b[0].predicate}`));
+}

package/src/memory/inspect.mjs

@@ -0,0 +1,141 @@
+// memory/inspect.mjs — seeing into the memory as TEXT (ROADMAP Phase 4,
+// "Memory inspection"). One renderer serves both surfaces — the `/memory` chat
+// command and the `tmct memory` CLI — in a terse (default) and a verbose form:
+//
+//   - the memory graph grouped by OWL superclass (Fact / Utterance / Session,
+//     plus any other class present), counts with BALANCED samples scaled
+//     log-wise to class size (a 10,000-fact class shows ~8 exemplars, a
+//     3-session class shows all 3);
+//   - top facts ranked by PROVENANCE BREADTH (a fact the corpus AND the chat
+//     both asserted outranks a single-writer fact), provenance verbatim;
+//   - recent Q→A utterance pairs (read off the mgx:inReplyTo edges);
+//   - the block-index summary (blocks, indexed tokens, top PageRank blocks).
+//
+// Pure renderers over loaded payloads + one thin I/O wrapper (inspectMemory).
+// Everything degrades honestly: an empty memory renders as the empty story,
+// never an error.
+
+import { loadMemory, UTTERANCE_CLASS, IN_REPLY_TO_PROP, readFactRows, findContradictions } from "./core.mjs";
+import { loadBlockIndex } from "./blocks.mjs";
+
+/** Log-scaled sample count for a class of `n` individuals: 2·log10(n), floored
+ *  at 3, never more than n (10,000 → 8; 500 → 5; 3 → 3; 1 → 1). Verbose doubles. */
+export function sampleSize(n, { verbose = false } = {}) {
+  const base = Math.max(3, Math.round(2 * Math.log10(Math.max(1, n))));
+  return Math.min(n, verbose ? base * 2 : base);
+}
+
+/** Evenly-spaced (balanced) deterministic sample of k items — spans the class
+ *  start to end rather than showing the first k. */
+export function balancedSample(items, k) {
+  const n = items.length;
+  if (n <= k) return items.slice();
+  if (k <= 1) return [items[0]];
+  const out = [];
+  for (let i = 0; i < k; i += 1) out.push(items[Math.round((i * (n - 1)) / (k - 1))]);
+  return out;
+}
+
+const attrOf = (ind, key) => (ind?.attributes || []).find((a) => a.key === key)?.value || "";
+const truncate = (s, cap) => {
+  const t = String(s ?? "").replace(/\s+/g, " ").trim();
+  return t.length > cap ? `${t.slice(0, cap - 1)}…` : t;
+};
+
+/** Render a loaded memory payload + block index into the inspection text.
+ *  Pure. `verbose` widens every cap and stops truncating provenance/text. */
+export function renderMemory({ memory, blocks }, { verbose = false } = {}) {
+  const individuals = memory?.individuals || [];
+  const lines = [];
+  const textCap = verbose ? 400 : 100;
+
+  if (!individuals.length) {
+    lines.push("memory is empty — nothing remembered yet (facts, utterances and sessions land in .tmct/memory/ as you chat).");
+  } else {
+    // ---- classes: counts + balanced log-scaled samples ----
+    const byClass = new Map();
+    for (const ind of individuals) {
+      const cls = ind?.class || "(unclassified)";
+      if (!byClass.has(cls)) byClass.set(cls, []);
+      byClass.get(cls).push(ind);
+    }
+    const classes = [...byClass.entries()].sort((a, b) => b[1].length - a[1].length);
+    lines.push(`memory — ${individuals.length} individuals: ${classes.map(([c, of]) => `${of.length} ${c}`).join(", ")}.`);
+    for (const [cls, of] of classes) {
+      const k = sampleSize(of.length, { verbose });
+      lines.push("", `${cls} — ${of.length} (showing ${k})`);
+      for (const ind of balancedSample(of, k)) lines.push(`  ${truncate(ind.label, textCap)}`);
+    }
+
+    // ---- top facts by COMPUTED TRUST (upgraded from raw provenance breadth) ----
+    // Trust folds source-type prior + corroboration + recency, so a corroborated
+    // operator-stated fact outranks a lone web scrape by construction; provenance
+    // rides along (verbatim in verbose) for the audit trail.
+    const ranked = readFactRows(memory)
+      .filter((r) => r.sourceIds.length || r.provenance)
+      .sort((a, b) => b.trust - a.trust
+        || b.sourceIds.length - a.sourceIds.length
+        || `${a.subject} ${a.predicate} ${a.object}`.localeCompare(`${b.subject} ${b.predicate} ${b.object}`));
+    if (ranked.length) {
+      lines.push("", "top facts by trust:");
+      for (const r of ranked.slice(0, verbose ? 8 : 3)) {
+        const n = r.sourceIds.length || (r.provenance ? r.provenance.split(" | ").filter(Boolean).length : 0);
+        const label = `${r.subject} ${r.predicate} ${r.object}`;
+        lines.push(`  ${truncate(label, textCap)} — trust ${r.trust.toFixed(2)}, ${n} source${n === 1 ? "" : "s"}: ${verbose ? r.provenance : truncate(r.provenance, 80)}`);
+      }
+    }
+
+    // ---- contradictions: same (subject,predicate), differing object, both above
+    //      the trust floor → surface BOTH with provenance, never silently pick ----
+    const contradictions = findContradictions(memory);
+    if (contradictions.length) {
+      lines.push("", `contradictions (${contradictions.length} — both kept, never silently resolved):`);
+      for (const group of contradictions.slice(0, verbose ? 8 : 3)) {
+        lines.push(`  ${group[0].subject} ${group[0].predicate}?`);
+        for (const r of group) {
+          lines.push(`    ${truncate(r.object, textCap)} (trust ${r.trust.toFixed(2)}; ${verbose ? r.provenance : truncate(r.provenance, 60)})`);
+        }
+      }
+    }
+
+    // ---- recent Q→A pairs (off the inReplyTo edges) ----
+    const byId = new Map(individuals.map((i) => [i.id, i]));
+    const replyGroup = (memory.objectProperties || []).find((g) => g?.prop === IN_REPLY_TO_PROP);
+    const pairs = (replyGroup?.examples || [])
+      .map((e) => ({ a: byId.get(e.subject), q: byId.get(e.object) }))
+      .filter((p) => p.a && p.q && p.a.class === UTTERANCE_CLASS)
+      .sort((x, y) => attrOf(y.a, "ts").localeCompare(attrOf(x.a, "ts")));
+    if (pairs.length) {
+      lines.push("", `recent Q→A pairs (${pairs.length} recorded):`);
+      for (const p of pairs.slice(0, verbose ? 8 : 3)) {
+        lines.push(`  Q: ${truncate(attrOf(p.q, "text"), textCap)}`);
+        lines.push(`  A: ${truncate(attrOf(p.a, "text"), textCap)}`);
+      }
+    }
+  }
+
+  // ---- block-index summary ----
+  const entries = Object.entries(blocks?.blocks || {});
+  if (entries.length) {
+    const tokens = entries.reduce((n, [, b]) => n + (b.tokens?.length || 0), 0);
+    const top = entries
+      .slice()
+      .sort((a, b) => (b[1].rank ?? 0) - (a[1].rank ?? 0) || a[0].localeCompare(b[0]))
+      .slice(0, verbose ? 8 : 3);
+    lines.push("", `blocks — ${entries.length} folded session block${entries.length === 1 ? "" : "s"}, ${tokens} indexed tokens.`);
+    lines.push(`  top by rank: ${top.map(([id, b]) => `${String(id).slice(0, 8)} (${(b.rank ?? 0).toFixed(3)})`).join(", ")}`);
+  } else {
+    lines.push("", "blocks — none folded yet (a session folds when it ends).");
+  }
+
+  return lines.join("\n");
+}
+
+/** Load + render a repo's memory (the one thin I/O wrapper both the `/memory`
+ *  chat command and the `tmct memory` CLI call). Never throws on a missing
+ *  store — that is the honest empty story. */
+export async function inspectMemory(dir, { verbose = false } = {}) {
+  const memory = await loadMemory(dir);
+  const blocks = await loadBlockIndex(dir);
+  return renderMemory({ memory, blocks }, { verbose });
+}

package/src/memory/trust.mjs

@@ -0,0 +1,113 @@
+// memory/trust.mjs — deterministic, explainable, auditable trust over a Fact's
+// Sources (PLAN_PROVENANCE_TRUST step (c)).
+//
+// Trust is a COMPUTED attribute of a Fact — never hand-set — a pure function of
+// its Source edges, those Sources' types, and its mgx:createdAt. Three inputs
+// combine:
+//   - a Source-TYPE PRIOR (operator > provider > corpus > web > entailed);
+//   - CORROBORATION over the fact's distinct Sources by noisy-OR
+//     (1 − Π(1 − wᵢ), capped at 1) — two independent web sources (0.4) reach
+//     0.64, a lone operator fact is already 1.0;
+//   - a bounded RECENCY nudge in [0.9, 1.0] from createdAt, half-life decayed —
+//     the codegraph "capped nudge" philosophy, so recency breaks ties and
+//     freshens but never flips a source-type ordering by itself.
+//
+// For ENTAILED facts (tier-5): trust = min(premise trusts) × rule-confidence — a
+// conclusion is only as trustworthy as its weakest premise. Premises may be
+// absent for now, so this is a documented HOOK: pass opts.premiseTrusts (and
+// opts.ruleConfidence) and it engages; otherwise an entailed fact scores off its
+// bare 0.3 prior like any other Source.
+//
+// This module is PURE and import-free of core.mjs (no cycle): it reads Source
+// individuals by their attribute props and returns { score, inputs }. core.mjs
+// materialises the score onto the Fact (mgx:trustScore) plus the inputs it was
+// computed from (mgx:trustInputs), so every score is reproducible and auditable.
+
+export const TRUST_SCORE_PROP = "mgx:trustScore";
+export const TRUST_INPUTS_PROP = "mgx:trustInputs";
+
+/** Source-type priors — the ordering operator > provider-graph > curated-corpus
+ *  > web > unverified-entailment. The entailed value is a FLOOR before premise
+ *  adjustment (see the entailed hook below). */
+export const SOURCE_PRIOR = Object.freeze({
+  operator: 1.0,
+  provider: 0.9,
+  corpus: 0.7,
+  web: 0.4,
+  entailed: 0.3,
+});
+
+export const RECENCY_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+export const RECENCY_FLOOR = 0.9; // recency multiplier stays within [0.9, 1.0]
+
+const round = (n, p = 6) => Number(n.toFixed(p));
+const sourceTypeOf = (s) => (s?.attributes || []).find((a) => a.prop === "mgx:sourceType")?.value || "";
+
+/**
+ * Bounded recency multiplier in [RECENCY_FLOOR, 1] from an ISO-8601 createdAt.
+ * A half-life decay: freshly written ≈ 1.0, ancient → RECENCY_FLOOR. An unknown
+ * or unparseable timestamp yields 1.0 (no penalty) — recency only ever nudges
+ * down from a full score, it never invents one.
+ */
+export function recencyNudge(createdAt, now = Date.now(), halfLifeMs = RECENCY_HALF_LIFE_MS) {
+  const t = Date.parse(createdAt);
+  if (!Number.isFinite(t)) return 1;
+  const ageMs = Math.max(0, now - t);
+  return RECENCY_FLOOR + (1 - RECENCY_FLOOR) * Math.pow(0.5, ageMs / halfLifeMs);
+}
+
+/**
+ * Pure trust for one Fact. `fact` supplies `{ sourceIds: [...], createdAt }`;
+ * the Source individuals are resolved from `sourcesById` (a plain { id: Source }
+ * map — exactly what a memory payload's Source individuals key into). Distinct
+ * sources are corroborated by noisy-OR over their type priors and nudged by
+ * recency. Deterministic given the same inputs and `opts.now`.
+ *
+ * opts:
+ *   - now            (ms) reference time for recency; default Date.now()
+ *   - halfLifeMs     recency half-life override
+ *   - premiseTrusts  entailed hook: [trusts] of the conclusion's premise Facts
+ *   - ruleConfidence entailed hook: the rule's confidence in [0,1] (default 1)
+ *
+ * Returns { score, inputs } — `inputs` (the source-type multiset, corroboration
+ * count, createdAt and the recency multiplier) is stored alongside the score so
+ * "why does this rank high?" is answerable from the record.
+ */
+export function computeTrust(fact, sourcesById = {}, opts = {}) {
+  const now = typeof opts.now === "number" ? opts.now : Date.now();
+  const ids = Array.isArray(fact?.sourceIds) ? fact.sourceIds : [];
+
+  // distinct sources → their type priors
+  const seen = new Set();
+  const types = [];
+  for (const id of ids) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const t = sourceTypeOf(sourcesById[id]);
+    if (t) types.push(t);
+  }
+
+  // corroboration via noisy-OR over distinct-source priors, capped at 1
+  let base = 0;
+  let complement = 1;
+  for (const t of types) complement *= 1 - (SOURCE_PRIOR[t] ?? 0);
+  if (types.length) base = Math.min(1, 1 - complement);
+
+  // entailed hook (tier-5): a conclusion is only as trustworthy as its weakest
+  // premise × the rule confidence. Engages only when premises are supplied;
+  // otherwise an entailed fact rides its bare prior through the noisy-OR above.
+  if (types.includes("entailed") && Array.isArray(opts.premiseTrusts) && opts.premiseTrusts.length) {
+    const rc = typeof opts.ruleConfidence === "number" ? opts.ruleConfidence : 1;
+    base = Math.max(0, Math.min(1, Math.min(...opts.premiseTrusts) * rc));
+  }
+
+  const recency = recencyNudge(fact?.createdAt, now, opts.halfLifeMs);
+  const score = round(Math.min(1, base * recency));
+  const inputs = {
+    sourceTypes: types.slice().sort(),
+    corroboration: types.length,
+    createdAt: fact?.createdAt || "",
+    recency: round(recency),
+  };
+  return { score, inputs };
+}