vyndr/specs/chain-v1.md

# chain-v1 / v2 — the portable engine, made whole, fed, and shadowed on MLB

> **v2 (2026-08-12) is appended at §8.** It corrects the order's premise (the
> chain was already firing on 99.6%, `paOutcome` reads no handedness, and there
> is no fallback path anywhere) and plumbs the hand split as a matchup
> conditioner on the RATE. Read §8 for the current numbers; §4 below is the v1
> measurement and is superseded.



**Status:** SHADOW. Served by nothing. Nothing promoted.
**Date:** 2026-08-12
**Predecessors:** chaining-v1 (Session 90 — the design, which never had a spec
file), A5 (factor freeze), A6 (the join keys, shadow), A7 (shadow accrual).

---

## 0. The finding this order started from

The extraction pass found `chain.js` was a **shell of its own header**:

| the header promised | the code had |
|---|---|
| `atoms` | a positional array ✅ |
| `context` | passed to `redistribute` only, partially |
| **`chainFn`** — atom → per-entity probability | **ABSENT. No parameter, no call site, no export.** |
| `aggregator` — ACROSS / UP | two functions ✅ |
| `redistribute` | **on `chainUp` only** |

And it was inert for a second, undocumented reason: `chainAcross` requires
`calibrated: true`, and the only writer of that flag is a loop over
`CALIBRATION_DEPLOYED`, which is `Object.freeze([])`. **No grade in the system
carries the flag**, so `chainAcross` had zero callers *and* would have refused
any caller it had.

The missing `chainFn` is why the "portable core" was not portable: with no slot
for the atom→probability stage, every sport's real work had to live somewhere
else. For MLB it lived in `scripts/`, reachable from no pipeline.

---

## 1. The three core fixes (`src/services/model/chain.js`)

### 1.1 `chainFn(atom, context) → per-entity probability`

- `applyChainFn` runs before usability filtering. **Default is identity-on-`p`**,
  so every pre-existing caller is byte-identical.
- Returning a **number** sets `p`; returning an **object** merges (so a chainFn
  can attach its own trace); returning **null or throwing** makes the atom
  UNREADABLE ⇒ **DROPPED, counted, never `p=0`**. A zero leg would zero an entire
  ticket, and "we could not read him" is not "he cannot do it".
- The refusals are surfaced as `chain_fn_refused` rather than swallowed, so a
  chainFn quietly failing across the board is visible instead of looking like a
  thin slate.

### 1.2 Correlation is SIGNED, and the direction follows the sign

Was clamped `[0, 1]` with the joint always shifted toward the weakest leg. That
is baseball's shape — same-game legs share the pitcher, the park and the weather
— and it made basketball's case **inexpressible**: teammates compete for finite
possessions, so one player's shot is another's non-shot and their props are
NEGATIVELY correlated.

Correlation is now clamped `[-1, 1]` and `|corr|` interpolates from independence
toward the **Fréchet–Hoeffding bound its sign selects**:

```
corr = +1  →  joint = min(p_i)                  (upper bound, co-monotone)
corr =  0  →  joint = Π p_i                     (independent)
corr = −1  →  joint = max(0, Σp − (n−1))        (lower bound, counter-monotone)
```

This is why the direction is principled rather than chosen. The positive branch
is arithmetically unchanged — the weakest leg **is** the upper bound — so every
previously-correct number stays exactly what it was.

### 1.3 `redistribute` reaches BOTH readings

Previously on `chainUp` only. A redistribution that reached the team read and not
the across read would leave `selfCheck` comparing post-redistribution to
pre-redistribution atoms and flagging an INTERNAL_INCONSISTENCY **the model had
itself just manufactured**.

`prepareAtoms(atoms, opts)` is exported so a caller prepares ONCE — chainFn, then
usability, then redistribution — and hands the identical legs to both readings.

---

## 2. Baseball's chainFn (`src/services/model/baseballChain.js`)

A chained forecast is always `rate × opportunity`. Baseball is the clean case
because **opportunity is fixed**: the batting order is set before first pitch, a
nine-run lead does not change who bats next, and PA/game varies over a narrow
range set almost entirely by lineup slot.

