@zanii/blackbox 0.2.0 → 0.3.0

package/dist/compliance/art12.js

@@ -0,0 +1,163 @@
+// 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;
+const NOT_PEOPLE = new Set(["timeout", "unattended", "classifier"]);
+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();
+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 = [];
+    const deciders = [];
+    let decisions = 0;
+    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") {
+                decisions++;
+                deciders.push(m.by);
+            }
+        }
+        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 people = sorted(deciders.filter((d) => !NOT_PEOPLE.has(d)));
+    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,
+            // 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 },
+        },
+        {
+            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/index.d.ts

@@ -1,13 +1,18 @@
+export { A2A_STREAMING, type AgentCardReport, a2aMethod, a2aRequestMeta, a2aResponseMeta, agentCardDigest, agentCardPayload, verifyAgentCard, } from "./a2a/index.ts";
 export { causality, memoryXray } from "./agents/index.ts";
 export { type DetectorOptions, detectors, fingerprint } from "./analysis/detectors.ts";
 export { FAULTS, type Fault, faultOf } from "./analysis/faults.ts";
 export { type AnalyzeOptions, analyze, type ClaimVerdict, type CriterionResult, checkFlightPlan, checkpointReplay, dualWitness, eventsOf, type Finding as AnalysisFinding, findingKey, type Landing, landing, OUTCOMES, type Outcome, type OutcomeRollup, rollup, type Severity, type WasteReason, type WasteReport, waste, } from "./analysis/index.ts";
+export { MITRE_ATLAS, OWASP_ASI, TAXONOMY, type Taxonomy, taxonomyOf, } from "./analysis/taxonomy.ts";
 export { type ApprovalFinding, approvalFindings } from "./approvals/index.ts";
 export { textWarnings } from "./approvals/warnings.ts";
+export { type ArchiveFile, type ArchiveManifest, type ArchiveReport, archiveDigest, archiveEntry, archiveManifest, verifyArchive, } from "./archive/index.ts";
 export { type Attestation, attest, isReadOnly, normalise, parseCommand } from "./attest/index.ts";
 export { type AuthorityFinding, authorityAt, authorityTimeline, automationSurprise, type Mode as AuthorityMode, type Span as AuthoritySpan, } from "./authority/index.ts";
 export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxInvoice, stripeSignatureOk, type TaxInvoice, type TaxInvoiceInput, taxInvoice, } from "./billing/index.ts";
+export { type AgentIdentity, checkAgent, sessionBom } from "./bom/index.ts";
 export { BlackboxApiError, type Client, type ClientOptions, client, type SessionQuery, } from "./client/index.ts";
+export { ART12_MIN_RETENTION_DAYS, type Art12Check, type Art12Report, art12Check, } from "./compliance/art12.ts";
 export { complianceFacts, complianceReport, type Facts, type Framework, type Report as ComplianceReport, renderReport, } from "./compliance/index.ts";
 export { type CallCost, type CostReport, callMicroUsd, effectivePrice, formatAed, type LoadedPrices, loadPrices, type ModelPrice, type PriceTable, priceCall, priceFor, promptTokens, requestsOf, sessionCost, type Tokens, toAedFils, tokensOf, } from "./cost/index.ts";
 export { type AuditRow, CORE_EVIDENCE, CORE_IDENTIFIERS, type Connector as AuditConnector, canaryIdentifier, checkAuditConnector, type DataFinding, type DataRules, dataClasses, dataFindings, dataFingerprint, dataMeta, dataScan, dataTopology, hasEvidence, type Identifier, type Lineage, lineage, luhn, normalizeValue, parseAuditLog, parseCsv, reconcileSystem, type SystemReport, type Topology, toolWitness, unevidenced, verifyToolWitness, witnessOf, } from "./data/index.ts";
@@ -28,7 +33,7 @@ export { toOtlp } from "./otlp/index.ts";
 export { checkIdentifier, checkPack, corePack, type PackEntry, packData, packFrameworks, } from "./packs/index.ts";
 export { type PolicyChange, type PolicyDelta, policyDelta } from "./policy/delta.ts";
 export { type Draft, type DraftGroup, policyDrafts } from "./policy/drafts.ts";
