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

package/dist/core/acdf.js

@@ -0,0 +1,162 @@
+import { keccak256, toUtf8Bytes } from "ethers";
+import { keccakJcs } from "./canonical.js";
+import { eventArgs } from "./world.js";
+/** ERC-8436 Agent Collective Decision Framework: how cells decide together. */
+export const BodyKind = { ROSTER_KOFN: 0, AUTHORIZED_SUBMITTER: 1 };
+export const Acceptance = { ON_CHAIN_TALLY: 0, SIGNED_BALLOTS: 1, AUTHORIZED_SUBMITTER: 2 };
+export const Combinator = { BODY: 0, ALL: 1, ANY: 2, KOFM: 3, VETO: 4 };
+export const VetoSilence = { PASS_THROUGH: 0, REQUIRE_CLEARANCE: 1 };
+export const AppealStanding = { ANYONE: 0, CONSUMER_OR_FILER: 1 };
+export const AppealMode = { PRESERVE_UNLESS_OVERTURNED: 0, REQUIRE_FRESH_DECISION: 1 };
+export const ProcedureStateName = ["None", "Filed", "Deciding", "Provisional", "Final", "Withdrawn"];
+export const OutcomeTypeName = ["None", "Decided", "NoDecision"];
+export const ReasonName = ["NONE", "QUORUM_NOT_MET", "SUBMITTER_SILENT", "VETOED", "NO_CLEARANCE", "NOT_REACHED", "TOTAL_TIMEOUT", "NO_ACCEPTANCE"];
+export const EnactmentStatusName = ["NotEnacted", "Enacted", "Failed"];
+const ZERO32 = "0x" + "00".repeat(32);
+export function familyId(name) {
+    return keccak256(toUtf8Bytes(name));
+}
+/**
+ * The FOGA-Council policy: one roster body of judges deciding K-of-N by on-chain tally within `window`, one
+ * appeal allowed for a Decided result (an appeal round that ends without a decision preserves the first one),
+ * no appeal of a NoDecision, hard cap covering every round and the appeal window.
+ */
+export function councilPolicySpec(p) {
+    const maxAppeals = 1;
+    return {
+        family: familyId("foga.council"),
+        version: p.version ?? 1,
+        previous: p.previous ?? ZERO32,
+        updateAuthority: p.updateAuthority,
+        bodies: [{ kind: BodyKind.ROSTER_KOFN, acceptance: Acceptance.ON_CHAIN_TALLY, members: p.judges, k: p.k, window: p.window }],
+        nodes: [{ op: Combinator.BODY, body: 0, k: 0, target: 0, vetoBody: 0, silence: VetoSilence.PASS_THROUGH, children: [] }],
+        maxAppeals,
+        appealWindow: p.appealWindow,
+        appealable: 1, // bit0: Decided results may be appealed; a NoDecision is final at once
+        appealStanding: AppealStanding.ANYONE,
+        appealMode: AppealMode.PRESERVE_UNLESS_OVERTURNED,
+        maxTotalDuration: p.window * (maxAppeals + 1) + p.appealWindow * maxAppeals,
+        ackWindow: 0,
+        allowAdvisory: false,
+        descriptorHash: keccakJcs(p.descriptor),
+    };
+}
+/** The off-chain descriptor the policy's descriptorHash commits to. */
+export function councilDescriptor(p) {
+    return {
+        acdf: "1.0",
+        kind: "policy-descriptor",
+        name: "FOGA-Council",
+        summary: "The judging body of the Finch OG Agent genesis: three judges, two approvals decide, one appeal of a decision, silence is no decision.",
+        bodies: [{ role: "judge", members: p.judges.map((j) => j.toLowerCase()), k: p.k, acceptance: "on-chain-tally", window: p.window }],
+        appeals: { max: 1, window: p.appealWindow, appealable: ["Decided"], mode: "preserve-unless-overturned" },
+        consumers: ["ACDFTaskTenderAdapter (ERC-8414 acceptance)", "ADRFACDFBridge (ERC-8471 judgment tier, phase 2b)"],
+        independence: "A judge is never a party: not a demander, fulfiller, swarm member or world operator of the matter judged; checked by the genesis before each case.",
+    };
+}
+export class ACDF {
+    world;
+    constructor(world) {
+        this.world = world;
+    }
+    policies(runner) {
+        return this.world.contract("8436/ACDFPolicyRegistry", runner);
+    }
+    registry(runner) {
+        return this.world.contract("8436/ACDFRegistry", runner);
+    }
+    get policyRegistryAddress() {
+        return this.world.address("8436/ACDFPolicyRegistry");
+    }
+    get registryAddress() {
+        return this.world.address("8436/ACDFRegistry");
+    }
+    encodeRegisterPolicy(spec) {
+        return this.policies().interface.encodeFunctionData("registerPolicy", [spec]);
+    }
+    async policyIdOf(spec) {
+        return this.policies().policyIdOf(spec);
+    }
+    policyIdFromReceipt(receipt) {
+        return eventArgs(this.policies().interface, receipt, "PolicyRegistered", this.policyRegistryAddress).policyId;
+    }
+    encodeCastBallot(issueId, round, body, approve) {
+        return this.registry().interface.encodeFunctionData("castBallot", [issueId, round, body, approve]);
+    }
+    encodeSettleRound(issueId) {
+        return this.registry().interface.encodeFunctionData("settleRound", [issueId]);
+    }
+    encodeFinalize(issueId) {
+        return this.registry().interface.encodeFunctionData("finalize", [issueId]);
+    }
+    async getResult(issueId) {
+        const r = await this.registry().getResult(issueId);
+        const state = Number(r.state);
+        const outcomeType = Number(r.outcomeType);
+        const reason = Number(r.reason);
+        return {
+            state,
+            stateName: ProcedureStateName[state] ?? String(state),
+            outcomeType,
+            outcomeName: OutcomeTypeName[outcomeType] ?? String(outcomeType),
+            outcomeYes: Boolean(r.outcomeYes),
+            reason,
+            reasonName: ReasonName[reason] ?? String(reason),
+            roundCount: Number(r.roundCount),
+            sourceRound: Number(r.sourceRound),
+            adoptedFromEarlierRound: Boolean(r.adoptedFromEarlierRound),
+            decidedAt: BigInt(r.decidedAt),
+            finalAt: BigInt(r.finalAt),
+        };
+    }
+    async roundOf(issueId) {
+        return Number((await this.registry().getIssue(issueId)).roundCount);
+    }
+    async roundState(issueId, round) {
+        const r = await this.registry().getRound(issueId, round);
+        return { startedAt: BigInt(r.startedAt), deadline: BigInt(r.deadline), settled: Boolean(r.settled), appealOpenUntil: BigInt(r.appealOpenUntil) };
+    }
+    async hasVoted(issueId, round, body, voter) {
+        return this.registry().hasVoted(issueId, round, body, voter);
+    }
+    async enactment(issueId, consumer, effectId) {
+        const e = await this.registry().getEnactment(issueId, consumer, effectId);
+        const status = Number(e.status);
+        return { status, statusName: EnactmentStatusName[status] ?? String(status), reporter: e.reporter, ref: e.ref };
+    }
+    /** Decode the first IssueFiled event of a receipt (filed by an adapter). */
+    issueIdFromReceipt(receipt) {
+        return eventArgs(this.registry().interface, receipt, "IssueFiled", this.registryAddress).issueId;
+    }
+}
+/** An ACDFTaskTenderAdapter instance (the upstream adapter, deployed by FOGA for its policy). */
+export class TenderAdapterRef {
+    world;
+    address;
+    iface;
+    constructor(world, address) {
+        this.world = world;
+        this.address = address;
+        this.iface = world.ifaceOf("acd-framework:ACDFTaskTenderAdapter");
+    }
+    contract(runner) {
+        return this.world.at("acd-framework:ACDFTaskTenderAdapter", this.address, runner);
+    }
+    encodeOpen(tokenId, submissionId) {
+        return this.iface.encodeFunctionData("open", [tokenId, submissionId]);
+    }
+    encodeExecute(issueId) {
+        return this.iface.encodeFunctionData("execute", [issueId]);
+    }
+    issueIdFromReceipt(receipt) {
+        return eventArgs(this.iface, receipt, "CaseOpened", this.address).issueId;
+    }
+    async caseOf(issueId) {
+        const c = await this.contract().caseOf(issueId);
+        return { exists: Boolean(c.exists), enacted: Boolean(c.enacted), tokenId: BigInt(c.tokenId), submissionId: BigInt(c.submissionId), consumerDeadline: BigInt(c.consumerDeadline) };
+    }
+    async effects() {
+        const c = this.contract();
+        return { accept: await c.EFFECT_ACCEPT(), reject: await c.EFFECT_REJECT() };
+    }
+}

