@kontourai/survey 1.1.1 → 1.2.1

package/README.md

@@ -96,6 +96,8 @@ One observation, one chain: the page it came from, what the extractor read, who
 
 Keep producer operational state outside Survey. Queue status, reviewer form state, retries, source caches, and product policy decisions belong in the producer's own data model. Survey carries only the portable evidence chain records needed by Surface.
 
+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 Workbench embed
 
 **Web component** (shadow DOM, no framework required):

package/dist/src/builder.d.ts

@@ -1,7 +1,8 @@
-import type { CandidateSet, ClaimTarget, EscalationRecord, Extraction, Interpretation, RawSource, ReviewOutcome, SurveyInput } from "./types.js";
+import type { CandidateSet, ClaimTarget, EscalationRecord, Extraction, Interpretation, ReviewStatus, RawSource, ReviewOutcome, SurveyInput } from "./types.js";
 export interface SurveyInputBuilderArgs {
     source: string;
     generatedAt?: string;
+    contractVersion?: string;
 }
 export interface SurveyClaimRecord {
     rawSource: RawSource;
@@ -54,6 +55,7 @@ export interface CandidateReviewRecordInput {
 export declare class SurveyInputBuilder {
     private readonly source;
     private readonly generatedAt;
+    private readonly contractVersion;
     private readonly rawSources;
     private readonly extractions;
     private readonly candidateSets;
@@ -78,3 +80,4 @@ export declare class SurveyInputBuilder {
     private addRecordRawSource;
 }
 export declare function candidateReviewRecord(input: CandidateReviewRecordInput): SurveyClaimRecord[];
+export declare function candidateSetStatusFor(reviewStatus?: ReviewStatus): CandidateSet["status"];

package/dist/src/builder.js

@@ -1,6 +1,8 @@
+import { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export class SurveyInputBuilder {
     source;
     generatedAt;
+    contractVersion;
     rawSources = new Map();
     extractions = new Map();
     candidateSets = new Map();
@@ -11,6 +13,7 @@ export class SurveyInputBuilder {
     constructor(args) {
         this.source = args.source;
         this.generatedAt = args.generatedAt ?? new Date().toISOString();
+        this.contractVersion = args.contractVersion ?? SURVEY_INPUT_CONTRACT_VERSION;
     }
     addRawSource(rawSource) {
         addUnique(this.rawSources, rawSource, "raw source");
@@ -64,6 +67,7 @@ export class SurveyInputBuilder {
     }
     build() {
         return {
+            contractVersion: this.contractVersion,
             source: this.source,
             generatedAt: this.generatedAt,
             rawSources: [...this.rawSources.values()],
@@ -206,7 +210,7 @@ function observationIds(rootId, observation) {
         reviewOutcomeId: observation.reviewOutcome?.id ?? `${rootId}.review`,
     };
 }
-function candidateSetStatusFor(reviewStatus) {
+export function candidateSetStatusFor(reviewStatus) {
     if (!reviewStatus || reviewStatus === "proposed")
         return "needs-review";
     return "resolved";

package/dist/src/current-proposed-review-item.d.ts

@@ -0,0 +1,55 @@
+import type { CandidateSetStatus } from "./types.js";
+import { type ClaimTargetHint, type ExtractionReference, type ProducerPolicy, type ReviewItem, type ReviewLocator, type SourceReference, type SurveyRecordProjectionHint } from "./review-resource.js";
+/**
+ * A single candidate value for a current/proposed {@link ReviewItem}. Carries
+ * the candidate value plus its source, extraction, and claim-target evidence.
+ * The builder owns id, role, and candidate-set wiring; the caller owns the
+ * value and its domain vocabulary.
+ */
+export interface CurrentProposedCandidateInput {
+    readonly value: unknown;
+    readonly confidence?: number;
+    readonly sourceRank?: number;
+    readonly rejectionReason?: string;
+    readonly source: SourceReference;
+    readonly locator?: ReviewLocator;
+    readonly extraction: ExtractionReference;
+    readonly claimTarget: ClaimTargetHint;
+    readonly projection?: SurveyRecordProjectionHint;
+    readonly producer?: Record<string, unknown>;
+}
+/**
+ * Input for {@link currentProposedReviewItem} — the generic envelope, id, and
+ * role wiring for a two-candidate current/proposed ReviewItem.
+ */
+export interface CurrentProposedReviewItemInput {
+    readonly name: string;
+    readonly target: string;
+    readonly current: CurrentProposedCandidateInput;
+    readonly proposed: CurrentProposedCandidateInput;
+    readonly candidateSetStatus?: CandidateSetStatus;
+    readonly selectedCandidateRole?: "current" | "proposed";
+    readonly rationale?: string;
+    readonly labels?: Record<string, string>;
+    readonly producerMetadata?: Record<string, unknown>;
+    readonly producerPolicy?: ProducerPolicy;
+    readonly projection?: SurveyRecordProjectionHint;
+    readonly candidateIdSuffix?: {
+        readonly current?: string;
+        readonly proposed?: string;
+    };
+}
+/**
+ * Builds the two-candidate current/proposed {@link ReviewItem} envelope that
+ * producers otherwise hand-assemble: candidate ids, roles, candidate-set id,
+ * observed-candidate count, and selected-candidate mirroring. The caller still
+ * owns each candidate's value, source, extraction, and claim-target vocabulary.
+ *
+ * Candidate ids default to `<name>.current` / `<name>.proposed` (the trailing
+ * segment is overridable via `candidateIdSuffix`); the candidate-set id defaults
+ * to `<name>.candidates` (overridable via `projection.candidateSetId`);
+ * `candidateSetStatus` defaults to `"needs-review"`. `status.observedCandidateCount`
+ * is always 2, and `status.selectedCandidateId` mirrors `spec.selectedCandidateId`
+ * when `selectedCandidateRole` is set.
+ */
+export declare function currentProposedReviewItem(input: CurrentProposedReviewItemInput): ReviewItem;

package/dist/src/current-proposed-review-item.js

@@ -0,0 +1,64 @@
+import { reviewResourceApiVersion, } from "./review-resource.js";
+/**
+ * Builds the two-candidate current/proposed {@link ReviewItem} envelope that
+ * producers otherwise hand-assemble: candidate ids, roles, candidate-set id,
+ * observed-candidate count, and selected-candidate mirroring. The caller still
+ * owns each candidate's value, source, extraction, and claim-target vocabulary.
+ *
+ * Candidate ids default to `<name>.current` / `<name>.proposed` (the trailing
+ * segment is overridable via `candidateIdSuffix`); the candidate-set id defaults
+ * to `<name>.candidates` (overridable via `projection.candidateSetId`);
+ * `candidateSetStatus` defaults to `"needs-review"`. `status.observedCandidateCount`
+ * is always 2, and `status.selectedCandidateId` mirrors `spec.selectedCandidateId`
+ * when `selectedCandidateRole` is set.
+ */
+export function currentProposedReviewItem(input) {
+    const candidateSetId = input.projection?.candidateSetId ?? `${input.name}.candidates`;
+    const currentId = `${input.name}.${input.candidateIdSuffix?.current ?? "current"}`;
+    const proposedId = `${input.name}.${input.candidateIdSuffix?.proposed ?? "proposed"}`;
+    const selectedCandidateId = input.selectedCandidateRole === "current"
+        ? currentId
+        : input.selectedCandidateRole === "proposed"
+            ? proposedId
+            : undefined;
+    const currentCandidate = buildCandidate("current", currentId, input.current, candidateSetId);
+    const proposedCandidate = buildCandidate("proposed", proposedId, input.proposed, candidateSetId);
+    return {
+        apiVersion: reviewResourceApiVersion,
+        kind: "ReviewItem",
+        metadata: {
+            name: input.name,
+            ...(input.labels ? { labels: input.labels } : {}),
+            ...(input.producerMetadata ? { producer: input.producerMetadata } : {}),
+        },
+        spec: {
+            target: input.target,
+            candidates: [currentCandidate, proposedCandidate],
+            candidateSetStatus: input.candidateSetStatus ?? "needs-review",
+            ...(selectedCandidateId ? { selectedCandidateId } : {}),
+            ...(input.rationale ? { rationale: input.rationale } : {}),
+            ...(input.producerPolicy ? { producerPolicy: input.producerPolicy } : {}),
+            projection: { ...input.projection, candidateSetId },
+        },
+        status: {
+            observedCandidateCount: 2,
+            ...(selectedCandidateId ? { selectedCandidateId } : {}),
+        },
+    };
+}
+function buildCandidate(role, id, input, candidateSetId) {
+    return {
+        id,
+        role,
+        value: input.value,
+        ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),
+        ...(input.sourceRank !== undefined ? { sourceRank: input.sourceRank } : {}),
+        ...(input.rejectionReason ? { rejectionReason: input.rejectionReason } : {}),
+        source: input.source,
+        ...(input.locator ? { locator: input.locator } : {}),
+        extraction: input.extraction,
+        claimTarget: input.claimTarget,
+        projection: { candidateSetId, candidateId: id, ...input.projection },
+        ...(input.producer ? { producer: input.producer } : {}),
+    };
+}

package/dist/src/index.d.ts

@@ -1,7 +1,8 @@
 export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, EscalationDimension, EscalationRecord, Extraction, Interpretation, LocatorScheme, 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, ExtractionReference, ResourceEnvelope, ResourceMetadata, ReviewActor, ReviewCandidate, ReviewDecision, ReviewDecisionSpec, ReviewDecisionStatus, ReviewItem, ReviewItemSpec, ReviewItemStatus, ReviewLocator, ReviewResource, ReviewResourceApiVersion, ReviewResourceKind, ReviewSession, ReviewSessionEvent, ReviewSessionEventSpec, ReviewSessionEventStatus, ReviewSessionEventType, ReviewSessionSpec, ReviewSessionStatus, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";
-export { candidateReviewRecord, SurveyInputBuilder } from "./builder.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 { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export type { CandidateReviewRecordInput, SurveyClaimRecord, SurveyInputBuilderArgs, SurveyObservationInput, } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export type { ReviewedCandidateResolutionInput } from "./reviewed-candidate-resolution.js";
@@ -29,7 +30,11 @@ export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInp
 export type { ExtractedStatement, StatementBadge, UtteranceClaimExtractor, UtteranceStatement, UtteranceStatementRecords, UtteranceTrustReport, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
 export type { MappingProposalRecord, ReviewedMapping, SchemaMappingExtractor, SchemaMappingOptions, SystemFieldRef, } from "./schema-mapping.js";
-export { buildAuthorizedActionAuthorizing, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
-export type { BuildAuthorizedActionAuthorizingInput, ReviewAuthorizingIssue, ReviewAuthorizingIssueCode, } from "./review-authorizing.js";
+export { buildAuthorizedActionAuthorizing, buildPromptRef, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
+export type { BuildAuthorizedActionAuthorizingInput, BuildPromptRefInput, ReviewAuthorizingIssue, ReviewAuthorizingIssueCode, } from "./review-authorizing.js";
+export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./vocabulary.js";
+export type { ConfidenceBasisForReviewInput, ProductVocabularyDefinition, } from "./vocabulary.js";
+export { currentProposedReviewItem } from "./current-proposed-review-item.js";
+export type { CurrentProposedCandidateInput, CurrentProposedReviewItemInput, } from "./current-proposed-review-item.js";
 export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";
 export type { AggregateOversightMetrics, DeriveOversightMetricsOptions, OversightMetrics, OversightMetricsClaimsSubject, OversightQualityClaim, ReviewerOversightMetrics, } from "./oversight-metrics.js";

package/dist/src/index.js

@@ -1,5 +1,6 @@
+export { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 export { reviewResourceApiVersion } from "./review-resource.js";
-export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
+export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";
 export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 export { buildSurveyTrustBundle } from "./to-surface.js";
@@ -13,5 +14,7 @@ export { apiRecordSource, manualEntrySource, policyStandardSource, uploadedDocum
 export { applyAutoAcceptPolicy, applyMappingReview, buildMappingReviewItems, lookupMapping, lookupRejectedMapping, normalizeQuestion, proposalsToCandidateSet, referenceMappingProposer, resolveQuestion, } from "./inquiry-mapping.js";
 export { referenceUtteranceExtractor, surveyAgentUtterance, utteranceToSurveyInput, } from "./agent-utterance.js";
 export { mappingReviewToSurface, referenceSchemaExtractor, surveySchemaMapping, } from "./schema-mapping.js";
-export { buildAuthorizedActionAuthorizing, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
+export { buildAuthorizedActionAuthorizing, buildPromptRef, isValidAuthorizing, validateAuthorizing } from "./review-authorizing.js";
+export { confidenceBasisForReview, defineProductVocabulary, stableId } from "./vocabulary.js";
+export { currentProposedReviewItem } from "./current-proposed-review-item.js";
 export { deriveOversightMetrics, mergeTrustBundleWithOversightMetrics, oversightMetricsToClaims, } from "./oversight-metrics.js";

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

@@ -37,3 +37,23 @@ export interface BuildAuthorizedActionAuthorizingInput {
  * runs validateAuthorizing and degrades gracefully instead of throwing.
  */
 export declare function buildAuthorizedActionAuthorizing(input: BuildAuthorizedActionAuthorizingInput): ReviewAuthorizingAuthorizedAction;
+export interface BuildPromptRefInput {
+    readonly module: string;
+    readonly component: string;
+    readonly version?: string;
+    readonly scheme?: string;
+}
+/**
+ * Builds a well-formed `promptRef` for an `authorized-action` authorizing block,
+ * generalizing the workbench's `<module>/<component>@<version>` convention.
+ *
+ * Without a `scheme` the result is bare (`"review-workbench/decision-card@v1"`),
+ * matching the workbench's own internal prompt refs. With a `scheme` the result
+ * is prefixed (`"survey://rules-admin/keep-current@v1"`) for producers that
+ * namespace their prompt refs. `version` defaults to `"v1"`.
+ *
+ * The returned string is a valid `promptRef` input to
+ * {@link buildAuthorizedActionAuthorizing}. Throws on an empty `module` or
+ * `component`, mirroring that helper's throw-on-invalid-input style.
+ */
+export declare function buildPromptRef(input: BuildPromptRefInput): string;

package/dist/src/review-authorizing.js

@@ -123,3 +123,30 @@ export function buildAuthorizedActionAuthorizing(input) {
     }
     return block;
 }
+/**
+ * Builds a well-formed `promptRef` for an `authorized-action` authorizing block,
+ * generalizing the workbench's `<module>/<component>@<version>` convention.
+ *
+ * Without a `scheme` the result is bare (`"review-workbench/decision-card@v1"`),
+ * matching the workbench's own internal prompt refs. With a `scheme` the result
+ * is prefixed (`"survey://rules-admin/keep-current@v1"`) for producers that
+ * namespace their prompt refs. `version` defaults to `"v1"`.
+ *
+ * The returned string is a valid `promptRef` input to
+ * {@link buildAuthorizedActionAuthorizing}. Throws on an empty `module` or
+ * `component`, mirroring that helper's throw-on-invalid-input style.
+ */
+export function buildPromptRef(input) {
+    const module = input.module?.trim();
+    const component = input.component?.trim();
+    if (!module) {
+        throw new Error("buildPromptRef: 'module' must be a non-empty string.");
+    }
+    if (!component) {
+        throw new Error("buildPromptRef: 'component' must be a non-empty string.");
+    }
+    const version = input.version?.trim() || "v1";
+    const scheme = input.scheme?.trim();
+    const ref = `${module}/${component}@${version}`;
+    return scheme ? `${scheme}://${ref}` : ref;
+}

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

@@ -59,6 +59,25 @@ export interface SurveyRecordProjectionHint {
     reviewOutcomeId?: ReviewOutcome["id"];
     claimId?: ClaimTarget["id"];
 }
+/**
+ * Well-known decision-mode vocabulary for {@link ProducerPolicy.decisionMode}.
+ * A producer declares how a ReviewItem is allowed to be resolved:
+ *   `keep-current`     — only a keep-current decision is admissible.
+ *   `current-proposed` — only the current or proposed candidate may be selected.
+ *   `free-select`      — any declared candidate may be selected.
+ * Enforcement is opt-in; see `assertReviewDecisionModeAllows` and the
+ * `enforceProducerPolicy` option on `applyReviewSession`.
+ */
+export type ReviewDecisionMode = "keep-current" | "current-proposed" | "free-select";
+/**
+ * Producer-declared policy carried on a ReviewItem. The well-known
+ * `decisionMode` sub-key is typed and optionally enforceable; all other keys
+ * remain opaque to Survey (tolerated via the index signature, never inspected).
+ */
+export interface ProducerPolicy {
+    decisionMode?: ReviewDecisionMode;
+    [key: string]: unknown;
+}
 export interface ReviewCandidate {
     id: string;
     role?: CandidateRole;
@@ -79,7 +98,7 @@ export interface ReviewItemSpec {
     candidateSetStatus?: CandidateSetStatus;
     selectedCandidateId?: string;
     rationale?: string;
-    producerPolicy?: Record<string, unknown>;
+    producerPolicy?: ProducerPolicy;
     projection?: SurveyRecordProjectionHint;
 }
 export interface ReviewItemStatus {

package/dist/src/review-workbench/producer-decision-mode.d.ts

@@ -0,0 +1,34 @@
+import type { ReviewItem } from "../review-resource.js";
+import type { ReviewWorkbenchResult } from "./review-workbench.js";
+export type ReviewDecisionModeIssueCode = "unknown-decision-mode" | "decision-not-allowed" | "candidate-not-in-item";
+export interface ReviewDecisionModeIssue {
+    readonly code: ReviewDecisionModeIssueCode;
+    readonly message: string;
+}
+/**
+ * The subset of a {@link ReviewWorkbenchResult} a decision-mode check inspects.
+ */
+export type ReviewDecisionModeResult = Pick<ReviewWorkbenchResult, "decision" | "selectedCandidateId" | "selectedCandidateRole">;
+/**
+ * Validates a review result against the item's declared `producerPolicy.decisionMode`.
+ *
+ * Returns an empty array when the item declares no `producerPolicy` or no
+ * `decisionMode` (the default, un-enforced posture). For a known mode it checks:
+ *   `keep-current`     — only a `keep-current` decision is admissible.
+ *   `current-proposed` — only the current or proposed candidate role may be selected.
+ *   `free-select`      — the selected candidate must be one declared on the item.
+ * An unrecognized `decisionMode` string fails closed with a single
+ * `unknown-decision-mode` issue.
+ */
+export declare function validateReviewDecisionMode(item: ReviewItem, result: ReviewDecisionModeResult): ReviewDecisionModeIssue[];
+export declare class DecisionModeViolationError extends Error {
+    readonly name = "DecisionModeViolationError";
+    readonly issues: readonly ReviewDecisionModeIssue[];
+    constructor(reviewItemName: string, issues: readonly ReviewDecisionModeIssue[]);
+}
+/**
+ * Asserts a review result satisfies the item's declared decision mode, throwing
+ * a {@link DecisionModeViolationError} otherwise. Mirrors the
+ * validate-then-assert idiom in `review-authorizing.ts`.
+ */
+export declare function assertReviewDecisionModeAllows(item: ReviewItem, result: ReviewDecisionModeResult): void;

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

@@ -0,0 +1,73 @@
+const KNOWN_DECISION_MODES = new Set([
+    "keep-current",
+    "current-proposed",
+    "free-select",
+]);
+/**
+ * Validates a review result against the item's declared `producerPolicy.decisionMode`.
+ *
+ * Returns an empty array when the item declares no `producerPolicy` or no
+ * `decisionMode` (the default, un-enforced posture). For a known mode it checks:
+ *   `keep-current`     — only a `keep-current` decision is admissible.
+ *   `current-proposed` — only the current or proposed candidate role may be selected.
+ *   `free-select`      — the selected candidate must be one declared on the item.
+ * An unrecognized `decisionMode` string fails closed with a single
+ * `unknown-decision-mode` issue.
+ */
+export function validateReviewDecisionMode(item, result) {
+    const decisionMode = item.spec.producerPolicy?.decisionMode;
+    if (decisionMode === undefined) {
+        return [];
+    }
+    if (!KNOWN_DECISION_MODES.has(decisionMode)) {
+        return [{
+                code: "unknown-decision-mode",
+                message: `ReviewItem ${item.metadata.name} declares an unrecognized producerPolicy.decisionMode '${String(decisionMode)}'.`,
+            }];
+    }
+    if (decisionMode === "keep-current") {
+        if (result.decision !== "keep-current") {
+            return [{
+                    code: "decision-not-allowed",
+                    message: `ReviewItem ${item.metadata.name} declares decisionMode 'keep-current'; decision '${result.decision}' is not allowed.`,
+                }];
+        }
+        return [];
+    }
+    if (decisionMode === "current-proposed") {
+        if (result.selectedCandidateRole !== "current" && result.selectedCandidateRole !== "proposed") {
+            return [{
+                    code: "decision-not-allowed",
+                    message: `ReviewItem ${item.metadata.name} declares decisionMode 'current-proposed'; selected candidate role '${result.selectedCandidateRole ?? "unknown"}' is not current or proposed.`,
+                }];
+        }
+        return [];
+    }
+    // free-select: the selected candidate must be one declared on the item.
+    if (!item.spec.candidates.some((candidate) => candidate.id === result.selectedCandidateId)) {
+        return [{
+                code: "candidate-not-in-item",
+                message: `ReviewItem ${item.metadata.name} declares decisionMode 'free-select'; selected candidate '${result.selectedCandidateId}' is not declared on the item.`,
+            }];
+    }
+    return [];
+}
+export class DecisionModeViolationError extends Error {
+    name = "DecisionModeViolationError";
+    issues;
+    constructor(reviewItemName, issues) {
+        super(`ReviewItem ${reviewItemName} violates its declared producerPolicy.decisionMode: ${issues.map((issue) => issue.message).join(" ")}`);
+        this.issues = issues;
+    }
+}
+/**
+ * Asserts a review result satisfies the item's declared decision mode, throwing
+ * a {@link DecisionModeViolationError} otherwise. Mirrors the
+ * validate-then-assert idiom in `review-authorizing.ts`.
+ */
+export function assertReviewDecisionModeAllows(item, result) {
+    const issues = validateReviewDecisionMode(item, result);
+    if (issues.length > 0) {
+        throw new DecisionModeViolationError(item.metadata.name, issues);
+    }
+}

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

@@ -152,7 +152,7 @@ export declare const regulatedRuleConflictReviewItemExample: {
             candidateSetId: string;
         };
         producerPolicy: {
-            decisionMode: string;
+            decisionMode: "keep-current";
             sourceAuthorityProjection: string;
             feedbackTags: string[];
         };
@@ -290,7 +290,7 @@ export declare const facilityCredentialReviewItemExample: {
             candidateSetId: string;
         };
         producerPolicy: {
-            decisionMode: string;
+            decisionMode: "current-proposed";
             sourceAuthorityProjection: string;
             feedbackTags: string[];
         };
@@ -577,7 +577,7 @@ export declare const reviewWorkbenchQueueExamples: (ReviewItem | {
             candidateSetId: string;
         };
         producerPolicy: {
-            decisionMode: string;
+            decisionMode: "keep-current";
             sourceAuthorityProjection: string;
             feedbackTags: string[];
         };

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

@@ -6,6 +6,7 @@ export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionRe
 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";
 export { validateReviewSessionEventsForSnapshot, type ReviewSessionReplayIssue, type ReviewSessionReplayIssueCode, } from "./review-session-replay.js";
+export { assertReviewDecisionModeAllows, DecisionModeViolationError, validateReviewDecisionMode, type ReviewDecisionModeIssue, type ReviewDecisionModeIssueCode, type ReviewDecisionModeResult, } from "./producer-decision-mode.js";
 export declare function buildReviewDecision(state: ReviewWorkbenchState): ReviewDecision | undefined;
 export interface ReviewWorkbenchSessionExport {
     readonly session: ReviewSession;

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

@@ -10,6 +10,7 @@ export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionRe
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, } from "./review-surface-preview.js";
 export { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
+export { assertReviewDecisionModeAllows, DecisionModeViolationError, validateReviewDecisionMode, } from "./producer-decision-mode.js";
 export function buildReviewDecision(state) {
     if (!state.decision) {
         return undefined;

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

@@ -1,6 +1,7 @@
-import { type DeriveReviewSessionApplyResultForSnapshotResult, type ReviewSessionApplyResolutionRequirement } from "./review-workbench.js";
+import { type DeriveReviewSessionApplyResultForSnapshotResult, type MapReviewWorkbenchResultsToApplyActionsOptions, type ReviewApplyActionIssue, type ReviewApplyActionMapping, type ReviewSessionApplyIssue, type ReviewSessionApplyResolutionRequirement, type ReviewWorkbenchResult } from "./review-workbench.js";
+import { type ReviewDecisionModeIssue } from "./producer-decision-mode.js";
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
-import type { ReviewSessionEvent } from "../review-resource.js";
+import type { ReviewDecision, ReviewSessionEvent } from "../review-resource.js";
 import type { ReviewQueueSessionState } from "./review-queue-session.js";
 export interface ServerReviewSessionRecord {
     readonly sessionName: string;
@@ -63,3 +64,68 @@ export declare function assertServerReviewSessionFreshness(record: ServerReviewS
 export declare function validateServerReviewSessionEvents(record: ServerReviewSessionRecord, events: readonly ReviewSessionEvent[]): ServerReviewSessionEventValidationIssue[];
 export declare function assertServerReviewSessionEvents(record: ServerReviewSessionRecord, events: readonly ReviewSessionEvent[]): void;
 export declare function deriveServerReviewSessionApplyResult(options: DeriveServerReviewSessionApplyResultOptions): DeriveReviewSessionApplyResultForSnapshotResult;
+export interface ApplyReviewSessionOptions<TAction = never> {
+    /** Pre-built server record. When omitted, one is built from `snapshot`. */
+    readonly record?: ServerReviewSessionRecord;
+    /** Reviewed snapshot to build a server record from when `record` is omitted. */
+    readonly snapshot?: ReviewQueueSessionState;
+    /** Session name for the built record; falls back to the first event's session name. */
+    readonly sessionName?: string;
+    /** `updatedAt` stamp for the built record. */
+    readonly recordUpdatedAt?: string | Date;
+    readonly events: readonly ReviewSessionEvent[];
+    readonly currentSnapshot?: ReviewQueueSessionState;
+    readonly currentEventCount?: number;
+    readonly requiredResolvedItems?: ReviewSessionApplyResolutionRequirement;
+    /** When true, each result is checked against its item's producerPolicy.decisionMode. */
+    readonly enforceProducerPolicy?: boolean;
+    /** When provided, results are mapped to product apply actions in the same call. */
+    readonly mapActions?: Omit<MapReviewWorkbenchResultsToApplyActionsOptions<TAction>, "results" | "items">;
+}
+export type ApplyReviewSessionIssue = ReviewSessionApplyIssue | {
+    readonly code: "stale-session";
+    readonly message: string;
+} | {
+    readonly code: "invalid-events";
+    readonly message: string;
+} | {
+    readonly code: "decision-mode-violation";
+    readonly reviewItemName: string;
+    readonly message: string;
+    readonly issues: readonly ReviewDecisionModeIssue[];
+} | {
+    readonly code: "action-mapping-failed";
+    readonly message: string;
+    readonly issues: readonly ReviewApplyActionIssue[];
+};
+export type ApplyReviewSessionResult<TAction = never> = {
+    readonly ok: true;
+    readonly issues: readonly [];
+    readonly decisions: readonly ReviewDecision[];
+    readonly results: readonly ReviewWorkbenchResult[];
+    readonly actions: readonly ReviewApplyActionMapping<TAction>[];
+    readonly replayedSession: ReviewQueueSessionState;
+} | {
+    readonly ok: false;
+    readonly issues: readonly ApplyReviewSessionIssue[];
+    readonly decisions: readonly ReviewDecision[];
+    readonly results: readonly ReviewWorkbenchResult[];
+    readonly actions: readonly ReviewApplyActionMapping<TAction>[];
+};
+/**
+ * One-call server apply: collapses the "resolve server record → derive apply
+ * result → normalize freshness/event errors → (optionally) enforce
+ * producerPolicy.decisionMode → (optionally) map results to product actions"
+ * choreography into a single call.
+ *
+ * Returns a discriminated `{ ok }` result rather than throwing for expected
+ * failure modes (stale session, invalid events, unresolved items, decision-mode
+ * violations, action-mapping failures) — matching the
+ * `deriveReviewSessionApplyResultForSnapshot` idiom. Unexpected errors still
+ * propagate.
+ *
+ * Supply either a pre-built `record` or a `snapshot` (a record is then built via
+ * `createServerReviewSessionRecord`). `enforceProducerPolicy` is off by default;
+ * unset `producerPolicy`/`decisionMode` never changes behavior.
+ */
+export declare function applyReviewSession<TAction = never>(options: ApplyReviewSessionOptions<TAction>): ApplyReviewSessionResult<TAction>;

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

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { deriveReviewSessionApplyResultForSnapshot, } from "./review-workbench.js";
+import { deriveReviewSessionApplyResultForSnapshot, mapReviewWorkbenchResultsToApplyActions, ReviewApplyActionMappingError, } from "./review-workbench.js";
+import { validateReviewDecisionMode, } from "./producer-decision-mode.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
 import { canonicalJson } from "./canonical.js";
 export class StaleServerReviewSessionError extends Error {
@@ -114,3 +115,113 @@ function sha256(value) {
 function isoTimestamp(value) {
     return value instanceof Date ? value.toISOString() : value;
 }
+/**
+ * One-call server apply: collapses the "resolve server record → derive apply
+ * result → normalize freshness/event errors → (optionally) enforce
+ * producerPolicy.decisionMode → (optionally) map results to product actions"
+ * choreography into a single call.
+ *
+ * Returns a discriminated `{ ok }` result rather than throwing for expected
+ * failure modes (stale session, invalid events, unresolved items, decision-mode
+ * violations, action-mapping failures) — matching the
+ * `deriveReviewSessionApplyResultForSnapshot` idiom. Unexpected errors still
+ * propagate.
+ *
+ * Supply either a pre-built `record` or a `snapshot` (a record is then built via
+ * `createServerReviewSessionRecord`). `enforceProducerPolicy` is off by default;
+ * unset `producerPolicy`/`decisionMode` never changes behavior.
+ */
+export function applyReviewSession(options) {
+    const record = resolveApplyReviewSessionRecord(options);
+    let derived;
+    try {
+        derived = deriveServerReviewSessionApplyResult({
+            record,
+            events: options.events,
+            currentSnapshot: options.currentSnapshot,
+            currentEventCount: options.currentEventCount,
+            requiredResolvedItems: options.requiredResolvedItems,
+        });
+    }
+    catch (error) {
+        if (error instanceof StaleServerReviewSessionError) {
+            return { ok: false, issues: [{ code: "stale-session", message: error.message }], decisions: [], results: [], actions: [] };
+        }
+        if (error instanceof ServerReviewSessionEventValidationError) {
+            return { ok: false, issues: [{ code: "invalid-events", message: error.message }], decisions: [], results: [], actions: [] };
+        }
+        throw error;
+    }
+    if (!derived.ok) {
+        return { ok: false, issues: derived.issues, decisions: derived.decisions, results: derived.results, actions: [] };
+    }
+    if (options.enforceProducerPolicy) {
+        const itemsByName = new Map(record.snapshot.items.map((item) => [item.metadata.name, item]));
+        const violations = [];
+        for (const result of derived.results) {
+            const item = itemsByName.get(result.reviewItemName);
+            if (!item) {
+                continue;
+            }
+            const issues = validateReviewDecisionMode(item, result);
+            if (issues.length > 0) {
+                violations.push({
+                    code: "decision-mode-violation",
+                    reviewItemName: result.reviewItemName,
+                    message: issues.map((issue) => issue.message).join(" "),
+                    issues,
+                });
+            }
+        }
+        if (violations.length > 0) {
+            return { ok: false, issues: violations, decisions: derived.decisions, results: derived.results, actions: [] };
+        }
+    }
+    let actions = [];
+    if (options.mapActions) {
+        try {
+            actions = mapReviewWorkbenchResultsToApplyActions({
+                ...options.mapActions,
+                results: derived.results,
+                items: record.snapshot.items,
+            });
+        }
+        catch (error) {
+            if (error instanceof ReviewApplyActionMappingError) {
+                return {
+                    ok: false,
+                    issues: [{ code: "action-mapping-failed", message: error.message, issues: error.issues }],
+                    decisions: derived.decisions,
+                    results: derived.results,
+                    actions: [],
+                };
+            }
+            throw error;
+        }
+    }
+    return {
+        ok: true,
+        issues: [],
+        decisions: derived.decisions,
+        results: derived.results,
+        actions,
+        replayedSession: derived.replayedSession,
+    };
+}
+function resolveApplyReviewSessionRecord(options) {
+    if (options.record) {
+        return options.record;
+    }
+    if (!options.snapshot) {
+        throw new Error("applyReviewSession requires either a server `record` or a `snapshot` to build one.");
+    }
+    const sessionName = options.sessionName ?? options.events[0]?.spec.sessionName;
+    if (!sessionName) {
+        throw new Error("applyReviewSession requires a `sessionName` (or a `record`, or events that name their session) to build a server record.");
+    }
+    return createServerReviewSessionRecord({
+        sessionName,
+        snapshot: options.snapshot,
+        updatedAt: options.recordUpdatedAt,
+    });
+}

package/dist/src/types.d.ts

@@ -129,7 +129,23 @@ export interface ClaimTarget {
     eventMethod?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Shape-contract version for the flat record arrays in a {@link SurveyInput}
+ * batch (`rawSources`, `extractions`, `candidateSets`, `reviewOutcomes`,
+ * `claims`). Stamped by {@link SurveyInputBuilder.build} when a batch does not
+ * set one of its own. See `docs/record-contracts.md` for the compatibility
+ * policy — a future breaking change to any of those record shapes must bump
+ * this constant and document the migration before release.
+ */
+export declare const SURVEY_INPUT_CONTRACT_VERSION = "1";
 export interface SurveyInput {
+    /**
+     * Identifies the shape contract for the record arrays in this batch. Optional
+     * and defaults to {@link SURVEY_INPUT_CONTRACT_VERSION} when omitted, so
+     * batches built before this field existed remain valid. Compatibility marker
+     * only — Survey does not gate records on it. See `docs/record-contracts.md`.
+     */
+    contractVersion?: string;
     source: string;
     generatedAt: string;
     rawSources: RawSource[];

package/dist/src/types.js

@@ -1 +1,9 @@
-export {};
+/**
+ * Shape-contract version for the flat record arrays in a {@link SurveyInput}
+ * batch (`rawSources`, `extractions`, `candidateSets`, `reviewOutcomes`,
+ * `claims`). Stamped by {@link SurveyInputBuilder.build} when a batch does not
+ * set one of its own. See `docs/record-contracts.md` for the compatibility
+ * policy — a future breaking change to any of those record shapes must bump
+ * this constant and document the migration before release.
+ */
+export const SURVEY_INPUT_CONTRACT_VERSION = "1";

package/dist/src/vocabulary.d.ts

@@ -0,0 +1,78 @@
+import type { ConfidenceBasis, ImpactLevel, TrustStatus } from "@kontourai/surface";
+/**
+ * Builds a stable, url-safe identifier from ordered parts. Each part is
+ * lowercased, non-alphanumeric runs collapse to a single hyphen, leading and
+ * trailing hyphens are trimmed, and parts join with a dot.
+ *
+ * `stableId(["Public Record", "entity-123", "current"])` → `"public-record.entity-123.current"`.
+ *
+ * Producers use this to derive deterministic candidate, candidate-set, and claim
+ * identifiers from domain values without inventing their own slug helper.
+ */
+export declare function stableId(parts: ReadonlyArray<string | number>): string;
+/**
+ * A product's Survey/Surface vocabulary: the subject type and surface it
+ * projects onto, its claim-type names, and its decision-effect names. Generic
+ * over the caller's claim-type and decision-effect key maps so the concrete
+ * string literals stay visible to callers.
+ */
+export interface ProductVocabularyDefinition<TClaimTypes extends Readonly<Record<string, string>>, TDecisionEffects extends Readonly<Record<string, string>>> {
+    readonly subjectType: string;
+    readonly surface: string;
+    readonly claimTypes: TClaimTypes;
+    readonly decisionEffects: TDecisionEffects;
+}
+/**
+ * Defines a product vocabulary as a deep-frozen, discoverable value that a
+ * `currentProposedReviewItem` caller can pass instead of loose top-level
+ * constants. Returns the same shape it received, frozen so callers cannot
+ * mutate a shared vocabulary at runtime.
+ */
+export declare function defineProductVocabulary<TClaimTypes extends Readonly<Record<string, string>>, TDecisionEffects extends Readonly<Record<string, string>>>(definition: ProductVocabularyDefinition<TClaimTypes, TDecisionEffects>): ProductVocabularyDefinition<TClaimTypes, TDecisionEffects>;
+export interface ConfidenceBasisForReviewInput {
+    readonly status: TrustStatus;
+    readonly impactLevel: ImpactLevel;
+    readonly extractionConfidence?: number;
+    readonly sourceQuality?: ConfidenceBasis["sourceQuality"];
+    readonly reviewerAuthority?: ConfidenceBasis["reviewerAuthority"];
+    readonly evidenceStrength?: ConfidenceBasis["evidenceStrength"];
+}
+/**
+ * Builds a {@link ConfidenceBasis} from a reviewed status and impact level.
+ *
+ * The two known real-world consumers hand-roll *different* five-field
+ * mappings, not one shared algorithm: one derives `sourceQuality` and
+ * `evidenceStrength` from whether any extraction/review support exists at
+ * all, and never returns `"strong"` for either field even when `status` is
+ * `"verified"` with no supporting evidence; the other derives `sourceQuality`
+ * from the extracted document's source type (independent of `status`) and
+ * `evidenceStrength` from `status` alone, never returning `"weak"` or
+ * `"none"`. There is no single formula that reproduces both, so this helper
+ * does not attempt to guess one.
+ *
+ * Defaults are therefore conservative-by-default: `sourceQuality` defaults to
+ * `"unknown"` and `evidenceStrength` defaults to `"none"` — the weakest
+ * possible values — unless the caller supplies an explicit value. The only
+ * field this helper derives from `status` without an explicit override is
+ * `reviewerAuthority` (`"operator"` when `status === "verified"`, otherwise
+ * `"none"`), because that is the one mapping both known real algorithms
+ * agree on for every non-verified status, and it is exactly what the more
+ * conservative of the two returns for the verified case too. `impactLevel`
+ * is always the caller-supplied value (never defaulted). `extractionConfidence`
+ * is copied through and included on the result only when provided; its mere
+ * presence no longer implies a stronger `sourceQuality`/`evidenceStrength` by
+ * default — callers who know that an extraction or review should count as
+ * support must say so explicitly.
+ *
+ * Producers with domain knowledge about their own source quality or evidence
+ * strength should pass `sourceQuality`/`evidenceStrength` explicitly instead
+ * of relying on the bare defaults — for example, a source-type-driven
+ * mapping (strong for corrected/high-confidence documents, moderate for
+ * medium-confidence documents, weak otherwise) the way one known consumer
+ * derives `sourceQuality` from its extracted record's source type. This
+ * function is a conservative, independently-designed baseline, not a
+ * behavioral match for either known consumer's algorithm; verify against
+ * your own data before treating it as a drop-in replacement for hand-rolled
+ * mapping logic.
+ */
+export declare function confidenceBasisForReview(input: ConfidenceBasisForReviewInput): ConfidenceBasis;

package/dist/src/vocabulary.js

@@ -0,0 +1,92 @@
+/**
+ * Builds a stable, url-safe identifier from ordered parts. Each part is
+ * lowercased, non-alphanumeric runs collapse to a single hyphen, leading and
+ * trailing hyphens are trimmed, and parts join with a dot.
+ *
+ * `stableId(["Public Record", "entity-123", "current"])` → `"public-record.entity-123.current"`.
+ *
+ * Producers use this to derive deterministic candidate, candidate-set, and claim
+ * identifiers from domain values without inventing their own slug helper.
+ */
+export function stableId(parts) {
+    return parts
+        .map((part) => String(part)
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase())
+        .join(".");
+}
+/**
+ * Defines a product vocabulary as a deep-frozen, discoverable value that a
+ * `currentProposedReviewItem` caller can pass instead of loose top-level
+ * constants. Returns the same shape it received, frozen so callers cannot
+ * mutate a shared vocabulary at runtime.
+ */
+export function defineProductVocabulary(definition) {
+    return deepFreeze({
+        subjectType: definition.subjectType,
+        surface: definition.surface,
+        claimTypes: { ...definition.claimTypes },
+        decisionEffects: { ...definition.decisionEffects },
+    });
+}
+/**
+ * Builds a {@link ConfidenceBasis} from a reviewed status and impact level.
+ *
+ * The two known real-world consumers hand-roll *different* five-field
+ * mappings, not one shared algorithm: one derives `sourceQuality` and
+ * `evidenceStrength` from whether any extraction/review support exists at
+ * all, and never returns `"strong"` for either field even when `status` is
+ * `"verified"` with no supporting evidence; the other derives `sourceQuality`
+ * from the extracted document's source type (independent of `status`) and
+ * `evidenceStrength` from `status` alone, never returning `"weak"` or
+ * `"none"`. There is no single formula that reproduces both, so this helper
+ * does not attempt to guess one.
+ *
+ * Defaults are therefore conservative-by-default: `sourceQuality` defaults to
+ * `"unknown"` and `evidenceStrength` defaults to `"none"` — the weakest
+ * possible values — unless the caller supplies an explicit value. The only
+ * field this helper derives from `status` without an explicit override is
+ * `reviewerAuthority` (`"operator"` when `status === "verified"`, otherwise
+ * `"none"`), because that is the one mapping both known real algorithms
+ * agree on for every non-verified status, and it is exactly what the more
+ * conservative of the two returns for the verified case too. `impactLevel`
+ * is always the caller-supplied value (never defaulted). `extractionConfidence`
+ * is copied through and included on the result only when provided; its mere
+ * presence no longer implies a stronger `sourceQuality`/`evidenceStrength` by
+ * default — callers who know that an extraction or review should count as
+ * support must say so explicitly.
+ *
+ * Producers with domain knowledge about their own source quality or evidence
+ * strength should pass `sourceQuality`/`evidenceStrength` explicitly instead
+ * of relying on the bare defaults — for example, a source-type-driven
+ * mapping (strong for corrected/high-confidence documents, moderate for
+ * medium-confidence documents, weak otherwise) the way one known consumer
+ * derives `sourceQuality` from its extracted record's source type. This
+ * function is a conservative, independently-designed baseline, not a
+ * behavioral match for either known consumer's algorithm; verify against
+ * your own data before treating it as a drop-in replacement for hand-rolled
+ * mapping logic.
+ */
+export function confidenceBasisForReview(input) {
+    const verified = input.status === "verified";
+    const basis = {
+        sourceQuality: input.sourceQuality ?? "unknown",
+        reviewerAuthority: input.reviewerAuthority ?? (verified ? "operator" : "none"),
+        evidenceStrength: input.evidenceStrength ?? "none",
+        impactLevel: input.impactLevel,
+    };
+    if (input.extractionConfidence !== undefined) {
+        basis.extractionConfidence = input.extractionConfidence;
+    }
+    return basis;
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        for (const nested of Object.values(value)) {
+            deepFreeze(nested);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -68,7 +68,7 @@
     "check:generated-css": "node scripts/copy-review-workbench-package-assets.cjs --check"
   },
   "dependencies": {
-    "@kontourai/surface": "^0.9.0"
+    "@kontourai/surface": "^1.3.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.20.0"