@remnic/core 10.0.39 → 10.0.41

package/src/access-entity-principal.test.ts

@@ -0,0 +1,190 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test, { type TestContext } from "node:test";
+import { EngramAccessHttpServer } from "./access-http.js";
+import { getOperation } from "./access-boundary.js";
+import { EngramAccessService } from "./access-service.js";
+import { createChatExecutor } from "./chat/chat-executor.js";
+import { parseConfig } from "./config.js";
+import { NamespaceStorageRouter } from "./namespaces/storage.js";
+import type { Orchestrator } from "./orchestrator.js";
+
+interface EntityHttpBody {
+  error?: string;
+  found?: boolean;
+  namespace?: string;
+  entities?: Array<{ name?: string }>;
+  entity?: { name?: string };
+}
+
+interface McpToolBody {
+  result: { isError: boolean; content: Array<{ text: string }>; structuredContent: { entity: { name: string } } };
+}
+
+async function readMcp(response: Response): Promise<McpToolBody> {
+  // SAFETY: /mcp answers tools/call with the JSON-RPC result shape named above; each test asserts the fields it reads.
+  return (await response.json()) as McpToolBody;
+}
+
+async function readBody(response: Response): Promise<EntityHttpBody> {
+  // SAFETY: the access server answers these routes with the JSON shape named above; each test asserts the fields it reads.
+  return (await response.json()) as EntityHttpBody;
+}
+
+/** Entity reads need only config and real storage routing from the orchestrator. */
+async function createFixture(t: TestContext, namespacesEnabled = true) {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-entity-acl-"));
+  t.after(() => rm(memoryDir, { recursive: true, force: true }));
+  const config = parseConfig({
+    memoryDir,
+    namespacesEnabled,
+    defaultNamespace: "default",
+    sharedNamespace: "shared",
+    namespacePolicies: [
+      { name: "default", readPrincipals: ["owner"], writePrincipals: ["owner"] },
+      { name: "restricted", readPrincipals: ["owner", "reader"], writePrincipals: ["owner"] },
+    ],
+  });
+  const router = new NamespaceStorageRouter(config);
+  for (const namespace of namespacesEnabled ? ["default", "restricted"] : ["default"]) {
+    const storage = await router.storageFor(namespace);
+    const entitiesDir = path.join(storage.dir, "entities");
+    await mkdir(entitiesDir, { recursive: true });
+    await writeFile(path.join(entitiesDir, "project-widget.md"), [
+      `# Widget-${namespace}`,
+      "",
+      "**Type:** project",
+      "",
+      "## Summary",
+      "",
+      `Synthetic entity in ${namespace}.`,
+      "",
+    ].join("\n"));
+  }
+  const dependencies: Pick<Orchestrator, "config" | "getStorage"> = {
+    config,
+    getStorage: (namespace) => router.storageFor(namespace ?? config.defaultNamespace),
+  };
+  // SAFETY: the entity read paths touch only `config` and `getStorage` (the Pick above); the rest of the Orchestrator is unused here.
+  return new EngramAccessService(dependencies as Orchestrator);
+}
+
+test("entity service enforces read ACLs and requires a principal before list/get", async (t) => {
+  const service = await createFixture(t);
+  await assert.rejects(() => service.entityList({ namespace: "restricted" }, "intruder"), /not readable/);
+  await assert.rejects(() => service.entityGet("project-widget", "restricted", "intruder"), /not readable/);
+  await assert.rejects(() => service.entityList({ namespace: "restricted" }), /authentication required/);
+  await assert.rejects(() => service.entityGet("project-widget", "restricted"), /authentication required/);
+  await assert.rejects(() => service.entityList({}, "reader"), /not readable/);
+  await assert.rejects(() => service.entityGet("project-widget", undefined, "reader"), /not readable/);
+
+  const list = await service.entityList({ namespace: " restricted ", query: "widget", limit: 1 }, "reader");
+  assert.equal(list.namespace, "restricted");
+  assert.equal(list.total, 1);
+  assert.equal(list.entities[0]?.name, "Widget-restricted");
+  const entity = await service.entityGet("project-widget", " restricted ", "reader");
+  assert.equal(entity.namespace, "restricted");
+  assert.equal(entity.entity?.name, "Widget-restricted");
+  assert.deepEqual(await service.entityGet("missing", "restricted", "reader"), {
+    found: false, namespace: "restricted",
+  });
+});
+
+test("entity service retains principal-free reads when namespaces are disabled", async (t) => {
+  const service = await createFixture(t, false);
+  assert.equal((await service.entityList()).entities[0]?.name, "Widget-default");
+  assert.equal((await service.entityGet("project-widget")).entity?.name, "Widget-default");
+});
+
+test("entity_list registry dispatch preserves the trusted principal", async (t) => {
+  const service = await createFixture(t);
+  const operation = getOperation("entity_list");
+  assert.ok(operation);
+  await assert.rejects(
+    () => operation.run({ principal: "owner" }, { service, authenticatedPrincipal: "reader" }),
+    /not readable/,
+  );
+  const output = await operation.run({}, { service, authenticatedPrincipal: "owner" });
+  const result = JSON.parse(JSON.stringify(output)).result;
+  assert.equal(result.namespace, "default");
+  assert.equal(result.entities[0]?.name, "Widget-default");
+});
+
+test("HTTP and MCP entity reads bind ACLs to the transport principal across aliases", async (t) => {
+  const service = await createFixture(t);
+  const token = "synthetic-entity-token";
+  const server = new EngramAccessHttpServer({
+    service,
+    host: "127.0.0.1",
+    port: 0,
+    principal: "reader",
+    enableAdapters: false,
+    trustPrincipalHeader: false,
+    authTokenEntriesGetter: () => [{
+      token,
+      capabilities: { version: 1, ops: ["entity_get", "entity_list"], namespaces: ["default", "restricted"] },
+    }],
+  });
+  const started = await server.start();
+  t.after(() => server.stop());
+  const base = `http://${started.host}:${started.port}`;
+  const headers = {
+    authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    "x-engram-principal": "owner",
+  };
+  for (const prefix of ["engram", "remnic"]) {
+    // The entity HTTP routes are served under /engram/v1 only; the /remnic prefix is an alias for the MCP tool names below.
+    for (const suffix of prefix === "engram" ? ["entities", "entities/project-widget"] : []) {
+      const denied = await fetch(`${base}/${prefix}/v1/${suffix}?namespace=default&principal=owner`, { headers });
+      assert.equal(denied.status, 400);
+      assert.match((await readBody(denied)).error ?? "", /not readable/);
+      const allowed = await fetch(`${base}/${prefix}/v1/${suffix}?namespace=restricted`, { headers });
+      assert.equal(allowed.status, 200);
+      const body = await readBody(allowed);
+      assert.equal(body.namespace, "restricted");
+      assert.equal(suffix === "entities" ? body.entities?.[0]?.name : body.entity?.name, "Widget-restricted");
+    }
+    if (prefix === "engram") {
+      const missing = await fetch(`${base}/${prefix}/v1/entities/missing?namespace=restricted`, { headers });
+      assert.equal(missing.status, 404);
+      assert.equal((await readBody(missing)).found, false);
+    }
+
+    for (const namespace of ["default", "restricted"]) {
+      const response = await fetch(`${base}/mcp`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: `${prefix}-${namespace}`,
+          method: "tools/call",
+          params: {
+            name: `${prefix}.entity_get`,
+            arguments: {
+              name: "project-widget", namespace, principal: "owner", authenticatedPrincipal: "owner",
+            },
+          },
+        }),
+      });
+      assert.equal(response.status, 200);
+      const body = await readMcp(response);
+      assert.equal(body.result.isError, namespace === "default");
+      if (namespace === "default") {
+        assert.match(body.result.content[0].text, /not readable/);
+      } else {
+        assert.equal(body.result.structuredContent.entity.name, "Widget-restricted");
+      }
+    }
+  }
+});
+
+test("chat entity reads preserve the bound principal instead of losing identity", async (t) => {
+  const service = await createFixture(t);
+  const allowed = createChatExecutor({ service, namespace: "restricted", principal: "reader" });
+  assert.equal(JSON.parse(await allowed.entityGet("project-widget")).entity.name, "Widget-restricted");
+  const denied = createChatExecutor({ service, namespace: "default", principal: "reader" });
+  await assert.rejects(() => denied.entityGet("project-widget"), /not readable/);
+});

