@remnic/core 9.69.30 → 9.69.32

package/src/briefing-window.ts

@@ -1,27 +1,216 @@
 import { log } from "./logger.js";
 import type { MemoryFile } from "./types.js";
+import { isAbortError } from "./abort-error.js";
+import type { CorpusReadOptions } from "./corpus-read-cancellation.js";
+import type { ParsedBriefingWindow } from "./briefing.js";
+
 type BriefingMemoryReader = {
   readMemoriesWindow?: (options: { updatedAfter?: Date }) => Promise<{ memories: MemoryFile[] }>;
-  readAllMemories: () => Promise<MemoryFile[]>;
+  readAllMemories: ((options?: CorpusReadOptions) => Promise<MemoryFile[]>) & {
+    supportsAbortSignal?: boolean;
+  };
+  supportsAbortSignal?: boolean;
+  supportsCancellation?: boolean;
+  cancellable?: boolean;
 };
-import type { ParsedBriefingWindow } from "./briefing.js";
+
+/**
+ * Deadline for the legacy full-read fallback (issue #2779). Storage doubles
+ * that predate `readMemoriesWindow()` can only answer with a full-corpus
+ * `readAllMemories()`, which is unbounded work; on a large corpus that read
+ * alone can outlast the 60s MCP client timeout. Arm an AbortController with
+ * this budget (well under 60s, leaving room for entity reads and follow-ups)
+ * and fail open with an empty read. The deadline reaches the read as an
+ * abort signal (the #2307 corpus-read contract), so the scan stops at its
+ * next boundary instead of being abandoned to run on in the background.
+ */
+export const BRIEFING_FULL_READ_FALLBACK_MS = 30_000;
+
+/** Options for {@link safeReadMemories}. */
+export interface SafeReadMemoriesOptions {
+  /** Test seam overriding {@link BRIEFING_FULL_READ_FALLBACK_MS}. */
+  fallbackDeadlineMs?: number;
+}
+
+type BriefingReadMode = "windowed" | "full-read-fallback";
+type BriefingReadOutcome = "success" | "timeout" | "error";
+
+/** Internal marker: the fallback deadline fired and the read was aborted. */
+class BriefingReadTimedOut extends Error {
+  constructor(readonly deadlineMs: number) {
+    super("briefing full-read fallback timed out");
+    this.name = "BriefingReadTimedOut";
+  }
+}
+
+/** Internal marker: the adapter's readAllMemories predates the signal contract. */
+class LegacyReadUnsupported extends Error {
+  constructor() {
+    super("readAllMemories does not accept an abort signal");
+    this.name = "LegacyReadUnsupported";
+  }
+}
+
+const SAFE_ERROR_CLASSES: Record<string, true> = {
+  Error: true,
+  TypeError: true,
+  RangeError: true,
+  ReferenceError: true,
+  SyntaxError: true,
+  URIError: true,
+  EvalError: true,
+  AggregateError: true,
+  AbortError: true,
+  TimeoutError: true,
+  SystemError: true,
+  BriefingReadTimedOut: true,
+  LegacyReadUnsupported: true,
+  StorageError: true,
+  EngramAccessInputError: true,
+};
+
+/**
+ * Sanitize adapter-controlled Error.name before structured discriminator logs
+ * (issue #2827). Allow-lists known system/remnic error names and maps any
+ * unrecognized or backend-controlled names to a safe bounded class ("CustomError").
+ */
+function errorClass(err: unknown): string {
+  if (err instanceof Error) {
+    const name = err.name;
+    if (typeof name === "string" && SAFE_ERROR_CLASSES[name] === true) {
+      return name;
+    }
+    return "CustomError";
+  }
+  return typeof err === "string"
+    ? "string"
+    : typeof err === "object" && err !== null
+      ? "object"
+      : typeof err;
+}
+
+function bestEffortLog(level: "info" | "warn", message: string): void {
+  try {
+    log[level](message);
+  } catch {
+    // Diagnostics must never turn a successful or fail-open briefing read into
+    // a request failure when a host logger transport is unavailable.
+  }
+}
+
+/**
+ * One structured, content-free discriminator per briefing memory read
+ * (issue #2779): `mode`, `durationMs`, `count` when known, `outcome`, and on
+ * failure a safe error class — never error messages or memory content.
+ */
+function logBriefingMemoryRead(
+  mode: BriefingReadMode,
+  outcome: BriefingReadOutcome,
+  durationMs: number,
+  resultCount: number | undefined,
+  errClass: string | undefined,
+): void {
+  const fields = [
+    `mode=${mode}`,
+    `durationMs=${durationMs}`,
+    ...(resultCount === undefined ? [] : [`count=${resultCount}`]),
+    `outcome=${outcome}`,
+    ...(errClass === undefined ? [] : [`err=${errClass}`]),
+  ];
+  bestEffortLog("info", `briefing: memory read ${fields.join(" ")}`);
+}
 
 /** Read only the memories needed by a briefing, with compatibility fallback. */
 export async function safeReadMemories(
   storage: BriefingMemoryReader,
-  window: ParsedBriefingWindow
+  window: ParsedBriefingWindow,
+  options: SafeReadMemoriesOptions = {},
 ): Promise<MemoryFile[]> {
+  const startedAt = Date.now();
+  const mode: BriefingReadMode =
+    typeof storage.readMemoriesWindow === "function" ? "windowed" : "full-read-fallback";
+  let outcome: BriefingReadOutcome = "error";
+  let resultCount: number | undefined;
+  let errClass: string | undefined;
   try {
-    // A briefing only needs memories inside its lookback window. Avoid parsing
-    // the full corpus on cache misses; keep the full-read fallback for custom
-    // StorageManager-compatible callers that predate readMemoriesWindow().
-    if (typeof storage.readMemoriesWindow === "function") {
-      const result = await storage.readMemoriesWindow({ updatedAfter: window.from });
-      return result.memories;
-    }
-    return await storage.readAllMemories();
+    const memories = await readBriefingMemories(storage, window, mode, options);
+    outcome = "success";
+    resultCount = memories.length;
+    return memories;
   } catch (err) {
-    log.warn(`briefing: read memories failed: ${err}`);
+    if (err instanceof BriefingReadTimedOut) {
+      outcome = "timeout";
+      bestEffortLog(
+        "warn",
+        `briefing: memory read mode=full-read-fallback timed out after ${err.deadlineMs}ms — ` +
+          `returning no memories (storage adapter lacks readMemoriesWindow; upgrade it to ` +
+          `windowed or signal-aware reads)`,
+      );
+    } else if (err instanceof LegacyReadUnsupported) {
+      errClass = errorClass(err);
+      bestEffortLog(
+        "warn",
+        `briefing: memory read mode=full-read-fallback refused: readAllMemories() takes no abort ` +
+          `signal, so its scan could not be stopped at the deadline — returning no memories ` +
+          `(upgrade the storage adapter to readMemoriesWindow or a signal-aware readAllMemories)`,
+      );
+    } else {
+      errClass = errorClass(err);
+      bestEffortLog("warn", `briefing: read memories failed (${errClass}) — returning no memories`);
+    }
     return [];
+  } finally {
+    logBriefingMemoryRead(mode, outcome, Date.now() - startedAt, resultCount, errClass);
+  }
+}
+
+async function readBriefingMemories(
+  storage: BriefingMemoryReader,
+  window: ParsedBriefingWindow,
+  mode: BriefingReadMode,
+  options: SafeReadMemoriesOptions,
+): Promise<MemoryFile[]> {
+  // A briefing only needs memories inside its lookback window. Avoid parsing
+  // the full corpus on cache misses; keep the full-read fallback for custom
+  // StorageManager-compatible callers that predate readMemoriesWindow().
+  if (mode === "windowed") {
+    const result = await storage.readMemoriesWindow!({ updatedAfter: window.from });
+    return result.memories;
+  }
+  // Refuse legacy adapters that do not explicitly declare cancellation support (#2827).
+  // Require affirmative cancellation support (`true` on one explicit marker) before fallback.
+  // Do not rely on Function.length, which is zero for default/rest/bound functions.
+  const isCancellable =
+    storage.supportsAbortSignal === true ||
+    storage.supportsCancellation === true ||
+    storage.cancellable === true ||
+    storage.readAllMemories?.supportsAbortSignal === true;
+  if (!isCancellable) {
+    throw new LegacyReadUnsupported();
+  }
+  const deadlineMs = options.fallbackDeadlineMs ?? BRIEFING_FULL_READ_FALLBACK_MS;
+  const controller = new AbortController();
+  let deadlineFired = false;
+  const timer = setTimeout(() => {
+    deadlineFired = true;
+    controller.abort();
+  }, deadlineMs);
+  try {
+    // Direct await, no Promise.race: the signal IS the deadline. A
+    // signal-aware read settles on abort (AbortError at its next scan
+    // boundary, #2307), so nothing is left scanning in the background once
+    // this function returns.
+    const memories = await storage.readAllMemories({ abortSignal: controller.signal });
+    if (deadlineFired) {
+      // A double that resolves partial rows instead of rejecting on abort
+      // must not have them served as a complete corpus.
+      throw new BriefingReadTimedOut(deadlineMs);
+    }
+    return memories;
+  } catch (err) {
+    if (isAbortError(err) && deadlineFired) throw new BriefingReadTimedOut(deadlineMs);
+    throw err;
+  } finally {
+    clearTimeout(timer);
   }
 }

