@kontourai/survey 1.14.0 → 1.16.0

package/README.md

@@ -105,6 +105,24 @@ Keep producer operational state outside Survey. Queue status, reviewer form stat
 
 When you build an `authorized-action` authorizing block outside the workbench, pair `buildAuthorizedActionAuthorizing` with `buildPromptRef({ module, component, version?, scheme? })` — `buildPromptRef` formats a well-formed, versioned `promptRef` (bare `"review-workbench/decision-card@v1"` or scheme-prefixed `"survey://<module>/<component>@v1"`) that `buildAuthorizedActionAuthorizing` accepts directly, instead of hand-formatting the string.
 
+## Review lifecycle
+
+`ReviewOutcome.resolution` optionally records the terminal result of a review
+round while preserving compatibility with outcomes that infer their result from
+`status`. The explicit `could_not_confirm` resolution requires a non-empty
+`resolutionReason`; `attemptEvidenceIds` may record evidence of what the reviewer
+tried. It is valid only with an unchanged `proposed` or `assumed` status.
+Other explicit resolutions must also agree with status: accepted is
+verified/assumed, rejected is rejected, and held is any non-rejected retained
+posture.
+
+Could-not-confirm is terminal for the review round, but it is not rejection,
+verification, or escalation. Surface projection stays quiet: the claim keeps its
+pre-review status, no attempt evidence is projected, and no review-derived
+freshness, validity, gap, or verification posture is added. The outcome remains
+available in Survey review records, canonical review proof v3, and the distinct
+`learning.could-not-confirm` producer-learning signal.
+
 ## Review Workbench embed
 
 **Web component** (shadow DOM, no framework required):
@@ -147,6 +165,32 @@ The embedded stylesheet is scoped to `.survey-workbench-embed` and bundles Conso
 
 `@kontourai/survey/review-workbench/standalone.css` exists for pages Survey owns entirely.
 
+### Theme it as your own brand
+
+The bundled `--k-*` token defaults are emitted in overridable form
+(`--k-brand: var(--k-brand, <default>)`), so a host brand is authoritative: set
+any `--k-*` token on an ancestor of the embed (or inline on the embed element,
+or the host element of the web component) and it propagates in — no need to
+out-specificity the embed's own selectors. Unset tokens keep their default, so
+you only declare what you re-brand.
+
+```css
+/* Your app's own palette drives the workbench — no Kontour branding. */
+.survey-workbench-embed {
+  --k-brand: var(--brand-accent);
+  --k-bg: var(--paper);
+  --k-panel: var(--paper-2);
+  --k-text: var(--ink);
+  --k-line: var(--hairline);
+  --k-font-ui: var(--font-body);
+  --k-radius-md: 2px;
+}
+```
+
+The full token list is in the [Consumer Integration Guide](docs/consumer-integration-guide.md).
+Prefer this over the built-in `theme-survey`/`theme-console`/… presets when the
+host app should read as itself.
+
 ## Review MCP
 
 Drive review-queue decisions from an MCP agent (Claude Desktop, Cursor, or any MCP host):
