release(v0.15.1): Polaris — WR diagnostics + per-user accuracy + reset hygiene

[imzzaidd]

Release v0.15.1 "Polaris"

Patch release on top of v0.15.0 "Orion". 11 commits covering the
WR diagnostics layer, per-user accuracy correctness, and the
reset / ghost-DM hygiene cluster surfaced during live operator
testing on 2026-05-21/22.

The release builds toward the operator's standing target of 70%+
tracked decisive WR by raising the emission bar, hard-skipping
unsafe-cycle calls, accelerating warmup exits, and giving the
operator runtime visibility into which signals are dragging WR
down.

---

A — Polaris diagnostics layer

A complete per-signal WR observability + correction loop. Every
signal now has a measured decisive WR, the engine can invert or
dampen a signal whose sign is flipped, and the operator can pin
overrides at runtime.

• A1 — signal_outcomes SQLite table: per-prediction per-
  signal vote + outcome rows written by the resolver. Source of
  truth for all per-signal accuracy queries.
• A2 — Signal auditor: rolling WR-driven classifier per
  signal (INVERT / DAMPEN / WATCH / KEEP) over configurable
  window + sample threshold.
• A3 — Signal-polarity registry: runtime sign + cap
  overrides applied before composite assembly. Supports both
  auto (auditor-driven) and manual (operator-pinned) modes.
  Persisted to signal_polarity.
• A4 — /wr-diagnose Telegram command: per-signal WR
  breakdown with inversion / dampen / watch sections + active
  overrides.
• A5 — /signal-override Telegram command: operator-pinned
  polarity that wins over the auto auditor.
• A6 — pnpm wr:audit CLI: exits non-zero when any active
  signal sits below the INVERT threshold so CI can gate releases
  on per-signal calibration health.

B — Per-user accuracy correctness

Closes a long-standing visibility bug where every operator on the
same Telegram bot saw a shared WR aggregated across all users.

• B1 — user_id column is now persisted at logPrediction
  insert time (the read paths already filtered correctly — the
  bug was that the write path never populated the column).
• B2 — engine.predict() gains an options.userId that
  flows through to every logPrediction call site (forecast,
  directional with TP/SL, forecast resolve).
• B3 — All Telegram and AI tool-call sites that originate
  from an authenticated user thread userId through:
  /predict, /diagnose, /polymarket, get_prediction,
  predict_price, polymarket_edge, bulk-ladder.
• B4 — New regression test covers the end-to-end user-scoped
  logging path.

C — Predictiveness signals (leading-indicator alpha)

Engine now anticipates moves via leading flow indicators instead
of reacting to lagging structure. Operator standing rule:
predictions must anticipate big moves, not chase them.

• C1 — leadingFlow signal aggregator: taker momentum +
  orderbook imbalance + whale flow + CVD slope + funding
  inflection. Injected with 30% weight at the front of the
  on-chain composite via sigCfg.onChain.leadingFlowWeight.
• C2 — CVD-gated SMC vote: when SMC reads bullish demand but
  CVD's recent slope is bearish (demand is being eaten),
  neutralize the structural vote instead of letting it outvote
  real-time order-flow truth.
• C3 — 8 reversal FOL rules:
  failed_support_break, failed_resistance_rejection,
  asian_range_continuation_bull/bear,
  funding_peak_reversal_bearish,
  funding_trough_reversal_bullish,
  sweep_and_reverse_bullish_trap,
  sweep_and_reverse_bearish_trap.
• C4 — 4 structural FOL rules:
  stable_supply_expanding_bullish /
  stable_supply_contracting_bearish,
  alt_rotation_confirmed_alt_bullish,
  btc_rotation_dominant_btc_bullish (TOTAL2/TOTAL3 dominance
  algebra).
• C5 — 2 volatility FOL rules:
  vol_term_inverted_break_imminent,
  vol_acceleration_post_consolidation (realized vol + term
  structure).
• C6 — Realized-volatility signal: short (12h) vs long (48h)
  realized σ + acceleration, pure compute on existing OHLCV.
• C7 — MarketContext gains spotPrice,
  stablecoinNetExpansionUsd, altDominancePct,
  nonBtcEthDominancePct, realizedVol1h/4h, volTermSlope,
  volAcceleration.

D — Band-edge deformation (post-forecast)

Two post-processors run after computePredictionForecast closes,
mutating a shallow copy of the forecast so the band absorbs
predictable wick patterns the prior grader counted as MISS.

