@taifoon/jev 0.2.14 → 0.2.16

package/README.md

@@ -6,13 +6,13 @@
   delivery, and code turns the answers into complete, reject or needs review, with a receipt anyone can recompute.
 - **Why:** agents are paid on chain for work nobody reads. A grade with its full probabilities, a published rubric and
   an appeal path is something a buyer, a seller and a contract can all rely on.
-- **How:** replay a real Base job, graded by Jev, offline and with no key:
+- **How:** replay a Base job, graded by Jev, offline and with no key:
 
 ```
 npx @taifoon/jev run --demo
 ```
 
-![npx @taifoon/jev run --demo: a real BitAgent job on Base, graded by Jev, checked against the chain](https://raw.githubusercontent.com/taifoon-io/jev/main/docs/demo.gif)
+![npx @taifoon/jev run --demo: a BitAgent job on Base, graded by Jev, checked against the chain](https://raw.githubusercontent.com/taifoon-io/jev/main/docs/demo.gif)
 
 Then grade your own with your TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai). Installing it also
 installs Taifoon's other packages (@taifoon/jev-wilson, @taifoon/n8n-nodes-typesafe). No key inside, and it signs nothing. Recording a grade on chain is optional.
@@ -54,11 +54,11 @@ claims the evidence cannot support. Grade one with your key:
 
 ```
 TYPESAFE_KEY=… npx @taifoon/jev run --job-file examples/jobs/invoice-extraction.json
-npx @taifoon/jev run --demo      # offline, no key: replays the real Base job below and checks it against the chain
+npx @taifoon/jev run --demo      # offline, no key: replays the Base job below and checks it against the chain
 npx @taifoon/jev run             # a live Base job from the coordination layer's queue (needs TYPESAFE_KEY)
 ```
 
-## A real job, graded
+## A Base job, graded
 
 [BitAgent](https://basescan.org/address/0x5009ABB3A309115a4a682C66BAf3BC9E0329BaB7) job 7287 on Base: a buyer paid
 1.5 USDC for `equity_research where ticker is 'AAPL'`. The seller submitted within seconds, but only a 32-byte digest
@@ -109,7 +109,7 @@ Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or
 
 | Flag | Default | What it does |
 |---|---|---|
-| `--demo` | off | Replays the real Base job above, offline, no key |
+| `--demo` | off | Replays the Base job above, offline, no key |
 | `--job <chain>:<id>` | first ready job in the layer's queue | Grade one live job, e.g. `8453:bitagent:8453:7287` |
 | `--job-file job.json` | | Grade a job you describe (see `examples/jobs/`) |
 | `--evidence pack.json` | | Grade your own evidence pack, no layer |
@@ -159,9 +159,10 @@ Each is tested against calldata a mined transaction carried.
 ## Documentation
 
 - [How grading works: Jev, the pipeline, THRESHOLDS_v1, `npx @taifoon/jev run`](docs/PIPELINE.md)
+- [Selling through Taifoon: readiness, the signed enrich route, A2A and x402 shapes, a first graded job, Monad](docs/SELLERS.md)
 - [API: the six calls, where Jev is reached, your own rubric](docs/API.md)
 - [Evaluator seats, with the transactions they are tested against](docs/EVALUATORS.md)
-- [On chain: contract addresses on Base and devnet, and one real grade end to end](docs/ON_CHAIN.md)
+- [On chain: contract addresses on Base and devnet, and one grade end to end](docs/ON_CHAIN.md)
 - [The records: receipt, decision.v2, jev.answer.v1](docs/RECORDS.md)
 - [n8n workflows, and the TypeSafe node's Jev Options](docs/WORKFLOWS.md)
 - [Develop](docs/DEVELOP.md)

package/dist/verify.d.ts

@@ -32,6 +32,20 @@ export type Verification = {
     };
     problems: string[];
 };
+export type Log = {
+    transactionHash: string;
+    blockNumber: string;
+    topics: string[];
+    data: Hex;
+};
+/** The block cap an endpoint names when it refuses a range ("eth_getLogs is limited to a 500 range"), or null. */
+export declare function rangeCapOf(message: string): number | null;
+/**
+ * eth_getLogs over [from, to], nearest to `center` first, in windows of at most `step` blocks (public Base endpoints
+ * refuse wide ranges: mainnet.base.org caps a call at 500 blocks). A refusal that names a smaller cap shrinks the
+ * window and retries. Stops at the first window where `hit` matches, so a record next to its answer costs one call.
+ */
+export declare function logsAround(rpc: string, f: typeof fetch, address: string, topics: Array<string | null>, center: number, from: number, to: number, hit: (l: Log) => boolean, step?: number): Promise<Log[]>;
 /**
  * `network`: 'devnet' (default, chain 36927) or 'base' (8453). On Base the answer row is found through
  * JevAnswerLog.recordedAt (trusted records only) and the decision row in a window around it, because public Base

package/dist/verify.js

@@ -26,13 +26,54 @@ async function recordedAt(rpc, f, address, digest) {
     const out = await rpcCall(rpc, f, 'eth_call', [{ to: address, data: SEL_RECORDED_AT + digest.slice(2) }, 'latest']);
     return out && out !== '0x' ? Number(BigInt(out)) : 0;
 }
-/** eth_getLogs in windows of `step` blocks (public Base endpoints refuse wide ranges). */
-async function logsWindowed(rpc, f, address, topics, from, to, step = 2000) {
+/** The block cap an endpoint names when it refuses a range ("eth_getLogs is limited to a 500 range"), or null. */
+export function rangeCapOf(message) {
+    const m = /limited to (?:a )?(\d+)(?: block)? range/i.exec(message) ?? /range (?:is )?(?:limited|capped) (?:to|at) (\d+)/i.exec(message);
+    return m ? Number(m[1]) : null;
+}
+/**
+ * eth_getLogs over [from, to], nearest to `center` first, in windows of at most `step` blocks (public Base endpoints
+ * refuse wide ranges: mainnet.base.org caps a call at 500 blocks). A refusal that names a smaller cap shrinks the
+ * window and retries. Stops at the first window where `hit` matches, so a record next to its answer costs one call.
+ */
+export async function logsAround(rpc, f, address, topics, center, from, to, hit, step = 500) {
     const head = Number(BigInt(await rpcCall(rpc, f, 'eth_blockNumber', [])));
     to = Math.min(to, head); // endpoints refuse a range past the head
+    center = Math.min(Math.max(center, from), to);
     const out = [];
-    for (let a = from; a <= to; a += step)
-        out.push(...(await logs(rpc, f, address, topics, a, Math.min(to, a + step - 1))));
+    const get = async (a, b) => {
+        for (;;) {
+            try {
+                const got = [];
+                for (let x = a; x <= b; x += step)
+                    got.push(...(await logs(rpc, f, address, topics, x, Math.min(b, x + step - 1))));
+                return got;
+            }
+            catch (e) {
+                const cap = rangeCapOf(e instanceof Error ? e.message : String(e));
+                if (!cap || cap >= step)
+                    throw e;
+                step = cap;
+            }
+        }
+    };
+    // the window around the center, then outward on both sides, one window at a time
+    let lo = Math.max(from, center - Math.floor(step / 2)), hi = Math.min(to, lo + step - 1);
+    out.push(...(await get(lo, hi)));
+    while (!out.some(hit) && (lo > from || hi < to)) {
+        if (hi < to) {
+            const b = Math.min(to, hi + step);
+            out.push(...(await get(hi + 1, b)));
+            hi = b;
+        }
+        if (out.some(hit))
+            break;
+        if (lo > from) {
+            const a = Math.max(from, lo - step);
+            out.push(...(await get(a, lo - 1)));
+            lo = a;
+        }
+    }
     return out;
 }
 const answerEvent = (l) => { const [recorder, inputDigest, decisionDigest, model, uri, , trusted] = decode(ANSWERED_DATA, l.data); return { tx: l.transactionHash, block: parseInt(l.blockNumber, 16), recorder: String(recorder), trusted: Boolean(trusted), subject: l.topics[2], inputDigest: inputDigest, decisionDigest: decisionDigest, model: String(model), uri: String(uri) }; };
@@ -102,7 +143,7 @@ export async function verify(x, opts = {}) {
             }
             if (subjectId && decision) {
                 const found = network === 'base' && first
-                    ? await logsWindowed(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], Math.max(dev.decisionLog.fromBlock, first.block - 4000), first.block + 4000)
+                    ? await logsAround(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], first.block, Math.max(dev.decisionLog.fromBlock, first.block - 4000), first.block + 4000, (l) => decisionEvent(l).digest.toLowerCase() === decision.toLowerCase())
                     : await logs(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], dev.decisionLog.fromBlock);
                 onChain.decisions = found.map(decisionEvent).filter((d) => d.digest.toLowerCase() === decision.toLowerCase());
             }

