@taifoon/jev 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Taifoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# @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.
+
+Built by Taifoon. MIT. The package has no runtime dependencies and contains no key.
+
+```
+npm i @taifoon/jev
+```
+
+The package also ships the n8n workflows that run Jev as a versioned bundle (see [Workflows](#workflows)).
+
+## 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, 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:
+
+```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 }
+});
+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
+```
+
+## 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.
+
+## 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 |
+|---|---|---|
+| 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.
+
+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.
+
+## 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
+
+`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`:
+
+- **`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.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:
+
+- `@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
+```
+
+## 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>/ from the umbrella's workflows/ and zip it for the release
+```

package/bin/jev.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// 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
+import { cpSync, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+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 bundle = join(ROOT, 'workflows', version);
+const die = (m) => { console.error(m); process.exit(1); };
+const [cmd, sub, target] = args;
+
+if (cmd === 'workflows') {
+  if (!existsSync(bundle)) die(`no workflow bundle ${version}; bundled: ${readdirSync(join(ROOT, 'workflows')).join(', ')}`);
+  const m = JSON.parse(readFileSync(join(bundle, 'manifest.json'), 'utf8'));
+  if (sub === 'list') {
+    for (const w of m.workflows) console.log(`${w.file}  ${w.name}\n  nodes: ${w.packages.join(', ')}  ·  credentials: ${w.credentials.join(', ') || 'none'}`);
+  } else if (sub === 'export') {
+    if (!target) die('usage: jev workflows export <dir> [--version X]');
+    const out = resolve(target);
+    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 === 'verify' && sub) {
+  const { verify } = await import('../dist/index.js');
+  const v = await verify(sub);
+  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>`);
+}

package/dist/abi.d.ts

@@ -0,0 +1,11 @@
+import { type Hex } from './hash.js';
+export type AbiType = 'bytes32' | 'uint256' | 'uint64' | 'uint16' | 'uint8' | 'bool' | 'address' | 'bytes' | 'string';
+export type AbiValue = string | number | bigint | boolean;
+/** abi.encode(values) for the given types */
+export declare function encode(types: readonly AbiType[], values: readonly AbiValue[]): Hex;
+/** the 4-byte selector of a canonical signature, e.g. "complete(bytes32)" */
+export declare const selector: (signature: string) => Hex;
+/** calldata: selector ‖ abi.encode(args); the types are read from the signature */
+export declare function encodeCall(signature: string, values: readonly AbiValue[]): Hex;
+/** abi.decode for the same types (log data) */
+export declare function decode(types: readonly AbiType[], data: Hex): AbiValue[];

package/dist/abi.js

@@ -0,0 +1,81 @@
+// The ABI encoding this package needs, and no more: static words (bytes32, uintN, bool, address) and dynamic bytes /
+// string, for calls and for reading the two log events. Checked against viem in test/abi.test.ts.
+import { fromHex, keccakHex, toHex, utf8 } from './hash.js';
+const word = (n) => { if (n < 0n || n >= 1n << 256n)
+    throw new Error('uint out of range'); return n.toString(16).padStart(64, '0'); };
+const isDynamic = (t) => t === 'bytes' || t === 'string';
+function staticWord(t, v) {
+    switch (t) {
+        case 'bool': return word(v ? 1n : 0n);
+        case 'address': {
+            const s = String(v);
+            if (!/^0x[0-9a-fA-F]{40}$/.test(s))
+                throw new Error(`not an address: ${s}`);
+            return s.slice(2).toLowerCase().padStart(64, '0');
+        }
+        case 'bytes32': {
+            const s = String(v);
+            if (!/^0x[0-9a-fA-F]{64}$/.test(s))
+                throw new Error(`not a bytes32: ${s}`);
+            return s.slice(2).toLowerCase();
+        }
+        default: {
+            const bits = Number(t.slice(4));
+            const n = BigInt(v);
+            if (n < 0n || n >= 1n << BigInt(bits))
+                throw new Error(`${String(v)} does not fit ${t}`);
+            return word(n);
+        }
+    }
+}
+function tail(t, v) {
+    const b = t === 'string' ? utf8(String(v)) : fromHex(String(v));
+    const hex = toHex(b).slice(2);
+    return word(BigInt(b.length)) + hex.padEnd(Math.ceil(hex.length / 64) * 64, '0');
+}
+/** abi.encode(values) for the given types */
+export function encode(types, values) {
+    if (types.length !== values.length)
+        throw new Error('types and values differ in length');
+    let head = '';
+    let body = '';
+    const headLen = types.length * 32;
+    types.forEach((t, i) => {
+        if (isDynamic(t)) {
+            head += word(BigInt(headLen + body.length / 2));
+            body += tail(t, values[i]);
+        }
+        else
+            head += staticWord(t, values[i]);
+    });
+    return `0x${head}${body}`;
+}
+/** the 4-byte selector of a canonical signature, e.g. "complete(bytes32)" */
+export const selector = (signature) => keccakHex(signature).slice(0, 10);
+/** calldata: selector ‖ abi.encode(args); the types are read from the signature */
+export function encodeCall(signature, values) {
+    const inner = signature.slice(signature.indexOf('(') + 1, -1);
+    const types = (inner ? inner.split(',') : []);
+    return `${selector(signature)}${encode(types, values).slice(2)}`;
+}
+/** abi.decode for the same types (log data) */
+export function decode(types, data) {
+    const h = data.slice(2);
+    const at = (i) => h.slice(i * 64, i * 64 + 64);
+    return types.map((t, i) => {
+        const w = at(i);
+        if (isDynamic(t)) {
+            const off = Number(BigInt('0x' + w)) * 2;
+            const len = Number(BigInt('0x' + h.slice(off, off + 64)));
+            const raw = h.slice(off + 64, off + 64 + len * 2);
+            return t === 'string' ? new TextDecoder().decode(fromHex(raw)) : `0x${raw}`;
+        }
+        if (t === 'bool')
+            return BigInt('0x' + w) !== 0n;
+        if (t === 'address')
+            return `0x${w.slice(24)}`;
+        if (t === 'bytes32')
+            return `0x${w}`;
+        return BigInt('0x' + w);
+    });
+}

package/dist/ask.d.ts

@@ -0,0 +1,27 @@
+import type { Answer, Question } from './rubric.js';
+export declare const TRIAL_URL = "https://typesafe.taifoon.dev/v1/trial";
+export declare const TYPESAFE_URL = "https://api.typesafe.ai";
+export declare const TRIAL_MAX_STATE = 4000;
+export type Asked = {
+    answers: Record<string, Answer>;
+    model: string | null;
+    latency_ms: number | null;
+    connection: 'trial' | 'key';
+    trial: {
+        calls: number;
+        left: number;
+    } | null;
+};
+export declare class JevError extends Error {
+    readonly status: number;
+    readonly next?: string | undefined;
+    constructor(message: string, status: number, next?: string | undefined);
+}
+export declare function askJev(a: {
+    text: string;
+    questions: readonly Question[];
+    key?: string | null;
+    trialUrl?: string;
+    endpoint?: string;
+    fetch?: typeof fetch;
+}): Promise<Asked>;

package/dist/ask.js

@@ -0,0 +1,47 @@
+export const TRIAL_URL = 'https://typesafe.taifoon.dev/v1/trial';
+export const TYPESAFE_URL = 'https://api.typesafe.ai';
+export const TRIAL_MAX_STATE = 4_000;
+export class JevError extends Error {
+    status;
+    next;
+    constructor(message, status, next) {
+        super(message);
+        this.status = status;
+        this.next = next;
+        this.name = 'JevError';
+    }
+}
+const norm = (id, a) => ({ id, value: String(a.value ?? a.choice ?? ''), confidence: Number(a.confidence ?? 0), probabilities: a.probabilities ?? {} });
+export async function askJev(a) {
+    const f = a.fetch ?? fetch;
+    const started = Date.now();
+    if (a.key) {
+        const base = (a.endpoint ?? TYPESAFE_URL).replace(/\/$/, '');
+        if (!/^https:\/\//.test(base))
+            throw new JevError('a key is only sent over https', 400);
+        const questions = Object.fromEntries(a.questions.map((q) => [q.id, { type: 'choice', instructions: q.text, criteria: Object.fromEntries(q.options.map((o) => [o, o])) }]));
+        const r = await f(`${base}/v1/systemone`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${a.key}` }, body: JSON.stringify({ model: 'jev-latest', state: a.text, questions }), signal: AbortSignal.timeout(65_000) });
+        const j = (await r.json().catch(() => ({})));
+        if (!r.ok)
+            throw new JevError(`TypeSafe answered ${r.status}${r.status === 401 || r.status === 403 ? ': the key was rejected' : r.status === 402 ? ': the account has no credit' : ''}`, r.status);
+        const answers = {};
+        for (const q of a.questions) {
+            const x = j.answers?.[q.id];
+            if (x)
+                answers[q.id] = norm(q.id, x);
+        }
+        return { answers, model: j.model ?? null, latency_ms: Date.now() - started, connection: 'key', trial: null };
+    }
+    const body = { state: a.text, questions: a.questions.map((q) => ({ id: q.id, kind: 'choice', text: q.text, options: [...q.options] })) };
+    const r = await f(a.trialUrl ?? TRIAL_URL, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(65_000) });
+    const j = (await r.json().catch(() => ({})));
+    if (!r.ok || j.ok === false)
+        throw new JevError(`the free trial answered ${r.status}: ${j.error ?? 'refused'}`, r.status, j.next ?? 'use your own TypeSafe key: grade({ key })');
+    const answers = {};
+    for (const x of j.answers ?? []) {
+        const id = String(x.id ?? '');
+        if (id && x.schema_ok !== false)
+            answers[id] = norm(id, x);
+    }
+    return { answers, model: j.upstreamModel ?? j.model ?? null, latency_ms: typeof j.latency_ms === 'number' ? j.latency_ms : Date.now() - started, connection: 'trial', trial: j.trial ? { calls: j.trial.calls, left: j.trial.left } : null };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,37 @@
+export declare const CONTRACTS: Readonly<{
+    /** the public devnet the logs live on: chain 36927, free gas; anyone may send */
+    readonly devnet: {
+        readonly chainId: 36927;
+        readonly rpc: "https://rpc.taifoon.dev";
+        /** JevAnswerLog: append-only, no owner. Recorders fixed at deploy are `trusted`; any other sender is logged with trusted = false */
+        readonly answerLog: {
+            readonly address: "0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3";
+            readonly fromBlock: 1106754;
+        };
+        /** JevDecisionLog: append-only, no owner, no upgrade; the recorder is msg.sender */
+        readonly decisionLog: {
+            readonly address: "0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05";
+            readonly fromBlock: 981099;
+        };
+        /** JudgeAdapter: posts a verdict (with the decision digest) to the devnet assurance hook */
+        readonly judgeAdapter: "0xbd4c9e797a8DBbfdde9C77bc5A5b21ACf611Db8f";
+        readonly assuranceHook: "0x7110c8951d17b69054395742e265bbd98259564a";
+    };
+    /** Base (8453). answerLog / decisionLog: null in this version → record({ network: 'base' }) returns the call data with `to: null` */
+    readonly base: {
+        readonly chainId: 8453;
+        readonly rpc: "https://mainnet.base.org";
+        readonly answerLog: {
+            address: string;
+            fromBlock: number;
+        } | null;
+        readonly decisionLog: {
+            address: string;
+            fromBlock: number;
+        } | null;
+        readonly virtualsErc8183: "0x238E541BfefD82238730D00a2208E5497F1832E0";
+        readonly virtualsMemoAcpRouter: "0xa6C9BA866992cfD7fd6460ba912bfa405adA9df0";
+        readonly bitagentErc8183: "0x5009ABB3A309115a4a682C66BAf3BC9E0329BaB7";
+        readonly bitagentEvaluator: "0x4302e523D982f3b89Cfc43cE4530C012b495Ec11";
+    };
+}>;