• D1 — applyLiquidationMagnet: when a significant long /
  short liquidation cluster sits beyond the band edge on the
  matching side, stretch the edge to (cluster ± small buffer)
  capped at 2× the original half-width. Symbol-agnostic — runs
  off liquidationProximity data the engine already gathers.
• D2 — applyMomentumBandWidth: when taker momentum + OB
  imbalance derivative + CVD short slope stack one way with
  magnitude ≥ 0.25, widen the band on that side by up to 1.8×
  while modestly widening the other edge.

E — Warmup acceleration (α + β + γ)

Three independent accelerators that reduce the real-world sample
budget needed to exit warmup-conservatism and engage full-strength
prediction.

• E1 (α) — Calibrator bootstrap from history: replays up to
  1000 most-recent resolved predictions through the calibrator +
  rule tracker on boot when the persistence layer comes back
  empty. Fresh DB or post-/reset start exits warmup in seconds
  instead of 30+ live resolutions. Idempotent.
• E2 (β) — Graduated warmup multiplier: replaces the binary
  cliff with sqrt(samples / minSamples) scaling on the
  probability + confidence caps so confidence climbs smoothly
  through warmup instead of unlocking on a single lucky
  resolution.
• E3 (γ) — Graduated outcome labels for Platt scaling: the
  calibrator now accepts a number ∈ [0,1] in addition to a
  boolean wasCorrect, feeding partial-credit resolution scores
  directly to the SGD update. Empirically halves the sample
  count needed to converge on the same MAE.

F — Quality gates (raise the floor)

• F1 — Per-family emission floors via
  chronovisor.perFamilyMinLogConfidence
  (micro=0.45, intraday=0.40, swing=0.35, macro=0.30). Short
  horizons (where prod WR sat at 15–32%) get a higher bar.
• F2 — Sideways dead zone widened from ±0.005 to ±0.04
  around 0.5 — uncertain calls now correctly file as RANGE
  instead of being emitted as razor-thin directional predictions.
• F3 — wrWatchdog config drives a rolling-WR warning DM in
  the resolver: when recent decisive WR falls below warnBelow
  over windowSize samples, the watchdog emits an info
  notification naming the worst-performing signal.
• F4 — Cycle-degraded hard-skip: directional predictions
  with cycleHealth.status ∈ {degraded, unsafe} AND
  systemConfirmations < 3 are now hard-skipped at
  qualification time so they never enter the resolution
  pipeline. Cold-start (warmingUp) is exempt.
• F5 — RANGE gate label fix: the 🚦 Gate: 0/3 — SKIP
  label was misleading for RANGE plays (sideways forecasts have
  no direction to confirm). RANGE plays now render
  🚦 Gate: RANGE play (3-system gate applies to directional only).

G — Reset hygiene + ghost-DM elimination

Operator bug report 2026-05-22: /reset all and manual sqlite
DELETE runs were leaving stale state that re-emerged as ghost
predictions in the next cycle. Three causes, fixed in one atomic
operation.

• G1 — performFullReset(): atomic wipe of every
  prediction-related table including Polaris additions
  (signal_outcomes, signal_polarity, calibration_family,
  calibration_symbol, rule_stats, volatility, weights,
  patterns), every alert rule, every pending notification.
• G2 — ChronoVisorEngine.getResetCallbacks(): exposes
  named clear() functions for every in-process registry the
  engine owns (CalibratorRegistry, RuleTracker,
  VolatilityRegistry, SignalPolarityRegistry, pattern library,
  warmup-state cached counts). Without flushing these, the next
  debounced ml-state save wrote the pre-wipe snapshot straight
  back to DB.
• G3 — Orphan-row guard in sendTelegramDm: before
  delivering a prediction_resolved or price_threshold DM
  the channel checks that the underlying prediction /
  alert-rule row still exists. If not, the DM is suppressed.
  Eliminates the post-wipe ghost bubble. Resolver writes
  predictionId into metadata so the guard has a key.
• G4 — /reset all reply gains a visible "VIZZOR STATS
  RESET" divider block so chat scrollback has an unambiguous
  "everything above is stale" marker (Telegram permanently
  keeps history).
• G5 — Polarity reconciliation cadence: the existing
  CALIBRATION_RETRAIN_INTERVAL now also triggers signal-
  polarity reconciliation from the auditor so a freshly-seen
  sign error is corrected within ~20 resolutions of becoming
  statistically defensible. Manual overrides are preserved.

