merge: feat/phase1-knowledge-specialist-s1 — the knowledge specialist's governed ToolUniverse core (ADR-0001): 28-tool allow-list with exactly 12 loaded, no-model-key and load_workspace=False startup guards, 10-field provenance, pinned output schemas, retrieved_at-preserving cache, per-source rate limits, identifier validator, annotation payloads; 117 passed / 1 strict xfail; ADR-0014 scan clean

.gitattributes

@@ -0,0 +1,4 @@
+# Bookkeeping files are union-merged so concurrent lanes' entries both survive
+# (fleet convention). NEVER set merge=union on code or lockfiles.
+memory.md merge=union
+TODO.md merge=union

.github/workflows/tests.yml

@@ -0,0 +1,69 @@
+# The test suite and the formatting check, run on the GitHub mirror (copied from pdac-spatial-agent,
+# where a repo with no workflow let an unformatted file sit for three days).
+#
+# WHERE IT RUNS. Once the Spaces exist, `origin` IS the HuggingFace prod Space and `hf-dev` the dev
+# Space; HuggingFace does not execute GitHub Actions, so this only ever runs via the `github` mirror,
+# which deploys nothing.
+#
+# WHY IT NEEDS NO SECRETS. `tests/conftest.py` blocks outbound sockets before collection and removes
+# every model-provider variable, so the suite is hermetic by enforcement. Install-time network is
+# still required (PyPI). If this job ever starts needing a token, that is a regression in the guard,
+# not a missing secret.
+name: tests
+
+on:
+  pull_request:
+  push:
+    branches: [main, dev]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Separate from pytest on purpose: a style failure and a test failure are different news, and
+  # folding them together hides one behind the other. Safe to gate only because the repo is
+  # formatted from its first commit — a check that fails on day one is one people learn to ignore.
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install ruff (pinned — see requirements-dev.txt)
+        run: pip install "$(grep '^ruff==' requirements-dev.txt)"
+      - name: Check formatting
+        # `format --check` only. `ruff check` (lint) is not gated: it still has pre-existing
+        # findings across files no single lane owns, and gating that would fail on day one.
+        run: ruff format --check .
+
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          # Matches `python_version` in the README front-matter — CI should run what the Space
+          # runs. Note this is 3.12 where most of the fleet is 3.11; that is this Space's setting,
+          # not a copy-paste slip.
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+
+      - name: Install deps
+        # The whole pinned set plus pytest. ToolUniverse (~100 packages) makes this the slow step; the
+        # pip cache above is what keeps it from being slow every time.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Run the suite
+        run: python -m pytest tests/ -q

.gitleaks.toml

@@ -0,0 +1,31 @@
+# Gitleaks config — ADR-0014 secret scan (this repo's copy of the shared definition
+# authored in DecoupleRpy_Agent, ported via pdac-subtype-agent).
+#
+# Extends the upstream default ruleset (do not replace it). Real secrets (HF_TOKEN,
+# `research_agent_token`, `ANTHROPIC_API_KEY`) must NEVER be committed — they live in HF
+# Space secrets. Runs over the working tree AND full git history, because tokens have
+# flowed through these repos.
+#
+# Run:  gitleaks detect --config .gitleaks.toml --redact --no-banner
+
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "known-safe paths and placeholder tokens"
+paths = [
+  '''\.venv/''',
+  '''(^|/)node_modules/''',
+  '''security/sbom\.json''',
+  '''security/pip-audit-.*\.(json|txt)''',
+  '''\.gitleaks\.toml''',
+]
+# Docs and ADRs reference token *names* as identifiers, never their values.
+regexes = [
+  '''research_agent_token''',
+  '''ANTHROPIC_API_KEY''',
+  '''(?i)your[-_]?(hf|api|anthropic)[-_]?(token|key)[-_]?here''',
+  '''(?i)example[-_]?(token|key|secret)''',
+  '''xxx+|placeholder|dummy|fake[-_]?(token|key|secret)''',
+]
+stopwords = ["example", "placeholder", "changeme"]

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+# Pre-commit hooks — shared lint/format baseline across the PDAC-system repos.
+# Install once per clone:  pip install pre-commit && pre-commit install
+# Run on all files:        pre-commit run --all-files
+#
+# NOTE: this is separate from the ADR-0014 *security* pre-push hook
+# (scripts/hooks/pre-push, installed via `make install-hooks`). This one runs
+# ruff at commit time for style/correctness; that one runs the security scan at
+# push time.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff              # lint (uses ruff.toml / [tool.ruff]); --fix applies safe fixes
+        args: [--fix]
+      - id: ruff-format       # formatter (line-length + quote style from config)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=2048]

Makefile

@@ -0,0 +1,36 @@
+# pdac-knowledge-agent — developer entry points. The security targets are this repo's copy
+# of the shared surface ADR-0014 standardizes across the fleet.
+.PHONY: help security-scan security-baseline install-hooks test
+
+help:
+	@echo "make install-hooks      Install the pre-push hook (security gate + GitHub mirror sync on prod deploys)."
+	@echo "make security-scan      Run the security scan (pip-audit, bandit, gitleaks; trivy N/A)."
+	@echo "make security-baseline  Regenerate the accepted-findings bandit baseline."
+	@echo "make test               Run the test suite."
+
+# One scan definition; the pre-push hook and a manual run both call it, so the check
+# cannot drift between entry points.
+security-scan:
+	@bash scripts/security_scan.sh
+
+# Only after intentionally accepting a new finding. Review the diff before committing —
+# a new entry is a new accepted suppression and must be justified in
+# security/ACCEPTED-FINDINGS.md. Targets match the scan: src/ + root-level modules.
+security-baseline:
+	@if command -v bandit >/dev/null 2>&1; then B="bandit"; else B="uvx bandit"; fi; \
+	$$B -r src $$(git ls-files '*.py' | grep -v /) -ll -c bandit.yaml \
+	  -f json -o security/bandit-baseline.json -q; \
+	echo "Wrote security/bandit-baseline.json — review the diff and document any new suppression."
+
+# Git never commits .git/hooks, so this installs one (idempotent).
+# `--git-path hooks` resolves correctly from a linked worktree, where .git is a file.
+# It installs a SHIM, not a copy: scripts/hooks/pre-push-shim runs the tracked hook as it is
+# on `dev`, so an edited gate never needs re-installing (a stale copy silently disabled a gate
+# in pdac-analysis-orchestrator for six days). Run once per clone.
+install-hooks:
+	@hooks_dir="$$(git rev-parse --git-path hooks)"; mkdir -p "$$hooks_dir"; \
+	cp scripts/hooks/pre-push-shim "$$hooks_dir/pre-push"; chmod +x "$$hooks_dir/pre-push"; \
+	echo "Installed $$hooks_dir/pre-push — every push now runs dev's security gate on the pushed commit."
+
+test:
+	@python -m pytest tests/ -q

README.md

