@polycode-projects/the-mechanical-code-talker 1.5.4 → 1.8.3

package/src/memory/core.mjs

@@ -57,6 +57,12 @@ export const DERIVED_FROM_PROP = "mgx:derivedFrom";        // umbrella: 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
+// DERIVED at read/render time for most individuals (codegraph.mjs's derivedUpdatedAt: an
+// individual's own createdAt, or the max createdAt over every edge touching it) — this constant
+// exists for the handful of call sites that mutate an individual's OWN attributes in place
+// without necessarily touching an edge (upsertSession, recomputeFactTrust,
+// recomputeSourceReliability), where the derived rule alone can't see the change (PLAN_VIZ.md §2).
+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]
 
 // The bare (session-less) singleton Source ids — the fallback for an
@@ -98,6 +104,7 @@ const MEMORY_VOCABULARY = [
   { prop: "mgx:ruleBaseCase", note: "recursive only: the base-case relation name (hop zero)" },
   { prop: "mgx:ruleRecStep", note: "recursive only: the self-referential recursive-step relation name" },
   { prop: CREATED_AT_PROP, note: "when an individual was FIRST written, ISO-8601 (first-write-wins on upsert); the audit 'when', the recency input to trust, the novelty signal" },
+  { prop: UPDATED_AT_PROP, note: "when an individual's OWN attributes were last mutated in place (upsertSession, recomputeFactTrust, recomputeSourceReliability) — most individuals never carry this and instead derive 'updated' from codegraph.mjs's derivedUpdatedAt (max createdAt over their edges)" },
   { 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" },
@@ -141,12 +148,430 @@ export function emptyMemory() {
  *  independent path-resolution copies (core.mjs's mutateMemory and fold.mjs's
  *  writeMemoryGraph used to compute this path separately). */
 export function resolveMemoryGraphFile(dir, version = null) {
+  if (isMemoryHandle(dir) || isSqliteHandle(dir)) {
+    throw new Error("resolveMemoryGraphFile: dir is a memory/sqlite handle, not a file path (Backend A only)");
+  }
   if (version === null) return join(dir, MEMORY_GRAPH_REL);
   return join(dir, MEMORY_DIR_REL, `graph.v${version}.json`);
 }
 
 const memoryGraphFile = (dir) => resolveMemoryGraphFile(dir);
 
+// ---- Storage-backend seam (PLAN_SEED.md §6) ---------------------------------
+//
+// Every dir-taking export in this file historically assumed `dir` was a plain
+// string repo path that resolveMemoryGraphFile joins into an on-disk file
+// (Backend A, unchanged below — still the exact byte-identical default for
+// every existing caller that never opts into anything else).
+//
+// `dir` may now ALSO be a memory HANDLE: a small tagged object created by
+// createInMemoryStore() (Backend B, pure in-memory, zero disk I/O) or
+// createSqliteMemoryStore() (Backend C, a live node:sqlite connection kept
+// open for the session's lifetime). loadMemory/mutateMemory below recognize
+// both and dispatch the LOAD/PERSIST steps only; every other function in this
+// file (appendFact, appendFacts, appendUtterance(s), appendRule,
+// readFactRows, findRuleByName, resolveRelationChase(Reverse),
+// findContradictions) takes `memory`/`dir` exactly as before and never
+// branches on backend — they operate on the plain JS payload object
+// mutateMemory hands them, regardless of where it came from or where it goes
+// next. That is the whole point of the seam: id hashing, provenance/trust
+// computation, migrateLegacyProvenance, recomputeSourceReliability and
+// buildProseIndex are backend-agnostic logic, unchanged either way.
+//
+// snapshotMemory (manifest-versioned snapshots) and resolveMemoryGraphFile
+// stay Backend-A-only (a handle has no on-disk file to snapshot) — both throw
+// a clear error if given a handle rather than silently doing the wrong thing.
+
+const BACKEND_MEMORY = "memory";
+const BACKEND_SQLITE = "sqlite";
+
+function isMemoryHandle(dir) {
+  return !!dir && typeof dir === "object" && dir.backend === BACKEND_MEMORY;
+}
+function isSqliteHandle(dir) {
+  return !!dir && typeof dir === "object" && dir.backend === BACKEND_SQLITE;
+}
+function isMemoryOrSqliteHandle(dir) {
+  return isMemoryHandle(dir) || isSqliteHandle(dir);
+}
+
+/**
+ * Backend B — pure in-memory store (new). A plain JS object held by the
+ * CALLER (never module-global state, which would break multiple concurrent
+ * sessions in one process): `{ backend: "memory", payload }`. loadMemory
+ * returns `payload` directly (the live reference, not a fresh parse — there
+ * is nothing to parse); mutateMemory's persist step is a no-op assignment
+ * (`handle.payload = out` — already the same object in every real caller,
+ * since none of appendFact/appendFacts/appendUtterance(s)/appendRule ever
+ * return a NEW object from their mutateMemory callback, they all mutate the
+ * payload in place). ZERO readFile/writeFile/JSON.parse/JSON.stringify calls
+ * ever happen for this backend — verified directly by this module's own
+ * dispatch (no fs import is even reachable from this path) and by
+ * test/memory-backend-memory.test.mjs's fs-spy assertions.
+ *
+ * Distinct from `--ephemeral` (createSession): ephemeral mode still does real
+ * readFile/JSON.parse/writeFile round-trips against a throwaway mkdtemp temp
+ * dir every turn — "disposable disk," not "no disk." Backend B is genuinely
+ * disk-free.
+ */
+export function createInMemoryStore() {
+  return { backend: BACKEND_MEMORY, payload: emptyMemory() };
+}
+
+// ---- Backend C — SQLite (new; schema shape adapted from seonix's src/store.mjs,
+// write model is NOT) ----------------------------------------------------------
+//
+// seonix (a sibling repo consuming tmct as a library) already has a working,
+// opt-in node:sqlite store (SEONIX_STORE=sqlite, node:sqlite lazily imported,
+// zero external dependency): an `ids`/`nodes`/`relations`/`edges`/`meta` table
+// set. Its WRITE MODEL is a full rebuild-and-atomic-swap on every write — correct
+// for seonix's problem (read-latency on a relatively static, rebuild-on-change
+// code graph), wrong for tmct's (write-heavy, one-fact-at-a-time accumulation
+// across a session's lifetime): lifting it as-is would just replace "rewrite the
+// whole JSON file per turn" with "rebuild the whole SQLite file per turn."
+//
+// tmct's Backend C reuses the SHAPE, not the write model: real per-row
+// INSERT/REPLACE/DELETE against a LIVE, OPEN connection kept for the session's
+// lifetime (see createSqliteMemoryStore/closeSqliteMemoryStore below),
+// diffed against whatever is already on that row so only touched
+// individuals/edges are ever written — not seonix's rebuild-and-swap.
+//
+// Schema, adapted (not ported) to tmct's actual payload shape (emptyMemory(),
+// above — { generated_at, memory, prefixes, vocabulary, classes,
+// objectProperties, individuals, proseIndex }, distinct from seonix's code-graph
+// `entities` shape): seonix's separate integer-interning `ids` table exists to
+// cover edge endpoints that AREN'T always node ids (e.g. an `inherits` edge's
+// `ext:<Base>` target). tmct's own edge groups (saidInSession, inReplyTo,
+// statedBy, canonicalisedFrom) only ever link two individuals-table ids, so
+// that interning table is dropped here — individuals/edges reference each
+// other by their natural TEXT id directly, a deliberate simplification over a
+// literal port. A Fact's reified rdf:subject/rdf:predicate/rdf:object live as
+// ATTRIBUTES on the individual (tmct's own reification style, no seonix
+// equivalent), so they ride inside that individual's own JSON blob column —
+// no separate fact-triple columns needed.
+//
+// Cached, incrementally patched reads (closes the PLAN_SEED.md §6 gap the
+// prior "honest shortcut" comment used to flag here): the READ side
+// (readSqlitePayload) reconstructs the FULL in-memory payload shape from real
+// SQL SELECTs only ONCE — the first call for a given handle, or the first
+// call after a failed/rolled-back write — and stashes the result on
+// `handle.cachedPayload`. Every later call returns a deep clone of that cache
+// directly, with ZERO SQL queries: no re-SELECT of individuals, no
+// per-relation edge SELECT. The WRITE side (persistSqlitePayload) was never a
+// shortcut: it already diffs the incoming payload against what is already in
+// each row/edge-group and only issues a real INSERT/REPLACE/DELETE for what
+// actually changed (write cost proportional to what changed this turn, not to
+// the total store size). It now ALSO applies that exact same diff to
+// `handle.cachedPayload` in lockstep — patching only the individuals/edges it
+// actually wrote to SQLite, in the same order SQLite itself would reorder
+// them (a changed row gets a fresh rowid and sorts last) — so the cache never
+// goes stale, and never needs a re-query to catch up either. If a write fails
+// mid-transaction (ROLLBACK), the partially-patched cache is not trusted: it
+// is invalidated so the NEXT read does an honest full rebuild instead of
+// risking a state that was never actually committed.
+
+const SQLITE_DDL = `
+CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS individuals (id TEXT PRIMARY KEY, ord INTEGER NOT NULL, class TEXT, label TEXT, json TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS relations (prop TEXT PRIMARY KEY, ord INTEGER NOT NULL, predicate TEXT, count INTEGER);
+CREATE TABLE IF NOT EXISTS edges (prop TEXT NOT NULL, subject TEXT NOT NULL, object TEXT NOT NULL, subject_label TEXT, object_label TEXT, extra TEXT, PRIMARY KEY (prop, subject, object));
+CREATE INDEX IF NOT EXISTS edges_by_prop ON edges(prop);
+`;
+
+// Edge keys with dedicated columns; any other key on an edge example object
+// (none exist in core.mjs's own edge groups today, but a future/external
+// writer might add one) round-trips via the `extra` JSON column, same
+// discipline as seonix's own STD_EDGE_KEYS.
+const STD_EDGE_KEYS = new Set(["subject", "object", "subjectLabel", "objectLabel"]);
+
+/**
+ * Open (creating if absent) a resident node:sqlite connection for `dbPath` and
+ * return a Backend C handle: `{ backend: "sqlite", db, dbPath }`. `node:sqlite`
+ * is imported LAZILY here — calling this function is the ONLY way it is ever
+ * loaded, so a caller that never opts into this backend never even imports it
+ * (matching seonix's own SEONIX_STORE=sqlite gating discipline, and tmct's
+ * minimal-deps philosophy: zero external dependency either way).
+ *
+ * The connection is meant to be opened ONCE per session and kept open for the
+ * session's lifetime (not re-opened per call) — close it via
+ * closeSqliteMemoryStore when the session ends.
+ */
+export async function createSqliteMemoryStore(dbPath) {
+  const { DatabaseSync } = await import("node:sqlite");
+  const db = new DatabaseSync(dbPath);
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA synchronous = NORMAL");
+  db.exec(SQLITE_DDL);
+  return { backend: BACKEND_SQLITE, db, dbPath };
+}
+
+/** Close a Backend C handle's connection. A no-op for anything else (so a
+ *  caller that doesn't know which backend it has can call this unconditionally
+ *  at session end). */
+export function closeSqliteMemoryStore(handle) {
+  if (isSqliteHandle(handle)) handle.db.close();
+}
+
+/** Deep-clone a JSON-safe value. Used two ways here: (1) readSqlitePayload
+ *  hands every CALLER a clone of the cache, never the live cached object
+ *  itself, so this backend keeps the same "fresh object every call" contract
+ *  Backend A's JSON.parse(readFile()) always had — nothing outside this
+ *  module can mutate handle.cachedPayload by mutating what loadMemory
+ *  returned; and (2) persistSqlitePayload clones a value INTO the cache so
+ *  the cache never ends up aliasing a piece of the caller's own payload
+ *  object (which mutateMemory's caller may go on to mutate further). */
+const cloneJson = (v) => (v === undefined ? v : structuredClone(v));
+
+/** The loadMemory-equivalent read for Backend C. First call for a handle (or
+ *  first call after a failed write invalidated the cache): a real, full
+ *  reconstruction from SQL SELECTs, same as before — then it is stashed on
+ *  `handle.cachedPayload`. Every later call, with no write in between, skips
+ *  SQL entirely and returns a clone of that cache (see the module-comment
+ *  above SQLITE_DDL for the full mechanism). A brand-new store (no meta rows
+ *  written yet) reconstructs to the same shape emptyMemory() returns, so a
+ *  fresh handle behaves like Backend A's ENOENT-bootstrap and Backend B's
+ *  fresh createInMemoryStore(). */
+function readSqlitePayload(handle) {
+  if (!handle.cachedPayload) handle.cachedPayload = buildSqlitePayloadFromRows(handle);
+  return cloneJson(handle.cachedPayload);
+}
+
+/** The actual SQL reconstruction — unchanged from the pre-cache implementation,
+ *  just extracted so readSqlitePayload can call it only when the cache is
+ *  cold. */
+function buildSqlitePayloadFromRows(handle) {
+  const db = handle.db;
+  const empty = emptyMemory();
+  const getMeta = (k, fallback) => {
+    const row = db.prepare("SELECT v FROM meta WHERE k = ?").get(k);
+    return row ? JSON.parse(row.v) : fallback;
+  };
+
+  const individuals = db.prepare("SELECT json FROM individuals ORDER BY ord").all()
+    .map((r) => JSON.parse(r.json));
+
+  const edgesForProp = db.prepare(
+    "SELECT subject, object, subject_label, object_label, extra FROM edges WHERE prop = ? ORDER BY rowid",
+  );
+  const objectProperties = db.prepare("SELECT prop, predicate, count FROM relations ORDER BY ord").all()
+    .map((r) => ({
+      predicate: r.predicate,
+      prop: r.prop,
+      count: r.count,
+      examples: edgesForProp.all(r.prop).map((e) => {
+        const edge = { subject: e.subject, object: e.object, subjectLabel: e.subject_label, objectLabel: e.object_label };
+        if (e.extra) Object.assign(edge, JSON.parse(e.extra));
+        return edge;
+      }),
+    }));
+
+  return {
+    generated_at: getMeta("generated_at", empty.generated_at),
+    memory: getMeta("memory", empty.memory),
+    prefixes: getMeta("prefixes", empty.prefixes),
+    vocabulary: getMeta("vocabulary", empty.vocabulary),
+    classes: getMeta("classes", empty.classes),
+    objectProperties,
+    individuals,
+    proseIndex: getMeta("proseIndex", empty.proseIndex),
+  };
+}
+
+// ---- handle.cachedPayload mirrors --------------------------------------
+// Applied by persistSqlitePayload in LOCKSTEP with the SQL statement sitting
+// right beside each call — same condition (only when the SQL write actually
+// runs), same effect, so the cache always ends up holding exactly what a
+// fresh SQL reconstruction would now produce. `cache.individuals`/
+// `cache.objectProperties` are mutated in place; persistSqlitePayload is
+// responsible for invalidating the whole cache on a rolled-back write (these
+// helpers assume the surrounding transaction succeeds).
+
+/** Mirrors `INSERT OR REPLACE INTO individuals(...)`: an existing id is
+ *  replaced IN PLACE (same array position, matching how SQL keeps that row's
+ *  `ord` — and so its sort position — unchanged on an update); a new id is
+ *  appended (matching a fresh row getting the next `ord`). */
+function cacheUpsertIndividual(cache, ind) {
+  const clone = cloneJson(ind);
+  const i = cache.individuals.findIndex((x) => x?.id === ind.id);
+  if (i >= 0) cache.individuals[i] = clone;
+  else cache.individuals.push(clone);
+}
+
+/** Mirrors the individuals delete loop: drop any cached individual whose id
+ *  isn't in the just-persisted payload's full id set. */
+function cacheDropIndividualsExcept(cache, seenIds) {
+  cache.individuals = cache.individuals.filter((i) => seenIds.has(i?.id));
+}
+
+/** Find-or-create the cached edge group for `prop` — mirrors a relation row
+ *  being implicitly created the first time a group is written. */
+function cacheGroupFor(cache, prop) {
+  let g = cache.objectProperties.find((x) => x?.prop === prop);
+  if (!g) {
+    g = { predicate: null, prop, count: 0, examples: [] };
+    cache.objectProperties.push(g);
+  }
+  return g;
+}
+
+/** Mirrors `INSERT OR REPLACE INTO edges(...)`: SQLite deletes-then-reinserts
+ *  a changed/new row on conflict, so it gets a fresh (highest) rowid and sorts
+ *  LAST under readSqlitePayload's `ORDER BY rowid` — moving the entry to the
+ *  end of `examples` here (rather than replacing it in place) reproduces that
+ *  ordering exactly, without a re-SELECT. Rebuilds the cached edge shape the
+ *  same way buildSqlitePayloadFromRows does (subject/object/labels + any
+ *  extra keys), from the same `extraKeys` persistSqlitePayload already
+ *  computed for the SQL `extra` column, so it never re-derives them. Same
+ *  NUL-delimited (subject,object) key discipline as the SQL diff beside it
+ *  (a space could be forged by a term that contains one; NUL never occurs in
+ *  a normalized term). */
+function cacheUpsertEdge(group, edge, extraKeys) {
+  const key = `${edge.subject}\u0000${edge.object}`;
+  group.examples = group.examples.filter((e) => `${e.subject}\u0000${e.object}` !== key);
+  const cached = {
+    subject: edge.subject, object: edge.object,
+    subjectLabel: edge.subjectLabel ?? null, objectLabel: edge.objectLabel ?? null,
+  };
+  if (extraKeys.length) Object.assign(cached, cloneJson(Object.fromEntries(extraKeys.map((k) => [k, edge[k]]))));
+  group.examples.push(cached);
+}
+
+/** Mirrors the per-group edge delete loop: drop any cached edge in this group
+ *  whose (subject,object) key isn't in the just-persisted group's key set. */
+function cacheDropEdgesExcept(group, newKeys) {
+  group.examples = group.examples.filter((e) => newKeys.has(`${e.subject}\u0000${e.object}`));
+}
+
+/** Mirrors the relations delete loop: drop any cached edge group whose prop
+ *  wasn't in the just-persisted payload's `objectProperties`. */
+function cacheDropGroupsExcept(cache, seenProps) {
+  cache.objectProperties = cache.objectProperties.filter((g) => seenProps.has(g?.prop));
+}
+
+/** Persist a mutated payload into a Backend C handle: real per-row
+ *  INSERT/REPLACE/DELETE, diffed against whatever is ALREADY in the table for
+ *  that individual id / (prop,subject,object) edge key — not seonix's
+ *  rebuild-and-swap. Every statement runs inside one transaction so a session
+ *  never observes (or leaves on disk) a half-applied mutation.
+ *
+ *  Also patches `handle.cachedPayload` (if one exists yet — it always will in
+ *  practice, since mutateMemory always calls loadMemory before this) in the
+ *  same lockstep as the SQL diff below, so a subsequent loadMemory() never has
+ *  to re-query SQLite to see this write (see the module comment above
+ *  SQLITE_DDL). On a rolled-back write, the cache is invalidated rather than
+ *  left holding a partially-applied patch — the next read does an honest
+ *  full rebuild instead. */
+function persistSqlitePayload(handle, payload) {
+  const db = handle.db;
+  const empty = emptyMemory();
+  const cache = handle.cachedPayload || null;
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const setMeta = db.prepare("INSERT OR REPLACE INTO meta(k, v) VALUES (?, ?)");
+    setMeta.run("generated_at", JSON.stringify(payload.generated_at ?? empty.generated_at));
+    setMeta.run("memory", JSON.stringify(payload.memory ?? empty.memory));
+    setMeta.run("prefixes", JSON.stringify(payload.prefixes ?? empty.prefixes));
+    setMeta.run("vocabulary", JSON.stringify(payload.vocabulary ?? empty.vocabulary));
+    setMeta.run("classes", JSON.stringify(payload.classes ?? empty.classes));
+    setMeta.run("proseIndex", JSON.stringify(payload.proseIndex ?? empty.proseIndex));
+    if (cache) {
+      cache.generated_at = cloneJson(payload.generated_at ?? empty.generated_at);
+      cache.memory = cloneJson(payload.memory ?? empty.memory);
+      cache.prefixes = cloneJson(payload.prefixes ?? empty.prefixes);
+      cache.vocabulary = cloneJson(payload.vocabulary ?? empty.vocabulary);
+      cache.classes = cloneJson(payload.classes ?? empty.classes);
+      cache.proseIndex = cloneJson(payload.proseIndex ?? empty.proseIndex);
+    }
+
+    // individuals: a real per-row upsert, only for an id that is new or whose
+    // JSON actually changed since the last persist — every other row is left
+    // untouched (no whole-table rewrite).
+    const getInd = db.prepare("SELECT ord, json FROM individuals WHERE id = ?");
+    const maxOrd = db.prepare("SELECT COALESCE(MAX(ord), -1) AS m FROM individuals").get().m;
+    let nextOrd = maxOrd + 1;
+    const upsertInd = db.prepare("INSERT OR REPLACE INTO individuals(id, ord, class, label, json) VALUES (?, ?, ?, ?, ?)");
+    const seenIds = new Set();
+    for (const ind of payload.individuals || []) {
+      seenIds.add(ind.id);
+      const json = JSON.stringify(ind);
+      const existing = getInd.get(ind.id);
+      if (existing && existing.json === json) continue; // unchanged — skip the write entirely (cache already matches)
+      const ord = existing ? existing.ord : nextOrd++;
+      upsertInd.run(ind.id, ord, ind.class ?? null, ind.label ?? null, json);
+      if (cache) cacheUpsertIndividual(cache, ind);
+    }
+    // Removal (no appendX function in this file ever removes an individual
+    // today — dead code path in practice, kept for correctness): a cheap
+    // index-only scan of the primary-key column only, never the JSON payload.
+    const deleteInd = db.prepare("DELETE FROM individuals WHERE id = ?");
+    for (const row of db.prepare("SELECT id FROM individuals").all()) {
+      if (!seenIds.has(row.id)) deleteInd.run(row.id);
+    }
+    if (cache) cacheDropIndividualsExcept(cache, seenIds);
+
+    // objectProperties/edges: per-edge diff WITHIN each group, scoped to that
+    // group's own rows (edges_by_prop) rather than the whole edges table — a
+    // group that gains one new edge (e.g. statedBy, touched by nearly every
+    // appendFact call) writes exactly that one new row, not the group's
+    // entire history.
+    const getRelOrd = db.prepare("SELECT ord FROM relations WHERE prop = ?");
+    const maxRelOrd = db.prepare("SELECT COALESCE(MAX(ord), -1) AS m FROM relations").get().m;
+    let nextRelOrd = maxRelOrd + 1;
+    const upsertRel = db.prepare("INSERT OR REPLACE INTO relations(prop, ord, predicate, count) VALUES (?, ?, ?, ?)");
+    const edgesForProp = db.prepare("SELECT subject, object, subject_label, object_label, extra FROM edges WHERE prop = ?");
+    const upsertEdge = db.prepare("INSERT OR REPLACE INTO edges(prop, subject, object, subject_label, object_label, extra) VALUES (?, ?, ?, ?, ?, ?)");
+    const deleteEdge = db.prepare("DELETE FROM edges WHERE prop = ? AND subject = ? AND object = ?");
+    const seenProps = new Set();
+    for (const group of payload.objectProperties || []) {
+      seenProps.add(group.prop);
+      const existingRows = edgesForProp.all(group.prop);
+      const existingByKey = new Map(existingRows.map((r) => [`${r.subject}\u0000${r.object}`, r]));
+      const newKeys = new Set();
+      const cacheGroup = cache ? cacheGroupFor(cache, group.prop) : null;
+      for (const e of group.examples || []) {
+        const key = `${e.subject}\u0000${e.object}`;
+        newKeys.add(key);
+        const extraKeys = Object.keys(e).filter((k) => !STD_EDGE_KEYS.has(k));
+        const extra = extraKeys.length ? JSON.stringify(Object.fromEntries(extraKeys.map((k) => [k, e[k]]))) : null;
+        const existing = existingByKey.get(key);
+        const unchanged = existing
+          && (existing.subject_label ?? null) === (e.subjectLabel ?? null)
+          && (existing.object_label ?? null) === (e.objectLabel ?? null)
+          && (existing.extra ?? null) === (extra ?? null);
+        if (unchanged) continue;
+        upsertEdge.run(group.prop, e.subject, e.object, e.subjectLabel ?? null, e.objectLabel ?? null, extra);
+        if (cacheGroup) cacheUpsertEdge(cacheGroup, e, extraKeys);
+      }
+      for (const key of existingByKey.keys()) {
+        if (newKeys.has(key)) continue;
+        const [s, o] = key.split("\u0000");
+        deleteEdge.run(group.prop, s, o);
+      }
+      if (cacheGroup) cacheDropEdgesExcept(cacheGroup, newKeys);
+      const relCount = Number.isFinite(group.count) ? group.count : (group.examples || []).length;
+      const relOrd = getRelOrd.get(group.prop)?.ord ?? nextRelOrd++;
+      upsertRel.run(group.prop, relOrd, group.predicate ?? null, relCount);
+      if (cacheGroup) { cacheGroup.predicate = group.predicate ?? null; cacheGroup.count = relCount; }
+    }
+    for (const row of db.prepare("SELECT prop FROM relations").all()) {
+      if (seenProps.has(row.prop)) continue;
+      db.prepare("DELETE FROM edges WHERE prop = ?").run(row.prop);
+      db.prepare("DELETE FROM relations WHERE prop = ?").run(row.prop);
+    }
+    if (cache) cacheDropGroupsExcept(cache, seenProps);
+
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    // The cache may hold a partially-applied patch at this point (some of the
+    // loop bodies above already mutated it before the failure) that was never
+    // actually committed to SQLite — never trust it silently. Drop it so the
+    // next loadMemory() call does an honest full rebuild instead.
+    handle.cachedPayload = undefined;
+    throw e;
+  }
+}
+
 /** Atomic write of raw text (temp in the same dir + rename) — the discipline
  *  every writer in this module (and fold.mjs/sessions.mjs's own copies) uses:
  *  a crash never destroys the previous file, a concurrent reader never sees a
@@ -209,6 +634,9 @@ const resolveManifestFile = (dir) => join(dir, MEMORY_MANIFEST_REL);
  *  the snapshot just written (or null if skipped); `prunedVersion` is the
  *  number pruned, or null if nothing was in range to prune yet. */
 export async function snapshotMemory(dir, { retentionVersions } = {}) {
+  if (isMemoryOrSqliteHandle(dir)) {
+    throw new Error("snapshotMemory only supports the flat-JSON backend (Backend A) — a memory/sqlite handle has no on-disk graph.json to snapshot");
+  }
   const graphFile = resolveMemoryGraphFile(dir);
   let graphText;
   try {
@@ -251,10 +679,14 @@ export async function snapshotMemory(dir, { retentionVersions } = {}) {
   return { skipped: false, version: v, prunedVersion };
 }
 
-/** Load the memory graph for a repo dir. A missing store is the bootstrap:
- *  return the empty payload (uncached — the first append creates the file).
- *  The result is a raw entities payload; parseEntities() loads it. */
+/** Load the memory graph for a repo dir OR a Backend B/C handle (see the
+ *  storage-backend seam above `createInMemoryStore`). A missing Backend-A
+ *  store is the bootstrap: return the empty payload (uncached — the first
+ *  append creates the file). The result is a raw entities payload;
+ *  parseEntities() loads it. */
 export async function loadMemory(dir) {
+  if (isMemoryHandle(dir)) return dir.payload;
+  if (isSqliteHandle(dir)) return readSqlitePayload(dir);
   let text;
   try {
     text = await readFile(memoryGraphFile(dir), "utf8");
@@ -265,6 +697,19 @@ export async function loadMemory(dir) {
   return JSON.parse(text);
 }
 
+/** Persist a mutated payload back to `dir` — the seam's other half. Backend A
+ *  (unchanged): atomic write of the whole file. Backend B: the payload IS the
+ *  handle's live object already (every real caller mutates in place); this
+ *  assignment is a documented no-op safety net, never I/O. Backend C: a real,
+ *  diffed per-row INSERT/UPDATE/DELETE against the live connection — see
+ *  persistSqlitePayload. */
+async function persistMemory(dir, payload) {
+  if (isMemoryHandle(dir)) { dir.payload = payload; return; }
+  if (isSqliteHandle(dir)) { persistSqlitePayload(dir, payload); return; }
+  await mkdir(dirname(memoryGraphFile(dir)), { recursive: true });
+  await atomicWriteJson(memoryGraphFile(dir), payload);
+}
+
 /** Fresh read → mutate → atomic write. Serialized per call; every public append
  *  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
@@ -286,8 +731,7 @@ async function mutateMemory(dir, fn) {
   migrateLegacyProvenance(out);
   recomputeSourceReliability(out);
   out.proseIndex = buildProseIndex(out.individuals);
-  await mkdir(dirname(memoryGraphFile(dir)), { recursive: true });
-  await atomicWriteJson(memoryGraphFile(dir), out);
+  await persistMemory(dir, out);
   return out;
 }
 
@@ -425,7 +869,9 @@ function statedByObjectsFor(payload, factId) {
  *  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). */
+ *  (PLAN_INFERENCE_TESTING.md §4 stage 2's exit criterion). Also stamps
+ *  `mgx:updatedAt` (PLAN_VIZ.md §2) — this mutates the Fact's own attributes in place without
+ *  necessarily touching an edge, so the derived "max over edges" updatedAt rule can't see it. */
 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 || "";
@@ -436,6 +882,7 @@ function recomputeFactTrust(payload, fact, nowMs = Date.now(), trustOpts = {}) {
   });
   setAttr(fact, TRUST_SCORE_PROP, "trustScore", String(score));
   setAttr(fact, TRUST_INPUTS_PROP, "trustInputs", JSON.stringify(inputs));
+  setAttr(fact, UPDATED_AT_PROP, "updatedAt", new Date(nowMs).toISOString());
 }
 
 /** Reconcile a Fact's Sources + statedBy edges with its (unchanged, compat)
@@ -540,6 +987,8 @@ function recomputeSourceReliability(payload) {
     const source = payload.individuals.find((i) => i?.id === sid);
     if (!source) continue;
     setAttr(source, SOURCE_RELIABILITY_PROP, "sourceReliability", String(sessionReliabilityFrom(counts)));
+    // Own-attribute mutation in place (PLAN_VIZ.md §2) — same reasoning as recomputeFactTrust.
+    setAttr(source, UPDATED_AT_PROP, "updatedAt", new Date().toISOString());
   }
 
   // Re-materialise trust for EVERY individual statedBy a recomputed session
@@ -560,17 +1009,26 @@ function upsertIndividual(payload, ind) {
   else payload.individuals.push(ind);
 }
 
-/** Upsert one edge into the named relation group (dedupe by subject>object). */
+/** Upsert one edge into the named relation group (dedupe by subject>object). Stamps `createdAt`
+ *  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. */
 function upsertEdge(payload, { predicate, prop }, edge) {
   let group = payload.objectProperties.find((g) => g?.prop === prop);
   if (!group) {
     group = { predicate, prop, count: 0, examples: [] };
     payload.objectProperties.push(group);
   }
+  // Edges are flat ({subject, object, ...}), not attribute-bearing individuals, so this can't
+  // reuse firstWriteCreatedAt (which reads `.attributes`) directly — same discipline, edge shape:
+  // the prior edge's OWN createdAt wins if it has one, else the incoming candidate, else now.
+  const prior = (group.examples || []).find((e) => e?.subject === edge.subject && e?.object === edge.object);
+  const createdAt = prior?.createdAt || edge.createdAt || nowIso();
   group.examples = (group.examples || []).filter(
     (e) => !(e?.subject === edge.subject && e?.object === edge.object),
   );
-  group.examples.push(edge);
+  group.examples.push({ ...edge, createdAt });
   group.count = group.examples.length;
 }
 

package/src/router/goal-reasoner.mjs

@@ -197,13 +197,20 @@ export function threatsAmong(candidateName, _pending) {
 }
 
 /** Resolve the FOCUS the request scopes the goal model to — an entity binding
- *  (extractEntity + the graph oracle), NOT an intent keyword. Returns the bound
- *  individual or null (no bindable focus => a whole-graph / global goal). */
+ *  (extractEntity + the graph oracle), NOT an intent keyword. Returns
+ *  `{match, ambiguous, candidates}`: `match` is the bound individual or null (no
+ *  bindable focus => a whole-graph / global goal); `ambiguous`+`candidates` let
+ *  the caller distinguish "genuinely no focus" from "a focus term that TIED"
+ *  (PLAN_BREADTH_FIRST_NLU.md §4 — the latter must never silently fall back to
+ *  a global answer, since that would silently answer a DIFFERENT goal than the
+ *  one the user actually named). */
 function focusOf(request, ctx) {
   const term = extractEntity(String(request || ""));
-  if (!term || !ctx || !ctx.resolve) return null;
+  if (!term || !ctx || !ctx.resolve) return { match: null, ambiguous: false, candidates: [] };
   const r = ctx.resolve(term);
-  return r && r.match && !r.ambiguous ? r.match : null;
+  if (r && r.match && !r.ambiguous) return { match: r.match, ambiguous: false, candidates: [] };
+  if (r && r.ambiguous) return { match: null, ambiguous: true, candidates: [r.match, ...(r.candidates || [])].filter(Boolean) };
+  return { match: null, ambiguous: false, candidates: [] };
 }
 
 /** The GLOBAL-MODE DOMAIN GATE's primitive: what entity CLASS (if any) did
@@ -268,14 +275,41 @@ export function dropCondition(intention, observed, mode, focus, focusClass) {
  *  omits it). PLAN_CODE.md Track 1's synthesis oracle (synthbench/rules/
  *  oracle.mjs) is the one caller that overrides it, with a CLONED array
  *  holding a candidate rule — the candidate then runs through this exact same
- *  meta-loop a hand-written rule does, never a parallel re-implementation. */
-export async function goalReason(request, tools, ctx, { driver = "goal-0.8.1", ruleSet = GOAL_RULES } = {}) {
+ *  meta-loop a hand-written rule does, never a parallel re-implementation.
+ *
+ *  `pinnedFocus` (internal — PLAN_BREADTH_FIRST_NLU.md §4's breadth-first
+ *  ambiguity fix) skips `focusOf` entirely and scopes straight to the given
+ *  individual: the mechanism the ambiguous-focus branch below uses to run this
+ *  SAME meta-loop once per tied candidate, "pin, don't re-resolve" (the same
+ *  idiom PLAN_BREADTH_FIRST_NLU.md §1 uses for ask.mjs's entity ties). No
+ *  product call site ever passes it. */
+export async function goalReason(request, tools, ctx, { driver = "goal-0.8.1", ruleSet = GOAL_RULES, pinnedFocus = null } = {}) {
   const declared = Array.isArray(tools) ? tools : [];
 
   // STEP 1 — deduce the goal scope from the DECLARED model + a bound focus,
   // then SELECT the goal-rule by pure applicability (no request keyword ever):
   // a bound focus reads scoped, no focus reads global (keystone arbitration).
-  const focus = focusOf(request, ctx);
+  const focusRes = pinnedFocus ? { match: pinnedFocus, ambiguous: false, candidates: [] } : focusOf(request, ctx);
+  const focus = focusRes.match;
+
+  // An AMBIGUOUS focus term must never silently collapse to "global" — that
+  // would silently answer a DIFFERENT goal (whole-graph keystone arbitration)
+  // than the one the user actually named. Refuse honestly, the same "never a
+  // guess" discipline resolver.mjs/guardrail.mjs apply to an ambiguous resolved
+  // term — and, when the tied candidates share ONE class a declared goal-rule
+  // scopes and a dispatcher is wired, ADDITIONALLY run this SAME meta-loop once
+  // per (pinned) candidate, so a machine caller gets both the honest "still
+  // ambiguous" signal and every candidate's real composed answer.
+  if (!pinnedFocus && focusRes.ambiguous) {
+    const term = extractEntity(String(request || ""));
+    const pool = focusRes.candidates.slice(0, 4);
+    const why2 = `open-world: focus "${term}" is ambiguous (${pool.map((c) => c.label).join(", ")}) — narrow it`;
+    const scopable = pool.length > 0 && pool.every((c) => c.class === pool[0].class) && ruleSet.some((r) => r.focusClass === pool[0].class);
+    if (!scopable || !ctx.dispatch) return refuse(why2, driver);
+    const candidateResults = [];
+    for (const c of pool) candidateResults.push({ candidate: c.label, result: await goalReason(request, tools, ctx, { driver, ruleSet, pinnedFocus: c }) });
+    return { ...refuse(why2, driver), candidateResults };
+  }
   const mode = focus ? "scoped" : "global";
 
   // The open-world goal-generation seam, named honestly: a resolved focus whose