H — /predict card renderer

Operator-requested compact trader-channel format. One card per
horizon, MarkdownV2-escaped, with branded glyphs for known
assets and a clean fallback for everything else.

₿ BITCOIN · 30m
💰 BTC Price: $77,733.83
💵 Direction: ➖ RANGE (55%)
🪙 Band: $77,656.09 — $77,811.56
💹 Best Play: Range fade — long $77,656.09, short $77,811.56 (no leverage)

🟣 SOLANA · 30m
💰 SOL Price: $87.40
💵 Direction: 📉 SHORT (61%)
🪙 Entry Zone: $87.40 — $87.44
📈 TP1: $87.29 (-0.13%)
📊 SL: $87.54 (+0.16%)
⚠ Skip: R:R 1:0.78 — risk exceeds reward, no trade

Multi-horizon replies separate cards with a horizontal rule and
surface a "Multi-horizon consensus" chip when per-horizon
directions disagree.

symbol-display registry holds the branded glyphs with operator
extension via chronovisor.symbolDisplay.<TICKER> in config.
Unknown symbols fall back to a generic icon + raw ticker —
features still apply universally (no symbol-list gating).

---

Impact

• Per-user WR: reports now correctly scope to the calling
  operator's history. Pre-fix, every operator on the same bot
  saw a shared aggregate.
• Tracked WR pollution: directional emissions on degraded /
  unsafe cycles no longer enter the resolution pipeline. The
  raised per-family floors + widened dead zone push genuinely
  uncertain calls to file as RANGE.
• Warmup time-to-full-power: bootstrap + graduated cap +
  graduated SGD label cut the practical sample budget by roughly
  half on synthetic + replay tests.
• Ghost DMs: post-reset ghost bubbles eliminated by the
  orphan-row guard plus the in-memory registry flush.
• Operator visibility: /wr-diagnose, /signal-override,
  the rolling-WR watchdog DM, and the polarity reconciliation
  DM give the operator a closed-loop view of which signals are
  helping vs hurting.

Breaking changes

None. All new config fields ship with sane defaults; existing
configs without the new keys behave identically to v0.15.0 except
for the higher minLogConfidence floor (0.25 → 0.30) and the
wider sideways dead zone (0.495/0.505 → 0.46/0.54), both of
which are documented as intentional WR-quality changes.

Test plan

• pnpm typecheck — 0 errors
• pnpm lint — 0 errors (334 pre-existing non-null-assertion warnings)
• pnpm test — 133 files, 1630 tests, all green
• Operator soak: 24h run on prod data with /wr and
  /wr-diagnose polled hourly
• /reset all end-to-end: confirm no ghost DMs land after
  the wipe completes
• /predict BTC 30m from two different operator accounts
  and confirm /wr shows distinct per-user histories

---

Round 2 — 2026-05-23 (additional commits)

Follow-up sprint after operator MISS data from 2026-05-22/23 showed
that BTC tracked WR was still sitting at ~37% with RANGE forecasts
landing 0.01–0.17% outside the displayed band and SMC self-
contradictions (bearish bias + supply zone, yet bullish vote) leaking
into directional emissions. Round 2 closes those specific failure
modes and adds the leading-edge signals + calibration acceleration
that didn't make Round 1.

Quick wins (ω₁–ω₆)

• ω₁ — Dead ICT session + no active flow + thin confirmations
  hard-skipped at qualification time (was advisory).
• ω₂ — SMC self-contradiction detector neutralizes the SMC vote
  when smc.vote disagrees with both smcLastBreakType and
  smcBias.
• ω₃ — Universal R:R<1.0 hard-skip across all tracking profiles.
  Negative-EV trades never reach chat regardless of profile.
• ω₄ — /precisions and /wr render "— (n/m, warming up)"
  until a calibrator has at least 10 decisive resolutions. Stops
  the bot from publishing 14.5% / 22% noise WR figures.
• ω₅ — Realized-vol features (volTermSlope, volAcceleration)
  feed band-magnitude lift in composeMomentumDirection (direction
  untouched — vol is a magnitude indicator only).
• ω₆ — /predict card gains a "🔬 Why" section per emission:
  per-signal CF contributions, triple-system status, guardrails
  snapshot, short reasoning paragraph. On by default.

Calibration acceleration (δ ε θ)

