@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/undo/index.d.ts

@@ -0,0 +1,45 @@
+export interface Compensation {
+    tool: string;
+    undo: {
+        tool: string;
+        args?: Record<string, unknown>;
+    } | null;
+}
+export type UndoStatus = "ready" | "irreversible" | "manual" | "undone";
+export interface UndoStep {
+    seq: number;
+    tool: string;
+    via: string;
+    undo: {
+        tool: string;
+        args: Record<string, unknown>;
+    } | null;
+    status: UndoStatus;
+    reason?: string;
+}
+export interface UndoFinding {
+    code: "UNDO_FAILED";
+    source: "undo";
+    severity: "warning";
+    ref: {
+        seq: number;
+        undo_of: number;
+    };
+}
+type Bodies = (hash: string) => Uint8Array | undefined;
+/** spec/undo.md §2: newest first, the order to reverse them in. */
+export declare function undoPlan(lines: readonly string[], bodies: Bodies, compensations: readonly Compensation[]): UndoStep[];
+/** spec/undo.md §3: an undo that the gateway ran and that failed. */
+export declare function undoFindings(lines: readonly string[], bodies: Bodies): UndoFinding[];
+/** Checks a policy file's `compensations` (spec/undo.md §1); throws on anything invalid. */
+export declare function checkCompensations(value: unknown): Compensation[];
+/** spec/undo.md §3: runs the `ready` steps that are the agent's own tools (`via: "sdk"`), newest
+ * first, each with the handler named after its undo tool; each is recorded with `undo_of`. Steps
+ * it can't run come back unchanged. Never throws: a failed handler is recorded and reported. */
+export declare function runUndo(steps: readonly UndoStep[], handlers: Record<string, (args: Record<string, unknown>) => unknown>, session: {
+    event(type: string, name?: string, data?: Record<string, unknown>): void;
+}): Promise<Array<UndoStep & {
+    outcome?: "done" | "failed";
+    error?: string;
+}>>;
+export {};

package/dist/undo/index.js

