@remnic/core 9.27.0 → 9.28.0

package/src/entity-retrieval.ts

@@ -7,6 +7,7 @@ import { collectNativeKnowledgeChunks, type NativeKnowledgeChunk } from "./nativ
 import { compareEntityTimestamps, normalizeEntityName, type StorageManager } from "./storage.js";
 import { normalizeEntityText, resolveRequestedEntitySectionKeys } from "./entity-schema.js";
 import type { EntityStructuredSection, MemoryFile, PluginConfig, TranscriptEntry } from "./types.js";
+import { containsPhrase } from "./entity-retrieval-boundaries.js";
 
 const ENTITY_INDEX_VERSION = 3;
 const RECENT_TRANSCRIPT_LOOKBACK_HOURS = 24;
@@ -51,6 +52,7 @@ type EntityMentionIndexEntry = {
 type EntityMentionIndex = {
   version: number;
   updatedAt: string;
+  entityStatusVersion?: number;
   entities: EntityMentionIndexEntry[];
 };
 
@@ -89,12 +91,6 @@ function uniqueStrings(values: string[]): string[] {
   return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
 }
 
-function containsPhrase(haystack: string, needle: string): boolean {
-  if (!needle) return false;
-  const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return new RegExp(`(^|\\b)${escaped}(\\b|$)`, "i").test(haystack);
-}
-
 function compactLine(value: string, maxLength: number = 220): string {
   const normalized = value.replace(/\s+/g, " ").trim();
   if (normalized.length <= maxLength) return normalized;
@@ -383,6 +379,57 @@ async function readEntityIndexState(storage: StorageManager): Promise<EntityMent
   }
 }
 
