AD4 - Arb Desk

Weather-based quantitative trading system for Polymarket daily high-temperature band markets across 54 cities. Paper trading only: real market data, real calculations, real logged trades, real settlement and P&L, no automated real-money order submission.

Full build specification: see the spec document supplied alongside this repo (AD4-COMPLETE-BUILD-SPEC.md + Revision A). This README is the map of what got built against it and where to find things.

Start here if you're picking this up

0. Short on time? docs/DO_THIS_NOW.md. Only the steps that are outstanding: 7 SQL files, 6 n8n imports, 8 GitHub Actions, in order, with nothing else in the way.

0b. Follow docs/GO_LIVE.md. It is the single ordered checklist for taking this from a fresh Supabase project to a working desk, with the exact command and the exact expected result at every step. Everything below is the map; that file is the route.

1. Run the SQL, in this order - twenty-three files, in the Supabase SQL editor (each file is idempotent, safe to re-run any number of times). docs/GO_LIVE.md step 3 is the same list with a one-line description of each:

   1. sql/ad4_00_preflight.sql - run this first. It guarantees every table, column and unique key the other twenty-two need, whatever state the database is in, and prints a NOTICE listing exactly what it had to add. This is what makes the rest of the run order safe: the base Phase 0 schema is not in this repo, so nothing else may assume a column exists.
   2. ad4_phase1_tables.sql
   3. sql/ad4_phase2.sql
   4. sql/ad4_phase2_ranking.sql
   5. sql/ad4_capacity_correlation.sql
   6. sql/ad4_strategies_seed.sql
   7. sql/ad4_paper_engine_columns.sql
   8. sql/ad4_settlement.sql
   9. sql/ad4_backtest.sql
   10. sql/ad4_rpc.sql
   11. sql/ad4_live_weather.sql
   12. sql/ad4_rls.sql (it grants EXECUTE on functions the earlier files define, so it has to come after them).
   13. sql/ad4_13_reconcile.sql - reconciles files 1-12 with the real Phase 0 column shapes, which none of them could see.
   14. sql/ad4_14_workflows.sql - the Workflows page and its run history.
   15. sql/ad4_15_pipeline_fixes.sql - the system strategy the Signal Engine writes against.
   16. sql/ad4_16_nws.sql - api.weather.gov: per-city NWS ids, today's solar transit, and v_forecast_divergence.
   17. sql/ad4_17_city_stats.sql - each city's climatological normal and volatility, which is what lets the desk say how hot today is FOR THAT CITY rather than in absolute degrees.
   18. sql/ad4_18_databank.sql - the immutable record of predictions against outcomes. Everything else here is live or derived and is destroyed by its own next run; this is the only durable asset the desk has, and calibration is fitted on it.
   19. sql/ad4_19_stats_cache.sql - caches the climatology and bounds the forecast-divergence join. Without it City Clusters and Analytics time out once the observation archive is real.
   20. sql/ad4_20_schedules.sql - each workflow's cadence as a setting the UI owns, with should_run() for the workflows to check and a runs-per-month budget. n8n charges per execution.
   21. sql/ad4_21_weather_features.sql - what the morning already shows about the afternoon: dewpoint depression, cloud, wind and rain per city-day, plus persistence, the benchmark any forecast has to beat.
   22. sql/ad4_22_opportunity_context.sql - how the price and the forecast have MOVED, and whether the market has repriced since the forecast last changed. An edge with a cause behind it.
   23. sql/ad4_23_reasoning.sql - the desk's whole argument for one city in one row. It computes nothing new; it is a join, so every number shown as a reason is the same number the engine priced with.
   24. sql/ad4_24_nws_gridpoint.sql - the forecast side of file 21. Its columns carry the same names v_city_day_features uses for observed conditions, so the model fitted on what happened applies to what is forecast without a translation layer. n8n P1.4 fills it.
   25. sql/ad4_25_model_forecast.sql - AD4's own forward prediction, with the arithmetic that produced it stored beside the number. Deliberately not written into weather_forecasts: it is post-processing of NWS, not independent of it, and feeding it back into v_forecast_divergence would inflate the spread with its own reflection.
   26. sql/ad4_26_temp_trend.sql - which way today is pointing and how fast, and how much this city has HISTORICALLY still climbed from this hour. A temperature is a trajectory, not a number: 28.4C an hour before peak is a buy after 26.9 / 27.7 / 28.4 and a sell after 29.1 / 28.8 / 28.4. Feeds the City Monitor page and strategy S7.
   27. sql/ad4_28_feature_cache.sql last - the index and the caches that keep a page load off the archive. Without it v_weather_effects, v_persistence_skill and v_city_climb_profile run 1-3 seconds each on a modest archive and Supabase cancels the statement: 57014.
   28. sql/ad4_29_retention.sql - archive cold observations out of Postgres so a 500 MB free tier is enough. weather_observations is 98% of the database and compresses ~50x as CSV; the derived features, which are what the model actually reads, survive the prune. prune_observations() refuses unless they do.

   Then run sql/ad4_99_verify.sql against the real database. It is read-only and returns one grid: every check PASS / FAIL / ATTENTION, which file to re-run for anything that failed, which tables have data and which job fills the ones that don't, and the actual column shape of the six tables this repo previously had to guess at.

This is the beginning of the README. Read the rest at the original. Read the full README ↗