```
p_hit_per_PA   ← skillProjection.paOutcome     the RATE (modelled)
expected PA    ← lineup slot                    the OPPORTUNITY (a lookup)
P(hits ≥ k)    ← Binomial(PA, p) mixed over paDistribution
```

**Atoms routed** — all pre-existing, all previously reachable only from
`scripts/`:

| atom | source | role |
|---|---|---|
| `fromStatcastRow` | skillProjection:161 | the ONE legal units conversion (statcast stores PERCENTAGES 0–100) |
| `paOutcome` | skillProjection:268 | K / BB via log5 odds-ratio vs league; remainder = balls in play |
| `hitOnContact` | skillProjection:213 | archetype-selected barrel / hard-hit / exit-velo / GB-speed × pitcher contact allowed × park |
| `paDistribution`, `binomialPmf`, `atLeast` | skillProjection:327/308/339 | the chain over opportunity |

`PA_BY_SLOT` is a **lookup, not a fit** — 4.65 (leadoff) down to 3.85 (nine hole),
the documented ~0.1-PA-per-slot decline. Nothing was tuned on settled rows; a
tuned opportunity term on 1,741 rows is curve-fitting dressed as physics.

**Refusals:** no batter profile ⇒ null ⇒ dropped (never a league hitter). A
missing pitcher is different and handled inside `paOutcome` — the batter's own
rate stands rather than being pulled toward average.

**Scope: hits only.** `projectSkill` also routes `total_bases`, but TB's
head-to-head is on record as INCONCLUSIVE-under-contamination. Widening the first
shadow to a stat whose verdict is already muddy buys noise.

**`redistribute` is dormant** and returns the legs unchanged — the honest dormant
behaviour. Returning null would read as "the hook failed".

---

## 3. The shadow (`src/services/model/chainShadow.js`)

Runs at the post-enriched / pre-persist point in `snapshotService` — the A6
position, where the slate exists as a set. Reuses the statcast rows and resolved
opposing starter the challenger pass already fetched: **zero new I/O**.

### The unit of evidence is the TRIPLE

```
(chain_p, counter_p, outcome)
```

all three on one row, all side-aligned. `counter_p` is the served
`estimateProbability` value for that exact side; `outcome` arrives from the
ordinary settle pass; `chain_p` is the chain's. **Evidence you cannot adjudicate
is not evidence** — a chain probability stored without the number it must beat,
or without the result, can only ever be compared to itself.

**Side alignment is load-bearing.** The chain computes P(over the line); `p_win`
is expressed for the graded SIDE. An under row stores `1 − p_over`. Storing the
raw over-probability against an under row would invert every later comparison,
silently.

### UN-SERVABLE, said in the data

`requireCalibrated: false` is legitimate **only** because nothing downstream
reads the result. Every stored block carries `status: 'UN-SERVABLE'` and
`servable: false` in its own payload, not merely in a comment — a caveat that
lives only in a comment is not attached to the data once something else queries
it. Flipping that requires passing the gate, not editing a file.

### The self-check is VACUOUS today, and says so

`selfCheck` earns its keep by comparing per-entity reads to an **independent**
team read. None exists — the game-script projection was deliberately not built
(no atom has passed the gate). So the up-read is assembled from the SAME atoms as
the across-read and agreement between them is arithmetic. Every block carries
`self_check.vacuous: true` with its reason, so nobody later mistakes a tautology
for a passing consistency test.

### Storage

`model_snapshots.chain_shadow jsonb` (migration 038). A separate column, not
extra keys inside `features` — `champion-ablation.js` iterates every `features`
key for its residual scan, so widening it would silently enlarge that
multiple-comparisons denominator. Same reasoning as 034.

---

## 4. First measurement (`scripts/chain-shadow-probe.js`)

Real board, 2026-08-07 → 2026-08-12, MLB hits, **9,376 graded rows**:

