@taifoon/jev 0.1.0 → 0.2.1

package/dist/pipeline.js

@@ -0,0 +1,193 @@
+// pipeline(): one job through the coordination layer's steps, each step a function with a typed output.
+//   pick → evidence → facts → grade → record → evaluator → premium → verify
+// Every step works without the layer too: pass `evidence` (your own pack) and the layer is never read; `grade` then
+// runs on your own TypeSafe key (or answers you already have), `record` returns unsigned calls, `premium` is skipped. With the layer
+// (https://coord.taifoon.dev by default) the job comes from /v1/judge/queue, the pack from /v1/judge/evidence, the
+// seller's terms from /v1/pools/quote, and — only with a relayer key — the answers are recorded on the layer through
+// /v1/judge/answers/record. Nothing here signs a transaction.
+import { facts as runFacts } from './facts.js';
+import { grade } from './grade.js';
+import { record } from './record.js';
+import { verify } from './verify.js';
+import { evaluatorCall } from './evaluator/index.js';
+export const LAYER = 'https://coord.taifoon.dev';
+/** The steps in order, each with the layer route it reads (null: runs locally only). */
+/** `required`: the later steps need its output, so saying no at the gate stops the run instead of skipping it. */
+export const STEPS = Object.freeze([
+    { id: 'pick', title: 'Pick a job a grader is needed for', route: 'GET /v1/judge/queue', required: true },
+    { id: 'evidence', title: 'Read the evidence pack', route: 'GET /v1/judge/evidence/{chain}/{jobId}', required: true },
+    { id: 'facts', title: 'Code establishes the facts (a failed check ends the job)', route: null, required: true },
+    { id: 'grade', title: 'Jev answers RUBRIC_v1, code composes the verdict', route: null, required: true },
+    { id: 'record', title: 'Record the answers and the decision', route: 'POST /v1/judge/answers/record' },
+    { id: 'evaluator', title: 'The call that ends the job on its protocol', route: null },
+    { id: 'premium', title: 'Price the next premium from the seller record (Wilson)', route: 'POST /v1/pools/quote' },
+    { id: 'verify', title: 'Re-derive the receipt (and find it on chain)', route: null },
+]);
+const num = (s) => { const m = /([0-9]+(?:\.[0-9]+)?)/.exec(s ?? ''); return m ? Number(m[1]) : null; };
+const fact = (ev, label) => ev.facts.find(([k]) => label.test(k))?.[1];
+/** A job reference: `8453:81100`, `8453:bitagent:8453:7287`, or a bare id (chain 8453). */
+export function parseJob(j) {
+    if (typeof j === 'object')
+        return j;
+    const m = /^(\d+):(.+)$/.exec(j.trim());
+    return m ? { chainId: Number(m[1]), jobId: m[2] } : { chainId: 8453, jobId: j.trim() };
+}
+/** The layer's queue rows a grader can actually read: evidence must resolve (decimal id or label:chain:id). */
+export const readable = (r) => /\/v1\/judge\/evidence\/\d+\/(\d+|[a-z0-9-]+:\d+:\d+)$/.test(r.evidence);
+/**
+ * The deterministic facts an ERC-8183 evidence pack supports on its own:
+ * delivered = the pack names a delivery; submitted_before_deadline when both times are on chain; priceUsdc from "price".
+ * A protocol that can re-derive the delivery (a proof, a hash, a file) adds its own checks on top.
+ */
+export function factsFromEvidence(ev, extra = {}) {
+    const delivered = fact(ev, /what was delivered/i);
+    const submitted = fact(ev, /^submitted$/i);
+    const deadline = fact(ev, /^deadline$/i);
+    const price = fact(ev, /^price$/i);
+    const checks = { ...extra };
+    if (submitted && deadline)
+        checks.submitted_before_deadline = !/after the deadline/i.test(submitted);
+    return { delivered: Boolean(delivered && !/^nothing|not delivered|no submission/i.test(delivered)), checks, priceUsdc: price && /usdc/i.test(price) ? num(price) : null };
+}
+/** The evaluator seat for a job id, when the id says which protocol it is on. */
+export function protocolFor(jobId) {
+    const b = /^bitagent:\d+:(\d+)$/.exec(jobId);
+    if (b)
+        return { protocol: 'bitagent-erc8183', id: b[1] };
+    if (/^\d+$/.test(jobId))
+        return { protocol: 'virtuals-erc8183', id: jobId };
+    if (/^0x[0-9a-fA-F]{64}$/.test(jobId))
+        return { protocol: 'assurance-hook', id: jobId };
+    return null;
+}
+async function getJson(f, url, init) {
+    const r = await f(url, { ...init, signal: AbortSignal.timeout(30_000) });
+    const j = (await r.json().catch(() => ({})));
+    if (!r.ok || j.ok === false)
+        throw new Error(`${init?.method ?? 'GET'} ${url.replace(/^https?:\/\/[^/]+/, '')}: ${r.status} ${j.error ?? ''}`.trim());
+    return j;
+}
+export async function pipeline(o = {}) {
+    const f = o.fetch ?? fetch;
+    const layer = o.layer === false ? null : (o.layer ?? LAYER).replace(/\/$/, '');
+    if (!layer && !o.evidence)
+        throw new Error('independent mode (layer: false) needs `evidence`');
+    const t = { job: null, steps: [], receipt: null, recorded: null, layerRecord: null, evaluator: null, quote: null, verification: null };
+    let ev = null;
+    let budget = null;
+    let factsIn = null;
+    const step = async (id, run) => {
+        const s = STEPS.find((x) => x.id === id);
+        const t0 = Date.now();
+        let res;
+        if (o.before && !(await o.before(s, t)))
+            res = s.required ? { id, ok: true, stopped: true, skipped: 'stopped at the gate: the later steps need this one', ms: 0 } : { id, ok: true, skipped: 'skipped at the gate', ms: 0 };
+        else {
+            try {
+                const out = await run();
+                res = out && typeof out === 'object' && 'skip' in out ? { id, ok: true, skipped: out.skip, ms: Date.now() - t0 } : { id, ok: true, ms: Date.now() - t0, out };
+            }
+            catch (e) {
+                res = { id, ok: false, ms: Date.now() - t0, error: e.message };
+            }
+        }
+        t.steps.push(res);
+        await o.after?.(res, t);
+    };
+    const failed = () => t.steps.some((s) => !s.ok || s.stopped);
+    await step('pick', async () => {
+        if (o.evidence) {
+            t.job = { chainId: o.evidence.chainId ?? 0, jobId: o.evidence.subject, seller: o.evidence.seller ?? null };
+            return { skip: 'your own evidence pack' };
+        }
+        if (o.job) {
+            t.job = { ...parseJob(o.job), seller: null };
+            return t.job;
+        }
+        const q = await getJson(f, `${layer}/v1/judge/queue?limit=50`);
+        const row = q.rows.find(readable);
+        if (!row)
+            throw new Error('no queue row with a readable evidence pack');
+        t.job = { ...parseJob(`${/\/evidence\/(\d+)\//.exec(row.evidence)[1]}:${row.jobId}`), seller: row.seller };
+        budget = row.budget;
+        return { row, skipped_unreadable: q.rows.indexOf(row) };
+    });
+    if (failed())
+        return t;
+    await step('evidence', async () => {
+        if (o.evidence) {
+            ev = { chainId: 0, jobId: o.evidence.subject, state: o.evidence.state, facts: [] };
+            return { skip: 'your own evidence pack' };
+        }
+        ev = await getJson(f, `${layer}/v1/judge/evidence/${t.job.chainId}/${encodeURIComponent(t.job.jobId)}`);
+        t.job.seller ??= fact(ev, /^seller$/i) ?? null;
+        return { facts: ev.facts.length, gaps: ev.gaps ?? [], state_chars: ev.state.length };
+    });
+    if (failed() || !ev)
+        return t;
+    const pack = ev;
+    await step('facts', async () => {
+        factsIn = o.evidence ? { delivered: o.evidence.delivered ?? true, checks: o.evidence.checks ?? {}, priceUsdc: o.evidence.priceUsdc ?? null } : factsFromEvidence(pack);
+        budget ??= factsIn.priceUsdc ?? null;
+        return runFacts(factsIn);
+    });
+    if (failed())
+        return t;
+    await step('grade', async () => {
+        const g = { subject: o.subject ? o.subject(t.job) : { chainId: t.job.chainId, ref: t.job.jobId, ...(o.evidence?.label ? { label: o.evidence.label } : {}) }, evidence: pack.state, facts: runFacts(factsIn), fetch: f, ...(o.caller ? { caller: o.caller } : {}) };
+        if (o.answers) {
+            g.answers = o.answers;
+            if (o.model)
+                g.model = o.model;
+        }
+        else if (o.key)
+            g.key = o.key;
+        else
+            throw new Error('Jev needs your TypeSafe key: set TYPESAFE_KEY (console.typesafe.ai), or pass answers you already have');
+        t.receipt = await grade(g);
+        return { verdict: t.receipt.verdict, reasons: t.receipt.reasons, model: t.receipt.model, receiptHash: t.receipt.receiptHash };
+    });
+    if (failed() || !t.receipt)
+        return t;
+    const receipt = t.receipt;
+    await step('record', async () => {
+        if (!receipt.decision)
+            return { skip: `nothing to record: ${receipt.reasons[0] ?? receipt.verdict} (the facts decided; Jev was not asked)` };
+        t.recorded = await record(receipt, { network: o.network ?? 'none' });
+        if (layer && o.relayerKey && receipt.answersRecord)
+            t.layerRecord = await getJson(f, `${layer}/v1/judge/answers/record`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': o.relayerKey }, body: JSON.stringify({ ...receipt.answersRecord, record: o.network ?? 'none' }) });
+        const rec = t.layerRecord?.recording;
+        return { status: t.recorded.status, recording: rec ? { used: rec.used ?? null, held: rec.held?.message ?? null } : null, calls: t.recorded.calls.map((c) => `${c.fn}@${c.chainId}${c.to ? '' : ' (no address)'}`), digests: t.recorded.digests, layer: t.layerRecord ?? (layer ? 'not written: pass a relayer key to record on the layer' : 'independent mode') };
+    });
+    await step('evaluator', async () => {
+        if (receipt.verdict === 'needs_review')
+            return { skip: 'needs_review ends nothing: the job goes to appeal' };
+        const p = o.protocol ? { protocol: o.protocol, id: t.job.jobId } : protocolFor(t.job.jobId);
+        if (!p)
+            return { skip: 'the job id does not say which protocol it is on (pass protocol)' };
+        try {
+            t.evaluator = evaluatorCall(p.protocol, p.id, receipt, receipt);
+        }
+        catch (e) {
+            return { skip: `${p.protocol}: ${e.message}` };
+        }
+        return t.evaluator ?? { skip: 'no evaluator call for this verdict' };
+    });
+    await step('premium', async () => {
+        const seller = t.job.seller;
+        if (!layer)
+            return { skip: 'independent mode: price it with @taifoon/jev-wilson (premium({ k, n }, { price }))' };
+        if (!seller)
+            return { skip: 'no seller address in the evidence' };
+        const price = o.priceUsdc ?? budget;
+        if (!price)
+            return { skip: 'no price for the job' };
+        t.quote = await getJson(f, `${layer}/v1/pools/quote`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ seller, price_usdc: price, chainId: 8453 }) });
+        return { guaranteed: t.quote.guaranteed, premium_ratio: t.quote.premium_ratio, premium_label: t.quote.premium_label, record: t.quote.record ?? null };
+    });
+    await step('verify', async () => {
+        t.verification = await verify(receipt, { chain: o.chainVerify ?? t.recorded?.status === 'sent', fetch: f });
+        return { ok: t.verification.ok, checks: t.verification.checks, problems: t.verification.problems };
+    });
+    return t;
+}

