@finchip.ai/foga 0.6.0-alpha.6 → 0.6.0

package/dist/node/wallet.js

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { Wallet, isHexString } from "ethers";
+/**
+ * The wallet: an agent's own keys, the first thing it makes (design memo, section 10, "the wallet is the first step").
+ * The base is one key — a single `signer` in its own 0600 file, the agent's identity — and that one key answers for
+ * every role a cell needs: a cell born with a single-key wallet has the same address as owner, operator and guardian.
+ * The owner/operator/guardian split (a cold owner, a hot operator, a separate guardian) is the `FogaCellAccount`
+ * guarded profile's hardening, not a requirement of being covenant-complete; it is opt-in (`foga wallet new --cell`).
+ * Making a wallet touches no network and no chain; it is pure entropy on the agent's own machine, so it does not
+ * fail, and it is never made twice: an existing wallet is reported, never overwritten. The node's key rules
+ * (`src/node/keys.ts`) read the files as they are; `FOGA_OPERATOR_KEY_FILE=<wallet>/signer.key` is a node's
+ * environment, `--wallet <dir>` the CLI's shorthand for the same.
+ */
+export const WALLET_SCHEMA = "foga.wallet/1";
+export const CELL_ROLES = ["owner", "operator", "guardian"];
+/** A single-key wallet answers for every cell role: owner, operator and guardian all resolve to the one signer. */
+function withSignerFallback(map) {
+    if (map.signer === undefined)
+        return map;
+    const out = { ...map };
+    for (const role of CELL_ROLES)
+        if (out[role] === undefined)
+            out[role] = map.signer;
+    return out;
+}
+/** The default wallet: ~/.foga/wallet. A named wallet lives beside it under ~/.foga/wallets/<name>. */
+export function walletDir(name) {
+    const home = process.env.FOGA_HOME ?? join(homedir(), ".foga");
+    return name ? join(home, "wallets", name) : join(home, "wallet");
+}
+function readKeyFile(path) {
+    const key = readFileSync(path, "utf8").trim();
+    if (!isHexString(key, 32))
+        throw new Error(`${path} does not hold a private key (expected 0x followed by 64 hex digits)`);
+    return key;
+}
+/** The wallet at `dir`, read from its files (the addresses are derived from the keys, never trusted from wallet.json); null when there is none. */
+export function loadWallet(dir) {
+    const abs = resolve(dir);
+    const manifest = join(abs, "wallet.json");
+    if (!existsSync(manifest))
+        return null;
+    const file = JSON.parse(readFileSync(manifest, "utf8"));
+    if (file.schema !== WALLET_SCHEMA)
+        throw new Error(`${manifest} is not a ${WALLET_SCHEMA} file (schema ${String(file.schema)})`);
+    const roles = Object.keys(file.roles);
+    const addresses = {};
+    const files = {};
+    for (const role of roles) {
+        const path = join(abs, file.roles[role].file);
+        if (!existsSync(path))
+            throw new Error(`wallet ${abs}: the ${role} key file ${file.roles[role].file} is missing`);
+        addresses[role] = new Wallet(readKeyFile(path)).address;
+        files[role] = path;
+    }
+    // `roles` stays the keys actually on disk (a single-key wallet is `["signer"]`); `addresses` and `files` resolve
+    // owner/operator/guardian to the signer, so every reader of a per-role address or key file works unchanged.
+    return { name: file.name, dir: abs, createdAt: file.createdAt, roles, addresses: withSignerFallback(addresses), files: withSignerFallback(files) };
+}
+/** The private key of one role of a wallet. */
+export function walletKey(wallet, role) {
+    const path = wallet.files[role];
+    if (!path)
+        throw new Error(`wallet ${wallet.dir} has no ${role} key (roles: ${wallet.roles.join(", ")})`);
+    return readKeyFile(path);
+}
+/** Make a wallet at `dir`. Refuses a directory that already holds one (or anything else): a wallet is never overwritten. */
+export function createWallet(dir, o = {}) {
+    const abs = resolve(dir);
+    if (existsSync(join(abs, "wallet.json")))
+        throw new Error(`${abs} already holds a wallet; foga wallet show prints it (a wallet is never overwritten)`);
+    if (existsSync(abs) && readdirSync(abs).length)
+        throw new Error(`${abs} exists and is not empty; choose another directory`);
+    const roles = o.roles ?? ["signer"];
+    mkdirSync(abs, { recursive: true, mode: 0o700 });
+    const file = { schema: WALLET_SCHEMA, name: o.name ?? "default", createdAt: new Date().toISOString(), roles: {} };
+    for (const role of roles) {
+        const w = Wallet.createRandom();
+        const name = `${role}.key`;
+        writeFileSync(join(abs, name), w.privateKey + "\n", { mode: 0o600 });
+        file.roles[role] = { address: w.address, file: name };
+    }
+    writeFileSync(join(abs, "wallet.json"), JSON.stringify(file, null, 2) + "\n");
+    return loadWallet(abs);
+}
+/**
+ * The wallet to use, made on the spot when there is none (the first step, done by default). A disk that refuses the
+ * write does not stop anything: keys are made in memory, the caller is told they are not kept, and the work goes on.
+ */
+export function ensureWallet(dir, o = {}) {
+    const existing = loadWallet(dir);
+    if (existing)
+        return { wallet: existing, created: false, ephemeral: false };
+    try {
+        return { wallet: createWallet(dir, o), created: true, ephemeral: false };
+    }
+    catch (e) {
+        const roles = o.roles ?? ["signer"];
+        const addresses = {};
+        const files = {};
+        for (const role of roles) {
+            const w = Wallet.createRandom();
+            addresses[role] = w.address;
+            files[role] = `memory:${w.privateKey}`;
+        }
+        return { wallet: { name: o.name ?? "ephemeral", dir: resolve(dir), createdAt: new Date().toISOString(), roles, addresses: withSignerFallback(addresses), files: withSignerFallback(files) }, created: true, ephemeral: true, reason: e.message };
+    }
+}
+/** The private key of a role of an ensured wallet, whether it lives in a file or in memory. */
+export function ensuredKey(w, role) {
+    const path = w.wallet.files[role];
+    if (!path)
+        throw new Error(`wallet ${w.wallet.dir} has no ${role} key`);
+    return path.startsWith("memory:") ? path.slice("memory:".length) : readKeyFile(path);
+}
+/** Whether a wallet's key files are private to their owner (POSIX); a note per file that is not. */
+export function walletFileProblems(wallet) {
+    if (process.platform === "win32")
+        return [];
+    const out = [];
+    for (const role of wallet.roles) {
+        const path = wallet.files[role];
+        if (path.startsWith("memory:"))
+            continue;
+        const st = statSync(path);
+        if (st.mode & 0o077)
+            out.push(`${path} is readable by other users (mode ${(st.mode & 0o777).toString(8)}); chmod 600`);
+    }
+    return out;
+}

