@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/client/index.d.ts

@@ -0,0 +1,146 @@
+import { type Bundle, type BundleReport } from "../verify/anchor.ts";
+export interface ClientOptions {
+    url: string;
+    /** The admin key or a tenant's `bbxt_` key. */
+    apiKey: string;
+    /** Per request (default 30 s). */
+    timeoutMs?: number;
+    /** Retries of a 429, a 503 or a network error, with backoff (default 2; 0 = none). Only reads and
+     *  idempotent writes are retried. */
+    retries?: number;
+}
+export interface SessionQuery {
+    limit?: number;
+    /** The previous page's `next`. */
+    before?: string;
+    label?: string;
+    status?: "open" | "closed";
+    /** ISO dates on `created_at`; `to` is exclusive. */
+    from?: string;
+    to?: string;
+}
+export type Json = Record<string, unknown>;
+/**
+ * The gateway answered with an error, or couldn't be reached. `code` is its stable error code
+ * (spec/api.md §3), or `network`, `timeout` or `integrity` from the client itself. `requestId` is
+ * the gateway's `x-request-id`, to find the call in its logs.
+ */
+export declare class BlackboxApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | null;
+    constructor(status: number, code: string, message: string, requestId?: string | null);
+}
+export declare function client(options: ClientOptions): {
+    /** Any JSON read route not covered below, e.g. `get("/v1/fleet/collisions")`. */
+    get: (path: string) => Promise<Json>;
+    version: () => Promise<Json>;
+    /** One page, newest first: `{sessions, next}`; pass `next` back as `before`. */
+    sessions: (q?: SessionQuery) => Promise<{
+        sessions: Json[];
+        next: string | null;
+    }>;
+    /** Every matching session, newest first, page by page. */
+    allSessions(q?: SessionQuery): AsyncGenerator<Json>;
+    session: (id: string) => Promise<Json>;
+    verify: (id: string) => Promise<Json>;
+    state: (id: string) => Promise<Json>;
+    /** The session's events, parsed; with `afterSeq`, only those after it (audit S4). */
+    events(id: string, o?: {
+        afterSeq?: number;
+    }): Promise<Json[]>;
+    /**
+     * Audit K13: the session's events live, as they're recorded (Server-Sent Events), from
+     * `afterSeq`. Ends once the session is closed and everything is sent.
+     */
+    tail(id: string, o?: {
+        afterSeq?: number;
+    }): AsyncGenerator<Json>;
+    /** The audit bundle, typed for verifyBundle (audit K22). */
+    bundle: (id: string) => Promise<Bundle>;
+    /** Audit K22: fetches the bundle and verifies it here, not trusting the gateway's own check. */
+    verifiedBundle(id: string, o?: {
+        proofs?: boolean;
+    }): Promise<{
+        bundle: Bundle;
+        report: BundleReport;
+    }>;
+    summary: (id: string) => Promise<Json>;
+    cost: (id: string) => Promise<Json>;
+    findings: (id: string) => Promise<Json>;
+    landing: (id: string) => Promise<Json>;
+    waste: (id: string) => Promise<Json>;
+    /** Markdown, in English or Arabic. */
+    incident: (id: string, lang?: "en" | "ar") => Promise<string>;
+    fleet: () => Promise<Json>;
+    logbook: (o?: {
+        limit?: number;
+    }) => Promise<Json>;
+    certificate: (label: string) => Promise<Json>;
+    /**
+     * The exact body bytes, or null if unknown or erased. The bytes are checked against their
+     * hash (audit K24): a mismatch throws, code `integrity`.
+     */
+    body(hash: string): Promise<Uint8Array | null>;
+    close: (id: string, o?: {
+        outcome?: "success" | "failure" | "abandoned";
+        note?: string;
+    }) => Promise<Json>;
+    /** PDPL / GDPR erasure of a closed session's content (spec/api.md). Idempotent. */
+    erase: (id: string) => Promise<Json>;
+    /** Unblocks a blocked session (spec/control.md §3). */
+    resume: (id: string, o?: {
+        token?: string;
+        force?: boolean;
+        note?: string;
+    }) => Promise<Json>;
+    /** Stops the session at its next call, resumable without a token (spec/control.md §3). */
+    pause: (id: string, o?: {
+        note?: string;
+    }) => Promise<Json>;
+    /** The emergency stop (squawk 7700, spec/control.md). */
+    emergency: (id: string, o?: {
+        note?: string;
+    }) => Promise<Json>;
+    /** Hands the controls over (spec/authority.md): `human` takes over; `agent`/`supervised` hand back. */
+    authority: (id: string, to: "human" | "agent" | "supervised", o?: {
+        reason?: string;
+    }) => Promise<Json>;
+    /** The pending approvals (spec/approvals.md). */
+    approvals: (id: string) => Promise<Json>;
+    /** Approves or rejects one (never with the session's own token). */
+    decide: (id: string, approvalId: string, decision: "approve" | "reject", o?: {
+        note?: string;
+    }) => Promise<Json>;
+    /** The undo plan (spec/undo.md); with `confirm: true`, runs the gateway's own steps. */
+    undo: (id: string, o?: {
+        confirm?: boolean;
+    }) => Promise<Json>;
+    /** Records a regulator filing (spec/occurrence.md). */
+    file: (id: string, filing: {
+        framework: string;
+        reference: string;
+        channel?: string;
+        filed_at?: string;
+    }) => Promise<Json>;
+    /** A cost reconciliation against the provider's statement (spec/money.md §2). */
+    reconcileCosts: (input: {
+        from: string;
+        to: string;
+        statement: Json;
+        tolerance_ppm?: number;
+        tenant?: string;
+    }) => Promise<Json>;
+    /** Operator only: tenants and their keys (spec/tenancy.md). */
+    tenants: () => Promise<Json>;
+    createTenant: (name: string) => Promise<Json>;
+    updateTenant: (tenantId: string, o: {
+        name?: string;
+        disabled?: boolean;
+    }) => Promise<Json>;
+    createKey: (tenantId: string, o?: {
+        scope?: "full" | "read";
+    }) => Promise<Json>;
+    revokeKey: (tenantId: string, keyId: string) => Promise<Json>;
+};
+export type Client = ReturnType<typeof client>;

