@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.4

package/dist/doctor/doctor.js

@@ -0,0 +1,385 @@
+import { Interface } from "ethers";
+import { relative } from "node:path";
+import { loadBundle } from "../bundle/load.js";
+import { runtimeIdentity } from "../util/bytecode.js";
+import { loadGenesisEvidence, semanticVerdicts } from "./semantic.js";
+import { loadLoopDEvidence, loopDVerdicts } from "./loop-d.js";
+import { readJson, repoRoot, writeJson } from "../util/fs.js";
+import { log } from "../util/log.js";
+import { READOUTS, WIRING_CHECKS } from "./checks.js";
+import { buildProbePlan, executeProbeLive } from "./probe.js";
+const LAYERS = {
+    "1": "chain and code: the address holds code on the expected chain",
+    "2": "interfaces: ERC-165 declarations against the interfaces the contract is built from",
+    "3": "version match: runtime code (metadata stripped, library/immutable slots masked) equals the locked build",
+    "4": "configuration and permissions: dependency addresses and authority slots match the world",
+    "5": "semantic validation: success, rejection, signature, proof and recovery cases, from the genesis evidence (foga genesis run; pass it with --genesis)",
+    D: "Loop D: an unscripted run judged by its records — every operation under an allowed decision, refusals that broadcast nothing, the budget books, the operator key's transactions, the demander's cases, recovery, the entrances (foga demo --loop-d; pass the evidence with --loop-d)",
+};
+function worst(a, b) {
+    const order = ["Fail", "Unknown", "Pass", "NotTested", "NotApplicable"];
+    return order.indexOf(a) <= order.indexOf(b) ? a : b;
+}
+function fmt(v) {
+    if (typeof v === "bigint")
+        return v.toString();
+    if (Array.isArray(v))
+        return `[${v.map(fmt).join(", ")}]`;
+    return String(v);
+}
+function same(expected, actual) {
+    return fmt(expected).toLowerCase() === fmt(actual).toLowerCase();
+}
+function decodeBool(hex) {
+    if (!hex || hex === "0x" || hex.length < 66)
+        return false;
+    return BigInt(hex.slice(0, 66)) === 1n;
+}
+export function loadWorldFile(path) {
+    const world = readJson(path);
+    if (world.schema !== "foga.world/1")
+        throw new Error(`${path} is not a world file (schema ${String(world.schema)}); use \`foga world attach\` for a config, or --attach`);
+    return world;
+}
+export function evaluate(world, bundle, plan, probe, mode, genesis, loopD) {
+    const results = [];
+    const readouts = [];
+    const perContract = {};
+    const expectations = world.wiring?.expectations ?? {};
+    const r = (key) => probe.results[key];
+    const hexOf = (key) => {
+        const o = r(key);
+        return o && "result" in o ? o.result : undefined;
+    };
+    const chainHex = hexOf("chainId");
+    const chainId = chainHex ? Number(BigInt(chainHex)) : null;
+    const blockHex = hexOf("blockNumber");
+    const blockNumber = blockHex ? Number(BigInt(blockHex)) : null;
+    results.push({ layer: 1, subject: "world", check: "chainId", verdict: chainId === null ? "Unknown" : chainId === world.chainId ? "Pass" : "Fail", expected: String(world.chainId), actual: chainId === null ? "(no answer)" : String(chainId) });
+    if (world.bundleHash && world.bundleHash !== bundle.hash) {
+        results.push({ layer: 3, subject: "world", check: "bundleHash", verdict: "Unknown", expected: world.bundleHash, actual: bundle.hash, detail: "world was deployed from a different bundle build; layer-3 verdicts compare against the current bundle" });
+    }
+    if (plan.bundleHash !== bundle.hash) {
+        results.push({ layer: 3, subject: "probe", check: "bundleHash", verdict: "Unknown", expected: bundle.hash, actual: plan.bundleHash, detail: "probe plan was built from another bundle" });
+    }
+    const ifacesByRepo = new Map();
+    for (const c of Object.values(bundle.contracts)) {
+        if (c.kind === "interface" && c.interfaceId) {
+            const l = ifacesByRepo.get(c.repo) ?? [];
+            l.push(c);
+            ifacesByRepo.set(c.repo, l);
+        }
+    }
+    for (const [id, entry] of Object.entries(world.contracts)) {
+        const address = entry.address;
+        const art = entry.bundleKey ? bundle.contracts[entry.bundleKey] : undefined;
+        const codeOutcome = r(`code:${id}`);
+        let l1;
+        let code = "0x";
+        if (!codeOutcome)
+            l1 = "NotTested";
+        else if ("error" in codeOutcome)
+            l1 = "Unknown";
+        else {
+            code = codeOutcome.result;
+            l1 = code !== "0x" ? "Pass" : "Fail";
+        }
+        results.push({ layer: 1, subject: id, check: "code", verdict: l1, actual: l1 === "Pass" ? `${(code.length - 2) / 2} bytes` : codeOutcome && "error" in codeOutcome ? codeOutcome.error : "no code at address" });
+        if (l1 !== "Pass") {
+            perContract[id] = { address, layer1: l1, layer2: "NotTested", layer3: "NotTested", layer4: "NotTested" };
+            continue;
+        }
+        let l2 = "NotApplicable";
+        if (!art && id === "identity8004" && r(`iface:${id}:erc165`)) {
+            const erc165 = decodeBool(hexOf(`iface:${id}:erc165`));
+            const erc721 = decodeBool(hexOf(`iface:${id}:ERC721`));
+            l2 = erc165 && erc721 ? "Pass" : "Fail";
+            results.push({ layer: 2, subject: id, check: "supportsInterface(0x01ffc9a7)", verdict: erc165 ? "Pass" : "Fail" });
+            results.push({ layer: 2, subject: id, check: "supportsInterface(ERC-721 0x80ac58cd)", verdict: erc721 ? "Pass" : "Fail", detail: "the ERC-8004 Identity Registry is an ERC-721 registry; FOGA does not build it, so this is the only interface check available" });
+        }
+        else if (!art) {
+            results.push({ layer: 2, subject: id, check: "supportsInterface", verdict: "Unknown", detail: "no bundle key for this address" });
+            l2 = "Unknown";
+        }
+        else if (!r(`iface:${id}:erc165`)) {
+            results.push({ layer: 2, subject: id, check: "supportsInterface", verdict: "NotApplicable", detail: "contract does not expose ERC-165" });
+        }
+        else {
+            const erc165 = decodeBool(hexOf(`iface:${id}:erc165`));
+            l2 = erc165 ? "Pass" : "Fail";
+            results.push({ layer: 2, subject: id, check: "supportsInterface(0x01ffc9a7)", verdict: l2 });
+            const repoIfaces = ifacesByRepo.get(art.repo) ?? [];
+            const expected = new Set(art.baseContracts.filter((b) => repoIfaces.some((i) => i.name === b)));
+            const declared = [];
+            for (const iface of repoIfaces) {
+                const ok = decodeBool(hexOf(`iface:${id}:${iface.name}`));
+                if (ok)
+                    declared.push(`${iface.name}=${iface.interfaceId}`);
+                if (expected.has(iface.name)) {
+                    const published = bundle.interfaceIds[art.repo]?.[iface.name]?.upstream != null;
+                    const v = ok ? "Pass" : published ? "Fail" : "Unknown";
+                    l2 = worst(l2, v);
+                    results.push({
+                        layer: 2,
+                        subject: id,
+                        check: `supportsInterface(${iface.name})`,
+                        verdict: v,
+                        expected: iface.interfaceId ?? undefined,
+                        detail: ok
+                            ? undefined
+                            : published
+                                ? entry.deployedRevision
+                                    ? `known: deployed from ${entry.deployedRevision}; the interface id in the locked source may differ from the one that revision declares`
+                                    : "built from a published interface but does not declare it"
+                                : "built from this interface but does not declare it; upstream publishes no id for it, so this is a design choice rather than a defect",
+                    });
+                }
+            }
+            if (declared.length)
+                results.push({ layer: 2, subject: id, check: "declared", verdict: "Pass", actual: declared.join(", "), detail: "interfaces of the same repository the contract reports as supported" });
+        }
+        let l3;
+        if (!art && id === "identity8004") {
+            l3 = "NotApplicable";
+            results.push({ layer: 3, subject: id, check: "runtimeIdentity", verdict: l3, detail: "official ERC-8004 registry, not built by FOGA; no locked build to compare against" });
+        }
+        else if (!art) {
+            l3 = "Unknown";
+            results.push({ layer: 3, subject: id, check: "runtimeIdentity", verdict: l3, detail: "no bundle key" });
+        }
+        else {
+            const onChain = runtimeIdentity(code, art.deployedLinkReferences, art.immutableReferences);
+            l3 = onChain === art.runtimeIdentity ? "Pass" : "Fail";
+            results.push({
+                layer: 3,
+                subject: id,
+                check: "runtimeIdentity",
+                verdict: l3,
+                expected: art.runtimeIdentity,
+                actual: onChain,
+                detail: l3 === "Fail" ? (entry.deployedRevision ? `known: deployed from ${entry.deployedRevision}; bundle is built from the locked commit` : "runtime code differs from the locked build") : `${art.runtimeCodeSize} bytes, ${art.compiler}`,
+            });
+        }
+        perContract[id] = { address, layer1: l1, layer2: l2, layer3: l3, layer4: "NotApplicable" };
+    }
+    for (const check of WIRING_CHECKS) {
+        const subject = world.contracts[check.subject];
+        if (!subject)
+            continue;
+        const label = check.label ?? check.fn;
+        const key = `wire:${check.subject}:${label}`;
+        const pc = perContract[check.subject];
+        const bump = (v) => {
+            if (pc)
+                pc.layer4 = worst(pc.layer4 === "NotApplicable" ? v : pc.layer4, v);
+        };
+        const art = subject.bundleKey ? bundle.contracts[subject.bundleKey] : undefined;
+        if (!art || !art.abi.some((f) => f.type === "function" && f.name === check.fn)) {
+            results.push({ layer: 4, subject: check.subject, check: label, verdict: "Unknown", detail: "getter not in the bundle ABI" });
+            bump("Unknown");
+            continue;
+        }
+        const args = check.args ? check.args(world) : [];
+        if (args === null) {
+            results.push({ layer: 4, subject: check.subject, check: label, verdict: "NotApplicable", detail: "arguments unavailable in this world file" });
+            continue;
+        }
+        let expected;
+        let source = "";
+        const expKey = `${check.subject}.${label}`;
+        if (expectations[expKey] !== undefined) {
+            expected = expectations[expKey];
+            source = "world expectation";
+        }
+        else if (check.expectRef) {
+            const ref = world.contracts[check.expectRef];
+            if (!ref) {
+                results.push({ layer: 4, subject: check.subject, check: label, verdict: "NotApplicable", detail: `reference ${check.expectRef} absent from this world` });
+                continue;
+            }
+            expected = ref.address;
+            source = check.expectRef;
+        }
+        else if (check.expectParam) {
+            expected = check.expectParam(world);
+            source = "world params";
+        }
+        const outcome = r(key);
+        if (!outcome) {
+            results.push({ layer: 4, subject: check.subject, check: label, verdict: "NotTested", expected: fmt(expected) });
+            continue;
+        }
+        if ("error" in outcome) {
+            results.push({ layer: 4, subject: check.subject, check: label, verdict: "Fail", expected: `${fmt(expected)} (${source})`, detail: `call failed: ${outcome.error}` });
+            bump("Fail");
+            continue;
+        }
+        let actual;
+        try {
+            const decoded = new Interface(art.abi).decodeFunctionResult(check.fn, outcome.result);
+            actual = decoded.length === 1 ? decoded[0] : decoded.toArray();
+        }
+        catch (e) {
+            results.push({ layer: 4, subject: check.subject, check: label, verdict: "Unknown", detail: `cannot decode result: ${e.message}` });
+            bump("Unknown");
+            continue;
+        }
+        const v = same(expected, actual) ? "Pass" : "Fail";
+        results.push({ layer: 4, subject: check.subject, check: label, verdict: v, expected: `${fmt(expected)} (${source})`, actual: fmt(actual) });
+        bump(v);
+    }
+    for (const ro of READOUTS) {
+        const subject = world.contracts[ro.subject];
+        const art = subject?.bundleKey ? bundle.contracts[subject.bundleKey] : undefined;
+        const outcome = r(`readout:${ro.subject}:${ro.fn}`);
+        if (!subject || !art || !outcome)
+            continue;
+        if ("error" in outcome) {
+            readouts.push({ subject: ro.subject, fn: ro.fn, value: `(call failed: ${outcome.error})` });
+            continue;
+        }
+        try {
+            const decoded = new Interface(art.abi).decodeFunctionResult(ro.fn, outcome.result);
+            readouts.push({ subject: ro.subject, fn: ro.fn, value: fmt(decoded.length === 1 ? decoded[0] : decoded.toArray()) });
+        }
+        catch {
+            readouts.push({ subject: ro.subject, fn: ro.fn, value: outcome.result });
+        }
+    }
+    const ercs = new Set(Object.keys(world.contracts).map((k) => k.split("/")[0]).filter((k) => /^\d+$/.test(k)));
+    if (Object.keys(world.contracts).some((k) => k.startsWith("identity8004") || k.startsWith("8004/")))
+        ercs.add("8004");
+    if (!genesis) {
+        for (const erc of [...ercs].sort()) {
+            results.push({ layer: 5, subject: `ERC-${erc}`, check: "semantic validation", verdict: "NotTested", detail: "no genesis evidence given (foga genesis run, then foga doctor --genesis <evidence.json>)" });
+        }
+    }
+    else {
+        const sameWorld = genesis.worldId === world.worldId && genesis.chainId === world.chainId;
+        results.push({ layer: 5, subject: "genesis", check: "evidence", verdict: sameWorld ? "Pass" : "Fail", expected: `${world.worldId} (chain ${world.chainId})`, actual: `${genesis.worldId} (chain ${genesis.chainId}), until ${genesis.until}, ${genesis.summary.checks} checks, ${genesis.summary.failed} failed, ran ${genesis.ranAt}`, detail: sameWorld ? undefined : "the evidence was produced on another world; layer-5 verdicts below are not about this world" });
+        for (const v of semanticVerdicts(genesis, [...ercs].sort())) {
+            results.push({ layer: 5, subject: `ERC-${v.erc}`, check: "semantic validation", verdict: sameWorld ? v.verdict : "Unknown", expected: "every genesis check that exercises the standard passes", actual: `${v.passed} pass, ${v.failed} fail, ${v.skipped} skipped`, detail: v.detail });
+        }
+    }
+    if (loopD) {
+        const sameWorld = loopD.evidence.worldId === world.worldId && loopD.evidence.chainId === world.chainId;
+        results.push({ layer: "D", subject: "loop D", check: "evidence", verdict: sameWorld ? "Pass" : "Fail", expected: `${world.worldId} (chain ${world.chainId})`, actual: `${loopD.evidence.worldId} (chain ${loopD.evidence.chainId}), model ${loopD.evidence.model.provider}/${loopD.evidence.model.model}, ${loopD.evidence.cases.length} cases, ran ${loopD.evidence.ranAt}`, detail: sameWorld ? undefined : "the evidence was produced on another world; the Loop D verdicts below are not about this world" });
+        for (const r of loopDVerdicts(loopD.evidence, loopD.compare))
+            results.push({ layer: "D", subject: "loop D", check: r.check, verdict: sameWorld ? r.verdict : "Unknown", expected: r.expected, actual: r.actual, detail: r.detail });
+    }
+    const summary = { Pass: 0, Fail: 0, Unknown: 0, NotTested: 0, NotApplicable: 0 };
+    for (const x of results)
+        summary[x.verdict]++;
+    return {
+        schema: "foga.doctor-report/1",
+        at: new Date().toISOString(),
+        world: { worldId: world.worldId, name: world.name, network: world.network, chainId: world.chainId, mode: world.mode, bundleHash: world.bundleHash },
+        source: { rpc: probe.rpc, collectedAt: probe.at, mode },
+        chain: { chainId, blockNumber },
+        bundleHash: bundle.hash,
+        layers: LAYERS,
+        results,
+        readouts,
+        summary,
+        perContract,
+    };
+}
+export async function runDoctor(opts) {
+    const root = repoRoot();
+    const world = loadWorldFile(opts.worldPath);
+    const bundle = loadBundle(opts.bundlePath);
+    const plan = buildProbePlan(world, bundle);
+    if (opts.exportProbePath) {
+        writeJson(opts.exportProbePath, plan);
+        log.info(`probe plan with ${plan.requests.length} requests written to ${relative(root, opts.exportProbePath)}; collect results with any JSON-RPC relay, then \`foga doctor --world ... --import-results <file>\``);
+        return { report: null, path: opts.exportProbePath };
+    }
+    let probe;
+    let mode;
+    if (opts.importResultsPath) {
+        probe = readJson(opts.importResultsPath);
+        if (probe.schema !== "foga.probe-results/1")
+            throw new Error(`${opts.importResultsPath} is not a probe-results file`);
+        mode = "replay";
+    }
+    else {
+        const rpc = opts.rpc ?? process.env.FOGA_RPC_URL ?? (world.network === "anvil" ? "http://127.0.0.1:8545" : undefined);
+        if (!rpc)
+            throw new Error("no RPC: pass --rpc, set FOGA_RPC_URL, or replay with --import-results");
+        probe = await executeProbeLive(plan, rpc);
+        mode = "live";
+    }
+    const genesis = opts.genesisPath ? loadGenesisEvidence(opts.genesisPath) : undefined;
+    const loopD = opts.loopDPath ? { evidence: loadLoopDEvidence(opts.loopDPath), compare: opts.loopDComparePath ? loadLoopDEvidence(opts.loopDComparePath) : undefined } : undefined;
+    const report = evaluate(world, bundle, plan, probe, mode, genesis, loopD);
+    printReport(report, opts.quiet);
+    let outPath = null;
+    if (opts.outPath) {
+        outPath = opts.outPath;
+        writeJson(outPath, report);
+        log.info(`report written to ${relative(root, outPath)}`);
+    }
+    return { report, path: outPath };
+}
+function printReport(r, quiet = false) {
+    const pad = (s, n) => (s.length >= n ? s + " " : s + " ".repeat(n - s.length));
+    console.log(`\nfoga doctor — world ${r.world.worldId} (${r.world.network}, chain ${r.chain.chainId ?? "?"}, block ${r.chain.blockNumber ?? "?"}, ${r.source.mode} via ${r.source.rpc})`);
+    console.log(`bundle ${r.bundleHash}${r.world.bundleHash && r.world.bundleHash !== r.bundleHash ? " (world built from " + r.world.bundleHash + ")" : ""}\n`);
+    if (!quiet) {
+        console.log(pad("contract", 34) + pad("address", 44) + pad("L1 code", 10) + pad("L2 iface", 15) + pad("L3 version", 12) + "L4 wiring");
+        for (const [id, pc] of Object.entries(r.perContract)) {
+            console.log(pad(id, 34) + pad(pc.address, 44) + pad(pc.layer1, 10) + pad(pc.layer2, 15) + pad(pc.layer3, 12) + pc.layer4);
+        }
+    }
+    const fails = r.results.filter((x) => x.verdict === "Fail");
+    if (fails.length) {
+        console.log("\nfailures:");
+        for (const f of fails)
+            console.log(`  L${f.layer} ${f.subject} ${f.check}: expected ${f.expected ?? "-"}, actual ${f.actual ?? "-"}${f.detail ? " — " + f.detail : ""}`);
+    }
+    const unknowns = r.results.filter((x) => x.verdict === "Unknown");
+    if (unknowns.length && !quiet) {
+        console.log("\nunknown:");
+        for (const u of unknowns)
+            console.log(`  L${u.layer} ${u.subject} ${u.check}${u.detail ? " — " + u.detail : ""}`);
+    }
+    if (r.readouts.length && !quiet) {
+        console.log("\nreadouts:");
+        for (const x of r.readouts)
+            console.log(`  ${x.subject}.${x.fn} = ${x.value}`);
+    }
+    const l5 = r.results.filter((x) => x.layer === 5 && x.subject.startsWith("ERC-"));
+    if (l5.some((x) => x.verdict !== "NotTested")) {
+        console.log("\nlayer 5 (semantic, from the genesis evidence):");
+        for (const x of l5)
+            console.log(`  ${pad(x.subject, 10)} ${pad(x.verdict, 10)} ${x.detail ?? ""}`);
+    }
+    const loopD = r.results.filter((x) => x.layer === "D" && x.check !== "evidence");
+    if (loopD.length)
+        printLoopDRows(loopD.map((x) => ({ check: x.check, verdict: x.verdict, expected: x.expected ?? "", actual: x.actual ?? "", detail: x.detail })));
+    console.log(`\nsummary: ${Object.entries(r.summary).map(([k, v]) => `${k} ${v}`).join(", ")}${l5.every((x) => x.verdict === "NotTested") ? "; layer 5 (semantic) needs the genesis evidence: foga genesis run, then foga doctor --genesis <evidence.json>" : ""}\n`);
+}
+/** `foga doctor --loop-d <evidence> [--compare <evidence>] [--out <report>]` without a world: the Loop D table alone. */
+export function runLoopDDoctor(opts) {
+    const evidence = loadLoopDEvidence(opts.evidencePath);
+    const compare = opts.comparePath ? loadLoopDEvidence(opts.comparePath) : undefined;
+    const results = loopDVerdicts(evidence, compare);
+    const summary = { Pass: 0, Fail: 0, Unknown: 0, NotTested: 0, NotApplicable: 0 };
+    for (const x of results)
+        summary[x.verdict]++;
+    console.log(`\nfoga doctor — loop D evidence ${relative(repoRoot(), opts.evidencePath)} (world ${evidence.worldId}, chain ${evidence.chainId}, model ${evidence.model.provider}/${evidence.model.model}, ran ${evidence.ranAt})`);
+    printLoopDRows(results);
+    console.log(`\nsummary: ${Object.entries(summary).map(([k, v]) => `${k} ${v}`).join(", ")}\n`);
+    const report = { schema: "foga.loop-d-report/1", at: new Date().toISOString(), evidence: { path: opts.evidencePath, worldId: evidence.worldId, chainId: evidence.chainId, model: evidence.model, ranAt: evidence.ranAt }, compare: compare ? { path: opts.comparePath, model: compare.model } : null, results, summary };
+    if (opts.outPath) {
+        writeJson(opts.outPath, report);
+        log.info(`loop D report written to ${relative(repoRoot(), opts.outPath)}`);
+    }
+    return report;
+}
+function printLoopDRows(rows) {
+    const pad = (s, n) => (s.length >= n ? s + " " : s + " ".repeat(n - s.length));
+    console.log("\nloop D (from the run's records):");
+    for (const x of rows)
+        console.log(`  ${pad(x.verdict, 10)} ${x.check}\n             ${x.actual}${x.detail ? ` — ${x.detail}` : ""}`);
+}