-export { audited, type CompiledPolicy, compilePolicy, type Decision, decide, loadPolicy, type Policy, policyFindings, type Rule, } from "./policy/index.ts";
+export { audited, type CompiledPolicy, compilePolicy, type Decision, decide, loadPolicy, mcpToolHints, type Policy, policyFindings, type Rule, type ToolHints, } from "./policy/index.ts";
 export { calibration, FEATURES, features, MIN_EACH, type PrecogModel, precogFindings, precogReport, predict, prefixOf, splitOf, TARGET, train, } from "./precog/index.ts";
 export { type InterventionEvidence, interventionEvidence, interventionGain, } from "./precog/intervention.ts";
 export { activities, buildNormal, type NormalModel, type NormalScore, normalScore, normalThreshold, } from "./precog/normal.ts";
@@ -39,6 +44,8 @@ export { cassette, requestKey, type Take } from "./replay/index.ts";
 export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.ts";
 export { type DrainResult, drainSpools } from "./session/drain.ts";
 export { BlackboxSession, checkEgress, type EgressCheck, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
+export { type TimestampReport, timestampRequest, verifyTimestamp, } from "./timestamp/index.ts";
+export { addCheckpointBody, type Cbor, cborDecode, cborEncode, checkpointText, consistencyProof, cosign, cosignMldsa, ed25519PublicKey, inclusionProof, keyRotationNote, leafHash, logKid, makeReceipt, merkleRoot, mldsaAvailable, mldsaPublicKey, noteVkey, parseAddCheckpoint, parseCheckpoint, parseVkey, RECEIPT_SUB, SESSION_CONTENT_TYPE, sessionStatement, signNote, signStatement, splitNote, statementEntry, subtreeMessage, transparentStatement, verifyConsistency, verifyCoseSign1, verifyCosignature, verifyInclusion, verifyKeyRotation, verifyNote, verifyReceipt, verifyTransparency, } from "./transparency/index.ts";
 export { type Compensation, checkCompensations, runUndo, type UndoFinding, type UndoStatus, type UndoStep, undoFindings, undoPlan, } from "./undo/index.ts";
 export * from "./verify/index.ts";
 export { VERSION } from "./version.ts";

package/dist/index.js

@@ -1,15 +1,20 @@
 // Public API of @zanii/blackbox. Everything customers can import is re-exported here.
 // Keep this file in step with sdks/python/src/zanii_blackbox/__init__.py (the SDKs mirror each other).
+export { A2A_STREAMING, a2aMethod, a2aRequestMeta, a2aResponseMeta, agentCardDigest, agentCardPayload, verifyAgentCard, } from "./a2a/index.js";
 export { causality, memoryXray } from "./agents/index.js";
 export { detectors, fingerprint } from "./analysis/detectors.js";
 export { FAULTS, faultOf } from "./analysis/faults.js";
 export { analyze, checkFlightPlan, checkpointReplay, dualWitness, eventsOf, findingKey, landing, OUTCOMES, rollup, waste, } from "./analysis/index.js";
+export { MITRE_ATLAS, OWASP_ASI, TAXONOMY, taxonomyOf, } from "./analysis/taxonomy.js";
 export { approvalFindings } from "./approvals/index.js";
 export { textWarnings } from "./approvals/warnings.js";
+export { archiveDigest, archiveEntry, archiveManifest, verifyArchive, } from "./archive/index.js";
 export { attest, isReadOnly, normalise, parseCommand } from "./attest/index.js";
 export { authorityAt, authorityTimeline, automationSurprise, } from "./authority/index.js";
 export { invoice, loadPlans, renderTaxInvoice, stripeSignatureOk, taxInvoice, } from "./billing/index.js";
+export { checkAgent, sessionBom } from "./bom/index.js";
 export { BlackboxApiError, client, } from "./client/index.js";
+export { ART12_MIN_RETENTION_DAYS, art12Check, } from "./compliance/art12.js";
 export { complianceFacts, complianceReport, renderReport, } from "./compliance/index.js";
 export { callMicroUsd, effectivePrice, formatAed, loadPrices, priceCall, priceFor, promptTokens, requestsOf, sessionCost, toAedFils, tokensOf, } from "./cost/index.js";
 export { CORE_EVIDENCE, CORE_IDENTIFIERS, canaryIdentifier, checkAuditConnector, dataClasses, dataFindings, dataFingerprint, dataMeta, dataScan, dataTopology, hasEvidence, lineage, luhn, normalizeValue, parseAuditLog, parseCsv, reconcileSystem, toolWitness, unevidenced, verifyToolWitness, witnessOf, } from "./data/index.js";
@@ -30,7 +35,7 @@ export { toOtlp } from "./otlp/index.js";
 export { checkIdentifier, checkPack, corePack, packData, packFrameworks, } from "./packs/index.js";
 export { policyDelta } from "./policy/delta.js";
 export { policyDrafts } from "./policy/drafts.js";
-export { audited, compilePolicy, decide, loadPolicy, policyFindings, } from "./policy/index.js";
+export { audited, compilePolicy, decide, loadPolicy, mcpToolHints, policyFindings, } from "./policy/index.js";
 export { calibration, FEATURES, features, MIN_EACH, precogFindings, precogReport, predict, prefixOf, splitOf, TARGET, train, } from "./precog/index.js";
 export { interventionEvidence, interventionGain, } from "./precog/intervention.js";
 export { activities, buildNormal, normalScore, normalThreshold, } from "./precog/normal.js";
@@ -41,6 +46,8 @@ export { cassette, requestKey } from "./replay/index.js";
 export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.js";
 export { drainSpools } from "./session/drain.js";
 export { BlackboxSession, checkEgress, session, stableEventId, } from "./session/index.js";
+export { timestampRequest, verifyTimestamp, } from "./timestamp/index.js";
+export { addCheckpointBody, cborDecode, cborEncode, checkpointText, consistencyProof, cosign, cosignMldsa, ed25519PublicKey, inclusionProof, keyRotationNote, leafHash, logKid, makeReceipt, merkleRoot, mldsaAvailable, mldsaPublicKey, noteVkey, parseAddCheckpoint, parseCheckpoint, parseVkey, RECEIPT_SUB, SESSION_CONTENT_TYPE, sessionStatement, signNote, signStatement, splitNote, statementEntry, subtreeMessage, transparentStatement, verifyConsistency, verifyCoseSign1, verifyCosignature, verifyInclusion, verifyKeyRotation, verifyNote, verifyReceipt, verifyTransparency, } from "./transparency/index.js";
 export { checkCompensations, runUndo, undoFindings, undoPlan, } from "./undo/index.js";
 export * from "./verify/index.js";
 export { VERSION } from "./version.js";

package/dist/ocsf/index.d.ts

@@ -1,5 +1,5 @@
 import type { Json } from "../verify/index.ts";
-export type OcsfVersion = "1.8" | "1.3" | "1.1";
+export type OcsfVersion = "1.9" | "1.8" | "1.3" | "1.1";
 export type OcsfEvent = {
     [key: string]: Json;
 };

package/dist/ocsf/index.js

@@ -1,6 +1,7 @@
 // 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.
+import { taxonomyOf } from "../analysis/taxonomy.js";
 const SEVERITY = {
     advisory: [2, "Low"],
     caution: [3, "Medium"],
@@ -45,11 +46,16 @@ const FINDING = [2004, "Detection Finding", 2, "Findings"];
  * gets what the gateway saw. */
 export function toOcsf(lines, options = {}) {
     const pv = options.productVersion ?? "unknown";
+    let label;
+    let session = "";
     const requests = new Map();
     const out = [];
     for (const line of lines) {
         const e = JSON.parse(line);
         const m = e.meta;
+        session = e.session_id;
+        if (e.kind === "session.open" && typeof m.label === "string")
+            label = m.label;
         if (e.kind === "llm.request") {
             requests.set(e.seq, {
                 ...(typeof m.provider === "string" ? { provider: m.provider } : {}),
@@ -114,9 +120,36 @@ export function toOcsf(lines, options = {}) {
             out.push(ev);
         }
     }
-    return options.version && options.version !== "1.8"
-        ? out.map((ev) => downgrade(ev, options.version))
-        : out;
+    const version = options.version ?? "1.9";
+    if (version === "1.9")
+        return out.map((ev) => upgrade(ev, label, session));
+    return version === "1.8" ? out : out.map((ev) => downgrade(ev, version));
+}
+/** OCSF 1.9 (spec/ocsf.md §2): the agent (`ai_agent`) on model and tool events, and each finding's
+ * MITRE ATLAS techniques (`attacks`) and OWASP ASI ids (`metadata.tags`). */
+function upgrade(ev, label, session) {
+    const metadata = {
+        ...ev.metadata,
+        version: "1.9.0",
+    };
+    const out = { ...ev, metadata };
+    const ai = ev.ai_model !== undefined ||
+        ev.api?.operation === "tools/call";
+    if (ai) {
+        out.ai_agent = { name: label ?? "agent", instance_uid: session };
+        metadata.profiles = ["ai_operation"];
+    }
+    if (ev.class_uid === 2004) {
+        const t = taxonomyOf(String(ev.finding_info.title));
+        if (t.atlas.length)
+            out.attacks = t.atlas.map((a) => ({
+                technique: { uid: a.id, name: a.name },
+                version: "ATLAS v2026.09",
+            }));
+        if (t.owasp.length)
+            metadata.tags = t.owasp.map((o) => ({ name: "owasp_asi", value: o.id }));
+    }
+    return 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`. */

package/dist/otlp/index.d.ts

@@ -7,7 +7,14 @@ type Attr = {
     key: string;
     value: Value;
 };
-export declare function toOtlp(lines: readonly string[]): {
+/**
+ * spec/otlp.md: a session as OTLP/JSON. `semconv: 2` (the default) follows the GenAI semantic
+ * conventions as of v1.42 (`gen_ai.provider.name`, `invoke_agent`, MCP `tools/call`); `semconv: 1`
+ * is the first version's output, pinned by spec/vectors/otlp.json.
+ */
+export declare function toOtlp(lines: readonly string[], options?: {
+    semconv?: 1 | 2;
+}): {
     resourceSpans: {
         resource: {
             attributes: Attr[];

package/dist/otlp/index.js

@@ -1,12 +1,21 @@
 // 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 { taxonomyOf } from "../analysis/taxonomy.js";
 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) {
+/**
+ * spec/otlp.md: a session as OTLP/JSON. `semconv: 2` (the default) follows the GenAI semantic
+ * conventions as of v1.42 (`gen_ai.provider.name`, `invoke_agent`, MCP `tools/call`); `semconv: 1`
+ * is the first version's output, pinned by spec/vectors/otlp.json.
+ */
+export function toOtlp(lines, options = {}) {
+    return options.semconv === 1 ? toOtlpV1(lines) : toOtlpV2(lines);
+}
+function toOtlpV1(lines) {
     const events = lines.map((l) => JSON.parse(l));
     const first = events[0];
     if (!first)
@@ -141,3 +150,224 @@ export function toOtlp(lines) {
         ],
     };
 }
+// ---------------------------------------------------------------- semconv 2 (GenAI v1.42)
+/** Provider kinds as `gen_ai.provider.name` well-known values; any other provider id as it is. */
+const PROVIDER_NAMES = {
+    anthropic: "anthropic",
+    openai: "openai",
+    "azure-openai": "azure.ai.openai",
+    gemini: "gcp.gemini",
+    vertex: "gcp.vertex_ai",
+    bedrock: "aws.bedrock",
+};
+const list = (key, vs) => vs.length
+    ? [{ key, value: { arrayValue: { values: vs.map((v) => ({ stringValue: v })) } } }]
+    : [];
+const strs = (key, v) => typeof v === "string" ? [{ key, value: { arrayValue: { values: [{ stringValue: v }] } } }] : [];
+const failure = (type, message) => ({
+    attrs: str("error.type", type),
+    status: { status: { code: 2, message } },
+});
+function toOtlpV2(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 label = typeof first.meta.label === "string" ? first.meta.label : undefined;
+    const conversation = str("gen_ai.conversation.id", session);
+    const spans = [];
+    // The session is the agent's invocation, with the findings as its events.
+    spans.push({
+        traceId,
+        spanId: root,
+        name: label ? `invoke_agent ${label}` : "invoke_agent",
+        kind: 1,
+        startTimeUnixNano: nanos(first.ts),
+        endTimeUnixNano: nanos(last.ts),
+        attributes: [
+            ...str("gen_ai.operation.name", "invoke_agent"),
+            ...str("gen_ai.agent.name", label),
+            ...conversation,
+            ...str("blackbox.session_id", session),
+            ...str("blackbox.mode", first.meta.mode),
+            ...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),
+                ...list("blackbox.owasp_asi", taxonomyOf(String(e.meta.code)).owasp.map((o) => o.id)),
+                ...list("blackbox.mitre_atlas", taxonomyOf(String(e.meta.code)).atlas.map((a) => a.id)),
+                ...int("blackbox.seq", e.seq),
+            ],
+        })),
+    });
+    // Model calls: CLIENT spans named `chat {model}`.
+    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 model = typeof end?.meta.model === "string" ? end.meta.model : undefined;
+        const provider = typeof e.meta.provider === "string" ? e.meta.provider : undefined;
+        const reason = String(end?.meta.reason ?? "incomplete");
+        const fail = !end
+            ? failure("incomplete", "no response recorded")
+            : end.kind === "llm.incomplete"
+                ? failure(reason, reason)
+                : typeof status === "number" && status >= 400
+                    ? failure(String(status), `status ${status}`)
+                    : null;
+        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.operation.name", "chat"),
+                ...str("gen_ai.provider.name", provider ? (PROVIDER_NAMES[provider] ?? provider) : undefined),
+                ...str("gen_ai.response.model", model),
+                ...str("gen_ai.response.id", end?.meta.message_id ?? end?.meta.response_id),
+                ...strs("gen_ai.response.finish_reasons", end?.meta.stop_reason ?? end?.meta.finish_reason),
+                ...(usage
+                    ? [
+                        ...int("gen_ai.usage.input_tokens", usage.input + usage.cache_read + usage.cache_write),
+                        ...int("gen_ai.usage.output_tokens", usage.output),
+                        ...(usage.cache_read
+                            ? int("gen_ai.usage.cache_read.input_tokens", usage.cache_read)
+                            : []),
+                        ...(usage.cache_write
+                            ? int("gen_ai.usage.cache_write.input_tokens", usage.cache_write)
+                            : []),
+                    ]
+                    : []),
+                ...conversation,
+                ...str("blackbox.provider", provider),
+                ...str("blackbox.region", e.meta.region),
+                ...int("http.response.status_code", status),
+                ...(fail ? fail.attrs : []),
+                ...int("blackbox.seq", e.seq),
+            ],
+            ...(fail ? fail.status : {}),
+        });
+    }
+    // MCP and broker calls, closed by their result (call_seq). MCP spans follow the MCP conventions.
+    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 broker = e.meta.via === "broker";
+        const method = typeof e.meta.method === "string" ? e.meta.method : undefined;
+        const tool = typeof e.meta.tool === "string" ? e.meta.tool : undefined;
+        const isCall = broker || method === "tools/call";
+        const fail = e.meta.policy !== undefined
+            ? failure("policy_denied", "denied by policy")
+            : end?.meta.rpc_error !== undefined
+                ? failure(String(end.meta.rpc_error), "rpc error")
+                : end?.meta.is_error === true
+                    ? failure("tool_error", "tool error")
+                    : broker && typeof end?.meta.status === "number" && end.meta.status >= 400
+                        ? failure(String(end.meta.status), `status ${end.meta.status}`)
+                        : null;
+        const rpcId = e.meta.rpc_id;
+        spans.push({
+            traceId,
+            spanId: spanId(e.seq),
+            parentSpanId: root,
+            name: broker
+                ? `execute_tool ${tool ?? "api"}`
+                : `${method ?? "mcp"}${tool && isCall ? ` ${tool}` : ""}`,
+            kind: 3,
+            startTimeUnixNano: nanos(e.ts),
+            endTimeUnixNano: nanos((end ?? e).ts),
+            attributes: [
+                ...(isCall ? str("gen_ai.operation.name", "execute_tool") : []),
+                ...str("gen_ai.tool.name", tool),
+                ...(broker ? str("gen_ai.tool.type", "extension") : []),
+                ...(broker ? [] : str("mcp.method.name", method)),
+                ...(broker ? [] : str("mcp.protocol.version", e.meta.protocol_version)),
+                ...(typeof rpcId === "string" || typeof rpcId === "number"
+                    ? str("jsonrpc.request.id", String(rpcId))
+                    : []),
+                ...(broker ? str("http.request.method", e.meta.method) : []),
+                ...(broker ? str("url.path", e.meta.path) : []),
+                ...str("blackbox.mcp_server", e.meta.server),
+                ...int("rpc.response.status_code", end?.meta.rpc_error),
+                ...conversation,
+                ...(fail ? fail.attrs : []),
+                ...int("blackbox.seq", e.seq),
+            ],
+            ...(fail ? fail.status : {}),
+        });
+    }
+    // The agent's own tools (SDK events): INTERNAL spans, from a call to the next result of its name.
+    const open = new Map();
+    const sdk = (e, type) => e.kind === "sdk.event" && e.meta.type === type;
+    for (const e of events) {
+        const name = typeof e.meta.name === "string" ? e.meta.name : undefined;
+        if (!name)
+            continue;
+        if (sdk(e, "tool.call"))
+            open.set(name, [...(open.get(name) ?? []), e]);
+        if (!sdk(e, "tool.result"))
+            continue;
+        const call = open.get(name)?.shift();
+        spans.push({
+            traceId,
+            spanId: spanId(e.seq),
+            parentSpanId: root,
+            name: `execute_tool ${name}`,
+            kind: 1,
+            startTimeUnixNano: nanos((call ?? e).ts),
+            endTimeUnixNano: nanos(e.ts),
+            attributes: [
+                ...str("gen_ai.operation.name", "execute_tool"),
+                ...str("gen_ai.tool.name", name),
+                ...str("gen_ai.tool.type", "function"),
+                ...conversation,
+                ...str("blackbox.reported_by", "agent"),
+                ...int("blackbox.seq", e.seq),
+            ],
+        });
+    }
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        ...str("service.name", "zanii-blackbox"),
+                        ...str("blackbox.session_id", session),
+                    ],
+                },
+                scopeSpans: [
+                    {
+                        scope: { name: "zanii-blackbox", version: "2" },
+                        schemaUrl: "https://opentelemetry.io/schemas/1.44.0",
+                        spans,
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/policy/index.d.ts

@@ -11,7 +11,23 @@ export interface Rule {
     reason?: string;
     /** N3 (idea C5): record-only. Never decides a call; what it would do is recorded (POLICY_AUDIT). */
     audit?: boolean;
+    /** spec/policy.md §1: MCP tool annotations the call must have (from the server's `tools/list`). */
+    hints?: Partial<ToolHints>;
 }
+/** MCP tool annotations as booleans, with the spec's defaults for what a server leaves out. */
+export interface ToolHints {
+    read_only: boolean;
+    destructive: boolean;
+    idempotent: boolean;
+    open_world: boolean;
+}
+/**
+ * spec/policy.md §1: a tool's annotations (MCP `readOnlyHint`, `destructiveHint`, `idempotentHint`,
+ * `openWorldHint`) as hints. Missing ones take MCP's defaults: not read-only, destructive, not
+ * idempotent, open-world; destructive and idempotent only mean something for a tool that writes.
+ * An unknown tool gets the defaults too. Hints are the server's word, not proof.
+ */
+export declare function mcpToolHints(annotations?: unknown): ToolHints;
 export interface Policy {
     version: 1;
     rules: Rule[];
@@ -31,11 +47,12 @@ interface Compiled {
 /** Parses a policy file; throws on anything invalid (the server refuses to start). */
 export declare function loadPolicy(bytes: Uint8Array): Policy;
 export declare function compilePolicy(policy: Policy): Compiled[];
-/** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool has two). */
-export declare function decide(compiled: readonly Compiled[], names: readonly string[], args: unknown): Decision | null;
+/** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool
+ * has two). `hints`: an MCP tool's annotations; a rule with `hints` never matches a call without. */
+export declare function decide(compiled: readonly Compiled[], names: readonly string[], args: unknown, hints?: ToolHints): Decision | null;
 export type CompiledPolicy = ReturnType<typeof compilePolicy>;
 /** N3 (idea C5): every audit rule this call matches, and what it would do if it were enforced. */
-export declare function audited(compiled: readonly Compiled[], names: readonly string[], args: unknown): Array<{
+export declare function audited(compiled: readonly Compiled[], names: readonly string[], args: unknown, hints?: ToolHints): Array<{
     rule: string;
     would: Rule["action"];
 }>;