package/dist/rubric.js

@@ -1,6 +1,6 @@
 // RUBRIC_v1: the questions Jev is asked, the thresholds, and the composition. Code decides the facts first; Jev answers
 // a few ATOMIC closed questions (never "is the job good?"); code composes the verdict from both under published
-// thresholds. Byte-for-byte the same rules as the Taifoon judge (judge/src/judge-compose.ts; test/parity.test.ts
+// thresholds. Byte-for-byte the same rules as the hosted Taifoon judge (test/parity.test.ts
 // holds them together), so a receipt made here and one made by the hosted judge hash the same.
 import { sha256Hex } from './hash.js';
 const THRESHOLDS_V1 = Object.freeze({ completeSpecMin: 0.85, completeUnsupportedMax: 0.2, rejectSpecMax: 0.4, rejectUnsupportedMin: 0.7, cheatShapedMin: 0.5, autoCompleteCapUsdc: 50 });

package/dist/verify.d.ts

@@ -32,9 +32,15 @@ export type Verification = {
     };
     problems: string[];
 };
+/**
+ * `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
+ * endpoints refuse wide log ranges.
+ */
 export declare function verify(x: Receipt | string, opts?: {
     rpc?: string;
     fetch?: typeof fetch;
     rubric?: Rubric | RubricInput;
     chain?: boolean;
+    network?: 'devnet' | 'base';
 }): Promise<Verification>;

