@oracle-agent/oracle 0.14.0 → 0.15.0

package/src/equities/normalize.mjs

@@ -1,295 +0,0 @@
-// Symbol normalization for Oracle Equities.
-//
-// Every venue names the same underlying differently. This module resolves all of
-// those forms to ONE canonical Oracle symbol so the ranking engine compares like
-// with like.
-//
-// The governing rule is FAIL CLOSED. A wrong symbol match does not produce a
-// missing row, it produces a FABRICATED one: two different assets get differenced
-// and printed as an arbitrage that does not exist. Concretely, in the captured
-// fixtures the ticker "LIT" appears on hyperliquid_hip3 (dex hyna, mark 3.37) and
-// on arcus perps (mark 2.0379). A naive canonicalization merges them and prints a
-// ~6536bp spread. Those are two different underlyings sharing three letters. The
-// same trap exists for SKHX (1169.2) versus SKHY (153.61), both live on dex xyz.
-//
-// So: we never guess. Unknown or contested input returns
-// { ambiguous: true, candidates: [...] } and the caller must either supply an
-// explicit assetClass assertion or drop the row.
-//
-// Zero runtime dependencies. Node builtins only, via src/fixtures.mjs.
-
-import { getUniverse, getVenues } from './fixtures.mjs';
-
-// ---------------------------------------------------------------------------
-// canonical universe, sourced from fixtures/universe.json (the authority)
-// ---------------------------------------------------------------------------
-
-let canonicalSet;
-function canonical() {
-  canonicalSet ??= new Set(Object.keys(getUniverse()));
-  return canonicalSet;
-}
-
-let dexSet;
-function knownDexs() {
-  dexSet ??= new Set(Object.keys(getVenues().venues.hyperliquid_hip3.dexs));
-  return dexSet;
-}
-
-/**
- * Symbols that mean genuinely DIFFERENT underlyings on different venues.
- * Listed explicitly. Each entry must be disambiguated by the caller with an
- * assetClass assertion, and even then the result is never cross venue comparable.
- */
-export const CONTESTED_SYMBOLS = Object.freeze({
-  LIT: Object.freeze([
-    Object.freeze({
-      assetClass: 'etf',
-      description: 'Global X Lithium and Battery Tech ETF, an equity basket',
-      venues: Object.freeze(['hyperliquid_hip3']),
-    }),
-    Object.freeze({
-      assetClass: 'crypto',
-      description: 'a crypto perp listed under the same three letters',
-      venues: Object.freeze(['arcus']),
-    }),
-  ]),
-});
-
-/**
- * Venue unique names: pre IPO markets and synthetic baskets that exist on exactly
- * ONE venue in the captured fixtures. They map to themselves. They can never be
- * cross venue ranked because there is no second venue to compare against.
- *
- * Derived from fixtures/venues.json: symbols on dex vntl that appear nowhere else.
- * NOTE: WHEAT is on vntl AND xyz, so it is deliberately excluded here.
- */
-export const VENUE_UNIQUE_SYMBOLS = Object.freeze([
-  'SPACEX',
-  'OPENAI',
-  'ANTHROPIC',
-  'MAG7',
-  'SEMIS',
-  'ROBOT',
-  'INFOTECH',
-  'NUCLEAR',
-  'DEFENSE',
-  'ENERGY',
-  'BIOTECH',
-  'GOLDJM',
-  'SILVERJM',
-  'SOY',
-]);
-
-const VENUE_UNIQUE_SET = new Set(VENUE_UNIQUE_SYMBOLS);
-
-/**
- * Allowlist for the lowercase x suffix (Solana xStocks style: NVDAx -> NVDA).
- * The suffix is stripped ONLY for these bases, so a genuine ticker ending in a
- * lowercase x is never mangled. No fixture currently exercises this with real
- * data (no Solana or TON venue was captured), but the rule is cheap and correct
- * and a future adapter needs it.
- */
-export const XSTOCK_BASE_ALLOWLIST = Object.freeze([
-  'NVDA',
-  'TSLA',
-  'SPY',
-  'AAPL',
-  'COIN',
-  'AMZN',
-  'GOOGL',
-  'MSFT',
-]);
-
-const XSTOCK_BASE_SET = new Set(XSTOCK_BASE_ALLOWLIST);
-
-const QUOTE_SUFFIXES = Object.freeze(['-USD', '-USDC', '-USDT', '-PERP']);
-
-// ---------------------------------------------------------------------------
-// result shape
-// ---------------------------------------------------------------------------
-
-function resolved(symbolRaw, symbol, extra = {}) {
-  return Object.freeze({
-    ok: true,
-    ambiguous: false,
-    symbol,
-    symbolRaw,
-    dex: extra.dex ?? null,
-    applied: Object.freeze(extra.applied ?? []),
-    venueUnique: extra.venueUnique ?? false,
-    contested: extra.contested ?? false,
-    crossVenueComparable: extra.crossVenueComparable ?? true,
-    candidates: Object.freeze([]),
-    reason: null,
-  });
-}
-
-function unresolved(symbolRaw, reason, candidates = []) {
-  return Object.freeze({
-    ok: false,
-    ambiguous: true,
-    symbol: null,
-    symbolRaw: typeof symbolRaw === 'string' ? symbolRaw : null,
-    dex: null,
-    applied: Object.freeze([]),
-    venueUnique: false,
-    contested: false,
-    crossVenueComparable: false,
-    candidates: Object.freeze(candidates.map((c) => Object.freeze({ ...c }))),
-    reason,
-  });
-}
-
-// ---------------------------------------------------------------------------
-// public helpers
-// ---------------------------------------------------------------------------
-
-export function listCanonicalSymbols() {
-  return [...canonical()];
-}
-
-export function isCanonical(symbol) {
-  return typeof symbol === 'string' && canonical().has(symbol);
-}
-
-/**
- * Resolve a venue specific symbol form to its canonical Oracle symbol.
- *
- * @param {string} input        raw venue symbol, e.g. "xyz:NVDA", "NVDA-USD", "NVDAx"
- * @param {object} [options]
- * @param {string} [options.assetClass]  explicit assertion required to resolve a
- *                                       contested ticker. Never inferred.
- * @returns {object} frozen resolution record. Check `.ok` before using `.symbol`.
- */
-export function normalizeSymbol(input, options = {}) {
-  if (typeof input !== 'string') {
-    return unresolved(input, 'input must be a string');
-  }
-
-  const trimmed = input.trim();
-  if (trimmed.length === 0) {
-    return unresolved(input, 'input must be a nonempty symbol');
-  }
-
-  const applied = [];
-  let working = trimmed;
-  let dex = null;
-
-  // 1. dex namespace strip, allowlisted against the real HIP-3 dex list.
-  const colon = working.indexOf(':');
-  if (colon !== -1) {
-    const prefix = working.slice(0, colon);
-    const rest = working.slice(colon + 1);
-    if (prefix.length === 0 || rest.length === 0) {
-      return unresolved(input, 'malformed dex namespace');
-    }
-    if (!knownDexs().has(prefix)) {
-      return unresolved(input, `unknown dex namespace "${prefix}"`, [
-        {
-          assetClass: 'unknown',
-          description: `no HIP-3 dex named "${prefix}" in the captured fixtures`,
-          venues: [],
-        },
-      ]);
-    }
-    dex = prefix;
-    working = rest;
-    applied.push('dex-namespace-strip');
-  }
-
-  // 2. quote suffix strip (-USD and friends), case insensitive on the suffix only.
-  for (const suffix of QUOTE_SUFFIXES) {
-    if (working.length > suffix.length && working.toUpperCase().endsWith(suffix)) {
-      working = working.slice(0, working.length - suffix.length);
-      applied.push('quote-suffix-strip');
-      break;
-    }
-  }
-
-  // 3. lowercase x suffix strip, allowlist gated so a real ticker ending in a
-  //    lowercase x is never mangled. Uppercase X is NOT a suffix (see SKHX).
-  if (working.endsWith('x')) {
-    const base = working.slice(0, -1);
-    if (XSTOCK_BASE_SET.has(base)) {
-      working = base;
-      applied.push('xstock-suffix-strip');
-    }
-    // Not allowlisted: leave it alone and let the canonical check decide.
-  }
-
-  if (working.length === 0) {
-    return unresolved(input, 'symbol empty after transforms');
-  }
-
-  // 4. venue unique names (pre IPO, baskets) map to themselves.
-  if (VENUE_UNIQUE_SET.has(working)) {
-    return resolved(trimmed, working, {
-      dex,
-      applied,
-      venueUnique: true,
-      crossVenueComparable: false,
-    });
-  }
-
-  // 5. contested tickers: never guessed, require an explicit assetClass.
-  if (Object.hasOwn(CONTESTED_SYMBOLS, working)) {
-    const candidates = CONTESTED_SYMBOLS[working];
-    const asserted = options.assetClass;
-    if (typeof asserted !== 'string' || asserted.length === 0) {
-      return unresolved(
-        input,
-        `"${working}" names different underlyings on different venues, ` +
-          'caller must assert assetClass',
-        candidates,
-      );
-    }
-    const match = candidates.find((c) => c.assetClass === asserted);
-    if (!match) {
-      return unresolved(
-        input,
-        `assetClass "${asserted}" matches no known underlying for "${working}"`,
-        candidates,
-      );
-    }
-    return resolved(trimmed, working, {
-      dex,
-      applied,
-      contested: true,
-      crossVenueComparable: false,
-    });
-  }
-
-  // 6. canonical universe check. This is the fail closed gate.
-  if (canonical().has(working)) {
-    return resolved(trimmed, working, { dex, applied });
-  }
-
-  return unresolved(
-    input,
-    `"${working}" is not in the canonical universe, refusing to guess`,
-    nearMissCandidates(working),
-  );
-}
-
-/**
- * Suggest canonical symbols a caller might have meant, WITHOUT resolving to them.
- * Suggestions are diagnostic only. They are deliberately not auto applied: that is
- * exactly the fuzzy step that fabricates spreads.
- */
-function nearMissCandidates(working) {
-  const upper = working.toUpperCase();
-  const out = [];
-  for (const symbol of canonical()) {
-    if (symbol === upper) continue;
-    if (symbol.startsWith(upper) || upper.startsWith(symbol)) {
-      out.push({
-        assetClass: 'unknown',
-        description: `canonical "${symbol}" shares a prefix, not auto applied`,
-        venues: [],
-      });
-    }
-    if (out.length >= 5) break;
-  }
-  return out;
-}

