@colophon-claims/verify 0.0.0 → 0.1.0

package/dist/admission/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./application.js";
+export * from "./contracts.js";
+export * from "./intake.js";
+export * from "./screening-sample.js";
+export * from "./verification.js";

package/dist/admission/index.js

@@ -0,0 +1,5 @@
+export * from "./application.js";
+export * from "./contracts.js";
+export * from "./intake.js";
+export * from "./screening-sample.js";
+export * from "./verification.js";

package/dist/admission/intake.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+export declare const BINARY_ITEM_BANK_ENTRY_PROTOCOL: "https://spec.jinn.network/binary-judgment/item-bank-entry/v1";
+export declare const BINARY_SOURCE_MANIFEST_ENTRY_PROTOCOL: "https://spec.jinn.network/binary-judgment/source-manifest-entry/v1";
+export declare const BINARY_ADMISSION_INDEX_ENTRY_PROTOCOL: "https://spec.jinn.network/binary-judgment/admission-index-entry/v1";
+export declare const BINARY_ITEM_BANK_INTAKE_EXTENSION: "https://product.jinn.network/extensions/binary-judgment-intake/v1";
+export declare const BinaryItemBankEntrySchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"https://spec.jinn.network/binary-judgment/item-bank-entry/v1">;
+    item: z.ZodObject<{
+        itemId: z.ZodString;
+        question: z.ZodString;
+        referenceAnswer: z.ZodString;
+        candidateAnswer: z.ZodString;
+        evidence: z.ZodOptional<z.ZodString>;
+        provenance: z.ZodObject<{
+            sourceCommitment: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+            timestamp: z.ZodString;
+        }, z.core.$strict>;
+        sources: z.ZodArray<z.ZodObject<{
+            digest: z.ZodObject<{
+                sha256: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type BinaryItemBankEntry = z.infer<typeof BinaryItemBankEntrySchema>;
+export declare const BinarySourceManifestEntrySchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"https://spec.jinn.network/binary-judgment/source-manifest-entry/v1">;
+    provenanceSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    source: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        uri: z.ZodString;
+        digest: z.ZodObject<{
+            sha256: z.ZodString;
+        }, z.core.$strict>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        downloadLocation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    license: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        uri: z.ZodString;
+        digest: z.ZodObject<{
+            sha256: z.ZodString;
+        }, z.core.$strict>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        downloadLocation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    attribution: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        uri: z.ZodString;
+        digest: z.ZodObject<{
+            sha256: z.ZodString;
+        }, z.core.$strict>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        downloadLocation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    publishedAt: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+}, z.core.$strict>;
+export type BinarySourceManifestEntry = z.infer<typeof BinarySourceManifestEntrySchema>;
+export declare const BinaryAdmissionIndexEntrySchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"https://spec.jinn.network/binary-judgment/admission-index-entry/v1">;
+    admissionManifestSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    itemSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    labelResolutionSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    analysisContextSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+}, z.core.$strict>;
+export type BinaryAdmissionIndexEntry = z.infer<typeof BinaryAdmissionIndexEntrySchema>;
+export declare const BinaryItemBankIntakeExtensionSchema: z.ZodObject<{
+    profile: z.ZodLiteral<"https://spec.jinn.network/task-profiles/binary-judgment/2.0">;
+    itemBankSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    sourceManifestSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    admissionIndexSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    admissionManifestSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+    replacementLedgerSha256: z.ZodPipe<z.ZodString, z.ZodTransform<`sha256:${string}`, string>>;
+}, z.core.$strict>;
+export type BinaryItemBankIntakeExtension = z.infer<typeof BinaryItemBankIntakeExtensionSchema>;

package/dist/admission/intake.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
+import { isCalendarStrictRfc3339 } from "@jinn-network/benchmarking-records";
+import { BINARY_JUDGMENT_TIMESTAMP_PATTERN } from "@jinn-network/task-execution-profiles";
+export const BINARY_ITEM_BANK_ENTRY_PROTOCOL = "https://spec.jinn.network/binary-judgment/item-bank-entry/v1";
+export const BINARY_SOURCE_MANIFEST_ENTRY_PROTOCOL = "https://spec.jinn.network/binary-judgment/source-manifest-entry/v1";
+export const BINARY_ADMISSION_INDEX_ENTRY_PROTOCOL = "https://spec.jinn.network/binary-judgment/admission-index-entry/v1";
+export const BINARY_ITEM_BANK_INTAKE_EXTENSION = "https://product.jinn.network/extensions/binary-judgment-intake/v1";
+const DigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/u).transform((value) => value);
+const Sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/u);
+/**
+ * RFC 3339 instant SHAPE, seconds precision, no fractional part. The pattern itself is imported
+ * from the profiles package rather than restated, so the payload contract and this manifest row
+ * cannot drift apart. Shape only: calendar strictness is the `publishedAt` refinement below.
+ */
+const BinaryJudgmentTimestampShapeSchema = z.string().regex(new RegExp(BINARY_JUDGMENT_TIMESTAMP_PATTERN, "u"));
+const ItemPayloadSchema = z.strictObject({
+    itemId: z.string().regex(/^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u),
+    question: z.string(),
+    referenceAnswer: z.string(),
+    candidateAnswer: z.string(),
+    evidence: z.string().optional(),
+    provenance: z.strictObject({
+        sourceCommitment: DigestSchema,
+        timestamp: BinaryJudgmentTimestampShapeSchema,
+    }),
+    sources: z.array(z.strictObject({ digest: z.strictObject({ sha256: Sha256HexSchema }) })).min(1),
+});
+const SourceDescriptorSchema = z.strictObject({
+    name: z.string().min(1).optional(),
+    uri: z.string().min(1),
+    digest: z.strictObject({ sha256: Sha256HexSchema }),
+    mediaType: z.string().min(1).optional(),
+    downloadLocation: z.string().min(1).optional(),
+});
+export const BinaryItemBankEntrySchema = z.strictObject({
+    protocol: z.literal(BINARY_ITEM_BANK_ENTRY_PROTOCOL),
+    item: ItemPayloadSchema,
+});
+export const BinarySourceManifestEntrySchema = z.strictObject({
+    protocol: z.literal(BINARY_SOURCE_MANIFEST_ENTRY_PROTOCOL),
+    provenanceSha256: DigestSchema,
+    source: SourceDescriptorSchema,
+    license: SourceDescriptorSchema,
+    attribution: SourceDescriptorSchema,
+    // The source publication instant lives on the source row, not the item: two items drawn from
+    // one source then structurally carry the same cluster key (provenanceSha256) and the same
+    // publishedAt, instead of a rule someone has to check by hand. A per-item timestamp would let a
+    // bank author encode an ordering that correlates with the label.
+    publishedAt: BinaryJudgmentTimestampShapeSchema.refine(isCalendarStrictRfc3339, "publishedAt must be a calendar-strict RFC 3339 instant at seconds precision"),
+}).superRefine((entry, ctx) => {
+    if (`sha256:${entry.source.digest.sha256}` !== entry.provenanceSha256) {
+        ctx.addIssue({ code: "custom", path: ["source", "digest", "sha256"], message: "source digest must equal provenanceSha256" });
+    }
+});
+export const BinaryAdmissionIndexEntrySchema = z.strictObject({
+    protocol: z.literal(BINARY_ADMISSION_INDEX_ENTRY_PROTOCOL),
+    admissionManifestSha256: DigestSchema,
+    itemSha256: DigestSchema,
+    labelResolutionSha256: DigestSchema,
+    analysisContextSha256: DigestSchema,
+});
+export const BinaryItemBankIntakeExtensionSchema = z.strictObject({
+    profile: z.literal("https://spec.jinn.network/task-profiles/binary-judgment/2.0"),
+    itemBankSha256: DigestSchema,
+    sourceManifestSha256: DigestSchema,
+    admissionIndexSha256: DigestSchema,
+    admissionManifestSha256: DigestSchema,
+    replacementLedgerSha256: DigestSchema,
+});

package/dist/admission/result-evaluation.d.ts

@@ -0,0 +1,18 @@
+export interface AdmissionVerdictStatementView {
+    readonly evaluatorId: string;
+    readonly verdict: "pass" | "fail" | "inconclusive";
+    readonly evaluationSpecificationSha256: string;
+    readonly measurements: Readonly<Record<string, boolean | number | string>>;
+    readonly evaluatedAt: string;
+    readonly evidence?: readonly {
+        readonly name: string;
+        readonly sha256: string;
+        readonly mediaType?: string;
+    }[];
+    readonly limitations?: readonly string[];
+}
+export declare function readAdmissionVerdictEnvelope(envelopeBytes: Uint8Array): AdmissionVerdictStatementView;
+export declare function readOrderedAdmissionVerdictMeasurements(envelopeBytes: Uint8Array): readonly {
+    readonly name: string;
+    readonly value: boolean | number | string;
+}[];

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,89 @@
+import { 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"];
+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 iff `manifest.truthAdmission === "screened-operator-sampled"` (spec §6.5 check (3)). */
+    readonly screening?: {
+        readonly sampleAgreementRate: number;
+        readonly instrumentSha256: AdmissionSha256;
+    };
+}
+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;