@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/occurrence/index.d.ts

@@ -0,0 +1,108 @@
+import type { LoadedPrices } from "../cost/index.ts";
+import { type Summary } from "../fleet/index.ts";
+import type { Bodies } from "../reconcile/record.ts";
+export interface OccurrenceFramework {
+    title: string;
+    authority: string;
+    deadlines: string[];
+    sections: Array<{
+        id: string;
+        title: string;
+        fill: "record" | "findings" | "redactions" | "operator";
+    }>;
+    /** spec/packs.md §1: the Arabic title, authority, deadlines and section titles (by id). */
+    ar?: {
+        title: string;
+        authority: string;
+        deadlines: string[];
+        sections: Record<string, string>;
+    };
+}
+export interface OccurrenceFacts {
+    summary: Summary;
+    findings: Array<{
+        seq: number;
+        ts: string;
+        code: string;
+        fault: string | null;
+        severity: string;
+    }>;
+    redactions: Record<string, number>;
+    verified: boolean;
+    generated_at: string;
+}
+/** The facts a report is filled from (the servers pass `verified` from their own verification). */
+export declare function occurrenceFacts(lines: readonly string[], bodies: Bodies, prices: LoadedPrices, verified: boolean, generatedAt: string): OccurrenceFacts;
+/** A report in English, or in Arabic (`lang` "ar") from the framework's `ar`; throws when it has none. */
+export declare function occurrenceReport(id: string, framework: OccurrenceFramework, facts: OccurrenceFacts, lang?: "en" | "ar"): {
+    v: 1;
+    framework: string;
+    lang: "ar";
+    title: string;
+    authority: string;
+    deadlines: string[];
+    session_id: string;
+    verified: boolean;
+    generated_at: string;
+    sections: {
+        id: string;
+        title: string;
+        fill: "findings" | "operator" | "record" | "redactions";
+        text: string;
+    }[];
+} | {
+    lang?: never;
+    v: 1;
+    framework: string;
+    title: string;
+    authority: string;
+    deadlines: string[];
+    session_id: string;
+    verified: boolean;
+    generated_at: string;
+    sections: {
+        id: string;
+        title: string;
+        fill: "findings" | "operator" | "record" | "redactions";
+        text: string;
+    }[];
+};
+export type OccurrenceReport = ReturnType<typeof occurrenceReport>;
+export declare function renderOccurrence(r: OccurrenceReport, notes: string): string;
+/** spec/occurrence.md "Filing": what a person needs to file the report in an authority's portal. */
+export declare function filingPack(r: OccurrenceReport, notes: string, pack: {
+    id: string;
+    status: string;
+}, evidence: {
+    events: number;
+    head: string | null;
+    anchored_events: number;
+}): {
+    v: 1;
+    framework: string;
+    pack: {
+        id: string;
+        status: string;
+    };
+    title: string;
+    authority: string;
+    deadlines: string[];
+    session_id: string;
+    verified: boolean;
+    generated_at: string;
+    fields: {
+        id: string;
+        title: string;
+        text: string;
+        complete: boolean;
+    }[];
+    to_complete: string[];
+    evidence: {
+        events: number;
+        head: string | null;
+        anchored_events: number;
+        bundle: string;
+        verify: string;
+    };
+    markdown: string;
+};

package/dist/occurrence/index.js

