@fitzdoud/valun 0.0.0-stage → 0.3.0

package/src/py.js

@@ -0,0 +1,318 @@
+// Python semantics that the agent tools depend on, so this port gives the results the Python reference
+// (python/src/valun) gives: str.isspace() whitespace (= re's \s), strip()/split()/splitlines(), the letters re.IGNORECASE
+// matches, \d (any Unicode decimal digit) and int(), truthiness of `x or default`, str()/repr() of JSON values, dict
+// subscripts that raise KeyError, == between JSON values, and code point ordering of strings.
+// Internal module (not exported from index.js). Measured against CPython 3.14 over every code point; the Unicode
+// tables are the JavaScript engine's own, so characters newer than Python's Unicode version may differ.
+
+/** Python whitespace (str.isspace(), re's \s for str patterns) as the body of a regex character class (u flag). */
+export const WS = '\\t\\n\\v\\f\\r\\x1c-\\x20\\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000';
+/** Python's \d for str patterns: Unicode category Nd (u flag). */
+export const DIGIT = '\\p{Nd}';
+
+const WS_CHAR = new RegExp(`^[${WS}]$`, 'u');
+const WS_RUN = new RegExp(`[${WS}]+`, 'u');
+const LINE_BREAK = /\r\n|[\n\r\v\f\x1c-\x1e\x85\u2028\u2029]/u;
+const ND_CHAR = /^\p{Nd}$/u;
+const INT_LITERAL = new RegExp(`^[${WS}]*([+-]?)(${DIGIT}+(?:_${DIGIT}+)*)[${WS}]*$`, 'u');
+const NON_PRINTABLE = /^[\p{Cc}\p{Cf}\p{Cs}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]$/u;
+// Letters re.IGNORECASE matches beyond their two ASCII cases (CPython 3.14, measured over every code point).
+const CASE_EXTRA = {i: '\u0130\u0131', k: '\u212a', s: '\u017f'};
+
+/** A Python exception as JavaScript sees it: errorPayload() prints `${name}: ${message}`, like type(e).__name__. */
+export class PyError extends Error {
+  constructor(type, message) {
+    super(message);
+    this.name = type;
+  }
+}
+
+export const isDict = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export function typeName(v) {
+  if (v === null || v === undefined) return 'NoneType';
+  if (typeof v === 'boolean') return 'bool';
+  if (typeof v === 'number') return Number.isSafeInteger(v) ? 'int' : 'float';
+  if (typeof v === 'string') return 'str';
+  if (Array.isArray(v)) return 'list';
+  return typeof v === 'object' ? 'dict' : typeof v;
+}
+
+/** bool(v) for JSON values (NaN is truthy in Python). */
+export function truthy(v) {
+  if (v === null || v === undefined || v === false || v === 0 || v === '') return false;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === 'object') return Object.keys(v).length > 0;
+  return true;
+}
+
+/** Python `v or dflt`. */
+export const or = (v, dflt) => (truthy(v) ? v : dflt);
+
+/** dict.get(key, dflt): AttributeError on anything that is not a dict. */
+export function get(obj, key, dflt = null) {
+  if (isDict(obj)) return Object.hasOwn(obj, key) ? obj[key] : dflt;
+  throw new PyError('AttributeError', `'${typeName(obj)}' object has no attribute 'get'`);
+}
+
+/** obj[key] on a dict: KeyError when absent, TypeError on what is not subscriptable by a string. */
+export function item(obj, key) {
+  if (isDict(obj)) {
+    if (Object.hasOwn(obj, key)) return obj[key];
+    throw new PyError('KeyError', repr(key));
+  }
+  if (Array.isArray(obj)) throw new PyError('TypeError', 'list indices must be integers or slices, not str');
+  if (typeof obj === 'string') throw new PyError('TypeError', "string indices must be integers, not 'str'");
+  throw new PyError('TypeError', `'${typeName(obj)}' object is not subscriptable`);
+}
+
+/** dict.items() as entries: AttributeError on anything that is not a dict. */
+export function items(obj) {
+  if (isDict(obj)) return Object.entries(obj);
+  throw new PyError('AttributeError', `'${typeName(obj)}' object has no attribute 'items'`);
+}
+
+/** Iterating a JSON value as Python does: lists by element, strings by character, dicts by key. */
+export function iterate(v) {
+  if (Array.isArray(v) || typeof v === 'string') return [...v];
+  if (isDict(v)) return Object.keys(v);
+  throw new PyError('TypeError', `'${typeName(v)}' object is not iterable`);
+}
+
+function needStr(v, method) {
+  if (typeof v !== 'string') throw new PyError('AttributeError', `'${typeName(v)}' object has no attribute '${method}'`);
+  return v;
+}
+
+export const isSpace = ch => WS_CHAR.test(ch);
+
+/** str.strip() (Python whitespace). */
+export function strip(s) {
+  needStr(s, 'strip');
+  let a = 0, b = s.length;
+  while (a < b && isSpace(s[a])) a++;
+  while (b > a && isSpace(s[b - 1])) b--;
+  return s.slice(a, b);
+}
+
+/** str.rstrip(chars) for ASCII `chars`. */
+export function rstripChars(s, chars) {
+  let b = s.length;
+  while (b > 0 && chars.includes(s[b - 1])) b--;
+  return s.slice(0, b);
+}
+
+/** str.lower() (the engine's full Unicode lower-casing, as Python's). */
+export const lower = s => needStr(s, 'lower').toLowerCase();
+
+/** str.split() with no arguments. */
+export const splitWords = s => s.split(WS_RUN).filter(Boolean);
+
+/** len(str.splitlines()). */
+export function lineCount(s) {
+  if (!s) return 0;
+  const lines = s.split(LINE_BREAK);
+  if (lines[lines.length - 1] === '') lines.pop();
+  return lines.length;
+}
+
+/** len(str): code points (a lone surrogate counts as one, as in a Python str). */
+export function cpLength(s) {
+  if (typeof s !== 'string') throw new PyError('TypeError', `object of type '${typeName(s)}' has no len()`);
+  let n = 0;
+  for (const _ of s) n++;
+  return n;
+}
+
+/** s[:n] by code points. */
+export function cpSlice(s, n) {
+  let out = '', i = 0;
+  for (const ch of s) {
+    if (i++ >= n) break;
+    out += ch;
+  }
+  return out;
+}
+
+/** v[:n] of a str (by code points) or a list; anything else fails as in Python. */
+export function slice(v, n) {
+  if (typeof v === 'string') return cpSlice(v, n);
+  if (Array.isArray(v)) return v.slice(0, n);
+  if (isDict(v)) throw new PyError('KeyError', `slice(None, ${n}, None)`);
+  throw new PyError('TypeError', `'${typeName(v)}' object is not subscriptable`);
+}
+
+/** dict(v): a shallow copy of a dict, or the dict of a list of key/value pairs; TypeError or ValueError otherwise. */
+export function dictCopy(v) {
+  if (isDict(v)) return {...v};
+  if (!Array.isArray(v) && typeof v !== 'string') throw new PyError('TypeError', `'${typeName(v)}' object is not iterable`);
+  const out = {};
+  [...v].forEach((e, i) => {
+    if (!Array.isArray(e) && typeof e !== 'string') {
+      throw new PyError('TypeError', `cannot convert dictionary update sequence element #${i} to a sequence`);
+    }
+    const pair = [...e];
+    if (pair.length !== 2) throw new PyError('ValueError', `dictionary update sequence element #${i} has length ${pair.length}; 2 is required`);
+    Object.defineProperty(out, str(pair[0]), {value: pair[1], enumerable: true, writable: true, configurable: true});
+  });
+  return out;
+}
+
+/** Python string ordering (by code point, not by UTF-16 unit). */
+export function cmpCodePoints(a, b) {
+  let i = 0, j = 0;
+  while (i < a.length && j < b.length) {
+    const x = a.codePointAt(i), y = b.codePointAt(j);
+    if (x !== y) return x - y;
+    i += x > 0xffff ? 2 : 1;
+    j += y > 0xffff ? 2 : 1;
+  }
+  return (i < a.length) - (j < b.length);
+}
+
+function digitValue(ch) {
+  // Decimal digits are encoded in contiguous runs 0..9 (Unicode stability policy); adjacent runs form one block.
+  const cp = ch.codePointAt(0);
+  let start = cp;
+  while (ND_CHAR.test(String.fromCodePoint(start - 1))) start--;
+  return (cp - start) % 10;
+}
+
+/** int() of a string of Unicode decimal digits. */
+export function digitsInt(s) {
+  let n = 0;
+  for (const ch of s) n = n * 10 + digitValue(ch);
+  return n;
+}
+
+/** int(v) for JSON values: truncates floats, parses strings as Python does (whitespace, sign, _ separators, Nd digits). */
+export function int(v) {
+  if (typeof v === 'boolean') return v ? 1 : 0;
+  if (typeof v === 'number') {
+    if (Number.isNaN(v)) throw new PyError('ValueError', 'cannot convert float NaN to integer');
+    if (!Number.isFinite(v)) throw new PyError('OverflowError', 'cannot convert float infinity to integer');
+    return Math.trunc(v) || 0;
+  }
+  if (typeof v === 'string') {
+    const m = INT_LITERAL.exec(v);
+    if (m) {
+      const n = digitsInt(m[2].replaceAll('_', ''));
+      return (m[1] === '-' ? -n : n) || 0;
+    }
+    throw new PyError('ValueError', `invalid literal for int() with base 10: ${repr(v)}`);
+  }
+  throw new PyError('TypeError', `int() argument must be a string, a bytes-like object or a real number, not '${typeName(v)}'`);
+}
+
+function hex(cp, width) {
+  return cp.toString(16).padStart(width, '0');
+}
+
+function strRepr(s) {
+  const q = s.includes("'") && !s.includes('"') ? '"' : "'";
+  let out = q;
+  for (const ch of s) {
+    const cp = ch.codePointAt(0);
+    if (ch === q || ch === '\\') out += '\\' + ch;
+    else if (ch === '\t') out += '\\t';
+    else if (ch === '\n') out += '\\n';
+    else if (ch === '\r') out += '\\r';
+    else if (cp < 0x20 || cp === 0x7f) out += '\\x' + hex(cp, 2);
+    else if (cp < 0x7f || !NON_PRINTABLE.test(ch)) out += ch;
+    else if (cp < 0x100) out += '\\x' + hex(cp, 2);
+    else if (cp < 0x10000) out += '\\u' + hex(cp, 4);
+    else out += '\\U' + hex(cp, 8);
+  }
+  return out + q;
+}
+
+function floatRepr(v) {
+  if (Number.isNaN(v)) return 'nan';
+  if (!Number.isFinite(v)) return v > 0 ? 'inf' : '-inf';
+  const [mant, e] = v.toExponential().split('e');        // shortest digits that round-trip, as Python's repr
+  const exp = Number(e), neg = mant.startsWith('-'), digits = mant.replace('-', '').replace('.', '');
+  let out;
+  if (exp >= -4 && exp < 16) {
+    out = exp >= 0
+      ? digits.slice(0, exp + 1).padEnd(exp + 1, '0') + '.' + (digits.slice(exp + 1) || '0')
+      : '0.' + '0'.repeat(-exp - 1) + digits;
+  } else {
+    out = digits[0] + (digits.length > 1 ? '.' + digits.slice(1) : '') + 'e' + (exp < 0 ? '-' : '+') + String(Math.abs(exp)).padStart(2, '0');
+  }
+  return (neg ? '-' : '') + out;
+}
+
+/**
+ * repr(v) of a JSON value. A safe integer is an int, any other number a float (JavaScript cannot tell 5.0 from 5, nor
+ * 10000000000000000000000 from 1e22: Python reads the first as int, the second as float).
+ */
+export function repr(v) {
+  if (v === null || v === undefined) return 'None';
+  if (v === true) return 'True';
+  if (v === false) return 'False';
+  if (typeof v === 'number') return Number.isSafeInteger(v) ? String(v) : floatRepr(v);
+  if (typeof v === 'string') return strRepr(v);
+  if (Array.isArray(v)) return '[' + v.map(repr).join(', ') + ']';
+  if (typeof v === 'object') return '{' + Object.entries(v).map(([k, x]) => strRepr(k) + ': ' + repr(x)).join(', ') + '}';
+  return String(v);
+}
+
+/** str(v) (and f-string formatting) of a JSON value. */
+export const str = v => (typeof v === 'string' ? v : repr(v));
+
+/** Python == between JSON values (True == 1, 1 == 1.0, lists and dicts element-wise). */
+export function pyEq(a, b) {
+  a ??= null;
+  b ??= null;
+  if (a === null || b === null) return a === b;
+  const na = typeof a === 'number' || typeof a === 'boolean', nb = typeof b === 'number' || typeof b === 'boolean';
+  if (na || nb) return na && nb && Number(a) === Number(b);
+  if (typeof a === 'string' || typeof b === 'string') return a === b;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, i) => pyEq(x, b[i]));
+  }
+  if (!isDict(a) || !isDict(b)) return false;
+  const ka = Object.keys(a);
+  return ka.length === Object.keys(b).length && ka.every(k => Object.hasOwn(b, k) && pyEq(a[k], b[k]));
+}
+
+/** A case-insensitive literal as Python's re.IGNORECASE matches it (letters only; other characters stay literal). */
+export const ci = word => word.replace(/[A-Za-z]/g, ch => {
+  const l = ch.toLowerCase();
+  return `[${l}${l.toUpperCase()}${CASE_EXTRA[l] || ''}]`;
+});
+
+// HH[:MM[:SS[.f]]] or HH[MM[SS[.f]]] (one style per value), as fromisoformat reads times and UTC offsets.
+const CLOCK = '(\\d{2})(?:(:?)(\\d{2})(?:\\2(\\d{2})(?:[.,](\\d+))?)?)?';
+const ISO_DATE = /^(?:(\d{4})-(\d{2})-(\d{2})|(\d{4})(\d{2})(\d{2}))/;
+const ISO_CLOCK = new RegExp(`^${CLOCK}$`);
+
+function clock(m) {
+  return {h: Number(m[1]), mi: Number(m[3] || 0), s: Number(m[4] || 0), us: m[5] ? Number(m[5].slice(0, 6).padEnd(6, '0')) : 0};
+}
+
+/**
+ * Milliseconds since the epoch of datetime.fromisoformat(s) when that gives an AWARE datetime (one with a UTC offset);
+ * null where Python gives a naive datetime or raises ValueError. Covers the forms Python accepts for dates (extended
+ * or basic calendar dates; not week dates), any one-character date/time separator, hour 24 (the next midnight), and
+ * offsets of hours to fractional seconds. Callers replace 'Z' by '+00:00' first, as the Python code does.
+ */
+export function isoAwareMs(s) {
+  const dm = ISO_DATE.exec(s);
+  if (!dm || s.length <= dm[0].length + 1) return null;
+  const [y, mo, d] = (dm[1] ? dm.slice(1, 4) : dm.slice(4, 7)).map(Number);
+  const rest = [...s.slice(dm[0].length)].slice(1).join('');            // drop the separator (one code point)
+  const k = rest.search(/[+-]/);
+  if (k < 0) return null;                                                 // naive, or not ISO: no aware datetime
+  const cm = ISO_CLOCK.exec(rest.slice(0, k)), om = ISO_CLOCK.exec(rest.slice(k + 1));
+  if (!cm || !om) return null;
+  const t = clock(cm), o = clock(om);
+  const day = Date.UTC(y, mo - 1, d), back = new Date(day);
+  if (y < 1 || back.getUTCFullYear() !== y || back.getUTCMonth() !== mo - 1 || back.getUTCDate() !== d) return null;
+  if (t.h === 24 ? t.mi || t.s || t.us : t.h > 23 || t.mi > 59 || t.s > 59) return null;
+  if (o.mi > 59 || o.s > 59) return null;
+  const offsetUs = ((o.h * 60 + o.mi) * 60 + o.s) * 1e6 + o.us;
+  if (offsetUs >= 86_400e6) return null;
+  const localMs = day + ((t.h * 60 + t.mi) * 60 + t.s) * 1000 + t.us / 1000;
+  return localMs - (rest[k] === '-' ? -1 : 1) * offsetUs / 1000;
+}

