@remnic/core 9.39.0 → 9.41.0

package/dist/{chunk-443XCR34.js → chunk-3SG4FGDV.js}

@@ -8,6 +8,32 @@ import {
 
 // src/extraction-liveness.ts
 var DEFAULT_STALE_WINDOW_MS = 864e5;
+async function coerceExtractionWatermark(watermark) {
+  if (watermark && "readFailed" in watermark && typeof watermark.readFailed === "boolean") {
+    return watermark;
+  }
+  try {
+    let lastExtractionAt = 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)
+    };
+  }
+}
 function parseExtractionLivenessConfig(cfg) {
   const raw = cfg.extractionLiveness;
   if (raw !== void 0 && (raw === null || typeof raw !== "object" || Array.isArray(raw))) {
@@ -52,8 +78,9 @@ function evaluateExtractionLiveness(input) {
   const stale = !hasWatermark || ageMs < 0 || ageMs >= config.staleWindowMs;
   const hasBacklog = snapshot.bufferedSessionCount > 0;
   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 = null;
   if (degraded) {
     if (metaReadFailed) {
@@ -72,7 +99,8 @@ function evaluateExtractionLiveness(input) {
     oldestBufferedTurnAgeMs: ageMsFrom(snapshot.oldestTurnTimestamp, nowMs),
     degraded,
     degradedReason,
-    watermarkScope: input.watermarkScope ?? "root-store"
+    ...watermarkPending ? { watermarkPending: true } : {},
+    watermarkScope: "aggregate"
   };
 }
 var EMPTY_SNAPSHOT = {
@@ -93,27 +121,17 @@ async function readBufferSnapshot(buffer) {
   }
 }
 async function gatherExtractionLivenessStatus(input) {
-  const { config, storage, buffer, nowMs } = input;
-  let lastExtractionAt = null;
-  let metaReadFailed = false;
-  let metaReadError;
-  try {
-    lastExtractionAt = (await storage.loadMeta()).lastExtractionAt ?? null;
-  } catch (err) {
-    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
   });
 }
 var ExtractionLivenessWarnThrottle = class {
@@ -139,26 +157,26 @@ function resolveExtractionLivenessConfig(block) {
     staleWindowMs: staleWindowMs !== void 0 && Number.isInteger(staleWindowMs) && staleWindowMs >= 1 ? staleWindowMs : DEFAULT_STALE_WINDOW_MS
   };
 }
-async function computeExtractionLivenessStatus(orchestrator, throttle, nowMs = Date.now()) {
+async function computeExtractionLivenessStatus(orchestrator, watermark, throttle, nowMs = Date.now()) {
   const config = resolveExtractionLivenessConfig(orchestrator.config.extractionLiveness);
   const status = await gatherExtractionLivenessStatus({
     config,
-    storage: orchestrator.storage,
+    watermark,
     buffer: orchestrator.buffer,
     nowMs
   });
   throttle?.maybeWarn(status, config.staleWindowMs, nowMs);
   return status;
 }
-async function summarizeExtractionLiveness(config, storage, buffer, nowMs = Date.now()) {
+async function summarizeExtractionLiveness(config, watermark, buffer, nowMs = Date.now()) {
   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}.` : `Extraction pipeline healthy: last extraction ${status.lastExtractionAt ?? "never"}, ${status.bufferedSessionCount} buffered session(s), ${status.pendingTurnCount} turn(s) pending${livenessConfig.enabled ? "" : " (liveness check disabled)"}.`) + scopeNote;
   return {
     key: "extraction_liveness",
@@ -168,30 +186,23 @@ async function summarizeExtractionLiveness(config, storage, buffer, nowMs = Date
     details: { ...status, staleWindowMs: livenessConfig.staleWindowMs, enabled: livenessConfig.enabled }
   };
 }
-async function renderExtractionLivenessStats(orchestrator, nowMs = Date.now()) {
-  let meta = null;
-  let metaReadFailed = false;
-  let metaReadError;
-  try {
-    meta = await orchestrator.storage.loadMeta();
-  } catch (err) {
-    metaReadFailed = true;
-    metaReadError = err instanceof Error ? err.message : String(err);
-  }
+async function renderExtractionLivenessStats(orchestrator, watermark, nowMs = Date.now()) {
   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}`,
@@ -200,6 +211,7 @@ async function renderExtractionLivenessStats(orchestrator, nowMs = Date.now()) {
 }
 
 export {
+  coerceExtractionWatermark,
   parseExtractionLivenessConfig,
   formatAgeMs,
   evaluateExtractionLiveness,
@@ -210,4 +222,4 @@ export {
   summarizeExtractionLiveness,
   renderExtractionLivenessStats
 };
-//# sourceMappingURL=chunk-443XCR34.js.map
+//# sourceMappingURL=chunk-3SG4FGDV.js.map

package/dist/chunk-3SG4FGDV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extraction-liveness.ts"],"sourcesContent":["/**\n * Extraction-pipeline liveness (issue #2151).\n *\n * A daemon's implicit extraction can fail continuously for months while\n * `/health` stays green and recall keeps serving: every individual failure is\n * logged (timeouts, fallback-no-parsed-output), but nothing aggregates them\n * into a checkable status. This module surfaces a liveness *watermark* — the\n * last successful extraction plus the current buffer backlog — and decides when\n * that watermark is stale enough to call the pipeline degraded.\n *\n * The §22 error-vs-empty principle applies at the pipeline level: \"no\n * extraction succeeded for 90 days\" (a non-empty buffer with a stale/absent\n * watermark) must be distinguishable from \"nothing to extract\" (an empty\n * buffer). Degradation therefore requires a NON-EMPTY buffer — an idle daemon\n * with nothing buffered is healthy, not degraded.\n *\n * The core decision (`evaluateExtractionLiveness`) is a pure function shared by\n * every surface (authenticated `/health`, `remnic doctor`, `remnic stats`) so\n * the verdict never diverges across code paths.\n */\nimport { coerceBool, coerceNumber } from \"./connectors/coerce.js\";\nimport { log } from \"./logger.js\";\nimport type { OperatorDoctorCheck } from \"./operator-doctor-types.js\";\nimport type { PluginConfig } from \"./types.js\";\n\n/** Default staleness window: 24h. A watermark older than this with a non-empty buffer is degraded. */\nconst DEFAULT_STALE_WINDOW_MS = 86_400_000;\n\nexport interface ExtractionLivenessConfig {\n  /** Master gate. When false, liveness is never reported degraded. Default true. */\n  enabled: boolean;\n  /**\n   * How stale the last-successful-extraction watermark may get (ms) before a\n   * non-empty buffer flags the pipeline degraded. Default 24h.\n   */\n  staleWindowMs: number;\n}\n\n/**\n * A read-only snapshot of buffered, not-yet-extracted work. Structurally\n * satisfied by `SmartBuffer.getBufferSnapshot()` so callers can pass the live\n * buffer without this module depending on the buffer implementation.\n */\nexport interface ExtractionBufferSnapshot {\n  bufferedSessionCount: number;\n  pendingTurnCount: number;\n  oldestTurnTimestamp: string | null;\n  /**\n   * Set by the liveness reader (never by `SmartBuffer`) when the buffer exists\n   * but its snapshot read threw. An unreadable buffer is a pipeline fault, not\n   * an empty queue (§22): it degrades the pipeline with a distinct reason\n   * instead of masquerading as a zero-backlog (healthy) snapshot.\n   */\n  readFailed?: boolean;\n  /** Read-failure detail, surfaced in the degraded reason when `readFailed`. */\n  readError?: string;\n}\n\nexport interface ExtractionBufferSource {\n  getBufferSnapshot(): Promise<ExtractionBufferSnapshot>;\n}\n\nexport interface ExtractionRootStats {\n  extractionCount?: number;\n  lastConsolidationAt?: string | null;\n}\n\nexport interface ExtractionWatermarkRead {\n  lastExtractionAt: string | null;\n  readFailed: boolean;\n  readError?: string;\n  pending?: boolean;\n  rootStats?: ExtractionRootStats;\n}\n\nexport type ExtractionWatermarkOrStorage =\n  | ExtractionWatermarkRead\n  | { readMetadata(): Promise<{ lastExtractionAt?: string | null } | null> }\n  | { loadMeta(): Promise<{ lastExtractionAt?: string | null }> };\n\nexport async function coerceExtractionWatermark(\n  watermark: ExtractionWatermarkOrStorage,\n): Promise<ExtractionWatermarkRead> {\n  if (watermark && \"readFailed\" in watermark && typeof watermark.readFailed === \"boolean\") {\n    return watermark as ExtractionWatermarkRead;\n  }\n  try {\n    let lastExtractionAt: string | null = null;\n    if (\"loadMeta\" in watermark && typeof watermark.loadMeta === \"function\") {\n      const meta = await watermark.loadMeta();\n      lastExtractionAt = meta?.lastExtractionAt ?? null;\n    } else if (\"readMetadata\" in watermark && typeof watermark.readMetadata === \"function\") {\n      const meta = await watermark.readMetadata();\n      lastExtractionAt = meta?.lastExtractionAt ?? null;\n    }\n    return {\n      lastExtractionAt,\n      readFailed: true,\n      readError: \"aggregate watermark unavailable from legacy root-store-only storage argument\",\n    };\n  } catch (error) {\n    return {\n      lastExtractionAt: null,\n      readFailed: true,\n      readError: error instanceof Error ? error.message : String(error),\n    };\n  }\n}\n\n/**\n * The daemon-scoped liveness payload surfaced on `/health.extraction` and in\n * doctor/stats details. Its watermark is the maximum successful extraction\n * across every distinct namespace store, matching the daemon-wide buffer scope.\n */\nexport interface ExtractionLivenessStatus {\n  lastExtractionAt: string | null;\n  bufferedSessionCount: number;\n  pendingTurnCount: number;\n  oldestBufferedTurnAgeMs: number | null;\n  degraded: boolean;\n  degradedReason: string | null;\n  watermarkPending?: boolean;\n  watermarkScope: \"aggregate\";\n}\n\ninterface ExtractionLivenessOrchestratorLike {\n  config: Pick<PluginConfig, \"extractionLiveness\">;\n  buffer?: ExtractionBufferSource;\n}\n\n/**\n * Parse the `extractionLiveness` config block. Follows the nested-block shape\n * validation used elsewhere in `config.ts` and coerces string booleans (§24:\n * CLI/JSON deliver `\"false\"`/`\"0\"` as strings, which must read as falsy).\n */\nexport function parseExtractionLivenessConfig(\n  cfg: Record<string, unknown>,\n): ExtractionLivenessConfig {\n  const raw = cfg.extractionLiveness;\n  if (raw !== undefined && (raw === null || typeof raw !== \"object\" || Array.isArray(raw))) {\n    throw new Error(`extractionLiveness must be a plain object (got ${JSON.stringify(raw)})`);\n  }\n  const block = (raw ?? {}) as Record<string, unknown>;\n  return {\n    // `?? true` keeps the default on when the key is absent while honoring\n    // explicit \"false\"/\"0\"/false opt-outs (coerceBool handles the string forms).\n    enabled: coerceBool(block.enabled) ?? true,\n    staleWindowMs: parseStaleWindowMs(block.staleWindowMs),\n  };\n}\n\n/**\n * Parse `extractionLiveness.staleWindowMs`. Absent (`undefined`) → the 24h\n * default; any PRESENT value (including an explicit `null`) must coerce to a\n * positive INTEGER of milliseconds, else THROW. A fractional or non-positive\n * value (\"0.5\" would floor to 0, making every backlog instantly stale; 1.9 would\n * floor to 1) is rejected, never floored/reinterpreted (§1/§17/§39). Mirrors\n * config.ts's `parseIntegerInClosedRange` (round 9 finding 1): only an absent key\n * falls back; an explicit `null` is invalid input, not \"use the default\".\n * Inlined rather than imported because config.ts already imports this module\n * (importing back would be circular), the same reason `recall-concurrency-config.ts`\n * inlines its numeric validation.\n */\nfunction parseStaleWindowMs(value: unknown): number {\n  // Only an absent key (undefined) falls back to the default; an explicit `null`\n  // is invalid input and proceeds to validation → throw (mirrors\n  // parseIntegerInClosedRange, round 9 finding 1).\n  if (value === undefined) return DEFAULT_STALE_WINDOW_MS;\n  const coerced = coerceNumber(value);\n  if (coerced === undefined || !Number.isFinite(coerced) || !Number.isInteger(coerced) || coerced < 1) {\n    throw new Error(\n      `extractionLiveness.staleWindowMs must be an integer greater than or equal to 1; got ${JSON.stringify(value)}`,\n    );\n  }\n  return coerced;\n}\n\n/** Milliseconds between `timestamp` and `nowMs`, clamped at 0; null when unparsable/absent. */\nfunction ageMsFrom(timestamp: string | null, nowMs: number): number | null {\n  if (typeof timestamp !== \"string\") return null;\n  const parsed = Date.parse(timestamp);\n  if (!Number.isFinite(parsed)) return null;\n  return Math.max(0, nowMs - parsed);\n}\n\n/** Compact human-readable duration (\"3d\", \"5h\", \"12m\", \"45s\") for logs and CLI output. */\nexport function formatAgeMs(ms: number): string {\n  const s = Math.max(0, Math.floor(ms / 1000));\n  if (s >= 86_400) return `${Math.floor(s / 86_400)}d`;\n  if (s >= 3_600) return `${Math.floor(s / 3_600)}h`;\n  if (s >= 60) return `${Math.floor(s / 60)}m`;\n  return `${s}s`;\n}\n\n/**\n * Pure liveness verdict. Degraded when the feature is enabled AND any of: the\n * last-extraction watermark could not be READ (a storage fault, §22), the buffer\n * read failed (a pipeline fault, §22), or the buffer is non-empty and the\n * watermark is absent or stale. Each cause yields a DISTINCT reason so an\n * operator can tell a meta-read failure from a buffer-read failure from a\n * pipeline that has genuinely never extracted.\n *\n * Staleness uses a half-open freshness window (§23): an extraction is fresh\n * while its age is in `[0, staleWindowMs)`, so an age of EXACTLY `staleWindowMs`\n * is stale (the upper bound on \"fresh\" is exclusive). A null/unparsable watermark\n * means \"never succeeded\" and is treated as stale — as is a FUTURE watermark (a\n * clock-skewed or corrupt timestamp ahead of now must not read as a fresh\n * extraction and hide a real backlog stall).\n */\nexport function evaluateExtractionLiveness(input: {\n  config: ExtractionLivenessConfig;\n  lastExtractionAt: string | null;\n  snapshot: ExtractionBufferSnapshot;\n  nowMs: number;\n  metaReadFailed?: boolean;\n  metaReadError?: string;\n  watermarkPending?: boolean;\n}): ExtractionLivenessStatus {\n  const { config, lastExtractionAt, snapshot, nowMs } = input;\n  const lastMs = lastExtractionAt !== null ? Date.parse(lastExtractionAt) : Number.NaN;\n  const hasWatermark = Number.isFinite(lastMs);\n  const ageMs = nowMs - lastMs;\n  // A future watermark (negative age) is clock-skewed or corrupt data, not a\n  // fresh extraction: treat it as stale so a real backlog stall is not hidden.\n  const stale = !hasWatermark || ageMs < 0 || ageMs >= config.staleWindowMs;\n  const hasBacklog = snapshot.bufferedSessionCount > 0;\n  // A watermark or buffer that cannot be READ is a fault, not an empty queue\n  // (§22): a storage/pipeline outage must not read as healthy, and must stay\n  // distinct from a pipeline that has genuinely never extracted.\n  const metaReadFailed = input.metaReadFailed === true;\n  const watermarkPending = input.watermarkPending === true;\n  const readFailed = snapshot.readFailed === true;\n  const degraded =\n    config.enabled && (metaReadFailed || readFailed || (!watermarkPending && hasBacklog && stale));\n\n  let degradedReason: string | null = null;\n  if (degraded) {\n    if (metaReadFailed) {\n      degradedReason = `extraction watermark unreadable: ${input.metaReadError ?? \"meta read failed\"}`;\n    } else if (readFailed) {\n      degradedReason = `extraction buffer unreadable: ${snapshot.readError ?? \"buffer snapshot read failed\"}`;\n    } else {\n      const watermark = hasWatermark\n        ? `last succeeded ${formatAgeMs(nowMs - lastMs)} ago`\n        : \"no successful extraction on record\";\n      degradedReason =\n        `${watermark}; ${snapshot.bufferedSessionCount} buffered session(s), ` +\n        `${snapshot.pendingTurnCount} turn(s) pending extraction`;\n    }\n  }\n\n  return {\n    lastExtractionAt,\n    bufferedSessionCount: snapshot.bufferedSessionCount,\n    pendingTurnCount: snapshot.pendingTurnCount,\n    oldestBufferedTurnAgeMs: ageMsFrom(snapshot.oldestTurnTimestamp, nowMs),\n    degraded,\n    degradedReason,\n    ...(watermarkPending ? { watermarkPending: true } : {}),\n    watermarkScope: \"aggregate\",\n  };\n}\n\nconst EMPTY_SNAPSHOT: ExtractionBufferSnapshot = {\n  bufferedSessionCount: 0,\n  pendingTurnCount: 0,\n  oldestTurnTimestamp: null,\n};\n\n/**\n * Read a buffer snapshot without throwing. An ABSENT buffer degrades to an empty\n * (healthy) snapshot — some service constructions have no orchestrator buffer. A\n * buffer that EXISTS but whose read throws yields a `readFailed` snapshot so the\n * verdict can distinguish a pipeline fault from an empty queue (§22).\n */\nasync function readBufferSnapshot(\n  buffer: ExtractionBufferSource | undefined,\n): Promise<ExtractionBufferSnapshot> {\n  if (!buffer || typeof buffer.getBufferSnapshot !== \"function\") return EMPTY_SNAPSHOT;\n  try {\n    return await buffer.getBufferSnapshot();\n  } catch (err) {\n    return {\n      ...EMPTY_SNAPSHOT,\n      readFailed: true,\n      readError: err instanceof Error ? err.message : String(err),\n    };\n  }\n}\n\n/**\n * Gather the liveness status from an aggregate watermark read and an optional\n * buffer. A read failure on either side is surfaced as a degraded status with a\n * distinct reason rather than swallowed into a healthy-looking verdict.\n */\nexport async function gatherExtractionLivenessStatus(input: {\n  config: ExtractionLivenessConfig;\n  watermark: ExtractionWatermarkOrStorage;\n  buffer: ExtractionBufferSource | undefined;\n  nowMs: number;\n}): Promise<ExtractionLivenessStatus> {\n  const { config, buffer, nowMs } = input;\n  const watermarkRead = await coerceExtractionWatermark(input.watermark);\n  const snapshot = await readBufferSnapshot(buffer);\n  return evaluateExtractionLiveness({\n    config,\n    lastExtractionAt: watermarkRead.lastExtractionAt,\n    snapshot,\n    nowMs,\n    metaReadFailed: watermarkRead.readFailed,\n    metaReadError: watermarkRead.readError,\n    watermarkPending: watermarkRead.pending,\n  });\n}\n\n/**\n * Aggregated-WARN throttle (issue #2151): emit at most ONE warning per\n * staleness window while degraded — not one line per failed extraction attempt.\n * State is instance-scoped (held by the owning service), never a module global\n * (§5), so multiple service instances throttle independently.\n */\nexport class ExtractionLivenessWarnThrottle {\n  private lastWarnAtMs: number | null = null;\n\n  /** Warn if degraded and outside the throttle window; returns whether a WARN was emitted. */\n  maybeWarn(status: ExtractionLivenessStatus, staleWindowMs: number, nowMs: number): boolean {\n    if (!status.degraded) {\n      // Recovered (or never degraded): reset so a fresh episode warns at once.\n      this.lastWarnAtMs = null;\n      return false;\n    }\n    if (this.lastWarnAtMs !== null && nowMs - this.lastWarnAtMs < staleWindowMs) return false;\n    this.lastWarnAtMs = nowMs;\n    log.warn(\n      `extraction pipeline liveness degraded: ${status.degradedReason ?? \"buffered turns are not being extracted\"}`,\n    );\n    return true;\n  }\n}\n\n/**\n * Normalize the `extractionLiveness` block at the read boundary. `parseConfig`\n * always populates it, but a host adapter, an older persisted config, or a\n * hand-built `PluginConfig` can hand us an absent, partial, or loosely-typed\n * block - and every liveness surface (/health, doctor, stats) must degrade to\n * the documented default (enabled, 24h window) rather than throw. Both fields\n * are coerced with the same rules as `parseExtractionLivenessConfig` (§24:\n * `\"false\"`/`\"0\"` read as falsy; a numeric string like `\"5000\"` parses), except a\n * present but non-integer or non-positive `staleWindowMs` falls back to the\n * default here rather than throwing.\n */\nexport function resolveExtractionLivenessConfig(\n  block: { enabled?: unknown; staleWindowMs?: unknown } | undefined,\n): ExtractionLivenessConfig {\n  const staleWindowMs = coerceNumber(block?.staleWindowMs);\n  return {\n    enabled: coerceBool(block?.enabled) ?? true,\n    staleWindowMs:\n      staleWindowMs !== undefined && Number.isInteger(staleWindowMs) && staleWindowMs >= 1\n        ? staleWindowMs\n        : DEFAULT_STALE_WINDOW_MS,\n  };\n}\n\n/**\n * Compute the daemon-wide liveness status for the authenticated `/health`\n * payload and emit the throttled aggregate warning.\n */\nexport async function computeExtractionLivenessStatus(\n  orchestrator: ExtractionLivenessOrchestratorLike,\n  watermark: ExtractionWatermarkOrStorage,\n  throttle?: ExtractionLivenessWarnThrottle,\n  nowMs: number = Date.now(),\n): Promise<ExtractionLivenessStatus> {\n  const config = resolveExtractionLivenessConfig(orchestrator.config.extractionLiveness);\n  const status = await gatherExtractionLivenessStatus({\n    config,\n    watermark,\n    buffer: orchestrator.buffer,\n    nowMs,\n  });\n  throttle?.maybeWarn(status, config.staleWindowMs, nowMs);\n  return status;\n}\n\n/**\n * `remnic doctor` check for extraction-pipeline liveness. Status `warn` when\n * degraded (with a remediation hint), `ok` otherwise.\n */\nexport async function summarizeExtractionLiveness(\n  config: Pick<PluginConfig, \"extractionLiveness\">,\n  watermark: ExtractionWatermarkOrStorage,\n  buffer?: ExtractionBufferSource,\n  nowMs: number = Date.now(),\n): Promise<OperatorDoctorCheck> {\n  const livenessConfig = resolveExtractionLivenessConfig(config.extractionLiveness);\n  const status = await gatherExtractionLivenessStatus({\n    config: livenessConfig,\n    watermark,\n    buffer,\n    nowMs,\n  });\n  const scopeNote = ` Watermark scope: ${status.watermarkScope}.`;\n  const summary =\n    (status.degraded\n      ? `Extraction pipeline degraded: ${status.degradedReason}.`\n      : `Extraction pipeline healthy: last extraction ${status.lastExtractionAt ?? \"never\"}, ` +\n        `${status.bufferedSessionCount} buffered session(s), ${status.pendingTurnCount} turn(s) pending` +\n        `${livenessConfig.enabled ? \"\" : \" (liveness check disabled)\"}.`) + scopeNote;\n  return {\n    key: \"extraction_liveness\",\n    status: status.degraded ? \"warn\" : \"ok\",\n    summary,\n    remediation: status.degraded\n      ? \"Extraction has stalled while turns are buffered. Inspect daemon logs for extraction \" +\n        \"timeouts or fallback-no-parsed-output errors, verify the extraction model/provider is \" +\n        \"reachable, then force a flush (e.g. `remnic flush`).\"\n      : undefined,\n    details: { ...status, staleWindowMs: livenessConfig.staleWindowMs, enabled: livenessConfig.enabled },\n  };\n}\n\n/**\n * Lines for `remnic stats`: the aggregate extraction watermark, root metadata\n * counters, buffer backlog, and liveness verdict. Root counter failures render\n * those counters unavailable; the injected aggregate read alone determines\n * watermark liveness so stats cannot diverge from health and doctor.\n */\nexport async function renderExtractionLivenessStats(\n  orchestrator: ExtractionLivenessOrchestratorLike,\n  watermark: ExtractionWatermarkRead,\n  nowMs: number = Date.now(),\n): Promise<string[]> {\n  const status = evaluateExtractionLiveness({\n    config: resolveExtractionLivenessConfig(orchestrator.config.extractionLiveness),\n    lastExtractionAt: watermark.lastExtractionAt,\n    snapshot: await readBufferSnapshot(orchestrator.buffer),\n    nowMs,\n    metaReadFailed: watermark.readFailed,\n    metaReadError: watermark.readError,\n    watermarkPending: watermark.pending,\n  });\n  const oldestAge =\n    status.oldestBufferedTurnAgeMs !== null ? formatAgeMs(status.oldestBufferedTurnAgeMs) : \"n/a\";\n  const rootStats = watermark.rootStats;\n  const watermarkDisplay = watermark.readFailed\n    ? \"unavailable\"\n    : watermark.pending\n      ? \"pending\"\n      : status.lastExtractionAt ?? \"never\";\n  return [\n    `Extractions: ${rootStats?.extractionCount ?? \"unavailable\"}`,\n    `Last extraction: ${watermarkDisplay}`,\n    `Last consolidation: ${rootStats ? rootStats.lastConsolidationAt ?? \"never\" : \"unavailable\"}`,\n    `Buffered sessions: ${status.bufferedSessionCount} (${status.pendingTurnCount} turns pending)`,\n    `Oldest buffered turn age: ${oldestAge}`,\n    `Extraction watermark scope: ${status.watermarkScope}`,\n    `Extraction liveness: ${status.degraded ? `DEGRADED — ${status.degradedReason}` : \"ok\"}`,\n  ];\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-MHCRASVK.js → chunk-5N26WBPQ.js}

@@ -1,6 +1,6 @@
 import {
   StorageManager
-} from "./chunk-ENLZOWYK.js";
+} from "./chunk-ZERSIPFC.js";
 import {
   assertPathInsideRoot
 } from "./chunk-GCASGYIO.js";
@@ -759,4 +759,4 @@ export {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact
 };
-//# sourceMappingURL=chunk-MHCRASVK.js.map
+//# sourceMappingURL=chunk-5N26WBPQ.js.map

package/dist/{chunk-CMFUYOYB.js → chunk-5TOV3D6U.js}

@@ -1,6 +1,6 @@
 import {
   StorageManager
-} from "./chunk-ENLZOWYK.js";
+} from "./chunk-ZERSIPFC.js";
 import {
   getCachedRuleMemories,
   setCachedRuleMemories
@@ -119,4 +119,4 @@ export {
   compareVerifiedSemanticRuleResults,
   searchVerifiedSemanticRules
 };
-//# sourceMappingURL=chunk-CMFUYOYB.js.map
+//# sourceMappingURL=chunk-5TOV3D6U.js.map

package/dist/{chunk-SHTPVI47.js → chunk-6GIMMNVK.js}

@@ -7,13 +7,13 @@ import {
 import {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact
-} from "./chunk-MHCRASVK.js";
+} from "./chunk-5N26WBPQ.js";
 import {
   commitPreparedFileAtomically
 } from "./chunk-R6YJI3HE.js";
 import {
   StorageManager
-} from "./chunk-ENLZOWYK.js";
+} from "./chunk-ZERSIPFC.js";
 import {
   assertInjectedStorageRooted,
   readProjectedEntityMentionRows,
@@ -1001,4 +1001,4 @@ export {
   verifyMemoryProjection,
   repairMemoryProjection
 };
-//# sourceMappingURL=chunk-SHTPVI47.js.map
+//# sourceMappingURL=chunk-6GIMMNVK.js.map

package/dist/{chunk-5JUYBWJD.js → chunk-6I2C3EOH.js}

@@ -16,7 +16,7 @@ import {
 import {
   ActivityStore,
   MaintenanceScheduler
-} from "./chunk-5TRIAPT4.js";
+} from "./chunk-NHRNYJPJ.js";
 import {
   migrateFromEngram
 } from "./chunk-7HYPN2GC.js";
@@ -32,7 +32,7 @@ import {
 import {
   CompoundingEngine,
   defaultTierMigrationCycleBudget
-} from "./chunk-F5EVTFQK.js";
+} from "./chunk-MSXWUXFE.js";
 import {
   SharedContextManager
 } from "./chunk-AS7YMSL6.js";
@@ -198,7 +198,7 @@ import {
   buildEntityRecallSection,
   entityRecentTranscriptLookbackHours,
   readRecentEntityTranscriptEntries
-} from "./chunk-DJH35IVS.js";
+} from "./chunk-JDXDA5OO.js";
 import {
   buildEventOrderRecallSection,
   shouldRecallEventOrderEvidence
@@ -214,7 +214,7 @@ import {
   ensureBuiltInWearableConnectors,
   getWearableConnector,
   listWearableConnectors
-} from "./chunk-KJP2R5MJ.js";
+} from "./chunk-UGCUVLOL.js";
 import {
   normalizeReplaySessionKey
 } from "./chunk-AJVLDJU6.js";
@@ -224,14 +224,14 @@ import {
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-VGK33D3K.js";
+} from "./chunk-OEXKYYVH.js";
 import {
   ThreadingManager
 } from "./chunk-OJP3N7UK.js";
 import {
   compareVerifiedSemanticRuleResults,
   searchVerifiedSemanticRules
-} from "./chunk-CMFUYOYB.js";
+} from "./chunk-5TOV3D6U.js";
 import {
   searchWorkProductLedgerEntries
 } from "./chunk-ZRWB5D4H.js";
@@ -244,11 +244,11 @@ import {
 import {
   runNamespaceMaintenanceFanout,
   summarizeNamespaceMaintenanceHealth
-} from "./chunk-GYGXKATH.js";
+} from "./chunk-CQ5MR2HQ.js";
 import {
   NamespaceCatalog,
   planNamespaceMaintenance
-} from "./chunk-7ERHAARG.js";
+} from "./chunk-BI6RE2ZS.js";
 import {
   isAboveImportanceThreshold,
   scoreImportance
@@ -283,7 +283,7 @@ import {
   materializeAfterSemanticConsolidation,
   parseConsolidationResponse,
   parseOperatorAwareConsolidationResponse
-} from "./chunk-AL73FWSS.js";
+} from "./chunk-QY66HJ4X.js";
 import {
   buildBehaviorSignalsForMemory,
   dedupeBehaviorSignalsByMemoryAndHash
@@ -305,7 +305,7 @@ import {
 } from "./chunk-UQ7RN5HK.js";
 import {
   detectMeetings
-} from "./chunk-IB26HVAJ.js";
+} from "./chunk-TM72UOX2.js";
 import {
   compileCorrectionRule,
   correctionsFilePath,
@@ -322,7 +322,7 @@ import {
 } from "./chunk-LBJBNWS2.js";
 import {
   MeetingsInputError
-} from "./chunk-CYM2PHLB.js";
+} from "./chunk-CWPDM66T.js";
 import {
   WearablesInputError,
   describeErrorForOperator
@@ -340,7 +340,7 @@ import {
   capturePassiveCorrections,
   clusterByKey,
   detectPassiveCorrections
-} from "./chunk-BVJIAIB3.js";
+} from "./chunk-Q4XL7LJW.js";
 import {
   importCapsule
 } from "./chunk-3CE77VAP.js";
@@ -360,7 +360,7 @@ import {
 } from "./chunk-JGSKJHF7.js";
 import {
   buildXraySnapshot
-} from "./chunk-KWU6MAD4.js";
+} from "./chunk-R4Q7CQGZ.js";
 import {
   boundRecallContextComposition,
   composeRecallContext,
@@ -399,7 +399,7 @@ import {
 } from "./chunk-CYEPCZN5.js";
 import {
   NamespaceStorageRouter
-} from "./chunk-UGAZILZG.js";
+} from "./chunk-F2KMAFEB.js";
 import {
   writeConversationChunks
 } from "./chunk-72A4L5JJ.js";
@@ -462,7 +462,7 @@ import {
 } from "./chunk-NRV4Y3PM.js";
 import {
   buildChainFollowupGenerator
-} from "./chunk-AVGTOOYP.js";
+} from "./chunk-3C2TGBDB.js";
 import {
   QmdResultResolver,
   StorageManager,
@@ -481,7 +481,7 @@ import {
   reconstructFusionInputs,
   selfDeps,
   serializeFusionDay
-} from "./chunk-ENLZOWYK.js";
+} from "./chunk-ZERSIPFC.js";
 import {
   bodyIsEscaped,
   decodeTranscriptBody,
@@ -502,7 +502,7 @@ import {
 } from "./chunk-J6A3CX5N.js";
 import {
   confidenceTier
-} from "./chunk-HXDWZFNP.js";
+} from "./chunk-GSL47NPM.js";
 import {
   namespaceIdentityFromToken,
   namespaceIdentityToken,
@@ -23923,4 +23923,4 @@ export {
   filterRecallCandidates,
   Orchestrator
 };
-//# sourceMappingURL=chunk-5JUYBWJD.js.map
+//# sourceMappingURL=chunk-6I2C3EOH.js.map

package/dist/chunk-7VIB7PAE.js

@@ -0,0 +1,142 @@
+import {
+  resolveCorpusNamespaceRoots
+} from "./chunk-OYFDEJZB.js";
+import {
+  normalizeNamespaceIdentity
+} from "./chunk-EGGE52UU.js";
+import {
+  capabilityAllowsNamespace
+} from "./chunk-MZWSOLMT.js";
+import {
+  resolveNamespaceCapabilities
+} from "./chunk-2XRE6FLM.js";
+
+// src/orchestration/extraction-watermark.ts
+import path from "path";
+function readFailure(reason, rootStats) {
+  return {
+    lastExtractionAt: null,
+    readFailed: true,
+    readError: reason,
+    ...rootStats ? { rootStats } : {}
+  };
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function watermarkFromMeta(meta, name) {
+  if (meta.lastExtractionAt !== null && meta.lastExtractionAt !== void 0) {
+    const parsed = Date.parse(meta.lastExtractionAt);
+    if (!Number.isFinite(parsed)) {
+      return readFailure(`${name} watermark timestamp invalid`);
+    }
+  }
+  const hasRootStats = meta.extractionCount !== void 0 || meta.lastConsolidationAt !== void 0;
+  return {
+    lastExtractionAt: meta.lastExtractionAt ?? null,
+    readFailed: false,
+    ...hasRootStats ? {
+      rootStats: {
+        extractionCount: meta.extractionCount,
+        lastConsolidationAt: meta.lastConsolidationAt
+      }
+    } : {}
+  };
+}
+async function readWatermark(storage, name) {
+  try {
+    return watermarkFromMeta(await storage.loadMeta(), name);
+  } catch (error) {
+    return readFailure(`${name} watermark unreadable: ${errorMessage(error)}`);
+  }
+}
+async function resolveRoots(options) {
+  const compute = () => resolveCorpusNamespaceRoots({
+    config: options.config,
+    propagateDiscoveryErrors: true
+  });
+  if (options.rootsCache) {
+    const { roots, refreshError } = options.rootsCache.getResolvedRootsStatus(compute);
+    if (refreshError !== void 0) {
+      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) {
+  return !Array.isArray(value);
+}
+function newerWatermark(current, candidate) {
+  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;
+}
+async function readAggregateExtractionWatermark(options) {
+  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 = /* @__PURE__ */ new Set([rootDir]);
+  const targets = [];
+  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 = { 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 } : {}
+  };
+}
+
+export {
+  readAggregateExtractionWatermark
+};
+//# sourceMappingURL=chunk-7VIB7PAE.js.map

package/dist/chunk-7VIB7PAE.js.map

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

package/dist/{chunk-CNZLKQEL.js → chunk-AXUU7SG3.js}

@@ -2,7 +2,7 @@ import {
   OPERATION_NAMES,
   getOperation,
   operationRequiresAuthorizedNamespace
-} from "./chunk-BVJIAIB3.js";
+} from "./chunk-Q4XL7LJW.js";
 import {
   assertOperationAuthorizationAllowed
 } from "./chunk-MZWSOLMT.js";
@@ -49,4 +49,4 @@ export {
   probeOperationAuthorization,
   authorizationProbeNamespaces
 };
-//# sourceMappingURL=chunk-CNZLKQEL.js.map
+//# sourceMappingURL=chunk-AXUU7SG3.js.map

package/dist/{chunk-7ERHAARG.js → chunk-BI6RE2ZS.js}

@@ -4,7 +4,7 @@ import {
 import {
   resolveDefaultNamespaceRoot,
   resolveNamespaceStorageRoot
-} from "./chunk-UGAZILZG.js";
+} from "./chunk-F2KMAFEB.js";
 import {
   namespaceIdentityFromToken,
   namespaceIdentityToken,
@@ -2204,4 +2204,4 @@ export {
   runNamespaceMaintenancePlan,
   runNamespaceMaintenanceBatchPlan
 };
-//# sourceMappingURL=chunk-7ERHAARG.js.map
+//# sourceMappingURL=chunk-BI6RE2ZS.js.map