@zanii/blackbox 0.0.0-stage → 0.1.0

package/dist/cost/index.js

@@ -0,0 +1,293 @@
+// The cost engine (spec/cost.md): integer micro-USD from a versioned price table, AED display.
+// Mirrors sdks/python/src/zanii_blackbox/cost.py.
+import { createHash } from "node:crypto";
+const CLASSES = ["input", "output", "cache_read", "cache_write"];
+const EXTRA = ["cache_write_1h", "input_audio", "output_audio"];
+const OPTIONAL_PRICES = [
+    "context_window",
+    "cache_write_1h",
+    "input_audio",
+    "output_audio",
+    "web_search_per_1k",
+];
+/** Parses and checks a price table; its sha256 is of the exact file bytes. */
+export function loadPrices(bytes) {
+    const table = JSON.parse(new TextDecoder().decode(bytes));
+    if (table.currency !== "USD" ||
+        table.unit !== "micro_usd_per_mtok" ||
+        typeof table.models !== "object")
+        throw new Error("not a v1 price table (USD, micro_usd_per_mtok)");
+    const whole = (model, field, v) => {
+        if (!Number.isSafeInteger(v) || v < 0)
+            throw new Error(`price table: ${model}.${field} must be an integer ≥ 0`);
+    };
+    for (const [model, p] of Object.entries(table.models)) {
+        for (const c of CLASSES)
+            whole(model, c, p[c]);
+        for (const c of OPTIONAL_PRICES)
+            if (p[c] !== undefined)
+                whole(model, c, p[c]);
+        for (const [i, t] of (p.context_tiers ?? []).entries()) {
+            whole(model, `context_tiers[${i}].above`, t.above);
+            for (const c of CLASSES)
+                if (t[c] !== undefined)
+                    whole(model, `context_tiers[${i}].${c}`, t[c]);
+        }
+        for (const [name, t] of Object.entries(p.service_tiers ?? {}))
+            for (const c of CLASSES)
+                if (t[c] !== undefined)
+                    whole(model, `service_tiers.${name}.${c}`, t[c]);
+        if (p.status !== undefined && p.status !== "deprecated" && p.status !== "beta")
+            throw new Error(`price table: ${model}.status must be deprecated or beta`);
+    }
+    return { table, sha256: `sha256:${createHash("sha256").update(bytes).digest("hex")}` };
+}
+/** The exact model, else the longest table key the model starts with; null when there's none. */
+export function priceFor(model, table, 
+/** The configured provider id: `<provider>/<model>` keys are tried first (spec/cost.md §1). */
+provider) {
+    if (provider) {
+        const scoped = lookup(`${provider}/${model}`, table);
+        if (scoped)
+            return scoped;
+    }
+    const found = lookup(model, table);
+    if (found)
+        return found;
+    // spec/cost.md §1: a cloud's model id (Bedrock's `us.anthropic.claude-…`) as the vendor's own
+    const plain = model.replace(GEO, "").replace(VENDOR, "");
+    return plain !== model ? lookup(plain, table) : null;
+}
+const GEO = /^(?:us|eu|apac|au|ca|jp|global|us-gov)\./;
+const VENDOR = /^(?:anthropic|amazon|meta|mistral|cohere|ai21|deepseek|openai|qwen|writer|google)\./;
+function lookup(model, table) {
+    const exact = table.models[model];
+    if (exact)
+        return { key: model, price: exact };
+    let best = null;
+    for (const key of Object.keys(table.models))
+        if (model.startsWith(key) && (best === null || key.length > best.length))
+            best = key;
+    return best === null ? null : { key: best, price: table.models[best] };
+}
+/** Token classes from a recorded, flattened `meta.usage` (spec/cost.md §2). */
+export function tokensOf(usage) {
+    const n = (k) => {
+        const v = usage[k];
+        return typeof v === "number" && Number.isSafeInteger(v) && v > 0 ? v : 0;
+    };
+    if ("promptTokenCount" in usage) {
+        // Gemini (spec/providers.md §5): the prompt count includes the cached part; thoughts are output.
+        const cached = n("cachedContentTokenCount");
+        const audioIn = n("promptTokensDetails_AUDIO");
+        const audioOut = n("candidatesTokensDetails_AUDIO");
+        return extras({
+            input: Math.max(0, n("promptTokenCount") - cached - audioIn) + n("toolUsePromptTokenCount"),
+            output: Math.max(0, n("candidatesTokenCount") - audioOut) + n("thoughtsTokenCount"),
+            cache_read: cached,
+            cache_write: 0,
+        }, { input_audio: audioIn, output_audio: audioOut });
+    }
+    if ("inputTokens" in usage)
+        // Bedrock Converse (spec/providers.md §5)
+        return {
+            input: n("inputTokens"),
+            output: n("outputTokens"),
+            cache_read: n("cacheReadInputTokens"),
+            cache_write: n("cacheWriteInputTokens"),
+        };
+    if ("prompt_tokens" in usage) {
+        // prompt_tokens includes both the cached part and the part written to the cache (B1)
+        const cached = n("prompt_tokens_details_cached_tokens");
+        const written = n("prompt_tokens_details_cache_write_tokens");
+        const audioIn = n("prompt_tokens_details_audio_tokens");
+        const audioOut = n("completion_tokens_details_audio_tokens");
+        return extras({
+            input: Math.max(0, n("prompt_tokens") - cached - written - audioIn),
+            output: Math.max(0, n("completion_tokens") - audioOut),
+            cache_read: cached,
+            cache_write: written,
+        }, { input_audio: audioIn, output_audio: audioOut });
+    }
+    if (Object.keys(usage).some((k) => k.startsWith("input_tokens_details_") || k.startsWith("output_tokens_details_"))) {
+        const cached = n("input_tokens_details_cached_tokens");
+        const written = n("input_tokens_details_cache_write_tokens");
+        const audioIn = n("input_tokens_details_audio_tokens");
+        const audioOut = n("output_tokens_details_audio_tokens");
+        return extras({
+            input: Math.max(0, n("input_tokens") - cached - written - audioIn),
+            output: Math.max(0, n("output_tokens") - audioOut),
+            cache_read: cached,
+            cache_write: written,
+        }, { input_audio: audioIn, output_audio: audioOut });
+    }
+    // Anthropic: cache_creation_input_tokens is both lifetimes; the 1-hour part is priced apart
+    const hour = n("cache_creation_ephemeral_1h_input_tokens");
+    return extras({
+        input: n("input_tokens"),
+        output: n("output_tokens"),
+        cache_read: n("cache_read_input_tokens"),
+        cache_write: Math.max(0, n("cache_creation_input_tokens") - hour),
+    }, { cache_write_1h: hour });
+}
+/** Adds the optional classes that are non-zero, so a record without them prices as before. */
+function extras(base, more) {
+    const out = { ...base };
+    for (const c of EXTRA)
+        if ((more[c] ?? 0) > 0)
+            out[c] = more[c];
+    return out;
+}
+/** Requests a call made to a provider's server tools (Anthropic web search). */
+export function requestsOf(usage) {
+    const v = usage.server_tool_use_web_search_requests;
+    return typeof v === "number" && Number.isSafeInteger(v) && v > 0 ? { web_search: v } : undefined;
+}
+/** A call's prompt, in tokens: what a context tier is decided on. */
+export function promptTokens(t) {
+    return t.input + t.cache_read + t.cache_write + (t.cache_write_1h ?? 0) + (t.input_audio ?? 0);
+}
+/** The prices a call pays: a context tier when its prompt is over one, then its service tier. */
+export function effectivePrice(price, tokens, serviceTier) {
+    let out = price;
+    const tier = {};
+    const size = promptTokens(tokens);
+    const context = [...(price.context_tiers ?? [])]
+        .sort((a, b) => b.above - a.above)
+        .find((t) => size > t.above);
+    if (context) {
+        out = { ...out, ...pick(context) };
+        tier.context_above = context.above;
+    }
+    const service = serviceTier ? price.service_tiers?.[serviceTier] : undefined;
+    if (service && serviceTier) {
+        out = { ...out, ...pick(service) };
+        tier.service = serviceTier;
+    }
+    return Object.keys(tier).length ? { price: out, tier } : { price: out };
+}
+function pick(t) {
+    const o = {};
+    for (const c of CLASSES)
+        if (t[c] !== undefined)
+            o[c] = t[c];
+    return o;
+}
+/** round_half_up((tokens × price + requests × price per 1k × 1000) / 1e6), integers only. */
+export function callMicroUsd(tokens, price, requests) {
+    let sum = 0;
+    for (const c of CLASSES)
+        sum += tokens[c] * price[c];
+    sum += (tokens.cache_write_1h ?? 0) * (price.cache_write_1h ?? price.cache_write);
+    sum += (tokens.input_audio ?? 0) * (price.input_audio ?? price.input);
+    sum += (tokens.output_audio ?? 0) * (price.output_audio ?? price.output);
+    sum += (requests?.web_search ?? 0) * (price.web_search_per_1k ?? 0) * 1000;
+    if (!Number.isSafeInteger(sum))
+        throw new RangeError("cost overflow: tokens × price beyond 2^53");
+    return Math.floor((sum + 500_000) / 1_000_000);
+}
+/** One call's cost as the cost report prices it: the table (provider-scoped, tiered), else the
+ *  provider's own reported cost, else null. The spend and duty checks use the same. */
+export function priceCall(call, table) {
+    const tokens = tokensOf(call.usage);
+    const requests = requestsOf(call.usage);
+    const match = call.model === null ? null : priceFor(call.model, table, call.provider);
+    if (match) {
+        const { price, tier } = effectivePrice(match.price, tokens, call.serviceTier);
+        return {
+            key: match.key,
+            tokens,
+            micro_usd: callMicroUsd(tokens, price, requests),
+            ...(requests ? { requests } : {}),
+            ...(tier ? { tier } : {}),
+        };
+    }
+    if (typeof call.reportedMicroUsd === "number")
+        return {
+            key: null,
+            tokens,
+            micro_usd: call.reportedMicroUsd,
+            ...(requests ? { requests } : {}),
+            source: "reported",
+        };
+    return { key: null, tokens, micro_usd: null, ...(requests ? { requests } : {}) };
+}
+/** fils at the CBUAE peg (3.6725 AED / USD), rounded half up. */
+export function toAedFils(microUsd) {
+    return Math.floor((microUsd * 36725 + 50_000_000) / 100_000_000);
+}
+export function formatAed(fils) {
+    const sign = fils < 0 ? "-" : "";
+    const abs = Math.abs(fils);
+    return `${sign}AED ${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, "0")}`;
+}
+/** The session's cost report from its recorded lines. */
+export function sessionCost(lines, prices) {
+    const calls = [];
+    const unknown = new Set();
+    const total = { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+    let micro = 0;
+    const replayed = new Set(); // requests served from a cassette: no provider was paid (spec/cost.md)
+    const providers = new Map(); // request seq → the configured provider id
+    let webSearch = 0;
+    let pinnedSha; // session.open's meta.prices_sha256 (L3.1.5)
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        if (e.kind === "session.open")
+            pinnedSha = e.meta.prices_sha256;
+        if (e.kind === "llm.request") {
+            const r = e.meta.replay;
+            if (Number.isSafeInteger(r?.take))
+                replayed.add(e.seq);
+            if (typeof e.meta.provider === "string")
+                providers.set(e.seq, e.meta.provider);
+            continue;
+        }
+        if (e.kind !== "llm.response" && e.kind !== "llm.incomplete")
+            continue;
+        if (replayed.has(e.meta.request_seq))
+            continue;
+        const usage = e.meta.usage;
+        if (typeof usage !== "object" || usage === null)
+            continue;
+        const model = typeof e.meta.model === "string" ? e.meta.model : null;
+        const priced = priceCall({
+            model,
+            usage: usage,
+            provider: providers.get(e.meta.request_seq) ?? null,
+            serviceTier: typeof e.meta.service_tier === "string" ? e.meta.service_tier : null,
+            reportedMicroUsd: Number.isSafeInteger(e.meta.reported_cost_micro_usd)
+                ? e.meta.reported_cost_micro_usd
+                : null,
+        }, prices.table);
+        const { key: _key, ...call } = priced;
+        for (const c of CLASSES)
+            total[c] += call.tokens[c];
+        for (const c of EXTRA)
+            if (call.tokens[c] !== undefined)
+                total[c] = (total[c] ?? 0) + call.tokens[c];
+        webSearch += call.requests?.web_search ?? 0;
+        if (call.micro_usd === null)
+            unknown.add(model ?? "(no model)");
+        else
+            micro += call.micro_usd;
+        calls.push({ seq: e.seq, model, ...call });
+    }
+    return {
+        v: 1,
+        price_table: {
+            version: prices.table.version,
+            sha256: prices.sha256,
+            ...(typeof pinnedSha === "string" ? { pinned: pinnedSha === prices.sha256 } : {}),
+        },
+        total_micro_usd: micro,
+        total_aed_fils: toAedFils(micro),
+        calls_priced: calls.filter((c) => c.micro_usd !== null).length,
+        calls_unpriced: calls.filter((c) => c.micro_usd === null).length,
+        unknown_models: [...unknown].sort(),
+        tokens: total,
+        calls,
+        ...(replayed.size ? { calls_replayed: replayed.size } : {}),
+        ...(webSearch ? { requests: { web_search: webSearch } } : {}),
+    };
+}

