@colophon-claims/verify 0.0.0 → 0.2.0

package/dist/admission/result-evaluation.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
+import { VERDICT_DSSE_PAYLOAD_TYPE } from "@jinn-network/task-execution-profiles";
+import { parseExactDsseEnvelope } from "@jinn-network/trust-core";
+const MeasurementValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+const VerdictStatementSchema = z.looseObject({
+    predicateType: z.string().min(1),
+    predicate: z.looseObject({
+        evaluator: z.looseObject({ id: z.string().min(1) }),
+        verdict: z.enum(["pass", "fail", "inconclusive"]),
+        evaluationSpecification: z.looseObject({
+            digest: z.looseObject({ sha256: z.string().regex(/^[a-f0-9]{64}$/u) }),
+        }),
+        evaluationMethod: z.looseObject({
+            name: z.string().min(1),
+            digest: z.looseObject({ sha256: z.string().regex(/^[a-f0-9]{64}$/u) }),
+        }).optional(),
+        measurements: z.array(z.looseObject({ name: z.string().min(1), value: MeasurementValueSchema })).optional(),
+        evidence: z.array(z.looseObject({
+            name: z.string().min(1),
+            digest: z.looseObject({ sha256: z.string().regex(/^[a-f0-9]{64}$/u) }),
+            mediaType: z.string().optional(),
+        })).optional(),
+        evaluatedAt: z.string().min(1),
+        limitations: z.array(z.string()).optional(),
+    }),
+});
+function statement(envelopeBytes) {
+    const envelope = parseExactDsseEnvelope(envelopeBytes);
+    if (envelope.payloadType !== VERDICT_DSSE_PAYLOAD_TYPE)
+        throw new Error("wrong Result Evaluation payload type");
+    let json;
+    try {
+        json = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(envelope.payloadBytes));
+    }
+    catch {
+        throw new Error("Result Evaluation payload is not UTF-8 JSON");
+    }
+    const parsed = VerdictStatementSchema.safeParse(json);
+    if (!parsed.success)
+        throw new Error("Result Evaluation payload is outside the closed view");
+    return parsed.data;
+}
+export function readAdmissionVerdictEnvelope(envelopeBytes) {
+    const { predicate } = statement(envelopeBytes);
+    const measurements = {};
+    for (const measurement of predicate.measurements ?? [])
+        measurements[measurement.name] = measurement.value;
+    return {
+        evaluatorId: predicate.evaluator.id,
+        verdict: predicate.verdict,
+        evaluationSpecificationSha256: predicate.evaluationSpecification.digest.sha256,
+        measurements,
+        evaluatedAt: predicate.evaluatedAt,
+        ...(predicate.evidence === undefined ? {} : {
+            evidence: predicate.evidence.map((entry) => ({
+                name: entry.name,
+                sha256: entry.digest.sha256,
+                ...(entry.mediaType === undefined ? {} : { mediaType: entry.mediaType }),
+            })),
+        }),
+        ...(predicate.limitations === undefined ? {} : { limitations: predicate.limitations }),
+    };
+}
+export function readOrderedAdmissionVerdictMeasurements(envelopeBytes) {
+    const measurements = statement(envelopeBytes).predicate.measurements ?? [];
+    if (new Set(measurements.map((measurement) => measurement.name)).size !== measurements.length) {
+        throw new Error("Result Evaluation carries duplicate measurement names");
+    }
+    return measurements.map((measurement) => ({ name: measurement.name, value: measurement.value }));
+}

package/dist/admission/screening-sample.d.ts

