@remnic/core 9.69.35 → 9.69.37

package/src/extraction-span-materialize.ts

@@ -0,0 +1,241 @@
+/**
+ * Span-mode materialization for production extraction (issue #2333 Phase B).
+ *
+ * Runs immediately after the extraction result is parsed and BEFORE
+ * sanitize/grounding/judge/dedup/persistence, so everything downstream sees
+ * exactly one content form and the content-hash dedup invariant (checklist
+ * §13) holds by construction. Offsets die here — nothing offset-based is
+ * stored.
+ *
+ * Modes:
+ * - "off":    spans are never requested; a stray span is stripped untrusted.
+ * - "shadow": spans are requested alongside full content; materialization
+ *             runs for comparison only, the generated content is persisted
+ *             unchanged (zero behavior change), agreement telemetry logged.
+ * - "on":     materialized frame+span content is persisted; per-fact fail-open
+ *             to the generated content (the frame) on any validation failure.
+ *
+ * Validation (identical to the Phase A bench contract):
+ * - `0 <= charStart < charEnd <= turn.text.length`, end-exclusive, integers;
+ * - slice length <= 400 chars and non-whitespace;
+ * - frame 1..15 words;
+ * - the turn text's stamp (sha256 + length of the exact in-memory string the
+ *   model saw) must verify — offset drift is rejected, never guessed around.
+ */
+
+import { log } from "./logger.js";
+import { stampSpanSource, verifySpanSource, type SpanSourceStamp } from "./extraction-span-source-hash.js";
+import { validateSpanOffsets } from "./extraction-span-validate.js";
+import { sliceSpanText } from "./extraction-span-slice.js";
+import type { ExtractionResult } from "./types.js";
+import type { ExtractedFactSpanRef } from "./extraction-span-config.js";
+
+export const SPAN_MAX_SLICE_CHARS = 400;
+export const SPAN_MAX_FRAME_WORDS = 15;
+
+export type SpanMode = "off" | "shadow" | "on";
+
+/** A source turn exactly as rendered into the extraction prompt. */
+export interface SpanMaterializeTurn {
+  text: string;
+  stamp: SpanSourceStamp;
+}
+
+export interface SpanMaterializeFact {
+  content: string;
+  span?: ExtractedFactSpanRef | null;
+  quote?: string;
+}
+
+export interface SpanMaterializeTelemetry {
+  /** Facts that carried a span ref. */
+  attempts: number;
+  /** Spans that failed validation and fell back to generated content. */
+  fallbacks: number;
+  /** Shadow mode only: comparisons made / exact-or-containment agreements. */
+  shadowComparisons: number;
+  shadowAgreements: number;
+}
+
+/** Strip span refs from facts that were never given the span prompt
+ * (e.g. the proactive second pass). Untrusted: never validated, never used.
+ * The key is omitted entirely so no `span: undefined` reaches persistence. */
+export function stripUntrustedFactSpans<T extends { span?: unknown }>(facts: readonly T[]): T[] {
+  return facts.map((fact) => {
+    if (fact.span === undefined || fact.span === null) return fact;
+    const { span: _span, ...rest } = fact;
+    return rest as T;
+  });
+}
+
+export function buildSpanMaterializeTurns(texts: readonly string[]): SpanMaterializeTurn[] {
+  return texts.map((text) => ({ text, stamp: stampSpanSource(text) }));
+}
+
+export function truncateLocalExtractionConversation(
+  conversation: string,
+  maxConversationChars: number,
+): string {
+  return conversation.length > maxConversationChars
+    ? `${conversation.slice(0, maxConversationChars)}\n\n[truncated]`
+    : conversation;
+}
+
+export function bindLocalExtractionPrompt(
+  conversation: string,
+  turns: readonly { role: string; content: string; extractionContextOnly?: boolean }[],
+  maxConversationChars: number,
+  renderedConversation: string = conversation,
+): { promptConversation: string; spanTurns: SpanMaterializeTurn[] } {
+  const promptConversation = truncateLocalExtractionConversation(conversation, maxConversationChars);
+  if (conversation.length <= maxConversationChars || !conversation.endsWith(renderedConversation)) {
+    return { promptConversation, spanTurns: buildSpanMaterializeTurns(turns.map((turn) => turn.content)) };
+  }
+  const renderedStart = conversation.length - renderedConversation.length;
+  const limit = maxConversationChars;
+  const texts: string[] = [];
+  let pos = 0;
+  for (let index = 0; index < turns.length; index += 1) {
+    const turn = turns[index];
+    if (turn === undefined) {
+      texts.push("");
+      continue;
+    }
+    if (index > 0) pos += 2;
+    const label = turn.extractionContextOnly === true ? `context ${turn.role}` : turn.role;
+    pos += `[${label}] `.length;
+    const absStart = renderedStart + pos;
+    const absEnd = absStart + turn.content.length;
+    texts.push(absEnd > absStart && limit > absStart ? conversation.slice(absStart, Math.min(absEnd, limit)) : "");
+    pos += turn.content.length;
+  }
+  return { promptConversation, spanTurns: buildSpanMaterializeTurns(texts) };
+}
+
+export function factCarriesSpan(fact: { span?: ExtractedFactSpanRef | null }): boolean {
+  return fact.span !== undefined && fact.span !== null;
+}
+
+/**
+ * Materialize one fact's span. Never throws: any validation failure falls
+ * open to the fact's generated content and is counted.
+ */
+export function materializeFactSpan<T extends SpanMaterializeFact>(
+  fact: T,
+  turns: readonly SpanMaterializeTurn[],
+  mode: SpanMode,
+): { fact: T; outcome: "span" | "fallback"; materialized?: string } {
+  const span = fact.span ?? null;
+  if (span === null) {
+    return { fact, outcome: "fallback" };
+  }
+  const { sourceMessageIndex, charStart, charEnd, frame, sourceHash, sourceLength } = span;
+  const turn = turns[sourceMessageIndex];
+  if (
+    !Number.isInteger(sourceMessageIndex) ||
+    sourceMessageIndex < 0 ||
+    sourceMessageIndex >= turns.length ||
+    turn === undefined
+  ) {
+    return { fact: stripSpan(fact), outcome: "fallback" };
+  }
+  const stampCheck = verifySpanSource(turn.text, turn.stamp);
+  if (!stampCheck.ok) {
+    return { fact: stripSpan(fact), outcome: "fallback" };
+  }
+  if (
+    (sourceHash !== undefined && sourceHash !== turn.stamp.hash) ||
+    (sourceLength !== undefined && sourceLength !== turn.stamp.length)
+  ) {
+    return { fact: stripSpan(fact), outcome: "fallback" };
+  }
+  const offsetCheck = validateSpanOffsets({ start: charStart, end: charEnd, textLength: turn.text.length });
+  if (!offsetCheck.ok) {
+    return { fact: stripSpan(fact), outcome: "fallback" };
+  }
+  const slice = sliceSpanText({ text: turn.text, start: charStart, end: charEnd });
+  if (slice.length > SPAN_MAX_SLICE_CHARS || slice.trim().length === 0) {
+    return { fact: stripSpan(fact), outcome: "fallback" };
+  }
+  const frameWords = frame.trim().split(/\s+/).filter(Boolean);
+  if (frameWords.length === 0 || frameWords.length > SPAN_MAX_FRAME_WORDS) {
+    return { fact: stripSpan(fact), outcome: "fallback" };
+  }
+
+  const trimmedFrame = frameWords.join(" ");
+  const materialized = /[:—-]$/.test(trimmedFrame)
+    ? `${trimmedFrame} ${slice}`
+    : `${trimmedFrame}: ${slice}`;
+
+  if (mode === "on") {
+    return {
+      fact: { ...stripSpan(fact), content: materialized, quote: slice },
+      outcome: "span",
+      materialized,
+    };
+  }
+  // shadow: persist generated content unchanged; materialize for comparison.
+  return { fact: stripSpan(fact), outcome: "span", materialized };
+}
+
+/** Shadow agreement: exact match or containment either way. */
+export function spanAgreesWithContent(materialized: string, content: string): boolean {
+  const left = materialized.trim();
+  const right = content.trim();
+  return left === right || left.includes(right) || right.includes(left);
+}
+
+/**
+ * Whole-result span materialization pass (issue #2333 Phase B). Called from
+ * `ExtractionEngine.applySpanMaterialization` after parse, before sanitize /
+ * grounding / judge / dedup / persist. "off" strips stray spans untrusted.
+ * Shadow logs agreement telemetry and persists generated content. "on"
+ * persists materialized frame+span content; facts that omit the optional
+ * span are dropped so a short frame cannot persist as a standalone memory.
+ */
+export function applyExtractionSpanMaterialization(
+  result: ExtractionResult,
+  turns: readonly SpanMaterializeTurn[],
+  mode: SpanMode,
+): ExtractionResult {
+  if (mode === "off") {
+    return { ...result, facts: stripUntrustedFactSpans(result.facts) };
+  }
+  let attempts = 0;
+  let fallbacks = 0;
+  let agreements = 0;
+  const facts = result.facts.flatMap((fact) => {
+    if (!factCarriesSpan(fact)) {
+      return mode === "on" ? [] : [fact];
+    }
+    attempts += 1;
+    const { fact: materialized, outcome, materialized: text } = materializeFactSpan(
+      fact,
+      turns,
+      mode,
+    );
+    if (outcome === "fallback") {
+      fallbacks += 1;
+    } else if (mode === "shadow" && text !== undefined) {
+      if (spanAgreesWithContent(text, fact.content)) {
+        agreements += 1;
+      }
+    }
+    return [materialized];
+  });
+  if (mode === "shadow") {
+    log.info(
+      `extraction span-mode shadow: ${agreements}/${attempts} span facts agree with generated content (${fallbacks} span validation fallbacks)`,
+    );
+  } else if (fallbacks > 0) {
+    log.info(
+      `extraction span-mode: ${fallbacks}/${attempts} span facts fell back to generated content`,
+    );
+  }
+  return { ...result, facts };
+}
+
+function stripSpan<T extends SpanMaterializeFact>(fact: T): T {
+  const { span: _span, ...rest } = fact;
+  return rest as T;
+}

