@remnic/core 9.69.36 → 9.69.37

package/dist/who-knows.d.ts

@@ -1,6 +1,6 @@
-export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-Cl_x57xR.js';
-import './types-yDgWDkrJ.js';
-import './orchestrator-Cf3G-3Ed.js';
+export { bA as WHO_KNOWS_AUTHORSHIP_BONUS, bB as WHO_KNOWS_DEFAULT_LIMIT, bC as WHO_KNOWS_MAX_EVIDENCE, bD as WHO_KNOWS_MAX_LIMIT, bE as WHO_KNOWS_MCP_TOOLS, bF as WhoKnowsEntity, bG as WhoKnowsEvidence, bH as WhoKnowsHit, bI as WhoKnowsHttpOutcome, W as WhoKnowsResult, bJ as WhoKnowsStorage, bT as computeWhoKnows, bZ as handleWhoKnowsHttpQuery, c2 as loadWhoKnowsEntities, c9 as tokenizeTopic, ca as validateWhoKnowsInput } from './access-service-DwHC7lcV.js';
+import './types-48sPkWB0.js';
+import './orchestrator-DBUX-aAM.js';
 import './recall-state.js';
 import './utils/serialize-mutations.js';
 import './search/port.js';
@@ -20,7 +20,7 @@ import './semantic-merge-config.js';
 import './types-continuity.js';
 import './included-memories.js';
 import './briefing.js';
-import './storage-Ca0MbTfm.js';
+import './storage-Cbll3-Tk.js';
 import './corpus-read-cancellation.js';
 import './artifact-search.js';
 import './active-context-transform.js';
@@ -43,8 +43,8 @@ import './resolve-provider-secret.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
-import './maintenance-ag1gYztC.js';
-import './catalog-Bq1AxZwF.js';
+import './maintenance-DItyBwTC.js';
+import './catalog-Cl4H8N89.js';
 import './namespaces/search.js';
 import './compounding/engine.js';
 import './shared-context/manager.js';
@@ -54,7 +54,7 @@ import './utility-runtime.js';
 import './tier-routing.js';
 import './lifecycle.js';
 import './orchestration/compression-guideline-coordinator.js';
-import './semantic-consolidation-C83DVakV.js';
+import './semantic-consolidation-D7sJocll.js';
 import './connectors/codex-materialize.js';
 import './logger.js';
 import './embedding-fallback.js';
@@ -76,17 +76,17 @@ import './conversation-index/chunker.js';
 import './conversation-index/backend.js';
 import './faiss-adapter-BHecI1fF.js';
 import './runtime/child-process.js';
-import './dependency-propagation-delivery-DLiAtj25.js';
+import './dependency-propagation-delivery-Bua2ApHV.js';
 import './namespaces/storage.js';
 import './threading.js';
-import './scope-profiles-nxTKvjE-.js';
+import './scope-profiles-BIJMsd0B.js';
 import './graph-DRkl22KE.js';
 import './graph-write-lock.js';
 import './recall-xray.js';
 import './memory-provenance.js';
 import './user-model.js';
 import './recall-context-composition.js';
-import './generic-recall-paths-DbitKJI5.js';
+import './generic-recall-paths-DJBADojG.js';
 import './live-connectors-runner.js';
 import './framework-CNDn2164.js';
 import './relevance.js';
@@ -94,7 +94,7 @@ import './negative.js';
 import './session-observer-state.js';
 import './semantic-BalR6EXU.js';
 import './replay/types.js';
-import './service-q-xtOoAr.js';
+import './service-fwgEngUj.js';
 import './extraction-judge.js';
 import './lcm/engine.js';
 import './lcm/archive.js';
@@ -116,7 +116,7 @@ import './recall-audit.js';
 import './types-B1VHaf2w.js';
 import './transfer/capsule-import.js';
 import './transfer/types.js';
-import './access-namespace-preflight-D8qri11P.js';
+import './access-namespace-preflight-CV5cHujx.js';
 import './access-token-capabilities.js';
 import 'node:async_hooks';
 import './recall-explain-renderer.js';

package/dist/who-knows.js

