@remnic/core 9.29.1 → 9.30.1

package/src/maintenance/purge.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { access, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -9,6 +9,7 @@ import { rebuildMemoryProjection } from "./rebuild-memory-projection.js";
 import { readProjectedMemoryBrowse } from "../memory-projection-store.js";
 import { StorageManager } from "../storage.js";
 import type { MemoryFile } from "../types.js";
+import { buildExplicitCaptureDedupKey } from "../storage/tombstone-blocked-capture-index.js";
 
 test("purgeMemories records audit errors without blocking hard delete", async () => {
   const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-purge-"));
@@ -38,6 +39,10 @@ test("purgeMemories records audit errors without blocking hard delete", async ()
       readAllMemories: async () => [],
       readAllColdMemories: async () => [memory],
       readArchivedMemories: async () => [],
+      deleteMemoryForMaintenance: async (candidate: MemoryFile) => {
+        await unlink(candidate.path);
+        return candidate;
+      },
     };
 
     const result = await purgeMemories({
@@ -108,6 +113,10 @@ test("purgeMemories invalidates projection rows for already-absent files but not
       dir,
       readAllMemories: async () => [firstMemory, secondMemory],
       readAllColdMemories: async () => [],
+      deleteMemoryForMaintenance: async (candidate: MemoryFile) => {
+        await unlink(candidate.path);
+        return candidate;
+      },
       readArchivedMemories: async () => [],
     };
     const future = () => new Date(Date.now() + 86_400_000);
@@ -130,6 +139,153 @@ test("purgeMemories invalidates projection rows for already-absent files but not
   }
 });
 
+test("cleanExpiredCommitments coordinates blocked capture deletion", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-commitment-delete-lock-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    storage.setTombstonesConfig({
+      enabled: true,
+      semanticMatch: false,
+      semanticThreshold: 0.9,
+      namespace: "default",
+    });
+    const content = "A blocked commitment must not disappear under a concurrent capture.";
+    const tombstoneId = await storage.appendTombstone({
+      reason: "correction",
+      createdBy: "user_correction",
+      sourceMemoryId: "commitment-delete-lock",
+      rawContent: content,
+    });
+    assert.ok(tombstoneId);
+    const result = await storage.writeMemory("fact", content, {
+      source: "test",
+      sourceConnector: "provider-a",
+    });
+    assert.equal(result.tombstoneBlocked, true);
+    const blocked = await storage.getMemoryById(result.id);
+    assert.ok(blocked);
+    assert.equal(
+      await storage.writeMemoryFrontmatter(blocked, {
+        category: "commitment",
+        tags: ["fulfilled"],
+      }),
+      true,
+    );
+    const identity = buildExplicitCaptureDedupKey(content, "commitment", "provider-a");
+    const release = Promise.withResolvers<void>();
+    const entered = Promise.withResolvers<void>();
+    const held = storage.withTombstoneBlockedCaptureWriteLock(async () => {
+      entered.resolve();
+      await release.promise;
+    }, identity);
+    await entered.promise;
+
+    let completed = false;
+    const pending = storage.cleanExpiredCommitments(-1).then((deleted) => {
+      completed = true;
+      return deleted;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    assert.equal(completed, false, "commitment cleanup must wait for the blocked capture identity lock");
+    release.resolve();
+    await held;
+    const deleted = await pending;
+    assert.equal(deleted.length, 1);
+    assert.equal(deleted[0]?.frontmatter.id, result.id);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("purgeMemories coordinates blocked capture deletion", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-purge-delete-lock-"));
+  try {
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    storage.setTombstonesConfig({
+      enabled: true,
+      semanticMatch: false,
+      semanticThreshold: 0.9,
+      namespace: "default",
+    });
+    const content = "A blocked memory must not disappear under a concurrent capture.";
+    const tombstoneId = await storage.appendTombstone({
+      reason: "correction",
+      createdBy: "user_correction",
+      sourceMemoryId: "purge-delete-lock",
+      rawContent: content,
+    });
+    assert.ok(tombstoneId);
+    const result = await storage.writeMemory("fact", content, {
+      source: "test",
+      sourceConnector: "provider-a",
+    });
+    assert.equal(result.tombstoneBlocked, true);
+    const blocked = await storage.getMemoryById(result.id);
+    assert.ok(blocked);
+    const identity = buildExplicitCaptureDedupKey(content, "fact", "provider-a");
+    const release = Promise.withResolvers<void>();
+    const entered = Promise.withResolvers<void>();
+    const held = storage.withTombstoneBlockedCaptureWriteLock(async () => {
+      entered.resolve();
+      await release.promise;
+    }, identity);
+    await entered.promise;
+
+    let completed = false;
+    const pending = purgeMemories({
+      storage,
+      olderThanMs: 1,
+      tier: "all",
+      dryRun: false,
+      now: () => new Date(Date.now() + 86_400_000),
+    }).then((purged) => {
+      completed = true;
+      return purged;
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    assert.equal(completed, false, "purge must wait for the blocked capture identity lock");
+    release.resolve();
+    await held;
+    const purged = await pending;
+    assert.equal(purged.purgedCount, 1);
+    assert.equal(await fileExists(blocked.path), false);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("maintenance deletion prefers the candidate path when IDs overlap across tiers", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-delete-tier-path-"));
+  try {
+    StorageManager.clearAllStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    const content = "The cold candidate path must win when a hot copy shares its ID.";
+    const result = await storage.writeMemory("fact", content, {
+      source: "test",
+      sourceConnector: "provider-a",
+    });
+    const hot = await storage.getMemoryById(result.id);
+    assert.ok(hot);
+    const coldPath = storage.buildTierMemoryPath(hot, "cold");
+    await mkdir(path.dirname(coldPath), { recursive: true });
+    await writeFile(coldPath, await readFile(hot.path));
+    StorageManager.clearAllStaticCaches();
+
+    const cold = (await storage.readAllColdMemories()).find((memory) => memory.frontmatter.id === result.id);
+    assert.ok(cold);
+    const removed = await storage.deleteMemoryForMaintenance(cold);
+    assert.equal(removed?.path, coldPath);
+    assert.equal(await fileExists(coldPath), false);
+    assert.equal(await fileExists(hot.path), true);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
 async function fileExists(filePath: string): Promise<boolean> {
   try {
     await access(filePath);

package/src/maintenance/purge.ts

@@ -20,7 +20,7 @@
  */
 
 import path from "node:path";
-import { appendFile, mkdir, unlink } from "node:fs/promises";
+import { appendFile, mkdir } from "node:fs/promises";
 import type { StorageManager } from "../storage.js";
 import type { MemoryFile } from "../types.js";
 import { markProjectedMemoryPathInvalid } from "../memory-projection-store.js";
@@ -168,7 +168,7 @@ export async function purgeMemories(
 
   // Build candidate list
   const candidates: PurgeCandidate[] = [];
-  const candidateMemoriesById = new Map<string, MemoryFile>();
+  const candidateMemoriesByPath = new Map<string, MemoryFile>();
   for (const { memory, resolvedTier } of poolEntries) {
     const ts = resolveTimestamp(memory);
     if (ts.length === 0) continue;
@@ -193,7 +193,7 @@ export async function purgeMemories(
       updatedOrCreated: ts,
       ageMs,
     });
-    candidateMemoriesById.set(memory.frontmatter.id, memory);
+    candidateMemoriesByPath.set(memory.path, memory);
   }
 
   if (dryRun) {
@@ -234,13 +234,19 @@ export async function purgeMemories(
 
   for (const candidate of candidates) {
     try {
-      await unlink(candidate.path);
-      actuallyPurged.push(candidate);
-      addCollectionForCandidate(candidate);
-      markProjectedMemoryPathInvalid(storage.dir, candidate.id);
+      const memory = candidateMemoriesByPath.get(candidate.path);
+      if (!memory) throw new Error(`purge candidate memory missing: ${candidate.id}`);
+      const removed = await storage.deleteMemoryForMaintenance(memory);
+      if (removed) {
+        actuallyPurged.push(candidate);
+        addCollectionForCandidate(candidate);
+      } else {
+        alreadyAbsent.push(candidate);
+        addCollectionForCandidate(candidate);
+        markProjectedMemoryPathInvalid(storage.dir, candidate.id);
+      }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      // ENOENT is fine — already gone
       if (hasErrorCode(err, "ENOENT")) {
         alreadyAbsent.push(candidate);
         addCollectionForCandidate(candidate);
@@ -302,7 +308,7 @@ export async function purgeMemories(
   }
 
   const purgedFactMemories = resolvedPurges
-    .map((candidate) => candidateMemoriesById.get(candidate.id))
+    .map((candidate) => candidateMemoriesByPath.get(candidate.path))
     .filter((memory): memory is MemoryFile => memory?.frontmatter.category === "fact");
   if (purgedFactMemories.length > 0) {
     const removeFactHashes = (

package/src/orchestration/recall-internal-deps.ts

@@ -0,0 +1,385 @@
+/**
+ * recall-internal-deps.ts — the `RecallInternalDeps` contract (issue #1526
+ * seam 18), extracted from recall-internal.ts so that file can stay under
+ * its frozen ratchet ceiling while recall work proceeds (#2183). Pure type
+ * relocation: no behavior change, no renames, no member reordering.
+ */
+
+import type { BoxBuilder } from "../boxes.js";
+import type { CapabilitySet, GraphConstructionCapabilitySet } from "../capabilities.js";
+import type { CausalTrajectorySearchResult } from "../causal-trajectory.js";
+import type { CompoundingEngine } from "../compounding/engine.js";
+import type { EvalShadowRecallRecord } from "../evals.js";
+import type { HarmonicRetrievalResult } from "../harmonic-retrieval.js";
+import type { StorageManager } from "../index.js";
+import type { LcmEngine } from "../lcm/index.js";
+import type { NamespaceCatalog } from "../namespaces/catalog.js";
+import type { NamespaceStorageRouter } from "../namespaces/storage.js";
+import type { ObjectiveStateSearchResult } from "../objective-state.js";
+import type { IntentDebugSnapshot, QmdRecallSnapshot, QueryAwarePrefilter } from "../orchestrator.js";
+import type { ProfilingCollector } from "../profiling.js";
+import type { GraphRecallExpandedEntry, LastRecallBudgetSummary, LastRecallStore, RecallHandleHistoryStore } from "../recall-state.js";
+import type { RecallXraySnapshot } from "../recall-xray.js";
+import type { RerankCache } from "../rerank.js";
+import type { SearchBackend, SearchDegradation, SearchQueryOptions } from "../search/port.js";
+import type { VerifiedSemanticRuleResult } from "../semantic-rule-verifier.js";
+import type { SharedContextManager } from "../shared-context/manager.js";
+import type { HourlySummarizer } from "../summarizer.js";
+import type { isValidAsOf } from "../temporal-validity.js";
+import type { TmtBuilder } from "../tmt.js";
+import type { TranscriptManager } from "../transcript.js";
+import type { TrustStageResultItem } from "../trust-score-stage.js";
+import type { TrustZoneSearchResult } from "../trust-zones.js";
+import type { CodingContext, EngramTraceEvent, IdentityInjectionMode, MemoryFile, MemoryIntent, PluginConfig, QmdSearchResult, RecallPlanMode, RecallSectionConfig } from "../types.js";
+import type { VerifiedEpisodeResult } from "../verified-recall.js";
+import type { WorkProductLedgerSearchResult } from "../work-product-ledger.js";
+import type { GraphRecallRankedResult, GraphRecallShadowComparison } from "./graph-recall-coordinator.js";
+import type { RecallSectionAppendOptions, RecallSectionBuckets } from "./recall-section-coordinator.js";
+
+export interface RecallInternalDeps {
+  readonly _recallWorkspaceOverrides: Map<string, string>;
+  appendRecallSection(
+    sectionBuckets: RecallSectionBuckets,
+    sectionId: string,
+    content: string,
+    options?: RecallSectionAppendOptions,
+  ): boolean;
+  applyColdFallbackPipeline(options: {
+    prompt: string;
+    recallNamespaces: string[];
+    recallResultLimit: number;
+    recallMode: RecallPlanMode;
+    /**
+     * Recall-operation capability gates resolved once at recall entry (#1523).
+     * OPTIONAL and additive: the recall pipeline threads a resolved set, but
+     * callers that omit it (e.g. direct unit-test invocations) get an
+     * equivalent config-derived set — behavior-preserving.
+     */
+    caps?: CapabilitySet;
+    /** Graph-construction gates resolved at recall entry (#1566 Cluster A). */
+    graphCaps?: GraphConstructionCapabilitySet;
+    queryAwarePrefilter?: QueryAwarePrefilter;
+    abortSignal?: AbortSignal;
+    /** Backend degradation observer — cold-tier QMD must report like hot (#1536). */
+    onDegradation?: (degradation: SearchDegradation) => void;
+    /** Issue #680 — historical recall point in ms-since-epoch. */
+    asOfMs?: number;
+    /**
+     * Optional out-parameter that receives the pre-MMR / pre-truncation
+     * pool size captured inside the pipeline (issue #570 PR 1).  The
+     * X-ray capture block in `recallInternal` passes a small sink so
+     * the cold-fallback branch's pre-truncation pool size can be
+     * attributed back to the branch when `recallSource === "cold_fallback"`.
+     * Unset by default so existing call sites are unaffected.
+     */
+    xrayPoolSizeSink?: { size: number };
+    /**
+     * Issue #1577 — out-parameter that receives the TrustScore stage's
+     * per-path trust map (admitted + quarantined) when the cold path runs
+     * trust scoring. Mirrors the xrayPoolSizeSink pattern so recallInternal
+     can propagate trust data for epistemic rendering and X-ray visibility
+     without changing the cold pipeline's return type.
+     */
+    trustByPathSink?: { trustByPath: Map<string, TrustStageResultItem> | null };
+    deadlineAtMs?: number | null;
+    /** Issue #681 — when true, bypass graphTraversalConfidenceFloor. */
+    includeLowConfidence?: boolean;
+  }): Promise<QmdSearchResult[]>;
+  applyTrustScoreToBranch(
+    results: QmdSearchResult[],
+    namespaces: string[],
+    caps: CapabilitySet,
+    label: string,
+    preloadedFrontmatter?: ReadonlyMap<string, MemoryFile>,
+    abortSignal?: AbortSignal,
+  ): Promise<{
+    results: QmdSearchResult[];
+    trustByPath: Map<string, TrustStageResultItem> | null;
+  }>;
+  assembleRecallSections(
+    sectionBuckets: RecallSectionBuckets,
+    budgetOverride?: number,
+  ): {
+    sections: string[];
+    includedIds: string[];
+    omittedIds: string[];
+    truncated: boolean;
+    finalChars: number;
+    includedMemoryIds: string[];
+    includedMemoryPaths: string[];
+    includedMemoryNamespaces: Array<string | undefined>;
+    omittedMemoryIds: string[];
+  };
+  boostSearchResults(
+    results: QmdSearchResult[],
+    _recallNamespaces: string[],
+    prompt?: string,
+    preloadedMemoryMap?: Map<string, MemoryFile>,
+    options?: {
+      allowLifecycleFiltered?: boolean;
+      allowDedicatedSurface?: boolean;
+      /**
+       * Historical recall point in ms-since-epoch (issue #680).  When
+       * set, drops candidates that were not authoritative at this
+       * instant per `temporal-validity.isValidAsOf`.  Caller is
+       * responsible for parsing/validating the user-supplied ISO
+       * string at the input boundary (CLI / HTTP / MCP).
+       */
+      asOfMs?: number;
+    },
+  ): Promise<QmdSearchResult[]>;
+  boxBuilderFor(storage: StorageManager): BoxBuilder;
+  buildCompressionGuidelineRecallSection(): Promise<string | null>;
+  buildConfiguredQmdSearchOptions(
+    queryText: string,
+  ): SearchQueryOptions | undefined;
+  buildGraphRecallRankedResults(
+    results: QmdSearchResult[],
+    sourceLabelResolver: (path: string) => string[],
+    limit?: number,
+  ): GraphRecallRankedResult[];
+  buildIdentityContinuitySection(options: {
+    storage: StorageManager;
+    recallMode: RecallPlanMode;
+    prompt: string;
+  }): Promise<{
+    section: string;
+    mode: IdentityInjectionMode;
+    injectedChars: number;
+    truncated: boolean;
+  } | null>;
+  buildLastRecallBudgetSummary(options: {
+    requestedTopK?: number;
+    recallResultLimit: number;
+    qmdFetchLimit: number;
+    qmdHybridFetchLimit: number;
+    finalContextChars?: number;
+    truncated?: boolean;
+    includedSections?: string[];
+    omittedSections?: string[];
+    includedMemoryIds?: string[];
+    includedMemoryPaths?: string[];
+    includedMemoryNamespaces?: Array<string | undefined>;
+    omittedMemoryIds?: string[];
+  }): LastRecallBudgetSummary;
+  buildQueryAwarePrefilter(
+    prompt: string,
+    recallNamespaces: string[],
+  ): Promise<QueryAwarePrefilter>;
+  collectLastRecallSources(
+    sectionBuckets: RecallSectionBuckets,
+    recallSource:
+      | "none"
+      | "hot_qmd"
+      | "hot_embedding"
+      | "cold_fallback"
+      | "recent_scan",
+  ): string[];
+  readonly compounding?: CompoundingEngine;
+  readonly config: PluginConfig;
+  currentPolicyVersion(): string;
+  diversifyAndLimitRecallResults(
+    sectionId: string,
+    results: QmdSearchResult[],
+    limit: number,
+    retrievalQuery?: string,
+    caps?: CapabilitySet,
+  ): QmdSearchResult[];
+  effectiveCronRecallInstructionHeavyTokenCap(): number;
+  emitTrace(event: EngramTraceEvent): void;
+  expandResultsViaGraph(options: {
+    memoryResults: QmdSearchResult[];
+    recallNamespaces: string[];
+    recallResultLimit: number;
+    deadlineAtMs?: number | null;
+    includeLowConfidence?: boolean;
+  }): Promise<{
+    merged: QmdSearchResult[];
+    seedPaths: string[];
+    expandedPaths: GraphRecallExpandedEntry[];
+    seedResults: QmdSearchResult[];
+  }>;
+  extractMemoryIdsFromResults(results: QmdSearchResult[]): string[];
+  readonly fastLlmForRerank: {
+    chatCompletion: (
+      messages: Array<{ role: string; content: string }>,
+      options?: { maxTokens?: number; temperature?: number; timeoutMs?: number; operation?: string; priority?: "recall-critical" | "background" },
+    ) => Promise<{ content: string } | null>;
+  };
+  fetchQmdMemoryResultsWithArtifactTopUp(
+    prompt: string,
+    qmdFetchLimit: number,
+    qmdHybridFetchLimit: number,
+    options: {
+      namespacesEnabled: boolean;
+      recallNamespaces: string[];
+      resolveNamespace: (path: string) => string;
+      collection?: string;
+      queryAwarePrefilter?: QueryAwarePrefilter;
+      searchOptions?: SearchQueryOptions;
+      onDebugSnapshot?: (snapshot: QmdRecallSnapshot) => Promise<void>;
+      /** Backend degradation observer, threaded into every QMD call (#1536). */
+      onDegradation?: (degradation: SearchDegradation) => void;
+      abortSignal?: AbortSignal;
+    },
+  ): Promise<QmdSearchResult[]>;
+  filterSearchResultsForRecall(
+    results: QmdSearchResult[],
+    preloadedMemoryMap?: Map<string, MemoryFile>,
+    options?: {
+      allowLifecycleFiltered?: boolean;
+      allowDedicatedSurface?: boolean;
+      asOfMs?: number;
+      deadlineAtMs?: number | null;
+      abortSignal?: AbortSignal;
+      dropUnresolved?: boolean;
+      recallNamespaces?: readonly string[];
+    },
+  ): Promise<{ results: QmdSearchResult[]; memoryByPath: Map<string, MemoryFile> }>;
+  formatCausalTrajectoryResults(
+    results: CausalTrajectorySearchResult[],
+  ): string;
+  formatConversationRecallSection(
+    results: Array<{ path: string; snippet: string; score: number }>,
+    maxChars: number,
+  ): string | null;
+  formatHarmonicRetrievalResults(
+    results: HarmonicRetrievalResult[],
+  ): string;
+  formatObjectiveStateResults(
+    results: ObjectiveStateSearchResult[],
+  ): string;
+  formatQmdResults(
+    title: string,
+    results: QmdSearchResult[],
+    sessionKey?: string,
+    trustByPath?: Map<string, TrustStageResultItem> | null,
+  ): string;
+  formatTrustZoneResults(results: TrustZoneSearchResult[]): string;
+  formatVerifiedEpisodeResults(
+    results: VerifiedEpisodeResult[],
+  ): string;
+  formatVerifiedSemanticRuleResults(
+    results: VerifiedSemanticRuleResult[],
+  ): string;
+  formatWorkProductResults(
+    results: WorkProductLedgerSearchResult[],
+  ): string;
+  getCodingContextForSession(sessionKey: string | undefined): CodingContext | null;
+  getPeerIdForSession(sessionKey: string | undefined): string | null;
+  getRecallBudgetChars(override?: number): number;
+  getRecallSectionEntry(
+    sectionId: string,
+  ): RecallSectionConfig | undefined;
+  getRecallSectionMaxChars(
+    sectionId: string,
+  ): number | null | undefined;
+  getRecallSectionNumber(
+    sectionId: string,
+    key: keyof RecallSectionConfig,
+  ): number | undefined;
+  getStorage(namespace?: string): Promise<StorageManager>;
+  readonly handleHistory: RecallHandleHistoryStore;
+  trackMemoryAccess(
+    memoryIds: string[],
+    memoryPaths?: string[],
+    memoryNamespaces?: Array<string | undefined>,
+  ): void;
+  trackRecallBackgroundWrite(promise: Promise<void>, label: string): void;
+  isRecallSectionEnabled(
+    sectionId: string,
+    defaultEnabled?: boolean,
+  ): boolean;
+  isSpecializedRecallSectionEnabled(
+    sectionId: string,
+    topLevelEnabled: boolean,
+  ): boolean;
+  lastQmdReprobeAtMs: number;
+  readonly lastRecall: LastRecallStore;
+  lastXraySnapshot: RecallXraySnapshot | null;
+  readonly lcmEngine: LcmEngine | null;
+  readonly namespaceCatalog: NamespaceCatalog;
+  namespaceFromPath(p: string): string;
+  readonly profiler: ProfilingCollector;
+  publishRecallResults(options: {
+    title: string;
+    results: QmdSearchResult[];
+    sectionBuckets: RecallSectionBuckets;
+    retrievalQuery: string;
+    sessionKey: string | undefined;
+    identityInjection?: {
+      mode: IdentityInjectionMode | "none";
+      injectedChars: number;
+      truncated: boolean;
+    };
+    /**
+     * Issue #1577 — per-recall trust map. When present, quarantined items
+     * are filtered from injection on EVERY recall path (hot QMD, embedding
+     * fallback, cold archive, recent) so a faithfulness-contradicted memory
+     * cannot sneak in via a branch that bypasses trust scoring (review:
+     * fallback paths bypass trust). The map is also threaded to
+     * formatQmdResults for the epistemic hedge.
+     */
+    trustByPath?: Map<string, TrustStageResultItem> | null;
+  }): void;
+  readonly qmd: SearchBackend;
+  queueEvalShadowRecall(
+    record: Omit<EvalShadowRecallRecord, "schemaVersion">,
+  ): void;
+  readAllMemoriesForNamespaces(
+    namespaces: string[],
+  ): Promise<MemoryFile[]>;
+  recallArtifactsAcrossNamespaces(
+    prompt: string,
+    recallNamespaces: string[],
+    targetCount: number,
+  ): Promise<MemoryFile[]>;
+  recallAssemblyClockMs(): number;
+  recordLastGraphRecallSnapshot(options: {
+    storage: StorageManager;
+    prompt: string;
+    recallMode: RecallPlanMode;
+    recallNamespaces: string[];
+    seedPaths: string[];
+    expandedPaths: GraphRecallExpandedEntry[];
+    status: "completed" | "skipped" | "aborted";
+    reason?: string;
+    shadowMode?: boolean;
+    queryIntent: MemoryIntent;
+    seedResults?: GraphRecallRankedResult[];
+    finalResults?: GraphRecallRankedResult[];
+    shadowComparison?: GraphRecallShadowComparison;
+  }): Promise<void>;
+  recordLastIntentSnapshot(options: {
+    storage: StorageManager;
+    snapshot: IntentDebugSnapshot;
+  }): Promise<void>;
+  recordLastIntentSnapshotForNamespace(options: {
+    namespace: string;
+    snapshot: IntentDebugSnapshot;
+  }): Promise<void>;
+  recordLastQmdRecallSnapshot(options: {
+    storage: StorageManager;
+    snapshot: QmdRecallSnapshot;
+  }): Promise<void>;
+  readonly rerankCache: RerankCache;
+  searchConversationRecallResults(
+    retrievalQuery: string,
+    topK: number,
+  ): Promise<Array<{ path: string; snippet: string; score: number }>>;
+  searchEmbeddingFallback(
+    query: string,
+    limit: number,
+  ): Promise<QmdSearchResult[]>;
+  readonly sharedContext?: SharedContextManager;
+  readonly storage: StorageManager;
+  readonly storageRouter: NamespaceStorageRouter;
+  readonly summarizer: HourlySummarizer;
+  readonly tmtBuilder: TmtBuilder;
+  readonly transcript: TranscriptManager;
+  truncateArtifactForRecall(text: string, maxChars?: number): string;
+  truncateRecallSectionToBudget(
+    content: string,
+    maxChars: number,
+  ): string;
+}