feat: fee-adjusted edge, fractional-Kelly sizing, and risk-assessment endpoints

[JonathanW666]

Summary

This PR extends the signal pipeline so the API's trading primitives are
fee-aware, return Kelly-sized stakes, and ship with reproducible harnesses
for matcher quality and end-to-end back-test performance. All changes are
additive; no existing response field or query parameter was renamed or
removed. Version bumps from 2.0.0 to 2.1.0.

Fourteen commits, organised by concern:

• Analysis math (commits 1–3): shared fee, Kelly, and risk modules; a
  rewritten sentiment analyzer; a signed-edge correction in the signal
  generator.
• Arbitrage sizing (commit 4): maxStake, expectedDollarProfit, and
  annualisedReturn added to the covered-bundle opportunities introduced
  in PR Fix legacy arbitrage detector with covered-bundle pricing and strict contract matching #2. The underlying detector is unchanged.
• Endpoints (commits 5–6): analyze-text now surfaces EV and Kelly
  fields; markets/arbitrage accepts three sizing filters; two new POST
  endpoints are added (/api/position-sizing, /api/risk-assessment).
• Matcher quality (commit 7): a post-match quality gate and a
  reproducible evaluation harness.
• Infrastructure (commit 8): stale-while-revalidate and in-flight request
  deduplication on the market cache; a per-IP sliding-window rate limiter.
• Validation (commits 9–11): a Monte Carlo back-test with calibration
  sensitivity, a signal-generator fix that routes neutral-sentiment tweets
  to HOLD, and a metrics fix that computes Sharpe and win rate over
  active trades.
• Review pass (commits 12–13): six correctness and documentation fixes
  identified during a full re-read of the PR. Detail in the "Review pass"
  section below.
• Polish (commit 14): three follow-up corrections to the public-facing
  response shapes (SCALE_DOWN reachability, HOLD-override reasoning,
  alternative_sizing semantics). Detail in the "Polish" section below.

Matcher evaluation

Evaluation on the 30-tweet × 1,857-market fixture
(scripts/matcher-eval/run-eval.ts):

	before	after	delta
total matches surfaced	99	86	−13
junk rate (any rule)	63.6%	40.7%	−22.9 pp
thin-market (<$5k volume)	4.0%	0.0%	−4.0 pp
extreme-price (<2% or >98%)	46.5%	25.6%	−20.9 pp
cross-domain	29.3%	20.9%	−8.4 pp
weak-signal	4.0%	0.0%	−4.0 pp

Back-test

Monte Carlo over 500 replications at calibration = 1.0
(scripts/backtest/run-backtest.ts):

strategy	active/slots	total return	Sharpe (active)	max DD	win rate (active)	Brier
KELLY	1/1	+17.4%	0.923	3.5%	71.0%	0.206
FLAT	1/1	+1.9%	0.980	0.3%	71.0%	0.206
RANDOM	1/1	+0.6%	0.331	0.5%	50.0%	0.209

Kelly sensitivity to calibration:

calibration	total return	Sharpe (active)	max DD	win rate (active)
0.00	−1.2%	−0.067	9.0%	26.2%
0.25	+3.7%	0.183	7.5%	38.0%
0.50	+8.3%	0.398	6.2%	49.0%
0.75	+13.5%	0.668	4.7%	61.6%
1.00	+18.4%	0.995	3.3%	73.2%

Performance degrades monotonically with calibration error. At
calibration = 0 the EV filter routes zero-edge signals to HOLD, which
bounds the total-return loss to −1.2%.

Back-test interpretation

The single active signal on the current corpus is Ethereum at $2,600,
yesPrice = 0.24, implied trueProb = 0.691. KELLY and FLAT both take
the YES side on that signal, so the observed differences reflect stake
sizing rather than directional divergence.

• Total return scales linearly with stake size. KELLY stakes 10% of
  bankroll and FLAT stakes 1%; the observed 17.4% / 1.9% ratio matches
  the 10× stake ratio.