@@ -0,0 +1,71 @@
+---
+title: PDAC Knowledge Agent
+emoji: 📚
+colorFrom: indigo
+colorTo: blue
+sdk: gradio
+sdk_version: 6.28.0
+python_version: "3.12"
+app_file: gradio_ui.py
+hf_oauth: true
+pinned: false
+---
+
+# PDAC Knowledge Agent
+
+The knowledge specialist of the PDAC Research Agent System. It looks up what public knowledge
+bases say about named genes, drugs, diseases and trials, and returns **annotation, never
+analysis**: it reads no dataset and computes no statistic. Built per
+[ADR-0001](docs/adr/ADR-0001-knowledge-specialist-contract.md) on a pinned, allow-listed subset
+of [ToolUniverse](https://github.com/mims-harvard/ToolUniverse) (Apache-2.0).
+
+> **Status: Phase 1, slice s1 — the governed core only.** The endpoints, the Gradio app and the
+> deploy descriptor arrive in s2; there is no Space yet. See
+> [the plan](docs/plans/PLAN-phase1-knowledge-specialist.md).
+
+## What it will answer (s2)
+
+| Endpoint | What | Sources |
+|---|---|---|
+| `drugs_for_targets` | Drugs and clinical candidates per target, with mechanism and maximum clinical stage | HGNC → Open Targets; ChEMBL |
+| `trials_for_genes` | ClinicalTrials.gov studies whose intervention matches the gene | ClinicalTrials.gov |
+| `annotate_genes` | Approved name, UniProt accession, protein name, function, subcellular location | HGNC, UniProt |
+| `pathways_for_genes` | Reactome pathways each gene belongs to (membership, not enrichment) | UniProt → Reactome |
+| `targets_for_disease` | Top associated targets, with Open Targets' own association score | Open Targets |
+
+Which TFs or pathways are active, which genes are differentially expressed and which gene sets
+are enriched in a dataset are DecoupleRpy's questions; the literature corpus is lit-agent's.
+
+## The rules, enforced in code
+
+- **Provenance on every row:** source, ToolUniverse tool and version, the query sent, the
+  source's own id and URL, when the source answered, cache hit or miss, licence and licence URL
+  (`src/provenance.py`). A row missing any of them cannot reach a payload.
+- **Annotation, not analysis:** every ok payload is `kind: "annotation"` and carries no
+  `n_for_inference`; a row count is never a sample size (`src/payloads.py`).
+- **Allow-list by construction:** only the tools the endpoints use are loaded, from the approved
+  28 in `config/tools_allowlist.yaml`. Agentic/LLM-backed tools, tool finders, remote MCP
+  servers, web search and key-gated tools can never load, ToolUniverse's workspace and profile
+  are never read, and startup refuses if any model-provider key is set (`src/tu_client.py`).
+- **Pinned output schemas:** a source response that drifts from its schema becomes
+  `upstream_schema_drift`, never a guessed row (`src/schemas/`).
+- **Identifiers only leave the Space:** gene symbols, Ensembl/UniProt/EFO/MONDO/NCT ids and a
+  bounded disease name. Free text, sample ids and numbers are refused before any call
+  (`src/identifiers.py`).
+- **Declared hosts:** every host the loaded tools can reach is in `config/sources.yaml`, checked
+  offline against the installed package. This is a behaviour contract, not an egress firewall:
+  Hugging Face Spaces have no egress allow-list.
+- **Cache and limits:** ephemeral SQLite cache with a TTL per source that keeps the original
+  `retrieved_at`; a token bucket per source; timeouts and limits become structured errors.
+
+## Development
+
+```bash
+uv venv --python 3.12 .venv && uv pip install -r requirements-dev.txt
+python -m pytest                 # hermetic: outbound sockets are blocked
+make security-scan               # ADR-0014: pip-audit, bandit, gitleaks (trivy N/A)
+make install-hooks               # the pre-push security gate, once per clone
+```
+
+`dev` is the integration branch and `main` is production (once the Spaces exist, `main` IS the
+prod Space). Lanes merge to `dev` only.

access.py

@@ -0,0 +1,69 @@
+"""App-layer identity & authorization — the family allow-list gate.
+
+Deliberately mirrors the sibling specialists' ``access.py`` env contract
+(pdac-genomics-agent, pdac-subtype-agent ADR-0012, DecoupleRpy_Agent
+``access_control``) so all Spaces share ONE allow-list model:
+
+- ``ADMIN_IDS``   — comma-separated admin identities (``UPLOAD_ADMIN_IDS`` honored
+  for back-compat with the family contract).
+- ``ALLOWED_IDS`` — comma-separated regular-user identities. Admins are allowed too.
+- ``ACCESS_CONTROL`` — dark-launch switch. OFF unless one of ``1/on/true/enforce/yes``.
+  It is set to enforce on both Spaces before either is made public (plan D2-C). When
+  ON, fail-closed: an empty list denies everyone; unknown/anonymous identities are refused.
+"""
+
+from __future__ import annotations
+
+import os
+
+ADMIN_ROLE = "admin"
+USER_ROLE = "user"
+
+_ADMIN_ENV_VARS = ("ADMIN_IDS", "UPLOAD_ADMIN_IDS")
+_ALLOWED_ENV_VAR = "ALLOWED_IDS"
+_ENFORCE_VALUES = {"1", "on", "true", "enforce", "yes"}
+
+
+def _ids_from_env(*env_vars: str) -> set[str]:
+    ids: set[str] = set()
+    for var in env_vars:
+        raw = os.environ.get(var, "")
+        ids.update(part.strip() for part in raw.split(",") if part.strip())
+    return ids
+
+
+def access_enforced() -> bool:
+    return os.environ.get("ACCESS_CONTROL", "").strip().lower() in _ENFORCE_VALUES
+
+
+def role_for(identity: str | None) -> str | None:
+    if not identity:
+        return None
+    identity = identity.strip()
+    if not identity:
+        return None
+    if identity in _ids_from_env(*_ADMIN_ENV_VARS):
+        return ADMIN_ROLE
+    if identity in _ids_from_env(_ALLOWED_ENV_VAR):
+        return USER_ROLE
+    return None
+
+
+def is_authorized(identity: str | None) -> bool:
+    return role_for(identity) is not None
+
+
+def check_access(username: str | None) -> tuple[bool, str | None]:
+    """(allowed, denial_message). Enforcement off ⇒ everyone allowed."""
+    if not access_enforced():
+        return True, None
+    if not username:
+        return False, (
+            "🔒 Please sign in with your HuggingFace account (button above) to use this tool."
+        )
+    if not is_authorized(username):
+        return False, (
+            f"🔒 Access denied — '{username}' is not on the authorized-users list "
+            "for this deployment. Contact the study admin to request access."
+        )
+    return True, None

audit.py

@@ -0,0 +1,66 @@
+"""Minimal run audit — one record per call, results NEVER stored.
+
+Records who called which endpoint, with how many identifiers and what status. Neither the
+identifiers nor the payload are written (the ADR-0008 posture of the sibling
+specialists — orchestrator persistence stores results in ITS private index; the
+specialist's sink stays result-free). Failure to write never fails a call.
+
+Destination is the configured sink (``LOG_SINK``, see :mod:`logging_sink`): ``local`` by
+default, ``hf`` on the deployed Spaces so the trail survives a rebuild (2026-10-13; the
+temp-dir JSONL this replaced was erased by every rebuild).
+
+The ``hf`` upload runs on a daemon thread: the answer never waits on HuggingFace. A slow or
+failing hub (HF git returned 500s for minutes on 2026-10-13) must not push a call past the
+orchestrator's 120 s budget. The cost is that a record still uploading when the container is
+killed is lost — seconds, against the whole trail before.
+"""
+
+from __future__ import annotations
+
+import datetime
+import secrets
+import threading
+
+from access import access_enforced, role_for
+from logging_sink import get_log_sink, persist_trace_safe
+
+
+def record_run(
+    tool: str,
+    *,
+    username: str | None,
+    n_identifiers: int | None,
+    status: str,
+    run_id: str | None = None,
+) -> threading.Thread | None:
+    """Build and persist one audit record. Returns the upload thread for the ``hf`` sink.
+
+    ``run_id`` is the payload's own id (None for denials and input errors). The record's
+    storage key is that id, or a fresh one when there is none, so no record overwrites
+    another. Fail-open: any error building or writing the record is swallowed.
+    """
+    try:
+        now = datetime.datetime.now(datetime.UTC)
+        key = run_id or f"{now:%Y%m%d_%H%M%S}_{secrets.token_hex(4)}_{status}"
+        record = {
+            "run_id": run_id,
+            "timestamp": now.isoformat(),
+            "tool": tool,
+            "status": status,
+            "n_identifiers": n_identifiers,
+            "principal": username or "anonymous",
+            "role": role_for(username),
+            "enforced": access_enforced(),
+        }
+        sink = get_log_sink()
+        if sink.name != "hf":
+            persist_trace_safe(sink, key, record)
+            return None
+        upload = threading.Thread(
+            target=persist_trace_safe, args=(sink, key, record), name="audit-upload", daemon=True
+        )
+        upload.start()
+        return upload
+    except Exception as e:  # noqa: BLE001 — auditing must never crash a request
+        print(f"[audit] record_run failed: {e}")
+        return None

bandit.yaml

@@ -0,0 +1,15 @@
+# Bandit config — ADR-0014 static-analysis scan (this repo's copy of the shared
+# definition authored in DecoupleRpy_Agent, ported via pdac-subtype-agent).
+#
+# Scope: the app code — `src/` plus every root-level module (scripts/security_scan.sh
+# discovers them). Tests use synthetic data and assert on error paths, so scanning them
+# produces noise without signal. Accepted findings live in security/bandit-baseline.json
+# (the scan fails only on NEW ones) and each is justified in
+# security/ACCEPTED-FINDINGS.md. `-ll` = medium severity and above.
+
+exclude_dirs:
+  - tests
+  - .venv
+  - scripts
+  - docker
+  - .claude

config/sources.yaml

@@ -0,0 +1,133 @@
+# Every external source this Space may call, with the hosts its loaded tools reach (ADR-0001 §6).
+#
+# This file is the honest egress statement, not an egress firewall: Hugging Face Spaces have no
+# egress allow-list, so what this lists is "the hosts this code is built to call", enforced by
+# tests/test_sources_hosts.py (every loaded tool's host must appear here) and by the allow-list
+# loader. The security-review addendum's host table is generated from it (s4), and on any future
+# AWS footprint this list becomes the VPC egress allow-list.
+#
+# Per source:
+#   hosts             hosts the loaded tools call (found in ToolUniverse 1.5.6's tool code/config)
+#   licence           the licence string stamped on every row from this source
+#   licence_url       where that licence is stated
+#   licence_checked   date + how it was checked; "partial" says what could not be confirmed
+#   ttl_seconds       cache lifetime (ADR-0001 §8): 7 days; ClinicalTrials.gov 24 h (recruitment moves)
+#   rate_per_second   token-bucket rate (plan default: at most 3 requests/s per source)
+#   burst             bucket size
+#   timeout_seconds   per-call limit; a timeout becomes a `source_unavailable` entry
+#   coverage_notes    deterministic caveats every payload from this source carries
+#   citation          the attribution line for `attribution[]`
+#
+# PubChem and DGIdb have no Phase 1 endpoint, so none of their tools is loaded; they are listed
+# because they are on the approved allow-list, and their hosts are declared ahead of use.
+
+sources:
+  opentargets:
+    name: "Open Targets Platform"
+    hosts: [api.platform.opentargets.org]
+    licence: "CC0 1.0"
+    licence_url: "https://platform-docs.opentargets.org/licence"
+    licence_checked: "2026-10-20: the licence page states the Platform is marked with CC0 1.0"
+    ttl_seconds: 604800
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes:
+      - "Open Targets lists drugs and clinical candidates with trial or approval evidence; an investigational compound with no trial record (for example MRTX1133 against KRAS G12D) may be absent."
+      - "Open Targets association scores are Open Targets' own scores, relayed as such; they are not a statistic computed here."
+    citation: "Open Targets Platform (platform.opentargets.org)"
+
+  chembl:
+    name: "ChEMBL"
+    hosts: [www.ebi.ac.uk]
+    licence: "CC BY-SA 3.0"
+    licence_url: "https://chembl.gitbook.io/chembl-interface-documentation/about"
+    licence_checked: "2026-10-20: 'made available on a Creative Commons Attribution-Share Alike 3.0 Unported License'"
+    ttl_seconds: 604800
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes:
+      - "ChEMBL data are share-alike (CC BY-SA 3.0): a redistributed table built from these rows must carry the same licence."
+    citation: "ChEMBL, EMBL-EBI (www.ebi.ac.uk/chembl)"
+
+  uniprot:
+    name: "UniProt"
+    hosts: [rest.uniprot.org]
+    licence: "CC BY 4.0"
+    licence_url: "https://www.uniprot.org/help/license"
+    licence_checked: "2026-10-20 partial: the licence page is script-rendered and did not load; every UniProtKB record's copyright line states CC BY 4.0 and points to uniprot.org/terms"
+    ttl_seconds: 604800
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes:
+      - "Only reviewed (Swiss-Prot) human entries are used; a symbol with no reviewed entry (for example a pseudogene such as SORD2P) is reported as unresolved, not guessed."
+    citation: "The UniProt Consortium, UniProtKB (www.uniprot.org)"
+
+  clinicaltrials:
+    name: "ClinicalTrials.gov"
+    hosts: [clinicaltrials.gov]
+    licence: "Public (U.S. National Library of Medicine); NLM terms and conditions apply"
+    licence_url: "https://clinicaltrials.gov/about-site/terms-conditions"
+    licence_checked: "2026-10-20 partial: the terms page did not render; NLM policy (ncbi.nlm.nih.gov/home/about/policies) puts government-created information in the public domain and asks for acknowledgment"
+    ttl_seconds: 86400
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes:
+      - "ToolUniverse narrows an intervention search to trials whose intervention matches the gene (Phase 0 finding 5: 1 pancreas-specific CD40 trial, where a broad API query also returns 2 solid-tumour basket trials). The payload's query_semantics states this."
+    citation: "ClinicalTrials.gov, U.S. National Library of Medicine"
+
+  reactome:
+    name: "Reactome"
+    hosts: [reactome.org]
+    licence: "CC0 1.0"
+    licence_url: "https://reactome.org/license"
+    licence_checked: "2026-10-20: the License Agreement §1(c) releases data under the Creative Commons Public Domain Dedication (CC0). The plan had assumed CC BY 4.0; corrected here."
+    ttl_seconds: 604800
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes:
+      - "Pathway rows are membership (this gene is annotated to this pathway), never enrichment of a gene list."
+    citation: "Reactome Knowledgebase (reactome.org)"
+
+  hgnc:
+    name: "HGNC"
+    hosts: [rest.genenames.org]
+    licence: "No restrictions on access or use (HGNC data release policy); citation requested"
+    licence_url: "https://www.genenames.org/about/"
+    licence_checked: "2026-10-20: 'No restrictions are imposed on access to, or use of, the data provided by the HGNC'; asks users to cite the HUGO Gene Nomenclature Committee (RRID:SCR_002827)"
+    ttl_seconds: 604800
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes: []
+    citation: "HUGO Gene Nomenclature Committee (HGNC), www.genenames.org"
+
+  pubchem:
+    name: "PubChem"
+    hosts: [pubchem.ncbi.nlm.nih.gov]
+    licence: "NCBI places no restrictions on the data; some depositor content may carry its own rights"
+    licence_url: "https://www.ncbi.nlm.nih.gov/home/about/policies/"
+    licence_checked: "2026-10-20: NCBI policy page; PubChem is named among resources that may include third-party material"
+    ttl_seconds: 604800
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes: []
+    citation: "PubChem, U.S. National Library of Medicine"
+
+  dgidb:
+    name: "DGIdb"
+    hosts: [dgidb.org]
+    licence: "Unconfirmed: DGIdb aggregates sources that carry their own terms; rows must name the interaction's source"
+    licence_url: "https://dgidb.org/about"
+    licence_checked: "2026-10-20 partial: no data licence found on dgidb.org; must be confirmed before any DGIdb endpoint ships"
+    ttl_seconds: 604800
+    rate_per_second: 3
+    burst: 3
+    timeout_seconds: 30
+    coverage_notes: []
+    citation: "DGIdb, the Drug Gene Interaction Database (dgidb.org)"

config/tools_allowlist.yaml

@@ -0,0 +1,147 @@
+# The ToolUniverse allow-list — the ONLY tools this Space may ever load.
+#
+# Source of truth: the Phase 0 evaluation memo's 28-tool allow-list across 8 keyless public
+# sources, approved by the project lead 2026-10-13 (memo decision 2: "additions go by config
+# with a review note"). The memo described the tools by function; the exact names below were
+# resolved against ToolUniverse 1.5.6's own tool configs on 2026-10-20 (s1), and every name
+# exists in that version (tests/test_allowlist.py asserts it).
+#
+# `endpoints` names which BCC endpoints use a tool (ADR-0001 §4). Only tools with at least one
+# endpoint are LOADED (ADR-0001 §7); the rest are approved but wait for an endpoint that needs
+# them. Adding a tool here is a reviewed change: give it a `review` note saying who approved it
+# and why. Never add an agentic/LLM-backed tool, the tool finder, a remote MCP server, a
+# web-search backend or a key-gated tool — tests/test_allowlist.py refuses each of those.
+#
+# The five endpoints are built in s2; their tool sets are fixed here so the loaded surface is
+# reviewable before any endpoint code exists.
+
+tooluniverse_version: "1.5.6"
+
+tools:
+  # --- Open Targets (6) ---
+  - name: OpenTargets_get_disease_id_description_by_name
+    source: opentargets
+    endpoints: [targets_for_disease]
+    review: "memo 2026-10-12, approved 2026-10-13 — disease name to EFO/MONDO id"
+  - name: OpenTargets_get_associated_targets_by_disease_efoId
+    source: opentargets
+    endpoints: [targets_for_disease]
+    review: "memo 2026-10-12, approved 2026-10-13 — targets by disease (Phase 0 Q8)"
+  - name: OpenTargets_get_associated_drugs_by_target_ensemblID
+    source: opentargets
+    endpoints: [drugs_for_targets]
+    review: "memo 2026-10-12, approved 2026-10-13 — drugs by target (Phase 0 Q1, Q2, Q7)"
+  - name: OpenTargets_get_associated_drugs_by_disease_efoId
+    source: opentargets
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — drugs by disease"
+  - name: OpenTargets_get_drug_mechanisms_of_action_by_chemblId
+    source: opentargets
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — drug mechanisms"
+  - name: OpenTargets_get_drug_description_by_chemblId
+    source: opentargets
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — drug description"
+
+  # --- ChEMBL (4) ---
+  - name: ChEMBL_search_molecules
+    source: chembl
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — molecule search (Phase 0 found MRTX-1133 only here)"
+  - name: ChEMBL_get_drug
+    source: chembl
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — drug record"
+  - name: ChEMBL_get_drug_mechanisms
+    source: chembl
+    endpoints: [drugs_for_targets]
+    review: "memo 2026-10-12, approved 2026-10-13 — mechanism of action per drug (ADR-0001 §4)"
+  - name: ChEMBL_search_targets
+    source: chembl
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — target search"
+
+  # --- UniProt (4) ---
+  - name: UniProt_search
+    source: uniprot
+    endpoints: [annotate_genes, pathways_for_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — symbol to reviewed human accession (Phase 0 Q4)"
+  - name: UniProt_get_function_by_accession
+    source: uniprot
+    endpoints: [annotate_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — function (Phase 0 Q3)"
+  - name: UniProt_get_recommended_name_by_accession
+    source: uniprot
+    endpoints: [annotate_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — recommended protein name"
+  - name: UniProt_get_subcellular_location_by_accession
+    source: uniprot
+    endpoints: [annotate_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — subcellular location"
+
+  # --- ClinicalTrials.gov (3) ---
+  - name: ClinicalTrials_search_studies
+    source: clinicaltrials
+    endpoints: [trials_for_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — interactive trials lookups (memo decision 3; Phase 0 Q5)"
+  - name: ClinicalTrials_get_study
+    source: clinicaltrials
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — one study by NCT id"
+  - name: ClinicalTrials_search_by_intervention
+    source: clinicaltrials
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — search by intervention"
+
+  # --- PubChem (3) ---
+  - name: PubChem_get_CID_by_compound_name
+    source: pubchem
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — compound name to CID (Phase 0 Q10)"
+  - name: PubChem_get_compound_properties_by_CID
+    source: pubchem
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — compound properties (Phase 0 Q10)"
+  - name: PubChem_get_compound_xrefs_by_CID
+    source: pubchem
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — cross-references"
+
+  # --- Reactome (3) ---
+  - name: Reactome_map_uniprot_to_pathways
+    source: reactome
+    endpoints: [pathways_for_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — protein to pathways (Phase 0 Q9)"
+  - name: Reactome_get_pathway
+    source: reactome
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — one pathway"
+  - name: Reactome_get_pathways_low_entity
+    source: reactome
+    endpoints: [pathways_for_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — lowest-level pathways for an entity (ADR-0001 §4)"
+
+  # --- DGIdb (3) ---
+  - name: DGIdb_get_drug_gene_interactions
+    source: dgidb
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — drug–gene interactions (Phase 0 Q6)"
+  - name: DGIdb_get_gene_druggability
+    source: dgidb
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — druggability categories"
+  - name: DGIdb_get_drug_info
+    source: dgidb
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — drug info"
+
+  # --- HGNC (2) ---
+  - name: HGNC_fetch_gene_by_symbol
+    source: hgnc
+    endpoints: [drugs_for_targets, annotate_genes]
+    review: "memo 2026-10-12, approved 2026-10-13 — approved symbol, name and Ensembl id"
+  - name: HGNC_search_genes
+    source: hgnc
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — gene search"

docs/adr/ADR-0001-knowledge-specialist-contract.md

@@ -0,0 +1,116 @@
+# ADR-0001 — The knowledge specialist: contract, boundary, and what a lookup may claim
+
+**Status:** Accepted 2026-10-20 (project lead: D1-A of `docs/plans/PLAN-phase1-knowledge-specialist.md`, five endpoints
+as drafted).
+Access is set by D2-C: public Spaces behind the allow-list gate.
+**Numbering:** drafted beside the roadmap's planning ADRs and moved into this repo at s1 (2026-10-20); this repo's
+`docs/adr/RESERVED.md` owns the number. No orchestrator ADR number is claimed for Phase 1.
+**Rests on:** the Phase 0 evaluation memo (kept with the roadmap, outside this repo), all four of whose decisions were approved
+2026-10-13: borrow, wrapped; the 28-tool allow-list; ToolUniverse for interactive trials lookups (lit-agent's
+harvester keeps the digest); knowledge lookups joined by the orchestrator, never called from inside DecoupleRpy's
+code agent. It also rests on `pdac-analysis-orchestrator` ADR-0001 (tool_server dispatch), ADR-0002 (machine auth)
+and ADR-0006 (a run card before every tool-server run), and on `pdac-spatial-agent` ADR-0001, the template.
+
+## Context
+
+After any result, scientists ask the same next question: what is known about these genes, and is anything
+targeting them? Today the model answers that from memory, and memory is the one source the rest of the architecture
+refuses to rely on. The Phase 0 test showed that ToolUniverse 1.5.6 answers the ten PDAC lookups as well as direct
+API calls do (9 of 10 equal), keeps up with upstream schema changes we would otherwise maintain, and returns
+structured errors. But it stamps no provenance or licence, it silently rewrites some queries (ClinicalTrials.gov
+"CD40"), it carries LLM-backed and hosted-service tools that must never load, and it changes often (six releases in
+two weeks). The fleet's contract has to sit between ToolUniverse and the orchestrator.
+
+## Decisions
+
+1. **Repo `pdac-knowledge-agent`, agent id `pdac_knowledge_agent`.** Spaces are `anne-voigt/pdac-knowledge-agent`
+   (prod; `main` is prod) and `anne-voigt/pdac-knowledge-agent-dev`, with a GitHub mirror at
+   `Anne-Voigt/pdac-knowledge-agent`. It uses the standard remotes: `origin`, `hf-dev`, `github`.
+2. **Dispatch kind `tool_server`.** Deterministic `gr.api` endpoints, plain strings in and JSON strings out.
+   `mcp_server=True` and the `x-orchestrator-token` machine gate work as they do in the siblings. It is not a
+   CodeAgent, and **it makes no model call.** No LLM-provider key may be set; startup refuses if one is.
+3. **The boundary sentence**, reused verbatim in the descriptor and the routing prompt: *"Looks up what public
+   knowledge bases say about named genes, drugs, diseases and trials (Open Targets, ChEMBL, UniProt,
+   ClinicalTrials.gov, Reactome, HGNC). It returns annotation, never analysis: it reads no dataset and computes no
+   statistic. Which genes are differentially expressed, which TFs or pathways are active, and which gene sets are
+   enriched in a dataset are DecoupleRpy's questions. The literature corpus belongs to lit-agent."*
+4. **Five endpoints, frozen once the descriptor exists:**
+
+   | Endpoint | Input | What it returns | Sources |
+   |---|---|---|---|
+   | `drugs_for_targets` | gene symbols or Ensembl ids | drugs and clinical candidates per target, with mechanism and maximum clinical stage | HGNC → Open Targets; ChEMBL for mechanism |
+   | `trials_for_genes` | gene symbols, optional condition and status | ClinicalTrials.gov studies whose intervention matches the gene, with NCT id, phase, status | ClinicalTrials.gov |
+   | `annotate_genes` | gene symbols | approved name, UniProt accession, recommended protein name, function, subcellular location; unresolved symbols listed | HGNC, UniProt |
+   | `pathways_for_genes` | gene symbols or UniProt accessions | Reactome lowest-level pathways each gene belongs to (membership, not enrichment) | UniProt → Reactome |
+   | `targets_for_disease` | disease name or EFO/MONDO id | top associated targets, with Open Targets' association score labelled as its score | Open Targets |
+
+   No endpoint passes through a raw ToolUniverse tool name. A ToolUniverse version bump may change the code behind
+   an endpoint, but never the endpoint's name or its payload shape.
+5. **The payload contract.** The family invariants apply: `status` is one of `ok`, `refused`, `error` or `denied`,
+   with a `reason` on anything but `ok`. Refusals are data. `run_id` is on everything except denials. The gate runs
+   first, then argument validation. Beyond those:
+   - **`kind: "annotation"` is on every ok payload.** Ok payloads carry no `hierarchy` and no `n_for_inference`. A row
+     count is not a sample size and must never be rendered as one.
+   - **Every row carries `provenance`:** `source`, `source_tool` (the ToolUniverse tool name), `tooluniverse_version`,
+     `query` (the arguments actually sent), `source_ref` (the source's own id: ChEMBL, NCT, UniProt, Reactome or
+     Ensembl), `source_url`, `retrieved_at` (when the source answered, which is not when the cache served it),
+     `cache` (`hit` or `miss`), `licence` and `licence_url`.
+   - **Payload-level fields:** `unresolved[]` (each input not found, with its reason) and `source_errors[]` (each with
+     `source` and one of `source_unavailable`, `rate_limited` or `upstream_schema_drift`). `coverage_notes[]` come
+     from config (for example, that Open Targets may omit investigational compounds that have no trial record, such
+     as MRTX1133). `attribution[]` holds one entry per source used. A deterministic `narrative` is generated from the
+     rows and always says "according to <source> (queried <date>)".
+   - **Output schema check.** Each source's raw response is validated against a pinned schema before any row is
+     built. A mismatch gives `upstream_schema_drift` for that source. Rows are never guessed from a partial match.
+     Phase 0 saw Open Targets rename `knownDrugs` while the test ran; this check is what catches that.
+6. **What may leave the Space: identifiers only.** Allowed inputs are HGNC symbols, Ensembl gene ids, UniProt
+   accessions, EFO/MONDO ids, NCT ids, and disease names as a bounded string (80 characters; letters, digits,
+   spaces, hyphens, commas and apostrophes). At most 100 identifiers per call. Free text, sample ids, expression
+   values and file contents are refused as `invalid_identifier` before any outbound call. Every outbound host is
+   named in `config/sources.yaml`. The Space calls those hosts and nothing else that is ours to configure; this is a
+   behaviour contract, not an egress firewall, and Hugging Face Spaces have no egress allow-list. The security-review
+   wording must say exactly that.
+7. **Allow-list by construction.** `config/tools_allowlist.yaml` holds the approved 28. Only the tools the five
+   endpoints use are loaded. Agentic or LLM-backed tools, the tool finder, remote MCP servers, web-search backends
+   and any key-gated tool can never load. ToolUniverse's own result cache and any download of an embedding model
+   or tool index are switched off. `tooluniverse==1.5.6` is pinned. A version bump is its own lane:
+   `tooluniverse-doctor`, re-recorded fixtures with the diff reviewed, the schema tests, and the security scan.
+   Adding a tool is a config change with a review note.
+8. **Cache and rate limits.** The cache is SQLite inside the container and ephemeral, with a TTL per source from
+   `config/sources.yaml`. A per-source token-bucket limit and a per-call timeout also come from that file. A timeout
+   or limit becomes a structured `source_errors` entry, never a retry loop that outlasts the orchestrator's call
+   limit.
+
+## Knowledge is annotation, never analysis
+
+- The specialist computes nothing across sources: no combined scores, no rankings of its own, no p-values. When a
+  source has its own score (Open Targets' association score), it is relayed as that source's score.
+- Knowledge payloads never enter `biodata-registry`, any statistical step, or the orchestrator's significance
+  chain. In Phase 1 the orchestrator registration declares no `cross_modality_join` partner, and a test asserts
+  that. The Phase 2 recipes may join a knowledge payload to a data result **by identifier only**, and must label the
+  join. That join rule gets its own orchestrator ADR when Phase 2 is shaped.
+- Summaries say "according to <source> (queried <date>)" and never state an external fact flat. A deterministic
+  backstop in the orchestrator flags any drug name, NCT id or ChEMBL id in a summary that is absent from the
+  payload.
+
+## Consequences
+
+- The fleet gets a fifth Space with a 266 MB, 106-package dependency. The memo accepted that under the security scan
+  (ADR-0014 standard), with mandatory pinning and recorded fixtures.
+- **The Space adds runtime calls to eight public hosts.** The OHSU security review's "Where data comes from" lists
+  only GEO, GDC, ICGC, CPTAC and cBioPortal, so the review needs an addendum naming the component and its hosts.
+  Plan slice s4 drafts it in Phase 1. Filing it is the project lead's call, and lab access does not wait for it (plan D2-C).
+- Recorded-fixture tests block outbound sockets, so drift in a source shows up only at a deliberate re-record or as
+  `upstream_schema_drift` in production, never as a silently different answer.
+- DecoupleRpy's `mcp_config.yaml` remote-server path stays unused for knowledge tools (memo decision 4).
+
+## Alternatives rejected
+
+- **Expose `tooluniverse-smcp` directly with category filters.** It has no contract of our own, no provenance, and
+  a version bump would change what the orchestrator sees. Rejected by memo decision 1.
+- **Build thin clients for five sources.** That was the desk review's lean. The hands-on test showed our own Open
+  Targets client breaking on an upstream schema change that ToolUniverse had already absorbed.
+- **Add the endpoints to an existing specialist.** That puts external calls and a large dependency inside a Space
+  that holds data and computes on it, and it blurs the line this ADR exists to draw.
+- **Let the DecoupleRpy code agent call knowledge tools.** Rejected by memo decision 4, for the same provenance
+  reasons as re-mining's chain-first design.

docs/adr/RESERVED.md

@@ -0,0 +1,21 @@
+# ADR number ledger — pdac-knowledge-agent
+
+Claim-first discipline (the fleet pattern): to claim a number, add a CLAIMED row and commit it to
+**`dev`** BEFORE writing the ADR. Here, as in pdac-spatial-agent, `main` IS production once the
+Spaces exist, so a claim on `main` would either strand unpushed or ship a docs-only prod deploy to
+announce an intention; lanes branch from `dev`, which is where a claim is visible to the collision it
+exists to prevent. Statuses: `PUBLISHED`, `CLAIMED`, `EXTERNAL`, `DROPPED`. Family-wide standards
+owned elsewhere are EXTERNAL here, and cross-repo citations are always repo-qualified.
+
+| ADR | Title | Status | Notes |
+|---|---|---|---|
+| 0001 | Knowledge specialist: contract, boundary, and what a lookup may claim | PUBLISHED | accepted 2026-10-20 (project lead, plan D1-A); drafted beside the roadmap's planning ADRs, moved in at s1 |
+| — | Specialist dispatch contracts (tool_server) | EXTERNAL | pdac-analysis-orchestrator ADR-0001 |
+| — | Machine auth (`x-orchestrator-token`) | EXTERNAL | pdac-analysis-orchestrator ADR-0002 |
+| — | A run card before every tool-server run | EXTERNAL | pdac-analysis-orchestrator ADR-0006 |
+| — | Family security scan | EXTERNAL | ADR-0014 (fleet-wide, authored in DecoupleRpy_Agent) |
+
+**Next free number: 0002.**
+
+The orchestrator-side ADR for joining annotation to data results by identifier (Phase 2's recipes)
+belongs to pdac-analysis-orchestrator's ledger, not this one, and is claimed when Phase 2 is shaped.

docs/plans/PLAN-phase1-knowledge-specialist.md

@@ -0,0 +1,201 @@
+# PLAN — A fifth specialist answers "what is known about these genes, and what targets them?" from named public sources, with provenance on every row
+
+**Status:** Approved 2026-10-20 (project lead): D1–D4 decided · **Owner repo:** `pdac-knowledge-agent` (this repo; s1 created
+it and moved this plan in) · **Touches:** pdac-analysis-orchestrator, the fleet status rollup and skills ·
+**Asked:** project lead, 2026-10-20 (roadmap Plan 4 / index plan 3, Phase 1) · **Gate on starting:** none since D4-A
+(2026-10-20): s1 starts now, in parallel with re-mining.
+
+**Why it lives here.** The specialist owns the user-facing outcome, not the orchestrator, so a plan in the
+orchestrator's `docs/design/` would be the copy that drifts. It was drafted beside the roadmap's planning ADRs while
+this repo did not exist, and moved in at s1 with `docs/adr/ADR-0001-knowledge-specialist-contract.md`. This copy is
+the canonical one; the planning folder keeps a pointer.
+
+**Settled before this plan; cited, not re-asked.** All four memo decisions were approved 2026-10-13
+(the Phase 0 evaluation memo, kept with the roadmap): borrow ToolUniverse, wrapped behind BCC endpoints; the 28-tool
+allow-list, with additions by config and a review note; ToolUniverse for interactive trials lookups while
+lit-agent's harvester keeps the digest; knowledge lookups joined by the orchestrator, never called from inside
+DecoupleRpy's code agent. The memo's acceptance of the dependency footprint under the security scan is also settled.
+
+## Brief
+
+- **The ask:** build Phase 1 of the ToolUniverse plan, the skeleton of a knowledge specialist. It wraps the approved
+  allow-list behind the fleet's contract: provenance on every row, output schema checks, caching, rate limits, and
+  external knowledge as annotation, never analysis.
+- **The problem behind it:** after any result, a scientist's next question is what is known about these genes and
+  whether anything targets them. Today the model answers from memory, which is the one source the architecture
+  otherwise refuses to rely on. Phase 2's three recipes (activity → targets, DE genes → trials,
+  signature → annotation) need a governed source to chain to. This phase builds that source and proves it on its
+  own.
+- **Who meets it, and where:** lab members, in orchestrator chat, asking a direct lookup ("which drugs target JAK1
+  and JAK2?"). They get a table with a source, a query date and a licence on each row, after the run card
+  (orchestrator ADR-0006). Later callers are Phase 2's recipes, the knowledge graph (index plan 5's `targets` and
+  `tested_in` edges) and re-mining's optional enrichment.
+- **The boundary:** the sentence in ADR-0001 §3, reused verbatim. The specialist reads no dataset and computes no
+  statistic. Activity, DE and enrichment belong to DecoupleRpy, the literature corpus to lit-agent, and the
+  chained recipes to Phase 2.
+
+## Done when
+
+| # | Check | How |
+|---|---|---|
+| C1 | **The project lead's click-through on the dev orchestrator.** (a) "Which drugs target JAK1, JAK2 or STAT1, and what is their maximum clinical stage?" gives a table with ruxolitinib among the rows. Every row shows its source, query date and licence, and the narrative reads "According to Open Targets (queried …)". (b) "Are there recruiting pancreatic cancer trials with a CD40 intervention?" gives NCT ids plus the sentence stating the query semantics. (c) "Annotate KRAS, TP53 and SORD2P" lists SORD2P as unresolved, not guessed. (d) "Which TFs are most active in basal-like TCGA-PAAD samples?" goes to DecoupleRpy, not here | ticked with screenshots |
+| C2 | **Allow-list by construction.** The loaded tool set equals the five endpoints' set, which is a subset of the 28 in `config/tools_allowlist.yaml`. No agentic, tool-finder, remote-MCP, web-search or key-gated tool can load. Startup refuses if any LLM-provider key is set. `tooluniverse.__version__ == "1.5.6"` at runtime. Loading tools opens no socket | `tests/test_allowlist.py`, `tests/test_no_llm_keys.py` |
+| C3 | **Provenance on every row.** For every endpoint and every fixture, each row carries all ten provenance fields (ADR-0001 §5), and every ok payload has `kind: "annotation"` and no `n_for_inference` | `tests/test_provenance.py` (property test over all fixtures) |
+| C4 | **Output schema checks.** Every recorded response validates against its pinned schema. A fixture mutated the way Open Targets changed during Phase 0 (`knownDrugs` → `drugAndClinicalCandidates`) returns `upstream_schema_drift` for that source, with no rows built from it | `tests/test_output_schemas.py` |
+| C5 | **Cache and rate limits.** A repeated call is a `hit` that keeps the original `retrieved_at`, and the TTL expires per source. A 55-gene burst (the pORG list) never exceeds a source's configured rate. A source timeout becomes a `source_unavailable` entry within the per-call limit | `tests/test_cache.py`, `tests/test_ratelimit.py` |
+| C6 | **Hermetic Phase 0 replay.** Tests block outbound sockets. The ten Phase 0 lookups, recorded once, replay to their expected entities: KRAS G12C gives sotorasib and adagrasib; DR5 gives all 7 agents; pORG gives 54 of 55 with SORD2P unresolved; the CD40 trial semantics are pinned; ISG15, RSAD2 and OAS1 are in Interferon alpha/beta signaling; KRAS G12D has no MRTX1133 from Open Targets, with the coverage note present | `tests/conftest.py` socket block, `tests/test_phase0_replay.py` |
+| C7 | **Refusals are data.** Free text, sample ids, numbers or more than 100 identifiers are refused as `invalid_identifier` or `too_many_identifiers` before any outbound call. A call without the token is `denied`. The gate runs before validation on every handler | `tests/test_refusals_and_payloads.py`, `tests/test_access_gate.py` |
+| C8 | **Hosts are declared.** Each loaded tool's configured endpoint URL has its host in `config/sources.yaml`, and every source there has a licence string and licence URL, checked against the source's own page | `tests/test_sources_hosts.py` |
+| C9 | **Deploy surface.** Descriptor endpoint names equal the live `gr.api` surface on the dev Space. An unauthenticated call to the dev Space is `denied` (the gate fails closed). The prod Space is RUNNING at the verified sha (runtime API) | `tests/test_deploy_surface.py`; runtime sha in the s3 packet |
+| C10 | **Orchestrator registration.** The `agents.yaml` block mirrors the descriptor. It is a tool_server pointing at the prod Space, with the dev override `HF_SPACE_PDAC_KNOWLEDGE_AGENT`. There is no `cross_modality_join` or significance-chain partner, so knowledge never enters analysis. The routing bank has boundary cases going to DecoupleRpy ("which pathways are enriched in…") and to the direct route. `make eval-cheap` is green, and `scripts/build_tool_catalog.py --check` exits 0 with the five rows | `tests/test_knowledge_registration.py`, `eval/routing_cases.json`, `tests/test_tool_catalog.py` |
+| C11 | **Summary backstop.** The rows table and the narrative are rendered from the payload, not from model prose. A summary that names a drug, NCT id or ChEMBL id absent from the payload is flagged. On the recorded KRAS G12D payload, a summary that adds MRTX1133 is caught | `tests/test_knowledge_backstop.py` |
+| C12 | **End to end.** One judged eval case, dev orchestrator to dev knowledge Space, judged PASS, with the trace checked for the payload itself (rows plus provenance). That is one live question, per the credit rule | `eval/` judged case `KNOW-001`; packet cites the run id |
+| C13 | **Security-review addendum drafted** in the review's own language. The component, its eight hosts (generated from `config/sources.yaml`), keyless access, no model calls, the identifiers-only boundary, and the egress sentence from ADR-0001 §6. Filing it with OHSU is the project lead's act, and it does not gate lab access (D2-C) | `scripts/render_host_table.py --check`; the project lead ticks "filed" |
+
+## Options and recommendation
+
+The memo settled the approach. The only real choice left is where the endpoints live:
+
+- **A. A new tool_server specialist from the spatial template (recommended).** Six slices, each S or M. It keeps
+  the 266 MB dependency and the outbound calls out of every Space that holds data, and it is the contract the Phase 2
+  joins and the knowledge graph will consume.
+- **B. Expose `tooluniverse-smcp` with category filters.** It is quick, but it has no contract of our own, and a
+  version bump changes what the router sees. Memo decision 1 rejects it.
+- **C. Put the endpoints in DecoupleRpy or the orchestrator.** It adds no Space, but it puts external calls inside a
+  Space that computes on data, and memo decision 4 rejects calls from inside the code agent.
+
+## Decisions
+
+### Decision D1: accept the knowledge-specialist contract (ADR-0001) as drafted?
+- **Door:** one-way. It freezes the repo, the Space names, five endpoint names and the payload contract that Phase 2,
+  the knowledge graph and re-mining will consume.
+- **Options:**
+  - A) accept as drafted: `pdac-knowledge-agent` / `pdac_knowledge_agent`; the five endpoints from the memo
+    (`drugs_for_targets`, `trials_for_genes`, `annotate_genes`, `pathways_for_genes`, `targets_for_disease`);
+    `kind: annotation` with ten provenance fields per row;
+  - B) only the three endpoints the Phase 2 recipes need (`drugs_for_targets`, `trials_for_genes`,
+    `annotate_genes`), with pathways and disease targets deferred. This removes the boundary risk that
+    `pathways_for_genes` gets mistaken for enrichment;
+  - C) accept with changes she names.
+- **Recommend:** A. The memo named all five. The pathways boundary is held by the routing sentence and a C10 boundary
+  case, and `targets_for_disease` is the lookup Phase 0 found most useful as a sanity check.
+- **Blocks:** s1, s2.
+- **Status:** DECIDED 2026-10-20 (project lead): A — the five endpoints as drafted. ADR-0001 is accepted.
+
+### Decision D2: who may use the new Spaces, and does lab access wait for the security-review addendum?
+- **Door:** one-way. It sets access and visibility. The Space adds runtime calls to eight hosts that OHSU's security
+  review does not list (the review names GEO, GDC, ICGC, CPTAC and cBioPortal), and the review is what a reviewer sees.
+- **Options:**
+  - A) both Spaces private with `ACCESS_CONTROL=enforce` from the first deploy, and admin only until the addendum
+    (C13) is filed with OHSU. After that, the lab allow-list goes on prod, followed by the orchestrator's prod
+    registration (orchestrator-forwarded principals must be on the specialist's `ALLOWED_IDS`);
+  - B) both private and gated, with the lab allow-list on prod as soon as the specialist is verified there, and the
+    addendum in Phase 3 as the roadmap first planned;
+  - C) public Spaces behind the allow-list gate, the older sibling pattern.
+- **Recommend:** A. The addendum is an S slice that s4 drafts in parallel, so the wait costs little. It also keeps
+  the review's "where data comes from" true on the day lab members can reach the new hosts.
+- **Blocks:** s3 (Space settings), and the prod half of s5.
+- **Status:** DECIDED 2026-10-20 (project lead): C — public Spaces behind the allow-list gate, the sibling pattern.
+  - What follows for s3: `ACCESS_CONTROL=enforce` with `ADMIN_IDS` and `ALLOWED_IDS` set before either Space is made
+    public. The gate is verified to fail closed on the dev Space while it is still private (`new-specialist-agent`
+    §5). Every handler calls the access check itself, so an anonymous `gr.api` call is `denied`.
+  - **Lab access is not tied to filing the addendum.** Only option A tied the two, so that is how this answer is
+    read; if the project lead meant otherwise, this line changes and nothing else does.
+  - s4 still drafts the addendum in Phase 1, and when to file it is her call.
+
+### Decision D3: what does the router advertise in Phase 1?
+- **Door:** one-way. It sets what the router offers lab users.
+- **Options:**
+  - A) the five direct lookups go to orchestrator prod once the specialist is verified on its own prod, C11's
+    backstop and C12's judged case pass, and D2's access condition is met;
+  - B) registration on orchestrator dev only, with prod waiting for Phase 2's recipes;
+  - C) no orchestrator work in Phase 1; the specialist is proven on its own Spaces only.
+- **Recommend:** A. Direct lookups are useful on their own. The deterministic table plus the backstop makes the
+  "memory blended with tool results" risk testable now. And Phase 2 then only adds joins on a route that is already
+  proven.
+- **Blocks:** s5.
+- **Status:** DECIDED 2026-10-20 (project lead): A. Under D2-C, "D2's condition" means the lab allow-list is set on the
+  knowledge prod Space (orchestrator-forwarded principals must be on it).
+
+### Decision D4: what gates the first slice, given that re-mining has not shown anything visible yet?
+- **Door:** one-way, in schedule. The roadmap index says the build "waits until Plan 1 has produced something
+  visible", and re-mining Phase 1 had not started. On 2026-10-20 the project lead chose to start this plan in
+  parallel with two others.
+- **Options:**
+  - A) start s1 now. Her 2026-10-20 call supersedes the README order. s1, s2 and s4 are offline, cost zero credits
+    and show nothing to users, and D2 and D3 already hold anything user-facing back;
+  - B) s1, s2 and s4 now, but no Space (s3) until re-mining has something visible (re-mining's start, or Plan 1's
+    first dry-run digest);
+  - C) nothing until re-mining Phase 1 shows its dry-run digest (the README's original order).
+- **Recommend:** A. The README's reason was not to put a new capability in front of the lab ahead of re-mining. D2 and
+  D3 already make every user-facing step the project lead's call, so holding the offline slices back only spends calendar
+  time.
+- **Blocks:** s1 (and through it every slice).
+- **Status:** DECIDED 2026-10-20 (project lead): A — start s1 now.
+
+**Two-way defaults** (DECIDED by default; overrule in one line):
+- The plan and ADR-0001 stay here until s1 moves them into the new repo.
+- **No orchestrator ADR number is claimed in Phase 1.** The knowledge-join ADR (annotation inside chains, the recipe
+  backstop, BYOD-derived gene lists) is claimed when Phase 2 is shaped. That leaves `0008` free for the audit-trail
+  plan.
+- The repo mirrors `pdac-spatial-agent`: Python 3.12, gradio 6.28.0, `access.py`/`audit.py` copied from the newest
+  sibling, the keep-local `.gitignore` from the first commit, the ADR-0014 security scan, and a `dev` branch.
+  It has **no `biodata-registry` dependency**, because it reads no dataset. `src/registry_gate.py` and `src/fetch.py`
+  are replaced by `src/tu_client.py` (the only module that imports `tooluniverse`), `src/provenance.py`,
+  `src/schemas/`, `src/cache.py`, `src/ratelimit.py` and `src/identifiers.py`.
+- Only the tools the five endpoints use are loaded; PubChem and DGIdb wait for an endpoint that needs them.
+  ToolUniverse's own cache is off. Our SQLite cache lives in `/tmp` and is ephemeral, with a 7-day TTL (24 h for
+  ClinicalTrials.gov).
+- Limits per source: at most 3 requests/s, 30 s per call, an endpoint budget of 240 s, and 100 identifiers per call.
+  The orchestrator sets `timeout_seconds: 300` on `annotate_genes`, since the 55 pORG genes took 75 s unbatched in
+  Phase 0. UniProt lookups are batched where its query syntax allows.
+- Trials semantics follow ToolUniverse's intervention-narrowed query, stated in `query_semantics` and pinned by a
+  fixture (memo finding 5). The defaults are condition "pancreatic cancer" and status RECRUITING.
+- Fixtures are recorded once from the ten Phase 0 lookups (live, keyless, from the Mac) in s2. They are re-recorded
+  only in a version-bump lane.
+- Licences per source, as checked in s1 (2026-10-20, `config/sources.yaml`): Open Targets CC0 1.0, ChEMBL CC BY-SA 3.0,
+  UniProt CC BY 4.0, **Reactome CC0 1.0** (not CC BY 4.0 as first assumed), HGNC unrestricted with citation requested,
+  ClinicalTrials.gov public under NLM terms (terms page did not render: partial check). DGIdb's data licence could not
+  be confirmed, so no DGIdb endpoint ships until it is.
+- The specialist writes the narrative. The orchestrator relays it and renders the rows table from the payload. The
+  model adds framing only, and C11's backstop checks it.
+- On the orchestrator side: `own_dataset_universe: true`, with a clarification saying it takes gene, drug, disease
+  or trial names rather than datasets. The run card shows "lookup, not analysis". Catalog rows come through the
+  existing `tool_catalog` annotations.
+- Slice ids `phase1-knowledge-specialist-s<n>` go in branch names, with a `Slice:` trailer on commits.
+
+## Slices
+
+| id | repo | goal (one sentence) | depends on | gates | size | status |
+|---|---|---|---|---|---|---|
+| s1 | pdac-knowledge-agent (new, local only) | Create the repo from the spatial template and build the governed core: the allow-list loader, the no-LLM-key guard, provenance stamping, schema validation, cache, rate limiter, identifier validator and hermetic test harness, behind the security gate; move ADR-0001 and this plan in | D1, D4 (decided) | C2, C5, C8, C3/C4 (core, on synthetic responses) | M | READY |
+| s2 | pdac-knowledge-agent | The five endpoints on recorded Phase 0 fixtures, with deterministic narratives, refusals, `gradio_ui.py` (gate, `mcp_server=True`) and the frozen `deploy/orchestrator_registration.yaml` | s1 | C3, C4, C6, C7 | M | BLOCKED |
+| s4 | pdac-knowledge-agent | Security-review addendum, with its host table generated from `config/sources.yaml`, written in the review's own language | s1 | C13 (drafted) | S | BLOCKED |
+| s3 | pdac-knowledge-agent + HF | Dev and prod Spaces and the GitHub mirror (the project lead creates or approves), each created private. Set the secrets and gate variables, verify the gate fails closed on dev, then make the Spaces public (D2-C). Check the deploy surface on dev, then go to prod through `promote-to-prod` | s2 | C9 | S | BLOCKED |
+| s5 | pdac-analysis-orchestrator | Registration: the `agents.yaml` block, the `prompts.yaml` boundary, routing cases, the registration test, catalog rows, the deterministic table and narrative relay with the entity backstop, and one judged case on dev | s3 on **prod**; prod half also needs the lab allow-list on the knowledge prod Space | C10, C11, C12, C1 | M | BLOCKED |
+| s6 | fleet | Fleet wiring: a status fragment and `build-status.sh` row, plus the repo added to the skills and checks that list repos by name (`promote-to-prod`, `pre-showing-repo-cleanup`, `hf-allowlist`, the weekday health check, the Friday report, the hook fleet path list) | s3 | `grep -l pdac-knowledge-agent` hits each listed file | S | BLOCKED |
+
+- **Order and parallelism:** s1, then s2. s4 can run beside s2 once s1 lands (it needs only `config/sources.yaml`).
+  s3 needs s2 and D2. s5 and s6 can run in parallel once the specialist is on its own prod. Orchestrator prod is
+  last, through `promote-to-prod`, once D2's condition holds.
+- **Fleet rule** (`new-specialist-agent` §8): the specialist reaches its dev Space, then its prod at a verified
+  commit, then the orchestrator's dev registration and a real question end to end, and only then orchestrator prod.
+- **Credits:** s1–s4 and s6 spend none. s5 spends one judged question on dev (C12) and, at promotion, at most one
+  live prod question.
+
+## Out of scope (Phase 2 and later)
+
+- The three chained recipes and their joins. These include the orchestrator ADR on joining annotation to data by
+  identifier, and the 20-question knowledge bank (roadmap §7, Phase 2).
+- **Whether gene lists derived from BYOD or unpublished uploads may be sent to external sources.** Phase 1 has no
+  chain, so its only inputs are identifiers a user types. This becomes a Phase 2 one-way decision.
+- Scheduled smoke runs, the ≥ 95% reliability week, the p95 latency report and the cost report (Phase 3).
+- PubChem and DGIdb endpoints, compound identifiers, and any tool beyond the five endpoints' set.
+- Outbound registration of BCC methods in ToolUniverse (Phase 4, after Plan 5).
+- lit-agent's ClinicalTrials.gov harvester, which stays as it is (memo decision 3).
+
+## Kickoffs and pointers
+
+- Kickoffs are keep-local (`docs/tasks/`, gitignored). s1's was written beside the roadmap's planning ADRs; s2's and
+  s4's are written into this repo's `docs/tasks/` when s1 merges. s5's goes in the orchestrator's `docs/tasks/`.
+- The roadmap's Plan 4 file points at this plan. DecoupleRpy is not touched by Phase 1 (memo decision 4).

