@kontourai/survey 2.2.3 → 2.3.0

package/dist/src/index.d.ts

@@ -5,7 +5,7 @@ export { buildReviewItemsFromExtractionEnvelopeImport, createExtractionEnvelopeR
 export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, } from "./review-workbench/extraction-inspector.js";
 export { resolvePortablePdfRegion } from "./pdf-layout.js";
 export type { PortablePdfBoundingBox, PortablePdfLayout, PortablePdfPageGeometry, PortablePdfRegionContext, PortablePdfTable, PortablePdfTableCell, PortablePdfTextElement, PortablePdfTextRange, } from "./pdf-layout.js";
-export type { ExtractionAlignmentState, ArtifactUnavailableCode, ExtractionInspectorCandidate, ExtractionInspectorEntry, ExtractionInspectorExportOptions, ExtractionInspectorFilters, ExtractionInspectorInput, ExtractionInspectorModel, ExtractionInspectorSource, ResolvedExtractionArtifact, } from "./review-workbench/extraction-inspector.js";
+export type { ExtractionAlignmentState, ArtifactUnavailableCode, BuiltExtractionInspectorCandidate, BuiltExtractionInspectorModel, ExtractionInspectorCandidate, ExtractionInspectorEntry, ExtractionInspectorExportOptions, ExtractionInspectorFilters, ExtractionInspectorInput, ExtractionInspectorModel, ExtractionInspectorSource, ResolvedExtractionArtifact, } from "./review-workbench/extraction-inspector.js";
 export type { ExtractionEnvelopeImport, ExtractionEnvelopeImportDiagnostic, ExtractionEnvelopeImportOptions, ExtractionEnvelopeImportResult, ExtractionEnvelopeResolutionIdentity, PortableExtractionOccurrence, PortableExtractionProposal, PortableExtractionResultEnvelope, PortablePreparedArtifactState, } from "./extraction-envelope.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, ReviewValueDescriptor, ReviewValueType, SourceReference, SurveyRecordProjectionHint, } from "./review-resource.js";
 export { candidateReviewRecord, candidateSetStatusFor, SurveyInputBuilder } from "./builder.js";

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

