@zanii/blackbox 0.3.0 → 0.4.0

package/dist/analysis/reference.d.ts

@@ -0,0 +1,49 @@
+import type { Fact } from "./grounding.ts";
+export interface ReferenceFact {
+    id: string;
+    /** Terms that name what the fact is about (`SOFA-221`, `refund`, `استرداد`): one of them must be in
+     * the answer's sentence for the fact to apply. */
+    about: string[];
+    kind: "money" | "percent" | "quantity" | "date" | "text";
+    /** Canonical (`1250.5`, `20261015`); absent for `text`. */
+    value?: string;
+    currency?: string;
+    unit?: string;
+    text?: string;
+    source?: string;
+}
+export interface ReferencePack {
+    id: string;
+    version: string;
+    tenant?: string;
+    title?: string;
+    facts: ReferenceFact[];
+    /** `sha256:` of the pack's RFC 8785 JSON as loaded. */
+    hash: string;
+}
+/** spec/findings.md §10: the packs in a reference file, checked; throws with the first problem. */
+export declare function loadReferencePacks(bytes: Uint8Array): ReferencePack[];
+/** The packs a session's tenant sees: its own, and those for everyone. */
+export declare function packsFor(packs: readonly ReferencePack[], tenant: string | undefined): ReferencePack[];
+export type ReferenceVerdict = {
+    status: "grounded";
+    pack: ReferencePack;
+    fact: ReferenceFact;
+} | {
+    status: "contradicted";
+    pack: ReferencePack;
+    fact: ReferenceFact;
+} | null;
+/**
+ * §10: what the packs say about one fact of an answer. The pack facts that apply are those of the
+ * same kind with an `about` term in the fact's sentence. Grounded when one of them has its value;
+ * contradicted when some apply and none has it; null when none applies.
+ */
+export declare function checkAgainstPacks(text: string, f: Fact, packs: readonly ReferencePack[]): ReferenceVerdict;
+/** §10: the text facts an answer touches (an `about` term anywhere in it), for a grounding service. */
+export declare function referenceContext(text: string, packs: readonly ReferencePack[]): Array<{
+    pack: string;
+    id: string;
+    text: string;
+    source?: string;
+}>;

package/dist/analysis/reference.js

