@oracle-agent/oracle 0.4.1 → 0.5.0

package/src/onboarding/harness-configs.mjs

@@ -0,0 +1,102 @@
+const PACKAGE = "@oracle-agent/oracle";
+const COMMAND = "npx";
+const ARGS = ["-y", "--package", PACKAGE, "oracle-data-mcp"];
+const FORBIDDEN_NAME = /(?:^|_)(?:PRIVATE_KEY|SECRET|TOKEN|PASSWORD|PASSPHRASE|MNEMONIC|SEED)(?:_|$)/i;
+
+function requiredText(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
+  if (/\r|\n|\0/.test(value)) throw new TypeError(`${name} must be a single-line string`);
+  return value.trim();
+}
+
+function validateUrl(value) {
+  const text = requiredText(value, "url");
+  let parsed;
+  try { parsed = new URL(text); } catch { throw new TypeError("url must be a valid http(s) URL"); }
+  if (!/^https?:$/.test(parsed.protocol) || parsed.username || parsed.password) {
+    throw new TypeError("url must be a credential-free http(s) URL");
+  }
+  for (const name of parsed.searchParams.keys()) {
+    if (FORBIDDEN_NAME.test(name) || /^(?:key|api[_-]?key|auth)$/i.test(name)) {
+      throw new TypeError(`url must not contain secret-shaped query parameter: ${name}`);
+    }
+  }
+  return parsed.href;
+}
+
+function validateKey(value) {
+  const text = requiredText(value, "key");
+  if (/^[A-Z][A-Z0-9_]*\s*=/.test(text) || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(text)) {
+    throw new TypeError("key must be an Oracle agent key, not an environment assignment or private key");
+  }
+  if (/^(?:0x)?[0-9a-f]{64}$/i.test(text) || text.trim().split(/\s+/).length >= 12) {
+    throw new TypeError("key looks like private signing material");
+  }
+  return text;
+}
+
+function validateLabel(value) {
+  const label = requiredText(value, "label");
+  if (!/^[a-z0-9][a-z0-9_-]{0,62}$/i.test(label)) {
+    throw new TypeError("label must contain only letters, digits, underscores, and hyphens");
+  }
+  if (FORBIDDEN_NAME.test(label)) throw new TypeError("label must not be a secret-shaped environment name");
+  return label;
+}
+
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function yamlString(value) {
+  return JSON.stringify(value);
+}
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+/**
+ * Return deterministic, copy-pasteable MCP configuration snippets.
+ * This function performs no I/O and never reads from process.env.
+ */
+export function emitHarnessConfigs({ url, key, label = "oracle-data" } = {}) {
+  const endpoint = validateUrl(url);
+  const agentKey = validateKey(key);
+  const name = validateLabel(label);
+  const server = {
+    command: COMMAND,
+    args: [...ARGS],
+    env: { ORACLE_DATA_URL: endpoint, ORACLE_AGENT_KEY: agentKey },
+  };
+  const mcp = { mcpServers: { [name]: server } };
+
+  return {
+    hermes: [
+      "mcp_servers:",
+      `  ${name}:`,
+      `    command: ${yamlString(COMMAND)}`,
+      "    args:",
+      ...ARGS.map((arg) => `      - ${yamlString(arg)}`),
+      "    env:",
+      `      ORACLE_DATA_URL: ${yamlString(endpoint)}`,
+      `      ORACLE_AGENT_KEY: ${yamlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    claudeCode: json(mcp),
+    codex: [
+      `[mcp_servers.${tomlString(name)}]`,
+      `command = ${tomlString(COMMAND)}`,
+      `args = [${ARGS.map(tomlString).join(", ")}]`,
+      "",
+      `[mcp_servers.${tomlString(name)}.env]`,
+      `ORACLE_DATA_URL = ${tomlString(endpoint)}`,
+      `ORACLE_AGENT_KEY = ${tomlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    cursor: json(mcp),
+    genericMcp: json(mcp),
+  };
+}
+
+export const createHarnessConfigs = emitHarnessConfigs;

package/src/oracle-env.mjs

@@ -20,9 +20,18 @@ export function envFlag(primary, legacy, defaultValue = false) {
   return String(env(primary, legacy, fallback)).trim() === "1";
 }
 
+const DISABLE_WORDS = ["0", "false", "off", "no"];
+
+// Reading a flag that may default ON. Only an explicit disable word turns it
+// off, and an unset value keeps `defaultValue`.
+//
+// The old shape (`!== "0"`) inverted with a false default: ORACLE_ONBOARD_HTTP
+// defaults off, so a user writing `false` to keep it off actually ENABLED it,
+// because "false" is not "0". A disable word must never enable a surface.
 export function envEnabled(primary, legacy, defaultValue = true) {
-  const fallback = defaultValue ? "1" : "0";
-  return String(env(primary, legacy, fallback)).trim() !== "0";
+  const raw = String(env(primary, legacy, "")).trim().toLowerCase();
+  if (raw === "") return defaultValue;
+  return !DISABLE_WORDS.includes(raw);
 }
 
 export function csvEnv(primary, legacy) {

package/src/portfolio-risk.mjs

@@ -0,0 +1,170 @@
+// Pure portfolio exposure and coverage summary. This module performs no I/O.
+
+export const DEFAULT_RISK_THRESHOLDS = Object.freeze({
+  assetHighPct: 50,
+  assetMediumPct: 25,
+  chainHighPct: 75,
+  venueHighPct: 60,
+  stablecoinHighPct: 70,
+});
+
+const STABLECOINS = new Set(["USDC", "USDT", "USDT0", "DAI", "FRAX", "LUSD", "TUSD", "USDP", "GUSD", "PYUSD", "USDE"]);
+
+function finite(value) {
+  if (value === null || value === "" || value === undefined) return null;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+function rounded(value) {
+  return Math.round((value + Number.EPSILON) * 1e8) / 1e8;
+}
+
+function pct(value, total) {
+  return total > 0 ? rounded((value / total) * 100) : null;
+}
+
+function addressOf(snapshot) {
+  return snapshot.address || snapshot.owner || snapshot.walletAddress || snapshot.wallet?.address || null;
+}
+
+function labelIndex(labels) {
+  const entries = Array.isArray(labels) ? labels : Array.isArray(labels?.entries) ? labels.entries : [];
+  const index = new Map();
+  for (const entry of entries) {
+    if (!entry?.address) continue;
+    const key = String(entry.address).toLowerCase();
+    if (!index.has(key)) index.set(key, entry);
+  }
+  return index;
+}
+
+function addAsset(output, raw, context = {}) {
+  if (!raw || typeof raw !== "object") return;
+  const symbol = String(raw.symbol ?? raw.coin ?? raw.name ?? raw.collection ?? raw.tokenId ?? "unknown");
+  const value = finite(raw.usdValue ?? raw.valueUsd ?? raw.knownUsd ?? raw.estimatedValueUsd ?? raw.floorValueUsd);
+  const kind = raw.kind === "nft" || raw.type === "nft" || raw.collection || raw.tokenId != null ? "nft" : "fungible";
+  output.push({
+    symbol,
+    usdValue: value,
+    chain: String(raw.chain ?? raw.chainName ?? context.chain ?? "unknown"),
+    venue: String(raw.venue ?? raw.protocol ?? raw.platform ?? context.venue ?? "wallet"),
+    address: raw.address ?? context.address ?? null,
+    kind,
+    stablecoin: raw.stablecoin === true || STABLECOINS.has(symbol.toUpperCase()),
+  });
+}
+
+function assetsFromSnapshot(snapshot) {
+  const output = [];
+  const rootAddress = addressOf(snapshot);
+  for (const asset of snapshot.assets || snapshot.holdings || []) addAsset(output, asset, { address: rootAddress, chain: snapshot.chain, venue: snapshot.venue });
+  for (const chain of snapshot.chains || []) {
+    const chainName = chain.chain ?? chain.name ?? chain.slug ?? (chain.chainId != null ? String(chain.chainId) : chain.family) ?? "unknown";
+    const context = { address: chain.address ?? rootAddress, chain: chainName, venue: chain.venue };
+    if (chain.native && (chain.native.amount == null || Number(chain.native.amount) !== 0)) {
+      addAsset(output, { ...chain.native, symbol: chain.native.symbol ?? chain.symbol ?? chainName }, context);
+    }
+    for (const asset of chain.assets || chain.fungibleTokens?.assets || []) addAsset(output, asset, context);
+    for (const asset of chain.collectibles?.assets || chain.nfts || []) addAsset(output, { ...asset, kind: "nft" }, context);
+    for (const asset of chain.spot?.balances || []) addAsset(output, asset, { ...context, venue: "Hyperliquid spot" });
+    const accountValue = finite(chain.perps?.accountValueUsd);
+    if (accountValue != null) addAsset(output, { symbol: "perps account", usdValue: accountValue }, { ...context, venue: "Hyperliquid perps" });
+  }
+  for (const item of snapshot.inventory?.items || snapshot.nfts?.items || []) addAsset(output, { ...item, kind: "nft" }, { address: rootAddress, chain: item.chain ?? snapshot.chain, venue: item.marketplace ?? snapshot.venue });
+  return output;
+}
+
+function snapshotKey(snapshot, index) {
+  const address = addressOf(snapshot);
+  const chain = snapshot.chain ?? snapshot.chainId ?? snapshot.family ?? "*";
+  return address ? `${String(address).toLowerCase()}|${String(chain).toLowerCase()}` : `snapshot:${index}`;
+}
+
+function buckets(assets, property, total) {
+  const map = new Map();
+  for (const asset of assets) {
+    if (asset.usdValue == null) continue;
+    const name = asset[property];
+    map.set(name, (map.get(name) || 0) + asset.usdValue);
+  }
+  return [...map].map(([name, knownUsd]) => ({ name, knownUsd: rounded(knownUsd), percentOfKnown: pct(knownUsd, total) }))
+    .sort((a, b) => b.knownUsd - a.knownUsd || a.name.localeCompare(b.name));
+}
+
+/**
+ * Summarize already-fetched portfolio snapshots. Accepts either
+ * `{ snapshots, labels, thresholds }` or an array plus an options object.
+ */
+export function summarizePortfolioRisk(input = {}, options = {}) {
+  const snapshots = Array.isArray(input) ? input : Array.isArray(input.snapshots) ? input.snapshots : input.snapshot ? [input.snapshot] : [];
+  const labels = labelIndex(options.labels ?? options.addressBook ?? input.labels ?? input.addressBook);
+  const thresholds = { ...DEFAULT_RISK_THRESHOLDS, ...(input.thresholds || {}), ...(options.thresholds || {}) };
+  const unique = [];
+  const seen = new Set();
+  let duplicatesIgnored = 0;
+  snapshots.forEach((snapshot, index) => {
+    if (!snapshot || typeof snapshot !== "object") return;
+    const key = snapshotKey(snapshot, index);
+    if (seen.has(key)) duplicatesIgnored += 1;
+    else { seen.add(key); unique.push(snapshot); }
+  });
+
+  const assets = unique.flatMap(assetsFromSnapshot);
+  const priced = assets.filter((asset) => asset.usdValue != null);
+  const unknown = assets.filter((asset) => asset.usdValue == null);
+  const explicitUnknown = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.unpricedNonzeroItems || snapshot.unpricedNonzeroItems || 0), 0);
+  const totalKnownUsd = rounded(priced.reduce((sum, asset) => sum + asset.usdValue, 0));
+  const unknownItemCount = unknown.length + explicitUnknown;
+  const chainExposures = buckets(priced, "chain", totalKnownUsd);
+  const venueExposures = buckets(priced, "venue", totalKnownUsd);
+  const groupedAssets = buckets(priced, "symbol", totalKnownUsd);
+  for (const row of chainExposures) row.chain = row.name;
+  for (const row of venueExposures) row.venue = row.name;
+  for (const row of groupedAssets) {
+    row.asset = row.name;
+    row.symbol = row.name;
+  }
+  const stablecoinKnownUsd = rounded(priced.filter((asset) => asset.stablecoin).reduce((sum, asset) => sum + asset.usdValue, 0));
+  const nftAssets = assets.filter((asset) => asset.kind === "nft");
+  const snapshotNftUnvalued = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.nftUnvaluedItems || 0), 0);
+  const nftUnvaluedItems = nftAssets.filter((asset) => asset.usdValue == null).length + snapshotNftUnvalued;
+  const nftValuedItems = nftAssets.filter((asset) => asset.usdValue != null).length;
+  const top = groupedAssets[0] || null;
+  const concentrationLevel = !top ? "unknown" : top.percentOfKnown >= thresholds.assetHighPct ? "high" : top.percentOfKnown >= thresholds.assetMediumPct ? "medium" : "low";
+  const warnings = [];
+  if (unknownItemCount) warnings.push(`${unknownItemCount} nonzero holding(s) have unknown USD value; they are excluded from totals and percentages.`);
+  if (nftUnvaluedItems) warnings.push("NFT valuation coverage is partial; estimates are not executable bids and unvalued NFTs are not treated as zero.");
+  if (duplicatesIgnored) warnings.push(`${duplicatesIgnored} duplicate address/chain snapshot(s) were ignored.`);
+  if (top && concentrationLevel !== "low") warnings.push(`Asset concentration is ${concentrationLevel}: ${top.name} is ${top.percentOfKnown}% of known value.`);
+  if (chainExposures[0]?.percentOfKnown >= thresholds.chainHighPct) warnings.push(`Chain concentration is high: ${chainExposures[0].name} is ${chainExposures[0].percentOfKnown}% of known value.`);
+  if (venueExposures[0]?.percentOfKnown >= thresholds.venueHighPct) warnings.push(`Venue concentration is high: ${venueExposures[0].name} is ${venueExposures[0].percentOfKnown}% of known value.`);
+
+  const addresses = unique.map(addressOf).filter(Boolean).map((address) => {
+    const entry = labels.get(String(address).toLowerCase());
+    return { address, label: entry?.label ?? null, who: entry?.who ?? null, role: entry?.role ?? null };
+  });
+  return {
+    totalKnownUsd,
+    coverage: {
+      complete: unique.length > 0 && unknownItemCount === 0 && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false),
+      label: unknownItemCount === 0 && unique.length && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false)
+        ? "complete for the supplied snapshots" : "known priced value only; portfolio coverage is partial or unverified",
+      unknownUsd: unknownItemCount ? null : 0,
+      pricedItemCount: priced.length,
+      unknownItemCount,
+      snapshotCount: unique.length,
+      duplicatesIgnored,
+    },
+    chainExposures,
+    venueExposures,
+    topAssets: groupedAssets.slice(0, Math.max(1, Number(options.topAssets ?? input.topAssets ?? 10))),
+    concentrationRisk: { level: concentrationLevel, topAsset: top?.name ?? null, topAssetPercent: top?.percentOfKnown ?? null, thresholds: { mediumPct: thresholds.assetMediumPct, highPct: thresholds.assetHighPct } },
+    stablecoinExposure: { knownUsd: stablecoinKnownUsd, percentOfKnown: pct(stablecoinKnownUsd, totalKnownUsd), high: totalKnownUsd > 0 && pct(stablecoinKnownUsd, totalKnownUsd) >= thresholds.stablecoinHighPct },
+    nftCoverage: { status: nftAssets.length || snapshotNftUnvalued ? (nftUnvaluedItems ? "partial" : "valued") : "not-observed", valuedItems: nftValuedItems, unvaluedItems: nftUnvaluedItems, knownUsd: rounded(nftAssets.filter((asset) => asset.usdValue != null).reduce((sum, asset) => sum + asset.usdValue, 0)) },
+    addresses,
+    warnings: [...new Set(warnings)],
+  };
+}
+
+export const portfolioRiskSummary = summarizePortfolioRisk;