@@ -231,3 +231,16 @@ export interface ReviewSessionEventStatus {
 export type ReviewSession = ResourceEnvelope<"ReviewSession", ReviewSessionSpec, ReviewSessionStatus>;
 export type ReviewSessionEvent = ResourceEnvelope<"ReviewSessionEvent", ReviewSessionEventSpec, ReviewSessionEventStatus>;
 export type ReviewResource = ReviewItem | ReviewDecision | ReviewSession | ReviewSessionEvent;
+/**
+ * The one candidate carrying `candidateId`, or `undefined` if the item has none.
+ *
+ * Fails closed when two carry it. A `ReviewDecision` references its candidate by
+ * id and nothing else, so unlike a DOM binding there is no second handle to
+ * route on: if the id is ambiguous, the decision itself is undecidable, and
+ * picking the first match would project one candidate's value under another's
+ * decision. `ReviewItem` has never validated candidate-id uniqueness — the
+ * Surface record builder does (`assertUniqueCandidateIds`), but a
+ * caller-authored ReviewItem reaches the workbench without passing through it.
+ */
+export declare function assertSoleCandidateId(item: ReviewItem, candidateId: string): void;
+export declare function findSoleCandidateById(item: ReviewItem, candidateId: string): ReviewCandidate | undefined;

package/dist/src/review-resource.js

@@ -1 +1,22 @@
 export const reviewResourceApiVersion = "survey.kontourai.io/v1alpha1";
+/**
+ * The one candidate carrying `candidateId`, or `undefined` if the item has none.
+ *
+ * Fails closed when two carry it. A `ReviewDecision` references its candidate by
+ * id and nothing else, so unlike a DOM binding there is no second handle to
+ * route on: if the id is ambiguous, the decision itself is undecidable, and
+ * picking the first match would project one candidate's value under another's
+ * decision. `ReviewItem` has never validated candidate-id uniqueness — the
+ * Surface record builder does (`assertUniqueCandidateIds`), but a
+ * caller-authored ReviewItem reaches the workbench without passing through it.
+ */
+export function assertSoleCandidateId(item, candidateId) {
+    const matches = item.spec.candidates.filter((candidate) => candidate.id === candidateId);
+    if (matches.length > 1) {
+        throw new Error(`ReviewItem ${item.metadata.name} has ${matches.length} candidates with id ${candidateId}; candidate ids must be unique.`);
+    }
+}
+export function findSoleCandidateById(item, candidateId) {
+    assertSoleCandidateId(item, candidateId);
+    return item.spec.candidates.find((candidate) => candidate.id === candidateId);
+}

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

@@ -0,0 +1,72 @@
+/**
+ * The AUDIT DETAILS row contract.
+ *
+ * Two separate concerns live here, and they are not the same thing:
+ *
+ * 1. **Naming.** Every row inside a field card's AUDIT DETAILS carries
+ *    `data-audit-row="<key>"` — a stable machine name a host can select on.
+ *    Row *labels* are display copy and change; these keys do not. A host that
+ *    wants to restyle, reorder, or suppress a row on its own surface selects on
+ *    the key. Deriving a selector from label text is not a supported way to
+ *    address a row, and this attribute exists so nobody has to.
+ *
+ * 2. **Not printing the same fact twice.** Survey renders a card's identifiers
+ *    and provenance in more than one place (the ID stack, the Raw Source
+ *    section, each section's "IDs and trace links"). Where those placements
+ *    carry the *same fact*, the card printed one value two or three times under
+ *    different labels. {@link AuditFactTrace} keeps the first placement and
+ *    drops the later ones. That is Survey's job, not a consumer's — see
+ *    docs/consumer-integration-guide.md.
+ */
+/**
+ * PUBLIC CONTRACT — every `data-audit-row` key Survey emits.
+ *
+ * Additive by policy: a key may be added, and a row may stop being emitted when
+ * it is a duplicate placement or a constant, but a key is never renamed or
+ * repointed at a different fact. Hosts may hold selectors against these values.
+ */
+export declare const reviewAuditRowKeys: readonly ["current-candidate-id", "proposed-candidate-id", "claim-id", "raw-source-id", "locator", "model", "extractor", "extracted-at", "history-value", "candidate-id", "source-reference", "excerpt", "observed", "source-authority-class", "declared-by", "authority-scope", "extraction-id", "actor", "reviewed-at", "status", "rationale", "outcome", "checksum", "candidate-set-id", "authority-trace-status", "authority-trace-detail"];
+/** One of {@link reviewAuditRowKeys}. */
+export type ReviewAuditRowKey = (typeof reviewAuditRowKeys)[number];
+/**
+ * The identity of a *fact*, not of a string: which record a value came from and
+ * which property of it. Two placements share an identity only when they are the
+ * same property of the same record — which is exactly when printing both says
+ * nothing the first one did not.
+ *
+ * Matching on the rendered value instead conflates facts that merely coincide.
+ * A candidate whose `extraction.extractedAt` equals its `source.observedAt` —
+ * the stock fixture's shape, and a common one — would lose its `Observed` row
+ * entirely, and an auditor reading the card could not tell that field had ever
+ * existed. The labels differing is the signal that the facts differ.
+ */
+export interface AuditFactId {
+    /** The record the value belongs to: a candidate id, or the review item. */
+    readonly of: string;
+    /** The property path within that record. */
+    readonly property: string;
+}
+/** Per-card record of which facts have already been printed, and as what. */
+export interface AuditFactTrace {
+    /**
+     * Records `fact` and reports whether this card has already printed it with
+     * this same value. Placeholder and empty values are never recorded and never
+     * suppressed.
+     */
+    isRepeatPlacement(fact: AuditFactId, value: unknown): boolean;
+}
+/**
+ * Suppression requires BOTH conditions, and each rules out a different mistake.
+ *
+ * Identity alone would be too eager: placements that nominally report the same
+ * property can resolve through different fallback chains (a projection override
+ * versus the candidate's own field), so a matching identity does not guarantee
+ * a matching value. Value alone would be far too eager — that is what conflates
+ * `extracted-at` with `observed`.
+ *
+ * @param alreadyOnCard facts the card face shows outside AUDIT DETAILS (the
+ *   quoted excerpt, for one), so the audit surface does not reprint them.
+ */
+export declare function createAuditFactTrace(alreadyOnCard?: readonly (AuditFactId & {
+    readonly value: unknown;
+})[]): AuditFactTrace;

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

@@ -0,0 +1,133 @@
+/**
+ * The AUDIT DETAILS row contract.
+ *
+ * Two separate concerns live here, and they are not the same thing:
+ *
+ * 1. **Naming.** Every row inside a field card's AUDIT DETAILS carries
+ *    `data-audit-row="<key>"` — a stable machine name a host can select on.
+ *    Row *labels* are display copy and change; these keys do not. A host that
+ *    wants to restyle, reorder, or suppress a row on its own surface selects on
+ *    the key. Deriving a selector from label text is not a supported way to
+ *    address a row, and this attribute exists so nobody has to.
+ *
+ * 2. **Not printing the same fact twice.** Survey renders a card's identifiers
+ *    and provenance in more than one place (the ID stack, the Raw Source
+ *    section, each section's "IDs and trace links"). Where those placements
+ *    carry the *same fact*, the card printed one value two or three times under
+ *    different labels. {@link AuditFactTrace} keeps the first placement and
+ *    drops the later ones. That is Survey's job, not a consumer's — see
+ *    docs/consumer-integration-guide.md.
+ */
+/**
+ * PUBLIC CONTRACT — every `data-audit-row` key Survey emits.
+ *
+ * Additive by policy: a key may be added, and a row may stop being emitted when
+ * it is a duplicate placement or a constant, but a key is never renamed or
+ * repointed at a different fact. Hosts may hold selectors against these values.
+ */
+export const reviewAuditRowKeys = [
+    // Card-level identity
+    "current-candidate-id",
+    "proposed-candidate-id",
+    "claim-id",
+    "raw-source-id",
+    "locator",
+    "model",
+    "extractor",
+    "extracted-at",
+    // Unselected candidate history
+    "history-value",
+    "candidate-id",
+    // Raw Source
+    "source-reference",
+    "excerpt",
+    "observed",
+    "source-authority-class",
+    "declared-by",
+    "authority-scope",
+    "extraction-id",
+    // Review event
+    "actor",
+    "reviewed-at",
+    "status",
+    "rationale",
+    "outcome",
+    // Integrity posture
+    "checksum",
+    "candidate-set-id",
+    // Authority trace
+    "authority-trace-status",
+    "authority-trace-detail",
+];
+/**
+ * Values that report a fact as missing rather than carrying one. Two placements
+ * both reading "not provided" are not one fact printed twice, so a placeholder
+ * never suppresses a later placement and is never suppressed by an earlier one.
+ *
+ * Deliberately only the literals the workbench itself substitutes for an absent
+ * field — every one of them, and nothing else. Producer data is not ours to
+ * interpret: an extractor genuinely named "none" would be misread as an absence,
+ * so a general vocabulary of nullish-looking words does not belong here.
+ * "unknown" is the one string on both sides of that line: Survey emits it for a
+ * missing extractor or timestamp, and a producer could conceivably use it as a
+ * real name. The cost of getting that wrong is a duplicate row, never a dropped
+ * one, so it stays.
+ *
+ * Keep this in step with the `?? "…"` substitutions in review-surface-preview.ts
+ * and the ID-stack rows in review-workbench.ts. The last two entries are not
+ * reachable through today's traced placements; they are here so the set means
+ * what it says rather than what it currently needs to.
+ */
+const ABSENCE_VALUES = new Set([
+    "not provided",
+    "not recorded",
+    "unknown",
+    "no source excerpt provided.",
+    "no reviewer rationale provided.",
+]);
+/**
+ * Suppression requires BOTH conditions, and each rules out a different mistake.
+ *
+ * Identity alone would be too eager: placements that nominally report the same
+ * property can resolve through different fallback chains (a projection override
+ * versus the candidate's own field), so a matching identity does not guarantee
+ * a matching value. Value alone would be far too eager — that is what conflates
+ * `extracted-at` with `observed`.
+ *
+ * @param alreadyOnCard facts the card face shows outside AUDIT DETAILS (the
+ *   quoted excerpt, for one), so the audit surface does not reprint them.
+ */
+export function createAuditFactTrace(alreadyOnCard = []) {
+    const printed = new Map();
+    for (const fact of alreadyOnCard) {
+        if (carriesAFact(fact.value)) {
+            printed.set(factKey(fact), String(fact.value));
+        }
+    }
+    return {
+        isRepeatPlacement(fact, value) {
+            if (!carriesAFact(value)) {
+                return false;
+            }
+            const key = factKey(fact);
+            const already = printed.get(key);
+            if (already !== undefined) {
+                // Same identity but a different value is a divergence worth showing,
+                // not a repeat. Keep the first reading on record.
+                return already === String(value);
+            }
+            printed.set(key, String(value));
+            return false;
+        },
+    };
+}
+function factKey(fact) {
+    return `${fact.of}::${fact.property}`;
+}
+function carriesAFact(value) {
+    if (value === undefined || value === null) {
+        return false;
+    }
+    const text = String(value).trim();
+    return text.length > 0 && !ABSENCE_VALUES.has(text.toLocaleLowerCase());
+}

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

@@ -25,6 +25,44 @@ export type ExtractionInspectorInput = ExtractionInspectorEntry | {
 };
 export interface ExtractionInspectorCandidate {
     id: string;
+    /**
+     * PUBLIC CONTRACT — the element id of the source-highlight anchor that
+     * {@link mountExtractionInspector} renders for this candidate.
+     *
+     * A host that wants to link a fact back to the sentence it came from uses this
+     * value directly (`href="#" + highlightElementId`, or
+     * `document.getElementById(highlightElementId)`); it must never re-derive an id
+     * from {@link ExtractionInspectorCandidate.id}. The renderer reads this same
+     * field, so the value a host reads and the id in the DOM cannot drift apart.
+     *
+     * Optional **here** only because this type is also the shape a caller may hand
+     * to {@link mountExtractionInspector} directly; a model that came from
+     * {@link buildExtractionInspectorModel} is a
+     * {@link BuiltExtractionInspectorModel}, where it is always present. Take the
+     * builder's type if you want to link, and the guarantees below are yours.
+     * Mount fills in an id for any candidate that arrives without one, so a
+     * hand-authored model still renders — it just has nothing published to link to.
+     *
+     * Resolvable for **every** candidate in the model for as long as the inspector
+     * is mounted, in every posture. Anchors are deliberately exempt from the
+     * candidate list's paging and filtering (see
+     * {@link ExtractionInspectorMountOptions.pageSize}), and are rendered even when
+     * the prepared artifact is unavailable, digest-mismatched, or excerpt-
+     * mismatched — there is no highlighted span to land on then, so the anchor sits
+     * with the non-grounded posture message that explains why. A link that dies
+     * when a reviewer pages, filters, or opens a source that failed verification is
+     * the same broken promise as an id that drifted.
+     *
+     * Guaranteed unique across every candidate in one
+     * {@link BuiltExtractionInspectorModel}, and a valid CSS/HTML identifier.
+     *
+     * The reverse lookup — DOM node to candidate — is the equally public
+     * `data-highlight-candidate-id="<candidate.id>"` attribute on the same anchor.
+     *
+     * Deliberately omitted from {@link exportExtractionInspector}: the canonical
+     * export records extraction evidence, and a DOM binding is not evidence.
+     */
+    highlightElementId?: string;
     sourceKey: string;
     reviewItemName: string;
     proposalIndex: number;
@@ -57,6 +95,23 @@ export interface ExtractionInspectorModel {
     sources: ExtractionInspectorSource[];
     candidates: ExtractionInspectorCandidate[];
 }
+/**
+ * A candidate from {@link buildExtractionInspectorModel}, where the DOM binding
+ * is resolved rather than optional.
+ *
+ * The split exists so the linking guarantee can be unconditional without making
+ * the *input* shape unbuildable by hand. `ExtractionInspectorModel` stays what a
+ * caller may author and pass to mount; this is what the builder hands back, and
+ * only the builder can promise the id is present, unique, and the one the
+ * renderer will use.
+ */
+export interface BuiltExtractionInspectorCandidate extends ExtractionInspectorCandidate {
+    highlightElementId: string;
+}
+/** The model {@link buildExtractionInspectorModel} returns. Assignable anywhere an {@link ExtractionInspectorModel} is accepted. */
+export interface BuiltExtractionInspectorModel extends ExtractionInspectorModel {
+    candidates: BuiltExtractionInspectorCandidate[];
+}
 export interface ExtractionInspectorFilters {
     field?: string;
     provider?: string;
@@ -72,7 +127,17 @@ export interface ExtractionInspectorExportOptions {
     includeExcerpts?: boolean;
 }
 export interface ExtractionInspectorMountOptions {
-    /** Maximum candidate rows and source highlights mounted at once. Defaults to 100 and is capped at 500. */
+    /**
+     * Maximum candidate rows and painted source highlights mounted at once.
+     * Defaults to 100 and is capped at 500.
+     *
+     * This governs the candidate list and the `<mark>` painting only. The
+     * highlight *anchors* — the elements
+     * {@link ExtractionInspectorCandidate.highlightElementId} names — are mounted
+     * for every candidate in the model regardless of page or filter, because a
+     * host's link to a span must not go dead when a reviewer types in the filter
+     * box. Anchors are empty and inert; the per-candidate cost is one element.
+     */
     pageSize?: number;
 }
 /**
@@ -80,7 +145,7 @@ export interface ExtractionInspectorMountOptions {
  * public import boundary. The function rechecks the result/ReviewItem binding
  * and fails closed if mutable caller data has drifted since import.
  */
-export declare function buildExtractionInspectorModel(input: ExtractionInspectorInput): ExtractionInspectorModel;
+export declare function buildExtractionInspectorModel(input: ExtractionInspectorInput): BuiltExtractionInspectorModel;
 export declare function filterExtractionInspectorCandidates(model: ExtractionInspectorModel, filters: ExtractionInspectorFilters): ExtractionInspectorCandidate[];
 export declare function exportExtractionInspector(model: ExtractionInspectorModel, options?: ExtractionInspectorExportOptions): string;
 export declare function mountExtractionInspector(container: HTMLElement, model: ExtractionInspectorModel, options?: ExtractionInspectorMountOptions): () => void;