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

package/dist/tools/tenders.js

@@ -0,0 +1,400 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAddress, toUtf8Bytes, hexlify } from "ethers";
+import { z } from "zod";
+import { accountRef, dataUri, dataUriJcs, keccakJcs, sha256Hex } from "../core/canonical.js";
+import { kindId, taskDescriptor } from "../core/ard.js";
+import { hashlock, nativeTerms } from "../core/tenders.js";
+import { runExtractIsolated, runProbeIsolated } from "../genesis/skill-runner.js";
+import { ok, refused, safetyGate, skillGate, tenderGates } from "../node/policy.js";
+import { GateSchema, TaskDocumentSchema, TenderOutputSchema, derivedJobId, readTender, tenderJobId, tenderOutput, zAs, zBool, zBytes32, zHex, zJobId, zUint } from "./common.js";
+/**
+ * The tender path (ERC-8414) as capabilities: what the genesis does in T3 by hand, offered to a caller and judged by
+ * the catalog. The fulfiller's side — precheck, run the skill, submit, settle, withdraw — is the Loop D path; the
+ * demander's side — mint, fund — is what a counterparty (or a test) uses, in act mode through the cell or in build
+ * mode as calldata for its own account.
+ */
+const ZERO32 = "0x" + "00".repeat(32);
+/** The text of a data: URI (base64 or percent-encoded), whatever its media type. */
+function decodeDataUriText(uri) {
+    const m = /^data:([^,]*?)(;base64)?,(.*)$/s.exec(uri);
+    if (!m)
+        throw new Error("not a data: URI");
+    return m[2] ? Buffer.from(m[3], "base64").toString("utf8") : decodeURIComponent(m[3]);
+}
+/** The business gates of taking a tender: liveness and safety, skill, the tender policy, the hashlock commitment. */
+async function takingGates(node, view) {
+    const k = node.kernel;
+    const cell = node.body;
+    const gates = [];
+    const [aidState, status] = await Promise.all([k.aid.stateName(cell.address), cell.status()]);
+    gates.push(safetyGate(aidState, status, "commitment"));
+    const held = await node.heldSkills();
+    gates.push(skillGate(node.config, { skill: view.facts.skill, packageHash: view.facts.packageHash }, held.map((h) => ({ name: h.name, packageHash: h.packageHash }))));
+    gates.push(...tenderGates(node.config, view.facts, { now: await node.now() }, node.acceptance));
+    if (getAddress(view.facts.acceptanceAuthority) === getAddress(node.acceptance.hashlock)) {
+        const committed = await k.tenders.hashlockVerifier().answerHashOf(await k.tenders.hashlockVerifier().key(k.tenders.address, view.facts.tokenId));
+        if (committed === ZERO32)
+            gates.push(refused("verifier", "the hashlock verifier holds no committed answer for this tender yet"));
+        else if (view.task?.acceptance.answerHash && view.task.acceptance.answerHash.toLowerCase() !== committed.toLowerCase())
+            gates.push(refused("verifier", `the task document's answerHash ${view.task.acceptance.answerHash.slice(0, 10)}… differs from the verifier's commitment ${committed.slice(0, 10)}…`));
+        else
+            gates.push(ok("verifier", `answer committed in the hashlock verifier (${committed.slice(0, 10)}…)`));
+    }
+    const gas = await k.balance(node.config.identity.operator);
+    const floor = BigInt(node.config.policy.budget.dailyGasWei) / 4n;
+    if (gas < floor)
+        gates.push(refused("budget", `operator gas ${gas} wei is below a quarter of the daily gas budget (${floor} wei)`));
+    else
+        gates.push(ok("budget", `operator holds ${gas} wei of gas (floor ${floor} wei)`));
+    return gates;
+}
+export const tender_precheck = {
+    name: "tender_precheck",
+    title: "Pre-check a tender",
+    description: "Every gate the cell passes before taking a tender: anchor ACTIVE and binding Satisfied, the skill held and offered with the committed package, the policy on reward and deadlines, the acceptance authority, the hashlock commitment, the budget. Writes a decision record; sends nothing.",
+    action: "act",
+    visibility: "public",
+    principal: "cell",
+    ercs: [8414, 8434, 8468, 8338],
+    input: z.object({ tokenId: zUint }),
+    output: z.object({ tokenId: zUint, jobId: z.string(), gates: z.array(GateSchema), tender: TenderOutputSchema }),
+    async plan({ node }, { tokenId }) {
+        const id = BigInt(tokenId);
+        const view = await readTender(node, id, { counterparty: true });
+        const gates = await takingGates(node, view);
+        return {
+            job: { id: `precheck:${tokenId}`, kind: "precheck", input: { tokenId }, commitment: true, ephemeral: true },
+            gates,
+            valueWei: 0n,
+            steps: [],
+            output: () => ({ tokenId, jobId: tenderJobId(id, view.facts.completions), gates, tender: tenderOutput(view) }),
+        };
+    },
+};
+const RunOutput = z.object({
+    skill: z.string(),
+    packageHash: zBytes32,
+    jobId: z.string(),
+    answer: z.string(),
+    answerHash: zBytes32,
+    /** sha256(answer ‖ cell): what a hashlock submission by this cell carries. */
+    resultHash: zBytes32,
+    report: z.unknown(),
+    runReceipt: z.unknown(),
+    elapsedMs: z.number(),
+});
+export const skill_run = {
+    name: "skill_run",
+    title: "Run a held skill",
+    description: "Run one of the cell's skills in the isolated worker (foga-probe: view calls at a pinned block; finch-extract-verify: the deterministic extraction over a document inside the input directory or given inline). A job with a persistent result; the same input is the same job.",
+    action: "act",
+    visibility: "caller",
+    principal: "cell",
+    ercs: [8338],
+    input: z.object({ skill: z.string(), input: z.unknown(), tokenId: zUint.optional(), jobId: zJobId }),
+    output: RunOutput,
+    async plan({ node }, input) {
+        const held = await node.heldSkills();
+        const gates = [skillGate(node.config, { skill: input.skill, packageHash: null }, held.map((h) => ({ name: h.name, packageHash: h.packageHash })))];
+        const skill = held.find((h) => h.name === input.skill);
+        const jobId = input.jobId ?? derivedJobId(`skill-run:${input.skill}`, { input: input.input, tokenId: input.tokenId ?? null });
+        const cell = node.body.address;
+        return {
+            job: { id: jobId, kind: "skill-run", input: { skill: input.skill, input: input.input, tokenId: input.tokenId ?? null } },
+            gates,
+            valueWei: 0n,
+            steps: [],
+            work: async () => {
+                if (!skill)
+                    throw new Error(`skill ${input.skill} is not held`);
+                const started = Date.now();
+                let answer;
+                let report;
+                if (input.skill === "foga-probe") {
+                    const probe = input.input;
+                    const run = await runProbeIsolated({ worldPath: node.worldPath, rpc: node.rpc, bundlePath: node.bundlePath, input: probe });
+                    answer = run.answer;
+                    report = run.report;
+                }
+                else if (input.skill === "finch-extract-verify") {
+                    const doc = input.input?.document;
+                    if (!doc)
+                        throw new Error("finch-extract-verify needs input.document: a file name inside the input directory or a data: URI holding the text");
+                    // an inline document is written beside the cell's store and read from there; a named one must be a bare file name in the input directory
+                    let documentPath;
+                    let inputDir = node.inputDir;
+                    if (doc.startsWith("data:")) {
+                        const text = decodeDataUriText(doc);
+                        inputDir = join(dirname(node.storePath), "inline");
+                        mkdirSync(inputDir, { recursive: true });
+                        documentPath = join(inputDir, `${sha256Hex(text).slice(2, 34)}.txt`);
+                        writeFileSync(documentPath, text);
+                    }
+                    else {
+                        if (/[\\/]|\.\./.test(doc))
+                            throw new Error("input.document must be a bare file name inside the input directory");
+                        documentPath = join(node.inputDir, doc);
+                    }
+                    const run = await runExtractIsolated({ documentPath, fieldsPath: join(node.skillsDir, "finch-extract-verify", "fields.json"), packageHash: skill.packageHash, inputDir, skillsDir: node.skillsDir });
+                    answer = run.canonical;
+                    report = run.report;
+                }
+                else
+                    throw new Error(`no executor for skill ${input.skill}; the node runs foga-probe and finch-extract-verify`);
+                const answerHash = hashlock.answerHash(answer);
+                const runReceipt = { schema: "foga.run-receipt/1", skill: input.skill, packageHash: skill.packageHash, tokenId: input.tokenId ?? null, input: input.input, answerHash, fulfiller: accountRef(node.chainId, cell), worker: "isolated child process (skill-worker), view calls only" };
+                return { answer, answerHash, resultHash: hashlock.resultHash(answer, cell), report, runReceipt, elapsedMs: Date.now() - started };
+            },
+            output: (_c, work) => ({ skill: input.skill, packageHash: skill?.packageHash ?? ZERO32, jobId, ...work }),
+        };
+    },
+};
+export const tender_submit = {
+    name: "tender_submit",
+    title: "Submit a fulfillment",
+    description: "Submit the result of a run to a tender through the cell's account (ERC-8414 submitFulfillment): a commitment-class call that passes every taking gate again at the moment of sending. The job is the tender's n-th completion by this cell.",
+    action: "act",
+    visibility: "caller",
+    principal: "cell",
+    ercs: [8414],
+    input: z.object({ tokenId: zUint, resultHash: zBytes32, resultURI: z.string().optional(), runReceipt: z.unknown().optional(), jobId: zJobId }),
+    output: z.object({ tokenId: zUint, submissionId: zUint, txHash: z.string(), operationId: z.string(), jobId: z.string() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const id = BigInt(input.tokenId);
+        const view = await readTender(node, id, { counterparty: true });
+        const gates = await takingGates(node, view);
+        const jobId = input.jobId ?? tenderJobId(id, view.facts.completions);
+        const resultURI = input.resultURI ?? (input.runReceipt ? dataUriJcs(input.runReceipt) : dataUriJcs({ schema: "foga.run-receipt/1", tokenId: input.tokenId, resultHash: input.resultHash, fulfiller: accountRef(node.chainId, node.body.address) }));
+        const intent = { target: k.tenders.address, value: 0n, data: k.tenders.encodeSubmit(id, input.resultHash, resultURI), label: `submitFulfillment(${input.tokenId}, ${input.resultHash.slice(0, 10)}…)` };
+        return {
+            job: { id: jobId, kind: "tender", input: { tokenId: input.tokenId, resultHash: input.resultHash }, commitment: true },
+            gates,
+            valueWei: 0n,
+            steps: [{ name: "submit", kind: "commitment", build: () => intent }],
+            output: (confirmed) => {
+                const c = confirmed[0];
+                return { tokenId: input.tokenId, submissionId: k.tenders.submissionIdFromReceipt(c.receipt).toString(), txHash: c.txHash, operationId: `job:${jobId}:submit`, jobId };
+            },
+        };
+    },
+};
+export const tender_settle = {
+    name: "tender_settle",
+    title: "Settle a submission",
+    description: "Reveal the answer and settle the cell's submission (ERC-8414 settleFulfillment with the hashlock proof); the reward is paid to the account or credited for withdrawal.",
+    action: "act",
+    visibility: "caller",
+    principal: "cell",
+    ercs: [8414],
+    input: z.object({ tokenId: zUint, submissionId: zUint, answer: z.string().optional(), proof: zHex.optional(), jobId: zJobId }),
+    output: z.object({ tokenId: zUint, submissionId: zUint, txHash: z.string(), operationId: z.string(), jobId: z.string(), paidWei: zUint, creditWei: zUint, status: z.number() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const id = BigInt(input.tokenId);
+        const sid = BigInt(input.submissionId);
+        if (!input.answer && !input.proof)
+            throw new Error("pass the answer (text) or the proof (hex)");
+        const proof = input.proof ?? hexlify(toUtf8Bytes(input.answer));
+        const view = await readTender(node, id);
+        const sub = view.submissions.find((s) => s.id === input.submissionId);
+        const gates = [];
+        const [aidState, status] = await Promise.all([k.aid.stateName(node.body.address), node.body.status()]);
+        gates.push(safetyGate(aidState, status, "plain"));
+        if (!sub)
+            gates.push(refused("input", `tender ${input.tokenId} has no submission ${input.submissionId}`));
+        else if (getAddress(sub.fulfiller) !== getAddress(node.body.address))
+            gates.push(refused("policy", `submission ${input.submissionId} is ${sub.fulfiller}'s, not the cell's`));
+        else if (sub.status !== 0)
+            gates.push(refused("policy", `submission ${input.submissionId} is not pending (status ${sub.status})`));
+        else
+            gates.push(ok("policy", `submission ${input.submissionId} by the cell is pending`));
+        const now = await node.now();
+        if (view.facts.settleBy !== 0n && Number(view.facts.settleBy) <= now)
+            gates.push(refused("policy", "past settleBy"));
+        const jobId = input.jobId ?? `${tenderJobId(id, view.facts.completions)}:settle`;
+        const intent = { target: k.tenders.address, value: 0n, data: k.tenders.encodeSettle(id, sid, proof), label: `settleFulfillment(${input.tokenId}, ${input.submissionId})` };
+        const before = await node.body.balance();
+        return {
+            job: { id: jobId, kind: "tender-settle", input: { tokenId: input.tokenId, submissionId: input.submissionId, proofHash: sha256Hex(proof) } },
+            gates,
+            valueWei: 0n,
+            steps: [{ name: "settle", kind: "plain", build: () => intent }],
+            output: async (confirmed) => {
+                const c = confirmed[0];
+                const [after, credit, s] = await Promise.all([node.body.balance(), k.tenders.creditOf(id, node.body.address), k.tenders.submissionOf(id, sid)]);
+                return { tokenId: input.tokenId, submissionId: input.submissionId, txHash: c.txHash, operationId: `job:${jobId}:settle`, jobId, paidWei: (after > before ? after - before : 0n).toString(), creditWei: credit.toString(), status: s.status };
+            },
+        };
+    },
+};
+export const credit_withdraw = {
+    name: "credit_withdraw",
+    title: "Withdraw credited reward",
+    description: "Withdraw the cell's credited reward of a tender (ERC-8414 withdrawCredit), a de-risk action the account allows under a derisk-only suspension.",
+    action: "act",
+    visibility: "caller",
+    principal: "cell",
+    ercs: [8414],
+    input: z.object({ tokenId: zUint, jobId: zJobId }),
+    output: z.object({ tokenId: zUint, withdrawnWei: zUint, txHash: z.string(), operationId: z.string(), jobId: z.string() }),
+    async plan({ node }, input) {
+        const k = node.kernel;
+        const id = BigInt(input.tokenId);
+        const credit = await k.tenders.creditOf(id, node.body.address);
+        const [aidState, status] = await Promise.all([k.aid.stateName(node.body.address), node.body.status()]);
+        const gates = [safetyGate(aidState, status, "derisk")];
+        if (credit === 0n)
+            gates.push(refused("policy", `no credit of tender ${input.tokenId} is due to the cell`));
+        else
+            gates.push(ok("policy", `${credit} wei credited`));
+        const jobId = input.jobId ?? derivedJobId(`credit-withdraw:${input.tokenId}`, { credit: credit.toString() });
+        return {
+            job: { id: jobId, kind: "withdraw", input: { tokenId: input.tokenId } },
+            gates,
+            valueWei: 0n,
+            steps: [{ name: "withdraw", kind: "derisk", build: () => ({ target: k.tenders.address, value: 0n, data: k.tenders.encodeWithdrawCredit(id, node.body.address), label: `withdrawCredit(${input.tokenId}, cell)` }) }],
+            output: (confirmed) => ({ tokenId: input.tokenId, withdrawnWei: credit.toString(), txHash: confirmed[0].txHash, operationId: `job:${jobId}:withdraw`, jobId }),
+        };
+    },
+};
+const MintInput = z.object({
+    skill: z.string(),
+    packageHash: zBytes32,
+    input: z.unknown(),
+    answerHash: zBytes32,
+    rewardWei: zUint,
+    /** Seconds from now. */
+    submitIn: z.coerce.number().int().positive(),
+    settleIn: z.coerce.number().int().positive(),
+    judgmentWindowSeconds: z.coerce.number().int().positive().default(7 * 86400),
+    title: z.string().max(200).optional(),
+    deliverable: z.string().max(500).optional(),
+    /** Whether to fund and commit the answer in the same job (default) or mint only. */
+    fundAndCommit: zBool.default(true),
+    /** Also register an ERC-8444 task record for discovery (act mode). */
+    record: zBool.default(false),
+    as: zAs,
+    jobId: zJobId,
+});
+export const tender_mint = {
+    name: "tender_mint",
+    title: "Mint a hashlock tender",
+    description: "The demander's side: mint an ERC-8414 tender for a skill run with a foga.task/1 document, fund it with the reward and commit the answer hash in the hashlock verifier (one job, three operations), optionally with an ERC-8444 task record. In build mode the three calls are returned for the caller's own account.",
+    action: "act",
+    visibility: "caller",
+    principal: "cell",
+    ercs: [8414, 8444],
+    input: MintInput,
+    output: z.object({ tokenId: zUint, taskHash: zBytes32, answerHash: zBytes32, rewardWei: zUint, submitBy: z.number(), settleBy: z.number(), operations: z.array(z.string()), jobId: z.string(), recordId: zBytes32.nullable() }),
+    async plan(ctx, input) {
+        const { node } = ctx;
+        const k = node.kernel;
+        const now = await node.now();
+        const reward = BigInt(input.rewardWei);
+        const submitBy = now + input.submitIn;
+        const settleBy = now + input.settleIn;
+        if (settleBy <= submitBy)
+            throw new Error("settleIn must be later than submitIn");
+        const task = { schema: "foga.task/1", skill: input.skill, packageHash: input.packageHash, input: input.input, acceptance: { mode: "verifier", profile: "x-hashlock-v1", verifier: k.tenders.hashlockAddress, answerHash: input.answerHash }, deliverable: input.deliverable ?? "the canonical answer; resultHash = sha256(answer || fulfiller)" };
+        TaskDocumentSchema.parse(task);
+        const taskURI = dataUri(task);
+        const taskHash = sha256Hex(JSON.stringify(task));
+        const tdHash = keccakJcs({ td: "foga.task/1", skill: input.skill });
+        const terms = nativeTerms(reward, { submitBy: BigInt(submitBy), settleBy: BigInt(settleBy), judgmentWindow: BigInt(input.judgmentWindowSeconds) });
+        const owner = ctx.mode === "build" ? ctx.as : node.body.address;
+        const jobId = input.jobId ?? derivedJobId("tender-mint", { skill: input.skill, input: input.input, answerHash: input.answerHash, rewardWei: input.rewardWei, submitBy, settleBy, owner });
+        const gates = [];
+        if (ctx.mode !== "build") {
+            const [aidState, status] = await Promise.all([k.aid.stateName(node.body.address), node.body.status()]);
+            gates.push(safetyGate(aidState, status, "plain"));
+            const balance = await node.body.balance();
+            if (input.fundAndCommit && balance < reward)
+                gates.push(refused("budget", `the account holds ${balance} wei; the reward is ${reward} wei`));
+        }
+        const mintIntent = () => ({ target: k.tenders.address, value: 0n, data: k.tenders.encodeMint({ to: owner, updateAuthority: owner, acceptanceAuthority: k.tenders.hashlockAddress, tdHash, taskHash, taskURI, terms }), label: `mintTask(${input.skill}, reward ${reward})` });
+        const tokenOf = (prior) => k.tenders.tokenIdFromReceipt(prior[0].receipt);
+        const steps = [
+            { name: "mint", kind: "plain", build: mintIntent },
+            ...(input.fundAndCommit
+                ? [
+                    { name: "fund", kind: "plain", build: (prior) => ({ target: k.tenders.address, value: reward, data: k.tenders.encodeFund(tokenOf(prior), reward), label: `fundTask(reward ${reward})` }) },
+                    { name: "commit", kind: "plain", build: (prior) => ({ target: k.tenders.hashlockAddress, value: 0n, data: k.tenders.encodeCommitAnswer(tokenOf(prior), input.answerHash), label: `commitAnswer(${input.answerHash.slice(0, 10)}…)` }) },
+                ]
+                : []),
+            ...(input.record && ctx.mode !== "build"
+                ? [
+                    {
+                        name: "record",
+                        kind: "plain",
+                        build: (prior) => {
+                            const tokenId = tokenOf(prior);
+                            const desc = taskDescriptor({ chainId: node.chainId, demander: owner, slug: `tender-${tokenId}`, name: input.title ?? `${input.skill} tender ${tokenId}`, wants: input.deliverable ?? `a run of ${input.skill}`, taskHash, taskURI, bounty: { amount: (Number(reward) / 1e18).toString(), currency: "ETH", asset: `eip155:${node.chainId}/slip44:60` }, acceptance: { mode: "verifier", ref: accountRef(node.chainId, k.tenders.hashlockAddress) }, settleBy, judgmentWindow: `PT${input.judgmentWindowSeconds}S` });
+                            return { target: k.ard.address, value: 0n, data: k.ard.encodeRegister(kindId("task"), k.tenders.address, tokenId, desc), label: `ARD register(task ${tokenId})` };
+                        },
+                    },
+                ]
+                : []),
+        ];
+        // build mode: the calls for the caller's own account, the token id taken from nextId()
+        let calls;
+        if (ctx.mode === "build") {
+            const next = await k.tenders.nextId();
+            calls = [mintIntent()];
+            if (input.fundAndCommit)
+                calls.push({ target: k.tenders.address, value: reward, data: k.tenders.encodeFund(next, reward), label: `fundTask(${next}, ${reward}) — token id assumed from nextId()` }, { target: k.tenders.hashlockAddress, value: 0n, data: k.tenders.encodeCommitAnswer(next, input.answerHash), label: `commitAnswer(${next}) — token id assumed from nextId()` });
+        }
+        return {
+            job: { id: jobId, kind: "tender-mint", input: { task, rewardWei: input.rewardWei, submitBy, settleBy, owner } },
+            gates,
+            valueWei: input.fundAndCommit ? reward : 0n,
+            steps,
+            calls,
+            output: (confirmed) => {
+                const tokenId = confirmed.length ? k.tenders.tokenIdFromReceipt(confirmed[0].receipt) : 0n;
+                const recordStep = steps.findIndex((s) => s.name === "record");
+                const recordId = recordStep >= 0 && confirmed[recordStep] ? k.ard.recordIdFromReceipt(confirmed[recordStep].receipt) : null;
+                return { tokenId: tokenId.toString(), taskHash, answerHash: input.answerHash, rewardWei: input.rewardWei, submitBy, settleBy, operations: steps.slice(0, confirmed.length).map((s) => `job:${jobId}:${s.name}`), jobId, recordId };
+            },
+        };
+    },
+};
+export const tender_fund = {
+    name: "tender_fund",
+    title: "Fund a tender",
+    description: "Add native value to a tender's escrow (ERC-8414 fundTask) from the cell, or as calldata for another funder.",
+    action: "act",
+    visibility: "caller",
+    principal: "cell",
+    ercs: [8414],
+    input: z.object({ tokenId: zUint, amountWei: zUint, as: zAs, jobId: zJobId }),
+    output: z.object({ tokenId: zUint, amountWei: zUint, escrowWei: zUint, txHash: z.string().nullable(), operationId: z.string().nullable(), jobId: z.string() }),
+    async plan(ctx, input) {
+        const { node } = ctx;
+        const k = node.kernel;
+        const id = BigInt(input.tokenId);
+        const amount = BigInt(input.amountWei);
+        const gates = [];
+        if (ctx.mode !== "build") {
+            const [aidState, status] = await Promise.all([k.aid.stateName(node.body.address), node.body.status()]);
+            gates.push(safetyGate(aidState, status, "plain"));
+            const balance = await node.body.balance();
+            if (balance < amount)
+                gates.push(refused("budget", `the account holds ${balance} wei; ${amount} wei asked`));
+        }
+        const jobId = input.jobId ?? derivedJobId(`tender-fund:${input.tokenId}`, { amount: input.amountWei, escrowBefore: (await k.tenders.escrowBalanceOf(id)).toString() });
+        const intent = { target: k.tenders.address, value: amount, data: k.tenders.encodeFund(id, amount), label: `fundTask(${input.tokenId}, ${amount})` };
+        return {
+            job: { id: jobId, kind: "tender-fund", input: { tokenId: input.tokenId, amountWei: input.amountWei } },
+            gates,
+            valueWei: amount,
+            steps: [{ name: "fund", kind: "plain", build: () => intent }],
+            calls: [intent],
+            output: async (confirmed) => ({ tokenId: input.tokenId, amountWei: input.amountWei, escrowWei: (await k.tenders.escrowBalanceOf(id)).toString(), txHash: confirmed[0]?.txHash ?? null, operationId: confirmed.length ? `job:${jobId}:fund` : null, jobId }),
+        };
+    },
+};
+export const TENDER_CAPABILITIES = [tender_precheck, skill_run, tender_submit, tender_settle, credit_withdraw, tender_mint, tender_fund];
+/** For other modules: the gates of taking a tender, as the precheck computes them. */
+export { takingGates };

package/dist/tools/types.js

@@ -0,0 +1,4 @@
+export const ACTION_RANK = { read: 0, build: 1, act: 2, admin: 3 };
+export const VISIBILITY_RANK = { public: 0, caller: 1, operator: 2 };
+export const OPERATOR_CALLER = { id: "operator", entrance: "cli", level: "admin", visibility: "operator" };
+export const PUBLIC_CALLER = { id: "anonymous", entrance: "http", level: "build", visibility: "public" };

package/dist/util/bytecode.js

@@ -0,0 +1,123 @@
+import { keccak256 } from "ethers";
+function hexBody(hex) {
+    return hex.startsWith("0x") ? hex.slice(2) : hex;
+}
+/**
+ * Remove the CBOR metadata trailer solc appends to runtime and creation code.
+ * The last two bytes encode the trailer length (big-endian). We only strip when the
+ * trailer parses as a CBOR map (0xa1..0xa5), which is what solc emits.
+ */
+export function stripMetadata(hex) {
+    const body = hexBody(hex);
+    if (body.length < 4)
+        return "0x" + body;
+    const len = parseInt(body.slice(-4), 16);
+    const total = (len + 2) * 2;
+    if (!Number.isFinite(len) || total > body.length)
+        return "0x" + body;
+    const trailer = body.slice(body.length - total, body.length - 4);
+    const first = trailer.slice(0, 2).toLowerCase();
+    if (!["a1", "a2", "a3", "a4", "a5"].includes(first))
+        return "0x" + body;
+    return "0x" + body.slice(0, body.length - total);
+}
+/**
+ * Zero the content hash inside every CBOR metadata block found anywhere in the code, not only the
+ * trailer. A contract that creates other contracts (TaskToken deploys a TaskVault per token) embeds
+ * their creation code, including their metadata trailer; that nested hash depends on source names and
+ * build paths, so two builds of identical code can differ there. Handles the `ipfs` form
+ * (a2 64 "ipfs" 58 22 <34-byte multihash> ... ) and the legacy `bzzr0`/`bzzr1` form (a1/a2 65 "bzzr?" 58 20 <32 bytes>).
+ * Metadata written with `bytecode_hash = none` carries no hash and is left untouched.
+ */
+export function maskEmbeddedMetadataHashes(hex) {
+    let body = hexBody(hex).toLowerCase();
+    const patterns = [
+        { marker: "a2646970667358" + "22", hashHex: 68 }, // a2 64 'ipfs' 58 22 + 34 bytes
+        { marker: "a165627a7a72305820", hashHex: 64 }, // a1 65 'bzzr0' 58 20 + 32 bytes
+        { marker: "a265627a7a72305820", hashHex: 64 },
+        { marker: "a265627a7a72315820", hashHex: 64 }, // bzzr1
+    ];
+    for (const { marker, hashHex } of patterns) {
+        let from = 0;
+        for (;;) {
+            const at = body.indexOf(marker, from);
+            if (at < 0)
+                break;
+            if (at % 2 === 0 && at + marker.length + hashHex <= body.length) {
+                const start = at + marker.length;
+                body = body.slice(0, start) + "0".repeat(hashHex) + body.slice(start + hashHex);
+            }
+            from = at + 2;
+        }
+    }
+    return "0x" + body;
+}
+/** Zero out every immutable value slot (constructor-set immutables and a library's own deploy address). */
+export function maskImmutables(hex, refs) {
+    let body = hexBody(hex);
+    if (!refs)
+        return "0x" + body;
+    for (const slots of Object.values(refs)) {
+        for (const { start, length } of slots) {
+            const a = start * 2;
+            const b = a + length * 2;
+            if (b <= body.length)
+                body = body.slice(0, a) + "0".repeat(length * 2) + body.slice(b);
+        }
+    }
+    return "0x" + body;
+}
+/** Zero out every linked-library address slot so linked and unlinked code compare equal. */
+export function maskLinks(hex, refs) {
+    if (!refs)
+        return hex.startsWith("0x") ? hex : "0x" + hex;
+    let body = hexBody(hex);
+    for (const libs of Object.values(refs)) {
+        for (const slots of Object.values(libs)) {
+            for (const { start, length } of slots) {
+                const a = start * 2;
+                const b = a + length * 2;
+                if (b <= body.length)
+                    body = body.slice(0, a) + "0".repeat(length * 2) + body.slice(b);
+            }
+        }
+    }
+    return "0x" + body;
+}
+/** Replace library placeholders with the deployed addresses. `resolve` returns a 0x address or undefined. */
+export function linkBytecode(hex, refs, resolve) {
+    let body = hexBody(hex);
+    if (!refs)
+        return "0x" + body;
+    for (const [sourcePath, libs] of Object.entries(refs)) {
+        for (const [libName, slots] of Object.entries(libs)) {
+            const address = resolve(sourcePath, libName);
+            if (!address)
+                throw new Error(`unlinked library ${sourcePath}:${libName}`);
+            const addr = hexBody(address).toLowerCase().padStart(40, "0");
+            if (addr.length !== 40)
+                throw new Error(`bad library address for ${libName}: ${address}`);
+            for (const { start, length } of slots) {
+                if (length !== 20)
+                    throw new Error(`unexpected link slot length ${length} for ${libName}`);
+                const a = start * 2;
+                body = body.slice(0, a) + addr + body.slice(a + 40);
+            }
+        }
+    }
+    if (body.includes("__$"))
+        throw new Error("bytecode still contains unresolved link placeholders");
+    return "0x" + body;
+}
+/**
+ * keccak256 of runtime code with the metadata trailer stripped, every embedded metadata hash zeroed and
+ * every deployment-dependent slot (linked library addresses, immutables, a library's own address) masked:
+ * the "code identity" the doctor compares between a build and a chain. Two builds of the same source with
+ * the same compiler and settings share it whatever their source names or build paths were.
+ */
+export function runtimeIdentity(deployedBytecode, links, immutables) {
+    return keccak256(stripMetadata(maskEmbeddedMetadataHashes(maskImmutables(maskLinks(deployedBytecode, links), immutables))));
+}
+export function codeSize(hex) {
+    return hexBody(hex).length / 2;
+}

package/dist/util/fs.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, rmSync, cpSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Repository root (the directory that holds package.json). */
+export function repoRoot() {
+    // src/util/fs.ts -> repo root is two levels up; dist/util/fs.js -> same shape.
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..", "..");
+}
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+export function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n");
+}
+export function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+export function rmrf(path) {
+    rmSync(path, { recursive: true, force: true });
+}
+export function copyTree(from, to) {
+    mkdirSync(dirname(to), { recursive: true });
+    cpSync(from, to, { recursive: true });
+}
+export function exists(path) {
+    return existsSync(path);
+}
+/** Recursively list files under `dir` (absolute paths). */
+export function walk(dir, out = []) {
+    if (!existsSync(dir))
+        return out;
+    for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        const st = statSync(p);
+        if (st.isDirectory())
+            walk(p, out);
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** Deterministic JSON: keys sorted at every level, no whitespace. */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const k of Object.keys(value).sort())
+            out[k] = sortKeys(value[k]);
+        return out;
+    }
+    return value;
+}

package/dist/util/hash.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function sha256Hex(data) {
+    return "0x" + createHash("sha256").update(data).digest("hex");
+}

package/dist/util/log.js

@@ -0,0 +1,11 @@
+const prefix = "foga";
+export const log = {
+    info: (msg) => console.log(`${prefix}: ${msg}`),
+    warn: (msg) => console.warn(`${prefix}: warning: ${msg}`),
+    error: (msg) => console.error(`${prefix}: error: ${msg}`),
+    step: (msg) => console.log(`  - ${msg}`),
+};
+export function fail(msg) {
+    log.error(msg);
+    process.exit(1);
+}

package/dist/util/version.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { repoRoot } from "./fs.js";
+/** The package version, read once from package.json (the same file the npm package ships). */
+export const version = (() => {
+    try {
+        return String(JSON.parse(readFileSync(join(repoRoot(), "package.json"), "utf8")).version);
+    }
+    catch {
+        return "0.0.0";
+    }
+})();