@zanii/blackbox 0.2.0 → 0.4.0

package/dist/archive/parquet.js

@@ -0,0 +1,185 @@
+// A session archive as one Parquet file (spec/archive.md §7, L7): the events of the archived sessions
+// as typed columns, for the analytics tools that read Parquet. A minimal writer: one row group, one
+// uncompressed PLAIN page per column, REQUIRED columns, written with Thrift's compact protocol; no
+// dependency. Deterministic, so both SDKs write the same bytes (spec/vectors/parquet.json). The
+// JSONL files stay the record; this is a copy for reading at scale. Mirrors parquet.py.
+import { canonical } from "../reconcile/shared.js";
+const MAGIC = new TextEncoder().encode("PAR1");
+const CREATED_BY = "zanii-blackbox parquet v1";
+// Parquet's enums (parquet.thrift)
+const BYTE_ARRAY = 6;
+const INT64 = 2;
+const REQUIRED = 0;
+const UTF8 = 0;
+const PLAIN = 0;
+const RLE = 3;
+const UNCOMPRESSED = 0;
+const DATA_PAGE = 0;
+// Thrift compact types
+const I32 = 5;
+const I64 = 6;
+const BINARY = 8;
+const LIST = 9;
+const STRUCT = 12;
+const COLUMNS = [
+    ["session_id", BYTE_ARRAY],
+    ["seq", INT64],
+    ["ts", BYTE_ARRAY],
+    ["kind", BYTE_ARRAY],
+    ["body_hash", BYTE_ARRAY],
+    ["meta", BYTE_ARRAY],
+];
+const enc = new TextEncoder();
+const varint = (n) => {
+    const out = [];
+    let v = n;
+    for (;;) {
+        const b = Number(v & 0x7fn);
+        v >>= 7n;
+        if (v)
+            out.push(b | 0x80);
+        else {
+            out.push(b);
+            return out;
+        }
+    }
+};
+const zigzag = (n) => {
+    const v = BigInt(n);
+    return BigInt.asUintN(64, (v << 1n) ^ (v >> 63n));
+};
+const concat = (parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+};
+/** Thrift compact protocol: a struct's fields, in increasing id order. */
+class Struct {
+    parts = [];
+    last = 0;
+    head(fid, type) {
+        const delta = fid - this.last;
+        if (delta > 0 && delta <= 15)
+            this.parts.push([(delta << 4) | type]);
+        else
+            this.parts.push([type], varint(zigzag(fid)));
+        this.last = fid;
+    }
+    i32(fid, v) {
+        this.head(fid, I32);
+        this.parts.push(varint(zigzag(v)));
+        return this;
+    }
+    i64(fid, v) {
+        this.head(fid, I64);
+        this.parts.push(varint(zigzag(v)));
+        return this;
+    }
+    string(fid, v) {
+        const b = enc.encode(v);
+        this.head(fid, BINARY);
+        this.parts.push(varint(BigInt(b.length)), b);
+        return this;
+    }
+    struct(fid, v) {
+        this.head(fid, STRUCT);
+        this.parts.push(v.done());
+        return this;
+    }
+    list(fid, type, items) {
+        this.head(fid, LIST);
+        const n = items.length;
+        this.parts.push(n < 15 ? [(n << 4) | type] : [0xf0 | type, ...varint(BigInt(n))]);
+        this.parts.push(...items);
+        return this;
+    }
+    done() {
+        return concat([...this.parts, [0]]);
+    }
+}
+const i32Item = (v) => new Uint8Array(varint(zigzag(v)));
+const strItem = (v) => {
+    const b = enc.encode(v);
+    return concat([varint(BigInt(b.length)), b]);
+};
+const u32 = (n) => {
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, true);
+    return b;
+};
+function plain(kind, values) {
+    if (kind === INT64) {
+        const b = new Uint8Array(values.length * 8);
+        const view = new DataView(b.buffer);
+        values.forEach((v, i) => {
+            view.setBigInt64(i * 8, BigInt(Number(v)), true);
+        });
+        return b;
+    }
+    return concat(values.flatMap((v) => {
+        const s = enc.encode(String(v));
+        return [u32(s.length), s];
+    }));
+}
+/** The archived events (session lines, in archive order) as one Parquet file. */
+export function archiveParquet(lines) {
+    const rows = lines.map((l) => JSON.parse(l));
+    const values = {
+        session_id: rows.map((r) => r.session_id ?? ""),
+        seq: rows.map((r) => r.seq ?? 0),
+        ts: rows.map((r) => r.ts ?? ""),
+        kind: rows.map((r) => r.kind ?? ""),
+        body_hash: rows.map((r) => r.body_hash ?? ""),
+        meta: rows.map((r) => canonical(r.meta ?? {})),
+    };
+    const parts = [MAGIC];
+    let offset = MAGIC.length;
+    const chunks = [];
+    let total = 0;
+    for (const [name, kind] of COLUMNS) {
+        const data = plain(kind, values[name]);
+        const page = new Struct().i32(1, rows.length).i32(2, PLAIN).i32(3, RLE).i32(4, RLE);
+        const header = new Struct()
+            .i32(1, DATA_PAGE)
+            .i32(2, data.length)
+            .i32(3, data.length)
+            .struct(5, page)
+            .done();
+        const at = offset;
+        parts.push(header, data);
+        const size = header.length + data.length;
+        offset += size;
+        total += size;
+        const meta = new Struct()
+            .i32(1, kind)
+            .list(2, I32, [i32Item(PLAIN), i32Item(RLE)])
+            .list(3, BINARY, [strItem(name)])
+            .i32(4, UNCOMPRESSED)
+            .i64(5, rows.length)
+            .i64(6, size)
+            .i64(7, size)
+            .i64(9, at);
+        chunks.push(new Struct().i64(2, at).struct(3, meta).done());
+    }
+    const schema = [new Struct().string(4, "schema").i32(5, COLUMNS.length).done()];
+    for (const [name, kind] of COLUMNS) {
+        const el = new Struct().i32(1, kind).i32(3, REQUIRED).string(4, name);
+        if (kind === BYTE_ARRAY)
+            el.i32(6, UTF8);
+        schema.push(el.done());
+    }
+    const group = new Struct().list(1, STRUCT, chunks).i64(2, total).i64(3, rows.length).done();
+    const footer = new Struct()
+        .i32(1, 1)
+        .list(2, STRUCT, schema)
+        .i64(3, rows.length)
+        .list(4, STRUCT, [group])
+        .string(6, CREATED_BY)
+        .done();
+    parts.push(footer, u32(footer.length), MAGIC);
+    return concat(parts);
+}