package/src/access-http.ts

@@ -2168,7 +2168,7 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
         query: parsed.searchParams.get("q") ?? undefined,
         limit,
         offset,
-      });
+      }, this.resolveRequestPrincipal(req));
       this.respondJson(res, 200, response);
       return;
     }
@@ -2178,7 +2178,7 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
       this.enforceTokenOp("entity_get"); // boundary dispatch (issue #1525)
       const entityName = decodeURIComponent(entityMatch[1] ?? "");
       const namespace = this.resolveNamespace(req, parsed.searchParams.get("namespace") ?? undefined);
-      const response = await this.service.entityGet(entityName, namespace);
+      const response = await this.service.entityGet(entityName, namespace, this.resolveRequestPrincipal(req));
       this.respondJson(res, response.found ? 200 : 404, response);
       return;
     }

package/src/access-operations-batch.ts

@@ -279,7 +279,7 @@ defineOperation({
     };
   },
 });
-defineOperation({ name: "entity_get", description: "Get entity.", schema: strictSchema({ name: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.entityGet(optStr(input.name) ?? "", optStr(input.namespace)) }) });
+defineOperation({ name: "entity_get", description: "Get entity.", schema: strictSchema({ name: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.entityGet(optStr(input.name) ?? "", optStr(input.namespace), ctx.authenticatedPrincipal) }) });
 defineOperation({ name: "review_queue_list", description: "List review queue.", schema: strictSchema({ runId: S.str, namespace: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.reviewQueue(optStr(input.runId) ?? "", optStr(input.namespace), ctx.authenticatedPrincipal) }) });
 // Issue #2482: observe validates through the canonical observeRequestSchema
 // (same as HTTP/MCP wire validation). Nullable wire fields (parts /