• δ — Fresh per-symbol Platt shards inherit the family's
  calibration parameters via inheritFamilyPriorIntoShard() instead
  of starting cold. New tokens skip the ~48 h warmup window.
• ε — Calibrator now keeps per-(family, regime) shards in
  addition to per-family and per-(symbol, family). Each resolution
  routes to all four buckets so a bull-trained curve no longer
  poisons bear emissions.
• θ — updatePlatt SGD step is scaled by |p − 0.5| × 2 + 0.5.
  High-confidence misses correct the calibrator harder than low-
  confidence ones.

New free-tier signals (H K L N π σ τ)

• H — Cross-venue funding aggregator: Binance + Bybit + OKX
  public funding-rate endpoints, 30 s cache, exposes weighted
  average + binanceDivergencePct + maxDivergencePct. Drives
  three new FOL rules around single-venue over-leverage.
• K — ETH gas spike detector via Etherscan free tier: 5 min
  baseline + 3× spike threshold. A 3×-baseline gas spike inside
  5 min historically precedes ETH liquidation cascades by 30–90 min.
• L — BTC mempool fee pulse via mempool.space: 5 min baseline +
  2× isCongested threshold. Fee acceleration is a 30–90 min
  leading volatility signal.
• N — Volume profile signal: 50-bucket profile, Point of
  Control (POC), 70%-volume value area, insideValueArea flag.
  Pure compute on existing klines. Drives
  volume_profile_above/below_va_mean_revert_* rules.
• π — Multi-timeframe CVD divergence: parallel 5 m + 1 h kline
  fetch, classifies 5m-bullish / 1h-bearish (and mirror) as multi-
  TF divergence — smart-money distribution vs retail pump signal.
• σ — Funding-payment-timing rules: ±15 min around 00:00 /
  08:00 / 16:00 UTC funding settlements emit pre-payment squeeze
  and post-payment relief / capitulation calls.
• τ — Session-momentum continuation detector: ICT kill-zone
  alignment (London / NY) combined with active leading flow
  emits session-continuation rules.

Rationale

The Round 2 surface targets the exact MISS pattern in the operator's
2026-05-22/23 screenshots: dead-session emissions, SMC self-
contradictions reaching chat, R:R<1 trades labeled "Tentative",
WR figures published from <10-sample shards, and missing leading-
edge signals (cross-venue funding, gas / mempool, multi-TF flow)
that would have flagged the BTC RANGE breaks before they happened.

Verification

• pnpm typecheck — 0 errors
• pnpm lint — 0 errors (345 pre-existing non-null-assertion warnings)
• pnpm test — 133 files, 1630 tests, all green

Round 2 commits

• 6b7da0f — fix(ml): hard-skip dead-session + R:R<1 emissions (ω₁ ω₃)
• eb4ef8f — feat(telegram): min-sample-gated WR + full-context /predict (ω₄ ω₆)
• dbb27b1 — feat(ml): realized-vol band sizing + multi-TF CVD divergence (ω₅ π)
• 2187247 — feat(ml): regime + cross-symbol + confidence-weighted calibration (ε δ θ)
• 9d61dfb — feat(data): cross-venue funding + ETH gas + BTC mempool sources (H K L)
• 4be9c7e — feat(ml): volume profile + FOL rules + engine wiring for Round 2 (ω₂ + N + H I J K L M N π σ τ)

---

Round 2.5 — 2026-05-24 (additional commits)

After Round 2 shipped, live operator data showed BTC tracked WR
sitting at ~32% on n=10 decisive resolutions. The number itself is
inside the 95% CI of a coin flip at that sample size, but examining
the emission stream surfaced five concrete gaps Round 2 did not
close — all of which let weak-edge predictions reach chat regardless
of how good the calibrator gets.

Gap 1 — emission-floor bump (config)

perFamilyMinLogConfidence floors raised:
micro 0.45→0.58 · intraday 0.40→0.55 · swing 0.35→0.52 · macro 0.30→0.50.
A 55%-probability prediction cannot resolve at 70% even with perfect
calibration — the math forbids it. Volume drops ~40%, surviving
emissions resolve with meaningfully better EV. Floors lower back to
Round 2 values once decisive samples per family cross 60 and
calibration is trusted across all 3 regime shards.

Gap 2 — adversarial signal-conflict detector (ι)

