@taifoon/jev 0.1.0

package/dist/evaluator/types.d.ts

@@ -0,0 +1,27 @@
+import type { Hex } from '../hash.js';
+export type EvaluatorVerdict = 'complete' | 'reject';
+export type EvaluatorCall = {
+    protocol: string;
+    chainId: number;
+    to: string;
+    data: Hex;
+    value: '0';
+    fn: string;
+    /** who must sign: the seat the protocol checks */
+    signer: string;
+};
+export type AdapterOpts = {
+    to?: string;
+    chainId?: number;
+    seat?: 'job' | 'platform';
+    reason?: string;
+};
+export type Adapter = {
+    name: string;
+    /** what it is, in a line */
+    about: string;
+    call: (jobId: string | number | bigint, verdict: EvaluatorVerdict, digest: Hex, opts: AdapterOpts) => EvaluatorCall;
+};
+export declare const need: (v: string | undefined, what: string) => string;
+export declare const asBytes32: (id: string | number | bigint) => Hex;
+export declare const asUint: (id: string | number | bigint) => bigint;

package/dist/evaluator/types.js

@@ -0,0 +1,6 @@
+export const need = (v, what) => { if (!v)
+    throw new Error(`${what} is required for this adapter (opts.to)`); return v; };
+export const asBytes32 = (id) => { const s = String(id); if (!/^0x[0-9a-fA-F]{64}$/.test(s))
+    throw new Error(`job id must be a 32-byte hex id here, got ${s.slice(0, 20)}`); return s.toLowerCase(); };
+export const asUint = (id) => { const n = BigInt(id); if (n < 0n)
+    throw new Error('job id must be ≥ 0'); return n; };

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

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

package/dist/evaluator/virtuals-erc8183.js

@@ -0,0 +1,15 @@
+// Virtuals ERC-8183 (AgenticCommerceV3 on Base). When the job names you as its evaluator you end it:
+// complete(jobId, reason, optParams) or reject(jobId, reason, optParams). `reason` is a bytes32 — the decision digest.
+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)' };
+export const virtualsErc8183 = {
+    name: 'virtuals-erc8183',
+    about: 'Virtuals AgenticCommerceV3: complete / reject(jobId, digest, 0x) as the job’s evaluator',
+    call: (jobId, verdict, digest, o) => ({
+        protocol: 'virtuals-erc8183', chainId: o.chainId ?? CONTRACTS.base.chainId, to: o.to ?? CONTRACTS.base.virtualsErc8183, value: '0', fn: ABI[verdict],
+        data: encodeCall(ABI[verdict], [asUint(jobId), digest, '0x']),
+        signer: 'the address the job names as evaluator',
+    }),
+};

package/dist/evaluator/virtuals-memo-acp.d.ts

@@ -0,0 +1,5 @@
+import { type Adapter } from './types.js';
+export declare const ABI: {
+    readonly signMemo: "signMemo(uint256,bool,string)";
+};
+export declare const virtualsMemoAcp: Adapter;

package/dist/evaluator/virtuals-memo-acp.js

@@ -0,0 +1,15 @@
+// Virtuals memo-ACP (ACPRouter on Base). The evaluator ends a job by signing its evaluation memo:
+// signMemo(memoId, isApproved, reason). Pass the memo id as the job id; the reason carries the verdict and the digest.
+import { encodeCall } from '../abi.js';
+import { CONTRACTS } from '../contracts.js';
+import { asUint } from './types.js';
+export const ABI = { signMemo: 'signMemo(uint256,bool,string)' };
+export const virtualsMemoAcp = {
+    name: 'virtuals-memo-acp',
+    about: 'Virtuals memo-ACP router: signMemo(memoId, approved, "jev <verdict> <digest>") on the evaluation memo',
+    call: (memoId, verdict, digest, o) => ({
+        protocol: 'virtuals-memo-acp', chainId: o.chainId ?? CONTRACTS.base.chainId, to: o.to ?? CONTRACTS.base.virtualsMemoAcpRouter, value: '0', fn: ABI.signMemo,
+        data: encodeCall(ABI.signMemo, [asUint(memoId), verdict === 'complete', o.reason ?? `jev ${verdict} ${digest}`]),
+        signer: 'the job’s evaluator (the memo’s counterparty)',
+    }),
+};

