@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/hooks/openai-agents.js

@@ -0,0 +1,40 @@
+// OpenAI Agents SDK (JS) run hooks (spec/sdk.md §5). Mirrors hooks/openai_agents.py.
+//
+//   const runner = new Runner();  attachBlackbox(runner, session);  await runner.run(agent, "…");
+//
+// The JS SDK's hooks are events on the Runner (agent / handoff / tool); it has no model-call event,
+// so model-call ids come from the gateway alone here.
+import { neverThrow } from "./shared.js";
+const nameOf = (x) => String(x?.name ?? "agent").slice(0, 256);
+/** Audit K23: the SDK turns a tool's exception into this answer (its default error function), so a
+ *  tool that failed isn't recorded as a success. */
+const TOOL_ERROR = "An error occurred while running the tool.";
+const failed = (result) => typeof result === "string" && result.startsWith(TOOL_ERROR);
+export function attachBlackbox(runner, session) {
+    const on = (event, listener) => runner.on(event, ((...args) => neverThrow(() => listener(...args))));
+    on("agent_start", (_context, agent) => session.event("step", nameOf(agent), {}));
+    on("agent_handoff", (_context, from, to) => session.event("step", nameOf(to), { handoff_from: nameOf(from) }));
+    on("agent_tool_start", (_context, agent, tool, details) => {
+        const call = details
+            ?.toolCall;
+        let args = call?.arguments;
+        try {
+            args = typeof args === "string" ? JSON.parse(args) : args;
+        }
+        catch { }
+        session.event("tool.call", nameOf(tool), {
+            agent: nameOf(agent),
+            ...(call?.callId ? { call_id: call.callId } : {}),
+            ...(args === undefined ? {} : { args }),
+        });
+    });
+    on("agent_tool_end", (_context, agent, tool, result, details) => {
+        const callId = details?.toolCall?.callId;
+        session.event("tool.result", nameOf(tool), {
+            ok: !failed(result),
+            agent: nameOf(agent),
+            ...(callId ? { call_id: callId } : {}),
+            ...(failed(result) ? { error: String(result).slice(0, 500) } : {}),
+        });
+    });
+}

package/dist/hooks/protect.d.ts

@@ -0,0 +1,7 @@
+export declare const MANAGED_START = "<!-- blackbox:managed:start -->";
+export declare const MANAGED_END = "<!-- blackbox:managed:end -->";
+/** The managed block (markers included), or null when the text has none. */
+export declare function managedBlock(text: string): string | null;
+/** Why this file tool call must not run, or null. `current` is the file's text now (null when
+ * it doesn't exist). Tools: write_file {content}, edit_file {old_string, new_string}, delete. */
+export declare function protectedEdit(current: string | null, tool: string, args: Record<string, unknown>): string | null;

package/dist/hooks/protect.js

@@ -0,0 +1,39 @@
+// Protected regions (spec/sdk.md §5.2, idea S5): a machine-managed block in a file the agent may
+// edit (an AGENTS.md, a memory file), between `<!-- blackbox:managed:start -->` and
+// `<!-- blackbox:managed:end -->`. A write, edit or delete that would change or remove it is
+// refused before the tool runs. Mirrors protect.py.
+export const MANAGED_START = "<!-- blackbox:managed:start -->";
+export const MANAGED_END = "<!-- blackbox:managed:end -->";
+/** The managed block (markers included), or null when the text has none. */
+export function managedBlock(text) {
+    const i = text.indexOf(MANAGED_START);
+    const j = i < 0 ? -1 : text.indexOf(MANAGED_END, i);
+    return i < 0 || j < 0 ? null : text.slice(i, j + MANAGED_END.length);
+}
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** Why this file tool call must not run, or null. `current` is the file's text now (null when
+ * it doesn't exist). Tools: write_file {content}, edit_file {old_string, new_string}, delete. */
+export function protectedEdit(current, tool, args) {
+    const block = current === null ? null : managedBlock(current);
+    if (block === null)
+        return null;
+    const path = str(args.file_path) ?? str(args.path) ?? "the file";
+    const refuse = `blackbox: ${path} has a machine-managed block (between the blackbox:managed markers) that can't be changed or removed. The edit wasn't applied.`;
+    if (tool === "delete" || tool === "delete_file" || tool === "rm")
+        return `${refuse}`;
+    if (tool === "write_file") {
+        const content = str(args.content) ?? "";
+        return managedBlock(content) === block ? null : refuse;
+    }
+    if (tool === "edit_file") {
+        const oldText = str(args.old_string);
+        const newText = str(args.new_string) ?? "";
+        if (oldText === undefined || !current.includes(oldText))
+            return null; // the tool fails itself
+        const after = args.replace_all === true
+            ? current.split(oldText).join(newText)
+            : current.replace(oldText, () => newText);
+        return managedBlock(after) === block ? null : refuse;
+    }
+    return null;
+}

