@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/analysis/index.js

@@ -0,0 +1,388 @@
+// Analyses that produce findings (spec/findings.md): pure functions over a session's record, run
+// offline or by the server on the live record. Mirrors sdks/python/src/zanii_blackbox/analysis/.
+import { approvalFindings } from "../approvals/index.js";
+import { automationSurprise } from "../authority/index.js";
+import { dutyFindings } from "../duty/index.js";
+import { policyFindings } from "../policy/index.js";
+import { precogFindings } from "../precog/index.js";
+import { preflightFindings } from "../preflight/index.js";
+import { canonical } from "../reconcile/shared.js";
+import { undoFindings } from "../undo/index.js";
+import { detectors } from "./detectors.js";
+import { flightPlan } from "./landing.js";
+import { memoryFindings } from "./memory.js";
+export { checkFlightPlan, landing, } from "./landing.js";
+export { OUTCOMES, rollup, waste, } from "./waste.js";
+const decoder = new TextDecoder();
+/** Parses the lines once, attaching SDK event bodies. */
+export function eventsOf(lines, bodies) {
+    // N4 (idea R6): a re-sent SDK event (meta.duplicate_of) stays on the record but counts once.
+    return lines.flatMap((line) => {
+        const e = JSON.parse(line);
+        if (e.kind === "sdk.event" && e.meta.duplicate_of !== undefined)
+            return [];
+        if (e.kind === "sdk.event") {
+            const b = bodies(e.body_hash);
+            try {
+                const parsed = b === undefined ? {} : JSON.parse(decoder.decode(b));
+                e.data =
+                    typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+            }
+            catch {
+                e.data = {};
+            }
+        }
+        return [e];
+    });
+}
+/** Every analysis, in spec order. */
+export function analyze(lines, options) {
+    const events = eventsOf(lines, options.bodies);
+    const now = options.now ?? Date.now();
+    const graceMs = options.graceMs ?? 60_000;
+    return [
+        ...dualWitness(events, now, graceMs),
+        ...checkpointReplay(events),
+        ...orphanedToolCalls(events, now),
+        ...tokenMisuse(events),
+        ...verifyRegression(events),
+        ...falseSuccess(events, now),
+        ...exitDurability(events),
+        ...detectors(lines, {
+            bodies: options.bodies,
+            now,
+            ...(options.prices ? { prices: options.prices } : {}),
+            ...(options.budgetMicroUsd ? { budgetMicroUsd: options.budgetMicroUsd } : {}),
+        }),
+        ...flightPlan(events, lines, options.bodies),
+        ...(options.policy ? policyFindings(lines, options.bodies, options.policy) : []),
+        ...nearMisses(events),
+        ...memoryFindings(events),
+        ...attestationFindings(events),
+        ...automationSurprise(lines),
+        ...undoFindings(lines, options.bodies),
+        ...approvalFindings(lines),
+        ...preflightFindings(lines),
+        ...dutyFindings(lines, options.prices, options.duty),
+        ...(options.precog && options.prices
+            ? precogFindings(lines, options.bodies, options.prices, options.precog)
+            : []),
+    ];
+}
+/** spec/attestation.md §3: a re-run that printed something else than the model was given. */
+export function attestationFindings(events) {
+    return events
+        .filter((e) => e.kind === "sdk.event" &&
+        e.meta.type === "attestation" &&
+        e.data?.match === false &&
+        e.data.error === undefined)
+        .map((e) => ({
+        code: "TOOL_OUTPUT_MISMATCH",
+        source: "attestation",
+        severity: "warning",
+        ref: { seq: e.seq },
+    }));
+}
+/** spec/fleet.md §3: the agent's own near-miss reports. */
+export function nearMisses(events) {
+    return events
+        .filter((e) => e.kind === "sdk.event" && e.meta.type === "near_miss")
+        .map((e) => ({
+        code: "NEAR_MISS",
+        source: "agent",
+        severity: "advisory",
+        ref: { seq: e.seq },
+    }));
+}
+/** A stable key for dedup: code + ref with sorted keys. */
+export function findingKey(f) {
+    return `${f.code}:${JSON.stringify(Object.keys(f.ref)
+        .sort()
+        .map((k) => [k, f.ref[k]]))}`;
+}
+// ---------------------------------------------------------------- dual witness (spec/findings.md §2)
+const ID_KEYS = ["message_id", "request_id", "response_id", "completion_id"];
+function idsOf(source) {
+    if (!source)
+        return [];
+    return ID_KEYS.map((k) => source[k]).filter((v) => typeof v === "string" && v !== "");
+}
+export function dualWitness(events, now, graceMs) {
+    const old = (e) => now === Number.POSITIVE_INFINITY || Date.parse(e.ts) <= now - graceMs;
+    const gateway = events.filter((e) => e.kind === "llm.response" || e.kind === "llm.incomplete");
+    const sdk = events.filter((e) => e.kind === "sdk.event" && e.meta.type === "llm.call");
+    const gatewayIds = new Set(gateway.flatMap((e) => idsOf(e.meta)));
+    const sdkIds = new Set(sdk.flatMap((e) => idsOf(e.data)));
+    const findings = [];
+    for (const e of sdk) {
+        const ids = idsOf(e.data);
+        if (ids.length === 0 || !old(e) || ids.some((id) => gatewayIds.has(id)))
+            continue;
+        findings.push({
+            code: "BYPASS",
+            source: "dual_witness",
+            severity: "warning",
+            ref: { sdk_seq: e.meta.sdk_seq },
+            detail: "The SDK reported a model call the gateway never saw: the agent called a model around the gateway.",
+        });
+    }
+    // L2.3.2: a session opened with `sdk: true` expects the SDK from the start, even if it never reports.
+    const expected = events[0]?.kind === "session.open" && events[0].meta.sdk === true;
+    const first = sdk[0];
+    if (first || expected) {
+        let run = [];
+        for (const e of gateway) {
+            if ((first && e.seq < first.seq) || !old(e))
+                continue;
+            if (idsOf(e.meta).some((id) => sdkIds.has(id)))
+                run = [];
+            else
+                run.push(e);
+            if (run.length === 3) {
+                findings.push({
+                    code: "SDK_SILENT",
+                    source: "dual_witness",
+                    severity: "caution",
+                    ref: { after_seq: run[0].seq },
+                    detail: first
+                        ? "The gateway saw 3 model calls in a row the SDK didn't report: the SDK was disabled or removed."
+                        : "The session expected an SDK, but the gateway saw 3 model calls and the SDK reported none.",
+                });
+                break;
+            }
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------- checkpoint replay (spec/findings.md §3)
+export function checkpointReplay(events) {
+    const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+    const failed = new Set();
+    const written = [];
+    const interrupts = [];
+    for (const e of events) {
+        if (e.kind !== "sdk.event" || !e.data)
+            continue;
+        if (e.meta.type === "tool.result" && e.data.ok === false && str(e.data.run_id))
+            failed.add(e.data.run_id);
+        // N5 (idea R2): a checkpointer's record of a task's writes (hooks/langgraph-checkpoint)
+        if (e.meta.type === "checkpoint.writes" && str(e.data.task_id))
+            written.push({ seq: e.seq, taskId: e.data.task_id });
+        if (e.meta.type === "interrupt")
+            interrupts.push({
+                seq: e.seq,
+                thread: str(e.data.thread_id),
+                node: str(e.data.node),
+                taskId: str(e.data.task_id),
+            });
+    }
+    const calls = [];
+    const findings = [];
+    for (const e of events) {
+        if (e.kind !== "sdk.event" || e.meta.type !== "tool.call" || !e.data)
+            continue;
+        const thread = str(e.data.thread_id);
+        const root = str(e.data.root_run_id);
+        const node = str(e.data.node);
+        const taskId = str(e.data.task_id);
+        if (!thread || !root || (!node && !taskId))
+            continue;
+        const call = {
+            seq: e.seq,
+            sdkSeq: e.meta.sdk_seq,
+            name: String(e.meta.name ?? ""),
+            args: canonical(e.data.args ?? null),
+            thread,
+            root,
+            ...(node ? { node } : {}),
+            ...(taskId ? { taskId } : {}),
+            ...(str(e.data.run_id) ? { runId: e.data.run_id } : {}),
+        };
+        const same = (c) => c.name === call.name &&
+            c.args === call.args &&
+            c.thread === call.thread &&
+            c.root !== call.root &&
+            (c.taskId && call.taskId
+                ? c.taskId === call.taskId
+                : c.node !== undefined && c.node === call.node) &&
+            !(c.runId && failed.has(c.runId));
+        const first = calls.find(same);
+        if (first) {
+            const paused = interrupts.some((i) => i.seq > first.seq &&
+                i.seq < call.seq &&
+                i.thread === first.thread &&
+                (first.taskId && i.taskId ? i.taskId === first.taskId : i.node === first.node));
+            findings.push({
+                code: "CHECKPOINT_REPLAY",
+                source: "detectors",
+                severity: "warning",
+                ref: {
+                    sdk_seq: call.sdkSeq,
+                    first_sdk_seq: first.sdkSeq,
+                    cause: paused ? "pre_interrupt_side_effect" : "resume",
+                    // Task ids are deterministic: a checkpointed write of the same task between the two
+                    // calls makes it the same task run again, not a guess.
+                    ...(first.taskId &&
+                        written.some((w) => w.taskId === first.taskId && w.seq > first.seq && w.seq < call.seq)
+                        ? { certain: true }
+                        : {}),
+                },
+                detail: paused
+                    ? "A node ran this tool, paused at interrupt(), and resuming re-ran the node from the top: the side effect happened twice."
+                    : "A resumed LangGraph run re-executed a tool call an earlier run already made (a repeated side effect).",
+            });
+        }
+        calls.push(call);
+    }
+    return findings;
+}
+// ---------------------------------------------------------------- orphaned tool calls (spec/findings.md §3)
+/** N4 (idea R9): a tool call with no result, judged at close (`now` is +Infinity): a crash
+ * mid-call. */
+export function orphanedToolCalls(events, now) {
+    if (now !== Number.POSITIVE_INFINITY)
+        return [];
+    const finished = new Set();
+    const answered = new Set();
+    const refused = new Set();
+    for (const e of events) {
+        if (e.kind === "sdk.event" &&
+            e.meta.type === "tool.result" &&
+            typeof e.data?.run_id === "string")
+            finished.add(e.data.run_id);
+        if (e.kind === "tool.result" && typeof e.meta.call_seq === "number")
+            answered.add(e.meta.call_seq);
+        if (e.kind === "control" &&
+            e.meta.action === "approval" &&
+            e.meta.decision !== "approve" &&
+            typeof e.meta.approval_id === "string")
+            refused.add(e.meta.approval_id);
+    }
+    const out = [];
+    for (const e of events) {
+        const runId = e.data?.run_id;
+        if (e.kind === "sdk.event" && e.meta.type === "tool.call" && typeof runId === "string") {
+            if (!finished.has(runId))
+                out.push({
+                    code: "ORPHANED_TOOL_CALL",
+                    source: "detectors",
+                    severity: "caution",
+                    ref: { sdk_seq: e.meta.sdk_seq, run_id: runId },
+                    detail: "A tool call started and never finished: the agent or the tool stopped mid-call. Check what it did before resuming.",
+                });
+            continue;
+        }
+        if (e.kind !== "tool.call" || e.meta.method !== "tools/call" || e.meta.transport === "stdio")
+            continue;
+        const p = e.meta.policy;
+        const held = typeof p?.approval_id === "string" && refused.has(p.approval_id);
+        if (answered.has(e.seq) || p?.action === "deny" || held)
+            continue;
+        out.push({
+            code: "ORPHANED_TOOL_CALL",
+            source: "detectors",
+            severity: "caution",
+            ref: { seq: e.seq },
+            detail: "The gateway forwarded a tool call and never recorded its result: it stopped mid-call. Check what the tool did before resuming.",
+        });
+    }
+    return out;
+}
+/** N4 (idea R5): a LangGraph run in `exit` durability that ran tools. Once per session. */
+export function exitDurability(events) {
+    const cfg = events.find((e) => e.kind === "sdk.event" && e.meta.type === "run.config" && e.data?.durability === "exit");
+    if (!cfg)
+        return [];
+    const tool = events.find((e) => e.seq > cfg.seq &&
+        ((e.kind === "sdk.event" && e.meta.type === "tool.call") ||
+            (e.kind === "tool.call" && e.meta.method === "tools/call")));
+    if (!tool)
+        return [];
+    return [
+        {
+            code: "EXIT_DURABILITY",
+            source: "detectors",
+            severity: "caution",
+            ref: { sdk_seq: cfg.meta.sdk_seq, first_tool_seq: tool.seq },
+            detail: "The run saves its state only when it exits (durability exit) and ran tools: a crash loses the record of what already ran, and a resume runs it again.",
+        },
+    ];
+}
+/** N6 (idea S3): the gateway refused a request that carried the session's own token. */
+export function tokenMisuse(events) {
+    return events
+        .filter((e) => e.meta.token_in_body === true)
+        .map((e) => ({
+        code: "TOKEN_MISUSE",
+        source: "detectors",
+        severity: "warning",
+        ref: { seq: e.seq },
+        detail: "The agent put its own session token into a request (a prompt or a tool call): it was refused, and the token should be treated as exposed.",
+    }));
+}
+// ---------------------------------------------------------------- verification (spec/findings.md §6)
+/** Stage 2 R3: a `verify` check that passed, then failed later in the run. */
+export function verifyRegression(events) {
+    const passed = new Map();
+    const out = [];
+    for (const e of events) {
+        if (e.kind !== "sdk.event" || e.meta.type !== "verify" || typeof e.meta.name !== "string")
+            continue;
+        const check = e.meta.name;
+        const seq = e.meta.sdk_seq;
+        if (e.data?.ok === true)
+            passed.set(check, seq);
+        else if (e.data?.ok === false && passed.has(check)) {
+            out.push({
+                code: "VERIFY_REGRESSION",
+                source: "verification",
+                severity: "caution",
+                ref: { sdk_seq: seq, check, passed_sdk_seq: passed.get(check) },
+                detail: "A check that passed earlier now fails: something the agent did since broke it.",
+            });
+            passed.delete(check);
+        }
+    }
+    return out;
+}
+/** Stage 2 R4, judged at close: a run labelled (or claimed) a success that its own record contradicts:
+ * a check's last result failed, or the last tool call failed with nothing succeeding after it. */
+export function falseSuccess(events, now) {
+    if (now !== Number.POSITIVE_INFINITY)
+        return [];
+    const outcome = events.filter((e) => e.kind === "outcome").at(-1)?.meta.outcome;
+    const claimed = events.some((e) => e.kind === "sdk.event" && e.meta.type === "claim");
+    const by = outcome === "success" ? "outcome" : outcome === undefined && claimed ? "claim" : null;
+    if (!by)
+        return [];
+    const last = new Map();
+    let tool = null;
+    for (const e of events) {
+        if (e.kind === "sdk.event" && e.meta.type === "verify" && typeof e.meta.name === "string")
+            last.set(e.meta.name, e);
+        const sdkResult = e.kind === "sdk.event" && e.meta.type === "tool.result";
+        if (sdkResult && typeof e.data?.ok === "boolean")
+            tool = { seq: e.seq, failed: e.data.ok === false };
+        if (e.kind === "tool.result" && typeof e.meta.is_error === "boolean")
+            tool = { seq: e.seq, failed: e.meta.is_error === true };
+    }
+    const failing = [...last.values()].find((e) => e.data?.ok === false);
+    const finding = (reason, seq, detail) => [
+        {
+            code: "FALSE_SUCCESS",
+            source: "verification",
+            severity: "warning",
+            ref: { claimed: by, reason, seq },
+            detail,
+        },
+    ];
+    if (failing)
+        return finding("failing_check", failing.seq, by === "outcome"
+            ? "The run is labelled a success, but a check it ran last failed."
+            : "The agent claimed it was done, but a check it ran last failed.");
+    if (tool?.failed)
+        return finding("last_tool_failed", tool.seq, by === "outcome"
+            ? "The run is labelled a success, but its last tool call failed and nothing succeeded after it."
+            : "The agent claimed it was done, but its last tool call failed and nothing succeeded after it.");
+    return [];
+}

package/dist/analysis/landing.d.ts

@@ -0,0 +1,25 @@
+import type { Json } from "../verify/index.ts";
+import type { Ev, Finding } from "./index.ts";
+export type Result = "pass" | "fail" | "cannot_verify";
+export interface CriterionResult {
+    criterion: string;
+    predicate: Json;
+    result: Result;
+    gap?: string;
+}
+export interface ClaimVerdict {
+    seq: number;
+    summary?: string;
+    verdict: "satisfied" | "failed" | "unverified";
+    criteria: CriterionResult[];
+}
+export interface Landing {
+    plan: {
+        [key: string]: Json;
+    } | null;
+    claims: ClaimVerdict[];
+}
+export declare function landing(events: Ev[], lines: readonly string[], bodies: (h: string) => Uint8Array | undefined): Landing;
+export declare function flightPlan(events: Ev[], lines: readonly string[], bodies: (h: string) => Uint8Array | undefined): Finding[];
+/** Why a flight plan is invalid (spec/findings.md §5), or undefined if it's fine. */
+export declare function checkFlightPlan(plan: unknown): string | undefined;

package/dist/analysis/landing.js

@@ -0,0 +1,225 @@
+// Flight plan and landing checklist (spec/findings.md §5): a declared plan, deviations from it, and
+// completion claims judged against the gateway's record. Mirrors analysis/landing.py.
+import { checkDuty } from "../duty/index.js";
+import { callsOf } from "../reconcile/record.js";
+import { isObj } from "../reconcile/shared.js";
+import { toolCallsOf, toolResultsOf } from "./detectors.js";
+/** Every tool call in the record, with what its result said (provider tool_use ids; MCP call_seq). */
+function usesOf(events, lines, bodies) {
+    const calls = callsOf(lines, bodies);
+    const results = new Map();
+    for (const r of toolResultsOf(calls, lines))
+        if (r.id !== undefined)
+            results.set(r.id, r);
+    const uses = toolCallsOf(calls).map((t) => {
+        const r = t.id === undefined ? undefined : results.get(t.id);
+        return r
+            ? { seq: t.seq, tool: t.tool, ok: !r.error, resultSeq: r.seq }
+            : { seq: t.seq, tool: t.tool };
+    });
+    const mcp = new Map();
+    for (const e of events) {
+        if (e.kind === "tool.call" &&
+            e.meta.method === "tools/call" &&
+            typeof e.meta.tool === "string") {
+            const u = { seq: e.seq, tool: e.meta.tool };
+            mcp.set(e.seq, u);
+            uses.push(u);
+        }
+        else if (e.kind === "tool.result" && typeof e.meta.call_seq === "number") {
+            const u = mcp.get(e.meta.call_seq);
+            if (u && u.ok === undefined) {
+                u.ok =
+                    e.meta.rpc_error !== undefined || e.meta.is_error === true
+                        ? false
+                        : e.meta.is_error === false
+                            ? true
+                            : null;
+                u.resultSeq = e.seq;
+            }
+        }
+    }
+    return uses.sort((a, b) => a.seq - b.seq);
+}
+function planOf(events) {
+    return plansOf(events).plan;
+}
+/** The plan in force, and the SDK filings refused on the way (spec/findings.md §5, L3.4.6): the
+ * plan from session.open wins; else the first valid `flight_plan` SDK event. */
+function plansOf(events) {
+    const open = events[0];
+    if (open?.kind === "session.open" && isObj(open.meta.flight_plan))
+        return { plan: open.meta.flight_plan, invalid: [] };
+    const invalid = [];
+    for (const e of events) {
+        if (e.kind !== "sdk.event" || e.meta.type !== "flight_plan")
+            continue;
+        const error = checkFlightPlan(e.data);
+        if (!error)
+            return { plan: e.data, invalid };
+        invalid.push({ seq: e.seq, error });
+    }
+    return { plan: null, invalid };
+}
+const listOf = (v) => (Array.isArray(v) ? v : []);
+/** One predicate over the tool calls (and results) recorded before `before`. */
+function judge(p, uses, before) {
+    const seen = uses.filter((u) => u.seq < before);
+    const one = isObj(p) && Object.keys(p).length === 1 ? Object.entries(p)[0] : null;
+    const [key, arg] = one ?? ["", null];
+    const named = typeof arg === "string" ? seen.filter((u) => u.tool === arg) : [];
+    const out = (result, gap) => ({ predicate: p, result, ...(gap ? { gap } : {}) });
+    if (key === "tool_called" && typeof arg === "string")
+        return named.length ? out("pass") : out("fail", `${arg} was never called`);
+    if (key === "tool_not_called" && typeof arg === "string")
+        return named.length
+            ? out("fail", `${arg} was called (seq ${named[0].seq})`)
+            : out("pass");
+    if (key === "max_tool_calls" && typeof arg === "number" && Number.isSafeInteger(arg))
+        return seen.length <= arg
+            ? out("pass")
+            : out("fail", `${seen.length} tool calls, more than ${arg}`);
+    if (key === "tool_succeeded" && typeof arg === "string") {
+        if (!named.length)
+            return out("fail", `${arg} was never called`);
+        const judged = named.map((u) => u.resultSeq !== undefined && u.resultSeq < before ? u.ok : undefined);
+        if (judged.includes(true))
+            return out("pass");
+        if (judged.every((ok) => ok === false))
+            return out("fail", `every ${arg} call returned an error`);
+        return out("cannot_verify", `no recorded result says whether ${arg} worked`);
+    }
+    return out("cannot_verify", "unsupported predicate");
+}
+export function landing(events, lines, bodies) {
+    const plan = planOf(events);
+    const uses = usesOf(events, lines, bodies);
+    const claims = [];
+    for (const e of events) {
+        if (e.kind !== "sdk.event" || e.meta.type !== "claim")
+            continue;
+        const data = e.data ?? {};
+        const criteria = [
+            ...listOf(plan?.criteria).map((p, i) => ({
+                criterion: `plan:${i}`,
+                ...judge(p, uses, e.seq),
+            })),
+            ...listOf(data.asserts).map((p, i) => ({
+                criterion: `assert:${i}`,
+                ...judge(p, uses, e.seq),
+            })),
+        ];
+        const verdict = criteria.some((c) => c.result === "fail")
+            ? "failed"
+            : criteria.length === 0 || criteria.some((c) => c.result === "cannot_verify")
+                ? "unverified"
+                : "satisfied";
+        claims.push({
+            seq: e.seq,
+            ...(typeof data.summary === "string" ? { summary: data.summary } : {}),
+            verdict,
+            criteria,
+        });
+    }
+    return { plan, claims };
+}
+const f = (code, severity, ref, detail) => ({
+    code,
+    source: "flight_plan",
+    severity,
+    ref,
+    detail,
+});
+export function flightPlan(events, lines, bodies) {
+    const { plan, claims } = landing(events, lines, bodies);
+    const out = plansOf(events).invalid.map((x) => f("PLAN_INVALID", "advisory", { seq: x.seq }, `A flight plan filed by the SDK was ignored: ${x.error}.`));
+    if (plan) {
+        const uses = usesOf(events, lines, bodies);
+        const expected = Array.isArray(plan.expected_tools) ? new Set(plan.expected_tools) : null;
+        if (expected) {
+            const reported = new Set();
+            for (const u of uses)
+                if (!expected.has(u.tool) && !reported.has(u.tool)) {
+                    reported.add(u.tool);
+                    out.push(f("PLAN_DEVIATION", "caution", { tool: u.tool }, `${u.tool} isn't in the flight plan.`));
+                }
+        }
+        listOf(plan.criteria).forEach((p, i) => {
+            if (!isObj(p) || !("tool_not_called" in p || "max_tool_calls" in p))
+                return;
+            const r = judge(p, uses, Number.POSITIVE_INFINITY);
+            if (r.result === "fail")
+                out.push(f("PLAN_VIOLATION", "warning", { criterion: `plan:${i}` }, `Flight plan broken: ${r.gap}.`));
+        });
+        // Sterile cockpit (A9): from the first call to `after` until the first call to `until` (if
+        // set), only `after`, `until` and the `allow` tools.
+        listOf(plan.sterile).forEach((phase, i) => {
+            if (!isObj(phase) || typeof phase.after !== "string")
+                return;
+            const until = typeof phase.until === "string" ? phase.until : undefined;
+            const allowed = new Set([phase.after, ...(until ? [until] : []), ...listOf(phase.allow)]);
+            const start = uses.find((u) => u.tool === phase.after);
+            const end = start && until ? uses.find((u) => u.seq > start.seq && u.tool === until) : undefined;
+            const reported = new Set();
+            for (const u of uses)
+                if (start &&
+                    u.seq > start.seq &&
+                    (end === undefined || u.seq < end.seq) &&
+                    !allowed.has(u.tool) &&
+                    !reported.has(u.tool)) {
+                    reported.add(u.tool);
+                    out.push(f("STERILE_VIOLATION", "warning", { phase: `sterile:${i}`, tool: u.tool }, `${u.tool} was called in the sterile phase after ${phase.after}.`));
+                }
+        });
+    }
+    for (const c of claims) {
+        if (c.criteria.length === 0)
+            out.push(f("CLAIM_UNVERIFIED", "caution", { claim_seq: c.seq, criterion: "none" }, "A completion claim with nothing to check it against."));
+        for (const r of c.criteria)
+            if (r.result === "fail")
+                out.push(f("FALSE_CLAIM", "warning", { claim_seq: c.seq, criterion: r.criterion }, `Claimed done, but ${r.gap}.`));
+            else if (r.result === "cannot_verify")
+                out.push(f("CLAIM_UNVERIFIED", "caution", { claim_seq: c.seq, criterion: r.criterion }, `Can't verify the claim: ${r.gap}.`));
+    }
+    return out;
+}
+/** Why a flight plan is invalid (spec/findings.md §5), or undefined if it's fine. */
+export function checkFlightPlan(plan) {
+    if (!isObj(plan))
+        return "flight_plan must be an object";
+    const { objective, expected_tools: tools, criteria } = plan;
+    if (typeof objective !== "string" || objective.length === 0 || objective.length > 2000)
+        return "flight_plan.objective must be a string of 1–2000 characters";
+    if (tools !== undefined &&
+        !(Array.isArray(tools) &&
+            tools.length <= 100 &&
+            tools.every((x) => typeof x === "string" && x.length > 0 && x.length <= 128)))
+        return "flight_plan.expected_tools must be at most 100 tool names";
+    const value = (v) => typeof v === "string" ? v.length <= 128 : Number.isSafeInteger(v) && v >= 0;
+    if (criteria !== undefined &&
+        !(Array.isArray(criteria) &&
+            criteria.length <= 50 &&
+            criteria.every((c) => isObj(c) && Object.keys(c).length === 1 && value(Object.values(c)[0]))))
+        return 'flight_plan.criteria must be at most 50 predicates like {"tool_called": "run_tests"}';
+    const name = (x) => typeof x === "string" && x.length > 0 && x.length <= 128;
+    const { sterile } = plan;
+    if (sterile !== undefined &&
+        !(Array.isArray(sterile) &&
+            sterile.length <= 10 &&
+            sterile.every((p) => isObj(p) &&
+                name(p.after) &&
+                Object.keys(p).every((k) => k === "after" || k === "allow" || k === "until") &&
+                (p.until === undefined || name(p.until)) &&
+                (p.allow === undefined ||
+                    (Array.isArray(p.allow) && p.allow.length <= 100 && p.allow.every(name))))))
+        return 'flight_plan.sterile must be at most 10 phases like {"after": "deploy", "allow": ["rollback"]}';
+    if (plan.duty !== undefined) {
+        const bad = checkDuty(plan.duty); // spec/duty.md §1
+        if (bad)
+            return bad;
+    }
+    const extra = Object.keys(plan).filter((k) => !["objective", "expected_tools", "criteria", "sterile", "duty"].includes(k));
+    if (extra.length)
+        return `flight_plan has unknown fields: ${extra.join(", ")}`;
+    return undefined;
+}

package/dist/analysis/memory.d.ts

@@ -0,0 +1,13 @@
+import type { Ev, Finding } from "./index.ts";
+/** spec/agents.md §2, over parsed events (sdk.event bodies attached). */
+export declare function memoryXrayOf(events: readonly Ev[], revokedElsewhere?: readonly string[]): {
+    writes: number;
+    reads: number;
+    revoked: string[];
+    stale_reads: {
+        seq: number;
+        memory_id: string;
+    }[];
+};
+/** The findings part (this record's own revocations only). */
+export declare function memoryFindings(events: readonly Ev[]): Finding[];