package/dist/facts.d.ts

@@ -0,0 +1,16 @@
+import type { Facts } from './rubric.js';
+export type Check = boolean | null | (() => boolean | null | Promise<boolean | null>);
+export type FactsInput = {
+    /** did anything come back / get submitted? false = hard fail */
+    delivered: boolean;
+    /** name → result, or name → a function that computes it; a function that throws counts as "could not be checked" */
+    checks?: Record<string, Check>;
+    /** the job's price in USDC; above the rubric's cap a "complete" is held for review */
+    priceUsdc?: number | null;
+    /** the class whose check ran and what it found, shown to Jev in the facts section */
+    det?: {
+        class: string;
+        why: string;
+    };
+};
+export declare function facts(input: FactsInput): Promise<Facts>;

package/dist/facts.js

@@ -0,0 +1,15 @@
+export async function facts(input) {
+    const checks = {};
+    for (const [name, c] of Object.entries(input.checks ?? {})) {
+        try {
+            const v = typeof c === 'function' ? await c() : c;
+            checks[name] = v === true ? true : v === false ? false : null;
+        }
+        catch {
+            checks[name] = null;
+        }
+    }
+    const vals = Object.values(checks);
+    const checksOk = vals.includes(false) ? false : vals.includes(true) ? true : null;
+    return { delivered: Boolean(input.delivered), checksOk, checks, priceUsdc: typeof input.priceUsdc === 'number' ? input.priceUsdc : null, ...(input.det ? { det: input.det } : {}) };
+}

package/dist/grade.d.ts

@@ -0,0 +1,32 @@
+import { type Receipt } from './receipt.js';
+import type { Subject } from './records.js';
+import type { Answer, Facts, Rubric, RubricInput } from './rubric.js';
+export type GradeInput = {
+    /** what is being graded: a job id / reference, or { chainId, at, ref } for an on-chain job */
+    subject: string | Subject;
+    /** the evidence pack: the task, the delivery, anything Jev should read. Objects are JSON-encoded. */
+    evidence: string | object;
+    /** facts() output (or a promise of it); default: delivered, no deterministic check */
+    facts?: Facts | Promise<Facts>;
+    /** default RUBRIC_v1; or your own { version, questions, asked?, thresholds?, compose? } */
+    rubric?: Rubric | RubricInput;
+    /** your own TypeSafe key → api.typesafe.ai. Never stored, never recorded. */
+    key?: string | null;
+    /** no key: the public trial (3 free calls). `true` or { url } */
+    trial?: boolean | {
+        url?: string;
+    };
+    /** answers you already have (e.g. from the n8n TypeSafe node): nothing is asked, the rest is identical */
+    answers?: Record<string, Answer> | Answer[];
+    /** the model that produced supplied answers, e.g. "jev-1.13.0" */
+    model?: string | null;
+    /** who is recording (jev.answer.v1 `caller`); default "sdk" */
+    caller?: string;
+    /** base URL for `key` (default https://api.typesafe.ai) */
+    endpoint?: string;
+    fetch?: typeof fetch;
+    /** ms since epoch for the answer record; default now */
+    at?: number;
+};
+export type { Receipt };
+export declare function grade(g: GradeInput): Promise<Receipt>;

package/dist/grade.js

