@taifoon/jev 0.2.11 → 0.2.13

package/README.md

@@ -137,7 +137,7 @@ code checks reject is still graded). Exit codes: `0` done, `1` a step failed, `2
 - **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 five calls
+## The six calls
 
 | Call | What it does |
 |---|---|
@@ -148,13 +148,18 @@ code checks reject is still graded). Exit codes: `0` done, `1` a step failed, `2
 | `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 |
 
+`verifyDecision(record, { answers? })` does the same for a decision as the coordination layer serves it at
+`/v1/judge/decisions/{id}`: the input fingerprint, the decision digest, the answers digest and the verdict RUBRIC_v1
+composes, all offline. `npx @taifoon/jev verify decision-1790522234088-10691d5017 --network base` runs it on the
+block-proof grade and then finds both entries on Base.
+
 Evaluator seats: `assurance-hook`, `judge-adapter`, `virtuals-erc8183`, `virtuals-memo-acp` and `bitagent-erc8183`.
 Each is tested against calldata a mined transaction carried.
 
 ## Documentation
 
 - [How grading works: Jev, the pipeline, THRESHOLDS_v1, `npx @taifoon/jev run`](docs/PIPELINE.md)
-- [API: the five calls, where Jev is reached, your own rubric](docs/API.md)
+- [API: the six calls, where Jev is reached, your own rubric](docs/API.md)
 - [Evaluator seats, with the transactions they are tested against](docs/EVALUATORS.md)
 - [On chain: contract addresses on Base and devnet, and one real grade end to end](docs/ON_CHAIN.md)
 - [The records: receipt, decision.v2, jev.answer.v1](docs/RECORDS.md)
@@ -163,6 +168,7 @@ Each is tested against calldata a mined transaction carried.
 
 ```
 npx @taifoon/jev verify <digest> --network base