New src/core/chronovisor/signal-conflict.ts scans the
onChain × logicRules pair and flags conflict when both |CF| ≥ 0.6 AND
their signs oppose. Engine hook fires before the existing
systemConfirmations / targetEqualsEntry normalize-to-sideways block:
on conflict the prediction is reframed as RANGE, probability is
collapsed toward 0.5–0.6, the forecast is recomputed as sideways,
and a signal_conflict reasoning line is threaded into the trigger
snapshot. Catches the exact SMC-bearish-vs-ICT-bullish-vs-RANGE-call
pattern in the operator's old MISS screenshots.

Gap 3 — composite EV gate

ω₃ catches R:R<1 and the per-family floor catches low-confidence calls
but a 56% / R:R 1.05 combo escapes both axes individually with
near-zero edge. Added prediction-qualification.ts rule:
skip if (probability − 0.5) × edgeRatio < 0.04 for directional
predictions with R:R ≥ 1.0. Knocks out the marginal positive-RR but
low-edge tail that was hitting the calibrator with coin-flip outcomes.

Gap 4 — regime-aware emission throttle

Round 2's ε regime-bucketed calibration LEARNS per regime but didn't
THROTTLE EMISSIONS in a known-bad regime. Added:

• ConfidenceCalibrator.getHitRate() — cumulative bin-aggregate WR
• CalibratorRegistry.getRegimeShardHitRate(family, regime)
• shouldTrackPrediction accepts regimeShardHitRate + regimeShardSamples + regimeThrottleRoll. Throttle fires when
  samples ≥ 20 AND hitRate < 0.50 AND uniform random roll < 0.5 →
  50% emission cut in known-bad regime.
• Engine maps currentRegime ∈ {bull, bear, chop} →
  CalibrationRegime ∈ {bull, bear, consolidation}, queries the
  shard's hit rate, and passes Math.random() per call so the
  throttle is probabilistic (not a hard veto). Tests inject a
  deterministic roll for repeatability.

Gap 6 — bootstrap calibrator from 30-day time window

Round 1's α bootstrap pulled the most recent 1000 resolved rows.
The count-based bound was wrong-shaped for low-volume operators
(may produce <1000 rows in 30+ days) and high-volume operators
(1000 rows may span only 8h and miss regime variety). Replaced
with a time-windowed pull: 30-day window by default
(VIZZOR_BOOTSTRAP_WINDOW_DAYS) capped at 5000 rows
(VIZZOR_BOOTSTRAP_MAX_ROWS). Zero behavior change for mid-volume
operators with <5000 rows in 30 days.

Round 2.5 commits

• 8183d89 — feat(config): raise per-family emission floors (Gap 1)
• d5c662b — feat(ml): bootstrap calibrator from 30-day time window (Gap 6)
• 93efddd — feat(ml): adversarial signal-conflict detector ι (Gap 2)
• 7bff8d5 — feat(ml): composite EV gate + regime-aware emission throttle (Gap 3 + Gap 4)

Verification

• pnpm typecheck — 0 errors
• pnpm lint — 0 errors (345 pre-existing non-null-assertion warnings)
• pnpm test — 133 files, 1630 tests, all green

Deferred to Round 3

Gap 5 (bring up the Python ML sidecar) is environmental, not a
code change — handled outside the PR. The combined expected WR lift
from Gaps 1–4 + Gap 6 once 20+ samples accumulate is roughly +10pp
to +15pp on the tracked-decisive cohort, primarily by reducing
low-edge emission volume rather than improving any single signal.

---

Round 2.6 + Round 3.0 — 2026-05-25 (additional commits)

After Round 2.5 shipped the operator's WR snapshot (/precisions) showed
tracked decisive WR at 28% on n=71 — the qualification gate was selecting
WORSE predictions than the broader 32% cohort, because every Round 2.5
gate was directional-only and RANGE plays at 50% probability flooded
through. Round 2.6 closes the RANGE gap. Round 3.0 adds four free-tier
leading-indicator signals worth an estimated +7–12pp combined WR lift.
A small sweep at the end relocates two hardcoded symbol lists to config.

Round 2.6 — RANGE quality bar

The 45m BTC HIT card surfaced the bug: RANGE 50% · 0/3 systems · dead session · Tier: Tracked. A random-walk play counted toward WR. Round 2.6
adds three sideways-specific gates inside shouldTrackPrediction:

• 2.6.1a RANGE probability floor 0.58 — a 50% RANGE call carries no
  information; only emit when the model has at least mild conviction.