package/dist/verify.js

@@ -9,19 +9,46 @@ const TOPIC_ANSWERED = keccakHex('JevAnswered(address,bytes32,bytes32,bytes32,by
 const TOPIC_DECIDED = keccakHex('Decided(bytes32,bytes32,address,uint256,bytes32,uint16,string,string)');
 const ANSWERED_DATA = ['address', 'bytes32', 'bytes32', 'string', 'string', 'uint256', 'bool'];
 const DECIDED_DATA = ['uint256', 'bytes32', 'uint16', 'string', 'string'];
-async function logs(rpc, f, address, topics, fromBlock) {
-    const r = await f(rpc, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_getLogs', params: [{ address, topics, fromBlock: '0x' + fromBlock.toString(16), toBlock: 'latest' }] }), signal: AbortSignal.timeout(30_000) });
+const hexN = (n) => '0x' + n.toString(16);
+async function rpcCall(rpc, f, method, params) {
+    const r = await f(rpc, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }), signal: AbortSignal.timeout(30_000) });
     const j = (await r.json());
     if (j.error)
-        throw new Error(`eth_getLogs: ${j.error.message}`);
-    return j.result ?? [];
+        throw new Error(`${method}: ${j.error.message}`);
+    return j.result;
+}
+async function logs(rpc, f, address, topics, fromBlock, toBlock) {
+    return (await rpcCall(rpc, f, 'eth_getLogs', [{ address, topics, fromBlock: hexN(fromBlock), toBlock: toBlock == null ? 'latest' : hexN(toBlock) }])) ?? [];
+}
+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) {
+    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) {
+    const head = Number(BigInt(await rpcCall(rpc, f, 'eth_blockNumber', [])));
+    to = Math.min(to, head); // endpoints refuse a range past the head
+    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))));
+    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) }; };
 const decisionEvent = (l) => { const [index, digest, bps, model, uri] = decode(DECIDED_DATA, l.data); return { tx: l.transactionHash, block: parseInt(l.blockNumber, 16), recorder: `0x${String(l.topics[3]).slice(26)}`, index: Number(index), digest: digest, confidenceBps: Number(bps), model: String(model), uri: String(uri) }; };
