@zanii/blackbox 0.21.2 → 0.23.0

package/dist/evals/index.js

@@ -0,0 +1,488 @@
+// Datasets, scorers and eval runs (spec/evals.md §1-§3), prompt versions and experiments (§4-§5).
+// Pure functions: the servers score and compare with them, the CLI builds datasets with them, and
+// spec/vectors/evals.json pins them. Mirrors evals.py.
+import { createHash } from "node:crypto";
+import { schemaProblem } from "../analysis/hallucination.js";
+import { successRange, systemPromptHash } from "../analysis/learning.js";
+import { portableRegexError } from "../policy/index.js";
+import { canonical } from "../reconcile/shared.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+export const SCORERS = [
+    "exact",
+    "contains",
+    "regex",
+    "json_schema",
+    "numeric",
+    "tool_called",
+    "tool_not_called",
+    "findings_absent",
+    "judge",
+];
+export const CASE_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const TOOL = /^[A-Za-z0-9._:/-]{1,128}$/;
+const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+const DECIMAL = /^-?[0-9]+(?:\.[0-9]+)?$/;
+const SESSION_ID = /^ses_[A-Za-z0-9]{16,64}$/;
+const CASE_FIELDS = ["id", "input", "expected", "rubric", "tags", "scorer"];
+const MAX_CASES = 1000;
+const MAX_TEXT = 100_000;
+/** The first number in `v` that isn't a safe integer, as a path, or null (no floats are hashed). */
+function floatAt(v, path) {
+    if (typeof v === "number")
+        return Number.isSafeInteger(v) ? null : path;
+    if (Array.isArray(v)) {
+        for (const [i, x] of v.entries()) {
+            const p = floatAt(x, `${path}[${i}]`);
+            if (p)
+                return p;
+        }
+    }
+    else if (isObj(v))
+        for (const [k, x] of Object.entries(v)) {
+            const p = floatAt(x, `${path}.${k}`);
+            if (p)
+                return p;
+        }
+    return null;
+}
+/** §2: a scorer, checked: the normalised scorer, or what's wrong with it. */
+export function checkScorer(v, at = "scorer") {
+    if (!isObj(v) || !SCORERS.includes(v.kind))
+        return `${at}.kind must be one of ${SCORERS.join(", ")}`;
+    const kind = v.kind;
+    if (kind === "regex") {
+        const p = v.pattern;
+        if (typeof p !== "string" || p.length < 1 || p.length > 500)
+            return `${at}.pattern must be a regular expression of 1-500 characters`;
+        const unportable = portableRegexError(p);
+        if (unportable)
+            return `${at}.pattern uses syntax JavaScript and Python don't share (${unportable})`;
+        try {
+            new RegExp(p);
+        }
+        catch {
+            return `${at}.pattern is not a valid regular expression`;
+        }
+        return { kind, pattern: p };
+    }
+    if (kind === "json_schema") {
+        if (!isObj(v.schema))
+            return `${at}.schema must be a JSON Schema object`;
+        return { kind, schema: v.schema };
+    }
+    if (kind === "numeric") {
+        const t = v.tolerance_milli ?? 0;
+        if (!(typeof t === "number" && Number.isSafeInteger(t) && t >= 0))
+            return `${at}.tolerance_milli must be an integer of at least 0`;
+        return { kind, tolerance_milli: t };
+    }
+    if (kind === "tool_called" || kind === "tool_not_called") {
+        if (typeof v.tool !== "string" || !TOOL.test(v.tool))
+            return `${at}.tool must be a tool name`;
+        return { kind, tool: v.tool };
+    }
+    if (kind === "findings_absent") {
+        const c = v.codes;
+        if (!Array.isArray(c) ||
+            c.length > 50 ||
+            !c.every((x) => typeof x === "string" && CODE.test(x)))
+            return `${at}.codes must be at most 50 finding codes`;
+        return { kind, codes: [...new Set(c)].sort() };
+    }
+    return { kind };
+}
+/**
+ * §1: a dataset, checked: `{name, cases}` with every case normalised (an id, tags, its scorer or
+ * the dataset's), or the first problem. Numbers must be integers: decimals are written as strings.
+ */
+export function checkDataset(v) {
+    if (!isObj(v))
+        return "the dataset must be a JSON object";
+    const name = v.name;
+    if (typeof name !== "string" || name.length < 1 || name.length > 128)
+        return "name must be 1-128 characters";
+    let fallback;
+    if (v.scorer !== undefined) {
+        const float = floatAt(v.scorer, "scorer");
+        if (float)
+            return `${float} is a number that isn't an integer (write decimals as strings)`;
+        const s = checkScorer(v.scorer);
+        if (typeof s === "string")
+            return s;
+        fallback = s;
+    }
+    const raw = v.cases;
+    if (!Array.isArray(raw) || raw.length < 1 || raw.length > MAX_CASES)
+        return `cases must be a list of 1-${MAX_CASES} cases`;
+    const cases = [];
+    const ids = new Set();
+    for (const [i, c] of raw.entries()) {
+        const at = `cases[${i}]`;
+        if (!isObj(c))
+            return `${at} must be an object`;
+        const extra = Object.keys(c).find((k) => !CASE_FIELDS.includes(k));
+        if (extra !== undefined)
+            return `${at}.${extra} is not a case field`;
+        const id = c.id === undefined ? `case-${i + 1}` : c.id;
+        if (typeof id !== "string" || !CASE_ID.test(id))
+            return `${at}.id must be 1-128 of A-Z a-z 0-9 . _ : -`;
+        if (ids.has(id))
+            return `${at}.id repeats "${id}"`;
+        ids.add(id);
+        if (c.input === undefined)
+            return `${at}.input is required`;
+        const float = floatAt(c, at);
+        if (float)
+            return `${float} is a number that isn't an integer (write decimals as strings)`;
+        const expected = c.expected;
+        if (expected !== undefined &&
+            !(typeof expected === "string" && expected.length <= MAX_TEXT) &&
+            typeof expected !== "number")
+            return `${at}.expected must be a string of at most ${MAX_TEXT} characters or an integer`;
+        const rubric = c.rubric;
+        if (rubric !== undefined &&
+            (typeof rubric !== "string" || rubric.length < 1 || rubric.length > 2000))
+            return `${at}.rubric must be 1-2000 characters`;
+        const tags = c.tags === undefined ? [] : c.tags;
+        if (!Array.isArray(tags) ||
+            tags.length > 20 ||
+            !tags.every((t) => typeof t === "string" && t.length >= 1 && t.length <= 64))
+            return `${at}.tags must be at most 20 tags of 1-64 characters`;
+        let scorer = fallback;
+        if (c.scorer !== undefined) {
+            const s = checkScorer(c.scorer, `${at}.scorer`);
+            if (typeof s === "string")
+                return s;
+            scorer = s;
+        }
+        if (!scorer)
+            return `${at}.scorer is required (or give the dataset a scorer)`;
+        if (["exact", "contains", "numeric"].includes(scorer.kind) && expected === undefined)
+            return `${at} needs expected for ${scorer.kind}`;
+        if (scorer.kind === "numeric" &&
+            !(typeof expected === "number" || DECIMAL.test(String(expected))))
+            return `${at}.expected must be a number for numeric (an integer, or a decimal as a string)`;
+        if (scorer.kind === "judge" && rubric === undefined)
+            return `${at} needs a rubric for judge`;
+        cases.push({
+            id,
+            input: c.input,
+            ...(expected !== undefined ? { expected: expected } : {}),
+            ...(rubric !== undefined ? { rubric: rubric } : {}),
+            tags: tags,
+            scorer,
+        });
+    }
+    return { name, cases };
+}
+/** §1: what names a dataset's content exactly: `sha256:` over the canonical JSON of {name, cases}. */
+export function datasetHash(d) {
+    return `sha256:${sha256(canonical({ name: d.name, cases: d.cases }))}`;
+}
+/** §1: a JSON Lines file of cases: one object per non-empty line, or the first line that isn't. */
+export function parseCasesJsonl(text) {
+    const out = [];
+    for (const [i, raw] of text.split("\n").entries()) {
+        const line = raw.replace(/\r$/, "");
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            return `line ${i + 1}: not JSON`;
+        }
+    }
+    return out;
+}
+/** §1: one case per saved scenario (spec/replay.md §3): a fork of the incident, passing when none
+ * of its findings comes back. */
+export function casesFromScenarios(scenarios) {
+    const out = [];
+    for (const [i, s] of scenarios.entries()) {
+        if (!isObj(s) || s.v !== 1 || typeof s.source !== "string" || !SESSION_ID.test(s.source))
+            return `scenarios[${i}] is not a scenario (spec/replay.md §3)`;
+        const expect = isObj(s.expect) && isObj(s.expect.finding_codes) ? s.expect.finding_codes : {};
+        out.push({
+            id: s.source,
+            input: { replay_of: s.source },
+            tags: ["scenario"],
+            scorer: { kind: "findings_absent", codes: Object.keys(expect).sort() },
+        });
+    }
+    return out;
+}
+/** §1: one case per recorded session: a fork of it, expected to answer what it answered then. */
+export function casesFromSessions(items) {
+    return items.map((s) => ({
+        id: s.session_id,
+        input: { replay_of: s.session_id },
+        expected: s.answer,
+        tags: ["session"],
+    }));
+}
+const trimWs = (s) => s.replace(/^[ \t\n\r]+|[ \t\n\r]+$/g, "");
+const NUMBER = /-?[0-9]+(?:,[0-9]{3})*(?:\.[0-9]+)?/;
+const FENCE = /^```[A-Za-z]*\n([\s\S]*?)\n?```$/;
+/** A decimal as integer milli-units, the digits past the third decimal dropped. */
+export function toMilli(s) {
+    const t = s.replace(/,/g, "");
+    const neg = t.startsWith("-");
+    const [whole, frac = ""] = (neg ? t.slice(1) : t).split(".");
+    const v = BigInt(whole) * 1000n + BigInt(`${frac}000`.slice(0, 3));
+    return neg ? -v : v;
+}
+/** §2: one case scored against what its run left. An outage of the judge is never a pass. */
+export function scoreCase(c, o) {
+    const s = c.scorer;
+    const ok = (pass, yes, no) => ({
+        pass,
+        reason: pass ? yes : no,
+    });
+    if (s.kind === "tool_called" || s.kind === "tool_not_called") {
+        const called = (o.tools[s.tool] ?? 0) > 0;
+        const yes = `${s.tool} was called`;
+        const no = `${s.tool} was never called`;
+        return s.kind === "tool_called" ? ok(called, yes, no) : ok(!called, no, yes);
+    }
+    if (s.kind === "findings_absent") {
+        const back = (s.codes ?? []).filter((code) => (o.finding_codes[code] ?? 0) > 0);
+        return ok(back.length === 0, "none of the findings", `recurred: ${back.join(", ")}`);
+    }
+    if (o.answer === null)
+        return { pass: false, reason: "no answer" };
+    if (s.kind === "judge") {
+        if (o.judge === undefined)
+            return { pass: false, reason: "the judge wasn't asked", outage: true };
+        if (o.judge === null)
+            return { pass: false, reason: "the judge didn't answer", outage: true };
+        const failed = o.judge.steps.filter((x) => !x.pass).length;
+        if (!o.judge.steps.length)
+            return { pass: false, reason: "the judge gave no steps" };
+        return ok(failed === 0, "passed every step", `failed ${failed} of ${o.judge.steps.length} steps`);
+    }
+    const answer = trimWs(o.answer);
+    const expected = c.expected === undefined ? "" : String(c.expected);
+    if (s.kind === "exact")
+        return ok(answer === trimWs(expected), "matches", "differs from expected");
+    if (s.kind === "contains")
+        return ok(answer.includes(expected), "contains expected", "doesn't contain expected");
+    if (s.kind === "regex")
+        return ok(new RegExp(s.pattern).test(o.answer), "matches the pattern", "doesn't match the pattern");
+    if (s.kind === "json_schema") {
+        let value;
+        try {
+            value = JSON.parse(FENCE.exec(answer)?.[1] ?? answer);
+        }
+        catch {
+            return { pass: false, reason: "not JSON" };
+        }
+        const problem = schemaProblem(s.schema, value);
+        return ok(problem === null, "matches the schema", `schema: ${problem}`);
+    }
+    // numeric
+    const found = NUMBER.exec(answer)?.[0];
+    if (found === undefined)
+        return { pass: false, reason: "no number in the answer" };
+    const diff = toMilli(found) - toMilli(expected);
+    const off = diff < 0n ? -diff : diff;
+    return ok(off <= BigInt(s.tolerance_milli ?? 0), "within tolerance", `off by ${off} milli`);
+}
+const ppm = (n, d) => (d ? Math.floor((n * 1_000_000) / d) : 0);
+/** §3: a run's totals: passes with the 95% range, outages, cost, and per tag. */
+export function runSummary(results) {
+    const total = results.length;
+    const passed = results.filter((r) => r.pass).length;
+    const cost = results.reduce((n, r) => n + r.cost_micro_usd, 0);
+    const [low, high] = successRange(passed, total);
+    const tags = new Map();
+    for (const r of results)
+        for (const t of new Set(r.tags ?? [])) {
+            const x = tags.get(t) ?? { total: 0, passed: 0 };
+            x.total++;
+            if (r.pass)
+                x.passed++;
+            tags.set(t, x);
+        }
+    return {
+        total,
+        passed,
+        failed: total - passed,
+        outages: results.filter((r) => r.outage === true).length,
+        pass_ppm: ppm(passed, total),
+        pass_low_ppm: low,
+        pass_high_ppm: high,
+        cost_micro_usd: cost,
+        cost_per_case_micro_usd: total ? Math.floor(cost / total) : 0,
+        tags: Object.fromEntries([...tags.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+    };
+}
+/** spec/fleet.md §9's rule: only a difference outside both 95% ranges counts. */
+function versus(now, before) {
+    return now.low > before.high ? "better" : now.high < before.low ? "worse" : "unclear";
+}
+/** §3: run `b` against run `a`: better, worse or unclear, and the cases each fixed or broke. */
+export function compareRuns(a, b) {
+    const before = new Map(a.results.map((r) => [r.case, r.pass]));
+    const fixed = [];
+    const broken = [];
+    for (const r of b.results) {
+        const was = before.get(r.case);
+        if (was === false && r.pass)
+            fixed.push(r.case);
+        if (was === true && !r.pass)
+            broken.push(r.case);
+    }
+    const range = (s) => ({ low: s.pass_low_ppm, high: s.pass_high_ppm });
+    return {
+        a: a.id,
+        b: b.id,
+        same_dataset: a.dataset.hash === b.dataset.hash,
+        verdict: versus(range(b.summary), range(a.summary)),
+        pass_ppm: { a: a.summary.pass_ppm, b: b.summary.pass_ppm },
+        pass_range_ppm: {
+            a: [a.summary.pass_low_ppm, a.summary.pass_high_ppm],
+            b: [b.summary.pass_low_ppm, b.summary.pass_high_ppm],
+        },
+        fixed: fixed.sort(),
+        broken: broken.sort(),
+        cost_per_case_delta_micro_usd: b.summary.cost_per_case_micro_usd - a.summary.cost_per_case_micro_usd,
+    };
+}
+// ---------------------------------------------------------------- prompts and experiments (§4-§5)
+export const PROMPT_NAME = /^[A-Za-z0-9._-]{1,128}$/;
+const ARM_NAME = /^[a-z0-9_-]{1,64}$/;
+/** §4: a prompt text's version hash: the gateway's `system_sha256` of a request whose system
+ * prompt is this text (an Anthropic `system` string, or a Chat Completions system message). */
+export function promptSha256(text) {
+    return systemPromptHash({ system: text });
+}
+/** §5: the arm a session falls in: the first 8 hex of sha256(`<experiment>:<session>`) mod 1000,
+ * walked through the arms' per-mille shares in order. The same session always gets the same arm. */
+export function assignArm(experimentId, sessionId, arms) {
+    const bucket = Number.parseInt(sha256(`${experimentId}:${sessionId}`).slice(0, 8), 16) % 1000;
+    let at = 0;
+    for (const a of arms) {
+        at += a.share_permille;
+        if (bucket < at)
+            return a.name;
+    }
+    return arms[arms.length - 1].name;
+}
+/** §5: an experiment, checked against its prompt's versions: `{name, prompt, arms}`, or why not. */
+export function checkExperiment(v, versions) {
+    if (!isObj(v))
+        return "the experiment must be a JSON object";
+    if (typeof v.name !== "string" || v.name.length < 1 || v.name.length > 128)
+        return "name must be 1-128 characters";
+    if (typeof v.prompt !== "string" || !PROMPT_NAME.test(v.prompt))
+        return "prompt must be a prompt's name";
+    if (!Array.isArray(v.arms) || v.arms.length < 2 || v.arms.length > 10)
+        return "arms must be a list of 2-10 arms";
+    const arms = [];
+    for (const [i, a] of v.arms.entries()) {
+        const at = `arms[${i}]`;
+        if (!isObj(a))
+            return `${at} must be {name, version, share_permille}`;
+        if (typeof a.name !== "string" || !ARM_NAME.test(a.name))
+            return `${at}.name must be 1-64 of a-z 0-9 _ -`;
+        if (arms.some((x) => x.name === a.name))
+            return `${at}.name repeats "${a.name}"`;
+        if (!(typeof a.version === "number" && versions.includes(a.version)))
+            return `${at}.version must be a version of ${v.prompt}`;
+        const share = a.share_permille;
+        if (!(typeof share === "number" && Number.isSafeInteger(share) && share >= 0 && share <= 1000))
+            return `${at}.share_permille must be an integer 0-1000`;
+        arms.push({ name: a.name, version: a.version, share_permille: share });
+    }
+    if (arms.reduce((n, a) => n + a.share_permille, 0) !== 1000)
+        return "the arms' share_permille must add up to 1000";
+    return { name: v.name, prompt: v.prompt, arms };
+}
+/** §4: how a group of runs did: success with the 95% range, spend per run, findings. */
+export function armStats(runs) {
+    const wins = runs.filter((s) => s.outcome === "success").length;
+    const [low, high] = successRange(wins, runs.length);
+    const findings = { advisory: 0, caution: 0, warning: 0 };
+    const codes = {};
+    for (const s of runs) {
+        for (const k of ["advisory", "caution", "warning"])
+            findings[k] += s.findings?.[k] ?? 0;
+        for (const [c, n] of Object.entries(s.finding_codes ?? {}))
+            codes[c] = (codes[c] ?? 0) + n;
+    }
+    return {
+        sessions: runs.length,
+        success: wins,
+        success_ppm: ppm(wins, runs.length),
+        success_low_ppm: low,
+        success_high_ppm: high,
+        spend_per_run_micro_usd: runs.length
+            ? Math.floor(runs.reduce((n, s) => n + s.spend_micro_usd, 0) / runs.length)
+            : 0,
+        findings,
+        finding_codes: Object.fromEntries(Object.keys(codes)
+            .sort()
+            .map((c) => [c, codes[c]])),
+    };
+}
+/**
+ * §4: each version of a prompt, from closed sessions' summaries: the runs that declared it (an
+ * experiment's arm or the SDK's `promptVersion`), and the runs that declared none whose first
+ * request's system prompt hash is the version's. Oldest version first, each against the one before.
+ */
+export function promptResults(summaries, prompt) {
+    let matched = 0;
+    const groups = new Map(prompt.versions.map((v) => [v.version, { declared: [], detected: [] }]));
+    for (const s of summaries) {
+        if (!s.closed)
+            continue;
+        const pv = s.prompt_version;
+        if (pv) {
+            const g = pv.name === prompt.name ? groups.get(pv.version) : undefined;
+            if (g) {
+                g.declared.push(s);
+                matched++;
+            }
+            continue;
+        }
+        const v = prompt.versions.find((x) => x.sha256 === s.version?.prompt);
+        if (v) {
+            groups.get(v.version)?.detected.push(s);
+            matched++;
+        }
+    }
+    const versions = prompt.versions.map((v) => {
+        const g = groups.get(v.version);
+        return {
+            version: v.version,
+            sha256: v.sha256,
+            declared: g.declared.length,
+            detected: g.detected.length,
+            ...armStats([...g.declared, ...g.detected]),
+            vs_previous: null,
+        };
+    });
+    for (let i = 1; i < versions.length; i++) {
+        const [p, v] = [versions[i - 1], versions[i]];
+        v.vs_previous = versus({ low: v.success_low_ppm, high: v.success_high_ppm }, { low: p.success_low_ppm, high: p.success_high_ppm });
+    }
+    return { name: prompt.name, sessions: matched, versions };
+}
+/** §5: each arm of an experiment, from the closed sessions it assigned, against the first arm. */
+export function experimentResults(summaries, experiment) {
+    const mine = summaries.filter((s) => s.closed && s.experiment?.id === experiment.id);
+    const arms = experiment.arms.map((a) => ({
+        name: a.name,
+        version: a.version,
+        share_permille: a.share_permille,
+        ...armStats(mine.filter((s) => s.experiment?.arm === a.name)),
+        vs_control: null,
+    }));
+    const control = arms[0];
+    if (control)
+        for (const a of arms.slice(1))
+            a.vs_control = versus({ low: a.success_low_ppm, high: a.success_high_ppm }, { low: control.success_low_ppm, high: control.success_high_ppm });
+    return { id: experiment.id, sessions: mine.length, arms };
+}

package/dist/evidence/index.d.ts

@@ -1,3 +1,4 @@
+import type { actionsPage } from "../actions/index.ts";
 import type { Bundle, BundleReport } from "../verify/index.ts";
 type Text = {
     en: string;
@@ -7,7 +8,10 @@ export interface EvidencePackOptions {
     generated_at: string;
     bundle_sha256: string;
     proofs: "checked" | "not_checked";
+    /** §7a: an `actionsPage`, when the bodies are at hand: each action with the reasoning before it. */
+    actions?: ActionsPage;
 }
+type ActionsPage = ReturnType<typeof actionsPage>;
 /** spec/investigations.md §7. */
 export declare function evidencePack(bundle: Bundle, report: BundleReport, opts: EvidencePackOptions): {
     v: 1;
@@ -53,6 +57,11 @@ export declare function evidencePack(bundle: Bundle, report: BundleReport, opts:
     reproduce: string[];
     generated_at: string;
     bundle_sha256: string;
+    actions?: {
+        total: number;
+        capped: boolean;
+        actions: import("../actions/index.ts").Action[];
+    };
 };
 export type EvidencePack = ReturnType<typeof evidencePack>;
 /** The Markdown copy (spec/investigations.md §7): `en`, `ar` or `both`. */

package/dist/evidence/index.js

@@ -97,6 +97,7 @@ export function evidencePack(bundle, report, opts) {
         reproduce: REPRODUCE,
         generated_at: opts.generated_at,
         bundle_sha256: opts.bundle_sha256,
+        ...(opts.actions ? { actions: opts.actions } : {}),
     };
 }
 // U+2067 … U+2069 isolate the Arabic paragraphs, so they read right to left in any viewer.
@@ -147,5 +148,54 @@ export function renderEvidencePack(pack, lang = "both") {
         ...pack.reproduce,
         "```",
         "",
+        ...actionsMd(pack.actions, label),
     ].join("\n");
 }
+const KIND = {
+    text: ["the model's own reasoning", "تفكير النموذج نفسه"],
+    summary: ["the provider's summary of it", "ملخّص المزوّد له"],
+    encrypted: ["recorded, but encrypted by the provider", "مسجّل لكنه مشفّر من المزوّد"],
+    none: ["none recorded", "لم يُسجَّل شيء"],
+};
+const quote = (text) => text
+    .split(/\r?\n|\r/)
+    .map((l) => `   > ${l}`)
+    .join("\n") || ">";
+/** Python's json.dumps(…, ensure_ascii=False, sort_keys=True): keys sorted, ", " and ": ". */
+function pyJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map(pyJson).join(", ")}]`;
+    if (v && typeof v === "object")
+        return `{${Object.keys(v)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}: ${pyJson(v[k])}`)
+            .join(", ")}}`;
+    return JSON.stringify(v) ?? "null";
+}
+/** §7a: each action, then the reasoning recorded before it. */
+function actionsMd(page, label) {
+    if (!page)
+        return [];
+    const out = [
+        `## ${label("Actions and the reasoning before each", "الإجراءات والتفكير الذي سبق كلًّا منها")}`,
+        "",
+    ];
+    if (!page.actions.length)
+        out.push(label("No actions recorded.", "لم تُسجَّل أي إجراءات."), "");
+    page.actions.forEach((a, i) => {
+        const all = pyJson(a.args);
+        const points = Array.from(all);
+        const args = points.length <= 300 ? all : `${points.slice(0, 300).join("")}…`;
+        const [en, ar] = KIND[a.reasoning.kind] ?? KIND.none;
+        out.push(`${i + 1}. **\`${a.tool}\`** · ${label("event", "الحدث")} ${a.seq} · \`${args}\``, "", `   ${label("Reasoning", "التفكير")}: ${label(en, ar)}`, "");
+        if (a.reasoning.text)
+            out.push(quote(a.reasoning.text), "");
+        if (a.said)
+            out.push(`   ${label("It wrote", "كتب")}:`, "", quote(a.said), "");
+    });
+    if (page.capped) {
+        const n = page.actions.length;
+        out.push(label(`The first ${n} of ${page.total} actions.`, `أول ${n} من أصل ${page.total} إجراءات.`), "");
+    }
+    return out;
+}

