@kontourai/survey 2.5.0 → 4.0.0

package/README.md

@@ -40,6 +40,10 @@ The Review Workbench rendering a real example queue — current vs proposed valu
 npm install @kontourai/survey @kontourai/surface
 ```
 
+Survey supports `@kontourai/surface` 2.13 and later 2.x, and 3.x, and CI tests
+the lowest 2.x and the newest 3.x. Install either major and your project and
+Survey share one Surface copy (`npm ls @kontourai/surface` shows one entry).
+
 Requires Node.js >=22. TypeScript >=5.0 is required to compile against
 Survey's published type declarations (`defineProductVocabulary`'s `const`
 type parameters are TS 5.0+ syntax) — JavaScript consumers are unaffected;
@@ -203,7 +207,8 @@ host app should read as itself.
 
 ## Review MCP
 
-Drive review-queue decisions from an MCP agent (Claude Desktop, Cursor, or any MCP host):
+Drive review-queue decisions from any MCP host. The official server runtime
+automatically supports MCP 2026-07-28 discovery and existing legacy clients:
 
 ```sh
 npx survey-review-mcp --session path/to/session.json

package/dist/examples/calibrated-auto-accept.d.ts

@@ -1,29 +1,36 @@
 /**
- * Worked example: wiring confidence calibration into a downstream consumer.
+ * Worked example: EXPERIMENTAL confidence calibration from review history.
  *
- * A consumer that owns human review outcomes can close the confidence loop in two
- * places, both shipped in @kontourai/survey (1.10.0):
+ * Calibration summarizes how often reviewers affirmed an extractor's proposals.
+ * Both outputs below are experimental descriptive statistics (#279), not
+ * validated probabilities or policy:
  *
- *   1. Ground the auto-accept threshold. `deriveCalibration` over a history of
- *      review outcomes yields `suggestedThreshold` — the lowest confidence at
- *      which the extractor's proposals were empirically affirmed often enough.
- *      Feed that number into a producer profile's `autoAcceptMinConfidence`
- *      (see `SchemaMappingOptions.autoAcceptMinConfidence` /
- *      `InquiryMappingOptions.minConfidence`) instead of hand-picking it.
+ *   1. `deriveCalibration` reports per-decile affirmation rates and, only when a
+ *      decile has enough samples AND a one-sided 95% Wilson lower bound on its
+ *      accuracy clears the target, a `suggestedThreshold`. A thin history gets
+ *      no threshold at all. Do not feed `suggestedThreshold` into an auto-accept
+ *      policy (`autoAcceptMinConfidence` / `minConfidence`) as-is: it is not an
+ *      evaluated gate.
  *
- *   2. Produce calibrated conclusion confidence. Pass the same calibration
- *      `metrics` into `buildSurveyTrustBundle({ calibration: { metrics } })` and
- *      affirmed claims carry `conclusionConfidence.value` = the empirical
- *      affirmation rate for their extractor/field.
+ *   2. `buildSurveyTrustBundle({ calibration: { experimentalConclusionValue:
+ *      true, metrics } })` sets `conclusionConfidence.value` on affirmed claims
+ *      to their extractor/field GROUP's affirmation rate. Every affirmed claim in
+ *      the group gets the same base rate whatever its own confidence, so it is
+ *      not a per-claim probability. Without the experimental flag no value is set.
  *
- * Calibration is advisory (ADR 0003 §4): the threshold is a suggestion the
- * operator wires into policy, and the produced value never changes claim status.
+ * Calibration is advisory (ADR 0003 §4): it never changes claim status.
  *
  * Run: `node dist/examples/calibrated-auto-accept.js`
  */
 export interface CalibratedAutoAcceptResult {
+    /** Threshold from a 60-samples-per-decile history (enough evidence). */
     readonly suggestedThreshold: number | undefined;
+    /** Threshold from a 10-samples-per-decile history (withheld: too thin). */
+    readonly sparseHistoryThreshold: number | undefined;
     readonly groupAccuracy: number | undefined;
+    /** Values with the experimental opt-in: the group base rate on each claim. */
     readonly producedValues: ReadonlyArray<number | undefined>;
+    /** Values with `calibration` enabled but no experimental opt-in: none. */
+    readonly defaultValues: ReadonlyArray<number | undefined>;
 }
 export declare function runCalibratedAutoAccept(): CalibratedAutoAcceptResult;

