@kontourai/survey 0.2.1 → 0.3.0

package/README.md

@@ -183,6 +183,20 @@ preserved. Producers still own scalar semantics, validation, candidate ranking,
 review policy, and whether a value should be verified, proposed, rejected, or
 assumed.
 
+## Reviewed candidate resolutions
+
+Use `reviewedCandidateResolution` when a producer has multiple candidate
+observations for the same target and a review outcome selects one candidate.
+The helper wraps `candidateReviewRecord`, attaches the review outcome to the
+selected candidate, defaults the candidate set to `resolved`, defaults the
+selected claim status from the review outcome, and defaults unselected
+candidates to `superseded`. Producers can override selected or unselected claim
+statuses when their domain workflow needs a different posture.
+
+This is useful for corrected documents, source-of-truth choices, and review
+queues where losing candidates should remain visible for transparency rather
+than disappearing from the trust trail.
+
 ## Repeated observations
 
 Use `repeatedObservation` when a producer wants to describe a repeated field or

package/dist/src/index.d.ts

@@ -1,6 +1,8 @@
 export type { CandidateSetStatus, Candidate, CandidateSet, ClaimTarget, Extraction, LocatorScheme, RawSource, RawSourceKind, ReviewOutcome, ReviewStatus, SurveyInput, } from "./types.js";
 export { candidateReviewRecord, 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";
 export { buildSurveyTrustInput } from "./to-surface.js";
 export { fieldObservation } from "./field-observation.js";
 export type { FieldObservationInput } from "./field-observation.js";

package/dist/src/index.js

@@ -1,4 +1,5 @@
 export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
+export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
 export { buildSurveyTrustInput } from "./to-surface.js";
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";

package/dist/src/reviewed-candidate-resolution.d.ts

@@ -0,0 +1,18 @@
+import { type SurveyClaimRecord, type SurveyObservationInput } from "./builder.js";
+import type { CandidateSet, ClaimTarget, ReviewOutcome } from "./types.js";
+export interface ReviewedCandidateResolutionInput {
+    id: string;
+    target: string;
+    observations: SurveyObservationInput[];
+    selectedCandidateId: string;
+    rationale?: string;
+    metadata?: Record<string, unknown>;
+    status?: CandidateSet["status"];
+    reviewOutcome: Omit<ReviewOutcome, "id" | "candidateSetId" | "candidateId"> & {
+        id?: string;
+        candidateId?: string;
+    };
+    selectedClaimStatus?: ClaimTarget["status"];
+    unselectedClaimStatus?: ClaimTarget["status"];
+}
+export declare function reviewedCandidateResolution(input: ReviewedCandidateResolutionInput): SurveyClaimRecord[];

package/dist/src/reviewed-candidate-resolution.js

@@ -0,0 +1,36 @@
+import { candidateReviewRecord } from "./builder.js";
+export function reviewedCandidateResolution(input) {
+    return candidateReviewRecord({
+        id: input.id,
+        target: input.target,
+        selectedCandidateId: input.selectedCandidateId,
+        status: input.status ?? candidateSetStatusForReview(input.reviewOutcome.status),
+        rationale: input.rationale,
+        metadata: input.metadata,
+        reviewOutcome: {
+            ...input.reviewOutcome,
+            candidateId: input.reviewOutcome.candidateId ?? input.selectedCandidateId,
+        },
+        observations: input.observations.map((observation) => ({
+            ...observation,
+            claim: {
+                ...observation.claim,
+                status: observation.claim.status ?? claimStatusForObservation(input, observation),
+            },
+        })),
+    });
+}
+function claimStatusForObservation(input, observation) {
+    if (observationCandidateId(observation) === input.selectedCandidateId) {
+        return input.selectedClaimStatus ?? input.reviewOutcome.status;
+    }
+    return input.unselectedClaimStatus ?? "superseded";
+}
+function observationCandidateId(observation) {
+    return observation.candidate?.id ?? `${observation.id}.candidate`;
+}
+function candidateSetStatusForReview(status) {
+    if (status === "proposed")
+        return "needs-review";
+    return "resolved";
+}

package/package.json

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