package/src/equities/num.mjs

@@ -1,146 +0,0 @@
-const MAX_SCALE = 1000;
-const TEN_THOUSAND = Object.freeze({ mantissa: 10000n, scale: 0 });
-
-function assertScale(scale) {
-  if (!Number.isSafeInteger(scale) || scale < 0 || scale > MAX_SCALE) {
-    throw new RangeError(`scale must be a safe integer from 0 through ${MAX_SCALE}`);
-  }
-}
-
-function fixed(mantissa, scale) {
-  if (typeof mantissa !== 'bigint') {
-    throw new TypeError('mantissa must be a bigint');
-  }
-  assertScale(scale);
-  return Object.freeze({ mantissa, scale });
-}
-
-function assertFixed(value, name = 'value') {
-  if (value === null || typeof value !== 'object') {
-    throw new TypeError(`${name} must be a fixed point value`);
-  }
-  if (typeof value.mantissa !== 'bigint') {
-    throw new TypeError(`${name}.mantissa must be a bigint`);
-  }
-  assertScale(value.scale);
-}
-
-function pow10(scale) {
-  assertScale(scale);
-  return 10n ** BigInt(scale);
-}
-
-export function parseDecimal(value) {
-  if (typeof value !== 'string' || !/^[+-]?\d+(?:\.\d+)?$/.test(value)) {
-    throw new TypeError('value must be a plain decimal string');
-  }
-
-  const negative = value.startsWith('-');
-  const unsigned = value[0] === '-' || value[0] === '+' ? value.slice(1) : value;
-  const [whole, fraction = ''] = unsigned.split('.');
-  const digits = `${whole}${fraction}`;
-  const mantissa = BigInt(digits) * (negative ? -1n : 1n);
-
-  return fixed(mantissa, fraction.length);
-}
-
-export function fromScaledInteger(value, scale) {
-  assertScale(scale);
-  if (typeof value === 'bigint') {
-    return fixed(value, scale);
-  }
-  if (typeof value !== 'string' || !/^[+-]?\d+$/.test(value)) {
-    throw new TypeError('value must be an integer string or bigint');
-  }
-  return fixed(BigInt(value), scale);
-}
-
-export function toString(value) {
-  assertFixed(value);
-  const negative = value.mantissa < 0n;
-  const digits = (negative ? -value.mantissa : value.mantissa).toString();
-
-  if (value.scale === 0) {
-    return `${negative ? '-' : ''}${digits}`;
-  }
-
-  const padded = digits.padStart(value.scale + 1, '0');
-  const splitAt = padded.length - value.scale;
-  return `${negative ? '-' : ''}${padded.slice(0, splitAt)}.${padded.slice(splitAt)}`;
-}
-
-export function rescale(value, targetScale) {
-  assertFixed(value);
-  assertScale(targetScale);
-
-  if (targetScale === value.scale) {
-    return fixed(value.mantissa, value.scale);
-  }
-  if (targetScale > value.scale) {
-    return fixed(value.mantissa * pow10(targetScale - value.scale), targetScale);
-  }
-  return fixed(value.mantissa / pow10(value.scale - targetScale), targetScale);
-}
-
-function align(left, right) {
-  assertFixed(left, 'left');
-  assertFixed(right, 'right');
-  const scale = Math.max(left.scale, right.scale);
-  return [rescale(left, scale), rescale(right, scale), scale];
-}
-
-export function add(left, right) {
-  const [a, b, scale] = align(left, right);
-  return fixed(a.mantissa + b.mantissa, scale);
-}
-
-export function sub(left, right) {
-  const [a, b, scale] = align(left, right);
-  return fixed(a.mantissa - b.mantissa, scale);
-}
-
-export function mul(left, right) {
-  assertFixed(left, 'left');
-  assertFixed(right, 'right');
-  const scale = left.scale + right.scale;
-  assertScale(scale);
-  return fixed(left.mantissa * right.mantissa, scale);
-}
-
-export function div(left, right, resultScale = Math.max(left?.scale ?? 0, right?.scale ?? 0)) {
-  assertFixed(left, 'left');
-  assertFixed(right, 'right');
-  assertScale(resultScale);
-  if (right.mantissa === 0n) {
-    throw new RangeError('division by zero');
-  }
-
-  const numerator = left.mantissa * pow10(right.scale + resultScale);
-  const denominator = right.mantissa * pow10(left.scale);
-  return fixed(numerator / denominator, resultScale);
-}
-
-export function cmp(left, right) {
-  const [a, b] = align(left, right);
-  if (a.mantissa < b.mantissa) return -1;
-  if (a.mantissa > b.mantissa) return 1;
-  return 0;
-}
-
-export function spreadBps(value, reference, resultScale = 8) {
-  const delta = sub(value, reference);
-  return div(mul(delta, TEN_THOUSAND), reference, resultScale);
-}
-
-export function applyBps(value, bps, resultScale = value?.scale ?? 0) {
-  assertFixed(value);
-  assertFixed(bps, 'bps');
-  assertScale(resultScale);
-
-  const factor = fixed(10000n * pow10(bps.scale) + bps.mantissa, bps.scale);
-  return div(mul(value, factor), TEN_THOUSAND, resultScale);
-}
-
-export function formatUsd(value) {
-  return `$${toString(rescale(value, 2))}`;
-}

