@colophon-claims/verify 0.0.0 → 0.2.0

package/dist/profile/claim-consistency.js

@@ -0,0 +1,91 @@
+import { BENCHMARKING_METHOD_IDS } from "@jinn-network/benchmarking-records";
+import { canonicalJsonBytes } from "@jinn-network/trust-core";
+import { refuse } from "./errors.js";
+import { buildClaimPackage } from "./claim.js";
+import { buildLocalVenueHonesty, localVenueLimitsForRun } from "./run-results.js";
+import { previewDisclosureSummaryLine } from "./preview-log.js";
+import { venueIsolationPostureForPolicy } from "./isolation.js";
+import { binaryInstrumentReportLimitations } from "./binary-qualification.js";
+/** Mirrors `benchmark-product/core/src/verification/claim-consistency.ts`'s own (unexported)
+ * copy of this exact string. Not imported from core: this package cannot take a package edge
+ * on core, and core already depends on this package. The two copies must stay byte-identical. */
+const PAIRED_ESTIMATE_LIMITATION = "This method estimates an effect; it does not gate one — no verdict, threshold, or selection was registered.";
+const equal = (left, right) => left.length === right.length && left.every((byte, index) => byte === right[index]);
+/** The path of the first field that actually differs, or `undefined` when the two values are
+ * equal — equal leaves must report NO difference, or the object branch returns on its first key
+ * and every mismatch names the first key in sorted order instead of the edited field. Mirrors
+ * `benchmark-product/core`'s own copy (`src/verification/claim-consistency.ts`). */
+function firstDifference(actual, expected, path = "claim") {
+    // Never hand `undefined` to canonicalJsonBytes: it is deliberately not a JSON value, and a
+    // field carried by one side alone is itself the first difference.
+    if (actual === undefined || expected === undefined)
+        return actual === expected ? undefined : path;
+    if (equal(canonicalJsonBytes(actual), canonicalJsonBytes(expected)))
+        return undefined;
+    if (actual === null || expected === null || typeof actual !== "object" || typeof expected !== "object" || Array.isArray(actual) !== Array.isArray(expected))
+        return path;
+    if (Array.isArray(actual) && Array.isArray(expected)) {
+        if (actual.length !== expected.length)
+            return path;
+        for (const [index, value] of actual.entries()) {
+            const nested = firstDifference(value, expected[index], `${path}.${index}`);
+            if (nested !== undefined)
+                return nested;
+        }
+        return path;
+    }
+    for (const key of [...new Set([...Object.keys(actual), ...Object.keys(expected)])].sort()) {
+        const nested = firstDifference(actual[key], expected[key], path === "claim" ? key : `${path}.${key}`);
+        if (nested !== undefined)
+            return nested;
+    }
+    return path;
+}
+export function assertClaimConsistency(input) {
+    const { claim, identities, runRecord, matrixRecord, reportRecord } = input;
+    if (identities.reportSha256 === undefined)
+        refuse("record-integrity", "claim-consistency", "verified Report identity is absent");
+    const plan = runRecord.analysisPlan?.find((entry) => entry.method === reportRecord.method.id && entry.version === reportRecord.method.version);
+    const verdictRule = plan?.parameters?.verdictRule;
+    const minVerdicts = runRecord.policy.evaluation.minVerdicts;
+    const distinctEvaluator = runRecord.policy.evaluation.distinctEvaluator;
+    if ((verdictRule !== "sole" && verdictRule !== "majority" && verdictRule !== "unanimous") || minVerdicts === undefined || distinctEvaluator === undefined)
+        refuse("record-integrity", "claim-consistency", "sealed Run carries no complete supported evaluation assurance primitives");
+    // Presence, not emptiness: an empty section belongs to the anchored closure's declared-but-absent
+    // bundle, and an omitted one to every unanchored bundle.
+    const anchors = input.anchors;
+    const expected = buildClaimPackage({ draftId: input.draftId, benchmarkSha256: identities.benchmarkSha256, runRecord, runSha256: identities.runSha256, matrixRecord, matrixSha256: identities.matrixSha256, reportRecord, reportSha256: identities.reportSha256, reportEnvelopeSha256: identities.reportEnvelopeSha256, venueHonesty: buildLocalVenueHonesty(matrixRecord.cells, runRecord, anchors ?? []), verificationCommandVerb: "bundle verify", assurance: { preset: input.assurancePreset, resolved: { independence: runRecord.policy.independence, minVerdicts, distinctEvaluator, verdictRule } }, ...(input.rehearsal === undefined ? {} : { previewDisclosure: input.rehearsal }), ...(anchors === undefined ? {} : { anchors }) });
+    if (!equal(canonicalJsonBytes(claim), canonicalJsonBytes(expected)))
+        refuse("record-integrity", "claim-consistency", `claim package ${firstDifference(claim, expected) ?? "claim"} is not the exact projection of verified facts`);
+    const rehearsalLine = input.rehearsal === undefined ? undefined : previewDisclosureSummaryLine(input.rehearsal);
+    const binaryLimitations = reportRecord.method.id === BENCHMARKING_METHOD_IDS.binaryInstrument
+        ? binaryInstrumentReportLimitations((plan?.parameters ?? {}))
+        : [];
+    // paired-majority-delta@1 carries the same PAIRED_ESTIMATE_LIMITATION as paired-delta@1
+    // (coordinator ruling, packet #2837) -- mirrors core's `verification/claim-consistency.ts`
+    // method-conditional exactly, so the portable rebuild agrees with what `report` sealed.
+    // Computed from `reportRecord.method.id` directly (like this file's own `binaryLimitations`)
+    // rather than threaded through `input.additionalLimitations`.
+    const pairedEstimateLimitation = reportRecord.method.id === BENCHMARKING_METHOD_IDS.pairedDelta
+        || reportRecord.method.id === BENCHMARKING_METHOD_IDS.pairedMajorityDelta
+        ? [PAIRED_ESTIMATE_LIMITATION]
+        : [];
+    const expectedLimitations = [
+        ...localVenueLimitsForRun(runRecord),
+        ...(input.additionalLimitations ?? []),
+        ...binaryLimitations,
+        ...pairedEstimateLimitation,
+        ...(rehearsalLine === undefined ? [] : [rehearsalLine]),
+    ];
+    const posture = venueIsolationPostureForPolicy(runRecord.policy.submissionBaseline?.isolationPolicy);
+    // The gate itself is UNCHANGED by the paired-estimate addition (still isolation posture,
+    // caller-supplied additionalLimitations, or the existing binary-instrument arm). Deliberately
+    // not widened to `|| pairedEstimateLimitation.length > 0` -- core left that gate unchanged so
+    // this addition is not responsible for surfacing an unrelated pre-existing gap. For flagship
+    // oci-container runs, `posture.inventory.length > 1` already activates the gate; folding the
+    // line into `expectedLimitations` is what makes expected match the sealed Report.
+    if ((posture.inventory.length > 1 || (input.additionalLimitations?.length ?? 0) > 0 || binaryLimitations.length > 0) && !equal(canonicalJsonBytes(reportRecord.limitations ?? []), canonicalJsonBytes(expectedLimitations)))
+        refuse("record-integrity", "claim-consistency", "Report limitations are not the exact disclosure derived from the sealed Run and rehearsal history");
+    if (rehearsalLine === undefined ? (reportRecord.limitations ?? []).some((line) => line.includes("disposable preview rehearsal(s)")) : !(reportRecord.limitations ?? []).includes(rehearsalLine))
+        refuse("record-integrity", "claim-consistency", "claim rehearsal and verified Report disclosure disagree");
+}

