@kontourai/survey 6.1.0 → 8.0.0

package/dist/src/calibration.d.ts

@@ -75,6 +75,21 @@ export interface DeriveCalibrationOptions {
      * labeled samples. Default false — see the module note on circularity.
      */
     readonly includeAutoAccepted?: boolean;
+    /**
+     * Count only audit labels: outcomes whose metadata records a score-blind
+     * decision (`presentation.scoreBlind === true`) on a random audit sample
+     * (`sampling.kind === "random-audit"`), as the review workbench writes them
+     * for a session opened with `openRandomAuditSession`. Default false (every
+     * human outcome counts, as before). Other outcomes are skipped and counted
+     * in `skippedCount`, as windowed-out outcomes are.
+     *
+     * Calibration reads these fields as recorded on the outcome. The review
+     * session validates them (a `random-audit` rate in (0, 1] and a stable seed)
+     * and replay refuses events recorded under other conditions than the
+     * snapshot's, but an outcome assembled outside Survey's apply path is taken
+     * at its word: only feed outcomes from a store you trust.
+     */
+    readonly auditSamplesOnly?: boolean;
 }
 /** One labeled calibration sample: a prediction paired with the human label. */
 export interface CalibrationSample {

package/dist/src/calibration.js

@@ -80,6 +80,10 @@ export function deriveCalibration(input, options = {}) {
     const samples = [];
     let skippedCount = 0;
     for (const outcome of input.reviewOutcomes) {
+        if (options.auditSamplesOnly && !isScoreBlindAuditOutcome(outcome)) {
+            skippedCount++;
+            continue;
+        }
         if (outcome.resolution === "could_not_confirm") {
             skippedCount++;
             continue;
@@ -142,6 +146,13 @@ export function deriveCalibration(input, options = {}) {
 // ---------------------------------------------------------------------------
 // Internal: sample construction
 // ---------------------------------------------------------------------------
+/** A decision recorded score-blind on a random audit sample (see `openRandomAuditSession`). */
+function isScoreBlindAuditOutcome(outcome) {
+    const presentation = outcome.metadata?.presentation;
+    const sampling = outcome.metadata?.sampling;
+    return typeof presentation === "object" && presentation !== null && presentation.scoreBlind === true
+        && typeof sampling === "object" && sampling !== null && sampling.kind === "random-audit";
+}
 function toSample(outcome, candidateSetById, extractionById, includeAutoAccepted) {
     // No human label yet.
     if (outcome.status === "proposed")

package/dist/src/canonical-reviewed-trust-input.d.ts

@@ -1,6 +1,7 @@
 import type { SurveyInput } from "./types.js";
 import type { ReviewItem } from "./review-resource.js";
 import type { ReviewWorkbenchResult } from "./review-workbench/review-workbench.js";
+import { type DeriveFieldStatesInput } from "./field-states.js";
 export interface BuildCanonicalReviewedTrustInputOptions {
     /** Producer identity for the resulting SurveyInput batch. */
     readonly source: string;
@@ -12,6 +13,15 @@ export interface BuildCanonicalReviewedTrustInputOptions {
     readonly items: readonly ReviewItem[];
     /** Results derived by Survey's server apply boundary from snapshot + events. */
     readonly results: readonly ReviewWorkbenchResult[];
+    /**
+     * The extraction imports the items came from (and optionally verifier
+     * records and supersessions). When present, each claim whose item one of
+     * these imports produced carries its derived content and lifecycle states
+     * under `metadata["survey.kontourai.io/field-state"]` (see
+     * `deriveFieldStates`). The states are derived here from the imports and the
+     * results' own decisions, never supplied as labels. Claim status is unchanged.
+     */
+    readonly fieldStates?: Omit<DeriveFieldStatesInput, "decisions" | "carryForwards">;
 }
 export interface CanonicalReviewedTrustInput {
     readonly surveyInput: SurveyInput;

package/dist/src/canonical-reviewed-trust-input.js

@@ -1,6 +1,7 @@
 import { SURVEY_INPUT_CONTRACT_VERSION } from "./types.js";
 import { canonicalJson } from "./review-workbench/canonical.js";
 import { decisionSelectsNoCandidate, workbenchDecisionDefinitions } from "./review-workbench/review-queue-session.js";
+import { deriveFieldStates, fieldStateClaimMetadata, FIELD_STATE_METADATA_KEY } from "./field-states.js";
 /**
  * Projects server-applied review records into the complete SurveyInput consumed
  * by buildSurveyTrustBundle. The ReviewItem and ReviewWorkbenchResult are the
@@ -22,6 +23,13 @@ export function buildCanonicalReviewedTrustInput(options) {
     if (itemsByName.size !== resultsByName.size) {
         throw new Error("Canonical review projection requires exactly one resolved result for every ReviewItem.");
     }
+    const fieldStatesByItem = new Map();
+    if (options.fieldStates) {
+        const states = deriveFieldStates({ ...options.fieldStates, decisions: options.results.map((result) => result.reviewDecision) });
+        for (const state of states)
+            if (state.reviewItemName !== undefined)
+                fieldStatesByItem.set(state.reviewItemName, state);
+    }
     const rawSources = new Map();
     const extractions = new Map();
     const candidateSets = new Map();
@@ -39,10 +47,17 @@ export function buildCanonicalReviewedTrustInput(options) {
         const rejectsAll = selectsNone && result.decision === "reject-proposed";
         const rejectedRole = workbenchDecisionDefinitions[result.decision].candidateRole;
         const rejectAllReason = result.rationale?.trim() || "Every proposed value for this claim was rejected.";
+        // A choice of one conflicting value passes over the others: each keeps a
+        // record that it was seen and not chosen (and so its own rejected-candidate
+        // learning), never silently dropped.
+        const unchosenIds = new Set(result.decision === "select-proposed" ? result.reviewDecision.spec.unselectedCandidateIds ?? [] : []);
+        const notChosenReason = `Not chosen: the reviewer chose candidate ${recordIdFor(item, result.selectedCandidateId ?? "")} for this claim.`;
         const candidates = item.spec.candidates.map((candidate) => {
             const records = projectCandidate(item, rejectsAll && candidate.role === rejectedRole
                 ? { ...candidate, rejectionReason: candidate.rejectionReason ?? rejectAllReason }
-                : candidate);
+                : unchosenIds.has(candidate.id)
+                    ? { ...candidate, rejectionReason: candidate.rejectionReason ?? notChosenReason }
+                    : candidate);
             addConsistent(rawSources, records.rawSource, "raw source");
             addConsistent(extractions, records.extraction, "extraction");
             return records.candidate;
@@ -96,6 +111,13 @@ export function buildCanonicalReviewedTrustInput(options) {
             metadata: {
                 workbenchDecision: result.decision,
                 ...(result.editedValue !== undefined ? { editedValue: result.editedValue } : {}),
+                ...(decision.unselectedCandidateIds?.length
+                    ? { unselectedCandidateIds: decision.unselectedCandidateIds.map((id) => recordIdFor(item, id)) }
+                    : {}),
+                // How the decision was made: whether scores were hidden, and how the
+                // item was sampled. Calibration reads these to select audit labels.
+                ...(decision.presentation !== undefined ? { presentation: { scoreBlind: decision.presentation.scoreBlind } } : {}),
+                ...(decision.sampling !== undefined ? { sampling: { ...decision.sampling } } : {}),
             },
         };
         addConsistent(reviewOutcomes, reviewOutcome, "review outcome");
@@ -136,6 +158,9 @@ export function buildCanonicalReviewedTrustInput(options) {
             ...(hint.derivedFrom ? { derivedFrom: [...hint.derivedFrom] } : {}),
             collectedBy: hint.collectedBy ?? sharedExtractor(selected ? [selected] : item.spec.candidates) ?? options.source,
             ...(decision.actor?.id ? { actor: decision.actor.id } : {}),
+            ...(fieldStatesByItem.has(item.metadata.name)
+                ? { metadata: { [FIELD_STATE_METADATA_KEY]: fieldStateClaimMetadata(fieldStatesByItem.get(item.metadata.name)) } }
+                : {}),
         };
         addConsistent(claims, claim, "claim target");
     }
@@ -192,6 +217,20 @@ function assertCanonicalResult(item, result) {
         || canonicalJson(decision.editedValue) !== canonicalJson(result.editedValue)) {
         throw new Error(`Review result ${result.reviewItemName} contradicts its canonical ReviewDecision.`);
     }
+    // Accepting one value of a conflict would project it as if it had been the
+    // only value; a choice between conflicting values is select-proposed.
+    if (result.decision === "accept-proposed" && item.spec.candidates.filter((candidate) => candidate.role === "proposed").length > 1) {
+        throw new Error(`Review result ${result.reviewItemName} accepts one proposed value of a conflict; a choice between conflicting values must be a select-proposed decision that records the values it passed over.`);
+    }
+    // A choice names exactly the proposed values it passed over; no other
+    // decision names any.
+    const expectedUnselected = result.decision === "select-proposed" && selected
+        ? item.spec.candidates.filter((candidate) => candidate.role === "proposed" && candidate.id !== selected.id).map((candidate) => candidate.id)
+        : [];
+    if (canonicalJson(decision.unselectedCandidateIds ?? []) !== canonicalJson(expectedUnselected)
+        || (result.decision === "select-proposed" && expectedUnselected.length === 0)) {
+        throw new Error(`Review result ${result.reviewItemName} does not record the proposed values its ${result.decision} decision passed over.`);
+    }
     if ((result.decision === "could-not-confirm") !== (decision.resolution === "could_not_confirm")) {
         throw new Error(`Review result ${result.reviewItemName} contradicts its canonical review resolution.`);
     }
@@ -210,6 +249,11 @@ function assertCanonicalResult(item, result) {
         }
     }
 }
+/** The projected Candidate record id of a ReviewItem candidate. */
+function recordIdFor(item, candidateId) {
+    const candidate = item.spec.candidates.find((entry) => entry.id === candidateId);
+    return candidate?.projection?.candidateId ?? candidateId;
+}
 function claimTargetIdentity(target) {
     const { claimId: _claimId, ...identity } = target;
     return identity;

package/dist/src/console/review-console-server.js

@@ -18,6 +18,7 @@ import { readFile as readFileAsync } from "node:fs/promises";
 import { resolve, join, dirname, extname, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createServerReviewSessionRecord, currentSessionState, deriveServerReviewSessionApplyResult, } from "../review-workbench/server-review-session.js";
+import { attestReviewQueueExtraction } from "../review-workbench/queue-binding.js";
 import { appendReviewSessionEvents, readReviewSessionFile, reviewSessionRevision, storedReviewSessionName, updateReviewSessionFile, } from "../review-session-file.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -404,9 +405,15 @@ let activeItemName = null;
 async function fetchAndMount() {
   try {
     const res = await fetch("/api/session");
-    if (!res.ok) throw new Error("Session fetch failed: " + res.status);
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      showSaveStatus(body.error || ("The session could not be loaded (HTTP " + res.status + ")."));
+      const root = document.getElementById("review-workbench");
+      if (root) root.innerHTML = "";
+      return;
+    }
     const data = await res.json();
-    const { snapshot, events, revision } = data;
+    const { snapshot, events, revision, extractionImport } = data;
     const state = events && events.length > 0
       ? replayReviewSessionEvents(snapshot, events)
       : snapshot;
@@ -419,7 +426,7 @@ async function fetchAndMount() {
     const root = document.getElementById("review-workbench");
     if (!root) return;
 
-    mountReviewWorkbench(root, state, { eventStore: createConsoleEventStore(revision) });
+    mountReviewWorkbench(root, state, { eventStore: createConsoleEventStore(revision), ...(extractionImport ? { extractionImport } : {}) });
   } catch (err) {
     console.error("[console] Mount error:", err);
   }
@@ -602,12 +609,22 @@ export async function startReviewConsoleServer(options) {
             // ---- Session read ----
             if (pathname === "/api/session" && req.method === "GET") {
                 const content = await readSession(sessionPath);
+                // A queue that does not match the extraction import stored with it is
+                // not served for review; one without a stored import is served, and the
+                // workbench marks it unverified.
+                const attestation = attestReviewQueueExtraction(content.snapshot.items, content.extractionImport);
+                if (attestation.state === "diverges") {
+                    sendJson(res, 409, { error: attestation.message, queueAttestation: attestation.state });
+                    return;
+                }
                 sendJson(res, 200, {
                     session: content.session,
                     snapshot: content.snapshot,
                     events: content.events,
                     revision: reviewSessionRevision(content.events),
                     state: currentSessionState(content.snapshot, content.events),
+                    queueAttestation: attestation.state,
+                    ...(content.extractionImport !== undefined ? { extractionImport: content.extractionImport } : {}),
                 });
                 return;
             }
@@ -660,6 +677,7 @@ export async function startReviewConsoleServer(options) {
                             record,
                             events: nextEvents,
                             requiredResolvedItems: "none",
+                            extractionImport: content.extractionImport,
                         });
                         issueMessages = applyResult.ok
                             ? []
@@ -672,7 +690,7 @@ export async function startReviewConsoleServer(options) {
                         return { result: { status: 422, body: { error: `Validation failed: ${issueMessages.join("; ")}` } } };
                     }
                     return {
-                        next: { session: content.session, snapshot, events: nextEvents },
+                        next: { ...content, session: content.session, snapshot, events: nextEvents },
                         result: {
                             status: 200,
                             body: { ok: true, eventCount: nextEvents.length, revision: reviewSessionRevision(nextEvents) },

package/dist/src/decision-carry-forward.d.ts

@@ -0,0 +1,157 @@
+import type { ReviewDecision, ReviewItem } from "./review-resource.js";
+/**
+ * Decisions across review rounds (#295).
+ *
+ * A new extraction of the same document gives every review item a new identity,
+ * so on its own every re-extraction sends every field back to review. Given the
+ * producer's stable slot identity and per-candidate version identity, a
+ * decision on a slot whose candidates did not change is carried forward to the
+ * new round, and a decision that a later one replaces is marked superseded.
+ *
+ * Vocabulary follows the round receipts producers already keep: a decision is
+ * `carried-forward` (made in an earlier round and still holding because its
+ * candidates are unchanged) or `affirmed` (made against this round's item).
+ *
+ * Survey does not invent slot or version identities: they come from the
+ * producer, and every item and candidate must carry one. Survey additionally
+ * compares each candidate's value, full locator, source evidence and full
+ * claim target, so a
+ * decision is never carried across a candidate whose content changed, even if a
+ * producer reused a version identity.
+ *
+ * Both records are content-addressed (`id` is a digest of every other field)
+ * and immutable: a record that changes is a new record.
+ */
+export declare const decisionCarryForwardKind: "survey.decision-carry-forward";
+export declare const decisionSupersessionKind: "survey.decision-supersession";
+/** How a decision reads in a round. */
+export type DecisionBasis = "carried-forward" | "affirmed";
+/** The terminal resolution a decision reached, as carry-forward reads it. */
+export type CarriedResolution = "accepted" | "rejected" | "could_not_confirm";
+/** One review item in a round, with the producer's slot and version identities. */
+export interface RoundReviewItem {
+    readonly item: ReviewItem;
+    /** Producer slot identity: the same field of the same source lineage across rounds. */
+    readonly slotId: string;
+    /** Producer version identity of every candidate of `item`, keyed by candidate id. */
+    readonly candidateVersionIds: Readonly<Record<string, string>>;
+}
+/** A decision made in an earlier round, with the round item it was made on. */
+export interface PriorRoundDecision extends RoundReviewItem {
+    readonly decision: ReviewDecision;
+}
+/** A decision named by content: its resource name and the digest of its canonical bytes. */
+export interface DecisionReference {
+    readonly name: string;
+    readonly digest: string;
+}
+export interface DecisionCarryForward {
+    /** `sha256:` digest of every other field; recomputed on validation. */
+    readonly id: string;
+    readonly kind: typeof decisionCarryForwardKind;
+    readonly schemaVersion: 1;
+    readonly priorDecision: DecisionReference;
+    readonly slotId: string;
+    /** Sorted, unique version ids of the slot's candidates, identical in both rounds. */
+    readonly versionIds: readonly string[];
+    readonly roundId: string;
+    /** The new round's review item the decision now applies to. */
+    readonly reviewItemName: string;
+    /** The new round's candidate the prior decision selected, when it selected one. */
+    readonly candidateId?: string;
+    readonly resolution: CarriedResolution;
+    readonly basis: "carried-forward";
+}
+/**
+ * Why a decision was superseded: its slot's candidates changed and the new
+ * version was decided (`candidate-changed`), or the unchanged slot was
+ * reviewed again and decided anew (`re-reviewed`).
+ */
+export type SupersessionReason = "candidate-changed" | "re-reviewed";
+export interface DecisionSupersession {
+    /** `sha256:` digest of every other field; recomputed on validation. */
+    readonly id: string;
+    readonly kind: typeof decisionSupersessionKind;
+    readonly schemaVersion: 1;
+    readonly priorDecision: DecisionReference;
+    readonly newDecision: DecisionReference;
+    readonly slotId: string;
+    readonly reason: SupersessionReason;
+}
+/**
+ * Which prior resolutions may be carried forward. Only `accepted` is carried
+ * unless a policy names others explicitly: a rejection or a could-not-confirm
+ * is a judgment about evidence a new round may have changed around it.
+ */
+export interface CarryForwardPolicy {
+    readonly carry: readonly CarriedResolution[];
+}
+export declare const defaultCarryForwardPolicy: CarryForwardPolicy;
+export type NeedsReviewReason = 
+/** No prior decision was made on this slot. */
+"no-prior-decision"
+/** The slot's candidate versions differ from the ones the prior decision saw. */
+ | "candidate-changed"
+/** A version id matched, but the candidate's value, locator, source or claim target did not. */
+ | "candidate-content-changed"
+/** The prior decision's resolution is not one the policy carries. */
+ | "resolution-not-carried"
+/** More than one live prior decision names this slot. */
+ | "ambiguous-prior-decisions";
+export interface CarriedForwardItem {
+    readonly item: RoundReviewItem;
+    readonly carryForward: DecisionCarryForward;
+}
+export interface NeedsReviewItem {
+    readonly item: RoundReviewItem;
+    readonly reason: NeedsReviewReason;
+    /** The prior decision the item could not inherit, when there was one. */
+    readonly priorDecision?: DecisionReference;
+}
+export interface SplitRoundForCarryForwardInput {
+    /** Identity of the new round. */
+    readonly roundId: string;
+    readonly items: readonly RoundReviewItem[];
+    readonly priorDecisions: readonly PriorRoundDecision[];
+    /** Supersessions already recorded: a prior decision they name is no longer live. */
+    readonly supersessions?: readonly DecisionSupersession[];
+    readonly policy?: CarryForwardPolicy;
+}
+export interface SplitRoundForCarryForwardResult {
+    readonly carriedForward: readonly CarriedForwardItem[];
+    readonly needsReview: readonly NeedsReviewItem[];
+}
+/**
+ * Splits a new round's items into those that inherit a prior decision
+ * (with a {@link DecisionCarryForward} record naming it) and those that need
+ * review. Pure; performs no I/O. An item carries forward only when exactly one
+ * live prior decision names its slot, the slot's candidates have the same
+ * version ids in both rounds, each candidate's value, locator, excerpt and
+ * source are unchanged, and the policy carries the prior resolution.
+ */
+export declare function splitRoundForCarryForward(input: SplitRoundForCarryForwardInput): SplitRoundForCarryForwardResult;
+export interface BuildDecisionSupersessionInput {
+    readonly prior: PriorRoundDecision;
+    /** The new round's item the new decision was made on. */
+    readonly item: RoundReviewItem;
+    readonly decision: ReviewDecision;
+}
+/**
+ * Records that `decision`, made on the new round's item for the same slot,
+ * replaces `prior`. The reason is derived: `candidate-changed` when the slot's
+ * candidate versions or content differ, `re-reviewed` when they do not.
+ */
+export declare function buildDecisionSupersession(input: BuildDecisionSupersessionInput): DecisionSupersession;
+/** The name and canonical digest of a decision. */
+export declare function decisionReference(decision: ReviewDecision): DecisionReference;
+/**
+ * The terminal resolution a decision reached: `could_not_confirm`, `rejected`
+ * for a rejected status, `accepted` for a verified or assumed one. Undefined
+ * for a decision that reached none (a `proposed` status without
+ * could-not-confirm).
+ */
+export declare function decisionResolution(decision: ReviewDecision): CarriedResolution | undefined;
+/** Validates a stored carry-forward record: its shape and its content-addressed id. */
+export declare function validateDecisionCarryForward(value: unknown): DecisionCarryForward;
+/** Validates a stored supersession record: its shape and its content-addressed id. */
+export declare function validateDecisionSupersession(value: unknown): DecisionSupersession;