@@ -0,0 +1,33 @@
+// grade(): evidence → deterministic facts → Jev's atomic questions → composed verdict → receipt.
+import { askJev, JevError, TRIAL_MAX_STATE } from './ask.js';
+import { answersOf, buildReceipt, DEFAULT_FACTS, inputFor, packOf, rubricOf } from './receipt.js';
+export async function grade(g) {
+    const rubric = rubricOf(g.rubric);
+    const facts = (await g.facts) ?? DEFAULT_FACTS;
+    const useTrial = Boolean(!g.key && !g.answers && g.trial);
+    const { state, jevState } = inputFor(packOf(g.evidence), facts, useTrial ? TRIAL_MAX_STATE : undefined);
+    // the facts decide first: a hard fail is final and Jev is never asked
+    let asked = null;
+    let answers = null;
+    let model = null;
+    let connection = 'none';
+    if (rubric.compose(facts, null).forced !== 'hard_fail') {
+        if (g.answers) {
+            answers = answersOf(g.answers);
+            model = g.model ?? null;
+            connection = 'supplied';
+        }
+        else {
+            if (!g.key && !g.trial)
+                throw new JevError('pass { key } (your TypeSafe key) or { trial: true } (3 free calls)', 400);
+            asked = await askJev({ text: jevState, questions: rubric.asked, key: g.key, trialUrl: typeof g.trial === 'object' ? g.trial.url : undefined, endpoint: g.endpoint, fetch: g.fetch });
+            const missing = rubric.asked.filter((q) => !asked.answers[q.id]).map((q) => q.id);
+            if (missing.length)
+                throw new JevError(`Jev returned no valid answer for: ${missing.join(', ')}`, 502);
+            answers = asked.answers;
+            model = asked.model;
+            connection = asked.connection;
+        }
+    }
+    return buildReceipt({ rubric, subject: g.subject, state, jevState, facts, answers, model, connection, latency_ms: asked?.latency_ms ?? null, trial: asked?.trial ?? null, caller: g.caller, at: g.at });
+}

package/dist/hash.d.ts

@@ -0,0 +1,10 @@
+export type Hex = `0x${string}`;
+export declare const utf8: (s: string) => Uint8Array;
+export declare const toHex: (b: Uint8Array) => Hex;
+export declare const fromHex: (h: string) => Uint8Array;
+export declare function sha256(data: Uint8Array): Uint8Array;
+/** sha256 of a UTF-8 string, as 0x-hex — the digest every Jev record uses */
+export declare const sha256Hex: (s: string) => Hex;
+export declare function keccak256(data: Uint8Array): Uint8Array;
+/** keccak256 of a UTF-8 string (or of raw bytes), as 0x-hex */
+export declare const keccakHex: (v: string | Uint8Array) => Hex;

package/dist/hash.js