logging_sink.py

@@ -0,0 +1,123 @@
+"""Configurable sink for audit-record persistence.
+
+Copied from `pdac-spatial-agent/logging_sink.py` (genomics → subtype → spatial) so every
+Space in the family shares one audit-sink contract. The destination is a CONFIG value (the
+`LOG_SINK` env var), not a hardcoded path — prep for a future migration to OHSU-managed AWS.
+
+Why it exists in the family (2026-10-13): a sink that wrote JSONL to the container's temp dir
+lost the whole trail on every rebuild, because the Spaces have no persistent storage.
+
+**No redaction layer, deliberately.** Runs are structured tool calls and `audit.py` builds a
+record that by construction holds no results and no query identifiers, only a count. The
+record is safe *by shape*.
+
+Every sink implements one method::
+
+    persist_trace(run_id: str, trace: dict) -> str | None
+
+returning a location string on success, or None on failure/no-op. Callers use
+:func:`persist_trace_safe` so a logging failure NEVER crashes a user request.
+
+Env vars (all optional):
+
+  LOG_SINK               local | hf            (default: local)
+  LOG_SINK_LOCAL_DIR     output directory      (default: AUDIT_DIR, else <tmp>/pdac-knowledge-agent-audit)
+  LOG_SINK_HF_DATASET    dataset repo id       (default: anne-voigt/pdac-knowledge-results)
+  LOG_SINK_HF_TOKEN      HF write token        (falls back to research_agent_token;
+                                                no token => no-op)
+
+**Never co-mingle with a sibling's results dataset** — this Space writes to its own
+`pdac-knowledge-results` repo.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+DEFAULT_HF_DATASET = "anne-voigt/pdac-knowledge-results"
+
+
+class LogSink:
+    """Common interface for audit-record persistence."""
+
+    name = "base"
+
+    def persist_trace(self, run_id: str, trace: dict) -> str | None:
+        raise NotImplementedError
+
+
+class LocalLogSink(LogSink):
+    """Write the record JSON to a directory on local disk (the default).
+
+    On a Space this directory is ephemeral: it is for local runs and tests, not an audit trail.
+    """
+
+    name = "local"
+
+    def __init__(self, directory: str | None = None):
+        self.directory = (
+            directory
+            or os.environ.get("LOG_SINK_LOCAL_DIR")
+            or os.environ.get("AUDIT_DIR")  # the pre-2026-10-13 variable, still honoured
+            or str(Path(tempfile.gettempdir()) / "pdac-knowledge-agent-audit")
+        )
+
+    def persist_trace(self, run_id: str, trace: dict) -> str | None:
+        os.makedirs(self.directory, exist_ok=True)
+        path = os.path.join(self.directory, f"{run_id}.json")
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(trace, fh, indent=2)
+        return path
+
+
+class HFDatasetLogSink(LogSink):
+    """Write the record to a private HuggingFace dataset repo (the deployed-Space posture).
+
+    One file per record (``runs/<run_id>.json``), so concurrent calls never contend for a
+    shared file. No-ops (returns None) when no write token is configured, so a Space without
+    the secret degrades to "not logged" rather than erroring on every request.
+    """
+
+    name = "hf"
+
+    def __init__(self, repo_id: str | None = None, token: str | None = None):
+        self.repo_id = repo_id or os.environ.get("LOG_SINK_HF_DATASET", DEFAULT_HF_DATASET)
+        self.token = (
+            token or os.environ.get("LOG_SINK_HF_TOKEN") or os.environ.get("research_agent_token")
+        )
+
+    def persist_trace(self, run_id: str, trace: dict) -> str | None:
+        if not self.token:
+            return None
+        from huggingface_hub import HfApi
+
+        path_in_repo = f"runs/{run_id}.json"
+        HfApi(token=self.token).upload_file(
+            path_or_fileobj=json.dumps(trace, indent=2).encode("utf-8"),
+            path_in_repo=path_in_repo,
+            repo_id=self.repo_id,
+            repo_type="dataset",
+            commit_message=f"audit: {trace.get('tool', '?')} {trace.get('status', '?')}",
+        )
+        return f"{self.repo_id}/{path_in_repo}"
+
+
+_SINKS = {"local": LocalLogSink, "hf": HFDatasetLogSink}
+
+
+def get_log_sink() -> LogSink:
+    """The sink selected by the `LOG_SINK` env var (default `local`)."""
+    choice = os.environ.get("LOG_SINK", "local").strip().lower()
+    return _SINKS.get(choice, LocalLogSink)()
+
+
+def persist_trace_safe(sink: LogSink, run_id: str, trace: dict) -> str | None:
+    """Persist via `sink`, swallowing any failure (auditing must never break a request)."""
+    try:
+        return sink.persist_trace(run_id, trace)
+    except Exception as e:  # noqa: BLE001
+        print(f"[logging_sink] persist_trace failed ({sink.name}): {e}")
+        return None

pytest.ini

@@ -0,0 +1,6 @@
+[pytest]
+# `tests/` only, so a hand-run script under scripts/ can never be collected (the DecoupleRpy
+# 2026-09 lesson), and the repo root on sys.path so `src` and the root modules import.
+testpaths = tests
+pythonpath = .
+addopts = -q

requirements-dev.txt

@@ -0,0 +1,12 @@
+# Test-only dependencies. Deliberately NOT in requirements.txt: that file IS the Space's build
+# input, so anything added there is installed into production.
+#
+# It layers on requirements.txt rather than restating it — one pinned runtime set, extended, so
+# CI resolves the same versions the Space builds from.
+-r requirements.txt
+
+pytest==9.1.1
+
+# Pinned, not floating: the formatter's output may change between ruff releases. Same version
+# the rest of the fleet pins.
+ruff==0.16.9

requirements.in

@@ -0,0 +1,30 @@
+# Curated top-level dependencies for pdac-knowledge-agent (HF gradio Space, py3.12).
+# Same convention as the sibling specialists: THIS file is edited by hand; requirements.txt is
+# the full lock HF actually installs, regenerated via:
+#
+#   uv pip compile requirements.in -o requirements.txt \
+#       --python-version 3.12 --python-platform linux
+#
+# uv prefers the versions already in requirements.txt, so a recompile only moves what a changed
+# line forces. Check `git diff requirements.txt` shows only what you meant to move. Because
+# requirements.txt is a compiled lock, scripts/security_scan.sh audits it as-is
+# (pip-audit --no-deps), transitive dependencies included.
+#
+# There is NO biodata-registry line: this specialist reads no dataset (ADR-0001 §3).
+
+# --- UI / MCP ---
+# Pinned to the Space's sdk_version (README front matter). HF's generated Dockerfile installs
+# `gradio[oauth,mcp]==<sdk_version>` in the same pip command as this lock, so the extras are named
+# here too and the audit sees exactly what the Space installs.
+gradio[oauth,mcp]==6.28.0
+
+# --- ToolUniverse (ADR-0001 §7) ---
+# Pinned EXACTLY. config/tools_allowlist.yaml carries the same version and src/tu_client.py
+# refuses to start on a mismatch. A bump is its own lane: tooluniverse-doctor, re-recorded
+# fixtures with the diff reviewed, the schema tests, and this repo's security scan. The memo
+# accepted its footprint (~100 packages) under that scan, 2026-10-13.
+tooluniverse==1.5.6
+
+# --- Config and output-schema checks ---
+PyYAML==6.0.3
+jsonschema==4.26.0

requirements.txt

@@ -0,0 +1,397 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile requirements.in -o requirements.txt --python-version 3.12 --python-platform linux
+aiofile==3.12.3
+    # via py-key-value-aio
+annotated-doc==0.0.5
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.8.0
+    # via pydantic
+anyio==4.15.1
+    # via
+    #   boltz-api
+    #   gradio
+    #   httpx
+    #   mcp
+    #   py-key-value-aio
+    #   sse-starlette
+    #   starlette
+    #   watchfiles
+attrs==26.1.0
+    # via
+    #   cyclopts
+    #   jsonschema
+    #   jsonschema-path
+    #   referencing
+authlib==1.9.1
+    # via
+    #   fastmcp-slim
+    #   gradio
+beartype==0.23.1
+    # via py-key-value-aio
+beautifulsoup4==4.15.0
+    # via tooluniverse
+boltz-api==0.46.0
+    # via tooluniverse
+brotli==1.2.0
+    # via gradio
+cachetools==7.2.4
+    # via py-key-value-aio
+caio==0.12.9
+    # via aiofile
+certifi==2026.10.19
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+cffi==2.1.1
+    # via cryptography
+charset-normalizer==3.5.2
+    # via
+    #   pdfminer-six
+    #   requests
+click==8.5.0
+    # via
+    #   huggingface-hub
+    #   uvicorn
+cryptography==50.0.2
+    # via
+    #   authlib
+    #   joserfc
+    #   pdfminer-six
+    #   pyjwt
+    #   secretstorage
+cyclopts==5.2.0
+    # via fastmcp-slim
+distro==1.9.0
+    # via boltz-api
+dnspython==2.9.0
+    # via email-validator
+docstring-parser==0.18.0
+    # via cyclopts
+email-validator==2.3.0
+    # via pydantic
+et-xmlfile==2.0.0
+    # via openpyxl
+exceptiongroup==1.3.1
+    # via fastmcp-slim
+faiss-cpu==1.12.0
+    # via tooluniverse
+fastapi==0.156.2
+    # via
+    #   gradio
+    #   tooluniverse
+fastmcp==3.4.10
+    # via tooluniverse
+fastmcp-slim==3.4.10
+    # via fastmcp
+filelock==4.2.4
+    # via huggingface-hub
+fsspec==2026.9.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+gradio==6.28.0
+    # via -r requirements.in
+gradio-client==2.7.1
+    # via
+    #   gradio
+    #   hf-gradio
+graphql-core==3.3.0
+    # via
+    #   rcsb-api
+    #   tooluniverse
+griffelib==2.4.0
+    # via fastmcp-slim
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-gradio==0.4.1
+    # via gradio
+hf-xet==1.7.0
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   boltz-api
+    #   fastmcp-slim
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   mcp
+    #   rcsb-api
+    #   safehttpx
+httpx-sse==0.4.3
+    # via mcp
+huggingface-hub==1.33.0
+    # via
+    #   gradio
+    #   gradio-client
+    #   tooluniverse
+idna==3.20
+    # via
+    #   anyio
+    #   email-validator
+    #   httpx
+    #   requests
+itsdangerous==2.2.0
+    # via gradio
+jaraco-classes==3.4.0
+    # via keyring
+jaraco-context==6.1.2
+    # via keyring
+jaraco-functools==4.6.0
+    # via keyring
+jeepney==0.9.0
+    # via
+    #   keyring
+    #   secretstorage
+jinja2==3.1.6
+    # via gradio
+joserfc==1.7.7
+    # via
+    #   authlib
+    #   fastmcp-slim
+jsonpath-ng==1.11.0
+    # via tooluniverse
+jsonref==1.1.0
+    # via fastmcp-slim
+jsonschema==4.26.0
+    # via
+    #   -r requirements.in
+    #   mcp
+    #   tooluniverse
+jsonschema-path==0.5.0
+    # via fastmcp-slim
+jsonschema-specifications==2025.9.1
+    # via jsonschema
+keyring==25.7.0
+    # via py-key-value-aio
+lxml==6.1.3
+    # via tooluniverse
+markdown-it-py==4.2.0
+    # via rich
+markupsafe==3.0.4
+    # via
+    #   gradio
+    #   jinja2
+mcp==1.30.0
+    # via
+    #   fastmcp-slim
+    #   gradio
+    #   tooluniverse
+mdurl==0.1.2
+    # via markdown-it-py
+more-itertools==11.2.1
+    # via
+    #   jaraco-classes
+    #   jaraco-functools
+nest-asyncio==1.6.0
+    # via rcsb-api
+numpy==2.5.4
+    # via
+    #   faiss-cpu
+    #   gradio
+    #   pandas
+    #   rustworkx
+    #   tooluniverse
+openapi-pydantic==0.6.0
+    # via fastmcp-slim
+openpyxl==3.1.5
+    # via tooluniverse
+opentelemetry-api==1.45.1
+    # via
+    #   fastapi
+    #   fastmcp-slim
+orjson==3.13.0
+    # via gradio
+packaging==26.3
+    # via
+    #   faiss-cpu
+    #   fastmcp-slim
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+pandas==3.0.6
+    # via
+    #   gradio
+    #   tooluniverse
+pathable==0.6.0
+    # via jsonschema-path
+pdfminer-six==20260107
+    # via pdfplumber
+pdfplumber==0.11.10
+    # via tooluniverse
+pillow==12.3.0
+    # via
+    #   gradio
+    #   pdfplumber
+pip==26.2.2
+    # via tooluniverse
+platformdirs==4.13.5
+    # via fastmcp-slim
+py-key-value-aio==0.4.6
+    # via fastmcp-slim
+pycparser==3.11
+    # via cffi
+pydantic==2.12.5
+    # via
+    #   boltz-api
+    #   fastapi
+    #   fastmcp-slim
+    #   gradio
+    #   mcp
+    #   openapi-pydantic
+    #   pydantic-settings
+    #   tooluniverse
+pydantic-core==2.41.5
+    # via pydantic
+pydantic-settings==2.16.1
+    # via
+    #   fastmcp-slim
+    #   mcp
+pydub==0.25.1
+    # via gradio
+pygments==2.21.0
+    # via
+    #   rich
+    #   rich-rst
+pyjwt==2.15.1
+    # via mcp
+pypdfium2==5.14.0
+    # via pdfplumber
+pyperclip==1.11.0
+    # via fastmcp-slim
+python-dateutil==2.9.0.post0
+    # via pandas
+python-dotenv==1.2.4
+    # via
+    #   fastmcp-slim
+    #   mcp
+    #   pydantic-settings
+    #   tooluniverse
+python-multipart==0.0.32
+    # via
+    #   fastmcp-slim
+    #   gradio
+    #   mcp
+pytz==2026.5
+    # via gradio
+pyyaml==6.0.3
+    # via
+    #   -r requirements.in
+    #   fastmcp-slim
+    #   gradio
+    #   huggingface-hub
+    #   jsonschema-path
+    #   tooluniverse
+rcsb-api==1.7.3
+    # via tooluniverse
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-path
+    #   jsonschema-specifications
+requests==2.34.2
+    # via tooluniverse
+rich==15.0.0
+    # via
+    #   cyclopts
+    #   fastmcp-slim
+    #   rich-rst
+    #   typer
+rich-rst==2.2.0
+    # via cyclopts
+rpds-py==2026.9.1
+    # via
+    #   jsonschema
+    #   referencing
+rustworkx==0.18.1
+    # via rcsb-api
+safehttpx==0.1.7
+    # via gradio
+secretstorage==3.5.0
+    # via keyring
+semantic-version==2.10.0
+    # via gradio
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via python-dateutil
+sniffio==1.3.1
+    # via boltz-api
+soupsieve==3.0.3
+    # via beautifulsoup4
+sse-starlette==3.5.0
+    # via mcp
+starlette==1.9.0
+    # via
+    #   fastapi
+    #   fastmcp-slim
+    #   gradio
+    #   mcp
+    #   sse-starlette
+tomlkit==0.14.0
+    # via gradio
+tooluniverse==1.5.6
+    # via -r requirements.in
+tqdm==4.70.1
+    # via
+    #   huggingface-hub
+    #   rcsb-api
+typer==0.27.3
+    # via
+    #   gradio
+    #   hf-gradio
+    #   mcp
+typing-extensions==4.16.0
+    # via
+    #   anyio
+    #   beautifulsoup4
+    #   boltz-api
+    #   exceptiongroup
+    #   fastapi
+    #   fastmcp-slim
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   mcp
+    #   opentelemetry-api
+    #   py-key-value-aio
+    #   pydantic
+    #   pydantic-core
+    #   pydantic-settings
+    #   referencing
+    #   starlette
+    #   typing-inspection
+typing-inspection==0.4.4
+    # via
+    #   fastapi
+    #   mcp
+    #   pydantic
+    #   pydantic-settings
+uncalled-for==0.4.1
+    # via fastmcp-slim
+urllib3==2.8.0
+    # via
+    #   requests
+    #   tooluniverse
+uvicorn==0.54.0
+    # via
+    #   fastmcp-slim
+    #   gradio
+    #   mcp
+    #   tooluniverse
+watchfiles==1.3.0
+    # via fastmcp-slim
+websockets==17.3
+    # via
+    #   fastmcp-slim
+    #   tooluniverse
+xmltodict==1.0.4
+    # via tooluniverse

ruff.toml

@@ -0,0 +1,23 @@
+# Ruff configuration. Its job today is to pin the line length, because without a config file every
+# contributor and every CI runner silently uses ruff's default of 88 while this fleet writes at 100.
+#
+# That is not theoretical here. On 2026-09-25, porting `memory.py` into this repo, a reflexive
+# `ruff format` reformatted the shared builder to 88 — breaking the byte-identity with the other
+# five copies that is the entire point of sharing it. Caught and reverted, but the next person gets
+# no warning either. This file is the warning.
+
+line-length = 100
+
+# **py312, unlike the siblings' py311** — deliberately, and not a copy-paste slip: this Space runs
+# `python_version: "3.12"` (README front-matter). target-version tells ruff which syntax is valid,
+# so it should describe the interpreter the code actually runs on, not the one next door.
+target-version = "py312"
+
+exclude = [".venv", "run_logs", "security"]
+
+[format]
+quote-style = "double"
+
+[lint]
+# Ruff's defaults. Turning on more rules is a separate decision from writing down a line length,
+# and would arrive as findings across files this lane does not own.

scripts/hooks/pre-push

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# Two jobs, in this order (the genomics-agent pattern):
+#   1. ADR-0014 security gate — runs on EVERY push. Blocks on findings.
+#   2. GitHub mirror sync — only on a PROD deploy (`main` to `origin`). Warns, never blocks.
+# The gate runs first, so a blocked deploy can never have already updated the mirror.
+#
+# --- 1. ADR-0014 pre-push security gate ----------------------------------------------------
+#
+# `origin` and `hf-dev` ARE HuggingFace Spaces — a push builds a live Space — so there is
+# no CI merge gate in front of them. This hook is the enforced check: it runs the shared
+# scan (scripts/security_scan.sh) before anything leaves the machine.
+#
+# It scans the commit being PUSHED, not the working tree it happens to run from. The
+# sibling hooks scan the working tree, and on 2026-09-21 that went wrong in the
+# orchestrator: pushed from a checkout parked on another lane's branch, the scan audited
+# THAT branch's requirements.txt instead of the commit being shipped. Here each pushed sha
+# is checked out into a throwaway worktree and scanned there; reports (and the cached
+# audit venv) are written to this checkout's security/ so they outlive it.
+#
+# Install with:  make install-hooks
+# Bypass (e.g. a docs-only push, knowingly):  git push --no-verify
+# Set SECURITY_SCAN_STRICT=1 to fail on skipped stages.
+set -euo pipefail
+
+# The mirror push below sets this, so that nested push is neither rescanned nor re-mirrored.
+[[ -n "${SECURITY_SCAN_DONE:-}" ]] && exit 0
+
+remote_name="${1:-}"
+remote_url="${2:-}"
+mirror_remote="${MIRROR_REMOTE:-github}"
+dev_remote="${DEV_REMOTE:-hf-dev}"
+repo_root="$(git rev-parse --show-toplevel)"
+
+# stdin: "<local ref> <local sha> <remote ref> <remote sha>" per ref being pushed. Git sends it
+# once and both jobs need it, so it is read here and replayed from the variable.
+push_lines="$(cat)"
+shas=()
+while read -r _lref lsha _rref _rsha; do
+  [[ -n "${lsha:-}" ]] || continue
+  case "$lsha" in *[!0]*) ;; *) continue ;; esac          # all-zero = a delete; nothing to scan
+  [[ " ${shas[*]-} " == *" $lsha "* ]] || shas+=("$lsha")
+done <<< "$push_lines"
+[[ ${#shas[@]} -gt 0 ]] || exit 0
+
+# Sweep leaks from earlier interrupted pushes. Named (not `mktemp -d`) so a leak is
+# identifiable, and keyed on LIVENESS rather than age: each scan dir records its hook's PID
+# and its scan child's, so a dir whose hook is gone is swept at once while a CONCURRENT
+# push's dir is never touched. A dir with no .hookpid predates this and is by definition a
+# leak. (2026-09-23: a leaked worktree was found with `git worktree add`'s inner
+# `git reset --hard` still sleeping after 2 days 7 hours, in a directory macOS had reaped.)
+for stale in "${TMPDIR:-/tmp}"/pre-push-scan.*; do
+  [[ -d "$stale" ]] || continue
+  stale_pid="$(cat "$stale/.hookpid" 2>/dev/null || true)"
+  if [[ -z "$stale_pid" ]] || ! kill -0 "$stale_pid" 2>/dev/null; then
+    stale_scan="$(cat "$stale/.scanpid" 2>/dev/null || true)"
+    if [[ -n "$stale_scan" ]] && kill -0 "$stale_scan" 2>/dev/null; then
+      kill -TERM "-$stale_scan" 2>/dev/null || kill -TERM "$stale_scan" 2>/dev/null || true
+      sleep 1
+      if kill -0 "$stale_scan" 2>/dev/null; then
+        kill -KILL "-$stale_scan" 2>/dev/null || kill -KILL "$stale_scan" 2>/dev/null || true
+      fi
+    fi
+    for wt in "$stale"/wt-*; do
+      [[ -d "$wt" ]] && git worktree remove --force "$wt" >/dev/null 2>&1
+    done
+    rm -rf "$stale"
+    echo "[pre-push] swept a leaked scan directory from an interrupted push: $(basename "$stale")"
+  fi
+done
+git worktree prune >/dev/null 2>&1 || true
+
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/pre-push-scan.XXXXXX")"
+echo "$$" > "$tmp/.hookpid"
+scan_pid=""
+cleanup() {
+  # Kill the scan BEFORE its directory disappears: deleting the tree under a live child is
+  # how a gitleaks or `git reset --hard` ends up running in a path that no longer exists.
+  if [[ -n "$scan_pid" ]] && kill -0 "$scan_pid" 2>/dev/null; then
+    # Negative pid = the whole process group. run_scan starts the job with `set -m` so it
+    # gets its own group; signalling the group takes gitleaks / pip-audit / bandit down with
+    # the shell that launched them, instead of reparenting them to init.
+    kill -TERM "-$scan_pid" 2>/dev/null || kill -TERM "$scan_pid" 2>/dev/null || true
+    wait "$scan_pid" 2>/dev/null || true
+  fi
+  for wt in "$tmp"/wt-*; do [[ -d "$wt" ]] && git worktree remove --force "$wt" >/dev/null 2>&1; done
+  git worktree prune >/dev/null 2>&1 || true
+  rm -rf "$tmp"
+}
+# EXIT alone is not enough: a non-interactive bash killed by an UNTRAPPED signal dies
+# without running its EXIT trap, so Ctrl-C, a closed terminal or a terminated agent session
+# left the worktree registered and its directory behind. `trap - EXIT` stops a double run.
+# Nothing in-process survives SIGKILL — that case is what the sweep above is for.
+on_signal() {
+  cleanup
+  trap - EXIT
+  echo "[pre-push] interrupted — scan worktree cleaned up; push aborted." >&2
+  exit 130
+}
+trap cleanup EXIT
+trap on_signal INT TERM HUP
+
+# Run the scan as a background job and `wait`: bash defers a trap handler until the running
+# FOREGROUND command returns, so a Ctrl-C during a multi-minute scan would not be acted on
+# until the scan finished. `wait` IS interruptible, so cleanup runs at once.
+run_scan() {
+  set -m            # give the job its own process group, so cleanup can signal the tree
+  "$@" &
+  scan_pid=$!
+  set +m
+  echo "$scan_pid" > "$tmp/.scanpid"
+  local rc=0
+  wait "$scan_pid" || rc=$?
+  scan_pid=""
+  rm -f "$tmp/.scanpid"
+  return "$rc"
+}
+
+for sha in "${shas[@]}"; do
+  short="${sha:0:7}"
+  # Branches that predate the scan have no script — skip them cleanly rather than block.
+  if ! git cat-file -e "$sha:scripts/security_scan.sh" 2>/dev/null; then
+    echo "[pre-push] $short has no scripts/security_scan.sh — skipping scan for it."
+    continue
+  fi
+  echo "[pre-push] running ADR-0014 security scan on the pushed commit $short (git push --no-verify to skip)…"
+  wt="$tmp/wt-$short"
+  git worktree add --detach --quiet "$wt" "$sha"
+  # Git exports GIT_DIR & co. into hooks; left set, the scan's own git calls (bandit's
+  # target discovery, gitleaks) would read the wrong checkout.
+  scan_job() {
+    env -u GIT_DIR -u GIT_WORK_TREE -u GIT_INDEX_FILE -u GIT_PREFIX \
+      SECURITY_SCAN_OUT="$repo_root/security" bash "$wt/scripts/security_scan.sh"
+  }
+  if run_scan scan_job; then
+    echo "[pre-push] $short: security scan clean."
+  else
+    echo "[pre-push] $short: security scan reported findings — push blocked." >&2
+    echo "[pre-push] triage the reports in security/, or 'git push --no-verify' to override." >&2
+    exit 1
+  fi
+done
+echo "[pre-push] security scan clean — proceeding."
+
+# --- 2. GitHub mirror sync -----------------------------------------------------------------
+# `origin` IS the prod Space and `github` is a source mirror that only runs CI; nothing links
+# them, so the mirror fell behind prod by hand-sync on 2026-10-01 more than once. A stale mirror
+# means CI runs a SUBSET of production, which reads as a pass. This syncs the mirror's `main`
+# at the only moment git offers: when a prod deploy is about to go out.
+#
+# Two honest limitations (as in pdac-genomics-agent):
+# 1. The mirror is pushed FIRST: git has no post-push hook. If the `origin` push then fails,
+#    `github` is briefly AHEAD of prod. That self-corrects on the next deploy, and CI running a
+#    superset of production is the milder error.
+# 2. A mirror failure WARNS; it does not block. The mirror is CI; `origin` is production. It is
+#    pushed without force, so a mirror that has moved on (another lane synced it) is left alone.
+#
+# Only `main` on `origin` is mirrored. `git push hf-dev dev:main` also targets refs/heads/main on
+# a huggingface.co URL, so the dev Space is excluded by name AND by URL first — mirroring it
+# would put dev code on the mirror's `main`, where CI reads it as production.
+case "$remote_name$remote_url" in
+  "$dev_remote"*|*-dev|*-dev.git|*-dev/) exit 0 ;;
+esac
+case "$remote_name$remote_url" in
+  origin*|*huggingface.co/spaces/anne-voigt/pdac-knowledge-agent) ;;
+  *) exit 0 ;;
+esac
+
+main_sha=""
+while read -r _lref lsha rref _rsha; do
+  [[ "${rref:-}" == "refs/heads/main" ]] || continue
+  case "${lsha:-}" in *[!0]*) main_sha="$lsha" ;; esac    # all-zero = a DELETE; never mirror it
+done <<< "$push_lines"
+[[ -n "$main_sha" ]] || exit 0                            # nothing headed for main: not a deploy
+
+if ! git remote get-url "$mirror_remote" >/dev/null 2>&1; then
+  echo "[pre-push] no '$mirror_remote' remote — the GitHub mirror will fall behind this deploy." >&2
+  echo "[pre-push]   git remote add $mirror_remote https://github.com/Anne-Voigt/pdac-knowledge-agent.git" >&2
+  exit 0
+fi
+
+echo "[pre-push] mirroring ${main_sha:0:7} to '$mirror_remote' main so the mirror matches prod…"
+if SECURITY_SCAN_DONE=1 git push --quiet "$mirror_remote" "$main_sha:refs/heads/main"; then
+  echo "[pre-push] mirror in sync — proceeding with the deploy."
+else
+  echo "[pre-push] WARNING: mirror push failed (often: it already moved on). The deploy proceeds." >&2
+  echo "[pre-push] Check it after the deploy:  git fetch $mirror_remote && git log --oneline -1 $mirror_remote/main" >&2
+fi
+exit 0

scripts/hooks/pre-push-shim

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Installed as .git/hooks/pre-push by `make install-hooks`. It never needs re-installing.
+#
+# The real gate is the TRACKED scripts/hooks/pre-push. Installing a COPY freezes whatever
+# version was current on install day — in pdac-analysis-orchestrator that silently disabled a
+# gate for six days (the installed copy predated it). This shim instead runs the tracked hook
+# as it is on `dev` (the integration branch), so an edited gate is live on the next push from
+# any checkout or worktree, including one parked on an older branch. The gate LOGIC comes from
+# `dev`; the CODE it judges is still the pushed commit (the hook scans each pushed sha).
+# Falls back to this checkout's copy if `dev` has none.
+set -euo pipefail
+
+hook="$(mktemp)"
+refs="$(mktemp)"
+trap 'rm -f "$hook" "$refs"' EXIT
+if ! git show dev:scripts/hooks/pre-push > "$hook" 2>/dev/null; then
+  cp "$(git rev-parse --show-toplevel)/scripts/hooks/pre-push" "$hook"
+fi
+
+# Capture git's ref lines BEFORE backgrounding the gate. Not optional plumbing: POSIX gives an
+# asynchronous command's stdin /dev/null in a non-interactive shell, so a backgrounded gate reads
+# NO ref lines, concludes "no commits to scan" and exits 0 — a gate that passes every push while
+# checking nothing. Found in DecoupleRpy_Agent on 2026-09-23 while adding the forwarding below,
+# and only because the test asserted the gate had SCANNED rather than that the hook exited 0.
+cat > "$refs"
+
+# Run the gate as a background job and FORWARD signals to it. The shim is the process git starts,
+# so it is the one a terminating session signals — and the gate's own cleanup traps cannot help if
+# the shim dies and leaves the gate reparented to init with a scan worktree open, which is the
+# 2026-09-23 leak one layer up. (Ctrl-C alone is fine: the terminal signals the whole foreground
+# group. A plain TERM to the hook is not.) `wait` is interruptible, so the forward is immediate.
+bash "$hook" "$@" < "$refs" &          # "$@" is git's remote name + URL
+gate=$!
+forward() { kill -TERM "$gate" 2>/dev/null || true; }
+trap forward INT TERM HUP
+rc=0
+wait "$gate" || rc=$?
+exit "$rc"

scripts/security_scan.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# ADR-0014 security scan — this repo's copy of the shared definition (authored in
+# DecoupleRpy_Agent; ported from pdac-subtype-agent). Same stages everywhere, run by
+# the pre-push hook and `make security-scan`:
+#
+#   1. Dependencies   — pip-audit over the FULL resolved dependency tree (+ SBOM)
+#   2. Static         — bandit over the app code (baseline-suppressed accepted findings)
+#   3. Secrets        — gitleaks over the working tree AND full git history
+#   4. Sandbox image  — trivy over docker/sandbox.Dockerfile (skips where absent)
+#
+# Differences from the sibling copies, both deliberate:
+#
+#   - Stage 1 audits the RESOLVED tree, not the lines in requirements.txt. The
+#     siblings run `pip-audit --no-deps`, which is right for them because their
+#     requirements.txt is a compiled lockfile pinning every transitive dependency.
+#     Here it is a short hand-written list, so --no-deps would audit only the top-level
+#     pins and never see a transitive CVE — exactly the class that hit anyio on
+#     2026-09-21. So a hand-written file is first resolved with uv for the Space's own
+#     python_version, plus the gradio HF installs from README `sdk_version`; a file that
+#     is already a uv lock is audited as-is.
+#   - bandit targets are discovered, not listed: `src/` plus every root-level module,
+#     so a new top-level file cannot silently fall outside the scan.
+#
+# Not audited: HF's generic SDK base layer (datasets, huggingface-hub, …), which HF
+# installs and caches outside this repo. Anything we depend on through it that
+# matters must be floored in requirements.in (see its security-floors block).
+#
+# Design goals (unchanged from the shared definition):
+#   - No global installs, no repo mutation beyond security/ artifacts.
+#   - Graceful skip (not failure) when an optional scanner is absent; loud about it.
+#     SECURITY_SCAN_STRICT=1 turns skips into failures.
+#   - Artifacts land in $SECURITY_SCAN_OUT (default: security/). The pre-push hook
+#     scans a throwaway checkout of the PUSHED commit and points this at the real
+#     repo, so reports and the cached audit venv survive the checkout's removal.
+#
+# Exit code: non-zero if ANY enabled stage reports findings.
+# Usage:  scripts/security_scan.sh [requirements.txt]
+set -uo pipefail
+
+cd "$(dirname "$0")/.."
+REQ="${1:-requirements.txt}"
+OUT="${SECURITY_SCAN_OUT:-security}"
+mkdir -p "$OUT"
+STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+STRICT="${SECURITY_SCAN_STRICT:-0}"
+
+RC=0
+SKIPS=()
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+note()  { printf '\n\033[1m==> %s\033[0m\n' "$*"; }
+fail()  { printf '\033[31mFINDINGS:\033[0m %s\n' "$*"; RC=1; }
+skip()  { printf '\033[33mSKIP:\033[0m %s\n' "$*"; SKIPS+=("$*"); [[ "$STRICT" == "1" ]] && RC=1; return 0; }
+ok()    { printf '\033[32mOK:\033[0m %s\n' "$*"; }
+
+[[ -f "$REQ" ]] || { echo "error: '$REQ' not found" >&2; exit 2; }
+
+# README front matter is what HF builds from — read it rather than restating it.
+front() { awk '/^---$/{n++; next} n==1' README.md 2>/dev/null | sed -n "s/^$1:[[:space:]]*//p" | tr -d '"' | head -1; }
+PYV="$(front python_version)"; PYV="${PYV:-3.10}"   # HF's default when unset
+SDKV="$(front sdk_version)"
+
+# --------------------------------------------------------------------------- #
+# Stage 1a — the full dependency lock that stage 1 audits
+# --------------------------------------------------------------------------- #
+note "dependency tree (python $PYV, linux${SDKV:+, gradio $SDKV from sdk_version})"
+LOCK="$TMP/lock.txt"
+if head -3 "$REQ" | grep -q 'uv pip compile'; then
+  cp "$REQ" "$LOCK"; ok "$REQ is already a compiled lock — auditing it as-is"
+elif command -v uv >/dev/null 2>&1; then
+  { cat "$REQ"; [[ -n "$SDKV" ]] && echo "gradio[oauth,mcp]==$SDKV"; } > "$TMP/in.txt"
+  if uv pip compile "$TMP/in.txt" -o "$LOCK" --python-version "$PYV" \
+       --python-platform linux --no-header --quiet 2>"$TMP/uv.err"; then
+    ok "resolved $(grep -cE '^[A-Za-z0-9_.-]+==' "$LOCK") packages (incl. transitive)"
+  else
+    fail "could not resolve $REQ for python $PYV:"; sed 's/^/         /' "$TMP/uv.err"; LOCK=""
+  fi
+else
+  skip "dependency resolution — uv not found; transitive deps will NOT be audited"
+  cp "$REQ" "$LOCK"
+fi
+
+# --------------------------------------------------------------------------- #
+# Stage 1b — CycloneDX SBOM (of the resolved tree)
+# --------------------------------------------------------------------------- #
+note "SBOM (CycloneDX) -> $OUT/sbom.json"
+if [[ -z "$LOCK" ]]; then
+  skip "SBOM — no resolved dependency tree"
+elif command -v uvx >/dev/null 2>&1; then
+  uvx --from cyclonedx-bom cyclonedx-py requirements "$LOCK" --of JSON -o "$OUT/sbom.json" \
+    >/dev/null 2>&1 && ok "SBOM written" || fail "SBOM generation errored"
+else
+  skip "SBOM — uvx not found"
+fi
+
+# --------------------------------------------------------------------------- #
+# Stage 1c — pip-audit (known CVEs)
+# --------------------------------------------------------------------------- #
+# biodata-registry is a first-party wheel hosted on HF, not a PyPI package, so it has
+# no advisories to look up; strip it (and any URL/git line) before auditing.
+note "pip-audit (known CVEs; first-party HF-wheel dep excluded)"
+PYBIN=""
+for cand in python3.13 python3.12 python3.11 python3; do
+  command -v "$cand" >/dev/null 2>&1 || continue
+  if "$cand" -m venv "$TMP/probe-$cand" >/dev/null 2>&1; then PYBIN="$cand"; break; fi
+done
+if [[ -z "$LOCK" ]]; then
+  : # already reported as a finding above
+elif [[ -z "$PYBIN" ]]; then
+  skip "pip-audit — no Python >=3.11 with a working venv found"
+else
+  grep -vE 'git\+|biodata-registry|https?://' "$LOCK" > "$TMP/audit.txt"
+  VENV="$OUT/.audit-venv"
+  if [[ ! -x "$VENV/bin/pip-audit" ]]; then
+    echo "    setting up audit venv ($PYBIN)"
+    "$PYBIN" -m venv "$VENV" && "$VENV/bin/python" -m pip install -q --upgrade pip pip-audit
+  fi
+  "$VENV/bin/python" -m pip_audit --requirement "$TMP/audit.txt" --no-deps --disable-pip \
+    --format columns 2>/dev/null | tee "$OUT/pip-audit-$STAMP.txt"
+  AUDIT_RC=${PIPESTATUS[0]}
+  if [[ "$AUDIT_RC" -eq 0 ]]; then
+    ok "pip-audit — no known vulnerabilities in the resolved tree"
+  else
+    fail "pip-audit reported vulnerabilities (see $OUT/pip-audit-$STAMP.txt)."
+    echo "         Fix by pinning or flooring the package in requirements.txt, or record a"
+    echo "         justified acceptance in security/ACCEPTED-FINDINGS.md."
+  fi
+fi
+
+# --------------------------------------------------------------------------- #
+# Stage 2 — bandit (static analysis, baseline-suppressed)
+# --------------------------------------------------------------------------- #
+TARGETS=(); [[ -d src ]] && TARGETS+=(src)
+while IFS= read -r f; do TARGETS+=("$f"); done < <(git ls-files '*.py' 2>/dev/null | grep -v /)
+note "bandit (static analysis over: ${TARGETS[*]})"
+BASELINE="security/bandit-baseline.json"
+BANDIT=(); if command -v bandit >/dev/null 2>&1; then BANDIT=(bandit); \
+  elif command -v uvx >/dev/null 2>&1; then BANDIT=(uvx bandit); fi
+if [[ ${#BANDIT[@]} -eq 0 ]]; then
+  skip "bandit — not installed and uvx unavailable"
+elif [[ ${#TARGETS[@]} -eq 0 ]]; then
+  skip "bandit — no Python code found"
+else
+  BARGS=(-r "${TARGETS[@]}" -ll -c bandit.yaml)
+  [[ -f "$BASELINE" ]] && BARGS+=(-b "$BASELINE")
+  "${BANDIT[@]}" "${BARGS[@]}" -f json -o "$OUT/bandit-$STAMP.json" -q 2>/dev/null
+  BRC=$?
+  "${BANDIT[@]}" "${BARGS[@]}" -q 2>/dev/null | tail -n 25 || true
+  if [[ "$BRC" -eq 0 ]]; then
+    ok "bandit — no new findings beyond the accepted baseline"
+  else
+    fail "bandit reported NEW findings (see $OUT/bandit-$STAMP.json). Fix, or if"
+    echo "         intended, annotate inline (# nosec Bxxx), document it in"
+    echo "         security/ACCEPTED-FINDINGS.md, and run: make security-baseline"
+  fi
+fi
+
+# --------------------------------------------------------------------------- #
+# Stage 3 — gitleaks (secrets: working tree AND full history)
+# --------------------------------------------------------------------------- #
+note "gitleaks (secrets — working tree + full git history)"
+if command -v gitleaks >/dev/null 2>&1; then
+  gitleaks detect --config .gitleaks.toml --redact --no-banner --log-level warn \
+    --report-format json --report-path "$OUT/gitleaks-$STAMP.json"
+  if [[ $? -eq 0 ]]; then
+    ok "gitleaks — no secrets detected in tree or history"
+  else
+    fail "gitleaks detected potential secrets (see $OUT/gitleaks-$STAMP.json)."
+    echo "         If a real secret leaked, ROTATE it (HF_TOKEN / research_agent_token /"
+    echo "         ANTHROPIC_API_KEY are HF Space secrets) — removing the commit is not enough."
+  fi
+else
+  skip "gitleaks — not installed (brew install gitleaks)"
+fi
+
+# --------------------------------------------------------------------------- #
+# Stage 4 — trivy (sandbox image) — N/A unless the repo has one
+# --------------------------------------------------------------------------- #
+note "trivy (sandbox Dockerfile)"
+DOCKERFILE="docker/sandbox.Dockerfile"
+if [[ ! -f "$DOCKERFILE" ]]; then
+  skip "trivy — $DOCKERFILE not found (no sandboxed-exec image in this repo)"
+elif command -v trivy >/dev/null 2>&1; then
+  trivy config --severity HIGH,CRITICAL --exit-code 1 \
+    --format json --output "$OUT/trivy-$STAMP.json" "$DOCKERFILE"
+  [[ $? -eq 0 ]] && ok "trivy — no HIGH/CRITICAL Dockerfile misconfigurations" \
+                 || fail "trivy flagged the sandbox Dockerfile (see $OUT/trivy-$STAMP.json)."
+else
+  skip "trivy — not installed (brew install trivy)"
+fi
+
+# --------------------------------------------------------------------------- #
+# Summary
+# --------------------------------------------------------------------------- #
+note "summary"
+if [[ ${#SKIPS[@]} -gt 0 ]]; then
+  echo "Skipped stages:"; for s in "${SKIPS[@]}"; do echo "  - $s"; done
+fi
+if [[ "$RC" -eq 0 ]]; then
+  ok "security scan passed (all enabled stages clean)."
+else
+  echo "Security scan FAILED (rc=$RC) — triage above. Artifacts in $OUT/."
+fi
+exit "$RC"

security/.gitignore

@@ -0,0 +1,10 @@
+# Ephemeral scan outputs — reproducible via `make security-scan`, so not tracked.
+.audit-venv/
+bandit-2*.json
+pip-audit-*.json
+pip-audit-*.txt
+gitleaks-*.json
+trivy-*.json
+
+# CycloneDX SBOM — regenerable, carries a per-run timestamp+uuid, so not tracked.
+sbom.json

security/ACCEPTED-FINDINGS.md

@@ -0,0 +1,22 @@
+# Accepted security-scan findings — pdac-knowledge-agent
+
+Triage record for the ADR-0014 security scan (`make security-scan`, and the pre-push hook installed by
+`make install-hooks`). Every suppression would be a deliberate, justified acceptance, not an ignored finding.
+There are none.
+
+## §0 — First full run (2026-10-20, slice s1)
+
+| Stage | Result |
+|-------|--------|
+| **pip-audit** (compiled lock vs OSV/PyPI advisories) | **clean** — `requirements.txt` is a uv lock of `requirements.in` for python 3.12 / linux: 119 pinned packages, including gradio 6.28.0 from `sdk_version` and ToolUniverse 1.5.6 with every transitive dependency. The memo accepted that footprint under this scan (2026-10-13). |
+| **bandit** (static, medium+, `src/` + `access.py`, `audit.py`, `logging_sink.py`) | **clean** — 0 findings, so there is no baseline file. |
+| **gitleaks** (working tree + full git history) | **clean**. The first run flagged `src/identifiers.py:4` under `generic-api-key`: the docstring phrase "UniProt accessions, EFO/MONDO/Orphanet" matched the rule's keyword-plus-token shape. Not a secret; fixed by rewording the docstring and amending the unpushed commit, **not** by an allowlist entry. |
+| **trivy** (sandbox image) | **N/A** — no sandboxed-exec Dockerfile in this repo; the stage skips. |
+| **SBOM** (CycloneDX, of the lock) | written to `security/sbom.json` (not tracked — regenerable, as in pdac-spatial-agent). |
+
+### What a ToolUniverse bump must re-run
+
+A version bump is its own lane (ADR-0001 §7): `tooluniverse-doctor`, re-recorded fixtures with the diff reviewed,
+the schema tests, and this scan on the recompiled lock. `tests/test_no_llm_keys.py` also fails if the lock ever
+gains an LLM client library (openai, anthropic, google-genai, smolagents, litellm, langchain, vllm), so a new
+transitive of that kind is a reviewed change, not a silent one.

src/cache.py

@@ -0,0 +1,80 @@
+"""Response cache — SQLite inside the container, ephemeral, TTL per source (ADR-0001 §8).
+
+ToolUniverse's own result cache is switched off (``src.tu_client``) so this is the only one, and
+it keeps the one fact a cache usually hides: ``retrieved_at`` is when the SOURCE answered, and a
+hit returns that original time, never the time the cache served it. Only responses that passed
+their schema check are stored, so a drifted response is never replayed.
+
+The file lives in the temp dir by default (``KNOWLEDGE_CACHE_PATH`` overrides; ``:memory:`` for
+tests). Nothing here is persistent on a Space, by design: a rebuild empties it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sqlite3
+import tempfile
+import threading
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from src import config
+
+DEFAULT_PATH = str(Path(tempfile.gettempdir()) / "pdac-knowledge-cache.sqlite3")
+
+
+def cache_key(tool: str, args: dict[str, Any]) -> str:
+    canonical = json.dumps({"tool": tool, "args": args}, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+class ResponseCache:
+    def __init__(self, path: str | None = None, *, clock: Callable[[], float] = time.time):
+        self.path = path or os.environ.get("KNOWLEDGE_CACHE_PATH") or DEFAULT_PATH
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(self.path, check_same_thread=False)
+        self._db.execute(
+            "CREATE TABLE IF NOT EXISTS responses ("
+            " key TEXT PRIMARY KEY, source TEXT NOT NULL, tool TEXT NOT NULL,"
+            " data TEXT NOT NULL, retrieved_at REAL NOT NULL)"
+        )
+        self._db.commit()
+
+    def get(self, source: str, tool: str, args: dict[str, Any]) -> tuple[Any, float] | None:
+        """``(data, retrieved_at)`` for a live entry, else None. Expired entries are dropped."""
+        key = cache_key(tool, args)
+        ttl = config.source(source)["ttl_seconds"]
+        with self._lock:
+            row = self._db.execute(
+                "SELECT data, retrieved_at FROM responses WHERE key = ?", (key,)
+            ).fetchone()
+            if row is None:
+                return None
+            data, retrieved_at = row
+            if self._clock() - retrieved_at >= ttl:
+                self._db.execute("DELETE FROM responses WHERE key = ?", (key,))
+                self._db.commit()
+                return None
+        return json.loads(data), retrieved_at
+
+    def put(
+        self, source: str, tool: str, args: dict[str, Any], data: Any, retrieved_at: float
+    ) -> None:
+        key = cache_key(tool, args)
+        with self._lock:
+            self._db.execute(
+                "INSERT OR REPLACE INTO responses (key, source, tool, data, retrieved_at)"
+                " VALUES (?, ?, ?, ?, ?)",
+                (key, source, tool, json.dumps(data), retrieved_at),
+            )
+            self._db.commit()
+
+    def clear(self) -> None:
+        with self._lock:
+            self._db.execute("DELETE FROM responses")
+            self._db.commit()

src/config.py

@@ -0,0 +1,142 @@
+"""The two config files every other module reads: the tool allow-list and the source list.
+
+`config/tools_allowlist.yaml` is the approved surface (ADR-0001 §7): which ToolUniverse tools may
+ever load, and which BCC endpoint uses each. `config/sources.yaml` is the honest egress statement
+(ADR-0001 §6): the hosts each source's tools reach, the licence stamped on its rows, and its cache
+and rate settings. Both are validated here once, so a malformed file stops the Space at import
+rather than surfacing as a half-stamped row later.
+"""
+
+from __future__ import annotations
+
+import functools
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+CONFIG_DIR = ROOT / "config"
+
+# Frozen by ADR-0001 §4 (accepted 2026-10-20). s2 builds them; the names are fixed now so the
+# loaded tool set can be checked before any endpoint code exists.
+ENDPOINTS = (
+    "drugs_for_targets",
+    "trials_for_genes",
+    "annotate_genes",
+    "pathways_for_genes",
+    "targets_for_disease",
+)
+
+_TOOL_FIELDS = ("name", "source", "endpoints", "review")
+_SOURCE_FIELDS = {
+    "name": str,
+    "hosts": list,
+    "licence": str,
+    "licence_url": str,
+    "licence_checked": str,
+    "ttl_seconds": int,
+    "rate_per_second": (int, float),
+    "burst": int,
+    "timeout_seconds": (int, float),
+    "coverage_notes": list,
+    "citation": str,
+}
+
+
+class ConfigError(ValueError):
+    """A config file is malformed. Raised at import, never at request time."""
+
+
+def _read(name: str) -> dict[str, Any]:
+    with open(CONFIG_DIR / name, encoding="utf-8") as fh:
+        data = yaml.safe_load(fh)
+    if not isinstance(data, dict):
+        raise ConfigError(f"{name}: expected a mapping at the top level")
+    return data
+
+
+@functools.cache
+def sources() -> dict[str, dict[str, Any]]:
+    """Every declared source, keyed by its short id (`opentargets`, `chembl`, …)."""
+    data = _read("sources.yaml").get("sources")
+    if not isinstance(data, dict) or not data:
+        raise ConfigError("sources.yaml: `sources` must be a non-empty mapping")
+    for sid, entry in data.items():
+        for field, kind in _SOURCE_FIELDS.items():
+            if not isinstance(entry.get(field), kind):
+                raise ConfigError(f"sources.yaml: {sid}.{field} missing or not {kind}")
+        if not entry["hosts"] or not all(isinstance(h, str) and h for h in entry["hosts"]):
+            raise ConfigError(f"sources.yaml: {sid}.hosts must list at least one host")
+        if not entry["licence"].strip() or not entry["licence_url"].startswith("https://"):
+            raise ConfigError(f"sources.yaml: {sid} needs a licence and an https licence_url")
+        if entry["rate_per_second"] <= 0 or entry["burst"] < 1 or entry["ttl_seconds"] <= 0:
+            raise ConfigError(f"sources.yaml: {sid} has a non-positive rate, burst or TTL")
+    return data
+
+
+def source(source_id: str) -> dict[str, Any]:
+    try:
+        return sources()[source_id]
+    except KeyError:
+        raise ConfigError(f"unknown source {source_id!r}") from None
+
+
+@functools.cache
+def allowlist() -> dict[str, Any]:
+    """The parsed allow-list: `tooluniverse_version` plus `tools` keyed by tool name."""
+    data = _read("tools_allowlist.yaml")
+    version = data.get("tooluniverse_version")
+    if not isinstance(version, str) or not version:
+        raise ConfigError("tools_allowlist.yaml: `tooluniverse_version` must be a string")
+    tools: dict[str, dict[str, Any]] = {}
+    for entry in data.get("tools") or []:
+        if not all(field in entry for field in _TOOL_FIELDS):
+            raise ConfigError(f"tools_allowlist.yaml: entry missing {_TOOL_FIELDS}: {entry!r}")
+        name = entry["name"]
+        if name in tools:
+            raise ConfigError(f"tools_allowlist.yaml: {name} is listed twice")
+        if entry["source"] not in sources():
+            raise ConfigError(
+                f"tools_allowlist.yaml: {name} names undeclared source {entry['source']!r}"
+            )
+        unknown = set(entry["endpoints"]) - set(ENDPOINTS)
+        if unknown:
+            raise ConfigError(
+                f"tools_allowlist.yaml: {name} names unknown endpoints {sorted(unknown)}"
+            )
+        if not str(entry["review"]).strip():
+            raise ConfigError(f"tools_allowlist.yaml: {name} has no review note")
+        tools[name] = entry
+    if not tools:
+        raise ConfigError("tools_allowlist.yaml: no tools")
+    return {"tooluniverse_version": version, "tools": tools}
+
+
+def pinned_tooluniverse_version() -> str:
+    return allowlist()["tooluniverse_version"]
+
+
+def allowed_tool_names() -> frozenset[str]:
+    """Every approved tool (the memo's 28), loaded or not."""
+    return frozenset(allowlist()["tools"])
+
+
+def endpoint_tool_names() -> frozenset[str]:
+    """The tools at least one endpoint uses: exactly the set that is loaded (ADR-0001 §7)."""
+    return frozenset(name for name, t in allowlist()["tools"].items() if t["endpoints"])
+
+
+def tools_for_endpoint(endpoint: str) -> tuple[str, ...]:
+    if endpoint not in ENDPOINTS:
+        raise ConfigError(f"unknown endpoint {endpoint!r}")
+    return tuple(
+        sorted(name for name, t in allowlist()["tools"].items() if endpoint in t["endpoints"])
+    )
+
+
+def source_of(tool: str) -> str:
+    try:
+        return allowlist()["tools"][tool]["source"]
+    except KeyError:
+        raise ConfigError(f"{tool!r} is not on the allow-list") from None

src/identifiers.py

@@ -0,0 +1,154 @@
+"""What may leave the Space: identifiers only (ADR-0001 §6).
+
+Every endpoint argument passes through here BEFORE any outbound call. Allowed are HGNC symbols,
+Ensembl gene ids, UniProt accession numbers, disease ids from EFO, MONDO or Orphanet, NCT ids, and
+a disease name as a bounded string. Free text, sample ids, numbers (expression values) and file contents are
+refused as data — ``invalid_identifier`` — and more than 100 identifiers as
+``too_many_identifiers``. A refusal never echoes more than a short, truncated token back.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+MAX_IDENTIFIERS = 100
+MAX_DISEASE_NAME = 80
+_ECHO = 24  # longest token a refusal message repeats back
+
+# HGNC approved symbols start with a letter and use letters, digits and hyphens (C1orf112,
+# HLA-DRB1, NKX2-1; immunoglobulin segments such as IGHV1-69-2 carry two hyphens).
+SYMBOL = re.compile(r"^[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+){0,2}$")
+ENSEMBL_GENE = re.compile(r"^ENSG\d{11}(?:\.\d+)?$")
+# UniProt's published accession pattern.
+UNIPROT = re.compile(
+    r"^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})$"
+)
+DISEASE_ID = re.compile(r"^(?:EFO|MONDO|Orphanet)_\d{1,10}$")
+NCT = re.compile(r"^NCT\d{8}$")
+DISEASE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 ,'\-]*$")
+
+# Shapes that would pass as a symbol but are sample or run identifiers (TCGA barcodes, GEO and
+# SRA accessions, CPTAC case ids, ICGC donor/sample ids). They never leave the Space: a sample id
+# is study data, not a public identifier. Every prefix here is checked against real symbols that
+# share its letters (CPT1A, ERRFI1, DOK1, SAA1 stay valid; tests/test_identifiers.py).
+_SAMPLE_ID = re.compile(
+    r"^(?:TCGA-|GSM\d|GSE\d|SRR\d|ERR\d|DRR\d|SRS\d|SAMN\d|C3[LN]-|DO\d|SA\d)",
+    re.IGNORECASE,
+)
+_SPLIT = re.compile(r"[\s,;]+")
+
+GENE_KINDS = frozenset({"symbol", "ensembl"})
+PROTEIN_OR_GENE_KINDS = frozenset({"symbol", "ensembl", "uniprot"})
+
+
+@dataclass(frozen=True)
+class Identifier:
+    value: str
+    kind: str  # symbol | ensembl | uniprot | disease_id | disease_name | nct
+
+
+@dataclass(frozen=True)
+class Parsed:
+    """Either a list of identifiers or a refusal (``reason`` + ``message``), never both."""
+
+    identifiers: tuple[Identifier, ...] = ()
+    reason: str | None = None
+    message: str | None = None
+    duplicates_dropped: int = field(default=0)
+
+    @property
+    def ok(self) -> bool:
+        return self.reason is None
+
+
+def _echo(token: str) -> str:
+    return token if len(token) <= _ECHO else token[:_ECHO] + "…"
+
+
+def _refuse(reason: str, message: str) -> Parsed:
+    return Parsed(reason=reason, message=message)
+
+
+def _dedupe_key(token: str) -> str:
+    """Symbols compare case-insensitively (kras == KRAS); Ensembl ids exactly."""
+    return token if token.startswith("ENSG") else token.upper()
+
+
+def classify_gene_token(token: str, *, allow_uniprot: bool = False) -> str | None:
+    """The identifier kind for one gene/protein token, or None if it is not one."""
+    if _SAMPLE_ID.match(token):
+        return None
+    if ENSEMBL_GENE.match(token):
+        return "ensembl"
+    if allow_uniprot and UNIPROT.match(token):
+        return "uniprot"
+    if len(token) <= 25 and SYMBOL.match(token):
+        return "symbol"
+    return None
+
+
+def parse_gene_list(raw: str | list[str] | None, *, allow_uniprot: bool = False) -> Parsed:
+    """Split, de-duplicate (order kept) and validate a gene list."""
+    if isinstance(raw, list):
+        tokens = [str(t).strip() for t in raw]
+    else:
+        tokens = _SPLIT.split((raw or "").strip())
+    tokens = [t for t in tokens if t]
+    if not tokens:
+        return _refuse("invalid_identifier", "No gene identifiers were given.")
+    unique = {_dedupe_key(t) for t in tokens}
+    if len(unique) > MAX_IDENTIFIERS:
+        return _refuse(
+            "too_many_identifiers",
+            f"{len(unique)} identifiers given; at most {MAX_IDENTIFIERS} per call.",
+        )
+    bad = [t for t in tokens if classify_gene_token(t, allow_uniprot=allow_uniprot) is None]
+    if bad:
+        shown = ", ".join(_echo(t) for t in bad[:5])
+        more = f" and {len(bad) - 5} more" if len(bad) > 5 else ""
+        accepted = "HGNC symbols or Ensembl gene ids" + (
+            " or UniProt accessions" if allow_uniprot else ""
+        )
+        return _refuse(
+            "invalid_identifier",
+            f"Not a gene identifier: {shown}{more}. Only {accepted} are sent to external sources; "
+            "free text, sample ids and numbers are not.",
+        )
+    out: list[Identifier] = []
+    emitted: set[str] = set()
+    for t in tokens:
+        key = _dedupe_key(t)
+        if key in emitted:
+            continue
+        emitted.add(key)
+        out.append(Identifier(t, classify_gene_token(t, allow_uniprot=allow_uniprot) or "symbol"))
+    return Parsed(identifiers=tuple(out), duplicates_dropped=len(tokens) - len(out))
+
+
+def parse_disease(raw: str | None) -> Parsed:
+    """One disease: an EFO/MONDO/Orphanet id, or a bounded name."""
+    text = (raw or "").strip()
+    if not text:
+        return _refuse("invalid_identifier", "No disease was given.")
+    if DISEASE_ID.match(text):
+        return Parsed(identifiers=(Identifier(text, "disease_id"),))
+    if (
+        len(text) <= MAX_DISEASE_NAME
+        and DISEASE_NAME.match(text)
+        and any(c.isalpha() for c in text)
+        and not _SAMPLE_ID.match(text)
+    ):
+        return Parsed(identifiers=(Identifier(" ".join(text.split()), "disease_name"),))
+    return _refuse(
+        "invalid_identifier",
+        f"Not a disease name or id: {_echo(text)}. Give an EFO/MONDO id or a name of at most "
+        f"{MAX_DISEASE_NAME} characters (letters, digits, spaces, hyphens, commas, apostrophes).",
+    )
+
+
+def parse_nct(raw: str | None) -> Parsed:
+    text = (raw or "").strip().upper()
+    if NCT.match(text):
+        return Parsed(identifiers=(Identifier(text, "nct"),))
+    return _refuse("invalid_identifier", f"Not an NCT id: {_echo(text)}.")

src/payloads.py

@@ -0,0 +1,151 @@
+"""Payload assembly — every answer this Space returns goes through here.
+
+The contract (ADR-0001 §5, accepted 2026-10-20), on top of the family invariants:
+
+- Every payload is a dict with ``status`` in {"ok", "refused", "error", "denied"} plus a
+  human-readable ``reason`` on every non-ok status. Refusals are answers, never exceptions.
+- Every payload except a denial carries a ``run_id`` (the gate mints none for a caller it
+  turned away).
+- Every ``ok`` payload carries ``kind: "annotation"`` and **no** ``hierarchy`` or
+  ``n_for_inference``. This is the deliberate break from the data specialists: a row count here
+  is not a sample size, and nothing downstream may render it as one.
+- Every row carries a complete ``provenance`` block (:mod:`src.provenance`); :func:`ok` refuses to
+  build a payload around a row that does not.
+- ``coverage_notes`` and ``attribution`` come from config for every source the payload used, and
+  the deterministic ``narrative`` says "according to <source> (queried <date>)".
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import secrets
+from collections.abc import Iterable
+from typing import Any
+
+from src import config
+from src.provenance import missing_fields
+
+STATUSES = ("ok", "refused", "error", "denied")
+SOURCE_ERROR_REASONS = ("source_unavailable", "rate_limited", "upstream_schema_drift")
+KIND = "annotation"
+DISCLAIMER = (
+    "External annotation, not analysis: these rows are what the named public sources say, "
+    "as of the query date on each row. Nothing here was computed from a dataset, and no "
+    "statistic was run."
+)
+
+
+def mint_run_id() -> str:
+    """A sortable, collision-resistant run id (sibling-agent format)."""
+    stamp = datetime.datetime.now(datetime.UTC).strftime("%Y%m%d_%H%M%S")
+    return f"{stamp}_{secrets.randbelow(10**6):06d}"
+
+
+def source_error(source: str, reason: str, detail: str) -> dict[str, str]:
+    if reason not in SOURCE_ERROR_REASONS:
+        raise ValueError(f"source error reason must be one of {SOURCE_ERROR_REASONS}")
+    return {"source": source, "reason": reason, "detail": detail}
+
+
+def _attribution(source_ids: Iterable[str]) -> list[dict[str, str]]:
+    out = []
+    for sid in sorted(set(source_ids)):
+        src = config.source(sid)
+        out.append(
+            {
+                "source": sid,
+                "name": src["name"],
+                "citation": src["citation"],
+                "licence": src["licence"],
+                "licence_url": src["licence_url"],
+            }
+        )
+    return out
+
+
+def _coverage_notes(source_ids: Iterable[str]) -> list[dict[str, str]]:
+    return [
+        {"source": sid, "note": note}
+        for sid in sorted(set(source_ids))
+        for note in config.source(sid)["coverage_notes"]
+    ]
+
+
+def ok(
+    endpoint: str,
+    *,
+    query: dict[str, Any],
+    rows: list[dict[str, Any]],
+    sources_used: Iterable[str],
+    narrative: str,
+    unresolved: Iterable[dict[str, str]] = (),
+    source_errors: Iterable[dict[str, str]] = (),
+    run_id: str | None = None,
+    **extra: Any,
+) -> dict[str, Any]:
+    """An ok payload. Raises ValueError (a programming error) on an unstamped row."""
+    for i, row in enumerate(rows):
+        gaps = missing_fields(row)
+        if gaps:
+            raise ValueError(f"row {i} is missing provenance fields {gaps}")
+    if not narrative.strip():
+        raise ValueError("an ok payload needs its deterministic narrative")
+    used = list(sources_used)
+    forbidden = {"hierarchy", "n_for_inference"} & set(extra)
+    if forbidden:
+        raise ValueError(f"annotation payloads never carry {sorted(forbidden)}")
+    payload: dict[str, Any] = {
+        "status": "ok",
+        "run_id": run_id or mint_run_id(),
+        "kind": KIND,
+        "endpoint": endpoint,
+        "query": query,
+        "rows": rows,
+        "unresolved": list(unresolved),
+        "source_errors": list(source_errors),
+        "coverage_notes": _coverage_notes(used),
+        "attribution": _attribution(used),
+        "narrative": narrative,
+        "disclaimer": DISCLAIMER,
+    }
+    payload.update(extra)
+    return payload
+
+
+def refused(endpoint: str, reason: str, message: str, *, run_id: str | None = None) -> dict:
+    return {
+        "status": "refused",
+        "run_id": run_id or mint_run_id(),
+        "endpoint": endpoint,
+        "reason": reason,
+        "message": message,
+    }
+
+
+def error(
+    endpoint: str,
+    reason: str,
+    message: str,
+    *,
+    source_errors: Iterable[dict[str, str]] = (),
+    run_id: str | None = None,
+) -> dict:
+    return {
+        "status": "error",
+        "run_id": run_id or mint_run_id(),
+        "endpoint": endpoint,
+        "reason": reason,
+        "message": message,
+        "source_errors": list(source_errors),
+    }
+
+
+def denied(message: str) -> dict:
+    return {"status": "denied", "reason": "access_denied", "message": message}
+
+
+def to_json(payload: dict[str, Any]) -> str:
+    if payload.get("status") not in STATUSES:
+        raise ValueError(f"unknown status {payload.get('status')!r}")
+    return json.dumps(payload, ensure_ascii=False)

src/provenance.py

@@ -0,0 +1,74 @@
+"""Provenance on every row (ADR-0001 §5).
+
+ToolUniverse returns each source's raw response with no provenance or licence (Phase 0 governance
+finding), so every row this Space returns is stamped here with the ten fields below. A row that is
+missing any of them is a bug, and :func:`src.payloads.ok` refuses to build a payload around it.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+from src import config
+
+PROVENANCE_FIELDS = (
+    "source",  # short source id from config/sources.yaml (opentargets, chembl, …)
+    "source_tool",  # the ToolUniverse tool name that produced the row
+    "tooluniverse_version",  # the pinned version that ran it
+    "query",  # the arguments actually sent
+    "source_ref",  # the source's own id for the row (ChEMBL, NCT, UniProt, Reactome, Ensembl)
+    "source_url",  # where a reader can look the row up
+    "retrieved_at",  # when the SOURCE answered — survives a cache hit unchanged
+    "cache",  # "hit" or "miss"
+    "licence",
+    "licence_url",
+)
+
+CACHE_STATES = ("hit", "miss")
+
+
+def iso_utc(epoch_seconds: float) -> str:
+    """``2026-10-20T15:37:49Z`` — second resolution, always UTC."""
+    moment = datetime.datetime.fromtimestamp(epoch_seconds, tz=datetime.UTC)
+    return moment.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def stamp(
+    row: dict[str, Any],
+    *,
+    source: str,
+    source_tool: str,
+    tooluniverse_version: str,
+    query: dict[str, Any],
+    source_ref: str,
+    source_url: str,
+    retrieved_at: float,
+    cache: str,
+) -> dict[str, Any]:
+    """A copy of ``row`` carrying a complete ``provenance`` block. Licence comes from config."""
+    if cache not in CACHE_STATES:
+        raise ValueError(f"cache must be one of {CACHE_STATES}, not {cache!r}")
+    src = config.source(source)
+    stamped = dict(row)
+    stamped["provenance"] = {
+        "source": source,
+        "source_tool": source_tool,
+        "tooluniverse_version": tooluniverse_version,
+        "query": dict(query),
+        "source_ref": source_ref,
+        "source_url": source_url,
+        "retrieved_at": iso_utc(retrieved_at),
+        "cache": cache,
+        "licence": src["licence"],
+        "licence_url": src["licence_url"],
+    }
+    return stamped
+
+
+def missing_fields(row: dict[str, Any]) -> list[str]:
+    """Provenance fields absent or empty on ``row`` (empty list = complete)."""
+    prov = row.get("provenance")
+    if not isinstance(prov, dict):
+        return list(PROVENANCE_FIELDS)
+    return [f for f in PROVENANCE_FIELDS if prov.get(f) in (None, "", {}, [])]

src/ratelimit.py

@@ -0,0 +1,78 @@
+"""Per-source rate limits — a token bucket per source, settings from config/sources.yaml.
+
+A caller that would have to wait longer than its budget does not wait: it gets ``False`` and the
+client turns that into a ``rate_limited`` source error. A limit must never become a retry loop
+that outlasts the orchestrator's call limit (ADR-0001 §8).
+
+Tokens are reserved under the lock and slept for outside it, so concurrent callers queue in
+order without holding the lock while they sleep.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+
+from src import config
+
+
+class TokenBucket:
+    def __init__(
+        self,
+        rate_per_second: float,
+        burst: int,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+    ):
+        if rate_per_second <= 0 or burst < 1:
+            raise ValueError("rate must be positive and burst at least 1")
+        self.rate = float(rate_per_second)
+        self.burst = int(burst)
+        self._clock = clock
+        self._sleep = sleep
+        self._tokens = float(burst)
+        self._last = clock()
+        self._lock = threading.Lock()
+
+    def acquire(self, max_wait: float) -> bool:
+        """Take one token, waiting at most ``max_wait`` seconds. False if that is not enough."""
+        with self._lock:
+            now = self._clock()
+            self._tokens = min(self.burst, self._tokens + (now - self._last) * self.rate)
+            self._last = now
+            wait = 0.0 if self._tokens >= 1 else (1 - self._tokens) / self.rate
+            if wait > max_wait:
+                return False
+            self._tokens -= 1  # reserve now; may go negative while the caller sleeps
+        if wait > 0:
+            self._sleep(wait)
+        return True
+
+
+class RateLimiters:
+    """One bucket per declared source, built lazily from config."""
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+    ):
+        self._clock = clock
+        self._sleep = sleep
+        self._buckets: dict[str, TokenBucket] = {}
+        self._lock = threading.Lock()
+
+    def bucket(self, source: str) -> TokenBucket:
+        with self._lock:
+            if source not in self._buckets:
+                cfg = config.source(source)
+                self._buckets[source] = TokenBucket(
+                    cfg["rate_per_second"], cfg["burst"], clock=self._clock, sleep=self._sleep
+                )
+            return self._buckets[source]
+
+    def acquire(self, source: str, max_wait: float) -> bool:
+        return self.bucket(source).acquire(max_wait)

