@zanii/blackbox 0.13.0 → 0.15.0

package/README.md

@@ -83,6 +83,18 @@ verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: t
 
 The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
 
+## New in 0.15.0
+
+- M-of-N shares: `splitSecret` / `combineShares`, and `blackbox key-split --m 3 --n 5` / `blackbox key-combine`, so no single custodian holds the gateway's key passphrase.
+- `otlpFromProtobuf(bytes)`: OTLP/HTTP protobuf spans, read without a protobuf library (gateway v0.17 takes them on `/v1/traces`).
+- Works with gateway v0.17: the passphrase from Google Cloud KMS or Azure Key Vault, retention per tenant, closed-session summaries kept, the trace exported while a session runs.
+
+## New in 0.14.0
+
+- Price uplifts (`uplifts` in a price table): US-only inference, regional endpoints and fast modes priced above list, per deployment (`upliftPercent`).
+- Statements in any currency: the `fx:<CUR>:<rate>` unit, `fxRate(currency)` (the ECB's rate through Frankfurter), and `blackbox statement --currency EUR` with the rate, date and source in the statement.
+- Tax invoices for zero-rated and reverse-charge customers (`vat_treatment`).
+
 ## New in 0.13.0
 
 - `fromOtlp(body)`: OpenTelemetry spans (GenAI semconv or OpenInference) as session events, the mapping behind gateway v0.15's `POST /v1/traces`. Point any framework's OTLP exporter at the gateway with the session's token, and its spans join the record.

package/dist/billing/index.d.ts

@@ -31,6 +31,8 @@ export interface Plans {
 }
 /** Parses a plans file (spec/billing.md §1); throws on anything that isn't integer fils. */
 export declare function loadPlans(bytes: Uint8Array): Plans;
+/** spec/billing.md §5b: how VAT applies to a customer. */
+export type VatTreatment = "standard" | "zero_rated" | "reverse_charge";
 export interface TaxInvoiceInput {
     number: string;
     issued_at: string;
@@ -53,6 +55,8 @@ export interface TaxInvoiceInput {
         sessions: number;
     };
     vat_percent?: number;
+    /** §5b: `zero_rated` and `reverse_charge` invoice VAT at 0%, with a note saying why. */
+    vat_treatment?: VatTreatment;
 }
 /** spec/billing.md §5: the tax invoice document. */
 export declare function taxInvoice(input: TaxInvoiceInput): {
@@ -90,6 +94,8 @@ export declare function taxInvoice(input: TaxInvoiceInput): {
         events: number;
         sessions: number;
     };
+    vat_treatment?: "reverse_charge" | "zero_rated";
+    vat_note?: string;
     total_aed: string;
 };
 export type TaxInvoice = ReturnType<typeof taxInvoice>;

package/dist/billing/index.js

@@ -69,6 +69,10 @@ export function loadPlans(bytes) {
     }
     return doc;
 }