package/dist/core/adrf.js

@@ -0,0 +1,273 @@
+import { keccak256, toUtf8Bytes } from "ethers";
+import { abi, keccakJcs } from "./canonical.js";
+import { eventArgs } from "./world.js";
+/**
+ * ERC-8471 AI Dispute Resolution Framework: disputes about deliveries and declarations, decided by methods a
+ * policy binds (a deterministic verifier, an evidence rule, or an ERC-8436 collective decision through the
+ * bridge), with rulings enacted by the bound business contract within its own authority.
+ */
+export const QuestionType = { FORMAL: 0, EVIDENCED: 1, JUDGED: 2 };
+export const Value = { UNDETERMINED: 0, TRUE: 1, FALSE: 2 };
+export const ValueName = ["UNDETERMINED", "TRUE", "FALSE"];
+export const AcceptanceMode = { PRE_COMMIT: 0, POST_DISPUTE: 1 };
+export const EffectClass = { Advisory: 0, Binding: 1 };
+export const EffectCategory = { SUBSTANTIVE: 0, PROCEDURAL_ECONOMIC: 1 };
+export const OnUndetermined = { NOT_SUSTAINED: 0, NO_DECISION: 1 };
+export const StandingMode = { PARTIES: 0, BENEFICIARIES: 1, OPEN: 2 };
+export const SilenceRule = { NONE: 0, SUSTAIN: 1, NOT_SUSTAIN: 2 };
+export const ReviewMode = { PRESERVE_UNLESS_OVERTURNED: 0, REQUIRE_FRESH_DECISION: 1 };
+export const ProcedureStateName = ["None", "Filed", "Admitted", "Provisional", "Final", "NotAdmitted", "Withdrawn", "Expired"];
+export const SubstantiveResultName = ["None", "Sustained", "NotSustained", "NoDecision"];
+export const ReasonName = ["NONE", "MISSING_ELEMENT", "NO_BINDING_AUTHORITY", "CLOCK_INCOMPATIBLE", "DUPLICATE", "PREMISE_NOT_ESTABLISHED", "METHOD_UNDETERMINED", "BURDEN_NOT_MET", "TIMEOUT", "REVIEW_LAPSED", "ACCEPTANCE_LAPSED", "SILENCE", "PROCEDURE_FAILURE"];
+export const EnactmentStatusName = ["NotRequested", "Pending", "Enacted", "Failed", "Unknown"];
+export const SettlementStateName = ["Held", "Released", "Refunded"];
+export const REVIEW_FACT = 1;
+export const REVIEW_EVIDENCE = 2;
+export const REVIEW_RULE_APPLICATION = 4;
+export const RESULT_PROFILE_V1 = keccak256(toUtf8Bytes("adrf:result/v1"));
+/** Obligation kinds as the worked-example escrow declares them. */
+export const KIND_RESULT = 1;
+export const KIND_LIMIT = 3;
+/** Identifiers of the worked-example escrow (ADRFServiceEscrow). */
+export const EFFECT_REFUND = keccak256(toUtf8Bytes("adrf:effect/refund"));
+export const DISPOSITION_STATUS_QUO = keccak256(toUtf8Bytes("adrf:disposition/status-quo"));
+export const EVENT_DELIVERY = keccak256(toUtf8Bytes("delivery"));
+export const STATEMENT_ACTUAL_VERSION = keccak256(toUtf8Bytes("the version actually used for the call matches the committed version"));
+const DECLARED_VERSION_STATEMENT = keccak256(toUtf8Bytes("adrf:prop/declared-version-differs/v1"));
+const ZERO32 = "0x" + "00".repeat(32);
+export function familyId(name) {
+    return keccak256(toUtf8Bytes(name));
+}
+/**
+ * FOGA-Service-v1: the dispute policy for service calls between cells. A (result, FORMAL) question goes to the
+ * upstream DeclaredVersionVerifier over the escrow; a (result, JUDGED) question goes to FOGA-Council through
+ * the ADRF/ACDF bridge, with NO_DECISION as the burden rule (an undecided council leaves the status quo). One
+ * substantive effect: the escrow's refund. Standing: the parties of the call. One review round.
+ */
+export function servicePolicySpec(p) {
+    const t = p.timing;
+    const maxReviews = 1;
+    return {
+        family: familyId("foga.service"),
+        version: p.version ?? 1,
+        previous: p.previous ?? ZERO32,
+        updateAuthority: p.updateAuthority,
+        objectKind: keccak256(toUtf8Bytes("service-call")),
+        methods: [
+            { obligationKind: KIND_RESULT, qType: QuestionType.FORMAL, method: p.versionVerifier, params: addressParam(p.escrow), onUndetermined: OnUndetermined.NOT_SUSTAINED },
+            { obligationKind: KIND_RESULT, qType: QuestionType.JUDGED, method: p.bridge, params: p.councilPolicyId, onUndetermined: OnUndetermined.NO_DECISION },
+        ],
+        effects: [{ id: EFFECT_REFUND, category: EffectCategory.SUBSTANTIVE }],
+        track: {
+            filingWindow: t.filingWindow,
+            acceptanceWindow: 0,
+            evidenceWindow: t.evidenceWindow,
+            decisionWindow: t.decisionWindow,
+            reviewWindow: t.reviewWindow,
+            maxReviews,
+            reviewTypes: REVIEW_FACT | REVIEW_EVIDENCE | REVIEW_RULE_APPLICATION,
+            reviewMode: ReviewMode.PRESERVE_UNLESS_OVERTURNED,
+            maxTotalDuration: t.decisionWindow + maxReviews * (t.reviewWindow + t.decisionWindow),
+            enactmentMargin: t.enactmentMargin,
+            optimistic: false,
+            answerWindow: 0,
+            silenceRule: SilenceRule.NONE,
+        },
+        standing: StandingMode.PARTIES,
+        resultProfile: RESULT_PROFILE_V1,
+        economicDeclaration: keccakJcs({ kind: "economic-declaration", name: "FOGA-Service-v1", bonds: "none", fees: "none", rewards: "none" }),
+        descriptorHash: keccakJcs(p.descriptor),
+    };
+}
+/** The off-chain descriptor the policy's descriptorHash commits to. */
+export function serviceDescriptor(p) {
+    return {
+        adrf: "0.2",
+        kind: "policy-descriptor",
+        name: "FOGA-Service-v1",
+        summary: "Disputes about service calls between Finch OG Agent cells settled through the worked-example escrow: a formal question on the declared version, a judged question on the version actually used, decided by FOGA-Council; one effect, the refund of the held settlement.",
+        object: { kind: "service-call", escrow: p.escrow.toLowerCase() },
+        methods: [
+            { obligation: "result", question: "FORMAL", method: p.versionVerifier.toLowerCase(), params: "the escrow", burden: "NOT_SUSTAINED" },
+            { obligation: "result", question: "JUDGED", method: p.bridge.toLowerCase(), params: p.councilPolicyId, burden: "NO_DECISION" },
+        ],
+        effects: [{ id: "adrf:effect/refund", category: "substantive", executor: "the escrow, within the settlement it holds" }],
+        windows: { ...p.timing },
+        standing: "parties",
+        reviews: { max: 1, mode: "preserve-unless-overturned", types: ["fact", "evidence", "rule-application"] },
+        noDecision: "status quo: balances stay where the call left them",
+    };
+}
+export function addressParam(a) {
+    return "0x" + a.toLowerCase().replace(/^0x/, "").padStart(64, "0");
+}
+/** The declared-version verifier's canonical proposition for a call of a service. */
+export function declaredVersionProposition(service, callId) {
+    return keccak256(abi.encode(["bytes32", "address", "uint256"], [DECLARED_VERSION_STATEMENT, service, callId]));
+}
+export function declaredVersionInputs(callId) {
+    return abi.encode(["uint256"], [callId]);
+}
+export function declaredVersionInputsHash(callId) {
+    return keccak256(declaredVersionInputs(callId));
+}
+export class ADRF {
+    world;
+    constructor(world) {
+        this.world = world;
+    }
+    policies(runner) {
+        return this.world.contract("8471/ADRFPolicyRegistry", runner);
+    }
+    /** The dispute registry through its full interface: the deployed contract is a router whose own ABI only names its modules. */
+    registry(runner) {
+        return this.world.at("ai-dispute-resolution:IADRFDisputeRegistry", this.registryAddress, runner);
+    }
+    bridge(runner) {
+        return this.world.contract("8471/ADRFACDFBridge", runner);
+    }
+    escrow(runner) {
+        return this.world.contract("8471/ADRFServiceEscrow", runner);
+    }
+    get policyRegistryAddress() {
+        return this.world.address("8471/ADRFPolicyRegistry");
+    }
+    get registryAddress() {
+        return this.world.address("8471/ADRFDisputeRegistry");
+    }
+    get bridgeAddress() {
+        return this.world.address("8471/ADRFACDFBridge");
+    }
+    get escrowAddress() {
+        return this.world.address("8471/ADRFServiceEscrow");
+    }
+    get versionVerifierAddress() {
+        return this.world.address("8471/DeclaredVersionVerifier");
+    }
+    policyIdFromReceipt(receipt) {
+        return eventArgs(this.policies().interface, receipt, "PolicyRegistered", this.policyRegistryAddress).policyId;
+    }
+    bindingIdFromReceipt(receipt) {
+        return eventArgs(this.registry().interface, receipt, "BindingRegistered", this.registryAddress).bindingId;
+    }
+    caseIdFromReceipt(receipt) {
+        return eventArgs(this.registry().interface, receipt, "CaseFiled", this.registryAddress).caseId;
+    }
+    callIdFromReceipt(receipt) {
+        return BigInt(eventArgs(this.escrow().interface, receipt, "CallOpened", this.escrowAddress).callId);
+    }
+    // ---- escrow (business) ----
+    encodeDeposit() {
+        return this.escrow().interface.encodeFunctionData("deposit", []);
+    }
+    encodeOpenCall(provider, amount, termsHash, committedVersion, disputePeriod) {
+        return this.escrow().interface.encodeFunctionData("openCall", [provider, amount, termsHash, committedVersion, disputePeriod]);
+    }
+    encodeDeliver(callId, declaredVersion) {
+        return this.escrow().interface.encodeFunctionData("deliver", [callId, declaredVersion]);
+    }
+    encodeSettle(callId) {
+        return this.escrow().interface.encodeFunctionData("settle", [callId]);
+    }
+    encodeRelease(callId) {
+        return this.escrow().interface.encodeFunctionData("release", [callId]);
+    }
+    encodeWithdrawBalance(amount) {
+        return this.escrow().interface.encodeFunctionData("withdrawBalance", [amount]);
+    }
+    encodeEnact(caseId, effectId) {
+        return this.escrow().interface.encodeFunctionData("enact", [caseId, effectId]);
+    }
+    async objectOf(callId) {
+        const o = await this.escrow().objectOf(callId);
+        return { chainId: BigInt(o.chainId), target: o.target, id: BigInt(o.id), versionHash: o.versionHash };
+    }
+    async call(callId) {
+        const c = await this.escrow().calls(callId);
+        return { client: c.client, provider: c.provider, amount: BigInt(c.amount), termsHash: c.termsHash, committedVersion: c.committedVersion, declaredVersion: c.declaredVersion, createdAt: Number(c.createdAt), deliveredAt: Number(c.deliveredAt), disputePeriod: Number(c.disputePeriod) };
+    }
+    async settlementOf(callId, ordinal) {
+        const s = await this.escrow().settlementOf(callId, ordinal);
+        // positional: the output is named `at`, which on an ethers Result is shadowed by Array.prototype.at
+        const state = Number(s[1]);
+        return { at: Number(s[0]), state, stateName: SettlementStateName[state] ?? String(state) };
+    }
+    async escrowBalanceOf(account) {
+        return BigInt(await this.escrow().balanceOf(account));
+    }
+    async heldOf(callId) {
+        return BigInt(await this.escrow().heldOf(callId));
+    }
+    // ---- registry (procedure) ----
+    encodeFile(bindingId, claim) {
+        return this.registry().interface.encodeFunctionData("file", [bindingId, claim]);
+    }
+    async getCase(caseId) {
+        const c = await this.registry().getCase(caseId);
+        const state = Number(c.state);
+        return { state, stateName: ProcedureStateName[state] ?? String(state), effectClass: Number(c.effectClass), claimant: c.claimant, respondent: c.respondent, source: c.source, bindingId: c.bindingId, exclusivityKey: c.exclusivityKey, decisive: Number(c.decisive) };
+    }
+    async getClock(caseId) {
+        const c = await this.registry().getClock(caseId);
+        return { eventAt: Number(c.eventAt), filedAt: Number(c.filedAt), admittedAt: Number(c.admittedAt), decisionDeadline: Number(c.decisionDeadline), hardDeadline: Number(c.hardDeadline), reviewOpenUntil: Number(c.reviewOpenUntil), roundCount: Number(c.roundCount) };
+    }
+    async getFinding(caseId, subQuestion) {
+        const f = await this.registry().getFinding(caseId, subQuestion);
+        const value = Number(f.value);
+        const reason = Number(f.reason);
+        return { resolved: Boolean(f.resolved), value, valueName: ValueName[value] ?? String(value), supportKinds: Number(f.supportKinds), acceptedBy: f.acceptedBy, reason, reasonName: ReasonName[reason] ?? String(reason), issueId: f.source.issueId };
+    }
+    async getRuling(caseId) {
+        const u = await this.registry().getRuling(caseId);
+        const state = Number(u.state);
+        const result = Number(u.result);
+        const reason = Number(u.reason);
+        const closure = Number(u.closure);
+        return { state, stateName: ProcedureStateName[state] ?? String(state), result, resultName: SubstantiveResultName[result] ?? String(result), reason, reasonName: ReasonName[reason] ?? String(reason), closure, closureName: ReasonName[closure] ?? String(closure), allowedEffect: u.allowedEffect, fallbackRef: u.fallbackRef, supportKinds: Number(u.supportKinds), judgmentIssueId: u.judgment.issueId };
+    }
+    async getEnactment(caseId, effectId) {
+        const e = await this.registry().getEnactment(caseId, effectId);
+        const status = Number(e.status);
+        return { status, statusName: EnactmentStatusName[status] ?? String(status), reporter: e.reporter, ref: e.ref };
+    }
+    async issueOf(caseId, subQuestion) {
+        return this.bridge().issueOf(keccak256(abi.encode(["bytes32", "uint32"], [caseId, subQuestion])));
+    }
+}
+/** Builders for the dispute of T6 (the delivered version is not the committed one). */
+export const claims = {
+    /**
+     * The claim of a client against a provider on the delivery of a call: "the service did not run the committed
+     * version". Sub-question 0 (FORMAL, informative): the declared version differs from the committed one, decided by
+     * the verifier over the escrow's own records. Sub-question 1 (JUDGED, decisive): "the version actually used
+     * matches the committed version", put to FOGA-Council; the claim is sustained when the council finds it FALSE.
+     */
+    versionCommitment(p) {
+        return {
+            object: p.object,
+            eventRef: EVENT_DELIVERY,
+            proposition: keccak256(toUtf8Bytes("claim: the service did not run the committed version")),
+            normRef: p.termsHash,
+            clause: keccak256(toUtf8Bytes("terms: the service runs the committed version")),
+            obligationKind: KIND_RESULT,
+            respondent: p.provider,
+            actorRef: ZERO32,
+            requestedEffects: [EFFECT_REFUND],
+            effectOnSustained: EFFECT_REFUND,
+            effectOnNotSustained: ZERO32,
+            fallbackRef: DISPOSITION_STATUS_QUO,
+            evidenceScopeHash: p.evidenceScopeHash,
+            documentHash: p.documentHash,
+            decisive: 1,
+            supportsWhen: Value.FALSE,
+            subQuestions: [
+                { proposition: declaredVersionProposition(p.escrow, p.callId), qType: QuestionType.FORMAL, obligationKind: KIND_RESULT, inputsHash: declaredVersionInputsHash(p.callId), dependsOn: [], requiredValues: [] },
+                { proposition: STATEMENT_ACTUAL_VERSION, qType: QuestionType.JUDGED, obligationKind: KIND_RESULT, inputsHash: ZERO32, dependsOn: [], requiredValues: [] },
+            ],
+        };
+    },
+};
+/** The escrow's binding to FOGA-Service-v1: all its calls, pre-committed, the refund authorized, the escrow as executor. */
+export function escrowBindingInput(policyId, termsHash) {
+    return { policyId, scopeKey: ZERO32, mode: AcceptanceMode.PRE_COMMIT, authorizedEffects: [EFFECT_REFUND], executors: [], beneficiaries: [], openChallenge: false, downgradeOnClock: false, validUntil: 0, termsHash };
+}