@@ -0,0 +1,212 @@
+// Undo (spec/undo.md): the completed risky actions of a session, newest first, each with the call
+// that reverses it. Pure; mirrors sdks/python/src/zanii_blackbox/undo.py; pinned by
+// spec/vectors/undo.json.
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const glob = (pattern) => new RegExp(`^${pattern.split("*").map(escapeRe).join(".*")}$`);
+const REDACTED = /\[REDACTED:[a-z_]+\]/;
+function bodyJson(bodies, hash) {
+    const bytes = bodies(hash);
+    if (!bytes)
+        return undefined;
+    const text = new TextDecoder().decode(bytes);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // an SSE-framed message: the first data line that parses
+        for (const line of text.split("\n"))
+            if (line.startsWith("data:"))
+                try {
+                    return JSON.parse(line.slice(5).trim());
+                }
+                catch { }
+        return undefined;
+    }
+}
+/** `$args.a.0.b` / `$result.x` against the original call; undefined when the path isn't there. */
+function resolve(value, args, result) {
+    if (typeof value !== "string")
+        return value;
+    const m = /^\$(args|result)\.(.+)$/.exec(value);
+    if (!m)
+        return value;
+    let at = m[1] === "args" ? args : result;
+    for (const key of m[2].split(".")) {
+        if (at === null || typeof at !== "object")
+            return undefined;
+        at = at[Array.isArray(at) ? Number(key) : key];
+    }
+    return at;
+}
+/** Completed, successful tool calls (not policy-denied, not undos), and the seqs already undone. */
+function callsOf(lines, bodies) {
+    const events = lines.map((l) => JSON.parse(l));
+    const calls = [];
+    const undone = new Set();
+    const results = new Map();
+    for (const e of events)
+        if (e.kind === "tool.result" && typeof e.meta.call_seq === "number")
+            results.set(e.meta.call_seq, e);
+    const sdkResults = events.filter((e) => e.kind === "sdk.event" && e.meta.type === "tool.result");
+    const usedResults = new Set();
+    for (const e of events) {
+        if (e.kind === "tool.call" &&
+            e.meta.method === "tools/call" &&
+            typeof e.meta.tool === "string") {
+            // A denied call never ran; a held one that was approved did (spec/approvals.md).
+            if (e.meta.policy?.action === "deny")
+                continue;
+            const r = results.get(e.seq);
+            const res = r
+                ? bodyJson(bodies, r.body_hash)
+                : undefined;
+            const succeeded = !!res && res.error === undefined && res.result?.isError !== true;
+            if (typeof e.meta.undo_of === "number") {
+                if (succeeded)
+                    undone.add(e.meta.undo_of); // a failed undo leaves the step to retry
+                continue;
+            }
+            if (!res || !succeeded)
+                continue;
+            const req = bodyJson(bodies, e.body_hash);
+            const server = String(e.meta.server);
+            calls.push({
+                seq: e.seq,
+                tool: `mcp__${server}__${e.meta.tool}`,
+                names: [`mcp__${server}__${e.meta.tool}`, e.meta.tool],
+                via: `mcp:${server}`,
+                args: req?.params?.arguments ?? {},
+                result: res.result,
+            });
+        }
+        else if (e.kind === "sdk.event" &&
+            e.meta.type === "tool.call" &&
+            typeof e.meta.name === "string") {
+            const data = bodyJson(bodies, e.body_hash);
+            const r = sdkResults.find((x) => x.seq > e.seq && x.meta.name === e.meta.name && !usedResults.has(x.seq));
+            if (r)
+                usedResults.add(r.seq);
+            const res = r ? bodyJson(bodies, r.body_hash) : undefined;
+            if (typeof data?.undo_of === "number") {
+                if (r && res?.ok !== false)
+                    undone.add(data.undo_of); // a failed undo leaves it to retry
+                continue;
+            }
+            if (!r || res?.ok === false)
+                continue;
+            calls.push({
+                seq: e.seq,
+                tool: e.meta.name,
+                names: [e.meta.name],
+                via: "sdk",
+                args: data?.args ?? {},
+                result: res ?? {},
+            });
+        }
+    }
+    return { calls, undone };
+}
+/** spec/undo.md §2: newest first, the order to reverse them in. */
+export function undoPlan(lines, bodies, compensations) {
+    const matchers = compensations.map((c) => ({ c, re: glob(c.tool) }));
+    const { calls, undone } = callsOf(lines, bodies);
+    const steps = [];
+    for (const call of calls) {
+        const hit = matchers.find((m) => call.names.some((n) => m.re.test(n)));
+        if (!hit)
+            continue;
+        const base = { seq: call.seq, tool: call.tool, via: call.via };
+        if (hit.c.undo === null) {
+            steps.push({ ...base, undo: null, status: undone.has(call.seq) ? "undone" : "irreversible" });
+            continue;
+        }
+        const args = {};
+        let reason;
+        for (const [k, v] of Object.entries(hit.c.undo.args ?? {})) {
+            const value = resolve(v, call.args, call.result);
+            if (value === undefined)
+                reason ??= `${String(v)} isn't in the record`;
+            else if (REDACTED.test(JSON.stringify(value)))
+                reason ??= `${k} was redacted in the record`;
+            else
+                args[k] = value;
+        }
+        const undo = { tool: hit.c.undo.tool, args };
+        if (undone.has(call.seq))
+            steps.push({ ...base, undo, status: "undone" });
+        else if (reason)
+            steps.push({ ...base, undo, status: "manual", reason });
+        else
+            steps.push({ ...base, undo, status: "ready" });
+    }
+    return steps.sort((a, b) => b.seq - a.seq);
+}
+/** spec/undo.md §3: an undo that the gateway ran and that failed. */
+export function undoFindings(lines, bodies) {
+    const out = [];
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind !== "tool.result" || typeof e.meta.undo_of !== "number")
+            continue;
+        const res = bodyJson(bodies, e.body_hash);
+        if (!res || res.error !== undefined || res.result?.isError === true)
+            out.push({
+                code: "UNDO_FAILED",
+                source: "undo",
+                severity: "warning",
+                ref: { seq: e.seq, undo_of: e.meta.undo_of },
+            });
+    }
+    return out;
+}
+/** Checks a policy file's `compensations` (spec/undo.md §1); throws on anything invalid. */
+export function checkCompensations(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("policy: compensations must be a list");
+    for (const [i, c] of value.entries()) {
+        const x = c;
+        if (typeof x.tool !== "string" || x.tool === "")
+            throw new Error(`policy: compensations[${i}].tool is required`);
+        if (x.undo === null)
+            continue;
+        const u = x.undo;
+        if (!u || typeof u !== "object" || typeof u.tool !== "string" || u.tool === "")
+            throw new Error(`policy: compensations[${i}].undo must be null or {tool, args?}`);
+        if (u.args !== undefined &&
+            (typeof u.args !== "object" || u.args === null || Array.isArray(u.args)))
+            throw new Error(`policy: compensations[${i}].undo.args must be an object`);
+    }
+    return value;
+}
+/** spec/undo.md §3: runs the `ready` steps that are the agent's own tools (`via: "sdk"`), newest
+ * first, each with the handler named after its undo tool; each is recorded with `undo_of`. Steps
+ * it can't run come back unchanged. Never throws: a failed handler is recorded and reported. */
+export async function runUndo(steps, handlers, session) {
+    const out = [];
+    for (const step of steps) {
+        const handler = step.undo ? handlers[step.undo.tool] : undefined;
+        if (step.status !== "ready" || step.via !== "sdk" || !step.undo || !handler) {
+            out.push(step);
+            continue;
+        }
+        const { tool, args } = step.undo;
+        session.event("tool.call", tool, { args, undo_of: step.seq });
+        try {
+            await handler(args);
+            session.event("tool.result", tool, { ok: true, undo_of: step.seq });
+            out.push({ ...step, outcome: "done" });
+        }
+        catch (error) {
+            const text = error instanceof Error ? error.message : String(error);
+            session.event("tool.result", tool, {
+                ok: false,
+                error: text.slice(0, 500),
+                undo_of: step.seq,
+            });
+            out.push({ ...step, outcome: "failed", error: text });
+        }
+    }
+    return out;
+}