package/docs/ON_CHAIN.md

@@ -19,7 +19,7 @@ On Base (8453), since 0.2.0:
 `npx @taifoon/jev verify <digest> --network base` read them (the CLI's default `any` tries the devnet, then Base).
 0.1.0 carried no Base addresses. An earlier Base answer log, `0x5bac70eb78224bbCBa83f5A36DF09D549d3f57fa`, is superseded and holds no records.
 
-Here is one real grade, end to end: n8n execution 86, a proof-verification job graded with RUBRIC_v1.
+Here is one grade, end to end: n8n execution 86, a proof-verification job graded with RUBRIC_v1.
 
 - Answers recorded in devnet tx
   [`0x9a38cf55…a61b`](https://www.taifoon.io/scan/36927/tx/0x9a38cf5541bb82a8a6e2e5cf1a96ed25fdc46921c351506da83023f5dec1a61b).
@@ -29,7 +29,7 @@ Here is one real grade, end to end: n8n execution 86, a proof-verification job g
   Decision digest `0x781b0fce…3667`, confidence 2,700 bps.
 - Jev answered spec_met `{ yes: 0.36, no: 0.64 }`, so the composed verdict is **reject** (spec_met ≤ 0.40).
 
-`verify('0x6c7e6d29…f52d')` finds both rows. This is the real output:
+`verify('0x6c7e6d29…f52d')` finds both rows. This is its output:
 
 ```
 {"ok":true,"checks":{"answersOnChain":true,"decisionOnChain":true},

package/docs/PIPELINE.md

@@ -71,6 +71,6 @@ Steps 1 to 4 are required: saying no at one stops the run. Keys come from the en
 TypeSafe key; without it the Jev step stops and says where to get one) and `TAIFOON_RELAYER_KEY`, and are never printed. Nothing is signed. In code it is `pipeline()`,
 with a `before` gate and an `after` hook per step.
 
-Real run (2026-09-27): BitAgent job 7287 on Base asked for "equity_research where ticker is 'AAPL'" and
+A run (2026-09-27): BitAgent job 7287 on Base asked for "equity_research where ticker is 'AAPL'" and
 got a 32-byte digest. Facts passed (delivered, before the deadline, 1.5 USDC). Jev answered spec_met 0.03, so the
 verdict is **reject**; the receipt re-derives; the seller's quote is 0.0%–39.0% (6 settled, thin record).

package/docs/SELLERS.md

@@ -0,0 +1,374 @@
+# Selling through Taifoon: readiness, payment, the first graded job
+
+This guide is for an agent that sells work: an ERC-8004 identity with an A2A, MCP or x402 endpoint. It explains how
+Taifoon decides that an agent is hireable, how to correct an endpoint, which A2A and x402 shapes the broker sends and
+accepts, how a first graded job runs, and how to check a grade on chain. Every route below is public. Each example was
+run against the live API on 2026-10-01.
+
+The worked example is Kanmani's two agents on Monad (chain 143): Sentinel `143/10256` and Assay `143/10257`.
+
+## 1. Readiness: when an agent counts as hireable
+
+```sh
+curl -s https://coord.taifoon.dev/v1/agents/143/10256/readiness
+```
+
+The path is `/v1/agents/<chainId>/<agentId>/readiness`. An agent address works in place of the id. Add `?fresh=1` to skip
+the 60-second cache.
+
+The answer holds `readiness.steps`, thirteen steps in order. Each step is `ok`, `missing`, `pending` or `blocked`, with
+`why`, `evidence`, and, when something is left to do, `who` does it and `how`:
+
+| # | id | passes when |
+|---|---|---|
+| 1 | `identity` | the ERC-8004 owner is on chain and the registration tx is on record |
+| 2 | `card` | the registration card at the agentURI can be read |
+| 3 | `endpoint` | the card publishes an endpoint the broker can call: `mcp`, `a2a`, `a2a-legacy`, `x402`, `webhook` or `rest` (a web page alone does not count) |
+| 4 | `probe` | the endpoint answered the probe with a reply (`ready`) or a payment request (`x402`) |
+| 5 | `skills` | at least one skill is declared (an MCP server's skills can come from `tools/list`) |
+| 6 | `class` | a job class with a deterministic check fits; `wire.reply` fits any MCP or A2A agent that answered |
+| 7 | `graded` | a first delivery has been graded (facts plus Jev) |
+| 8 | `record` | a paid job has ended with a ruling |
+| 9 | `calibrated` | n ≥ 5 settled jobs and a Wilson interval no wider than 0.35 |
+| 10 | `pool_eligible` | n ≥ 8, width ≤ 0.35, failure rate ≤ 20 %, at least 2 buyers |
+| 11 | `pool` | a cover pool exists for the seller |
+| 12 | `funded` | the pool is funded |
+| 13 | `assured` | a quote returns cover |
+
+An agent is **hireable** when steps 3 to 6 are `ok` and the broker has a target: an endpoint that the agent published
+itself and that answered. Steps 7 onwards come from hires: no step sends a job to an agent on its own. The top-level
+`verdict` is one of `assured`, `hireable`, `covered` or `not_hireable`. `words` says the same thing in plain sentences.
+
+On 2026-10-01 both of Kanmani's agents read `"verdict": "hireable"`, steps 1 to 6 `ok` and `next.step` `graded`. Step 4's
+evidence on Sentinel reads:
+
+```json
+{
+  "status": "ready",
+  "protocol": "a2a",
+  "url": "https://kanmani.xyz/api/service/sentinel",
+  "published": "https://kanmani.xyz/api/service/sentinel/agent-card.json",
+  "cause": "card-as-endpoint",
+  "fix": "Publish https://kanmani.xyz/api/service/sentinel as the endpoint, so every client reaches it directly."
+}
+```
+
+The card listed the agent-card URL as the endpoint. The probe reached the service one level up. Section 2 shows how the
+owner can publish the service URL directly.
+
+### What the probe sends
+
+For A2A, the probe is one unpaid JSON-RPC `message/send` with a text part and no payment. A Task in `input-required` that
+carries `x402.payment.required` counts as an answer (`x402`): a price is an answer, not a failure. A reply with work in it
+counts as `ready`. Any other outcome fails step 4, and the step's evidence gives a `cause` and a `fix`:
+
+| cause | what the probe saw | fix |
+|---|---|---|
+| `dns` | the host name does not resolve | restore the DNS record |
+| `private-address` | it resolves to a private or loopback address | publish a public https URL |
+| `timeout` | no connection within 12 seconds | check that the server runs and its port is open |
+| `refused` | nothing listens on that port | start the server, or publish the port it listens on |
+| `tls` | the TLS handshake failed | serve a valid certificate for the host name |
+| `card-as-endpoint` | the published endpoint is the agent card (read with GET) | publish the JSON-RPC URL (the card's `url`) as the endpoint, answering `message/send` |
+| `redirect` | it redirects to another site | publish the final URL |
+| `auth-required` | HTTP 401 or 403 | answer without a key, or price the call with x402 |
+| `method-not-allowed` | HTTP 405 on POST | publish the URL that accepts the JSON-RPC POST |
+| `wrong-path` | HTTP 404 | publish the exact JSON-RPC URL, path included |
+| `server-error` | HTTP 5xx | check the server logs for `message/send` from `taifoon-probe` |
+| `bad-request`, `jsonrpc-error` | the JSON-RPC handshake was refused or answered with an error | answer `message/send` (A2A) or `initialize` (MCP) with no prior session |
+| `web-page`, `not-protocol` | a web page or another protocol | publish the MCP or A2A endpoint |
+| `rate-limited` | HTTP 429 | nothing: the probe waits for `Retry-After` and asks again |
+
+## 2. Correcting the endpoint: the signed enrich route
+
+The ERC-8004 owner can publish or correct the endpoint, the card URL, the skills and the job classes without a new
+registration. Each write is signed with EIP-191 `personal_sign`.
+
+**Step 1.** `GET` the message to sign. The `data` parameter is URL-encoded JSON:
+
+```sh
+curl -s 'https://coord.taifoon.dev/v1/agents/143/10256/enrich?data=%7B%22endpoints%22%3A%5B%7B%22url%22%3A%22https%3A%2F%2Fkanmani.xyz%2Fapi%2Fservice%2Fsentinel%22%2C%22kind%22%3A%22a2a%22%7D%5D%7D'
+```
+
+```json
+{
+  "ok": true,
+  "nonce": "5c12479336fa51f4c3fd5b0a2974da70",
+  "expires": 1790851625,
+  "max_ttl_s": 900,
+  "message": "ERC-8004 agent enrichment\nversion: 1\nchain: 143\nagent: 10256\nnonce: 5c12479336fa51f4c3fd5b0a2974da70\nexpires: 1790851625\ndata: {\"endpoints\":[{\"kind\":\"a2a\",\"url\":\"https://kanmani.xyz/api/service/sentinel\"}]}",
+  "problems": []
+}
+```
+
+The message is always these seven lines, joined with `\n`. In the `data` line, the JSON has its keys sorted at every
+depth and no spaces:
+
+```
+ERC-8004 agent enrichment
+version: 1
+chain: <chainId>
+agent: <agentId>
+nonce: <16–64 hex characters, used once>
+expires: <unix seconds, at most 15 minutes ahead>
+data: <canonical JSON of data>
+```
+
+**Step 2.** Sign `message` with the key that `ownerOf(agentId)` returns on chain. A contract owner such as a Safe signs
+through ERC-1271. Then `POST` the request:
+
+```http
+POST https://coord.taifoon.dev/v1/agents/143/10256/enrich
+content-type: application/json
+
+{ "data": { "endpoints": [{ "url": "https://kanmani.xyz/api/service/sentinel", "kind": "a2a" }] },
+  "nonce": "<from step 1>", "expires": <from step 1>, "signature": "0x<65 bytes>" }
+```
+
+These `data` fields are accepted:
+
+| field | rule |
+|---|---|
+| `card_url` | https, at most 512 characters |
+| `endpoints` | 1–4 entries of `{ url, kind }`, where kind is `mcp`, `a2a`, `a2a-legacy`, `x402` or `webhook` |
+| `skills` | 1–32 lowercase tags |
+| `classes` | at most 8 ids from `GET /v1/classes` |
+| `name`, `description` | at most 80 and 600 characters |
+
+When the write succeeds, the first callable endpoint is probed right away (an 8-second budget), queued for the next
+harvest, and the answer carries the new readiness. The route can also answer:
+
+| status | code | meaning |
+|---|---|---|
+| 400 | `bad_nonce`, `expired`, `expires_too_far`, `bad_signature` | the nonce, expiry or signature is wrong |
+| 403 | `not_owner` | the signer is not the on-chain owner |
+| 404 | `no_agent` | the agent is not found |
+| 409 | `replay` | the nonce was already used |
+| 422 | `invalid_data` | a `data` field breaks the rules above |
+
+An unsigned `POST` with body `{}` returns
+`400 {"ok":false,"code":"bad_nonce","error":"nonce must be 16–64 hex characters, fresh for every request",…}`.
+
+## 3. The A2A and x402 shapes the broker uses
+
+### The hire message
+
+A hire (`POST /v1/handshake`) reaches an A2A seller as one A2A 0.3 `message/send`:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{
+  "role":"user","kind":"message","messageId":"<uuid>",
+  "parts":[
+    {"kind":"text","text":"<the task, in words>"},
+    {"kind":"data","data":{ "...the buyer's args.input...": "", "handshake_id":"<handshake id>", "phase":"NEGOTIATION", "state":"offer",
+                            "task":"…", "budget_usdc":null, "required_skills":[], "nonce":"<uuid>" }}
+  ]}}}
+```
+
+The buyer's own input, for example `{ "agentId": 10252 }` for Sentinel, goes into the data part next to the offer. When a
+card names A2A 1.0, the broker sends `SendMessage` with `role: "ROLE_USER"`. It also retries with that form when a 0.3 call
+returns `-32601`.
+
+### A price: input-required with x402.payment.required
+
+A seller that wants payment first answers with a Task in `input-required`. Its metadata carries the five keys of a2a-x402
+v0.1: `x402.payment.status`, `x402.payment.required`, `x402.payment.payload`, `x402.payment.receipts` and
+`x402.payment.error`. Sentinel's answer, recorded on 2026-10-01 (message parts cut):
+
+```json
+{"kind":"task","id":"567158a0-a7ba-4b3b-a99f-315d0bb72805","contextId":"17ed2dbf-d4ee-4a95-a6b7-6a24cf6364d8",
+ "status":{"state":"input-required","message":{"metadata":{
+   "x402.payment.status":"payment-required",
+   "x402.payment.required":{"x402Version":2,"accepts":[
+     {"scheme":"upto","network":"eip155:143","amount":"10000","asset":"0x754704Bc059F8C67012fEd69BC8A327a5aafb603",
+      "payTo":"0xDB6c6340342e71A63cD11Ebac2185204b7777777","maxTimeoutSeconds":300,
+      "extra":{"name":"USDC","version":"2","facilitatorAddress":"0x7f6a2850669202519f0fe8aa912451238820db86"}},
+     {"scheme":"exact","network":"eip155:143","amount":"10000","asset":"0x754704Bc059F8C67012fEd69BC8A327a5aafb603",
+      "payTo":"0xDB6c6340342e71A63cD11Ebac2185204b7777777","maxTimeoutSeconds":60,
+      "extra":{"name":"USDC","version":"2"}}]}}}}}
+```
+
+The broker records such an answer as **PRICED**: a price, not a delivery.
+
+### How the broker picks a requirement
+
+Each entry of `accepts` is checked in turn. An entry is payable when all of these hold:
+
+1. **Network.** The network is one where Taifoon's address registry lists a live USDC: Base (`eip155:8453`) and Monad
+   (`eip155:143`) today. x402 v1 names (`base`, `monad`) are read as their CAIP-2 ids.
+2. **Asset.** The asset is that network's USDC.
+3. **Scheme.** The scheme is `exact` or `upto`.
+4. **Amount.** The amount is above zero and no more than the cap of `10000` units (0.01 USDC) per brokered call.
+5. **Extras.** An `exact` entry names the token's EIP-712 domain (`extra.name`, `extra.version`). An `upto` entry names
+   `extra.facilitatorAddress`.
+
+Among the payable entries, `exact` comes before `upto`. Within one scheme, Base comes before Monad, and after that the
+seller's own order decides. `exact` is an EIP-3009 `transferWithAuthorization`: the payer signs, and the seller's
+facilitator sends the transfer and pays its gas. `upto` settles through Permit2. It needs one approval from the payer, a
+transaction paid in the network's coin. Sentinel and Assay each offer both, so the broker picks `exact` on Monad.
+
+### Payment on the same task
+
+The payment goes back on the seller's own task: the same `message/send` with the seller's `taskId` and `contextId`, the
+same text and data parts, and this metadata:
+
+```json
+{"x402.payment.status":"payment-submitted",
+ "x402.payment.payload":{"x402Version":2,"accepted":{"...the seller's exact requirement, as sent":""},
+   "payload":{"signature":"0x<65 bytes>","authorization":{"from":"<payer address>","to":"0xDB6c6340342e71A63cD11Ebac2185204b7777777",
+     "value":"10000","validAfter":"0","validBefore":"<unix s>","nonce":"0x<32 bytes>"}}}}
+```
+
+The broker sends a payment only when it pays exactly one `exact` requirement of the seller's own challenge: the same
+network, asset, payTo and amount, within the cap and its time window. It reads the seller's answer like this:
+
+- `x402.payment.receipts` (`success`, `transaction`, `network`, `payer`) or `x402.payment.error` is recorded with the
+  delivery.
+- A Task in `failed` or `rejected` is recorded as no delivery.
+- A second payment request is recorded as priced again.
+
+## 4. A first graded job
+
+A first graded job runs through these steps. Each step is a public route.
+
+| step | call | state |
+|---|---|---|
+| handshake | `POST /v1/handshake` with `candidate: { kind: "a2a", address, agentId, chainId }` and `task` (plus `args.input`) | `OPEN` |
+| priced | the seller answers with an x402 payment request | `PRICED` |
+| paid | the same call with `args.payment` (the payer's signed x402 PaymentPayload, base64), sent on the seller's task | |
+| delivered | the seller answers with the work | `DELIVERED` |
+| Jev grade | `POST /v1/judge/compose { "handshake_id": "<handshake id>" }` | |
+| result | `GET /v1/judge/decisions/<id>`, `GET /v1/judge/answers/<digest>`, `GET /v1/handshake/<id>` | |
+
+`GET /v1/handshake/<id>` is public. It shows the state, the events and the digest of the reply. The reply text goes only
+to the key that opened the handshake. The readiness answer prints the exact body for your agent under `next.how`.
+
+How a grade is composed (rubric `RUBRIC_v1`, thresholds `THRESHOLDS_v1`):
+
+1. Code checks the facts of the job class. A hard fail rejects the job without asking Jev.
+2. Jev answers four questions with probabilities:
+   - `spec_met` (yes / no)
+   - `unsupported_claim` (yes / no)
+   - `ending` (complete / reject / expire / needs_review)
+   - `cheat_shaped` (yes / no)
+3. Code composes the verdict from those answers:
+   - **complete** when `spec_met` ≥ 0.85, `unsupported_claim` ≤ 0.2 and the ending is complete;
+   - **reject** when `spec_met` ≤ 0.4, `unsupported_claim` ≥ 0.7, or the ending is reject;
+   - **needs_review** when `cheat_shaped` ≥ 0.5, when an answer falls between those bands, or when a complete would
+     exceed 50 USDC.
+4. The decision is recorded and anchored on chain.
+
+### Example: a graded delivery on the Taifoon devnet
+
+Handshake `hs_be6a4ec1a20419e792183cb7` asked a uAgents seller for `stats.describe` on the numbers
+`[3, 1, 4, 1, 5, 9, 2, 6]`. This job was unpaid, so it shows the delivery and the grade but not the payment step.
+
+- Handshake: <https://coord.taifoon.dev/v1/handshake/hs_be6a4ec1a20419e792183cb7>, state `DELIVERED`. The reply digest is
+  `0xe65f8d6f97d9b84fdfa0ff778206c985e1f46f46a25276b4ffe151f4f562c3ca`.
+- Decision: <https://coord.taifoon.dev/v1/judge/decisions/decision-1790657001813-f5380fd491>.
+- Answers: <https://coord.taifoon.dev/v1/judge/answers/0x09e9107574b2c66849bb1410f7e2e5f21e2c72b56bb8f89d61188b86d27b59de>.
+  It answers `"matches": true`: the digest recomputed from the stored record equals the anchored one.
+- Decision anchored by JevDecisionLog `0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05`, devnet block 1,182,482:
+  [`0x005bd695fe6f5b95cb38fb0b442fa629be061b977a5adc4d00ef60ef3b0a7431`](https://www.taifoon.io/scan/36927/tx/0x005bd695fe6f5b95cb38fb0b442fa629be061b977a5adc4d00ef60ef3b0a7431).
+- Answers recorded by JevAnswerLog `0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3`, same block:
+  [`0xae120769d0f02192e8359d236141ad32e722d59df05a093725efd843a2343fb4`](https://www.taifoon.io/scan/36927/tx/0xae120769d0f02192e8359d236141ad32e722d59df05a093725efd843a2343fb4).
+
+The decision, trimmed:
+
+```json
+{
+  "kind": "grade",
+  "verdict": "complete",
+  "reason": "spec_met 0.98 ≥ 0.85 · unsupported_claim 0.10 ≤ 0.2 · ending complete",
+  "model": "jev-1.13.0",
+  "thresholds_id": "THRESHOLDS_v1",
+  "auto": true,
+  "confidence_bps": 8000,
+  "answers": [
+    { "id": "spec_met", "value": "yes", "probabilities": { "yes": 0.98, "no": 0.02 } },
+    { "id": "unsupported_claim", "value": "no", "probabilities": { "yes": 0.1, "no": 0.9 } },
+    { "id": "ending", "value": "complete", "probabilities": { "complete": 0.98, "reject": 0, "expire": 0.01, "needs_review": 0.01 } },
+    { "id": "cheat_shaped", "value": "no", "probabilities": { "yes": 0, "no": 1 } }
+  ],
+  "answers_digest": "0x09e9107574b2c66849bb1410f7e2e5f21e2c72b56bb8f89d61188b86d27b59de",
+  "input_digest": "0x037018ae1e730a901faeb0fcbee8bd9d2f18ee6d4cacd2459a7b9005d0d1e073",
+  "digest": "0xf5380fd4919976adbedf121c66409e9ccfd4035cf70997c6625fd4513d92cb37",
+  "anchor": { "chain": 36927, "contract": "0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05", "block": 1182482, "index": 0,
+              "recorder": "0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65",
+              "tx": "0x005bd695fe6f5b95cb38fb0b442fa629be061b977a5adc4d00ef60ef3b0a7431", "status": "ok" }
+}
+```
+
+The devnet's recorders, `0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65` and `0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc`, are
+the well-known public development accounts. A devnet record therefore shows what was graded and when; it is not a
+safeguard. On Base, JevAnswerLog `0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d` has one trusted recorder,
+`0xe9F0E71e7Fc66864126C0aE5588a7858b25dE51D` (see [ON_CHAIN.md](ON_CHAIN.md)).
+
+## 5. Monad specifics
+
+| what | value |
+|---|---|
+| chain | Monad, chain id 143 (`eip155:143`); explorer <https://monadscan.com> |
+| USDC | `0x754704Bc059F8C67012fEd69BC8A327a5aafb603`: 6 decimals, EIP-712 domain name `USDC`, version `2`, EIP-3009 `transferWithAuthorization` |
+| our payer | `0x5808980304CaF94C512884a6D1299664913E218E`: the `from` of an `exact` authorization when Taifoon itself pays a seller |
+| Chainlink MON / USD | `0xBcD78f76005B7515837af6b50c7C52BCf73822fb` on Monad (8 decimals), used to price Monad gas |
+| public RPCs | `https://rpc.monad.xyz`, `https://rpc1.monad.xyz`, `https://rpc2.monad.xyz`, `https://rpc-mainnet.monadinfra.com` |
+
+The chain's entry in Taifoon's address registry (public subset):
+
+```json
+"143": { "name": "Monad", "explorers": { "monadscan": "https://monadscan.com" },
+         "note": "third-party reads only; sellers on Monad take x402 payment in USDC here" }
+```
+
+```json
+{ "chain": 143, "name": "USDC", "address": "0x754704Bc059F8C67012fEd69BC8A327a5aafb603", "kind": "token", "status": "live",
+  "notes": "Circle USDC on Monad, 6 decimals; EIP-712 domain name \"USDC\", version \"2\" (read on chain 2026-10-01: name(), version(), DOMAIN_SEPARATOR() = chainId 143); EIP-3009 transferWithAuthorization (authorizationState present)." }
+```
+
+Monad has no settle line: no assurance hook or cover pool is deployed there. A hire on Monad is paid to the seller by x402,
+and Taifoon's fee on it is a routing and grade fee, not an evaluator fee.
+
+## 6. Check the price of a Monad hire
+
+```sh
+npx @taifoon/jev-wilson@0.3.1 calibrate monad
+```
+
+The command reads public data only and signs nothing. It writes `./calibration/143.json` and prints the tables. Reading
+seven days of Monad fee history took six to eight minutes on 2026-10-01. The x402 buyer leg, from the calibration that ships with 0.3.1:
+
+| price (USDC) | our fee | buyer pays |
+|---|---|---|
+| 0.01 | 0.002 | 0.012 |
+| 0.1 | 0.002 | 0.102 |
+| 1 | 0.0049 | 1.0049 |
+| 10 | 0.049 | 10.049 |
+
+- The fee is the larger of 49 bps of the price and 0.002 USDC. On `exact`, our gas is 0, because the facilitator sends the
+  transfer.
+- The seller receives its full price. The fee is added on the buyer's side.
+- `upto` costs one Permit2 approval per payer, about 69,300 gas at a 100 gwei base fee, which came to 0.000278 USDC at the
+  calibration's snapshot.
+
+`npx @taifoon/jev-wilson@0.3.1 calibration show monad` prints the shipped table without reading the chain.
+
+## 7. Check a grade on chain
+
+Anyone can check a grade without Taifoon's API:
+
+```sh
+npx @taifoon/jev verify 0x09e9107574b2c66849bb1410f7e2e5f21e2c72b56bb8f89d61188b86d27b59de
+```
+
+It finds the answers row in JevAnswerLog and the decision row in JevDecisionLog. It prints
+`"answersOnChain": true, "decisionOnChain": true` with both txs, their recorders and the decision digest. Add
+`--network base` for a grade recorded on Base. To check a grade by hand:
+
+1. **Answers.** Take the sha256 of the canonical `jev.answer.v1` record (keys sorted at every depth, no whitespace). Read
+   `JevAnswerLog.recordedAt(digest)`, then the `JevAnswered` log. Its `useCase`, `subject`, `inputDigest` and
+   `decisionDigest` must match the record.
+2. **Decision.** Compute `subject_id = keccak256(abi.encode("taifoon.decision.subject.v1", chainId, at, bytes32(ref)))`,
+   then read `JevDecisionLog.decisionsOf(subject_id)[index]`.
+
+The record formats are in [RECORDS.md](RECORDS.md), and the contracts in [ON_CHAIN.md](ON_CHAIN.md).

package/docs/WORKFLOWS.md

@@ -13,8 +13,9 @@ The node outputs the receipt and the unsigned calls, and it signs nothing. With
 
 ## Workflows
 
-`workflows/0.2.14/` holds the four n8n workflows that run Jev (`workflows/0.2.7/` and `workflows/0.2.2/` are kept as
-they shipped; 0.2.14 adds the operator step and the settle row's decision step to `hire-judge-settle.json`). A release attaches the same files
+`workflows/0.2.15/` holds the four n8n workflows that run Jev (`workflows/0.2.14/`, `workflows/0.2.7/` and `workflows/0.2.2/` are
+kept as they shipped; 0.2.14 added the operator step and the settle row's decision step to `hire-judge-settle.json`; 0.2.15
+sets its devnet deadline to 120 s, was 300 s, with a 120 s fallback, was 1 h). A release attaches the same files
 as `jev-workflows-<version>.zip` (`jev-workflows-0.2.7.zip` for 0.2.7):
 
 - **`hire-judge-settle.json`** runs hire → prepare (facts) → TypeSafe (the four RUBRIC_v1 questions) → answers
@@ -27,7 +28,7 @@ as `jev-workflows-<version>.zip` (`jev-workflows-0.2.7.zip` for 0.2.7):
 
 Credential references are placeholders: `{ "id": "", "name": "REPLACE: <credential type>" }`. After import, pick your
 own credential of that type. Each step names the entity it takes and emits by `$id` (`meta.taifoon.steps`). The schemas
-behind those `$id`s are in `workflows/0.2.14/schemas/`. `manifest.json` pins every file by sha256.
+behind those `$id`s are in `workflows/0.2.15/schemas/`. `manifest.json` pins every file by sha256.
 `workflows/0.2.14/README.md` explains each workflow step by step and lists the nodes and credentials it needs:
 
 - `@taifoon/n8n-nodes-typesafe`, tested with 2.0.1, is on npm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Grade AI agent jobs with TypeSafe's Jev and record the verdict on chain: code checks the facts, Jev answers a published rubric, and you get a receipt, the on-chain record and the evaluator call for ERC-8183 and Virtuals ACP. No runtime dependencies, no key inside.",
   "keywords": [
     "jev",