+
+async function readCurrentPersistedEntityIndex(
+  storage: StorageManager,
+  config: PluginConfig,
+  recallNamespaces?: string[],
+  namespaceStorage?: (namespace: string) => Promise<StorageManager>,
+): Promise<EntityMentionIndex | null> {
+  if (
+    resolveNamespaceCapabilities(config).namespaces &&
+    namespaceStorage &&
+    recallNamespaces &&
+    recallNamespaces.length > 0
+  ) {
+    return null;
+  }
+  const index = await readEntityIndexState(storage);
+  if (!index || index.entityStatusVersion !== storage.getMemoryStatusVersion()) {
+    return null;
+  }
+  return index;
+}
+const namespaceEntityIndexCache = new Map<string, EntityMentionIndex>();
+const MAX_NAMESPACE_ENTITY_INDEX_CACHE_ENTRIES = 32;
+
+function namespaceEntityIndexCacheKey(
+  storages: StorageManager[],
+  recallNamespaces: string[],
+): string {
+  const namespaceKey = uniqueStrings(recallNamespaces).sort().join("\u001f");
+  const storageKey = storages
+    .map((scopedStorage) => {
+      const aliases = Object.entries(scopedStorage.entityAliases)
+        .sort(([left], [right]) => left.localeCompare(right));
+      return (
+        `${path.resolve(scopedStorage.dir)}@${scopedStorage.getMemoryStatusVersion()}` +
+        `:${scopedStorage.getMemoryCorpusVersion()}:${scopedStorage.hotCacheKeyId()}:${JSON.stringify(aliases)}`
+      );
+    })
+    .sort()
+    .join("\u001f");
+  return `${namespaceKey}\u001e${storageKey}`;
+}
+
+function rememberNamespaceEntityIndex(key: string, index: EntityMentionIndex): void {
+  if (namespaceEntityIndexCache.size >= MAX_NAMESPACE_ENTITY_INDEX_CACHE_ENTRIES) {
+    const oldestKey = namespaceEntityIndexCache.keys().next().value;
+    if (typeof oldestKey === "string") namespaceEntityIndexCache.delete(oldestKey);
+  }
+  namespaceEntityIndexCache.set(key, index);
+}
+
 async function writeEntityIndexState(storage: StorageManager, index: EntityMentionIndex): Promise<void> {
   const statePath = entityIndexStatePath(storage);
   await mkdir(path.dirname(statePath), { recursive: true });
@@ -438,13 +485,32 @@ function mergeNativeChunk(entry: EntityMentionIndexEntry, chunk: NativeKnowledge
   entry.aliases = uniqueStrings([...entry.aliases, ...(chunk.aliases ?? [])]);
 }
 
+function hasFreshNativeExplicitMention(
+  index: EntityMentionIndex,
+  nativeChunks: NativeKnowledgeChunk[],
+  query: string,
+): boolean {
+  if (nativeChunks.length === 0) return false;
+  const nativeCanonicalIds = new Set(nativeChunks.map(nativePseudoCanonicalId));
+  const freshNativeIndex: EntityMentionIndex = {
+    ...index,
+    entities: [
+      ...index.entities.filter((entry) => !nativeCanonicalIds.has(entry.canonicalId)),
+      ...nativeChunks.map(createPseudoNativeEntry),
+    ],
+  };
+  return resolveLanguageIndependentExplicitCandidates(freshNativeIndex, query).length > 0;
+}
+
 async function buildEntityMentionIndex(
   storage: StorageManager,
   config: PluginConfig,
   recallNamespaces?: string[],
   namespaceStorage?: (namespace: string) => Promise<StorageManager>,
+  nativeChunksOverride?: NativeKnowledgeChunk[],
+  resolvedStorages?: StorageManager[],
 ): Promise<EntityMentionIndex> {
-  const storages = await resolveEntityIndexStorages(
+  const storages = resolvedStorages ?? await resolveEntityIndexStorages(
     storage,
     config,
     recallNamespaces,
@@ -452,23 +518,27 @@ async function buildEntityMentionIndex(
   );
   const shouldPersistIndex =
     storages.length === 1 && path.resolve(storages[0]!.dir) === path.resolve(storage.dir);
+  const entityStatusVersionBefore = shouldPersistIndex ? storage.getMemoryStatusVersion() : undefined;
   const [previousIndex, entityFileSets, memorySets, nativeChunks] = await Promise.all([
     shouldPersistIndex ? readEntityIndexState(storage) : Promise.resolve(null),
     Promise.all(storages.map((scopedStorage) => scopedStorage.readAllEntityFiles())),
     Promise.all(storages.map((scopedStorage) => scopedStorage.readAllMemories())),
-    readNativeChunks(config, recallNamespaces),
+    nativeChunksOverride ? Promise.resolve(nativeChunksOverride) : readNativeChunks(config, recallNamespaces),
   ]);
-  // Pair each entity with the alias table of the store it came from (#1534):
-  // canonical ids must reflect the owning store's aliases, never another
+  // Pair each entity with the storage that owns it (#1534): canonical ids must
+  // reflect that store's aliases and historical migration mappings, never another
   // namespace's.
   const entityRecords = entityFileSets.flatMap((set, index) =>
-    set.map((entity) => ({ entity, aliases: storages[index]!.entityAliases })),
+    set.map((entity) => ({ entity, storage: storages[index]! })),
   );
   const memories = memorySets.flat();
 
   const entities = new Map<string, EntityMentionIndexEntry>();
-  for (const { entity, aliases } of entityRecords) {
-    const canonicalId = normalizeEntityName(entity.name, entity.type, aliases);
+  for (const { entity, storage: entityStorage } of entityRecords) {
+    const canonicalId =
+      typeof entityStorage.normalizeEntityName === "function"
+        ? entityStorage.normalizeEntityName(entity.name, entity.type)
+        : normalizeEntityName(entity.name, entity.type, entityStorage.entityAliases);
     const rawStructuredSections = entity.structuredSections ?? [];
     const rawBeliefLedgerFactKeys = beliefLedgerFactKeys(rawStructuredSections);
     const sanitizedFacts = entity.facts
@@ -539,15 +609,18 @@ async function buildEntityMentionIndex(
   const sortedEntities = [...entities.values()].sort((left, right) => left.name.localeCompare(right.name));
   const previousEntities = previousIndex ? JSON.stringify(previousIndex.entities) : "";
   const nextEntities = JSON.stringify(sortedEntities);
+  const entityStatusVersionAfter = shouldPersistIndex ? storage.getMemoryStatusVersion() : undefined;
+  const canPersistIndex = shouldPersistIndex && entityStatusVersionBefore === entityStatusVersionAfter;
   const index: EntityMentionIndex = {
     version: ENTITY_INDEX_VERSION,
     updatedAt:
       previousIndex && previousEntities === nextEntities
         ? previousIndex.updatedAt
         : new Date().toISOString(),
+    entityStatusVersion: canPersistIndex ? entityStatusVersionAfter : undefined,
     entities: sortedEntities,
   };
-  if (shouldPersistIndex) {
+  if (canPersistIndex) {
     await writeEntityIndexState(storage, index);
   }
   return index;
@@ -575,6 +648,114 @@ function resolveExplicitCandidates(
   return candidates.sort((left, right) => right.score - left.score);
 }
 
+const EXPLICIT_ENTITY_MENTION_SCORE = 9;
+
+const IMPLICIT_ENTITY_STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "can",
+  "do",
+  "for",
+  "from",
+  "has",
+  "how",
+  "i",
+  "if",
+  "in",
+  "is",
+  "it",
+  "me",
+  "my",
+  "of",
+  "on",
+  "or",
+  "the",
+  "to",
+  "was",
+  "what",
+  "when",
+  "where",
+  "who",
+  "why",
+  "with",
+  "you",
+  "your",
+]);
+
+function isDistinctiveImplicitAlias(normalizedAlias: string): boolean {
+  const tokens = normalizedAlias.split(/\s+/).filter(Boolean);
+  if (tokens.length > 1 && tokens.every((token) => IMPLICIT_ENTITY_STOP_WORDS.has(token))) return false;
+  if (tokens.length !== 1) return true;
+  const token = tokens[0]!;
+  return Array.from(token).length > 1 && !IMPLICIT_ENTITY_STOP_WORDS.has(token);
+}
+
+function isShortLatinAlias(alias: string): boolean {
+  return /^[A-Za-z]{2,3}$/.test(alias.trim());
+}
+
+function hasStrongShortLatinAliasMention(query: string, alias: string): boolean {
+  const normalizedAlias = alias.trim();
+  const titleCaseAlias = `${normalizedAlias[0]!.toUpperCase()}${normalizedAlias.slice(1).toLowerCase()}`;
+  const forms = new Set([normalizedAlias, normalizedAlias.toUpperCase(), titleCaseAlias]);
+  return [...forms].some((form) => {
+    if (form === form.toLowerCase()) return false;
+    const escaped = form.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|[^A-Za-z0-9])${escaped}(?:$|[^A-Za-z0-9])`).test(query);
+  });
+}
+
+function resolveLanguageIndependentExplicitCandidates(
+  index: EntityMentionIndex,
+  query: string,
+): EntityCandidate[] {
+  const canonicalIdsByAlias = new Map<string, Set<string>>();
+  for (const entry of index.entities) {
+    for (const alias of uniqueStrings([entry.name, ...entry.aliases])) {
+      const normalizedAlias = normalizeEntityText(alias);
+      if (!normalizedAlias) continue;
+      const canonicalIds = canonicalIdsByAlias.get(normalizedAlias) ?? new Set<string>();
+      canonicalIds.add(entry.canonicalId);
+      canonicalIdsByAlias.set(normalizedAlias, canonicalIds);
+    }
+  }
+
+  const candidates: EntityCandidate[] = [];
+  for (const entry of index.entities) {
+    let bestAlias = "";
+    let bestScore = 0;
+    for (const alias of uniqueStrings([entry.name, ...entry.aliases])) {
+      const normalizedAlias = normalizeEntityText(alias);
+      const score = scoreAliasMatch(query, alias);
+      if (
+        !normalizedAlias ||
+        !isDistinctiveImplicitAlias(normalizedAlias) ||
+        (isShortLatinAlias(alias) && !hasStrongShortLatinAliasMention(query, alias)) ||
+        canonicalIdsByAlias.get(normalizedAlias)?.size !== 1 ||
+        score < EXPLICIT_ENTITY_MENTION_SCORE ||
+        score <= bestScore
+      ) {
+        continue;
+      }
+      bestAlias = alias;
+      bestScore = score;
+    }
+    if (bestAlias) {
+      candidates.push({ entry, alias: bestAlias, score: bestScore, source: "query" });
+    }
+  }
+
+  return candidates.sort(
+    (left, right) => right.score - left.score || left.entry.name.localeCompare(right.entry.name),
+  );
+}
+
 function resolveRecentTurnCandidates(
   index: EntityMentionIndex,
   transcriptEntries: TranscriptEntry[],
@@ -825,26 +1006,71 @@ function formatEntityHintSection(
 }
 
 export async function buildEntityRecallSection(options: BuildEntityRecallSectionOptions): Promise<string | null> {
-  const mode = detectEntityQueryMode(options.query);
-  if (!mode) return null;
-
-  const index = await buildEntityMentionIndex(
-    options.storage,
-    options.config,
-    options.recallNamespaces,
-    options.namespaceStorage,
-  );
-  if (index.entities.length === 0) return null;
-
+  const prefixedMode = detectEntityQueryMode(options.query);
+  const persistedIndex = prefixedMode
+    ? null
+    : await readCurrentPersistedEntityIndex(
+      options.storage,
+      options.config,
+      options.recallNamespaces,
+      options.namespaceStorage,
+    );
+  let nativeChunks: NativeKnowledgeChunk[] | undefined;
+  if (
+    !prefixedMode &&
+    persistedIndex &&
+    resolveLanguageIndependentExplicitCandidates(persistedIndex, options.query).length === 0
+  ) {
+    nativeChunks = await readNativeChunks(options.config, options.recallNamespaces);
+    if (!hasFreshNativeExplicitMention(persistedIndex, nativeChunks, options.query)) {
+      return null;
+    }
+  }
+  const namespaceScoped =
+    resolveNamespaceCapabilities(options.config).namespaces &&
+    options.namespaceStorage !== undefined &&
+    (options.recallNamespaces?.length ?? 0) > 0;
+  const resolvedStorages = namespaceScoped
+    ? await resolveEntityIndexStorages(
+      options.storage,
+      options.config,
+      options.recallNamespaces,
+      options.namespaceStorage,
+    )
+    : undefined;
+  const namespaceCacheKey =
+    resolvedStorages && options.recallNamespaces
+      ? namespaceEntityIndexCacheKey(resolvedStorages, options.recallNamespaces)
+      : undefined;
+  let index: EntityMentionIndex | undefined = namespaceCacheKey
+    ? namespaceEntityIndexCache.get(namespaceCacheKey)
+    : undefined;
+  if (!index) {
+    index = await buildEntityMentionIndex(
+      options.storage,
+      options.config,
+      options.recallNamespaces,
+      options.namespaceStorage,
+      nativeChunks,
+      resolvedStorages,
+    );
+    if (namespaceCacheKey) rememberNamespaceEntityIndex(namespaceCacheKey, index);
+  }
   const explicitCandidates = resolveExplicitCandidates(index, options.query);
-  const candidates = explicitCandidates.length > 0
+  const queryCandidates = prefixedMode
     ? explicitCandidates
+    : resolveLanguageIndependentExplicitCandidates(index, options.query);
+  const mode = prefixedMode ?? (queryCandidates.length > 0 ? "direct" : null);
+  if (!mode) return null;
+
+  const candidates = queryCandidates.length > 0
+    ? queryCandidates
     : resolveRecentTurnCandidates(index, options.transcriptEntries, options.recentTurns);
 
   if (candidates.length === 0) return null;
 
   const queryTokens = tokenize(options.query);
-  const candidateLimit = explicitCandidates.length === 0 && mode === "follow_up"
+  const candidateLimit = queryCandidates.length === 0 && mode === "follow_up"
     ? 1
     : options.maxHints;
   const rankedCandidates = candidates.slice(0, candidateLimit);

package/src/entity-schema.ts

@@ -44,8 +44,9 @@ const DEFAULT_ENTITY_SCHEMAS: Record<string, EntitySchemaDefinition> = {
 
 export function normalizeEntityText(value: string): string {
   return value
+    .normalize("NFC")
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/[^\p{L}\p{M}\p{N}]+/gu, " ")
     .trim();
 }
 

package/src/memory-projection-mutations.ts

@@ -0,0 +1,132 @@
+import { lstat, realpath } from "node:fs/promises";
+import { isErrnoCode } from "./utils/errno.js";
+import { assertPathInsideRoot } from "./utils/path-containment.js";
+import { getMemoryProjectionPath, initializeMemoryProjectionDb } from "./memory-projection-store.js";
+import { type BetterSqlite3Database, openBetterSqlite3 } from "./runtime/better-sqlite.js";
+
+const PROJECTION_WRITE_BUSY_TIMEOUT_MS = 100;
+const PROJECTION_WRITE_RETRY_COUNT = 4;
+const PROJECTION_WRITE_RETRY_DELAY_MS = 100;
+
+function isSqliteBusyError(error: unknown): boolean {
+  const messages: string[] = [];
+  const seen = new Set<unknown>();
+  let current: unknown = error;
+  while (current !== null && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    if (current instanceof Error) messages.push(current.message);
+    if (!("cause" in current)) break;
+    current = current.cause;
+  }
+  const lower = messages.join("\n").toLowerCase();
+  return lower.includes("database is locked") || lower.includes("sqlite_busy");
+}
+
+async function validateProjectionPath(
+  memoryDir: string,
+  projectionPath: string,
+): Promise<boolean> {
+  let projectionStat;
+  try {
+    projectionStat = await lstat(projectionPath);
+  } catch (error) {
+    if (isErrnoCode(error, "ENOENT")) return false;
+    throw error;
+  }
+  if (projectionStat.isSymbolicLink() || !projectionStat.isFile()) {
+    throw new Error(`Refusing memory projection rewrite through unsafe database path: ${projectionPath}.`);
+  }
+  const [memoryRoot, projectionReal] = await Promise.all([
+    realpath(memoryDir),
+    realpath(projectionPath),
+  ]);
+  assertPathInsideRoot(memoryRoot, projectionReal, projectionPath);
+  return true;
+}
+
+async function rewriteProjectedEntityReferenceRows(
+  memoryDir: string,
+  entries: ReadonlyArray<readonly [string, string]>,
+  memoryId?: string,
+): Promise<void> {
+  if (memoryId !== undefined && memoryId.length === 0) {
+    throw new Error("Projection memoryId must not be empty.");
+  }
+  const scopedMemory = memoryId !== undefined;
+  const validEntries = entries.filter(
+    ([previousEntityRef, nextEntityRef]) =>
+      previousEntityRef.length > 0 && nextEntityRef.length > 0 && previousEntityRef !== nextEntityRef,
+  );
+  if (validEntries.length === 0) return;
+
+  const projectionPath = getMemoryProjectionPath(memoryDir);
+  if (!(await validateProjectionPath(memoryDir, projectionPath))) return;
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt < PROJECTION_WRITE_RETRY_COUNT; attempt += 1) {
+    if (!(await validateProjectionPath(memoryDir, projectionPath))) return;
+    let db: BetterSqlite3Database | null = null;
+    try {
+      db = openBetterSqlite3(projectionPath, { fileMustExist: true });
+      db.pragma(`busy_timeout = ${PROJECTION_WRITE_BUSY_TIMEOUT_MS}`);
+      initializeMemoryProjectionDb(db);
+      const updateCurrent = db.prepare(
+        scopedMemory
+          ? "UPDATE memory_current SET entity_ref = ? WHERE memory_id = ? AND entity_ref = ?"
+          : "UPDATE memory_current SET entity_ref = ? WHERE entity_ref = ?",
+      );
+      const updateMentions = db.prepare(
+        scopedMemory
+          ? `
+            UPDATE memory_entity_mentions
+            SET entity_ref = ?
+            WHERE memory_id = ? AND entity_ref = ? AND mention_source = 'frontmatter.entityRef'
+          `
+          : `
+            UPDATE memory_entity_mentions
+            SET entity_ref = ?
+            WHERE entity_ref = ? AND mention_source = 'frontmatter.entityRef'
+          `,
+      );
+      const rewrite = db.transaction(() => {
+        for (const [previousEntityRef, nextEntityRef] of validEntries) {
+          const params = scopedMemory
+            ? [nextEntityRef, memoryId, previousEntityRef]
+            : [nextEntityRef, previousEntityRef];
+          updateCurrent.run(...params);
+          updateMentions.run(...params);
+        }
+      });
+      rewrite();
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!isSqliteBusyError(error) || attempt === PROJECTION_WRITE_RETRY_COUNT - 1) {
+        throw error;
+      }
+      const { promise, resolve } = Promise.withResolvers<void>();
+      setTimeout(resolve, PROJECTION_WRITE_RETRY_DELAY_MS);
+      await promise;
+    } finally {
+      db?.close();
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error("Projection rewrite failed.");
+}
+
+export async function rewriteProjectedMemoryEntityReference(
+  memoryDir: string,
+  memoryId: string,
+  previousEntityRef: string,
+  nextEntityRef: string,
+): Promise<void> {
+  await rewriteProjectedEntityReferenceRows(memoryDir, [[previousEntityRef, nextEntityRef]], memoryId);
+}
+
+export async function rewriteProjectedEntityReferences(
+  memoryDir: string,
+  replacements: Readonly<Record<string, string>>,
+): Promise<void> {
+  await rewriteProjectedEntityReferenceRows(memoryDir, Object.entries(replacements));
+}

package/src/namespaces/storage.ts

@@ -284,6 +284,7 @@ export class NamespaceStorageRouter {
       root = await this.defaultNamespaceRoot();
       const cached = this.cache.get(ns);
       if (cached && cached.dir === root) {
+        await this.applySecureStoreConfig(cached);
         this.notifyResolved(ns, root);
         return cached;
       }
@@ -291,6 +292,7 @@ export class NamespaceStorageRouter {
       const cached = this.cache.get(ns);
       root = await this.namespaceRoot(ns);
       if (cached && cached.dir === root) {
+        await this.applySecureStoreConfig(cached);
         this.notifyResolved(ns, root);
         return cached;
       }
@@ -335,7 +337,7 @@ export class NamespaceStorageRouter {
     // recovery paths (e.g. the CLI lifecycle-ledger rebuild) refuse an encrypted
     // ledger they could actually rewrite, and namespace writes could silently
     // fall back to plaintext. Mirror the orchestrator's setup exactly.
-    this.applySecureStoreConfig(sm);
+    await this.applySecureStoreConfig(sm);
     this.cache.set(ns, sm);
     // #2019: let the orchestrator wire write-triggered prioritized embedding on
     // every router-created namespace storage, not just the primary default store.
@@ -478,12 +480,12 @@ export class NamespaceStorageRouter {
    * root keyring id — exactly the id the orchestrator and `secure-store unlock`
    * register under. No-op when secure-store is disabled.
    */
-  private applySecureStoreConfig(sm: StorageManager): void {
+  private async applySecureStoreConfig(sm: StorageManager): Promise<void> {
     if (!resolveRecallAuxiliaryCapabilities(this.config).secureStore) return;
     sm.setSecureStoreRequired(true);
     const existingKey = keyring.getKey(secureStoreDir(this.config.memoryDir));
     if (existingKey) {
-      sm.setSecureStoreKey(existingKey, this.config.secureStoreEncryptOnWrite);
+      await sm.setSecureStoreKeyAndWait(existingKey, this.config.secureStoreEncryptOnWrite);
     }
   }
 

package/src/operator-doctor-corpus.ts

@@ -23,7 +23,9 @@ import {
   computeCorpusWatermarks,
   resolveCorpusNamespaceRoots,
 } from "./corpus-watermark.js";
+import { summarizeReplicaDivergence } from "./operator-doctor-replica.js";
 import type { OperatorDoctorCheck } from "./operator-toolkit.js";
+import type { ResolveSecretRefFn } from "./resolve-auth-token.js";
 import type { PluginConfig } from "./types.js";
 
 const DIGEST_PREFIX_LENGTH = 12;
@@ -93,3 +95,42 @@ export async function summarizeCorpusWatermark(
     details: { corpus: watermarks },
   };
 }
+
+/**
+ * Extract the watermark array this check stores under `details.corpus` (issue
+ * #2149). The replica-divergence doctor check reuses the local watermark set
+ * computed here rather than rescanning the corpus, and consumes it through this
+ * helper so the `details.corpus` shape stays owned by the module that produces it.
+ */
+export function corpusWatermarksFromCheck(check: OperatorDoctorCheck): CorpusWatermark[] {
+  const details = check.details;
+  if (!details || typeof details !== "object" || !("corpus" in details) || !Array.isArray(details.corpus)) {
+    return [];
+  }
+  // This check always stores a CorpusWatermark[] under `corpus` (guarded above).
+  return details.corpus as CorpusWatermark[];
+}
+
+/**
+ * Build the corpus-watermark and replica-divergence doctor checks together.
+ *
+ * They are paired deliberately: the replica comparison consumes the corpus
+ * check's watermarks (one scan, not two) AND its completeness — an incomplete
+ * local census must not let the replica check certify convergence. The pairing
+ * lives HERE, next to the corpus check + `corpusWatermarksFromCheck` it consumes
+ * and the `PluginConfig` it needs, so the sibling replica module stays a light
+ * tsup DTS entry free of the heavy `PluginConfig` type graph (round 6, coderabbit).
+ */
+export async function summarizeCorpusAndReplica(
+  config: PluginConfig,
+  storageFactory: (dir: string) => CorpusStorage,
+  resolveSecretRef?: ResolveSecretRefFn | null,
+): Promise<OperatorDoctorCheck[]> {
+  const watermarkCheck = await summarizeCorpusWatermark(config, storageFactory);
+  const replicaCheck = await summarizeReplicaDivergence(
+    config.replicaPeers,
+    corpusWatermarksFromCheck(watermarkCheck),
+    { resolveSecretRef, localCensusComplete: watermarkCheck.status === "ok" },
+  );
+  return [watermarkCheck, replicaCheck];
+}