Build Roadmap

Status types and fields

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

latency = p50 and p95 of measured round-trip ms over a rolling window (null if no sample). age = now - lastSuccessAt. rateLimitHeadroom = 1 - used/limit from response headers only (null if the provider sends none). errorRate = errors/requests over the window with N shown. healthScore H = sum(w_i * c_i)/sum(w_i) over measured components c_i in [0,1] (freshness, 1-errorRate, latency vs. budget, auth ok, headroom); a missing component is dropped and the weights renormalised; with no component H = null (SKIP), never 0 or 50. H is an operational indicator, not a prediction score.

Steps

1. Inventory the existing fields in /api/admin/connections rows and the api-health registry; list which of the 11 dashboard fields already exist and which do not.
2. Add missing fields to the row type as optional/nullable (typed) with the source of each value documented.
3. Compute p50/p95 latency, error rate and rate-limit headroom from the instrumented-fetch ring (no new network calls).
4. Compute health score H with renormalised weights and a visible per-component breakdown (founder approves the weights; they are operational, not trading weights).
5. Render read-only columns on /admin/connections; reconnect and backup shown as state, actions stay on the existing operator-gated POST route.
6. Add unit tests: null in, null out; status mapping is total; no zero-fill.

Best option

Extend the existing /admin/connections snapshot (one source of truth) rather than a new dashboard route.

Risks

Adding probes would burn provider rate limits (GeckoTerminal 429); stay passive-read. Health score weights are subjective, so show components next to the number.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• No Socket.IO on the market path; server-side feeds and REST/SSE only.
• Score gates stay S>=75 (spot) and S>=88 (futures) untouched; weights.json and score formulas untouched; p-star stays blank until N>=200.

Formula

retry delay d_n = min(cap, base * 2^n) * (1 + U(0, j)) with full jitter, n = attempt index, max attempts fixed per provider; honour Retry-After when present (hold, never hammer). Circuit breaker: open after f failures in a window of W calls, half-open probe after cooldown. timeout = per-provider p99 latency * m, bounded. dedupe key = hash(method, url, normalised body) with in-flight coalescing (one upstream call serves all waiters). Backup provider is used only if its data is real for the same field; otherwise the field stays null.

Steps

1. Audit current retry/timeout code in instrumented-fetch, circuit-breaker.ts and the rails; record gaps per provider.
2. Define one RepairPolicy type (retry, timeout, reconnect, backup order, normalizer, dedupe, log level) per provider.
3. Wrap fetches with the policy; keep 429 handling as hold/pacing (GeckoTerminal).
4. Normalise responses to one typed shape with units; reject, never coerce, malformed fields to 0.
5. Coalesce duplicate in-flight requests; add dedupe of repeated events by stable id.
6. Structured log of every retry, reconnect and backup switch, visible in /api/admin/api-errors.
7. Tests with fake timers: backoff bounds, breaker transitions, Retry-After, no zero-fill on parse failure.

Best option

Build on the existing circuit-breaker and instrumented-fetch modules and migrate providers one at a time behind the same interface.

Risks

A badly tuned retry multiplies load during an outage; the breaker and Retry-After hold are mandatory. Backup providers may disagree, so never average silently.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• No Socket.IO on the market path; server-side feeds and REST/SSE only.
• LIVE_MONEY stays false; ibot-engine, nginx, pod start command and env/deploy settings are not touched.

Exchange data

Not measured yet. The exchange snapshot was not read, so no line is counted.

Formula

mid = (bestBid + bestAsk)/2; spread_bps = 10^4 * (ask - bid)/mid; depth_k = sum of notional within k bps of mid per side; book imbalance OBI = (B - A)/(B + A) over the same depth (null if either side empty). Cross-venue volume = sum of per-venue quote volume converted with a measured quote price, each venue listed with its own freshness; stale venues are excluded and counted, not zero-filled. Funding annualised = rate * (8760 / interval_hours). OI change = (OI_t - OI_{t-w})/OI_{t-w}, null if either point is missing. Liquidation notional = sum(price * qty) of reported liquidation events in the window.

Steps