• Max drawdown scales similarly with stake. KELLY's 3.5% versus FLAT's
  0.3% reflects position size, not additional per-dollar risk.
• Per-trade Sharpe on a fixed Bernoulli payoff is approximately
  invariant to stake size. The 0.923 / 0.980 gap between KELLY and FLAT
  is attributable to the non-linear fee and slippage terms, not to
  strategy divergence.
• Win rate is identical (71.0%) because both strategies take the same
  side on the same signal.

RANDOM serves as a control: it chooses YES or NO uniformly and
therefore converges on a 50% win rate and a near-zero Sharpe.

New surfaces

• POST /api/position-sizing returns Kelly-optimal stake plus
  alternatives, given true_prob, yes_price, bankroll, and
  volume_24h.
• POST /api/risk-assessment returns a TAKE / SCALE_DOWN / AVOID
  recommendation together with EV, variance, Sharpe, prob_profit, and
  a Kelly suggestion for a proposed trade.
• analyze-text adds ev_per_dollar, kelly_fraction, and
  breakeven_prob under data.suggested_action, and
  metadata.implied_true_prob for debugging.
• markets/arbitrage adds maxStake, expectedDollarProfit, and
  annualisedReturn to data.opportunities[], and accepts
  minExpectedProfit, minAnnualisedReturn, and minMaxStake as query
  parameters.
• Every response carries X-RateLimit-Limit, X-RateLimit-Remaining,
  and X-RateLimit-Reset headers; 429 responses additionally carry
  Retry-After.

Testing

• npm run typecheck passes for both tsconfigs.
• npm run test:wallet passes 5 of 5.
• npx tsx scripts/matcher-eval/run-eval.ts reproduces the matcher
  evaluation table above.
• npx tsx scripts/backtest/run-backtest.ts reproduces the back-test
  tables above.
• The rate limiter is exercised by direct import; see the commit body
  for infra: stale-while-revalidate cache and per-IP rate limiting
  for the burst pattern and per-IP isolation check.

Backwards compatibility

• Existing response fields and query parameters retain their shapes.
• Additions to ArbitrageOpportunity, Market, and TradingSignal
  are optional properties.
• analyzeSentiment(text) retains its legacy signature.
• KeywordMatcher accepts an optional fourth constructor argument to
  disable the quality gate; the evaluation harness uses this to produce
  the "before" baseline row.
• The neutral-sentiment change in commit 10 is a behaviour correction:
  on neutral sentiment the endpoint now returns
  direction: 'HOLD'. The prior behaviour issued a directional
  recommendation derived from the 50/50 prior against the market price,
  which is not a supported use of the signal.

Review pass

A full re-read of the PR identified six correctness and documentation
issues. They are addressed in the two commits at the tip of the branch
(review: correct arbitrage profit formula, sentiment polarity match, and worst-case loss, and review: tighten arbitrage cache invalidation and rate-limit algorithm).

1. Arbitrage profit formula

estimateExecutableSizing computed
expectedDollarProfit = refinedEdge × maxStake. refinedEdge is profit
per $1 of bundle payout, while maxStake is dollars outlaid, so the
correct expression is refinedEdge × maxStake / (1 − refinedEdge).
Understatement was approximately 1–5% at typical edges and ~43% at
30%+ edges. File: src/api/arbitrage-detector.ts.

2. Arbitrage cache invalidation

cachedArbitrage previously had an independent TTL. When the market
cache refreshed mid-window, a subsequent request could receive fresh
market prices alongside arbitrage opportunities computed against the
previous snapshot. The arbitrage cache now records the cacheTimestamp
under which it was computed and invalidates whenever that timestamp
advances. File: api/lib/market-cache.ts.

3. Empty-result arbitrage sentinel

The "is the arbitrage cache populated?" check used
cachedArbitrage.length === 0 as the uninitialised sentinel, which
caused a legitimate no-arbitrage result to trigger a full O(n·m) rescan
on every subsequent request. An explicit timestamp sentinel now
distinguishes "not yet computed" from "computed and empty". File:
api/lib/market-cache.ts (same commit as item 2).

