@zanii/blackbox 0.2.0 → 0.4.0

package/dist/compliance/art12.js

@@ -0,0 +1,190 @@
+// EU AI Act Article 12 (record-keeping) for one session's record (spec/art12.md): what the record
+// shows against Art. 12(1), 12(2)(a)-(c), 12(3)(a)-(d), and the six-month log retention of Art. 19(1)
+// and 26(6). Evidence mapping from the public text of Regulation (EU) 2024/1689, not legal advice.
+// Mirrors sdks/python/src/zanii_blackbox/art12.py.
+/** Art. 19(1) and 26(6): "at least six months". Counted as 183 days, the longest six months. */
+export const ART12_MIN_RETENTION_DAYS = 183;
+// "ciba" closes a call its people already voted on (spec/approvals.md §7): the votes are counted
+const NOT_PEOPLE = new Set(["timeout", "unattended", "classifier", "ciba"]);
+const NOTES = "Evidence mapping from the public text of Regulation (EU) 2024/1689, not legal advice. Article 12 applies to high-risk AI systems; whether a system is one, and whether it complies, is for its provider, deployer and counsel to judge. One session shows one period of use, not the system's lifetime.";
+const sorted = (s) => [...new Set(s)].sort();
+/** The person an approval decision names: an SSO login (authenticated) or a key holder's word. */
+function personOf(p) {
+    if (typeof p !== "object" || p === null)
+        return null;
+    const o = p;
+    const s = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+    if (o.authenticated === true && s(o.sub))
+        return {
+            key: `sub:${s(o.iss) ?? ""}#${o.sub}`,
+            label: s(o.email) ?? s(o.name) ?? o.sub,
+            authenticated: true,
+        };
+    if (o.asserted === true && s(o.name))
+        return { key: `name:${o.name}`, label: o.name, authenticated: false };
+    return null;
+}
+const count = (into, key) => {
+    into[key] = (into[key] ?? 0) + 1;
+};
+/**
+ * Checks one session's record against Article 12. `verified`: whether its chain verifies (the caller
+ * runs the check). `retentionDays`: the deployment's retention, null when records are kept forever.
+ * `annexIII1a`: the system is a remote biometric identification system, so 12(3) applies.
+ */
+export function art12Check(record, options) {
+    const events = record.lines.map((l) => JSON.parse(l));
+    const annex = options.annexIII1a === true;
+    let gaps = 0;
+    let lostContact = 0;
+    let errors = 0;
+    let inputs = 0;
+    let outcome = null;
+    const findings = {};
+    const codes = [];
+    const controls = {};
+    const models = [];
+    const providers = [];
+    const sources = [];
+    // spec/approvals.md §2.1: each human decision, and the person it names (if any)
+    const human = [];
+    for (const e of events) {
+        const m = e.meta;
+        if (e.kind === "capture.gap")
+            gaps += typeof m.missed === "number" ? m.missed : 1;
+        else if (e.kind === "session.lost_contact")
+            lostContact++;
+        else if (e.kind === "finding") {
+            count(findings, typeof m.severity === "string" ? m.severity : "unknown");
+            if (typeof m.code === "string")
+                codes.push(m.code);
+        }
+        else if (e.kind === "control" && typeof m.action === "string") {
+            count(controls, m.action);
+            if (m.action === "approval" && typeof m.by === "string") {
+                if (!NOT_PEOPLE.has(m.by))
+                    human.push(personOf(m.person));
+            }
+            if (m.action === "approval_vote" && m.counted !== false && m.person !== undefined)
+                human.push(personOf(m.person));
+        }
+        else if (e.kind === "llm.request") {
+            inputs++;
+            if (typeof m.provider === "string")
+                providers.push(m.provider);
+        }
+        else if (e.kind === "llm.response") {
+            if (typeof m.model === "string")
+                models.push(m.model);
+            if (typeof m.status === "number" && m.status >= 400)
+                errors++;
+        }
+        else if (e.kind === "tool.call") {
+            inputs++;
+            if (typeof m.server === "string")
+                sources.push(typeof m.tool === "string" ? `${m.server}/${m.tool}` : m.server);
+        }
+        else if (e.kind === "outcome" && typeof m.outcome === "string")
+            outcome = m.outcome;
+    }
+    const open = events.find((e) => e.kind === "session.open");
+    const close = events.find((e) => e.kind === "session.close");
+    const named = human.filter((p) => p !== null);
+    const persons = new Map(named.map((p) => [p.key, p.label]));
+    const authenticated = named.filter((p) => p.authenticated).length;
+    const retention = options.retentionDays;
+    const checks = [
+        {
+            id: "automatic-recording",
+            article: "12(1)",
+            requirement: "Events are recorded automatically over the system's lifetime: here, a record that verifies and has no capture gaps.",
+            applies: true,
+            ok: record.verified && open !== undefined && gaps === 0,
+            evidence: {
+                events: events.length,
+                verified: record.verified,
+                capture_gaps: gaps,
+                lost_contact: lostContact,
+            },
+        },
+        {
+            id: "risk-situations",
+            article: "12(2)(a)",
+            requirement: "Events relevant to identifying situations that may present a risk (Art. 79(1)) or a substantial modification.",
+            applies: true,
+            ok: null,
+            evidence: { findings, finding_codes: sorted(codes), models: sorted(models) },
+        },
+        {
+            id: "post-market-monitoring",
+            article: "12(2)(b)",
+            requirement: "Events that facilitate post-market monitoring (Art. 72).",
+            applies: true,
+            ok: null,
+            evidence: { providers: sorted(providers), models: sorted(models), errors, outcome },
+        },
+        {
+            id: "operation-monitoring",
+            article: "12(2)(c)",
+            requirement: "Events for deployers' monitoring of the system's operation (Art. 26(5)).",
+            applies: true,
+            ok: null,
+            evidence: { controls, unattended: open?.meta.unattended === true },
+        },
+        {
+            id: "period-of-use",
+            article: "12(3)(a)",
+            requirement: "The start and end date and time of each use.",
+            applies: annex,
+            ok: open !== undefined && close !== undefined,
+            evidence: { start: open?.ts ?? null, end: close?.ts ?? null },
+        },
+        {
+            id: "reference-database",
+            article: "12(3)(b)",
+            requirement: "The reference database against which input data was checked.",
+            applies: annex,
+            ok: null,
+            evidence: { sources: sorted(sources) },
+        },
+        {
+            id: "input-data",
+            article: "12(3)(c)",
+            requirement: "The input data for which the search led to a match.",
+            applies: annex,
+            ok: null,
+            evidence: { inputs },
+        },
+        {
+            id: "verifying-persons",
+            article: "12(3)(d), 14(5)",
+            requirement: "The natural persons who verified the results; for Art. 14(5), at least two, separately.",
+            applies: annex,
+            // every human decision names its person, and at least two different people decided
+            ok: human.length === 0 ? null : named.length === human.length && persons.size >= 2,
+            evidence: {
+                decisions: human.length,
+                persons: sorted(persons.values()),
+                authenticated,
+                asserted: named.length - authenticated,
+                unnamed: human.length - named.length,
+            },
+        },
+        {
+            id: "log-retention",
+            article: "19(1), 26(6)",
+            requirement: "Logs are kept for at least six months, unless other Union or national law says otherwise.",
+            applies: true,
+            ok: retention === null || retention >= ART12_MIN_RETENTION_DAYS,
+            evidence: { retention_days: retention, minimum_days: ART12_MIN_RETENTION_DAYS },
+        },
+    ];
+    return {
+        session_id: events[0]?.session_id ?? "",
+        regulation: "Regulation (EU) 2024/1689",
+        annex_iii_1a: annex,
+        ok: checks.every((c) => !c.applies || c.ok !== false),
+        checks,
+        notes: NOTES,
+    };
+}

