@oracle-agent/oracle 0.14.0 → 0.15.0

package/src/equities/rank.mjs

@@ -1,260 +0,0 @@
-// Net-of-cost ranking engine.
-//
-// Ranks quotes after fees, gas, and impact at the requested size. Missing costs
-// force rankedOn: "gross" for that comparison and are never silently treated as
-// zero. Default mode segments by instrument (spot table vs perp table). Horizon
-// mode merges via funding carry and reports the breakeven hold duration.
-//
-// bestPreparable is independent of the overall winner so a quote-only best price
-// is never presented as actionable.
-
-import { filterQuotes } from './liveness.mjs';
-import { carryForQuote } from './funding.mjs';
-import { sessionState } from './marketHours.mjs';
-import {
-  add,
-  cmp,
-  div,
-  fromScaledInteger,
-  mul,
-  parseDecimal,
-  sub,
-  toString,
-} from './num.mjs';
-import { validateRankResult } from './types.mjs';
-
-function priceOf(quote) {
-  return quote.mid ?? quote.mark ?? quote.ask ?? quote.bid ?? null;
-}
-
-function netScore(quote) {
-  // Lower is better for a buy (you pay less). Higher is better for a sell.
-  // We normalize to a "cost to buy one unit" score so sorting is consistent.
-  const px = priceOf(quote);
-  if (px === null) return null;
-
-  let costAccounted = quote.costAccounted === true;
-  let extras = parseDecimal('0');
-
-  if (quote.fees !== null) {
-    // fees is a fraction of notional when from fee tier; when it's absolute we
-    // still add it. Adapters emit fee as a rate fraction or absolute; treat as
-    // absolute addend for v1 when scale suggests a small number.
-    extras = add(extras, quote.fees);
-  } else {
-    costAccounted = false;
-  }
-  if (quote.priceImpact !== null) {
-    extras = add(extras, quote.priceImpact);
-  } else if (quote.requestedSize && quote.requestedSize.mantissa > 0n) {
-    costAccounted = false;
-  }
-  if (quote.gasEstimate === null) {
-    costAccounted = false;
-  } else {
-    extras = add(extras, quote.gasEstimate);
-  }
-
-  // For a buy, net = price * (1 + feeRate-ish) + impact. We approximate by
-  // price + extras when extras are absolute fractions of 1 (fee rates).
-  // fee rates like 0.003 are added to 1 then multiplied.
-  // Detect rate-like fees (value < 1) vs absolute.
-  let net;
-  if (quote.fees !== null && cmp(quote.fees, parseDecimal('1')) < 0 && cmp(quote.fees, parseDecimal('0')) >= 0) {
-    const onePlus = add(parseDecimal('1'), quote.fees);
-    net = mul(px, onePlus);
-    if (quote.priceImpact !== null) net = add(net, mul(px, quote.priceImpact));
-  } else {
-    net = add(px, extras);
-  }
-
-  return { net, costAccounted, px };
-}
-
-function routeEntry(quote, score, carry = null) {
-  return {
-    venue: quote.venue,
-    chain: quote.chain,
-    instrument: quote.instrument,
-    tier: quote.tier,
-    symbol: quote.symbol,
-    symbolRaw: quote.symbolRaw,
-    side: quote.side,
-    price: score.px,
-    net: score.net,
-    costAccounted: score.costAccounted,
-    fundingHourly: quote.fundingHourly,
-    carry,
-    quote,
-  };
-}
-
-function improvementBps(winner, runner) {
-  if (!winner || !runner) return null;
-  if (!winner.costAccounted || !runner.costAccounted) return null;
-  if (winner.instrument !== runner.instrument) return null;
-  if (winner.net.mantissa === 0n) return null;
-  // For buys: how many bps cheaper is winner than runner.
-  const delta = sub(runner.net, winner.net);
-  return div(mul(delta, fromScaledInteger(10000n, 0)), runner.net, 4);
-}
-
-/**
- * Rank a list of quotes for one symbol.
- *
- * @param {object[]} quotes
- * @param {object} [opts]
- * @param {number} [opts.horizonHours]   if set, enable heterogeneous carry mode
- * @param {number} [opts.nowMs]
- * @param {boolean} [opts.skipLiveness]
- */
-export function rank(quotes, opts = {}) {
-  if (!Array.isArray(quotes)) throw new TypeError('quotes must be an array');
-
-  const nowMs = opts.nowMs ?? (quotes[0]?.capturedAt ?? Date.now());
-  const sourcesTried = quotes.length;
-  let working = quotes;
-  let excluded = [];
-
-  if (!opts.skipLiveness) {
-    const gate = filterQuotes(quotes, { nowMs });
-    working = gate.survivors;
-    excluded = gate.excluded;
-  }
-
-  const sourcesAnswered = quotes.length; // all inputs answered; failures come from callers
-  const failed = []; // ranking does not itself call adapters
-
-  const horizonHours = opts.horizonHours;
-  const heterogeneous = Number.isFinite(horizonHours) && horizonHours > 0;
-
-  // Score each survivor.
-  const scored = [];
-  for (const q of working) {
-    const score = netScore(q);
-    if (score === null) continue;
-    let carry = null;
-    if (heterogeneous && q.instrument === 'perp') {
-      carry = carryForQuote(q, horizonHours, { nowMs });
-      // Fold carry into net as an additive cost in price space is wrong dimensionally.
-      // Carry is in bps of notional; convert: net' = net * (1 + carryBps/10000)
-      if (carry.carryBps !== null) {
-        const factor = add(
-          parseDecimal('1'),
-          div(carry.carryBps, fromScaledInteger(10000n, 0), 12),
-        );
-        score.net = mul(score.net, factor);
-        // Carry is an estimate: never upgrade costAccounted.
-        score.costAccounted = false;
-      }
-    }
-    scored.push(routeEntry(q, score, carry));
-  }
-
-  // Segment.
-  let pool = scored;
-  let instrumentMix = 'homogeneous';
-  if (!heterogeneous) {
-    // Default: require a single instrument class. If mixed, rank each class
-    // separately and pick the class with more routes (spot preferred on tie).
-    const spots = scored.filter((r) => r.instrument === 'spot');
-    const perps = scored.filter((r) => r.instrument === 'perp');
-    if (spots.length > 0 && perps.length > 0) {
-      pool = spots.length >= perps.length ? spots : perps;
-      instrumentMix = 'homogeneous';
-    } else {
-      pool = scored;
-      instrumentMix = 'homogeneous';
-    }
-  } else {
-    instrumentMix = 'heterogeneous';
-    pool = scored;
-  }
-
-  // Sort ascending by net (best buy price first). Stable tie break on venue name.
-  pool.sort((a, b) => {
-    const c = cmp(a.net, b.net);
-    if (c !== 0) return c;
-    return a.venue < b.venue ? -1 : a.venue > b.venue ? 1 : 0;
-  });
-
-  const winner = pool[0] ?? null;
-  const runnersUp = pool.slice(1);
-  const ranked = pool;
-
-  // rankedOn: net-of-cost only when the top two both fully accounted; else gross.
-  let rankedOn = 'gross';
-  if (winner && winner.costAccounted && (runnersUp.length === 0 || runnersUp[0].costAccounted)) {
-    rankedOn = 'net-of-cost';
-  }
-  // One answering source is not a comparison.
-  const imp =
-    runnersUp.length === 0 ? null : improvementBps(winner, runnersUp[0]);
-
-  const bestPreparable =
-    scored.find((r) => r.tier === 'prepare') ?? null;
-
-  const session = sessionState(nowMs);
-  const darkWindow =
-    session === 'core'
-      ? null
-      : {
-          session,
-          warning:
-            session === 'dark'
-              ? 'market is dark; marks are not real price discovery'
-              : 'extended session; thinner books and higher staleness risk',
-        };
-
-  // Breakeven horizon between best spot and best perp (heterogeneous diagnostic).
-  let breakEvenHorizonHours = null;
-  if (heterogeneous) {
-    breakEvenHorizonHours = estimateBreakeven(scored);
-  }
-
-  const result = {
-    rankedOn,
-    ranked,
-    winner,
-    runnersUp,
-    improvementBps: imp === null ? null : Number(toString(imp)),
-    sourcesAnswered,
-    sourcesTried,
-    failed,
-    excluded,
-    darkWindow,
-    instrumentMix,
-    bestPreparable,
-    carry: winner?.carry ?? null,
-    breakEvenHorizonHours,
-  };
-
-  return validateRankResult(result);
-}
-
-function estimateBreakeven(scored) {
-  const bestSpot = scored
-    .filter((r) => r.instrument === 'spot')
-    .sort((a, b) => cmp(a.net, b.net))[0];
-  const bestPerp = scored
-    .filter((r) => r.instrument === 'perp')
-    .sort((a, b) => cmp(a.net, b.net))[0];
-  if (!bestSpot || !bestPerp || bestPerp.fundingHourly === null) return null;
-
-  // Entry gap in price space. Carry closes the gap at rate funding * price per hour.
-  // breakEvenHours ~= entryGap / (fundingHourly * perpPrice)
-  const gap = sub(bestSpot.net, bestPerp.net); // positive if spot more expensive
-  if (gap.mantissa === 0n) return 0;
-  // If perp is more expensive at entry and funding is positive (longs pay), gap never closes for a long.
-  const hourlyCarry = mul(bestPerp.fundingHourly, bestPerp.price);
-  if (hourlyCarry.mantissa === 0n) return null;
-  // hours = gap / hourlyCarry (only meaningful when signs agree)
-  try {
-    const hours = div(gap, hourlyCarry, 4);
-    const h = Number(toString(hours));
-    if (!Number.isFinite(h) || h < 0) return null;
-    return h;
-  } catch {
-    return null;
-  }
-}