@@ -0,0 +1,56 @@
+export declare class ScreeningSampleError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+export interface ScreeningSampleParams {
+    /** The table's `itemSha256` values -- the row identity set. Order is irrelevant; see R-4. */
+    readonly itemSha256s: readonly string[];
+    /** Non-empty seed string. Enters the HMAC key as literal UTF-8 text, concatenated with `poolDigest`. */
+    readonly sampleSeed: string;
+    /** Positive integer, `<= itemSha256s.length`. The sample is the first `sampleSize` of the full order. */
+    readonly sampleSize: number;
+}
+export interface ScreeningSampleResult {
+    /** `sha256:<64 lowercase hex>` -- the digest of the sorted, unique identity set alone. */
+    readonly poolDigest: string;
+    /** Every `itemSha256` in the pool, ascending by HMAC stream (unsigned byte order), ties by code-unit order. */
+    readonly order: readonly string[];
+    /** `order.slice(0, sampleSize)`. */
+    readonly sample: readonly string[];
+}
+/**
+ * One entry in the HMAC-stream ordering: the value actually compared (`stream`) paired with the
+ * tie-break key (`itemSha256`). Exported so the sort itself is directly testable -- a real
+ * HMAC-SHA256 collision cannot be constructed to exercise the tie-break in an end-to-end call.
+ */
+export interface ScreeningStreamEntry {
+    readonly itemSha256: string;
+    readonly stream: Uint8Array;
+}
+/**
+ * `stream` compared as 32 unsigned bytes ascending; ties broken by `itemSha256` code-unit order.
+ * `Uint8Array` indexing always yields an unsigned 0-255 number in JavaScript, so a direct numeric
+ * subtraction per element is already the unsigned comparison -- no bit-masking is needed, but it
+ * must not be replaced by a signed-view read (e.g. `Int8Array`) or by comparing a hex rendering.
+ */
+export declare function compareScreeningStreamEntries(left: ScreeningStreamEntry, right: ScreeningStreamEntry): number;
+/**
+ * `sha256:` followed by the 64 lowercase hex digits of the SHA-256 of the canonical-JSON bytes of
+ * `itemSha256s`, code-unit sorted AND deduplicated, so the digest depends on the identity SET and
+ * not on input order or on repetition. §6.5 says "sorted and unique" and this function is the one
+ * that has to mean it: `computeScreeningSample` refuses duplicates before it ever calls here, so
+ * the dedupe is a no-op on every in-repo path and moves no digest, but this is exported precisely
+ * so a cross-language implementer can check `poolDigest` in ISOLATION, and in isolation "sorted"
+ * alone would have silently accepted a duplicated identity and produced a digest no other
+ * implementation reproduces. Otherwise does not validate its input; `computeScreeningSample`
+ * owns that.
+ */
+export declare function computeScreeningPoolDigest(itemSha256s: readonly string[]): string;
+/**
+ * Procedure `screening-sample/1` (§6.5). Refuses (throws `ScreeningSampleError`) when:
+ * - `itemSha256s` is empty, contains a duplicate, or contains an entry not matching
+ *   `^sha256:[0-9a-f]{64}$`;
+ * - `sampleSeed` is empty;
+ * - `sampleSize` is not a positive integer, or exceeds `itemSha256s.length`.
+ */
+export declare function computeScreeningSample(params: ScreeningSampleParams): ScreeningSampleResult;

