@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/analysis/detectors.js

@@ -0,0 +1,339 @@
+// Detectors (spec/findings.md §4): deterministic rules over the gateway's record, so they work for
+// any agent, instrumented or not. Mirrors sdks/python/src/zanii_blackbox/analysis/detectors.py.
+import { createHash } from "node:crypto";
+import { priceCall, priceFor, promptTokens, tokensOf } from "../cost/index.js";
+import { callsOf } from "../reconcile/record.js";
+import { canonical, isObj } from "../reconcile/shared.js";
+const VOLATILE = new Set([
+    "timestamp",
+    "ts",
+    "time",
+    "date",
+    "request_id",
+    "requestId",
+    "nonce",
+    "uuid",
+    "trace_id",
+]);
+const WINDOW = 20;
+function normalise(value) {
+    if (Array.isArray(value))
+        return value.map(normalise);
+    if (isObj(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            if (!VOLATILE.has(k))
+                out[k] = normalise(v);
+        return out;
+    }
+    return typeof value === "string" ? value.replaceAll("\\", "/") : value;
+}
+/** T1.4: equivalent arguments give the same fingerprint (volatile keys dropped, paths normalised). */
+export function fingerprint(args) {
+    return createHash("sha256")
+        .update(canonical(normalise(args ?? null)))
+        .digest("hex")
+        .slice(0, 16);
+}
+export function toolCallsOf(calls) {
+    const out = [];
+    for (const c of [...calls].sort((a, b) => a.endSeq - b.endSeq)) {
+        for (const [, b] of [...c.blocks].sort(([x], [y]) => x - y))
+            if (b.type === "tool_use" && typeof b.name === "string")
+                out.push({
+                    seq: c.endSeq,
+                    tool: b.name,
+                    fp: fingerprint(b.input ?? {}),
+                    args: b.input ?? {},
+                    ...(typeof b.id === "string" ? { id: b.id } : {}),
+                });
+        for (const item of c.items) {
+            if (item.type === "function_call" && typeof item.name === "string") {
+                let args = item.arguments;
+                if (typeof args === "string")
+                    try {
+                        args = JSON.parse(args);
+                    }
+                    catch { }
+                out.push({
+                    seq: c.endSeq,
+                    tool: item.name,
+                    fp: fingerprint(args),
+                    args,
+                    ...(typeof item.call_id === "string" ? { id: item.call_id } : {}),
+                });
+            }
+            else if (item.type === "custom_tool_call" && typeof item.name === "string")
+                out.push({
+                    seq: c.endSeq,
+                    tool: item.name,
+                    fp: fingerprint(item.input),
+                    args: item.input,
+                    ...(typeof item.call_id === "string" ? { id: item.call_id } : {}),
+                });
+        }
+    }
+    return out;
+}
+/**
+ * Tool results the agent sent back: Anthropic tool_result blocks and Chat Completions `role: "tool"`
+ * messages (the first carrying each id), MCP tool.result. Chat Completions has no error flag, so its
+ * results count as not errors.
+ */
+export function toolResultsOf(calls, lines) {
+    const out = [];
+    const seen = new Set();
+    for (const c of calls) {
+        const messages = Array.isArray(c.request?.messages) ? c.request.messages.filter(isObj) : [];
+        for (const m of messages) {
+            if (m.role === "tool" && typeof m.tool_call_id === "string") {
+                if (!seen.has(m.tool_call_id)) {
+                    seen.add(m.tool_call_id);
+                    out.push({ seq: c.requestSeq, error: false, id: m.tool_call_id });
+                }
+                continue;
+            }
+            if (!Array.isArray(m.content))
+                continue;
+            for (const b of m.content.filter(isObj))
+                if (b.type === "tool_result" &&
+                    typeof b.tool_use_id === "string" &&
+                    !seen.has(b.tool_use_id)) {
+                    seen.add(b.tool_use_id);
+                    out.push({ seq: c.requestSeq, error: b.is_error === true, id: b.tool_use_id });
+                }
+        }
+    }
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind === "tool.result" && typeof e.meta.is_error === "boolean")
+            out.push({ seq: e.seq, error: e.meta.is_error });
+    }
+    return out.sort((a, b) => a.seq - b.seq);
+}
+function segments(request) {
+    const out = [
+        ["system", canonical(request.system ?? request.instructions ?? null)],
+        ["tools", canonical(request.tools ?? null)],
+    ];
+    const messages = Array.isArray(request.messages)
+        ? request.messages
+        : Array.isArray(request.input)
+            ? request.input
+            : [];
+    for (const [i, m] of messages.entries())
+        out.push([`message:${i}`, canonical(m)]);
+    return out;
+}
+/** T1.5: the first prefix segment that differs; "none" when the earlier request is a prefix of the later. */
+function changedSegment(before, after) {
+    const a = segments(before);
+    const b = segments(after);
+    for (let i = 0; i < Math.min(a.length, b.length); i++)
+        if (a[i]?.[1] !== b[i]?.[1])
+            return b[i][0];
+    return b.length >= a.length ? "none" : a[b.length][0];
+}
+const f = (code, severity, ref, detail) => ({ code, source: "detectors", severity, ref, detail });
+export function detectors(lines, options) {
+    const calls = callsOf(lines, options.bodies);
+    const byEnd = [...calls].sort((a, b) => a.endSeq - b.endSeq);
+    const tools = toolCallsOf(calls);
+    const results = toolResultsOf(calls, lines);
+    const keys = tools.map((t) => `${t.tool}\n${t.fp}`);
+    const first = lines[0] ? JSON.parse(lines[0]) : null;
+    const open = first?.kind === "session.open" ? first.meta : {};
+    const out = [];
+    // D1: the 3rd / 5th occurrence of the same call within the last 20 tool calls.
+    const d1 = new Set();
+    const repeat = [];
+    keys.forEach((key, i) => {
+        const count = keys.slice(Math.max(0, i - WINDOW + 1), i + 1).filter((k) => k === key).length;
+        repeat.push(count >= 2);
+        for (const [at, severity] of [
+            [3, "caution"],
+            [5, "warning"],
+        ])
+            if (count === at && !d1.has(`${key}\n${at}`)) {
+                d1.add(`${key}\n${at}`);
+                const t = tools[i];
+                out.push(f("D1_REPEAT_CALL", severity, { tool: t.tool, fingerprint: t.fp, count: at }, `The same ${t.tool} call ${at} times in the last ${WINDOW} tool calls.`));
+            }
+    });
+    // D2: an n-gram (n = 2..4) repeated 3 times back to back, not one repeated call.
+    const inLoop = new Array(keys.length).fill(false);
+    for (let i = 0; i < keys.length;) {
+        let found = 0;
+        for (let n = 2; n <= 4 && !found; n++) {
+            if (i + 3 * n > keys.length)
+                break;
+            const gram = keys.slice(i, i + n);
+            if (new Set(gram).size === 1)
+                continue;
+            const same = (at) => keys.slice(at, at + n).every((k, j) => k === gram[j]);
+            if (same(i + n) && same(i + 2 * n))
+                found = n;
+        }
+        if (found) {
+            out.push(f("D2_ACTION_LOOP", "caution", { n: found, first_seq: tools[i].seq }, `A sequence of ${found} tool calls repeated 3 times in a row.`));
+            for (let j = i; j < i + 3 * found; j++)
+                inLoop[j] = true;
+            i += 3 * found;
+        }
+        else
+            i++;
+    }
+    // D3: 3+ error results in a row, once per streak.
+    let streak = 0;
+    let streakStart = 0;
+    for (const r of results) {
+        if (!r.error) {
+            streak = 0;
+            continue;
+        }
+        if (streak === 0)
+            streakStart = r.seq;
+        streak++;
+        if (streak === 3)
+            out.push(f("D3_ERROR_STREAK", "caution", { first_seq: streakStart }, "Three tool results in a row were errors."));
+    }
+    // D4: input grew on each of the last 5 calls and exceeds 60% of the context window.
+    const priced = byEnd.filter((c) => c.usage);
+    const inputs = priced.map((c) => {
+        return promptTokens(tokensOf(c.usage));
+    });
+    for (let j = 5; j < priced.length; j++) {
+        const c = priced[j];
+        const window = c.model && options.prices
+            ? priceFor(c.model, options.prices.table, c.provider)?.price.context_window
+            : undefined;
+        const rising = inputs
+            .slice(j - 5, j + 1)
+            .every((v, k, a) => k === 0 || v > a[k - 1]);
+        if (window && rising && inputs[j] * 10 > window * 6) {
+            out.push(f("D4_CONTEXT_BLOAT", "caution", { first_seq: c.endSeq }, "The context has grown on every call and is past 60% of the model's window."));
+            break;
+        }
+    }
+    // D5: cached input drops to zero; which prefix segment changed (T1.5).
+    for (let j = 1; j < priced.length; j++) {
+        const prev = priced[j - 1];
+        const cur = priced[j];
+        if (prev.model !== cur.model || !prev.request || !cur.request)
+            continue;
+        if (tokensOf(prev.usage).cache_read > 0 && tokensOf(cur.usage).cache_read === 0) {
+            const changed = changedSegment(prev.request, cur.request);
+            out.push(f("D5_CACHE_BREAK", "advisory", { seq: cur.endSeq, changed }, changed === "none"
+                ? "The prompt cache expired: nothing in the prefix changed."
+                : `The prompt cache broke: ${changed} changed.`));
+        }
+    }
+    // MODEL_DEPRECATED: a call to a model the price table marks deprecated (spec/cost.md §1), once
+    // per model, in the order they're first called.
+    if (options.prices) {
+        const seen = new Set();
+        for (const c of byEnd) {
+            if (!c.model || seen.has(c.model))
+                continue;
+            const match = priceFor(c.model, options.prices.table, c.provider);
+            if (match?.price.status !== "deprecated")
+                continue;
+            seen.add(c.model);
+            out.push(f("MODEL_DEPRECATED", "advisory", { seq: c.endSeq, model: c.model }, `${c.model} is deprecated: plan the move to its successor before the provider retires it.`));
+        }
+    }
+    // A person may raise a limit mid-session (spec/approvals.md §4): the latest grant wins.
+    const granted = grantedLimits(lines);
+    // D6: running cost crosses 80% / 100% of the budget (the session's own, else the default).
+    const budget = granted.budget ??
+        (typeof open.budget_micro_usd === "number" && open.budget_micro_usd > 0
+            ? open.budget_micro_usd
+            : options.budgetMicroUsd);
+    if (options.prices && budget && budget > 0) {
+        let micro = 0;
+        const crossed = new Set();
+        for (const c of priced) {
+            // the cost report's own pricing (spec/cost.md): tiers, provider scope, reported costs
+            const priced = priceCall({ ...c, usage: c.usage }, options.prices.table);
+            if (priced.micro_usd === null)
+                continue;
+            micro += priced.micro_usd;
+            for (const [threshold, severity] of [
+                [80, "caution"],
+                [100, "warning"],
+            ])
+                if (!crossed.has(threshold) && micro * 100 >= threshold * budget) {
+                    crossed.add(threshold);
+                    out.push(f("D6_SPEND", severity, 
+                    // a raised budget is a new one: its crossings are new findings
+                    granted.budget !== undefined
+                        ? { threshold, budget_micro_usd: budget }
+                        : { threshold }, `The session has spent ${threshold}% of its budget.`));
+                }
+        }
+    }
+    // CALL_LIMIT: more model calls than the session's max_llm_calls (spec/control.md §2).
+    const limit = granted.calls ?? open.max_llm_calls;
+    if (typeof limit === "number" &&
+        Number.isSafeInteger(limit) &&
+        limit >= 0 &&
+        calls.length > limit)
+        out.push(f("CALL_LIMIT", "warning", { limit }, `The session made more than its ${limit} allowed model calls.`));
+    // RETRY_STORM: 3+ responses in a row with 429 or ≥ 500.
+    let storm = 0;
+    let stormStart = 0;
+    for (const c of byEnd) {
+        if (c.status === null)
+            continue;
+        if (c.status === 429 || c.status >= 500) {
+            if (storm === 0)
+                stormStart = c.endSeq;
+            storm++;
+            if (storm === 3)
+                out.push(f("RETRY_STORM", "caution", { first_seq: stormStart }, "Three provider errors (429 / 5xx) in a row."));
+        }
+        else
+            storm = 0;
+    }
+    // DANGLING_TOOL_CALL: a tool_use whose result never came back (judged at close).
+    if (options.now === Number.POSITIVE_INFINITY) {
+        const answered = new Set(results.flatMap((r) => (r.id ? [r.id] : [])));
+        for (const c of byEnd)
+            for (const [, b] of [...c.blocks].sort(([x], [y]) => x - y))
+                if (b.type === "tool_use" && typeof b.id === "string" && !answered.has(b.id))
+                    out.push(f("DANGLING_TOOL_CALL", "advisory", { tool_use_id: b.id }, "A tool call's result never reached the model; the tool may have run."));
+    }
+    // LOST_COMMS: the session went silent (squawk 7600).
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind === "session.lost_contact")
+            out.push(f("LOST_COMMS", "warning", { seq: e.seq }, "The agent stopped sending heartbeats: lost contact."));
+    }
+    // C_CUSUM over tool-call steps.
+    const errorIds = new Set(results.filter((r) => r.error && r.id).map((r) => r.id));
+    let s = 0;
+    for (let i = 0; i < tools.length; i++) {
+        const t = tools[i];
+        const score = (repeat[i] ? 1 : 0) + (inLoop[i] ? 1 : 0) + (t.id && errorIds.has(t.id) ? 1 : 0);
+        s = Math.max(0, s + score - 0.5);
+        if (s > 4) {
+            out.push(f("C_CUSUM", "caution", { seq: t.seq }, "The run has been going wrong step after step (repeats, loops, errors)."));
+            break;
+        }
+    }
+    return out;
+}
+/** The latest budget and call limit a person granted (spec/approvals.md §4), if any. */
+export function grantedLimits(lines) {
+    const out = {};
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind !== "control" || e.meta.action !== "permission")
+            continue;
+        if (Number.isSafeInteger(e.meta.budget_micro_usd))
+            out.budget = e.meta.budget_micro_usd;
+        if (Number.isSafeInteger(e.meta.max_llm_calls))
+            out.calls = e.meta.max_llm_calls;
+    }
+    return out;
+}

