@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/packs/index.js

@@ -0,0 +1,343 @@
+// Framework packs (spec/packs.md): compliance and occurrence frameworks as data a deployment
+// switches on. Pure; mirrors sdks/python/src/zanii_blackbox/packs.py; pinned by
+// spec/vectors/packs.json. The `data` part is spec/data.md §4.
+import { CORE_EVIDENCE, CORE_IDENTIFIERS } from "../data/index.js";
+const FACTS = new Set([
+    "sessions",
+    "events",
+    "sessions_verified",
+    "sessions_anchored",
+    "redactions",
+    "findings_warning",
+    "bypasses",
+    "false_claims",
+    "blocks",
+    "emergency_stops",
+    "resumes_with_note",
+    "outcomes",
+    "data_region",
+]);
+const FILLS = new Set(["record", "findings", "redactions", "operator"]);
+const PACK_ID = /^[a-z0-9-]{1,64}$/;
+const FRAMEWORK_ID = /^[a-z0-9_-]{1,64}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+// Lengths in code points, as Python counts them (spec/packs.md §1).
+const text = (v, max) => typeof v === "string" && v.length >= 1 && [...v].length <= max;
+const only = (o, keys) => Object.keys(o).every((k) => keys.includes(k));
+function checkSections(sections, max, at, check) {
+    if (!Array.isArray(sections) || sections.length < 1 || sections.length > max)
+        return `${at}.sections must hold 1-${max} sections`;
+    const ids = new Set();
+    for (const [i, s] of sections.entries()) {
+        const sat = `${at}.sections[${i}]`;
+        if (!isObj(s))
+            return `${sat} must be an object`;
+        if (typeof s.id !== "string" || !FRAMEWORK_ID.test(s.id))
+            return `${sat}.id must be 1-64 of a-z 0-9 _ -`;
+        if (ids.has(s.id))
+            return `${sat}.id ${s.id} repeats`;
+        ids.add(s.id);
+        if (!text(s.title, 500))
+            return `${sat}.title must be 1-500 characters`;
+        const bad = check(s, sat);
+        if (bad)
+            return bad;
+    }
+    return undefined;
+}
+function checkPart(part, kind) {
+    if (!isObj(part) || !only(part, ["notes", "notes_ar", "frameworks"]))
+        return `${kind} must be {notes, frameworks}`;
+    if (!text(part.notes, 2000))
+        return `${kind}.notes must be 1-2000 characters`;
+    if (part.notes_ar !== undefined && !text(part.notes_ar, 2000))
+        return `${kind}.notes_ar must be 1-2000 characters`;
+    const fws = part.frameworks;
+    if (!isObj(fws) || Object.keys(fws).length < 1 || Object.keys(fws).length > 50)
+        return `${kind}.frameworks must hold 1-50 frameworks`;
+    for (const [id, fw] of Object.entries(fws)) {
+        const at = `${kind}.frameworks.${id}`;
+        if (!FRAMEWORK_ID.test(id))
+            return `${at}: the id must be 1-64 of a-z 0-9 _ -`;
+        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`;
+            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`;
+                if (!text(s.requirement, 2000))
+                    return `${sat}.requirement must be 1-2000 characters`;
+                if (!Array.isArray(s.facts) || s.facts.length < 1 || s.facts.length > 20)
+                    return `${sat}.facts must hold 1-20 fact keys`;
+                const unknown = s.facts.find((f) => typeof f !== "string" || !FACTS.has(f));
+                return unknown === undefined
+                    ? undefined
+                    : `${sat}.facts: unknown fact ${JSON.stringify(unknown)}`;
+            });
+            if (bad)
+                return bad;
+        }
+        else {
+            if (!only(fw, ["title", "authority", "deadlines", "sections", "ar"]))
+                return `${at} may only have title, authority, deadlines, sections`;
+            if (!text(fw.authority, 500))
+                return `${at}.authority must be 1-500 characters`;
+            if (!Array.isArray(fw.deadlines) ||
+                fw.deadlines.length < 1 ||
+                fw.deadlines.length > 10 ||
+                !fw.deadlines.every((d) => text(d, 500)))
+                return `${at}.deadlines must hold 1-10 texts of 1-500 characters`;
+            const bad = checkSections(fw.sections, 30, at, (s, sat) => {
+                if (!only(s, ["id", "title", "fill"]))
+                    return `${sat} may only have id, title, fill`;
+                return FILLS.has(s.fill)
+                    ? undefined
+                    : `${sat}.fill must be record, findings, redactions or operator`;
+            });
+            if (bad)
+                return bad;
+            if (fw.ar !== undefined) {
+                const badAr = checkArabic(fw.ar, fw, `${at}.ar`);
+                if (badAr)
+                    return badAr;
+            }
+        }
+    }
+    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"]))
+        return `${at} must be {title, authority, deadlines, sections}`;
+    if (!text(ar.title, 500) || !text(ar.authority, 500))
+        return `${at}.title and .authority must be 1-500 characters`;
+    const deadlines = fw.deadlines;
+    if (!Array.isArray(ar.deadlines) ||
+        ar.deadlines.length !== deadlines.length ||
+        !ar.deadlines.every((d) => text(d, 500)))
+        return `${at}.deadlines must translate each deadline`;
+    const ids = fw.sections.map((s) => s.id);
+    const titles = ar.sections;
+    if (!isObj(titles) ||
+        Object.keys(titles).length !== ids.length ||
+        !ids.every((id) => text(titles[id], 500)))
+        return `${at}.sections must translate each section's title, by id`;
+    return undefined;
+}
+/** spec/packs.md §1: why a pack is invalid, or undefined. */
+export function checkPack(value) {
+    if (!isObj(value))
+        return "a pack must be an object";
+    // `data` came later (spec/data.md §4); the pinned messages below name the v1 keys only.
+    if (!only(value, [
+        "data",
+        "v",
+        "id",
+        "title",
+        "status",
+        "reviewed_by",
+        "reviewed_at",
+        "compliance",
+        "occurrence",
+    ]))
+        return "a pack may only have v, id, title, status, reviewed_by, reviewed_at, compliance, occurrence";
+    if (value.v !== 1)
+        return "v must be 1";
+    if (typeof value.id !== "string" || !PACK_ID.test(value.id))
+        return "id must be 1-64 of a-z 0-9 -";
+    if (!text(value.title, 200))
+        return "title must be 1-200 characters";
+    if (value.status !== "draft" && value.status !== "reviewed")
+        return "status must be draft or reviewed";
+    if (value.status === "reviewed" &&
+        (!text(value.reviewed_by, 200) ||
+            typeof value.reviewed_at !== "string" ||
+            !DATE.test(value.reviewed_at)))
+        return "a reviewed pack needs reviewed_by and reviewed_at (YYYY-MM-DD)";
+    if (value.compliance === undefined && value.occurrence === undefined && value.data === undefined)
+        return "a pack needs compliance, occurrence or both";
+    for (const kind of ["compliance", "occurrence"])
+        if (value[kind] !== undefined) {
+            const bad = checkPart(value[kind], kind);
+            if (bad)
+                return bad;
+        }
+    return value.data === undefined ? undefined : checkData(value.data);
+}
+const IDENTIFIER_ID = /^[a-z0-9_]{1,64}$/;
+const NORMALIZE = new Set(["digits", "lower", "upper", "exact"]);
+// Escapes Python reads over Unicode and JavaScript over ASCII (spec/data.md §1).
+const UNPORTABLE = /\\[dDwWbBsS]/;
+const ALLOW = /^(?:region|model|tool|api):(?:[A-Za-z0-9._-]{1,128}\*?|\*)$/;
+const TOOL = /^[A-Za-z0-9._-]{1,128}$/;
+const FIELD = /^[A-Za-z0-9_.-]{1,64}$/;
+const compiles = (pattern) => {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** spec/data.md §1: why an identifier is invalid, or undefined. */
+export function checkIdentifier(v, at) {
+    if (!isObj(v) ||
+        !only(v, ["id", "title", "pattern", "normalize", "keep_last", "check", "personal"]))
+        return `${at} may only have id, title, pattern, normalize, keep_last, check, personal`;
+    if (typeof v.id !== "string" || !IDENTIFIER_ID.test(v.id))
+        return `${at}.id must be 1-64 of a-z 0-9 _`;
+    if (!text(v.title, 200))
+        return `${at}.title must be 1-200 characters`;
+    if (typeof v.pattern !== "string" || !text(v.pattern, 500) || !compiles(v.pattern))
+        return `${at}.pattern must be a regular expression of 1-500 characters`;
+    if (UNPORTABLE.test(v.pattern))
+        return `${at}.pattern must not use \\d \\w \\b or \\s`;
+    if (!NORMALIZE.has(v.normalize))
+        return `${at}.normalize must be digits, lower, upper or exact`;
+    if (v.keep_last !== undefined &&
+        (!Number.isInteger(v.keep_last) || v.keep_last < 1 || v.keep_last > 30))
+        return `${at}.keep_last must be 1-30`;
+    if (v.check !== undefined && v.check !== "luhn")
+        return `${at}.check must be luhn`;
+    if (typeof v.personal !== "boolean")
+        return `${at}.personal must be true or false`;
+    return undefined;
+}
+function checkData(part) {
+    if (!isObj(part) || !only(part, ["notes", "identifiers", "residency", "restricted", "evidence"]))
+        return "data may only have notes, identifiers, residency, restricted, evidence";
+    if (!text(part.notes, 2000))
+        return "data.notes must be 1-2000 characters";
+    const ids = part.identifiers ?? [];
+    if (!Array.isArray(ids) || ids.length > 50)
+        return "data.identifiers must hold 0-50 identifiers";
+    const seen = new Set(CORE_IDENTIFIERS.map((i) => i.id));
+    for (const [i, v] of ids.entries()) {
+        const bad = checkIdentifier(v, `data.identifiers[${i}]`);
+        if (bad)
+            return bad;
+        const id = v.id;
+        if (seen.has(id))
+            return `data.identifiers[${i}].id ${id} is already defined`;
+        seen.add(id);
+    }
+    if (part.residency !== undefined && typeof part.residency !== "boolean")
+        return "data.residency must be true or false";
+    const rules = part.restricted ?? [];
+    if (!Array.isArray(rules) || rules.length > 50)
+        return "data.restricted must hold 0-50 rules";
+    for (const [i, r] of rules.entries()) {
+        const at = `data.restricted[${i}]`;
+        if (!isObj(r) || !only(r, ["identifiers", "allow"]))
+            return `${at} must be {identifiers, allow}`;
+        if (!Array.isArray(r.identifiers) ||
+            r.identifiers.length < 1 ||
+            r.identifiers.length > 50 ||
+            !r.identifiers.every((x) => typeof x === "string" && seen.has(x)))
+            return `${at}.identifiers must hold 1-50 known identifier ids`;
+        if (!Array.isArray(r.allow) ||
+            r.allow.length < 1 ||
+            r.allow.length > 20 ||
+            !r.allow.every((x) => typeof x === "string" && ALLOW.test(x)))
+            return `${at}.allow must hold 1-20 of region:, model:, tool:, api:`;
+    }
+    const evidence = part.evidence ?? [];
+    if (!Array.isArray(evidence) || evidence.length > 200)
+        return "data.evidence must hold 0-200 rules";
+    for (const [i, e] of evidence.entries())
+        if (!isObj(e) ||
+            !only(e, ["tool", "field"]) ||
+            typeof e.tool !== "string" ||
+            !TOOL.test(e.tool) ||
+            typeof e.field !== "string" ||
+            !FIELD.test(e.field))
+            return `data.evidence[${i}] must be {tool, field}`;
+    return undefined;
+}
+/**
+ * spec/data.md §4: the data rules of packs merged in order, then the core. Pack identifiers come
+ * before the core ones; throws on an invalid pack or an identifier id in two packs.
+ */
+export function packData(packs) {
+    const identifiers = [];
+    const restricted = [];
+    const evidence = [];
+    const owner = new Map();
+    let residency = false;
+    for (const p of packs) {
+        const bad = checkPack(p);
+        const id = isObj(p) && typeof p.id === "string" ? p.id : "?";
+        if (bad)
+            throw new Error(`pack ${id}: ${bad}`);
+        const data = p.data;
+        if (!data)
+            continue;
+        for (const ident of data.identifiers ?? []) {
+            const had = owner.get(ident.id);
+            if (had)
+                throw new Error(`identifier ${ident.id} is in packs ${had} and ${id}`);
+            owner.set(ident.id, id);
+            identifiers.push(ident);
+        }
+        residency ||= data.residency === true;
+        restricted.push(...(data.restricted ?? []));
+        evidence.push(...(data.evidence ?? []));
+    }
+    identifiers.push(...CORE_IDENTIFIERS);
+    return { identifiers, residency, restricted, evidence: [...evidence, ...CORE_EVIDENCE] };
+}
+/** spec/packs.md §2: the core pack, from the built-in frameworks files. */
+export function corePack(compliance, occurrence) {
+    return {
+        v: 1,
+        id: "core",
+        title: "Core (built in)",
+        status: "draft",
+        compliance: { notes: compliance.notes, frameworks: compliance.frameworks },
+        occurrence: {
+            notes: occurrence.notes,
+            ...(occurrence.notes_ar ? { notes_ar: occurrence.notes_ar } : {}),
+            frameworks: occurrence.frameworks,
+        },
+    };
+}
+/** spec/packs.md §2: packs merged in order; throws on an invalid pack or a repeated framework id. */
+export function packFrameworks(packs) {
+    const out = {
+        compliance: {},
+        occurrence: {},
+    };
+    const seen = new Set();
+    for (const p of packs) {
+        const bad = checkPack(p);
+        const id = isObj(p) && typeof p.id === "string" ? p.id : "?";
+        if (bad)
+            throw new Error(`pack ${id}: ${bad}`);
+        const pack = p;
+        if (seen.has(id))
+            throw new Error(`pack ${id} is listed twice`);
+        seen.add(id);
+        for (const kind of ["compliance", "occurrence"]) {
+            const part = pack[kind];
+            if (!part)
+                continue;
+            for (const [fid, fw] of Object.entries(part.frameworks)) {
+                const had = out[kind][fid];
+                if (had)
+                    throw new Error(`${kind} framework ${fid} is in packs ${had.pack} and ${id}`);
+                out[kind][fid] = {
+                    pack: id,
+                    status: pack.status,
+                    notes: part.notes,
+                    ...(part.notes_ar ? { notes_ar: part.notes_ar } : {}),
+                    framework: fw,
+                };
+            }
+        }
+    }
+    return out;
+}

package/dist/policy/delta.d.ts

@@ -0,0 +1,11 @@
+import type { Policy } from "./index.ts";
+export interface PolicyChange {
+    rule: string;
+    change: "added" | "removed" | "weakened" | "strengthened" | "modified" | "moved";
+    adds_power: boolean;
+}
+export interface PolicyDelta {
+    adds_power: boolean;
+    changes: PolicyChange[];
+}
+export declare function policyDelta(current: Policy, proposed: Policy): PolicyDelta;

package/dist/policy/delta.js

@@ -0,0 +1,39 @@
+// Policy deltas (spec/policy.md §6, idea C4): does a proposed policy give agents more power than the
+// current one? A change that adds none can be applied without a second person. Conservative: when
+// 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 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]));
+    const after = new Map(proposed.rules.map((r) => [r.id, r]));
+    const changes = [];
+    for (const r of proposed.rules) {
+        const old = before.get(r.id);
+        if (!old) {
+            changes.push({ rule: r.id, change: "added", adds_power: rank(r) < 1 });
+            continue;
+        }
+        if (matcher(old) !== matcher(r))
+            changes.push({ rule: r.id, change: "modified", adds_power: rank(old) > 1 || rank(r) < 1 });
+        else if (rank(r) !== rank(old))
+            changes.push({
+                rule: r.id,
+                change: rank(r) < rank(old) ? "weakened" : "strengthened",
+                adds_power: rank(r) < rank(old),
+            });
+    }
+    for (const r of current.rules)
+        if (!after.has(r.id))
+            changes.push({ rule: r.id, change: "removed", adds_power: rank(r) > 1 });
+    // First match wins, so the order of the rules both keep matters: any move may open something.
+    const kept = (rules, other) => rules.filter((r) => other.has(r.id)).map((r) => r.id);
+    const was = kept(current.rules, after);
+    const now = kept(proposed.rules, before);
+    now.forEach((id, i) => {
+        if (was[i] !== id)
+            changes.push({ rule: id, change: "moved", adds_power: true });
+    });
+    return { adds_power: changes.some((c) => c.adds_power), changes };
+}

