@zanii/blackbox 0.2.0 → 0.4.0

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.2.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.2.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.2.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",