@taifoon/jev 0.2.14 → 0.2.15

package/README.md

@@ -159,6 +159,7 @@ 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)

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/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.15",
   "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",

package/workflows/0.2.15/README.md

@@ -0,0 +1,109 @@
+# Jev workflows 0.2.15
+
+The n8n workflows that run Jev on n8n.taifoon.dev, exported with credential references replaced by placeholders (`{ "id": "", "name": "REPLACE: <credential type>" }`: pick your own credential of that type after import). Import with n8n → Workflows → Import from File, or `n8n import:workflow --input=<file>`. Every step carries its contract: `meta.taifoon.steps` names the canonical entity it takes and emits by `$id`; the schemas are in `schemas/` (the `$id`s are identifiers, the files are here).
+
+## Nodes they need
+
+| Package | Tested with | Where |
+|---|---|---|
+| `@taifoon/n8n-nodes-typesafe` | 2.0.1 | npm (community node): npm i @taifoon/n8n-nodes-typesafe |
+| `n8n-nodes-taifoon` | 0.4.5 | custom extension (type prefix CUSTOM.); not on npm |
+| `n8n-nodes-taifoon-devnet-signer` | 0.3.0 | custom extension (type prefix CUSTOM.); not on npm |
+
+## Credentials they need
+
+| Type | What |
+|---|---|
+| `taifoonTypeSafeApi` | your TypeSafe key (console.typesafe.ai) — credential type "TypeSafe API" of @taifoon/n8n-nodes-typesafe |
+| `taifoonRelayerApi` | a Taifoon relayer key (tfr_…) for https://www.taifoon.io/v1 — credential type "Taifoon Relayer API" of n8n-nodes-taifoon |
+| `taifoonDevnetKeyApi` | a devnet 36927 key with gas from https://faucet.taifoon.dev — credential type "Taifoon Devnet Key API" of n8n-nodes-taifoon-devnet-signer |
+
+## HIRE → JUDGE → SETTLE (devnet 36927) — `hire-judge-settle.json`
+
+One hire from offer to settlement. The seller’s reply is held with its digest; prepare decides the facts (a hard fail skips Jev); your TypeSafe credential answers the four RUBRIC_v1 questions; answers composes the verdict under THRESHOLDS_v1, records decision.v2 and jev.answer.v1 and, with Record On = devnet (set in this file), anchors them on the devnet logs; a complete settles through the devnet assurance hook (approve, fund, submit, complete), needs_review is held until the job’s deadline, when anyone may call expire. Executions 86 and 88 of this workflow are the golden runs @taifoon/jev re-derives.
+
+**Needs:** n8n-nodes-taifoon ≥ 0.4.5 and n8n-nodes-taifoon-devnet-signer ≥ 0.3.0 (custom extensions), @taifoon/n8n-nodes-typesafe ≥ 2.0.1; a Taifoon relayer key, your TypeSafe key, and two devnet 36927 keys (buyer, seller) with gas and dUSDC. **Outputs:** the whole JOB (Receipt, then Proofs · wait): handshake, verdict, decision with its devnet anchor tx, and every settlement transaction with its proof link.
+
+- source: `tfnhiresettle001` on n8n.taifoon.dev · sha256 `b13b48369fb6cdba88371c22d5aba8710eab414ac30a818c2a8189116b86c94b`
+- nodes: `n8n-nodes-taifoon`, `@taifoon/n8n-nodes-typesafe`, `n8n-nodes-taifoon-devnet-signer`; built-ins manualTrigger v1, set v3.4, code v2, if v2.2, httpRequest v4.2
+- credentials: `taifoonRelayerApi`, `taifoonTypeSafeApi`, `taifoonDevnetKeyApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| Start | — | — | start a run (swap for a Webhook or Schedule trigger) |
+| Inputs | — | hire.json | the hire intent: task, candidate seller, endpoint/tool, buyer, price, chain (a HIRE in state Open) |
+| Offer + deliver | hire.json | job.json | POST /v1/handshake {dispatch:true}: the offer goes to the seller’s own endpoint; the reply is held with its keccak digest |
+| Delivery | job.json | delivery.json | stop unless a reply digest is held (no digest = nothing to settle) |
+| Judge · prepare | delivery.json | facts.json | POST /v1/judge/compose (prepare): the facts decide first; hard_fail ends here; else the exact text Jev reads + prepare_digest |
+| Hard fail? | facts.json | facts.json | branch: a hard fail goes straight to the verdict without asking Jev |
+| Jev · TypeSafe (our credential) | facts.json | answers.json | TypeSafe ask on the prepared text: every RUBRIC_ASKED answer with its whole distribution |
+| Judge · answers | answers.json | verdict.json | POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2, anchor on JevDecisionLog |
+| Verdict | verdict.json + facts.json | verdict.json | the composed verdict (complete \| reject \| needs_review) with what settlement needs carried forward |
+| Settle | verdict.json | settlement.json | POST /v1/settle: the plan (jobId, price, premium, deposit, calls[] in order, who signs each) |
+| Seller · approve deposit | settlement.json | settlement.json | the seller approves D (> P); the tx joins settlement.txs |
+| Buyer · approve + fund | settlement.json | settlement.json | the buyer approves P + π and calls fundJob: machine Delivered → Funded |
+| Seller · submit | settlement.json | settlement.json | submit(jobId, evidenceDigest = delivery.digest): machine Funded → Submitted |
+| Verdict says complete? | settlement.json | settlement.json | branch on the composed verdict: complete → complete; otherwise hold (Submitted → Held) |
+| Buyer · complete + capture | settlement.json | settlement.json | complete(jobId) (+ capture): machine → Settled |
+| Settle row · decided | settlement.json | settlement.json | the settle row names the decision, not a document: POST /v1/settle/decided { jobId, decision_id, end_tx = the complete transaction } on the lane’s relayer key. The layer writes decided_by "jev" only when the chain proves it (an automatic complete, the decision’s anchor on the JevDecisionLog, the job bound to the handshake and its sealed reply, Completed for this job); it never errors the run |
+| Held for review | settlement.json | settlement.json | needs_review / reject: funded and sealed, nothing paid; the operator step (a record, then the evaluator’s postVerdict) or the deadline decides |
+| Receipt | settlement.json | job.json | the whole JOB: hire, delivery, facts, verdict, settlement — every transaction with its proof link |
+| Proofs · wait | job.json | job.json | GET /v1/proof/tx/36927/<tx> for every transaction of the run; pending is retried with backoff (5 s -> 60 s, <= 240 s), never reported as a gap |
+| Operator step · open | settlement.json | settlement.json | the evaluator leg, not a document: POST /v1/settle/evaluate {open:true} opens the operator step of a job held on needs_review. The workflow does not decide: the step waits for an operator record (decided_by loop-agent on the devnet, or operator with the operator key), anchored on chain before the evaluator posts. A composed reject is not an operator step (the layer answers not_needs_review) |
+
+## Jev on-chain grader (grade → stamp → devnet) — `jev-grader.json`
+
+Grades Base jobs that were paid and delivered and that nobody ruled on (GET /v1/judge/ready): four per run, each through prepare → Jev → answers, then the canonical verdict, then GradeStampRegistry.stamp on the devnet, signed by the devnet signer node; the stamp transaction is appended to the verdict’s anchors.
+
+- source: `tfnjevgrader0001` on n8n.taifoon.dev · sha256 `762248c554dd0607362e20361ec3efe0fda58326d89c2f1c18c525ea48e92e35`
+- nodes: `n8n-nodes-taifoon`, `@taifoon/n8n-nodes-typesafe`, `n8n-nodes-taifoon-devnet-signer`; built-ins manualTrigger v1, code v2, if v2.2
+- credentials: `taifoonRelayerApi`, `taifoonTypeSafeApi`, `taifoonDevnetKeyApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| When clicking ‘Execute workflow’ | — | — | start a grading run |
+| Ready jobs (Base) | — | job.json | GET /v1/judge/ready: jobs on Base that were paid and delivered, and nobody ruled |
+| Pick 4 calibrated | job.json | job.json | keep four whose seller has a calibrated record; one item per job, no state built here |
+| Judge · prepare | job.json | facts.json | POST /v1/judge/compose (prepare) on the job: facts decide first; the pack comes from the job evidence (GRADEABLE labels 1–21) |
+| Hard fail? | facts.json | facts.json | a hard fail is final at prepare (Jev is not asked; nothing to stamp) |
+| Jev · TypeSafe (our credential) | facts.json | answers.json | TypeSafe ask on the prepared text (jevStateOf): every RUBRIC_ASKED answer with its whole distribution |
+| Judge · answers | answers.json | verdict.json | POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2 and the answers, anchor both |
+| Verdict | verdict.json | verdict.json | the recorded decision as a canonical VERDICT (fromDecision), composed from this run’s receipt |
+| Stamp Grade (unsigned) | verdict.json | verdict.json | POST /v1/assurance/call stampGrade: the unsigned GradeStampRegistry.stamp(subject_id, digest, verdict code, mode 2) |
+| Taifoon Devnet Signer | verdict.json | verdict.json | sign and send the stamp on devnet 36927 (anvil #0) |
+| Verdict + stamp | verdict.json | verdict.json | the same VERDICT with the stamp transaction appended to anchors |
+
+## Batch judge — `batch-judge.json`
+
+A batch of subjects, each as its own prepare → Jev → answers (so every answer is recorded), aggregated and posted to POST /v1/judge/batch.
+
+- source: `tfnbatchjudge001` on n8n.taifoon.dev · sha256 `8e66a8e261e9f1f8052bd0b7658cb2ef5212d8df89b8a5347b56762701f078fd`
+- nodes: `n8n-nodes-taifoon`, `@taifoon/n8n-nodes-typesafe`; built-ins manualTrigger v1, code v2, if v2.2, httpRequest v4.2
+- credentials: `taifoonRelayerApi`, `taifoonTypeSafeApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| Grade a batch | — | — | start a batch (pass { subjects, jobId, threshold } or run the demo set) |
+| Build the batch | — | hire.json | one canonical HIRE per subject (a delivered handshake, or a job on chain); no state is built here |
+| Judge · prepare | hire.json | facts.json | POST /v1/judge/compose (prepare) per subject: the facts decide first; the pack is built from DELIVERY + FACTS; else the exact text Jev reads + prepare_digest |
+| Hard fail? | facts.json | facts.json | branch: a hard fail is final (Jev is not asked) and goes straight to the batch |
+| Jev · TypeSafe (our credential) | facts.json | answers.json | TypeSafe ask on the prepared text (jevStateOf): every RUBRIC_ASKED answer with its whole distribution |
+| Judge · answers | answers.json | verdict.json | POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2 and the answers (jev.answer.v1), anchor both |
+| Grade + aggregate | facts.json + verdict.json | — | the batch outcome from the recorded verdicts (Conformant / NonConformant / NoGrade counts, fail fraction vs threshold) — a batch record, not a canonical entity |
+| Record the batch to the coordination layer | — | — | POST /v1/judge/batch (relayer key): the batch record, keyed batch:<jobId> |
+
+## Stamp Grade (a recorded verdict → GradeStampRegistry) — `stamp-grade.json`
+
+Takes one recorded decision (by id), maps it to the canonical verdict, and stamps it on the devnet GradeStampRegistry; emits the verdict with the stamp transaction in its anchors.
+
+- source: `tfnstamp00000001` on n8n.taifoon.dev · sha256 `516d9483e3d26e1891dacb8c4493d609340e3c6a3b200784c72864f9cb931ebc`
+- nodes: `n8n-nodes-taifoon`, `n8n-nodes-taifoon-devnet-signer`; built-ins manualTrigger v1, code v2
+- credentials: `taifoonDevnetKeyApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| Start | — | — | start (pass { decision_id } to stamp another verdict) |
+| Verdict | — | verdict.json | GET /v1/judge/decisions/:id → the canonical VERDICT (fromDecision) and its stamp code |
+| Stamp Grade | verdict.json | verdict.json | POST /v1/assurance/call stampGrade: the unsigned GradeStampRegistry.stamp(subject_id, digest, verdict code, mode) |
+| Taifoon Devnet Signer | verdict.json | verdict.json | sign and send the stamp on devnet 36927 (anvil #0) |
+| Verdict + stamp | verdict.json | verdict.json | the same VERDICT with the stamp transaction appended to anchors |