refactor(evidence): add cohesive Python facade (#28)

harness/tht/evidence/__init__.py

@@ -0,0 +1,97 @@
+"""Cohesive public entrypoint for Evidence domain capabilities.
+
+The implementation is introduced beside the legacy module layout so production callers can
+migrate one path at a time. These functions deliberately preserve the existing objects, ordering,
+and exceptions; they do not define a cross-domain service protocol.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from tht.ports.evidence import (
+    AcquiredDocument,
+    EvidenceSource,
+    EvidenceSourceError,
+    EvidenceSourceErrorCategory,
+    SourceObject,
+)
+
+if TYPE_CHECKING:
+    from tht.corpus.store import CorpusStore
+    from tht.decisions import DecisionRecord
+    from tht.search.evidence import ActiveEvidenceSearcher
+    from tht.session.models import SchemaLinking
+
+
+def discover(source: EvidenceSource) -> Iterable[SourceObject]:
+    """Discover source objects without changing source-defined laziness or ordering."""
+    return source.discover()
+
+
+def acquire(source: EvidenceSource, item: SourceObject) -> AcquiredDocument:
+    """Acquire one discovered object, preserving the source's classified failures."""
+    return source.acquire(item)
+
+
+def active_searcher(
+    cfg,
+    delegate,
+    *,
+    workspace_id: str | None = None,
+) -> ActiveEvidenceSearcher:
+    """Bind vector search to the atomically ACTIVE Evidence corpus generation."""
+    from tht.search.evidence import active_searcher as legacy_active_searcher
+
+    return legacy_active_searcher(cfg, delegate, workspace_id=workspace_id)
+
+
+def validate_corpus_workspace(cfg, workspace_id: str) -> None:
+    """Validate persisted Evidence corpus ownership before runtime retrieval setup."""
+    from tht.search.evidence import validate_corpus_workspace as legacy_validate
+
+    legacy_validate(cfg, workspace_id)
+
+
+def resolve_citation(
+    store: "CorpusStore",
+    evidence_id: str,
+    *,
+    materialized_root: Path | None = None,
+) -> str:
+    """Resolve an Evidence identifier to its immutable ACTIVE materialization."""
+    from tht.search.evidence import resolve_evidence_file
+
+    return resolve_evidence_file(
+        store,
+        evidence_id,
+        materialized_root=materialized_root,
+    )
+
+
+def project_session(
+    decisions: list["DecisionRecord"],
+    linking: "SchemaLinking",
+    evidence_root: Path,
+) -> list[dict]:
+    """Project cited and reviewed Evidence into the existing session artifact shape."""
+    from tht.session.artifacts import build_evidence_entries
+
+    return build_evidence_entries(decisions, linking, evidence_root)
+
+
+__all__ = [
+    "AcquiredDocument",
+    "EvidenceSource",
+    "EvidenceSourceError",
+    "EvidenceSourceErrorCategory",
+    "SourceObject",
+    "acquire",
+    "active_searcher",
+    "discover",
+    "project_session",
+    "resolve_citation",
+    "validate_corpus_workspace",
+]