eduevidence 5.2.0

package/engine/projections.py

@@ -0,0 +1,240 @@
+"""V2 graph projections + V1 compatibility result.json.
+
+Projections are read-only views of a graph revision: they never mutate graph
+entities. Outcome aggregation uses Finding.effect_direction; claim trace uses
+EvidenceLink.relation_to_claim; study counts use Study IDs. Compatibility
+`evidence` rows are view rows with explicit finding_id/evidence_link_id in
+extensions so no identity is lost.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from engine.graph_store import GraphStore
+from engine.project import ProjectWorkspace
+from engine.semantics import claim_relation, decision_implication, finding_effect
+
+
+def _load_latest_snapshot(project: ProjectWorkspace,
+                          decision_snapshot_id: str | None) -> dict | None:
+    decisions = project.path / "decisions"
+    if not decisions.is_dir():
+        return None
+    if decision_snapshot_id:
+        p = decisions / f"{decision_snapshot_id}.json"
+        if p.is_file():
+            return json.loads(p.read_text(encoding="utf-8"))
+        return None
+    snaps = []
+    for p in decisions.glob("DEC-*.json"):
+        try:
+            rec = json.loads(p.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        snaps.append(rec)
+    if not snaps:
+        return None
+    # latest by created_at, never by filename (DEC ids are random hex)
+    return max(snaps, key=lambda r: r.get("created_at", ""))
+
+
+def _load_gaps(project: ProjectWorkspace) -> list[dict]:
+    gaps: list[dict] = []
+    gaps_dir = project.path / "gaps"
+    if gaps_dir.is_dir():
+        for f in sorted(gaps_dir.glob("gaps-rev-*.jsonl")):
+            for line in f.read_text(encoding="utf-8").splitlines():
+                if line.strip():
+                    gaps.append(json.loads(line))
+    return gaps
+
+
+def _load_study_designs(project: ProjectWorkspace) -> list[dict]:
+    designs: list[dict] = []
+    ddir = project.path / "study-designs"
+    if ddir.is_dir():
+        for f in sorted(ddir.glob("DSN-*.json")):
+            designs.append(json.loads(f.read_text(encoding="utf-8")))
+    return designs
+
+
+def build_report_projection(project: ProjectWorkspace, *,
+                            graph_revision: int | None = None,
+                            decision_snapshot_id: str | None = None) -> dict:
+    """Project the active (or named) graph revision into a report view."""
+    store = GraphStore.create(project)
+    revision = graph_revision if graph_revision is not None else store.active_revision()
+    if revision != store.active_revision():
+        raise ValueError(
+            f"projection of historical revision {revision} not yet supported; "
+            f"active revision is {store.active_revision()}")
+
+    manifest = project.manifest()
+    sources = store.read_table("sources")
+    studies = store.read_table("studies")
+    findings = store.read_table("findings")
+    outcomes = store.read_table("outcomes")
+    claims = store.read_table("claims")
+    links = store.read_table("evidence_links")
+    audits = store.read_table("audits")
+
+    snapshot = _load_latest_snapshot(project, decision_snapshot_id)
+
+    # outcome aggregation by effect_direction
+    outcome_rows: dict[str, dict] = {}
+    for o in outcomes:
+        outcome_rows[o["outcome_id"]] = {
+            "outcome_id": o["outcome_id"],
+            "name": o["name"],
+            "outcome_type": o["outcome_type"],
+            "positive_count": 0, "negative_count": 0, "null_count": 0,
+            "evidence_ids": [],
+        }
+    for f in findings:
+        row = outcome_rows.setdefault(f["outcome_id"], {
+            "outcome_id": f["outcome_id"], "name": f.get("measure", f["outcome_id"]),
+            "outcome_type": "learning", "positive_count": 0,
+            "negative_count": 0, "null_count": 0, "evidence_ids": []})
+        direction = finding_effect(f)
+        if direction == "positive":
+            row["positive_count"] += 1
+        elif direction == "negative":
+            row["negative_count"] += 1
+        else:
+            row["null_count"] += 1
+        row["evidence_ids"].append(f["finding_id"])
+
+    # claim trace via EvidenceLink semantics
+    claim_rows: list[dict] = []
+    for c in claims:
+        c_links = [l for l in links if l["claim_id"] == c["claim_id"]]
+        claim_rows.append({
+            "claim_id": c["claim_id"],
+            "claim": c["text"],
+            "claim_type": c["claim_type"],
+            "outcome_type": c["primary_outcome_ids"][0] if c["primary_outcome_ids"] else None,
+            "evidence_ids": [l["finding_id"] for l in c_links],
+            "status": c["status"],
+            "supporting_links": [l["evidence_link_id"] for l in c_links
+                                 if claim_relation(l) == "support"],
+            "contradicting_links": [l["evidence_link_id"] for l in c_links
+                                    if claim_relation(l) == "contradict"],
+        })
+
+    # evidence view rows (compat) with identity preserved
+    study_source: dict[str, str | None] = {}
+    for s in studies:
+        study_source[s["study_id"]] = s["source_ids"][0] if s.get("source_ids") else None
+    evidence_rows = []
+    for f in findings:
+        f_links = [l for l in links if l["finding_id"] == f["finding_id"]]
+        evidence_rows.append({
+            "evidence_id": f["finding_id"],
+            "source_id": study_source.get(f["study_id"]),
+            "study_id": f["study_id"],
+            "claim": f.get("raw_result_text", ""),
+            "outcome_type": f.get("measure", ""),
+            "relation_to_claim": claim_relation(f_links[0]) if f_links else "neutral",
+            "effect_direction": finding_effect(f),
+            "decision_relation": decision_implication(f_links[0]) if f_links else "neutral",
+            "source_location": f.get("source_locator", ""),
+            "extensions": {
+                "finding_id": f["finding_id"],
+                "evidence_link_id": f_links[0]["evidence_link_id"] if f_links else None,
+            },
+        })
+
+    return {
+        "project_id": project.project_id,
+        "graph_revision": revision,
+        "decision_snapshot_id": snapshot["decision_snapshot_id"] if snapshot else None,
+        "decision": snapshot["decision"] if snapshot else "INSUFFICIENT_EVIDENCE",
+        "confidence_label": snapshot["confidence_label"] if snapshot else None,
+        "research_frame": {
+            "education_question": manifest["question"],
+            "research_mode": manifest["research_mode"],
+            "decision_target": manifest["decision_target"],
+        },
+        "counts": {
+            "source_count": len(sources),
+            "study_count": len(studies),
+            "finding_count": len(findings),
+            "claim_count": len(claims),
+            "evidence_link_count": len(links),
+        },
+        "sources": sources,
+        "studies": studies,
+        "findings": findings,
+        "evidence_links": links,
+        "outcomes": list(outcome_rows.values()),
+        "claims": claim_rows,
+        "evidence": evidence_rows,
+        "methodology_reviews": audits,
+        "knowledge_gaps": _load_gaps(project),
+        "study_designs": _load_study_designs(project),
+        "analysis_provenance": [
+            {
+                "dataset_id": (s.get("extensions") or {}).get("dataset_id"),
+                "design_id": (s.get("extensions") or {}).get("design_id"),
+                "analysis_run_id": (s.get("extensions") or {}).get("analysis_run_id"),
+            }
+            for s in sources if s.get("origin") == "project"
+        ],
+        "provenance": {
+            "project_id": project.project_id,
+            "graph_revision": revision,
+            "projected_at": __import__("datetime").datetime.now(
+                __import__("datetime").timezone.utc).isoformat(),
+        },
+    }
+
+
+def build_v1_compat_result(project: ProjectWorkspace, *,
+                           graph_revision: int | None = None,
+                           decision_snapshot_id: str | None = None) -> dict:
+    """Map the projection into the V1 result.json shape the renderer expects."""
+    proj = build_report_projection(project, graph_revision=graph_revision,
+                                   decision_snapshot_id=decision_snapshot_id)
+    return {
+        "meta": {"engine_version": "2.0.0", "project_id": proj["project_id"]},
+        "execution": {"graph_revision": proj["graph_revision"]},
+        "research_frame": proj["research_frame"],
+        "decision": {
+            "verdict": proj["decision"],
+            "confidence": proj["confidence_label"],
+            "summary": "",
+        },
+        "outcomes": proj["outcomes"],
+        "claims": proj["claims"],
+        "sources": proj["sources"],
+        "evidence": proj["evidence"],
+        "methodology_reviews": proj["methodology_reviews"],
+        "conflicts": [],
+        "applicability": {},
+        "intervention": {},
+        "evaluation": {},
+        "knowledge_gaps": proj["knowledge_gaps"],
+        "study_designs": proj["study_designs"],
+        "analysis_provenance": proj["analysis_provenance"],
+        "benchmark": {},
+        "provenance": proj["provenance"],
+    }
+
+
+def build_localization_pack(projection: dict, *, lang: str,
+                            localized_text: dict[str, str]) -> dict:
+    """Wrap a projection with a localization layer (language strings)."""
+    if lang not in ("zh", "en"):
+        raise ValueError(f"unsupported language {lang!r}")
+    return {
+        "lang": lang,
+        "project_id": projection.get("project_id"),
+        "graph_revision": projection.get("graph_revision"),
+        "decision_snapshot_id": projection.get("decision_snapshot_id"),
+        "decision": projection.get("decision"),
+        "confidence_label": projection.get("confidence_label"),
+        "localized_text": dict(localized_text),
+        "counts": projection.get("counts", {}),
+    }

package/engine/robustness.py

@@ -0,0 +1,109 @@
+"""engine/robustness.py - leave-one-out sensitivity analysis for v4 meta-analysis.
+
+    leave_one_out     re-run a pooling function k times, each time dropping
+                      one study, and compare every result against the
+                      full-sample pooled effect.
+    robustness_label  robust vs fragile: any leave-one-out iteration whose
+                      pooled direction flips, or whose 95% CI crosses zero,
+                      marks the synthesis fragile.
+
+Pure stdlib, no third-party dependencies.
+"""
+from __future__ import annotations
+
+import math
+from typing import Any, Callable
+
+
+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"]))]
+
+
+def _direction(d: float) -> int:
+    """+1 positive, −1 negative, 0 exactly zero."""
+    if d > 0:
+        return 1
+    if d < 0:
+        return -1
+    return 0
+
+
+def _ci_crosses_zero(pooled: dict) -> bool:
+    return pooled["ci_low"] <= 0.0 <= pooled["ci_high"]
+
+
+def leave_one_out(rows: list[dict],
+                  pooling_fn: Callable[[list[dict]], dict | None]) -> dict | None:
+    """Re-run ``pooling_fn`` on every k−1 subset; compare to the full pooled.
+
+    ``direction_flip`` is True when the dropped study reverses the pooled
+    direction (full-sample effect is nonzero and the subset moves to the
+    opposite sign); ``ci_crosses_zero`` when the subset CI spans zero;
+    ``decision_changed`` = either. Returns None when fewer than two usable
+    rows exist.
+    """
+    usable = _usable(rows)
+    k = len(usable)
+    if k < 2:
+        return None
+    full = pooling_fn(usable)
+    if full is None:
+        return None
+    full_dir = _direction(full["d"])
+    iterations = []
+    for i, removed in enumerate(usable):
+        subset = usable[:i] + usable[i + 1:]
+        pooled = pooling_fn(subset)
+        if pooled is None:
+            continue
+        direction_flip = (full_dir != 0
+                          and _direction(pooled["d"]) != 0
+                          and _direction(pooled["d"]) != full_dir)
+        ci_crosses_zero = _ci_crosses_zero(pooled)
+        iterations.append({
+            "removed_study_id": removed.get("study_id"),
+            "removed_index": i,
+            "pooled": pooled,
+            "direction_flip": direction_flip,
+            "ci_crosses_zero": ci_crosses_zero,
+            "decision_changed": direction_flip or ci_crosses_zero,
+        })
+    return {
+        "method": "leave_one_out",
+        "k": k,
+        "full_pooled": full,
+        "iterations": iterations,
+        "n_direction_flips": sum(1 for it in iterations if it["direction_flip"]),
+        "n_ci_crossings": sum(1 for it in iterations if it["ci_crosses_zero"]),
+        "n_decision_changes": sum(1 for it in iterations if it["decision_changed"]),
+    }
+
+
+def robustness_label(results: dict | None) -> str:
+    """robust / fragile classification of a leave-one-out result.
+
+    Fragile when any dropped study flips the pooled direction or makes the
+    CI cross zero; otherwise robust. None (no analysis possible) is fragile.
+    """
+    if results is None:
+        return "fragile"
+    for it in results.get("iterations", []):
+        if it.get("direction_flip") or it.get("ci_crosses_zero"):
+            return "fragile"
+    return "robust"
+
+
+def _mean_std(values: list[float]) -> tuple[float, float]:
+    """Unused helper kept for parity with the textbook SD definition."""
+    if not values:
+        return 0.0, 0.0
+    m = sum(values) / len(values)
+    v = sum((x - m) ** 2 for x in values) / (len(values) - 1) if len(values) > 1 else 0.0
+    return m, math.sqrt(v)

package/engine/run.py

@@ -0,0 +1,85 @@
+"""RunRecord lifecycle — one execution attempt or mutation inside a Project.
+
+A Run starts at the Project's current graph revision (`graph_revision_before`)
+and, on completion, records `graph_revision_after`. Runs live at
+`runs/<run_id>/run.json`; a second Run never overwrites the first.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from engine.contracts import validate_record
+from engine.ids import new_run_id
+from engine.project import ProjectWorkspace
+from engine.versions import (
+    CONFIDENCE_POLICY_VERSION,
+    METHODOLOGY_POLICY_VERSION,
+    SOURCE_VALIDATION_POLICY_VERSION,
+)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _run_path(project: ProjectWorkspace, run_id: str) -> Path:
+    return project.runs_dir() / run_id / "run.json"
+
+
+def _atomic_write_json(path: Path, record: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(
+        json.dumps(record, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    os.replace(tmp, path)
+
+
+def _check(record: dict) -> None:
+    errors = validate_record("run", record)
+    if errors:
+        raise ValueError(f"invalid run record: {errors}")
+
+
+def start_run(project: ProjectWorkspace, *, purpose: str,
+              capabilities: list[str], execution_backend: str) -> dict:
+    """Open a new Run at the Project's current revision."""
+    run = {
+        "run_id": new_run_id(),
+        "project_id": project.project_id,
+        "purpose": purpose,
+        "started_at": _now_iso(),
+        "status": "running",
+        "graph_revision_before": project.current_revision(),
+        "graph_revision_after": None,
+        "capabilities": sorted(set(capabilities)),
+        "execution_backend": execution_backend,
+        "policy_versions": {
+            "source_validation": SOURCE_VALIDATION_POLICY_VERSION,
+            "methodology": METHODOLOGY_POLICY_VERSION,
+            "confidence": CONFIDENCE_POLICY_VERSION,
+        },
+    }
+    _check(run)
+    _atomic_write_json(_run_path(project, run["run_id"]), run)
+    return run
+
+
+def finish_run(project: ProjectWorkspace, run_id: str, *,
+               status: str, graph_revision_after: int) -> dict:
+    """Close a Run with its final status and end revision."""
+    path = _run_path(project, run_id)
+    if not path.is_file():
+        raise FileNotFoundError(f"run {run_id!r} not found in project {project.project_id}")
+    run = json.loads(path.read_text(encoding="utf-8"))
+    if run["status"] != "running":
+        raise ValueError(f"run {run_id} is already {run['status']!r}; cannot finish twice")
+    run["status"] = status
+    run["graph_revision_after"] = graph_revision_after
+    _check(run)
+    _atomic_write_json(path, run)
+    return run

package/engine/semantics.py

@@ -0,0 +1,135 @@
+"""engine/semantics.py — Centralized V2 & V4/V5 semantics and Outcome Ontology.
+
+Combines:
+1. V2 Direction & Implication Semantics (finding_effect, claim_relation, decision_implication)
+2. V5 Social Science Outcome Ontology & OutcomeClassifier (OutcomeDimension, OutcomeClassifier)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Set
+
+# --- V2 Direction & Relation Constants ---
+FINDING_EFFECTS = ("positive", "negative", "null", "mixed", "not_applicable")
+CLAIM_RELATIONS = ("support", "contradict", "neutral")
+DECISION_IMPLICATIONS = ("support_adoption", "oppose_adoption", "conditional", "neutral")
+
+_RELATION_TO_IMPLICATION = {
+    "support": "support_adoption",
+    "contradict": "oppose_adoption",
+    "neutral": "neutral",
+}
+
+
+def finding_effect(finding: dict) -> str:
+    """Observed effect direction of a V2 Finding."""
+    effect = finding.get("effect_direction")
+    if effect in FINDING_EFFECTS:
+        return effect
+    return "null"
+
+
+def claim_relation(link: dict) -> str:
+    """Relation of an EvidenceLink to the Claim it binds."""
+    relation = link.get("relation_to_claim")
+    if relation in CLAIM_RELATIONS:
+        return relation
+    return "neutral"
+
+
+def decision_implication(link: dict) -> str:
+    """Implication of an EvidenceLink for the current teaching decision."""
+    implication = link.get("decision_implication")
+    if implication in DECISION_IMPLICATIONS:
+        return implication
+    return _RELATION_TO_IMPLICATION[claim_relation(link)]
+
+
+def independent_study_ids(findings: list[dict]) -> set[str]:
+    """Unique Study IDs behind a set of Findings (independent-study counting)."""
+    return {f["study_id"] for f in findings if f.get("study_id")}
+
+
+def independent_sample_keys(studies: list[dict]) -> set[str]:
+    """Unique independence keys across Studies (independent sample counting)."""
+    keys = {s["independence_key"] for s in studies if s.get("independence_key")}
+    return keys
+
+
+def graph_counts(store) -> dict[str, int]:
+    """Entity counts of the active graph revision."""
+    return {
+        "source_count": len(store.read_table("sources")),
+        "study_count": len(store.read_table("studies")),
+        "finding_count": len(store.read_table("findings")),
+        "outcome_count": len(store.read_table("outcomes")),
+        "claim_count": len(store.read_table("claims")),
+        "evidence_link_count": len(store.read_table("evidence_links")),
+        "audit_count": len(store.read_table("audits")),
+    }
+
+
+# --- V5 Outcome Ontology & Dimension Classifier ---
+
+class OutcomeDimension:
+    PROCEDURAL_EFFICIENCY = "PROCEDURAL_EFFICIENCY"   # Speed, task velocity, immediate completion during intervention
+    CONCEPTUAL_MASTERY = "CONCEPTUAL_MASTERY"         # Deep understanding, mental model construction, reasoning
+    INDEPENDENT_TRANSFER = "INDEPENDENT_TRANSFER"     # Delayed retention, unassisted solo closed-book transfer
+    AFFECTIVE_PSYCHOSOCIAL = "AFFECTIVE_PSYCHOSOCIAL" # Anxiety, engagement, self-efficacy, motivation
+    SOCIOECONOMIC_POLICY = "SOCIOECONOMIC_POLICY"     # Family expenditure, equity gap, resource allocation
+    GENERAL_MEASURE = "GENERAL_MEASURE"
+
+    ALL = [
+        PROCEDURAL_EFFICIENCY,
+        CONCEPTUAL_MASTERY,
+        INDEPENDENT_TRANSFER,
+        AFFECTIVE_PSYCHOSOCIAL,
+        SOCIOECONOMIC_POLICY,
+        GENERAL_MEASURE,
+    ]
+
+
+class OutcomeClassifier:
+    """Classifies outcome metric descriptions into canonical social science dimensions."""
+
+    @staticmethod
+    def classify(metric_text: str) -> str:
+        if not metric_text:
+            return OutcomeDimension.GENERAL_MEASURE
+
+        t = metric_text.lower()
+        # 1. Independent Transfer & Delayed Retention (Highest Priority to detect Scaffolding Traps)
+        if any(k in t for k in [
+            "transfer", "retention", "delayed", "exam", "solo", "unassisted", "no-ai",
+            "post-test", "follow-up", "long-term", "persistence",
+            "迁移", "闭卷", "期末", "长期", "留存", "保持", "无ai测试", "独立解题", "手写代码"
+        ]):
+            return OutcomeDimension.INDEPENDENT_TRANSFER
+        # 2. Conceptual Mastery & Deep Reasoning
+        elif any(k in t for k in [
+            "thinking", "conceptual", "problem solving", "reasoning", "comprehension",
+            "mental model", "algorithmic", "abstraction", "debugging strategy",
+            "思维", "概念", "架构", "认知", "问题解决", "算法理解", "心智模型", "调试策略"
+        ]):
+            return OutcomeDimension.CONCEPTUAL_MASTERY
+        # 3. Procedural Efficiency & In-task velocity
+        elif any(k in t for k in [
+            "speed", "velocity", "completion", "time", "procedural", "task performance",
+            "accuracy", "efficiency", "correctness", "syntax", "lines of code", "loc",
+            "速度", "耗时", "效率", "作业完成", "完成时间", "语法正确", "即时准确率", "代码量"
+        ]):
+            return OutcomeDimension.PROCEDURAL_EFFICIENCY
+        # 4. Affective & Psychosocial
+        elif any(k in t for k in [
+            "anxiety", "engagement", "interest", "efficacy", "collaboration", "motivation",
+            "confidence", "self-regulation", "frustration",
+            "焦虑", "投入", "效能", "协作", "动机", "自信", "自我调节", "挫败感", "学习兴趣"
+        ]):
+            return OutcomeDimension.AFFECTIVE_PSYCHOSOCIAL
+        # 5. Socioeconomic & Policy
+        elif any(k in t for k in [
+            "expenditure", "cost", "equity", "burden", "socioeconomic", "disparity",
+            "支出", "负担", "公平", "成本", "数字鸿沟", "社会经济"
+        ]):
+            return OutcomeDimension.SOCIOECONOMIC_POLICY
+
+        return OutcomeDimension.GENERAL_MEASURE

package/engine/study_design.py

@@ -0,0 +1,87 @@
+"""Evidence-grounded StudyDesign gate + persistence.
+
+A StudyDesign may only be created from explicit KnowledgeGap entities that
+exist in THIS project (same project_id) and were derived from the current
+graph revision. The engine validates grounding and stores designs; it does
+not itself claim ethics approval — human-subject flags are surfaced, and
+institutional review remains the institution's decision.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from engine.contracts import validate_record
+from engine.project import ProjectWorkspace
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def validate_design_grounding(project: ProjectWorkspace, design: dict) -> list[str]:
+    """Validate that the design references real, project-local GAP ids.
+
+    Returns a list of error strings (empty == valid).
+    """
+    errors: list[str] = []
+    # grounding gate first: an empty gap list is a grounding failure with a
+    # clear message, not just a schema minItems violation
+    if not design.get("gap_ids"):
+        return ["gap_ids must be non-empty: no new study design without "
+                "evidence grounding"]
+    schema_errors = validate_record("study-design", design)
+    if schema_errors:
+        errors.extend(schema_errors)
+        return errors
+
+    gap_ids = design["gap_ids"]
+
+    # load this project's gaps (all revisions; the gap file records revision)
+    gaps_dir = project.path / "gaps"
+    known_gap_ids: set[str] = set()
+    if gaps_dir.is_dir():
+        for f in sorted(gaps_dir.glob("gaps-rev-*.jsonl")):
+            for line in f.read_text(encoding="utf-8").splitlines():
+                if line.strip():
+                    rec = json.loads(line)
+                    known_gap_ids.add(rec["gap_id"])
+                    # gap must be derived from the current graph revision
+                    if rec["gap_id"] in gap_ids and rec.get(
+                            "derived_from_graph_revision") != project.current_revision():
+                        errors.append(
+                            f"gap {rec['gap_id']} derives from revision "
+                            f"{rec.get('derived_from_graph_revision')} but the "
+                            f"project is at revision {project.current_revision()}")
+    missing = [g for g in gap_ids if g not in known_gap_ids]
+    if missing:
+        errors.append(f"design references unknown gaps: {missing}")
+    return errors
+
+
+def save_study_design(project: ProjectWorkspace, design: dict) -> Path:
+    """Persist a StudyDesign under study-designs/ (never rewritten)."""
+    errors = validate_design_grounding(project, design)
+    if errors:
+        raise ValueError("design fails grounding gate:\n- " + "\n- ".join(errors))
+    path = project.path / "study-designs" / f"{design['design_id']}.json"
+    if path.exists():
+        raise FileExistsError(f"study design already exists: {path}")
+    path.write_text(json.dumps(design, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8")
+    return path
+
+
+def save_analysis_plan(project: ProjectWorkspace, plan: dict) -> Path:
+    """Persist an AnalysisPlan under study-designs/ (or analyses/)."""
+    errors = validate_record("analysis-plan", plan)
+    if errors:
+        raise ValueError(f"invalid analysis plan: {errors}")
+    path = project.path / "analyses" / f"{plan['analysis_plan_id']}.json"
+    if path.exists():
+        raise FileExistsError(f"analysis plan already exists: {path}")
+    path.write_text(json.dumps(plan, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8")
+    return path