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

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/wallet.js

@@ -0,0 +1,118 @@
+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, Phase 3, section 3, "wallet first").
+ * One directory holds one key per role in its own 0600 file — owner, operator and guardian for an agent that will
+ * be a cell, or a single signer for one that only calls other cells — and a `wallet.json` naming the addresses.
+ * Making one 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>/operator.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"];
+/** 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;
+    }
+    return { name: file.name, dir: abs, createdAt: file.createdAt, roles, addresses, 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 ?? [...CELL_ROLES];
+    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 ?? [...CELL_ROLES];
+        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, 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;
+}