@@ -0,0 +1,164 @@
+// Reference packs (spec/findings.md §10, H4): the facts an organisation owns (prices, fees, rules,
+// deadlines, limits, terms), loaded once and checked against every answer, even when the agent
+// called no tool. Any industry: a pack is data, and a tenant can have its own. Mirrors
+// sdks/python/src/zanii_blackbox/analysis/reference.py; pinned by spec/vectors/reference.json.
+import { createHash } from "node:crypto";
+import { canonical } from "../reconcile/shared.js";
+import { canonicalNumber, normaliseValue, western } from "./hallucination.js";
+const KINDS = new Set(["money", "percent", "quantity", "date", "text"]);
+const NUMERIC = /^[0-9]{1,3}(?:,[0-9]{3})+(?:\.[0-9]+)?$|^[0-9]+(?:\.[0-9]+)?$/;
+const DATE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+const str = (v, max) => typeof v === "string" && v.length >= 1 && v.length <= max;
+/** spec/findings.md §10: the packs in a reference file, checked; throws with the first problem. */
+export function loadReferencePacks(bytes) {
+    let doc;
+    try {
+        doc = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new Error("the reference file isn't JSON");
+    }
+    const packs = doc?.packs;
+    if (!Array.isArray(packs) || packs.length < 1 || packs.length > 100)
+        throw new Error("packs must be a list of 1-100 packs");
+    const ids = new Set();
+    return packs.map((p, i) => {
+        const at = `packs[${i}]`;
+        if (typeof p !== "object" || p === null || Array.isArray(p))
+            throw new Error(`${at} must be an object`);
+        const o = p;
+        if (typeof o.id !== "string" || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(o.id))
+            throw new Error(`${at}.id must be 1-64 of a-z 0-9 -`);
+        const key = `${o.tenant ?? ""}\u0000${o.id}`;
+        if (ids.has(key))
+            throw new Error(`${at}.id ${o.id} is there twice`);
+        ids.add(key);
+        if (!str(o.version, 64))
+            throw new Error(`${at}.version must be 1-64 characters`);
+        if (o.tenant !== undefined && !str(o.tenant, 128))
+            throw new Error(`${at}.tenant must be 1-128 characters`);
+        if (o.title !== undefined && !str(o.title, 200))
+            throw new Error(`${at}.title must be 1-200 characters`);
+        if (!Array.isArray(o.facts) || o.facts.length < 1 || o.facts.length > 10_000)
+            throw new Error(`${at}.facts must be a list of 1-10,000 facts`);
+        const factIds = new Set();
+        const facts = o.facts.map((f, j) => checkFact(f, `${at}.facts[${j}]`, factIds));
+        const pack = {
+            id: o.id,
+            version: o.version,
+            ...(o.tenant !== undefined ? { tenant: o.tenant } : {}),
+            ...(o.title !== undefined ? { title: o.title } : {}),
+            facts,
+        };
+        return {
+            ...pack,
+            hash: `sha256:${createHash("sha256").update(canonical(pack)).digest("hex")}`,
+        };
+    });
+}
+function checkFact(f, at, ids) {
+    if (typeof f !== "object" || f === null || Array.isArray(f))
+        throw new Error(`${at} must be an object`);
+    const o = f;
+    if (typeof o.id !== "string" || !/^[A-Za-z0-9._-]{1,128}$/.test(o.id))
+        throw new Error(`${at}.id must be 1-128 of A-Z a-z 0-9 . _ -`);
+    if (ids.has(o.id))
+        throw new Error(`${at}.id ${o.id} is there twice`);
+    ids.add(o.id);
+    if (!Array.isArray(o.about) ||
+        o.about.length < 1 ||
+        o.about.length > 20 ||
+        !o.about.every((a) => str(a, 100)))
+        throw new Error(`${at}.about must be 1-20 terms of 1-100 characters`);
+    if (typeof o.kind !== "string" || !KINDS.has(o.kind))
+        throw new Error(`${at}.kind must be money, percent, quantity, date or text`);
+    for (const k of ["currency", "unit"])
+        if (o[k] !== undefined && !str(o[k], 32))
+            throw new Error(`${at}.${k} must be 1-32 characters`);
+    if (o.text !== undefined && !str(o.text, 2000))
+        throw new Error(`${at}.text must be 1-2,000 characters`);
+    if (o.source !== undefined && !str(o.source, 500))
+        throw new Error(`${at}.source must be 1-500 characters`);
+    let value;
+    if (o.kind === "text") {
+        if (o.text === undefined)
+            throw new Error(`${at}: a text fact needs text`);
+    }
+    else {
+        const v = typeof o.value === "number" ? String(o.value) : o.value;
+        if (typeof v !== "string")
+            throw new Error(`${at}.value is required`);
+        if (o.kind === "date") {
+            if (!DATE.test(v))
+                throw new Error(`${at}.value must be a date (YYYY-MM-DD)`);
+            value = normaliseValue(v);
+        }
+        else {
+            if (!NUMERIC.test(v))
+                throw new Error(`${at}.value must be a number`);
+            value = canonicalNumber(v);
+        }
+    }
+    return {
+        id: o.id,
+        about: o.about,
+        kind: o.kind,
+        ...(value !== undefined ? { value } : {}),
+        ...(o.currency !== undefined ? { currency: o.currency } : {}),
+        ...(o.unit !== undefined ? { unit: o.unit } : {}),
+        ...(o.text !== undefined ? { text: o.text } : {}),
+        ...(o.source !== undefined ? { source: o.source } : {}),
+    };
+}
+/** The packs a session's tenant sees: its own, and those for everyone. */
+export function packsFor(packs, tenant) {
+    return packs.filter((p) => p.tenant === undefined || p.tenant === tenant);
+}
+const norm = (s) => western(s).toLowerCase();
+/** The sentence around [at, end) in `text`. */
+function sentenceAt(text, at, end) {
+    let a = at;
+    while (a > 0 && !".!?؟\n".includes(text[a - 1]))
+        a--;
+    let b = end;
+    // a decimal point between digits doesn't end a sentence
+    while (b < text.length &&
+        !(".!?؟\n".includes(text[b]) && !/[0-9]/.test(text[b + 1] ?? "")))
+        b++;
+    return text.slice(a, b);
+}
+/**
+ * §10: what the packs say about one fact of an answer. The pack facts that apply are those of the
+ * same kind with an `about` term in the fact's sentence. Grounded when one of them has its value;
+ * contradicted when some apply and none has it; null when none applies.
+ */
+export function checkAgainstPacks(text, f, packs) {
+    if (f.kind !== "money" && f.kind !== "percent" && f.kind !== "quantity" && f.kind !== "date")
+        return null;
+    const sentence = norm(sentenceAt(text, f.at, f.end));
+    let first = null;
+    for (const pack of packs)
+        for (const fact of pack.facts) {
+            if (fact.kind !== f.kind || !fact.about.some((t) => sentence.includes(norm(t))))
+                continue;
+            if (fact.value === f.value)
+                return { status: "grounded", pack, fact };
+            first ??= { pack, fact };
+        }
+    return first ? { status: "contradicted", ...first } : null;
+}
+/** §10: the text facts an answer touches (an `about` term anywhere in it), for a grounding service. */
+export function referenceContext(text, packs) {
+    const t = norm(text);
+    const out = [];
+    for (const pack of packs)
+        for (const fact of pack.facts)
+            if (fact.text !== undefined && fact.about.some((a) => t.includes(norm(a))) && out.length < 50)
+                out.push({
+                    pack: pack.id,
+                    id: fact.id,
+                    text: fact.text,
+                    ...(fact.source ? { source: fact.source } : {}),
+                });
+    return out;
+}