package/dist/compliance/index.d.ts

@@ -1,4 +1,4 @@
-export type FactValue = number | string | null | Record<string, number>;
+export type FactValue = number | string | null | Record<string, number | string>;
 export type Facts = Record<string, FactValue>;
 export interface Framework {
     title: string;
@@ -8,6 +8,14 @@ export interface Framework {
         requirement: string;
         facts: string[];
     }>;
+    /** spec/packs.md §1: the framework in Arabic, by section id. */
+    ar?: {
+        title: string;
+        sections: Record<string, {
+            title: string;
+            requirement: string;
+        }>;
+    };
 }
 export interface Report {
     framework: string;
@@ -24,6 +32,8 @@ export interface Report {
         evidence: Facts;
     }>;
     notes: string;
+    /** "ar" when the report is in Arabic (spec/compliance.md §3). */
+    lang?: "ar";
 }
 export declare function complianceReport(frameworkId: string, framework: Framework, facts: Facts, meta: {
     tenant_id: string;
@@ -31,7 +41,8 @@ export declare function complianceReport(frameworkId: string, framework: Framewo
     to: string;
     generated_at: string;
     notes: string;
-}): Report;
+    notes_ar?: string;
+}, lang?: "en" | "ar"): Report;
 export declare function renderReport(r: Report): string;
 /** spec/compliance.md §1: the facts over sessions' records (the server adds verified / anchored). */
 export declare function complianceFacts(sessions: ReadonlyArray<{
@@ -39,3 +50,26 @@ export declare function complianceFacts(sessions: ReadonlyArray<{
     verified: boolean;
     anchored: boolean;
 }>, dataRegion: string | null): Facts;
+/** spec/compliance.md §1a: what a period's records say about hallucinations and their checks. */
+export declare function hallucinationFacts(sessions: ReadonlyArray<{
+    lines: readonly string[];
+}>): Facts;
+/** §1a: `detector_accuracy`, the labels' overall figures (spec/findings.md §12) as percentages. */
+export declare function accuracyFact(a: {
+    labels: number;
+    overall: {
+        precision: number | null;
+        recall: number | null;
+        precision_low: number | null;
+        recall_low: number | null;
+    };
+}): Record<string, number | string>;
+/** §1a: `hallucination_controls`, which checks ran (spec/findings.md §8-§12). */
+export declare function controlsFact(o: {
+    packs: ReadonlyArray<{
+        id: string;
+        version: string;
+    }>;
+    grounding: boolean;
+    judge: boolean;
+}): Record<string, string>;

package/dist/compliance/index.js

@@ -1,40 +1,53 @@
 // Compliance reports (spec/compliance.md): facts from the record, mapped onto a framework's sections,
 // and rendered as Markdown. Evidence mapping, not legal advice. Mirrors sdks/python/src/zanii_blackbox/compliance.py.
-export function complianceReport(frameworkId, framework, facts, meta) {
+export function complianceReport(frameworkId, framework, facts, meta, lang = "en") {
+    // spec/compliance.md §3: in Arabic when the framework has its Arabic; English otherwise
+    const ar = lang === "ar" ? framework.ar : undefined;
+    const { notes_ar, ...rest } = meta;
     return {
         framework: frameworkId,
-        title: framework.title,
-        ...meta,
+        title: ar?.title ?? framework.title,
+        ...rest,
+        notes: ar && notes_ar ? notes_ar : meta.notes,
         facts,
         sections: framework.sections.map((s) => ({
             id: s.id,
-            title: s.title,
-            requirement: s.requirement,
+            title: ar?.sections[s.id]?.title ?? s.title,
+            requirement: ar?.sections[s.id]?.requirement ?? s.requirement,
             evidence: Object.fromEntries(s.facts.map((f) => [f, facts[f] ?? null])),
         })),
+        ...(ar ? { lang: "ar" } : {}),
     };
 }
-const show = (v) => {
+const show = (v, ar = false) => {
     if (v === null)
-        return "not set";
+        return ar ? "غير محدد" : "not set";
     if (typeof v === "object") {
         const keys = Object.keys(v).sort();
-        return keys.length === 0 ? "none" : keys.map((k) => `${k}: ${v[k]}`).join(", ");
+        return keys.length === 0
+            ? ar
+                ? "لا شيء"
+                : "none"
+            : keys.map((k) => `${k}: ${v[k]}`).join(", ");
     }
     return String(v);
 };
 export function renderReport(r) {
+    const ar = r.lang === "ar";
     const out = [
         `# ${r.title}`,
         "",
-        `Tenant \`${r.tenant_id}\` · sessions created from ${r.from} to ${r.to} (exclusive) · generated ${r.generated_at}`,
+        ar
+            ? `المستأجر \`${r.tenant_id}\` · الجلسات المنشأة من ${r.from} إلى ${r.to} (غير شامل) · أُنشئ في ${r.generated_at}`
+            : `Tenant \`${r.tenant_id}\` · sessions created from ${r.from} to ${r.to} (exclusive) · generated ${r.generated_at}`,
         "",
         `> ${r.notes}`,
     ];
     for (const s of r.sections) {
-        out.push("", `## ${s.title}`, "", s.requirement, "", "| Evidence | Value |", "|---|---|");
+        const head = ar ? "| الدليل | القيمة |" : "| Evidence | Value |";
+        out.push("", `## ${s.title}`, "", s.requirement, "", head, "|---|---|");
         for (const [k, v] of Object.entries(s.evidence))
-            out.push(`| ${k} | ${show(v)} |`);
+            out.push(`| ${k} | ${show(v, ar)} |`);
     }
     return `${out.join("\n")}\n`;
 }
@@ -94,3 +107,57 @@ export function complianceFacts(sessions, dataRegion) {
         data_region: dataRegion,
     };
 }
+// ---------------------------------------------------------------- hallucination facts (§1a, H6)
+/** spec/compliance.md §1a: what a period's records say about hallucinations and their checks. */
+export function hallucinationFacts(sessions) {
+    let responses = 0;
+    const codes = {};
+    const grounding = { checked: 0, outages: 0 };
+    const judge = { checked: 0, outages: 0 };
+    for (const s of sessions)
+        for (const line of s.lines) {
+            const e = JSON.parse(line);
+            const m = e.meta;
+            if (e.kind === "llm.response")
+                responses++;
+            else if (e.kind === "finding" && m.source === "hallucination" && typeof m.code === "string")
+                codes[m.code] = (codes[m.code] ?? 0) + 1;
+            else if (e.kind === "control" && (m.action === "grounding" || m.action === "judge")) {
+                const c = m.action === "grounding" ? grounding : judge;
+                if (m.outage === true)
+                    c.outages++;
+                else
+                    c.checked++;
+            }
+        }
+    return {
+        model_responses: responses,
+        hallucination_findings: codes,
+        grounding_checks: grounding,
+        judge_checks: judge,
+    };
+}
+/** A 0-1 figure as a percentage with two decimals, from whole basis points (exact in both SDKs). */
+function percent(x) {
+    const bp = Math.floor(x * 10_000 + 0.5);
+    return `${Math.floor(bp / 100)}.${String(bp % 100).padStart(2, "0")}%`;
+}
+/** §1a: `detector_accuracy`, the labels' overall figures (spec/findings.md §12) as percentages. */
+export function accuracyFact(a) {
+    const out = { labels: a.labels };
+    for (const k of ["precision", "precision_low", "recall", "recall_low"]) {
+        const v = a.overall[k];
+        if (v !== null)
+            out[k] = percent(v);
+    }
+    return out;
+}
+/** §1a: `hallucination_controls`, which checks ran (spec/findings.md §8-§12). */
+export function controlsFact(o) {
+    return {
+        exact_checks: "on",
+        reference_packs: o.packs.length ? o.packs.map((p) => `${p.id}@${p.version}`).join(" ") : "none",
+        grounding_service: o.grounding ? "on" : "off",
+        judge: o.judge ? "on" : "off",
+    };
+}

package/dist/compliance/zanii.d.ts

@@ -0,0 +1,29 @@
+import type { Bundle, BundleReport } from "../verify/index.ts";
+export declare function zaniiCompliance(bundle: Bundle, report: BundleReport, opts: {
+    generated_at: string;
+    controls?: Readonly<Record<string, string>>;
+}): {
+    agent_id: string;
+    generated_at: string;
+    verified: boolean;
+    period: {
+        first: string | null;
+        last: string | null;
+    };
+    total_actions: number;
+    by_namespace: Record<string, number>;
+    anchored: {
+        count: number;
+        total: number;
+        complete: boolean;
+    };
+    controls: {
+        namespace: string;
+        control: string;
+        actions: number;
+    }[];
+    flags: string[];
+};
+export type ZaniiComplianceReport = ReturnType<typeof zaniiCompliance>;
+/** Zanii's Markdown, as zanii.compliance.render_compliance_markdown gives it. */
+export declare function renderZaniiCompliance(r: ZaniiComplianceReport): string;

package/dist/compliance/zanii.js

@@ -0,0 +1,84 @@
+// Zanii's compliance report, from a session (spec/compliance.md §4): @zanii/compliance's
+// ComplianceReport fields and its Markdown, so a customer's own Zanii tooling reads our evidence.
+// Pure; mirrors sdks/python/src/zanii_blackbox/compliance.py; pinned by
+// spec/vectors/zanii-compliance.json.
+function namespaceOf(e) {
+    const m = e.meta ?? {};
+    if (e.kind === "llm.request")
+        return `model:${String(m.provider ?? "unknown")}`;
+    if (e.kind === "tool.call")
+        return `tool:${String(m.server ?? m.via ?? "unknown")}`;
+    if (e.kind === "sdk.event" && m.type === "tool.call")
+        return "tool:sdk";
+    return null;
+}
+export function zaniiCompliance(bundle, report, opts) {
+    const events = bundle.lines.map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return {};
+        }
+    });
+    const anchoredThrough = bundle.anchors.at(-1)?.count ?? 0;
+    const byNamespace = {};
+    let total = 0;
+    let anchored = 0;
+    for (const e of events) {
+        const ns = namespaceOf(e);
+        if (ns === null)
+            continue;
+        byNamespace[ns] = (byNamespace[ns] ?? 0) + 1;
+        total++;
+        if (typeof e.seq === "number" && e.seq < anchoredThrough)
+            anchored++;
+    }
+    const controls = Object.entries(byNamespace).map(([namespace, actions]) => ({
+        namespace,
+        control: opts.controls?.[namespace] ?? "(unmapped)",
+        actions,
+    }));
+    const flags = [];
+    if (!report.ok)
+        flags.push("bundle FAILED offline verification — treat all figures below as unproven");
+    if (anchored < total)
+        flags.push(`${total - anchored} of ${total} receipts are not yet anchored on-chain`);
+    if (opts.controls) {
+        const unmapped = controls.filter((c) => c.control === "(unmapped)").map((c) => c.namespace);
+        if (unmapped.length)
+            flags.push(`no control mapped for namespace(s): ${unmapped.join(", ")}`);
+    }
+    const ts = (e) => (typeof e?.ts === "string" ? e.ts : null);
+    return {
+        agent_id: bundle.anchored_by ?? "",
+        generated_at: opts.generated_at,
+        verified: report.ok,
+        period: { first: ts(events[0]), last: ts(events.at(-1)) },
+        total_actions: total,
+        by_namespace: byNamespace,
+        anchored: { count: anchored, total, complete: anchored >= total },
+        controls,
+        flags,
+    };
+}
+/** Zanii's Markdown, as zanii.compliance.render_compliance_markdown gives it. */
+export function renderZaniiCompliance(r) {
+    // Python's sort is stable, as JavaScript's is: equal counts keep their order
+    const rows = [...r.controls]
+        .sort((a, b) => b.actions - a.actions)
+        .map((c) => `| \`${c.namespace}\` | ${c.control} | ${c.actions} |`)
+        .join("\n") || "| — | — | 0 |";
+    const flags = r.flags.length ? r.flags.map((f) => `- ⚠️ ${f}`).join("\n") : "- ✅ none";
+    return ("# Zanii Compliance Report\n\n" +
+        `- **Agent:** \`${r.agent_id}\`\n` +
+        `- **Generated:** ${r.generated_at}\n` +
+        `- **Verification:** ${r.verified ? "✅ PROVEN offline" : "❌ FAILED"}\n` +
+        `- **Period:** ${r.period.first ?? "—"} → ${r.period.last ?? "—"}\n` +
+        `- **Actions:** ${r.total_actions} (${r.anchored.count}/${r.anchored.total} anchored on-chain)\n\n` +
+        "## Actions by control\n\n" +
+        "| Namespace | Control | Actions |\n| --- | --- | --- |\n" +
+        `${rows}\n\n` +
+        "## Findings\n\n" +
+        `${flags}\n`);
+}