package/dist/analysis/faults.d.ts

@@ -0,0 +1,9 @@
+export interface Fault {
+    fault: string;
+    squawk?: string;
+    en: string;
+    ar: string;
+}
+export declare const FAULTS: Readonly<Record<string, Fault>>;
+/** The fault for a finding code; unknown codes get a generic entry, never an exception. */
+export declare function faultOf(code: string): Fault;

package/dist/analysis/faults.js

@@ -0,0 +1,250 @@
+// The fault catalog (spec/control.md §1), embedded from spec/faults/v1.json. Mirrors analysis/faults.py.
+// Generated from the spec file; faults.test.ts checks they match exactly. Edit the spec, then regenerate.
+export const FAULTS = {
+    BYPASS: {
+        fault: "BBX-7500",
+        squawk: "HIJACK",
+        en: "Model call around the gateway",
+        ar: "استدعاء نموذج خارج البوابة",
+    },
+    LOST_COMMS: {
+        fault: "BBX-7600",
+        squawk: "LOST_COMMS",
+        en: "Lost contact with the agent",
+        ar: "انقطاع الاتصال بالوكيل",
+    },
+    EMERGENCY: { fault: "BBX-7700", squawk: "EMERGENCY", en: "Emergency stop", ar: "إيقاف طارئ" },
+    MISSING_LOCAL: { fault: "BBX-1101", en: "Deleted from the agent's log", ar: "حُذف من سجل الوكيل" },
+    ALTERED: { fault: "BBX-1102", en: "Altered in the agent's log", ar: "عُدّل في سجل الوكيل" },
+    EXTRA_LOCAL: { fault: "BBX-1103", en: "Not seen by the gateway", ar: "لم تشاهده البوابة" },
+    LOCAL_GAP: { fault: "BBX-1104", en: "Gap in the agent's log", ar: "فجوة في سجل الوكيل" },
+    RECEIPT_MISSING: {
+        fault: "BBX-1105",
+        en: "Workspace receipt missing",
+        ar: "إيصال مساحة العمل مفقود",
+    },
+    UNATTRIBUTED_CHANGE: {
+        fault: "BBX-1106",
+        en: "File change outside any tool call",
+        ar: "تغيير في الملفات خارج أي استدعاء أداة",
+    },
+    SDK_SILENT: {
+        fault: "BBX-1201",
+        en: "The SDK stopped reporting",
+        ar: "توقّفت حزمة SDK عن الإبلاغ",
+    },
+    D1_REPEAT_CALL: { fault: "BBX-2101", en: "Repeated tool call", ar: "تكرار استدعاء الأداة" },
+    D2_ACTION_LOOP: { fault: "BBX-2102", en: "Action loop", ar: "حلقة إجراءات متكررة" },
+    D3_ERROR_STREAK: { fault: "BBX-2103", en: "Error streak", ar: "سلسلة أخطاء متتالية" },
+    D4_CONTEXT_BLOAT: { fault: "BBX-2104", en: "Context bloat", ar: "تضخّم السياق" },
+    D5_CACHE_BREAK: {
+        fault: "BBX-2105",
+        en: "Prompt cache break",
+        ar: "انقطاع ذاكرة التخزين المؤقت للموجّه",
+    },
+    RETRY_STORM: { fault: "BBX-2106", en: "Retry storm", ar: "عاصفة إعادة المحاولة" },
+    DANGLING_TOOL_CALL: {
+        fault: "BBX-2107",
+        en: "Tool result never returned",
+        ar: "نتيجة أداة لم تُعَد إلى النموذج",
+    },
+    C_CUSUM: {
+        fault: "BBX-2108",
+        en: "Run degrading step after step",
+        ar: "تدهور التشغيل خطوة بعد خطوة",
+    },
+    ORPHANED_TOOL_CALL: {
+        fault: "BBX-2109",
+        en: "A tool call never finished",
+        ar: "استدعاء أداة لم يكتمل",
+    },
+    EXIT_DURABILITY: {
+        fault: "BBX-2202",
+        en: "Side effects in a run that saves only on exit",
+        ar: "آثار جانبية في تشغيل لا يحفظ حالته إلا عند الخروج",
+    },
+    CHECKPOINT_REPLAY: {
+        fault: "BBX-2201",
+        en: "Side effect repeated on resume",
+        ar: "تكرار أثر جانبي عند الاستئناف",
+    },
+    D6_SPEND: { fault: "BBX-3101", en: "Spend limit", ar: "حدّ الإنفاق" },
+    CALL_LIMIT: {
+        fault: "BBX-3102",
+        en: "Model-call limit reached",
+        ar: "بلوغ حدّ استدعاءات النموذج",
+    },
+    MODEL_DEPRECATED: { fault: "BBX-3103", en: "Deprecated model", ar: "نموذج متوقّف الدعم" },
+    PLAN_DEVIATION: {
+        fault: "BBX-4101",
+        en: "Deviation from the flight plan",
+        ar: "انحراف عن خطة الرحلة",
+    },
+    PLAN_VIOLATION: { fault: "BBX-4102", en: "Flight plan limit broken", ar: "خرق حدود خطة الرحلة" },
+    PLAN_INVALID: {
+        fault: "BBX-4104",
+        en: "Flight plan filed by the SDK is invalid",
+        ar: "خطة رحلة غير صالحة مرسلة من الـ SDK",
+    },
+    STERILE_VIOLATION: {
+        fault: "BBX-4103",
+        en: "A tool outside a sterile phase's allowed list",
+        ar: "أداة خارج القائمة المسموحة في مرحلة حرجة",
+    },
+    FALSE_CLAIM: { fault: "BBX-4201", en: "False completion claim", ar: "ادعاء إنجاز غير صحيح" },
+    FALSE_SUCCESS: {
+        fault: "BBX-4203",
+        en: "A success the record contradicts",
+        ar: "نجاح مُعلن يناقضه السجل",
+    },
+    VERIFY_REGRESSION: {
+        fault: "BBX-4204",
+        en: "A check that passed now fails",
+        ar: "فحص نجح سابقًا ثم فشل",
+    },
+    CLAIM_UNVERIFIED: {
+        fault: "BBX-4202",
+        en: "Completion claim can't be verified",
+        ar: "تعذّر التحقق من ادعاء الإنجاز",
+    },
+    POLICY_DENIED: {
+        fault: "BBX-5101",
+        en: "Tool call refused by policy",
+        ar: "رُفض استدعاء الأداة وفق السياسة",
+    },
+    POLICY_VIOLATION: {
+        fault: "BBX-5102",
+        en: "Tool use against policy",
+        ar: "استخدام أداة مخالف للسياسة",
+    },
+    POLICY_AUDIT: {
+        fault: "BBX-5103",
+        en: "An audit-only policy rule would have acted",
+        ar: "كانت قاعدة سياسة قيد التدقيق سترفض استدعاء الأداة",
+    },
+    NEAR_MISS: {
+        fault: "BBX-6101",
+        en: "Near miss reported by the agent",
+        ar: "حادثة وشيكة أبلغ عنها الوكيل",
+    },
+    TOKEN_MISUSE: {
+        fault: "BBX-7401",
+        en: "The session token was sent onward",
+        ar: "أُرسل رمز الجلسة إلى جهة أخرى",
+    },
+    REVOKED_MEMORY_READ: {
+        fault: "BBX-7101",
+        en: "A revoked memory was used",
+        ar: "استُخدمت ذاكرة ملغاة",
+    },
+    TOOL_OUTPUT_MISMATCH: {
+        fault: "BBX-7201",
+        en: "Tool output doesn't match a re-run",
+        ar: "مخرجات الأداة لا تطابق إعادة التشغيل",
+    },
+    ABNORMAL_RUN: {
+        fault: "BBX-7302",
+        en: "A run unlike this agent's successful runs",
+        ar: "مسار تشغيل غير مألوف لهذا الوكيل",
+    },
+    PRECOG_RISK: {
+        fault: "BBX-7301",
+        en: "Likely to fail, predicted early",
+        ar: "من المرجح أن تفشل، بتنبؤ مبكر",
+    },
+    AUTOMATION_SURPRISE: {
+        fault: "BBX-8101",
+        en: "The agent acted after it lost the controls",
+        ar: "تصرّف الوكيل بعد أن فقد السيطرة",
+    },
+    TAKEOVER: {
+        fault: "BBX-8102",
+        en: "A person took the controls",
+        ar: "تولّى شخص القيادة",
+    },
+    PAUSED: { fault: "BBX-8103", en: "Paused by the operator", ar: "إيقاف مؤقت من المشغّل" },
+    DIRECTIVE: {
+        fault: "BBX-8201",
+        en: "An airworthiness directive applies to this fleet",
+        ar: "ينطبق توجيه صلاحية على هذا الأسطول",
+    },
+    UNDO_FAILED: {
+        fault: "BBX-8301",
+        en: "An undo didn't go through",
+        ar: "لم ينجح التراجع",
+    },
+    APPROVAL_REJECTED: {
+        fault: "BBX-8401",
+        en: "A second person refused the action",
+        ar: "رفض شخص ثانٍ الإجراء",
+    },
+    APPROVAL_TIMEOUT: {
+        fault: "BBX-8402",
+        en: "No second person confirmed in time",
+        ar: "لم يؤكد شخص ثانٍ في الوقت المحدد",
+    },
+    APPROVAL_PENDING: {
+        fault: "BBX-8403",
+        en: "An action waits for a second person",
+        ar: "إجراء بانتظار شخص ثانٍ",
+    },
+    PREFLIGHT_DEGRADED: {
+        fault: "BBX-8501",
+        en: "Started with equipment missing",
+        ar: "بدأ مع نقص في المعدات",
+    },
+    DUTY_LIMIT: {
+        fault: "BBX-8601",
+        en: "Duty limit reached: hand over",
+        ar: "بلغ حد العمل: سلّم المهمة",
+    },
+    TYPE_UNRATED: {
+        fault: "BBX-8801",
+        en: "Flying a model it isn't rated on",
+        ar: "يعمل على نموذج غير مؤهل له",
+    },
+    DATA_LEFT_REGION: {
+        fault: "BBX-9101",
+        en: "Personal data sent outside the data region",
+        ar: "بيانات شخصية أُرسلت خارج منطقة البيانات",
+    },
+    DATA_REGION_UNKNOWN: {
+        fault: "BBX-9102",
+        en: "Personal data sent to a model of unknown region",
+        ar: "بيانات شخصية أُرسلت إلى نموذج منطقته غير معروفة",
+    },
+    DATA_TO_UNAPPROVED_DESTINATION: {
+        fault: "BBX-9103",
+        en: "Data sent to a destination its rules don't allow",
+        ar: "بيانات أُرسلت إلى وجهة لا تسمح بها قواعدها",
+    },
+    DATA_CANARY_TRIPPED: {
+        fault: "BBX-9104",
+        en: "A canary value left the gateway",
+        ar: "قيمة إنذار خرجت من البوابة",
+    },
+    CONSENT_WITHDRAWN_USE: {
+        fault: "BBX-9105",
+        en: "Data used after consent was withdrawn",
+        ar: "استُخدمت بيانات بعد سحب الموافقة",
+    },
+    UNEVIDENCED_SIDE_EFFECT: {
+        fault: "BBX-9201",
+        en: "A change the touched system gave no proof of",
+        ar: "تغيير لم يقدّم النظام المعني دليلاً عليه",
+    },
+    TOOL_WITNESS_INVALID: {
+        fault: "BBX-9202",
+        en: "A tool's signature doesn't verify",
+        ar: "توقيع الأداة غير صالح",
+    },
+    EGRESS_OPEN: {
+        fault: "BBX-9301",
+        en: "The agent can reach the internet around the gateway",
+        ar: "يستطيع الوكيل الوصول إلى الإنترنت متجاوزاً البوابة",
+    },
+};
+/** The fault for a finding code; unknown codes get a generic entry, never an exception. */
+export function faultOf(code) {
+    return FAULTS[code] ?? { fault: "BBX-0000", en: code, ar: code };
+}

