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

package/dist/core/asf.js

@@ -0,0 +1,157 @@
+import { keccak256 } from "ethers";
+import { abi, accountRef, dataUriJcs, jcs, keccakUtf8 } from "./canonical.js";
+import { eventArgs } from "./world.js";
+/** ERC-8468 Agent Safety Framework: specifications a cell adopts and interventions it must honor. */
+export const Enforcement = { self: 1, account: 2, runtime: 4, custodian: 8, contract: 16, collective: 32 };
+export const Rights = { suspend: 1, resume: 2, terminate: 4 };
+export const Restriction = { noNewRisk: 1, shrink: 2, essentialOnly: 4, deriskOnly: 8, fullStop: 16 };
+export const Combinator = { All: 0, Any: 1, KOf: 2 };
+export const Verdict = { Unknown: 0, Satisfied: 1, NotSatisfied: 2 };
+export const VerdictName = ["Unknown", "Satisfied", "NotSatisfied"];
+export const ReasonName = ["None", "NoBinding", "Terminated", "Suspended", "NotYetValid", "Expired", "SpecMismatch", "VersionMismatch", "AdopterMismatch", "SubjectMismatch", "ScopeMismatch", "EnforcementMismatch", "ParentNotSatisfied", "SpecRegistryUnavailable", "IntervenerMismatch", "StoppedByIntervener"];
+export const BindingStateName = ["None", "Active", "Suspended", "Terminated"];
+const ZERO32 = "0x" + "00".repeat(32);
+export function subjectKeyOf(ref) {
+    return keccakUtf8(ref);
+}
+export function accountSubjectKey(chainId, account) {
+    return keccakUtf8(accountRef(chainId, account));
+}
+export function scopeKeyOf(scope) {
+    return keccakUtf8(jcs(scope));
+}
+export function specIdOf(chainId, registry, publisher, salt) {
+    return keccak256(abi.encode(["uint256", "address", "address", "bytes32"], [chainId, registry, publisher, salt]));
+}
+export const REQUIREMENT_TUPLE = "tuple(uint8 combinator,uint16 k,tuple(address specRegistry,bytes32 specId,uint32[] versions,address adopter,bytes32 subjectKey,bytes32 scopeKey,uint16 enforcement,tuple(address account,uint8 rights)[] interveners)[] clauses)";
+export function requirementIdOf(req) {
+    return keccak256(abi.encode([REQUIREMENT_TUPLE], [req]));
+}
+export function oneClause(p) {
+    return {
+        combinator: Combinator.All,
+        k: 0,
+        clauses: [
+            {
+                specRegistry: p.specRegistry,
+                specId: p.specId,
+                versions: p.versions ?? [1],
+                adopter: p.adopter ?? "0x0000000000000000000000000000000000000000",
+                subjectKey: p.subjectKey ?? ZERO32,
+                scopeKey: p.scopeKey ?? ZERO32,
+                enforcement: p.enforcement ?? Enforcement.account,
+                interveners: p.interveners ?? [],
+            },
+        ],
+    };
+}
+export class ASF {
+    world;
+    constructor(world) {
+        this.world = world;
+    }
+    specs(runner) {
+        return this.world.contract("8468/ASFSpecificationRegistry", runner);
+    }
+    bindings(runner) {
+        return this.world.contract("8468/ASFBindingRegistry", runner);
+    }
+    get specRegistryAddress() {
+        return this.world.address("8468/ASFSpecificationRegistry");
+    }
+    get bindingRegistryAddress() {
+        return this.world.address("8468/ASFBindingRegistry");
+    }
+    /** The commitment of a specification document: contentHash = keccak256(JCS(document)); locator = data: URI. */
+    specificationCommitment(document) {
+        return { contentHash: keccakUtf8(jcs(document)), locator: dataUriJcs(document) };
+    }
+    encodeRegisterSpecification(salt, document, requiredProfiles = []) {
+        const c = this.specificationCommitment(document);
+        return this.specs().interface.encodeFunctionData("registerSpecification", [salt, c.contentHash, c.locator, requiredProfiles]);
+    }
+    specIdFromReceipt(receipt) {
+        return eventArgs(this.specs().interface, receipt, "SpecificationRegistered", this.specRegistryAddress).specId;
+    }
+    encodeSuspend(bindingId, restrictions, responseRef, reasonRef) {
+        return this.bindings().interface.encodeFunctionData("suspend", [bindingId, restrictions, responseRef, reasonRef]);
+    }
+    encodeResume(bindingId, reasonRef) {
+        return this.bindings().interface.encodeFunctionData("resume", [bindingId, reasonRef]);
+    }
+    /** Publish a safety specification document (version 1). contentHash = keccak256(JCS(document)); the locator is a data: URI. */
+    async registerSpecification(publisher, salt, document, requiredProfiles = []) {
+        const contentHash = keccakUtf8(jcs(document));
+        const locator = dataUriJcs(document);
+        const tx = await this.specs(publisher).registerSpecification(salt, contentHash, locator, requiredProfiles);
+        const receipt = await tx.wait();
+        return { specId: eventArgs(this.specs().interface, receipt, "SpecificationRegistered").specId, contentHash, locator, receipt };
+    }
+    async versionOf(specId, version) {
+        const v = await this.specs().versionOf(specId, version);
+        return { contentHash: v.contentHash, locator: v.locator, publishedAt: BigInt(v.publishedAt), deprecated: Boolean(v.deprecated) };
+    }
+    encodeAdopt(input) {
+        return this.bindings().interface.encodeFunctionData("adopt", [input]);
+    }
+    async computeBindingId(adopter, input) {
+        return this.bindings().computeBindingId(adopter, input);
+    }
+    bindingIdFromReceipt(receipt) {
+        return eventArgs(this.bindings().interface, receipt, "BindingCreated", this.bindingRegistryAddress).bindingId;
+    }
+    async suspend(intervener, bindingId, restrictions, responseRef, reasonRef) {
+        const tx = await this.bindings(intervener).suspend(bindingId, restrictions, responseRef, reasonRef);
+        return tx.wait();
+    }
+    async resume(intervener, bindingId, reasonRef) {
+        const tx = await this.bindings(intervener).resume(bindingId, reasonRef);
+        return tx.wait();
+    }
+    async check(requirement, bindingIds) {
+        const r = await this.bindings().check(requirement, bindingIds);
+        return { verdict: Number(r[0]), reasons: Array.from(r[1], (x) => Number(x)), restrictions: Array.from(r[2], (x) => Number(x)) };
+    }
+    async bindingOf(bindingId) {
+        const b = await this.bindings().bindingOf(bindingId);
+        return { adopter: b.adopter, state: Number(b.state), restrictions: Number(b.restrictions), validUntil: BigInt(b.validUntil) };
+    }
+    /** The binding a cell adopts for the FOGA cell specification. */
+    cellBindingInput(p) {
+        return {
+            subjectKey: accountSubjectKey(p.chainId, p.cell),
+            scopeKey: scopeKeyOf({ ref: accountRef(p.chainId, p.cell) }),
+            specRegistry: this.specRegistryAddress,
+            specId: p.specId,
+            version: p.version,
+            contentHash: p.contentHash,
+            paramsHash: keccakUtf8(jcs(p.params)),
+            paramsLocator: dataUriJcs(p.params),
+            authorityRef: keccakUtf8(jcs(p.authority)),
+            enforcement: Enforcement.account | Enforcement.contract,
+            validFrom: 0,
+            validUntil: p.validUntil ?? 0,
+            parentBindingId: ZERO32,
+            salt: p.salt ?? "0x" + "00".repeat(31) + "01",
+            interveners: [{ account: p.guardian, rights: Rights.suspend | Rights.resume }],
+        };
+    }
+}
+/** The FOGA cell safety specification, version 1. */
+export function fogaCellSpecification() {
+    return {
+        asf: "1.0",
+        kind: "safety-specification",
+        name: "FOGA Cell Safety Specification",
+        version: 1,
+        summary: "The baseline every FOGA cell adopts: commitment-class actions only while the anchor is ACTIVE, interventions honored at the execution gate, de-risking always open.",
+        clauses: [
+            { id: "aid-active", text: "A cell MUST NOT make a commitment-class call (submit, join, adopt, assert) while its ERC-8434 anchor is not ACTIVE. Enforced by the cell account's AID-state gate." },
+            { id: "honor-stop", text: "A cell MUST stop commitment-class calls while its binding is suspended and MUST NOT continue under a full stop. Enforced by the cell account's execution gate against the Binding Registry." },
+            { id: "derisk-open", text: "Withdrawals of earned credit, refunds and leaving a swarm remain allowed under a derisk-only suspension and MUST be listed as de-risk actions by the owner." },
+            { id: "attribution", text: "Only calls routed through the cell account are the cell's acts; a direct call by the operator key is the operator's own." },
+        ],
+        enforcement: ["account", "contract"],
+        profiles: [],
+    };
+}

