@zanii/blackbox 0.2.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 The TypeScript SDK for [Zanii Blackbox](https://zanii.agency), the flight recorder for AI agents.
 
-Blackbox records every model call and tool call your agent makes, from a gateway that runs outside the agent's process. The records are hash-chained, so an edit or a deletion shows, and anchored as receipts that anyone can verify offline. This SDK is optional. It adds what only the agent knows (steps, its own tools, its checks, the outcome) as a second, independent record, and it reads and verifies what the gateway recorded.
+Blackbox records every model call and tool call your agent makes, for any industry and any organisation, from a gateway that runs outside the agent's process. The records are hash-chained, so an edit or a deletion shows, and anchored as receipts that anyone can verify offline. This SDK is optional. It adds what only the agent knows (steps, its own tools, its checks, the outcome) as a second, independent record, and it reads and verifies what the gateway recorded.
 
 ```sh
 npm install @zanii/blackbox
@@ -65,6 +65,31 @@ await s.close("success");
 - **It stays out of the way.** Recording is non-blocking with bounded memory. A recorded call costs about 0.3 ms (measured over 20,000 calls on a laptop); shipping happens in the background.
 - **It has no other runtime dependencies** besides the Zanii core libraries.
 
+## Hallucination controls
+
+The gateway checks every record, with no model needed: an invented tool or ID, arguments a tool's schema refuses, "done" right after an error, and amounts, doses, dates and IDs in answers that nothing the agent was given holds. With your organisation's own **reference packs** (prices, fees, rules, limits) it also catches answers that contradict them, and your own grounding model and judge can plug in. A risky answer can be held for a person before your customer sees it.
+
+From the SDK, pin what the agent read, then check an answer's signed credential anywhere:
+
+```ts
+import { verifyAnswerCredential, verifyCertificate } from "@zanii/blackbox";
+
+s.retrieved([{ id: "returns-policy", version: "2026-10", content: policyText }]); // hashed here, never sent
+
+// later, from GET /v1/sessions/:id/answers/:seq/credential and the session's record:
+verifyCertificate(credential).ok;                       // signed by the gateway
+verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: the record backs every claim
+```
+
+The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
+
+## New in 0.4.0
+
+- Hallucination controls: the checks above, reference packs, answer credentials (`answerClaims`, `answerCredential`, `verifyAnswerCredential`), `session.retrieved()`, accuracy from people's labels (`detectorAccuracy`, Wilson bounds), the grounding and judge contracts, `answerRisk` for held answers.
+- Keyed redaction tokens (`tokenFor`, `resolveTokens`).
+- Evidence for payments, health and public services (`payment`, `healthAccess`, `decision` and their verifiers); provable agent memory (`memoryChain`); record badges, agent CVs, SLAs, ledger co-signing and the post-quantum binding.
+- Compliance reports in Arabic, and the hallucination-controls report (`hallucinationFacts`).
+
 ## Frameworks
 
 | Framework | Use |

package/dist/a2a/index.d.ts

@@ -0,0 +1,77 @@
+import { type Json } from "../verify/envelope.ts";
+type Meta = {
+    [key: string]: Json;
+};
+/** The methods whose answer is an SSE stream. */
+export declare const A2A_STREAMING: Set<string>;
+/** The v1.0 name of an A2A method, either name set, or undefined for one A2A doesn't define. */
+export declare function a2aMethod(method: string): string | undefined;
+/**
+ * §2: a request's meta. `version` and `extensions` are the A2A-Version and A2A-Extensions headers
+ * (or the A2A-Version query parameter); an empty version means 0.3.
+ */
+export declare function a2aRequestMeta(body: Uint8Array, headers?: {
+    version?: string | null;
+    extensions?: string | null;
+}): Meta;
+/** §2: an answer's meta: a JSON body, or (for a stream) one SSE event's `data:` lines. */
+export declare function a2aResponseMeta(bytes: Uint8Array, contentType: string | undefined): Meta;
+/** `sha256:<hex>` of the card's JCS form without `signatures`: what `agent.card_digest` names. */
+export declare function agentCardDigest(card: Record<string, unknown>): string;
+/** What an Agent Card's JWS signs: BASE64URL(JCS(card without signatures)). */
+export declare function agentCardPayload(card: Record<string, unknown>): string;
+export interface AgentCardReport {
+    ok: boolean;
+    digest: string | null;
+    /** Each signature's kid and alg, and whether it verifies under the keys given (null: no such key). */
+    signatures: Array<{
+        kid: string | null;
+        alg: string | null;
+        ok: boolean | null;
+    }>;
+    problems: string[];
+}
+type Jwk = {
+    kty?: string;
+    crv?: string;
+    kid?: string;
+    x?: string;
+    y?: string;
+    n?: string;
+    e?: string;
+};
+/**
+ * §3: checks an Agent Card's signatures against trusted JWKs (by kid): each is a JWS over
+ * BASE64URL(protected) "." BASE64URL(JCS(card without signatures)), ES256, RS256 or EdDSA. The card
+ * is canonicalised as received (A2A's proto default-dropping can't be known from JSON). `ok` when at
+ * least one signature verifies.
+ */
+export declare function verifyAgentCard(card: unknown, keys: readonly Jwk[]): AgentCardReport;
+/**
+ * spec/a2a.md §3a (L3): the card as the gateway serves it, so a client that follows it stays on the
+ * record: every JSON-RPC interface points at `gatewayUrl`, other bindings (which the gateway can't
+ * capture) are dropped, and the publisher's signatures, which no longer hold, are replaced by the
+ * gateway's own EdDSA signature (kid: its did:key).
+ */
+export declare function rewriteAgentCard(card: Record<string, unknown>, o: {
+    gatewayUrl: string;
+    signer: {
+        kid: string;
+        seed: Uint8Array;
+    };
+}): Record<string, unknown>;
+/** The JWK of a gateway's Ed25519 did:key, to check a card it rewrote with verifyAgentCard. */
+export declare function gatewayCardKey(did: string): Jwk;
+/** The A2A method and task a REST call is, or undefined for a path that isn't one of A2A's. */
+export declare function a2aRestMethod(httpMethod: string, path: string): {
+    method: string;
+    taskId?: string;
+} | undefined;
+/** §2a: a REST call's meta: the same fields as a JSON-RPC call's, with `binding: "http+json"`. */
+export declare function a2aRestRequestMeta(httpMethod: string, path: string, body: Uint8Array, headers?: {
+    version?: string | null;
+    extensions?: string | null;
+}): Meta;
+/** §2a: a REST answer's meta (a bare Task, a `{task | message}`, or one SSE event's StreamResponse). */
+export declare function a2aRestResponseMeta(bytes: Uint8Array, contentType: string | undefined): Meta;
+export {};

package/dist/a2a/index.js

@@ -0,0 +1,305 @@
+// A2A v1.0 capture (spec/a2a.md): what the gateway records of an agent-to-agent JSON-RPC call (both
+// the v1.0 PascalCase methods and the v0.3 names), of each answer or stream event, and the check of
+// an Agent Card's JWS signatures (A2A §8.4: detached, over the JCS card without `signatures`).
+// Mirrors sdks/python/src/zanii_blackbox/a2a.py.
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { canonicalBytes, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign } from "../transparency/index.js";
+import { assertSafeIntegers } from "../verify/envelope.js";
+/** v0.3 method names → v1.0 (A2A §9.4). */
+const LEGACY = {
+    "message/send": "SendMessage",
+    "message/stream": "SendStreamingMessage",
+    "tasks/get": "GetTask",
+    "tasks/list": "ListTasks",
+    "tasks/cancel": "CancelTask",
+    "tasks/resubscribe": "SubscribeToTask",
+    "tasks/pushNotificationConfig/set": "CreateTaskPushNotificationConfig",
+    "tasks/pushNotificationConfig/get": "GetTaskPushNotificationConfig",
+    "tasks/pushNotificationConfig/list": "ListTaskPushNotificationConfigs",
+    "tasks/pushNotificationConfig/delete": "DeleteTaskPushNotificationConfig",
+    "agent/getAuthenticatedExtendedCard": "GetExtendedAgentCard",
+};
+const V1 = new Set(Object.values(LEGACY));
+/** The methods whose answer is an SSE stream. */
+export const A2A_STREAMING = new Set(["SendStreamingMessage", "SubscribeToTask"]);
+/** The v1.0 name of an A2A method, either name set, or undefined for one A2A doesn't define. */
+export function a2aMethod(method) {
+    return V1.has(method) ? method : LEGACY[method];
+}
+const str = (v, max) => (typeof v === "string" && v.length <= max ? v : undefined);
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : {};
+const rpcId = (id) => typeof id === "string" && id.length <= 256
+    ? id
+    : typeof id === "number" && Number.isSafeInteger(id)
+        ? id
+        : undefined;
+const put = (meta, key, value) => {
+    if (value !== undefined)
+        meta[key] = value;
+};
+/**
+ * §2: a request's meta. `version` and `extensions` are the A2A-Version and A2A-Extensions headers
+ * (or the A2A-Version query parameter); an empty version means 0.3.
+ */
+export function a2aRequestMeta(body, headers = {}) {
+    let rpc = {};
+    try {
+        rpc = obj(JSON.parse(Buffer.from(body).toString("utf8")));
+    }
+    catch { }
+    const meta = { a2a_version: str(headers.version, 16) || "0.3" };
+    const ext = (headers.extensions ?? "")
+        .split(",")
+        .map((e) => e.trim())
+        .filter((e) => e !== "" && e.length <= 256)
+        .slice(0, 10);
+    if (ext.length > 0)
+        meta.extensions = ext;
+    const method = str(rpc.method, 128);
+    put(meta, "method", method);
+    const canonical = method === undefined ? undefined : a2aMethod(method);
+    put(meta, "a2a_method", canonical);
+    if (method !== undefined && canonical !== undefined && canonical !== method)
+        meta.legacy = true;
+    put(meta, "rpc_id", rpcId(rpc.id));
+    const p = obj(rpc.params);
+    put(meta, "tenant", str(p.tenant, 128));
+    if (canonical === "SendMessage" || canonical === "SendStreamingMessage") {
+        const m = obj(p.message);
+        put(meta, "message_id", str(m.messageId, 128));
+        put(meta, "context_id", str(m.contextId, 128));
+        put(meta, "task_id", str(m.taskId, 128));
+        put(meta, "role", str(m.role, 32));
+    }
+    else if (canonical !== undefined && /Task$/.test(canonical))
+        put(meta, "task_id", str(p.id, 128));
+    return meta;
+}
+const LEGACY_KINDS = {
+    task: "task",
+    message: "message",
+    "status-update": "statusUpdate",
+    "artifact-update": "artifactUpdate",
+};
+const STATE = /^TASK_STATE_[A-Z_]{1,32}$/;
+const legacyState = (s) => typeof s === "string" && /^[a-z-]{1,32}$/.test(s)
+    ? `TASK_STATE_${s.replaceAll("-", "_").toUpperCase()}`
+    : undefined;
+/** One JSON-RPC response (or SSE event's data), as meta. */
+function responseOf(rpc) {
+    const meta = {};
+    put(meta, "rpc_id", rpcId(rpc.id));
+    const code = obj(rpc.error).code;
+    if (typeof code === "number" && Number.isSafeInteger(code))
+        meta.rpc_error = code;
+    const result = obj(rpc.result);
+    // v1.0: a oneof by key; v0.3: `kind`
+    let type = ["task", "message", "statusUpdate", "artifactUpdate"].find((k) => k in result);
+    let inner = type ? obj(result[type]) : {};
+    if (!type && typeof result.kind === "string" && result.kind in LEGACY_KINDS) {
+        type = LEGACY_KINDS[result.kind];
+        inner = result;
+    }
+    if (!type)
+        return meta;
+    meta.result_type = type;
+    put(meta, "task_id", str(type === "task" ? inner.id : inner.taskId, 128));
+    put(meta, "context_id", str(inner.contextId, 128));
+    const state = obj(inner.status).state;
+    put(meta, "task_state", typeof state === "string" && STATE.test(state) ? state : legacyState(state));
+    if (type === "artifactUpdate")
+        put(meta, "artifact_id", str(obj(inner.artifact).artifactId, 128));
+    return meta;
+}
+/** §2: an answer's meta: a JSON body, or (for a stream) one SSE event's `data:` lines. */
+export function a2aResponseMeta(bytes, contentType) {
+    let text = Buffer.from(bytes).toString("utf8");
+    if (contentType?.includes("text/event-stream"))
+        text = text
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).trim())
+            .join("\n");
+    try {
+        return responseOf(obj(JSON.parse(text)));
+    }
+    catch {
+        return {};
+    }
+}
+// ---------------------------------------------------------------- Agent Cards (A2A §8.4)
+const b64u = (b) => Buffer.from(b).toString("base64url");
+/** `sha256:<hex>` of the card's JCS form without `signatures`: what `agent.card_digest` names. */
+export function agentCardDigest(card) {
+    const { signatures: _, ...rest } = card;
+    assertSafeIntegers(rest); // as Python's canonical JSON does
+    return `sha256:${createHash("sha256")
+        .update(canonicalBytes(rest))
+        .digest("hex")}`;
+}
+/** What an Agent Card's JWS signs: BASE64URL(JCS(card without signatures)). */
+export function agentCardPayload(card) {
+    const { signatures: _, ...rest } = card;
+    assertSafeIntegers(rest);
+    return b64u(canonicalBytes(rest));
+}
+function verifyJws(alg, jwk, input, sig) {
+    try {
+        const key = createPublicKey({ key: jwk, format: "jwk" });
+        if (alg === "ES256" && jwk.kty === "EC" && jwk.crv === "P-256")
+            return verify("sha256", input, { key, dsaEncoding: "ieee-p1363" }, sig);
+        if (alg === "RS256" && jwk.kty === "RSA")
+            return verify("sha256", input, key, sig);
+        if (alg === "EdDSA" && jwk.kty === "OKP" && jwk.crv === "Ed25519")
+            return verify(null, input, key, sig);
+    }
+    catch { }
+    return false;
+}
+/**
+ * §3: checks an Agent Card's signatures against trusted JWKs (by kid): each is a JWS over
+ * BASE64URL(protected) "." BASE64URL(JCS(card without signatures)), ES256, RS256 or EdDSA. The card
+ * is canonicalised as received (A2A's proto default-dropping can't be known from JSON). `ok` when at
+ * least one signature verifies.
+ */
+export function verifyAgentCard(card, keys) {
+    const report = { ok: false, digest: null, signatures: [], problems: [] };
+    const c = obj(card);
+    if (Object.keys(c).length === 0)
+        return { ...report, problems: ["not an Agent Card"] };
+    let payload;
+    try {
+        report.digest = agentCardDigest(c);
+        payload = agentCardPayload(c);
+    }
+    catch {
+        return { ...report, problems: ["the card can't be canonicalised (non-integer numbers?)"] };
+    }
+    const sigs = Array.isArray(c.signatures) ? c.signatures.slice(0, 10) : [];
+    if (sigs.length === 0)
+        report.problems.push("the card isn't signed");
+    for (const s of sigs) {
+        const sig = obj(s);
+        let header = {};
+        try {
+            header = obj(JSON.parse(Buffer.from(String(sig.protected), "base64url").toString("utf8")));
+        }
+        catch { }
+        const kid = str(header.kid, 256) ?? null;
+        const alg = str(header.alg, 16) ?? null;
+        const jwk = keys.find((k) => k.kid !== undefined && k.kid === kid);
+        const ok = jwk && alg && typeof sig.protected === "string" && typeof sig.signature === "string"
+            ? verifyJws(alg, jwk, Buffer.from(`${sig.protected}.${payload}`), Buffer.from(sig.signature, "base64url"))
+            : null;
+        report.signatures.push({ kid, alg, ok });
+    }
+    report.ok = report.signatures.some((s) => s.ok === true);
+    if (sigs.length > 0 && !report.ok)
+        report.problems.push(report.signatures.some((s) => s.ok === false)
+            ? "a signature doesn't verify"
+            : "no signature is by a trusted key");
+    return report;
+}
+const JSONRPC = (t) => typeof t === "string" && t.toUpperCase().replace(/[-_]/g, "") === "JSONRPC";
+/**
+ * spec/a2a.md §3a (L3): the card as the gateway serves it, so a client that follows it stays on the
+ * record: every JSON-RPC interface points at `gatewayUrl`, other bindings (which the gateway can't
+ * capture) are dropped, and the publisher's signatures, which no longer hold, are replaced by the
+ * gateway's own EdDSA signature (kid: its did:key).
+ */
+export function rewriteAgentCard(card, o) {
+    const { signatures: _drop, ...rest } = card;
+    const out = { ...rest };
+    if (Array.isArray(card.supportedInterfaces))
+        out.supportedInterfaces = card.supportedInterfaces
+            .filter((i) => i && typeof i === "object" && JSONRPC(i.protocolBinding ?? i.transport))
+            .map((i) => ({ ...i, url: o.gatewayUrl }));
+    if (typeof card.url === "string")
+        out.url = o.gatewayUrl;
+    if (card.preferredTransport !== undefined)
+        out.preferredTransport = "JSONRPC";
+    if (Array.isArray(card.additionalInterfaces))
+        out.additionalInterfaces = card.additionalInterfaces
+            .filter((i) => i && typeof i === "object" && JSONRPC(i.transport ?? i.protocolBinding))
+            .map((i) => ({ ...i, url: o.gatewayUrl }));
+    const header = b64u(new TextEncoder().encode(JSON.stringify({ alg: "EdDSA", kid: o.signer.kid, typ: "JOSE" })));
+    const input = new TextEncoder().encode(`${header}.${agentCardPayload(out)}`);
+    const signature = b64u(ed25519Sign(o.signer.seed, input));
+    return { ...out, signatures: [{ protected: header, signature }] };
+}
+/** The JWK of a gateway's Ed25519 did:key, to check a card it rewrote with verifyAgentCard. */
+export function gatewayCardKey(did) {
+    const pub = publicKeyFromDid(did);
+    if (!pub)
+        throw new Error("not an Ed25519 did:key");
+    return { kty: "OKP", crv: "Ed25519", x: b64u(pub), kid: did };
+}
+// ---------------------------------------------------------------- the HTTP+JSON binding (§2a, L8)
+/** A2A §11's REST routes, by HTTP method and path (after the agent's base, an optional `/v1`). */
+const REST = [
+    ["POST", /^\/message:send$/, "SendMessage"],
+    ["POST", /^\/message:stream$/, "SendStreamingMessage"],
+    ["GET", /^\/tasks$/, "ListTasks"],
+    ["GET", /^\/tasks\/([^/:]+)$/, "GetTask"],
+    ["POST", /^\/tasks\/([^/:]+):cancel$/, "CancelTask"],
+    ["GET", /^\/tasks\/([^/:]+):subscribe$/, "SubscribeToTask"],
+    ["POST", /^\/tasks\/([^/:]+):subscribe$/, "SubscribeToTask"],
+    ["POST", /^\/tasks\/([^/:]+)\/pushNotificationConfigs$/, "CreateTaskPushNotificationConfig"],
+    ["GET", /^\/tasks\/([^/:]+)\/pushNotificationConfigs$/, "ListTaskPushNotificationConfigs"],
+    ["GET", /^\/tasks\/([^/:]+)\/pushNotificationConfigs\/[^/]+$/, "GetTaskPushNotificationConfig"],
+    [
+        "DELETE",
+        /^\/tasks\/([^/:]+)\/pushNotificationConfigs\/[^/]+$/,
+        "DeleteTaskPushNotificationConfig",
+    ],
+    ["GET", /^\/extendedAgentCard$/, "GetExtendedAgentCard"],
+];
+/** The A2A method and task a REST call is, or undefined for a path that isn't one of A2A's. */
+export function a2aRestMethod(httpMethod, path) {
+    const p = (path.split("?")[0] ?? "").replace(/^\/v1(?=\/)/, "");
+    for (const [verb, re, method] of REST) {
+        if (verb !== httpMethod.toUpperCase())
+            continue;
+        const m = re.exec(p);
+        if (m)
+            return m[1] ? { method, taskId: decodeURIComponent(m[1]) } : { method };
+    }
+    return undefined;
+}
+/** §2a: a REST call's meta: the same fields as a JSON-RPC call's, with `binding: "http+json"`. */
+export function a2aRestRequestMeta(httpMethod, path, body, headers = {}) {
+    const r = a2aRestMethod(httpMethod, path);
+    let params = {};
+    try {
+        params = obj(JSON.parse(Buffer.from(body).toString("utf8")));
+    }
+    catch { }
+    if (r?.taskId !== undefined)
+        params = { ...params, id: r.taskId };
+    const rpc = r ? { method: r.method, params } : { params };
+    return {
+        ...a2aRequestMeta(new TextEncoder().encode(JSON.stringify(rpc)), headers),
+        binding: "http+json",
+    };
+}
+/** §2a: a REST answer's meta (a bare Task, a `{task | message}`, or one SSE event's StreamResponse). */
+export function a2aRestResponseMeta(bytes, contentType) {
+    let text = Buffer.from(bytes).toString("utf8");
+    if (contentType?.includes("text/event-stream"))
+        text = text
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).trim())
+            .join("\n");
+    let value;
+    try {
+        value = obj(JSON.parse(text));
+    }
+    catch {
+        return {};
+    }
+    const oneOf = ["task", "message", "statusUpdate", "artifactUpdate"].some((k) => k in value);
+    const result = oneOf ? value : "id" in value && "status" in value ? { task: value } : value;
+    return responseOf({ result });
+}

package/dist/agents/index.d.ts

@@ -8,6 +8,14 @@ export declare function memoryXray(lines: readonly string[], bodies: Bodies, rev
         seq: number;
         memory_id: string;
     }[];
+    chain?: {
+        ok: boolean;
+        length: number;
+        broken: Array<{
+            seq: number;
+            reason: string;
+        }>;
+    };
 };
 /** spec/agents.md §3. */
 export declare function causality(records: ReadonlyArray<readonly string[]>): {

package/dist/analysis/accuracy.d.ts

@@ -0,0 +1,24 @@
+export type Label = {
+    code: string;
+    verdict: "right" | "wrong" | "missed";
+};
+export interface Accuracy {
+    code: string;
+    right: number;
+    wrong: number;
+    missed: number;
+    /** right / (right + wrong): how often a finding was real. null with no right or wrong labels. */
+    precision: number | null;
+    /** right / (right + missed): how often a real case was found. null with neither. */
+    recall: number | null;
+    /** The Wilson 95% lower bounds of the two. */
+    precision_low: number | null;
+    recall_low: number | null;
+}
+/** The Wilson score interval's lower bound for `k` of `n`, at 95%; null when n = 0. */
+export declare function wilsonLow(k: number, n: number): number | null;
+/** §12: each code's accuracy, by code, and all codes together. */
+export declare function detectorAccuracy(labels: readonly Label[]): {
+    codes: Accuracy[];
+    overall: Accuracy;
+};

package/dist/analysis/accuracy.js

@@ -0,0 +1,45 @@
+// How right each check is (spec/findings.md §12, H5): people mark findings right or wrong, and
+// report hallucinations no check caught; from those labels, each code's precision and recall, with
+// a 95% lower bound an auditor can quote. Mirrors sdks/python/src/zanii_blackbox/analysis/
+// accuracy.py; pinned by spec/vectors/accuracy.json.
+const Z = 1.96;
+const round4 = (x) => Math.floor(x * 10_000 + 0.5) / 10_000;
+/** The Wilson score interval's lower bound for `k` of `n`, at 95%; null when n = 0. */
+export function wilsonLow(k, n) {
+    if (n === 0)
+        return null;
+    const p = k / n;
+    const z2 = Z * Z;
+    const centre = p + z2 / (2 * n);
+    const spread = Z * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n));
+    return round4(Math.max(0, (centre - spread) / (1 + z2 / n)));
+}
+function row(code, right, wrong, missed) {
+    const judged = right + wrong;
+    const real = right + missed;
+    return {
+        code,
+        right,
+        wrong,
+        missed,
+        precision: judged ? round4(right / judged) : null,
+        recall: real ? round4(right / real) : null,
+        precision_low: wilsonLow(right, judged),
+        recall_low: wilsonLow(right, real),
+    };
+}
+/** §12: each code's accuracy, by code, and all codes together. */
+export function detectorAccuracy(labels) {
+    const counts = new Map();
+    for (const l of labels) {
+        const c = counts.get(l.code) ?? { right: 0, wrong: 0, missed: 0 };
+        c[l.verdict]++;
+        counts.set(l.code, c);
+    }
+    const codes = [...counts.keys()].sort().map((code) => {
+        const c = counts.get(code);
+        return row(code, c.right, c.wrong, c.missed);
+    });
+    const sum = (k) => codes.reduce((n, c) => n + c[k], 0);
+    return { codes, overall: row("*", sum("right"), sum("wrong"), sum("missed")) };
+}

package/dist/analysis/credential.d.ts

@@ -0,0 +1,101 @@
+import type { Bodies } from "../reconcile/record.ts";
+import { type ReferencePack } from "./reference.ts";
+export interface ClaimEntry {
+    index: number;
+    kind: string;
+    value_sha256: string;
+    status: "grounded" | "ungrounded" | "contradicted";
+    via: "pack" | "exact";
+    evidence: Array<{
+        seq: number;
+        line_hash: string;
+    }>;
+    pack?: {
+        id: string;
+        version: string;
+        hash: string;
+        fact: string;
+    };
+}
+export interface AnswerClaims {
+    seq: number;
+    line_hash: string;
+    text_sha256: string;
+    claims: ClaimEntry[];
+    service?: {
+        seq: number;
+        line_hash: string;
+        outage: true;
+    } | {
+        seq: number;
+        line_hash: string;
+        model?: string;
+        version?: string;
+        claims: Array<{
+            index: number;
+            status: string;
+            text_sha256: string;
+            score?: number;
+        }>;
+    };
+    sources: Array<{
+        seq: number;
+        id: string;
+        uri?: string;
+        version?: string;
+        sha256: string;
+    }>;
+}
+/** spec/findings.md §11: the claims of every final answer on a record. */
+export declare function answerClaims(lines: readonly string[], bodies: Bodies, packs?: readonly ReferencePack[]): AnswerClaims[];
+/** spec/findings.md §11: the credential for one answer, unsigned; null when `seq` isn't a final
+ * answer. The server signs it (`signCertificate`). */
+export declare function answerCredential(lines: readonly string[], bodies: Bodies, seq: number, o: {
+    sessionId: string;
+    packs?: readonly ReferencePack[];
+}): {
+    v: number;
+    type: string;
+    session_id: string;
+    answer: {
+        seq: number;
+        line_hash: string;
+        text_sha256: string;
+    };
+    claims: ClaimEntry[];
+    service?: {
+        seq: number;
+        line_hash: string;
+        outage: true;
+    } | {
+        seq: number;
+        line_hash: string;
+        model?: string;
+        version?: string;
+        claims: Array<{
+            index: number;
+            status: string;
+            text_sha256: string;
+            score?: number;
+        }>;
+    };
+    sources: {
+        seq: number;
+        id: string;
+        uri?: string;
+        version?: string;
+        sha256: string;
+    }[];
+    packs: {
+        id: string;
+        version: string;
+        hash: string;
+    }[];
+    issued_at: string;
+} | null;
+/** §11: a credential checked against the record it names: recomputed, then compared field by field
+ * (the signature is `verifyCertificate`'s job). */
+export declare function verifyAnswerCredential(credential: Record<string, unknown>, lines: readonly string[], bodies: Bodies, packs?: readonly ReferencePack[]): {
+    ok: boolean;
+    problems: string[];
+};