package/dist/constitution/index.d.ts

@@ -0,0 +1,57 @@
+export type Effect = "forbid" | "require_approval" | "allow";
+export interface ConstitutionRule {
+    id: string;
+    effect: Effect;
+    targets: string[];
+    note?: string;
+}
+export interface Constitution {
+    v: 1;
+    type: "constitution";
+    issuer: string;
+    name: string;
+    rules: ConstitutionRule[];
+    default: "allow" | "forbid";
+    created_at: string;
+    sig: string;
+}
+/** Builds and signs the rulebook; rules are evaluated first match wins, top to bottom. */
+export declare function createConstitution(input: {
+    issuer: string;
+    name: string;
+    rules: ConstitutionRule[];
+    defaultEffect?: "allow" | "forbid";
+    createdAt: string;
+    issuerPrivateKey: Uint8Array;
+}): Constitution;
+/** Structure and the issuer's signature. */
+export declare function verifyConstitution(c: unknown): boolean;
+/** The `manifest_hash`: RFC 8785 JSON, SHA-256. */
+export declare const constitutionHash: (c: Constitution) => string;
+/** First match wins, then the default. */
+export declare function evaluateConstitution(c: Constitution, target: string): {
+    effect: Effect;
+    rule: ConstitutionRule;
+} | {
+    effect: Effect;
+    rule: null;
+};
+/** spec/governance.md §3: a session's record against the rulebook. */
+export declare function governanceOf(lines: readonly string[], c: Constitution): {
+    manifest_hash: string;
+    governed: boolean;
+    ok: boolean;
+    actions: number;
+    violations: {
+        seq: number;
+        target: string;
+        kind: string;
+        rule_id?: string;
+    }[];
+    approvals_required: {
+        seq: number;
+        target: string;
+        rule_id: string;
+        approved: boolean;
+    }[];
+};