+const VAT_NOTES = {
+    zero_rated: "Zero-rated supply (export of services): VAT at 0%",
+    reverse_charge: "Reverse charge: the customer accounts for the VAT",
+};
 /** The month's `[from, to)` and its last day (spec/billing.md §5). */
 function period(month) {
     const [y, m] = month.split("-").map(Number);
@@ -79,7 +83,8 @@ function period(month) {
 /** spec/billing.md §5: the tax invoice document. */
 export function taxInvoice(input) {
     const p = period(input.month);
-    const inv = invoice(input.plan, input.usage, input.vat_percent ?? 5);
+    const treatment = input.vat_treatment ?? "standard";
+    const inv = invoice(input.plan, input.usage, treatment === "standard" ? (input.vat_percent ?? 5) : 0);
     return {
         v: 1,
         title: "Tax Invoice",
@@ -101,6 +106,9 @@ export function taxInvoice(input) {
         plan: { id: input.plan_id, name: input.plan.name, version: input.plans_version },
         usage: { events: input.usage.events, sessions: input.usage.sessions },
         ...inv,
+        ...(treatment !== "standard"
+            ? { vat_treatment: treatment, vat_note: VAT_NOTES[treatment] }
+            : {}),
         total_aed: formatAed(inv.total_fils),
     };
 }
@@ -146,6 +154,7 @@ export function renderTaxInvoice(d) {
         `| VAT ${d.vat_percent}% | ${aed(d.vat_fils)} |`,
         `| **Total** | **${aed(d.total_fils)}** |`,
         "",
+        ...(d.vat_note ? [`VAT: ${d.vat_note}.`, ""] : []),
         `Plan: ${oneLine(d.plan.name)} (${d.plan.id}, plans ${d.plan.version}). Usage: ${grouped(d.usage.events)} events, ${grouped(d.usage.sessions)} sessions.`,
         "",
     ];

package/dist/cli.js

@@ -43,7 +43,7 @@ const USAGE = `usage (spec/cli.md):
   blackbox policy-from-zanii <zanii-policy.json> [--out <file>]
   blackbox policy-to-zanii <policy.json> [--out <file>]
   blackbox statement --provider anthropic|openai --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
-  blackbox statement --provider csv --file <f> --model-column <name> --amount-column <name> --unit usd|cents|micro_usd|aed [--delimiter <c>] --from <d> --to <d> [--out <file>]
+  blackbox statement --provider csv --file <f> --model-column <name> --amount-column <name> (--unit usd|cents|micro_usd|aed | --currency <CUR> [--rate <usd per unit>] [--rate-date <d>]) [--delimiter <c>] --from <d> --to <d> [--out <file>]
   blackbox statement --provider custom --connector <file> --from <d> --to <d> [--out <file>]
   blackbox preflight --require <items> [--optional <items>]
   blackbox --version
@@ -53,7 +53,9 @@ const USAGE = `usage (spec/cli.md):
   blackbox reconcile-system --connector <connector.json> --log <export.csv|jsonl> [--pack <pack.json>] <session_id>
   blackbox workspace-receipt   (a Claude Code PreToolUse / PostToolUse hook; reads the hook JSON on stdin)
   blackbox attest   (a Claude Code PostToolUse hook: spec/attestation.md §4)
-  blackbox policy-hook   (a Claude Code / Codex PreToolUse hook: asks the gateway's policy; fails closed)`;
+  blackbox policy-hook   (a Claude Code / Codex PreToolUse hook: asks the gateway's policy; fails closed)
+  blackbox key-split --m <M> --n <N> < secret   (M-of-N shares of a secret, one per line: spec/operations.md §4b)
+  blackbox key-combine <share> <share> …   (the secret back, on stdout)`;
 async function main(argv) {
     const [command, ...rest] = argv;
     if (command === "mcp")
@@ -70,6 +72,10 @@ async function main(argv) {
         return attestCommand();
     if (command === "policy-hook")
         return policyHookCommand();
+    if (command === "key-split")
+        return keySplitCommand(rest);
+    if (command === "key-combine")
+        return keyCombineCommand(rest);
     if (command === "verify")
         return verifyCommand(rest);
     if (command === "export")
@@ -218,6 +224,39 @@ async function attestCommand() {
     }
     return 0;
 }
+/** spec/operations.md §4b: the secret on stdin, as M-of-N shares on stdout, one a line. */
+async function keySplitCommand(rest) {
+    const { flags } = parse(rest, []);
+    const m = Number(flags.m);
+    const n = Number(flags.n);
+    const parts = [];
+    for await (const chunk of process.stdin)
+        parts.push(chunk);
+    const secret = Buffer.from(Buffer.concat(parts)
+        .toString("utf8")
+        .replace(/\r?\n$/, ""), "utf8");
+    try {
+        const { splitSecret } = await import("./shares/index.js");
+        process.stdout.write(`${splitSecret(secret, m, n).join("\n")}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`blackbox key-split: ${error instanceof Error ? error.message : error}\n`);
+        return 2;
+    }
+}
+/** spec/operations.md §4b: M shares (arguments) back to the secret, on stdout. */
+async function keyCombineCommand(rest) {
+    try {
+        const { combineShares } = await import("./shares/index.js");
+        process.stdout.write(`${Buffer.from(combineShares(rest)).toString("utf8")}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`blackbox key-combine: ${error instanceof Error ? error.message : error}\n`);
+        return 2;
+    }
+}
 /** spec/policy.md §2a: a PreToolUse hook. Deny: exit 2, the reason on stderr (the agent sees it).
  * Ask: Claude Code's `permissionDecision: "ask"` on stdout. Allow: exit 0, nothing printed. Any
  * failure denies, unless BLACKBOX_HOOK_FAIL_OPEN=1. */
@@ -956,8 +995,29 @@ async function statementAny(provider, flags, from, to) {
     if (provider === "csv") {
         const model = flags["model-column"];
         const amount = flags["amount-column"];
-        const unit = flags.unit;
+        let unit = flags.unit;
         const delimiter = flags.delimiter;
+        // spec/money.md §2c: another currency, at a stated rate or the ECB's for the day
+        let fx;
+        if (flags.currency) {
+            try {
+                fx = flags.rate
+                    ? {
+                        currency: flags.currency,
+                        usd_per_unit: flags.rate,
+                        date: flags["rate-date"] ?? to,
+                        source: "stated",
+                    }
+                    : await money.fxRate(flags.currency, {
+                        ...(flags["rate-date"] ? { date: flags["rate-date"] } : {}),
+                        ...(process.env.BLACKBOX_FX_URL ? { url: process.env.BLACKBOX_FX_URL } : {}),
+                    });
+                unit = money.fxUnit(fx.currency, fx.usd_per_unit);
+            }
+            catch (e) {
+                return message(e);
+            }
+        }
         if (!flags.file ||
             !model ||
             !amount ||
@@ -972,7 +1032,7 @@ async function statementAny(provider, flags, from, to) {
                 unit,
                 ...(delimiter ? { delimiter } : {}),
             });
-            return { doc: { provider: "csv", from, to, lines: statement.lines } };
+            return { doc: { provider: "csv", from, to, lines: statement.lines, ...(fx ? { fx } : {}) } };
         }
         catch (e) {
             return message(e);

package/dist/cost/index.d.ts

@@ -33,6 +33,19 @@ export interface PriceTable {
     currency: "USD";
     unit: "micro_usd_per_mtok";
     models: Record<string, ModelPrice>;
+    /** spec/cost.md §1a: percentages added to a call's table price when it matches. */
+    uplifts?: Uplift[];
+}
+/** spec/cost.md §1a: a call that matches every condition given costs `percent` more. */
+export interface Uplift {
+    /** The configured provider id the call went to (`bedrock-eu`). */
+    provider?: string;
+    /** A model id prefix (`claude-opus-5`). */
+    model?: string;
+    /** Flattened usage fields and the values they must have (`{"inference_geo": "us"}`). */
+    usage?: Record<string, string>;
+    percent: number;
+    note?: string;
 }
 export interface Tokens {
     input: number;
@@ -58,6 +71,8 @@ export interface CallCost {
         service?: string;
         context_above?: number;
     };
+    /** spec/cost.md §1a: the uplift applied, when one matched. */
+    uplift_percent?: number;
     source?: "reported";
 }
 export interface CostReport {
@@ -126,6 +141,9 @@ export declare function priceCall(call: {
 }, table: PriceTable): Omit<CallCost, "seq" | "model"> & {
     key: string | null;
 };
+/** spec/cost.md §1a: the sum of the uplifts a call matches (0 when none): its provider, a model
+ * prefix, and usage fields, each only when the uplift names it. */
+export declare function upliftPercent(table: PriceTable, provider: string | null, model: string, usage: Record<string, unknown>): number;
 /** 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;

package/dist/cost/index.js

@@ -40,6 +40,24 @@ export function loadPrices(bytes) {
         if (p.status !== undefined && p.status !== "deprecated" && p.status !== "beta")
             throw new Error(`price table: ${model}.status must be deprecated or beta`);
     }
+    if (table.uplifts !== undefined) {
+        if (!Array.isArray(table.uplifts))
+            throw new Error("price table: uplifts must be a list");
+        for (const [i, u] of table.uplifts.entries()) {
+            const at = `price table: uplifts[${i}]`;
+            if (!Number.isSafeInteger(u?.percent) || u.percent < 1 || u.percent > 1000)
+                throw new Error(`${at}.percent must be an integer 1-1000`);
+            if (u.provider !== undefined && typeof u.provider !== "string")
+                throw new Error(`${at}.provider must be a string`);
+            if (u.model !== undefined && typeof u.model !== "string")
+                throw new Error(`${at}.model must be a string`);
+            if (u.usage !== undefined &&
+                (typeof u.usage !== "object" ||
+                    u.usage === null ||
+                    Object.values(u.usage).some((v) => typeof v !== "string")))
+                throw new Error(`${at}.usage must map usage fields to strings`);
+        }
+    }
     return { table, sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}` };
 }
 /** The exact model, else the longest table key the model starts with; null when there's none. */
@@ -194,12 +212,15 @@ export function priceCall(call, table) {
     const match = call.model === null ? null : priceFor(call.model, table, call.provider);
     if (match) {
         const { price, tier } = effectivePrice(match.price, tokens, call.serviceTier);
+        const base = callMicroUsd(tokens, price, requests);
+        const uplift = upliftPercent(table, call.provider ?? null, call.model, call.usage);
         return {
             key: match.key,
             tokens,
-            micro_usd: callMicroUsd(tokens, price, requests),
+            micro_usd: uplift ? Math.floor((base * (100 + uplift) + 50) / 100) : base,
             ...(requests ? { requests } : {}),
             ...(tier ? { tier } : {}),
+            ...(uplift ? { uplift_percent: uplift } : {}),
         };
     }
     if (typeof call.reportedMicroUsd === "number")
@@ -212,6 +233,21 @@ export function priceCall(call, table) {
         };
     return { key: null, tokens, micro_usd: null, ...(requests ? { requests } : {}) };
 }
+/** spec/cost.md §1a: the sum of the uplifts a call matches (0 when none): its provider, a model
+ * prefix, and usage fields, each only when the uplift names it. */
+export function upliftPercent(table, provider, model, usage) {
+    let percent = 0;
+    for (const u of table.uplifts ?? []) {
+        if (u.provider !== undefined && u.provider !== provider)
+            continue;
+        if (u.model !== undefined && !model.startsWith(u.model))
+            continue;
+        if (u.usage && Object.entries(u.usage).some(([k, v]) => String(usage[k] ?? "") !== v))
+            continue;
+        percent += u.percent;
+    }
+    return percent;
+}
 /** fils at the CBUAE peg (3.6725 AED / USD), rounded half up. */
 export function toAedFils(microUsd) {
     return Math.floor((microUsd * 36725 + 50_000_000) / 100_000_000);

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Con
 export { deadlinesDue, filingPack, type OccurrenceFacts, type OccurrenceFramework, type OccurrenceReport, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.ts";
 export { ingestOcsf, type OcsfEvent, type OcsfVersion, ocsfLine, toOcsf } from "./ocsf/index.ts";
 export { fromOtlp, type OtlpEvent, toOtlp } from "./otlp/index.ts";
+export { otlpFromProtobuf } from "./otlp/protobuf.ts";
 export { checkIdentifier, checkPack, corePack, type PackEntry, packData, packFrameworks, } from "./packs/index.ts";
 export { type PolicyChange, type PolicyDelta, policyDelta } from "./policy/delta.ts";
 export { type Draft, type DraftGroup, policyDrafts } from "./policy/drafts.ts";
@@ -62,6 +63,7 @@ export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.ts";
 export { checkSearch, type SearchMatch, type SearchQuery, searchEvents } from "./search/index.ts";
 export { type DrainResult, drainSpools } from "./session/drain.ts";
 export { type AnswerCheck, BlackboxSession, checkEgress, type EgressCheck, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
+export { combineShares, splitSecret } from "./shares/index.ts";
 export { assembleSla, assessCompliance, buildSlaBody, signSla, slaHash, verifySla, } from "./sla/index.ts";
 export { assembleSuccession, buildSuccessionBody, type Succession, type SuccessionBody, type SuccessionReason, signSuccession, successionHash, verifyLineage, verifySuccession, } from "./succession/index.ts";
 export { type TimestampReport, timestampRequest, verifyTimestamp, } from "./timestamp/index.ts";

package/dist/index.js

@@ -45,6 +45,7 @@ export { anthropicStatement, baselines, checkConnector, checkStatement, csvState
 export { deadlinesDue, filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
 export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
 export { fromOtlp, toOtlp } from "./otlp/index.js";
+export { otlpFromProtobuf } from "./otlp/protobuf.js";
 export { checkIdentifier, checkPack, corePack, packData, packFrameworks, } from "./packs/index.js";
 export { policyDelta } from "./policy/delta.js";
 export { policyDrafts } from "./policy/drafts.js";
@@ -64,6 +65,7 @@ export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.js";
 export { checkSearch, searchEvents } from "./search/index.js";
 export { drainSpools } from "./session/drain.js";
 export { BlackboxSession, checkEgress, session, stableEventId, } from "./session/index.js";
+export { combineShares, splitSecret } from "./shares/index.js";
 export { assembleSla, assessCompliance, buildSlaBody, signSla, slaHash, verifySla, } from "./sla/index.js";
 export { assembleSuccession, buildSuccessionBody, signSuccession, successionHash, verifyLineage, verifySuccession, } from "./succession/index.js";
 export { timestampRequest, verifyTimestamp, } from "./timestamp/index.js";

package/dist/money/index.d.ts

@@ -45,7 +45,23 @@ export declare function fuel(summary: Summary, budgetMicroUsd: number | null, ba
     p90_total_micro_usd: number | null;
     verdict: string;
 };
-export type AmountUnit = "usd" | "cents" | "micro_usd" | "aed";
+/** `fx:<ISO code>:<USD per unit>` (`fx:EUR:1.0821`): another currency at a stated rate (§2c). */
+export type AmountUnit = "usd" | "cents" | "micro_usd" | "aed" | `fx:${string}`;
+/** spec/money.md §2c: the unit for amounts in `currency` at `usdPerUnit` (a decimal string). */
+export declare function fxUnit(currency: string, usdPerUnit: string): AmountUnit;
+export interface FxRate {
+    currency: string;
+    /** USD per one unit of the currency, as the source gave it (a decimal string). */
+    usd_per_unit: string;
+    /** The rate's own date (a reference rate is set once a working day). */
+    date: string;
+    source: string;
+}
+/** spec/money.md §2c: the ECB reference rate for a day (or the latest), through Frankfurter. */
+export declare function fxRate(currency: string, opts?: {
+    date?: string;
+    url?: string;
+}): Promise<FxRate>;
 /** spec/money.md §2a-b: an exact decimal amount (string, or a JSON number's text) to integer
  * micro-USD, rounded half up. `unit` is what the amount counts. */
 export declare function decimalToMicroUsd(value: unknown, unit: AmountUnit): number;

package/dist/money/index.js

@@ -112,23 +112,66 @@ const UNITS = {
     micro_usd: [0, 1n],
     aed: [10, 36725n],
 };
+const FX_UNIT = /^fx:([A-Z]{3}):(\d{1,9})(?:\.(\d{1,12}))?$/;
+/** A unit as [power of ten, multiplier, divisor]; null for one that isn't. */
+function unitScale(unit) {
+    const s = Object.hasOwn(UNITS, unit) ? UNITS[unit] : undefined;
+    if (s)
+        return [s[0], 1n, s[1]];
+    const m = FX_UNIT.exec(unit);
+    if (!m)
+        return null;
+    const frac = m[3] ?? "";
+    const rate = BigInt(`${m[2]}${frac}`);
+    return rate === 0n ? null : [6 - frac.length, rate, 1n];
+}
+/** spec/money.md §2c: the unit for amounts in `currency` at `usdPerUnit` (a decimal string). */
+export function fxUnit(currency, usdPerUnit) {
+    const unit = `fx:${currency}:${usdPerUnit}`;
+    if (!unitScale(unit))
+        throw new Error(`not a currency and rate: ${currency} ${usdPerUnit}`);
+    return unit;
+}
+/** spec/money.md §2c: the ECB reference rate for a day (or the latest), through Frankfurter. */
+export async function fxRate(currency, opts = {}) {
+    if (!/^[A-Z]{3}$/.test(currency))
+        throw new Error(`not an ISO 4217 code: ${currency}`);
+    if (opts.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(opts.date))
+        throw new Error(`not a date: ${opts.date}`);
+    const base = (opts.url ?? "https://api.frankfurter.dev").replace(/\/+$/, "");
+    const res = await fetch(`${base}/v1/${opts.date ?? "latest"}?base=${currency}&symbols=USD`, {
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok)
+        throw new Error(`the rate service answered HTTP ${res.status}`);
+    const body = (await res.json());
+    const usd = body.rates?.USD;
+    if (typeof usd !== "number" || !(usd > 0) || typeof body.date !== "string")
+        throw new Error("the rate service's answer has no USD rate");
+    return {
+        currency,
+        usd_per_unit: String(usd),
+        date: body.date,
+        source: "ECB reference rate, via Frankfurter",
+    };
+}
 /** spec/money.md §2a-b: an exact decimal amount (string, or a JSON number's text) to integer
  * micro-USD, rounded half up. `unit` is what the amount counts. */
 export function decimalToMicroUsd(value, unit) {
     const text = typeof value === "number" && Number.isFinite(value) ? String(value) : value;
     const m = typeof text === "string" ? DECIMAL.exec(text.trim()) : null;
-    const scale = UNITS[unit];
+    const scale = unitScale(unit);
     if (!m || !scale)
         throw new Error(`not a non-negative decimal amount: ${JSON.stringify(value)}`);
     const frac = m[2] ?? "";
-    const digits = BigInt(`${m[1]}${frac}`);
+    const digits = BigInt(`${m[1]}${frac}`) * scale[1];
     if (digits === 0n)
         return 0;
     const k = Number(m[3] ?? 0) - frac.length + scale[0];
     if (k > 30)
         throw new Error(`amount too large: ${JSON.stringify(value)}`);
     const num = k >= 0 ? digits * 10n ** BigInt(k) : digits;
-    const den = scale[1] * (k >= 0 ? 1n : 10n ** BigInt(-k));
+    const den = scale[2] * (k >= 0 ? 1n : 10n ** BigInt(-k));
     let micro = num / den;
     if ((num % den) * 2n >= den)
         micro += 1n;
@@ -312,8 +355,8 @@ export function checkConnector(value) {
     for (const k of ["results", "model", "amount"])
         if (typeof c[k] !== "string" || !PATH.test(c[k]))
             return `${k} must be a path`;
-    if (!c.unit || !(c.unit in UNITS))
-        return "unit must be usd, cents, micro_usd or aed";
+    if (!c.unit || !unitScale(c.unit))
+        return "unit must be usd, cents, micro_usd, aed or fx:<CUR>:<USD per unit>";
     if (c.currency !== undefined &&
         (typeof c.currency?.path !== "string" ||
             !PATH.test(c.currency.path) ||

package/dist/otlp/protobuf.d.ts

@@ -0,0 +1,4 @@
+/** spec/otlp.md §4: an ExportTraceServiceRequest's bytes as OTLP/JSON. Throws on bad bytes. */
+export declare function otlpFromProtobuf(buf: Uint8Array): {
+    resourceSpans: object[];
+};

package/dist/otlp/protobuf.js

@@ -0,0 +1,167 @@
+// OTLP/HTTP protobuf (spec/otlp.md §4): an ExportTraceServiceRequest's bytes as the OTLP/JSON
+// shape `fromOtlp` reads. A reader for just the trace messages, no protobuf library: wire types
+// varint, 64-bit, length-delimited and 32-bit; unknown fields are skipped. Mirrors
+// sdks/python/src/zanii_blackbox/otlp_protobuf.py; pinned by spec/vectors/otlp-protobuf.json.
+function fields(buf) {
+    const out = [];
+    let i = 0;
+    const varint = () => {
+        let r = 0n;
+        let s = 0n;
+        for (;;) {
+            if (i >= buf.length)
+                throw new Error("protobuf: a varint runs past the end");
+            const b = buf[i++];
+            r |= BigInt(b & 0x7f) << s;
+            if (!(b & 0x80))
+                return r;
+            s += 7n;
+            if (s > 63n)
+                throw new Error("protobuf: a varint over 64 bits");
+        }
+    };
+    const fixed = (size) => {
+        if (i + size > buf.length)
+            throw new Error("protobuf: a fixed field runs past the end");
+        let v = 0n;
+        for (let k = size - 1; k >= 0; k--)
+            v = (v << 8n) | BigInt(buf[i + k]);
+        i += size;
+        return v;
+    };
+    while (i < buf.length) {
+        const key = Number(varint());
+        const n = key >>> 3;
+        const wire = key & 7;
+        if (wire === 0)
+            out.push({ n, wire, v: varint() });
+        else if (wire === 1)
+            out.push({ n, wire, v: fixed(8) });
+        else if (wire === 5)
+            out.push({ n, wire, v: fixed(4) });
+        else if (wire === 2) {
+            const len = Number(varint());
+            if (i + len > buf.length)
+                throw new Error("protobuf: a field runs past the end");
+            out.push({ n, wire, v: buf.subarray(i, i + len) });
+            i += len;
+        }
+        else
+            throw new Error(`protobuf: wire type ${wire} isn't supported`);
+    }
+    return out;
+}
+const text = (b) => new TextDecoder().decode(b);
+const hex = (b) => Buffer.from(b).toString("hex");
+const bytes = (f) => f.v;
+const big = (f) => f.v;
+const float64 = (bits) => {
+    const view = new DataView(new ArrayBuffer(8));
+    view.setBigUint64(0, bits, true);
+    return view.getFloat64(0, true);
+};
+function anyValue(b) {
+    for (const f of fields(b)) {
+        if (f.n === 1 && f.wire === 2)
+            return { stringValue: text(bytes(f)) };
+        if (f.n === 2 && f.wire === 0)
+            return { boolValue: big(f) !== 0n };
+        if (f.n === 3 && f.wire === 0)
+            return { intValue: BigInt.asIntN(64, big(f)).toString() };
+        if (f.n === 4 && f.wire === 1)
+            return { doubleValue: float64(big(f)) };
+        if (f.n === 5 && f.wire === 2)
+            return {
+                arrayValue: {
+                    values: fields(bytes(f))
+                        .filter((x) => x.n === 1 && x.wire === 2)
+                        .map((x) => anyValue(bytes(x))),
+                },
+            };
+        if (f.n === 6 && f.wire === 2)
+            return { kvlistValue: { values: keyValues(bytes(f), 1) } };
+        if (f.n === 7 && f.wire === 2)
+            return { bytesValue: Buffer.from(bytes(f)).toString("base64") };
+    }
+    return {};
+}
+/** The repeated KeyValue at field `at` of a message. */
+function keyValues(b, at) {
+    return fields(b)
+        .filter((f) => f.n === at && f.wire === 2)
+        .map((f) => {
+        let key = "";
+        let value = {};
+        for (const g of fields(bytes(f))) {
+            if (g.n === 1 && g.wire === 2)
+                key = text(bytes(g));
+            if (g.n === 2 && g.wire === 2)
+                value = anyValue(bytes(g));
+        }
+        return { key, value };
+    });
+}
+function span(b) {
+    const out = {};
+    for (const f of fields(b)) {
+        if (f.n === 1 && f.wire === 2)
+            out.traceId = hex(bytes(f));
+        else if (f.n === 2 && f.wire === 2)
+            out.spanId = hex(bytes(f));
+        else if (f.n === 4 && f.wire === 2 && bytes(f).length)
+            out.parentSpanId = hex(bytes(f));
+        else if (f.n === 5 && f.wire === 2)
+            out.name = text(bytes(f));
+        else if (f.n === 6 && f.wire === 0)
+            out.kind = Number(big(f));
+        else if (f.n === 7 && f.wire === 1)
+            out.startTimeUnixNano = big(f).toString();
+        else if (f.n === 8 && f.wire === 1)
+            out.endTimeUnixNano = big(f).toString();
+        else if (f.n === 15 && f.wire === 2) {
+            const status = {};
+            for (const g of fields(bytes(f))) {
+                if (g.n === 2 && g.wire === 2)
+                    status.message = text(bytes(g));
+                if (g.n === 3 && g.wire === 0)
+                    status.code = Number(big(g));
+            }
+            out.status = status;
+        }
+    }
+    out.attributes = keyValues(b, 9);
+    return out;
+}
+/** spec/otlp.md §4: an ExportTraceServiceRequest's bytes as OTLP/JSON. Throws on bad bytes. */
+export function otlpFromProtobuf(buf) {
+    return {
+        resourceSpans: fields(buf)
+            .filter((f) => f.n === 1 && f.wire === 2)
+            .map((rs) => {
+            const out = { scopeSpans: [] };
+            for (const f of fields(bytes(rs))) {
+                if (f.n === 1 && f.wire === 2)
+                    out.resource = { attributes: keyValues(bytes(f), 1) };
+                if (f.n === 2 && f.wire === 2) {
+                    const ss = { spans: [] };
+                    for (const g of fields(bytes(f))) {
+                        if (g.n === 1 && g.wire === 2) {
+                            const scope = {};
+                            for (const h of fields(bytes(g))) {
+                                if (h.n === 1 && h.wire === 2)
+                                    scope.name = text(bytes(h));
+                                if (h.n === 2 && h.wire === 2)
+                                    scope.version = text(bytes(h));
+                            }
+                            ss.scope = scope;
+                        }
+                        if (g.n === 2 && g.wire === 2)
+                            ss.spans.push(span(bytes(g)));
+                    }
+                    out.scopeSpans.push(ss);
+                }
+            }
+            return out;
+        }),
+    };
+}

package/dist/shares/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Splits `secret` into `n` shares, any `m` of which rebuild it: `zks1-<m>-<x>-<check>-<hex>`,
+ * where `check` (8 hex of the secret's SHA-256) catches a share from another secret. `random`
+ * gives the polynomial's coefficients (the tests pass fixed ones; never do that for real).
+ */
+export declare function splitSecret(secret: Uint8Array, m: number, n: number, random?: (count: number) => Uint8Array): string[];
+/** Rebuilds a secret from at least `m` of its shares; throws if they're too few or don't fit. */
+export declare function combineShares(shares: readonly string[]): Uint8Array;

package/dist/shares/index.js

@@ -0,0 +1,84 @@
+// M-of-N secret shares (spec/operations.md §4b): Shamir's scheme over GF(256), byte by byte, so any
+// M of N custodians can rebuild a secret (the key passphrase) and fewer learn nothing about it.
+// Mirrors sdks/python/src/zanii_blackbox/shares.py; pinned by spec/vectors/shares.json.
+import { createHash, randomBytes } from "node:crypto";
+// GF(256) with the AES polynomial x^8 + x^4 + x^3 + x + 1, generator 3
+const EXP = new Uint8Array(512);
+const LOG = new Uint8Array(256);
+{
+    let x = 1;
+    for (let i = 0; i < 255; i++) {
+        EXP[i] = x;
+        LOG[x] = i;
+        x ^= (x << 1) ^ (x & 0x80 ? 0x11b : 0);
+        x &= 0xff;
+    }
+    for (let i = 255; i < 512; i++)
+        EXP[i] = EXP[i - 255];
+}
+const mul = (a, b) => a === 0 || b === 0 ? 0 : EXP[LOG[a] + LOG[b]];
+const div = (a, b) => a === 0 ? 0 : EXP[LOG[a] + 255 - LOG[b]];
+const check = (secret) => createHash("sha256").update(secret).digest("hex").slice(0, 8);
+/**
+ * Splits `secret` into `n` shares, any `m` of which rebuild it: `zks1-<m>-<x>-<check>-<hex>`,
+ * where `check` (8 hex of the secret's SHA-256) catches a share from another secret. `random`
+ * gives the polynomial's coefficients (the tests pass fixed ones; never do that for real).
+ */
+export function splitSecret(secret, m, n, random = (count) => new Uint8Array(randomBytes(count))) {
+    if (!Number.isInteger(m) || !Number.isInteger(n) || m < 2 || n < m || n > 255)
+        throw new Error("shares need 2 ≤ m ≤ n ≤ 255");
+    if (secret.length < 1 || secret.length > 4096)
+        throw new Error("a secret is 1-4096 bytes");
+    const ys = Array.from({ length: n }, () => new Uint8Array(secret.length));
+    for (let i = 0; i < secret.length; i++) {
+        const coefficients = [secret[i], ...random(m - 1)];
+        for (let x = 1; x <= n; x++) {
+            let y = 0;
+            for (let k = coefficients.length - 1; k >= 0; k--)
+                y = mul(y, x) ^ coefficients[k]; // Horner, in GF(256)
+            ys[x - 1][i] = y;
+        }
+    }
+    const c = check(secret);
+    return ys.map((y, i) => `zks1-${m}-${i + 1}-${c}-${Buffer.from(y).toString("hex")}`);
+}
+/** Rebuilds a secret from at least `m` of its shares; throws if they're too few or don't fit. */
+export function combineShares(shares) {
+    const parsed = shares.map((s) => {
+        const p = /^zks1-(\d{1,3})-(\d{1,3})-([0-9a-f]{8})-((?:[0-9a-f]{2})+)$/.exec(s.trim());
+        if (!p)
+            throw new Error("not a share (zks1-<m>-<x>-<check>-<hex>)");
+        return {
+            m: Number(p[1]),
+            x: Number(p[2]),
+            check: p[3],
+            y: Buffer.from(p[4], "hex"),
+        };
+    });
+    const first = parsed[0];
+    if (!first)
+        throw new Error("no shares");
+    if (parsed.some((p) => p.m !== first.m || p.check !== first.check || p.y.length !== first.y.length))
+        throw new Error("the shares aren't of one secret");
+    const unique = [...new Map(parsed.map((p) => [p.x, p])).values()];
+    if (unique.some((p) => p.x < 1 || p.x > 255))
+        throw new Error("a share's index is out of range");
+    if (unique.length < first.m)
+        throw new Error(`${first.m} shares are needed, ${unique.length} given`);
+    const use = unique.slice(0, first.m);
+    const secret = new Uint8Array(first.y.length);
+    for (let i = 0; i < secret.length; i++) {
+        let s = 0;
+        for (const [j, pj] of use.entries()) {
+            let l = 1; // the Lagrange basis at 0
+            for (const [k, pk] of use.entries())
+                if (k !== j)
+                    l = mul(l, div(pk.x, pk.x ^ pj.x));
+            s ^= mul(pj.y[i], l);
+        }
+        secret[i] = s;
+    }
+    if (check(secret) !== first.check)
+        throw new Error("the shares don't fit together");
+    return secret;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.13.0";
+export declare const VERSION = "0.15.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.13.0";
+export const VERSION = "0.15.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",