Surface the active-learning surrogate as the Learn-phase "wow" moment

Research finding: the field's actual bottleneck isn't tool routing, it's
getting smarter after every real measurement (ALDE, Nat. Commun.: 12%->93%
yield in 3 rounds via uncertainty-aware active learning) — and our biggest
funded competitor's headline feature is exactly "learns each time you
upload experimental data." We already had both technical pieces (the
per-user surrogate in active_learning.py, the cross-user aggregate +
scheduled rebuild in aggregate.py/server.py) — they were just invisible,
reduced to a one-line note nobody would notice. This makes them visible.

Backend:
- active_learning.Surrogate gains `components` (prior/learned/explore/
n_measured per mutation) and a new narrate() helper — a deterministic,
template-only explanation of why a mutation's score moved (or didn't).
Never fabricates: it's a pure decomposition of numbers fit_surrogate
already computes.
- _de_round2_library now also blends the cross-user global prior (parity
with round 1, previously round-2-only used the personal surrogate) and
assembles `pool_deltas` — every pool mutation's prior vs adjusted score
+ plain-language reason, sorted by the new ranking.
- JobState gains a structured `global_prior_info` field so round-1's
field-wide-prior blend (previously only ever visible in a `message`
string overwritten before the job finished) survives to /api/result.

Frontend:
- "What Turing learned": a re-rank panel showing the biggest movers with
before/after scores, a "you tested this" badge, and the reason text —
the visible "the model just got smarter" moment, staggered fade-in.
- Predicted-vs-measured calibration: client-side scatter (round-1
Predicted_Fitness_Score vs what you just logged) + Pearson r, with an
honest low-n caveat — trust-through-transparency instead of a claim.
- "Informed by pooled results from other labs (N substitution types)" on
round-1 results, once the aggregate has actually contributed — never
claims a lab count it can't back.

5 new backend tests (components/narrate) + 7 new tests (pool_deltas shape/
order, global_prior wiring on round1+round2, exercised through the real
top_percentile_pool/evolve/variants_to_dataframe pipeline, not mocked away).
414 tests green. Frontend verified in the preview browser end-to-end
(round 1 -> log outcomes -> round 2) in both themes; classic UI byte-for-
byte unaffected.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

dee/core/active_learning.py

@@ -82,6 +82,13 @@ class Surrogate:
     n_effects: int                           # mutations that got a learned correction
     learned: bool                            # False ⇒ fell back to the prior
     note: str