@@ -0,0 +1,168 @@
+// Regulator occurrence reports (spec/occurrence.md). Mirrors sdks/python/src/zanii_blackbox/occurrence.py.
+import { sessionSummary } from "../fleet/index.js";
+/** The facts a report is filled from (the servers pass `verified` from their own verification). */
+export function occurrenceFacts(lines, bodies, prices, verified, generatedAt) {
+    const findings = [];
+    const redactions = {};
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind === "finding")
+            findings.push({
+                seq: e.seq,
+                ts: e.ts,
+                code: String(e.meta.code),
+                fault: typeof e.meta.fault === "string" ? e.meta.fault : null,
+                severity: String(e.meta.severity),
+            });
+        const r = e.meta.redacted;
+        if (typeof r === "object" && r !== null)
+            for (const [k, v] of Object.entries(r))
+                if (typeof v === "number")
+                    redactions[k] = (redactions[k] ?? 0) + v;
+    }
+    return {
+        summary: sessionSummary(lines, bodies, prices),
+        findings,
+        redactions: Object.fromEntries(Object.keys(redactions)
+            .sort()
+            .map((k) => [k, redactions[k]])),
+        verified,
+        generated_at: generatedAt,
+    };
+}
+function textOf(id, fill, f) {
+    const s = f.summary;
+    if (fill === "operator")
+        return "[To be completed by the operator]";
+    if (fill === "redactions") {
+        const kinds = Object.entries(f.redactions);
+        return kinds.length
+            ? `Redacted before storage: ${kinds.map(([k, v]) => `${k} × ${v}`).join(", ")}.`
+            : "No personal data patterns were redacted from this record.";
+    }
+    if (fill === "findings") {
+        const bad = f.findings.filter((x) => x.severity === "warning" || x.severity === "caution");
+        return bad.length
+            ? bad.map((x) => `- ${x.ts} · ${x.fault ?? "—"} · ${x.severity} · ${x.code}`).join("\n")
+            : "No warning or caution findings in the record.";
+    }
+    if (id === "timeline")
+        return `From ${s.started_at} to ${s.last_event_at} (the gateway's clock).`;
+    const status = s.blocked_by ? `blocked by ${s.blocked_by}` : s.closed ? "closed" : "open";
+    return `Agent session ${s.label ?? s.session_id} (${s.session_id}): ${s.model_calls} model calls, ${s.tool_calls} tool calls, outcome ${s.outcome ?? "none"}, status ${status}.`;
+}
+// spec/occurrence.md "Arabic": the same facts in Arabic words; ids, times and codes stay as they are.
+function textOfAr(id, fill, f) {
+    const s = f.summary;
+    if (fill === "operator")
+        return "[يستكمله المشغّل]";
+    if (fill === "redactions") {
+        const kinds = Object.entries(f.redactions);
+        return kinds.length
+            ? `حُجب قبل التخزين: ${kinds.map(([k, v]) => `${k} × ${v}`).join("، ")}.`
+            : "لم يُحجب أي نمط من أنماط البيانات الشخصية في هذا السجل.";
+    }
+    if (fill === "findings") {
+        const bad = f.findings.filter((x) => x.severity === "warning" || x.severity === "caution");
+        return bad.length
+            ? bad.map((x) => `- ${x.ts} · ${x.fault ?? "—"} · ${x.severity} · ${x.code}`).join("\n")
+            : "لا توجد في السجل نتائج بمستوى تحذير أو تنبيه.";
+    }
+    if (id === "timeline")
+        return `من ${s.started_at} إلى ${s.last_event_at} (بحسب ساعة البوابة).`;
+    const status = s.blocked_by ? `محظورة بواسطة ${s.blocked_by}` : s.closed ? "مغلقة" : "مفتوحة";
+    return `جلسة الوكيل ${s.label ?? s.session_id} (${s.session_id}): ${s.model_calls} من استدعاءات النموذج، ${s.tool_calls} من استدعاءات الأدوات، النتيجة ${s.outcome ?? "لا شيء"}، الحالة ${status}.`;
+}
+/** A report in English, or in Arabic (`lang` "ar") from the framework's `ar`; throws when it has none. */
+export function occurrenceReport(id, framework, facts, lang = "en") {
+    if (lang === "ar") {
+        const ar = framework.ar;
+        if (!ar)
+            throw new Error(`framework ${id} has no Arabic`);
+        return {
+            v: 1,
+            framework: id,
+            lang: "ar",
+            title: ar.title,
+            authority: ar.authority,
+            deadlines: [...ar.deadlines],
+            session_id: facts.summary.session_id,
+            verified: facts.verified,
+            generated_at: facts.generated_at,
+            sections: framework.sections.map((x) => ({
+                id: x.id,
+                title: ar.sections[x.id],
+                fill: x.fill,
+                text: textOfAr(x.id, x.fill, facts),
+            })),
+        };
+    }
+    return {
+        v: 1,
+        framework: id,
+        title: framework.title,
+        authority: framework.authority,
+        deadlines: [...framework.deadlines],
+        session_id: facts.summary.session_id,
+        verified: facts.verified,
+        generated_at: facts.generated_at,
+        sections: framework.sections.map((x) => ({
+            id: x.id,
+            title: x.title,
+            fill: x.fill,
+            text: textOf(x.id, x.fill, facts),
+        })),
+    };
+}
+const LABELS = {
+    en: ["Session", "Record verifies", "yes", "NO", "Report to", "Generated", "Deadlines"],
+    ar: ["الجلسة", "السجل موثّق", "نعم", "لا", "جهة الإبلاغ", "تاريخ الإنشاء", "المواعيد النهائية"],
+};
+export function renderOccurrence(r, notes) {
+    const [session, verifies, yes, no, reportTo, generated, deadlines] = LABELS["lang" in r ? "ar" : "en"];
+    const out = [
+        `# ${r.title}`,
+        "",
+        "| | |",
+        "|---|---|",
+        `| ${session} | \`${r.session_id}\` |`,
+        `| ${verifies} | ${r.verified ? yes : no} |`,
+        `| ${reportTo} | ${r.authority} |`,
+        `| ${generated} | ${r.generated_at} |`,
+        "",
+        `**${deadlines}**`,
+        "",
+        ...r.deadlines.map((d) => `- ${d}`),
+        ...r.sections.flatMap((x) => ["", `## ${x.title}`, "", x.text]),
+        "",
+        `*${notes}*`,
+    ];
+    return `${out.join("\n")}\n`;
+}
+/** spec/occurrence.md "Filing": what a person needs to file the report in an authority's portal. */
+export function filingPack(r, notes, pack, evidence) {
+    return {
+        v: 1,
+        framework: r.framework,
+        pack,
+        title: r.title,
+        authority: r.authority,
+        deadlines: r.deadlines,
+        session_id: r.session_id,
+        verified: r.verified,
+        generated_at: r.generated_at,
+        fields: r.sections.map((s) => ({
+            id: s.id,
+            title: s.title,
+            text: s.text,
+            complete: s.fill !== "operator",
+        })),
+        to_complete: r.sections.filter((s) => s.fill === "operator").map((s) => s.id),
+        evidence: {
+            ...evidence,
+            bundle: `/v1/sessions/${r.session_id}/bundle`,
+            verify: "blackbox verify <bundle.json> --proofs",
+        },
+        markdown: renderOccurrence(r, notes),
+    };
+}

