@remnic/core 9.7.15 → 9.8.0

package/src/contradiction/resolution.ts

@@ -6,6 +6,7 @@
  */
 
 import { log } from "../logger.js";
+import { composeMemoryEnvelope } from "../write-envelope.js";
 import type { StorageManager } from "../storage.js";
 import type { MemoryCategory, MemoryFile } from "../types.js";
 import type { ResolutionVerb } from "./contradiction-review.js";
@@ -386,11 +387,23 @@ async function prepareMergeReplacement(
   const category = options.mergedCategory ?? mergedMemoryCategory(sourceA, sourceB);
   let mergedId: string;
   try {
-    const mergeResult = await storage.writeMemory(category, mergedContent, {
+    // Sealed-envelope write (issue #1989 PR4): merged content is
+    // LLM-produced — salvage; drops are warn-logged.
+    const mergeEnvelope = composeMemoryEnvelope(
+      {
+        content: mergedContent,
+        category,
+        confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
+        tags: ["contradiction-resolution", "merge"],
+      },
+      { source: "contradiction-resolution" },
+      { salvage: true },
+    );
+    if (mergeEnvelope.salvageNotes.length > 0) {
+      log.warn(`contradiction-resolution write salvaged invalid fields: ${mergeEnvelope.salvageNotes.join("; ")}`);
+    }
+    const mergeResult = await storage.writeSealedMemory(mergeEnvelope, {
       actor: "contradiction-resolution",
-      confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
-      tags: ["contradiction-resolution", "merge"],
-      source: "contradiction-resolution",
       lineage: [idA, idB],
       derivedVia: "merge",
     });

package/src/correction/correction-access-wiring.ts

@@ -21,6 +21,8 @@
  */
 
 import path from "node:path";
+import { composeMemoryEnvelope, isMemoryCategory } from "../write-envelope.js";
+import { log } from "../logger.js";
 import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import type { Orchestrator } from "../orchestrator.js";
@@ -402,20 +404,39 @@ async function writeReplacementMemory(
   // writeMemory is the single storage chokepoint — catalog/dedup/reindex fire
   // here (rule 43). Tombstone blocking also fires here (#1579), so a
   // resurrected fact lands as pending_review rather than silently overwriting.
-  const { id, tombstoneBlocked } = await storage.writeMemory(
-    (draft.category ?? "fact") as Parameters<typeof storage.writeMemory>[0],
-    draft.content,
+  // Sealed-envelope write (issue #1989 PR4): correction drafts carry
+  // plan-derived (machine) field values — salvage so one malformed optional
+  // field cannot make a correction unapplicable; drops are warn-logged.
+  // Category is IDENTITY and stays fatal (#2022 review): default to "fact"
+  // only when ABSENT (the legacy default); an explicit unrecognized value
+  // must surface as a contract error, not silently change the correction's
+  // meaning before it supersedes the target.
+  if (draft.category !== undefined && !isMemoryCategory(draft.category)) {
+    throw new CorrectionContractError(
+      `correction draft carries unrecognized category ${JSON.stringify(draft.category)} — expected a valid memory category`,
+    );
+  }
+  const draftCategory = draft.category ?? ("fact" as const);
+  const draftEnvelope = composeMemoryEnvelope(
     {
-      source: "correction",
+      content: draft.content,
+      category: draftCategory,
       confidence: draft.confidence ?? 0.9,
       tags: draft.tags ?? [],
       ...(draft.entityRef ? { entityRef: draft.entityRef } : {}),
       ...(draft.validAt ? { validAt: draft.validAt } : {}),
-      ...(draft.observedAt ? { observedAt: draft.observedAt } : {}),
       ...(draft.structuredAttributes ? { structuredAttributes: draft.structuredAttributes } : {}),
-      ...(draft.supersedes ? { supersedes: draft.supersedes } : {}),
     },
+    { source: "correction" },
+    { salvage: true },
   );
+  if (draftEnvelope.salvageNotes.length > 0) {
+    log.warn(`correction write salvaged invalid fields: ${draftEnvelope.salvageNotes.join("; ")}`);
+  }
+  const { id, tombstoneBlocked } = await storage.writeSealedMemory(draftEnvelope, {
+    ...(draft.observedAt ? { observedAt: draft.observedAt } : {}),
+    ...(draft.supersedes ? { supersedes: draft.supersedes } : {}),
+  });
   if (tombstoneBlocked) {
     // #1645 (review thread): the replacement content matched a tombstone, so it
     // landed pending_review (non-active). Returning the id would let the
@@ -516,13 +537,27 @@ async function rescopeMemoryFn(
   const destContent = fm.structuredAttributes
     ? stripAttributesSuffix(memory.content)
     : memory.content;
-  const { id: destId, tombstoneBlocked: destBlocked } = await destStorage.writeMemory(fm.category, destContent, {
-    source: `correction:rescope:${namespace}`,
-    ...(typeof fm.confidence === "number" ? { confidence: fm.confidence } : {}),
-    ...(Array.isArray(fm.tags) ? { tags: fm.tags } : {}),
-    ...(fm.entityRef ? { entityRef: fm.entityRef } : {}),
-    ...(fm.structuredAttributes ? { structuredAttributes: fm.structuredAttributes } : {}),
-    ...(fm.valid_at ? { validAt: fm.valid_at } : {}),
+  // Sealed-envelope write (issue #1989 PR4): a rescope REPLAYS stored
+  // frontmatter — legacy rows may predate current field limits, and a
+  // rescope must never be impossible for data already in the store, so
+  // compose in salvage mode (drops warn-logged).
+  const rescopeEnvelope = composeMemoryEnvelope(
+    {
+      content: destContent,
+      category: fm.category,
+      ...(typeof fm.confidence === "number" ? { confidence: fm.confidence } : {}),
+      ...(Array.isArray(fm.tags) ? { tags: fm.tags } : {}),
+      ...(fm.entityRef ? { entityRef: fm.entityRef } : {}),
+      ...(fm.structuredAttributes ? { structuredAttributes: fm.structuredAttributes } : {}),
+      ...(fm.valid_at ? { validAt: fm.valid_at } : {}),
+    },
+    { source: `correction:rescope:${namespace}` },
+    { salvage: true },
+  );
+  if (rescopeEnvelope.salvageNotes.length > 0) {
+    log.warn(`rescope write salvaged invalid fields: ${rescopeEnvelope.salvageNotes.join("; ")}`);
+  }
+  const { id: destId, tombstoneBlocked: destBlocked } = await destStorage.writeSealedMemory(rescopeEnvelope, {
     ...(fm.observedAt ? { observedAt: fm.observedAt } : {}),
     ...(fm.memoryKind ? { memoryKind: fm.memoryKind } : {}),
     ...(Array.isArray(fm.links) ? { links: fm.links } : {}),
@@ -669,11 +704,20 @@ async function appendAuditRecordFn(
   // Corrections are themselves memories, searchable and namespaced (issue
   // #1580 design §4). Write a correction-category memory capturing the
   // plan + outcome as the audit trail.
-  const { id: id } = await storage.writeMemory("correction", buildAuditBody(record), {
-    source: "correction-contract",
-    confidence: 1.0,
-    tags: ["correction-audit", `plan:${record.planId}`, `classification:${record.classification}`],
-  });
+  // Sealed-envelope write (issue #1989 PR4): system-built audit body —
+  // strict compose; an invalid audit record is a code bug.
+  const { id: id } = await storage.writeSealedMemory(
+    composeMemoryEnvelope(
+      {
+        content: buildAuditBody(record),
+        category: "correction",
+        confidence: 1.0,
+        tags: ["correction-audit", `plan:${record.planId}`, `classification:${record.classification}`],
+      },
+      { source: "correction-contract" },
+    ),
+    {},
+  );
   return id;
 }
 

package/src/cross-namespace-budget.test.ts

@@ -355,3 +355,38 @@ test("inverted soft/hard limits clamp soft <= hard", () => {
   const cfg = limiter.getConfig();
   assert.equal(cfg.softLimit, cfg.hardLimit);
 });
+
+test("release(token) removes the EXACT reserved entry, not the newest (issue #1906 review #4)", () => {
+  const limiter = new CrossNamespaceBudget({
+    enabled: true,
+    softLimit: 0,
+    hardLimit: 10,
+    windowMs: 60_000,
+  });
+
+  // A reserves first (older), B reserves later (newer).
+  const a = limiter.record("p1", 0);
+  const b = limiter.record("p1", 1_000);
+  assert.ok(a.reservation, "an allowed record returns a reservation token");
+  assert.ok(b.reservation);
+  assert.equal(a.count, 1);
+  assert.equal(b.count, 2);
+
+  // A fails and releases ITS token. A naive pop-newest would drop B's entry.
+  limiter.release(a.reservation);
+
+  // Advance so A's original timestamp (t=0) would have expired but B's (t=1000)
+  // is still live. A fresh record counts only B + itself => 2. If B had been
+  // wrongly removed, only the fresh entry would remain => 1.
+  const after = limiter.record("p1", 60_500);
+  assert.equal(
+    after.count,
+    2,
+    "B's newer reservation survives A's release (A's exact entry was removed)",
+  );
+
+  // release() is idempotent and a no-op for an unknown/already-freed token.
+  limiter.release(a.reservation);
+  limiter.release(undefined);
+  assert.equal(limiter.bucketCount(), 1);
+});

package/src/cross-namespace-budget.ts

@@ -67,6 +67,17 @@ export type BudgetDecisionReason =
   | "warn-over-soft"
   | "deny-over-hard";
 
+/**
+ * Opaque token identifying the EXACT window entry a {@link CrossNamespaceBudget.record}
+ * reserve created (issue #1906 review #4). Pass it to `release()` to remove
+ * that specific entry — never "the newest", which under concurrency could evict
+ * a different (newer) recall's reservation and reopen the limiter early.
+ */
+export interface BudgetReservation {
+  principal: string;
+  id: number;
+}
+
 export interface BudgetDecision {
   allowed: boolean;
   reason: BudgetDecisionReason;
@@ -78,11 +89,40 @@ export interface BudgetDecision {
     hardLimit: number;
     windowMs: number;
   };
+  /**
+   * Present only when this decision RESERVED a window entry (an allowed
+   * `record()`), so the caller can later `release(reservation)` that exact
+   * entry on a failed/aborted recall. Absent on denials, peeks, and
+   * same-namespace/no-limit decisions.
+   */
+  reservation?: BudgetReservation;
+}
+
+/**
+ * Response-safe projection of a soft-limit warning: a {@link BudgetDecision}
+ * WITHOUT the server-only `reservation` rollback token (which carries the
+ * principal id). This is what may be surfaced on HTTP/MCP recall responses and
+ * persisted in idempotency-cache entries, so it must never carry internal quota
+ * state (issue #1906 review round 10 #2).
+ */
+export type BudgetWarning = Omit<BudgetDecision, "reservation">;
+
+/**
+ * Project a decision to its response-safe {@link BudgetWarning}, stripping the
+ * internal `reservation` token. Returns `undefined` unless the decision is a
+ * soft-limit warning (`warn-over-soft`) — so callers can assign the result to
+ * `budgetWarning` directly.
+ */
+export function toBudgetWarning(decision: BudgetDecision): BudgetWarning | undefined {
+  if (decision.reason !== "warn-over-soft") return undefined;
+  const { reservation: _reservation, ...warning } = decision;
+  return warning;
 }
 
 interface PrincipalBucket {
-  /** Epoch-ms timestamps of cross-namespace reads in the active window. */
-  timestamps: number[];
+  /** Cross-namespace reads in the active window, each tagged with a unique id
+   *  so a specific reservation can be released without disturbing others. */
+  entries: Array<{ id: number; ts: number }>;
 }
 
 /**
@@ -149,6 +189,8 @@ function normalizeClock(now: number | undefined): number {
 export class CrossNamespaceBudget {
   private readonly config: Required<CrossNamespaceBudgetConfig>;
   private readonly buckets = new Map<string, PrincipalBucket>();
+  /** Monotonic id source for reservation tokens (issue #1906 review #4). */
+  private reservationSeq = 0;
 
   constructor(config?: CrossNamespaceBudgetConfig) {
     this.config = effectiveConfig(config);
@@ -192,46 +234,51 @@ export class CrossNamespaceBudget {
       principal = "__anonymous__";
     }
 
-    const bucket = this.buckets.get(principal) ?? { timestamps: [] };
+    const bucket = this.buckets.get(principal) ?? { entries: [] };
     const cutoff = normalizedNow - windowMs;
-    // Drop timestamps that slid out of the window.
-    while (bucket.timestamps.length > 0 && bucket.timestamps[0]! < cutoff) {
-      bucket.timestamps.shift();
+    // Drop entries that slid out of the window.
+    while (bucket.entries.length > 0 && bucket.entries[0]!.ts < cutoff) {
+      bucket.entries.shift();
     }
 
     // Count the current call against the window BEFORE deciding — a call
     // that crosses the deny threshold should itself be denied, not the
     // next one. This is what the threat model calls "fail at the Nth,
     // not the (N+1)th".
-    bucket.timestamps.push(normalizedNow);
+    const id = ++this.reservationSeq;
+    bucket.entries.push({ id, ts: normalizedNow });
     this.buckets.set(principal, bucket);
-    const count = bucket.timestamps.length;
+    const count = bucket.entries.length;
 
     if (count >= hardLimit) {
-      // Denied: roll back the timestamp we just added so a repeated denied
+      // Denied: roll back the entry we just added so a repeated denied
       // call does not push the bucket further into the future. This keeps
       // the limiter stateless with respect to denied attempts.
-      bucket.timestamps.pop();
+      bucket.entries.pop();
       // Evict empty buckets (e.g. the first record after a long idle
-      // rolled the only timestamp out, then got denied and rolled back).
+      // rolled the only entry out, then got denied and rolled back).
       // Prevents unbounded map growth across many transient principals.
-      if (bucket.timestamps.length === 0) {
+      if (bucket.entries.length === 0) {
         this.buckets.delete(principal);
       }
       return {
         allowed: false,
         reason: "deny-over-hard",
-        count: bucket.timestamps.length,
+        count: bucket.entries.length,
         limit,
       };
     }
 
+    // Allowed: the entry stands as a reservation the caller can later release
+    // by token (issue #1906 review #4).
+    const reservation: BudgetReservation = { principal, id };
     if (count > softLimit) {
       return {
         allowed: true,
         reason: "warn-over-soft",
         count,
         limit,
+        reservation,
       };
     }
 
@@ -240,6 +287,7 @@ export class CrossNamespaceBudget {
       reason: "allowed-under-soft",
       count,
       limit,
+      reservation,
     };
   }
 
@@ -283,11 +331,11 @@ export class CrossNamespaceBudget {
       principal = "__anonymous__";
     }
     const now = normalizeClock(args.now);
-    const bucket = this.buckets.get(principal) ?? { timestamps: [] };
+    const bucket = this.buckets.get(principal) ?? { entries: [] };
     const cutoff = now - windowMs;
     let liveCount = 0;
-    for (const ts of bucket.timestamps) {
-      if (ts >= cutoff) liveCount++;
+    for (const entry of bucket.entries) {
+      if (entry.ts >= cutoff) liveCount++;
     }
     const projected = liveCount + 1; // +1 for the current call
     if (projected >= hardLimit) {
@@ -335,6 +383,25 @@ export class CrossNamespaceBudget {
     return this.record(args.principal, args.now);
   }
 
+  /**
+   * Roll back the EXACT reservation made by an allowed {@link record} (issue
+   * #1906 review #4). When a recall reserves budget at admission but then fails
+   * or is aborted, the caller releases its own `reservation` token so the
+   * errored recall does not consume budget permanently — and, critically, does
+   * NOT evict a different concurrent recall's entry (which could expire early
+   * and reopen the limiter). A no-op when the token is absent or already gone.
+   * Evicts empty buckets.
+   */
+  release(reservation: BudgetReservation | null | undefined): void {
+    if (!reservation) return;
+    const bucket = this.buckets.get(reservation.principal);
+    if (!bucket) return;
+    const index = bucket.entries.findIndex((entry) => entry.id === reservation.id);
+    if (index < 0) return;
+    bucket.entries.splice(index, 1);
+    if (bucket.entries.length === 0) this.buckets.delete(reservation.principal);
+  }
+
   /**
    * Clear all state. Intended for tests and for the orchestrator's
    * lifecycle `before_reset` hook.
@@ -355,10 +422,10 @@ export class CrossNamespaceBudget {
     const cutoff = normalizedNow - this.config.windowMs;
     let evicted = 0;
     for (const [principal, bucket] of this.buckets.entries()) {
-      while (bucket.timestamps.length > 0 && bucket.timestamps[0]! < cutoff) {
-        bucket.timestamps.shift();
+      while (bucket.entries.length > 0 && bucket.entries[0]!.ts < cutoff) {
+        bucket.entries.shift();
       }
-      if (bucket.timestamps.length === 0) {
+      if (bucket.entries.length === 0) {
         this.buckets.delete(principal);
         evicted++;
       }

package/src/explicit-capture.ts

@@ -1,3 +1,4 @@
+import { composeMemoryEnvelope, TAG_LIMITS } from "./write-envelope.js";
 import { resolveNamespaceCapabilities } from "./capabilities.js";
 import { randomUUID } from "node:crypto";
 import type { Orchestrator } from "./orchestrator.js";
@@ -366,15 +367,31 @@ export function validateExplicitCaptureInput(
   }
   const expiresAt = parseExplicitCaptureTtl(input.ttl);
 
+  // #2014 review round: enforce the composer's tag contract HERE so a capture
+  // that passes validation can never fail later at strict compose time
+  // (validated-then-thrown was a broken contract). Same limits as TAG_LIMITS.
+  const dedupedTags = Array.from(new Set((input.tags ?? []).map((tag) => tag.trim()).filter(Boolean)));
+  if (dedupedTags.length > TAG_LIMITS.maxTags) {
+    throw new Error(`too many tags: ${dedupedTags.length} exceeds the ${TAG_LIMITS.maxTags}-tag limit`);
+  }
+  for (const tag of dedupedTags) {
+    if (tag.length > TAG_LIMITS.maxTagLength) {
+      throw new Error(`tag exceeds ${TAG_LIMITS.maxTagLength} characters: ${JSON.stringify(tag.slice(0, 40))}…`);
+    }
+  }
+
   return {
     content,
     category,
     confidence,
     namespace: asTrimmed(input.namespace),
-    tags: Array.from(new Set((input.tags ?? []).map((tag) => tag.trim()).filter(Boolean))),
+    tags: dedupedTags,
     entityRef: asTrimmed(input.entityRef),
     sourceReason: asTrimmed(input.sourceReason),
-    sourceConnector: input.sourceConnector,
+    // Trimmed like the other optional metadata (#2017 review round): a
+    // whitespace-only connector previously passed validation and then blew
+    // up at strict compose time - validated input must always compose.
+    sourceConnector: asTrimmed(input.sourceConnector),
     expiresAt,
   };
 }
@@ -442,14 +459,21 @@ export async function persistExplicitCapture(
   // #1645 (review thread yG-): surface the tombstone block so callers
   // (memory_store tool, access-service HTTP/MCP) can report the capture as
   // queued for review instead of a successfully stored active memory.
-  const { id, tombstoneBlocked } = await storage.writeMemory(candidate.category, candidate.content, {
-    confidence: candidate.confidence,
-    tags: candidate.tags,
-    entityRef: candidate.entityRef,
-    expiresAt: candidate.expiresAt,
-    source: source === "inline" ? "explicit-inline" : "explicit",
-    ...(candidate.sourceConnector ? { sourceConnector: candidate.sourceConnector } : {}),
-  });
+  // Sealed-envelope write (issue #1989 PR2).
+  const captureEnvelope = composeMemoryEnvelope(
+    {
+      content: candidate.content,
+      category: candidate.category,
+      confidence: candidate.confidence,
+      tags: candidate.tags,
+      ...(candidate.entityRef ? { entityRef: candidate.entityRef } : {}),
+      ...(candidate.expiresAt ? { ttl: candidate.expiresAt } : {}),
+      ...(candidate.sourceConnector ? { sourceConnector: candidate.sourceConnector } : {}),
+      ...(candidate.sourceReason ? { sourceReason: candidate.sourceReason } : {}),
+    },
+    { source: source === "inline" ? "explicit-inline" : "explicit" },
+  );
+  const { id, tombstoneBlocked } = await storage.writeSealedMemory(captureEnvelope);
   // #1522: catalog touch handled at the storage chokepoint — the StorageManager's
   // post-write hook records the namespace touch automatically.
 
@@ -547,13 +571,26 @@ export async function queueExplicitCaptureForReview(
     : "fact";
   const requestedTags = sanitizeReviewTags(input.tags);
   const storage = await orchestrator.getStorage(queueNamespace);
-  const { id: id } = await storage.writeMemory(reviewCategory, content, {
-    confidence: 0.2,
-    tags: Array.from(new Set([...EXPLICIT_CAPTURE_REVIEW_TAGS, ...requestedTags])),
-    entityRef: sanitizeReviewMetadata(input.entityRef),
-    source: source === "inline" ? "explicit-inline-review" : "explicit-review",
-    ...(input.sourceConnector ? { sourceConnector: input.sourceConnector } : {}),
-  });
+  const reviewEnvelope = composeMemoryEnvelope(
+    {
+      content,
+      category: reviewCategory,
+      confidence: 0.2,
+      tags: Array.from(new Set([...EXPLICIT_CAPTURE_REVIEW_TAGS, ...requestedTags])),
+      ...(sanitizeReviewMetadata(input.entityRef) ? { entityRef: sanitizeReviewMetadata(input.entityRef) } : {}),
+      ...(input.sourceConnector ? { sourceConnector: input.sourceConnector } : {}),
+    },
+    { source: source === "inline" ? "explicit-inline-review" : "explicit-review" },
+    // The review queue is the FALLBACK for a capture that already failed
+    // primary validation — it must never be un-queueable. The tag list is
+    // machine-assembled (requested tags + the two fixed review tags), so 49+
+    // requested tags would push past the 50-tag limit and strict compose
+    // would throw, losing the capture (#2014 review round). Salvage clamps
+    // instead; the fixed review tags sort first in the assembly above, so
+    // they always survive the clamp.
+    { salvage: true },
+  );
+  const { id: id } = await storage.writeSealedMemory(reviewEnvelope);
   try {
     const created = await storage.getMemoryById(id);
     if (created) {

package/src/extraction.ts

@@ -2,6 +2,7 @@ import OpenAI from "openai";
 import { log } from "./logger.js";
 import { delinearize } from "./delinearize.js";
 import { LocalLlmClient } from "./local-llm.js";
+import { shouldRunProactivePass } from "./proactive-contention.js";
 import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig, gatewayTaskChainOptions } from "./fallback-llm.js";
 import {
   ExtractionResultSchema,
@@ -633,9 +634,7 @@ export class ExtractionEngine {
   ): Promise<ExtractionResult> {
     if (!resolvePipelineProcessingCapabilities(this.config).proactiveExtraction) return base;
     const maxAdditional = Math.max(0, Math.floor(this.config.maxProactiveQuestionsPerExtraction));
-    if (maxAdditional === 0) return base;
-    if (this.config.proactiveExtractionTimeoutMs === 0) return base;
-    if (this.config.proactiveExtractionMaxTokens === 0) return base;
+    if (!shouldRunProactivePass(this.config, maxAdditional, this.shouldUseLocalLlm, this.localLlm)) return base;
 
     try {
       const proactive = await this.generateProactiveQuestions(conversation, base, maxAdditional);

package/src/faithfulness-graph-guard.test.ts

@@ -26,6 +26,8 @@ import { readEdges } from "./graph.js";
 import type { ExtractionResult, PluginConfig } from "./types.js";
 import type { LocalLlmClient } from "./local-llm.js";
 import type { BufferTurn, ConversationThread } from "./types.js";
+import type { PersistExtractionFn } from "./testing/orchestrator-lite.js";
+import type { StorageManager } from "./storage.js";
 
 /**
  * Stub local LLM whose `chatCompletion` only answers faithfulness-gate calls
@@ -126,33 +128,18 @@ test("pending_review fact gets no graph edge; an active fact with the same entit
       faithfulnessStubLocalLlm((c) =>
         c.includes("closed permanently") ? "unsupported" : "entailed",
       );
-    const storage = await (orchestrator as unknown as {
-      getStorage: (ns: string) => Promise<{
-        ensureDirectories: () => Promise<void>;
-        readAllMemories: () => Promise<
-          Array<{
-            path: string;
-            frontmatter: { id: string; status?: string };
-          }>
-        >;
-      }>;
-    }).getStorage("default");
+    // getStorage + persistExtraction are private; reach them through a named production-typed surface.
+    const persist = orchestrator as unknown as {
+      getStorage: (ns: string) => Promise<StorageManager>;
+      persistExtraction: PersistExtractionFn;
+    };
+    const storage = await persist.getStorage("default");
     await storage.ensureDirectories();
 
     const sourceText =
       "The widget factory produces widgets. It launched last year. The team is small.";
 
-    const ids0 = await (orchestrator as unknown as {
-      persistExtraction: (
-        r: ExtractionResult,
-        s: unknown,
-        t: unknown,
-        ctx: unknown,
-        bn: unknown,
-        plan: unknown,
-        src: string,
-      ) => Promise<string[]>;
-    }).persistExtraction(
+    const { persistedIds: ids0 } = await persist.persistExtraction(
       factResult("The widget factory produces widgets daily.", "widget-factory"),
       storage,
       null,
@@ -166,17 +153,7 @@ test("pending_review fact gets no graph edge; an active fact with the same entit
 
     // fact1 → unsupported (pending_review). Under the bug it would originate an
     // entity edge to fact0; under the guard it must NOT.
-    const ids1 = await (orchestrator as unknown as {
-      persistExtraction: (
-        r: ExtractionResult,
-        s: unknown,
-        t: unknown,
-        ctx: unknown,
-        bn: unknown,
-        plan: unknown,
-        src: string,
-      ) => Promise<string[]>;
-    }).persistExtraction(
+    const { persistedIds: ids1 } = await persist.persistExtraction(
       factResult(
         "The widget factory closed permanently.",
         "widget-factory",
@@ -216,17 +193,7 @@ test("pending_review fact gets no graph edge; an active fact with the same entit
 
     // Control: an ACTIVE fact with the same entityRef DOES create entity edges
     // (proving the graph is wired and only pending_review is excluded).
-    const ids2 = await (orchestrator as unknown as {
-      persistExtraction: (
-        r: ExtractionResult,
-        s: unknown,
-        t: unknown,
-        ctx: unknown,
-        bn: unknown,
-        plan: unknown,
-        src: string,
-      ) => Promise<string[]>;
-    }).persistExtraction(
+    const { persistedIds: ids2 } = await persist.persistExtraction(
       factResult("The widget factory reopened this quarter.", "widget-factory"),
       storage,
       null,
@@ -312,26 +279,6 @@ function twoFactResult(
   } as unknown as ExtractionResult;
 }
 
-interface StorageLike {
-  ensureDirectories: () => Promise<void>;
-  dir: string;
-  readAllMemories: () => Promise<
-    Array<{ path: string; frontmatter: { id: string; status?: string } }>
-  >;
-}
-
-interface PersistExtractionSig {
-  (
-    r: ExtractionResult,
-    s: unknown,
-    t: string | null,
-    ctx: unknown,
-    bn: unknown,
-    plan: unknown,
-    src: string,
-  ): Promise<string[]>;
-}
-
 test("pending_review id must NOT enter persisted thread episodes across a cross-flush (#1635)", async () => {
   const { orchestrator, memoryDir } = await makeThreadHarness();
   try {
@@ -342,7 +289,7 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
       );
 
     const getStorage = orchestrator as unknown as {
-      getStorage: (ns: string) => Promise<StorageLike>;
+      getStorage: (ns: string) => Promise<StorageManager>;
     };
     const storage = await getStorage.getStorage("default");
     await storage.ensureDirectories();
@@ -365,10 +312,10 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
     assert.ok(threadId, "thread established via processTurn");
 
     const persist = orchestrator as unknown as {
-      persistExtraction: PersistExtractionSig;
+      persistExtraction: PersistExtractionFn;
       appendPersistedThreadEpisodes: (
         threadId: string,
-        persistedIds: string[],
+        persistedIds: string[]
       ) => Promise<void>;
     };
 
@@ -376,7 +323,7 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
       "The widget factory reopened this quarter after being closed permanently last year.";
 
     // --- Flush 1: an active fact + a pending_review fact, same thread ---
-    const flush1 = await persist.persistExtraction(
+    const { persistedIds: flush1 } = await persist.persistExtraction(
       twoFactResult(
         "The widget factory reopened this quarter.", "wf-active",
         "The widget factory closed permanently last year.", "wf-pending",
@@ -419,7 +366,7 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
     );
 
     // --- Flush 2: an active fact in the SAME thread ---
-    const flush2 = await persist.persistExtraction(
+    const { persistedIds: flush2 } = await persist.persistExtraction(
       factResult("The widget factory hired ten new engineers.", "wf-active"),
       storage,
       threadId,