@zanii/certify 0.0.0-stage → 0.6.0

package/dist/scheme-authority.d.ts

@@ -0,0 +1,5 @@
+import { type SchemeLogsInput } from "./scheme-log.ts";
+export declare function schemeAuthority(log: SchemeLogsInput, owner: string | undefined, groups: Record<string, readonly unknown[]>): {
+    reasons: string[];
+    canceled: Set<string>;
+};

package/dist/scheme-authority.js

@@ -0,0 +1,15 @@
+// Optional complete, checkpoint-authenticated context for standalone authority consumers.
+import { jcsHash } from "@zanii/core";
+import { verifySchemeLogs } from "./scheme-log.js";
+import { isObj } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export function schemeAuthority(log, owner, groups) {
+    if (!withinVerificationBudget({ log, groups }) || !isObj(log) || Object.keys(log).some(k => !["entries", "checkpoint", "previous", "witness", "appends", "ledgerReceipts"].includes(k)) || !Array.isArray(log?.entries) || log.entries.length > 10_000)
+        return { reasons: ["scheme authority context exceeds the verification budget"], canceled: new Set() };
+    const checked = verifySchemeLogs(log, { owner }), reasons = [...checked.reasons];
+    for (const [type, rows] of Object.entries(groups)) {
+        if (!Array.isArray(rows) || jcsHash(rows) !== jcsHash(log.entries.filter(e => isObj(e) && e.type === type)))
+            reasons.push(`supplied ${type} history differs from the authenticated scheme log`);
+    }
+    return { reasons, canceled: new Set(reasons.length ? [] : checked.canceled ?? []) };
+}

package/dist/scheme-entry.d.ts

@@ -0,0 +1,25 @@
+import { type LicenceState } from "./licence.ts";
+export declare const MAX_SCHEME_ENTRY_BYTES = 1048576;
+export interface SchemeEntryContext {
+    owner: string;
+    /** Already authenticated newest board and the head of this entry's type. */
+    board: Record<string, unknown> | null;
+    head: {
+        size: number;
+        hash: string;
+        effective_at: string | null;
+    } | null;
+    maxSignedEffective: string | null;
+    release: (hash: string) => Record<string, unknown> | undefined;
+    released: (subject: string) => boolean;
+    withdrawn: (release: string) => boolean;
+    licenceState: (hash: string) => LicenceState;
+    statusIssuers?: readonly string[];
+}
+export interface SchemeEntryCheck {
+    ok: boolean;
+    reasons: string[];
+    effectiveAt?: string;
+    licenceState?: LicenceState;
+}
+export declare function verifySchemeEntry(doc: unknown, c: SchemeEntryContext): SchemeEntryCheck;

package/dist/scheme-entry.js

