eduevidence 6.0.0 → 6.2.0

package/engine/orchestration.py

@@ -75,8 +75,8 @@ class RoleSpec:
 
 
 ROLE_REGISTRY: dict[str, RoleSpec] = {
-    "education-planner": RoleSpec(
-        "education-planner",
+    "research-planner": RoleSpec(
+        "research-planner",
         "Own framing completeness, scope, comparison and outcome definition.",
         ("frame",),
         ("research-planning",),
@@ -409,7 +409,7 @@ class ExecutionPlanner:
 
     def _serial_tasks(self, run_id, base_revision) -> tuple[TaskSpec, ...]:
         return (
-            self._base("frame", "frame", "education-planner", "Structure the research question.", "frame", run_id=run_id, base_revision=base_revision),
+            self._base("frame", "frame", "research-planner", "Structure the research question.", "frame", run_id=run_id, base_revision=base_revision),
             self._base("retrieve", "retrieve", "evidence-retriever", "Acquire bounded evidence.", "direct+counter", run_id=run_id, base_revision=base_revision),
             self._base("extract", "extract", "evidence-analyst", "Extract structured findings.", "all-eligible", run_id=run_id, base_revision=base_revision),
             self._base("challenge", "challenge", "skeptic", "Challenge the provisional interpretation.", "counter-evidence", run_id=run_id, base_revision=base_revision),
@@ -419,7 +419,7 @@ class ExecutionPlanner:
 
     def _medium_tasks(self, run_id, base_revision) -> tuple[TaskSpec, ...]:
         return (
-            self._base("frame", "frame", "education-planner", "Structure the research question.", "frame", run_id=run_id, base_revision=base_revision),
+            self._base("frame", "frame", "research-planner", "Structure the research question.", "frame", run_id=run_id, base_revision=base_revision),
             self._base("retrieve-direct", "retrieve", "evidence-retriever", "Retrieve direct decision-relevant evidence.", "direct-causal", run_id=run_id, base_revision=base_revision, delegated=True, outputs=("SourceCandidates",)),
             self._base("retrieve-counter", "retrieve", "evidence-retriever", "Retrieve null, negative and contradictory evidence.", "counter-risk", run_id=run_id, base_revision=base_revision, delegated=True, outputs=("SourceCandidates",)),
             self._base("extract", "extract", "evidence-analyst", "Merge validated sources and extract findings.", "all-eligible", run_id=run_id, base_revision=base_revision),
@@ -430,7 +430,7 @@ class ExecutionPlanner:
 
     def _deep_tasks(self, run_id, base_revision) -> tuple[TaskSpec, ...]:
         return (
-            self._base("frame", "frame", "education-planner", "Structure the research question.", "frame", run_id=run_id, base_revision=base_revision),
+            self._base("frame", "frame", "research-planner", "Structure the research question.", "frame", run_id=run_id, base_revision=base_revision),
             self._base("retrieve-direct", "retrieve", "evidence-retriever", "Retrieve direct causal evidence.", "direct-causal", run_id=run_id, base_revision=base_revision, delegated=True, outputs=("SourceCandidates",)),
             self._base("retrieve-transfer", "retrieve", "evidence-retriever", "Retrieve retention and independent-transfer evidence.", "transfer-retention", run_id=run_id, base_revision=base_revision, delegated=True, outputs=("SourceCandidates",)),
             self._base("retrieve-counter", "retrieve", "evidence-retriever", "Retrieve null, negative, risk and contradiction evidence.", "counter-risk", run_id=run_id, base_revision=base_revision, delegated=True, outputs=("SourceCandidates",)),

package/engine/paths.py

@@ -4,6 +4,8 @@ EDUEVIDENCE_HOME (default `~/.eduevidence`) is the root that owns the Shared
 Research Library and all Projects. An explicit path always wins.
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 import os
 

package/engine/pilot.py

@@ -22,6 +22,7 @@ from engine.datasets import analysis_blocked_by_privacy, derive_csv_profile, ing
 from engine.graph_store import GraphMutation, GraphStore
 from engine.ids import new_local_id, new_run_id
 from engine.project import ProjectWorkspace
+from engine.taxonomy import category_of, tokens as taxonomy_tokens
 from engine.synthesis import synthesize_project
 from engine.tribunal import adjudicate, decision_diff, save_decision_snapshot
 from engine.versions import (
@@ -30,15 +31,21 @@ from engine.versions import (
     SOURCE_VALIDATION_POLICY_VERSION,
 )
 
-#: Outcome Taxonomy tokens that pilots may measure (mirrors outcome-taxonomy.md).
-OUTCOME_TAXONOMY = {
-    "knowledge_gain", "concept_understanding", "retention", "transfer",
-    "independent_problem_solving", "completion_time", "accuracy",
-    "code_quality", "assignment_score", "engagement", "motivation",
-    "cognitive_load", "help_seeking", "metacognition", "ai_dependency",
-    "over_reliance", "reduced_effort", "reduced_transfer",
-    "academic_integrity_risk", "false_confidence",
-}
+def outcome_taxonomy_tokens(domain: str = "education") -> set[str]:
+    """Outcome tokens a pilot may measure, read from the domain registry.
+
+    This was a module-level set of the 20 education tokens, so a policy pilot
+    could not register at all. The domain registry (via engine/taxonomy.py) is
+    now the single authority.
+    """
+    return set(taxonomy_tokens(domain))
+
+
+def project_domain(project: ProjectWorkspace) -> str:
+    """The domain a project registers; defaults to education when absent."""
+    manifest = project.manifest()
+    return str(manifest.get("domain") or "education")
+
 
 PILOT_STATUSES = ("registered", "data_imported", "analyzed", "adjudicated")
 
@@ -49,22 +56,6 @@ PII_COLUMN_HINTS = ("name", "student", "学号", "姓名", "email", "mail",
 _DECISION_IMPLICATION = {"support": "support_adoption",
                          "contradict": "oppose_adoption", "neutral": "neutral"}
 
-#: Outcome Taxonomy token -> graph outcome category enum (schemas/v2/outcome).
-_OUTCOME_CATEGORY = {
-    "knowledge_gain": "learning", "concept_understanding": "learning",
-    "retention": "learning", "transfer": "learning",
-    "independent_problem_solving": "learning",
-    "completion_time": "task_performance", "accuracy": "task_performance",
-    "code_quality": "task_performance", "assignment_score": "task_performance",
-    "engagement": "process", "motivation": "process",
-    "cognitive_load": "process", "help_seeking": "process",
-    "metacognition": "process",
-    "ai_dependency": "risk", "over_reliance": "risk",
-    "reduced_effort": "risk", "reduced_transfer": "risk",
-    "academic_integrity_risk": "risk", "false_confidence": "risk",
-}
-
-
 def _now_iso() -> str:
     return datetime.now(timezone.utc).isoformat()
 
@@ -111,10 +102,13 @@ def register_pilot(project: ProjectWorkspace, *,
         raise ValueError(
             f"decision snapshot {decision_snapshot_id} not found in this project; "
             "a pilot must bind to a real adjudication")
-    unknown = [o for o in outcome_columns if o not in OUTCOME_TAXONOMY]
+    domain = project_domain(project)
+    known_tokens = outcome_taxonomy_tokens(domain)
+    unknown = [o for o in outcome_columns if o not in known_tokens]
     if unknown:
         raise ValueError(
-            f"outcome_columns outside Outcome Taxonomy: {sorted(unknown)}")
+            f"outcome_columns outside the {domain} Outcome Taxonomy: "
+            f"{sorted(unknown)}")
     if not conditions or sample_size < 1:
         raise ValueError("conditions must be non-empty and sample_size >= 1")
     if anon_policy.get("no_pii_columns") is not True:
@@ -208,7 +202,13 @@ def link_analysis(project: ProjectWorkspace, pilot_id: str, *,
     return pilot
 
 
-def _ensure_outcome(store: GraphStore, outcome_id: str) -> dict:
+def _ensure_outcome(store: GraphStore, outcome_id: str, domain: str) -> dict:
+    """Create the pilot outcome row, classified by the DOMAIN registry.
+
+    ``category_of`` raises for an unregistered token; the caller has already
+    validated the token against ``outcome_taxonomy_tokens(domain)``, so an
+    error here means the two disagreed and must not be silently absorbed.
+    """
     existing = store.get("outcomes", outcome_id)
     if existing:
         return existing
@@ -216,7 +216,7 @@ def _ensure_outcome(store: GraphStore, outcome_id: str) -> dict:
     return {
         "outcome_id": outcome_id,
         "name": token,
-        "outcome_type": _OUTCOME_CATEGORY.get(token, "learning"),
+        "outcome_type": category_of(domain, token),
         "extensions": {"pilot_outcome": True},
     }
 
@@ -237,9 +237,11 @@ def redecide(project: ProjectWorkspace, pilot_id: str, *,
         raise ValueError(f"invalid effect_direction {effect_direction!r}")
     if relation_to_claim not in ("support", "contradict", "neutral"):
         raise ValueError(f"invalid relation_to_claim {relation_to_claim!r}")
-    if outcome_token not in OUTCOME_TAXONOMY:
+    domain = project_domain(project)
+    if outcome_token not in outcome_taxonomy_tokens(domain):
         raise ValueError(
-            f"outcome_token {outcome_token!r} outside Outcome Taxonomy")
+            f"outcome_token {outcome_token!r} outside the {domain} "
+            "Outcome Taxonomy")
     outcome_id = f"OUT-{outcome_token}"
     pilot = _load_pilot(project, pilot_id)
     if pilot["status"] not in ("analyzed", "data_imported"):
@@ -282,7 +284,7 @@ def redecide(project: ProjectWorkspace, pilot_id: str, *,
         "identity_status": "resolved",
         "extensions": {"pilot_id": pilot_id},
     }
-    outcome = _ensure_outcome(store, outcome_id)
+    outcome = _ensure_outcome(store, outcome_id, domain)
     estimate = None
     if effect_estimate is not None:
         estimate = {

package/engine/taxonomy.py

@@ -0,0 +1,211 @@
+"""engine/taxonomy.py - Outcome taxonomy authority (domain registry backed).
+
+Every domain registers its own outcome taxonomy in
+``domains/<id>/outcome_taxonomy.json``. Each file declares the domain category
+buckets (``categories``) and one entry per outcome token carrying an explicit
+``category`` (``tokens[].category``).
+
+This module is the ONLY reader of that contract. Before it existed, the token
+set and the token-to-category mapping were hard-coded in ``engine/pilot.py``
+with a ``.get(token, "learning")`` fallback, so a policy outcome was silently
+classified as a learning outcome and policy runs could not complete. Callers
+must no longer keep private copies of either table.
+
+Fail-closed rule: an unknown token or an unregistered domain raises. Silent
+classification is what produced the original defect; unknown input must be
+visible as an error, never absorbed into a default bucket.
+
+Stdlib only; results are cached per process.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Iterable
+
+from engine.evidencecore import list_domains, load_domain
+
+#: Bucket used when a caller must render an outcome whose category could not be
+#: resolved. It is deliberately not a domain category: it marks the value as
+#: unclassified instead of pretending it belongs to a real bucket.
+UNCLASSIFIED = "unclassified"
+
+_cache: dict[str, Any] = {}
+
+
+class TaxonomyError(ValueError):
+    """Raised when taxonomy data is missing, malformed, or unknown."""
+
+
+def _taxonomy_path(domain_id: str) -> str:
+    """Registered relative path of a domain taxonomy file."""
+    entry = load_domain(domain_id)
+    raw = entry.get("outcome_taxonomy")
+    if not raw:
+        raise TaxonomyError(
+            "domain " + repr(domain_id) + " registers no outcome_taxonomy")
+    return str(raw).partition("#")[0]
+
+
+def _load(domain_id: str) -> dict:
+    """Load (and cache) one domain taxonomy, validating its shape."""
+    key = "taxonomy:" + domain_id
+    if key in _cache:
+        return _cache[key]
+    from engine._resources import resource_root
+
+    path = resource_root() / _taxonomy_path(domain_id)
+    if not path.is_file():
+        raise TaxonomyError(
+            "domain " + repr(domain_id) + ": taxonomy file missing: " + str(path))
+    data = json.loads(path.read_text(encoding="utf-8"))
+    categories = data.get("categories")
+    tokens = data.get("tokens")
+    if not isinstance(categories, dict) or not categories:
+        raise TaxonomyError(
+            "domain " + repr(domain_id) + ": taxonomy declares no categories")
+    if not isinstance(tokens, list) or not tokens:
+        raise TaxonomyError(
+            "domain " + repr(domain_id) + ": taxonomy declares no tokens")
+    seen: set[str] = set()
+    for item in tokens:
+        if not isinstance(item, dict) or not item.get("id"):
+            raise TaxonomyError(
+                "domain " + repr(domain_id) + ": token entry without an id")
+        token = str(item["id"])
+        if token in seen:
+            raise TaxonomyError(
+                "domain " + repr(domain_id) + ": duplicate token " + repr(token))
+        seen.add(token)
+        category = item.get("category")
+        if not category:
+            raise TaxonomyError(
+                "domain " + repr(domain_id) + ": token " + repr(token)
+                + " declares no category (silent defaults are forbidden)")
+        if str(category) not in categories:
+            raise TaxonomyError(
+                "domain " + repr(domain_id) + ": token " + repr(token)
+                + " uses category " + repr(category) + " absent from "
+                + repr(sorted(categories)))
+    _cache[key] = data
+    return data
+
+
+def _domain_ids(domain_id: str | None = None) -> tuple[str, ...]:
+    if domain_id:
+        return (domain_id,)
+    return tuple(d["id"] for d in list_domains())
+
+
+def tokens(domain_id: str) -> tuple[str, ...]:
+    """Outcome tokens declared by one domain, in registry order."""
+    return tuple(str(item["id"]) for item in _load(domain_id)["tokens"])
+
+
+def categories(domain_id: str) -> dict[str, dict]:
+    """Category buckets declared by one domain (id -> descriptor)."""
+    return dict(_load(domain_id)["categories"])
+
+
+def category_of(domain_id: str, token: str) -> str:
+    """Category bucket for a token in a domain.
+
+    Raises TaxonomyError for an unknown token: a caller that cannot classify a
+    value must surface that, not guess. Use category_of_or_unclassified at
+    rendering boundaries where an unclassified value is acceptable.
+    """
+    for item in _load(domain_id)["tokens"]:
+        if str(item["id"]) == token:
+            return str(item["category"])
+    raise TaxonomyError(
+        "domain " + repr(domain_id) + ": unknown outcome token " + repr(token)
+        + " (" + str(len(tokens(domain_id))) + " tokens known)")
+
+
+def category_of_or_unclassified(domain_id: str, token: str) -> str:
+    """Rendering-safe variant: unknown tokens map to UNCLASSIFIED."""
+    try:
+        return category_of(domain_id, token)
+    except TaxonomyError:
+        return UNCLASSIFIED
+
+
+def category_labels(domain_id: str, lang: str = "zh") -> dict[str, str]:
+    """Display label per category bucket (falls back to the category id)."""
+    suffix = "_en" if lang == "en" else "_zh"
+    out: dict[str, str] = {}
+    for key, descriptor in categories(domain_id).items():
+        if isinstance(descriptor, dict):
+            label = descriptor.get("name" + suffix) or descriptor.get("name")
+            out[key] = str(label or key)
+        else:
+            out[key] = key
+    return out
+
+
+def all_tokens() -> dict[str, str]:
+    """Every registered token -> owning domain, across registered domains.
+
+    A token registered by two domains is a contract conflict and raises: the
+    token would otherwise mean different things depending on lookup order.
+    """
+    key = "all_tokens"
+    if key in _cache:
+        return _cache[key]
+    out: dict[str, str] = {}
+    for domain_id in _domain_ids():
+        for token in tokens(domain_id):
+            owner = out.get(token)
+            if owner is not None and owner != domain_id:
+                raise TaxonomyError(
+                    "outcome token " + repr(token) + " is registered by both "
+                    + repr(owner) + " and " + repr(domain_id))
+            out[token] = domain_id
+    _cache[key] = out
+    return out
+
+
+def domain_of(token: str, default: str = "education") -> str:
+    """Owning domain for a token; default when the token is unregistered."""
+    return all_tokens().get(token, default)
+
+
+def all_tokens_ordered() -> tuple[str, ...]:
+    """Every registered token in domain-registry then taxonomy order."""
+    ordered: list[str] = []
+    for domain_id in _domain_ids():
+        ordered.extend(tokens(domain_id))
+    return tuple(ordered)
+
+
+def all_categories() -> tuple[str, ...]:
+    """Every category bucket across domains, de-duplicated, order preserved."""
+    ordered: list[str] = []
+    for domain_id in _domain_ids():
+        for name in categories(domain_id):
+            if name not in ordered:
+                ordered.append(name)
+    return tuple(ordered)
+
+
+def categories_for_tokens(
+    token_list: Iterable[str], domain_id: str = "education"
+) -> dict[str, list[str]]:
+    """Group tokens by category; unregistered tokens land in UNCLASSIFIED."""
+    grouped: dict[str, list[str]] = {}
+    for token in token_list:
+        bucket = category_of_or_unclassified(domain_id, token)
+        grouped.setdefault(bucket, []).append(token)
+    return grouped
+
+
+def reset_cache() -> None:
+    """Drop memoised taxonomies (tests and long-lived processes)."""
+    _cache.clear()
+
+
+__all__ = [
+    "UNCLASSIFIED", "TaxonomyError",
+    "tokens", "categories", "category_of", "category_of_or_unclassified",
+    "category_labels", "all_tokens", "all_tokens_ordered", "all_categories",
+    "categories_for_tokens", "domain_of", "reset_cache",
+]

package/engine/tribunal.py

@@ -38,6 +38,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from engine.contracts import validate_record
+from engine.decision_policy import (
+    ADOPT_DIRECTNESS,
+    decision_action as _policy_decision_action,
+    outcome_category,
+    primary_effect_categories,
+)
 from engine.graph_store import GraphStore
 from engine.ids import new_local_id
 from engine.project import ProjectWorkspace
@@ -230,16 +236,18 @@ def _confidence(store: GraphStore, syntheses: tuple[ClaimSynthesis, ...]) -> dic
             "decisive_relations": dict(decisive)}
 
 
-def _has_direct_learning_evidence(store: GraphStore,
-                                  decisive_relations: dict[str, str]) -> bool:
-    """True when at least one decisive support_adoption Study measures a
-    learning outcome directly.
+def _has_direct_primary_evidence(store: GraphStore,
+                                 decisive_relations: dict[str, str],
+                                 domain: str = "education") -> bool:
+    """True when a decisive support_adoption Study measures a primary outcome.
 
-    Learning evidence means the finding's outcome is declared
-    outcome_type == "learning" AND its evidence link carries directness == 2.
-    Task performance / process / risk outcomes never qualify, and a missing
-    outcome record or missing directness fails closed (False).
+    Primary means the finding's outcome_type maps — through the domain
+    registry — into one of :func:`primary_effect_categories` (education:
+    learning; policy: effectiveness/cost), AND its evidence link carries
+    directness == 2. Task-performance, process and risk outcomes never
+    qualify, and a missing outcome record or missing directness fails closed.
     """
+    primary = primary_effect_categories(domain)
     findings = {f["finding_id"]: f for f in store.read_table("findings")}
     outcomes = {o["outcome_id"]: o for o in store.read_table("outcomes")}
     links_by_finding: dict[str, list[dict]] = {}
@@ -254,37 +262,37 @@ def _has_direct_learning_evidence(store: GraphStore,
         if fnd.get("study_id") not in support_studies:
             continue
         outcome = outcomes.get(fnd.get("outcome_id"))
-        if outcome is None or outcome.get("outcome_type") != "learning":
+        if outcome is None:
+            continue
+        value = str(outcome.get("outcome_type") or "")
+        category = outcome_category(domain, value, primary)
+        # Unknown value: fail closed rather than treating it as
+        # decision-grade evidence.
+        if category is None:
+            continue
+        if category not in primary:
             continue
         for link in links_by_finding.get(fid, []):
             directness = link.get("directness")
-            if isinstance(directness, (int, float)) and int(directness) == 2:
+            if (isinstance(directness, (int, float))
+                    and int(directness) == ADOPT_DIRECTNESS):
                 return True
     return False
 
 
 def _decision_action(syn_statuses: dict[str, str], confidence: dict,
                      decisive_relations: dict[str, str],
-                     has_direct_learning_evidence: bool = False) -> str:
-    """Gate-enforced decision action.
-
-    REJECT requires usable direct opposition evidence (an independent Study
-    folded to oppose_adoption). Low/Insufficient can never yield ADOPT.
-    ADOPT additionally requires direct learning/transfer evidence: High +
-    decisive support WITHOUT a direct learning outcome downgrades to PILOT
-    (task performance / procedural efficiency is not learning). Moderate +
-    decisive support → PILOT; otherwise INSUFFICIENT_EVIDENCE.
+                     has_direct_primary_evidence: bool = False) -> str:
+    """Gate-enforced decision action; rule lives in engine.decision_policy.
+
+    The V1 Pre-Verdict Gate enforces the same rule, so the thresholds are
+    imported rather than restated here.
     """
-    label = confidence["label"]
-    has_oppose = any(r == "oppose_adoption" for r in decisive_relations.values())
-    has_support = any(r == "support_adoption" for r in decisive_relations.values())
-    if has_oppose:
-        return "REJECT"
-    if label == "High" and has_support and has_direct_learning_evidence:
-        return "ADOPT"
-    if label in ("High", "Moderate") and has_support:
-        return "PILOT"
-    return "INSUFFICIENT_EVIDENCE"
+    return _policy_decision_action(
+        confidence_label=confidence["label"],
+        decisive_relations=decisive_relations,
+        has_direct_primary_evidence=has_direct_primary_evidence,
+    )
 
 
 
@@ -299,10 +307,11 @@ def adjudicate(store: GraphStore, *, project: ProjectWorkspace,
 
     syn_statuses = {s.claim_id: s.status for s in syntheses}
     decisive_relations = confidence.get("decisive_relations", {})
-    direct_learning = _has_direct_learning_evidence(store, decisive_relations)
+    domain = str(project.manifest().get("domain") or "education")
+    direct_learning = _has_direct_primary_evidence(store, decisive_relations, domain)
 
     decision = _decision_action(syn_statuses, confidence, decisive_relations,
-                                has_direct_learning_evidence=direct_learning)
+                                has_direct_primary_evidence=direct_learning)
 
     key_links: list[str] = []
     for syn in syntheses:
@@ -351,6 +360,9 @@ def adjudicate(store: GraphStore, *, project: ProjectWorkspace,
         "extensions": {"confidence_components": {
             "decisive_studies": confidence.get("decisive_studies", 0),
             "usable_studies": confidence.get("usable_studies", 0),
+            "has_direct_primary_evidence": direct_learning,
+            # Backward-compatible alias under the education-era name,
+            # so readers written against the older contract keep working.
             "has_direct_learning_evidence": direct_learning,
         }},
     }

package/engine/versions.py

@@ -4,7 +4,7 @@ Policy versions are frozen identifiers, not free-form strings: changing a
 policy requires a new version, never silent mutation of an existing one.
 """
 
-ENGINE_VERSION = "6.0.0"
+ENGINE_VERSION = "6.2.0"
 GRAPH_SCHEMA_VERSION = "2.0"
 SOURCE_VALIDATION_POLICY_VERSION = "2026-08-12.v2"
 METHODOLOGY_POLICY_VERSION = "2026-08-12.v2"