src/schemas/OpenTargets_get_associated_drugs_by_target_ensemblID.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s1) from the Phase 0 response recorded through ToolUniverse 1.5.6 on 2026-10-12 (TNFRSF10B). Only the fields drugs_for_targets reads are required. A null target means the id is unknown to Open Targets: an unresolved input, not drift. `target` is object-or-null in one schema rather than a oneOf, so a drift error names the field that moved instead of 'not valid under any of the given schemas' (JSON Schema's required/properties only apply to objects).",
+  "type": "object",
+  "required": [
+    "target"
+  ],
+  "properties": {
+    "target": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "required": [
+        "id",
+        "approvedSymbol",
+        "drugAndClinicalCandidates"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^ENSG\\d{11}$"
+        },
+        "approvedSymbol": {
+          "type": "string",
+          "minLength": 1
+        },
+        "drugAndClinicalCandidates": {
+          "type": "object",
+          "required": [
+            "count",
+            "rows"
+          ],
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "rows": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "drug",
+                  "maxClinicalStage"
+                ],
+                "properties": {
+                  "drug": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "name"
+                    ],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "pattern": "^CHEMBL\\d+$"
+                      },
+                      "name": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  },
+                  "maxClinicalStage": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

src/schemas/__init__.py

@@ -0,0 +1,65 @@
+"""Pinned output schemas — the check that stands between a source's response and a row.
+
+ADR-0001 §5: each source's raw response is validated against a pinned schema BEFORE any row is
+built, and a mismatch is ``upstream_schema_drift`` for that source. Rows are never guessed from a
+partial match. Phase 0 is why: while the test ran, Open Targets renamed ``knownDrugs`` to
+``drugAndClinicalCandidates`` and a hand-written client broke. A schema here pins the fields the
+row builders READ, not ToolUniverse's whole declared ``return_schema``, so a harmless addition
+upstream passes and a rename of something we rely on fails loudly.
+
+One file per tool: ``<tool name>.schema.json`` (JSON Schema draft 2020-12), describing the tool's
+``data`` after ToolUniverse's ``{"status": "success", "data": …}`` envelope is removed.
+
+**No schema means no rows.** A loaded tool without a pinned schema is refused the same way as a
+drifted one. That keeps the contract fail-closed while s2 is still recording fixtures and
+pinning the remaining schemas.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import best_match
+
+SCHEMA_DIR = Path(__file__).resolve().parent
+
+
+class SchemaDrift(ValueError):
+    """The response does not match the pinned schema (or there is none to check against)."""
+
+    def __init__(self, tool: str, detail: str):
+        super().__init__(f"{tool}: {detail}")
+        self.tool = tool
+        self.detail = detail
+
+
+@functools.cache
+def _validator(tool: str) -> Draft202012Validator | None:
+    path = SCHEMA_DIR / f"{tool}.schema.json"
+    if not path.is_file():
+        return None
+    schema = json.loads(path.read_text(encoding="utf-8"))
+    Draft202012Validator.check_schema(schema)
+    return Draft202012Validator(schema)
+
+
+def pinned_tools() -> frozenset[str]:
+    """Tools that have a pinned schema file."""
+    return frozenset(p.name.removesuffix(".schema.json") for p in SCHEMA_DIR.glob("*.schema.json"))
+
+
+def validate(tool: str, data: Any) -> None:
+    """Raise :class:`SchemaDrift` unless ``data`` matches the tool's pinned schema."""
+    validator = _validator(tool)
+    if validator is None:
+        raise SchemaDrift(tool, "no pinned schema for this tool, so no rows can be built from it")
+    error = best_match(validator.iter_errors(data))
+    if error is not None:
+        where = "/".join(str(p) for p in error.absolute_path) or "(root)"
+        raise SchemaDrift(
+            tool, f"response does not match the pinned schema at {where}: {error.message}"
+        )

