@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/plugins/defaults/memory/v3/orchestrate.ts

@@ -9,7 +9,11 @@
  *          PREVIOUS message as separate queries at a smaller budget
  *          (`replyQueryK` per lane), surfacing the threads the assistant is
  *          actively developing that the user's message references without
- *          naming — and
+ *          naming —
+ *        - the span-query pass — the dense lane re-run over the current
+ *          message's clause chunks as separate queries at a small per-chunk
+ *          budget (`spanQueryK`), rescuing motifs a long multi-topic message's
+ *          single query vector averages away — and
  *        - link-graph edge expansion (`edgeExpand`) over the top
  *          user-message needle+dense article seeds, and
  *        - learned-edge expansion (`edgeExpand` over the co-selection NPMI
@@ -61,6 +65,7 @@ import {
 } from "../../../../daemon/turn-latency-sub-spans.js";
 import { recordWatchdogEvent } from "../../../../telemetry/watchdog-events-store.js";
 import { getLogger } from "../logging.js";
+import type { DenseHitScored } from "./dense.js";
 import { denseLaneScored } from "./dense.js";
 import type { EdgeGraph } from "./edge.js";
 import { edgeExpand } from "./edge.js";
@@ -74,6 +79,7 @@ import type {
 } from "./pool-select.js";
 import { selectAllPoolCandidates, selectPool } from "./pool-select.js";
 import type { SectionNeedle } from "./section-needle.js";
+import { spanChunksOf } from "./span-query.js";
 import type {
   FinderLane,
   MemoryRoutingTurn,
@@ -195,6 +201,12 @@ export interface OrchestrateDeps {
    *  over `turn.previousAssistantMessage` as separate queries). `0` or
    *  omitted disables the pass (canonical value: `memory.v3.replyQueryK`). */
   replyQueryK?: number;
+  /** Per-chunk article budget for the span-query pass (dense re-run over the
+   *  current message's clause chunks as separate queries). `0` or omitted
+   *  disables the pass; it is also inert when the dense lane is disabled or
+   *  the message yields fewer than two chunks (canonical value:
+   *  `memory.v3.spanQueryK`). */
+  spanQueryK?: number;
   /** Number of top needle+dense seeds expanded. When omitted, the edge lane's
    *  own default applies (canonical value: `memory.v3.edge.seedCount`). */
   edgeSeeds?: number;
@@ -220,9 +232,9 @@ export interface OrchestrateDeps {
   /** Whether to run the selector LLM. False passes all pooled candidates
    *  straight through as selections, preserving pool-order slug dedup. */
   selectorEnabled?: boolean;
-  /** Per-turn injection gate config (`memory.v3.gate` tuning + the flag-derived
-   *  `enabled`, assembled in observeTurn). Omitted/disabled → the gate never
-   *  runs and every turn proceeds to selectPool as before. */
+  /** Per-turn injection gate config (the `memory.v3.gate` tuning, threaded
+   *  through by observeTurn). Omitted/disabled → the gate never runs and every
+   *  turn proceeds to selectPool as before. */
   gateConfig?: V3GateConfig;
   /** Real concept-page count at lane build — the same corpus-size signal
    *  `resolveV3Tuning` switches the lean/full profile on. Reported with each
@@ -359,15 +371,23 @@ export async function orchestrate(
   // a vector that matches neither) at its own, smaller budget; it runs in the
   // same parallel batch.
   // `denseK = 0` disables dense retrieval for the whole turn, including the
-  // reply-query dense pass.
+  // reply-query and span-query dense passes.
   const replyK = deps.replyQueryK ?? 0;
   const replyQuery =
     replyK > 0 ? (turn.previousAssistantMessage ?? "").trim() : "";
   const denseEnabled = denseK > 0;
-  const [needled, densed, replyNeedled, replyDensed] = await timeLatencySubSpan(
-    "v3_lanes",
-    "Memory search",
-    () =>
+  // The span-query pass re-runs the dense lane over the current message's
+  // clause chunks as SEPARATE queries (a single embedding of a multi-topic
+  // message averages its intents into a vector that matches none of them —
+  // the within-message form of the averaging the reply pass avoids across
+  // speakers). A single-chunk message would just duplicate the full-message
+  // dense query, so the pass needs at least two chunks to run.
+  const spanK = deps.spanQueryK ?? 0;
+  const spanChunks =
+    spanK > 0 && denseEnabled ? spanChunksOf(turn.currentMessage) : [];
+  const spanQueries = spanChunks.length >= 2 ? spanChunks : [];
+  const [needled, densed, replyNeedled, replyDensed, spanDensed] =
+    await timeLatencySubSpan("v3_lanes", "Memory search", () =>
       Promise.all([
         Promise.resolve(deps.needle.queryScored(turn.currentMessage, needleK)),
         denseEnabled
@@ -381,8 +401,13 @@ export async function orchestrate(
         replyQuery.length > 0 && denseEnabled
           ? denseLaneScored(deps.denseConfig, replyQuery, replyK)
           : Promise.resolve([]),
+        Promise.all(
+          spanQueries.map((chunk) =>
+            denseLaneScored(deps.denseConfig, chunk, spanK),
+          ),
+        ),
       ]),
-  );
+    );
   // Everything from here to the step-3 selection — finder assembly, the
   // entity lane, the injection gate, edge + learned-edge expansion, pool
   // assembly — is synchronous in-memory work, measured as one `v3_expand`
@@ -437,18 +462,29 @@ export async function orchestrate(
   // Step 1b: dense hits — `section` is the matched ORDINAL; resolve it to the
   // concrete `Section` via the section index. Falls back to undefined (blank
   // descriptor) if the ordinal is not in the in-memory index.
+  //
+  // `denseOwnedSection` tracks the articles whose recorded matched section
+  // came from THIS loop (needle records first and wins ties), along with the
+  // hit's cosine score — the span pass upgrades those sections when a clause
+  // query finds a strictly stronger match under the same metric.
+  const denseOwnedSection = new Map<Slug, number>();
   for (const hit of densed) {
     // A deleted page's points can linger in Qdrant; keep only live-index
     // articles. The section index is rebuilt from `getPageIndex` at `initLanes`,
     // so `byArticle` holds exactly the live pages (synthetic capability slugs
     // included) — only truly-deleted pages are dropped here.
-    if (!deps.sectionIndex.byArticle.has(hit.article)) continue;
-    addFinder(
+    if (!deps.sectionIndex.byArticle.has(hit.article)) {
+      continue;
+    }
+    const section = sectionByOrdinal(
+      deps.sectionIndex,
       hit.article,
-      sectionByOrdinal(deps.sectionIndex, hit.article, hit.section),
-      undefined,
-      "dense",
+      hit.section,
     );
+    if (section && !matchedSections.has(hit.article)) {
+      denseOwnedSection.set(hit.article, hit.score);
+    }
+    addFinder(hit.article, section, undefined, "dense");
   }
 
   // Step 1b': reply-query hits — candidates the user-message lanes already
@@ -469,7 +505,53 @@ export async function orchestrate(
     );
   }
 
-  // Step 1b'': entity lane — sections whose `## ` heading NAMES a distinctive
+  // Step 1b'': span-query hits — union-additive at the pass's own small
+  // budget. Candidates the primary or reply lanes already surfaced keep their
+  // attribution (`addFinder`'s first-lane-wins dedupe); only genuinely
+  // span-surfaced articles tag `"span"`. Like the reply pass, span hits are
+  // excluded from the injection gate (which scores current-message needle +
+  // dense only) and from the edge-expansion seeds.
+  //
+  // An article can be surfaced by SEVERAL chunks; dedupe by best cosine score
+  // before `addFinder`, since chunk order would otherwise decide which section
+  // gets recorded — letting an earlier chunk's weak match mask the strong
+  // buried-clause match the pass exists to recover.
+  const bestSpanHits = new Map<Slug, DenseHitScored>();
+  for (const hit of spanDensed.flat()) {
+    const prev = bestSpanHits.get(hit.article);
+    if (!prev || hit.score > prev.score) {
+      bestSpanHits.set(hit.article, hit);
+    }
+  }
+  // For an article a primary lane already surfaced, upgrade its matched
+  // section/descriptor ONLY when the existing section was recorded by the
+  // full-message dense hit and the span's cosine is strictly higher — same
+  // encoder, same collection, so the comparison is evidence, not judgment.
+  // Needle- and reply-recorded sections stay (BM25 and cosine scores are not
+  // comparable, and the reply pass's own convention is first-wins); lane
+  // attribution never changes here.
+  for (const hit of bestSpanHits.values()) {
+    if (!deps.sectionIndex.byArticle.has(hit.article)) {
+      continue;
+    }
+    const section = sectionByOrdinal(
+      deps.sectionIndex,
+      hit.article,
+      hit.section,
+    );
+    const denseScore = denseOwnedSection.get(hit.article);
+    if (section && denseScore !== undefined && hit.score > denseScore) {
+      matchedSections.set(hit.article, section);
+      const existing = finder.find((c) => c.slug === hit.article);
+      if (existing) {
+        existing.descriptor = section.text;
+      }
+      continue;
+    }
+    addFinder(hit.article, section, undefined, "span");
+  }
+
+  // Step 1b''': entity lane — sections whose `## ` heading NAMES a distinctive
   // entity the message mentions. Additive BM25 buries a single named entity
   // under a long, multi-topic message's bulk theme; this keys on the heading
   // vocabulary so the page the user named surfaces regardless of the bulk
@@ -501,8 +583,8 @@ export async function orchestrate(
     }
   }
 
-  // Step 1b''': opt-in injection gate. With the CURRENT-message finder lanes in
-  // hand (needle + dense — NOT reply/entity/edge, which only add recall), decide
+  // Step 1b'''': opt-in injection gate. With the CURRENT-message finder lanes in
+  // hand (needle + dense — NOT reply/span/entity/edge, which only add recall), decide
   // whether retrieval is confident enough to spend the selectPool LLM call this
   // turn. Default-off via `?.enabled`; pass-open on any throw (a gate bug must
   // never drop a turn's memory). A closed gate either hard-skips selection

package/src/plugins/defaults/memory/v3/page-content.ts

@@ -1,8 +1,8 @@
 import { getWorkspaceDir } from "../paths.js";
+import { injectedConceptHeader } from "../substrate/injected-block-slugs.js";
+import { readPage, renderPageContent } from "../substrate/page-store.js";
 import { renderCapabilityContent } from "./capabilities.js";
 import { renderCard } from "./card.js";
-import { injectedConceptHeader } from "./substrate/injected-block-slugs.js";
-import { readPage, renderPageContent } from "./substrate/page-store.js";
 import type { Section, Slug } from "./types.js";
 
 /**
@@ -35,12 +35,18 @@ function withConceptHeader(slug: Slug, body: string): string {
  */
 export async function renderV3PageContent(slug: Slug): Promise<string> {
   const capability = renderCapabilityContent(slug);
-  if (capability !== null) return capability;
+  if (capability !== null) {
+    return capability;
+  }
   try {
     const page = await readPage(getWorkspaceDir(), slug);
-    if (!page) return "";
+    if (!page) {
+      return "";
+    }
     const content = renderPageContent(page).trim();
-    if (content.length === 0) return "";
+    if (content.length === 0) {
+      return "";
+    }
     return withConceptHeader(slug, content);
   } catch {
     return "";
@@ -62,10 +68,14 @@ export async function renderV3PageContent(slug: Slug): Promise<string> {
  */
 export async function renderV3CardContent(slug: Slug): Promise<string> {
   const capability = renderCapabilityContent(slug);
-  if (capability !== null) return capability;
+  if (capability !== null) {
+    return capability;
+  }
   try {
     const page = await readPage(getWorkspaceDir(), slug);
-    if (!page) return "";
+    if (!page) {
+      return "";
+    }
     return renderCard(slug, renderPageContent(page));
   } catch {
     return "";
@@ -93,10 +103,16 @@ export async function renderV3SectionContent(
   section: Section | undefined,
 ): Promise<string> {
   const capability = renderCapabilityContent(slug);
-  if (capability !== null) return capability;
-  if (!section) return renderV3PageContent(slug);
+  if (capability !== null) {
+    return capability;
+  }
+  if (!section) {
+    return renderV3PageContent(slug);
+  }
 
   const text = section.text.trim();
-  if (text.length === 0) return "";
+  if (text.length === 0) {
+    return "";
+  }
   return withConceptHeader(slug, text);
 }

package/src/plugins/defaults/memory/v3/prune.ts

@@ -65,6 +65,10 @@ import { getMemoryConfig } from "../config.js";
 import { getLogger } from "../logging.js";
 import { memorySqliteOrNull } from "../memory-db.js";
 import { unwrapMemoryBlock, wrapMemoryBlock } from "../memory-marker.js";
+import {
+  INJECTED_CONCEPT_HEADER_REGEX,
+  readInjectedBlock,
+} from "../substrate/injected-block-slugs.js";
 import {
   getActiveEntries,
   getPrunedSlugs,
@@ -72,10 +76,6 @@ import {
   MEMORY_V3_INJECTED_BLOCK_METADATA_KEY,
   residentBytes,
 } from "./ever-injected-store.js";
-import {
-  INJECTED_CONCEPT_HEADER_REGEX,
-  readInjectedBlock,
-} from "./substrate/injected-block-slugs.js";
 
 const log = getLogger("memory-v3-shadow");
 
@@ -133,7 +133,9 @@ export function parseCardSections(inner: string): {
     cardMatches.map((match) => ({ index: match.index!, slug: match[1]! }));
   for (const match of inner.matchAll(TOP_LEVEL_HEADER_REGEX)) {
     const i = match.index!;
-    if (cardStarts.has(i)) continue;
+    if (cardStarts.has(i)) {
+      continue;
+    }
     // Foreign header on a `\n\n` seam → starts its own chunk.
     if (i >= 2 && inner[i - 1] === "\n" && inner[i - 2] === "\n") {
       boundaries.push({ index: i, slug: null });
@@ -175,16 +177,24 @@ export function filterPrunedCardSections(
   prunedSlugs: ReadonlySet<string>,
 ): string {
   const { preamble, sections, pieces } = parseCardSections(inner);
-  if (sections.length === 0) return inner;
+  if (sections.length === 0) {
+    return inner;
+  }
 
   const kept = pieces.filter(
     (piece) => piece.kind !== "card" || !prunedSlugs.has(piece.slug),
   );
-  if (kept.length === pieces.length) return inner;
-  if (kept.length === 0) return "";
+  if (kept.length === pieces.length) {
+    return inner;
+  }
+  if (kept.length === 0) {
+    return "";
+  }
 
   const texts = kept.map((piece) => piece.text);
-  if (preamble.length > 0) texts.unshift(preamble);
+  if (preamble.length > 0) {
+    texts.unshift(preamble);
+  }
   return texts.join("\n\n");
 }
 
@@ -226,7 +236,9 @@ export function planPrune(
 ): PrunePlan | null {
   const activeEntries = getActiveEntries(conversationId);
   const resident = activeEntries.reduce((sum, e) => sum + e.bytes, 0);
-  if (resident <= deps.maxResidentBytes) return null;
+  if (resident <= deps.maxResidentBytes) {
+    return null;
+  }
 
   const memoryRaw = memorySqliteOrNull("planPrune");
   const selectionRows = memoryRaw
@@ -256,7 +268,9 @@ export function planPrune(
   const slugs: string[] = [];
   let bytesFreed = 0;
   for (const candidate of candidates) {
-    if (resident - bytesFreed <= deps.targetResidentBytes) break;
+    if (resident - bytesFreed <= deps.targetResidentBytes) {
+      break;
+    }
     slugs.push(candidate.slug);
     bytesFreed += candidate.bytes;
   }
@@ -293,7 +307,9 @@ export function collectPersistedV3Cards(conversationId: string): Set<string> {
       row.metadata,
       MEMORY_V3_INJECTED_BLOCK_METADATA_KEY,
     );
-    if (block === null) continue;
+    if (block === null) {
+      continue;
+    }
     for (const section of parseCardSections(unwrapMemoryBlock(block))
       .sections) {
       sections.add(section.text);
@@ -321,7 +337,9 @@ export function stripPrunedCardsFromMessages(
 ): number {
   let strippedBlocks = 0;
   for (const message of messages) {
-    if (message.role !== "user") continue;
+    if (message.role !== "user") {
+      continue;
+    }
     let changed = false;
     const nextContent: ContentBlock[] = [];
     for (const block of message.content) {
@@ -355,7 +373,9 @@ export function stripPrunedCardsFromMessages(
         nextContent.push({ type: "text", text: wrapMemoryBlock(filtered) });
       }
     }
-    if (changed) message.content = nextContent;
+    if (changed) {
+      message.content = nextContent;
+    }
   }
   return strippedBlocks;
 }
@@ -400,7 +420,9 @@ export async function runPruneValve(
 ): Promise<PrunePlan | null> {
   // Defensive read: test configs may omit the prune block entirely.
   const pruneConfig = getMemoryConfig()?.v3?.prune;
-  if (!pruneConfig) return null;
+  if (!pruneConfig) {
+    return null;
+  }
 
   // Planning needs only the store (cheap); the persisted-metadata scan for
   // the live strip's ownership test runs only once a plan exists — a
@@ -413,7 +435,9 @@ export async function runPruneValve(
     },
     conversationId,
   );
-  if (!plan) return null;
+  if (!plan) {
+    return null;
+  }
 
   markPruned(conversationId, plan.slugs, options.now ?? Date.now());
 

package/src/plugins/defaults/memory/v3/selection-log-store.ts

@@ -22,12 +22,12 @@ import { isMemoryV3Live } from "../../../../config/memory-v3-gate.js";
 import { getDb, getSqliteFrom } from "../../../../persistence/db-connection.js";
 import { memorySqliteOrNull } from "../memory-db.js";
 import { getWorkspaceDir } from "../paths.js";
+import { readPage } from "../substrate/page-store.js";
 import { capabilityOrDiskBody } from "./capabilities.js";
 import { sectionByOrdinal } from "./orchestrate.js";
 import { renderV3SectionContent } from "./page-content.js";
 import { renderMemoryBlock } from "./render-injection.js";
 import { buildSectionIndex } from "./sections.js";
-import { readPage } from "./substrate/page-store.js";
 import {
   type Section,
   SELECTION_SOURCES,
@@ -63,7 +63,9 @@ function rowsForTurn(conversationId: string, turn: number): SelectionRow[] {
 }
 
 function rowsForMessageIds(messageIds: string[]): SelectionRow[] {
-  if (messageIds.length === 0) return [];
+  if (messageIds.length === 0) {
+    return [];
+  }
   const raw = memorySqliteOrNull("rowsForMessageIds");
   if (!raw) {
     return [];
@@ -87,7 +89,9 @@ const MAX_FORK_HOPS = 64;
  * stamps onto every message a fork copies, for the given message ids.
  */
 function forkSourceIdsOf(messageIds: string[]): string[] {
-  if (messageIds.length === 0) return [];
+  if (messageIds.length === 0) {
+    return [];
+  }
   const placeholders = messageIds.map(() => "?").join(", ");
   const rows = getSqliteFrom(getDb())
     .query(
@@ -117,10 +121,16 @@ function rowsViaForkSource(messageIds: string[]): SelectionRow[] {
   const visited = new Set(messageIds);
   for (let hop = 0; hop < MAX_FORK_HOPS; hop++) {
     const sources = forkSourceIdsOf(frontier).filter((id) => !visited.has(id));
-    if (sources.length === 0) return [];
-    for (const id of sources) visited.add(id);
+    if (sources.length === 0) {
+      return [];
+    }
+    for (const id of sources) {
+      visited.add(id);
+    }
     const rows = rowsForMessageIds(sources);
-    if (rows.length > 0) return rows;
+    if (rows.length > 0) {
+      return rows;
+    }
     frontier = sources;
   }
   return [];
@@ -140,7 +150,9 @@ async function reconstructMatchedSections(
   const sectionSlugs = rows
     .filter((r) => r.section_ordinal != null)
     .map((r) => r.slug);
-  if (sectionSlugs.length === 0) return new Map();
+  if (sectionSlugs.length === 0) {
+    return new Map();
+  }
 
   const workspaceDir = getWorkspaceDir();
   const pageBody = (slug: Slug): Promise<string> =>
@@ -155,9 +167,13 @@ async function reconstructMatchedSections(
 
   const sectionBySlug = new Map<Slug, Section>();
   for (const row of rows) {
-    if (row.section_ordinal == null) continue;
+    if (row.section_ordinal == null) {
+      continue;
+    }
     const section = sectionByOrdinal(index, row.slug, row.section_ordinal);
-    if (section) sectionBySlug.set(row.slug, section);
+    if (section) {
+      sectionBySlug.set(row.slug, section);
+    }
   }
   return sectionBySlug;
 }
@@ -165,7 +181,9 @@ async function reconstructMatchedSections(
 async function buildSelectionLog(
   rows: SelectionRow[],
 ): Promise<MemoryV3SelectionLog | null> {
-  if (rows.length === 0) return null;
+  if (rows.length === 0) {
+    return null;
+  }
 
   const config = getConfig();
   const selections = rows.map((r) => ({
@@ -226,7 +244,9 @@ export async function getMemoryV3SelectionForInspector(
   conversationId: string,
   turn: number | null | undefined,
 ): Promise<MemoryV3SelectionLog | null> {
-  if (turn == null) return null;
+  if (turn == null) {
+    return null;
+  }
   return buildSelectionLog(rowsForTurn(conversationId, turn));
 }
 
@@ -280,7 +300,9 @@ export function summarizeSelections(conversationId: string): SelectionSummary {
   const turns = new Set<number>();
   const slugs = new Set<string>();
   for (const row of rows) {
-    if (isSelectionSource(row.source)) bySource[row.source] += 1;
+    if (isSelectionSource(row.source)) {
+      bySource[row.source] += 1;
+    }
     turns.add(row.turn);
     slugs.add(row.slug);
   }

package/src/plugins/defaults/memory/v3/shadow-plugin.ts

@@ -32,6 +32,7 @@ import {
 } from "@vellumai/plugin-api";
 
 import { getConfig } from "../../../../config/loader.js";
+import { isMemoryEnabled } from "../../../../config/memory-v3-gate.js";
 import type { AssistantConfig } from "../../../../config/schema.js";
 import {
   recordLatencySubSpan,
@@ -41,6 +42,8 @@ import { stripCommentLines } from "../host-utils.js";
 import { getLogger } from "../logging.js";
 import { memorySqliteOrNull } from "../memory-db.js";
 import { getWorkspaceDir, getWorkspacePromptPath } from "../paths.js";
+import { getPageIndex, invalidatePageIndex } from "../substrate/page-index.js";
+import { readPage, renderPageContent } from "../substrate/page-store.js";
 import {
   capabilityOrDiskBody,
   renderCapabilityContent,
@@ -53,7 +56,6 @@ import type { EntityIndex } from "./entity-lane.js";
 import { buildEntityIndex } from "./entity-lane.js";
 import { getActiveSlugs } from "./ever-injected-store.js";
 import { computeFreshSet } from "./fresh-set.js";
-import { isMemoryV3InjectionGateEnabled } from "./gate-flag.js";
 import { computeHotSet } from "./hot-set.js";
 import { bumpLanesVersion, readLanesVersion } from "./lanes-version-store.js";
 import { computeLearnedEdgeGraph } from "./learned-edges.js";
@@ -67,8 +69,6 @@ import { ensureSectionCollection } from "./section-dense-store.js";
 import type { SectionNeedle } from "./section-needle.js";
 import { buildSectionNeedle } from "./section-needle.js";
 import { buildSectionIndex } from "./sections.js";
-import { getPageIndex, invalidatePageIndex } from "./substrate/page-index.js";
-import { readPage, renderPageContent } from "./substrate/page-store.js";
 import { resolveV3Tuning } from "./tuning-profile.js";
 import {
   type MemoryRoutingTurn,
@@ -690,7 +690,7 @@ export async function observeTurn(
     }
 
     const cfg = getConfig();
-    if (cfg.memory.enabled === false) {
+    if (!isMemoryEnabled(cfg)) {
       return null;
     }
     // Lane init is module-memoized: the first turn after daemon start pays
@@ -702,10 +702,6 @@ export async function observeTurn(
       () => getLanes(cfg),
     );
     const v3 = cfg.memory.v3;
-    // Resolve the effective gate enable once for the turn: the feature flag
-    // AND the `memory.v3.gate.enabled` config kill-switch. Tuning lives in
-    // `memory.v3.gate`.
-    const gateEnabled = isMemoryV3InjectionGateEnabled(cfg);
     // Re-resolve the corpus-adaptive tuning each turn from the CURRENT config
     // (with the lane-build corpus-size signal) so a live config.json edit to a
     // per-turn knob (selectorEnabled, denseK, replyQueryK, edge.*) takes effect
@@ -733,6 +729,7 @@ export async function observeTurn(
       activeSlugs: getActiveSlugs(conversationId),
       entityCap: v3.entity.cap,
       replyQueryK: tuning.replyQueryK,
+      spanQueryK: tuning.spanQueryK,
       edgeSeeds: tuning.edgeSeedCount,
       edgePerSeed: tuning.edgePerSeed,
       edgeCap: tuning.edgeCap,
@@ -744,11 +741,10 @@ export async function observeTurn(
         v3.selectorPromptPath,
         getWorkspaceDir(),
       ),
-      // Per-turn injection gate: the `memory.v3.gate` tuning with the raw
-      // config `enabled` overwritten by the effective enable (flag AND config).
-      // The spread is the compile-time drift guard — if the gate schema and
-      // `V3GateConfig` diverge, this stops typechecking.
-      gateConfig: { ...v3.gate, enabled: gateEnabled },
+      // Per-turn injection gate: the `memory.v3.gate` tuning, `enabled`
+      // kill-switch included. Read-only downstream, so the config object is
+      // passed as-is.
+      gateConfig: v3.gate,
     });
 
     // A zero-selection turn over a non-trivial pool is unusual enough to be

package/src/plugins/defaults/memory/v3/span-query.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+
+import { MAX_SPAN_CHUNKS, spanChunksOf } from "./span-query.js";
+
+describe("spanChunksOf", () => {
+  test("short message passes through as its clause spans", () => {
+    const chunks = spanChunksOf(
+      "the first sentence is here. and a second sentence follows!",
+    );
+    expect(chunks).toEqual([
+      "the first sentence is here.",
+      "and a second sentence follows!",
+    ]);
+  });
+
+  test("newlines split spans like sentence punctuation", () => {
+    const chunks = spanChunksOf(
+      "a line without terminal punctuation\nanother line of the message",
+    );
+    expect(chunks).toEqual([
+      "a line without terminal punctuation",
+      "another line of the message",
+    ]);
+  });
+
+  test("sub-15-char fragments are dropped", () => {
+    const chunks = spanChunksOf("ok. this sentence is long enough to keep.");
+    expect(chunks).toEqual(["this sentence is long enough to keep."]);
+  });
+
+  test("empty and whitespace-only messages yield no chunks", () => {
+    expect(spanChunksOf("")).toEqual([]);
+    expect(spanChunksOf("  \n\n  ")).toEqual([]);
+  });
+
+  test("fullwidth CJK terminators split without trailing whitespace", () => {
+    const chunks = spanChunksOf(
+      "这是消息里的第一句完整的话。这是紧跟着的第二句完整的话！第三句也一样长够十五个字符？",
+    );
+    expect(chunks).toEqual([
+      "这是消息里的第一句完整的话。",
+      "这是紧跟着的第二句完整的话！",
+      "第三句也一样长够十五个字符？",
+    ]);
+  });
+
+  test("non-ASCII spaced terminators split like ASCII ones", () => {
+    const chunks = spanChunksOf(
+      "पहला वाक्य यहाँ लिखा गया है। दूसरा वाक्य भी यहाँ मौजूद है।",
+    );
+    expect(chunks).toEqual([
+      "पहला वाक्य यहाँ लिखा गया है।",
+      "दूसरा वाक्य भी यहाँ मौजूद है।",
+    ]);
+  });
+
+  test("ASCII periods still do not split decimals or dotted numbers", () => {
+    expect(spanChunksOf("the value came out to 3.14159 in the final run.")) //
+      .toEqual(["the value came out to 3.14159 in the final run."]);
+  });
+
+  test("a message at the cap is returned unchanged", () => {
+    const sentences = Array.from(
+      { length: MAX_SPAN_CHUNKS },
+      (_, i) => `sentence number ${i} padded for length.`,
+    );
+    expect(spanChunksOf(sentences.join(" "))).toEqual(sentences);
+  });
+
+  test("over-cap messages merge into ≤cap contiguous chunks covering every span", () => {
+    const sentences = Array.from(
+      { length: 30 },
+      (_, i) => `sentence number ${i} padded for length.`,
+    );
+    const chunks = spanChunksOf(sentences.join(" "));
+    expect(chunks.length).toBe(MAX_SPAN_CHUNKS);
+    // Contiguous coverage: rejoining the chunks reproduces every span in order.
+    expect(chunks.join(" ")).toBe(sentences.join(" "));
+    // Near-equal partition: no chunk hoards spans (30/8 → sizes 3 or 4).
+    for (const chunk of chunks) {
+      const n = chunk.match(/sentence number/g)?.length ?? 0;
+      expect(n).toBeGreaterThanOrEqual(3);
+      expect(n).toBeLessThanOrEqual(4);
+    }
+  });
+});