@taifoon/jev 0.2.8 → 0.2.10

package/README.md

@@ -118,6 +118,7 @@ Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or
 | `--layer <https url>` / `--no-layer` | `https://coord.taifoon.dev` | Where jobs and quotes are read |
 | `--protocol <name>` | from the job id | Evaluator seat: `virtuals-erc8183`, `virtuals-memo-acp`, `bitagent-erc8183`, `assurance-hook`, `judge-adapter` |
 | `--price-usdc <n>` | the job's budget | Price for the premium quote |
+| `--seller-record <k>/<n>` | read from the layer | Price the premium here from the seller's record (k delivered of n graded) with [`@taifoon/jev-wilson`](https://www.npmjs.com/package/@taifoon/jev-wilson): the layer's numbers, no request |
 | `--yes` / `--json` | ask per step / text | Run every step without asking / print the whole trace as JSON |
 
 Environment: `TYPESAFE_KEY` (your key; without it a job that needs Jev stops and says where to get one, while a job the

package/bin/run.mjs

@@ -35,7 +35,7 @@ function factOf(r) {
   }
 }
 
-const USAGE = 'jev run [--demo | --job <chain>:<id> | --job-file job.json | --evidence pack.json] [--answers answers.json] [--record none|devnet|base|both] [--layer <https url> | --no-layer] [--protocol <name>] [--price-usdc <n>] [--yes] [--json]';
+const USAGE = 'jev run [--demo | --job <chain>:<id> | --job-file job.json | --evidence pack.json] [--answers answers.json] [--record none|devnet|base|both] [--layer <https url> | --no-layer] [--protocol <name>] [--price-usdc <n>] [--seller-record <k>/<n>] [--yes] [--json]';
 const PROTOCOLS = ['assurance-hook', 'judge-adapter', 'virtuals-erc8183', 'virtuals-memo-acp', 'bitagent-erc8183'];
 /** A stranger's typo must never run something else: every flag is known, every value checked, exit 2 with the fix. */
 function refuse(msg) { process.stderr.write(`jev run: ${msg}\n  ${USAGE}\n`); process.exit(2); }
