eduevidence 5.2.0

package/engine/analysis.py

@@ -0,0 +1,308 @@
+"""AnalysisPlan/AnalysisRun + Native Core descriptive analysis.
+
+Native Core (stdlib only — no scipy/pandas/statsmodels) supports
+deterministic: row/column/type profile, missingness, group counts,
+mean/median/min/max, explicit pre/post descriptive difference, explicit
+between-group descriptive difference. Advanced analysis (regression,
+multilevel, meta-analysis, thematic analysis) is capability-discovered; an
+unavailable capability returns `ANALYSIS_CAPABILITY_UNAVAILABLE` and never
+fabricates p-values. Advanced results enter only through
+`record_external_analysis()` with explicit provider/software provenance.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import statistics
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from engine.contracts import validate_record
+from engine.datasets import analysis_blocked_by_privacy
+from engine.ids import new_local_id
+from engine.project import ProjectWorkspace
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(frozen=True)
+class AnalysisCapabilityResult:
+    status: str
+    capability_id: str
+    output: dict
+    warnings: tuple[str, ...]
+
+
+NATIVE_CAPABILITIES = frozenset({
+    "row_column_type_profile", "missingness", "group_counts",
+    "descriptive_statistics", "pre_post_descriptive_difference",
+    "between_group_descriptive_difference",
+})
+
+ADVANCED_CAPABILITIES = frozenset({
+    "regression", "multilevel_analysis", "meta_analysis",
+    "qualitative_thematic_analysis", "structural_equation_modeling",
+})
+
+
+def _load_rows(path: Path) -> tuple[list[str], list[list[str]]]:
+    with path.open("r", encoding="utf-8-sig", newline="") as f:
+        reader = csv.reader(f)
+        rows = list(reader)
+    if not rows:
+        return [], []
+    return rows[0], rows[1:]
+
+
+def _num(value: str) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def validate_analysis_plan(project: ProjectWorkspace, plan: dict) -> list[str]:
+    errors = validate_record("analysis-plan", plan)
+    return errors
+
+
+def run_native_descriptive(project: ProjectWorkspace, plan: dict) -> dict:
+    """Run deterministic Native Core descriptive analyses for the plan.
+
+    `plan` carries dataset_ids + primary_analysis; analysis_requirements
+    from the design select which native capabilities run. Returns an
+    AnalysisRun record (status completed or capability_unavailable).
+    """
+    # privacy gate: block on required-but-undone deidentification
+    from engine.datasets import ingest_dataset  # noqa: F401  (registry use)
+    manifests = {}
+    for dsid in plan.get("dataset_ids", []):
+        manifest = project.path / "datasets" / "raw" / dsid / "manifest.json"
+        if not manifest.is_file():
+            return {
+                "analysis_run_id": new_local_id("ANL", set()),
+                "analysis_plan_id": plan["analysis_plan_id"],
+                "dataset_ids": plan.get("dataset_ids", []),
+                "status": "failed",
+                "outputs": {"error": f"dataset {dsid} not found in project"},
+                "assumption_checks": [],
+                "created_at": _now_iso(),
+                "extensions": {},
+            }
+        asset = json.loads(manifest.read_text(encoding="utf-8"))
+        reasons = analysis_blocked_by_privacy(asset)
+        if reasons:
+            return {
+                "analysis_run_id": new_local_id("ANL", set()),
+                "analysis_plan_id": plan["analysis_plan_id"],
+                "dataset_ids": plan.get("dataset_ids", []),
+                "status": "failed",
+                "outputs": {"privacy_block": reasons},
+                "assumption_checks": [],
+                "created_at": _now_iso(),
+                "extensions": {},
+            }
+        manifests[dsid] = asset
+
+    outputs: dict = {}
+    warnings: list[str] = []
+    for dsid, asset in manifests.items():
+        path = Path(asset["path"])
+        cols, rows = _load_rows(path)
+
+        # type profile
+        types: dict[str, str] = {}
+        numeric_cols: dict[str, list[float]] = {c: [] for c in cols}
+        for row in rows:
+            for idx, c in enumerate(cols):
+                if idx < len(row):
+                    v = row[idx].strip()
+                    if v == "":
+                        continue
+                    if _num(v) is not None:
+                        types.setdefault(c, "number")
+                        numeric_cols[c].append(_num(v))
+                    else:
+                        types[c] = "string"
+        missing = {
+            c: sum(1 for row in rows if len(row) <= idx or row[idx].strip() == "")
+            for idx, c in enumerate(cols)
+        }
+
+        # group counts (all columns with <= 10 distinct values)
+        group_counts: dict[str, dict] = {}
+        for idx, c in enumerate(cols):
+            counts: dict[str, int] = {}
+            for row in rows:
+                if idx < len(row) and row[idx].strip():
+                    counts[row[idx].strip()] = counts.get(row[idx].strip(), 0) + 1
+            if 0 < len(counts) <= 10:
+                group_counts[c] = counts
+
+        # descriptive statistics: ONLY for columns whose type is fully
+        # 'number'; a mixed column (some non-numeric cells) is marked
+        # explicitly instead of silently summarizing the numeric subset
+        desc: dict[str, dict] = {}
+        for c, vals in numeric_cols.items():
+            if types.get(c) == "number" and vals:
+                desc[c] = {
+                    "count": len(vals),
+                    "mean": round(statistics.fmean(vals), 4),
+                    "median": statistics.median(vals),
+                    "min": min(vals),
+                    "max": max(vals),
+                }
+
+        outputs[dsid] = {
+            "columns": cols,
+            "row_count": len(rows),
+            "types": types,
+            "missingness": missing,
+            "group_counts": group_counts,
+            "descriptive_statistics": desc,
+        }
+
+    # explicit pre/post descriptive difference (same dataset, mapped columns)
+    pre_post = (plan.get("extensions") or {}).get("pre_post_mapping")
+    if pre_post:
+        dsid = pre_post.get("dataset_id")
+        if dsid in outputs:
+            pre_col = pre_post["pre_column"]
+            post_col = pre_post["post_column"]
+            pre_vals = outputs[dsid]["descriptive_statistics"].get(pre_col, {})
+            post_vals = outputs[dsid]["descriptive_statistics"].get(post_col, {})
+            if pre_vals and post_vals:
+                outputs[dsid]["pre_post_descriptive_difference"] = {
+                    "pre_mean": pre_vals["mean"],
+                    "post_mean": post_vals["mean"],
+                    "mean_difference": round(post_vals["mean"] - pre_vals["mean"], 4),
+                    "note": "descriptive only; no p-value inferred",
+                }
+
+    # explicit between-group descriptive difference
+    between = (plan.get("extensions") or {}).get("between_group_mapping")
+    if between:
+        dsid = between.get("dataset_id")
+        if dsid in outputs:
+            group_col = between["group_column"]
+            value_col = between["value_column"]
+            path = Path(manifests[dsid]["path"])
+            cols2, rows2 = _load_rows(path)
+            if group_col in cols2 and value_col in cols2:
+                gi = cols2.index(group_col)
+                vi = cols2.index(value_col)
+                groups: dict[str, list[float]] = {}
+                for row in rows2:
+                    if gi < len(row) and vi < len(row):
+                        v = _num(row[vi])
+                        g = row[gi].strip()
+                        if v is not None and g:
+                            groups.setdefault(g, []).append(v)
+                means = {g: round(statistics.fmean(vs), 4) for g, vs in groups.items() if vs}
+                outputs[dsid]["between_group_descriptive_difference"] = {
+                    "group_means": means,
+                    "note": "descriptive only; no p-value inferred",
+                }
+
+    if warnings:
+        outputs["warnings"] = list(warnings)
+
+    run = {
+        "analysis_run_id": new_local_id("ANL", set()),
+        "analysis_plan_id": plan["analysis_plan_id"],
+        "dataset_ids": plan.get("dataset_ids", []),
+        "status": "completed",
+        "outputs": outputs,
+        "assumption_checks": [],
+        "created_at": _now_iso(),
+        "extensions": {"engine": "native_core", "capabilities": sorted(NATIVE_CAPABILITIES)},
+    }
+    errors = validate_record("analysis-run", run)
+    if errors:
+        raise ValueError(f"invalid analysis run: {errors}")
+    return run
+
+
+def record_external_analysis(project: ProjectWorkspace, *, plan: dict,
+                             provider: str, software: dict,
+                             outputs: dict, assumption_checks: list[dict],
+                             status: str) -> dict:
+    """Record an analysis produced by a discovered external capability."""
+    run = {
+        "analysis_run_id": new_local_id("ANL", set()),
+        "analysis_plan_id": plan["analysis_plan_id"],
+        "dataset_ids": plan.get("dataset_ids", []),
+        "status": "completed" if status == "completed" else "failed",
+        "outputs": outputs,
+        "assumption_checks": assumption_checks,
+        "created_at": _now_iso(),
+        "extensions": {
+            "provider": provider,
+            "software": software,
+            "external": True,
+        },
+    }
+    errors = validate_record("analysis-run", run)
+    if errors:
+        raise ValueError(f"invalid external analysis run: {errors}")
+    return run
+
+
+def save_analysis_run(project: ProjectWorkspace, run: dict) -> Path:
+    """Persist an AnalysisRun under analyses/ (atomic; never rewritten)."""
+    errors = validate_record("analysis-run", run)
+    if errors:
+        raise ValueError(f"invalid analysis run: {errors}")
+    path = project.path / "analyses" / f"{run['analysis_run_id']}.json"
+    if path.exists():
+        raise FileExistsError(f"analysis run already exists: {path}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(__import__("json").dumps(run, ensure_ascii=False, indent=2) + "\n",
+                   encoding="utf-8")
+    tmp.replace(path)
+    return path
+
+
+def mark_analysis_validated(project: ProjectWorkspace, run_id: str) -> dict:
+    """Promote a persisted AnalysisRun to `validated`.
+
+    `validated` is the ONLY status that closes the Full Research Cycle gate
+    in engine/update.py (ANALYSIS_INVALID otherwise). A human or automated
+    review gate calls this after checking the run's outputs.
+    """
+    path = project.path / "analyses" / f"{run_id}.json"
+    if not path.is_file():
+        raise FileNotFoundError(f"analysis run {run_id} not persisted under {path}")
+    run = json.loads(path.read_text(encoding="utf-8"))
+    if run.get("status") not in ("completed", "validated"):
+        raise ValueError(
+            f"cannot validate analysis run {run_id} with status "
+            f"{run.get('status')!r}; only completed runs may be validated"
+        )
+    run["status"] = "validated"
+    errors = validate_record("analysis-run", run)
+    if errors:
+        raise ValueError(f"invalid validated run: {errors}")
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(run, ensure_ascii=False, indent=2) + "\n",
+                   encoding="utf-8")
+    tmp.replace(path)
+    return run
+
+
+def capability_unavailable(capability_id: str, plan: dict) -> AnalysisCapabilityResult:
+    """Honest degradation for undiscovered advanced capabilities."""
+    return AnalysisCapabilityResult(
+        status="ANALYSIS_CAPABILITY_UNAVAILABLE",
+        capability_id=capability_id,
+        output={},
+        warnings=(
+            f"capability {capability_id!r} not discovered; no p-values or "
+            f"effect estimates were fabricated",
+        ),
+    )

package/engine/bias.py

@@ -0,0 +1,178 @@
+"""engine/bias.py - publication-bias diagnostics for v4 meta-analysis.
+
+    egger_regression  Egger (1997) funnel-asymmetry test: regress the
+                      standard normal deviate SND = d/se on precision
+                      prec = 1/se; the intercept estimates small-study bias
+                      (Borenstein 2009, ch. 41, eq. 41.1-41.3).
+    fail_safe_n       Rosenthal (1979) fail-safe N: how many null-effect
+                      studies would push the combined z below significance
+                      (Borenstein 2009, ch. 42):  N_fs = (ΣZ)² / 2.706 − k,
+                      with 2.706 = 1.645² (one-tailed z at α = 0.05).
+
+Pure stdlib (math only). Egger's intercept is tested with a two-tailed
+Student t (df = k − 2); the t CDF uses the regularized incomplete beta
+function (Numerical Recipes betacf) so no scipy is required.
+"""
+from __future__ import annotations
+
+import math
+from typing import Any
+
+_Z_CRIT_ONE_TAIL = 1.6448536269514722  # z at α = 0.05, one-tailed
+_Z_CRIT_SQUARED = _Z_CRIT_ONE_TAIL ** 2  # 2.7055434540954042
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _usable(rows: list[dict]) -> list[dict]:
+    import math as _m
+    return [r for r in rows or []
+            if _is_number(r.get("d")) and _is_number(r.get("se")) and r["se"] > 0
+            and _m.isfinite(float(r["d"])) and _m.isfinite(float(r["se"]))]
+
+
+# ---------------------------------------------------------------------------
+# Student-t survival via regularized incomplete beta (stdlib only)
+# ---------------------------------------------------------------------------
+
+def _betacf(a: float, b: float, x: float, max_iter: int = 200,
+            eps: float = 3.0e-12) -> float:
+    """Continued-fraction evaluation of the incomplete beta function."""
+    tiny = 1.0e-30
+    qab, qap, qam = a + b, a + 1.0, a - 1.0
+    c = 1.0
+    d = 1.0 - qab * x / qap
+    if abs(d) < tiny:
+        d = tiny
+    d = 1.0 / d
+    h = d
+    for m in range(1, max_iter + 1):
+        m2 = 2 * m
+        aa = m * (b - m) * x / ((qam + m2) * (a + m2))
+        d = 1.0 + aa * d
+        if abs(d) < tiny:
+            d = tiny
+        c = 1.0 + aa / c
+        if abs(c) < tiny:
+            c = tiny
+        d = 1.0 / d
+        h *= d * c
+        aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2))
+        d = 1.0 + aa * d
+        if abs(d) < tiny:
+            d = tiny
+        c = 1.0 + aa / c
+        if abs(c) < tiny:
+            c = tiny
+        d = 1.0 / d
+        delta = d * c
+        h *= delta
+        if abs(delta - 1.0) < eps:
+            break
+    return h
+
+
+def _betai(a: float, b: float, x: float) -> float:
+    """Regularized incomplete beta I_x(a, b)."""
+    if x <= 0.0:
+        return 0.0
+    if x >= 1.0:
+        return 1.0
+    bt = math.exp(math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b)
+                  + a * math.log(x) + b * math.log1p(-x))
+    if x < (a + 1.0) / (a + b + 2.0):
+        return bt * _betacf(a, b, x) / a
+    return 1.0 - bt * _betacf(b, a, 1.0 - x) / b
+
+
+def _t_two_tailed_p(t: float, df: int) -> float:
+    """Two-tailed p for a Student t with ``df`` degrees of freedom.
+
+    Uses the identity P(T > t) = 0.5 · I_{df/(df+t²)}(df/2, 1/2).
+    """
+    if df <= 0:
+        return 1.0
+    if not math.isfinite(t):
+        return 0.0
+    x = df / (df + t * t)
+    return 2.0 * 0.5 * _betai(df / 2.0, 0.5, x)
+
+
+# ---------------------------------------------------------------------------
+# Egger's regression test
+# ---------------------------------------------------------------------------
+
+def egger_regression(rows: list[dict]) -> dict:
+    """Egger (1997) funnel-asymmetry test via OLS of SND on precision.
+
+    Symmetric data (effect independent of precision) yields intercept ≈ 0;
+    a nonzero intercept signals small-study bias. Significance: two-tailed
+    t-test on the intercept, df = k − 2. With k < 3, or constant precision
+    across studies, the test is not applicable. A perfect fit (RSS = 0) is
+    treated as no detectable bias (t = 0, p = 1).
+    """
+    usable = _usable(rows)
+    k = len(usable)
+    if k < 3:
+        return {"applicable": False, "reason": "need >= 3 studies",
+                "k": k}
+    x = [1.0 / float(r["se"]) for r in usable]   # precision
+    y = [float(r["d"]) / float(r["se"]) for r in usable]  # SND
+    x_bar = sum(x) / k
+    y_bar = sum(y) / k
+    sxx = sum((xi - x_bar) ** 2 for xi in x)
+    if sxx == 0:
+        return {"applicable": False, "reason": "constant precision",
+                "k": k}
+    sxy = sum((xi - x_bar) * (yi - y_bar) for xi, yi in zip(x, y))
+    slope = sxy / sxx
+    intercept = y_bar - slope * x_bar
+    residuals = [yi - (intercept + slope * xi) for xi, yi in zip(x, y)]
+    rss = sum(rr * rr for rr in residuals)
+    mse = rss / (k - 2) if k > 2 else 0.0
+    se_intercept = math.sqrt(mse * (1.0 / k + x_bar * x_bar / sxx))
+    if se_intercept == 0 or not math.isfinite(se_intercept):  # perfect fit
+        t, p = 0.0, 1.0
+    else:
+        t = intercept / se_intercept
+        p = _t_two_tailed_p(t, k - 2)
+    return {
+        "applicable": True,
+        "k": k,
+        "intercept": intercept,
+        "se_intercept": se_intercept,
+        "slope": slope,
+        "t": t,
+        "p_value": p,
+        "significant": p < 0.05,
+        "bias_detected": p < 0.05,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Rosenthal's fail-safe N
+# ---------------------------------------------------------------------------
+
+def fail_safe_n(rows: list[dict]) -> dict:
+    """Rosenthal (1979) fail-safe N: null studies needed to nullify the result.
+
+    N_fs = (ΣZ)² / 2.706 − k with Z = d/se (floored at 0). ``tolerates_5``
+    reports whether the finding survives the addition of 5 null studies
+    (N_fs ≥ 5) — the task's minimum robustness bar.
+    """
+    usable = _usable(rows)
+    k = len(usable)
+    zs = [float(r["d"]) / float(r["se"]) for r in usable]
+    sum_z = sum(zs)
+    n_fail_safe = max(0.0, (sum_z * sum_z) / _Z_CRIT_SQUARED - k)
+    return {
+        "method": "rosenthal",
+        "k": k,
+        "sum_z": sum_z,
+        "z_crit": _Z_CRIT_ONE_TAIL,
+        "z_crit_squared": _Z_CRIT_SQUARED,
+        "n_fail_safe": n_fail_safe,
+        "tolerates_5": n_fail_safe >= 5.0,
+    }

package/engine/briefs.py

@@ -0,0 +1,106 @@
+"""Schema-bound task briefs.
+
+A task brief is generated from the registered schema metadata — required
+fields and enums are read from the schema, never hard-coded twice in this
+module. `build_task_brief()` accepts only `PlanStep(kind="capability")`;
+calling it on a wait step raises a clear ValueError instead of generating a
+fake agent task.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from engine.contracts import load_schema, schema_path
+from engine.planner import PlanStep
+
+
+def _schema_section(schema: dict) -> str:
+    lines: list[str] = []
+    props = schema.get("properties", {})
+    required = set(schema.get("required", []))
+    for key in sorted(props):
+        prop = props[key]
+        line = f"- `{key}`"
+        if key in required:
+            line += " (REQUIRED)"
+        if "enum" in prop:
+            line += f" enum={prop['enum']}"
+        if "pattern" in prop:
+            line += f" pattern={prop['pattern']!r}"
+        if "const" in prop:
+            line += f" const={prop['const']!r}"
+        lines.append(line)
+    return "\n".join(lines) if lines else "(no properties)"
+
+
+def build_task_brief(step: PlanStep, *, project: ProjectWorkspace,
+                     input_payload: dict, output_path: Path) -> str:
+    """Render a capability step into an executable agent brief.
+
+    `project` is the ProjectWorkspace (for context ids); `input_payload`
+    carries the input entity ids/records for this step; `output_path` is
+    where the step's output artifact must be written.
+    """
+    if step.kind != "capability" or step.capability_id is None:
+        raise ValueError(
+            f"cannot build a task brief for non-capability step "
+            f"{step.step_id!r} (kind={step.kind}); wait steps are real "
+            f"states, not fake agent tasks"
+        )
+    cap = step.capability_id
+    schema_name = step.output_contract
+    if schema_name is None:
+        raise ValueError(f"capability {cap} has no output contract")
+
+    sch = load_schema(schema_name)
+    sch_file = schema_path(schema_name)
+
+    lines = [
+        f"# Task brief: {cap}",
+        "",
+        f"Project: {project.project_id}",
+        f"Output schema: {sch_file.relative_to(Path.cwd()) if sch_file.is_relative_to(Path.cwd()) else sch_file}",
+        "",
+        "## Output contract (schema-derived)",
+        _schema_section(sch),
+        "",
+        "## Required fields",
+        ", ".join(sch.get("required", [])) or "(none)",
+        "",
+        "## Validation",
+        f"Validate the output with `engine.contracts.validate_record({schema_name!r}, record)` — "
+        f"it must return [] (empty errors).",
+        "",
+        f"## Output path",
+        str(output_path),
+        "",
+        "## Inputs",
+        json.dumps(input_payload, ensure_ascii=False, indent=2),
+    ]
+
+    # capability-specific hard rules
+    rules: dict[str, str] = {
+        "finding_extraction": (
+            "HARD RULE: `relation_to_claim` does NOT belong in a Finding. "
+            "Findings record only what the study observed (`effect_direction`); "
+            "the relation to a Claim lives on the EvidenceLink."),
+        "source_validation": (
+            "HARD RULE: a search snippet is never evidence content (RULE 2). "
+            "Only fetched + validated source content may be extracted."),
+        "counter_evidence_search": (
+            "HARD RULE: seek null/negative/contradictory evidence, AI "
+            "dependency, reduced transfer, novelty effects, self-selection "
+            "bias, alternative explanations. Never fabricate counter-evidence."),
+        "evidence_synthesis": (
+            "HARD RULE: independent-study counting only. 5 Findings from one "
+            "Study = 1 independent study; never count Findings as Studies."),
+        "tribunal": (
+            "HARD RULE: pass the Pre-Verdict Gate before adjudicating; "
+            "critical failures forbid high-confidence verdicts."),
+    }
+    if cap in rules:
+        lines += ["", "## Hard rules", rules[cap]]
+
+    return "\n".join(lines) + "\n"

