@zanii/blackbox 0.22.0 → 0.23.0

package/dist/aviation/index.js

@@ -0,0 +1,1014 @@
+// Aviation practices for agent fleets (spec/aviation.md): clearances and resolution advisories,
+// NOTAMs, the emergency locator, the protected reasoning track, safety reports, the quick
+// reference handbook, the commit point, mayday, envelope protection, the load sheet and OpSpecs.
+// Pure; mirrors sdks/python/src/zanii_blackbox/aviation.py; pinned by spec/vectors/aviation-*.json.
+import { createHash } from "node:crypto";
+import { docHash } from "../admission/index.js";
+import { faultOf } from "../analysis/faults.js";
+import { authorityTimeline } from "../authority/index.js";
+import { callMicroUsd, priceFor, sessionCost } from "../cost/index.js";
+import { resourceChanges, verifyCertificate } from "../fleet/index.js";
+import { canonical } from "../reconcile/shared.js";
+import { QRH } from "./qrh.js";
+export { QRH };
+const parse = (lines) => lines.map((l) => JSON.parse(l));
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** A `*` pattern as a whole-name match (spec/policy.md §1's tool patterns). */
+export function globMatch(pattern, name) {
+    const re = pattern
+        .split("*")
+        .map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${re}$`, "s").test(name);
+}
+/** spec/aviation.md §1: may this session have the resource now? §2: and what each side does. */
+export function clearance(active, request) {
+    const at = Date.parse(request.at);
+    const conflicts = active
+        .filter((c) => c.resource === request.resource &&
+        c.session_id !== request.session_id &&
+        Date.parse(c.expires_at) > at &&
+        !(c.mode === "shared" && request.mode === "shared"))
+        .map(({ session_id, mode, expires_at }) => ({ session_id, mode, expires_at }))
+        .sort((a, b) => Date.parse(a.expires_at) - Date.parse(b.expires_at) || cmp(a.session_id, b.session_id));
+    if (conflicts.length === 0)
+        return { decision: "granted", conflicts: [], advisories: [] };
+    const first = Date.parse(conflicts[0].expires_at);
+    return {
+        decision: "hold",
+        retry_after_s: Math.max(1, Math.ceil((first - at) / 1000)),
+        conflicts,
+        advisories: [
+            { session_id: request.session_id, action: "hold" },
+            ...conflicts.map((c) => ({ session_id: c.session_id, action: "proceed" })),
+        ],
+    };
+}
+/** spec/aviation.md §1: each change made without an exclusive clearance in force for it. */
+export function clearanceFindings(lines, bodies) {
+    const events = parse(lines);
+    const ts = new Map(events.map((e) => [e.seq, Date.parse(e.ts)]));
+    const granted = new Map();
+    const released = new Map();
+    for (const e of events) {
+        if (e.kind !== "control")
+            continue;
+        const m = e.meta;
+        if (m.action === "clearance" &&
+            m.decision === "granted" &&
+            m.mode === "exclusive" &&
+            typeof m.clearance_id === "string" &&
+            typeof m.resource === "string" &&
+            typeof m.expires_at === "string")
+            granted.set(m.clearance_id, {
+                seq: e.seq,
+                resource: m.resource,
+                expires: Date.parse(m.expires_at),
+            });
+        if (m.action === "clearance_release" && typeof m.clearance_id === "string")
+            released.set(m.clearance_id, e.seq);
+    }
+    const out = [];
+    for (const c of resourceChanges(lines, bodies)) {
+        const at = ts.get(c.seq) ?? 0;
+        const covered = [...granted].some(([id, g]) => g.resource === c.resource &&
+            g.seq < c.seq &&
+            g.expires > at &&
+            !((released.get(id) ?? Number.POSITIVE_INFINITY) < c.seq));
+        if (!covered)
+            out.push({
+                code: "NO_CLEARANCE",
+                source: "clearance",
+                severity: "caution",
+                ref: { seq: c.seq, resource: c.resource },
+            });
+    }
+    return out;
+}
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+const DAY_MS = 86_400_000;
+const isoMs = (v) => typeof v === "string" && ISO.test(v) && Number.isFinite(Date.parse(v)) ? Date.parse(v) : null;
+const listOf = (v, max, ok) => v === undefined
+    ? []
+    : Array.isArray(v) && v.length <= max && v.every((x) => typeof x === "string" && ok(x))
+        ? v
+        : null;
+/** No control characters (newlines too, unless allowed). */
+const plain = (text, newlines = false) => ![...text].some((ch) => (ch < " " && !(newlines && ch === "\n")) || ch === "\u007f");
+/** spec/aviation.md §3: a notice's fields with defaults filled in, or an error message. */
+export function checkNotam(input, now) {
+    const { text } = input;
+    if (typeof text !== "string" || text.length < 1 || text.length > 1000 || !plain(text, true))
+        return { ok: false, error: "text must be 1-1000 characters, no control characters" };
+    const from = input.from === undefined ? Date.parse(now) : isoMs(input.from);
+    if (from === null)
+        return { ok: false, error: "from must be a UTC ISO-8601 time" };
+    const until = isoMs(input.until);
+    if (until === null)
+        return { ok: false, error: "until must be a UTC ISO-8601 time" };
+    if (until <= from || until - from > 90 * DAY_MS)
+        return { ok: false, error: "until must be after from, at most 90 days after it" };
+    const tools = listOf(input.tools, 50, (x) => x.length >= 1 && x.length <= 128 && plain(x));
+    if (tools === null)
+        return { ok: false, error: "tools must be up to 50 patterns of 1-128 characters" };
+    const providers = listOf(input.providers, 20, (x) => /^[a-z0-9][a-z0-9_-]{0,63}$/.test(x));
+    if (providers === null)
+        return { ok: false, error: "providers must be up to 20 provider ids" };
+    const effect = input.effect ?? "inform";
+    if (effect !== "inform" && effect !== "avoid")
+        return { ok: false, error: "effect must be inform or avoid" };
+    return {
+        ok: true,
+        notam: {
+            text,
+            from: new Date(from).toISOString(),
+            until: new Date(until).toISOString(),
+            tools,
+            providers,
+            effect,
+        },
+    };
+}
+/** spec/aviation.md §3: the notices in force at `at` for a tenant, by `from` then `id`. */
+export function notamsInForce(notams, at, tenant) {
+    const t = Date.parse(at);
+    return notams
+        .filter((n) => !(n.cancelled_at !== null && Date.parse(n.cancelled_at) <= t) &&
+        Date.parse(n.from) <= t &&
+        t < Date.parse(n.until) &&
+        (n.tenant === null || n.tenant === tenant))
+        .sort((a, b) => Date.parse(a.from) - Date.parse(b.from) || cmp(a.id, b.id));
+}
+/** spec/aviation.md §3: the first event each `avoid` notice in force covers. */
+export function notamFindings(lines, notams) {
+    const events = parse(lines);
+    const tenant = events[0]?.kind === "session.open" ? events[0].meta.tenant : undefined;
+    const avoid = notams.filter((n) => n.effect === "avoid");
+    const out = [];
+    const hit = new Set();
+    for (const e of events) {
+        let names = [];
+        let provider;
+        if (e.kind === "tool.call" && e.meta.method === "tools/call" && typeof e.meta.tool === "string")
+            names = [`mcp__${String(e.meta.server)}__${e.meta.tool}`, e.meta.tool];
+        else if (e.kind === "llm.request" && typeof e.meta.provider === "string")
+            provider = e.meta.provider;
+        else
+            continue;
+        for (const n of notamsInForce(avoid, e.ts, typeof tenant === "string" ? tenant : null)) {
+            if (hit.has(n.id))
+                continue;
+            const covers = provider !== undefined
+                ? n.providers.includes(provider)
+                : n.tools.some((p) => names.some((name) => globMatch(p, name)));
+            if (!covers)
+                continue;
+            hit.add(n.id);
+            out.push({
+                code: "NOTAM_CONFLICT",
+                source: "notam",
+                severity: "caution",
+                ref: { seq: e.seq, notam: n.id },
+            });
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------- §9 the commit point
+/** spec/aviation.md §9: the seq of the session's first `commit_point` SDK event, or null. */
+export function commitPointSeq(lines) {
+    for (const e of parse(lines))
+        if (e.kind === "sdk.event" &&
+            e.meta.type === "commit_point" &&
+            e.meta.duplicate_of === undefined)
+            return e.seq;
+    return null;
+}
+/** spec/aviation.md §9: a non-critical finding that comes after the commit point. */
+export function pastCommitPoint(lines, finding) {
+    const at = commitPointSeq(lines);
+    if (at === null || finding.severity === "warning")
+        return false;
+    const seq = finding.ref.seq;
+    return typeof seq === "number" ? seq > at : true;
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isInt = (v) => typeof v === "number" && Number.isSafeInteger(v);
+/** The output-token limits of a model request, in the order they're read and capped. */
+const OUTPUT_LIMITS = [
+    ["max_tokens"],
+    ["max_completion_tokens"],
+    ["max_output_tokens"],
+    ["generationConfig", "maxOutputTokens"],
+    ["inferenceConfig", "maxTokens"],
+];
+/** The object holding a limit, and its key. */
+const limitAt = (body, path) => {
+    const holder = path.length === 1 ? body : body[path[0]];
+    return { holder: isObj(holder) ? holder : undefined, key: path[path.length - 1] };
+};
+/** spec/aviation.md §15: an error message, or null for a valid envelope. */
+export function checkEnvelope(doc) {
+    if (!isObj(doc) || doc.v !== 1)
+        return "the envelope must be {v: 1, ...}";
+    const extra = Object.keys(doc).filter((k) => !["v", "forbidden_tools", "max_output_tokens"].includes(k));
+    if (extra.length)
+        return `the envelope has an unknown field: ${extra.sort().join(", ")}`;
+    const tools = doc.forbidden_tools;
+    if (tools !== undefined &&
+        !(Array.isArray(tools) &&
+            tools.length <= 100 &&
+            tools.every((t) => typeof t === "string" && t.length >= 1 && t.length <= 128 && plain(t))))
+        return "forbidden_tools must be up to 100 tool patterns of 1-128 characters";
+    const max = doc.max_output_tokens;
+    if (max !== undefined && !(isInt(max) && max >= 1 && max <= 1_000_000))
+        return "max_output_tokens must be an integer 1-1000000";
+    return null;
+}
+/** A tool definition's name: Anthropic's `name`, or Chat Completions' `function.name`. */
+const toolName = (t) => {
+    if (!isObj(t))
+        return undefined;
+    if (typeof t.name === "string")
+        return t.name;
+    return isObj(t.function) && typeof t.function.name === "string" ? t.function.name : undefined;
+};
+/** spec/aviation.md §15: the request inside the envelope, and what changed; null when nothing did. */
+export function shapeRequest(body, envelope) {
+    if (!isObj(body))
+        return null;
+    const out = structuredClone(body);
+    const changes = [];
+    const cap = envelope.max_output_tokens;
+    if (cap !== undefined)
+        for (const path of OUTPUT_LIMITS) {
+            const { holder, key } = limitAt(out, path);
+            const v = holder?.[key];
+            if (holder && isInt(v) && v > cap) {
+                holder[key] = cap;
+                changes.push({ field: path.join("."), from: v, to: cap });
+            }
+        }
+    const forbidden = envelope.forbidden_tools ?? [];
+    if (forbidden.length && Array.isArray(out.tools)) {
+        const all = out.tools;
+        const kept = all.filter((t) => {
+            const name = toolName(t);
+            if (name === undefined || !forbidden.some((p) => globMatch(p, name)))
+                return true;
+            changes.push({ removed_tool: name });
+            return false;
+        });
+        if (kept.length !== all.length) {
+            if (kept.length)
+                out.tools = kept;
+            else {
+                delete out.tools;
+                delete out.tool_choice;
+            }
+        }
+    }
+    return changes.length ? { body: out, changes } : null;
+}
+/** spec/aviation.md §15: each model request the envelope shaped. */
+export function envelopeFindings(lines) {
+    return parse(lines)
+        .filter((e) => e.kind === "llm.request" && isObj(e.meta.envelope))
+        .map((e) => ({
+        code: "ENVELOPE_SHAPED",
+        source: "envelope",
+        severity: "advisory",
+        ref: { seq: e.seq },
+    }));
+}
+const encoder = new TextEncoder();
+/** Estimated tokens: the canonical JSON's bytes over 4, rounded up. */
+const estimate = (v) => Math.ceil(encoder.encode(canonical(v)).length / 4);
+/** spec/aviation.md §17: the load sheet of a model request. Pure; an estimate. */
+export function loadSheet(body, options = {}) {
+    const b = isObj(body) ? body : {};
+    const msgs = Array.isArray(b.messages) ? b.messages : [];
+    const isSystem = (m) => isObj(m) && (m.role === "system" || m.role === "developer");
+    let system = 0;
+    for (const k of ["system", "instructions", "systemInstruction"])
+        if (b[k] !== undefined)
+            system += estimate(b[k]);
+    for (const m of msgs)
+        if (isSystem(m))
+            system += estimate(m);
+    const toolList = Array.isArray(b.tools)
+        ? b.tools
+        : isObj(b.toolConfig) && Array.isArray(b.toolConfig.tools)
+            ? b.toolConfig.tools
+            : null;
+    const tools = toolList ? estimate(toolList) : 0;
+    const rest = msgs.filter((m) => !isSystem(m));
+    let messages = rest.length ? estimate(rest) : 0;
+    for (const k of ["input", "contents"])
+        if (b[k] !== undefined)
+            messages += estimate(b[k]);
+    const total = system + tools + messages;
+    let maxOut = null;
+    for (const path of OUTPUT_LIMITS) {
+        const { holder, key } = limitAt(b, path);
+        const v = holder?.[key];
+        if (isInt(v)) {
+            maxOut = v;
+            break;
+        }
+    }
+    const model = options.model ?? (typeof b.model === "string" ? b.model : null);
+    const price = model && options.prices ? priceFor(model, options.prices.table)?.price : undefined;
+    const window = price?.context_window ?? null;
+    const pct = window ? Math.floor((total * 100) / window) : null;
+    const expected = price
+        ? callMicroUsd({ input: total, output: maxOut ?? 0, cache_read: 0, cache_write: 0 }, price)
+        : null;
+    const budget = options.budgetMicroUsd ?? null;
+    const reasons = [];
+    if (window && total + (maxOut ?? 0) > window)
+        reasons.push("context");
+    if (expected !== null && budget !== null && expected > budget)
+        reasons.push("budget");
+    const count = toolList ? toolList.length : 0;
+    return {
+        v: 1,
+        model,
+        parts: { system, tools, messages },
+        total_tokens: total,
+        max_output_tokens: maxOut,
+        context_window: window,
+        context_pct: pct,
+        tools: count,
+        expected_micro_usd: expected,
+        budget_micro_usd: budget,
+        overweight: reasons.length > 0,
+        reasons,
+        risk: reasons.length > 0 || (pct !== null && pct >= 90)
+            ? "high"
+            : (pct !== null && pct >= 70) || count > 32
+                ? "medium"
+                : "low",
+    };
+}
+// ---------------------------------------------------------------- §19 OpSpecs and classification
+export const LEVELS = ["public", "restricted", "confidential", "secret"];
+export const isLevel = (v) => LEVELS.includes(v);
+/** spec/aviation.md §19: an error message, or null for valid OpSpecs. */
+export function checkOpspecs(doc) {
+    if (!isObj(doc) || doc.v !== 1)
+        return "the OpSpecs must be {v: 1, ...}";
+    const known = ["v", "default_classification", "default", "environments", "providers", "tools"];
+    const extra = Object.keys(doc).filter((k) => !known.includes(k));
+    if (extra.length)
+        return `the OpSpecs have an unknown field: ${extra.sort().join(", ")}`;
+    for (const k of ["default_classification", "default"])
+        if (doc[k] !== undefined && !isLevel(doc[k]))
+            return `${k} must be one of ${LEVELS.join(", ")}`;
+    const names = [
+        ["environments", (k) => /^[a-z][a-z0-9-]{0,31}$/.test(k)],
+        ["providers", (k) => /^[a-z0-9][a-z0-9_-]{0,63}$/.test(k)],
+        ["tools", (k) => k.length >= 1 && k.length <= 128 && plain(k)],
+    ];
+    for (const [k, ok] of names) {
+        const m = doc[k];
+        if (m === undefined)
+            continue;
+        if (!isObj(m) || Object.keys(m).length > 1000)
+            return `${k} must map at most 1000 names to levels`;
+        for (const [name, level] of Object.entries(m))
+            if (!ok(name) || !isLevel(level))
+                return `${k}: "${name}" must map a valid name to a level`;
+    }
+    return null;
+}
+/** spec/aviation.md §19: null when approved at this classification, else why not. */
+export function opspecsCheck(specs, classification, item) {
+    const def = specs.default ?? "secret";
+    let reason;
+    let max;
+    if ("environment" in item) {
+        reason = "environment";
+        max = specs.environments?.[item.environment] ?? def;
+    }
+    else if ("provider" in item) {
+        reason = "provider";
+        max = specs.providers?.[item.provider] ?? def;
+    }
+    else {
+        reason = "tool";
+        const hit = Object.entries(specs.tools ?? {}).find(([p]) => item.tool.some((n) => globMatch(p, n)));
+        max = hit ? hit[1] : def;
+    }
+    return LEVELS.indexOf(classification) > LEVELS.indexOf(max)
+        ? { reason, classification, max }
+        : null;
+}
+/** The model requests and tool calls still open just before `at` (a seq). */
+function openAt(events, at) {
+    const done = new Set();
+    for (const e of events) {
+        if (e.seq >= at)
+            break;
+        if ((e.kind === "llm.response" || e.kind === "llm.incomplete") && isInt(e.meta.request_seq))
+            done.add(`r${e.meta.request_seq}`);
+        if (e.kind === "tool.result" && isInt(e.meta.call_seq))
+            done.add(`t${e.meta.call_seq}`);
+    }
+    const out = [];
+    for (const e of events) {
+        if (e.seq >= at)
+            break;
+        if (e.kind === "llm.request" && !done.has(`r${e.seq}`))
+            out.push({
+                seq: e.seq,
+                kind: e.kind,
+                at: e.ts,
+                ...(typeof e.meta.provider === "string" ? { provider: e.meta.provider } : {}),
+            });
+        if (e.kind === "tool.call" && !done.has(`t${e.seq}`))
+            out.push({
+                seq: e.seq,
+                kind: e.kind,
+                at: e.ts,
+                ...(typeof e.meta.tool === "string" ? { tool: e.meta.tool } : {}),
+            });
+    }
+    return out;
+}
+/** spec/aviation.md §4: the session's last known state, packaged when it goes silent. */
+export function locator(lines) {
+    const events = parse(lines);
+    const open = events[0]?.kind === "session.open" ? events[0] : undefined;
+    const lost = events.filter((e) => e.kind === "session.lost_contact").at(-1);
+    const at = lost ? lost.seq : Number.POSITIVE_INFINITY;
+    const findings = [];
+    for (const e of events)
+        if (e.kind === "finding" && typeof e.meta.code === "string" && !findings.includes(e.meta.code))
+            findings.push(e.meta.code);
+    const span = authorityTimeline(lines)
+        .filter((s) => s.from_seq <= at)
+        .at(-1);
+    return {
+        session_id: JSON.parse(lines[0] ?? "{}").session_id ?? null,
+        label: typeof open?.meta.label === "string" ? open.meta.label : null,
+        lost_contact: lost
+            ? {
+                seq: lost.seq,
+                at: lost.ts,
+                last_seen: lost.meta.last_seen ?? null,
+                silent_ms: lost.meta.silent_ms ?? null,
+            }
+            : null,
+        open_actions: openAt(events, at),
+        last_events: events
+            .filter((e) => e.seq <= at)
+            .slice(-5)
+            .map((e) => ({ seq: e.seq, kind: e.kind, ts: e.ts })),
+        findings,
+        controls: span ? { mode: span.mode, by: span.by } : null,
+    };
+}
+/** spec/aviation.md §4: each loss of contact while an action was open. */
+export function locatorFindings(lines) {
+    const events = parse(lines);
+    const out = [];
+    for (const e of events) {
+        if (e.kind !== "session.lost_contact")
+            continue;
+        const open = openAt(events, e.seq);
+        if (open.length)
+            out.push({
+                code: "EMERGENCY_LOCATOR",
+                source: "locator",
+                severity: "warning",
+                ref: { seq: e.seq },
+                figures: { open_actions: open.length },
+            });
+    }
+    return out;
+}
+/** spec/aviation.md §5: where an opening request stands at `at`. */
+export function reasoningStatus(request, at) {
+    if (request.decision === "reject")
+        return "rejected";
+    if (request.decision !== "approve")
+        return "pending";
+    return request.expires_at !== null && Date.parse(at) < Date.parse(request.expires_at)
+        ? "open"
+        : "expired";
+}
+/** spec/aviation.md §5: whether two deciders are one person: the same login (iss + sub), or the
+ * same name or email (case and surrounding spaces ignored). */
+export function samePerson(a, b) {
+    if (typeof a.iss === "string" && typeof a.sub === "string" && a.iss === b.iss && a.sub === b.sub)
+        return true;
+    const names = (p) => [p.name, p.email]
+        .filter((v) => typeof v === "string" && v.trim() !== "")
+        .map((v) => v.trim().toLowerCase());
+    const theirs = names(b);
+    return names(a).some((n) => theirs.includes(n));
+}
+/** spec/aviation.md §5: an actions page with the reasoning text taken out. */
+export function protectReasoning(page) {
+    return {
+        ...page,
+        actions: page.actions.map((a) => ({
+            ...a,
+            reasoning: { kind: a.reasoning.kind, protected: true },
+        })),
+    };
+}
+// ---------------------------------------------------------------- §6, §10 reports from the agent and from people
+export const SAFETY_CATEGORIES = ["near_miss", "hazard", "procedure", "tooling", "other"];
+/** spec/aviation.md §6: a person's safety report, checked: the fields, or an error message. */
+export function checkSafetyReport(input) {
+    const category = input.category ?? "other";
+    if (!SAFETY_CATEGORIES.includes(category))
+        return { ok: false, error: `category must be one of ${SAFETY_CATEGORIES.join(", ")}` };
+    const { description } = input;
+    if (typeof description !== "string" ||
+        description.length < 1 ||
+        description.length > 4000 ||
+        !plain(description, true))
+        return { ok: false, error: "description must be 1-4000 characters, no control characters" };
+    return {
+        ok: true,
+        report: { category: category, description },
+    };
+}
+/** spec/aviation.md §6: report counts by category, only those at least `k` tenants reported. */
+export function safetyReportSummary(reports, k = 3) {
+    const kk = Math.max(3, Math.trunc(k));
+    const by = new Map();
+    for (const r of reports) {
+        const g = by.get(r.category) ?? { reports: 0, tenants: new Set() };
+        g.reports++;
+        g.tenants.add(r.tenant);
+        by.set(r.category, g);
+    }
+    return {
+        k: kk,
+        categories: [...by.entries()]
+            .filter(([, g]) => g.tenants.size >= kk)
+            .sort(([a], [b]) => cmp(a, b))
+            .map(([category, g]) => ({ category, reports: g.reports, tenants: g.tenants.size })),
+    };
+}
+/** spec/aviation.md §6, §10: the agent's own safety reports, maydays and pan-pans. */
+export function agentReportFindings(lines) {
+    const out = [];
+    for (const e of parse(lines)) {
+        if (e.kind !== "sdk.event" || e.meta.duplicate_of !== undefined)
+            continue;
+        const type = e.meta.type;
+        const ref = { seq: e.seq, non_punitive: true };
+        const kind = typeof e.meta.name === "string" ? { detail: e.meta.name } : {};
+        if (type === "safety_report")
+            out.push({ code: "SAFETY_REPORT", source: "agent", severity: "advisory", ref });
+        else if (type === "mayday")
+            out.push({ code: "MAYDAY", source: "agent", severity: "warning", ref, ...kind });
+        else if (type === "pan_pan")
+            out.push({ code: "PAN_PAN", source: "agent", severity: "caution", ref, ...kind });
+    }
+    return out;
+}
+/** spec/aviation.md §8: the procedure for a fault code, or the generic one. */
+export function procedureFor(code) {
+    const fault = faultOf(code);
+    const steps = QRH.procedures[code];
+    return {
+        code,
+        fault: fault.fault,
+        title: fault.en,
+        title_ar: fault.ar,
+        steps: [...(steps ?? QRH.generic)],
+        source: steps ? "qrh" : "generic",
+    };
+}
+const HAZARD_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const FINDING_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const isDate = (v) => typeof v === "string" &&
+    DATE.test(v) &&
+    !Number.isNaN(Date.parse(`${v}T00:00:00Z`)) &&
+    new Date(`${v}T00:00:00Z`).toISOString().slice(0, 10) === v;
+const text = (v, max) => typeof v === "string" && v.length >= 1 && v.length <= max && plain(v);
+/** spec/aviation.md §7: an error message, or null for a valid hazard register. */
+export function checkHazardRegister(doc) {
+    if (!isObj(doc) || doc.v !== 1 || doc.type !== "blackbox.hazard-register")
+        return "the register must be {v: 1, type: blackbox.hazard-register, hazards}";
+    const hazards = doc.hazards;
+    if (!Array.isArray(hazards) || hazards.length > 500)
+        return "hazards must be a list of at most 500";
+    const seen = new Set();
+    for (const [i, h] of hazards.entries()) {
+        const at = `hazards[${i}]`;
+        if (!isObj(h))
+            return `${at} must be an object`;
+        if (typeof h.id !== "string" || !HAZARD_ID.test(h.id) || seen.has(h.id))
+            return `${at}.id must be a unique id of 1-64 of a-z 0-9 . _ -`;
+        seen.add(h.id);
+        if (!text(h.title, 200))
+            return `${at}.title must be 1-200 characters`;
+        for (const k of ["likelihood", "severity"])
+            if (!isInt(h[k]) || h[k] < 1 || h[k] > 5)
+                return `${at}.${k} must be an integer 1-5`;
+        if (!Array.isArray(h.codes) ||
+            h.codes.length > 50 ||
+            !h.codes.every((c) => typeof c === "string" && FINDING_CODE.test(c)))
+            return `${at}.codes must be up to 50 finding codes`;
+        if (!Array.isArray(h.mitigations) ||
+            h.mitigations.length > 20 ||
+            !h.mitigations.every((m) => text(m, 500)))
+            return `${at}.mitigations must be up to 20 texts of 1-500 characters`;
+        if (!text(h.owner, 128))
+            return `${at}.owner must be 1-128 characters`;
+        if (!isDate(h.review_by))
+            return `${at}.review_by must be a date (YYYY-MM-DD)`;
+        const extra = Object.keys(h).filter((k) => ![
+            "id",
+            "title",
+            "likelihood",
+            "severity",
+            "codes",
+            "mitigations",
+            "owner",
+            "review_by",
+        ].includes(k));
+        if (extra.length)
+            return `${at} has an unknown field: ${extra.sort().join(", ")}`;
+    }
+    return null;
+}
+/** spec/aviation.md §7: each hazard's risk, and the sessions that show it, highest risk first. */
+export function hazardStatus(register, summaries, today) {
+    const hazards = register.hazards.map((h) => {
+        let sessions = 0;
+        let findings = 0;
+        let last = null;
+        for (const s of summaries) {
+            const n = h.codes.reduce((sum, c) => sum + (s.finding_codes[c] ?? 0), 0);
+            if (n === 0)
+                continue;
+            sessions++;
+            findings += n;
+            if (last === null || Date.parse(s.started_at) > Date.parse(last))
+                last = s.started_at;
+        }
+        const risk = h.likelihood * h.severity;
+        return {
+            ...h,
+            risk,
+            band: risk <= 4 ? "low" : risk <= 12 ? "medium" : "high",
+            review_overdue: today > h.review_by,
+            sessions,
+            findings,
+            last_seen: last,
+        };
+    });
+    return {
+        v: 1,
+        type: "blackbox.hazard-status",
+        register_hash: docHash(register),
+        hazards: hazards.sort((a, b) => b.risk - a.risk || cmp(a.id, b.id)),
+    };
+}
+// ---------------------------------------------------------------- §11 type certificates
+const SHA256 = /^sha256:[0-9a-f]{64}$/;
+/** spec/aviation.md §11: a configuration's id, the same as a version's (spec/fleet.md §9). */
+export function configurationId(prompt, tools, model) {
+    return `ver_${createHash("sha256")
+        .update(canonical([prompt, tools, model]))
+        .digest("hex")
+        .slice(0, 12)}`;
+}
+/** spec/aviation.md §11: a type certificate (unsigned), or an error message. */
+export function typeCertificate(input, tenant, issuedAt) {
+    const { label, model, prompt, tools } = input;
+    if (!text(label, 200))
+        return { ok: false, error: "label must be 1-200 characters" };
+    if (!text(model, 200))
+        return { ok: false, error: "model must be 1-200 characters" };
+    for (const [k, v] of [
+        ["prompt", prompt],
+        ["tools", tools],
+    ])
+        if (v !== null && !(typeof v === "string" && SHA256.test(v)))
+            return { ok: false, error: `${k} must be sha256: and 64 hex, or null` };
+    if (prompt === null && tools === null)
+        return { ok: false, error: "prompt and tools can't both be null" };
+    const configuration = configurationId(prompt, tools, model);
+    const id = `tc_${createHash("sha256")
+        .update(`${tenant ?? ""}\n${label}\n${configuration}`)
+        .digest("hex")
+        .slice(0, 16)}`;
+    return {
+        ok: true,
+        certificate: {
+            v: 1,
+            type: "blackbox.type-certificate",
+            id,
+            configuration,
+            label,
+            model,
+            prompt: prompt,
+            tools: tools,
+            tenant,
+            issued_at: issuedAt,
+        },
+    };
+}
+/** spec/aviation.md §11: each configuration a labelled session ran that no certificate covers. */
+export function unapprovedModifications(lines, certificates) {
+    const events = parse(lines);
+    const label = events[0]?.kind === "session.open" ? events[0].meta.label : undefined;
+    if (typeof label !== "string")
+        return [];
+    const covered = new Set(certificates.filter((c) => c.label === label).map((c) => c.configuration));
+    const models = new Map();
+    for (const e of events)
+        if ((e.kind === "llm.response" || e.kind === "llm.incomplete") && isInt(e.meta.request_seq))
+            if (!models.has(e.meta.request_seq))
+                models.set(e.meta.request_seq, typeof e.meta.model === "string" ? e.meta.model : null);
+    const out = [];
+    const seen = new Set();
+    for (const e of events) {
+        if (e.kind !== "llm.request" || !models.has(e.seq))
+            continue;
+        const str = (v) => (typeof v === "string" ? v : null);
+        const prompt = str(e.meta.system_sha256);
+        const tools = str(e.meta.tools_sha256);
+        if (prompt === null && tools === null)
+            continue;
+        const id = configurationId(prompt, tools, models.get(e.seq) ?? null);
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        if (!covered.has(id))
+            out.push({
+                code: "UNAPPROVED_MODIFICATION",
+                source: "type_certificate",
+                severity: "warning",
+                ref: { seq: e.seq, configuration: id },
+            });
+    }
+    return out;
+}
+/** spec/aviation.md §14: the operator's certificate (unsigned) over the facts. */
+export function operatorCertificate(facts, options) {
+    const reasons = [];
+    if (!facts.audit_chain_ok)
+        reasons.push("audit_chain_broken");
+    if (!facts.anchoring.enabled)
+        reasons.push("anchoring_off");
+    if (facts.anchoring.dead > 0)
+        reasons.push("anchoring_dead");
+    if (facts.incidents_open > 0)
+        reasons.push("incidents_open");
+    if ((facts.checks_overdue ?? 0) > 0)
+        reasons.push("checks_overdue");
+    const days = options.days ?? 30;
+    return {
+        v: 1,
+        type: "blackbox.operator-certificate",
+        operator: options.operator,
+        issued_at: options.issuedAt,
+        expires_at: new Date(Date.parse(options.issuedAt) + days * DAY_MS).toISOString(),
+        controls: facts,
+        verdict: reasons.length ? "not_certified" : "certified",
+        reasons,
+    };
+}
+/** spec/aviation.md §14: an operator certificate checked offline, like an accreditation. */
+export function checkOperatorCertificate(cert, options) {
+    if (!isObj(cert) ||
+        cert.v !== 1 ||
+        cert.type !== "blackbox.operator-certificate" ||
+        isoMs(cert.issued_at) === null ||
+        isoMs(cert.expires_at) === null)
+        return { ok: false, reason: "malformed" };
+    const signed = verifyCertificate(cert);
+    if (!signed.ok)
+        return { ok: false, reason: "unsigned" };
+    if (options.issuers?.length && !options.issuers.includes(signed.by))
+        return { ok: false, reason: "wrong_issuer" };
+    const now = Date.parse(options.now);
+    if (now < Date.parse(cert.issued_at))
+        return { ok: false, reason: "not_yet" };
+    if (now >= Date.parse(cert.expires_at))
+        return { ok: false, reason: "expired" };
+    if (cert.verdict !== "certified")
+        return { ok: false, reason: "not_certified" };
+    return { ok: true };
+}
+/** spec/aviation.md §12: an error message, or null for a valid checks file. */
+export function checkChecks(doc) {
+    if (!isObj(doc) || doc.v !== 1 || !Array.isArray(doc.checks) || doc.checks.length > 200)
+        return "the checks file must be {v: 1, checks: [...]} with at most 200 checks";
+    const seen = new Set();
+    for (const [i, c] of doc.checks.entries()) {
+        const at = `checks[${i}]`;
+        if (!isObj(c))
+            return `${at} must be an object`;
+        if (typeof c.id !== "string" || !HAZARD_ID.test(c.id) || seen.has(c.id))
+            return `${at}.id must be a unique id of 1-64 of a-z 0-9 . _ -`;
+        seen.add(c.id);
+        if (!text(c.label, 200))
+            return `${at}.label must be 1-200 characters`;
+        if (c.kind !== "drill" && c.kind !== "scenario")
+            return `${at}.kind must be drill or scenario`;
+        if (!isInt(c.every_days) || c.every_days < 1 || c.every_days > 365)
+            return `${at}.every_days must be an integer 1-365`;
+        if (c.grace_days !== undefined &&
+            !(isInt(c.grace_days) && c.grace_days >= 0 && c.grace_days <= 90))
+            return `${at}.grace_days must be an integer 0-90`;
+        const extra = Object.keys(c).filter((k) => !["id", "label", "kind", "every_days", "grace_days"].includes(k));
+        if (extra.length)
+            return `${at} has an unknown field: ${extra.sort().join(", ")}`;
+    }
+    return null;
+}
+/** spec/aviation.md §12: each check's last run, due date and status at `now`. */
+export function checkStatus(checks, done, now) {
+    const t = Date.parse(now);
+    return checks.map((c) => {
+        const grace = c.grace_days ?? 0;
+        let last = null;
+        for (const d of done)
+            if (d.label === c.label &&
+                d.kind === c.kind &&
+                (last === null || Date.parse(d.at) > Date.parse(last)))
+                last = d.at;
+        if (last === null)
+            return { ...c, grace_days: grace, last_done: null, due_at: null, status: "overdue" };
+        const due = Date.parse(last) + c.every_days * DAY_MS;
+        return {
+            ...c,
+            grace_days: grace,
+            last_done: last,
+            due_at: new Date(due).toISOString(),
+            status: t < due ? "current" : t < due + grace * DAY_MS ? "due" : "overdue",
+        };
+    });
+}
+/** spec/aviation.md §12: an overdue check of the session's label, flagged at pre-flight. */
+export function checkFindings(lines, statuses) {
+    const first = lines[0] ? JSON.parse(lines[0]) : undefined;
+    const label = first?.kind === "session.open" ? first.meta.label : undefined;
+    if (typeof label !== "string")
+        return [];
+    return statuses
+        .filter((c) => c.label === label && c.status === "overdue")
+        .map((c) => ({
+        code: "CHECK_OVERDUE",
+        source: "checks",
+        severity: "advisory",
+        ref: { seq: 0, check: c.id },
+    }));
+}
+/** spec/aviation.md §13: whether each airworthy rating is still current. */
+export function ratingCurrency(ratings, items, options) {
+    const t = Date.parse(options.now);
+    return ratings
+        .filter((r) => r.verdict === "airworthy")
+        .map((r) => {
+        let last = null;
+        for (const i of items)
+            if (i.summary.closed &&
+                (i.summary.label ?? "(no label)") === r.label &&
+                i.models.includes(r.model) &&
+                (last === null || Date.parse(i.summary.started_at) > Date.parse(last)))
+                last = i.summary.started_at;
+        return {
+            label: r.label,
+            model: r.model,
+            last_flown: last,
+            current: last !== null && t - Date.parse(last) <= options.days * DAY_MS,
+        };
+    });
+}
+/** spec/aviation.md §13: each model the session uses whose rating for its label has lapsed. */
+export function ratingLapsed(lines, prices, currency, severity = "advisory") {
+    const first = lines[0] ? JSON.parse(lines[0]) : undefined;
+    if (first?.kind !== "session.open")
+        return [];
+    const label = typeof first.meta.label === "string" ? first.meta.label : "(no label)";
+    const lapsed = new Set(currency.filter((c) => c.label === label && !c.current).map((c) => c.model));
+    const out = [];
+    const seen = new Set();
+    for (const c of sessionCost(lines, prices).calls) {
+        if (!c.model || seen.has(c.model))
+            continue;
+        seen.add(c.model);
+        if (lapsed.has(c.model))
+            out.push({
+                code: "RATING_LAPSED",
+                source: "type_rating",
+                severity,
+                ref: { seq: c.seq, model: c.model },
+            });
+    }
+    return out;
+}
+const NOT_PEOPLE = new Set(["timeout", "unattended", "classifier"]);
+/** Who decided: pseudonymous where it can be. */
+function approverOf(meta) {
+    const p = isObj(meta.person) ? meta.person : null;
+    if (p && typeof p.iss === "string" && typeof p.sub === "string")
+        return `${p.iss}#${p.sub}`;
+    if (p && typeof p.name === "string" && p.name.trim())
+        return `name:${p.name.trim().toLowerCase()}`;
+    return typeof meta.by === "string" ? `role:${meta.by}` : null;
+}
+/** A session's people decisions: {seq, approver, decision, ms (or null)}. */
+function decisionsOf(lines) {
+    const asked = new Map();
+    const out = [];
+    for (const e of parse(lines)) {
+        const m = e.meta;
+        const policy = isObj(m.policy) ? m.policy : null;
+        if (e.kind === "tool.call" && policy && typeof policy.approval_id === "string")
+            asked.set(policy.approval_id, Date.parse(e.ts));
+        if (e.kind === "control" &&
+            (m.action === "approval_request" || m.action === "permission_request") &&
+            typeof m.approval_id === "string")
+            asked.set(m.approval_id, Date.parse(e.ts));
+        if (e.kind !== "control" || m.action !== "approval")
+            continue;
+        if (m.decision !== "approve" && m.decision !== "reject")
+            continue;
+        if (typeof m.by === "string" && NOT_PEOPLE.has(m.by))
+            continue;
+        const who = approverOf(m);
+        if (who === null)
+            continue;
+        const from = typeof m.approval_id === "string" ? asked.get(m.approval_id) : undefined;
+        out.push({
+            seq: e.seq,
+            approver: who,
+            decision: m.decision,
+            ms: from === undefined ? null : Math.max(0, Date.parse(e.ts) - from),
+        });
+    }
+    return out;
+}
+/** spec/aviation.md §18: each approver's decisions, speed and whether they rubber-stamp. */
+export function approverStats(records, options = {}) {
+    const fastMs = options.fastMs ?? 2000;
+    const min = options.minDecisions ?? 10;
+    const stampPpm = options.rubberStampPpm ?? 800_000;
+    const by = new Map();
+    for (const lines of records)
+        for (const d of decisionsOf(lines)) {
+            const g = by.get(d.approver) ?? { approved: 0, rejected: 0, ms: [], fast: 0 };
+            if (d.decision === "approve")
+                g.approved++;
+            else
+                g.rejected++;
+            if (d.ms !== null) {
+                g.ms.push(d.ms);
+                if (d.ms < fastMs)
+                    g.fast++;
+            }
+            by.set(d.approver, g);
+        }
+    const approvers = [...by.entries()]
+        .sort(([a], [b]) => cmp(a, b))
+        .map(([approver, g]) => {
+        const decisions = g.approved + g.rejected;
+        const ms = [...g.ms].sort((a, b) => a - b);
+        const approvePpm = Math.floor((g.approved * 1_000_000) / decisions);
+        const fastPpm = Math.floor((g.fast * 1_000_000) / decisions);
+        return {
+            approver,
+            decisions,
+            approved: g.approved,
+            rejected: g.rejected,
+            approve_ppm: approvePpm,
+            median_ms: ms.length ? ms[Math.floor((ms.length - 1) / 2)] : null,
+            fast: g.fast,
+            fast_ppm: fastPpm,
+            rubber_stamp: decisions >= min && approvePpm >= 950_000 && fastPpm >= stampPpm,
+        };
+    });
+    return { approvers };
+}
+/** spec/aviation.md §18: once per rubber-stamping approver who decided in this session. */
+export function approverFatigueFindings(lines, stats) {
+    const tired = new Set(stats.approvers.filter((a) => a.rubber_stamp).map((a) => a.approver));
+    const out = [];
+    const seen = new Set();
+    for (const d of decisionsOf(lines)) {
+        if (!tired.has(d.approver) || seen.has(d.approver))
+            continue;
+        seen.add(d.approver);
+        out.push({
+            code: "APPROVER_FATIGUE",
+            source: "approvals",
+            severity: "caution",
+            ref: { seq: d.seq, approver: d.approver },
+        });
+    }
+    return out;
+}