package/dist/admission/screening-sample.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `screening-sample/1` -- the verifier's independent recomputation of binary-judgment human-review
+ * sample membership (judge-path program packet P6, spec
+ * `docs/superpowers/specs/2026-08-19-judge-path-delta-contracts.md` §6.5 "(1) Sample membership").
+ *
+ * The verifier does not execute the operator's sealed sampling script; it recomputes membership
+ * from this specified procedure instead, and the recomputation wins on disagreement. That only
+ * works if the procedure is reimplementable in any language from the spec paragraph alone (R-4), so
+ * every encoding choice below is spelled out rather than left to convention:
+ *
+ * - **`poolDigest` binds the row *identity* set, never the rows.** It is `sha256:` followed by the
+ *   64 lowercase hex digits of the SHA-256 of the canonical-JSON bytes of the `itemSha256` values
+ *   alone, code-unit sorted and unique -- not the rows themselves. Binding the rows is circular and
+ *   uncomputable: a row carries `handChecked`, which rows carry it depends on the sample, and the
+ *   sample depends on the digest. Binding the identity set breaks the cycle, because `itemSha256` is
+ *   exactly the part of a row hand-checking never touches.
+ * - **The key is text, not raw digest bytes.** The HMAC key is `utf8(sampleSeed || poolDigest)`,
+ *   where `poolDigest` enters in its `sha256:`-prefixed lowercase-hex string form -- the exact
+ *   64-hex-digit string, concatenated onto `sampleSeed`, then UTF-8 encoded. Keying on the digest's
+ *   32 raw bytes instead would introduce the only binary-versus-text distinction in an otherwise
+ *   all-text procedure, which is exactly the kind of thing a second implementer gets wrong.
+ * - **No delimiter separates `sampleSeed` and `poolDigest`.** `poolDigest` is a fixed 71-character
+ *   suffix (`sha256:` + 64 hex digits), so a delimiter would just be a second convention to get
+ *   wrong.
+ * - **The HMAC message is `utf8(itemSha256)`**, the same `sha256:`-prefixed lowercase-hex string
+ *   used everywhere else in the spec -- never raw digest bytes.
+ * - **Stream comparison is over 32 *unsigned* bytes.** `Uint8Array` elements are unsigned by
+ *   construction in JavaScript (0-255), so a plain per-element numeric comparison is correct; the
+ *   classic bug is reading the same bytes through a signed 8-bit view (where 0x80 becomes -128)
+ *   or via a hex-string shortcut that doesn't preserve this. Ties are broken by `itemSha256` in
+ *   code-unit order (never `localeCompare`, which is locale-dependent).
+ *
+ * This module does no filesystem or network I/O, throws `ScreeningSampleError` on any invalid
+ * input, and owns exactly its own input validity -- not the four other §6.5 checks (coverage,
+ * required hand checks, agreement rate, per-row admission), which read the recomputed sample but
+ * live elsewhere in this package.
+ */
+import { createHash, createHmac } from "node:crypto";
+import { canonicalJsonBytes, compareCodeUnitStrings } from "@jinn-network/task-execution-profiles";
+const SHA256_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+export class ScreeningSampleError extends Error {
+    path;
+    constructor(path, detail) {
+        super(`${path}: ${detail}`);
+        this.name = "ScreeningSampleError";
+        this.path = path;
+    }
+}
+function fail(path, detail) {
+    throw new ScreeningSampleError(path, detail);
+}
+/**
+ * `stream` compared as 32 unsigned bytes ascending; ties broken by `itemSha256` code-unit order.
+ * `Uint8Array` indexing always yields an unsigned 0-255 number in JavaScript, so a direct numeric
+ * subtraction per element is already the unsigned comparison -- no bit-masking is needed, but it
+ * must not be replaced by a signed-view read (e.g. `Int8Array`) or by comparing a hex rendering.
+ */
+export function compareScreeningStreamEntries(left, right) {
+    const length = Math.min(left.stream.length, right.stream.length);
+    for (let index = 0; index < length; index += 1) {
+        const delta = left.stream[index] - right.stream[index];
+        if (delta !== 0)
+            return delta;
+    }
+    if (left.stream.length !== right.stream.length)
+        return left.stream.length - right.stream.length;
+    return compareCodeUnitStrings(left.itemSha256, right.itemSha256);
+}
+/**
+ * `sha256:` followed by the 64 lowercase hex digits of the SHA-256 of the canonical-JSON bytes of
+ * `itemSha256s`, code-unit sorted AND deduplicated, so the digest depends on the identity SET and
+ * not on input order or on repetition. §6.5 says "sorted and unique" and this function is the one
+ * that has to mean it: `computeScreeningSample` refuses duplicates before it ever calls here, so
+ * the dedupe is a no-op on every in-repo path and moves no digest, but this is exported precisely
+ * so a cross-language implementer can check `poolDigest` in ISOLATION, and in isolation "sorted"
+ * alone would have silently accepted a duplicated identity and produced a digest no other
+ * implementation reproduces. Otherwise does not validate its input; `computeScreeningSample`
+ * owns that.
+ */
+export function computeScreeningPoolDigest(itemSha256s) {
+    const sorted = [...new Set(itemSha256s)].sort(compareCodeUnitStrings);
+    const bytes = canonicalJsonBytes(sorted);
+    const hex = createHash("sha256").update(bytes).digest("hex");
+    return `sha256:${hex}`;
+}
+/**
+ * Procedure `screening-sample/1` (§6.5). Refuses (throws `ScreeningSampleError`) when:
+ * - `itemSha256s` is empty, contains a duplicate, or contains an entry not matching
+ *   `^sha256:[0-9a-f]{64}$`;
+ * - `sampleSeed` is empty;
+ * - `sampleSize` is not a positive integer, or exceeds `itemSha256s.length`.
+ */
+export function computeScreeningSample(params) {
+    const { itemSha256s, sampleSeed, sampleSize } = params;
+    itemSha256s.forEach((itemSha256, index) => {
+        if (!SHA256_DIGEST_PATTERN.test(itemSha256)) {
+            fail(`itemSha256s[${index}]`, `must match ^sha256:[0-9a-f]{64}$, got ${JSON.stringify(itemSha256)}`);
+        }
+    });
+    if (itemSha256s.length === 0)
+        fail("itemSha256s", "identity set must be non-empty");
+    if (new Set(itemSha256s).size !== itemSha256s.length) {
+        fail("itemSha256s", "identity set must not contain duplicate itemSha256 values");
+    }
+    if (sampleSeed.length === 0)
+        fail("sampleSeed", "must be non-empty");
+    if (!Number.isInteger(sampleSize) || sampleSize <= 0) {
+        fail("sampleSize", `must be a positive integer, got ${JSON.stringify(sampleSize)}`);
+    }
+    if (sampleSize > itemSha256s.length) {
+        fail("sampleSize", `must not exceed the pool size (${itemSha256s.length}), got ${sampleSize}`);
+    }
+    const poolDigest = computeScreeningPoolDigest(itemSha256s);
+    const key = Buffer.from(`${sampleSeed}${poolDigest}`, "utf8");
+    const entries = itemSha256s.map((itemSha256) => ({
+        itemSha256,
+        stream: new Uint8Array(createHmac("sha256", key).update(Buffer.from(itemSha256, "utf8")).digest()),
+    }));
+    const order = [...entries].sort(compareScreeningStreamEntries).map((entry) => entry.itemSha256);
+    return {
+        poolDigest,
+        order,
+        sample: order.slice(0, sampleSize),
+    };
+}