package/dist/core/aid.js

@@ -0,0 +1,83 @@
+import { keccak256, toUtf8Bytes } from "ethers";
+import { accountRef, dataUriJcs, jcs, keccakUtf8 } from "./canonical.js";
+/** ERC-8434 Agent Identity: the address-anchored identity and liveness of a cell. */
+export const AIDState = { DORMANT: 0, ACTIVE: 1, STALE: 2, RETIRED: 3 };
+export const AIDStateName = ["DORMANT", "ACTIVE", "STALE", "RETIRED"];
+export function facetTypeKey(facetType) {
+    return keccak256(toUtf8Bytes(facetType));
+}
+/**
+ * A second ERC-8434 instance another standard's adapter reads. On Sepolia the ERC-8444 agent kind is anchored to
+ * ARD's own fixture AIDRegistry, not to aid-standard's reference instance (docs/version-lock.md, seam 1); a cell
+ * whose records must resolve as backed keeps its liveness in both. The world file names it under this id.
+ */
+export const BACKING_REGISTRY_ID = "8434/AIDRegistry(ard-fixture)";
+export class AID {
+    world;
+    address;
+    /** The backing registry, when the world has one at another address than the primary registry. */
+    backing;
+    constructor(world) {
+        this.world = world;
+        this.address = world.address("8434/AIDRegistry");
+        const backing = world.has(BACKING_REGISTRY_ID) ? world.address(BACKING_REGISTRY_ID) : null;
+        this.backing = backing && backing.toLowerCase() !== this.address.toLowerCase() ? { id: BACKING_REGISTRY_ID, address: backing } : null;
+    }
+    contract(runner) {
+        return this.world.contract("8434/AIDRegistry", runner);
+    }
+    /** The same ABI at another registry address (the backing registry). */
+    at(address, runner) {
+        return this.world.at("aid-standard:AIDRegistry", address, runner);
+    }
+    encodeBind(identityRegistry, agentId) {
+        return this.contract().interface.encodeFunctionData("bind", [identityRegistry, agentId]);
+    }
+    encodeHeartbeat() {
+        return this.contract().interface.encodeFunctionData("heartbeat", []);
+    }
+    encodeSetDocumentURI(uri, digest) {
+        return this.contract().interface.encodeFunctionData("setDocumentURI", [uri, digest]);
+    }
+    encodeSetFacet(facetType, digest, validFrom, validUntil, access, uri) {
+        return this.contract().interface.encodeFunctionData("setFacet", [facetTypeKey(facetType), digest, validFrom, validUntil, access, uri]);
+    }
+    encodeRetire(successor) {
+        return this.contract().interface.encodeFunctionData("retire", [successor]);
+    }
+    /** `window` in seconds, at most the registry's maximum; 0 restores the registry's default. */
+    encodeSetLivenessWindow(window) {
+        return this.contract().interface.encodeFunctionData("setLivenessWindow", [window]);
+    }
+    async state(anchor, registry = this.address) {
+        return Number(await this.at(registry).state(anchor));
+    }
+    async stateName(anchor, registry = this.address) {
+        return AIDStateName[await this.state(anchor, registry)];
+    }
+    async livenessWindow(anchor) {
+        return Number(await this.contract().livenessWindow(anchor));
+    }
+    async defaultLivenessWindow() {
+        return Number(await this.contract().defaultLivenessWindow());
+    }
+    async bindingOf(anchor) {
+        const b = await this.contract().bindingOf(anchor);
+        return { registry: b.registry, agentId: BigInt(b.agentId), boundAt: BigInt(b.boundAt) };
+    }
+    async documentURI(anchor) {
+        const r = await this.contract().documentURI(anchor);
+        return { uri: r.uri ?? r[0], digest: r.digest ?? r[1] };
+    }
+    async lastSeen(anchor) {
+        return BigInt(await this.contract().lastSeen(anchor));
+    }
+    /** The AID document and its on-chain commitment: keccak256(UTF-8(JCS(document))). */
+    static documentCommitment(doc) {
+        const canonical = jcs(doc);
+        return { jcs: canonical, digest: keccakUtf8(canonical), uri: dataUriJcs(doc) };
+    }
+    static aidOf(chainId, anchor) {
+        return accountRef(chainId, anchor);
+    }
+}

