recallnest 3.0.0 → 4.0.0

package/src/flock.ts

@@ -0,0 +1,97 @@
+/**
+ * Kernel advisory file locks (flock(2)) reached through bun:ffi, for distill-lock.ts.
+ *
+ * Why the kernel: a flock belongs to an open file description, and the kernel drops it when the
+ * last descriptor closes — including when the holding process exits or is SIGKILLed. So "is the
+ * holder still alive" is answered by the kernel, and nobody ever has to decide that a lock is
+ * stale and take it away from its holder.
+ *
+ * Only `flock(int, int)` and the errno accessor are called; both are non-variadic, so the FFI
+ * signatures below match the C ABI on x86-64 and arm64 alike (fcntl/open are variadic and would
+ * not be safe to declare this way on Apple arm64, which passes variadic arguments on the stack).
+ *
+ * - Linux (glibc): `flock` and `__errno_location` in libc.so.6. LOCK_EX=2, LOCK_NB=4, LOCK_UN=8,
+ *   EWOULDBLOCK=EAGAIN=11, EINTR=4, O_CLOEXEC=0o2000000.
+ * - macOS: `flock` and `__error` in libSystem.B.dylib (served from the dyld shared cache, so
+ *   dlopen by its install name works without the file on disk). Same LOCK_* values
+ *   (<sys/fcntl.h>), EWOULDBLOCK=EAGAIN=35, EINTR=4, O_CLOEXEC=0x01000000.
+ */
+
+import { dlopen, FFIType, read, type Pointer } from "bun:ffi";
+import { constants, openSync } from "node:fs";
+
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const LOCK_UN = 8;
+const EINTR = 4;
+
+interface Platform {
+  libPath: string;
+  errnoSymbol: "__errno_location" | "__error";
+  ewouldblock: number;
+  oCloexec: number;
+}
+
+function platform(): Platform {
+  if (process.platform === "linux") {
+    return { libPath: "libc.so.6", errnoSymbol: "__errno_location", ewouldblock: 11, oCloexec: 0o2000000 };
+  }
+  if (process.platform === "darwin") {
+    return { libPath: "/usr/lib/libSystem.B.dylib", errnoSymbol: "__error", ewouldblock: 35, oCloexec: 0x01000000 };
+  }
+  throw new Error(`cross-process locks need flock(2); platform '${process.platform}' is not supported`);
+}
+
+interface Flock {
+  flock: (fd: number, op: number) => number;
+  errno: () => number;
+  ewouldblock: number;
+  oCloexec: number;
+}
+
+let loaded: Flock | null = null;
+
+function lib(): Flock {
+  if (loaded) return loaded;
+  const p = platform();
+  const handle = dlopen(p.libPath, {
+    flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+    [p.errnoSymbol]: { args: [], returns: FFIType.ptr },
+  });
+  const symbols = handle.symbols as unknown as Record<string, (...args: number[]) => unknown>;
+  const flockFn = symbols.flock!;
+  const errnoFn = symbols[p.errnoSymbol]!;
+  loaded = {
+    flock: (fd, op) => flockFn(fd, op) as number,
+    errno: () => read.i32(errnoFn() as Pointer, 0),
+    ewouldblock: p.ewouldblock,
+    oCloexec: p.oCloexec,
+  };
+  return loaded;
+}
+
+/**
+ * Open (creating if needed) a lock file for reading and writing, close-on-exec so a child
+ * process can never inherit the descriptor and with it the lock.
+ */
+export function openLockFile(path: string): number {
+  return openSync(path, constants.O_RDWR | constants.O_CREAT | lib().oCloexec, 0o644);
+}
+
+/** Non-blocking exclusive flock. true = acquired, false = another open file description holds it. */
+export function tryLockExclusive(fd: number): boolean {
+  const l = lib();
+  for (;;) {
+    if (l.flock(fd, LOCK_EX | LOCK_NB) === 0) return true;
+    // Read errno immediately: nothing runs between the FFI return and this call.
+    const errno = l.errno();
+    if (errno === l.ewouldblock) return false;
+    if (errno === EINTR) continue;
+    throw new Error(`flock(LOCK_EX|LOCK_NB) failed on fd ${fd}: errno ${errno}`);
+  }
+}
+
+/** Explicit unlock. Closing the descriptor also unlocks; this is for clarity before close. */
+export function unlockFd(fd: number): void {
+  lib().flock(fd, LOCK_UN);
+}