package/src/public-api/connect-agent.mjs

@@ -53,6 +53,18 @@ export class SecretLeakError extends Error {
 const FORBIDDEN_KEY_RE =
   /(private[_-]?key|secret|bearer|keystore|mnemonic|seed[_-]?phrase|passphrase|password|api[_-]?key|access[_-]?token|auth[_-]?token|session[_-]?token|signer[_-]?url|signature)/i;
 
+/** Short wallet-export aliases need exact normalized matching. Substring
+ * matching `wif`, for example, would incorrectly reject an unrelated key such
+ * as `swift`. Removing common separators catches snake/kebab/spaced variants
+ * without widening those short aliases into arbitrary words. */
+const FORBIDDEN_KEY_ALIASES = Object.freeze(["privkey", "wif", "xprv", "seed"]);
+
+function isForbiddenKeyName(key) {
+  const text = String(key);
+  const normalized = text.toLowerCase().replace(/[\s._-]+/g, "");
+  return FORBIDDEN_KEY_RE.test(text) || FORBIDDEN_KEY_ALIASES.includes(normalized);
+}
+
 /** String-value shapes that must never appear in any object we return. */
 const FORBIDDEN_VALUE_RULES = Object.freeze([
   // 32-byte hex — the shape of a raw EVM private key / session secret. Public
@@ -69,8 +81,12 @@ const FORBIDDEN_VALUE_RULES = Object.freeze([
   // gets disabled. Smuggling a key inside a longer string is still caught at
   // the serialized layer for any non-allowlisted field.
   { rule: "raw-32-byte-hex-bare", re: /^[0-9a-fA-F]{64}$/ },
-  // Bitcoin WIF (mainnet 5/K/L, testnet c) — base58, 51-52 chars.
-  { rule: "bitcoin-wif", re: /\b[5KLc][1-9A-HJ-NP-Za-km-z]{50,51}\b/ },
+  // BIP-32 private extended keys. Public xpub/tpub/ypub/zpub identifiers are
+  // intentionally not matched; only their private-key counterparts fail.
+  { rule: "extended-private-key", re: /\b(?:xprv|tprv|yprv|zprv)[1-9A-HJ-NP-Za-km-z]{107}\b/ },
+  // Bitcoin WIF (mainnet 5/K/L, testnet uncompressed 9 or compressed c) —
+  // base58, 51-52 chars.
+  { rule: "bitcoin-wif", re: /\b[59KLc][1-9A-HJ-NP-Za-km-z]{50,51}\b/ },
   // BIP-39 mnemonic: 12/15/18/21/24 lowercase words. Detect a long run of
   // space-separated short alpha words rather than shipping the wordlist.
   { rule: "bip39-mnemonic", re: /\b(?:[a-z]{3,8}\s+){11,23}[a-z]{3,8}\b/ },
@@ -169,12 +185,15 @@ export function assertSerializedNoSecrets(value) {
   if (embedded.test(scanned)) {
     throw new SecretLeakError("$<serialized>", "raw-32-byte-hex-embedded");
   }
-  // Key names are checked against the serialized text too, so a key smuggled
-  // in via toJSON or a getter is still caught.
-  const keyHit = scanned.match(
-    /"([^"]*(?:private[_-]?key|secret|bearer|keystore|mnemonic|seed[_-]?phrase|passphrase|password|api[_-]?key|access[_-]?token|auth[_-]?token|session[_-]?token|signer[_-]?url)[^"]*)"\s*:/i
-  );
-  if (keyHit) throw new SecretLeakError(`$<serialized>.${keyHit[1]}`, "forbidden-key-name");
+  // Parse the exact serialized bytes with a reviver so escaped or toJSON-made
+  // key names receive the same normalization as real object properties. This
+  // avoids maintaining a second, inevitably drifting key-name regex.
+  JSON.parse(json, (key, item) => {
+    if (key && isForbiddenKeyName(key)) {
+      throw new SecretLeakError(`$<serialized>.${key}`, "forbidden-key-name");
+    }
+    return item;
+  });
   return json;
 }
 
@@ -207,7 +226,7 @@ export function assertNoSecretMaterial(value, path = "$", seen = new Set(), keyH
   if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value;
   if (value instanceof Map) {
     for (const [k, v] of value.entries()) {
-      if (typeof k === "string" && FORBIDDEN_KEY_RE.test(k)) {
+      if (typeof k === "string" && isForbiddenKeyName(k)) {
         throw new SecretLeakError(`${path}[${JSON.stringify(k)}]`, "forbidden-key-name");
       }
       assertNoSecretMaterial(k, `${path}[key]`, seen);
@@ -225,7 +244,7 @@ export function assertNoSecretMaterial(value, path = "$", seen = new Set(), keyH
     return value;
   }
   for (const [k, v] of Object.entries(value)) {
-    if (FORBIDDEN_KEY_RE.test(k)) {
+    if (isForbiddenKeyName(k)) {
       throw new SecretLeakError(`${path}.${k}`, "forbidden-key-name");
     }
     assertNoSecretMaterial(v, `${path}.${k}`, seen, k);

package/src/signals/engine.mjs

@@ -0,0 +1,146 @@
+const SIGNAL_TYPES = Object.freeze([
+  "wallet",
+  "pool",
+  "nft_floor",
+  "hl_flow",
+  "prediction_market",
+]);
+
+const TYPE_ALIASES = Object.freeze({
+  wallets: "wallet",
+  smart_wallet: "wallet",
+  pools: "pool",
+  new_pool: "pool",
+  nft: "nft_floor",
+  nft_floors: "nft_floor",
+  hyperliquid: "hl_flow",
+  prediction: "prediction_market",
+  prediction_markets: "prediction_market",
+});
+
+const clamp = (value, min = 0, max = 1) => Math.min(max, Math.max(min, value));
+const finite = (value) => (Number.isFinite(Number(value)) ? Number(value) : null);
+const round = (value) => Math.round(value * 10_000) / 10_000;
+
+function typeOf(event) {
+  const raw = String(event?.type ?? event?.surface ?? event?.kind ?? "").toLowerCase();
+  return TYPE_ALIASES[raw] ?? raw;
+}
+
+function idOf(event, index) {
+  return String(event?.id ?? event?.signalId ?? event?.asset ?? event?.market ?? event?.pool ?? event?.collection ?? `${typeOf(event)}:${index}`);
+}
+
+function add(contributions, feature, value, observed = true) {
+  if (!observed || value === null || !Number.isFinite(value)) return;
+  contributions.push({ feature, value: round(value) });
+}
+
+function walletFeatures(event, out) {
+  const buys = finite(event.repeatBuys ?? event.repeat_buys ?? event.buyCount);
+  const winRate = finite(event.walletWinRate ?? event.winRate);
+  add(out, "repeat_buys", buys === null ? null : clamp((buys - 1) / 4) * 0.38);
+  add(out, "wallet_win_rate", winRate === null ? null : (clamp(winRate) - 0.5) * 0.5);
+}
+
+function poolFeatures(event, out) {
+  const age = finite(event.ageHours ?? event.poolAgeHours);
+  const liquidity = finite(event.liquidityUsd ?? event.liquidity);
+  const locked = event.liquidityLocked ?? event.locked;
+  add(out, "pool_age", age === null ? null : age < 24 ? -0.42 : clamp(age / 720) * 0.12);
+  add(out, "liquidity", liquidity === null ? null : (clamp(Math.log10(Math.max(1, liquidity)) / 7) - 0.5) * 0.28);
+  add(out, "liquidity_lock", locked == null ? null : locked ? 0.12 : -0.28);
+}
+
+function nftFeatures(event, out) {
+  const change = finite(event.floorChange ?? event.floorChangePct);
+  const sales = finite(event.sales ?? event.saleCount);
+  add(out, "floor_change", change === null ? null : clamp(change, -1, 1) * 0.35);
+  add(out, "sales_depth", sales === null ? null : clamp(sales / 50) * 0.18);
+}
+
+function hlFeatures(event, out) {
+  const imbalance = finite(event.flowImbalance ?? event.imbalance);
+  const funding = finite(event.fundingRate ?? event.funding);
+  add(out, "flow_imbalance", imbalance === null ? null : clamp(imbalance, -1, 1) * 0.42);
+  add(out, "funding", funding === null ? null : -clamp(funding * 100, -1, 1) * 0.12);
+}
+
+function predictionFeatures(event, out) {
+  const market = finite(event.marketProbability ?? event.marketPrice ?? event.probability);
+  const fair = finite(event.fairProbability ?? event.referenceProbability ?? event.fairValue);
+  add(out, "probability_mispricing", market === null || fair === null ? null : clamp(fair - market, -1, 1) * 0.65);
+  const liquidity = finite(event.liquidityUsd ?? event.liquidity);
+  add(out, "market_liquidity", liquidity === null ? null : clamp(Math.log10(Math.max(1, liquidity)) / 6) * 0.12);
+}
+
+const FEATURE_BUILDERS = Object.freeze({
+  wallet: walletFeatures,
+  pool: poolFeatures,
+  nft_floor: nftFeatures,
+  hl_flow: hlFeatures,
+  prediction_market: predictionFeatures,
+});
+
+function markoutFor(event, id, markouts) {
+  const rows = markouts.filter((row) => {
+    const target = row?.signalId ?? row?.eventId ?? row?.id ?? row?.asset ?? row?.market;
+    return target != null && String(target) === id;
+  });
+  if (rows.length === 0) return null;
+  const values = rows.map((row) => finite(row.return ?? row.markout ?? row.pnl ?? row.value)).filter((value) => value !== null);
+  if (values.length === 0) return null;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+/** Pure, deterministic scoring of observed onchain events. It never fetches data or executes. */
+export function scoreSignals(events = [], markouts = [], options = {}) {
+  if (!Array.isArray(events) || !Array.isArray(markouts)) throw new TypeError("events and markouts must be arrays");
+  const minimumCoverage = clamp(finite(options.minimumCoverage) ?? 0.5);
+
+  return events.map((event, index) => {
+    const type = typeOf(event);
+    const id = idOf(event, index);
+    const builder = FEATURE_BUILDERS[type];
+    const contributions = [];
+    if (builder) builder(event, contributions);
+
+    const expected = type === "wallet" ? 2 : type === "pool" ? 3 : 2;
+    const coverage = round(clamp(contributions.length / expected));
+    const rawFeatureScore = contributions.reduce((sum, item) => sum + item.value, 0);
+    const markout = markoutFor(event, id, markouts);
+    const markoutContribution = markout === null ? 0 : clamp(markout, -1, 1) * 0.35;
+    if (markout !== null) add(contributions, "shadow_markout", markoutContribution);
+    const score = round(clamp(0.5 + rawFeatureScore + markoutContribution));
+    const markoutFactor = markout === null ? 0.8 : clamp(0.85 + markout * 0.3, 0.35, 1);
+    const confidence = round(clamp(coverage * markoutFactor));
+    const flags = ["COLD_INTELLIGENCE_ONLY", "NO_HOT_EXECUTION"];
+    if (!builder) flags.push("UNSUPPORTED_SIGNAL_TYPE");
+    if (coverage < minimumCoverage) flags.push("LOW_COVERAGE", "NO_TRADE");
+    if (confidence < 0.5) flags.push("LOW_CONFIDENCE", "NO_TRADE");
+    if (type === "pool" && (finite(event.ageHours ?? event.poolAgeHours) ?? Infinity) < 24) flags.push("NEW_POOL_RISK", "NO_TRADE");
+    if (markout !== null && markout < 0) flags.push("NEGATIVE_MARKOUT");
+
+    return {
+      id,
+      type,
+      score,
+      confidence,
+      coverage,
+      contributions,
+      flags: [...new Set(flags)],
+      noTrade: flags.includes("NO_TRADE"),
+      executionAllowed: false,
+    };
+  }).sort((a, b) => b.score - a.score || b.confidence - a.confidence || a.id.localeCompare(b.id));
+}
+
+export function createSignalsEngine(defaults = {}) {
+  return Object.freeze({
+    score(events, markouts = [], options = {}) {
+      return scoreSignals(events, markouts, { ...defaults, ...options });
+    },
+  });
+}
+
+export { SIGNAL_TYPES };

package/src/signals/index.mjs

@@ -0,0 +1 @@
+export { SIGNAL_TYPES, createSignalsEngine, scoreSignals } from "./engine.mjs";

package/src/watch-preferences.mjs

@@ -0,0 +1,85 @@
+/** Notification classes supported by Oracle watches. */
+export const WATCH_CATEGORIES = Object.freeze([
+  'price',
+  'wallet',
+  'risk',
+  'execution',
+  'security',
+  'nft',
+  'governance',
+  'system',
+]);
+
+const CATEGORY_SET = new Set(WATCH_CATEGORIES);
+
+function assertCategory(category) {
+  if (!CATEGORY_SET.has(category)) {
+    throw new TypeError(`Unknown watch category: ${String(category)}`);
+  }
+  return category;
+}
+
+function subscribedCategories(preferences = {}) {
+  const categories = preferences.subscribedCategories ?? [];
+  if (!Array.isArray(categories)) {
+    throw new TypeError('subscribedCategories must be an array');
+  }
+  return categories;
+}
+
+/** New users receive no category notifications until they explicitly opt in. */
+export function defaultPreferences() {
+  return { subscribedCategories: [] };
+}
+
+/** Return a new preference value with exactly one notification class enabled. */
+export function subscribe(preferences, category) {
+  assertCategory(category);
+  const current = subscribedCategories(preferences);
+  if (current.includes(category)) return { ...preferences, subscribedCategories: [...current] };
+  return { ...preferences, subscribedCategories: [...current, category] };
+}
+
+/** Return a new preference value with the requested notification class disabled. */
+export function unsubscribe(preferences, category) {
+  assertCategory(category);
+  const current = subscribedCategories(preferences);
+  return {
+    ...preferences,
+    subscribedCategories: current.filter((candidate) => candidate !== category),
+  };
+}
+
+/** Create a direct watch. Notifications are opt-in independently for every watch. */
+export function createWatch({ category, notify = false, ...watch } = {}) {
+  assertCategory(category);
+  if (typeof notify !== 'boolean') throw new TypeError('watch notify must be a boolean');
+  return { ...watch, category, notify };
+}
+
+function isMatchingNotifyingWatch(alert, watch) {
+  if (!watch || watch.notify !== true || watch.category !== alert.category) return false;
+  if (alert.watchId !== undefined && watch.id !== alert.watchId) return false;
+  return true;
+}
+
+/**
+ * Decide whether an alert may be delivered. This function only describes policy;
+ * it performs no scheduling or delivery.
+ */
+export function evaluateAlert(alert, preferences = defaultPreferences(), watch) {
+  if (!alert || typeof alert !== 'object') throw new TypeError('alert must be an object');
+  assertCategory(alert.category);
+
+  if (subscribedCategories(preferences).includes(alert.category)) {
+    return { deliver: true, reason: 'category-subscribed' };
+  }
+  if (isMatchingNotifyingWatch(alert, watch)) {
+    return { deliver: true, reason: 'watch-opt-in' };
+  }
+  return { deliver: false, reason: 'not-subscribed' };
+}
+
+export function shouldDeliverAlert(alert, preferences, watch) {
+  return evaluateAlert(alert, preferences, watch).deliver;
+}