package/src/extraction.ts

@@ -20,18 +20,8 @@ import {
   type ProactiveQuestionsResultParsed,
   DaySummaryResultSchema,
 } from "./schemas.js";
-import type {
-  BufferTurn,
-  ExtractionResult,
-  ConsolidationResult,
-  MemoryFile,
-  PluginConfig,
-  LlmTraceEvent,
-  GatewayConfig,
-  MemoryCategory,
-  DaySummaryResult as DaySummaryResultShape,
-  ExtractionFailureClass,
-} from "./types.js";
+import type { BufferTurn, ExtractionResult, ConsolidationResult, MemoryFile, PluginConfig, LlmTraceEvent, GatewayConfig, MemoryCategory, DaySummaryResult as DaySummaryResultShape, ExtractionFailureClass } from "./types.js";
+import type { ExtractedFactSpanRef } from "./extraction-span-config.js";
 import { ModelRegistry } from "./model-registry.js";
 import { extractJsonCandidates } from "./json-extract.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
@@ -53,13 +43,14 @@ import { AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT, clampAmbientCaptureConfidence }
 import {
   CONSOLIDATION_RESPONSE_SCHEMA,
   CUE_ANCHOR_PROMPT_INSTRUCTION,
-  EXTRACTION_RESPONSE_SHAPE,
+  extractionResponseShape,
   OUTPUT_LANGUAGE_POLICY,
   PROFILE_CONSOLIDATION_RESPONSE_SCHEMA,
   buildConsolidationSystemPrompt,
   buildExtractionInstructions,
   buildProfileConsolidationSystemPrompt,
   eventTimePromptInstruction,
+  spanModePromptSection,
 } from "./extraction-prompt.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import {
