@kontourai/survey 3.0.0 → 5.0.0

package/dist/src/review-workbench/extraction-inspector.js

@@ -26,14 +26,19 @@ export function buildExtractionInspectorModel(input) {
         if (sourceKeys.has(sourceKey))
             throw new Error("Extraction inspector source identity collision.");
         sourceKeys.add(sourceKey);
-        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.state, entry.artifact, envelope.result.ocrDerived);
+        const source = sourceModel(sourceKey, record.metadata.name, prepared, record.status.diagnostics, entry.artifact, envelope.result.ocrDerived);
         sources.push(source);
         const candidateStart = candidates.length;
+        const itemByProposalIndex = new Map();
+        for (const item of entry.importResult.reviewItems) {
+            for (const proposalIndex of envelopeItemProposalIndices(item))
+                itemByProposalIndex.set(proposalIndex, item.metadata.name);
+        }
         envelope.result.proposals.forEach((proposal, proposalIndex) => {
-            const item = entry.importResult.reviewItems[proposalIndex];
-            if (!item)
+            const itemName = itemByProposalIndex.get(proposalIndex);
+            if (!itemName)
                 return; // unresolved imports legitimately produce no ReviewItems
-            candidates.push(candidateModel(source, item.metadata.name, proposal, proposalIndex, envelope.result.provider, envelope.result.model, envelope.result.runId, entry.pass, envelope.result.pdfPageOffsets, envelope.result.pdfLayout, envelope.result.ocrDerived));
+            candidates.push(candidateModel(source, itemName, proposal, proposalIndex, envelope.result.provider, envelope.result.model, envelope.result.runId, entry.pass, envelope.result.pdfPageOffsets, envelope.result.pdfLayout, envelope.result.ocrDerived));
         });
         if (source.alignment === "excerpt-mismatch") {
             delete source.artifactText;
@@ -141,28 +146,53 @@ function assertImportedResult(result, record) {
     if (!record.metadata?.name || !record.metadata.producerNamespace || !record.spec?.envelope?.result || !Array.isArray(record.spec.envelope.result.proposals))
         throw new Error("Malformed extraction import result.");
     const grounded = record.status?.state === "grounded";
-    if ((!grounded && reviewItems.length !== 0) || (grounded && reviewItems.length !== record.spec.envelope.result.proposals.length))
+    const proposals = record.spec.envelope.result.proposals;
+    const covered = reviewItems.flatMap(envelopeItemProposalIndices).sort((left, right) => left - right);
+    if ((!grounded && reviewItems.length !== 0) || (grounded && canonicalJson(covered) !== canonicalJson(proposals.map((_proposal, index) => index))))
         throw new Error("Extraction import ReviewItems do not match its grounding state.");
     const canonicalItems = buildReviewItemsFromExtractionEnvelopeImport(record);
     if (canonicalJson(reviewItems) !== canonicalJson(canonicalItems))
         throw new Error("Extraction import ReviewItems do not match their canonical identities and bindings.");
-    reviewItems.forEach((item, index) => {
-        const proposal = record.spec.envelope.result.proposals[index];
+    reviewItems.forEach((item, itemIndex) => {
         const metadata = item.metadata?.producer?.["survey.kontourai.io/extraction-envelope"];
-        const candidate = item.spec?.candidates?.[0];
-        const binding = candidate?.producer?.["survey.kontourai.io/extraction-envelope"];
-        if (item.kind !== "ReviewItem" || !item.metadata.name || item.spec.candidates.length !== 1
-            || metadata?.importName !== record.metadata.name || binding?.importName !== record.metadata.name
-            || binding.proposalIndex !== index || binding.runId !== record.spec.envelope.result.runId || binding.provider !== record.spec.envelope.result.provider
-            || item.spec.target !== proposal.fieldPath || candidate?.locator?.locator !== proposal.provenance.locator || candidate.locator.excerpt !== proposal.provenance.excerpt) {
-            throw new Error(`Extraction import ReviewItem ${index} is inconsistent with its validated proposal.`);
+        if (item.kind !== "ReviewItem" || !item.metadata.name || item.spec.candidates.length === 0 || metadata?.importName !== record.metadata.name) {
+            throw new Error(`Extraction import ReviewItem ${itemIndex} is inconsistent with its validated proposals.`);
+        }
+        for (const candidate of item.spec.candidates) {
+            const binding = candidate.producer?.["survey.kontourai.io/extraction-envelope"];
+            const proposal = typeof binding?.proposalIndex === "number" ? proposals[binding.proposalIndex] : undefined;
+            if (!proposal || binding?.importName !== record.metadata.name || binding.runId !== record.spec.envelope.result.runId || binding.provider !== record.spec.envelope.result.provider
+                || candidate.extraction.target !== proposal.fieldPath || candidate.locator?.locator !== proposal.provenance.locator || candidate.locator.excerpt !== proposal.provenance.excerpt) {
+                throw new Error(`Extraction import ReviewItem ${itemIndex} is inconsistent with its validated proposals.`);
+            }
         }
     });
 }
-function sourceModel(key, importName, prepared, state, artifact, ocrDerived) {
+/** The proposal indices one imported ReviewItem stands for, as its producer metadata records them. */
+function envelopeItemProposalIndices(item) {
+    const metadata = item.metadata?.producer?.["survey.kontourai.io/extraction-envelope"];
+    const indices = metadata?.proposalIndices;
+    if (!Array.isArray(indices) || indices.length === 0 || !indices.every((index) => Number.isSafeInteger(index) && index >= 0)) {
+        throw new Error(`Extraction import ReviewItem ${item.metadata?.name ?? "(unnamed)"} does not record its proposals.`);
+    }
+    return indices;
+}
+/**
+ * The posture a source is shown with: the extraction's own failure or early
+ * stop when there is one, otherwise the artifact alignment. A failed
+ * extraction over an aligned artifact must not show the aligned posture.
+ */
+export function inspectorSourcePosture(source) {
+    if (source.extractionDiagnostic)
+        return source.extractionDiagnostic.kind;
+    return source.alignment;
+}
+function sourceModel(key, importName, prepared, diagnostics, artifact, ocrDerived) {
     let alignment;
     let message;
-    if (state !== "grounded" || artifact.status === "unavailable") {
+    const artifactUnresolved = diagnostics.some((diagnostic) => diagnostic.kind === "artifact-unavailable" || diagnostic.kind === "digest-mismatch");
+    const extractionDiagnostic = diagnostics.find((diagnostic) => diagnostic.kind === "extraction-failed" || diagnostic.kind === "extraction-incomplete");
+    if (artifactUnresolved || artifact.status === "unavailable") {
         alignment = "artifact-unavailable";
         message = `Prepared artifact unavailable (${artifact.status === "unavailable" ? artifact.code : "invalid-artifact"}). Candidates are not grounded.`;
     }
@@ -177,9 +207,15 @@ function sourceModel(key, importName, prepared, state, artifact, ocrDerived) {
     }
     else {
         alignment = "aligned";
-        message = `Prepared artifact identity verified. Exact source spans are available.${ocrDerived ? " Prepared text is OCR-derived." : ""}`;
+        message = extractionDiagnostic
+            ? "Prepared artifact identity verified."
+            : `Prepared artifact identity verified. Exact source spans are available.${ocrDerived ? " Prepared text is OCR-derived." : ""}`;
     }
-    return { key, importName, ...(prepared?.ref ? { artifactRef: prepared.ref } : {}), ...(prepared?.digest ? { expectedDigest: prepared.digest } : {}), ...("actualDigest" in artifact ? { actualDigest: artifact.actualDigest } : {}), ...(alignment === "aligned" && artifact.status === "available" ? { artifactText: artifact.text } : {}), ...(ocrDerived ? { ocrDerived: true } : {}), alignment, message };
+    // The extraction's own failure leads: an aligned artifact with no candidates
+    // must not read as a complete run that found nothing.
+    if (extractionDiagnostic)
+        message = `${extractionDiagnostic.message} ${message}`;
+    return { key, importName, ...(extractionDiagnostic ? { extractionDiagnostic } : {}), ...(prepared?.ref ? { artifactRef: prepared.ref } : {}), ...(prepared?.digest ? { expectedDigest: prepared.digest } : {}), ...("actualDigest" in artifact ? { actualDigest: artifact.actualDigest } : {}), ...(alignment === "aligned" && artifact.status === "available" ? { artifactText: artifact.text } : {}), ...(ocrDerived ? { ocrDerived: true } : {}), alignment, message };
 }
 function candidateModel(source, reviewItemName, proposal, index, provider, model, attempt, pass, pdfPageOffsets, pdfLayout, ocrDerived) {
     const match = /^chars:(\d+)-(\d+)$/.exec(proposal.provenance.locator);
@@ -270,7 +306,7 @@ export function mountExtractionInspector(container, model, options = {}) {
         next.hidden = pageCount === 1;
         previous.disabled = page === 0;
         next.disabled = page >= pageCount - 1;
-        postures.innerHTML = model.sources.map(s => `<div class="inspector-posture ${s.alignment}" role="status"><strong>${escapeHtml(s.importName)}: ${escapeHtml(s.alignment)}</strong><span>${escapeHtml(s.message)}</span></div>`).join("");
+        postures.innerHTML = model.sources.map(s => { const posture = inspectorSourcePosture(s); return `<div class="inspector-posture ${s.alignment}${posture !== s.alignment ? ` ${posture}` : ""}" role="status" data-posture="${escapeHtml(posture)}"><strong>${escapeHtml(s.importName)}: ${escapeHtml(posture)}</strong><span>${escapeHtml(s.message)}</span></div>`; }).join("");
         sourcesRoot.innerHTML = model.sources.map(s => { const anchored = model.candidates.filter(c => c.sourceKey === s.key); const marked = visible.filter(c => c.sourceKey === s.key); return `<div class="inspector-source" aria-label="Prepared source for ${escapeHtml(s.importName)}"><h3>${escapeHtml(s.importName)}</h3><pre tabindex="0">${s.artifactText === undefined ? `${anchored.map(c => anchorHtml(c, highlightIdFor(c))).join("")}<span class="source-unavailable">${escapeHtml(s.message)}</span>` : renderSource(s.artifactText, anchored, marked, highlightIdFor)}</pre></div>`; }).join("");
     };
     root.querySelectorAll("select").forEach(select => select.addEventListener("change", event => { event.stopPropagation(); const key = select.dataset.filter; if (select.value)

package/dist/src/review-workbench/queue-binding.js

@@ -229,7 +229,7 @@ export function validateReviewQueueAgainstExtractionImport(items, importResult)
     if (record.status.state !== "grounded") {
         return [{
                 code: "import-not-grounded",
-                message: `Extraction import ${record.metadata.name} is ${record.status.state}, not grounded; it cannot attest a review queue.`,
+                message: `Extraction import ${record.metadata.name} is ${record.status.state}, not grounded (${record.status.diagnostics.map((diagnostic) => diagnostic.message).join(" ")}); it cannot attest a review queue.`,
             }];
     }
     if (items.length === 0) {

package/dist/src/review-workbench/review-presentation.d.ts

@@ -1,4 +1,5 @@
 import { type ReviewCandidate, type ReviewItem } from "../review-resource.js";
+import type { InterpretationAnswerImpact, InterpretationReadingKind } from "../types.js";
 import { type ReviewWorkbenchResult } from "./review-workbench.js";
 export interface ReviewPresentationAdapter {
     readonly labelForTarget?: (target: string, context: ReviewItemPresentationContext) => string | undefined;
@@ -56,11 +57,55 @@ export interface ReviewResultPresentation {
     readonly target: string;
     readonly targetLabel: string;
     readonly decisionLabel: string;
-    readonly selectedValueText: string;
+    /** Absent when the decision selects no candidate (reject-all or could-not-confirm on a conflict). */
+    readonly selectedValueText?: string;
     readonly applyMeaning: string;
     readonly reviewItemLink?: ReviewPresentationLink;
     readonly traceRefs: readonly ReviewTraceRef[];
 }
+/**
+ * Structural input for {@link buildInterpretationReadingPresentation}: either
+ * a Survey `Interpretation` record (`id`) or the entry Survey projects onto a
+ * claim at `metadata.survey.interpretations[]` (`interpretationId`). Kind and
+ * impact arrive as plain strings when read back from projected metadata.
+ */
+export interface InterpretationReadingSource {
+    readonly id?: string;
+    readonly interpretationId?: string;
+    readonly readingKind?: string;
+    readonly answerImpact?: string;
+    readonly ruleLocator: string;
+    readonly reading: string;
+    readonly actor: string;
+    readonly recordedAt: string;
+}
+export interface InterpretationReadingPresentation {
+    readonly interpretationId: string;
+    readonly readingKind: InterpretationReadingKind;
+    readonly kindLabel: string;
+    readonly answerImpact?: InterpretationAnswerImpact;
+    readonly answerImpactLabel?: string;
+    readonly reading: string;
+    readonly actor: string;
+    readonly recordedAt: string;
+    readonly ruleLocator: string;
+    /**
+     * Always `"authored-judgment"`. This is DERIVED from the record type, not a
+     * stored flag: every Interpretation reading is a producer-authored reading
+     * by contract (CONTEXT.md "Interpretation Record"), never a machine-observed
+     * fact. Renderers must present readings under this marking, visually
+     * distinct from machine-observed values — the StatementBadge / ADR 0003 §4
+     * discipline (blending the two is the defect class of #247).
+     */
+    readonly provenance: "authored-judgment";
+    readonly provenanceLabel: string;
+}
+/**
+ * Presents one interpretation reading as authored judgment. Fails closed on
+ * unknown reading-kind / answer-impact vocabulary rather than rendering an
+ * authored record under a label nothing derived.
+ */
+export declare function buildInterpretationReadingPresentation(source: InterpretationReadingSource): InterpretationReadingPresentation;
 export declare function buildReviewItemPresentation(item: ReviewItem, adapter?: ReviewPresentationAdapter): ReviewItemPresentation;
 export declare function buildReviewCandidatePresentation(item: ReviewItem, candidate: ReviewCandidate, adapter?: ReviewPresentationAdapter, targetLabel?: string): ReviewCandidatePresentation;
 export declare function buildReviewResultPresentation(result: ReviewWorkbenchResult, item: ReviewItem | undefined, adapter?: ReviewPresentationAdapter): ReviewResultPresentation;

package/dist/src/review-workbench/review-presentation.js

@@ -1,5 +1,54 @@
 import { findSoleCandidateById } from "../review-resource.js";
 import { formatValue } from "./review-surface-preview.js";
+const INTERPRETATION_KIND_LABELS = {
+    "policy-standard": "Policy-standard reading",
+    gleaned: "Gleaned from results",
+    answerImpact: "Answer impact",
+};
+const ANSWER_IMPACT_LABELS = {
+    supported: "Supported the answer",
+    narrowed: "Narrowed the answer",
+    "accepted-risk": "Accepted as a risk",
+};
+/**
+ * Presents one interpretation reading as authored judgment. Fails closed on
+ * unknown reading-kind / answer-impact vocabulary rather than rendering an
+ * authored record under a label nothing derived.
+ */
+export function buildInterpretationReadingPresentation(source) {
+    const interpretationId = source.interpretationId ?? source.id;
+    if (!interpretationId) {
+        throw new Error("Interpretation reading presentation requires an id or interpretationId.");
+    }
+    const readingKind = (source.readingKind ?? "policy-standard");
+    const kindLabel = INTERPRETATION_KIND_LABELS[readingKind];
+    if (!kindLabel) {
+        throw new Error(`Interpretation ${interpretationId} has unknown readingKind ${String(source.readingKind)}`);
+    }
+    const answerImpact = source.answerImpact;
+    const answerImpactLabel = answerImpact === undefined ? undefined : ANSWER_IMPACT_LABELS[answerImpact];
+    if (answerImpact !== undefined && !answerImpactLabel) {
+        throw new Error(`Interpretation ${interpretationId} has unknown answerImpact ${String(source.answerImpact)}`);
+    }
+    if (readingKind === "answerImpact" && answerImpact === undefined) {
+        throw new Error(`Interpretation ${interpretationId} readingKind answerImpact requires an answerImpact value`);
+    }
+    if (readingKind !== "answerImpact" && answerImpact !== undefined) {
+        throw new Error(`Interpretation ${interpretationId} sets answerImpact but readingKind is ${readingKind}`);
+    }
+    return {
+        interpretationId,
+        readingKind,
+        kindLabel,
+        ...(answerImpact !== undefined ? { answerImpact, answerImpactLabel } : {}),
+        reading: source.reading,
+        actor: source.actor,
+        recordedAt: source.recordedAt,
+        ruleLocator: source.ruleLocator,
+        provenance: "authored-judgment",
+        provenanceLabel: "Authored judgment",
+    };
+}
 export function buildReviewItemPresentation(item, adapter = {}) {
     const context = { item };
     const targetLabel = adapter.labelForTarget?.(item.spec.target, context) ?? humanizeIdentifier(item.spec.target);
@@ -36,6 +85,28 @@ export function buildReviewResultPresentation(result, item, adapter = {}) {
         ? adapter.labelForTarget?.(target, itemContext) ?? humanizeIdentifier(target)
         : humanizeIdentifier(target);
     const selectedCandidate = item ? selectedCandidateForResult(item, result) : undefined;
+    // A decision that selects no candidate presents no selected value and no
+    // selected trace; it names every candidate instead.
+    if (result.selectedCandidateId === undefined) {
+        const rejected = result.decision === "reject-proposed";
+        return {
+            result,
+            item,
+            target,
+            targetLabel,
+            decisionLabel: humanizeIdentifier(result.decision),
+            applyMeaning: rejected
+                ? "Saved decision rejects every proposed value; none is applied"
+                : "Saved decision records that no proposed value could be confirmed; none is applied",
+            reviewItemLink: item && itemContext ? adapter.linkForReviewItem?.(item, itemContext) : undefined,
+            traceRefs: [
+                { label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item", context: undefined },
+                ...result.unselectedCandidates.map((candidate) => ({
+                    label: rejected ? "Rejected candidate" : "Unconfirmed candidate", value: candidate.id, kind: "candidate", context: candidate,
+                })),
+            ].flatMap(({ context, ...ref }) => (item ? withTraceLinks([ref], { item, candidate: context }, adapter) : [ref])),
+        };
+    }
     return {
         result,
         item,
@@ -119,7 +190,7 @@ function traceRefsForCandidate(item, candidate, adapter) {
 function traceRefsForResult(item, result, selectedCandidate, adapter) {
     return withTraceLinks([
         { label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item" },
-        { label: "Selected candidate", value: result.selectedCandidateId, kind: "candidate" },
+        { label: "Selected candidate", value: result.selectedCandidateId ?? "none", kind: "candidate" },
         {
             label: "Selected claim",
             value: selectedCandidate?.claimTarget.claimId ?? "not provided",

package/dist/src/review-workbench/review-queue-session.d.ts

@@ -94,15 +94,29 @@ export declare function keepActionDecision(item: ReviewItem, flaggedWrong: boole
 /**
  * The candidate a workbench decision applies to.
  *
- * Selection is by role, but the id this returns is what every caller makes
- * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
- * replay expectation. So the id has to name exactly one candidate before it
- * leaves here. Guarding the render path alone let the workbench emit an
- * undecidable decision through the export path and then present a different
+ * Selection is by role, so the role has to name exactly one candidate before a
+ * decision may trust it. Guarding the render path alone let the workbench emit
+ * an undecidable decision through the export path and then present a different
  * candidate's value against it; this is the shared selector all of those go
  * through, which is why the check belongs here rather than at each of them.
+ *
+ * A decision that would make one of several candidates in its role the trusted
+ * value is refused: picking the first would settle the conflict for the
+ * reviewer without showing it. A value-neutral decision (reject, could not
+ * confirm) on such an item selects none of them. It still returns the first
+ * candidate so in-process callers that need one candidate (rendering, the
+ * in-memory `ReviewWorkbenchResult`) have one, but that anchor is not recorded:
+ * {@link decisionCandidateId} is `undefined` for it, so the decision, its
+ * session events and the canonical projection name no candidate.
  */
 export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
+/** Whether a decision on this item selects no candidate at all (see {@link candidateForDecision}). */
+export declare function decisionSelectsNoCandidate(item: ReviewItem, decision: ReviewWorkbenchDecision): boolean;
+/**
+ * The candidate id a decision records: the selected candidate's, or
+ * `undefined` when the decision selects no candidate.
+ */
+export declare function decisionCandidateId(item: ReviewItem, decision: ReviewWorkbenchDecision): string | undefined;
 /**
  * The value that should actually be applied for a decision: the reviewer's inline
  * edit when one was made for an accept-proposed decision, otherwise the selected

package/dist/src/review-workbench/review-queue-session.js

@@ -1,5 +1,6 @@
 import { publicDirectoryReviewItemExample, reviewWorkbenchQueueExamples } from "./review-workbench-data.js";
 import { assertReviewResolutionConsistency } from "../producer-discipline.js";
+import { checkEditedValueForItem } from "./edited-value.js";
 import { assertSoleCandidateId, reviewResourceApiVersion, } from "../../src/review-resource.js";
 export const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export const defaultReviewSessionName = "review-workbench-session";
@@ -142,32 +143,65 @@ export function reviewSessionSummary(session) {
  * would invent a prior value, with provenance, that the source never had.
  */
 export function keepActionDecision(item, flaggedWrong) {
-    const hasRole = (role) => item.spec.candidates.some((candidate) => candidate.role === role);
-    if (flaggedWrong || !hasRole("current")) {
-        return hasRole("proposed") ? "reject-proposed" : undefined;
+    // Keeping the current value is recordable only when exactly one candidate is
+    // current (see candidateForDecision); rejecting the proposed values is
+    // recordable however many there are.
+    const count = (role) => item.spec.candidates.filter((candidate) => candidate.role === role).length;
+    if (flaggedWrong || count("current") === 0) {
+        return count("proposed") > 0 ? "reject-proposed" : undefined;
     }
-    return "keep-current";
+    return count("current") === 1 ? "keep-current" : undefined;
 }
+/**
+ * Decisions that make no candidate the trusted value: rejecting the proposed
+ * values and ending the round as could-not-confirm. On an item whose role holds
+ * several candidates (conflicting values for one claim) they select none of them.
+ */
+const VALUE_NEUTRAL_DECISIONS = new Set(["reject-proposed", "could-not-confirm"]);
 /**
  * The candidate a workbench decision applies to.
  *
- * Selection is by role, but the id this returns is what every caller makes
- * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
- * replay expectation. So the id has to name exactly one candidate before it
- * leaves here. Guarding the render path alone let the workbench emit an
- * undecidable decision through the export path and then present a different
+ * Selection is by role, so the role has to name exactly one candidate before a
+ * decision may trust it. Guarding the render path alone let the workbench emit
+ * an undecidable decision through the export path and then present a different
  * candidate's value against it; this is the shared selector all of those go
  * through, which is why the check belongs here rather than at each of them.
+ *
+ * A decision that would make one of several candidates in its role the trusted
+ * value is refused: picking the first would settle the conflict for the
+ * reviewer without showing it. A value-neutral decision (reject, could not
+ * confirm) on such an item selects none of them. It still returns the first
+ * candidate so in-process callers that need one candidate (rendering, the
+ * in-memory `ReviewWorkbenchResult`) have one, but that anchor is not recorded:
+ * {@link decisionCandidateId} is `undefined` for it, so the decision, its
+ * session events and the canonical projection name no candidate.
  */
 export function candidateForDecision(item, decision) {
     const definition = workbenchDecisionDefinitions[decision];
-    const candidate = item.spec.candidates.find((entry) => entry.role === definition.candidateRole);
+    const matches = item.spec.candidates.filter((entry) => entry.role === definition.candidateRole);
+    const candidate = matches[0];
     if (!candidate) {
         throw new Error(`ReviewItem ${item.metadata.name} has no ${definition.candidateRole} candidate.`);
     }
+    if (matches.length > 1 && !VALUE_NEUTRAL_DECISIONS.has(decision)) {
+        throw new Error(`ReviewItem ${item.metadata.name} has ${matches.length} ${definition.candidateRole} candidates; the ${decision} decision cannot choose between them.`);
+    }
     assertSoleCandidateId(item, candidate.id);
     return candidate;
 }
+/** Whether a decision on this item selects no candidate at all (see {@link candidateForDecision}). */
+export function decisionSelectsNoCandidate(item, decision) {
+    const role = workbenchDecisionDefinitions[decision].candidateRole;
+    return VALUE_NEUTRAL_DECISIONS.has(decision) && item.spec.candidates.filter((entry) => entry.role === role).length > 1;
+}
+/**
+ * The candidate id a decision records: the selected candidate's, or
+ * `undefined` when the decision selects no candidate.
+ */
+export function decisionCandidateId(item, decision) {
+    const candidate = candidateForDecision(item, decision);
+    return decisionSelectsNoCandidate(item, decision) ? undefined : candidate.id;
+}
 /**
  * The value that should actually be applied for a decision: the reviewer's inline
  * edit when one was made for an accept-proposed decision, otherwise the selected
@@ -253,7 +287,7 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
         if (decision === "could-not-confirm" && !note?.trim()) {
             throw new Error(`ReviewItem ${item.metadata.name} could not confirm requires a non-empty reason.`);
         }
-        const candidate = candidateForDecision(item, decision);
+        const candidateId = decisionCandidateId(item, decision);
         const definition = workbenchDecisionDefinitions[decision];
         const reviewDecisionName = `${item.metadata.name}-${decision}`;
         // Carry the reviewer's inline edit in the event itself (accept-proposed
@@ -283,7 +317,7 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
             occurredAt: session.reviewedAt,
             reviewItemName: item.metadata.name,
             reviewDecisionName,
-            candidateId: candidate.id,
+            ...(candidateId !== undefined ? { candidateId } : {}),
             status: definition.status,
             ...(decision === "could-not-confirm"
                 ? {
@@ -301,7 +335,7 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
             occurredAt: session.reviewedAt,
             reviewItemName: item.metadata.name,
             reviewDecisionName,
-            candidateId: candidate.id,
+            ...(candidateId !== undefined ? { candidateId } : {}),
             status: definition.status,
             rationale: note,
             ...(decision === "could-not-confirm"
@@ -368,7 +402,13 @@ export function replayReviewSessionEvents(startState, events) {
             const editedValuesByItemName = { ...session.editedValuesByItemName };
             const attemptEvidenceIdsByItemName = { ...session.attemptEvidenceIdsByItemName };
             if (decision === "accept-proposed" && editedValue !== undefined) {
-                editedValuesByItemName[itemName] = editedValue;
+                // Legacy sessions stored typed edits as editor text ("42"); store the
+                // descriptor-typed value so effectiveValue is 42. An edit the item does
+                // not allow is left as carried: validated replay refuses it before this
+                // point (kontourai/survey#278).
+                const item = session.items.find((entry) => entry.metadata.name === itemName);
+                const check = item ? checkEditedValueForItem(item, editedValue) : undefined;
+                editedValuesByItemName[itemName] = check?.ok ? check.value : editedValue;
             }
             else {
                 delete editedValuesByItemName[itemName];

package/dist/src/review-workbench/review-session-replay.d.ts

@@ -1,6 +1,6 @@
 import type { ReviewSessionEvent } from "../review-resource.js";
 import { type ReviewQueueSessionState } from "./review-queue-session.js";
-export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason";
+export type ReviewSessionReplayIssueCode = "invalid-sequence" | "duplicate-sequence" | "non-contiguous-sequence" | "unknown-active-item" | "unknown-review-item" | "unknown-candidate" | "missing-review-item" | "invalid-workbench-decision" | "decision-candidate-mismatch" | "decision-status-mismatch" | "decision-resolution-mismatch" | "missing-resolution-reason" | "edited-value-not-editable" | "edited-value-type-mismatch";
 export interface ReviewSessionReplayIssue {
     readonly code: ReviewSessionReplayIssueCode;
     readonly eventName: string;
@@ -10,3 +10,37 @@ export interface ReviewSessionReplayIssue {
     readonly message: string;
 }
 export declare function validateReviewSessionEventsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewSessionReplayIssue[];
+/**
+ * A ReviewSessionEvent whose `data.workbenchEditedValue` was rewritten from
+ * legacy editor text to its descriptor-typed value during replay (see
+ * checkEditedValueForItem). Not an error: the apply result still succeeds, and
+ * the warning lets a consumer see that a saved session was normalized.
+ */
+export type ReviewSessionReplayWarning = {
+    readonly code: "edited-value-converted-from-text";
+    readonly eventName: string;
+    readonly sequence: number;
+    readonly reviewItemName: string;
+    readonly originalValue: string;
+    readonly convertedValue: unknown;
+    readonly message: string;
+} | {
+    /**
+     * An edit that would be refused (see checkEditedValueForItem) on a
+     * decision event that a later decision for the same item superseded. It
+     * never reaches effectiveValue, so it does not fail the session.
+     */
+    readonly code: "superseded-edited-value-refused";
+    readonly eventName: string;
+    readonly sequence: number;
+    readonly reviewItemName: string;
+    readonly refusedCode: "edited-value-not-editable" | "edited-value-type-mismatch";
+    readonly editedValue: unknown;
+    readonly message: string;
+};
+/**
+ * Lists the legacy text edits replay converts to typed values, and refused
+ * edits that a later decision superseded. Call it only on an event stream that
+ * validateReviewSessionEventsForSnapshot accepted.
+ */
+export declare function reviewSessionReplayWarningsForSnapshot(snapshot: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewSessionReplayWarning[];

package/dist/src/review-workbench/review-session-replay.js

@@ -1,7 +1,9 @@
-import { candidateForDecision, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { candidateForDecision, decisionSelectsNoCandidate, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { checkEditedValueForItem } from "./edited-value.js";
 export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
     const sequenceIssues = validateEventSequence(events);
+    const finalDecisionEvents = finalDecisionEventPerItem(events);
     const replayIssues = events.flatMap((event) => {
         const issues = [];
         const activeItemName = event.spec.activeItemName;
@@ -54,17 +56,19 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
             else if (itemName && itemsByName.has(itemName)) {
                 const item = itemsByName.get(itemName);
                 const expectedCandidate = item ? candidateForDecision(item, decision) : undefined;
+                // A decision that selects no candidate must reference none.
+                const expectedCandidateId = item && !decisionSelectsNoCandidate(item, decision) ? expectedCandidate?.id : undefined;
                 const expectedStatus = workbenchDecisionDefinitions[decision].status;
                 const referencedCandidateExists = event.spec.candidateId
                     ? item?.spec.candidates.some((candidate) => candidate.id === event.spec.candidateId)
                     : false;
-                if (expectedCandidate && (!event.spec.candidateId || referencedCandidateExists) && event.spec.candidateId !== expectedCandidate.id) {
+                if (expectedCandidate && (!event.spec.candidateId || referencedCandidateExists) && event.spec.candidateId !== expectedCandidateId) {
                     issues.push({
                         ...eventRef,
                         code: "decision-candidate-mismatch",
                         reviewItemName: itemName,
                         candidateId: event.spec.candidateId,
-                        message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects candidate ${expectedCandidate.id}, but references ${event.spec.candidateId ?? "no candidate"}.`,
+                        message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects ${expectedCandidateId ? `candidate ${expectedCandidateId}` : "no candidate"}, but references ${event.spec.candidateId ?? "no candidate"}.`,
                     });
                 }
                 if (event.spec.status !== expectedStatus) {
@@ -86,6 +90,22 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
                         message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects resolution ${expectedResolution ?? "none"}, but references ${event.spec.resolution ?? "no resolution"}.`,
                     });
                 }
+                const editedValue = editedValueFromDecisionEvent(event);
+                // Only the item's final decision decides its effectiveValue, so only an
+                // edit on that event is refused. An edit a later decision superseded is
+                // reported as a warning instead of failing the whole session.
+                if (item && decision === "accept-proposed" && editedValue !== undefined && finalDecisionEvents.has(event)) {
+                    const check = checkEditedValueForItem(item, editedValue);
+                    if (!check.ok) {
+                        issues.push({
+                            ...eventRef,
+                            code: check.code,
+                            reviewItemName: itemName,
+                            candidateId: event.spec.candidateId,
+                            message: `ReviewSessionEvent ${event.metadata.name}: ${check.message}`,
+                        });
+                    }
+                }
                 if (decision === "could-not-confirm" && !event.spec.resolutionReason?.trim()) {
                     issues.push({
                         ...eventRef,
@@ -114,6 +134,65 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     });
     return [...sequenceIssues, ...replayIssues];
 }
+/**
+ * Lists the legacy text edits replay converts to typed values, and refused
+ * edits that a later decision superseded. Call it only on an event stream that
+ * validateReviewSessionEventsForSnapshot accepted.
+ */
+export function reviewSessionReplayWarningsForSnapshot(snapshot, events) {
+    const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
+    const finalDecisionEvents = finalDecisionEventPerItem(events);
+    return events.flatMap((event) => {
+        const itemName = event.spec.reviewItemName;
+        const item = itemName ? itemsByName.get(itemName) : undefined;
+        const editedValue = editedValueFromDecisionEvent(event);
+        if (!item || !itemName || editedValue === undefined
+            || replayableWorkbenchDecision(event.spec.data?.workbenchDecision) !== "accept-proposed") {
+            return [];
+        }
+        const check = checkEditedValueForItem(item, editedValue);
+        if (!check.ok) {
+            return finalDecisionEvents.has(event) ? [] : [{
+                    code: "superseded-edited-value-refused",
+                    eventName: event.metadata.name,
+                    sequence: event.spec.sequence,
+                    reviewItemName: itemName,
+                    refusedCode: check.code,
+                    editedValue,
+                    message: `ReviewSessionEvent ${event.metadata.name} carries an edit a later decision superseded, which would be refused: ${check.message}`,
+                }];
+        }
+        if (!check.convertedFromText || typeof editedValue !== "string") {
+            return [];
+        }
+        return [{
+                code: "edited-value-converted-from-text",
+                eventName: event.metadata.name,
+                sequence: event.spec.sequence,
+                reviewItemName: itemName,
+                originalValue: editedValue,
+                convertedValue: check.value,
+                message: `ReviewSessionEvent ${event.metadata.name} stores edited value ${JSON.stringify(editedValue)} as text; replay converted it to ${JSON.stringify(check.value)} per ReviewItem ${itemName}'s value descriptor.`,
+            }];
+    });
+}
+/** The last decision event (by sequence, as replay applies them) for each ReviewItem. */
+function finalDecisionEventPerItem(events) {
+    const lastByItem = new Map();
+    for (const event of [...events].sort((left, right) => left.spec.sequence - right.spec.sequence)) {
+        if ((event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
+            && event.spec.reviewItemName) {
+            lastByItem.set(event.spec.reviewItemName, event);
+        }
+    }
+    return new Set(lastByItem.values());
+}
+function editedValueFromDecisionEvent(event) {
+    return (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
+        && event.spec.data && "workbenchEditedValue" in event.spec.data
+        ? event.spec.data.workbenchEditedValue
+        : undefined;
+}
 function replayableWorkbenchDecision(value) {
     return typeof value === "string" && value in workbenchDecisionDefinitions
         ? value

package/dist/src/review-workbench/review-workbench-css.generated.js

@@ -247,6 +247,8 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .inspector-heading h2{ margin: 0; }
 .survey-workbench-embed .inspector-posture{ display: flex; flex-direction: column; padding: .75rem; border-radius: var(--k-radius-sm); background: var(--k-positive-wash); }
 .survey-workbench-embed .inspector-posture.digest-mismatch, .survey-workbench-embed .inspector-posture.artifact-unavailable, .survey-workbench-embed .inspector-posture.excerpt-mismatch{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
+.survey-workbench-embed .inspector-posture.extraction-failed{ background: var(--k-negative-wash); color: var(--k-negative); border: 2px solid currentColor; }
+.survey-workbench-embed .inspector-posture.extraction-incomplete{ background: var(--k-caution-wash); color: var(--k-caution); border: 2px solid currentColor; }
 .survey-workbench-embed .inspector-filters{ display: flex; flex-wrap: wrap; gap: .6rem; margin: 1rem 0; }
 .survey-workbench-embed .inspector-filters label{ display: grid; gap: .25rem; font-size: .75rem; color: var(--k-text-muted); }
 .survey-workbench-embed .inspector-filters select, .survey-workbench-embed .inspector-filters input{ color: var(--k-text); background: var(--k-sunken); border: 1px solid var(--k-line); padding: .4rem; }