@remnic/core 10.0.85 → 10.0.87

package/src/buffer-types.ts

@@ -1,6 +1,33 @@
 /** Types split out of buffer.ts (structural ratchet, issue #1995). */
 
-import type { BufferTurn } from "./types.js";
+import type { BufferTurn, CodingContext, SignalLevel } from "./types.js";
+import type { ResolvedScopeProfilePlan } from "./namespaces/scope-profiles.js";
+
+export type TriggerDecision = "extract_now" | "extract_batch" | "keep_buffering";
+
+export interface AddTurnOutcome {
+  decision: TriggerDecision;
+  extractionTurns?: BufferTurn[];
+}
+
+export interface AddTurnMutationResult {
+  decision: TriggerDecision;
+  signalLevel: SignalLevel;
+  priorTurns: BufferTurn[];
+  activeTurnsSnapshot: BufferTurn[];
+  retainedTurnsSnapshot: BufferTurn[];
+  turnCountInWindow: number;
+}
+
+export interface RetainedTurnCleanupOptions {
+  abortSignal?: AbortSignal;
+  deadlineMs?: number;
+  /** Keep cleanup within the accepted namespace. */
+  writeNamespaceOverride?: string;
+  /** Match the original profile and project binding, not just its write namespace. */
+  scopeProfileWritePlan?: ResolvedScopeProfilePlan | null;
+  codingContext?: CodingContext;
+}
 
 /**
  * Optional surprise probe injected into `SmartBuffer`.

package/src/buffer.ts

@@ -23,39 +23,32 @@ import {
   bufferTurnsEqual,
   copyBufferTurn,
   describeError,
+  entryActivityAt,
+  entryHoldsAcceptedCapture,
   hasPinnedCaptureScope,
   liveTurnsFromExtractionSnapshot,
   matchingQueuedExtractionPrefixLength,
+  normalizeBufferState,
   probeWithTimeout,
   selectRetainedDeferredTurns,
   type BufferEntryCounts,
 } from "./buffer-turn-helpers.js";
+import { BufferAdmissionRefusedError, canAdmitNewEntryUnlocked } from "./buffer-admission.js";
+export { BufferAdmissionRefusedError } from "./buffer-admission.js";
+import type { AddTurnMutationResult, AddTurnOutcome, RetainedTurnCleanupOptions, TriggerDecision } from "./buffer-types.js";
 
-export type TriggerDecision = "extract_now" | "extract_batch" | "keep_buffering";
+export type { TriggerDecision, AddTurnOutcome, RetainedTurnCleanupOptions } from "./buffer-types.js";
+
+// Eviction hooks are pure functions of an entry; one shared instance serves
+// pruneEntries, the admission probe and the batch preflight.
+const EVICTION_HOOKS = { activityAt: entryActivityAt, holdsAcceptedCapture: entryHoldsAcceptedCapture };
 
 export type { BufferSurpriseProbe } from "./buffer-types.js";
 import type { BufferSurpriseProbe, SurpriseTelemetryQueueEntry } from "./buffer-types.js";
 
-export interface AddTurnOutcome {
-  decision: TriggerDecision;
-  extractionTurns?: BufferTurn[];
-}
-
-export interface RetainedTurnCleanupOptions {
-  abortSignal?: AbortSignal;
-  deadlineMs?: number;
-  /** Keep cleanup within the accepted namespace. */
-  writeNamespaceOverride?: string;
-  /** Match the original profile and project binding, not just its write namespace. */
-  scopeProfileWritePlan?: import("./namespaces/scope-profiles.js").ResolvedScopeProfilePlan | null;
-  codingContext?: import("./types.js").CodingContext;
-}
-
 // Raised from 200 in #3303: live captures were being dropped at busy hours
 // while the single extraction worker drained a backlog.
 const FALLBACK_MAX_BUFFER_SESSIONS = 1000;
-const isAcceptedTurn = (t: { acceptedCapture?: boolean; writeNamespaceOverride?: string }): boolean =>
-  t.acceptedCapture === true || t.writeNamespaceOverride !== undefined;
 
 /**
  * Upper bound on how long a debounced buffer save may be deferred under
@@ -76,15 +69,6 @@ const BUFFER_SAVE_MAX_DEFER_MULTIPLIER = 5;
  */
 const MAX_SET_TIMEOUT_MS = 2_147_483_647;
 
