@kontourai/survey 1.11.0 → 1.13.0

package/dist/example-data/public-directory-review-resource.d.ts

@@ -40,6 +40,7 @@ export declare const publicDirectoryReviewItemExample: {
                 confidence: number;
                 extractor: string;
                 extractedAt: string;
+                model?: undefined;
             };
             claimTarget: {
                 claimId: string;
@@ -91,6 +92,7 @@ export declare const publicDirectoryReviewItemExample: {
                 target: string;
                 confidence: number;
                 extractor: string;
+                model: string;
                 extractedAt: string;
             };
             claimTarget: {

package/dist/example-data/public-directory-review-resource.js

@@ -92,6 +92,7 @@ export const publicDirectoryReviewItemExample = {
                     target: "availabilityStatus",
                     confidence: 0.82,
                     extractor: "example-crawl",
+                    model: "example-extraction-model-2026-05",
                     extractedAt: "2026-05-31T15:00:00.000Z",
                 },
                 claimTarget: {

package/dist/examples/review-workbench/downstream-public-directory-adapter.js

@@ -110,7 +110,8 @@ function proposedReviewCandidate(proposal, field, diff, selectedRole) {
         sourceRef: diff.sourceUrl ?? proposal.sourceUrl,
         observedAt: proposal.createdAt,
         excerpt: diff.excerpt ?? `Proposed ${field} value from downstream extraction.`,
-        extractor: proposal.extractionModel,
+        extractor: "downstream-directory-extractor",
+        model: proposal.extractionModel,
         extractedAt: proposal.createdAt,
         confidence: diff.confidence,
         sourceRank: selectedRole === "proposed" ? 1 : 2,
@@ -193,6 +194,7 @@ function candidateExtraction(args, extractionId) {
         target: args.field,
         confidence: args.confidence,
         extractor: args.extractor,
+        ...(args.model ? { model: args.model } : {}),
         extractedAt: args.extractedAt,
     };
 }

package/dist/src/index.d.ts

@@ -1,7 +1,7 @@
 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 { 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, SourceReference, SurveyRecordProjectionHint, } 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";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";

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

@@ -35,7 +35,16 @@ export interface ExtractionReference {
     extractionId?: string;
     target: string;
     confidence?: number;
+    /** The extraction tool/pipeline that produced this candidate (e.g. a crawler or parser). */
     extractor?: string;
+    /**
+     * The model or model-version that generated this candidate, when the producer
+     * knows it (e.g. an LLM id or a dated extraction-model tag). Distinct from
+     * `extractor` (the tool): a reviewer wants to know *which model* proposed a
+     * value for trust/calibration. Producer-provided provenance; Survey only
+     * carries and displays it.
+     */
+    model?: string;
     extractedAt?: string;
 }
 export interface ClaimTargetHint {
@@ -96,6 +105,28 @@ export interface ReviewCandidate {
     projection?: SurveyRecordProjectionHint;
     producer?: Record<string, unknown>;
 }
+/**
+ * Well-known neutral value-type vocabulary for {@link ReviewValueDescriptor}.
+ * Survey defines NO field-schema system of its own; this deliberately MIRRORS
+ * the shape an upstream field-schema owner already uses (e.g. traverse's
+ * `TargetFieldSchema.type` / `ExtractionProposal.valueType`), so a producer can
+ * carry a reviewed field's declared type down to the review UI WITHOUT Survey
+ * importing that owner's package (structural match, zero coupling).
+ */
+export type ReviewValueType = "string" | "number" | "boolean" | "date" | "enum" | "array" | "object";
+/**
+ * Optional, producer-supplied descriptor of a reviewed field's declared value
+ * shape. Purely descriptive: the workbench uses it ONLY to pick a typed editor
+ * (an enum `<select>`, a date/number input) and to validate a reviewer's edit
+ * before "Use proposed". Survey never re-derives, coerces, or overrides a
+ * candidate's value from it — a producer can still surface an out-of-shape
+ * candidate, which is exactly what a typed reviewer catches.
+ */
+export interface ReviewValueDescriptor {
+    type: ReviewValueType;
+    /** Allowed values — meaningful with `type: "enum"`; ignored otherwise. */
+    enumValues?: string[];
+}
 export interface ReviewItemSpec {
     target: string;
     candidates: ReviewCandidate[];
@@ -104,6 +135,13 @@ export interface ReviewItemSpec {
     rationale?: string;
     producerPolicy?: ProducerPolicy;
     projection?: SurveyRecordProjectionHint;
+    /**
+     * Optional neutral descriptor of the reviewed field's declared value type.
+     * When present, the workbench renders a typed editor and validates a
+     * reviewer's inline edit against it before accepting the proposed value.
+     * Absent → a plain text editor with no validation (today's behavior).
+     */
+    valueDescriptor?: ReviewValueDescriptor;
 }
 export interface ReviewItemStatus {
     observedCandidateCount?: number;
@@ -130,6 +168,15 @@ export interface ReviewDecisionSpec {
      *  their own admissible block. */
     authorizing?: ReviewAuthorizing;
     projection?: SurveyRecordProjectionHint;
+    /**
+     * Reviewer-edited override for the proposed candidate's value, captured when the
+     * reviewer edits the inline proposed-value editor before choosing "Use proposed".
+     * Only meaningful when the decision selects the proposed candidate. Downstream
+     * consumers should read the effective value as `editedValue ?? <selected candidate value>`
+     * rather than assuming the candidate's original value was applied verbatim.
+     * Additive/optional: absent means the candidate's original value was used unchanged.
+     */
+    editedValue?: unknown;
 }
 export interface ReviewDecisionStatus {
     appliedToClaimIds?: string[];

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

@@ -9,6 +9,12 @@ export interface ReviewWorkbenchState {
     readonly decision?: ReviewWorkbenchDecision;
     readonly reviewedAt: string;
     readonly actorId: string;
+    /**
+     * Reviewer-edited override for the item's proposed value (inline edit in the
+     * field-diff card). Additive/optional: undefined means no edit was made and the
+     * proposed candidate's original value applies.
+     */
+    readonly editedValue?: unknown;
 }
 export interface ReviewQueueSessionState {
     readonly items: readonly ReviewItem[];
@@ -17,6 +23,13 @@ export interface ReviewQueueSessionState {
     readonly decisionsByItemName: Readonly<Record<string, ReviewWorkbenchDecision>>;
     readonly reviewedAt: string;
     readonly actorId: string;
+    /**
+     * Reviewer-edited overrides for proposed values, keyed by ReviewItem name.
+     * Additive/optional: a session built before this field existed behaves exactly
+     * as before (every lookup resolves to undefined, meaning "use the candidate's
+     * original value").
+     */
+    readonly editedValuesByItemName?: Readonly<Record<string, unknown>>;
 }
 export interface ReviewSessionSummary {
     readonly accepted: number;
@@ -53,8 +66,25 @@ export declare function deriveQueueRowStatus(item: ReviewItem, session: ReviewQu
 export declare function nextUnresolvedItemName(session: ReviewQueueSessionState): string | undefined;
 export declare function reviewSessionSummary(session: ReviewQueueSessionState): ReviewSessionSummary;
 export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
+/**
+ * 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
+ * candidate's original value. Consumers reading `ReviewWorkbenchResult` should
+ * prefer `effectiveValue`/`effectiveDisplayValue`, which are already computed with
+ * this rule; this helper exists for callers deriving the value from raw session
+ * state directly.
+ */
+export declare function effectiveValueForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision, editedValue?: unknown): unknown;
 export declare function selectedCandidateRole(state: ReviewWorkbenchState): ReviewCandidate["role"] | undefined;
 export declare function buildReviewSessionResource(session: ReviewQueueSessionState, events?: readonly ReviewSessionEvent[], sessionName?: string): ReviewSession;
 export declare function buildReviewSessionEvents(session: ReviewQueueSessionState, sessionName?: string): ReviewSessionEvent[];
 export declare function replayReviewSessionEvents(startState: ReviewQueueSessionState, events: readonly ReviewSessionEvent[]): ReviewQueueSessionState;
+/**
+ * Detects the explicit "clear this ReviewItem's decision" replay signal (emitted
+ * by the workbench's "Change" / undo control): a decision event whose
+ * `data.workbenchDecision` is the literal `null` sentinel, as opposed to `undefined`
+ * (no decision info present — event is ignored by replay, same as before this
+ * feature existed).
+ */
+export declare function isClearedWorkbenchDecisionEvent(event: ReviewSessionEvent): boolean;
 export declare function buildReviewSessionEvent(session: ReviewQueueSessionState, spec: Omit<ReviewSessionEventSpec, "actor">): ReviewSessionEvent;

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

@@ -37,6 +37,7 @@ export function initialReviewQueueSessionState(items = reviewWorkbenchQueueExamp
         activeItemName: items[0]?.metadata.name ?? "",
         notesByItemName: {},
         decisionsByItemName: {},
+        editedValuesByItemName: {},
         reviewedAt: "2026-06-04T00:00:00.000Z",
         actorId: "review-workbench-operator",
     };
@@ -47,6 +48,7 @@ export function currentReviewWorkbenchState(session) {
         item,
         note: session.notesByItemName[item.metadata.name] ?? "",
         decision: session.decisionsByItemName[item.metadata.name],
+        editedValue: session.editedValuesByItemName?.[item.metadata.name],
         reviewedAt: session.reviewedAt,
         actorId: session.actorId,
     };
@@ -117,6 +119,18 @@ export function candidateForDecision(item, decision) {
     }
     return candidate;
 }
+/**
+ * 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
+ * candidate's original value. Consumers reading `ReviewWorkbenchResult` should
+ * prefer `effectiveValue`/`effectiveDisplayValue`, which are already computed with
+ * this rule; this helper exists for callers deriving the value from raw session
+ * state directly.
+ */
+export function effectiveValueForDecision(item, decision, editedValue) {
+    const candidate = candidateForDecision(item, decision);
+    return decision === "accept-proposed" && editedValue !== undefined ? editedValue : candidate.value;
+}
 export function selectedCandidateRole(state) {
     if (!state.decision) {
         return undefined;
@@ -238,6 +252,10 @@ export function replayReviewSessionEvents(startState, events) {
         }
         if ((event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
             && event.spec.reviewItemName) {
+            if (isClearedWorkbenchDecisionEvent(event)) {
+                const { [event.spec.reviewItemName]: _removed, ...remainingDecisions } = session.decisionsByItemName;
+                return { ...session, decisionsByItemName: remainingDecisions };
+            }
             const decision = workbenchDecisionFromEvent(event);
             return decision
                 ? {
@@ -252,6 +270,18 @@ export function replayReviewSessionEvents(startState, events) {
         return session;
     }, startState);
 }
+/**
+ * Detects the explicit "clear this ReviewItem's decision" replay signal (emitted
+ * by the workbench's "Change" / undo control): a decision event whose
+ * `data.workbenchDecision` is the literal `null` sentinel, as opposed to `undefined`
+ * (no decision info present — event is ignored by replay, same as before this
+ * feature existed).
+ */
+export function isClearedWorkbenchDecisionEvent(event) {
+    return event.spec.data !== undefined
+        && "workbenchDecision" in event.spec.data
+        && event.spec.data.workbenchDecision === null;
+}
 export function buildReviewSessionEvent(session, spec) {
     return {
         apiVersion: reviewResourceApiVersion,

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

@@ -1,4 +1,4 @@
-import { candidateForDecision, workbenchDecisionDefinitions, } from "./review-queue-session.js";
+import { candidateForDecision, isClearedWorkbenchDecisionEvent, workbenchDecisionDefinitions, } from "./review-queue-session.js";
 export function validateReviewSessionEventsForSnapshot(snapshot, events) {
     const itemsByName = new Map(snapshot.items.map((item) => [item.metadata.name, item]));
     const sequenceIssues = validateEventSequence(events);
@@ -35,7 +35,12 @@ export function validateReviewSessionEventsForSnapshot(snapshot, events) {
                 message: `ReviewSessionEvent ${event.metadata.name} is a decision event but does not reference a ReviewItem.`,
             });
         }
-        if (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted") {
+        if ((event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted")
+            && isClearedWorkbenchDecisionEvent(event)) {
+            // Explicit "clear this ReviewItem's decision" signal (undo). No candidate/status
+            // expectations apply — the event carries no selected candidate.
+        }
+        else if (event.spec.eventType === "decision-changed" || event.spec.eventType === "decision-submitted") {
             const decision = replayableWorkbenchDecision(event.spec.data?.workbenchDecision);
             if (!decision) {
                 issues.push({