@@ -472,7 +472,7 @@ defineOperation({
     return { result: getRecallTimingStatus(ctx.service.configRef) };
   },
 });
-defineOperation({ name: "entity_list", description: "List entities.", schema: strictSchema({}), handler: async (_i, ctx) => ({ result: await ctx.service.entityList() }) });
+defineOperation({ name: "entity_list", description: "List entities.", schema: strictSchema({}), handler: async (_i, ctx) => ({ result: await ctx.service.entityList({}, ctx.authenticatedPrincipal) }) });
 defineOperation({ name: "maintenance_status", description: "Maintenance status.", schema: strictSchema({}), handler: async (_i, ctx) => ({ result: await ctx.service.maintenance() }) });
 defineOperation({ name: "quality_status", description: "Quality status.", schema: strictSchema({}), handler: async (_i, ctx) => ({ result: await ctx.service.quality() }) });
 defineOperation({ name: "trust_zones_status", description: "Trust-zone status.", schema: strictSchema({}), handler: async (_i, ctx) => ({ result: await ctx.service.trustZoneStatus() }) });

package/src/access-service.ts

@@ -3506,10 +3506,11 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
       query?: string;
       limit?: number;
       offset?: number;
-    } = {}
+    } = {},
+    principal?: string
   ): Promise<EngramAccessEntityListResponse> {
-    const storage = await this.orchestrator.getStorage(options.namespace);
-    const resolvedNamespace = options.namespace?.trim() || this.orchestrator.config.defaultNamespace;
+    const resolvedNamespace = this.resolveReadableNamespace(options.namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
     const { limit, offset } = normalizePagination(options.limit, options.offset);
     const query = options.query?.trim().toLowerCase() ?? "";
 
@@ -3553,9 +3554,9 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     };
   }
 
