@dzhechkov/p-replicator 1.5.13 → 1.5.15

package/templates/.claude/skills/goap-research-ed25519/scripts/ed25519_verifier.py

@@ -46,6 +46,41 @@ TRUST_CLASS_ISSUER_SIGNED = "ISSUER_SIGNED"
 TRUST_CLASS_SELF_ATTESTED = "SELF_ATTESTED"
 TRUST_CLASS_UNVERIFIED = "UNVERIFIED"
 
+# --- Evidence provenance (ADR-001): a SECOND, ORTHOGONAL axis -----------------
+# trust_class answers "was this record altered after signing?".
+# evidence_class answers "did anyone actually open the source?".
+# A fact can be ISSUER_SIGNED *and* ASSERTED — that combination is legal, and it
+# is exactly the dangerous one: a cryptographically perfect record of something
+# the model recited from memory. Merging the two axes into one field would make
+# that state inexpressible (and would repeat the whitelist_available defect,
+# where "issuer-signed" and "belongs to a trusted class" were fused).
+EVIDENCE_FETCH_VERIFIED = "FETCH_VERIFIED"  # this script performed the HTTP request itself
+EVIDENCE_LISTING_ONLY = "LISTING_ONLY"      # URL known from a listing / body supplied by hand
+EVIDENCE_ASSERTED = "ASSERTED"              # stated from model memory, source never opened
+
+EVIDENCE_CLASSES = (EVIDENCE_FETCH_VERIFIED, EVIDENCE_LISTING_ONLY, EVIDENCE_ASSERTED)
+
+# Confidence ceilings per evidence class. ASSERTED is 0.0 by construction, not
+# "low": a claim nobody checked is not weak evidence, it is no evidence.
+EVIDENCE_CEILINGS = {
+    EVIDENCE_FETCH_VERIFIED: 1.0,
+    EVIDENCE_LISTING_ONLY: 0.50,
+    EVIDENCE_ASSERTED: 0.0,
+}
+
+# Signed-message schema marker (ADR-002 + its AM-1 amendment).
+#
+# HONEST ROLE: this marker is self-description and the growth point for a future
+# v3 (slice C will add study_population). It is NOT what stops tampering.
+# What stops tampering is that the v2 message CONTAINS the three new keys at all:
+#   strip evidence_class → verifier builds the 6-key v1 text ≠ signed v2 text → fail
+#   add   evidence_class → verifier builds the v2 text      ≠ signed v1 text → fail
+# The first draft of ADR-002 credited this marker with closing the downgrade
+# attack; the discrimination run refuted that (removing the marker left
+# tamper_strip green). Keeping the wrong attribution would have been the exact
+# class of error this feature exists to prevent.
+FACT_SCHEMA_V2 = "fact-v2"
+
 
 @dataclass
 class PinnedKey:
@@ -92,6 +127,11 @@ class SignedFact:
     trust_class: str = TRUST_CLASS_SELF_ATTESTED
     research_context: Optional[str] = None
     metadata: Dict[str, Any] = field(default_factory=dict)
+    # --- evidence axis (ADR-001). None = legacy fact: evidence is UNKNOWN, which
+    # is neither ASSERTED nor FETCH_VERIFIED. Unknown is named, never guessed.
+    evidence_class: Optional[str] = None
+    fetch_date: Optional[str] = None
+    source_date: Optional[str] = None
 
     def to_dict(self) -> Dict[str, Any]:
         return asdict(self)
@@ -157,13 +197,39 @@ def canonical_json(data: Dict[str, Any]) -> str:
     return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
 
 