@@ -0,0 +1,85 @@
+// One authenticated extension of a previously verified semantic prefix. The caller commits the
+// entry and its returned state atomically; lookups must contain ONLY that verified prefix.
+import { jcsHash, verifySignedObject } from "@zanii/core";
+import { boardFieldError, boardSignedReasons, isBoard, isRelease, isWithdrawal, releaseFieldError, signersOf, subjectKey, withdrawalFieldError } from "./board.js";
+import { licenceStatusFieldError } from "./licence.js";
+import { isBodyRegister, registerFieldError } from "./register.js";
+import { isObj, ms } from "./shared.js";
+import { signingIdentityReasons } from "./signing-identity.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export const MAX_SCHEME_ENTRY_BYTES = 1_048_576;
+export function verifySchemeEntry(doc, c) {
+    const reasons = [];
+    const out = (extra = {}) => ({ ok: reasons.length === 0, reasons, ...extra });
+    if (!withinVerificationBudget(doc, { maxBytes: MAX_SCHEME_ENTRY_BYTES, maxNodes: 100_000 }))
+        return { ok: false, reasons: ["scheme entry exceeds the JSON verification budget"] };
+    if (!isObj(doc))
+        return { ok: false, reasons: ["not a scheme log entry"] };
+    const board = Boolean(isBoard(doc)), release = Boolean(isRelease(doc)), withdrawal = Boolean(isWithdrawal(doc)), register = Boolean(isBodyRegister(doc));
+    const status = doc.v === 1 && doc.type === "certify.licence-status" && Object.keys(doc).length === ("for_cause" in doc || "effective_at" in doc ? 12 : 10);
+    if (!board && !release && !withdrawal && !register && !status)
+        return { ok: false, reasons: ["not a scheme log entry (v1)"] };
+    if (c.statusIssuers !== undefined)
+        reasons.push(...signingIdentityReasons(c.owner, [], c.statusIssuers));
+    const err = board ? boardFieldError(doc) : release ? releaseFieldError(doc) : withdrawal ? withdrawalFieldError(doc) : register ? registerFieldError(doc) : licenceStatusFieldError(doc);
+    if (err) {
+        reasons.push(`entry is malformed: ${err}`);
+        return out();
+    }
+    const count = c.head?.size ?? 0;
+    if (!Number.isSafeInteger(count) || count < 0 || doc.seq !== count)
+        reasons.push(`entry is not at position ${count}`);
+    if (doc.prev !== (c.head?.hash ?? null))
+        reasons.push("entry does not name the previous entry of its type");
+    const effectiveAt = (status ? doc.at : doc.effective_from);
+    if (c.head?.effective_at && !(board || register ? ms(effectiveAt) > ms(c.head.effective_at) : ms(effectiveAt) >= ms(c.head.effective_at)))
+        reasons.push(board ? "board does not take effect after the previous board" : register ? "register does not take effect after the previous register" : "entry takes effect before the previous entry");
+    if (board) {
+        if (doc.owner !== c.owner)
+            reasons.push("the board log is not the trusted scheme owner's");
+        if (count && !c.board)
+            reasons.push("the authenticated previous board is missing");
+        if (c.maxSignedEffective && !(ms(effectiveAt) > ms(c.maxSignedEffective)))
+            reasons.push("the board does not take effect after every board-signed entry appended before it");
+        const allowed = count === 0 ? [c.owner] : (c.board?.members ?? []);
+        const need = count === 0 ? 1 : Number(c.board?.threshold ?? 1);
+        const signatures = signersOf(doc, allowed);
+        if (!signatures.wellFormed)
+            reasons.push("board carries a signature that is malformed, invalid or not by an authorised signer");
+        if (signatures.signers.length < need)
+            reasons.push(`board is signed by ${signatures.signers.length} of the ${need} previous board members required`);
+    }
+    else if (status) {
+        if (!verifySignedObject(doc) || doc.signer !== c.owner)
+            reasons.push("licence status entry is not signed by the scheme owner");
+        const previous = c.licenceState(doc.licence);
+        const allowed = doc.action === "suspend" ? previous === "active" : doc.action === "reinstate" ? previous === "suspended" : previous !== "withdrawn";
+        if (!allowed)
+            reasons.push(`entry cannot ${String(doc.action)} a licence that is ${previous}`);
+        return out({ effectiveAt, licenceState: doc.action === "suspend" ? "suspended" : doc.action === "reinstate" ? "active" : "withdrawn" });
+    }
+    else {
+        if (!c.board)
+            reasons.push("a board-signed entry is appended before any board");
+        else if (doc.board !== jcsHash(c.board))
+            reasons.push("entry is not signed by the newest board when it was appended");
+        else
+            reasons.push(...boardSignedReasons(doc, [c.board], release ? "release" : withdrawal ? "withdrawal" : "body register"));
+        if (release && c.released(subjectKey(doc.subject)))
+            reasons.push(`entry releases ${subjectKey(doc.subject)} again`);
+        if (withdrawal) {
+            const prior = c.release(doc.release);
+            if (!prior)
+                reasons.push("withdrawal names a release that is not in the release log");
+            else {
+                if (subjectKey(prior.subject) !== subjectKey(doc.subject))
+                    reasons.push("withdrawal subject is not the release's subject");
+                if (!(ms(effectiveAt) >= ms(prior.effective_from)))
+                    reasons.push("withdrawal takes effect before the release");
+            }
+            if (c.withdrawn(doc.release))
+                reasons.push("withdrawal withdraws a release again");
+        }
+    }
+    return out({ effectiveAt });
+}

package/dist/scheme-history.d.ts

@@ -0,0 +1,5 @@
+import { type SchemeAppendStatement, type SchemeLogsInput } from "./scheme-log.ts";
+export declare function schemeHistoryReasons(input: SchemeLogsInput, owner: string | undefined, statusIssuers?: readonly string[], prepared?: readonly SchemeAppendStatement[]): {
+    reasons: string[];
+    canceled: string[];
+};

package/dist/scheme-history.js