@@ -70,8 +61,15 @@ import {
   isPlainRecord,
 } from "./extraction-normalization.js";
 export { classifyExtractionThrownError, classifyFallbackParseFailure } from "./extraction-error-classification.js";
+import {
+  applyExtractionSpanMaterialization,
+  bindLocalExtractionPrompt,
+  buildSpanMaterializeTurns,
+  stripUntrustedFactSpans,
+  truncateLocalExtractionConversation,
+  type SpanMaterializeTurn,
+} from "./extraction-span-materialize.js";
 import { resolveLocalLlmCapabilities, resolveMemoryLifecycleCapabilities, resolvePipelineProcessingCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
-
 type ExtractionQuestion = ExtractionResult["questions"][number];
 type ExtractedFactResult = ExtractionResult["facts"][number];
 type ExtractedEntityResult = ExtractionResult["entities"][number];
@@ -113,6 +111,28 @@ function normalizeQuestion(question: ExtractionQuestion): ExtractionQuestion {
   };
 }
 
+function normalizeExtractedSpanRef(value: unknown): ExtractedFactSpanRef | undefined {
+  if (!isPlainRecord(value)) return undefined;
+  const { sourceMessageIndex, charStart, charEnd, frame, sourceHash, sourceLength } = value;
+  if (
+    typeof sourceMessageIndex !== "number" ||
+    typeof charStart !== "number" ||
+    typeof charEnd !== "number" ||
+    typeof frame !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    sourceMessageIndex,
+    charStart,
+    charEnd,
+    frame,
+    ...(typeof sourceHash === "string" && typeof sourceLength === "number"
+      ? { sourceHash, sourceLength }
+      : {}),
+  };
+}
+
 function normalizeFactKey(fact: Pick<ExtractedFactResult, "category" | "content">): string {
   return `${fact.category}:${fact.content.trim().toLowerCase()}`;
 }