package/src/forget-engine.ts

@@ -1,19 +1,57 @@
 /**
- * Forget Engine — Ethics-aware memory deletion with full cascade.
+ * Forget Engine — ethics-aware memory deletion, with a read-back.
  *
- * Philosophy: "The right to forget" — memories can be explicitly removed,
- * but the process must be auditable, reversible (via evidence export),
- * and propagated to all derived artifacts (KG triples, pins, evolution chains).
+ * Philosophy: "The right to forget" — a memory can be explicitly removed, the
+ * removal is auditable, and it reaches the places this engine knows the memory
+ * left a copy or a pointer in.
  *
- * Sequence:
- * 1. Fetch target memory
+ * Sequence (the step comments in forgetMemory() carry the same numbers and names;
+ * forget-cascade-completeness.test.ts fails if the two lists drift apart):
+ * 1. Fetch target
  * 2. Privacy tier check (durable requires explicit confirm)
- * 3. Evidence export (snapshot before deletion for audit trail)
- * 4. KG triple cleanup (via KGStore.deleteBySource)
- * 5. Pin archive (mark related pins as forgotten)
- * 6. Cascade demote (related memories via cascade-forget.ts)
- * 7. Primary delete (remove from LanceDB)
- * 8. Audit log (record the forget operation)
+ * 3. Evidence snapshot (returned to the caller, not persisted)
+ * 4. Trigger rows (delete its rows in memory_triggers; a failure aborts before anything is touched)
+ * 5. Pin archive (delete the indexed copy of each pin made from it, then move the pin files out of data/pins; a failure aborts, the primary row stays)
+ * 6. KG triples (KGStore.deleteBySource; a failure is logged and the forget continues)
+ * 7. Cascade demote (related memories lose importance, via cascade-forget.ts)
+ * 8. Evolution breadcrumb (mark the row archived with a "forgotten:" note just before deleting it)
+ * 9. Primary delete (remove the row from LanceDB)
+ * 10. Read-back (fetch the id again; count what is left in triggers, pins, pin index rows and KG)
+ * 11. Audit log (record the operation and what the read-back found)
+ *
+ * Steps 4 and 5 fail closed and run before the primary delete: once the row is
+ * gone, forget() can no longer find the id, so whatever they left behind would
+ * have no tool to remove it.
+ *
+ * When a forget stops part-way:
+ * - at step 4, nothing has been changed;
+ * - at step 5, the memory is untouched and still active, but its trigger rows, pin
+ *   index rows or some pin files may already be gone;
+ * - at step 9 or 10 (the delete threw, or the row is still readable afterwards), the
+ *   row stays in the table marked archived with the "forgotten:" note — default recall
+ *   skips it and the memory-file reconciler treats its text as forgotten — while its
+ *   triggers, pins and KG triples are gone. That is a soft forget; running forget
+ *   again finishes it.
+ * Whenever something was already changed, the error says what, and a
+ * `forget_incomplete` audit entry records it. That entry deliberately carries no
+ * `norm=` fingerprint and is not a `forget` operation, so the reconciler does not
+ * read an aborted forget as a completed one.
+ *
+ * Not covered — forgetting a memory does NOT touch:
+ * - memories derived from it by dream / consolidation (insights, patterns), or
+ *   evolution references held by other rows (supersedes, sourceMemories, consolidatedInto);
+ * - brief assets and exports that quoted it;
+ * - document slices or transcript chunks in other scopes that say the same thing;
+ * - the archived pin files themselves (data/archive/forgotten-pins keeps the snippet so a
+ *   mistaken forget can be undone; remove the file by hand if the content has to go);
+ * - older LanceDB table versions, backups, and the session transcripts it came from.
+ * The audit entry of a completed forget carries the normalized text fingerprint so
+ * that the memory-file reconciler does not put the same text back (memory-reconcile.ts).
+ *
+ * Until 2026-10-05 this header promised propagation to "all derived artifacts
+ * (KG triples, pins, evolution chains)" while the body had no pin code at all, the
+ * memory_triggers side table (added 2026-09-22) was never cleaned, and nothing
+ * read back after the delete.
  */
 
 import type { MemoryStore, MemoryEntry } from "./store.js";