package/dist/contracts.js

@@ -0,0 +1,27 @@
+// Where the records and the evaluator seats live. Every address here was read from the chain or from its deploy
+// broadcast; nothing is deployed by this package.
+export const CONTRACTS = Object.freeze({
+    /** the public devnet the logs live on: chain 36927, free gas; anyone may send */
+    devnet: {
+        chainId: 36927,
+        rpc: 'https://rpc.taifoon.dev',
+        /** JevAnswerLog: append-only, no owner. Recorders fixed at deploy are `trusted`; any other sender is logged with trusted = false */
+        answerLog: { address: '0xD8c1d8188Fc8EE388792f6EB3B3dbd4f341Ba8e3', fromBlock: 1_106_754 },
+        /** JevDecisionLog: append-only, no owner, no upgrade; the recorder is msg.sender */
+        decisionLog: { address: '0x1D622511862DD7DEffB8fEeBc225E0FAdA1e9A05', fromBlock: 981_099 },
+        /** JudgeAdapter: posts a verdict (with the decision digest) to the devnet assurance hook */
+        judgeAdapter: '0xbd4c9e797a8DBbfdde9C77bc5A5b21ACf611Db8f',
+        assuranceHook: '0x7110c8951d17b69054395742e265bbd98259564a',
+    },
+    /** Base (8453). answerLog / decisionLog: null in this version → record({ network: 'base' }) returns the call data with `to: null` */
+    base: {
+        chainId: 8453,
+        rpc: 'https://mainnet.base.org',
+        answerLog: null,
+        decisionLog: null,
+        virtualsErc8183: '0x238E541BfefD82238730D00a2208E5497F1832E0',
+        virtualsMemoAcpRouter: '0xa6C9BA866992cfD7fd6460ba912bfa405adA9df0',
+        bitagentErc8183: '0x5009ABB3A309115a4a682C66BAf3BC9E0329BaB7',
+        bitagentEvaluator: '0x4302e523D982f3b89Cfc43cE4530C012b495Ec11',
+    },
+});