```
CHAIN FIRE — 9,340/9,376 atoms read (36 refused) across 82/82 games   [99.6%]

                       min     p25    median    p75     max    mean
chain_p              0.013   0.382    0.500   0.618   0.987   0.500
counter_p            0.050   0.396    0.500   0.604   0.950   0.500
divergence (signed) −0.556  −0.082    0.000   0.082   0.556  −0.000
divergence (abs)     0.000   0.038    0.082   0.142   0.556   0.100

|divergence| < 0.02    1,203  (12.9%)   agrees with the counter
       0.02 – 0.05     1,760  (18.8%)
       0.05 – 0.10     2,577  (27.6%)
       0.10 – 0.20     2,835  (30.4%)
            ≥ 0.20       965  (10.3%)   a different read entirely

OVER SIDE ONLY (n=4,673)
divergence (signed) −0.526  −0.045    0.031   0.104   0.556   0.029
chain HIGHER on 2,837 (60.7%)
```

**Reading it honestly:**

- The chain **fires**, on 99.6% of the board. It is not the A5 case (built,
  correct, never invoked).
- It is **not a relabelled counter**: 40.7% of rows differ by ≥0.10, and 10.3%
  by ≥0.20. It is also not noise — 12.9% agree inside 0.02.
- The **symmetry of the two-sided signed distribution is arithmetic**, not a
  finding: both sides of every prop are in the sample, so each pair contributes
  `+d` and `−d`. Reading `mean −0.000` as "unbiased" would be reading the
  sampling scheme. The over-side slice is the one that can lean, and it does:
  **+2.9pp mean, higher on 60.7%**.
- **Divergence is not merit.** A challenger that disagrees is interesting, not
  right. Which of the two is closer to what happened is the settle pass's
  question, and it is exactly why the triple is stored.
- **The probe is contaminated by construction** and reports only a divergence
  (a property of two forecasts) rather than a resolution (a property of a
  forecast against an outcome): `statcast_aggregates` is upserted in place and
  keeps one as-of date, so profiles read for a row graded three days ago are
  today's. The forward accrual on the cron does not have this problem.
- The probe resolves **no opposing pitcher** (offline), so it measures the
  batter-side read. The live shadow does resolve it.

---

## 5. What is NOT claimed

- **Nothing is promoted.** The proven set remains empty.
- **The chain is not calibrated** and has passed no gate.
- **No head-to-head has been run.** That needs settled outcomes against the
  stored triples and must go through `factorGate` / the cumulative Bonferroni
  denominator, as a NEW hypothesis.
- **`CALIBRATION_DEPLOYED` stays `[]`.** Nothing is served calibrated.
- **WNBA is untouched.** Its contested-possession chainFn and its possession feed
  are later orders. The core changes (signed correlation, redistribute on both
  readings) were built now because they are engine honesty, not because MLB needs
  them — MLB exercises neither.

---

## 6. The pre-registered next step

Once settled outcomes accrue against `chain_shadow`:

1. Score `chain_p` vs `counter_p` on the SAME rows (paired bootstrap — comparing
   independent SEs overstates uncertainty and has previously read a reliable
   −0.022 as noise).
2. Per stat, never pooled (pooled resolution is inflated by base-rate structure).
3. Through the cumulative test ledger; the CI widens to `1 − 0.05/tests`.
4. **Pre-registered fallback, stated before the answer is known:** if the chain
   moves ~87% of the board and does not improve Brier, it is THEATER by the
   `factorGate` definition and the correct action is to leave it off — not to
   re-tune the opportunity term until it passes.

---

## 7. Incidental defect found and fixed

`runSnapshot`'s `deps` object was an **allowlist of 17 keys**, but fourteen call
sites read `deps.challenger`, `deps.loadStatcast`, `deps.environmentContext`,
`deps.lineupContext`, `deps.hitsFactorContext`, `deps.matchupKeys`,
`deps.gameBinder`, `deps.archetypeAxes`, `deps.contactChallenger`,
`deps.projectionChallenger`, `deps.loadArsenals`, `deps.mlbAdapter` — each
documented as injectable, each **permanently `undefined`**, each always falling
through to the real module. The seam existed in the comment and not in the code.

Fixed by spreading `...opts` FIRST in the literal: every explicit key is declared
after and already reads `opts.X`, so no existing behaviour moves, while an
unlisted dep now actually arrives. Found because the chain shadow's own test
could not inject a statcast map — the test would have passed while measuring
nothing, which is the failure this whole line of work exists to stop repeating.