package/dist/ocsf/index.d.ts

@@ -0,0 +1,22 @@
+import type { Json } from "../verify/index.ts";
+export type OcsfVersion = "1.8" | "1.3" | "1.1";
+export type OcsfEvent = {
+    [key: string]: Json;
+};
+/** The session's events as OCSF, oldest first. Agent-asserted SDK events aren't exported: a SIEM
+ * gets what the gateway saw. */
+export declare function toOcsf(lines: readonly string[], options?: {
+    version?: OcsfVersion;
+    productVersion?: string;
+}): OcsfEvent[];
+/** One line per event, for people and grep: `<ISO time> <class>/<activity> <severity> <message>`. */
+export declare function ocsfLine(ev: OcsfEvent): string;
+/** Idea I4: reads an OCSF JSONL log (OpenShell's sandbox audit log, for one) into the session as
+ * `ocsf` SDK events, named by class. A record's `metadata.uid` is its stable event id, so reading
+ * the same log twice records nothing twice. Lines that aren't JSON objects are skipped; returns
+ * how many were recorded. */
+export declare function ingestOcsf(session: {
+    event(type: string, name?: string, data?: Record<string, unknown>, o?: {
+        eventId?: string;
+    }): void;
+}, jsonl: string): number;

package/dist/ocsf/index.js