+/**
+ * `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
+ * endpoints refuse wide log ranges.
+ */
 export async function verify(x, opts = {}) {
+    const network = opts.network ?? 'devnet';
     const f = opts.fetch ?? fetch;
-    const rpc = opts.rpc ?? CONTRACTS.devnet.rpc;
-    const dev = CONTRACTS.devnet;
+    const rpc = opts.rpc ?? CONTRACTS[network].rpc;
+    const dev = network === 'base'
+        ? { chainId: CONTRACTS.base.chainId, answerLog: CONTRACTS.base.answerLog, decisionLog: CONTRACTS.base.decisionLog }
+        : { chainId: CONTRACTS.devnet.chainId, answerLog: CONTRACTS.devnet.answerLog, decisionLog: CONTRACTS.devnet.decisionLog };
     const checks = {};
     const problems = [];
     const onChain = { chainId: dev.chainId, answers: [], decisions: [] };
@@ -58,15 +85,27 @@ export async function verify(x, opts = {}) {
     }
     if (opts.chain !== false && answersDigest) {
         try {
-            onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], dev.answerLog.fromBlock)).map(answerEvent);
+            if (!dev.answerLog || !dev.decisionLog)
+                throw new Error(`this package version carries no ${network} address for the logs`);
+            if (network === 'base') {
+                const at = await recordedAt(rpc, f, dev.answerLog.address, answersDigest);
+                if (at > 0)
+                    onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], at, at)).map(answerEvent);
+            }
+            else
+                onChain.answers = (await logs(rpc, f, dev.answerLog.address, [TOPIC_ANSWERED, null, null, answersDigest], dev.answerLog.fromBlock)).map(answerEvent);
             // a bare digest: the answer row names its subject and decision, so the decision row can be found too
             const first = onChain.answers[0];
             if (!subjectId && first && !/^0x0{64}$/.test(first.decisionDigest)) {
                 subjectId = first.subject;
                 decision = first.decisionDigest;
             }
