@verax-ai/proxy 0.1.0

package/dist/approvals.d.ts

@@ -0,0 +1,91 @@
+import { renameSync } from "node:fs";
+/** I/O seam so drain-busy tests can inject rename failures. */
+export declare const approvalFs: {
+    renameSync: typeof renameSync;
+};
+export declare const drainMetrics: {
+    renameBusy: number;
+};
+import type { ApprovalChannel, InputsLog, Ledger, RecordSigner } from "./types.ts";
+export type ApprovalRow = {
+    ref: string;
+    requestHash: string;
+    subject: string;
+    args: Record<string, unknown>;
+    ruleId: string | null;
+    ruleText: string | null;
+    inputsSummary: {
+        count: number;
+        ids: string[];
+    };
+    amount?: unknown;
+    payee?: unknown;
+    currency?: unknown;
+    createdAtMs?: number;
+    expiresAtMs: number;
+    status: "pending" | "approved" | "expired";
+    brain: string;
+    allowRef?: string;
+};
+export type ApprovalsLog = {
+    append(row: ApprovalRow): Promise<void>;
+    get(ref: string): Promise<ApprovalRow | null>;
+    listPending(): Promise<ApprovalRow[]>;
+    listAll(): Promise<ApprovalRow[]>;
+    updateStatus(ref: string, status: "approved" | "expired", extra?: {
+        allowRef?: string;
+    }): Promise<void>;
+};
+export declare class MemoryApprovalsLog implements ApprovalsLog {
+    private readonly rows;
+    private readonly byRef;
+    append(row: ApprovalRow): Promise<void>;
+    get(ref: string): Promise<ApprovalRow | null>;
+    listPending(): Promise<ApprovalRow[]>;
+    listAll(): Promise<ApprovalRow[]>;
+    updateStatus(ref: string, status: "approved" | "expired", extra?: {
+        allowRef?: string;
+    }): Promise<void>;
+}
+export declare class FileApprovalsLog implements ApprovalsLog {
+    private readonly path;
+    private readonly byRef;
+    constructor(dir: string);
+    append(row: ApprovalRow): Promise<void>;
+    get(ref: string): Promise<ApprovalRow | null>;
+    listPending(): Promise<ApprovalRow[]>;
+    listAll(): Promise<ApprovalRow[]>;
+    updateStatus(ref: string, status: "approved" | "expired", extra?: {
+        allowRef?: string;
+    }): Promise<void>;
+    private read;
+}
+export declare function approvalsLogFor(ledger: object): ApprovalsLog;
+export declare function loadApprovalsFromDir(dir: string): ApprovalRow[];
+export type ApproveResult = {
+    ok: true;
+    allowRef: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function approvePending(opts: {
+    ledger: Ledger;
+    recordSigner: RecordSigner;
+    now: () => number;
+    nonce: () => string;
+    ref: string;
+    approverId: string;
+    /** Signed into the inputs document, so it has to be the door the approval came through. */
+    via: ApprovalChannel;
+    policyHash: string;
+    approvals: ApprovalsLog;
+    inputsLog?: InputsLog;
+}): Promise<ApproveResult>;
+export type ApprovalCommand = {
+    ref: string;
+    approverId: string;
+    atMs: number;
+};
+export declare function enqueueApprovalCommand(dir: string, cmd: ApprovalCommand): void;
+export declare function drainApprovalCommands(dir: string, apply: (cmd: ApprovalCommand) => Promise<void>): Promise<void>;

package/dist/approvals.js

@@ -0,0 +1,282 @@
+import { appendFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, } from "node:fs";
+/** I/O seam so drain-busy tests can inject rename failures. */
+export const approvalFs = {
+    renameSync,
+};
+export const drainMetrics = { renameBusy: 0 };
+import { join } from "node:path";
+import { signDecisionRecord } from "@cedulon/core";
+import { appendDurable, lookupDecisionByRef, lookupResolvedBy, noteResolution } from "./ledger.js";
+import { effectDescriptor, sha256Canonical } from "./hash.js";
+import { inputsLogFor } from "./inputs.js";
+function lastByRef(rows) {
+    const map = new Map();
+    for (const row of rows)
+        map.set(row.ref, row);
+    return map;
+}
+function parseLines(text) {
+    const rows = [];
+    for (const line of text.split("\n")) {
+        if (line === "")
+            continue;
+        rows.push(JSON.parse(line));
+    }
+    return rows;
+}
+export class MemoryApprovalsLog {
+    rows = [];
+    byRef = new Map();
+    async append(row) {
+        this.rows.push(row);
+        this.byRef.set(row.ref, row);
+    }
+    async get(ref) {
+        return this.byRef.get(ref) ?? null;
+    }
+    async listPending() {
+        return [...this.byRef.values()].filter((r) => r.status === "pending");
+    }
+    async listAll() {
+        return [...this.byRef.values()];
+    }
+    async updateStatus(ref, status, extra) {
+        const cur = this.byRef.get(ref);
+        if (!cur)
+            return;
+        await this.append({ ...cur, status, ...(extra?.allowRef !== undefined ? { allowRef: extra.allowRef } : {}) });
+    }
+}
+export class FileApprovalsLog {
+    path;
+    byRef = new Map();
+    constructor(dir) {
+        this.path = join(dir, "approvals.jsonl");
+        for (const row of this.read())
+            this.byRef.set(row.ref, row);
+    }
+    async append(row) {
+        await appendDurable(this.path, `${JSON.stringify(row)}\n`);
+        this.byRef.set(row.ref, row);
+    }
+    async get(ref) {
+        return this.byRef.get(ref) ?? null;
+    }
+    async listPending() {
+        return [...this.byRef.values()].filter((r) => r.status === "pending");
+    }
+    async listAll() {
+        return [...this.byRef.values()];
+    }
+    async updateStatus(ref, status, extra) {
+        const cur = this.byRef.get(ref);
+        if (!cur)
+            return;
+        await this.append({ ...cur, status, ...(extra?.allowRef !== undefined ? { allowRef: extra.allowRef } : {}) });
+    }
+    read() {
+        try {
+            return parseLines(readFileSync(this.path, "utf8"));
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+    }
+}
+const STASH = Symbol.for("verax.approvalsLog");
+export function approvalsLogFor(ledger) {
+    const bag = ledger;
+    if (bag[STASH])
+        return bag[STASH];
+    const log = typeof bag.dir === "string" ? new FileApprovalsLog(bag.dir) : new MemoryApprovalsLog();
+    bag[STASH] = log;
+    return log;
+}
+export function loadApprovalsFromDir(dir) {
+    const path = join(dir, "approvals.jsonl");
+    try {
+        return [...lastByRef(parseLines(readFileSync(path, "utf8"))).values()];
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+async function hasResolves(inputsLog, ledger, deferRef) {
+    const indexed = ledger;
+    if (typeof indexed.lookupResolvedBy === "function") {
+        return indexed.lookupResolvedBy(deferRef) != null;
+    }
+    for (const d of await ledger.decisions()) {
+        if (!d.claims.ref || d.claims.ref === deferRef)
+            continue;
+        const inp = await inputsLog.get(d.claims.ref);
+        if (inp?.approver?.resolves === deferRef)
+            return true;
+    }
+    return false;
+}
+export async function approvePending(opts) {
+    const inputsLog = opts.inputsLog ?? inputsLogFor(opts.ledger);
+    const defer = await lookupDecisionByRef(opts.ledger, opts.ref);
+    if (!defer || defer.decision !== "defer")
+        return { ok: false, reason: "unknown-ref" };
+    const snap = await opts.approvals.get(opts.ref);
+    if (snap && snap.status !== "pending")
+        return { ok: false, reason: "already-resolved" };
+    const resolved = lookupResolvedBy(opts.ledger, opts.ref);
+    if (resolved || (await hasResolves(inputsLog, opts.ledger, opts.ref))) {
+        const hit = resolved ?? lookupResolvedBy(opts.ledger, opts.ref);
+        if (snap?.status === "pending" && hit) {
+            await opts.approvals.updateStatus(opts.ref, hit.kind === "allow" ? "approved" : "expired", hit.kind === "allow" ? { allowRef: hit.ref } : undefined);
+        }
+        return { ok: false, reason: "already-resolved" };
+    }
+    if (!snap)
+        return { ok: false, reason: "snapshot-missing" };
+    const requestHash = sha256Canonical({ name: snap.subject, arguments: snap.args });
+    if (requestHash !== defer.requestHash || requestHash !== snap.requestHash) {
+        return { ok: false, reason: "hash-mismatch" };
+    }
+    if (opts.now() > snap.expiresAtMs) {
+        const expireRef = opts.nonce();
+        const prior = await inputsLog.get(opts.ref);
+        const inputs = {
+            principal: prior?.principal ?? { brain: snap.brain, scopes: [] },
+            inputs: prior?.inputs ?? [],
+            approver: { id: opts.approverId, via: opts.via, resolves: opts.ref },
+        };
+        const inputsHash = sha256Canonical(inputs);
+        await inputsLog.append(expireRef, inputs);
+        await opts.ledger.appendDecisionChained((prevRecordHash) => signDecisionRecord({
+            decider: "verax-operator",
+            subject: defer.subject,
+            requestHash: defer.requestHash,
+            policyHash: opts.policyHash,
+            inputsHash,
+            decision: "deny",
+            reasonCode: "expired",
+            ref: expireRef,
+            effectHash: null,
+            // A refusal names what it refused, in the same word the effect row
+            // would have carried had the operator approved in time.
+            effectClass: defer.subject,
+            timestampMs: opts.now(),
+            nonce: expireRef,
+            prevRecordHash,
+        }, opts.recordSigner.privateKeyPem, opts.recordSigner.publicKeyPem));
+        noteResolution(opts.ledger, opts.ref, { ref: expireRef, kind: "expired" });
+        await opts.approvals.updateStatus(opts.ref, "expired");
+        return { ok: false, reason: "expired" };
+    }
+    const allowRef = opts.nonce();
+    const prior = await inputsLog.get(opts.ref);
+    const inputs = {
+        principal: prior?.principal ?? { brain: snap.brain, scopes: [] },
+        inputs: prior?.inputs ?? [],
+        approver: { id: opts.approverId, via: opts.via, resolves: opts.ref },
+    };
+    const inputsHash = sha256Canonical(inputs);
+    const effectHash = sha256Canonical(effectDescriptor(snap.subject, snap.args));
+    await inputsLog.append(allowRef, inputs);
+    await opts.ledger.appendDecisionChained((prevRecordHash) => signDecisionRecord({
+        decider: "verax-operator",
+        subject: defer.subject,
+        requestHash: defer.requestHash,
+        policyHash: opts.policyHash,
+        inputsHash,
+        decision: "allow",
+        reasonCode: "approved-by-operator",
+        ref: allowRef,
+        effectHash,
+        // Same word the effect row below carries, so the audit can hold the
+        // two to each other.
+        effectClass: defer.subject,
+        timestampMs: opts.now(),
+        nonce: allowRef,
+        prevRecordHash,
+    }, opts.recordSigner.privateKeyPem, opts.recordSigner.publicKeyPem));
+    noteResolution(opts.ledger, opts.ref, { ref: allowRef, kind: "allow" });
+    if (snap.subject === "spend") {
+        const resultHash = sha256Canonical({
+            authorized: true,
+            ref: allowRef,
+            amountMinor: snap.args.amountMinor,
+            currency: snap.args.currency,
+            payee: snap.args.payee,
+            reference: snap.args.reference,
+        });
+        await opts.ledger.appendEffect({
+            ref: allowRef,
+            effectHash,
+            effectClass: "spend",
+            timestampMs: opts.now(),
+            actor: opts.approverId,
+        }, "self", resultHash);
+    }
+    await opts.approvals.updateStatus(opts.ref, "approved", { allowRef });
+    return { ok: true, allowRef };
+}
+export function enqueueApprovalCommand(dir, cmd) {
+    appendFileSync(join(dir, "approval-commands.jsonl"), `${JSON.stringify(cmd)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+export async function drainApprovalCommands(dir, apply) {
+    const live = join(dir, "approval-commands.jsonl");
+    if (existsSync(live)) {
+        const processing = join(dir, `approval-commands.processing-${Date.now()}-${process.pid}`);
+        try {
+            approvalFs.renameSync(live, processing);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "EPERM" || code === "EBUSY") {
+                drainMetrics.renameBusy += 1;
+                process.stderr.write(`verax-drain: rename-busy ${code} count=${drainMetrics.renameBusy}\n`);
+                return;
+            }
+            if (code !== "ENOENT")
+                throw err;
+        }
+    }
+    let names;
+    try {
+        names = readdirSync(dir)
+            .filter((n) => n.startsWith("approval-commands.processing-"))
+            .sort();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    const donePath = join(dir, "approval-commands.applied.jsonl");
+    const poisonPath = join(dir, "approval-commands.poison.jsonl");
+    for (const name of names) {
+        const file = join(dir, name);
+        try {
+            const text = readFileSync(file, "utf8");
+            for (const line of text.split("\n")) {
+                if (line === "")
+                    continue;
+                try {
+                    const cmd = JSON.parse(line);
+                    await apply(cmd);
+                    appendFileSync(donePath, `${line}\n`, { encoding: "utf8", mode: 0o600 });
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err.message : String(err);
+                    appendFileSync(poisonPath, `${JSON.stringify({ line, error, atMs: Date.now() })}\n`, { encoding: "utf8", mode: 0o600 });
+                }
+            }
+        }
+        finally {
+            unlinkSync(file);
+        }
+    }
+}

package/dist/checkpoints.d.ts

@@ -0,0 +1,3 @@
+import type { SignedCheckpoint } from "@cedulon/checkpoint";
+export declare function checkpointsPath(dir: string): string;
+export declare function loadCheckpoints(dir: string): SignedCheckpoint[];

package/dist/checkpoints.js

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+export function checkpointsPath(dir) {
+    return join(dir, "checkpoints.jsonl");
+}
+export function loadCheckpoints(dir) {
+    let text;
+    try {
+        text = readFileSync(checkpointsPath(dir), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line === "")
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (row && typeof row === "object" && row.claims && typeof row.coseHex === "string") {
+                out.push(row);
+            }
+        }
+        catch {
+            // skip a truncated line; the next honest row still loads
+        }
+    }
+    return out;
+}

package/dist/disk.d.ts

@@ -0,0 +1,6 @@
+export declare function defaultDiskFreeBytes(): number;
+/** Injected by tests. Production uses statfs on stateDir. */
+export declare const diskProbe: {
+    failAppend: boolean;
+    freeBytes(dir: string): number;
+};

package/dist/disk.js

@@ -0,0 +1,13 @@
+import { statfsSync } from "node:fs";
+const DEFAULT_DISK_FREE_BYTES = 64 * 1024 * 1024;
+export function defaultDiskFreeBytes() {
+    return DEFAULT_DISK_FREE_BYTES;
+}
+/** Injected by tests. Production uses statfs on stateDir. */
+export const diskProbe = {
+    failAppend: false,
+    freeBytes(dir) {
+        const s = statfsSync(dir);
+        return Number(s.bavail) * Number(s.bsize);
+    },
+};

package/dist/explain.d.ts

@@ -0,0 +1,13 @@
+import type { ExplainOpts, ExplainResult, Ledger } from "./types.ts";
+/**
+ * Re-runs the Cedulon decision profile on the whole ledger. Finding codes
+ * are Cedulon's; this wrapper does not invent names. With no durable
+ * checkpoint on disk, window-coverage is listed as notApplicable and
+ * dropped from the finding set before balanced is computed. When
+ * `checkpoints.jsonl` has at least one signed row, that finding is kept.
+ * General issuer/extract warnings and the audit guarantee are kept. A
+ * self witness and each general Cedulon warning are named in the
+ * condition list; "balanced" is never written alone, and "conditional"
+ * is never written twice.
+ */
+export declare function explain(ledger: Ledger, ref: string, opts?: ExplainOpts): Promise<ExplainResult>;

package/dist/explain.js

@@ -0,0 +1,211 @@
+import { audit, DECISION_PROFILE } from "@cedulon/audit";
+import { findDecisionRecordChainBreak } from "@cedulon/core";
+import { approvalsLogFor } from "./approvals.js";
+import { sha256Canonical } from "./hash.js";
+import { inputsLogFor } from "./inputs.js";
+import { lookupResolvedBy } from "./ledger.js";
+import { loadCheckpoints } from "./checkpoints.js";
+async function pairFor(ledger, decisions, record, inputsLog, approvals) {
+    const ref = record.claims.ref;
+    if (!ref)
+        return { defer: null, resolution: null };
+    if (record.claims.decision === "defer") {
+        const snap = await approvals.get(ref);
+        if (snap?.allowRef) {
+            const resolution = decisions.find((d) => d.claims.ref === snap.allowRef) ?? null;
+            return { defer: record, resolution };
+        }
+        const hit = lookupResolvedBy(ledger, ref);
+        if (hit) {
+            const resolution = decisions.find((d) => d.claims.ref === hit.ref) ?? null;
+            return { defer: record, resolution };
+        }
+        return { defer: null, resolution: null };
+    }
+    const own = await inputsLog.get(ref);
+    if (own?.approver?.resolves) {
+        const defer = decisions.find((d) => d.claims.ref === own.approver?.resolves) ?? null;
+        return { defer, resolution: record };
+    }
+    return { defer: null, resolution: null };
+}
+const WINDOW_COVERAGE = "window-coverage";
+function resolveIssuerTrust(opts) {
+    if (opts?.issuerTrust) {
+        return {
+            pin: { publicKeyPem: opts.issuerTrust.publicKeyPem },
+            source: opts.issuerTrust.source ?? null,
+        };
+    }
+    const env = process.env.VERAX_RECORD_PUBKEY_PIN;
+    if (typeof env === "string" && env.trim() !== "") {
+        return { pin: { publicKeyPem: env }, source: "env" };
+    }
+    return { pin: undefined, source: null };
+}
+function asWarning(f) {
+    return { id: f.id, code: f.code, detail: f.detail };
+}
+function conditionName(f, extractPresented) {
+    if (f.code === "unauthenticated-issuer")
+        return "issuer unpinned";
+    if (f.code === "unauthenticated-extract") {
+        // Name from whether an extract was handed to audit, not Cedulon detail text.
+        return extractPresented ? "extract unpinned" : "extract unsigned";
+    }
+    return null;
+}
+function balancedSummary(guarantee, conditions, cedulonSummary) {
+    if (conditions.length > 0) {
+        return `audit: balanced (${guarantee}: ${conditions.join("; ")})`;
+    }
+    if (guarantee === "unconditional") {
+        return "audit: balanced (unconditional)";
+    }
+    const why = cedulonSummary.replace(/^audit:\s*/i, "").trim();
+    if (why !== "" && why !== "balanced" && why !== "conditional") {
+        return `audit: balanced (${guarantee}: ${why})`;
+    }
+    return `audit: balanced (${guarantee})`;
+}
+/**
+ * Re-runs the Cedulon decision profile on the whole ledger. Finding codes
+ * are Cedulon's; this wrapper does not invent names. With no durable
+ * checkpoint on disk, window-coverage is listed as notApplicable and
+ * dropped from the finding set before balanced is computed. When
+ * `checkpoints.jsonl` has at least one signed row, that finding is kept.
+ * General issuer/extract warnings and the audit guarantee are kept. A
+ * self witness and each general Cedulon warning are named in the
+ * condition list; "balanced" is never written alone, and "conditional"
+ * is never written twice.
+ */
+export async function explain(ledger, ref, opts) {
+    const decisions = await ledger.decisions();
+    const effects = await ledger.effects();
+    const record = decisions.find((d) => d.claims.ref === ref);
+    if (!record) {
+        throw new Error(`explain-unknown-ref:${ref}`);
+    }
+    const effect = effects.find((e) => e.row.ref === ref && e.row.effectClass !== "duplicate-effect") ?? null;
+    const presentedExtract = opts?.extract ?? effect?.receipt;
+    const extractPresented = Boolean(presentedExtract);
+    const resolvedTrust = resolveIssuerTrust(opts);
+    const issuerTrust = resolvedTrust.pin;
+    const pinSource = resolvedTrust.source;
+    const pinned = issuerTrust !== undefined;
+    const dir = ledger.dir;
+    const checkpoints = typeof dir === "string" ? loadCheckpoints(dir) : [];
+    const report = audit({
+        receipts: decisions,
+        checkpoints,
+        settlements: effects.map((e) => e.row),
+        profile: DECISION_PROFILE,
+        ...(issuerTrust ? { issuerTrust } : {}),
+        ...(presentedExtract ? { extract: presentedExtract } : {}),
+    });
+    const dropWindow = checkpoints.length === 0;
+    const dropped = dropWindow
+        ? [
+            ...new Set([...report.findings, ...report.warnings]
+                .filter((f) => f.code === WINDOW_COVERAGE)
+                .map((f) => f.code)),
+        ]
+        : [];
+    const applicable = dropWindow
+        ? report.findings.filter((f) => f.code !== WINDOW_COVERAGE)
+        : report.findings;
+    const applicableWarnings = dropWindow
+        ? report.warnings.filter((f) => f.code !== WINDOW_COVERAGE)
+        : report.warnings;
+    const refFindings = applicable.filter((f) => f.id === ref);
+    const issuerFinding = applicable.find((f) => f.code === "issuer-key-mismatch" || f.id === "issuer") ??
+        applicableWarnings.find((f) => f.code === "issuer-key-mismatch") ??
+        null;
+    const hit = refFindings[0] ??
+        (pinned ? issuerFinding : null) ??
+        applicableWarnings.find((f) => f.id === ref) ??
+        null;
+    const prefix = decisions.slice(0, decisions.indexOf(record) + 1);
+    const brk = findDecisionRecordChainBreak(prefix);
+    const breakAt = brk ? (prefix[brk.index]?.claims.ref ?? null) : null;
+    const chain = { intact: brk === null, breakAt };
+    const witnessClass = effect?.witnessClass ?? null;
+    const self = witnessClass === "self";
+    const chainBreak = !chain.intact;
+    const conditions = [];
+    if (self)
+        conditions.push("self witness");
+    if (pinSource === "own-key")
+        conditions.push("issuer pinned to own key");
+    for (const w of applicableWarnings) {
+        const name = conditionName(w, extractPresented);
+        if (name && !conditions.includes(name))
+            conditions.push(name);
+    }
+    const issuerMismatch = applicable.concat(applicableWarnings).some((f) => f.code === "issuer-key-mismatch" || (pinned && f.code === "unauthenticated-issuer"));
+    const inputsLog = opts?.inputsLog ?? inputsLogFor(ledger);
+    const approvals = approvalsLogFor(ledger);
+    const inputsDoc = record.claims.ref ? await inputsLog.get(record.claims.ref) : null;
+    const inputsMismatch = Boolean(inputsDoc &&
+        typeof record.claims.inputsHash === "string" &&
+        sha256Canonical(inputsDoc) !== record.claims.inputsHash);
+    const inputsMissing = typeof record.claims.inputsHash === "string" && inputsDoc === null;
+    if (inputsMissing)
+        conditions.push("inputs document missing");
+    const balanced = refFindings.length === 0 && !chainBreak && !issuerMismatch && !inputsMismatch && !inputsMissing;
+    const code = chainBreak
+        ? "receipt-chain-break"
+        : inputsMismatch
+            ? "inputs-hash-mismatch"
+            : inputsMissing
+                ? "inputs-document-missing"
+                : (hit?.code ?? null);
+    const detail = chainBreak
+        ? `receipt-chain-break at ${breakAt ?? "unknown"} (${brk?.reason ?? "broken"})`
+        : inputsMismatch
+            ? "inputs document hash does not match claims.inputsHash"
+            : inputsMissing
+                ? "claims.inputsHash is on the record; the inputs document is not on disk"
+                : (hit?.detail ?? null);
+    const findingCount = chainBreak
+        ? Math.max(refFindings.length, 1)
+        : refFindings.length +
+            (issuerMismatch && pinned ? 1 : 0) +
+            (inputsMismatch ? 1 : 0) +
+            (inputsMissing ? 1 : 0);
+    const guarantee = report.guarantee;
+    const summary = balanced
+        ? balancedSummary(guarantee, conditions, report.summary)
+        : `audit: ${Math.max(findingCount, 1)} finding(s) → FAIL`;
+    const warnings = applicableWarnings.filter((f) => f.id === "issuer" || f.id === "extract").map(asWarning);
+    if (inputsMissing) {
+        warnings.push({
+            id: "inputs",
+            code: "inputs-document-missing",
+            detail: "claims.inputsHash is on the record; the inputs document is not on disk",
+        });
+    }
+    return {
+        record,
+        effect,
+        pair: await pairFor(ledger, decisions, record, inputsLog, approvals),
+        witnessClass,
+        balanced,
+        chain,
+        guarantee,
+        warnings,
+        trustRoot: {
+            pinned,
+            issuerMatches: pinned ? !issuerMismatch && !warnings.some((w) => w.id === "issuer") : null,
+            source: pinSource,
+        },
+        ...(report.scope ? { scope: report.scope } : {}),
+        finding: {
+            code,
+            label: guarantee === "conditional" || conditions.length > 0 ? "conditional" : null,
+            detail,
+            summary,
+            ...(dropped.length > 0 ? { notApplicable: dropped } : {}),
+        },
+    };
+}

package/dist/hash.d.ts

@@ -0,0 +1,4 @@
+/** SHA-256 of Cedulon's RFC 8785 canonical JSON, 64-char lowercase hex. */
+export declare function sha256Canonical(value: unknown): string;
+/** Decision and effect rows hash this same descriptor on a successful allow. */
+export declare function effectDescriptor(tool: string, args: Record<string, unknown>, threw?: boolean): Record<string, unknown>;

package/dist/hash.js

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+import { canonical } from "@cedulon/core";
+/** SHA-256 of Cedulon's RFC 8785 canonical JSON, 64-char lowercase hex. */
+export function sha256Canonical(value) {
+    return createHash("sha256").update(canonical(value), "utf8").digest("hex");
+}
+/** Decision and effect rows hash this same descriptor on a successful allow. */
+export function effectDescriptor(tool, args, threw = false) {
+    return threw ? { tool, arguments: args, threw: true } : { tool, arguments: args };
+}