@kontourai/survey 0.2.1 → 0.4.0

package/README.md

@@ -183,6 +183,36 @@ 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.
+
+## Reviewed current/proposed resolutions
+
+Use `reviewedCurrentProposedResolution` when a producer has exactly two
+candidate roles for the same target: the current value the producer would keep
+absent a change, and a proposed value introduced by new source material,
+extraction, or review work. The helper consumes full observations, selects
+either the current or proposed candidate through `selectedCandidateRole`, and
+wraps the result with `reviewedCandidateResolution`.
+
+The helper may promote the selected candidate to a caller-supplied
+`selectedClaimId`. The unselected observation keeps its caller-authored claim
+id, so producers can keep losing candidates as candidate-specific history.
+Survey does not decide producer policy: callers still own review status,
+selected and unselected claim statuses, source details, claim vocabulary, and
+domain metadata.
+
 ## Repeated observations
 
 Use `repeatedObservation` when a producer wants to describe a repeated field or

package/dist/src/index.d.ts

@@ -1,6 +1,10 @@
 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 { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
+export type { CurrentProposedCandidateRole, ReviewedCurrentProposedResolutionInput, } from "./reviewed-current-proposed-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,6 @@
 export { candidateReviewRecord, SurveyInputBuilder } from "./builder.js";
+export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
+export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-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/dist/src/reviewed-current-proposed-resolution.d.ts

@@ -0,0 +1,10 @@
+import { type ReviewedCandidateResolutionInput } from "./reviewed-candidate-resolution.js";
+import type { SurveyClaimRecord, SurveyObservationInput } from "./builder.js";
+export type CurrentProposedCandidateRole = "current" | "proposed";
+export interface ReviewedCurrentProposedResolutionInput extends Omit<ReviewedCandidateResolutionInput, "observations" | "selectedCandidateId"> {
+    currentObservation: SurveyObservationInput;
+    proposedObservation: SurveyObservationInput;
+    selectedCandidateRole: CurrentProposedCandidateRole;
+    selectedClaimId?: string;
+}
+export declare function reviewedCurrentProposedResolution(input: ReviewedCurrentProposedResolutionInput): SurveyClaimRecord[];

package/dist/src/reviewed-current-proposed-resolution.js

@@ -0,0 +1,49 @@
+import { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js";
+export function reviewedCurrentProposedResolution(input) {
+    const currentCandidateId = candidateIdFor(input, "current", input.currentObservation);
+    const proposedCandidateId = candidateIdFor(input, "proposed", input.proposedObservation);
+    const selectedCandidateId = input.selectedCandidateRole === "current"
+        ? currentCandidateId
+        : proposedCandidateId;
+    return reviewedCandidateResolution({
+        ...input,
+        selectedCandidateId,
+        observations: [
+            observationForRole({
+                input,
+                role: "current",
+                candidateId: currentCandidateId,
+                observation: input.currentObservation,
+            }),
+            observationForRole({
+                input,
+                role: "proposed",
+                candidateId: proposedCandidateId,
+                observation: input.proposedObservation,
+            }),
+        ],
+    });
+}
+function observationForRole(input) {
+    const selected = input.input.selectedCandidateRole === input.role;
+    return {
+        ...input.observation,
+        candidate: {
+            ...input.observation.candidate,
+            id: input.candidateId,
+            metadata: {
+                ...input.observation.candidate?.metadata,
+                candidateRole: input.role,
+            },
+        },
+        claim: {
+            ...input.observation.claim,
+            id: selected && input.input.selectedClaimId
+                ? input.input.selectedClaimId
+                : input.observation.claim.id,
+        },
+    };
+}
+function candidateIdFor(input, role, observation) {
+    return observation.candidate?.id ?? `${input.id}.${role}.candidate`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/survey",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Producer-side source, extraction, candidate, and review contracts for projecting verified claims into Surface.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,8 @@
     "build": "rm -rf dist && tsc",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test dist/tests/*.test.js",
-    "verify": "npm run typecheck && npm test"
+    "verify": "node scripts/check-content-boundary.cjs && npm run typecheck && npm test",
+    "check:content-boundary": "node scripts/check-content-boundary.cjs"
   },
   "dependencies": {
     "@kontourai/surface": "^0.5.0"