package/dist/badge/index.d.ts

@@ -0,0 +1,16 @@
+/** Zanii's flat badge as an SVG string; every value is escaped. */
+export declare function badgeSvg(o: {
+    message: string;
+    label?: string;
+    color?: string;
+}): string;
+export declare const RECORD_STATES: readonly ["anchored", "verified", "recording", "broken"];
+export type RecordState = (typeof RECORD_STATES)[number];
+/** A session's record as a badge: anchored or verified (green), recording (blue), broken (red). */
+export declare function recordBadge(state: RecordState): string;
+/** The state from what GET /v1/sessions/:id says: the chain, whether it's closed, the anchors. */
+export declare function recordState(o: {
+    ok: boolean;
+    closed: boolean;
+    anchorStatus: string;
+}): RecordState;

package/dist/badge/index.js

@@ -0,0 +1,48 @@
+// Record badges (spec/anchoring.md §11): Zanii's zero-dependency shields-style SVG (@zanii/embed),
+// for a session's record state. Pure; mirrors sdks/python/src/zanii_blackbox/badge.py; pinned by
+// spec/vectors/badge.json.
+const COLORS = {
+    green: "#2ea44f",
+    red: "#d1242f",
+    gray: "#6a737d",
+    blue: "#0969da",
+    black: "#1f2328",
+};
+const ESCAPE = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ESCAPE[c]);
+// ~6.5px a character, so the badge fits its text without font metrics (Zanii's estimate)
+const width = (s) => Math.round([...s].length * 6.5) + 10;
+/** Zanii's flat badge as an SVG string; every value is escaped. */
+export function badgeSvg(o) {
+    const label = o.label ?? "zanii";
+    const fill = COLORS[o.color ?? "green"] ?? o.color ?? COLORS.green;
+    const lw = width(label);
+    const mw = width(o.message);
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${lw + mw}" height="20" role="img" aria-label="${esc(label)}: ${esc(o.message)}">` +
+        `<rect width="${lw}" height="20" fill="#555"/>` +
+        `<rect x="${lw}" width="${mw}" height="20" fill="${esc(String(fill))}"/>` +
+        '<g fill="#fff" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">' +
+        `<text x="${lw / 2}" y="14">${esc(label)}</text>` +
+        `<text x="${lw + mw / 2}" y="14">${esc(o.message)}</text>` +
+        "</g></svg>");
+}
+export const RECORD_STATES = ["anchored", "verified", "recording", "broken"];
+/** A session's record as a badge: anchored or verified (green), recording (blue), broken (red). */
+export function recordBadge(state) {
+    const color = state === "broken" ? "red" : state === "recording" ? "blue" : "green";
+    return badgeSvg({ label: "blackbox", message: state, color });
+}
+/** The state from what GET /v1/sessions/:id says: the chain, whether it's closed, the anchors. */
+export function recordState(o) {
+    if (!o.ok)
+        return "broken";
+    if (o.anchorStatus === "complete")
+        return "anchored";
+    return o.closed ? "verified" : "recording";
+}