+npx @taifoon/jev verify <decision id> --network base   # recompute the served record offline, then find it on chain
 npx @taifoon/jev workflows export ./jev-workflows
 ```
 
@@ -170,4 +176,4 @@ npx @taifoon/jev workflows export ./jev-workflows
 
 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.
+Built by Taifoon. MIT. The package's only runtime dependency is Taifoon's own @taifoon/jev-wilson, the pricing; nothing third-party. It contains no key. It calls Jev only with your own TypeSafe key.

package/bin/jev.mjs

@@ -3,7 +3,7 @@
 //   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 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)
+//   jev verify <answers-digest | decision id> [--network devnet|base|any]  (a decision id: recompute its record offline, then) 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';
@@ -34,12 +34,25 @@ if (cmd === 'workflows') {
 } 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 { verify, verifyDecision, LAYER } = await import('../dist/index.js');
   if (!['devnet', 'base', 'any'].includes(network)) die('--network is devnet, base or any');
-  let v = await verify(sub, { network: network === 'base' ? 'base' : 'devnet' });
+  let digest = sub; let offline = null;
+  // a decision id (or its /v1/judge/decisions URL): read the served record and its answers, recompute both here, then
+  // find the answers digest on chain like any other
+  const m = /(decision-\d+-[0-9a-f]{10})/.exec(sub);
+  if (m) {
+    const get = async (p) => { const r = await fetch(`${LAYER}${p}`, { signal: AbortSignal.timeout(30_000) }); if (!r.ok) die(`${LAYER}${p} answered ${r.status}`); return r.json(); };
+    const rec = await get(`/v1/judge/decisions/${m[1]}`);
+    const ad = rec?.decision?.answers_digest;
+    const ans = ad ? await get(`/v1/judge/answers/${ad}`) : null;
+    offline = verifyDecision(rec, ans?.record ? { answers: ans.record } : {});
+    if (!ad) { console.log(JSON.stringify({ offline }, null, 1)); process.exit(offline.ok ? 0 : 2); }
+    digest = ad;
+  }
+  let v = await verify(digest, { 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);
+  console.log(JSON.stringify(offline ? { offline, ...v, ok: v.ok && offline.ok } : v, null, 1));
+  process.exit(v.ok && (!offline || offline.ok) ? 0 : 2);
 } else {
-  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]`);
+  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 | decision id> [--network devnet|base|any]`);
 }

package/dist/decision.d.ts

@@ -0,0 +1,35 @@
+import { type Hex } from './hash.js';
+import { type AnswerRecord, type DecisionAnswer, type Subject } from './records.js';
+import { type Composed, type Facts, type Rubric, type RubricInput } from './rubric.js';
+/** The fields of a served decision.v2 record this check reads (the rest is carried as is). */
+export type DecisionRecord = {
+    v?: string;
+    id?: string;
+    kind: string;
+    subject: Subject;
+    model: string | null;
+    answers: DecisionAnswer[];
+    input?: string | null;
+    input_digest: Hex;
+    digest: Hex;
+    subject_id?: Hex;
+    kind_id?: Hex;
+    confidence_bps?: number;
+    answers_digest?: Hex | null;
+};
+export type DecisionCheck = {
+    ok: boolean;
+    checks: Record<string, boolean>;
+    problems: string[];
+    composed: Composed | null;
+    digest: Hex;
+};
+export declare function verifyDecision(d: DecisionRecord | {
+    decision: DecisionRecord;
+}, opts?: {
+    answers?: AnswerRecord | {
+        record: AnswerRecord;
+    };
+    facts?: Facts;
+    rubric?: Rubric | RubricInput;
+}): DecisionCheck;

package/dist/decision.js

@@ -0,0 +1,40 @@
+// verifyDecision(): recompute a decision.v2 record exactly as the coordination layer serves it at
+// /v1/judge/decisions/{id} (and its jev.answer.v1 record at /v1/judge/answers/{digest}), offline, with this package's
+// own code: the input fingerprint (sha256 of the text Jev read), the subject and kind ids, the decision digest, the
+// on-chain confidence, the answers digest and the verdict RUBRIC_v1 composes from the answers. `verify()` takes the
+// receipt `grade()` returns; this takes the record a reader finds by its link.
+import { sha256Hex } from './hash.js';
+import { answersDigestOf, confidenceBpsOf, decisionDigest, kindIdOf, subjectIdOf } from './records.js';
+import { defineRubric, RUBRIC_v1 } from './rubric.js';
+const low = (h) => String(h ?? '').toLowerCase();
+export function verifyDecision(d, opts = {}) {
+    const r = ('decision' in d ? d.decision : d);
+    const checks = {};
+    if (typeof r.input === 'string')
+        checks.inputDigest = low(sha256Hex(r.input)) === low(r.input_digest);
+    if (r.subject_id)
+        checks.subjectId = low(subjectIdOf(r.subject)) === low(r.subject_id);
+    if (r.kind_id)
+        checks.kindId = low(kindIdOf(r.kind)) === low(r.kind_id);
+    const digest = decisionDigest({ kind: r.kind, subject: r.subject, answers: r.answers, model: r.model, input_digest: r.input_digest });
+    checks.decisionDigest = low(digest) === low(r.digest);
+    if (typeof r.confidence_bps === 'number')
+        checks.confidenceBps = confidenceBpsOf(r.answers) === r.confidence_bps;
+    const ans = opts.answers ? ('record' in opts.answers ? opts.answers.record : opts.answers) : null;
+    if (ans) {
+        if (r.answers_digest)
+            checks.answersDigest = low(answersDigestOf(ans)) === low(r.answers_digest);
+        checks.answersBindInput = low(ans.input_digest) === low(r.input_digest);
+        checks.answersMatchDecision = r.answers.every((a) => { const b = ans.answers.find((x) => x.id === a.id); return !!b && b.value === a.value && JSON.stringify(b.distribution) === JSON.stringify(a.probabilities); });
+    }
+    let composed = null;
+    if (r.kind === 'grade') {
+        const rubric = opts.rubric ? defineRubric(opts.rubric) : RUBRIC_v1;
+        // A recorded decision exists only once the checks passed (a failed check rejects without asking Jev), so the
+        // default facts are "delivered, checks ok"; pass `facts` to compose under others (e.g. the job's price).
+        const facts = opts.facts ?? { delivered: true, checksOk: true, checks: {}, priceUsdc: null };
+        composed = rubric.compose(facts, Object.fromEntries(r.answers.map((a) => [a.id, { id: a.id, value: a.value, confidence: a.confidence, probabilities: a.probabilities }])));
+    }
+    const problems = Object.entries(checks).filter(([, v]) => !v).map(([k]) => `${k} does not recompute`);
+    return { ok: problems.length === 0, checks, problems, composed, digest };
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  *   record()         the unsigned calls that put the receipt's digests on JevAnswerLog / JevDecisionLog
  *   evaluatorCall()  the unsigned call that ends the job on the protocol whose evaluator seat you hold
  *   verify()         recompute every digest and find the chain events that hold them
+ *   verifyDecision() recompute a decision record as /v1/judge/decisions/{id} serves it, offline
  *   pipeline()       one job through the coordination layer's steps: pick → evidence → facts → grade → record → evaluator → premium → verify
  *   RUBRIC_v1        the questions, thresholds and composition (pass your own rubric to grade)
  *   CONTRACTS        where the logs and the evaluator seats are
@@ -19,6 +20,7 @@ export { prepareJob, runCheck } from './job.js';
 export { record } from './record.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
+export { verifyDecision } from './decision.js';
 export { pipeline, STEPS, LAYER, factsFromEvidence, protocolFor, parseJob, localQuote } from './pipeline.js';
 export { RUBRIC_v1 } from './rubric.js';
 export { CONTRACTS } from './contracts.js';
@@ -27,6 +29,7 @@ export type { FactsInput, Check } from './facts.js';
 export type { JobSpec, JobCheck, PreparedJob } from './job.js';
 export type { Recorded, UnsignedCall, Network } from './record.js';
 export type { Verification, AnswerEvent, DecisionEvent } from './verify.js';
+export type { DecisionRecord, DecisionCheck } from './decision.js';
 export type { Protocol, Adapter, AdapterOpts, EvaluatorCall } from './evaluator/index.js';
 export type { JevError } from './ask.js';
 export type { Rubric, RubricInput, Question, Answer, Facts, Verdict, Composed, Thresholds } from './rubric.js';

package/dist/index.js

@@ -7,6 +7,7 @@
  *   record()         the unsigned calls that put the receipt's digests on JevAnswerLog / JevDecisionLog
  *   evaluatorCall()  the unsigned call that ends the job on the protocol whose evaluator seat you hold
  *   verify()         recompute every digest and find the chain events that hold them
+ *   verifyDecision() recompute a decision record as /v1/judge/decisions/{id} serves it, offline
  *   pipeline()       one job through the coordination layer's steps: pick → evidence → facts → grade → record → evaluator → premium → verify
  *   RUBRIC_v1        the questions, thresholds and composition (pass your own rubric to grade)
  *   CONTRACTS        where the logs and the evaluator seats are
@@ -19,6 +20,7 @@ export { prepareJob, runCheck } from './job.js';
 export { record } from './record.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
+export { verifyDecision } from './decision.js';
 export { pipeline, STEPS, LAYER, factsFromEvidence, protocolFor, parseJob, localQuote } from './pipeline.js';
 export { RUBRIC_v1 } from './rubric.js';
 export { CONTRACTS } from './contracts.js';

package/dist/wilson.d.ts

@@ -1,49 +1,2 @@
-/** z for a two-sided 95% interval, as the layer pins it. */
-export declare const Z = 1.959963984540054;
-/** The layer's pool rule: no pool covers above this premium ratio. */
-export declare const MAX_PREMIUM_RATIO = 0.3;
-/** The premium ratio is rounded to millionths before it multiplies the price. */
-export declare const RATIO_SCALE = 1000000;
-/** The Wilson score interval for `successes` of `n`. [0, 1] when n = 0. Same operations, same order as the layer. */
-export declare function wilson(successes: number, n: number, z?: number): [number, number];
-/** u_F: the upper Wilson bound on the failure rate, n - k failed of n. This is the layer's π ratio. */
-export declare function wilsonUpperFailure(k: number, n: number, z?: number): number;
-/** floor(price × round(ratio × 1e6) / 1e6), exactly as the layer's pool-quote computes it. */
-export declare function premiumAmount(price: bigint, ratio: number): bigint;
-export type SellerRecord = {
-    k: number;
-    n: number;
-};
-export type PremiumOpts = {
-    /** floor on the ratio; default 0 (the layer has none) */
-    min?: number;
-    /** cover only when ratio <= max; default 0.30 (the layer's pool rule) */
-    max?: number;
-    /** price in the token's smallest unit; when given, `amount` is computed */
-    price?: bigint | number | string;
-    /** z for the record form; default Z */
-    z?: number;
-};
-export type Premium = {
-    insurable: false;
-    reason: 'UNKNOWN';
-    ratio: null;
-    amount: null;
-    covered: false;
-    basis: 'record';
-} | {
-    insurable: true;
-    ratio: number;
-    amount: bigint | null;
-    covered: boolean;
-    basis: 'record' | 'p_L';
-};
-/**
- * The premium for the next job.
- *
- * premium({ k, n }, opts)  prices from the record: ratio = u_F, bit-for-bit with the layer.
- * premium(pL, opts)        prices from a lower bound you already hold: ratio = 1 - p_L. Equal in real
- *                          arithmetic, but 1 - p_L can differ from u_F in the last bits of a double.
- *                          Use the record form when you need the layer's number to the last digit.
- */
-export declare function premium(input: number | SellerRecord, opts?: PremiumOpts): Premium;
+export { Z, MAX_PREMIUM_RATIO, RATIO_SCALE, wilson, wilsonUpperFailure, premiumAmount, premium } from '@taifoon/jev-wilson';
+export type { SellerRecord, PremiumOpts, Premium } from '@taifoon/jev-wilson';

package/dist/wilson.js

@@ -1,66 +1,3 @@
-// GENERATED from @taifoon/jev-wilson 0.1.0 (src/wilson.ts) by scripts/vendor-wilson.mjs. Do not edit here.
-// The pricing half only: z, the Wilson interval, the premium. Same numbers as the layer's /v1/pools/quote.
-/** z for a two-sided 95% interval, as the layer pins it. */
-export const Z = 1.959963984540054;
-/** The layer's pool rule: no pool covers above this premium ratio. */
-export const MAX_PREMIUM_RATIO = 0.3;
-/** The premium ratio is rounded to millionths before it multiplies the price. */
-export const RATIO_SCALE = 1_000_000;
-function checkRecord(k, n) {
-    if (!Number.isInteger(k) || !Number.isInteger(n) || k < 0 || n < 0 || k > n) {
-        throw new RangeError(`need integers 0 <= k <= n, got k=${k}, n=${n}`);
-    }
-}
-/** The Wilson score interval for `successes` of `n`. [0, 1] when n = 0. Same operations, same order as the layer. */
-export function wilson(successes, n, z = Z) {
-    if (n <= 0)
-        return [0, 1];
-    const p = successes / n, z2 = z * z;
-    const d = 1 + z2 / n;
-    const c = p + z2 / (2 * n);
-    const s = z * Math.sqrt((p * (1 - p) + z2 / (4 * n)) / n);
-    return [Math.max(0, (c - s) / d), Math.min(1, (c + s) / d)];
-}
-/** u_F: the upper Wilson bound on the failure rate, n - k failed of n. This is the layer's π ratio. */
-export function wilsonUpperFailure(k, n, z = Z) {
-    checkRecord(k, n);
-    return wilson(n - k, n, z)[1];
-}
-/** JavaScript Math.round, kept explicit so the Python twin can match it. */
-const roundHalfUp = (x) => Math.round(x);
-/** floor(price × round(ratio × 1e6) / 1e6), exactly as the layer's pool-quote computes it. */
-export function premiumAmount(price, ratio) {
-    if (price <= 0n)
-        throw new RangeError('price must be a positive integer in the token’s smallest unit');
-    return (price * BigInt(roundHalfUp(ratio * RATIO_SCALE))) / BigInt(RATIO_SCALE);
-}
-/**
- * The premium for the next job.
- *
- * premium({ k, n }, opts)  prices from the record: ratio = u_F, bit-for-bit with the layer.
- * premium(pL, opts)        prices from a lower bound you already hold: ratio = 1 - p_L. Equal in real
- *                          arithmetic, but 1 - p_L can differ from u_F in the last bits of a double.
- *                          Use the record form when you need the layer's number to the last digit.
- */
-export function premium(input, opts = {}) {
-    const min = opts.min ?? 0;
-    const max = opts.max ?? MAX_PREMIUM_RATIO;
-    let raw;
-    let basis;
-    if (typeof input === 'number') {
-        if (!(input >= 0 && input <= 1))
-            throw new RangeError(`p_L must be in [0, 1], got ${input}`);
-        raw = 1 - input;
-        basis = 'p_L';
-    }
-    else {
-        checkRecord(input.k, input.n);
-        if (input.k <= 0)
-            return { insurable: false, reason: 'UNKNOWN', ratio: null, amount: null, covered: false, basis: 'record' };
-        raw = wilsonUpperFailure(input.k, input.n, opts.z ?? Z);
-        basis = 'record';
-    }
-    const ratio = raw < min ? min : raw;
-    const amount = opts.price === undefined ? null : premiumAmount(BigInt(opts.price), ratio);
-    return { insurable: true, ratio, amount, covered: ratio <= max, basis };
-}
+// The pricing half is @taifoon/jev-wilson, the layer's own package, and this module is its re-export: one
+// implementation, the same numbers as the layer's /v1/pools/quote. Installing @taifoon/jev installs it.
+export { Z, MAX_PREMIUM_RATIO, RATIO_SCALE, wilson, wilsonUpperFailure, premiumAmount, premium } from '@taifoon/jev-wilson';

package/docs/API.md

@@ -1,6 +1,6 @@
 # API
 
-## The five calls
+## The six calls
 
 | Call | What it does | Network |
 |---|---|---|
@@ -8,9 +8,11 @@
 | `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 |