---

# §8 — chain v2: FEED THE ENGINE (2026-08-12)

## 8.1 The order's premise, checked before building

The v2 order opened from four numbers. Each was checked against the code and the
board before anything was written:

| claim | measured |
|---|---|
| "`paOutcome` returned null on 596/725 rows" | **False.** Fire rate is **9,752/9,792 (99.6%)**. The only refusal reason on the whole board is `no_batter_profile: 40`. `pa_outcome_refused` never fires. |
| "it needs the batter-vs-pitcher-hand split" *to run* | **False.** `paOutcome` and `hitOnContact` read `k_pct`, `bb_pct`, `barrel_pct`, `hard_hit_pct`, `avg_exit_velo`, `avg_launch_angle` and the pitcher's `k_pct`/`bb_pct`/`hard_hit_pct`. Neither reads `bats` or `throws` at all. A hand split cannot change whether they run. |
| "82% FELL BACK to the seasonal rate, i.e. became the counter" | **No fallback path exists.** `baseballChain.chainFn` returns null on any refusal and `chain.applyChainFn` DROPS the atom. Nothing in the module reads a season rate as a substitute. |
| "425/425 served-identical" | That figure is from commit `7c8ef8b` (the A1–A7 deploy verification), not from the chain. v1 measured **2/2 served-identical** in the harness and byte-identical served payloads. |

Chain v1 was also never committed or deployed and migration 038 was never
applied, so no chain-shadow rows exist in production — the premise numbers cannot
have come from a chain-shadow run.

**The premise was wrong about the mechanism. It was right about the thing that
matters:** the chain was reading a hitter's SEASON rates, which already average
his platoon split over whichever hands he happened to face. That is a season read
wearing a matchup read's clothes, and un-averaging it is real work. So v2 plumbs
the hand split — as a **conditioner on the rate**, not as a fix to the fire rate.

## 8.2 What was built

**The split enters at the per-PA hit rate, not at the output probability.**
Multiplying `P(hits ≥ 1)` by a platoon factor would scale a number that has
already been through the opportunity term — a different and wrong claim. So
`baseballChain.chainFn` now writes the chain out explicitly:

```
paOutcome  →  p_hit_per_pa (season)
           →  × platoonRead multiplier   ← THE MATCHUP CONDITIONER
           →  Binomial(PA, p_hit) over paDistribution
           →  P(hits ≥ k)
```

A test asserts that with no split supplied this is **arithmetically identical to
`projectSkill`** across three archetypes × three PA values, so the restructuring
cannot quietly become a second model.

**As-of-correct (A4).** The hitter's own split comes from `hitsFactorContext`
(whose reads are `lte('as_of_date', asOf)`), the opposing starter's hand through
the A6 `matchupKeys` resolve. The probe bounds every read at the row's own
`game_date`. Nothing later than the grade can enter.

**Refuse, never substitute.** `platoonSeverity` already refuses below 60 PA on
the smaller side and declares switch hitters unreadable. On a refusal the season
rate stands **exactly** untouched (asserted to 6 dp) and the reason is recorded.

**Refusals are counted by reason** (`context.onRefusal`), and the count is taken
off the **stored blocks**, not the legs — a prop with both an over and an under
row produces two legs sharing one block, and the first draft reported 48.1% and
55.1% for the same fact over two different denominators.

## 8.3 Measured — real board, 2026-08-07 → 08-12, 9,792 graded hits rows

