@remnic/core 9.30.1 → 9.31.0

package/src/access-service-observe-scope.test.ts

@@ -33,6 +33,8 @@ import { join } from "node:path";
 import test from "node:test";
 
 import { EngramAccessService } from "./access-service.js";
+import { PendingObserveExtractionTracker } from "./access-observe-helpers.js";
+
 import { tokenCapabilityStore } from "./access-token-capabilities.js";
 import { resolveAuthorizedNamespaceWritablePreflight } from "./access-namespace-preflight.js";
 import { Orchestrator } from "./orchestrator.js";
@@ -216,6 +218,92 @@ test("#1495 projectTag: LCM, extraction, objective-state, and response all agree
   );
 });
 
+test("#2128 pending observe preparation is a force-flush barrier", async () => {
+  const tracker = new PendingObserveExtractionTracker();
+  const preparation = tracker.reserve("session-z");
+  let releaseExtraction!: () => void;
+  const extraction = new Promise<void>((resolve) => {
+    releaseExtraction = resolve;
+  });
+  let waited = false;
+  const waitPromise = tracker.wait("session-z", "alice", "team-project").then(() => {
+    waited = true;
+  });
+
+  await Promise.resolve();
+  assert.equal(waited, false, "a force flush must wait while observe is still resolving scope");
+
+  tracker.track(tracker.key("session-z", "alice", "team-project"), extraction, new AbortController());
+  preparation.release();
+  await Promise.resolve();
+  assert.equal(waited, false, "registration must remain a barrier until extraction settles");
+
+  releaseExtraction();
+  await waitPromise;
+  assert.equal(waited, true);
+});
+
+test("#2128 scoped observe preparation cancellation preserves another project", () => {
+  const tracker = new PendingObserveExtractionTracker();
+  const projectA = tracker.reserve("opaque-session", "projectTag:project-a");
+  const projectB = tracker.reserve("opaque-session", "projectTag:project-b");
+
+  tracker.cancel("opaque-session", undefined, "alice-project-a", "projectTag:project-a");
+
+  assert.equal(projectA.isCancelled(), true);
+  assert.equal(projectB.isCancelled(), false);
+  projectA.release();
+  projectB.release();
+});
+
+
+test("#2128 cancellation matches resolved scope despite a different request hint", () => {
+  const tracker = new PendingObserveExtractionTracker();
+  const preparation = tracker.reserve("session-z", "cwd:/workspace/project/src");
+  preparation.setScope("alice", "alice-project");
+
+  tracker.cancel("session-z", "alice", "alice-project", "projectTag:Acme/Webshop");
+
+  assert.equal(preparation.isCancelled(), true);
+  preparation.release();
+});
+test("#2128 concurrent scope plans do not share temporary coding context", async () => {
+  const probe = makeObserveProbe(withSelfPolicyPrefix("pi-geek"));
+  const service = new EngramAccessService(probe.orch);
+  const internals = service as unknown as {
+    resolveMemoryScopePlan: (request: EngramAccessObserveRequest) => Promise<{
+      writeNamespace: string;
+    }>;
+  };
+
+  const firstProject = projectTagProjectId("Acme/Webshop");
+  const secondProject = projectTagProjectId("Contoso/Portal");
+  const [firstPlan, secondPlan] = await Promise.all([
+    internals.resolveMemoryScopePlan.call(
+      service,
+      observeRequest({ sessionKey: "pi-geek:concurrent", projectTag: "Acme/Webshop" }),
+    ),
+    internals.resolveMemoryScopePlan.call(
+      service,
+      observeRequest({ sessionKey: "pi-geek:concurrent", projectTag: "Contoso/Portal" }),
+    ),
+  ]);
+
+  assert.equal(
+    firstPlan.writeNamespace,
+    combineNamespaces("pi-geek", projectNamespaceName(firstProject)),
+  );
+  assert.equal(
+    secondPlan.writeNamespace,
+    combineNamespaces("pi-geek", projectNamespaceName(secondProject)),
+  );
+  assert.equal(
+    probe.contexts.get("pi-geek:concurrent"),
+    undefined,
+    "scope planning must not bind temporary coding context visible to concurrent calls",
+  );
+});
+
 test("#1501 scope profile exposes layered read/write/promotion diagnostics without changing user-project write default", async () => {
   const probe = makeObserveProbe({
     namespacePolicies: [

package/src/access-service.ts

@@ -222,6 +222,20 @@ import type {
   RecallDisclosure,
   RecallPlanMode,
 } from "./types.js";
+import {
+  delegateExtractionForceFlush,
+  type EngramAccessExtractionForceFlushRequest,
+  type EngramAccessExtractionForceFlushResponse,
+  type EngramAccessLcmCompactionFlushRequest,
+  type EngramAccessLcmCompactionFlushResponse,
+} from "./access-service-helpers.js";
+export type {
+  EngramAccessExtractionForceFlushRequest,
+  EngramAccessExtractionForceFlushResponse,
+  EngramAccessLcmCompactionFlushRequest,
+  EngramAccessLcmCompactionFlushResponse,
+};
+
 import { DEFAULT_RECALL_DISCLOSURE, isRecallDisclosure } from "./types.js";
 import { estimateRecallTokens, type RecallXraySnapshot } from "./recall-xray.js";
 import type {
@@ -943,6 +957,8 @@ export interface MemoryScopePlan {
   readNamespaces: string[];
   /** Active scope profile id, when `defaultScopeProfile` is configured. */
   scopeProfile?: string;
+  /** Internal resolved profile used to keep scoped extraction persistence aligned with access resolution. */
+  scopeProfilePlan?: ResolvedScopeProfilePlan | null;
   /** Resolved profile layer that supplied `writeNamespace`. */
   writeLayer?: string;
   /** Resolved profile layers in the active profile contract. */
@@ -1082,19 +1098,6 @@ export interface EngramAccessLcmStatusResponse {
   stats?: { totalTurns?: number };
 }
 
-export interface EngramAccessLcmCompactionFlushRequest {
-  sessionKey: string;
-  namespace?: string;
-  authenticatedPrincipal?: string;
-}
-
-export interface EngramAccessLcmCompactionFlushResponse {
-  enabled: boolean;
-  flushed: boolean;
-  sessionKey: string;
-  namespace: string;
-  reason?: string;
-}
 
 export interface EngramAccessLcmCompactionRecordRequest {
   sessionKey: string;
@@ -1732,98 +1735,27 @@ export class EngramAccessService {
       this.orchestrator.config,
     );
 
-    // Resolve the coding overlay through the SAME orchestrator method recall and
-    // the buffer-flush write path use (`applyCodingNamespaceOverlay`), NOT a
-    // private re-implementation. Routing through the one shared method (rule 22 /
-    // 42) means a project-scoped observe writes to byte-for-byte the namespace a
-    // same-session recall reads — and that the read/write overlay logic cannot
-    // drift (the #1495 drift this PR exists to close). The orchestrator method
-    // already gates on `namespacesEnabled` + a bound/derivable coding context, so
-    // it returns the base unchanged when no overlay applies.
-    //
-    // `applyCodingNamespaceOverlay` reads the session's ATTACHED context. The
-    // scope plan runs BEFORE `maybeAttachCodingContext` (resolve-before-mutate),
-    // so when nothing is attached yet we seed the per-call cwd/projectTag context
-    // first — identical to what attach would bind — so the overlay is the same
-    // either way (Codex review precedence: session context first, per-call
-    // fallback).
-    const hasSession =
-      typeof request.sessionKey === "string" && request.sessionKey.length > 0;
-    const overlayEligible =
-      hasSession &&
-      resolveNamespaceCapabilities(this.orchestrator.config).namespaces === true &&
-      this.orchestrator.config.codingMode?.projectScope === true;
-
-    // Resolve the coding context the overlay must use: the session's ATTACHED
-    // context first (so a bound session wins), else the per-call cwd/projectTag —
-    // identical precedence to recall and to `resolveCodingScopedWriteNamespace`.
-    let attachedContext = hasSession
-      ? this.orchestrator.getCodingContextForSession(request.sessionKey)
-      : null;
-    // Track whether WE seeded the per-call context so we can leave the session
-    // exactly as we found it on any rejection (read-only contract / no-orphan
-    // guard, observe-scope "unauthorized overlay self-base" test).
-    let seededContext = false;
-    if (overlayEligible && !attachedContext) {
-      attachedContext = await this.resolveCodingContextFromOptions(request);
-      if (attachedContext) {
-        // Seed the per-call context so the shared
-        // `applyCodingNamespaceOverlay` (which reads ATTACHED session context)
-        // overlays it through the ONE method recall/buffer-flush use (rule 22 /
-        // 42) — no private re-implementation that could drift. On the happy
-        // path `maybeAttachCodingContext` re-binds the identical context after
-        // auth passes; on a rejection we clear the seed below, so the session is
-        // untouched either way.
-        this.orchestrator.setCodingContextForSession(
-          request.sessionKey!,
-          attachedContext,
-        );
-        seededContext = true;
-      }
-    }
-
-    // Clear a seed we added, used only on the rejection paths so a failed
-    // observe never leaves an orphaned project binding (read-only contract).
-    const clearSeededContext = (): void => {
-      if (seededContext && hasSession) {
-        this.orchestrator.setCodingContextForSession(request.sessionKey!, null);
-      }
-    };
+    // Resolve the coding context and overlay through the shared read-only
+    // resolver used by the other scoped access paths. It applies the same
+    // session-first, per-call fallback precedence without mutating session
+    // state, so concurrent requests cannot observe temporary context.
+    const {
+      overlay: codingOverlay,
+      profilePlan,
+    } = await this.resolveCodingScopeInputs(request);
+    const overlaidBase = codingOverlay
+      ? combineNamespaces(baseNamespace, codingOverlay.namespace)
+      : baseNamespace;
+    const codingOverlayApplied = overlaidBase !== baseNamespace;
     const assertWriteNamespaceAllowed = (namespace: string): void => {
-      try {
-        this.assertTokenCanWriteNamespace(namespace);
-      } catch (error) {
-        clearSeededContext();
-        throw error;
-      }
+      this.assertTokenCanWriteNamespace(namespace);
     };
-
-
-    const overlaidBase = this.orchestrator.applyCodingNamespaceOverlay(
-      request.sessionKey,
-      baseNamespace,
-    );
-    const codingOverlayApplied = overlaidBase !== baseNamespace;
-    const codingOverlay = overlayEligible
-      ? resolveCodingNamespaceOverlay(
-          attachedContext,
-          this.orchestrator.config.codingMode,
-          this.orchestrator.config.defaultNamespace,
-        )
-      : null;
-    const profilePlan = resolveScopeProfilePlan({
-      config: this.orchestrator.config,
-      principal,
-      codingContext: attachedContext,
-      codingOverlay,
-    });
     if (profilePlan) {
       const selectedLayer = profilePlan.layers.find((layer) => layer.id === profilePlan.writeLayer);
       const writeNamespaceReadable =
         profilePlan.writeNamespace.length > 0 &&
         profilePlan.readNamespaces.includes(profilePlan.writeNamespace);
       if (!selectedLayer?.writable || !writeNamespaceReadable) {
-        clearSeededContext();
         throw new NamespaceNotWritableError(profilePlan.writeNamespace, principal,
           `scope profile ${profilePlan.profileId} has no writable layer for principal ${principal ?? "anonymous"}`);
       }
@@ -1857,6 +1789,7 @@ export class EngramAccessService {
         objectiveStateNamespace: profilePlan.writeNamespace,
         readNamespaces,
         scopeProfile: profilePlan.profileId,
+        scopeProfilePlan: profilePlan,
         writeLayer: profilePlan.writeLayer,
         layers: profilePlan.layers,
         promotionTargets: profilePlan.promotionTargets,
@@ -1899,7 +1832,6 @@ export class EngramAccessService {
         resolveNamespaceCapabilities(this.orchestrator.config).namespaces === true &&
         !canWriteNamespace(principal, baseNamespace, this.orchestrator.config)
       ) {
-        clearSeededContext();
         throw new NamespaceNotWritableError(baseNamespace, principal);
       }
       assertWriteNamespaceAllowed(writeNamespace);
@@ -1927,15 +1859,13 @@ export class EngramAccessService {
     // (the overlay is a principal-owned `project-*` sub-namespace derived from
     // it, so it needs no separate write policy — rule 42 / 47 / 48).
     if (!canWriteNamespace(principal, baseNamespace, this.orchestrator.config)) {
-      clearSeededContext();
       throw new NamespaceNotWritableError(baseNamespace, principal);
     }
     const writeNamespace = overlaidBase;
     const readNamespaces = [writeNamespace];
     // Include read fallbacks (branch→project→root) so the diagnostic readNamespaces
-    // matches what a same-session recall searches. Resolved through the pure
-    // overlay helper to enumerate fallbacks; the write namespace itself already
-    // came from `applyCodingNamespaceOverlay` so the two agree.
+    // matches what a same-session recall searches. They come from the shared pure
+    // coding-scope resolver, so the write namespace and read fallbacks agree.
     for (const fallback of codingOverlay?.readFallbacks ?? []) {
       const ns = combineNamespaces(baseNamespace, fallback);
       if (!readNamespaces.includes(ns)) readNamespaces.push(ns);
@@ -4333,26 +4263,9 @@ export class EngramAccessService {
       throw new EngramAccessInputError("sessionKey is required and must be a non-empty string");
     }
 
-    // Authorize compaction against the SCOPED WRITE TARGET — the SAME effective
-    // write namespace `observe` archived the LCM queue under — NOT a premature
-    // the writable-namespace resolver (undefined ⇒ config.defaultNamespace) (#1505
-    // thread NBHWs). Under a restrictive `default` WRITE policy where the
-    // principal can still write its self/project overlay, that premature default
-    // write-auth threw `namespace is not writable: default` BEFORE the scoped key
-    // was computed, so the overlay queue `observe` just wrote could never be
-    // flushed. `resolveMemoryScopePlan` is the ONE write-scoped plan/gate observe
-    // uses (rule 22 / 39 / 42): it authorizes the principal self base for an
-    // overlay write and only collapses to `config.defaultNamespace` (always
-    // writable) when no overlay applies — so it never throws `not writable:
-    // default` for a validly scoped observe's queue.
+    // Authorize compaction against the same effective write namespace that
+    // observe archived under, not a premature default writable-namespace check.
     const scope = await this.resolveMemoryScopePlan(request);
-    // Legacy `namespace` response field: pre-#1505 semantics were exactly
-    // the writable-namespace resolver (overlay-agnostic) — the
-    // authorized explicit namespace when supplied, else `config.defaultNamespace`.
-    // DERIVED from the scope plan (NOT a second auth pass, #1505 thread jvO):
-    // explicit ⇒ writeNamespace; user-project coding overlay ⇒ defaultNamespace;
-    // non-user scope-profile layer/no overlay ⇒ writeNamespace. Identical to
-    // observe's legacy field.
     const namespace = this.legacyResponseNamespaceForScope(scope);
     if (!this.orchestrator.lcmEngine || !this.orchestrator.lcmEngine.enabled) {
       return {
@@ -4364,13 +4277,7 @@ export class EngramAccessService {
       };
     }
 
-    // Flush the SAME LCM session_id `observe` archived under: encode the scope
-    // plan's EFFECTIVE write namespace (the coding overlay when one applies, else
-    // the default store) through the SAME `lcmSessionKeyForNamespace` helper
-    // observe uses for archival, so the flush key is byte-for-byte the write key
-    // (#1495 thread 2 / #1505 thread NBHWs, rule 42). A write-only / self-omitted
-    // principal still flushes the overlay queue because the scope plan authorized
-    // the write target by WRITE policy, not readability.
+    // Flush the same LCM session ID observe archived under.
     const lcmSessionKey =
       lcmSessionKeyForNamespace(
         scope.writeNamespace,
@@ -4387,6 +4294,17 @@ export class EngramAccessService {
     };
   }
 
+  async extractionForceFlush(request: EngramAccessExtractionForceFlushRequest): Promise<EngramAccessExtractionForceFlushResponse> {
+    return delegateExtractionForceFlush(this.accessObserveWriteSurface, request);
+  }
+  cancelPendingObserveExtractions(
+    sessionKey: string,
+    principal?: string,
+    namespace?: string,
+    scopeHint?: string,
+  ): void {
+    this.accessObserveWriteSurface.cancelPendingObserveExtractions(sessionKey, principal, namespace, scopeHint);
+  }
   async lcmCompactionRecord(
     request: EngramAccessLcmCompactionRecordRequest,
   ): Promise<EngramAccessLcmCompactionRecordResponse> {

package/src/access-surface-catalog.test.ts

@@ -282,6 +282,26 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
     }
   }
 
+  if (/\bawait\s+maybeHandleLifecycleFlush\(/.test(source)) {
+    const lifecycleSource = readFileSync(
+      new URL("./access-http-lifecycle-flush.ts", import.meta.url),
+      "utf-8",
+    );
+    const lifecycleRoutes = [
+      ["/engram/v1/lcm/compaction/flush", "lcm_compaction_flush"],
+      ["/engram/v1/extraction/flush", "extraction_force_flush"],
+      ["/engram/v1/lcm/compaction/record", "lcm_compaction_record"],
+    ] as const;
+    for (const [pathname, operation] of lifecycleRoutes) {
+      const escapedPathname = pathname.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const routeBlock = lifecycleSource.match(
+        new RegExp(`pathname\\s*===\\s*"${escapedPathname}"[\\s\\S]*?return true;`),
+      )?.[0];
+      if (routeBlock?.includes(`deps.enforceTokenOp("${operation}")`)) {
+        routeOps.set(`POST ${pathname}`, new Set([operation]));
+      }
+    }
+  }
   return routeOps;
 }
 
@@ -468,6 +488,18 @@ test("dispatch validator catches cross-method contamination on a shared path", (
   );
 });
 
+test("dispatch validator follows lifecycle helper-owned HTTP routes", () => {
+  const routeDispatch = extractHttpRouteDispatchMap();
+  assert.equal(
+    routeDispatch.get("POST /engram/v1/lcm/compaction/flush")?.has("lcm_compaction_flush"),
+    true,
+  );
+  assert.equal(
+    routeDispatch.get("POST /engram/v1/extraction/flush")?.has("extraction_force_flush"),
+    true,
+  );
+});
+
 // ---------------------------------------------------------------------------
 // Real surface coverage — the gate that runs on every build
 // ---------------------------------------------------------------------------

package/src/access-surface-catalog.ts

@@ -106,6 +106,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "observe", operation: "observe" },
   { tool: "lcm_search", operation: "lcm_search" },
   { tool: "lcm_compaction_flush", operation: "lcm_compaction_flush" },
+  { tool: "extraction_force_flush", operation: "extraction_force_flush" },
   { tool: "lcm_compaction_record", operation: "lcm_compaction_record" },
   { tool: "continuity_audit_generate", operation: "continuity_audit_generate" },
   { tool: "continuity_incident_open", operation: "continuity_incident_open" },
@@ -199,6 +200,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/observe", operation: "observe" },
   { method: "POST", pathname: "/engram/v1/lcm/search", operation: "lcm_search" },
   { method: "POST", pathname: "/engram/v1/lcm/compaction/flush", operation: "lcm_compaction_flush" },
+  { method: "POST", pathname: "/engram/v1/extraction/flush", operation: "extraction_force_flush" },
   { method: "POST", pathname: "/engram/v1/lcm/compaction/record", operation: "lcm_compaction_record" },
   { method: "GET", pathname: "/engram/v1/lcm/status", operation: "lcm_status" },
   { method: "GET", pathname: "/engram/v1/relay/missions/:id", operation: "relay_mission_read" },

package/src/buffer-session.test.ts

@@ -216,6 +216,59 @@ test("SmartBuffer clearAfterExtraction preserves appends after queued snapshots"
   );
 });
 
+test("SmartBuffer shared-buffer clear removes only the extracted session turns", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const aliceTurn = makeTurn("alice", "alice memory");
+  const bobTurn = makeTurn("bob", "bob memory");
+
+  await buffer.addTurn("provider-thread", aliceTurn);
+  await buffer.addTurn("provider-thread", bobTurn);
+  await buffer.clearAfterExtraction("provider-thread", [aliceTurn], {
+    allowNonPrefix: true,
+  });
+
+  assert.deepEqual(buffer.getTurns("provider-thread"), [bobTurn]);
+});
+
+test("SmartBuffer shared-buffer clear distinguishes duplicate turns by owner", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const aliceTurn = { ...makeTurn("opaque-session", "same memory"), sessionOwnerPrincipal: "alice" };
+  const bobTurn = { ...makeTurn("opaque-session", "same memory"), sessionOwnerPrincipal: "bob" };
+
+  await buffer.addTurn("provider-thread", aliceTurn);
+  await buffer.addTurn("provider-thread", bobTurn);
+  await buffer.clearAfterExtraction("provider-thread", [aliceTurn], {
+    allowNonPrefix: true,
+  });
+
+  assert.deepEqual(buffer.getTurns("provider-thread"), [bobTurn]);
+});
+
+test("SmartBuffer preserves owner identity in deferred turns", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const aliceTurn = { ...makeTurn("opaque-session", "deferred memory"), sessionOwnerPrincipal: "alice" };
+
+  await buffer.retainDeferredTurns("provider-thread", [aliceTurn]);
+
+  assert.deepEqual(buffer.getRetainedDeferredTurns("provider-thread"), [aliceTurn]);
+});
+
+
 test("SmartBuffer clearAfterExtraction chooses the longest queued snapshot overlap", async () => {
   const storage = new FakeStorage({
     turns: [],
@@ -414,6 +467,101 @@ test("retainDeferredTurns preserves turns across clearAfterExtraction", async ()
   assert.equal(afterClear[1]?.content, "deferred context two");
 });
 
+test("clearRetainedTurnsForSession drains only the force-flushed session", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const sessionTurn = makeTurn("session-a", "deferred context");
+  const otherTurn = makeTurn("session-b", "other deferred context");
+
+  await buffer.addTurn("provider-thread", sessionTurn);
+  await buffer.retainDeferredTurns("provider-thread", [sessionTurn]);
+  await buffer.addTurn("other-thread", otherTurn);
+  await buffer.retainDeferredTurns("other-thread", [otherTurn]);
+
+  await buffer.clearRetainedTurnsForSession("session-a");
+
+  assert.deepEqual(buffer.getRetainedDeferredTurns("provider-thread"), []);
+  assert.deepEqual(buffer.getRetainedDeferredTurns("other-thread"), [otherTurn]);
+  assert.deepEqual(
+    storage.saved?.entries?.["provider-thread"]?.retainedTurns,
+    undefined,
+  );
+});
+
+test("clearRetainedTurnsForSession flushes another session's pending save when target is absent", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(
+    parseConfig({ bufferSaveDebounceMs: 10_000, triggerMode: "smart", bufferMaxTurns: 10_000 }),
+    storage as any,
+  );
+  const otherTurn = makeTurn("session-a", "pending turn from another session");
+  await buffer.addTurn("session-a", otherTurn);
+
+  const internals = buffer as unknown as DebouncedBufferInternals;
+  assert.equal(storage.saveCount, 0);
+  assert.equal(internals.pendingSave, true);
+  assert.notEqual(internals.saveTimer, null);
+
+  await buffer.clearRetainedTurnsForSession("session-b");
+
+  assert.equal(storage.saveCount, 1);
+  assert.equal(storage.saved?.entries?.["session-a"]?.turns.length, 1);
+  assert.equal(internals.pendingSave, false);
+  assert.equal(internals.saveTimer, null);
+});
+
+test("clearRetainedTurnsForSession drains only the authenticated owner", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const aliceTurn = { ...makeTurn("opaque-session", "alice deferred"), sessionOwnerPrincipal: "alice" };
+  const bobTurn = { ...makeTurn("opaque-session", "bob deferred"), sessionOwnerPrincipal: "bob" };
+
+  await buffer.addTurn("provider-thread", aliceTurn);
+  await buffer.addTurn("provider-thread", bobTurn);
+  await buffer.retainDeferredTurns("provider-thread", [aliceTurn, bobTurn]);
+
+  await buffer.clearRetainedTurnsForSession("opaque-session", "alice");
+
+  assert.deepEqual(buffer.getRetainedDeferredTurns("provider-thread"), [bobTurn]);
+});
+test("clearRetainedTurnsForSession discovers buffer keys inside the mutation", async () => {
+  const storage = new FakeStorage({
+    turns: [],
+    lastExtractionAt: null,
+    extractionCount: 0,
+  });
+  const buffer = new SmartBuffer(parseConfig({}), storage as any);
+  const firstTurn = makeTurn("session-a", "first deferred context");
+  const lateTurn = makeTurn("session-a", "late deferred context");
+
+  await buffer.addTurn("provider-thread", firstTurn);
+  await buffer.retainDeferredTurns("provider-thread", [firstTurn]);
+  const originalFindBufferKeys = buffer.findBufferKeysForSession.bind(buffer);
+  (buffer as any).findBufferKeysForSession = async (sessionKey: string) => {
+    const keys = await originalFindBufferKeys(sessionKey);
+    await buffer.addTurn("late-provider-thread", lateTurn);
+    await buffer.retainDeferredTurns("late-provider-thread", [lateTurn]);
+    return keys;
+  };
+
+  await buffer.clearRetainedTurnsForSession("session-a");
+
+  assert.deepEqual(buffer.getRetainedDeferredTurns("provider-thread"), []);
+  assert.deepEqual(buffer.getRetainedDeferredTurns("late-provider-thread"), []);
+});
+
 test("retainDeferredTurns respects the max tail size", async () => {
   const storage = new FakeStorage({
     turns: [],