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

package/dist/tools/catalog.js

@@ -0,0 +1,261 @@
+import { z } from "zod";
+import { jcs, sha256Hex } from "../core/canonical.js";
+import { OperationAmbiguous, OperationReverted } from "../kernel/tx.js";
+import { budgetGate, firstRefusal } from "../node/policy.js";
+import { ACTION_RANK, VISIBILITY_RANK } from "./types.js";
+/** Gas reserved per step against the fee budget until the operation settles and its real cost replaces it. */
+export const FEE_RESERVE_GAS = 300000n;
+/**
+ * The capability catalog and the one place authorization happens (design memo, Phase 3, section 3). `invoke` runs
+ * the three checks for every act — call permission (who may use what, at which level), business authorization (the
+ * policy engine over the plan the capability made), wallet permission (the account's own scope, simulated before
+ * the send and enforced again on chain) — and writes a decision record for every attempt. Reads pass the
+ * permission check alone and leave no record. The entrances (CLI, MCP, HTTP, A2A) call this and nothing else.
+ */
+export class Catalog {
+    caps = new Map();
+    register(cap) {
+        if (this.caps.has(cap.name))
+            throw new Error(`capability ${cap.name} registered twice`);
+        this.caps.set(cap.name, cap);
+        return this;
+    }
+    get(name) {
+        return this.caps.get(name);
+    }
+    names() {
+        return [...this.caps.keys()];
+    }
+    /** The capabilities a caller may use, with the modes its level allows. */
+    list(caller) {
+        const out = [];
+        for (const cap of this.caps.values()) {
+            if (VISIBILITY_RANK[caller.visibility] < VISIBILITY_RANK[cap.visibility])
+                continue;
+            const modes = modesFor(caller, cap);
+            if (cap.action !== "read" && modes.length === 0)
+                continue;
+            out.push({
+                name: cap.name,
+                title: cap.title,
+                description: cap.description,
+                action: cap.action,
+                visibility: cap.visibility,
+                principal: cap.principal,
+                ercs: cap.ercs,
+                modes,
+                inputSchema: z.toJSONSchema(cap.input, { target: "draft-2020-12", io: "input" }),
+                outputSchema: z.toJSONSchema(cap.output, { target: "draft-2020-12", io: "output" }),
+            });
+        }
+        return out;
+    }
+    async invoke(node, name, rawInput, caller, opts = {}) {
+        const cap = this.caps.get(name);
+        if (!cap)
+            return { ok: false, gate: "input", reason: `unknown capability ${name}` };
+        const mode = opts.mode ?? "act";
+        const inputHash = hashInput(rawInput);
+        // the data scope first: a capability the caller may not see is as if it did not exist (a read leaves no record)
+        if (VISIBILITY_RANK[caller.visibility] < VISIBILITY_RANK[cap.visibility]) {
+            const reason = `${cap.name} is ${cap.visibility}-visible; this caller sees ${caller.visibility} data`;
+            return cap.action === "read" ? { ok: false, gate: "permission", reason } : this.refuse(node, cap, caller, mode, inputHash, "permission", reason);
+        }
+        const parsed = cap.input.safeParse(rawInput ?? {});
+        if (!parsed.success) {
+            const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+            return this.refuse(node, cap, caller, mode, inputHash, "input", issues);
+        }
+        const input = parsed.data;
+        if (cap.action === "read") {
+            if (ACTION_RANK[caller.level] < ACTION_RANK.read)
+                return { ok: false, gate: "permission", reason: "no read permission" };
+            const output = await cap.handler({ node, caller }, input);
+            return { ok: true, output: cap.output.parse(output) };
+        }
+        // call permission: the mode decides the level needed (a build or a dry run needs build; the act itself needs act or admin)
+        const needed = mode === "act" ? cap.action : "build";
+        if (ACTION_RANK[caller.level] < ACTION_RANK[needed]) {
+            return this.refuse(node, cap, caller, mode, inputHash, "permission", `${cap.name} in mode ${mode} needs level ${needed}; this caller has ${caller.level}`);
+        }
+        if (mode === "act" && cap.signer && !node.hasKey(cap.signer)) {
+            return this.refuse(node, cap, caller, mode, inputHash, "permission", `${cap.name} is the ${cap.signer}'s act and this process holds no ${cap.signer} key`);
+        }
+        const asInput = input.as;
+        const as = mode === "build" && asInput ? asInput : node.cell?.address ?? asInput ?? "0x0000000000000000000000000000000000000000";
+        let plan;
+        try {
+            plan = await cap.plan({ node, caller, mode, as }, input);
+        }
+        catch (e) {
+            return this.refuse(node, cap, caller, mode, inputHash, "input", explain(e));
+        }
+        const jobId = plan.job.id;
+        if (mode === "build") {
+            const calls = plan.calls ?? (await buildAll(plan.steps));
+            const decision = node.store.decide({ entrance: caller.entrance, caller: caller.id, capability: cap.name, mode, inputHash, verdict: "allowed", gate: "build", reason: `${calls.length} call(s) built for ${as}`, jobId, operationId: null, model: opts.model ?? null });
+            return { ok: true, output: { as, calls: calls.map((c) => ({ to: c.target, value: c.value.toString(), data: c.data, label: c.label })) }, decisionId: decision.id, jobId };
+        }
+        // an act under a known job: the same job with the same input is answered from the store, never done twice;
+        // a job is created only once every gate has passed, so a refusal leaves a decision record and nothing else
+        let job = null;
+        if (mode === "act" && !plan.job.ephemeral) {
+            const existing = node.store.getJob(jobId);
+            if (existing) {
+                if (existing.inputHash !== inputHash)
+                    return this.refuse(node, cap, caller, mode, inputHash, "conflict", `job ${jobId} exists for another request (${existing.inputHash}); the same job id must carry the same request`, jobId);
+                if (existing.status === "done") {
+                    const decision = node.store.decide({ entrance: caller.entrance, caller: caller.id, capability: cap.name, mode, inputHash, verdict: "allowed", gate: "idempotent", reason: `job ${jobId} is done; its result is returned, nothing is sent again`, jobId, operationId: existing.operations[0] ?? null, model: opts.model ?? null });
+                    return { ok: true, output: existing.result, decisionId: decision.id, jobId, operations: existing.operations };
+                }
+                if (existing.status === "failed" || existing.status === "cancelled") {
+                    return this.refuse(node, cap, caller, mode, inputHash, "execution", `job ${jobId} ${existing.status} before (${existing.error ?? "no reason recorded"}); the same job answers with that outcome. A new attempt is a new job (another idempotency key).`, jobId);
+                }
+                job = existing; // accepted or running: a run that stopped before finishing is continued (the kernel sends nothing twice)
+            }
+        }
+        // the decision section runs one act at a time per node: the budget gate reads what earlier decisions reserved (a job's
+        // planned value counts from its creation, before its operations exist), so concurrent callers cannot each pass a cap
+        // that only one of them fits under
+        const decided = await node.serialize(async () => {
+            // business authorization: the capability's gates, then the budget (a cell's act only; an admin step is the owner's own transaction)
+            const gates = [...plan.gates];
+            if (cap.action === "act" && (plan.steps.length || plan.valueWei > 0n || plan.job.commitment)) {
+                const fee = await feeReserve(node, plan.steps.length);
+                gates.push(budgetGate(node.config, node.budgetUse(), { valueWei: plan.valueWei, feeReserveWei: fee, commitment: Boolean(plan.job.commitment) && !job }));
+            }
+            const refusal = firstRefusal(gates);
+            if (refusal)
+                return this.refuse(node, cap, caller, mode, inputHash, refusal.gate, refusal.reason, jobId);
+            // wallet permission: the first step is simulated from its signer (the account's allow-list, gate and daily cap decide on chain as well)
+            if (plan.steps.length) {
+                const first = plan.steps[0];
+                const intent = await first.build([]);
+                const route = routeOf(first);
+                const from = node.config.identity[route.signer];
+                const to = route.route === "execute" ? node.body.address : intent.target;
+                const data = route.route === "execute" ? node.body.encodeExecute(intent.target, intent.value, intent.data) : intent.data;
+                const value = route.route === "execute" ? 0n : intent.value;
+                const revert = await node.wouldRevert(from, to, data, value);
+                if (revert !== null)
+                    return this.refuse(node, cap, caller, mode, inputHash, "wallet", `${first.name} would revert: ${revert}`, jobId);
+            }
+            if (mode === "simulate") {
+                const decision = node.store.decide({ entrance: caller.entrance, caller: caller.id, capability: cap.name, mode, inputHash, verdict: "allowed", gate: "all", reason: summarize(gates, plan.steps.length), jobId, operationId: null, model: opts.model ?? null });
+                const output = await plan.output([], undefined);
+                return { ok: true, output: cap.output.parse(output), decisionId: decision.id, jobId };
+            }
+            // the act: recorded as allowed before anything is sent; the job (with the value it will move) exists from here on
+            const allowed = node.store.decide({ entrance: caller.entrance, caller: caller.id, capability: cap.name, mode, inputHash, verdict: "allowed", gate: "all", reason: summarize(gates, plan.steps.length), jobId, operationId: plan.steps.length ? `job:${jobId}:${plan.steps[0].name}` : null, model: opts.model ?? null });
+            if (plan.job.ephemeral)
+                return { allowed, gates, job: null };
+            const created = job ?? node.store.createJob({ id: jobId, kind: plan.job.kind, caller: caller.id, cell: node.cell?.address, inputHash, input: plan.job.input, valueWei: plan.valueWei });
+            node.store.updateJob(jobId, { status: "running" });
+            return { allowed, gates, job: created };
+        });
+        if ("ok" in decided)
+            return decided;
+        const { allowed } = decided;
+        if (plan.job.ephemeral) {
+            const output = cap.output.parse(await plan.output([], plan.work ? await plan.work() : undefined));
+            return { ok: true, output, decisionId: allowed.id, jobId };
+        }
+        job = decided.job;
+        const confirmed = [];
+        const operations = [...job.operations];
+        try {
+            const work = plan.work ? await plan.work() : undefined;
+            const fee = await feeReserve(node, 1);
+            for (const step of plan.steps) {
+                const intent = await step.build(confirmed);
+                const key = `job:${jobId}:${step.name}`;
+                const binding = { requestHash: inputHash, capability: cap.name, caller: caller.id, cell: node.cell?.address, valueWei: intent.value, feeCapWei: fee };
+                const route = routeOf(step);
+                let c;
+                if (route.route === "execute") {
+                    c = await node.body.execute(key, intent.target, intent.data, { value: intent.value, by: route.signer === "owner" ? "owner" : "operator", binding });
+                }
+                else {
+                    c = await node.kernel.tx.send({ key, signer: node.signerOf(route.signer), kind: "direct", binding, build: () => ({ to: intent.target, data: intent.data, value: intent.value }) });
+                }
+                confirmed.push(c);
+                if (!operations.includes(key))
+                    operations.push(key);
+                node.store.updateJob(jobId, { addOperation: key });
+            }
+            const output = cap.output.parse(await plan.output(confirmed, work));
+            node.store.updateJob(jobId, { status: "done", result: output });
+            return { ok: true, output, decisionId: allowed.id, jobId, operations };
+        }
+        catch (e) {
+            const reason = explain(e);
+            const operationId = e instanceof OperationReverted || e instanceof OperationAmbiguous ? e.key ?? e.op?.key ?? null : operations.at(-1) ?? null;
+            node.store.updateJob(jobId, { status: "failed", error: reason });
+            const decision = node.store.decide({ entrance: caller.entrance, caller: caller.id, capability: cap.name, mode, inputHash, verdict: "refused", gate: "execution", reason, jobId, operationId, model: opts.model ?? null });
+            return { ok: false, gate: "execution", reason, decisionId: decision.id, jobId };
+        }
+    }
+    refuse(node, cap, caller, mode, inputHash, gate, reason, jobId) {
+        const decision = node.store.decide({ entrance: caller.entrance, caller: caller.id, capability: cap.name, mode, inputHash, verdict: "refused", gate, reason, jobId: jobId ?? null, operationId: null, model: null });
+        return { ok: false, gate, reason, decisionId: decision.id, jobId };
+    }
+}
+/**
+ * The canonical hash of a request: the input without its idempotency key. `jobId` names the job and is not part of
+ * what the job does, so a request first made under a derived id and then repeated naming that id is the same request
+ * (idempotent), while the same id with another input is a conflict.
+ */
+export function hashInput(input) {
+    if (input && typeof input === "object" && !Array.isArray(input) && "jobId" in input) {
+        const { jobId: _jobId, ...rest } = input;
+        return sha256Hex(jcs(rest));
+    }
+    return sha256Hex(jcs(input ?? {}));
+}
+function modesFor(caller, cap) {
+    if (cap.action === "read")
+        return [];
+    const out = [];
+    if (ACTION_RANK[caller.level] >= ACTION_RANK.build)
+        out.push("simulate", "build");
+    if (ACTION_RANK[caller.level] >= ACTION_RANK[cap.action])
+        out.push("act");
+    return out;
+}
+function routeOf(step) {
+    return { route: step.route ?? "execute", signer: step.by ?? "operator" };
+}
+async function buildAll(steps) {
+    const out = [];
+    for (const s of steps) {
+        try {
+            out.push(await s.build([]));
+        }
+        catch {
+            break; // a later step that needs an earlier receipt cannot be built ahead
+        }
+    }
+    return out;
+}
+async function feeReserve(node, steps) {
+    if (!steps)
+        return 0n;
+    const fee = await node.world.provider.getFeeData();
+    const price = fee.maxFeePerGas ?? fee.gasPrice ?? 0n;
+    return BigInt(steps) * FEE_RESERVE_GAS * price;
+}
+function summarize(gates, steps) {
+    const names = [...new Set(gates.map((g) => g.gate))];
+    return `all gates passed (${names.join(", ")}); ${steps} step(s)`;
+}
+function explain(e) {
+    if (e instanceof OperationReverted || e instanceof OperationAmbiguous)
+        return e.message;
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+/** True when a result is a success (for callers that narrow). */
+export function succeeded(r) {
+    return r.ok;
+}

package/dist/tools/common.js

@@ -0,0 +1,143 @@
+import { getAddress } from "ethers";
+import { z } from "zod";
+import { accountSubject } from "../core/kya.js";
+import { parseDataUri, sha256Hex, jcs } from "../core/canonical.js";
+/** Shared schema fragments. */
+export const zAddress = z.string().regex(/^0x[0-9a-fA-F]{40}$/, "an address (0x + 40 hex digits)");
+export const zBytes32 = z.string().regex(/^0x[0-9a-fA-F]{64}$/, "a 32-byte hex value");
+export const zUint = z.string().regex(/^\d+$/, "a decimal integer");
+export const zHex = z.string().regex(/^0x([0-9a-fA-F]{2})*$/, "hex bytes");
+/** A boolean that also reads "true" / "false" (CLI flags). */
+export const zBool = z.preprocess((v) => (v === "true" ? true : v === "false" ? false : v), z.boolean());
+/** The caller's idempotency key for a job; derived from the semantic input when absent. */
+export const zJobId = z.string().min(1).max(128).regex(/^[A-Za-z0-9:_.-]+$/, "a job id: letters, digits, : _ . -").optional();
+/** The account a build is for (`build` mode): a third party gets calldata it can execute itself. */
+export const zAs = zAddress.optional().describe("build mode: the account the calldata is for (default: the cell)");
+/** A task document a tender points at (foga.task/1), as the genesis publishes it. */
+export const TaskDocumentSchema = z.object({
+    schema: z.literal("foga.task/1"),
+    skill: z.string(),
+    packageHash: zBytes32,
+    input: z.unknown(),
+    acceptance: z.object({ mode: z.string(), profile: z.string().optional(), verifier: zAddress.optional(), answerHash: zBytes32.optional() }).passthrough(),
+    deliverable: z.string().optional(),
+});
+/** Everything the policy and the capabilities need to know about one tender, read from the chain. */
+export async function readTender(node, tokenId, opts = {}) {
+    const k = node.kernel;
+    const token = k.tenders.contract();
+    const [terms, authority, escrow, cancelled, completions, count, demander, taskURI, binding] = await Promise.all([
+        k.tenders.terms(tokenId),
+        k.tenders.acceptanceAuthorityOf(tokenId),
+        k.tenders.escrowBalanceOf(tokenId),
+        k.tenders.isCancelled(tokenId),
+        token.completionsOf(tokenId).then((v) => BigInt(v)),
+        k.tenders.submissionCount(tokenId),
+        token.ownerOf(tokenId).then((a) => String(a)),
+        token.taskURI(tokenId).then((u) => String(u)),
+        token.taskOf(tokenId),
+    ]);
+    let task = null;
+    if (taskURI.startsWith("data:")) {
+        try {
+            const parsed = TaskDocumentSchema.safeParse(parseDataUri(taskURI));
+            task = parsed.success ? parsed.data : null;
+        }
+        catch {
+            task = null;
+        }
+    }
+    const submissions = [];
+    // submission ids start at 1 (TaskToken: the count is the last id)
+    for (let i = 1n; i <= count; i++) {
+        const s = await k.tenders.submissionOf(tokenId, i);
+        submissions.push({ id: i.toString(), fulfiller: s.fulfiller, status: s.status, machineSettled: s.machineSettled, resultHash: s.resultHash });
+    }
+    let counterpartyLevel = null;
+    if (opts.counterparty && node.config.identity.standing) {
+        const st = node.config.identity.standing;
+        try {
+            const r = await k.kya.resolve(accountSubject(node.chainId, demander), st.schemeId, st.issuers);
+            counterpartyLevel = Number(r.level);
+        }
+        catch {
+            counterpartyLevel = null;
+        }
+    }
+    return {
+        facts: {
+            tokenId,
+            rewardWei: terms.rewardPerCompletion,
+            asset: terms.asset,
+            submitBy: terms.submitBy,
+            settleBy: terms.settleBy,
+            maxCompletions: terms.maxCompletions,
+            completions,
+            acceptanceAuthority: getAddress(authority),
+            cancelled,
+            escrowWei: escrow,
+            skill: task?.skill ?? null,
+            packageHash: task?.packageHash ?? null,
+            acceptanceProfile: task?.acceptance.profile ?? null,
+            counterpartyLevel,
+        },
+        demander: getAddress(demander),
+        taskURI,
+        task,
+        taskHash: String(binding.taskHash),
+        tdHash: String(binding.tdHash),
+        version: Number(binding.version),
+        submissions,
+    };
+}
+/** A tender's JSON view for outputs (bigints as strings). */
+export function tenderOutput(v) {
+    const f = v.facts;
+    return {
+        tokenId: f.tokenId.toString(),
+        demander: v.demander,
+        rewardWei: f.rewardWei.toString(),
+        asset: f.asset,
+        submitBy: Number(f.submitBy),
+        settleBy: Number(f.settleBy),
+        maxCompletions: Number(f.maxCompletions),
+        completions: Number(f.completions),
+        acceptanceAuthority: f.acceptanceAuthority,
+        cancelled: f.cancelled,
+        escrowWei: f.escrowWei.toString(),
+        taskURI: v.taskURI.length > 200 ? `${v.taskURI.slice(0, 200)}… (${v.taskURI.length} chars)` : v.taskURI,
+        task: v.task,
+        taskHash: v.taskHash,
+        tdHash: v.tdHash,
+        version: v.version,
+        submissions: v.submissions,
+    };
+}
+export const TenderOutputSchema = z.object({
+    tokenId: zUint,
+    demander: zAddress,
+    rewardWei: zUint,
+    asset: zAddress,
+    submitBy: z.number(),
+    settleBy: z.number(),
+    maxCompletions: z.number(),
+    completions: z.number(),
+    acceptanceAuthority: zAddress,
+    cancelled: z.boolean(),
+    escrowWei: zUint,
+    taskURI: z.string(),
+    task: TaskDocumentSchema.nullable(),
+    taskHash: zBytes32,
+    tdHash: zBytes32,
+    version: z.number(),
+    submissions: z.array(z.object({ id: zUint, fulfiller: zAddress, status: z.number(), machineSettled: z.boolean(), resultHash: zBytes32 })),
+});
+/** A short, stable id from semantic input (the default job id of an act). */
+export function derivedJobId(prefix, parts) {
+    return `${prefix}:${sha256Hex(jcs(parts)).slice(2, 18)}`;
+}
+/** The job of a tender's n-th completion by this cell: the second legitimate completion of a tender is another job. */
+export function tenderJobId(tokenId, completions) {
+    return `tender:${tokenId}:c${completions}`;
+}
+export const GateSchema = z.object({ gate: z.string(), ok: z.boolean(), reason: z.string() });

package/dist/tools/identity.js

@@ -0,0 +1,107 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { kindId, skillDescriptor } from "../core/ard.js";
+import { dataUriJcs } from "../core/canonical.js";
+import { buildSkillPackage, readSkillDir } from "../core/pack/skillpack.js";
+import { skillUnitDefinition } from "../core/units.js";
+import { ok, refused, safetyGate } from "../node/policy.js";
+import { derivedJobId, zBool, zBytes32, zJobId, zUint } from "./common.js";
+/**
+ * The cell's own identity and capability acts: minting a skill it will offer (ERC-8338 token, ERC-8444 record,
+ * ERC-8454 unit — what the genesis does in T2) and keeping its anchor alive (ERC-8434 heartbeat in every registry
+ * it is bound in). Both are the cell's acts through its account.
+ */
+export const skill_mint = {
+    name: "skill_mint",
+    title: "Mint a skill the cell holds",
+    description: "Package a skill directory, mint its ERC-8338 token to the cell, register its ERC-8444 skill record and its ERC-8454 unit, and record it in the cell's configuration as held (and offered, when asked).",
+    action: "act",
+    visibility: "operator",
+    principal: "cell",
+    ercs: [8338, 8444, 8454],
+    input: z.object({ skill: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "a skill directory name"), offer: zBool.default(true), priceEth: z.string().regex(/^\d+(\.\d+)?$/).default("0"), jobId: zJobId }),
+    output: z.object({ skill: z.string(), tokenId: zUint, recordId: zBytes32, unitId: zUint, mdHash: zBytes32, packageHash: zBytes32, offered: z.boolean(), operations: z.array(z.string()), jobId: z.string() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const cell = node.body;
+        const chainId = node.chainId;
+        const dir = join(node.skillsDir, input.skill);
+        const pkg = buildSkillPackage(readSkillDir(dir));
+        const gates = [];
+        const [aidState, status] = await Promise.all([k.aid.stateName(cell.address), cell.status()]);
+        gates.push(safetyGate(aidState, status, "plain"));
+        const already = node.config.skills.held[input.skill];
+        if (already)
+            gates.push(refused("policy", `the cell already holds ${input.skill} as token ${already.tokenId}; update the skill instead`));
+        else
+            gates.push(ok("policy", `${input.skill} v${pkg.version}: mdHash ${pkg.mdHash.slice(0, 10)}…, packageHash ${pkg.packageHash.slice(0, 10)}…`));
+        const packageURI = dataUriJcs({ skill: input.skill, version: pkg.version, mdHash: pkg.mdHash, packageHash: pkg.packageHash, rootCid: pkg.rootCid, source: `${node.config.skills.dir}/${input.skill}` });
+        const jobId = input.jobId ?? derivedJobId(`skill-mint:${input.skill}`, { packageHash: pkg.packageHash, cell: cell.address });
+        const tokenOf = (prior) => k.skills.tokenIdFromReceipt(prior[0].receipt);
+        const steps = [
+            { name: "mint", kind: "plain", build: () => ({ target: k.skills.address, value: 0n, data: k.skills.encodeMint(cell.address, cell.address, pkg, packageURI), label: `mintSkill(${input.skill})` }) },
+            {
+                name: "record",
+                kind: "plain",
+                build: (prior) => {
+                    const tokenId = tokenOf(prior);
+                    const descriptor = skillDescriptor({ chainId, controller: cell.address, slug: input.skill, name: input.skill, description: String(pkg.manifest.summary ?? input.skill), packageHash: pkg.packageHash, packageURI, price: { amount: input.priceEth, currency: "ETH", asset: `eip155:${chainId}/slip44:60` } });
+                    return { target: k.ard.address, value: 0n, data: k.ard.encodeRegister(kindId("skill"), k.skills.address, tokenId, descriptor), label: `ARD register(skill ${tokenId})` };
+                },
+            },
+            { name: "unit", kind: "plain", build: (prior) => ({ target: k.units.registryAddress, value: 0n, data: k.units.encodeRegisterUnit(cell.address, skillUnitDefinition({ chainId, skillToken: k.skills.address, tokenId: tokenOf(prior), holder: cell.address, name: input.skill }), []), label: `AUF registerUnit(skill ${input.skill})` }) },
+        ];
+        return {
+            job: { id: jobId, kind: "skill-mint", input: { skill: input.skill, packageHash: pkg.packageHash } },
+            gates,
+            valueWei: 0n,
+            steps,
+            output: (confirmed) => {
+                const tokenId = tokenOf(confirmed);
+                const recordId = k.ard.recordIdFromReceipt(confirmed[1].receipt);
+                const unitId = k.units.unitIdFromReceipt(confirmed[2].receipt);
+                // the configuration follows the chain: the skill is now held (and offered, when asked)
+                node.config.skills.held[input.skill] = { tokenId: tokenId.toString(), recordId, unitId: unitId.toString(), packageHash: pkg.packageHash };
+                if (input.offer && !node.config.skills.offered.includes(input.skill))
+                    node.config.skills.offered.push(input.skill);
+                node.saveConfig();
+                return { skill: input.skill, tokenId: tokenId.toString(), recordId, unitId: unitId.toString(), mdHash: pkg.mdHash, packageHash: pkg.packageHash, offered: node.config.skills.offered.includes(input.skill), operations: steps.map((s) => `job:${jobId}:${s.name}`), jobId };
+            },
+        };
+    },
+};
+export const aid_heartbeat = {
+    name: "aid_heartbeat",
+    title: "Heartbeat",
+    description: "Keep the cell's anchor ACTIVE: an ERC-8434 heartbeat in the reference registry and in the backing registry where the world has one. The watcher sends it on schedule; a caller may ask for one.",
+    action: "act",
+    visibility: "caller",
+    principal: "cell",
+    ercs: [8434],
+    input: z.object({ jobId: zJobId }),
+    output: z.object({ registries: z.array(z.object({ registry: z.string(), state: z.string(), txHash: z.string() })), jobId: z.string() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const cell = node.body;
+        const gates = [];
+        const [aidState, status] = await Promise.all([k.aid.stateName(cell.address), cell.status()]);
+        if (aidState === "RETIRED")
+            gates.push(refused("policy", "anchor RETIRED: nothing to keep alive"));
+        else if (aidState === "DORMANT" && (await k.aid.bindingOf(cell.address)).registry === "0x0000000000000000000000000000000000000000")
+            gates.push(refused("policy", "the anchor is not bound to an agent: nothing to keep alive"));
+        else
+            gates.push(ok("policy", `anchor ${aidState}`));
+        gates.push(safetyGate(aidState, status, "plain"));
+        const registries = [k.aid.address, ...(k.aid.backing ? [k.aid.backing.address] : [])];
+        const jobId = input.jobId ?? derivedJobId("heartbeat", { at: Math.floor(Date.now() / 60_000) });
+        const steps = registries.map((registry, i) => ({ name: i === 0 ? "heartbeat" : "heartbeat.backing", kind: "plain", build: () => ({ target: registry, value: 0n, data: k.aid.encodeHeartbeat(), label: `heartbeat() in ${registry}` }) }));
+        return {
+            job: { id: jobId, kind: "heartbeat", input: { registries } },
+            gates,
+            valueWei: 0n,
+            steps,
+            output: async (confirmed) => ({ registries: await Promise.all(registries.map(async (registry, i) => ({ registry, state: await k.aid.stateName(cell.address, registry), txHash: confirmed[i]?.txHash ?? "" }))), jobId }),
+        };
+    },
+};
+export const IDENTITY_CAPABILITIES = [skill_mint, aid_heartbeat];

package/dist/tools/index.js

@@ -0,0 +1,14 @@
+import { ADMIN_CAPABILITIES } from "./admin.js";
+import { Catalog } from "./catalog.js";
+import { IDENTITY_CAPABILITIES } from "./identity.js";
+import { READ_CAPABILITIES } from "./read.js";
+import { TENDER_CAPABILITIES } from "./tenders.js";
+export { Catalog, hashInput, succeeded } from "./catalog.js";
+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])
+        c.register(cap);
+    return c;
+}