package/src/equities/sourceNum.mjs

@@ -1,69 +0,0 @@
-// Source numbers arrive from venue JSON as IEEE 754 doubles. The numeric core in
-// src/num.mjs deliberately refuses JavaScript numbers, so every adapter needs one
-// audited crossing point from approximate source data into exact fixed point.
-//
-// This module is that crossing point. It exists so the conversion is written once
-// and tested once, rather than six adapters each inventing their own.
-//
-// Honesty boundary: converting a double to fixed point does NOT make it exact. It
-// makes it EXACTLY REPRESENTED. The value still carries whatever error the venue
-// and JSON parsing already introduced. Nothing here may be read as a precision
-// upgrade. See docs/NUMERIC.md.
-
-import { parseDecimal } from './num.mjs';
-
-// Number.prototype.toString gives the shortest string that round trips back to the
-// same double, which is the closest thing to source truth we can recover after
-// JSON.parse. Its one problem is exponent notation, which parseDecimal rejects on
-// purpose. So we expand it here rather than loosening the parser.
-export function numberToDecimalString(value) {
-  if (typeof value !== 'number' || !Number.isFinite(value)) {
-    throw new TypeError('value must be a finite number');
-  }
-
-  const text = String(value);
-  if (!text.includes('e') && !text.includes('E')) return text;
-
-  const [mantissaText, exponentText] = text.split(/[eE]/);
-  const exponent = Number(exponentText);
-  const negative = mantissaText.startsWith('-');
-  const unsigned = negative ? mantissaText.slice(1) : mantissaText;
-  const [whole, fraction = ''] = unsigned.split('.');
-  const digits = `${whole}${fraction}`;
-  // Decimal point currently sits after the whole part, then shifts by the exponent.
-  const pointIndex = whole.length + exponent;
-
-  let out;
-  if (pointIndex <= 0) {
-    out = `0.${'0'.repeat(-pointIndex)}${digits}`;
-  } else if (pointIndex >= digits.length) {
-    out = `${digits}${'0'.repeat(pointIndex - digits.length)}`;
-  } else {
-    out = `${digits.slice(0, pointIndex)}.${digits.slice(pointIndex)}`;
-  }
-
-  return `${negative ? '-' : ''}${out}`;
-}
-
-// Convert an approximate source number to fixed point. Returns null for null,
-// undefined, and non finite input so a missing venue field stays MISSING and
-// forces costAccounted false downstream. A missing number must never become zero.
-export function fromSourceNumber(value) {
-  if (value === null || value === undefined) return null;
-  if (typeof value === 'string') {
-    // Some venues publish decimal strings. Those are source truth, use them directly.
-    return parseDecimal(value);
-  }
-  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
-  return parseDecimal(numberToDecimalString(value));
-}
-
-// Same as fromSourceNumber but throws instead of returning null. Use only where a
-// field is structurally guaranteed by the fixture shape check.
-export function requireSourceNumber(value, label) {
-  const parsed = fromSourceNumber(value);
-  if (parsed === null) {
-    throw new TypeError(`${label} must be a finite source number`);
-  }
-  return parsed;
-}