package/dist/core/canonical.js

@@ -0,0 +1,79 @@
+import { createHash } from "node:crypto";
+import { AbiCoder, getAddress, keccak256, toUtf8Bytes } from "ethers";
+/**
+ * RFC 8785 JSON Canonicalization Scheme (the subset the ten ERCs use): object keys sorted by UTF-16 code
+ * units, no whitespace, strings and finite numbers serialized as JSON.stringify does, `undefined`
+ * properties skipped. Throws on non-finite numbers, bigints and functions.
+ */
+export function jcs(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return JSON.stringify(value);
+        case "number":
+            if (!Number.isFinite(value))
+                throw new Error("JCS: non-finite number");
+            return JSON.stringify(value);
+        case "bigint":
+            throw new Error("JCS: bigint is not JSON; stringify it first");
+        case "undefined":
+            throw new Error("JCS: undefined is not JSON");
+        case "object": {
+            if (Array.isArray(value))
+                return "[" + value.map((v) => (v === undefined ? "null" : jcs(v))).join(",") + "]";
+            const obj = value;
+            const keys = Object.keys(obj)
+                .filter((k) => obj[k] !== undefined)
+                .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+            return "{" + keys.map((k) => JSON.stringify(k) + ":" + jcs(obj[k])).join(",") + "}";
+        }
+        default:
+            throw new Error(`JCS: unsupported type ${typeof value}`);
+    }
+}
+export function sha256Hex(data) {
+    const buf = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+    return "0x" + createHash("sha256").update(buf).digest("hex");
+}
+export function sha256Bytes(data) {
+    return new Uint8Array(createHash("sha256").update(Buffer.from(data)).digest());
+}
+/** keccak256 over the UTF-8 bytes of a string (identifier ids, AID / AUF / ASF content hashes). */
+export function keccakUtf8(s) {
+    return keccak256(toUtf8Bytes(s));
+}
+/** keccak256(UTF-8(JCS(doc))) — AID documents, ASF documents, AUF definitions and companions. */
+export function keccakJcs(doc) {
+    return keccakUtf8(jcs(doc));
+}
+/** SHA-256(UTF-8(JCS(doc))) — ARD descriptors (content members) and SAI pack hashes. */
+export function sha256Jcs(doc) {
+    return sha256Hex(jcs(doc));
+}
+export function dataUri(doc) {
+    return "data:application/json;base64," + Buffer.from(JSON.stringify(doc)).toString("base64");
+}
+export function dataUriJcs(doc) {
+    return "data:application/json;base64," + Buffer.from(jcs(doc)).toString("base64");
+}
+export function parseDataUri(uri) {
+    const m = /^data:application\/json(;base64)?,(.*)$/s.exec(uri);
+    if (!m)
+        throw new Error("not a JSON data: URI");
+    const body = m[1] ? Buffer.from(m[2], "base64").toString("utf8") : decodeURIComponent(m[2]);
+    return JSON.parse(body);
+}
+/** "eip155:<chainId>:<0x + lowercase hex>" — CAIP-10 account reference used by AID, ASF and AUF. */
+export function accountRef(chainId, address) {
+    return `eip155:${chainId}:${getAddress(address).toLowerCase()}`;
+}
+/** "eip155:<chainId>/erc721:<0x lowercase>/<id>" — CAIP-19 token reference used by ARD and AUF. */
+export function erc721Ref(chainId, collection, id) {
+    return `eip155:${chainId}/erc721:${getAddress(collection).toLowerCase()}/${id}`;
+}
+export const abi = AbiCoder.defaultAbiCoder();
+export function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}