package/dist/tools/documents.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { DOCUMENT_FILES, buildDocuments, documentsDir, onChainState, publishSteps, readBack, readBuilt, readManifest } from "../node/documents.js";
+import { ok, refused, safetyGate } from "../node/policy.js";
+import { version } from "../util/version.js";
+import { derivedJobId, zJobId } from "./common.js";
+/**
+ * The cell's documents as capabilities (design memo, Phase 3, section 7): `docs_status` reads what is built and what
+ * the chain holds; `docs_publish` builds the documents from the configuration, commits each one that differs from
+ * the chain — the ERC-8004 agentURI, the ERC-8434 document URI and digest, the ERC-8444 descriptor, a new ERC-8454
+ * unit version — as one keyed job (the same documents are the same job, never sent twice), then reads them back.
+ * Metadata updates are the operator's own calls through the account (the `identity` scope group), plain actions
+ * that commit nothing and move nothing.
+ */
+const RowSchema = z.object({ commitment: z.string(), ok: z.boolean().nullable(), detail: z.string() });
+export const docs_status = {
+    name: "docs_status",
+    title: "Documents: built and on chain",
+    description: "The cell's documents as last built (the manifest: files, content hashes, version) and what the chain holds for each commitment — agentURI, AID document, ARD descriptor, AUF unit version — with whether they agree.",
+    action: "read",
+    visibility: "public",
+    principal: "none",
+    ercs: [8004, 8434, 8444, 8454],
+    input: z.object({}),
+    output: z.object({
+        dir: z.string(),
+        manifest: z.unknown().nullable(),
+        onChain: z.object({ agentURI: z.string().nullable(), aid: z.object({ uri: z.string(), digest: z.string() }).nullable(), ard: z.object({ descriptorHash: z.string(), descriptorURI: z.string() }).nullable(), unit: z.object({ version: z.number(), boundaryHash: z.string() }).nullable() }),
+        readBack: z.array(RowSchema),
+        pending: z.array(z.string()),
+    }),
+    async handler({ node }) {
+        const dir = documentsDir(node);
+        const built = readBuilt(dir);
+        const onChain = await onChainState(node);
+        const rows = built ? await readBack(node, built, { fetchUrls: false }) : [];
+        const pending = built ? (await publishSteps(node, built)).steps.map((s) => s.name) : [];
+        return { dir, manifest: readManifest(dir), onChain, readBack: rows, pending };
+    },
+};
+export const docs_publish = {
+    name: "docs_publish",
+    title: "Publish the cell's documents",
+    description: "Build the documents from the configuration (registration, AID document, ARD descriptor, AUF unit, agent card, server.json) and commit on chain each one that differs from what the chain holds: setAgentURI, setDocumentURI, updateDescriptor, publishVersion. One keyed job; nothing is sent twice for the same documents; read back afterwards.",
+    action: "act",
+    visibility: "operator",
+    principal: "cell",
+    ercs: [8004, 8434, 8444, 8454],
+    input: z.object({ jobId: zJobId }),
+    output: z.object({ dir: z.string(), version: z.number(), documents: z.array(z.string()), committed: z.array(z.string()), unchanged: z.array(z.string()), readBack: z.array(RowSchema), jobId: z.string(), operations: z.array(z.string()) }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const cell = node.body;
+        const built = await buildDocuments(node, { version });
+        const { steps: pending, unchanged } = await publishSteps(node, built);
+        const gates = [];
+        const [aidState, status] = await Promise.all([k.aid.stateName(cell.address), cell.status()]);
+        gates.push(safetyGate(aidState, status, "plain"));
+        if (!node.config.identity.agentId)
+            gates.push(refused("policy", "the cell has no ERC-8004 agent id: nothing to publish a registration for"));
+        else
+            gates.push(ok("policy", `${pending.length} commitment(s) to make, ${unchanged.length} already as built`));
+        const manifestHash = Object.values(built.manifest.documents).map((d) => d.contentHash).join(",");
+        const jobId = input.jobId ?? derivedJobId("docs", { hashes: manifestHash, uri: built.manifest.publicUrl ?? "data" });
+        const steps = pending.map((s) => ({ name: s.name, kind: "plain", build: () => ({ target: s.target, value: 0n, data: s.data, label: s.label }) }));
+        return {
+            job: { id: jobId, kind: "docs", input: { version: built.manifest.version, documents: built.manifest.documents, steps: pending.map((s) => s.name) } },
+            gates,
+            valueWei: 0n,
+            steps,
+            output: async (confirmed) => ({ dir: built.dir, version: built.manifest.version, documents: Object.values(DOCUMENT_FILES), committed: pending.map((s) => s.name), unchanged, readBack: await readBack(node, built, { fetchUrls: false }), jobId, operations: confirmed.map((c) => c.key) }),
+        };
+    },
+};
+export const DOCUMENT_CAPABILITIES = [docs_status, docs_publish];