@@ -9,20 +9,20 @@ import {
   loadWhoKnowsEntities,
   tokenizeTopic,
   validateWhoKnowsInput
-} from "./chunk-3FJKJ5UZ.js";
-import "./chunk-5VAF4ID4.js";
-import "./chunk-46WM6JX2.js";
+} from "./chunk-X7BCM2NA.js";
+import "./chunk-ZEPVWLCN.js";
 import "./chunk-UHVXE24Y.js";
+import "./chunk-46WM6JX2.js";
 import "./chunk-D5F7TKMH.js";
-import "./chunk-Y63ZFP4X.js";
-import "./chunk-JRWW7GM6.js";
+import "./chunk-7RKBPXY6.js";
+import "./chunk-Q6D7EUSQ.js";
+import "./chunk-BD7JTBYP.js";
+import "./chunk-OB3XMWX5.js";
 import "./chunk-CYEPCZN5.js";
 import "./chunk-TNSCIPBQ.js";
 import "./chunk-YQNNHLCG.js";
-import "./chunk-6KTXE6A3.js";
-import "./chunk-BD7JTBYP.js";
-import "./chunk-OB3XMWX5.js";
 import "./chunk-4O6WRBGE.js";
+import "./chunk-6KTXE6A3.js";
 import "./chunk-GUMZC2BO.js";
 import "./chunk-TFA6HPOA.js";
 import "./chunk-F4TWWUMP.js";
@@ -30,7 +30,7 @@ import "./chunk-72A4L5JJ.js";
 import "./chunk-A7Q43EUZ.js";
 import "./chunk-S2V7RUCL.js";
 import "./chunk-PCEYGOSL.js";
-import "./chunk-4MDKNUV4.js";
+import "./chunk-RN3MVLW3.js";
 import "./chunk-S2HLHAZ4.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-MRPOZBJC.js";

package/dist/write-envelope.d.ts

@@ -1,4 +1,4 @@
-import { u as MemoryCategory, N as MemorySubject } from './types-yDgWDkrJ.js';
+import { u as MemoryCategory, N as MemorySubject } from './types-48sPkWB0.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.69.36",
+  "version": "9.69.37",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -1035,6 +1035,46 @@
       "remnic-source": "./src/extraction.ts",
       "import": "./dist/extraction.js"
     },