package/dist/examples/calibrated-auto-accept.js

@@ -1,23 +1,24 @@
 /**
- * Worked example: wiring confidence calibration into a downstream consumer.
+ * Worked example: EXPERIMENTAL confidence calibration from review history.
  *
- * A consumer that owns human review outcomes can close the confidence loop in two
- * places, both shipped in @kontourai/survey (1.10.0):
+ * Calibration summarizes how often reviewers affirmed an extractor's proposals.
+ * Both outputs below are experimental descriptive statistics (#279), not
+ * validated probabilities or policy:
  *
- *   1. Ground the auto-accept threshold. `deriveCalibration` over a history of
- *      review outcomes yields `suggestedThreshold` — the lowest confidence at
- *      which the extractor's proposals were empirically affirmed often enough.
- *      Feed that number into a producer profile's `autoAcceptMinConfidence`
- *      (see `SchemaMappingOptions.autoAcceptMinConfidence` /
- *      `InquiryMappingOptions.minConfidence`) instead of hand-picking it.
+ *   1. `deriveCalibration` reports per-decile affirmation rates and, only when a
+ *      decile has enough samples AND a one-sided 95% Wilson lower bound on its
+ *      accuracy clears the target, a `suggestedThreshold`. A thin history gets
+ *      no threshold at all. Do not feed `suggestedThreshold` into an auto-accept
+ *      policy (`autoAcceptMinConfidence` / `minConfidence`) as-is: it is not an
+ *      evaluated gate.
  *
- *   2. Produce calibrated conclusion confidence. Pass the same calibration
- *      `metrics` into `buildSurveyTrustBundle({ calibration: { metrics } })` and
- *      affirmed claims carry `conclusionConfidence.value` = the empirical
- *      affirmation rate for their extractor/field.
+ *   2. `buildSurveyTrustBundle({ calibration: { experimentalConclusionValue:
+ *      true, metrics } })` sets `conclusionConfidence.value` on affirmed claims
+ *      to their extractor/field GROUP's affirmation rate. Every affirmed claim in
+ *      the group gets the same base rate whatever its own confidence, so it is
+ *      not a per-claim probability. Without the experimental flag no value is set.
  *
- * Calibration is advisory (ADR 0003 §4): the threshold is a suggestion the
- * operator wires into policy, and the produced value never changes claim status.
+ * Calibration is advisory (ADR 0003 §4): it never changes claim status.
  *
  * Run: `node dist/examples/calibrated-auto-accept.js`
  */
@@ -31,15 +32,15 @@ const BATCH_AT = "2026-07-01T00:00:00.000Z";
  * almost always affirmed by reviewers and low-confidence ones were mostly
  * rejected — the pattern that makes an empirical threshold meaningful.
  */
