@zanii/blackbox 0.3.0 → 0.5.0

package/dist/memory/index.js

@@ -0,0 +1,85 @@
+// Provable agent memory (spec/agents.md §4): Zanii's memory.write entries, a salted commitment to
+// what the agent remembered, hash-chained so an edit afterwards shows (@zanii/memory). Pure;
+// mirrors sdks/python/src/zanii_blackbox/memory.py; pinned by spec/vectors/memory.json.
+import { createHash, randomBytes } from "node:crypto";
+import { jcsHash } from "@zanii/core";
+/** Zanii's salted commitment to memory content. */
+export function commitContent(content, salt) {
+    const s = salt ?? randomBytes(16).toString("hex");
+    const h = createHash("sha256")
+        .update(Buffer.from(s, "hex"))
+        .update(content, "utf8")
+        .digest("hex");
+    return { commitment: `sha256:${h}`, salt: s };
+}
+/** The entry was about `content`, given the salt kept at write time. */
+export const verifyMemoryContent = (content, salt, commitment) => commitContent(content, salt).commitment === commitment;
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+const entryHash = (commitment, kind, ts, prev, seq) => jcsHash({ v: 1, content_commitment: commitment, kind, ts, prev, seq });
+/** Zanii's memory.write payload, after `prev` (the previous entry; null starts a chain). Keep the salt. */
+export function memoryEntry(input) {
+    if (!validTs(input.ts))
+        throw new Error("ts must be an ISO timestamp");
+    const p = input.prev ?? null;
+    if (p && (typeof p.entry_hash !== "string" || !Number.isSafeInteger(p.seq)))
+        throw new Error("previous entry has no entry_hash or seq");
+    const kind = input.kind ?? "fact";
+    const c = commitContent(input.content, input.salt);
+    const seq = p ? p.seq + 1 : 0;
+    const prev = p ? p.entry_hash : null;
+    return {
+        payload: {
+            _zr_kind: "memory",
+            v: 1,
+            kind,
+            content_commitment: c.commitment,
+            prev,
+            seq,
+            entry_hash: entryHash(c.commitment, kind, input.ts, prev, seq),
+            agent: input.agent ?? null,
+            tags: input.tags ?? null,
+            ts: input.ts,
+        },
+        salt: c.salt,
+    };
+}
+/** Zanii's check of one entry: well formed, and its entry_hash matches. */
+export function verifyMemoryEntry(payload) {
+    const p = (payload ?? {});
+    const reasons = [];
+    if (p._zr_kind !== "memory" || p.v !== 1)
+        reasons.push("not a memory receipt (v1)");
+    const cc = p.content_commitment;
+    if (typeof cc !== "string" || !cc.startsWith("sha256:"))
+        reasons.push("missing/invalid content commitment");
+    if (!validTs(p.ts))
+        reasons.push("missing/invalid ts");
+    if (!Number.isSafeInteger(p.seq) || p.seq < 0)
+        reasons.push("missing/invalid seq");
+    if (p.prev !== null && p.prev !== undefined && typeof p.prev !== "string")
+        reasons.push("prev must be a hash string or null");
+    if (reasons.length === 0 &&
+        entryHash(cc, p.kind || "fact", p.ts, p.prev ?? null, p.seq) !== p.entry_hash)
+        reasons.push("entry_hash does not match its contents (tampered)");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Walks entries in order: each checks, links to the one before and counts up by one. The first may continue a chain from elsewhere. */
+export function memoryChain(entries) {
+    const broken = [];
+    let prevHash = null;
+    let prevSeq = null;
+    entries.forEach((e, i) => {
+        const p = (e ?? {});
+        const single = verifyMemoryEntry(p);
+        if (!single.ok)
+            broken.push({ index: i, reason: single.reasons.join("; ") });
+        else if (i > 0 && (p.prev ?? null) !== prevHash)
+            broken.push({ index: i, reason: "broken link (prev is not the previous entry_hash)" });
+        if (single.ok && prevSeq !== null && p.seq !== prevSeq + 1)
+            broken.push({ index: i, reason: "seq is not previous + 1" });
+        // a bad entry is reported once: the next one is checked against what it claims
+        prevHash = p.entry_hash;
+        prevSeq = Number.isSafeInteger(p.seq) ? p.seq : null;
+    });
+    return { ok: broken.length === 0, length: entries.length, broken };
+}

package/dist/occurrence/index.d.ts

@@ -5,6 +5,8 @@ export interface OccurrenceFramework {
     title: string;
     authority: string;
     deadlines: string[];
+    /** spec/packs.md §1: each deadline's hours after awareness, or null. */
+    clock_hours?: Array<number | null>;
     sections: Array<{
         id: string;
         title: string;
@@ -68,6 +70,15 @@ export declare function occurrenceReport(id: string, framework: OccurrenceFramew
     }[];
 };
 export type OccurrenceReport = ReturnType<typeof occurrenceReport>;
+/**
+ * spec/occurrence.md §1a: each deadline's due time, counted from when the entity became aware
+ * (`awareAt`, ISO-8601 with a zone). A deadline without a clock (it runs from another event, like a
+ * corrective measure) is `null`. Whether and when the entity became aware is the entity's call.
+ */
+export declare function deadlinesDue(framework: OccurrenceFramework, awareAt: string, lang?: "en" | "ar"): Array<{
+    deadline: string;
+    due_at: string | null;
+}>;
 export declare function renderOccurrence(r: OccurrenceReport, notes: string): string;
 /** spec/occurrence.md "Filing": what a person needs to file the report in an authority's portal. */
 export declare function filingPack(r: OccurrenceReport, notes: string, pack: {

package/dist/occurrence/index.js

@@ -114,6 +114,24 @@ export function occurrenceReport(id, framework, facts, lang = "en") {
         })),
     };
 }