package/src/equities/prepare.mjs

@@ -1,95 +0,0 @@
-// Prepare-only artifact builder for RH Uniswap routes.
-// Emits unsigned transaction descriptors. Contains zero signing code and zero
-// key handling by construction. Refuses quote-only routes and stale quotes.
-
-import { quote as rhQuote } from './venues/rh-uniswap.mjs';
-import { getRhPoolState } from './fixtures.mjs';
-
-export const FRESHNESS_MS = 120_000;
-
-// Uniswap V3 SwapRouter02 style exactInputSingle selector, placeholder encoding.
-// The real calldata builder lands when a full router address is pinned. For v1
-// we emit a structured intent the user wallet / higher layer can encode.
-const V3_ROUTER = '0x0000000000000000000000000000000000000000'; // not yet pinned
-const V4_POOL_MANAGER = '0x84b75b19A3cdf8E2F56d0507d22D442847B2053C';
-
-/**
- * Prepare an unsigned swap artifact for a RH Uniswap equity pool.
- *
- * @param {object} opts
- * @param {string} opts.symbol
- * @param {'buy'|'sell'} [opts.side]
- * @param {object} [opts.sizeUsd]   fixed point
- * @param {number} [opts.nowMs]
- * @param {string} opts.recipient   user wallet, required
- */
-export function prepare(opts = {}) {
-  const { symbol, side = 'buy', sizeUsd = null, recipient, nowMs = Date.now() } = opts;
-
-  if (typeof symbol !== 'string' || !symbol) {
-    throw new TypeError('symbol is required');
-  }
-  if (typeof recipient !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(recipient)) {
-    throw new TypeError('recipient must be a 0x-prefixed 20 byte address');
-  }
-
-  const q = rhQuote({ symbol, side, sizeUsd });
-  if (q === null) {
-    throw new Error(`no RH Uniswap pool for ${symbol}`);
-  }
-  if (q.tier !== 'prepare') {
-    throw new Error(`route tier is ${q.tier}, only prepare tier can be prepared`);
-  }
-
-  const ageMs = nowMs - q.capturedAt;
-  if (ageMs > FRESHNESS_MS) {
-    throw new Error(
-      `quote is stale (${ageMs}ms old, bound ${FRESHNESS_MS}ms); re-quote before preparing`,
-    );
-  }
-
-  const state = getRhPoolState();
-  const pool = state.pools[symbol];
-  const to = pool.version === 'v4' ? V4_POOL_MANAGER : V3_ROUTER;
-
-  // Approval target is the router/pool manager, NEVER the destination of funds.
-  const spender = to;
-  const token = side === 'buy' ? pool.quoteAddr : pool.token;
-
-  return Object.freeze({
-    artifactKind: 'unsigned-tx',
-    chainId: 4663,
-    to,
-    data: '0x', // calldata encoding is a follow up; structure is the contract
-    value: '0',
-    requiresApproval: {
-      spender,
-      token,
-      amount: null, // exact amount filled by the caller from size
-    },
-    requiresWalletSignature: true,
-    backendSigner: false,
-    unsigned: true,
-    houseSigned: false,
-    quoteRef: {
-      venue: q.venue,
-      symbol: q.symbol,
-      symbolRaw: q.symbolRaw,
-      capturedAt: q.capturedAt,
-      blockOrSeq: q.blockOrSeq,
-      mid: q.mid,
-      version: pool.version,
-      pair: pool.pair,
-    },
-    quoteAgeMs: ageMs,
-    recipient,
-    side,
-    notes: [
-      'prepare-only: user wallet must sign',
-      'calldata encoding is deferred; this artifact is the bound intent',
-      pool.version === 'v4'
-        ? 'V4 route via PoolManager'
-        : 'V3 route via SwapRouter (address not yet pinned)',
-    ],
-  });
-}