```
CHAIN FIRE — 9,752/9,792 atoms read (40 refused) across 83/83 games
  refusal reasons: { no_batter_profile: 40 }

HAND SPLIT — fired on 288/553 unique props (52.1%)
  season-rate reasons:
    insufficient_split_sample          130   the honest 60-PA refusal
    no_pitcher_hand                     71   the only FIXABLE gap
    switch_hitter_side_value_unknown    60   genuinely unreadable
    no_splits / missing_split            4

CHAIN vs COUNTER — n=9,752
                       min     p25   median    p75     max    mean
  chain_p            0.016   0.359   0.498   0.641   0.984   0.500
  counter_p          0.050   0.397   0.500   0.603   0.950   0.500
  |divergence|       0.000   0.044   0.095   0.164   0.509   0.113

  |div| < 0.02   1,142 (11.7%)      0.10–0.20   3,129 (32.1%)
  0.02–0.05      1,608 (16.5%)      >= 0.20     1,538 (15.8%)
  0.05–0.10      2,335 (23.9%)

OVER SIDE ONLY (n=4,879): mean +0.045, chain HIGHER on 66.3%

MATCHUP READ vs SEASON READ
  split FIRED   (n=5,372 rows)  median |div| 0.091 · >= 0.10 on 46.0% · within 0.02 on 13.0%
  split REFUSED (n=4,380 rows)  median |div| 0.100 · >= 0.10 on 50.1% · within 0.02 on 10.2%
```

## 8.4 Reading it honestly

- **The hand split fires on 52.1% of props**, up from 0. Of the 47.9% that do
  not, **190 of 265 (72%) are principled refusals** — a thin split or a switch
  hitter. Only `no_pitcher_hand` (71) is a plumbing gap, and it is the A5 shape
  exactly: the hitter's split is sitting right there and the pitcher hand is
  missing because that player had no lineup row.
- **Feeding the split widened the divergence**: median |div| 0.082 → **0.095**,
  and the over-side lean +2.9pp → **+4.5pp**. The chain moved further from the
  counter, which is what a matchup conditioner should do and is *not* evidence
  it moved in the right direction.
- **The rows where the split FIRED disagree with the counter slightly LESS**
  (median 0.091 vs 0.100) than the rows where it refused. **This comparison is
  confounded and must not be read as an effect**: a hitter with 60+ PA on both
  sides is an established regular, and the counter has more game log on him too.
  It is two different populations, not two treatments.
- **Divergence is still not merit.** Nothing here says the chain is closer to
  what happened. That needs settled outcomes against the stored triple, and it
  goes through the gate as a new hypothesis against the cumulative denominator.
- **The probe remains contaminated** for the batter profile
  (`statcast_aggregates` keeps one as-of date) and so reports a divergence, never
  a resolution. The forward cron accrual does not have this problem.

## 8.5 Still not claimed

Unchanged from §5: nothing promoted, no head-to-head run, `CALIBRATION_DEPLOYED`
still `[]`, A8 untouched, `hitsFactors` untouched, the counter still serves,
WNBA untouched.

## 8.6 Second incidental defect found and fixed

`hitsFactorContext.build` and `matchupKeys.build` were both gated on
`require('../utils/supabase').getSupabaseServiceClient()` called inline, so the
entire factor and hand-split path was **unreachable from any test**. "It is
wired" could only ever have rested on reading the code — which is precisely how
A5 shipped three factors that never fired. Both now read `deps.supabase ||` the
real client (additive; `undefined` gives identical behaviour).

---

# §9 — chain v3: the opportunity term, and the artifact/signal diagnostic (2026-08-12)

## 9.1 The premise, again checked first — one half right, one half wrong

**RIGHT, and a real defect:** the v2 shadow passed **no `lineupSlotFor`**, so
every hitter fell to `skillProjection.DEFAULT_PA = 4.1`. "A regular" was asserted
about the leadoff man and the nine hole alike. The chain is `rate × opportunity`
and the opportunity half was a constant across the entire lineup — a free,
known, pre-game fact thrown away. Fixed.

**WRONG about the conversion, and about the direction:**

- *"mis-handles the multiple-chances structure"* — it does not.
  `paDistribution` is a mean-preserving two-point mixture, and
  `atLeast(Binomial(n, p), 1)` **is** `1 − (1−p)^n` averaged over n. The order's
  proposed formula is what the code already computes. The defect was the INPUT
  `E[PA]`, not the conversion.
- *"5.7pts BELOW the counter on 92% of rows"* — **measured the other way.** On
  the over side the chain runs **+4.5pp ABOVE** the counter and is below on
  **33.6%**. It was never 92%-below, at any point, in any measurement here.

## 9.2 Phase 1 — the E[PA] fix, A/B on identical rows

