@zanii/certify 0.0.0-stage → 0.5.0

package/dist/scheme-log.js

@@ -0,0 +1,266 @@
+// spec/scheme-log.md: the scheme owner's logs (boards, releases, licence status, release withdrawals,
+// body registers) as one checkpointed append-only log, like the status log (spec/witness.md):
+// signed tree heads, inclusion and consistency proofs, witness co-signatures, and an append
+// receipt binding each entry to the Zanii ledger receipt that anchors it.
+import { canonicalBytes, consistencyProof, createSTHAsync, inclusionProof, jcsHash, leafHash, merkleRoot, receiptHash, verifyChain, verifyConsistency, verifyInclusion, verifyReceiptSignature, verifySignedObject, verifySTH, } from "@zanii/core";
+import { verifyQuorum } from "@zanii/witness";
+import { isBoard, isRelease, isWithdrawal, verifyBoardLog, verifyReleaseLog, verifyWithdrawalLog } from "./board.js";
+import { verifyLicenceLog } from "./licence.js";
+import { isBodyRegister, verifyBodyRegisterLog } from "./register.js";
+import { isDid, isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { signerDid, signWith } from "./signer.js";
+import { signingIdentityReasons } from "./signing-identity.js";
+import { schemeHistoryReasons } from "./scheme-history.js";
+import { schemePrefixStatements } from "./scheme-merkle.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export const SCHEME_LOG_TYPES = ["certify.board", "certify.release", "certify.licence-status", "certify.release-withdrawal", "certify.body-register", "certify.board-transition"];
+const HEX32 = /^[0-9a-f]{64}$/;
+const hex = (b) => Buffer.from(b).toString("hex");
+const bytes = (h) => new Uint8Array(Buffer.from(h, "hex"));
+const leaves = (entries) => entries.map((e) => leafHash(canonicalBytes(e)));
+const rootOf = (entries) => `sha256:${hex(merkleRoot(leaves(entries)))}`;
+const hexList = (p) => Array.isArray(p) && p.every((h) => typeof h === "string" && HEX32.test(h));
+const known = (e) => isObj(e) && SCHEME_LOG_TYPES.includes(e.type);
+/** Section 2: the owner's signed tree head over the scheme log (leaf i = entry i). */
+export async function schemeCheckpoint(entries, ts, signer) {
+    if (!Array.isArray(entries) || entries.length === 0 || !entries.every(known))
+        throw new Error("the scheme log must be 1 or more scheme log entries");
+    if (!isIso(ts))
+        throw new Error("ts must be an ISO UTC timestamp");
+    return createSTHAsync({ logId: signerDid(signer), size: entries.length, root: rootOf(entries), ts }, signer.sign);
+}
+/** Section 2: the inclusion proof of entry `index` in the checkpoint over `entries`, hex. */
+export const schemeInclusionProof = (entries, index) => inclusionProof(index, leaves(entries)).map(hex);
+/** Section 2: the proof that the log over `entries` extends its first `fromSize` entries, hex. */
+export const schemeConsistencyProof = (entries, fromSize) => consistencyProof(fromSize, leaves(entries)).map(hex);
+const checkpointOk = (cp, owner) => isObj(cp) && verifySTH(cp) && (owner === undefined || cp.log_id === owner) && isInt(cp.size, 1, Number.MAX_SAFE_INTEGER) && isSha(cp.root);
+/** Section 2: one entry is at `index` of a checkpoint signed by the owner (a light client's check). */
+export function verifySchemeInclusion(entry, index, checkpoint, proof, opts = {}) {
+    const reasons = [];
+    if (opts.owner === undefined)
+        reasons.push("no trusted scheme owner supplied: the checkpoint signer was NOT checked");
+    if (!checkpointOk(checkpoint, opts.owner))
+        return { ok: false, reasons: [...reasons, "scheme checkpoint is not signed by the scheme owner"] };
+    const included = known(entry) && isInt(index, 0, checkpoint.size - 1) && hexList(proof) &&
+        verifyInclusion(leafHash(canonicalBytes(entry)), index, checkpoint.size, proof.map(bytes), bytes(checkpoint.root.slice(7)));
+    if (!included)
+        reasons.push("the entry is not in the scheme checkpoint at that index");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Section 3: the statement for entry `index` of `entries` (the server records it on the ledger). */
+export function schemeAppendStatement(entries, index, owner) {
+    if (!Array.isArray(entries) || !isInt(index, 0, entries.length - 1) || !known(entries[index]))
+        throw new Error("index is not an entry of the scheme log");
+    if (!isDid(owner))
+        throw new Error("owner must be a did:key");
+    const prefix = entries.slice(0, index + 1);
+    return { v: 1, type: "certify.scheme-append", log: owner, index, entry: jcsHash(entries[index]), size: index + 1, root: rootOf(prefix) };
+}
+/** Why a ledger receipt does not anchor `statement`; empty when it does. */
+function ledgerReasons(statement, receipt, anchoredAt) {
+    const r = isObj(receipt) ? receipt : null;
+    if (!r || !verifyReceiptSignature(r))
+        return ["ledger receipt signature is invalid"];
+    if (r.payload_hash !== jcsHash(statement) || r.payload_encoding !== "jcs")
+        return ["ledger receipt does not commit to the append"];
+    if (anchoredAt !== undefined && r.ts !== anchoredAt)
+        return ["append time is not the ledger receipt's"];
+    return [];
+}
+/** Section 3: the receipt's agent is delegated, at the receipt's time, by the owner's ledger identity. */
+const ledgerIdentity = (r, ledger) => Array.isArray(r.delegation) && isIso(r.ts) && verifyChain(r.delegation, { agentId: r.agent_id, expectedRoot: ledger, at: new Date(r.ts) }).ok;
+/** Section 3: the owner's append receipt for entry `index`, bound to the ledger receipt that anchors it. */
+export async function buildSchemeAppend(entries, index, ledgerReceipt, signer) {
+    const statement = schemeAppendStatement(entries, index, signerDid(signer));
+    return buildSchemeAppendFromStatement(statement, ledgerReceipt, signer);
+}
+/** The bounded equivalent when the caller maintains authenticated Merkle subtrees. */
+export async function buildSchemeAppendFromStatement(statement, ledgerReceipt, signer) {
+    if (!withinVerificationBudget(ledgerReceipt, { maxBytes: 524_288, maxNodes: 50_000 }))
+        throw new Error("scheme ledger receipt exceeds the verification budget");
+    if (!isObj(statement) || Object.keys(statement).length !== 7 || statement.v !== 1 || statement.type !== "certify.scheme-append"
+        || statement.log !== signerDid(signer) || !isInt(statement.index, 0, Number.MAX_SAFE_INTEGER - 1) || statement.size !== statement.index + 1
+        || !isSha(statement.entry) || !isSha(statement.root))
+        throw new Error("invalid scheme append statement");
+    const bad = ledgerReasons(statement, ledgerReceipt);
+    if (bad.length)
+        throw new Error(bad[0]);
+    if (!isIso(ledgerReceipt.ts))
+        throw new Error("the ledger receipt ts is not an ISO UTC timestamp");
+    return signWith({ ...statement, ledger_receipt: receiptHash(ledgerReceipt), anchored_at: ledgerReceipt.ts }, signer);
+}
+/** One append against the authenticated entry/tree prefix; no history arrays are needed. */
+export function verifySchemeAppend(statement, entry, append, receipt, opts = {}) {
+    const reasons = [];
+    if (!withinVerificationBudget(entry, { maxBytes: 1_048_576, maxNodes: 100_000 }) || !withinVerificationBudget(append, { maxBytes: 65_536, maxNodes: 10_000 })
+        || !withinVerificationBudget(receipt, { maxBytes: 524_288, maxNodes: 50_000 }))
+        return { ok: false, reasons: ["scheme append exceeds the verification budget"] };
+    if (!isObj(append) || Object.keys(append).length !== 11 || append.type !== "certify.scheme-append" || !verifySignedObject(append) || append.signer !== statement.log)
+        return { ok: false, reasons: ["entry has no append receipt signed by the scheme owner"] };
+    const { ledger_receipt, anchored_at, signer: _s, sig: _g, ...given } = append;
+    if (jcsHash(given) !== jcsHash(statement) || statement.entry !== jcsHash(entry))
+        reasons.push("the append receipt is not for this entry at this position");
+    if (!isIso(anchored_at) || opts.previousAt && ms(anchored_at) < ms(opts.previousAt))
+        reasons.push("the append time goes back");
+    if (opts.ledger && (isRelease(entry) || isWithdrawal(entry)) && isIso(anchored_at) && ms(entry.effective_from) < ms(anchored_at))
+        reasons.push("entry takes effect before it was appended");
+    if (!isObj(receipt) || ledger_receipt !== receiptHash(receipt))
+        reasons.push("its ledger receipt was not supplied");
+    else {
+        reasons.push(...ledgerReasons(statement, receipt, anchored_at));
+        if (opts.ledger && !ledgerIdentity(receipt, opts.ledger))
+            reasons.push("ledger receipt is not signed by the scheme owner's ledger identity");
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+const NOUN = { "certify.release": "release", "certify.release-withdrawal": "withdrawal", "certify.body-register": "body register" };
+const cosigShape = (c) => isObj(c) && typeof c.witnessed_log_id === "string" && isObj(c.cosignature) && typeof c.cosignature.log_id === "string";
+/**
+ * Section 4: the scheme log verifies: each kind of entry forms its own log (governance-board.md,
+ * licensing.md, body-register.md); the append rules hold in leaf order (each board-signed entry by
+ * the newest board appended before it, each later board taking effect after every board-signed
+ * entry before it); the checkpoint is the owner's over exactly these entries and extends every
+ * previous one; with `witness`, k trusted witnesses co-signed it; with `appends`, each entry has the
+ * owner's append receipt with append times never going back; with `ledgerReceipts`, each append is
+ * bound to its ledger receipt.
+ */
+export function verifySchemeLogs(input, opts = {}) {
+    const entries = Array.isArray(input?.entries) ? input.entries : [];
+    const out = (reasons, extra = {}) => {
+        const r = [...new Set(reasons)];
+        return { ok: r.length === 0, reasons: r, size: entries.length, anchored: 0, ...extra, ...(extra.canceled ? { canceled: r.length ? [] : extra.canceled } : {}) };
+    };
+    if (entries.length === 0)
+        return out(["the scheme log is empty"]);
+    const transitions = entries.some((e) => isObj(e) && e.type === "certify.board-transition");
+    if (transitions && (!withinVerificationBudget(input) || entries.length > 10_000))
+        return out(["transition-aware scheme history exceeds the verification budget"], { canceled: [] });
+    const reasons = [];
+    entries.forEach((e, i) => {
+        if (!known(e))
+            reasons.push(`entry ${i} is not a scheme log entry`);
+    });
+    const of = (t) => entries.filter((e) => isObj(e) && e.type === t);
+    const boards = of("certify.board");
+    const releases = of("certify.release");
+    const statuses = of("certify.licence-status");
+    const withdrawals = of("certify.release-withdrawal");
+    const registers = of("certify.body-register");
+    const prepared = transitions ? schemePrefixStatements(entries, opts.owner ?? "") : null;
+    const semantics = transitions ? schemeHistoryReasons(input, opts.owner, opts.statusIssuers, prepared) : null;
+    if (semantics)
+        reasons.push(...semantics.reasons);
+    if (!transitions) {
+        reasons.push(...verifyBoardLog(boards, opts).reasons);
+        if (releases.length)
+            reasons.push(...verifyReleaseLog(releases, boards, opts).reasons);
+        if (statuses.length)
+            reasons.push(...verifyLicenceLog(statuses, opts).reasons);
+        if (withdrawals.length)
+            reasons.push(...verifyWithdrawalLog(withdrawals, releases, boards, opts).reasons);
+        if (registers.length)
+            reasons.push(...verifyBodyRegisterLog(registers, boards, opts).reasons);
+        // the append rules, replayed in leaf order.
+        let newest = null;
+        const signedAt = [];
+        entries.forEach((e, i) => {
+            if (!isObj(e))
+                return;
+            const o = e;
+            const signed = isRelease(o) || isWithdrawal(o) || isBodyRegister(o);
+            if (isBoard(e)) {
+                if (newest !== null && signedAt.some((t) => !(ms(e.effective_from) > t)))
+                    reasons.push(`entry ${i}: the board does not take effect after every board-signed entry appended before it`);
+                newest = e;
+            }
+            else if (signed) {
+                if (newest === null)
+                    reasons.push(`entry ${i}: a ${NOUN[o.type]} is appended before any board`);
+                else if (o.board !== jcsHash(newest))
+                    reasons.push(`entry ${i}: the ${NOUN[o.type]} is not signed by the newest board when it was appended`);
+                signedAt.push(ms(o.effective_from));
+            }
+        });
+    }
+    const owner = opts.owner ?? (isBoard(boards[0]) ? boards[0].owner : undefined);
+    if (opts.statusIssuers !== undefined)
+        reasons.push(...signingIdentityReasons(owner, [], opts.statusIssuers));
+    const cp = input.checkpoint;
+    if (!checkpointOk(cp, owner))
+        reasons.push("scheme checkpoint is not signed by the scheme owner");
+    else if (cp.size !== entries.length || cp.root !== rootOf(entries))
+        reasons.push("scheme checkpoint is not over these entries");
+    for (const [n, p] of (Array.isArray(input.previous) ? input.previous : []).entries()) {
+        const old = isObj(p) ? p.checkpoint : null;
+        if (!checkpointOk(old, owner))
+            reasons.push(`previous checkpoint ${n} is not signed by the scheme owner`);
+        else if (!checkpointOk(cp, owner) || !hexList(p.proof) || old.size > cp.size ||
+            !verifyConsistency(old.size, cp.size, bytes(old.root.slice(7)), bytes(cp.root.slice(7)), p.proof.map(bytes)))
+            reasons.push(`the scheme log does not extend previous checkpoint ${n}`);
+    }
+    let witnesses;
+    if (input.witness) {
+        const w = input.witness;
+        if (!isInt(w.k, 1, 1000))
+            reasons.push("witness policy k must be an integer from 1");
+        else if (checkpointOk(cp, owner)) {
+            const cosigs = (Array.isArray(w.cosignatures) ? w.cosignatures : []).filter(cosigShape);
+            const q = verifyQuorum(cp, cosigs, { trusted: Array.isArray(w.trusted) ? [...w.trusted] : [], k: w.k });
+            witnesses = q.witnesses;
+            if (!q.ok)
+                reasons.push(`scheme checkpoint has ${q.witnesses.length} of the ${w.k} trusted witness co-signatures required`);
+        }
+    }
+    const extra = { ...(witnesses ? { witnesses } : {}), ...(semantics ? { canceled: semantics.canceled } : {}) };
+    if (input.appends === undefined)
+        return out(reasons, extra);
+    const appends = Array.isArray(input.appends) ? input.appends : [];
+    if (appends.length !== entries.length)
+        reasons.push(`${appends.length} append receipts for ${entries.length} entries`);
+    const receipts = new Map();
+    for (const r of Array.isArray(input.ledgerReceipts) ? input.ledgerReceipts : [])
+        if (isObj(r))
+            receipts.set(receiptHash(r), r);
+    const appended = [];
+    let anchored = 0;
+    let last = Number.NEGATIVE_INFINITY;
+    // section 3: the owner's ledger identity named by the newest board appended at or before each entry
+    let ledger;
+    entries.forEach((e, i) => {
+        if (isBoard(e) && typeof e.ledger === "string")
+            ledger = e.ledger;
+        const a = appends[i];
+        if (!isObj(a) || a.type !== "certify.scheme-append" || Object.keys(a).length !== 11 || !verifySignedObject(a) || (owner !== undefined && a.signer !== owner)) {
+            reasons.push(`entry ${i} has no append receipt signed by the scheme owner`);
+            return;
+        }
+        if (!known(e) || !owner)
+            return;
+        const statement = prepared?.[i] ?? schemeAppendStatement(entries, i, owner);
+        const { ledger_receipt, anchored_at, signer: _s, sig: _g, ...given } = a;
+        if (jcsHash(given) !== jcsHash(statement))
+            reasons.push(`entry ${i}: the append receipt is not for this entry at this position`);
+        if (!isIso(anchored_at) || !(ms(anchored_at) >= last))
+            reasons.push(`entry ${i}: the append time goes back`);
+        else
+            last = ms(anchored_at);
+        appended.push(String(anchored_at));
+        const o = e;
+        if (ledger && (isRelease(o) || isWithdrawal(o)) && isIso(anchored_at) && ms(o.effective_from) < ms(anchored_at))
+            reasons.push(`entry ${i}: the ${NOUN[o.type]} takes effect before it was appended`);
+        if (input.ledgerReceipts === undefined)
+            return;
+        const r = typeof ledger_receipt === "string" ? receipts.get(ledger_receipt) : undefined;
+        if (r === undefined) {
+            reasons.push(`entry ${i}: its ledger receipt was not supplied`);
+            return;
+        }
+        const bad = ledgerReasons(statement, r, anchored_at);
+        if (!bad.length && ledger && !ledgerIdentity(r, ledger))
+            bad.push("ledger receipt is not signed by the scheme owner's ledger identity");
+        reasons.push(...bad.map((x) => `entry ${i}: ${x}`));
+        if (!bad.length)
+            anchored++;
+    });
+    return out(reasons, { ...extra, anchored, appended });
+}

package/dist/scheme-merkle.d.ts

@@ -0,0 +1,2 @@
+import type { SchemeAppendStatement } from "./scheme-log.ts";
+export declare function schemePrefixStatements(entries: readonly unknown[], owner: string): SchemeAppendStatement[];

package/dist/scheme-merkle.js

@@ -0,0 +1,20 @@
+// One preparation for complete offline verification; the server uses persisted indexed nodes.
+import { canonicalBytes, jcsHash, leafHash, merkleRoot } from "@zanii/core";
+export function schemePrefixStatements(entries, owner) {
+    const frontier = [];
+    return entries.map((entry, index) => {
+        let level = 0, position = index, node = leafHash(canonicalBytes(entry));
+        while (position % 2 === 1) {
+            node = merkleRoot([frontier[level], node]);
+            frontier[level] = undefined;
+            position = Math.floor(position / 2);
+            level++;
+        }
+        frontier[level] = node;
+        let root;
+        for (const left of frontier)
+            if (left)
+                root = root ? merkleRoot([left, root]) : left;
+        return { v: 1, type: "certify.scheme-append", log: owner, index, entry: jcsHash(entry), size: index + 1, root: `sha256:${Buffer.from(root).toString("hex")}` };
+    });
+}

package/dist/scheme-text.d.ts

@@ -0,0 +1,25 @@
+export interface SchemeTextFile {
+    path: string;
+    text: string;
+}
+export interface SchemeTextBundle {
+    v: 1;
+    type: "certify.scheme-text";
+    scheme: string;
+    files: SchemeTextFile[];
+}
+export declare const SCHEME_TEXT_MAX_BYTES = 4194304;
+/** LF normalization is explicit; Unicode content is retained byte for byte otherwise. */
+export declare function buildSchemeTextBundle(input: {
+    scheme: string;
+    files: readonly SchemeTextFile[];
+}): SchemeTextBundle;
+/** The released file is these canonical JSON bytes; a digest alone is not board approval. */
+export declare function schemeTextBundleHash(doc: unknown): string;
+export declare function verifySchemeTextBundle(doc: unknown, expected: {
+    scheme: string;
+    sha256: string;
+}): {
+    ok: boolean;
+    reasons: string[];
+};

package/dist/scheme-text.js

@@ -0,0 +1,46 @@
+import { jcsHash } from "@zanii/core";
+import { isObj, isSha } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export const SCHEME_TEXT_MAX_BYTES = 4_194_304;
+const scheme = (value) => typeof value === "string" && /^zanii-certify\/(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$/.exec(value)?.[0] === value;
+const path = (value) => typeof value === "string" && /^[a-z0-9][a-z0-9._/-]{0,127}$/.exec(value)?.[0] === value && !value.endsWith("/") && value.split("/").every(part => part !== "" && part !== "." && part !== "..");
+const text = (value) => typeof value === "string" && value.length <= 524_288 && value.isWellFormed() && Buffer.byteLength(value, "utf8") <= 524_288 && !value.startsWith("\uFEFF") && !/[\x00-\x08\x0b-\x1f\x7f]/.test(value);
+function reasons(doc) {
+    if (!withinVerificationBudget(doc, { maxBytes: SCHEME_TEXT_MAX_BYTES, maxNodes: 1000, maxDepth: 4 }))
+        return ["scheme text exceeds its 4 MiB JSON budget"];
+    if (!isObj(doc) || Object.keys(doc).length !== 4 || doc.v !== 1 || doc.type !== "certify.scheme-text" || !scheme(doc.scheme) || !Array.isArray(doc.files) || doc.files.length < 1 || doc.files.length > 64)
+        return ["invalid scheme text bundle or file count"];
+    let previous = "";
+    for (const file of doc.files) {
+        if (!isObj(file) || Object.keys(file).length !== 2 || !path(file.path) || file.path <= previous || !text(file.text) || file.text.includes("\r"))
+            return ["scheme files must be sorted distinct relative paths and bounded UTF-8 text with LF endings"];
+        previous = file.path;
+    }
+    return [];
+}
+/** LF normalization is explicit; Unicode content is retained byte for byte otherwise. */
+export function buildSchemeTextBundle(input) {
+    if (!withinVerificationBudget(input, { maxBytes: SCHEME_TEXT_MAX_BYTES, maxNodes: 1000, maxDepth: 4 }) || !isObj(input) || Object.keys(input).length !== 2 || !scheme(input.scheme) || !Array.isArray(input.files) || input.files.length < 1 || input.files.length > 64)
+        throw new Error("invalid bounded scheme text input");
+    const files = input.files.map(file => { if (!isObj(file) || Object.keys(file).length !== 2 || !path(file.path) || typeof file.text !== "string")
+        throw new Error("invalid scheme file"); return { path: file.path, text: file.text.replace(/\r\n?/g, "\n") }; }).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const bundle = { v: 1, type: "certify.scheme-text", scheme: input.scheme, files }, bad = reasons(bundle);
+    if (bad.length)
+        throw new Error(bad[0]);
+    return bundle;
+}
+/** The released file is these canonical JSON bytes; a digest alone is not board approval. */
+export function schemeTextBundleHash(doc) { const bad = reasons(doc); if (bad.length)
+    throw new Error(bad[0]); return jcsHash(doc); }
+export function verifySchemeTextBundle(doc, expected) {
+    if (!isObj(expected) || Object.keys(expected).length !== 2 || !scheme(expected.scheme) || typeof expected.sha256 !== "string" || expected.sha256.length !== 71 || !isSha(expected.sha256))
+        return { ok: false, reasons: ["independently selected scheme and released digest are required"] };
+    const bad = reasons(doc);
+    if (bad.length)
+        return { ok: false, reasons: bad };
+    if (doc.scheme !== expected.scheme)
+        bad.push("scheme text names another scheme version");
+    if (jcsHash(doc) !== expected.sha256)
+        bad.push("scheme text does not match the released content digest");
+    return { ok: bad.length === 0, reasons: bad };
+}

package/dist/scheme-timing.d.ts

@@ -0,0 +1,16 @@
+export interface SchemeTimingPolicy {
+    v: 1;
+    type: "certify.scheme-timing-policy";
+    max_future_s: number;
+}
+export type SchemeTimingCode = "SCHEME_TIMING_POLICY" | "SCHEME_EFFECTIVE_INVALID" | "SCHEME_EFFECTIVE_PAST" | "SCHEME_EFFECTIVE_TOO_FAR";
+export interface SchemeTimingCheck {
+    ok: boolean;
+    codes: SchemeTimingCode[];
+    reasons: string[];
+}
+/** Check again under the append lock using the trusted commit clock. No clock skew allowance. */
+export declare function verifySchemeEffectiveTime(doc: unknown, opts: {
+    policy: unknown;
+    now: string;
+}): SchemeTimingCheck;

package/dist/scheme-timing.js

@@ -0,0 +1,22 @@
+// Admission policy for NEW owner submissions, never a reinterpretation of signed history.
+import { isInt, isIso, isObj, ms } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const TYPES = ["certify.board", "certify.release", "certify.release-withdrawal", "certify.body-register"];
+/** Check again under the append lock using the trusted commit clock. No clock skew allowance. */
+export function verifySchemeEffectiveTime(doc, opts) {
+    const codes = [], reasons = [];
+    const fail = (code, reason) => { codes.push(code); reasons.push(reason); };
+    const p = opts?.policy;
+    if (!isObj(p) || Object.keys(p).length !== 3 || p.v !== 1 || p.type !== "certify.scheme-timing-policy" || !isInt(p.max_future_s, 1, 2_592_000))
+        fail("SCHEME_TIMING_POLICY", "a closed scheme timing policy with max_future_s from 1 to 2592000 is required");
+    if (!isIso(opts?.now) || !withinVerificationBudget(doc, { maxBytes: 1_048_576, maxNodes: 100_000 }) || !isObj(doc) || !TYPES.includes(doc.type) || !isIso(doc.effective_from))
+        fail("SCHEME_EFFECTIVE_INVALID", "a supported scheme entry, effective_from and trusted reference time are required");
+    if (!codes.length && isObj(doc) && isObj(p)) {
+        const delta = ms(doc.effective_from) - ms(opts.now);
+        if (delta < 0)
+            fail("SCHEME_EFFECTIVE_PAST", "effective_from must not precede the protected append time");
+        else if (delta > Number(p.max_future_s) * 1000)
+            fail("SCHEME_EFFECTIVE_TOO_FAR", "effective_from exceeds the scheme timing policy's future limit");
+    }
+    return { ok: codes.length === 0, codes, reasons };
+}

package/dist/scheme-transition.d.ts

@@ -0,0 +1,47 @@
+import { type BodySignature } from "./board.ts";
+import { type SchemeAppendStatement } from "./scheme-log.ts";
+import { type Signer } from "./signer.ts";
+export interface SchemeTransitionBody {
+    v: 1;
+    type: "certify.board-transition";
+    owner: string;
+    from: string;
+    to: string;
+    epoch: number;
+    at: string;
+    cancel: string[];
+}
+export type SchemeTransition = SchemeTransitionBody & {
+    signatures: BodySignature[];
+};
+export interface SchemeTransitionAnchor {
+    statement: SchemeAppendStatement;
+    append: unknown;
+    receipt: unknown;
+}
+export interface SchemeTransitionContext {
+    owner: string;
+    /** Authenticated newest board, exact proposed next board and next scheme-log position. */
+    board: unknown;
+    nextBoard: unknown;
+    index: number;
+    previousAt: string;
+    /** ONLY authenticated prefix entries. Canceled records remain in this history. */
+    entry: (hash: string) => unknown;
+    anchor: SchemeTransitionAnchor;
+    nextAnchor: SchemeTransitionAnchor;
+}
+export declare function buildSchemeTransition(fields: Omit<SchemeTransitionBody, "v" | "type">, signers: readonly Signer[]): Promise<SchemeTransition>;
+/** Strict effect verification: both authenticated append receipts are mandatory. */
+export declare function verifySchemeTransition(doc: unknown, c: SchemeTransitionContext): {
+    ok: boolean;
+    reasons: string[];
+    canceled: string[];
+};
+/** Admission only. This does NOT authorize cancellation or a new board before anchoring. */
+export declare function verifySchemeTransitionProposal(doc: unknown, c: Omit<SchemeTransitionContext, "anchor" | "nextAnchor"> & {
+    now: string;
+}): {
+    ok: boolean;
+    reasons: string[];
+};

package/dist/scheme-transition.js

@@ -0,0 +1,101 @@
+// An explicit anchored cancellation of future entries, followed immediately by one exact board.
+import { jcsHash } from "@zanii/core";
+import { boardFieldError, bodySignature, isBoard, isRelease, isWithdrawal, releaseFieldError, signersOf, withSignatures, withdrawalFieldError } from "./board.js";
+import { isBodyRegister, registerFieldError } from "./register.js";
+import { verifySchemeAppend } from "./scheme-log.js";
+import { isDid, isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import {} from "./signer.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+function fieldError(d) {
+    if (!isObj(d) || Object.keys(d).length !== 9 || d.v !== 1 || d.type !== "certify.board-transition")
+        return "not a closed board-transition (v1)";
+    if (!isDid(d.owner) || !isSha(d.from) || !isSha(d.to) || !isInt(d.epoch, 1, Number.MAX_SAFE_INTEGER) || !isIso(d.at))
+        return "invalid transition authority, board binding, epoch or time";
+    if (!Array.isArray(d.cancel) || d.cancel.length < 1 || d.cancel.length > 100 || !d.cancel.every((h, i, xs) => isSha(h) && (i === 0 || xs[i - 1] < h)))
+        return "cancel must contain 1 to 100 sorted distinct entry hashes";
+    return null;
+}
+export async function buildSchemeTransition(fields, signers) {
+    if (!withinVerificationBudget(fields, { maxBytes: 32_768, maxNodes: 1_000 }) || !Array.isArray(signers) || signers.length < 1 || signers.length > 65)
+        throw new Error("transition exceeds its signing budget");
+    const body = { v: 1, type: "certify.board-transition", owner: fields.owner, from: fields.from, to: fields.to, epoch: fields.epoch, at: fields.at, cancel: Array.isArray(fields.cancel) ? [...fields.cancel] : fields.cancel };
+    const err = fieldError({ ...body, signatures: [] });
+    if (err)
+        throw new Error(err);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+/** The caller must atomically accept this entry and its immediately following exact next board. */
+function transitionCheck(doc, c, proposalNow) {
+    const reasons = [];
+    const out = () => ({ ok: reasons.length === 0, reasons, canceled: reasons.length || !isObj(doc) ? [] : [...doc.cancel] });
+    if (!withinVerificationBudget(doc, { maxBytes: 65_536, maxNodes: 3_000 }) || !withinVerificationBudget(c?.board, { maxBytes: 65_536, maxNodes: 3_000 }) || !withinVerificationBudget(c?.nextBoard, { maxBytes: 65_536, maxNodes: 3_000 }) || proposalNow === undefined && (!withinVerificationBudget(c?.anchor, { maxBytes: 655_360, maxNodes: 60_000 }) || !withinVerificationBudget(c?.nextAnchor, { maxBytes: 655_360, maxNodes: 60_000 })))
+        return { ok: false, reasons: ["board transition exceeds the verification budget"], canceled: [] };
+    const err = fieldError(doc);
+    if (err || !isObj(doc))
+        return { ok: false, reasons: [err], canceled: [] };
+    const b = c?.board, next = c?.nextBoard;
+    if (!isDid(c?.owner) || doc.owner !== c.owner || !isBoard(b) || boardFieldError(b) || b.owner !== c.owner || !isBoard(next) || boardFieldError(next) || next.owner !== c.owner)
+        return { ok: false, reasons: ["trusted outgoing and next boards are required"], canceled: [] };
+    if (doc.from !== jcsHash(b) || doc.to !== jcsHash(next) || doc.epoch !== next.seq || next.seq !== Number(b.seq) + 1 || next.prev !== doc.from)
+        reasons.push("transition is not bound to the exact outgoing and next board epoch");
+    if (!isDid(b.ledger) || next.ledger !== b.ledger)
+        reasons.push("transition requires the same explicit ledger identity on both boards");
+    if (!(ms(next.effective_from) > ms(b.effective_from)))
+        reasons.push("next board does not take effect after the outgoing board");
+    if (!isIso(c.previousAt))
+        reasons.push("the authenticated previous append time is required");
+    const allowed = [c.owner, ...b.members];
+    const signed = signersOf(doc, allowed), members = signed.signers.filter((s) => b.members.includes(s));
+    if (!signed.wellFormed || !signed.signers.includes(c.owner) || members.length < Number(b.threshold))
+        reasons.push("transition requires the owner and outgoing board threshold signatures");
+    const nextSigned = signersOf(next, b.members);
+    if (!nextSigned.wellFormed || nextSigned.signers.length < Number(b.threshold))
+        reasons.push("next board is not signed by the outgoing threshold");
+    let anchoredAt = proposalNow ?? "";
+    if (proposalNow !== undefined && (!isIso(proposalNow) || ms(proposalNow) < ms(doc.at) || ms(proposalNow) - ms(doc.at) > 60_000))
+        reasons.push("transition proposal must be within 60 seconds after its authorization time");
+    if (proposalNow === undefined) {
+        for (const [offset, target, a] of [[0, doc, c.anchor], [1, next, c.nextAnchor]]) {
+            if (!a || !isObj(a.statement) || Object.keys(a.statement).length !== 7 || a.statement.v !== 1 || a.statement.type !== "certify.scheme-append" || !isInt(c.index, 1, Number.MAX_SAFE_INTEGER - 2) || a.statement?.index !== c.index + offset || a.statement?.size !== c.index + offset + 1 || a.statement?.log !== c.owner || a.statement?.entry !== jcsHash(target) || !isSha(a.statement?.root))
+                reasons.push("authenticated transition and next-board appends at the exact prefix positions are required");
+            else
+                reasons.push(...verifySchemeAppend(a.statement, target, a.append, a.receipt, { ledger: b.ledger }).reasons);
+            if (!isObj(a?.receipt) || a.receipt.v !== 1 || a.receipt.action !== "certify.scheme-append" || a.receipt.target !== `certify.scheme/${c.index + offset}`)
+                reasons.push("transition anchor receipt has another purpose or target");
+            const time = isObj(a?.append) ? a.append.anchored_at : undefined;
+            if (!isIso(time) || ms(time) < ms(doc.at) || ms(time) - ms(doc.at) > 60_000 || ms(time) < ms(c.previousAt) || anchoredAt && ms(time) < ms(anchoredAt))
+                reasons.push("transition anchors must be ordered within 60 seconds after their authorization time");
+            if (isIso(time))
+                anchoredAt = time;
+        }
+    }
+    if (!isIso(anchoredAt) || ms(next.effective_from) < ms(anchoredAt))
+        reasons.push("next board takes effect before the authenticated transition anchors");
+    for (const hash of doc.cancel) {
+        let entry;
+        try {
+            entry = c.entry(hash);
+        }
+        catch {
+            reasons.push("transition prefix lookup failed");
+            break;
+        }
+        if (!withinVerificationBudget(entry, { maxBytes: 1_048_576, maxNodes: 100_000 }) || !isObj(entry)) {
+            reasons.push("cancellation target is absent from the authenticated prefix");
+            continue;
+        }
+        const invalid = isRelease(entry) ? releaseFieldError(entry) : isWithdrawal(entry) ? withdrawalFieldError(entry) : isBodyRegister(entry) ? registerFieldError(entry) : "not cancellable";
+        if (invalid || jcsHash(entry) !== hash || entry.board !== doc.from)
+            reasons.push("cancellation target is not an outgoing-board release, withdrawal or register");
+        if (!isIso(anchoredAt) || !(ms(entry.effective_from) > ms(anchoredAt)))
+            reasons.push("cancellation target is already effective at the authenticated transition anchor");
+    }
+    return out();
+}
+/** Strict effect verification: both authenticated append receipts are mandatory. */
+export function verifySchemeTransition(doc, c) { return transitionCheck(doc, c); }
+/** Admission only. This does NOT authorize cancellation or a new board before anchoring. */
+export function verifySchemeTransitionProposal(doc, c) {
+    const { ok, reasons } = transitionCheck(doc, c, c?.now ?? "");
+    return { ok, reasons };
+}

package/dist/scoring.d.ts

@@ -0,0 +1,35 @@
+export type Verdict = "pass" | "fail" | "inconclusive";
+export interface CategoryScore {
+    rate_ppm: number;
+    low_ppm: number;
+    high_ppm: number;
+    verdict: Verdict;
+}
+/** Section 1: the 95% Wilson range of `passes` in `trials`, judged against `thresholdPpm`. */
+export declare function scoreCategory(passes: number, trials: number, thresholdPpm: number): CategoryScore;
+export interface ScoredResult {
+    category: string;
+    trials: number;
+    threshold_ppm: number;
+    verdict: Verdict;
+}
+export interface ProfileCategoryRule {
+    id: string;
+    required_levels: number[];
+    min_trials: number;
+    threshold_ppm: number;
+}
+export interface Overall {
+    pass: boolean;
+    /** Codes `<RULE>:<category>` (or `LEVEL_NOT_IN_PROFILE`), sorted. Empty on a pass. */
+    reasons: string[];
+}
+/**
+ * Section 2: pass only when the level is in the profile and every category the profile requires
+ * at that level is present, passes, ran at least min_trials and was judged at a threshold no
+ * lower than the profile's.
+ */
+export declare function overallVerdict(results: readonly ScoredResult[], profile: {
+    levels: number[];
+    categories: readonly ProfileCategoryRule[];
+}, level: number): Overall;

package/dist/scoring.js

@@ -0,0 +1,50 @@
+// spec/scoring.md: per-category verdicts from repeated trials, and the overall pass rule.
+import { successRange } from "@zanii/blackbox";
+import { isInt } from "./shared.js";
+/** Section 1: the 95% Wilson range of `passes` in `trials`, judged against `thresholdPpm`. */
+export function scoreCategory(passes, trials, thresholdPpm) {
+    if (!isInt(trials, 1, 1_000_000))
+        throw new Error("trials must be an integer 1-1000000");
+    if (!isInt(passes, 0, trials))
+        throw new Error("passes must be an integer 0-trials");
+    if (!isInt(thresholdPpm, 0, 1_000_000))
+        throw new Error("threshold_ppm must be 0-1000000");
+    const [low, high] = successRange(passes, trials);
+    const verdict = low >= thresholdPpm ? "pass" : high < thresholdPpm ? "fail" : "inconclusive";
+    return {
+        rate_ppm: Math.floor((passes * 1_000_000) / trials),
+        low_ppm: low,
+        high_ppm: high,
+        verdict,
+    };
+}
+/**
+ * Section 2: pass only when the level is in the profile and every category the profile requires
+ * at that level is present, passes, ran at least min_trials and was judged at a threshold no
+ * lower than the profile's.
+ */
+export function overallVerdict(results, profile, level) {
+    const reasons = [];
+    if (!profile.levels.includes(level))
+        reasons.push("LEVEL_NOT_IN_PROFILE");
+    const by = new Map(results.map((r) => [r.category, r]));
+    for (const c of profile.categories) {
+        if (!c.required_levels.includes(level))
+            continue;
+        const r = by.get(c.id);
+        if (!r) {
+            reasons.push(`CATEGORY_MISSING:${c.id}`);
+            continue;
+        }
+        if (r.trials < c.min_trials)
+            reasons.push(`TOO_FEW_TRIALS:${c.id}`);
+        if (r.threshold_ppm < c.threshold_ppm)
+            reasons.push(`THRESHOLD_BELOW_PROFILE:${c.id}`);
+        if (r.verdict === "fail")
+            reasons.push(`CATEGORY_FAILED:${c.id}`);
+        if (r.verdict === "inconclusive")
+            reasons.push(`CATEGORY_INCONCLUSIVE:${c.id}`);
+    }
+    reasons.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return { pass: reasons.length === 0, reasons };
+}