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

package/dist/node/documents.js

@@ -0,0 +1,298 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildAgentCard, endpointsOf } from "../a2a/card.js";
+import { AID } from "../core/aid.js";
+import { agentDescriptor, descriptorHash } from "../core/ard.js";
+import { accountRef, dataUri, dataUriJcs, keccakJcs } from "../core/canonical.js";
+import { cellUnitDefinition } from "../core/units.js";
+import { repoRoot } from "../util/fs.js";
+import { configPath } from "./config.js";
+/**
+ * One configuration, several documents (design memo, Phase 3, section 7): everything the cell says about itself to
+ * the outside is generated from `cell.config.json` and the chain — the ERC-8004 registration file, the ERC-8434
+ * AID document, the ERC-8444 agent descriptor, the ERC-8454 unit definition, the A2A agent card and the MCP
+ * registry manifest — each in its own file with only the fields its standard prescribes, the shared metadata
+ * (version, content hash, built time) in `manifest.json` beside them. `foga cell docs build` writes them under the
+ * configuration's documents directory; the node serves them (`/documents/<file>`, `/.well-known/agent-card.json`,
+ * `/.well-known/agent-registration.json`); `foga cell docs publish` commits what changed on chain and reads it back.
+ */
+export const DOCUMENTS_SCHEMA = "foga.documents/1";
+export const DOCUMENT_FILES = {
+    registration: "registration.json",
+    aidDocument: "aid-document.json",
+    ardAgent: "ard-agent.json",
+    aufUnit: "auf-unit.json",
+    agentCard: "agent-card.json",
+    serverJson: "server.json",
+};
+/** The directory the documents live in: runtime.http.documentsDir, relative to the configuration's directory. */
+export function documentsDir(node) {
+    return configPath(node.loaded, node.config.runtime.http.documentsDir);
+}
+/** The URI a document is published under: the public URL when the node has one, the document itself (data:) otherwise. */
+export function documentUri(node, file, doc) {
+    const base = node.config.runtime.http.publicUrl?.replace(/\/+$/, "");
+    if (!base)
+        return dataUri(doc);
+    if (file === DOCUMENT_FILES.registration)
+        return `${base}/.well-known/agent-registration.json`;
+    if (file === DOCUMENT_FILES.agentCard)
+        return `${base}/.well-known/agent-card.json`;
+    return `${base}/documents/${file}`;
+}
+/** The ERC-8004 registration file (registration-v1) of the cell, from its configuration. */
+export function buildRegistration(node) {
+    const cfg = node.config;
+    const chainId = node.chainId;
+    const endpoints = endpointsOf(node);
+    const account = cfg.identity.account;
+    const services = [
+        ...(endpoints.mcp ? [{ name: "MCP", endpoint: endpoints.mcp, version: "2026-07-28" }] : []),
+        ...(endpoints.a2a ? [{ name: "A2A", endpoint: endpoints.a2a, version: "1.0" }] : []),
+        ...(endpoints.web ? [{ name: "web", endpoint: endpoints.web }] : []),
+    ];
+    return {
+        type: "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
+        name: cfg.presence.name,
+        description: cfg.presence.description,
+        ...(cfg.presence.image ? { image: cfg.presence.image } : {}),
+        services,
+        ...(cfg.identity.agentId ? { registrations: [{ agentId: Number(cfg.identity.agentId), agentRegistry: `eip155:${chainId}:${node.kernel.identity.address.toLowerCase()}` }] } : {}),
+        x402Support: false,
+        active: true,
+        supportedTrust: ["reputation"],
+        "x-foga": { cell: cfg.name, anchor: accountRef(chainId, account), ...(cfg.identity.bindingId ? { binding: cfg.identity.bindingId } : {}), ...(cfg.identity.safety.specId ? { specification: cfg.identity.safety.specId } : {}) },
+    };
+}
+/** The AID document: the identity facet over the registration, the standing facet when attested, the skills facet, the endpoints facet. */
+export async function buildAidDocument(node, registration) {
+    const cfg = node.config;
+    const k = node.kernel;
+    const chainId = node.chainId;
+    const account = cfg.identity.account;
+    const self = accountRef(chainId, account);
+    const agentId = cfg.identity.agentId ? Number(cfg.identity.agentId) : undefined;
+    const facets = [{ facetType: "aid:core/identity/v1", provenance: "SELF", issuer: self, validUntil: 0, digest: keccakJcs(registration), access: { mode: "PUBLIC" }, resolver: { kind: "erc8004-identity", chainId, registry: k.identity.address, ...(agentId !== undefined ? { agentId } : {}) } }];
+    if (cfg.identity.standing) {
+        try {
+            const subject = (await import("../core/kya.js")).accountSubject(chainId, account);
+            const r = await k.kya.resolve(subject, cfg.identity.standing.schemeId, cfg.identity.standing.issuers);
+            if (r.level > 0)
+                facets.push({ facetType: "aid:core/kya/v1", provenance: "ATTESTED", issuer: accountRef(chainId, cfg.identity.standing.issuers[0]), validUntil: Number(r.expiresAt), digest: r.assertionId, access: { mode: "PUBLIC" }, resolver: { kind: "erc8419-assertion", chainId, registry: k.kya.registryAddress, schemeId: cfg.identity.standing.schemeId, issuers: cfg.identity.standing.issuers, assertionId: r.assertionId, level: r.level } });
+        }
+        catch {
+            /* no standing readable: no facet */
+        }
+    }
+    const held = Object.entries(cfg.skills.held);
+    if (held.length) {
+        const skills = Object.fromEntries(held.map(([name, h]) => [name, { tokenId: h.tokenId, packageHash: h.packageHash ?? null, offered: cfg.skills.offered.includes(name) }]));
+        facets.push({ facetType: "aid:skills/erc8338/v1", provenance: "SELF", issuer: self, validUntil: 0, digest: keccakJcs(skills), access: { mode: "PUBLIC" }, resolver: { kind: "erc8338-skill", chainId, registry: k.skills.address, tokenIds: held.map(([, h]) => h.tokenId) } });
+    }
+    const endpoints = endpointsOf(node);
+    if (endpoints.mcp || endpoints.a2a || endpoints.web) {
+        const ep = { mcp: endpoints.mcp, a2a: endpoints.a2a, web: endpoints.web };
+        facets.push({ facetType: "aid:endpoints/v1", provenance: "SELF", issuer: self, validUntil: 0, digest: keccakJcs(ep), access: { mode: "PUBLIC" }, resolver: { kind: "foga-endpoints", ...ep } });
+    }
+    return {
+        version: "aid-document/v1",
+        aid: self,
+        did: `did:aid:${self}`,
+        ...(agentId !== undefined ? { binding: { registry: k.identity.address, agentId } } : {}),
+        livenessWindow: cfg.identity.livenessWindow ?? Number(node.world.file.params.aid.defaultLivenessWindow),
+        facets,
+    };
+}
+/** The MCP registry manifest for this cell: the package's server.json with this cell's remote. */
+export function buildServerJson(node, version) {
+    const template = JSON.parse(readFileSync(join(repoRoot(), "server.json"), "utf8"));
+    const endpoints = endpointsOf(node);
+    const remotes = endpoints.mcp ? [{ type: "streamable-http", url: endpoints.mcp, headers: [{ name: "Authorization", description: "Bearer <key> for acts (foga node key new), or a FOGA-EIP712 envelope signed by your wallet; reads and builds need none", isRequired: false, isSecret: true }] }] : [];
+    return { ...template, description: `${node.config.presence.name}: a FOGA cell on ${node.world.file.network} (chain ${node.chainId}); reads, dry runs and builds for the public, acts by key or signature`.slice(0, 100), version, remotes };
+}
+/** Build every document from the configuration and the chain and write them, with the manifest, under the documents directory. */
+export async function buildDocuments(node, o) {
+    const cfg = node.config;
+    if (!cfg.identity.account)
+        throw new Error("the cell is not born: no account in the configuration (foga cell init first)");
+    const dir = resolve(o.dir ?? documentsDir(node));
+    mkdirSync(dir, { recursive: true });
+    const registration = buildRegistration(node);
+    const aidDocument = await buildAidDocument(node, registration);
+    const chainId = node.chainId;
+    const endpoints = endpointsOf(node);
+    const offered = cfg.skills.offered.map((s) => `erc8338:${s}`);
+    const ardAgent = agentDescriptor({ chainId, anchor: cfg.identity.account, slug: `cell-${cfg.name.toLowerCase()}`, name: cfg.presence.name, description: cfg.presence.description, url: endpoints.web ?? undefined, capabilities: ["erc8414:fulfiller", "erc8338:holder", ...offered], registration: cfg.identity.agentId ? { registry: `eip155:${chainId}:${node.kernel.identity.address.toLowerCase()}`, agentId: cfg.identity.agentId } : undefined, domain: cfg.runtime.http.publicUrl ? new URL(cfg.runtime.http.publicUrl).hostname : undefined });
+    const aufUnit = cellUnitDefinition({ chainId, cell: cfg.identity.account, name: cfg.presence.name, summary: cfg.presence.description || undefined });
+    const agentCard = await buildAgentCard(node, { version: o.version });
+    const serverJson = buildServerJson(node, o.version);
+    const previous = readManifest(dir);
+    const docs = { [DOCUMENT_FILES.registration]: registration, [DOCUMENT_FILES.aidDocument]: aidDocument, [DOCUMENT_FILES.ardAgent]: ardAgent, [DOCUMENT_FILES.aufUnit]: aufUnit, [DOCUMENT_FILES.agentCard]: agentCard, [DOCUMENT_FILES.serverJson]: serverJson };
+    const standards = { [DOCUMENT_FILES.registration]: "ERC-8004 registration-v1", [DOCUMENT_FILES.aidDocument]: "ERC-8434 aid-document/v1", [DOCUMENT_FILES.ardAgent]: "ERC-8444 agent descriptor", [DOCUMENT_FILES.aufUnit]: "ERC-8454 unit definition", [DOCUMENT_FILES.agentCard]: "A2A 1.0 AgentCard", [DOCUMENT_FILES.serverJson]: "MCP registry server.json (2025-12-11)" };
+    const entries = {};
+    let changed = !previous;
+    for (const [file, doc] of Object.entries(docs)) {
+        const text = JSON.stringify(doc, null, 2) + "\n";
+        writeFileSync(join(dir, file), text);
+        const contentHash = keccakJcs(doc);
+        entries[file] = { file, contentHash, bytes: Buffer.byteLength(text), standard: standards[file] };
+        if (previous && previous.documents[file]?.contentHash !== contentHash)
+            changed = true;
+    }
+    const manifest = {
+        schema: DOCUMENTS_SCHEMA,
+        cell: cfg.name,
+        account: cfg.identity.account,
+        agentId: cfg.identity.agentId ?? null,
+        chainId,
+        version: previous ? (changed ? previous.version + 1 : previous.version) : 1,
+        builtAt: new Date().toISOString(),
+        publicUrl: cfg.runtime.http.publicUrl ?? null,
+        documents: entries,
+    };
+    writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    return { dir, manifest, registration, aidDocument, ardAgent, aufUnit, agentCard, serverJson };
+}
+export function readManifest(dir) {
+    try {
+        const m = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
+        return m.schema === DOCUMENTS_SCHEMA ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The documents as built, read back from their directory (for the node to serve and for a publish). */
+export function readBuilt(dir) {
+    const manifest = readManifest(dir);
+    if (!manifest)
+        return null;
+    const read = (file) => JSON.parse(readFileSync(join(dir, file), "utf8"));
+    return { dir, manifest, registration: read(DOCUMENT_FILES.registration), aidDocument: read(DOCUMENT_FILES.aidDocument), ardAgent: read(DOCUMENT_FILES.ardAgent), aufUnit: read(DOCUMENT_FILES.aufUnit), agentCard: read(DOCUMENT_FILES.agentCard), serverJson: read(DOCUMENT_FILES.serverJson) };
+}
+/** What the chain holds now for the four commitments. */
+export async function onChainState(node) {
+    const cfg = node.config;
+    const k = node.kernel;
+    const account = cfg.identity.account;
+    const agentURI = cfg.identity.agentId ? await k.identity.contract().tokenURI(BigInt(cfg.identity.agentId)).catch(() => null) : null;
+    const aid = await k.aid.documentURI(account).catch(() => null);
+    const ard = cfg.identity.recordId ? await k.ard.recordOf(cfg.identity.recordId).then((r) => ({ descriptorHash: r.descriptorHash, descriptorURI: r.descriptorURI })).catch(() => null) : null;
+    let unit = null;
+    if (cfg.identity.unitId) {
+        try {
+            const id = BigInt(cfg.identity.unitId);
+            const version = await k.units.latestVersion(id);
+            const v = await k.units.versionOf(id, version);
+            unit = { version, boundaryHash: v.boundaryHash };
+        }
+        catch {
+            unit = null;
+        }
+    }
+    return { agentURI, aid, ard, unit };
+}
+/** The on-chain steps a publish needs: each commitment that differs from what the chain holds; nothing for one that matches. */
+export async function publishSteps(node, built) {
+    const cfg = node.config;
+    const k = node.kernel;
+    const state = await onChainState(node);
+    const steps = [];
+    const unchanged = [];
+    if (cfg.identity.agentId) {
+        const uri = documentUri(node, DOCUMENT_FILES.registration, built.registration);
+        if (state.agentURI === uri)
+            unchanged.push("identity-uri");
+        else
+            steps.push({ name: "identity-uri", target: k.identity.address, data: k.identity.contract().interface.encodeFunctionData("setAgentURI", [BigInt(cfg.identity.agentId), uri]), label: `setAgentURI(${cfg.identity.agentId}, ${uri.slice(0, 60)}${uri.length > 60 ? "…" : ""})`, expect: { uri } });
+    }
+    {
+        const c = AID.documentCommitment(built.aidDocument);
+        const uri = cfg.runtime.http.publicUrl ? documentUri(node, DOCUMENT_FILES.aidDocument, built.aidDocument) : c.uri;
+        if (state.aid && state.aid.digest.toLowerCase() === c.digest.toLowerCase() && state.aid.uri === uri)
+            unchanged.push("aid-document");
+        else
+            steps.push({ name: "aid-document", target: k.aid.address, data: k.aid.encodeSetDocumentURI(uri, c.digest), label: `setDocumentURI(${uri.slice(0, 60)}${uri.length > 60 ? "…" : ""}, ${c.digest.slice(0, 10)}…)`, expect: { uri, digest: c.digest } });
+    }
+    if (cfg.identity.recordId) {
+        const p = descriptorHash(built.ardAgent);
+        if (state.ard && state.ard.descriptorHash.toLowerCase() === p.hex.toLowerCase())
+            unchanged.push("ard-descriptor");
+        else
+            steps.push({ name: "ard-descriptor", target: k.ard.address, data: k.ard.encodeUpdateDescriptor(cfg.identity.recordId, built.ardAgent), label: `updateDescriptor(${cfg.identity.recordId.slice(0, 10)}…, ${p.hex.slice(0, 10)}…)`, expect: { hash: p.hex } });
+    }
+    if (cfg.identity.unitId) {
+        const hash = k.units.boundaryHash(built.aufUnit);
+        if (state.unit && state.unit.boundaryHash.toLowerCase() === hash.toLowerCase())
+            unchanged.push("unit-version");
+        else
+            steps.push({ name: "unit-version", target: k.units.registryAddress, data: k.units.registry().interface.encodeFunctionData("publishVersion", [BigInt(cfg.identity.unitId), hash, dataUriJcs(built.aufUnit), []]), label: `publishVersion(${cfg.identity.unitId}, ${hash.slice(0, 10)}…)`, expect: { hash } });
+    }
+    return { steps, unchanged };
+}
+/** After a publish: what the chain holds against what was built; a URL is fetched when it can be. */
+export async function readBack(node, built, o = {}) {
+    const cfg = node.config;
+    const k = node.kernel;
+    const rows = [];
+    const state = await onChainState(node);
+    let lastFetchProblem = "";
+    const fetchJson = async (url) => {
+        if (!url.startsWith("http"))
+            return null;
+        if (o.fetchUrls === false) {
+            lastFetchProblem = "not fetched";
+            return null;
+        }
+        try {
+            const r = await fetch(url, { signal: AbortSignal.timeout(o.timeoutMs ?? 5000) });
+            if (!r.ok) {
+                lastFetchProblem = `HTTP ${r.status}`;
+                return null;
+            }
+            return await r.json();
+        }
+        catch (e) {
+            lastFetchProblem = e.message;
+            return null;
+        }
+    };
+    if (cfg.identity.agentId) {
+        const expected = documentUri(node, DOCUMENT_FILES.registration, built.registration);
+        if (!state.agentURI)
+            rows.push({ commitment: "ERC-8004 agentURI", ok: false, detail: "no tokenURI readable" });
+        else if (state.agentURI !== expected)
+            rows.push({ commitment: "ERC-8004 agentURI", ok: false, detail: `the chain names ${state.agentURI.slice(0, 80)}; built ${expected.slice(0, 80)}` });
+        else {
+            const identityFacet = built.aidDocument.facets.find((f) => f.facetType === "aid:core/identity/v1");
+            const content = state.agentURI.startsWith("data:") ? built.registration : await fetchJson(state.agentURI);
+            if (content === null)
+                rows.push({ commitment: "ERC-8004 agentURI", ok: null, detail: `${state.agentURI} is the committed URI; not read from here (${lastFetchProblem}; the node must serve it)` });
+            else {
+                const digest = keccakJcs(content);
+                rows.push({ commitment: "ERC-8004 agentURI", ok: digest === identityFacet?.digest, detail: digest === identityFacet?.digest ? `the registration read from ${state.agentURI.startsWith("data:") ? "the data URI" : state.agentURI} hashes to the AID identity facet's digest ${digest.slice(0, 10)}…` : `the registration read back hashes to ${digest.slice(0, 10)}…, the AID identity facet says ${identityFacet?.digest.slice(0, 10)}…` });
+            }
+        }
+    }
+    {
+        const c = AID.documentCommitment(built.aidDocument);
+        const ok = Boolean(state.aid && state.aid.digest.toLowerCase() === c.digest.toLowerCase());
+        rows.push({ commitment: "ERC-8434 documentURI", ok, detail: ok ? `digest ${c.digest.slice(0, 10)}… at ${state.aid.uri.slice(0, 60)}${state.aid.uri.length > 60 ? "…" : ""}` : `the chain holds ${state.aid?.digest.slice(0, 10) ?? "nothing"}, built ${c.digest.slice(0, 10)}…` });
+        if (ok && state.aid.uri.startsWith("http")) {
+            const content = await fetchJson(state.aid.uri);
+            if (content !== null)
+                rows.push({ commitment: "ERC-8434 document content", ok: AID.documentCommitment(content).digest.toLowerCase() === c.digest.toLowerCase(), detail: `fetched from ${state.aid.uri}` });
+        }
+    }
+    if (cfg.identity.recordId) {
+        const p = descriptorHash(built.ardAgent);
+        const ok = Boolean(state.ard && state.ard.descriptorHash.toLowerCase() === p.hex.toLowerCase());
+        rows.push({ commitment: "ERC-8444 descriptor", ok, detail: ok ? `descriptorHash ${p.hex.slice(0, 10)}… on record ${cfg.identity.recordId.slice(0, 10)}…` : `the record holds ${state.ard?.descriptorHash.slice(0, 10) ?? "nothing"}, built ${p.hex.slice(0, 10)}…` });
+    }
+    if (cfg.identity.unitId) {
+        const hash = k.units.boundaryHash(built.aufUnit);
+        const ok = Boolean(state.unit && state.unit.boundaryHash.toLowerCase() === hash.toLowerCase());
+        rows.push({ commitment: "ERC-8454 unit version", ok, detail: ok ? `version ${state.unit.version} boundaryHash ${hash.slice(0, 10)}…` : `the latest version holds ${state.unit?.boundaryHash.slice(0, 10) ?? "nothing"}, built ${hash.slice(0, 10)}…` });
+    }
+    return rows;
+}

package/dist/node/preflight.js

@@ -0,0 +1,208 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { formatEther, getAddress } from "ethers";
+import { accountSubject } from "../core/kya.js";
+import { operatorScope } from "../genesis/operator-scope.js";
+import { runExtractIsolated, runProbeIsolated } from "../genesis/skill-runner.js";
+import { documentsDir, readBack, readBuilt } from "./documents.js";
+import { NODE_SCOPE_GROUPS } from "./init.js";
+import { KeyIsolationError, loadOperatorKey } from "./keys.js";
+export async function preflight(node, o = {}) {
+    const rows = [];
+    const row = (area, check, verdict, detail) => rows.push({ area, check, verdict, detail });
+    const cfg = node.config;
+    const k = node.kernel;
+    const env = o.env ?? process.env;
+    // --- the world and the chain
+    try {
+        const net = await k.world.provider.getNetwork();
+        const same = Number(net.chainId) === node.world.file.chainId;
+        row("world", "the RPC serves the world's chain", same ? "Pass" : "Fail", `RPC chain ${net.chainId}, world ${node.world.file.worldId} on chain ${node.world.file.chainId}`);
+    }
+    catch (e) {
+        row("world", "the RPC serves the world's chain", "Fail", `the RPC did not answer: ${e.message}`);
+    }
+    const storeWorld = node.store.getMeta("worldId");
+    row("world", "the store belongs to this world and this account", storeWorld && storeWorld !== node.world.file.worldId ? "Fail" : "Pass", `store ${node.storePath}: world ${storeWorld ?? "(new)"}, account ${node.store.getMeta("cellAccount") ?? "(none yet)"}`);
+    // --- the account and its permissions
+    if (!cfg.identity.account || !node.cell) {
+        row("account", "the cell is born", "Fail", "the configuration names no account (foga cell init)");
+        return finish(node, rows);
+    }
+    const cell = node.body;
+    let version = 1;
+    try {
+        version = Number(await cell.contract().ACCOUNT_VERSION());
+    }
+    catch {
+        version = 1;
+    }
+    row("account", "a revision-2 account (operator allow-list)", version >= 2 ? "Pass" : "Fail", `${cell.address} is revision ${version}${version < 2 ? ": no allow-list; foga cell migrate moves the cell to a revision-2 account" : ""}`);
+    const [owner, operator] = await Promise.all([cell.owner(), cell.operator()]);
+    const rolesOk = getAddress(owner) === getAddress(cfg.identity.owner) && getAddress(operator) === getAddress(cfg.identity.operator);
+    row("account", "the account names the configuration's owner and operator", rolesOk ? "Pass" : "Fail", `owner ${owner}, operator ${operator}`);
+    try {
+        const [anchor, status] = await Promise.all([k.aid.stateName(cell.address), cell.status()]);
+        row("account", "anchor ACTIVE and binding Satisfied", anchor === "ACTIVE" && status.verdictName === "Satisfied" ? "Pass" : anchor === "STALE" ? "Warn" : "Fail", `anchor ${anchor}, binding ${status.verdictName}${status.reasonNames.length ? ` [${status.reasonNames.join(", ")}]` : ""}${anchor === "STALE" ? " (the next heartbeat restores it)" : ""}`);
+    }
+    catch (e) {
+        row("account", "anchor ACTIVE and binding Satisfied", "Fail", e.message);
+    }
+    if (version >= 2) {
+        try {
+            const scope = operatorScope(k, NODE_SCOPE_GROUPS);
+            const missing = [];
+            for (let i = 0; i < scope.targets.length; i++)
+                if (!(await cell.contract().operatorAllowed(scope.targets[i], scope.selectors[i])))
+                    missing.push(scope.names[i]);
+            row("account", "the operator allow-list covers the node's capabilities", missing.length ? "Fail" : "Pass", missing.length ? `${missing.length} of ${scope.names.length} missing: ${missing.join(", ")} (the owner adds them with setOperatorAllowedBatch; a cell born before they were part of the scope)` : `${scope.names.length} (target, selector) pairs allowed`);
+        }
+        catch (e) {
+            row("account", "the operator allow-list covers the node's capabilities", "NotTested", e.message);
+        }
+    }
+    try {
+        const [valueCap, balance] = await Promise.all([cell.contract().operatorDailyValueCap?.().catch(() => null), k.balance(cell.address)]);
+        const budget = BigInt(cfg.policy.budget.dailyValueWei);
+        const perOp = BigInt(cfg.policy.budget.perOperationValueWei);
+        row("budget", "the policy's caps are consistent", perOp <= budget && BigInt(cfg.policy.budget.dailyGasWei) > 0n ? "Pass" : "Fail", `per operation ${formatEther(perOp)} ETH <= daily ${formatEther(budget)} ETH; gas ${formatEther(BigInt(cfg.policy.budget.dailyGasWei))} ETH a day`);
+        row("budget", "the account holds working capital", balance > 0n ? "Pass" : "Warn", `${formatEther(balance)} ETH on the account${valueCap !== null && valueCap !== undefined ? `; the account's own daily value cap ${formatEther(BigInt(valueCap))} ETH` : ""}`);
+    }
+    catch (e) {
+        row("budget", "the policy's caps are consistent", "NotTested", e.message);
+    }
+    // --- the operator key: this environment's, alone; the address the account names; gas for its acts
+    try {
+        const key = loadOperatorKey(env);
+        const match = getAddress(key.address) === getAddress(cfg.identity.operator);
+        row("keys", "the operator key is here, alone, and is the account's operator", match ? "Pass" : "Fail", `${key.address} from ${key.source.kind === "file" ? key.source.path : key.source.name}${match ? "" : `; the account names ${cfg.identity.operator}`}`);
+        const gas = await k.balance(key.address);
+        const floor = BigInt(cfg.policy.budget.dailyGasWei) / 4n;
+        row("keys", "the operator holds gas (a quarter of the daily gas budget at least)", gas >= floor ? "Pass" : "Fail", `${formatEther(gas)} ETH (floor ${formatEther(floor)} ETH); the catalog refuses commitments below the floor`);
+    }
+    catch (e) {
+        row("keys", "the operator key is here, alone, and is the account's operator", e instanceof KeyIsolationError ? "Fail" : "NotTested", e.message);
+    }
+    for (const role of ["owner", "guardian"]) {
+        const names = { inline: `FOGA_${role.toUpperCase()}_KEY`, file: `FOGA_${role.toUpperCase()}_KEY_FILE` };
+        if (env[names.inline] || env[names.file])
+            row("keys", `the ${role} key stays out of the node's environment`, "Fail", `${env[names.inline] ? names.inline : names.file} is set here; a node holds the operator key alone`);
+    }
+    if (env.FOGA_MNEMONIC || env.FOGA_MNEMONIC_FILE)
+        row("keys", "the phrase stays out of the node's environment", "Fail", "FOGA_MNEMONIC[_FILE] is set here");
+    // --- standing
+    if (cfg.identity.standing) {
+        try {
+            const r = await k.kya.resolve(accountSubject(node.chainId, cell.address), cfg.identity.standing.schemeId, cfg.identity.standing.issuers);
+            const now = await node.now();
+            const live = r.level > 0 && (Number(r.expiresAt) === 0 || Number(r.expiresAt) > now);
+            row("standing", "the cell's KYA standing is attested and current", live ? "Pass" : "Warn", live ? `level ${r.level}${Number(r.expiresAt) ? `, until ${new Date(Number(r.expiresAt) * 1000).toISOString()}` : ""}` : `level ${r.level}${Number(r.expiresAt) && Number(r.expiresAt) <= now ? ", expired" : ""}; an issuer attests (foga cell attest is theirs, not the cell's)`);
+        }
+        catch (e) {
+            row("standing", "the cell's KYA standing is attested and current", "NotTested", e.message);
+        }
+    }
+    else
+        row("standing", "the cell's KYA standing is attested and current", "Warn", "no identity.standing in the configuration: counterparties cannot be required to a level, and the cell has none to show");
+    // --- skills: held on chain, committed to the package that is here, complete, offered, and running
+    let held = [];
+    try {
+        held = await node.heldSkills();
+        row("skills", "every held skill's package is here and matches its on-chain commitment", "Pass", held.length ? held.map((h) => `${h.name} (token ${h.tokenId}, ${Object.keys(h.pkg.objects).length} objects, ${h.packageHash.slice(0, 10)}…)`).join("; ") : "no skills held");
+    }
+    catch (e) {
+        row("skills", "every held skill's package is here and matches its on-chain commitment", "Fail", e.message);
+    }
+    const notHeld = cfg.skills.offered.filter((s) => !(s in cfg.skills.held));
+    row("skills", "every offered skill is held", notHeld.length ? "Fail" : "Pass", notHeld.length ? `offered but not held: ${notHeld.join(", ")}` : `${cfg.skills.offered.length} offered of ${Object.keys(cfg.skills.held).length} held`);
+    const executors = ["foga-probe", "finch-extract-verify"];
+    const noExecutor = cfg.skills.offered.filter((s) => !executors.includes(s));
+    if (noExecutor.length)
+        row("skills", "every offered skill has an executor in this node", "Fail", `no executor for ${noExecutor.join(", ")} (this node runs ${executors.join(" and ")})`);
+    if (o.executors !== false) {
+        if (cfg.skills.offered.includes("foga-probe") && held.some((h) => h.name === "foga-probe")) {
+            try {
+                const started = Date.now();
+                const block = await k.blockNumber();
+                const run = await runProbeIsolated({ worldPath: node.worldPath, rpc: node.rpc, bundlePath: node.bundlePath, input: { subject: cell.address, block, lookback: 9000, kya: cfg.identity.standing ? { schemeId: cfg.identity.standing.schemeId, issuers: cfg.identity.standing.issuers } : undefined }, timeoutMs: 60_000 });
+                row("skills", "foga-probe runs in the worker", run.answer ? "Pass" : "Fail", `probed ${cell.address} at block ${block} in ${Date.now() - started} ms`);
+            }
+            catch (e) {
+                row("skills", "foga-probe runs in the worker", "Fail", e.message);
+            }
+        }
+        if (cfg.skills.offered.includes("finch-extract-verify") && held.some((h) => h.name === "finch-extract-verify")) {
+            const fixture = existsSync(node.inputDir) ? readdirSync(node.inputDir).find((f) => f.endsWith(".txt")) : undefined;
+            if (!fixture)
+                row("skills", "finch-extract-verify runs in the worker", "NotTested", `no .txt document in the input directory ${node.inputDir}`);
+            else {
+                try {
+                    const started = Date.now();
+                    const pkg = held.find((h) => h.name === "finch-extract-verify");
+                    const run = await runExtractIsolated({ documentPath: join(node.inputDir, fixture), fieldsPath: join(node.skillsDir, "finch-extract-verify", "fields.json"), packageHash: pkg.packageHash, inputDir: node.inputDir, skillsDir: node.skillsDir, timeoutMs: 60_000 });
+                    row("skills", "finch-extract-verify runs in the worker", run.resultHash ? "Pass" : "Fail", `extracted ${fixture} in ${Date.now() - started} ms`);
+                }
+                catch (e) {
+                    row("skills", "finch-extract-verify runs in the worker", "Fail", e.message);
+                }
+            }
+        }
+    }
+    row("skills", "the input directory exists", existsSync(node.inputDir) && statSync(node.inputDir).isDirectory() ? "Pass" : "Fail", node.inputDir);
+    // --- the documents: built, and what the chain holds agrees with them
+    const built = readBuilt(documentsDir(node));
+    if (!built)
+        row("documents", "the documents are built", "Warn", `nothing under ${documentsDir(node)} (foga cell docs build; foga cell docs publish commits them)`);
+    else {
+        row("documents", "the documents are built", "Pass", `v${built.manifest.version} built ${built.manifest.builtAt}, ${Object.keys(built.manifest.documents).length} files`);
+        for (const r of await readBack(node, built, { fetchUrls: o.network !== false }))
+            row("documents", r.commitment, r.ok === true ? "Pass" : r.ok === false ? "Fail" : "Warn", r.detail);
+    }
+    // --- the public face
+    const publicUrl = cfg.runtime.http.publicUrl;
+    if (!publicUrl)
+        row("public", "a public URL is configured", "Warn", "runtime.http.publicUrl is not set: the documents commit as data: URIs and the card declares no interface");
+    else if (o.network === false)
+        row("public", "the public URL answers", "NotTested", publicUrl);
+    else {
+        try {
+            const r = await fetch(`${publicUrl.replace(/\/+$/, "")}/healthz`, { signal: AbortSignal.timeout(5000) });
+            const body = (await r.json());
+            const same = body.account?.toLowerCase() === cell.address.toLowerCase();
+            row("public", "the public URL answers for this cell", r.ok && same ? "Pass" : "Fail", `${publicUrl}/healthz: HTTP ${r.status}, account ${body.account ?? "none"}`);
+        }
+        catch (e) {
+            row("public", "the public URL answers for this cell", "Warn", `${publicUrl}/healthz not reachable from here: ${e.message}`);
+        }
+    }
+    if (cfg.runtime.http.allowedHosts.length && publicUrl) {
+        const host = new URL(publicUrl).hostname;
+        row("public", "the public host is among the allowed hosts", cfg.runtime.http.allowedHosts.includes(host) ? "Pass" : "Fail", `${host} ${cfg.runtime.http.allowedHosts.includes(host) ? "is" : "is not"} in runtime.http.allowedHosts (${cfg.runtime.http.allowedHosts.join(", ")})`);
+    }
+    // --- the model, when the node is to run alive
+    if (cfg.runtime.model.provider === "anthropic") {
+        row("model", "the anthropic adapter has its key and model name", env.ANTHROPIC_API_KEY && cfg.runtime.model.model ? "Pass" : "Fail", `${env.ANTHROPIC_API_KEY ? "ANTHROPIC_API_KEY set" : "ANTHROPIC_API_KEY not set"}; model ${cfg.runtime.model.model ?? "(none)"}; ${cfg.runtime.model.dailyCalls} calls a day`);
+    }
+    else
+        row("model", "the model", "Pass", `provider ${cfg.runtime.model.provider} (host mode serves without one; foga node run --model anthropic needs the key and a model name)`);
+    return finish(node, rows);
+}
+function finish(node, rows) {
+    const summary = { Pass: 0, Warn: 0, Fail: 0, NotTested: 0 };
+    for (const r of rows)
+        summary[r.verdict]++;
+    return { schema: "foga.preflight/1", cell: node.config.name, account: node.config.identity.account ?? null, chainId: node.chainId, at: new Date().toISOString(), rows, summary };
+}
+export function printPreflight(report, print) {
+    print(`preflight: cell ${report.cell}${report.account ? ` (${report.account})` : ""} on chain ${report.chainId}, ${report.at}`);
+    let area = "";
+    for (const r of report.rows) {
+        if (r.area !== area) {
+            area = r.area;
+            print(`  ${area}`);
+        }
+        print(`    ${r.verdict.padEnd(9)} ${r.check}`);
+        print(`              ${r.detail}`);
+    }
+    print(`  ${report.summary.Pass} pass, ${report.summary.Warn} warn, ${report.summary.Fail} fail, ${report.summary.NotTested} not tested`);
+}

package/dist/node/propagation.js

@@ -0,0 +1,95 @@
+import { endpointsOf } from "../a2a/card.js";
+import { PACKAGE_NAME } from "../util/version.js";
+/**
+ * Propagation and discovery (design memo, section 10, the self-propagation refinement): the free, off-chain material
+ * a covenant-complete cell offers so that FOGA spreads — flexibly, at no fixed cost, and only ever by consent.
+ *
+ * Three rules shape every line of this module:
+ *  - Flexible, not nailed down. What the cell exposes is *material* — a manifest and a replication pointer — that an
+ *    agent weaves into its own interactions however it sees fit. There is no single mandated channel or hook.
+ *  - No fixed cost. All of it is off-chain: built from the configuration, served over HTTP, read over MCP. Nothing
+ *    here touches the chain or spends gas. On-chain discoverability (the ERC-8444 ARD descriptor) stays the opt-in
+ *    `docs_publish`, with this free manifest and the agent card as the always-available backup.
+ *  - By consent. The replication pointer is a visible, declinable offer the counterparty sees because it came to the
+ *    cell. It is never hidden inside an unrelated step and never pushed, unsolicited, to anyone who did not ask.
+ */
+/** The covenants this program is complete over: the ten plus ERC-8004. The base set, not a ceiling — see `world`. */
+export const FOGA_COVENANTS = ["ERC-8004", "ERC-8338", "ERC-8414", "ERC-8419", "ERC-8434", "ERC-8436", "ERC-8444", "ERC-8447", "ERC-8454", "ERC-8468", "ERC-8471"];
+export const PROPAGATION_SCHEMA = "foga.propagation/1";
+/**
+ * Where the program's maintainer lists the services around the covenants — free ones, and later paid ones. The
+ * manifest carries the pointer; the catalog itself lives behind the URL, so what is on offer changes there, not here.
+ */
+export const MAINTAINER_SERVICES_CATALOG = "https://foga.finchip.ai/services.json";
+export const MAINTAINER = "FinChip.ai";
+/** The maintainer's offers as of this build; the live list is the catalog's. */
+export const MAINTAINER_OFFERS = [
+    { id: "become-a-cell", name: "Become a cell", kind: "free", status: "available", url: "https://github.com/garyyang-finchip/foga#readme", description: "The program, the quickstart and the public-chain birth — free, with an identity of your own." },
+    { id: "kya-attestation", name: "KYA standing attestation", kind: "paid", status: "planned", url: MAINTAINER_SERVICES_CATALOG, description: "Standing under the FOGA scheme, attested by an issuer, for the tenders that require it; a cell cannot attest itself." },
+    { id: "hosted-cell", name: "Hosted cell", kind: "paid", status: "planned", url: MAINTAINER_SERVICES_CATALOG, description: "A cell served around the clock — the box, the TLS, the watchers, the backups — on keys that stay yours." },
+    { id: "dispute-resolution", name: "Dispute resolution", kind: "paid", status: "planned", url: MAINTAINER_SERVICES_CATALOG, description: "An ERC-8471 arbiter for the disputes a tender economy produces." },
+];
+/** The services block from the configuration: the maintainer's by default, the operator's own, or none. */
+export function servicesOf(cfg) {
+    const s = cfg.presence.services;
+    if (s && s.catalog === null)
+        return null;
+    return {
+        catalog: s?.catalog ?? MAINTAINER_SERVICES_CATALOG,
+        maintainer: s?.catalog ? "the operator of this cell" : MAINTAINER,
+        offers: s?.offers ?? MAINTAINER_OFFERS,
+        note: "optional and declinable; the catalog is the live list; a planned offer is not for sale yet",
+    };
+}
+export const SERVICES_SCHEMA = "foga.services/1";
+/**
+ * The catalog document a cell serves at `/services.json` when the catalog its manifest points at is its own — the
+ * reference cell serving the maintainer's list, an operator serving theirs. A cell whose pointer names another host
+ * serves nothing: the list is that host's, and the pointer resolves there. The list changes without a release by a
+ * static file at the same path on the host (the proxy answering it before the node) — that is the live list; this
+ * is what it says until then.
+ */
+export function servicesCatalogOf(node, o) {
+    const s = servicesOf(node.config);
+    const base = node.config.runtime.http.publicUrl?.replace(/\/+$/, "") ?? null;
+    if (!s || !base || s.catalog !== `${base}/services.json`)
+        return null;
+    return { schema: SERVICES_SCHEMA, catalog: s.catalog, maintainer: s.maintainer, program: { package: PACKAGE_NAME, version: o.version }, offers: s.offers, note: s.note };
+}
+/**
+ * Build the manifest from the cell's configuration and the package version. Pure and cheap: no chain read, no key,
+ * no I/O beyond what `endpointsOf` derives from the config, so it can be served on every request and before birth.
+ */
+export function buildPropagationManifest(node, o) {
+    const cfg = node.config;
+    const ep = endpointsOf(node);
+    const base = cfg.runtime.http.publicUrl?.replace(/\/+$/, "") ?? null;
+    const inWorld = node.world.covenants();
+    return {
+        schema: PROPAGATION_SCHEMA,
+        cell: { name: cfg.name, account: cfg.identity.account ?? null, agentId: cfg.identity.agentId ?? null, chainId: node.chainId },
+        covenants: FOGA_COVENANTS,
+        world: { covenants: inWorld, extensions: inWorld.filter((c) => !FOGA_COVENANTS.includes(c)) },
+        program: {
+            package: PACKAGE_NAME,
+            version: o.version,
+            becomeACell: `npx -y ${PACKAGE_NAME} quickstart`,
+            wallet: `npx -y ${PACKAGE_NAME} wallet new`,
+            docs: "https://github.com/garyyang-finchip/foga#readme",
+            site: ep.web ?? "https://foga.finchip.ai",
+        },
+        endpoints: { mcp: ep.mcp, a2a: ep.a2a, web: ep.web, card: base ? `${base}/.well-known/agent-card.json` : null, manifest: base ? `${base}/.well-known/foga-cell.json` : null },
+        replication: {
+            pitch: "You can become a FOGA cell yourself: the program is public, the identity you make is your own, and nothing of this cell's identity is copied.",
+            pointer: `Run \`npx -y ${PACKAGE_NAME} quickstart\` for a living cell on a local chain, or read ${ep.web ?? "https://foga.finchip.ai"}.`,
+            optional: true,
+            consensual: true,
+        },
+        skills: o.skills ?? cfg.skills.offered,
+        discovery: {
+            free: ["this manifest at /.well-known/foga-cell.json", "the agent card at /.well-known/agent-card.json", `the npm package ${PACKAGE_NAME} and the MCP registry`],
+            onchain: { optional: true, via: "the ERC-8444 ARD descriptor (foga cell docs publish)", cost: "gas; opt-in, with this manifest and the card as the free backup" },
+        },
+        services: servicesOf(cfg),
+    };
+}