package/dist/verify/anchor.d.ts

@@ -0,0 +1,54 @@
+import { fetchAndVerifyProof } from "@zanii/sdk";
+import { type VerifyResult } from "./chain.ts";
+export declare const ANCHOR_TARGET = "blackbox.anchor";
+/** The anchor payload text A: canonical JSON of {count, head, session_id} (always ASCII). */
+export declare function anchorPayload(sessionId: string, count: number, head: string): string;
+/**
+ * The bytes the Zanii SDKs hash when A is recorded as a string payload: its JSON string literal.
+ * (Object payloads serialise differently in the TypeScript and Python SDKs; a string does not.)
+ */
+export declare function anchorPayloadBytes(sessionId: string, count: number, head: string): string;
+export interface BundleAnchor {
+    count: number;
+    head: string;
+    receipt_hash: string;
+    nonce: string;
+    anchored_at: string;
+}
+export interface Bundle {
+    v: 1;
+    session: {
+        session_id: string;
+        final_count: number | null;
+        [key: string]: unknown;
+    };
+    ledger_url: string | null;
+    anchored_by: string | null;
+    lines: string[];
+    anchors: BundleAnchor[];
+}
+export interface BundleReport {
+    ok: boolean;
+    chain: VerifyResult;
+    /** anchored_by matches the identity pinned in session.open. */
+    identity: {
+        ok: boolean;
+        message?: string;
+    };
+    /** One entry per anchor when proofs were checked; null when they weren't. */
+    proofs: Array<{
+        receipt_hash: string;
+        ok: boolean;
+        problems: string[];
+    }> | null;
+}
+/**
+ * Verifies an audit bundle: the chain against its anchors and final count, the pinned identity, and,
+ * with `proofs: true`, every anchor's receipt on the ledger (network).
+ */
+export declare function verifyBundle(bundle: Bundle, options?: {
+    proofs?: boolean;
+    fetchImpl?: Parameters<typeof fetchAndVerifyProof>[2];
+    /** Audit K3: looks up a body by hash (a bodies folder); the bytes are checked against it. */
+    body?: (bodyHash: string) => Uint8Array | undefined;
+}): Promise<BundleReport>;