@@ -0,0 +1,168 @@
+// OCSF export (spec/ocsf.md, idea S1): a session's record as OCSF 1.8.0 events for a SIEM (Splunk,
+// AWS Security Lake, CrowdStrike, Elastic), with a lossy downgrade to 1.1 / 1.3 and a one-line text
+// form. Mirrors ocsf.py.
+const SEVERITY = {
+    advisory: [2, "Low"],
+    caution: [3, "Medium"],
+    warning: [4, "High"],
+};
+function base(e, cls, activity, message, productVersion) {
+    const [classUid, className, categoryUid, categoryName] = cls;
+    return {
+        class_uid: classUid,
+        class_name: className,
+        category_uid: categoryUid,
+        category_name: categoryName,
+        activity_id: activity[0],
+        activity_name: activity[1],
+        type_uid: classUid * 100 + activity[0],
+        severity_id: 1,
+        severity: "Informational",
+        status_id: 1,
+        status: "Success",
+        time: Date.parse(e.ts),
+        message,
+        metadata: {
+            version: "1.8.0",
+            uid: `${e.session_id}:${e.seq}`,
+            correlation_uid: e.session_id,
+            log_name: "zanii-blackbox",
+            product: { name: "Zanii Blackbox", vendor_name: "Zanii", version: productVersion },
+        },
+        unmapped: { seq: e.seq, kind: e.kind },
+    };
+}
+const HTTP = [4002, "HTTP Activity", 4, "Network Activity"];
+const API = [6003, "API Activity", 6, "Application Activity"];
+const LIFECYCLE = [
+    6002,
+    "Application Lifecycle",
+    6,
+    "Application Activity",
+];
+const FINDING = [2004, "Detection Finding", 2, "Findings"];
+/** The session's events as OCSF, oldest first. Agent-asserted SDK events aren't exported: a SIEM
+ * gets what the gateway saw. */
+export function toOcsf(lines, options = {}) {
+    const pv = options.productVersion ?? "unknown";
+    const requests = new Map();
+    const out = [];
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        const m = e.meta;
+        if (e.kind === "llm.request") {
+            requests.set(e.seq, {
+                ...(typeof m.provider === "string" ? { provider: m.provider } : {}),
+                ...(typeof m.method === "string" ? { method: m.method } : {}),
+                ...(typeof m.path === "string" ? { path: m.path } : {}),
+            });
+        }
+        else if (e.kind === "llm.response") {
+            const r = typeof m.request_seq === "number" ? requests.get(m.request_seq) : undefined;
+            const status = typeof m.status === "number" ? m.status : 0;
+            const model = typeof m.model === "string" ? m.model : "unknown";
+            const provider = r?.provider ?? "unknown";
+            const ev = base(e, HTTP, [6, "Post"], `${r?.method ?? "POST"} ${provider} ${model} → ${status}`, pv);
+            ev.http_request = { http_method: r?.method ?? "POST", url: { path: r?.path ?? "" } };
+            ev.http_response = { code: status };
+            ev.ai_model = { name: model, ai_provider: provider };
+            ev.metadata.profiles = ["ai_operation"];
+            if (status >= 400)
+                Object.assign(ev, { status_id: 2, status: "Failure" });
+            out.push(ev);
+        }
+        else if (e.kind === "tool.call" && m.method === "tools/call") {
+            const p = m.policy;
+            const tool = `${String(m.server ?? "?")}.${String(m.tool ?? "?")}`;
+            const denied = p?.action === "deny";
+            const ev = base(e, API, [99, "Other"], denied ? `tools/call ${tool} denied by ${String(p?.rule)}` : `tools/call ${tool}`, pv);
+            ev.api = { operation: "tools/call", service: { name: String(m.server ?? "") } };
+            Object.assign(ev, denied
+                ? {
+                    action_id: 2,
+                    action: "Denied",
+                    disposition_id: 2,
+                    disposition: "Blocked",
+                    status_id: 2,
+                    status: "Failure",
+                    firewall_rule: { name: String(p?.rule), type: "blackbox-policy" },
+                }
+                : { action_id: 1, action: "Allowed", disposition_id: 1, disposition: "Allowed" });
+            out.push(ev);
+        }
+        else if (e.kind === "finding") {
+            const [sid, sev] = SEVERITY[String(m.severity)] ?? [5, "Critical"];
+            const ev = base(e, FINDING, [1, "Create"], String(m.detail ?? m.code), pv);
+            Object.assign(ev, { severity_id: sid, severity: sev });
+            ev.finding_info = {
+                uid: `${e.session_id}:${e.seq}`,
+                title: String(m.code),
+                types: [String(m.code)],
+            };
+            ev.metadata.event_code = String(m.fault ?? m.code);
+            out.push(ev);
+        }
+        else if (e.kind === "session.open" || e.kind === "session.close") {
+            const open = e.kind === "session.open";
+            const ev = base(e, LIFECYCLE, open ? [3, "Start"] : [4, "Stop"], open ? "session opened" : "session closed", pv);
+            ev.app = { name: "Zanii Blackbox session", uid: e.session_id };
+            out.push(ev);
+        }
+        else if (e.kind === "control" && typeof m.action === "string") {
+            const ev = base(e, API, [99, "Other"], `control ${m.action}`, pv);
+            ev.api = { operation: `control.${m.action}`, service: { name: "blackbox" } };
+            out.push(ev);
+        }
+    }
+    return options.version && options.version !== "1.8"
+        ? out.map((ev) => downgrade(ev, options.version))
+        : out;
+}
+/** Idea S1: for a SIEM on an older OCSF: drops what came later (`ai_model`), the `ai_operation`
+ * profile, and says so in `unmapped.downgraded_from`. */
+function downgrade(ev, version) {
+    const { ai_model: _, ...rest } = ev;
+    const metadata = {
+        ...rest.metadata,
+        version: `${version}.0`,
+    };
+    const profiles = metadata.profiles?.filter((p) => p !== "ai_operation");
+    if (profiles?.length)
+        metadata.profiles = profiles;
+    else
+        delete metadata.profiles;
+    return {
+        ...rest,
+        metadata,
+        unmapped: { ...rest.unmapped, downgraded_from: "1.8.0" },
+    };
+}
+/** One line per event, for people and grep: `<ISO time> <class>/<activity> <severity> <message>`. */
+export function ocsfLine(ev) {
+    return `${new Date(ev.time).toISOString()} ${ev.class_name}/${ev.activity_name} ${ev.severity} ${ev.message}`;
+}
+/** Idea I4: reads an OCSF JSONL log (OpenShell's sandbox audit log, for one) into the session as
+ * `ocsf` SDK events, named by class. A record's `metadata.uid` is its stable event id, so reading
+ * the same log twice records nothing twice. Lines that aren't JSON objects are skipped; returns
+ * how many were recorded. */
+export function ingestOcsf(session, jsonl) {
+    let n = 0;
+    for (const line of jsonl.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof ev !== "object" || ev === null || Array.isArray(ev))
+            continue;
+        const e = ev;
+        const uid = e.metadata?.uid;
+        session.event("ocsf", typeof e.class_name === "string" ? e.class_name.slice(0, 256) : undefined, e, typeof uid === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(uid) ? { eventId: uid } : {});
+        n++;
+    }
+    return n;
+}