-function buildReviewHistory() {
+function buildReviewHistory(samplesPerDecile) {
     const extractions = [];
     const candidateSets = [];
     const reviewOutcomes = [];
-    let n = 0;
+    let seq = 0;
     const addSamples = (count, confidence, affirmed) => {
         for (let i = 0; i < count; i += 1) {
-            const key = `h-${n}`;
-            n += 1;
+            const key = `h-${seq}`;
+            seq += 1;
             extractions.push({
                 id: `${key}-ext`,
                 sourceId: `${key}-src`,
@@ -67,33 +68,34 @@ function buildReviewHistory() {
             });
         }
     };
-    addSamples(10, 0.95, 10); // top decile: all affirmed
-    addSamples(10, 0.85, 10); // 0.8–0.9: all affirmed
-    addSamples(10, 0.75, 5); // 0.7–0.8: half affirmed → below target, ends the run
-    addSamples(10, 0.55, 1); // 0.5–0.6: mostly rejected
+    const n = samplesPerDecile;
+    addSamples(n, 0.95, n); // top decile: all affirmed
+    addSamples(n, 0.85, n - 1); // 0.8–0.9: all but one affirmed
+    addSamples(n, 0.75, Math.round(n / 2)); // 0.7–0.8: half affirmed → ends the run
+    addSamples(n, 0.55, Math.round(n / 10)); // 0.5–0.6: mostly rejected
     return { reviewOutcomes, candidateSets, extractions };
 }
 export function runCalibratedAutoAccept() {
     // (1) Derive the empirical calibration curve over the review history.
-    const metrics = deriveCalibration(buildReviewHistory(), {
-        targetAccuracy: 0.9, // the accuracy the auto-accept threshold must clear
-        minBinSamples: 5, // a decile needs this many samples to ground the threshold
-    });
+    const options = { targetAccuracy: 0.9 }; // default 30-sample floor per decile
+    const metrics = deriveCalibration(buildReviewHistory(60), options);
     const suggestedThreshold = metrics.overall.suggestedThreshold;
+    const sparseHistoryThreshold = deriveCalibration(buildReviewHistory(10), options).overall.suggestedThreshold;
     const group = metrics.byExtractorField.find((g) => g.extractor === EXTRACTOR && g.field === FIELD);
-    // This is the number you feed into your producer profile's auto-accept policy:
-    //   surveySchemaMapping(context, extractor, { autoAcceptMinConfidence: suggestedThreshold })
-    // Proposals at/above it were empirically affirmed often enough to auto-accept.
-    // (2) Produce calibrated conclusion confidence on a new batch of affirmed claims.
+    // (2) Attach the group affirmation rate to a new batch of affirmed claims.
     const input = new SurveyInputBuilder({ source: "example-consumer:calibrated", generatedAt: BATCH_AT })
         .addObservation(affirmedObservation("entity-1", 0.85))
         .addObservation(affirmedObservation("entity-2", 0.92))
         .build();
     // Prefer metrics computed over history (not just this batch), so a claim's own
     // outcome does not feed its own value.
-    const bundle = buildSurveyTrustBundle(input, { calibration: { metrics, minSamples: 20 } });
+    const bundle = buildSurveyTrustBundle(input, {
+        calibration: { experimentalConclusionValue: true, metrics, minSamples: 20 },
+    });
     const producedValues = bundle.claims.map((c) => c.conclusionConfidence?.value);
-    return { suggestedThreshold, groupAccuracy: group?.empiricalAccuracy, producedValues };
+    const defaultValues = buildSurveyTrustBundle(input, { calibration: { metrics, minSamples: 20 } })
+        .claims.map((c) => c.conclusionConfidence?.value);
+    return { suggestedThreshold, sparseHistoryThreshold, groupAccuracy: group?.empiricalAccuracy, producedValues, defaultValues };
 }
 function affirmedObservation(subjectId, confidence) {
     return {
@@ -128,8 +130,10 @@ function affirmedObservation(subjectId, confidence) {
 if (process.argv[1]?.endsWith("calibrated-auto-accept.js")) {
     const result = runCalibratedAutoAccept();
     console.log(JSON.stringify({
-        suggestedAutoAcceptThreshold: result.suggestedThreshold,
-        empiricalAffirmationRate: result.groupAccuracy,
-        producedConclusionConfidenceValues: result.producedValues,
+        experimentalSuggestedThreshold: result.suggestedThreshold,
+        sparseHistorySuggestedThreshold: result.sparseHistoryThreshold,
+        groupAffirmationRate: result.groupAccuracy,
+        experimentalConclusionValues: result.producedValues,
+        valuesWithoutOptIn: result.defaultValues,
     }, null, 2));
 }

package/dist/src/agent-utterance.d.ts

@@ -16,7 +16,7 @@
  * has full provenance (excerpt, span, extractor name, confidence) and is
  * run through the Inquiry pipeline rather than treated as authoritative.
  */
-import type { DerivationRule, InquiryRecord, TrustBundle } from "@kontourai/surface";
+import type { DerivationRule, InquiryRecord, TrustBundle, TrustStatus } from "@kontourai/surface";
 import type { CanonicalClaimTarget } from "@kontourai/surface";
 import type { Candidate, CandidateSet, Extraction, RawSource, SurveyInput } from "./types.js";
 import type { InquiryMapping } from "./inquiry-mapping.js";
@@ -52,17 +52,63 @@ export interface UtteranceClaimExtractor {
     extract(utterance: string): ExtractedStatement[] | Promise<ExtractedStatement[]>;
 }
 /**
- * Badge values for each extracted statement, derived from the inquiry outcome
- * and the answer status.
- *
- * - "verified": inquiry matched/derived and answer status is "verified"
- * - "assumed": inquiry matched/derived and answer status is "assumed"
- * - "stale": inquiry matched/derived and answer status is "stale"
- * - "disputed": inquiry matched/derived and answer status is "disputed"
- * - "rejected": inquiry matched/derived and answer status is "rejected"
- * - "unsupported": inquiry outcome is "unsupported" (no mapping or no registered claim)
+ * Badge values for each extracted statement.
+ *
+ * A badge grades THE STATEMENT, not the target. It is a function of two
+ * things: the status of the bundle's answer for the statement's canonical
+ * target, and how the statement's own asserted value compares to that
+ * answer's value.
+ *
+ * The status half of the vocabulary is Surface's `TrustStatus` verbatim —
+ * Survey does not mint parallel status terms for concepts Surface (and the
+ * Hachure core record shapes it implements) already name. Only two badge
+ * values are Survey-side additions, because they describe the
+ * statement-vs-answer relation rather than a claim's standing:
+ *
+ * - "contradicted": the bundle has an answer that would otherwise read as
+ *   support ("verified", "assumed", "stale") and the statement asserts a
+ *   DIFFERENT value. Mirrors the Hachure `contradiction` transparency-gap
+ *   type (merge.md §7b): a value conflict is surfaced, never silently
+ *   resolved in favour of one side.
+ * - "unsupported": the inquiry did not resolve to an answer at all — no
+ *   mapping and no registered claim for the target. This value means "there
+ *   is nothing here to compare against", and nothing else: a claim that is
+ *   registered but merely awaiting review badges "proposed", and one with no
+ *   evidence badges "unknown".
+ *
+ * Every other badge is the answer's `TrustStatus` passed through unchanged,
+ * so there is no fall-through path that can report a real status under a
+ * label meaning "no such claim".
+ */
+export type StatementBadge = TrustStatus | "contradicted" | "unsupported";
+/**
+ * How a statement's asserted value compares to the bundle's answer value.
+ *
+ * - "agrees": both are comparable scalars and equivalent under
+ *   `assertionComparisonKey`.
+ * - "contradicts": both are comparable scalars and NOT equivalent.
+ * - "not-compared": no comparison was possible — the inquiry produced no
+ *   answer, or the extractor parsed no value out of the statement
+ *   (`ExtractedStatement.value` absent), or one side is not a scalar.
+ *   Never treated as agreement.
+ */
+export type StatementValueComparison = "agrees" | "contradicts" | "not-compared";
+/**
+ * How the Extraction's `text-span:` locator was resolved for a statement.
+ *
+ * - "span": the extractor supplied an explicit character span; the locator
+ *   points where the extractor said it does.
+ * - "excerpt-match": no span, but the excerpt was found verbatim in the
+ *   utterance; the locator points at that occurrence.
+ * - "unanchored-fallback": no span AND the excerpt does not occur in the
+ *   utterance. The locator is still well-formed (`text-span:0-<length>`) so
+ *   downstream producer discipline holds, but it is a length-shaped
+ *   placeholder anchored at offset 0 — it does NOT point at the excerpt, and
+ *   the text it spans is unrelated prose. Anything that resolves the locator
+ *   against the source MUST check this field first; a hallucinated excerpt
+ *   lands here.
  */
-export type StatementBadge = "verified" | "assumed" | "stale" | "disputed" | "rejected" | "unsupported";
+export type LocatorResolution = "span" | "excerpt-match" | "unanchored-fallback";
 export interface UtteranceStatement {
     excerpt: string;
     span?: {
@@ -70,6 +116,29 @@ export interface UtteranceStatement {
         end: number;
     };
     target: CanonicalClaimTarget;
+    /**
+     * The value the statement asserted, verbatim from the extractor
+     * (`ExtractedStatement.value`) — not normalized, not defaulted. Absent when
+     * the extractor parsed no value, which is exactly when `valueComparison`
+     * is "not-compared". This is the field a reader needs to see WHAT was
+     * compared against the bundle's answer.
+     */
+    assertedValue?: unknown;
+    /** How `assertedValue` compares to `inquiryRecord.answer?.value`. */
+    valueComparison: StatementValueComparison;
+    /** Human-readable account of the comparison, naming both sides. */
+    comparisonRationale: string;
+    /**
+     * The Survey provenance records this statement produced: its Extraction,
+     * its Candidate, and the per-target Candidate Set it belongs to. The
+     * Candidate Set carries the Candidate Conflict verdict and rationale when
+     * two statements in the SAME utterance disagree about one target
+     * (`candidateSet.status === "conflict"`), which is a different signal from
+     * `valueComparison` (statement vs bundle).
+     */
+    records: UtteranceStatementRecords;
+    /** How this statement's Extraction locator was resolved. */
+    locatorResolution: LocatorResolution;
     inquiryRecord: InquiryRecord;
     badge: StatementBadge;
 }
@@ -107,6 +176,13 @@ interface UtteranceRecordsResult {
     records: UtteranceStatementRecords[];
     extractions: Extraction[];
     candidateSets: CandidateSet[];
+    /**
+     * `locatorResolutions[idx]` is how `records[idx]`'s Extraction locator was
+     * resolved — a parallel array rather than a fourth key on
+     * `UtteranceStatementRecords`, whose shape is a pinned contract. The same
+     * value is also on `records[idx].extraction.metadata.agentUtterance`.
+     */
+    locatorResolutions: LocatorResolution[];
 }
 /**
  * Build the full set of Survey records for every extracted statement in one

package/dist/src/agent-utterance.js

@@ -59,8 +59,10 @@ function buildUtteranceExtraction(params) {
     const candidateId = `${statementId}.candidate`;
     // Compute locator — required for non-manual-entry sources
     // (assertProducerDiscipline throws without it). Source Locator rule:
-    // span-first, excerpt-fallback — UNCHANGED from Slice 1.
-    const locator = spanToLocator(statement.span) ?? excerptLocator(utterance, statement.excerpt);
+    // span-first, excerpt-fallback — locator VALUES unchanged from Slice 1;
+    // what is new is that the record now says which branch produced them, so
+    // an unanchored placeholder is never mistaken for a resolved pointer.
+    const { locator, resolution: locatorResolution } = resolveUtteranceLocator(utterance, statement);
     const extraction = {
         id: extractionId,
         sourceId,
@@ -77,6 +79,7 @@ function buildUtteranceExtraction(params) {
                 excerpt: statement.excerpt,
                 extractorName,
                 confidence: statement.confidence,
+                locatorResolution,
             },
         },
     };
@@ -93,7 +96,7 @@ function buildUtteranceExtraction(params) {
             confidence: statement.confidence,
         },
     };
-    return { extraction, proposal };
+    return { extraction, proposal, locatorResolution };
 }
 /**
  * Group extraction/proposal pairs by canonical target and project each
@@ -166,7 +169,7 @@ function groupUtteranceExtractionsByTarget(sourceId, items) {
 export function buildUtteranceRecords(params) {
     const { sourceId, utterance, extracted, extractorName, observedAt } = params;
     const items = extracted.map((statement, idx) => {
-        const { extraction, proposal } = buildUtteranceExtraction({
+        const { extraction, proposal, locatorResolution } = buildUtteranceExtraction({
             sourceId,
             idx,
             statement,
@@ -174,7 +177,7 @@ export function buildUtteranceRecords(params) {
             extractorName,
             observedAt,
         });
-        return { statement, extraction, proposal };
+        return { statement, extraction, proposal, locatorResolution };
     });
     const groups = groupUtteranceExtractionsByTarget(sourceId, items);
     const records = items.map((item) => {
@@ -186,6 +189,7 @@ export function buildUtteranceRecords(params) {
         records,
         extractions: items.map((i) => i.extraction),
         candidateSets: [...groups.values()].map((g) => g.candidateSet),
+        locatorResolutions: items.map((i) => i.locatorResolution),
     };
 }
 // ---------------------------------------------------------------------------
@@ -234,7 +238,7 @@ export function utteranceToSurveyInput(utterance, extracted, context) {
     // core) — replaces the old per-statement builder call. Claims below stay
     // one-per-statement; `record.candidateSet.id`/`record.candidate.id` may be
     // shared across several claims when statements share a target (legal).
-    const { records, extractions, candidateSets } = buildUtteranceRecords({
+    const { records, extractions, candidateSets, locatorResolutions } = buildUtteranceRecords({
         sourceId,
         utterance,
         extracted,
@@ -270,6 +274,9 @@ export function utteranceToSurveyInput(utterance, extracted, context) {
                         span: statement.span,
                         confidence: statement.confidence,
                         locator: record.extraction.locator,
+                        // Travels with the locator so a downstream reader of the Claim
+                        // never has to assume the locator resolved.
+                        locatorResolution: locatorResolutions[idx],
                     },
                 },
             },
@@ -318,13 +325,14 @@ export async function surveyAgentUtterance(utterance, extractor, context) {
     };
     // Step 2: Extract statements
     const extracted = await Promise.resolve(extractor.extract(utterance));
-    // Batched, grouped provenance construction — kept for provenance/doc-comment
-    // fidelity across the whole utterance (grouping needs every statement of a
-    // target's group present at once; a per-statement call cannot compute it).
-    // Still not surfaced on UtteranceStatement/UtteranceTrustReport this slice
-    // (unchanged from Slice 1's own scoping note) — wiring is left for a future
-    // slice, same as before.
-    buildUtteranceRecords({
+    // Batched, grouped provenance construction. Grouping needs every statement
+    // of a target's group present at once, so this cannot be a per-statement
+    // call. The result is now carried onto every UtteranceStatement
+    // (`records`), so the extractor's confidence, locator, Candidate and
+    // Candidate Set — including the Candidate Conflict verdict when two
+    // statements in this utterance disagree about one target — are observable
+    // in the report instead of being computed and dropped on the floor.
+    const { records, locatorResolutions } = buildUtteranceRecords({
         sourceId,
         utterance,
         extracted,
@@ -333,7 +341,7 @@ export async function surveyAgentUtterance(utterance, extractor, context) {
     });
     // Step 3 & 4: Resolve each statement and build the report
     const statements = [];
-    for (const statement of extracted) {
+    for (const [idx, statement] of extracted.entries()) {
         // Resolve the claim
         let inquiryRecord;
         if (mappings && mappings.length > 0) {
@@ -358,11 +366,17 @@ export async function surveyAgentUtterance(utterance, extractor, context) {
             // Resolve directly by canonical target
             inquiryRecord = resolveByTarget(bundle, statement.target, agentId, observedAt, rules, now);
         }
-        const badge = badgeFromRecord(inquiryRecord);
+        const comparison = compareAssertedValue(statement, inquiryRecord);
+        const badge = badgeFor(inquiryRecord, comparison.valueComparison);
         statements.push({
             excerpt: statement.excerpt,
             span: statement.span,
             target: statement.target,
+            ...(hasAssertedValue(statement) ? { assertedValue: statement.value } : {}),
+            valueComparison: comparison.valueComparison,
+            comparisonRationale: comparison.rationale,
+            records: records[idx],
+            locatorResolution: locatorResolutions[idx],
             inquiryRecord,
             badge,
         });
@@ -389,45 +403,122 @@ function canonicalTargetKey(target) {
 function targetToQuestion(target) {
     return `${target.subjectId} ${target.fieldOrBehavior}`;
 }
-function badgeFromRecord(record) {
+/**
+ * Answer statuses a reader takes as support for what the statement said.
+ * These — and only these — are the statuses a contradiction must override:
+ * badging a statement "verified" when it asserts a value the verified claim
+ * denies is the exact failure this profile exists to prevent. For any other
+ * status the claim's own standing is already the more informative thing to
+ * show, and the contradiction stays legible in `valueComparison`.
+ */
+const SUPPORTING_STATUSES = new Set(["verified", "assumed", "stale"]);
+function hasAssertedValue(statement) {
+    return statement.value !== undefined;
+}
+/**
+ * Whether a value can take part in a statement-vs-answer comparison at all.
+ * Scalars can; objects and arrays cannot, because an utterance extractor
+ * pulls a token out of prose and there is no defensible way to decide
+ * whether that token "is" a structured value. Those report "not-compared"
+ * rather than being asserted to contradict.
+ */
+function isComparableScalar(value) {
+    return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+/**
+ * The statement-vs-answer comparison key.
+ *
+ * This is deliberately NOT `utteranceEquivalenceKey`. That key compares two
+ * values from the SAME extractor, which share one type discipline, so it
+ * refuses cross-type equality on purpose (5 and "5" from one extractor
+ * really are different findings). A statement-vs-answer comparison crosses a
+ * boundary: the left side is a token the extractor pulled out of prose, the
+ * right side is a value the producer typed. Comparing those two by
+ * `typeof` would badge every true statement about a numeric or boolean field
+ * as a contradiction — a false accusation, which damages the badge exactly
+ * as much as a false green does.
+ *
+ * So scalars are compared by their canonical TEXT rendering, trimmed and
+ * lowercased. This bridges "the agent wrote 95" to "the producer stored 95"
+ * without losing a genuine disagreement: "5" and "6" still differ, and the
+ * bridge is named in `comparisonRationale` rather than applied silently.
+ */
+function assertionComparisonKey(value) {
+    return String(value).trim().toLowerCase();
+}
+/**
+ * Compare the statement's own asserted value against the bundle's answer.
+ *
+ * An absent asserted value is never treated as agreement: an extractor that
+ * parsed no value has asserted nothing to check, so it reports
+ * "not-compared".
+ */
+function compareAssertedValue(statement, record) {
+    const targetKey = canonicalTargetKey(statement.target);
+    const answer = record.answer;
+    if (!answer) {
+        return {
+            valueComparison: "not-compared",
+            rationale: `No answer for ${targetKey} (inquiry outcome: ${record.outcome}); nothing to compare the statement against.`,
+        };
+    }
+    if (!hasAssertedValue(statement)) {
+        return {
+            valueComparison: "not-compared",
+            rationale: `The extractor parsed no value out of this statement, so nothing was compared against the ${answer.status} answer for ${targetKey}.`,
+        };
+    }
+    if (!isComparableScalar(statement.value) || !isComparableScalar(answer.value)) {
+        return {
+            valueComparison: "not-compared",
+            rationale: `Statement value ${JSON.stringify(statement.value) ?? "undefined"} and the ${answer.status} answer ${JSON.stringify(answer.value) ?? "undefined"} for ${targetKey} are not both scalars; no comparison was attempted.`,
+        };
+    }
+    const asserted = assertionComparisonKey(statement.value);
+    const answered = assertionComparisonKey(answer.value);
+    const shown = `statement "${asserted}" vs ${answer.status} answer "${answered}" (compared as text)`;
+    return asserted === answered
+        ? { valueComparison: "agrees", rationale: `Agrees for ${targetKey}: ${shown}.` }
+        : { valueComparison: "contradicts", rationale: `Contradicts for ${targetKey}: ${shown}.` };
+}
+/**
+ * Grade the STATEMENT: the answer's status, overridden by "contradicted"
+ * when the statement asserts something the answer denies and that answer
+ * would otherwise have read as support.
+ */
+function badgeFor(record, valueComparison) {
     if (record.outcome === "unsupported")
         return "unsupported";
     const status = record.answer?.status;
     if (!status)
         return "unsupported";
-    if (status === "verified")
-        return "verified";
-    if (status === "assumed")
-        return "assumed";
-    if (status === "stale")
-        return "stale";
-    if (status === "disputed")
-        return "disputed";
-    if (status === "rejected" || status === "superseded")
-        return "rejected";
-    return "unsupported";
+    if (valueComparison === "contradicts" && SUPPORTING_STATUSES.has(status))
+        return "contradicted";
+    return status;
 }
 /**
- * Convert a text-span to a locator string.
- */
-function spanToLocator(span) {
-    if (!span)
-        return undefined;
-    return `text-span:${span.start}-${span.end}`;
-}
-/**
- * Best-effort locator from excerpt text — find the first occurrence of the
- * excerpt in the utterance and use that as a text-span locator.
- * Falls back to text-span:0-0 if the excerpt is not found.
+ * The single Source Locator rule this module guarantees: span-first,
+ * excerpt-match second, unanchored placeholder last — and it always reports
+ * WHICH of the three produced the locator.
+ *
+ * The locator strings are unchanged from Slice 1, including the last branch's
+ * `text-span:0-<excerpt.length>` placeholder. That placeholder is deliberate
+ * (producer discipline requires a locator on a non-manual-entry source), but
+ * it is well-formed and therefore resolvable — it will happily span real,
+ * unrelated prose at the head of the utterance. Returning the resolution
+ * alongside it is what keeps a hallucinated excerpt from acquiring a pointer
+ * that looks exactly like a found one: the record now says the lookup failed
+ * instead of leaving the reader to re-derive it.
  */
-function excerptLocator(utterance, excerpt) {
-    const idx = utterance.indexOf(excerpt);
+function resolveUtteranceLocator(utterance, statement) {
+    if (statement.span) {
+        return { locator: `text-span:${statement.span.start}-${statement.span.end}`, resolution: "span" };
+    }
+    const idx = utterance.indexOf(statement.excerpt);
     if (idx >= 0) {
-        return `text-span:${idx}-${idx + excerpt.length}`;
+        return { locator: `text-span:${idx}-${idx + statement.excerpt.length}`, resolution: "excerpt-match" };
     }
-    // Fallback: anchor to start (preserves discipline contract; locator is
-    // best-effort for span-less extractors)
-    return `text-span:0-${excerpt.length}`;
+    return { locator: `text-span:0-${statement.excerpt.length}`, resolution: "unanchored-fallback" };
 }
 // ---------------------------------------------------------------------------
 // Reference extractor (deterministic, for tests — not for production use)