4. Rate-limit algorithm and documentation

The previous rate limiter was a fixed-window counter, not the
sliding-window implementation its docstring described; the INCR + EXPIRE claim was also inaccurate, as the Vercel KV path performs a
non-atomic read-modify-write. The limiter has been replaced with a
two-bucket weighted sliding window, and the docstring updated to
describe its behaviour (non-atomic KV, fail-open on KV failure,
in-process counter as the authoritative limiter within a warm
instance). The source field on the result now distinguishes
kv-with-local from local-only. File: api/lib/rate-limit.ts.

5. Sentiment polarity matching

analyzeSentimentForMarket matched BEARISH_LEXICON keys with
title.toLowerCase().includes(key), which produced false flips on
substrings (for example, fall inside "Falcons roster 2026"). Replaced
with a word-boundary regex that preserves multi-word key support.
File: src/analysis/sentiment-analyzer.ts.

6. Worst-case loss bound

EdgeResult.worstCaseLoss was 1 + cost, which propagated to the
/api/position-sizing and /api/risk-assessment responses as a loss
exceeding the stake. Binary-option longs on Polymarket and Kalshi
cannot lose more than the stake, and fees are already accounted for in
evPerDollar. worstCaseLoss is now bounded at 1; bestCaseGain is
floored at 0 for symmetry. File: src/analysis/edge.ts.

Polish

Three follow-up corrections to the public-facing response shapes,
delivered in the final commit on the branch.

1. SCALE_DOWN reachability without an explicit bankroll

/api/risk-assessment previously inferred bankroll = stake / maxFrac
when the caller omitted bankroll, which made stake / bankroll
identically equal to maxFrac and rendered the bankroll-fraction
branch of SCALE_DOWN structurally unreachable. The module now tracks
whether bankroll was supplied. When it is, both SCALE_DOWN branches
fire as documented. When it is not, the bankroll-fraction check is
skipped and a warning is appended instructing the caller to supply
bankroll for a complete assessment. The Kelly-vs-stake branch of
SCALE_DOWN continues to operate in both cases. The dollar worst-case
in assessRisk is also bounded at -stake (previously -stake * (1 + cost), consistent with the worstCaseLoss correction in the review
pass). File: src/analysis/risk.ts.

2. HOLD-override reasoning consistency

When computeEdge identifies raw edge on a side (YES or NO) but fees
and slippage push evPerDollar non-positive, buildSuggestedAction
overrode the direction to HOLD while leaving reasoning as the
original "YES underpriced at X%" string produced by computeEdge. The
override path now rewrites the reasoning to explain that raw edge
favoured the side but net EV is non-positive, so the returned payload
is internally consistent. File: src/analysis/signal-generator.ts.

3. alternative_sizing semantics

alternative_sizing.half_kelly and alternative_sizing.quarter_kelly
were computed as recommendedStake / 2 and recommendedStake / 4.
Because recommendedStake is already capped at min(kelly_cap, max_bankroll_fraction) of bankroll, those values did not correspond
to one-half and one-quarter of the full Kelly fraction. Both fields
are now derived from the uncapped full Kelly fraction (via
kellyFraction(shrunk_prob, yes_price)), with the same outer risk
cap applied so the "safer" sizings never exceed the recommended stake
or the caller's hard risk limit. A new full_kelly_fraction field is
exposed for clients that need the uncapped value. File:
api/position-sizing.ts.

Future improvements

The items below were identified during the review pass and are out of
scope for this PR. They are listed as a prioritised backlog for
subsequent iterations.

Correctness