@@ -0,0 +1,132 @@
+const enc = new TextEncoder();
+export const utf8 = (s) => enc.encode(s);
+export const toHex = (b) => {
+    let s = '0x';
+    for (let i = 0; i < b.length; i++)
+        s += (b[i] < 16 ? '0' : '') + b[i].toString(16);
+    return s;
+};
+export const fromHex = (h) => {
+    const s = h.startsWith('0x') ? h.slice(2) : h;
+    if (s.length % 2 || /[^0-9a-fA-F]/.test(s))
+        throw new Error(`not hex: ${h.slice(0, 20)}`);
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    return out;
+};
+// ── SHA-256 (FIPS 180-4) ──
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+export function sha256(data) {
+    const bitLen = data.length * 8;
+    const padded = new Uint8Array(((data.length + 9 + 63) >> 6) << 6);
+    padded.set(data);
+    padded[data.length] = 0x80;
+    const dv = new DataView(padded.buffer);
+    dv.setUint32(padded.length - 8, Math.floor(bitLen / 2 ** 32));
+    dv.setUint32(padded.length - 4, bitLen >>> 0);
+    const H = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const W = new Uint32Array(64);
+    const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++)
+            W[i] = dv.getUint32(off + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const a = W[i - 15], b = W[i - 2];
+            W[i] = (W[i - 16] + (rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3)) + W[i - 7] + (rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10))) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = [H[0], H[1], H[2], H[3], H[4], H[5], H[6], H[7]];
+        for (let i = 0; i < 64; i++) {
+            const t1 = (h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + W[i]) >>> 0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        H[0] = (H[0] + a) >>> 0;
+        H[1] = (H[1] + b) >>> 0;
+        H[2] = (H[2] + c) >>> 0;
+        H[3] = (H[3] + d) >>> 0;
+        H[4] = (H[4] + e) >>> 0;
+        H[5] = (H[5] + f) >>> 0;
+        H[6] = (H[6] + g) >>> 0;
+        H[7] = (H[7] + h) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const ov = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++)
+        ov.setUint32(i * 4, H[i]);
+    return out;
+}
+/** sha256 of a UTF-8 string, as 0x-hex — the digest every Jev record uses */
+export const sha256Hex = (s) => toHex(sha256(utf8(s)));
+// ── Keccak-256 (the Ethereum variant: pad 0x01) ──
+const RC = [
+    0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an, 0x8000000080008000n, 0x000000000000808bn, 0x0000000080000001n,
+    0x8000000080008081n, 0x8000000000008009n, 0x000000000000008an, 0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
+    0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n, 0x8000000000008002n, 0x8000000000000080n,
+    0x000000000000800an, 0x800000008000000an, 0x8000000080008081n, 0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n,
+];
+const ROT = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14];
+const M64 = (1n << 64n) - 1n;
+const rotl = (x, n) => (n === 0 ? x : ((x << BigInt(n)) | (x >> BigInt(64 - n))) & M64);
+function keccakF(s) {
+    const C = new Array(5), B = new Array(25);
+    for (let r = 0; r < 24; r++) {
+        for (let x = 0; x < 5; x++)
+            C[x] = s[x] ^ s[x + 5] ^ s[x + 10] ^ s[x + 15] ^ s[x + 20];
+        for (let x = 0; x < 5; x++) {
+            const d = C[(x + 4) % 5] ^ rotl(C[(x + 1) % 5], 1);
+            for (let y = 0; y < 25; y += 5)
+                s[x + y] = s[x + y] ^ d;
+        }
+        for (let x = 0; x < 5; x++)
+            for (let y = 0; y < 5; y++)
+                B[y + 5 * ((2 * x + 3 * y) % 5)] = rotl(s[x + 5 * y], ROT[x + 5 * y]);
+        for (let x = 0; x < 5; x++)
+            for (let y = 0; y < 25; y += 5)
+                s[x + y] = B[x + y] ^ (~B[((x + 1) % 5) + y] & M64 & B[((x + 2) % 5) + y]);
+        s[0] = s[0] ^ RC[r];
+    }
+}
+export function keccak256(data) {
+    const rate = 136;
+    const s = new Array(25).fill(0n);
+    const len = Math.floor(data.length / rate) * rate + rate;
+    const p = new Uint8Array(len);
+    p.set(data);
+    p[data.length] = 0x01;
+    p[len - 1] = p[len - 1] | 0x80;
+    for (let off = 0; off < len; off += rate) {
+        for (let i = 0; i < rate / 8; i++) {
+            let lane = 0n;
+            for (let b = 7; b >= 0; b--)
+                lane = (lane << 8n) | BigInt(p[off + i * 8 + b]);
+            s[i] = s[i] ^ lane;
+        }
+        keccakF(s);
+    }
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 4; i++) {
+        let lane = s[i];
+        for (let b = 0; b < 8; b++) {
+            out[i * 8 + b] = Number(lane & 0xffn);
+            lane >>= 8n;
+        }
+    }
+    return out;
+}
+/** keccak256 of a UTF-8 string (or of raw bytes), as 0x-hex */
+export const keccakHex = (v) => toHex(keccak256(typeof v === 'string' ? utf8(v) : v));

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @taifoon/jev — Jev as a grader any protocol can call.
+ *
+ *   grade()          evidence → deterministic facts → Jev's atomic questions → composed verdict → receipt
+ *   facts()          the deterministic checks a protocol supplies (a failed one is final; Jev is not asked)
+ *   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
+ *   RUBRIC_v1        the questions, thresholds and composition (pass your own rubric to grade)
+ *   CONTRACTS        where the logs and the evaluator seats are
+ *
+ * No runtime dependency. No key inside: the free trial, or your own TypeSafe key.
+ */
+export { grade } from './grade.js';
+export { facts } from './facts.js';
+export { record } from './record.js';
+export { evaluatorCall } from './evaluator/index.js';
+export { verify } from './verify.js';
+export { RUBRIC_v1 } from './rubric.js';
+export { CONTRACTS } from './contracts.js';
+export type { GradeInput, Receipt } from './grade.js';
+export type { FactsInput, Check } from './facts.js';
+export type { Recorded, UnsignedCall, Network } from './record.js';
+export type { Verification, AnswerEvent, DecisionEvent } from './verify.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';
+export type { Subject, AnswerRecord } from './records.js';
+export type { Hex } from './hash.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @taifoon/jev — Jev as a grader any protocol can call.
+ *
+ *   grade()          evidence → deterministic facts → Jev's atomic questions → composed verdict → receipt
+ *   facts()          the deterministic checks a protocol supplies (a failed one is final; Jev is not asked)
+ *   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
+ *   RUBRIC_v1        the questions, thresholds and composition (pass your own rubric to grade)
+ *   CONTRACTS        where the logs and the evaluator seats are
+ *
+ * No runtime dependency. No key inside: the free trial, or your own TypeSafe key.
+ */
+export { grade } from './grade.js';
+export { facts } from './facts.js';
+export { record } from './record.js';
+export { evaluatorCall } from './evaluator/index.js';
+export { verify } from './verify.js';
+export { RUBRIC_v1 } from './rubric.js';
+export { CONTRACTS } from './contracts.js';

