Add Evidence & Research tab + curated/live evidence layer (#185)

Task #185: curated + live (arXiv/GitHub) research evidence layer wired into the console as an Evidence & Research tab; honest live/cached/unreachable labels, no fabrication.

Dockerfile

@@ -427,6 +427,7 @@ COPY szl_budget_router.py ./szl_budget_router.py
 # matrix-health pre-flight reports the module missing. serve.py + szl_governance_gateway
 # import it try/except-guarded. LOCKED-proven stays EXACTLY 5; Lambda=Conjecture 1.
 COPY szl_wave910_proofs.py ./szl_wave910_proofs.py
+COPY szl_evidence_research.py ./szl_evidence_research.py
 
 CMD ["python", "serve.py"]
 

pages/console.html

@@ -291,6 +291,7 @@ details.raw[open] summary{color:var(--muted);}
     <div class="nav-item" data-view="codetab" onclick="go('codetab')"><span class="ico">⌨</span>a11oy Code</div>
     <div class="nav-item" data-view="mcp" onclick="go('mcp')"><span class="ico">⚙</span>Agent Tools</div>
     <div class="nav-item" data-view="honest" onclick="go('honest')"><span class="ico">⊘</span>What We Claim</div>
+    <div class="nav-item" data-view="evidence" onclick="go('evidence')"><span class="ico">⧉</span>Evidence &amp; Research</div>  <!-- evidence-tab-patch-185 -->
     <div class="nav-group">Leader-Grade (NEW)</div>
     <div class="nav-item" data-view="lineage" onclick="go('lineage')"><span class="ico">⚛</span>Knowledge Lineage</div>
     <div class="nav-item" data-view="mission" onclick="go('mission')"><span class="ico">⬢</span>Mission Health</div>
@@ -466,6 +467,7 @@ const HONEST='<div class="honesty"><b>How to read this.</b> Every panel reads a
 const FLOOR=0.9;
 
 const VIEWS={
+  evidence:{title:'Evidence & Research',badge:'CURATED CITATIONS · LIVE arXiv + GitHub',sub:'Every headline claim below is grounded in real, resolvable sources — official standards, public datasets and GitHub repositories. Paper lists and repo stats are fetched <b>live</b> from the arXiv + GitHub APIs and labelled live/cached; if a feed is down the panel degrades to the curated citations, never to invented figures.',render:async(c)=>{window.evidence_render(c);}}, // evidence-tab-patch-185
   command:{title:'Command Center',badge:'LIVE',sub:'One pane of glass over the whole governed-AI platform \u2014 live service health, the connected system map, trust posture, and a verifiable audit trail.',
     render:async(c)=>{c.innerHTML=`<div class="kpis">
       <div class="kpi"><div class="k">Services up</div><div class="v live" id="k-fleet">probing\u2026</div><div class="d">live health probe</div></div>
@@ -1595,6 +1597,49 @@ window.toggleSide=toggleSide;
    can override VIEWS[tab].render. const bindings do NOT auto-attach to window, so we do it
    explicitly here. This is the single source of truth the batch module mutates in place. */
 window.VIEWS=VIEWS; window.go=go;
+/* evidence-tab-patch-185 — curated + live research/evidence layer */
+window.__ev_ns="a11oy";
+window.evidence_live=async function(id){
+  var box=document.getElementById('ev-live-'+id); if(!box) return;
+  box.innerHTML='<div class="dim">fetching live arXiv + GitHub…</div>';
+  try{
+    var r=await fetch('/api/'+window.__ev_ns+'/v1/evidence/research/'+id+'/live');
+    var d=await r.json(); var h=''; var ax=d.arxiv||{};
+    h+='<div class="dim" style="margin:.3rem 0">arXiv ['+esc(ax.mode||'?')+(ax.fetched_at?(' · '+esc(ax.fetched_at)):'')+']</div>';
+    (ax.papers||[]).forEach(function(p){
+      h+='<div class="row"><a href="'+esc(p.url||'#')+'" target="_blank" rel="noopener">'+esc(p.title||'(untitled)')+'</a> <span class="dim">'+esc(p.published||'')+'</span></div>';
+    });
+    if(!((ax.papers||[]).length)) h+='<div class="dim">no live papers ('+esc(ax.mode||'')+') — curated sources above remain valid</div>';
+    h+='<div class="dim" style="margin:.5rem 0 .3rem">GitHub</div>';
+    (d.github||[]).forEach(function(g){
+      var meta=(g.stars!=null?('★ '+g.stars):'')+(g.license?(' · '+esc(g.license)):'')+(g.pushed_at?(' · pushed '+esc(g.pushed_at)):'')+' ['+esc(g.mode||'')+']';
+      h+='<div class="row"><a href="'+esc(g.url||'#')+'" target="_blank" rel="noopener">'+esc(g.repo||'')+'</a> <span class="dim">'+meta+'</span></div>';
+    });
+    box.innerHTML=h;
+  }catch(e){ box.innerHTML='<div class="dim">live evidence unavailable: '+esc(e.message||e)+' — curated sources above remain valid</div>'; }
+};
+window.evidence_render=async function(c){
+  c.innerHTML='<div class="card"><div class="dim">loading curated evidence…</div></div>';
+  try{
+    var r=await fetch('/api/'+window.__ev_ns+'/v1/evidence/research');
+    var d=await r.json(); var h='';
+    if(d.honest) h+='<div class="honesty">'+esc(d.honest)+'</div>';
+    (d.claims||[]).forEach(function(cl){
+      h+='<div class="card"><div><b>'+esc(cl.claim||'')+'</b>'+(cl.maturity?(' <span class="badge">'+esc(cl.maturity)+'</span>'):'')+(cl.tab?(' <span class="dim">→ '+esc(cl.tab)+' tab</span>'):'')+'</div>';
+      h+='<div class="dim" style="margin:.45rem 0 .25rem">Cited sources</div>';
+      (cl.sources||[]).forEach(function(s){
+        h+='<div class="row"><span class="badge">'+esc(s.kind||'src')+'</span> <a href="'+esc(s.url||'#')+'" target="_blank" rel="noopener">'+esc(s.title||'')+'</a>'+(s.note?(' <span class="dim">— '+esc(s.note)+'</span>'):'')+'</div>';
+      });
+      h+='<div style="margin-top:.55rem"><button class="btn ev-live-btn" data-ev="'+esc(cl.id)+'">⟳ Load live arXiv + GitHub</button></div>';
+      h+='<div id="ev-live-'+esc(cl.id)+'" style="margin-top:.5rem"></div></div>';
+    });
+    c.innerHTML=h||'<div class="card"><div class="dim">no claims registered.</div></div>';
+    Array.prototype.forEach.call(c.querySelectorAll('.ev-live-btn'),function(b){
+      b.addEventListener('click',function(){ window.evidence_live(b.getAttribute('data-ev')); });
+    });
+  }catch(e){ c.innerHTML='<div class="card"><div class="dim">evidence layer unavailable: '+esc(e.message||e)+'</div></div>'; }
+};
+/* end evidence-tab-patch-185 */
 const start=(location.hash||'#command').slice(1);
 /* defer initial render until all inline scripts (helpers + frontier loaders) have executed,
    so deep-links to tabs whose loaders live in a later script block resolve correctly */

serve.py

@@ -74,6 +74,15 @@ except ImportError:
 
 app = FastAPI(title="a11oy — Brand Orchestration Layer", version="2.0.0")
 
+# ── Evidence & Research layer (evidence-research-185) — curated + live arXiv/GitHub citations.
+# Additive, try/except-guarded, registered EARLY (before the SPA catch-all). Pure stdlib.
+try:
+    import szl_evidence_research as _szl_evidence_research
+    _szl_evidence_research.register(app, ns="a11oy")
+    print("[a11oy] Evidence & Research registered: /api/a11oy/v1/evidence/research", file=__import__("sys").stderr)
+except Exception as _szl_ev_e:  # pragma: no cover
+    print(f"[a11oy] Evidence & Research NOT registered: {_szl_ev_e!r}", file=__import__("sys").stderr)
+
 # ── BE hardening (Greene) — szl_be_hardening ──
 # Backend hardening: pydantic validation, 60/min/IP rate limit, real OpenAPI at
 # /api/a11oy/openapi.json, /healthz + /readyz (Khipu chain check), JSON logs

szl_evidence_research.py

@@ -0,0 +1,475 @@
+"""
+szl_evidence_research.py — Evidence & Research layer (a11oy + killinchu)
+=======================================================================
+
+Grounds the organ demos in REAL, citeable, REFRESHABLE research instead of
+static prose. For every headline claim a console tab makes, this module ships:
+
+  * a CURATED bundle of real, resolvable sources — official standards /
+    project homes, public datasets, and GitHub repositories (each with a URL);
+  * a LIVE overlay pulled at request time from the arXiv API (papers) and the
+    GitHub REST API (repo stars / last-push / license) so the panel is
+    refreshable, not frozen prose;
+  * honest mode labels (live | cached | curated) on every block — a down feed
+    degrades to the curated bundle, NEVER to fabricated figures.
+
+Doctrine: claims need machine-readable evidence. Nothing here invents a number.
+The only numbers are (a) live counts/stars from the upstream APIs, honestly
+labelled with their fetch time, or (b) absent. There are no synthetic figures
+in this layer; where the wider console shows illustrative values they are
+labelled there. This layer is pure citation + live freshness.
+
+Pattern mirrors a11oy_live_feeds.py / killinchu_live_feeds.py:
+    from szl_evidence_research import register as register_evidence_research
+    register_evidence_research(app, ns="a11oy")
+
+Endpoints (per namespace ns):
+    GET /api/{ns}/v1/evidence/research
+        -> index: curated claims + their static sources (fast, always works)
+    GET /api/{ns}/v1/evidence/research/{claim_id}/live
+        -> refreshable: live arXiv search + live GitHub repo stats for a claim
+    GET /api/{ns}/v1/evidence/research/refresh
+        -> light freshness sweep across every claim (cached, honest)
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from typing import Any, Dict, List, Optional
+
+_UA = "szl-evidence-research/1.0 (+https://a11oy.net; research-evidence layer)"
+_ARXIV = "https://export.arxiv.org/api/query"
+_GH_REPO = "https://api.github.com/repos/"
+
+# ---------------------------------------------------------------------------
+# Curated claim -> evidence map. Every URL below is a real, resolvable source:
+# an official standard, a public dataset, a canonical project home, or a real
+# GitHub repository. arxiv_query drives the LIVE paper overlay.
+# ---------------------------------------------------------------------------
+
+def _src(kind: str, title: str, url: str, note: str = "") -> Dict[str, str]:
+    return {"kind": kind, "title": title, "url": url, "note": note}
+
+
+CLAIMS: Dict[str, List[Dict[str, Any]]] = {
+    # =====================================================================
+    "a11oy": [
+        {
+            "id": "signed-receipts",
+            "tab": "chain",
+            "claim": "Every governed decision emits a cryptographically signed, "
+                     "tamper-evident receipt (DSSE envelope), verifiable offline.",
+            "maturity": "implemented",
+            "sources": [
+                _src("standard", "in-toto Attestation Framework",
+                     "https://github.com/in-toto/attestation",
+                     "Signed software-supply-chain statements; our receipt shape."),
+                _src("standard", "DSSE — Dead Simple Signing Envelope (spec)",
+                     "https://github.com/secure-systems-lab/dsse",
+                     "Envelope + PAE pre-auth encoding our receipts use."),
+                _src("project", "Sigstore — keyless signing & transparency",
+                     "https://www.sigstore.dev/",
+                     "Public-good signing model we mirror."),
+                _src("dataset", "Rekor public transparency log",
+                     "https://rekor.sigstore.dev/",
+                     "Append-only signature transparency (our live Rekor feed)."),
+            ],
+            "github": ["in-toto/attestation", "secure-systems-lab/dsse",
+                       "sigstore/cosign", "sigstore/rekor"],
+            "arxiv_query": "in-toto software supply chain provenance signing",
+        },
+        {
+            "id": "slsa-provenance",
+            "tab": "deploy",
+            "claim": "Container images carry verified SLSA build provenance "
+                     "(L2 on the organs that claim it; remainder on the roadmap).",
+            "maturity": "implemented-partial",
+            "sources": [
+                _src("standard", "SLSA — Supply-chain Levels for Software Artifacts",
+                     "https://slsa.dev/spec/v1.0/levels",
+                     "L1-L4 provenance ladder; we claim L2 honestly."),
+                _src("project", "SLSA GitHub generator",
+                     "https://github.com/slsa-framework/slsa-github-generator",
+                     "Reference provenance generator."),
+                _src("standard", "NIST SSDF (SP 800-218)",
+                     "https://csrc.nist.gov/pubs/sp/800/218/final",
+                     "Secure software development framework."),
+            ],
+            "github": ["slsa-framework/slsa-github-generator", "slsa-framework/slsa"],
+            "arxiv_query": "software supply chain security provenance attestation",
+        },
+        {
+            "id": "policy-gates",
+            "tab": "gates",
+            "claim": "Autonomy is constrained by machine-checkable policy gates; "
+                     "severity is an input, the gate verdict is the decision.",
+            "maturity": "implemented",
+            "sources": [
+                _src("project", "Open Policy Agent (OPA) / Rego",
+                     "https://www.openpolicyagent.org/",
+                     "Policy-as-code engine; our gate model is in this family."),
+                _src("standard", "NIST AI Risk Management Framework (AI RMF 1.0)",
+                     "https://www.nist.gov/itl/ai-risk-management-framework",
+                     "Govern/Map/Measure/Manage functions we map gates onto."),
+                _src("standard", "MITRE ATT&CK",
+                     "https://attack.mitre.org/",
+                     "Adversary technique corpus our gates reference."),
+            ],
+            "github": ["open-policy-agent/opa", "mitre-attack/attack-stix-data"],
+            "arxiv_query": "policy as code safe autonomous agent guardrails",
+        },
+        {
+            "id": "lambda-conjecture",
+            "tab": "lambda",
+            "claim": "The trust score Lambda is a formally specified research "
+                     "conjecture, machine-checked in Lean (advisory, not an oracle).",
+            "maturity": "research",
+            "sources": [
+                _src("project", "Lean 4 theorem prover",
+                     "https://github.com/leanprover/lean4",
+                     "Proof assistant our Lambda formalisation targets."),
+                _src("project", "mathlib4 — Lean mathematical library",
+                     "https://github.com/leanprover-community/mathlib4",
+                     "Background theory used by the formalisation."),
+            ],
+            "github": ["leanprover/lean4", "leanprover-community/mathlib4"],
+            "arxiv_query": "formal verification trust score multi attribute decision Lean",
+        },
+        {
+            "id": "vuln-grounding",
+            "tab": "cve",
+            "claim": "Vulnerability prioritisation reads only public signals "
+                     "(CVSS + CISA-KEV + OSV + EPSS) and labels that it has no "
+                     "environment telemetry.",
+            "maturity": "implemented",
+            "sources": [
+                _src("dataset", "CISA Known Exploited Vulnerabilities (KEV)",
+                     "https://www.cisa.gov/known-exploited-vulnerabilities-catalog",
+                     "Exploited-in-the-wild ground truth (our live KEV feed)."),
+                _src("dataset", "OSV — Open Source Vulnerabilities",
+                     "https://osv.dev/",
+                     "Distributed vuln database (our live OSV feed)."),
+                _src("dataset", "NVD — National Vulnerability Database",
+                     "https://nvd.nist.gov/",
+                     "CVSS base scores (the CVE Watch tab reads this live)."),
+                _src("dataset", "EPSS — Exploit Prediction Scoring System",
+                     "https://www.first.org/epss/",
+                     "Data-driven exploit-likelihood, FIRST.org."),
+            ],
+            "github": ["cisagov/kev-data", "google/osv.dev"],
+            "arxiv_query": "exploit prediction scoring system vulnerability prioritization EPSS",
+        },
+        {
+            "id": "ai-oversight",
+            "tab": "oversight",
+            "claim": "Agentic autonomy is kept under human-auditable oversight; "
+                     "no AGI claims are made.",
+            "maturity": "research",
+            "sources": [
+                _src("standard", "NIST AI RMF — Generative AI Profile (600-1)",
+                     "https://csrc.nist.gov/pubs/ai/600/1/final",
+                     "Risk profile for generative / agentic systems."),
+                _src("standard", "ISO/IEC 42001 — AI management systems",
+                     "https://www.iso.org/standard/81230.html",
+                     "Auditable AI governance management system."),
+            ],
+            "github": ["openai/evals"],
+            "arxiv_query": "AI oversight agent governance constitutional AI alignment",
+        },
+    ],
+    # =====================================================================
+    "killinchu": [
+        {
+            "id": "bft-consensus",
+            "tab": "w910gg",
+            "claim": "Command authority requires Byzantine-fault-tolerant agreement "
+                     "(survives a minority of faulty / compromised nodes).",
+            "maturity": "research",
+            "sources": [
+                _src("project", "PBFT — Practical Byzantine Fault Tolerance (Castro & Liskov)",
+                     "https://pmg.csail.mit.edu/papers/osdi99.pdf",
+                     "Foundational 3f+1 BFT result."),
+                _src("project", "Tendermint / CometBFT consensus",
+                     "https://github.com/cometbft/cometbft",
+                     "Production BFT state machine replication."),
+            ],
+            "github": ["cometbft/cometbft", "hyperledger/fabric"],
+            "arxiv_query": "byzantine fault tolerant consensus multi agent command",
+        },
+        {
+            "id": "sensor-fusion",
+            "tab": "fusion",
+            "claim": "Multi-sensor tracks are fused with covariance-aware estimation "
+                     "(Kalman / covariance intersection) producing valid uncertainty.",
+            "maturity": "implemented",
+            "sources": [
+                _src("project", "FilterPy — Kalman & Bayesian filters",
+                     "https://github.com/rlabbe/filterpy",
+                     "Reference Kalman/UKF implementations."),
+                _src("project", "Covariance Intersection (Julier & Uhlmann)",
+                     "https://en.wikipedia.org/wiki/Covariance_intersection",
+                     "Fuse without known cross-covariance; conservative PSD result."),
+            ],
+            "github": ["rlabbe/filterpy"],
+            "arxiv_query": "covariance intersection sensor fusion track estimation",
+        },
+        {
+            "id": "air-picture",
+            "tab": "livepic",
+            "claim": "The live air picture is built from public ADS-B feeds, "
+                     "honestly labelled live vs cached.",
+            "maturity": "implemented",
+            "sources": [
+                _src("dataset", "adsb.lol — community ADS-B (no auth)",
+                     "https://adsb.lol/",
+                     "Military + civil aircraft feed (our live air feed)."),
+                _src("dataset", "The OpenSky Network",
+                     "https://opensky-network.org/",
+                     "Research-grade ADS-B / Mode-S data."),
+                _src("project", "dump1090 — ADS-B decoder",
+                     "https://github.com/flightaware/dump1090",
+                     "Reference SDR ADS-B decoder."),
+            ],
+            "github": ["flightaware/dump1090", "wiedehopf/readsb"],
+            "arxiv_query": "ADS-B aircraft trajectory anomaly detection surveillance",
+        },
+        {
+            "id": "maritime-picture",
+            "tab": "darkhunt",
+            "claim": "Maritime / dark-vessel hunting reads public AIS; gaps are "
+                     "surfaced as candidate dark vessels, not asserted as targets.",
+            "maturity": "implemented",
+            "sources": [
+                _src("dataset", "Digitraffic — open AIS (Fintraffic)",
+                     "https://www.digitraffic.fi/en/marine-traffic/",
+                     "Open maritime AIS stream (our live AIS feed)."),
+                _src("dataset", "AISStream.io — open AIS websocket",
+                     "https://aisstream.io/",
+                     "Public AIS message stream."),
+            ],
+            "github": ["aisstream/example-code"],
+            "arxiv_query": "AIS dark vessel detection maritime anomaly trajectory",
+        },
+        {
+            "id": "pqc-signing",
+            "tab": "w910audit",
+            "claim": "Receipts can be signed with post-quantum signatures "
+                     "(ML-DSA / Dilithium) per NIST FIPS 204.",
+            "maturity": "implemented",
+            "sources": [
+                _src("standard", "NIST FIPS 204 — ML-DSA (module-lattice signature)",
+                     "https://csrc.nist.gov/pubs/fips/204/final",
+                     "Standardised post-quantum signature."),
+                _src("project", "pq-crystals/dilithium (reference)",
+                     "https://github.com/pq-crystals/dilithium",
+                     "Reference ML-DSA / Dilithium implementation."),
+                _src("project", "Open Quantum Safe — liboqs",
+                     "https://github.com/open-quantum-safe/liboqs",
+                     "PQC algorithm library."),
+            ],
+            "github": ["pq-crystals/dilithium", "open-quantum-safe/liboqs"],
+            "arxiv_query": "ML-DSA Dilithium lattice post-quantum digital signature",
+        },
+        {
+            "id": "stl-monitoring",
+            "tab": "w910stl",
+            "claim": "Runtime behaviour is checked against Signal Temporal Logic "
+                     "rules, returning a signed robustness margin rho.",
+            "maturity": "research",
+            "sources": [
+                _src("project", "Robustness of STL (Donze & Maler, FORMATS 2010)",
+                     "https://link.springer.com/chapter/10.1007/978-3-642-15297-9_9",
+                     "Quantitative robustness semantics (the rho margin)."),
+                _src("project", "RTAMT — runtime STL monitoring",
+                     "https://github.com/nickovic/rtamt",
+                     "Open STL monitor library."),
+            ],
+            "github": ["nickovic/rtamt"],
+            "arxiv_query": "signal temporal logic robustness runtime monitoring",
+        },
+        {
+            "id": "counter-uas",
+            "tab": "engage",
+            "claim": "Counter-UAS engagement reasoning is grounded in published "
+                     "drone-detection research; it is advisory, not a targeting product.",
+            "maturity": "research",
+            "sources": [
+                _src("standard", "FAA UAS Remote ID rule",
+                     "https://www.faa.gov/uas/getting_started/remote_id",
+                     "Regulatory basis for drone identification."),
+                _src("project", "DJI / open drone telemetry references",
+                     "https://github.com/opendroneid/opendroneid-core-c",
+                     "Open Drone ID core library."),
+            ],
+            "github": ["opendroneid/opendroneid-core-c"],
+            "arxiv_query": "counter UAS drone detection deep learning survey",
+        },
+    ],
+}
+
+# ---------------------------------------------------------------------------
+# Live fetch helpers (server-side, cached, honest). No fabrication: on failure
+# we return mode="cached"/"unreachable" and lean on the curated bundle.
+# ---------------------------------------------------------------------------
+
+_CACHE: Dict[str, Dict[str, Any]] = {}
+_TTL = 1800  # 30 min
+
+
+def _get(url: str, timeout: int = 12, headers: Optional[Dict[str, str]] = None) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": _UA, **(headers or {})})
+    with urllib.request.urlopen(req, timeout=timeout) as r:  # nosec - public read-only APIs
+        return r.read()
+
+
+def _arxiv(query: str, limit: int = 5) -> Dict[str, Any]:
+    key = "arxiv:" + query
+    now = time.time()
+    hit = _CACHE.get(key)
+    if hit and now - hit["_t"] < _TTL:
+        return {**hit["v"], "mode": "cached", "fetched_at": hit["at"]}
+    params = urllib.parse.urlencode({
+        "search_query": "all:" + query,
+        "start": 0,
+        "max_results": limit,
+        "sortBy": "relevance",
+    })
+    try:
+        raw = _get(_ARXIV + "?" + params, timeout=14)
+        ns = {"a": "http://www.w3.org/2005/Atom"}
+        root = ET.fromstring(raw)
+        papers = []
+        for e in root.findall("a:entry", ns):
+            link = ""
+            for l in e.findall("a:link", ns):
+                if l.get("rel") == "alternate" or l.get("type") == "text/html":
+                    link = l.get("href") or link
+            title = (e.findtext("a:title", default="", namespaces=ns) or "").strip()
+            summ = (e.findtext("a:summary", default="", namespaces=ns) or "").strip()
+            pub = (e.findtext("a:published", default="", namespaces=ns) or "")[:10]
+            authors = [a.findtext("a:name", default="", namespaces=ns)
+                       for a in e.findall("a:author", ns)][:4]
+            papers.append({
+                "title": title, "url": link or (e.findtext("a:id", default="", namespaces=ns) or ""),
+                "published": pub, "authors": [a for a in authors if a],
+                "summary": summ[:280],
+            })
+        val = {"source": "arXiv API", "source_url": "https://arxiv.org",
+               "query": query, "count": len(papers), "papers": papers}
+        at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        _CACHE[key] = {"v": val, "_t": now, "at": at}
+        return {**val, "mode": "live", "fetched_at": at}
+    except Exception as ex:  # noqa: BLE001
+        if hit:
+            return {**hit["v"], "mode": "cached", "fetched_at": hit["at"],
+                    "note": "live arXiv unreachable; cached result"}
+        return {"source": "arXiv API", "source_url": "https://arxiv.org",
+                "query": query, "count": 0, "papers": [],
+                "mode": "unreachable", "error": str(ex)[:120],
+                "note": "live arXiv unreachable; see curated sources below"}
+
+
+def _github(repo: str) -> Dict[str, Any]:
+    key = "gh:" + repo
+    now = time.time()
+    hit = _CACHE.get(key)
+    if hit and now - hit["_t"] < _TTL:
+        return {**hit["v"], "mode": "cached", "fetched_at": hit["at"]}
+    try:
+        raw = _get(_GH_REPO + repo, timeout=10,
+                   headers={"Accept": "application/vnd.github+json"})
+        d = json.loads(raw)
+        val = {
+            "repo": repo, "url": d.get("html_url") or ("https://github.com/" + repo),
+            "stars": d.get("stargazers_count"),
+            "pushed_at": (d.get("pushed_at") or "")[:10],
+            "license": ((d.get("license") or {}) or {}).get("spdx_id"),
+            "description": (d.get("description") or "")[:160],
+            "archived": bool(d.get("archived")),
+        }
+        at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        _CACHE[key] = {"v": val, "_t": now, "at": at}
+        return {**val, "mode": "live", "fetched_at": at}
+    except Exception as ex:  # noqa: BLE001
+        if hit:
+            return {**hit["v"], "mode": "cached", "fetched_at": hit["at"]}
+        return {"repo": repo, "url": "https://github.com/" + repo,
+                "stars": None, "mode": "unreachable", "error": str(ex)[:120]}
+
+
+_HONEST = (
+    "Evidence layer: every source below is a real, resolvable citation — an "
+    "official standard, a public dataset, or a GitHub repository. Paper lists "
+    "and repo stats are fetched live from the arXiv and GitHub APIs and labelled "
+    "live/cached/unreachable; a down feed degrades to the curated citations, "
+    "never to fabricated figures. No synthetic numbers are introduced here."
+)
+
+
+def _claims_for(ns: str) -> List[Dict[str, Any]]:
+    return CLAIMS.get(ns, CLAIMS.get("a11oy", []))
+
+
+def register(app, ns: str = "a11oy") -> None:
+    """Attach the evidence-research endpoints for namespace ns to a FastAPI app."""
+    try:
+        from fastapi.responses import JSONResponse
+    except Exception:  # pragma: no cover
+        return
+
+    base = "/api/%s/v1/evidence/research" % ns
+
+    @app.get(base)
+    async def _evidence_index():  # noqa: ANN202
+        claims = _claims_for(ns)
+        out = []
+        for c in claims:
+            out.append({
+                "id": c["id"], "tab": c.get("tab"), "claim": c["claim"],
+                "maturity": c.get("maturity"),
+                "sources": c["sources"],
+                "github_repos": c.get("github", []),
+                "arxiv_query": c.get("arxiv_query"),
+                "live_endpoint": "%s/%s/live" % (base, c["id"]),
+            })
+        return JSONResponse({
+            "layer": "%s evidence & research" % ns,
+            "honest": _HONEST,
+            "count": len(out),
+            "claims": out,
+        })
+
+    @app.get(base + "/{claim_id}/live")
+    async def _evidence_live(claim_id: str):  # noqa: ANN202
+        claim = next((c for c in _claims_for(ns) if c["id"] == claim_id), None)
+        if not claim:
+            return JSONResponse({"error": "unknown claim", "claim_id": claim_id}, status_code=404)
+        papers = _arxiv(claim.get("arxiv_query", claim["claim"]))
+        repos = [_github(r) for r in claim.get("github", [])]
+        return JSONResponse({
+            "id": claim["id"], "claim": claim["claim"], "tab": claim.get("tab"),
+            "honest": _HONEST,
+            "sources": claim["sources"],
+            "arxiv": papers,
+            "github": repos,
+        })
+
+    @app.get(base + "/refresh")
+    async def _evidence_refresh():  # noqa: ANN202
+        claims = _claims_for(ns)
+        rows = []
+        for c in claims:
+            p = _arxiv(c.get("arxiv_query", c["claim"]), limit=2)
+            rows.append({
+                "id": c["id"], "claim": c["claim"],
+                "arxiv_count": p.get("count", 0), "arxiv_mode": p.get("mode"),
+                "n_sources": len(c["sources"]), "n_repos": len(c.get("github", [])),
+            })
+        return JSONResponse({
+            "layer": "%s evidence freshness sweep" % ns,
+            "honest": _HONEST, "claims": rows,
+            "fetched_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        })