@@ -0,0 +1,87 @@
+// Transition-aware semantic replay. The enclosing verifier authenticates the final checkpoint.
+import { jcsHash, receiptHash } from "@zanii/core";
+import {} from "./licence.js";
+import { verifySchemeEntry } from "./scheme-entry.js";
+import {} from "./scheme-log.js";
+import { schemePrefixStatements } from "./scheme-merkle.js";
+import { verifySchemeTransition } from "./scheme-transition.js";
+import { isObj, ms } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export function schemeHistoryReasons(input, owner, statusIssuers, prepared) {
+    if (!owner || !Array.isArray(input.entries) || input.entries.length > 10_000 || !withinVerificationBudget(input))
+        return { reasons: ["transition-aware scheme history needs a trusted owner and at most 10000 bounded entries"], canceled: [] };
+    const reasons = [], canceled = new Set(), records = new Map();
+    const heads = new Map(), states = new Map();
+    const withdrawals = new Map();
+    const subjects = new Set();
+    let board = null, maximum = null;
+    const receipts = new Map((Array.isArray(input.ledgerReceipts) ? input.ledgerReceipts : []).filter(isObj).map((r) => [receiptHash(r), r]));
+    const statements = prepared ?? schemePrefixStatements(input.entries, owner);
+    const active = (hash) => canceled.has(hash) ? undefined : records.get(hash);
+    const withdrawn = (hash) => { const digest = withdrawals.get(hash); return digest !== undefined && !canceled.has(digest); };
+    const rebuildEffective = () => {
+        maximum = null;
+        for (const [type, head] of heads) {
+            if (!["certify.release", "certify.release-withdrawal", "certify.body-register"].includes(type))
+                continue;
+            head.effective_at = null;
+        }
+        for (const [hash, e] of records)
+            if (!canceled.has(hash) && ["certify.release", "certify.release-withdrawal", "certify.body-register"].includes(e.type)) {
+                const at = e.effective_from;
+                if (!maximum || ms(at) > ms(maximum))
+                    maximum = at;
+                heads.get(e.type).effective_at = at;
+            }
+    };
+    const anchor = (index) => {
+        const append = input.appends?.[index];
+        const receipt = isObj(append) ? receipts.get(append.ledger_receipt) : undefined;
+        return statements[index] ? { statement: statements[index], append, receipt } : undefined;
+    };
+    for (let i = 0; i < input.entries.length; i++) {
+        const e = input.entries[i];
+        if (!isObj(e)) {
+            reasons.push(`entry ${i} is not a scheme entry`);
+            break;
+        }
+        if (e.type === "certify.board-transition") {
+            const next = input.entries[i + 1];
+            const previous = input.appends?.[i - 1];
+            const checked = verifySchemeTransition(e, { owner, board, nextBoard: next, index: i, previousAt: isObj(previous) ? previous.anchored_at : "", entry: active, anchor: anchor(i), nextAnchor: i + 1 < input.entries.length ? anchor(i + 1) : undefined });
+            reasons.push(...checked.reasons.map((r) => `entry ${i}: ${r}`));
+            if (!checked.ok)
+                break;
+            for (const hash of checked.canceled)
+                canceled.add(hash);
+            // A canceled release cannot leave an uncanceled withdrawal referring to it.
+            for (const [hash, prior] of records)
+                if (!canceled.has(hash) && prior.type === "certify.release-withdrawal" && canceled.has(prior.release))
+                    reasons.push(`entry ${i}: dependent future withdrawal must be explicitly canceled with its release`);
+            rebuildEffective();
+            records.set(jcsHash(e), e);
+            continue;
+        }
+        const check = verifySchemeEntry(e, { owner, board, head: heads.get(e.type) ?? null, maxSignedEffective: maximum, statusIssuers,
+            release: active, released: (subject) => subjects.has(subject), withdrawn, licenceState: (hash) => states.get(hash) ?? "active" });
+        reasons.push(...check.reasons.map((r) => `entry ${i}: ${r}`));
+        if (!check.ok)
+            break;
+        const hash = jcsHash(e), type = e.type;
+        records.set(hash, e);
+        heads.set(type, { size: Number(e.seq) + 1, hash, effective_at: check.effectiveAt });
+        if (type === "certify.board")
+            board = e;
+        if (type === "certify.release") {
+            const s = e.subject;
+            subjects.add(`${s.kind} ${s.ref}`);
+        }
+        if (type === "certify.release-withdrawal")
+            withdrawals.set(e.release, hash);
+        if (type === "certify.licence-status")
+            states.set(e.licence, check.licenceState);
+        if (["certify.release", "certify.release-withdrawal", "certify.body-register"].includes(type) && (!maximum || ms(check.effectiveAt) > ms(maximum)))
+            maximum = check.effectiveAt;
+    }
+    return { reasons, canceled: reasons.length ? [] : [...canceled].sort() };
+}

package/dist/scheme-log.d.ts

