@remnic/core 9.40.0 → 9.41.0

package/src/extraction-liveness.ts

@@ -21,7 +21,7 @@
 import { coerceBool, coerceNumber } from "./connectors/coerce.js";
 import { log } from "./logger.js";
 import type { OperatorDoctorCheck } from "./operator-doctor-types.js";
-import type { MetaState, PluginConfig } from "./types.js";
+import type { PluginConfig } from "./types.js";
 
 /** Default staleness window: 24h. A watermark older than this with a non-empty buffer is degraded. */
 const DEFAULT_STALE_WINDOW_MS = 86_400_000;
@@ -60,23 +60,57 @@ export interface ExtractionBufferSource {
   getBufferSnapshot(): Promise<ExtractionBufferSnapshot>;
 }
 
+export interface ExtractionRootStats {
+  extractionCount?: number;
+  lastConsolidationAt?: string | null;
+}
+
+export interface ExtractionWatermarkRead {
+  lastExtractionAt: string | null;
+  readFailed: boolean;
+  readError?: string;
+  pending?: boolean;
+  rootStats?: ExtractionRootStats;
+}
+
+export type ExtractionWatermarkOrStorage =
+  | ExtractionWatermarkRead
+  | { readMetadata(): Promise<{ lastExtractionAt?: string | null } | null> }
+  | { loadMeta(): Promise<{ lastExtractionAt?: string | null }> };
+
+export async function coerceExtractionWatermark(
+  watermark: ExtractionWatermarkOrStorage,
+): Promise<ExtractionWatermarkRead> {
+  if (watermark && "readFailed" in watermark && typeof watermark.readFailed === "boolean") {
+    return watermark as ExtractionWatermarkRead;
+  }
+  try {
+    let lastExtractionAt: string | null = null;
+    if ("loadMeta" in watermark && typeof watermark.loadMeta === "function") {
+      const meta = await watermark.loadMeta();
+      lastExtractionAt = meta?.lastExtractionAt ?? null;
+    } else if ("readMetadata" in watermark && typeof watermark.readMetadata === "function") {
+      const meta = await watermark.readMetadata();
+      lastExtractionAt = meta?.lastExtractionAt ?? null;
+    }
+    return {
+      lastExtractionAt,
+      readFailed: true,
+      readError: "aggregate watermark unavailable from legacy root-store-only storage argument",
+    };
+  } catch (error) {
+    return {
+      lastExtractionAt: null,
+      readFailed: true,
+      readError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 /**
- * The liveness payload surfaced on `/health.extraction` and in the doctor/stats
- * details.
- *
- * DAEMON-SCOPED SIGNAL: a daemon exposes a single extraction verdict; the
- * last-extraction watermark is read from the daemon's default/root store, so
- * `/health` returns the same `extraction` block for every namespace argument.
- *
- * KNOWN LIMITATION (issue #2159): extraction stamps `lastExtractionAt` on the
- * PER-NAMESPACE store (`storageFor(selfNamespace)`), so this watermark reflects
- * only extraction that stamped the root store (default-namespace work). On a
- * single-namespace deployment (the common case) the watermark and buffer share
- * one scope and the verdict is exact. On a multi-namespace deployment the verdict
- * is NOT guaranteed correct for work isolated to a non-default namespace: it can
- * over-report `degraded` (the default namespace idle while another is extracting)
- * or miss a stall confined to a non-default namespace. Aggregating the watermark
- * across namespace stores is tracked in #2159.
+ * The daemon-scoped liveness payload surfaced on `/health.extraction` and in
+ * doctor/stats details. Its watermark is the maximum successful extraction
+ * across every distinct namespace store, matching the daemon-wide buffer scope.
  */
 export interface ExtractionLivenessStatus {
   lastExtractionAt: string | null;
@@ -85,18 +119,8 @@ export interface ExtractionLivenessStatus {
   oldestBufferedTurnAgeMs: number | null;
   degraded: boolean;
   degradedReason: string | null;
-  /**
-   * Scope of the last-extraction watermark: `root-store` today (read from the
-   * daemon's default/root store only), `aggregate` once it is resolved across
-   * every namespace store (#2159). A monitor can alert on
-   * `watermarkScope !== "aggregate"` while namespaces are enabled instead of
-   * trusting a number that may be wrong in either direction.
-   */
-  watermarkScope: "root-store" | "aggregate";
-}
-
-interface ExtractionLivenessStorageLike {
-  loadMeta(): Promise<Pick<MetaState, "lastExtractionAt">>;
+  watermarkPending?: boolean;
+  watermarkScope: "aggregate";
 }
 
 interface ExtractionLivenessOrchestratorLike {
@@ -190,7 +214,7 @@ export function evaluateExtractionLiveness(input: {
   nowMs: number;
   metaReadFailed?: boolean;
   metaReadError?: string;
-  watermarkScope?: "root-store" | "aggregate";
+  watermarkPending?: boolean;
 }): ExtractionLivenessStatus {
   const { config, lastExtractionAt, snapshot, nowMs } = input;
   const lastMs = lastExtractionAt !== null ? Date.parse(lastExtractionAt) : Number.NaN;
@@ -204,8 +228,10 @@ export function evaluateExtractionLiveness(input: {
   // (§22): a storage/pipeline outage must not read as healthy, and must stay
   // distinct from a pipeline that has genuinely never extracted.
   const metaReadFailed = input.metaReadFailed === true;
+  const watermarkPending = input.watermarkPending === true;
   const readFailed = snapshot.readFailed === true;
-  const degraded = config.enabled && (metaReadFailed || readFailed || (hasBacklog && stale));
+  const degraded =
+    config.enabled && (metaReadFailed || readFailed || (!watermarkPending && hasBacklog && stale));
 
   let degradedReason: string | null = null;
   if (degraded) {
@@ -230,7 +256,8 @@ export function evaluateExtractionLiveness(input: {
     oldestBufferedTurnAgeMs: ageMsFrom(snapshot.oldestTurnTimestamp, nowMs),
     degraded,
     degradedReason,
-    watermarkScope: input.watermarkScope ?? "root-store",
+    ...(watermarkPending ? { watermarkPending: true } : {}),
+    watermarkScope: "aggregate",
   };
 }
 
@@ -262,40 +289,27 @@ async function readBufferSnapshot(
 }
 
 /**
- * Gather the liveness status from a meta store (last-extraction watermark) and
- * an optional buffer (backlog). A read failure on EITHER side is captured and
- * surfaced as a DEGRADED status with a distinct reason (§22) rather than being
- * swallowed into a healthy-looking verdict; no failure path throws.
+ * Gather the liveness status from an aggregate watermark read and an optional
+ * buffer. A read failure on either side is surfaced as a degraded status with a
+ * distinct reason rather than swallowed into a healthy-looking verdict.
  */
 export async function gatherExtractionLivenessStatus(input: {
   config: ExtractionLivenessConfig;
-  storage: ExtractionLivenessStorageLike;
+  watermark: ExtractionWatermarkOrStorage;
   buffer: ExtractionBufferSource | undefined;
   nowMs: number;
 }): Promise<ExtractionLivenessStatus> {
-  const { config, storage, buffer, nowMs } = input;
-  let lastExtractionAt: string | null = null;
-  let metaReadFailed = false;
-  let metaReadError: string | undefined;
-  try {
-    lastExtractionAt = (await storage.loadMeta()).lastExtractionAt ?? null;
-  } catch (err) {
-    // A swallowed loadMeta() failure that reads as "never extracted" is the
-    // exact §22 conflation this feature exists to kill — surface it explicitly.
-    metaReadFailed = true;
-    metaReadError = err instanceof Error ? err.message : String(err);
-  }
+  const { config, buffer, nowMs } = input;
+  const watermarkRead = await coerceExtractionWatermark(input.watermark);
   const snapshot = await readBufferSnapshot(buffer);
   return evaluateExtractionLiveness({
     config,
-    lastExtractionAt,
+    lastExtractionAt: watermarkRead.lastExtractionAt,
     snapshot,
     nowMs,
-    metaReadFailed,
-    metaReadError,
-    // Today the watermark comes from the root store only; #2159 flips this to
-    // "aggregate" when the resolver reads across every namespace store.
-    watermarkScope: "root-store",
+    metaReadFailed: watermarkRead.readFailed,
+    metaReadError: watermarkRead.readError,
+    watermarkPending: watermarkRead.pending,
   });
 }
 
@@ -349,25 +363,19 @@ export function resolveExtractionLivenessConfig(
 }
 
 /**
- * Compute the liveness status for the authenticated `/health` payload and emit
- * the throttled aggregated WARN.
- *
- * The watermark is read from the daemon's default/root store (`orchestrator.storage`),
- * which is why `/health` returns the same `extraction` block for any namespace
- * argument. KNOWN LIMITATION (issue #2159): extraction writes `lastExtractionAt`
- * per-namespace, so this watermark reflects only default-namespace extraction and
- * the verdict is exact only for a single-namespace daemon (see
- * `ExtractionLivenessStatus`).
+ * Compute the daemon-wide liveness status for the authenticated `/health`
+ * payload and emit the throttled aggregate warning.
  */
 export async function computeExtractionLivenessStatus(
-  orchestrator: ExtractionLivenessOrchestratorLike & { storage: ExtractionLivenessStorageLike },
+  orchestrator: ExtractionLivenessOrchestratorLike,
+  watermark: ExtractionWatermarkOrStorage,
   throttle?: ExtractionLivenessWarnThrottle,
   nowMs: number = Date.now(),
 ): Promise<ExtractionLivenessStatus> {
   const config = resolveExtractionLivenessConfig(orchestrator.config.extractionLiveness);
   const status = await gatherExtractionLivenessStatus({
     config,
-    storage: orchestrator.storage,
+    watermark,
     buffer: orchestrator.buffer,
     nowMs,
   });
@@ -381,22 +389,18 @@ export async function computeExtractionLivenessStatus(
  */
 export async function summarizeExtractionLiveness(
   config: Pick<PluginConfig, "extractionLiveness">,
-  storage: ExtractionLivenessStorageLike,
+  watermark: ExtractionWatermarkOrStorage,
   buffer?: ExtractionBufferSource,
   nowMs: number = Date.now(),
 ): Promise<OperatorDoctorCheck> {
   const livenessConfig = resolveExtractionLivenessConfig(config.extractionLiveness);
   const status = await gatherExtractionLivenessStatus({
     config: livenessConfig,
-    storage,
+    watermark,
     buffer,
     nowMs,
   });
-  const scopeNote =
-    ` Watermark scope: ${status.watermarkScope}` +
-    (status.watermarkScope === "root-store"
-      ? " (default-namespace only; multi-namespace aggregation tracked in #2159)."
-      : ".");
+  const scopeNote = ` Watermark scope: ${status.watermarkScope}.`;
   const summary =
     (status.degraded
       ? `Extraction pipeline degraded: ${status.degradedReason}.`
@@ -416,44 +420,38 @@ export async function summarizeExtractionLiveness(
   };
 }
 
-/** Meta fields the `remnic stats` view renders directly, beyond the liveness watermark. */
-type ExtractionStatsMeta = Pick<MetaState, "extractionCount" | "lastExtractionAt" | "lastConsolidationAt">;
-
 /**
- * Lines for `remnic stats`: extraction watermark, buffer backlog, and the
- * liveness verdict so dashboards can alert on a stalled pipeline. The meta
- * watermark is loaded HERE (not by the caller) so a meta-read failure surfaces
- * as an explicit DEGRADED verdict plus "unavailable" counts (§22) instead of
- * crashing the whole `stats` command.
+ * Lines for `remnic stats`: the aggregate extraction watermark, root metadata
+ * counters, buffer backlog, and liveness verdict. Root counter failures render
+ * those counters unavailable; the injected aggregate read alone determines
+ * watermark liveness so stats cannot diverge from health and doctor.
  */
 export async function renderExtractionLivenessStats(
-  orchestrator: ExtractionLivenessOrchestratorLike & { storage: { loadMeta(): Promise<ExtractionStatsMeta> } },
+  orchestrator: ExtractionLivenessOrchestratorLike,
+  watermark: ExtractionWatermarkRead,
   nowMs: number = Date.now(),
 ): Promise<string[]> {
-  let meta: ExtractionStatsMeta | null = null;
-  let metaReadFailed = false;
-  let metaReadError: string | undefined;
-  try {
-    meta = await orchestrator.storage.loadMeta();
-  } catch (err) {
-    metaReadFailed = true;
-    metaReadError = err instanceof Error ? err.message : String(err);
-  }
   const status = evaluateExtractionLiveness({
     config: resolveExtractionLivenessConfig(orchestrator.config.extractionLiveness),
-    lastExtractionAt: meta?.lastExtractionAt ?? null,
+    lastExtractionAt: watermark.lastExtractionAt,
     snapshot: await readBufferSnapshot(orchestrator.buffer),
     nowMs,
-    metaReadFailed,
-    metaReadError,
+    metaReadFailed: watermark.readFailed,
+    metaReadError: watermark.readError,
+    watermarkPending: watermark.pending,
   });
   const oldestAge =
     status.oldestBufferedTurnAgeMs !== null ? formatAgeMs(status.oldestBufferedTurnAgeMs) : "n/a";
-  const unavailable = metaReadFailed ? "unavailable" : "never";
+  const rootStats = watermark.rootStats;
+  const watermarkDisplay = watermark.readFailed
+    ? "unavailable"
+    : watermark.pending
+      ? "pending"
+      : status.lastExtractionAt ?? "never";
   return [
-    `Extractions: ${meta?.extractionCount ?? unavailable}`,
-    `Last extraction: ${meta?.lastExtractionAt ?? unavailable}`,
-    `Last consolidation: ${meta?.lastConsolidationAt ?? unavailable}`,
+    `Extractions: ${rootStats?.extractionCount ?? "unavailable"}`,
+    `Last extraction: ${watermarkDisplay}`,
+    `Last consolidation: ${rootStats ? rootStats.lastConsolidationAt ?? "never" : "unavailable"}`,
     `Buffered sessions: ${status.bufferedSessionCount} (${status.pendingTurnCount} turns pending)`,
     `Oldest buffered turn age: ${oldestAge}`,
     `Extraction watermark scope: ${status.watermarkScope}`,

package/src/extraction-watermark.test.ts

@@ -0,0 +1,290 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { TOKEN_CAPABILITIES_VERSION } from "./access-token-capabilities.js";
+import { parseConfig } from "./config.js";
+import { CorpusWatermarkCache } from "./corpus-watermark.js";
+import { readAggregateExtractionWatermark } from "./orchestration/extraction-watermark.js";
+import type { PluginConfig } from "./types.js";
+
+interface FakeWatermarkStorage {
+  readonly dir: string;
+  loadMeta(): Promise<{ lastExtractionAt: string | null }>;
+}
+
+function storage(dir: string, read: () => Promise<string | null>): FakeWatermarkStorage {
+  return {
+    dir,
+    loadMeta: async () => ({ lastExtractionAt: await read() }),
+  };
+}
+
+async function namespacedFixture(): Promise<{
+  memoryDir: string;
+  config: PluginConfig;
+  namespaceDirs: Record<string, string>;
+}> {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-extraction-watermark-"));
+  const namespaceDirs = {
+    "team-a": path.join(memoryDir, "namespaces", "team-a"),
+    "team-b": path.join(memoryDir, "namespaces", "team-b"),
+  };
+  await Promise.all(Object.values(namespaceDirs).map((dir) => mkdir(dir, { recursive: true })));
+  return {
+    memoryDir,
+    config: parseConfig({ memoryDir, namespacesEnabled: true, defaultNamespace: "default" }),
+    namespaceDirs,
+  };
+}
+
+test("aggregate watermark selects the most recent extraction across distinct namespace stores", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const timestamps = {
+      default: "2026-07-20T12:00:00.000Z",
+      "team-a": "2026-07-21T12:00:00.000Z",
+      "team-b": "2026-07-22T12:00:00.000Z",
+    };
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => timestamps.default),
+      storageForNamespace: async (namespace) =>
+        storage(fixture.namespaceDirs[namespace], async () => timestamps[namespace as keyof typeof timestamps]),
+    });
+
+    assert.deepEqual(result, {
+      lastExtractionAt: timestamps["team-b"],
+      readFailed: false,
+    });
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a namespace-isolated extraction advances the daemon aggregate watermark", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const rootTimestamp = "2026-07-20T12:00:00.000Z";
+    let teamTimestamp = "2026-07-19T12:00:00.000Z";
+    const options = {
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => rootTimestamp),
+      storageForNamespace: async (namespace: string) =>
+        storage(fixture.namespaceDirs[namespace], async () => (namespace === "team-a" ? teamTimestamp : null)),
+    };
+
+    assert.equal((await readAggregateExtractionWatermark(options)).lastExtractionAt, rootTimestamp);
+    teamTimestamp = "2026-07-23T12:00:00.000Z";
+    assert.equal((await readAggregateExtractionWatermark(options)).lastExtractionAt, teamTimestamp);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a partial namespace read returns readFailed instead of a survivor's fresh watermark", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => "2026-07-23T12:00:00.000Z"),
+      storageForNamespace: async (namespace) =>
+        storage(fixture.namespaceDirs[namespace], async () => {
+          if (namespace === "team-b") throw new Error("meta store unavailable");
+          return "2026-07-22T12:00:00.000Z";
+        }),
+    });
+
+    assert.equal(result.lastExtractionAt, null, "a surviving timestamp must not be reported as complete");
+    assert.equal(result.readFailed, true);
+    assert.match(result.readError ?? "", /namespace watermark unreadable/);
+    assert.match(result.readError ?? "", /meta store unavailable/);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+test("scoped capabilities filter candidate namespaces during aggregate read", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    let scannedTeamB = false;
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => "2026-07-20T12:00:00.000Z"),
+      storageForNamespace: async (namespace) => {
+        if (namespace === "team-b") scannedTeamB = true;
+        return storage(fixture.namespaceDirs[namespace], async () => "2026-07-25T12:00:00.000Z");
+      },
+      caps: { version: TOKEN_CAPABILITIES_VERSION, namespaces: ["team-a"] },
+    });
+
+    assert.equal(scannedTeamB, false, "team-b should be skipped when token is restricted to team-a");
+    assert.equal(result.readFailed, false);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("default root capability check uses normalized aliases for migrated storage", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const migratedDefaultDir = path.join(fixture.memoryDir, "namespaces", "default");
+    await mkdir(migratedDefaultDir, { recursive: true });
+    const result = await readAggregateExtractionWatermark({
+      config: { ...fixture.config, defaultNamespace: " default " },
+      rootStorage: storage(fixture.memoryDir, async () => {
+        throw new Error("inactive legacy root is unreadable");
+      }),
+      storageForNamespace: async (_namespace, rootDir) =>
+        storage(rootDir, async () =>
+          path.resolve(rootDir) === path.resolve(migratedDefaultDir)
+            ? "2026-07-26T12:00:00.000Z"
+            : "2026-07-24T12:00:00.000Z",
+        ),
+      caps: { version: TOKEN_CAPABILITIES_VERSION, namespaces: ["default"] },
+    });
+
+    assert.equal(result.lastExtractionAt, "2026-07-26T12:00:00.000Z");
+    assert.equal(result.readFailed, false);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+test("unparsable non-null timestamp in namespace store fails the aggregate read", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => "2026-07-20T12:00:00.000Z"),
+      storageForNamespace: async (namespace) =>
+        storage(fixture.namespaceDirs[namespace], async () => (namespace === "team-a" ? "invalid-date-string" : "2026-07-25T12:00:00.000Z")),
+    });
+
+    assert.equal(result.lastExtractionAt, null);
+    assert.equal(result.readFailed, true);
+    assert.match(result.readError ?? "", /watermark timestamp invalid/);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("namespace discovery I/O failure is an explicit incomplete read", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-extraction-watermark-enumeration-"));
+  try {
+    await writeFile(path.join(memoryDir, "namespaces"), "not a directory", "utf8");
+    const config = parseConfig({ memoryDir, namespacesEnabled: true });
+    const result = await readAggregateExtractionWatermark({
+      config,
+      rootStorage: storage(memoryDir, async () => "2026-07-23T12:00:00.000Z"),
+      storageForNamespace: async (_namespace, rootDir) => storage(rootDir, async () => null),
+    });
+
+    assert.equal(result.lastExtractionAt, null);
+    assert.equal(result.readFailed, true);
+    assert.match(result.readError ?? "", /namespace watermark enumeration failed/);
+    assert.match(result.readError ?? "", /ENOTDIR/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a failed stale-cache refresh makes later reads incomplete", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    let now = 1;
+    const cache = new CorpusWatermarkCache({ ttlMs: 1, clock: () => now });
+    const options = {
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => "2026-07-20T12:00:00.000Z"),
+      storageForNamespace: async (namespace: string) =>
+        storage(fixture.namespaceDirs[namespace], async () => "2026-07-21T12:00:00.000Z"),
+      rootsCache: cache,
+    };
+
+    const coldRead = await readAggregateExtractionWatermark(options);
+    assert.equal(coldRead.readFailed, false);
+    assert.equal(coldRead.pending, true);
+    await cache.whenIdle();
+    assert.equal((await readAggregateExtractionWatermark(options)).readFailed, false);
+
+    await rm(path.join(fixture.memoryDir, "namespaces"), { recursive: true, force: true });
+    await writeFile(path.join(fixture.memoryDir, "namespaces"), "not a directory", "utf8");
+    now += 2;
+    assert.equal(
+      (await readAggregateExtractionWatermark(options)).readFailed,
+      false,
+      "the stale value may be served while refresh is still in flight",
+    );
+    await cache.whenIdle();
+    const failedRefresh = await readAggregateExtractionWatermark(options);
+    assert.equal(failedRefresh.lastExtractionAt, null);
+    assert.equal(failedRefresh.readFailed, true);
+    assert.match(failedRefresh.readError ?? "", /namespace watermark enumeration failed/);
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("a cold namespace-root cache is pending, not a failed read", async () => {
+  const fixture = await namespacedFixture();
+  try {
+    let rootReads = 0;
+    const result = await readAggregateExtractionWatermark({
+      config: fixture.config,
+      rootStorage: storage(fixture.memoryDir, async () => {
+        rootReads += 1;
+        return "2026-07-23T12:00:00.000Z";
+      }),
+      storageForNamespace: async (namespace) => storage(fixture.namespaceDirs[namespace], async () => null),
+      rootsCache: {
+        getResolvedRootsStatus: () => ({ roots: undefined, refreshError: undefined }),
+      },
+    });
+
+    assert.equal(result.lastExtractionAt, null);
+    assert.equal(result.readFailed, false);
+    assert.equal(result.pending, true);
+    assert.equal(rootReads, 0, "a root survivor is not read or published before enumeration completes");
+  } finally {
+    await rm(fixture.memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("namespaces disabled performs exactly one root metadata read", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-extraction-watermark-single-"));
+  try {
+    const config = parseConfig({ memoryDir, namespacesEnabled: false });
+    let rootReads = 0;
+    let namespaceResolutions = 0;
+    const timestamp = "2026-07-23T12:00:00.000Z";
+    const result = await readAggregateExtractionWatermark({
+      config,
+      rootStorage: {
+        dir: memoryDir,
+        loadMeta: async () => {
+          rootReads += 1;
+          return {
+            lastExtractionAt: timestamp,
+            extractionCount: 9,
+            lastConsolidationAt: null,
+          };
+        },
+      },
+      storageForNamespace: async () => {
+        namespaceResolutions += 1;
+        throw new Error("disabled path must not resolve namespace storage");
+      },
+    });
+
+    assert.deepEqual(result, {
+      lastExtractionAt: timestamp,
+      readFailed: false,
+      rootStats: { extractionCount: 9, lastConsolidationAt: null },
+    });
+    assert.equal(rootReads, 1);
+    assert.equal(namespaceResolutions, 0);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/namespaces/migrate.ts

@@ -65,6 +65,7 @@ async function hasAnyLegacyData(rootDir: string): Promise<boolean> {
 
 async function discoverConfiguredNamespaces(
   config: PluginConfig,
+  propagateDiscoveryErrors: boolean,
 ): Promise<string[]> {
   const discovered = new Set<string>([
     config.defaultNamespace,
@@ -85,7 +86,10 @@ async function discoverConfiguredNamespaces(
         discovered.add(namespace);
       }
     }
-  } catch {
+  } catch (error) {
+    if (propagateDiscoveryErrors && (error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
     // No namespace directory yet.
   }
 
@@ -95,9 +99,13 @@ async function discoverConfiguredNamespaces(
 export async function listNamespaces(options: {
   config: PluginConfig;
   storageRouter?: NamespaceStorageRouter;
+  propagateDiscoveryErrors?: boolean;
 }): Promise<NamespaceInventoryEntry[]> {
   const storageRouter = options.storageRouter ?? new NamespaceStorageRouter(options.config);
-  const namespaces = await discoverConfiguredNamespaces(options.config);
+  const namespaces = await discoverConfiguredNamespaces(
+    options.config,
+    options.propagateDiscoveryErrors ?? false,
+  );
   const items = await Promise.all(
     namespaces.map(async (namespace) => {
       const storage = await storageRouter.storageFor(namespace);

package/src/operator-doctor-corpus.test.ts

@@ -143,11 +143,18 @@ test("runOperatorDoctor: includes the corpus_watermark check", async () => {
   const { root, memoryDir, configPath, orchestrator } = await makeFixture();
   try {
     await writeMemory(memoryDir, "facts/2026-03-08/a.md");
+    let metadataReads = 0;
+    const loadMeta = orchestrator.storage.loadMeta.bind(orchestrator.storage);
+    orchestrator.storage.loadMeta = async () => {
+      metadataReads += 1;
+      return loadMeta();
+    };
     const report = await runOperatorDoctor({ configPath, orchestrator });
     const check = report.checks.find((c) => c.key === "corpus_watermark");
     assert.ok(check, "expected a corpus_watermark check");
     assert.equal(check?.status, "ok");
     assert.equal(corpusOf(check)[0]?.memoryFileCount, 1);
+    assert.equal(metadataReads, 1, "doctor reuses the root metadata read for extraction liveness");
   } finally {
     await rm(root, { recursive: true, force: true });
   }

package/src/operator-doctor-corpus.ts

@@ -42,7 +42,7 @@ export async function summarizeCorpusWatermark(
     // The doctor orchestrator has no live namespace catalog, so config-driven
     // enumeration (deduped by root inside the shared helper) is the whole set.
     const rootByNamespace = new Map<string, string>();
-    for (const root of await resolveCorpusNamespaceRoots({ config })) {
+    for (const root of await resolveCorpusNamespaceRoots({ config, propagateDiscoveryErrors: true })) {
       rootByNamespace.set(root.namespace, root.rootDir);
     }
     resolved = [...rootByNamespace.keys()];