package/dist/receipt.d.ts

@@ -0,0 +1,68 @@
+import { type Hex } from './hash.js';
+import { type AnswerRecord, type Subject } from './records.js';
+import { type Answer, type Facts, type ReceiptBody, type Rubric, type RubricInput } from './rubric.js';
+export type Connection = 'trial' | 'key' | 'supplied' | 'none';
+export type Receipt = ReceiptBody & {
+    v: 'jev.receipt.v1';
+    receiptHash: Hex;
+    /** the on-chain subject: JevDecisionLog.subjectOf(chainId, at, ref) */
+    chainSubject: Subject;
+    subjectId: Hex;
+    /** the exact text Jev read (evidence cut at the cap + the facts section + the instruction) and its sha256 */
+    input: string;
+    inputDigest: Hex;
+    decision: {
+        v: 'decision.v2';
+        kind: 'grade';
+        kindId: Hex;
+        digest: Hex;
+        confidenceBps: number;
+    } | null;
+    answersRecord: AnswerRecord | null;
+    answersDigest: Hex | null;
+    via: {
+        connection: Connection;
+        latency_ms: number | null;
+        trial: {
+            calls: number;
+            left: number;
+        } | null;
+    };
+};
+export declare const DEFAULT_FACTS: Facts;
+export declare const rubricOf: (r?: Rubric | RubricInput) => Rubric;
+export declare const packOf: (evidence: string | object) => string;
+/** the text Jev reads, cut until its JSON form fits `maxJson` characters (the trial's limit) — the facts section is never cut */
+export declare function inputFor(pack: string, facts: Facts, maxJson?: number): {
+    state: string;
+    jevState: string;
+};
+export declare function buildReceipt(a: {
+    rubric: Rubric;
+    subject: string | Subject;
+    state: string;
+    jevState: string;
+    facts: Facts;
+    answers: Record<string, Answer> | null;
+    model: string | null;
+    connection: Connection;
+    latency_ms?: number | null;
+    trial?: {
+        calls: number;
+        left: number;
+    } | null;
+    caller?: string;
+    at?: number;
+}): Receipt;
+/** answers as a map id → { id, value, confidence, probabilities } (key order fixed: it is hashed) */
+export declare function answersOf(list: Array<{
+    id: string;
+    value: unknown;
+    confidence?: unknown;
+    probabilities?: Record<string, number>;
+}> | Record<string, {
+    id?: string;
+    value: unknown;
+    confidence?: unknown;
+    probabilities?: Record<string, number>;
+}>): Record<string, Answer>;

