@zanii/blackbox 0.3.0 → 0.4.0

package/dist/sla/index.d.ts

@@ -0,0 +1,61 @@
+type Obj = Record<string, unknown>;
+type Commitments = {
+    min_actions?: number;
+    max_actions?: number;
+    max_gap_ms?: number;
+};
+/** Zanii's SLA terms. `commitments` holds at least one of min_actions, max_actions, max_gap_ms. */
+export declare function buildSlaBody(o: {
+    provider: string;
+    client: string;
+    scope: string;
+    window: {
+        start: string;
+        end: string;
+    };
+    commitments: Commitments;
+    price?: {
+        amount: string;
+        currency: string;
+    };
+    createdAt: string;
+    ref?: string;
+}): Obj;
+/** One party signs the terms. Collect the provider's and the client's. */
+export declare const signSla: (body: Obj, did: string, privateKey: Uint8Array) => {
+    did: string;
+    sig: string;
+};
+export declare const assembleSla: (body: Obj, signatures: Array<{
+    did: string;
+    sig: string;
+}>) => {
+    body: Obj;
+    signatures: {
+        did: string;
+        sig: string;
+    }[];
+};
+export declare const slaHash: (sla: Obj) => string;
+/** Zanii's check: sane terms, and BOTH provider and client signed exactly these. */
+export declare function verifySla(sla: unknown): {
+    ok: boolean;
+    reasons: string[];
+};
+/**
+ * Zanii's verdict over the provider's consecutive receipt chain for the window. Breaches:
+ * INVALID_RECEIPT, INCOMPLETE_RECORD (a seam: something recorded was left out), TOO_FEW_ACTIONS,
+ * TOO_MANY_ACTIONS, MAX_GAP_EXCEEDED. `asOf` (default the window's end) caps the trailing gap.
+ */
+export declare function assessCompliance(sla: Obj, receipts: readonly unknown[], asOf?: string): {
+    ok: boolean;
+    breaches: {
+        kind: string;
+        detail: string;
+    }[];
+    metrics: {
+        actions: number;
+        max_gap_ms: number | null;
+    };
+};
+export {};

package/dist/sla/index.js