-  async entityGet(name: string, namespace?: string): Promise<EngramAccessEntityResponse> {
-    const storage = await this.orchestrator.getStorage(namespace);
-    const resolvedNamespace = namespace?.trim() || this.orchestrator.config.defaultNamespace;
+  async entityGet(name: string, namespace?: string, principal?: string): Promise<EngramAccessEntityResponse> {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
     const raw = await storage.readEntity(name);
     if (!raw) return { found: false, namespace: resolvedNamespace };
     return {

package/src/chat/chat-executor.ts

@@ -60,7 +60,7 @@ export function createChatExecutor(bindings: ChatExecutorBindings): ChatToolExec
     },
 
     async entityGet(name: string): Promise<string> {
-      const result = await service.entityGet(name, namespace);
+      const result = await service.entityGet(name, namespace, principal);
       return JSON.stringify(result);
     },
 

package/src/extraction-error-classification.ts

@@ -85,3 +85,26 @@ export function formatExtractionParseFailureLog(input: {
     `traceId=${input.traceId}`,
   ].join(" ");
 }
+
+/**
+ * The local endpoint answered, and what it said rejects this input (unusable content, or a client error that is not
+ * auth, timeout or rate limiting): the chunk's problem, not an outage. Retried like an empty parse, and a trigger-drain
+ * chunk that keeps drawing it is dropped after its recovery copy is saved.
+ */
+export class LocalLlmRejectedError extends Error {
+  constructor(readonly httpStatus?: number) {
+    super(httpStatus === undefined ? "local LLM answered with unusable content" : `local LLM rejected the input (HTTP ${httpStatus})`);
+    this.name = "LocalLlmRejectedError";
+  }
+}
+
+/** What the local client recorded about a failed call (`failureDiag`). */
+export interface LocalFailureDiag {
+  lastError?: unknown;
+}
+
+/** The HTTP status when the local endpoint answered and refuses this input (400, 413, 422); else undefined. A wrong model name or route (404, 405, 410), auth, timeout and rate limiting are the setup's problem, not the chunk's. */
+export function localRejectionStatus(diag: LocalFailureDiag): number | undefined {
+  const status = httpStatusFromError(diag.lastError);
+  return status !== undefined && [400, 413, 422].includes(status) ? status : undefined;
+}

package/src/extraction-local-failure-class.test.ts

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { ExtractionEngine } from "./extraction.js";
+import type { BufferTurn } from "./types.js";
+
+// Follow-up to #3266: the trigger drain drops a chunk after N failures, but not for an outage. Whether a local-model failure
+// is the chunk's fault is decided here, by what the local endpoint did.
+const TURNS: BufferTurn[] = [
+  { role: "user", content: "I keep my backups on the NAS in the garage.", timestamp: "2026-10-30T01:00:00.000Z" },
+  { role: "assistant", content: "Noted.", timestamp: "2026-10-30T01:00:05.000Z" },
+];
+
+type LocalMessages = Array<{ role: string; content: string }>;
+type LocalStub = (messages: LocalMessages, options: { failureDiag?: { lastError?: Error } }) => Promise<{ content: string } | null>;
+
+async function extractWith(local: LocalStub) {
+  const engine = new ExtractionEngine(parseConfig({ localLlmEnabled: true, localLlmModel: "fixture-local", localLlmFallback: false }));
+  const modelRegistry = { calculateContextSizes: () => ({ maxInputChars: 8_000, maxOutputTokens: 1_000, description: "fixture" }) };
+  assert.equal(Reflect.set(engine, "localLlm", { chatCompletion: local }), true);
+  assert.equal(Reflect.set(engine, "modelRegistry", modelRegistry), true);
+  return await engine.extract(TURNS);
+}
+
+const withStatus = (status: number) => Object.assign(new Error("local LLM http failure"), { status });
+
+test("a local endpoint that answers with something unusable rejects the chunk: parse_empty", async () => {
+  const result = await extractWith(async () => ({ content: "I cannot help with that request." }));
+  assert.equal(result.extractionFailure, "local_llm_error");
+  assert.equal(result.extractionFailureClass, "parse_empty");
+});
+
+test("a local endpoint that answers with a client error rejects the chunk: parse_empty", async () => {
+  for (const status of [400, 413, 422]) {
+    const result = await extractWith(async (_messages, options) => {
+      if (options.failureDiag) options.failureDiag.lastError = withStatus(status);
+      return null;
+    });
+    assert.equal(result.extractionFailureClass, "parse_empty", `HTTP ${status}`);
+  }
+});
+
+test("not the chunk's fault: unreachable, timeout, 5xx, 429, auth and a wrong model or route (404) stay provider_retryable", async () => {
+  const outage = await extractWith(async () => null);
+  assert.equal(outage.extractionFailure, "local_llm_unavailable");
+  assert.equal(outage.extractionFailureClass, "provider_retryable");
+  for (const status of [401, 403, 404, 405, 408, 410, 429, 500, 503]) {
+    const result = await extractWith(async (_messages, options) => {
+      if (options.failureDiag) options.failureDiag.lastError = withStatus(status);
+      return null;
+    });
+    assert.equal(result.extractionFailureClass, "provider_retryable", `HTTP ${status}`);
+  }
+});

package/src/extraction.ts

@@ -38,7 +38,7 @@ import {
 import { applyGroundingWithConnector, headerConnector, renderExtractionConversation, resolveSourceConnector, type ExtractionGroundingContext } from "./source-agent-qualifier.js";
 import { isMemoryCategory } from "./write-envelope.js";
 export { classifyExtractionThrownError, classifyFallbackParseFailure, formatExtractionParseFailureLog } from "./extraction-error-classification.js";
-import { classifyExtractionThrownError, classifyFallbackParseFailure, formatExtractionParseFailureLog } from "./extraction-error-classification.js";
+import { LocalLlmRejectedError, classifyExtractionThrownError, classifyFallbackParseFailure, formatExtractionParseFailureLog, localRejectionStatus, type LocalFailureDiag } from "./extraction-error-classification.js";
 import { AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT, clampAmbientCaptureConfidence } from "./ambient-provenance.js";
 import {
   CONSOLIDATION_RESPONSE_SCHEMA,
@@ -1244,7 +1244,7 @@ export class ExtractionEngine {
             entities: [],
             questions: [],
             extractionFailure: "local_llm_error",
-            extractionFailureClass: "provider_retryable",
+            extractionFailureClass: err instanceof LocalLlmRejectedError ? "parse_empty" : classifyExtractionThrownError(err),
           };
         }
         log.info("extraction: local LLM error, falling back to gateway default AI:", err);
@@ -1494,9 +1494,8 @@ ${extractionResponseShape(this.config.extraction?.spanMode ?? "off")}
 Conversation:
 ${truncatedConversation}`;
 
-    log.debug(
-      `extractWithLocalLlm: calling localLlm.chatCompletion with prompt length ${localPrompt.length}...`,
-    );
+    log.debug(`extractWithLocalLlm: calling localLlm.chatCompletion with prompt length ${localPrompt.length}...`);
+    const failureDiag: LocalFailureDiag = {};
     const response = await this.localLlm.chatCompletion(
       [
         { role: "system", content: "You are a memory extraction system. Output valid JSON only." },
@@ -1512,9 +1511,12 @@ ${truncatedConversation}`;
           : undefined,
         priority: "background",
         signal,
+        failureDiag,
       },
     );
     if (!response?.content) {
+      const rejected = localRejectionStatus(failureDiag);
+      if (rejected !== undefined) throw new LocalLlmRejectedError(rejected); // the endpoint is up and refuses this input
       log.debug("extractWithLocalLlm: chatCompletion returned null or empty content");
       return null;
     }
@@ -1547,12 +1549,10 @@ ${truncatedConversation}`;
     log.debug("extractWithLocalLlm: JSON parse failed, attempting partial extraction...");
     const partial = this.extractPartialFacts(content);
     if (partial.facts.length > 0 || partial.entities.length > 0) {
-      log.debug(
-        `extractWithLocalLlm: extracted ${partial.facts.length} partial facts from truncated JSON`,
-      );
+      log.debug(`extractWithLocalLlm: extracted ${partial.facts.length} partial facts from truncated JSON`);
       return partial;
     }
-    return null;
+    throw new LocalLlmRejectedError(); // the endpoint answered and nothing in the answer is usable
   }
 
   /**

package/src/namespaces/search.ts

@@ -700,7 +700,7 @@ export function normalizeQmdResultPath(resultPath: string, collection: string):
   }
   return value;
 }
-function resolveNamespaceResultPath(
+export function resolveNamespaceResultPath(
   memoryDir: string,
   collection: string,
   resultPath: string,

package/src/orchestration/extraction-run.test.ts

@@ -88,6 +88,7 @@ const migrationSummary: TierMigrationCycleSummary = {
 
 interface Harness {
   config: PluginConfig;
+  buffer: SmartBuffer;
   storageForNs: (ns: string) => Promise<StorageManager>;
   setStorageForDelay: (delayMs: number) => void;
   newCoordinator: () => ExtractionRunCoordinator;
@@ -105,7 +106,7 @@ interface Harness {
     coord: ExtractionRunCoordinator,
     content: string,
     opts?: { force?: boolean; failClosed?: boolean; writeNamespaceOverride?: string },
-  ) => Promise<{ status: string; reason?: string }>;
+  ) => Promise<{ status: string; reason?: string; failureClass?: string; retainedBuffer?: boolean }>;
   cleanup: () => Promise<void>;
   passiveCapture: () => { principal?: string; namespace?: string } | null;
   setThreadingBlock: (blocked: boolean) => void;
@@ -201,6 +202,7 @@ async function makeHarness(overrides: Record<string, unknown> = {}): Promise<Har
 
   return {
     config,
+    buffer,
     storageForNs,
     setStorageForDelay: (delayMs) => {
       storageForDelayMs = delayMs;
@@ -243,7 +245,7 @@ async function makeHarness(overrides: Record<string, unknown> = {}): Promise<Har
         forceExtractionAttempt: opts.force === true,
         writeNamespaceOverride: opts.writeNamespaceOverride,
       });
-      return { status: result.status, reason: result.reason };
+      return { status: result.status, reason: result.reason, failureClass: result.failureClass, retainedBuffer: result.retainedBuffer };
     },
     cleanup: async () => {
       StorageManager.clearAllStaticCaches();
@@ -1336,3 +1338,82 @@ test("#3140: a successful flush heals the recorded LLM health", async () => {
     await h.cleanup();
   }
 });
+
+// ---------------------------------------------------------------------------
+// Wiring the trigger drain depends on (#3266): what a real run hands back, and what it asks of the buffer
+// ---------------------------------------------------------------------------
+
+test("a retained failure carries the extraction's failure class, so the drain can tell an outage from a bad chunk", async () => {
+  for (const cls of ["provider_retryable", "auth_config", "parse_empty"] as const) {
+    const h = await makeHarness({ extractionRetryScheduleMs: [3_600_000], extractionBreakerFailureThreshold: 100 });
+    try {
+      h.setRespond(() => failureResult(cls));
+      const result = await h.run(h.newCoordinator(), `class-${cls}`);
+      assert.equal(result.retainedBuffer, true, `${cls}: the window is kept for a retry`);
+      assert.equal(result.failureClass, cls, `${cls}: the class reaches the run result`);
+    } finally {
+      await h.cleanup();
+    }
+  }
+});
+
+test("a failure with no class defaults to provider_retryable on the run result, like the retry bookkeeping", async () => {
+  const h = await makeHarness({ extractionRetryScheduleMs: [3_600_000], extractionBreakerFailureThreshold: 100 });
+  try {
+    h.setRespond(() => ({ ...failureResult("parse_empty"), extractionFailureClass: undefined }));
+    const result = await h.run(h.newCoordinator(), "class-default");
+    assert.equal(result.failureClass, "provider_retryable");
+  } finally {
+    await h.cleanup();
+  }
+});
+
+test("a run without a failure reports no failure class", async () => {
+  const h = await makeHarness();
+  try {
+    h.setRespond(() => ({ ...successResult(), facts: [] }));
+    const result = await h.run(h.newCoordinator(), "class-none");
+    assert.equal(result.failureClass, undefined);
+  } finally {
+    await h.cleanup();
+  }
+});
+
+test("the retention window a chunk run is given reaches the buffer as the processed snapshot (#3266)", async () => {
+  const h = await makeHarness();
+  try {
+    const seen: Array<readonly BufferTurn[] | undefined> = [];
+    const original = h.buffer.retainDeferredTurns.bind(h.buffer);
+    h.buffer.retainDeferredTurns = async (key, turns, max, processed) => {
+      seen.push(processed);
+      await original(key, turns, max, processed);
+    };
+    const chunk = makeTurns("chunk-turns");
+    const window = [...makeTurns("earlier-turns"), ...chunk];
+    h.setRespond(() => successResult());
+    await h.newCoordinator().runExtraction(chunk, {
+      skipCharThreshold: true,
+      skipUserTurnThreshold: true,
+      clearBufferAfterExtraction: true,
+      bufferKey: "window",
+      failOnExtractionFailure: false,
+      forceExtractionAttempt: false,
+      retentionWindow: window,
+    });
+    assert.equal(seen.length, 1, "the run asked the buffer to update its retention slot once");
+    assert.deepEqual(seen[0], window, "with the window it was given, not just its own chunk");
+
+    seen.length = 0;
+    await h.newCoordinator().runExtraction(chunk, {
+      skipCharThreshold: true,
+      skipUserTurnThreshold: true,
+      clearBufferAfterExtraction: true,
+      bufferKey: "window",
+      failOnExtractionFailure: false,
+      forceExtractionAttempt: false,
+    });
+    assert.deepEqual(seen[0], chunk, "without a window the run keeps naming its own turns");
+  } finally {
+    await h.cleanup();
+  }
+});

package/src/orchestration/qmd-result-resolver.ts

@@ -26,12 +26,13 @@
  * RecallRerankCoordinator / ConversationIndexCoordinator accessor pattern.
  */
 
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { resolveNamespaceCapabilities } from "../capabilities.js";
 import type { StorageManager } from "../index.js";
 import { log } from "../logger.js";
 import { namespaceIdentityFromToken } from "../namespaces/identity.js";
-import { normalizeQmdResultPath } from "../namespaces/search.js";
+import { normalizeQmdResultPath, resolveNamespaceResultPath } from "../namespaces/search.js";
 import { SecureStoreLockedError } from "../secure-store/index.js";
 import { isPathInsideStorageRoot } from "../storage-paths.js";
 import { isSupportPassportPrivateMemory } from "../support-passport/card-projection.js";
@@ -136,6 +137,30 @@ export function qmdResultPathCandidates(storageDir: string, resultPath: string):
   return [...candidates];
 }
 
+/** Canonicalize flat hot-memory identities before merging with native hits (#3194).
+ * This is a path-only map: no candidates, collections or namespace scopes are removed.
+ * Cold/explicit foreign collections keep their existing owner-resolution path.
+ */
+export function normalizeFlatQmdResults(
+  results: QmdSearchResult[],
+  config: PluginConfig,
+  collection = config.qmdCollection,
+): QmdSearchResult[] {
+  if (!collection || resolveNamespaceCapabilities(config).namespaces || collection !== config.qmdCollection) return results;
+  return results.map((result) => ({
+    ...result,
+    path: withHotFactsPath(config.memoryDir, resolveNamespaceResultPath(config.memoryDir, collection, result.path)),
+  }));
+}
+
+/** A hot-facts collection registered at the facts/ subtree returns date-relative paths (#2111); meet the loaded memory's path. */
+function withHotFactsPath(memoryDir: string, resolved: string): string {
+  const relative = path.relative(path.resolve(memoryDir), resolved).split(path.sep).join("/");
+  if (!/^\d{4}-\d{2}-\d{2}\//.test(relative) || existsSync(resolved)) return resolved;
+  const hot = path.join(path.resolve(memoryDir), "facts", relative);
+  return existsSync(hot) ? hot : resolved;
+}
+
 /**
  * Extract a non-empty `dir` from a storage, returning `null` when the
  * property is absent or not a non-empty string at runtime. Proxy-backed