@zanii/blackbox 0.3.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

@@ -47,4 +47,31 @@ type Jwk = {
  * 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

@@ -3,7 +3,8 @@
 // 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 } from "@zanii/core";
+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 = {
@@ -200,3 +201,105 @@ export function verifyAgentCard(card, keys) {
             : "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[];
+};

package/dist/analysis/credential.js

@@ -0,0 +1,142 @@
+// The claim record and answer credentials (spec/findings.md §11, H3): for each final answer, every
+// fact in it, how it was checked (a pack, the record, the grounding service) and the record lines
+// that hold its evidence; and a credential for one answer that anyone holding the record can check.
+// Mirrors sdks/python/src/zanii_blackbox/analysis/credential.py; pinned by
+// spec/vectors/credential.json.
+import { createHash } from "node:crypto";
+import { canonical } from "../reconcile/shared.js";
+import { hashLine } from "../verify/envelope.js";
+import { answersOf, factsIn, parseGroundingAnswer } from "./grounding.js";
+import { checkAgainstPacks } from "./reference.js";
+const sha = (s) => `sha256:${createHash("sha256").update(s).digest("hex")}`;
+const decoder = new TextDecoder();
+/** spec/findings.md §11: the claims of every final answer on a record. */
+export function answerClaims(lines, bodies, packs = []) {
+    const hashes = new Map();
+    const verdicts = new Map();
+    const retrieved = [];
+    for (const l of lines) {
+        const e = JSON.parse(l);
+        hashes.set(e.seq, hashLine(l));
+        if (e.kind === "control" &&
+            e.meta.action === "grounding" &&
+            typeof e.meta.answer_seq === "number")
+            verdicts.set(e.meta.answer_seq, e); // the latest verdict for an answer is its verdict
+        if (e.kind === "sdk.event" && e.meta.type === "retrieved") {
+            const b = bodies(e.body_hash);
+            try {
+                const d = b ? JSON.parse(decoder.decode(b)) : {};
+                if (Array.isArray(d.docs))
+                    retrieved.push({ seq: e.seq, docs: d.docs });
+            }
+            catch { }
+        }
+    }
+    const at = (seq) => ({ seq, line_hash: hashes.get(seq) });
+    return answersOf(lines, bodies).map((a) => {
+        const claims = factsIn(a.text).map((f, index) => {
+            const base = { index, kind: f.kind, value_sha256: sha(f.value) };
+            const said = checkAgainstPacks(a.text, f, packs);
+            if (said) {
+                const pack = {
+                    id: said.pack.id,
+                    version: said.pack.version,
+                    hash: said.pack.hash,
+                    fact: said.fact.id,
+                };
+                return { ...base, status: said.status, via: "pack", evidence: [], pack };
+            }
+            const seqs = a.evidence.support(f);
+            return seqs
+                ? { ...base, status: "grounded", via: "exact", evidence: seqs.map(at) }
+                : { ...base, status: "ungrounded", via: "exact", evidence: [] };
+        });
+        const v = verdicts.get(a.seq);
+        let service;
+        if (v?.meta.outage === true)
+            service = { ...at(v.seq), outage: true };
+        else if (v) {
+            const b = bodies(v.body_hash);
+            let parsed = null;
+            try {
+                parsed = b ? parseGroundingAnswer(JSON.parse(decoder.decode(b))) : null;
+            }
+            catch { }
+            if (parsed)
+                service = {
+                    ...at(v.seq),
+                    ...(parsed.model ? { model: parsed.model } : {}),
+                    ...(parsed.version ? { version: parsed.version } : {}),
+                    claims: parsed.claims.map((c, index) => ({
+                        index,
+                        status: c.status,
+                        text_sha256: sha(c.text),
+                        ...(c.score !== undefined ? { score: c.score } : {}),
+                    })),
+                };
+        }
+        const sources = retrieved
+            .filter((r) => r.seq < a.seq)
+            .flatMap((r) => r.docs.flatMap((d) => {
+            const o = d;
+            if (typeof o.id !== "string" || typeof o.sha256 !== "string")
+                return [];
+            return [
+                {
+                    seq: r.seq,
+                    id: o.id,
+                    ...(typeof o.uri === "string" ? { uri: o.uri } : {}),
+                    ...(typeof o.version === "string" ? { version: o.version } : {}),
+                    sha256: o.sha256,
+                },
+            ];
+        }));
+        return {
+            ...at(a.seq),
+            text_sha256: sha(a.text),
+            claims,
+            ...(service ? { service } : {}),
+            sources,
+        };
+    });
+}
+/** spec/findings.md §11: the credential for one answer, unsigned; null when `seq` isn't a final
+ * answer. The server signs it (`signCertificate`). */
+export function answerCredential(lines, bodies, seq, o) {
+    const packs = o.packs ?? [];
+    const entry = answerClaims(lines, bodies, packs).find((x) => x.seq === seq);
+    if (!entry)
+        return null;
+    const ts = lines.map((l) => JSON.parse(l)).find((e) => e.seq === seq)?.ts;
+    return {
+        v: 1,
+        type: "answer_credential",
+        session_id: o.sessionId,
+        answer: { seq: entry.seq, line_hash: entry.line_hash, text_sha256: entry.text_sha256 },
+        claims: entry.claims,
+        ...(entry.service ? { service: entry.service } : {}),
+        sources: entry.sources,
+        packs: packs.map((p) => ({ id: p.id, version: p.version, hash: p.hash })),
+        issued_at: ts,
+    };
+}
+/** §11: a credential checked against the record it names: recomputed, then compared field by field
+ * (the signature is `verifyCertificate`'s job). */
+export function verifyAnswerCredential(credential, lines, bodies, packs = []) {
+    const answer = credential.answer;
+    if (typeof answer?.seq !== "number" || typeof credential.session_id !== "string")
+        return { ok: false, problems: ["malformed"] };
+    const again = answerCredential(lines, bodies, answer.seq, {
+        sessionId: credential.session_id,
+        packs,
+    });
+    if (!again)
+        return { ok: false, problems: ["the record has no such answer"] };
+    const problems = [];
+    const fields = new Set([...Object.keys(again), ...Object.keys(credential)]);
+    fields.delete("signed");
+    for (const k of [...fields].sort())
+        if (canonical(again[k] ?? null) !== canonical(credential[k] ?? null))
+            problems.push(`${k} differs from the record`);
+    return { ok: problems.length === 0, problems };
+}

package/dist/analysis/faults.js

@@ -28,6 +28,26 @@ export const FAULTS = {
         en: "File change outside any tool call",
         ar: "تغيير في الملفات خارج أي استدعاء أداة",
     },
+    INTEGRITY_FAILED: {
+        fault: "BBX-1107",
+        en: "A stored record failed the self-check",
+        ar: "فشل سجل محفوظ في الفحص الذاتي",
+    },
+    ANCHOR_STALE: {
+        fault: "BBX-1108",
+        en: "Anchoring has stalled",
+        ar: "توقّف تثبيت السجلات",
+    },
+    LEDGER_VIOLATION: {
+        fault: "BBX-1109",
+        en: "The ledger's log was rewritten",
+        ar: "أُعيدت كتابة سجل دفتر الأستاذ",
+    },
+    ANCHOR_REJECTED: {
+        fault: "BBX-1110",
+        en: "The ledger rejected an anchor",
+        ar: "رفض دفتر الأستاذ تثبيتًا",
+    },
     SDK_SILENT: {
         fault: "BBX-1201",
         en: "The SDK stopped reporting",
@@ -102,6 +122,46 @@ export const FAULTS = {
         en: "A check that passed now fails",
         ar: "فحص نجح سابقًا ثم فشل",
     },
+    UNKNOWN_TOOL: {
+        fault: "BBX-4301",
+        en: "A call to a tool that doesn't exist",
+        ar: "استدعاء أداة غير موجودة",
+    },
+    TOOL_ARGS_INVALID: {
+        fault: "BBX-4302",
+        en: "Tool arguments its schema refuses",
+        ar: "وسائط أداة يرفضها مخططها",
+    },
+    FABRICATED_VALUE: {
+        fault: "BBX-4303",
+        en: "A value the agent never saw",
+        ar: "قيمة لم يطّلع عليها الوكيل",
+    },
+    SUCCESS_AFTER_ERROR: {
+        fault: "BBX-4304",
+        en: "Success claimed right after an error",
+        ar: "نجاح مُعلن بعد خطأ مباشرة",
+    },
+    PHANTOM_RESULT: {
+        fault: "BBX-4305",
+        en: "A result quoted from a tool never called",
+        ar: "نتيجة منسوبة إلى أداة لم تُستدعَ",
+    },
+    UNGROUNDED_CLAIM: {
+        fault: "BBX-4401",
+        en: "A fact in an answer nothing supports",
+        ar: "معلومة في إجابة لا يدعمها شيء",
+    },
+    CONTRADICTED_CLAIM: {
+        fault: "BBX-4402",
+        en: "A fact in an answer the evidence contradicts",
+        ar: "معلومة في إجابة يناقضها الدليل",
+    },
+    JUDGE_FAILED: {
+        fault: "BBX-4501",
+        en: "A judge's rubric step failed",
+        ar: "خطوة من معايير الحكم لم تتحقق",
+    },
     CLAIM_UNVERIFIED: {
         fault: "BBX-4202",
         en: "Completion claim can't be verified",
@@ -117,6 +177,41 @@ export const FAULTS = {
         en: "Tool use against policy",
         ar: "استخدام أداة مخالف للسياسة",
     },
+    WALL_CROSSED: {
+        fault: "BBX-5104",
+        en: "An answer crossed a regulator's wall",
+        ar: "تجاوزت إجابة حدود جهة رقابية",
+    },
+    UNSCREENED_COUNTERPARTY: {
+        fault: "BBX-9401",
+        en: "A payment to an unscreened counterparty",
+        ar: "دفعة إلى طرف لم يُفحص",
+    },
+    SCREENING_HIT_PAID: {
+        fault: "BBX-9402",
+        en: "A flagged counterparty was paid",
+        ar: "دُفع لطرف عليه إنذار في الفحص",
+    },
+    FTA_NO_HANDOFF: {
+        fault: "BBX-9403",
+        en: "A tax filing never reached a Tax Agent",
+        ar: "لم يصل إقرار ضريبي إلى وكيل ضريبي",
+    },
+    BREAK_GLASS: {
+        fault: "BBX-9501",
+        en: "Emergency access to a record (break-glass)",
+        ar: "وصول طارئ إلى سجل (كسر الزجاج)",
+    },
+    HEALTH_SIGNATURE_INVALID: {
+        fault: "BBX-9502",
+        en: "A clinician signature doesn't check",
+        ar: "توقيع طبيب لا يصح",
+    },
+    UNCONFIRMED_RECOMMENDATION: {
+        fault: "BBX-9503",
+        en: "No clinician confirmed a recommendation",
+        ar: "لم يؤكد أي طبيب توصية",
+    },
     POLICY_AUDIT: {
         fault: "BBX-5103",
         en: "An audit-only policy rule would have acted",
@@ -132,11 +227,21 @@ export const FAULTS = {
         en: "The session token was sent onward",
         ar: "أُرسل رمز الجلسة إلى جهة أخرى",
     },
+    TOOL_CHANGED: {
+        fault: "BBX-7402",
+        en: "A tool's definition changed mid-session",
+        ar: "تغيّر تعريف أداة أثناء الجلسة",
+    },
     REVOKED_MEMORY_READ: {
         fault: "BBX-7101",
         en: "A revoked memory was used",
         ar: "استُخدمت ذاكرة ملغاة",
     },
+    MEMORY_CHAIN_BROKEN: {
+        fault: "BBX-7102",
+        en: "A memory entry was changed or is out of order",
+        ar: "عُدّل إدخال ذاكرة أو جاء خارج الترتيب",
+    },
     TOOL_OUTPUT_MISMATCH: {
         fault: "BBX-7201",
         en: "Tool output doesn't match a re-run",
@@ -188,6 +293,11 @@ export const FAULTS = {
         en: "An action waits for a second person",
         ar: "إجراء بانتظار شخص ثانٍ",
     },
+    APPROVAL_ARGS_CHANGED: {
+        fault: "BBX-8404",
+        en: "An approved tool ran with other arguments",
+        ar: "شُغّلت أداة معتمدة بمعطيات أخرى",
+    },
     PREFLIGHT_DEGRADED: {
         fault: "BBX-8501",
         en: "Started with equipment missing",
@@ -238,6 +348,11 @@ export const FAULTS = {
         en: "A tool's signature doesn't verify",
         ar: "توقيع الأداة غير صالح",
     },
+    UNPROVEN_SIDE_EFFECT: {
+        fault: "BBX-9203",
+        en: "A change the tool didn't prove",
+        ar: "تغيير لم تُثبته الأداة",
+    },
     EGRESS_OPEN: {
         fault: "BBX-9301",
         en: "The agent can reach the internet around the gateway",