eduevidence 5.2.0 → 6.2.0

package/engine/orchestration.py

@@ -0,0 +1,460 @@
+"""Canonical orchestration primitives for EduEvidence.
+
+Protocol stage, scientific role, capability, worker/subagent, and model/CLI are
+separate concepts. A RoleSpec describes scientific responsibility; a TaskSpec
+is one bounded execution contract; an ExecutionPlan states sequencing and
+parallel groups. Runtime model/CLI selection remains an adapter concern.
+
+Scientific rule: workers produce staging artifacts only. Canonical project
+state is committed by the single-writer lead path after validation.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any, Iterable
+
+
+class Complexity(str, Enum):
+    S = "S"
+    M = "M"
+    L = "L"
+
+
+class ExecutionMode(str, Enum):
+    LOCAL = "local"
+    DELEGATED = "delegated"
+
+
+CANONICAL_STAGES = (
+    "frame",
+    "retrieve",
+    "extract",
+    "challenge",
+    "audit",
+    "adjudicate",
+    "applicability",
+    "intervene",
+    "evaluate",
+)
+
+CANONICAL_STATE_ARTIFACTS = frozenset({
+    "EvidenceGraph",
+    "GraphRevision",
+    "DecisionSnapshot",
+    "KnowledgeGap",
+    "StudyDesign",
+    "PilotRun",
+    "AnalysisRun",
+})
+
+DEFAULT_FORBIDDEN_WORKER_ACTIONS = (
+    "canonical_state_write",
+    "decision_promotion",
+    "recursive_worker_spawn",
+    "evaluator_mutation",
+)
+
+
+@dataclass(frozen=True)
+class RoleSpec:
+    """A scientific responsibility, not an instruction to spawn an agent."""
+
+    name: str
+    responsibility: str
+    stages: tuple[str, ...]
+    capabilities: tuple[str, ...]
+    independence_required: bool = False
+    critical_path: bool = False
+
+    def __post_init__(self) -> None:
+        unknown = set(self.stages) - set(CANONICAL_STAGES)
+        if unknown:
+            raise ValueError(f"role {self.name!r} references unknown stages: {sorted(unknown)}")
+
+
+ROLE_REGISTRY: dict[str, RoleSpec] = {
+    "research-planner": RoleSpec(
+        "research-planner",
+        "Own framing completeness, scope, comparison and outcome definition.",
+        ("frame",),
+        ("research-planning",),
+        critical_path=True,
+    ),
+    "evidence-retriever": RoleSpec(
+        "evidence-retriever",
+        "Acquire candidate sources and record verifiable provenance without adjudicating them.",
+        ("retrieve",),
+        ("literature-review", "full-text-fetch", "source-validation"),
+    ),
+    "evidence-analyst": RoleSpec(
+        "evidence-analyst",
+        "Extract structured study findings without deciding what the evidence body means.",
+        ("extract",),
+        ("evidence-extraction",),
+    ),
+    "skeptic": RoleSpec(
+        "skeptic",
+        "Own independent counter-evidence and alternative-explanation coverage.",
+        ("challenge",),
+        ("contradiction-analysis", "counter-retrieval"),
+        independence_required=True,
+        critical_path=True,
+    ),
+    "method-reviewer": RoleSpec(
+        "method-reviewer",
+        "Own study-level methodology appraisal and evidence-quality limitations.",
+        ("audit",),
+        ("methodology-audit",),
+        independence_required=True,
+        critical_path=True,
+    ),
+    "evidence-judge": RoleSpec(
+        "evidence-judge",
+        "Own the bounded decision after evidence, challenge and audit gates pass.",
+        ("adjudicate", "applicability"),
+        ("evidence-review", "decision-adjudication", "applicability"),
+        critical_path=True,
+    ),
+    "intervention-designer": RoleSpec(
+        "intervention-designer",
+        "Turn a grounded decision and KnowledgeGap into a bounded intervention or pilot.",
+        ("intervene",),
+        ("study-design", "intervention-design"),
+    ),
+    "evaluation-designer": RoleSpec(
+        "evaluation-designer",
+        "Define estimable evaluation, retention/transfer measurement and update logic.",
+        ("evaluate",),
+        ("evaluation-design", "data-analysis"),
+    ),
+}
+
+
+@dataclass(frozen=True)
+class TaskSpec:
+    """One bounded scientific task; delegation requires full runtime context."""
+
+    task_id: str
+    stage: str
+    role: str
+    objective: str
+    evidence_axis: str
+    run_id: str | None = None
+    base_revision: int | None = None
+    role_profile: str | None = None
+    reason_for_delegation: str | None = None
+    inputs: tuple[str, ...] = ()  # legacy alias kept during migration
+    input_artifacts: tuple[str, ...] = ()
+    allowed_capabilities: tuple[str, ...] = ()
+    forbidden_actions: tuple[str, ...] = DEFAULT_FORBIDDEN_WORKER_ACTIONS
+    scope: dict[str, Any] = field(default_factory=dict)
+    budget: dict[str, Any] = field(default_factory=dict)
+    expected_outputs: tuple[str, ...] = ()
+    output_contract: dict[str, Any] = field(default_factory=dict)
+    termination: dict[str, Any] = field(default_factory=dict)
+    execution_mode: ExecutionMode = ExecutionMode.LOCAL
+    independent: bool = False
+    read_only: bool = True
+    timeout_seconds: int = 1800
+    token_budget: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self) -> None:
+        if not self.task_id.strip():
+            raise ValueError("task_id must be non-empty")
+        if self.stage not in CANONICAL_STAGES:
+            raise ValueError(f"unknown protocol stage: {self.stage!r}")
+        spec = ROLE_REGISTRY.get(self.role)
+        if spec is None:
+            raise ValueError(f"unknown scientific role: {self.role!r}")
+        if self.stage not in spec.stages:
+            raise ValueError(
+                f"role {self.role!r} does not own stage {self.stage!r}; owns {spec.stages}"
+            )
+        if self.role_profile not in (None, self.role):
+            raise ValueError("role_profile must identify the same scientific role")
+        if not self.objective.strip():
+            raise ValueError("objective must be non-empty")
+        if not self.evidence_axis.strip():
+            raise ValueError("evidence_axis must be non-empty")
+        if self.base_revision is not None and self.base_revision < 0:
+            raise ValueError("base_revision must be >= 0")
+        if self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        if self.token_budget is not None and self.token_budget <= 0:
+            raise ValueError("token_budget must be positive when provided")
+        unknown_caps = set(self.allowed_capabilities) - set(spec.capabilities)
+        if unknown_caps:
+            raise ValueError(
+                f"task grants capabilities outside role {self.role!r}: {sorted(unknown_caps)}"
+            )
+        forbidden = CANONICAL_STATE_ARTIFACTS.intersection(self.expected_outputs)
+        if self.execution_mode is ExecutionMode.DELEGATED:
+            if not self.read_only:
+                raise ValueError("delegated workers must be read-only against canonical state")
+            if forbidden:
+                raise ValueError(
+                    "delegated workers may only return staging artifacts; canonical outputs forbidden: "
+                    f"{sorted(forbidden)}"
+                )
+            if "canonical_state_write" not in self.forbidden_actions:
+                raise ValueError("delegated TaskSpec must explicitly forbid canonical_state_write")
+            if spec.independence_required and not self.independent:
+                raise ValueError(f"role {self.role!r} requires independent delegated execution")
+
+    def validate_for_dispatch(self) -> None:
+        self.validate()
+        if self.execution_mode is not ExecutionMode.DELEGATED:
+            raise ValueError("only delegated TaskSpecs may be dispatched")
+        if not self.run_id or not self.run_id.strip():
+            raise ValueError("delegated TaskSpec requires run_id")
+        if self.base_revision is None:
+            raise ValueError("delegated TaskSpec requires base_revision")
+        if not self.reason_for_delegation or not self.reason_for_delegation.strip():
+            raise ValueError("delegated TaskSpec requires reason_for_delegation")
+        if not self.allowed_capabilities:
+            raise ValueError("delegated TaskSpec requires explicit allowed_capabilities")
+        if not self.output_contract:
+            raise ValueError("delegated TaskSpec requires output_contract")
+        if not self.termination:
+            raise ValueError("delegated TaskSpec requires termination contract")
+
+    def to_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["execution_mode"] = self.execution_mode.value
+        return value
+
+    def to_prompt_contract(self) -> str:
+        """Produce a stable, explicit worker envelope."""
+        self.validate_for_dispatch()
+        return (
+            f"TASK_ID: {self.task_id}\n"
+            f"RUN_ID: {self.run_id}\n"
+            f"BASE_GRAPH_REVISION: {self.base_revision}\n"
+            f"STAGE: {self.stage}\n"
+            f"SCIENTIFIC_ROLE: {self.role}\n"
+            f"EVIDENCE_AXIS: {self.evidence_axis}\n"
+            f"OBJECTIVE: {self.objective}\n"
+            f"REASON_FOR_DELEGATION: {self.reason_for_delegation}\n"
+            f"ALLOWED_CAPABILITIES: {', '.join(self.allowed_capabilities)}\n"
+            f"FORBIDDEN_ACTIONS: {', '.join(self.forbidden_actions)}\n"
+            f"INPUT_ARTIFACTS: {', '.join(self.input_artifacts or self.inputs) if (self.input_artifacts or self.inputs) else 'none'}\n"
+            f"SCOPE_JSON: {json.dumps(self.scope, ensure_ascii=False, sort_keys=True)}\n"
+            f"BUDGET_JSON: {json.dumps(self.budget, ensure_ascii=False, sort_keys=True)}\n"
+            f"OUTPUT_CONTRACT_JSON: {json.dumps(self.output_contract, ensure_ascii=False, sort_keys=True)}\n"
+            f"TERMINATION_JSON: {json.dumps(self.termination, ensure_ascii=False, sort_keys=True)}\n"
+            "CANONICAL_STATE_WRITE: FORBIDDEN\n"
+            "Return only the requested staging artifact(s)."
+        )
+
+
+@dataclass(frozen=True)
+class ExecutionPlan:
+    complexity: Complexity
+    tasks: tuple[TaskSpec, ...]
+    max_parallel_workers: int
+    parallel_groups: tuple[tuple[str, ...], ...] = ()
+    plan_id: str | None = None
+
+    @property
+    def delegated_tasks(self) -> tuple[TaskSpec, ...]:
+        return tuple(t for t in self.tasks if t.execution_mode is ExecutionMode.DELEGATED)
+
+    def validate(self) -> None:
+        if self.max_parallel_workers < 0:
+            raise ValueError("max_parallel_workers cannot be negative")
+        if self.max_parallel_workers > 6:
+            raise ValueError("bounded worker pool exceeds hard limit of 6")
+        ids: set[str] = set()
+        by_id: dict[str, TaskSpec] = {}
+        for task in self.tasks:
+            task.validate()
+            if task.task_id in ids:
+                raise ValueError(f"duplicate task id: {task.task_id}")
+            ids.add(task.task_id)
+            by_id[task.task_id] = task
+        if self.delegated_tasks and self.max_parallel_workers < 1:
+            raise ValueError("delegated plan requires max_parallel_workers >= 1")
+
+        grouped: list[str] = []
+        for group in self.parallel_groups:
+            if not group:
+                raise ValueError("parallel groups may not be empty")
+            if len(group) > self.max_parallel_workers:
+                raise ValueError("parallel group exceeds max_parallel_workers")
+            for task_id in group:
+                task = by_id.get(task_id)
+                if task is None:
+                    raise ValueError(f"parallel group references unknown task {task_id}")
+                if task.execution_mode is not ExecutionMode.DELEGATED:
+                    raise ValueError(f"parallel group may contain delegated tasks only: {task_id}")
+                grouped.append(task_id)
+        delegated_ids = [task.task_id for task in self.delegated_tasks]
+        if sorted(grouped) != sorted(delegated_ids):
+            raise ValueError("every delegated task must appear exactly once in parallel_groups")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "plan_id": self.plan_id,
+            "complexity": self.complexity.value,
+            "tasks": [task.to_dict() for task in self.tasks],
+            "max_parallel_workers": self.max_parallel_workers,
+            "parallel_groups": [list(group) for group in self.parallel_groups],
+        }
+
+
+class ExecutionPlanner:
+    """Deterministic policy planner; it never chooses a concrete model/CLI."""
+
+    def plan(
+        self,
+        complexity: str | Complexity,
+        *,
+        run_id: str | None = None,
+        base_revision: int | None = None,
+        plan_id: str | None = None,
+    ) -> ExecutionPlan:
+        level = complexity if isinstance(complexity, Complexity) else Complexity(complexity.upper())
+        if level is Complexity.S:
+            plan = ExecutionPlan(
+                level,
+                self._serial_tasks(run_id, base_revision),
+                max_parallel_workers=0,
+                parallel_groups=(),
+                plan_id=plan_id,
+            )
+        elif level is Complexity.M:
+            tasks = self._medium_tasks(run_id, base_revision)
+            plan = ExecutionPlan(
+                level,
+                tasks,
+                max_parallel_workers=2,
+                parallel_groups=(("retrieve-direct", "retrieve-counter"), ("challenge",)),
+                plan_id=plan_id,
+            )
+        else:
+            tasks = self._deep_tasks(run_id, base_revision)
+            plan = ExecutionPlan(
+                level,
+                tasks,
+                max_parallel_workers=4,
+                parallel_groups=(
+                    (
+                        "retrieve-direct",
+                        "retrieve-transfer",
+                        "retrieve-counter",
+                        "retrieve-applicability",
+                    ),
+                    ("challenge", "audit"),
+                ),
+                plan_id=plan_id,
+            )
+        plan.validate()
+        return plan
+
+    @staticmethod
+    def _base(
+        task_id: str,
+        stage: str,
+        role: str,
+        objective: str,
+        axis: str,
+        *,
+        run_id: str | None,
+        base_revision: int | None,
+        delegated: bool = False,
+        independent: bool = False,
+        outputs: Iterable[str] = (),
+    ) -> TaskSpec:
+        role_spec = ROLE_REGISTRY[role]
+        timeout_seconds = 1800
+        token_budget = None
+        outputs = tuple(outputs)
+        return TaskSpec(
+            task_id=task_id,
+            stage=stage,
+            role=role,
+            role_profile=role,
+            objective=objective,
+            evidence_axis=axis,
+            run_id=run_id,
+            base_revision=base_revision,
+            reason_for_delegation=(
+                f"independent bounded {axis} work benefits from delegated context"
+                if delegated
+                else None
+            ),
+            allowed_capabilities=role_spec.capabilities,
+            forbidden_actions=DEFAULT_FORBIDDEN_WORKER_ACTIONS,
+            scope={"evidence_axis": axis},
+            budget={"timeout_seconds": timeout_seconds, "token_budget": token_budget},
+            expected_outputs=outputs,
+            output_contract={
+                "artifact_types": list(outputs),
+                "canonical_state": False,
+                "validation_owner": "lead-orchestrator",
+            },
+            termination={
+                "max_seconds": timeout_seconds,
+                "conditions": ["output_contract_satisfied", "budget_exhausted", "tool_failure"],
+            },
+            execution_mode=ExecutionMode.DELEGATED if delegated else ExecutionMode.LOCAL,
+            independent=independent,
+            read_only=True,
+            timeout_seconds=timeout_seconds,
+            token_budget=token_budget,
+        )
+
+    def _serial_tasks(self, run_id, base_revision) -> tuple[TaskSpec, ...]:
+        return (
+            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),
+            self._base("audit", "audit", "method-reviewer", "Audit methodology and outcome validity.", "methodology", run_id=run_id, base_revision=base_revision),
+            self._base("judge", "adjudicate", "evidence-judge", "Emit an evidence-bounded decision.", "decision", run_id=run_id, base_revision=base_revision),
+        )
+
+    def _medium_tasks(self, run_id, base_revision) -> tuple[TaskSpec, ...]:
+        return (
+            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),
+            self._base("challenge", "challenge", "skeptic", "Independently test the provisional interpretation.", "counter-evidence", run_id=run_id, base_revision=base_revision, delegated=True, independent=True, outputs=("SkepticFindings",)),
+            self._base("audit", "audit", "method-reviewer", "Audit methodology and construct validity.", "methodology", run_id=run_id, base_revision=base_revision),
+            self._base("judge", "adjudicate", "evidence-judge", "Emit an evidence-bounded decision.", "decision", run_id=run_id, base_revision=base_revision),
+        )
+
+    def _deep_tasks(self, run_id, base_revision) -> tuple[TaskSpec, ...]:
+        return (
+            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",)),
+            self._base("retrieve-applicability", "retrieve", "evidence-retriever", "Retrieve subgroup, context and freshness evidence.", "applicability-freshness", run_id=run_id, base_revision=base_revision, delegated=True, outputs=("SourceCandidates",)),
+            self._base("extract", "extract", "evidence-analyst", "Deterministically merge and extract validated findings.", "all-eligible", run_id=run_id, base_revision=base_revision),
+            self._base("challenge", "challenge", "skeptic", "Independently challenge the merged interpretation.", "counter-evidence", run_id=run_id, base_revision=base_revision, delegated=True, independent=True, outputs=("SkepticFindings",)),
+            self._base("audit", "audit", "method-reviewer", "Independently audit methodology and outcome validity.", "methodology", run_id=run_id, base_revision=base_revision, delegated=True, independent=True, outputs=("MethodologyAudit",)),
+            self._base("judge", "adjudicate", "evidence-judge", "Emit an evidence-bounded decision after all gates.", "decision", run_id=run_id, base_revision=base_revision),
+        )
+
+
+class CanonicalWriteGuard:
+    """Fail-closed single-writer authority for canonical state mutations."""
+
+    def __init__(self, writer_id: str = "lead-orchestrator") -> None:
+        if not writer_id.strip():
+            raise ValueError("writer_id must be non-empty")
+        self.writer_id = writer_id
+
+    def require(self, actor_id: str, artifact_type: str) -> None:
+        if artifact_type not in CANONICAL_STATE_ARTIFACTS:
+            return
+        if actor_id != self.writer_id:
+            raise PermissionError(
+                f"canonical state {artifact_type} may only be written by {self.writer_id!r}; "
+                f"actor {actor_id!r} is staging-only"
+            )

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()
 
@@ -83,7 +74,8 @@ def _load_pilot(project: ProjectWorkspace, pilot_id: str) -> dict:
 def _save_pilot(project: ProjectWorkspace, pilot: dict) -> Path:
     from scripts.validate_schema import SchemaError, validate  # noqa: PLC0415
 
-    schema_path = (Path(__file__).resolve().parent.parent / "schemas" / "v3"
+    from engine._resources import resource_root
+    schema_path = (resource_root() / "schemas" / "v3"
                    / "pilot-outcome.schema.json")
     schema = json.loads(schema_path.read_text(encoding="utf-8"))
     try:
@@ -110,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:
@@ -207,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
@@ -215,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},
     }
 
@@ -236,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"):
@@ -281,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/project.py

@@ -62,7 +62,7 @@ class ProjectWorkspace:
 
     @classmethod
     def create(cls, home: Path, *, question: str, title: str,
-               research_mode: str) -> "ProjectWorkspace":
+               research_mode: str, domain: str = "education") -> "ProjectWorkspace":
         home = Path(home).expanduser().resolve()
         project_id = new_project_id(question)
         path = home / "projects" / project_id
@@ -72,7 +72,7 @@ class ProjectWorkspace:
         manifest = {
             "project_id": project_id,
             "title": title,
-            "domain": "education",
+            "domain": domain,
             "question": question,
             "research_mode": research_mode,
             "decision_target": _default_decision_target(research_mode),