@colophon-claims/verify 0.2.0 → 0.2.1

package/dist/binding/beacon-binding.js

@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `beacon-binding/1` -- binding a sealed run to public randomness that did not exist when it was
+ * sealed (issue #2976).
+ *
+ * Sealing proves a method document predates its publication. It cannot prove the *run* happened
+ * after the seal: a party could run privately, write a method describing what already happened,
+ * seal it, and re-run. `verify/src/profile/anchor-claims.ts` says as much in the sealed claim's own
+ * words -- a time anchor proves "the design's existence by that time and nothing else about the run
+ * -- in particular, not that results were produced after it".
+ *
+ * This procedure closes that gap by deriving a run property from a value that postdates the seal.
+ * Where a slate is drawn from a larger pool, the draw is a function of (seal digest, beacon value),
+ * so no post-hoc selection is possible: the operator would have had to predict the beacon. Where
+ * the slate is a whole census, there is no draw to bind, and the beacon binds only execution
+ * ORDER -- a strictly weaker property that this module names as such rather than dressing up.
+ *
+ * It is the deliberate sibling of `../admission/screening-sample.ts` (`screening-sample/1`) and
+ * reuses that procedure's encoding decisions verbatim, including its identity-set digest. The one
+ * substantive difference is the HMAC key: `screening-sample/1` keys on a SEALED seed, which is
+ * exactly the property #2976 says is insufficient, and this one keys on the seal digest together
+ * with a post-seal beacon value. Everything else is deliberately identical so a second implementer
+ * who has already built one has nothing new to get wrong.
+ *
+ * Every encoding choice, restated here so this paragraph alone is reimplementable in any language:
+ *
+ * - **The HMAC key is `utf8(sealDigest || beaconValue)`.** `sealDigest` enters in its
+ *   `sha256:`-prefixed lowercase-hex string form (a fixed 71 characters) and `beaconValue` as its
+ *   64 lowercase hex digits. Both are fixed-length, so -- as in `screening-sample/1` -- no
+ *   delimiter separates them; a delimiter would only be a second convention to get wrong. Never
+ *   raw digest bytes: the whole procedure is text.
+ * - **The HMAC message is `utf8(itemSha256)`**, the same `sha256:`-prefixed lowercase-hex form.
+ * - **The order is ascending over the 32 unsigned HMAC-SHA256 bytes**, ties broken by `itemSha256`
+ *   in code-unit order. This is `compareScreeningStreamEntries`, shared rather than re-derived.
+ * - **`poolDigest` binds the identity SET**: `sha256:` followed by the SHA-256 of the canonical-JSON
+ *   bytes of the `itemSha256` values, code-unit sorted and unique. This is
+ *   `computeScreeningPoolDigest`, shared for the same reason.
+ * - **The sample is the first `sampleSize` of that order.** In census mode there is no sample and
+ *   the order itself is the execution order.
+ *
+ * The beacon's postdating is checked, not assumed, and how strongly it can be checked depends on
+ * the source. A drand round number maps to a time by published chain parameters
+ * (`genesis + (round - 1) * period`), so "this value did not exist at seal time" is arithmetic any
+ * reader does offline. A Bitcoin height does not: block times need headers, so that check is
+ * attributive and this module says so instead of claiming an offline proof it cannot make.
+ *
+ * Postdating alone would still leave the operator a choice, and issue #3322 closes it: admitting any
+ * round later than the seal makes the VALUE unpredictable but not WHICH realized value applies, so
+ * an operator could watch the rounds published between lock and launch and bind the one whose
+ * derivation they preferred. For a scheduled source the seal already names one round --
+ * `requiredBeaconRound`, the first published strictly after it -- so the commitment needs no
+ * separate record, the producer refuses any other round, and `roundBasis` reports which of the two
+ * situations a record is in so the report face can say only what is true of it.
+ *
+ * This module does no filesystem or network I/O and throws `RunBindingError` on any invalid input.
+ */
+import { createHmac } from "node:crypto";
+import { z } from "zod";
+import { compareScreeningStreamEntries, computeScreeningPoolDigest, } from "../admission/screening-sample.js";
+/** The procedure identifier a binding record must carry. */
+export const BEACON_BINDING_PROCEDURE = "beacon-binding/1";
+/**
+ * The beacons this procedure admits. Values are the sources' own published chain parameters and
+ * are part of the derivation: a reader recomputing `beaconRoundInstant` needs exactly these
+ * numbers, so they live in the code rather than in a comment.
+ */
+export const BEACON_SOURCES = {
+    "drand/quicknet": {
+        timeBasis: "deterministic-round-time",
+        genesisTimeSeconds: 1692803367,
+        periodSeconds: 3,
+        displayName: "drand quicknet",
+    },
+    "drand/default": {
+        timeBasis: "deterministic-round-time",
+        genesisTimeSeconds: 1595431050,
+        periodSeconds: 30,
+        displayName: "drand default chain",
+    },
+    "bitcoin/mainnet": {
+        timeBasis: "attributive-height",
+        displayName: "Bitcoin mainnet",
+    },
+};
+export const BEACON_SOURCE_IDS = Object.keys(BEACON_SOURCES).sort();
+/**
+ * A schema-level sanity ceiling on a round index. Not a beacon limit, and deliberately not the
+ * representability guarantee either: the ceiling that matters is per-source, because it falls out
+ * of each source's own period, and one shared number cannot be sound for all of them. Quicknet's
+ * 3-second period puts round 1,000,000,000,000 some 95,000 years out and inside what `Date`
+ * represents; the default chain's 30-second period puts the same round ten times further out and
+ * outside it. So this bound only rejects the absurd, and `beaconRoundInstant` -- not the schema --
+ * owns the guarantee that the arithmetic stays representable. Every real Bitcoin height is eight
+ * orders of magnitude below this.
+ */
+export const MAX_BEACON_ROUND = 1_000_000_000_000;
+/**
+ * The widest instant `Date` represents, in milliseconds either side of the epoch (ECMA-262:
+ * 8.64e15). Beyond it `toISOString` throws an untyped `RangeError`, which is what
+ * `beaconRoundInstant` refuses on this module's own terms instead.
+ */
+const MAX_REPRESENTABLE_TIME_MS = 8_640_000_000_000_000;
+const HexValueSchema = z.string().regex(/^[0-9a-f]{64}$/, "must be 64 lowercase hex characters");
+const DigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/, "must match ^sha256:[0-9a-f]{64}$");
+const InstantSchema = z.string().datetime({ offset: true });
+/**
+ * A public beacon reference: which beacon, which round or height, and the value it published
+ * there. `round` is the source's own index -- a drand round number, a Bitcoin block height.
+ */
+export const BeaconReferenceSchema = z.strictObject({
+    source: z.enum(Object.keys(BEACON_SOURCES)),
+    round: z.number().int().positive().max(MAX_BEACON_ROUND),
+    value: HexValueSchema,
+});
+const CommonBindingFields = {
+    procedure: z.literal(BEACON_BINDING_PROCEDURE),
+    /** The digest of the sealed record this binding postdates -- the run's own seal. */
+    sealDigest: DigestSchema,
+    /** When that seal was taken. The beacon must postdate it. */
+    sealedAt: InstantSchema,
+    beacon: BeaconReferenceSchema,
+};
+/**
+ * The two shapes, disjoint by construction so no reader can mistake the weaker binding for the
+ * stronger one:
+ *
+ * - `sampled` -- a slate drawn from a larger pool. `sample` is the claim; the verifier recomputes
+ *   it and fails on mismatch.
+ * - `census` -- the whole declared population runs, so there is no draw. `order` is the claim, and
+ *   it binds execution order only.
+ */
+export const RunBindingSchema = z.discriminatedUnion("mode", [
+    z.strictObject({
+        ...CommonBindingFields,
+        mode: z.literal("sampled"),
+        /** The pool the slate was drawn from. Order is irrelevant; the identity set is what binds. */
+        poolItemSha256s: z.array(DigestSchema).min(1),
+        sampleSize: z.number().int().positive(),
+        /** The drawn slate, in derived order. */
+        sample: z.array(DigestSchema).min(1),
+    }),
+    z.strictObject({
+        ...CommonBindingFields,
+        mode: z.literal("census"),
+        /** The whole population. Order is irrelevant here; `order` below is the derived claim. */
+        itemSha256s: z.array(DigestSchema).min(1),
+        /** Every item, in beacon-derived execution order. */
+        order: z.array(DigestSchema).min(1),
+    }),
+]);
+export class RunBindingError extends Error {
+    name = "RunBindingError";
+    path;
+    constructor(path, detail) {
+        super(`${path}: ${detail}`);
+        this.path = path;
+    }
+}
+function fail(path, detail) {
+    throw new RunBindingError(path, detail);
+}
+/**
+ * The instant a `deterministic-round-time` beacon published `round`, as an RFC 3339 UTC string, or
+ * `undefined` for a source whose round index carries no offline time. The schedule is
+ * `genesis + (round - 1) * period`: round 1 is published at genesis.
+ *
+ * Refuses (throws `RunBindingError`) when that instant falls outside the range `Date` represents.
+ * The check lives here rather than on the schema because the largest representable round is a
+ * function of the source's own period -- the default chain runs out ten times earlier than
+ * quicknet does -- so a single schema ceiling would leave the slower source's tail passing
+ * validation and then throwing an untyped `RangeError` from `toISOString` deep inside
+ * verification. Guarding the arithmetic where the arithmetic happens makes the typed refusal a
+ * property of this function, and therefore true for every source and every caller.
+ */
+export function beaconRoundInstant(beacon) {
+    const source = BEACON_SOURCES[beacon.source];
+    if (source.timeBasis !== "deterministic-round-time")
+        return undefined;
+    const { genesisTimeSeconds, periodSeconds } = source;
+    const instantMs = (genesisTimeSeconds + (beacon.round - 1) * periodSeconds) * 1000;
+    if (!Number.isFinite(instantMs) || Math.abs(instantMs) > MAX_REPRESENTABLE_TIME_MS) {
+        fail("beacon.round", `${source.displayName} round ${beacon.round} is scheduled outside the range a timestamp can `
+            + "represent, so its publication instant cannot be computed");
+    }
+    return new Date(instantMs).toISOString();
+}
+/**
+ * The one round a run sealed at `sealedAt` may bind to on a `deterministic-round-time` source: the
+ * first round that source publishes STRICTLY after the seal (issue #3322).
+ *
+ * The point is that the seal already fixes it. `verifyRunBinding` admits any round whose instant
+ * postdates the seal, which makes the beacon VALUE unpredictable but leaves the CHOICE among
+ * realized values open: between seal and binding an operator sees many published rounds, can derive
+ * what each would produce, and can bind the one they prefer. The standard construction is to commit
+ * at seal time to a specific future round -- and for a scheduled source no separate commitment
+ * record is needed, because `(source, sealedAt)` already determines exactly one such round, and both
+ * are fixed at seal time and carried by the binding itself.
+ *
+ * From `instant(r) = genesis + (r - 1) * period`, the smallest `r` with `instant(r) > sealedAt` is
+ * `floor((sealedAt - genesis) / period) + 2`, clamped to round 1 for a seal that predates genesis.
+ *
+ * `undefined` -- meaning no round is derivable, so the operator's choice remains and the report face
+ * says so -- when the source indexes by block height rather than by a schedule, when `sealedAt` is
+ * unparseable, or when the required round leaves `MAX_BEACON_ROUND` or the representable range.
+ */
+export function requiredBeaconRound(source, sealedAt) {
+    const definition = BEACON_SOURCES[source];
+    if (definition.timeBasis !== "deterministic-round-time")
+        return undefined;
+    const { genesisTimeSeconds, periodSeconds } = definition;
+    const sealedAtMs = Date.parse(sealedAt);
+    if (!Number.isFinite(sealedAtMs))
+        return undefined;
+    const round = Math.max(1, Math.floor((sealedAtMs - genesisTimeSeconds * 1000) / (periodSeconds * 1000)) + 2);
+    if (!Number.isSafeInteger(round) || round > MAX_BEACON_ROUND)
+        return undefined;
+    // `beaconRoundInstant` owns the representability refusal; a round derived from a real seal is
+    // within one period of it, so this only ever throws on an input `Date` itself cannot represent.
+    let publishedAt;
+    try {
+        publishedAt = beaconRoundInstant({ source, round });
+    }
+    catch {
+        return undefined;
+    }
+    return publishedAt === undefined ? undefined : { round, publishedAt };
+}
+/**
+ * The derivation itself. Refuses (throws `RunBindingError`) when `sealDigest` or `beaconValue` is
+ * malformed, or when `itemSha256s` is empty, contains a duplicate, or contains a malformed entry.
+ */
+export function computeBeaconOrder(params) {
+    const { sealDigest, beaconValue, itemSha256s } = params;
+    if (!DigestSchema.safeParse(sealDigest).success) {
+        fail("sealDigest", `must match ^sha256:[0-9a-f]{64}$, got ${JSON.stringify(sealDigest)}`);
+    }
+    if (!HexValueSchema.safeParse(beaconValue).success) {
+        fail("beaconValue", `must be 64 lowercase hex characters, got ${JSON.stringify(beaconValue)}`);
+    }
+    itemSha256s.forEach((itemSha256, index) => {
+        if (!DigestSchema.safeParse(itemSha256).success) {
+            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");
+    }
+    const key = Buffer.from(`${sealDigest}${beaconValue}`, "utf8");
+    const entries = itemSha256s.map((itemSha256) => ({
+        itemSha256,
+        stream: new Uint8Array(createHmac("sha256", key).update(Buffer.from(itemSha256, "utf8")).digest()),
+    }));
+    return {
+        poolDigest: computeScreeningPoolDigest(itemSha256s),
+        order: [...entries].sort(compareScreeningStreamEntries).map((entry) => entry.itemSha256),
+    };
+}
+/**
+ * Verifies one binding record: the beacon postdates the seal, and the declared draw or order is
+ * exactly what `beacon-binding/1` derives. Throws `RunBindingError` on any disagreement -- the
+ * recomputation wins, always; a stored field never does.
+ */
+export function verifyRunBinding(candidate) {
+    const parsed = RunBindingSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        fail(issue.path.length === 0 ? "binding" : issue.path.join("."), issue.message);
+    }
+    const binding = parsed.data;
+    const sealedAtMs = Date.parse(binding.sealedAt);
+    const beaconInstant = beaconRoundInstant(binding.beacon);
+    let postSeal;
+    if (beaconInstant === undefined) {
+        postSeal = "attributive";
+    }
+    else {
+        if (Date.parse(beaconInstant) <= sealedAtMs) {
+            fail("beacon.round", `${BEACON_SOURCES[binding.beacon.source].displayName} round ${binding.beacon.round} was published at `
+                + `${beaconInstant}, which does not postdate the seal at ${binding.sealedAt} — a beacon that existed at `
+                + "seal time binds nothing");
+        }
+        postSeal = "proven-offline";
+    }
+    const pool = binding.mode === "sampled" ? binding.poolItemSha256s : binding.itemSha256s;
+    const derived = computeBeaconOrder({
+        sealDigest: binding.sealDigest,
+        beaconValue: binding.beacon.value,
+        itemSha256s: pool,
+    });
+    const required = requiredBeaconRound(binding.beacon.source, binding.sealedAt);
+    const roundBasis = required !== undefined && required.round === binding.beacon.round
+        ? "seal-derived"
+        : "operator-chosen";
+    const common = {
+        procedure: BEACON_BINDING_PROCEDURE,
+        beacon: binding.beacon,
+        sealDigest: binding.sealDigest,
+        sealedAt: binding.sealedAt,
+        poolDigest: derived.poolDigest,
+        poolSize: pool.length,
+        order: derived.order,
+        postSeal,
+        roundBasis,
+        ...(beaconInstant === undefined ? {} : { beaconInstant }),
+    };
+    if (binding.mode === "census") {
+        if (!sameSequence(binding.order, derived.order)) {
+            fail("order", "declared execution order differs from the beacon-binding/1 recomputation");
+        }
+        return { ...common, mode: "census" };
+    }
+    if (binding.sampleSize > pool.length) {
+        fail("sampleSize", `must not exceed the pool size (${pool.length}), got ${binding.sampleSize}`);
+    }
+    const sample = derived.order.slice(0, binding.sampleSize);
+    if (!sameSequence(binding.sample, sample)) {
+        fail("sample", "declared sample differs from the beacon-binding/1 recomputation");
+    }
+    return { ...common, mode: "sampled", sample };
+}
+function sameSequence(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

package/dist/binding/report-face.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The report face for `beacon-binding/1` (issue #2976, acceptance criteria 3 and 4): which binding
+ * applied, in plain words, and what it does and does not establish.
+ *
+ * Two rules carried over from `../profile/anchor-claims.ts`, whose conditional honesty copy this
+ * mirrors:
+ *
+ * - **Single-sourced, never mirrored.** `@colophon-claims/core` already depends on this package, so
+ *   producer and reader render the same function rather than two copies that can drift.
+ * - **The words key on facts, not on configuration.** Every value in a sentence below comes from
+ *   the verified binding itself, so the text is identical for every reader.
+ *
+ * A third rule follows from issue #3322: **a sentence claims unchosen-ness only where the seal
+ * established it.** A beacon that merely postdates the seal makes the value unpredictable and
+ * leaves the operator choosing among the values that postdate it. So both sentences carry
+ * `roundChoiceClause`, which asserts the second property under `seal-derived` and retracts it under
+ * `operator-chosen` rather than letting either branch imply it.
+ *
+ * A fourth rule is this module's own, and is the whole point of the originating issue: **the census
+ * sentence says it is the weaker binding.** Ordering-only binding shows the run's order was fixed by
+ * randomness that postdates the seal; it does not show the population was, because with a census
+ * there was no population choice to make. Letting the two modes share one confident sentence would
+ * be the failure this feature exists to prevent. Issue #3425 subjects that sentence to the third
+ * rule as well: `censusOrderClause` asserts the postdating only under `proven-offline`, and concedes
+ * it under `attributive` in the register the sampled opening already uses, because the clauses on
+ * either side of it concede exactly that.
+ */
+import { type VerifiedRunBinding } from "./beacon-binding.js";
+/**
+ * Which binding a run carries. `none` is the historical state every unbound run keeps -- the
+ * absence of a binding is a fact about the run, and is reported as one.
+ */
+export type RunBindingClass = "none" | "beacon-drawn-slate" | "beacon-ordering-only";
+export declare function runBindingClass(binding: VerifiedRunBinding | undefined): RunBindingClass;
+/**
+ * The one sentence that states which binding applied. `undefined` yields the unbound statement,
+ * which is a claim about the run too: nothing about it was drawn from post-seal randomness.
+ */
+export declare function runBindingSentence(binding: VerifiedRunBinding | undefined): string;
+/**
+ * The venue-limits list with the binding statement appended. Returns the list unchanged when the
+ * run carries no binding, so every run that predates this feature keeps its exact limits bytes --
+ * the same additive posture `anchoredVenueLimits` takes for an unanchored run.
+ */
+export declare function runBoundVenueLimits(limits: readonly string[], binding: VerifiedRunBinding | undefined): readonly string[];

package/dist/binding/report-face.js

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The report face for `beacon-binding/1` (issue #2976, acceptance criteria 3 and 4): which binding
+ * applied, in plain words, and what it does and does not establish.
+ *
+ * Two rules carried over from `../profile/anchor-claims.ts`, whose conditional honesty copy this
+ * mirrors:
+ *
+ * - **Single-sourced, never mirrored.** `@colophon-claims/core` already depends on this package, so
+ *   producer and reader render the same function rather than two copies that can drift.
+ * - **The words key on facts, not on configuration.** Every value in a sentence below comes from
+ *   the verified binding itself, so the text is identical for every reader.
+ *
+ * A third rule follows from issue #3322: **a sentence claims unchosen-ness only where the seal
+ * established it.** A beacon that merely postdates the seal makes the value unpredictable and
+ * leaves the operator choosing among the values that postdate it. So both sentences carry
+ * `roundChoiceClause`, which asserts the second property under `seal-derived` and retracts it under
+ * `operator-chosen` rather than letting either branch imply it.
+ *
+ * A fourth rule is this module's own, and is the whole point of the originating issue: **the census
+ * sentence says it is the weaker binding.** Ordering-only binding shows the run's order was fixed by
+ * randomness that postdates the seal; it does not show the population was, because with a census
+ * there was no population choice to make. Letting the two modes share one confident sentence would
+ * be the failure this feature exists to prevent. Issue #3425 subjects that sentence to the third
+ * rule as well: `censusOrderClause` asserts the postdating only under `proven-offline`, and concedes
+ * it under `attributive` in the register the sampled opening already uses, because the clauses on
+ * either side of it concede exactly that.
+ */
+import { BEACON_BINDING_PROCEDURE, BEACON_SOURCES, } from "./beacon-binding.js";
+export function runBindingClass(binding) {
+    if (binding === undefined)
+        return "none";
+    return binding.mode === "sampled" ? "beacon-drawn-slate" : "beacon-ordering-only";
+}
+/** `<source display name> round <n>`, the one rendering every sentence below uses. */
+function beaconName(binding) {
+    return `${BEACON_SOURCES[binding.beacon.source].displayName} round ${binding.beacon.round}`;
+}
+/**
+ * How the sentence may talk about the beacon postdating the seal. `proven-offline` asserts,
+ * because the source's own published schedule turns the round number into a time by arithmetic.
+ * `attributive` reports what the chain asserts and names what checking it takes -- the same
+ * assertive/attributive split `anchoredPreRegistrationSentence` draws between a timestamp token
+ * and an OpenTimestamps commitment.
+ */
+function postSealClause(binding) {
+    return binding.postSeal === "proven-offline"
+        ? `a value that did not exist until ${binding.beaconInstant}, after this run was sealed at ${binding.sealedAt}`
+        : `a value the chain places after this run's seal at ${binding.sealedAt} — establishing that ordering `
+            + "requires block headers on the reader's side, so it is what the chain asserts rather than something "
+            + "this bundle proves";
+}
+/**
+ * What the run's choice of ROUND does or does not add (issue #3322). A beacon that merely postdates
+ * the seal leaves the operator picking among realized values, and a sentence that names only the
+ * value's unpredictability reads as though it had ruled that out. So the clause is not decoration:
+ * under `seal-derived` it states the second property and then names the residue that survives it
+ * (the source choice), and under `operator-chosen` it retracts the property in the same plain
+ * register the census branch uses about its own weaker binding.
+ */
+function roundChoiceClause(binding) {
+    // Name the thing a chosen round would actually have moved. Saying "the result" for both modes
+    // made the census clause read as a retraction of a population claim a census never makes: with a
+    // census the population is the whole declared one whatever round applies, and only the ORDER
+    // moves. The residue named under `seal-derived` is likewise the SOURCE, not a count of sources:
+    // one admitted source is indexed by block height, where no round follows from a seal at all, so
+    // its alternatives are every height published since rather than a single candidate.
+    const derived = binding.mode === "sampled" ? "slate" : "order";
+    if (binding.roundBasis === "seal-derived") {
+        // Only a scheduled source reaches here: `requiredBeaconRound` derives nothing for a height, so
+        // an `attributive` binding is `operator-chosen` by construction.
+        return "The round was not the operator's to pick either: it is the first round this source publishes after "
+            + "the seal, so the seal instant alone fixes it. What choosing remains is the source — this procedure "
+            + "admits other beacons, one of them indexed by block height, where no round follows from a seal at all — "
+            + "so an operator could have bound a different source instead.";
+    }
+    if (binding.postSeal === "attributive") {
+        // Say no more here than the postdating clause two sentences earlier already conceded. Claiming
+        // the value was unpredictable would assert exactly what this branch cannot check: nothing in
+        // the bundle places this height after the seal, so nothing rules out a height that predates it.
+        return `No round follows from a seal on a height-indexed source, so this height was the operator's choice — `
+            + `and on the reader's side it is the chain, not this bundle, that places it after the seal at all. Any `
+            + `other height would have derived a different ${derived} from the same inputs.`;
+    }
+    return `Which post-seal value applied was still the operator's choice: this binding names a round selected after `
+        + `the seal, and every round the source published in between was an available alternative deriving a `
+        + `different ${derived} from the same inputs. The value could not have been predicted; this ${derived} is `
+        + `nonetheless one of several the operator could have realized by waiting.`;
+}
+/**
+ * What the census binding shows about the ORDER (issue #3425). The postdating half keys on
+ * `postSeal` for the same reason the sampled opening does: on a height-indexed source nothing in
+ * the bundle places the value after the seal, so asserting that the order was fixed by randomness
+ * postdating it would be conceded by `postSealClause` two clauses earlier and again by
+ * `roundChoiceClause` two clauses later. The population half is unconditional -- a census makes no
+ * population choice on any basis.
+ */
+function censusOrderClause(binding) {
+    const order = binding.postSeal === "proven-offline"
+        ? "It shows the run's order was fixed by randomness postdating the seal"
+        : "It shows the run's order was tied to a value this bundle cannot place after the seal";
+    return `${order}; it does not show the population was, because a census makes no population choice.`;
+}
+const RECOMPUTE_CLAUSE = `Any reader recomputes the derivation offline from the sealed digest, the published beacon value and the `
+    + `item identities alone, by procedure ${BEACON_BINDING_PROCEDURE}; the verifier fails the run when its `
+    + "recomputation disagrees.";
+/**
+ * The one sentence that states which binding applied. `undefined` yields the unbound statement,
+ * which is a claim about the run too: nothing about it was drawn from post-seal randomness.
+ */
+export function runBindingSentence(binding) {
+    if (binding === undefined) {
+        return "This run is bound to no public randomness: its seal shows the design existed by a given time, and "
+            + "nothing establishes that execution followed the seal rather than preceding it.";
+    }
+    if (binding.mode === "sampled") {
+        // The "could not have been selected after the fact" claim is the one issue #3322 exists to
+        // stop overstating, so it appears ONLY on the branch where the seal named the round. Under
+        // `operator-chosen` it is not merely unproven, it is false -- selecting the slate after the
+        // fact needed no prediction at all, only waiting for a round whose derivation the operator
+        // liked -- so it is dropped rather than hedged.
+        //
+        // The opening keys on `postSeal` as well, for the same reason `roundChoiceClause` does: under
+        // `attributive` nothing in the bundle places the height after the seal, so an opening that
+        // called the value unpredictable would assert what the branch cannot check -- and would be
+        // retracted two clauses later by the very postdating clause it introduces.
+        const opening = binding.roundBasis === "seal-derived"
+            ? "This run's slate was drawn, not chosen"
+            : binding.postSeal === "attributive"
+                ? "This run's slate was drawn from a value this bundle cannot place after the seal"
+                : "This run's slate was drawn from a value it could not have predicted";
+        const unpredictabilityClause = binding.roundBasis === "seal-derived"
+            ? "Selecting the slate after the fact would have required predicting that value. "
+            : "";
+        return `${opening}: its ${binding.sample.length} items were derived from a `
+            + `declared pool of ${binding.poolSize} by procedure ${BEACON_BINDING_PROCEDURE}, keyed on this run's sealed `
+            + `digest together with ${beaconName(binding)} — ${postSealClause(binding)}. `
+            + `${unpredictabilityClause}${roundChoiceClause(binding)} ${RECOMPUTE_CLAUSE}`;
+    }
+    return `This run evaluated its whole declared population of ${binding.poolSize} items, so no slate was selected `
+        + `and none could be selected after the fact. The beacon binds execution ORDER only: the order was derived by `
+        + `procedure ${BEACON_BINDING_PROCEDURE} from this run's sealed digest together with ${beaconName(binding)} — `
+        + `${postSealClause(binding)}. This is a weaker binding than a beacon-drawn slate. `
+        + `${censusOrderClause(binding)} ${roundChoiceClause(binding)} ${RECOMPUTE_CLAUSE}`;
+}
+/**
+ * The venue-limits list with the binding statement appended. Returns the list unchanged when the
+ * run carries no binding, so every run that predates this feature keeps its exact limits bytes --
+ * the same additive posture `anchoredVenueLimits` takes for an unanchored run.
+ */
+export function runBoundVenueLimits(limits, binding) {
+    return binding === undefined ? limits : [...limits, runBindingSentence(binding)];
+}

package/dist/cli.js

@@ -1,7 +1,6 @@
 import { readFileSync } from "node:fs";
 import { SUPPORTED_BUNDLE_FORMATS } from "./manifest.js";
-import { EVIDENCE_NATIVE_BUNDLE_V5_CHECKS } from "@jinn-network/benchmarking-evidence";
-import { PUBLIC_BUNDLE_VERIFICATION_CHECKS, PUBLIC_BUNDLE_V6_CHECKS } from "./reader-instructions.js";
+import { summarizeVerificationOutcome } from "./outcome.js";
 import { verifyPublicBundle } from "./verify.js";
 import { VERIFIER_VERSION } from "./version.js";
 export { VERIFIER_VERSION } from "./version.js";
@@ -75,29 +74,82 @@ function renderAnchorReport(report) {
         : report.anchors.map(renderAnchor).join("\n");
     return `\nAnchors\n${anchors}\n\nAnchor subjects\n${report.subjects.map(renderSubject).join("\n")}\n`;
 }
+const SIGNER_ROLE_NAMES = {
+    publisher: "publisher",
+    "automated-grader": "automated grader",
+    "human-reviewer": "human reviewer",
+    "label-admission": "label admission",
+};
+/** The role in plain words. `urn:`/`did:key` identifiers stay in `--json`, where they are the join
+ * key a reader actually needs them for; on this surface they are noise a reader has to decode.
+ * Undeclared custody is stated rather than left blank: a reader who has seen the same-operator
+ * suffix elsewhere would otherwise read its absence as an independence claim, which no bundle
+ * format can establish. The publisher takes no suffix -- it *is* the operator the others are
+ * measured against. */
+function renderSignerGroup(role, custody, count) {
+    const suffix = role === "publisher"
+        ? ""
+        : custody === "same-operator" ? " \u2014 same operator" : " \u2014 custody not declared";
+    return `  ${SIGNER_ROLE_NAMES[role]}${suffix} \u00b7 ${count} ${count === 1 ? "key" : "keys"}`;
+}
+function renderSigners(signers) {
+    const counts = new Map();
+    for (const signer of signers) {
+        const key = `${signer.role} ${signer.custody}`;
+        const group = counts.get(key);
+        if (group === undefined)
+            counts.set(key, { role: signer.role, custody: signer.custody, count: 1 });
+        else
+            group.count += 1;
+    }
+    // The role-name record's own key order is the print order; a second parallel list would drift.
+    const order = Object.keys(SIGNER_ROLE_NAMES);
+    const groups = [...counts.values()]
+        .sort((left, right) => order.indexOf(left.role) - order.indexOf(right.role));
+    return `\nSigned by\n${groups.map((group) => renderSignerGroup(group.role, group.custody, group.count)).join("\n")}\n`;
+}
 export function renderVerifiedBundle(result) {
-    const checks = result.checks.map((check) => `${check.padEnd(24)}passed`).join("\n");
-    const totalChecks = result.format === "benchmark-product-public-bundle/5"
-        ? EVIDENCE_NATIVE_BUNDLE_V5_CHECKS.length
-        : result.format === "benchmark-product-public-bundle/6"
-            ? PUBLIC_BUNDLE_V6_CHECKS.length
-            : PUBLIC_BUNDLE_VERIFICATION_CHECKS.length;
+    // A metadata-first bundle carries artifact digests without their bytes. Printing "passed" for a
+    // check that read nothing would be the one claim this format cannot afford, so the deferred check
+    // prints as not fetched and is counted out of the passed total.
+    const outcome = summarizeVerificationOutcome(result);
+    const artifactContent = outcome.artifactContent;
+    const checks = outcome.outcomes
+        .map(({ check, state }) => `${check.padEnd(24)}${state}`)
+        .join("\n");
+    const totalChecks = outcome.total;
     const identity = result.identity.startsWith("sha256:") ? result.identity : `sha256:${result.identity}`;
     const anchors = "anchors" in result && result.anchors !== undefined
         ? renderAnchorReport(result.anchors)
         : "";
+    const signers = result.signers === undefined || result.signers.length === 0
+        ? ""
+        : renderSigners(result.signers);
+    // Naming the digests is what makes the deferred check completable: they are the addresses to
+    // fetch and the expectations to check the fetched bytes against. Adding a body to this directory
+    // is not the completion path -- it would break the manifest closure the bundle is identified by,
+    // so the reader is pointed at the full-evidence bundle instead.
+    const artifactContentReport = artifactContent === undefined
+        ? ""
+        : `\nArtifact content\n  ${artifactContent.notFetched} artifact ${artifactContent.notFetched === 1 ? "body was" : "bodies were"} not fetched. This bundle carries their\n  exact digests, not their bytes:\n${artifactContent.notFetchedDigests.map((digest) => `    sha256:${digest}`).join("\n")}\n  Check fetched bytes against those digests yourself, or verify the\n  full-evidence bundle, which carries them.\n`;
+    const artifactContentLimit = artifactContent === undefined
+        ? ""
+        : "\nEverything above was checked against the bytes this bundle carries. The artifact\ncontents themselves were not read, so nothing here says what they contain.";
     const anchorLimits = anchors === ""
         ? ""
         : "\nAn anchor dates the bytes it covers and says nothing else about the run: not\nthat results were produced after it, and not that the anchoring authority is\nindependent of the bundle's owner.";
-    return `Verified: ${result.checks.length} of ${totalChecks} checks passed
+    const verdictLine = outcome.notFetched === 0
+        ? `Verified: ${outcome.passed} of ${totalChecks} checks passed`
+        : `Verified: ${outcome.passed} of ${totalChecks} checks passed, ${outcome.notFetched} not fetched`;
+    return `${verdictLine}
 Bundle: ${identity}
 Format: ${result.format}
 
 ${checks}
-${anchors}
+${signers}${artifactContentReport}${anchors}
 This checks the bundle's integrity, evidence closure, calculations, report,
 and claim consistency. It does not prove that the machine that produced the
-bundle was honest or that the compared identities are independent parties.${anchorLimits}
+bundle was honest or that the compared identities are independent parties.${artifactContentLimit}${anchorLimits}
 No files were uploaded.
 Protocol identifiers name https://spec.jinn.network/…. That origin is not hosted yet.
 Verification uses the exact platform bytes installed from npm.
@@ -132,6 +184,16 @@ function readBlockHeaders(bytes, path) {
         };
     });
 }
+/** `urn:…` and `did:key:z…` as they appear inside a refusal message. The base58btc class stops a
+ * `did:key` match before a trailing `:reason` suffix the message appended. */
+const RAW_IDENTIFIER = /urn:[^\s,;)"']+|did:key:z[1-9A-HJ-NP-Za-km-z]+/gu;
+/** A refusal names the signer it refused, and on the machine surface that identifier is the whole
+ * point. On the human surface it is a string a reader cannot act on, so the same rule as the
+ * verified report applies: the identifier lives in `--json` (issue #3024). What failed, and where,
+ * is untouched. */
+function withoutRawIdentifiers(message) {
+    return message.replace(RAW_IDENTIFIER, "<identifier: see --json>");
+}
 function parseArguments(args) {
     const positional = [];
     const tsaRoots = [];
@@ -199,7 +261,7 @@ export async function runVerifierCli(args, deps = {}) {
         const stdout = parsed.json
             ? `${JSON.stringify({ ok: false, verifierVersion: VERIFIER_VERSION, supportedFormats: SUPPORTED_BUNDLE_FORMATS, code, message: error.message })}\n`
             : "";
-        const stderr = parsed.json ? "" : `colophon-verify: ${error.message}\n`;
+        const stderr = parsed.json ? "" : `colophon-verify: ${withoutRawIdentifiers(error.message)}\n`;
         return { exitCode: code === "record-integrity" ? 1 : 2, stdout, stderr };
     }
 }