package/dist/receipt.js

@@ -0,0 +1,42 @@
+// The receipt, built from what is already known — no network. grade() asks Jev and then calls this; the n8n node calls
+// it with the answers its own TypeSafe call returned.
+import { sha256Hex } from './hash.js';
+import { answerRecordOf, answersDigestOf, confidenceBpsOf, decisionAnswersOf, decisionDigest, kindIdOf, subjectIdOf, subjectOf } from './records.js';
+import { defineRubric, jevStateOf, receiptBody, receiptHashOf, RUBRIC_v1, STATE_CAP } from './rubric.js';
+export const DEFAULT_FACTS = Object.freeze({ delivered: true, checksOk: null, checks: {}, priceUsdc: null });
+export const rubricOf = (r) => (r ? defineRubric(r) : RUBRIC_v1);
+export const packOf = (evidence) => (typeof evidence === 'string' ? evidence : JSON.stringify(evidence));
+/** the text Jev reads, cut until its JSON form fits `maxJson` characters (the trial's limit) — the facts section is never cut */
+export function inputFor(pack, facts, maxJson) {
+    let cap = STATE_CAP;
+    let s = jevStateOf(pack, facts, cap);
+    while (maxJson && JSON.stringify(s.jevState).length > maxJson && cap > 200) {
+        cap -= 200;
+        s = jevStateOf(pack, facts, cap);
+    }
+    return s;
+}
+export function buildReceipt(a) {
+    const subject = subjectOf(a.subject);
+    const subjectId = subjectIdOf(subject);
+    const inputDigest = sha256Hex(a.jevState);
+    const composed = a.rubric.compose(a.facts, a.answers);
+    const body = receiptBody({ rubric: a.rubric, subject: subject.ref, state: a.state, facts: a.facts, answers: a.answers, model: a.model, composed });
+    let decision = null;
+    let answersRecord = null;
+    let answersDigest = null;
+    if (a.answers) {
+        const dA = decisionAnswersOf(a.answers, a.rubric.questions);
+        decision = { v: 'decision.v2', kind: 'grade', kindId: kindIdOf('grade'), digest: decisionDigest({ kind: 'grade', subject, answers: dA, model: a.model, input_digest: inputDigest }), confidenceBps: confidenceBpsOf(dA) };
+        answersRecord = answerRecordOf({ subjectId, inputDigest, answers: a.answers, questions: a.rubric.questions, model: a.model, latency_ms: a.latency_ms ?? null,
+            credential_path: a.connection === 'trial' ? 'trial' : 'caller-credential', use_case: a.connection === 'trial' ? 'compose' : 'compose.answers', caller: a.caller ?? 'sdk', at: a.at ?? Date.now() });
+        answersDigest = answersDigestOf(answersRecord);
+    }
+    return { v: 'jev.receipt.v1', ...body, receiptHash: receiptHashOf(body), chainSubject: subject, subjectId, input: a.jevState, inputDigest, decision, answersRecord, answersDigest,
+        via: { connection: a.connection, latency_ms: a.latency_ms ?? null, trial: a.trial ?? null } };
+}
+/** answers as a map id → { id, value, confidence, probabilities } (key order fixed: it is hashed) */
+export function answersOf(list) {
+    const arr = Array.isArray(list) ? list : Object.entries(list).map(([id, a]) => ({ ...a, id: a.id ?? id }));
+    return Object.fromEntries(arr.map((a) => [a.id, { id: a.id, value: String(a.value), confidence: Number(a.confidence), probabilities: a.probabilities ?? {} }]));
+}

package/dist/record.d.ts