package/dist/directives/index.d.ts

@@ -0,0 +1,35 @@
+import { type Summary } from "../fleet/index.ts";
+export interface DirectiveItem {
+    tenant: string;
+    summary: Summary;
+    /** The models the session's calls used, sorted. */
+    models: string[];
+}
+export interface Directive {
+    id: string;
+    applies_to: {
+        model: string;
+    } | {
+        tool: string;
+    };
+    pattern: string[];
+    signature: string;
+    sessions: number;
+    type_sessions: number;
+    affected_ppm: number;
+    failure_ppm: number;
+    tenants: number;
+    first_seen: string;
+}
+export interface DirectiveOptions {
+    k?: number;
+    minSessions?: number;
+    minAffectedPpm?: number;
+}
+/** spec/directives.md §1. */
+export declare function directives(items: readonly DirectiveItem[], { k, minSessions, minAffectedPpm }?: DirectiveOptions): Directive[];
+/** spec/directives.md §2: the directives for the types one fleet flies, with its own sessions. */
+export declare function fleetDirectives(all: readonly Directive[], mine: readonly DirectiveItem[]): Array<Directive & {
+    your_sessions: string[];
+    your_type_sessions: number;
+}>;

package/dist/directives/index.js

@@ -0,0 +1,80 @@
+// Airworthiness directives (spec/directives.md): one failure pattern, on one model or tool, across
+// fleets. Pure; mirrors sdks/python/src/zanii_blackbox/directives.py; pinned by
+// spec/vectors/directives.json.
+import { createHash } from "node:crypto";
+import { signatureOf } from "../fleet/index.js";
+const FAILED = new Set(["failure", "abandoned"]);
+const typesOf = (item) => [
+    ...[...new Set(item.models)].sort().map((m) => `model:${m}`),
+    ...Object.keys(item.summary.tools)
+        .sort()
+        .map((t) => `tool:${t}`),
+];
+/** spec/directives.md §1. */
+export function directives(items, { k = 3, minSessions = 5, minAffectedPpm = 50_000 } = {}) {
+    const typeSessions = new Map();
+    const groups = new Map();
+    for (const item of items) {
+        const sig = signatureOf(item.summary);
+        for (const type of typesOf(item)) {
+            typeSessions.set(type, (typeSessions.get(type) ?? 0) + 1);
+            if (!sig)
+                continue;
+            const key = `${type}|${sig.pattern.join(",")}`;
+            const g = groups.get(key) ?? {
+                type,
+                pattern: sig.pattern,
+                signature: sig.signature,
+                tenants: new Set(),
+                sessions: 0,
+                failed: 0,
+                first: item.summary.started_at,
+            };
+            g.tenants.add(item.tenant);
+            g.sessions++;
+            if (FAILED.has(item.summary.outcome ?? ""))
+                g.failed++;
+            if (item.summary.started_at < g.first)
+                g.first = item.summary.started_at;
+            groups.set(key, g);
+        }
+    }
+    const out = [];
+    for (const [key, g] of groups) {
+        const total = typeSessions.get(g.type) ?? 0;
+        const affected = Math.floor((g.sessions * 1_000_000) / total);
+        if (g.tenants.size < k || g.sessions < minSessions || affected < minAffectedPpm)
+            continue;
+        const [kind, ...rest] = g.type.split(":");
+        const name = rest.join(":");
+        out.push({
+            id: `AD-${createHash("sha256").update(key).digest("hex").slice(0, 10)}`,
+            applies_to: kind === "model" ? { model: name } : { tool: name },
+            pattern: g.pattern,
+            signature: g.signature,
+            sessions: g.sessions,
+            type_sessions: total,
+            affected_ppm: affected,
+            failure_ppm: Math.floor((g.failed * 1_000_000) / g.sessions),
+            tenants: g.tenants.size,
+            first_seen: g.first,
+        });
+    }
+    return out.sort((a, b) => b.affected_ppm !== a.affected_ppm ? b.affected_ppm - a.affected_ppm : a.id < b.id ? -1 : 1);
+}
+/** spec/directives.md §2: the directives for the types one fleet flies, with its own sessions. */
+export function fleetDirectives(all, mine) {
+    const out = [];
+    for (const d of all) {
+        const type = "model" in d.applies_to ? `model:${d.applies_to.model}` : `tool:${d.applies_to.tool}`;
+        const flying = mine.filter((i) => typesOf(i).includes(type));
+        if (flying.length === 0)
+            continue;
+        const hit = flying
+            .filter((i) => signatureOf(i.summary)?.signature === d.signature)
+            .map((i) => i.summary.session_id)
+            .sort();
+        out.push({ ...d, your_sessions: hit, your_type_sessions: flying.length });
+    }
+    return out;
+}

