eduevidence 5.2.0 → 6.2.0

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,8 +38,15 @@ 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
 from engine.semantics import claim_relation, decision_implication
 from engine.synthesis import ClaimSynthesis, synthesize_project
 from engine.versions import (
@@ -229,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]] = {}
@@ -253,39 +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.
-    """
-    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"
-
+                     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.
+    """
+    return _policy_decision_action(
+        confidence_label=confidence["label"],
+        decisive_relations=decisive_relations,
+        has_direct_primary_evidence=has_direct_primary_evidence,
+    )
 
 
 
@@ -300,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:
@@ -352,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/update.py

@@ -16,6 +16,7 @@ from datetime import datetime, timezone
 
 from engine.contracts import validate_record
 from engine.graph_store import GraphStore, GraphMutation, GraphRevision
+from engine.project import ProjectWorkspace
 
 
 def _now_iso() -> str:

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 = "5.2.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"

package/engine/worker_result.py

@@ -0,0 +1,109 @@
+"""Validation boundary between delegated workers and canonical reasoning.
+
+A worker may return candidate staging artifacts and prose, but it cannot mark
+its own output trustworthy. The lead/main process reconstructs WorkerResult,
+checks it against the originating TaskSpec and artifact validators, and only
+then may validated artifacts enter a Judge context.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from engine.orchestration import CANONICAL_STATE_ARTIFACTS, TaskSpec
+
+
+ArtifactValidator = Callable[[dict[str, Any]], list[str]]
+
+
+@dataclass(frozen=True)
+class WorkerResult:
+    task_id: str
+    status: str
+    staging_artifacts: tuple[dict[str, Any], ...]
+    validated: bool
+    validation_issues: tuple[str, ...] = ()
+    metrics: dict[str, Any] = field(default_factory=dict)
+    summary: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "status": self.status,
+            "staging_artifacts": [dict(item) for item in self.staging_artifacts],
+            "validated": self.validated,
+            "validation_issues": list(self.validation_issues),
+            "metrics": dict(self.metrics),
+            "summary": self.summary,
+        }
+
+
+def validate_worker_output(
+    task: TaskSpec,
+    raw: dict[str, Any],
+    *,
+    artifact_validator: ArtifactValidator | None = None,
+) -> WorkerResult:
+    """Validate untrusted worker output in the lead process.
+
+    Any worker-supplied `validated` field is deliberately ignored.
+    """
+    task.validate_for_dispatch()
+    issues: list[str] = []
+    if not isinstance(raw, dict):
+        raise ValueError("worker output must be an object")
+    if raw.get("task_id") != task.task_id:
+        issues.append("task_id mismatch")
+    status = str(raw.get("status", "failed"))
+    if status not in {"completed", "failed", "blocked"}:
+        issues.append(f"invalid worker status: {status}")
+        status = "failed"
+    artifacts = raw.get("staging_artifacts", [])
+    if not isinstance(artifacts, list) or any(not isinstance(item, dict) for item in artifacts):
+        issues.append("staging_artifacts must be a list of objects")
+        artifacts = []
+
+    expected = set(task.expected_outputs)
+    for index, artifact in enumerate(artifacts):
+        artifact_type = str(artifact.get("artifact_type", ""))
+        if not artifact_type:
+            issues.append(f"artifact[{index}] missing artifact_type")
+            continue
+        if artifact_type in CANONICAL_STATE_ARTIFACTS:
+            issues.append(f"artifact[{index}] attempts canonical output {artifact_type}")
+        if expected and artifact_type not in expected:
+            issues.append(
+                f"artifact[{index}] type {artifact_type} not allowed by TaskSpec output contract"
+            )
+        if artifact_validator is not None:
+            issues.extend(
+                f"artifact[{index}]: {problem}"
+                for problem in artifact_validator(artifact)
+            )
+
+    validated = status == "completed" and not issues
+    return WorkerResult(
+        task_id=task.task_id,
+        status=status,
+        staging_artifacts=tuple(dict(item) for item in artifacts),
+        validated=validated,
+        validation_issues=tuple(issues),
+        metrics=dict(raw.get("metrics") or {}),
+        summary=str(raw.get("summary", "")),
+    )
+
+
+def require_validated_artifacts_for_judge(
+    results: list[WorkerResult] | tuple[WorkerResult, ...],
+) -> list[dict[str, Any]]:
+    """Fail closed if a Judge context contains any unvalidated worker result."""
+    invalid = [result.task_id for result in results if not result.validated]
+    if invalid:
+        raise PermissionError(
+            "Judge may consume validated staging artifacts only; rejected task results: "
+            + ",".join(invalid)
+        )
+    artifacts: list[dict[str, Any]] = []
+    for result in results:
+        artifacts.extend(dict(item) for item in result.staging_artifacts)
+    return artifacts

package/engine/workflows.py

@@ -0,0 +1,70 @@
+"""Canonical workflow registry for the Decision-Grade Evidence Engine.
+
+The scientific protocol is deliberately independent from execution adapters and
+projections.  A renderer may fail or be replaced without changing what counts
+as completed scientific work.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+SCIENTIFIC_STAGE_IDS = (
+    "frame", "retrieve", "extract", "challenge", "audit", "adjudicate",
+    "applicability", "intervene", "evaluate",
+)
+PROJECTION_STAGE_ID = "projection"
+
+
+@dataclass(frozen=True)
+class WorkflowSpec:
+    workflow_id: str
+    title: str
+    stage_ids: tuple[str, ...]
+    capability_ids: tuple[str, ...]
+
+
+_EVIDENCE_REVIEW = (
+    "research_framing", "literature_search", "counter_evidence_search",
+    "source_fetch", "source_validation", "study_extraction",
+    "finding_extraction", "methodology_appraisal", "claim_linking",
+    "evidence_synthesis", "tribunal", "applicability_analysis",
+    "knowledge_gap_detection",
+)
+
+_WORKFLOWS = {
+    "evidence_review": WorkflowSpec(
+        "evidence_review", "Evidence Review",
+        SCIENTIFIC_STAGE_IDS[:7], _EVIDENCE_REVIEW,
+    ),
+    "decision_and_pilot": WorkflowSpec(
+        "decision_and_pilot", "Decision & Pilot",
+        SCIENTIFIC_STAGE_IDS[:8], _EVIDENCE_REVIEW + ("intervention_design",),
+    ),
+    "evaluate_and_update": WorkflowSpec(
+        "evaluate_and_update", "Evaluate & Update",
+        ("evaluate",), ("evaluation_design", "data_validation", "data_analysis"),
+    ),
+    "full_research_cycle": WorkflowSpec(
+        "full_research_cycle", "Full Research Cycle",
+        SCIENTIFIC_STAGE_IDS,
+        _EVIDENCE_REVIEW + ("intervention_design", "evaluation_design", "data_validation", "data_analysis"),
+    ),
+}
+
+
+def workflow_registry() -> dict[str, WorkflowSpec]:
+    """Return the immutable workflow catalogue keyed by user intent."""
+    return dict(_WORKFLOWS)
+
+
+def workflow(workflow_id: str) -> WorkflowSpec:
+    try:
+        return _WORKFLOWS[workflow_id]
+    except KeyError as exc:
+        raise ValueError(f"unknown workflow {workflow_id!r}") from exc
+
+
+def execution_stages() -> tuple[str, ...]:
+    """Canonical execution order, with Projection explicitly outside science."""
+    return SCIENTIFIC_STAGE_IDS + (PROJECTION_STAGE_ID,)