@kontourai/survey 1.6.0 → 1.6.1

package/dist/src/index.d.ts

@@ -12,8 +12,8 @@ export { buildSurveyTrustBundle } from "./to-surface.js";
 export type { BuildSurveyTrustBundleOptions } from "./to-surface.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
 export type { LearningProjection, LearningProjectionKind, LearningProjectionSeverity, LearningProjectionSignal, } from "./learning-projections.js";
-export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
-export type { CanonicalReviewProofPayload, ReviewProofInput, } from "./review-proof.js";
+export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, verifyCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
+export type { CanonicalReviewProofPayload, CanonicalReviewProofPayloadV1, CanonicalReviewProofPayloadV2, ReviewProofInput, } from "./review-proof.js";
 export { fieldObservation } from "./field-observation.js";
 export type { FieldObservationInput } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";

package/dist/src/index.js

@@ -5,7 +5,7 @@ export { reviewedCandidateResolution } from "./reviewed-candidate-resolution.js"
 export { reviewedCurrentProposedResolution } from "./reviewed-current-proposed-resolution.js";
 export { buildSurveyTrustBundle } from "./to-surface.js";
 export { buildSurveyLearningProjections } from "./learning-projections.js";
-export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
+export { buildCanonicalReviewProofPayload, buildReviewProofAnchor, canonicalReviewProofJson, hashCanonicalReviewProofPayload, verifyCanonicalReviewProofPayload, REVIEW_PROOF_CONTRACT_VERSION, REVIEW_PROOF_PACKAGE_NAME, REVIEW_PROOF_SCHEMA, REVIEW_PROOF_SCHEMA_VERSION, } from "./review-proof.js";
 export { fieldObservation } from "./field-observation.js";
 export { repeatedObservation } from "./repeated-observation.js";
 export { sourceOfAuthorityObservation, sourceOfAuthorityObservationBuilder, SourceOfAuthorityObservationBuilder, } from "./source-of-authority-observation.js";

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

@@ -1,5 +1,5 @@
 import type { ReviewAuthorizing, ReviewAuthorizingAuthorizedAction } from "./types.js";
-export type ReviewAuthorizingIssueCode = "not-an-object" | "missing-kind" | "unknown-kind" | "missing-statement" | "missing-prompt" | "missing-response" | "missing-prompt-ref" | "missing-rendered-prompt" | "missing-action" | "invalid-action" | "missing-authority-ref";
+export type ReviewAuthorizingIssueCode = "not-an-object" | "missing-kind" | "unknown-kind" | "missing-statement" | "invalid-source" | "missing-prompt" | "missing-response" | "missing-prompt-ref" | "missing-rendered-prompt" | "missing-action" | "invalid-action" | "missing-authority-ref";
 export interface ReviewAuthorizingIssue {
     readonly code: ReviewAuthorizingIssueCode;
     readonly message: string;

package/dist/src/review-authorizing.js

@@ -43,6 +43,7 @@ function validateExplicitStatement(block) {
             message: "explicit-statement authorizing block requires a non-empty 'statement' string.",
         });
     }
+    validateOptionalSource(block.source, issues);
     return issues;
 }
 function validateExchange(block) {
@@ -59,8 +60,17 @@ function validateExchange(block) {
             message: "exchange authorizing block requires a non-empty 'response' string (both halves required for self-contained testimony).",
         });
     }
+    validateOptionalSource(block.source, issues);
     return issues;
 }