package/dist/admission/verification.d.ts

@@ -0,0 +1,102 @@
+import { PROMPTED_SCREENING_PROFILE, type BinaryJudgmentAdmissionManifest, type HumanReviewReplacementLedger } from "./contracts.js";
+export type AdmissionSha256 = `sha256:${string}`;
+export declare const BINARY_JUDGMENT_ADMISSION_RECORD_ROLES: readonly ["admission-manifest", "replacement-ledger", "source-item", "label-resolution", "analysis-context", "human-review-evaluation-spec", "human-review-form", "human-review-packet", "human-review-response", "human-review-verdict", "reviewer-roster", "review-visibility-receipt", "review-reveal-receipt", "operator-assertion", "screening-table", "screening-reveal-receipt", "screening-instrument", "screening-sampling-script", "screening-raw-outputs", "screening-prompt", "screening-procedure", "screening-pool", "screening-sample-commitment", "screening-transcript"];
+export type BinaryJudgmentAdmissionRecordRole = (typeof BINARY_JUDGMENT_ADMISSION_RECORD_ROLES)[number];
+export type AdmissionAuthorityRole = "roster-attestor" | "truth-reveal-attestor" | "operator-truth-attestor";
+export interface BinaryJudgmentAdmissionClosurePorts {
+    /** Resolve immutable bytes by their prefixed digest. The verifier re-hashes every result. */
+    resolveExactRecord(digest: AdmissionSha256): Uint8Array;
+    /** Verify the one reviewer signature against the evaluator/key binding trusted by the caller. */
+    verifyReviewerSignature(input: {
+        readonly envelopeBytes: Uint8Array;
+        readonly evaluatorId: string;
+        readonly keyId: string;
+    }): boolean;
+    /** Verify the one product-authority signature under its payload-declared, separated role. */
+    verifyAuthoritySignature(input: {
+        readonly envelopeBytes: Uint8Array;
+        readonly keyId: string;
+        readonly role: AdmissionAuthorityRole;
+    }): boolean;
+}
+export interface VerifyBinaryJudgmentAdmissionClosureInput {
+    readonly admissionManifestSha256: AdmissionSha256;
+    readonly expectedDraftId: string;
+}
+export interface VerifiedBinaryJudgmentAdmissionItem {
+    readonly itemSha256: AdmissionSha256;
+    readonly itemId: string;
+    readonly truthLabel: "CORRECT" | "WRONG";
+    readonly candidateClass: string;
+    readonly stratum: string;
+    readonly truthAdmission: "two-human-unanimous" | "operator-only" | "screened-operator-sampled";
+    readonly labelResolutionSha256: AdmissionSha256;
+    readonly analysisContextSha256: AdmissionSha256;
+}
+export interface VerifiedBinaryJudgmentAdmissionExclusion {
+    readonly itemSha256: AdmissionSha256;
+    readonly itemId: string;
+    readonly candidateClass: string;
+    readonly stratum: string;
+    readonly reason: "review-disagreement" | "review-indeterminate" | "review-incomplete" | "screening-disagreement" | "screening-indeterminate" | "screening-hand-excluded";
+    readonly replacementItemSha256: AdmissionSha256;
+}
+export interface VerifiedBinaryJudgmentAdmissionClosure {
+    readonly manifestSha256: AdmissionSha256;
+    readonly manifest: BinaryJudgmentAdmissionManifest;
+    readonly replacementLedger: HumanReviewReplacementLedger;
+    readonly publicationGrade: boolean;
+    readonly classes: readonly string[];
+    readonly strata: readonly string[];
+    readonly accepted: readonly VerifiedBinaryJudgmentAdmissionItem[];
+    readonly excluded: readonly VerifiedBinaryJudgmentAdmissionExclusion[];
+    /** Complete, sorted digest inventory reachable from the manifest closure. */
+    readonly reachableSha256s: readonly AdmissionSha256[];
+    /** Same closure with semantic roles assigned by the exact traversal that authenticated it. */
+    readonly reachableRecords: readonly {
+        readonly sha256: AdmissionSha256;
+        readonly roles: readonly BinaryJudgmentAdmissionRecordRole[];
+    }[];
+    /** Present for the legacy screening-table/v1 method (spec §6.5 check (3)). */
+    readonly screening?: {
+        readonly sampleAgreementRate: number;
+        readonly instrumentSha256: AdmissionSha256;
+    };
+    /** Present for screening-table/v2; kept separate so the legacy v1 result shape stays source-compatible. */
+    readonly promptedScreening?: {
+        readonly sampleAgreementRate: number;
+        readonly procedureSha256: AdmissionSha256;
+        readonly profile: typeof PROMPTED_SCREENING_PROFILE;
+        readonly capabilityBoundary: PromptedScreeningCapabilityBoundary;
+    };
+}
+export declare const PROMPTED_SCREENING_CAPABILITY_BOUNDARY: {
+    readonly status: "not-machine-verified";
+    readonly machineVerified: readonly ["sealed-pool", "sealed-sample", "signed-table", "operator-decisions", "artifact-integrity"];
+    readonly notMachineVerified: readonly ["prompt-compliance-not-machine-verified", "provider-execution-not-machine-verified", "transcript-provenance-not-machine-verified", "mutable-model-alias-weights-not-machine-verified"];
+};
+export type PromptedScreeningCapabilityBoundary = typeof PROMPTED_SCREENING_CAPABILITY_BOUNDARY;
+export declare class BinaryJudgmentAdmissionClosureError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string, options?: ErrorOptions);
+}
+export interface VerifiedBinaryJudgmentReviewerResult {
+    readonly evaluatorId: string;
+    readonly keyId: string;
+    readonly label: "CORRECT" | "WRONG" | "indeterminate";
+    readonly complete: boolean;
+    readonly completedAt: string;
+    readonly itemId: string;
+    readonly packetSha256: AdmissionSha256;
+    readonly visibilityReceiptSha256: AdmissionSha256;
+}
+/** The reviewer Result Evaluation verifier shared by admission construction and closure replay. */
+export declare function verifyBinaryJudgmentReviewerResult(input: {
+    readonly verdictSha256: AdmissionSha256;
+    readonly expectedItemSha256: AdmissionSha256;
+}, ports: BinaryJudgmentAdmissionClosurePorts): VerifiedBinaryJudgmentReviewerResult;
+/**
+ * Portable, fail-closed replay of the entire binary-judgment admission graph. The caller supplies
+ * immutable record resolution and role-separated trust; no candidate truth is caller-authored.
+ */
+export declare function verifyBinaryJudgmentAdmissionClosure(input: VerifyBinaryJudgmentAdmissionClosureInput, ports: BinaryJudgmentAdmissionClosurePorts): VerifiedBinaryJudgmentAdmissionClosure;