@zanii/blackbox 0.21.2 → 0.23.0

package/dist/analysis/taxonomy.js

@@ -55,6 +55,7 @@ export const TAXONOMY = {
     TOKEN_MISUSE: { owasp: ["ASI03"], atlas: ["AML.T0091.000", "AML.T0086"] },
     TOOL_CHANGED: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },
     TOOL_DRIFTED: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },
+    ELICITATION_SECRET: { owasp: ["ASI03"], atlas: ["AML.T0057"] },
     PROMPT_INJECTION: { owasp: ["ASI01"], atlas: ["AML.T0051"] },
     PROMPT_CHANGED: { owasp: ["ASI04"] },
     SELF_CHANGE_UNAPPROVED: { owasp: ["ASI10"] },

package/dist/analysis/waste.js

@@ -1,15 +1,14 @@
 // The waste ledger (spec/cost.md §5): which paid model calls were wasted, and why.
 // Mirrors analysis/waste.py.
 import { sessionCost, toAedFils } from "../cost/index.js";
-import { callsOf } from "../reconcile/record.js";
+import { callsOf, envelopesOf } from "../reconcile/record.js";
 import { toolCallsOf } from "./detectors.js";
 export const OUTCOMES = ["success", "failure", "abandoned"];
 export function waste(lines, bodies, prices) {
     const cost = sessionCost(lines, prices);
     const status = new Map();
     let outcome = null;
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         if (e.kind === "llm.response" && typeof e.meta.status === "number")
             status.set(e.seq, e.meta.status);
         else if (e.kind === "llm.incomplete")

package/dist/approvals/index.d.ts

@@ -21,14 +21,23 @@ export declare function approvalFindings(lines: readonly string[]): ApprovalFind
 export declare function approvalConfirmation(lines: readonly string[], approvalId: string, gateway: {
     did: string;
     privateKey: Uint8Array;
-}): {
+}): ApprovalConfirmation | {
+    error: "not_found" | "not_approved";
+};
+/** spec/anchoring.md §15: `approvalConfirmation` with a key held outside the process. */
+export declare function approvalConfirmationWith(lines: readonly string[], approvalId: string, gateway: {
+    did: string;
+    sign: (message: Uint8Array) => Promise<Uint8Array>;
+}): Promise<ApprovalConfirmation | {
+    error: "not_found" | "not_approved";
+}>;
+type ApprovalConfirmation = {
     confirmation: ReturnType<typeof createConfirmation>;
     decision_seq: number;
     action_seq: number;
     by: unknown;
     person?: unknown;
-} | {
-    error: "not_found" | "not_approved";
 };
 /** spec/approvals.md §8: Zanii's check of an action_confirmation (the DID it names signed it). */
 export declare const verifyConfirmation: (c: unknown) => boolean;
+export {};

package/dist/approvals/index.js

@@ -1,7 +1,8 @@
 // The two-person rule (spec/approvals.md): what the approval decisions say. Pure; mirrors
 // sdks/python/src/zanii_blackbox/approvals.py; pinned by spec/vectors/approvals.json.
 import { createHash } from "node:crypto";