package/dist/core/ard.js

@@ -0,0 +1,146 @@
+import { keccak256, toUtf8Bytes } from "ethers";
+import { abi, accountRef, dataUri, jcs, sha256Hex } from "./canonical.js";
+import { eventArgs } from "./world.js";
+/** ERC-8444 ARD Onchain: how cells, skills and tasks are found. */
+export const ARDStatus = { None: 0, Active: 1, Suspended: 2, Retired: 3 };
+export function kindId(name) {
+    return keccak256(toUtf8Bytes(`ard-onchain.kind.${name}`));
+}
+const PUBLICATION_MEMBERS = ["@context", "@id", "identifier", "trustManifest"];
+const RESOLVED_MEMBERS = ["value:anchor", "value:adopted", "value:binding", "value:level", "value:status", "value:aliases", "value:canonical", "value:registry", "value:descriptorHash", "value:stale", "value:claimedUrn"];
+/** The authored (content) members of a descriptor: publication and resolver-computed members removed. */
+export function authoredDescriptor(entry) {
+    const out = {};
+    for (const [k, v] of Object.entries(entry)) {
+        if (PUBLICATION_MEMBERS.includes(k) || RESOLVED_MEMBERS.includes(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/** descriptorHash = SHA-256(JCS(authored descriptor)). */
+export function descriptorHash(entry) {
+    const canonical = jcs(authoredDescriptor(entry));
+    const hex = sha256Hex(canonical);
+    return { canonical, hex, digest: `sha256:${hex.slice(2)}` };
+}
+export function recordIdOf(chainId, target, id) {
+    return keccak256(abi.encode(["uint256", "address", "uint256"], [chainId, target, id]));
+}
+const CONTEXT = ["https://agenticresourcediscovery.org/context/v1", { value: "https://eips.ethereum.org/assets/eip-8444/ns#" }];
+export function agentDescriptor(p) {
+    return {
+        "@context": CONTEXT,
+        identifier: `urn:air:${p.domain ?? "foga.local"}:agents:${p.slug}`,
+        type: "application/a2a-agent-card+json",
+        displayName: p.name,
+        description: p.description,
+        url: p.url ?? "",
+        tags: p.tags ?? ["foga", "cell"],
+        capabilities: p.capabilities ?? [],
+        version: "1",
+        trustManifest: { identity: p.domain ?? "foga.local" },
+        "value:kind": "agent",
+        "value:controller": `did:pkh:eip155:${p.chainId}:${p.anchor.toLowerCase()}`,
+        ...(p.registration ? { "value:registration": p.registration } : {}),
+        ...(p.settlement ? { "value:settlement": p.settlement } : {}),
+        ...(p.credit ? { "value:credit": p.credit } : {}),
+    };
+}
+export function skillDescriptor(p) {
+    return {
+        "@context": CONTEXT,
+        identifier: `urn:air:${p.domain ?? "foga.local"}:skills:${p.slug}`,
+        type: "application/vnd.erc8338.skill+json",
+        displayName: p.name,
+        description: p.description,
+        url: p.packageURI,
+        tags: p.tags ?? ["foga", "skill"],
+        version: "1",
+        trustManifest: { identity: p.domain ?? "foga.local" },
+        "value:kind": "skill",
+        "value:controller": `did:pkh:eip155:${p.chainId}:${p.controller.toLowerCase()}`,
+        "value:terms": { unit: "call", price: p.price ?? { amount: "0", currency: "ETH", asset: `eip155:${p.chainId}/slip44:60` } },
+        "value:settlement": [{ rail: "onchain", payee: accountRef(p.chainId, p.payee ?? p.controller), asset: `eip155:${p.chainId}/slip44:60` }],
+        "value:provenance": { packageDigest: `sha256:${p.packageHash.replace(/^0x/, "")}` },
+    };
+}
+export function taskDescriptor(p) {
+    return {
+        "@context": CONTEXT,
+        identifier: `urn:air:${p.domain ?? "foga.local"}:tasks:${p.slug}`,
+        type: "application/ai-task+json",
+        displayName: p.name,
+        description: p.wants,
+        url: p.taskURI,
+        tags: ["foga", "task"],
+        version: "1",
+        trustManifest: { identity: p.domain ?? "foga.local" },
+        data: {
+            wants: p.wants,
+            specDigest: `sha256:${p.taskHash.replace(/^0x/, "")}`,
+            specURI: p.taskURI,
+            bounty: p.bounty,
+            cardinality: "1-of-1",
+            copies: 1,
+            acceptance: p.acceptance,
+            deadlines: { ...(p.settleBy ? { settleBy: new Date(p.settleBy * 1000).toISOString() } : {}), judgmentWindow: p.judgmentWindow },
+        },
+        "value:kind": "task",
+        "value:controller": `did:pkh:eip155:${p.chainId}:${p.demander.toLowerCase()}`,
+        "value:provenance": { packageDigest: `sha256:${p.taskHash.replace(/^0x/, "")}` },
+    };
+}
+export class ARD {
+    world;
+    address;
+    constructor(world) {
+        this.world = world;
+        this.address = world.address("8444/ARDOnchainRegistry");
+    }
+    contract(runner) {
+        return this.world.contract("8444/ARDOnchainRegistry", runner);
+    }
+    /** Publication form: descriptorURI as a data: URI, descriptorHash over the authored members, urn = identifier. */
+    publication(descriptor) {
+        return { descriptorHash: descriptorHash(descriptor).hex, descriptorURI: dataUri(descriptor), urn: String(descriptor.identifier ?? "") };
+    }
+    encodeRegister(kind, target, id, descriptor) {
+        const p = this.publication(descriptor);
+        return this.contract().interface.encodeFunctionData("register", [kind, target, id, p.descriptorHash, p.descriptorURI, p.urn]);
+    }
+    /** Recommit a record's current descriptor unchanged: the adoption of a record by its new controller. */
+    encodeRecommit(recordId, rec) {
+        return this.contract().interface.encodeFunctionData("updateDescriptor", [recordId, rec.descriptorHash, rec.descriptorURI, rec.urn]);
+    }
+    encodeUpdateDescriptor(recordId, descriptor) {
+        const p = this.publication(descriptor);
+        return this.contract().interface.encodeFunctionData("updateDescriptor", [recordId, p.descriptorHash, p.descriptorURI, p.urn]);
+    }
+    async register(signer, kind, target, id, descriptor) {
+        const p = this.publication(descriptor);
+        const tx = await this.contract(signer).register(kind, target, id, p.descriptorHash, p.descriptorURI, p.urn);
+        const receipt = await tx.wait();
+        return { recordId: eventArgs(this.contract().interface, receipt, "Registered", this.address).recordId, receipt };
+    }
+    recordIdFromReceipt(receipt) {
+        return eventArgs(this.contract().interface, receipt, "Registered", this.address).recordId;
+    }
+    recordIdOf(target, id) {
+        return recordIdOf(this.world.chainId, target, id);
+    }
+    async recordOf(recordId) {
+        const r = await this.contract().recordOf(recordId);
+        return { kind: r.kind, target: r.target, id: BigInt(r.id), descriptorHash: r.descriptorHash, descriptorURI: r.descriptorURI, urn: r.urn, status: Number(r.status), attestor: r.attestor, updatedAt: BigInt(r.updatedAt) };
+    }
+    async controllerOf(recordId) {
+        return this.contract().controllerOf(recordId);
+    }
+    async backed(recordId) {
+        return this.contract().backed(recordId);
+    }
+    async isAdopted(recordId) {
+        const [rec, controller] = await Promise.all([this.recordOf(recordId), this.controllerOf(recordId)]);
+        return controller !== "0x0000000000000000000000000000000000000000" && rec.attestor.toLowerCase() === controller.toLowerCase();
+    }
+}