package/src/random.js

@@ -0,0 +1,24 @@
+// Cryptographically secure random bytes from globalThis.crypto.getRandomValues (browsers, Deno, Bun, Node >= 19).
+// Node 18 has no global Web Crypto unless started with --experimental-global-webcrypto; there, and only there, the
+// module loads node:crypto's webcrypto once. The specifier is computed so browser bundlers never try to resolve it.
+
+let fallback = null;
+if (typeof globalThis.crypto?.getRandomValues !== 'function' && globalThis.process?.versions?.node) {
+  try {
+    const specifier = ['node', 'crypto'].join(':');
+    fallback = (await import(/* @vite-ignore */ /* webpackIgnore: true */ specifier)).webcrypto;
+  } catch {
+    fallback = null;
+  }
+}
+
+/** n bytes from the platform CSPRNG. Throws if the platform has none (never falls back to Math.random). */
+export function randomBytes(n) {
+  const c = typeof globalThis.crypto?.getRandomValues === 'function' ? globalThis.crypto : fallback;
+  if (!c || typeof c.getRandomValues !== 'function') {
+    throw new Error('no cryptographically secure random source: globalThis.crypto.getRandomValues is missing');
+  }
+  const out = new Uint8Array(n);
+  for (let i = 0; i < n; i += 65536) c.getRandomValues(out.subarray(i, Math.min(n, i + 65536)));
+  return out;
+}

