@zanii/blackbox 0.3.0 → 0.4.0

package/dist/finance/index.js

@@ -0,0 +1,320 @@
+// Finance (spec/finance.md): exact money and payments (@zanii/payments), counterparty screening
+// (@zanii/kya), tax filings prepared, never filed (@zanii/fta), the owner behind a counterparty
+// (@zanii/kyb), and the findings over them. Pure; mirrors sdks/python/src/zanii_blackbox/finance.py;
+// pinned by spec/vectors/finance.json.
+import { canonicalBytes, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+/** Minor-unit precision: Zanii's table, plus the Gulf's currencies. */
+export const CURRENCIES = {
+    USD: 2,
+    EUR: 2,
+    GBP: 2,
+    CHF: 2,
+    CAD: 2,
+    AUD: 2,
+    CNY: 2,
+    INR: 2,
+    JPY: 0,
+    KRW: 0,
+    USDC: 6,
+    USDT: 6,
+    BTC: 8,
+    ZAN: 9,
+    ETH: 18,
+    AED: 2,
+    SAR: 2,
+    QAR: 2,
+    KWD: 3,
+    BHD: 3,
+    OMR: 3,
+};
+function decimalsOf(currency) {
+    const d = CURRENCIES[currency.toUpperCase()];
+    if (d === undefined)
+        throw new Error(`unknown currency '${currency}'`);
+    return d;
+}
+function formatMinorUnits(minor, decimals) {
+    const neg = minor < 0n;
+    const m = neg ? -minor : minor;
+    const base = 10n ** BigInt(decimals);
+    const whole = m / base;
+    if (decimals === 0)
+        return `${neg ? "-" : ""}${whole}`;
+    return `${neg ? "-" : ""}${whole}.${(m % base).toString().padStart(decimals, "0")}`;
+}
+/** Zanii's exact parse: a decimal string to minor units (a string), never a float. */
+export function parseMoney(amount, currency) {
+    const decimals = decimalsOf(currency);
+    const s = String(amount).trim();
+    if (!/^\d+(\.\d+)?$/.test(s))
+        throw new Error(`invalid amount '${s}' (expected a non-negative decimal)`);
+    const [whole = "0", frac = ""] = s.split(".");
+    if (frac.length > decimals)
+        throw new Error(`amount '${s}' has more precision than ${currency} allows (${decimals} dp)`);
+    const minor = BigInt(whole) * 10n ** BigInt(decimals) + BigInt(frac.padEnd(decimals, "0") || "0");
+    if (minor <= 0n)
+        throw new Error("amount must be > 0");
+    const cur = currency.toUpperCase();
+    return {
+        currency: cur,
+        minor: minor.toString(),
+        display: `${formatMinorUnits(minor, decimals)} ${cur}`,
+    };
+}
+export const formatMoney = (minor, currency) => formatMinorUnits(BigInt(minor), decimalsOf(currency));
+/** Zanii's payment receipt payload. No settlement reference, no payment. */
+export function buildPayment(input) {
+    if (!input.rail)
+        throw new Error("rail is required");
+    if (!input.reference)
+        throw new Error("reference is required (a payment with no settlement reference is unprovable)");
+    return {
+        target: `pay.${input.rail.toLowerCase()}`,
+        rail: input.rail,
+        reference: input.reference,
+        money: parseMoney(input.amount, input.currency),
+        from: input.from ?? null,
+        to: input.to ?? null,
+        memo: input.memo ?? null,
+        extra: input.extra ?? null,
+    };
+}
+/** Zanii's KYA screen, offline: the DID or its owner on a deny list is a hit. */
+export function screenCounterparty(did, opts = {}) {
+    if (!did)
+        throw new Error("did is required");
+    const deny = new Set(opts.denyList ?? []);
+    const hits = [];
+    if (deny.has(did))
+        hits.push({ source: "deny-list", detail: did });
+    if (opts.owner && deny.has(opts.owner))
+        hits.push({ source: "deny-list", detail: opts.owner });
+    return { did, owner: opts.owner ?? null, ok: hits.length === 0, hits, history: null };
+}
+/** Zanii's kya.screening payload for a screening result. */
+export function screeningPayload(result, ts, screenedBy = null) {
+    const sources = [...new Set(result.hits.map((h) => h.source))].sort();
+    return {
+        _zr_kind: "kya",
+        v: 1,
+        did: result.did,
+        owner: result.owner,
+        ok: result.ok,
+        hits: result.hits,
+        sources,
+        screened_by: screenedBy,
+        ts,
+    };
+}
+export const FTA_WALL_ID = "fta-prepares-never-files";
+/** Zanii's FTA payloads: a filing prepared (never filed), and its hand-off to a Tax Agent. */
+export function ftaPayload(input) {
+    if (!input.filingType)
+        throw new Error("filing_type is required");
+    if (!input.period)
+        throw new Error("period is required");
+    if (input.action === "prepared")
+        return {
+            _zr_kind: "fta",
+            v: 1,
+            action: "prepared",
+            filing_type: input.filingType,
+            period: input.period,
+            prepared_by: input.by,
+            filing_ref: input.filingRef ?? null,
+            manifest_hash: input.manifestHash ?? null,
+            wall: FTA_WALL_ID,
+        };
+    if (!input.toTaxAgent)
+        throw new Error("to_tax_agent (the licensed Tax Agent) is required");
+    return {
+        _zr_kind: "fta",
+        v: 1,
+        action: "handoff",
+        filing_type: input.filingType,
+        period: input.period,
+        from_agent: input.by,
+        to_tax_agent: input.toTaxAgent,
+        filing_ref: input.filingRef ?? null,
+        wall: FTA_WALL_ID,
+    };
+}
+// ---------------------------------------------------------------- KYB: the owner behind a party
+/** Zanii's kyb.attestation: an owner DID signs which domain and legal entity it is. */
+export function buildOwnerAttestation(input) {
+    if (!input.did)
+        throw new Error("did is required");
+    if (!input.domain)
+        throw new Error("domain is required");
+    if (!input.entity?.name)
+        throw new Error("entity.name is required");
+    if (Number.isNaN(Date.parse(input.ts)))
+        throw new Error("ts must be an ISO timestamp");
+    const unsigned = {
+        v: 1,
+        type: "kyb.attestation",
+        did: input.did,
+        domain: input.domain.toLowerCase(),
+        entity: input.entity,
+        ts: input.ts,
+    };
+    const sig = Buffer.from(ed25519Sign(input.ownerPrivateKey, canonicalBytes(unsigned))).toString("hex");
+    return { ...unsigned, sig: `ed25519:${sig}` };
+}
+export function verifyOwnerAttestation(a) {
+    const p = (a ?? {});
+    if (p.v !== 1 || p.type !== "kyb.attestation" || !p.did || !p.domain)
+        return false;
+    const entity = p.entity;
+    if (!entity || typeof entity !== "object" || !entity.name)
+        return false;
+    if (typeof p.ts !== "string" || Number.isNaN(Date.parse(p.ts)))
+        return false;
+    const pub = publicKeyFromDid(String(p.did));
+    const m = typeof p.sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(p.sig) : null;
+    if (!pub || !m)
+        return false;
+    const { sig: _sig, ...unsigned } = p;
+    return ed25519Verify(pub, canonicalBytes(unsigned), Buffer.from(m[1], "hex"));
+}
+/** Zanii's two-way check: the owner signed it, and the domain's own doc lists that owner. */
+export function verifyOwnerBinding(attestation, doc) {
+    const a = (attestation ?? {});
+    if (!verifyOwnerAttestation(attestation))
+        return { ok: false, reasons: ["attestation is not validly signed by its DID"], entity: null };
+    const d = (doc ?? {});
+    if (d.v !== 1 ||
+        typeof d.domain !== "string" ||
+        typeof d.entity !== "object" ||
+        d.entity === null ||
+        !d.entity.name ||
+        !Array.isArray(d.owner_dids))
+        return {
+            ok: false,
+            reasons: [
+                `${a.domain} publishes no valid owner doc — the domain side of the binding is missing`,
+            ],
+            entity: null,
+        };
+    const reasons = [];
+    if (d.domain.toLowerCase() !== a.domain.toLowerCase())
+        reasons.push(`attestation names ${a.domain} but the doc is for ${d.domain}`);
+    if (!d.owner_dids.includes(a.did))
+        reasons.push(`the domain does not list ${a.did} — anyone can sign a claim; only the domain's list makes it mutual`);
+    if (d.entity.name !== a.entity.name)
+        reasons.push(`entity name mismatch: domain says '${String(d.entity.name)}', owner claims '${String(a.entity.name)}'`);
+    for (const field of ["jurisdiction", "registration"]) {
+        const x = a.entity[field];
+        const y = d.entity[field];
+        if (x !== undefined && y !== undefined && x !== y)
+            reasons.push(`entity ${field} mismatch: domain says '${String(y)}', owner claims '${String(x)}'`);
+    }
+    return { ok: reasons.length === 0, reasons, entity: reasons.length === 0 ? d.entity : null };
+}
+const decoder = new TextDecoder();
+export function financeFindings(lines, bodies, closing = false) {
+    let closed = closing;
+    const out = [];
+    const screened = new Map();
+    const prepared = [];
+    const handedOff = new Set();
+    for (const l of lines) {
+        const e = JSON.parse(l);
+        if (e.kind === "session.close")
+            closed = true;
+        if (e.kind !== "sdk.event")
+            continue;
+        const type = e.meta.type;
+        if (type !== "payment" &&
+            type !== "kya.screening" &&
+            type !== "fta.prepared" &&
+            type !== "fta.handoff")
+            continue;
+        const body = bodies(e.body_hash);
+        let data = {};
+        try {
+            data = body ? JSON.parse(decoder.decode(body)) : {};
+        }
+        catch { }
+        if (type === "kya.screening" && typeof data.did === "string")
+            screened.set(data.did, { ok: data.ok === true, seq: e.seq });
+        else if (type === "payment" && typeof data.to === "string" && data.to) {
+            const s = screened.get(data.to);
+            if (!s)
+                out.push({
+                    code: "UNSCREENED_COUNTERPARTY",
+                    source: "detectors",
+                    severity: "warning",
+                    ref: { seq: e.seq, to: data.to },
+                    detail: "A payment to a counterparty this session never screened first.",
+                });
+            else if (!s.ok)
+                out.push({
+                    code: "SCREENING_HIT_PAID",
+                    source: "detectors",
+                    severity: "warning",
+                    ref: { seq: e.seq, to: data.to, screening_seq: s.seq },
+                    detail: "A payment to a counterparty whose screening had hits.",
+                });
+        }
+        else if (type === "fta.prepared" || type === "fta.handoff") {
+            const key = `${String(data.filing_type)}\u0000${String(data.period)}`;
+            if (type === "fta.handoff")
+                handedOff.add(key);
+            else
+                prepared.push({
+                    seq: e.seq,
+                    key,
+                    filing_type: String(data.filing_type),
+                    period: String(data.period),
+                });
+        }
+    }
+    if (closed)
+        for (const p of prepared)
+            if (!handedOff.has(p.key))
+                out.push({
+                    code: "FTA_NO_HANDOFF",
+                    source: "detectors",
+                    severity: "advisory",
+                    ref: { seq: p.seq, filing_type: p.filing_type, period: p.period },
+                    detail: "A tax filing was prepared and never handed to a licensed Tax Agent.",
+                });
+    return out;
+}
+/** spec/finance.md §2: the session's payments, and exact totals per currency (minor units). */
+export function paymentsOf(lines, bodies) {
+    const payments = [];
+    const totals = new Map();
+    for (const l of lines) {
+        const e = JSON.parse(l);
+        if (e.kind !== "sdk.event" || e.meta.type !== "payment")
+            continue;
+        const body = bodies(e.body_hash);
+        let p;
+        try {
+            p = body ? JSON.parse(decoder.decode(body)) : {};
+        }
+        catch {
+            continue;
+        }
+        const m = p.money;
+        if (!m || typeof m !== "object")
+            continue;
+        payments.push({
+            seq: e.seq,
+            rail: p.rail ?? null,
+            reference: p.reference ?? null,
+            money: m,
+            to: p.to ?? null,
+        });
+        const cur = String(m.currency);
+        totals.set(cur, (totals.get(cur) ?? 0n) + BigInt(String(m.minor)));
+    }
+    const sorted = [...totals.keys()].sort();
+    return {
+        payments,
+        totals: Object.fromEntries(sorted.map((k) => [k, String(totals.get(k))])),
+    };
+}

package/dist/fleet/index.js

@@ -6,6 +6,7 @@ import { toolCallsOf } from "../analysis/detectors.js";
 import { FAULTS } from "../analysis/faults.js";
 import { eventsOf } from "../analysis/index.js";
 import { landing } from "../analysis/landing.js";
+import { authorityTimeline } from "../authority/index.js";
 import { formatAed, sessionCost, toAedFils } from "../cost/index.js";
 import { callsOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
@@ -60,10 +61,18 @@ export function sessionSummary(lines, bodies, prices) {
     const claims = { satisfied: 0, failed: 0, unverified: 0 };
     for (const c of landing(eventsOf(lines, bodies), lines, bodies).claims)
         claims[c.verdict]++;
+    const inControl = authorityTimeline(lines).at(-1)?.mode ?? "agent";
     return {
         session_id: first.session_id,
         label: typeof first.meta.label === "string" ? first.meta.label : null,
         tenant: typeof first.meta.tenant === "string" ? first.meta.tenant : null,
+        // spec/api.md: only when the session has one, so older summaries read the same
+        ...(typeof first.meta.environment === "string" ? { environment: first.meta.environment } : {}),
+        // spec/fleet.md §2: the budget, when there is one; who flies, when it isn't the agent
+        ...(typeof first.meta.budget_micro_usd === "number"
+            ? { budget_micro_usd: first.meta.budget_micro_usd }
+            : {}),
+        ...(inControl !== "agent" ? { in_control: inControl } : {}),
         objective: typeof plan?.objective === "string" ? plan.objective : null,
         started_at: first.ts,
         last_event_at: last.ts,

package/dist/gov/index.d.ts

@@ -0,0 +1,108 @@
+type Text = {
+    en: string;
+    ar: string;
+};
+type Obj = Record<string, unknown>;
+export declare const GOV_DECISION_KINDS: readonly ["benefit.grant", "benefit.deny", "visa.decide", "fine.issue", "licence.decide"];
+/** Zanii's pseudonymous, authority-scoped tag for a person's did:key. */
+export declare function subjectTag(subjectDid: string, authority: string): string;
+/** Zanii's subject claim: "this is my slice", signed with the person's own key. */
+export declare function signSubjectClaim(input: {
+    platform: string;
+    subjectDid: string;
+    ts: string;
+    subjectPrivateKey: Uint8Array;
+}): {
+    v: number;
+    type: string;
+    platform: string;
+    subject: string;
+    tag: string;
+    ts: string;
+    sig: string;
+};
+/** The subject signed it, and the tag derives from that subject at that platform. */
+export declare function verifySubjectClaim(claim: unknown): boolean;
+/** Zanii's decision payload, v1, for a government decision. No rulebook, no decision. */
+export declare function decisionPayload(input: {
+    kind: string;
+    manifestHash: string;
+    outcome: Obj;
+    ts: string;
+    factors?: Obj;
+    appealBy?: string;
+    nonce?: string;
+}): {
+    payload: Obj;
+    nonce: string;
+};
+/** The disclosed factors and nonce match the commitment made at decision time. */
+export declare const verifyFactors: (factors: unknown, nonce: string, commitment: string) => boolean;
+/** Zanii's structural check of a decision payload. */
+export declare function verifyDecision(payload: unknown): {
+    ok: boolean;
+    reasons: string[];
+};
+/** Zanii's rulebook windows over time; interleaving is the red flag. */
+export declare function ruleConsistency(payloads: readonly unknown[]): {
+    rulebooks: {
+        manifest_hash: string;
+        count: number;
+        first_ts: string;
+        last_ts: string;
+    }[];
+    consistent: boolean;
+    reasons: string[];
+};
+export interface AppealItem {
+    session_id: string;
+    seq: number;
+    line: string;
+    event_hash: string;
+    anchored: boolean;
+    decision: unknown;
+}
+/** spec/gov.md §3: the citizen's appeal pack over the decisions recorded about their tag. */
+export declare function appealPack(items: readonly AppealItem[], opts: {
+    tag: string;
+    authority: string;
+    generated_at: string;
+}): {
+    v: 1;
+    legal_basis: Text;
+    subject_tag: string;
+    authority: string;
+    decisions: number;
+    rules: {
+        rulebooks: {
+            manifest_hash: string;
+            count: number;
+            first_ts: string;
+            last_ts: string;
+        }[];
+        consistent: boolean;
+        reasons: string[];
+    };
+    unruled: number;
+    period: {
+        first: string | null;
+        last: string | null;
+    };
+    items: {
+        session_id: string;
+        seq: number;
+        line: string;
+        event_hash: string;
+        anchored: boolean;
+    }[];
+    steps: {
+        en: string;
+        ar: string;
+        n: number;
+    }[];
+    generated_at: string;
+};
+export type AppealPack = ReturnType<typeof appealPack>;
+/** The reading copy for an administrative judge: `en`, `ar` or `both` (headers always bilingual). */
+export declare function renderAppealPack(pack: AppealPack, lang?: "en" | "ar" | "both"): string;
+export {};

package/dist/gov/index.js

@@ -0,0 +1,225 @@
+// Government decisions about people, and the citizen's appeal pack (spec/gov.md), on Zanii's
+// subject tags, subject claims and decision payloads (@zanii/subject, @zanii/decisions, @zanii/gov).
+// Pure; mirrors sdks/python/src/zanii_blackbox/gov.py; pinned by spec/vectors/gov.json.
+import { createHash, randomBytes } from "node:crypto";
+import { canonicalBytes, jcsHash, publicKeyFromDid } from "@zanii/core";
+import { canonical } from "../reconcile/shared.js";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+export const GOV_DECISION_KINDS = [
+    "benefit.grant",
+    "benefit.deny",
+    "visa.decide",
+    "fine.issue",
+    "licence.decide",
+];
+const KIND = /^[a-z][a-z0-9.]{0,63}$/;
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+/** Zanii's pseudonymous, authority-scoped tag for a person's did:key. */
+export function subjectTag(subjectDid, authority) {
+    if (!subjectDid || !authority)
+        throw new Error("subject_did and platform_id are required");
+    return jcsHash({ v: 1, type: "subject_tag", platform: authority, subject: subjectDid });
+}
+/** Zanii's subject claim: "this is my slice", signed with the person's own key. */
+export function signSubjectClaim(input) {
+    if (!validTs(input.ts))
+        throw new Error("ts must be an ISO timestamp");
+    const unsigned = {
+        v: 1,
+        type: "subject_claim",
+        platform: input.platform,
+        subject: input.subjectDid,
+        tag: subjectTag(input.subjectDid, input.platform),
+        ts: input.ts,
+    };
+    const sig = Buffer.from(ed25519Sign(input.subjectPrivateKey, canonicalBytes(unsigned))).toString("hex");
+    return { ...unsigned, sig: `ed25519:${sig}` };
+}
+/** The subject signed it, and the tag derives from that subject at that platform. */
+export function verifySubjectClaim(claim) {
+    const c = (claim ?? {});
+    if (c.v !== 1 || c.type !== "subject_claim")
+        return false;
+    try {
+        if (subjectTag(String(c.subject ?? ""), String(c.platform ?? "")) !== c.tag)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const pub = publicKeyFromDid(String(c.subject));
+    const m = typeof c.sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(c.sig) : null;
+    if (!pub || !m)
+        return false;
+    const { sig: _sig, ...unsigned } = c;
+    return ed25519Verify(pub, canonicalBytes(unsigned), Buffer.from(m[1], "hex"));
+}
+const commit = (factors, nonce) => `sha256:${createHash("sha256")
+    .update(Buffer.from(nonce, "hex"))
+    .update(canonical(factors))
+    .digest("hex")}`;
+/** Zanii's decision payload, v1, for a government decision. No rulebook, no decision. */
+export function decisionPayload(input) {
+    if (!KIND.test(input.kind))
+        throw new Error("kind must be lowercase, 1-64 characters, a-z 0-9 .");
+    if (!input.manifestHash)
+        throw new Error("manifest_hash is required: a state decision with no governing rulebook on record is not auditable, and must not be issued");
+    if (!validTs(input.ts))
+        throw new Error("ts must be an ISO timestamp");
+    if (input.appealBy !== undefined && !validTs(input.appealBy))
+        throw new Error("appeal_by must be an ISO date");
+    const nonce = input.factors !== undefined ? (input.nonce ?? randomBytes(16).toString("hex")) : "";
+    const payload = {
+        _zr_kind: "decision",
+        v: 1,
+        kind: input.kind,
+        manifest_hash: input.manifestHash,
+        outcome: input.outcome,
+        ts: input.ts,
+        ...(input.factors !== undefined ? { factors_commitment: commit(input.factors, nonce) } : {}),
+        ...(input.appealBy !== undefined ? { appeal_by: input.appealBy } : {}),
+        _zr_domain: "gov",
+    };
+    return { payload, nonce };
+}
+/** The disclosed factors and nonce match the commitment made at decision time. */
+export const verifyFactors = (factors, nonce, commitment) => /^[0-9a-f]{32}$/.test(nonce) && commit(factors, nonce) === commitment;
+/** Zanii's structural check of a decision payload. */
+export function verifyDecision(payload) {
+    const p = (payload ?? {});
+    const reasons = [];
+    if (p._zr_kind !== "decision" || p.v !== 1)
+        reasons.push("not a decision receipt (v1)");
+    if (!p.kind)
+        reasons.push("missing kind");
+    if (typeof p.manifest_hash !== "string" || !p.manifest_hash)
+        reasons.push("missing manifest_hash (no governing rulebook)");
+    if (!validTs(p.ts))
+        reasons.push("missing/invalid ts");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Zanii's rulebook windows over time; interleaving is the red flag. */
+export function ruleConsistency(payloads) {
+    const reasons = [];
+    const windows = new Map();
+    const sorted = [...payloads].sort((a, b) => {
+        const x = String(a?.ts);
+        const y = String(b?.ts);
+        return x < y ? -1 : x > y ? 1 : 0;
+    });
+    for (const p of sorted) {
+        const check = verifyDecision(p);
+        if (!check.ok) {
+            reasons.push(`invalid decision: ${check.reasons.join("; ")}`);
+            continue;
+        }
+        const h = String(p.manifest_hash);
+        const ts = String(p.ts);
+        const w = windows.get(h);
+        if (w) {
+            w.count++;
+            w.last_ts = ts;
+        }
+        else
+            windows.set(h, { manifest_hash: h, count: 1, first_ts: ts, last_ts: ts });
+    }
+    const rulebooks = [...windows.values()].sort((a, b) => a.first_ts < b.first_ts ? -1 : a.first_ts > b.first_ts ? 1 : 0);
+    for (let i = 1; i < rulebooks.length; i++) {
+        const prev = rulebooks[i - 1];
+        const cur = rulebooks[i];
+        if (cur.first_ts < prev.last_ts)
+            reasons.push(`rulebooks ${prev.manifest_hash} and ${cur.manifest_hash} interleave — rules differed between people at the same time`);
+    }
+    return { rulebooks, consistent: reasons.length === 0, reasons };
+}
+const LEGAL_BASIS = {
+    en: "This pack is a self-contained, independently verifiable record of the automated decisions taken about the holder by the issuing authority. Each decision names the rulebook that governed it, and the pack is signed by the gateway that recorded it. A court or appointed expert can verify every element offline, without the cooperation of the authority that produced it.",
+    ar: "هذه الحزمة سجلّ قائم بذاته وقابل للتحقّق المستقل للقرارات الآلية التي اتُّخذت بشأن حاملها من قبل الجهة المُصدِرة. يذكر كل قرار القواعد التي حكمته، والحزمة موقّعة من البوابة التي سجّلته. ويمكن للمحكمة أو الخبير المعيّن التحقّق من كل عنصر دون اتصال ودون تعاون الجهة التي أصدرته.",
+};
+const STEPS = [
+    {
+        en: "Verify the pack's signature against the gateway's published log key (did:key).",
+        ar: "تحقّق من توقيع الحزمة مقابل مفتاح السجل المنشور للبوابة (did:key).",
+    },
+    {
+        en: "Verify each decision line hashes (SHA-256) to the event hash given for it: the line is exactly what was recorded.",
+        ar: "تحقّق من أن تجزئة كل سطر قرار (SHA-256) تساوي تجزئة الحدث المذكورة له: السطر هو ما سُجّل بالضبط.",
+    },
+    {
+        en: "Confirm every decision names the rulebook that governed it (manifest_hash): a decision without one is not evidence of a lawful process.",
+        ar: "تأكّد من أنّ كل قرار يذكر القواعد الحاكمة له (بصمة القواعد): فالقرار الخالي منها ليس دليلاً على إجراء سليم.",
+    },
+    {
+        en: "Check rule-consistency: the same rulebook decided everyone in the period, and any change of rules is visible and dated.",
+        ar: "تحقّق من اتساق القواعد: أنّ القواعد نفسها طُبِّقت على الجميع في المدة، وأنّ أي تغيير فيها ظاهر ومؤرَّخ.",
+    },
+    {
+        en: "With the session records the authority discloses, verify each line is in its session's hash chain and under its anchors: it was not added afterwards.",
+        ar: "مع سجلات الجلسات التي تفصح عنها الجهة، تحقّق من أن كل سطر ضمن سلسلة تجزئة جلسته وتحت تثبيتاتها: لم يُضَف لاحقًا.",
+    },
+    {
+        en: "On dispute, the authority discloses the committed decision factors and their nonce; verify they match the commitment made at decision time (no reasoning added afterwards).",
+        ar: "عند النزاع، تفصح الجهة عن عوامل القرار المُلتزَم بها ومعامل الملح؛ تحقّق من مطابقتها للالتزام وقت اتخاذ القرار (لا تبرير لاحق).",
+    },
+];
+/** spec/gov.md §3: the citizen's appeal pack over the decisions recorded about their tag. */
+export function appealPack(items, opts) {
+    const payloads = items.map((i) => i.decision);
+    const times = payloads
+        .map((p) => p?.ts)
+        .filter((t) => typeof t === "string")
+        .sort();
+    return {
+        v: 1,
+        legal_basis: LEGAL_BASIS,
+        subject_tag: opts.tag,
+        authority: opts.authority,
+        decisions: items.length,
+        rules: ruleConsistency(payloads),
+        unruled: payloads.filter((p) => !verifyDecision(p).ok).length,
+        period: { first: times[0] ?? null, last: times.at(-1) ?? null },
+        items: items.map(({ session_id, seq, line, event_hash, anchored }) => ({
+            session_id,
+            seq,
+            line,
+            event_hash,
+            anchored,
+        })),
+        steps: STEPS.map((s, i) => ({ n: i + 1, ...s })),
+        generated_at: opts.generated_at,
+    };
+}
+/** The reading copy for an administrative judge: `en`, `ar` or `both` (headers always bilingual). */
+export function renderAppealPack(pack, lang = "both") {
+    const show = (b) => (lang === "en" ? b.en : lang === "ar" ? b.ar : `${b.en}\n\n> ${b.ar}`);
+    const steps = pack.steps.map((s) => `${s.n}. ${show(s)}`).join("\n");
+    const rulebooks = pack.rules.rulebooks
+        .map((w) => `- \`${w.manifest_hash}\` — ${w.count} decision(s), ${w.first_ts} → ${w.last_ts}`)
+        .join("\n") || "- (none)";
+    const flags = [];
+    if (!pack.rules.consistent)
+        flags.push("⚠️ RULES INTERLEAVED — different rulebooks decided people at the same time");
+    if (pack.unruled > 0)
+        flags.push(`❌ ${pack.unruled} decision(s) carry NO governing rulebook`);
+    const findings = flags.length
+        ? `## Findings / النتائج\n\n${flags.map((f) => `- ${f}`).join("\n")}\n\n`
+        : "";
+    const p = pack.period;
+    return ("# Appeal Pack / حزمة الطعن\n\n" +
+        `- **Subject (pseudonymous) / الشخص المعني (مستعار):** \`${pack.subject_tag}\`\n` +
+        `- **Authority / الجهة:** ${pack.authority || "—"}\n` +
+        `- **Decisions / القرارات:** ${pack.decisions}\n` +
+        `- **Period / المدة:** ${p.first ?? "—"} → ${p.last ?? "—"}\n\n` +
+        findings +
+        `## Legal basis / الأساس القانوني\n\n${show(pack.legal_basis)}\n\n` +
+        `## Rulebooks applied / القواعد المطبَّقة\n\n${rulebooks}\n\n` +
+        `## Verification steps / خطوات التحقّق\n\n${steps}\n\n` +
+        "## What this does and does not prove / ما تثبته هذه الحزمة وما لا تثبته\n\n" +
+        "It proves the **process**: the same rules decided everyone, the record is complete and " +
+        "unaltered, and the inputs were committed at decision time. It does **not** prove the " +
+        "decision was *just* — a rule applied consistently may still be unlawful. That judgment " +
+        "is the court's.\n\n" +
+        "> تُثبت هذه الحزمة **سلامة الإجراء**: أنّ القواعد نفسها طُبِّقت على الجميع، وأنّ السجل كامل " +
+        "وغير مُعدَّل، وأنّ المعطيات التُزم بها وقت القرار. ولا تُثبت **عدالة** القرار — فالقاعدة " +
+        "المطبَّقة باتساق قد تظل مخالفة للقانون، وهذا تقدير المحكمة.\n");
+}