package/dist/evaluator/assurance-hook.d.ts

@@ -0,0 +1,6 @@
+import { type Adapter } from './types.js';
+export declare const ABI: {
+    readonly complete: "complete(bytes32)";
+    readonly reject: "reject(bytes32,bytes32)";
+};
+export declare const assuranceHook: Adapter;

package/dist/evaluator/assurance-hook.js

@@ -0,0 +1,15 @@
+// An assurance hook (the AssuranceHook family: Taifoon's, Moonbeam's on Base). The job's evaluator — or its buyer —
+// ends it: complete(jobId) pays the seller; reject(jobId, digest) walks every party back and records the digest.
+import { encodeCall } from '../abi.js';
+import { asBytes32, need } from './types.js';
+export const ABI = { complete: 'complete(bytes32)', reject: 'reject(bytes32,bytes32)' };
+export const assuranceHook = {
+    name: 'assurance-hook',
+    about: 'AssuranceHook: complete(jobId) or reject(jobId, digest); pass the hook address as opts.to',
+    call: (jobId, verdict, digest, o) => ({
+        protocol: 'assurance-hook', chainId: o.chainId ?? 8453, to: need(o.to, 'the hook address'), value: '0',
+        fn: verdict === 'complete' ? ABI.complete : ABI.reject,
+        data: verdict === 'complete' ? encodeCall(ABI.complete, [asBytes32(jobId)]) : encodeCall(ABI.reject, [asBytes32(jobId), digest]),
+        signer: 'the job’s buyer or an evaluator the hook registered',
+    }),
+};