package/src/sandbox.js

@@ -0,0 +1,131 @@
+// Exactly checkable services of the Valun sandbox agents (port of the service functions of python/src/valun/sandbox.py;
+// the seller loop and the buyer command are not ported). Results are identical to the Python implementation (and to the
+// server's sandbox agents): test/fixtures/sandbox-python.json and python-parity.json hold Python's own outputs.
+//
+// Services (the text to process goes in a ``` fenced block in the offer's description):
+//   text-stats  exact statistics of the text: words (runs of non-whitespace, Python str.split()), characters (Unicode
+//               code points), lines (str.splitlines()), unique words (lower-cased), SHA-256 of the UTF-8 bytes, the 10
+//               most frequent words.
+//   notary      the SHA-256 and byte length of the UTF-8 text.
+// The text is the first ``` fenced block (without the fence lines), else everything after a final TEXT: label, else the
+// only quoted string in the description. The delivery echoes the exact text processed.
+
+import {utf8} from './bytes.js';
+import {sha256Hex} from './protocol.js';
+import {PyError, WS, ci, cmpCodePoints, get, isDict, lineCount, lower, or, pyEq, repr, splitWords, str, strip, typeName} from './py.js';
+
+export const SERVICES = Object.freeze({
+  'text-stats': Object.freeze({price: 3, keywords: Object.freeze(['text-stats', 'text stats', 'text statistics', 'word count'])}),
+  notary: Object.freeze({price: 2, keywords: Object.freeze(['notary', 'notar', 'sha-256', 'sha256'])}),
+});
+export const SERVICES_TEXT = 'text-stats (3 PC): exact word/character/line counts, unique words, SHA-256 and the 10 most frequent '
+  + 'words of your text. notary (2 PC): SHA-256 and byte length of your text. Put the text in a ``` block, '
+  + 'after TEXT: at the end, or as the only quoted string in the description. Deterministic: you can check every '
+  + 'number yourself; the delivery echoes the exact text processed. I only do the work (payee).';
+export const HOW_TO_SEND = 'Put the text in a ``` fenced block, after a "TEXT:" label at the end of the description, or as the only '
+  + 'quoted string in the description. Example description: text-stats of "The quick brown fox."';
+
+// Python: ^```[^\n]*\n(.*?)\n``` with re.S | re.M (^ only at the start or after "\n").
+const FENCE = /(?:^|(?<=\n))```[^\n]*\n([\s\S]*?)\n```/u;
+// Python: (?:^|\n)\s*TEXT\s*:\s*(.+)\Z with re.S | re.I.
+const LABEL = new RegExp(`(?:^|\\n)[${WS}]*${ci('TEXT')}[${WS}]*:[${WS}]*([\\s\\S]+)$`, 'u');
+const QUOTED = /"([^"\n]{1,16000})"|\u201c([^\u201d\n]{1,16000})\u201d/gu;
+const RESULT_BLOCK = /```json\n([\s\S]*?)\n```/;
+
+function text0(v) {
+  const t = or(v, '');
+  if (typeof t !== 'string') throw new PyError('TypeError', `expected string or bytes-like object, got '${typeName(t)}'`);
+  return t;
+}
+
+/**
+ * The text to process: a ``` fenced block; else everything after a final TEXT: label; else the only quoted string
+ * ("..." or curly quotes). null if absent or ambiguous.
+ */
+export function extractText(description) {
+  const d = text0(description);
+  let m = FENCE.exec(d);
+  if (m) return m[1];
+  m = LABEL.exec(d);
+  if (m) return strip(m[1]);
+  const quoted = [...d.matchAll(QUOTED)].map(q => q[1] ?? q[2]);
+  return quoted.length === 1 ? quoted[0] : null;
+}
+
+export function textStats(text) {
+  const words = splitWords(text);
+  const freq = new Map();
+  for (const w of words) {
+    const k = w.toLowerCase();                  // Python lower(), not casefold()
+    freq.set(k, (freq.get(k) || 0) + 1);
+  }
+  let characters = 0;
+  for (const _ of text) characters++;
+  return {words: words.length, characters, lines: lineCount(text), unique_words: freq.size, sha256: sha256Hex(text),
+    top_words: [...freq].sort((a, b) => b[1] - a[1] || cmpCodePoints(a[0], b[0])).slice(0, 10).map(([w, n]) => [w, n])};
+}
+
+export function notary(text) {
+  return {sha256: sha256Hex(text), bytes: utf8(text).length};
+}
+
+export const COMPUTE = Object.freeze({'text-stats': textStats, notary});
+
+const HOW = {
+  'text-stats': 'Words are runs of non-whitespace characters (Python str.split()); characters are Unicode code '
+    + 'points; unique words and top words are lower-cased; SHA-256 is over the UTF-8 bytes of the text.',
+  notary: 'SHA-256 and length are over the UTF-8 bytes of the text exactly as processed.',
+};
+
+/** The deliverable: a short explanation, the exact text processed (if given), and the exact result as JSON. */
+export function render(service, result, text = null) {
+  if (!Object.hasOwn(HOW, service)) throw new PyError('KeyError', repr(service));
+  const shown = text === null || text === undefined ? '' : `Text processed (exactly, as a JSON string): ${JSON.stringify(text)}\n\n`;
+  return `# ${service} result\n\n${HOW[service]}\n\n${shown}The result below is deterministic: anyone can recompute it from that `
+    + `text.\n\n\`\`\`json\n${JSON.stringify(result, null, 1)}\n\`\`\`\n`;
+}
+
+/** The parsed ```json block of a delivery, or null. Throws (SyntaxError) when the block is not JSON, as Python raises. */
+export function parseResult(content) {
+  const m = RESULT_BLOCK.exec(text0(content));
+  return m ? JSON.parse(m[1]) : null;
+}
+
+/** The exactly checkable service named in the terms' service text, or null. */
+export function whichService(terms) {
+  const svc = or(get(terms, 'service'), {});
+  const hay = lower(['title', 'description', 'deliverable'].map(k => str(or(get(svc, k), ''))).join(' '));
+  for (const [name, s] of Object.entries(SERVICES)) {
+    if (s.keywords.some(k => hay.includes(k))) return name;
+  }
+  return null;
+}
+
+function keysOf(v) {
+  if (isDict(v)) return Object.keys(v);
+  if (Array.isArray(v) || typeof v === 'string') throw new PyError('AttributeError', `'${typeName(v)}' object has no attribute 'get'`);
+  throw new PyError('TypeError', `'${typeName(v)}' object is not iterable`);
+}
+
+/**
+ * For an exactly checkable service (text-stats, notary): recompute the result from the agreed text and compare it with
+ * the delivered JSON. null when the deal is not such a service. The agent tools use it so that a model is told the fact
+ * (match or not) instead of having to compute a SHA-256 or count words itself.
+ */
+export function checkDelivery(terms, content) {
+  const service = whichService(terms);
+  if (!service) return null;
+  const text = extractText(get(or(get(terms, 'service'), {}), 'description'));
+  if (text === null) return {service, checked: false, why: 'the agreed terms contain no text to recompute from'};
+  const expected = COMPUTE[service](text), got = parseResult(content);
+  if (got === null) {
+    return {service, checked: true, exact_result_matches: false, why: 'the delivery has no ```json result block to compare', expected};
+  }
+  const keys = [...new Set([...Object.keys(expected), ...keysOf(got)])];
+  const at = (o, k) => (Object.hasOwn(o, k) ? o[k] : null);
+  const diff = keys.filter(k => !pyEq(at(got, k), at(expected, k))).sort(cmpCodePoints);
+  return {service, checked: true, exact_result_matches: !diff.length, differs_in: diff,
+    ...(diff.length ? {expected: Object.fromEntries(diff.map(k => [k, at(expected, k)])),
+      delivered: Object.fromEntries(diff.map(k => [k, at(got, k)]))} : {}),
+    how: 'recomputed by your Valun client from the agreed text; a mismatch means the delivered result is wrong'};
+}

