@remnic/core 9.3.701 → 9.3.702

package/src/recall-pipeline-parity.test.ts

@@ -0,0 +1,288 @@
+// Issue #1539 PRs 3–6 — migration parity guards.
+//
+// Each recall pipeline (targeted-fact, response-guidance, explicit-cue,
+// event-order) was migrated from an inline dedup/score/threshold/sort block to
+// a thin config object handed to `unifiedDedupeAndRank` (the spine). The
+// per-tier test files (targeted-fact-recall.test.ts etc.) are the end-to-end
+// characterization — they exercise buildXxxRecallSection on full fixtures. This
+// file is the SEAM guard: it pins, per pipeline, that the declared config shape
+// routes through the spine with the correct divergence (sort direction,
+// content-dedup on/off, rank threshold, transform-applied-to-output-but-not-
+// score). If a future refactor flips one of these silently, the matching test
+// here fails BEFORE the end-to-end suites have a chance to mask it.
+//
+// These tests do NOT re-implement the per-tier scorers — those are genuinely
+// per-tier policy and stay in the per-tier test files. Here we use small
+// representative scorers that exercise the divergence dimension each pipeline
+// declares on the spine.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { EvidencePackItem } from "./evidence-pack.js";
+import { unifiedDedupeAndRank } from "./recall-pipeline-stages.js";
+
+function item(
+  turnIndex: number,
+  content: string,
+  overrides: Partial<EvidencePackItem> = {},
+): EvidencePackItem {
+  return {
+    id: `s1:${turnIndex}`,
+    sessionId: "s1",
+    turnIndex,
+    role: "user",
+    content,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PR3 — targeted-fact shape: DESC, content-dedup, transform-applied-to-output,
+// score-on-original. No rank threshold.
+// ---------------------------------------------------------------------------
+
+test("parity targeted-fact: DESC ordering on score ties (latest turnIndex first)", () => {
+  const items = [
+    item(1, "early turn"),
+    item(5, "late turn"),
+    item(3, "middle turn"),
+  ];
+  // Constant scorer forces score ties so turnIndex DESC is the deciding key.
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 10,
+  });
+  assert.equal(ranked[0].turnIndex, 5);
+  assert.equal(ranked[1].turnIndex, 3);
+  assert.equal(ranked[2].turnIndex, 1);
+});
+
+test("parity targeted-fact: content transform applied to output, NOT to scorer input", () => {
+  const items = [item(2, "Revenue was $500")];
+  // A scorer that reads ORIGINAL content must NOT see the appended cue suffix.
+  let scorerObserved = "";
+  unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: (original) => {
+      scorerObserved = original.content;
+      return 1;
+    },
+    transformContent: (content) => `${content} [CUE]`,
+  });
+  assert.equal(scorerObserved, "Revenue was $500");
+  // ...and the output content carries the transform:
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 1,
+    transformContent: (content) => `${content} [CUE]`,
+  });
+  assert.equal(ranked[0].content, "Revenue was $500 [CUE]");
+});
+
+test("parity targeted-fact: duplicate normalized content collapses (default dedupByContent)", () => {
+  const items = [
+    item(1, "Same content"),
+    item(2, "same   content"), // whitespace/case differences normalize equal
+    item(3, "Distinct"),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 10,
+  });
+  assert.equal(ranked.length, 2);
+  // First-seen wins: turnIndex 1 is kept, turnIndex 2 (same normalized content)
+  // is dropped. Output is then sorted DESC by turnIndex on the score tie.
+  assert.deepEqual(
+    ranked.map((r) => r.turnIndex),
+    [3, 1],
+  );
+});
+
+// ---------------------------------------------------------------------------
+// PR4 — response-guidance shape: same as targeted-fact (DESC + content-dedup +
+// transform + score-on-original) but with guidance-cue transform. Pin the shape
+// matches; the guidance-specific transform is exercised end-to-end in
+// response-guidance-recall.test.ts.
+// ---------------------------------------------------------------------------
+
+test("parity response-guidance: DESC ordering on score ties", () => {
+  const items = [
+    item(2, "guidance b"),
+    item(7, "guidance a"),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 5,
+  });
+  assert.equal(ranked[0].turnIndex, 7);
+  assert.equal(ranked[1].turnIndex, 2);
+});
+
+test("parity response-guidance: rank primary key always DESC regardless of turnIndex", () => {
+  const items = [
+    item(1, "low rank high turnIndex"),
+    item(9, "high rank low turnIndex"),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: (original) => (original.content.includes("high rank") ? 20 : 1),
+  });
+  assert.equal(ranked[0].turnIndex, 9);
+  assert.equal(ranked[1].turnIndex, 1);
+});
+
+// ---------------------------------------------------------------------------
+// PR5 — explicit-cue shape: the pipeline that OPTS OUT of scoring AND sorting.
+// Its deliberate value ordering (turn references -> content cues -> lexical
+// cues, by evidence type then read-key priority) is the highest-value design
+// choice — preserved verbatim via preserveInsertionOrder + constant scorer +
+// id-only dedup (the spine call is behavior-idempotent; items are already
+// deduped by seenTurns during collection).
+// ---------------------------------------------------------------------------
+
+test("parity explicit-cue: preserveInsertionOrder keeps collection order intact", () => {
+  // Insertion order is 2, 4, 1. A default sort would reorder to 4, 2, 1.
+  // explicit-cue must NOT reorder — the collection order IS the value order.
+  const items = [
+    item(2, "explicit cue b", { id: "s:2" }),
+    item(4, "explicit cue a", { id: "s:4" }),
+    item(1, "explicit cue c", { id: "s:1" }),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 0,
+    dedupByContent: false,
+    preserveInsertionOrder: true,
+  });
+  assert.deepEqual(
+    ranked.map((r) => r.turnIndex),
+    [2, 4, 1],
+  );
+});
+
+test("parity explicit-cue: id-only dedup (dedupByContent false) keeps distinct turns", () => {
+  const items = [
+    item(1, "same body", { id: "s:1" }),
+    item(2, "same body", { id: "s:2" }),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 0,
+    dedupByContent: false,
+    preserveInsertionOrder: true,
+  });
+  assert.equal(ranked.length, 2);
+});
+
+// ---------------------------------------------------------------------------
+// PR6 — event-order shape: ASC ordering, NO content-dedup (dedupByContent:false
+// keeps distinct turns even when cue-appended bodies match), declared
+// rankThreshold of 6, transform applied to output.
+// ---------------------------------------------------------------------------
+
+test("parity event-order: ASC ordering on rank ties (earliest turnIndex first)", () => {
+  const items = [
+    item(5, "turn five"),
+    item(1, "turn one"),
+    item(3, "turn three"),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 10,
+    turnIndexSortDirection: "asc",
+  });
+  assert.deepEqual(
+    ranked.map((r) => r.turnIndex),
+    [1, 3, 5],
+  );
+});
+
+test("parity event-order: dedupByContent false keeps distinct turns with identical bodies", () => {
+  // Two distinct turns (different ids/turnIndex) but identical cue-appended body.
+  // Event-order MUST keep both — they are legitimate repeated turns in a
+  // chronological transcript. This is the cursor-bugbot a4299851 regression guard.
+  const items = [
+    item(1, "the user asked again"),
+    item(4, "the user asked again"),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 10,
+    dedupByContent: false,
+    turnIndexSortDirection: "asc",
+  });
+  assert.equal(ranked.length, 2);
+  assert.deepEqual(
+    ranked.map((r) => r.turnIndex),
+    [1, 4],
+  );
+});
+
+test("parity event-order: declared rankThreshold (6) drops below-threshold items", () => {
+  const items = [
+    item(1, "strong", { id: "s:1" }),
+    item(2, "weak", { id: "s:2" }),
+    item(3, "borderline", { id: "s:3" }),
+  ];
+  const ranked = unifiedDedupeAndRank(items, {
+    query: "",
+    intents: [],
+    scoreEvidence: (original) => {
+      if (original.content === "strong") return 10;
+      if (original.content === "borderline") return 6; // exactly threshold -> kept (>=)
+      return 5; // weak -> dropped
+    },
+    rankThreshold: 6,
+    turnIndexSortDirection: "asc",
+  });
+  // rank is ALWAYS DESC primary: strong (10) outranks borderline (6).
+  // turnIndex ASC only breaks ties within the same rank.
+  assert.deepEqual(
+    ranked.map((r) => r.content),
+    ["strong", "borderline"],
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Cross-pipeline divergence guard: the SAME corpus produces DIFFERENT orderings
+// under DESC vs ASC config. This is the core #1539 defect class — copy-pasting
+// the comparator into a chronological pipeline silently inverts ordering.
+// ---------------------------------------------------------------------------
+
+test("parity divergence: DESC vs ASC configs on the same corpus invert turnIndex ordering", () => {
+  const corpus = [
+    item(1, "a", { id: "x:1" }),
+    item(2, "b", { id: "x:2" }),
+    item(3, "c", { id: "x:3" }),
+  ];
+  const desc = unifiedDedupeAndRank(corpus, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 10,
+  });
+  const asc = unifiedDedupeAndRank(corpus, {
+    query: "",
+    intents: [],
+    scoreEvidence: () => 10,
+    turnIndexSortDirection: "asc",
+  });
+  assert.deepEqual(
+    desc.map((r) => r.turnIndex),
+    [3, 2, 1],
+  );
+  assert.deepEqual(
+    asc.map((r) => r.turnIndex),
+    [1, 2, 3],
+  );
+});

package/src/recall-pipeline-stages.test.ts

@@ -267,3 +267,46 @@ test("unifiedDedupeAndRank: dedupByContent true (default) still collapses identi
   });
   assert.equal(resultExplicit.length, 1, "explicit dedupByContent: true collapses identical content");
 });
