@kontourai/survey 6.1.0 → 7.0.0

package/dist/src/review-workbench/server-review-session.d.ts

@@ -3,7 +3,9 @@ import { type ReviewDecisionModeIssue } from "./producer-decision-mode.js";
 import { type ReviewSessionReplayIssue, type ReviewSessionReplayWarning } from "./review-session-replay.js";
 import type { ReviewDecision, ReviewSessionEvent } from "../review-resource.js";
 import { type ReviewQueueBinding } from "./queue-binding.js";
+import type { ExtractionEnvelopeImport, ExtractionEnvelopeImportResult } from "../extraction-envelope.js";
 import { type ReviewQueueSessionState } from "./review-queue-session.js";
+import type { ReviewPresentationAdapter } from "./review-presentation.js";
 export interface ServerReviewSessionRecord {
     readonly sessionName: string;
     readonly snapshot: ReviewQueueSessionState;
@@ -57,6 +59,8 @@ export interface DeriveServerReviewSessionApplyResultOptions {
     readonly currentSnapshot?: ReviewQueueSessionState;
     readonly currentEventCount?: number;
     readonly requiredResolvedItems?: ReviewSessionApplyResolutionRequirement;
+    /** The adapter the reviewer's card used; the recorded decision prompts render the target label and values with it. */
+    readonly presentationAdapter?: ReviewPresentationAdapter;
     /**
      * The queue binding taken when this session opened (see
      * ./queue-binding.ts). When present, the apply derivation refuses unless the
@@ -70,6 +74,15 @@ export interface DeriveServerReviewSessionApplyResultOptions {
      * consumer's storage, not be recomputed at call time.
      */
     readonly binding?: ReviewQueueBinding;
+    /**
+     * The extraction import record the snapshot's items were built from, as
+     * stored beside the session. When present, the derivation refuses (throws
+     * {@link UnattestedExtractionQueueError}) unless the record's snapshot items
+     * match it (see `validateReviewQueueAgainstExtractionImport`). When absent and
+     * the snapshot's items carry the extraction-envelope binding, the result
+     * carries an `unverified-extraction-queue` warning: nothing checked them.
+     */
+    readonly extractionImport?: ExtractionEnvelopeImport | ExtractionEnvelopeImportResult;
 }
 export declare function createServerReviewSessionRecord(options: CreateServerReviewSessionRecordOptions): ServerReviewSessionRecord;
 export declare function hashReviewSessionSnapshot(snapshot: ReviewQueueSessionState): string;
@@ -104,6 +117,8 @@ export interface ApplyReviewSessionOptions<TAction = never> {
     readonly currentSnapshot?: ReviewQueueSessionState;
     readonly currentEventCount?: number;
     readonly requiredResolvedItems?: ReviewSessionApplyResolutionRequirement;
+    /** See {@link DeriveServerReviewSessionApplyResultOptions.extractionImport}. */
+    readonly extractionImport?: ExtractionEnvelopeImport | ExtractionEnvelopeImportResult;
     /** When true, each result is checked against its item's producerPolicy.decisionMode. */
     readonly enforceProducerPolicy?: boolean;
     /** When provided, results are mapped to product apply actions in the same call. */
@@ -115,6 +130,9 @@ export type ApplyReviewSessionIssue = ReviewSessionApplyIssue | {
 } | {
     readonly code: "invalid-events";
     readonly message: string;
+} | {
+    readonly code: "unattested-extraction-queue";
+    readonly message: string;
 } | {
     readonly code: "decision-mode-violation";
     readonly reviewItemName: string;

package/dist/src/review-workbench/server-review-session.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { deriveReviewSessionApplyResultForSnapshot, mapReviewWorkbenchResultsToApplyActions, ReviewApplyActionMappingError, } from "./review-workbench.js";
 import { validateReviewDecisionMode, } from "./producer-decision-mode.js";
 import { validateReviewSessionEventsForSnapshot, } from "./review-session-replay.js";
-import { assertReviewQueueBinding } from "./queue-binding.js";
+import { assertReviewQueueBinding, attestReviewQueueExtraction, UnattestedExtractionQueueError, } from "./queue-binding.js";
 import { replayReviewSessionEvents } from "./review-queue-session.js";
 import { canonicalJson } from "./canonical.js";
 export class StaleServerReviewSessionError extends Error {
@@ -104,11 +104,25 @@ export function deriveServerReviewSessionApplyResult(options) {
         assertServerReviewSessionFreshness(options.record, options.currentSnapshot, options.currentEventCount);
     }
     assertServerReviewSessionEvents(options.record, options.events);
-    return deriveReviewSessionApplyResultForSnapshot({
+    const attestation = attestReviewQueueExtraction(options.record.snapshot.items, options.extractionImport);
+    if (attestation.state === "diverges") {
+        throw new UnattestedExtractionQueueError(attestation.issues);
+    }
+    const derived = deriveReviewSessionApplyResultForSnapshot({
         snapshot: options.record.snapshot,
         events: options.events,
         requiredResolvedItems: options.requiredResolvedItems,
+        presentationAdapter: options.presentationAdapter,
     });
+    return attestation.state === "unverified"
+        ? {
+            ...derived,
+            warnings: [
+                ...(derived.warnings ?? []),
+                { code: "unverified-extraction-queue", itemNames: attestation.itemNames, message: attestation.message },
+            ],
+        }
+        : derived;
 }
 function staleIssuesForComparison(comparison) {
     const issues = [];
@@ -164,9 +178,13 @@ export function applyReviewSession(options) {
             currentSnapshot: options.currentSnapshot,
             currentEventCount: options.currentEventCount,
             requiredResolvedItems: options.requiredResolvedItems,
+            extractionImport: options.extractionImport,
         });
     }
     catch (error) {
+        if (error instanceof UnattestedExtractionQueueError) {
+            return { ok: false, issues: [{ code: "unattested-extraction-queue", message: error.message }], decisions: [], results: [], actions: [] };
+        }
         if (error instanceof StaleServerReviewSessionError) {
             return { ok: false, issues: [{ code: "stale-session", message: error.message }], decisions: [], results: [], actions: [] };
         }

package/dist/src/surface-reviewed-extraction.d.ts

@@ -1,6 +1,29 @@
 import type { SurveyExtractionEnvelopeImport, SurveyExtractionReviewDecision, SurveyExtractionReviewItem } from "@kontourai/surface";
 import type { ExtractionEnvelopeImport } from "./extraction-envelope.js";
 import type { ReviewDecision, ReviewItem } from "./review-resource.js";
+/**
+ * The version of the `@kontourai/surface` package whose entry point
+ * `resolveEntry` returns. Surface does not export its package.json, so this
+ * walks up from the entry to the nearest package.json named
+ * `@kontourai/surface`; other package.json files on the way (a nested
+ * `{ "type": "module" }`, say) are skipped. Throws a Survey error when the
+ * entry cannot be resolved, as in a bundle without `import.meta.resolve`, or
+ * no such package.json exists.
+ */
+export declare function surfaceVersionFromEntry(resolveEntry: () => string): string;
+/** Whether a Surface version accepts proposals without confidence. An unparseable version does not. */
+export declare function surfaceAcceptsAbsentConfidence(version: string): boolean;
+/**
+ * The record, typed for Surface's reviewed-extraction profile. A proposal
+ * without confidence passes through without one; no number is substituted.
+ * On a Surface older than 4.1.0, which rejects such a proposal, the record is
+ * refused by name instead.
+ *
+ * The version checked is that of the Surface copy Survey itself resolves. A
+ * consumer that projects with a different copy (for example Surface 4.0.0 of
+ * its own next to Survey's 4.2.0) gets Surface's own refusal instead of this
+ * one; dedupe Surface so that one copy is installed.
+ */
 export declare function toSurfaceReviewedExtractionImport(record: ExtractionEnvelopeImport): SurveyExtractionEnvelopeImport;
 export declare function toSurfaceReviewedExtractionItem(item: ReviewItem): SurveyExtractionReviewItem;
 export declare function toSurfaceReviewedExtractionDecision(decision: ReviewDecision): SurveyExtractionReviewDecision;

package/dist/src/surface-reviewed-extraction.js

@@ -1,7 +1,70 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The first Surface release whose reviewed-extraction profile accepts a proposal without confidence. */
+const ABSENT_CONFIDENCE_SINCE = [4, 1];
+let resolvedSurfaceVersion;
+const UNKNOWN_SURFACE_VERSION = "Cannot determine the installed @kontourai/surface version; refusing to export proposals without confidence.";
+/**
+ * The version of the `@kontourai/surface` package whose entry point
+ * `resolveEntry` returns. Surface does not export its package.json, so this
+ * walks up from the entry to the nearest package.json named
+ * `@kontourai/surface`; other package.json files on the way (a nested
+ * `{ "type": "module" }`, say) are skipped. Throws a Survey error when the
+ * entry cannot be resolved, as in a bundle without `import.meta.resolve`, or
+ * no such package.json exists.
+ */
+export function surfaceVersionFromEntry(resolveEntry) {
+    let dir;
+    try {
+        dir = dirname(fileURLToPath(resolveEntry()));
+    }
+    catch (error) {
+        throw new Error(UNKNOWN_SURFACE_VERSION, { cause: error });
+    }
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === "@kontourai/surface" && typeof pkg.version === "string")
+                return pkg.version;
+        }
+        catch { /* no readable package.json here; keep walking up */ }
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error(UNKNOWN_SURFACE_VERSION);
+        dir = parent;
+    }
+}
+/** The version of the `@kontourai/surface` copy this module resolves, cached once found. */
+function installedSurfaceVersion() {
+    return resolvedSurfaceVersion ??= surfaceVersionFromEntry(() => import.meta.resolve("@kontourai/surface"));
+}
+/** Whether a Surface version accepts proposals without confidence. An unparseable version does not. */
+export function surfaceAcceptsAbsentConfidence(version) {
+    const match = /^(\d+)\.(\d+)\.\d+/.exec(version);
+    if (!match)
+        return false;
+    const [major, minor] = [Number(match[1]), Number(match[2])];
+    return major > ABSENT_CONFIDENCE_SINCE[0] || (major === ABSENT_CONFIDENCE_SINCE[0] && minor >= ABSENT_CONFIDENCE_SINCE[1]);
+}
+/**
+ * The record, typed for Surface's reviewed-extraction profile. A proposal
+ * without confidence passes through without one; no number is substituted.
+ * On a Surface older than 4.1.0, which rejects such a proposal, the record is
+ * refused by name instead.
+ *
+ * The version checked is that of the Surface copy Survey itself resolves. A
+ * consumer that projects with a different copy (for example Surface 4.0.0 of
+ * its own next to Survey's 4.2.0) gets Surface's own refusal instead of this
+ * one; dedupe Surface so that one copy is installed.
+ */
 export function toSurfaceReviewedExtractionImport(record) {
     const unreported = record.spec.envelope.result.proposals.findIndex((proposal) => proposal.confidence === undefined);
     if (unreported !== -1) {
-        throw new Error(`Surface's reviewed-extraction profile requires a proposer confidence on every proposal; proposal ${unreported} of ${record.metadata.name} reports none.`);
+        const version = installedSurfaceVersion();
+        if (!surfaceAcceptsAbsentConfidence(version)) {
+            throw new Error(`@kontourai/surface ${version} requires a proposer confidence on every proposal (4.1.0 and later do not); proposal ${unreported} of ${record.metadata.name} reports none.`);
+        }
     }
     return record;
 }

package/dist/src/to-surface.js

@@ -7,6 +7,16 @@ import { canonicalJson } from "./review-workbench/canonical.js";
 /** Minimum labeled samples a calibration group needs before its empirical
  *  accuracy is emitted as a `conclusionConfidence.value`. */
 const DEFAULT_CALIBRATION_MIN_SAMPLES = 20;
+/**
+ * The evidence's own `confidence` replaces any a metadata spread carried. When
+ * the extraction reported none, the key is removed rather than set to
+ * undefined, so absence is absence in memory as well as on the wire.
+ */
+function withoutUndefinedConfidence(metadata) {
+    if (metadata.confidence === undefined)
+        delete metadata.confidence;
+    return metadata;
+}
 /**
  * Thrown when a claim's trusted status or value does not agree with the review
  * outcome it cites, or when the governing review cannot be chosen.
@@ -80,7 +90,8 @@ export function buildSurveyTrustBundle(input, options = {}) {
             derivationEdges: projection.derivationEdges,
             confidenceBasis: {
                 sourceQuality: "moderate",
-                extractionConfidence: candidate.confidence ?? extraction.confidence,
+                // An absent confidence stays absent; no key, no default.
+                ...((candidate.confidence ?? extraction.confidence) !== undefined ? { extractionConfidence: candidate.confidence ?? extraction.confidence } : {}),
                 // An auto-accept policy checked nothing but the proposer's own
                 // confidence, so its claims carry system authority and weak evidence;
                 // only a human review earns operator authority.
@@ -168,7 +179,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
             observedAt: rawSource.observedAt,
             collectedBy: projection.collectedBy,
             integrityRef: rawSource.checksum,
-            metadata: {
+            metadata: withoutUndefinedConfidence({
                 ...rawSource.metadata,
                 ...extraction.metadata,
                 ...candidate.metadata,
@@ -177,7 +188,7 @@ export function buildSurveyTrustBundle(input, options = {}) {
                 locatorScheme: rawSource.locatorScheme,
                 ...(rawSource.resolution ? { provenanceResolution: rawSource.resolution } : {}),
                 confidence: candidate.confidence ?? extraction.confidence,
-            },
+            }),
         });
         const rationale = projectionReview?.rationale ?? candidateSet.rationale;
         events.push({
@@ -606,8 +617,26 @@ function buildSurveyMetadata(input) {
                 },
             }
             : {}),
+        // A claim whose value was chosen from conflicting proposed values lists
+        // every value and marks the chosen one, so the claim never reads as if its
+        // value had been the only one proposed.
+        ...(proposedRoleCount(input.candidateSet) > 1
+            ? {
+                candidateSetStatus: input.candidateSet.status,
+                candidates: input.candidateSet.candidates.map((candidate) => ({
+                    candidateId: candidate.id,
+                    value: candidate.value,
+                    ...(candidate.id === input.candidate.id ? { selected: true } : {}),
+                    ...(candidate.rejectionReason !== undefined ? { rejectionReason: candidate.rejectionReason } : {}),
+                })),
+            }
+            : {}),
     };
 }
+/** How many of a set's candidates carry the `proposed` role (Survey writes it to `metadata.role`). */
+function proposedRoleCount(candidateSet) {
+    return candidateSet.candidates.filter((candidate) => candidate.metadata?.role === "proposed").length;
+}
 function statusFor(input) {
     if (input.review)
         return input.review.status;

package/package.json

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