@zanii/blackbox 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,15 +1,21 @@
+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";
 export { type Directive, type DirectiveItem, type DirectiveOptions, directives, fleetDirectives, } from "./directives/index.ts";
 export { checkDrill, drillReport, type Fault as DrillFault } from "./drills/index.ts";
 export { checkDuty, type DutyFinding, type DutyLimits, dutyFindings } from "./duty/index.ts";
@@ -24,10 +30,10 @@ export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Con
 export { filingPack, type OccurrenceFacts, type OccurrenceFramework, type OccurrenceReport, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.ts";
 export { ingestOcsf, type OcsfEvent, type OcsfVersion, ocsfLine, toOcsf } from "./ocsf/index.ts";
 export { toOtlp } from "./otlp/index.ts";
-export { checkPack, corePack, type PackEntry, packFrameworks } from "./packs/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";
@@ -37,7 +43,9 @@ export { type Finding, type FindingCode, type Harness, loadLocal, type Reconcile
 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, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.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,17 +1,23 @@
 // 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";
 export { directives, fleetDirectives, } from "./directives/index.js";
 export { checkDrill, drillReport } from "./drills/index.js";
 export { checkDuty, dutyFindings } from "./duty/index.js";
@@ -26,10 +32,10 @@ export { anthropicStatement, baselines, checkConnector, checkStatement, csvState
 export { filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
 export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
 export { toOtlp } from "./otlp/index.js";
-export { checkPack, corePack, packFrameworks } from "./packs/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";
@@ -39,7 +45,9 @@ export { loadLocal, RecordNotVerified, reconcile, } from "./reconcile/index.js";
 export { cassette, requestKey } from "./replay/index.js";
 export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.js";
 export { drainSpools } from "./session/drain.js";
-export { BlackboxSession, session, stableEventId, } from "./session/index.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/packs/index.d.ts

@@ -1,3 +1,4 @@
+import { type DataRules } from "../data/index.ts";
 type Obj = Record<string, unknown>;
 export interface PackEntry {
     pack: string;
@@ -9,6 +10,13 @@ export interface PackEntry {
 }
 /** 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;

package/dist/packs/index.js

@@ -1,6 +1,7 @@
 // Framework packs (spec/packs.md): compliance and occurrence frameworks as data a deployment
 // switches on. Pure; mirrors sdks/python/src/zanii_blackbox/packs.py; pinned by
-// spec/vectors/packs.json.
+// spec/vectors/packs.json. The `data` part is spec/data.md §4.
+import { CORE_EVIDENCE, CORE_IDENTIFIERS } from "../data/index.js";
 const FACTS = new Set([
     "sessions",
     "events",
@@ -130,7 +131,9 @@ function checkArabic(ar, fw, at) {
 export function checkPack(value) {
     if (!isObj(value))
         return "a pack must be an object";
+    // `data` came later (spec/data.md §4); the pinned messages below name the v1 keys only.
     if (!only(value, [
+        "data",
         "v",
         "id",
         "title",
@@ -154,7 +157,7 @@ export function checkPack(value) {
             typeof value.reviewed_at !== "string" ||
             !DATE.test(value.reviewed_at)))
         return "a reviewed pack needs reviewed_by and reviewed_at (YYYY-MM-DD)";
-    if (value.compliance === undefined && value.occurrence === undefined)
+    if (value.compliance === undefined && value.occurrence === undefined && value.data === undefined)
         return "a pack needs compliance, occurrence or both";
     for (const kind of ["compliance", "occurrence"])
         if (value[kind] !== undefined) {
@@ -162,8 +165,131 @@ export function checkPack(value) {
             if (bad)
                 return bad;
         }
+    return value.data === undefined ? undefined : checkData(value.data);
+}
+const IDENTIFIER_ID = /^[a-z0-9_]{1,64}$/;
+const NORMALIZE = new Set(["digits", "lower", "upper", "exact"]);
+// Escapes Python reads over Unicode and JavaScript over ASCII (spec/data.md §1).
+const UNPORTABLE = /\\[dDwWbBsS]/;
+const ALLOW = /^(?:region|model|tool|api):(?:[A-Za-z0-9._-]{1,128}\*?|\*)$/;
+const TOOL = /^[A-Za-z0-9._-]{1,128}$/;
+const FIELD = /^[A-Za-z0-9_.-]{1,64}$/;
+const compiles = (pattern) => {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** spec/data.md §1: why an identifier is invalid, or undefined. */
+export function checkIdentifier(v, at) {
+    if (!isObj(v) ||
+        !only(v, ["id", "title", "pattern", "normalize", "keep_last", "check", "personal"]))
+        return `${at} may only have id, title, pattern, normalize, keep_last, check, personal`;
+    if (typeof v.id !== "string" || !IDENTIFIER_ID.test(v.id))
+        return `${at}.id must be 1-64 of a-z 0-9 _`;
+    if (!text(v.title, 200))
+        return `${at}.title must be 1-200 characters`;
+    if (typeof v.pattern !== "string" || !text(v.pattern, 500) || !compiles(v.pattern))
+        return `${at}.pattern must be a regular expression of 1-500 characters`;
+    if (UNPORTABLE.test(v.pattern))
+        return `${at}.pattern must not use \\d \\w \\b or \\s`;
+    if (!NORMALIZE.has(v.normalize))
+        return `${at}.normalize must be digits, lower, upper or exact`;
+    if (v.keep_last !== undefined &&
+        (!Number.isInteger(v.keep_last) || v.keep_last < 1 || v.keep_last > 30))
+        return `${at}.keep_last must be 1-30`;
+    if (v.check !== undefined && v.check !== "luhn")
+        return `${at}.check must be luhn`;
+    if (typeof v.personal !== "boolean")
+        return `${at}.personal must be true or false`;
+    return undefined;
+}
+function checkData(part) {
+    if (!isObj(part) || !only(part, ["notes", "identifiers", "residency", "restricted", "evidence"]))
+        return "data may only have notes, identifiers, residency, restricted, evidence";
+    if (!text(part.notes, 2000))
+        return "data.notes must be 1-2000 characters";
+    const ids = part.identifiers ?? [];
+    if (!Array.isArray(ids) || ids.length > 50)
+        return "data.identifiers must hold 0-50 identifiers";
+    const seen = new Set(CORE_IDENTIFIERS.map((i) => i.id));
+    for (const [i, v] of ids.entries()) {
+        const bad = checkIdentifier(v, `data.identifiers[${i}]`);
+        if (bad)
+            return bad;
+        const id = v.id;
+        if (seen.has(id))
+            return `data.identifiers[${i}].id ${id} is already defined`;
+        seen.add(id);
+    }
+    if (part.residency !== undefined && typeof part.residency !== "boolean")
+        return "data.residency must be true or false";
+    const rules = part.restricted ?? [];
+    if (!Array.isArray(rules) || rules.length > 50)
+        return "data.restricted must hold 0-50 rules";
+    for (const [i, r] of rules.entries()) {
+        const at = `data.restricted[${i}]`;
+        if (!isObj(r) || !only(r, ["identifiers", "allow"]))
+            return `${at} must be {identifiers, allow}`;
+        if (!Array.isArray(r.identifiers) ||
+            r.identifiers.length < 1 ||
+            r.identifiers.length > 50 ||
+            !r.identifiers.every((x) => typeof x === "string" && seen.has(x)))
+            return `${at}.identifiers must hold 1-50 known identifier ids`;
+        if (!Array.isArray(r.allow) ||
+            r.allow.length < 1 ||
+            r.allow.length > 20 ||
+            !r.allow.every((x) => typeof x === "string" && ALLOW.test(x)))
+            return `${at}.allow must hold 1-20 of region:, model:, tool:, api:`;
+    }
+    const evidence = part.evidence ?? [];
+    if (!Array.isArray(evidence) || evidence.length > 200)
+        return "data.evidence must hold 0-200 rules";
+    for (const [i, e] of evidence.entries())
+        if (!isObj(e) ||
+            !only(e, ["tool", "field"]) ||
+            typeof e.tool !== "string" ||
+            !TOOL.test(e.tool) ||
+            typeof e.field !== "string" ||
+            !FIELD.test(e.field))
+            return `data.evidence[${i}] must be {tool, field}`;
     return 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 function packData(packs) {
+    const identifiers = [];
+    const restricted = [];
+    const evidence = [];
+    const owner = new Map();
+    let residency = false;
+    for (const p of packs) {
+        const bad = checkPack(p);
+        const id = isObj(p) && typeof p.id === "string" ? p.id : "?";
+        if (bad)
+            throw new Error(`pack ${id}: ${bad}`);
+        const data = p.data;
+        if (!data)
+            continue;
+        for (const ident of data.identifiers ?? []) {
+            const had = owner.get(ident.id);
+            if (had)
+                throw new Error(`identifier ${ident.id} is in packs ${had} and ${id}`);
+            owner.set(ident.id, id);
+            identifiers.push(ident);
+        }
+        residency ||= data.residency === true;
+        restricted.push(...(data.restricted ?? []));
+        evidence.push(...(data.evidence ?? []));
+    }
+    identifiers.push(...CORE_IDENTIFIERS);
+    return { identifiers, residency, restricted, evidence: [...evidence, ...CORE_EVIDENCE] };
+}
 /** spec/packs.md §2: the core pack, from the built-in frameworks files. */
 export function corePack(compliance, occurrence) {
     return {

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"];
 }>;