package/dist/verify/anchor.js

@@ -0,0 +1,77 @@
+// Anchors and audit bundles (spec/anchoring.md). Mirrors sdks/python/src/zanii_blackbox/verify/anchor.py.
+import { canonicalBytes } from "@zanii/core";
+import { fetchAndVerifyProof, verifyPayload } from "@zanii/sdk";
+import { verifyChain } from "./chain.js";
+export const ANCHOR_TARGET = "blackbox.anchor";
+/** The anchor payload text A: canonical JSON of {count, head, session_id} (always ASCII). */
+export function anchorPayload(sessionId, count, head) {
+    return new TextDecoder().decode(canonicalBytes({ count, head, session_id: sessionId }));
+}
+/**
+ * The bytes the Zanii SDKs hash when A is recorded as a string payload: its JSON string literal.
+ * (Object payloads serialise differently in the TypeScript and Python SDKs; a string does not.)
+ */
+export function anchorPayloadBytes(sessionId, count, head) {
+    return JSON.stringify(anchorPayload(sessionId, count, head));
+}
+/**
+ * Verifies an audit bundle: the chain against its anchors and final count, the pinned identity, and,
+ * with `proofs: true`, every anchor's receipt on the ledger (network).
+ */
+export async function verifyBundle(bundle, options = {}) {
+    const chain = verifyChain(bundle.lines, {
+        sessionId: bundle.session.session_id,
+        ...(options.body ? { body: options.body } : {}),
+        anchors: bundle.anchors,
+        ...(bundle.session.final_count === null ? {} : { count: bundle.session.final_count }),
+    });
+    let pinned;
+    try {
+        pinned = JSON.parse(bundle.lines[0] ?? "{}").meta
+            ?.anchored_by;
+    }
+    catch {
+        pinned = undefined;
+    }
+    const identity = bundle.anchors.length === 0 && bundle.anchored_by === null
+        ? { ok: true }
+        : pinned === bundle.anchored_by && typeof pinned === "string"
+            ? { ok: true }
+            : { ok: false, message: "anchored_by does not match the identity pinned in session.open" };
+    let proofs = null;
+    if (options.proofs) {
+        proofs = [];
+        for (const a of bundle.anchors) {
+            const problems = [];
+            if (!bundle.ledger_url)
+                problems.push("no ledger_url in the bundle");
+            else {
+                const proof = await fetchAndVerifyProof(bundle.ledger_url, a.receipt_hash, options.fetchImpl);
+                if (!proof.ok)
+                    problems.push(`ledger proof failed: ${proof.checks
+                        .filter((c) => !c.ok)
+                        .map((c) => c.label)
+                        .join(", ")}`);
+                const r = proof.receipt;
+                if (!r)
+                    problems.push("no receipt in the proof");
+                else {
+                    if (r.agent_id !== bundle.anchored_by)
+                        problems.push("receipt was not signed by the pinned gateway identity");
+                    if (r.target !== ANCHOR_TARGET)
+                        problems.push(`receipt target is ${r.target}, not ${ANCHOR_TARGET}`);
+                    if (!verifyPayload(anchorPayloadBytes(bundle.session.session_id, a.count, a.head), a.nonce, r.payload_hash)) {
+                        problems.push("receipt payload does not commit to this (count, head)");
+                    }
+                }
+            }
+            proofs.push({ receipt_hash: a.receipt_hash, ok: problems.length === 0, problems });
+        }
+    }
+    return {
+        ok: chain.ok && identity.ok && (proofs === null || proofs.every((p) => p.ok)),
+        chain,
+        identity,
+        proofs,
+    };
+}