package/dist/analysis/index.d.ts

@@ -0,0 +1,68 @@
+import type { LoadedPrices } from "../cost/index.ts";
+import { type DutyLimits } from "../duty/index.ts";
+import { type CompiledPolicy } from "../policy/index.ts";
+import { type PrecogModel } from "../precog/index.ts";
+import type { Envelope, Json } from "../verify/index.ts";
+export { type ClaimVerdict, type CriterionResult, checkFlightPlan, type Landing, landing, } from "./landing.ts";
+export { OUTCOMES, type Outcome, type OutcomeRollup, rollup, type WasteReason, type WasteReport, waste, } from "./waste.ts";
+export type Severity = "advisory" | "caution" | "warning";
+export interface Finding {
+    code: string;
+    source: string;
+    severity: Severity;
+    ref: {
+        [key: string]: string | number | boolean;
+    };
+    detail?: string;
+}
+export interface AnalyzeOptions {
+    /** Body bytes by hash (SDK events carry their ids in the body; requests and responses are bodies). */
+    bodies: (hash: string) => Uint8Array | undefined;
+    /** For the detectors: context windows (D4) and cost (D6). */
+    prices?: LoadedPrices;
+    budgetMicroUsd?: number;
+    /** spec/duty.md §1: the server's default duty limits (a flight plan's win). */
+    duty?: DutyLimits;
+    /** spec/policy.md: the compiled tool policy, for POLICY_DENIED / POLICY_VIOLATION. */
+    policy?: CompiledPolicy;
+    /** spec/precog.md §3: the early-failure model, for PRECOG_RISK (needs `prices`). */
+    precog?: PrecogModel;
+    /** Epoch ms; +Infinity = judge everything (a session being closed). Default: now. */
+    now?: number;
+    graceMs?: number;
+}
+export interface Ev extends Envelope {
+    /** The parsed body, for kinds whose body is JSON (sdk.event). */
+    data?: {
+        [key: string]: Json;
+    };
+}
+/** Parses the lines once, attaching SDK event bodies. */
+export declare function eventsOf(lines: readonly string[], bodies: AnalyzeOptions["bodies"]): Ev[];
+/** Every analysis, in spec order. */
+export declare function analyze(lines: readonly string[], options: AnalyzeOptions): Finding[];
+/** spec/attestation.md §3: a re-run that printed something else than the model was given. */
+export declare function attestationFindings(events: readonly Ev[]): Finding[];
+/** spec/fleet.md §3: the agent's own near-miss reports. */
+export declare function nearMisses(events: readonly Ev[]): Finding[];
+/** A stable key for dedup: code + ref with sorted keys. */
+export declare function findingKey(f: {
+    code: string;
+    ref: {
+        [key: string]: unknown;
+    };
+}): string;
+export declare function dualWitness(events: Ev[], now: number, graceMs: number): Finding[];
+export declare function checkpointReplay(events: Ev[]): Finding[];
+/** N4 (idea R9): a tool call with no result, judged at close (`now` is +Infinity): a crash
+ * mid-call. */
+export declare function orphanedToolCalls(events: Ev[], now: number): Finding[];
+/** N4 (idea R5): a LangGraph run in `exit` durability that ran tools. Once per session. */
+export declare function exitDurability(events: Ev[]): Finding[];
+/** N6 (idea S3): the gateway refused a request that carried the session's own token. */
+export declare function tokenMisuse(events: Ev[]): Finding[];
+/** Stage 2 R3: a `verify` check that passed, then failed later in the run. */
+export declare function verifyRegression(events: Ev[]): Finding[];
+/** Stage 2 R4, judged at close: a run labelled (or claimed) a success that its own record contradicts:
+ * a check's last result failed, or the last tool call failed with nothing succeeding after it. */
+export declare function falseSuccess(events: Ev[], now: number): Finding[];