1. Build the venue matrix (rows: venue; columns: spot, futures, orderbook, funding, OI, liquidations, trades, depth, candles, streams) from real worker rails; mark every cell one of measured / REST-only / not offered / not wired.
2. Fill gaps one venue at a time via server-side REST or WS in the worker, with the repair framework policy.
3. OKX REST slot: OKX ticker, trades (coverage cursor) and top-5 books by REST only, paced; no socket feeds it and it is not added to the hub quotes. REST-only venues: REST polling only, paced; no stream is claimed.
4. Normalise symbols and units in market-normalizer; one canonical symbol map.
5. Store with timestamps; expose freshness per cell on /futures-data-v2 and /admin/connections.
6. Tests: unit conversion, empty side gives null, stale excluded, REST-only venues claim no WS.

Best option

Extend the existing worker rails and venue-board rather than adding a new data service; widen venue by venue with proof of live data.

Risks

Venue rate limits and bans; WS reconnect storms; symbol-mapping mistakes causing wrong-coin data.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• No Socket.IO on the market path; server-side feeds and REST/SSE only.
• REST-only venues stay REST; no browser-side exchange connections.

Whale parts

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

For each measured component i: z_i = clip((x_i - median_i)/(1.4826*MAD_i), -3, 3)/3 in [-1,1] using that asset's own rolling baseline. Exchange net flow x = inflow - outflow (positive inflow = potential sell pressure). Accumulation/distribution x = sum of signed net wallet balance change of verified accumulators over distributors / circulating supply. Dormant activation = count and value of wallets idle for >= D days that move. whaleScore W = 50 + 50 * sum(w_i * z_i)/sum(w_i) mapped to [0,100] over components that are measured; if no component is measured, W = null (SKIP). Never zero-filled; never 50 by default; component weights are proposals for founder approval and do not alter weights.json.

Steps

1. Source audit: list ~30 candidate whale sources with chain, auth, rate limit, latency, coverage, licence; mark each LIVE-proven / unproven / rejected, with evidence link.
2. Wallet classification: exchange, stablecoin issuer, institutional/treasury, smart money (by realised PnL track), dormant, unknown. Only labelled by a cited source; no guessed labels.
3. Address registry: each address stores source URL and verification date; unverified addresses are not stored or shown.
4. Compute exchange flow, stablecoin flow, institutional, smart-money, dormant and cross-chain components separately, each with N and freshness.
5. Combine into whale score W with the renormalised formula; show per-component contribution.
6. Feed W to the existing whale leg only after paper shadow of at least 28 days; leg gate logic unchanged.
7. Tests: null in gives null out; zero stays zero; unverified address rejected.

Best option

Build on whale-rail and hl-whales (existing verified rails) and add sources one by one, keeping each source's proof next to it.

Risks

Label errors (a wrong exchange tag flips the sign); chain reorgs; paid APIs. Proxy large-print data must stay labelled PROXY, not wallet LIVE.

Hard-rule checks

• Whale and DEX legs compute-or-SKIP: null, never zero, when inputs are missing; never fabricate a whale address (verified addresses only).
• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• Score gates stay S>=75 (spot) and S>=88 (futures) untouched; weights.json and score formulas untouched; p-star stays blank until N>=200.

DEX parts

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

Pool liquidity change = (L_t - L_{t-w})/L_{t-w}. Swap imbalance = (buyUSD - sellUSD)/(buyUSD + sellUSD) from real swap counts/volumes, null when counts are missing. Cross-DEX price difference in bps = 10^4 * (p_A - p_B)/mean(p_A, p_B) only between pools above a minimum liquidity floor, reported net of nothing and labelled gross. New-pair age = now - poolCreatedAt. Trending rank = rank of z-scored volume growth over a rolling window. The DEX score is computed from measured inputs only; if swap counts or liquidity are missing the leg is SKIP (null), never zero.

Steps

1. List provider endpoints in use (DexScreener, GeckoTerminal) with real rate limits; keep the 429 hold: on 429, stop that provider for Retry-After or a fixed cool-down and serve last-good with age shown.
2. Pool and token scanners by chain with liquidity floor; store creation time and pair age.
3. Swap and volume scanners using provider-reported counts; mark windows where provider gives none as missing.
4. Trending and new-pair lists with age and liquidity displayed; no ranking of pairs below the floor.
5. Cross-DEX price difference only for same-token pools; flag low-liquidity as not tradable.
6. Tests: 429 pacing (fake timers), null never zero, below-floor pools excluded.