src/tu_client.py

@@ -0,0 +1,335 @@
+"""The governed ToolUniverse client — the ONLY module that imports ``tooluniverse``.
+
+ADR-0001 §7, enforced in code rather than by convention:
+
+- **Allow-list by construction.** ToolUniverse is built with ``keep_default_tools=False`` and
+  ``load_workspace=False``, then ``load_tools(include_tools=<the endpoints' set>)``, and startup
+  is REFUSED unless the loaded set equals that set exactly. With these arguments 1.5.6 loads the
+  named tools and nothing else: no special tools, no tool finder, no agentic tools, no remote MCP
+  servers (measured 2026-10-20, with outbound sockets blocked, so loading opens no connection).
+- **No workspace.** ``load_workspace=False`` is not optional. With a workspace directory present
+  (``TOOLUNIVERSE_HOME``, or ``./.tooluniverse``), 1.5.6's constructor writes a default
+  ``profile.yaml`` into it and applies it, which loads ALL 2,691 tools before ``load_tools`` runs;
+  it also reads that workspace's ``.env`` and ``~/.tooluniverse/.env`` into the environment, which
+  could bring a model key in after the check below. Found by this repo's own tests on 2026-10-20,
+  when an earlier draft pointed ``TOOLUNIVERSE_HOME`` at an empty temp dir.
+- **No model provider keys.** ToolUniverse's agentic tools and tool finder can reach OpenAI, Azure
+  OpenAI, Gemini, OpenRouter or a vLLM server when keys are set. None of those tools can load
+  here, and startup still refuses if any key is present: the Space makes no model call
+  (ADR-0001 §2). ``HF_TOKEN`` is allowed — the machine gate needs it — and in 1.5.6 only
+  Hugging Face inference and embedding tools read it, none of which is on the allow-list.
+- **Exactly one cache.** ToolUniverse's own result cache is disabled through its environment
+  switches and every call passes ``use_cache=False``; :mod:`src.cache` is the only cache, because
+  it is the one that keeps ``retrieved_at`` honest.
+- **Pinned.** The installed version must equal ``config/tools_allowlist.yaml``'s
+  ``tooluniverse_version``. A bump is its own lane (doctor, re-recorded fixtures, schema tests,
+  security scan) and never changes an endpoint's name or payload shape.
+
+:class:`ToolClient` is what the endpoints call. It returns a :class:`SourceResult` or raises a
+:class:`SourceError` whose ``reason`` is one of the three payload source-error reasons, so a
+timeout, a limit or a drifted response is always structured, never a guess.
+"""
+
+from __future__ import annotations
+
+import ast
+import concurrent.futures
+import inspect
+import os
+import re
+import threading
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from src import config, schemas
+from src.cache import ResponseCache
+from src.ratelimit import RateLimiters
+
+# Every variable through which ToolUniverse 1.5.6 (or a library it can load) reaches a model.
+LLM_KEY_VARS = (
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "AZURE_OPENAI_API_KEY",
+    "AZURE_OPENAI_ENDPOINT",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+    "OPENROUTER_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "VLLM_SERVER_URL",
+)
+
+# Tool types that must never load, whatever the allow-list says: LLM-backed agents, the tool
+# finders (they can call a model or download an embedding index), remote MCP auto-loaders and
+# web-search backends. A tool whose config names `required_api_keys` is key-gated and refused too.
+FORBIDDEN_TOOL_TYPES = frozenset(
+    {
+        "AgenticTool",
+        "SmolAgentTool",
+        "MCPAutoLoaderTool",
+        "MCPClientTool",
+        "ToolFinderEmbedding",
+        "ToolFinderLLM",
+        "ToolFinderKeyword",
+        "ToolFinderJev",
+        "WebSearchTool",
+        "WebAPIDocumentationSearchTool",
+    }
+)
+
+# ToolUniverse's own switches: its result cache off. The workspace and profile variables are
+# REMOVED rather than set, because any workspace widens what loads (see the module docstring).
+_TU_ENV = {
+    "TOOLUNIVERSE_CACHE_ENABLED": "false",
+    "TOOLUNIVERSE_CACHE_PERSIST": "false",
+    "TOOLUNIVERSE_QUIET": "1",
+}
+_TU_ENV_REMOVED = ("TOOLUNIVERSE_PROFILE", "TOOLUNIVERSE_HOME")
+
+_HOST = re.compile(r"https?://([A-Za-z0-9.-]+)")
+_build_lock = threading.Lock()
+
+
+class StartupRefused(RuntimeError):
+    """The Space must not start: a key is set, the version drifted, or the tool set is wrong."""
+
+
+class SourceError(Exception):
+    """A structured failure from one source call (``reason`` ∈ payload SOURCE_ERROR_REASONS)."""
+
+    def __init__(self, source: str, reason: str, detail: str):
+        super().__init__(f"{source}: {reason}: {detail}")
+        self.source = source
+        self.reason = reason
+        self.detail = detail
+
+    def as_payload(self) -> dict[str, str]:
+        return {"source": self.source, "reason": self.reason, "detail": self.detail}
+
+
+@dataclass(frozen=True)
+class SourceResult:
+    tool: str
+    source: str
+    args: dict[str, Any]
+    data: Any
+    retrieved_at: float  # epoch seconds when the SOURCE answered
+    cache: str  # "hit" | "miss"
+    tooluniverse_version: str
+
+
+def assert_no_llm_keys(environ: Mapping[str, str] | None = None) -> None:
+    env = os.environ if environ is None else environ
+    present = [var for var in LLM_KEY_VARS if (env.get(var) or "").strip()]
+    if present:
+        raise StartupRefused(
+            f"Model-provider settings are present ({', '.join(present)}). This Space makes no "
+            "model call and must run without them (ADR-0001 §2); remove them from the Space's "
+            "secrets and variables."
+        )
+
+
+def configure_tooluniverse_env() -> None:
+    """Set ToolUniverse's environment before an instance is built (idempotent)."""
+    for var, value in _TU_ENV.items():
+        os.environ[var] = value
+    for var in _TU_ENV_REMOVED:
+        os.environ.pop(var, None)
+
+
+def installed_tooluniverse_version() -> str:
+    import tooluniverse
+
+    return str(getattr(tooluniverse, "__version__", ""))
+
+
+def build_tooluniverse(include: frozenset[str] | None = None):
+    """A ToolUniverse holding exactly ``include`` (default: the endpoints' set), or refuse."""
+    include = config.endpoint_tool_names() if include is None else include
+    if not include <= config.allowed_tool_names():
+        raise StartupRefused(
+            f"not on the allow-list: {sorted(include - config.allowed_tool_names())}"
+        )
+    assert_no_llm_keys()
+    configure_tooluniverse_env()
+    version = installed_tooluniverse_version()
+    if version != config.pinned_tooluniverse_version():
+        raise StartupRefused(
+            f"ToolUniverse {version!r} is installed; config pins "
+            f"{config.pinned_tooluniverse_version()!r}. A version bump is its own reviewed lane."
+        )
+    from tooluniverse import ToolUniverse
+
+    tu = ToolUniverse(keep_default_tools=False, load_workspace=False)
+    if tu.all_tool_dict:
+        raise StartupRefused(
+            f"ToolUniverse loaded {len(tu.all_tool_dict)} tools before the allow-list was applied"
+        )
+    tu.load_tools(include_tools=sorted(include), quiet=True)
+    assert_no_llm_keys()  # again: nothing during construction may have brought one in
+    loaded = frozenset(tu.all_tool_dict)
+    if loaded != include:
+        raise StartupRefused(
+            f"loaded tool set differs from the allow-listed set: extra {sorted(loaded - include)}, "
+            f"missing {sorted(include - loaded)}"
+        )
+    unsafe = sorted(
+        name
+        for name, cfg in tu.all_tool_dict.items()
+        if cfg.get("type") in FORBIDDEN_TOOL_TYPES or cfg.get("required_api_keys")
+    )
+    if unsafe:
+        raise StartupRefused(f"agentic, finder, remote-MCP, web-search or key-gated: {unsafe}")
+    cache_manager = getattr(tu, "cache_manager", None)
+    if cache_manager is not None and getattr(cache_manager, "enabled", False):
+        raise StartupRefused("ToolUniverse's own result cache is enabled; it must be off")
+    return tu
+
+
+def tool_hosts(tu, tool: str) -> set[str]:
+    """Every host a loaded tool can reach: URLs in its config plus its class's code.
+
+    Read offline from the installed package: the tool's config dict, the source of its class and
+    ToolUniverse base classes, and any module-level URL constant those classes name (HGNC keeps
+    its base URL in one). So the egress statement in config/sources.yaml can be checked without a
+    network call (tests/test_sources_hosts.py).
+    """
+    from tooluniverse.tool_registry import get_tool_class_lazy
+
+    cfg = tu.all_tool_dict[tool]
+    hosts = set(_HOST.findall(repr(cfg)))
+    # The lazy lookup imports the class's module (offline); the plain registry is empty until a
+    # tool instance has been created, which would make this check silently find nothing.
+    cls = get_tool_class_lazy(cfg["type"])
+    if cls is None:
+        raise StartupRefused(f"{tool}: tool type {cfg['type']!r} has no class to inspect")
+    for klass in inspect.getmro(cls):
+        if not klass.__module__.startswith("tooluniverse"):
+            continue
+        try:
+            class_source = inspect.getsource(klass)
+            module_source = inspect.getsource(inspect.getmodule(klass))
+        except (OSError, TypeError):
+            continue
+        hosts.update(_HOST.findall(class_source))
+        for name, value in _module_url_constants(module_source).items():
+            if re.search(rf"\b{re.escape(name)}\b", class_source):
+                hosts.update(_HOST.findall(value))
+    return hosts
+
+
+def _module_url_constants(module_source: str) -> dict[str, str]:
+    """Top-level ``NAME = "https://…"`` assignments in a module."""
+    found: dict[str, str] = {}
+    for node in ast.parse(module_source).body:
+        if isinstance(node, ast.Assign) and isinstance(node.value, ast.Constant):
+            value = node.value.value
+            if isinstance(value, str) and _HOST.search(value):
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        found[target.id] = value
+    return found
+
+
+def _unwrap(tool: str, source: str, raw: Any) -> Any:
+    """ToolUniverse's envelope → the source's data, or a structured error."""
+    if raw is None:
+        raise SourceError(source, "source_unavailable", f"{tool} returned nothing")
+    if isinstance(raw, dict):
+        status = raw.get("status")
+        if status == "success" and "data" in raw:
+            return raw["data"]
+        if status == "error" or ("error" in raw and raw.get("error")):
+            detail = str(raw.get("error") or raw.get("message") or "error")[:200]
+            raise SourceError(source, "source_unavailable", f"{tool}: {detail}")
+    if isinstance(raw, str) and raw.lower().startswith("error"):
+        raise SourceError(source, "source_unavailable", f"{tool}: {raw[:200]}")
+    return raw
+
+
+class ToolClient:
+    """Cache → rate limit → call with a deadline → schema check → cache.
+
+    ``runner(tool, args)`` performs the actual call. By default it is ToolUniverse's
+    ``run_one_function`` on a lazily built, allow-listed instance; tests inject a fake runner
+    with synthetic or recorded responses, so the suite never reaches the network.
+    """
+
+    def __init__(
+        self,
+        *,
+        runner: Callable[[str, dict[str, Any]], Any] | None = None,
+        cache: ResponseCache | None = None,
+        limiters: RateLimiters | None = None,
+        clock: Callable[[], float] = time.time,
+        tooluniverse_version: str | None = None,
+    ):
+        self._runner = runner
+        self._tu = None
+        self.cache = cache if cache is not None else ResponseCache()
+        self.limiters = limiters if limiters is not None else RateLimiters()
+        self._clock = clock
+        self._version = tooluniverse_version
+        self._pool = concurrent.futures.ThreadPoolExecutor(
+            max_workers=8, thread_name_prefix="tu-call"
+        )
+
+    @property
+    def tooluniverse_version(self) -> str:
+        if self._version is None:
+            self._version = installed_tooluniverse_version()
+        return self._version
+
+    def _default_runner(self, tool: str, args: dict[str, Any]) -> Any:
+        with _build_lock:
+            if self._tu is None:
+                self._tu = build_tooluniverse()
+        return self._tu.run_one_function({"name": tool, "arguments": args}, use_cache=False)
+
+    def call(self, tool: str, args: dict[str, Any], *, max_wait: float = 10.0) -> SourceResult:
+        if tool not in config.endpoint_tool_names():
+            # A programming error, not a user input: endpoints only ever name loaded tools.
+            raise ValueError(f"{tool!r} is not an endpoint tool")
+        source = config.source_of(tool)
+        cfg = config.source(source)
+
+        hit = self.cache.get(source, tool, args)
+        if hit is not None:
+            data, retrieved_at = hit
+            return SourceResult(
+                tool, source, dict(args), data, retrieved_at, "hit", self.tooluniverse_version
+            )
+
+        if not self.limiters.acquire(source, max_wait):
+            raise SourceError(
+                source, "rate_limited", f"{cfg['name']} limit of {cfg['rate_per_second']}/s reached"
+            )
+
+        runner = self._runner or self._default_runner
+        future = self._pool.submit(runner, tool, dict(args))
+        try:
+            raw = future.result(timeout=cfg["timeout_seconds"])
+        except concurrent.futures.TimeoutError:
+            future.cancel()
+            raise SourceError(
+                source,
+                "source_unavailable",
+                f"{cfg['name']} did not answer within {cfg['timeout_seconds']} s",
+            ) from None
+        except SourceError:
+            raise
+        except Exception as e:
+            raise SourceError(source, "source_unavailable", f"{tool}: {type(e).__name__}") from e
+        retrieved_at = self._clock()
+
+        data = _unwrap(tool, source, raw)
+        try:
+            schemas.validate(tool, data)
+        except schemas.SchemaDrift as drift:
+            raise SourceError(source, "upstream_schema_drift", drift.detail) from drift
+
+        self.cache.put(source, tool, args, data, retrieved_at)
+        return SourceResult(
+            tool, source, dict(args), data, retrieved_at, "miss", self.tooluniverse_version
+        )