package/dist/client/index.js

@@ -0,0 +1,210 @@
+// A client for the gateway's API (audit S3, S4; spec/api.md): reads, and the operator's control
+// and decision calls (audit K6). Unlike a session, it throws: a failed call is the caller's to
+// handle, always as a BlackboxApiError (audit K11). Mirrors sdks/python/src/zanii_blackbox/client.py.
+//
+//   const bb = client({ url, apiKey });
+//   for await (const s of bb.allSessions({ label: "billing-agent" })) console.log(s.session_id);
+//   for await (const line of bb.tail(id)) console.log(line.kind);
+import { verifyBundle } from "../verify/anchor.js";
+import { hashBody } from "../verify/envelope.js";
+/**
+ * The gateway answered with an error, or couldn't be reached. `code` is its stable error code
+ * (spec/api.md §3), or `network`, `timeout` or `integrity` from the client itself. `requestId` is
+ * the gateway's `x-request-id`, to find the call in its logs.
+ */
+export class BlackboxApiError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(status, code, message, requestId = null) {
+        super(`${status} ${code}: ${message}${requestId ? ` (request ${requestId})` : ""}`);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+const RETRY_STATUSES = new Set([429, 503]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function client(options) {
+    const base = options.url.replace(/\/$/, "");
+    const retries = options.retries ?? 2;
+    async function once(method, path, body) {
+        let res;
+        try {
+            res = await fetch(`${base}${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${options.apiKey}`,
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
+            });
+        }
+        catch (error) {
+            const timedOut = error instanceof Error && error.name === "TimeoutError";
+            throw new BlackboxApiError(0, timedOut ? "timeout" : "network", error instanceof Error ? error.message : String(error));
+        }
+        if (res.status >= 400) {
+            const text = await res.text();
+            let err = {};
+            try {
+                err = JSON.parse(text);
+            }
+            catch { }
+            throw Object.assign(new BlackboxApiError(res.status, typeof err.code === "string" ? err.code : "error", typeof err.error === "string" ? err.error : text.slice(0, 200), res.headers.get("x-request-id")), { retryAfter: Number(res.headers.get("retry-after")) || 0 });
+        }
+        return res;
+    }
+    /** `retry` only for reads and idempotent writes: a retried POST must not act twice. */
+    async function request(method, path, body, retry = method === "GET") {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await once(method, path, body);
+            }
+            catch (error) {
+                const e = error;
+                const again = e.status === 0 || RETRY_STATUSES.has(e.status);
+                if (!retry || !again || attempt >= retries)
+                    throw error;
+                // the server's Retry-After, else 0.5 s, 1 s, 2 s ... with jitter, at most 10 s
+                const wait = e.retryAfter ? e.retryAfter * 1000 : 500 * 2 ** attempt;
+                await sleep(Math.min(10_000, wait) * (0.75 + Math.random() / 2));
+            }
+        }
+    }
+    const json = async (method, path, body, retry) => (await (await request(method, path, body, retry)).json());
+    const text = async (path) => (await request("GET", path)).text();
+    const ses = (id, action = "") => `/v1/sessions/${encodeURIComponent(id)}${action ? `/${action}` : ""}`;
+    const query = (q) => {
+        const p = new URLSearchParams();
+        for (const [k, v] of Object.entries(q))
+            if (v !== undefined)
+                p.set(k, String(v));
+        const s = p.toString();
+        return s ? `?${s}` : "";
+    };
+    const compact = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+    const api = {
+        /** Any JSON read route not covered below, e.g. `get("/v1/fleet/collisions")`. */
+        get: (path) => json("GET", path),
+        version: () => json("GET", "/v1/version"),
+        /** One page, newest first: `{sessions, next}`; pass `next` back as `before`. */
+        sessions: (q = {}) => json("GET", `/v1/sessions${query({ ...q })}`),
+        /** Every matching session, newest first, page by page. */
+        async *allSessions(q = {}) {
+            let before = q.before;
+            for (;;) {
+                const page = await api.sessions({ ...q, ...(before ? { before } : {}) });
+                yield* page.sessions;
+                if (!page.next)
+                    return;
+                before = page.next;
+            }
+        },
+        session: (id) => json("GET", ses(id)),
+        verify: (id) => json("GET", ses(id, "verify")),
+        state: (id) => json("GET", ses(id, "state")),
+        /** The session's events, parsed; with `afterSeq`, only those after it (audit S4). */
+        async events(id, o = {}) {
+            const t = await text(`${ses(id, "events")}${query({ after_seq: o.afterSeq })}`);
+            return t
+                .split("\n")
+                .filter((l) => l)
+                .map((l) => JSON.parse(l));
+        },
+        /**
+         * Audit K13: the session's events live, as they're recorded (Server-Sent Events), from
+         * `afterSeq`. Ends once the session is closed and everything is sent.
+         */
+        async *tail(id, o = {}) {
+            const res = await once("GET", `${ses(id, "stream")}${query({ after_seq: o.afterSeq })}`);
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    return;
+                buffer += decoder.decode(value, { stream: true });
+                for (let end = buffer.indexOf("\n\n"); end !== -1; end = buffer.indexOf("\n\n")) {
+                    const frame = buffer.slice(0, end);
+                    buffer = buffer.slice(end + 2);
+                    if (/^event: end$/m.test(frame))
+                        return;
+                    const data = frame
+                        .split("\n")
+                        .filter((l) => l.startsWith("data: "))
+                        .map((l) => l.slice(6))
+                        .join("\n");
+                    if (data)
+                        yield JSON.parse(data);
+                }
+            }
+        },
+        /** The audit bundle, typed for verifyBundle (audit K22). */
+        bundle: async (id) => (await json("GET", ses(id, "bundle"))),
+        /** Audit K22: fetches the bundle and verifies it here, not trusting the gateway's own check. */
+        async verifiedBundle(id, o = {}) {
+            const bundle = await api.bundle(id);
+            return { bundle, report: await verifyBundle(bundle, o) };
+        },
+        summary: (id) => json("GET", ses(id, "summary")),
+        cost: (id) => json("GET", ses(id, "cost")),
+        findings: (id) => json("GET", ses(id, "findings")),
+        landing: (id) => json("GET", ses(id, "landing")),
+        waste: (id) => json("GET", ses(id, "waste")),
+        /** Markdown, in English or Arabic. */
+        incident: (id, lang = "en") => text(`${ses(id, "incident")}${query({ lang })}`),
+        fleet: () => json("GET", "/v1/fleet"),
+        logbook: (o = {}) => json("GET", `/v1/logbook${query({ ...o })}`),
+        certificate: (label) => json("GET", `/v1/logbook/certificate${query({ label })}`),
+        /**
+         * The exact body bytes, or null if unknown or erased. The bytes are checked against their
+         * hash (audit K24): a mismatch throws, code `integrity`.
+         */
+        async body(hash) {
+            let bytes;
+            try {
+                bytes = new Uint8Array(await (await request("GET", `/v1/bodies/${encodeURIComponent(hash).replace(/%3A/gi, ":")}`)).arrayBuffer());
+            }
+            catch (error) {
+                if (error instanceof BlackboxApiError && (error.status === 404 || error.status === 410))
+                    return null;
+                throw error;
+            }
+            if (hashBody(bytes) !== hash)
+                throw new BlackboxApiError(0, "integrity", `the gateway's bytes don't match ${hash}`);
+            return bytes;
+        },
+        // ---------------------------------------------------------------- control (audit K6)
+        close: (id, o = {}) => json("POST", ses(id, "close"), o, true), // idempotent (spec/api.md)
+        /** PDPL / GDPR erasure of a closed session's content (spec/api.md). Idempotent. */
+        erase: (id) => json("POST", ses(id, "erase"), {}, true),
+        /** Unblocks a blocked session (spec/control.md §3). */
+        resume: (id, o = {}) => json("POST", ses(id, "resume"), compact(o)),
+        /** Stops the session at its next call, resumable without a token (spec/control.md §3). */
+        pause: (id, o = {}) => json("POST", ses(id, "pause"), compact(o)),
+        /** The emergency stop (squawk 7700, spec/control.md). */
+        emergency: (id, o = {}) => json("POST", ses(id, "emergency"), compact(o)),
+        /** Hands the controls over (spec/authority.md): `human` takes over; `agent`/`supervised` hand back. */
+        authority: (id, to, o = {}) => json("POST", ses(id, "authority"), compact({ to, ...o })),
+        /** The pending approvals (spec/approvals.md). */
+        approvals: (id) => json("GET", ses(id, "approvals")),
+        /** Approves or rejects one (never with the session's own token). */
+        decide: (id, approvalId, decision, o = {}) => json("POST", `${ses(id, "approvals")}/${encodeURIComponent(approvalId)}`, compact({ decision, ...o })),
+        /** The undo plan (spec/undo.md); with `confirm: true`, runs the gateway's own steps. */
+        undo: (id, o = {}) => o.confirm ? json("POST", ses(id, "undo"), { confirm: true }) : json("GET", ses(id, "undo")),
+        /** Records a regulator filing (spec/occurrence.md). */
+        file: (id, filing) => json("POST", ses(id, "occurrence/filings"), compact(filing)),
+        /** A cost reconciliation against the provider's statement (spec/money.md §2). */
+        reconcileCosts: (input) => json("POST", "/v1/costs/reconcile", compact(input)),
+        /** Operator only: tenants and their keys (spec/tenancy.md). */
+        tenants: () => json("GET", "/v1/tenants"),
+        createTenant: (name) => json("POST", "/v1/tenants", { name }),
+        updateTenant: (tenantId, o) => json("PATCH", `/v1/tenants/${encodeURIComponent(tenantId)}`, compact(o)),
+        createKey: (tenantId, o = {}) => json("POST", `/v1/tenants/${encodeURIComponent(tenantId)}/keys`, compact(o)),
+        revokeKey: (tenantId, keyId) => json("POST", `/v1/tenants/${encodeURIComponent(tenantId)}/keys/${encodeURIComponent(keyId)}/revoke`, {}, true),
+    };
+    return api;
+}