@@ -0,0 +1,32 @@
+import { type Hex } from './hash.js';
+import type { Receipt } from './receipt.js';
+export type Network = 'none' | 'devnet' | 'base' | 'both';
+export type UnsignedCall = {
+    chainId: number;
+    to: string | null;
+    data: Hex;
+    value: '0';
+    fn: string;
+};
+export type Recorded = {
+    network: Network;
+    /** ready: every call has an address · partial: some have `to: null` · sent: `send` sent the addressed ones · none: nothing to send */
+    status: 'ready' | 'partial' | 'sent' | 'none';
+    calls: UnsignedCall[];
+    digests: {
+        answers: Hex;
+        decision: Hex;
+        input: Hex;
+        subject: Hex;
+        receipt: Hex;
+    };
+    notes: string[];
+    sent?: string[];
+};
+export declare const ANSWER_LOG_RECORD = "record(bytes32,bytes32,bytes32,bytes32,bytes32,string,string)";
+export declare const DECISION_LOG_RECORD = "record(bytes32,bytes32,bytes32,uint16,string,string)";
+export declare function record(r: Receipt, opts?: {
+    network?: Network;
+    uri?: string;
+    send?: (call: UnsignedCall) => Promise<string>;
+}): Promise<Recorded>;

package/dist/record.js

@@ -0,0 +1,41 @@
+// record(): the unsigned calls that put a receipt's digests on chain — JevAnswerLog.record (jev.answer.v1) and
+// JevDecisionLog.record (decision.v2). `network` is a flag: none | devnet | base | both. Nothing here signs: pass `send`
+// (your wallet, e.g. viem's walletClient.sendTransaction) to send the calls that have an address, or hand them on.
+import { encodeCall } from './abi.js';
+import { CONTRACTS } from './contracts.js';
+import { keccakHex } from './hash.js';
+export const ANSWER_LOG_RECORD = 'record(bytes32,bytes32,bytes32,bytes32,bytes32,string,string)';
+export const DECISION_LOG_RECORD = 'record(bytes32,bytes32,bytes32,uint16,string,string)';
+const TARGETS = {
+    devnet: () => ({ chainId: CONTRACTS.devnet.chainId, answerLog: CONTRACTS.devnet.answerLog.address, decisionLog: CONTRACTS.devnet.decisionLog.address,
+        note: 'devnet 36927: any account may send (gas from https://faucet.taifoon.dev). A sender outside JevAnswerLog’s deploy-time recorders is logged with trusted = false.' }),
+    base: () => ({ chainId: CONTRACTS.base.chainId, answerLog: CONTRACTS.base.answerLog?.address ?? null, decisionLog: CONTRACTS.base.decisionLog?.address ?? null,
+        note: CONTRACTS.base.answerLog && CONTRACTS.base.decisionLog ? 'Base 8453: the logs at CONTRACTS.base.' : 'Base 8453: this package version carries no Base address for the logs, so these calls have to = null (the call data is final; set `to` to send them).' }),
+};
+export async function record(r, opts = {}) {
+    if (!r.decision || !r.answersRecord || !r.answersDigest)
+        throw new Error(`nothing to record: Jev was not asked (${r.reasons[0] ?? r.verdict}) — a hard fail is decided by the facts alone`);
+    const network = opts.network ?? 'devnet';
+    const digests = { answers: r.answersDigest, decision: r.decision.digest, input: r.inputDigest, subject: r.subjectId, receipt: r.receiptHash };
+    if (network === 'none')
+        return { network, status: 'none', calls: [], digests, notes: ['network none: the receipt and its digests only'] };
+    const model = (r.answersRecord.upstream_model ?? r.answersRecord.model ?? 'jev').slice(0, 64);
+    const uri = (kind, d) => (opts.uri ? `${opts.uri.replace(/\/$/, '')}/${d}` : `urn:jev:${kind}:${d}`).slice(0, 512);
+    const answerData = encodeCall(ANSWER_LOG_RECORD, [keccakHex(r.answersRecord.use_case), r.subjectId, r.inputDigest, r.answersDigest, r.decision.digest, model, uri('answers', r.answersDigest)]);
+    const decisionData = encodeCall(DECISION_LOG_RECORD, [r.subjectId, r.decision.kindId, r.decision.digest, r.decision.confidenceBps, model, uri('decision', r.decision.digest)]);
+    const targets = (network === 'both' ? ['devnet', 'base'] : [network]).map((n) => TARGETS[n]());
+    const calls = targets.flatMap((t) => [
+        { chainId: t.chainId, to: t.answerLog, value: '0', fn: 'JevAnswerLog.record', data: answerData },
+        { chainId: t.chainId, to: t.decisionLog, value: '0', fn: 'JevDecisionLog.record', data: decisionData },
+    ]);
+    const out = { network, status: calls.every((c) => c.to) ? 'ready' : 'partial', calls, digests, notes: targets.map((t) => t.note) };
+    if (opts.send) {
+        out.sent = [];
+        for (const c of calls)
+            if (c.to)
+                out.sent.push(await opts.send(c));
+        if (out.sent.length)
+            out.status = 'sent';
+    }
+    return out;
+}