package/dist/policy/drafts.d.ts

@@ -0,0 +1,34 @@
+import type { Rule } from "./index.ts";
+export interface DraftGroup {
+    rule: string;
+    tool: string;
+    denied: number;
+    audited: number;
+    held: number;
+    approved: number;
+    rejected: number;
+    timeout: number;
+    /** Sessions where a person granted the tool after this rule denied it (spec/approvals.md §4). */
+    granted: number;
+    sessions: number;
+    samples: Array<{
+        session_id: string;
+        seq: number;
+    }>;
+}
+export interface Draft {
+    /** `allow`: add `draft` before `rule`; `enforce`: remove `audit` from `rule`. */
+    kind: "allow" | "enforce";
+    rule: string;
+    tool: string;
+    confidence_pct: number;
+    why: string;
+    draft?: Rule;
+}
+export declare function policyDrafts(sessions: ReadonlyArray<{
+    session_id: string;
+    lines: readonly string[];
+}>): {
+    groups: DraftGroup[];
+    drafts: Draft[];
+};

package/dist/policy/drafts.js

@@ -0,0 +1,129 @@
+// Rule drafts from what the policy did (spec/policy.md §5, idea C6): denials, holds, audit hits and
+// grants, grouped by rule and tool, counted, with samples, and drafted into rule changes with a
+// confidence. Deterministic, no model. Mirrors policy/drafts.py.
+const SAMPLES = 3;
+/** The tool's policy name: `mcp__<server>__<tool>` for an MCP call. */
+const toolOf = (meta) => typeof meta.server === "string" && typeof meta.tool === "string"
+    ? `mcp__${meta.server}__${meta.tool}`
+    : String(meta.tool ?? "?");
+const allowId = (tool) => `allow-${tool
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")}`.slice(0, 64);
+export function policyDrafts(sessions) {
+    const groups = new Map();
+    const group = (rule, tool) => {
+        const key = `${rule}\n${tool}`;
+        let g = groups.get(key);
+        if (!g) {
+            g = {
+                rule,
+                tool,
+                denied: 0,
+                audited: 0,
+                held: 0,
+                approved: 0,
+                rejected: 0,
+                timeout: 0,
+                granted: 0,
+                sessions: 0,
+                samples: [],
+                seen: new Set(),
+            };
+            groups.set(key, g);
+        }
+        return g;
+    };
+    const touch = (g, sessionId, seq) => {
+        if (!g.seen.has(sessionId)) {
+            g.seen.add(sessionId);
+            g.sessions++;
+        }
+        if (g.samples.length < SAMPLES)
+            g.samples.push({ session_id: sessionId, seq });
+    };
+    for (const { session_id, lines } of sessions) {
+        const decisions = new Map();
+        const held = [];
+        const denied = new Set();
+        const grants = new Set();
+        for (const line of lines) {
+            const e = JSON.parse(line);
+            const meta = e.meta ?? {};
+            if (e.kind === "control") {
+                if (meta.action === "approval" && typeof meta.approval_id === "string")
+                    decisions.set(meta.approval_id, String(meta.decision));
+                if (meta.action === "permission" && typeof meta.tool === "string")
+                    grants.add(meta.tool);
+                continue;
+            }
+            if (e.kind !== "tool.call")
+                continue;
+            const tool = toolOf(meta);
+            const p = meta.policy;
+            if (typeof p?.rule === "string" && p.rule !== "supervised") {
+                const g = group(p.rule, tool);
+                if (p.action === "deny") {
+                    g.denied++;
+                    denied.add(g);
+                    touch(g, session_id, e.seq);
+                }
+                else if (p.action === "hold" && typeof p.approval_id === "string") {
+                    g.held++;
+                    held.push([g, p.approval_id]);
+                    touch(g, session_id, e.seq);
+                }
+            }
+            const hits = Array.isArray(meta.policy_audit) ? meta.policy_audit : [];
+            for (const a of hits)
+                if (typeof a.rule === "string") {
+                    const g = group(a.rule, tool);
+                    g.audited++;
+                    touch(g, session_id, e.seq);
+                }
+        }
+        for (const [g, id] of held) {
+            const d = decisions.get(id);
+            if (d === "approve")
+                g.approved++;
+            else if (d === "reject")
+                g.rejected++;
+            else if (d === "timeout")
+                g.timeout++;
+        }
+        for (const g of denied)
+            if (grants.has(g.tool))
+                g.granted++;
+    }
+    const out = [...groups.values()]
+        .map(({ seen: _, ...g }) => g)
+        .sort((a, b) => (a.rule === b.rule ? cmp(a.tool, b.tool) : cmp(a.rule, b.rule)));
+    const drafts = [];
+    for (const g of out) {
+        if (g.audited > 0)
+            drafts.push({
+                kind: "enforce",
+                rule: g.rule,
+                tool: g.tool,
+                confidence_pct: Math.min(100, g.sessions * 20),
+                why: `audit only: it would have acted ${g.audited} times in ${g.sessions} sessions`,
+            });
+        const byApproval = g.held >= 5 && g.approved === g.held ? Math.min(100, g.approved * 5) : 0;
+        const byGrant = g.granted >= 3 ? Math.min(100, g.granted * 20) : 0;
+        if (byApproval || byGrant)
+            drafts.push({
+                kind: "allow",
+                rule: g.rule,
+                tool: g.tool,
+                confidence_pct: Math.max(byApproval, byGrant),
+                why: byGrant >= byApproval
+                    ? `a person granted it in ${g.granted} sessions after ${g.rule} denied it`
+                    : `a person approved all ${g.approved} held calls`,
+                draft: { id: allowId(g.tool), tool: g.tool, action: "allow" },
+            });
+    }
+    drafts.sort((a, b) => b.confidence_pct - a.confidence_pct || cmp(a.rule, b.rule) || cmp(a.tool, b.tool));
+    return { groups: out, drafts };
+}
+/** Code-point order, the same in both SDKs. */
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);

package/dist/policy/index.d.ts

@@ -0,0 +1,47 @@
+import type { Finding } from "../analysis/index.ts";
+import { type Bodies } from "../reconcile/record.ts";
+import { type Compensation } from "../undo/index.ts";
+export interface Rule {
+    id: string;
+    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";
+    reason?: string;
+    /** N3 (idea C5): record-only. Never decides a call; what it would do is recorded (POLICY_AUDIT). */
+    audit?: boolean;
+}
+export interface Policy {
+    version: 1;
+    rules: Rule[];
+    /** spec/undo.md §1: how to reverse each risky tool. */
+    compensations?: Compensation[];
+}
+export interface Decision {
+    rule: string;
+    action: "deny" | "allow" | "require_approval";
+    reason?: string;
+}
+interface Compiled {
+    rule: Rule;
+    tool: RegExp;
+    args: RegExp | null;
+}
+/** 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[];
+/** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool has two). */
+export declare function decide(compiled: readonly Compiled[], names: readonly string[], args: unknown): 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): Array<{
+    rule: string;
+    would: Rule["action"];
+}>;
+/**
+ * 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.
+ */
+export declare function policyFindings(lines: readonly string[], bodies: Bodies, compiled: CompiledPolicy): Finding[];
+export {};