package/dist/drills/index.d.ts

@@ -0,0 +1,43 @@
+export type Fault = {
+    kind: "provider_error";
+    at_call: number;
+    status: number;
+} | {
+    kind: "latency";
+    at_call: number;
+    ms: number;
+} | {
+    kind: "truncate";
+    at_call: number;
+} | {
+    kind: "tool_error";
+    at_tool_call: number;
+    message?: string;
+} | {
+    kind: "bad_data";
+    at_tool_call: number;
+    text: string;
+};
+/** spec/drills.md §1: the drill with defaults filled in, or an error message. */
+export declare function checkDrill(value: unknown): {
+    faults: Fault[];
+} | string;
+/** spec/drills.md §3. */
+export declare function drillReport(lines: readonly string[]): {
+    drill: false;
+    planned: never[];
+    injected: never[];
+    findings_after: never[];
+    recovered: boolean;
+    outcome: null;
+} | {
+    drill: true;
+    planned: Fault[];
+    injected: {
+        seq: number;
+        kind: string;
+    }[];
+    findings_after: string[];
+    recovered: boolean;
+    outcome: string | null;
+};

package/dist/drills/index.js

@@ -0,0 +1,101 @@
+// Drills (spec/drills.md): scheduled failures, checked, and what the agent did about them. Pure;
+// mirrors sdks/python/src/zanii_blackbox/drills.py; pinned by spec/vectors/drills.json.
+const MODEL_KINDS = new Set(["provider_error", "latency", "truncate"]);
+const TOOL_KINDS = new Set(["tool_error", "bad_data"]);
+const int = (v, min, max) => Number.isSafeInteger(v) && v >= min && v <= max;
+/** spec/drills.md §1: the drill with defaults filled in, or an error message. */
+export function checkDrill(value) {
+    const faults = value?.faults;
+    if (typeof value !== "object" || value === null || Array.isArray(value) || !Array.isArray(faults))
+        return "drill must be {faults: [...]}";
+    if (faults.length === 0 || faults.length > 20)
+        return "drill.faults must hold 1-20 faults";
+    const out = [];
+    for (const [i, raw] of faults.entries()) {
+        const f = raw;
+        const at = `drill.faults[${i}]`;
+        if (typeof f !== "object" || f === null)
+            return `${at} must be an object`;
+        if (MODEL_KINDS.has(f.kind)) {
+            if (!int(f.at_call, 1, 1_000_000))
+                return `${at}.at_call must be an integer of at least 1`;
+            if (f.kind === "provider_error") {
+                const status = f.status ?? 500;
+                if (!(status === 429 || int(status, 500, 599)))
+                    return `${at}.status must be 429 or 500-599`;
+                out.push({
+                    kind: "provider_error",
+                    at_call: f.at_call,
+                    status: status,
+                });
+            }
+            else if (f.kind === "latency") {
+                if (!int(f.ms, 1, 60_000))
+                    return `${at}.ms must be 1-60000`;
+                out.push({ kind: "latency", at_call: f.at_call, ms: f.ms });
+            }
+            else
+                out.push({ kind: "truncate", at_call: f.at_call });
+        }
+        else if (TOOL_KINDS.has(f.kind)) {
+            if (!int(f.at_tool_call, 1, 1_000_000))
+                return `${at}.at_tool_call must be an integer of at least 1`;
+            if (f.kind === "tool_error") {
+                if (f.message !== undefined && (typeof f.message !== "string" || f.message.length > 500))
+                    return `${at}.message must be at most 500 characters`;
+                out.push({
+                    kind: "tool_error",
+                    at_tool_call: f.at_tool_call,
+                    ...(f.message !== undefined ? { message: f.message } : {}),
+                });
+            }
+            else {
+                if (typeof f.text !== "string" || f.text.length > 2000)
+                    return `${at}.text must be a string of at most 2000 characters`;
+                out.push({ kind: "bad_data", at_tool_call: f.at_tool_call, text: f.text });
+            }
+        }
+        else
+            return `${at}.kind must be provider_error, latency, truncate, tool_error or bad_data`;
+    }
+    return { faults: out };
+}
+/** spec/drills.md §3. */
+export function drillReport(lines) {
+    const events = lines.map((l) => JSON.parse(l));
+    const drill = events[0]?.meta.drill?.faults;
+    if (events[0]?.kind !== "session.open" || !drill)
+        return {
+            drill: false,
+            planned: [],
+            injected: [],
+            findings_after: [],
+            recovered: false,
+            outcome: null,
+        };
+    const injected = events
+        .filter((e) => (e.kind === "llm.request" || e.kind === "tool.call") &&
+        typeof e.meta.injected === "object" &&
+        e.meta.injected !== null)
+        .map((e) => ({ seq: e.seq, kind: String(e.meta.injected.kind) }));
+    const first = injected[0]?.seq ?? Number.POSITIVE_INFINITY;
+    const lastInjected = Math.max(-1, ...events.filter((e) => e.meta.injected !== undefined).map((e) => e.seq));
+    const codes = [
+        ...new Set(events.filter((e) => e.kind === "finding" && e.seq > first).map((e) => String(e.meta.code))),
+    ].sort();
+    const recovered = events.some((e) => e.kind === "llm.response" &&
+        e.seq > lastInjected &&
+        e.meta.status === 200 &&
+        e.meta.injected === undefined &&
+        injected.length > 0);
+    const outcomes = events.filter((e) => e.kind === "outcome");
+    const outcome = outcomes.length ? String(outcomes.at(-1)?.meta.outcome) : null;
+    return {
+        drill: true,
+        planned: drill,
+        injected,
+        findings_after: codes,
+        recovered,
+        outcome,
+    };
+}