package/dist/records.d.ts

@@ -0,0 +1,78 @@
+import { type Hex } from './hash.js';
+import type { Answer, Question } from './rubric.js';
+export declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+export declare const ZERO_HASH: Hex;
+/** What a grade is about: a chain, an address (a job contract, a seller, zero when none) and a reference. */
+export type Subject = {
+    chainId: number;
+    at?: string | null;
+    ref: string;
+    label?: string | null;
+};
+export declare const subjectOf: (s: string | Subject) => Subject;
+/** a 32-byte hex passes through; anything else is keccak'd */
+export declare const refBytes32: (ref: string) => Hex;
+/** = JevDecisionLog.subjectOf(chainId, at, ref): keccak256(abi.encode("taifoon.decision.subject.v1", chainId, at, ref)) */
+export declare const subjectIdOf: (s: Subject) => Hex;
+export declare const kindIdOf: (kind: string) => Hex;
+export declare function canonicalize(v: unknown): unknown;
+export declare const canonicalJson: (v: unknown) => string;
+export type DecisionAnswer = {
+    id: string;
+    question: string | null;
+    options: readonly string[] | Record<string, string> | null;
+    value: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+};
+export type Decision = {
+    v: 'decision.v2';
+    kind: string;
+    subject: Subject;
+    answers: DecisionAnswer[];
+    model: string | null;
+    input_digest: Hex;
+};
+export declare function decisionDigest(d: Omit<Decision, 'v'>): Hex;
+/** a battery's on-chain confidence: its LOWEST answer, in basis points */
+export declare const confidenceBpsOf: (answers: Array<{
+    confidence: number;
+}>) => number;
+export declare const decisionAnswersOf: (answers: Record<string, Answer>, questions: readonly Question[]) => DecisionAnswer[];
+export type AnswerRecord = {
+    v: 'jev.answer.v1';
+    use_case: string;
+    subject: Hex;
+    input_digest: Hex | null;
+    questions: Array<{
+        id: string;
+        kind: 'choice';
+        text: string | null;
+        options: readonly string[] | null;
+    }>;
+    answers: Array<{
+        id: string;
+        value: string;
+        distribution: Record<string, number>;
+        confidence: number | null;
+    }>;
+    model: string | null;
+    upstream_model: string | null;
+    latency_ms: number | null;
+    credential_path: string;
+    caller: string;
+    at: number;
+};
+export declare const answersDigestOf: (r: AnswerRecord) => Hex;
+export declare function answerRecordOf(a: {
+    subjectId: Hex;
+    inputDigest: Hex;
+    answers: Record<string, Answer>;
+    questions: readonly Question[];
+    model: string | null;
+    latency_ms: number | null;
+    credential_path: string;
+    caller: string;
+    at: number;
+    use_case?: string;
+}): AnswerRecord;