`matchup_keys` now carries `batting_order` (one extra column on a read it
already performs — no new query), and the shadow feeds it as the opportunity
term. Absent ⇒ `DEFAULT_PA` and the block records `default_regular`, so a
league-shaped opportunity term is never mistaken for a posted one.

```
OPPORTUNITY — posted lineup slot on 491/553 props (88.8%)
              fell to a default regular: 62

                                 n      mean      median    chain BELOW counter
  REAL E[PA] (posted slot)     4,879   +0.0450   +0.0499          33.6%
  CONSTANT 4.1 (the v2 shadow) 4,879   +0.0322   +0.0363          39.6%
```

**The uniform bias did not collapse, because it was never there to collapse.**
The fix moved the chain *further above* the counter, not toward it — which is
correct behaviour, not a regression: real slots raise E[PA] for the top of the
order and lower it for the bottom, and top-of-order hitters are over-represented
in the prop board.

## 9.3 Phase 2 — THE DIAGNOSTIC: artifact or signal?

Over side, n=3,705 rows carrying an opposing-pitcher profile, quintiles of
opposing-pitcher K% (low = soft matchup):

| bucket | opp K% | n | mean divergence | chain below counter |
|---|---|---|---|---|
| Q1 | 10.8–18.4 | 741 | **+0.0749** | 27.8% |
| Q2 | 18.4–20.3 | 741 | +0.0560 | 30.8% |
| Q3 | 20.3–23.1 | 741 | +0.0287 | 34.1% |
| Q4 | 23.1–26.6 | 741 | +0.0396 | 35.0% |
| Q5 | 26.6–40.6 | 741 | **+0.0256** | 38.6% |

**Q1 − Q5 spread +0.0494 · Pearson r(oppK, divergence) = −0.119**

### The answer is BOTH, and the order's binary framing does not fit

The order asked for *uniform (broken)* **or** *difficulty-correlated (signal)*.
The data is a **mixture of the two, and both components should be named**:

- **A difficulty-correlated component, ~+0.049 across the range.** The chain
  reads soft matchups higher and hard matchups lower than the counter does. The
  `below %` is **monotone across all five quintiles** (27.8 → 30.8 → 34.1 → 35.0
  → 38.6), which is a cleaner signature than the means (Q4 breaks order).
- **A uniform positive offset of ~+0.026.** Even in the HARDEST quintile the
  chain sits +2.6pp above the counter. That floor does not move with the matchup
  and is therefore not conditioning — it is exactly the shape a residual
  mechanical bias makes. It is smaller than the conditioning component but it
  has not been explained, and calling the whole result "signal" would bury it.

### The caveat that must travel with the correlation

**This is close to mechanically guaranteed and is NOT evidence of correctness.**
The chain reads the opposing pitcher's K rate directly (log5 odds-ratio in
`paOutcome`) and the counter reads nothing about the pitcher at all. So a
monotone relationship between opposing-pitcher K% and chain-minus-counter is
approximately a proof that *the wiring works* — that the pitcher input reaches
the number. It says nothing about whether the adjustment is the right size, the
right direction on any individual row, or better than ignoring the pitcher.

**Does the chain see the game, or just miscompute it?** It demonstrably
CONDITIONS on the game — the pitcher input reaches the forecast and moves it in
the theorised direction. Whether that conditioning is *right* is unanswerable
from a divergence and needs settled outcomes against the stored triple. There is
also a residual ~2.6pp offset that conditioning does not explain and that should
be chased before anyone reads the correlation as a win.

## 9.4 Open item created by this measurement

The ~+0.026 floor. Candidates not yet tested: the chain is unclamped where the
counter clamps to `[0.10, 0.95]` (chain min 0.016 vs counter min 0.050); the
`LEAGUE.babip = 0.291` anchor in `hitOnContact`; the ±35% BABIP bound. Naming it
as unexplained is the honest state — it is not yet an artifact and not yet
signal.

## 9.5 Unchanged

Nothing promoted, no head-to-head, `CALIBRATION_DEPLOYED` still `[]`, A8 and
`hitsFactors` untouched, the counter still serves, WNBA untouched. Migration 038
is still an unapplied blocking precondition of deploy.