@zanii/blackbox 0.1.0 → 0.3.0

package/dist/data/index.js

@@ -0,0 +1,762 @@
+// Data handling (spec/data.md): what data a session touched, where it went, whether the systems it
+// touched confirm it. Pure functions, pinned with the Python SDK by spec/vectors/data.json.
+// Mirrors sdks/python/src/zanii_blackbox/data.py.
+import { createHmac, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import { canonicalBytes, didFromPublicKey, publicKeyFromDid } from "@zanii/core";
+/** spec/data/identifiers-v1.json: always on. */
+export const CORE_IDENTIFIERS = [
+    {
+        id: "email",
+        title: "E-mail address",
+        pattern: "(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\\.[A-Za-z0-9-]{1,63}){0,8}\\.[A-Za-z]{2,63}(?![A-Za-z0-9-])",
+        normalize: "lower",
+        personal: true,
+    },
+    {
+        id: "card",
+        title: "Payment card number",
+        pattern: "(?<![0-9])(?:4[0-9]{3}|5[1-5][0-9]{2}|2[2-7][0-9]{2}|3[47][0-9]{2}|6(?:011|5[0-9]{2}))(?:[ -]?[0-9]){9,15}(?![0-9])",
+        normalize: "digits",
+        check: "luhn",
+        personal: true,
+    },
+    {
+        id: "iban",
+        title: "IBAN",
+        pattern: "(?<![A-Za-z0-9])[A-Z]{2}[0-9]{2}(?: ?[A-Z0-9]){11,30}(?![A-Za-z0-9])",
+        normalize: "upper",
+        personal: true,
+    },
+    {
+        id: "phone_e164",
+        title: "Phone number (international format)",
+        pattern: "(?<![0-9+])\\+[1-9][0-9]{7,14}(?![0-9])",
+        normalize: "digits",
+        personal: true,
+    },
+];
+/** spec/data/core-v1.json: evidence defaults for common writes (§5). */
+export const CORE_EVIDENCE = [
+    { tool: "send_email", field: "message_id" },
+    { tool: "issue_refund", field: "refund_id" },
+    { tool: "create_ticket", field: "ticket_id" },
+    { tool: "create_payment", field: "payment_id" },
+    { tool: "transfer", field: "transaction_id" },
+];
+/**
+ * §6: the canary values as one identifier, matched literally. Longer values first, so a value that
+ * contains another wins. ASCII punctuation is escaped the same way both languages read it.
+ */
+export function canaryIdentifier(values) {
+    const alts = [...new Set(values.filter((v) => v !== ""))]
+        .sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0))
+        .map((v) => v.replace(/[!-/:-@[-`{-~]/g, (c) => `\\${c}`));
+    return {
+        id: "canary",
+        title: "Canary value",
+        pattern: alts.length > 0 ? `(?:${alts.join("|")})` : "(?!)",
+        normalize: "exact",
+        personal: false,
+    };
+}
+const MAX_FOUND = 200;
+const compiled = new Map();
+const regex = (pattern) => {
+    let r = compiled.get(pattern);
+    if (!r) {
+        r = new RegExp(pattern, "g");
+        compiled.set(pattern, r);
+    }
+    r.lastIndex = 0;
+    return r;
+};
+export function normalizeValue(value, how) {
+    if (how === "digits")
+        return value.replace(/[^0-9]/g, "");
+    if (how === "lower")
+        return value.replace(/\s/g, "").toLowerCase();
+    if (how === "upper")
+        return value.replace(/\s/g, "").toUpperCase();
+    return value;
+}
+const keepLast = (v, n) => (n !== undefined && v.length > n ? v.slice(-n) : v);
+export function luhn(digits) {
+    if (!/^[0-9]{2,}$/.test(digits))
+        return false;
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let d = digits.charCodeAt(digits.length - 1 - i) - 48;
+        if (i % 2 === 1) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return sum % 10 === 0;
+}
+/** §1: each distinct (id, normalized value) in text order, at most 200. Earlier identifiers win a span. */
+export function dataScan(text, identifiers) {
+    const taken = [];
+    const hits = [];
+    for (const ident of identifiers) {
+        for (const m of text.matchAll(regex(ident.pattern))) {
+            const start = m.index ?? 0;
+            const end = start + m[0].length;
+            if (m[0].length === 0 || taken.some(([a, b]) => start < b && end > a))
+                continue;
+            const value = keepLast(normalizeValue(m[0], ident.normalize), ident.keep_last);
+            if (value === "" || (ident.check === "luhn" && !luhn(value)))
+                continue;
+            taken.push([start, end]);
+            hits.push({ at: start, id: ident.id, value });
+        }
+    }
+    hits.sort((a, b) => a.at - b.at || (a.id < b.id ? -1 : 1));
+    const out = [];
+    const seen = new Set();
+    for (const h of hits) {
+        const k = `${h.id}\n${h.value}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push({ id: h.id, value: h.value });
+        if (out.length === MAX_FOUND)
+            break;
+    }
+    return out;
+}
+/** Every match counted (not only distinct ones), for `data.classes`. */
+export function dataClasses(text, identifiers) {
+    const taken = [];
+    const counts = {};
+    for (const ident of identifiers)
+        for (const m of text.matchAll(regex(ident.pattern))) {
+            const start = m.index ?? 0;
+            const end = start + m[0].length;
+            if (m[0].length === 0 || taken.some(([a, b]) => start < b && end > a))
+                continue;
+            const value = keepLast(normalizeValue(m[0], ident.normalize), ident.keep_last);
+            if (value === "" || (ident.check === "luhn" && !luhn(value)))
+                continue;
+            taken.push([start, end]);
+            counts[ident.id] = (counts[ident.id] ?? 0) + 1;
+        }
+    return Object.fromEntries(Object.entries(counts).sort(([a], [b]) => (a < b ? -1 : 1)));
+}
+// ---------------------------------------------------------------- §2 fingerprints
+const hmac = (key, data) => createHmac("sha256", key).update(data).digest();
+/** §2: the tenant's fingerprint of one identifier value. */
+export function dataFingerprint(key, tenant, id, value) {
+    const m = hmac(key, `${id}\n${value}`).toString("hex");
+    const tk = hmac(key, `blackbox-lineage-tenant\n${tenant}`);
+    return `fp:${hmac(tk, m).toString("hex").slice(0, 32)}`;
+}
+/** §2: the `data` meta of a body, or undefined when it holds no identifier. */
+export function dataMeta(text, identifiers, key, tenant) {
+    const found = dataScan(text, identifiers);
+    if (found.length === 0)
+        return undefined;
+    return {
+        classes: dataClasses(text, identifiers),
+        fps: found.map((f) => ({ id: f.id, fp: dataFingerprint(key, tenant, f.id, f.value) })),
+    };
+}
+const parse = (lines) => lines.filter((l) => l.trim() !== "").map((l) => JSON.parse(l));
+const fpsOf = (e) => {
+    const d = e.meta?.data;
+    return Array.isArray(d?.fps)
+        ? d.fps.filter((x) => x && typeof x.fp === "string" && typeof x.id === "string")
+        : [];
+};
+/** Where an event sends data, or undefined if it doesn't. */
+function sendOf(e, tools) {
+    const m = e.meta ?? {};
+    if (e.kind === "llm.request")
+        return {
+            to: `model:${String(m.provider ?? "unknown")}`,
+            ...(typeof m.region === "string" ? { region: m.region } : {}),
+        };
+    if (e.kind === "tool.call") {
+        if (m.via === "broker")
+            return { to: `api:${String(m.tool ?? "unknown")}` };
+        const name = toolName(m);
+        if (name)
+            tools.set(e.seq, name);
+        return name ? { to: `tool:${name}` } : undefined;
+    }
+    if (e.kind === "sdk.event" && m.type === "tool.call" && typeof m.name === "string")
+        return { to: `tool:${m.name}` };
+    return undefined;
+}
+const toolName = (m) => typeof m.tool === "string"
+    ? typeof m.server === "string"
+        ? `${m.server}__${m.tool}`
+        : m.tool
+    : undefined;
+/** Where an event brings data in from, or undefined. */
+function readOf(e, tools) {
+    const m = e.meta ?? {};
+    if (e.kind === "tool.result") {
+        if (m.via === "broker")
+            return `api:${String(m.tool ?? "unknown")}`;
+        const name = typeof m.call_seq === "number" ? tools.get(m.call_seq) : undefined;
+        return name ? `tool:${name}` : typeof m.server === "string" ? `tool:${m.server}` : "tool";
+    }
+    if (e.kind === "sdk.event" && m.type === "tool.result" && typeof m.name === "string")
+        return `tool:${m.name}`;
+    if (e.kind === "llm.response" || e.kind === "llm.chunk")
+        return `model:${String(m.provider ?? "unknown")}`;
+    return undefined;
+}
+/** §3: where each subject's data came from and went in one session. */
+export function lineage(lines) {
+    const tools = new Map();
+    const subjects = new Map();
+    for (const e of parse(lines)) {
+        const send = sendOf(e, tools);
+        const read = send ? undefined : readOf(e, tools);
+        for (const { id, fp } of fpsOf(e)) {
+            let s = subjects.get(fp);
+            if (!s) {
+                s = { fp, id, first: { seq: e.seq, kind: e.kind, from: read ?? "input" }, sent: [] };
+                subjects.set(fp, s);
+            }
+            if (send && !s.sent.some((x) => x.to === send.to))
+                s.sent.push({ seq: e.seq, ...send });
+        }
+    }
+    const list = [...subjects.values()].sort((a, b) => a.first.seq - b.first.seq);
+    const dest = new Map();
+    for (const s of list)
+        for (const x of s.sent) {
+            let d = dest.get(x.to);
+            if (!d) {
+                d = { to: x.to, ...(x.region ? { region: x.region } : {}), classes: {}, subjects: 0 };
+                dest.set(x.to, d);
+            }
+            d.classes[s.id] = (d.classes[s.id] ?? 0) + 1;
+            d.subjects++;
+        }
+    const destinations = [...dest.values()].sort((a, b) => (a.to < b.to ? -1 : 1));
+    for (const d of destinations)
+        d.classes = Object.fromEntries(Object.entries(d.classes).sort(([a], [b]) => (a < b ? -1 : 1)));
+    return { subjects: list, destinations };
+}
+/**
+ * §3a: many sessions' lineage as one map: where data is read from (nodes on the left) and sent to,
+ * with how many subjects and sessions each flow carried. With `dataRegion`, a flow to a model in
+ * another region is flagged `outside_region`, one to a model of no known region `region_unknown`.
+ */
+export function dataTopology(sessions, dataRegion = null) {
+    const edges = new Map();
+    const nodes = new Map();
+    const node = (id, sid, region) => {
+        const n = nodes.get(id) ?? { ses: new Set() };
+        if (region !== undefined)
+            n.region = region;
+        n.ses.add(sid);
+        nodes.set(id, n);
+    };
+    for (const { session_id: sid, lines } of sessions)
+        for (const s of lineage(lines).subjects) {
+            node(s.first.from, sid);
+            for (const x of s.sent) {
+                node(x.to, sid, x.region);
+                const key = `${s.first.from}\n${x.to}`;
+                const e = edges.get(key) ?? {
+                    from: s.first.from,
+                    to: x.to,
+                    classes: new Map(),
+                    fps: new Set(),
+                    ses: new Set(),
+                };
+                if (x.region !== undefined)
+                    e.region = x.region;
+                const c = e.classes.get(s.id) ?? new Set();
+                c.add(`${sid}\n${s.fp}`);
+                e.classes.set(s.id, c);
+                e.fps.add(s.fp);
+                e.ses.add(sid);
+                edges.set(key, e);
+            }
+        }
+    const byId = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return {
+        nodes: [...nodes.entries()]
+            .sort(([a], [b]) => byId(a, b))
+            .map(([id, n]) => ({
+            id,
+            kind: id.includes(":") ? id.split(":")[0] : id,
+            ...(n.region !== undefined ? { region: n.region } : {}),
+            sessions: n.ses.size,
+        })),
+        edges: [...edges.values()]
+            .sort((a, b) => byId(a.from, b.from) || byId(a.to, b.to))
+            .map((e) => {
+            const flags = [];
+            if (dataRegion && e.to.startsWith("model:"))
+                if (e.region === undefined)
+                    flags.push("region_unknown");
+                else if (e.region !== dataRegion)
+                    flags.push("outside_region");
+            return {
+                from: e.from,
+                to: e.to,
+                ...(e.region !== undefined ? { region: e.region } : {}),
+                classes: Object.fromEntries([...e.classes.entries()].sort(([a], [b]) => byId(a, b)).map(([k, v]) => [k, v.size])),
+                subjects: e.fps.size,
+                sessions: e.ses.size,
+                flags,
+            };
+        }),
+    };
+}
+const allows = (pattern, send) => {
+    if (pattern.startsWith("region:"))
+        return send.region === pattern.slice(7);
+    return pattern.endsWith("*") ? send.to.startsWith(pattern.slice(0, -1)) : send.to === pattern;
+};
+/** §4, §6, §7, §9: findings over a session's events. */
+export function dataFindings(lines, rules, dataRegion) {
+    const events = parse(lines);
+    const personal = new Set(rules.identifiers.filter((i) => i.personal).map((i) => i.id));
+    const out = [];
+    const once = new Set();
+    const add = (f, key) => {
+        if (once.has(key))
+            return;
+        once.add(key);
+        out.push(f);
+    };
+    const tools = new Map();
+    const withdrawn = new Set();
+    for (const e of events) {
+        const m = e.meta ?? {};
+        if (e.kind === "sdk.event" && m.type === "consent" && m.name === "withdrawn")
+            for (const { fp } of fpsOf(e))
+                withdrawn.add(fp);
+        if (e.kind === "sdk.event" && m.type === "egress_check" && m.name === "open")
+            add({ code: "EGRESS_OPEN", severity: "warning", ref: { seq: e.seq } }, `egress`);
+        const w = m.witness;
+        if (w && w.ok === false)
+            add({
+                code: "TOOL_WITNESS_INVALID",
+                severity: "warning",
+                ref: { seq: e.seq, did: String(w.did ?? "") },
+            }, `witness ${e.seq}`);
+        const send = sendOf(e, tools);
+        if (!send)
+            continue;
+        for (const { id, fp } of fpsOf(e)) {
+            const ref = { seq: e.seq, fp, id, to: send.to };
+            if (id === "canary")
+                add({ code: "DATA_CANARY_TRIPPED", severity: "warning", ref }, `canary ${fp} ${send.to}`);
+            if (withdrawn.has(fp))
+                add({ code: "CONSENT_WITHDRAWN_USE", severity: "warning", ref }, `consent ${fp} ${send.to}`);
+            if (rules.residency && dataRegion && personal.has(id) && send.to.startsWith("model:")) {
+                if (send.region === undefined)
+                    add({ code: "DATA_REGION_UNKNOWN", severity: "advisory", ref }, `unknown ${fp} ${send.to}`);
+                else if (send.region !== dataRegion)
+                    add({
+                        code: "DATA_LEFT_REGION",
+                        severity: "warning",
+                        ref: { ...ref, region: send.region },
+                    }, `left ${fp} ${send.to}`);
+            }
+            for (const r of rules.restricted)
+                if (r.identifiers.includes(id) && !r.allow.some((p) => allows(p, send)))
+                    add({ code: "DATA_TO_UNAPPROVED_DESTINATION", severity: "warning", ref }, `restricted ${fp} ${send.to}`);
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------- §5 evidence
+/** Every object inside a value, including JSON written inside strings (as MCP text content). */
+function* objects(value, depth = 0) {
+    if (depth > 20)
+        return;
+    if (typeof value === "string") {
+        const t = value.trim();
+        if ((t.startsWith("{") || t.startsWith("[")) && t.length <= 1_000_000)
+            try {
+                yield* objects(JSON.parse(t), depth + 1);
+            }
+            catch {
+                /* not JSON */
+            }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const v of value)
+            yield* objects(v, depth + 1);
+        return;
+    }
+    if (value && typeof value === "object") {
+        yield value;
+        for (const v of Object.values(value))
+            yield* objects(v, depth + 1);
+    }
+}
+export const hasEvidence = (value, field) => {
+    for (const o of objects(value)) {
+        const v = o[field];
+        if ((typeof v === "string" && v.trim() !== "") || (typeof v === "number" && Number.isFinite(v)))
+            return true;
+    }
+    return false;
+};
+const ruleFor = (rules, names) => rules.find((r) => names.includes(r.tool));
+/** §5: successful results of state-changing tools with no evidence of their own. */
+export function unevidenced(lines, body, rules) {
+    const out = [];
+    const calls = new Map();
+    const json = (e) => {
+        const b = e.body_hash ? body(e.body_hash) : undefined;
+        if (!b)
+            return undefined;
+        try {
+            return JSON.parse(Buffer.from(b).toString("utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    for (const e of parse(lines)) {
+        const m = e.meta ?? {};
+        if (e.kind === "tool.call" && typeof m.tool === "string")
+            calls.set(e.seq, [
+                m.tool,
+                ...(typeof m.server === "string" ? [`${m.server}__${m.tool}`] : []),
+            ]);
+        if (e.kind === "tool.result" && typeof m.call_seq === "number") {
+            const names = calls.get(m.call_seq);
+            const rule = names ? ruleFor(rules, names) : undefined;
+            if (!rule)
+                continue;
+            const r = json(e);
+            if (r === undefined || r.error !== undefined || r.result?.isError === true)
+                continue;
+            if (!hasEvidence(r.result ?? r, rule.field))
+                out.push({
+                    code: "UNEVIDENCED_SIDE_EFFECT",
+                    severity: "caution",
+                    ref: { seq: e.seq, tool: rule.tool, field: rule.field },
+                });
+        }
+        if (e.kind === "sdk.event" && m.type === "tool.result" && typeof m.name === "string") {
+            const rule = ruleFor(rules, [m.name]);
+            if (!rule)
+                continue;
+            const d = json(e);
+            if (d === undefined || d.ok === false)
+                continue;
+            if (!hasEvidence(d, rule.field))
+                out.push({
+                    code: "UNEVIDENCED_SIDE_EFFECT",
+                    severity: "caution",
+                    ref: { seq: e.seq, tool: rule.tool, field: rule.field },
+                });
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------- §9 tool witness
+const PKCS8 = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI = Buffer.from("302a300506032b6570032100", "hex");
+/** §9: a tool signs what it returns, so the result is the tool's word, not the agent's. */
+export function toolWitness(keypair) {
+    const key = createPrivateKey({
+        key: Buffer.concat([PKCS8, Buffer.from(keypair.privateKey).subarray(0, 32)]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const raw = createPublicKey(key).export({ format: "der", type: "spki" }).subarray(-32);
+    const did = keypair.did ?? didFromPublicKey(new Uint8Array(raw));
+    return {
+        did,
+        sign(result) {
+            const sig = sign(null, Buffer.from(canonicalBytes(result)), key);
+            return { result, witness: { did, sig: sig.toString("base64url") } };
+        },
+    };
+}
+/** §9: does `witness` sign `result`? */
+export function verifyToolWitness(result, witness) {
+    try {
+        if (typeof witness.did !== "string" || typeof witness.sig !== "string")
+            return false;
+        const raw = publicKeyFromDid(witness.did);
+        if (!raw)
+            return false;
+        const pub = createPublicKey({
+            key: Buffer.concat([SPKI, Buffer.from(raw)]),
+            format: "der",
+            type: "spki",
+        });
+        return verify(null, Buffer.from(canonicalBytes(result)), pub, Buffer.from(witness.sig, "base64url"));
+    }
+    catch {
+        return false;
+    }
+}
+/** §9: the witness an MCP result or an SDK tool.result body carries, checked; undefined if none. */
+export function witnessOf(bodyJson) {
+    if (!bodyJson || typeof bodyJson !== "object")
+        return undefined;
+    const b = bodyJson;
+    // An SDK tool.result event: {result, witness}
+    if (b.witness && typeof b.witness === "object" && "result" in b) {
+        const w = b.witness;
+        return { did: String(w.did ?? ""), ok: verifyToolWitness(b.result, w) };
+    }
+    // An MCP JSON-RPC answer: result._meta["blackbox/witness"], signed without that key
+    const r = b.result;
+    const meta = r?._meta;
+    const w = meta?.["blackbox/witness"];
+    if (!r || !w)
+        return undefined;
+    const { "blackbox/witness": _, ...rest } = meta;
+    const unsigned = { ...r, _meta: rest };
+    if (Object.keys(rest).length === 0)
+        delete unsigned._meta;
+    return { did: String(w.did ?? ""), ok: verifyToolWitness(unsigned, w) };
+}
+const COLUMN = (v) => typeof v === "string" && v.length >= 1 && v.length <= 200;
+/** §10: why a connector is invalid, or undefined. */
+export function checkAuditConnector(value) {
+    const c = value;
+    if (typeof c !== "object" || c === null || Array.isArray(c))
+        return "a connector must be an object";
+    if (c.v !== 1)
+        return "v must be 1";
+    if (typeof c.id !== "string" || !/^[a-z0-9_-]{1,64}$/.test(c.id))
+        return "id must be 1-64 of a-z 0-9 _ -";
+    if (c.format !== "csv" && c.format !== "jsonl")
+        return "format must be csv or jsonl";
+    const f = c.fields;
+    if (typeof f !== "object" || f === null || !COLUMN(f.at) || !COLUMN(f.action))
+        return "fields needs at and action";
+    for (const k of Object.keys(f))
+        if (!["at", "action", "object", "evidence", "amount", "actor"].includes(k) || !COLUMN(f[k]))
+            return `fields.${k} must be a column name (at, action, object, evidence, amount, actor)`;
+    const a = c.actions;
+    if (typeof a !== "object" || a === null || Array.isArray(a) || Object.keys(a).length === 0)
+        return "actions must map at least one tool to an action";
+    if (!Object.values(a).every(COLUMN))
+        return "each action must be 1-200 characters";
+    const g = c.arguments;
+    if (g !== undefined &&
+        (typeof g !== "object" ||
+            g === null ||
+            !Object.entries(g).every(([k, v]) => (k === "object" || k === "amount") && COLUMN(v))))
+        return "arguments may name object and amount";
+    const w = c.window_seconds;
+    if (w !== undefined && (!Number.isInteger(w) || w < 1 || w > 86_400))
+        return "window_seconds must be 1-86400";
+    return undefined;
+}
+/** RFC 4180: a header row, then rows; quoted fields may hold commas, quotes ("") and newlines. */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let quoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (quoted) {
+            if (c === '"' && text[i + 1] === '"') {
+                field += '"';
+                i++;
+            }
+            else if (c === '"')
+                quoted = false;
+            else
+                field += c;
+        }
+        else if (c === '"' && field === "")
+            quoted = true;
+        else if (c === ",") {
+            row.push(field);
+            field = "";
+        }
+        else if (c === "\n" || c === "\r") {
+            if (c === "\r" && text[i + 1] === "\n")
+                i++;
+            row.push(field);
+            field = "";
+            if (row.some((f) => f !== ""))
+                rows.push(row);
+            row = [];
+        }
+        else
+            field += c;
+    }
+    row.push(field);
+    if (row.some((f) => f !== ""))
+        rows.push(row);
+    return rows;
+}
+const timeOf = (v) => {
+    if (typeof v === "number" && Number.isFinite(v))
+        return Math.round(v * 1000);
+    if (typeof v !== "string" || v.trim() === "")
+        return undefined;
+    const t0 = v.trim();
+    if (/^[0-9]{9,11}(\.[0-9]+)?$/.test(t0))
+        return Math.round(Number(t0) * 1000);
+    // ISO-8601 with a zone only: without one, JavaScript reads local time and Python doesn't.
+    if (!/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\.[0-9]{1,6})?)?(Z|[+-][0-9]{2}:[0-9]{2})$/.test(t0))
+        return undefined;
+    const t = Date.parse(t0);
+    return Number.isNaN(t) ? undefined : t;
+};
+/** §10: the rows of an audit-log export, in file order; rows without a time or action are skipped. */
+export function parseAuditLog(text, connector) {
+    let records;
+    if (connector.format === "csv") {
+        const [head, ...rest] = parseCsv(text);
+        records = (rest ?? []).map((r) => Object.fromEntries((head ?? []).map((h, i) => [h.trim(), r[i] ?? ""])));
+    }
+    else
+        records = text
+            .split(/\r?\n/)
+            .filter((l) => l.trim() !== "")
+            .flatMap((l) => {
+            try {
+                const o = JSON.parse(l);
+                return o && typeof o === "object" && !Array.isArray(o)
+                    ? [o]
+                    : [];
+            }
+            catch {
+                return [];
+            }
+        });
+    const f = connector.fields;
+    const str = (v) => (v === undefined || v === null || v === "" ? undefined : String(v));
+    const out = [];
+    records.forEach((r, i) => {
+        const at = timeOf(r[f.at]);
+        const action = str(r[f.action]);
+        if (at === undefined || action === undefined)
+            return;
+        const row = { row: i + 1, at, action };
+        for (const k of ["object", "evidence", "amount", "actor"]) {
+            const col = f[k];
+            const v = col ? str(r[col]) : undefined;
+            if (v !== undefined)
+                row[k] = v;
+        }
+        out.push(row);
+    });
+    return out;
+}
+/** §10: the session's successful mapped tool calls against the system's own log. */
+export function reconcileSystem(lines, body, rows, connector, evidence) {
+    const events = parse(lines);
+    const json = (e) => {
+        const b = e.body_hash ? body(e.body_hash) : undefined;
+        if (!b)
+            return undefined;
+        try {
+            return JSON.parse(Buffer.from(b).toString("utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const window = (connector.window_seconds ?? 300) * 1000;
+    const callTools = new Map();
+    const calls = [];
+    const first = events.find((e) => e.kind === "session.open");
+    const ts = (e) => Date.parse(String(e.ts ?? ""));
+    const fieldValue = (v, field) => {
+        if (!field)
+            return undefined;
+        for (const o of objects(v)) {
+            const x = o[field];
+            if ((typeof x === "string" && x !== "") || typeof x === "number")
+                return String(x);
+        }
+        return undefined;
+    };
+    for (const e of events) {
+        const m = e.meta ?? {};
+        const sdkCall = e.kind === "sdk.event" && m.type === "tool.call" && typeof m.name === "string";
+        if ((e.kind === "tool.call" && typeof m.tool === "string") || sdkCall) {
+            const name = String(sdkCall ? m.name : m.tool);
+            const names = [name, ...(typeof m.server === "string" ? [`${m.server}__${name}`] : [])];
+            const req = json(e);
+            callTools.set(e.seq, {
+                name,
+                names,
+                at: ts(e),
+                args: sdkCall ? req : req?.params?.arguments,
+            });
+        }
+        const sdkResult = e.kind === "sdk.event" && m.type === "tool.result" && typeof m.name === "string";
+        if ((e.kind === "tool.result" && typeof m.call_seq === "number") || sdkResult) {
+            const call = sdkResult
+                ? [...callTools.entries()].reverse().find(([, c]) => c.name === m.name)
+                : [m.call_seq, callTools.get(m.call_seq)];
+            const c = call?.[1];
+            if (!c)
+                continue;
+            const tool = c.names.find((n) => connector.actions[n] !== undefined);
+            if (!tool)
+                continue;
+            const r = json(e);
+            if (r === undefined || r.error !== undefined || r.ok === false || r.result?.isError === true)
+                continue;
+            const rule = evidence.find((x) => c.names.includes(x.tool));
+            const object = fieldValue(c.args, connector.arguments?.object);
+            const amount = fieldValue(c.args, connector.arguments?.amount);
+            const proof = rule ? fieldValue(r, rule.field) : undefined;
+            calls.push({
+                seq: e.seq,
+                tool,
+                at: c.at,
+                ...(object !== undefined ? { object } : {}),
+                ...(proof !== undefined ? { evidence: proof } : {}),
+                ...(amount !== undefined ? { amount } : {}),
+            });
+        }
+    }
+    const used = new Set();
+    const matched = [];
+    const findings = [];
+    for (const c of calls) {
+        const action = connector.actions[c.tool];
+        let hit = c.evidence
+            ? rows.find((r) => !used.has(r.row) && r.evidence !== undefined && r.evidence === c.evidence)
+            : undefined;
+        let by = "evidence";
+        if (!hit) {
+            by = "action";
+            hit = rows.find((r) => !used.has(r.row) &&
+                r.action === action &&
+                (c.object === undefined || r.object === undefined || r.object === c.object) &&
+                Math.abs(r.at - c.at) <= window);
+        }
+        if (!hit) {
+            findings.push({ code: "AGENT_ACTION_NOT_IN_SYSTEM", ref: { seq: c.seq } });
+            continue;
+        }
+        used.add(hit.row);
+        matched.push({ seq: c.seq, row: hit.row, by });
+        if (by === "evidence" &&
+            c.amount !== undefined &&
+            hit.amount !== undefined &&
+            c.amount !== hit.amount)
+            findings.push({ code: "SYSTEM_RECORD_MISMATCH", ref: { seq: c.seq, row: hit.row } });
+    }
+    const start = first ? ts(first) : Number.NEGATIVE_INFINITY;
+    const lastEv = events.at(-1);
+    const end = lastEv ? ts(lastEv) : Number.POSITIVE_INFINITY;
+    const mapped = new Set(Object.values(connector.actions));
+    for (const r of rows)
+        if (!used.has(r.row) && mapped.has(r.action) && r.at >= start - window && r.at <= end + window)
+            findings.push({ code: "SYSTEM_CHANGE_NOT_IN_RECORD", ref: { row: r.row } });
+    return { connector: connector.id, calls: calls.length, rows: rows.length, matched, findings };
+}