@@ -56,7 +56,7 @@ export async function run(argv) {
   const ansFile = file('--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 protocol = val('--protocol'); const price = val('--price-usdc'); const sellerRec = val('--seller-record');
   if (a.length) refuse(`unknown flag ${a[0]}`);
   if (!['none', 'devnet', 'base', 'both'].includes(network)) refuse(`--record is none, devnet, base or both (got ${network})`);
   if (demo && (job || evFile || jobFile || ansFile)) refuse('--demo replays one recorded job: drop --job, --job-file, --evidence and --answers');
@@ -65,6 +65,8 @@ export async function run(argv) {
   if (layer && !/^https:\/\//.test(layer)) refuse('--layer must be an https:// URL');
   if (protocol && !PROTOCOLS.includes(protocol)) refuse(`--protocol is one of ${PROTOCOLS.join(', ')}`);
   if (price !== undefined && !(Number(price) > 0)) refuse(`--price-usdc must be a positive number (got ${price})`);
+  const recM = sellerRec === undefined ? null : /^(\d+)\/(\d+)$/.exec(sellerRec);
+  if (sellerRec !== undefined && (!recM || Number(recM[1]) > Number(recM[2]) || Number(recM[2]) === 0)) refuse(`--seller-record must be <delivered>/<graded>, e.g. 60/62 (got ${sellerRec})`);
   const { pipeline, STEPS, prepareJob } = await import('../dist/index.js');
 
   const t = createTerm({ quiet: json });
@@ -72,7 +74,7 @@ export async function run(argv) {
   t.info(`jev run · ${noLayer ? 'offline' : `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,
+    layer, job, network, protocol, priceUsdc: price ? Number(price) : undefined, sellerRecord: recM ? { k: Number(recM[1]), n: Number(recM[2]) } : undefined,
     evidence: rec ? { subject: rec.subject.ref, from: `the recorded job ${rec.job.ref} (${rec.job.protocol}, ${rec.job.price})`, 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,

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export { prepareJob, runCheck } from './job.js';
 export { record } from './record.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
-export { pipeline, STEPS, LAYER, factsFromEvidence, protocolFor, parseJob } from './pipeline.js';
+export { pipeline, STEPS, LAYER, factsFromEvidence, protocolFor, parseJob, localQuote } from './pipeline.js';
 export { RUBRIC_v1 } from './rubric.js';
 export { CONTRACTS } from './contracts.js';
 export type { GradeInput, Receipt } from './grade.js';

package/dist/index.js

@@ -19,6 +19,6 @@ export { prepareJob, runCheck } from './job.js';
 export { record } from './record.js';
 export { evaluatorCall } from './evaluator/index.js';
 export { verify } from './verify.js';
-export { pipeline, STEPS, LAYER, factsFromEvidence, protocolFor, parseJob } from './pipeline.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/pipeline.d.ts

@@ -127,12 +127,23 @@ export type PipelineOpts = {
     chainVerify?: boolean;
     /** price for the premium step, in USDC; default: the job's budget */
     priceUsdc?: number | null;
+    /** the seller's record, k delivered of n graded: the premium is priced locally (@taifoon/jev-wilson, the layer's own
+     *  numbers to the last digit) and the layer is not asked */
+    sellerRecord?: {
+        k: number;
+        n: number;
+    } | null;
     /** a gate before each step: return false to skip it. The interactive CLI asks here. */
     before?: (step: (typeof STEPS)[number], trace: Trace) => boolean | Promise<boolean>;
     /** called after each step with its result */
     after?: (result: StepResult, trace: Trace) => void | Promise<void>;
     fetch?: typeof fetch;
 };
+/** The premium the layer would quote for this record, computed here: same z, same bound, same rounding. */
+export declare function localQuote(record: {
+    k: number;
+    n: number;
+}, priceUsdc: number | null): Quote;
 /** A job reference: `8453:81100`, `8453:bitagent:8453:7287`, or a bare id (chain 8453). */
 export declare function parseJob(j: string | {
     chainId: number;

package/dist/pipeline.js

@@ -1,10 +1,11 @@
 // 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
+// runs on your own TypeSafe key (or answers you already have), `record` returns unsigned calls, `premium` is priced from a `sellerRecord` you pass (or 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 { premium as wilsonPremium, wilson } from './wilson.js';
 import { facts as runFacts } from './facts.js';
 import { grade } from './grade.js';
 import { record } from './record.js';
@@ -23,6 +24,19 @@ export const STEPS = Object.freeze([
     { 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 },
 ]);
+/** The premium the layer would quote for this record, computed here: same z, same bound, same rounding. */
+export function localQuote(record, priceUsdc) {
+    const units = priceUsdc ? Math.round(priceUsdc * 1e6) : undefined;
+    const p = wilsonPremium(record, units === undefined ? {} : { price: units });
+    const [lo, hi] = wilson(record.n - record.k, record.n);
+    const pct = (x) => `${(x * 100).toFixed(1)}%`;
+    return {
+        guaranteed: p.covered, premium: p.amount === null ? null : p.amount.toString(), premium_ratio: p.ratio, deposit: null,
+        premium_label: p.insurable ? `${pct(lo)}–${pct(hi)} · ${record.k} of ${record.n} delivered` : 'UNKNOWN: no delivered job on record',
+        record: { n: record.n, settled: record.n, incorrect: record.n - record.k, wilson: [lo, hi], calibrated: false, insurable: p.insurable },
+        why: p.insurable ? (p.covered ? [] : [`ratio ${p.ratio.toFixed(4)} is above the 0.30 the pool covers`]) : ['a record with no delivered job is not insurable'],
+    };
+}
 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). */
@@ -181,8 +195,13 @@ export async function pipeline(o = {}) {
     });
     await step('premium', async () => {
         const seller = t.job.seller;
+        if (o.sellerRecord) {
+            const price = o.priceUsdc ?? budget;
+            t.quote = localQuote(o.sellerRecord, price);
+            return { source: 'local: Wilson on the record you passed', guaranteed: t.quote.guaranteed, premium_ratio: t.quote.premium_ratio, premium_label: t.quote.premium_label, record: t.quote.record ?? null };
+        }
         if (!layer)
-            return { skip: 'offline: the premium quote reads the seller\'s record from the layer' };
+            return { skip: 'offline: pass sellerRecord (--seller-record k/n) to price locally, or a layer to read the seller\'s record' };
         if (!seller)
             return { skip: 'no seller address in the evidence' };
         const price = o.priceUsdc ?? budget;

package/dist/wilson.d.ts

@@ -0,0 +1,49 @@
+/** 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;

package/dist/wilson.js

@@ -0,0 +1,66 @@
+// 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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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",
@@ -70,6 +70,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@taifoon/jev-wilson": "^0.1.0",
     "@types/node": "^25.9.2",
     "typescript": "5.9.2",
     "viem": "2.52.2",