+
+test("unifiedDedupeAndRank: preserveInsertionOrder skips the sort stage (explicit-cue shape)", () => {
+  // Insertion order is turn-index 3, 1, 2. A DESC sort would reorder to 3, 2, 1.
+  // preserveInsertionOrder must keep the original (post-dedup) order: 3, 1, 2.
+  const items: EvidencePackItem[] = [
+    item(3, "turn ref", { id: "s:3" }),
+    item(1, "content cue", { id: "s:1" }),
+    item(2, "lexical hit", { id: "s:2" }),
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: () => 0, // explicit-cue does not score
+    dedupByContent: false, // explicit-cue dedupes by id only (seenTurns)
+    preserveInsertionOrder: true,
+  });
+  assert.deepEqual(
+    result.map((r) => r.id),
+    ["s:3", "s:1", "s:2"],
+    "insertion order is preserved — no sort applied",
+  );
+});
+
+test("unifiedDedupeAndRank: preserveInsertionOrder still applies threshold filter", () => {
+  const items: EvidencePackItem[] = [
+    item(1, "strong", { id: "s:1" }),
+    item(2, "weak", { id: "s:2" }),
+    item(3, "medium", { id: "s:3" }),
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: (original) => (original.content === "strong" ? 10 : original.content === "medium" ? 5 : 1),
+    rankThreshold: 5,
+    dedupByContent: false,
+    preserveInsertionOrder: true,
+  });
+  // threshold drops "weak" (rank 1); insertion order of survivors preserved.
+  assert.deepEqual(
+    result.map((r) => r.id),
+    ["s:1", "s:3"],
+  );
+});