+    "./extraction-span-fallback": {
+      "types": "./dist/extraction-span-fallback.d.ts",
+      "remnic-source": "./src/extraction-span-fallback.ts",
+      "import": "./dist/extraction-span-fallback.js"
+    },
+    "./extraction-span-fallback.js": {
+      "types": "./dist/extraction-span-fallback.d.ts",
+      "remnic-source": "./src/extraction-span-fallback.ts",
+      "import": "./dist/extraction-span-fallback.js"
+    },
+    "./extraction-span-gate": {
+      "types": "./dist/extraction-span-gate.d.ts",
+      "remnic-source": "./src/extraction-span-gate.ts",
+      "import": "./dist/extraction-span-gate.js"
+    },
+    "./extraction-span-gate.js": {
+      "types": "./dist/extraction-span-gate.d.ts",
+      "remnic-source": "./src/extraction-span-gate.ts",
+      "import": "./dist/extraction-span-gate.js"
+    },
+    "./extraction-span-source-hash": {
+      "types": "./dist/extraction-span-source-hash.d.ts",
+      "remnic-source": "./src/extraction-span-source-hash.ts",
+      "import": "./dist/extraction-span-source-hash.js"
+    },
+    "./extraction-span-source-hash.js": {
+      "types": "./dist/extraction-span-source-hash.d.ts",
+      "remnic-source": "./src/extraction-span-source-hash.ts",
+      "import": "./dist/extraction-span-source-hash.js"
+    },
+    "./extraction-span-tokens": {
+      "types": "./dist/extraction-span-tokens.d.ts",
+      "remnic-source": "./src/extraction-span-tokens.ts",
+      "import": "./dist/extraction-span-tokens.js"
+    },
+    "./extraction-span-tokens.js": {
+      "types": "./dist/extraction-span-tokens.d.ts",
+      "remnic-source": "./src/extraction-span-tokens.ts",
+      "import": "./dist/extraction-span-tokens.js"
+    },
     "./fallback-llm": {
       "types": "./dist/fallback-llm.d.ts",
       "remnic-source": "./src/fallback-llm.ts",
@@ -3257,7 +3297,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.69.36"
+    "@remnic/coding-graph": "^9.69.37"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-http.test.ts

@@ -10,6 +10,7 @@ import {
   type RemnicAdminControls,
   type RemnicAdminDashboardStatus,
 } from "./access-http.js";
+import { peerManifestRevision } from "./reconcile/manifest.js";
 import {
   EngramAccessInputError,
   type EngramAccessRecallRequest,
@@ -1528,11 +1529,48 @@ test("HTTP offline sync capabilities advertise manifest streaming", async () =>
       { headers: { authorization: "Bearer test-token" } },
     );
     assert.equal(response.status, 200);
-    assert.deepEqual(await response.json(), {
-      version: 1,
-      convergenceFinalization: true,
-      manifestStream: true,
-    });
+    const payload = (await response.json()) as {
+      version?: unknown;
+      convergenceFinalization?: unknown;
+      manifestStream?: unknown;
+      manifestRevision?: unknown;
+    };
+    assert.deepEqual(
+      {
+        version: payload.version,
+        convergenceFinalization: payload.convergenceFinalization,
+        manifestStream: payload.manifestStream,
+      },
+      {
+        version: 1,
+        convergenceFinalization: true,
+        manifestStream: true,
+      }
+    );
+    assert.equal(payload.manifestRevision, peerManifestRevision());
+  } finally {
+    await server.stop();
+  }
+});
+
+test("HTTP offline sync capabilities include the configured citation fingerprint", async () => {
+  const citationTemplate = "{{source}} — {{title}}";
+  const server = new EngramAccessHttpServer({
+    service: { configRef: { inlineSourceAttributionFormat: citationTemplate } } as EngramAccessService,
+    port: 0,
+    authToken: "test-token",
+    adminConsoleEnabled: false,
+  });
+  const status = await server.start();
+  try {
+    const response = await fetch(
+      `http://127.0.0.1:${status.port}/remnic/v1/offline-sync/capabilities`,
+      { headers: { authorization: "Bearer test-token" } },
+    );
+    assert.equal(response.status, 200);
+    const payload = (await response.json()) as { manifestRevision?: unknown };
+    assert.equal(payload.manifestRevision, peerManifestRevision(citationTemplate));
+    assert.notEqual(payload.manifestRevision, peerManifestRevision());
   } finally {
     await server.stop();
   }

package/src/access-http.ts

@@ -23,6 +23,7 @@ import {
   respondOfflineManifestStream,
   respondOfflineSnapshotStream,
 } from "./access-http-offline-stream.js";
+import { peerManifestRevision } from "./reconcile/manifest.js";
 import { nonEmptyQueryParam, optionalNamespaceKindQueryParam, optionalQueryString, positiveIntQueryParam } from "./access-http-query.js";
 import { CorrectionContractError } from "./correction/correction-contract.js";
 import { respondWearablesErrorGlue } from "./wearables/http-glue.js"; import { respondMeetingsList, respondMeetingsGet, respondMeetingsBuild } from "./meetings/http-glue.js"; import { respondLocationStatus, respondLocationCheck, respondLocationSync, respondLocationBackfill, respondLocationDay } from "./location/http-glue.js"; import { respondStandup } from "./standup/http-glue.js"; import { respondDeepRecall } from "./deep-recall-http-glue.js";
@@ -1203,6 +1204,7 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
         version: 1,
         convergenceFinalization: true,
         manifestStream: true,
+        manifestRevision: peerManifestRevision(this.service.configRef?.inlineSourceAttributionFormat),
       });
       return;
     }

package/src/config.ts

@@ -40,7 +40,7 @@ import { coerceBool, coerceBooleanLike, coerceInstallExtension, coerceNumber } f
 import { parseSubjectRuntimeConfig } from "./subject-config.js";
 import { parseRecallStateViews } from "./recall-state-view.js";
 import { parseRecallConcurrencyConfig } from "./recall-concurrency-config.js";
-import { parseExtractionLivenessConfig } from "./extraction-liveness.js";
+import { parseExtractionFields } from "./extraction-span-config.js";
 import { parseReplicaPeersConfig } from "./replica-peers-config.js";
 import { parseDependencyPropagationConfig } from "./dependency-propagation-config.js";
 import { parseProceduralMaintenanceConfig } from "./procedural/maintenance-config.js";