+    # Per-mutation breakdown of `adjusted[key]` into its three additive terms
+    # (prior + learned + explore ≈ adjusted[key]) plus how many of the user's
+    # measured variants included this mutation. Exists purely so a caller can
+    # NARRATE round 2 ("recommended because your data corrected this position")
+    # and VISUALIZE the before/after re-rank — adjusted/adjust_pool are
+    # unaffected and existing callers/tests don't need to know this exists.
+    components: Dict[Tuple[int, str], Dict[str, float]]
 
     def adjust_pool(self, pool: list) -> list:
         """Return a copy of a `search.Mutation` pool with delta_ll replaced by
@@ -132,13 +139,21 @@ def fit_surrogate(
     # Exploration bonus: under-measured mutations get a larger nudge.
     unc = 1.0 / np.sqrt(1.0 + counts)
 
-    # Not enough signal → honest fallback to the pure ΔLL prior.
+    # Not enough signal → honest fallback to the pure ΔLL prior. Components
+    # still populate (prior-only, no correction, no explore) so a caller can
+    # render "not enough data yet" consistently rather than special-casing it.
     y_all = np.array([y for _, _, y in rows], dtype=float)
     if n < MIN_MEASUREMENTS or M == 0 or (n and np.std(y_all) < 1e-9):
+        fallback_components = {
+            key: {"prior": prior[key], "learned": 0.0, "explore": 0.0,
+                  "n_measured": int(counts[index[key]])}
+            for key in keys
+        }
         return Surrogate(
             adjusted=dict(prior), w_prior=1.0, n_train=n, n_effects=0, learned=False,
             note=(f"{n} measurement(s) logged — need ≥{MIN_MEASUREMENTS} with a spread of "
                   "values to learn; round 2 uses the ESM-2 prior."),
+            components=fallback_components,
         )
 
     # Standardize y (assay scale is arbitrary; ranking is scale-invariant).
@@ -163,14 +178,43 @@ def fit_surrogate(
     w_prior = float(w[1])
     beta = w[2:]
     # Acquisition per pool mutation: prior (re-weighted) + learned correction + explore.
-    adjusted = {}
+    adjusted, components = {}, {}
     for key in keys:
         c = index[key]
-        adjusted[key] = w_prior * prior[key] + float(beta[c]) + kappa * float(unc[c])
+        prior_term = w_prior * prior[key]
+        learned_term = float(beta[c])
+        explore_term = kappa * float(unc[c])
+        adjusted[key] = prior_term + learned_term + explore_term
+        components[key] = {"prior": prior_term, "learned": learned_term,
+                            "explore": explore_term, "n_measured": int(counts[c])}
     n_effects = int(np.sum(np.abs(beta) > 1e-6))
     return Surrogate(
         adjusted=adjusted, w_prior=w_prior, n_train=n, n_effects=n_effects, learned=True,
         note=(f"Learned from {n} measured variants (prior weight {w_prior:.2f}; "
               f"{n_effects} mutation effects corrected). Round 2 balances the "
               "learned model with exploration of under-tested positions."),
+        components=components,
     )
+
+
+# β magnitude below this is "no real correction" for narration purposes — a
+# separate, looser threshold than n_effects' 1e-6 (that one's for counting
+# whether ridge found ANY signal; this one's for whether it's worth a sentence).
+_NARRATE_LEARNED_FLOOR = 0.05
+
+
+def narrate(prior: float, learned: float, explore: float, n_measured: int) -> str:
+    """One short, honest sentence for why a mutation's round-2 score moved (or
+    didn't) — the same three components `fit_surrogate` computes, turned into
+    plain language. Deterministic and template-only: never invents a reason
+    beyond what the numbers actually show."""
+    if n_measured == 0:
+        return ("Not yet tested — kept close to the ESM-2 prior, nudged up for "
+                "exploration since your data hasn't covered it.")
+    if abs(learned) < _NARRATE_LEARNED_FLOOR:
+        return (f"Consistent with your {n_measured} measurement"
+                f"{'s' if n_measured != 1 else ''} so far — no correction needed.")
+    direction = "helped more than the ESM-2 prior expected" if learned > 0 else \
+                "underperformed what the ESM-2 prior expected"
+    return (f"Revised from {n_measured} of your measurement"
+            f"{'s' if n_measured != 1 else ''} — this substitution {direction}.")

dee/server.py

@@ -221,6 +221,11 @@ class JobState:
     # library to the user when the pipeline finishes. None for anonymous
     # runs; the save-to-Storage path no-ops in that case.
     user_id: Optional[str] = None
+    # Whether/how much the cross-user field-wide aggregate (dee.core.aggregate)
+    # contributed to this run's scores — was only ever recorded transiently in
+    # `message` (overwritten by the next status update, so gone by "done").
+    # Structured here so /api/result can surface it after the job finishes.
+    global_prior_info: Optional[Dict[str, Any]] = None
 
     def elapsed(self) -> float:
         end = self.finished_at if self.finished_at else time.time()
@@ -1355,6 +1360,7 @@ def create_app() -> Flask:
                 "settings_used": job.settings_used,
                 "started_at": job.started_at,
                 "elapsed_seconds": job.elapsed(),
+                "global_prior": job.global_prior_info or {"applied": False, "substitution_types": 0},
             }
         )
 
@@ -3394,13 +3400,22 @@ def _compute_de_ll_maps(grouped_with_lib):
     return maps
 
 
+_POOL_DELTAS_MAX = 40   # cap the "what changed" payload — biggest movers only
+
+
 def _de_round2_library(wt_protein: str, settings: Dict[str, Any],
                        measurements: list) -> tuple[list, Dict[str, Any]]:
-    """Active-learning round 2 (Design→Build→Test→Learn). Score the WT, fit the
+    """Active-learning round 2 (Design→Build→Test→Learn). Score the WT, blend
+    the cross-user field-wide prior (parity with round 1), fit the personal
     surrogate on the user's measured variants, re-rank the single-site pool by
     the learned acquisition score, evolve, and assemble the same variant table
-    shape as a normal run. Returns (variant_rows, surrogate_info)."""
+    shape as a normal run. Returns (variant_rows, surrogate_info) — the latter
+    now also carries `pool_deltas` (per-mutation before/after + plain-language
+    reason, sorted by round-2 score) and `global_prior` (whether the field-wide
+    aggregate contributed), so the frontend can show a genuine before/after
+    re-rank instead of a silent number change."""
     from dee.core import active_learning as _al
+    from dee.core import aggregate as _agg
     from dee.optimizer.search import Mutation as _Mut
 
     scorer = _scoring.get_scorer(
@@ -3411,18 +3426,58 @@ def _de_round2_library(wt_protein: str, settings: Dict[str, Any],
     scores_df = _scoring.score_guarded(scorer, wt_protein)
     pool_df = top_percentile_pool(scores_df, percentile=float(settings.get("percentile", 85.0)))
 
-    # Fit the surrogate on the round-1 single-site pool + the user's results,
-    # then overwrite the pool's per-mutation score with the learned acquisition
-    # (additive ⇒ evolve() consumes it unchanged).
     muts = [_Mut(int(r.position), str(r.wt_aa), str(r.mut_aa), float(r.delta_ll))
             for r in pool_df.itertuples(index=False)]
+
+    # Same field-wide blend round 1 gets (soft nudge by substitution TYPE only,
+    # no-op until a post-effective-date rebuild has populated the aggregate) —
+    # applied BEFORE the personal surrogate so the two signals compose the same
+    # way in both rounds: ESM-2 prior → +field-wide nudge → +your own data.
+    global_prior_info = {"applied": False, "substitution_types": 0}
+    try:
+        _gp = _load_global_prior()
+        if _gp and _gp.effects:
+            muts = _agg.apply_global_prior(muts, _gp)
+            global_prior_info = {"applied": True, "substitution_types": len(_gp.effects)}
+    except Exception:  # noqa: BLE001 — global-prior blend is a nice-to-have, never fatal
+        logger.exception("global-prior blend skipped (round 2)")
+
+    # Fit the surrogate on the (possibly field-nudged) single-site pool + the
+    # user's results, then overwrite the pool's per-mutation score with the
+    # learned acquisition (additive ⇒ evolve() consumes it unchanged).
     surrogate = _al.fit_surrogate(muts, measurements)
+    baseline = {(m.position, m.mut_aa): float(m.delta_ll) for m in muts}
     adj_df = pool_df.copy()
     adj_df["delta_ll"] = [
         surrogate.adjusted.get((int(r.position), str(r.mut_aa)), float(r.delta_ll))
         for r in pool_df.itertuples(index=False)
     ]
 
+    # "What Turing learned" — every pool mutation's prior vs adjusted score
+    # plus a plain-language reason, sorted by the new score so the biggest
+    # movers (and the ones round 2 now favors most) lead. Cheap: template
+    # text only, no LLM call, and it's a straight decomposition of numbers
+    # fit_surrogate already computed — nothing here can fabricate a reason
+    # the data doesn't support.
+    pool_deltas = []
+    for m in muts:
+        key = (m.position, m.mut_aa)
+        prior_score = baseline.get(key, float(m.delta_ll))
+        adjusted_score = surrogate.adjusted.get(key, prior_score)
+        comp = surrogate.components.get(key, {"prior": prior_score, "learned": 0.0,
+                                               "explore": 0.0, "n_measured": 0})
+        pool_deltas.append({
+            "label": f"{m.wt_aa}{m.position + 1}{m.mut_aa}",
+            "prior_score": round(prior_score, 4),
+            "adjusted_score": round(adjusted_score, 4),
+            "delta": round(adjusted_score - prior_score, 4),
+            "n_measured": int(comp.get("n_measured", 0)),
+            "reason": _al.narrate(comp.get("prior", prior_score), comp.get("learned", 0.0),
+                                   comp.get("explore", 0.0), int(comp.get("n_measured", 0))),
+        })
+    pool_deltas.sort(key=lambda d: d["adjusted_score"], reverse=True)
+    pool_deltas = pool_deltas[:_POOL_DELTAS_MAX]
+
     variants = evolve(adj_df, SearchConfig(
         k=int(settings.get("k", 30)),
         max_mutations=int(settings.get("max_mutations", 5)),
@@ -3437,11 +3492,13 @@ def _de_round2_library(wt_protein: str, settings: Dict[str, Any],
         forbidden_sites=DEFAULT_FORBIDDEN_SITES,
     )
     return df.to_dict(orient="records"), {
-        "learned":   surrogate.learned,
-        "n_train":   surrogate.n_train,
-        "w_prior":   round(surrogate.w_prior, 3),
-        "n_effects": surrogate.n_effects,
-        "note":      surrogate.note,
+        "learned":      surrogate.learned,
+        "n_train":      surrogate.n_train,
+        "w_prior":      round(surrogate.w_prior, 3),
+        "n_effects":    surrogate.n_effects,
+        "note":         surrogate.note,
+        "pool_deltas":  pool_deltas,
+        "global_prior": global_prior_info,
     }
 
 
@@ -3515,6 +3572,12 @@ def _run_pipeline(
                 ]
                 job.message = (f"Filtered to {len(pool)} mutations; blended field-wide "
                                f"priors ({len(_gp.effects)} substitution types).")
+                # job.message gets overwritten by later status updates (searching,
+                # done, ...), so by the time the job finishes this fact would
+                # otherwise be lost — record it structurally so /api/result can
+                # still tell the user "this was informed by other labs" after
+                # the run is done, not just mid-flight in a progress string.
+                job.global_prior_info = {"applied": True, "substitution_types": len(_gp.effects)}
         except Exception:  # noqa: BLE001
             logger.exception("global-prior blend skipped")
 

dee/static/app.css

@@ -6361,6 +6361,58 @@ h3, h4 {
     .round2-row { grid-template-columns: 50px 1fr 84px; gap: 8px; }
 }
 
+/* ── "What Turing learned" — round-2 re-rank + reasons ────────────────── */
+.learned-panel { margin: 14px 0 0; padding-top: 16px; border-top: 1px solid var(--line); }
+.learned-list { display: flex; flex-direction: column; gap: 1px; margin-top: 8px;
+    background: var(--line); border: 1px solid var(--line); border-radius: var(--r-2); overflow: hidden; }
+.learned-row {
+    display: grid; grid-template-columns: 22px 72px 128px auto 1fr;
+    align-items: center; gap: 10px; padding: 9px 12px; background: var(--bg-card);
+    /* Staggered entrance — the "watch it re-rank" moment. Each row's delay is
+       driven by its own --i (set inline per row), so they cascade in order
+       instead of all popping at once. Respects prefers-reduced-motion below. */
+    animation: learnedRowIn 260ms var(--ease) both;
+    animation-delay: calc(var(--i, 0) * 45ms);
+}
+@keyframes learnedRowIn {
+    from { opacity: 0; transform: translateY(4px); }
+    to   { opacity: 1; transform: translateY(0); }
+}
+@media (prefers-reduced-motion: reduce) {
+    .learned-row { animation: none; }
+}
+.learned-arrow { font-size: 15px; text-align: center; font-weight: 600; }
+.learned-up   { color: var(--success, #047857); }
+.learned-down { color: var(--danger, #991B1B); }
+.learned-flat { color: var(--ink-faint); }
+.learned-label { font-family: var(--font-mono); font-size: 12.5px; color: var(--ink); }
+.learned-scores { font-family: var(--font-mono); font-size: 11.5px; color: var(--ink-faint);
+    white-space: nowrap; }
+.learned-scores .ls-old { color: var(--ink-disabled); }
+.learned-scores .ls-new { color: var(--ink); font-weight: 600; }
+.learned-badge {
+    font-family: var(--font-mono); font-size: 9px; letter-spacing: 0.08em; text-transform: uppercase;
+    color: var(--brand-deep); background: var(--brand-50); border-radius: 999px; padding: 2px 8px;
+    white-space: nowrap; justify-self: start;
+}
+.learned-reason { font-size: 12.5px; color: var(--ink-soft); line-height: 1.4; grid-column: 1 / -1;
+    padding-left: 32px; margin-top: -2px; }
+@media (max-width: 640px) {
+    .learned-row { grid-template-columns: 20px 1fr; row-gap: 4px; }
+    .learned-scores, .learned-badge { grid-column: 2; }
+    .learned-reason { padding-left: 0; grid-column: 1 / -1; }
+}
+
+/* ── Predicted-vs-measured calibration ─────────────────────────────────── */
+.calib-panel { margin: 14px 0 0; padding-top: 16px; border-top: 1px solid var(--line); }
+.calib-body { margin-top: 8px; display: flex; flex-direction: column; align-items: flex-start; gap: 6px; }
+.calib-svg { width: 100%; max-width: 360px; height: auto; }
+.calib-axis { stroke: var(--line-strong); stroke-width: 1; }
+.calib-axislabel { font-family: var(--font-mono); font-size: 8px; letter-spacing: 0.06em;
+    fill: var(--ink-faint); text-transform: uppercase; }
+.calib-point { fill: var(--ink); fill-opacity: 0.72; stroke: var(--bg-card); stroke-width: 1; }
+.calib-caption { font-size: 12px; margin: 0; }
+
 /* ── One-time policy-change notice (Privacy/Terms v2.0) ───────────────── */
 /* Matches the .research-strip register so it reads as part of the chrome:
    theme-aware surface, hairline rule, an inset accent stripe on the left. */

dee/static/app.js

@@ -1297,6 +1297,149 @@ function _renderRound2Panel(data) {
     panel.hidden = false;
 }
 
+// "What Turing learned" — the round-2 before/after re-rank + plain-language
+// reasons, from surrogate.pool_deltas (dee.core.active_learning components +
+// narrate, assembled server-side in dee.server._de_round2_library). Only
+// shown when the surrogate actually learned something real; a fresh round 2
+// on too little data has pool_deltas but every delta is 0 (nothing to show).
+function _renderLearnedPanel(surrogate) {
+    const panel = document.getElementById('learnedPanel');
+    const list = document.getElementById('learnedList');
+    if (!panel || !list) return;
+    const deltas = (surrogate && surrogate.pool_deltas) || [];
+    if (!surrogate || !surrogate.learned || !deltas.length) {
+        panel.hidden = true; list.innerHTML = ''; return;
+    }
+    // Lead with what actually MOVED (biggest |delta|), not just the current
+    // top score — that's the "the model just learned" moment, not a re-listing
+    // of the same ranking.
+    const movers = deltas.slice().sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta)).slice(0, 12);
+    list.innerHTML = movers.map((d, i) => {
+        const flat = Math.abs(d.delta) < 0.01;
+        const up = d.delta > 0;
+        const cls = flat ? 'flat' : (up ? 'up' : 'down');
+        const arrow = flat ? '&middot;' : (up ? '&uarr;' : '&darr;');
+        const badge = d.n_measured > 0
+            ? `<span class="learned-badge">you tested this</span>` : '';
+        return `<div class="learned-row" style="--i:${i}">
+            <span class="learned-arrow learned-${cls}">${arrow}</span>
+            <span class="learned-label">${escapeHtml(d.label)}</span>
+            <span class="learned-scores"><span class="ls-old">${d.prior_score.toFixed(2)}</span> &rarr; <span class="ls-new">${d.adjusted_score.toFixed(2)}</span></span>
+            ${badge}
+            <span class="learned-reason">${escapeHtml(d.reason)}</span>
+        </div>`;
+    }).join('');
+    panel.hidden = false;
+}
+
+function _pearsonR(xs, ys) {
+    const n = xs.length;
+    if (n < 2) return null;
+    const mx = xs.reduce((a, b) => a + b, 0) / n;
+    const my = ys.reduce((a, b) => a + b, 0) / n;
+    let num = 0, dx2 = 0, dy2 = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = xs[i] - mx, dy = ys[i] - my;
+        num += dx * dy; dx2 += dx * dx; dy2 += dy * dy;
+    }
+    const denom = Math.sqrt(dx2 * dy2);
+    return denom > 1e-9 ? num / denom : null;
+}
+
+// Predicted-vs-measured calibration — entirely client-side. Matches round 1's
+// Predicted_Fitness_Score (already in the table, per variant) against the
+// values the user just typed into the round-2 panel, keyed by the exact same
+// Mutations_AA string both sides already share (see _renderRound2Panel's
+// data-mut attribute). No backend round-trip needed: this is the same
+// "predictor, not oracle" honesty the rest of the product already commits
+// to, just made visible instead of only textual.
+function _renderCalibration(round1Data, measurements) {
+    const panel = document.getElementById('calibPanel');
+    const body = document.getElementById('calibBody');
+    if (!panel || !body) return;
+    const variants = (round1Data && round1Data.variants) || [];
+    const byMut = new Map();
+    variants.forEach((v) => {
+        if (v.Mutations_AA) byMut.set(v.Mutations_AA, Number(v.Predicted_Fitness_Score));
+    });
+    const points = [];
+    (measurements || []).forEach((m) => {
+        const pred = byMut.get(m.mutations);
+        if (pred != null && isFinite(pred) && isFinite(m.measured_value)) {
+            points.push({ x: pred, y: m.measured_value, label: m.mutations });
+        }
+    });
+    if (points.length < 2) { panel.hidden = true; body.innerHTML = ''; return; }
+
+    const xs = points.map((p) => p.x), ys = points.map((p) => p.y);
+    const r = _pearsonR(xs, ys);
+
+    const W = 320, H = 200, pad = { top: 14, right: 16, bottom: 30, left: 42 };
+    const innerW = W - pad.left - pad.right, innerH = H - pad.top - pad.bottom;
+    const xMin = Math.min(...xs), xMax = Math.max(...xs);
+    const yMin = Math.min(...ys), yMax = Math.max(...ys);
+    const xSpan = Math.max(1e-6, xMax - xMin), ySpan = Math.max(1e-6, yMax - yMin);
+    const xScale = (x) => pad.left + (x - xMin) / xSpan * innerW;
+    const yScale = (y) => pad.top + innerH - (y - yMin) / ySpan * innerH;
+
+    const svgNS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(svgNS, 'svg');
+    svg.setAttribute('viewBox', `0 0 ${W} ${H}`);
+    svg.setAttribute('class', 'calib-svg');
+    svg.setAttribute('role', 'img');
+    svg.setAttribute('aria-label', 'Scatter plot of ESM-2 predicted fitness versus your measured values');
+
+    const xAxis = document.createElementNS(svgNS, 'line');
+    xAxis.setAttribute('x1', pad.left); xAxis.setAttribute('x2', pad.left + innerW);
+    xAxis.setAttribute('y1', pad.top + innerH); xAxis.setAttribute('y2', pad.top + innerH);
+    xAxis.setAttribute('class', 'calib-axis');
+    svg.appendChild(xAxis);
+    const yAxis = document.createElementNS(svgNS, 'line');
+    yAxis.setAttribute('x1', pad.left); yAxis.setAttribute('x2', pad.left);
+    yAxis.setAttribute('y1', pad.top); yAxis.setAttribute('y2', pad.top + innerH);
+    yAxis.setAttribute('class', 'calib-axis');
+    svg.appendChild(yAxis);
+
+    points.forEach((p) => {
+        const c = document.createElementNS(svgNS, 'circle');
+        c.setAttribute('cx', xScale(p.x)); c.setAttribute('cy', yScale(p.y));
+        c.setAttribute('r', 4); c.setAttribute('class', 'calib-point');
+        const title = document.createElementNS(svgNS, 'title');
+        title.textContent = `${p.label}: predicted ${p.x.toFixed(2)}, measured ${p.y.toFixed(2)}`;
+        c.appendChild(title);
+        svg.appendChild(c);
+    });
+
+    const xLabel = document.createElementNS(svgNS, 'text');
+    xLabel.setAttribute('x', pad.left + innerW / 2); xLabel.setAttribute('y', H - 6);
+    xLabel.setAttribute('text-anchor', 'middle'); xLabel.setAttribute('class', 'calib-axislabel');
+    xLabel.textContent = 'ESM-2 predicted fitness (round 1)';
+    svg.appendChild(xLabel);
+    const yLabel = document.createElementNS(svgNS, 'text');
+    yLabel.setAttribute('x', -(pad.top + innerH / 2)); yLabel.setAttribute('y', 12);
+    yLabel.setAttribute('transform', 'rotate(-90)');
+    yLabel.setAttribute('text-anchor', 'middle'); yLabel.setAttribute('class', 'calib-axislabel');
+    yLabel.textContent = 'Your measured value';
+    svg.appendChild(yLabel);
+
+    body.innerHTML = '';
+    body.appendChild(svg);
+
+    const caption = document.createElement('p');
+    caption.className = 'calib-caption muted';
+    if (r == null) {
+        caption.textContent = `${points.length} point${points.length === 1 ? '' : 's'} — not enough spread to compute a correlation.`;
+    } else {
+        const strength = Math.abs(r) > 0.6 ? 'strong' : Math.abs(r) > 0.3 ? 'moderate' : 'weak';
+        const caveat = points.length < 6 ? ' — take this with a grain of salt below 6 points.' : '';
+        caption.textContent =
+            `r = ${r.toFixed(2)} (${strength} ${r >= 0 ? 'positive' : 'negative'} correlation) `
+            + `across ${points.length} tested variant${points.length === 1 ? '' : 's'}${caveat}`;
+    }
+    body.appendChild(caption);
+    panel.hidden = false;
+}
+
 function _collectRound2Measurements() {
     const out = [];
     document.querySelectorAll('#round2List .r2-val').forEach((inp) => {
@@ -1341,6 +1484,10 @@ function _round2Status(msg, kind) {
             if (res.status === 403) { window.dispatchEvent(new Event('td:signin-required')); _round2Status('Sign in to use round 2.', 'warn'); return; }
             if (!j.ok) { _round2Status(j.error || 'Round 2 failed.', 'warn'); return; }
             renderResults(j);   // renders the round-2 library + the "Round 2" banner
+            // `data` is still round 1 (captured above, before renderResults
+            // reassigned state.lastRun) — exactly what calibration needs to
+            // compare against what the user just typed in.
+            _renderCalibration(data, meas);
             const card = document.getElementById('resultsCard');
             if (card) card.scrollIntoView({ behavior: 'smooth', block: 'start' });
         } catch (e) { _round2Status('Round 2 failed — please try again.', 'warn'); }
@@ -1381,8 +1528,17 @@ function renderResults(data) {
     // and, for signed-in users, also persisted to Supabase Storage.
     const evolvedCount = (data.variants || []).filter(v => v.Variant_ID !== 'WT').length;
     const hasWt = (data.variants || []).some(v => v.Variant_ID === 'WT');
+    // Cross-user field-wide aggregate (dee.core.aggregate) blended into THIS
+    // run's scores — inert/absent until enough labs have logged outcomes for
+    // any substitution type, so this line only appears once it's honestly
+    // true. Never claims a specific lab count, only the substitution-type
+    // count actually behind it (what the k-anonymity-floored aggregate has).
+    const gp = data.global_prior;
+    const gpNote = (gp && gp.applied)
+        ? ` · <span class="micro" title="A soft nudge by amino-acid substitution type, pooled de-identified across labs — never raw sequences or user data.">informed by pooled results from other labs (${gp.substitution_types} substitution type${gp.substitution_types === 1 ? '' : 's'})</span>`
+        : '';
     $('#resultSummary').innerHTML =
-        `<strong>${evolvedCount}</strong> variants${hasWt ? ' + wild type' : ''} of <strong>${escapeHtml(data.wt_identifier)}</strong> · ${data.wt_protein.length} aa · ready to download`;
+        `<strong>${evolvedCount}</strong> variants${hasWt ? ' + wild type' : ''} of <strong>${escapeHtml(data.wt_identifier)}</strong> · ${data.wt_protein.length} aa · ready to download${gpNote}`;
 
     // Learning flywheel: remember this run + (re)build the round-2 panel.
     state.lastRun = data;
@@ -1394,6 +1550,14 @@ function renderResults(data) {
             _r2b.innerHTML = `<strong>Round 2.</strong> ${escapeHtml(data.surrogate.note || 'Designed from your logged bench results.')}`;
         } else { _r2b.hidden = true; _r2b.innerHTML = ''; }
     }
+    if (data.round === 2 && data.surrogate) {
+        _renderLearnedPanel(data.surrogate);
+    } else {
+        // Fresh round-1 render — clear any leftover round-2 panels from a
+        // PREVIOUS design in this same session so they don't show stale data.
+        const lp = document.getElementById('learnedPanel'); if (lp) lp.hidden = true;
+        const cp = document.getElementById('calibPanel'); if (cp) cp.hidden = true;
+    }
 
     renderStatsStrip(data);
     renderMutationMap(data);

dee/static/index.html

@@ -112,7 +112,7 @@
     <!-- ?v= query bumps invalidate browser + iframe asset caches when app.css /
          app.js change. Bump these numbers whenever you ship a frontend update —
          without them, users keep getting the stale file for up to a week. -->
-    <link rel="stylesheet" href="/static/app.css?v=20260714-bench-overflow-fix" />
+    <link rel="stylesheet" href="/static/app.css?v=20260714-learn-panel" />
     <link rel="icon" type="image/svg+xml" href="/static/favicon.svg?v=2" />
     <link rel="apple-touch-icon" href="/static/favicon.svg?v=2" />
     <!-- Mol* (PDBe) 3-D viewer is ~4.9 MB. We do NOT eager-load it on every
@@ -772,6 +772,23 @@
                     <div class="run-meta" id="runMeta" hidden></div>
                     <!-- Round-2 banner: set when a library was proposed from logged results. -->
                     <div class="round2-banner" id="round2Banner" hidden></div>
+                    <!-- "What Turing learned" — the round-2 re-rank + plain-language
+                         reasons (dee.core.active_learning components/narrate, surfaced
+                         via surrogate.pool_deltas). Only populated + shown when the
+                         surrogate actually learned something (enough measurements +
+                         real spread) — see _renderLearnedPanel in app.js. -->
+                    <section class="learned-panel" id="learnedPanel" hidden>
+                        <p class="card-kicker">&sect; What Turing learned</p>
+                        <div class="learned-list" id="learnedList"></div>
+                    </section>
+                    <!-- Predicted-vs-measured calibration — client-side only, built
+                         from the round-1 Predicted_Fitness_Score already in the table
+                         matched against what the user just typed into the round-2
+                         panel. See _renderCalibration in app.js. -->
+                    <section class="calib-panel" id="calibPanel" hidden>
+                        <p class="card-kicker">&sect; How well round 1 predicted your results</p>
+                        <div class="calib-body" id="calibBody"></div>
+                    </section>
 
                     <!-- Mutation map (lollipop chart). Was carrying a chip-
                          legend (Low / Med / High dots) that read as
@@ -2188,7 +2205,7 @@
     <!-- Cloning reference data must load before app.js so the Designer
          can read VECTORS / ENZYMES / CLONING_METHODS / TAGS / LINKERS. -->
     <script src="/static/cloning_db.js?v=20260530-ui-polish" defer></script>
-    <script src="/static/app.js?v=20260714-consult-typewriter" defer></script>
+    <script src="/static/app.js?v=20260714-learn-panel" defer></script>
     <!-- Dwell-time heartbeat. Loads after auth.js so its /api/ping calls go
          through the JWT-attaching fetch wrapper (signed-in attribution). -->
     <script src="/static/telemetry.js?v=20260622-analytics" defer></script>

tests/test_active_learning.py

@@ -18,6 +18,7 @@ from dee.core.active_learning import (
     MIN_MEASUREMENTS,
     Surrogate,
     fit_surrogate,
+    narrate,
     parse_label,
     parse_mutations,
 )
@@ -172,6 +173,56 @@ def test_adjust_pool_preserves_fields_and_swaps_score():
     assert pool[0].delta_ll == 1.0
 
 
+def test_components_populated_in_fallback():
+    """Below the measurement floor, components are still present (prior-only,
+    no correction, no explore) so a caller never has to special-case the
+    'not learned yet' branch when rendering."""
+    pool = _pool({(0, "L"): 1.0, (1, "R"): 0.5})
+    meas = [([_label(0, "L")], 3.0)]   # 1 < floor
+    s = fit_surrogate(pool, meas)
+    assert s.learned is False
+    assert s.components[(0, "L")] == {"prior": 1.0, "learned": 0.0, "explore": 0.0, "n_measured": 1}
+    assert s.components[(1, "R")] == {"prior": 0.5, "learned": 0.0, "explore": 0.0, "n_measured": 0}
+
+
+def test_components_sum_to_adjusted_when_learned():
+    """prior + learned + explore must reconstruct adjusted[key] exactly —
+    components is a DECOMPOSITION of the same score, not a separate estimate."""
+    pool = _pool({(0, "L"): 1.0, (3, "R"): -0.5, (5, "K"): 0.2})
+    meas = [
+        ([_label(0, "L")], 9.0),
+        ([_label(3, "R")], 2.0),
+        ([_label(5, "K")], 5.0),
+        ([_label(0, "L"), _label(5, "K")], 8.0),
+        ([_label(3, "R"), _label(5, "K")], 4.0),
+    ]
+    s = fit_surrogate(pool, meas)
+    assert s.learned is True
+    for key, comp in s.components.items():
+        total = comp["prior"] + comp["learned"] + comp["explore"]
+        assert total == pytest.approx(s.adjusted[key])
+        assert comp["n_measured"] >= 0
+
+
+def test_narrate_unmeasured():
+    text = narrate(prior=1.0, learned=0.0, explore=0.3, n_measured=0)
+    assert "not yet tested" in text.lower()
+
+
+def test_narrate_consistent_with_small_correction():
+    text = narrate(prior=1.0, learned=0.01, explore=0.05, n_measured=3)
+    assert "consistent" in text.lower()
+    assert "3" in text
+
+
+def test_narrate_revised_up_and_down():
+    up = narrate(prior=1.0, learned=0.5, explore=0.0, n_measured=4)
+    down = narrate(prior=1.0, learned=-0.5, explore=0.0, n_measured=4)
+    assert "helped more" in up.lower()
+    assert "underperformed" in down.lower()
+    assert up != down
+
+
 def test_unmeasured_mutation_falls_back_toward_prior():
     """A mutation never measured gets β≈0, so its adjusted score stays driven by
     the (re-weighted) prior plus only the exploration bonus — it isn't invented."""

