investor-flow/docs/adr/0012-confluence-signal-engine.md

ADR-0012: Confluence Signal Engine (M22)

Date: 2026-08-10
Status: Accepted

Context

Investor Flow evaluates entry/exit quality for a symbol by combining multiple evidence axes (technical, institutional, macro, seasonal, flows, sentiment). The existing codebase had per-indicator helpers (RSI, MACD, moving averages, volume-by-price, rotation, seasonality) but no unified layer that combined them into a single, per-symbol, per-date assessment. Users saw individual indicators but not the synthesized picture.

The product needs an evidence-based confluence layer that:

• Aggregates multi-axis signals into a single "picture quality" for a symbol
• Discounts redundant signals (e.g. golden cross + trend alignment both measure the same thing) so correlated evidence isn't double-counted
• Produces an ADR-0007-safe output: evidence descriptions ("strong bullish picture"), never buy/sell directives
• Supports a closed loop: slot fires are logged and later resolved to confirmed/false-alarm by measuring whether price followed through

Decision

Build a 34-slot Confluence Signal Engine as a first-class module (app/server/src/confluence/).

1. Slot catalog (34 slots, 6 families)

Each slot is an independently-evaluable check whose firing state contributes bullish or bearish evidence. Families: technical (15), institutional (5), macro (5), seasonal (5), flows (3), sentiment (1). Slots carry an ADR-safe explain note (evidence sentence, never a directive). SlotBody: bull / bear / exit (exit = bear evidence for an existing position).

2. Redundancy-aware rack evaluation

Slots are bucketed into redundancy groups (e.g. goldenCross + trendAlignment + pullbackToEMA21). Within each group, evidence decays geometrically (1 + 0.5 + 0.25 ...) so correlated signals count once, not three times. The rack then labels the picture using evidence totals:

• MIN_TOTAL_EVIDENCE = 1.0 (below → sparse)
• DIRECTION_RATIO = 0.6 (bull/totals must reach this for bullish label)
• STRONG_EVIDENCE = 4.0, MODERATE_EVIDENCE = 2.0 (magnitude thresholds)

Quality labels: strong/moderate/weak-bullish, mixed, weak/moderate/strong- bearish, sparse.

3. CandleProvider seam (data abstraction)

Confluence evaluators resolve candles through a CandleProvider interface, not cache.get inline. The cache-backed implementation folds in the freshest live quote as a partial daily bar so mid-session evaluations see the current price, not just the last EOD close. Weekly slots (50/200 cross, trend alignment) use the weekly cache key. This seam is pluggable for future replay/realtime sources.

4. Closed-loop signal history

Every slot fire is logged to confluence_signal_history with the as-of date, rack, and picture quality at the time. A resolver later checks whether price moved the expected direction over 4 weeks (bull slots → price up, bear/exit slots → price down). A small dead-band (0.5%) treats flat outcomes as unresolved rather than false alarms. Per-slot reliability weights (0.5–1.25) allow the rack to self-tune over time.

5. Picture-change alert producer

The confluence_change alert type fires when the picture quality tier changes (improved / deteriorated) or net evidence shifts beyond 0.35. Throttled to 5 per hour per type. ADR-0007 framing: "the picture has changed," never "act now."

6. COT data adapter

The CFTC Traders-in-Financial-Futures report (leveraged-funds long/short + open interest) is fetched from CFTC's annual zip files and parsed. The cotPositioning slot consumes this data. Registered under the cftc vendor family with 1.5s min-interval pacing.

Consequences

• The tRPC confluence.* router exposes slots, racks, evaluation, backtest, scorecard, and saveRack. The frontend /confluence page shows picture quality, per-slot evidence, and reliability scorecard.
• Three system rack presets are seeded on startup: Full Confluence (all 34), Technical Momentum (15), Macro + Flows + Sentiment (14).
• The 15-symbol confluence universe (PLTR, NVDA, AMD, AAPL, MSFT, SMH, XOM, JPM, UNH, COST, AMZN, CAT, LMT, LIN, NEE) + SPY benchmark are pinned into the demand set on startup.
• No advisory output is produced. All picture-quality labels describe evidence; they never recommend action.
• The closed loop is not self-executing: the confluence.eval procedure must be triggered to produce evaluations. The backtest procedure is read-only and query-driven. Future work can schedule periodic evaluation.