-interface AddTurnMutationResult {
-  decision: TriggerDecision;
-  signalLevel: SignalLevel;
-  priorTurns: BufferTurn[];
-  activeTurnsSnapshot: BufferTurn[];
-  retainedTurnsSnapshot: BufferTurn[];
-  turnCountInWindow: number;
-}
-
 export class SmartBuffer {
   private state: BufferState;
   private loaded = false;
@@ -182,61 +166,13 @@ export class SmartBuffer {
     };
   }
 
-  private normalizeState(state: BufferState): BufferState {
-    const entries = Object.assign(
-      Object.create(null),
-      state.entries ?? {},
-    ) as NonNullable<BufferState["entries"]>;
-    if (!entries.default) {
-      entries.default = {
-        turns: Array.isArray(state.turns) ? [...state.turns] : [],
-        lastExtractionAt: state.lastExtractionAt ?? null,
-        extractionCount:
-          typeof state.extractionCount === "number" ? state.extractionCount : 0,
-      };
-    }
-    return {
-      turns: entries.default.turns,
-      lastExtractionAt: entries.default.lastExtractionAt,
-      extractionCount: entries.default.extractionCount,
-      entries,
-    };
-  }
-
-  private entryActivityAt(entry: BufferEntryState): number {
-    const lastTurnAt = entry.turns.reduce((latest, turn) => {
-      const parsed = Date.parse(turn.timestamp);
-      return Number.isFinite(parsed) ? Math.max(latest, parsed) : latest;
-    }, -1);
-    const lastExtractionAt =
-      typeof entry.lastExtractionAt === "string"
-        ? Date.parse(entry.lastExtractionAt)
-        : Number.NaN;
-    return Math.max(
-      lastTurnAt,
-      Number.isFinite(lastExtractionAt) ? lastExtractionAt : -1,
-    );
-  }
-
   /** Evict oldest entries past this.maxSessionEntries and queue their session files for deletion. */
   private pruneEntries(retainKeys: string[], maxCount = this.maxSessionEntries): void {
     const entries = this.state.entries;
     if (!entries) return;
-    const evicted = selectEvictedBufferKeys(entries, retainKeys, maxCount, {
-      activityAt: (entry) => this.entryActivityAt(entry),
-      holdsAcceptedCapture: (entry) => this.entryHoldsAcceptedCapture(entry),
-    });
+    const evicted = selectEvictedBufferKeys(entries, retainKeys, maxCount, EVICTION_HOOKS);
     for (const key of evicted) delete entries[key];
     this.persistence.markEvicted(evicted);
-    if (evicted.length > 0) {
-      // Loud degradation (extraction hot-loop hardening, Step 7): buffer
-      // pressure during a provider outage is bounded and expected, but must
-      // be observable, not silent.
-      log.warn(
-        `buffer: pruned ${evicted.length} oldest session entr${evicted.length === 1 ? "y" : "ies"} ` +
-          `past the session-entry cap (${this.maxSessionEntries}); buffered turn data for those sessions was dropped`,
-      );
-    }
   }
 
   private async loadUnlocked(): Promise<void> {
@@ -244,7 +180,7 @@ export class SmartBuffer {
     if (!this.loadPromise) {
       this.loadPromise = this.storage.loadBuffer()
         .then((state) => {
-          this.state = this.normalizeState(state);
+          this.state = normalizeBufferState(state);
           this.loaded = true;
         })
         .finally(() => {
@@ -517,24 +453,80 @@ export class SmartBuffer {
     if (mutation === null) return null;
     return this.completeAddTurnOutcome(bufferKey, turn, mutation);
   }
+  /**
+   * Admit a multi-session durable capture as one capacity transaction.
+   * Preflight every new key under the mutation lock before persisting any
+   * turn; refusal records nothing and drops nothing.
+   */
+  async addTurnsBounded(
+    batches: readonly { bufferKey: string; turns: readonly BufferTurn[] }[],
+  ): Promise<Array<{ bufferKey: string; turn: BufferTurn; outcome: AddTurnOutcome }> | null> {
+    const pending = await this.enqueueMutation(async () => {
+      await this.loadUnlocked();
+      const additions: Array<{ bufferKey: string; turn: BufferTurn }> = [];
+      for (const batch of batches) {
+        for (const turn of batch.turns) {
+          additions.push({ bufferKey: batch.bufferKey, turn });
+        }
+      }
+
+      const entries = this.state.entries ?? {};
+      const newKeys = [...new Set(
+        additions
+          .map(({ bufferKey }) => bufferKey)
+          .filter((bufferKey) => this.peekEntry(bufferKey) === null),
+      )];
+      const count = Object.keys(entries).length;
+      const requiredEvictions = Math.max(0, count + newKeys.length - this.maxSessionEntries);
+      if (requiredEvictions > 0) {
+        const target = Math.max(0, this.maxSessionEntries - newKeys.length);
+        const evicted = selectEvictedBufferKeys(entries, newKeys, target, EVICTION_HOOKS);
+        if (newKeys.length > 0 && evicted.length < requiredEvictions) return null;
+        for (const key of evicted) delete entries[key];
+        this.persistence.markEvicted(evicted);
+      }
+
+      const recorded: Array<{ bufferKey: string; turn: BufferTurn; mutation: AddTurnMutationResult }> = [];
+      for (const { bufferKey, turn } of additions) {
+        recorded.push({ bufferKey, turn, mutation: await this.recordTurnUnlocked(bufferKey, turn) });
+      }
+      return recorded;
+    });
+    if (pending === null) return null;
+
+    const outcomes: Array<{ bufferKey: string; turn: BufferTurn; outcome: AddTurnOutcome }> = [];
+    for (const item of pending) {
+      outcomes.push({
+        bufferKey: item.bufferKey,
+        turn: item.turn,
+        outcome: await this.completeAddTurnOutcome(item.bufferKey, item.turn, item.mutation),
+      });
+    }
+    return outcomes;
+  }
 
-  /** Free one slot for an accepted capture via the native eviction policy (COS-244c). */
+  /** Free one slot only when an empty entry can be reclaimed. */
   private makeRoomForEntryUnlocked(): void {
     const entries = this.state.entries ?? {};
     const target = Math.max(0, this.maxSessionEntries - 1);
-    const pinned = Object.keys(entries).filter((k) => k === "default" || this.entryHoldsAcceptedCapture(entries[k]));
-    if (pinned.length <= target) this.pruneEntries([], target); // evict only if it frees a slot
-  }
-
-  private entryHoldsAcceptedCapture(entry: BufferEntryState | undefined): boolean {
-    return (entry?.turns ?? []).some(isAcceptedTurn) || (entry?.retainedTurns ?? []).some(isAcceptedTurn);
+    const pinned = Object.keys(entries).filter((k) => k === "default" || entryHoldsAcceptedCapture(entries[k]));
+    if (pinned.length <= target) this.pruneEntries([], target);
   }
 
   async addTurnWithOutcome(
     bufferKey: string,
     turn: BufferTurn,
   ): Promise<AddTurnOutcome> {
-    const mutation = await this.enqueueMutation(() => this.recordTurnUnlocked(bufferKey, turn));
+    const mutation = await this.enqueueMutation(async () => {
+      await this.loadUnlocked();
+      if (
+        this.peekEntry(bufferKey) === null &&
+        !canAdmitNewEntryUnlocked(this.state.entries ?? {}, bufferKey, this.maxSessionEntries, EVICTION_HOOKS)
+      ) {
+        throw new BufferAdmissionRefusedError(bufferKey, this.maxSessionEntries);
+      }
+      return this.recordTurnUnlocked(bufferKey, turn);
+    });
     return this.completeAddTurnOutcome(bufferKey, turn, mutation);
   }
 

package/src/capsule-import-gate.ts

@@ -0,0 +1,109 @@
+import { constants as fsConstants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { ZodError } from "zod";
+import { EngramAccessInputError } from "./access-errors.js";
+import { defaultCapsulesDir } from "./capsule-cli.js";
+
+/**
+ * Import-path gate for remote capsule imports (issue #3225 C1).
+ *
+ * `EngramAccessService.capsuleImport` serves the HTTP route and the
+ * `capsule_import` MCP operation, where the caller supplies `archivePath`.
+ * The destination namespace is authorized, but the source archive previously
+ * was not: any path the server process could read was accepted. This module
+ * confines the source to the namespace capsule store, `defaultCapsulesDir`
+ * of the destination storage dir, which is the same store `capsule export`
+ * writes and `capsule_list` lists.
+ *
+ * The CLI import path does not go through this gate; it is the explicit
+ * operator authority and keeps unrestricted local-path imports.
+ */
+
+/** True when the caught error carries the given errno-style code. */
+function hasFsErrorCode(cause: unknown, code: string): boolean {
+  return cause instanceof Object && "code" in cause && cause.code === code;
+}
+
+/** True when `cause` is a path error the gate reports as an input error instead of a server fault. */
+function isInputFsError(cause: unknown): boolean {
+  return (
+    hasFsErrorCode(cause, "ENOENT") ||
+    hasFsErrorCode(cause, "ENOTDIR") ||
+    hasFsErrorCode(cause, "EACCES") ||
+    hasFsErrorCode(cause, "EPERM") ||
+    hasFsErrorCode(cause, "ELOOP") ||
+    hasFsErrorCode(cause, "ENAMETOOLONG") ||
+    hasFsErrorCode(cause, "ERR_INVALID_ARG_VALUE")
+  );
+}
+
+/** Matches zod-style `Z_` error codes carried on error objects. */
+const ZOD_STYLE_CODE = /^Z_/;
+
+/** True when the caught error carries a zod-style `Z_` code. */
+function hasZodStyleErrorCode(cause: unknown): boolean {
+  return cause instanceof Object && "code" in cause && ZOD_STYLE_CODE.test(String(cause.code));
+}
+
+/** True when the importer failed on archive input (shape, gzip, checksum) rather than backend errors. */
+export function isCapsuleImportArchiveInputError(cause: unknown, message: string): boolean {
+  if (cause instanceof ZodError) return true;
+  if (hasZodStyleErrorCode(cause)) return true;
+  return (
+    message.startsWith("importCapsule: archive") ||
+    message.startsWith("importCapsule: bundle") ||
+    message.startsWith("importCapsule: manifest") ||
+    message.startsWith("importCapsule: record") ||
+    /incorrect header check|invalid stored block lengths|not in gzip format|unexpected end of file/i.test(message)
+  );
+}
+
+/**
+ * One message for every refusal before confinement is proven. A caller that
+ * can name any server path must not learn from the error whether that path
+ * exists, is a directory, or is unreadable.
+ */
+const IMPORT_SOURCE_REFUSED =
+  "capsule import failed: archivePath must be an existing file inside the namespace capsule store";
+
+/** Resolve a path to its real path; a missing, looping, or unreadable path resolves to null. */
+async function realpathOrNull(target: string): Promise<string | null> {
+  try {
+    return await realpath(target);
+  } catch (cause) {
+    if (!isInputFsError(cause)) throw cause;
+    return null;
+  }
+}
+
+/** True when `target` is a strict descendant of `directory` (both already resolved). */
+function isInsideDirectory(directory: string, target: string): boolean {
+  const rel = path.relative(directory, target);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+
+/**
+ * Validate a remote import source and confine it to the namespace capsule
+ * store. Both real paths are resolved first, so `..` segments and store
+ * symlinks that point outside are refused. Confinement is checked before the
+ * file is inspected in any other way, and every failure before it proves
+ * confinement raises the same message.
+ */
+export async function validateCapsuleImportArchive(archivePath: string, storageDir: string): Promise<void> {
+  const storeReal = await realpathOrNull(defaultCapsulesDir(storageDir));
+  const archiveReal = await realpathOrNull(archivePath);
+  if (storeReal === null || archiveReal === null || !isInsideDirectory(storeReal, archiveReal)) {
+    throw new EngramAccessInputError(IMPORT_SOURCE_REFUSED);
+  }
+  // The path now names a store entry, so the checks below only describe the store.
+  if (!(await stat(archiveReal)).isFile()) {
+    throw new EngramAccessInputError("capsule import failed: archivePath must point to a file");
+  }
+  try {
+    await access(archiveReal, fsConstants.R_OK);
+  } catch (cause) {
+    if (!isInputFsError(cause)) throw cause;
+    throw new EngramAccessInputError("capsule import failed: archive is not readable");
+  }
+}

package/src/extraction-quote-grounding.test.ts

@@ -593,3 +593,79 @@ test("a quote naming rewritten text is located after temporal anchoring", () =>
   );
   assert.equal(grounded.facts.length, 1);
 });
+
+const TURN_ONE =
+  "The river gauges read high all week near the mill.\n\nAlso the culvert repair is scheduled for next Tuesday at the plant.";
+const TURN_TWO = "A different conversation about the warehouse roof leaks and the insurance claim.";
+const TURNED_SOURCE = `${TURN_ONE}\n\n${TURN_TWO}`;
+
+test("a quote crossing a blank line inside one turn is anchored when turn boundaries are given", () => {
+  const quote = "near the mill. Also the culvert repair is scheduled for next Tuesday at the plant";
+  const anchors = quoteAnchors(quote, TURNED_SOURCE, undefined, [TURN_ONE, TURN_TWO]);
+  assert.equal(anchors.length, 1);
+  assert.equal(anchors[0]!.quote, quote);
+});
+
+test("a quote spanning two turns still yields no anchor even with turn boundaries given", () => {
+  const stitched = "scheduled for next Tuesday at the plant.\n\nA different conversation about the warehouse";
+  assert.deepEqual(quoteAnchors(stitched, TURNED_SOURCE, undefined, [TURN_ONE, TURN_TWO]), []);
+});
+
+test("the anchor window reaches past a blank line to its turn's end, never into the next turn", () => {
+  const [anchor] = quoteAnchors(
+    "The river gauges read high all week near the mill.",
+    TURNED_SOURCE,
+    undefined,
+    [TURN_ONE, TURN_TWO],
+  );
+  assert.ok(anchor !== undefined);
+  assert.ok(anchor.window.includes("culvert repair is scheduled for next Tuesday at the plant"));
+  assert.ok(!anchor.window.includes("warehouse"));
+});
+
+test("without turn boundaries a blank line still rejects the quote and cuts the window", () => {
+  const quote = "near the mill. Also the culvert repair is scheduled for next Tuesday at the plant";
+  assert.deepEqual(quoteAnchors(quote, TURNED_SOURCE), []);
+  const [anchor] = quoteAnchors("The river gauges read high all week near the mill.", TURNED_SOURCE);
+  assert.ok(anchor !== undefined);
+  assert.ok(!anchor.window.includes("culvert repair"));
+});
+
+test("turn texts that do not tile the source fall back to blank-line behavior", () => {
+  const quote = "near the mill. Also the culvert repair is scheduled for next Tuesday at the plant";
+  assert.deepEqual(quoteAnchors(quote, TURNED_SOURCE, undefined, ["a turn that is not in the source"]), []);
+});
+
+const LONG_TAIL = Array.from({ length: 60 }, (_, index) => `word${index} filler`).join(" ");
+const LONG_TURN = `The river gauges read high all week near the mill. ${LONG_TAIL}`;
+const LONG_SOURCE = `${LONG_TURN}\n\n${TURN_TWO}`;
+
+test("the window cut by the turn length ends on a whole word, matching the no-turns window", () => {
+  const quote = "The river gauges read high all week near the mill.";
+  const [bounded] = quoteAnchors(quote, LONG_SOURCE, undefined, [LONG_TURN, TURN_TWO]);
+  const [plain] = quoteAnchors(quote, LONG_TURN);
+  assert.ok(bounded !== undefined && plain !== undefined);
+  assert.equal(bounded.window, plain.window);
+});
+
+test("the window of a quote in a non-last turn does not end with a separator newline", () => {
+  const [anchor] = quoteAnchors(
+    "The river gauges read high all week near the mill.",
+    TURNED_SOURCE,
+    undefined,
+    [TURN_ONE, TURN_TWO],
+  );
+  assert.ok(anchor !== undefined);
+  assert.ok(!anchor.window.endsWith("\n"));
+});
+
+test("a quote ending exactly at the last character of a non-last turn still anchors", () => {
+  const anchors = quoteAnchors(
+    "Also the culvert repair is scheduled for next Tuesday at the plant.",
+    TURNED_SOURCE,
+    undefined,
+    [TURN_ONE, TURN_TWO],
+  );
+  assert.equal(anchors.length, 1);
+  assert.ok(anchors[0]!.window.endsWith("at the plant."));
+});

package/src/extraction-quote-grounding.ts

@@ -67,7 +67,18 @@ function normalizeWhitespaceWithMap(source: string): { text: string; originalInd
   return { text: chars.join(""), originalIndex };
 }
 
-function findQuoteAnchors(quote: string, source: string): QuoteAnchor[] {
+function turnStartOffsets(source: string, turns: readonly string[]): readonly number[] | undefined {
+  const offsets: number[] = [];
+  let at = 0;
+  for (const turn of turns) {
+    if (!source.startsWith(turn, at)) return undefined;
+    offsets.push(at);
+    at += turn.length + TURN_SEPARATOR.length;
+  }
+  return at - TURN_SEPARATOR.length === source.length ? offsets : undefined;
+}
+
+function findQuoteAnchors(quote: string, source: string, bounds?: readonly number[]): QuoteAnchor[] {
   const needle = quote.replace(/\s+/gu, " ").trim();
   if (needle.length < QUOTE_ANCHOR_MIN_CHARS) return [];
   const normalized = normalizeWhitespaceWithMap(source);
@@ -79,17 +90,36 @@ function findQuoteAnchors(quote: string, source: string): QuoteAnchor[] {
     from = at + 1;
     const start = normalized.originalIndex[at]!;
     const end = normalized.originalIndex[at + needle.length - 1]! + 1;
-    if (source.slice(start, end).includes(TURN_SEPARATOR)) continue;
-
-    let before = source.slice(Math.max(0, start - QUOTE_ANCHOR_CONTEXT_CHARS), start);
-    const turnStart = before.lastIndexOf(TURN_SEPARATOR);
-    if (turnStart >= 0) before = before.slice(turnStart + TURN_SEPARATOR.length);
-    else if (start > QUOTE_ANCHOR_CONTEXT_CHARS) before = before.replace(/^\S+/u, "");
 
-    let after = source.slice(end, end + QUOTE_ANCHOR_CONTEXT_CHARS);
-    const turnEnd = after.indexOf(TURN_SEPARATOR);
-    if (turnEnd >= 0) after = after.slice(0, turnEnd);
-    else if (source.length - end > QUOTE_ANCHOR_CONTEXT_CHARS) after = after.replace(/\S+$/u, "");
+    let before: string;
+    let after: string;
+    if (bounds === undefined) {
+      if (source.slice(start, end).includes(TURN_SEPARATOR)) continue;
+      before = source.slice(Math.max(0, start - QUOTE_ANCHOR_CONTEXT_CHARS), start);
+      const sepBefore = before.lastIndexOf(TURN_SEPARATOR);
+      if (sepBefore >= 0) before = before.slice(sepBefore + TURN_SEPARATOR.length);
+      else if (start > QUOTE_ANCHOR_CONTEXT_CHARS) before = before.replace(/^\S+/u, "");
+      after = source.slice(end, end + QUOTE_ANCHOR_CONTEXT_CHARS);
+      const sepAfter = after.indexOf(TURN_SEPARATOR);
+      if (sepAfter >= 0) after = after.slice(0, sepAfter);
+      else if (source.length - end > QUOTE_ANCHOR_CONTEXT_CHARS) after = after.replace(/\S+$/u, "");
+    } else {
+      let turnStart = 0;
+      let turnEnd = source.length;
+      for (const bound of bounds) {
+        if (bound <= start) turnStart = bound;
+        else {
+          turnEnd = bound - TURN_SEPARATOR.length;
+          break;
+        }
+      }
+      if (turnEnd < end) continue;
+      before = source.slice(Math.max(turnStart, start - QUOTE_ANCHOR_CONTEXT_CHARS), start);
+      if (start - QUOTE_ANCHOR_CONTEXT_CHARS > turnStart) before = before.replace(/^\S+/u, "");
+      const contextEnd = Math.min(turnEnd, end + QUOTE_ANCHOR_CONTEXT_CHARS);
+      after = source.slice(end, contextEnd);
+      if (end + QUOTE_ANCHOR_CONTEXT_CHARS < turnEnd) after = after.replace(/\S+$/u, "");
+    }
 
     anchors.push({ quote: needle, window: `${before}${needle.replace(/;/gu, ",")}${after}` });
   }
@@ -109,16 +139,22 @@ function findQuoteAnchors(quote: string, source: string): QuoteAnchor[] {
  * `source` may have been rewritten before grounding (temporal anchoring,
  * pronoun resolution) while the model quoted the original words. When the raw
  * quote is not found, `transformQuote` applies the same rewrite to the quote.
+ *
+ * `turns` are the texts `source` was joined from; when they tile `source`
+ * exactly, quotes and windows cut at real turn boundaries instead of any
+ * blank line. Without them, every `TURN_SEPARATOR` run is a boundary.
  */
 export function quoteAnchors(
   quote: string | undefined,
   source: string,
   transformQuote?: (quote: string) => string,
+  turns?: readonly string[],
 ): QuoteAnchor[] {
   if (typeof quote !== "string") return [];
-  const exact = findQuoteAnchors(quote, source);
+  const bounds = turns === undefined ? undefined : turnStartOffsets(source, turns);
+  const exact = findQuoteAnchors(quote, source, bounds);
   if (exact.length > 0 || transformQuote === undefined) return exact;
-  return findQuoteAnchors(transformQuote(quote), source);
+  return findQuoteAnchors(transformQuote(quote), source, bounds);
 }
 
 export function tokenPool(tokens: ReadonlySet<string>): TokenPool {

package/src/extraction-source-grounding-rules.ts

@@ -43,6 +43,8 @@ export interface ExtractionSourceGroundingOptions {
   spanMode?: "off" | "shadow" | "on";
   /** Rewrite applied to the source before this stage, so a verbatim quote can still be located in it. */
   quoteTransform?: (quote: string) => string;
+  /** Turn texts the sources were joined from, so quote anchors cut at real turn boundaries. */
+  turns?: readonly string[];
 }
 
 export function applyExtractionSourceGrounding(
@@ -68,6 +70,7 @@ export function applyExtractionSourceGrounding(
         ? undefined
         : anchorSource(roleAssertionSources.identity),
     };
+  const anchoredTurns = options.turns === undefined ? undefined : options.turns.map((turn) => anchorSource(turn));
   return filterExtractionResultBySource(
     result,
     anchorSource(sourceText),
@@ -78,6 +81,7 @@ export function applyExtractionSourceGrounding(
     options.anchorTemporalExpressions
       ? (quote) => anchorSource(options.quoteTransform?.(quote) ?? quote)
       : undefined,
+    anchoredTurns,
   );
 }
 
@@ -1117,6 +1121,7 @@ export function filterExtractionResultBySource(
   eventTimeNormalizer?: (eventTime: string) => string,
   spanMode: "off" | "shadow" | "on" = "off",
   quoteTransform?: (quote: string) => string,
+  turns?: readonly string[],
 ): ExtractionResult {
   if (source.trim().length === 0) {
     return {
@@ -1136,7 +1141,7 @@ export function filterExtractionResultBySource(
     result.facts.some((fact) => typeof fact.quote === "string") ? tokenize(quoteSource) : new Set(),
   );
   const facts = result.facts.flatMap((fact) => {
-    const anchors = quoteAnchors(fact.quote, quoteSource, quoteTransform);
+    const anchors = quoteAnchors(fact.quote, quoteSource, quoteTransform, turns);
     const grounded = filterGroundedFact(
       fact,
       source,

package/src/extraction-source-grounding.ts

@@ -101,6 +101,7 @@ export function filterExtractionResultBySource(
   eventTimeNormalizer?: (eventTime: string) => string,
   spanMode: "off" | "shadow" | "on" = "off",
   quoteTransform?: (quote: string) => string,
+  turns?: readonly string[],
 ): ExtractionResult {
   return filterGroundingRules(
     result,
@@ -110,5 +111,6 @@ export function filterExtractionResultBySource(
     eventTimeNormalizer,
     spanMode,
     quoteTransform,
+    turns,
   );
 }

package/src/extraction.ts

@@ -1122,10 +1122,8 @@ export class ExtractionEngine {
     const groundingSource = boundedTurns
       .map((turn) => turn.content)
       .join("\n\n");
-    const assertionSource = boundedTurns
-      .filter((turn) => turn.extractionContextOnly !== true)
-      .map((turn) => turn.content)
-      .join("\n\n");
+    const assertionTurns = boundedTurns.filter((turn) => turn.extractionContextOnly !== true);
+    const assertionSource = assertionTurns.map((turn) => turn.content).join("\n\n");
     const roleAssertionSources: ExtractionGroundingRoleSources = {
       profile: boundedTurns
         .filter((turn) => turn.role === "user" && turn.extractionContextOnly !== true)
@@ -1171,6 +1169,7 @@ export class ExtractionEngine {
       sourceConnector,
       ambientCapture,
       scopeClassificationEnabled: lifecycleCaps.extractionScopeClassification,
+      turns: assertionTurns.map((turn) => turn.content),
     };
 
     const traceId = crypto.randomUUID();