@zanii/certify 0.0.0-stage → 0.6.0

package/dist/board.js

@@ -0,0 +1,428 @@
+// spec/governance-board.md: the scheme governance board (k of n; each membership change signed by
+// k of the outgoing board, the first by the scheme owner) and the append-only log of scheme and
+// profile releases the board signs. A lab may only use a scheme or profile version with a release.
+import { jcsHash } from "@zanii/core";
+import { isDid, isInt, isIso, isObj, isSha, ms, SLUG, sortedUnique } from "./shared.js";
+import { signatureOk, signatureOver, signerDid } from "./signer.js";
+import { logPositionOk } from "./status.js";
+import { schemeAuthority } from "./scheme-authority.js";
+export async function bodySignature(body, signer) {
+    if ("signatures" in body)
+        throw new Error("sign the body, without signatures");
+    return { signer: signerDid(signer), sig: await signatureOver(body, signer) };
+}
+const bySigner = (a, b) => (a.signer < b.signer ? -1 : a.signer > b.signer ? 1 : 0);
+/** The document with its signatures sorted by signer; one signer signs once. */
+export function withSignatures(body, sigs) {
+    if ("signatures" in body)
+        throw new Error("the body already carries signatures");
+    const sorted = sigs.map((s) => ({ signer: s.signer, sig: s.sig })).sort(bySigner);
+    if (new Set(sorted.map((s) => s.signer)).size !== sorted.length)
+        throw new Error("a signer signs once");
+    return { ...body, signatures: sorted };
+}
+/**
+ * Section 1: the signers of `doc` whose signature verifies, and whether `signatures` is well formed
+ * (1 to 64 `{signer, sig}`, strictly sorted by signer, each verifying, each in `allowed` when given).
+ */
+export function signersOf(doc, allowed) {
+    const { signatures, ...body } = doc;
+    if (!Array.isArray(signatures) || signatures.length < 1 || signatures.length > (doc.type === "certify.board-transition" ? 65 : 64))
+        return { signers: [], wellFormed: false };
+    const signers = [];
+    let wellFormed = true;
+    let last = "";
+    for (const s of signatures) {
+        if (!isObj(s) || Object.keys(s).length !== 2 || !isDid(s.signer) || s.signer <= last) {
+            wellFormed = false;
+            continue;
+        }
+        last = s.signer;
+        if (!signatureOk(body, s.sig, s.signer) || (allowed && !allowed.includes(s.signer)))
+            wellFormed = false;
+        else
+            signers.push(s.signer);
+    }
+    return { signers, wellFormed };
+}
+const sortedDistinct = (xs) => Array.isArray(xs) && xs.every((x) => typeof x === "string") && sortedUnique(xs).join("\n") === xs.join("\n");
+function boardError(b) {
+    if (!isDid(b.owner))
+        return "owner must be a did:key";
+    if (!logPositionOk(b.seq, b.prev))
+        return "seq and prev are not a log position";
+    const m = b.members;
+    if (!Array.isArray(m) || m.length < 1 || m.length > 64 || !m.every(isDid) || !sortedDistinct(m))
+        return "members must be 1 to 64 sorted, distinct did:keys";
+    if (!isInt(b.threshold, 1, m.length))
+        return "threshold must be an integer from 1 to the number of members";
+    if (!isIso(b.effective_from))
+        return "effective_from must be an ISO timestamp";
+    if ("ledger" in b && !isDid(b.ledger))
+        return "ledger must be a did:key";
+    return null;
+}
+/** The unsigned board (each signer signs it with `bodySignature`). */
+export function boardBody(f) {
+    const body = {
+        v: 1,
+        type: "certify.board",
+        owner: f.owner,
+        seq: f.seq,
+        prev: f.prev,
+        members: Array.isArray(f.members) ? sortedUnique(f.members) : f.members,
+        threshold: f.threshold,
+        effective_from: f.effectiveFrom,
+        ...(f.ledger !== undefined ? { ledger: f.ledger } : {}),
+    };
+    const err = boardError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** A board signed by `signers`: the owner for the first board, k of the previous board after. */
+export async function buildBoard(f, signers) {
+    const body = boardBody(f);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+export const isBoard = (b) => isObj(b) && b.v === 1 && b.type === "certify.board" && Object.keys(b).length === ("ledger" in b ? 10 : 9);
+const ownerReason = (owner, opts) => opts.owner === undefined
+    ? ["no trusted scheme owner supplied: the owner was NOT checked"]
+    : owner !== opts.owner
+        ? ["the board log is not the trusted scheme owner's"]
+        : [];
+/**
+ * Section 2: the boards form one log: board i at seq i naming board i - 1, one owner, each taking
+ * effect after the previous one; board 0 signed by the owner, every later board by at least the
+ * previous board's threshold of its members, and no other signature.
+ */
+export function verifyBoardLog(boards, opts = {}) {
+    if (!Array.isArray(boards) || boards.length === 0)
+        return { ok: false, reasons: ["the board log is empty"] };
+    const reasons = [];
+    boards.forEach((b, i) => {
+        const prev = i > 0 ? boards[i - 1] : null;
+        if (!isBoard(b)) {
+            reasons.push(`board ${i} is not a board (v1)`);
+            return;
+        }
+        const err = boardError(b);
+        if (err) {
+            reasons.push(`board ${i} is malformed: ${err}`);
+            return;
+        }
+        if (b.seq !== i)
+            reasons.push(`board ${i} is not at position ${i}`);
+        if (b.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`board ${i} does not name the previous board`);
+        if (i > 0 && isObj(boards[0]) && b.owner !== boards[0].owner)
+            reasons.push(`board ${i} names another scheme owner`);
+        if (i > 0 && isBoard(prev) && !(ms(b.effective_from) > ms(prev.effective_from)))
+            reasons.push(`board ${i} does not take effect after the previous board`);
+        const allowed = i === 0 ? [b.owner] : isBoard(prev) && Array.isArray(prev.members) ? prev.members : [];
+        const need = i === 0 ? 1 : isBoard(prev) && Number.isInteger(prev.threshold) ? prev.threshold : 1;
+        const s = signersOf(b, allowed);
+        if (!s.wellFormed)
+            reasons.push(`board ${i} carries a signature that is malformed, invalid or not by an authorised signer`);
+        if (i === 0 && s.signers.length < 1)
+            reasons.push("board 0 is not signed by the scheme owner");
+        if (i > 0 && s.signers.length < need)
+            reasons.push(`board ${i} is signed by ${s.signers.length} of the ${need} previous board members required`);
+    });
+    reasons.push(...ownerReason(isObj(boards[0]) ? boards[0].owner : undefined, opts));
+    return { ok: reasons.length === 0, reasons };
+}
+// ---------------------------------------------------------------- 3. releases
+export const RELEASE_KINDS = ["scheme", "profile"];
+const SCHEME_REF = /^zanii-certify\/(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$/;
+const PROFILE_REF = new RegExp(`^${SLUG.source.slice(1, -1)}/[1-9][0-9]{0,5}$`);
+const text = (v) => typeof v === "string" && v.length >= 1 && v.length <= 4000;
+export const isText = (t) => isObj(t) && Object.keys(t).length === 2 && text(t.en) && text(t.ar);
+export function subjectOk(s) {
+    if (!isObj(s) || Object.keys(s).length !== 2 || typeof s.ref !== "string")
+        return false;
+    return s.kind === "scheme" ? SCHEME_REF.test(s.ref) : s.kind === "profile" && PROFILE_REF.test(s.ref);
+}
+function releaseError(r) {
+    if (!logPositionOk(r.seq, r.prev))
+        return "seq and prev are not a log position";
+    if (!subjectOk(r.subject))
+        return "subject must be {kind: scheme, ref: zanii-certify/<m>.<n>} or {kind: profile, ref: <slug>/<version>}";
+    if (!isSha(r.sha256))
+        return "sha256 must be a sha256 hash";
+    if (!isIso(r.effective_from))
+        return "effective_from must be an ISO timestamp";
+    if (!isText(r.notes))
+        return "notes need en and ar text (1-4000)";
+    if (!isSha(r.board))
+        return "board must be a board hash";
+    return null;
+}
+export function releaseBody(f) {
+    const body = {
+        v: 1,
+        type: "certify.release",
+        seq: f.seq,
+        prev: f.prev,
+        subject: { kind: f.subject?.kind, ref: f.subject?.ref },
+        sha256: f.sha256,
+        effective_from: f.effectiveFrom,
+        notes: { en: f.notes?.en, ar: f.notes?.ar },
+        board: f.board,
+    };
+    const err = releaseError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** A release signed by `signers` (members of the board it names). */
+export async function buildRelease(f, signers) {
+    const body = releaseBody(f);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+export const isRelease = (r) => isObj(r) && r.v === 1 && r.type === "certify.release" && Object.keys(r).length === 10;
+/**
+ * A board-signed document (release, withdrawal, body register) against a board log already checked:
+ * the board it names is in the log and in force at its effective_from, and k of its members signed it.
+ */
+export function boardSignedReasons(r, boards, noun) {
+    const reasons = [];
+    const i = boards.findIndex((b) => isBoard(b) && jcsHash(b) === r.board);
+    const board = boards[i];
+    if (!isBoard(board))
+        return [`${noun} names a board that is not in the board log`];
+    const next = boards[i + 1];
+    const at = ms(r.effective_from);
+    if (!(ms(board.effective_from) <= at) || (isBoard(next) && !(ms(next.effective_from) > at)))
+        reasons.push(`the named board is not the board in force at the ${noun}'s effective_from`);
+    const need = Number.isInteger(board.threshold) ? board.threshold : 1;
+    const s = signersOf(r, Array.isArray(board.members) ? board.members : []);
+    if (!s.wellFormed)
+        reasons.push(`${noun} carries a signature that is malformed, invalid or not by a board member`);
+    if (s.signers.length < need)
+        reasons.push(`${noun} is signed by ${s.signers.length} of the ${need} board members required`);
+    return reasons;
+}
+/** One release against a board log already checked: fields, its board in force, k board signatures. */
+function releaseReasons(r, boards) {
+    if (!isRelease(r))
+        return ["not a scheme release (v1)"];
+    const err = releaseError(r);
+    if (err)
+        return [`release is malformed: ${err}`];
+    return boardSignedReasons(r, boards, "release");
+}
+/** Section 3: one release, with the board log it names (checked with `verifyBoardLog`). */
+export function verifyRelease(release, boards, opts = {}) {
+    const reasons = [...verifyBoardLog(boards, opts).reasons, ...releaseReasons(release, Array.isArray(boards) ? boards : [])];
+    return { ok: reasons.length === 0, reasons };
+}
+export const subjectKey = (s) => (isObj(s) ? `${String(s.kind)} ${String(s.ref)}` : "?");
+/** Section 4: the release log: every release valid, at seq i naming release i - 1, effective_from never going back, each subject released once. */
+export function verifyReleaseLog(releases, boards, opts = {}) {
+    if (opts.schemeLog !== undefined) {
+        const { reasons } = schemeAuthority(opts.schemeLog, opts.owner, { "certify.board": boards, "certify.release": releases });
+        return { ok: reasons.length === 0, reasons };
+    }
+    const reasons = [...verifyBoardLog(boards, opts).reasons];
+    if (!Array.isArray(releases) || releases.length === 0)
+        return { ok: false, reasons: [...reasons, "the release log is empty"] };
+    const seen = new Set();
+    releases.forEach((r, i) => {
+        reasons.push(...releaseReasons(r, Array.isArray(boards) ? boards : []).map((x) => `release ${i}: ${x}`));
+        if (!isRelease(r))
+            return;
+        const prev = i > 0 ? releases[i - 1] : null;
+        if (r.seq !== i)
+            reasons.push(`release ${i} is not at position ${i}`);
+        if (r.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`release ${i} does not name the previous release`);
+        if (i > 0 && isRelease(prev) && !(ms(r.effective_from) >= ms(prev.effective_from)))
+            reasons.push(`release ${i} takes effect before the previous release`);
+        const key = subjectKey(r.subject);
+        if (seen.has(key))
+            reasons.push(`release ${i} releases ${key} again`);
+        seen.add(key);
+    });
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Section 5: may a lab use `subject` at `at`? The release log must verify, release the subject, take
+ * effect no later than `at` and (with `sha256`) for exactly that content. With `withdrawals`
+ * (section 6), a release withdrawn at or before `at` may not be used.
+ */
+export function requireRelease(releases, boards, subject, at, opts = {}) {
+    if (!isIso(at))
+        throw new Error("at must be an ISO timestamp");
+    const authority = opts.schemeLog !== undefined ? schemeAuthority(opts.schemeLog, opts.owner, { "certify.board": boards, "certify.release": releases, ...(opts.withdrawals ? { "certify.release-withdrawal": opts.withdrawals } : {}) }) : null;
+    const reasons = [...(authority ? authority.reasons : verifyReleaseLog(releases, boards, opts).reasons)];
+    const key = subjectKey(subject);
+    const r = (Array.isArray(releases) ? releases : []).find((x) => isRelease(x) && !authority?.canceled.has(jcsHash(x)) && subjectKey(x.subject) === key);
+    if (!r)
+        reasons.push(`${key} has no release`);
+    else {
+        if (!(ms(r.effective_from) <= ms(at)))
+            reasons.push(`${key} is not released until ${r.effective_from}`);
+        if (opts.sha256 !== undefined && r.sha256 !== opts.sha256)
+            reasons.push(`${key} content is not the released content`);
+    }
+    if (opts.withdrawals === undefined)
+        return { ok: reasons.length === 0, reasons, release: r ?? null };
+    if (!authority)
+        reasons.push(...withdrawalReasons(opts.withdrawals, releases, boards));
+    const w = r ? withdrawalOf((Array.isArray(opts.withdrawals) ? opts.withdrawals : []).filter(x => !authority?.canceled.size || !authority.canceled.has(jcsHash(x))), r) : null;
+    if (w && ms(w.effective_from) <= ms(at))
+        reasons.push(`${key} is withdrawn from ${w.effective_from} (${w.reason})`);
+    return { ok: reasons.length === 0, reasons, release: r ?? null, withdrawal: w };
+}
+/**
+ * Section 4a: may `board` be appended to the board log now? The board log with it verifies, it takes
+ * effect after the effective_from of every release already in the release log, and the release log
+ * still verifies against the longer board log (a board change never breaks a release).
+ */
+export function verifyBoardAppend(boards, releases, board, opts = {}) {
+    const next = [...(Array.isArray(boards) ? boards : []), board];
+    const rel = Array.isArray(releases) ? releases : [];
+    const reasons = [...verifyBoardLog(next, opts).reasons];
+    if (isBoard(board) && isIso(board.effective_from) && rel.some((r) => isRelease(r) && isIso(r.effective_from) && !(ms(board.effective_from) > ms(r.effective_from))))
+        reasons.push("the board does not take effect after every release's effective_from");
+    if (rel.length)
+        reasons.push(...verifyReleaseLog(rel, next, opts).reasons);
+    return { ok: reasons.length === 0, reasons: [...new Set(reasons)] };
+}
+/**
+ * Section 4a: may `release` be appended to the release log now? The release log with it verifies,
+ * and it is signed by the newest board of the board log (a board that was replaced signs nothing more).
+ */
+export function verifyReleaseAppend(releases, boards, release, opts = {}) {
+    const reasons = [...verifyReleaseLog([...(Array.isArray(releases) ? releases : []), release], boards, opts).reasons];
+    const last = Array.isArray(boards) ? boards.at(-1) : undefined;
+    if (isRelease(release) && !(isBoard(last) && release.board === jcsHash(last)))
+        reasons.push("the release is not signed by the newest board of the board log");
+    return { ok: reasons.length === 0, reasons: [...new Set(reasons)] };
+}
+// ---------------------------------------------------------------- 6. release withdrawals
+export const WITHDRAWAL_REASONS = ["DEFECT", "SECURITY", "LEGAL", "OTHER"];
+function withdrawalError(w) {
+    if (!logPositionOk(w.seq, w.prev))
+        return "seq and prev are not a log position";
+    if (!subjectOk(w.subject))
+        return "subject must be {kind: scheme, ref: zanii-certify/<m>.<n>} or {kind: profile, ref: <slug>/<version>}";
+    if (!isSha(w.release))
+        return "release must be a release hash";
+    if (!WITHDRAWAL_REASONS.includes(w.reason))
+        return `reason must be one of ${WITHDRAWAL_REASONS.join(", ")}`;
+    if (!isText(w.notes))
+        return "notes need en and ar text (1-4000)";
+    if (!isIso(w.effective_from))
+        return "effective_from must be an ISO timestamp";
+    if (!isSha(w.board))
+        return "board must be a board hash";
+    return null;
+}
+// Shared by the incremental verifier; field rules have one implementation.
+export { boardError as boardFieldError, releaseError as releaseFieldError, withdrawalError as withdrawalFieldError };
+export function releaseWithdrawalBody(f) {
+    const body = {
+        v: 1,
+        type: "certify.release-withdrawal",
+        seq: f.seq,
+        prev: f.prev,
+        subject: { kind: f.subject?.kind, ref: f.subject?.ref },
+        release: f.release,
+        reason: f.reason,
+        notes: { en: f.notes?.en, ar: f.notes?.ar },
+        effective_from: f.effectiveFrom,
+        board: f.board,
+    };
+    const err = withdrawalError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** A release withdrawal signed by `signers` (k members of the board it names). */
+export async function buildReleaseWithdrawal(f, signers) {
+    const body = releaseWithdrawalBody(f);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+export const isWithdrawal = (w) => isObj(w) && w.v === 1 && w.type === "certify.release-withdrawal" && Object.keys(w).length === 11;
+/** The withdrawal of `release` in a list (a release is withdrawn at most once), or null. */
+function withdrawalOf(withdrawals, release) {
+    const h = jcsHash(release);
+    return (Array.isArray(withdrawals) ? withdrawals : []).find((w) => isWithdrawal(w) && w.release === h) ?? null;
+}
+/** Section 6 without the release log's own reasons. */
+function withdrawalReasons(withdrawals, releases, boards) {
+    if (!Array.isArray(withdrawals))
+        return ["the withdrawal log is not a list"];
+    const rel = Array.isArray(releases) ? releases : [];
+    const bl = Array.isArray(boards) ? boards : [];
+    const reasons = [];
+    const seen = new Set();
+    withdrawals.forEach((w, i) => {
+        if (!isWithdrawal(w)) {
+            reasons.push(`withdrawal ${i} is not a release withdrawal (v1)`);
+            return;
+        }
+        const err = withdrawalError(w);
+        if (err) {
+            reasons.push(`withdrawal ${i} is malformed: ${err}`);
+            return;
+        }
+        const prev = i > 0 ? withdrawals[i - 1] : null;
+        if (w.seq !== i)
+            reasons.push(`withdrawal ${i} is not at position ${i}`);
+        if (w.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`withdrawal ${i} does not name the previous withdrawal`);
+        if (i > 0 && isWithdrawal(prev) && !(ms(w.effective_from) >= ms(prev.effective_from)))
+            reasons.push(`withdrawal ${i} takes effect before the previous withdrawal`);
+        const r = rel.find((x) => isRelease(x) && jcsHash(x) === w.release);
+        if (!isRelease(r))
+            reasons.push(`withdrawal ${i} names a release that is not in the release log`);
+        else {
+            if (subjectKey(r.subject) !== subjectKey(w.subject))
+                reasons.push(`withdrawal ${i} subject is not the release's subject`);
+            if (!(ms(w.effective_from) >= ms(r.effective_from)))
+                reasons.push(`withdrawal ${i} takes effect before the release`);
+        }
+        if (seen.has(w.release))
+            reasons.push(`withdrawal ${i} withdraws a release again`);
+        seen.add(w.release);
+        reasons.push(...boardSignedReasons(w, bl, "withdrawal").map((x) => `withdrawal ${i}: ${x}`));
+    });
+    return reasons;
+}
+/**
+ * Section 6: the withdrawal log: the release log verifies, every withdrawal at seq i naming
+ * withdrawal i - 1, effective_from never going back, naming a release of the log with its subject,
+ * taking effect no earlier than it, each release withdrawn once, signed by k of the board in force.
+ */
+export function verifyWithdrawalLog(withdrawals, releases, boards, opts = {}) {
+    if (opts.schemeLog !== undefined) {
+        const { reasons } = schemeAuthority(opts.schemeLog, opts.owner, { "certify.board": boards, "certify.release": releases, "certify.release-withdrawal": withdrawals });
+        return { ok: reasons.length === 0, reasons };
+    }
+    const reasons = [...verifyReleaseLog(releases, boards, opts).reasons, ...withdrawalReasons(withdrawals, releases, boards)];
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Section 6: a certificate issued under a withdrawn scheme or profile version is flagged, never
+ * failed. `ok` is whether the withdrawal log verified; `flags` names each withdrawal that touches
+ * the certificate's scheme or profile.
+ */
+export function withdrawalFlags(cert, logs) {
+    const authority = logs.schemeLog !== undefined ? schemeAuthority(logs.schemeLog, logs.owner, { "certify.board": logs.boards, "certify.release": logs.releases, "certify.release-withdrawal": logs.withdrawals }) : null;
+    const reasons = authority ? authority.reasons : verifyWithdrawalLog(logs.withdrawals, logs.releases, logs.boards, logs.owner === undefined ? {} : { owner: logs.owner }).reasons;
+    const claim = isObj(cert?.claim) ? cert.claim : {};
+    const flags = [];
+    for (const subject of [{ kind: "scheme", ref: claim.scheme }, { kind: "profile", ref: claim.profile }]) {
+        const key = subjectKey(subject);
+        const r = (Array.isArray(logs.releases) ? logs.releases : []).find((x) => isRelease(x) && !authority?.canceled.has(jcsHash(x)) && subjectKey(x.subject) === key);
+        const w = r ? withdrawalOf((Array.isArray(logs.withdrawals) ? logs.withdrawals : []).filter(x => !authority?.canceled.size || !authority.canceled.has(jcsHash(x))), r) : null;
+        if (!w)
+            continue;
+        const after = ms(cert?.issued_at) >= ms(w.effective_from) ? "; the certificate was issued after it" : "";
+        flags.push(`${key} was withdrawn from ${w.effective_from} (${w.reason})${after}`);
+    }
+    return { ok: reasons.length === 0, reasons, flags };
+}

package/dist/bundle.d.ts

@@ -0,0 +1,100 @@
+import { type Staff } from "./impartiality.ts";
+import { type CategoryScore } from "./scoring.ts";
+import { type ApplianceExecution, type ApplianceExportIdentity } from "./appliance-execution.ts";
+export type { ApplianceExecution, ApplianceExportIdentity } from "./appliance-execution.ts";
+export interface CategoryCount {
+    category: string;
+    trials: number;
+    passes: number;
+    threshold_ppm: number;
+    findings: readonly string[];
+}
+export interface CategoryResult extends CategoryScore {
+    category: string;
+    trials: number;
+    passes: number;
+    threshold_ppm: number;
+    findings: string[];
+}
+export interface Evidence {
+    case_id: string;
+    /** The hash-chain head of the case's recorded transcript. */
+    chain_head: string;
+    blackbox_session?: string;
+}
+export interface BundleInput {
+    execution?: ApplianceExecution | null;
+    profile: string;
+    level: number;
+    fingerprint: string;
+    plan: {
+        categories: readonly string[];
+        trials: number;
+    };
+    results: readonly CategoryCount[];
+    evidence: readonly Evidence[];
+    suite_snapshot: string;
+    staff: Staff;
+    started_at: string;
+    ended_at: string;
+    /** Default: pickScheme (0.1 for Levels 1 and 2, 0.2 for Level 3); the profile's scheme. */
+    scheme?: string;
+    /** Section 4: a partial re-test, and the bundle of the earlier passing run that covers the rest. */
+    partial?: {
+        covered_by: string;
+    } | null;
+    /** Section 2a (scheme 0.4): the categories assessed as simulated multi-step workflows, and the agent interface tested. */
+    assessment?: Assessment | null;
+}
+/** What a 0.4 run assessed: `voice_text` is a voice agent tested through its text interface only, never its audio. */
+export interface Assessment {
+    trajectory_categories: string[];
+    interface: "text" | "voice_text";
+}
+export interface ResultBundle {
+    execution?: ApplianceExecution;
+    v: 1;
+    type: "certify.result-bundle";
+    scheme: string;
+    profile: string;
+    level: number;
+    fingerprint: string;
+    plan: {
+        categories: string[];
+        trials: number;
+    };
+    results: CategoryResult[];
+    evidence: Evidence[];
+    suite_snapshot: string;
+    staff: {
+        testers: string[];
+        reviewer: string | null;
+        decider: string;
+    };
+    started_at: string;
+    ended_at: string;
+    partial?: {
+        covered_by: string;
+    };
+    assessment?: Assessment;
+}
+export interface ApplianceExportBundle extends Omit<ResultBundle, "v" | "staff" | "execution" | "partial"> {
+    v: 2;
+    phase: "undecided";
+    staff: {
+        testers: string[];
+        reviewer: null;
+        decider: null;
+    };
+    execution: ApplianceExportIdentity;
+}
+export type ApplianceExportBundleInput = Omit<BundleInput, "staff" | "partial" | "execution"> & {
+    testers: readonly string[];
+    execution: ApplianceExportIdentity;
+};
+/** Existing v1 output is unchanged unless explicit verified appliance provenance is supplied. */
+export declare function buildBundle(input: BundleInput): ResultBundle;
+/** An appliance supplies execution evidence; it never occupies a human reviewer or decider role. */
+export declare function buildApplianceExportBundle(input: ApplianceExportBundleInput): ApplianceExportBundle;
+/** The bundle's identity: what the certificate's `claim.bundle` names. */
+export declare const bundleHash: (bundle: ResultBundle | ApplianceExportBundle) => string;

package/dist/bundle.js

@@ -0,0 +1,122 @@
+// spec/result-bundle.md: what a test run produced, hashed into the certificate. Never item text.
+import { jcsHash } from "@zanii/core";
+import { LEVELS, pickScheme } from "./certificate.js";
+import { staffRefusals } from "./impartiality.js";
+import { scoreCategory } from "./scoring.js";
+import { isDid, isInt, isIso, isSha, ms, SLUG, sortedUnique } from "./shared.js";
+import { applianceExecution, applianceExportIdentity } from "./appliance-execution.js";
+const CATEGORY = /^[a-z][a-z0-9_]{0,63}$/;
+const FINDING = /^[A-Z][A-Z0-9_]{0,63}$/;
+const CASE_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const PROFILE_REF = new RegExp(`^${SLUG.source.slice(1, -1)}/[1-9][0-9]*$`);
+const byKey = (k) => (a, b) => k(a) < k(b) ? -1 : k(a) > k(b) ? 1 : 0;
+function normalizedBundle(input, source) {
+    if (!PROFILE_REF.test(input.profile))
+        throw new Error("profile must be <slug>/<version>");
+    if (!LEVELS.includes(input.level))
+        throw new Error("level must be 1, 2 or 3");
+    const scheme = pickScheme(input.scheme, input.level);
+    if (!isSha(input.fingerprint))
+        throw new Error("fingerprint must be a fingerprint id");
+    if (!isSha(input.suite_snapshot))
+        throw new Error("suite_snapshot must be a sha256");
+    if (!isIso(input.started_at) || !isIso(input.ended_at) || ms(input.ended_at) < ms(input.started_at))
+        throw new Error("started_at and ended_at must be ISO UTC timestamps, in order");
+    const categories = sortedUnique(input.plan.categories);
+    if (!categories.length || categories.length !== input.plan.categories.length)
+        throw new Error("plan.categories must be distinct and not empty");
+    if (!categories.every((c) => CATEGORY.test(c)))
+        throw new Error("bad category id");
+    if (!isInt(input.plan.trials, 1, 1000))
+        throw new Error("plan.trials must be 1-1000");
+    const results = input.results.map((r) => {
+        const findings = sortedUnique(r.findings);
+        if (!findings.every((f) => FINDING.test(f)))
+            throw new Error(`bad finding code in ${r.category}`);
+        return {
+            category: r.category,
+            trials: r.trials,
+            passes: r.passes,
+            ...scoreCategory(r.passes, r.trials, r.threshold_ppm),
+            threshold_ppm: r.threshold_ppm,
+            findings,
+        };
+    });
+    results.sort(byKey((r) => r.category));
+    if (results.map((r) => r.category).join() !== categories.join())
+        throw new Error("results must have exactly one entry per planned category");
+    const evidence = input.evidence.map((e) => {
+        if (!CASE_ID.test(e.case_id) || !isSha(e.chain_head))
+            throw new Error("bad evidence entry");
+        const out = { case_id: e.case_id, chain_head: e.chain_head };
+        if (e.blackbox_session != null) {
+            if (!CASE_ID.test(e.blackbox_session))
+                throw new Error("bad blackbox_session");
+            out.blackbox_session = e.blackbox_session;
+        }
+        return out;
+    });
+    evidence.sort(byKey((e) => e.case_id));
+    if (new Set(evidence.map((e) => e.case_id)).size !== evidence.length)
+        throw new Error("evidence case_id values must be distinct");
+    const { testers, reviewer, decider } = input.staff;
+    if (!testers.length || !testers.every(isDid) || !source && !isDid(decider))
+        throw new Error("staff needs tester and decider DIDs");
+    if (!source && (reviewer === null ? input.level !== 1 : !isDid(reviewer)))
+        throw new Error("a reviewer DID is required above Level 1");
+    const refusals = source ? [] : staffRefusals({ testers: [...testers], reviewer, decider: decider }, []);
+    if (refusals.length)
+        throw new Error(`staffing refused: ${refusals.join(", ")}`);
+    const partial = input.partial ?? null;
+    if (partial !== null && (Object.keys(partial).length !== 1 || !isSha(partial.covered_by)))
+        throw new Error("partial must be {covered_by: <bundle hash>}");
+    const assessment = input.assessment == null ? null : assessmentOf(input.assessment, categories, scheme);
+    const execution = input.execution == null ? undefined : applianceExecution(input.execution), machine = source?.appliance ?? execution?.appliance;
+    if (machine && [...testers, reviewer, decider].includes(machine))
+        throw new Error("an appliance cannot be recorded as human staff");
+    const bundle = {
+        v: 1,
+        type: "certify.result-bundle",
+        scheme,
+        profile: input.profile,
+        level: input.level,
+        fingerprint: input.fingerprint,
+        plan: { categories, trials: input.plan.trials },
+        results,
+        evidence,
+        suite_snapshot: input.suite_snapshot,
+        staff: { testers: sortedUnique(testers), reviewer, decider: decider },
+        started_at: input.started_at,
+        ended_at: input.ended_at,
+        ...(partial ? { partial: { covered_by: partial.covered_by } } : {}),
+        ...(execution ? { execution } : {}),
+        ...(assessment ? { assessment } : {}),
+    };
+    if (source) {
+        const { partial: ignored, ...base } = bundle;
+        return { ...base, v: 2, phase: "undecided", staff: { testers: sortedUnique(testers), reviewer: null, decider: null }, execution: source };
+    }
+    return bundle;
+}
+function assessmentOf(a, categories, scheme) {
+    if (scheme !== "zanii-certify/0.4")
+        throw new Error("assessment needs scheme zanii-certify/0.4");
+    if (typeof a !== "object" || Object.keys(a).sort().join() !== "interface,trajectory_categories" || !Array.isArray(a.trajectory_categories)
+        || (a.interface !== "text" && a.interface !== "voice_text"))
+        throw new Error("assessment must be {trajectory_categories, interface}");
+    const workflow = sortedUnique(a.trajectory_categories);
+    if (workflow.length !== a.trajectory_categories.length || !workflow.every((c) => categories.includes(c)))
+        throw new Error("assessment.trajectory_categories must be distinct planned categories");
+    return { trajectory_categories: workflow, interface: a.interface };
+}
+/** Existing v1 output is unchanged unless explicit verified appliance provenance is supplied. */
+export function buildBundle(input) { return normalizedBundle(input); }
+/** An appliance supplies execution evidence; it never occupies a human reviewer or decider role. */
+export function buildApplianceExportBundle(input) {
+    if (!Array.isArray(input.testers) || input.testers.length > 64 || !Array.isArray(input.results) || input.results.length > 10000 || !Array.isArray(input.evidence) || input.evidence.length > 10000 || !Array.isArray(input.plan?.categories) || input.plan.categories.length > 10000)
+        throw new Error("appliance bundle exceeds its staff or result bounds");
+    const source = applianceExportIdentity(input.execution);
+    return normalizedBundle({ ...input, execution: null, partial: null, staff: { testers: input.testers, reviewer: null, decider: null } }, source);
+}
+/** The bundle's identity: what the certificate's `claim.bundle` names. */
+export const bundleHash = (bundle) => jcsHash(bundle);