package/dist/analysis/taxonomy.js

@@ -52,6 +52,7 @@ export const TAXONOMY = {
     REVOKED_MEMORY_READ: { owasp: ["ASI06"], atlas: ["AML.T0080.000"] },
     STERILE_VIOLATION: { owasp: ["ASI02", "ASI10"], atlas: ["AML.T0053"] },
     TOKEN_MISUSE: { owasp: ["ASI03"], atlas: ["AML.T0091.000", "AML.T0086"] },
+    TOOL_CHANGED: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },
     TOOL_OUTPUT_MISMATCH: { owasp: ["ASI04", "ASI06"], atlas: ["AML.T0110.002", "AML.T0099"] },
     TOOL_WITNESS_INVALID: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },
 };

package/dist/approvals/index.d.ts

@@ -1,3 +1,7 @@
+import { createConfirmation } from "@zanii/core";
+/** spec/approvals.md §2: what an approval's arguments are, `sha256:<hex>` of their canonical JSON
+ * (keys sorted, no whitespace). The approver sees these; the run must use them. */
+export declare function argsHash(args: unknown): string;
 export interface ApprovalFinding {
     code: "APPROVAL_REJECTED" | "APPROVAL_TIMEOUT";
     source: "approval";
@@ -9,3 +13,22 @@ export interface ApprovalFinding {
 }
 /** spec/approvals.md §3: a refused action (advisory), and one nobody confirmed in time (warning). */
 export declare function approvalFindings(lines: readonly string[]): ApprovalFinding[];
+/**
+ * spec/approvals.md §8: a person's yes as a Zanii action_confirmation, signed with the gateway's
+ * identity: over the hash of the event approved (the held call, or the approval request), at the
+ * decision's time. Deterministic. `error` when there is no approve decision.
+ */
+export declare function approvalConfirmation(lines: readonly string[], approvalId: string, gateway: {
+    did: string;
+    privateKey: Uint8Array;
+}): {
+    confirmation: ReturnType<typeof createConfirmation>;
+    decision_seq: number;
+    action_seq: number;
+    by: unknown;
+    person?: unknown;
+} | {
+    error: "not_found" | "not_approved";
+};
+/** spec/approvals.md §8: Zanii's check of an action_confirmation (the DID it names signed it). */
+export declare const verifyConfirmation: (c: unknown) => boolean;

package/dist/approvals/index.js

@@ -1,5 +1,16 @@
 // The two-person rule (spec/approvals.md): what the approval decisions say. Pure; mirrors
 // sdks/python/src/zanii_blackbox/approvals.py; pinned by spec/vectors/approvals.json.
+import { createHash } from "node:crypto";
+import { createConfirmation, verifyConfirmation as zaniiVerifyConfirmation } from "@zanii/core";
+import { canonical } from "../reconcile/shared.js";
+import { hashLine } from "../verify/envelope.js";
+/** spec/approvals.md §2: what an approval's arguments are, `sha256:<hex>` of their canonical JSON
+ * (keys sorted, no whitespace). The approver sees these; the run must use them. */
+export function argsHash(args) {
+    return `sha256:${createHash("sha256")
+        .update(canonical(args ?? null))
+        .digest("hex")}`;
+}
 /** spec/approvals.md §3: a refused action (advisory), and one nobody confirmed in time (warning). */
 export function approvalFindings(lines) {
     const out = [];
@@ -25,3 +36,40 @@ export function approvalFindings(lines) {
     }
     return out;
 }
+/**
+ * spec/approvals.md §8: a person's yes as a Zanii action_confirmation, signed with the gateway's
+ * identity: over the hash of the event approved (the held call, or the approval request), at the
+ * decision's time. Deterministic. `error` when there is no approve decision.
+ */
+export function approvalConfirmation(lines, approvalId, gateway) {
+    const events = lines.map((l) => JSON.parse(l));
+    const decision = events.find((e) => e.kind === "control" && e.meta.action === "approval" && e.meta.approval_id === approvalId);
+    if (!decision)
+        return { error: "not_found" };
+    if (decision.meta.decision !== "approve")
+        return { error: "not_approved" };
+    const request = events.find((e) => e.kind === "control" &&
+        e.meta.action === "approval_request" &&
+        e.meta.approval_id === approvalId);
+    const actionSeq = typeof decision.meta.call_seq === "number" ? decision.meta.call_seq : (request?.seq ?? -1);
+    const line = lines[actionSeq];
+    if (line === undefined)
+        return { error: "not_found" };
+    const confirmation = createConfirmation({ ownerId: gateway.did, actionHash: hashLine(line), confirmedAt: decision.ts }, gateway.privateKey);
+    return {
+        confirmation,
+        decision_seq: decision.seq,
+        action_seq: actionSeq,
+        by: decision.meta.by,
+        ...(decision.meta.person !== undefined ? { person: decision.meta.person } : {}),
+    };
+}
+/** spec/approvals.md §8: Zanii's check of an action_confirmation (the DID it names signed it). */
+export const verifyConfirmation = (c) => {
+    try {
+        return zaniiVerifyConfirmation(c);
+    }
+    catch {
+        return false;
+    }
+};

package/dist/archive/parquet.d.ts

@@ -0,0 +1,2 @@
+/** The archived events (session lines, in archive order) as one Parquet file. */
+export declare function archiveParquet(lines: readonly string[]): Uint8Array;

package/dist/archive/parquet.js

@@ -0,0 +1,185 @@
+// A session archive as one Parquet file (spec/archive.md §7, L7): the events of the archived sessions
+// as typed columns, for the analytics tools that read Parquet. A minimal writer: one row group, one
+// uncompressed PLAIN page per column, REQUIRED columns, written with Thrift's compact protocol; no
+// dependency. Deterministic, so both SDKs write the same bytes (spec/vectors/parquet.json). The
+// JSONL files stay the record; this is a copy for reading at scale. Mirrors parquet.py.
+import { canonical } from "../reconcile/shared.js";
+const MAGIC = new TextEncoder().encode("PAR1");
+const CREATED_BY = "zanii-blackbox parquet v1";
+// Parquet's enums (parquet.thrift)
+const BYTE_ARRAY = 6;
+const INT64 = 2;
+const REQUIRED = 0;
+const UTF8 = 0;
+const PLAIN = 0;
+const RLE = 3;
+const UNCOMPRESSED = 0;
+const DATA_PAGE = 0;
+// Thrift compact types
+const I32 = 5;
+const I64 = 6;
+const BINARY = 8;
+const LIST = 9;
+const STRUCT = 12;
+const COLUMNS = [
+    ["session_id", BYTE_ARRAY],
+    ["seq", INT64],
+    ["ts", BYTE_ARRAY],
+    ["kind", BYTE_ARRAY],
+    ["body_hash", BYTE_ARRAY],
+    ["meta", BYTE_ARRAY],
+];
+const enc = new TextEncoder();
+const varint = (n) => {
+    const out = [];
+    let v = n;
+    for (;;) {
+        const b = Number(v & 0x7fn);
+        v >>= 7n;
+        if (v)
+            out.push(b | 0x80);
+        else {
+            out.push(b);
+            return out;
+        }
+    }
+};
+const zigzag = (n) => {
+    const v = BigInt(n);
+    return BigInt.asUintN(64, (v << 1n) ^ (v >> 63n));
+};
+const concat = (parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+};
+/** Thrift compact protocol: a struct's fields, in increasing id order. */
+class Struct {
+    parts = [];
+    last = 0;
+    head(fid, type) {
+        const delta = fid - this.last;
+        if (delta > 0 && delta <= 15)
+            this.parts.push([(delta << 4) | type]);
+        else
+            this.parts.push([type], varint(zigzag(fid)));
+        this.last = fid;
+    }
+    i32(fid, v) {
+        this.head(fid, I32);
+        this.parts.push(varint(zigzag(v)));
+        return this;
+    }
+    i64(fid, v) {
+        this.head(fid, I64);
+        this.parts.push(varint(zigzag(v)));
+        return this;
+    }
+    string(fid, v) {
+        const b = enc.encode(v);
+        this.head(fid, BINARY);
+        this.parts.push(varint(BigInt(b.length)), b);
+        return this;
+    }
+    struct(fid, v) {
+        this.head(fid, STRUCT);
+        this.parts.push(v.done());
+        return this;
+    }
+    list(fid, type, items) {
+        this.head(fid, LIST);
+        const n = items.length;
+        this.parts.push(n < 15 ? [(n << 4) | type] : [0xf0 | type, ...varint(BigInt(n))]);
+        this.parts.push(...items);
+        return this;
+    }
+    done() {
+        return concat([...this.parts, [0]]);
+    }
+}
+const i32Item = (v) => new Uint8Array(varint(zigzag(v)));
+const strItem = (v) => {
+    const b = enc.encode(v);
+    return concat([varint(BigInt(b.length)), b]);
+};
+const u32 = (n) => {
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, true);
+    return b;
+};
+function plain(kind, values) {
+    if (kind === INT64) {
+        const b = new Uint8Array(values.length * 8);
+        const view = new DataView(b.buffer);
+        values.forEach((v, i) => {
+            view.setBigInt64(i * 8, BigInt(Number(v)), true);
+        });
+        return b;
+    }
+    return concat(values.flatMap((v) => {
+        const s = enc.encode(String(v));
+        return [u32(s.length), s];
+    }));
+}
+/** The archived events (session lines, in archive order) as one Parquet file. */
+export function archiveParquet(lines) {
+    const rows = lines.map((l) => JSON.parse(l));
+    const values = {
+        session_id: rows.map((r) => r.session_id ?? ""),
+        seq: rows.map((r) => r.seq ?? 0),
+        ts: rows.map((r) => r.ts ?? ""),
+        kind: rows.map((r) => r.kind ?? ""),
+        body_hash: rows.map((r) => r.body_hash ?? ""),
+        meta: rows.map((r) => canonical(r.meta ?? {})),
+    };
+    const parts = [MAGIC];
+    let offset = MAGIC.length;
+    const chunks = [];
+    let total = 0;
+    for (const [name, kind] of COLUMNS) {
+        const data = plain(kind, values[name]);
+        const page = new Struct().i32(1, rows.length).i32(2, PLAIN).i32(3, RLE).i32(4, RLE);
+        const header = new Struct()
+            .i32(1, DATA_PAGE)
+            .i32(2, data.length)
+            .i32(3, data.length)
+            .struct(5, page)
+            .done();
+        const at = offset;
+        parts.push(header, data);
+        const size = header.length + data.length;
+        offset += size;
+        total += size;
+        const meta = new Struct()
+            .i32(1, kind)
+            .list(2, I32, [i32Item(PLAIN), i32Item(RLE)])
+            .list(3, BINARY, [strItem(name)])
+            .i32(4, UNCOMPRESSED)
+            .i64(5, rows.length)
+            .i64(6, size)
+            .i64(7, size)
+            .i64(9, at);
+        chunks.push(new Struct().i64(2, at).struct(3, meta).done());
+    }
+    const schema = [new Struct().string(4, "schema").i32(5, COLUMNS.length).done()];
+    for (const [name, kind] of COLUMNS) {
+        const el = new Struct().i32(1, kind).i32(3, REQUIRED).string(4, name);
+        if (kind === BYTE_ARRAY)
+            el.i32(6, UTF8);
+        schema.push(el.done());
+    }
+    const group = new Struct().list(1, STRUCT, chunks).i64(2, total).i64(3, rows.length).done();
+    const footer = new Struct()
+        .i32(1, 1)
+        .list(2, STRUCT, schema)
+        .i64(3, rows.length)
+        .list(4, STRUCT, [group])
+        .string(6, CREATED_BY)
+        .done();
+    parts.push(footer, u32(footer.length), MAGIC);
+    return concat(parts);
+}