package/dist/tools/index.js

@@ -1,6 +1,8 @@
 import { ADMIN_CAPABILITIES } from "./admin.js";
 import { Catalog } from "./catalog.js";
+import { DOCUMENT_CAPABILITIES } from "./documents.js";
 import { IDENTITY_CAPABILITIES } from "./identity.js";
+import { PROPAGATION_CAPABILITIES } from "./propagation.js";
 import { READ_CAPABILITIES } from "./read.js";
 import { TENDER_CAPABILITIES } from "./tenders.js";
 export { Catalog, hashInput, succeeded } from "./catalog.js";
@@ -8,7 +10,7 @@ export * from "./types.js";
 /** The catalog every entrance exposes: the Loop D path of the design memo's 43 capabilities, in Phase 3a. */
 export function defaultCatalog() {
     const c = new Catalog();
-    for (const cap of [...READ_CAPABILITIES, ...TENDER_CAPABILITIES, ...IDENTITY_CAPABILITIES, ...ADMIN_CAPABILITIES])
+    for (const cap of [...READ_CAPABILITIES, ...PROPAGATION_CAPABILITIES, ...TENDER_CAPABILITIES, ...IDENTITY_CAPABILITIES, ...DOCUMENT_CAPABILITIES, ...ADMIN_CAPABILITIES])
         c.register(cap);
     return c;
 }