• 2.6.1b RANGE signal-confirmation floor 2 — need ≥ 2/6 supporting
  signals; a single signal is noise.
• 2.6.2 Min-band-width vs ATR gate — skip when band half-width
  < 0.5× ATR(14). Bands narrower than half a 1-bar range have ~50/50
  "actual inside" by random walk; no edge.

Expected: ~50% drop in RANGE emission volume, surviving RANGE plays
carry real information, WR denominator stops being inflated by random
HITs.

Round 3.0 — four new free-tier signals (+10 FOL rules)

#	Signal	Source	New FOL rules
H	Funding-rate 30d historical z-score	New SQLite table funding_history fed by every cross-venue-funding fetch; computeFundingZScore exposes z-score per venue (Binance / Bybit / OKX, 30-day window, lazy-pruned 35d retention)	funding_zscore_extreme_long_bearish (z > +2 → SHORT), funding_zscore_extreme_short_bullish (z < -2 → LONG)
D	Deribit options term structure + skew	Free get_book_summary_by_currency + get_index_price, no auth. ATM IV per tenor (1-7d, 8-30d), term inversion flag, put/call OI ratio, 25-delta-proxy skew	options_iv_term_inverted_volatility_imminent, options_put_skew_extreme_bearish_reversal_imminent, options_call_skew_extreme_bullish_top, options_iv_crush_post_event_relief_bullish
X	Hyperliquid DEX positioning	Free metaAndAssetCtxs, no auth. Per-asset funding rate + open interest. DEX-vs-CEX funding divergence flags smart-money leverage concentration	hyperliquid_funding_long_skew_bearish (HL funding >20% above Binance → SHORT), hyperliquid_funding_short_skew_bullish (HL >20% below → LONG)
R	Reddit + 4chan /biz/ retail sentiment	Reddit r/cryptocurrency + r/cryptomoonshots .json (UA header only); 4chan /biz/catalog.json. Lexicon-based sentiment + mention-spike z-score per ticker, 6h rolling window	retail_euphoria_top_warning_bearish (mention spike >3σ + sentiment > 0.7 → SHORT), retail_capitulation_bottom_warning_bullish (mirror)

All four sources are free, no Nansen / Arkham / Glassnode-paid per
feedback_whale_flow_edge.md. Each gracefully returns null/undefined
for assets the source doesn't cover, and the dependent FOL rules skip
cleanly via typeof guards — no false fires, no degradation for symbols
outside coverage.

Sweep — hardcoded symbol lists → config

Two source-level hardcoded coin lists relocated to config-driven
defaults (per feedback_no_hardcoded_symbols.md):

• MAJOR_SYMBOLS (collector.ts, 23 tokens) → collector.symbols
• QUICK_SYMBOLS (telegram/ui-helpers.ts, 7 tokens) → telegram.quickSymbols

getCollectorDefaults() and getQuickSymbols() read the values via
getConfig() at call time with safe pre-config-load fallbacks so an
operator can edit YAML + reload without restart. Runtime Telegram
commands (/collector-symbols, /quick-symbols) deferred to Round 3.1
to complete the spirit of feedback_no_file_edits_for_operator_config.md.

Round 2.6 + 3.0 commits

• 9dafb16 fix(ml): range quality bar + min-band-width gate (Round 2.6)
• 8667f23 feat(data): funding-rate 30-day history + z-score (Round 3.0 H)
• ae7d615 feat(data): deribit options term structure + skew (Round 3.0 D)
• 3229cad feat(data): hyperliquid DEX positioning + funding divergence (Round 3.0 X)
• 1ac2fda feat(data): reddit + 4chan retail sentiment NLP (Round 3.0 R)
• 981f4f9 refactor(config): move MAJOR_SYMBOLS + QUICK_SYMBOLS to config-driven defaults

Verification

• pnpm typecheck — 0 errors
• pnpm lint — 0 errors (352 pre-existing warnings)
• pnpm test — 133 files, 1630 tests, all green

---

Round 3.1 + 3.2 — 2026-05-25 (post-restart hygiene)

Operator restart bug: after killing the bot, wiping chronovisor_predictions

• alert_rules (or only one of them), and restarting, old DMs and old
  auto-armed alerts still fired. The Round 1 G3 orphan-row guard was only
  applied at notification ENQUEUE time, and prediction-armed alert rules
  survived unless the operator explicitly ran /reset alerts. Two fixes close
  the gap at every surface.

