@zanii/blackbox 0.3.0 → 0.4.0

package/dist/cli.js

@@ -37,6 +37,10 @@ const USAGE = `usage (spec/cli.md):
   blackbox analyze <bundle.json> [--bodies <dir>] [--prices <file>]
   blackbox verify-certificate <certificate.json> [--did <did:key:…>]
   blackbox investigate <bundle.json> [--bodies <dir>] [--directives <file>] [--identity <file>] [--proofs] [--out <prefix>]
+  blackbox evidence-pack <bundle.json> [--proofs] [--identity <file>] [--lang en|ar|both] [--out <prefix>]
+  blackbox sign-constitution <draft.json> --identity <owner.json> [--out <file>]
+  blackbox policy-from-zanii <zanii-policy.json> [--out <file>]
+  blackbox policy-to-zanii <policy.json> [--out <file>]
   blackbox statement --provider anthropic|openai --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
   blackbox statement --provider csv --file <f> --model-column <name> --amount-column <name> --unit usd|cents|micro_usd|aed [--delimiter <c>] --from <d> --to <d> [--out <file>]
   blackbox statement --provider custom --connector <file> --from <d> --to <d> [--out <file>]
@@ -88,6 +92,12 @@ async function main(argv) {
         return preflightCommand(rest);
     if (command === "investigate")
         return investigateCommand(rest);
+    if (command === "evidence-pack")
+        return evidencePackCommand(rest);
+    if (command === "sign-constitution")
+        return signConstitutionCommand(rest);
+    if (command === "policy-from-zanii" || command === "policy-to-zanii")
+        return policyZaniiCommand(command, rest);
     if (command === "statement")
         return statementCommand(rest);
     if (command === "export-all")
@@ -607,6 +617,107 @@ async function certificateCommand(rest) {
     return result.ok ? 0 : 1;
 }
 /** spec/investigations.md §2: an independent investigator's signed report, offline. */
+/** A signing identity file `{did, private_key}` (the gateway's identity file works as is). */
+async function readIdentity(path) {
+    const { didFromSeed } = await import("./fleet/index.js");
+    const file = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof file.private_key !== "string" || !/^[0-9a-f]{64}$/.test(file.private_key))
+        throw new Error("identity file: private_key must be 64 hex characters");
+    const seed = Buffer.from(file.private_key, "hex");
+    if (file.did !== didFromSeed(seed))
+        throw new Error("identity file: did doesn't match private_key");
+    return { did: file.did, seed };
+}
+/** spec/policy.md §8: a Zanii policy file as a Blackbox one, or back; skipped rules are named. */
+async function policyZaniiCommand(command, rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length !== 1)
+        return usage();
+    const { fromZaniiPolicy, toZaniiPolicy } = await import("./policy/zanii.js");
+    try {
+        const input = JSON.parse(readFileSync(positional[0], "utf8"));
+        const r = command === "policy-from-zanii" ? fromZaniiPolicy(input) : toZaniiPolicy(input);
+        const out = flags.out || (command === "policy-from-zanii" ? "policy.json" : "zanii-policy.json");
+        writeFileSync(out, `${JSON.stringify(r.policy, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ok: true, file: out, rules: r.policy.rules.length, skipped: r.skipped })}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+        return 2;
+    }
+}
+/** spec/governance.md §1: signs a draft rulebook `{name, rules, default?}` as the identity's DID. */
+async function signConstitutionCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    if (positional.length !== 1 || !flags.identity)
+        return usage();
+    const { constitutionHash, createConstitution } = await import("./constitution/index.js");
+    try {
+        const draft = JSON.parse(readFileSync(positional[0], "utf8"));
+        const identity = await readIdentity(flags.identity);
+        const c = createConstitution({
+            issuer: identity.did,
+            name: String(draft.name ?? ""),
+            rules: (Array.isArray(draft.rules) ? draft.rules : []),
+            defaultEffect: (draft.default ?? "allow"),
+            createdAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+            issuerPrivateKey: identity.seed,
+        });
+        const out = flags.out || "constitution.json";
+        writeFileSync(out, `${JSON.stringify(c, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ok: true, file: out, manifest_hash: constitutionHash(c), issuer: c.issuer })}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`);
+        return 2;
+    }
+}
+/** spec/investigations.md §7: the court evidence pack, `<prefix>.json` (signed) and `<prefix>.md`. */
+async function evidencePackCommand(rest) {
+    const { flags, positional } = parse(rest, ["--proofs"]);
+    const lang = flags.lang ?? "both";
+    if (positional.length !== 1 || !["en", "ar", "both"].includes(lang))
+        return usage();
+    const fail = (error) => {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: String(error) })}\n`);
+        return 2;
+    };
+    const { evidencePack, renderEvidencePack } = await import("./evidence/index.js");
+    const { signCertificate } = await import("./fleet/index.js");
+    let raw;
+    let bundle;
+    let identity;
+    try {
+        raw = readFileSync(positional[0]);
+        bundle = JSON.parse(raw.toString("utf8"));
+        if (!Array.isArray(bundle.lines) || bundle.lines.length === 0)
+            throw new Error("the bundle has no lines");
+        if (flags.identity)
+            identity = await readIdentity(flags.identity);
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : error);
+    }
+    const proofs = flags.proofs === "1";
+    const pack = evidencePack(bundle, await verifyBundle(bundle, { proofs }), {
+        generated_at: new Date().toISOString(),
+        bundle_sha256: `sha256:${createHash("sha256").update(raw).digest("hex")}`,
+        proofs: proofs ? "checked" : "not_checked",
+    });
+    const final = identity ? signCertificate(pack, identity.did, identity.seed) : pack;
+    const prefix = flags.out || `evidence-${pack.session_id}`;
+    try {
+        writeFileSync(`${prefix}.json`, `${JSON.stringify(final)}\n`);
+        writeFileSync(`${prefix}.md`, renderEvidencePack(pack, lang));
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : error);
+    }
+    process.stdout.write(`${JSON.stringify({ ok: pack.verified, json: `${prefix}.json`, md: `${prefix}.md`, signed_by: identity?.did ?? null })}\n`);
+    return pack.verified ? 0 : 1;
+}
 async function investigateCommand(rest) {
     const { flags, positional } = parse(rest, ["--proofs"]);
     if (positional.length !== 1)
@@ -617,7 +728,7 @@ async function investigateCommand(rest) {
     };
     const { investigation, renderInvestigation } = await import("./investigate/index.js");
     const { loadPrices, sessionCost } = await import("./cost/index.js");
-    const { didFromSeed, sessionSummary, signCertificate } = await import("./fleet/index.js");
+    const { sessionSummary, signCertificate } = await import("./fleet/index.js");
     let raw;
     let bundle;
     let directives;
@@ -637,15 +748,8 @@ async function investigateCommand(rest) {
                 throw new Error("--directives must hold a list of directives");
             directives = list;
         }
-        if (flags.identity) {
-            const file = JSON.parse(readFileSync(flags.identity, "utf8"));
-            if (typeof file.private_key !== "string" || !/^[0-9a-f]{64}$/.test(file.private_key))
-                throw new Error("identity file: private_key must be 64 hex characters");
-            const seed = Buffer.from(file.private_key, "hex");
-            if (file.did !== didFromSeed(seed))
-                throw new Error("identity file: did doesn't match private_key");
-            identity = { did: file.did, seed };
-        }
+        if (flags.identity)
+            identity = await readIdentity(flags.identity);
     }
     catch (error) {
         return fail(error instanceof Error ? error.message : error);

package/dist/compliance/art12.js

@@ -4,9 +4,26 @@
 // 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;
-const NOT_PEOPLE = new Set(["timeout", "unattended", "classifier"]);
+// "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;
 };
@@ -29,8 +46,8 @@ export function art12Check(record, options) {
     const models = [];
     const providers = [];
     const sources = [];
-    const deciders = [];
-    let decisions = 0;
+    // 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")
@@ -45,9 +62,11 @@ export function art12Check(record, options) {
         else if (e.kind === "control" && typeof m.action === "string") {
             count(controls, m.action);
             if (m.action === "approval" && typeof m.by === "string") {
-                decisions++;
-                deciders.push(m.by);
+                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++;
@@ -70,7 +89,9 @@ export function art12Check(record, options) {
     }
     const open = events.find((e) => e.kind === "session.open");
     const close = events.find((e) => e.kind === "session.close");
-    const people = sorted(deciders.filter((d) => !NOT_PEOPLE.has(d)));
+    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 = [
         {
@@ -139,9 +160,15 @@ export function art12Check(record, options) {
             article: "12(3)(d), 14(5)",
             requirement: "The natural persons who verified the results; for Art. 14(5), at least two, separately.",
             applies: annex,
-            // ponytail: decisions name a role (admin, tenant), not a person; false until SSO subjects are recorded
-            ok: decisions === 0 ? null : false,
-            evidence: { decisions, deciders: people, persons_identified: false },
+            // 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",

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