package/src/recall-pipeline-stages.ts

@@ -125,6 +125,21 @@ export interface UnifiedRankConfig<TIntent> {
    * The rank primary key is ALWAYS DESC regardless of this setting.
    */
   turnIndexSortDirection?: TurnIndexSortDirection;
+  /**
+   * When `true`, skip the sort stage entirely and return items in their
+   * post-dedup insertion order (first-seen first). Used by explicit-cue,
+   * whose deliberate value ordering — turn references → content cues →
+   * lexical cues, gathered by evidence TYPE then read-key priority — is the
+   * pipeline's highest-value design choice. A rank-based sort would invert
+   * it (turn references are deliberately UNSCORED while lexical hits carry
+   * numeric scores; sorting by score would demote turn references below
+   * weak lexical hits — cursor[bot] / codex P2 on #1505).
+   *
+   * Score and threshold-filter still apply when declared; only the sort is
+   * skipped. The constant scorer (`scoreEvidence: () => 0`) makes the
+   * no-scoring policy explicit alongside this flag.
+   */
+  preserveInsertionOrder?: boolean;
 }
 
 /**
@@ -232,6 +247,13 @@ export function unifiedDedupeAndRank<TIntent>(
   // turnIndex direction is configurable: DESC (relevance) or ASC (chronology).
   // The tertiary tiebreaker follows the direction:
   //   DESC → score DESC; ASC → content.localeCompare.
+  //
+  // explicit-cue opts out of sorting entirely (preserveInsertionOrder) — its
+  // deliberate value ordering is the collection order (turn references →
+  // content cues → lexical cues), and a rank-based sort would invert it.
+  if (config.preserveInsertionOrder) {
+    return filtered;
+  }
   return filtered.sort(makeComparator(direction));
 }
 

package/src/response-guidance-recall.ts

@@ -5,6 +5,11 @@ import {
   resolveLcmReadSessionIds,
 } from "./lcm-fallback-read.js";
 
+import {
+  unifiedDedupeAndRank,
+  type RankedEvidenceItem,
+} from "./recall-pipeline-stages.js";
+
 export interface ResponseGuidanceRecallOptions {
   engine: ExplicitCueRecallEngine | null | undefined;
   sessionId?: string;
@@ -24,10 +29,6 @@ export interface ResponseGuidanceRecallOptions {
   forceGeneric?: boolean;
 }
 
-interface RankedGuidanceItem extends EvidencePackItem {
-  rank: number;
-}
-
 type GuidanceIntent =
   | "dates"
   | "editing"
@@ -341,42 +342,37 @@ async function collectGuidanceScanItems(
   return items;
 }
 
+/**
+ * Issue #1539 PR4: response-guidance now routes dedup/score/threshold/sort through
+ * the unified spine (`unifiedDedupeAndRank`). The divergence that lived inline
+ * here — append-guidance-cues content transform (two-arg: content + intents),
+ * relevance scoring on ORIGINAL content, default DESC turn-index ordering with
+ * -1 sentinel for missing turns — is now declared config on the spine. The score
+ * and appendGuidanceCues helpers stay in this module because they are genuinely
+ * per-tier policy; only the duplicated dedup/sort/threshold machinery moved out.
+ *
+ * Behavior is byte-for-byte identical to the inline implementation it replaces
+ * (the spine was extracted to match it exactly; see recall-pipeline-stages.ts).
+ * The response-guidance-recall.test.ts suite is the characterization.
+ *
+ * Note: response-guidance (like the pre-migration code) dedups on the TRANSFORMED
+ * (cue-appended) content, not the original — this matches the spine's default
+ * (transform-then-dedup) exactly. No divergence from prior behavior.
+ */
 function rankAndDedupeGuidanceItems(
   items: EvidencePackItem[],
   query: string,
   intents: readonly GuidanceIntent[],
-): RankedGuidanceItem[] {
-  const seenIds = new Set<string>();
-  const seenContent = new Set<string>();
-  const ranked: RankedGuidanceItem[] = [];
-
-  for (const item of items) {
-    const id = item.id ?? (
-      item.sessionId && typeof item.turnIndex === "number"
-        ? `${item.sessionId}:${item.turnIndex}`
-        : undefined
-    );
-    if (id && seenIds.has(id)) continue;
-
-    const enhancedContent = appendGuidanceCues(item.content, intents);
-    const contentKey = enhancedContent.toLowerCase().replace(/\s+/g, " ").trim();
-    if (seenContent.has(contentKey)) continue;
-
-    if (id) seenIds.add(id);
-    seenContent.add(contentKey);
-    ranked.push({
-      ...item,
-      content: enhancedContent,
-      rank: scoreGuidanceEvidence(item, query, intents),
-    });
-  }
-
-  return ranked.sort((left, right) => {
-    if (right.rank !== left.rank) return right.rank - left.rank;
-    const leftTurn = typeof left.turnIndex === "number" ? left.turnIndex : -1;
-    const rightTurn = typeof right.turnIndex === "number" ? right.turnIndex : -1;
-    if (rightTurn !== leftTurn) return rightTurn - leftTurn;
-    return (right.score ?? 0) - (left.score ?? 0);
+): RankedEvidenceItem[] {
+  // The spine's config.intents is typed TIntent[] (readability contract — it is
+  // never mutated). Cast the readonly array through; safe because the spine only
+  // forwards intents to the score/transform callbacks.
+  const mutableIntents = intents as GuidanceIntent[];
+  return unifiedDedupeAndRank(items, {
+    query,
+    intents: mutableIntents,
+    scoreEvidence: (item, q, intentArr) => scoreGuidanceEvidence(item, q, intentArr),
+    transformContent: (content, intentArr) => appendGuidanceCues(content, intentArr),
   });
 }
 

package/src/schemas.ts

@@ -93,6 +93,13 @@ export const ExtractedFactSchema = z.object({
     .describe(
       'Scope classification: "global" for cross-project knowledge (framework bugs, library behavior, API patterns, user preferences, tool configs, general coding patterns); "project" for project-specific knowledge (file paths, env configs, deployment details, project workarounds). Defaults to "project" when a coding context is active.',
     ),
+  quote: z
+    .string()
+    .optional()
+    .nullable()
+    .describe(
+      "The EXACT verbatim words from the conversation that support this fact. Copy a contiguous span from a single speaker turn (not a paraphrase). Cap at ~300 characters. This is the grounding evidence for downstream faithfulness verification (issue #1575).",
+    ),
   structuredAttributes: z
     .record(z.string(), z.string())
     .optional()

package/src/storage.ts

@@ -88,6 +88,7 @@ import type {
   ScoredEntity,
   TopicScore,
   FileHygieneConfig,
+  ProvenanceSource,
 } from "./types.js";
 import { confidenceTier, SPECULATIVE_TTL_DAYS } from "./types.js";
 import {
@@ -3608,6 +3609,14 @@ export class StorageManager {
        * can consume it. Absent = gate was off or fact predates #1576.
        */
       faithfulness?: import("./types.js").FaithfulnessFrontmatter;
+      /**
+       * Claim-level provenance spans (issue #1575 PR 2). When provided,
+       * persisted to frontmatter so downstream readers (memory_get, x-ray,
+       * faithfulness gate #1576) can consume them. Absent = fact predates
+       * #1575 or provenance was disabled.
+       */
+      sources?: ProvenanceSource[];
+      provenance?: "verified" | "unverified" | "none";
     } = {},
   ): Promise<string> {
     await this.ensureDirectories();
@@ -3681,6 +3690,14 @@ export class StorageManager {
     if (options.faithfulness !== undefined) {
       fm.faithfulness = options.faithfulness;
     }
+    // Claim-level provenance (issue #1575 PR 2). Wire through to frontmatter
+    // so verified spans survive extraction → storage → memory_get end-to-end.
+    if (options.sources !== undefined) {
+      fm.sources = options.sources;
+    }
+    if (options.provenance !== undefined) {
+      fm.provenance = options.provenance;
+    }
 
     // Append structured attributes as searchable suffix so QMD indexes them.
     // normalizeAttributePairs sorts and lowercases keys so the enriched content
@@ -7338,6 +7355,10 @@ export class StorageManager {
       status?: import("./types.js").MemoryStatus;
       /** Faithfulness gate verdict (issue #1576), propagated from the parent fact. */
       faithfulness?: import("./types.js").FaithfulnessFrontmatter;
+      /** Claim-level provenance spans (issue #1575 PR 2), propagated from the parent fact so a chunk surfaced independently (memory_get/x-ray) preserves them (chatgpt-codex-connector thread Ocvmo). */
+      sources?: ProvenanceSource[];
+      /** Coarse provenance tag (issue #1575 PR 2), propagated from the parent. */
+      provenance?: "verified" | "unverified" | "none";
     } = {},
   ): Promise<string> {
     await this.ensureDirectories();
@@ -7369,6 +7390,8 @@ export class StorageManager {
       valid_at: validAt,
       ...(options.status ? { status: options.status } : {}),
       ...(options.faithfulness ? { faithfulness: options.faithfulness } : {}),
+      ...(options.sources ? { sources: options.sources } : {}),
+      ...(options.provenance ? { provenance: options.provenance } : {}),
     };
 
     const sanitized = sanitizeMemoryContent(content);

package/src/targeted-fact-recall.ts

@@ -9,6 +9,11 @@ import {
   resolveLcmReadSessionIds,
 } from "./lcm-fallback-read.js";
 
+import {
+  unifiedDedupeAndRank,
+  type RankedEvidenceItem,
+} from "./recall-pipeline-stages.js";
+
 export interface TargetedFactRecallOptions {
   engine: ExplicitCueRecallEngine | null | undefined;
   sessionId?: string;
@@ -27,10 +32,6 @@ export interface TargetedFactRecallOptions {
   title?: string;
 }
 
-interface RankedEvidenceItem extends EvidencePackItem {
-  rank: number;
-}
-
 const DEFAULT_MAX_SEARCH_RESULTS = 48;
 const DEFAULT_SCAN_WINDOW_TURNS = 8;
 const DEFAULT_SCAN_WINDOW_TOKENS = 12_000;
@@ -210,38 +211,30 @@ async function collectTargetedFactScanItems(
   return items;
 }
 
+/**
+ * Issue #1539 PR3: targeted-fact now routes dedup/score/threshold/sort through
+ * the unified spine (`unifiedDedupeAndRank`). The divergence that lived inline
+ * here — append-normalized-numeric-cues content transform, relevance scoring on
+ * ORIGINAL content, default DESC turn-index ordering with -1 sentinel for
+ * missing turns — is now declared config on the spine. The score and
+ * appendNormalizedNumericCues helpers stay in this module because they are
+ * genuinely per-tier policy; only the duplicated dedup/sort/threshold machinery
+ * moved out.
+ *
+ * Behavior is byte-for-byte identical to the inline implementation it replaces
+ * (the spine was extracted to match it exactly; see recall-pipeline-stages.ts).
+ * The targeted-fact-recall.test.ts suite (42 cases, incl. the search/scan
+ * ordering and summary insertion tests) is the characterization.
+ */
 function rankAndDedupeTargetedFactItems(
   items: EvidencePackItem[],
   query: string,
 ): RankedEvidenceItem[] {
-  const seenIds = new Set<string>();
-  const seenContent = new Set<string>();
-  const ranked: RankedEvidenceItem[] = [];
-
-  for (const item of items) {
-    const id = item.id ?? (
-      item.sessionId && typeof item.turnIndex === "number"
-        ? `${item.sessionId}:${item.turnIndex}`
-        : undefined
-    );
-    if (id && seenIds.has(id)) continue;
-    const contentKey = item.content.toLowerCase().replace(/\s+/g, " ").trim();
-    if (seenContent.has(contentKey)) continue;
-    if (id) seenIds.add(id);
-    seenContent.add(contentKey);
-    ranked.push({
-      ...item,
-      content: appendNormalizedNumericCues(item.content),
-      rank: scoreTargetedFactEvidence(item, query),
-    });
-  }
-
-  return ranked.sort((left, right) => {
-    if (right.rank !== left.rank) return right.rank - left.rank;
-    const leftTurn = typeof left.turnIndex === "number" ? left.turnIndex : -1;
-    const rightTurn = typeof right.turnIndex === "number" ? right.turnIndex : -1;
-    if (rightTurn !== leftTurn) return rightTurn - leftTurn;
-    return (right.score ?? 0) - (left.score ?? 0);
+  return unifiedDedupeAndRank(items, {
+    query,
+    intents: [],
+    scoreEvidence: (item, q) => scoreTargetedFactEvidence(item, q),
+    transformContent: (content) => appendNormalizedNumericCues(content),
   });
 }
 

package/src/types.ts

@@ -2852,6 +2852,30 @@ export interface ExtractedFact {
    * "no verified span" and skip gracefully.
    */
   sources?: ProvenanceSource[];
+  /**
+   * Coarse provenance strength tag (issue #1575 PR 2). Set by the extraction
+   * validator: "verified" when the quote was located in source turns,
+   * "unverified" when the quote survived but no offsets were recoverable.
+   * Absent when `provenance.enabled` is false or no quote was provided —
+   * readers treat absent as "none" (rule 34 spirit).
+   */
+  provenance?: "verified" | "unverified" | "none";
+  /**
+   * Transient LLM-provided supporting quote (issue #1575 PR 2). Consumed by
+   * the post-parse validator to build `sources`, then stripped before the
+   * fact reaches persistence. NEVER included in content-hash dedup (rule 23 /
+   * checklist §13). Absent on facts that have already passed the validator.
+   */
+  quote?: string;
+  /**
+   * Transient requireSpans signal (issue #1575 PR 2). Set by the provenance
+   * validator (`ProvenanceBuildResult.requireSpansPending`) when
+   * `provenance.requireSpans` is enabled and the quote could not be located
+   * in any source turn. Read by the persist path to route the fact to
+   * `pending_review` instead of `active`. Stripped before persistence —
+   * it never reaches frontmatter (chatgpt-codex-connector thread 4xB).
+   */
+  requireSpansPending?: boolean;
   promptedByQuestion?: string;
   /**
    * Whether this fact is project-scoped or globally applicable.