package/dist/constitution/index.js

@@ -0,0 +1,131 @@
+// The signed rulebook (spec/governance.md), in Zanii's constitution v1 format, byte for byte with
+// @zanii/constitution / zanii.constitution, and a session's governance against it. Pure; mirrors
+// sdks/python/src/zanii_blackbox/constitution.py; pinned by spec/vectors/governance.json.
+import { canonicalBytes, jcsHash, publicKeyFromDid, scopeCovers } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const EFFECTS = new Set(["forbid", "require_approval", "allow"]);
+/** Builds and signs the rulebook; rules are evaluated first match wins, top to bottom. */
+export function createConstitution(input) {
+    const { issuer, name, rules, defaultEffect = "allow", createdAt } = input;
+    if (!issuer)
+        throw new Error("issuer is required");
+    if (!name)
+        throw new Error("name is required");
+    if (!rules.length)
+        throw new Error("a constitution with no rules constrains nothing");
+    const ids = new Set();
+    for (const r of rules) {
+        if (!r.id)
+            throw new Error("every rule needs an id");
+        if (ids.has(r.id))
+            throw new Error(`duplicate rule id '${r.id}'`);
+        ids.add(r.id);
+        if (!EFFECTS.has(r.effect))
+            throw new Error(`rule '${r.id}': invalid effect '${r.effect}'`);
+        if (!r.targets?.length)
+            throw new Error(`rule '${r.id}' has no targets`);
+    }
+    if (defaultEffect !== "allow" && defaultEffect !== "forbid")
+        throw new Error("default_effect must be 'allow' or 'forbid'");
+    if (Number.isNaN(Date.parse(createdAt)))
+        throw new Error("created_at must be an ISO timestamp");
+    const unsigned = {
+        v: 1,
+        type: "constitution",
+        issuer,
+        name,
+        rules,
+        default: defaultEffect,
+        created_at: createdAt,
+    };
+    const sig = Buffer.from(ed25519Sign(input.issuerPrivateKey, canonicalBytes(unsigned))).toString("hex");
+    return { ...unsigned, sig: `ed25519:${sig}` };
+}
+/** Structure and the issuer's signature. */
+export function verifyConstitution(c) {
+    const p = (c ?? {});
+    if (p.v !== 1 || p.type !== "constitution" || !p.issuer || !p.name)
+        return false;
+    if (!Array.isArray(p.rules) || p.rules.length === 0)
+        return false;
+    const ids = p.rules.map((r) => (r && typeof r === "object" ? r.id : undefined));
+    if (new Set(ids).size !== ids.length)
+        return false;
+    for (const r of p.rules)
+        if (!r || typeof r !== "object" || !EFFECTS.has(r.effect) || !r.targets?.length)
+            return false;
+    if (p.default !== "allow" && p.default !== "forbid")
+        return false;
+    const pub = publicKeyFromDid(p.issuer);
+    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"));
+}
+/** The `manifest_hash`: RFC 8785 JSON, SHA-256. */
+export const constitutionHash = (c) => jcsHash(c);
+/** First match wins, then the default. */
+export function evaluateConstitution(c, target) {
+    for (const r of c.rules)
+        if (r.targets.some((t) => scopeCovers(t, target)))
+            return { effect: r.effect, rule: r };
+    return { effect: c.default, rule: null };
+}
+/** spec/governance.md §3: the action's target, or null when the event isn't an action. */
+function targetOf(e) {
+    const m = e.meta;
+    const policy = m.policy;
+    if (policy?.action === "deny")
+        return null; // refused: it never ran
+    if (e.kind === "tool.call" && typeof m.tool === "string")
+        return m.server !== undefined
+            ? `mcp.${String(m.server)}.${m.tool}`
+            : `tool.${String(m.via)}.${m.tool}`;
+    if (e.kind === "llm.request")
+        return `model.${String(m.provider ?? "unknown")}`;
+    if (e.kind === "sdk.event" && m.type === "tool.call")
+        return `sdk.${String(m.name ?? "unknown")}`;
+    return null;
+}
+/** spec/governance.md §3: a session's record against the rulebook. */
+export function governanceOf(lines, c) {
+    const manifest = constitutionHash(c);
+    const events = lines.map((l) => JSON.parse(l));
+    const open = events.find((e) => e.kind === "session.open");
+    const governed = open?.meta.manifest_hash === manifest;
+    const approved = new Set(events
+        .filter((e) => e.kind === "control" && e.meta.action === "approval" && e.meta.decision === "approve")
+        .map((e) => e.meta.call_seq));
+    const violations = [];
+    const approvals = [];
+    let actions = 0;
+    for (const e of events) {
+        const target = targetOf(e);
+        if (target === null)
+            continue;
+        actions++;
+        if (!governed) {
+            violations.push({ seq: e.seq, target, kind: "ungoverned" });
+            continue;
+        }
+        const ev = evaluateConstitution(c, target);
+        if (ev.effect === "forbid")
+            violations.push({
+                seq: e.seq,
+                target,
+                kind: "forbidden",
+                ...(ev.rule ? { rule_id: ev.rule.id } : {}),
+            });
+        else if (ev.effect === "require_approval" && ev.rule)
+            approvals.push({ seq: e.seq, target, rule_id: ev.rule.id, approved: approved.has(e.seq) });
+    }
+    return {
+        manifest_hash: manifest,
+        governed,
+        ok: violations.length === 0,
+        actions,
+        violations,
+        approvals_required: approvals,
+    };
+}