tests/conftest.py

@@ -0,0 +1,103 @@
+"""Hermetic test setup — outbound network is BLOCKED before collection.
+
+The block is enforced, not asserted (the genomics/spatial pattern): the socket patch is in place
+at conftest import time, before any test module loads, so a test that would reach Open Targets,
+UniProt or any other source fails loudly instead of quietly depending on the network. Responses
+come from recorded Phase 0 fixtures (``tests/fixtures/``) or synthetic dicts, through
+``ToolClient(runner=...)``.
+
+Model-provider variables are removed for the session as well: this Space must start without them
+(ADR-0001 §2), and a developer shell that happens to export ``ANTHROPIC_API_KEY`` must not turn
+every startup test into a refusal. Tests that need one set it themselves.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+from pathlib import Path
+
+import pytest
+
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.pop("ACCESS_CONTROL", None)  # gate dark-launched off unless a test sets it
+
+from src.tu_client import LLM_KEY_VARS
+
+for _var in LLM_KEY_VARS:
+    os.environ.pop(_var, None)
+
+_real_connect = socket.socket.connect
+OUTBOUND_ATTEMPTS: list = []
+
+
+def _blocked_connect(self, address):
+    host = address[0] if isinstance(address, tuple) else address
+    # AF_UNIX (a filesystem path) is local IPC.
+    if isinstance(address, (str, bytes)) or str(host) in ("127.0.0.1", "::1", "localhost"):
+        return _real_connect(self, address)
+    OUTBOUND_ATTEMPTS.append(address)
+    raise RuntimeError(f"Outbound network blocked in tests (attempted {address!r})")
+
+
+socket.socket.connect = _blocked_connect  # type: ignore[method-assign]
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+
+
+def load_fixture(relpath: str) -> dict:
+    return json.loads((FIXTURES / relpath).read_text(encoding="utf-8"))
+
+
+class FakeClock:
+    """A clock that only moves when told to; ``sleep`` advances it."""
+
+    def __init__(self, start: float = 1_760_000_000.0):
+        self.now = start
+        self.sleeps: list[float] = []
+
+    def __call__(self) -> float:
+        return self.now
+
+    def sleep(self, seconds: float) -> None:
+        self.sleeps.append(seconds)
+        self.now += seconds
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+class FakeRunner:
+    """Stands in for ToolUniverse's ``run_one_function``: canned responses, every call recorded."""
+
+    def __init__(self, responses: dict[str, object] | None = None):
+        self.responses = dict(responses or {})
+        self.calls: list[tuple[str, dict]] = []
+
+    def __call__(self, tool: str, args: dict):
+        self.calls.append((tool, dict(args)))
+        response = self.responses[tool]
+        if isinstance(response, BaseException):
+            raise response
+        if callable(response):
+            return response(args)
+        return response
+
+
+@pytest.fixture()
+def clock() -> FakeClock:
+    return FakeClock()
+
+
+@pytest.fixture()
+def memory_cache(clock):
+    from src.cache import ResponseCache
+
+    return ResponseCache(":memory:", clock=clock)
+
+
+@pytest.fixture()
+def tnfrsf10b_response() -> dict:
+    """The real Open Targets response for DR5, recorded through ToolUniverse 1.5.6 in Phase 0."""
+    return load_fixture("phase0/opentargets_drugs_TNFRSF10B.json")["response"]

