@remnic/core 9.35.2 → 9.35.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.35.2",
+  "version": "9.35.4",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3086,7 +3086,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.35.2"
+    "@remnic/coding-graph": "^9.35.4"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-http.ts

@@ -66,6 +66,12 @@ export interface AccessHttpReadinessState {
   ready: boolean;
   warmupAttempts: number;
   lastError?: string | null;
+  /**
+   * True when the standalone init gate opened before search warm-up completed
+   * (issue #2215): the service is functional (recall serves via fallback
+   * retrieval), so health answers 200 with degraded info instead of 503.
+   */
+  degraded?: boolean;
 }
 
 export interface EngramAccessHttpServerOptions {
@@ -801,18 +807,13 @@ export class EngramAccessHttpServer {
     }
 
     if (req.method === "GET" && pathname === "/engram/v1/health") {
-      const readiness = this.readiness();
-      if (!readiness.ready) {
+      const { ready, warmupAttempts, lastError } = this.readiness();
+      if (!ready) {
         this.respondJson(res, 503, {
-          ok: false,
-          ready: false,
-          warmupAttempts: readiness.warmupAttempts,
-          lastError: readiness.lastError ?? null,
-          code: "not_ready",
+          ok: false, ready: false, warmupAttempts, lastError: lastError ?? null, code: "not_ready",
         });
         return;
       }
-
     }
 
     // Run any host-supplied pre-auth request handler. It runs AFTER the
@@ -888,7 +889,11 @@ export class EngramAccessHttpServer {
     }
 
     if (req.method === "GET" && pathname === "/engram/v1/health") {
-      this.respondJson(res, 200, await this.service.health());
+      const { degraded, warmupAttempts, lastError } = this.readiness();
+      const health = await this.service.health();
+      this.respondJson(res, 200, degraded !== true ? health : {
+        ...health, degraded: true, warmupAttempts, lastError: lastError ?? null,
+      });
       return;
     }
     if (req.method === "GET" && pathname === "/engram/v1/capabilities") return respondLcmCompactionCapabilitiesHttp(res);

package/src/binary-lifecycle/pipeline.ts

@@ -20,6 +20,16 @@ import { readManifest, writeManifest } from "./manifest.js";
 import { scanForBinaries } from "./scanner.js";
 import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
+import {
+  HistoricalEntityCanonicalIdCache,
+  canonicalizeEntityRefFrontmatter,
+  classifyEntityRefWritePath,
+  repairContentAfterJournalMove,
+  requestEntityCanonicalIdReconcile,
+} from "../storage/entity-canonical-id-references.js";
+
+// Write-boundary journal cache for redirect rewrites (issue #2213).
+const historicalIdCache = new HistoricalEntityCanonicalIdCache();
 
 /**
  * True when `mdPath` is an active recall-corpus memory file under `memoryDir`
@@ -319,7 +329,48 @@ async function stageRedirect(
     let writeFailCount = 0;
     for (const update of updates) {
       try {
-        await writeMarkdownFile(update.mdPath, update.content);
+        // Whole-record rewrite of bytes read earlier (issue #2213): for
+        // memory-tier records, resolve the frontmatter entityRef through the
+        // CURRENT journal at the write and REPAIR afterwards — writing back
+        // the as-read bytes could revert a rewrite a peer migration performed
+        // since the read. findMarkdownFiles also surfaces transcripts,
+        // profiles, and other Markdown outside the migration's scope: those
+        // keep their bytes (plus the redirect) untouched, and entities/ pages
+        // get the bounded reconcile marker instead — their migrated surface
+        // is relationship targets, not an entityRef frontmatter field.
+        const stateDir = path.join(memoryDir, "state");
+        const kind = classifyEntityRefWritePath(memoryDir, update.mdPath);
+        if (kind === "memory") {
+          const idsAtWrite = historicalIdCache.get(stateDir);
+          const written = canonicalizeEntityRefFrontmatter(update.content, idsAtWrite);
+          // Snapshot the ORIGINAL bytes: if repair fails after the write, the
+          // catch below reports a failed redirect, so the file must return to
+          // its pre-redirect state — a retry needs the original reference,
+          // and the skipped corpus bump means a warm cache would otherwise
+          // keep serving bytes that no longer match disk (AGENTS.md §14).
+          const originalBytes = await readMarkdownFile(update.mdPath).catch(() => null);
+          await writeMarkdownFile(update.mdPath, written);
+          try {
+            await repairContentAfterJournalMove({
+              stateDir,
+              cache: historicalIdCache,
+              idsAtWrite,
+              rawContent: update.content,
+              lastWritten: written,
+              rewrite: (next) => writeMarkdownFile(update.mdPath, next),
+            });
+          } catch (err) {
+            if (originalBytes !== null) {
+              await writeMarkdownFile(update.mdPath, originalBytes).catch(() => undefined);
+            }
+            throw err;
+          }
+        } else {
+          await writeMarkdownFile(update.mdPath, update.content);
+          if (kind === "entity") {
+            await requestEntityCanonicalIdReconcile(stateDir);
+          }
+        }
         // The redirect rewrote an on-disk memory file out-of-band (not through a
         // StorageManager mutation). Bump the corpus sentinel per write so a warm
         // hot-memories cache rescans — mid-batch too, never serving pre-redirect

package/src/consolidation-undo.ts

@@ -26,6 +26,7 @@ import { constants as fsConstants } from "node:fs";
 import type { StorageManager } from "./storage.js";
 import type { VersioningConfig } from "./page-versioning.js";
 import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
+import { requestEntityCanonicalIdReconcile } from "./storage/entity-canonical-id-references.js";
 import { getVersion } from "./page-versioning.js";
 
 /**
@@ -654,6 +655,9 @@ export async function runConsolidationUndo(options: {
         // restores would stay invisible to recall until an unrelated mutation or
         // restart (esp. with hotMemoriesCacheTtlMs: 0). Issue #1902, Codex Medium.
         bumpMemoryCorpusVersionForDir(memoryDir);
+        // Restored bytes predate the current migration journal and can carry
+        // legacy entity references (issue #2213) — request one reconcile pass.
+        await requestEntityCanonicalIdReconcile(path.join(memoryDir, "state"));
         result.restores.push({
           entry: p.entry,
           sourcePath: p.sourcePath,

package/src/curation/index.ts

@@ -10,6 +10,11 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { getCategoryDir, ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
 import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
+import {
+  HistoricalEntityCanonicalIdCache,
+  canonicalizeEntityRefFrontmatter,
+  repairContentAfterJournalMoveSync,
+} from "../storage/entity-canonical-id-references.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -444,6 +449,10 @@ function loadExistingMemories(memoryDir: string): Map<string, ExistingMemory> {
 
 // ── Writing ──────────────────────────────────────────────────────────────────
 
+// Curation writes raw frontmatter directly, so it is a write boundary for
+// entity references too (issue #2213): resolve through the target's journal.
+const historicalIdCache = new HistoricalEntityCanonicalIdCache();
+
 function writeStatement(stmt: CuratedStatement, memoryDir: string): string {
   const now = new Date();
   const dateDir = now.toISOString().split("T")[0];
@@ -454,8 +463,12 @@ function writeStatement(stmt: CuratedStatement, memoryDir: string): string {
 
   const fileName = `${stmt.category}-${Date.now()}-${stmt.id.slice(0, 8)}.md`;
   const filePath = path.join(dir, fileName);
+  const historicalIds = historicalIdCache.get(path.join(memoryDir, "state"));
 
-  const frontmatter = [
+  // Keep the caller's ORIGINAL ref in the raw form: repair-after-write must
+  // re-resolve from it, including the direction where a mapping was parked
+  // and the resolution falls back to the legacy claimant (issue #2213).
+  const rawBody = `${[
     "---",
     `id: ${stmt.id}`,
     `category: ${stmt.category}`,
@@ -471,14 +484,37 @@ function writeStatement(stmt: CuratedStatement, memoryDir: string): string {
     "---",
   ]
     .filter(Boolean)
-    .join("\n");
-
-  const body = `${frontmatter}\n\n${stmt.content}\n`;
+    .join("\n")}\n\n${stmt.content}\n`;
+  const body = canonicalizeEntityRefFrontmatter(rawBody, historicalIds);
 
   fs.writeFileSync(filePath, body);
+  // Post-write REPAIR (issue #2213): a peer process publishing the journal
+  // across this write would otherwise strand the reference — the corpus bump
+  // below no longer re-triggers the migration, and a parked mapping cannot be
+  // fixed after the fact by the reconcile pass. On repair exhaustion, remove
+  // the just-created file so the retryable error leaves no untracked partial
+  // statement (a retry would otherwise duplicate it).
+  try {
+    repairContentAfterJournalMoveSync({
+      stateDir: path.join(memoryDir, "state"),
+      cache: historicalIdCache,
+      idsAtWrite: historicalIds,
+      rawContent: rawBody,
+      lastWritten: body,
+      rewrite: (next) => fs.writeFileSync(filePath, next),
+    });
+  } catch (err) {
+    try {
+      fs.unlinkSync(filePath);
+    } catch {
+      // Best effort — the retryable repair error is the primary signal.
+    }
+    throw err;
+  }
   // Bump the corpus sentinel per write (out-of-band create) so a concurrent
   // same-process readAllMemories rescans and sees this statement immediately,
-  // never a stale/partial corpus mid-batch (Cursor Medium, #1902).
+  // never a stale/partial corpus mid-batch (Cursor Medium, #1902). AFTER the
+  // repair, so a rescan never captures pre-repair bytes.
   bumpMemoryCorpusVersionForDir(memoryDir);
   return filePath;
 }

package/src/lifecycle/tombstones.ts

@@ -835,6 +835,46 @@ export function collectRetiredMemoriesForRebuild(
   return retired;
 }
 
+/**
+ * One-shot write-time resurrection gate (issue #1579 / #2213). Looks up the
+ * fact's identity in the tombstone store and, on a match, downgrades the
+ * frontmatter to `pending_review` + `blockedBy` IN PLACE. ADD-ONLY: an
+ * already-blocked or terminal-status record is left untouched. Pure over its
+ * inputs (no I/O beyond the injected store) so both `writeMemory`'s gate and
+ * the chunk-repair re-gate share one lookup + apply.
+ */
+export function applyTombstoneResurrectionGate(
+  store: Pick<TombstoneStore, "lookup">,
+  fm: {
+    id: string;
+    status?: string;
+    blockedBy?: string;
+    tombstoneBlockTier?: TombstoneMatchTier;
+    entityRef?: string;
+    contentHash?: string;
+  },
+  query: {
+    normalizedText: string;
+    supersessionKeys: string[];
+    namespace: string;
+  },
+): TombstoneMatch | null {
+  if (fm.status === "pending_review" && fm.blockedBy) return null;
+  if (!(fm.status === undefined || fm.status === "active" || fm.status === "pending_review")) return null;
+  const match = store.lookup({
+    contentHash: fm.contentHash,
+    normalizedText: query.normalizedText,
+    ...(fm.entityRef ? { entityRef: fm.entityRef } : {}),
+    ...(query.supersessionKeys.length > 0 ? { supersessionKeys: query.supersessionKeys } : {}),
+    namespace: query.namespace,
+  });
+  if (!match) return null;
+  fm.status = "pending_review";
+  fm.blockedBy = match.tombstoneId;
+  fm.tombstoneBlockTier = match.matchedTier;
+  return match;
+}
+
 /**
  * Build the live-emission tombstone inputs for a single retired FACT — one
  * input per derived supersession key (or a single keyless record when no

package/src/maintenance/memory-governance.ts

@@ -6,6 +6,7 @@ import type { MemoryFile, MemoryStatus } from "../types.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
 import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
 import { assertPathInsideRoot } from "../utils/path-containment.js";
+import { requestEntityCanonicalIdReconcile } from "../storage/entity-canonical-id-references.js";
 
 export type MemoryGovernanceMode = "shadow" | "apply";
 export type MemoryGovernanceReasonCode =
@@ -1021,6 +1022,9 @@ export async function restoreMemoryGovernanceRun(
     // same-process or peer readAllMemories rescans mid-batch and never serves a
     // partially-restored corpus (Cursor Medium, #1902).
     bumpMemoryCorpusVersionForDir(options.memoryDir);
+    // Restored bytes predate the current migration journal and can carry
+    // legacy entity references (issue #2213) — request one reconcile pass.
+    await requestEntityCanonicalIdReconcile(path.join(options.memoryDir, "state"));
   }
 
   return {

package/src/page-versioning.ts

@@ -27,6 +27,10 @@ import {
 } from "node:fs/promises";
 import { ALL_CATEGORY_DIRS, RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
 import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
+import {
+  pathMayCarryEntityRefs,
+  requestEntityCanonicalIdReconcile,
+} from "./storage/entity-canonical-id-references.js";
 
 // ---------------------------------------------------------------------------
 // Public interfaces
@@ -342,9 +346,20 @@ export async function revertToVersion(
   // non-memory queue dirs (questions/). Use RECALL_FALLBACK_DIRS — a revert of a
   // questions/ page must NOT bump the recall corpus sentinel and force a rescan.
   const revertedTop = relPath(pagePath, resolvedMemoryDir).split(path.sep)[0];
-  if ((RECALL_FALLBACK_DIRS as readonly string[]).includes(revertedTop)) {
+  const inRecallTier = (RECALL_FALLBACK_DIRS as readonly string[]).includes(revertedTop);
+  if (inRecallTier) {
     bumpMemoryCorpusVersionForDir(resolvedMemoryDir);
   }
+  // A pre-migration snapshot can reintroduce a legacy entityRef — or, under
+  // entities/, a legacy relationship target rewriteRelationshipTargets had
+  // migrated — that the target's completed journal already renamed (issue
+  // #2213); the revert keeps the snapshot bytes faithful, so request one
+  // bounded reconcile pass instead. pathMayCarryEntityRefs is the migration's
+  // own scan scope (hot recall + cold + archive + entities), which is wider
+  // than the corpus bump above on purpose.
+  if (pathMayCarryEntityRefs(resolvedMemoryDir, pagePath)) {
+    await requestEntityCanonicalIdReconcile(path.join(resolvedMemoryDir, "state"));
+  }
   log.debug(`page-versioning: reverted ${pagePath} to version ${versionId}`);
 
   return version;

package/src/review/index.ts

@@ -9,6 +9,58 @@ import fs from "node:fs";
 import path from "node:path";
 import { getCategoryDir, ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
 import { bumpMemoryCorpusVersionForDir } from "../memory-corpus-version.js";
+import {
+  HistoricalEntityCanonicalIdCache,
+  canonicalizeEntityRefFrontmatter,
+  repairContentAfterJournalMoveSync,
+} from "../storage/entity-canonical-id-references.js";
+
+// Write-boundary journal cache for review-queue promotions (issue #2213).
+const historicalIdCache = new HistoricalEntityCanonicalIdCache();
+
+/**
+ * In-place raw rewrite under the uniform write-boundary rule (issue #2213):
+ * canonicalize the effective entityRef at the write and REPAIR when the
+ * journal moved across it — these rewrites re-serialize whole records, so an
+ * unrelated approve/dismiss/flag must not write a legacy ref back out. On
+ * repair exhaustion the ORIGINAL bytes are restored before the retryable
+ * error propagates: performReview bumps the corpus sentinel only after the
+ * action returns, so a half-applied rewrite would be invisible to a warm
+ * cache while the caller is told the action failed.
+ */
+function writeReviewFileCanonicalized(memoryDir: string, filePath: string, content: string): void {
+  const stateDir = path.join(memoryDir, "state");
+  const idsAtWrite = historicalIdCache.get(stateDir);
+  let originalBytes: string | null = null;
+  try {
+    originalBytes = fs.readFileSync(filePath, "utf8");
+  } catch {
+    originalBytes = null; // new file — rollback is removal
+  }
+  const written = canonicalizeEntityRefFrontmatter(content, idsAtWrite);
+  fs.writeFileSync(filePath, written, "utf8");
+  try {
+    repairContentAfterJournalMoveSync({
+      stateDir,
+      cache: historicalIdCache,
+      idsAtWrite,
+      rawContent: content,
+      lastWritten: written,
+      rewrite: (next) => fs.writeFileSync(filePath, next, "utf8"),
+    });
+  } catch (err) {
+    try {
+      if (originalBytes === null) {
+        fs.unlinkSync(filePath);
+      } else {
+        fs.writeFileSync(filePath, originalBytes, "utf8");
+      }
+    } catch {
+      // Best effort — the retryable repair error is the primary signal.
+    }
+    throw err;
+  }
+}
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -295,13 +347,16 @@ function approveItem(
   const fm = parseFrontmatter(content);
   if (!fm) return { itemId, action: "approve", message: "Could not parse frontmatter" };
 
-  // Issue #1579 — when approving a tombstone-blocked memory, fire the
-  // revocation hook so the content is re-allowed (append-only log: a
-  // `kind: "revocation"` entry supersedes the tombstone at lookup). Clear
-  // blockedBy/tombstoneBlockTier on the promoted memory so it is fully
-  // active. Fire-and-forget: a hook failure never fails the approval.
+  // Issue #1579 — approving a tombstone-blocked memory fires the revocation
+  // hook so the content is re-allowed (append-only log: a `kind: "revocation"`
+  // entry supersedes the tombstone at lookup). Deferred until the approval's
+  // writes commit (Codex P2, round 19): revoking before the promote left a
+  // failed repair with the non-resurrection guard already destroyed, letting
+  // a later extraction resurrect the content. Fire-and-forget once invoked:
+  // a hook failure never fails the approval.
   const blockedBy = typeof fm.blockedBy === "string" ? fm.blockedBy : null;
-  if (blockedBy && options.onApproveBlockedMemory) {
+  const fireBlockedRevocation = (): void => {
+    if (!blockedBy || !options.onApproveBlockedMemory) return;
     try {
       const maybe = options.onApproveBlockedMemory(blockedBy, itemId);
       if (maybe && typeof (maybe as Promise<void>).then === "function") {
@@ -310,7 +365,7 @@ function approveItem(
     } catch {
       /* fire-and-forget — never fail the approval (gotcha #13) */
     }
-  }
+  };
 
   const updatedContent = updateFrontmatterFields(content, {
     confidence: "0.9",
@@ -324,7 +379,8 @@ function approveItem(
   });
 
   if (found.location === "category") {
-    fs.writeFileSync(found.filePath, updatedContent, "utf8");
+    writeReviewFileCanonicalized(memoryDir, found.filePath, updatedContent);
+    fireBlockedRevocation();
     return {
       itemId,
       action: "approve",
@@ -342,10 +398,38 @@ function approveItem(
   const outputPath = path.join(targetDir, dateDir, path.basename(found.filePath));
 
   ensureSafeDirectory(rootReal, path.dirname(outputPath));
-  const promotedPath = writeFileWithoutClobber(outputPath, updatedContent, itemId);
+  // The suggestions/review queue dirs sit OUTSIDE the migration's reference
+  // scan, so a queued pre-migration item can still carry a legacy entityRef
+  // (issue #2213): promote it canonicalized against the target journal, and
+  // REPAIR when the journal moved across the write.
+  const reviewStateDir = path.join(memoryDir, "state");
+  const idsAtWrite = historicalIdCache.get(reviewStateDir);
+  const promotedWritten = canonicalizeEntityRefFrontmatter(updatedContent, idsAtWrite);
+  const promotedPath = writeFileWithoutClobber(outputPath, promotedWritten, itemId);
+  try {
+    repairContentAfterJournalMoveSync({
+      stateDir: reviewStateDir,
+      cache: historicalIdCache,
+      idsAtWrite,
+      rawContent: updatedContent,
+      lastWritten: promotedWritten,
+      rewrite: (next) => fs.writeFileSync(promotedPath, next, "utf8"),
+    });
+  } catch (err) {
+    // Roll back so a retried approve does not clobber-fail against a partial
+    // promotion; the queue entry survives untouched (Bugbot).
+    try {
+      fs.unlinkSync(promotedPath);
+    } catch {
+      // Best effort — the retryable repair error below is the primary signal.
+    }
+    throw err;
+  }
 
-  // Remove from review
+  // Remove from review, THEN revoke: the guard only falls once the approval
+  // has fully committed (promoted file repaired + queue entry gone).
   fs.unlinkSync(found.filePath);
+  fireBlockedRevocation();
 
   return {
     itemId,
@@ -372,13 +456,13 @@ function dismissItem(
   }
 
   const content = fs.readFileSync(found.filePath, "utf8");
-  fs.writeFileSync(
+  writeReviewFileCanonicalized(
+    memoryDir,
     found.filePath,
     updateFrontmatterFields(content, {
       reviewDismissed: "true",
       reviewDismissedAt: new Date().toISOString(),
     }),
-    "utf8",
   );
   return {
     itemId,
@@ -403,7 +487,7 @@ function flagItem(
     flagged: "true",
     flaggedAt: new Date().toISOString(),
   });
-  fs.writeFileSync(found.filePath, fixed);
+  writeReviewFileCanonicalized(memoryDir, found.filePath, fixed);
   return {
     itemId,
     action: "flag",