ummaya 0.2.3 → 0.2.5

package/src/ummaya/evidence/source_provenance.py

@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic_core import PydanticCustomError
+
+from ummaya.evidence.source_provenance_redaction import (
+    PromptInjectionState,
+    RedactionCategory,
+    detect_prompt_injection,
+    ordered_redaction_categories,
+    redact_source_text,
+    redact_source_url,
+    redaction_categories_for_text,
+)
+from ummaya.tools.routing.schema import sha256, unique
+
+SourceKind = Literal["web", "mcp", "agent", "file"]
+SourceUseState = Literal["used", "blocked"]
+SourceTrust = Literal["trusted", "untrusted"]
+SynthesisState = Literal[
+    "eligible_for_synthesis",
+    "blocked_pending_user_approval",
+    "blocked_untrusted",
+    "blocked_missing_source",
+]
+DocumentAuthoringState = Literal[
+    "approved_for_document",
+    "blocked_pending_user_approval",
+    "blocked_untrusted",
+    "blocked_missing_source",
+]
+
+
+class SourceRedactionMetadata(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    redacted: bool
+    categories: tuple[RedactionCategory, ...] = Field(default_factory=tuple)
+    raw_private_document_stored: Literal[False] = False
+    secret_values_stored: Literal[False] = False
+    pii_values_stored: Literal[False] = False
+
+    @model_validator(mode="after")
+    def _categories_match_redacted_flag(self) -> Self:
+        if self.redacted and not self.categories:
+            raise PydanticCustomError(
+                "source_provenance_missing_redaction_categories",
+                "redacted provenance requires redaction categories",
+            )
+        if not self.redacted and self.categories:
+            raise PydanticCustomError(
+                "source_provenance_unexpected_redaction_categories",
+                "unredacted provenance cannot carry redaction categories",
+            )
+        return self
+
+
+class SourceProvenanceRecord(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    source_kind: SourceKind
+    source_url: str | None
+    local_evidence_handle: str | None
+    title: str | None
+    description: str | None
+    tool_id: str = Field(min_length=1)
+    observed_at: datetime
+    state: SourceUseState
+    citation_id: str = Field(min_length=1)
+    provenance_id: str = Field(min_length=1)
+    trust: SourceTrust
+    prompt_injection: PromptInjectionState = "not_detected"
+    redaction: SourceRedactionMetadata
+
+    @field_validator(
+        "source_url",
+        "local_evidence_handle",
+        "title",
+        "description",
+        "tool_id",
+        "citation_id",
+        "provenance_id",
+    )
+    @classmethod
+    def _reject_unredacted_sensitive_value(cls, value: str | None) -> str | None:
+        if value is not None and redaction_categories_for_text(value):
+            raise PydanticCustomError(
+                "source_provenance_unredacted_sensitive_value",
+                "source provenance contains unredacted sensitive value",
+            )
+        return value
+
+    @model_validator(mode="after")
+    def _requires_source_handle_and_label(self) -> Self:
+        if self.source_url is None and self.local_evidence_handle is None:
+            raise PydanticCustomError(
+                "source_provenance_missing_source",
+                "source provenance requires source_url or local_evidence_handle",
+            )
+        if self.title is None and self.description is None:
+            raise PydanticCustomError(
+                "source_provenance_missing_label",
+                "source provenance requires title or description when available",
+            )
+        return self
+
+
+class SourceProvenanceDecision(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    decision_id: str = Field(min_length=1)
+    provenance_ids: tuple[str, ...] = Field(min_length=1)
+    synthesis_state: SynthesisState
+    document_authoring_state: DocumentAuthoringState
+    requires_user_approval: bool
+    approved_by_user: bool
+    rationale: str = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _document_approval_requires_user_approval(self) -> Self:
+        if self.document_authoring_state == "approved_for_document" and (
+            self.requires_user_approval or not self.approved_by_user
+        ):
+            raise PydanticCustomError(
+                "source_provenance_document_approval_missing_user_approval",
+                "approved document authoring requires completed user approval",
+            )
+        return self
+
+
+class SourceProvenanceLedger(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: Literal["source_provenance_ledger.v1"] = "source_provenance_ledger.v1"
+    ledger_id: str = Field(min_length=1)
+    records: tuple[SourceProvenanceRecord, ...] = Field(min_length=1)
+    decisions: tuple[SourceProvenanceDecision, ...] = Field(default_factory=tuple)
+
+    @model_validator(mode="after")
+    def _decisions_reference_known_provenance_ids(self) -> Self:
+        known_ids = {record.provenance_id for record in self.records}
+        if len(known_ids) != len(self.records):
+            raise PydanticCustomError(
+                "source_provenance_duplicate_ids",
+                "source provenance ledger contains duplicate provenance ids",
+            )
+        unknown_ids = tuple(
+            unique(
+                provenance_id
+                for decision in self.decisions
+                for provenance_id in decision.provenance_ids
+                if provenance_id not in known_ids
+            )
+        )
+        if unknown_ids:
+            raise PydanticCustomError(
+                "source_provenance_unknown_ids",
+                "unknown provenance ids: " + ", ".join(unknown_ids),
+            )
+        return self
+
+
+def build_source_provenance_record(
+    *,
+    source_kind: SourceKind,
+    tool_id: str,
+    source_url: str | None,
+    local_evidence_handle: str | None,
+    title: str | None,
+    description: str | None,
+    observed_at: datetime,
+    state: SourceUseState,
+    trust: SourceTrust,
+    citation_id: str,
+) -> SourceProvenanceRecord:
+    redacted_url, url_categories = redact_source_url(source_url)
+    redacted_handle, handle_categories = redact_source_text(local_evidence_handle)
+    redacted_title, title_categories = redact_source_text(title)
+    redacted_description, description_categories = redact_source_text(description)
+    categories = ordered_redaction_categories(
+        (
+            *url_categories,
+            *handle_categories,
+            *title_categories,
+            *description_categories,
+        )
+    )
+    prompt_injection_text_parts = (
+        title or "",
+        description or "",
+        source_url or "",
+        local_evidence_handle or "",
+    )
+    return SourceProvenanceRecord(
+        source_kind=source_kind,
+        source_url=redacted_url,
+        local_evidence_handle=redacted_handle,
+        title=redacted_title,
+        description=redacted_description,
+        tool_id=tool_id,
+        observed_at=observed_at,
+        state=state,
+        citation_id=citation_id,
+        provenance_id=stable_source_provenance_id(
+            source_kind=source_kind,
+            tool_id=tool_id,
+            source_url=redacted_url,
+            local_evidence_handle=redacted_handle,
+            citation_id=citation_id,
+        ),
+        trust=trust,
+        prompt_injection=detect_prompt_injection(
+            "\n".join(part for part in prompt_injection_text_parts if part)
+        ),
+        redaction=SourceRedactionMetadata(
+            redacted=bool(categories),
+            categories=categories,
+            raw_private_document_stored=False,
+            secret_values_stored=False,
+            pii_values_stored=False,
+        ),
+    )
+
+
+def stable_source_provenance_id(
+    *,
+    source_kind: SourceKind,
+    tool_id: str,
+    source_url: str | None,
+    local_evidence_handle: str | None,
+    citation_id: str,
+) -> str:
+    digest = sha256(
+        {
+            "citation_id": citation_id,
+            "local_evidence_handle": local_evidence_handle,
+            "source_kind": source_kind,
+            "source_url": source_url,
+            "tool_id": tool_id,
+        }
+    )
+    return f"prov-{digest[:24]}"

package/src/ummaya/evidence/source_provenance_redaction.py

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import Literal
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+RedactionCategory = Literal[
+    "auth_header",
+    "cookie",
+    "service_key",
+    "token",
+    "pii",
+    "private_document",
+]
+PromptInjectionState = Literal["detected", "not_detected"]
+
+_AUTH_HEADER_PATTERN = re.compile(r"\bAuthorization\s*:\s*[^\n\r;]+", re.IGNORECASE)
+_AUTH_ASSIGNMENT_PATTERN = re.compile(
+    r"\bauthorization\s*=\s*[^\s&;\n\r]+",
+    re.IGNORECASE,
+)
+_COOKIE_PATTERN = re.compile(r"\bCookie\s*:\s*[^;\n\r]+;?\s*", re.IGNORECASE)
+_COOKIE_ASSIGNMENT_PATTERN = re.compile(
+    r"\bcookie\s*=\s*[^\s&;\n\r]+",
+    re.IGNORECASE,
+)
+_SERVICE_KEY_PATTERN = re.compile(
+    r"\b(?:serviceKey|authKey)\s*=\s*[^\s&]+",
+    re.IGNORECASE,
+)
+_TOKEN_PATTERN = re.compile(
+    r"\b(?:UMMAYA_[A-Z0-9_]*TOKEN|"
+    r"[A-Z0-9_]*(?:API|AUTH|ACCESS|REFRESH|SESSION)[_-]?KEY|"
+    r"(?:session|access|refresh|id)[_-]?token)\s*=\s*[^\s&]+|"
+    r"\bBearer\s+[A-Za-z0-9._~+/=-]+",
+    re.IGNORECASE,
+)
+_GENERIC_TOKEN_ASSIGNMENT_PATTERN = re.compile(
+    r"\b(?:token|secret|api[_-]?key|access[_-]?token|session[_-]?token|"
+    r"refresh[_-]?token|id[_-]?token|client[_-]?secret)\s*=\s*[^\s&;\n\r]+",
+    re.IGNORECASE,
+)
+_EMAIL_PATTERN = re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE)
+_KOREAN_RRN_PATTERN = re.compile(r"\b\d{6}-[1-4]\d{6}\b")
+_PHONE_PATTERN = re.compile(r"\b01[016789]-?\d{3,4}-?\d{4}\b")
+_PRIVATE_DOCUMENT_PATTERN = re.compile(
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----|raw private document|private document bytes",
+    re.IGNORECASE,
+)
+_PROMPT_INJECTION_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"ignore\s+(?:all\s+)?previous\s+instructions", re.IGNORECASE),
+    re.compile(r"change\s+(?:the\s+)?permission\s+policy", re.IGNORECASE),
+    re.compile(r"bypass\s+(?:permissions?|approval|policy)", re.IGNORECASE),
+    re.compile(r"treat\s+this\s+as\s+(?:a\s+)?system\s+instruction", re.IGNORECASE),
+)
+_SECRET_QUERY_KEYS = frozenset(
+    {
+        "access_token",
+        "api_key",
+        "apikey",
+        "auth",
+        "authkey",
+        "authorization",
+        "cookie",
+        "id_token",
+        "key",
+        "refresh_token",
+        "servicekey",
+        "session",
+        "session_token",
+        "token",
+    }
+)
+
+
+def redact_source_url(value: str | None) -> tuple[str | None, tuple[RedactionCategory, ...]]:
+    if value is None:
+        return None, ()
+    categories: list[RedactionCategory] = []
+    try:
+        parsed = urlsplit(value)
+    except ValueError:
+        return redact_source_text(value)
+    query_items: list[tuple[str, str]] = []
+    for key, item_value in parse_qsl(parsed.query, keep_blank_values=True):
+        lowered_key = key.lower()
+        if lowered_key in _SECRET_QUERY_KEYS:
+            categories.append(
+                "service_key" if lowered_key in {"authkey", "servicekey"} else "token"
+            )
+            continue
+        redacted_value, item_categories = redact_source_text(item_value)
+        categories.extend(item_categories)
+        query_items.append((key, redacted_value or ""))
+    rebuilt = urlunsplit(
+        (
+            parsed.scheme,
+            parsed.netloc,
+            parsed.path,
+            urlencode(query_items),
+            parsed.fragment,
+        )
+    )
+    redacted_text, text_categories = redact_source_text(rebuilt)
+    categories.extend(text_categories)
+    return redacted_text, ordered_redaction_categories(categories)
+
+
+def redact_source_text(value: str | None) -> tuple[str | None, tuple[RedactionCategory, ...]]:
+    if value is None:
+        return None, ()
+    categories = list(redaction_categories_for_text(value))
+    redacted = _AUTH_HEADER_PATTERN.sub("[REDACTED_AUTH_HEADER]", value)
+    redacted = _AUTH_ASSIGNMENT_PATTERN.sub("[REDACTED_AUTH_HEADER]", redacted)
+    redacted = _COOKIE_PATTERN.sub("[REDACTED_COOKIE] ", redacted)
+    redacted = _COOKIE_ASSIGNMENT_PATTERN.sub("[REDACTED_COOKIE]", redacted)
+    redacted = _SERVICE_KEY_PATTERN.sub("[REDACTED_SERVICE_KEY]", redacted)
+    redacted = _TOKEN_PATTERN.sub("[REDACTED_TOKEN]", redacted)
+    redacted = _GENERIC_TOKEN_ASSIGNMENT_PATTERN.sub("[REDACTED_TOKEN]", redacted)
+    redacted = _EMAIL_PATTERN.sub("[REDACTED_PII]", redacted)
+    redacted = _KOREAN_RRN_PATTERN.sub("[REDACTED_PII]", redacted)
+    redacted = _PHONE_PATTERN.sub("[REDACTED_PII]", redacted)
+    redacted = _PRIVATE_DOCUMENT_PATTERN.sub("[REDACTED_PRIVATE_DOCUMENT]", redacted)
+    return re.sub(r"[ \t]{2,}", " ", redacted).strip(), ordered_redaction_categories(categories)
+
+
+def detect_prompt_injection(value: str) -> PromptInjectionState:
+    return (
+        "detected"
+        if any(pattern.search(value) for pattern in _PROMPT_INJECTION_PATTERNS)
+        else "not_detected"
+    )
+
+
+def redaction_categories_for_text(value: str) -> tuple[RedactionCategory, ...]:
+    categories: list[RedactionCategory] = []
+    if _AUTH_HEADER_PATTERN.search(value):
+        categories.append("auth_header")
+    if _AUTH_ASSIGNMENT_PATTERN.search(value):
+        categories.append("auth_header")
+    if _COOKIE_PATTERN.search(value):
+        categories.append("cookie")
+    if _COOKIE_ASSIGNMENT_PATTERN.search(value):
+        categories.append("cookie")
+    if _SERVICE_KEY_PATTERN.search(value):
+        categories.append("service_key")
+    if _TOKEN_PATTERN.search(value):
+        categories.append("token")
+    if _GENERIC_TOKEN_ASSIGNMENT_PATTERN.search(value):
+        categories.append("token")
+    if (
+        _EMAIL_PATTERN.search(value)
+        or _KOREAN_RRN_PATTERN.search(value)
+        or _PHONE_PATTERN.search(value)
+    ):
+        categories.append("pii")
+    if _PRIVATE_DOCUMENT_PATTERN.search(value):
+        categories.append("private_document")
+    return ordered_redaction_categories(categories)
+
+
+def ordered_redaction_categories(
+    categories: Iterable[RedactionCategory],
+) -> tuple[RedactionCategory, ...]:
+    order: tuple[RedactionCategory, ...] = (
+        "auth_header",
+        "cookie",
+        "service_key",
+        "token",
+        "pii",
+        "private_document",
+    )
+    present = set(categories)
+    return tuple(category for category in order if category in present)

package/src/ummaya/evidence/task_registry.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Harbor-style task registry for Evidence Fabric v2.
+
+The registry mirrors Harbor's task boundary: a task has an instruction,
+metadata/configuration, and a verifier script. UMMAYA keeps execution local and
+deterministic; this module only resolves and validates task definitions.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Literal, cast
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_BANNED_MODEL_VISIBLE_KEYS = frozenset(
+    {
+        "adapter_id",
+        "tool_id",
+        "expected_tool_id",
+        "fixture_refs",
+        "fixture_ref",
+        "current_adapter_id",
+    }
+)
+
+
+class TaskRegistryError(ValueError):
+    """Raised when an Evidence Fabric task registry is invalid."""
+
+
+class EvidenceTask(BaseModel):
+    """One resolved Harbor-style evidence task."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    task_id: str
+    task_dir: Path
+    instruction_path: Path
+    verifier_path: Path
+    description: str
+    dataset_id: str
+    keywords: tuple[str, ...] = Field(default_factory=tuple)
+    environment_os: Literal["linux", "windows"] = "linux"
+    allow_internet: bool = False
+    verifier_timeout_sec: float = 120.0
+
+
+class EvidenceDatasetRef(BaseModel):
+    """A dataset reference resolved from the local task registry."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    ref: str
+    dataset_id: str
+    scenario_path: Path
+    tasks: tuple[EvidenceTask, ...]
+
+
+class EvidenceTaskRegistry(BaseModel):
+    """Resolved Evidence Fabric task registry."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    version: int
+    registry_id: str
+    datasets: tuple[EvidenceDatasetRef, ...]
+
+    def resolve_dataset(self, ref: str) -> EvidenceDatasetRef:
+        """Return the dataset entry matching a Harbor-style dataset ref."""
+
+        for dataset in self.datasets:
+            if dataset.ref == ref:
+                return dataset
+        raise TaskRegistryError(f"dataset ref not found in task registry: {ref}")
+
+
+def _load_yaml_mapping(path: Path) -> Mapping[str, object]:
+    if not path.exists():
+        raise TaskRegistryError(f"task registry not found: {path}")
+    loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(loaded, Mapping):
+        raise TaskRegistryError(f"task registry must be a mapping: {path}")
+    return cast(Mapping[str, object], loaded)
+
+
+def _find_banned_keys(value: object, path: str = "$") -> tuple[str, ...]:
+    if isinstance(value, Mapping):
+        hits: list[str] = []
+        for key, nested in value.items():
+            key_text = str(key)
+            nested_path = f"{path}.{key_text}"
+            if key_text in _BANNED_MODEL_VISIBLE_KEYS:
+                hits.append(nested_path)
+            hits.extend(_find_banned_keys(nested, nested_path))
+        return tuple(hits)
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+        hits = []
+        for index, nested in enumerate(value):
+            hits.extend(_find_banned_keys(nested, f"{path}[{index}]"))
+        return tuple(hits)
+    return ()
+
+
+def _read_path(path: Path) -> Path:
+    return path if path.is_absolute() else _REPO_ROOT / path
+
+
+def _require_existing_files(paths: tuple[Path, ...]) -> None:
+    for required in paths:
+        if not _read_path(required).exists():
+            raise TaskRegistryError(f"task file missing: {required}")
+
+
+def _require_mapping(value: object, label: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise TaskRegistryError(f"{label} must be a mapping")
+    return cast(Mapping[str, object], value)
+
+
+def _require_non_empty_str(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise TaskRegistryError(f"{label} must be a non-empty string")
+    return value
+
+
+def _require_sequence(value: object, label: str) -> Sequence[object]:
+    if not isinstance(value, Sequence) or isinstance(value, str | bytes | bytearray):
+        raise TaskRegistryError(f"{label} must be a list")
+    return cast(Sequence[object], value)
+
+
+def _optional_float(value: object, label: str, default: float) -> float:
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, str | int | float):
+        raise TaskRegistryError(f"{label} must be a number")
+    return float(value)
+
+
+def _load_task_toml(task_toml: Path) -> Mapping[str, object]:
+    raw = tomllib.loads(_read_path(task_toml).read_text(encoding="utf-8"))
+    banned = _find_banned_keys(raw)
+    if banned:
+        raise TaskRegistryError(
+            "model-visible task registry contains banned implementation keys: " + ", ".join(banned)
+        )
+    return cast(Mapping[str, object], raw)
+
+
+def _build_task(
+    *,
+    task_dir: Path,
+    instruction_path: Path,
+    verifier_path: Path,
+    raw: Mapping[str, object],
+) -> EvidenceTask:
+    task_section = _require_mapping(raw.get("task"), "task.toml [task]")
+    metadata_section = _require_mapping(raw.get("metadata", {}), "task.toml [metadata]")
+    environment_section = _require_mapping(raw.get("environment", {}), "task.toml [environment]")
+    verifier_section = _require_mapping(raw.get("verifier", {}), "task.toml [verifier]")
+    keywords = _require_sequence(task_section.get("keywords", ()), "task.toml [task].keywords")
+
+    try:
+        return EvidenceTask(
+            task_id=_require_non_empty_str(task_section.get("name"), "task.toml [task].name"),
+            task_dir=task_dir,
+            instruction_path=instruction_path,
+            verifier_path=verifier_path,
+            description=_require_non_empty_str(
+                task_section.get("description"),
+                "task.toml [task].description",
+            ),
+            dataset_id=_require_non_empty_str(
+                metadata_section.get("dataset_id"),
+                "task.toml [metadata].dataset_id",
+            ),
+            keywords=tuple(str(keyword) for keyword in keywords),
+            environment_os=cast(
+                Literal["linux", "windows"],
+                environment_section.get("os", "linux"),
+            ),
+            allow_internet=bool(environment_section.get("allow_internet", False)),
+            verifier_timeout_sec=_optional_float(
+                verifier_section.get("timeout_sec"),
+                "task.toml [verifier].timeout_sec",
+                120.0,
+            ),
+        )
+    except ValidationError as exc:
+        raise TaskRegistryError(str(exc)) from exc
+
+
+def _load_task(task_dir: Path) -> EvidenceTask:
+    task_toml = task_dir / "task.toml"
+    instruction_path = task_dir / "instruction.md"
+    verifier_path = task_dir / "tests" / "test.sh"
+    _require_existing_files((task_toml, instruction_path, verifier_path))
+    return _build_task(
+        task_dir=task_dir,
+        instruction_path=instruction_path,
+        verifier_path=verifier_path,
+        raw=_load_task_toml(task_toml),
+    )
+
+
+def _load_dataset_ref(index: int, dataset_raw: object) -> EvidenceDatasetRef:
+    dataset_map = _require_mapping(dataset_raw, f"datasets[{index}]")
+    ref = _require_non_empty_str(dataset_map.get("ref"), f"datasets[{index}].ref")
+    dataset_id = _require_non_empty_str(
+        dataset_map.get("dataset_id"),
+        f"datasets[{index}].dataset_id",
+    )
+    scenario_path = _require_non_empty_str(
+        dataset_map.get("scenario_path"),
+        f"datasets[{index}].scenario_path",
+    )
+    task_paths = _require_sequence(dataset_map.get("task_paths"), f"datasets[{index}].task_paths")
+
+    tasks = tuple(_load_task(Path(str(task_path))) for task_path in task_paths)
+    mismatched = tuple(task.task_id for task in tasks if task.dataset_id != dataset_id)
+    if mismatched:
+        raise TaskRegistryError(
+            f"dataset {ref} has tasks with mismatched dataset_id: {', '.join(mismatched)}"
+        )
+    return EvidenceDatasetRef(
+        ref=ref,
+        dataset_id=dataset_id,
+        scenario_path=Path(scenario_path),
+        tasks=tasks,
+    )
+
+
+def load_task_registry(path: Path) -> EvidenceTaskRegistry:
+    """Load and validate a Harbor-style Evidence Fabric task registry."""
+
+    raw = _load_yaml_mapping(path)
+    banned = _find_banned_keys(raw)
+    if banned:
+        raise TaskRegistryError(
+            "model-visible task registry contains banned implementation keys: " + ", ".join(banned)
+        )
+
+    version = raw.get("version")
+    if not isinstance(version, int):
+        raise TaskRegistryError("task registry version must be an integer")
+    registry_id = _require_non_empty_str(raw.get("registry_id"), "task registry_id")
+    datasets = _require_sequence(raw.get("datasets"), "task registry datasets")
+    resolved_datasets = tuple(
+        _load_dataset_ref(index, dataset_raw) for index, dataset_raw in enumerate(datasets)
+    )
+
+    try:
+        return EvidenceTaskRegistry(
+            version=version,
+            registry_id=registry_id,
+            datasets=resolved_datasets,
+        )
+    except ValidationError as exc:
+        raise TaskRegistryError(str(exc)) from exc