package/dist/badge/index.d.ts

@@ -0,0 +1,16 @@
+/** Zanii's flat badge as an SVG string; every value is escaped. */
+export declare function badgeSvg(o: {
+    message: string;
+    label?: string;
+    color?: string;
+}): string;
+export declare const RECORD_STATES: readonly ["anchored", "verified", "recording", "broken"];
+export type RecordState = (typeof RECORD_STATES)[number];
+/** A session's record as a badge: anchored or verified (green), recording (blue), broken (red). */
+export declare function recordBadge(state: RecordState): string;
+/** The state from what GET /v1/sessions/:id says: the chain, whether it's closed, the anchors. */
+export declare function recordState(o: {
+    ok: boolean;
+    closed: boolean;
+    anchorStatus: string;
+}): RecordState;

package/dist/badge/index.js

@@ -0,0 +1,48 @@
+// Record badges (spec/anchoring.md §11): Zanii's zero-dependency shields-style SVG (@zanii/embed),
+// for a session's record state. Pure; mirrors sdks/python/src/zanii_blackbox/badge.py; pinned by
+// spec/vectors/badge.json.
+const COLORS = {
+    green: "#2ea44f",
+    red: "#d1242f",
+    gray: "#6a737d",
+    blue: "#0969da",
+    black: "#1f2328",
+};
+const ESCAPE = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ESCAPE[c]);
+// ~6.5px a character, so the badge fits its text without font metrics (Zanii's estimate)
+const width = (s) => Math.round([...s].length * 6.5) + 10;
+/** Zanii's flat badge as an SVG string; every value is escaped. */
+export function badgeSvg(o) {
+    const label = o.label ?? "zanii";
+    const fill = COLORS[o.color ?? "green"] ?? o.color ?? COLORS.green;
+    const lw = width(label);
+    const mw = width(o.message);
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${lw + mw}" height="20" role="img" aria-label="${esc(label)}: ${esc(o.message)}">` +
+        `<rect width="${lw}" height="20" fill="#555"/>` +
+        `<rect x="${lw}" width="${mw}" height="20" fill="${esc(String(fill))}"/>` +
+        '<g fill="#fff" font-family="Verdana,DejaVu Sans,sans-serif" font-size="11" text-anchor="middle">' +
+        `<text x="${lw / 2}" y="14">${esc(label)}</text>` +
+        `<text x="${lw + mw / 2}" y="14">${esc(o.message)}</text>` +
+        "</g></svg>");
+}
+export const RECORD_STATES = ["anchored", "verified", "recording", "broken"];
+/** A session's record as a badge: anchored or verified (green), recording (blue), broken (red). */
+export function recordBadge(state) {
+    const color = state === "broken" ? "red" : state === "recording" ? "blue" : "green";
+    return badgeSvg({ label: "blackbox", message: state, color });
+}
+/** The state from what GET /v1/sessions/:id says: the chain, whether it's closed, the anchors. */
+export function recordState(o) {
+    if (!o.ok)
+        return "broken";
+    if (o.anchorStatus === "complete")
+        return "anchored";
+    return o.closed ? "verified" : "recording";
+}