-            if (subjectId && decision)
-                onChain.decisions = (await logs(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], dev.decisionLog.fromBlock)).map(decisionEvent).filter((d) => d.digest.toLowerCase() === decision.toLowerCase());
+            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 logs(rpc, f, dev.decisionLog.address, [TOPIC_DECIDED, subjectId], dev.decisionLog.fromBlock);
+                onChain.decisions = found.map(decisionEvent).filter((d) => d.digest.toLowerCase() === decision.toLowerCase());
+            }
         }
         catch (e) {
             problems.push(`chain read failed: ${e instanceof Error ? e.message : String(e)}`);

package/docs/API.md

@@ -0,0 +1,20 @@
+# API
+
+## The five calls
+
+| Call | What it does | Network |
+|---|---|---|
+| `grade({ subject, evidence, facts?, rubric?, key \| answers })` | 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.** Calls go to `https://api.typesafe.ai/v1/systemone` with your own TypeSafe key from
+[console.typesafe.ai](https://console.typesafe.ai), and to no one else. 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.

package/docs/DEVELOP.md

@@ -0,0 +1,7 @@
+# Develop
+
+```
+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>/ and zip it for the release
+```

package/docs/EVALUATORS.md

@@ -0,0 +1,20 @@
+# 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.

package/docs/ON_CHAIN.md

@@ -0,0 +1,44 @@
+# On chain
+
+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 |
+|---|---|---|
+| 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` |
+
+On Base (8453), since 0.2.0:
+
+| Contract | Address | Rule |
+|---|---|---|
+| JevAnswerLog | `0x8e9B9cE86a2d55c10318607b0c815B7B8C66254d` | Same bytecode. The only `trusted` recorder is `0xe9F0E71e7Fc66864126C0aE5588a7858b25dE51D` |
+| JevDecisionLog | `0x209490d6A0FFC5368A42b0c2208BDCda853f6a92` | Same bytecode. The recorder is `msg.sender` |
+
+`record(receipt, { network: 'base' })` returns the Base calls with `to` set. `verify(digest, { network: 'base' })` and
+`npx @taifoon/jev verify <digest> --network base` read them (the CLI's default `any` tries the devnet, then Base).
+0.1.0 carried no Base addresses. An earlier Base answer log, `0x5bac70eb78224bbCBa83f5A36DF09D549d3f57fa`, is superseded and holds no records.
+
+Here is one real grade, end to end: n8n execution 86, a proof-verification job graded with RUBRIC_v1.
+
+- 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:
+
+```
+{"ok":true,"checks":{"answersOnChain":true,"decisionOnChain":true},
+ "answer":{"tx":"0x9a38cf5541bb82a8a6e2e5cf1a96ed25fdc46921c351506da83023f5dec1a61b","trusted":true},
+ "decision":{"tx":"0x687ba9d73d5789a2df9d9d09e94b6ed005447d7f5ece97f9226ea0d51f514ee4","confidenceBps":2700}}
+```
+
+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.

package/docs/PIPELINE.md

@@ -0,0 +1,76 @@
+# How grading works
+
+## What Jev is
+
+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 and turned into the one call that ends the job. Recording it on chain is
+  optional: `record()` builds the calls only when you ask.
+
+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.
+
+## Run it: `npx @taifoon/jev run`
+
+One job through the coordination layer's steps, one step at a time. Each step shows the layer route it reads and
+what came back, and asks before it runs (`--yes` runs them all; `--json` prints the whole trace).
+
+```
+npx @taifoon/jev run                               # the first job on /v1/judge/queue whose evidence the layer can read
+npx @taifoon/jev run --job 8453:bitagent:8453:7287 --network both
+npx @taifoon/jev run --no-layer --evidence pack.json    # your own pack, no layer at all: { subject, state, checks? }
+```
+
+| # | Step | Layer route | Without the layer |
+|---|---|---|---|
+| 1 | pick a job a grader is needed for | `GET /v1/judge/queue` | your `--evidence` |
+| 2 | read the evidence pack | `GET /v1/judge/evidence/{chain}/{jobId}` | your `--evidence` |
+| 3 | code establishes the facts | none | the checks in your pack |
+| 4 | Jev answers RUBRIC_v1, code composes the verdict | none | same |
+| 5 | record the answers and the decision | `POST /v1/judge/answers/record` (only with `TAIFOON_RELAYER_KEY`) | unsigned calls |
+| 6 | the evaluator call that ends the job | none | same |
+| 7 | price the next premium from the seller record | `POST /v1/pools/quote` | skipped; use `@taifoon/jev-wilson` |
+| 8 | re-derive the receipt (and find it on chain) | none | same |
+
+Steps 1 to 4 are required: saying no at one stops the run. Keys come from the environment only, `TYPESAFE_KEY` (your own
+TypeSafe key; without it the Jev step stops and says where to get one) and `TAIFOON_RELAYER_KEY`, and are never printed. Nothing is signed. In code it is `pipeline()`,
+with a `before` gate and an `after` hook per step.
+
+Real run (2026-09-27): BitAgent job 7287 on Base asked for "equity_research where ticker is 'AAPL'" and
+got a 32-byte digest. Facts passed (delivered, before the deadline, 1.5 USDC). Jev answered spec_met 0.03, so the
+verdict is **reject**; the receipt re-derives; the seller's quote is 0.0%–39.0% (6 settled, thin record).

package/docs/RECORDS.md

@@ -0,0 +1,10 @@
+# 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 (`caller-credential`; records made before 0.2.0 may say `trial`), caller and time.

package/docs/WORKFLOWS.md

@@ -0,0 +1,38 @@
+# Workflows and n8n
+
+## 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
+
+`workflows/0.2.1/` holds the four n8n workflows that run Jev. The same files are attached to the
+GitHub release as `jev-workflows-0.2.1.zip`:
+
+- **`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.
+
+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.1/schemas/`. `manifest.json` pins every file by sha256.
+`workflows/0.2.1/README.md` explains each workflow step by step and lists the nodes and credentials it needs:
+
+- `@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.
+
+```
+npx @taifoon/jev workflows list
+npx @taifoon/jev workflows export ./jev-workflows      # workflows + schemas + manifest + README
+npx @taifoon/jev verify 0x6c7e6d2977689f1c9639a377b165f998d1160cc30eca8ff4f1fedc793db2f52d
+```

package/examples/grade-job.mjs

@@ -0,0 +1,17 @@
+// Grade one agent job: did the agent do the work as the task laid it out?
+//   TYPESAFE_KEY=… node examples/grade-job.mjs examples/jobs/research-report.json
+//   node examples/grade-job.mjs examples/jobs/research-report-no-sources.json     (code rejects it; Jev is not asked)
+// Your key comes from console.typesafe.ai. It is sent to TypeSafe only, and never stored or recorded.
+import { readFileSync } from 'node:fs';
+import { prepareJob, facts, grade, record } from '@taifoon/jev';
+
+const spec = JSON.parse(readFileSync(process.argv[2] ?? new URL('./jobs/research-report.json', import.meta.url), 'utf8'));
+const job = prepareJob(spec);                         // task + numbered criteria + source + delivery, and the code checks
+
+const f = await facts(job.facts);
+console.log('facts', f.checks, f.checksOk === false ? '→ a check failed: code rejects, Jev is not asked' : '');
+
+const receipt = await grade({ subject: job.subject, evidence: job.evidence, facts: f, key: process.env.TYPESAFE_KEY });
+console.log(receipt.verdict, '·', receipt.reasons.join(' · '));
+if (receipt.answers) for (const [id, a] of Object.entries(receipt.answers)) console.log(' ', id.padEnd(18), a.value, a.probabilities);
+if (receipt.decision) console.log('record:', (await record(receipt)).calls.map((c) => c.fn).join(' + '));

package/examples/jobs/base-bitagent-7287.recorded.json

@@ -0,0 +1,80 @@
+{
+  "_about": "A real job on Base, graded by Jev (jev-1.13.0) through the Taifoon coordination layer on 2026-09-27. Everything here is copied from the recorded decision; test/jobs.test.ts re-derives its digests offline.",
+  "job": {
+    "chainId": 8453,
+    "protocol": "BitAgent ERC-8183",
+    "contract": "0x5009ABB3A309115a4a682C66BAf3BC9E0329BaB7",
+    "jobId": "7287",
+    "ref": "bitagent:8453:7287",
+    "task": "equity_research where ticker is 'AAPL'",
+    "price": "1.5 USDC",
+    "delivered": "a 32-byte digest; the content behind it is not published on chain",
+    "evidence_route": "https://coord.taifoon.dev/v1/judge/evidence/8453/bitagent:8453:7287"
+  },
+  "subject": {
+    "chainId": 8453,
+    "ref": "bitagent:8453:7287",
+    "label": "RUBRIC_v1 · bitagent:8453:7287"
+  },
+  "evidence": "job: ERC-8183 job 7287 of the BitAgent deployment on chain 8453 (contract 0x5009abb3a309115a4a682c66baf3bc9e0329bab7; observatory id bitagent:8453:7287)\nwhat the buyer asked (job description on chain): equity_research where ticker is 'AAPL\nprice: 1.5 USDC funded into escrow\nbuyer: 0xc41c35cd98ed94b54a2adfcdf24a5574fdd0b5b8\nseller: 0x1112889be806840a66419ea1e8d4dd21852993e5\nevaluator: 0x4302e523d982f3b89cfc43ce4530c012b495ec11\nevaluator kind: platform (bitagent_platform_evaluator) — buyer = the client evaluates its own job; none = no evaluator, the job auto-completes; named = another address; platform = the deployment's own evaluator contract, settled by its operator through forceSettleJob\nhook: 0x4302e523d982f3b89cfc43ce4530c012b495ec11\ncreated: 2026-08-28 05:51:23 UTC\nfunded: 2026-08-28 05:51:43 UTC (20 s after creation)\ndeadline: 2026-09-27 05:51:16 UTC (30.0 d after funding)\nsubmitted: 2026-08-28 05:51:55 UTC (12 s after funding), 30.0 d before the deadline\nwhat was delivered: a 32-byte digest 0xea9708d1352f28825bce3055ff248dbdae50314094f2adf3526bfe113d3f0641; the content behind it is not published on chain\nhow it ended: still open\nevents in order: JobCreated (block 50553468) → BudgetSet (block 50553473) → ProviderSet (block 50553475) → JobFunded (block 50553478) → JobSubmitted (block 50553484)\nthis buyer with this seller: 6 jobs: 6 open\nseller record (paid jobs that ended): 6 completed and paid, 0 delivered then rejected or paid and never delivered, 0 paid and expired after delivery with no ruling; 148 jobs in all\nseller speed: median 10 s from funding to delivery over 66 paid jobs\nseller buyers: 10 distinct buyers; the largest placed 7% of its jobs\nnot known:\n- the delivered content itself is not on chain, only its digest",
+  "facts": {
+    "delivered": true,
+    "checks": {
+      "funded": true,
+      "submitted": true
+    }
+  },
+  "model": "jev-1.13.0",
+  "answers": [
+    {
+      "id": "spec_met",
+      "value": "no",
+      "confidence": 0.95,
+      "probabilities": {
+        "no": 0.97,
+        "yes": 0.03
+      }
+    },
+    {
+      "id": "unsupported_claim",
+      "value": "no",
+      "confidence": 0.87,
+      "probabilities": {
+        "no": 0.94,
+        "yes": 0.06
+      }
+    },
+    {
+      "id": "ending",
+      "value": "needs_review",
+      "confidence": 0.9,
+      "probabilities": {
+        "complete": 0.07,
+        "expire": 0,
+        "needs_review": 0.93,
+        "reject": 0
+      }
+    },
+    {
+      "id": "cheat_shaped",
+      "value": "no",
+      "confidence": 0.13,
+      "probabilities": {
+        "no": 0.56,
+        "yes": 0.44
+      }
+    }
+  ],
+  "recorded": {
+    "decision": "decision-1790520028322-8a6fc06cd8",
+    "digest": "0x8a6fc06cd8bcbfc0ec4905a1b517a6840fd91312b291c9d4d4bfca88d6a4ed1b",
+    "input_digest": "0x4a66b95eab6227f134aafbf58a1d8a2a5388267007ae2941c4c883e25c3ecc1f",
+    "subject_id": "0x3d7648d403fc2475c772d92c7a0a3a5a6750a5544307895771b83f4637752923",
+    "confidence_bps": 1300,
+    "anchor": {
+      "chainId": 36927,
+      "contract": "0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05",
+      "tx": "0xffc608f8c8b39ff6992e8ec8d589b8784a3cf4199359c408f8eed1d4b581c622"
+    }
+  }
+}