Best option

Extend dex-rail with the existing gecko-gate pacing; add scanners as read-only views before any score use.

Risks

Rate-limit bans; wash trading and fake liquidity on new pairs; honeypot tokens must not be presented as opportunities.

Hard-rule checks

• Whale and DEX legs compute-or-SKIP: null, never zero, when inputs are missing; never fabricate a whale address (verified addresses only).
• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• Score gates stay S>=75 (spot) and S>=88 (futures) untouched; weights.json and score formulas untouched; p-star stays blank until N>=200.

Prediction inputs

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

Each signal j yields a direction-signed score s_j in [-1,1] or null. Ensemble E = sum(w_j * s_j)/sum(w_j) over non-null signals (weighted vote); if none, E = null. Explanation = the top-k signals by |w_j * s_j| with their raw inputs and timestamps. Multi-timeframe: signals computed per timeframe only from candles closed before decision time t (feature timestamp < t) so there is no look-ahead; targets use t+h strictly after. Probability, when shown, is calibrated on out-of-sample data (see M09) and blank until N >= 200. Existing execution gates are unchanged: S >= 75 spot, S >= 88 futures (score points, not percentages).

Steps

1. Write the signal contract: name, input fields with timestamps, output in [-1,1] or null, missing reason.
2. Map each of the 13 signal families to existing code or mark not built.
3. Implement the ensemble as a weighted vote with renormalised weights; weights are proposals through M09, not edited here.
4. Attach explanation (top contributors, inputs, timestamps, model version) to every prediction; refuse to publish one without it.
5. Look-ahead guard test: replay on stored history and assert every feature timestamp < decision time.
6. Walk-forward evaluation only (train on past, test on later) with embargo equal to the horizon.

Best option

Keep P200 predict-v2 as the base and add signal families as optional legs that default to SKIP until proven in paper.

Risks

Overfitting with many correlated signals; leakage via future-aligned candles; presenting the ensemble value as a probability before calibration.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• No fixed win-rate label or percentage; any accuracy shown is measured (Brier / calibration) with its sample size N.
• Score gates stay S>=75 (spot) and S>=88 (futures) untouched; weights.json and score formulas untouched; p-star stays blank until N>=200.
• Every prediction has an explanation; no look-ahead.

Pattern memory

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