package/dist/verify/chain.d.ts

@@ -0,0 +1,27 @@
+export type FailureCode = "NOT_JSON" | "NON_CANONICAL" | "BAD_NUMBER" | "SCHEMA" | "WRONG_SESSION" | "SEQ_GAP" | "BROKEN_LINK" | "BODY_MISMATCH" | "COUNT_MISMATCH" | "HEAD_MISMATCH" | "ANCHOR_TRUNCATED" | "ANCHOR_MISMATCH";
+export type VerifyResult = {
+    ok: true;
+    count: number;
+    head: string;
+} | {
+    ok: false;
+    code: FailureCode;
+    index: number;
+    message: string;
+};
+export interface VerifyOptions {
+    /** Expected session; defaults to the first line's session_id. */
+    sessionId?: string;
+    /** Looks up a body by hash. When it returns bytes, they are checked against body_hash. */
+    body?: (bodyHash: string) => Uint8Array | undefined;
+    /** Expected number of events (from session.close or an anchor). Detects truncation. */
+    count?: number;
+    /** Expected last event_hash (from an anchor). */
+    head?: string;
+    /** Published (count, head) anchors that the chain must still match (spec/anchoring.md §3). */
+    anchors?: ReadonlyArray<{
+        count: number;
+        head: string;
+    }>;
+}
+export declare function verifyChain(lines: readonly string[], options?: VerifyOptions): VerifyResult;

package/dist/verify/chain.js

