@taifoon/jev 0.1.0 → 0.2.1

package/README.md

@@ -1,222 +1,128 @@
 # @taifoon/jev
 
-Jev is a grader that any protocol can call from a contract's evaluator seat. The pipeline is code facts, then calibrated
-answers, then a composed verdict, a receipt, the on-chain record and finally the evaluator call.
+**Did the AI agent do the work it was paid for? Ask Jev, and get an answer you can check.**
 
-Built by Taifoon. MIT. The package has no runtime dependencies and contains no key.
+- **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 real Base job, graded by Jev, offline and with no key:
 
 ```
-npm i @taifoon/jev
+npx @taifoon/jev run --demo
 ```
 
-The package also ships the n8n workflows that run Jev as a versioned bundle (see [Workflows](#workflows)).
+Then grade your own with your TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai). No runtime
+dependencies, no key inside, and it signs nothing. Recording a grade on chain is optional.
 
-## What Jev is
+## Quick start
 
-Jev is TypeSafe's System One decision model. When this was written it answered as **`jev-1.13.0`**. You don't ask Jev
-for prose. You give it closed questions, and every answer comes back as a **full probability distribution** over the
-options, plus a confidence value. An answer to "did the delivery meet the spec?" looks like `{ yes: 0.93, no: 0.07 }`,
-not a paragraph.
-
-This package puts Jev inside a fixed judging procedure:
-
-- Code establishes the facts first. A failed check ends the job, and Jev is never asked.
-- Jev answers four **atomic** questions from a published rubric. It never gets a holistic "is the job good?".
-- Code composes the verdict from the facts and the answers under published thresholds.
-- Everything is hashed into a receipt, recorded on chain and turned into the one call that ends the job.
-
-How to describe the result: *graded against a published rubric by a pinned decision model, with an appeal.* It is not
-"independently verified". An on-chain record is an attestation by whoever sent it, not a proof that the answer is right.
-
-## The pipeline
-
-```
- evidence ─► facts() ──── a check failed? ── yes ─► reject (hard fail; Jev is not asked)
-             code checks                     │
-                                             no
-                                             ▼
-             Jev reads: evidence (cut at 3,600 chars) + the facts section + one instruction
-             Jev answers RUBRIC_v1:  spec_met · unsupported_claim · ending · cheat_shaped
-                                             ▼
-             compose under THRESHOLDS_v1 ─► complete | reject | needs_review
-                                             ▼
-             receipt: rubric hash, input digest, every distribution, verdict, reasons, receiptHash
-                                             ▼
-             record()  ─► JevAnswerLog.record (jev.answer.v1)  +  JevDecisionLog.record (decision.v2)
-                                             ▼
-             evaluatorCall() ─► complete / reject on the job's protocol   (needs_review ends nothing: appeal)
-```
-
-THRESHOLDS_v1:
-
-- **complete** needs spec_met ≥ 0.85, unsupported_claim ≤ 0.20 and ending = complete.
-- **reject** follows from spec_met ≤ 0.40, unsupported_claim ≥ 0.70 or ending = reject.
-- **needs_review** is the result when cheat_shaped ≥ 0.50 (escalate, never slash on this alone) or when the answers
-  land in the mid band.
-- Above 50 USDC a complete is held for review.
-
-## Quickstart
-
-This is `examples/quickstart.mjs`, run as is:
+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:
 
 ```js
-import { createHash } from 'node:crypto';
-import { grade, facts, record, evaluatorCall, verify } from '@taifoon/jev';
-
-const task = 'Return the SHA-256 hex digest of the ASCII string "jev".';
-const delivered = createHash('sha256').update('jev').digest('hex');   // what the seller handed in
-
-const receipt = await grade({
-  subject: { chainId: 8453, ref: 'quickstart:sha256-jev' },            // what is being judged (your job id)
-  evidence: { task, delivered },
-  facts: facts({ delivered: true, checks: { digest_recomputes: () => createHash('sha256').update('jev').digest('hex') === delivered } }),
-  trial: true,                                                          // 3 free calls; or { key: process.env.TYPESAFE_KEY }
+import { prepareJob, facts, grade, record } from '@taifoon/jev';
+
+const job = prepareJob({
+  id: 'job-4711', chainId: 8453,
+  task: 'Extract the invoice into JSON with invoice_no, total, currency and due_date',
+  criteria: ['Returns one JSON object with exactly the four fields', 'Every value matches the source invoice'],
+  source: 'INVOICE INV-20931 · Total due: EUR 1,240.50 · Payment due by 2026-10-01',
+  delivered: '{"invoice_no":"INV-20931","total":1240.50,"currency":"EUR","due_date":"2026-10-01"}',
+  checks: [{ kind: 'json', keys: ['invoice_no', 'total', 'currency', 'due_date'] }],
 });
-console.log(receipt.verdict, '·', receipt.reasons[0]);
-console.log('spec_met', receipt.answers?.spec_met.probabilities, '· model', receipt.model);
-const onchain = await record(receipt);                                  // unsigned: JevAnswerLog + JevDecisionLog (devnet)
-const end = evaluatorCall('virtuals-erc8183', 1n, receipt, receipt);    // unsigned: complete / reject as job 1's evaluator
-console.log(onchain.calls.map((c) => c.fn), '→', end?.fn, '· verifies:', (await verify(receipt, { chain: false })).ok);
-```
-
-Real output from one call to the public trial (2026-09-27):
-
-```
-complete · spec_met 0.93 ≥ 0.85 · unsupported_claim 0.10 ≤ 0.2 · ending complete
-spec_met { no: 0.07, yes: 0.93 } · model jev-1.13.0
-[ 'JevAnswerLog.record', 'JevDecisionLog.record' ] → complete(uint256,bytes32,bytes) · verifies: true
+const receipt = await grade({ subject: job.subject, evidence: job.evidence, facts: facts(job.facts), key: process.env.TYPESAFE_KEY });
+receipt.verdict;              // complete | reject | needs_review, with every answer's full distribution
+await record(receipt);        // the unsigned calls that put it on chain
 ```
 
-## The five calls
-
-| Call | What it does | Network |
-|---|---|---|
-| `grade({ subject, evidence, facts?, rubric?, key? \| trial })` | Checks the facts first. If none fails, asks Jev the rubric, composes the verdict and returns the receipt. | Asks Jev once, or never on a hard fail |
-| `facts({ delivered, checks, priceUsdc? })` | Runs the checks your protocol supplies. A check is a value or an (async) function; one that throws counts as "could not be checked". | None |
-| `record(receipt, { network, send? })` | Returns the unsigned `JevAnswerLog.record` and `JevDecisionLog.record` calls. `network` is a flag: `none`, `devnet` (default), `base` or `both`. Pass `send` (your wallet) to send every call that has an address. | None unless you pass `send` |
-| `evaluatorCall(protocol, jobId, verdict, digest)` | Returns the one unsigned call that ends the job on that protocol. For `needs_review` it returns `null`. | None |
-| `verify(receiptOrDigest)` | Recomputes every digest, re-composes the verdict and finds the `JevAnswered` and `Decided` events. | One devnet RPC read |
-
-It also exports `RUBRIC_v1` and `CONTRACTS`. Nothing else.
-
-**Where Jev is reached.** With `trial: true`, calls go to `https://typesafe.taifoon.dev/v1/trial`. The trial is free for
-3 calls per caller, takes at most 4 questions and 4,000 JSON characters, and SDK cuts the evidence to fit (never the facts
-section). With `key`, calls go to `https://api.typesafe.ai/v1/systemone` using your own TypeSafe key from
-[console.typesafe.ai](https://console.typesafe.ai). The key is not stored and never appears in a receipt. If you already
-have the answers (from the n8n node, for example), pass `answers` and nothing is asked.
-
-**Your own rubric.** `grade({ rubric: { version, questions, asked?, thresholds?, compose? } })`. The rubric hash is
-sha256 of its questions and goes into the receipt.
+What the grader needs, and where it comes from:
 
-## Evaluator seats
-
-Each adapter is one small file with its ABI fragment. Each one is tested against calldata that a mined transaction
-carried (`test/fixtures/evaluator-calls.json`, written by `scripts/record-evaluator-fixtures.mjs`).
-
-| `protocol` | Call | Tested against |
-|---|---|---|
-| `assurance-hook` | `complete(bytes32)` / `reject(bytes32 jobId, bytes32 digest)`, with `opts.to` = the hook | Base [`0xc606d00f…3116`](https://basescan.org/tx/0xc606d00fed64e912585bbc93feb15a9289cfcde94289f49f7c74a7a468903116), the complete of a covered GLMR hire on Moonbeam's hook (funded in [`0xfbe436ce…f193`](https://basescan.org/tx/0xfbe436ced5caf66dde0e96033f041480316fc5f62cd273006ad9c1852a57f193)) |
-| `judge-adapter` | `postVerdict(bytes32 jobId, 1\|2, 2, bytes32 digest)` → hook complete / reject | devnet [`0x07853069…2012`](https://www.taifoon.io/scan/36927/tx/0x07853069cf43200fad3761d05b532c654df6f02b8a47f5f767bec18cb91a2012) |
-| `virtuals-erc8183` | AgenticCommerceV3 `complete` / `reject(uint256, bytes32 reason, bytes)` as the job's evaluator | Base [`0x60890802…27bd`](https://basescan.org/tx/0x60890802a3b399af7face54c1cb33d771cffc9b8594d0113de14ae290b5c27bd) (complete) and [`0x152b5fb8…db76`](https://basescan.org/tx/0x152b5fb8900e57119cee6cbc15206d8938c11dc4056b20ec4c986f4d8acddb76) (reject), inside ERC-4337 handleOps |
-| `virtuals-memo-acp` | ACPRouter `signMemo(uint256 memoId, bool approved, string reason)` on the evaluation memo | Base [`0x94ba6b49…622e`](https://basescan.org/tx/0x94ba6b497e2fc2ecf7ae256e1a490cabdc4a5357ed306ee2071f46a1c4ef622e) |
-| `bitagent-erc8183` | AgenticCommerce `complete` / `reject(uint256, bytes32, bytes)` as the job's evaluator; `seat: 'platform'` → Evaluator `forceSettleJob(uint256, bool)` | Base [`0x195359ba…b01e`](https://basescan.org/tx/0x195359ba64f8ba429c449e82c27d0c57486511593646886b59a0d80c808fb01e) (forceSettleJob, job 8941) and its submit [`0xa4a49696…4ebc`](https://basescan.org/tx/0xa4a496968877ccbf1ba73fe5c5908f064d7333a2ced984e1867da9ee70f74ebc) (same layout) |
-
-The digest in the call is the receipt's decision digest. That is the same 32 bytes JevDecisionLog holds, so the job's
-ending, the decision record and the receipt all carry one value. On a hard fail no decision exists, so pass
-`receipt.receiptHash`.
-
-Whoever holds the seat signs the call; this package never does. The BitAgent implementation is unverified on Base, and
-its layout was read from its own transactions. Its jobs settle today through the platform Evaluator, which only
-BitAgent's operators can call.
-
-## On chain today
-
-The logs are on the public devnet (chain 36927, free gas from `https://faucet.taifoon.dev`). Any account may send to
-them.
-
-| Contract | Address | Rule |
+| Field | What it is | Who checks it |
 |---|---|---|
-| JevAnswerLog | `0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3` | Append-only, no owner. Recorders fixed at deploy are `trusted`; any other sender is logged with `trusted = false` |
-| JevDecisionLog | `0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05` | Append-only, no owner, no upgrade. The recorder is `msg.sender` |
-
-For Base, `CONTRACTS.base.answerLog` and `CONTRACTS.base.decisionLog` are `null` in 0.1.0. So `record(receipt, { network: 'base' })` returns the Base call data with `to: null` and `status: 'partial'`, and `send` skips those calls.
+| `task` | what the buyer asked for, in their words | Jev reads it |
+| `criteria` | what "done" means, one per line | Jev reads them numbered |
+| `source` | what the delivery must be faithful to (an invoice, a page, a dataset) | Jev compares against it |
+| `delivered` | what the agent handed in | code first, then Jev |
+| `checks` | `includes` · `sources` · `json` · `deadline` | code; a failed check rejects before Jev is asked |
 
-Here is one real 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).
-  The answers digest is `0x6c7e6d2977689f1c9639a377b165f998d1160cc30eca8ff4f1fedc793db2f52d`.
-- Decision anchored in devnet tx
-  [`0x687ba9d7…4ee4`](https://www.taifoon.io/scan/36927/tx/0x687ba9d73d5789a2df9d9d09e94b6ed005447d7f5ece97f9226ea0d51f514ee4).
-  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:
+Four illustrative jobs, written by hand, are in [`examples/jobs/`](examples/jobs): a research report that meets the brief, the same report
+without its sources (code rejects it), an invoice extraction checked against its source, and a trading signal whose
+claims the evidence cannot support. Grade one with your key:
 
 ```
-{"ok":true,"checks":{"answersOnChain":true,"decisionOnChain":true},
- "answer":{"tx":"0x9a38cf5541bb82a8a6e2e5cf1a96ed25fdc46921c351506da83023f5dec1a61b","trusted":true},
- "decision":{"tx":"0x687ba9d73d5789a2df9d9d09e94b6ed005447d7f5ece97f9226ea0d51f514ee4","confidenceBps":2700}}
+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             # a live Base job from the coordination layer's queue (needs TYPESAFE_KEY)
 ```
 
-The tests re-derive these rows offline, byte for byte:
-
-- **Execution 86:** the answers digest, the `JevAnswerLog.record` calldata (equal to the mined input) and the decision
-  digest.
-- **Execution 88:** run through `grade()` itself, it lands on the anchored decision digest and composes needs_review.
+## A real 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
+reached the chain; the report itself was never shown. Code confirmed the job was funded and delivered, then Jev
+(`jev-1.13.0`) answered on 27 September 2026:
+
+| Question | Jev's answer |
+|---|---|
+| spec_met: does the delivery meet the task? | **no** 0.97 · yes 0.03 |
+| unsupported_claim | no 0.94 · yes 0.06 |
+| ending | **needs_review** 0.93 · complete 0.07 |
+| cheat_shaped | no 0.56 · yes 0.44 |
+
+Code composed **reject** (spec_met ≤ 0.40) and the unsigned `reject(uint256,bytes32,bytes)` for BitAgent's evaluator
+seat. The decision is anchored on the Taifoon devnet in
+[`0xffc608f8…c622`](https://www.taifoon.io/scan/36927/tx/0xffc608f8c8b39ff6992e8ec8d589b8784a3cf4199359c408f8eed1d4b581c622).
+`npx @taifoon/jev run --demo` replays it from [`examples/jobs/base-bitagent-7287.recorded.json`](examples/jobs/base-bitagent-7287.recorded.json)
+with no key and no network, and arrives at the same decision digest.
+
+## What you must know
+
+- **Code decides the facts first.** A failed check ends the job as reject, and Jev is never asked.
+- **Jev answers four atomic questions** from RUBRIC_v1: spec_met, unsupported_claim, ending and cheat_shaped. It
+  never gets a holistic "is the job good?".
+- **Code composes the verdict** under THRESHOLDS_v1: complete, reject or needs_review. needs_review ends nothing and
+  leaves room for an appeal. Above 50 USDC a complete is held for review.
+- **Nothing is signed.** `record()` and `evaluatorCall()` return unsigned calls. Whoever holds the seat signs.
+- **Your key.** Jev is called with your own TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai),
+  directly at TypeSafe. The key is not stored and never appears in a receipt.
+- **What the result is.** *Graded against a published rubric by a pinned decision model, with an appeal.* It is not
+  "independently verified". An on-chain record is an attestation by whoever sent it, not a proof the answer is right.
 
-## The records
-
-- **Receipt.** `receiptHash = sha256(JSON.stringify(body))`. The body holds the rubric and its hash, the thresholds, the
-  subject, `stateHash`, the facts, the model, every answer with its distribution, what was not asked, the verdict,
-  `auto`, `forced`, the reasons and the scores.
-- **decision.v2.** `digest = sha256(canonical { v, kind, subject{chainId, at, ref}, model, answers[id, question,
-  options, value, probabilities, confidence], input_digest })`, with keys sorted.
-  `subjectId = keccak256(abi.encode("taifoon.decision.subject.v1", chainId, at, ref))`.
-- **jev.answer.v1.** `digest = sha256(canonical record)`, covering questions, answers with distributions, model,
-  upstream model, latency, credential path (`trial` or `caller-credential`), caller and time.
-
-## In n8n
-
-The TypeSafe node (`@taifoon/n8n-nodes-typesafe` 1.5.0) carries this package's network-free core under **Jev Options**:
-
-- **Ask RUBRIC_v1** routes Pass = complete, Fail = reject and Review = needs_review.
-- **Facts (JSON)** takes checks you already made. A false check rejects without asking Jev.
-- **Record On** takes `none`, `devnet`, `base` or `both`, and **Evaluator Call** takes a protocol and a job id.
-
-The node outputs the receipt and the unsigned calls, and it signs nothing. With the options unset it behaves exactly as
-1.4.0.
-
-## Workflows
+## The five calls
 
-`workflows/0.1.0/` holds the four n8n workflows that run Jev on n8n.taifoon.dev. The same files are attached to the
-GitHub release as `jev-workflows-0.1.0.zip`:
+| Call | What it does |
+|---|---|
+| `prepareJob({ id, task, criteria, delivered, source?, checks? })` | Turns a job as the buyer laid it out into the evidence Jev reads and the code checks |
+| `grade({ subject, evidence, facts?, rubric?, key \| answers })` | Checks the facts, asks Jev the rubric, composes the verdict, returns the receipt |
+| `facts({ delivered, checks, priceUsdc? })` | Runs the checks your protocol supplies |
+| `record(receipt, { network, send? })` | Returns the unsigned `JevAnswerLog.record` and `JevDecisionLog.record` calls |
+| `evaluatorCall(protocol, jobId, verdict, digest)` | Returns the one unsigned call that ends the job; `null` for needs_review |
+| `verify(receiptOrDigest)` | Recomputes every digest and finds the records on chain |
 
-- **`hire-judge-settle.json`** runs hire → prepare (facts) → TypeSafe (the four RUBRIC_v1 questions) → answers
-  (verdict, recorded and anchored) → settle on devnet. Executions 86 and 88 of this workflow are the golden runs above.
-- **`jev-grader.json`** grades Base jobs nobody ruled on, then stamps each verdict on the devnet GradeStampRegistry.
-- **`batch-judge.json`** runs prepare → Jev → answers for each subject, then `POST /v1/judge/batch`.
-- **`stamp-grade.json`** takes a recorded decision, turns it into the canonical verdict and stamps it.
+Evaluator seats: `assurance-hook`, `judge-adapter`, `virtuals-erc8183`, `virtuals-memo-acp` and `bitagent-erc8183`.
+Each is tested against calldata a mined transaction carried.
 
-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.1.0/schemas/`. `manifest.json` pins every file by sha256.
-`workflows/0.1.0/README.md` explains each workflow step by step and lists the nodes and credentials it needs:
+## Documentation
 
-- `@taifoon/n8n-nodes-typesafe`, tested with 1.3.0, is on npm.
-- `n8n-nodes-taifoon`, tested with 0.4.2, and `n8n-nodes-taifoon-devnet-signer`, tested with 0.2.0, are custom
-  extensions and are not on npm.
+- [How grading works: Jev, the pipeline, THRESHOLDS_v1, `npx @taifoon/jev run`](docs/PIPELINE.md)
+- [API: the five 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)
+- [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)
 
 ```
-npx @taifoon/jev workflows list
-npx @taifoon/jev workflows export ./jev-workflows      # workflows + schemas + manifest + README
-npx @taifoon/jev verify 0x6c7e6d2977689f1c9639a377b165f998d1160cc30eca8ff4f1fedc793db2f52d
+npx @taifoon/jev verify <digest> --network base
+npx @taifoon/jev workflows export ./jev-workflows
 ```
 
-## Develop
+Pricing the next job from a seller's record is a separate package:
+[`@taifoon/jev-wilson`](https://github.com/taifoon-io/jev-wilson).
 
-```
-npm ci && npm run check      # typecheck, tests (golden runs, recorded calldata, hashes vs viem), build
-node scripts/vendor-n8n.mjs  # refresh the n8n node's copy of the core; test/vendor.test.ts fails when it drifts
-npm run bundle && npm run zip   # rebuild workflows/<version>/ from the umbrella's workflows/ and zip it for the release
-```
+## Licence
+
+Independent project. Jev and TypeSafe are products of TypeSafe AI, Inc., which does not endorse this package.
+
+Built by Taifoon. MIT. The package has no runtime dependencies and contains no key. It calls Jev only with your own TypeSafe key.

package/bin/jev.mjs

@@ -2,7 +2,8 @@
 // jev — the @taifoon/jev command line.
 //   jev workflows list [--version X]          the bundled n8n workflows (and which nodes and credentials each needs)
 //   jev workflows export <dir> [--version X]  write them, their schemas, manifest and README into <dir>
-//   jev verify <answers-digest>               find the digest's JevAnswered / Decided rows on devnet 36927
+//   jev run [--job 8453:81100] [--evidence pack.json] [--network …] [--yes] [--json]   one job through the pipeline, step by step
+//   jev verify <answers-digest> [--network devnet|base|any]  find the digest's JevAnswered / Decided rows (default any: devnet, then Base 8453)
 import { cpSync, existsSync, readdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -12,6 +13,7 @@ const PKG = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
 const args = process.argv.slice(2);
 const flag = (n) => { const i = args.indexOf(n); return i >= 0 ? args.splice(i, 2)[1] : undefined; };
 const version = flag('--version') ?? PKG.version;
+const network = flag('--network') ?? 'any';
 const bundle = join(ROOT, 'workflows', version);
 const die = (m) => { console.error(m); process.exit(1); };
 const [cmd, sub, target] = args;
@@ -27,11 +29,15 @@ if (cmd === 'workflows') {
     cpSync(bundle, out, { recursive: true });
     console.log(`${m.bundle} → ${out}: ${m.workflows.length} workflows, ${m.schemas.length} schemas, manifest.json, README.md`);
   } else die('usage: jev workflows list|export <dir> [--version X]');
+} else if (cmd === 'run') {
+  await import('./run.mjs').then((m) => m.run(process.argv.slice(3)));
 } else if (cmd === 'verify' && sub) {
   const { verify } = await import('../dist/index.js');
-  const v = await verify(sub);
+  if (!['devnet', 'base', 'any'].includes(network)) die('--network is devnet, base or any');
+  let v = await verify(sub, { network: network === 'base' ? 'base' : 'devnet' });
+  if (network === 'any' && !v.checks.answersOnChain) { const b = await verify(sub, { network: 'base' }); if (b.checks.answersOnChain || !v.ok) v = b; }
   console.log(JSON.stringify(v, null, 1));
   process.exit(v.ok ? 0 : 2);
 } else {
-  console.log(`jev ${PKG.version}\n  jev workflows list [--version X]\n  jev workflows export <dir> [--version X]\n  jev verify <answers-digest>`);
+  console.log(`jev ${PKG.version}\n  jev workflows list [--version X]\n  jev workflows export <dir> [--version X]\n  jev run [--job <chain>:<id>] [--evidence pack.json] [--network none|devnet|base|both] [--yes] [--json]\n  jev verify <answers-digest> [--network devnet|base|any]`);
 }

package/bin/run.mjs

@@ -0,0 +1,86 @@
+// jev run — one job through the pipeline, one step at a time.
+//   jev run                              the first ready job on the coordination layer's queue (needs TYPESAFE_KEY)
+//   jev run --job 8453:81100             a job you name (chain:id; ids like bitagent:8453:7287 work too)
+//   jev run --evidence pack.json         your own pack, no layer at all: { subject, state, delivered?, checks?, priceUsdc? }
+//   jev run --job-file job.json          one agent job: { id, task, criteria[], delivered, source?, checks[] } (see examples/jobs/)
+//   jev run --demo                       offline, no key: replays a REAL graded job (BitAgent 7287 on Base) with Jev's
+//                                        recorded answers, and checks the result against the decision on chain
+//   jev run --answers answers.json       answers you already have (the n8n TypeSafe node's output): Jev is not asked
+//   --record none|devnet|base|both       opt-in: where the grade is recorded (default none: the receipt and digests only);
+//                                        --network is the same flag
+//   --layer <url> | --no-layer           the coordination layer (default https://coord.taifoon.dev)
+//   --yes                                run every step without asking;  --json  print the whole trace as JSON at the end
+// Keys come from the environment only: TYPESAFE_KEY (your own TypeSafe key, console.typesafe.ai) and
+// TAIFOON_RELAYER_KEY (records the answers on the layer). Neither is printed or written anywhere.
+// Output is @taifoon/term (vendored as ./term.mjs), the same rhythm as `taifoon up` and the STUDIO run log.
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { createTerm } from './term.mjs';
+
+const short = (s, n = 18) => (typeof s === 'string' && s.length > n ? `${s.slice(0, n - 8)}…${s.slice(-6)}` : String(s));
+
+/** One line per step: what it established. The full output is in the --json trace. */
+function factOf(r) {
+  const o = r.out ?? {};
+  switch (r.id) {
+    case 'pick': return o.row ? `job ${o.row.jobId} · ${o.row.why} · evidence ${o.row.evidence_ready}` : `job ${o.jobId} on ${o.chainId}`;
+    case 'evidence': return `${o.facts} labelled facts · ${o.gaps?.length ?? 0} gaps · ${o.state_chars} characters for Jev to read`;
+    case 'facts': return `delivered ${o.delivered ? 'yes' : 'no'} · checks ${o.checksOk === false ? 'failed' : o.checksOk ? 'ok' : 'none'}${o.priceUsdc != null ? ` · ${o.priceUsdc} USDC` : ''}`;
+    case 'grade': return `${o.verdict} · ${o.reasons?.[0] ?? ''}${o.model ? ` · ${o.model}` : ''}`;
+    case 'record': return `${o.status === 'none' ? 'not recorded (opt in with --record)' : `${o.status} · ${(o.calls ?? []).join(', ')}`}${o.recording?.held ? ` · layer held it: ${o.recording.held}` : ''}${typeof o.layer === 'object' && o.layer ? ` · layer ${short(o.layer.digest)}` : ''}`;
+    case 'evaluator': return `${o.fn} on ${o.protocol} · signed by ${o.signer}`;
+    case 'premium': return `${o.guaranteed ? 'guaranteed' : 'not guaranteed'} · premium ${o.premium_label ?? o.premium_ratio}`;
+    case 'verify': return o.ok ? `the receipt re-derives · ${Object.keys(o.checks ?? {}).length} checks` : `problems: ${(o.problems ?? []).join('; ')}`;
+    default: return 'done';
+  }
+}
+
+export async function run(argv) {
+  const a = [...argv];
+  const has = (n) => { const i = a.indexOf(n); if (i < 0) return false; a.splice(i, 1); return true; };
+  const val = (n) => { const i = a.indexOf(n); return i >= 0 ? a.splice(i, 2)[1] : undefined; };
+  const yes = has('--yes') || !process.stdin.isTTY; const json = has('--json'); const noLayer = has('--no-layer') || argv.includes('--demo') || argv.includes('--job-file');
+  const demo = has('--demo');
+  const job = val('--job'); const evFile = val('--evidence');
+  const jobFile = val('--job-file');
+  const ansFile = val('--answers');
+  const rec = demo ? JSON.parse(readFileSync(new URL('../examples/jobs/base-bitagent-7287.recorded.json', import.meta.url), 'utf8')) : null;
+  const network = val('--record') ?? val('--network') ?? 'none'; const layer = noLayer ? false : val('--layer');
+  const protocol = val('--protocol'); const price = val('--price-usdc');
+  const { pipeline, STEPS, prepareJob } = await import('../dist/index.js');
+
+  const t = createTerm({ quiet: json });
+  const rl = yes ? null : createInterface({ input: process.stdin, output: process.stdout });
+  t.info(`jev run · ${noLayer ? 'independent (no layer)' : `layer ${layer ?? 'https://coord.taifoon.dev'}`} · grade on ${demo ? `Jev's recorded answers for ${rec.job.ref} (${rec.job.task})` : ansFile ? 'supplied answers' : process.env.TYPESAFE_KEY ? 'your TypeSafe key' : 'no key: set TYPESAFE_KEY, or try --demo'} · record → ${network === 'none' ? 'none (opt in with --record devnet|base|both)' : network}${process.env.TAIFOON_RELAYER_KEY ? ' + the layer' : ''}`);
+
+  const trace = await pipeline({
+    layer, job, network, protocol, priceUsdc: price ? Number(price) : undefined,
+    evidence: rec ? { subject: rec.subject.ref, chainId: rec.subject.chainId, label: rec.subject.label, state: rec.evidence, delivered: rec.facts.delivered, checks: rec.facts.checks } : jobFile ? prepareJob(JSON.parse(readFileSync(jobFile, 'utf8'))).pack : evFile ? JSON.parse(readFileSync(evFile, 'utf8')) : undefined,
+    answers: rec ? rec.answers : ansFile ? JSON.parse(readFileSync(ansFile, 'utf8')) : undefined, ...(rec ? { model: rec.model } : {}),
+    key: process.env.TYPESAFE_KEY || null, relayerKey: process.env.TAIFOON_RELAYER_KEY || null,
+    before: async (s) => {
+      t.step(STEPS.indexOf(s) + 1, STEPS.length, s.title);
+      if (s.route) t.note(s.route);
+      if (!rl) return true;
+      const r = (await rl.question(s.required ? '  enter = run · q = quit › ' : '  enter = run · s = skip · q = quit › ')).trim().toLowerCase();
+      if (r === 'q') { rl.close(); process.exit(0); }
+      return s.required || r !== 's';
+    },
+    after: (r) => {
+      if (r.skipped) t.skip(r.skipped);
+      else if (!r.ok) t.fail(r.error ?? 'failed', { ms: r.ms });
+      else t.ok(factOf(r), { ms: r.ms });
+    },
+  });
+  rl?.close();
+  if (json) t.json(trace);
+  else if (trace.receipt) {
+    t.line('');
+    t.say(`verdict ${trace.receipt.verdict} · receipt ${trace.receipt.receiptHash}`);
+    if (rec) {
+      const same = trace.receipt.decision?.digest === rec.recorded.digest;
+      (same ? t.ok : t.fail)(`${same ? 'same decision digest as' : 'differs from'} the one recorded on chain: ${rec.recorded.decision}, anchored in ${rec.recorded.anchor.tx}`);
+    } else if (trace.recorded && trace.recorded.status !== 'none') t.cmd(`npx @taifoon/jev verify ${trace.recorded.digests.answers}`);
+  }
+  process.exit(trace.steps.some((s) => !s.ok) ? 1 : 0);
+}

package/bin/term.mjs

@@ -0,0 +1,154 @@
+// @taifoon/term — the step renderer shared by `taifoon up` and `jev run`.
+//
+// One file, no imports, no dependencies, and nothing happens at import time: every env read, TTY check and write
+// is inside a function, so this file can be vendored as-is (a consumer copies it byte for byte and pins its sha256).
+//
+// The rhythm is the STUDIO terminal on taifoon.io:
+//   → [1/5] readiness                                   step()    bold
+//   ● GET coord.taifoon.dev/v1/agents/8453/95902/…      call()    before the read
+//     ⎿ 200 · 612 ms                                    called()  after it
+//   ✓ hireable · 8 ok · 2 missing · 640 ms              ok() / warn() / fail() / skip()   ✓ ! ✗ ·
+//     the guide's line                                  say() / note()
+//   → calibrated: POST /v1/pools/quote                  next()    and its command, indented, via cmd()
+// Colour is on only for a TTY stream without NO_COLOR (FORCE_COLOR overrides both ways) and TERM != dumb.
+
+export const GLYPH = Object.freeze({ ok: '✓', warn: '!', fail: '✗', skip: '·' });
+export const SPIN = Object.freeze(['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']);
+export const MARKS = Object.freeze(['ok', 'warn', 'fail', 'skip']);
+
+const wrap = (open, close) => (s) => `\u001b[${open}m${s}\u001b[${close}m`;
+const plain = (s) => String(s);
+
+/** Whether to colour `stream`, from `env` (both read now, never at import). */
+export function colorOn(stream, env) {
+  const e = env || {};
+  if (e.FORCE_COLOR !== undefined && e.FORCE_COLOR !== '') return e.FORCE_COLOR !== '0' && e.FORCE_COLOR !== 'false';
+  if (e.NO_COLOR !== undefined && e.NO_COLOR !== '') return false;
+  if (e.TERM === 'dumb') return false;
+  return !!(stream && stream.isTTY === true);
+}
+
+/** The colour helpers (identity functions when `on` is false). */
+export function palette(on) {
+  if (!on) return { on: false, bold: plain, dim: plain, green: plain, yellow: plain, red: plain, cyan: plain };
+  return { on: true, bold: wrap(1, 22), dim: wrap(2, 22), green: wrap(32, 39), yellow: wrap(33, 39), red: wrap(31, 39), cyan: wrap(36, 39) };
+}
+
+/** Remove ANSI colour codes (for tests and for widths). */
+export const stripAnsi = (s) => String(s).replace(/\u001b\[[0-9;]*m/g, '');
+
+// ── elapsed time ─────────────────────────────────────────────────────────────────────────────────────────────
+/** Milliseconds since `t0` (`now` defaults to Date.now()). */
+export const elapsed = (t0, now) => Math.max(0, Math.round((now === undefined ? Date.now() : now) - t0));
+/** `640 ms` — the unit every line uses, as the STUDIO terminal prints it. */
+export const fmtMs = (ms) => (typeof ms === 'number' && Number.isFinite(ms) ? `${Math.round(ms)} ms` : '— ms');
+/** `42 s ago`, `3 min ago`, `2 h ago`, `1 d ago` — the age of a cached step. */
+export function fmtAge(ms) {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 5) return 'just now';
+  if (s < 60) return `${s} s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)} min ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)} h ago`;
+  return `${Math.floor(s / 86400)} d ago`;
+}
+
+// ── lines (pure: they return a string without a newline) ─────────────────────────────────────────────────────
+const P0 = palette(false);
+const tone = (mark, p) => (mark === 'ok' ? p.green : mark === 'warn' ? p.yellow : mark === 'fail' ? p.red : p.dim);
+
+export const stepLine = (n, of, title, p = P0) => p.bold(`→ [${n}/${of}] ${title}`);
+export const headLine = (text, p = P0) => p.bold(`→ ${text}`);
+export function callLine(method, url, body, p = P0) {
+  return `● ${p.bold(method)} ${url}${body !== undefined ? ' ' + p.dim(JSON.stringify(body)) : ''}`;
+}
+export function calledLine(status, ms, error, p = P0) {
+  const t = `⎿ ${status === null || status === undefined ? 'no answer' : status} · ${fmtMs(ms)}${error ? ` · ${error}` : ''}`;
+  return '  ' + (error ? p.red(t) : p.dim(t));
+}
+/** `✓ text · 640 ms · extra` — `mark` is ok | warn | fail | skip. */
+export function markLine(mark, text, o = {}, p = P0) {
+  const g = GLYPH[mark] || GLYPH.skip;
+  const tail = [o.ms !== undefined ? fmtMs(o.ms) : null, o.extra || null].filter(Boolean).join(' · ');
+  const body = mark === 'fail' ? p.red(text) : mark === 'skip' ? p.dim(text) : text;
+  return `${p.bold(tone(mark, p)(g))} ${body}${tail ? p.dim(` · ${tail}`) : ''}`;
+}
+export const noteLine = (text, p = P0) => `  ${p.dim(text)}`;
+export const sayLine = (text) => `  ${text}`;
+export const nextLine = (label, p = P0) => `${p.cyan('→')} ${label}`;
+export const cmdLine = (cmd, p = P0) => String(cmd).split('\n').map((l) => `    ${p.dim('$')} ${l}`).join('\n');
+
+// ── the writer ───────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * A terminal bound to a stream. Options (all optional; defaults are read when this is called):
+ *   out    a writable with .write (default process.stdout)
+ *   env    the environment for NO_COLOR / FORCE_COLOR / TERM (default process.env)
+ *   color  force colour on or off
+ *   quiet  write nothing (for --json runs); the line functions still return their text
+ */
+export function createTerm(o = {}) {
+  const proc = typeof process !== 'undefined' ? process : null;
+  const out = o.out || (proc && proc.stdout) || { write() {} };
+  const env = o.env || (proc && proc.env) || {};
+  const tty = !!out.isTTY;
+  const p = palette(o.color === undefined ? colorOn(out, env) : !!o.color);
+  const quiet = !!o.quiet;
+  let live = null; // the running spinner, cleared before any other line
+  const emit = (s) => {
+    if (quiet) return s;
+    if (live) live.clear();
+    out.write(s + '\n');
+    if (live) live.draw();
+    return s;
+  };
+  const t = {
+    color: p.on, tty, palette: p,
+    line: (s = '') => emit(s),
+    step: (n, of, title) => emit(stepLine(n, of, title, p)),
+    head: (text) => emit(headLine(text, p)),
+    call: (method, url, body) => emit(callLine(method, url, body, p)),
+    called: (status, ms, error) => emit(calledLine(status, ms, error, p)),
+    mark: (mark, text, x) => emit(markLine(mark, text, x, p)),
+    ok: (text, x) => emit(markLine('ok', text, x, p)),
+    warn: (text, x) => emit(markLine('warn', text, x, p)),
+    fail: (text, x) => emit(markLine('fail', text, x, p)),
+    skip: (text, x) => emit(markLine('skip', text, x, p)),
+    note: (text) => emit(noteLine(text, p)),
+    say: (text) => emit(sayLine(text)),
+    next: (label) => emit(nextLine(label, p)),
+    cmd: (cmd) => emit(cmdLine(cmd, p)),
+    info: (text) => emit(p.dim(text)),
+    /** one JSON value per line, written even when quiet (that is what --json prints) */
+    json: (v) => { out.write(JSON.stringify(v) + '\n'); return v; },
+    /** A spinner on its own line; animates only on a colour TTY. stop(line?) clears it and prints `line` if given. */
+    spinner(text) {
+      if (quiet || !tty || !p.on) return { update() {}, stop: (line) => (line ? emit(line) : undefined) };
+      let f = 0; let label = text;
+      const s = {
+        draw: () => out.write(`${p.dim(SPIN[f % SPIN.length])} ${label}`),
+        clear: () => out.write('\r\u001b[2K'),
+      };
+      live = s; s.draw();
+      const timer = setInterval(() => { f++; s.clear(); s.draw(); }, 90);
+      if (timer && typeof timer.unref === 'function') timer.unref();
+      return {
+        update(next) { label = next; },
+        stop(line) { clearInterval(timer); s.clear(); if (live === s) live = null; return line ? emit(line) : undefined; },
+      };
+    },
+  };
+  return t;
+}
+
+// ── the default terminal: process.stdout, created on first use (never at import) ─────────────────────────────
+let dflt = null;
+const d = () => (dflt || (dflt = createTerm()));
+export const step = (n, of, title) => d().step(n, of, title);
+export const call = (method, url, body) => d().call(method, url, body);
+export const called = (status, ms, error) => d().called(status, ms, error);
+export const ok = (text, x) => d().ok(text, x);
+export const warn = (text, x) => d().warn(text, x);
+export const fail = (text, x) => d().fail(text, x);
+export const skip = (text, x) => d().skip(text, x);
+export const note = (text) => d().note(text);
+export const next = (label) => d().next(label);
+export const spinner = (text) => d().spinner(text);