package/src/briefing.test.ts

@@ -963,7 +963,8 @@ test("buildBriefing excludes support passport records from generated context", a
     content: "Public project update",
   };
   const storage = {
-    readAllMemories: async () => [privateMemory, publicMemory],
+    supportsAbortSignal: true,
+    readAllMemories: async (_options?: { abortSignal?: AbortSignal }) => [privateMemory, publicMemory],
     readAllEntityFiles: async () => [],
   } as unknown as StorageManager;
 

package/src/orchestration/extraction-shutdown.ts

@@ -1,16 +1,8 @@
 import { log } from "../logger.js";
 
-export interface ExtractionDrainPort {
-  pauseAndDrain(): Promise<boolean>;
-}
-
-export interface DependencyPropagationShutdownPort {
-  shutdown(): Promise<void>;
-}
-
 export async function drainExtractionAndShutdownDependencyPropagation(
-  extractionQueue: ExtractionDrainPort,
-  dependencyPropagationDelivery: DependencyPropagationShutdownPort | undefined,
+  extractionQueue: { pauseAndDrain(): Promise<boolean> },
+  dependencyPropagationDelivery: { shutdown(): Promise<void> } | undefined,
 ): Promise<unknown | undefined> {
   let extractionDrainError: unknown;
   try {

package/src/orchestration/graph-recall-coordinator.ts

@@ -56,6 +56,24 @@ export interface GraphRecallShadowComparison {
   averageOverlapDelta: number;
 }
 
+export interface GraphRecallExpansionOptions {
+  memoryResults: QmdSearchResult[];
+  recallNamespaces: string[];
+  recallResultLimit: number;
+  /** Query-time instant used for graph-path invalidity checks. */
+  asOf?: string;
+  asOfMs?: number;
+  deadlineAtMs?: number | null;
+  /** Issue #681 — when true, bypass graphTraversalConfidenceFloor. */
+  includeLowConfidence?: boolean;
+}
+
+export interface GraphRecallExpansionResult {
+  merged: QmdSearchResult[];
+  seedPaths: string[];
+  expandedPaths: GraphRecallExpandedEntry[];
+  seedResults: QmdSearchResult[];
+}
 // ---------------------------------------------------------------------------
 // Utility functions (moved from orchestrator.ts; re-exported for callers)
 // ---------------------------------------------------------------------------
@@ -193,22 +211,7 @@ export class GraphRecallCoordinator {
   }
 
 
-  async expandResultsViaGraph(options: {
-    memoryResults: QmdSearchResult[];
-    recallNamespaces: string[];
-    recallResultLimit: number;
-    /** Query-time instant used for graph-path invalidity checks. */
-    asOf?: string;
-    asOfMs?: number;
-    deadlineAtMs?: number | null;
-    /** Issue #681 — when true, bypass graphTraversalConfidenceFloor. */
-    includeLowConfidence?: boolean;
-  }): Promise<{
-    merged: QmdSearchResult[];
-    seedPaths: string[];
-    expandedPaths: GraphRecallExpandedEntry[];
-    seedResults: QmdSearchResult[];
-  }> {
+  async expandResultsViaGraph(options: GraphRecallExpansionOptions): Promise<GraphRecallExpansionResult> {
     const config = this.getConfig();
     const parsedAsOfMs =
       typeof options.asOf === "string" ? Date.parse(options.asOf) : Number.NaN;

package/src/orchestration/namespace-read-fanout.ts

@@ -23,7 +23,7 @@ import { NamespaceCatalog } from "../namespaces/catalog.js";
 import { namespaceIdentityFromToken, namespaceIdentityToken, normalizeNamespaceIdentity } from "../namespaces/identity.js";
 import { NamespaceSearchRouter } from "../namespaces/search.js";
 import { NamespaceStorageRouter } from "../namespaces/storage.js";
-import { mergeArtifactRecallCandidates, tokenizeRecallQuery } from "./orchestrator-helpers.js";
+import { ARTIFACT_STATUS_CACHE_TTL_MS, mergeArtifactRecallCandidates, tokenizeRecallQuery } from "./orchestrator-helpers.js";
 import { qmdCollectionPathParts } from "./qmd-result-resolver.js";
 import { qmdCollectionNamespaceFromPrefix as computeQmdCollectionNamespaceFromPrefix } from "./orchestrator-namespace-scope.js";
 import { resolveNamespaceFromStorageDir } from "../scopes/scope-plan.js";
@@ -31,9 +31,6 @@ import { checkCorpusReadAbort, type CorpusReadOptions } from "../corpus-read-can
 import type { ArtifactRecallOptions } from "./recall-search-prefilter.js";
 import type { SearchBackend, SearchExecutionOptions, SearchQueryOptions } from "../search/port.js";
 import type { MemoryFile, PluginConfig, QmdSearchResult } from "../types.js";
-import {
-  Orchestrator,
-} from "../orchestrator.js";
 
 export interface NamespaceReadFanoutDeps {
   readonly artifactSourceStatusCache: WeakMap<StorageManager, { loadedAtMs: number; statusVersion: number; statuses: Map<string, "active" | "superseded" | "archived" | "missing"> }>;
@@ -257,7 +254,7 @@ export class NamespaceReadFanoutCoordinator {
     const isFresh =
       snapshot !== undefined &&
       Date.now() - snapshot.loadedAtMs <=
-        Orchestrator.ARTIFACT_STATUS_CACHE_TTL_MS &&
+        ARTIFACT_STATUS_CACHE_TTL_MS &&
       snapshot.statusVersion === currentStatusVersion;
 
     const rebuildSnapshot = async () => {

package/src/orchestration/orchestrator-helpers.ts

@@ -32,6 +32,8 @@ import { type BufferTurn, type MemoryActionEvent, type MemoryFile, type MemoryFr
 import { categoryDirName } from "../utils/category-dir.js";
 import { parseFlexibleIsoTimestamp } from "../utils/iso-timestamp.js";
 
+/** Freshness window for the artifact source status cache read by NamespaceReadFanoutCoordinator. */
+export const ARTIFACT_STATUS_CACHE_TTL_MS = 60_000;
 export interface BulkImportBatchIngestResult {
   attemptedTurnCount: number;
   extractionCount: number;

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

@@ -35,11 +35,7 @@ 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 {
-  GraphRecallExpansionOptions,
-  GraphRecallExpansionResult,
-} from "./graph-recall-seam.js";
+import type { GraphRecallExpansionOptions, GraphRecallExpansionResult, GraphRecallRankedResult, GraphRecallShadowComparison } from "./graph-recall-coordinator.js";
 import type { RecallRerankCoordinator, RecallResultPartitionSink } from "./recall-rerank-coordinator.js";
 import type { ArtifactRecallOptions } from "./recall-search-prefilter.js";
 import type { RecallSectionAppendOptions, RecallSectionBuckets } from "./recall-section-coordinator.js";

package/src/orchestration/recall-search-pipeline.ts

@@ -28,10 +28,7 @@ import { NamespaceStorageRouter } from "../namespaces/storage.js";
 import { NegativeExampleStore } from "../negative.js";
 import { qmdCollectionPathParts } from "./qmd-result-resolver.js";
 import type { RecallRerankCoordinator, RecallResultPartitionSink } from "./recall-rerank-coordinator.js";
-import type {
-  GraphRecallExpansionOptions,
-  GraphRecallExpansionResult,
-} from "./graph-recall-seam.js";
+import type { GraphRecallExpansionOptions, GraphRecallExpansionResult } from "./graph-recall-coordinator.js";
 import { RelevanceStore } from "../relevance.js";
 import { RerankCache, rerankLocalOrNoop, reorderByRankedKeys } from "../rerank.js";
 import type { SearchBackend, SearchDegradation, SearchExecutionOptions, SearchQueryOptions } from "../search/port.js";

package/src/orchestrator.ts

@@ -132,7 +132,7 @@ import { isDependencyPropagationEnabled } from "./orchestration/dependency-propa
 import { createDependencyPropagationReplayReconciliation } from "./orchestration/dependency-propagation-replay-reconciliation.js";
 import { RecallInternalCoordinator } from "./orchestration/recall-internal.js";
 import { RecallSearchPipelineCoordinator } from "./orchestration/recall-search-pipeline.js";
-import type { GraphRecallExpansionOptions, GraphRecallExpansionResult } from "./orchestration/graph-recall-seam.js";
+import type { GraphRecallExpansionOptions, GraphRecallExpansionResult } from "./orchestration/graph-recall-coordinator.js";
 import type { ArtifactRecallOptions } from "./orchestration/recall-search-prefilter.js";
 import type { CorpusReadOptions } from "./corpus-read-cancellation.js";
 import { TurnIngestionCoordinator, type TurnIngestionOptions } from "./orchestration/turn-ingestion.js";
@@ -716,8 +716,6 @@ export class Orchestrator {
       statuses: Map<string, "active" | "superseded" | "archived" | "missing">;
     }
   >();
-  /** Read by NamespaceReadFanoutCoordinator (seam 26), hence not `private`. */
-  static readonly ARTIFACT_STATUS_CACHE_TTL_MS = 60_000;
 
   // Batched access-tracking counts and timestamps (Phase 1A).
   private accessTrackingBuffer: Map<