package/dist/otlp/index.d.ts

@@ -0,0 +1,24 @@
+type Value = {
+    stringValue: string;
+} | {
+    intValue: string;
+};
+type Attr = {
+    key: string;
+    value: Value;
+};
+export declare function toOtlp(lines: readonly string[]): {
+    resourceSpans: {
+        resource: {
+            attributes: Attr[];
+        };
+        scopeSpans: {
+            scope: {
+                name: string;
+                version: string;
+            };
+            spans: object[];
+        }[];
+    }[];
+};
+export {};

package/dist/otlp/index.js

@@ -0,0 +1,143 @@
+// A session as OpenTelemetry traces (spec/otlp.md): OTLP/JSON with the GenAI semantic conventions.
+// Deterministic (ids derived from the session), so both SDKs produce the same bytes. Mirrors otlp.py.
+import { createHash } from "node:crypto";
+import { tokensOf } from "../cost/index.js";
+const hex = (s, n) => createHash("sha256").update(s).digest("hex").slice(0, n);
+const nanos = (ts) => `${Date.parse(ts)}000000`;
+const str = (key, v) => typeof v === "string" ? [{ key, value: { stringValue: v } }] : [];
+const int = (key, v) => typeof v === "number" && Number.isSafeInteger(v) ? [{ key, value: { intValue: String(v) } }] : [];
+export function toOtlp(lines) {
+    const events = lines.map((l) => JSON.parse(l));
+    const first = events[0];
+    if (!first)
+        return { resourceSpans: [] };
+    const session = first.session_id;
+    const traceId = hex(session, 32);
+    const spanId = (seq) => hex(`${session}:${seq}`, 16);
+    const root = spanId(0);
+    const last = events[events.length - 1];
+    const spans = [];
+    // The session itself, with the findings as its events.
+    spans.push({
+        traceId,
+        spanId: root,
+        name: "session",
+        kind: 1,
+        startTimeUnixNano: nanos(first.ts),
+        endTimeUnixNano: nanos(last.ts),
+        attributes: [
+            ...str("blackbox.session_id", session),
+            ...str("blackbox.mode", first.meta.mode),
+            ...str("blackbox.label", first.meta.label),
+            ...str("blackbox.tenant", first.meta.tenant),
+            ...int("blackbox.events", events.length),
+        ],
+        events: events
+            .filter((e) => e.kind === "finding")
+            .map((e) => ({
+            timeUnixNano: nanos(e.ts),
+            name: String(e.meta.code),
+            attributes: [
+                ...str("blackbox.severity", e.meta.severity),
+                ...str("blackbox.fault", e.meta.fault),
+                ...int("blackbox.seq", e.seq),
+            ],
+        })),
+    });
+    // Each model call: the request, closed by its response (request_seq) or its abnormal end.
+    const ends = new Map();
+    for (const e of events)
+        if ((e.kind === "llm.response" || e.kind === "llm.incomplete") &&
+            typeof e.meta.request_seq === "number")
+            ends.set(e.meta.request_seq, e);
+    for (const e of events.filter((x) => x.kind === "llm.request")) {
+        const end = ends.get(e.seq);
+        const usage = end?.meta.usage && typeof end.meta.usage === "object"
+            ? tokensOf(end.meta.usage)
+            : null;
+        const status = end?.meta.status;
+        const failed = !end || end.kind === "llm.incomplete" || (typeof status === "number" && status >= 400);
+        const model = typeof end?.meta.model === "string" ? end.meta.model : undefined;
+        spans.push({
+            traceId,
+            spanId: spanId(e.seq),
+            parentSpanId: root,
+            name: model ? `chat ${model}` : "chat",
+            kind: 3,
+            startTimeUnixNano: nanos(e.ts),
+            endTimeUnixNano: nanos((end ?? e).ts),
+            attributes: [
+                ...str("gen_ai.system", e.meta.provider),
+                ...str("gen_ai.response.model", model),
+                ...str("gen_ai.response.id", end?.meta.message_id ?? end?.meta.response_id),
+                ...(usage
+                    ? [
+                        ...int("gen_ai.usage.input_tokens", usage.input + usage.cache_read + usage.cache_write),
+                        ...int("gen_ai.usage.output_tokens", usage.output),
+                    ]
+                    : []),
+                ...int("http.response.status_code", status),
+                ...int("blackbox.seq", e.seq),
+            ],
+            ...(failed
+                ? {
+                    status: {
+                        code: 2,
+                        message: end?.kind === "llm.incomplete"
+                            ? String(end.meta.reason ?? "incomplete")
+                            : `status ${status ?? "none"}`,
+                    },
+                }
+                : {}),
+        });
+    }
+    // Each MCP tool call, closed by its result (call_seq).
+    const results = new Map();
+    for (const e of events)
+        if (e.kind === "tool.result" && typeof e.meta.call_seq === "number")
+            results.set(e.meta.call_seq, e);
+    for (const e of events.filter((x) => x.kind === "tool.call")) {
+        const end = results.get(e.seq);
+        const failed = end?.meta.is_error === true ||
+            end?.meta.rpc_error !== undefined ||
+            e.meta.policy !== undefined;
+        spans.push({
+            traceId,
+            spanId: spanId(e.seq),
+            parentSpanId: root,
+            name: typeof e.meta.tool === "string"
+                ? `execute_tool ${e.meta.tool}`
+                : `mcp ${String(e.meta.method ?? "call")}`,
+            kind: 3,
+            startTimeUnixNano: nanos(e.ts),
+            endTimeUnixNano: nanos((end ?? e).ts),
+            attributes: [
+                ...str("gen_ai.tool.name", e.meta.tool),
+                ...str("mcp.server", e.meta.server),
+                ...str("mcp.method", e.meta.method),
+                ...int("blackbox.seq", e.seq),
+            ],
+            ...(failed
+                ? {
+                    status: {
+                        code: 2,
+                        message: e.meta.policy !== undefined ? "denied by policy" : "tool error",
+                    },
+                }
+                : {}),
+        });
+    }
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        ...str("service.name", "zanii-blackbox"),
+                        ...str("blackbox.session_id", session),
+                    ],
+                },
+                scopeSpans: [{ scope: { name: "zanii-blackbox", version: "1" }, spans }],
+            },
+        ],
+    };
+}