package/dist/compliance/index.d.ts

@@ -0,0 +1,41 @@
+export type FactValue = number | string | null | Record<string, number>;
+export type Facts = Record<string, FactValue>;
+export interface Framework {
+    title: string;
+    sections: Array<{
+        id: string;
+        title: string;
+        requirement: string;
+        facts: string[];
+    }>;
+}
+export interface Report {
+    framework: string;
+    title: string;
+    tenant_id: string;
+    from: string;
+    to: string;
+    generated_at: string;
+    facts: Facts;
+    sections: Array<{
+        id: string;
+        title: string;
+        requirement: string;
+        evidence: Facts;
+    }>;
+    notes: string;
+}
+export declare function complianceReport(frameworkId: string, framework: Framework, facts: Facts, meta: {
+    tenant_id: string;
+    from: string;
+    to: string;
+    generated_at: string;
+    notes: string;
+}): Report;
+export declare function renderReport(r: Report): string;
+/** spec/compliance.md §1: the facts over sessions' records (the server adds verified / anchored). */
+export declare function complianceFacts(sessions: ReadonlyArray<{
+    lines: readonly string[];
+    verified: boolean;
+    anchored: boolean;
+}>, dataRegion: string | null): Facts;

package/dist/compliance/index.js

@@ -0,0 +1,96 @@
+// Compliance reports (spec/compliance.md): facts from the record, mapped onto a framework's sections,
+// and rendered as Markdown. Evidence mapping, not legal advice. Mirrors sdks/python/src/zanii_blackbox/compliance.py.
+export function complianceReport(frameworkId, framework, facts, meta) {
+    return {
+        framework: frameworkId,
+        title: framework.title,
+        ...meta,
+        facts,
+        sections: framework.sections.map((s) => ({
+            id: s.id,
+            title: s.title,
+            requirement: s.requirement,
+            evidence: Object.fromEntries(s.facts.map((f) => [f, facts[f] ?? null])),
+        })),
+    };
+}
+const show = (v) => {
+    if (v === null)
+        return "not set";
+    if (typeof v === "object") {
+        const keys = Object.keys(v).sort();
+        return keys.length === 0 ? "none" : keys.map((k) => `${k}: ${v[k]}`).join(", ");
+    }
+    return String(v);
+};
+export function renderReport(r) {
+    const out = [
+        `# ${r.title}`,
+        "",
+        `Tenant \`${r.tenant_id}\` · sessions created from ${r.from} to ${r.to} (exclusive) · generated ${r.generated_at}`,
+        "",
+        `> ${r.notes}`,
+    ];
+    for (const s of r.sections) {
+        out.push("", `## ${s.title}`, "", s.requirement, "", "| Evidence | Value |", "|---|---|");
+        for (const [k, v] of Object.entries(s.evidence))
+            out.push(`| ${k} | ${show(v)} |`);
+    }
+    return `${out.join("\n")}\n`;
+}
+/** spec/compliance.md §1: the facts over sessions' records (the server adds verified / anchored). */
+export function complianceFacts(sessions, dataRegion) {
+    const redactions = {};
+    const outcomes = { success: 0, failure: 0, abandoned: 0, unlabelled: 0 };
+    let events = 0;
+    let findingsWarning = 0;
+    let bypasses = 0;
+    let falseClaims = 0;
+    let blocks = 0;
+    let emergencies = 0;
+    let resumesWithNote = 0;
+    for (const s of sessions) {
+        let outcome = "unlabelled";
+        for (const line of s.lines) {
+            events++;
+            const e = JSON.parse(line);
+            const m = e.meta;
+            if (m.redacted && typeof m.redacted === "object")
+                for (const [k, v] of Object.entries(m.redacted))
+                    if (typeof v === "number")
+                        redactions[k] = (redactions[k] ?? 0) + v;
+            if (e.kind === "finding") {
+                if (m.severity === "warning")
+                    findingsWarning++;
+                if (m.code === "BYPASS")
+                    bypasses++;
+                if (m.code === "FALSE_CLAIM")
+                    falseClaims++;
+            }
+            else if (e.kind === "control") {
+                if (m.action === "block")
+                    m.code === "EMERGENCY" ? emergencies++ : blocks++;
+                if (m.action === "resume" && typeof m.note === "string" && m.note !== "")
+                    resumesWithNote++;
+            }
+            else if (e.kind === "outcome" && typeof m.outcome === "string" && m.outcome in outcomes)
+                outcome = m.outcome;
+        }
+        outcomes[outcome]++;
+    }
+    return {
+        sessions: sessions.length,
+        events,
+        sessions_verified: sessions.filter((s) => s.verified).length,
+        sessions_anchored: sessions.filter((s) => s.anchored).length,
+        redactions,
+        findings_warning: findingsWarning,
+        bypasses,
+        false_claims: falseClaims,
+        blocks,
+        emergency_stops: emergencies,
+        resumes_with_note: resumesWithNote,
+        outcomes,
+        data_region: dataRegion,
+    };
+}

