@remnic/core 9.7.14 → 9.8.0

package/src/buffer-surprise-trigger.test.ts

@@ -22,6 +22,7 @@ import type { BufferState, BufferTurn } from "./types.js";
 
 class FakeStorage {
   public saved: BufferState | null = null;
+  public saveCount = 0;
 
   constructor(private readonly initial: BufferState) {}
 
@@ -30,6 +31,7 @@ class FakeStorage {
   }
 
   async saveBuffer(state: BufferState): Promise<void> {
+    this.saveCount += 1;
     this.saved = structuredClone(state);
   }
 }
@@ -355,6 +357,7 @@ async function assertProbeRejectionHandled(
     bufferSurpriseThreshold: 0.35,
     bufferMaxTurns: 5,
     triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
   });
   const buffer = new SmartBuffer(config, storage as any, probe);
 
@@ -476,6 +479,7 @@ test("flag on: probe that never resolves is timed out, turn is still saved", asy
     bufferSurpriseProbeTimeoutMs: 30,
     bufferMaxTurns: 5,
     triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
   });
   const buffer = new SmartBuffer(config, storage as any, probe);
 
@@ -523,6 +527,7 @@ test("flag on: slow probe does not hold the buffer mutation queue", async () =>
     bufferSurpriseProbeTimeoutMs: 1000,
     bufferMaxTurns: 5,
     triggerMode: "smart",
+    bufferSaveDebounceMs: 0,
   });
   const buffer = new SmartBuffer(config, storage as any, probe);
 
@@ -750,3 +755,39 @@ test("flag on: stale snapshot clears do not mark live turns as freshly extracted
     "a skipped stale-snapshot clear must not advance extraction metadata",
   );
 });
+
+// ---------------------------------------------------------------------------
+// Issue #1909 (review finding 1) — surprise promotion forces a durable flush
+// ---------------------------------------------------------------------------
+
+test("debounce on: surprise-promoted extract_now flushes the buffer before extraction", async () => {
+  const storage = new FakeStorage(emptyBuffer());
+  const probe = fixedScoreProbe(0.99); // promotes keep_buffering -> extract_now
+  const config = parseConfig({
+    bufferSurpriseTriggerEnabled: true,
+    bufferSurpriseThreshold: 0.35,
+    // High turn cap so the built-in trigger keeps buffering; only the surprise
+    // probe promotes. Large debounce so a scheduled save would NOT have landed.
+    bufferMaxTurns: 100,
+    triggerMode: "smart",
+    bufferSaveDebounceMs: 10_000,
+  });
+  const buffer = new SmartBuffer(
+    config,
+    storage as unknown as ConstructorParameters<typeof SmartBuffer>[1],
+    probe,
+  );
+
+  const outcome = await buffer.addTurnWithOutcome("sess-1", makeTurn("sess-1", "novel turn"));
+  assert.equal(outcome.decision, "extract_now", "surprise promotes the turn");
+  assert.equal(
+    storage.saveCount,
+    1,
+    "the buffer was flushed to disk EXACTLY once before extraction (timer cancelled, single flush)",
+  );
+  assert.equal(
+    storage.saved?.entries?.["sess-1"]?.turns.length,
+    1,
+    "the persisted buffer contains the turn that triggered extraction",
+  );
+});

package/src/buffer.ts