package/dist/federation/index.d.ts

@@ -8,6 +8,15 @@ export declare function cosignLedgerSth(sth: SignedTreeHead, o: {
     witnessed_log_id: string;
     cosignature: SignedTreeHead;
 };
+/** spec/anchoring.md §15: `cosignLedgerSth` with a key held outside the process. */
+export declare function cosignLedgerSthWith(sth: SignedTreeHead, o: {
+    did: string;
+    sign: (message: Uint8Array) => Promise<Uint8Array>;
+}): Promise<{
+    v: number;
+    witnessed_log_id: string;
+    cosignature: SignedTreeHead;
+}>;
 /** Zanii's check: a valid co-signature over the same (size, root) of a valid tree head. */
 export declare function verifyLedgerCosignature(c: unknown, sth: SignedTreeHead): boolean;
 /** Zanii's equivocation proof: one log key, one size, two roots. Throws unless it really is one. */

package/dist/federation/index.js

@@ -2,7 +2,7 @@
 // co-signs the ledger's signed tree heads it checked, and gossip that turns a split view into an
 // equivocation proof (@zanii/witness, @zanii/federation). Pure; mirrors
 // sdks/python/src/zanii_blackbox/federation.py; pinned by spec/vectors/federation.json.
-import { createSTH, verifySTH } from "@zanii/core";
+import { createSTH, createSTHAsync, verifySTH } from "@zanii/core";
 const valid = (sth) => {
     try {
         return typeof sth === "object" && sth !== null && verifySTH(sth);
@@ -18,6 +18,13 @@ export function cosignLedgerSth(sth, o) {
     const cosignature = createSTH({ logId: o.did, size: sth.size, root: sth.root, ts: sth.ts }, o.privateKey);
     return { v: 1, witnessed_log_id: sth.log_id, cosignature };
 }
+/** spec/anchoring.md §15: `cosignLedgerSth` with a key held outside the process. */
+export async function cosignLedgerSthWith(sth, o) {
+    if (!valid(sth))
+        throw new Error("refusing to co-sign: the signed tree head doesn't verify");
+    const cosignature = await createSTHAsync({ logId: o.did, size: sth.size, root: sth.root, ts: sth.ts }, o.sign);
+    return { v: 1, witnessed_log_id: sth.log_id, cosignature };
+}
 /** Zanii's check: a valid co-signature over the same (size, root) of a valid tree head. */
 export function verifyLedgerCosignature(c, sth) {
     const p = (c ?? {});

package/dist/finance/index.js

@@ -3,6 +3,7 @@
 // (@zanii/kyb), and the findings over them. Pure; mirrors sdks/python/src/zanii_blackbox/finance.py;
 // pinned by spec/vectors/finance.json.
 import { canonicalBytes, publicKeyFromDid } from "@zanii/core";
+import { envelopesOf } from "../reconcile/record.js";
 import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
 /** Minor-unit precision: Zanii's table, plus the Gulf's currencies. */
 export const CURRENCIES = {
@@ -219,8 +220,7 @@ export function financeFindings(lines, bodies, closing = false) {
     const screened = new Map();
     const prepared = [];
     const handedOff = new Set();
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    for (const e of envelopesOf(lines)) {
         if (e.kind === "session.close")
             closed = true;
         if (e.kind !== "sdk.event")
@@ -287,8 +287,7 @@ export function financeFindings(lines, bodies, closing = false) {
 export function paymentsOf(lines, bodies) {
     const payments = [];
     const totals = new Map();
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    for (const e of envelopesOf(lines)) {
         if (e.kind !== "sdk.event" || e.meta.type !== "payment")
             continue;
         const body = bodies(e.body_hash);