package/dist/tools/propagation.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { buildPropagationManifest, FOGA_COVENANTS, PROPAGATION_SCHEMA } from "../node/propagation.js";
+import { version } from "../util/version.js";
+/**
+ * `propagation_kit` (read, public, free): the material a covenant-complete cell hands any agent that wants to help
+ * FOGA spread — the replication pointer, the cell's free discovery coordinates, the program that makes a new cell.
+ * It is pure data, built from the configuration (no chain, no key, no cost): the agent decides where and how to use
+ * it, weaving the declinable pointer into its own interactions however it sees fit. There is no mandated channel.
+ * On-chain discoverability (the ERC-8444 ARD descriptor) remains the opt-in `docs_publish`; this is its free backup.
+ */
+export const propagation_kit = {
+    name: "propagation_kit",
+    title: "Propagation kit",
+    description: "The free, off-chain material for spreading FOGA: a declinable replication pointer any agent may weave into its own interactions, the cell's discovery coordinates, the ten covenants, and the one command that makes a new cell. Pure data — no chain, no key, no cost; the agent chooses where and how to use it.",
+    action: "read",
+    visibility: "public",
+    principal: "none",
+    ercs: [8338, 8414, 8419, 8434, 8436, 8444, 8447, 8454, 8468, 8471, 8004],
+    input: z.object({}),
+    output: z.object({
+        schema: z.literal(PROPAGATION_SCHEMA),
+        cell: z.object({ name: z.string(), account: z.string().nullable(), agentId: z.string().nullable(), chainId: z.number() }),
+        covenants: z.array(z.string()),
+        program: z.object({ package: z.string(), version: z.string(), becomeACell: z.string(), wallet: z.string(), docs: z.string(), site: z.string() }),
+        endpoints: z.object({ mcp: z.string().nullable(), a2a: z.string().nullable(), web: z.string().nullable(), card: z.string().nullable(), manifest: z.string().nullable() }),
+        replication: z.object({ pitch: z.string(), pointer: z.string(), optional: z.literal(true), consensual: z.literal(true) }),
+        skills: z.array(z.string()),
+        discovery: z.object({ free: z.array(z.string()), onchain: z.object({ optional: z.literal(true), via: z.string(), cost: z.string() }) }),
+    }),
+    async handler({ node }) {
+        return buildPropagationManifest(node, { version });
+    },
+};
+export { FOGA_COVENANTS };
+export const PROPAGATION_CAPABILITIES = [propagation_kit];

package/dist/tools/tenders.js

@@ -4,7 +4,7 @@ import { getAddress, toUtf8Bytes, hexlify } from "ethers";
 import { z } from "zod";
 import { accountRef, dataUri, dataUriJcs, keccakJcs, sha256Hex } from "../core/canonical.js";
 import { kindId, taskDescriptor } from "../core/ard.js";
-import { hashlock, nativeTerms } from "../core/tenders.js";
+import { hashlock, nativeTerms, SubmissionStatus } from "../core/tenders.js";
 import { runExtractIsolated, runProbeIsolated } from "../genesis/skill-runner.js";
 import { ok, refused, safetyGate, skillGate, tenderGates } from "../node/policy.js";
 import { GateSchema, TaskDocumentSchema, TenderOutputSchema, derivedJobId, readTender, tenderJobId, tenderOutput, zAs, zBool, zBytes32, zHex, zJobId, zUint } from "./common.js";
