@zanii/blackbox 0.3.0 → 0.5.0

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",

package/dist/analysis/grounding.d.ts

@@ -0,0 +1,122 @@
+import { type Bodies, type Call } from "../reconcile/record.ts";
+import { canonicalNumber } from "./hallucination.ts";
+import { type ReferencePack } from "./reference.ts";
+export { canonicalNumber };
+import type { Finding } from "./index.ts";
+export interface Fact {
+    kind: "money" | "percent" | "quantity" | "date" | string;
+    /** Canonical: a decimal (`1250.5`) for money and percentages, normalised text otherwise. */
+    value: string;
+    at: number;
+    end: number;
+    currency?: string;
+}
+/** The facts an answer states: money, percentages, quantities, ISO dates, then identifiers (as H1's). */
+export declare function factsIn(text: string): Fact[];
+/** What the agent was given, to check facts against: the record lines it came from (§11 points at
+ * them), each normalised, with its numbers. */
+export declare class Evidence {
+    /** As given, for a grounding service (§9.1). */
+    readonly raw: string;
+    readonly numbers: Set<string>;
+    private readonly pieces;
+    private sums;
+    constructor(raw: string, pieces?: ReadonlyArray<{
+        seq: number;
+        text: string;
+    }>);
+    /** Whether the evidence holds the fact (§9). */
+    holds(f: Fact): boolean;
+    /**
+     * The seqs of the lines that hold a fact, or null. Money, percentages and quantities: the same
+     * number, the same in minor units, a percentage as a fraction, or (money) the sum of two of the
+     * evidence's numbers. Dates and identifiers: the normalised text.
+     */
+    support(f: Fact): number[] | null;
+    private pairSums;
+}
+/** The final answers on a record, each with the evidence it should rest on. */
+export declare function answersOf(lines: readonly string[], bodies: Bodies): Array<{
+    seq: number;
+    text: string;
+    evidence: Evidence;
+    call: Call;
+}>;
+/** What a grounding service is sent for one answer: the text, the exact tier's facts, and the
+ * context it should rest on (the newest 200,000 characters of it). */
+export declare function groundingRequest(sessionId: string, answer: {
+    seq: number;
+    text: string;
+    evidence: Evidence;
+}, packs?: readonly ReferencePack[]): {
+    session_id: string;
+    answer_seq: number;
+    answer: string;
+    facts: {
+        kind: string;
+        value: string;
+    }[];
+    context: string;
+    reference?: {
+        pack: string;
+        id: string;
+        text: string;
+        source?: string;
+    }[];
+};
+export interface GroundedClaim {
+    text: string;
+    status: "grounded" | "ungrounded" | "contradicted" | "no_fact";
+    score?: number;
+}
+/** A grounding service's answer, checked: `{claims, model?, version?}`, or null (an outage). */
+export declare function parseGroundingAnswer(v: unknown): {
+    claims: GroundedClaim[];
+    model?: string;
+    version?: string;
+} | null;
+/** §9.1: UNGROUNDED_CLAIM and CONTRADICTED_CLAIM from the verdicts a grounding service gave,
+ * recorded as `control {action: "grounding", via: "model"}` with the claims as the body. */
+export declare function modelGroundingFindings(lines: readonly string[], bodies: Bodies): Finding[];
+/** spec/findings.md §9-§10: for each fact in a final answer, CONTRADICTED_CLAIM when a reference
+ * pack says otherwise, else UNGROUNDED_CLAIM when nothing the agent was given holds it (at most 10
+ * per answer); then the grounding service's verdicts (§9.1). */
+export declare function groundingFindings(lines: readonly string[], bodies: Bodies, packs?: readonly ReferencePack[]): Finding[];
+/** What a judge is sent for one answer: the answer and the trajectory before it (its newest 100
+ * steps: tools called, whether they failed, earlier answers, the findings so far). */
+export declare function judgeRequest(sessionId: string, answer: {
+    seq: number;
+    text: string;
+}, lines: readonly string[]): {
+    session_id: string;
+    answer_seq: number;
+    answer: string;
+    steps: {
+        [key: string]: string | number | boolean;
+    }[];
+};
+/** A judge's answer, checked: `{steps: [{rubric, pass, reason?}], model?, version?}`, or null. */
+export declare function parseJudgeAnswer(v: unknown): {
+    steps: Array<{
+        rubric: string;
+        pass: boolean;
+        reason?: string;
+    }>;
+    model?: string;
+    version?: string;
+} | null;
+/** §12.1: JUDGE_FAILED for each rubric step a judge failed, from its recorded verdicts. */
+export declare function judgeFindings(lines: readonly string[], bodies: Bodies): Finding[];
+/** spec/findings.md §13: what can hold an answer (BLACKBOX_HOLD_ANSWERS). */
+export declare const HOLD_TRIGGERS: readonly ["contradicted", "money", "ids", "quantity", "percent", "date"];
+/** §13: why an answer should be held before it's delivered: each fact a pack contradicts (with
+ * `contradicted`), and each ungrounded fact whose kind is a trigger (`ids` covers the identifiers).
+ * Empty: deliver it. */
+export declare function answerRisk(answer: {
+    text: string;
+    evidence: Evidence;
+}, packs: readonly ReferencePack[], triggers: readonly string[]): Array<{
+    index: number;
+    kind: string;
+    status: "contradicted" | "ungrounded";
+}>;