tests/fixtures/phase0/opentargets_drugs_TNFRSF10B.json

@@ -0,0 +1,162 @@
+{
+ "_recorded": {
+  "tool": "OpenTargets_get_associated_drugs_by_target_ensemblID",
+  "arguments": {
+   "ensemblId": "ENSG00000120889",
+   "size": 100
+  },
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-12",
+  "origin": "Phase 0 evaluation run (run2_results.json, Q7_tu); each row's diseases list trimmed to two entries",
+  "licence": "Open Targets Platform, CC0 1.0"
+ },
+ "response": {
+  "status": "success",
+  "data": {
+   "target": {
+    "id": "ENSG00000120889",
+    "approvedSymbol": "TNFRSF10B",
+    "drugAndClinicalCandidates": {
+     "count": 7,
+     "rows": [
+      {
+       "drug": {
+        "id": "CHEMBL2109247",
+        "name": "LBY-135",
+        "maximumClinicalStage": "PHASE_1"
+       },
+       "maxClinicalStage": "PHASE_1",
+       "diseases": []
+      },
+      {
+       "drug": {
+        "id": "CHEMBL2107846",
+        "name": "DULANERMIN",
+        "maximumClinicalStage": "PHASE_2"
+       },
+       "maxClinicalStage": "PHASE_2",
+       "diseases": [
+        {
+         "disease": {
+          "id": "MONDO_0056806",
+          "name": "non-small cell squamous lung carcinoma"
+         }
+        },
+        {
+         "disease": {
+          "id": "MONDO_0005233",
+          "name": "non-small cell lung carcinoma"
+         }
+        }
+       ]
+      },
+      {
+       "drug": {
+        "id": "CHEMBL1743008",
+        "name": "DROZITUMAB",
+        "maximumClinicalStage": "PHASE_2"
+       },
+       "maxClinicalStage": "PHASE_2",
+       "diseases": [
+        {
+         "disease": {
+          "id": "MONDO_0005233",
+          "name": "non-small cell lung carcinoma"
+         }
+        },
+        {
+         "disease": {
+          "id": "MONDO_0018906",
+          "name": "follicular lymphoma"
+         }
+        }
+       ]
+      },
+      {
+       "drug": {
+        "id": "CHEMBL1743080",
+        "name": "TIGATUZUMAB",
+        "maximumClinicalStage": "PHASE_2"
+       },
+       "maxClinicalStage": "PHASE_2",
+       "diseases": [
+        {
+         "disease": {
+          "id": "MONDO_0007254",
+          "name": "breast cancer"
+         }
+        },
+        {
+         "disease": {
+          "id": "MONDO_0005575",
+          "name": "colorectal cancer"
+         }
+        }
+       ]
+      },
+      {
+       "drug": {
+        "id": "CHEMBL2109248",
+        "name": "APOMAB",
+        "maximumClinicalStage": "PHASE_1"
+       },
+       "maxClinicalStage": "PHASE_1",
+       "diseases": [
+        {
+         "disease": {
+          "id": "MONDO_0005575",
+          "name": "colorectal cancer"
+         }
+        }
+       ]
+      },
+      {
+       "drug": {
+        "id": "CHEMBL1743036",
+        "name": "LEXATUMUMAB",
+        "maximumClinicalStage": "PHASE_2"
+       },
+       "maxClinicalStage": "PHASE_2",
+       "diseases": [
+        {
+         "disease": {
+          "id": "MONDO_0005072",
+          "name": "neuroblastoma"
+         }
+        },
+        {
+         "disease": {
+          "id": "MONDO_0012817",
+          "name": "Ewing sarcoma"
+         }
+        }
+       ]
+      },
+      {
+       "drug": {
+        "id": "CHEMBL1743003",
+        "name": "CONATUMUMAB",
+        "maximumClinicalStage": "PHASE_2"
+       },
+       "maxClinicalStage": "PHASE_2",
+       "diseases": [
+        {
+         "disease": {
+          "id": "MONDO_0005575",
+          "name": "colorectal cancer"
+         }
+        },
+        {
+         "disease": {
+          "id": "HP_0012531",
+          "name": "Pain"
+         }
+        }
+       ]
+      }
+     ]
+    }
+   }
+  }
+ }
+}

tests/test_allowlist.py

