@kontourai/survey 1.15.0 → 1.17.0

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

@@ -1,4 +1,5 @@
 import { publicDirectoryReviewItemExample, reviewWorkbenchQueueExamples } from "./review-workbench-data.js";
+import { assertReviewResolutionConsistency } from "../producer-discipline.js";
 import { reviewResourceApiVersion, } from "../../src/review-resource.js";
 export const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export const defaultReviewSessionName = "review-workbench-session";
@@ -21,6 +22,12 @@ export const workbenchDecisionDefinitions = {
         candidateRole: "proposed",
         status: "rejected",
     },
+    "could-not-confirm": {
+        label: "Could not confirm",
+        effect: "The review round ends without changing or escalating the proposed claim.",
+        candidateRole: "proposed",
+        status: "proposed",
+    },
 };
 export function initialReviewWorkbenchState(item = publicDirectoryReviewItemExample) {
     return {
@@ -49,6 +56,7 @@ export function currentReviewWorkbenchState(session) {
         note: session.notesByItemName[item.metadata.name] ?? "",
         decision: session.decisionsByItemName[item.metadata.name],
         editedValue: session.editedValuesByItemName?.[item.metadata.name],
+        attemptEvidenceIds: session.attemptEvidenceIdsByItemName?.[item.metadata.name],
         reviewedAt: session.reviewedAt,
         actorId: session.actorId,
     };
@@ -65,6 +73,9 @@ export function deriveQueueRowStatus(item, session) {
     if (decision === "reject-proposed") {
         return "rejected";
     }
+    if (decision === "could-not-confirm") {
+        return "could-not-confirm";
+    }
     if (decision === "accept-proposed" || decision === "keep-current" || item.spec.candidateSetStatus === "resolved") {
         return "resolved";
     }
@@ -96,6 +107,9 @@ export function reviewSessionSummary(session) {
         if (decision === "reject-proposed") {
             return { ...summary, rejected: summary.rejected + 1 };
         }
+        if (decision === "could-not-confirm") {
+            return { ...summary, couldNotConfirm: (summary.couldNotConfirm ?? 0) + 1 };
+        }
         if (item.spec.candidateSetStatus === "escalated") {
             return { ...summary, escalated: summary.escalated + 1 };
         }
@@ -194,6 +208,9 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
         if (!decision) {
             continue;
         }
+        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 definition = workbenchDecisionDefinitions[decision];
         const reviewDecisionName = `${item.metadata.name}-${decision}`;
@@ -203,9 +220,20 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
         // the server apply boundary derives effectiveValue from it. Without this
         // the edit lives only in browser state and never survives replay.
         const editedValue = decision === "accept-proposed" ? session.editedValuesByItemName?.[item.metadata.name] : undefined;
+        const attemptEvidenceIds = decision === "could-not-confirm"
+            ? session.attemptEvidenceIdsByItemName?.[item.metadata.name]
+            : undefined;
+        assertReviewResolutionConsistency(`ReviewItem ${item.metadata.name}`, {
+            status: definition.status,
+            resolution: decision === "could-not-confirm" ? "could_not_confirm" : undefined,
+            resolutionReason: decision === "could-not-confirm" ? note : undefined,
+            attemptEvidenceIds,
+            actor: session.actorId,
+            reviewedAt: session.reviewedAt,
+        });
         const data = editedValue !== undefined
             ? { workbenchDecision: decision, workbenchEditedValue: editedValue }
-            : { workbenchDecision: decision };
+            : { workbenchDecision: decision, ...(attemptEvidenceIds?.length ? { attemptEvidenceIds } : {}) };
         events.push(buildReviewSessionEvent(session, {
             sessionName,
             sequence: events.length + 1,
@@ -215,6 +243,13 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
             reviewDecisionName,
             candidateId: candidate.id,
             status: definition.status,
+            ...(decision === "could-not-confirm"
+                ? {
+                    resolution: "could_not_confirm",
+                    resolutionReason: note,
+                    ...(attemptEvidenceIds ? { attemptEvidenceIds: [...attemptEvidenceIds] } : {}),
+                }
+                : {}),
             data,
         }));
         events.push(buildReviewSessionEvent(session, {
@@ -227,6 +262,13 @@ export function buildReviewSessionEvents(session, sessionName = defaultReviewSes
             candidateId: candidate.id,
             status: definition.status,
             rationale: note,
+            ...(decision === "could-not-confirm"
+                ? {
+                    resolution: "could_not_confirm",
+                    resolutionReason: note,
+                    ...(attemptEvidenceIds ? { attemptEvidenceIds: [...attemptEvidenceIds] } : {}),
+                }
+                : {}),
             data,
         }));
     }
@@ -264,7 +306,13 @@ export function replayReviewSessionEvents(startState, events) {
             if (isClearedWorkbenchDecisionEvent(event)) {
                 const { [itemName]: _removedDecision, ...remainingDecisions } = session.decisionsByItemName;
                 const { [itemName]: _removedEdit, ...remainingEdits } = session.editedValuesByItemName ?? {};
-                return { ...session, decisionsByItemName: remainingDecisions, editedValuesByItemName: remainingEdits };
+                const { [itemName]: _removedAttempts, ...remainingAttempts } = session.attemptEvidenceIdsByItemName ?? {};
+                return {
+                    ...session,
+                    decisionsByItemName: remainingDecisions,
+                    editedValuesByItemName: remainingEdits,
+                    attemptEvidenceIdsByItemName: remainingAttempts,
+                };
             }
             const decision = workbenchDecisionFromEvent(event);
             if (!decision) {
@@ -276,12 +324,19 @@ export function replayReviewSessionEvents(startState, events) {
             // reviewer moved away from.
             const editedValue = workbenchEditedValueFromEvent(event);
             const editedValuesByItemName = { ...session.editedValuesByItemName };
+            const attemptEvidenceIdsByItemName = { ...session.attemptEvidenceIdsByItemName };
             if (decision === "accept-proposed" && editedValue !== undefined) {
                 editedValuesByItemName[itemName] = editedValue;
             }
             else {
                 delete editedValuesByItemName[itemName];
             }
+            if (decision === "could-not-confirm" && event.spec.attemptEvidenceIds?.length) {
+                attemptEvidenceIdsByItemName[itemName] = [...event.spec.attemptEvidenceIds];
+            }
+            else {
+                delete attemptEvidenceIdsByItemName[itemName];
+            }
             return {
                 ...session,
                 decisionsByItemName: {
@@ -289,6 +344,7 @@ export function replayReviewSessionEvents(startState, events) {
                     [itemName]: decision,
                 },
                 editedValuesByItemName,
+                attemptEvidenceIdsByItemName,
             };
         }
         return session;

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";
+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 interface ReviewSessionReplayIssue {
     readonly code: ReviewSessionReplayIssueCode;
     readonly eventName: string;

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

@@ -76,6 +76,25 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
                         message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects status ${expectedStatus}, but references ${event.spec.status ?? "no status"}.`,
                     });
                 }
+                const expectedResolution = decision === "could-not-confirm" ? "could_not_confirm" : undefined;
+                if (event.spec.resolution !== expectedResolution) {
+                    issues.push({
+                        ...eventRef,
+                        code: "decision-resolution-mismatch",
+                        reviewItemName: itemName,
+                        candidateId: event.spec.candidateId,
+                        message: `ReviewSessionEvent ${event.metadata.name} decision ${decision} expects resolution ${expectedResolution ?? "none"}, but references ${event.spec.resolution ?? "no resolution"}.`,
+                    });
+                }
+                if (decision === "could-not-confirm" && !event.spec.resolutionReason?.trim()) {
+                    issues.push({
+                        ...eventRef,
+                        code: "missing-resolution-reason",
+                        reviewItemName: itemName,
+                        candidateId: event.spec.candidateId,
+                        message: `ReviewSessionEvent ${event.metadata.name} decision could-not-confirm requires a non-empty resolutionReason.`,
+                    });
+                }
             }
         }
         if (event.spec.candidateId && itemName && itemsByName.has(itemName)) {

package/dist/src/review-workbench/review-surface-preview.js

@@ -8,7 +8,7 @@ export function buildSurfaceProjectionPreview(item, decision, presentationAdapte
         canonicalClaim: buildPreviewClaim(item, selectedCandidate, decision, projection, presentationAdapter),
         candidateHistory: buildCandidateHistory(item, selectedCandidate, presentationAdapter),
         sourceEvidence: buildSourceEvidence(selectedCandidate),
-        reviewEvent: buildReviewEvent(decision, projection),
+        reviewEvent: decision.spec.resolution === "could_not_confirm" ? undefined : buildReviewEvent(decision, projection),
         integrityPosture: buildIntegrityPosture(item, selectedCandidate, projection),
         authorityTrace: portableAuthorityTrace(selectedCandidate.producer?.authorityTrace),
         postureDisclaimer: postureDisclaimer(),

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

@@ -437,6 +437,7 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .field[data-state="accepted"] .stripe{ background: var(--k-positive); }
 .survey-workbench-embed .field[data-state="kept"] .stripe{ background: var(--k-faint); }
 .survey-workbench-embed .field[data-state="rejected"] .stripe{ background: var(--k-negative); }
+.survey-workbench-embed .field[data-state="could-not-confirm"] .stripe{ background: var(--k-caution); }
 .survey-workbench-embed .field[data-state="review"] .stripe{ background: var(--k-brand); }
 
 .survey-workbench-embed .fbody{
@@ -491,6 +492,7 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .chip.accepted{ color: var(--k-positive); background: var(--k-positive-wash); }
 .survey-workbench-embed .chip.kept{ color: var(--k-muted); background: var(--k-sunken); }
 .survey-workbench-embed .chip.rejected{ color: var(--k-negative); background: var(--k-negative-wash); }
+.survey-workbench-embed .chip.could-not-confirm{ color: var(--k-caution); background: var(--k-caution-wash); }
 
 .survey-workbench-embed .frow1 .push{
   margin-left: auto;
@@ -755,6 +757,12 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   background: var(--k-panel-raised, var(--k-raised));
 }
 
+.survey-workbench-embed .btn.unconfirmed{
+  border-color: var(--k-caution);
+  color: var(--k-caution);
+  background: var(--k-caution-wash);
+}
+
 /* "Suggestion was wrong" — optional quiet calibration toggle on Keep current.
    Ticking it turns a keep-current decision into the reject signal. Not a third action. */
 .survey-workbench-embed .wrong{

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

@@ -434,6 +434,7 @@
 .survey-workbench-embed .field[data-state="accepted"] .stripe{ background: var(--k-positive); }
 .survey-workbench-embed .field[data-state="kept"] .stripe{ background: var(--k-faint); }
 .survey-workbench-embed .field[data-state="rejected"] .stripe{ background: var(--k-negative); }
+.survey-workbench-embed .field[data-state="could-not-confirm"] .stripe{ background: var(--k-caution); }
 .survey-workbench-embed .field[data-state="review"] .stripe{ background: var(--k-brand); }
 
 .survey-workbench-embed .fbody{
@@ -488,6 +489,7 @@
 .survey-workbench-embed .chip.accepted{ color: var(--k-positive); background: var(--k-positive-wash); }
 .survey-workbench-embed .chip.kept{ color: var(--k-muted); background: var(--k-sunken); }
 .survey-workbench-embed .chip.rejected{ color: var(--k-negative); background: var(--k-negative-wash); }
+.survey-workbench-embed .chip.could-not-confirm{ color: var(--k-caution); background: var(--k-caution-wash); }
 
 .survey-workbench-embed .frow1 .push{
   margin-left: auto;
@@ -752,6 +754,12 @@
   background: var(--k-panel-raised, var(--k-raised));
 }
 
+.survey-workbench-embed .btn.unconfirmed{
+  border-color: var(--k-caution);
+  color: var(--k-caution);
+  background: var(--k-caution-wash);
+}
+
 /* "Suggestion was wrong" — optional quiet calibration toggle on Keep current.
    Ticking it turns a keep-current decision into the reject signal. Not a third action. */
 .survey-workbench-embed .wrong{

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

@@ -1,4 +1,5 @@
 import { canonicalJson } from "./canonical.js";
+import { assertReviewResolutionConsistency } from "../producer-discipline.js";
 import { candidateForDecision, buildReviewSessionEvent, buildReviewSessionEvents, buildReviewSessionResource, currentReviewWorkbenchState, defaultReviewSessionName, effectiveValueForDecision, initialReviewQueueSessionState, replayReviewSessionEvents, reviewWorkbenchSessionStorageKey, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 import { buildSurfaceProjectionPreview, formatValue, } from "./review-surface-preview.js";
@@ -16,13 +17,16 @@ export function buildReviewDecision(state) {
         return undefined;
     }
     const definition = workbenchDecisionDefinitions[state.decision];
+    if (state.decision === "could-not-confirm" && !state.note.trim()) {
+        throw new Error("Could not confirm requires a non-empty reason.");
+    }
     const candidate = candidateForDecision(state.item, state.decision);
     const projection = {
         ...candidate.projection,
         reviewOutcomeId: candidate.projection?.reviewOutcomeId
             ?? `${state.item.metadata.name}:${state.decision}:review-outcome`,
     };
-    return {
+    const reviewDecision = {
         apiVersion: reviewResourceApiVersion,
         kind: "ReviewDecision",
         metadata: {
@@ -34,6 +38,13 @@ export function buildReviewDecision(state) {
             reviewItemName: state.item.metadata.name,
             candidateId: candidate.id,
             status: definition.status,
+            ...(state.decision === "could-not-confirm"
+                ? {
+                    resolution: "could_not_confirm",
+                    resolutionReason: state.note.trim(),
+                    ...(state.attemptEvidenceIds?.length ? { attemptEvidenceIds: [...state.attemptEvidenceIds] } : {}),
+                }
+                : {}),
             actor: {
                 id: state.actorId,
             },
@@ -47,6 +58,15 @@ export function buildReviewDecision(state) {
             appliedToClaimIds: candidate.projection?.claimId ? [candidate.projection.claimId] : undefined,
         },
     };
+    assertReviewResolutionConsistency(`ReviewDecision ${reviewDecision.metadata.name}`, {
+        status: reviewDecision.spec.status,
+        resolution: reviewDecision.spec.resolution,
+        resolutionReason: reviewDecision.spec.resolutionReason,
+        attemptEvidenceIds: reviewDecision.spec.attemptEvidenceIds,
+        actor: reviewDecision.spec.actor?.id,
+        reviewedAt: reviewDecision.spec.reviewedAt,
+    });
+    return reviewDecision;
 }
 /**
  * Stable versioned prompt identifier for the workbench decision card control.
@@ -177,6 +197,9 @@ function duplicateTargetIssues(items) {
     return issues;
 }
 function mapReviewApplyResultToActions(input) {
+    if (input.result.decision === "could-not-confirm") {
+        return [];
+    }
     const context = buildReviewApplyActionContext(input.result, input.itemByName, input.issues);
     if (!context || input.options.skip?.(context)) {
         return [];
@@ -442,6 +465,8 @@ function fieldCardState(item, decision) {
         return "kept";
     if (decision === "reject-proposed")
         return "rejected";
+    if (decision === "could-not-confirm")
+        return "could-not-confirm";
     if (item.spec.candidateSetStatus === "resolved")
         return "kept";
     return "review";
@@ -451,6 +476,7 @@ function chipLabel(state) {
         case "accepted": return "Accepted";
         case "kept": return "Kept current";
         case "rejected": return "Kept — flagged wrong";
+        case "could-not-confirm": return "Could not confirm";
         default: return "Needs review";
     }
 }
@@ -540,6 +566,7 @@ function renderFieldCard(item, session, presentationAdapter) {
             <input type="checkbox" class="wrongbox" data-testid="wrong-toggle" data-item-name="${escapeHtml(item.metadata.name)}">
             Suggestion was wrong
           </label>
+          <button class="btn unconfirmed" type="button" data-testid="could-not-confirm" data-item-name="${escapeHtml(item.metadata.name)}">Could not confirm</button>
         </div>
         <div class="decided">
           <span class="chip ${state}" data-testid="decided-chip">${chipLabel(state)}</span>
@@ -813,7 +840,7 @@ function renderProducerFeedbackTags(item) {
   `;
 }
 function renderFooterTally(session) {
-    const counts = { review: 0, accepted: 0, kept: 0, rejected: 0 };
+    const counts = { review: 0, accepted: 0, kept: 0, rejected: 0, "could-not-confirm": 0 };
     for (const item of session.items) {
         const state = fieldCardState(item, session.decisionsByItemName[item.metadata.name]);
         counts[state] += 1;
@@ -824,6 +851,7 @@ function renderFooterTally(session) {
         <span>Accepted <b data-testid="tally-accepted">${counts.accepted}</b></span>
         <span>Kept <b data-testid="tally-kept">${counts.kept}</b></span>
         <span>Flagged <b data-testid="tally-rejected">${counts.rejected}</b></span>
+        <span>Unconfirmed <b data-testid="tally-could-not-confirm">${counts["could-not-confirm"]}</b></span>
         <span>Remaining <b data-testid="tally-review">${counts.review}</b></span>
       </div>
     </footer>
@@ -973,10 +1001,13 @@ function createReviewWorkbenchController(root, startState, options) {
         // effectiveValue from snapshot + events alone. setDecision updates the
         // session before this runs, so the edit is already in state.
         const editedValue = itemName && decision === "accept-proposed" ? session.editedValuesByItemName?.[itemName] : undefined;
+        const attemptEvidenceIds = itemName && decision === "could-not-confirm"
+            ? session.attemptEvidenceIdsByItemName?.[itemName]
+            : undefined;
         const defaultData = decision
             ? (editedValue !== undefined
                 ? { workbenchDecision: decision, workbenchEditedValue: editedValue }
-                : { workbenchDecision: decision })
+                : { workbenchDecision: decision, ...(attemptEvidenceIds?.length ? { attemptEvidenceIds } : {}) })
             : undefined;
         events = [
             ...events,
@@ -989,6 +1020,13 @@ function createReviewWorkbenchController(root, startState, options) {
                 reviewDecisionName: item && decision ? `${item.metadata.name}-${decision}` : undefined,
                 candidateId: candidate?.id,
                 status: definition?.status,
+                ...(decision === "could-not-confirm"
+                    ? {
+                        resolution: "could_not_confirm",
+                        resolutionReason: note?.trim(),
+                        ...(attemptEvidenceIds ? { attemptEvidenceIds: [...attemptEvidenceIds] } : {}),
+                    }
+                    : {}),
                 rationale: note,
                 data: dataOverride ?? defaultData,
             }),
@@ -998,6 +1036,9 @@ function createReviewWorkbenchController(root, startState, options) {
         session = update(session);
     };
     const setDecision = (itemName, decision, rawEditedValue) => {
+        if (decision === "could-not-confirm" && !session.notesByItemName[itemName]?.trim()) {
+            throw new Error("Could not confirm requires a non-empty reason.");
+        }
         applySessionUpdate((current) => {
             const item = current.items.find((entry) => entry.metadata.name === itemName);
             const proposed = item?.spec.candidates.find((candidate) => candidate.role === "proposed");
@@ -1025,11 +1066,14 @@ function createReviewWorkbenchController(root, startState, options) {
             delete remainingDecisions[itemName];
             const remainingEdits = { ...current.editedValuesByItemName };
             delete remainingEdits[itemName];
+            const remainingAttemptEvidenceIds = { ...current.attemptEvidenceIdsByItemName };
+            delete remainingAttemptEvidenceIds[itemName];
             return {
                 ...current,
                 activeItemName: itemName,
                 decisionsByItemName: remainingDecisions,
                 editedValuesByItemName: remainingEdits,
+                attemptEvidenceIdsByItemName: remainingAttemptEvidenceIds,
             };
         });
         appendEvent("decision-changed", itemName, { workbenchDecision: null });
@@ -1082,6 +1126,9 @@ function queueSessionFromStartState(startState) {
         editedValuesByItemName: startState.editedValue !== undefined
             ? { [startState.item.metadata.name]: startState.editedValue }
             : {},
+        ...(startState.attemptEvidenceIds?.length
+            ? { attemptEvidenceIdsByItemName: { [startState.item.metadata.name]: [...startState.attemptEvidenceIds] } }
+            : {}),
         reviewedAt: startState.reviewedAt,
         actorId: startState.actorId,
     };
@@ -1125,6 +1172,23 @@ function bindFieldCardInteractions(root, controller) {
             controller.renderCurrentState();
         });
     });
+    root.querySelectorAll("[data-testid='could-not-confirm']").forEach((button) => {
+        button.addEventListener("click", () => {
+            const itemName = button.dataset.itemName ?? "";
+            const note = controller.currentSession().notesByItemName[itemName]?.trim() ?? "";
+            const field = button.closest("[data-testid='review-field']");
+            const textarea = field?.querySelector("[data-testid='reviewer-note']");
+            if (!note) {
+                textarea?.setCustomValidity?.("A reason is required when you could not confirm.");
+                textarea?.reportValidity?.();
+                textarea?.focus();
+                return;
+            }
+            textarea?.setCustomValidity?.("");
+            controller.setDecision(itemName, "could-not-confirm");
+            controller.renderCurrentState();
+        });
+    });
     root.querySelectorAll("[data-testid='undo-decision']").forEach((button) => {
         button.addEventListener("click", () => {
             controller.clearDecision(button.dataset.itemName ?? "");
@@ -1133,6 +1197,7 @@ function bindFieldCardInteractions(root, controller) {
     });
     root.querySelectorAll("[data-testid='reviewer-note']").forEach((textarea) => {
         textarea.addEventListener("input", () => {
+            textarea.setCustomValidity?.("");
             const itemName = textarea.dataset.itemName ?? "";
             controller.updateReviewerNote(itemName, textarea.value);
             refreshAuditPayloadForItem(textarea, controller, itemName);

package/dist/src/review-workbench/review-workbench.standalone.css

@@ -283,6 +283,7 @@ h1, h2, h3, p {
 .field[data-state="accepted"] .stripe { background: var(--k-positive); }
 .field[data-state="kept"] .stripe { background: var(--k-faint); }
 .field[data-state="rejected"] .stripe { background: var(--k-negative); }
+.field[data-state="could-not-confirm"] .stripe { background: var(--k-caution); }
 .field[data-state="review"] .stripe { background: var(--k-brand); }
 
 .fbody {
@@ -337,6 +338,7 @@ h1, h2, h3, p {
 .chip.accepted { color: var(--k-positive); background: var(--k-positive-wash); }
 .chip.kept { color: var(--k-muted); background: var(--k-sunken); }
 .chip.rejected { color: var(--k-negative); background: var(--k-negative-wash); }
+.chip.could-not-confirm { color: var(--k-caution); background: var(--k-caution-wash); }
 
 .frow1 .push {
   margin-left: auto;
@@ -601,6 +603,12 @@ h1, h2, h3, p {
   background: var(--k-panel-raised, var(--k-raised));
 }
 
+.btn.unconfirmed {
+  border-color: var(--k-caution);
+  color: var(--k-caution);
+  background: var(--k-caution-wash);
+}
+
 /* "Suggestion was wrong" — optional quiet calibration toggle on Keep current.
    Ticking it turns a keep-current decision into the reject signal. Not a third action. */
 .wrong {

package/dist/src/to-surface.js

@@ -27,11 +27,16 @@ export function buildSurveyTrustBundle(input, options = {}) {
         const extraction = requireMapValue(extractions, candidate.extractionId, "extraction");
         const rawSource = requireMapValue(rawSources, extraction.sourceId, "raw source");
         const review = selectReview(reviewsByCandidateSet.get(candidateSet.id) ?? [], candidate.id);
-        const status = projection.status ?? statusFor({ candidateSet, candidate, review });
-        assertProducerDiscipline({ status, review, extraction, rawSource, projection });
+        const projectionReview = review?.resolution === "could_not_confirm" ? undefined : review;
+        const unreviewedStatus = statusFor({ candidateSet, candidate });
+        const status = projection.status
+            ?? (review?.resolution === "could_not_confirm"
+                ? (unreviewedStatus === "disputed" ? unreviewedStatus : review.status)
+                : statusFor({ candidateSet, candidate, review }));
+        assertProducerDiscipline({ status, review, candidateSet, extraction, rawSource, projection });
         const claimValue = projection.value ?? candidate.value;
         const createdAt = projection.createdAt ?? extraction.extractedAt;
-        const updatedAt = projection.updatedAt ?? review?.reviewedAt ?? input.generatedAt;
+        const updatedAt = projection.updatedAt ?? projectionReview?.reviewedAt ?? input.generatedAt;
         const evidenceId = `${projection.id}.evidence.source`;
         const claim = {
             id: projection.id,
@@ -57,7 +62,15 @@ export function buildSurveyTrustBundle(input, options = {}) {
             },
             metadata: {
                 ...projection.metadata,
-                survey: buildSurveyMetadata({ projection, rawSource, extraction, candidateSet, candidate, review }),
+                survey: buildSurveyMetadata({
+                    projection,
+                    rawSource,
+                    extraction,
+                    candidateSet,
+                    candidate,
+                    review: projectionReview,
+                    comfortZoneReview: review,
+                }),
             },
         };
         // Promote the review's comfort-zone signal — and, when calibration is
@@ -82,7 +95,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
             }
             : undefined;
         const affirmedConclusion = status === "verified" || status === "assumed";
-        const calibrated = calibrationMetrics && review && affirmedConclusion
+        const calibrated = calibrationMetrics && projectionReview && affirmedConclusion
             ? lookupCalibratedValue(calibrationMetrics, extraction.extractor, extraction.target, calibrationMinSamples)
             : undefined;
         if (comfortZone || calibrated) {
@@ -91,13 +104,16 @@ export function buildSurveyTrustBundle(input, options = {}) {
                 ...(comfortZone ? { comfortZone } : {}),
             };
         }
-        if (options.reviewProofs && review) {
+        // Could-not-confirm stays byte-quiet at the Surface boundary. In particular,
+        // do not attach an anchor whose public observedAt would disclose review time;
+        // callers can persist/recompute Survey's canonical v3 proof separately.
+        if (options.reviewProofs && projectionReview) {
             claim.currentIntegrityAnchor = buildReviewProofAnchor({
                 rawSource,
                 extraction,
                 candidate,
                 candidateSet,
-                reviewOutcome: review,
+                reviewOutcome: projectionReview,
                 claim: {
                     ...projection,
                     value: claimValue,
@@ -129,16 +145,16 @@ export function buildSurveyTrustBundle(input, options = {}) {
                 confidence: candidate.confidence ?? extraction.confidence,
             },
         });
-        const rationale = review?.rationale ?? candidateSet.rationale;
+        const rationale = projectionReview?.rationale ?? candidateSet.rationale;
         events.push({
             id: `${projection.id}.event.${status}`,
             claimId: projection.id,
             status,
-            actor: projection.actor ?? review?.actor ?? projection.collectedBy,
+            actor: projection.actor ?? projectionReview?.actor ?? projection.collectedBy,
             method: projection.eventMethod ?? eventMethodFor(status, candidateSet),
-            evidenceIds: review?.evidenceIds?.length ? review.evidenceIds : [evidenceId],
-            createdAt: review?.reviewedAt ?? input.generatedAt,
-            verifiedAt: status === "verified" || status === "assumed" ? review?.reviewedAt ?? input.generatedAt : undefined,
+            evidenceIds: projectionReview?.evidenceIds?.length ? projectionReview.evidenceIds : [evidenceId],
+            createdAt: projectionReview?.reviewedAt ?? input.generatedAt,
+            verifiedAt: status === "verified" || status === "assumed" ? projectionReview?.reviewedAt ?? input.generatedAt : undefined,
             notes: rationale,
         });
     }
@@ -357,11 +373,11 @@ function buildSurveyMetadata(input) {
                 },
             }
             : {}),
-        ...(input.review?.withinComfortZone === false
+        ...(input.comfortZoneReview?.withinComfortZone === false
             ? {
                 comfortZone: {
                     withinComfortZone: false,
-                    ...(input.review.comfortZoneNote ? { note: input.review.comfortZoneNote } : {}),
+                    ...(input.comfortZoneReview.comfortZoneNote ? { note: input.comfortZoneReview.comfortZoneNote } : {}),
                 },
             }
             : {}),
@@ -384,6 +400,7 @@ function assertProducerDiscipline(input) {
         subject: `Claim ${input.projection.id}`,
         status: input.status,
         review: input.review,
+        candidateSetStatus: input.candidateSet.status,
     });
     if (input.rawSource.kind !== "manual-entry" && !input.extraction.locator) {
         throw new Error(`Claim ${input.projection.id} needs a source locator for ${input.rawSource.kind}`);

package/dist/src/types.d.ts

@@ -49,6 +49,7 @@ export interface CandidateSet {
     metadata?: Record<string, unknown>;
 }
 export type ReviewStatus = Extract<TrustStatus, "verified" | "assumed" | "rejected" | "proposed">;
+export type ReviewResolution = "accepted" | "rejected" | "held" | "could_not_confirm";
 export type ReviewAuthorizingKind = "explicit-statement" | "exchange" | "authorized-action";
 export interface ReviewAuthorizingExplicitStatement {
     kind: "explicit-statement";
@@ -74,6 +75,13 @@ export interface ReviewOutcome {
     candidateSetId: string;
     candidateId?: string;
     status: ReviewStatus;
+    /** Explicit terminal resolution for this review round. Absent outcomes retain
+     *  the legacy status-inference behavior. */
+    resolution?: ReviewResolution;
+    /** Required, non-empty explanation when resolution is `could_not_confirm`. */
+    resolutionReason?: string;
+    /** Evidence of attempts made before the reviewer concluded they could not confirm. */
+    attemptEvidenceIds?: string[];
     actor?: string;
     reviewedAt?: string;
     rationale?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -87,6 +87,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.54.0",
+    "@kontourai/traverse": "^0.19.0",
     "@kontourai/ui": "^1.1.0",
     "@playwright/test": "^1.60.0",
     "@types/node": "^25.6.0",