Deploy: commons provenance (migration 0018)

Seeded published-study rows can no longer be counted as contributing labs.
/api/atlas reports the two separately. Scoped the prior wipe by source so a
user rebuild can't delete the DMS seed. Run migration 0018 before seeding.

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

dee/auth.py

@@ -43,6 +43,7 @@ from __future__ import annotations
 import hashlib
 import hmac
 import json
+import urllib.parse
 import logging
 import os
 import threading
@@ -2113,16 +2114,26 @@ def get_mutation_priors() -> list:
         return []
 
 
-def replace_mutation_priors(rows: list) -> Dict[str, Any]:
-    """Replace the aggregate table with a fresh set of de-identified rows.
-    Each row: {substitution, n_users, n_obs, mean_effect}. Service-role.
+def replace_mutation_priors(rows: list, source: str = "user") -> Dict[str, Any]:
+    """Replace ONE SOURCE's aggregate rows with a freshly computed set.
+
+    Each row: {substitution, n_users, n_obs, mean_effect, source}. Service-role.
+
+    The delete is scoped to `source` — this used to wipe the whole table, which
+    was fine while every row came from user outcomes but destroys the seeded
+    DMS commons the moment both coexist (migration 0018). A nightly user-prior
+    rebuild silently deleting the published-study seed is exactly the sort of
+    failure nobody notices until the atlas is empty again.
     """
+    if source not in ("user", "dms"):
+        return {"ok": False, "error": f"unknown-source-{source}"}
     if not (SUPABASE_URL and SUPABASE_SERVICE_KEY):
         return {"ok": False, "error": "supabase-not-configured"}
     import urllib.request
-    # wipe then upsert (the aggregate is fully recomputed each run)
+    # wipe then upsert — this source's rows are fully recomputed each run
     try:
-        del_url = f"{SUPABASE_URL}/rest/v1/mutation_priors?substitution=neq.__none__"
+        del_url = (f"{SUPABASE_URL}/rest/v1/mutation_priors"
+                   f"?source=eq.{urllib.parse.quote(source)}")
         req = urllib.request.Request(del_url, method="DELETE",
                                      headers=_supabase_headers({"Prefer": "return=minimal"}))
         with urllib.request.urlopen(req, timeout=10.0):

dee/core/aggregate.py

@@ -124,9 +124,17 @@ class GlobalPrior:
     def __bool__(self) -> bool:
         return bool(self.effects)
 
-    def to_rows(self) -> List[dict]:
+    def to_rows(self, source: str = "user") -> List[dict]:
         """Serialize for storage in public.mutation_priors (de-identified).
-        A 3-tuple key (wt, mut, bin) serializes as 'W>L@hi'."""
+        A 3-tuple key (wt, mut, bin) serializes as 'W>L@hi'.
+
+        `source` records WHERE the pooling came from and is not cosmetic.
+        For 'dms' rows n_users counts independent published STUDIES, not
+        people — reporting the two together would assert lab adoption this
+        platform has not earned (migration 0018).
+        """
+        if source not in ("user", "dms"):
+            raise ValueError(f"unknown prior source {source!r}")
         out = []
         for sub, eff in sorted(self.effects.items(), key=lambda kv: tuple(map(str, kv[0]))):
             label = f"{sub[0]}>{sub[1]}" + (f"@{sub[2]}" if len(sub) > 2 and sub[2] else "")
@@ -135,6 +143,7 @@ class GlobalPrior:
                 "n_users": self.n_users[sub],
                 "n_obs": self.n_obs[sub],
                 "mean_effect": round(eff, 6),
+                "source": source,
             })
         return out
 

dee/core/dms_seed.py

