@remnic/core 9.39.0 → 9.41.0

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()];

package/src/operator-toolkit.ts

@@ -4,6 +4,7 @@ import { access, mkdir, readFile, readdir, stat, unlink, writeFile } from "node:
 import { lintWorkspaceFiles } from "./hygiene.js";
 import { parseConfig } from "./config.js";
 import { summarizeExtractionLiveness, type ExtractionBufferSource } from "./extraction-liveness.js";
+import { readAggregateExtractionWatermark } from "./orchestration/extraction-watermark.js";
 import type { OperatorDoctorCheck } from "./operator-doctor-types.js";
 import { readEnvVar, resolveHomeDir } from "./runtime/env.js";
 import { resolvePluginEntry } from "./plugin-entry-resolver.js";
@@ -53,6 +54,7 @@ import type {
   DreamsPhasesConfig,
   FileHygieneConfig,
   MemoryFile,
+  MetaState,
   PluginConfig,
 } from "./types.js";
 import { reportBufferSurpriseDistribution } from "./buffer-surprise-report.js";
@@ -155,12 +157,12 @@ interface ConversationIndexLike {
     }>;
   };
 }
-
 export interface OperatorToolkitOrchestrator extends ConversationIndexLike {
   config: PluginConfig;
   storage: StorageManager;
   qmd: QmdRuntimeLike;
   buffer?: ExtractionBufferSource;
+  getStorage?(namespace: string): Promise<StorageManager>;
 }
 
 export interface OperatorConfigLoadResult {
@@ -1496,11 +1498,10 @@ export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise
   checks.push(await summarizeGraphEdgeDecayStatus(config));
 
   // Tier distribution (issue #686 retention-completion).
-  // Shows hot/cold counts, per-status breakdown, and forgotten-memory count.
-  // Informational only — never errors, never blocks doctor from returning ok.
   checks.push(await summarizeTierDistribution(options.orchestrator.storage));
-  checks.push(await summarizeDreamsPhases(config, storage));
-  checks.push(await summarizeExtractionLiveness(config, storage, options.orchestrator.buffer));
+  checks.push(await summarizeDreamsPhases(config, storage, meta));
+  const extractionWatermark = await readAggregateExtractionWatermark({ config, rootStorage: storage, rootMeta: meta, storageForNamespace: (ns, rootDir) => options.orchestrator.getStorage?.(ns) ?? new StorageManager(rootDir) });
+  checks.push(await summarizeExtractionLiveness(config, extractionWatermark, options.orchestrator.buffer));
   checks.push(...(await summarizeCorpusAndReplica(config, (d) => new StorageManager(d), options.resolveSecretRef)));
   // Security mitigation status (issue #565).
   // Reports whether the cross-namespace budget and anomaly detection
@@ -1898,11 +1899,10 @@ export async function summarizeTierDistribution(
 export async function summarizeDreamsPhases(
   config: Pick<PluginConfig, "memoryDir" | "dreamsPhases">,
   storage: StorageManager = new StorageManager(config.memoryDir),
+  loadedMeta?: MetaState,
 ): Promise<OperatorDoctorCheck> {
   const phases: DreamsPhasesConfig = config.dreamsPhases;
-
-  // Load meta.json for best-available last-run timestamps.
-  const meta = await storage.loadMeta();
+  const meta = loadedMeta ?? (await storage.loadMeta());
 
   let deepSleepLastRun: string | null = null;
   let deepSleepLastRunWarning: string | null = null;

package/src/orchestration/extraction-watermark.ts

@@ -0,0 +1,188 @@
+import path from "node:path";
+
+import { capabilityAllowsNamespace, type TokenCapabilities } from "../access-token-capabilities.js";
+import { resolveNamespaceCapabilities } from "../capabilities.js";
+import { resolveCorpusNamespaceRoots, type CorpusNamespaceRoot } from "../corpus-watermark.js";
+import { normalizeNamespaceIdentity } from "../namespaces/identity.js";
+import type { ExtractionRootStats, ExtractionWatermarkRead } from "../extraction-liveness.js";
+import type { MetaState, PluginConfig } from "../types.js";
+
+export interface ExtractionWatermarkMeta extends Pick<MetaState, "lastExtractionAt"> {
+  extractionCount?: number;
+  lastConsolidationAt?: string | null;
+}
+
+export interface ExtractionWatermarkStorage {
+  readonly dir: string;
+  loadMeta(): Promise<ExtractionWatermarkMeta>;
+}
+
+export interface ExtractionNamespaceRootCache {
+  getResolvedRootsStatus(compute: () => Promise<CorpusNamespaceRoot[]>): {
+    roots: CorpusNamespaceRoot[] | undefined;
+    refreshError: unknown;
+  };
+}
+
+export interface AggregateExtractionWatermarkOptions {
+  config: PluginConfig;
+  rootStorage: ExtractionWatermarkStorage;
+  rootMeta?: ExtractionWatermarkMeta;
+  storageForNamespace(
+    namespace: string,
+    rootDir: string
+  ): ExtractionWatermarkStorage | Promise<ExtractionWatermarkStorage>;
+  rootsCache?: ExtractionNamespaceRootCache;
+  caps?: TokenCapabilities;
+}
+
+function readFailure(reason: string, rootStats?: ExtractionRootStats): ExtractionWatermarkRead {
+  return {
+    lastExtractionAt: null,
+    readFailed: true,
+    readError: reason,
+    ...(rootStats ? { rootStats } : {}),
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function watermarkFromMeta(meta: ExtractionWatermarkMeta, name: string): ExtractionWatermarkRead {
+  if (meta.lastExtractionAt !== null && meta.lastExtractionAt !== undefined) {
+    const parsed = Date.parse(meta.lastExtractionAt);
+    if (!Number.isFinite(parsed)) {
+      return readFailure(`${name} watermark timestamp invalid`);
+    }
+  }
+  const hasRootStats = meta.extractionCount !== undefined || meta.lastConsolidationAt !== undefined;
+  return {
+    lastExtractionAt: meta.lastExtractionAt ?? null,
+    readFailed: false,
+    ...(hasRootStats
+      ? {
+          rootStats: {
+            extractionCount: meta.extractionCount,
+            lastConsolidationAt: meta.lastConsolidationAt,
+          },
+        }
+      : {}),
+  };
+}
+
+async function readWatermark(storage: ExtractionWatermarkStorage, name: string): Promise<ExtractionWatermarkRead> {
+  try {
+    return watermarkFromMeta(await storage.loadMeta(), name);
+  } catch (error) {
+    return readFailure(`${name} watermark unreadable: ${errorMessage(error)}`);
+  }
+}
+
+async function resolveRoots(
+  options: AggregateExtractionWatermarkOptions
+): Promise<CorpusNamespaceRoot[] | ExtractionWatermarkRead> {
+  const compute = () =>
+    resolveCorpusNamespaceRoots({
+      config: options.config,
+      propagateDiscoveryErrors: true,
+    });
+  if (options.rootsCache) {
+    const { roots, refreshError } = options.rootsCache.getResolvedRootsStatus(compute);
+    if (refreshError !== undefined) {
+      return readFailure(`namespace watermark enumeration failed: ${errorMessage(refreshError)}`);
+    }
+    return roots ?? { lastExtractionAt: null, readFailed: false, pending: true };
+  }
+  try {
+    return await compute();
+  } catch (error) {
+    return readFailure(`namespace watermark enumeration failed: ${errorMessage(error)}`);
+  }
+}
+
+function isReadFailure(value: CorpusNamespaceRoot[] | ExtractionWatermarkRead): value is ExtractionWatermarkRead {
+  return !Array.isArray(value);
+}
+
+function newerWatermark(current: string | null, candidate: string | null): string | null {
+  if (candidate === null) return current;
+  const candidateMs = Date.parse(candidate);
+  if (!Number.isFinite(candidateMs)) return current;
+  if (current === null) return candidate;
+  const currentMs = Date.parse(current);
+  return !Number.isFinite(currentMs) || candidateMs > currentMs ? candidate : current;
+}
+
+export async function readAggregateExtractionWatermark(
+  options: AggregateExtractionWatermarkOptions
+): Promise<ExtractionWatermarkRead> {
+  if (!resolveNamespaceCapabilities(options.config).namespaces) {
+    return options.rootMeta
+      ? watermarkFromMeta(options.rootMeta, "root store")
+      : readWatermark(options.rootStorage, "root store");
+  }
+
+  const resolved = await resolveRoots(options);
+  if (isReadFailure(resolved)) return resolved;
+
+  const rootDir = path.resolve(options.rootStorage.dir);
+  const seenDirs = new Set<string>([rootDir]);
+  const targets: CorpusNamespaceRoot[] = [];
+  for (const root of resolved) {
+    if (
+      options.caps &&
+      !root.namespaces.some((ns) =>
+        capabilityAllowsNamespace(options.caps, normalizeNamespaceIdentity(ns)),
+      )
+    ) {
+      continue;
+    }
+    const resolvedDir = path.resolve(root.rootDir);
+    if (seenDirs.has(resolvedDir)) continue;
+    seenDirs.add(resolvedDir);
+    targets.push(root);
+  }
+
+  const defaultNamespace = normalizeNamespaceIdentity(options.config.defaultNamespace);
+  const hasMigratedDefault = resolved.some(
+    (root) =>
+      path.resolve(root.rootDir) !== rootDir &&
+      root.namespaces.some((namespace) => normalizeNamespaceIdentity(namespace) === defaultNamespace),
+  );
+  const canAccessRoot =
+    !hasMigratedDefault &&
+    (!options.caps || capabilityAllowsNamespace(options.caps, defaultNamespace));
+  let rootRead: ExtractionWatermarkRead = { lastExtractionAt: null, readFailed: false };
+  if (canAccessRoot) {
+    rootRead = await readWatermark(options.rootStorage, "root store");
+    if (rootRead.readFailed) return rootRead;
+  }
+  let lastExtractionAt = rootRead.lastExtractionAt;
+
+  const reads = await Promise.all(
+    targets.map(async (target) => {
+      try {
+        const storage = await options.storageForNamespace(target.namespace, target.rootDir);
+        return await readWatermark(storage, "namespace");
+      } catch (error) {
+        return readFailure(`namespace watermark storage unavailable: ${errorMessage(error)}`);
+      }
+    })
+  );
+
+  for (const read of reads) {
+    if (read.readFailed) {
+      return readFailure(
+        read.readError ?? "namespace watermark unreadable",
+        rootRead.rootStats
+      );
+    }
+    lastExtractionAt = newerWatermark(lastExtractionAt, read.lastExtractionAt);
+  }
+  return {
+    lastExtractionAt,
+    readFailed: false,
+    ...(rootRead.rootStats ? { rootStats: rootRead.rootStats } : {}),
+  };
+}

package/src/types.ts

@@ -1249,13 +1249,7 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   /** OpenClaw bridge mode (#2120): `"embedded"` (default) or `"delegate"`. */
   bridgeMode: string;
   codexCompat: CodexCompatConfig;
-  /**
-   * When true (default), the extraction prompt instructs the LLM to classify
-   * each fact as `"project"` or `"global"` scope. Global-scoped facts are
-   * promoted to the shared namespace so they are visible across all projects.
-   * When false, all facts go to whatever namespace the session is in (pre-
-   * scope-classification behavior). Rule 30: configuration gate.
-   */
+  /** When true (default), LLM classifies facts as `"project"` or `"global"` scope for promotion across projects. */
   extractionScopeClassificationEnabled: boolean;
   // Extraction judge (issue #376)
   /** Enable the LLM-as-judge fact-worthiness gate on extracted facts. Default false (opt-in). */