@@ -22,6 +60,7 @@ import type { AuditLogger } from "./audit-log.js";
 import { parsePrivacyTier, type PrivacyTier } from "./memory-schema.js";
 import { parseEvolution, patchEvolution } from "./memory-evolution.js";
 import { cascadeForget, type CascadeForgetConfig, DEFAULT_CASCADE_FORGET_CONFIG } from "./cascade-forget.js";
+import { textFingerprint } from "./text-fingerprint.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -51,6 +90,38 @@ export interface ForgetEvidence {
   reason?: string;
 }
 
+/** The places the read-back looks. */
+export type ForgetLayer = "primary" | "triggers" | "pins" | "pin-index" | "kg";
+
+/**
+ * What the read-back after the delete found.
+ * A count is `null` when that layer is not wired in, or when counting it failed; the
+ * second case is also listed in `unverified`, so "not there" and "could not look" stay apart.
+ */
+export interface ForgetVerification {
+  /** gone = the id no longer resolves; present = it still does; unverified = the read itself failed */
+  primary: "gone" | "present" | "unverified";
+  triggerRowsLeft: number | null;
+  pinsLeft: number | null;
+  pinIndexRowsLeft: number | null;
+  kgTriplesLeft: number | null;
+  /** Layers whose check threw. Empty when everything that could be checked was checked. */
+  unverified: ForgetLayer[];
+}
+
+/**
+ * One word for a read-back. `clean` is the only state in which the forget can be
+ * reported as done without a caveat: the id is gone, nothing was found left over,
+ * and no check failed.
+ */
+export function summarizeVerification(v: ForgetVerification): "clean" | "leftovers" | "unverified" | "present" {
+  if (v.primary === "present") return "present";
+  const left = (v.triggerRowsLeft ?? 0) + (v.pinsLeft ?? 0) + (v.pinIndexRowsLeft ?? 0) + (v.kgTriplesLeft ?? 0);
+  if (left > 0) return "leftovers";
+  if (v.unverified.length > 0) return "unverified";
+  return "clean";
+}
+
 export interface ForgetResult {
   /** Whether the memory was successfully forgotten */
   success: boolean;
@@ -58,19 +129,163 @@ export interface ForgetResult {
   memoryId: string;
   /** Evidence snapshot (for audit/undo) */
   evidence?: ForgetEvidence;
-  /** Number of KG triples removed */
+  /** Whether the KG cleanup ran without error */
   kgTriplesRemoved: boolean;
+  /** Rows removed from memory_triggers (null when no trigger store is wired in) */
+  triggerRowsRemoved: number | null;
+  /** Pin files moved to the archive (null when no pin archive is wired in) */
+  pinsArchived: number | null;
+  /** Indexed copies of those pins removed from the main table (null when the step was not reached) */
+  pinIndexRowsRemoved: number | null;
   /** Cascade demote results */
   cascadeResult: { demotedCount: number; demotedIds: string[] };
+  /** Read-back after the primary delete (absent when the forget stopped before deleting) */
+  verification?: ForgetVerification;
   /** Error message if failed */
   error?: string;
 }
 
+/** The slice of TriggerStore the forget engine needs. */
+export interface ForgetTriggerStore {
+  /**
+   * Delete every trigger row of this memory; resolves to the number of rows it counted just
+   * before deleting. A row that another process adds in between is not in that number, and
+   * when the number is 0 no delete is issued at all — the read-back (step 10) counts again.
+   */
+  deleteForMemory(memoryId: string): Promise<number>;
+  countForMemory(memoryId: string): Promise<number>;
+}
+
+/** Pin files made from a memory (memory-assets.ts: archivePinAssetsForMemory / findPinAssetsForMemory). */
+export interface ForgetPinArchive {
+  /**
+   * Move this memory's pin files out of the pins directory; returns how many were moved.
+   * If it fails after some files were already moved, the error it throws carries that number
+   * as `archivedCount` — otherwise the engine would report that nothing had been changed.
+   */
+  archiveForMemory(memoryId: string): number;
+  /** How many pin files made from this memory are still in the pins directory. */
+  countForMemory(memoryId: string): number;
+}
+
 export interface ForgetByIdDeps {
   store: MemoryStore;
   kgStore?: KGStore | null;
   auditLogger?: AuditLogger | null;
   cascadeConfig?: CascadeForgetConfig;
+  /** Omit to skip step 4 (callers that have no trigger side table). */
+  triggerStore?: ForgetTriggerStore | null;
+  /** Omit to skip the file half of step 5 (the indexed copies live in `store` and are always handled). */
+  pins?: ForgetPinArchive | null;
+}
+
+/** What a forget has already changed at the moment it stops or finishes. */
+interface ForgetProgress {
+  triggerRowsRemoved: number | null;
+  pinIndexRowsRemoved: number | null;
+  pinsArchived: number | null;
+  kgTriplesRemoved: boolean;
+  cascadeResult: { demotedCount: number; demotedIds: string[] };
+  breadcrumbWritten: boolean;
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** How many pin files a failed pin archive had already moved, when its error says so (see ForgetPinArchive). */
+function archivedCountOf(err: unknown): number | null {
+  if (typeof err !== "object" || err === null || !("archivedCount" in err)) return null;
+  const n = (err as { archivedCount: unknown }).archivedCount;
+  return typeof n === "number" && Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/** Quote a value so that it pastes into a POSIX shell command line as one argument. */
+function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_.:\/@%+=,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function countOrNa(n: number | null): string {
+  return n === null ? "n/a" : String(n);
+}
+
+function failed(memoryId: string, error: string, partial: Partial<ForgetResult> = {}): ForgetResult {
+  return {
+    success: false,
+    memoryId,
+    kgTriplesRemoved: false,
+    triggerRowsRemoved: null,
+    pinsArchived: null,
+    pinIndexRowsRemoved: null,
+    cascadeResult: { demotedCount: 0, demotedIds: [] },
+    error,
+    ...partial,
+  };
+}
+
+function resultFields(progress: ForgetProgress): Pick<ForgetResult, "kgTriplesRemoved" | "triggerRowsRemoved" | "pinsArchived" | "pinIndexRowsRemoved" | "cascadeResult"> {
+  return {
+    kgTriplesRemoved: progress.kgTriplesRemoved,
+    triggerRowsRemoved: progress.triggerRowsRemoved,
+    pinsArchived: progress.pinsArchived,
+    pinIndexRowsRemoved: progress.pinIndexRowsRemoved,
+    cascadeResult: progress.cascadeResult,
+  };
+}
+
+/** In plain words, what has already been changed. Empty when nothing has. */
+function describeProgress(progress: ForgetProgress): string[] {
+  const parts: string[] = [];
+  if (progress.triggerRowsRemoved) parts.push(`${progress.triggerRowsRemoved} trigger row(s) removed`);
+  if (progress.pinIndexRowsRemoved) parts.push(`${progress.pinIndexRowsRemoved} pin index row(s) removed`);
+  if (progress.pinsArchived) parts.push(`${progress.pinsArchived} pin file(s) archived`);
+  if (progress.kgTriplesRemoved) parts.push("KG cleanup ran");
+  if (progress.cascadeResult.demotedCount) parts.push(`${progress.cascadeResult.demotedCount} related memories demoted`);
+  if (progress.breadcrumbWritten) parts.push('row marked archived with a "forgotten:" note');
+  return parts;
+}
+
+/**
+ * Rows in the main table that index a pin made from this memory. `pin_memory` writes one
+ * per pin (asset-sync.ts: scope `asset:<pin id>`, text = title + summary + snippet,
+ * metadata.originalMemoryId), and search returns them like any other row.
+ */
+async function findPinIndexRows(store: MemoryStore, memoryId: string): Promise<MemoryEntry[]> {
+  const rows = await store.list(["asset"], undefined, Number.MAX_SAFE_INTEGER, 0);
+  return rows.filter((row) => {
+    if (!row.scope.startsWith("asset:")) return false;
+    try {
+      const meta = JSON.parse(row.metadata || "{}") as Record<string, unknown>;
+      return meta.assetType === "pinned-memory" && meta.originalMemoryId === memoryId;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Step 10. Checks by id only: every retrieval path can return a row only if it is still in the table. */
+async function readBack(deps: ForgetByIdDeps, id: string, scopeFilter?: string[]): Promise<ForgetVerification> {
+  const { store, kgStore, triggerStore, pins } = deps;
+  const unverified: ForgetLayer[] = [];
+  const check = async <T>(layer: ForgetLayer, look: () => T | Promise<T>): Promise<T | null> => {
+    try {
+      return await look();
+    } catch (err) {
+      unverified.push(layer);
+      console.error(`[recallnest] Read-back of ${layer} failed after forget:`, errorMessage(err));
+      return null;
+    }
+  };
+
+  const row = await check("primary", async () => ((await store.get(id, scopeFilter)) ? "present" as const : "gone" as const));
+  const triggerRowsLeft = triggerStore ? await check("triggers", () => triggerStore.countForMemory(id)) : null;
+  const pinsLeft = pins ? await check("pins", () => pins.countForMemory(id)) : null;
+  const pinIndexRowsLeft = await check("pin-index", async () => (await findPinIndexRows(store, id)).length);
+  const kgTriplesLeft = kgStore && typeof kgStore.getTriplesBySourceMemories === "function"
+    ? await check("kg", async () => (await kgStore.getTriplesBySourceMemories([id])).get(id)?.length ?? 0)
+    : null;
+
+  return { primary: row ?? "unverified", triggerRowsLeft, pinsLeft, pinIndexRowsLeft, kgTriplesLeft, unverified };
 }
 
 // ---------------------------------------------------------------------------
@@ -81,34 +296,22 @@ export async function forgetMemory(
   deps: ForgetByIdDeps,
   request: ForgetRequest,
 ): Promise<ForgetResult> {
-  const { store, kgStore, auditLogger, cascadeConfig } = deps;
+  const { store, kgStore, auditLogger, cascadeConfig, triggerStore, pins } = deps;
   const { memoryId, confirm, reason, scopeFilter } = request;
 
   // 1. Fetch target
   const entry = await store.get(memoryId, scopeFilter);
   if (!entry) {
-    return {
-      success: false,
-      memoryId,
-      kgTriplesRemoved: false,
-      cascadeResult: { demotedCount: 0, demotedIds: [] },
-      error: `Memory ${memoryId} not found`,
-    };
+    return failed(memoryId, `Memory ${memoryId} not found`);
   }
 
   // 2. Privacy tier check
   const privacyTier = parsePrivacyTier(entry.metadata);
   if (privacyTier === "durable" && !confirm) {
-    return {
-      success: false,
-      memoryId: entry.id,
-      kgTriplesRemoved: false,
-      cascadeResult: { demotedCount: 0, demotedIds: [] },
-      error: `Memory ${entry.id} has privacy tier "durable" — set confirm=true to proceed`,
-    };
+    return failed(entry.id, `Memory ${entry.id} has privacy tier "durable" — set confirm=true to proceed`);
   }
 
-  // 3. Evidence export (snapshot before deletion)
+  // 3. Evidence snapshot
   const evolution = parseEvolution(entry.metadata, entry.timestamp);
   const evidence: ForgetEvidence = {
     entry: { ...entry },
@@ -118,82 +321,160 @@ export async function forgetMemory(
     reason,
   };
 
-  // 4. KG triple cleanup
-  let kgTriplesRemoved = false;
+  const progress: ForgetProgress = {
+    triggerRowsRemoved: null,
+    pinIndexRowsRemoved: null,
+    pinsArchived: null,
+    kgTriplesRemoved: false,
+    cascadeResult: { demotedCount: 0, demotedIds: [] },
+    breadcrumbWritten: false,
+  };
+
+  // Stops the forget after something may already have been changed: says what in the error,
+  // and leaves a `forget_incomplete` audit entry (see the file header for why it is not a `forget`).
+  const stopIncomplete = (
+    stage: "pin-archive" | "delete" | "read-back",
+    problem: string,
+    nextStep: string,
+    extra: Partial<ForgetResult> = {},
+  ): ForgetResult => {
+    const done = describeProgress(progress);
+    if (done.length > 0) {
+      try {
+        auditLogger?.log({
+          operation: "forget_incomplete",
+          scope: entry.scope,
+          memoryId: entry.id,
+          actor: "system",
+          details: `stage=${stage} triggers=${countOrNa(progress.triggerRowsRemoved)} pins=${countOrNa(progress.pinsArchived)} pinIndex=${countOrNa(progress.pinIndexRowsRemoved)} kg=${progress.kgTriplesRemoved ? "ran" : "no"} cascade=${progress.cascadeResult.demotedCount} breadcrumb=${progress.breadcrumbWritten ? "yes" : "no"} error=${problem}`,
+        });
+      } catch (err) {
+        console.error("[recallnest] Audit log failed during an incomplete forget:", errorMessage(err));
+      }
+    }
+    const already = done.length > 0 ? ` Already done and not rolled back: ${done.join("; ")}.` : "";
+    return failed(entry.id, `${problem}${already} ${nextStep}`, { evidence, ...resultFields(progress), ...extra });
+  };
+
+  // 4. Trigger rows — fail closed (see the file header)
+  if (triggerStore) {
+    try {
+      progress.triggerRowsRemoved = await triggerStore.deleteForMemory(entry.id);
+    } catch (err) {
+      return failed(entry.id, `Trigger cleanup failed: ${errorMessage(err)}. Nothing was deleted; retry the forget.`, { evidence });
+    }
+  }
+
+  // 5. Pin archive — fail closed. A pin is a file under data/pins and an indexed copy in the
+  //    main table; the copy goes first, because it is the half that search returns.
+  try {
+    const indexRows = await findPinIndexRows(store, entry.id);
+    progress.pinIndexRowsRemoved = 0;
+    for (const row of indexRows) {
+      // false: the row was already gone (removed between the listing above and this call), so it is not counted
+      if (await store.delete(row.id)) progress.pinIndexRowsRemoved += 1;
+    }
+    if (pins) progress.pinsArchived = pins.archiveForMemory(entry.id);
+  } catch (err) {
+    // The archive may have moved some files before it failed. Without this, the error below
+    // and the audit entry would both say that nothing had been changed.
+    const movedBeforeFailing = archivedCountOf(err);
+    if (movedBeforeFailing !== null) progress.pinsArchived = movedBeforeFailing;
+    const restoreTriggers = progress.triggerRowsRemoved
+      ? ` To keep the memory instead, restore its trigger rows with \`triggers-backfill --rebuild --apply --scope ${shellQuote(entry.scope)}\`.`
+      : "";
+    return stopIncomplete(
+      "pin-archive",
+      `Pin archive failed: ${errorMessage(err)}.`,
+      `The memory itself was not deleted and is still active. Retry the forget.${restoreTriggers}`,
+    );
+  }
+
+  // 6. KG triples
   if (kgStore) {
     try {
       await kgStore.deleteBySource(entry.id);
-      kgTriplesRemoved = true;
+      progress.kgTriplesRemoved = true;
     } catch (err) {
-      console.error("[recallnest] KG cleanup failed during forget:", err instanceof Error ? err.message : String(err));
+      console.error("[recallnest] KG cleanup failed during forget:", errorMessage(err));
     }
   }
 
-  // 5. Cascade demote (related memories get importance reduction)
-  let cascadeResult = { demotedCount: 0, demotedIds: [] as string[] };
+  // 7. Cascade demote
   try {
-    cascadeResult = await cascadeForget(
+    progress.cascadeResult = await cascadeForget(
       store,
       { id: entry.id, vector: entry.vector, scope: entry.scope },
       cascadeConfig ?? DEFAULT_CASCADE_FORGET_CONFIG,
     );
   } catch (err) {
-    console.error("[recallnest] Cascade demote failed during forget:", err instanceof Error ? err.message : String(err));
+    console.error("[recallnest] Cascade demote failed during forget:", errorMessage(err));
   }
 
-  // 6. Mark evolution status as "forgotten" before delete (audit breadcrumb)
+  // 8. Evolution breadcrumb
   try {
     const patchedMetadata = patchEvolution(entry.metadata, {
       status: "archived" as any,
       evolutionNote: `forgotten: ${reason || "user request"}`,
     });
-    await store.update(entry.id, { metadata: patchedMetadata }, scopeFilter);
+    progress.breadcrumbWritten = (await store.update(entry.id, { metadata: patchedMetadata }, scopeFilter)) !== null;
   } catch (err) {
-    console.error("[recallnest] Evolution patch failed during forget:", err instanceof Error ? err.message : String(err));
+    console.error("[recallnest] Evolution patch failed during forget:", errorMessage(err));
   }
 
-  // 7. Primary delete
+  const rowState = () => (progress.breadcrumbWritten
+    ? 'The row is still in the table, marked archived with a "forgotten:" note: default recall skips it and the memory-file reconciler treats its text as forgotten.'
+    : "The row is still in the table and still active.");
+
+  // 9. Primary delete
   try {
     await store.delete(entry.id, scopeFilter);
   } catch (err) {
-    return {
-      success: false,
-      memoryId: entry.id,
-      evidence,
-      kgTriplesRemoved,
-      cascadeResult,
-      error: `Delete failed: ${err instanceof Error ? err.message : String(err)}`,
-    };
+    return stopIncomplete("delete", `Delete failed: ${errorMessage(err)}.`, `${rowState()} Run forget again to finish.`);
   }
 
-  // 8. Audit log
+  // 10. Read-back
+  const verification = await readBack(deps, entry.id, scopeFilter);
+  if (verification.primary === "present") {
+    return stopIncomplete(
+      "read-back",
+      `Delete reported success but memory ${entry.id} is still readable.`,
+      `${rowState()} Run forget again to finish.`,
+      { verification },
+    );
+  }
+
+  // 11. Audit log
   try {
     auditLogger?.log({
       operation: "forget",
       scope: entry.scope,
       memoryId: entry.id,
       actor: "system",
-      details: `tier=${privacyTier} reason=${reason || "none"} cascade=${cascadeResult.demotedCount}`,
+      // norm=<归一文本指纹> 放最前：删的是这一行，要忘的是这段文字。记忆文件对账据此不把同文的另一行
+      // 恢复回来（memory-reconcile.ts），只认 id 的话换个空白就绕过去了。
+      // reason 是自由文本，放最后：details 超 200 字会被截断，前面的字段不能被它挤掉。
+      details: `norm=${textFingerprint(entry.text)} tier=${privacyTier} triggers=${countOrNa(progress.triggerRowsRemoved)} pins=${countOrNa(progress.pinsArchived)} pinIndex=${countOrNa(progress.pinIndexRowsRemoved)} verify=${summarizeVerification(verification)} cascade=${progress.cascadeResult.demotedCount} reason=${reason || "none"}`,
     });
-    if (cascadeResult.demotedCount > 0) {
+    if (progress.cascadeResult.demotedCount > 0) {
       auditLogger?.log({
         operation: "cascade_forget",
         scope: entry.scope,
         memoryId: entry.id,
         actor: "system",
-        details: `demoted ${cascadeResult.demotedCount} related memories: ${cascadeResult.demotedIds.map(id => id.slice(0, 8)).join(",")}`,
+        details: `demoted ${progress.cascadeResult.demotedCount} related memories: ${progress.cascadeResult.demotedIds.map(id => id.slice(0, 8)).join(",")}`,
       });
     }
   } catch (err) {
-    console.error("[recallnest] Audit log failed during forget:", err instanceof Error ? err.message : String(err));
+    console.error("[recallnest] Audit log failed during forget:", errorMessage(err));
   }
 
   return {
     success: true,
     memoryId: entry.id,
     evidence,
-    kgTriplesRemoved,
-    cascadeResult,
+    ...resultFields(progress),
+    verification,
   };
 }
 
@@ -248,9 +529,12 @@ export async function forgetByScope(
     }
   }
 
-  // Bulk KG scope cleanup
+  // Bulk KG scope cleanup — only when every entry was forgotten. An entry whose forget stopped
+  // (its trigger or pin cleanup failed) is still an active memory, and wiping the whole scope
+  // would strip its triples anyway. The entries that were forgotten have already lost theirs
+  // in step 6 of forgetMemory (deleteBySource).
   let kgScopeCleared = false;
-  if (kgStore) {
+  if (kgStore && failedCount === 0) {
     try {
       await kgStore.deleteByScope(scope);
       kgScopeCleared = true;

package/src/gateway-server.ts

@@ -44,6 +44,7 @@ import { homedir } from "node:os";
 import { join, isAbsolute } from "node:path";
 import { execFile } from "node:child_process";
 import * as envConfig from "./env-config.js";
+import { HTTP_WRITE_IDLE_TIMEOUT_S } from "./store-write-budget.js";
 
 const HOME = homedir();
 const PORT = clampInt(envConfig.gatewayPortRaw(), 8791, 1, 65535);
@@ -195,6 +196,9 @@ function fileSearch(query: string, scope: string, limit: number): Promise<FileHi
 // ── server ───────────────────────────────────────────────────────────────────
 const server = Bun.serve({
   port: PORT,
+  // Writes can wait up to 30 s for store-write before they start; Bun's 10 s default would drop
+  // the connection while the handler still commits.
+  idleTimeout: HTTP_WRITE_IDLE_TIMEOUT_S,
   hostname: HOST,
   async fetch(request) {
     const id = randomUUID().slice(0, 8);