@@ -47,6 +47,25 @@ export interface BufferSurpriseProbe {
 
 const MAX_BUFFER_ENTRY_COUNT = 200;
 
+/**
+ * Upper bound on how long a debounced buffer save may be deferred under
+ * sustained activity (issue #1909). Each new turn re-arms the trailing-edge
+ * timer, so a steady stream of turns could otherwise push the save out
+ * indefinitely and widen the crash-loss window without bound. Once a pending
+ * save has been deferred this many debounce windows, the next scheduled save
+ * forces an inline flush instead of re-arming.
+ */
+const BUFFER_SAVE_MAX_DEFER_MULTIPLIER = 5;
+
+/**
+ * Node's maximum 32-bit `setTimeout` delay (2^31-1 ms, ~24.8 days). A larger
+ * value is overflow-clamped by Node to 1ms with a TimeoutOverflowWarning, so we
+ * clamp defensively at every timer arm (issue #1909 review round 5) even though
+ * parseConfig already caps `bufferSaveDebounceMs` — a directly-constructed config
+ * could still exceed it.
+ */
+const MAX_SET_TIMEOUT_MS = 2_147_483_647;
+
 /**
  * Minimal data carried on the serialized telemetry write chain
  * (issue #563 PR 3).
@@ -113,6 +132,20 @@ export class SmartBuffer {
    */
   private surpriseTelemetryWriteChain: Promise<unknown> = Promise.resolve();
 
+  /**
+   * Debounced buffer-save state (issue #1909). Steady-state buffering used to
+   * serialize + rewrite the whole multi-session buffer on EVERY turn. We now
+   * coalesce those writes onto a trailing-edge timer; correctness boundaries
+   * (extraction trigger, extraction clear, shutdown) still force an immediate
+   * flush. `bufferSaveDebounceMs: 0` restores save-every-turn exactly.
+   */
+  private saveTimer: NodeJS.Timeout | null = null;
+  private pendingSave = false;
+  /** Wall-clock ms when the currently-pending save was first scheduled (issue
+   * #1909). Null when nothing is pending. Used to bound deferral under sustained
+   * activity (see BUFFER_SAVE_MAX_DEFER_MULTIPLIER). */
+  private firstPendingAtMs: number | null = null;
+
   constructor(
     private readonly config: PluginConfig,
     private readonly storage: StorageManager,
@@ -291,6 +324,154 @@ export class SmartBuffer {
     await this.enqueueMutation(async () => this.saveUnlocked());
   }
 
+  /**
+   * Schedule a coalesced, TRUE trailing-edge buffer save (issue #1909). Only
+   * used for the debounced (`bufferSaveDebounceMs > 0`) steady-state buffering
+   * path; the debounce-off and correctness-boundary paths save inline within the
+   * mutation (see `recordTurnUnlocked`). Each call re-arms the timer from now so
+   * the write lands one full window after the LAST turn, not the first. To keep
+   * sustained activity from deferring the save without bound (which would widen
+   * the crash-loss window), once a pending save has been deferred
+   * BUFFER_SAVE_MAX_DEFER_MULTIPLIER windows it is flushed inline instead of
+   * re-armed. Runs inside the record mutation, so the inline save is awaited.
+   */
+  private async scheduleSave(): Promise<void> {
+    const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);
+    const now = Date.now();
+    this.pendingSave = true;
+    if (this.firstPendingAtMs === null) this.firstPendingAtMs = now;
+    if (now - this.firstPendingAtMs >= ms * BUFFER_SAVE_MAX_DEFER_MULTIPLIER) {
+      // Staleness cap hit: persist now rather than deferring further. Drop the
+      // armed timer, attempt the write, and only mark clean on success — a
+      // failure keeps the save pending + re-arms so shutdown/the next timer
+      // retries (issue #1909 review round 2), never diverging memory from disk.
+      clearTimeout(this.saveTimer ?? undefined);
+      this.saveTimer = null;
+      try {
+        await this.saveUnlocked();
+        this.pendingSave = false;
+        this.firstPendingAtMs = null;
+      } catch (err) {
+        log.warn(`buffer.scheduleSave: staleness-cap save failed, keeping it pending: ${describeError(err)}`);
+        this.saveTimer = setTimeout(() => {
+          this.saveTimer = null;
+          void this.flushPendingSave();
+        }, ms);
+        this.saveTimer.unref?.();
+      }
+      return;
+    }
+    // True trailing edge: drop any armed timer and re-arm from now.
+    clearTimeout(this.saveTimer ?? undefined);
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null;
+      void this.flushPendingSave();
+    }, ms);
+    this.saveTimer.unref?.();
+  }
+
+  /** Cancel any armed debounced save without persisting. */
+  private cancelScheduledSave(): void {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    this.pendingSave = false;
+    this.firstPendingAtMs = null;
+  }
+
+  /**
+   * Persist the current in-memory buffer state inline, keeping the global
+   * pending-save state armed until the write SUCCEEDS (issue #1909). On failure
+   * the save stays pending and — when debounced — a background retry timer is
+   * (re-)armed before the error propagates, so a graceful shutdown flush and the
+   * next timer tick both retry. A failed post-mutation save therefore can never
+   * silently drop buffered turns, including turns from OTHER sessions that were
+   * only in the debounced pending state. The pending flag is cleared (and any
+   * armed timer dropped) only after a durable write.
+   */
+  private async saveNowRetainingPendingOnFailure(context: string): Promise<void> {
+    this.pendingSave = true;
+    if (this.firstPendingAtMs === null) this.firstPendingAtMs = Date.now();
+    try {
+      await this.saveUnlocked();
+    } catch (err) {
+      log.warn(
+        `buffer.${context}: inline save failed, keeping it pending for retry: ${describeError(err)}`,
+      );
+      const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);
+      if (ms > 0 && !this.saveTimer) {
+        this.saveTimer = setTimeout(() => {
+          this.saveTimer = null;
+          void this.flushPendingSave();
+        }, ms);
+        this.saveTimer.unref?.();
+      }
+      throw err;
+    }
+    this.cancelScheduledSave();
+  }
+
+  /**
+   * Force any pending debounced save to land now (issue #1909). Idempotent and
+   * safe to call from outside a mutation (timer tick, shutdown/dispose, or the
+   * surprise-promotion path in `addTurnWithOutcome`). Do NOT `await` this from
+   * inside a mutation — it enqueues its own mutation and would deadlock the
+   * serializer.
+   *
+   * `throwOnFailure` (review round 7 finding 5): when set, a failed write is
+   * rethrown AFTER the keep-pending + re-arm bookkeeping, so the surprise
+   * extraction boundary gets the same durability guarantee as the built-in
+   * extract triggers (which propagate saveUnlocked failures) instead of
+   * proceeding to extract_now on a non-durable triggering turn. Default false
+   * keeps the fail-open behavior for the timer/shutdown callers.
+   */
+  async flushPendingSave(opts?: { throwOnFailure?: boolean }): Promise<void> {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    if (!this.pendingSave) return;
+    try {
+      await this.enqueueMutation(async () => {
+        // Re-check under the serializer: a concurrent flush may have already
+        // persisted this pending save. Skip the redundant write (no phantom
+        // writes).
+        if (!this.pendingSave) return;
+        await this.saveUnlocked();
+        // Clear the pending flag INSIDE the same serialized mutation as the
+        // write (issue #1909 review). Clearing it after the enqueue await
+        // resolved raced an addTurn interleaving between the write and the
+        // clear: that turn's scheduleSave re-armed pendingSave + a timer, then
+        // this clear wiped it and the debounced flush was lost. Atomic
+        // write+clear means any addTurn runs wholly before (its turn is in the
+        // write) or wholly after (its pendingSave survives and its timer
+        // persists it).
+        this.pendingSave = false;
+        this.firstPendingAtMs = null;
+      });
+    } catch (err) {
+      // The write failed: memory and disk diverge (issue #1909 review round 2).
+      // Keep the save PENDING (do NOT clear pendingSave/firstPendingAtMs) so a
+      // graceful shutdown flush and the re-armed timer both retry it — clearing
+      // the flag here would drop the buffered turns permanently. Re-arm a
+      // background retry when debounced.
+      log.warn(`buffer.flushPendingSave: save failed, keeping it pending for retry: ${describeError(err)}`);
+      const ms = Math.min(this.config.bufferSaveDebounceMs, MAX_SET_TIMEOUT_MS);
+      if (ms > 0 && !this.saveTimer) {
+        this.saveTimer = setTimeout(() => {
+          this.saveTimer = null;
+          void this.flushPendingSave();
+        }, ms);
+        this.saveTimer.unref?.();
+      }
+      // Surprise-extraction boundary needs the durability guarantee — surface
+      // the failure so the caller does not proceed with a non-durable flush.
+      if (opts?.throwOnFailure) throw err;
+      return; // fail-open for timer/shutdown callers
+    }
+  }
+
   async addTurn(bufferKey: string, turn: BufferTurn): Promise<TriggerDecision> {
     return (await this.addTurnWithOutcome(bufferKey, turn)).decision;
   }