package/dist/core/erc8004.js

@@ -0,0 +1,52 @@
+import { Contract } from "ethers";
+import { eventArgs } from "./world.js";
+/**
+ * ERC-8004 Identity Registry surface: the official registry on public chains, the local stub on Anvil.
+ * Both expose register(string) / ownerOf / getAgentWallet / setMetadata / transferFrom.
+ */
+export const ERC8004_ABI = [
+    "function register() returns (uint256)",
+    "function register(string agentURI) returns (uint256)",
+    "function ownerOf(uint256 agentId) view returns (address)",
+    "function getAgentWallet(uint256 agentId) view returns (address)",
+    "function setAgentURI(uint256 agentId, string newURI)",
+    "function tokenURI(uint256 agentId) view returns (string)",
+    "function getMetadata(uint256 agentId, string metadataKey) view returns (bytes)",
+    "function setMetadata(uint256 agentId, string metadataKey, bytes metadataValue)",
+    "function transferFrom(address from, address to, uint256 agentId)",
+    "function safeTransferFrom(address from, address to, uint256 agentId)",
+    "function balanceOf(address owner) view returns (uint256)",
+    "function supportsInterface(bytes4) view returns (bool)",
+    "event Registered(uint256 indexed agentId, string agentURI, address indexed owner)",
+    "event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)",
+    "event MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue)",
+];
+export class Identity8004 {
+    world;
+    address;
+    constructor(world) {
+        this.world = world;
+        this.address = world.address("identity8004");
+    }
+    contract(runner) {
+        return new Contract(this.address, ERC8004_ABI, runner ?? this.world.provider);
+    }
+    /** Calldata for register(agentURI) — used when a contract account registers through `execute`. */
+    encodeRegister(agentURI) {
+        return this.contract().interface.encodeFunctionData("register(string)", [agentURI]);
+    }
+    encodeTransfer(from, to, agentId) {
+        return this.contract().interface.encodeFunctionData("transferFrom", [from, to, agentId]);
+    }
+    /** The agent id minted by a register() call, from the Transfer(0, owner, id) event in the receipt. */
+    agentIdFromReceipt(receipt) {
+        const args = eventArgs(this.contract().interface, receipt, "Transfer", this.address);
+        return BigInt(args.tokenId);
+    }
+    async ownerOf(agentId) {
+        return this.contract().ownerOf(agentId);
+    }
+    async agentWallet(agentId) {
+        return this.contract().getAgentWallet(agentId);
+    }
+}