package/dist/hooks/providers.d.ts

@@ -0,0 +1,16 @@
+import { type EventSink } from "./shared.ts";
+/** The ids a provider's response (or its first stream event) carries, as `llmCall` takes them:
+ * Anthropic, OpenAI and OpenAI-compatible APIs (by `object`), Gemini and Vertex (`responseId`), and
+ * Bedrock (the AWS SDK's `$metadata.requestId`) (audit K4). */
+export declare function llmIdsOf(response: unknown): Record<string, string>;
+/** `client.messages.create` and `.stream` report each model call to the session. */
+export declare function wrapAnthropic<T extends object>(client: T, sink: EventSink): T;
+/** `client.chat.completions.create` / `.stream` and `client.responses.create` / `.stream` report
+ * each model call. */
+export declare function wrapOpenAI<T extends object>(client: T, sink: EventSink): T;
+/** Audit K4: Google's `@google/genai` client (Gemini, and Vertex AI with `vertexai: true`):
+ * `models.generateContent` and `models.generateContentStream` report each model call. */
+export declare function wrapGemini<T extends object>(client: T, sink: EventSink): T;
+/** Audit K4: the AWS SDK's `BedrockRuntimeClient`: every `send(command)` (Converse, ConverseStream,
+ * InvokeModel, …) reports its request id, which the gateway records from `x-amzn-requestid`. */
+export declare function wrapBedrock<T extends object>(client: T, sink: EventSink): T;

package/dist/hooks/providers.js