@@ -2332,7 +2332,7 @@ export function parseConfig(
     dreaming,
     dreamsPhases,
     procedural,
-    extractionLiveness: parseExtractionLivenessConfig(cfg),
+    ...parseExtractionFields(cfg),
     replicaPeers: parseReplicaPeersConfig(cfg),
     converge: parseConvergeConfig(cfg.converge),
     wearables,

package/src/extraction-prompt.ts

@@ -45,9 +45,19 @@ export const EXTRACTION_RESPONSE_SHAPE = `{
   "episodeTitle": "<six-to-eight word conversation segment title>",
   "relationships": [{"source": "<normalized-name>", "target": "<normalized-name>", "label": "<source-grounded relationship>"}]
 }`;
+export function extractionResponseShape(spanMode: "off" | "shadow" | "on" = "off"): string {
+  if (spanMode === "off") return EXTRACTION_RESPONSE_SHAPE;
+  return EXTRACTION_RESPONSE_SHAPE.replace(
+    `"eventTime": "<optional source temporal expression>"`,
+    `"eventTime": "<optional source temporal expression>",
+    "span": {"sourceMessageIndex": <message number>, "charStart": <number>, "charEnd": <number>, "frame": "<at most 15 words>"}`,
+  );
+}
 export const EXTRACTION_RESPONSE_PLACEHOLDERS: Record<string, true> = {};
-for (const placeholder of EXTRACTION_RESPONSE_SHAPE.match(/<[^<>\r\n]+>/g) ?? []) {
-  EXTRACTION_RESPONSE_PLACEHOLDERS[placeholder] = true;
+for (const shape of [EXTRACTION_RESPONSE_SHAPE, extractionResponseShape("on")]) {
+  for (const placeholder of shape.match(/<[^<>\r\n]+>/g) ?? []) {
+    EXTRACTION_RESPONSE_PLACEHOLDERS[placeholder] = true;
+  }
 }
 export const CUE_ANCHOR_PROMPT_INSTRUCTION = `- For each fact, emit at most 3 "cueAnchors".
 - Each cue anchor value must be a source-grounded search hook of at most 120 characters, in the form "<main entity or topic> <key aspect>".
@@ -76,6 +86,30 @@ export function eventTimePromptInstruction(config: PluginConfig): string {
 When a fact states when it became or stopped being true, copy that explicit temporal expression verbatim into "eventTime". Omit "eventTime" when no such expression appears; never infer dates.`;
 }
 
+/**
+ * Span-mode extraction instructions (issue #2333 Phase B). Empty when the
+ * mode is off (byte-identical prompt). The offset convention mirrors the
+ * Phase A bench: messages numbered in order from 0, offsets index the
+ * message's own text (after the `[role] ` tag), [charStart, charEnd)
+ * end-exclusive.
+ */
+export function spanModePromptSection(spanMode: "off" | "shadow" | "on"): string {
+  if (spanMode === "off") return "";
+  const requestBoth = spanMode === "shadow";
+  return `
+Span mode (numbered-message offsets):
+- Conversation messages are numbered in order starting at 0 (the "[role] text" blocks).
+- For each fact, return "span": {"sourceMessageIndex": <message number>, "charStart": <number>, "charEnd": <number>, "frame": "<at most 15 words>"} pointing at the verbatim supporting words in that message's text (the text after the "] "). Offsets are [charStart, charEnd), end-exclusive, counting from the first character of the message text.
+- "frame" is at most 15 generated words that make the span self-contained: resolve pronouns to names, name the subject (e.g., frame "Maya's relocation:" + span "moved to Seattle last spring…").${
+    requestBoth
+      ? `
+- This run is in SHADOW mode: ALSO include the full standalone "content" restatement exactly as you would normally write it, in addition to "span".`
+      : `
+- Set "content" to the frame text (the short ≤15-word frame) — do not restate the full fact; the span plus frame carry it.`
+  }
+- Invalid spans fall back to the frame, so keep the frame informative.`;
+}
+
 /**
  * Build extraction instructions shared between local and cloud LLM.
  *
@@ -170,7 +204,7 @@ When you see something that matches a known entity, use THAT name exactly. Only
 `
     : ""
 }
-${eventTimePromptInstruction(config)}
+${eventTimePromptInstruction(config)}${spanModePromptSection(config.extraction?.spanMode ?? "off")}
 Also extract relationships between entities mentioned in the conversation.
 - Format: {source: "entity-name", target: "entity-name", label: "relationship description"}
 - Max 5 relationships per extraction

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

@@ -29,6 +29,7 @@ import {
 export interface ExtractionSourceGroundingOptions {
   sourceGrounding: boolean;
   anchorTemporalExpressions: boolean;
+  spanMode?: "off" | "shadow" | "on";
 }
 
 export function applyExtractionSourceGrounding(
@@ -60,6 +61,7 @@ export function applyExtractionSourceGrounding(
     anchorSource(assertionSourceText),
     anchoredRoleSources,
     options.anchorTemporalExpressions ? anchorSource : undefined,
+    options.spanMode ?? "off",
   );
 }
 
@@ -653,18 +655,51 @@ function filterGroundedFact(
   assertionSource: string | undefined,
   roleAssertionSources: ExtractionGroundingRoleSources | undefined,
   eventTimeNormalizer: ((eventTime: string) => string) | undefined,
+  spanMode: "off" | "shadow" | "on" = "off",
 ): ExtractionResult["facts"][number] | undefined {
-  const factContext = selectGroundingContext(
+  // Span-materialized content (issue #2333) is "frame: verbatim slice". The
+  // frame is generated deixis, so full-content gating would drop a verbatim
+  // fact. Only on-mode facts whose content is that materialized shape may
+  // fall back to the slice. Shadow stays zero-diff with off.
+  const quote = typeof fact.quote === "string" ? fact.quote : "";
+  const materializedPrefix = quote.length > 0 && fact.content.endsWith(quote) && fact.content !== quote
+    ? fact.content.slice(0, fact.content.length - quote.length)
+    : "";
+  const embeddedQuote =
+    spanMode === "on"
+    && quote.trim().length > 0
+    && (materializedPrefix.endsWith(": ") || /[:—-]\s$/.test(materializedPrefix))
+      ? quote
+      : undefined;
+  const contentContext = selectGroundingContext(
     fact.content,
     resolveGroundingContext(fact.content, source, assertionSource, roleAssertionSources),
   );
-  if (!isGroundedCandidate(
-    fact.content,
-    factContext.source,
-    factContext.assertionSource,
-    false,
-    factContext.allowRoleNormalization,
-  )) return undefined;
+  let gateContent = fact.content;
+  let factContext = contentContext;
+  if (
+    !isGroundedCandidate(
+      fact.content,
+      contentContext.source,
+      contentContext.assertionSource,
+      false,
+      contentContext.allowRoleNormalization,
+    )
+  ) {
+    if (embeddedQuote === undefined) return undefined;
+    gateContent = embeddedQuote;
+    factContext = selectGroundingContext(
+      gateContent,
+      resolveGroundingContext(gateContent, source, assertionSource, roleAssertionSources),
+    );
+    if (!isGroundedCandidate(
+      gateContent,
+      factContext.source,
+      factContext.assertionSource,
+      false,
+      factContext.allowRoleNormalization,
+    )) return undefined;
+  }
   const factEventTime = fact.eventTime;
   const groundedFactEventTime = factEventTime === undefined
     ? undefined
@@ -672,7 +707,7 @@ function filterGroundedFact(
   const factSupportingSentences = sourceSentences(factContext.assertionSource ?? factContext.source).filter(
     (sentence) =>
     isGroundedCandidate(
-      fact.content,
+      gateContent,
       sentence,
       undefined,
       false,
@@ -1068,6 +1103,7 @@ export function filterExtractionResultBySource(
   assertionSource?: string,
   roleAssertionSources?: ExtractionGroundingRoleSources,
   eventTimeNormalizer?: (eventTime: string) => string,
+  spanMode: "off" | "shadow" | "on" = "off",
 ): ExtractionResult {
   if (source.trim().length === 0) {
     return {
@@ -1088,6 +1124,7 @@ export function filterExtractionResultBySource(
       assertionSource,
       roleAssertionSources,
       eventTimeNormalizer,
+      spanMode,
     );
     return grounded === undefined ? [] : [grounded];
   });

package/src/extraction-source-grounding.ts

@@ -99,6 +99,7 @@ export function filterExtractionResultBySource(
   assertionSource?: string,
   roleAssertionSources?: ExtractionGroundingRoleSources,
   eventTimeNormalizer?: (eventTime: string) => string,
+  spanMode: "off" | "shadow" | "on" = "off",
 ): ExtractionResult {
-  return filterGroundingRules(result, source, assertionSource, roleAssertionSources, eventTimeNormalizer);
+  return filterGroundingRules(result, source, assertionSource, roleAssertionSources, eventTimeNormalizer, spanMode);
 }

package/src/extraction-span-config.ts

@@ -0,0 +1,81 @@
+/**
+ * Span-mode extraction config + fact span-ref types (issue #2333 Phase B,
+ * bench-gated). Sibling module so config.ts and types.ts stay under their
+ * structural ratchets (#1995); types.ts re-exports both.
+ *
+ * Default "off"; an unrecognized value is REJECTED, never defaulted
+ * (checklist #39) — silently ignoring it would run an unbenched extraction
+ * contract.
+ */
+
+import { z } from "zod";
+import { parseExtractionLivenessConfig } from "./extraction-liveness.js";
+
+export interface ExtractionSpanConfig {
+  /**
+   * - "off" (default): extraction generates content as before.
+   * - "shadow": request spans AND content; materialize + compare + log
+   *   agreement telemetry; persist the generated content (zero behavior
+   *   change).
+   * - "on": persist materialized frame+span content, falling back per fact
+   *   to generated content when the span fails validation.
+   */
+  spanMode: "off" | "shadow" | "on";
+}
+
+export interface ExtractedFactSpanRef {
+  /** Ordinal of the source turn in the extraction segment (0-based). */
+  sourceMessageIndex: number;
+  /** [charStart, charEnd) into the turn's exact in-memory text (UTF-16 code units). */
+  charStart: number;
+  charEnd: number;
+  /** ≤ 15 generated words making the span self-contained (resolves deixis). */
+  frame: string;
+  /** Optional prompt-source identity; when present it must match the captured stamp. */
+  sourceHash?: string;
+  sourceLength?: number;
+}
+
+export const EXTRACTION_SPAN_MODES = ["off", "shadow", "on"] as const;
+const extractionSpanBlockSchema = z.object({ spanMode: z.unknown().optional() }).strict();
+
+/** Span + liveness fields for parseConfig. One spread keeps config.ts at the ratchet. */
+export function parseExtractionFields(cfg: Record<string, unknown>) {
+  return {
+    extraction: parseExtractionSpanConfig(cfg.extraction),
+    extractionLiveness: parseExtractionLivenessConfig(cfg),
+  };
+}
+
+export function parseExtractionSpanConfig(raw: unknown): ExtractionSpanConfig {
+  if (raw === undefined) {
+    return { spanMode: "off" };
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      `extraction must be an object with optional spanMode (got ${JSON.stringify(raw)}). Omit the key for the default "off".`,
+    );
+  }
+  const block = raw as Record<string, unknown>;
+  const parsed = extractionSpanBlockSchema.safeParse(block);
+  if (!parsed.success) {
+    const unknownKeys = parsed.error.issues.flatMap((issue) =>
+      issue.code === "unrecognized_keys" ? issue.keys : []
+    );
+    throw new Error(
+      `extraction has unknown propert${unknownKeys.length === 1 ? "y" : "ies"}: ${unknownKeys.join(", ")}. Allowed: "spanMode".`,
+    );
+  }
+  const spanMode = block.spanMode;
+  if (spanMode === undefined) {
+    return { spanMode: "off" };
+  }
+  for (const mode of EXTRACTION_SPAN_MODES) {
+    if (spanMode === mode) {
+      return { spanMode: mode };
+    }
+  }
+  throw new Error(
+    `extraction.spanMode must be one of "off", "shadow", "on" (got ${JSON.stringify(spanMode)}). Omit the key for the default "off".`,
+  );
+}