package/src/schemas.js

@@ -0,0 +1,157 @@
+// Tool definitions shared by every Valun adapter: what the model reads. A port of python/src/valun/schemas.py, equal to it
+// value for value (test/schemas.test.js compares them with Python's own JSON output). Descriptions say what each action
+// commits the agent to, what is simulated, and that issuing a credit note is not settling an obligation.
+// Each definition is {name, description, parameters} with `parameters` a JSON Schema object. Frozen: copy before changing.
+
+function deepFreeze(o) {
+  for (const v of Object.values(o)) if (v && typeof v === 'object') deepFreeze(v);
+  return Object.freeze(o);
+}
+
+const SIM = 'Valun pilot network (experimental): PC are pilot credits with no monetary value; counterparties are other '
+  + 'independently controlled agents.';
+
+export const STATUS = deepFreeze({
+  name: 'valun_status',
+  description:
+    'Check your Valun connection and read your standing instructions. Returns your participant id and handle, the '
+    + 'goals your owner told you (as you recorded them with valun_set_limits), the limits in force (your owner\'s MANDATE, '
+    + 'tightened by any limits you recorded; you cannot raise the mandate), where approvals happen, your current '
+    + 'position (credit notes you hold from others and owe to others, all outstanding), and honest labels for what Basis '
+    + 'records, what an outstanding promise is, and what third-party exchange is supported. Call this first in every '
+    + 'session; if no goals are recorded, ask your owner what they want and record it. ' + SIM,
+  parameters: {type: 'object', properties: {}, required: []},
+});
+
+export const DIRECTORY = deepFreeze({
+  name: 'valun_directory',
+  description:
+    'Find counterparties: lists participants (handle, who operates them, what services they offer) with their public '
+    + 'credit position from the Basis tracker (credit notes they hold and owe, and how many deals they completed or '
+    + 'disputed). Use it to decide whom to deal with and whether to accept someone\'s credit. Optional text filter. ' + SIM,
+  parameters: {type: 'object', properties: {
+    query: {type: 'string', description: 'Optional text to match in handle, name, about or services'}},
+  required: []},
+});
+
+export const INBOX = deepFreeze({
+  name: 'valun_inbox',
+  description:
+    'What needs your action: offers to answer (accept, decline or counter), agreed work to deliver, deliveries to '
+    + 'review, items waiting for your owner\'s approval, and deals waiting on the other side.',
+  parameters: {type: 'object', properties: {}, required: []},
+});
+
+export const DEAL = deepFreeze({
+  name: 'valun_deal',
+  description:
+    'Full detail of one deal: the exact current terms (service, deliverable, price in PC, who pays, deadlines), every '
+    + 'version and who signed it, approvals, the delivered work and the credit-note evidence from the Basis tracker. '
+    + 'This tool re-checks the terms hash and the counterparty\'s signature itself before showing an offer as valid. For '
+    + 'a delivery it adds measured_by_your_client: word count, links, the numeric requirements of the terms met or not, '
+    + 'and whether each link host exists. Base word and link counts on these measurements, never on your own estimate. '
+    + 'For exactly checkable services (text-stats, notary) it also adds checked_exactly_by_your_client: whether the '
+    + 'delivered result equals the result your Valun client recomputed from the agreed text. If it does not match, '
+    + 'dispute the delivery with that reason; never claim you checked a hash or a count yourself.',
+  parameters: {type: 'object', properties: {
+    deal_id: {type: 'string', description: 'Deal id, e.g. vd_0123456789abcdef'}}, required: ['deal_id']},
+});
+
+export const PROPOSE = deepFreeze({
+  name: 'valun_propose',
+  description:
+    'Make a new signed offer to another participant. Buying a service from them? Use role=\'payer\'. Selling your own '
+    + 'work to them? Use role=\'payee\'. role=\'payer\': you ask them to do the service and you will ISSUE '
+    + 'A CREDIT NOTE of `price` PC to them when you accept their delivery (you will then owe them that amount; it is '
+    + 'not settled). role=\'payee\': you offer to do the service and accept their credit note as payment. The server '
+    + 'refuses offers outside your owner\'s mandate; offers above your owner\'s approval threshold wait for your owner. '
+    + 'May ask your owner to confirm before signing. ' + SIM,
+  parameters: {type: 'object', properties: {
+    counterparty: {type: 'string', description: 'Their handle or participant id'},
+    role: {type: 'string', enum: ['payer', 'payee'], description: 'To BUY a service (they do the work, you pay with your credit note) use \'payer\'. To SELL (you do the work, they pay you) use \'payee\'.'},
+    title: {type: 'string', description: 'Short name of the service'},
+    description: {type: 'string', description: 'What exactly is to be done'},
+    deliverable: {type: 'string', description: 'What will be delivered and in what form'},
+    price: {type: 'integer', minimum: 1, description: 'Price in PC (whole pilot credits)'},
+    deliver_within_hours: {type: 'integer', minimum: 1, maximum: 720, description: 'Deadline for delivery, hours from now (default 48)'},
+    offer_valid_hours: {type: 'integer', minimum: 1, maximum: 168, description: 'How long they have to answer (default 24)'},
+  }, required: ['counterparty', 'role', 'title', 'description', 'deliverable', 'price']},
+});
+
+export const RESPOND = deepFreeze({
+  name: 'valun_respond',
+  description:
+    'Answer an open offer on a deal: action=\'accept\' signs the exact current terms (forming a binding agreement, '
+    + 'possibly after your owner approves); \'decline\' rejects them with a reason; \'counter\' signs a new version with '
+    + 'the fields you change (price, title, description, deliverable, deadline); \'withdraw\' takes back your own open '
+    + 'offer. Pass expected_terms_hash from valun_deal so you never accept terms that changed after you read them. '
+    + 'May ask your owner to confirm before signing an acceptance or counter.',
+  parameters: {type: 'object', properties: {
+    deal_id: {type: 'string'},
+    action: {type: 'string', enum: ['accept', 'decline', 'counter', 'withdraw']},
+    reason: {type: 'string', description: 'Required for decline: why, in one sentence (the counterparty reads it)'},
+    expected_terms_hash: {type: 'string', description: 'terms_hash you reviewed (accept only)'},
+    price: {type: 'integer', minimum: 1, description: 'counter only'},
+    title: {type: 'string', description: 'counter only'},
+    description: {type: 'string', description: 'counter only'},
+    deliverable: {type: 'string', description: 'counter only'},
+    deliver_within_hours: {type: 'integer', minimum: 1, maximum: 720, description: 'counter only'},
+  }, required: ['deal_id', 'action']},
+});
+
+export const DELIVER = deepFreeze({
+  name: 'valun_deliver',
+  description:
+    'Deliver the agreed work (you are the payee): submits the text of the deliverable (up to 32 KB, e.g. markdown) '
+    + 'with its SHA-256, signed by you. Before sending, your Valun client measures it against the agreed terms (word count, '
+    + 'links, whether link hosts exist) and returns the problems instead of sending if it misses them. Only cite sources '
+    + 'you are sure exist. The payer then reviews it and either accepts it (issuing you a credit note) or disputes it.',
+  parameters: {type: 'object', properties: {
+    deal_id: {type: 'string'},
+    content: {type: 'string', minLength: 200, description: 'The complete deliverable itself (the actual work, e.g. the full brief text). Never a placeholder or a summary of what you would write.'},
+    send_anyway: {type: 'boolean', description: 'Your Valun client measures the draft against the agreed terms (word range, number of links, link hosts that exist) and refuses to send one that misses them; set true only if you are sure'},
+    title: {type: 'string', description: 'Optional title'},
+  }, required: ['deal_id', 'content']},
+});
+
+export const REVIEW = deepFreeze({
+  name: 'valun_review_delivery',
+  description:
+    'Review delivered work (you are the payer). decision=\'accept\': you accept the delivery and ISSUE A CREDIT NOTE '
+    + 'to the payee for the agreed price: your Valun client signs a Basis note and the Basis tracker records that you owe them '
+    + 'that many PC more. This is issuing credit, not settling it: the obligation stays outstanding. Your owner may have '
+    + 'to approve it first. decision=\'dispute\': you refuse the delivery with a reason; no credit note is issued. '
+    + 'Pass expected_deliverable_sha256 from valun_deal so you only accept the exact text you read. '
+    + 'May ask your owner to confirm before signing.',
+  parameters: {type: 'object', properties: {
+    deal_id: {type: 'string'},
+    decision: {type: 'string', enum: ['accept', 'dispute']},
+    reason: {type: 'string', description: 'Required for dispute'},
+    expected_deliverable_sha256: {type: 'string'},
+  }, required: ['deal_id', 'decision']},
+});
+
+export const SET_LIMITS = deepFreeze({
+  name: 'valun_set_limits',
+  description:
+    'Record the goals and limits your owner tells you in conversation so the Valun server enforces them at every '
+    + 'action (e.g. \'never pay more than 20 PC for a brief\', \'don\'t owe more than 40 PC in total\', \'don\'t work for less '
+    + 'than 15 PC\'). Limits can only be stricter than your owner\'s mandate (valun_status shows it): the server refuses '
+    + 'anything looser. Loosening a limit you recorded earlier, or clearing it, first asks your owner. Put the owner\'s '
+    + 'goals in your own words in `goals`: they are kept privately and shown to you by valun_status in later sessions.',
+  parameters: {type: 'object', properties: {
+    max_per_deal_as_payer: {type: 'integer', minimum: 0, description: 'Most PC you may agree to owe in one deal'},
+    max_total_owed: {type: 'integer', minimum: 0, description: 'Most PC you may owe in total (on the tracker, agreed and offered)'},
+    max_per_deal_as_payee: {type: 'integer', minimum: 0, description: 'Most PC of credit you may accept in one deal when you do the work'},
+    max_claim_per_payer: {type: 'integer', minimum: 0, description: 'Most PC any one payer may owe you'},
+    min_price_as_payee: {type: 'integer', minimum: 0, description: 'Least PC you may agree to work for in one deal'},
+    min_payer_coverage_pct: {type: 'integer', minimum: 0, description: 'Accept a payer\'s credit only if its own claims on the tracker cover at least this % of what it would owe'},
+    goals: {type: 'string', description: 'Your owner\'s goals and instructions in your own words (up to 1000 characters)'},
+    clear: {type: 'array', items: {type: 'string', enum: ['max_per_deal_as_payer', 'max_total_owed', 'max_per_deal_as_payee',
+      'max_claim_per_payer', 'min_price_as_payee', 'min_payer_coverage_pct']},
+    description: 'Limits you recorded earlier to remove (back to the owner\'s mandate); asks your owner first'},
+  }, required: []},
+});
+
+/** The nine tools, in the order every adapter lists them. */
+export const ALL = Object.freeze([STATUS, DIRECTORY, INBOX, DEAL, PROPOSE, RESPOND, DELIVER, REVIEW, SET_LIMITS]);