+function validateOptionalSource(source, issues) {
+    if (source !== undefined && (typeof source !== "string" || source.trim() === "")) {
+        issues.push({
+            code: "invalid-source",
+            message: "authorizing 'source', when present, must be a non-empty string.",
+        });
+    }
+}
 function validateAuthorizedAction(block) {
     const issues = [];
     if (!block.promptRef || typeof block.promptRef !== "string" || block.promptRef.trim() === "") {

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

@@ -1,9 +1,11 @@
 import type { IntegrityAnchor } from "@kontourai/surface";
-import type { Candidate, CandidateSet, ClaimTarget, Extraction, RawSource, ReviewOutcome } from "./types.js";
+import type { Candidate, CandidateSet, ClaimTarget, Extraction, RawSource, ReviewAuthorizing, ReviewOutcome } from "./types.js";
 export declare const REVIEW_PROOF_SCHEMA = "survey.review-proof";
-export declare const REVIEW_PROOF_SCHEMA_VERSION = 1;
+export declare const REVIEW_PROOF_SCHEMA_VERSION = 2;
 export declare const REVIEW_PROOF_PACKAGE_NAME = "@kontourai/survey";
-export declare const REVIEW_PROOF_CONTRACT_VERSION = "1";
+export declare const REVIEW_PROOF_CONTRACT_VERSION = "2";
+declare const LEGACY_REVIEW_PROOF_SCHEMA_VERSION = 1;
+declare const LEGACY_REVIEW_PROOF_CONTRACT_VERSION = "1";
 export interface ReviewProofInput {
     rawSource: RawSource;
     extraction: Extraction;
@@ -15,13 +17,13 @@ export interface ReviewProofInput {
     observedAt?: string;
     metadata?: Record<string, unknown>;
 }
-export interface CanonicalReviewProofPayload {
+export interface CanonicalReviewProofPayloadV1 {
     schemaVersion: 1;
     proof: {
         schema: typeof REVIEW_PROOF_SCHEMA;
-        schemaVersion: typeof REVIEW_PROOF_SCHEMA_VERSION;
+        schemaVersion: typeof LEGACY_REVIEW_PROOF_SCHEMA_VERSION;
         packageName: typeof REVIEW_PROOF_PACKAGE_NAME;
-        packageVersion: typeof REVIEW_PROOF_CONTRACT_VERSION;
+        packageVersion: typeof LEGACY_REVIEW_PROOF_CONTRACT_VERSION;
         issuer: string;
         producer: string;
         issuedAt: string;
@@ -110,7 +112,38 @@ export interface CanonicalReviewProofPayload {
         eventMethod?: string;
     };
 }
-export declare function buildCanonicalReviewProofPayload(input: ReviewProofInput): CanonicalReviewProofPayload;
+type CanonicalReviewAuthorizing = (Extract<ReviewAuthorizing, {
+    kind: "explicit-statement";
+}> & {
+    authorityRef?: never;
+}) | (Extract<ReviewAuthorizing, {
+    kind: "exchange";
+}> & {
+    authorityRef?: never;
+}) | (Extract<ReviewAuthorizing, {
+    kind: "authorized-action";
+}> & {
+    source?: never;
+});
+export type CanonicalReviewProofPayloadV2 = Omit<CanonicalReviewProofPayloadV1, "schemaVersion" | "proof" | "reviewOutcome"> & {
+    schemaVersion: 2;
+    proof: Omit<CanonicalReviewProofPayloadV1["proof"], "schemaVersion" | "packageVersion"> & {
+        schemaVersion: typeof REVIEW_PROOF_SCHEMA_VERSION;
+        packageVersion: typeof REVIEW_PROOF_CONTRACT_VERSION;
+    };
+    reviewOutcome?: NonNullable<CanonicalReviewProofPayloadV1["reviewOutcome"]> & {
+        authorizing?: CanonicalReviewAuthorizing;
+    };
+};
+export type CanonicalReviewProofPayload = CanonicalReviewProofPayloadV1 | CanonicalReviewProofPayloadV2;
+export declare function buildCanonicalReviewProofPayload(input: ReviewProofInput): CanonicalReviewProofPayloadV2;
 export declare function canonicalReviewProofJson(payload: CanonicalReviewProofPayload): string;
 export declare function hashCanonicalReviewProofPayload(payload: CanonicalReviewProofPayload): string;
+/**
+ * Verifies the integrity hash of a persisted v1 or v2 canonical review proof.
+ * Envelope compatibility and v2 authorizing admissibility are checked before
+ * the expected hash is compared.
+ */
+export declare function verifyCanonicalReviewProofPayload(payload: unknown, expectedHash: string): boolean;
 export declare function buildReviewProofAnchor(input: ReviewProofInput): IntegrityAnchor;
+export {};

package/dist/src/review-proof.js

@@ -1,10 +1,13 @@
 import { createHash } from "node:crypto";
+import { validateAuthorizing } from "./review-authorizing.js";
 export const REVIEW_PROOF_SCHEMA = "survey.review-proof";
-export const REVIEW_PROOF_SCHEMA_VERSION = 1;
+export const REVIEW_PROOF_SCHEMA_VERSION = 2;
 export const REVIEW_PROOF_PACKAGE_NAME = "@kontourai/survey";
 // Version of the review proof contract emitted by this helper. This is intentionally
 // independent from the npm package release version because it participates in hashes.
-export const REVIEW_PROOF_CONTRACT_VERSION = "1";
+export const REVIEW_PROOF_CONTRACT_VERSION = "2";
+const LEGACY_REVIEW_PROOF_SCHEMA_VERSION = 1;
+const LEGACY_REVIEW_PROOF_CONTRACT_VERSION = "1";
 export function buildCanonicalReviewProofPayload(input) {
     assertCandidateConsistency(input);
     return {
@@ -78,6 +81,7 @@ export function buildCanonicalReviewProofPayload(input) {
                 reviewedAt: input.reviewOutcome.reviewedAt,
                 rationale: input.reviewOutcome.rationale,
                 evidenceIds: input.reviewOutcome.evidenceIds ? [...input.reviewOutcome.evidenceIds].sort() : undefined,
+                authorizing: copyCanonicalAuthorizing(input.reviewOutcome.authorizing),
             }
             : undefined,
         claim: {
@@ -111,6 +115,45 @@ export function buildCanonicalReviewProofPayload(input) {
         },
     };
 }
+function copyCanonicalAuthorizing(authorizing) {
+    if (authorizing === undefined)
+        return undefined;
+    const kind = authorizing.kind;
+    let snapshot;
+    switch (kind) {
+        case "explicit-statement":
+            snapshot = {
+                kind,
+                statement: authorizing.statement,
+                source: authorizing.source,
+            };
+            break;
+        case "exchange":
+            snapshot = {
+                kind,
+                prompt: authorizing.prompt,
+                response: authorizing.response,
+                source: authorizing.source,
+            };
+            break;
+        case "authorized-action":
+            snapshot = {
+                kind,
+                promptRef: authorizing.promptRef,
+                renderedPrompt: authorizing.renderedPrompt,
+                action: authorizing.action,
+                authorityRef: authorizing.authorityRef,
+            };
+            break;
+        default:
+            snapshot = { kind };
+    }
+    const issues = validateAuthorizing(snapshot);
+    if (issues.length > 0) {
+        throw new Error(`Canonical review proof has invalid authorizing: ${issues.map((issue) => issue.message).join(" ")}`);
+    }
+    return snapshot;
+}
 function assertCandidateConsistency(input) {
     if (input.extraction.sourceId !== input.rawSource.id) {
         throw new Error(`Review proof extraction sourceId "${input.extraction.sourceId}" does not match raw source id "${input.rawSource.id}".`);
@@ -143,6 +186,56 @@ export function canonicalReviewProofJson(payload) {
 export function hashCanonicalReviewProofPayload(payload) {
     return createHash("sha256").update(canonicalReviewProofJson(payload)).digest("hex");
 }
+/**
+ * Verifies the integrity hash of a persisted v1 or v2 canonical review proof.
+ * Envelope compatibility and v2 authorizing admissibility are checked before
+ * the expected hash is compared.
+ */
+export function verifyCanonicalReviewProofPayload(payload, expectedHash) {
+    try {
+        const snapshot = canonicalize(payload);
+        const canonicalJson = JSON.stringify(snapshot);
+        if (typeof canonicalJson !== "string" || !isRecord(snapshot) || !isRecord(snapshot.proof))
+            return false;
+        if (snapshot.proof.schema !== REVIEW_PROOF_SCHEMA)
+            return false;
+        if (snapshot.proof.packageName !== REVIEW_PROOF_PACKAGE_NAME)
+            return false;
+        const schemaVersion = snapshot.schemaVersion;
+        const proofSchemaVersion = snapshot.proof.schemaVersion;
+        const packageVersion = snapshot.proof.packageVersion;
+        const reviewOutcome = snapshot.reviewOutcome;
+        if (schemaVersion === LEGACY_REVIEW_PROOF_SCHEMA_VERSION) {
+            if (proofSchemaVersion !== LEGACY_REVIEW_PROOF_SCHEMA_VERSION
+                || packageVersion !== LEGACY_REVIEW_PROOF_CONTRACT_VERSION) {
+                return false;
+            }
+            if (isRecord(reviewOutcome) && Object.prototype.hasOwnProperty.call(reviewOutcome, "authorizing")) {
+                return false;
+            }
+        }
+        else if (schemaVersion === REVIEW_PROOF_SCHEMA_VERSION) {
+            if (proofSchemaVersion !== REVIEW_PROOF_SCHEMA_VERSION || packageVersion !== REVIEW_PROOF_CONTRACT_VERSION) {
+                return false;
+            }
+            if (reviewOutcome !== undefined && !isRecord(reviewOutcome))
+                return false;
+            if (isRecord(reviewOutcome)
+                && Object.prototype.hasOwnProperty.call(reviewOutcome, "authorizing")
+                && reviewOutcome.authorizing !== undefined
+                && validateAuthorizing(reviewOutcome.authorizing).length > 0) {
+                return false;
+            }
+        }
+        else {
+            return false;
+        }
+        return createHash("sha256").update(canonicalJson).digest("hex") === expectedHash;
+    }
+    catch {
+        return false;
+    }
+}
 export function buildReviewProofAnchor(input) {
     const payload = buildCanonicalReviewProofPayload(input);
     const hash = hashCanonicalReviewProofPayload(payload);

package/package.json

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