@zanii/blackbox 0.11.0 → 0.13.0

package/README.md

@@ -83,6 +83,14 @@ 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.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.
+
+## New in 0.12.0
+
+- Tax credit notes: `taxCreditNote` / `renderTaxCreditNote`, the document and printable copy behind gateway v0.14's `POST /v1/invoices/:number/credit-notes`.
+
 ## New in 0.11.0
 
 - Facts against the record compare currencies and units: `AED 500` in a tool result no longer grounds `USD 500` in the answer, nor `500 g` grounds `500 mg` (`currencyCodes`, `unitOf`). Dates written with an English or Arabic month (`3 March 2026`, `3 مارس 2026`) are facts too.

package/dist/billing/index.d.ts

@@ -95,5 +95,51 @@ export declare function taxInvoice(input: TaxInvoiceInput): {
 export type TaxInvoice = ReturnType<typeof taxInvoice>;
 /** spec/billing.md §5: the printable copy. */
 export declare function renderTaxInvoice(d: TaxInvoice): string;
+export interface TaxCreditNoteInput {
+    number: string;
+    issued_at: string;
+    /** The invoice it corrects, as issued. */
+    invoice: TaxInvoice;
+    reason: string;
+    /** What this note credits, before VAT. */
+    subtotal_fils: number;
+    /** What earlier notes on the invoice credited already. */
+    credited?: {
+        subtotal_fils: number;
+        vat_fils: number;
+    };
+}
+/** spec/billing.md §5a: a tax credit note. The note that credits what's left of the invoice takes
+ * the rest of its VAT exactly, so the notes never credit more VAT than was invoiced. */
+export declare function taxCreditNote(input: TaxCreditNoteInput): {
+    v: 1;
+    title: "Tax Credit Note";
+    number: string;
+    issued_at: string;
+    invoice: {
+        number: string;
+        issued_at: string;
+    };
+    reason: string;
+    supplier: {
+        name: string;
+        address: string;
+        trn: string;
+    };
+    customer: {
+        legal_name: string;
+        address: string;
+        trn: string | null;
+    };
+    currency: "AED";
+    subtotal_fils: number;
+    vat_percent: number;
+    vat_fils: number;
+    total_fils: number;
+    total_aed: string;
+};
+export type TaxCreditNote = ReturnType<typeof taxCreditNote>;
+/** spec/billing.md §5a: the printable copy. */
+export declare function renderTaxCreditNote(d: TaxCreditNote): string;
 /** spec/billing.md §6: a `Stripe-Signature` header checked against the raw body. */
 export declare function stripeSignatureOk(header: string, rawBody: Uint8Array, secret: string, nowSeconds: number, toleranceSeconds?: number): boolean;

package/dist/billing/index.js

@@ -151,6 +151,64 @@ export function renderTaxInvoice(d) {
     ];
     return out.join("\n");
 }
+/** spec/billing.md §5a: a tax credit note. The note that credits what's left of the invoice takes
+ * the rest of its VAT exactly, so the notes never credit more VAT than was invoiced. */
+export function taxCreditNote(input) {
+    const inv = input.invoice;
+    const before = input.credited ?? { subtotal_fils: 0, vat_fils: 0 };
+    const last = input.subtotal_fils === inv.subtotal_fils - before.subtotal_fils;
+    const vat = last
+        ? inv.vat_fils - before.vat_fils
+        : Math.floor((input.subtotal_fils * inv.vat_percent + 50) / 100);
+    return {
+        v: 1,
+        title: "Tax Credit Note",
+        number: input.number,
+        issued_at: input.issued_at,
+        invoice: { number: inv.number, issued_at: inv.issued_at },
+        reason: input.reason,
+        supplier: inv.supplier,
+        customer: inv.customer,
+        currency: "AED",
+        subtotal_fils: input.subtotal_fils,
+        vat_percent: inv.vat_percent,
+        vat_fils: vat,
+        total_fils: input.subtotal_fils + vat,
+        total_aed: formatAed(input.subtotal_fils + vat),
+    };
+}
+/** spec/billing.md §5a: the printable copy. */
+export function renderTaxCreditNote(d) {
+    return [
+        "# Tax Credit Note",
+        "",
+        "| Field | Value |",
+        "|---|---|",
+        `| Credit note number | ${cell(d.number)} |`,
+        `| Date of issue | ${d.issued_at} |`,
+        `| Corrects invoice | ${cell(d.invoice.number)} of ${d.invoice.issued_at} |`,
+        `| Reason | ${cell(oneLine(d.reason))} |`,
+        "",
+        "## Supplier",
+        "",
+        `${oneLine(d.supplier.name)}  `,
+        `${oneLine(d.supplier.address)}  `,
+        `TRN: ${d.supplier.trn}`,
+        "",
+        "## Customer",
+        "",
+        `${oneLine(d.customer.legal_name)}  `,
+        `${oneLine(d.customer.address)}  `,
+        `TRN: ${d.customer.trn ?? "not registered"}`,
+        "",
+        "| Credited | AED |",
+        "|---|---:|",
+        `| Subtotal | ${aed(d.subtotal_fils)} |`,
+        `| VAT ${d.vat_percent}% | ${aed(d.vat_fils)} |`,
+        `| **Total credited** | **${aed(d.total_fils)}** |`,
+        "",
+    ].join("\n");
+}
 // ---------------------------------------------------------------- Stripe webhook signature (§6)
 /** spec/billing.md §6: a `Stripe-Signature` header checked against the raw body. */
 export function stripeSignatureOk(header, rawBody, secret, nowSeconds, toleranceSeconds = 300) {

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { archiveParquet } from "./archive/parquet.ts";
 export { type Attestation, attest, isReadOnly, normalise, parseCommand } from "./attest/index.ts";
 export { type AuthorityFinding, authorityAt, authorityTimeline, automationSurprise, type Mode as AuthorityMode, type Span as AuthoritySpan, } from "./authority/index.ts";
 export { badgeSvg, RECORD_STATES, type RecordState, recordBadge, recordState, } from "./badge/index.ts";
-export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxInvoice, stripeSignatureOk, type TaxInvoice, type TaxInvoiceInput, taxInvoice, } from "./billing/index.ts";
+export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxCreditNote, renderTaxInvoice, stripeSignatureOk, type TaxCreditNote, type TaxCreditNoteInput, type TaxInvoice, type TaxInvoiceInput, taxCreditNote, taxInvoice, } from "./billing/index.ts";
 export { type AgentIdentity, checkAgent, sessionBom } from "./bom/index.ts";
 export { BlackboxApiError, type Client, type ClientOptions, client, type SessionQuery, } from "./client/index.ts";
 export { ART12_MIN_RETENTION_DAYS, type Art12Check, type Art12Report, art12Check, } from "./compliance/art12.ts";