package/dist/bom/index.d.ts

@@ -0,0 +1,14 @@
+export interface AgentIdentity {
+    id: string;
+    version?: string;
+    /** A SPIFFE ID for the workload the agent runs as. */
+    workload?: string;
+    /** The user or agent it acts for. */
+    on_behalf_of?: string;
+    /** The SHA-256 of its A2A Agent Card, `sha256:<hex>`. */
+    card_digest?: string;
+}
+/** spec/bom.md §1: an error message, or undefined for a valid `agent`. */
+export declare function checkAgent(value: unknown): string | undefined;
+/** spec/bom.md §2: a CycloneDX 1.6 JSON ML-BOM of one session's record. */
+export declare function sessionBom(lines: readonly string[]): Record<string, unknown>;

package/dist/bom/index.js

@@ -0,0 +1,152 @@
+// Agent identity and the agent's bill of materials (spec/bom.md): the `agent` a session is opened
+// with, and a CycloneDX 1.6 ML-BOM of what one session actually used (models, providers, tool
+// servers), made from its record. Deterministic: the same record gives the same bytes.
+// Mirrors sdks/python/src/zanii_blackbox/bom.py.
+import { createHash } from "node:crypto";
+import { hashLine } from "../verify/envelope.js";
+const AGENT_KEYS = new Set(["id", "version", "workload", "on_behalf_of", "card_digest"]);
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** spec/bom.md §1: an error message, or undefined for a valid `agent`. */
+export function checkAgent(value) {
+    if (!isObject(value))
+        return "agent must be an object";
+    const extra = Object.keys(value).find((k) => !AGENT_KEYS.has(k));
+    if (extra !== undefined)
+        return `agent.${extra} isn't a field`;
+    const { id, version, workload, on_behalf_of: onBehalfOf, card_digest: card } = value;
+    if (typeof id !== "string" || !/^[A-Za-z0-9._:@/-]{1,128}$/.test(id))
+        return "agent.id must be 1-128 of [A-Za-z0-9._:@/-]";
+    if (version !== undefined &&
+        (typeof version !== "string" || !/^[A-Za-z0-9._+-]{1,64}$/.test(version)))
+        return "agent.version must be 1-64 of [A-Za-z0-9._+-]";
+    if (workload !== undefined &&
+        (typeof workload !== "string" ||
+            !/^spiffe:\/\/[^\s/]+(\/\S*)?$/.test(workload) ||
+            workload.length > 2048))
+        return "agent.workload must be a SPIFFE ID (spiffe://trust-domain/path)";
+    if (onBehalfOf !== undefined &&
+        (typeof onBehalfOf !== "string" ||
+            onBehalfOf.length < 1 ||
+            onBehalfOf.length > 256 ||
+            [...onBehalfOf].some((c) => c < " " || c === "\u007f")))
+        return "agent.on_behalf_of must be 1-256 characters, no control characters";
+    if (card !== undefined && (typeof card !== "string" || !/^sha256:[0-9a-f]{64}$/.test(card)))
+        return "agent.card_digest must be sha256:<64 hex>";
+    return undefined;
+}
+const props = (pairs) => pairs
+    .filter((p) => typeof p[1] === "string" || typeof p[1] === "number")
+    .map(([name, value]) => ({ name, value: String(value) }));
+/** The principal and actor the gateway proved from a delegated token, if any. */
+function verifiedOf(agent) {
+    const v = agent.verified;
+    if (!isObject(v) || typeof v.iss !== "string" || typeof v.sub !== "string")
+        return {};
+    return { principal: `${v.iss}#${v.sub}`, ...(typeof v.act === "string" ? { actor: v.act } : {}) };
+}
+/** A UUID (version 8, RFC 9562) from the record's identity: the same record, the same serial. */
+function serialOf(sessionId, count, head) {
+    const h = createHash("sha256").update(`${sessionId}\n${count}\n${head}`).digest();
+    h[6] = (h[6] & 0x0f) | 0x80;
+    h[8] = (h[8] & 0x3f) | 0x80;
+    const x = h.subarray(0, 16).toString("hex");
+    return `urn:uuid:${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20)}`;
+}
+/** spec/bom.md §2: a CycloneDX 1.6 JSON ML-BOM of one session's record. */
+export function sessionBom(lines) {
+    const events = lines.map((l) => JSON.parse(l));
+    const first = events[0];
+    const last = lines.at(-1);
+    if (!first || last === undefined)
+        throw new Error("a BOM needs a record");
+    const sid = first.session_id;
+    const open = events.find((e) => e.kind === "session.open");
+    const agent = (isObject(open?.meta.agent) ? open.meta.agent : {});
+    const label = typeof open?.meta.label === "string" ? open.meta.label : undefined;
+    const providerOf = new Map();
+    const providers = new Map();
+    const models = new Map();
+    const servers = new Map();
+    for (const e of events) {
+        const m = e.meta;
+        if (e.kind === "llm.request" && typeof m.provider === "string") {
+            providerOf.set(e.seq, m.provider);
+            providers.set(m.provider, (providers.get(m.provider) ?? 0) + 1);
+        }
+        else if (e.kind === "llm.response" && typeof m.model === "string") {
+            const provider = providerOf.get(m.request_seq) ?? "unknown";
+            const key = `${provider}/${m.model}`;
+            const had = models.get(key) ?? { provider, model: m.model, calls: 0 };
+            had.calls++;
+            models.set(key, had);
+        }
+        else if (e.kind === "tool.call" && typeof m.server === "string") {
+            const tools = servers.get(m.server) ?? new Set();
+            if (typeof m.tool === "string")
+                tools.add(m.tool);
+            servers.set(m.server, tools);
+        }
+    }
+    const byKey = (m) => [...m.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const components = byKey(models).map(([key, v]) => ({
+        type: "machine-learning-model",
+        "bom-ref": `model:${key}`,
+        name: v.model,
+        publisher: v.provider,
+        properties: props([["zanii:calls", v.calls]]),
+    }));
+    const services = [
+        ...byKey(providers).map(([id, calls]) => ({
+            "bom-ref": `provider:${id}`,
+            name: id,
+            group: "llm-provider",
+            properties: props([["zanii:calls", calls]]),
+        })),
+        ...byKey(servers).map(([id, tools]) => ({
+            "bom-ref": `tools:${id}`,
+            name: id,
+            group: "tool-server",
+            properties: [...tools].sort().map((t) => ({ name: "zanii:tool", value: t })),
+        })),
+    ];
+    const refs = [...components.map((c) => c["bom-ref"]), ...services.map((s) => s["bom-ref"])];
+    return {
+        bomFormat: "CycloneDX",
+        specVersion: "1.6",
+        serialNumber: serialOf(sid, lines.length, hashLine(last)),
+        version: 1,
+        metadata: {
+            timestamp: events.at(-1).ts,
+            tools: { components: [{ type: "application", name: "zanii-blackbox" }] },
+            component: {
+                type: "application",
+                "bom-ref": "agent",
+                name: agent.id ?? label ?? sid,
+                ...(agent.version ? { version: agent.version } : {}),
+                properties: props([
+                    ["zanii:session_id", sid],
+                    ["zanii:workload", agent.workload],
+                    // spec/bom.md §1.2: set by the gateway from a JWT-SVID it checked
+                    ["zanii:workload_verified", workloadProof(agent)],
+                    ["zanii:on_behalf_of", agent.on_behalf_of],
+                    ["zanii:card_digest", agent.card_digest],
+                    // spec/bom.md §1.1: set by the gateway from a delegated token, never by the opener
+                    ["zanii:verified_principal", verifiedOf(agent).principal],
+                    ["zanii:verified_actor", verifiedOf(agent).actor],
+                    ["zanii:record_head", hashLine(last)],
+                ]),
+            },
+        },
+        components,
+        services,
+        dependencies: [{ ref: "agent", dependsOn: refs }],
+    };
+}
+/** spec/bom.md §1.2: `jwt-svid:<trust domain>` when the gateway checked the workload's SVID. */
+function workloadProof(agent) {
+    const v = agent
+        .workload_verified;
+    return typeof v?.method === "string" && typeof v.trust_domain === "string"
+        ? `${v.method}:${v.trust_domain}`
+        : undefined;
+}

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.d.ts

@@ -0,0 +1,35 @@
+type Evidence = Record<string, number | string | boolean | null | string[] | Record<string, number>>;
+export interface Art12Check {
+    id: string;
+    article: string;
+    requirement: string;
+    /** False: the paragraph covers only Annex III point 1(a) systems (remote biometric identification). */
+    applies: boolean;
+    /** True or false where the record can show it; null where a person must judge the evidence. */
+    ok: boolean | null;
+    evidence: Evidence;
+}
+export interface Art12Report {
+    session_id: string;
+    regulation: "Regulation (EU) 2024/1689";
+    annex_iii_1a: boolean;
+    /** Every applicable check that can pass, passes. */
+    ok: boolean;
+    checks: Art12Check[];
+    notes: string;
+}
+/** Art. 19(1) and 26(6): "at least six months". Counted as 183 days, the longest six months. */
+export declare const ART12_MIN_RETENTION_DAYS = 183;
+/**
+ * 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 declare function art12Check(record: {
+    lines: readonly string[];
+    verified: boolean;
+}, options: {
+    retentionDays: number | null;
+    annexIII1a?: boolean;
+}): Art12Report;
+export {};