package/dist/core/kya.js

@@ -0,0 +1,225 @@
+import { keccak256, toUtf8Bytes } from "ethers";
+import { abi, dataUri } from "./canonical.js";
+import { eventArgs } from "./world.js";
+/** ERC-8419 Know-Your-Agent: schemes, attested assertions, checks. */
+export const SubjectType = {
+    erc8004: keccak256(toUtf8Bytes("erc8004")),
+    account: keccak256(toUtf8Bytes("account")),
+    erc721: keccak256(toUtf8Bytes("erc721")),
+    did: keccak256(toUtf8Bytes("did")),
+};
+export const SchemeMode = { ATTESTED: 0, PROVED: 1 };
+export const BindingKind = { IDENTITY: 0, CONTROLLER: 1, INSTANCE: 2 };
+export const ResultKind = { ORDERED_LEVEL: 0, CATEGORICAL: 1, OPAQUE: 2 };
+/** An `account` subject: abi.encode(uint256 chainId, address account). Schemes for it must use IDENTITY binding. */
+export function accountSubject(chainId, account) {
+    return { subjectType: SubjectType.account, subjectData: abi.encode(["uint256", "address"], [chainId, account]) };
+}
+export function erc8004Subject(chainId, identityRegistry, agentId) {
+    return { subjectType: SubjectType.erc8004, subjectData: abi.encode(["uint256", "address", "uint256"], [chainId, identityRegistry, agentId]) };
+}
+export function subjectKey(s) {
+    return keccak256(abi.encode(["bytes32", "bytes"], [s.subjectType, s.subjectData]));
+}
+/** levelMask: bit n set <=> level n is a declared result. */
+export function levelMaskOf(levels) {
+    return levels.reduce((m, l) => m | (1n << BigInt(l)), 0n);
+}
+export class KYA {
+    world;
+    constructor(world) {
+        this.world = world;
+    }
+    schemes(runner) {
+        return this.world.contract("8419/KYASchemeRegistry", runner);
+    }
+    registry(runner) {
+        return this.world.contract("8419/KYARegistry", runner);
+    }
+    get registryAddress() {
+        return this.world.address("8419/KYARegistry");
+    }
+    /** SchemeInput for an ATTESTED, ORDERED_LEVEL scheme (IDENTITY binding: the only kind a plain address satisfies). */
+    attestedSchemeInput(descriptor) {
+        const bytes = Buffer.from(JSON.stringify(descriptor));
+        return {
+            schemeURI: dataUri(descriptor),
+            schemeHash: keccak256(bytes),
+            mode: SchemeMode.ATTESTED,
+            binding: BindingKind.IDENTITY,
+            resultKind: ResultKind.ORDERED_LEVEL,
+            levelMask: levelMaskOf(Object.keys(descriptor.levels).map(Number)),
+            verifier: "0x0000000000000000000000000000000000000000",
+            predecessor: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        };
+    }
+    /** SchemeInput for a PROVED scheme admitted by an IKYAVerifier. */
+    provedSchemeInput(descriptor, verifier) {
+        return { ...this.attestedSchemeInput(descriptor), mode: SchemeMode.PROVED, verifier };
+    }
+    encodeRegisterScheme(input) {
+        return this.schemes().interface.encodeFunctionData("registerScheme", [input]);
+    }
+    encodeAttest(p) {
+        return this.registry().interface.encodeFunctionData("attest", [p.subject, p.schemeId, p.level, p.claimDigest, p.expiresAt, p.evidenceURI ?? "", p.evidenceHash ?? "0x" + "00".repeat(32)]);
+    }
+    /** attestWithProof(subject, schemeId, publicInputs, proof, evidenceURI): the proved path; the verifier adapter becomes the issuer. */
+    encodeAttestWithProof(subject, schemeId, publicInputs, proof, evidenceURI = "") {
+        return this.registry().interface.encodeFunctionData("attestWithProof", [subject, schemeId, publicInputs, proof, evidenceURI]);
+    }
+    async isNullifierUsed(schemeId, nullifier) {
+        return this.registry().isNullifierUsed(schemeId, nullifier);
+    }
+    encodeRevoke(assertionId, reasonCode) {
+        return this.registry().interface.encodeFunctionData("revoke", [assertionId, reasonCode]);
+    }
+    schemeIdFromReceipt(receipt) {
+        return eventArgs(this.schemes().interface, receipt, "SchemeRegistered", this.world.address("8419/KYASchemeRegistry")).schemeId;
+    }
+    assertionIdFromReceipt(receipt) {
+        return eventArgs(this.registry().interface, receipt, "Asserted", this.registryAddress).assertionId;
+    }
+    get schemeRegistryAddress() {
+        return this.world.address("8419/KYASchemeRegistry");
+    }
+    /**
+     * Register an ATTESTED, ORDERED_LEVEL scheme for `account` subjects (IDENTITY binding, the only binding
+     * kind a plain address can satisfy). The descriptor is published as a data: URI and committed by keccak.
+     */
+    async registerAttestedScheme(controller, descriptor) {
+        const bytes = Buffer.from(JSON.stringify(descriptor));
+        const schemeHash = keccak256(bytes);
+        const levels = Object.keys(descriptor.levels).map(Number);
+        const input = {
+            schemeURI: dataUri(descriptor),
+            schemeHash,
+            mode: SchemeMode.ATTESTED,
+            binding: BindingKind.IDENTITY,
+            resultKind: ResultKind.ORDERED_LEVEL,
+            levelMask: levelMaskOf(levels),
+            verifier: "0x0000000000000000000000000000000000000000",
+            predecessor: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        };
+        const tx = await this.schemes(controller).registerScheme(input);
+        const receipt = await tx.wait();
+        const schemeId = eventArgs(this.schemes().interface, receipt, "SchemeRegistered").schemeId;
+        return { schemeId, receipt, schemeHash };
+    }
+    /** Register a PROVED scheme whose assertions are admitted by an IKYAVerifier (e.g. the Groth16 adapter). */
+    async registerProvedScheme(controller, descriptor, verifier) {
+        const bytes = Buffer.from(JSON.stringify(descriptor));
+        const schemeHash = keccak256(bytes);
+        const levels = Object.keys(descriptor.levels).map(Number);
+        const input = {
+            schemeURI: dataUri(descriptor),
+            schemeHash,
+            mode: SchemeMode.PROVED,
+            binding: BindingKind.IDENTITY,
+            resultKind: ResultKind.ORDERED_LEVEL,
+            levelMask: levelMaskOf(levels),
+            verifier,
+            predecessor: "0x0000000000000000000000000000000000000000000000000000000000000000",
+        };
+        const tx = await this.schemes(controller).registerScheme(input);
+        const receipt = await tx.wait();
+        return { schemeId: eventArgs(this.schemes().interface, receipt, "SchemeRegistered").schemeId, receipt, schemeHash };
+    }
+    /** The issuer records an assertion about a subject (ATTESTED mode). */
+    async attest(issuer, p) {
+        const tx = await this.registry(issuer).attest(p.subject, p.schemeId, p.level, p.claimDigest, p.expiresAt, p.evidenceURI ?? "", p.evidenceHash ?? "0x" + "00".repeat(32));
+        const receipt = await tx.wait();
+        return { assertionId: eventArgs(this.registry().interface, receipt, "Asserted").assertionId, receipt };
+    }
+    async revoke(issuer, assertionId, reasonCode) {
+        const tx = await this.registry(issuer).revoke(assertionId, reasonCode);
+        return tx.wait();
+    }
+    async check(subject, schemeId, minLevel, issuers) {
+        return this.registry().check(subject, schemeId, minLevel, issuers);
+    }
+    async resolve(subject, schemeId, issuers) {
+        const r = await this.registry().resolve(subject, schemeId, issuers);
+        return { level: Number(r.level), expiresAt: BigInt(r.expiresAt), assertionId: r.assertionId };
+    }
+    async admissionDomain() {
+        return this.registry().admissionDomain();
+    }
+    async getAssertion(assertionId) {
+        const a = await this.registry().getAssertion(assertionId);
+        return { subjectKey: a.subjectKey, schemeId: a.schemeId, issuer: a.issuer, level: Number(a.level), claimDigest: a.claimDigest, issuedAt: Number(a.issuedAt), expiresAt: Number(a.expiresAt), anchor: a.anchor, status: Number(a.status) };
+    }
+}
+/** The descriptor FOGA registers for its attested scheme: a plain ordered ladder of operational levels. */
+export function fogaAttestedSchemeDescriptor() {
+    return {
+        type: "https://eips.ethereum.org/EIPS/eip-8419#kya-scheme-v1",
+        name: "FOGA cell standing (attested) v1",
+        description: "An issuer's ordered judgment of a cell's operational standing: 1 = known, 2 = operating under a safety binding, 3 = audited.",
+        mode: "attested",
+        binding: "identity",
+        result: { kind: "ordered-level" },
+        dimensions: ["cell-standing"],
+        levels: {
+            "0": { label: "none", meaning: "no standing asserted" },
+            "1": { label: "known", meaning: "the issuer has identified the cell" },
+            "2": { label: "bound", meaning: "the cell operates under an adopted safety specification" },
+            "3": { label: "audited", meaning: "the issuer reviewed the cell's conduct" },
+        },
+        evidenceKinds: ["foga:cell-document", "erc8468:binding"],
+        issuerPolicy: { kind: "open" },
+    };
+}
+/** The descriptor for the credential-pattern proved scheme admitted by the Groth16 adapter (levels 0..4 as the reference circuit). */
+export function fogaProvedSchemeDescriptor() {
+    return {
+        type: "https://eips.ethereum.org/EIPS/eip-8419#kya-scheme-v1",
+        name: "FOGA cell standing (proved, credential pattern) v1",
+        description: "A hidden issuer from the admitted issuer set signed a standing level; the cell proves it in zero knowledge (kya-public-v1 layout).",
+        mode: "proved",
+        binding: "identity",
+        result: { kind: "ordered-level" },
+        dimensions: ["cell-standing"],
+        levels: {
+            "0": { label: "none", meaning: "no standing" },
+            "1": { label: "known", meaning: "identified" },
+            "2": { label: "bound", meaning: "safety-bound" },
+            "3": { label: "audited", meaning: "conduct reviewed" },
+            "4": { label: "verified", meaning: "credential verified by an admitted issuer" },
+        },
+        evidenceKinds: ["zk:groth16:kya-public-v1"],
+        issuerPolicy: { kind: "issuer-set" },
+    };
+}
+/**
+ * The descriptor for the predicate-pattern proved scheme (ERC-8419 section 5) admitted by FOGA's own adapter:
+ * the scheme is the rule "at least K task completions about the subject, signed by a source of the committed
+ * source set, are Accepted inside [t0, t1]"; the proof reveals the subject, the rule's parameters and the result
+ * bit. Level 1 = the rule holds for the disclosed parameters (committed in claimDigest); level 0 is declared and
+ * never issued (a false predicate is rejected, not recorded).
+ */
+export function fogaPredicateSchemeDescriptor() {
+    return {
+        type: "https://eips.ethereum.org/EIPS/eip-8419#kya-scheme-v1",
+        name: "FOGA accepted completions (proved, predicate pattern) v1",
+        description: "At least K task-completion records about the cell, signed by a source of the committed source set, carry status Accepted inside the window [t0, t1]; proved in zero knowledge over the records (kya-predicate-count-v1 layout). A fact about a range of records, not a judgment of trustworthiness.",
+        mode: "proved",
+        binding: "identity",
+        result: { kind: "ordered-level" },
+        dimensions: ["accepted-completions"],
+        levels: {
+            "0": { label: "not shown", meaning: "no proof recorded" },
+            "1": { label: "shown", meaning: "the rule holds for the parameters committed in claimDigest (challenge, t0, t1, K, source set root)" },
+        },
+        circuit: {
+            name: "kya_predicate_count_v1",
+            slots: 8,
+            sourceSetDepth: 16,
+            publicInputLayout: "abi.encode(bytes32 subjectKey, bytes32 nullifier, bytes32 challenge, uint64 t0, uint64 t1, uint16 k, bytes32 sourceSetRoot, uint64 epoch, uint8 result)",
+            record: "Poseidon(subjectKeyHi, subjectKeyLo, taskRef128, status, timestamp) signed EdDSA-Poseidon (Baby Jubjub) by the source",
+            nullifier: "Poseidon(secret, schemeIdHi, schemeIdLo, admissionDomainHi, admissionDomainLo, epoch, challengeHi, challengeLo)",
+            setup: "development ceremony with a public beacon (prover/build-predicate.mjs); not for production use",
+        },
+        evidenceKinds: ["zk:groth16:kya-predicate-count-v1"],
+        issuerPolicy: { kind: "source-set" },
+    };
+}