@@ -42,7 +42,7 @@ export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMem
 export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Connector, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, type Statement, } from "./money/index.ts";
 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 { toOtlp } from "./otlp/index.ts";
+export { fromOtlp, type OtlpEvent, toOtlp } from "./otlp/index.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";

package/dist/index.js

@@ -13,7 +13,7 @@ export { archiveParquet } from "./archive/parquet.js";
 export { attest, isReadOnly, normalise, parseCommand } from "./attest/index.js";
 export { authorityAt, authorityTimeline, automationSurprise, } from "./authority/index.js";
 export { badgeSvg, RECORD_STATES, recordBadge, recordState, } from "./badge/index.js";
-export { invoice, loadPlans, renderTaxInvoice, stripeSignatureOk, taxInvoice, } from "./billing/index.js";
+export { invoice, loadPlans, renderTaxCreditNote, renderTaxInvoice, stripeSignatureOk, taxCreditNote, taxInvoice, } from "./billing/index.js";
 export { checkAgent, sessionBom } from "./bom/index.js";
 export { BlackboxApiError, client, } from "./client/index.js";
 export { ART12_MIN_RETENTION_DAYS, art12Check, } from "./compliance/art12.js";
@@ -44,7 +44,7 @@ export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMem
 export { anthropicStatement, baselines, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, } from "./money/index.js";
 export { deadlinesDue, filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
 export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
-export { toOtlp } from "./otlp/index.js";
+export { fromOtlp, toOtlp } from "./otlp/index.js";
 export { checkIdentifier, checkPack, corePack, packData, packFrameworks, } from "./packs/index.js";
 export { policyDelta } from "./policy/delta.js";
 export { policyDrafts } from "./policy/drafts.js";

package/dist/otlp/index.d.ts

@@ -28,4 +28,21 @@ export declare function toOtlp(lines: readonly string[], options?: {
         }[];
     }[];
 };
+/** One event for `POST /v1/sessions/:id/sdk-events`, numbered by the server (spec/sdk.md §1). */
+export interface OtlpEvent {
+    event_id: string;
+    type: string;
+    name: string;
+    ts: string;
+    data: Record<string, unknown>;
+}
+/**
+ * spec/otlp.md §4: OTLP/JSON traces as session events: one per span, typed from its GenAI or
+ * OpenInference attributes, its event_id `otel:<trace>:<span>` so a resent span adds nothing.
+ */
+export declare function fromOtlp(body: unknown): {
+    events: OtlpEvent[];
+} | {
+    error: string;
+};
 export {};

package/dist/otlp/index.js

@@ -398,3 +398,122 @@ function toOtlpV2(lines) {
         ],
     };
 }