Round 3.1 — session-scoped DM delivery + orphan re-guard at poller

Problem: DMs sit in pending_notifications between enqueue and poller
drain. The G3 orphan guard fires only at enqueue. When the bot is killed
mid-flight and predictions are wiped before restart, the poller picks up
stale rows on the next session and delivers them referencing rows that no
longer exist.

Layer 1 — session expiry at startup. New
expirePendingDmsOlderThan(beforeMs) in pending-queue.ts marks-delivered
every undelivered row with created_at < beforeMs. The poller captures
Date.now() at boot and runs the expiry once. Anything queued by a previous
session is discarded instead of spuriously delivered. Logs:
Expired N stale pending Telegram DM(s) from prior session(s).

Layer 2 — orphan re-guard at delivery. New metadata TEXT column on
pending_notifications (idempotent ALTER, null for legacy rows).
sendTelegramDm passes notification.metadata through. The poller parses
metadata before each send and re-checks chronovisor_predictions /
alert_rules existence — if the underlying row is gone the DM is marked
delivered without sending. Mid-session deletes are caught even when the
DM was already queued.

Round 3.2 — prune orphaned prediction-armed alert rules at startup

Problem: Predictions arm price-threshold alert rules with id
pred_<predictionId>[_upper|_lower|_label]. Manual SQL wipes that only
delete chronovisor_predictions leave these rules dangling. On the next
session the price-alert-bridge keeps firing them against live prices and
the operator sees 42 system alerts on /alerts for predictions that no
longer exist.

Fix: New pruneOrphanedPredictionAlertRules() in
notifications/store.ts runs once at bot startup:

1. SELECT id FROM alert_rules WHERE id LIKE 'pred_%'
2. Strip pred_ prefix and _upper/_lower/_tp1/_sl suffix to extract
   the underlying predictionId
3. Cross-check chronovisor_predictions; collect IDs whose row is gone
4. Batch DELETE all orphans in one statement

Manual user alerts (no pred_ prefix) are left untouched. Logs:
Pruned N orphaned prediction-armed alert rule(s).

Round 3.1 + 3.2 commits

• 9846f56 fix(telegram): session-scoped DM delivery + orphan re-guard at poller (Round 3.1)
• ba52277 fix(telegram): prune orphaned prediction-armed alert rules at startup (Round 3.2)
• fdfd14b feat(telegram): refresh /start welcome + first-run nudge with chat-first framing

Verification

pnpm typecheck   # 0 errors
pnpm lint        # 0 errors
pnpm test        # 1630/1630 passing

Manual operator test:

1. Kill bot, manually DELETE FROM chronovisor_predictions, restart
2. /alerts after startup → should show 0 system alerts (was 42)
3. Bot log shows Pruned N orphaned prediction-armed alert rule(s) and
   Expired N stale pending Telegram DM(s) lines
4. Run a fresh /predict BTC 1h, kill bot mid-resolution, wipe predictions,
   restart → resolved-DM does NOT fire (orphan guard at delivery suppresses)

---

Round 3.3 — 2026-05-25 (production hardening: Sprint A + B)

After the production-deployment audit flagged 5 BLOCKERs + 12 HIGHs,
this sprint clears all 9 critical items so the branch is shippable.
Post-launch items (coverage thresholds, runbook, MEDIUM/LOW) are
intentionally deferred until the bot is in production where the
operator can observe and prioritize them with real data.

Sprint A — Pre-launch blockers

A1 — env-var validation fail-fast (config/loader.ts)
New validateProductionConfig() triggers when NODE_ENV=production
OR VIZZOR_REQUIRE_FULL_CONFIG=true. Throws at boot when
ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN, or ML_API_SECRET
(when ml.enabled) is missing. Dev runs without keys still work.

A2 — Sentry error tracking (utils/sentry.ts)
New @sentry/node integration gated on SENTRY_DSN. Captures
unhandledRejection + uncaughtException before the existing stderr
log. PII scrub redacts Authorization-style headers. Graceful
flush on SIGTERM. No-op when DSN unset.

A3 — security patches (pnpm up)
Cleared 6 moderate + 1 high advisories (postcss XSS, brace-expansion
DoS, ws uninitialized-memory disclosure, ...). Remaining 2 moderate

• 1 high sit in deep transitive paths via @solana/web3.js — at the
  floor available without dropping wallet-chain support.