@@ -58,7 +58,8 @@ def seed_rows(
         if meas:
             grouped.append((str(assay_id), meas))
     prior = _agg.build_priors(grouped, now=now, enforce_gate=enforce_gate)
-    return prior.to_rows()
+    # Published studies, not platform labs — see migration 0018.
+    return prior.to_rows("dms")
 
 
 def parse_proteingym_csv(text: str) -> List[Tuple[str, float]]:

dee/server.py

@@ -2809,13 +2809,25 @@ def create_app() -> Flask:
         rebuild accrues enough data (that's the honest cold-start, shown as
         such in the UI)."""
         from dee.core import aggregate as _agg
-        rows = _auth.get_mutation_priors()   # [{substitution, n_users, n_obs, mean_effect}]
+        rows = _auth.get_mutation_priors()   # [{substitution, n_users, n_obs, mean_effect, source}]
         total_obs = 0
+        # Count the two provenances SEPARATELY and never sum them into one
+        # "labs contributing" figure. A row seeded from published DMS studies
+        # carries n_users = number of independent STUDIES; reporting that
+        # beside user-contributed rows would assert lab adoption this platform
+        # has not earned. Migration 0018 added the column for exactly this.
+        by_source = {"user": 0, "dms": 0}
+        obs_by_source = {"user": 0, "dms": 0}
         for r in rows:
+            src = r.get("source") or "user"
             try:
-                total_obs += int(r.get("n_obs", 0) or 0)
+                n = int(r.get("n_obs", 0) or 0)
             except (TypeError, ValueError):
-                pass
+                n = 0
+            total_obs += n
+            if src in by_source:
+                by_source[src] += 1
+                obs_by_source[src] += n
         return jsonify({
             "ok": True,
             "substitutions": rows,
@@ -2823,6 +2835,21 @@ def create_app() -> Flask:
             "total_observations": total_obs,
             "min_users": _agg.MIN_USERS,
             "effective_date": _agg.EFFECTIVE_DATE.isoformat(),
+            # The honest breakdown. `from_published_studies` is prior
+            # knowledge the field already had; `from_platform_labs` is the
+            # only number that measures THIS commons growing.
+            "provenance": {
+                "from_published_studies": {
+                    "substitutions": by_source["dms"],
+                    "observations": obs_by_source["dms"],
+                    "unit": "independent published DMS assays",
+                },
+                "from_platform_labs": {
+                    "substitutions": by_source["user"],
+                    "observations": obs_by_source["user"],
+                    "unit": "distinct labs logging wet-lab outcomes",
+                },
+            },
         })
 
     @app.get("/api/benchmarks")
@@ -3108,7 +3135,10 @@ def create_app() -> Flask:
             return jsonify({"ok": False, "error": "gated", "detail": str(exc),
                             "effective_date": _agg.EFFECTIVE_DATE.isoformat()}), 423
 
-        result = _auth.replace_mutation_priors(rows)
+        # source="dms": replaces only the published-study rows, leaving any
+        # user-contributed commons untouched (migration 0018). _seed_rows
+        # already stamps each row source="dms".
+        result = _auth.replace_mutation_priors(rows, source="dms")
         _GLOBAL_PRIOR_CACHE["data"] = None   # bust so the next design sees it immediately
         out = {"ok": bool(result.get("ok")), "substitutions": len(rows),
                "contributing_assays": len(assays)}
@@ -3146,8 +3176,8 @@ def create_app() -> Flask:
         except _agg.AggregationGateError as exc:
             return jsonify({"ok": False, "error": "gated", "detail": str(exc),
                             "effective_date": _agg.EFFECTIVE_DATE.isoformat()}), 423
-        rows = prior.to_rows()
-        result = _auth.replace_mutation_priors(rows)
+        rows = prior.to_rows("user")
+        result = _auth.replace_mutation_priors(rows, source="user")
         _GLOBAL_PRIOR_CACHE["data"] = None              # bust the scorer cache
         return jsonify({"ok": bool(result.get("ok")),
                         "substitutions": len(rows),
@@ -3805,8 +3835,8 @@ def _rebuild_all_priors_once() -> None:
 
     try:
         grouped = _auth.list_all_de_outcomes_grouped()
-        rows = _agg.build_priors(grouped).to_rows()
-        _auth.replace_mutation_priors(rows)
+        rows = _agg.build_priors(grouped).to_rows("user")
+        _auth.replace_mutation_priors(rows, source="user")
         _GLOBAL_PRIOR_CACHE["data"] = None   # this route's own cache
         _agg.bust_cached_global_prior()      # the shared one design_variant_library (chat) reads
         logger.info("prior rebuild: de -> %d substitutions from %d libraries", len(rows), len(grouped))

supabase/migrations/0018_prior_provenance.sql

@@ -0,0 +1,60 @@
+-- 0018_prior_provenance.sql — say where each pooled row CAME FROM.
+--
+-- public.mutation_priors stored `n_users` with no source column, so a row
+-- pooled from three PUBLISHED DMS STUDIES was indistinguishable from one
+-- pooled from three PLATFORM LABS. /api/atlas surfaced that number raw, which
+-- would have read as "3 labs contributed this" the moment the commons was
+-- seeded from public data (dee/core/dms_seed.py) — a claim about traction
+-- that simply is not true.
+--
+-- That distinction is load-bearing for this product specifically. The whole
+-- pitch is that the numbers are inspectable; overstating where they came from
+-- is the one error that cannot be walked back. So provenance is a column, and
+-- the atlas reports the two counts separately.
+--
+-- `source` is deliberately free-form-but-checked rather than an enum: new
+-- provenance kinds (a curated literature import, a partner contribution) are
+-- expected, and a CHECK is cheaper to widen than an enum type is to alter.
+
+alter table public.mutation_priors
+    add column if not exists source text not null default 'user';
+
+alter table public.mutation_priors
+    drop constraint if exists mutation_priors_source_ck;
+alter table public.mutation_priors
+    add constraint mutation_priors_source_ck
+    check (source in ('user', 'dms'));
+
+comment on column public.mutation_priors.source is
+    'Where this pooled row came from. ''user'' = wet-lab outcomes logged by '
+    'platform labs. ''dms'' = published deep-mutational-scanning studies, '
+    'seeded via dee/core/dms_seed.py. For ''dms'' rows n_users counts '
+    'INDEPENDENT STUDIES, not people — /api/atlas must label them separately '
+    'and never sum them into a single "labs contributing" figure.';
+
+-- Same treatment for the per-tool prior, so CRISPR/primer aggregates cannot
+-- drift into the same ambiguity as they start being populated.
+alter table public.outcome_priors
+    add column if not exists source text not null default 'user';
+
+alter table public.outcome_priors
+    drop constraint if exists outcome_priors_source_ck;
+alter table public.outcome_priors
+    add constraint outcome_priors_source_ck
+    check (source in ('user', 'dms'));
+
+comment on column public.outcome_priors.source is
+    'Provenance of this pooled row — see public.mutation_priors.source.';
+
+-- Seeded and user-contributed rows for the same substitution must coexist:
+-- they are different evidence and get counted separately. The old primary key
+-- (substitution alone) would have made a seed overwrite real user data.
+alter table public.mutation_priors
+    drop constraint if exists mutation_priors_pkey;
+alter table public.mutation_priors
+    add primary key (substitution, source);
+
+alter table public.outcome_priors
+    drop constraint if exists outcome_priors_pkey;
+alter table public.outcome_priors
+    add primary key (tool, feature_key, source);

tests/test_admin_benchmarks_seed.py

@@ -162,7 +162,7 @@ def test_seed_commons_against_real_fixture(client, monkeypatch):
     _with_admin(monkeypatch)
     captured = {}
 
-    def fake_replace(rows):
+    def fake_replace(rows, source="user"):
         captured["rows"] = rows
         return {"ok": True}
 
@@ -191,7 +191,7 @@ def test_seed_commons_survives_one_bad_csv(client, monkeypatch, tmp_path):
     degrade to the other assays and report the failure by name."""
     _with_admin(monkeypatch)
     real_fixtures = _fixtures_dir()
-    monkeypatch.setattr(server._auth, "replace_mutation_priors", lambda rows: {"ok": True})
+    monkeypatch.setattr(server._auth, "replace_mutation_priors", lambda rows, source="user": {"ok": True})
     monkeypatch.setattr(server, "__file__", str(tmp_path / "server.py"))
     (tmp_path / "data").mkdir()
     import shutil

tests/test_agent_tools.py

@@ -905,3 +905,65 @@ def test_imported_hosts_are_reachable_through_their_common_aliases(host, expect)
     assert any(p["name"] == expect for p in result["promoters"]), (
         f"{expect} missing from {host}: "
         f"{[p['name'] for p in result['promoters']]}")
+
+
+# ───────── commons provenance (migration 0018) ─────────
+
+def test_seeded_rows_are_labelled_as_published_studies_not_users():
+    """A DMS-seeded row must never be countable as a contributing lab.
+
+    mutation_priors had no source column, so seeding the commons from public
+    deep-mutational-scanning data would have made /api/atlas report
+    "276 substitutions, 3 users each" — which reads as lab adoption that does
+    not exist. For a product whose pitch is that its numbers are inspectable,
+    that is the one error there is no walking back from.
+    """
+    from dee.core import aggregate as _agg
+
+    prior = _agg.GlobalPrior(
+        effects={("W", "L"): 0.5},
+        n_users={("W", "L"): 3},
+        n_obs={("W", "L"): 42},
+    )
+    seeded = prior.to_rows("dms")
+    assert seeded and seeded[0]["source"] == "dms"
+
+    contributed = prior.to_rows()          # default
+    assert contributed[0]["source"] == "user"
+
+    with pytest.raises(ValueError):
+        prior.to_rows("marketing")
+
+
+def test_a_user_rebuild_cannot_wipe_the_seeded_commons(monkeypatch):
+    """The delete must be scoped by source.
+
+    replace_mutation_priors used to clear the WHOLE table before inserting.
+    Once both provenances coexist, the nightly user-prior rebuild would have
+    silently deleted the published-study seed — the kind of failure nobody
+    notices until the atlas is empty again.
+    """
+    from dee import auth as _auth
+
+    monkeypatch.setattr(_auth, "SUPABASE_URL", "https://example.invalid")
+    monkeypatch.setattr(_auth, "SUPABASE_SERVICE_KEY", "test-key")
+
+    seen = {}
+
+    class _Resp:
+        def __enter__(self): return self
+        def __exit__(self, *a): return False
+
+    def fake_urlopen(req, timeout=None):
+        if req.get_method() == "DELETE":
+            seen["delete_url"] = req.full_url
+        return _Resp()
+
+    monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+    _auth.replace_mutation_priors([], source="user")
+
+    assert "source=eq.user" in seen["delete_url"], (
+        f"delete was not scoped by source: {seen['delete_url']}")
+    assert "neq.__none__" not in seen["delete_url"], "still wiping every row"
+
+    assert _auth.replace_mutation_priors([], source="nonsense")["ok"] is False

tests/test_aggregate.py

@@ -131,7 +131,13 @@ def test_to_rows_is_deidentified_and_roundtrips():
     obls = [("u%d" % i, _lib_for_sub((2.0, 0.0))) for i in range(3)]
     out = build_priors(obls, min_users=3, now=AFTER)
     rows = out.to_rows()
-    assert rows and all(set(r) == {"substitution", "n_users", "n_obs", "mean_effect"} for r in rows)
+    # `source` (migration 0018) records provenance and carries no user data —
+    # the exact-key assertion stays exact so a future field that DOES carry
+    # user data still fails here rather than sliding in unnoticed.
+    assert rows and all(
+        set(r) == {"substitution", "n_users", "n_obs", "mean_effect", "source"}
+        for r in rows)
+    assert all(r["source"] == "user" for r in rows)
     # no user ids, no positions, no raw values anywhere in the serialized form
     blob = str(rows)
     assert "u0" not in blob and "u1" not in blob and "10" not in "".join(r["substitution"] for r in rows)