+const LLM_OPS = new Set(["chat", "text_completion", "generate_content", "embeddings"]);
+const MAX_SPANS = 5000;
+const MAX_DATA = 60_000;
+function anyValue(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    if (typeof v.stringValue === "string")
+        return v.stringValue;
+    if (typeof v.boolValue === "boolean")
+        return v.boolValue;
+    if (v.intValue !== undefined) {
+        const n = Number(v.intValue);
+        return Number.isSafeInteger(n) ? n : String(v.intValue);
+    }
+    if (typeof v.doubleValue === "number")
+        return v.doubleValue;
+    if (v.arrayValue)
+        return (v.arrayValue.values ?? []).map(anyValue);
+    if (v.kvlistValue)
+        return attributes(v.kvlistValue.values);
+    return null;
+}
+function attributes(list) {
+    const out = {};
+    if (!Array.isArray(list))
+        return out;
+    for (const kv of list)
+        if (typeof kv?.key === "string")
+            out[kv.key] = anyValue(kv.value);
+    return out;
+}
+/** The event type for a span, from GenAI semconv and OpenInference attributes. */
+function spanType(a) {
+    const op = a["gen_ai.operation.name"];
+    const kind = a["openinference.span.kind"];
+    if ((typeof op === "string" && LLM_OPS.has(op)) || kind === "LLM" || kind === "EMBEDDING")
+        return "llm.call";
+    if (op === "execute_tool" || kind === "TOOL")
+        return "tool.call";
+    if (kind === "RETRIEVER")
+        return "retrieval";
+    if (op === "invoke_agent" || op === "create_agent" || kind === "AGENT" || kind === "CHAIN")
+        return "step";
+    return "otel.span";
+}
+const isoOfNanos = (n) => {
+    const s = typeof n === "string" || typeof n === "number" ? String(n) : "";
+    if (!/^[0-9]{1,20}$/.test(s))
+        return "";
+    return new Date(Number(BigInt(s) / 1000000n)).toISOString();
+};
+const size = (o) => new TextEncoder().encode(JSON.stringify(o)).length;
+/**
+ * spec/otlp.md §4: OTLP/JSON traces as session events: one per span, typed from its GenAI or
+ * OpenInference attributes, its event_id `otel:<trace>:<span>` so a resent span adds nothing.
+ */
+export function fromOtlp(body) {
+    const rs = body?.resourceSpans;
+    if (!body || typeof body !== "object" || !Array.isArray(rs))
+        return { error: "not OTLP/JSON traces (no resourceSpans)" };
+    const events = [];
+    for (const r of rs) {
+        const service = attributes(r?.resource?.attributes)["service.name"];
+        const scopes = Array.isArray(r?.scopeSpans) ? r.scopeSpans : [];
+        for (const ss of scopes) {
+            const spans = Array.isArray(ss?.spans) ? ss.spans : [];
+            for (const sp of spans) {
+                const trace = sp?.traceId;
+                const span = sp?.spanId;
+                if (typeof trace !== "string" || !/^[0-9a-f]{32}$/i.test(trace))
+                    return { error: "a span without a 32-hex traceId" };
+                if (typeof span !== "string" || !/^[0-9a-f]{16}$/i.test(span))
+                    return { error: "a span without a 16-hex spanId" };
+                if (events.length === MAX_SPANS)
+                    return { error: `more than ${MAX_SPANS} spans` };
+                const attrs = attributes(sp.attributes);
+                const status = sp.status;
+                const data = {
+                    source: "otlp",
+                    ...(typeof service === "string" ? { service } : {}),
+                    scope: {
+                        name: typeof ss?.scope?.name === "string" ? ss.scope.name : "",
+                        ...(typeof ss?.scope?.version === "string" ? { version: ss.scope.version } : {}),
+                    },
+                    trace_id: trace.toLowerCase(),
+                    span_id: span.toLowerCase(),
+                    ...(typeof sp.parentSpanId === "string" && sp.parentSpanId
+                        ? { parent_span_id: sp.parentSpanId.toLowerCase() }
+                        : {}),
+                    kind: typeof sp.kind === "number" ? sp.kind : 0,
+                    start_unix_nano: String(sp.startTimeUnixNano ?? ""),
+                    end_unix_nano: String(sp.endTimeUnixNano ?? ""),
+                    ...(status && typeof status.code === "number" && status.code !== 0
+                        ? {
+                            status: {
+                                code: status.code,
+                                ...(typeof status.message === "string" ? { message: status.message } : {}),
+                            },
+                        }
+                        : {}),
+                    attributes: attrs,
+                };
+                if (size(data) > MAX_DATA) {
+                    // keep the small attributes (ids, models, counts), drop the long ones (prompts, outputs)
+                    data.attributes = Object.fromEntries(Object.entries(attrs).filter(([, v]) => size(v) <= 1000));
+                    data.truncated = true;
+                }
+                events.push({
+                    event_id: `otel:${trace.toLowerCase()}:${span.toLowerCase()}`,
+                    type: spanType(attrs),
+                    name: typeof sp.name === "string" ? sp.name.slice(0, 256) : "span",
+                    ts: isoOfNanos(sp.startTimeUnixNano),
+                    data,
+                });
+            }
+        }
+    }
+    return { events };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.13.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.11.0";
+export const VERSION = "0.13.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.11.0",
+  "version": "0.13.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",