@oracle-agent/oracle 0.13.1 → 0.14.1

package/scripts/verify-dist.mjs

@@ -0,0 +1,29 @@
+// Smoke-test the bundled dist against the real package surface.
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
+const rows = [];
+
+for (const [name, target] of Object.entries(pkg.exports || {})) {
+  if (typeof target !== "string" || !target.startsWith("./src/")) continue;
+  const distPath = "../dist/" + target.replace(/^\.\/src\//, "");
+  try {
+    const srcMod = await import(new URL(target.replace("./", "../"), import.meta.url).href);
+    const dstMod = await import(new URL(distPath, import.meta.url).href);
+    const s = Object.keys(srcMod).sort();
+    const d = Object.keys(dstMod).sort();
+    const missing = s.filter((k) => !d.includes(k));
+    rows.push({ name, src: s.length, dist: d.length, missing });
+  } catch (e) {
+    rows.push({ name, error: String(e.message).slice(0, 80) });
+  }
+}
+
+let bad = 0;
+for (const r of rows) {
+  if (r.error) { bad++; console.log(`  FAIL ${r.name.padEnd(20)} ${r.error}`); continue; }
+  if (r.missing.length) { bad++; console.log(`  FAIL ${r.name.padEnd(20)} missing: ${r.missing.join(",")}`); continue; }
+  console.log(`  OK   ${r.name.padEnd(20)} ${r.dist} exports match`);
+}
+console.log(`\n${rows.length} entry points, ${bad} broken`);
+process.exitCode = bad ? 1 : 0;

package/scripts/verify-v3-venues.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Functionally verify Uniswap V3 venue addresses on every chain.
+//
+// Codesize alone is NOT verification -- an unrelated contract also has bytecode, and
+// on Base the canonical mainnet addresses returned 2109 bytes for two different
+// contracts, which is exactly the kind of false positive a size check waves through.
+//
+// The real test is behavioural: ask the candidate quoter to price a pair we already
+// know the answer to. A contract that returns a sane WETH->USDC quote at a standard
+// fee tier IS a working V3 quoter, regardless of what any doc claims.
+//
+// Output is a provenance record per chain, ready to paste into chains.config.mjs.
+
+import { rpcCall } from "../src/data/providers/evm-rpc.mjs";
+
+// Candidates. Most chains share the canonical deployment; Base, BSC and Avalanche
+// have their own. All of these are CANDIDATES until the probe passes.
+const CANONICAL_QUOTER = "0x61fFE014bA17989E743c5F6cB21bF9697530B21e";
+const CANONICAL_ROUTER = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45";
+
+const CANDIDATES = {
+  1: {
+    name: "ethereum",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+    tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+    decIn: 18,
+    decOut: 6,
+  },
+  10: {
+    name: "optimism",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x4200000000000000000000000000000000000006",
+    tokenOut: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+    decIn: 18,
+    decOut: 6,
+  },
+  56: {
+    name: "bsc",
+    quoter: "0x78D78E420Da98ad378D7799bE8f4AF69033EB077",
+    router: "0xB971eF87ede563556b2ED4b1C0b0019111Dd85d2",
+    tokenIn: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c", // WBNB
+    tokenOut: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", // USDC (18dp on BSC)
+    decIn: 18,
+    decOut: 18,
+  },
+  137: {
+    name: "polygon",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270", // WMATIC
+    tokenOut: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC native
+    decIn: 18,
+    decOut: 6,
+  },
+  8453: {
+    name: "base",
+    quoter: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a",
+    router: "0x2626664c2603336E57B271c5C0b26F421741e481",
+    tokenIn: "0x4200000000000000000000000000000000000006",
+    tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    decIn: 18,
+    decOut: 6,
+  },
+  42161: {
+    name: "arbitrum",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+    tokenOut: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    decIn: 18,
+    decOut: 6,
+  },
+  // HyperEVM 999 is a FORK deployment (HyperSwap), not the canonical Uniswap
+  // addresses -- which is exactly why it sat fail-closed: it was never in this
+  // map, so it was never tested, and "untested" printed the same as "broken".
+  999: {
+    name: "hyperevm",
+    quoter: "0x03A918028f22D9E1473B7959C927AD7425A45C7C",
+    router: "0x4E2960a8cd19B467b82d26D83fAcb0fAE26b094D",
+    tokenIn: "0x5555555555555555555555555555555555555555", // WHYPE
+    tokenOut: "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb", // USDT0
+    decIn: 18,
+    decOut: 6,
+  },
+  // Stable 988 is a CANONICAL deployment (Official Uniswap v3 Deployments List,
+  // 2026-05-12) but was never in this map either. Pair is thin, so amountIn is
+  // sized up: 1 TOAST rounds to zero out, 10000 does not.
+  988: {
+    name: "stable",
+    quoter: "0xb070179E7032CdA868b53e6C1742F80c9e940d1A",
+    router: "0x32eaf9B5d5F2CD7361c5012890C943D7de84C22a",
+    tokenIn: "0x817997Ca8394E26CCE3dE3A076a4889b27DbF9dE", // WgUSDT
+    tokenOut: "0xd9c2E67afbc787ba9C7a886dd09947c127D3cC0d", // LEVCAT
+    decIn: 18,
+    decOut: 18,
+    feeTiers: [100],
+    // Deepest live pool on this chain (liquidity 1.41e24). An earlier candidate
+    // (TOAST/USDT0) drained from 1.4e19 to 0 mid-verification, so pick on depth.
+  },
+  // Abstract 2741 is a ZK-stack chain: canonical Uniswap addresses do not exist
+  // here (codesize 0), which is why probing them made it look like Abstract had
+  // no V3 at all. These are the real deployment, found from live swap traffic.
+  2741: {
+    name: "abstract",
+    quoter: "0x728BD3eC25D5EDBafebB84F3d67367Cd9EBC7693",
+    router: "0x7712FA47387542819d4E35A23f8116C90C18767C",
+    tokenIn: "0x3439153EB7AF838Ad19d56E1571FBD09333C2809", // WETH
+    tokenOut: "0x84A71ccD554Cc1b02749b35d22F684CC8ec987e1", // USDC.e
+    decIn: 18,
+    decOut: 6,
+    feeTiers: [500],
+  },
+  43114: {
+    name: "avalanche",
+    quoter: "0xbe0F5544EC67e9B3b2D979aaA43f18Fd87E6257F",
+    router: "0xbb00FF08d01D300023C629E8fFfFcb65A5a578cE",
+    tokenIn: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7", // WAVAX
+    tokenOut: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", // USDC
+    decIn: 18,
+    decOut: 6,
+  },
+};
+
+const FEE_TIERS = [500, 3000, 10000];
+
+const word = (v) => BigInt(v).toString(16).padStart(64, "0");
+const addrWord = (a) => a.slice(2).toLowerCase().padStart(64, "0");
+
+// QuoterV2.quoteExactInputSingle((address,address,uint256,uint24,uint160))
+// selector 0xc6a5026a -- struct is encoded inline as 5 words.
+function encodeQuote({ tokenIn, tokenOut, amountIn, fee }) {
+  return (
+    "0xc6a5026a" +
+    addrWord(tokenIn) +
+    addrWord(tokenOut) +
+    word(amountIn) +
+    word(fee) +
+    word(0) // sqrtPriceLimitX96 = 0 (no limit)
+  );
+}
+
+async function codesize(chainId, address) {
+  const r = await rpcCall(chainId, "eth_getCode", [address, "latest"]).catch(() => null);
+  const raw = r?.result ?? r;
+  return raw && raw !== "0x" ? (raw.length - 2) / 2 : 0;
+}
+
+async function probe(chainId, cfg) {
+  const result = {
+    chainId: Number(chainId),
+    name: cfg.name,
+    quoter: cfg.quoter,
+    router: cfg.router,
+    quoterCodesize: 0,
+    routerCodesize: 0,
+    workingFeeTier: null,
+    quotedOut: null,
+    humanPrice: null,
+    verdict: "FAIL",
+    reason: "",
+  };
+
+  result.quoterCodesize = await codesize(chainId, cfg.quoter);
+  result.routerCodesize = await codesize(chainId, cfg.router);
+
+  if (!result.quoterCodesize || !result.routerCodesize) {
+    result.reason = "no bytecode at candidate address on this chain";
+    return result;
+  }
+
+  // Behavioural probe: does it actually price a pair we can sanity-check?
+  const units = cfg.amountIn ?? 1n;
+  const amountIn = units * 10n ** BigInt(cfg.decIn);
+  for (const fee of cfg.feeTiers ?? FEE_TIERS) {
+    const data = encodeQuote({
+      tokenIn: cfg.tokenIn,
+      tokenOut: cfg.tokenOut,
+      amountIn,
+      fee,
+    });
+    const r = await rpcCall(chainId, "eth_call", [{ to: cfg.quoter, data }, "latest"]).catch(
+      () => null,
+    );
+    const raw = r?.result ?? r;
+    if (!raw || raw === "0x" || raw.length < 66) continue;
+
+    const out = BigInt(`0x${raw.slice(2, 66)}`);
+    if (out === 0n) continue;
+
+    result.workingFeeTier = fee;
+    result.quotedOut = out.toString();
+    result.humanPrice = Number(out) / 10 ** cfg.decOut;
+    break;
+  }
+
+  if (result.workingFeeTier == null) {
+    result.reason = "bytecode present but no fee tier returned a quote -- not a working V3 quoter";
+    return result;
+  }
+
+  // Sanity band. A working quoter on a major pair should land in a plausible range;
+  // a wildly wrong number means we are talking to the wrong contract or decoding it
+  // wrong, and either way it must not be allowlisted.
+  if (result.humanPrice <= 0 || !Number.isFinite(result.humanPrice)) {
+    result.reason = `implausible quote ${result.humanPrice}`;
+    return result;
+  }
+
+  result.verdict = "PASS";
+  result.reason =
+    `quoteExactInputSingle at fee ${result.workingFeeTier} returned ` +
+    `${result.humanPrice} for 1 unit in -- a live, working V3 quote`;
+  return result;
+}
+
+const out = [];
+for (const [chainId, cfg] of Object.entries(CANDIDATES)) {
+  const r = await probe(chainId, cfg);
+  out.push(r);
+  const line =
+    `${r.name.padEnd(10)} ${r.verdict.padEnd(5)} ` +
+    `quoter=${String(r.quoterCodesize).padStart(6)} router=${String(r.routerCodesize).padStart(6)} ` +
+    (r.workingFeeTier ? `fee=${String(r.workingFeeTier).padStart(5)} price=${r.humanPrice}` : r.reason);
+  console.log(line);
+}
+
+console.log(`\n${out.filter((r) => r.verdict === "PASS").length}/${out.length} chains verified`);
+if (process.argv.includes("--json")) {
+  console.log(JSON.stringify(out, null, 2));
+}

package/skins/oracle.yaml

@@ -0,0 +1,56 @@
+name: oracle
+description: filled lowercase oracle in the classic boxed layout
+colors:
+  banner_border: "#455867"
+  banner_title: "#B8F0FF"
+  banner_accent: "#91C2D7"
+  banner_dim: "#60717F"
+  banner_text: "#EAF2F8"
+  ui_accent: "#B8F0FF"
+  ui_label: "#A5D9EB"
+  ui_ok: "#7EE7B5"
+  ui_error: "#FF7B7B"
+  ui_warn: "#F0C674"
+  prompt: "#B8F0FF"
+  input_rule: "#455867"
+  response_border: "#91C2D7"
+  status_bar_bg: "#11161B"
+  status_bar_text: "#91A2B1"
+  status_bar_strong: "#EAF2F8"
+  status_bar_dim: "#60717F"
+  status_bar_good: "#7EE7B5"
+  status_bar_warn: "#F0C674"
+  status_bar_bad: "#FF9B71"
+  status_bar_critical: "#FF7B7B"
+  session_label: "#B8F0FF"
+  session_border: "#455867"
+  voice_status_bg: "#11161B"
+  selection_bg: "#23313B"
+  completion_menu_bg: "#11161B"
+  completion_menu_current_bg: "#23313B"
+  completion_menu_meta_bg: "#11161B"
+  completion_menu_meta_current_bg: "#23313B"
+spinner:
+  waiting_faces: ["·", "··", "···"]
+  thinking_faces: ["◇", "◈", "◆", "◈"]
+  thinking_verbs: ["thinking", "reading", "checking", "routing"]
+  wings: [["", ""]]
+branding:
+  agent_name: "oracle"
+  welcome: ""
+  goodbye: "exit"
+  response_label: " oracle "
+  prompt_symbol: "›"
+  help_header: "oracle"
+tool_prefix: "│"
+banner_logo: |
+  [bold #B8F0FF]                                       ████[/]
+  [bold #B8F0FF]                                      ░░███[/]
+  [bold #ACDEEF]  ██████  ████████   ██████    ██████  ░███   ██████[/]
+  [bold #A5D9EB] ███░░███░░███░░███ ░░░░░███  ███░░███ ░███  ███░░███[/]
+  [bold #9FCBDD]░███ ░███ ░███ ░░░   ███████ ░███ ░░░  ░███ ░███████[/]
+  [bold #9FCBDD]░███ ░███ ░███      ███░░███ ░███  ███ ░███ ░███░░░[/]
+  [bold #ACDEEF]░░██████  █████    ░░████████░░██████  █████░░██████[/]
+  [bold #B8F0FF] ░░░░░░  ░░░░░      ░░░░░░░░  ░░░░░░  ░░░░░  ░░░░░░[/]
+banner_hero: |
+  [bold #EAF2F8]THE FUTURE IS AGENTIC[/]

package/src/action-receipts.mjs

@@ -0,0 +1,265 @@
+// Deterministic, public-only receipts for prepared and executed actions.
+//
+// This module deliberately has no authority and no I/O: it does not authorize,
+// sign, broadcast, or fetch. It only records facts supplied by its caller.
+
+import { createHash } from "node:crypto";
+import { wordlists } from "ethers";
+
+export const ACTION_RECEIPT_VERSION = 1;
+
+// Key-name matching was exact-ish and only covered five words, so every wallet
+// export alias (secretKey, seedPhrase, wif, keyMaterial, privKey, xprv, seed,
+// keystore) sailed through. There was also NO value-shape rule, so a raw key or
+// a BIP-39 phrase pasted into a benign field like `memo` was recorded verbatim.
+//
+// Both concerns were already solved in src/address-book.mjs; this module simply
+// did not use the hardened list. Found by the opus lane of the 2026-08-03
+// four-model review, and verified to PERSIST: unknown top-level props are
+// dropped by the schema whitelist, but a secret nested inside a RETAINED field
+// (intent, route, decodedAction) survives into the frozen receipt.
+const SECRET_KEYS = new Set([
+  "privatekey",
+  "privkey",
+  "secretkey",
+  "seedphrase",
+  "seed",
+  "mnemonic",
+  "passphrase",
+  "password",
+  "keystore",
+  "keymaterial",
+  "wif",
+  "xprv",
+  "xpriv",
+  "bearer",
+  "authorization",
+  "signature",
+  "apikey",
+  "credential",
+]);
+
+// Unambiguous key shapes: WIF, extended private key, BIP-39 word run. These are
+// refused wherever they appear.
+//
+// A bare 64-hex string is deliberately NOT in this list. A raw EVM private key
+// and a bytes32 tx hash are byte-identical, and receipts legitimately carry
+// txHash / orderHash / salt / merkleRoot / nonce. Blanket-refusing 64-hex would
+// break real receipts — an over-tight filter is its own bug. It is instead
+// gated on the field name below.
+const KEY_SHAPED_VALUE = [
+  /\b[5KL][1-9A-HJ-NP-Za-km-z]{50,51}\b/,
+  /\bxprv[0-9A-Za-z]{50,}\b/,
+];
+
+const BIP39_WORD_COUNTS = new Set([12, 15, 18, 21, 24]);
+
+function isBip39EnglishPhrase(value) {
+  const words = String(value).trim().toLowerCase().split(/\s+/).filter(Boolean);
+  return BIP39_WORD_COUNTS.has(words.length) && words.every((word) => wordlists.en.getWordIndex(word) >= 0);
+}
+
+const BARE_32_BYTE_HEX = /^\s*(?:0x)?[0-9a-fA-F]{64}\s*$/;
+
+// Field names whose whole value is EXPECTED to be a 32-byte digest.
+//
+// The trailing `(?:e?s)?` matters: `publicValue` scans array leaves using the
+// PARENT key, so a batched route's `orderHashes` / `proofs` / `commitments`
+// arrives here in its plural form (English pluralizes `hash` as `hashes`).
+// Without it a digest LIST is refused while the exact same digest in singular
+// form is accepted — an over-tight filter that breaks real receipts and blocks
+// no secret (key-SHAPED values are refused by KEY_SHAPED_VALUE / BIP-39
+// regardless of field name).
+const DIGEST_FIELD = /(hash|digest|root|salt|nonce|proof|commitment|sig|id)(?:e?s)?$/i;
+const PROTOCOL_HEX_FIELDS = new Set([
+  "calldata",
+  "data",
+  "publickey",
+  "pubkey",
+  "message",
+  "payload",
+  "input",
+  "extradata",
+]);
+
+function allows32ByteHex(key) {
+  const normalized = normalizedKey(key);
+  return PROTOCOL_HEX_FIELDS.has(normalized) || DIGEST_FIELD.test(normalized);
+}
+
+export class ActionReceiptSecretError extends Error {
+  constructor(path) {
+    super(`action receipt refused: secret-bearing field at ${path}`);
+    this.name = "ActionReceiptSecretError";
+    this.code = "ACTION_RECEIPT_SECRET";
+  }
+}
+
+function normalizedKey(key) {
+  return String(key).replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+
+function isSecretKey(key) {
+  const normalized = normalizedKey(key);
+  return [...SECRET_KEYS].some((secret) => normalized.includes(secret));
+}
+
+/**
+ * Refuse a key-material-shaped VALUE, so a secret pasted into a benign field
+ * name (memo, note, label) cannot be recorded verbatim.
+ *
+ * Bare 64-hex is only refused when the field name is NOT digest-shaped: a raw
+ * EVM private key and a bytes32 hash are byte-identical, and receipts carry
+ * txHash / orderHash / salt / nonce legitimately.
+ */
+function assertNoSecretValue(key, value, path) {
+  if (typeof value !== "string") return;
+  if (KEY_SHAPED_VALUE.some((re) => re.test(value)) || isBip39EnglishPhrase(value)) {
+    throw new ActionReceiptSecretError(path);
+  }
+  if (BARE_32_BYTE_HEX.test(value) && !allows32ByteHex(key)) {
+    throw new ActionReceiptSecretError(path);
+  }
+}
+
+function publicValue(value, path = "$", key = "") {
+  if (value == null || typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    assertNoSecretValue(key, value, path);
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError(`action receipt: non-finite number at ${path}`);
+    return value;
+  }
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return value.map((item, index) => publicValue(item, `${path}[${index}]`, key));
+  if (typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new TypeError(`action receipt: JSON-like value required at ${path}`);
+  }
+
+  const out = {};
+  for (const childKey of Object.keys(value).sort()) {
+    const childPath = `${path}.${childKey}`;
+    if (isSecretKey(childKey)) throw new ActionReceiptSecretError(childPath);
+    if (value[childKey] !== undefined) out[childKey] = publicValue(value[childKey], childPath, childKey);
+  }
+  return out;
+}
+
+/** Recursively reject secret-bearing fields and return a detached public copy. */
+export function assertNoReceiptSecrets(value) {
+  return publicValue(value);
+}
+
+function canonicalPublicJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalPublicJson).join(",")}]`;
+  return `{${Object.keys(value).map((key) => `${JSON.stringify(key)}:${canonicalPublicJson(value[key])}`).join(",")}}`;
+}
+
+/** Canonical JSON with recursively sorted object keys. */
+export function canonicalReceiptJson(value) {
+  return canonicalPublicJson(publicValue(value));
+}
+
+/** Hash exactly the public receipt fields, excluding the self-referential id. */
+export function computeReceiptId(receipt) {
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    throw new TypeError("action receipt: object required");
+  }
+  const { receiptId: _ignored, summary: _derived, ...publicFields } = receipt;
+  return createHash("sha256").update(canonicalReceiptJson(publicFields)).digest("hex");
+}
+
+function supplied(input, ...keys) {
+  for (const key of keys) if (input[key] !== undefined) return input[key];
+  return undefined;
+}
+
+function required(input, keys, label) {
+  const value = supplied(input, ...keys);
+  if (value === undefined || value === null) throw new TypeError(`action receipt: ${label} required`);
+  return value;
+}
+
+function balanceFields(input) {
+  const balances = supplied(input, "balances", "balanceChanges");
+  const before = supplied(input, "beforeBalances", "balancesBefore", "before");
+  const after = supplied(input, "afterBalances", "balancesAfter", "after");
+  if (balances !== undefined) return { balances };
+  if (before === undefined && after === undefined) return {};
+  return { balances: { ...(before === undefined ? {} : { before }), ...(after === undefined ? {} : { after }) } };
+}
+
+/**
+ * Normalize caller-supplied prepare/execute facts into the versioned schema.
+ * Unknown input fields are intentionally omitted from the receipt.
+ */
+export function normalizeActionReceipt(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("action receipt: input object required");
+  }
+  // Scan the complete input before selecting fields so a secret cannot be
+  // hidden in an otherwise unknown property and accidentally appear later.
+  publicValue(input);
+
+  const txHash = supplied(input, "txHash", "transactionHash");
+  const phase = supplied(input, "phase", "stage", "resultType") ?? (txHash == null ? "prepare" : "execute");
+  if (phase !== "prepare" && phase !== "execute") {
+    throw new TypeError('action receipt: phase must be "prepare" or "execute"');
+  }
+
+  const fields = {
+    receiptVersion: ACTION_RECEIPT_VERSION,
+    phase,
+    intent: required(input, ["intent"], "intent"),
+    route: required(input, ["route"], "route"),
+    decodedAction: required(input, ["decodedAction", "action"], "decodedAction"),
+    policyChecks: required(input, ["policyChecks", "checks"], "policyChecks"),
+    allowlistHits: required(input, ["allowlistHits", "allowlistMatches"], "allowlistHits"),
+    prepareHash: required(input, ["prepareHash"], "prepareHash"),
+    ...(txHash == null ? {} : { txHash }),
+    ...balanceFields(input),
+  };
+  const receipt = publicValue(fields);
+  return Object.freeze({ ...receipt, receiptId: computeReceiptId(receipt) });
+}
+
+export const createActionReceipt = normalizeActionReceipt;
+
+function label(value, preferred = []) {
+  if (typeof value === "string" || typeof value === "number") return String(value);
+  for (const key of preferred) if (value?.[key] != null) return String(value[key]);
+  return "recorded";
+}
+
+function checkResult(check) {
+  if (typeof check === "boolean") return check;
+  if (check && typeof check === "object") {
+    if (typeof check.ok === "boolean") return check.ok;
+    if (typeof check.allowed === "boolean") return check.allowed;
+    if (typeof check.passed === "boolean") return check.passed;
+  }
+  return null;
+}
+
+/** Produce a compact human-readable statement without changing the receipt. */
+export function summarizeActionReceipt(receipt) {
+  if (!receipt || typeof receipt !== "object") throw new TypeError("action receipt: object required");
+  const action = label(receipt.decodedAction, ["type", "action", "method", "name"]);
+  const route = label(receipt.route, ["name", "provider", "venue", "id"]);
+  const checks = Array.isArray(receipt.policyChecks)
+    ? receipt.policyChecks
+    : Object.values(receipt.policyChecks || {});
+  const passed = checks.filter((check) => checkResult(check) === true).length;
+  const failed = checks.filter((check) => checkResult(check) === false).length;
+  const hits = Array.isArray(receipt.allowlistHits)
+    ? receipt.allowlistHits.length
+    : Object.keys(receipt.allowlistHits || {}).length;
+  const tx = receipt.txHash == null ? "no transaction hash" : `tx ${receipt.txHash}`;
+  const balances = receipt.balances == null ? "balances not provided" : "before/after balances recorded";
+  return `${receipt.phase} ${action} via ${route}; policy ${passed} passed, ${failed} failed; ${hits} allowlist hit${hits === 1 ? "" : "s"}; ${tx}; ${balances}; receipt ${receipt.receiptId}`;
+}
+
+export const formatActionReceipt = summarizeActionReceipt;

package/src/action-semantics.mjs

@@ -0,0 +1,62 @@
+export const ACTION_MODES = Object.freeze({
+  ALERT_ONLY: "alert_only",
+  EXECUTE: "execute",
+});
+
+const ALERT_VERBS = new Set(["watch", "watch this", "ping", "ping me", "alert", "notify"]);
+const ACTIVE_LEGACY_WATCH_STATUSES = new Set(["watching", "armed"]);
+
+export function actionModeForVerb(verb) {
+  if (typeof verb !== "string" || !verb.trim()) {
+    throw new TypeError("explicit action verb required");
+  }
+  const normalized = verb.trim().toLowerCase().replace(/\s+/g, " ");
+  if (ALERT_VERBS.has(normalized)) return ACTION_MODES.ALERT_ONLY;
+  if (normalized === "arm") return ACTION_MODES.EXECUTE;
+  throw new TypeError(`unsupported action verb: ${normalized}`);
+}
+
+export function createActionRecord(input = {}) {
+  const { verb, ...fields } = input;
+  return {
+    ...fields,
+    active: true,
+    actionMode: actionModeForVerb(verb),
+  };
+}
+
+export function assertActionRecord(record) {
+  if (!record || typeof record !== "object" || typeof record.active !== "boolean") {
+    throw new TypeError("active must be boolean");
+  }
+  if (!Object.values(ACTION_MODES).includes(record.actionMode)) {
+    throw new TypeError("actionMode must be alert_only or execute");
+  }
+  return record;
+}
+
+export function isActiveAlert(record) {
+  return record?.active === true && record?.actionMode === ACTION_MODES.ALERT_ONLY;
+}
+
+export function isActiveExecution(record) {
+  return record?.active === true && record?.actionMode === ACTION_MODES.EXECUTE;
+}
+
+export function migrateLegacyWatchRecord(record = {}) {
+  if (
+    record.actionMode !== undefined &&
+    record.actionMode !== ACTION_MODES.ALERT_ONLY
+  ) {
+    throw new TypeError("non-alert record cannot enter alert-only watch migration");
+  }
+  const active =
+    typeof record.active === "boolean"
+      ? record.active
+      : ACTIVE_LEGACY_WATCH_STATUSES.has(String(record.status || "").toLowerCase());
+  return {
+    ...record,
+    active,
+    actionMode: ACTION_MODES.ALERT_ONLY,
+  };
+}