package/dist/profile/claim.d.ts

@@ -0,0 +1,327 @@
+/**
+ * The claim package (BP-13 deliverable 2, spec §8.2): a pure builder + a zod schema + a writer
+ * for the standalone, portable document a skeptic reads to check a benchmark result without
+ * re-running anything.
+ *
+ * `buildClaimPackage` is PURE — no filesystem, no digest recomputation, no re-derivation of the
+ * sealed Report's own judgment. Every headline-or-comparison number, disclosure, limitation, and
+ * attrition figure is EXTRACTED verbatim from the records the caller already sealed and verified
+ * elsewhere (`../operations/report.ts`), never recomputed here — a claim package that silently
+ * disagreed with its own cited report would be worse than one that failed to build. Nothing is
+ * dropped: `conflicted`, `completeness`, and `attrition` are always present, even when they carry
+ * unwelcome numbers (a conflicted cell, an incomplete run) — spec §8.2's whole point is that the
+ * claim package cannot be more flattering than the sealed records it cites.
+ *
+ * P4b Task 5: `buildClaimPackage` DISPATCHES on the produced Report's `method.id` — wilson@1's
+ * per-arm `headline` and paired-delta@1's `comparison` are mutually exclusive siblings, exactly
+ * one of which is present on any given claim (the schema refuses a claim carrying neither). Same
+ * "extracted, never recomputed" posture regardless of which method produced the Report.
+ *
+ * BP-20 (spec §7.2): the optional `rehearsal` block names any disclosed preview that preceded
+ * this run's lock, verbatim from the caller's `previewDisclosure` input — used previews are named
+ * in the official record; its absence means no preview preceded lock. Same "extracted, never
+ * recomputed" posture as everything else this builder emits.
+ *
+ * BP-21 (spec §6): the required `assurance` block states the draft's preset (a product-policy
+ * label) AND the platform primitives it resolved to, plus the fixed agent-distinctness
+ * disclosure. The one deliberate exception to "never cross-check here": `buildClaimPackage`
+ * THROWS when the stated primitives disagree with what the sealed Run record's own policy
+ * carries — a claim stating primitives the sealed Run does not carry would be dishonest.
+ */
+import { z } from "zod";
+import type { MatrixRecord, ReportRecord, RunRecord } from "@jinn-network/benchmarking-records";
+import { SELF_RUN_TRUST_ROOT } from "./anchor-claims.js";
+import type { ClaimAnchor } from "./anchor-claims.js";
+type VenueHonesty = unknown;
+export declare const CLAIM_PACKAGE_SCHEMA_ID = "benchmark-product.claim-package/1";
+export declare const BINARY_QUALIFICATION_CLAIM_PACKAGE_SCHEMA_ID = "benchmark-product.claim-package/2";
+/**
+ * The anchored claim package (anchor-evidence design §7.4): claim-package/1 plus the `anchors`
+ * section, carried by `benchmark-product-public-bundle/6`. The allocation is the next free number
+ * in the classic path; the evidence-native claim-package/3 adopts the same anchor surface in its
+ * own later allocation.
+ */
+export declare const ANCHORED_CLAIM_PACKAGE_SCHEMA_ID = "benchmark-product.claim-package/4";
+export declare const BINARY_QUALIFICATION_VERIFICATION_COMMAND: "npx @colophon-claims/verify@0.1.0 <bundle-dir>";
+export declare const BINARY_QUALIFICATION_COMPATIBLE_VERIFICATION_COMMAND: "npx @colophon-claims/verify@0.1 <bundle-dir>";
+/** Prompted-screening v2 claims require the verifier release that carries that admission surface. */
+export declare const PROMPTED_BINARY_QUALIFICATION_VERIFICATION_COMMAND: "npx @colophon-claims/verify@0.2.0 <bundle-dir>";
+export declare const PROMPTED_BINARY_QUALIFICATION_COMPATIBLE_VERIFICATION_COMMAND: "npx @colophon-claims/verify@0.2 <bundle-dir>";
+/** The fixed sentence every claim package's assurance block carries (BP-21, spec §6/§7.1): what
+ * distinct evaluator identities on this venue actually prove. Never softened per-claim. */
+export declare const ASSURANCE_DISCLOSURE: string;
+export declare const ClaimPackageSchema: z.ZodPreprocess<z.ZodObject<{
+    claimSchema: z.ZodUnion<readonly [z.ZodLiteral<"benchmark-product.claim-package/1">, z.ZodLiteral<"benchmark-product.claim-package/2">, z.ZodLiteral<"benchmark-product.claim-package/4">]>;
+    scope: z.ZodObject<{
+        draftId: z.ZodString;
+        benchmarkSha256: z.ZodString;
+        taskCount: z.ZodNumber;
+        arms: z.ZodArray<z.ZodObject<{
+            armId: z.ZodString;
+            pinning: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
+        replicates: z.ZodNumber;
+        venue: z.ZodLiteral<"self-run">;
+    }, z.core.$strip>;
+    records: z.ZodObject<{
+        benchmarkSha256: z.ZodString;
+        runSha256: z.ZodString;
+        matrixSha256: z.ZodString;
+        reportSha256: z.ZodString;
+        reportEnvelopeSha256: z.ZodString;
+    }, z.core.$strip>;
+    method: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+        parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        preregistered: z.ZodBoolean;
+    }, z.core.$strip>;
+    results: z.ZodUnknown;
+    headline: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        n: z.ZodNumber;
+        passRate: z.ZodString;
+        wilsonInterval: z.ZodObject<{
+            low: z.ZodString;
+            high: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    completeness: z.ZodUnknown;
+    attrition: z.ZodUnknown;
+    conflicted: z.ZodObject<{
+        count: z.ZodNumber;
+        cellKeys: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    assurance: z.ZodObject<{
+        preset: z.ZodString;
+        resolved: z.ZodObject<{
+            independence: z.ZodEnum<{
+                gating: "gating";
+                disclosed: "disclosed";
+            }>;
+            minVerdicts: z.ZodNumber;
+            distinctEvaluator: z.ZodBoolean;
+            verdictRule: z.ZodEnum<{
+                sole: "sole";
+                majority: "majority";
+                unanimous: "unanimous";
+            }>;
+        }, z.core.$strip>;
+        disclosure: z.ZodString;
+    }, z.core.$strip>;
+    disclosures: z.ZodObject<{
+        perSubject: z.ZodArray<z.ZodUnknown>;
+        integrityTierCounts: z.ZodObject<{
+            "re-derivable": z.ZodNumber;
+            "attested-only": z.ZodNumber;
+        }, z.core.$strip>;
+        pinningUnverifiableCounts: z.ZodObject<{
+            harness: z.ZodNumber;
+            model: z.ZodNumber;
+            loadout: z.ZodNumber;
+            isolation: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    limitations: z.ZodArray<z.ZodString>;
+    venueHonesty: z.ZodUnknown;
+    verification: z.ZodObject<{
+        command: z.ZodString;
+        compatibleCommand: z.ZodString;
+        checks: z.ZodArray<z.ZodString>;
+        trustRoot: z.ZodString;
+    }, z.core.$strip>;
+    rehearsal: z.ZodOptional<z.ZodObject<{
+        previewCount: z.ZodNumber;
+        timestamps: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    comparison: z.ZodOptional<z.ZodObject<{
+        pairs: z.ZodNumber;
+        delta: z.ZodNullable<z.ZodString>;
+        interval: z.ZodNullable<z.ZodObject<{
+            alpha: z.ZodString;
+            low: z.ZodString;
+            high: z.ZodString;
+        }, z.core.$strip>>;
+        reasons: z.ZodArray<z.ZodString>;
+        pairing: z.ZodObject<{
+            taskDigests: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        clustering: z.ZodObject<{
+            basis: z.ZodString;
+            clusters: z.ZodNumber;
+        }, z.core.$strip>;
+        excluded: z.ZodObject<{
+            count: z.ZodNumber;
+            cellKeys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        conflicted: z.ZodObject<{
+            count: z.ZodNumber;
+            cellKeys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        bootstrap: z.ZodUnknown;
+    }, z.core.$strip>>;
+    pairwiseDisagreement: z.ZodOptional<z.ZodObject<{
+        pairs: z.ZodArray<z.ZodObject<{
+            n: z.ZodNumber;
+            disagreements: z.ZodNumber;
+            rate: z.ZodNullable<z.ZodString>;
+            interval: z.ZodNullable<z.ZodObject<{
+                lower: z.ZodString;
+                upper: z.ZodString;
+                alpha: z.ZodString;
+            }, z.core.$strip>>;
+            armA: z.ZodString;
+            armB: z.ZodString;
+            byCandidateClass: z.ZodArray<z.ZodObject<{
+                n: z.ZodNumber;
+                disagreements: z.ZodNumber;
+                rate: z.ZodNullable<z.ZodString>;
+                interval: z.ZodNullable<z.ZodObject<{
+                    lower: z.ZodString;
+                    upper: z.ZodString;
+                    alpha: z.ZodString;
+                }, z.core.$strip>>;
+                candidateClass: z.ZodString;
+            }, z.core.$strip>>;
+            byStratum: z.ZodArray<z.ZodObject<{
+                n: z.ZodNumber;
+                disagreements: z.ZodNumber;
+                rate: z.ZodNullable<z.ZodString>;
+                interval: z.ZodNullable<z.ZodObject<{
+                    lower: z.ZodString;
+                    upper: z.ZodString;
+                    alpha: z.ZodString;
+                }, z.core.$strip>>;
+                stratum: z.ZodString;
+            }, z.core.$strip>>;
+            exclusions: z.ZodArray<z.ZodObject<{
+                taskDigest: z.ZodString;
+                armId: z.ZodString;
+                reason: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        conflicted: z.ZodObject<{
+            count: z.ZodNumber;
+            cellKeys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    pairedMajorityDelta: z.ZodOptional<z.ZodObject<{
+        n: z.ZodNumber;
+        delta: z.ZodNullable<z.ZodString>;
+        interval: z.ZodNullable<z.ZodObject<{
+            lower: z.ZodString;
+            upper: z.ZodString;
+            alpha: z.ZodString;
+        }, z.core.$strip>>;
+        reasons: z.ZodArray<z.ZodString>;
+        baseline: z.ZodString;
+        candidate: z.ZodString;
+        clusters: z.ZodObject<{
+            count: z.ZodNumber;
+            manifest: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>;
+        byCandidateClass: z.ZodArray<z.ZodObject<{
+            n: z.ZodNumber;
+            delta: z.ZodNullable<z.ZodString>;
+            interval: z.ZodNullable<z.ZodObject<{
+                lower: z.ZodString;
+                upper: z.ZodString;
+                alpha: z.ZodString;
+            }, z.core.$strip>>;
+            reasons: z.ZodArray<z.ZodString>;
+            candidateClass: z.ZodString;
+        }, z.core.$strip>>;
+        byStratum: z.ZodArray<z.ZodObject<{
+            n: z.ZodNumber;
+            delta: z.ZodNullable<z.ZodString>;
+            interval: z.ZodNullable<z.ZodObject<{
+                lower: z.ZodString;
+                upper: z.ZodString;
+                alpha: z.ZodString;
+            }, z.core.$strip>>;
+            reasons: z.ZodArray<z.ZodString>;
+            stratum: z.ZodString;
+        }, z.core.$strip>>;
+        exclusions: z.ZodArray<z.ZodObject<{
+            taskDigest: z.ZodString;
+            armId: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>>;
+        conflicted: z.ZodObject<{
+            count: z.ZodNumber;
+            cellKeys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    qualification: z.ZodOptional<z.ZodUnknown>;
+    anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        subject: z.ZodEnum<{
+            lock: "lock";
+            matrix: "matrix";
+        }>;
+        kind: z.ZodString;
+        provider: z.ZodString;
+        recordSha256: z.ZodString;
+        upgradesRecordSha256: z.ZodOptional<z.ZodString>;
+        facts: z.ZodUnion<readonly [z.ZodObject<{
+            genTime: z.ZodString;
+            policyOid: z.ZodString;
+            serialNumber: z.ZodString;
+            signerCertificateSha256: z.ZodString;
+        }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+            blockHeight: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            pending: z.ZodLiteral<true>;
+        }, z.core.$strict>]>]>;
+    }, z.core.$strict>>>;
+}, z.core.$strip>>;
+export type ClaimPackage = z.infer<typeof ClaimPackageSchema>;
+export interface BuildClaimPackageInput {
+    readonly draftId: string;
+    readonly benchmarkSha256: string;
+    readonly runRecord: RunRecord;
+    readonly runSha256: string;
+    readonly matrixRecord: MatrixRecord;
+    readonly matrixSha256: string;
+    readonly reportRecord: ReportRecord;
+    readonly reportSha256: string;
+    readonly reportEnvelopeSha256: string;
+    readonly venueHonesty: VenueHonesty;
+    /** Retained for structural parity; reader instructions come from the canonical projection. */
+    readonly verificationCommandVerb: string;
+    /** BP-21 (spec §6): the draft's assurance preset (a product-policy label) and the platform
+     * primitives it resolved to. `buildClaimPackage` cross-checks the primitives against what the
+     * sealed Run record itself carries and THROWS on any disagreement — a claim that states
+     * primitives the sealed Run does not carry would be dishonest. */
+    readonly assurance: {
+        readonly preset: string;
+        readonly resolved: {
+            readonly independence: "gating" | "disclosed";
+            readonly minVerdicts: number;
+            readonly distinctEvaluator: boolean;
+            readonly verdictRule: "sole" | "majority" | "unanimous";
+        };
+    };
+    /** BP-20 (spec §7.2): when present, this draft had at least one disclosed preview before this
+     * run's lock — `buildClaimPackage` carries it into the `rehearsal` block verbatim. Absent means
+     * the caller found no preview log entry, i.e. no preview preceded lock. */
+    readonly previewDisclosure?: {
+        readonly previewCount: number;
+        readonly timestamps: readonly string[];
+    };
+    /** anchor-evidence §7.4: the anchors section, already derived from the carried AnchorEvidence
+     * bytes by `deriveClaimAnchors`. **Supplying it at all** — even empty — makes this an anchored
+     * claim (claim-package/4); omitting it leaves every existing claim byte-identical. Never derived
+     * here: this builder is pure, and the derivation needs the record bytes the caller already
+     * authenticated. */
+    readonly anchors?: readonly ClaimAnchor[];
+}
+export declare const CLAIM_VERIFICATION_CHECKS: readonly string[];
+/** The anchored closure's list: the six frozen checks plus `integrity-anchors` (§8). */
+export declare const ANCHORED_CLAIM_VERIFICATION_CHECKS: readonly string[];
+export declare const PUBLIC_BUNDLE_VERIFICATION_COMMAND: "npx @colophon-claims/verify@0.1.0 <bundle-dir>";
+/** The unconditional trust-root sentence, re-exported unchanged. It is DEFINED once beside its
+ * anchored replacement in `anchor-claims.ts`: one sentence written out twice, in two mirrored
+ * files, is exactly the drift the conditional copy cannot afford. */
+export { SELF_RUN_TRUST_ROOT };
+/** Builds the claim package document (spec §8.2) from explicit, already-sealed record data. Pure
+ * — no filesystem access, no recomputation of anything the cited records already settled. */
+export declare function buildClaimPackage(input: BuildClaimPackageInput): ClaimPackage;