package/dist/cost/index.d.ts

@@ -0,0 +1,133 @@
+/** µUSD per million tokens, for the classes a tier or a service tier overrides. */
+export interface ClassPrices {
+    input?: number;
+    output?: number;
+    cache_read?: number;
+    cache_write?: number;
+}
+export interface ModelPrice {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    /** Tokens; optional (the context-bloat detector uses it). */
+    context_window?: number;
+    /** Anthropic's 1-hour cache writes (else `cache_write`). */
+    cache_write_1h?: number;
+    /** Audio in and out (else `input` / `output`). */
+    input_audio?: number;
+    output_audio?: number;
+    /** µUSD per 1,000 web-search requests (Anthropic's server tool); absent: not priced. */
+    web_search_per_1k?: number;
+    /** Prices once the call's prompt is over `above` tokens (Gemini's >200k tier), highest first. */
+    context_tiers?: Array<ClassPrices & {
+        above: number;
+    }>;
+    /** Prices for a provider's service tier (OpenAI `flex`, `priority`; Gemini's traffic type). */
+    service_tiers?: Record<string, ClassPrices>;
+    /** `deprecated` feeds the MODEL_DEPRECATED finding; `beta` is informational. */
+    status?: "deprecated" | "beta";
+}
+export interface PriceTable {
+    version: string;
+    currency: "USD";
+    unit: "micro_usd_per_mtok";
+    models: Record<string, ModelPrice>;
+}
+export interface Tokens {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    /** Present only when non-zero (2026-10-01): each is also out of the class it's part of. */
+    cache_write_1h?: number;
+    input_audio?: number;
+    output_audio?: number;
+}
+export interface CallCost {
+    seq: number;
+    model: string | null;
+    tokens: Tokens;
+    micro_usd: number | null;
+    /** Only when present: web-search requests; the tier the call was priced at; `reported` when
+     *  the provider's own cost was used (no table price). */
+    requests?: {
+        web_search: number;
+    };
+    tier?: {
+        service?: string;
+        context_above?: number;
+    };
+    source?: "reported";
+}
+export interface CostReport {
+    v: 1;
+    /** `pinned`: whether this is the table the session opened with (absent: nothing was pinned). */
+    price_table: {
+        version: string;
+        sha256: string;
+        pinned?: boolean;
+    };
+    total_micro_usd: number;
+    total_aed_fils: number;
+    calls_priced: number;
+    calls_unpriced: number;
+    unknown_models: string[];
+    tokens: Tokens;
+    calls: CallCost[];
+    /** Calls served from a replay cassette, left out of the cost (present only when there are any). */
+    calls_replayed?: number;
+    /** Web-search requests, when there were any. */
+    requests?: {
+        web_search: number;
+    };
+}
+export interface LoadedPrices {
+    table: PriceTable;
+    sha256: string;
+}
+/** Parses and checks a price table; its sha256 is of the exact file bytes. */
+export declare function loadPrices(bytes: Uint8Array): LoadedPrices;
+/** The exact model, else the longest table key the model starts with; null when there's none. */
+export declare function priceFor(model: string, table: PriceTable, 
+/** The configured provider id: `<provider>/<model>` keys are tried first (spec/cost.md §1). */
+provider?: string | null): {
+    key: string;
+    price: ModelPrice;
+} | null;
+/** Token classes from a recorded, flattened `meta.usage` (spec/cost.md §2). */
+export declare function tokensOf(usage: Record<string, unknown>): Tokens;
+/** Requests a call made to a provider's server tools (Anthropic web search). */
+export declare function requestsOf(usage: Record<string, unknown>): {
+    web_search: number;
+} | undefined;
+/** A call's prompt, in tokens: what a context tier is decided on. */
+export declare function promptTokens(t: Tokens): number;
+/** The prices a call pays: a context tier when its prompt is over one, then its service tier. */
+export declare function effectivePrice(price: ModelPrice, tokens: Tokens, serviceTier?: string | null): {
+    price: ModelPrice;
+    tier?: {
+        service?: string;
+        context_above?: number;
+    };
+};
+/** round_half_up((tokens × price + requests × price per 1k × 1000) / 1e6), integers only. */
+export declare function callMicroUsd(tokens: Tokens, price: ModelPrice, requests?: {
+    web_search: number;
+}): number;
+/** One call's cost as the cost report prices it: the table (provider-scoped, tiered), else the
+ *  provider's own reported cost, else null. The spend and duty checks use the same. */
+export declare function priceCall(call: {
+    model: string | null;
+    usage: Record<string, unknown>;
+    provider?: string | null;
+    serviceTier?: string | null;
+    reportedMicroUsd?: number | null;
+}, table: PriceTable): Omit<CallCost, "seq" | "model"> & {
+    key: string | null;
+};
+/** fils at the CBUAE peg (3.6725 AED / USD), rounded half up. */
+export declare function toAedFils(microUsd: number): number;
+export declare function formatAed(fils: number): string;
+/** The session's cost report from its recorded lines. */
+export declare function sessionCost(lines: readonly string[], prices: LoadedPrices): CostReport;