@@ -336,6 +517,16 @@ export class SmartBuffer {
             decision = "extract_now";
             triggered = true;
             extractionTurns = currentTurns;
+            // Issue #1909 (review): the record mutation for a `keep_buffering`
+            // turn only SCHEDULED a debounced save. Surprise now promotes it to
+            // extract_now AFTER that mutation, so force the buffer durable before
+            // the caller runs extraction — otherwise state/buffer.json lags the
+            // extracted turns by up to the debounce window on a crash. Safe to
+            // await here: we are outside the record mutation (deadlock-free).
+            // throwOnFailure (round 7 finding 5): match the built-in extract
+            // triggers — a failed durability write must NOT silently proceed to
+            // extract_now on a non-durable turn.
+            await this.flushPendingSave({ throwOnFailure: true });
           } else {
             log.debug(
               `buffer[${bufferKey}]: surprise=${surprise.toFixed(3)} ignored because buffer changed before probe resolved`,
@@ -399,7 +590,20 @@ export class SmartBuffer {
     const turnCountInWindow = entry.turns.length;
 
     this.pruneEntries([bufferKey]);
-    await this.saveUnlocked();
+    if (decision === "keep_buffering" && this.config.bufferSaveDebounceMs > 0) {
+      // Steady-state buffering: coalesce the whole-state serialize onto a
+      // trailing-edge timer (issue #1909) instead of rewriting per turn.
+      await this.scheduleSave();
+    } else {
+      // Persist immediately within this mutation (awaited) when either:
+      //  - the turn triggered extraction (the buffer must be durable), or
+      //  - debounce is disabled (bufferSaveDebounceMs <= 0), which reproduces
+      //    the legacy save-every-turn behavior byte-for-byte.
+      // Round 8 thread 4: the write is attempted BEFORE the pending state is
+      // cleared, and a failed write leaves it pending (+ a re-armed timer) for
+      // shutdown/timer retry instead of dropping the in-memory turns.
+      await this.saveNowRetainingPendingOnFailure("recordTurn");
+    }
     return {
       decision,
       signalLevel: signal.level,
@@ -710,6 +914,17 @@ export class SmartBuffer {
     extractedTurns?: readonly BufferTurn[],
   ): Promise<void> {
     await this.enqueueMutation(async () => {
+      // Drop any armed debounce TIMER so it cannot fire mid-mutation and race
+      // our post-clear write, but KEEP the pending-save state (issue #1909
+      // review round 13): the post-clear save below can fail, and clearing the
+      // pending flag here would strand buffered turns — including turns from
+      // OTHER sessions that only ever entered the debounced pending state — with
+      // nothing left to retry them. saveNowRetainingPendingOnFailure clears the
+      // pending state only after a durable write, or re-arms it on failure.
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
       await this.loadUnlocked();
       const entry = this.entryFor(bufferKey);
       if (Array.isArray(extractedTurns)) {
@@ -733,7 +948,7 @@ export class SmartBuffer {
           }
         }
         if (!clearedLiveTurns) {
-          await this.saveUnlocked();
+          await this.saveNowRetainingPendingOnFailure("clearAfterExtraction");
           return;
         }
       } else {
@@ -747,7 +962,7 @@ export class SmartBuffer {
         this.state.extractionCount = entry.extractionCount;
       }
       this.pruneEntries([bufferKey]);
-      await this.saveUnlocked();
+      await this.saveNowRetainingPendingOnFailure("clearAfterExtraction");
     });
   }
 

package/src/capabilities-cluster-b.test.ts

@@ -17,6 +17,7 @@ import {
 const ACCESS_FIELD_TO_FLAG: Record<keyof AccessSetupCapabilitySet, string> = {
   recallCrossNamespaceBudget: "recallCrossNamespaceBudgetEnabled",
   recallAuditAnomalyDetection: "recallAuditAnomalyDetectionEnabled",
+  recallSingleFlight: "recallSingleFlightEnabled",
 };
 
 const ACCESS_FIELDS = Object.keys(ACCESS_FIELD_TO_FLAG) as Array<

package/src/capabilities.ts

@@ -189,16 +189,14 @@ export interface AccessSetupCapabilitySet {
   readonly recallCrossNamespaceBudget: boolean;
   /** `recallAuditAnomalyDetectionEnabled` — access-audit anomaly detection (default-off). */
   readonly recallAuditAnomalyDetection: boolean;
+  readonly recallSingleFlight: boolean;
 }
 
-/**
- * Resolve the {@link AccessSetupCapabilitySet} from parsed config.
- *
- * Call this ONCE at access-service handler entry and thread the result down.
- */
+/** Resolve the {@link AccessSetupCapabilitySet} from parsed config. Call ONCE at
+ *  access-service handler entry and thread the result down. */
 export type AccessSetupConfigProjection = Pick<
   PluginConfig,
-  "recallCrossNamespaceBudgetEnabled" | "recallAuditAnomalyDetectionEnabled"
+  "recallCrossNamespaceBudgetEnabled" | "recallAuditAnomalyDetectionEnabled" | "recallSingleFlightEnabled"
 >;
 
 export function resolveAccessSetupCapabilities(
@@ -208,6 +206,7 @@ export function resolveAccessSetupCapabilities(
     recallCrossNamespaceBudget: config.recallCrossNamespaceBudgetEnabled,
     // Optional/default-off flag: preserve `=== true` semantics.
     recallAuditAnomalyDetection: config.recallAuditAnomalyDetectionEnabled === true,
+    recallSingleFlight: config.recallSingleFlightEnabled === true,
   });
 }
 

package/src/cli.ts

@@ -28,6 +28,7 @@ import type {
 import { isRecallDisclosure, RECALL_DISCLOSURE_LEVELS } from "./types.js";
 import { chunkContent } from "./chunking.js";
 import { rescoreMemoryImportance } from "./importance.js";
+import { renderQmdBacklogStatus } from "./qmd-status.js";
 import { exportJsonBundle } from "./transfer/export-json.js";
 import { exportMarkdownBundle } from "./transfer/export-md.js";
 import { backupMemoryDir } from "./transfer/backup.js";
@@ -51,7 +52,11 @@ import {
   type ProcessBatchFn,
 } from "./bulk-import/index.js";
 import { archiveObservations } from "./maintenance/archive-observations.js";
-import { rebuildMemoryLifecycleLedger } from "./maintenance/rebuild-memory-lifecycle-ledger.js";
+import {
+  runRebuildMemoryLifecycleLedgerCliCommand,
+  type RebuildMemoryLifecycleLedgerCliCommandOptions,
+} from "./maintenance/rebuild-memory-lifecycle-ledger-cli.js";
+export { runRebuildMemoryLifecycleLedgerCliCommand, type RebuildMemoryLifecycleLedgerCliCommandOptions };
 import {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact,
@@ -465,12 +470,6 @@ export interface RebuildObservationsCliCommandOptions {
   now?: Date;
 }
 
-export interface RebuildMemoryLifecycleLedgerCliCommandOptions {
-  memoryDir: string;
-  write?: boolean;
-  now?: Date;
-}
-
 export interface RebuildMemoryProjectionCliCommandOptions {
   memoryDir: string;
   defaultNamespace?: string;
@@ -1024,16 +1023,6 @@ export async function runRebuildObservationsCliCommand(
   });
 }
 
-export async function runRebuildMemoryLifecycleLedgerCliCommand(
-  options: RebuildMemoryLifecycleLedgerCliCommandOptions,
-) {
-  return rebuildMemoryLifecycleLedger({
-    memoryDir: options.memoryDir,
-    dryRun: options.write !== true,
-    now: options.now,
-  });
-}
-
 export async function runRebuildMemoryProjectionCliCommand(
   options: RebuildMemoryProjectionCliCommandOptions,
 ) {
@@ -3674,10 +3663,9 @@ export function registerCli(
           console.log(`Profile size: ${profile.length} chars`);
           console.log(`Extractions: ${meta.extractionCount}`);
           console.log(`Last extraction: ${meta.lastExtractionAt ?? "never"}`);
-          console.log(
-            `Last consolidation: ${meta.lastConsolidationAt ?? "never"}`,
-          );
+          console.log(`Last consolidation: ${meta.lastConsolidationAt ?? "never"}`);
           console.log(`QMD: ${orchestrator.qmd.isAvailable() ? "available" : "not available"}`);
+          for (const line of await renderQmdBacklogStatus(orchestrator.qmd, orchestrator.config.qmdEmbeddingBacklogThreshold)) console.log(line);
 
           // Category breakdown
           const categories: Record<string, number> = {};
@@ -7035,13 +7023,24 @@ export function registerCli(
         .command("rebuild-memory-lifecycle-ledger")
         .description("Rebuild the generic memory lifecycle ledger from markdown memories (dry-run by default)")
         .option("--write", "Write rebuilt ledger (default: dry-run)")
+        .option("--namespace <ns>", "Namespace whose ledger to rebuild (default: config defaultNamespace)", "")
         .action(async (...args: unknown[]) => {
           const options = (args[0] ?? {}) as Record<string, unknown>;
+          const namespace = typeof options.namespace === "string" && options.namespace.trim().length > 0
+            ? options.namespace.trim()
+            : undefined;
+          // Route BOTH the undefined/default and explicit namespace through the
+          // router (#2033 finding 2): a store may live at a tokenized
+          // namespaces/<token>/ path, and the default can migrate off the legacy
+          // root, so storage.dir keeps the rebuild aligned with the namespace
+          // router and secure store. The raw resolver still validates the segment.
+          await resolveMemoryDirForNamespace(orchestrator, namespace, { rejectUnsupportedOverride: true });
+          const storage = await orchestrator.getStorageForNamespace(namespace);
           const result = await runRebuildMemoryLifecycleLedgerCliCommand({
-            memoryDir: orchestrator.config.memoryDir,
+            memoryDir: storage.dir,
             write: options.write === true,
+            storage,
           });
-
           console.log(`Dry run: ${result.dryRun ? "yes" : "no"}`);
           console.log(`Scanned memories: ${result.scannedMemories}`);
           console.log(`Rebuilt rows: ${result.rebuiltRows}`);

package/src/coding/architecture-surfaces.test.ts

@@ -31,6 +31,7 @@ import {
   type ArchitectureSurfaceRequest,
   type ArchitectureSurfaceStorage,
 } from "./architecture-surfaces.js";
+import { sealedWriteToLegacyArgs } from "../write-envelope.js";
 import type { ArchitectureCardBuildResult } from "./architecture-card.js";
 import type {
   CodingKnowledgeConfig,
@@ -109,7 +110,9 @@ function makeStubStorage(initialMemories: MemoryFile[] = []): StubStorage {
     written,
     updated,
     async readAllMemories() { return [...allMemories]; },
-    async writeMemory(category, content, options) {
+    // Production mapper keeps the legacy-shaped recorder faithful (§21).
+    async writeSealedMemory(envelope, extras) {
+      const { category, content, options } = sealedWriteToLegacyArgs(envelope, extras as Record<string, unknown>);
       const id = `fact-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
       written.push({ category, content, options });
       allMemories.push({
@@ -409,8 +412,8 @@ test("refresh: tombstone-blocked write surfaces refreshed:false + blocked reason
   const base = makeStubStorage();
   const storage: StubStorage = {
     ...base,
-    async writeMemory(category, content, options) {
-      const result = await base.writeMemory(category, content, options);
+    async writeSealedMemory(envelope, extras) {
+      const result = await base.writeSealedMemory(envelope, extras);
       return { ...result, tombstoneBlocked: true, blockedBy: "tomb-arch-1" };
     },
   };

package/src/coding/architecture-surfaces.ts

@@ -34,6 +34,7 @@ import type { MemoryWriteResult } from "../storage.js";
 import { stripAttributesSuffix } from "../structured-attributes.js";
 import { ARCHITECTURE_CARD_TRUNCATION_MARKER, type ArchitectureCardBuildResult } from "./architecture-card.js";
 import { log } from "../logger.js";
+import { composeMemoryEnvelope, type SealedMemoryEnvelope } from "../write-envelope.js";
 
 // ──────────────────────────────────────────────────────────────────────────
 // Subcommands
@@ -149,17 +150,10 @@ export interface ArchitectureSurfaceStorage {
   /** The resolved namespace — used for logging/observability. */
   readonly namespace: string;
   readAllMemories(): Promise<readonly MemoryFile[]>;
-  writeMemory(
-    category: "fact",
-    content: string,
-    options: {
-      confidence?: number;
-      tags?: string[];
-      source?: string;
-      status?: MemoryStatus;
-      structuredAttributes?: Record<string, string>;
-      sourceConnector?: string;
-    },
+  /** Sealed-envelope write entry point (issue #1989 PR4). */
+  writeSealedMemory(
+    envelope: SealedMemoryEnvelope,
+    extras: { status?: MemoryStatus },
   ): Promise<MemoryWriteResult>;
   updateMemory(
     id: string,
@@ -320,13 +314,22 @@ async function architectureRefresh(
       log.warn(
         `coding_architecture/refresh: updateMemory returned false for id=${existing.frontmatter.id} — falling back to writeMemory`,
       );
-      const fallbackWrite = await storage.writeMemory("fact", cardContent, {
-        confidence: 1.0,
-        tags,
-        source: "coding-architecture",
-        ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}),
-        structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
-      });
+      // Sealed-envelope write (issue #1989 PR4): system-built card content —
+      // strict compose; an invalid card is a code bug that must surface.
+      const fallbackWrite = await storage.writeSealedMemory(
+        composeMemoryEnvelope(
+          {
+            content: cardContent,
+            category: "fact",
+            confidence: 1.0,
+            tags,
+            structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
+            ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}),
+          },
+          { source: "coding-architecture" },
+        ),
+        {},
+      );
       log.info(
         `access-write op=coding_architecture/refresh memoryId=${fallbackWrite.id} (fallback write) byteSize=${buildResult.card.byteSize}`,
       );
@@ -345,13 +348,21 @@ async function architectureRefresh(
   }
 
   // First card for this namespace — write a new memory.
-  const newWrite = await storage.writeMemory("fact", cardContent, {
-    confidence: 1.0,
-    tags,
-    source: "coding-architecture",
-    ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}),
-    structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
-  });
+  // Sealed-envelope write (issue #1989 PR4): strict — see the fallback site.
+  const newWrite = await storage.writeSealedMemory(
+    composeMemoryEnvelope(
+      {
+        content: cardContent,
+        category: "fact",
+        confidence: 1.0,
+        tags,
+        structuredAttributes: { cardKind: ARCHITECTURE_CARD_KIND },
+        ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}),
+      },
+      { source: "coding-architecture" },
+    ),
+    {},
+  );
   log.info(
     `access-write op=coding_architecture/refresh memoryId=${newWrite.id} (new) byteSize=${buildResult.card.byteSize}`,
   );