@taifoon/jev 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to `@taifoon/jev`. Versions follow the GitHub releases of this repository; each is published to npm
+with provenance by `.github/workflows/publish.yml`.
+
+## 0.4.0
+
+- `verify` reads a trusted record past an endpoint that serves only recent logs. `JevAnswerLog.recordedAt` names the block
+  of a trusted record; when an endpoint answers `[]` for that block, the next endpoint of the rotation is asked. A record
+  reads `not_recorded` only when every endpoint that answered held no row; no answer at all is still `rpc_unavailable`.
+  (Seen on Base for a record 1.35M blocks old.) Two tests cover both outcomes.
+- `src/attest.ts`: the defaults of an unknown chain are their own typed value, so the copy compiles under stricter
+  TypeScript settings (TS2783). Types only; the calls it returns are unchanged.
+- Taifoon mainnet (3692781) is Jev's record home: `record()` builds the `JevAnswerLog.record` and `JevDecisionLog.record`
+  calls for it by default (JevDecisionLog `0xaEbF9084Bb32eB2E0F58537526A8877dd1436b23`, JevAnswerLogV2
+  `0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c`), and `verify --chain taifoon` reads them. It has no GradeStampRegistry
+  yet; the stamp is listed under `missing`.
+- Base: answers are written to JevAnswerLogV2 (`0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c`, from block 52639649).
+  `verify` reads V2 first, then the earlier JevAnswerLog (`0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d`), so every
+  earlier record still verifies. Two tests cover both logs.
+- README: what you get, how it works, and where Jev's records live.
+- package: CHANGELOG.md ships in the tarball; search keywords.
+
+## 0.3.0 (2026-10-14)
+
+- Recording is on by default: every grade returns the unsigned `JevAnswerLog.record`, `JevDecisionLog.record` and
+  `GradeStampRegistry.stamp` calls for the Taifoon devnet 36927 and the Taifoon mainnet 3692781 (`--record none` turns
+  them off; a contract a network does not have is listed in `missing`). One shared attestation helper for the mark, the
+  attestation and the stamp.
+- Optional fields of the attestation helper accept `undefined` (`exactOptionalPropertyTypes`).
+
+Earlier versions: see the [releases](https://github.com/taifoon-io/jev/releases).

package/README.md

@@ -1,24 +1,83 @@
-# @taifoon/jev
+<p align="center">
+  <img src="https://raw.githubusercontent.com/taifoon-io/jev/main/assets/banner.svg" alt="Jev for agent jobs" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@taifoon/jev"><img src="https://img.shields.io/npm/v/@taifoon/jev?style=flat-square&labelColor=000000&color=3DA5FF&label=npm" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/@taifoon/jev#provenance"><img src="https://img.shields.io/badge/provenance-signed-00B5B8?style=flat-square&labelColor=000000" alt="provenance"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@taifoon/jev?style=flat-square&labelColor=000000&color=E6F0F7" alt="licence"></a>
+  <a href="https://www.npmjs.com/package/@taifoon/jev"><img src="https://img.shields.io/npm/dm/@taifoon/jev?style=flat-square&labelColor=000000&color=3DA5FF" alt="downloads"></a>
+</p>
 
 **Did the AI agent do the work it was paid for? Ask Jev, and get an answer you can check.**
 
-- **What:** a grader for agent jobs. Code checks the facts, TypeSafe's Jev answers four closed questions about the
-  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 Base job, graded by Jev, offline and with no key:
+Code checks the facts of the delivery, TypeSafe's Jev answers four closed questions about it, and code turns the answers
+into **complete**, **reject** or **needs review**, with a receipt anyone can recompute, the unsigned calls that record it on
+chain and the one call that ends the job on its protocol (ERC-8183, Virtuals ACP, BitAgent). No key inside, and it signs
+nothing.
 
-```
+## 30 seconds
+
+```sh
 npx @taifoon/jev run --demo
 ```
 
+Offline, no key: replays BitAgent job 7287 on Base as Jev graded it, composes **reject**, and arrives at the decision
+digest that is anchored on chain. Then read a recorded grade back from Base:
+
+```sh
+npx @taifoon/jev verify decision-1790522234088-10691d5017 --network base
+```
+
+It recomputes the record's digests offline and finds both rows on Base (`"status": "recorded"`).
+
 ![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 no key, on your free grades on the Taifoon coordination layer (3 a day per caller), or 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. Every grade comes with the unsigned calls that record it on chain (the Taifoon devnet and mainnet by default, any network you name; `--record none` turns them off).
+## What you get
+
+| | |
+|---|---|
+| **A verdict with its reasons** | complete, reject or needs review, with every answer's full probability distribution |
+| **A receipt anyone can recompute** | digests of the evidence, the answers and the decision; `verify()` recomputes them offline |
+| **The on-chain record, unsigned** | `JevAnswerLog.record`, `JevDecisionLog.record` and `GradeStampRegistry.stamp` calls for your wallet |
+| **The call that ends the job** | the evaluator call for `assurance-hook`, `judge-adapter`, `virtuals-erc8183`, `virtuals-memo-acp`, `bitagent-erc8183` |
+| **A cover price for the next job** | the seller's premium from its record, through [`@taifoon/jev-wilson`](https://www.npmjs.com/package/@taifoon/jev-wilson) |
+| **No key needed to start** | 3 free grades a day per caller on the Taifoon coordination layer, or your own TypeSafe key |
+
+## How it works
+
+```
+the job as the buyer wrote it (task, criteria, source, delivered)
+        │ prepareJob()
+        ▼
+code checks the facts ─── a check fails ──▶ reject (Jev is not asked)
+        │ all pass
+        ▼
+Jev answers RUBRIC_v1: spec_met · unsupported_claim · ending · cheat_shaped
+        │ grade()
+        ▼
+code composes THRESHOLDS_v1 ──▶ complete | reject | needs_review + receipt
+        │ record() · evaluatorCall()
+        ▼
+unsigned calls: the answer log, the decision log, the evaluator seat (you sign)
+        │ verify()
+        ▼
+digests recomputed, rows found on chain
+```
+
+## Install
+
+```sh
+npm i @taifoon/jev
+```
+
+Node.js 20 or later. Installing it also installs Taifoon's other packages (@taifoon/jev-wilson,
+@taifoon/n8n-nodes-typesafe); nothing third-party. Grade with no key on your free grades on the Taifoon coordination layer
+(3 a day per caller), or with your TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai). Every grade comes
+with the unsigned calls that record it on chain (the Taifoon devnet and mainnet by default, any network you name;
+`--record none` turns them off).
 
-## Quick start
+## Grade your own job
 
 An agent was hired for a job. The grader answers one question: did it do the work as the task laid it out? You give
 it the job the way the buyer wrote it, and it does the rest:
@@ -182,8 +241,30 @@ npx @taifoon/jev workflows export ./jev-workflows
 ## Chains
 
 `verify` reads the Jev logs on every chain they are deployed to: the Taifoon devnet (36927), Base (8453), Arbitrum One
-(42161), Arc (5042) and Monad (143). Robinhood Chain (4663), Taifoon mainnet (3692781) and Ethereum (1) are known
-chains with no Jev log yet; `verify` says so instead of reading them.
+(42161), Arc (5042) and Monad (143). Robinhood Chain (4663) and Ethereum (1) are known chains with no Jev log; `verify`
+says so instead of reading them.
+
+### Where Jev's records live
+
+| Chain | JevDecisionLog | JevAnswerLog |
+|---|---|---|
+| Taifoon mainnet (3692781), the record home | `0xaEbF9084Bb32eB2E0F58537526A8877dd1436b23` | `0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c` (JevAnswerLogV2) |
+| Base (8453) | [`0x209490d6A0FFC5368A42b0c2208BDCda853f6a92`](https://basescan.org/address/0x209490d6A0FFC5368A42b0c2208BDCda853f6a92) | [`0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c`](https://basescan.org/address/0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c) (JevAnswerLogV2); earlier records in [`0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d`](https://basescan.org/address/0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d) |
+| Taifoon devnet (36927) | `0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05` | `0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3` |
+
+The two Taifoon mainnet logs were deployed on 2026-11-08 at their CREATE2 addresses (JevAnswerLogV2 has the same
+address on Base). Taifoon mainnet has no public explorer yet; read them from its public RPC:
+
+```sh
+curl -s https://mainnet.taifoon.dev -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getCode","params":["0xaEbF9084Bb32eB2E0F58537526A8877dd1436b23","latest"]}'
+```
+
+`record()` builds the calls for both logs on Taifoon mainnet by default (next to the devnet), and `verify --chain taifoon`
+reads them. Taifoon mainnet has no GradeStampRegistry yet, so the stamp is listed under `missing` there, said rather
+than faked. On Base, answers are written to JevAnswerLogV2 and `verify` reads it first, then the earlier JevAnswerLog,
+so a record from before V2 still verifies. Base keeps its published JevDecisionLog. Every address above is in
+`src/addresses.ts` and `src/attest.ts`.
 
 | Flag | What it does |
 |---|---|
@@ -213,6 +294,12 @@ it ships (`src/rpc-fallback.ts`, generated from the RPC registry).
 In code: `verify(digest, { network: 'arbitrum' })` (a name or a chain id), `{ rpc: 'https://…' }`, and `JevChainError`
 (`code`: `rpc_unavailable`, `not_deployed`, `reverted`, `bad_input`) from the lower-level calls.
 
+## Links
+
+- npm: [@taifoon/jev](https://www.npmjs.com/package/@taifoon/jev) · pricing: [@taifoon/jev-wilson](https://www.npmjs.com/package/@taifoon/jev-wilson) · n8n: [@taifoon/n8n-nodes-typesafe](https://www.npmjs.com/package/@taifoon/n8n-nodes-typesafe)
+- The coordination layer: [coord.taifoon.dev/v1](https://coord.taifoon.dev/v1) ([OpenAPI](https://coord.taifoon.dev/v1/openapi.json)) · [taifoon.io](https://www.taifoon.io)
+- Changes: [CHANGELOG.md](CHANGELOG.md) · issues: [github.com/taifoon-io/jev/issues](https://github.com/taifoon-io/jev/issues) · contact: info@taifoon.io
+
 ## Licence
 
 Independent project. Jev and TypeSafe are products of TypeSafe AI, Inc., which does not endorse this package.

package/dist/addresses.d.ts

@@ -60,7 +60,8 @@ export declare const REGISTRY_ADDRESSES: {
         readonly block: 48395723;
     };
 };
-/** The Jev logs on every chain the registry deploys them to (JevAnswerLog + JevDecisionLog, from their deploy block). */
+/** The Jev logs on every chain the registry deploys them to (from their deploy block): the answer log records go to (JevAnswerLogV2
+ *  where it is live, else JevAnswerLog), the decision log, and the earlier answer logs still read (Base: the first JevAnswerLog). */
 export declare const JEV_LOGS: Readonly<Record<number, {
     answerLog: {
         address: string;
@@ -70,4 +71,8 @@ export declare const JEV_LOGS: Readonly<Record<number, {
         address: string;
         fromBlock: number;
     };
+    earlierAnswerLogs?: readonly {
+        address: string;
+        fromBlock: number;
+    }[];
 }>>;

package/dist/addresses.js

@@ -22,11 +22,13 @@ export const REGISTRY_ADDRESSES = {
     /** standards-erc8183 · BitAgent ERC-8183 escrow (live) */
     bitagentErc8183: { chainId: 8453, address: '0x5009ABB3A309115a4a682C66BAf3BC9E0329BaB7', block: 48395723 },
 };
-/** The Jev logs on every chain the registry deploys them to (JevAnswerLog + JevDecisionLog, from their deploy block). */
+/** The Jev logs on every chain the registry deploys them to (from their deploy block): the answer log records go to (JevAnswerLogV2
+ *  where it is live, else JevAnswerLog), the decision log, and the earlier answer logs still read (Base: the first JevAnswerLog). */
 export const JEV_LOGS = {
     143: { answerLog: { address: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', fromBlock: 110216088 }, decisionLog: { address: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', fromBlock: 110216093 } },
     5042: { answerLog: { address: '0x45214361A8cADb8aEe6302cd5653E119E5a89839', fromBlock: 24071071 }, decisionLog: { address: '0x863db7dAc69CC614a98822082cbe884F1f3b55cA', fromBlock: 24071074 } },
-    8453: { answerLog: { address: '0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d', fromBlock: 51863008 }, decisionLog: { address: '0x209490d6A0FFC5368A42b0c2208BDCda853f6a92', fromBlock: 51856200 } },
+    8453: { answerLog: { address: '0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c', fromBlock: 52639649 }, decisionLog: { address: '0x209490d6A0FFC5368A42b0c2208BDCda853f6a92', fromBlock: 51856200 }, earlierAnswerLogs: [{ address: '0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d', fromBlock: 51863008 }] },
     36927: { answerLog: { address: '0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3', fromBlock: 1106754 }, decisionLog: { address: '0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05', fromBlock: 981099 } },
     42161: { answerLog: { address: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', fromBlock: 511340178 }, decisionLog: { address: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', fromBlock: 511340188 } },
+    3692781: { answerLog: { address: '0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c', fromBlock: 2598386 }, decisionLog: { address: '0xaEbF9084Bb32eB2E0F58537526A8877dd1436b23', fromBlock: 2598383 } },
 };

package/dist/attest.js

@@ -22,10 +22,10 @@
 export const ATTEST_TARGETS = {
     143: { name: 'Monad', decisionLog: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', answerLog: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', stampRegistry: null },
     5042: { name: 'Arc', decisionLog: '0x863db7dAc69CC614a98822082cbe884F1f3b55cA', answerLog: '0x45214361A8cADb8aEe6302cd5653E119E5a89839', stampRegistry: null },
-    8453: { name: 'Base', decisionLog: '0x209490d6A0FFC5368A42b0c2208BDCda853f6a92', answerLog: '0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d', stampRegistry: null },
+    8453: { name: 'Base', decisionLog: '0x209490d6A0FFC5368A42b0c2208BDCda853f6a92', answerLog: '0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c', stampRegistry: null },
     36927: { name: 'Taifoon devnet', decisionLog: '0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05', answerLog: '0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3', stampRegistry: '0xff5B4852AC7066D04FEd8de97bdA52401d03ad6E' },
     42161: { name: 'Arbitrum One', decisionLog: '0x1aC6266b9926cB3E206D5dc0c9d1B7c873aa150a', answerLog: '0x29fEEc116e0CAbbaf38e9EBF2BBf65d82D672104', stampRegistry: null },
-    3692781: { name: 'Taifoon mainnet', decisionLog: null, answerLog: null, stampRegistry: null },
+    3692781: { name: 'Taifoon mainnet', decisionLog: '0xaEbF9084Bb32eB2E0F58537526A8877dd1436b23', answerLog: '0xC08dfc61d702AEA45d1EF2515d8BDA36d548C75c', stampRegistry: null },
 };
 // ── END GENERATED ──
 /** The default networks per profile. Taifoon: its devnet and its mainnet (GRID). Moonbeam: Base only. */
@@ -198,7 +198,9 @@ export function attest(input, opts = {}) {
     const calls = [];
     const missing = [];
     for (const chainId of networks) {
-        const t = { name: `chain ${chainId}`, decisionLog: null, answerLog: null, stampRegistry: null, ...ATTEST_TARGETS[chainId], ...opts.targets?.[chainId] };
+        // the defaults as their own value: written inline before a spread of a fully typed target, tsc refuses them (TS2783)
+        const unknownChain = { name: `chain ${chainId}`, decisionLog: null, answerLog: null, stampRegistry: null };
+        const t = { ...unknownChain, ...ATTEST_TARGETS[chainId], ...opts.targets?.[chainId] };
         const gap = (contract) => missing.push({ chainId, network: t.name, contract, why: `no ${contract} on ${t.name} (${chainId}) in the address registry` });
         // the answers first, then the decision that cites them (the order the layer's recorder sends)
         if (input.answers) {

package/dist/chains.d.ts

@@ -13,6 +13,10 @@ export declare const jevLogsOn: (chainId: number) => {
         address: string;
         fromBlock: number;
     };
+    earlierAnswerLogs?: readonly {
+        address: string;
+        fromBlock: number;
+    }[];
 } | null;
 /** Every chain that carries Jev logs, the devnet first, then Base, then the rest by id. */
 export declare const JEV_CHAINS: readonly number[];

package/dist/verify.js

@@ -15,6 +15,33 @@ const hexN = (n) => '0x' + n.toString(16);
 async function logs(rpc, f, address, topics, fromBlock, toBlock, chainId) {
     return (await rpcCall(rpc, f, 'eth_getLogs', [{ address, topics, fromBlock: hexN(fromBlock), toBlock: toBlock == null ? 'latest' : hexN(toBlock) }], { chainId })) ?? [];
 }
+/**
+ * _LOGS_AT_TRUSTED_v1_: the rows of the one block JevAnswerLog.recordedAt named. That block holds a trusted record, so an
+ * empty answer is the endpoint's (one that serves only recent logs answers [] for an older block instead of an error:
+ * base.rpc.blxrbdn.com, first in Base's rotation, did for a 1.35M-block-old record on 2026-10-29) and the next endpoint
+ * is asked. [] only when every endpoint that answered said so; no answer at all is rpc_unavailable, as before.
+ */
+async function logsAtRecorded(rpc, f, address, topics, block, chainId) {
+    const urls = typeof rpc === 'string' ? [rpc] : rpc;
+    let answered = false;
+    let last = null;
+    for (const u of urls) {
+        try {
+            const l = await logs(u, f, address, topics, block, block, chainId);
+            answered = true;
+            if (l.length)
+                return l;
+        }
+        catch (e) {
+            if (e instanceof JevChainError && e.code !== 'rpc_unavailable')
+                throw e;
+            last = e;
+        }
+    }
+    if (!answered && last)
+        throw last;
+    return [];
+}
 const SEL_RECORDED_AT = keccakHex('recordedAt(bytes32)').slice(0, 10);
 /** JevAnswerLog.recordedAt(digest): the block of the first trusted record, 0 when none. */
 async function recordedAt(rpc, f, address, digest, chainId) {
@@ -125,9 +152,14 @@ export async function verify(x, opts = {}) {
                 const given = typeof opts.rpc === 'string' ? opts.rpc.split(',').map((u) => u.trim()).filter(Boolean) : opts.rpc;
                 const rpc = given?.length ? given : await rpcRotation(chainId, f);
                 if (chainId !== DEVNET) {
-                    const at = await recordedAt(rpc, f, dev.answerLog.address, answersDigest, chainId);
-                    if (at > 0)
-                        onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], at, at, chainId)).map(answerEvent);
+                    // _JEV_SEATS_v1_: the answer log records go to (JevAnswerLogV2 where live), then the earlier ones still read (Base: the first log)
+                    for (const log of [dev.answerLog, ...(dev.earlierAnswerLogs ?? [])]) {
+                        const at = await recordedAt(rpc, f, log.address, answersDigest, chainId);
+                        if (at > 0) {
+                            onChain.answers = (await logsAtRecorded(rpc, f, log.address, [TOPIC_ANSWERED, null, null, answersDigest], at, chainId)).map(answerEvent);
+                            break;
+                        }
+                    }
                 }
                 else
                     onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], dev.answerLog.fromBlock, undefined, chainId)).map(answerEvent);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.3.0",
-  "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.",
+  "version": "0.4.0",
+  "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 third-party runtime dependencies, no key inside.",
   "keywords": [
     "jev",
     "typesafe",
@@ -18,7 +18,16 @@
     "ai-agents",
     "on-chain",
     "attestation",
-    "base"
+    "base",
+    "taifoon",
+    "agent-evaluation",
+    "ai-evaluation",
+    "llm-evaluation",
+    "verifiable-ai",
+    "receipt",
+    "x402",
+    "arbitrum",
+    "monad"
   ],
   "license": "MIT",
   "author": {
@@ -51,6 +60,7 @@
     "examples",
     "README.md",
     "LICENSE",
+    "CHANGELOG.md",
     "!docs/demo.gif"
   ],
   "sideEffects": false,