@@ -0,0 +1,149 @@
+// Audit S9 / S18: report model calls made with the official Anthropic and OpenAI clients, so the
+// dual witness (spec/findings.md §2) works without the app calling llmCall by hand. Duck-typed: no
+// dependency on either client. Mirrors sdks/python/src/zanii_blackbox/hooks/providers.py.
+//
+//   const anthropic = wrapAnthropic(new Anthropic({ baseURL: gateway }), session);
+//   const openai = wrapOpenAI(new OpenAI({ baseURL: gateway }), session);
+import { llmIds, neverThrow, providerOf } from "./shared.js";
+/** The ids a provider's response (or its first stream event) carries, as `llmCall` takes them:
+ * Anthropic, OpenAI and OpenAI-compatible APIs (by `object`), Gemini and Vertex (`responseId`), and
+ * Bedrock (the AWS SDK's `$metadata.requestId`) (audit K4). */
+export function llmIdsOf(response) {
+    const r = (response ?? {});
+    const google = r.responseId;
+    if (typeof google === "string" && ("candidates" in r || "usageMetadata" in r))
+        return {
+            provider: "gemini",
+            response_id: google,
+            ...(typeof r.modelVersion === "string" ? { model: r.modelVersion } : {}),
+        };
+    const aws = r.$metadata?.requestId;
+    if (typeof aws === "string")
+        return { provider: "bedrock", request_id: aws };
+    // A stream event: Anthropic's message_start carries `message`, OpenAI's response.* `response`.
+    const inner = (typeof r.message === "object" && r.message) ||
+        (typeof r.response === "object" && r.response) ||
+        r;
+    const o = inner;
+    const id = typeof o.id === "string" ? o.id : undefined;
+    const provider = providerOf(id, typeof o.object === "string" ? o.object : undefined);
+    if (!provider)
+        return {};
+    const requestId = typeof r._request_id === "string"
+        ? r._request_id
+        : typeof o._request_id === "string"
+            ? o._request_id
+            : undefined;
+    return {
+        provider,
+        ...llmIds(id, requestId, typeof o.model === "string" ? o.model : undefined, typeof o.object === "string" ? o.object : undefined),
+    };
+}
+/** `client.messages.create` and `.stream` report each model call to the session. */
+export function wrapAnthropic(client, sink) {
+    return wrap(client, [
+        ["messages", "create"],
+        ["messages", "stream"],
+        ["messages", "parse"],
+        // audit K18: the beta namespace (structured output, tools in preview) goes to the same API
+        ["beta", "messages", "create"],
+        ["beta", "messages", "stream"],
+        ["beta", "messages", "parse"],
+    ], sink);
+}
+/** `client.chat.completions.create` / `.stream` and `client.responses.create` / `.stream` report
+ * each model call. */
+export function wrapOpenAI(client, sink) {
+    return wrap(client, [
+        ["chat", "completions", "create"],
+        ["chat", "completions", "stream"],
+        ["responses", "create"],
+        ["responses", "stream"],
+        // audit K18: structured output and the beta namespace
+        ["chat", "completions", "parse"],
+        ["responses", "parse"],
+        ["beta", "chat", "completions", "parse"],
+        ["beta", "chat", "completions", "stream"],
+    ], sink);
+}
+/** Audit K4: Google's `@google/genai` client (Gemini, and Vertex AI with `vertexai: true`):
+ * `models.generateContent` and `models.generateContentStream` report each model call. */
+export function wrapGemini(client, sink) {
+    return wrap(client, [
+        ["models", "generateContent"],
+        ["models", "generateContentStream"],
+    ], sink);
+}
+/** Audit K4: the AWS SDK's `BedrockRuntimeClient`: every `send(command)` (Converse, ConverseStream,
+ * InvokeModel, …) reports its request id, which the gateway records from `x-amzn-requestid`. */
+export function wrapBedrock(client, sink) {
+    return wrap(client, [["send"]], sink);
+}
+/** The streaming helpers' promise of the final message, which carries the ids. */
+const FINAL = ["finalMessage", "finalChatCompletion", "finalResponse"];
+function wrap(target, paths, sink) {
+    return new Proxy(target, {
+        get(obj, prop, receiver) {
+            const value = Reflect.get(obj, prop, receiver);
+            const here = paths.filter((p) => p[0] === prop);
+            if (here.length === 0 || value === null || value === undefined)
+                return value;
+            if (here.some((p) => p.length === 1) && typeof value === "function")
+                return (...args) => {
+                    const result = value.apply(obj, args);
+                    neverThrow(() => observe(result, sink));
+                    return result; // the client's own promise, untouched (e.g. APIPromise.withResponse())
+                };
+            return typeof value === "object"
+                ? wrap(value, here.map((p) => p.slice(1)), sink)
+                : value;
+        },
+    });
+}
+function observe(result, sink) {
+    const then = result?.then;
+    if (typeof then !== "function") {
+        seen(result, sink);
+        return;
+    }
+    // Registered before the caller's own await, so a stream is patched before it's iterated.
+    result.then((r) => neverThrow(() => seen(r, sink)), () => { });
+}
+function seen(result, sink) {
+    if (result === null || typeof result !== "object")
+        return;
+    // A streaming helper (e.g. messages.stream()): whatever way the app reads it, its final message
+    // resolves once the stream ends.
+    for (const name of FINAL) {
+        const final = result[name];
+        if (typeof final === "function") {
+            final.call(result).then((m) => neverThrow(() => report(llmIdsOf(m), sink)), () => { });
+            return;
+        }
+    }
+    const iter = result[Symbol.asyncIterator];
+    if (typeof iter !== "function") {
+        report(llmIdsOf(result), sink);
+        return;
+    }
+    // A stream: the ids come with its first event that has one; the stream itself is unchanged.
+    const original = iter.bind(result);
+    let reported = false;
+    result[Symbol.asyncIterator] = async function* () {
+        for await (const event of { [Symbol.asyncIterator]: original }) {
+            if (!reported)
+                neverThrow(() => {
+                    const ids = llmIdsOf(event);
+                    if (ids.provider) {
+                        reported = true;
+                        report(ids, sink);
+                    }
+                });
+            yield event;
+        }
+    };
+}
+function report(ids, sink) {
+    if (ids.provider)
+        sink.event("llm.call", ids.provider, { ...ids });
+}

package/dist/hooks/shared.d.ts

@@ -0,0 +1,11 @@
+/** A BlackboxSession, or anything with the same `event` method. */
+export interface EventSink {
+    event(type: string, name?: string, data?: Record<string, unknown>): void;
+}
+/** Runs a hook body; a hook must never break the framework it's attached to (spec/sdk.md §4). */
+export declare function neverThrow(fn: () => void): void;
+/** A provider's response id → the key the gateway records it under (spec/findings.md §2). */
+export declare function llmIds(id: string | undefined, requestId?: string, model?: string, 
+/** An OpenAI-style `object` field: how an OpenAI-compatible API's own ids are told apart (K4). */
+object?: string): Record<string, string>;
+export declare function providerOf(id: string | undefined, object?: string): string | undefined;