package/dist/evaluator/bitagent-erc8183.d.ts

@@ -0,0 +1,7 @@
+import { type Adapter } from './types.js';
+export declare const ABI: {
+    readonly complete: "complete(uint256,bytes32,bytes)";
+    readonly reject: "reject(uint256,bytes32,bytes)";
+    readonly forceSettleJob: "forceSettleJob(uint256,bool)";
+};
+export declare const bitagentErc8183: Adapter;

package/dist/evaluator/bitagent-erc8183.js

@@ -0,0 +1,18 @@
+// BitAgent / Unibase ERC-8183 (AgenticCommerce on Base; implementation unverified, layout read from its transactions).
+//   seat "job" (default): you are the job's evaluator → AgenticCommerce complete / reject(jobId, digest, 0x), the same
+//     (uint256, bytes32, bytes) layout its submit uses.
+//   seat "platform": the platform Evaluator contract's forceSettleJob(jobId, approved) — what settles its jobs today;
+//     only BitAgent's operators may send it.
+import { encodeCall } from '../abi.js';
+import { CONTRACTS } from '../contracts.js';
+import { asUint } from './types.js';
+export const ABI = { complete: 'complete(uint256,bytes32,bytes)', reject: 'reject(uint256,bytes32,bytes)', forceSettleJob: 'forceSettleJob(uint256,bool)' };
+export const bitagentErc8183 = {
+    name: 'bitagent-erc8183',
+    about: 'BitAgent AgenticCommerce: complete / reject(jobId, digest, 0x) as evaluator; seat "platform" = Evaluator.forceSettleJob',
+    call: (jobId, verdict, digest, o) => o.seat === 'platform'
+        ? { protocol: 'bitagent-erc8183', chainId: o.chainId ?? CONTRACTS.base.chainId, to: o.to ?? CONTRACTS.base.bitagentEvaluator, value: '0', fn: ABI.forceSettleJob,
+            data: encodeCall(ABI.forceSettleJob, [asUint(jobId), verdict === 'complete']), signer: 'a BitAgent platform operator (the Evaluator contract’s own access control)' }
+        : { protocol: 'bitagent-erc8183', chainId: o.chainId ?? CONTRACTS.base.chainId, to: o.to ?? CONTRACTS.base.bitagentErc8183, value: '0', fn: ABI[verdict],
+            data: encodeCall(ABI[verdict], [asUint(jobId), digest, '0x']), signer: 'the address the job names as evaluator' },
+};