+/**
+ * spec/occurrence.md §1a: each deadline's due time, counted from when the entity became aware
+ * (`awareAt`, ISO-8601 with a zone). A deadline without a clock (it runs from another event, like a
+ * corrective measure) is `null`. Whether and when the entity became aware is the entity's call.
+ */
+export function deadlinesDue(framework, awareAt, lang = "en") {
+    const at = Date.parse(awareAt);
+    if (!/[zZ]|[+-]\d{2}:\d{2}$/.test(awareAt) || Number.isNaN(at))
+        throw new Error("aware_at must be an ISO-8601 time with a zone");
+    const texts = lang === "ar" && framework.ar ? framework.ar.deadlines : framework.deadlines;
+    return texts.map((deadline, i) => {
+        const h = framework.clock_hours?.[i];
+        return {
+            deadline,
+            due_at: typeof h === "number" ? new Date(at + h * 3_600_000).toISOString() : null,
+        };
+    });
+}
 const LABELS = {
     en: ["Session", "Record verifies", "yes", "NO", "Report to", "Generated", "Deadlines"],
     ar: ["الجلسة", "السجل موثّق", "نعم", "لا", "جهة الإبلاغ", "تاريخ الإنشاء", "المواعيد النهائية"],

package/dist/otlp/index.js

@@ -13,7 +13,34 @@ const int = (key, v) => typeof v === "number" && Number.isSafeInteger(v) ? [{ ke
  * is the first version's output, pinned by spec/vectors/otlp.json.
  */
 export function toOtlp(lines, options = {}) {
-    return options.semconv === 1 ? toOtlpV1(lines) : toOtlpV2(lines);
+    return linkCallers(options.semconv === 1 ? toOtlpV1(lines) : toOtlpV2(lines), lines);
+}
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+/** spec/otlp.md §3: a call that carried the caller's W3C `traceparent` links to the caller's span. */
+function linkCallers(out, lines) {
+    const links = new Map();
+    let session = "";
+    for (const l of lines) {
+        const e = JSON.parse(l);
+        session ||= e.session_id;
+        const tp = e.meta.headers?.traceparent;
+        const m = typeof tp === "string" ? TRACEPARENT.exec(tp) : null;
+        if (m && !/^0+$/.test(m[1]) && !/^0+$/.test(m[2]))
+            links.set(hex(`${session}:${e.seq}`, 16), {
+                traceId: m[1],
+                spanId: m[2],
+            });
+    }
+    if (links.size === 0)
+        return out;
+    for (const rs of out.resourceSpans)
+        for (const ss of rs.scopeSpans)
+            for (const sp of ss.spans) {
+                const link = links.get(sp.spanId);
+                if (link)
+                    sp.links = [link];
+            }
+    return out;
 }
 function toOtlpV1(lines) {
     const events = lines.map((l) => JSON.parse(l));

package/dist/packs/index.js

@@ -16,6 +16,13 @@ const FACTS = new Set([
     "resumes_with_note",
     "outcomes",
     "data_region",
+    // spec/compliance.md §1a (H6)
+    "model_responses",
+    "hallucination_findings",
+    "grounding_checks",
+    "judge_checks",
+    "hallucination_controls",
+    "detector_accuracy",
 ]);
 const FILLS = new Set(["record", "findings", "redactions", "operator"]);
 const PACK_ID = /^[a-z0-9-]{1,64}$/;
@@ -63,8 +70,8 @@ function checkPart(part, kind) {
         if (!isObj(fw) || !text(fw.title, 500))
             return `${at}.title must be 1-500 characters`;
         if (kind === "compliance") {
-            if (!only(fw, ["title", "sections"]))
-                return `${at} may only have title and sections`;
+            if (!only(fw, ["title", "sections", "ar"]))
+                return `${at} may only have title, sections and ar`;
             const bad = checkSections(fw.sections, 50, at, (s, sat) => {
                 if (!only(s, ["id", "title", "requirement", "facts"]))
                     return `${sat} may only have id, title, requirement, facts`;
@@ -79,10 +86,15 @@ function checkPart(part, kind) {
             });
             if (bad)
                 return bad;
+            if (fw.ar !== undefined) {
+                const badAr = checkComplianceArabic(fw.ar, fw, `${at}.ar`);
+                if (badAr)
+                    return badAr;
+            }
         }
         else {
-            if (!only(fw, ["title", "authority", "deadlines", "sections", "ar"]))
-                return `${at} may only have title, authority, deadlines, sections`;
+            if (!only(fw, ["title", "authority", "deadlines", "clock_hours", "sections", "ar"]))
+                return `${at} may only have title, authority, deadlines, clock_hours, sections`;
             if (!text(fw.authority, 500))
                 return `${at}.authority must be 1-500 characters`;
             if (!Array.isArray(fw.deadlines) ||
@@ -90,6 +102,13 @@ function checkPart(part, kind) {
                 fw.deadlines.length > 10 ||
                 !fw.deadlines.every((d) => text(d, 500)))
                 return `${at}.deadlines must hold 1-10 texts of 1-500 characters`;
+            // spec/packs.md §1: each deadline's hours after awareness, or null when it runs from another event
+            if (fw.clock_hours !== undefined &&
+                !(Array.isArray(fw.clock_hours) &&
+                    fw.clock_hours.length === fw.deadlines.length &&
+                    fw.clock_hours.every((h) => h === null ||
+                        (Number.isSafeInteger(h) && h >= 1 && h <= 8760))))
+                return `${at}.clock_hours must give each deadline 1-8760 hours, or null`;
             const bad = checkSections(fw.sections, 30, at, (s, sat) => {
                 if (!only(s, ["id", "title", "fill"]))
                     return `${sat} may only have id, title, fill`;
@@ -108,6 +127,27 @@ function checkPart(part, kind) {
     }
     return undefined;
 }
+/** spec/packs.md §1: a compliance framework's Arabic: its title, and each section's title and
+ * requirement, by id. */
+function checkComplianceArabic(ar, fw, at) {
+    if (!isObj(ar) || !only(ar, ["title", "sections"]))
+        return `${at} must be {title, sections}`;
+    if (!text(ar.title, 500))
+        return `${at}.title must be 1-500 characters`;
+    const ids = fw.sections.map((s) => s.id);
+    const secs = ar.sections;
+    if (!isObj(secs) ||
+        Object.keys(secs).length !== ids.length ||
+        !ids.every((id) => {
+            const s = secs[id];
+            return (isObj(s) &&
+                only(s, ["title", "requirement"]) &&
+                text(s.title, 500) &&
+                text(s.requirement, 2000));
+        }))
+        return `${at}.sections must translate each section's title and requirement, by id`;
+    return undefined;
+}
 /** spec/packs.md §1: an occurrence framework's Arabic: the same deadlines and sections, translated. */
 function checkArabic(ar, fw, at) {
     if (!isObj(ar) || !only(ar, ["title", "authority", "deadlines", "sections"]))

package/dist/policy/delta.js

@@ -3,7 +3,13 @@
 // in doubt, it adds power. Mirrors policy/delta.py.
 /** How much a rule holds back: an enforced allow opens (0), an audit rule does nothing (1), a hold
  * (2) and a deny (3) close. */
-const rank = (r) => r.audit === true ? 1 : r.action === "allow" ? 0 : r.action === "require_approval" ? 2 : 3;
+const rank = (r) => r.audit === true || r.action === "require_proof"
+    ? 1
+    : r.action === "allow"
+        ? 0
+        : r.action === "require_approval"
+            ? 2
+            : 3;
 const matcher = (r) => JSON.stringify([r.tool, r.args_match ?? null, r.ignore_case === true]);
 export function policyDelta(current, proposed) {
     const before = new Map(current.rules.map((r) => [r.id, r]));

package/dist/policy/index.d.ts

@@ -6,14 +6,21 @@ export interface Rule {
     tool: string;
     args_match?: string;
     ignore_case?: boolean;
-    /** spec/approvals.md: `require_approval` holds the call for a second person. */
-    action: "deny" | "allow" | "require_approval";
+    /** spec/approvals.md: `require_approval` holds the call for a second person; spec/policy.md
+     * §9: `require_proof` lets it run, and its result must prove itself. */
+    action: "deny" | "allow" | "require_approval" | "require_proof";
+    /** spec/policy.md §9: with `require_proof`, the system's own id in the result (`refund_id`). */
+    field?: string;
     reason?: string;
     /** N3 (idea C5): record-only. Never decides a call; what it would do is recorded (POLICY_AUDIT). */
     audit?: boolean;
     /** spec/policy.md §1: MCP tool annotations the call must have (from the server's `tools/list`). */
     hints?: Partial<ToolHints>;
+    /** spec/policy.md §1: the session environments the rule holds in (a session's `environment`). */
+    environment?: string[];
 }
+/** spec/api.md: a session's environment, e.g. `production`, `staging`, `dev`. */
+export declare const ENVIRONMENT: RegExp;
 /** MCP tool annotations as booleans, with the spec's defaults for what a server leaves out. */
 export interface ToolHints {
     read_only: boolean;
@@ -28,6 +35,13 @@ export interface ToolHints {
  * An unknown tool gets the defaults too. Hints are the server's word, not proof.
  */
 export declare function mcpToolHints(annotations?: unknown): ToolHints;
+/**
+ * spec/policy.md §1a: a tool definition's identity, `sha256:<hex>` of the canonical JSON of its
+ * name, title, description, schemas and annotations (the fields present). A changed description
+ * or schema changes it: what the agent was shown is no longer what was approved. `null` for
+ * something that isn't a named tool.
+ */
+export declare function toolDefinitionHash(tool: unknown): string | null;
 export interface Policy {
     version: 1;
     rules: Rule[];
@@ -36,7 +50,7 @@ export interface Policy {
 }
 export interface Decision {
     rule: string;
-    action: "deny" | "allow" | "require_approval";
+    action: "deny" | "allow" | "require_approval" | "require_proof";
     reason?: string;
 }
 interface Compiled {
@@ -47,12 +61,15 @@ interface Compiled {
 /** Parses a policy file; throws on anything invalid (the server refuses to start). */
 export declare function loadPolicy(bytes: Uint8Array): Policy;
 export declare function compilePolicy(policy: Policy): Compiled[];
+/** spec/api.md: the session's environment, from its `session.open` (the first line). */
+export declare function environmentOf(lines: readonly string[]): string | undefined;
 /** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool
- * has two). `hints`: an MCP tool's annotations; a rule with `hints` never matches a call without. */
-export declare function decide(compiled: readonly Compiled[], names: readonly string[], args: unknown, hints?: ToolHints): Decision | null;
+ * has two). `hints`: an MCP tool's annotations; a rule with `hints` never matches a call without.
+ * `environment`: the session's; a rule with `environment` never matches a session without one. */
+export declare function decide(compiled: readonly Compiled[], names: readonly string[], args: unknown, hints?: ToolHints, environment?: string): Decision | null;
 export type CompiledPolicy = ReturnType<typeof compilePolicy>;
 /** N3 (idea C5): every audit rule this call matches, and what it would do if it were enforced. */
-export declare function audited(compiled: readonly Compiled[], names: readonly string[], args: unknown, hints?: ToolHints): Array<{
+export declare function audited(compiled: readonly Compiled[], names: readonly string[], args: unknown, hints?: ToolHints, environment?: string): Array<{
     rule: string;
     would: Rule["action"];
 }>;

package/dist/policy/index.js

@@ -1,7 +1,11 @@
 // Tool policy (spec/policy.md): rules checked in order, the first match decides. Mirrors policy.py.
+import { createHash } from "node:crypto";
+import { hasEvidence } from "../data/index.js";
 import { callsOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
 import { checkCompensations } from "../undo/index.js";
+/** spec/api.md: a session's environment, e.g. `production`, `staging`, `dev`. */
+export const ENVIRONMENT = /^[a-z][a-z0-9-]{0,31}$/;
 const HINTS = ["read_only", "destructive", "idempotent", "open_world"];
 /**
  * spec/policy.md §1: a tool's annotations (MCP `readOnlyHint`, `destructiveHint`, `idempotentHint`,
@@ -19,6 +23,33 @@ export function mcpToolHints(annotations) {
         open_world: a.openWorldHint !== false,
     };
 }
+/** The fields of an MCP tool definition that say what the tool is and does (spec/policy.md §1a). */
+const DEFINITION_FIELDS = [
+    "name",
+    "title",
+    "description",
+    "inputSchema",
+    "outputSchema",
+    "annotations",
+];
+/**
+ * spec/policy.md §1a: a tool definition's identity, `sha256:<hex>` of the canonical JSON of its
+ * name, title, description, schemas and annotations (the fields present). A changed description
+ * or schema changes it: what the agent was shown is no longer what was approved. `null` for
+ * something that isn't a named tool.
+ */
+export function toolDefinitionHash(tool) {
+    if (typeof tool !== "object" || tool === null || Array.isArray(tool))
+        return null;
+    const t = tool;
+    if (typeof t.name !== "string" || t.name.length === 0 || t.name.length > 256)
+        return null;
+    const picked = {};
+    for (const k of DEFINITION_FIELDS)
+        if (t[k] !== undefined)
+            picked[k] = t[k];
+    return `sha256:${createHash("sha256").update(canonical(picked)).digest("hex")}`;
+}
 const hintsMatch = (want, have) => want === undefined ||
     (have !== undefined && Object.entries(want).every(([k, v]) => have[k] === v));
 const MAX_ARGS = 64 * 1024;
@@ -36,8 +67,13 @@ export function loadPolicy(bytes) {
             throw new Error(`policy: rule id "${r.id}" must match ^[a-z0-9-]{1,64}$`);
         if (typeof r.tool !== "string" || r.tool === "")
             throw new Error(`policy ${r.id}: tool is required`);
-        if (r.action !== "deny" && r.action !== "allow" && r.action !== "require_approval")
-            throw new Error(`policy ${r.id}: action must be deny, allow or require_approval`);
+        if (!["deny", "allow", "require_approval", "require_proof"].includes(r.action))
+            throw new Error(`policy ${r.id}: action must be deny, allow, require_approval or require_proof`);
+        if (r.field !== undefined &&
+            (r.action !== "require_proof" ||
+                typeof r.field !== "string" ||
+                !/^[A-Za-z0-9_.-]{1,64}$/.test(r.field)))
+            throw new Error(`policy ${r.id}: field is a 1-64 character key, with require_proof only`);
         if (r.args_match !== undefined) {
             if (typeof r.args_match !== "string" || r.args_match.length > 200)
                 throw new Error(`policy ${r.id}: args_match must be a regular expression of ≤ 200 characters`);
@@ -54,6 +90,12 @@ export function loadPolicy(bytes) {
                 !Object.entries(h).every(([k, v]) => HINTS.includes(k) && typeof v === "boolean"))
                 throw new Error(`policy ${r.id}: hints must set some of read_only, destructive, idempotent, open_world to true or false`);
         }
+        if (r.environment !== undefined &&
+            !(Array.isArray(r.environment) &&
+                r.environment.length > 0 &&
+                r.environment.length <= 16 &&
+                r.environment.every((e) => typeof e === "string" && ENVIRONMENT.test(e))))
+            throw new Error(`policy ${r.id}: environment must be a list of 1-16 environment names (^[a-z][a-z0-9-]{0,31}$)`);
     }
     const ids = doc.rules.map((r) => r.id);
     const twice = ids.find((id, i) => ids.indexOf(id) !== i);
@@ -76,7 +118,10 @@ function checkShadowed(rules) {
                 (e.args_match === later.args_match && !!e.ignore_case === !!later.ignore_case)) &&
             (e.hints === undefined ||
                 (later.hints !== undefined &&
-                    Object.entries(e.hints).every(([k, v]) => later.hints[k] === v))));
+                    Object.entries(e.hints).every(([k, v]) => later.hints[k] === v))) &&
+            (e.environment === undefined ||
+                (later.environment !== undefined &&
+                    later.environment.every((x) => e.environment.includes(x)))));
         if (first && first.action !== later.action)
             throw new Error(`policy ${later.id}: never applies: ${first.id} matches the same calls first (${first.action})`);
     });
@@ -90,15 +135,30 @@ export function compilePolicy(policy) {
             : new RegExp(rule.args_match, rule.ignore_case ? "i" : ""),
     }));
 }
+/** spec/api.md: the session's environment, from its `session.open` (the first line). */
+export function environmentOf(lines) {
+    const first = lines[0];
+    if (first === undefined)
+        return undefined;
+    const e = JSON.parse(first);
+    const env = e.kind === "session.open" ? e.meta?.environment : undefined;
+    return typeof env === "string" ? env : undefined;
+}
+/** A rule with `environment` holds only in a session whose environment it lists. */
+const environmentMatch = (rule, environment) => rule.environment === undefined ||
+    (environment !== undefined && rule.environment.includes(environment));
 /** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool
- * has two). `hints`: an MCP tool's annotations; a rule with `hints` never matches a call without. */
-export function decide(compiled, names, args, hints) {
+ * has two). `hints`: an MCP tool's annotations; a rule with `hints` never matches a call without.
+ * `environment`: the session's; a rule with `environment` never matches a session without one. */
+export function decide(compiled, names, args, hints, environment) {
     let text = null;
     for (const c of compiled) {
         if (c.rule.audit === true || !names.some((n) => c.tool.test(n)))
             continue;
         if (!hintsMatch(c.rule.hints, hints))
             continue;
+        if (!environmentMatch(c.rule, environment))
+            continue;
         if (c.args) {
             text ??= canonical(args ?? null).slice(0, MAX_ARGS);
             if (!c.args.test(text))
@@ -113,11 +173,12 @@ export function decide(compiled, names, args, hints) {
     return null;
 }
 /** N3 (idea C5): every audit rule this call matches, and what it would do if it were enforced. */
-export function audited(compiled, names, args, hints) {
+export function audited(compiled, names, args, hints, environment) {
     const text = canonical(args ?? null).slice(0, MAX_ARGS);
     return compiled
         .filter((c) => c.rule.audit === true && names.some((n) => c.tool.test(n)))
         .filter((c) => hintsMatch(c.rule.hints, hints))
+        .filter((c) => environmentMatch(c.rule, environment))
         .filter((c) => !c.args || c.args.test(text))
         .map((c) => ({ rule: c.rule.id, would: c.rule.action }));
 }
@@ -131,6 +192,86 @@ function auditFinding(rule, would, at, tool) {
         detail: `Policy ${rule} (audit only) would ${would === "deny" ? "have refused" : "have held"} ${String(tool ?? "a tool call")}.`,
     };
 }
+/**
+ * spec/policy.md §9: each successful result of a call a `require_proof` rule decided must carry a
+ * valid tool witness (spec/data.md §9) or the rule's `field`, the touched system's own id.
+ */
+function unproven(lines, bodies, compiled) {
+    const out = [];
+    const environment = environmentOf(lines);
+    const pending = new Map();
+    const sdkPending = new Map();
+    const json = (hash) => {
+        const b = bodies(hash);
+        if (!b)
+            return undefined;
+        try {
+            return JSON.parse(new TextDecoder().decode(b));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const ruleOf = (names, args, hints) => {
+        const d = decide(compiled, names, args, hints, environment);
+        return d?.action === "require_proof"
+            ? compiled.find((c) => c.rule.id === d.rule)?.rule
+            : undefined;
+    };
+    const proven = (rule, meta, result) => meta.witness?.ok === true ||
+        (rule.field !== undefined && hasEvidence(result, rule.field));
+    const finding = (seq, rule, tool) => ({
+        code: "UNPROVEN_SIDE_EFFECT",
+        source: "policy",
+        severity: "warning",
+        ref: { seq, rule: rule.id, tool },
+        detail: `${tool} ran under policy ${rule.id}, and its result carries no witness${rule.field ? ` or ${rule.field}` : ""}.`,
+    });
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        const m = e.meta;
+        if (e.kind === "tool.call" && typeof m.tool === "string" && m.via !== "broker") {
+            if (m.policy?.action === "deny")
+                continue;
+            const body = json(e.body_hash);
+            const names = [
+                m.tool,
+                ...(typeof m.server === "string" ? [`mcp__${m.server}__${m.tool}`] : []),
+            ];
+            const rule = ruleOf(names, body?.params?.arguments ?? {}, m.hints);
+            if (rule)
+                pending.set(e.seq, { rule, tool: m.tool });
+        }
+        else if (e.kind === "tool.result" && typeof m.call_seq === "number") {
+            const p = pending.get(m.call_seq);
+            if (!p)
+                continue;
+            pending.delete(m.call_seq);
+            const r = json(e.body_hash);
+            if (r === undefined || r.error !== undefined || r.result?.isError === true)
+                continue;
+            if (!proven(p.rule, m, r.result ?? r))
+                out.push(finding(e.seq, p.rule, p.tool));
+        }
+        else if (e.kind === "sdk.event" && m.type === "tool.call" && typeof m.name === "string") {
+            const d = json(e.body_hash);
+            const rule = ruleOf([m.name], d?.args ?? {});
+            if (rule)
+                sdkPending.set(m.name, [...(sdkPending.get(m.name) ?? []), { rule, tool: m.name }]);
+        }
+        else if (e.kind === "sdk.event" && m.type === "tool.result" && typeof m.name === "string") {
+            const p = sdkPending.get(m.name)?.shift();
+            if (!p)
+                continue;
+            const d = json(e.body_hash);
+            if (d === undefined || d.ok === false)
+                continue;
+            if (!proven(p.rule, m, d))
+                out.push(finding(e.seq, p.rule, p.tool));
+        }
+    }
+    return out;
+}
 /**
  * spec/policy.md §2 as findings: POLICY_DENIED for MCP calls the gateway refused (tool.call meta.policy),
  * POLICY_VIOLATION for tools a model response asked for that a deny rule matches.
@@ -153,12 +294,14 @@ export function policyFindings(lines, bodies, compiled) {
             if (typeof a.rule === "string" && a.would !== "allow")
                 out.push(auditFinding(a.rule, String(a.would), { seq: e.seq }, e.meta.tool));
     }
+    out.push(...unproven(lines, bodies, compiled));
     const calls = [...callsOf(lines, bodies)].sort((a, b) => a.endSeq - b.endSeq);
+    const environment = environmentOf(lines);
     const violation = (tool, id, args) => {
-        for (const a of audited(compiled, [tool], args))
+        for (const a of audited(compiled, [tool], args, undefined, environment))
             if (a.would !== "allow")
                 out.push(auditFinding(a.rule, a.would, { tool_use_id: id }, tool));
-        const d = decide(compiled, [tool], args);
+        const d = decide(compiled, [tool], args, undefined, environment);
         if (d?.action === "deny")
             out.push({
                 code: "POLICY_VIOLATION",

package/dist/policy/zanii.d.ts

@@ -0,0 +1,31 @@
+type OurRule = {
+    id: string;
+    tool: string;
+    action: string;
+    [key: string]: unknown;
+};
+type Skipped = {
+    id: string;
+    reason: string;
+};
+/** Zanii → Blackbox: `{policy: {version: 1, rules}, skipped}`. */
+export declare function fromZaniiPolicy(z: unknown): {
+    policy: {
+        version: 1;
+        rules: OurRule[];
+    };
+    skipped: Skipped[];
+};
+/** Blackbox → Zanii: `{policy: {default: "allow", rules}, skipped}`. */
+export declare function toZaniiPolicy(ours: unknown): {
+    policy: {
+        default: "allow";
+        rules: Array<{
+            id: string;
+            effect: string;
+            targets: string[];
+        }>;
+    };
+    skipped: Skipped[];
+};
+export {};