package/dist/hooks/shared.js

@@ -0,0 +1,39 @@
+// What both hook adapters share. Mirrors sdks/python/src/zanii_blackbox/hooks/shared.py.
+/** Runs a hook body; a hook must never break the framework it's attached to (spec/sdk.md §4). */
+export function neverThrow(fn) {
+    try {
+        fn();
+    }
+    catch { }
+}
+/** A provider's response id → the key the gateway records it under (spec/findings.md §2). */
+export function llmIds(id, requestId, model, 
+/** An OpenAI-style `object` field: how an OpenAI-compatible API's own ids are told apart (K4). */
+object) {
+    const ids = {};
+    if (id) {
+        if (id.startsWith("resp_") || object === "response")
+            ids.response_id = id;
+        else if (id.startsWith("chatcmpl") || object?.startsWith("chat.completion"))
+            ids.completion_id = id;
+        else
+            ids.message_id = id;
+    }
+    if (requestId)
+        ids.request_id = requestId;
+    if (model)
+        ids.model = model;
+    return ids;
+}
+export function providerOf(id, object) {
+    if (!id)
+        return undefined;
+    if (id.startsWith("msg_"))
+        return "anthropic";
+    if (id.startsWith("resp_") || id.startsWith("chatcmpl"))
+        return "openai";
+    // audit K4: an OpenAI-compatible API (vLLM, Azure, Jais, …) with ids of its own
+    if (object === "response" || object?.startsWith("chat.completion"))
+        return "openai";
+    return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+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 { type ApprovalFinding, approvalFindings } from "./approvals/index.ts";
+export { textWarnings } from "./approvals/warnings.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 { BlackboxApiError, type Client, type ClientOptions, client, type SessionQuery, } from "./client/index.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";
+export { aggregateFindings, airworthiness, type Collision, collisions, didFromSeed, type FindingGroup, incidentReport, logbook, type Summary, sessionSummary, signatureOf, signatures, signCertificate, verifyCertificate, } from "./fleet/index.ts";
+export { attachBlackbox, BlackboxAgentHooks, BlackboxCallbackHandler, type BlackboxCallbacks, blackboxAgentHooks, blackboxCallbacks, blackboxMiddleware, type EventSink, llmIds, llmIdsOf, trackMemory, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI, } from "./hooks/index.ts";
+export { type AgentSink, BlackboxStoppedError, blackboxAgentMiddleware, blackboxHitl, type HitlRequest, } from "./hooks/langchain-agent.ts";
+export { blackboxCheckpointer } from "./hooks/langgraph-checkpoint.ts";
+export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks/protect.ts";
+export { type Investigation, investigation, renderInvestigation, } from "./investigate/index.ts";
+export { type McpWrapOptions, mcpWrap } from "./mcp-wrap/index.ts";
+export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Connector, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, type Statement, } from "./money/index.ts";
+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 { 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 { 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";
+export { type PreflightFinding, preflightFindings } from "./preflight/index.ts";
+export { type Rating, type TypeUnratedFinding, typeRatings, typeUnrated, } from "./ratings/index.ts";
+export { type Finding, type FindingCode, type Harness, loadLocal, type ReconcileOptions, RecordNotVerified, type Report, reconcile, } from "./reconcile/index.ts";
+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 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";
+export { type Conditions, type Sample, weather } from "./weather/index.ts";
+export { postReceipt, receiptFor, type Tree, workspaceTree } from "./workspace-receipt/index.ts";

package/dist/index.js

@@ -0,0 +1,48 @@
+// 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 { 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 { approvalFindings } from "./approvals/index.js";
+export { textWarnings } from "./approvals/warnings.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 { BlackboxApiError, client, } from "./client/index.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";
+export { aggregateFindings, airworthiness, collisions, didFromSeed, incidentReport, logbook, sessionSummary, signatureOf, signatures, signCertificate, verifyCertificate, } from "./fleet/index.js";
+export { attachBlackbox, BlackboxAgentHooks, BlackboxCallbackHandler, blackboxAgentHooks, blackboxCallbacks, blackboxMiddleware, llmIds, llmIdsOf, trackMemory, wrapAnthropic, wrapBedrock, wrapGemini, wrapOpenAI, } from "./hooks/index.js";
+export { BlackboxStoppedError, blackboxAgentMiddleware, blackboxHitl, } from "./hooks/langchain-agent.js";
+export { blackboxCheckpointer } from "./hooks/langgraph-checkpoint.js";
+export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks/protect.js";
+export { investigation, renderInvestigation, } from "./investigate/index.js";
+export { mcpWrap } from "./mcp-wrap/index.js";
+export { anthropicStatement, baselines, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, } from "./money/index.js";
+export { filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
+export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
+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 { 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";
+export { preflightFindings } from "./preflight/index.js";
+export { typeRatings, typeUnrated, } from "./ratings/index.js";
+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, checkEgress, session, stableEventId, } from "./session/index.js";
+export { checkCompensations, runUndo, undoFindings, undoPlan, } from "./undo/index.js";
+export * from "./verify/index.js";
+export { VERSION } from "./version.js";
+export { weather } from "./weather/index.js";
+export { postReceipt, receiptFor, workspaceTree } from "./workspace-receipt/index.js";

package/dist/investigate/index.d.ts

@@ -0,0 +1,66 @@
+import { type Span } from "../authority/index.ts";
+import type { Directive } from "../directives/index.ts";
+import { type Summary } from "../fleet/index.ts";
+export interface InvestigationOptions {
+    summary: Summary;
+    models: readonly string[];
+    directives?: readonly Directive[];
+}
+/** spec/investigations.md §1. */
+export declare function investigation(lines: readonly string[], opts: InvestigationOptions): {
+    kind: "blackbox.investigation";
+    v: 1;
+    session_id: string;
+    label: string | null;
+    started_at: string;
+    last_event_at: string;
+    events: number;
+    outcome: string | null;
+    authority: Span[];
+    findings: {
+        seq: number;
+        code: string;
+        fault: string;
+        severity: string;
+        source: string;
+        in_control: import("../authority/index.ts").Mode | null;
+        in_control_by: string | null;
+        weather: {} | null;
+    }[];
+    directives: {
+        id: string;
+        applies_to: {
+            model: string;
+        } | {
+            tool: string;
+        };
+        pattern: string[];
+        affected_ppm: number;
+    }[] | null;
+    drill: {
+        drill: true;
+        planned: import("../drills/index.ts").Fault[];
+        injected: {
+            seq: number;
+            kind: string;
+        }[];
+        findings_after: string[];
+        recovered: boolean;
+        outcome: string | null;
+    } | null;
+};
+export type Investigation = ReturnType<typeof investigation> & {
+    verification?: {
+        ok: boolean;
+        identity: boolean;
+        proofs: string;
+    };
+    investigated_at?: string;
+    bundle_sha256?: string;
+    signed?: {
+        by: string;
+        sig: string;
+    };
+};
+/** spec/investigations.md §3: the reading copy. The signed JSON is the report; this isn't. */
+export declare function renderInvestigation(r: Investigation): string;

package/dist/investigate/index.js

@@ -0,0 +1,119 @@
+// Investigations (spec/investigations.md): the independent investigator's report and its reading
+// copy. Pure; mirrors sdks/python/src/zanii_blackbox/investigate.py; pinned by
+// spec/vectors/investigations.json.
+import { faultOf } from "../analysis/faults.js";
+import { authorityTimeline } from "../authority/index.js";
+import { drillReport } from "../drills/index.js";
+import { signatureOf } from "../fleet/index.js";
+/** spec/investigations.md §1. */
+export function investigation(lines, opts) {
+    const { summary, models } = opts;
+    const authority = authorityTimeline(lines);
+    const spanAt = (seq) => authority.find((s) => seq >= s.from_seq && (s.to_seq === null || seq <= s.to_seq));
+    const findings = lines
+        .map((l) => JSON.parse(l))
+        .filter((e) => e.kind === "finding")
+        .map((e) => {
+        const code = String(e.meta.code);
+        const ref = e.meta.ref;
+        const span = spanAt(typeof ref?.seq === "number" ? ref.seq : e.seq);
+        return {
+            seq: e.seq,
+            code,
+            fault: faultOf(code).fault,
+            severity: String(e.meta.severity),
+            source: String(e.meta.source),
+            in_control: span?.mode ?? null,
+            in_control_by: span?.by ?? null,
+            weather: e.meta.weather ?? null,
+        };
+    });
+    const signature = signatureOf(summary)?.signature;
+    const matches = (d) => d.signature === signature &&
+        ("model" in d.applies_to
+            ? models.includes(d.applies_to.model)
+            : Object.hasOwn(summary.tools, d.applies_to.tool));
+    const drill = drillReport(lines);
+    return {
+        kind: "blackbox.investigation",
+        v: 1,
+        session_id: summary.session_id,
+        label: summary.label,
+        started_at: summary.started_at,
+        last_event_at: summary.last_event_at,
+        events: summary.events,
+        outcome: summary.outcome,
+        authority,
+        findings,
+        directives: opts.directives
+            ? opts.directives.filter(matches).map((d) => ({
+                id: d.id,
+                applies_to: d.applies_to,
+                pattern: d.pattern,
+                affected_ppm: d.affected_ppm,
+            }))
+            : null,
+        drill: drill.drill ? drill : null,
+    };
+}
+const cell = (v) => v === null || v === undefined || v === ""
+    ? "—"
+    : String(v)
+        .replace(/\r\n|\r|\n/g, " ")
+        .replace(/\|/g, "\\|");
+const row = (cells) => `| ${cells.map(cell).join(" | ")} |`;
+const head = (names) => [row(names), `|${names.map(() => "---|").join("")}`];
+/** spec/investigations.md §3: the reading copy. The signed JSON is the report; this isn't. */
+export function renderInvestigation(r) {
+    const out = [`# Investigation: ${r.session_id}`, "", ...head(["Fact", "Value"])];
+    const v = r.verification;
+    out.push(row(["Label", r.label]), row(["Started", r.started_at]), row(["Last event", r.last_event_at]), row(["Events", r.events]), row(["Outcome", r.outcome]), row([
+        "Record verified",
+        v === undefined
+            ? "not checked"
+            : `${v.ok ? "yes" : "NO"} (identity ${v.identity ? "ok" : "not ok"}, ledger proofs ${v.proofs.replace("_", " ")})`,
+    ]), row(["Bundle SHA-256", r.bundle_sha256]), row(["Investigator", r.signed ? r.signed.by : "unsigned"]), row(["Investigated at", r.investigated_at]));
+    if (v && !v.ok)
+        out.push("", "**The record does not verify. Everything below may have been altered.**");
+    out.push("", "## Who had the controls", "");
+    if (r.authority.length === 0)
+        out.push("No authority recorded.");
+    else {
+        out.push(...head(["From seq", "To seq", "Mode", "By", "Reason"]));
+        for (const s of r.authority)
+            out.push(row([s.from_seq, s.to_seq ?? "end", s.mode, s.by, s.reason]));
+    }
+    out.push("", "## Findings", "");
+    if (r.findings.length === 0)
+        out.push("None recorded.");
+    else {
+        out.push(...head(["Seq", "Code", "Fault", "Severity", "In control", "Weather"]));
+        for (const f of r.findings) {
+            const weather = Array.isArray(f.weather)
+                ? f.weather
+                    .map((w) => `${w.model}: ${w.status}`)
+                    .join(", ")
+                : null;
+            const control = f.in_control === null ? null : `${f.in_control} (${f.in_control_by ?? "—"})`;
+            out.push(row([f.seq, f.code, f.fault, f.severity, control, weather]));
+        }
+    }
+    out.push("", "## Matching directives", "");
+    if (r.directives === null)
+        out.push("No directives were given.");
+    else if (r.directives.length === 0)
+        out.push("None matched.");
+    else {
+        out.push(...head(["Directive", "Applies to", "Pattern", "Affected (ppm)"]));
+        for (const d of r.directives) {
+            const to = "model" in d.applies_to ? `model ${d.applies_to.model}` : `tool ${d.applies_to.tool}`;
+            out.push(row([d.id, to, d.pattern.join(", "), d.affected_ppm]));
+        }
+    }
+    if (r.drill) {
+        const d = r.drill;
+        out.push("", "## Drill", "", `This session was a drill: ${d.planned.length} faults planned, ${d.injected.length} injected (${d.injected.map((i) => i.kind).join(", ") || "none"}).`, `Recovered: ${d.recovered ? "yes" : "no"}. Findings after the first fault: ${d.findings_after.join(", ") || "none"}.`);
+    }
+    out.push("", "## What this report proves", "", "If the record verifies, these events are the ones the gateway recorded, in this order, and unchanged since. Its chain is intact and its anchors are signed by the pinned identity; with ledger proofs checked, they were also on the ledger at the times shown.", "It does not prove what the agent intended, or that the providers and tools behaved as their answers say. It also can't show what happened outside the gateway.", "The signature shows who wrote this report. Check it with `blackbox verify-certificate <report>.json --did <investigator>`.", "");
+    return out.join("\n");
+}