package/src/equities/types.mjs

@@ -1,220 +0,0 @@
-const INSTRUMENTS = new Set(['spot', 'perp']);
-const TIERS = new Set(['read-only', 'quote-only', 'prepare', 'intent']);
-const SIDES = new Set(['buy', 'sell']);
-const RANKED_ON = new Set(['net-of-cost', 'gross']);
-const INSTRUMENT_MIXES = new Set(['homogeneous', 'heterogeneous']);
-const PRICE_FIELDS = ['bid', 'ask', 'mid', 'mark'];
-const COST_FIELDS = ['fees', 'gasEstimate', 'priceImpact', 'fundingHourly'];
-const MACHINE_REASON = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-
-function fail(path, message) {
-  throw new TypeError(`${path} ${message}`);
-}
-
-function isRecord(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function requireRecord(value, path) {
-  if (!isRecord(value)) fail(path, 'must be an object');
-}
-
-function requireOwn(value, key, path) {
-  if (!Object.hasOwn(value, key)) fail(`${path}.${key}`, 'is required');
-}
-
-function requireString(value, path) {
-  if (typeof value !== 'string' || value.length === 0) {
-    fail(path, 'must be a nonempty string');
-  }
-}
-
-function requireEnum(value, allowed, path) {
-  if (!allowed.has(value)) {
-    fail(path, `must be one of ${[...allowed].join(', ')}`);
-  }
-}
-
-function requireCount(value, path) {
-  if (!Number.isSafeInteger(value) || value < 0) {
-    fail(path, 'must be a nonnegative safe integer');
-  }
-}
-
-function requireFixed(value, path, nullable = false) {
-  if (value === null && nullable) return;
-  if (!isRecord(value)) fail(path, 'must be a fixed point value');
-  if (typeof value.mantissa !== 'bigint') fail(`${path}.mantissa`, 'must be a bigint');
-  if (!Number.isSafeInteger(value.scale) || value.scale < 0) {
-    fail(`${path}.scale`, 'must be a nonnegative safe integer');
-  }
-}
-
-function requireRoute(value, path, nullable = false) {
-  if (value === null && nullable) return;
-  requireRecord(value, path);
-}
-
-function validateOutcomeEntry(entry, path) {
-  requireRecord(entry, path);
-  requireString(entry.venue, `${path}.venue`);
-  requireString(entry.reason, `${path}.reason`);
-  if (!MACHINE_REASON.test(entry.reason)) {
-    fail(`${path}.reason`, 'must be a machine readable lower case code');
-  }
-  if (Object.hasOwn(entry, 'symbol') && entry.symbol !== null) {
-    requireString(entry.symbol, `${path}.symbol`);
-  }
-}
-
-export function validateQuote(quote) {
-  requireRecord(quote, 'quote');
-
-  for (const key of [
-    'venue',
-    'chain',
-    'instrument',
-    'tier',
-    'symbolRaw',
-    'symbol',
-    'side',
-    'requestedSize',
-    ...COST_FIELDS,
-    'costAccounted',
-    'capturedAt',
-    'blockOrSeq',
-    'raw',
-  ]) {
-    requireOwn(quote, key, 'quote');
-  }
-
-  requireString(quote.venue, 'quote.venue');
-  if (
-    !(typeof quote.chain === 'string' && quote.chain.length > 0) &&
-    !(Number.isSafeInteger(quote.chain) && quote.chain >= 0)
-  ) {
-    fail('quote.chain', 'must be a nonempty string or nonnegative chain id');
-  }
-  requireEnum(quote.instrument, INSTRUMENTS, 'quote.instrument');
-  requireEnum(quote.tier, TIERS, 'quote.tier');
-  requireString(quote.symbolRaw, 'quote.symbolRaw');
-  requireString(quote.symbol, 'quote.symbol');
-  requireEnum(quote.side, SIDES, 'quote.side');
-  requireFixed(quote.requestedSize, 'quote.requestedSize');
-  if (quote.requestedSize.mantissa < 0n) {
-    fail('quote.requestedSize', 'must not be negative');
-  }
-
-  let pricesFound = 0;
-  for (const field of PRICE_FIELDS) {
-    if (Object.hasOwn(quote, field)) {
-      requireFixed(quote[field], `quote.${field}`);
-      pricesFound += 1;
-    }
-  }
-  if (pricesFound === 0) {
-    fail('quote', 'must contain at least one of bid, ask, mid, mark');
-  }
-
-  for (const field of COST_FIELDS) {
-    requireFixed(quote[field], `quote.${field}`, true);
-  }
-  if (typeof quote.costAccounted !== 'boolean') {
-    fail('quote.costAccounted', 'must be a boolean');
-  }
-
-  if (quote.costAccounted) {
-    for (const field of ['fees', 'gasEstimate', 'priceImpact']) {
-      if (quote[field] === null) {
-        fail(`quote.${field}`, 'cannot be unknown when costAccounted is true');
-      }
-    }
-    if (quote.instrument === 'perp' && quote.fundingHourly === null) {
-      fail('quote.fundingHourly', 'cannot be unknown when costAccounted is true for a perp');
-    }
-  }
-  if (quote.instrument === 'spot' && quote.fundingHourly !== null) {
-    fail('quote.fundingHourly', 'must be null for a spot quote');
-  }
-
-  requireCount(quote.capturedAt, 'quote.capturedAt');
-  if (
-    quote.blockOrSeq !== null &&
-    !(typeof quote.blockOrSeq === 'string' && quote.blockOrSeq.length > 0) &&
-    !(Number.isSafeInteger(quote.blockOrSeq) && quote.blockOrSeq >= 0)
-  ) {
-    fail('quote.blockOrSeq', 'must be null, a nonempty string, or a nonnegative safe integer');
-  }
-  requireRecord(quote.raw, 'quote.raw');
-
-  return quote;
-}
-
-export function validateRankResult(result) {
-  requireRecord(result, 'rankResult');
-
-  for (const key of [
-    'rankedOn',
-    'ranked',
-    'winner',
-    'runnersUp',
-    'improvementBps',
-    'sourcesAnswered',
-    'sourcesTried',
-    'failed',
-    'excluded',
-    'darkWindow',
-    'instrumentMix',
-    'bestPreparable',
-  ]) {
-    requireOwn(result, key, 'rankResult');
-  }
-
-  requireEnum(result.rankedOn, RANKED_ON, 'rankResult.rankedOn');
-  if (!Array.isArray(result.ranked)) fail('rankResult.ranked', 'must be an array');
-  result.ranked.forEach((route, index) => requireRoute(route, `rankResult.ranked[${index}]`));
-
-  requireRoute(result.winner, 'rankResult.winner', true);
-  if (result.ranked.length === 0 && result.winner !== null) {
-    fail('rankResult.winner', 'must be null when ranked is empty');
-  }
-  if (result.ranked.length > 0 && result.winner === null) {
-    fail('rankResult.winner', 'must be present when ranked is not empty');
-  }
-
-  if (!Array.isArray(result.runnersUp)) fail('rankResult.runnersUp', 'must be an array');
-  result.runnersUp.forEach((route, index) =>
-    requireRoute(route, `rankResult.runnersUp[${index}]`),
-  );
-
-  if (
-    result.improvementBps !== null &&
-    !(typeof result.improvementBps === 'number' && Number.isFinite(result.improvementBps))
-  ) {
-    fail('rankResult.improvementBps', 'must be a finite number or null');
-  }
-
-  requireCount(result.sourcesAnswered, 'rankResult.sourcesAnswered');
-  requireCount(result.sourcesTried, 'rankResult.sourcesTried');
-  if (result.sourcesAnswered > result.sourcesTried) {
-    fail('rankResult.sourcesAnswered', 'must not exceed sourcesTried');
-  }
-
-  if (!Array.isArray(result.failed)) fail('rankResult.failed', 'must be an array');
-  result.failed.forEach((entry, index) => validateOutcomeEntry(entry, `failed[${index}]`));
-
-  if (!Array.isArray(result.excluded)) fail('rankResult.excluded', 'must be an array');
-  result.excluded.forEach((entry, index) => validateOutcomeEntry(entry, `excluded[${index}]`));
-
-  if (result.darkWindow !== null) {
-    requireRecord(result.darkWindow, 'rankResult.darkWindow');
-  }
-  requireEnum(result.instrumentMix, INSTRUMENT_MIXES, 'rankResult.instrumentMix');
-  requireRoute(result.bestPreparable, 'rankResult.bestPreparable', true);
-
-  if (Object.hasOwn(result, 'carry') && result.carry !== null) {
-    requireRecord(result.carry, 'rankResult.carry');
-  }
-
-  return result;
-}

package/src/equities/venues/arcus-perp.mjs

@@ -1,84 +0,0 @@
-// Arcus perpetual markets on Robinhood Chain 4663.
-// Tier: quote-only. Reports mark, oracle, funding, RTH flags, and margin fractions
-// exactly as the fixture captured them. Dark-window funding is locked to the SOFR
-// + 0.5% hourly constant; that constant is surfaceable from the fixture so
-// funding.mjs can apply it without re-deriving SOFR.
-
-import { getVenues } from '../fixtures.mjs';
-import { fromSourceNumber, requireSourceNumber } from '../sourceNum.mjs';
-import { parseDecimal } from '../num.mjs';
-import { validateQuote } from '../types.mjs';
-
-export const VENUE = 'arcus_perp';
-export const CHAIN = 'robinhood-4663';
-export const TIER = 'quote-only';
-
-// Locked dark-window hourly funding: SOFR + 0.5% annualized, held constant.
-// Verified exact string round trip through the fixed point core.
-export const DARK_WINDOW_FUNDING_HOURLY = '0.00000480324074074';
-
-function arcus() {
-  return getVenues().venues.arcus;
-}
-
-export function listMarkets() {
-  return Object.keys(arcus().markets).sort();
-}
-
-export function quote({ symbol, side = 'buy', sizeUsd = null } = {}) {
-  if (typeof symbol !== 'string' || symbol.length === 0) return null;
-  // Accept both NVDA and NVDA-USD forms.
-  const bare = symbol.endsWith('-USD') ? symbol.slice(0, -4) : symbol;
-  const market = arcus().markets[bare];
-  if (!market) return null;
-
-  const mark = requireSourceNumber(market.mark, `${bare}.mark`);
-  const oracle = fromSourceNumber(market.oracle);
-  const funding = fromSourceNumber(market.fundingHourly);
-  const requested = sizeUsd === null ? parseDecimal('0') : sizeUsd;
-
-  const q = {
-    venue: VENUE,
-    chain: CHAIN,
-    instrument: 'perp',
-    tier: TIER,
-    symbolRaw: symbol,
-    symbol: bare,
-    side,
-    requestedSize: requested,
-    mark,
-    fees: null,
-    gasEstimate: null,
-    priceImpact: null,
-    fundingHourly: funding,
-    costAccounted: false,
-    capturedAt: getVenues().capturedAt * 1000,
-    blockOrSeq: null,
-    raw: {
-      fixture: 'fixtures/venues.json#venues.arcus',
-      oraclePrice: market.oracle,
-      vol24h: market.vol24h,
-      oi: market.oi,
-      fundingAnnPct: market.fundingAnnPct,
-      category: market.category,
-      isOutsideRth: market.isOutsideRth === true,
-      rth: market.rth,
-      // Surface the locked dark-window constant so funding.mjs does not re-derive it.
-      darkWindowFundingHourly: DARK_WINDOW_FUNDING_HOURLY,
-      // Margin fractions are not always in the fixture. Surface when present.
-      initialMarginFraction: market.initialMarginFraction ?? null,
-      offHoursInitialMarginFraction: market.offHoursInitialMarginFraction ?? null,
-      reasonCostUnknown: 'fees, gas, and impact at size not captured for Arcus perps',
-    },
-  };
-
-  if (oracle !== null) q.raw.oracleFixed = oracle;
-
-  return validateQuote(q);
-}
-
-export function quoteAll({ side = 'buy', sizeUsd = null } = {}) {
-  return listMarkets()
-    .map((symbol) => quote({ symbol, side, sizeUsd }))
-    .filter((q) => q !== null);
-}