@kontourai/survey 7.0.0 → 8.1.0

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;

package/dist/src/decision-carry-forward.js

@@ -0,0 +1,295 @@
+import { sha256Hex } from "./sha256.js";
+import { canonicalJson } from "./review-workbench/canonical.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 const decisionCarryForwardKind = "survey.decision-carry-forward";
+export const decisionSupersessionKind = "survey.decision-supersession";
+export const defaultCarryForwardPolicy = Object.freeze({ carry: Object.freeze(["accepted"]) });
+/**
+ * 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 function splitRoundForCarryForward(input) {
+    const roundId = nonEmpty(input.roundId, "roundId");
+    const policy = normalizePolicy(input.policy ?? defaultCarryForwardPolicy);
+    const superseded = new Set((input.supersessions ?? []).map((record) => validateDecisionSupersession(record).priorDecision.digest));
+    const priorBySlot = new Map();
+    for (const prior of input.priorDecisions) {
+        assertRoundItem(prior, "prior decision");
+        assertDecisionNamesItem(prior.decision, prior.item);
+        if (superseded.has(decisionReference(prior.decision).digest))
+            continue;
+        priorBySlot.set(prior.slotId, [...(priorBySlot.get(prior.slotId) ?? []), prior]);
+    }
+    const seenSlots = new Set();
+    const carriedForward = [];
+    const needsReview = [];
+    for (const item of input.items) {
+        assertRoundItem(item, "round item");
+        if (seenSlots.has(item.slotId))
+            throw new Error(`Round ${roundId} has two items for slot ${item.slotId}.`);
+        seenSlots.add(item.slotId);
+        const priors = priorBySlot.get(item.slotId) ?? [];
+        if (priors.length === 0) {
+            needsReview.push({ item, reason: "no-prior-decision" });
+            continue;
+        }
+        if (priors.length > 1) {
+            needsReview.push({ item, reason: "ambiguous-prior-decisions" });
+            continue;
+        }
+        const prior = priors[0];
+        const priorDecision = decisionReference(prior.decision);
+        const priorVersions = sortedVersions(prior);
+        const versions = sortedVersions(item);
+        if (canonicalJson(priorVersions) !== canonicalJson(versions)) {
+            needsReview.push({ item, reason: "candidate-changed", priorDecision });
+            continue;
+        }
+        if (!sameCandidateContent(prior, item)) {
+            needsReview.push({ item, reason: "candidate-content-changed", priorDecision });
+            continue;
+        }
+        const resolution = decisionResolution(prior.decision);
+        if (resolution === undefined || !policy.carry.includes(resolution)) {
+            needsReview.push({ item, reason: "resolution-not-carried", priorDecision });
+            continue;
+        }
+        const priorCandidateId = prior.decision.spec.candidateId;
+        const candidateId = priorCandidateId === undefined ? undefined : candidateWithVersion(item, prior.candidateVersionIds[priorCandidateId]).id;
+        carriedForward.push({
+            item,
+            carryForward: sealCarryForward({
+                kind: decisionCarryForwardKind,
+                schemaVersion: 1,
+                priorDecision,
+                slotId: item.slotId,
+                versionIds: versions,
+                roundId,
+                reviewItemName: item.item.metadata.name,
+                ...(candidateId !== undefined ? { candidateId } : {}),
+                resolution,
+                basis: "carried-forward",
+            }),
+        });
+    }
+    return Object.freeze({ carriedForward: Object.freeze(carriedForward), needsReview: Object.freeze(needsReview) });
+}
+/**
+ * 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 function buildDecisionSupersession(input) {
+    assertRoundItem(input.prior, "prior decision");
+    assertRoundItem(input.item, "round item");
+    assertDecisionNamesItem(input.prior.decision, input.prior.item);
+    assertDecisionNamesItem(input.decision, input.item.item);
+    if (input.prior.slotId !== input.item.slotId)
+        throw new Error(`A supersession needs one slot; the prior decision is on ${input.prior.slotId} and the new one on ${input.item.slotId}.`);
+    const priorDecision = decisionReference(input.prior.decision);
+    const newDecision = decisionReference(input.decision);
+    if (priorDecision.digest === newDecision.digest)
+        throw new Error("A decision cannot supersede itself.");
+    const unchanged = canonicalJson(sortedVersions(input.prior)) === canonicalJson(sortedVersions(input.item)) && sameCandidateContent(input.prior, input.item);
+    return sealSupersession({
+        kind: decisionSupersessionKind,
+        schemaVersion: 1,
+        priorDecision,
+        newDecision,
+        slotId: input.item.slotId,
+        reason: unchanged ? "re-reviewed" : "candidate-changed",
+    });
+}
+/** The name and canonical digest of a decision. */
+export function decisionReference(decision) {
+    if (decision?.kind !== "ReviewDecision")
+        throw new Error("A decision reference needs a ReviewDecision.");
+    return { name: nonEmpty(decision.metadata?.name, "decision name"), digest: `sha256:${sha256Hex(canonicalJson(decision))}` };
+}
+/**
+ * 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 function decisionResolution(decision) {
+    if (decision.spec.resolution === "could_not_confirm")
+        return "could_not_confirm";
+    if (decision.spec.status === "rejected")
+        return "rejected";
+    if (decision.spec.status === "verified" || decision.spec.status === "assumed")
+        return "accepted";
+    return undefined;
+}
+/** Validates a stored carry-forward record: its shape and its content-addressed id. */
+export function validateDecisionCarryForward(value) {
+    const record = object(value, "DecisionCarryForward");
+    exactKeys(record, ["id", "kind", "schemaVersion", "priorDecision", "slotId", "versionIds", "roundId", "reviewItemName", "resolution", "basis"], ["candidateId"], "DecisionCarryForward");
+    if (record.kind !== decisionCarryForwardKind || record.schemaVersion !== 1 || record.basis !== "carried-forward")
+        throw new Error("DecisionCarryForward kind, schemaVersion or basis is invalid.");
+    validateReference(record.priorDecision, "priorDecision");
+    nonEmpty(record.slotId, "slotId");
+    nonEmpty(record.roundId, "roundId");
+    nonEmpty(record.reviewItemName, "reviewItemName");
+    if (record.candidateId !== undefined)
+        nonEmpty(record.candidateId, "candidateId");
+    if (!Array.isArray(record.versionIds) || record.versionIds.length === 0)
+        throw new Error("DecisionCarryForward versionIds must be a non-empty array.");
+    record.versionIds.forEach((entry, index) => {
+        nonEmpty(entry, "versionId");
+        if (index > 0 && !(record.versionIds[index - 1] < entry))
+            throw new Error("DecisionCarryForward versionIds must be sorted and unique.");
+    });
+    if (!["accepted", "rejected", "could_not_confirm"].includes(record.resolution))
+        throw new Error("DecisionCarryForward resolution is invalid.");
+    const { id, ...payload } = record;
+    if (id !== recordDigest(decisionCarryForwardKind, payload))
+        throw new Error("DecisionCarryForward id is not the digest of its fields.");
+    return deepFreeze(structuredClone(record));
+}
+/** Validates a stored supersession record: its shape and its content-addressed id. */
+export function validateDecisionSupersession(value) {
+    const record = object(value, "DecisionSupersession");
+    exactKeys(record, ["id", "kind", "schemaVersion", "priorDecision", "newDecision", "slotId", "reason"], [], "DecisionSupersession");
+    if (record.kind !== decisionSupersessionKind || record.schemaVersion !== 1)
+        throw new Error("DecisionSupersession kind or schemaVersion is invalid.");
+    validateReference(record.priorDecision, "priorDecision");
+    validateReference(record.newDecision, "newDecision");
+    nonEmpty(record.slotId, "slotId");
+    if (record.reason !== "candidate-changed" && record.reason !== "re-reviewed")
+        throw new Error("DecisionSupersession reason is invalid.");
+    if (record.priorDecision.digest === record.newDecision.digest)
+        throw new Error("A decision cannot supersede itself.");
+    const { id, ...payload } = record;
+    if (id !== recordDigest(decisionSupersessionKind, payload))
+        throw new Error("DecisionSupersession id is not the digest of its fields.");
+    return deepFreeze(structuredClone(record));
+}
+function sealCarryForward(payload) {
+    return deepFreeze({ id: recordDigest(decisionCarryForwardKind, payload), ...payload });
+}
+function sealSupersession(payload) {
+    return deepFreeze({ id: recordDigest(decisionSupersessionKind, payload), ...payload });
+}
+function recordDigest(kind, payload) {
+    return `sha256:${sha256Hex(canonicalJson({ kind: `${kind}/v1`, payload }))}`;
+}
+/** Every candidate of the item has exactly one non-empty version id, and ids are unique within the item. */
+function assertRoundItem(entry, label) {
+    nonEmpty(entry.slotId, `${label} slotId`);
+    const candidateIds = entry.item.spec.candidates.map((candidate) => candidate.id);
+    if (new Set(candidateIds).size !== candidateIds.length)
+        throw new Error(`ReviewItem ${entry.item.metadata.name} has duplicate candidate ids.`);
+    const versionKeys = Object.keys(entry.candidateVersionIds ?? {}).sort();
+    if (canonicalJson(versionKeys) !== canonicalJson([...candidateIds].sort())) {
+        throw new Error(`ReviewItem ${entry.item.metadata.name} (${label}) must carry a producer version id for exactly its candidates.`);
+    }
+    const versions = Object.values(entry.candidateVersionIds);
+    versions.forEach((version) => nonEmpty(version, `${label} versionId`));
+    if (new Set(versions).size !== versions.length)
+        throw new Error(`ReviewItem ${entry.item.metadata.name} (${label}) has two candidates with one version id.`);
+}
+function assertDecisionNamesItem(decision, item) {
+    if (decision.spec.reviewItemName !== item.metadata.name)
+        throw new Error(`ReviewDecision ${decision.metadata.name} names ${decision.spec.reviewItemName}, not ${item.metadata.name}.`);
+    if (decision.spec.candidateId !== undefined && !item.spec.candidates.some((candidate) => candidate.id === decision.spec.candidateId)) {
+        throw new Error(`ReviewDecision ${decision.metadata.name} selects candidate ${decision.spec.candidateId}, which ReviewItem ${item.metadata.name} does not hold.`);
+    }
+}
+function sortedVersions(entry) {
+    return Object.values(entry.candidateVersionIds).sort();
+}
+function candidateWithVersion(entry, versionId) {
+    const id = Object.keys(entry.candidateVersionIds).find((candidateId) => entry.candidateVersionIds[candidateId] === versionId);
+    return entry.item.spec.candidates.find((candidate) => candidate.id === id);
+}
+/** For each version id, the prior and new candidates carry the same value and evidence. */
+function sameCandidateContent(prior, next) {
+    return Object.entries(prior.candidateVersionIds).every(([candidateId, versionId]) => {
+        const before = prior.item.spec.candidates.find((candidate) => candidate.id === candidateId);
+        const after = candidateWithVersion(next, versionId);
+        return canonicalJson(candidateContent(before)) === canonicalJson(candidateContent(after));
+    });
+}
+/** What a decision was made about: the value, the evidence behind it, and the claim it is for. */
+function candidateContent(candidate) {
+    return {
+        role: candidate.role ?? null,
+        value: candidate.value,
+        // The whole locator (scheme, locator, excerpt) and the whole claim target
+        // (subject, field, impact and the rest): a decision is about this value,
+        // at this place in the source, for this claim.
+        locator: candidate.locator ?? null,
+        claimTarget: candidate.claimTarget,
+        sourceRef: candidate.source.sourceRef,
+        sourceChecksum: candidate.source.checksum ?? null,
+    };
+}
+function normalizePolicy(policy) {
+    if (!policy || !Array.isArray(policy.carry))
+        throw new Error("A carry-forward policy must list the resolutions it carries.");
+    for (const resolution of policy.carry) {
+        if (!["accepted", "rejected", "could_not_confirm"].includes(resolution))
+            throw new Error(`Carry-forward policy names an unknown resolution: ${String(resolution)}.`);
+    }
+    return policy;
+}
+function validateReference(value, label) {
+    const reference = object(value, label);
+    exactKeys(reference, ["name", "digest"], [], label);
+    nonEmpty(reference.name, `${label}.name`);
+    if (typeof reference.digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(reference.digest))
+        throw new Error(`${label}.digest must be a sha256:<64 hex> digest.`);
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object.`);
+    return value;
+}
+function exactKeys(value, required, optional, label) {
+    for (const key of required)
+        if (!Object.hasOwn(value, key))
+            throw new Error(`${label}.${key} is required.`);
+    for (const key of Object.keys(value))
+        if (!required.includes(key) && !optional.includes(key))
+            throw new Error(`${label}.${key} is unexpected.`);
+}
+function nonEmpty(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${label} must be a non-empty string.`);
+    return value;
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object") {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/src/extraction-envelope.d.ts