package/engine/capabilities.py

@@ -0,0 +1,99 @@
+"""Capability registry — the scientific capabilities a research plan can use.
+
+The registry is independent of Agent names and model names: planning routes
+by capability, execution routing (Agent MCP vs native) happens later and
+orthogonally. A capability may be deterministic-local (Native Core) or
+capability-discovered (SCP), and may carry a scientific gate.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CapabilitySpec:
+    capability_id: str
+    input_contracts: tuple[str, ...]
+    output_contracts: tuple[str, ...]
+    deterministic_local: bool
+    scientific_gate: str | None
+
+
+_REGISTRY: dict[str, CapabilitySpec] = {}
+
+
+def _register(capability_id: str, *, input_contracts: tuple[str, ...],
+              output_contracts: tuple[str, ...], deterministic_local: bool,
+              scientific_gate: str | None = None) -> None:
+    _REGISTRY[capability_id] = CapabilitySpec(
+        capability_id=capability_id,
+        input_contracts=input_contracts,
+        output_contracts=output_contracts,
+        deterministic_local=deterministic_local,
+        scientific_gate=scientific_gate,
+    )
+
+
+# Evidence Review pipeline
+_register("research_framing", input_contracts=("research-intent",),
+          output_contracts=("education-frame",), deterministic_local=False)
+_register("literature_search", input_contracts=("education-frame",),
+          output_contracts=("source",), deterministic_local=False)
+_register("counter_evidence_search", input_contracts=("education-frame",),
+          output_contracts=("source",), deterministic_local=False,
+          scientific_gate="RULE 4: independent counter-evidence search")
+_register("source_fetch", input_contracts=("source",),
+          output_contracts=("fetch-result",), deterministic_local=False)
+_register("source_validation", input_contracts=("source", "fetch-result"),
+          output_contracts=("source",), deterministic_local=True,
+          scientific_gate="snippet != evidence (RULE 2)")
+_register("study_extraction", input_contracts=("source",),
+          output_contracts=("study",), deterministic_local=False)
+_register("finding_extraction", input_contracts=("study",),
+          output_contracts=("finding",), deterministic_local=False)
+_register("methodology_appraisal", input_contracts=("study",),
+          output_contracts=("methodology-audit",), deterministic_local=False)
+_register("claim_linking", input_contracts=("finding", "claim"),
+          output_contracts=("evidence-link",), deterministic_local=False,
+          scientific_gate="relation_to_claim lives on the link, never the finding")
+_register("evidence_synthesis", input_contracts=("evidence-link", "methodology-audit"),
+          output_contracts=("synthesis",), deterministic_local=True,
+          scientific_gate="independent Study counting, never Finding counting")
+_register("tribunal", input_contracts=("synthesis",),
+          output_contracts=("decision-snapshot",), deterministic_local=False,
+          scientific_gate="Pre-Verdict Gate before Tribunal")
+_register("applicability_analysis", input_contracts=("evidence-link",),
+          output_contracts=("applicability",), deterministic_local=False)
+_register("knowledge_gap_detection", input_contracts=("education-frame", "claim"),
+          output_contracts=("knowledge-gap",), deterministic_local=True)
+_register("report_projection", input_contracts=("graph-revision",),
+          output_contracts=("projection",), deterministic_local=True)
+_register("report_rendering", input_contracts=("projection",),
+          output_contracts=("report",), deterministic_local=True)
+
+# Full Research Cycle additions
+_register("study_design", input_contracts=("knowledge-gap",),
+          output_contracts=("study-design",), deterministic_local=False,
+          scientific_gate="No new study design without evidence grounding")
+_register("measurement_design", input_contracts=("study-design",),
+          output_contracts=("analysis-plan",), deterministic_local=False)
+_register("data_validation", input_contracts=("dataset-asset",),
+          output_contracts=("dataset-manifest",), deterministic_local=True,
+          scientific_gate="provenance/hash/missingness before analysis")
+_register("data_analysis", input_contracts=("dataset-manifest", "analysis-plan"),
+          output_contracts=("analysis-run",), deterministic_local=True,
+          scientific_gate="never fabricate p-values; ANALYSIS_CAPABILITY_UNAVAILABLE")
+_register("intervention_design", input_contracts=("decision-snapshot",),
+          output_contracts=("intervention",), deterministic_local=False)
+_register("evaluation_design", input_contracts=("decision-snapshot",),
+          output_contracts=("evaluation",), deterministic_local=False)
+
+
+def capability_registry() -> dict[str, CapabilitySpec]:
+    """Return the frozen capability registry."""
+    return dict(_REGISTRY)
+
+
+def capability(capability_id: str) -> CapabilitySpec | None:
+    return _REGISTRY.get(capability_id)