• Back-test RNG drift across strategies. KELLY can skip signals
  (no rng() call), FLAT calls rng() once per signal, and RANDOM
  calls it twice. On a multi-signal corpus the three strategies would
  not observe the same coin flips on the same underlying bet.
  Innocuous with the present single-signal corpus; should be resolved
  before expanding the fixture set, either by pre-materialising
  outcomes per signal or by assigning a dedicated RNG stream per
  strategy. scripts/backtest/run-backtest.ts.

• breakevenProb semantics by side. The field is interpreted as
  "minimum trueProb for positive EV" on the YES side and "maximum
  trueProb for positive EV" on the NO side; the docstring states
  only "min". Proposed resolution: split into breakevenMin /
  breakevenMax, or add a side-aware docstring.
  src/analysis/edge.ts.

• Additive fee accounting. EV subtracts cost from the win-leg
  and adds it to the loss-leg, treating fees as paid on top of the
  stake. This slightly overstates EV under Polymarket's
  slippage-dominated model and slightly understates it under Kalshi's
  profit-based taker fees; net impact on typical markets is
  approximately 2%. A physical-model rewrite would shift the
  back-test headline numbers by 1–3 pp and belongs in a dedicated PR
  that also updates the back-test fixtures.

Observability and consistency

• Rate-limit KV TTL is windowSeconds × 2. windowSeconds is
  sufficient; the doubled TTL consumes additional KV memory without
  affecting correctness. api/lib/rate-limit.ts.

• RateLimitResult.source union includes an unused 'disabled'
  variant. Either remove from the union type or introduce a
  disabled-by-config code path.

• applyQualityGate.dropped telemetry is discarded. The gate
  produces per-reason drop counts (lowVolume, extremePrice,
  weakSignal), but KeywordMatcher.match consumes only .kept.
  Either emit drops to logs or metrics, or remove the field if unused.
  src/analysis/match-quality.ts.

• Divergent NaN handling. passesVolume drops non-finite input
  while passesExtremePrice passes it through. A single rule should
  apply. src/analysis/match-quality.ts.

• Divergent validation between position-sizing and
  risk-assessment. true_prob is required by the former and
  optional by the latter; yes_price bounds are aligned. Document the
  intentional difference or unify.

• generateEventId uses a 32-bit hash. Birthday collisions become
  meaningful around 60,000–100,000 distinct tweets; adequate for
  current usage. Migrate to a base36-truncated SHA-256 before
  event_id is relied upon as a primary key.
  src/analysis/signal-generator.ts.

Deployment and operations

• SWR and in-flight dedup are per-instance. The module-level
  cachedMarkets and inFlightFetch state does not cross function
  boundaries. Under Vercel's multi-instance scaling, concurrent
  requests routed to different instances each trigger an independent
  refresh. Migrating to a shared backend (for example, KV with a short
  TTL) is the appropriate remediation if cross-instance consistency
  becomes a requirement. api/lib/market-cache.ts.

• markets.snapshot.json (1.8 MB) is checked into the repo.
  Reviewed manually: contents are public market data (titles, prices,
  URLs). No remediation required.

• scripts/matcher-eval and scripts/backtest are not wired into
  npm run test. Reviewers must invoke them directly. Adding
  test:eval and test:backtest targets would make the evidence
  available as a single command.

• Narrow back-test corpus. One active signal remains after the
  quality gate and tradability filter. The 500-replication Monte Carlo
  exercises the sizing math but does not robustly estimate production
  PnL. Calibration sensitivity partially compensates; expanding the
  fixture corpus is the next step.

• KeywordMatcher constructor takes four positional arguments.
  Backwards compatible for 0–3 arguments, but subclasses or mocks that
  match the constructor signature require updating. Consider
  documenting the new argument or migrating to an options object.
  src/analysis/keyword-matcher.ts.

---

None of the above blocks merge. Recommended sequencing for the next
iteration: the back-test RNG drift fix before any corpus expansion,
and the SWR/dedup deployment note before the next deployment cycle
on a multi-instance Vercel project.

[vercel]

@LechenWang is attempting to deploy a commit to the Victor's projects Team on Vercel.

A member of the Team first needs to authorize it.