@@ -197,8 +197,9 @@ export type ResolvedExtractionArtifact = {
  * artifact text. `verified` means the supplied text matched the envelope's
  * digest and length and every proposal that produced a ReviewItem matched its
  * span; `unverified` means no text was supplied, or the text did not verify
- * (a diagnostic then says why). Records written before this field existed have
- * no `provenance` and are unverified.
+ * (a diagnostic then says why). Required: a record without it, or with any
+ * other value, is refused, so a record whose provenance was stripped cannot
+ * pass as the one-item-per-proposal shape Survey wrote before 6.0.0.
  */
 export type ExtractionEnvelopeImportProvenance = "verified" | "unverified";
 /**
@@ -253,7 +254,7 @@ export interface ExtractionEnvelopeImport {
     status: {
         state: "grounded" | "unresolved";
         diagnostics: ExtractionEnvelopeImportDiagnostic[];
-        provenance?: ExtractionEnvelopeImportProvenance;
+        provenance: ExtractionEnvelopeImportProvenance;
     };
 }
 export interface ExtractionEnvelopeImportResult {

package/dist/src/extraction-envelope.js

@@ -333,8 +333,6 @@ function excerptMismatchDiagnostic(index, proposal) {
  * written: each diagnostic is rebuilt from its own fields and must match.
  */
 function verificationDiagnosticsAreCoherent(envelope, provenance, diagnostics) {
-    if (provenance === undefined)
-        return diagnostics.length === 0;
     const prepared = envelope.result.preparedArtifact;
     const rebuild = (value) => {
         if (!value || typeof value !== "object" || Array.isArray(value) || !prepared)
@@ -422,7 +420,9 @@ function validateImport(value) {
     if (targets.length !== envelope.result.proposals.length)
         throw new Error("spec.claimTargets must align with proposals.");
     const status = obj(record.status, "status");
-    exact(status, ["state", "diagnostics"], "status", ["provenance"]);
+    exact(status, ["state", "diagnostics", "provenance"], "status");
+    if (status.provenance !== "verified" && status.provenance !== "unverified")
+        throw new Error("status.provenance must be \"verified\" or \"unverified\".");
     const diagnostics = array(status.diagnostics, "status.diagnostics");
     const expected = diagnosticsFor(envelope);
     if (canonicalJson(diagnostics.slice(0, expected.length)) !== canonicalJson(expected)

package/dist/src/field-states.d.ts

@@ -0,0 +1,100 @@
+import { type CandidateVerification } from "./candidate-verification.js";
+import { type DecisionBasis, type DecisionCarryForward, type DecisionSupersession } from "./decision-carry-forward.js";
+import { type ExtractionEnvelopeImport } from "./extraction-envelope.js";
+import type { ReviewDecision } from "./review-resource.js";
+/**
+ * Per-field content and lifecycle states (#294), derived from records Survey
+ * holds and never stored as labels.
+ *
+ * Only states with a producer ship. `not_found` (the source was read in full
+ * and holds no value for the field) needs per-field chunk coverage and a
+ * per-field dropped-proposal count from the extractor, which no producer
+ * reports yet, so a field with no candidate in a complete run has no content
+ * state at all. Absence of a state never means verified.
+ */
+/** The claim-metadata key under which the Surface projection carries a field's states. */
+export declare const FIELD_STATE_METADATA_KEY = "survey.kontourai.io/field-state";
+/**
+ * What the extraction says about a field.
+ *
+ * - `value`: at least one candidate with evidence.
+ * - `conflicting`: two or more distinct candidate values for the one claim.
+ * - `unsupported`: every candidate has a verifier record saying contradicted
+ *   or not-addressed for its current value, and none saying supported.
+ * - `excluded`: the extraction proposed values for the field, but the import
+ *   left every one out because its excerpt was not at its cited span. The
+ *   field was read; its proposals are unverifiable, not disproven.
+ * - `not_covered`: no proposal at all, and the extraction reported that part
+ *   of the content was not read (a partial or failed run).
+ */
+export type FieldContentState = "value" | "conflicting" | "unsupported" | "excluded" | "not_covered";
+/**
+ * Where review stands for a field: `pending` (no decision), `accepted`,
+ * `rejected`, `could_not_confirm`, or `superseded` (a supersession record
+ * names the decision as replaced).
+ */
+export type FieldLifecycleState = "pending" | "accepted" | "rejected" | "could_not_confirm" | "superseded";
+/** A claim slot: the claim a proposal would project to, at its path indices. */
+export interface FieldSlot {
+    readonly subjectType: string;
+    readonly subjectId: string;
+    readonly facet: string;
+    readonly claimType: string;
+    readonly fieldOrBehavior: string;
+    readonly claimId?: string;
+    readonly pathIndices?: readonly number[];
+}
+/** Facts about a field that are not states. */
+export interface FieldStateSignals {
+    /** The run that produced this import stopped short or failed: other text may hold values. */
+    readonly incompleteRun?: true;
+    /** Proposals for this slot the import left out because their excerpt was not at their span. */
+    readonly excludedProposals?: number;
+    /** The import could not ground any candidate (its prepared artifact did not resolve or verify). */
+    readonly unresolvedImport?: true;
+}
+export interface FieldState {
+    readonly importName: string;
+    readonly slot: FieldSlot;
+    /** The ReviewItem for this slot, when the import produced one. */
+    readonly reviewItemName?: string;
+    /** Absent when no producer can state one (see the module note on `not_found`). */
+    readonly content?: FieldContentState;
+    /** Absent when the slot has no review item, so there is nothing to decide. */
+    readonly lifecycle?: FieldLifecycleState;
+    /** The decision the lifecycle comes from, when there is one. */
+    readonly decisionName?: string;
+    /** Whether that decision was made on this round's item or carried forward from an earlier one. */
+    readonly decisionBasis?: DecisionBasis;
+    readonly signals: FieldStateSignals;
+}
+export interface FieldStateImport {
+    readonly record: ExtractionEnvelopeImport;
+    /**
+     * The fields the extraction was asked for, so a field with no proposal is
+     * reported too. Without it only slots that have a proposal appear.
+     */
+    readonly expectedFields?: readonly FieldSlot[];
+}
+export interface DeriveFieldStatesInput {
+    readonly imports: readonly FieldStateImport[];
+    /** Decisions on this round's items. At most one per item. */
+    readonly decisions?: readonly ReviewDecision[];
+    /** Verifier records for this round's candidates (see `CandidateVerification`). */
+    readonly verifications?: readonly CandidateVerification[];
+    /** Records that the decisions they name as prior were replaced. */
+    readonly supersessions?: readonly DecisionSupersession[];
+    /** Earlier decisions carried forward onto this round's items. */
+    readonly carryForwards?: readonly DecisionCarryForward[];
+}
+/**
+ * Derives the content and lifecycle state of every field in the given
+ * imports. Pure: reads only its input. Each state appears only when the input
+ * that produces it is present: no verifications, no `unsupported`; no
+ * supersessions, no `superseded`.
+ */
+export declare function deriveFieldStates(input: DeriveFieldStatesInput): FieldState[];
+/** The lifecycle a workbench decision gives its item, as `deriveFieldStates` reads it. */
+export declare function lifecycleForDecision(decision: ReviewDecision | undefined): Exclude<FieldLifecycleState, "superseded">;
+/** The claim metadata the Surface projection carries for one field state. */
+export declare function fieldStateClaimMetadata(state: FieldState): Record<string, unknown>;