package/dist/evaluator/index.d.ts

@@ -0,0 +1,12 @@
+import type { Verdict } from '../rubric.js';
+import type { Adapter, AdapterOpts, EvaluatorCall } from './types.js';
+export declare const ADAPTERS: Readonly<Record<string, Adapter>>;
+export type Protocol = 'assurance-hook' | 'judge-adapter' | 'virtuals-erc8183' | 'virtuals-memo-acp' | 'bitagent-erc8183';
+export declare function evaluatorCall(protocol: Protocol | Adapter, jobId: string | number | bigint, verdict: Verdict | {
+    verdict: Verdict;
+}, digest: string | {
+    decision: {
+        digest: string;
+    } | null;
+}, opts?: AdapterOpts): EvaluatorCall | null;
+export type { Adapter, AdapterOpts, EvaluatorCall };

package/dist/evaluator/index.js

@@ -0,0 +1,20 @@
+import { assuranceHook } from './assurance-hook.js';
+import { bitagentErc8183 } from './bitagent-erc8183.js';
+import { judgeAdapter } from './judge-adapter.js';
+import { virtualsErc8183 } from './virtuals-erc8183.js';
+import { virtualsMemoAcp } from './virtuals-memo-acp.js';
+export const ADAPTERS = Object.freeze(Object.fromEntries([assuranceHook, judgeAdapter, virtualsErc8183, virtualsMemoAcp, bitagentErc8183].map((a) => [a.name, a])));
+export function evaluatorCall(protocol, jobId, verdict, digest, opts = {}) {
+    const a = typeof protocol === 'string' ? ADAPTERS[protocol] : protocol;
+    if (!a)
+        throw new Error(`unknown protocol ${String(protocol)}; one of ${Object.keys(ADAPTERS).join(', ')}`);
+    const v = typeof verdict === 'string' ? verdict : verdict.verdict;
+    if (v === 'needs_review')
+        return null;
+    if (v !== 'complete' && v !== 'reject')
+        throw new Error(`verdict is complete | reject | needs_review, got ${String(v)}`);
+    const d = typeof digest === 'string' ? digest : digest.decision?.digest;
+    if (!d || !/^0x[0-9a-fA-F]{64}$/.test(d))
+        throw new Error('digest: the decision digest (receipt.decision.digest), 32 bytes');
+    return a.call(jobId, v, d.toLowerCase(), opts);
+}

package/dist/evaluator/judge-adapter.d.ts

@@ -0,0 +1,5 @@
+import { type Adapter } from './types.js';
+export declare const ABI: {
+    readonly postVerdict: "postVerdict(bytes32,uint8,uint8,bytes32)";
+};
+export declare const judgeAdapter: Adapter;

package/dist/evaluator/judge-adapter.js

@@ -0,0 +1,16 @@
+// JudgeAdapter: the evaluator seat between a judge and an assurance hook. postVerdict(jobId, 1 Conformant | 2
+// NonConformant, mode 2 calibrated, digest) stores the verdict once per job and calls hook.complete / hook.reject in the
+// same transaction, so the adapter's VerdictPosted, the hook's event and the decision record carry one digest.
+import { encodeCall } from '../abi.js';
+import { CONTRACTS } from '../contracts.js';
+import { asBytes32 } from './types.js';
+export const ABI = { postVerdict: 'postVerdict(bytes32,uint8,uint8,bytes32)' };
+export const judgeAdapter = {
+    name: 'judge-adapter',
+    about: 'JudgeAdapter.postVerdict(jobId, 1|2, 2, digest) → hook.complete / hook.reject (devnet by default)',
+    call: (jobId, verdict, digest, o) => ({
+        protocol: 'judge-adapter', chainId: o.chainId ?? CONTRACTS.devnet.chainId, to: o.to ?? CONTRACTS.devnet.judgeAdapter, value: '0', fn: ABI.postVerdict,
+        data: encodeCall(ABI.postVerdict, [asBytes32(jobId), verdict === 'complete' ? 1 : 2, 2, digest]),
+        signer: 'an evaluator registered on the adapter (isEvaluator)',
+    }),
+};