@kontourai/survey 1.12.0 → 1.13.0

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

@@ -105,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[];
@@ -113,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;

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

@@ -558,7 +558,8 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   margin-top: 8px;
 }
 
-.survey-workbench-embed .editrow input{
+.survey-workbench-embed .editrow input,
+.survey-workbench-embed .editrow select{
   flex: 1;
   min-width: 0;
   font-size: 13.5px;
@@ -569,7 +570,8 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   padding: 6px 9px;
 }
 
-.survey-workbench-embed .editrow input:focus-visible{
+.survey-workbench-embed .editrow input:focus-visible,
+.survey-workbench-embed .editrow select:focus-visible{
   outline: 2px solid var(--k-brand);
   outline-offset: 1px;
   border-color: var(--k-brand);
@@ -581,6 +583,20 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   white-space: nowrap;
 }
 
+/* Validation message for a typed proposed-value edit (hidden until the mount
+   handler blocks a "Use proposed" on an out-of-shape value). */
+.survey-workbench-embed .verr{
+  display: block;
+  margin-top: 5px;
+  font-size: 11.5px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.survey-workbench-embed .verr[hidden]{
+  display: none;
+}
+
 /* confidence + provenance */
 
 .survey-workbench-embed .prov{

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

@@ -555,7 +555,8 @@
   margin-top: 8px;
 }
 
-.survey-workbench-embed .editrow input{
+.survey-workbench-embed .editrow input,
+.survey-workbench-embed .editrow select{
   flex: 1;
   min-width: 0;
   font-size: 13.5px;
@@ -566,7 +567,8 @@
   padding: 6px 9px;
 }
 
-.survey-workbench-embed .editrow input:focus-visible{
+.survey-workbench-embed .editrow input:focus-visible,
+.survey-workbench-embed .editrow select:focus-visible{
   outline: 2px solid var(--k-brand);
   outline-offset: 1px;
   border-color: var(--k-brand);
@@ -578,6 +580,20 @@
   white-space: nowrap;
 }
 
+/* Validation message for a typed proposed-value edit (hidden until the mount
+   handler blocks a "Use proposed" on an out-of-shape value). */
+.survey-workbench-embed .verr{
+  display: block;
+  margin-top: 5px;
+  font-size: 11.5px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.survey-workbench-embed .verr[hidden]{
+  display: none;
+}
+
 /* confidence + provenance */
 
 .survey-workbench-embed .prov{

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

@@ -1,7 +1,7 @@
 import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type ReviewWorkbenchState } from "./review-queue-session.js";
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import { type ReviewPresentationAdapter } from "./review-presentation.js";
-import { type ReviewCandidate, type ReviewDecision, type ReviewItem, type ReviewSession, type ReviewSessionEvent } from "../review-resource.js";
+import { type ReviewCandidate, type ReviewDecision, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewValueDescriptor } from "../review-resource.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, type ReviewQueueRowStatus, type ReviewQueueSessionState, type ReviewSessionSummary, type ReviewWorkbenchDecision, type ReviewWorkbenchState, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, type ReviewCandidatePresentation, type ReviewCandidatePresentationContext, type ReviewItemPresentation, type ReviewItemPresentationContext, type ReviewPresentationAdapter, type ReviewPresentationLink, type ReviewResultPresentation, type ReviewTracePresentationContext, type ReviewTraceRef, type ReviewValuePresentationContext, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, type PreviewAuthorityTrace, type PreviewCandidateHistory, type PreviewClaim, type PreviewIntegrityPosture, type PreviewReviewEvent, type PreviewSourceAuthority, type PreviewSourceEvidence, type SurfaceProjectionPreview, } from "./review-surface-preview.js";
@@ -179,6 +179,16 @@ export declare function createPersistentReviewSessionEventStore(options: Persist
 export declare function renderReviewWorkbenchHtml(state: ReviewWorkbenchState | ReviewQueueSessionState, _events?: readonly ReviewSessionEvent[], options?: {
     readonly presentationAdapter?: ReviewPresentationAdapter;
 }): string;
+/**
+ * Validates a reviewer's raw (string) edit of a proposed value against the
+ * field's neutral {@link ReviewValueDescriptor}, returning a human-readable
+ * error message when the value violates the declared type/enum constraint, or
+ * `undefined` when it is acceptable — including when there is no descriptor or
+ * the type carries no single-line constraint (string/array/object). This is a
+ * FORMAT check only: it never coerces or rewrites the value (the workbench
+ * stores the reviewer's string edit unchanged, as it did before typed editors).
+ */
+export declare function validateProposedValue(descriptor: ReviewValueDescriptor | undefined, rawValue: string): string | undefined;
 export declare function mountReviewWorkbench(root: HTMLElement, startState?: ReviewQueueSessionState | ReviewWorkbenchState, options?: MountReviewWorkbenchOptions): void;
 export declare function browserReviewWorkbenchStartState(): ReviewQueueSessionState | ReviewWorkbenchState | undefined;
 declare global {

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

@@ -581,25 +581,131 @@ function renderDiffRow(item, current, proposed, targetLabel, decided, effectiveP
  * from an enum's allowed values, or date/number/boolean inputs — driven by an
  * optional neutral value-type descriptor, without touching the rest of the
  * field-card renderer. Survey deliberately has no value-type/enum system of its
- * own (that belongs to the upstream field-schema owner), so today this always
- * renders a plain text input, matching the approved mockup.
+ * own (that belongs to the upstream field-schema owner) — but a producer MAY
+ * carry a field's declared shape down via the neutral
+ * {@link ReviewValueDescriptor} on the item spec. When present, this renders a
+ * typed control (an enum `<select>`, a date/number input, a true/false select)
+ * and a validation-error slot the mount handler populates before "Use
+ * proposed"; when absent, it renders the plain text input, matching the
+ * approved mockup.
  */
 function renderProposedValueEditor(item, proposed, targetLabel) {
+    const descriptor = item.spec.valueDescriptor;
     const valueText = formatValue(proposed.value);
-    return `
-    <div class="editrow">
-      <input
-        type="text"
+    const commonAttrs = `
         class="proposed-value-input"
         data-testid="edit-proposed-value"
         data-item-name="${escapeHtml(item.metadata.name)}"
-        value="${escapeHtml(valueText)}"
-        aria-label="Edit proposed ${escapeHtml(targetLabel)}"
-      >
-      <span class="ehint">editable</span>
+        aria-label="Edit proposed ${escapeHtml(targetLabel)}"`;
+    const control = renderTypedProposedControl(descriptor, valueText, commonAttrs);
+    return `
+    <div class="editrow">
+      ${control}
+      <span class="ehint">${escapeHtml(proposedEditorHint(descriptor))}</span>
     </div>
+    <span class="verr" data-testid="value-error" role="alert" hidden></span>
   `;
 }
+/**
+ * Picks the concrete input control for the proposed-value editor from the
+ * neutral value-type descriptor. All variants carry the SAME
+ * `data-testid="edit-proposed-value"` and `.value` semantics so the mount
+ * handler reads a reviewer's edit uniformly (both `<input>` and `<select>`
+ * expose `.value`). Falls back to a plain text input when there is no
+ * descriptor, an enum without a declared set, or a free-form type
+ * (string/array/object).
+ */
+function renderTypedProposedControl(descriptor, valueText, commonAttrs) {
+    switch (descriptor?.type) {
+        case "enum": {
+            const allowed = descriptor.enumValues ?? [];
+            if (allowed.length === 0)
+                break;
+            // Keep an out-of-set current value selectable rather than silently
+            // rewriting it — the reviewer sees exactly what was proposed.
+            const leadingOption = allowed.includes(valueText)
+                ? ""
+                : `<option value="${escapeHtml(valueText)}" selected>${escapeHtml(valueText === "" ? "(unset)" : valueText)}</option>`;
+            const options = allowed
+                .map((opt) => `<option value="${escapeHtml(opt)}"${opt === valueText ? " selected" : ""}>${escapeHtml(opt)}</option>`)
+                .join("");
+            return `<select${commonAttrs}>${leadingOption}${options}</select>`;
+        }
+        case "boolean": {
+            const options = ["true", "false"]
+                .map((opt) => `<option value="${opt}"${opt === valueText ? " selected" : ""}>${opt}</option>`)
+                .join("");
+            return `<select${commonAttrs}>${options}</select>`;
+        }
+        case "date":
+            return `<input type="date"${commonAttrs} value="${escapeHtml(toDateInputValue(valueText))}">`;
+        case "number":
+            return `<input type="number" inputmode="decimal"${commonAttrs} value="${escapeHtml(valueText)}">`;
+        default:
+            break;
+    }
+    return `<input type="text"${commonAttrs} value="${escapeHtml(valueText)}">`;
+}
+/** The trailing editor hint, keyed to the declared value type. */
+function proposedEditorHint(descriptor) {
+    switch (descriptor?.type) {
+        case "enum":
+            return "choose one";
+        case "boolean":
+            return "true / false";
+        case "date":
+            return "date";
+        case "number":
+            return "number";
+        default:
+            return "editable";
+    }
+}
+/** Normalizes an arbitrary value string to the `YYYY-MM-DD` an `<input type="date">` accepts. */
+function toDateInputValue(text) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(text))
+        return text;
+    const parsed = Date.parse(text);
+    return Number.isNaN(parsed) ? "" : new Date(parsed).toISOString().slice(0, 10);
+}
+/**
+ * Validates a reviewer's raw (string) edit of a proposed value against the
+ * field's neutral {@link ReviewValueDescriptor}, returning a human-readable
+ * error message when the value violates the declared type/enum constraint, or
+ * `undefined` when it is acceptable — including when there is no descriptor or
+ * the type carries no single-line constraint (string/array/object). This is a
+ * FORMAT check only: it never coerces or rewrites the value (the workbench
+ * stores the reviewer's string edit unchanged, as it did before typed editors).
+ */
+export function validateProposedValue(descriptor, rawValue) {
+    if (!descriptor)
+        return undefined;
+    const value = rawValue.trim();
+    switch (descriptor.type) {
+        case "number":
+            if (value === "")
+                return "Enter a number.";
+            return Number.isFinite(Number(value)) ? undefined : `"${rawValue}" is not a number.`;
+        case "boolean":
+            if (value === "")
+                return "Choose true or false.";
+            return value === "true" || value === "false" ? undefined : `"${rawValue}" is not true or false.`;
+        case "date":
+            if (value === "")
+                return "Enter a date.";
+            return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(value))
+                ? undefined
+                : `"${rawValue}" is not a valid date (YYYY-MM-DD).`;
+        case "enum": {
+            const allowed = descriptor.enumValues ?? [];
+            if (allowed.length === 0)
+                return undefined; // nothing declared to enforce
+            return allowed.includes(value) ? undefined : `Choose one of: ${allowed.join(", ")}.`;
+        }
+        default:
+            return undefined;
+    }
+}
 function renderProvenanceRow(item, proposed, presentationAdapter) {
     const excerpt = proposed.locator?.excerpt;
     if (!excerpt) {
@@ -976,6 +1082,25 @@ function bindFieldCardInteractions(root, controller) {
             const itemName = button.dataset.itemName ?? "";
             const field = button.closest("[data-testid='review-field']");
             const input = field?.querySelector("[data-testid='edit-proposed-value']");
+            const descriptor = controller
+                .currentSession()
+                .items.find((entry) => entry.metadata.name === itemName)?.spec.valueDescriptor;
+            const error = validateProposedValue(descriptor, input?.value ?? "");
+            const errorEl = field?.querySelector("[data-testid='value-error']");
+            if (error) {
+                // Block the decision and surface the reason inline; the transient DOM
+                // message survives until the next interaction (no re-render on reject).
+                if (errorEl) {
+                    errorEl.textContent = error;
+                    errorEl.hidden = false;
+                }
+                input?.focus?.();
+                return;
+            }
+            if (errorEl) {
+                errorEl.textContent = "";
+                errorEl.hidden = true;
+            }
             controller.setDecision(itemName, "accept-proposed", input?.value);
             controller.renderCurrentState();
         });

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

@@ -404,7 +404,8 @@ h1, h2, h3, p {
   margin-top: 8px;
 }
 
-.editrow input {
+.editrow input,
+.editrow select {
   flex: 1;
   min-width: 0;
   font-size: 13.5px;
@@ -415,7 +416,8 @@ h1, h2, h3, p {
   padding: 6px 9px;
 }
 
-.editrow input:focus-visible {
+.editrow input:focus-visible,
+.editrow select:focus-visible {
   outline: 2px solid var(--k-brand);
   outline-offset: 1px;
   border-color: var(--k-brand);
@@ -427,6 +429,20 @@ h1, h2, h3, p {
   white-space: nowrap;
 }
 
+/* Validation message for a typed proposed-value edit (hidden until the mount
+   handler blocks a "Use proposed" on an out-of-shape value). */
+.verr {
+  display: block;
+  margin-top: 5px;
+  font-size: 11.5px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.verr[hidden] {
+  display: none;
+}
+
 /* confidence + provenance */
 
 .prov {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",