package/dist/packs/index.d.ts

@@ -0,0 +1,48 @@
+import { type DataRules } from "../data/index.ts";
+type Obj = Record<string, unknown>;
+export interface PackEntry {
+    pack: string;
+    status: "draft" | "reviewed";
+    notes: string;
+    /** The Arabic disclaimer, when the pack has one. */
+    notes_ar?: string;
+    framework: Obj;
+}
+/** spec/packs.md §1: why a pack is invalid, or undefined. */
+export declare function checkPack(value: unknown): string | undefined;
+/** spec/data.md §1: why an identifier is invalid, or undefined. */
+export declare function checkIdentifier(v: unknown, at: string): string | undefined;
+/**
+ * spec/data.md §4: the data rules of packs merged in order, then the core. Pack identifiers come
+ * before the core ones; throws on an invalid pack or an identifier id in two packs.
+ */
+export declare function packData(packs: readonly unknown[]): DataRules;
+/** spec/packs.md §2: the core pack, from the built-in frameworks files. */
+export declare function corePack(compliance: {
+    notes: string;
+    frameworks: Obj;
+}, occurrence: {
+    notes: string;
+    notes_ar?: string;
+    frameworks: Obj;
+}): {
+    v: number;
+    id: string;
+    title: string;
+    status: string;
+    compliance: {
+        notes: string;
+        frameworks: Obj;
+    };
+    occurrence: {
+        notes: string;
+        notes_ar?: string;
+        frameworks: Obj;
+    };
+};
+/** spec/packs.md §2: packs merged in order; throws on an invalid pack or a repeated framework id. */
+export declare function packFrameworks(packs: readonly unknown[]): {
+    compliance: Record<string, PackEntry>;
+    occurrence: Record<string, PackEntry>;
+};
+export {};