tests/test_de_round2_learn_features.py

@@ -0,0 +1,159 @@
+"""Tests for the Learn-phase "wow" additions to DE round 2
+(dee.server._de_round2_library): pool_deltas (the before/after re-rank +
+plain-language reasons) and global_prior (cross-user aggregate surfacing).
+
+Exercises the real top_percentile_pool / evolve / variants_to_dataframe /
+active_learning / aggregate pipeline on a tiny synthetic pool — only the ESM-2
+scorer itself and the stored cross-user aggregate are mocked, so this proves
+the new wiring (not just the isolated math already covered by
+test_active_learning.py / test_aggregate.py)."""
+import pandas as pd
+import pytest
+
+from dee import server
+from dee.core.aggregate import GlobalPrior
+
+_SETTINGS = {
+    "model": "small", "host": "e_coli", "percentile": 85.0, "k": 5,
+    "min_mutations": 1, "max_mutations": 2, "restarts": 1, "steps": 50, "seed": 1,
+}
+
+
+def _fake_scores_df(n=5):
+    # wt_aa is always 'A' -> labels are A1G, A2G, ... A5G.
+    return pd.DataFrame({
+        "position": list(range(n)), "wt_aa": ["A"] * n, "mut_aa": ["G"] * n,
+        "delta_ll": [float(i) - 2 for i in range(n)],   # -2, -1, 0, 1, 2
+    })
+
+
+def _label(i):
+    return f"A{i + 1}G"
+
+
+@pytest.fixture(autouse=True)
+def _mock_scorer(monkeypatch):
+    monkeypatch.setattr(server._scoring, "get_scorer", lambda *a, **kw: "the-scorer")
+    monkeypatch.setattr(server._scoring, "score_guarded",
+                        lambda scorer, protein: _fake_scores_df())
+    monkeypatch.setattr(server, "top_percentile_pool", lambda df, percentile: df)
+
+
+def test_pool_deltas_shape_sorted_and_reasoned_when_learned(monkeypatch):
+    monkeypatch.setattr(server, "_load_global_prior",
+                        lambda: GlobalPrior(effects={}, n_users={}, n_obs={}))
+    # Enough varied measurements to clear MIN_MEASUREMENTS with real spread.
+    measurements = [
+        ([_label(0)], 1.0), ([_label(1)], 3.0), ([_label(2)], 5.0),
+        ([_label(3)], 7.0), ([_label(4)], 9.0),
+    ]
+    rows, info = server._de_round2_library("A" * 5, _SETTINGS, measurements)
+
+    assert info["learned"] is True
+    deltas = info["pool_deltas"]
+    assert 1 <= len(deltas) <= server._POOL_DELTAS_MAX
+    # Sorted descending by adjusted_score.
+    scores = [d["adjusted_score"] for d in deltas]
+    assert scores == sorted(scores, reverse=True)
+    for d in deltas:
+        assert set(d.keys()) == {"label", "prior_score", "adjusted_score",
+                                  "delta", "n_measured", "reason"}
+        assert isinstance(d["reason"], str) and d["reason"]
+        assert d["delta"] == pytest.approx(d["adjusted_score"] - d["prior_score"])
+    # Every measured mutation should show n_measured >= 1.
+    measured_labels = {_label(i) for i in range(5)}
+    assert all(d["n_measured"] >= 1 for d in deltas if d["label"] in measured_labels)
+    assert rows  # a real variant table came back
+
+
+def test_pool_deltas_all_zero_delta_when_not_enough_signal(monkeypatch):
+    monkeypatch.setattr(server, "_load_global_prior",
+                        lambda: GlobalPrior(effects={}, n_users={}, n_obs={}))
+    # Only 1 measurement — below MIN_MEASUREMENTS -> honest fallback, no change.
+    rows, info = server._de_round2_library("A" * 5, _SETTINGS, [([_label(0)], 3.0)])
+    assert info["learned"] is False
+    assert all(d["delta"] == 0.0 for d in info["pool_deltas"])
+    assert rows
+
+
+def test_global_prior_absent_reports_not_applied(monkeypatch):
+    monkeypatch.setattr(server, "_load_global_prior",
+                        lambda: GlobalPrior(effects={}, n_users={}, n_obs={}))
+    _, info = server._de_round2_library("A" * 5, _SETTINGS, [([_label(0)], 3.0)])
+    assert info["global_prior"] == {"applied": False, "substitution_types": 0}
+
+
+def test_global_prior_present_blends_and_reports_applied(monkeypatch):
+    # A field-wide prior that says A>G substitutions tend to be strongly
+    # favorable — should nudge prior_score upward vs the no-prior case, and
+    # be honestly reported (substitution_types == 1, the one key present).
+    gp = GlobalPrior(effects={("A", "G"): 2.0}, n_users={("A", "G"): 5}, n_obs={("A", "G"): 12})
+    monkeypatch.setattr(server, "_load_global_prior", lambda: gp)
+    _, info = server._de_round2_library("A" * 5, _SETTINGS, [([_label(0)], 3.0)])
+    assert info["global_prior"] == {"applied": True, "substitution_types": 1}
+    # Not enough measurements to learn, but the global-prior nudge still shows
+    # up in prior_score (baseline moved even though round 2 fell back).
+    unpatched_gp = GlobalPrior(effects={}, n_users={}, n_obs={})
+    monkeypatch.setattr(server, "_load_global_prior", lambda: unpatched_gp)
+    _, info_no_gp = server._de_round2_library("A" * 5, _SETTINGS, [([_label(0)], 3.0)])
+    by_label = {d["label"]: d["prior_score"] for d in info["pool_deltas"]}
+    by_label_no_gp = {d["label"]: d["prior_score"] for d in info_no_gp["pool_deltas"]}
+    assert by_label[_label(0)] > by_label_no_gp[_label(0)]
+
+
+def test_round2_route_exposes_pool_deltas_and_global_prior(monkeypatch):
+    import types
+
+    app = server.create_app()
+    app.config.update(TESTING=True)
+    client = app.test_client()
+    monkeypatch.setattr(server._auth, "get_auth",
+                        lambda: types.SimpleNamespace(anonymous=False, user_id="u1",
+                                                      email="x@y.z", plan="free"))
+    monkeypatch.setattr(server._auth, "cleanup_expired_de_outcomes_async", lambda uid: None)
+    monkeypatch.setattr(server, "_load_global_prior",
+                        lambda: GlobalPrior(effects={}, n_users={}, n_obs={}))
+
+    r = client.post("/api/de/round2", json={
+        "wt_protein": "A" * 5,
+        "measurements": [
+            {"mutations": _label(0), "measured_value": 1.0},
+            {"mutations": _label(1), "measured_value": 3.0},
+            {"mutations": _label(2), "measured_value": 5.0},
+            {"mutations": _label(3), "measured_value": 7.0},
+        ],
+        "settings": _SETTINGS,
+    })
+    assert r.status_code == 200
+    body = r.get_json()
+    assert body["ok"] is True
+    assert body["round"] == 2
+    assert "pool_deltas" in body["surrogate"]
+    assert "global_prior" in body["surrogate"]
+
+
+def test_result_route_defaults_global_prior_when_never_set():
+    app = server.create_app()
+    app.config.update(TESTING=True)
+    client = app.test_client()
+    job = server.JobState(job_id="j1", status="done", wt_identifier="WT",
+                          wt_protein="ACDEFG", variants=[])
+    with server._JOBS_LOCK:
+        server._JOBS["j1"] = job
+    r = client.get("/api/result/j1")
+    assert r.status_code == 200
+    assert r.get_json()["global_prior"] == {"applied": False, "substitution_types": 0}
+
+
+def test_result_route_surfaces_global_prior_when_set():
+    app = server.create_app()
+    app.config.update(TESTING=True)
+    client = app.test_client()
+    job = server.JobState(job_id="j2", status="done", wt_identifier="WT",
+                          wt_protein="ACDEFG", variants=[],
+                          global_prior_info={"applied": True, "substitution_types": 7})
+    with server._JOBS_LOCK:
+        server._JOBS["j2"] = job
+    r = client.get("/api/result/j2")
+    assert r.status_code == 200
+    assert r.get_json()["global_prior"] == {"applied": True, "substitution_types": 7}