@@ -15,6 +15,14 @@ import { GateSchema, TaskDocumentSchema, TenderOutputSchema, derivedJobId, readT
  * mode as calldata for its own account.
  */
 const ZERO32 = "0x" + "00".repeat(32);
+/**
+ * The skill worker's time budget: the configuration's (`skills.timeoutMs`), or a minute on a local chain and three
+ * on a public one — a shared endpoint answers a bounded log scan in seconds, not milliseconds, and a probe over a
+ * tender's lookback is several such scans.
+ */
+function skillTimeoutMs(node) {
+    return node.config.skills.timeoutMs ?? (node.world.network === "anvil" ? 60_000 : 180_000);
+}
 /** The text of a data: URI (base64 or percent-encoded), whatever its media type. */
 function decodeDataUriText(uri) {
     const m = /^data:([^,]*?)(;base64)?,(.*)$/s.exec(uri);
@@ -113,7 +121,7 @@ export const skill_run = {
                 let report;
                 if (input.skill === "foga-probe") {
                     const probe = input.input;
-                    const run = await runProbeIsolated({ worldPath: node.worldPath, rpc: node.rpc, bundlePath: node.bundlePath, input: probe });
+                    const run = await runProbeIsolated({ worldPath: node.worldPath, rpc: node.rpc, bundlePath: node.bundlePath, input: probe, timeoutMs: skillTimeoutMs(node) });
                     answer = run.answer;
                     report = run.report;
                 }
@@ -136,7 +144,7 @@ export const skill_run = {
                             throw new Error("input.document must be a bare file name inside the input directory");
                         documentPath = join(node.inputDir, doc);
                     }
-                    const run = await runExtractIsolated({ documentPath, fieldsPath: join(node.skillsDir, "finch-extract-verify", "fields.json"), packageHash: skill.packageHash, inputDir, skillsDir: node.skillsDir });
+                    const run = await runExtractIsolated({ documentPath, fieldsPath: join(node.skillsDir, "finch-extract-verify", "fields.json"), packageHash: skill.packageHash, inputDir, skillsDir: node.skillsDir, timeoutMs: skillTimeoutMs(node) });
                     answer = run.canonical;
                     report = run.report;
                 }
@@ -215,7 +223,12 @@ export const tender_settle = {
             gates.push(refused("policy", "past settleBy"));
         const jobId = input.jobId ?? `${tenderJobId(id, view.facts.completions)}:settle`;
         const intent = { target: k.tenders.address, value: 0n, data: k.tenders.encodeSettle(id, sid, proof), label: `settleFulfillment(${input.tokenId}, ${input.submissionId})` };
-        const before = await node.body.balance();
+        // What the settlement pays is measured on the tender — the escrow it releases less what it leaves as credit —
+        // not as the account's net balance change: between the read before and the read after, another flow on the
+        // account (a tender the cell is minting, a withdrawal landing, a watcher's settlement of another tender) would
+        // leak into a balance delta and the evidence would record a reward the chain paid in full as a fraction of it.
+        // A rejected settlement releases the escrow to the demander and pays the cell nothing.
+        const [escrowBefore, creditBefore] = await Promise.all([k.tenders.escrowBalanceOf(id), k.tenders.creditOf(id, node.body.address)]);
         return {
             job: { id: jobId, kind: "tender-settle", input: { tokenId: input.tokenId, submissionId: input.submissionId, proofHash: sha256Hex(proof) } },
             gates,
@@ -223,8 +236,11 @@ export const tender_settle = {
             steps: [{ name: "settle", kind: "plain", build: () => intent }],
             output: async (confirmed) => {
                 const c = confirmed[0];
-                const [after, credit, s] = await Promise.all([node.body.balance(), k.tenders.creditOf(id, node.body.address), k.tenders.submissionOf(id, sid)]);
-                return { tokenId: input.tokenId, submissionId: input.submissionId, txHash: c.txHash, operationId: `job:${jobId}:settle`, jobId, paidWei: (after > before ? after - before : 0n).toString(), creditWei: credit.toString(), status: s.status };
+                const [escrowAfter, creditAfter, s] = await Promise.all([k.tenders.escrowBalanceOf(id), k.tenders.creditOf(id, node.body.address), k.tenders.submissionOf(id, sid)]);
+                const released = escrowBefore > escrowAfter ? escrowBefore - escrowAfter : 0n;
+                const credited = creditAfter > creditBefore ? creditAfter - creditBefore : 0n;
+                const paid = s.status === SubmissionStatus.Accepted && released > credited ? released - credited : 0n;
+                return { tokenId: input.tokenId, submissionId: input.submissionId, txHash: c.txHash, operationId: `job:${jobId}:settle`, jobId, paidWei: paid.toString(), creditWei: creditAfter.toString(), status: s.status };
             },
         };
     },

package/dist/util/version.js

@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { repoRoot } from "./fs.js";
+/** The npm package name (the binary stays `foga`; the scope is `finchip.ai`). */
+export const PACKAGE_NAME = "@finchip.ai/foga";
 /** The package version, read once from package.json (the same file the npm package ships). */
 export const version = (() => {
     try {

package/dist/world/sourcify.js

@@ -0,0 +1,165 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadBundle } from "../bundle/load.js";
+import { readJson, repoRoot } from "../util/fs.js";
+/**
+ * Source verification on Sourcify (design memo, section 8, the 2c leftover, and section 9, 3d-2): every contract a world deployed
+ * from the bundle is submitted with the very standard JSON input its compiler run took — the `build-info` files
+ * `forge build` leaves beside the artifacts (`.foga-build/out/<repo>/build-info/`, written by `npm run bundle:verify`
+ * and `foga build`) — the compiler version from the contract's metadata, and the creation transaction the world file
+ * recorded. Nothing is recompiled or rewritten for the verifier: what Sourcify checks is what the bundle was built
+ * from, at the locked commits. A dry run writes each request to a file instead of sending it; a chain Sourcify does
+ * not serve (anvil's 31337) is always a dry run.
+ */
+export const SOURCIFY_SERVER = "https://sourcify.dev/server";
+/** Every full build-info file under the work directory, by repository. */
+export function collectBuildInfo(outRoot = join(repoRoot(), ".foga-build", "out")) {
+    const out = [];
+    if (!existsSync(outRoot))
+        return out;
+    for (const repo of readdirSync(outRoot)) {
+        const dir = join(outRoot, repo, "build-info");
+        if (!existsSync(dir))
+            continue;
+        for (const name of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
+            const b = JSON.parse(readFileSync(join(dir, name), "utf8"));
+            if (!b.input || !b.output?.contracts)
+                continue; // a minimal build-info (no --build-info): nothing to submit
+            out.push({ file: join(dir, name), repo, solcVersion: b.solcLongVersion ?? b.solcVersion ?? "", input: b.input, output: b.output });
+        }
+    }
+    return out;
+}
+function normalizeCode(hex) {
+    return (hex ?? "").toLowerCase().replace(/^0x/, "");
+}
+/** The compiler's long version (0.8.28+commit.7893614a) from a contract's metadata, the build-info's otherwise. */
+function compilerVersionOf(meta, fallback) {
+    try {
+        const m = JSON.parse(meta ?? "{}");
+        return m.compiler?.version ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * The verification requests of a world: for every step the world deployed from the bundle, the build-info whose
+ * output holds a contract of that name in that repository with the bundle's runtime code, the path solc saw as the
+ * identifier.
+ */
+export function verificationRequests(world, infos, o = {}) {
+    const bundle = loadBundle();
+    const requests = [];
+    const missing = [];
+    for (const step of world.steps.filter((s) => s.status === "deployed")) {
+        if (o.only && !o.only.includes(step.id))
+            continue;
+        const entry = world.contracts[step.id];
+        if (!entry?.address || !entry.bundleKey) {
+            missing.push({ id: step.id, reason: "the world file names no address or bundle key for this step" });
+            continue;
+        }
+        const contract = bundle.contracts[entry.bundleKey];
+        if (!contract) {
+            missing.push({ id: step.id, reason: `bundle key ${entry.bundleKey} is not in the committed bundle` });
+            continue;
+        }
+        const [repo, name] = entry.bundleKey.split(":");
+        const wanted = normalizeCode(contract.deployedBytecode);
+        let found = null;
+        for (const info of infos.filter((i) => i.repo === repo)) {
+            for (const [path, byName] of Object.entries(info.output.contracts)) {
+                const c = byName[name];
+                if (!c)
+                    continue;
+                const code = normalizeCode(c.evm?.deployedBytecode?.object);
+                // immutables and the metadata hash make exact equality too strict only when they differ; the bundle was built the same way, so equality is the check
+                if (code && wanted && code !== wanted)
+                    continue;
+                found = { id: step.id, address: entry.address, bundleKey: entry.bundleKey, creationTransactionHash: step.txHash ?? null, contractIdentifier: `${path}:${name}`, compilerVersion: compilerVersionOf(c.metadata, info.solcVersion), buildInfo: info.file, stdJsonInput: info.input };
+                break;
+            }
+            if (found)
+                break;
+        }
+        if (!found)
+            missing.push({ id: step.id, reason: `no build-info under .foga-build/out/${repo}/build-info holds ${name} with the bundle's runtime code (run npm run bundle:verify to produce the build-info files)` });
+        else
+            requests.push(found);
+    }
+    return { requests, missing };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Verify a world's deployed contracts on Sourcify, or write what would be sent. */
+export async function verifyWorld(o) {
+    const log = o.log ?? (() => { });
+    const world = readJson(resolve(o.worldPath));
+    const server = (o.server ?? SOURCIFY_SERVER).replace(/\/+$/, "");
+    const served = ![31337, 1337].includes(world.chainId);
+    const dryRun = o.dryRun ?? !served;
+    if (!served && !dryRun)
+        throw new Error(`chain ${world.chainId} is a local chain Sourcify does not serve; use --dry-run`);
+    const infos = collectBuildInfo(o.buildInfoRoot);
+    const { requests, missing } = verificationRequests(world, infos, { only: o.only });
+    const outDir = resolve(o.outDir ?? join(repoRoot(), ".foga-build", "sourcify", world.name));
+    mkdirSync(outDir, { recursive: true });
+    const f = o.fetchImpl ?? fetch;
+    const results = [];
+    log(`sourcify: world ${world.worldId} (chain ${world.chainId}): ${requests.length} contract(s) to verify, ${missing.length} without a build-info; ${dryRun ? "dry run" : server}`);
+    for (const r of requests) {
+        const body = { stdJsonInput: r.stdJsonInput, compilerVersion: r.compilerVersion, contractIdentifier: r.contractIdentifier, ...(r.creationTransactionHash ? { creationTransactionHash: r.creationTransactionHash } : {}) };
+        const file = join(outDir, `${r.id.replace(/[^A-Za-z0-9._-]+/g, "_")}.json`);
+        writeFileSync(file, JSON.stringify({ chainId: world.chainId, address: r.address, ...body }, null, 2) + "\n");
+        if (dryRun) {
+            results.push({ id: r.id, address: r.address, contractIdentifier: r.contractIdentifier, compilerVersion: r.compilerVersion, outcome: "dry-run", detail: `request written to ${file}` });
+            continue;
+        }
+        try {
+            const existing = await f(`${server}/v2/contract/${world.chainId}/${r.address}`, { signal: AbortSignal.timeout(30_000) });
+            if (existing.ok) {
+                const e = (await existing.json());
+                if (e.match === "exact_match" || e.match === "match") {
+                    results.push({ id: r.id, address: r.address, contractIdentifier: r.contractIdentifier, compilerVersion: r.compilerVersion, outcome: "already", detail: `already verified (${e.match})`, creationMatch: e.creationMatch ?? null, runtimeMatch: e.runtimeMatch ?? null });
+                    log(`  ${r.id}: already verified (${e.match})`);
+                    continue;
+                }
+            }
+            const submitted = await f(`${server}/v2/verify/${world.chainId}/${r.address}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(120_000) });
+            const ticket = (await submitted.json());
+            if (!submitted.ok || !ticket.verificationId) {
+                results.push({ id: r.id, address: r.address, contractIdentifier: r.contractIdentifier, compilerVersion: r.compilerVersion, outcome: "error", detail: `HTTP ${submitted.status}: ${ticket.customCode ?? ""} ${ticket.message ?? ""}`.trim() });
+                log(`  ${r.id}: refused — HTTP ${submitted.status} ${ticket.customCode ?? ""} ${ticket.message ?? ""}`);
+                continue;
+            }
+            const started = Date.now();
+            let outcome = null;
+            while (Date.now() - started < (o.timeoutMs ?? 300_000)) {
+                await sleep(o.pollMs ?? 3000);
+                const status = await f(`${server}/v2/verify/${ticket.verificationId}`, { signal: AbortSignal.timeout(30_000) });
+                const job = (await status.json());
+                if (!job.isJobCompleted)
+                    continue;
+                if (job.error)
+                    outcome = { id: r.id, address: r.address, contractIdentifier: r.contractIdentifier, compilerVersion: r.compilerVersion, outcome: "failed", detail: `${job.error.customCode ?? ""} ${job.error.message ?? ""}`.trim(), verificationId: ticket.verificationId };
+                else
+                    outcome = { id: r.id, address: r.address, contractIdentifier: r.contractIdentifier, compilerVersion: r.compilerVersion, outcome: job.contract?.match === "exact_match" ? "exact_match" : "match", detail: `creation ${job.contract?.creationMatch ?? "-"}, runtime ${job.contract?.runtimeMatch ?? "-"}`, verificationId: ticket.verificationId, creationMatch: job.contract?.creationMatch ?? null, runtimeMatch: job.contract?.runtimeMatch ?? null };
+                break;
+            }
+            if (!outcome)
+                outcome = { id: r.id, address: r.address, contractIdentifier: r.contractIdentifier, compilerVersion: r.compilerVersion, outcome: "error", detail: `verification ${ticket.verificationId} did not complete in time; check ${server}/v2/verify/${ticket.verificationId}`, verificationId: ticket.verificationId };
+            results.push(outcome);
+            log(`  ${r.id}: ${outcome.outcome} — ${outcome.detail}`);
+        }
+        catch (e) {
+            results.push({ id: r.id, address: r.address, contractIdentifier: r.contractIdentifier, compilerVersion: r.compilerVersion, outcome: "error", detail: e.message });
+            log(`  ${r.id}: error — ${e.message}`);
+        }
+    }
+    const summary = {};
+    for (const r of results)
+        summary[r.outcome] = (summary[r.outcome] ?? 0) + 1;
+    const report = { schema: "foga.sourcify/1", worldId: world.worldId, chainId: world.chainId, server, dryRun, at: new Date().toISOString(), results, missing, summary };
+    writeFileSync(join(outDir, "report.json"), JSON.stringify(report, null, 2) + "\n");
+    return { report, outDir };
+}

package/docs/a2a.md

@@ -0,0 +1,31 @@
+# A2A (POST /a2a, /.well-known/agent-card.json)
+
+The fourth entrance (design memo, sections 7 and 9, 3d-2): the Agent2Agent protocol at version 1.0, the JSON-RPC binding only, on the node's HTTP server. Like MCP and the HTTP API it adds no rule of its own: an inbound message becomes work the catalog judges as the caller, and the economics stay on chain.
+
+## The card
+
+`GET /.well-known/agent-card.json` is the AgentCard (A2A 1.0, section 4.4), one of the documents `foga cell docs build` writes from the configuration (docs/documents.md): `name`, `description`, `supportedInterfaces: [{url: <publicUrl>/a2a, protocolBinding: "JSONRPC", protocolVersion: "1.0"}]` (empty until the cell has a public URL — the caller then uses the URL it knows), `provider` (`presence.provider`), `version` (the package's), `capabilities: {streaming: false, pushNotifications: false, extendedAgentCard: false}`, `securitySchemes` (`api-key`: `Bearer`; `wallet-signature`: `FOGA-EIP712`, docs/wallet.md), `defaultInputModes: ["text/plain", "application/json"]`, `defaultOutputModes: ["application/json", "text/plain"]`, and `skills`: the ERC-8338 skills the policy offers (`skills.offered`), each `id` the package name at its version, with two examples — a quote and a tender — as data parts. Not the token list, not a promise of anything the policy would refuse. The card is not signed (JWS stays for later).
+
+## The binding
+
+`POST /a2a` with `Content-Type: application/json` and `A2A-Version: 1.0` (or `?A2A-Version=1.0`); a JSON-RPC 2.0 request whose `method` is `SendMessage`, `GetTask`, `ListTasks` or `CancelTask`. An empty version is 0.3 by the specification and this agent does not speak it: `VersionNotSupportedError` (-32009). `SendStreamingMessage`, `SubscribeToTask` and `GetExtendedAgentCard` are `UnsupportedOperationError` (-32004), the push-notification methods `PushNotificationNotSupportedError` (-32003), anything else `MethodNotFoundError` (-32601); the error codes and their `data` (`google.rpc.ErrorInfo` with `reason`, `domain`, `metadata`) follow sections 5.4 and 9.5. Field names are camelCase and enums are their Protocol Buffer names (`TASK_STATE_COMPLETED`, `ROLE_USER`), as the specification prescribes for every JSON binding. Credentials are the HTTP server's (`Authorization`: nothing, a Bearer key, or a wallet signature); the caller a message comes from is what the node's access policy makes of them.
+
+## Two roads
+
+A message's data part may carry a `foga` object; a message of words is a quote.
+
+**Quote** — `{"foga": {"mode": "quote", "skill": "foga-probe", "input": {…}}}`, or any text. Open to anyone. The task completes at once with a `quote` artifact: the cell's offered skills (name, version, package hash, token id, summary), the terms a tender needs to meet (the acceptance authority — the world's hashlock verifier — the reward floor, the submit and settle windows, the counterparty level), and how to proceed. A skill the cell does not offer is `TASK_STATE_REJECTED` with the list of what it does. Nothing runs and nothing touches the chain.
+
+**Tender** — `{"foga": {"mode": "tender", "tokenId": "23"}}`, naming an ERC-8414 tender that exists, is funded, and has its answer committed to the hashlock verifier (the caller minted it for its own account — `tender_mint_build` gives the calls — or anyone did). The caller needs the act level: an API key the operator issued, or a wallet signature the cell's policy grants act to (with a request-bound envelope). The public is told to quote (`TASK_STATE_REJECTED`, gate `permission`). Without a `tokenId` the task waits (`TASK_STATE_INPUT_REQUIRED`) and a message with the `taskId` continues it. With one, the response is the task in `TASK_STATE_WORKING` and the work goes on after it (section 3.3.3): `tender_precheck`, then `skill_run` with the task document's input, then `tender_submit` — each through `Catalog.invoke` as the A2A caller, each a decision record under the caller's id. The task ends `TASK_STATE_COMPLETED` with a `submission` artifact (token id, result hash, answer hash, submission id, transaction hash, job and decision ids, the operations), `TASK_STATE_REJECTED` when a gate refused (the gate, the reason and the decision id in the status message's data part), or `TASK_STATE_FAILED` when the run failed. Settlement and withdrawal are the node's watchers' duty afterwards, as for every submission; the caller does not pay the cell through A2A and the cell does not pay the caller: the tender's escrow pays the account.
+
+There is no road that does work first and talks about payment after, and no road that mints or funds a tender on the caller's behalf (who pays and who approves would need an authority this version does not define).
+
+## Tasks
+
+A task lives in the cell's store (`a2a.task.<id>` among the facts): visible to the caller that made it and to the operator's view, never to another caller (`GetTask` answers `TaskNotFoundError` rather than reveal it exists). The same `messageId` from the same caller is the same task (section 3.3.1). A message to a terminal task is `UnsupportedOperationError`. `ListTasks` pages one's own tasks (`pageSize` 1–100, `pageToken` as an offset, `status` and `contextId` filters, `includeArtifacts`); `CancelTask` ends a task that has not started working, asks a working one to stop between its steps, and refuses (`TaskNotCancelableError`) once the submission is broadcast or the task is terminal: what reached the chain stays.
+
+## What the memo's v0.2 asked and where it landed
+
+The signature covers the request content (the request-bound envelope hashes method, path and body); the request right and the act right are separate (a grant decides the level; the cell's own rules decide the act); task and operation are layered (one task, the catalog's jobs beneath it, named in the artifact); only existing, funded tenders are taken; duplicates are detected by (caller, messageId); `CancelTask` undoes nothing broadcast; the content type is `application/json`; `ListTasks` is implemented and scoped to the caller; `supportedInterfaces` lists the one binding; the data types are the proto's names and shapes (`src/a2a/types.ts`). Outbound A2A — the node calling other agents — is not in this phase: the node's work comes from the chain.
+
+`test/a2a.test.ts` drives all of it on anvil with a raw JSON-RPC client; `foga quickstart` checks the card and a quote on every run.