Snapshot vector v_t of normalised features. Historical similarity = cosine(v_t, v_s) or Euclidean distance on z-scored features for past states s with s < t - horizon. Take the k nearest neighbours; empirical outcome frequency p = (#up outcomes)/k with a Wilson interval; confidence = interval width and N, never a fixed number. Signal order: record the timestamp order of threshold crossings before each move. Sector rotation: rank change of sector returns, sector defined by data (return correlation clusters), not by hand. Return null when k < Nmin.

Steps

1. Define move events (e.g. |return| beyond a rolling volatility multiple) from real candles.
2. Store the pre-move signal sequence with timestamps, lags and what moved after.
3. Build the neighbour search over past states only (no future rows).
4. Report p with Wilson interval, N and age of the memory; hide below Nmin.
5. Sector rotation from clustered correlations (M08).
6. Tests: no future neighbour ever returned; null below Nmin.

Best option

Extend the existing similarity-engine with an explicit time cut-off and a stored event log.

Risks

Regime change makes old patterns stale; small N produces overconfident p; survivorship bias if delisted coins are dropped.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• No fixed win-rate label or percentage; any accuracy shown is measured (Brier / calibration) with its sample size N.
• No look-ahead: neighbours strictly older than the decision time.

Coin relationships

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

Lagged cross-correlation rho(k) = corr(r_A[t], r_B[t+k]) over rolling windows of log returns, k in [-K, K]; significance by |rho| > z/sqrt(n_eff) with multiple-testing correction (Benjamini-Hochberg) and a shuffle/permutation test. Granger-style: regress r_B[t] on its own L lags (restricted) and on L lags of r_A as well (full); F = ((RSS_r - RSS_f)/L)/(RSS_f/(n - 2L - 1)); report p-value, never causality claims. Rolling beta beta = cov(r_A, r_M)/var(r_M). Dominance effect: partial correlation of alt returns on BTC dominance change controlling for BTC return. Inverse correlation = significantly negative rho. Pairs with too few observations are null.

Steps

1. Use aligned closed-candle log returns only; drop missing bars instead of filling.
2. Compute rho(k) per pair on rolling windows; keep only pairs passing the corrected significance test.
3. Granger-style F test on stationary returns; record p and lag.
4. Rolling beta against BTC and ETH; dominance partial correlation.
5. Store relationships with window, N and last-tested time; expire if no longer significant.
6. Tests on synthetic series with a known planted lag recover that lag; independent noise yields no significant pairs beyond the false-discovery rate.

Best option

Reuse causal-math.ts and fetch-causal.ts, adding the multiple-testing correction and permutation checks.

Risks

Spurious correlations from common drivers; non-stationarity; look-ahead from misaligned timestamps.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• Nothing hard-coded: no fixed coin-pair lists; relationships are learned and re-tested.

AI learning loop

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

Brier score BS = (1/N) * sum (p_i - o_i)^2 with o_i in {0,1}. Calibration: bin predictions by p, compare mean p with observed frequency per bin; ECE = sum_b (n_b/N) * |acc_b - conf_b|. Directional accuracy is reported with N and a Wilson interval, never as a fixed label. Error analysis groups misses by regime, venue, signal family. A weight proposal is a vector delta computed offline on out-of-sample data, shown as a diff; it is NOT applied automatically. p-star stays blank until N >= 200.

Steps

1. Log every prediction with model version, features hash, time and horizon (append-only).
2. Resolve outcomes at horizon end from real prices; unresolved stay unresolved.
3. Compute Brier, ECE, calibration curve and directional accuracy with N and intervals; blank when N < 200 for p-star.
4. Error analysis report by regime/venue/signal family.
5. Generate a weight proposal as a reviewable diff; founder approves manually; applied only via the normal reviewed change process.
6. Promotion rule: at least 28 days paper with measured metrics before any live consideration; LIVE_MONEY remains false.

Best option

Extend learn-loop and shadow-metrics; keep proposals as documents, not automatic writes.

Risks

Feedback loops that overfit to recent data; peeking at the test period; changing weights without audit trail.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• No fixed win-rate label or percentage; any accuracy shown is measured (Brier / calibration) with its sample size N.
• Score gates stay S>=75 (spot) and S>=88 (futures) untouched; weights.json and score formulas untouched; p-star stays blank until N>=200.
• LIVE_MONEY stays false; ibot-engine, nginx, pod start command and env/deploy settings are not touched.
• Weights change only via founder-approved process; paper >= 28 days before live.

Performance

Not measured yet. The connections snapshot has not been read, so no line is counted.

Formula

Latency percentiles p50/p95/p99 from request timing (server timing headers). Payload ratio = compressedBytes/rawBytes. Cache hit ratio = hits/(hits+misses). Budget check: improvement counts only if p95 before vs after is measured on the same endpoint under comparable load; report both numbers. Bundle size = gzip bytes per route chunk from the build output. Query cost = measured ms per query and rows scanned (EXPLAIN).

Steps

1. Baseline: record p50/p95 of the heaviest endpoints (universe, scan batch, connections) and route chunk sizes.
2. Background refresh store: serve last-good with age; refresh off the request path.
3. Universe body: ETag/304, field trimming, compression.
4. Caching headers and in-memory TTL per endpoint, honest age shown to the client.
5. Bundle: split heavy routes, lazy-load charts, drop unused dependencies.
6. DB: EXPLAIN slow queries; add indexes via reviewed migrations only.
7. Re-measure and publish before/after.

Best option

Measure first, then fix the top three bottlenecks; reuse refresh-store and json-etag already present.

Risks

Caching can serve stale data; must show age. Compression CPU cost on small bodies.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No Socket.IO on the market path; server-side feeds and REST/SSE only.
• LIVE_MONEY stays false; ibot-engine, nginx, pod start command and env/deploy settings are not touched.
• Cached values always show their age; stale is never presented as live.

Security

Not measured yet. The connections snapshot has not been read, so no line is counted.

<script>alert(1)</script>

Formula

Checklist, not a score. Rate limit as token bucket: tokens refill at r per second up to burst b; request allowed iff tokens >= 1. Validation: every external input parsed by a schema; unknown fields rejected. CSRF: state-changing routes require a same-site cookie and an origin check. Each finding records severity, evidence and fix; unresolved findings stay open, none is marked fixed without a test.

Steps

1. Inventory every POST/DELETE route (reconnect, test, session, tv-alert, auth) and its auth requirement.
2. Secrets: confirm none in the repo or client bundle; rotate through the deploy settings by the founder, not by code.
3. Add schema validation to each mutating handler.
4. Add rate limits to login and mutating routes.
5. XSS: audit any dangerouslySetInnerHTML; CORS: explicit allow-list; CSRF origin check.
6. Security headers (CSP, HSTS, frame, referrer, content-type) set in the app layer only; nginx is not touched.
7. Tests for each rule and a regression test for the auth invariant script.

Best option

Fix the auth and mutating-route findings first, as they have the highest impact, and keep header work in the app code.

Risks

A strict CSP can break existing inline scripts; rate limits can lock out the operator.

Hard-rule checks

• LIVE_MONEY stays false; ibot-engine, nginx, pod start command and env/deploy settings are not touched.
• No secret values appear in this page, the repo or logs; env/deploy settings and nginx are not touched.

Formula

No trading formula. Acceptance measures: contrast ratio >= 4.5:1 for body text (WCAG), tap target >= 44 px, layout checked at 360, 768, 1280 px widths, every data view has distinct loading, empty, error and stale states (no blank-as-zero).

Steps

1. Audit current tokens and components; list inconsistencies.
2. Founder chooses the design direction; document tokens (colour, spacing, type).
3. Chart component with real series only and a visible gap for missing data.
4. Dark mode via tokens; responsive pass per page.
5. Standard loading, empty, error and stale components used across pages.
6. Visual review in a browser at the three widths before release.

Best option

Introduce tokens and shared state components first, then restyle page by page.

Risks

Visual regressions on dense tables; charts that interpolate over missing data would hide gaps.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No 50/50 or neutral-50 default anywhere: unknown stays null.
• No fixed win-rate label or percentage; any accuracy shown is measured (Brier / calibration) with its sample size N.
• Charts never interpolate or draw zero for missing values.

Formula

Counts that must go down or stay at zero: tsc errors (baseline in typecheck-baseline.txt), eslint errors, unused exports, import cycles. A change is accepted only if the count after <= before and the full test suite and build pass.

Steps

1. Record the baselines: typecheck, lint, unused exports and import cycles.
2. Dead code: list unused files/exports with a tool, review by hand, then delete in small commits.
3. Fix type errors and lint errors in batches; never silence with ts-ignore without a comment.
4. Detect import cycles and break them.
5. CI: keep the test and build jobs required; add typecheck and lint once they are at zero.
6. Archive/attachment folders reviewed with the founder before removal.

Best option

Ratchet: fail CI on new type or lint errors while old ones are burned down.

Risks

Deleting code that only the worker or scripts import; run the full tests and build before each removal.

Hard-rule checks

• Score gates stay S>=75 (spot) and S>=88 (futures) untouched; weights.json and score formulas untouched; p-star stays blank until N>=200.
• LIVE_MONEY stays false; ibot-engine, nginx, pod start command and env/deploy settings are not touched.
• Do not touch ibot-engine, weights.json or score formulas while cleaning.

Formula

Coverage by contract, not by percentage target: each module must have (a) a doc with formula and sources, (b) unit tests for null-handling, bounds and look-ahead, (c) a live check. A module is Done only when all three exist and CI is green.

Steps

1. Per module: a doc page with inputs, formula, limits and honest unknowns.
2. Unit tests added to the npm test script for each new file.
3. Property tests for math helpers (bounds, null in gives null out).
4. Post-deploy checklist: version commit, page loads, key numbers non-null.
5. Keep PREDICTION_FORMULA.md as the single math source; update on any formula change approved by the founder.

Best option

Docs and tests are written in the same commit as the code they cover.

Risks

Docs drifting from code; tests that assert implementation instead of the contract.

Hard-rule checks

• No fake or placeholder data: a missing input renders as missing (null / SKIP / —), never as a made-up number.
• No fixed win-rate label or percentage; any accuracy shown is measured (Brier / calibration) with its sample size N.
• Score gates stay S>=75 (spot) and S>=88 (futures) untouched; weights.json and score formulas untouched; p-star stays blank until N>=200.