@@ -0,0 +1,98 @@
+import { type Receipt, type SignedTreeHead } from "@zanii/core";
+import { type Signer } from "./signer.ts";
+export declare const SCHEME_LOG_TYPES: readonly ["certify.board", "certify.release", "certify.licence-status", "certify.release-withdrawal", "certify.body-register", "certify.board-transition"];
+/** Section 2: the owner's signed tree head over the scheme log (leaf i = entry i). */
+export declare function schemeCheckpoint(entries: readonly unknown[], ts: string, signer: Signer): Promise<SignedTreeHead>;
+/** Section 2: the inclusion proof of entry `index` in the checkpoint over `entries`, hex. */
+export declare const schemeInclusionProof: (entries: readonly unknown[], index: number) => string[];
+/** Section 2: the proof that the log over `entries` extends its first `fromSize` entries, hex. */
+export declare const schemeConsistencyProof: (entries: readonly unknown[], fromSize: number) => string[];
+/** Section 2: one entry is at `index` of a checkpoint signed by the owner (a light client's check). */
+export declare function verifySchemeInclusion(entry: unknown, index: number, checkpoint: unknown, proof: unknown, opts?: {
+    owner?: string;
+}): {
+    ok: boolean;
+    reasons: string[];
+};
+/** Section 3: what the ledger receipt of an append commits to (`payload_hash` = jcsHash of it, `payload_encoding: jcs`). */
+export interface SchemeAppendStatement {
+    v: 1;
+    type: "certify.scheme-append";
+    /** The scheme owner's DID, the log id. */
+    log: string;
+    index: number;
+    /** jcsHash of the entry appended. */
+    entry: string;
+    /** The log after the append: index + 1 entries and their Merkle root. */
+    size: number;
+    root: string;
+}
+export type SchemeAppend = SchemeAppendStatement & {
+    /** receiptHash of the Zanii ledger receipt that anchors the append. */
+    ledger_receipt: string;
+    /** The ledger receipt's `ts`: the append time. */
+    anchored_at: string;
+    signer: string;
+    sig: string;
+};
+/** Section 3: the statement for entry `index` of `entries` (the server records it on the ledger). */
+export declare function schemeAppendStatement(entries: readonly unknown[], index: number, owner: string): SchemeAppendStatement;
+/** Section 3: the owner's append receipt for entry `index`, bound to the ledger receipt that anchors it. */
+export declare function buildSchemeAppend(entries: readonly unknown[], index: number, ledgerReceipt: Receipt, signer: Signer): Promise<SchemeAppend>;
+/** The bounded equivalent when the caller maintains authenticated Merkle subtrees. */
+export declare function buildSchemeAppendFromStatement(statement: SchemeAppendStatement, ledgerReceipt: Receipt, signer: Signer): Promise<SchemeAppend>;
+/** One append against the authenticated entry/tree prefix; no history arrays are needed. */
+export declare function verifySchemeAppend(statement: SchemeAppendStatement, entry: unknown, append: unknown, receipt: unknown, opts?: {
+    previousAt?: string | null;
+    ledger?: string | null;
+}): {
+    ok: boolean;
+    reasons: string[];
+};
+export interface SchemeLogsInput {
+    /** The scheme log in append order. */
+    entries: readonly unknown[];
+    /** The owner's newest checkpoint, over all of `entries`. */
+    checkpoint: unknown;
+    /** Checkpoints this verifier saw before, each with the consistency proof from it to `checkpoint`. */
+    previous?: readonly {
+        checkpoint: unknown;
+        proof: unknown;
+    }[];
+    /** Require `checkpoint` co-signed by k trusted witnesses. */
+    witness?: {
+        cosignatures: readonly unknown[];
+        trusted: readonly string[];
+        k: number;
+    };
+    /** One append receipt per entry. */
+    appends?: readonly unknown[];
+    /** The Zanii ledger receipts the appends name: each append time is then the ledger's. */
+    ledgerReceipts?: readonly unknown[];
+}
+export interface SchemeLogsCheck {
+    ok: boolean;
+    reasons: string[];
+    size: number;
+    /** Entries whose append is bound to a supplied ledger receipt. */
+    anchored: number;
+    /** With `appends`: each entry's append time. */
+    appended?: string[];
+    /** With `witness`: the trusted witnesses that co-signed the checkpoint. */
+    witnesses?: string[];
+    /** Transition-aware logs only: authenticated cancellation hashes; empty on any refusal. */
+    canceled?: 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 declare function verifySchemeLogs(input: SchemeLogsInput, opts?: {
+    owner?: string;
+    statusIssuers?: readonly string[];
+}): SchemeLogsCheck;

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[];
+};