vyndr/specs/order-zero-widening.md

Order Zero — TIER REALITY + AGGREGATOR WIDENING

Date: 2026-08-01 · Phase 1 verified on our real prod keys · Phase 2 LIVE · Phase 3 model path byte-identical.

Gates: 4,028 tests / 322 suites green · next build exit 0 · tier-reality report per endpoint · widening fingerprinted on the served feed · model input unchanged.

---

PHASE 1 — THE FREE-TIER DISCREPANCY, RESOLVED

The order was right to demand this. I found and discarded a bad source on the way. A fetched rendering of PropLine's docs "tier matrix" claimed /odds/closing is 403 on free and that /odds returns prices nulled on free. Both are contradicted by direct observation: we get 200 redacted on /odds/closing, and 6,196 two-sided PRICED prop groups on MLB /odds. That matrix is not cited anywhere below.

Two authoritative sources are used instead: the machine-readable OpenAPI contract, and the verbatim detail bodies our own keys received.

The verdict per endpoint

endpoint	our keys	verbatim reason	verdict
/events/{id}/results	403	upgrade_required · required_tier: "hobby" · "Prop resolution is a paid feature — start at $9/mo Hobby"	Free-tier exclusion. $9/mo.
/exports/resolved-props	403 ×4 sports	upgrade_required · required_tier: "pro" · "Resolved-prop exports are a Pro feature"	Free-tier exclusion. $19/mo.
/events/{id}/odds/closing	200, 1,847 outcomes, 0 priced, upgrade_url present	OpenAPI: "Paid tiers: full data. Free tier: redacted (structure only)."	Free-tier redaction. $9/mo.
/events/{id}/movement	200, 1,847 outcomes, 0 priced, steam: []	OpenAPI: "Paid tiers (Hobby+): full data. Free tier: redacted."	Free-tier redaction. $9/mo.
/events/{id}/context (MLB)	200, full data	—	Free. Works.
/events/{id}/context (WNBA)	404 · "No context on file for this event yet."	—	Not a tier issue — MLB-only coverage.

It is NOT a key-permission problem and NOT a plan problem. The keys return exactly what the Free tier's published contract says they should, on every one of the six endpoints. error: "upgrade_required" with an explicit required_tier is as unambiguous as this gets.

What money would buy

tier	cost	unlocks
Hobby	$9/mo	/results (settled outcomes + actual values) · /odds/closing (the CLV instrument) · /movement (steam across 18 books) · /odds/history (30d) · /players/trends + /history · /ev
Pro	$19/mo	the above + /exports/resolved-props — 90-day bulk settlement CSV incl. closing price, the backtest input

$9/mo buys the two instruments we have been unable to build — a real closing line and cross-book steam. /exports/odds-history (the full tick firehose) stays Enterprise-only at any price we'd consider.

I am not recommending the spend in this order. It is a decision, priced and evidenced, for you to make.

---

PHASE 2 — AGGREGATOR WIDENING (LIVE)

normalizeProps now emits every DISPLAY book instead of 5 of 18.

Fingerprint — the SERVED MLB feed, post-deploy

	before	after
distinct books served	5	13
book rows	—	11,737
props rendered (player+stat)	546	2,780
mean books/prop	~0.6	4.22

Props that render now and rendered nothing before: 2,234. The slate a user sees is 5.1× larger.

The part that isn't flattering, stated up front

Of those 2,234 newly-visible props:

• 698 (31.2%) carry at least one real non-DFS market price — genuinely new market data.
• 1,536 (68.8%) are DFS-only — PrizePicks/Underdog/Sleeper/Dabble rows, which are not a market at all.

So the honest headline is not "80% of the slate was unlocked". It is: the board is 5× fuller, about a third of the new depth is real market data, and the rest is pick'em inventory that is now shown but tagged.

Served role mix: dfs 8,515 · reference 2,042 · both 791 · offshore 389.

book_role is load-bearing, not decorative

Every row carries book_role ∈ {both, takeable, reference, dfs, offshore} — through the normalizer and through the odds route's grouping, which was silently dropping it.

Why it matters, from live data. On one MLB prop:

betmgm      +450 / -750     ← a real two-way market
prizepicks  +100 / +100     ← fixed-payout pick'em

Rendered side by side untagged, the PrizePicks row reads as a dramatically better price. It is a different product. Untagged breadth would have been a new way to mislead, dressed as a feature — which is exactly what the split exists to prevent. Consumers gate on book_role !== 'dfs' before treating a row as a market price.

The ?book= filter now accepts any DISPLAY book, since shopping a real book against an exchange is the point.

---

PHASE 3 — THE MODEL DOES NOT MOVE

bookRoles.js splits MODEL_BOOKS (the legacy allow-list, character for character) from DISPLAY_BOOKS. Both model paths re-filter before they pick a line:

1. gradeSlateService.dedupeProps — filters to MODEL_BOOKS before first-row-wins and before the 25-prop limit, so the graded set is byte-identical through the widening. A test asserts exactly this.
2. intradayRefreshService.indexOddsProps — the one that would have bitten. It re-grades props at the current line, so without a gate the widened feed would have silently moved locked lines onto DFS and exchange numbers the model has never been calibrated against.

Props the model can grade: 546 — unchanged. CURRENT_RULER_VERSION is still v1_first_book.

The gate lifts only when the MLB calibration is re-run on the consensus ruler and v2 is promoted.

---

HONEST FRAMING — do not let this read as model progress

• This is an AGGREGATOR win. It does not fix the model. Not one grade changed.
• WNBA still abstains. It is a model problem, not a coverage problem — WNBA is better covered than MLB (4.21 vs 3.61 books/prop). Coverage was never its constraint.
• MLB isotonic p_win is still PROVISIONAL until re-run on the consensus ruler.
• The consensus is MARKET, not SHARP. pinnacle, matchbook and polymarket are 0% on both sports. No sharp anchor exists in our feed — and none is purchasable from this provider, because it is a coverage fact, not a tier gate.
• A third of the new depth is real; two thirds is pick'em. Both are shown; only one is a market.

---

THREE SUPERSEDED TESTS, UPDATED TO STRONGER PROPERTIES (not deleted)

1. roleOf(dfs) returned 'excluded' → now names the kind ('dfs'), plus assertions that it is display-visible, non-reference and non-model.
2. "filters out books not in the allowed set" → now asserts the display set widens with correct role tags, unknown books are still dropped, and the model set does not move.
3. "returns 400 for invalid book" (bovada) → split into: an unknown book still 400s, and a newly-visible one no longer does.

OPEN

1. $9/mo Hobby — buys the CLV instrument and steam. Evidenced above; your call.
2. $19/mo Pro — adds the 90-day settlement export, which is the backtest input and the thing that makes soccer settle.
3. The display layer should now surface multi-book line shopping — the data is live and tagged; no surface consumes it yet. That is a frontend order.