-def canonical_fact_message(fact: SignedFact) -> str:
-    """Canonical signed message for a fact."""
+def canonical_fact_message_v1(fact: SignedFact) -> str:
+    """Legacy signed message. Frozen: every fact signed before the evidence axis
+    existed verifies against exactly these six fields."""
+    return canonical_json(
+        {
+            "claim": fact.claim,
+            "issuer": fact.issuer,
+            "research_context": fact.research_context,
+            "source_hash": fact.source_hash,
+            "source_url": fact.source_url,
+            "timestamp": fact.timestamp,
+        }
+    )
+
+
+def canonical_fact_message_v2(fact: SignedFact) -> str:
+    """Signed message that COVERS the evidence axis (ADR-002).
+
+    The `schema` marker is load-bearing, not decoration: it makes the v1 and v2
+    messages differ even when the six shared fields are identical, so BOTH tamper
+    directions break the signature —
+      * strip evidence_class  → verifier picks v1 → v1 text != signed v2 text → fail
+      * add evidence_class    → verifier picks v2 → v2 text != signed v1 text → fail
+    """
     return canonical_json(
         {
+            "schema": FACT_SCHEMA_V2,
             "claim": fact.claim,
+            "evidence_class": fact.evidence_class,
+            "fetch_date": fact.fetch_date,
             "issuer": fact.issuer,
             "research_context": fact.research_context,
+            "source_date": fact.source_date,
             "source_hash": fact.source_hash,
             "source_url": fact.source_url,
             "timestamp": fact.timestamp,
@@ -171,6 +237,58 @@ def canonical_fact_message(fact: SignedFact) -> str:
     )
 
 
+def fact_schema_version(fact: SignedFact) -> int:
+    """Which signed-message schema this fact uses. Presence of the evidence axis
+    IS the discriminator — a legacy fact has none and stays on v1 forever."""
+    return 2 if fact.evidence_class is not None else 1
+
+
+def canonical_fact_message(fact: SignedFact) -> str:
+    """Canonical signed message for a fact — dispatched by schema version."""
+    return canonical_fact_message_v2(fact) if fact_schema_version(fact) == 2 else canonical_fact_message_v1(fact)
+
+
+def evidence_ceiling(evidence_class: Optional[str]) -> float:
+    """Confidence ceiling contributed by the evidence axis. An UNKNOWN (legacy)
+    evidence class contributes NO ceiling (1.0) — absence of evidence data is not
+    evidence of absence; the legacy fact is judged by its trust class alone.
+    An UNRECOGNISED class is 0.0: a misspelling must not read as permission."""
+    if evidence_class is None:
+        return 1.0
+    return EVIDENCE_CEILINGS.get(evidence_class, 0.0)
+
+
+def source_tier_ceiling(fact: SignedFact) -> float:
+    """Ceiling from the source-class tier (FR-5). Wired because a formula printed
+    in SKILL.md but never called is a false claim — the first draft computed
+    min(trust, evidence) while the docs promised min(trust, evidence, tier), so an
+    unknown-domain fact kept 0.60 instead of the promised 0.40 (Codex QE #6).
+
+    APPLIES TO v2 FACTS ONLY. A new ceiling must not retroactively re-score records
+    signed before it existed: wiring it globally silently downgraded a legacy
+    ISSUER_SIGNED fact from 0.95 to 0.40 and broke the backward-compatibility test
+    that is this feature's NFR-2 evidence. Old facts keep the semantics they were
+    created under; the tier applies from the schema that introduced it.
+
+    Import is local and fail-open: source_tiers is a DATA module, and missing data
+    must never break signature verification."""
+    if fact_schema_version(fact) != 2 or not fact.source_url:
+        return 1.0
+    # FAIL CLOSED (Codex QE r2): the first version returned 1.0 when source_tiers
+    # was missing or raised, so losing the security-data module SILENTLY RAISED
+    # every confidence. A ceiling that disappears when its data disappears is not a
+    # ceiling. Absent data ⇒ the most cautious tier, and the caller sees the low
+    # number rather than a comfortable one.
+    try:
+        from source_tiers import classify_source, TIER_CEILINGS, TIER_D
+    except Exception:
+        return 0.40
+    try:
+        return classify_source(fact.source_url).ceiling
+    except Exception:
+        return TIER_CEILINGS.get(TIER_D, 0.40)
+
+
 def fact_content_hash(fact: SignedFact) -> str:
     """Stable hash for chain linkage. Excludes parent links and chain position."""
     return hashlib.sha256(canonical_fact_message(fact).encode("utf-8")).hexdigest()
@@ -391,6 +509,165 @@ class Ed25519Verifier:
         fact.signature, _ = self.sign_content(canonical_fact_message(fact))
         return fact
 
+    # ---------------------------------------------------------------- evidence axis
+    # THREE constructors, not one with an `evidence_class=` parameter (ADR-003).
+    # The manual paths below cannot emit FETCH_VERIFIED because they never receive
+    # a FetchRecord — the restriction is in the API shape, not in the author's
+    # discipline. A single constructor taking the class as an argument would put
+    # the guarantee back on the caller's honesty, which is the thing that failed.
+
+    def _sign_evidence_fact(
+        self,
+        claim: str,
+        source_url: str,
+        source_hash: str,
+        issuer: str,
+        evidence_class: str,
+        fetch_date: Optional[str],
+        source_date: Optional[str],
+        metadata: Optional[Dict[str, Any]],
+        research_context: Optional[str],
+        base_confidence: float,
+    ) -> SignedFact:
+        if self._private_key is None or self._public_key is None:
+            raise ValueError("No keypair loaded.")
+        if evidence_class not in EVIDENCE_CLASSES:
+            raise ValueError(f"unknown evidence_class {evidence_class!r}; expected one of {EVIDENCE_CLASSES}")
+        fact = SignedFact(
+            claim=claim,
+            source_url=source_url,
+            source_hash=source_hash,
+            issuer=issuer,
+            issuer_pubkey=f"ed25519:{self.get_public_key_b64()}",
+            signature="",
+            timestamp=datetime.utcnow().isoformat() + "Z",
+            confidence=min(base_confidence, evidence_ceiling(evidence_class)),
+            trust_class=TRUST_CLASS_SELF_ATTESTED,
+            research_context=research_context,
+            metadata=metadata or {},
+            evidence_class=evidence_class,
+            fetch_date=fetch_date,
+            source_date=source_date,
+        )
+        fact.signature, _ = self.sign_content(canonical_fact_message(fact))
+        return fact
+
+    def create_fetched_fact(
+        self,
+        claim: str,
+        fetch_record: Any,
+        issuer: str,
+        source_date: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        research_context: Optional[str] = None,
+    ) -> SignedFact:
+        """FETCH_VERIFIED — requires proof the request actually happened.
+
+        `fetch_record` must be an evidence_fetch.FetchRecord for a 2xx response.
+        Duck-typed on purpose (the verifier must not import the network module),
+        but validated: anything lacking the proof fields is refused outright
+        rather than silently downgraded, because a caller reaching for THIS
+        constructor is asserting a fetch occurred.
+        """
+        # A duck-typed check was NOT enough (Codex QE #1): a SimpleNamespace with
+        # four plausible attributes minted FETCH_VERIFIED without any network I/O.
+        # The record must be the real type AND carry this process's fetch witness,
+        # which only evidence_fetch.fetch_source() hands out.
+        if not getattr(fetch_record, "is_authentic", None) or not fetch_record.is_authentic():
+            raise ValueError(
+                "create_fetched_fact requires a FetchRecord produced by evidence_fetch.fetch_source() "
+                "in this process — a hand-built or duck-typed record is not proof that a fetch happened"
+            )
+        required = ("sha256_body", "final_url", "status", "fetched_at")
+        missing = [f for f in required if getattr(fetch_record, f, None) is None]
+        if missing:
+            raise ValueError(
+                f"create_fetched_fact requires a FetchRecord; missing proof fields: {', '.join(missing)}"
+            )
+        if not (200 <= int(getattr(fetch_record, "status")) < 300):
+            raise ValueError(
+                f"create_fetched_fact refuses a non-2xx fetch (status {getattr(fetch_record, 'status')}) — "
+                "an error page is not the source it stands for"
+            )
+        meta = dict(metadata or {})
+        meta.setdefault("fetch_status", int(getattr(fetch_record, "status")))
+        meta.setdefault("fetch_bytes", getattr(fetch_record, "bytes_len", None))
+        if getattr(fetch_record, "final_url", None) != getattr(fetch_record, "url", None):
+            meta.setdefault("redirected_from", getattr(fetch_record, "url", None))
+        return self._sign_evidence_fact(
+            claim=claim,
+            source_url=getattr(fetch_record, "final_url"),
+            source_hash=getattr(fetch_record, "sha256_body"),
+            issuer=issuer,
+            evidence_class=EVIDENCE_FETCH_VERIFIED,
+            fetch_date=getattr(fetch_record, "fetched_at"),
+            source_date=source_date,
+            metadata=meta,
+            research_context=research_context,
+            base_confidence=0.60,
+        )
+
+    def create_listing_fact(
+        self,
+        claim: str,
+        source_url: str,
+        reason: str,
+        source_content: Optional[str] = None,
+        issuer: str = "researcher",
+        source_date: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        research_context: Optional[str] = None,
+    ) -> SignedFact:
+        """LISTING_ONLY — the URL is known but this script did not fetch it, or a
+        body was supplied by hand. `reason` is MANDATORY and stored verbatim: a
+        degradation whose cause is not recorded is indistinguishable from a bug.
+        """
+        if not reason or not reason.strip():
+            raise ValueError("create_listing_fact requires a non-empty reason (why was this not fetched?)")
+        meta = dict(metadata or {})
+        meta["evidence_note"] = reason.strip()
+        digest = hashlib.sha256((source_content or "").encode("utf-8")).hexdigest()
+        if source_content is None:
+            meta.setdefault("source_body", "not supplied — source_hash is the hash of an empty body")
+        return self._sign_evidence_fact(
+            claim=claim,
+            source_url=source_url,
+            source_hash=digest,
+            issuer=issuer,
+            evidence_class=EVIDENCE_LISTING_ONLY,
+            fetch_date=None,
+            source_date=source_date,
+            metadata=meta,
+            research_context=research_context,
+            base_confidence=0.50,
+        )
+
+    def create_asserted_fact(
+        self,
+        claim: str,
+        issuer: str = "researcher",
+        source_url: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+        research_context: Optional[str] = None,
+    ) -> SignedFact:
+        """ASSERTED — stated from model memory, source never opened. Confidence is
+        0.0 by construction: this is not weak evidence, it is no evidence. Such a
+        fact exists so it can be RECORDED and then refused by the report gate,
+        rather than quietly becoming a sentence in a medical document.
+        """
+        return self._sign_evidence_fact(
+            claim=claim,
+            source_url=source_url,
+            source_hash=hashlib.sha256(b"").hexdigest(),
+            issuer=issuer,
+            evidence_class=EVIDENCE_ASSERTED,
+            fetch_date=None,
+            source_date=None,
+            metadata=metadata,
+            research_context=research_context,
+            base_confidence=0.0,
+        )
+
     def create_issuer_signed_fact(
         self,
         claim: str,
@@ -462,7 +739,15 @@ class Ed25519Verifier:
             except Exception:
                 return self._result(fact, False, 0.0, TRUST_CLASS_UNVERIFIED, "Invalid embedded public key")
             if self.verify_signature(canonical_fact_message(fact), fact.signature, public_key):
-                return self._result(fact, True, min(fact.confidence or 0.60, 0.60), TRUST_CLASS_SELF_ATTESTED, None)
+                # Weakest link, not the average: a signed-but-unread claim is capped by
+                # the evidence axis regardless of how sound its signature is (ADR-001).
+                capped = min(
+                    fact.confidence or 0.60,
+                    0.60,
+                    evidence_ceiling(fact.evidence_class),
+                    source_tier_ceiling(fact),
+                )
+                return self._result(fact, True, capped, TRUST_CLASS_SELF_ATTESTED, None)
             return self._result(fact, False, 0.0, TRUST_CLASS_UNVERIFIED, "Self-attestation signature failed")
 
         pin = self.registry.get(fact.issuer)
@@ -481,7 +766,15 @@ class Ed25519Verifier:
         verified = self.verify_signature(canonical_fact_message(fact), fact.signature, public_key)
         if not verified:
             return self._result(fact, False, 0.0, TRUST_CLASS_UNVERIFIED, "Signature verification failed")
-        return self._result(fact, True, min(fact.confidence or 0.95, 0.95), TRUST_CLASS_ISSUER_SIGNED, None)
+        # An ISSUER_SIGNED fact that nobody actually read is still capped by the
+        # evidence axis — this is the dangerous quadrant the axis exists to expose.
+        capped = min(
+            fact.confidence or 0.95,
+            0.95,
+            evidence_ceiling(fact.evidence_class),
+            source_tier_ceiling(fact),
+        )
+        return self._result(fact, True, capped, TRUST_CLASS_ISSUER_SIGNED, None)
 
     def chain_message(self, chain: CitationChain) -> str:
         return canonical_json({"chain_id": chain.chain_id, "hashes": chain.ordered_hashes()})

package/templates/.claude/skills/goap-research-ed25519/scripts/evidence_fetch.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""
+Evidence fetch — the ONLY place that can mint the artifact behind FETCH_VERIFIED.
+
+Why this file exists (ADR-003). Before it, the package had no network path at all
+(`grep -rn "requests.get\\|urlopen\\|httpx"` over the skill returned nothing), and
+`create_signed_fact(source_content=...)` hashed whatever string the caller passed.
+So `source_hash` was a hash of the agent's own words. Any "did you read it?" class
+assigned on the agent's word would repeat the failure it is meant to catch: the
+model that confidently recites an unread source will just as confidently label it
+verified. A checklist item is satisfied by writing it; only running something
+produces an artifact.
+
+So FETCH_VERIFIED is earned by an artifact obtainable only by performing the
+request: the sha256 of a real response body, its HTTP status, its final URL after
+redirects, and the date it happened.
+
+HONEST SCOPE — printed by every surface that shows the class:
+  FETCH_VERIFIED means "this script issued an HTTP request and received a body
+  with this byte hash on this date".
+  It does NOT mean the source is authoritative, that the claim follows from it,
+  or that the reader understood it. It is provenance, not truth.
+
+Constraints: stdlib only (no new dependency in a medical package); the network is
+never touched implicitly — a caller must ask; offline degrades LOUDLY to
+LISTING_ONLY with a stated reason, it never fails the run.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import http.client
+import ipaddress
+import socket
+from dataclasses import asdict, dataclass, replace
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+from urllib import error as urlerror
+from urllib import request as urlrequest
+from urllib.parse import urlparse
+
+DEFAULT_TIMEOUT_SECONDS = 20
+DEFAULT_MAX_BYTES = 5 * 1024 * 1024  # 5 MiB — a paper/abstract page, not a dataset
+# Hard ceiling the caller cannot raise: `read(max_bytes + 1)` with an unbounded
+# max_bytes is an unbounded-memory path (Codex QE #12).
+HARD_MAX_BYTES = 32 * 1024 * 1024
+DEFAULT_MAX_REDIRECTS = 5
+USER_AGENT = "health-advisor-evidence-fetch/1.0 (+provenance; stdlib urllib)"
+
+# Only these schemes may be fetched. file:// and friends would let a "fetch"
+# read the local disk and pass as network evidence.
+ALLOWED_SCHEMES = ("http", "https")
+
+
+class FetchRefused(ValueError):
+    """The request was refused before any I/O (bad scheme, malformed URL)."""
+
+
+# Process-local witness. A FetchRecord is only accepted as proof if it carries
+# THIS process's token, which is handed out exclusively by fetch_source().
+# HONEST THREAT MODEL (the narrow promise): the adversary here is a MODEL TAKING A
+# SHORTCUT, not an attacker with code execution. Anything running inside this
+# interpreter can read _FETCH_WITNESS and forge a record — in-process Python
+# cannot be made tamper-proof against its own caller, and pretending otherwise
+# would be the very over-claim this feature exists to delete. What this stops is
+# the realistic failure: a caller that constructs a plausible-looking record (a
+# SimpleNamespace, a hand-built FetchRecord) instead of performing the request.
+_FETCH_WITNESS = object()
+
+
+@dataclass(frozen=True)
+class FetchRecord:
+    """Proof-of-fetch. Frozen on purpose: the artifact must not be edited after
+    the fact by the code that consumes it."""
+
+    url: str
+    final_url: str
+    status: int
+    sha256_body: str
+    bytes_len: int
+    fetched_at: str
+    content_type: Optional[str] = None
+    witness: Any = None
+
+    def is_authentic(self) -> bool:
+        """True only for a record minted by fetch_source() in this process."""
+        return self.witness is _FETCH_WITNESS
+
+    @property
+    def ok(self) -> bool:
+        """2xx only. A 404 body is a real body, but it is not the source."""
+        return 200 <= self.status < 300
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serializable view. The witness is a process-local sentinel: exporting it
+        breaks json.dumps, and `asdict()` deep-copies it — destroying the very
+        identity that makes it proof (Codex QE r2). It is deliberately dropped."""
+        data = {k: v for k, v in asdict(self).items() if k != "witness"}
+        data["authentic"] = self.is_authentic()
+        return data
+
+
+@dataclass(frozen=True)
+class FetchFailure:
+    """A named failure. Never raised into the caller's face — the caller degrades
+    to LISTING_ONLY and records `reason` verbatim, so the downgrade is auditable."""
+
+    url: str
+    reason: str
+    attempted_at: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _resolved_addresses(host: str, port: Optional[int]) -> list:
+    """Every address the host resolves to. ALL of them are checked, because a
+    name that resolves to one public and one private address would otherwise
+    pass on the public one and connect on the private one."""
+    try:
+        infos = socket.getaddrinfo(host, port or 0, proto=socket.IPPROTO_TCP)
+    except (socket.gaierror, UnicodeError, ValueError) as exc:
+        raise FetchRefused(f"cannot resolve host {host!r}: {exc}") from exc
+    return [info[4][0] for info in infos]
+
+
+def _is_public_address(address: str) -> bool:
+    try:
+        ip = ipaddress.ip_address(address)
+    except ValueError:
+        return False
+    # Loopback, RFC1918, link-local (incl. 169.254.169.254 cloud metadata),
+    # multicast, reserved — all off limits for evidence fetching.
+    return not (
+        ip.is_private
+        or ip.is_loopback
+        or ip.is_link_local
+        or ip.is_multicast
+        or ip.is_reserved
+        or ip.is_unspecified
+    )
+
+
+def _validate_url(url: str, allow_private: bool = False) -> str:
+    """Scheme + host + destination-address check.
+
+    SSRF matters here even though the body is only hashed: a fetch against an
+    internal address is still a GET with side effects, and the status/length/hash
+    it returns is an oracle about the private network. A research tool has no
+    business reaching anything but public web sources (Codex QE #8).
+
+    `allow_private` exists ONLY for the local test server; it is never set by the
+    library's own code paths.
+    """
+    if not isinstance(url, str):
+        raise FetchRefused(f"refusing non-string URL of type {type(url).__name__}")
+    try:
+        parsed = urlparse(url)
+    except (ValueError, UnicodeError) as exc:  # malformed IPv6, control chars, lone surrogates
+        raise FetchRefused(f"refusing malformed URL {url!r}: {exc}") from exc
+    if parsed.scheme.lower() not in ALLOWED_SCHEMES:
+        raise FetchRefused(
+            f"refusing to fetch scheme {parsed.scheme!r}: only {'/'.join(ALLOWED_SCHEMES)} may back FETCH_VERIFIED"
+        )
+    try:
+        host = parsed.hostname
+        port = parsed.port
+    except ValueError as exc:  # invalid port
+        raise FetchRefused(f"refusing malformed URL {url!r}: {exc}") from exc
+    if not host:
+        raise FetchRefused(f"refusing to fetch malformed URL {url!r}: no host")
+    if allow_private:
+        return url
+    for address in _resolved_addresses(host, port):
+        if not _is_public_address(address):
+            raise FetchRefused(
+                f"refusing to fetch {host!r}: resolves to non-public address {address} "
+                "(loopback/private/link-local are not evidence sources)"
+            )
+    return url
+
+
+class _CappedRedirectHandler(urlrequest.HTTPRedirectHandler):
+    """Redirects are followed but FULLY re-validated — scheme AND destination
+    address. A public URL redirecting into the internal network is the classic
+    SSRF bypass, and checking only the scheme on the hop leaves it open."""
+
+    max_repeats = DEFAULT_MAX_REDIRECTS
+    max_redirections = DEFAULT_MAX_REDIRECTS
+
+    def __init__(self, allow_private: bool = False):
+        super().__init__()
+        self._allow_private = allow_private
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D102
+        _validate_url(newurl, allow_private=self._allow_private)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def fetch_source(
+    url: str,
+    timeout: int = DEFAULT_TIMEOUT_SECONDS,
+    max_bytes: int = DEFAULT_MAX_BYTES,
+    _allow_private: bool = False,
+) -> "FetchRecord | FetchFailure":
+    """Perform the request and return proof of it, or a NAMED failure.
+
+    Never raises for network conditions: an unreachable source is a normal state
+    of the world, and the caller's correct response is to degrade the evidence
+    class, not to abort the research. `_allow_private` is for the test server
+    only — the library never sets it.
+    """
+    try:
+        max_bytes = int(max_bytes)
+    except (TypeError, ValueError):
+        return FetchFailure(url=str(url), reason="max_bytes is not an integer", attempted_at=_now_iso())
+    if max_bytes <= 0 or max_bytes > HARD_MAX_BYTES:
+        return FetchFailure(
+            url=str(url),
+            reason=f"max_bytes must be in 1..{HARD_MAX_BYTES}; refusing an unbounded read",
+            attempted_at=_now_iso(),
+        )
+    try:
+        _validate_url(url, allow_private=_allow_private)
+    except FetchRefused as exc:
+        return FetchFailure(url=str(url), reason=str(exc), attempted_at=_now_iso())
+
+    opener = urlrequest.build_opener(_CappedRedirectHandler(allow_private=_allow_private))
+    try:
+        req = urlrequest.Request(url, headers={"User-Agent": USER_AGENT})
+    except ValueError as exc:
+        return FetchFailure(url=str(url), reason=f"malformed request: {exc}", attempted_at=_now_iso())
+    try:
+        with opener.open(req, timeout=timeout) as response:
+            # Read ONE byte past the cap so truncation is detectable rather than
+            # silent: a truncated body would hash to something that no repeat
+            # fetch could ever reproduce.
+            body = response.read(max_bytes + 1)
+            if len(body) > max_bytes:
+                return FetchFailure(
+                    url=url,
+                    reason=f"response exceeds max_bytes={max_bytes}; refusing to hash a truncated body",
+                    attempted_at=_now_iso(),
+                )
+            status = getattr(response, "status", None) or response.getcode()
+            final_url = response.geturl()
+            content_type = response.headers.get("Content-Type") if response.headers else None
+    except urlerror.HTTPError as exc:
+        # An HTTP error still carries a status — report it as a failure with the
+        # status named, because a 403/404 page is not the source it stands for.
+        return FetchFailure(url=url, reason=f"HTTP {exc.code} {exc.reason}", attempted_at=_now_iso())
+    except (urlerror.URLError, socket.timeout, TimeoutError, OSError, UnicodeError) as exc:
+        return FetchFailure(url=str(url), reason=f"network error: {exc}", attempted_at=_now_iso())
+    except FetchRefused as exc:
+        return FetchFailure(url=url, reason=str(exc), attempted_at=_now_iso())
+    except (http.client.HTTPException, ValueError) as exc:
+        # InvalidURL, bad chunking, control characters in the URL — a NAMED
+        # failure, never an exception in the caller's face (Codex QE #11).
+        return FetchFailure(url=str(url), reason=f"protocol/URL error: {exc}", attempted_at=_now_iso())
+
+    record = FetchRecord(
+        url=url,
+        final_url=final_url,
+        status=int(status),
+        sha256_body=hashlib.sha256(body).hexdigest(),
+        bytes_len=len(body),
+        fetched_at=_now_iso(),
+        content_type=content_type,
+        witness=_FETCH_WITNESS,  # only real fetches carry it
+    )
+    if not record.ok:
+        return FetchFailure(url=url, reason=f"non-2xx status {record.status}", attempted_at=record.fetched_at)
+    return record

package/templates/.claude/skills/goap-research-ed25519/scripts/fixture_legacy_v1_fact.json

@@ -0,0 +1,21 @@
+{
+ "fact": {
+  "claim": "Ference 2012 Mendelian randomization on LDL",
+  "confidence": 0.6,
+  "evidence_class": null,
+  "fetch_date": null,
+  "issuer": "researcher",
+  "issuer_pubkey": "ed25519:DVZqfSVe8GBRSSIK38iOabeJE2YRm1mIUvZCUEGGVGY=",
+  "metadata": {},
+  "parent_citation": null,
+  "parent_hash": null,
+  "research_context": null,
+  "signature": "5g7V4a87VxWpiozUFrPTmCQEkwUVo9rCMFS0nU3ivO1UbDX4PbGteSmKEVdYzhdxumFMkp7tcpy2kQKaBjTLCw==",
+  "source_date": null,
+  "source_hash": "a24eb38dea1b79268072302d9adee7b2e109cb580bb31ff05aa632d390fc694d",
+  "source_url": "https://pubmed.ncbi.nlm.nih.gov/23083789",
+  "timestamp": "2026-08-03T12:16:18.191716Z",
+  "trust_class": "SELF_ATTESTED"
+ },
+ "pubkey_b64": "DVZqfSVe8GBRSSIK38iOabeJE2YRm1mIUvZCUEGGVGY="
+}