@@ -0,0 +1,105 @@
+// Chain verification (spec/chain.md). Mirrors sdks/python/src/zanii_blackbox/verify/chain.py.
+// Never throws on bad input: every problem is reported as a failure code.
+import { canonicalBytes } from "@zanii/core";
+import { EVENT_KINDS, GENESIS, hashBody, hashLine } from "./envelope.js";
+const HASH = /^sha256:[0-9a-f]{64}$/;
+const SESSION = /^ses_[A-Za-z0-9]{16,64}$/;
+const TS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/;
+const KINDS = new Set(EVENT_KINDS);
+export function verifyChain(lines, options = {}) {
+    let prev = GENESIS;
+    const hashes = [];
+    let session = options.sessionId;
+    const fail = (code, index, message) => ({
+        ok: false,
+        code,
+        index,
+        message,
+    });
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const parsed = parseStrict(line);
+        if (parsed.error === "NOT_JSON")
+            return fail("NOT_JSON", i, "line is not valid JSON");
+        if (parsed.error === "BAD_NUMBER")
+            return fail("BAD_NUMBER", i, `number ${parsed.token} is not a safe integer literal`);
+        const env = parsed.value;
+        if (new TextDecoder().decode(canonicalBytes(env)) !== line)
+            return fail("NON_CANONICAL", i, "line is not in canonical form");
+        if (env === null || typeof env !== "object" || Array.isArray(env))
+            return fail("SCHEMA", i, "line is not a JSON object");
+        const schemaError = checkSchema(env);
+        if (schemaError)
+            return fail("SCHEMA", i, schemaError);
+        session ??= env.session_id;
+        if (env.session_id !== session)
+            return fail("WRONG_SESSION", i, `session_id ${env.session_id} ≠ ${session}`);
+        if (env.seq !== i)
+            return fail("SEQ_GAP", i, `expected seq ${i}, found ${env.seq}`);
+        if (env.prev !== prev)
+            return fail("BROKEN_LINK", i, "prev does not match the previous event_hash");
+        const body = options.body?.(env.body_hash);
+        if (body !== undefined && hashBody(body) !== env.body_hash)
+            return fail("BODY_MISMATCH", i, "body bytes do not match body_hash");
+        prev = hashLine(line);
+        hashes.push(prev);
+    }
+    if (options.count !== undefined && options.count !== lines.length) {
+        return fail("COUNT_MISMATCH", lines.length, `expected ${options.count} events, found ${lines.length}`);
+    }
+    if (options.head !== undefined && options.head !== prev)
+        return fail("HEAD_MISMATCH", lines.length, "head does not match the expected head");
+    for (const a of options.anchors ?? []) {
+        if (a.count > lines.length) {
+            return fail("ANCHOR_TRUNCATED", lines.length, `anchored ${a.count} events, found ${lines.length}`);
+        }
+        if (a.count < 1 || hashes[a.count - 1] !== a.head) {
+            return fail("ANCHOR_MISMATCH", Math.max(0, a.count - 1), `event ${a.count - 1} does not match its anchor`);
+        }
+    }
+    return { ok: true, count: lines.length, head: prev };
+}
+const INTEGER_LITERAL = /^-?(0|[1-9][0-9]*)$/;
+// JSON.parse only gives us the parsed value, where 1.0 and 1 look identical. The reviver's
+// `context.source` (Node 22+) exposes each number token exactly as written.
+function parseStrict(line) {
+    let badToken;
+    let value;
+    try {
+        value = JSON.parse(line, (_key, v, context) => {
+            if (typeof v === "number" && badToken === undefined) {
+                const source = context?.source ?? String(v);
+                if (!INTEGER_LITERAL.test(source) || !Number.isSafeInteger(v))
+                    badToken = source;
+            }
+            return v;
+        });
+    }
+    catch {
+        return { error: "NOT_JSON" };
+    }
+    return badToken === undefined ? { value } : { error: "BAD_NUMBER", token: badToken };
+}
+function checkSchema(env) {
+    const allowed = new Set(["v", "session_id", "seq", "ts", "kind", "prev", "body_hash", "meta"]);
+    for (const key of Object.keys(env))
+        if (!allowed.has(key))
+            return `unexpected field ${key}`;
+    if (env.v !== 1)
+        return "v must be 1";
+    if (typeof env.session_id !== "string" || !SESSION.test(env.session_id))
+        return "bad session_id";
+    if (typeof env.seq !== "number" || env.seq < 0)
+        return "bad seq";
+    if (typeof env.ts !== "string" || !TS.test(env.ts))
+        return "bad ts";
+    if (typeof env.kind !== "string" || !KINDS.has(env.kind))
+        return "bad kind";
+    if (typeof env.prev !== "string" || (env.prev !== GENESIS && !HASH.test(env.prev)))
+        return "bad prev";
+    if (typeof env.body_hash !== "string" || !HASH.test(env.body_hash))
+        return "bad body_hash";
+    if (env.meta === null || typeof env.meta !== "object" || Array.isArray(env.meta))
+        return "meta must be an object";
+    return undefined;
+}

package/dist/verify/envelope.d.ts

@@ -0,0 +1,28 @@
+export declare const GENESIS = "genesis";
+export declare const EVENT_KINDS: readonly ["session.open", "session.close", "session.lost_contact", "llm.request", "llm.chunk", "llm.response", "llm.incomplete", "tool.call", "tool.result", "tool.notification", "workspace.receipt", "sdk.event", "control", "outcome", "finding", "capture.gap"];
+export type EventKind = (typeof EVENT_KINDS)[number];
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface Envelope {
+    v: 1;
+    session_id: string;
+    seq: number;
+    ts: string;
+    kind: EventKind;
+    prev: string;
+    body_hash: string;
+    meta: {
+        [key: string]: Json;
+    };
+}
+export declare class EncodingError extends Error {
+}
+/** Throws EncodingError if any number in `value` is a float or outside the safe-integer range. */
+export declare function assertSafeIntegers(value: unknown, path?: string): void;
+/** The stored form of an event: RFC 8785 canonical JSON. */
+export declare function encodeEnvelope(envelope: Envelope): string;
+/** `sha256:<hex>` of a line's UTF-8 bytes. For a canonical line this equals `jcsHash(envelope)`. */
+export declare function hashLine(line: string): string;
+/** `sha256:<hex>` of the exact body bytes. */
+export declare function hashBody(body: Uint8Array): string;

