@remnic/core 9.7.15 → 9.9.0

package/src/cross-namespace-budget.ts

@@ -67,6 +67,17 @@ export type BudgetDecisionReason =
   | "warn-over-soft"
   | "deny-over-hard";
 
+/**
+ * Opaque token identifying the EXACT window entry a {@link CrossNamespaceBudget.record}
+ * reserve created (issue #1906 review #4). Pass it to `release()` to remove
+ * that specific entry — never "the newest", which under concurrency could evict
+ * a different (newer) recall's reservation and reopen the limiter early.
+ */
+export interface BudgetReservation {
+  principal: string;
+  id: number;
+}
+
 export interface BudgetDecision {
   allowed: boolean;
   reason: BudgetDecisionReason;
@@ -78,11 +89,40 @@ export interface BudgetDecision {
     hardLimit: number;
     windowMs: number;
   };
+  /**
+   * Present only when this decision RESERVED a window entry (an allowed
+   * `record()`), so the caller can later `release(reservation)` that exact
+   * entry on a failed/aborted recall. Absent on denials, peeks, and
+   * same-namespace/no-limit decisions.
+   */
+  reservation?: BudgetReservation;
+}
+
+/**
+ * Response-safe projection of a soft-limit warning: a {@link BudgetDecision}
+ * WITHOUT the server-only `reservation` rollback token (which carries the
+ * principal id). This is what may be surfaced on HTTP/MCP recall responses and
+ * persisted in idempotency-cache entries, so it must never carry internal quota
+ * state (issue #1906 review round 10 #2).
+ */
+export type BudgetWarning = Omit<BudgetDecision, "reservation">;
+
+/**
+ * Project a decision to its response-safe {@link BudgetWarning}, stripping the
+ * internal `reservation` token. Returns `undefined` unless the decision is a
+ * soft-limit warning (`warn-over-soft`) — so callers can assign the result to
+ * `budgetWarning` directly.
+ */
+export function toBudgetWarning(decision: BudgetDecision): BudgetWarning | undefined {
+  if (decision.reason !== "warn-over-soft") return undefined;
+  const { reservation: _reservation, ...warning } = decision;
+  return warning;
 }
 
 interface PrincipalBucket {
-  /** Epoch-ms timestamps of cross-namespace reads in the active window. */
-  timestamps: number[];
+  /** Cross-namespace reads in the active window, each tagged with a unique id
+   *  so a specific reservation can be released without disturbing others. */
+  entries: Array<{ id: number; ts: number }>;
 }
 
 /**
@@ -149,6 +189,8 @@ function normalizeClock(now: number | undefined): number {
 export class CrossNamespaceBudget {
   private readonly config: Required<CrossNamespaceBudgetConfig>;
   private readonly buckets = new Map<string, PrincipalBucket>();
+  /** Monotonic id source for reservation tokens (issue #1906 review #4). */
+  private reservationSeq = 0;
 
   constructor(config?: CrossNamespaceBudgetConfig) {
     this.config = effectiveConfig(config);
@@ -192,46 +234,51 @@ export class CrossNamespaceBudget {
       principal = "__anonymous__";
     }
 
-    const bucket = this.buckets.get(principal) ?? { timestamps: [] };
+    const bucket = this.buckets.get(principal) ?? { entries: [] };
     const cutoff = normalizedNow - windowMs;
-    // Drop timestamps that slid out of the window.
-    while (bucket.timestamps.length > 0 && bucket.timestamps[0]! < cutoff) {
-      bucket.timestamps.shift();
+    // Drop entries that slid out of the window.
+    while (bucket.entries.length > 0 && bucket.entries[0]!.ts < cutoff) {
+      bucket.entries.shift();
     }
 
     // Count the current call against the window BEFORE deciding — a call
     // that crosses the deny threshold should itself be denied, not the
     // next one. This is what the threat model calls "fail at the Nth,
     // not the (N+1)th".
-    bucket.timestamps.push(normalizedNow);
+    const id = ++this.reservationSeq;
+    bucket.entries.push({ id, ts: normalizedNow });
     this.buckets.set(principal, bucket);
-    const count = bucket.timestamps.length;
+    const count = bucket.entries.length;
 
     if (count >= hardLimit) {
-      // Denied: roll back the timestamp we just added so a repeated denied
+      // Denied: roll back the entry we just added so a repeated denied
       // call does not push the bucket further into the future. This keeps
       // the limiter stateless with respect to denied attempts.
-      bucket.timestamps.pop();
+      bucket.entries.pop();
       // Evict empty buckets (e.g. the first record after a long idle
-      // rolled the only timestamp out, then got denied and rolled back).
+      // rolled the only entry out, then got denied and rolled back).
       // Prevents unbounded map growth across many transient principals.
-      if (bucket.timestamps.length === 0) {
+      if (bucket.entries.length === 0) {
         this.buckets.delete(principal);
       }
       return {
         allowed: false,
         reason: "deny-over-hard",
-        count: bucket.timestamps.length,
+        count: bucket.entries.length,
         limit,
       };
     }
 
+    // Allowed: the entry stands as a reservation the caller can later release
+    // by token (issue #1906 review #4).
+    const reservation: BudgetReservation = { principal, id };
     if (count > softLimit) {
       return {
         allowed: true,
         reason: "warn-over-soft",
         count,
         limit,
+        reservation,
       };
     }
 
@@ -240,6 +287,7 @@ export class CrossNamespaceBudget {
       reason: "allowed-under-soft",
       count,
       limit,
+      reservation,
     };
   }
 
@@ -283,11 +331,11 @@ export class CrossNamespaceBudget {
       principal = "__anonymous__";
     }
     const now = normalizeClock(args.now);
-    const bucket = this.buckets.get(principal) ?? { timestamps: [] };
+    const bucket = this.buckets.get(principal) ?? { entries: [] };
     const cutoff = now - windowMs;
     let liveCount = 0;
-    for (const ts of bucket.timestamps) {
-      if (ts >= cutoff) liveCount++;
+    for (const entry of bucket.entries) {
+      if (entry.ts >= cutoff) liveCount++;
     }
     const projected = liveCount + 1; // +1 for the current call
     if (projected >= hardLimit) {
@@ -335,6 +383,25 @@ export class CrossNamespaceBudget {
     return this.record(args.principal, args.now);
   }
 
+  /**
+   * Roll back the EXACT reservation made by an allowed {@link record} (issue
+   * #1906 review #4). When a recall reserves budget at admission but then fails
+   * or is aborted, the caller releases its own `reservation` token so the
+   * errored recall does not consume budget permanently — and, critically, does
+   * NOT evict a different concurrent recall's entry (which could expire early
+   * and reopen the limiter). A no-op when the token is absent or already gone.
+   * Evicts empty buckets.
+   */
+  release(reservation: BudgetReservation | null | undefined): void {
+    if (!reservation) return;
+    const bucket = this.buckets.get(reservation.principal);
+    if (!bucket) return;
+    const index = bucket.entries.findIndex((entry) => entry.id === reservation.id);
+    if (index < 0) return;
+    bucket.entries.splice(index, 1);
+    if (bucket.entries.length === 0) this.buckets.delete(reservation.principal);
+  }
+
   /**
    * Clear all state. Intended for tests and for the orchestrator's
    * lifecycle `before_reset` hook.
@@ -355,10 +422,10 @@ export class CrossNamespaceBudget {
     const cutoff = normalizedNow - this.config.windowMs;
     let evicted = 0;
     for (const [principal, bucket] of this.buckets.entries()) {
-      while (bucket.timestamps.length > 0 && bucket.timestamps[0]! < cutoff) {
-        bucket.timestamps.shift();
+      while (bucket.entries.length > 0 && bucket.entries[0]!.ts < cutoff) {
+        bucket.entries.shift();
       }
-      if (bucket.timestamps.length === 0) {
+      if (bucket.entries.length === 0) {
         this.buckets.delete(principal);
         evicted++;
       }

package/src/explicit-capture.ts

@@ -1,3 +1,4 @@
+import { composeMemoryEnvelope, TAG_LIMITS } from "./write-envelope.js";
 import { resolveNamespaceCapabilities } from "./capabilities.js";
 import { randomUUID } from "node:crypto";
 import type { Orchestrator } from "./orchestrator.js";
@@ -366,15 +367,31 @@ export function validateExplicitCaptureInput(
   }
   const expiresAt = parseExplicitCaptureTtl(input.ttl);
 
+  // #2014 review round: enforce the composer's tag contract HERE so a capture
+  // that passes validation can never fail later at strict compose time
+  // (validated-then-thrown was a broken contract). Same limits as TAG_LIMITS.
+  const dedupedTags = Array.from(new Set((input.tags ?? []).map((tag) => tag.trim()).filter(Boolean)));
+  if (dedupedTags.length > TAG_LIMITS.maxTags) {
+    throw new Error(`too many tags: ${dedupedTags.length} exceeds the ${TAG_LIMITS.maxTags}-tag limit`);
+  }
+  for (const tag of dedupedTags) {
+    if (tag.length > TAG_LIMITS.maxTagLength) {
+      throw new Error(`tag exceeds ${TAG_LIMITS.maxTagLength} characters: ${JSON.stringify(tag.slice(0, 40))}…`);
+    }
+  }
+
   return {
     content,
     category,
     confidence,
     namespace: asTrimmed(input.namespace),
-    tags: Array.from(new Set((input.tags ?? []).map((tag) => tag.trim()).filter(Boolean))),
+    tags: dedupedTags,
     entityRef: asTrimmed(input.entityRef),
     sourceReason: asTrimmed(input.sourceReason),
-    sourceConnector: input.sourceConnector,
+    // Trimmed like the other optional metadata (#2017 review round): a
+    // whitespace-only connector previously passed validation and then blew
+    // up at strict compose time - validated input must always compose.
+    sourceConnector: asTrimmed(input.sourceConnector),
     expiresAt,
   };
 }
@@ -442,14 +459,21 @@ export async function persistExplicitCapture(
   // #1645 (review thread yG-): surface the tombstone block so callers
   // (memory_store tool, access-service HTTP/MCP) can report the capture as
   // queued for review instead of a successfully stored active memory.
-  const { id, tombstoneBlocked } = await storage.writeMemory(candidate.category, candidate.content, {
-    confidence: candidate.confidence,
-    tags: candidate.tags,
-    entityRef: candidate.entityRef,
-    expiresAt: candidate.expiresAt,
-    source: source === "inline" ? "explicit-inline" : "explicit",
-    ...(candidate.sourceConnector ? { sourceConnector: candidate.sourceConnector } : {}),
-  });
+  // Sealed-envelope write (issue #1989 PR2).
+  const captureEnvelope = composeMemoryEnvelope(
+    {
+      content: candidate.content,
+      category: candidate.category,
+      confidence: candidate.confidence,
+      tags: candidate.tags,
+      ...(candidate.entityRef ? { entityRef: candidate.entityRef } : {}),
+      ...(candidate.expiresAt ? { ttl: candidate.expiresAt } : {}),
+      ...(candidate.sourceConnector ? { sourceConnector: candidate.sourceConnector } : {}),
+      ...(candidate.sourceReason ? { sourceReason: candidate.sourceReason } : {}),
+    },
+    { source: source === "inline" ? "explicit-inline" : "explicit" },
+  );
+  const { id, tombstoneBlocked } = await storage.writeSealedMemory(captureEnvelope);
   // #1522: catalog touch handled at the storage chokepoint — the StorageManager's
   // post-write hook records the namespace touch automatically.
 
@@ -547,13 +571,26 @@ export async function queueExplicitCaptureForReview(
     : "fact";
   const requestedTags = sanitizeReviewTags(input.tags);
   const storage = await orchestrator.getStorage(queueNamespace);
-  const { id: id } = await storage.writeMemory(reviewCategory, content, {
-    confidence: 0.2,
-    tags: Array.from(new Set([...EXPLICIT_CAPTURE_REVIEW_TAGS, ...requestedTags])),
-    entityRef: sanitizeReviewMetadata(input.entityRef),
-    source: source === "inline" ? "explicit-inline-review" : "explicit-review",
-    ...(input.sourceConnector ? { sourceConnector: input.sourceConnector } : {}),
-  });
+  const reviewEnvelope = composeMemoryEnvelope(
+    {
+      content,
+      category: reviewCategory,
+      confidence: 0.2,
+      tags: Array.from(new Set([...EXPLICIT_CAPTURE_REVIEW_TAGS, ...requestedTags])),
+      ...(sanitizeReviewMetadata(input.entityRef) ? { entityRef: sanitizeReviewMetadata(input.entityRef) } : {}),
+      ...(input.sourceConnector ? { sourceConnector: input.sourceConnector } : {}),
+    },
+    { source: source === "inline" ? "explicit-inline-review" : "explicit-review" },
+    // The review queue is the FALLBACK for a capture that already failed
+    // primary validation — it must never be un-queueable. The tag list is
+    // machine-assembled (requested tags + the two fixed review tags), so 49+
+    // requested tags would push past the 50-tag limit and strict compose
+    // would throw, losing the capture (#2014 review round). Salvage clamps
+    // instead; the fixed review tags sort first in the assembly above, so
+    // they always survive the clamp.
+    { salvage: true },
+  );
+  const { id: id } = await storage.writeSealedMemory(reviewEnvelope);
   try {
     const created = await storage.getMemoryById(id);
     if (created) {

package/src/extraction.ts

@@ -2,6 +2,7 @@ import OpenAI from "openai";
 import { log } from "./logger.js";
 import { delinearize } from "./delinearize.js";
 import { LocalLlmClient } from "./local-llm.js";
+import { shouldRunProactivePass } from "./proactive-contention.js";
 import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig, gatewayTaskChainOptions } from "./fallback-llm.js";
 import {
   ExtractionResultSchema,
@@ -633,9 +634,7 @@ export class ExtractionEngine {
   ): Promise<ExtractionResult> {
     if (!resolvePipelineProcessingCapabilities(this.config).proactiveExtraction) return base;
     const maxAdditional = Math.max(0, Math.floor(this.config.maxProactiveQuestionsPerExtraction));
-    if (maxAdditional === 0) return base;
-    if (this.config.proactiveExtractionTimeoutMs === 0) return base;
-    if (this.config.proactiveExtractionMaxTokens === 0) return base;
+    if (!shouldRunProactivePass(this.config, maxAdditional, this.shouldUseLocalLlm, this.localLlm)) return base;
 
     try {
       const proactive = await this.generateProactiveQuestions(conversation, base, maxAdditional);

package/src/faithfulness-graph-guard.test.ts

@@ -26,6 +26,8 @@ import { readEdges } from "./graph.js";
 import type { ExtractionResult, PluginConfig } from "./types.js";
 import type { LocalLlmClient } from "./local-llm.js";
 import type { BufferTurn, ConversationThread } from "./types.js";
+import type { PersistExtractionFn } from "./testing/orchestrator-lite.js";
+import type { StorageManager } from "./storage.js";
 
 /**
  * Stub local LLM whose `chatCompletion` only answers faithfulness-gate calls
@@ -126,33 +128,18 @@ test("pending_review fact gets no graph edge; an active fact with the same entit
       faithfulnessStubLocalLlm((c) =>
         c.includes("closed permanently") ? "unsupported" : "entailed",
       );
-    const storage = await (orchestrator as unknown as {
-      getStorage: (ns: string) => Promise<{
-        ensureDirectories: () => Promise<void>;
-        readAllMemories: () => Promise<
-          Array<{
-            path: string;
-            frontmatter: { id: string; status?: string };
-          }>
-        >;
-      }>;
-    }).getStorage("default");
+    // getStorage + persistExtraction are private; reach them through a named production-typed surface.
+    const persist = orchestrator as unknown as {
+      getStorage: (ns: string) => Promise<StorageManager>;
+      persistExtraction: PersistExtractionFn;
+    };
+    const storage = await persist.getStorage("default");
     await storage.ensureDirectories();
 
     const sourceText =
       "The widget factory produces widgets. It launched last year. The team is small.";
 
-    const ids0 = await (orchestrator as unknown as {
-      persistExtraction: (
-        r: ExtractionResult,
-        s: unknown,
-        t: unknown,
-        ctx: unknown,
-        bn: unknown,
-        plan: unknown,
-        src: string,
-      ) => Promise<string[]>;
-    }).persistExtraction(
+    const { persistedIds: ids0 } = await persist.persistExtraction(
       factResult("The widget factory produces widgets daily.", "widget-factory"),
       storage,
       null,
@@ -166,17 +153,7 @@ test("pending_review fact gets no graph edge; an active fact with the same entit
 
     // fact1 → unsupported (pending_review). Under the bug it would originate an
     // entity edge to fact0; under the guard it must NOT.
-    const ids1 = await (orchestrator as unknown as {
-      persistExtraction: (
-        r: ExtractionResult,
-        s: unknown,
-        t: unknown,
-        ctx: unknown,
-        bn: unknown,
-        plan: unknown,
-        src: string,
-      ) => Promise<string[]>;
-    }).persistExtraction(
+    const { persistedIds: ids1 } = await persist.persistExtraction(
       factResult(
         "The widget factory closed permanently.",
         "widget-factory",
@@ -216,17 +193,7 @@ test("pending_review fact gets no graph edge; an active fact with the same entit
 
     // Control: an ACTIVE fact with the same entityRef DOES create entity edges
     // (proving the graph is wired and only pending_review is excluded).
-    const ids2 = await (orchestrator as unknown as {
-      persistExtraction: (
-        r: ExtractionResult,
-        s: unknown,
-        t: unknown,
-        ctx: unknown,
-        bn: unknown,
-        plan: unknown,
-        src: string,
-      ) => Promise<string[]>;
-    }).persistExtraction(
+    const { persistedIds: ids2 } = await persist.persistExtraction(
       factResult("The widget factory reopened this quarter.", "widget-factory"),
       storage,
       null,
@@ -312,26 +279,6 @@ function twoFactResult(
   } as unknown as ExtractionResult;
 }
 
-interface StorageLike {
-  ensureDirectories: () => Promise<void>;
-  dir: string;
-  readAllMemories: () => Promise<
-    Array<{ path: string; frontmatter: { id: string; status?: string } }>
-  >;
-}
-
-interface PersistExtractionSig {
-  (
-    r: ExtractionResult,
-    s: unknown,
-    t: string | null,
-    ctx: unknown,
-    bn: unknown,
-    plan: unknown,
-    src: string,
-  ): Promise<string[]>;
-}
-
 test("pending_review id must NOT enter persisted thread episodes across a cross-flush (#1635)", async () => {
   const { orchestrator, memoryDir } = await makeThreadHarness();
   try {
@@ -342,7 +289,7 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
       );
 
     const getStorage = orchestrator as unknown as {
-      getStorage: (ns: string) => Promise<StorageLike>;
+      getStorage: (ns: string) => Promise<StorageManager>;
     };
     const storage = await getStorage.getStorage("default");
     await storage.ensureDirectories();
@@ -365,10 +312,10 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
     assert.ok(threadId, "thread established via processTurn");
 
     const persist = orchestrator as unknown as {
-      persistExtraction: PersistExtractionSig;
+      persistExtraction: PersistExtractionFn;
       appendPersistedThreadEpisodes: (
         threadId: string,
-        persistedIds: string[],
+        persistedIds: string[]
       ) => Promise<void>;
     };
 
@@ -376,7 +323,7 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
       "The widget factory reopened this quarter after being closed permanently last year.";
 
     // --- Flush 1: an active fact + a pending_review fact, same thread ---
-    const flush1 = await persist.persistExtraction(
+    const { persistedIds: flush1 } = await persist.persistExtraction(
       twoFactResult(
         "The widget factory reopened this quarter.", "wf-active",
         "The widget factory closed permanently last year.", "wf-pending",
@@ -419,7 +366,7 @@ test("pending_review id must NOT enter persisted thread episodes across a cross-
     );
 
     // --- Flush 2: an active fact in the SAME thread ---
-    const flush2 = await persist.persistExtraction(
+    const { persistedIds: flush2 } = await persist.persistExtraction(
       factResult("The widget factory hired ten new engineers.", "wf-active"),
       storage,
       threadId,

package/src/graph-recall.test.ts

@@ -6,8 +6,39 @@ import {
   type GraphRecallOptions,
   runGraphRecall,
 } from "./graph-recall.js";
+import { mergeGraphExpandedResults } from "./orchestration/graph-recall-coordinator.js";
 import type { MemoryEdgeSource } from "./graph-retrieval.js";
 
+test("mergeGraphExpandedResults preserves same paths from different namespaces", () => {
+  const merged = mergeGraphExpandedResults(
+    [
+      {
+        docid: "default-memory",
+        path: "facts/same-id.md",
+        namespace: "default",
+        snippet: "default",
+        score: 0.8,
+      },
+      {
+        docid: "project-memory",
+        path: "facts/same-id.md",
+        namespace: "project-x",
+        snippet: "project",
+        score: 0.7,
+      },
+    ],
+    [],
+  );
+
+  assert.deepEqual(
+    merged.map((result) => [result.namespace, result.path]),
+    [
+      ["default", "facts/same-id.md"],
+      ["project-x", "facts/same-id.md"],
+    ],
+  );
+});
+
 const DEFAULT_CONFIG: GraphRecallConfig = {
   recallGraphEnabled: true,
   recallGraphDamping: 0.85,

package/src/index.ts

@@ -111,6 +111,26 @@ export {
   serializeEntityFile,
   type MemoryWriteResult,
 } from "./storage.js";
+export {
+  composeMemoryEnvelope,
+  buildAccessWriteRequestFingerprint,
+  buildObserveRequestFingerprint,
+  buildWriteIdempotencyPayload,
+  isSealedMemoryEnvelope,
+  sealedWriteToLegacyArgs,
+  TAG_LIMITS,
+  STRUCTURED_ATTRIBUTE_LIMITS,
+  WRITE_FINGERPRINT_FIELDS,
+  FINGERPRINT_EXEMPT_FIELDS,
+  FINGERPRINT_SCOPE_FIELDS,
+  type SealedMemoryEnvelope,
+  type MemoryWriteInput,
+  type WriteContext,
+  type FingerprintScope,
+  type AccessWriteFingerprintParts,
+  type ObserveFingerprintParts,
+  type ComposeEnvelopeOptions,
+} from "./write-envelope.js";
 export {
   getHostEmbeddingProvider,
   normalizeHostEmbeddingVector,
@@ -329,7 +349,7 @@ export { MeilisearchBackend } from "./search/meilisearch-backend.js";
 // ---------------------------------------------------------------------------
 
 export { buildEntityRecallSection } from "./entity-retrieval.js";
-export { resolvePrincipal } from "./namespaces/principal.js";
+export { isNamespacePolicyCovered, resolvePrincipal } from "./namespaces/principal.js";
 export {
   NamespaceCatalog,
   type NamespaceRecord,
@@ -810,7 +830,7 @@ export {
 // ---------------------------------------------------------------------------
 // Offline Sync
 // ---------------------------------------------------------------------------
-
+export { drainPendingImpressionsForOfflineSync, drainPendingLifecycleForOfflineSync } from "./offline-sync-impression-drain.js";
 export {
   OFFLINE_SYNC_APPLY_MAX_BODY_BYTES,
   OFFLINE_SYNC_CHANGESET_FORMAT,

package/src/local-llm.ts

@@ -858,11 +858,9 @@ export class LocalLlmClient {
     });
   }
 
-  private hasQueuedRequests(): boolean {
-    return (
-      this.requestQueues["recall-critical"].length > 0 ||
-      this.requestQueues.background.length > 0
-    );
+  /** True when a background-priority request occupies or awaits this client's local lane (issue #2011). */
+  isBackgroundLaneContended(): boolean {
+    return this.queueProcessing.has("background") || this.requestQueues.background.length > 0;
   }
 
   private dequeueQueuedRequest(priority: LocalLlmRequestPriority): LocalLlmQueuedRequest | null {
@@ -924,7 +922,7 @@ export class LocalLlmClient {
       next.resolve(result);
     } finally {
       this.queueProcessing.delete(next.priority);
-      if (this.hasQueuedRequests()) {
+      if (this.requestQueues["recall-critical"].length > 0 || this.requestQueues.background.length > 0) {
         this.scheduleQueueDrain();
       }
     }

package/src/logger.ts

@@ -60,6 +60,22 @@ export function initLogger(backend?: LoggerBackend, debug?: boolean, options?: L
   _clock = options?.clock ?? (() => new Date().toISOString());
 }
 
+// Whether a real backend has been installed via initLogger. Lets diagnostics
+// that must not be swallowed (config misconfiguration warnings) fall back to
+// console when a host-agnostic consumer uses core without calling initLogger.
+export function isLoggerInitialized(): boolean {
+  return _backend !== NOOP_LOGGER;
+}
+
+// Restore the pristine no-op backend (as at module load, before initLogger).
+// Primarily a test seam for exercising the standalone/no-host path.
+export function resetLogger(): void {
+  _backend = NOOP_LOGGER;
+  _debug = false;
+  _timestamps = true;
+  _clock = () => new Date().toISOString();
+}
+
 // Format one log line: "<iso> remnic: <msg>" when timestamps are enabled,
 // otherwise the legacy "remnic: <msg>". Timestamp is per-call.
 function fmt(msg: string, label = "remnic"): string {