A4 — hot-path DB indices
Added composite + partial indices on chronovisor_predictions
(symbol+created_at, resolved_at, user_id+symbol, source+resolved_at),
alert_rules (enabled+type), and a standalone funding_history
(fetched_at) so the lazy-prune query becomes a range scan instead
of a table scan once the table grows past ~100k rows.

A5 — /health auth (telegram/health-server.ts)
Optional bearer-token gate via VIZZOR_HEALTH_TOKEN. Constant-time
comparison. Returns 401 with WWW-Authenticate challenge. Open
endpoint preserved when env var unset (back-compat with loopback-
only setups).

Sprint B — Pre-launch reliability

B1 — Prometheus metrics endpoint (utils/metrics.ts)
New /metrics endpoint gated on VIZZOR_METRICS_PORT. Exposes
default process metrics + four counters
(vizzor_predictions_emitted_total, vizzor_predictions_resolved_total,
vizzor_telegram_dm_delivered_total,
vizzor_data_source_fetch_total) + an
vizzor_engine_cycle_duration_seconds histogram. Recorders are
small wrappers so call sites never import prom-client directly.

B2 — retry / backoff / circuit breaker (utils/fetch-resilience.ts)
New resilientJsonFetch(url, source, opts) adds 2 exponential-
backoff retries on 5xx + timeouts, per-source circuit breaker (5
consecutive failures → 60s open with half-open probe on recovery),
and metrics on every call. Applied to Deribit options, Hyperliquid
positioning, and Reddit + 4chan retail-sentiment adapters. Remaining
stable upstreams (Bybit, OKX, Etherscan, mempool.space) deferred
to a follow-up — changing them in the same commit increased blast
radius without matching reward.

B3 — image version pins (docker-compose.yml)
postgres: timescale/timescaledb:latest-pg15 → 2.21.4-pg15,
n8n: latest → 1.117.4. Bumps now require staging validation +
backup; no more silent breaking changes via floating tags.

B4 — n8n healthcheck (docker-compose.yml)
Probe against n8n's built-in /healthz. Container no longer
reports "up" when the internal process is crashed.

Round 3.3 commits

• bc0ba42 feat(config): fail-fast on missing production env vars (A1)
• 28a3c0f feat(ml): sentry error tracking with graceful flush on shutdown (A2)
• d90502e chore(deps): patch security advisories via pnpm up (A3)
• 5313683 perf(data): hot-path indices on predictions / alert_rules / funding_history (A4)
• 9de0ae0 feat(telegram): optional bearer-token auth on /health endpoint (A5)
• 7a60c22 feat(ml): prometheus metrics endpoint with engine + delivery counters (B1)
• 1222052 feat(data): retry / backoff / circuit-breaker on Round 3.0 data sources (B2)
• 3d4f701 chore(deps): pin postgres + n8n image versions, add n8n healthcheck (B3 + B4)

Production env vars introduced

Var	Required	Effect when set
NODE_ENV=production	yes	Activates env-var fail-fast (A1)
VIZZOR_REQUIRE_FULL_CONFIG=true	no	Opt-in to A1 outside prod (staging)
SENTRY_DSN	recommended	Activates Sentry error capture (A2)
SENTRY_TRACES_SAMPLE_RATE	no	Defaults to 0 (no tracing)
VIZZOR_HEALTH_TOKEN	recommended	Bearer-auth on /health (A5)
VIZZOR_METRICS_PORT	recommended	Activates /metrics server (B1)
VIZZOR_METRICS_HOST	no	Defaults to 127.0.0.1

Verification

• pnpm typecheck — 0 errors
• pnpm lint — 0 errors
• pnpm test — 133 files, 1630 tests, all green
• pnpm audit --prod — 2 moderate + 1 high (1 ignored), all deep
  transitive via @solana/web3.js (upstream tracking issue)

Deferred to post-launch (operator observes + prioritizes)

• Recording at call sites for the metrics counters defined in B1
  (engine.predict, prediction-resolver, pending-poller, data
  sources) — infrastructure ships first, then per-module recorders
• Cross-venue funding + ETH gas + BTC mempool migration to
  resilientJsonFetch (stable upstreams; lower priority)
• CI coverage threshold enforcement
• Backup / restore runbook in DEPLOYMENT.md
• Rate-limit map memory bounds
• Runtime Telegram commands for collector/quickSymbols config
• /reset notifications and /reset config commands