@@ -206,6 +226,22 @@ export class ExtractionEngine {
     return !this.useGatewayModelSource && this.client !== null;
   }
 
+  /**
+   * Span-mode materialization (issue #2333 Phase B): sibling module, called
+   * after parse and before sanitize/grounding so downstream sees one content
+   * form. Offsets index the exact prompt turn texts and die at materialization.
+   */
+  private applySpanMaterialization(
+    result: ExtractionResult,
+    spanTurns: readonly SpanMaterializeTurn[],
+  ): ExtractionResult {
+    return applyExtractionSpanMaterialization(
+      result,
+      spanTurns,
+      this.config.extraction?.spanMode ?? "off",
+    );
+  }
+
   /**
    * Build FallbackLlmOptions with the configured gateway agent ID injected.
    */
@@ -328,6 +364,7 @@ export class ExtractionEngine {
               procedureSteps,
               reasoningTrace,
               quote: extractionText(f.quote),
+              span: normalizeExtractedSpanRef(f.span),
               eventTime: extractionText(f.eventTime) ?? extractionText(f.event_time),
             };
           })
@@ -628,7 +665,7 @@ export class ExtractionEngine {
       const ambient = ctx.ambientCapture === true;
       const proactiveAdditions = await this.answerProactiveQuestions(
         conversation, base, proactive, maxAdditional, ctx.sourceConnector, ambient, signal);
-      const sanitizedAdditions = this.sanitizeExtractionResult(proactiveAdditions, ctx.messageTimestamp);
+      const sanitizedAdditions = this.sanitizeExtractionResult({ ...proactiveAdditions, facts: stripUntrustedFactSpans(proactiveAdditions.facts) }, ctx.messageTimestamp);
       const groundedAdditions = applyGroundingWithConnector(this.config, sanitizedAdditions, ctx);
       if (!this.hasExtractionOutputs(groundedAdditions)) return base;
       return this.mergeProactiveExtractionPass(base, groundedAdditions, maxAdditional);
@@ -1102,6 +1139,7 @@ export class ExtractionEngine {
       ? resolvedConnector
       : undefined;
     const { conversation, renderedConversation } = renderExtractionConversation(boundedTurns, headerConnector(sourceConnector));
+    const spanTurns = buildSpanMaterializeTurns(boundedTurns.map((turn) => turn.content));
 
     const groundingSource = boundedTurns
       .map((turn) => turn.content)
@@ -1191,7 +1229,16 @@ export class ExtractionEngine {
           this.profiler.endSpan("local-llm", extractionTraceId);
           this.emit({ kind: "llm_end", traceId, model: this.config.localLlmModel, operation: "extraction", durationMs });
           log.debug(`extraction: used local LLM — ${localResult.facts.length} facts, ${localResult.entities.length} entities`);
-          const sanitized = this.sanitizeExtractionResult(localResult, messageTimestamp);
+          const localSpanTurns = bindLocalExtractionPrompt(
+            conversation,
+            boundedTurns,
+            this.modelRegistry.calculateContextSizes(
+              this.config.localLlmModel,
+              this.config.localLlmMaxContext,
+            ).maxInputChars,
+            renderedConversation,
+          ).spanTurns;
+          const sanitized = this.sanitizeExtractionResult(this.applySpanMaterialization(localResult, localSpanTurns), messageTimestamp);
           const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
           const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
           return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
@@ -1240,7 +1287,7 @@ export class ExtractionEngine {
           this.profiler.endSpan("direct-client", extractionTraceId);
           this.emit({ kind: "llm_end", traceId, model: this.config.model, operation: "extraction", durationMs });
           log.debug(`extraction: used direct client (${this.config.model}) — ${directResult.facts.length} facts, ${directResult.entities.length} entities`);
-          const sanitized = this.sanitizeExtractionResult(directResult, messageTimestamp);
+          const sanitized = this.sanitizeExtractionResult(this.applySpanMaterialization(directResult, spanTurns), messageTimestamp);
           const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
           const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
           return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
@@ -1303,7 +1350,7 @@ export class ExtractionEngine {
           role: "system" as const,
           content:
             buildExtractionInstructions(this.config, existingEntities, ambientCapture) +
-            `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${EXTRACTION_RESPONSE_SHAPE}`,
+            `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${extractionResponseShape(this.config.extraction?.spanMode ?? "off")}`,
         },
         { role: "user" as const, content: conversation },
       ];
@@ -1338,7 +1385,7 @@ export class ExtractionEngine {
           `extracted ${result.facts.length} facts, ${result.entities.length} entities, ${(result.questions ?? []).length} questions via fallback (${detailed.modelUsed})`,
         );
         const normalized = this.normalizeExtractionResultPayload(result);
-        const sanitized = this.sanitizeExtractionResult(normalized, messageTimestamp);
+        const sanitized = this.sanitizeExtractionResult(this.applySpanMaterialization(normalized, spanTurns), messageTimestamp);
         const grounded = applyGroundingWithConnector(this.config, sanitized, groundingContext);
         const finalResult = await this.applyProactiveQuestionPass(conversation, grounded, groundingContext, signal);
         return this.finalizeExtractionResult(finalResult, boundedTurns, resolvedConnector, ambientCapture);
@@ -1414,9 +1461,7 @@ export class ExtractionEngine {
     log.debug(`Model context: ${contextSizes.description}`);
 
     const maxConversationChars = contextSizes.maxInputChars;
-    const truncatedConversation = conversation.length > maxConversationChars
-      ? conversation.slice(0, maxConversationChars) + "\n\n[truncated]"
-      : conversation;
+    const truncatedConversation = truncateLocalExtractionConversation(conversation, maxConversationChars);
 
     const localPrompt = `You are a memory extraction system. Extract durable, reusable memories from this conversation.
 
@@ -1449,9 +1494,9 @@ ${CUE_ANCHOR_PROMPT_INSTRUCTION}\n- Include at most five durable relationships.$
 - Each fact must include a quote copied verbatim from one contiguous conversation span.` : ""}${lifecycleCaps.extractionScopeClassification ? `
 - Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge. Tool, command, or CLI-flag instructions tied to one agent are "project" (the same tool name can mean different things across agents); when keeping one, begin the fact with a leading "In <agent>," clause naming that agent.` : ""}${this.config.subjectClassification?.enabled === true ? `
 - Set each fact subject to "user" when it models the person (preferences, relationships, biography, moments, commitments about their life) or "agent" when it is reusable operating knowledge (procedures, principles, tool-usage lessons, debugging strategies, environment facts with no personal content).` : ""}${ambientCapture ? AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT : ""}
-${eventTimePromptInstruction(this.config)}
+${eventTimePromptInstruction(this.config)}${spanModePromptSection(this.config.extraction?.spanMode ?? "off")}
 Return only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:
-${EXTRACTION_RESPONSE_SHAPE}
+${extractionResponseShape(this.config.extraction?.spanMode ?? "off")}
 
 Conversation:
 ${truncatedConversation}`;
@@ -1542,7 +1587,7 @@ ${truncatedConversation}`;
             role: "system",
             content:
               buildExtractionInstructions(this.config, existingEntities, ambientCapture) +
-              `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${EXTRACTION_RESPONSE_SHAPE}`,
+              `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${extractionResponseShape(this.config.extraction?.spanMode ?? "off")}`,
           },
           { role: "user", content: conversation },
         ],

package/src/reconcile/manifest.test.ts

@@ -5,7 +5,7 @@ import { computeLegacyContentHash } from "../content-hash.js";
 import { attachCitation, formatCitation } from "../source-attribution.js";
 import { parseFrontmatter } from "../storage.js";
 import { ContentHashIndex } from "../storage/content-hash-index.js";
-import { type ReconcileManifest, buildReconcileManifest, collapseActiveFactDuplicates } from "./manifest.js";
+import { type ReconcileManifest, buildReconcileManifest, citationTemplateFingerprint, collapseActiveFactDuplicates, peerManifestRevision } from "./manifest.js";
 import { planReconciliation } from "./plan.js";
 
 const fileHash = (content: string): string => createHash("sha256").update(content).digest("hex");
@@ -29,6 +29,16 @@ function memoryFile(options: {
   ].join("\n");
 }
 
+test("peer manifest revision includes the citation-template fingerprint", () => {
+  const fallback = peerManifestRevision();
+  const custom = peerManifestRevision("{{source}}");
+  assert.match(fallback, new RegExp(`(?:^|;)citation=${citationTemplateFingerprint(undefined)}(?:;|$)`));
+  assert.match(custom, new RegExp(`(?:^|;)citation=${citationTemplateFingerprint("{{source}}")}(?:;|$)`));
+  assert.notEqual(fallback, custom);
+  assert.notEqual(custom, peerManifestRevision("{{title}}"));
+  assert.equal(peerManifestRevision("{{source}}"), custom);
+});
+
 test("reconcile manifest keeps file identity separate from canonical semantic identity", async () => {
   const content = "The deployment uses a durable queue with an enrichment suffix.";
   const semanticHash = ContentHashIndex.computeHash("The deployment uses a durable queue.");

package/src/reconcile/manifest.ts

@@ -30,6 +30,18 @@ export const CONTENT_HASH_NORMALIZER_VERSION = 4;
  */
 export const IDENTITY_RESOLUTION_VERSION = 2;
 
+/**
+ * Identity of the manifest-affecting implementation this peer builds
+ * STREAMED manifests with. Advertised via offline-sync capabilities so the
+ * client can key peer-side plan caches on it: a peer that upgrades its
+ * normalization logic or citation template without rewriting stored files
+ * keeps the same file hashes, and only this revision invalidates the stale
+ * cached identities (#2803 / #2956 review).
+ */
+export function peerManifestRevision(citationTemplate?: string): string {
+  return `schema=${RECONCILE_MANIFEST_SCHEMA_VERSION};normalizer=${CONTENT_HASH_NORMALIZER_VERSION};identity=${IDENTITY_RESOLUTION_VERSION};citation=${citationTemplateFingerprint(citationTemplate)}`;
+}
+
 export interface ReconcileMemoryIdentity {
   id: string;
   category: string;

package/src/schemas.ts

@@ -129,6 +129,20 @@ export const ExtractedFactSchema = z.object({
     .describe(
       'For category "procedure" only: ordered steps (intent per step). At least two steps; include explicit trigger phrasing in content (e.g. "When you deploy…").',
     ),
+  span: z
+    .object({
+      sourceMessageIndex: z.number(),
+      charStart: z.number(),
+      charEnd: z.number(),
+      frame: z.string(),
+      sourceHash: z.string().optional().nullable(),
+      sourceLength: z.number().optional().nullable(),
+    })
+    .optional()
+    .nullable()
+    .describe(
+      'Span-mode only (issue #2333): offsets of a verbatim supporting span in the numbered conversation segment. Messages are numbered in order starting at 0; charStart/charEnd index that message\'s text in a [charStart, charEnd) interval (end-exclusive). "frame" is at most 15 words that make the span self-contained (resolve pronouns, name the subject). Optional sourceHash/sourceLength bind the span to the exact prompt text. When span-mode requests spans, omit the full "content" restatement and let the frame plus span carry the fact.',
+    ),
   reasoningTrace: z
     .object({
       steps: z

package/src/source-agent-qualifier.ts

@@ -60,7 +60,11 @@ export function applyGroundingWithConnector(
   ctx: ExtractionGroundingContext,
 ): ExtractionResult {
   const caps = resolvePipelineProcessingCapabilities(config);
-  const options = { sourceGrounding: caps.sourceGrounding, anchorTemporalExpressions: caps.delinearize };
+  const options = {
+    sourceGrounding: caps.sourceGrounding,
+    anchorTemporalExpressions: caps.delinearize,
+    spanMode: config.extraction?.spanMode ?? "off",
+  };
   const known = buildKnownConnectors(ctx.sourceConnector);
   // Scope-forcing is decoupled from strip/restore (runs without a trusted
   // connector) but gated on the capability: flag off = byte-identical pre-#2183.

package/src/testing/subjects/extraction-lifecycle.test.ts

@@ -73,6 +73,7 @@ function namespacedConfig(memoryDir: string): PluginConfig {
       { name: "alice", readPrincipals: ["alice"], writePrincipals: ["alice"] },
       { name: "bob", readPrincipals: ["bob"], writePrincipals: ["bob"] },
     ],
+    extraction: { spanMode: "on" },
   });
 }
 
@@ -98,6 +99,7 @@ function rememberedBindingConfig(memoryDir: string): PluginConfig {
     principalFromSessionKeyMode: "map",
     principalFromSessionKeyRules: [{ match: REMEMBERED_SESSION, principal: "alice" }],
     namespacePolicies: [{ name: "alice", readPrincipals: ["alice"], writePrincipals: ["alice"] }],
+    extraction: { spanMode: "on" },
   });
 }
 
@@ -107,6 +109,20 @@ const NAMESPACE_ROWS: Partial<Record<MatrixRowId, true>> = {
   "provider-rebinding": true,
 };
 
+function spanBearingResult(turns: BufferTurn[]) {
+  const result = singleFactResult(turns.map((turn) => turn.content).join(" | "));
+  const first = turns[0]?.content ?? "";
+  const fact = result.facts[0];
+  if (fact === undefined) return result;
+  fact.span = {
+    sourceMessageIndex: 0,
+    charStart: 0,
+    charEnd: first.length,
+    frame: "Lifecycle probe",
+  };
+  return result;
+}
+
 async function assertHarmonicEpisode(memoryDir: string, sessionKey?: string): Promise<void> {
   const status = await harmonicNodeStoreStatus(memoryDir);
   assert.equal(status.nodes.invalid, 0, "harmonic persistence must write only valid abstraction nodes");
@@ -133,10 +149,15 @@ const subject: LifecycleSubject<ExtractionLifecycleState> = {
               ? makeHarmonicLifecycleConfig(memoryDir, {
                   extractionDedupeEnabled: true,
                   extractionDedupeWindowMs: 60_000,
+                  // Issue #2333: materialization sits inside the extraction
+                  // path, so the dedupe/replay row must hold with spanMode on.
+                  extraction: { spanMode: "on" },
                 })
-              : makeHarmonicLifecycleConfig(memoryDir);
+              // Issue #2333: extraction-lifecycle rows (compaction flush,
+              // before_reset, …) must pass with `extraction.spanMode: "on"`.
+              : makeHarmonicLifecycleConfig(memoryDir, { extraction: { spanMode: "on" } });
       primary = new Orchestrator(cfg);
-      const calls = stubExtraction(primary, (turns) => singleFactResult(turns.map((turn) => turn.content).join(" | ")));
+      const calls = stubExtraction(primary, (turns) => spanBearingResult(turns));
       return { memoryDir, cfg, orchestrators: [primary], calls };
     } catch (err) {
       // Transactional setup: a partial build must not leak the orchestrator or temp dir.
@@ -216,11 +237,9 @@ const subject: LifecycleSubject<ExtractionLifecycleState> = {
         );
         await primary.destroy();
         state.orchestrators.length = 0;
-        const second = new Orchestrator(makeHarmonicLifecycleConfig(state.memoryDir));
+        const second = new Orchestrator(makeHarmonicLifecycleConfig(state.memoryDir, { extraction: { spanMode: "on" } }));
         state.orchestrators.push(second);
-        state.restartCalls = stubExtraction(second, (turns) =>
-          singleFactResult(turns.map((turn) => turn.content).join(" | "))
-        );
+        state.restartCalls = stubExtraction(second, (turns) => spanBearingResult(turns));
         // Drain the buffer that survived the restart (state/buffer.json).
         await second.flushSession("session-parked", { reason: "session_end" });
         return;
@@ -250,7 +269,7 @@ const subject: LifecycleSubject<ExtractionLifecycleState> = {
         // Rewire the seam: extraction succeeds but trips the abort mid-flight.
         state.abortFlushCalls = stubExtraction(primary, (turns) => {
           controller.abort();
-          return singleFactResult(turns.map((turn) => turn.content).join(" | "));
+          return spanBearingResult(turns);
         });
         let abortRejected = false;
         await primary
@@ -267,9 +286,7 @@ const subject: LifecycleSubject<ExtractionLifecycleState> = {
         // A fresh, non-aborted flush must find the turn still buffered AND must
         // itself succeed — swallowing its failure would let a recovery-flush
         // regression pass vacuously (the extraction call still bumps the count).
-        state.secondFlushCalls = stubExtraction(primary, (turns) =>
-          singleFactResult(turns.map((turn) => turn.content).join(" | "))
-        );
+        state.secondFlushCalls = stubExtraction(primary, (turns) => spanBearingResult(turns));
         await primary.flushSession("session-reset", { reason: "before_reset" });
         // The recovery flush must PERSIST the preserved turn as a fact...
         state.recoveredFactCount = (

package/src/types.ts

@@ -4,6 +4,7 @@ import type { LocationConfig } from "./location/types.js";
 import type { OkfConfig } from "./okf/config.js";
 import type { ActivityConfig } from "./activity/types.js";
 import type { WearablesConfig } from "./wearables/types.js";
+import type { ExtractionSpanConfig, ExtractedFactSpanRef } from "./extraction-span-config.js";
 import type { ExtractionLivenessConfig } from "./extraction-liveness.js";
 import type { ReplicaPeersConfig } from "./replica-peers-config.js";
 import type { ExternalWikiRoot } from "./external-wiki-config.js";
@@ -1231,6 +1232,8 @@ export interface PluginConfig
   dreamsPhases: DreamsPhasesConfig;
   procedural: ProceduralConfig;
   extractionLiveness: ExtractionLivenessConfig;
+  /** Span-mode extraction (#2333 Phase B, bench-gated). Default off. */
+  extraction: ExtractionSpanConfig;
   replicaPeers: ReplicaPeersConfig;
   converge: ConvergeConfig;
   /** Claim-level provenance spans (#1575); see `ProvenanceConfig` for defaults. */
@@ -3232,17 +3235,11 @@ export interface ExtractedFact {
    * content-hash dedup (rule 23 / checklist §13).
    */
   quote?: string;
-  /**
-   * Transient requireSpans signal (#1575 PR 2): quote unlocatable while
-   * `provenance.requireSpans` is on. Persist path routes the fact to
-   * `pending_review`. Stripped before persistence — never reaches frontmatter.
-   */
+  /** Transient requireSpans signal (#1575 PR 2): quote unlocatable while
+   * `provenance.requireSpans` is on → routed to `pending_review`; stripped pre-persist. */
   requireSpansPending?: boolean;
   promptedByQuestion?: string;
-  /**
-   * Project- vs global-scoped; emitted when `extractionScopeClassificationEnabled`.
-   * Defaults to "project" with a coding context active, else "global".
-   */
+  /** Project- vs global-scoped; emitted when `extractionScopeClassificationEnabled`; defaults "project" with a coding context. */
   scope?: MemoryScope;
   /** Extractor-assigned subject, present only when subjectClassification.enabled (issue #2372). */
   subject?: MemorySubject;
@@ -3278,6 +3275,9 @@ export interface ExtractedFact {
    * `observedAt`, then to the batch anchor, when absent.
    */
   sourceTurnTimestamp?: string;
+  /** Transient span-mode reference (issue #2333): offsets into the exact
+   * per-turn text the extraction model saw; stripped at materialization. */
+  span?: ExtractedFactSpanRef | null;
 }
 
 export interface ExtractedReasoningTraceStep {