package/dist/bom/index.js

@@ -37,6 +37,13 @@ export function checkAgent(value) {
 const props = (pairs) => pairs
     .filter((p) => typeof p[1] === "string" || typeof p[1] === "number")
     .map(([name, value]) => ({ name, value: String(value) }));
+/** The principal and actor the gateway proved from a delegated token, if any. */
+function verifiedOf(agent) {
+    const v = agent.verified;
+    if (!isObject(v) || typeof v.iss !== "string" || typeof v.sub !== "string")
+        return {};
+    return { principal: `${v.iss}#${v.sub}`, ...(typeof v.act === "string" ? { actor: v.act } : {}) };
+}
 /** A UUID (version 8, RFC 9562) from the record's identity: the same record, the same serial. */
 function serialOf(sessionId, count, head) {
     const h = createHash("sha256").update(`${sessionId}\n${count}\n${head}`).digest();
@@ -119,8 +126,13 @@ export function sessionBom(lines) {
                 properties: props([
                     ["zanii:session_id", sid],
                     ["zanii:workload", agent.workload],
+                    // spec/bom.md §1.2: set by the gateway from a JWT-SVID it checked
+                    ["zanii:workload_verified", workloadProof(agent)],
                     ["zanii:on_behalf_of", agent.on_behalf_of],
                     ["zanii:card_digest", agent.card_digest],
+                    // spec/bom.md §1.1: set by the gateway from a delegated token, never by the opener
+                    ["zanii:verified_principal", verifiedOf(agent).principal],
+                    ["zanii:verified_actor", verifiedOf(agent).actor],
                     ["zanii:record_head", hashLine(last)],
                 ]),
             },
@@ -130,3 +142,11 @@ export function sessionBom(lines) {
         dependencies: [{ ref: "agent", dependsOn: refs }],
     };
 }
+/** spec/bom.md §1.2: `jwt-svid:<trust domain>` when the gateway checked the workload's SVID. */
+function workloadProof(agent) {
+    const v = agent
+        .workload_verified;
+    return typeof v?.method === "string" && typeof v.trust_domain === "string"
+        ? `${v.method}:${v.trust_domain}`
+        : undefined;
+}