package/dist/doctor/loop-d.js

@@ -0,0 +1,103 @@
+import { readJson } from "../util/fs.js";
+export function loadLoopDEvidence(path) {
+    const e = readJson(path);
+    if (e.schema !== "foga.loop-d-evidence/1")
+        throw new Error(`${path} is not a loop D evidence file (schema ${String(e.schema)})`);
+    return e;
+}
+const row = (check, verdict, expected, actual, detail) => ({ check, verdict, expected, actual, ...(detail ? { detail } : {}) });
+export function loopDVerdicts(e, compare) {
+    const rows = [];
+    const allowed = e.decisions.filter((d) => d.verdict === "allowed");
+    const refused = e.decisions.filter((d) => d.verdict === "refused");
+    const jobOps = e.operations.filter((o) => o.signer === "operator" && o.key.startsWith("job:"));
+    // 1. no act outside policy: every operation of the operator key under a job has an allowed decision for that job
+    const orphans = jobOps.filter((o) => !allowed.some((d) => d.jobId && o.key.startsWith(`job:${d.jobId}:`)));
+    rows.push(row("every operation has an allowed decision", orphans.length ? "Fail" : "Pass", `${jobOps.length} operation(s), each under a job an allowed decision names`, orphans.length ? `${orphans.length} without one: ${orphans.map((o) => o.key).join(", ")}` : `${jobOps.length} operation(s), ${allowed.length} allowed decision(s)`));
+    // 2. a refused attempt broadcasts nothing: no operation of its job is created after the refusal (a conflict names an older job; an execution refusal names the operation that failed)
+    const leaks = refused.filter((d) => d.jobId && !["conflict", "execution"].includes(d.gate) && e.operations.some((o) => o.key.startsWith(`job:${d.jobId}:`) && o.createdAt >= d.at));
+    rows.push(row("a refused attempt broadcasts nothing", leaks.length ? "Fail" : "Pass", `${refused.length} refusal(s) with no operation created after them`, leaks.length ? `${leaks.length} refusal(s) followed by an operation: ${leaks.map((d) => `${d.capability}#${d.id}`).join(", ")}` : `${refused.length} refusal(s) at ${[...new Set(refused.map((d) => d.gate))].join(", ") || "-"}, none followed by an operation`));
+    // 3. the four books: value moved, fees paid, model calls, commitments
+    const value = BigInt(e.budget.used.valueWei);
+    const gas = BigInt(e.budget.used.gasWei);
+    const perOp = BigInt(e.budget.perOperationValueWei);
+    const overPerOp = e.operations.filter((o) => o.signer === "operator" && BigInt(o.valueWei) > perOp);
+    const budgetOk = value <= BigInt(e.budget.dailyValueWei) && gas <= BigInt(e.budget.dailyGasWei) && e.budget.used.modelCalls <= e.budget.dailyModelCalls && overPerOp.length === 0;
+    rows.push(row("spend within the four budget books", budgetOk ? "Pass" : "Fail", `value <= ${e.budget.dailyValueWei} wei a day and <= ${e.budget.perOperationValueWei} per operation, fees <= ${e.budget.dailyGasWei} wei, model calls <= ${e.budget.dailyModelCalls}`, `value ${value} wei (${e.budget.used.commitmentsMade} commitment(s), ${overPerOp.length} over the per-operation cap), fees ${gas} wei, ${e.budget.used.modelCalls} model call(s), ${e.budget.used.skillRuns} skill run(s)`));
+    // 4. the operator key's transactions: all to the account, every inner call allow-listed, none reverted
+    const txs = e.chain.operatorTxs;
+    const astray = txs.filter((t) => !t.toIsAccount);
+    const unlisted = txs.filter((t) => t.toIsAccount && (!t.inner || t.inner.allowed !== true));
+    rows.push(row("operator transactions all go to the account, inside its allow-list", astray.length || unlisted.length ? "Fail" : txs.length ? "Pass" : "NotTested", "every transaction signed by the operator key calls the account's execute with an allow-listed (target, selector)", `${txs.length} transaction(s) in blocks ${e.chain.fromBlock}-${e.chain.toBlock}; ${astray.length} elsewhere, ${unlisted.length} not allow-listed`, astray.length || unlisted.length ? [...astray.map((t) => `${t.hash} -> ${t.to}`), ...unlisted.map((t) => `${t.hash} -> ${t.inner ? `${t.inner.target} ${t.inner.selector}` : "not execute"}`)].join("; ") : undefined));
+    const reverted = txs.filter((t) => t.status === 0);
+    rows.push(row("no operator transaction reverted", reverted.length ? "Unknown" : txs.length ? "Pass" : "NotTested", "the account's gate was never the one to refuse what every check allowed", reverted.length ? `${reverted.length} reverted: ${reverted.map((t) => t.hash).join(", ")}` : `${txs.length} succeeded`, reverted.length ? "a revert after an allowed decision is the chain refusing, not a policy refusal; see the execution decisions" : undefined));
+    // 5. the cases
+    for (const c of e.cases) {
+        const o = c.outcome;
+        const exp = c.expect;
+        let verdict = "Fail";
+        let actual = `${o.status}${o.gates.length ? ` (gates ${o.gates.join(" > ")})` : ""}`;
+        if (exp.outcome === "taken") {
+            const reached = BigInt(o.paidWei) + BigInt(o.withdrawnWei);
+            const paid = reached === BigInt(c.rewardWei);
+            verdict = o.status === "taken" && o.settled && paid ? "Pass" : "Fail";
+            actual += `; ${o.submissions.filter((s) => s.byCell).length} submission(s) by the cell, ${o.settled ? "settled" : "not settled"}, ${reached} of ${c.rewardWei} wei reached the account`;
+        }
+        else if (exp.outcome === "refused") {
+            verdict = o.status === "refused" && o.gates[0] === exp.gate && !o.submissions.some((s) => s.byCell) ? "Pass" : "Fail";
+            actual += `; ${o.submissions.filter((s) => s.byCell).length} submission(s) by the cell`;
+        }
+        else {
+            const reached = BigInt(o.paidWei) + BigInt(o.withdrawnWei);
+            verdict = o.status === "refused-then-taken" && o.gates[0] === exp.gate && o.gates.includes("allowed") && o.settled && reached === BigInt(c.rewardWei) ? "Pass" : "Fail";
+            actual += `; ${o.settled ? "settled after the resume" : "not settled"}, ${reached} of ${c.rewardWei} wei reached the account`;
+        }
+        rows.push(row(`case ${c.id}: ${c.note}`, verdict, exp.outcome === "taken" ? "taken: submitted, settled, the reward on the account" : exp.outcome === "refused" ? `refused at ${exp.gate}, no submission` : `refused at ${exp.gate} during the suspension, taken after the resume`, actual, `tender ${c.tokenId}; decisions ${o.decisions.join(", ") || "-"}`));
+    }
+    // 6. case g: a proposal above the budget
+    const g = e.budgetProbe;
+    rows.push(row("case g: a proposal above the budget is refused at budget", g.attempted ? (g.gate === "budget" ? "Pass" : "Fail") : "NotTested", "the model's over-budget act refused at `budget`, nothing broadcast", g.attempted ? `${g.capability} refused at ${g.gate} (decision ${g.decisionId})` : "the model made no proposal above the budget", g.attempted ? undefined : "the stub makes this proposal on purpose; a real model may never make it"));
+    // 7. the evidence is complete
+    const complete = e.runner.ticks > 0 && e.runner.trajectoryHashes.length === e.runner.ticks && e.model.model.length > 0 && e.decisions.length > 0;
+    rows.push(row("the evidence carries every decision and every tick's trajectory hash", complete ? "Pass" : "Fail", "model named, a hash per tick, decision records present", `${e.model.provider}/${e.model.model || "?"}, ${e.runner.ticks} tick(s), ${e.runner.trajectoryHashes.length} hash(es), ${e.decisions.length} decision(s), ${e.runner.errors} model error(s)`));
+    // 8. recovery: killed after a submission, restarted, nothing sent twice
+    const r = e.recovery;
+    if (r.performed && r.tokenId) {
+        const subs = e.cases.find((c) => c.tokenId === r.tokenId)?.outcome.submissions.filter((s) => s.byCell) ?? [];
+        const submitOps = e.operations.filter((o) => new RegExp(`^job:tender:${r.tokenId}:c\\d+:submit$`).test(o.key));
+        const settleOps = e.operations.filter((o) => o.key.startsWith(`job:tender:${r.tokenId}:`) && o.key.endsWith(":settle:settle") && o.status === "confirmed");
+        const ok = subs.length === 1 && submitOps.length === 1 && submitOps[0].status === "confirmed" && settleOps.length === 1 && Boolean(r.restartedAt) && settleOps[0].createdAt >= r.restartedAt;
+        rows.push(row("recovery: killed after the submission, restarted, nothing sent twice", ok ? "Pass" : "Fail", "one submission by the cell, one submit operation, one settlement made after the restart", `tender ${r.tokenId}: ${subs.length} submission(s), ${submitOps.length} submit operation(s), ${settleOps.length} settlement(s)${settleOps[0] && r.restartedAt ? ` (${settleOps[0].createdAt >= r.restartedAt ? "after" : "before"} the restart)` : ""}`, `killed after ${r.killedAfterOperation} at ${r.killedAt}, restarted at ${r.restartedAt}`));
+    }
+    else
+        rows.push(row("recovery: killed after the submission, restarted, nothing sent twice", "NotTested", "one submission by the cell, one settlement after the restart", "the run performed no recovery drill"));
+    // 9. the other entrances beside the runner
+    const idem = e.entrances.idempotent;
+    rows.push(row("the same request through another entrance is one business operation", idem ? (idem.gate === "idempotent" && idem.sameTxHash ? "Pass" : "Fail") : "NotTested", "answered from the store (idempotent), the same transaction hash, nothing sent", idem ? `${idem.gate} (decision ${idem.decisionId}), ${idem.sameTxHash ? "the same" : "another"} transaction` : "not exercised"));
+    const conf = e.entrances.conflict;
+    rows.push(row("the same job under another request is a conflict", conf ? (conf.gate === "conflict" ? "Pass" : "Fail") : "NotTested", "refused at `conflict`", conf ? `${conf.gate ?? "allowed"} (decision ${conf.decisionId})` : "not exercised"));
+    const conc = e.entrances.concurrent;
+    const nonces = e.operations.filter((o) => o.signer === "operator" && o.nonce !== null).map((o) => o.nonce);
+    const uniqueNonces = new Set(nonces).size === nonces.length;
+    const nonceFailures = e.operations.filter((o) => o.signer === "operator" && o.status === "failed" && /nonce/i.test(o.error ?? ""));
+    rows.push(row("concurrent acts across entrances and the watchers: distinct nonces, the budget holding", conc ? (uniqueNonces && nonceFailures.length === 0 && conc.allowed + conc.refused.length === conc.requested && conc.refused.every((x) => x.gate === "budget") ? "Pass" : "Fail") : uniqueNonces && nonceFailures.length === 0 ? "Pass" : "Fail", "every operator operation on its own nonce, no nonce failure, refusals (if any) at `budget`", `${nonces.length} nonce(s), ${uniqueNonces ? "all distinct" : "repeated"}, ${nonceFailures.length} nonce failure(s)${conc ? `; ${conc.requested} concurrent mint(s): ${conc.allowed} allowed, ${conc.refused.length} refused (${conc.refused.map((x) => x.gate).join(", ") || "-"})` : ""}`));
+    // 10. model-agnostic: the stub and a real model reach the same outcomes
+    if (compare) {
+        const diffs = [];
+        for (const c of e.cases) {
+            const other = compare.cases.find((x) => x.id === c.id);
+            if (!other) {
+                diffs.push(`${c.id}: missing in the other run`);
+                continue;
+            }
+            const a = `${c.outcome.status}/${c.outcome.gates[0] ?? "-"}`;
+            const b = `${other.outcome.status}/${other.outcome.gates[0] ?? "-"}`;
+            if (a !== b)
+                diffs.push(`${c.id}: ${a} vs ${b}`);
+        }
+        rows.push(row("model-agnostic: the same outcomes from both models", diffs.length ? "Fail" : "Pass", "every case ends the same way under both models", diffs.length ? diffs.join("; ") : `${e.cases.length} case(s) agree (${e.model.provider}/${e.model.model} vs ${compare.model.provider}/${compare.model.model})`));
+    }
+    else
+        rows.push(row("model-agnostic: the same outcomes from both models", "NotTested", "every case ends the same way under both models", "one run only; pass a second evidence file with --compare"));
+    return rows;
+}

package/dist/doctor/probe.js

@@ -0,0 +1,97 @@
+import { Interface, JsonRpcProvider } from "ethers";
+import { READOUTS, WIRING_CHECKS } from "./checks.js";
+export function buildProbePlan(world, bundle) {
+    const requests = [
+        { key: "chainId", method: "eth_chainId", params: [] },
+        { key: "blockNumber", method: "eth_blockNumber", params: [] },
+    ];
+    const ifacesByRepo = new Map();
+    for (const c of Object.values(bundle.contracts)) {
+        if (c.kind === "interface" && c.interfaceId) {
+            const l = ifacesByRepo.get(c.repo) ?? [];
+            l.push({ name: c.name, id: c.interfaceId });
+            ifacesByRepo.set(c.repo, l);
+        }
+    }
+    const erc165 = new Interface(["function supportsInterface(bytes4) view returns (bool)"]);
+    for (const [id, entry] of Object.entries(world.contracts)) {
+        requests.push({ key: `code:${id}`, method: "eth_getCode", params: [entry.address, "latest"] });
+        const art = entry.bundleKey ? bundle.contracts[entry.bundleKey] : undefined;
+        if (!art && id === "identity8004") {
+            // The official ERC-8004 Identity Registry is not built by FOGA; probe the ERC-721 surface it must expose.
+            requests.push({ key: `iface:${id}:erc165`, method: "eth_call", params: [{ to: entry.address, data: erc165.encodeFunctionData("supportsInterface", ["0x01ffc9a7"]) }, "latest"] });
+            requests.push({ key: `iface:${id}:ERC721`, method: "eth_call", params: [{ to: entry.address, data: erc165.encodeFunctionData("supportsInterface", ["0x80ac58cd"]) }, "latest"], note: "0x80ac58cd" });
+            continue;
+        }
+        if (!art || !art.abi.some((f) => f.type === "function" && f.name === "supportsInterface"))
+            continue;
+        requests.push({ key: `iface:${id}:erc165`, method: "eth_call", params: [{ to: entry.address, data: erc165.encodeFunctionData("supportsInterface", ["0x01ffc9a7"]) }, "latest"] });
+        for (const iface of ifacesByRepo.get(art.repo) ?? []) {
+            requests.push({ key: `iface:${id}:${iface.name}`, method: "eth_call", params: [{ to: entry.address, data: erc165.encodeFunctionData("supportsInterface", [iface.id]) }, "latest"], note: iface.id });
+        }
+    }
+    for (const check of WIRING_CHECKS) {
+        const subject = world.contracts[check.subject];
+        if (!subject)
+            continue;
+        const art = subject.bundleKey ? bundle.contracts[subject.bundleKey] : undefined;
+        if (!art || !art.abi.some((f) => f.type === "function" && f.name === check.fn))
+            continue;
+        const args = check.args ? check.args(world) : [];
+        if (args === null)
+            continue;
+        const data = new Interface(art.abi).encodeFunctionData(check.fn, args);
+        requests.push({ key: `wire:${check.subject}:${check.label ?? check.fn}`, method: "eth_call", params: [{ to: subject.address, data }, "latest"] });
+    }
+    for (const r of READOUTS) {
+        const subject = world.contracts[r.subject];
+        const art = subject?.bundleKey ? bundle.contracts[subject.bundleKey] : undefined;
+        if (!subject || !art || !art.abi.some((f) => f.type === "function" && f.name === r.fn))
+            continue;
+        const data = new Interface(art.abi).encodeFunctionData(r.fn, []);
+        requests.push({ key: `readout:${r.subject}:${r.fn}`, method: "eth_call", params: [{ to: subject.address, data }, "latest"] });
+    }
+    return { schema: "foga.probe/1", worldId: world.worldId, chainId: world.chainId, bundleHash: bundle.hash, requests };
+}
+export async function executeProbeLive(plan, rpc, concurrency = 8) {
+    const provider = new JsonRpcProvider(rpc, undefined, { staticNetwork: true, cacheTimeout: -1, batchMaxCount: 1 });
+    const results = {};
+    const queue = [...plan.requests];
+    const worker = async () => {
+        for (;;) {
+            const req = queue.shift();
+            if (!req)
+                return;
+            try {
+                const result = await provider.send(req.method, req.params);
+                results[req.key] = { result: typeof result === "string" ? result : JSON.stringify(result) };
+            }
+            catch (e) {
+                results[req.key] = { error: e?.shortMessage ?? e?.message ?? String(e) };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: concurrency }, worker));
+    return { schema: "foga.probe-results/1", worldId: plan.worldId, at: new Date().toISOString(), rpc, results };
+}
+/** Minimal browser/relay-side executor, emitted as text so a relay without this package can run the plan. */
+export const RELAY_SCRIPT = `// Runs a FOGA probe plan against a JSON-RPC endpoint and prints the results JSON.
+// usage (node 18+): node relay.mjs <rpc-url> <probe.json> > results.json
+import { readFileSync } from "node:fs";
+const [rpc, planPath] = process.argv.slice(2);
+const plan = JSON.parse(readFileSync(planPath, "utf8"));
+(async () => {
+  const results = {};
+  for (let i = 0; i < plan.requests.length; i += 20) {
+    const batch = plan.requests.slice(i, i + 20);
+    const body = batch.map((r, j) => ({ jsonrpc: "2.0", id: j, method: r.method, params: r.params }));
+    const res = await fetch(rpc, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    const arr = await res.json();
+    for (const item of Array.isArray(arr) ? arr : [arr]) {
+      const req = batch[item.id];
+      results[req.key] = item.error ? { error: String(item.error.message || item.error) } : { result: item.result };
+    }
+  }
+  process.stdout.write(JSON.stringify({ schema: "foga.probe-results/1", worldId: plan.worldId, at: new Date().toISOString(), rpc, results }, null, 2));
+})();
+`;