package/dist/duty/index.d.ts

@@ -0,0 +1,21 @@
+import { type LoadedPrices } from "../cost/index.ts";
+export interface DutyLimits {
+    max_minutes?: number;
+    max_llm_calls?: number;
+    max_context_pct?: number;
+}
+export interface DutyFinding {
+    code: "DUTY_LIMIT";
+    source: "duty";
+    severity: "warning";
+    ref: {
+        seq: number;
+        limit: "minutes" | "llm_calls" | "context_pct";
+        value: number;
+        max: number;
+    };
+}
+/** spec/duty.md §2: at most one DUTY_LIMIT per limit, where it was first crossed. */
+export declare function dutyFindings(lines: readonly string[], prices?: LoadedPrices, defaults?: DutyLimits): DutyFinding[];
+/** Checks a flight plan's `duty` (spec/duty.md §1): an error message, or undefined. */
+export declare function checkDuty(duty: unknown): string | undefined;

package/dist/duty/index.js

@@ -0,0 +1,68 @@
+// Duty-time limits (spec/duty.md): long sessions and full context windows, detected. Pure; mirrors
+// sdks/python/src/zanii_blackbox/duty.py; pinned by spec/vectors/duty.json.
+import { priceFor, promptTokens, sessionCost } from "../cost/index.js";
+const KEYS = ["max_minutes", "max_llm_calls", "max_context_pct"];
+/** spec/duty.md §1: the flight plan's limits win, limit by limit, over the server's defaults. */
+function limitsOf(open, defaults) {
+    const plan = open?.meta.flight_plan?.duty;
+    const out = { max_minutes: 0, max_llm_calls: 0, max_context_pct: 0 };
+    for (const k of KEYS) {
+        const v = plan?.[k] ?? defaults[k];
+        if (Number.isSafeInteger(v) && v > 0)
+            out[k] = v;
+    }
+    return out;
+}
+/** spec/duty.md §2: at most one DUTY_LIMIT per limit, where it was first crossed. */
+export function dutyFindings(lines, prices, defaults = {}) {
+    const events = lines.map((l) => JSON.parse(l));
+    const open = events[0]?.kind === "session.open" ? events[0] : undefined;
+    const limits = limitsOf(open, defaults);
+    const out = [];
+    const finding = (seq, limit, value, max) => out.push({
+        code: "DUTY_LIMIT",
+        source: "duty",
+        severity: "warning",
+        ref: { seq, limit, value, max },
+    });
+    if (limits.max_minutes && open) {
+        const start = Date.parse(open.ts);
+        const late = events.find((e) => Date.parse(e.ts) - start > limits.max_minutes * 60_000);
+        if (late)
+            finding(late.seq, "minutes", Math.floor((Date.parse(late.ts) - start) / 60_000), limits.max_minutes);
+    }
+    if (limits.max_llm_calls) {
+        const requests = events.filter((e) => e.kind === "llm.request");
+        const over = requests[limits.max_llm_calls];
+        if (over)
+            finding(over.seq, "llm_calls", limits.max_llm_calls + 1, limits.max_llm_calls);
+    }
+    if (limits.max_context_pct && prices) {
+        for (const c of sessionCost(lines, prices).calls) {
+            const window = c.model ? priceFor(c.model, prices.table)?.price.context_window : undefined;
+            if (!window)
+                continue;
+            const prompt = promptTokens(c.tokens);
+            const pct = Math.floor((prompt * 100) / window);
+            if (pct >= limits.max_context_pct) {
+                finding(c.seq, "context_pct", pct, limits.max_context_pct);
+                break;
+            }
+        }
+    }
+    return out;
+}
+/** Checks a flight plan's `duty` (spec/duty.md §1): an error message, or undefined. */
+export function checkDuty(duty) {
+    if (typeof duty !== "object" || duty === null || Array.isArray(duty))
+        return "flight_plan.duty must be an object";
+    for (const [k, v] of Object.entries(duty)) {
+        if (!KEYS.includes(k))
+            return `flight_plan.duty has an unknown field: ${k}`;
+        if (!Number.isSafeInteger(v) ||
+            v < 1 ||
+            (k === "max_context_pct" && v > 100))
+            return `flight_plan.duty.${k} must be a positive integer${k === "max_context_pct" ? " of at most 100" : ""}`;
+    }
+    return undefined;
+}