@remnic/plugin-openclaw 1.0.7 → 1.0.8

package/dist/{chunk-KPMXWORS.js → chunk-JJSNPSCD.js}

@@ -1,12 +1,15 @@
+import {
+  createVersion
+} from "./chunk-6OJAU466.js";
 import {
   log
 } from "./chunk-UFU5GGGA.js";
 
 // ../remnic-core/src/storage.ts
-import { access as access2, readdir, readFile as readFile3, stat as stat2, writeFile as writeFile3, mkdir as mkdir3, unlink as unlink2, rename, appendFile } from "fs/promises";
+import { access, readdir, readFile as readFile2, stat as stat2, writeFile as writeFile2, mkdir as mkdir2, unlink, rename, appendFile } from "fs/promises";
 import { appendFileSync, mkdirSync, statSync } from "fs";
-import { createHash as createHash2 } from "crypto";
-import path5 from "path";
+import { createHash } from "crypto";
+import path4 from "path";
 
 // ../remnic-core/src/memory-cache.ts
 var entityCacheByDir = /* @__PURE__ */ new Map();
@@ -173,128 +176,24 @@ function sanitizeMemoryContent(text) {
   };
 }
 
-// ../remnic-core/src/page-versioning.ts
-import { createHash } from "crypto";
-import path2 from "path";
-import {
-  access,
-  mkdir as mkdir2,
-  readFile as readFile2,
-  writeFile as writeFile2,
-  unlink
-} from "fs/promises";
-var NOOP_LOGGER = {
-  debug: () => {
-  },
-  warn: () => {
-  }
-};
-var writeLocks = /* @__PURE__ */ new Map();
-function withPageLock(pageKey, fn) {
-  const prev = writeLocks.get(pageKey) ?? Promise.resolve();
-  const next = prev.then(fn, fn);
-  writeLocks.set(pageKey, next.then(() => {
-  }, () => {
-  }));
-  return next;
-}
-function contentHash(content) {
-  return createHash("sha256").update(content, "utf-8").digest("hex");
-}
-function sidecarKey(pagePath) {
-  const withoutExt = pagePath.replace(/\.md$/i, "");
-  return withoutExt.replace(/[\\/]/g, "__");
-}
-function sidecarDir(memoryDir, sidecar, pagePath) {
-  return path2.join(memoryDir, sidecar, sidecarKey(pagePath));
-}
-function manifestPath(memoryDir, sidecar, pagePath) {
-  return path2.join(sidecarDir(memoryDir, sidecar, pagePath), "manifest.json");
-}
-async function readManifest(memoryDir, sidecar, pagePath) {
-  const mp = manifestPath(memoryDir, sidecar, pagePath);
-  try {
-    const raw = await readFile2(mp, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null) {
-      return { pagePath, versions: [], currentVersion: "0" };
-    }
-    const obj = parsed;
-    const versions = Array.isArray(obj.versions) ? obj.versions : [];
-    const currentVersion = typeof obj.currentVersion === "string" ? obj.currentVersion : "0";
-    return { pagePath: typeof obj.pagePath === "string" ? obj.pagePath : pagePath, versions, currentVersion };
-  } catch {
-    return { pagePath, versions: [], currentVersion: "0" };
-  }
-}
-async function writeManifest(memoryDir, sidecar, pagePath, history) {
-  const dir = sidecarDir(memoryDir, sidecar, pagePath);
-  await mkdir2(dir, { recursive: true });
-  const mp = manifestPath(memoryDir, sidecar, pagePath);
-  await writeFile2(mp, JSON.stringify(history, null, 2) + "\n", "utf-8");
-}
-async function createVersion(pagePath, content, trigger, config, log2 = NOOP_LOGGER, note, memoryDir) {
-  const { sidecarDir: sidecar, maxVersionsPerPage } = config;
-  const resolvedMemoryDir = memoryDir ?? resolveMemoryDir(pagePath);
-  const mPath = manifestPath(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));
-  return withPageLock(mPath, async () => {
-    const history = await readManifest(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));
-    const nextId = String(history.versions.length > 0 ? Math.max(...history.versions.map((v) => Number(v.versionId))) + 1 : 1);
-    const hash = contentHash(content);
-    const version = {
-      versionId: nextId,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      contentHash: hash,
-      sizeBytes: Buffer.byteLength(content, "utf-8"),
-      trigger,
-      ...note !== void 0 ? { note } : {}
-    };
-    const dir = sidecarDir(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir));
-    await mkdir2(dir, { recursive: true });
-    const ext = path2.extname(pagePath) || ".md";
-    const snapshotPath = path2.join(dir, `${nextId}${ext}`);
-    await writeFile2(snapshotPath, content, "utf-8");
-    history.versions.push(version);
-    history.currentVersion = nextId;
-    if (maxVersionsPerPage > 0 && history.versions.length > maxVersionsPerPage) {
-      const toRemove = history.versions.splice(0, history.versions.length - maxVersionsPerPage);
-      for (const old of toRemove) {
-        const oldPath = path2.join(dir, `${old.versionId}${ext}`);
-        try {
-          await unlink(oldPath);
-        } catch {
-          log2.debug(`page-versioning: could not remove old snapshot ${oldPath}`);
-        }
-      }
-    }
-    await writeManifest(resolvedMemoryDir, sidecar, relPath(pagePath, resolvedMemoryDir), history);
-    log2.debug(`page-versioning: created version ${nextId} for ${pagePath} (trigger=${trigger})`);
-    return version;
-  });
-}
-function resolveMemoryDir(pagePath) {
-  const knownSubdirs = /* @__PURE__ */ new Set([
-    "facts",
-    "corrections",
-    "entities",
-    "state",
-    "artifacts",
-    "questions",
-    "profiles"
-  ]);
-  let dir = path2.dirname(pagePath);
-  for (let depth = 0; depth < 5; depth++) {
-    const base = path2.basename(dir);
-    if (knownSubdirs.has(base) || /^\d{4}-\d{2}-\d{2}$/.test(base)) {
-      dir = path2.dirname(dir);
-    } else {
-      break;
-    }
-  }
-  return dir;
-}
-function relPath(pagePath, memoryDir) {
-  return path2.relative(memoryDir, pagePath);
+// ../remnic-core/src/consolidation-operator.ts
+var CONSOLIDATION_OPERATORS = [
+  "split",
+  "merge",
+  "update"
+];
+var DERIVED_FROM_ENTRY_RE = /^(.+):(\d+)$/;
+function isValidDerivedFromEntry(entry) {
+  if (typeof entry !== "string") return false;
+  const match = entry.match(DERIVED_FROM_ENTRY_RE);
+  if (!match) return false;
+  const pathPart = match[1];
+  if (pathPart.length === 0 || pathPart.trim().length === 0) return false;
+  const versionNum = Number(match[2]);
+  return Number.isInteger(versionNum) && versionNum >= 0;
+}
+function isConsolidationOperator(value) {
+  return typeof value === "string" && CONSOLIDATION_OPERATORS.includes(value);
 }
 
 // ../remnic-core/src/entity-schema.ts
@@ -651,7 +550,7 @@ function confidenceTier(score) {
 var SPECULATIVE_TTL_DAYS = 30;
 
 // ../remnic-core/src/memory-projection-store.ts
-import path3 from "path";
+import path2 from "path";
 import { readFileSync } from "fs";
 
 // ../remnic-core/src/runtime/better-sqlite.ts
@@ -684,7 +583,7 @@ function openBetterSqlite3(file, options) {
 // ../remnic-core/src/memory-projection-store.ts
 var MEMORY_PROJECTION_SCHEMA_VERSION = 2;
 function getMemoryProjectionPath(memoryDir) {
-  return path3.join(memoryDir, "state", "memory-projection.sqlite");
+  return path2.join(memoryDir, "state", "memory-projection.sqlite");
 }
 function listTableColumns(db, tableName) {
   try {
@@ -916,7 +815,7 @@ function parseCurrentRow(memoryDir, row) {
     category: row.category,
     status: row.status,
     lifecycleState: typeof row.lifecycle_state === "string" ? row.lifecycle_state : void 0,
-    path: path3.join(memoryDir, row.path_rel),
+    path: path2.join(memoryDir, row.path_rel),
     pathRel: row.path_rel,
     created: row.created_at,
     updated: row.updated_at,
@@ -1077,7 +976,7 @@ function readProjectedMemoryBrowse(memoryDir, options) {
           return true;
         }
         try {
-          const filePath = path3.join(memoryDir, row.path_rel);
+          const filePath = path2.join(memoryDir, row.path_rel);
           const content = readFileSync(filePath, "utf-8").toLowerCase();
           return content.includes(normalizedQuery);
         } catch {
@@ -1091,7 +990,7 @@ function readProjectedMemoryBrowse(memoryDir, options) {
           (row) => typeof row.memory_id === "string" && typeof row.path_rel === "string" && typeof row.category === "string" && typeof row.status === "string"
         ).map((row) => ({
           id: row.memory_id,
-          path: path3.join(memoryDir, row.path_rel),
+          path: path2.join(memoryDir, row.path_rel),
           category: row.category,
           status: row.status,
           created: typeof row.created_at === "string" ? row.created_at : void 0,
@@ -1125,7 +1024,7 @@ function readProjectedMemoryBrowse(memoryDir, options) {
         (row) => typeof row.memory_id === "string" && typeof row.path_rel === "string" && typeof row.category === "string" && typeof row.status === "string"
       ).map((row) => ({
         id: row.memory_id,
-        path: path3.join(memoryDir, row.path_rel),
+        path: path2.join(memoryDir, row.path_rel),
         category: row.category,
         status: row.status,
         created: typeof row.created_at === "string" ? row.created_at : void 0,
@@ -1341,7 +1240,7 @@ function readProjectedGovernanceRecord(memoryDir) {
 }
 
 // ../remnic-core/src/memory-lifecycle-ledger-utils.ts
-import path4 from "path";
+import path3 from "path";
 var MEMORY_LIFECYCLE_RULE_VERSION = "memory-lifecycle-ledger.v1";
 var MEMORY_LIFECYCLE_EVENT_SORT_ORDER = {
   created: 0,
@@ -1357,8 +1256,8 @@ var MEMORY_LIFECYCLE_EVENT_SORT_ORDER = {
   archived: 10
 };
 function toMemoryPathRel(baseDir, filePath) {
-  if (!baseDir) return filePath.split(path4.sep).join("/");
-  return path4.relative(baseDir, filePath).split(path4.sep).join("/");
+  if (!baseDir) return filePath.split(path3.sep).join("/");
+  return path3.relative(baseDir, filePath).split(path3.sep).join("/");
 }
 function isArchivedMemoryPath(pathRel) {
   return pathRel === "archive" || pathRel.startsWith("archive/");
@@ -1722,6 +1621,17 @@ var ARTIFACT_SEARCH_STOPWORDS = /* @__PURE__ */ new Set([
 function tokenizeArtifactSearchText(input) {
   return input.toLowerCase().split(/[^a-z0-9]+/i).map((t) => t.trim()).filter((t) => t.length >= 2).filter((t) => !ARTIFACT_SEARCH_STOPWORDS.has(t));
 }
+function assertMemoryWorthCounter(field, value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${field} must be a finite number, got ${String(value)}`);
+  }
+  if (!Number.isInteger(value)) {
+    throw new Error(`${field} must be an integer, got ${value}`);
+  }
+  if (value < 0) {
+    throw new Error(`${field} must be >= 0, got ${value}`);
+  }
+}
 function serializeFrontmatter(fm) {
   const lines = [
     "---",
@@ -1754,6 +1664,14 @@ function serializeFrontmatter(fm) {
     lines.push(`accessCount: ${fm.accessCount}`);
   }
   if (fm.lastAccessed) lines.push(`lastAccessed: ${fm.lastAccessed}`);
+  if (fm.mw_success !== void 0) {
+    assertMemoryWorthCounter("mw_success", fm.mw_success);
+    lines.push(`mw_success: ${fm.mw_success}`);
+  }
+  if (fm.mw_fail !== void 0) {
+    assertMemoryWorthCounter("mw_fail", fm.mw_fail);
+    lines.push(`mw_fail: ${fm.mw_fail}`);
+  }
   if (fm.importance) {
     lines.push(`importanceScore: ${fm.importance.score}`);
     lines.push(`importanceLevel: ${fm.importance.level}`);
@@ -1791,6 +1709,33 @@ function serializeFrontmatter(fm) {
     lines.push(`structuredAttributes: ${JSON.stringify(fm.structuredAttributes)}`);
   }
   if (fm.contentHash) lines.push(`contentHash: ${fm.contentHash}`);
+  if (fm.derived_from !== void 0) {
+    if (!Array.isArray(fm.derived_from)) {
+      throw new Error(
+        `serializeFrontmatter: derived_from must be an array of "<path>:<version>" strings`
+      );
+    }
+    for (const entry of fm.derived_from) {
+      if (!isValidDerivedFromEntry(entry)) {
+        throw new Error(
+          `serializeFrontmatter: invalid derived_from entry ${JSON.stringify(entry)} \u2014 expected "<path>:<version>" with version >= 0`
+        );
+      }
+    }
+    if (fm.derived_from.length > 0) {
+      lines.push(
+        `derived_from: [${fm.derived_from.map((e) => `"${e.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`).join(", ")}]`
+      );
+    }
+  }
+  if (fm.derived_via !== void 0) {
+    if (!isConsolidationOperator(fm.derived_via)) {
+      throw new Error(
+        `serializeFrontmatter: invalid derived_via ${JSON.stringify(fm.derived_via)} \u2014 expected one of "split" | "merge" | "update"`
+      );
+    }
+    lines.push(`derived_via: ${fm.derived_via}`);
+  }
   lines.push("---");
   return lines.join("\n");
 }
@@ -1823,13 +1768,54 @@ function parseLinkReasonValue(rawValue) {
     return legacyValue;
   }
 }
+function parseMemoryWorthCounterField(raw) {
+  if (raw === void 0) return void 0;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return void 0;
+  const n = Number(trimmed);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) return void 0;
+  return n;
+}
 function parseFrontmatter2(raw) {
   const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
   if (!match) return null;
   const fmBlock = match[1];
   const content = match[2].trim();
   const fm = {};
-  for (const line of fmBlock.split("\n")) {
+  const rawLines = fmBlock.split("\n");
+  const lines = [];
+  let i = 0;
+  while (i < rawLines.length) {
+    const line = rawLines[i];
+    const colonIdx = line.indexOf(":");
+    if (colonIdx !== -1 && line.slice(colonIdx + 1).trim() === "") {
+      const baseIndent = line.match(/^\s*/)[0].length;
+      const items = [];
+      let j = i + 1;
+      while (j < rawLines.length) {
+        const next = rawLines[j];
+        const m = next.match(/^(\s+)- (.*)$/);
+        if (!m || m[1].length <= baseIndent) break;
+        let item = m[2].trim();
+        if (item.startsWith('"') && item.endsWith('"') && item.length >= 2) {
+          item = item.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+        } else if (item.startsWith("'") && item.endsWith("'") && item.length >= 2) {
+          item = item.slice(1, -1).replace(/''/g, "'");
+        }
+        items.push(item);
+        j++;
+      }
+      if (items.length > 0) {
+        const inline = items.map((v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`).join(", ");
+        lines.push(`${line.slice(0, colonIdx + 1)} [${inline}]`);
+        i = j;
+        continue;
+      }
+    }
+    lines.push(line);
+    i++;
+  }
+  for (const line of lines) {
     const colonIdx = line.indexOf(":");
     if (colonIdx === -1) continue;
     const key = line.slice(0, colonIdx).trim();
@@ -1855,9 +1841,84 @@ function parseFrontmatter2(raw) {
   if (lineageMatch) {
     lineage = lineageMatch[1].split(",").map((l) => l.trim().replace(/^"|"$/g, "")).filter(Boolean);
   }
+  let derived_from;
+  const derivedFromStr = (fm.derived_from ?? "").trim();
+  if (derivedFromStr.startsWith("[") && derivedFromStr.endsWith("]")) {
+    const inner = derivedFromStr.slice(1, -1);
+    const entries = [];
+    let i2 = 0;
+    while (i2 < inner.length) {
+      const ch = inner[i2];
+      if (ch === '"') {
+        let buf = "";
+        i2++;
+        while (i2 < inner.length) {
+          const c = inner[i2];
+          if (c === "\\" && i2 + 1 < inner.length) {
+            const next = inner[i2 + 1];
+            if (next === '"') {
+              buf += '"';
+              i2 += 2;
+              continue;
+            }
+            if (next === "\\") {
+              buf += "\\";
+              i2 += 2;
+              continue;
+            }
+            buf += c;
+            i2++;
+            continue;
+          }
+          if (c === '"') {
+            i2++;
+            break;
+          }
+          buf += c;
+          i2++;
+        }
+        if (buf.length > 0) entries.push(buf);
+      } else if (ch === "'") {
+        let buf = "";
+        i2++;
+        while (i2 < inner.length) {
+          const c = inner[i2];
+          if (c === "'") {
+            if (i2 + 1 < inner.length && inner[i2 + 1] === "'") {
+              buf += "'";
+              i2 += 2;
+              continue;
+            }
+            i2++;
+            break;
+          }
+          buf += c;
+          i2++;
+        }
+        if (buf.length > 0) entries.push(buf);
+      } else if (ch === "," || /\s/.test(ch)) {
+        i2++;
+      } else {
+        let buf = "";
+        while (i2 < inner.length) {
+          const c = inner[i2];
+          if (c === "," || /\s/.test(c)) break;
+          buf += c;
+          i2++;
+        }
+        if (buf.length > 0) entries.push(buf);
+      }
+    }
+    if (entries.length > 0) derived_from = entries;
+  }
+  const derivedViaRaw = (fm.derived_via ?? "").trim();
+  const derivedViaUnquoted = derivedViaRaw.startsWith('"') && derivedViaRaw.endsWith('"') || derivedViaRaw.startsWith("'") && derivedViaRaw.endsWith("'") ? derivedViaRaw.slice(1, -1) : derivedViaRaw;
+  const derived_via = isConsolidationOperator(derivedViaUnquoted) ? derivedViaUnquoted : void 0;
   const accessCount = fm.accessCount ? parseInt(fm.accessCount, 10) : void 0;
   const decayScore = fm.decayScore !== void 0 ? parseFloat(fm.decayScore) : void 0;
   const heatScore = fm.heatScore !== void 0 ? parseFloat(fm.heatScore) : void 0;
+  const mw_success = parseMemoryWorthCounterField(fm.mw_success);
+  const mw_fail = parseMemoryWorthCounterField(fm.mw_fail);
   let importance;
   if (fm.importanceScore) {
     const score = parseFloat(fm.importanceScore);
@@ -1909,6 +1970,9 @@ function parseFrontmatter2(raw) {
       // Access tracking
       accessCount: accessCount && accessCount > 0 ? accessCount : void 0,
       lastAccessed: fm.lastAccessed || void 0,
+      // Memory Worth counters (issue #560)
+      mw_success,
+      mw_fail,
       // Importance scoring
       importance,
       // Chunking
@@ -1927,7 +1991,11 @@ function parseFrontmatter2(raw) {
       // Structured attributes (JSON on a single line)
       structuredAttributes: parseStructuredAttributes(fm.structuredAttributes),
       // Raw-content dedup hash (format-agnostic archive/consolidation cleanup)
-      contentHash: fm.contentHash || void 0
+      contentHash: fm.contentHash || void 0,
+      // Consolidation provenance (issue #561) — read-through only in this
+      // PR; no code produces these fields yet.
+      derived_from,
+      derived_via
     },
     content
   };
@@ -1964,17 +2032,17 @@ var KNOWN_ENTITY_FILENAME_PREFIXES = /* @__PURE__ */ new Set([
   "topic"
 ]);
 function inferEntityTypeFromFilename(pathRel) {
-  const basename = path5.basename(pathRel, ".md").toLowerCase();
+  const basename = path4.basename(pathRel, ".md").toLowerCase();
   const separator = basename.indexOf("-");
   if (separator <= 0) return void 0;
   const candidate = basename.slice(0, separator);
   return KNOWN_ENTITY_FILENAME_PREFIXES.has(candidate) ? candidate : void 0;
 }
 function normalizeFrontmatterForPath(frontmatter, pathRel, content = "") {
-  const normalizedPath = pathRel.split(path5.sep).join("/");
+  const normalizedPath = pathRel.split(path4.sep).join("/");
   let normalizedFrontmatter = frontmatter;
   if (normalizedPath === "entities" || normalizedPath.startsWith("entities/") || normalizedPath.includes("/entities/")) {
-    const basename = path5.basename(pathRel, ".md");
+    const basename = path4.basename(pathRel, ".md");
     const inferredType = inferEntityTypeFromContent(content) || inferEntityTypeFromFilename(pathRel) || "entity";
     const existingTags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
     normalizedFrontmatter = {
@@ -2039,12 +2107,12 @@ var ContentHashIndex = class _ContentHashIndex {
   dirty = false;
   filePath;
   constructor(stateDir) {
-    this.filePath = path5.join(stateDir, "fact-hashes.txt");
+    this.filePath = path4.join(stateDir, "fact-hashes.txt");
   }
   /** Load existing hashes from disk. Safe to call multiple times. */
   async load() {
     try {
-      const raw = await readFile3(this.filePath, "utf-8");
+      const raw = await readFile2(this.filePath, "utf-8");
       for (const line of raw.split("\n")) {
         const trimmed = line.trim();
         if (trimmed.length > 0) {
@@ -2074,8 +2142,8 @@ var ContentHashIndex = class _ContentHashIndex {
   /** Persist index to disk if changed. */
   async save() {
     if (!this.dirty) return;
-    await mkdir3(path5.dirname(this.filePath), { recursive: true });
-    await writeFile3(this.filePath, [...this.hashes].join("\n") + "\n", "utf-8");
+    await mkdir2(path4.dirname(this.filePath), { recursive: true });
+    await writeFile2(this.filePath, [...this.hashes].join("\n") + "\n", "utf-8");
     this.dirty = false;
     log.debug(`content-hash index: saved ${this.hashes.size} hashes`);
   }
@@ -2120,7 +2188,7 @@ var ContentHashIndex = class _ContentHashIndex {
   /** Normalize content and compute SHA-256 hash. */
   static computeHash(content) {
     const normalized = _ContentHashIndex.normalizeContent(content);
-    return createHash2("sha256").update(normalized).digest("hex");
+    return createHash("sha256").update(normalized).digest("hex");
   }
 };
 function normalizeAttributePairs(pairs) {
@@ -2611,7 +2679,7 @@ function fingerprintEntityStructuredFacts(entity) {
     facts: normalizeStructuredSectionFacts(section.facts).slice().sort((left, right) => left.localeCompare(right))
   })).filter((section) => section.facts.length > 0).sort((left, right) => left.key.localeCompare(right.key) || left.title.localeCompare(right.title) || left.facts.join("\n").localeCompare(right.facts.join("\n")));
   if (normalizedSections.length === 0) return void 0;
-  return createHash2("sha256").update(JSON.stringify(normalizedSections)).digest("hex");
+  return createHash("sha256").update(JSON.stringify(normalizedSections)).digest("hex");
 }
 function isEntitySynthesisStale(entity) {
   const structuredFactCount = countEntityStructuredFacts(entity);
@@ -2902,6 +2970,27 @@ function buildEntitySchemaCacheKey(entitySchemas) {
   ]);
   return JSON.stringify(normalized);
 }
+function isValidBufferSurpriseEvent(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const v = value;
+  if (v.event !== "BUFFER_SURPRISE") return false;
+  if (typeof v.timestamp !== "string" || v.timestamp.length === 0) return false;
+  if (!Number.isFinite(Date.parse(v.timestamp))) return false;
+  if (typeof v.bufferKey !== "string" || v.bufferKey.length === 0) return false;
+  if (v.sessionKey !== null && typeof v.sessionKey !== "string") return false;
+  if (v.turnRole !== "user" && v.turnRole !== "assistant") return false;
+  if (typeof v.surpriseScore !== "number" || !Number.isFinite(v.surpriseScore)) {
+    return false;
+  }
+  if (v.surpriseScore < 0 || v.surpriseScore > 1) return false;
+  if (typeof v.threshold !== "number" || !Number.isFinite(v.threshold)) return false;
+  if (v.threshold < 0 || v.threshold > 1) return false;
+  if (typeof v.triggeredFlush !== "boolean") return false;
+  if (typeof v.turnCountInWindow !== "number" || !Number.isFinite(v.turnCountInWindow)) {
+    return false;
+  }
+  return true;
+}
 var StorageManager = class _StorageManager {
   constructor(baseDir, entitySchemas) {
     this.baseDir = baseDir;
@@ -2979,24 +3068,65 @@ var StorageManager = class _StorageManager {
   async snapshotBeforeWrite(filePath, trigger) {
     if (!this._versioningConfig || !this._versioningConfig.enabled) return;
     try {
-      const existing = await readFile3(filePath, "utf-8");
+      const existing = await readFile2(filePath, "utf-8");
       await createVersion(filePath, existing, trigger, this._versioningConfig, log, void 0, this.baseDir);
     } catch {
     }
   }
+  /**
+   * Consolidation provenance helper (issue #561 PR 2).
+   *
+   * Captures the current on-disk content of a source memory as a
+   * page-version snapshot so the downstream consolidated write can record a
+   * `derived_from` pointer that actually resolves.  Returns the
+   * `"<relative-path>:<versionId>"` entry expected by the `derived_from`
+   * frontmatter field.
+   *
+   * Returns `null` when versioning is disabled (snapshots would not be
+   * created), when the file does not exist (nothing to snapshot), or when
+   * the snapshot write itself fails (best-effort — callers skip the entry
+   * rather than block the consolidation).
+   */
+  async snapshotForProvenance(filePath) {
+    if (!this._versioningConfig || !this._versioningConfig.enabled) return null;
+    let existing;
+    try {
+      existing = await readFile2(filePath, "utf-8");
+    } catch {
+      return null;
+    }
+    try {
+      const version = await createVersion(
+        filePath,
+        existing,
+        "consolidation",
+        this._versioningConfig,
+        log,
+        void 0,
+        this.baseDir
+      );
+      const rel = path4.relative(this.baseDir, filePath).split(path4.sep).join("/");
+      return `${rel}:${version.versionId}`;
+    } catch (err) {
+      log.warn(
+        `storage.snapshotForProvenance: failed to snapshot ${filePath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return null;
+    }
+  }
   /** The root directory of this storage instance. */
   get dir() {
     return this.baseDir;
   }
   identityFilePath(workspaceDir, namespace) {
     const rawNamespace = typeof namespace === "string" ? namespace.trim() : "";
-    if (!rawNamespace) return path5.join(workspaceDir, "IDENTITY.md");
+    if (!rawNamespace) return path4.join(workspaceDir, "IDENTITY.md");
     const safeNamespace = rawNamespace.replace(/[^a-zA-Z0-9._-]/g, "-");
-    return path5.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
+    return path4.join(workspaceDir, `IDENTITY.${safeNamespace}.md`);
   }
   versionFilePath(kind) {
     const fileName = kind === "memory-status" ? ".memory-status-version.log" : kind === "artifact-write" ? ".artifact-write-version.log" : ".cold-write-version.log";
-    return path5.join(this.stateDir, fileName);
+    return path4.join(this.stateDir, fileName);
   }
   bumpSharedVersion(kind, fallbackMap) {
     const filePath = this.versionFilePath(kind);
@@ -3033,25 +3163,28 @@ var StorageManager = class _StorageManager {
     return this.readSharedVersion("artifact-write", _StorageManager.artifactWriteVersionByDir);
   }
   get factsDir() {
-    return path5.join(this.baseDir, "facts");
+    return path4.join(this.baseDir, "facts");
   }
   get correctionsDir() {
-    return path5.join(this.baseDir, "corrections");
+    return path4.join(this.baseDir, "corrections");
   }
   get proceduresDir() {
-    return path5.join(this.baseDir, "procedures");
+    return path4.join(this.baseDir, "procedures");
+  }
+  get reasoningTracesDir() {
+    return path4.join(this.baseDir, "reasoning-traces");
   }
   get entitiesDir() {
-    return path5.join(this.baseDir, "entities");
+    return path4.join(this.baseDir, "entities");
   }
   get stateDir() {
-    return path5.join(this.baseDir, "state");
+    return path4.join(this.baseDir, "state");
   }
   get entitySynthesisQueuePath() {
-    return path5.join(this.stateDir, "entity-synthesis-queue.json");
+    return path4.join(this.stateDir, "entity-synthesis-queue.json");
   }
   get factHashIndexReadyPath() {
-    return path5.join(this.stateDir, "fact-hashes.ready");
+    return path4.join(this.stateDir, "fact-hashes.ready");
   }
   async getFactHashIndex() {
     if (this.factHashIndex) {
@@ -3079,7 +3212,7 @@ var StorageManager = class _StorageManager {
     }
     this.factHashIndexAuthoritativePromise = (async () => {
       try {
-        await access2(this.factHashIndexReadyPath);
+        await access(this.factHashIndexReadyPath);
         this.factHashIndexAuthoritative = true;
         return;
       } catch {
@@ -3117,8 +3250,8 @@ var StorageManager = class _StorageManager {
         );
       }
       await factHashIndex.save();
-      await mkdir3(path5.dirname(this.factHashIndexReadyPath), { recursive: true });
-      await writeFile3(this.factHashIndexReadyPath, "v1\n", "utf-8");
+      await mkdir2(path4.dirname(this.factHashIndexReadyPath), { recursive: true });
+      await writeFile2(this.factHashIndexReadyPath, "v1\n", "utf-8");
       this.factHashIndexAuthoritative = true;
     })().finally(() => {
       this.factHashIndexAuthoritativePromise = null;
@@ -3126,55 +3259,68 @@ var StorageManager = class _StorageManager {
     await this.factHashIndexAuthoritativePromise;
   }
   get questionsDir() {
-    return path5.join(this.baseDir, "questions");
+    return path4.join(this.baseDir, "questions");
   }
   get artifactsDir() {
-    return path5.join(this.baseDir, "artifacts");
+    return path4.join(this.baseDir, "artifacts");
   }
   get identityDir() {
-    return path5.join(this.baseDir, "identity");
+    return path4.join(this.baseDir, "identity");
   }
   get identityAnchorPath() {
-    return path5.join(this.identityDir, "identity-anchor.md");
+    return path4.join(this.identityDir, "identity-anchor.md");
   }
   get identityIncidentsDir() {
-    return path5.join(this.identityDir, "incidents");
+    return path4.join(this.identityDir, "incidents");
   }
   get identityAuditsWeeklyDir() {
-    return path5.join(this.identityDir, "audits", "weekly");
+    return path4.join(this.identityDir, "audits", "weekly");
   }
   get identityAuditsMonthlyDir() {
-    return path5.join(this.identityDir, "audits", "monthly");
+    return path4.join(this.identityDir, "audits", "monthly");
   }
   get identityImprovementLoopsPath() {
-    return path5.join(this.identityDir, "improvement-loops.md");
+    return path4.join(this.identityDir, "improvement-loops.md");
   }
   get identityReflectionsPath() {
-    return path5.join(this.identityDir, "reflections.md");
+    return path4.join(this.identityDir, "reflections.md");
   }
   get profilePath() {
-    return path5.join(this.baseDir, "profile.md");
+    return path4.join(this.baseDir, "profile.md");
   }
   get memoryActionsPath() {
-    return path5.join(this.stateDir, "memory-actions.jsonl");
+    return path4.join(this.stateDir, "memory-actions.jsonl");
   }
   get memoryLifecycleLedgerPath() {
-    return path5.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
+    return path4.join(this.stateDir, "memory-lifecycle-ledger.jsonl");
   }
   get compressionGuidelinesPath() {
-    return path5.join(this.stateDir, "compression-guidelines.md");
+    return path4.join(this.stateDir, "compression-guidelines.md");
   }
   get compressionGuidelineDraftPath() {
-    return path5.join(this.stateDir, "compression-guidelines.draft.md");
+    return path4.join(this.stateDir, "compression-guidelines.draft.md");
   }
   get compressionGuidelineStatePath() {
-    return path5.join(this.stateDir, "compression-guideline-state.json");
+    return path4.join(this.stateDir, "compression-guideline-state.json");
   }
   get compressionGuidelineDraftStatePath() {
-    return path5.join(this.stateDir, "compression-guideline-draft-state.json");
+    return path4.join(this.stateDir, "compression-guideline-draft-state.json");
   }
   get behaviorSignalsPath() {
-    return path5.join(this.stateDir, "behavior-signals.jsonl");
+    return path4.join(this.stateDir, "behavior-signals.jsonl");
+  }
+  /**
+   * Buffer surprise telemetry ledger (issue #563 PR 3).
+   *
+   * Append-only JSONL of per-turn `BUFFER_SURPRISE` events emitted by
+   * `SmartBuffer` when `bufferSurpriseTriggerEnabled` is on. Each row
+   * captures the score, the threshold in force at the time, whether the
+   * turn caused an extract_now upgrade, and the buffer size. Kept in
+   * `state/` alongside the other append-only ledgers so cleanup and
+   * governance sweeps can treat it uniformly.
+   */
+  get bufferSurpriseLedgerPath() {
+    return path4.join(this.stateDir, "buffer-surprise-ledger.jsonl");
   }
   /**
    * Load user-defined entity aliases from config/aliases.json in the memory store.
@@ -3182,9 +3328,9 @@ var StorageManager = class _StorageManager {
    * Call this once at startup (e.g. from orchestrator.initialize()).
    */
   async loadAliases() {
-    const aliasPath = path5.join(this.baseDir, "config", "aliases.json");
+    const aliasPath = path4.join(this.baseDir, "config", "aliases.json");
     try {
-      const raw = await readFile3(aliasPath, "utf-8");
+      const raw = await readFile2(aliasPath, "utf-8");
       const parsed = JSON.parse(raw);
       if (typeof parsed === "object" && parsed !== null) {
         userAliases = parsed;
@@ -3196,18 +3342,19 @@ var StorageManager = class _StorageManager {
   }
   async ensureDirectories() {
     const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    await mkdir3(path5.join(this.factsDir, today), { recursive: true });
-    await mkdir3(path5.join(this.proceduresDir, today), { recursive: true });
-    await mkdir3(this.correctionsDir, { recursive: true });
-    await mkdir3(this.entitiesDir, { recursive: true });
-    await mkdir3(this.stateDir, { recursive: true });
-    await mkdir3(this.questionsDir, { recursive: true });
-    await mkdir3(this.artifactsDir, { recursive: true });
-    await mkdir3(this.identityDir, { recursive: true });
-    await mkdir3(this.identityIncidentsDir, { recursive: true });
-    await mkdir3(this.identityAuditsWeeklyDir, { recursive: true });
-    await mkdir3(this.identityAuditsMonthlyDir, { recursive: true });
-    await mkdir3(path5.join(this.baseDir, "config"), { recursive: true });
+    await mkdir2(path4.join(this.factsDir, today), { recursive: true });
+    await mkdir2(path4.join(this.proceduresDir, today), { recursive: true });
+    await mkdir2(path4.join(this.reasoningTracesDir, today), { recursive: true });
+    await mkdir2(this.correctionsDir, { recursive: true });
+    await mkdir2(this.entitiesDir, { recursive: true });
+    await mkdir2(this.stateDir, { recursive: true });
+    await mkdir2(this.questionsDir, { recursive: true });
+    await mkdir2(this.artifactsDir, { recursive: true });
+    await mkdir2(this.identityDir, { recursive: true });
+    await mkdir2(this.identityIncidentsDir, { recursive: true });
+    await mkdir2(this.identityAuditsWeeklyDir, { recursive: true });
+    await mkdir2(this.identityAuditsMonthlyDir, { recursive: true });
+    await mkdir2(path4.join(this.baseDir, "config"), { recursive: true });
   }
   async writeMemory(category, content, options = {}) {
     await this.ensureDirectories();
@@ -3250,6 +3397,12 @@ var StorageManager = class _StorageManager {
     if (options.status !== void 0) {
       fm.status = options.status;
     }
+    if (options.derivedFrom !== void 0 && options.derivedFrom.length > 0) {
+      fm.derived_from = options.derivedFrom;
+    }
+    if (options.derivedVia !== void 0) {
+      fm.derived_via = options.derivedVia;
+    }
     let enrichedContent = content;
     if (options.structuredAttributes && Object.keys(options.structuredAttributes).length > 0) {
       enrichedContent = `${content}
@@ -3269,15 +3422,18 @@ ${sanitized.text}
 `;
     let filePath;
     if (category === "correction") {
-      filePath = path5.join(this.correctionsDir, `${id}.md`);
+      filePath = path4.join(this.correctionsDir, `${id}.md`);
     } else if (category === "procedure") {
-      await mkdir3(path5.join(this.proceduresDir, today), { recursive: true });
-      filePath = path5.join(this.proceduresDir, today, `${id}.md`);
+      await mkdir2(path4.join(this.proceduresDir, today), { recursive: true });
+      filePath = path4.join(this.proceduresDir, today, `${id}.md`);
+    } else if (category === "reasoning_trace") {
+      await mkdir2(path4.join(this.reasoningTracesDir, today), { recursive: true });
+      filePath = path4.join(this.reasoningTracesDir, today, `${id}.md`);
     } else {
-      filePath = path5.join(this.factsDir, today, `${id}.md`);
+      filePath = path4.join(this.factsDir, today, `${id}.md`);
     }
     await this.snapshotBeforeWrite(filePath, "write");
-    await writeFile3(filePath, fileContent, "utf-8");
+    await writeFile2(filePath, fileContent, "utf-8");
     this.invalidateAllMemoriesCache();
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeMemory", {
       memoryId: id,
@@ -3321,8 +3477,8 @@ ${sanitized.text}
     await this.ensureDirectories();
     const now = /* @__PURE__ */ new Date();
     const day = now.toISOString().slice(0, 10);
-    const dir = path5.join(this.artifactsDir, day);
-    await mkdir3(dir, { recursive: true });
+    const dir = path4.join(this.artifactsDir, day);
+    await mkdir2(dir, { recursive: true });
     const id = `artifact-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
     const fm = {
       id,
@@ -3345,8 +3501,8 @@ ${sanitized.text}
       log.warn(`artifact content rejected for ${id}; violations=${sanitized.violations.join(", ")}`);
       return "";
     }
-    const filePath = path5.join(dir, `${id}.md`);
-    await writeFile3(filePath, `${serializeFrontmatter(fm)}
+    const filePath = path4.join(dir, `${id}.md`);
+    await writeFile2(filePath, `${serializeFrontmatter(fm)}
 
 ${sanitized.text}
 `, "utf-8");
@@ -3373,7 +3529,7 @@ ${sanitized.text}
         try {
           const entries = await readdir(dir, { withFileTypes: true });
           for (const entry of entries) {
-            const fullPath = path5.join(dir, entry.name);
+            const fullPath = path4.join(dir, entry.name);
             if (entry.isDirectory()) {
               await readDir(fullPath);
               continue;
@@ -3439,7 +3595,7 @@ ${sanitized.text}
       log.debug(`fuzzy match: "${normalized}" \u2192 existing "${match}"`);
       normalized = match;
     }
-    const filePath = path5.join(this.entitiesDir, `${normalized}.md`);
+    const filePath = path4.join(this.entitiesDir, `${normalized}.md`);
     let entity = {
       name,
       type,
@@ -3458,7 +3614,7 @@ ${sanitized.text}
       aliases: []
     };
     try {
-      const existing = await readFile3(filePath, "utf-8");
+      const existing = await readFile2(filePath, "utf-8");
       entity = parseEntityFile(existing, this.entitySchemas);
     } catch {
     }
@@ -3516,7 +3672,7 @@ ${sanitized.text}
     entity.created = entity.created || timestamp;
     entity.updated = (/* @__PURE__ */ new Date()).toISOString();
     await this.snapshotBeforeWrite(filePath, "write");
-    await writeFile3(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
+    await writeFile2(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
     this.invalidateKnowledgeIndexCache();
     this.bumpMemoryStatusVersion();
     log.debug(`wrote entity ${normalized}`);
@@ -3524,7 +3680,7 @@ ${sanitized.text}
   }
   async readProfile() {
     try {
-      return await readFile3(this.profilePath, "utf-8");
+      return await readFile2(this.profilePath, "utf-8");
     } catch {
       return "";
     }
@@ -3532,7 +3688,7 @@ ${sanitized.text}
   async writeProfile(content) {
     await this.ensureDirectories();
     await this.snapshotBeforeWrite(this.profilePath, "consolidation");
-    await writeFile3(this.profilePath, content, "utf-8");
+    await writeFile2(this.profilePath, content, "utf-8");
     log.debug("updated profile.md");
   }
   /**
@@ -3650,7 +3806,7 @@ ${sanitized.text}
    * per-process in-memory cache safe across process boundaries.
    */
   invalidateColdMemoriesCache() {
-    const coldRoot = path5.join(this.baseDir, "cold");
+    const coldRoot = path4.join(this.baseDir, "cold");
     _StorageManager.coldMemoriesCache.delete(coldRoot);
     this.bumpColdWriteVersion();
   }
@@ -3678,7 +3834,7 @@ ${sanitized.text}
         const entries = await readdir(dir, { withFileTypes: true });
         const subdirs = [];
         for (const entry of entries) {
-          const fullPath = path5.join(dir, entry.name);
+          const fullPath = path4.join(dir, entry.name);
           if (entry.isDirectory()) {
             subdirs.push(fullPath);
           } else if (entry.name.endsWith(".md")) {
@@ -3693,6 +3849,7 @@ ${sanitized.text}
     };
     await collectPaths(this.factsDir);
     await collectPaths(this.proceduresDir);
+    await collectPaths(this.reasoningTracesDir);
     await collectPaths(this.correctionsDir);
     return filePaths;
   }
@@ -3705,7 +3862,7 @@ ${sanitized.text}
       const results = await Promise.all(
         batch.map(async (fullPath) => {
           try {
-            const raw = await readFile3(fullPath, "utf-8");
+            const raw = await readFile2(fullPath, "utf-8");
             const parsed = parseFrontmatter2(raw);
             if (!parsed) return null;
             return {
@@ -3730,7 +3887,7 @@ ${sanitized.text}
   }
   async readWindowUpdatedMs(filePath) {
     try {
-      const raw = await readFile3(filePath, "utf-8");
+      const raw = await readFile2(filePath, "utf-8");
       const match = raw.match(/^---\n([\s\S]*?)\n---\n?/);
       if (!match) return null;
       const frontmatterBlock = match[1];
@@ -3760,7 +3917,7 @@ ${sanitized.text}
     const correctionPaths = [];
     const factPaths = [];
     for (const filePath of filePaths) {
-      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path5.sep}`)) {
+      if (filePath === this.correctionsDir || filePath.startsWith(`${this.correctionsDir}${path4.sep}`)) {
         correctionPaths.push(filePath);
       } else {
         factPaths.push(filePath);
@@ -3880,7 +4037,7 @@ ${sanitized.text}
         const entries = await readdir(dir, { withFileTypes: true });
         const subdirs = [];
         for (const entry of entries) {
-          const fullPath = path5.join(dir, entry.name);
+          const fullPath = path4.join(dir, entry.name);
           if (entry.isDirectory()) {
             subdirs.push(fullPath);
           } else if (entry.name.endsWith(".md")) {
@@ -3909,12 +4066,12 @@ ${sanitized.text}
       try {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
-          const fullPath = path5.join(dir, entry.name);
+          const fullPath = path4.join(dir, entry.name);
           if (entry.isDirectory()) {
             await readDir(fullPath);
           } else if (entry.name.endsWith(".md")) {
             try {
-              const raw = await readFile3(fullPath, "utf-8");
+              const raw = await readFile2(fullPath, "utf-8");
               const parsed = parseFrontmatter2(raw);
               if (parsed) {
                 memories.push({
@@ -3940,7 +4097,7 @@ ${sanitized.text}
   /** Read a single memory file by its absolute path. Returns null if unreadable. */
   async readMemoryByPath(filePath) {
     try {
-      const raw = await readFile3(filePath, "utf-8");
+      const raw = await readFile2(filePath, "utf-8");
       const parsed = parseFrontmatter2(raw);
       if (parsed) {
         return {
@@ -3953,11 +4110,11 @@ ${sanitized.text}
           content: parsed.content
         };
       }
-      const normalizedPath = filePath.split(path5.sep).join("/");
+      const normalizedPath = filePath.split(path4.sep).join("/");
       if (normalizedPath.includes("/entities/") && filePath.endsWith(".md")) {
         const entity = parseEntityFile(raw, this.entitySchemas);
         if (!entity.name) return null;
-        const nameWithoutExt = path5.basename(filePath, ".md");
+        const nameWithoutExt = path4.basename(filePath, ".md");
         const fileMtime = entity.updated || await stat2(filePath).then((s) => s.mtime.toISOString()).catch(() => (/* @__PURE__ */ new Date(0)).toISOString());
         return {
           path: filePath,
@@ -3980,7 +4137,7 @@ ${sanitized.text}
     }
   }
   resolveTierRootDir(tier) {
-    return tier === "cold" ? path5.join(this.baseDir, "cold") : this.baseDir;
+    return tier === "cold" ? path4.join(this.baseDir, "cold") : this.baseDir;
   }
   resolveMemoryDateDir(memory) {
     const preferred = memory.frontmatter.created || memory.frontmatter.updated;
@@ -3995,30 +4152,33 @@ ${sanitized.text}
   buildTierMemoryPath(memory, tier) {
     const root = this.resolveTierRootDir(tier);
     if (this.isArtifactMemory(memory)) {
-      return path5.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+      return path4.join(root, "artifacts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
     }
     if (memory.frontmatter.category === "correction") {
-      return path5.join(root, "corrections", `${memory.frontmatter.id}.md`);
+      return path4.join(root, "corrections", `${memory.frontmatter.id}.md`);
     }
     if (memory.frontmatter.category === "procedure") {
-      return path5.join(root, "procedures", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+      return path4.join(root, "procedures", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+    }
+    if (memory.frontmatter.category === "reasoning_trace") {
+      return path4.join(root, "reasoning-traces", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
     }
-    return path5.join(root, "facts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
+    return path4.join(root, "facts", this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
   }
   async writeMemoryFileAtomic(targetPath, memory) {
     const fileContent = `${serializeFrontmatter(memory.frontmatter)}
 
 ${memory.content}
 `;
-    await mkdir3(path5.dirname(targetPath), { recursive: true });
+    await mkdir2(path4.dirname(targetPath), { recursive: true });
     const tempPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
     try {
-      await writeFile3(tempPath, fileContent, "utf-8");
+      await writeFile2(tempPath, fileContent, "utf-8");
       await rename(tempPath, targetPath);
       this.invalidateAllMemoriesCache();
     } catch (err) {
       try {
-        await unlink2(tempPath);
+        await unlink(tempPath);
       } catch {
       }
       throw err;
@@ -4026,11 +4186,11 @@ ${memory.content}
   }
   async moveMemoryToPath(memory, targetPath) {
     await this.writeMemoryFileAtomic(targetPath, memory);
-    const sourcePath = path5.resolve(memory.path);
-    const destPath = path5.resolve(targetPath);
+    const sourcePath = path4.resolve(memory.path);
+    const destPath = path4.resolve(targetPath);
     if (sourcePath !== destPath) {
       try {
-        await unlink2(memory.path);
+        await unlink(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -4042,15 +4202,15 @@ ${memory.content}
   }
   async migrateMemoryToTier(memory, targetTier) {
     const targetPath = this.buildTierMemoryPath(memory, targetTier);
-    const sourcePath = path5.resolve(memory.path);
-    const destPath = path5.resolve(targetPath);
+    const sourcePath = path4.resolve(memory.path);
+    const destPath = path4.resolve(targetPath);
     if (sourcePath === destPath) {
       return { changed: false, targetPath };
     }
     const existing = await this.readMemoryByPath(targetPath);
     if (existing?.frontmatter.id === memory.frontmatter.id) {
       try {
-        await unlink2(memory.path);
+        await unlink(memory.path);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (!message.includes("ENOENT")) {
@@ -4069,7 +4229,7 @@ ${memory.content}
     return { changed: true, targetPath };
   }
   get archiveDir() {
-    return path5.join(this.baseDir, "archive");
+    return path4.join(this.baseDir, "archive");
   }
   /**
    * Archive a memory by moving it from facts/ to archive/YYYY-MM-DD/.
@@ -4080,8 +4240,8 @@ ${memory.content}
     try {
       const now = lifecycle?.at ?? /* @__PURE__ */ new Date();
       const today = now.toISOString().slice(0, 10);
-      const destDir = path5.join(this.archiveDir, today);
-      await mkdir3(destDir, { recursive: true });
+      const destDir = path4.join(this.archiveDir, today);
+      await mkdir2(destDir, { recursive: true });
       const updatedFm = {
         ...memory.frontmatter,
         status: "archived",
@@ -4092,9 +4252,9 @@ ${memory.content}
 
 ${memory.content}
 `;
-      const destPath = path5.join(destDir, path5.basename(memory.path));
-      await writeFile3(destPath, fileContent, "utf-8");
-      await unlink2(memory.path);
+      const destPath = path4.join(destDir, path4.basename(memory.path));
+      await writeFile2(destPath, fileContent, "utf-8");
+      await unlink(memory.path);
       this.invalidateAllMemoriesCache();
       await this.appendGeneratedMemoryLifecycleEventFailOpen(
         "storage.archiveMemory",
@@ -4129,7 +4289,7 @@ ${memory.content}
   }
   async readEntity(name) {
     try {
-      return await readFile3(path5.join(this.entitiesDir, `${name}.md`), "utf-8");
+      return await readFile2(path4.join(this.entitiesDir, `${name}.md`), "utf-8");
     } catch {
       return "";
     }
@@ -4183,7 +4343,7 @@ ${memory.content}
     const memory = memories.find((m) => m.frontmatter.id === id);
     if (!memory) return false;
     try {
-      await unlink2(memory.path);
+      await unlink(memory.path);
       this.invalidateAllMemoriesCache();
       this.bumpMemoryStatusVersion();
       log.debug(`invalidated memory ${id}`);
@@ -4214,7 +4374,7 @@ ${memory.content}
 
 ${sanitized.text}
 `;
-    await writeFile3(memory.path, fileContent, "utf-8");
+    await writeFile2(memory.path, fileContent, "utf-8");
     this.invalidateAllMemoriesCache();
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.updateMemory", {
       memoryId: id,
@@ -4246,9 +4406,9 @@ ${sanitized.text}
 
 ${memory.content}
 `;
-    await writeFile3(memory.path, fileContent, "utf-8");
+    await writeFile2(memory.path, fileContent, "utf-8");
     this.invalidateAllMemoriesCache();
-    if (memory.path.includes(`${path5.sep}cold${path5.sep}`)) {
+    if (memory.path.includes(`${path4.sep}cold${path4.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
     await this.appendGeneratedMemoryLifecycleEventFailOpen(
@@ -4295,7 +4455,7 @@ ${memory.content}
       const expiresAt = new Date(m.frontmatter.expiresAt).getTime();
       if (expiresAt < now) {
         try {
-          await unlink2(m.path);
+          await unlink(m.path);
           deleted.push(m);
           log.debug(`cleaned expired memory ${m.frontmatter.id} (TTL expired)`);
         } catch {
@@ -4309,9 +4469,9 @@ ${memory.content}
     return deleted;
   }
   async loadBuffer() {
-    const bufferPath = path5.join(this.stateDir, "buffer.json");
+    const bufferPath = path4.join(this.stateDir, "buffer.json");
     try {
-      const raw = await readFile3(bufferPath, "utf-8");
+      const raw = await readFile2(bufferPath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return { turns: [], lastExtractionAt: null, extractionCount: 0 };
@@ -4319,13 +4479,13 @@ ${memory.content}
   }
   async saveBuffer(state) {
     await this.ensureDirectories();
-    const bufferPath = path5.join(this.stateDir, "buffer.json");
-    await writeFile3(bufferPath, JSON.stringify(state, null, 2), "utf-8");
+    const bufferPath = path4.join(this.stateDir, "buffer.json");
+    await writeFile2(bufferPath, JSON.stringify(state, null, 2), "utf-8");
   }
   async loadMeta() {
-    const metaPath = path5.join(this.stateDir, "meta.json");
+    const metaPath = path4.join(this.stateDir, "meta.json");
     try {
-      const raw = await readFile3(metaPath, "utf-8");
+      const raw = await readFile2(metaPath, "utf-8");
       const parsed = JSON.parse(raw);
       return {
         extractionCount: typeof parsed.extractionCount === "number" ? parsed.extractionCount : 0,
@@ -4355,8 +4515,8 @@ ${memory.content}
   }
   async saveMeta(state) {
     await this.ensureDirectories();
-    const metaPath = path5.join(this.stateDir, "meta.json");
-    await writeFile3(metaPath, JSON.stringify(state, null, 2), "utf-8");
+    const metaPath = path4.join(this.stateDir, "meta.json");
+    await writeFile2(metaPath, JSON.stringify(state, null, 2), "utf-8");
   }
   async appendMemoryActionEvents(events) {
     if (events.length === 0) return 0;
@@ -4388,12 +4548,102 @@ ${memory.content}
     await appendFile(this.memoryLifecycleLedgerPath, payload, "utf-8");
     return events.length;
   }
+  /**
+   * Append a batch of `BUFFER_SURPRISE` telemetry events (issue #563 PR 3).
+   *
+   * Each event records a single buffer flush decision driven by the
+   * surprise gate. The ledger is consumed by
+   * `reportBufferSurpriseDistribution` (Doctor report) and by downstream
+   * benchmark analysis. This method is fire-and-forget by contract:
+   * callers log but do not fail the hot path if the append throws.
+   */
+  async appendBufferSurpriseEvents(events) {
+    if (events.length === 0) return 0;
+    await this.ensureDirectories();
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    const payload = events.map((event) => {
+      const normalized = {
+        ...event,
+        event: "BUFFER_SURPRISE",
+        timestamp: event.timestamp && event.timestamp.length > 0 ? event.timestamp : nowIso
+      };
+      return `${JSON.stringify(normalized)}
+`;
+    }).join("");
+    await appendFile(this.bufferSurpriseLedgerPath, payload, "utf-8");
+    return events.length;
+  }
+  /**
+   * Read the buffer-surprise ledger, most recent rows last.
+   *
+   * `limit` bounds the number of **valid rows** returned (not the
+   * number of raw lines parsed). We parse every row, discard malformed
+   * ones, then take the tail — so a partial/truncated trailing line
+   * (the common failure mode after an interrupted append) cannot hide
+   * otherwise-valid recent data above it.
+   *
+   * Non-positive / non-integer / non-finite limits return `[]` rather
+   * than the entire file, matching the other ledger readers in this
+   * class and protecting against `slice(-0.5)` → `slice(-0)` silently
+   * devolving into an unbounded parse.
+   *
+   * # Performance note
+   *
+   * For very large ledgers (issue #563 follow-up), a tail-first reader
+   * would avoid parsing the full file when only a recent window is
+   * needed. We keep the full-scan implementation here because:
+   *
+   *   - the ledger is opt-in (flag off by default), so early deployments
+   *     accumulate rows slowly;
+   *   - telemetry rows are small (~200 bytes), so even 100k rows parse
+   *     in well under a second;
+   *   - the governance archive/cleanup flow can trim the ledger when
+   *     size becomes a concern, reusing the existing maintenance hooks.
+   *
+   * Swap to a chunked tail-reader if production logs show this is a
+   * hot path — leaving that work for a follow-up keeps this PR scoped
+   * to correctness, not optimization.
+   */
+  async readBufferSurpriseEvents(options = {}) {
+    let raw;
+    try {
+      raw = await readFile2(this.bufferSurpriseLedgerPath, "utf-8");
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") return [];
+      throw err;
+    }
+    let effectiveLimit = null;
+    if (options.limit !== void 0) {
+      if (typeof options.limit !== "number" || !Number.isFinite(options.limit) || options.limit <= 0) {
+        return [];
+      }
+      const floored = Math.floor(options.limit);
+      if (floored <= 0) return [];
+      effectiveLimit = floored;
+    }
+    const lines = raw.split("\n");
+    const events = [];
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (isValidBufferSurpriseEvent(parsed)) {
+          events.push(parsed);
+        }
+      } catch {
+      }
+    }
+    if (effectiveLimit === null) return events;
+    return events.slice(-effectiveLimit);
+  }
   async appendBehaviorSignals(events) {
     if (events.length === 0) return 0;
     await this.ensureDirectories();
     let existingKeys = /* @__PURE__ */ new Set();
     try {
-      const raw = await readFile3(this.behaviorSignalsPath, "utf-8");
+      const raw = await readFile2(this.behaviorSignalsPath, "utf-8");
       const lines = raw.split("\n");
       for (const line of lines) {
         const row = line.trim();
@@ -4429,7 +4679,7 @@ ${memory.content}
   async appendReextractJobs(events) {
     if (events.length === 0) return 0;
     await this.ensureDirectories();
-    const filePath = path5.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path4.join(this.stateDir, "reextract-jobs.jsonl");
     const lines = events.map((event) => JSON.stringify(event)).join("\n") + "\n";
     try {
       await appendFile(filePath, lines, "utf-8");
@@ -4440,9 +4690,9 @@ ${memory.content}
   }
   async readReextractJobs(limit = 200) {
     const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(1e3, Math.floor(limit))) : 200;
-    const filePath = path5.join(this.stateDir, "reextract-jobs.jsonl");
+    const filePath = path4.join(this.stateDir, "reextract-jobs.jsonl");
     try {
-      const raw = await readFile3(filePath, "utf-8");
+      const raw = await readFile2(filePath, "utf-8");
       const lines = raw.split("\n").filter((line) => line.trim().length > 0);
       const parsed = [];
       for (const line of lines) {
@@ -4470,7 +4720,7 @@ ${memory.content}
     const cappedLimit = Math.max(0, Math.floor(limit));
     if (cappedLimit === 0) return [];
     try {
-      const raw = await readFile3(this.behaviorSignalsPath, "utf-8");
+      const raw = await readFile2(this.behaviorSignalsPath, "utf-8");
       const out = [];
       const lines = raw.split("\n");
       for (let i = lines.length - 1; i >= 0 && out.length < cappedLimit; i -= 1) {
@@ -4493,7 +4743,7 @@ ${memory.content}
     const cappedLimit = Math.max(0, Math.floor(limit));
     if (cappedLimit === 0) return [];
     try {
-      const raw = await readFile3(this.memoryActionsPath, "utf-8");
+      const raw = await readFile2(this.memoryActionsPath, "utf-8");
       const out = [];
       const lines = raw.split("\n");
       for (let i = lines.length - 1; i >= 0 && out.length < cappedLimit; i -= 1) {
@@ -4514,7 +4764,7 @@ ${memory.content}
   }
   async readAllMemoryLifecycleEvents() {
     try {
-      const raw = await readFile3(this.memoryLifecycleLedgerPath, "utf-8");
+      const raw = await readFile2(this.memoryLifecycleLedgerPath, "utf-8");
       const out = [];
       const lines = raw.split("\n");
       for (const line of lines) {
@@ -4541,34 +4791,34 @@ ${memory.content}
   }
   async writeCompressionGuidelines(content) {
     await this.ensureDirectories();
-    await writeFile3(this.compressionGuidelinesPath, content, "utf-8");
+    await writeFile2(this.compressionGuidelinesPath, content, "utf-8");
   }
   async readCompressionGuidelines() {
     try {
-      return await readFile3(this.compressionGuidelinesPath, "utf-8");
+      return await readFile2(this.compressionGuidelinesPath, "utf-8");
     } catch {
       return null;
     }
   }
   async writeCompressionGuidelineDraft(content) {
     await this.ensureDirectories();
-    await writeFile3(this.compressionGuidelineDraftPath, content, "utf-8");
+    await writeFile2(this.compressionGuidelineDraftPath, content, "utf-8");
   }
   async readCompressionGuidelineDraft() {
     try {
-      return await readFile3(this.compressionGuidelineDraftPath, "utf-8");
+      return await readFile2(this.compressionGuidelineDraftPath, "utf-8");
     } catch {
       return null;
     }
   }
   async writeCompressionGuidelineOptimizerState(state) {
     await this.ensureDirectories();
-    await writeFile3(this.compressionGuidelineStatePath, `${JSON.stringify(state, null, 2)}
+    await writeFile2(this.compressionGuidelineStatePath, `${JSON.stringify(state, null, 2)}
 `, "utf-8");
   }
   async writeCompressionGuidelineDraftState(state) {
     await this.ensureDirectories();
-    await writeFile3(this.compressionGuidelineDraftStatePath, `${JSON.stringify(state, null, 2)}
+    await writeFile2(this.compressionGuidelineDraftStatePath, `${JSON.stringify(state, null, 2)}
 `, "utf-8");
   }
   async readCompressionGuidelineOptimizerState() {
@@ -4590,8 +4840,8 @@ ${memory.content}
       return false;
     }
     if (draftState.contentHash) {
-      const contentHash2 = createHash2("sha256").update(draftContent).digest("hex");
-      if (contentHash2 !== draftState.contentHash) return false;
+      const contentHash = createHash("sha256").update(draftContent).digest("hex");
+      if (contentHash !== draftState.contentHash) return false;
     }
     await this.writeCompressionGuidelines(draftContent);
     await this.writeCompressionGuidelineOptimizerState({
@@ -4599,8 +4849,8 @@ ${memory.content}
       activationState: "active"
     });
     await Promise.all([
-      unlink2(this.compressionGuidelineDraftPath).catch(() => void 0),
-      unlink2(this.compressionGuidelineDraftStatePath).catch(() => void 0)
+      unlink(this.compressionGuidelineDraftPath).catch(() => void 0),
+      unlink(this.compressionGuidelineDraftStatePath).catch(() => void 0)
     ]);
     return true;
   }
@@ -4617,12 +4867,12 @@ ${memory.content}
       return typeof rule.action === "string" && typeof rule.delta === "number" && Number.isFinite(rule.delta) && (rule.direction === "increase" || rule.direction === "decrease" || rule.direction === "hold") && (rule.confidence === "low" || rule.confidence === "medium" || rule.confidence === "high") && Array.isArray(rule.notes) && rule.notes.every((note) => typeof note === "string");
     };
     try {
-      const raw = await readFile3(filePath, "utf-8");
+      const raw = await readFile2(filePath, "utf-8");
       const parsed = JSON.parse(raw);
       const sourceWindow = parsed?.sourceWindow;
       const eventCounts = parsed?.eventCounts;
       const activationState = parsed?.activationState === "draft" || parsed?.activationState === "active" ? parsed.activationState : void 0;
-      const contentHash2 = typeof parsed?.contentHash === "string" && parsed.contentHash.length > 0 ? parsed.contentHash : void 0;
+      const contentHash = typeof parsed?.contentHash === "string" && parsed.contentHash.length > 0 ? parsed.contentHash : void 0;
       const actionSummaries = Array.isArray(parsed?.actionSummaries) ? parsed.actionSummaries.filter(isValidActionSummary) : void 0;
       const ruleUpdates = Array.isArray(parsed?.ruleUpdates) ? parsed.ruleUpdates.filter(isValidRuleUpdate) : void 0;
       if (!isFiniteNonNegativeInteger(parsed?.version) || typeof parsed?.updatedAt !== "string" || parsed.updatedAt.length === 0 || !sourceWindow || typeof sourceWindow.from !== "string" || sourceWindow.from.length === 0 || typeof sourceWindow.to !== "string" || sourceWindow.to.length === 0 || !eventCounts || !isFiniteNonNegativeInteger(eventCounts.total) || !isFiniteNonNegativeInteger(eventCounts.applied) || !isFiniteNonNegativeInteger(eventCounts.skipped) || !isFiniteNonNegativeInteger(eventCounts.failed) || !isFiniteNonNegativeInteger(parsed?.guidelineVersion)) {
@@ -4642,7 +4892,7 @@ ${memory.content}
           failed: eventCounts.failed
         },
         guidelineVersion: parsed.guidelineVersion,
-        ...contentHash2 ? { contentHash: contentHash2 } : {},
+        ...contentHash ? { contentHash } : {},
         ...activationState ? { activationState } : {},
         ...actionSummaries ? { actionSummaries } : {},
         ...ruleUpdates ? { ruleUpdates } : {}
@@ -4653,11 +4903,11 @@ ${memory.content}
   }
   async writeIdentityAnchor(content) {
     await this.ensureDirectories();
-    await writeFile3(this.identityAnchorPath, content, "utf-8");
+    await writeFile2(this.identityAnchorPath, content, "utf-8");
   }
   async readIdentityAnchor() {
     try {
-      return await readFile3(this.identityAnchorPath, "utf-8");
+      return await readFile2(this.identityAnchorPath, "utf-8");
     } catch {
       return null;
     }
@@ -4669,8 +4919,8 @@ ${memory.content}
     const date = nowIso.slice(0, 10);
     const id = this.generateId("incident");
     const incident = createContinuityIncidentRecord(id, input, nowIso);
-    const filePath = path5.join(this.identityIncidentsDir, `${date}-${id}.md`);
-    await writeFile3(filePath, serializeContinuityIncident(incident), "utf-8");
+    const filePath = path4.join(this.identityIncidentsDir, `${date}-${id}.md`);
+    await writeFile2(filePath, serializeContinuityIncident(incident), "utf-8");
     return { ...incident, filePath };
   }
   async readContinuityIncidents(limit = 200, state = "all") {
@@ -4682,9 +4932,9 @@ ${memory.content}
       const incidents = [];
       for (const file of candidates) {
         if (incidents.length >= cappedLimit) break;
-        const filePath = path5.join(this.identityIncidentsDir, file);
+        const filePath = path4.join(this.identityIncidentsDir, file);
         try {
-          const raw = await readFile3(filePath, "utf-8");
+          const raw = await readFile2(filePath, "utf-8");
           const parsed = parseContinuityIncident(raw);
           if (!parsed) continue;
           if (state !== "all" && parsed.state !== state) continue;
@@ -4703,33 +4953,33 @@ ${memory.content}
     if (!target || !directFilePath) return null;
     if (target.state === "closed") return target;
     const closed = closeContinuityIncidentRecord(target, closure, (/* @__PURE__ */ new Date()).toISOString());
-    await writeFile3(directFilePath, serializeContinuityIncident(closed), "utf-8");
+    await writeFile2(directFilePath, serializeContinuityIncident(closed), "utf-8");
     return { ...closed, filePath: directFilePath };
   }
   async writeIdentityAudit(period, key, content) {
     await this.ensureDirectories();
     const safeKey = this.sanitizeIdentityAuditKey(key);
     const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
-    const filePath = path5.join(dir, `${safeKey}.md`);
-    await writeFile3(filePath, content, "utf-8");
+    const filePath = path4.join(dir, `${safeKey}.md`);
+    await writeFile2(filePath, content, "utf-8");
     return filePath;
   }
   async readIdentityAudit(period, key) {
     try {
       const safeKey = this.sanitizeIdentityAuditKey(key);
       const dir = period === "weekly" ? this.identityAuditsWeeklyDir : this.identityAuditsMonthlyDir;
-      return await readFile3(path5.join(dir, `${safeKey}.md`), "utf-8");
+      return await readFile2(path4.join(dir, `${safeKey}.md`), "utf-8");
     } catch {
       return null;
     }
   }
   async writeIdentityImprovementLoops(content) {
     await this.ensureDirectories();
-    await writeFile3(this.identityImprovementLoopsPath, content, "utf-8");
+    await writeFile2(this.identityImprovementLoopsPath, content, "utf-8");
   }
   async readIdentityImprovementLoops() {
     try {
-      return await readFile3(this.identityImprovementLoopsPath, "utf-8");
+      return await readFile2(this.identityImprovementLoopsPath, "utf-8");
     } catch {
       return null;
     }
@@ -4767,7 +5017,7 @@ ${memory.content}
   }
   async readContinuityIncidentFile(filePath) {
     try {
-      const raw = await readFile3(filePath, "utf-8");
+      const raw = await readFile2(filePath, "utf-8");
       const parsed = parseContinuityIncident(raw);
       return parsed ? { ...parsed, filePath } : null;
     } catch {
@@ -4778,12 +5028,12 @@ ${memory.content}
     const fileNames = await this.readContinuityIncidentFileNames();
     const directMatch = fileNames.find((name) => name.endsWith(`-${id}.md`));
     if (directMatch) {
-      const directPath = path5.join(this.identityIncidentsDir, directMatch);
+      const directPath = path4.join(this.identityIncidentsDir, directMatch);
       const parsed = await this.readContinuityIncidentFile(directPath);
       if (parsed?.id === id) return directPath;
     }
     for (const fileName of fileNames) {
-      const filePath = path5.join(this.identityIncidentsDir, fileName);
+      const filePath = path4.join(this.identityIncidentsDir, fileName);
       const parsed = await this.readContinuityIncidentFile(filePath);
       if (parsed?.id === id) return filePath;
     }
@@ -4797,7 +5047,7 @@ ${memory.content}
     return trimmed;
   }
   async writeQuestion(question, context, priority) {
-    await mkdir3(this.questionsDir, { recursive: true });
+    await mkdir2(this.questionsDir, { recursive: true });
     const id = this.generateId("q");
     const frontmatter = {
       id,
@@ -4813,8 +5063,8 @@ ${question}
 
 **Context:** ${context}
 `;
-    const filePath = path5.join(this.questionsDir, `${id}.md`);
-    await writeFile3(filePath, content, "utf-8");
+    const filePath = path4.join(this.questionsDir, `${id}.md`);
+    await writeFile2(filePath, content, "utf-8");
     log.debug(`wrote question ${id} to ${filePath}`);
     this.invalidateQuestionsCache();
     return id;
@@ -4837,8 +5087,8 @@ ${question}
       const questions = [];
       for (const file of files) {
         if (!file.endsWith(".md")) continue;
-        const filePath = path5.join(this.questionsDir, file);
-        const raw = await readFile3(filePath, "utf-8");
+        const filePath = path4.join(this.questionsDir, file);
+        const raw = await readFile2(filePath, "utf-8");
         const parsed = this.parseQuestionFile(raw, filePath);
         if (parsed) {
           questions.push(parsed);
@@ -4860,7 +5110,7 @@ ${question}
     if (!match) return null;
     const frontmatterStr = match[1];
     const body = match[2].trim();
-    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path5.basename(filePath, ".md");
+    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path4.basename(filePath, ".md");
     const created = this.extractFrontmatterValue(frontmatterStr, "created") ?? "";
     const priority = parseFloat(
       this.extractFrontmatterValue(frontmatterStr, "priority") ?? "0.5"
@@ -4881,7 +5131,7 @@ ${question}
     const questions = await this.readQuestions();
     const q = questions.find((q2) => q2.id === id);
     if (!q) return false;
-    let raw = await readFile3(q.filePath, "utf-8");
+    let raw = await readFile2(q.filePath, "utf-8");
     raw = raw.replace(/resolved: false/, "resolved: true");
     raw = raw.replace(
       /---\n\n/,
@@ -4890,7 +5140,7 @@ ${question}
 
 `
     );
-    await writeFile3(q.filePath, raw, "utf-8");
+    await writeFile2(q.filePath, raw, "utf-8");
     log.debug(`resolved question ${id}`);
     return true;
   }
@@ -4900,14 +5150,14 @@ ${question}
   async readIdentity(workspaceDir, namespace) {
     const identityPath = this.identityFilePath(workspaceDir, namespace);
     try {
-      return await readFile3(identityPath, "utf-8");
+      return await readFile2(identityPath, "utf-8");
     } catch {
       return "";
     }
   }
   async writeIdentity(workspaceDir, content, namespace) {
     const identityPath = this.identityFilePath(workspaceDir, namespace);
-    await writeFile3(identityPath, content, "utf-8");
+    await writeFile2(identityPath, content, "utf-8");
     log.debug(`wrote consolidated IDENTITY.md (${content.length} chars)`);
   }
   /** Max size for IDENTITY.md before we stop appending reflections (15KB leaves room under 20KB gateway limit) */
@@ -4918,22 +5168,22 @@ ${question}
     const identityPath = this.identityFilePath(workspaceDir, opts?.namespace);
     let existing = "";
     try {
-      existing = await readFile3(identityPath, "utf-8");
+      existing = await readFile2(identityPath, "utf-8");
     } catch {
     }
     const hygiene = opts?.hygiene;
-    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path5.basename(identityPath));
+    const rotateEnabled = hygiene?.enabled === true && hygiene.rotateEnabled === true && Array.isArray(hygiene.rotatePaths) && hygiene.rotatePaths.includes(path4.basename(identityPath));
     if (rotateEnabled) {
       const maxBytes = hygiene.rotateMaxBytes;
       if (existing.length > maxBytes) {
-        const archiveDir = path5.join(workspaceDir, hygiene.archiveDir);
+        const archiveDir = path4.join(workspaceDir, hygiene.archiveDir);
         const { newContent } = await rotateMarkdownFileToArchive({
           filePath: identityPath,
           archiveDir,
           archivePrefix: "IDENTITY",
           keepTailChars: hygiene.rotateKeepTailChars
         });
-        await writeFile3(identityPath, newContent, "utf-8");
+        await writeFile2(identityPath, newContent, "utf-8");
         existing = newContent;
         log.info(
           `rotated IDENTITY.md to archive (size=${existing.length} chars, maxBytes=${maxBytes})`
@@ -4964,24 +5214,24 @@ ${question}
 
 ${reflection}
 `;
-    await writeFile3(identityPath, existing + section, "utf-8");
+    await writeFile2(identityPath, existing + section, "utf-8");
     log.debug(`appended reflection to ${identityPath}`);
   }
   async readIdentityReflections() {
     try {
-      return await readFile3(this.identityReflectionsPath, "utf-8");
+      return await readFile2(this.identityReflectionsPath, "utf-8");
     } catch {
       return null;
     }
   }
   async writeIdentityReflections(content) {
-    await mkdir3(this.identityDir, { recursive: true });
-    await writeFile3(this.identityReflectionsPath, content, "utf-8");
+    await mkdir2(this.identityDir, { recursive: true });
+    await writeFile2(this.identityReflectionsPath, content, "utf-8");
   }
   async appendIdentityReflection(reflection) {
     let existing = "";
     try {
-      existing = await readFile3(this.identityReflectionsPath, "utf-8");
+      existing = await readFile2(this.identityReflectionsPath, "utf-8");
     } catch {
     }
     if (existing.length > _StorageManager.IDENTITY_MAX_BYTES) {
@@ -5006,8 +5256,8 @@ ${reflection}
 
 ${reflection}
 `;
-    await mkdir3(this.identityDir, { recursive: true });
-    await writeFile3(this.identityReflectionsPath, `${existing.trimEnd()}${section}`, "utf-8");
+    await mkdir2(this.identityDir, { recursive: true });
+    await writeFile2(this.identityReflectionsPath, `${existing.trimEnd()}${section}`, "utf-8");
     log.debug(`appended namespace-local reflection to ${this.identityReflectionsPath}`);
   }
   // ---------------------------------------------------------------------------
@@ -5018,10 +5268,10 @@ ${reflection}
    * Deduplicates by target+label.
    */
   async addEntityRelationship(name, rel) {
-    const filePath = path5.join(this.entitiesDir, `${name}.md`);
+    const filePath = path4.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
-      const content = await readFile3(filePath, "utf-8");
+      const content = await readFile2(filePath, "utf-8");
       entity = parseEntityFile(content, this.entitySchemas);
     } catch {
       log.debug(`addEntityRelationship: entity file ${name}.md not found`);
@@ -5033,7 +5283,7 @@ ${reflection}
     if (exists) return;
     entity.relationships.push(rel);
     entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await writeFile3(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
+    await writeFile2(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
     this.invalidateKnowledgeIndexCache();
   }
   /**
@@ -5041,10 +5291,10 @@ ${reflection}
    * Prepends to the beginning, prunes oldest entries beyond maxEntries.
    */
   async addEntityActivity(name, entry, maxEntries) {
-    const filePath = path5.join(this.entitiesDir, `${name}.md`);
+    const filePath = path4.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
-      const content = await readFile3(filePath, "utf-8");
+      const content = await readFile2(filePath, "utf-8");
       entity = parseEntityFile(content, this.entitySchemas);
     } catch {
       log.debug(`addEntityActivity: entity file ${name}.md not found`);
@@ -5055,17 +5305,17 @@ ${reflection}
       entity.activity = entity.activity.slice(0, maxEntries);
     }
     entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await writeFile3(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
+    await writeFile2(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
     this.invalidateKnowledgeIndexCache();
   }
   /**
    * Add an alias to an entity file. Deduplicates.
    */
   async addEntityAlias(name, alias) {
-    const filePath = path5.join(this.entitiesDir, `${name}.md`);
+    const filePath = path4.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
-      const content = await readFile3(filePath, "utf-8");
+      const content = await readFile2(filePath, "utf-8");
       entity = parseEntityFile(content, this.entitySchemas);
     } catch {
       log.debug(`addEntityAlias: entity file ${name}.md not found`);
@@ -5074,17 +5324,17 @@ ${reflection}
     if (entity.aliases.includes(alias)) return;
     entity.aliases.push(alias);
     entity.updated = (/* @__PURE__ */ new Date()).toISOString();
-    await writeFile3(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
+    await writeFile2(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
     this.invalidateKnowledgeIndexCache();
   }
   /**
    * Set or rewrite the synthesis layer of an entity file.
    */
   async updateEntitySynthesis(name, synthesis, options = {}) {
-    const filePath = path5.join(this.entitiesDir, `${name}.md`);
+    const filePath = path4.join(this.entitiesDir, `${name}.md`);
     let entity;
     try {
-      const content = await readFile3(filePath, "utf-8");
+      const content = await readFile2(filePath, "utf-8");
       entity = parseEntityFile(content, this.entitySchemas);
     } catch {
       log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
@@ -5103,7 +5353,7 @@ ${reflection}
     entity.synthesisStructuredFactDigest = synthesisStructuredFactDigest;
     entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0) + (options.incrementVersion === false ? 0 : 1);
     entity.updated = entityUpdatedAt;
-    await writeFile3(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
+    await writeFile2(filePath, serializeEntityFile(entity, this.entitySchemas), "utf-8");
     await this.removeEntitySynthesisQueueEntries([
       .../* @__PURE__ */ new Set([name, normalizeEntityName(entity.name, entity.type)])
     ]);
@@ -5117,8 +5367,8 @@ ${reflection}
     const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     let synthesisTimelineCount;
     try {
-      const filePath = path5.join(this.entitiesDir, `${name}.md`);
-      const content = await readFile3(filePath, "utf-8");
+      const filePath = path4.join(this.entitiesDir, `${name}.md`);
+      const content = await readFile2(filePath, "utf-8");
       synthesisTimelineCount = parseEntityFile(content, this.entitySchemas).timeline.length;
     } catch {
       synthesisTimelineCount = void 0;
@@ -5131,7 +5381,7 @@ ${reflection}
   }
   async readEntitySynthesisQueue() {
     try {
-      const raw = await readFile3(this.entitySynthesisQueuePath, "utf-8");
+      const raw = await readFile2(this.entitySynthesisQueuePath, "utf-8");
       const parsed = JSON.parse(raw);
       return Array.isArray(parsed.entityNames) ? parsed.entityNames.filter((value) => typeof value === "string") : [];
     } catch {
@@ -5155,8 +5405,8 @@ ${reflection}
       const rightTs = latestEntityTimelineTimestamp(right.entity) ?? "";
       return compareEntityTimestamps(rightTs, leftTs);
     }).map(({ entityName }) => entityName);
-    await mkdir3(this.stateDir, { recursive: true });
-    await writeFile3(
+    await mkdir2(this.stateDir, { recursive: true });
+    await writeFile2(
       this.entitySynthesisQueuePath,
       JSON.stringify(
         {
@@ -5176,8 +5426,8 @@ ${reflection}
     if (queue.length === 0) return;
     const removals = new Set(entityNames);
     const nextQueue = queue.filter((name) => !removals.has(name));
-    await mkdir3(this.stateDir, { recursive: true });
-    await writeFile3(
+    await mkdir2(this.stateDir, { recursive: true });
+    await writeFile2(
       this.entitySynthesisQueuePath,
       JSON.stringify(
         {
@@ -5198,7 +5448,7 @@ ${reflection}
       if (!raw) continue;
       const serialized = serializeEntityFile(parseEntityFile(raw, this.entitySchemas), this.entitySchemas);
       if (raw.trimEnd() === serialized.trimEnd()) continue;
-      await writeFile3(path5.join(this.entitiesDir, `${entityName}.md`), serialized, "utf-8");
+      await writeFile2(path4.join(this.entitiesDir, `${entityName}.md`), serialized, "utf-8");
       migrated += 1;
     }
     if (migrated > 0) {
@@ -5232,7 +5482,7 @@ ${reflection}
         const batch = mdFiles.slice(i, i + BATCH_SIZE);
         const results = await Promise.all(
           batch.map(
-            (entry) => readFile3(path5.join(this.entitiesDir, entry), "utf-8").catch(() => null)
+            (entry) => readFile2(path4.join(this.entitiesDir, entry), "utf-8").catch(() => null)
           )
         );
         for (const content of results) {
@@ -5372,9 +5622,9 @@ ${rows.join("\n")}
           extraSections: []
         };
         for (const file of files) {
-          const filePath = path5.join(this.entitiesDir, file);
+          const filePath = path4.join(this.entitiesDir, file);
           try {
-            const content = await readFile3(filePath, "utf-8");
+            const content = await readFile2(filePath, "utf-8");
             const parsed = parseEntityFile(content, this.entitySchemas);
             if (!mergedEntity.type || mergedEntity.type === "other") {
               mergedEntity.type = parsed.type;
@@ -5501,13 +5751,13 @@ ${rows.join("\n")}
         }
         mergedEntity.created = mergedEntity.created || mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
         mergedEntity.updated = mergedEntity.updated || (/* @__PURE__ */ new Date()).toISOString();
-        const canonicalPath = path5.join(this.entitiesDir, `${canonical}.md`);
-        await writeFile3(canonicalPath, serializeEntityFile(mergedEntity, this.entitySchemas), "utf-8");
+        const canonicalPath = path4.join(this.entitiesDir, `${canonical}.md`);
+        await writeFile2(canonicalPath, serializeEntityFile(mergedEntity, this.entitySchemas), "utf-8");
         for (const file of files) {
-          const filePath = path5.join(this.entitiesDir, file);
+          const filePath = path4.join(this.entitiesDir, file);
           if (filePath !== canonicalPath) {
             try {
-              await unlink2(filePath);
+              await unlink(filePath);
               merged++;
               log.debug(`merged entity ${file} \u2192 ${canonical}.md`);
             } catch {
@@ -5532,7 +5782,7 @@ ${rows.join("\n")}
       const updatedAt = new Date(m.frontmatter.updated).getTime();
       if (updatedAt < cutoff) {
         try {
-          await unlink2(m.path);
+          await unlink(m.path);
           deleted.push(m);
           log.debug(`cleaned expired commitment ${m.frontmatter.id}`);
         } catch {
@@ -5569,7 +5819,7 @@ ${rows.join("\n")}
 ${memory.content}
 `;
       try {
-        await writeFile3(memory.path, fileContent, "utf-8");
+        await writeFile2(memory.path, fileContent, "utf-8");
         updated++;
       } catch (err) {
         log.debug(`failed to update access tracking for ${entry.memoryId}: ${err}`);
@@ -5602,7 +5852,7 @@ ${memory.content}
     const filePaths = await this.collectActiveMemoryPaths();
     const foundIds = /* @__PURE__ */ new Set();
     for (const filePath of filePaths) {
-      const basename = path5.basename(filePath, ".md");
+      const basename = path4.basename(filePath, ".md");
       if (wantedIds.has(basename)) {
         foundIds.add(basename);
         if (foundIds.size === wantedIds.size) break;
@@ -5700,14 +5950,17 @@ ${sanitized.text}
 `;
     let filePath;
     if (category === "correction") {
-      filePath = path5.join(this.correctionsDir, `${id}.md`);
+      filePath = path4.join(this.correctionsDir, `${id}.md`);
     } else if (category === "procedure") {
-      await mkdir3(path5.join(this.proceduresDir, today), { recursive: true });
-      filePath = path5.join(this.proceduresDir, today, `${id}.md`);
+      await mkdir2(path4.join(this.proceduresDir, today), { recursive: true });
+      filePath = path4.join(this.proceduresDir, today, `${id}.md`);
+    } else if (category === "reasoning_trace") {
+      await mkdir2(path4.join(this.reasoningTracesDir, today), { recursive: true });
+      filePath = path4.join(this.reasoningTracesDir, today, `${id}.md`);
     } else {
-      filePath = path5.join(this.factsDir, today, `${id}.md`);
+      filePath = path4.join(this.factsDir, today, `${id}.md`);
     }
-    await writeFile3(filePath, fileContent, "utf-8");
+    await writeFile2(filePath, fileContent, "utf-8");
     log.debug(`wrote chunk ${id} (${chunkIndex + 1}/${chunkTotal}) to ${filePath}`);
     return id;
   }
@@ -5743,7 +5996,7 @@ ${sanitized.text}
 ${oldMemory.content}
 `;
     try {
-      await writeFile3(oldMemory.path, fileContent, "utf-8");
+      await writeFile2(oldMemory.path, fileContent, "utf-8");
       await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.supersedeMemory", {
         memoryId: oldMemoryId,
         eventType: "superseded",
@@ -5774,15 +6027,15 @@ Reason: ${reason}`, {
   // Memory Summarization (Phase 4A)
   // ---------------------------------------------------------------------------
   get summariesDir() {
-    return path5.join(this.baseDir, "summaries");
+    return path4.join(this.baseDir, "summaries");
   }
   /**
    * Write a memory summary.
    */
   async writeSummary(summary) {
-    await mkdir3(this.summariesDir, { recursive: true });
-    const filePath = path5.join(this.summariesDir, `${summary.id}.json`);
-    await writeFile3(filePath, JSON.stringify(summary, null, 2), "utf-8");
+    await mkdir2(this.summariesDir, { recursive: true });
+    const filePath = path4.join(this.summariesDir, `${summary.id}.json`);
+    await writeFile2(filePath, JSON.stringify(summary, null, 2), "utf-8");
     log.debug(`wrote summary ${summary.id}`);
   }
   /**
@@ -5794,8 +6047,8 @@ Reason: ${reason}`, {
       const summaries = [];
       for (const file of files) {
         if (!file.endsWith(".json")) continue;
-        const filePath = path5.join(this.summariesDir, file);
-        const raw = await readFile3(filePath, "utf-8");
+        const filePath = path4.join(this.summariesDir, file);
+        const raw = await readFile2(filePath, "utf-8");
         summaries.push(JSON.parse(raw));
       }
       return summaries;
@@ -5825,7 +6078,7 @@ Reason: ${reason}`, {
 ${memory.content}
 `;
       try {
-        await writeFile3(memory.path, fileContent, "utf-8");
+        await writeFile2(memory.path, fileContent, "utf-8");
         await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.archiveMemories", {
           memoryId: id,
           eventType: "archived",
@@ -5853,18 +6106,18 @@ ${memory.content}
    * Save topic scores to meta.json.
    */
   async saveTopics(topics) {
-    const metaPath = path5.join(this.stateDir, "topics.json");
-    await mkdir3(this.stateDir, { recursive: true });
-    await writeFile3(metaPath, JSON.stringify({ topics, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2), "utf-8");
+    const metaPath = path4.join(this.stateDir, "topics.json");
+    await mkdir2(this.stateDir, { recursive: true });
+    await writeFile2(metaPath, JSON.stringify({ topics, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2), "utf-8");
     log.debug(`saved ${topics.length} topic scores`);
   }
   /**
    * Load topic scores from meta.json.
    */
   async loadTopics() {
-    const metaPath = path5.join(this.stateDir, "topics.json");
+    const metaPath = path4.join(this.stateDir, "topics.json");
     try {
-      const raw = await readFile3(metaPath, "utf-8");
+      const raw = await readFile2(metaPath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return { topics: [], updatedAt: null };
@@ -5953,6 +6206,7 @@ export {
   setCachedQmdSearch,
   lintWorkspaceFiles,
   rotateMarkdownFileToArchive,
+  isConsolidationOperator,
   confidenceTier,
   openBetterSqlite3,
   MEMORY_PROJECTION_SCHEMA_VERSION,