@@ -0,0 +1,166 @@
+"""C2 — the allow-list holds by construction (ADR-0001 §7).
+
+What these tests pin, against the INSTALLED ToolUniverse (offline: loading reads the package's
+own JSON configs and opens no socket, which the conftest block would turn into a failure):
+
+- the config is the memo's 28 tools across 8 sources, and every name exists in 1.5.6;
+- the Space loads exactly the five endpoints' set (12 tools), nothing more;
+- no agentic, tool-finder, remote-MCP, web-search or key-gated tool is or can be loaded;
+- the installed version is the pinned one, and a mismatch refuses startup;
+- ToolUniverse's own result cache is off.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+import pytest
+
+from src import config, tu_client
+from src.tu_client import FORBIDDEN_TOOL_TYPES, StartupRefused, build_tooluniverse
+from tests.conftest import OUTBOUND_ATTEMPTS
+
+MEMO_COUNTS = {
+    "opentargets": 6,
+    "chembl": 4,
+    "uniprot": 4,
+    "clinicaltrials": 3,
+    "pubchem": 3,
+    "reactome": 3,
+    "dgidb": 3,
+    "hgnc": 2,
+}
+
+
+@pytest.fixture(scope="module")
+def loaded_tu():
+    return build_tooluniverse()
+
+
+def test_allowlist_is_the_memos_28_across_8_sources():
+    counts = Counter(config.source_of(name) for name in config.allowed_tool_names())
+    assert dict(counts) == MEMO_COUNTS
+    assert len(config.allowed_tool_names()) == 28
+
+
+def test_every_allowlisted_name_exists_in_the_installed_version():
+    tu = build_tooluniverse(include=config.allowed_tool_names())
+    assert frozenset(tu.all_tool_dict) == config.allowed_tool_names()
+
+
+def test_the_space_loads_exactly_the_endpoints_set(loaded_tu):
+    loaded = frozenset(loaded_tu.all_tool_dict)
+    assert loaded == config.endpoint_tool_names()
+    assert len(loaded) == 12
+    assert loaded <= config.allowed_tool_names()
+
+
+def test_loading_opens_no_socket():
+    before = len(OUTBOUND_ATTEMPTS)
+    build_tooluniverse()
+    assert OUTBOUND_ATTEMPTS[before:] == []
+
+
+def test_no_loaded_tool_is_agentic_finder_mcp_websearch_or_key_gated(loaded_tu):
+    for name, cfg in loaded_tu.all_tool_dict.items():
+        assert cfg.get("type") not in FORBIDDEN_TOOL_TYPES, name
+        assert not cfg.get("required_api_keys"), name
+
+
+def test_no_allowlisted_tool_is_of_a_forbidden_kind():
+    tu = build_tooluniverse(include=config.allowed_tool_names())
+    for name, cfg in tu.all_tool_dict.items():
+        assert cfg.get("type") not in FORBIDDEN_TOOL_TYPES, name
+        assert not cfg.get("required_api_keys"), name
+
+
+@pytest.mark.parametrize("name", ["Tool_Finder_LLM", "Tool_RAG", "web_search", "Finish"])
+def test_a_tool_off_the_allowlist_cannot_be_requested(name):
+    with pytest.raises(StartupRefused, match="not on the allow-list"):
+        build_tooluniverse(include=frozenset({name}))
+
+
+def test_a_forbidden_type_refuses_startup_even_if_it_loaded(monkeypatch):
+    """Defence in depth: if an allow-list edit ever let one in, the Space still will not start."""
+    from tooluniverse import ToolUniverse
+
+    real_load = ToolUniverse.load_tools
+
+    def load_with_an_agent(self, *args, **kwargs):
+        real_load(self, *args, **kwargs)
+        name = next(iter(self.all_tool_dict))
+        self.all_tool_dict[name] = {**self.all_tool_dict[name], "type": "AgenticTool"}
+
+    monkeypatch.setattr(ToolUniverse, "load_tools", load_with_an_agent)
+    with pytest.raises(StartupRefused, match="agentic"):
+        build_tooluniverse()
+
+
+def test_an_extra_loaded_tool_refuses_startup(monkeypatch):
+    from tooluniverse import ToolUniverse
+
+    real_load = ToolUniverse.load_tools
+
+    def load_one_more(self, *args, include_tools=None, **kwargs):
+        real_load(
+            self,
+            *args,
+            include_tools=[*include_tools, "PubChem_get_CID_by_compound_name"],
+            **kwargs,
+        )
+
+    monkeypatch.setattr(ToolUniverse, "load_tools", load_one_more)
+    with pytest.raises(StartupRefused, match="differs from the allow-listed set"):
+        build_tooluniverse()
+
+
+def test_a_workspace_cannot_widen_what_loads_or_bring_in_a_key(monkeypatch, tmp_path):
+    """The 2026-10-20 trap: with any workspace present, 1.5.6's constructor seeds and applies a
+    default profile (all 2,691 tools) and reads the workspace's and ~/.tooluniverse's .env."""
+    home = tmp_path / "home"
+    home.mkdir()
+    local = tmp_path / "cwd" / ".tooluniverse"
+    local.mkdir(parents=True)
+    (local / ".env").write_text("OPENAI_API_KEY=planted-in-a-workspace\n")
+    (home / ".env").write_text("GEMINI_API_KEY=planted-in-home\n")
+    monkeypatch.setenv("TOOLUNIVERSE_HOME", str(home))
+    monkeypatch.setenv("TOOLUNIVERSE_PROFILE", str(home / "profile.yaml"))
+    monkeypatch.chdir(tmp_path / "cwd")
+    tu = build_tooluniverse()
+    assert frozenset(tu.all_tool_dict) == config.endpoint_tool_names()
+    import os
+
+    assert "OPENAI_API_KEY" not in os.environ and "GEMINI_API_KEY" not in os.environ
+    assert not (home / "profile.yaml").exists()
+
+
+def test_installed_version_is_the_pinned_one():
+    assert config.pinned_tooluniverse_version() == "1.5.6"
+    assert tu_client.installed_tooluniverse_version() == "1.5.6"
+
+
+def test_a_version_mismatch_refuses_startup(monkeypatch):
+    monkeypatch.setattr(tu_client, "installed_tooluniverse_version", lambda: "1.5.7")
+    with pytest.raises(StartupRefused, match="1.5.7"):
+        build_tooluniverse()
+
+
+def test_tooluniverse_result_cache_is_off(loaded_tu):
+    assert loaded_tu.cache_manager.enabled is False
+    assert loaded_tu.cache_manager.persistent is None
+
+
+def test_only_tu_client_imports_tooluniverse():
+    from pathlib import Path
+
+    root = Path(__file__).resolve().parent.parent
+    offenders = [
+        str(p.relative_to(root))
+        for p in [*root.glob("src/**/*.py"), *root.glob("*.py")]
+        if p.name != "tu_client.py"
+        and any(
+            line.lstrip().startswith(("import tooluniverse", "from tooluniverse"))
+            for line in p.read_text(encoding="utf-8").splitlines()
+        )
+    ]
+    assert offenders == []

tests/test_audit.py

@@ -0,0 +1,58 @@
+"""The audit record is result-free and query-free: who, which endpoint, how many ids, status."""
+
+from __future__ import annotations
+
+import json
+
+import audit
+
+
+def test_local_record_holds_a_count_never_the_identifiers(monkeypatch, tmp_path):
+    monkeypatch.delenv("LOG_SINK", raising=False)
+    monkeypatch.setenv("LOG_SINK_LOCAL_DIR", str(tmp_path))
+    assert (
+        audit.record_run(
+            "drugs_for_targets",
+            username="someone",
+            n_identifiers=3,
+            status="ok",
+            run_id="20261020_120000_000001",
+        )
+        is None
+    )
+    [path] = tmp_path.glob("*.json")
+    record = json.loads(path.read_text())
+    assert record["tool"] == "drugs_for_targets"
+    assert record["n_identifiers"] == 3
+    assert record["principal"] == "someone"
+    assert set(record) == {
+        "run_id",
+        "timestamp",
+        "tool",
+        "status",
+        "n_identifiers",
+        "principal",
+        "role",
+        "enforced",
+    }
+
+
+def test_a_failing_sink_never_fails_the_call(monkeypatch):
+    import logging_sink
+
+    class Broken(logging_sink.LogSink):
+        name = "local"
+
+        def persist_trace(self, run_id, trace):
+            raise OSError("disk full")
+
+    monkeypatch.setattr(audit, "get_log_sink", lambda: Broken())
+    assert (
+        audit.record_run("annotate_genes", username=None, n_identifiers=0, status="denied") is None
+    )
+
+
+def test_the_hf_sink_defaults_to_this_spaces_own_dataset():
+    import logging_sink
+
+    assert logging_sink.DEFAULT_HF_DATASET == "anne-voigt/pdac-knowledge-results"

tests/test_cache.py

@@ -0,0 +1,74 @@
+"""C5 — the cache keeps retrieved_at honest and expires per source (ADR-0001 §8)."""
+
+from __future__ import annotations
+
+import pytest
+
+from src import config
+from src.cache import cache_key
+from src.tu_client import SourceError, ToolClient
+from tests.conftest import FakeRunner
+
+OT_DRUGS = "OpenTargets_get_associated_drugs_by_target_ensemblID"
+ARGS = {"ensemblId": "ENSG00000120889", "size": 100}
+
+
+def _client(runner, memory_cache, clock):
+    return ToolClient(runner=runner, cache=memory_cache, clock=clock, tooluniverse_version="1.5.6")
+
+
+def test_a_repeat_call_is_a_hit_with_the_original_retrieved_at(
+    memory_cache, clock, tnfrsf10b_response
+):
+    runner = FakeRunner({OT_DRUGS: tnfrsf10b_response})
+    client = _client(runner, memory_cache, clock)
+    first = client.call(OT_DRUGS, ARGS)
+    clock.advance(3600)
+    second = client.call(OT_DRUGS, ARGS)
+    assert (first.cache, second.cache) == ("miss", "hit")
+    assert second.retrieved_at == first.retrieved_at
+    assert second.data == first.data
+    assert len(runner.calls) == 1
+
+
+def test_an_entry_expires_at_the_sources_ttl(memory_cache, clock, tnfrsf10b_response):
+    runner = FakeRunner({OT_DRUGS: tnfrsf10b_response})
+    client = _client(runner, memory_cache, clock)
+    client.call(OT_DRUGS, ARGS)
+    clock.advance(config.source("opentargets")["ttl_seconds"] - 1)
+    assert client.call(OT_DRUGS, ARGS).cache == "hit"
+    clock.advance(2)
+    again = client.call(OT_DRUGS, ARGS)
+    assert again.cache == "miss"
+    assert again.retrieved_at == clock.now
+    assert len(runner.calls) == 2
+
+
+def test_ttls_are_seven_days_and_one_day_for_trials():
+    assert config.source("clinicaltrials")["ttl_seconds"] == 86_400
+    for sid in ("opentargets", "chembl", "uniprot", "reactome", "hgnc"):
+        assert config.source(sid)["ttl_seconds"] == 7 * 86_400
+
+
+def test_store_and_read_directly(memory_cache, clock):
+    memory_cache.put("chembl", "ChEMBL_get_drug_mechanisms", {"x": 1}, {"ok": True}, clock.now - 10)
+    data, retrieved_at = memory_cache.get("chembl", "ChEMBL_get_drug_mechanisms", {"x": 1})
+    assert data == {"ok": True}
+    assert retrieved_at == clock.now - 10
+    assert memory_cache.get("chembl", "ChEMBL_get_drug_mechanisms", {"x": 2}) is None
+
+
+def test_the_key_ignores_argument_order():
+    assert cache_key("T", {"a": 1, "b": 2}) == cache_key("T", {"b": 2, "a": 1})
+    assert cache_key("T", {"a": 1}) != cache_key("U", {"a": 1})
+
+
+def test_a_drifted_response_is_never_cached(memory_cache, clock):
+    drifted = {"status": "success", "data": {"target": {"id": "ENSG00000120889"}}}
+    runner = FakeRunner({OT_DRUGS: drifted})
+    client = _client(runner, memory_cache, clock)
+    for _ in range(2):
+        with pytest.raises(SourceError, match="upstream_schema_drift"):
+            client.call(OT_DRUGS, ARGS)
+    assert memory_cache.get("opentargets", OT_DRUGS, ARGS) is None
+    assert len(runner.calls) == 2

tests/test_identifiers.py

@@ -0,0 +1,109 @@
+"""What may leave the Space: identifiers only (ADR-0001 §6). Refusals are data."""
+
+from __future__ import annotations
+
+import pytest
+
+from src.identifiers import MAX_IDENTIFIERS, parse_disease, parse_gene_list, parse_nct
+
+# Real HGNC symbols chosen to exercise the edges of the pattern and of the sample-id prefixes.
+VALID_SYMBOLS = [
+    "KRAS",
+    "TP53",
+    "ELAVL1",
+    "C1orf112",
+    "HLA-DRB1",
+    "NKX2-1",
+    "IGHV1-69-2",
+    "CPT1A",
+    "ERRFI1",
+    "DOK1",
+    "SAA1",
+    "SORD2P",
+]
+
+
+@pytest.mark.parametrize("symbol", VALID_SYMBOLS)
+def test_real_symbols_pass(symbol):
+    parsed = parse_gene_list(symbol)
+    assert parsed.ok, parsed.message
+    assert parsed.identifiers[0].kind == "symbol"
+
+
+def test_a_list_splits_on_commas_spaces_and_semicolons_and_keeps_order():
+    parsed = parse_gene_list("JAK1, JAK2;STAT1  jak1")
+    assert parsed.ok
+    assert [i.value for i in parsed.identifiers] == ["JAK1", "JAK2", "STAT1"]
+    assert parsed.duplicates_dropped == 1
+
+
+def test_ensembl_ids_are_genes_and_uniprot_only_when_allowed():
+    assert parse_gene_list("ENSG00000133703").identifiers[0].kind == "ensembl"
+    assert parse_gene_list("P05161", allow_uniprot=True).identifiers[0].kind == "uniprot"
+    assert parse_gene_list("P05161").identifiers[0].kind == "symbol"
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        "what drugs target KRAS?",
+        "TCGA-2J-AAB1-01A",
+        "GSM1234567",
+        "C3L-00017",
+        "12.5",
+        "KRAS 3.2 1.1",
+        "<script>",
+        "SELECT * FROM genes",
+    ],
+)
+def test_free_text_sample_ids_and_numbers_are_refused(raw):
+    parsed = parse_gene_list(raw)
+    assert not parsed.ok
+    assert parsed.reason == "invalid_identifier"
+    assert "free text, sample ids and numbers are not" in parsed.message
+
+
+def test_an_empty_list_is_refused():
+    assert parse_gene_list("  ").reason == "invalid_identifier"
+    assert parse_gene_list([]).reason == "invalid_identifier"
+
+
+def test_more_than_the_cap_is_refused_with_the_cap():
+    raw = ",".join(f"GENE{i}" for i in range(MAX_IDENTIFIERS + 1))
+    parsed = parse_gene_list(raw)
+    assert parsed.reason == "too_many_identifiers"
+    assert str(MAX_IDENTIFIERS) in parsed.message
+    assert parse_gene_list(",".join(f"GENE{i}" for i in range(MAX_IDENTIFIERS))).ok
+
+
+def test_a_refusal_never_echoes_a_long_token():
+    parsed = parse_gene_list("x" * 200 + "!")
+    assert len(parsed.message) < 250
+    assert "x" * 30 not in parsed.message
+
+
+@pytest.mark.parametrize(
+    "raw,kind",
+    [
+        ("EFO_0002618", "disease_id"),
+        ("MONDO_0005192", "disease_id"),
+        ("pancreatic ductal adenocarcinoma", "disease_name"),
+        ("Crohn's disease", "disease_name"),
+        ("type 2 diabetes mellitus", "disease_name"),
+    ],
+)
+def test_diseases(raw, kind):
+    parsed = parse_disease(raw)
+    assert parsed.ok and parsed.identifiers[0].kind == kind
+
+
+@pytest.mark.parametrize(
+    "raw", ["", "a" * 81, "patient 12; DOB 1950-01-01?", "1234", "TCGA-2J-AAB1"]
+)
+def test_bad_diseases_are_refused(raw):
+    assert parse_disease(raw).reason == "invalid_identifier"
+
+
+def test_nct_ids():
+    assert parse_nct("nct04635059").identifiers[0].value == "NCT04635059"
+    assert parse_nct("NCT123").reason == "invalid_identifier"

tests/test_no_llm_keys.py

@@ -0,0 +1,61 @@
+"""C2 — the Space makes no model call, so it refuses to start with any model-provider setting."""
+
+from __future__ import annotations
+
+import pytest
+
+from src.tu_client import LLM_KEY_VARS, StartupRefused, assert_no_llm_keys, build_tooluniverse
+
+
+def test_a_clean_environment_passes():
+    assert_no_llm_keys({})
+    assert_no_llm_keys({"HF_TOKEN": "hf_test", "ACCESS_CONTROL": "enforce"})
+
+
+@pytest.mark.parametrize("var", LLM_KEY_VARS)
+def test_each_model_provider_setting_refuses(var):
+    with pytest.raises(StartupRefused, match=var):
+        assert_no_llm_keys({var: "set-in-a-test"})
+
+
+def test_blank_values_do_not_count():
+    assert_no_llm_keys({"OPENAI_API_KEY": "", "ANTHROPIC_API_KEY": "   "})
+
+
+@pytest.mark.parametrize("var", ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY"])
+def test_startup_refuses_before_tooluniverse_is_built(monkeypatch, var):
+    monkeypatch.setenv(var, "set-in-a-test")
+    with pytest.raises(StartupRefused, match=var):
+        build_tooluniverse()
+
+
+def test_the_message_names_the_variable_never_its_value():
+    with pytest.raises(StartupRefused) as excinfo:
+        assert_no_llm_keys({"OPENROUTER_API_KEY": "sk-should-not-appear"})
+    assert "sk-should-not-appear" not in str(excinfo.value)
+
+
+# Client libraries through which a model could be called. The memo found that, as installed,
+# ToolUniverse's LLM-backed tools cannot load because none of these is present; the lock keeps
+# it that way, so adding one is a reviewed change to this test rather than a silent transitive.
+LLM_CLIENT_LIBRARIES = {
+    "openai",
+    "anthropic",
+    "google-genai",
+    "google-generativeai",
+    "smolagents",
+    "litellm",
+    "langchain",
+    "langchain-core",
+    "vllm",
+}
+
+
+def test_the_lock_installs_no_llm_client_library():
+    import re
+    from pathlib import Path
+
+    lock = (Path(__file__).resolve().parent.parent / "requirements.txt").read_text()
+    pinned = {m.group(1).lower() for m in re.finditer(r"^([A-Za-z0-9_.-]+)==", lock, re.MULTILINE)}
+    assert pinned, "requirements.txt holds no pins"
+    assert not pinned & LLM_CLIENT_LIBRARIES

tests/test_output_schemas.py

@@ -0,0 +1,114 @@
+"""C4 (core) — a response that drifts from its pinned schema builds no rows (ADR-0001 §5).
+
+The drift case is the one Phase 0 actually saw: Open Targets replaced ``knownDrugs`` (rows of
+``drug{name maximumClinicalTrialPhase} phase``) with ``drugAndClinicalCandidates`` while the test
+ran, and a hand-written client broke. Here the old shape and a future rename both come back as
+``upstream_schema_drift``, never as partial rows.
+"""
+
+from __future__ import annotations
+
+import copy
+
+import pytest
+
+from src import config, schemas
+from src.tu_client import SourceError, ToolClient
+from tests.conftest import FakeRunner
+
+OT_DRUGS = "OpenTargets_get_associated_drugs_by_target_ensemblID"
+ARGS = {"ensemblId": "ENSG00000120889", "size": 100}
+
+# The pre-2026 Open Targets shape that the Phase 0 direct client was written against.
+KNOWN_DRUGS_SHAPE = {
+    "status": "success",
+    "data": {
+        "target": {
+            "id": "ENSG00000120889",
+            "approvedSymbol": "TNFRSF10B",
+            "knownDrugs": {
+                "count": 1,
+                "rows": [
+                    {"drug": {"name": "CONATUMUMAB", "maximumClinicalTrialPhase": 2}, "phase": 2}
+                ],
+            },
+        }
+    },
+}
+
+
+def _client(response, memory_cache, clock):
+    return ToolClient(
+        runner=FakeRunner({OT_DRUGS: response}),
+        cache=memory_cache,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+
+
+def test_the_recorded_phase0_response_validates(tnfrsf10b_response):
+    schemas.validate(OT_DRUGS, tnfrsf10b_response["data"])
+
+
+def test_an_unknown_target_is_valid_not_drift():
+    schemas.validate(OT_DRUGS, {"target": None})
+
+
+def test_the_old_known_drugs_shape_is_drift(memory_cache, clock):
+    with pytest.raises(SourceError) as excinfo:
+        _client(KNOWN_DRUGS_SHAPE, memory_cache, clock).call(OT_DRUGS, ARGS)
+    assert excinfo.value.reason == "upstream_schema_drift"
+    assert excinfo.value.source == "opentargets"
+    assert "drugAndClinicalCandidates" in excinfo.value.detail
+
+
+def test_a_future_rename_is_drift(memory_cache, clock, tnfrsf10b_response):
+    mutated = copy.deepcopy(tnfrsf10b_response)
+    target = mutated["data"]["target"]
+    target["knownDrugsAndCandidates"] = target.pop("drugAndClinicalCandidates")
+    with pytest.raises(SourceError) as excinfo:
+        _client(mutated, memory_cache, clock).call(OT_DRUGS, ARGS)
+    assert excinfo.value.reason == "upstream_schema_drift"
+
+
+def test_a_renamed_field_inside_a_row_is_drift(memory_cache, clock, tnfrsf10b_response):
+    mutated = copy.deepcopy(tnfrsf10b_response)
+    row = mutated["data"]["target"]["drugAndClinicalCandidates"]["rows"][2]
+    row["maximumStage"] = row.pop("maxClinicalStage")
+    with pytest.raises(SourceError) as excinfo:
+        _client(mutated, memory_cache, clock).call(OT_DRUGS, ARGS)
+    assert excinfo.value.reason == "upstream_schema_drift"
+    assert "rows/2" in excinfo.value.detail
+
+
+def test_an_added_field_upstream_is_not_drift(memory_cache, clock, tnfrsf10b_response):
+    mutated = copy.deepcopy(tnfrsf10b_response)
+    mutated["data"]["target"]["newUpstreamField"] = {"anything": True}
+    result = _client(mutated, memory_cache, clock).call(OT_DRUGS, ARGS)
+    assert result.cache == "miss"
+
+
+def test_a_tool_with_no_pinned_schema_builds_no_rows(memory_cache, clock):
+    client = ToolClient(
+        runner=FakeRunner({"UniProt_search": {"status": "success", "data": {"results": []}}}),
+        cache=memory_cache,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+    with pytest.raises(SourceError) as excinfo:
+        client.call("UniProt_search", {"query": "gene_exact:KRAS"})
+    assert excinfo.value.reason == "upstream_schema_drift"
+    assert "no pinned schema" in excinfo.value.detail
+
+
+def test_every_pinned_schema_belongs_to_an_endpoint_tool():
+    assert schemas.pinned_tools() <= config.endpoint_tool_names()
+
+
+@pytest.mark.xfail(
+    strict=True,
+    reason="s2 records the Phase 0 fixtures and pins the remaining 11 schemas; when it does, "
+    "this XPASSes and strict mode fails the suite until the marker is removed",
+)
+def test_every_endpoint_tool_has_a_pinned_schema():
+    assert schemas.pinned_tools() == config.endpoint_tool_names()

tests/test_provenance.py

@@ -0,0 +1,145 @@
+"""C3 (core) — provenance on every row, and the annotation payload shape (ADR-0001 §5).
+
+s1 runs these on the Phase 0 recorded Open Targets response through a stub row builder; s2 reruns
+the same assertions over every endpoint and every recorded fixture.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from src import payloads
+from src.provenance import PROVENANCE_FIELDS, missing_fields, stamp
+from src.tu_client import SourceResult, ToolClient
+from tests.conftest import FakeRunner
+
+OT_DRUGS = "OpenTargets_get_associated_drugs_by_target_ensemblID"
+ARGS = {"ensemblId": "ENSG00000120889", "size": 100}
+
+
+def _rows_from(result: SourceResult) -> list[dict]:
+    """A minimal stand-in for s2's drugs_for_targets row builder."""
+    target = result.data["target"]
+    return [
+        stamp(
+            {
+                "target": target["approvedSymbol"],
+                "drug": r["drug"]["name"],
+                "max_clinical_stage": r["maxClinicalStage"],
+            },
+            source=result.source,
+            source_tool=result.tool,
+            tooluniverse_version=result.tooluniverse_version,
+            query=result.args,
+            source_ref=r["drug"]["id"],
+            source_url=f"https://platform.opentargets.org/drug/{r['drug']['id']}",
+            retrieved_at=result.retrieved_at,
+            cache=result.cache,
+        )
+        for r in target["drugAndClinicalCandidates"]["rows"]
+    ]
+
+
+@pytest.fixture()
+def result(memory_cache, clock, tnfrsf10b_response):
+    client = ToolClient(
+        runner=FakeRunner({OT_DRUGS: tnfrsf10b_response}),
+        cache=memory_cache,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+    return client.call(OT_DRUGS, ARGS)
+
+
+def test_there_are_exactly_ten_provenance_fields():
+    assert len(PROVENANCE_FIELDS) == 10
+
+
+def test_every_row_carries_all_ten_fields(result):
+    rows = _rows_from(result)
+    assert len(rows) == 7  # the seven DR5 agents Phase 0 found
+    for row in rows:
+        assert missing_fields(row) == []
+        prov = row["provenance"]
+        assert prov["source"] == "opentargets"
+        assert prov["source_tool"] == OT_DRUGS
+        assert prov["tooluniverse_version"] == "1.5.6"
+        assert prov["query"] == ARGS
+        assert prov["source_ref"].startswith("CHEMBL")
+        assert prov["licence"] == "CC0 1.0"
+        assert prov["retrieved_at"].endswith("Z")
+
+
+def test_a_cache_hit_keeps_the_original_retrieved_at(memory_cache, clock, tnfrsf10b_response):
+    client = ToolClient(
+        runner=FakeRunner({OT_DRUGS: tnfrsf10b_response}),
+        cache=memory_cache,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+    miss = _rows_from(client.call(OT_DRUGS, ARGS))
+    clock.advance(86_400)
+    hit = _rows_from(client.call(OT_DRUGS, ARGS))
+    assert [r["provenance"]["cache"] for r in miss + hit] == ["miss"] * 7 + ["hit"] * 7
+    assert {r["provenance"]["retrieved_at"] for r in hit} == {miss[0]["provenance"]["retrieved_at"]}
+
+
+def test_an_ok_payload_is_annotation_with_no_sample_size(result):
+    payload = payloads.ok(
+        "drugs_for_targets",
+        query={"genes": ["TNFRSF10B"]},
+        rows=_rows_from(result),
+        sources_used=["opentargets"],
+        narrative="According to Open Targets (queried 2025-10-09), 7 drugs target TNFRSF10B.",
+    )
+    assert payload["status"] == "ok"
+    assert payload["kind"] == "annotation"
+    assert "n_for_inference" not in payload
+    assert "hierarchy" not in payload
+    assert payload["run_id"]
+    assert [a["source"] for a in payload["attribution"]] == ["opentargets"]
+    assert any("MRTX1133" in n["note"] for n in payload["coverage_notes"])
+    assert "not analysis" in payload["disclaimer"]
+    payloads.to_json(payload)
+
+
+def test_an_unstamped_row_cannot_reach_a_payload(result):
+    rows = _rows_from(result)
+    del rows[3]["provenance"]["licence"]
+    with pytest.raises(ValueError, match="row 3 is missing provenance fields \\['licence'\\]"):
+        payloads.ok(
+            "drugs_for_targets",
+            query={},
+            rows=rows,
+            sources_used=["opentargets"],
+            narrative="x",
+        )
+
+
+@pytest.mark.parametrize("key", ["n_for_inference", "hierarchy"])
+def test_an_annotation_payload_refuses_a_sample_size(result, key):
+    with pytest.raises(ValueError, match="never carry"):
+        payloads.ok(
+            "drugs_for_targets",
+            query={},
+            rows=_rows_from(result),
+            sources_used=["opentargets"],
+            narrative="x",
+            **{key: 7},
+        )
+
+
+def test_non_ok_payloads():
+    refused = payloads.refused("annotate_genes", "invalid_identifier", "Not a gene identifier: x")
+    assert refused["status"] == "refused" and refused["run_id"] and refused["reason"]
+    err = payloads.error(
+        "annotate_genes",
+        "all_sources_failed",
+        "UniProt did not answer",
+        source_errors=[payloads.source_error("uniprot", "source_unavailable", "timeout")],
+    )
+    assert err["status"] == "error" and err["source_errors"][0]["reason"] == "source_unavailable"
+    denied = payloads.denied("sign in")
+    assert denied["status"] == "denied" and "run_id" not in denied
+    with pytest.raises(ValueError):
+        payloads.source_error("uniprot", "guessed", "no")

tests/test_ratelimit.py

@@ -0,0 +1,143 @@
+"""C5 — per-source rate limits and timeouts become structured errors, never long waits."""
+
+from __future__ import annotations
+
+import threading
+import time
+
+import pytest
+
+from src import config
+from src.ratelimit import RateLimiters, TokenBucket
+from src.tu_client import SourceError, ToolClient
+from tests.conftest import FakeClock, FakeRunner
+
+OT_DRUGS = "OpenTargets_get_associated_drugs_by_target_ensemblID"
+UNIPROT_SEARCH = "UniProt_search"
+
+
+def test_every_source_is_limited_to_at_most_three_per_second():
+    for sid, cfg in config.sources().items():
+        assert 0 < cfg["rate_per_second"] <= 3, sid
+        assert cfg["burst"] >= 1, sid
+
+
+def test_a_55_call_burst_never_exceeds_the_configured_rate():
+    """The pORG list is 55 genes; annotating it is a burst of one call per gene."""
+    clock = FakeClock(start=0.0)
+    cfg = config.source("uniprot")
+    bucket = TokenBucket(cfg["rate_per_second"], cfg["burst"], clock=clock, sleep=clock.sleep)
+    times = []
+    for _ in range(55):
+        assert bucket.acquire(max_wait=60)
+        times.append(clock.now)
+    rate, burst = cfg["rate_per_second"], cfg["burst"]
+    for start in times:
+        in_window = sum(1 for t in times if start <= t < start + 1.0)
+        assert in_window <= rate + burst
+    # Sustained: 55 calls at 3/s with a burst of 3 cannot finish before (55 - 3) / 3 s.
+    assert times[-1] >= (55 - burst) / rate - 1e-9
+
+
+def test_waiting_longer_than_the_budget_is_refused_not_slept():
+    clock = FakeClock(start=0.0)
+    bucket = TokenBucket(1, 1, clock=clock, sleep=clock.sleep)
+    assert bucket.acquire(max_wait=0)
+    assert bucket.acquire(max_wait=0.5) is False
+    assert clock.sleeps == []
+
+
+def test_a_limited_call_becomes_a_rate_limited_source_error(
+    memory_cache, clock, tnfrsf10b_response
+):
+    limiters = RateLimiters(clock=clock, sleep=clock.sleep)
+    client = ToolClient(
+        runner=FakeRunner({OT_DRUGS: tnfrsf10b_response}),
+        cache=memory_cache,
+        limiters=limiters,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+    burst = config.source("opentargets")["burst"]
+    for i in range(burst):
+        client.call(OT_DRUGS, {"ensemblId": f"ENSG0000012088{i}", "size": 100}, max_wait=0)
+    with pytest.raises(SourceError) as excinfo:
+        client.call(OT_DRUGS, {"ensemblId": "ENSG00000120889", "size": 50}, max_wait=0)
+    assert excinfo.value.reason == "rate_limited"
+    assert excinfo.value.source == "opentargets"
+
+
+def test_concurrent_callers_share_one_bucket():
+    clock = FakeClock(start=0.0)
+    lock = threading.Lock()
+
+    def sleep(seconds):
+        with lock:
+            clock.sleeps.append(seconds)
+
+    bucket = TokenBucket(3, 3, clock=clock, sleep=sleep)
+    granted = []
+
+    def worker():
+        granted.append(bucket.acquire(max_wait=100))
+
+    threads = [threading.Thread(target=worker) for _ in range(9)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    assert all(granted)
+    # 3 from the burst, then 6 reservations each waiting a strictly later slot.
+    assert sorted(clock.sleeps) == pytest.approx([i / 3 for i in range(1, 7)])
+
+
+def test_a_source_timeout_is_source_unavailable_within_the_limit(monkeypatch, memory_cache, clock):
+    monkeypatch.setitem(config.source("uniprot"), "timeout_seconds", 0.2)
+
+    def hangs(args):
+        time.sleep(2)
+
+    client = ToolClient(
+        runner=FakeRunner({UNIPROT_SEARCH: hangs}),
+        cache=memory_cache,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+    started = time.monotonic()
+    with pytest.raises(SourceError) as excinfo:
+        client.call(UNIPROT_SEARCH, {"query": "gene_exact:KRAS"})
+    assert time.monotonic() - started < 1.5
+    assert excinfo.value.reason == "source_unavailable"
+    assert "did not answer within" in excinfo.value.detail
+
+
+def test_an_exception_inside_a_source_is_source_unavailable(memory_cache, clock):
+    client = ToolClient(
+        runner=FakeRunner({UNIPROT_SEARCH: ConnectionError("reset by peer")}),
+        cache=memory_cache,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+    with pytest.raises(SourceError) as excinfo:
+        client.call(UNIPROT_SEARCH, {"query": "gene_exact:KRAS"})
+    assert excinfo.value.reason == "source_unavailable"
+    assert "ConnectionError" in excinfo.value.detail
+
+
+def test_a_tooluniverse_error_envelope_is_source_unavailable(memory_cache, clock):
+    envelope = {"status": "error", "error": "Read timed out. (read timeout=30)"}
+    client = ToolClient(
+        runner=FakeRunner({UNIPROT_SEARCH: envelope}),
+        cache=memory_cache,
+        clock=clock,
+        tooluniverse_version="1.5.6",
+    )
+    with pytest.raises(SourceError) as excinfo:
+        client.call(UNIPROT_SEARCH, {"query": "gene_exact:KRAS"})
+    assert excinfo.value.reason == "source_unavailable"
+
+
+def test_a_tool_off_the_endpoint_set_is_a_programming_error(memory_cache, clock):
+    client = ToolClient(runner=FakeRunner(), cache=memory_cache, clock=clock)
+    with pytest.raises(ValueError, match="not an endpoint tool"):
+        client.call("PubChem_get_CID_by_compound_name", {"name": "gemcitabine"})

tests/test_sources_hosts.py

@@ -0,0 +1,73 @@
+"""C8 — every host a loaded tool can reach is declared in config/sources.yaml (ADR-0001 §6).
+
+The hosts are read offline from the installed ToolUniverse: URLs in each tool's config and in the
+source of its tool class. This is what makes the security-review addendum's host table honest:
+it is generated from the same file this test checks.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from src import config
+from src.tu_client import build_tooluniverse, tool_hosts
+
+
+@pytest.fixture(scope="module")
+def loaded_tu():
+    return build_tooluniverse()
+
+
+def test_every_loaded_tool_has_at_least_one_host(loaded_tu):
+    for name in loaded_tu.all_tool_dict:
+        assert tool_hosts(loaded_tu, name), name
+
+
+def test_every_loaded_tools_hosts_are_declared_for_its_source(loaded_tu):
+    for name in loaded_tu.all_tool_dict:
+        declared = set(config.source(config.source_of(name))["hosts"])
+        undeclared = tool_hosts(loaded_tu, name) - declared
+        assert not undeclared, f"{name} reaches undeclared hosts {sorted(undeclared)}"
+
+
+def test_no_stale_host_for_a_source_in_use(loaded_tu):
+    """A used source declares no host its loaded tools never reach."""
+    reached: dict[str, set[str]] = {}
+    for name in loaded_tu.all_tool_dict:
+        reached.setdefault(config.source_of(name), set()).update(tool_hosts(loaded_tu, name))
+    for sid, hosts in reached.items():
+        assert set(config.source(sid)["hosts"]) == hosts, sid
+
+
+def test_the_six_phase1_sources_are_the_ones_in_use():
+    used = {config.source_of(t) for t in config.endpoint_tool_names()}
+    assert used == {"opentargets", "chembl", "uniprot", "clinicaltrials", "reactome", "hgnc"}
+
+
+@pytest.mark.parametrize("sid", sorted(config.sources()))
+def test_every_source_has_a_licence_url_and_check_note(sid):
+    src = config.source(sid)
+    assert src["licence"].strip()
+    assert src["licence_url"].startswith("https://")
+    assert src["licence_checked"].startswith("2026-")
+    assert src["citation"].strip()
+
+
+def test_licences_as_checked_on_2026_10_20():
+    expected = {
+        "opentargets": "CC0 1.0",
+        "chembl": "CC BY-SA 3.0",
+        "uniprot": "CC BY 4.0",
+        "reactome": "CC0 1.0",
+    }
+    for sid, licence in expected.items():
+        assert config.source(sid)["licence"] == licence, sid
+
+
+def test_a_source_without_a_confirmed_licence_has_no_endpoint():
+    """DGIdb's data licence could not be confirmed, so no loaded tool may come from it."""
+    unconfirmed = {
+        sid for sid, src in config.sources().items() if src["licence"].startswith("Unconfirmed")
+    }
+    assert unconfirmed == {"dgidb"}
+    assert not {config.source_of(t) for t in config.endpoint_tool_names()} & unconfirmed