-import { createConfirmation, verifyConfirmation as zaniiVerifyConfirmation } from "@zanii/core";
+import { canonicalBytes, createConfirmation, verifyConfirmation as zaniiVerifyConfirmation, } from "@zanii/core";
+import { envelopesOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
 import { hashLine } from "../verify/envelope.js";
 /** spec/approvals.md §2: what an approval's arguments are, `sha256:<hex>` of their canonical JSON
@@ -14,8 +15,7 @@ export function argsHash(args) {
 /** spec/approvals.md §3: a refused action (advisory), and one nobody confirmed in time (warning). */
 export function approvalFindings(lines) {
     const out = [];
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         if (e.kind !== "control" || e.meta.action !== "approval")
             continue;
         const id = typeof e.meta.approval_id === "string" ? e.meta.approval_id : "";
@@ -42,7 +42,31 @@ export function approvalFindings(lines) {
  * decision's time. Deterministic. `error` when there is no approve decision.
  */
 export function approvalConfirmation(lines, approvalId, gateway) {
-    const events = lines.map((l) => JSON.parse(l));
+    const found = approvedAction(lines, approvalId);
+    if ("error" in found)
+        return found;
+    const { actionHash, confirmedAt, rest } = found;
+    const confirmation = createConfirmation({ ownerId: gateway.did, actionHash, confirmedAt }, gateway.privateKey);
+    return { confirmation, ...rest };
+}
+/** spec/anchoring.md §15: `approvalConfirmation` with a key held outside the process. */
+export async function approvalConfirmationWith(lines, approvalId, gateway) {
+    const found = approvedAction(lines, approvalId);
+    if ("error" in found)
+        return found;
+    const unsigned = {
+        v: 1,
+        type: "action_confirmation",
+        owner_id: gateway.did,
+        action_hash: found.actionHash,
+        confirmed_at: found.confirmedAt,
+    };
+    const sig = `ed25519:${Buffer.from(await gateway.sign(canonicalBytes(unsigned))).toString("hex")}`;
+    return { confirmation: { ...unsigned, sig }, ...found.rest };
+}
+/** The approved event's hash, the decision's time, and the rest of the answer. */
+function approvedAction(lines, approvalId) {
+    const events = envelopesOf(lines);
     const decision = events.find((e) => e.kind === "control" && e.meta.action === "approval" && e.meta.approval_id === approvalId);
     if (!decision)
         return { error: "not_found" };
@@ -55,13 +79,15 @@ export function approvalConfirmation(lines, approvalId, gateway) {
     const line = lines[actionSeq];
     if (line === undefined)
         return { error: "not_found" };
-    const confirmation = createConfirmation({ ownerId: gateway.did, actionHash: hashLine(line), confirmedAt: decision.ts }, gateway.privateKey);
     return {
-        confirmation,
-        decision_seq: decision.seq,
-        action_seq: actionSeq,
-        by: decision.meta.by,
-        ...(decision.meta.person !== undefined ? { person: decision.meta.person } : {}),
+        actionHash: hashLine(line),
+        confirmedAt: decision.ts,
+        rest: {
+            decision_seq: decision.seq,
+            action_seq: actionSeq,
+            by: decision.meta.by,
+            ...(decision.meta.person !== undefined ? { person: decision.meta.person } : {}),
+        },
     };
 }
 /** spec/approvals.md §8: Zanii's check of an action_confirmation (the DID it names signed it). */

package/dist/authority/index.js

@@ -1,5 +1,6 @@
 // Who had the controls (spec/authority.md): the authority timeline, and automation surprise.
 // Pure; mirrors sdks/python/src/zanii_blackbox/authority.py; pinned by spec/vectors/authority.json.
+import { envelopesOf } from "../reconcile/record.js";
 const MODES = new Set(["agent", "supervised", "human"]);
 const ADMIN_BLOCKS = new Set(["EMERGENCY", "TAKEOVER"]);
 /** The mode an event sets, or null for one that doesn't change who is flying (spec §2). */
@@ -28,8 +29,7 @@ function change(e) {
 /** spec/authority.md §3: who was flying, span by span, oldest first. */
 export function authorityTimeline(lines) {
     const spans = [];
-    for (const line of lines) {
-        const e = JSON.parse(line);
+    for (const e of envelopesOf(lines)) {
         const c = change(e);
         const current = spans.at(-1);
         if (!c || current?.mode === c.mode)
@@ -49,7 +49,7 @@ export function authorityAt(lines, seq) {
 }
 /** spec/authority.md §4: the agent acted in a `human` span before it knew the mode had changed. */
 export function automationSurprise(lines) {
-    const events = lines.map((l) => JSON.parse(l));
+    const events = envelopesOf(lines);
     const out = [];
     for (const span of authorityTimeline(lines)) {
         if (span.mode !== "human")

package/dist/aviation/index.d.ts

@@ -0,0 +1,422 @@
+import type { Finding } from "../analysis/index.ts";
+import { type LoadedPrices } from "../cost/index.ts";
+import type { Bodies } from "../reconcile/record.ts";
+import { QRH } from "./qrh.ts";
+export { QRH };
+/** A `*` pattern as a whole-name match (spec/policy.md §1's tool patterns). */
+export declare function globMatch(pattern: string, name: string): boolean;
+export type ClearanceMode = "exclusive" | "shared";
+export interface ActiveClearance {
+    clearance_id: string;
+    session_id: string;
+    resource: string;
+    mode: ClearanceMode;
+    expires_at: string;
+}
+export interface ClearanceDecision {
+    decision: "granted" | "hold";
+    retry_after_s?: number;
+    conflicts: Array<{
+        session_id: string;
+        mode: ClearanceMode;
+        expires_at: string;
+    }>;
+    advisories: Array<{
+        session_id: string;
+        action: "hold" | "proceed";
+    }>;
+}
+/** spec/aviation.md §1: the gateway's answer to a clearance request. */
+export type ClearanceAnswer = ClearanceDecision & {
+    resource: string;
+    mode: ClearanceMode;
+    clearance_id?: string;
+    expires_at?: string;
+};
+/** spec/aviation.md §1: may this session have the resource now? §2: and what each side does. */
+export declare function clearance(active: readonly ActiveClearance[], request: {
+    session_id: string;
+    resource: string;
+    mode: ClearanceMode;
+    at: string;
+}): ClearanceDecision;
+/** spec/aviation.md §1: each change made without an exclusive clearance in force for it. */
+export declare function clearanceFindings(lines: readonly string[], bodies: Bodies): Finding[];
+export interface Notam {
+    id: string;
+    text: string;
+    from: string;
+    until: string;
+    tools: string[];
+    providers: string[];
+    effect: "inform" | "avoid";
+    tenant: string | null;
+    created_at: string;
+    cancelled_at: string | null;
+}
+/** spec/aviation.md §3: a notice's fields with defaults filled in, or an error message. */
+export declare function checkNotam(input: Record<string, unknown>, now: string): {
+    ok: true;
+    notam: Pick<Notam, "text" | "from" | "until" | "tools" | "providers" | "effect">;
+} | {
+    ok: false;
+    error: string;
+};
+/** spec/aviation.md §3: the notices in force at `at` for a tenant, by `from` then `id`. */
+export declare function notamsInForce(notams: readonly Notam[], at: string, tenant: string | null): Notam[];
+/** spec/aviation.md §3: the first event each `avoid` notice in force covers. */
+export declare function notamFindings(lines: readonly string[], notams: readonly Notam[]): Finding[];
+/** spec/aviation.md §9: the seq of the session's first `commit_point` SDK event, or null. */
+export declare function commitPointSeq(lines: readonly string[]): number | null;
+/** spec/aviation.md §9: a non-critical finding that comes after the commit point. */
+export declare function pastCommitPoint(lines: readonly string[], finding: {
+    severity: string;
+    ref: {
+        [key: string]: unknown;
+    };
+}): boolean;
+export interface EnvelopeLimits {
+    v: 1;
+    forbidden_tools?: string[];
+    max_output_tokens?: number;
+}
+export type EnvelopeChange = {
+    field: string;
+    from: number;
+    to: number;
+} | {
+    removed_tool: string;
+};
+/** spec/aviation.md §15: an error message, or null for a valid envelope. */
+export declare function checkEnvelope(doc: unknown): string | null;
+/** spec/aviation.md §15: the request inside the envelope, and what changed; null when nothing did. */
+export declare function shapeRequest(body: unknown, envelope: EnvelopeLimits): {
+    body: Record<string, unknown>;
+    changes: EnvelopeChange[];
+} | null;
+/** spec/aviation.md §15: each model request the envelope shaped. */
+export declare function envelopeFindings(lines: readonly string[]): Finding[];
+export interface LoadSheet {
+    v: 1;
+    model: string | null;
+    parts: {
+        system: number;
+        tools: number;
+        messages: number;
+    };
+    total_tokens: number;
+    max_output_tokens: number | null;
+    context_window: number | null;
+    context_pct: number | null;
+    tools: number;
+    expected_micro_usd: number | null;
+    budget_micro_usd: number | null;
+    overweight: boolean;
+    reasons: Array<"context" | "budget">;
+    risk: "low" | "medium" | "high";
+}
+/** spec/aviation.md §17: the load sheet of a model request. Pure; an estimate. */
+export declare function loadSheet(body: unknown, options?: {
+    prices?: LoadedPrices;
+    model?: string;
+    budgetMicroUsd?: number;
+}): LoadSheet;
+export declare const LEVELS: readonly ["public", "restricted", "confidential", "secret"];
+export type Level = (typeof LEVELS)[number];
+export interface OpSpecs {
+    v: 1;
+    default_classification?: Level;
+    default?: Level;
+    environments?: Record<string, Level>;
+    providers?: Record<string, Level>;
+    tools?: Record<string, Level>;
+}
+export declare const isLevel: (v: unknown) => v is Level;
+/** spec/aviation.md §19: an error message, or null for valid OpSpecs. */
+export declare function checkOpspecs(doc: unknown): string | null;
+/** spec/aviation.md §19: null when approved at this classification, else why not. */
+export declare function opspecsCheck(specs: OpSpecs, classification: Level, item: {
+    environment: string;
+} | {
+    provider: string;
+} | {
+    tool: readonly string[];
+}): {
+    reason: "environment" | "provider" | "tool";
+    classification: Level;
+    max: Level;
+} | null;
+export interface Locator {
+    session_id: string | null;
+    label: string | null;
+    lost_contact: {
+        seq: number;
+        at: string;
+        last_seen: unknown;
+        silent_ms: unknown;
+    } | null;
+    open_actions: Array<{
+        seq: number;
+        kind: string;
+        at: string;
+        provider?: string;
+        tool?: string;
+    }>;
+    last_events: Array<{
+        seq: number;
+        kind: string;
+        ts: string;
+    }>;
+    findings: string[];
+    controls: {
+        mode: string;
+        by: string;
+    } | null;
+}
+/** spec/aviation.md §4: the session's last known state, packaged when it goes silent. */
+export declare function locator(lines: readonly string[]): Locator;
+/** spec/aviation.md §4: each loss of contact while an action was open. */
+export declare function locatorFindings(lines: readonly string[]): Finding[];
+export interface ReasoningRequest {
+    request_id: string;
+    session_id: string;
+    reason: string;
+    requested_by: Record<string, unknown>;
+    requested_at: string;
+    decision: "approve" | "reject" | null;
+    decided_by: Record<string, unknown> | null;
+    decided_at: string | null;
+    expires_at: string | null;
+}
+/** spec/aviation.md §5: where an opening request stands at `at`. */
+export declare function reasoningStatus(request: Pick<ReasoningRequest, "decision" | "expires_at">, at: string): "pending" | "open" | "rejected" | "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 declare function samePerson(a: Record<string, unknown>, b: Record<string, unknown>): boolean;
+/** spec/aviation.md §5: an actions page with the reasoning text taken out. */
+export declare function protectReasoning<T extends {
+    actions: ReadonlyArray<{
+        reasoning: {
+            kind: string;
+        };
+    }>;
+}>(page: T): T;
+export declare const SAFETY_CATEGORIES: readonly ["near_miss", "hazard", "procedure", "tooling", "other"];
+/** spec/aviation.md §6: a person's safety report, checked: the fields, or an error message. */
+export declare function checkSafetyReport(input: Record<string, unknown>): {
+    ok: true;
+    report: {
+        category: (typeof SAFETY_CATEGORIES)[number];
+        description: string;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+/** spec/aviation.md §6: report counts by category, only those at least `k` tenants reported. */
+export declare function safetyReportSummary(reports: ReadonlyArray<{
+    category: string;
+    tenant: string | null;
+}>, k?: number): {
+    k: number;
+    categories: Array<{
+        category: string;
+        reports: number;
+        tenants: number;
+    }>;
+};
+/** spec/aviation.md §6, §10: the agent's own safety reports, maydays and pan-pans. */
+export declare function agentReportFindings(lines: readonly string[]): Finding[];
+export interface Procedure {
+    code: string;
+    fault: string;
+    title: string;
+    title_ar: string;
+    steps: string[];
+    source: "qrh" | "generic";
+}
+/** spec/aviation.md §8: the procedure for a fault code, or the generic one. */
+export declare function procedureFor(code: string): Procedure;
+export interface Hazard {
+    id: string;
+    title: string;
+    likelihood: number;
+    severity: number;
+    codes: string[];
+    mitigations: string[];
+    owner: string;
+    review_by: string;
+}
+export interface HazardRegister {
+    v: 1;
+    type: "blackbox.hazard-register";
+    hazards: Hazard[];
+}
+/** spec/aviation.md §7: an error message, or null for a valid hazard register. */
+export declare function checkHazardRegister(doc: unknown): string | null;
+/** spec/aviation.md §7: each hazard's risk, and the sessions that show it, highest risk first. */
+export declare function hazardStatus(register: HazardRegister, summaries: ReadonlyArray<{
+    started_at: string;
+    finding_codes: Record<string, number>;
+}>, today: string): {
+    v: 1;
+    type: "blackbox.hazard-status";
+    register_hash: string;
+    hazards: {
+        id: string;
+        title: string;
+        likelihood: number;
+        severity: number;
+        codes: string[];
+        mitigations: string[];
+        owner: string;
+        review_by: string;
+        risk: number;
+        band: string;
+        review_overdue: boolean;
+        sessions: number;
+        findings: number;
+        last_seen: string | null;
+    }[];
+};
+/** spec/aviation.md §11: a configuration's id, the same as a version's (spec/fleet.md §9). */
+export declare function configurationId(prompt: string | null, tools: string | null, model: string | null): string;
+export interface TypeCertificate {
+    v: 1;
+    type: "blackbox.type-certificate";
+    id: string;
+    configuration: string;
+    label: string;
+    model: string;
+    prompt: string | null;
+    tools: string | null;
+    tenant: string | null;
+    issued_at: string;
+}
+/** spec/aviation.md §11: a type certificate (unsigned), or an error message. */
+export declare function typeCertificate(input: {
+    label: unknown;
+    model: unknown;
+    prompt: unknown;
+    tools: unknown;
+}, tenant: string | null, issuedAt: string): {
+    ok: true;
+    certificate: TypeCertificate;
+} | {
+    ok: false;
+    error: string;
+};
+/** spec/aviation.md §11: each configuration a labelled session ran that no certificate covers. */
+export declare function unapprovedModifications(lines: readonly string[], certificates: ReadonlyArray<{
+    label: string;
+    configuration: string;
+}>): Finding[];
+export interface OperatorFacts {
+    packs: string[];
+    audit_chain_ok: boolean;
+    anchoring: {
+        enabled: boolean;
+        dead: number;
+    };
+    incidents_open: number;
+    checks_overdue: number | null;
+}
+/** spec/aviation.md §14: the operator's certificate (unsigned) over the facts. */
+export declare function operatorCertificate(facts: OperatorFacts, options: {
+    operator: string;
+    issuedAt: string;
+    days?: number;
+}): {
+    v: 1;
+    type: "blackbox.operator-certificate";
+    operator: string;
+    issued_at: string;
+    expires_at: string;
+    controls: OperatorFacts;
+    verdict: "certified" | "not_certified";
+    reasons: string[];
+};
+/** spec/aviation.md §14: an operator certificate checked offline, like an accreditation. */
+export declare function checkOperatorCertificate(cert: unknown, options: {
+    issuers?: readonly string[];
+    now: string;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface Check {
+    id: string;
+    label: string;
+    kind: "drill" | "scenario";
+    every_days: number;
+    grace_days?: number;
+}
+export interface CheckStatus {
+    id: string;
+    label: string;
+    kind: "drill" | "scenario";
+    every_days: number;
+    grace_days: number;
+    last_done: string | null;
+    due_at: string | null;
+    status: "current" | "due" | "overdue";
+}
+/** spec/aviation.md §12: an error message, or null for a valid checks file. */
+export declare function checkChecks(doc: unknown): string | null;
+/** spec/aviation.md §12: each check's last run, due date and status at `now`. */
+export declare function checkStatus(checks: readonly Check[], done: ReadonlyArray<{
+    label: string;
+    kind: string;
+    at: string;
+}>, now: string): CheckStatus[];
+/** spec/aviation.md §12: an overdue check of the session's label, flagged at pre-flight. */
+export declare function checkFindings(lines: readonly string[], statuses: readonly CheckStatus[]): Finding[];
+export interface Currency {
+    label: string;
+    model: string;
+    last_flown: string | null;
+    current: boolean;
+}
+/** spec/aviation.md §13: whether each airworthy rating is still current. */
+export declare function ratingCurrency(ratings: ReadonlyArray<{
+    label: string;
+    model: string;
+    verdict: string;
+}>, items: ReadonlyArray<{
+    summary: {
+        label: string | null;
+        started_at: string;
+        closed: boolean;
+    };
+    models: readonly string[];
+}>, options: {
+    days: number;
+    now: string;
+}): Currency[];
+/** spec/aviation.md §13: each model the session uses whose rating for its label has lapsed. */
+export declare function ratingLapsed(lines: readonly string[], prices: LoadedPrices, currency: readonly Currency[], severity?: "advisory" | "warning"): Finding[];
+export interface ApproverStat {
+    approver: string;
+    decisions: number;
+    approved: number;
+    rejected: number;
+    approve_ppm: number;
+    median_ms: number | null;
+    fast: number;
+    fast_ppm: number;
+    rubber_stamp: boolean;
+}
+/** spec/aviation.md §18: each approver's decisions, speed and whether they rubber-stamp. */
+export declare function approverStats(records: ReadonlyArray<readonly string[]>, options?: {
+    fastMs?: number;
+    minDecisions?: number;
+    rubberStampPpm?: number;
+}): {
+    approvers: ApproverStat[];
+};
+/** spec/aviation.md §18: once per rubber-stamping approver who decided in this session. */
+export declare function approverFatigueFindings(lines: readonly string[], stats: {
+    approvers: readonly ApproverStat[];
+}): Finding[];