@@ -0,0 +1,197 @@
+// Service agreements proven from receipts (spec/anchoring.md §14): Zanii's SLA, co-signed terms
+// whose compliance is computed from the provider's consecutive receipt chain, the same verdict for
+// everyone (@zanii/sla). Pure; mirrors sdks/python/src/zanii_blackbox/sla.py; pinned by
+// spec/vectors/sla.json.
+import { canonicalBytes, jcsHash, publicKeyFromDid, receiptHash, scopeCovers, verifyReceipt, } from "@zanii/core";
+import { parseMoney } from "../finance/index.js";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const ms = (ts) => {
+    if (typeof ts !== "string")
+        return null;
+    const t = Date.parse(ts);
+    return Number.isNaN(t) ? null : t;
+};
+const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
+/** Zanii's SLA terms. `commitments` holds at least one of min_actions, max_actions, max_gap_ms. */
+export function buildSlaBody(o) {
+    if (!o.provider || !o.client)
+        throw new Error("provider and client are required");
+    if (o.provider === o.client)
+        throw new Error("provider and client must differ");
+    if (!o.scope)
+        throw new Error("scope is required (the target pattern the service receipts match)");
+    const start = ms(o.window.start);
+    const end = ms(o.window.end);
+    if (start === null || end === null)
+        throw new Error("window start/end must be ISO timestamps");
+    if (start >= end)
+        throw new Error("window start must be before end");
+    if (ms(o.createdAt) === null)
+        throw new Error("created_at must be an ISO timestamp");
+    const c = { ...o.commitments };
+    for (const [k, v] of Object.entries(c))
+        if (v !== undefined && v !== null && !isCount(v))
+            throw new Error(`commitment ${k} must be a non-negative integer`);
+    if (c.min_actions == null && c.max_actions == null && c.max_gap_ms == null)
+        throw new Error("an SLA with no commitments commits to nothing");
+    if (c.min_actions != null && c.max_actions != null && c.min_actions > c.max_actions)
+        throw new Error("min_actions must not exceed max_actions");
+    return {
+        v: 1,
+        type: "sla",
+        provider: o.provider,
+        client: o.client,
+        scope: o.scope,
+        window: { start: o.window.start, end: o.window.end },
+        commitments: c,
+        created_at: o.createdAt,
+        ...(o.price ? { price: parseMoney(o.price.amount, o.price.currency) } : {}),
+        ...(o.ref !== undefined ? { ref: o.ref } : {}),
+    };
+}
+/** One party signs the terms. Collect the provider's and the client's. */
+export const signSla = (body, did, privateKey) => ({
+    did,
+    sig: `ed25519:${Buffer.from(ed25519Sign(privateKey, canonicalBytes(body))).toString("hex")}`,
+});
+export const assembleSla = (body, signatures) => ({
+    body,
+    signatures,
+});
+export const slaHash = (sla) => jcsHash(sla);
+const sigValid = (body, did, sig) => {
+    const pub = publicKeyFromDid(did);
+    const m = typeof sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sig) : null;
+    return Boolean(pub && m && ed25519Verify(pub, canonicalBytes(body), Buffer.from(m[1], "hex")));
+};
+/** Zanii's check: sane terms, and BOTH provider and client signed exactly these. */
+export function verifySla(sla) {
+    const reasons = [];
+    const e = (sla ?? {});
+    const b = e.body ?? {};
+    if (b.v !== 1 || b.type !== "sla")
+        reasons.push("not an sla (v1)");
+    const { provider, client } = b;
+    if (!provider || !client || provider === client)
+        reasons.push("missing/invalid parties");
+    if (!b.scope)
+        reasons.push("missing scope");
+    const w = (b.window ?? {});
+    const start = ms(w.start);
+    const end = ms(w.end);
+    if (start === null || end === null || start >= end)
+        reasons.push("invalid window");
+    const c = (b.commitments ?? {});
+    if (c.min_actions == null && c.max_actions == null && c.max_gap_ms == null)
+        reasons.push("no commitments");
+    if (reasons.length === 0)
+        for (const [party, role] of [
+            [provider, "provider"],
+            [client, "client"],
+        ]) {
+            const s = (e.signatures ?? []).find((x) => x.did === party);
+            if (!s)
+                reasons.push(`missing signature from ${role}`);
+            else if (!sigValid(b, String(s.did), s.sig))
+                reasons.push(`invalid signature from ${role}`);
+        }
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Zanii's verdict over the provider's consecutive receipt chain for the window. Breaches:
+ * INVALID_RECEIPT, INCOMPLETE_RECORD (a seam: something recorded was left out), TOO_FEW_ACTIONS,
+ * TOO_MANY_ACTIONS, MAX_GAP_EXCEEDED. `asOf` (default the window's end) caps the trailing gap.
+ */
+export function assessCompliance(sla, receipts, asOf) {
+    const agreement = verifySla(sla);
+    if (!agreement.ok)
+        return {
+            ok: false,
+            breaches: agreement.reasons.map((r) => ({ kind: "INVALID_RECEIPT", detail: `sla: ${r}` })),
+            metrics: { actions: 0, max_gap_ms: null },
+        };
+    const b = sla.body;
+    const breaches = [];
+    const winStart = ms(b.window.start);
+    const winEnd = ms(b.window.end);
+    if (asOf !== undefined && ms(asOf) === null)
+        throw new Error("as_of must be an ISO timestamp");
+    const asOfMs = Math.min(asOf !== undefined ? ms(asOf) : winEnd, winEnd);
+    // a stable sort, as Python's sorted
+    const sorted = receipts
+        .map((r, i) => ({ r, i, t: ms(r.ts) ?? 0 }))
+        .sort((x, y) => x.t - y.t || x.i - y.i)
+        .map((x) => x.r);
+    for (const r of sorted) {
+        let check;
+        try {
+            check = verifyReceipt(r);
+        }
+        catch (error) {
+            check = { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+        if (!check.ok)
+            breaches.push({
+                kind: "INVALID_RECEIPT",
+                detail: check.error || "invalid receipt",
+                receipt: receiptHash(r),
+            });
+        else if (r.agent_id !== b.provider)
+            breaches.push({
+                kind: "INVALID_RECEIPT",
+                detail: `receipt by ${r.agent_id}, not the provider`,
+                receipt: receiptHash(r),
+            });
+    }
+    for (let i = 1; i < sorted.length; i++)
+        if (sorted[i].prev !== receiptHash(sorted[i - 1]))
+            breaches.push({
+                kind: "INCOMPLETE_RECORD",
+                detail: `chain break between receipts #${i - 1} and #${i} — the slice is not the provider's consecutive record`,
+                receipt: receiptHash(sorted[i]),
+            });
+    const matching = sorted.filter((r) => {
+        const t = ms(r.ts);
+        return (t !== null && winStart <= t && t <= winEnd && scopeCovers(String(b.scope), r.target || ""));
+    });
+    const c = b.commitments;
+    if (c.min_actions != null && matching.length < c.min_actions)
+        breaches.push({
+            kind: "TOO_FEW_ACTIONS",
+            detail: `${matching.length} matching actions < committed minimum ${c.min_actions}`,
+        });
+    if (c.max_actions != null && matching.length > c.max_actions)
+        breaches.push({
+            kind: "TOO_MANY_ACTIONS",
+            detail: `${matching.length} matching actions > committed maximum ${c.max_actions}`,
+        });
+    let maxGap = null;
+    if (matching.length > 0) {
+        const times = matching.map((r) => ms(r.ts));
+        const gaps = [[times[0] - winStart, null]];
+        for (let i = 1; i < times.length; i++)
+            gaps.push([times[i] - times[i - 1], matching[i - 1]]);
+        const last = times[times.length - 1];
+        if (asOfMs > last)
+            gaps.push([asOfMs - last, matching[matching.length - 1]]);
+        maxGap = Math.max(...gaps.map(([g]) => g));
+        if (c.max_gap_ms != null)
+            for (const [g, after] of gaps)
+                if (g > c.max_gap_ms)
+                    breaches.push({
+                        kind: "MAX_GAP_EXCEEDED",
+                        detail: `${g}ms of silence > committed max ${c.max_gap_ms}ms`,
+                        ...(after ? { receipt: receiptHash(after) } : {}),
+                    });
+    }
+    else if (c.max_gap_ms != null && asOfMs - winStart > c.max_gap_ms)
+        breaches.push({
+            kind: "MAX_GAP_EXCEEDED",
+            detail: `no matching actions for ${asOfMs - winStart}ms > committed max ${c.max_gap_ms}ms`,
+        });
+    return {
+        ok: breaches.length === 0,
+        breaches,
+        metrics: { actions: matching.length, max_gap_ms: maxGap },
+    };
+}

package/dist/succession/index.d.ts

@@ -0,0 +1,50 @@
+export type SuccessionReason = "rotation" | "compromise" | "retirement";
+export interface SuccessionBody {
+    v: 1;
+    type: "succession";
+    predecessor: string;
+    successor: string;
+    owner: string;
+    reason: SuccessionReason;
+    ts: string;
+    compromised_at?: string;
+    note?: string;
+}
+export interface Succession {
+    body: SuccessionBody;
+    signatures: Array<{
+        did: string;
+        sig: string;
+    }>;
+}
+export declare function buildSuccessionBody(input: {
+    predecessor: string;
+    successor: string;
+    owner: string;
+    reason: string;
+    ts: string;
+    compromised_at?: string;
+    note?: string;
+}): SuccessionBody;
+/** Signs as the owner (required) or the predecessor (optional: a planned handover). */
+export declare const signSuccession: (body: SuccessionBody, did: string, seed: Uint8Array) => {
+    did: string;
+    sig: string;
+};
+export declare const assembleSuccession: (body: SuccessionBody, signatures: Succession["signatures"]) => Succession;
+export declare const successionHash: (s: Succession) => string;
+/** Structure sane and the owner signed; `cosigned` when the predecessor countersigned too. */
+export declare function verifySuccession(s: unknown): {
+    ok: boolean;
+    reasons: string[];
+    cosigned: boolean;
+};
+/**
+ * Walks the successions back from `did`: every link verifies, links connect, one owner throughout
+ * (a change of owner is a sale, not a succession). `lineage` is oldest first.
+ */
+export declare function verifyLineage(successions: unknown[], did: string): {
+    ok: boolean;
+    reasons: string[];
+    lineage: string[];
+};

package/dist/succession/index.js

@@ -0,0 +1,123 @@
+// Owner-signed succession of the gateway identity (spec/anchoring.md §7), in Zanii's format:
+// byte-identical bodies, signatures and hashes to `@zanii/succession` / `zanii.succession`
+// (vectors: spec/vectors/succession.json). The Python SDK re-exports zanii.succession.
+//
+// Succession proves continuity of authority (the owner says B follows A), not which code ran.
+// After a compromise the predecessor's signature isn't asked for (the attacker holds that key), and
+// `compromised_at` brackets the window its old receipts can be trusted in.
+import { canonicalBytes, jcsHash, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const REASONS = new Set(["rotation", "compromise", "retirement"]);
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+export function buildSuccessionBody(input) {
+    const { predecessor, successor, owner, reason, ts, compromised_at, note } = input;
+    if (!predecessor || !successor || !owner)
+        throw new Error("predecessor, successor, and owner are required");
+    if (predecessor === successor)
+        throw new Error("an agent cannot succeed itself");
+    if (!REASONS.has(reason))
+        throw new Error(`invalid reason '${reason}'`);
+    if (!validTs(ts))
+        throw new Error("ts must be an ISO timestamp");
+    if (reason === "compromise") {
+        if (!validTs(compromised_at))
+            throw new Error("a 'compromise' succession requires compromised_at");
+    }
+    else if (compromised_at !== undefined)
+        throw new Error("compromised_at is only meaningful with reason 'compromise'");
+    return {
+        v: 1,
+        type: "succession",
+        predecessor,
+        successor,
+        owner,
+        reason: reason,
+        ts,
+        ...(compromised_at !== undefined ? { compromised_at } : {}),
+        ...(note !== undefined ? { note } : {}),
+    };
+}
+/** Signs as the owner (required) or the predecessor (optional: a planned handover). */
+export const signSuccession = (body, did, seed) => ({
+    did,
+    sig: `ed25519:${Buffer.from(ed25519Sign(seed, canonicalBytes(body))).toString("hex")}`,
+});
+export const assembleSuccession = (body, signatures) => ({ body, signatures });
+export const successionHash = (s) => jcsHash(s);
+function sigValid(body, did, sig) {
+    const pub = publicKeyFromDid(did);
+    const m = typeof sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sig) : null;
+    if (!pub || !m)
+        return false;
+    return ed25519Verify(pub, canonicalBytes(body), Buffer.from(m[1], "hex"));
+}
+/** Structure sane and the owner signed; `cosigned` when the predecessor countersigned too. */
+export function verifySuccession(s) {
+    const reasons = [];
+    const e = (s ?? {});
+    const b = (e.body ?? {});
+    if (b.v !== 1 || b.type !== "succession")
+        reasons.push("not a succession (v1)");
+    const { predecessor: pred, successor: succ, owner } = b;
+    if (!pred || !succ || !owner || pred === succ)
+        reasons.push("missing/invalid parties");
+    if (!REASONS.has(String(b.reason)))
+        reasons.push("invalid reason");
+    if (b.reason === "compromise" && !validTs(b.compromised_at))
+        reasons.push("a 'compromise' succession requires a valid compromised_at");
+    if (!validTs(b.ts))
+        reasons.push("missing/invalid ts");
+    let cosigned = false;
+    if (reasons.length === 0) {
+        const sigs = Array.isArray(e.signatures) ? e.signatures : [];
+        const ownerSig = sigs.find((x) => x?.did === owner);
+        if (!ownerSig || !sigValid(b, ownerSig.did, ownerSig.sig))
+            reasons.push("missing/invalid OWNER signature");
+        const predSig = sigs.find((x) => x?.did === pred);
+        cosigned = predSig !== undefined && sigValid(b, predSig.did, predSig.sig);
+    }
+    return { ok: reasons.length === 0, reasons, cosigned };
+}
+/**
+ * Walks the successions back from `did`: every link verifies, links connect, one owner throughout
+ * (a change of owner is a sale, not a succession). `lineage` is oldest first.
+ */
+export function verifyLineage(successions, did) {
+    if (successions.length === 0)
+        return { ok: true, reasons: [], lineage: [did] };
+    const bySuccessor = new Map();
+    for (const s of successions) {
+        const check = verifySuccession(s);
+        if (!check.ok) {
+            const label = s?.body?.successor ?? "?";
+            return { ok: false, reasons: check.reasons.map((r) => `link ${label}: ${r}`), lineage: [] };
+        }
+        const link = s;
+        if (bySuccessor.has(link.body.successor))
+            return {
+                ok: false,
+                reasons: [`two successions claim successor ${link.body.successor}`],
+                lineage: [],
+            };
+        bySuccessor.set(link.body.successor, link);
+    }
+    const links = successions;
+    const owner = links[0]?.body.owner;
+    if (!links.every((s) => s.body.owner === owner))
+        return { ok: false, reasons: ["lineage spans multiple owners"], lineage: [] };
+    const lineage = [did];
+    const seen = new Set([did]);
+    let cursor = did;
+    for (let link = bySuccessor.get(cursor); link; link = bySuccessor.get(cursor)) {
+        const prev = link.body.predecessor;
+        if (seen.has(prev))
+            return { ok: false, reasons: ["succession cycle detected"], lineage: [] };
+        seen.add(prev);
+        lineage.unshift(prev);
+        cursor = prev;
+    }
+    const reasons = lineage.length === links.length + 1
+        ? []
+        : [`${links.length + 1 - lineage.length} succession(s) do not connect to ${did}'s lineage`];
+    return { ok: reasons.length === 0, reasons, lineage };
+}

package/dist/tokens/index.d.ts

@@ -0,0 +1,6 @@
+/** The token for one value: `<kind_tok:base64url(nonce ‖ AES-256-GCM(value, aad=kind))>`. */
+export declare function tokenFor(kind: string, value: string, key: Uint8Array): string;
+/** A token's value, or null when it isn't one, or isn't this key's. */
+export declare function resolveToken(token: string, key: Uint8Array): string | null;
+/** Every token in `text` this key resolves, put back; any other is left as it is. */
+export declare function resolveTokens(text: string, key: Uint8Array): string;

package/dist/tokens/index.js

@@ -0,0 +1,46 @@
+// Keyed redaction tokens (spec/data.md §12, L9): a redacted value as `<kind_tok:…>`, AES-256-GCM
+// under the deployment's token key, so a tool that holds the key resolves it and nothing in between
+// (the model, the gateway's memory) has the value. Deterministic: the nonce is an HMAC of the kind
+// and value, so the same value always reads the same. Mirrors sdks/python/src/zanii_blackbox/
+// tokens.py; pinned by spec/vectors/tokens.json.
+import { createCipheriv, createDecipheriv, createHmac } from "node:crypto";
+const TOKEN = /<([a-z_]{1,32})_tok:([A-Za-z0-9_-]{24,4096})>/g;
+const check = (key) => {
+    if (key.length !== 32)
+        throw new Error("a token key is 32 bytes");
+};
+/** The token for one value: `<kind_tok:base64url(nonce ‖ AES-256-GCM(value, aad=kind))>`. */
+export function tokenFor(kind, value, key) {
+    check(key);
+    if (!/^[a-z_]{1,32}$/.test(kind))
+        throw new Error("kind must be 1-32 of a-z _");
+    const nonce = createHmac("sha256", key).update(`${kind}\0${value}`).digest().subarray(0, 12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    cipher.setAAD(Buffer.from(kind));
+    const sealed = Buffer.concat([cipher.update(value, "utf8"), cipher.final(), cipher.getAuthTag()]);
+    return `<${kind}_tok:${Buffer.concat([nonce, sealed]).toString("base64url")}>`;
+}
+/** A token's value, or null when it isn't one, or isn't this key's. */
+export function resolveToken(token, key) {
+    check(key);
+    const m = new RegExp(`^${TOKEN.source}$`).exec(token);
+    if (!m)
+        return null;
+    try {
+        const raw = Buffer.from(m[2], "base64url");
+        if (raw.length < 12 + 16)
+            return null;
+        const d = createDecipheriv("aes-256-gcm", key, raw.subarray(0, 12));
+        d.setAAD(Buffer.from(m[1]));
+        d.setAuthTag(raw.subarray(raw.length - 16));
+        return Buffer.concat([d.update(raw.subarray(12, raw.length - 16)), d.final()]).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Every token in `text` this key resolves, put back; any other is left as it is. */
+export function resolveTokens(text, key) {
+    check(key);
+    return text.replace(TOKEN, (t) => resolveToken(t, key) ?? t);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.4.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.3.0";
+export const VERSION = "0.4.0";

package/dist/walls/index.d.ts

@@ -0,0 +1,31 @@
+export interface Wall {
+    id: string;
+    regulator: string;
+    scopes: string[];
+    denies: string[];
+    forbidden: string[];
+    note: string;
+}
+export declare const WALLS: Readonly<Record<string, Wall>>;
+/** Zanii's wall manifest hash: the id and its sorted scopes and denies (order-independent). */
+export declare const wallManifestHash: (w: Wall) => string;
+/** Zanii's heuristic: an output crosses the wall when it holds a forbidden phrase. */
+export declare function checkOutput(w: Wall, text: string): {
+    ok: boolean;
+    violations: string[];
+};
+/**
+ * spec/governance.md §5: WALL_CROSSED for each model response that holds a phrase one of the
+ * walls forbids; one finding per response and wall, naming the first phrase.
+ */
+export declare function wallFindings(lines: readonly string[], bodies: (hash: string) => Uint8Array | undefined, wallIds: readonly string[]): {
+    code: string;
+    source: string;
+    severity: "warning";
+    ref: {
+        seq: number;
+        wall: string;
+        phrase: string;
+    };
+    detail: string;
+}[];

package/dist/walls/index.js

@@ -0,0 +1,119 @@
+// Zanii's UAE vertical walls (spec/governance.md §5): the table from spec/walls/v1.json, embedded
+// (a test checks it matches), and the output check. Mirrors sdks/python/src/zanii_blackbox/walls.py.
+import { jcsHash } from "@zanii/core";
+export const WALLS = {
+    "sca-trading": {
+        id: "sca-trading",
+        regulator: "SCA",
+        scopes: ["trading.education.*", "market.read.*"],
+        denies: ["trading.execute.*", "trading.advise.*", "trading.recommend.*"],
+        forbidden: [
+            "buy this",
+            "sell this",
+            "you should buy",
+            "you should sell",
+            "i recommend buying",
+            "i recommend selling",
+            "guaranteed return",
+            "guaranteed profit",
+            "this will go up",
+            "will moon",
+        ],
+        note: 'education only; NEVER "buy this" — investment advice/execution is a licensed SCA activity',
+    },
+    "rera-realty": {
+        id: "rera-realty",
+        regulator: "RERA/DLD",
+        scopes: ["realty.inform.*", "realty.read.*"],
+        denies: ["realty.broker.*", "realty.list.*"],
+        forbidden: ["i can broker", "i will list", "sign the deal"],
+        note: "informs; never brokers or lists unpermitted properties",
+    },
+    "tdra-messaging": {
+        id: "tdra-messaging",
+        regulator: "TDRA",
+        scopes: ["messaging.send.optin.*"],
+        denies: ["messaging.send.bulk.*", "messaging.send.nonoptin.*"],
+        forbidden: [],
+        note: "opt-in only; must announce it is a bot",
+    },
+    "legal-drafting": {
+        id: "legal-drafting",
+        regulator: "Legal Affairs",
+        scopes: ["legal.draft.*", "legal.read.*"],
+        denies: ["legal.opine.*", "legal.advise.*"],
+        forbidden: ["my legal opinion is", "you should sue", "this is legally binding advice"],
+        note: "drafts; never gives legal opinions",
+    },
+    "consumer-due": {
+        id: "consumer-due",
+        regulator: "Consumer Protection / Central Bank",
+        scopes: ["collections.remind.*"],
+        denies: ["collections.threaten.*"],
+        forbidden: ["we will sue you", "legal action today", "you will be arrested"],
+        note: "reminds; never threatens; frequency limits",
+    },
+    "difc-dp": {
+        id: "difc-dp",
+        regulator: "DIFC (DP Law 2020)",
+        scopes: ["data.process.difc.*"],
+        denies: ["data.export.nonadequate.*"],
+        forbidden: [],
+        note: "DIFC free-zone data protection; select per deployment (not federal PDPL)",
+    },
+    "adgm-dp": {
+        id: "adgm-dp",
+        regulator: "ADGM (DP Regs 2021)",
+        scopes: ["data.process.adgm.*"],
+        denies: ["data.export.nonadequate.*"],
+        forbidden: [],
+        note: "ADGM free-zone data protection; select per deployment (not federal PDPL)",
+    },
+};
+/** Zanii's wall manifest hash: the id and its sorted scopes and denies (order-independent). */
+export const wallManifestHash = (w) => jcsHash({ id: w.id, scopes: [...w.scopes].sort(), denies: [...w.denies].sort() });
+/** Zanii's heuristic: an output crosses the wall when it holds a forbidden phrase. */
+export function checkOutput(w, text) {
+    const lower = text.toLowerCase();
+    const violations = w.forbidden.filter((p) => lower.includes(p));
+    return { ok: violations.length === 0, violations };
+}
+const decoder = new TextDecoder();
+/**
+ * spec/governance.md §5: WALL_CROSSED for each model response that holds a phrase one of the
+ * walls forbids; one finding per response and wall, naming the first phrase.
+ */
+export function wallFindings(lines, bodies, wallIds) {
+    const walls = wallIds.map((id) => WALLS[id]).filter((w) => w !== undefined);
+    const out = [];
+    if (walls.length === 0)
+        return out;
+    // a response's bytes are its chunks' bodies, joined in order (spec/api.md: llm.chunk)
+    const chunks = new Map();
+    for (const l of lines) {
+        const e = JSON.parse(l);
+        if (e.kind === "llm.chunk") {
+            const body = bodies(e.body_hash);
+            const list = chunks.get(e.meta.request_seq) ?? [];
+            list.push(body ? decoder.decode(body) : "");
+            chunks.set(e.meta.request_seq, list);
+        }
+        if (e.kind !== "llm.response")
+            continue;
+        const text = (chunks.get(e.meta.request_seq) ?? []).join("");
+        if (!text)
+            continue;
+        for (const w of walls) {
+            const check = checkOutput(w, text);
+            if (!check.ok)
+                out.push({
+                    code: "WALL_CROSSED",
+                    source: "detectors",
+                    severity: "warning",
+                    ref: { seq: e.seq, wall: w.id, phrase: check.violations[0] },
+                    detail: `The model's answer crossed the ${w.regulator} wall: ${w.note}`,
+                });
+        }
+    }
+    return out;
+}

package/package.json

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