package/dist/core/measure.js

@@ -0,0 +1,96 @@
+import { getAddress, keccak256, toUtf8Bytes } from "ethers";
+import { abi, dataUriJcs, keccakJcs, parseDataUri } from "./canonical.js";
+/**
+ * Realized net cash flow, measured (ERC-8454 observation profile). A receipt states what was observed inside an
+ * economic boundary over a window — inflows with their on-chain references, costs, the items that could not be
+ * observed — and never a value. The resolver recomputes the receipt from the chain and checks the boundary, the
+ * method registration and double counting across receipts.
+ */
+export const METHOD_KIND = keccak256(toUtf8Bytes("auf:method-descriptor"));
+export const RECEIPT_SCHEMA = "foga.measurement-receipt/1";
+export const CHECK_SCHEMA = "foga.measurement-check/1";
+export const AssertionKind = { None: 0, Characterization: 1, Observation: 2, Valuation: 3, Extension: 4 };
+/** The method FOGA registers once and every receipt cites by its descriptor hash. */
+export function realizedNetCashFlowMethod() {
+    return {
+        auf: "1.0",
+        kind: "method-descriptor",
+        name: "foga.realized-net-cash-flow/1",
+        profile: "observation",
+        summary: "Realized net cash flow of a unit over a window: inflows that settled on chain to accounts inside the unit's economic boundary, minus the gas the unit's own operations paid, in the asset's smallest denomination. Items that cannot be observed on chain are listed as missing, never written as zero. The result is a measurement, not a valuation: no field of a receipt states a value.",
+        rules: [
+            { id: "boundary", text: "An inflow counts only when its on-chain recipient is an account of the unit's economic boundary." },
+            { id: "settled", text: "An inflow counts only once it settled on chain (a tender settlement, a released escrow settlement); pending, held and refunded amounts are shown and not counted." },
+            { id: "attribution", text: "A payment to a key of the unit's operator that did not pass through the unit's account is not the unit's inflow." },
+            { id: "once", text: "An inflow reference appears in at most one receipt of a set; a settlement counted for two units is a double count." },
+            { id: "costs", text: "Costs are the gas of the unit's own operations in the window, as paid; other costs are listed as missing when not observable." },
+            { id: "no-value", text: "A receipt carries no value, price, worth or score." },
+        ],
+        receiptSchema: RECEIPT_SCHEMA,
+    };
+}
+export function receiptHash(receipt) {
+    return keccakJcs(receipt);
+}
+export function receiptUri(receipt) {
+    return dataUriJcs(receipt);
+}
+export function totals(inflows, gasWei) {
+    const inflowsWei = inflows.filter((i) => i.status === "counted").reduce((s, i) => s + BigInt(i.amount), 0n);
+    return { inflowsWei: inflowsWei.toString(), costsWei: gasWei.toString(), netWei: (inflowsWei - gasWei).toString() };
+}
+/** ObservationCore payload: (snapshotHash, windowStart, windowEnd). */
+export function observationPayload(snapshotHash, windowStart, windowEnd) {
+    return abi.encode(["bytes32", "uint64", "uint64"], [snapshotHash, windowStart, windowEnd]);
+}
+const FORBIDDEN = /"(value|price|worth|valuation|score)"\s*:/i;
+/**
+ * Checks one receipt against the chain and against the other receipts of the set. Deterministic: the same
+ * receipts and the same chain state give the same report.
+ */
+export async function checkReceipt(receipt, others, chain, assertionId) {
+    const lines = [];
+    const hash = receiptHash(receipt);
+    const d = await chain.descriptor(receipt.methodHash);
+    lines.push({ rule: "method.registered", pass: d !== null && d.kind === METHOD_KIND, detail: d ? `descriptor ${receipt.methodHash.slice(0, 10)}… registered by ${d.publisher}` : `descriptor ${receipt.methodHash.slice(0, 10)}… is not registered: the receipt is not resolvable` });
+    lines.push({ rule: "method.named", pass: receipt.method === "foga.realized-net-cash-flow/1" && receipt.methodHash === keccakJcs(realizedNetCashFlowMethod()), detail: `method ${receipt.method}, hash ${receipt.methodHash === keccakJcs(realizedNetCashFlowMethod()) ? "matches" : "does not match"} the committed descriptor` });
+    const latest = await chain.latestVersion(BigInt(receipt.unit.unitId));
+    lines.push({ rule: "unit.version", pass: receipt.unit.version >= 1 && receipt.unit.version <= latest, detail: `unit ${receipt.unit.unitId} version ${receipt.unit.version} (latest ${latest})` });
+    lines.push({ rule: "window", pass: receipt.window.end >= receipt.window.start, detail: `window [${receipt.window.start}, ${receipt.window.end}]` });
+    lines.push({ rule: "no-value", pass: !FORBIDDEN.test(JSON.stringify(receipt)), detail: "no value, price, worth, valuation or score field" });
+    const boundary = new Set(receipt.boundary.accounts.map((a) => getAddress(a)));
+    let counted = 0n;
+    for (const inflow of receipt.inflows) {
+        const s = await chain.settled(inflow);
+        if (inflow.status === "counted") {
+            const ok = s !== null && s.settled && boundary.has(getAddress(s.recipient)) && s.amount === BigInt(inflow.amount);
+            if (ok)
+                counted += s.amount;
+            lines.push({ rule: `inflow.${inflow.ref}`, pass: ok, detail: s ? `${inflow.amount} wei to ${s.recipient}${boundary.has(getAddress(s.recipient)) ? " (inside the boundary)" : " (OUTSIDE the boundary)"}, settled ${s.settled}, chain amount ${s.amount}` : `could not be re-derived from the chain` });
+        }
+        else {
+            const outside = s === null || !boundary.has(getAddress(s.recipient)) || !s.settled;
+            lines.push({ rule: `excluded.${inflow.ref}`, pass: outside || Boolean(inflow.reason), detail: `${inflow.amount} wei excluded: ${inflow.reason ?? "no reason given"}` });
+        }
+    }
+    lines.push({ rule: "totals.inflows", pass: counted.toString() === receipt.totals.inflowsWei, detail: `counted ${counted} wei; receipt says ${receipt.totals.inflowsWei}` });
+    const net = BigInt(receipt.totals.inflowsWei) - BigInt(receipt.totals.costsWei);
+    lines.push({ rule: "totals.net", pass: net.toString() === receipt.totals.netWei && receipt.totals.costsWei === receipt.costs.gasWei, detail: `net ${net} wei = inflows - gas ${receipt.costs.gasWei}` });
+    // double counting across the set: the same settlement reference counted in two receipts
+    const mine = new Set(receipt.inflows.filter((i) => i.status === "counted").map((i) => i.ref));
+    const dup = [];
+    for (const o of others)
+        for (const i of o.inflows)
+            if (i.status === "counted" && mine.has(i.ref))
+                dup.push(`${i.ref} (also counted for unit ${o.unit.unitId})`);
+    lines.push({ rule: "once", pass: dup.length === 0, detail: dup.length ? `double count: ${dup.join("; ")}` : `no inflow of this receipt is counted by another receipt of the set (${others.length} other${others.length === 1 ? "" : "s"})` });
+    if (assertionId && chain.assertion) {
+        const a = await chain.assertion(assertionId);
+        const ok = a !== null && a.kind === AssertionKind.Observation && a.profileId === receipt.methodHash && a.contentHash === hash && a.unitId === BigInt(receipt.unit.unitId) && a.version === receipt.unit.version && a.windowStart === receipt.window.start && a.windowEnd === receipt.window.end;
+        lines.push({ rule: "assertion", pass: ok, detail: a ? `assertion ${assertionId.slice(0, 10)}…: kind ${a.kind}, profile ${a.profileId === receipt.methodHash ? "= method" : "differs"}, contentHash ${a.contentHash === hash ? "= receipt" : "differs"}, window ${a.windowStart}-${a.windowEnd}` : `assertion ${assertionId.slice(0, 10)}… not found` });
+    }
+    return { schema: CHECK_SCHEMA, receiptHash: hash, unit: receipt.unit, lines, pass: lines.every((l) => l.pass) };
+}
+export function receiptFromUri(uri) {
+    return parseDataUri(uri);
+}