Investor Flow Build
24349a8b6d
CI / Test & Type-Check (push) Canceled after 0s
ADR-0012 documents the 34-slot confluence signal engine architecture: slot catalog, redundancy-aware rack evaluation, CandleProvider seam, closed-loop signal history, and picture-change alert producer. CONTEXT.md gains a new 'Confluence Signal Engine (M22)' glossary section.
97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
# 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. |