package/dist/verify/envelope.js

@@ -0,0 +1,55 @@
+// Event envelope encoding (spec/chain.md). Mirrors sdks/python/src/zanii_blackbox/verify/envelope.py.
+import { createHash } from "node:crypto";
+import { canonicalBytes } from "@zanii/core";
+export const GENESIS = "genesis";
+export const EVENT_KINDS = [
+    "session.open",
+    "session.close",
+    "session.lost_contact",
+    "llm.request",
+    "llm.chunk",
+    "llm.response",
+    "llm.incomplete",
+    "tool.call",
+    "tool.result",
+    "tool.notification",
+    "workspace.receipt",
+    "sdk.event",
+    "control",
+    "outcome",
+    "finding",
+    "capture.gap",
+];
+export class EncodingError extends Error {
+}
+/** Throws EncodingError if any number in `value` is a float or outside the safe-integer range. */
+export function assertSafeIntegers(value, path = "$") {
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value))
+            throw new EncodingError(`${path}: ${value} is not a safe integer`);
+    }
+    else if (Array.isArray(value)) {
+        for (const [i, v] of value.entries())
+            assertSafeIntegers(v, `${path}[${i}]`);
+    }
+    else if (value !== null && typeof value === "object") {
+        for (const [k, v] of Object.entries(value))
+            assertSafeIntegers(v, `${path}.${k}`);
+    }
+}
+/** The stored form of an event: RFC 8785 canonical JSON. */
+export function encodeEnvelope(envelope) {
+    assertSafeIntegers(envelope);
+    return new TextDecoder().decode(canonicalBytes(envelope));
+}
+/** `sha256:<hex>` of a line's UTF-8 bytes. For a canonical line this equals `jcsHash(envelope)`. */
+export function hashLine(line) {
+    return sha256(Buffer.from(line, "utf8"));
+}
+/** `sha256:<hex>` of the exact body bytes. */
+export function hashBody(body) {
+    return sha256(body);
+}
+function sha256(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}

package/dist/verify/index.d.ts

@@ -0,0 +1,3 @@
+export { ANCHOR_TARGET, anchorPayload, anchorPayloadBytes, type Bundle, type BundleAnchor, type BundleReport, verifyBundle, } from "./anchor.ts";
+export { type FailureCode, type VerifyOptions, type VerifyResult, verifyChain } from "./chain.ts";
+export { assertSafeIntegers, EncodingError, type Envelope, EVENT_KINDS, type EventKind, encodeEnvelope, GENESIS, hashBody, hashLine, type Json, } from "./envelope.ts";

package/dist/verify/index.js

@@ -0,0 +1,3 @@
+export { ANCHOR_TARGET, anchorPayload, anchorPayloadBytes, verifyBundle, } from "./anchor.js";
+export { verifyChain } from "./chain.js";
+export { assertSafeIntegers, EncodingError, EVENT_KINDS, encodeEnvelope, GENESIS, hashBody, hashLine, } from "./envelope.js";

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.2.0";

package/dist/version.js

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

package/dist/weather/index.d.ts

@@ -0,0 +1,24 @@
+export interface Sample {
+    at_ms: number;
+    provider: string;
+    model: string | null;
+    ok: boolean;
+    ms: number;
+}
+export interface Window {
+    calls: number;
+    errors: number;
+    error_ppm: number;
+    p95_ms: number;
+}
+export interface Conditions {
+    provider: string;
+    model: string | null;
+    last_5m: Window;
+    last_15m: Window;
+    status: "clear" | "degraded" | "down";
+}
+/** spec/weather.md §2. */
+export declare function weather(samples: readonly Sample[], nowMs: number, { slowMs }?: {
+    slowMs?: number;
+}): Conditions[];