@@ -155,7 +199,7 @@ Drive review-queue decisions from an MCP agent (Claude Desktop, Cursor, or any M
 npx survey-review-mcp --session path/to/session.json
 ```
 
-Three tools: `survey_review_queue` (queue state), `survey_review_item` (item detail), and `survey_review_decide` (record a decision). Each queue and item call includes an embedded, fully self-contained review card with Accept / Hold / Reject buttons. See [docs/review-mcp.md](docs/review-mcp.md).
+Three tools: `survey_review_queue` (queue state), `survey_review_item` (item detail), and `survey_review_decide` (record a decision). Each queue and item call includes an embedded, fully self-contained review card with Accept / Hold / Reject / Could not confirm actions. See [docs/review-mcp.md](docs/review-mcp.md).
 
 At viewports ≤ 980 px, the queue panel becomes a slide-in drawer with a compact progress bar. At narrow container widths, `cqi`-based type scaling keeps candidate values from overflowing at 360 px. CSS custom properties (`--k-*`) inherit through the shadow boundary so the host can theme either mode without forking styles.
 

package/dist/src/calibration.d.ts

@@ -151,6 +151,7 @@ export interface CalibrationMetrics {
  * label. A sample is skipped when it carries no human label or no prediction:
  *
  * - status "proposed" (not yet reviewed);
+ * - resolution "could_not_confirm" (no human correctness label);
  * - a machine auto-accept, unless `includeAutoAccepted` is set;
  * - no `selectedCandidateId`, or the selected candidate / its confidence is
  *   missing or non-finite (no prediction to calibrate).

package/dist/src/calibration.js

@@ -37,6 +37,7 @@ const DEFAULT_MIN_BIN_SAMPLES = 1;
  * label. A sample is skipped when it carries no human label or no prediction:
  *
  * - status "proposed" (not yet reviewed);
+ * - resolution "could_not_confirm" (no human correctness label);
  * - a machine auto-accept, unless `includeAutoAccepted` is set;
  * - no `selectedCandidateId`, or the selected candidate / its confidence is
  *   missing or non-finite (no prediction to calibrate).
@@ -66,6 +67,10 @@ export function deriveCalibration(input, options = {}) {
     const samples = [];
     let skippedCount = 0;
     for (const outcome of input.reviewOutcomes) {
+        if (outcome.resolution === "could_not_confirm") {
+            skippedCount++;
+            continue;
+        }
         if (cutoff !== undefined) {
             const t = outcome.reviewedAt ? Date.parse(outcome.reviewedAt) : NaN;
             if (isNaN(t) || t < cutoff) {

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, ProvenanceResolution, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
+export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, ProvenanceResolution, RawSource, RawSourceKind, ReviewAuthorizing, ReviewAuthorizingAuthorizedAction, ReviewAuthorizingExchange, ReviewAuthorizingExplicitStatement, ReviewAuthorizingKind, ReviewOutcome, ReviewResolution, ReviewStatus, SurveyInput, } from "./types.js";
 export { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
 export type { CandidateRole, ClaimTargetHint, ProducerPolicy, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionMode, ReviewDecisionSpec, ReviewDecisionStatus, ReviewItem, ReviewItemSpec, ReviewItemStatus, ReviewLocator, ReviewResource, ReviewResourceApiVersion, ReviewResourceKind, ReviewSession, ReviewSessionEvent, ReviewSessionEventSpec, ReviewSessionEventStatus, ReviewSessionEventType, ReviewSessionSpec, ReviewSessionStatus, ReviewValueDescriptor, ReviewValueType, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";

package/dist/src/learning-projections.d.ts

@@ -1,6 +1,6 @@
 import type { SurveyInput } from "./types.js";
-export type LearningProjectionKind = "learning.comfort-zone" | "learning.escalation" | "learning.rejected-candidate";
-export type LearningProjectionSignal = "comfort-zone.outside" | "escalation.unresolved" | "rejected-candidate.reason";
+export type LearningProjectionKind = "learning.comfort-zone" | "learning.escalation" | "learning.rejected-candidate" | "learning.could-not-confirm";
+export type LearningProjectionSignal = "comfort-zone.outside" | "escalation.unresolved" | "rejected-candidate.reason" | "could-not-confirm.reason";
 export type LearningProjectionSeverity = "info" | "attention";
 export interface LearningProjection {
     id: string;

package/dist/src/learning-projections.js

@@ -40,6 +40,31 @@ export function buildSurveyLearningProjections(input) {
         }
     }
     for (const reviewOutcome of input.reviewOutcomes) {
+        if (reviewOutcome.resolution === "could_not_confirm") {
+            const target = candidateSetTargets.get(reviewOutcome.candidateSetId);
+            const claim = findClaimForReview(claimsByCandidateSet.get(reviewOutcome.candidateSetId) ?? [], reviewOutcome);
+            const resolutionReason = normalizeText(reviewOutcome.resolutionReason) ?? "(no reason recorded)";
+            projections.push({
+                id: `${reviewOutcome.id}.learning.could-not-confirm`,
+                kind: "learning.could-not-confirm",
+                source: input.source,
+                createdAt: reviewOutcome.reviewedAt ?? input.generatedAt,
+                target,
+                claimId: claim?.id,
+                reviewOutcomeId: reviewOutcome.id,
+                signal: "could-not-confirm.reason",
+                severity: "attention",
+                summary: `Could not confirm: ${resolutionReason}`,
+                metadata: {
+                    couldNotConfirm: {
+                        reason: resolutionReason,
+                        ...(reviewOutcome.attemptEvidenceIds?.length
+                            ? { attemptEvidenceIds: [...reviewOutcome.attemptEvidenceIds] }
+                            : {}),
+                    },
+                },
+            });
+        }
         if (reviewOutcome.withinComfortZone !== false)
             continue;
         const target = candidateSetTargets.get(reviewOutcome.candidateSetId);

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

@@ -30,6 +30,7 @@ const MCP_DECISION_MAP = {
     accept: "accept-proposed",
     hold: "keep-current",
     reject: "reject-proposed",
+    "could-not-confirm": "could-not-confirm",
 };
 async function readSessionFile(path) {
     const raw = await readFile(path, "utf8");
@@ -59,7 +60,7 @@ function queueSummaryText(snapshot, events) {
         `Active item: ${activeItem.metadata.name} (${activeItem.spec.target})`,
         ...(nextItem ? [`Next unresolved: ${nextItem}`] : ["All items resolved."]),
         ``,
-        `Session summary: accepted=${summary.accepted} keptCurrent=${summary.keptCurrent} rejected=${summary.rejected} escalated=${summary.escalated} unresolved=${summary.unresolved}`,
+        `Session summary: accepted=${summary.accepted} keptCurrent=${summary.keptCurrent} rejected=${summary.rejected} couldNotConfirm=${summary.couldNotConfirm ?? 0} escalated=${summary.escalated} unresolved=${summary.unresolved}`,
         ``,
         `Items:`,
         ...rows,
@@ -202,12 +203,13 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 .note-label{font-size:11px;color:var(--k-text-muted);margin-bottom:4px}
 .note-input{width:100%;background:var(--k-panel-raised);border:1px solid var(--k-line-strong);border-radius:var(--k-radius-sm);color:var(--k-text);font:inherit;font-size:12px;padding:7px 10px;resize:vertical;min-height:52px}
 .note-input:focus{outline:2px solid var(--k-brand);outline-offset:1px;border-color:transparent}
-.btn-row{display:grid;grid-template-columns:1fr 1fr 1fr;gap:8px;margin-top:10px}
+.btn-row{display:grid;grid-template-columns:1fr 1fr;gap:8px;margin-top:10px}
 .btn{padding:9px 4px;border:1px solid var(--k-line-strong);border-radius:var(--k-radius-sm);background:var(--k-panel-raised);color:var(--k-text-muted);font:inherit;font-size:12px;font-weight:600;cursor:pointer;transition:background .12s,color .12s,border-color .12s}
 .btn:hover{background:var(--k-panel);border-color:var(--k-brand);color:var(--k-text)}
 .btn-accept:hover,.btn-accept.active{background:color-mix(in srgb,var(--k-positive) 16%,transparent);border-color:var(--k-positive);color:var(--k-positive)}
 .btn-hold:hover,.btn-hold.active{background:color-mix(in srgb,var(--k-caution) 16%,transparent);border-color:var(--k-caution);color:var(--k-caution)}
 .btn-reject:hover,.btn-reject.active{background:color-mix(in srgb,var(--k-negative) 16%,transparent);border-color:var(--k-negative);color:var(--k-negative)}
+.btn-unconfirmed:hover,.btn-unconfirmed.active{background:color-mix(in srgb,var(--k-caution) 16%,transparent);border-color:var(--k-caution);color:var(--k-caution)}
 .feedback{font-size:11px;color:var(--k-text-faint);margin-top:8px;min-height:16px}
 </style>
 </head>
@@ -239,13 +241,14 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 
 <div class="divider"></div>
 
-<div class="note-label">Reviewer note (optional)</div>
+<div class="note-label">Reviewer note (required for Could not confirm)</div>
 <textarea class="note-input" id="note" placeholder="Add a rationale for this decision...">${escapeHtml(current.notesByItemName[item.metadata.name] ?? "")}</textarea>
 
 <div class="btn-row">
   <button class="btn btn-accept${decision === "accept-proposed" ? " active" : ""}" id="btn-accept">Accept proposed</button>
   <button class="btn btn-hold${decision === "keep-current" ? " active" : ""}" id="btn-hold">Hold / Keep current</button>
   <button class="btn btn-reject${decision === "reject-proposed" ? " active" : ""}" id="btn-reject">Reject proposed</button>
+  <button class="btn btn-unconfirmed${decision === "could-not-confirm" ? " active" : ""}" id="btn-unconfirmed">Could not confirm</button>
 </div>
 <div class="feedback" id="feedback"></div>
 
@@ -256,20 +259,29 @@ h1{font-size:15px;font-weight:700;margin:0 0 4px}
 
   function postDecision(decision) {
     var note = document.getElementById('note').value;
+    if (decision === 'could-not-confirm' && !note.trim()) {
+      document.getElementById('feedback').textContent = 'A reason is required when you could not confirm.';
+      document.getElementById('note').focus();
+      return false;
+    }
     window.parent.postMessage({
       jsonrpc: "2.0",
       id: msgId++,
       method: "tools/call",
       params: {
         name: "survey_review_decide",
-        arguments: { itemName: itemName, decision: decision, note: note || undefined }
+        arguments: decision === 'could-not-confirm'
+          ? { itemName: itemName, decision: decision, reason: note }
+          : { itemName: itemName, decision: decision, note: note || undefined }
       }
     }, "*");
+    return true;
   }
 
   document.getElementById('btn-accept').addEventListener('click', function () { postDecision('accept'); document.getElementById('feedback').textContent = 'Submitting accept…'; });
   document.getElementById('btn-hold').addEventListener('click', function () { postDecision('hold'); document.getElementById('feedback').textContent = 'Submitting hold…'; });
   document.getElementById('btn-reject').addEventListener('click', function () { postDecision('reject'); document.getElementById('feedback').textContent = 'Submitting reject…'; });
+  document.getElementById('btn-unconfirmed').addEventListener('click', function () { if (postDecision('could-not-confirm')) document.getElementById('feedback').textContent = 'Submitting could not confirm…'; });
 
   window.addEventListener('message', function (evt) {
     var data = evt.data;
@@ -347,10 +359,13 @@ async function toolItem(itemName, options) {
     }
     return content;
 }
-async function toolDecide(itemName, mcpDecision, note, options) {
+async function toolDecide(itemName, mcpDecision, note, attemptEvidenceIds, options) {
     const wbDecision = MCP_DECISION_MAP[mcpDecision];
     if (!wbDecision) {
-        throw new DomainError(`Invalid decision: ${mcpDecision}. Must be accept, hold, or reject.`);
+        throw new DomainError(`Invalid decision: ${mcpDecision}. Must be accept, hold, reject, or could-not-confirm.`);
+    }
+    if (wbDecision === "could-not-confirm" && !note?.trim()) {
+        throw new DomainError("survey_review_decide requires a non-empty reason for could-not-confirm");
     }
     const file = await readSessionFile(options.sessionPath);
     const { snapshot, events } = file;
@@ -378,6 +393,14 @@ async function toolDecide(itemName, mcpDecision, note, options) {
                 },
             }
             : {}),
+        ...(attemptEvidenceIds?.length
+            ? {
+                attemptEvidenceIdsByItemName: {
+                    ...current.attemptEvidenceIdsByItemName,
+                    [itemName]: [...attemptEvidenceIds],
+                },
+            }
+            : {}),
     };
     // Use the server session APIs for apply-path validation
     const record = createServerReviewSessionRecord({
@@ -518,19 +541,29 @@ async function handleLine(line, options, serverVersion) {
                         {
                             name: "survey_review_decide",
                             title: "Record a review decision",
-                            description: "Apply a decision to a review item and persist it to the session file. Decision must be accept (accept-proposed), hold (keep-current), or reject (reject-proposed). Domain failures return isError:true.",
+                            description: "Apply a decision to a review item and persist it to the session file. Decision must be accept, hold, reject, or could-not-confirm. Could-not-confirm requires a reason. Domain failures return isError:true.",
                             inputSchema: {
                                 type: "object",
                                 properties: {
                                     itemName: { type: "string", description: "The ReviewItem name to decide." },
                                     decision: {
                                         type: "string",
-                                        enum: ["accept", "hold", "reject"],
-                                        description: "accept = accept-proposed, hold = keep-current, reject = reject-proposed.",
+                                        enum: ["accept", "hold", "reject", "could-not-confirm"],
+                                        description: "accept = accept-proposed, hold = keep-current, reject = reject-proposed, could-not-confirm = terminal non-answer.",
                                     },
                                     note: { type: "string", description: "Optional reviewer note / rationale." },
+                                    reason: { type: "string", minLength: 1, description: "Required non-empty reason when decision is could-not-confirm." },
+                                    attemptEvidenceIds: {
+                                        type: "array",
+                                        items: { type: "string" },
+                                        description: "Optional evidence ids recording what was attempted before could-not-confirm.",
+                                    },
                                 },
                                 required: ["itemName", "decision"],
+                                allOf: [{
+                                        if: { properties: { decision: { const: "could-not-confirm" } }, required: ["decision"] },
+                                        then: { required: ["reason"] },
+                                    }],
                             },
                         },
                     ],
@@ -587,11 +620,16 @@ async function handleLine(line, options, serverVersion) {
                     const itemName = typeof toolArgs.itemName === "string" ? toolArgs.itemName : "";
                     const decision = typeof toolArgs.decision === "string" ? toolArgs.decision : "";
                     const note = typeof toolArgs.note === "string" ? toolArgs.note : undefined;
+                    const reason = typeof toolArgs.reason === "string" ? toolArgs.reason : undefined;
+                    const attemptEvidenceIds = Array.isArray(toolArgs.attemptEvidenceIds)
+                        && toolArgs.attemptEvidenceIds.every((value) => typeof value === "string")
+                        ? toolArgs.attemptEvidenceIds
+                        : undefined;
                     if (!itemName)
                         throw new DomainError("survey_review_decide requires itemName");
                     if (!decision)
                         throw new DomainError("survey_review_decide requires decision");
-                    content = await toolDecide(itemName, decision, note, options);
+                    content = await toolDecide(itemName, decision, decision === "could-not-confirm" ? reason : note, attemptEvidenceIds, options);
                 }
                 else {
                     send({ jsonrpc: "2.0", id, error: { code: -32602, message: `Unknown tool: ${name || "(missing name)"}` } });

package/dist/src/producer-discipline.d.ts

@@ -1,4 +1,5 @@
 import type { TrustStatus } from "@kontourai/surface";
+import type { CandidateSetStatus, ReviewResolution } from "./types.js";
 /**
  * Producer Discipline core — CONTEXT.md "Producer Discipline" /
  * "Source-of-Authority Observation".
@@ -28,13 +29,25 @@ import type { TrustStatus } from "@kontourai/surface";
  * src/index.ts.
  */
 export interface ReviewOutcomePosture {
+    status?: TrustStatus;
     actor?: string;
     reviewedAt?: string;
+    resolution?: ReviewResolution;
+    resolutionReason?: string;
+    attemptEvidenceIds?: readonly string[];
 }
+/** Explicit review resolutions refine (but may not contradict) status:
+ * accepted -> verified/assumed; rejected -> rejected; held -> any non-rejected
+ * pre-existing posture; could_not_confirm -> proposed/assumed with reviewer,
+ * time, and reason. */
+export declare function assertReviewResolutionConsistency(subject: string, review: ReviewOutcomePosture): void;
 export declare function assertReviewOutcomeDiscipline(input: {
     /** Message subject, e.g. `Claim ${id}` or `Source-of-authority observation ${id}` —
      *  each call site supplies its own noun so error text is unchanged. */
     subject: string;
     status: TrustStatus | undefined;
     review?: ReviewOutcomePosture;
+    /** Candidate-set conflict/escalation is an independent pre-review posture.
+     * A could-not-confirm round must preserve it as disputed, never downgrade it. */
+    candidateSetStatus?: CandidateSetStatus;
 }): void;

package/dist/src/producer-discipline.js

@@ -1,4 +1,45 @@
+/** Explicit review resolutions refine (but may not contradict) status:
+ * accepted -> verified/assumed; rejected -> rejected; held -> any non-rejected
+ * pre-existing posture; could_not_confirm -> proposed/assumed with reviewer,
+ * time, and reason. */
+export function assertReviewResolutionConsistency(subject, review) {
+    if (review.resolution === undefined)
+        return;
+    const statusAllowed = review.resolution === "accepted"
+        ? review.status === "verified" || review.status === "assumed"
+        : review.resolution === "rejected"
+            ? review.status === "rejected"
+            : review.resolution === "held"
+                ? review.status === "verified" || review.status === "assumed" || review.status === "proposed"
+                : review.status === "proposed" || review.status === "assumed";
+    if (!statusAllowed) {
+        throw new Error(`${subject} review resolution ${review.resolution} cannot use status ${review.status ?? "undefined"}`);
+    }
+    if (review.resolution !== "could_not_confirm")
+        return;
+    if (!review.resolutionReason?.trim()) {
+        throw new Error(`${subject} review resolution could_not_confirm requires a non-empty resolutionReason`);
+    }
+    if (!review.actor?.trim()) {
+        throw new Error(`${subject} review resolution could_not_confirm requires a review actor`);
+    }
+    if (!review.reviewedAt?.trim()) {
+        throw new Error(`${subject} review resolution could_not_confirm requires reviewedAt`);
+    }
+}
 export function assertReviewOutcomeDiscipline(input) {
+    if (input.review) {
+        assertReviewResolutionConsistency(input.subject, input.review);
+    }
+    if (input.review?.resolution === "could_not_confirm"
+        && (input.status === "verified" || input.status === "rejected")) {
+        throw new Error(`${input.subject} review resolution could_not_confirm cannot use status ${input.status}`);
+    }
+    if (input.review?.resolution === "could_not_confirm"
+        && (input.candidateSetStatus === "conflict" || input.candidateSetStatus === "escalated")
+        && input.status !== "disputed") {
+        throw new Error(`${input.subject} review resolution could_not_confirm cannot mask ${input.candidateSetStatus} as ${input.status}`);
+    }
     if (input.status !== "verified" && input.status !== "assumed")
         return;
     if (!input.review) {

package/dist/src/review-proof.d.ts

@@ -1,11 +1,13 @@
 import type { IntegrityAnchor } from "@kontourai/surface";
 import type { Candidate, CandidateSet, ClaimTarget, Extraction, RawSource, ReviewAuthorizing, ReviewOutcome } from "./types.js";
 export declare const REVIEW_PROOF_SCHEMA = "survey.review-proof";
-export declare const REVIEW_PROOF_SCHEMA_VERSION = 2;
+export declare const REVIEW_PROOF_SCHEMA_VERSION = 3;
 export declare const REVIEW_PROOF_PACKAGE_NAME = "@kontourai/survey";
-export declare const REVIEW_PROOF_CONTRACT_VERSION = "2";
+export declare const REVIEW_PROOF_CONTRACT_VERSION = "3";
 declare const LEGACY_REVIEW_PROOF_SCHEMA_VERSION = 1;
 declare const LEGACY_REVIEW_PROOF_CONTRACT_VERSION = "1";
+declare const REVIEW_PROOF_SCHEMA_VERSION_V2 = 2;
+declare const REVIEW_PROOF_CONTRACT_VERSION_V2 = "2";
 export interface ReviewProofInput {
     rawSource: RawSource;
     extraction: Extraction;
@@ -128,20 +130,32 @@ type CanonicalReviewAuthorizing = (Extract<ReviewAuthorizing, {
 export type CanonicalReviewProofPayloadV2 = Omit<CanonicalReviewProofPayloadV1, "schemaVersion" | "proof" | "reviewOutcome"> & {
     schemaVersion: 2;
     proof: Omit<CanonicalReviewProofPayloadV1["proof"], "schemaVersion" | "packageVersion"> & {
-        schemaVersion: typeof REVIEW_PROOF_SCHEMA_VERSION;
-        packageVersion: typeof REVIEW_PROOF_CONTRACT_VERSION;
+        schemaVersion: typeof REVIEW_PROOF_SCHEMA_VERSION_V2;
+        packageVersion: typeof REVIEW_PROOF_CONTRACT_VERSION_V2;
     };
     reviewOutcome?: NonNullable<CanonicalReviewProofPayloadV1["reviewOutcome"]> & {
         authorizing?: CanonicalReviewAuthorizing;
     };
 };
-export type CanonicalReviewProofPayload = CanonicalReviewProofPayloadV1 | CanonicalReviewProofPayloadV2;
-export declare function buildCanonicalReviewProofPayload(input: ReviewProofInput): CanonicalReviewProofPayloadV2;
+export type CanonicalReviewProofPayloadV3 = Omit<CanonicalReviewProofPayloadV2, "schemaVersion" | "proof" | "reviewOutcome"> & {
+    schemaVersion: 3;
+    proof: Omit<CanonicalReviewProofPayloadV2["proof"], "schemaVersion" | "packageVersion"> & {
+        schemaVersion: typeof REVIEW_PROOF_SCHEMA_VERSION;
+        packageVersion: typeof REVIEW_PROOF_CONTRACT_VERSION;
+    };
+    reviewOutcome?: NonNullable<CanonicalReviewProofPayloadV2["reviewOutcome"]> & {
+        resolution?: ReviewOutcome["resolution"];
+        resolutionReason?: string;
+        attemptEvidenceIds?: string[];
+    };
+};
+export type CanonicalReviewProofPayload = CanonicalReviewProofPayloadV1 | CanonicalReviewProofPayloadV2 | CanonicalReviewProofPayloadV3;
+export declare function buildCanonicalReviewProofPayload(input: ReviewProofInput): CanonicalReviewProofPayloadV3;
 export declare function canonicalReviewProofJson(payload: CanonicalReviewProofPayload): string;
 export declare function hashCanonicalReviewProofPayload(payload: CanonicalReviewProofPayload): string;
 /**
- * Verifies the integrity hash of a persisted v1 or v2 canonical review proof.
- * Envelope compatibility and v2 authorizing admissibility are checked before
+ * Verifies the integrity hash of a persisted v1, v2, or v3 canonical review proof.
+ * Envelope compatibility and version-specific admissibility are checked before
  * the expected hash is compared.
  */
 export declare function verifyCanonicalReviewProofPayload(payload: unknown, expectedHash: string): boolean;

package/dist/src/review-proof.js

@@ -1,15 +1,21 @@
 import { createHash } from "node:crypto";
 import { validateAuthorizing } from "./review-authorizing.js";
+import { assertReviewResolutionConsistency } from "./producer-discipline.js";
 export const REVIEW_PROOF_SCHEMA = "survey.review-proof";
-export const REVIEW_PROOF_SCHEMA_VERSION = 2;
+export const REVIEW_PROOF_SCHEMA_VERSION = 3;
 export const REVIEW_PROOF_PACKAGE_NAME = "@kontourai/survey";
 // Version of the review proof contract emitted by this helper. This is intentionally
 // independent from the npm package release version because it participates in hashes.
-export const REVIEW_PROOF_CONTRACT_VERSION = "2";
+export const REVIEW_PROOF_CONTRACT_VERSION = "3";
 const LEGACY_REVIEW_PROOF_SCHEMA_VERSION = 1;
 const LEGACY_REVIEW_PROOF_CONTRACT_VERSION = "1";
+const REVIEW_PROOF_SCHEMA_VERSION_V2 = 2;
+const REVIEW_PROOF_CONTRACT_VERSION_V2 = "2";
 export function buildCanonicalReviewProofPayload(input) {
     assertCandidateConsistency(input);
+    if (input.reviewOutcome) {
+        assertReviewResolutionConsistency("Canonical review proof", input.reviewOutcome);
+    }
     return {
         schemaVersion: REVIEW_PROOF_SCHEMA_VERSION,
         proof: {
@@ -77,6 +83,13 @@ export function buildCanonicalReviewProofPayload(input) {
                 candidateSetId: input.reviewOutcome.candidateSetId,
                 candidateId: input.reviewOutcome.candidateId,
                 status: input.reviewOutcome.status,
+                ...(input.reviewOutcome.resolution !== undefined ? { resolution: input.reviewOutcome.resolution } : {}),
+                ...(input.reviewOutcome.resolutionReason !== undefined
+                    ? { resolutionReason: input.reviewOutcome.resolutionReason }
+                    : {}),
+                ...(input.reviewOutcome.attemptEvidenceIds
+                    ? { attemptEvidenceIds: [...input.reviewOutcome.attemptEvidenceIds].sort() }
+                    : {}),
                 actor: input.reviewOutcome.actor,
                 reviewedAt: input.reviewOutcome.reviewedAt,
                 rationale: input.reviewOutcome.rationale,
@@ -187,8 +200,8 @@ export function hashCanonicalReviewProofPayload(payload) {
     return createHash("sha256").update(canonicalReviewProofJson(payload)).digest("hex");
 }
 /**
- * Verifies the integrity hash of a persisted v1 or v2 canonical review proof.
- * Envelope compatibility and v2 authorizing admissibility are checked before
+ * Verifies the integrity hash of a persisted v1, v2, or v3 canonical review proof.
+ * Envelope compatibility and version-specific admissibility are checked before
  * the expected hash is compared.
  */
 export function verifyCanonicalReviewProofPayload(payload, expectedHash) {
@@ -210,7 +223,30 @@ export function verifyCanonicalReviewProofPayload(payload, expectedHash) {
                 || packageVersion !== LEGACY_REVIEW_PROOF_CONTRACT_VERSION) {
                 return false;
             }
-            if (isRecord(reviewOutcome) && Object.prototype.hasOwnProperty.call(reviewOutcome, "authorizing")) {
+            if (isRecord(reviewOutcome)
+                && (Object.prototype.hasOwnProperty.call(reviewOutcome, "authorizing")
+                    || Object.prototype.hasOwnProperty.call(reviewOutcome, "resolution")
+                    || Object.prototype.hasOwnProperty.call(reviewOutcome, "resolutionReason")
+                    || Object.prototype.hasOwnProperty.call(reviewOutcome, "attemptEvidenceIds"))) {
+                return false;
+            }
+        }
+        else if (schemaVersion === REVIEW_PROOF_SCHEMA_VERSION_V2) {
+            if (proofSchemaVersion !== REVIEW_PROOF_SCHEMA_VERSION_V2 || packageVersion !== REVIEW_PROOF_CONTRACT_VERSION_V2) {
+                return false;
+            }
+            if (reviewOutcome !== undefined && !isRecord(reviewOutcome))
+                return false;
+            if (isRecord(reviewOutcome)
+                && Object.prototype.hasOwnProperty.call(reviewOutcome, "authorizing")
+                && reviewOutcome.authorizing !== undefined
+                && validateAuthorizing(reviewOutcome.authorizing).length > 0) {
+                return false;
+            }
+            if (isRecord(reviewOutcome)
+                && (Object.prototype.hasOwnProperty.call(reviewOutcome, "resolution")
+                    || Object.prototype.hasOwnProperty.call(reviewOutcome, "resolutionReason")
+                    || Object.prototype.hasOwnProperty.call(reviewOutcome, "attemptEvidenceIds"))) {
                 return false;
             }
         }
@@ -226,6 +262,21 @@ export function verifyCanonicalReviewProofPayload(payload, expectedHash) {
                 && validateAuthorizing(reviewOutcome.authorizing).length > 0) {
                 return false;
             }
+            if (isRecord(reviewOutcome)) {
+                if (reviewOutcome.resolution !== undefined
+                    && reviewOutcome.resolution !== "accepted"
+                    && reviewOutcome.resolution !== "rejected"
+                    && reviewOutcome.resolution !== "held"
+                    && reviewOutcome.resolution !== "could_not_confirm") {
+                    return false;
+                }
+                if (reviewOutcome.attemptEvidenceIds !== undefined
+                    && (!Array.isArray(reviewOutcome.attemptEvidenceIds)
+                        || reviewOutcome.attemptEvidenceIds.some((id) => typeof id !== "string"))) {
+                    return false;
+                }
+                assertReviewResolutionConsistency("Canonical review proof", reviewOutcome);
+            }
         }
         else {
             return false;

package/dist/src/review-resource.d.ts

@@ -168,6 +168,9 @@ export interface ReviewDecisionSpec {
     reviewItemName: string;
     candidateId?: string;
     status: ReviewOutcome["status"];
+    resolution?: ReviewOutcome["resolution"];
+    resolutionReason?: string;
+    attemptEvidenceIds?: string[];
     actor?: ReviewActor;
     reviewedAt?: string;
     rationale?: string;
@@ -216,6 +219,9 @@ export interface ReviewSessionEventSpec {
     reviewDecisionName?: string;
     candidateId?: string;
     status?: ReviewOutcome["status"];
+    resolution?: ReviewOutcome["resolution"];
+    resolutionReason?: string;
+    attemptEvidenceIds?: string[];
     rationale?: string;
     data?: Record<string, unknown>;
 }

package/dist/src/review-workbench/producer-decision-mode.js

@@ -15,6 +15,8 @@ const KNOWN_DECISION_MODES = new Set([
  * `unknown-decision-mode` issue.
  */
 export function validateReviewDecisionMode(item, result) {
+    if (result.decision === "could-not-confirm")
+        return [];
     const decisionMode = item.spec.producerPolicy?.decisionMode;
     if (decisionMode === undefined) {
         return [];

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

@@ -1,6 +1,6 @@
 import { type ReviewCandidate, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewSessionEventSpec } from "../../src/review-resource.js";
-export type ReviewWorkbenchDecision = "accept-proposed" | "keep-current" | "reject-proposed";
-export type ReviewQueueRowStatus = "pending" | "in-review" | "resolved" | "rejected" | "escalated";
+export type ReviewWorkbenchDecision = "accept-proposed" | "keep-current" | "reject-proposed" | "could-not-confirm";
+export type ReviewQueueRowStatus = "pending" | "in-review" | "resolved" | "rejected" | "could-not-confirm" | "escalated";
 export declare const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export declare const defaultReviewSessionName = "review-workbench-session";
 export interface ReviewWorkbenchState {
@@ -15,6 +15,7 @@ export interface ReviewWorkbenchState {
      * proposed candidate's original value applies.
      */
     readonly editedValue?: unknown;
+    readonly attemptEvidenceIds?: readonly string[];
 }
 export interface ReviewQueueSessionState {
     readonly items: readonly ReviewItem[];
@@ -30,11 +31,13 @@ export interface ReviewQueueSessionState {
      * original value").
      */
     readonly editedValuesByItemName?: Readonly<Record<string, unknown>>;
+    readonly attemptEvidenceIdsByItemName?: Readonly<Record<string, readonly string[]>>;
 }
 export interface ReviewSessionSummary {
     readonly accepted: number;
     readonly keptCurrent: number;
     readonly rejected: number;
+    readonly couldNotConfirm?: number;
     readonly escalated: number;
     readonly unresolved: number;
 }
@@ -57,6 +60,12 @@ export declare const workbenchDecisionDefinitions: {
         candidateRole: "proposed";
         status: "rejected";
     };
+    "could-not-confirm": {
+        label: string;
+        effect: string;
+        candidateRole: "proposed";
+        status: "proposed";
+    };
 };
 export declare function initialReviewWorkbenchState(item?: ReviewItem): ReviewWorkbenchState;
 export declare function initialReviewQueueSessionState(items?: readonly ReviewItem[]): ReviewQueueSessionState;