+| `prepareJob({ id, task, criteria, delivered, source?, checks? })` | Turns a job as the buyer laid it out into the evidence Jev reads and the checks code runs. | None |
 | `verify(receiptOrDigest)` | Recomputes every digest, re-composes the verdict and finds the `JevAnswered` and `Decided` events. | One devnet RPC read |
+| `verifyDecision(record, { answers?, facts? })` | Recomputes a decision record as `/v1/judge/decisions/{id}` serves it: sha256 of the text Jev read, subject and kind ids, the decision digest, the on-chain confidence, the answers digest (with the `/v1/judge/answers/{digest}` record) and the verdict RUBRIC_v1 composes. | None |
 
-It also exports `RUBRIC_v1` and `CONTRACTS`. Nothing else.
+It also exports `RUBRIC_v1`, `CONTRACTS`, `runCheck` and the `jev run` pipeline (`pipeline`, `STEPS`, `LAYER` and its helpers).
 
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Grade AI agent jobs with TypeSafe's Jev and record the verdict on chain: code checks the facts, Jev answers a published rubric, and you get a receipt, the on-chain record and the evaluator call for ERC-8183 and Virtuals ACP. No runtime dependencies, no key inside.",
   "keywords": [
     "jev",
@@ -69,8 +69,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@taifoon/jev-wilson": "^0.2.0"
+  },
   "devDependencies": {
-    "@taifoon/jev-wilson": "^0.1.0",
     "@types/node": "^25.9.2",
     "typescript": "5.9.2",
     "viem": "2.52.2",