@dzhechkov/p-replicator 1.5.17 → 1.6.0

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

@@ -70,8 +70,7 @@ EVIDENCE_CEILINGS = {
 
 # 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.
+# HONEST ROLE: this marker is self-description. 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
@@ -81,6 +80,29 @@ EVIDENCE_CEILINGS = {
 # class of error this feature exists to prevent.
 FACT_SCHEMA_V2 = "fact-v2"
 
+# v3 has LANDED (slice C, ADR-003): study_population, trust_class, confidence and
+# metadata are inside the signed message. The same honest role applies to this
+# marker as to v2's — self-description, not the protection. What protects a v3
+# fact is that its message CONTAINS those four keys, so any reclaim/rewrite
+# rebuilds a different text than the one that was signed.
+FACT_SCHEMA_V3 = "fact-v3"
+
+# The source-tier ceiling applies FROM this schema ONWARD (ADR-005 / D-20).
+# Written as a LOWER BOUND, never as an equality: `!= 2` meant "applies to exactly
+# the schema that introduced it", which silently switched the third ceiling off the
+# moment v3 was minted (MEASURED: an unknown-domain fact went 0.40 → 1.0). A future
+# v4 must not be able to repeat this a third time.
+TIER_CEILING_MIN_SCHEMA = 2
+
+# The schemas this verifier can reconstruct a signed message for. A version outside
+# this tuple is REFUSED, never approximated to the nearest known one (QE G6).
+KNOWN_SCHEMA_VERSIONS = (1, 2, 3)
+
+# `VerificationResult.schema_version` when the fact's own version could not be
+# identified at all. Not 1: reporting an unidentifiable record as "legacy v1" is the
+# same laundering this slice exists to stop.
+SCHEMA_VERSION_UNIDENTIFIED = 0
+
 
 @dataclass
 class PinnedKey:
@@ -105,6 +127,12 @@ class VerificationResult:
     confidence: float
     trust_class: str = TRUST_CLASS_UNVERIFIED
     error: Optional[str] = None
+    # --- what the signature actually covered (ADR-003, D-6) --------------------
+    # Turns "the pre-v3 hole is documented" into "the pre-v3 hole is a VALUE a
+    # caller can branch on". A consumer asking *may I rely on trust_class?* gets an
+    # answer from the object instead of from a paragraph a tired reader skips at 2am.
+    schema_version: int = 1
+    signed_fields: Tuple[str, ...] = ()
 
     def to_dict(self) -> Dict[str, Any]:
         return asdict(self)
@@ -132,6 +160,15 @@ class SignedFact:
     evidence_class: Optional[str] = None
     fetch_date: Optional[str] = None
     source_date: Optional[str] = None
+    # --- applicability axis (slice C / ADR-001). None = legacy fact: the study
+    # population is UNKNOWN, which is neither "stated" nor "unstated-with-reason".
+    # The DTO stays PERMISSIVE on purpose — a loader that refuses to parse a legacy
+    # record cannot report on it, and a record we cannot parse is one we cannot warn
+    # about. The mandatory-ness lives on the five CREATION paths, not here.
+    study_population: Optional[Dict[str, Any]] = None
+    # Self-describing schema version. Signed indirectly, via the "schema" marker in
+    # the v3 message: stripping it makes the verifier rebuild a different text.
+    schema_version: Optional[int] = None
 
     def to_dict(self) -> Dict[str, Any]:
         return asdict(self)
@@ -193,8 +230,16 @@ class CitationChain:
 
 
 def canonical_json(data: Dict[str, Any]) -> str:
-    """Return deterministic JSON for signatures and hashes."""
-    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    """Return deterministic JSON for signatures and hashes.
+
+    `allow_nan=False` (D-18): NaN/Infinity are not JSON, and Python's default emits
+    them as bare `NaN`/`Infinity` tokens that another runtime may reject or reparse
+    differently — a serialization difference on the far side of a signed message is
+    a security bug, not a formatting nit. Signing REFUSES rather than emitting a
+    text no other reader can reproduce. Byte-identical for every value that does
+    not contain NaN/Infinity, so v1/v2 messages are unchanged.
+    """
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True, allow_nan=False)
 
 
 def canonical_fact_message_v1(fact: SignedFact) -> str:
@@ -237,15 +282,175 @@ def canonical_fact_message_v2(fact: SignedFact) -> str:
     )
 
 
+def _canonical_metadata(metadata: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """`metadata` enters the v3 message as a NESTED OBJECT, never as a digest.
+
+    A digest would sign the bytes without letting a reader see what was signed; a
+    nested object keeps the audit trail readable and still tamper-evident, because
+    `canonical_json` sorts keys deterministically. Non-serializable content raises
+    (D-18) instead of being dropped — a silently dropped key is an UNSIGNED key.
+    """
+    payload = dict(metadata or {})
+    try:
+        canonical_json(payload)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            f"metadata is not canonically serializable ({exc}) — refusing to sign a message whose "
+            f"contents cannot be reproduced byte-for-byte by the verifier"
+        ) from None
+    return payload
+
+
+def canonical_fact_message_v3(fact: SignedFact) -> str:
+    """Signed message that ADDITIONALLY covers the fields that decide how far a fact
+    is trusted (ADR-003): `study_population`, `trust_class`, `confidence`, `metadata`.
+
+    Why this is the whole of Part 3: `verify_fact()` selects its verification branch
+    from `fact.trust_class` BEFORE any signature check. While `trust_class` sat
+    outside the signed bytes, a fact signed `ISSUER_SIGNED` under a since-revoked pin
+    could be relabelled `SELF_ATTESTED` with a text editor — the signature still
+    verified (against the embedded key, on a branch that never consults the pin) and
+    the fact came back verified at 0.60. A field that SELECTS the verification branch
+    must be inside the envelope that branch is verifying.
+
+    `confidence` is signed as a FIXED-WIDTH string: float repr differs across
+    runtimes, and a signed message that two runtimes serialize differently is a
+    signature that fails for the wrong reason.
+
+    v1 and v2 remain byte-frozen: this function is additive, never a rewrite of them.
+    """
+    return canonical_json(
+        {
+            "schema": FACT_SCHEMA_V3,
+            "claim": fact.claim,
+            "confidence": format(round(float(fact.confidence or 0.0), 4), ".4f"),
+            "evidence_class": fact.evidence_class,
+            "fetch_date": fact.fetch_date,
+            "issuer": fact.issuer,
+            "metadata": _canonical_metadata(fact.metadata),
+            "research_context": fact.research_context,
+            "source_date": fact.source_date,
+            "source_hash": fact.source_hash,
+            "source_url": fact.source_url,
+            "study_population": fact.study_population,
+            "timestamp": fact.timestamp,
+            "trust_class": fact.trust_class,
+        }
+    )
+
+
+class SchemaVersionError(ValueError):
+    """A fact whose schema cannot be identified. A subclass of ValueError so callers
+    that already handle malformed facts keep working."""
+
+
+def coerce_schema_version(value: Any) -> Optional[int]:
+    """`value` → an integer schema version, or None when it is not one (QE G6).
+
+    `int("not-a-number")` raised an UNCAUGHT ValueError out of the middle of a gate
+    run — a traceback instead of a refusal. Parsing is now total: every input either
+    names a version or names nothing, and the caller decides what to do with nothing.
+    `bool` is rejected explicitly (`True` is not schema 1), and a non-integral float
+    is rejected rather than truncated: `2.9` is not "schema 2".
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value) if float(value).is_integer() else None
+    if isinstance(value, str):
+        try:
+            return int(value.strip())
+        except (TypeError, ValueError):
+            return None
+    return None
+
+
+def schema_version_of_mapping(data: Any) -> int:
+    """The schema dispatch, over a RAW ledger dict.
+
+    ONE definition, two entry points: `fact_schema_version` (a `SignedFact`) delegates
+    here, and the report gate calls it directly on the JSON it loaded. The gate cannot
+    build a `SignedFact` from a partial ledger record — the DTO's fields are mandatory
+    — and a second copy of "which schema is this?" would be free to disagree with this
+    one exactly where it matters.
+    """
+    if not isinstance(data, dict):
+        raise SchemaVersionError(f"schema dispatch needs a mapping, got {type(data).__name__}")
+    declared = data.get("schema_version")
+    if declared is not None:
+        version = coerce_schema_version(declared)
+        if version is None:
+            raise SchemaVersionError(
+                f"schema_version {declared!r} is not an integer — a fact whose schema "
+                f"cannot be identified cannot be verified against any message"
+            )
+        return version
+    if data.get("study_population") is not None:
+        return 3
+    if data.get("evidence_class") is not None:
+        return 2
+    return 1
+
+
 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
+    """Which signed-message schema this fact uses.
+
+    Self-describing first (a v3 fact stores `schema_version=3`), then dispatch by
+    field PRESENCE for records written before that field existed. Both routes are
+    tamper-evident, and for the same reason: whichever version the verifier picks, it
+    rebuilds THAT version's text, and a text that differs from the signed one fails.
+    Stripping `schema_version` from a v3 fact makes it look like v2 → the v2 text is
+    rebuilt → mismatch → refused.
+
+    A `schema_version` that is not an integer raises `SchemaVersionError` — a NAMED
+    refusal that `verify_fact()` converts into `verified=False`, instead of the bare
+    `int()` crash it used to be.
+    """
+    return schema_version_of_mapping({
+        "schema_version": fact.schema_version,
+        "study_population": fact.study_population,
+        "evidence_class": fact.evidence_class,
+    })
+
+
+def signed_fields_for(fact: SignedFact) -> Tuple[str, ...]:
+    """The keys the fact's own signed message actually covers, sorted (D-6).
+
+    Derived from the message that was ACTUALLY built, not from a hand-maintained
+    table — a table would be a second definition of the same truth, and the two
+    would drift. `"schema"` is dropped: it is the marker, not a fact field.
+    """
+    try:
+        payload = json.loads(canonical_fact_message(fact))
+    except Exception:
+        return ()
+    return tuple(sorted(key for key in payload if key != "schema"))
 
 
 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)
+    """Canonical signed message for a fact — dispatched by schema version.
+
+    DISPATCH IS EXACT, NOT A BAND (QE G6). The band `version >= 3` accepted any
+    number at or above 3 as "v3", so `schema_version` could be moved 3 → 99 and the
+    fact still verified: within the band the value is not covered by the signed text,
+    which made a self-describing field silently editable. An unknown version now
+    RAISES — the verifier refuses to guess which text a schema it has never seen was
+    signed against, and `verify_fact()` turns that refusal into `verified=False`.
+    Adding v4 is one new branch, and the refusal is what forces that branch to exist.
+    """
+    version = fact_schema_version(fact)
+    if version == 3:
+        return canonical_fact_message_v3(fact)
+    if version == 2:
+        return canonical_fact_message_v2(fact)
+    if version == 1:
+        return canonical_fact_message_v1(fact)
+    raise SchemaVersionError(
+        f"schema_version {version!r} is not a schema this verifier knows "
+        f"{KNOWN_SCHEMA_VERSIONS} — refusing to reconstruct a message for it"
+    )
 
 
 def evidence_ceiling(evidence_class: Optional[str]) -> float:
@@ -264,15 +469,30 @@ def source_tier_ceiling(fact: SignedFact) -> float:
     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
+    APPLIES FROM SCHEMA v2 ONWARD. 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.
 
+    THE SCOPE IS A LOWER BOUND, NOT AN EQUALITY (ADR-005 / D-20). The condition read
+    `!= 2` — which says "applies to exactly v2" — and the two readings coincided only
+    while 2 was the newest schema. Minting v3 therefore switched this ceiling OFF in
+    silence (MEASURED: the same unknown-domain fact scored 0.40 at schema 2 and 1.0 at
+    schema 3). That is the SAME defect this docstring already records as shipped once,
+    with one difference that makes it worse: the first time the ceiling was never
+    wired; the second time it was wired, tested, and then disarmed by a migration two
+    functions away.
+
     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:
+    try:
+        version = fact_schema_version(fact)
+    except SchemaVersionError:
+        # An unidentifiable schema is the MOST cautious case, not an exempt one: the
+        # same fail-closed reasoning as a missing source_tiers module below.
+        return 0.40
+    if version < TIER_CEILING_MIN_SCHEMA 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
@@ -289,6 +509,49 @@ def source_tier_ceiling(fact: SignedFact) -> float:
         return TIER_CEILINGS.get(TIER_D, 0.40)
 
 
+def _require_study_population(value: Any) -> Dict[str, Any]:
+    """SHAPE-ONLY validation of the `study_population` an author supplies (D-2).
+
+    ARCHITECTURAL CONSTRAINT (05_architecture.md §1.1c): this module must NEVER
+    import `population_match`. A crypto module whose correctness depends on importing
+    a semantics module is exactly the fail-open shape `source_tier_ceiling` was
+    already bitten by — losing a data module SILENTLY RAISED every confidence. So
+    `study_population` crosses the boundary as an OPAQUE JSON dict: the verifier
+    validates its shape, never its meaning, and never interprets a criterion.
+
+    Accepts anything exposing `to_dict()` (e.g. population_match.StudyPopulation)
+    without importing that type — duck-typing here is a boundary, not a shortcut.
+    """
+    if value is None:
+        raise ValueError(
+            "study_population is required — a fact that does not say WHO the finding was measured "
+            "in cannot be checked against any patient. Use StudyPopulation.unstated(reason) if the "
+            "source genuinely does not state it; an unrecorded reason is indistinguishable from a bug."
+        )
+    if hasattr(value, "to_dict") and not isinstance(value, dict):
+        value = value.to_dict()
+    if not isinstance(value, dict):
+        raise ValueError(f"study_population must be a JSON object, got {type(value).__name__}")
+    description = value.get("description")
+    if not isinstance(description, str) or not description.strip():
+        raise ValueError("study_population.description must be a non-empty string")
+    criteria = value.get("criteria") or {}
+    unstated_reason = value.get("unstated_reason") or ""
+    if not criteria and not str(unstated_reason).strip():
+        raise ValueError(
+            "study_population needs at least one criterion, or an explicit unstated_reason — "
+            "`{description: 'adults', criteria: {}}` is present and meaningless"
+        )
+    try:
+        canonical_json(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            f"study_population is not canonically serializable ({exc}) — a key the verifier cannot "
+            f"reproduce byte-for-byte is a key that is not really signed"
+        ) from None
+    return value
+
+
 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()
@@ -485,11 +748,21 @@ class Ed25519Verifier:
         issuer: str,
         metadata: Optional[Dict[str, Any]] = None,
         research_context: Optional[str] = None,
+        *,
+        study_population: Any,
     ) -> SignedFact:
-        """Create a researcher self-attested fact. This never grants issuer trust."""
+        """Create a researcher self-attested fact. This never grants issuer trust.
+
+        `study_population` is KEYWORD-ONLY WITH NO DEFAULT (FR-1, D-1): omitting it is
+        a `TypeError` raised by Python itself, not a validation branch a later author
+        can soften. Keyword-only rather than positional so an un-migrated caller fails
+        AT the call, naming the parameter, instead of silently absorbing its next
+        argument.
+        """
         if self._private_key is None or self._public_key is None:
             raise ValueError("No keypair loaded.")
 
+        population = _require_study_population(study_population)
         source_hash = hashlib.sha256(source_content.encode("utf-8")).hexdigest()
         timestamp = datetime.utcnow().isoformat() + "Z"
         public_key_b64 = self.get_public_key_b64()
@@ -505,6 +778,8 @@ class Ed25519Verifier:
             trust_class=TRUST_CLASS_SELF_ATTESTED,
             research_context=research_context,
             metadata=metadata or {},
+            study_population=population,
+            schema_version=3,
         )
         fact.signature, _ = self.sign_content(canonical_fact_message(fact))
         return fact
@@ -528,11 +803,14 @@ class Ed25519Verifier:
         metadata: Optional[Dict[str, Any]],
         research_context: Optional[str],
         base_confidence: float,
+        *,
+        study_population: Any,
     ) -> 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}")
+        population = _require_study_population(study_population)
         fact = SignedFact(
             claim=claim,
             source_url=source_url,
@@ -548,7 +826,12 @@ class Ed25519Verifier:
             evidence_class=evidence_class,
             fetch_date=fetch_date,
             source_date=source_date,
+            study_population=population,
+            schema_version=3,
         )
+        # ORDERING IS LOAD-BEARING: `confidence` is clamped by the evidence ceiling
+        # ABOVE, before signing. Signing first and clamping after would put a number
+        # in the envelope that the verifier then contradicts.
         fact.signature, _ = self.sign_content(canonical_fact_message(fact))
         return fact
 
@@ -560,6 +843,8 @@ class Ed25519Verifier:
         source_date: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
         research_context: Optional[str] = None,
+        *,
+        study_population: Any,
     ) -> SignedFact:
         """FETCH_VERIFIED — requires proof the request actually happened.
 
@@ -605,6 +890,7 @@ class Ed25519Verifier:
             metadata=meta,
             research_context=research_context,
             base_confidence=0.60,
+            study_population=study_population,
         )
 
     def create_listing_fact(
@@ -617,6 +903,8 @@ class Ed25519Verifier:
         source_date: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
         research_context: Optional[str] = None,
+        *,
+        study_population: Any,
     ) -> 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
@@ -640,6 +928,7 @@ class Ed25519Verifier:
             metadata=meta,
             research_context=research_context,
             base_confidence=0.50,
+            study_population=study_population,
         )
 
     def create_asserted_fact(
@@ -649,6 +938,8 @@ class Ed25519Verifier:
         source_url: str = "",
         metadata: Optional[Dict[str, Any]] = None,
         research_context: Optional[str] = None,
+        *,
+        study_population: Any,
     ) -> 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
@@ -666,6 +957,7 @@ class Ed25519Verifier:
             metadata=metadata,
             research_context=research_context,
             base_confidence=0.0,
+            study_population=study_population,
         )
 
     def create_issuer_signed_fact(
@@ -676,10 +968,13 @@ class Ed25519Verifier:
         issuer: str,
         metadata: Optional[Dict[str, Any]] = None,
         research_context: Optional[str] = None,
+        *,
+        study_population: Any,
     ) -> SignedFact:
         """Create a fact intended to verify against the active pinned key for issuer."""
         if self._public_key is None:
             raise ValueError("No keypair loaded.")
+        population = _require_study_population(study_population)
         source_hash = hashlib.sha256(source_content.encode("utf-8")).hexdigest()
         timestamp = datetime.utcnow().isoformat() + "Z"
         fact = SignedFact(
@@ -694,6 +989,8 @@ class Ed25519Verifier:
             trust_class=TRUST_CLASS_ISSUER_SIGNED,
             research_context=research_context,
             metadata=metadata or {},
+            study_population=population,
+            schema_version=3,
         )
         fact.signature, _ = self.sign_content(canonical_fact_message(fact))
         return fact
@@ -706,6 +1003,12 @@ class Ed25519Verifier:
         trust_class: str,
         error: Optional[str],
     ) -> VerificationResult:
+        try:
+            schema_version = fact_schema_version(fact)
+        except SchemaVersionError:
+            # The result object must be constructible for EVERY fact, including the
+            # one whose version is the reason it is being refused (QE G6).
+            schema_version = SCHEMA_VERSION_UNIDENTIFIED
         result = VerificationResult(
             verified=verified,
             content_hash=fact.source_hash,
@@ -716,10 +1019,55 @@ class Ed25519Verifier:
             confidence=confidence,
             trust_class=trust_class,
             error=error,
+            schema_version=schema_version,
+            signed_fields=signed_fields_for(fact),
         )
         self.verification_ledger.append(result)
         return result
 
+    def _schema_refusal(self, fact: SignedFact) -> Optional[str]:
+        """The refusal text for a fact whose schema cannot be identified, or None.
+
+        Two ways a schema is unusable, and both used to end in a traceback rather than
+        a verdict (QE G6): a `schema_version` that is not an integer at all, and one
+        that is an integer this verifier has no message builder for.
+        """
+        try:
+            version = fact_schema_version(fact)
+        except SchemaVersionError as exc:
+            return str(exc)
+        if version not in KNOWN_SCHEMA_VERSIONS:
+            return (
+                f"schema_version {version} is not one of {KNOWN_SCHEMA_VERSIONS} — this verifier "
+                f"cannot reconstruct the message such a fact would have been signed against"
+            )
+        return None
+
+    def _legacy_reclaim_belt(self, fact: SignedFact) -> Optional[str]:
+        """BOUNDED BELT for pre-v3 facts, not a closure (M3.7).
+
+        A v1/v2 fact never signed its `trust_class`, so the §0.1 reclaim attack
+        remains available against every record signed before this slice. What CAN be
+        checked is the one field those schemas DO sign: `issuer`. So if a fact claims
+        SELF_ATTESTED while its issuer holds a NON-ACTIVE pin, refuse — the attacker
+        cannot redirect the lookup, because `issuer` is inside the signed bytes.
+
+        HONEST SCOPE: an UNPINNED issuer's fact is still launderable to
+        SELF_ATTESTED @ 0.60. That residual is unclosable for bytes signed without
+        `trust_class`, and it is named in SKILL.md rather than papered over.
+        """
+        if fact_schema_version(fact) >= 3:
+            return None
+        if fact.trust_class != TRUST_CLASS_SELF_ATTESTED:
+            return None
+        pin = self.registry.get(fact.issuer)
+        if pin is not None and pin.status != "active":
+            return (
+                f"legacy fact claims {TRUST_CLASS_SELF_ATTESTED} but its issuer's pinned key is "
+                f"{pin.status} — pre-v3 facts do not sign trust_class, so the claim cannot be trusted"
+            )
+        return None
+
     def verify_fact(self, fact: SignedFact) -> VerificationResult:
         """
         Verify a signed fact.
@@ -731,8 +1079,20 @@ class Ed25519Verifier:
         if not fact.issuer_pubkey.startswith("ed25519:"):
             return self._result(fact, False, 0.0, TRUST_CLASS_UNVERIFIED, "Invalid public key format")
 
+        # A fact whose schema cannot be identified is REFUSED, never crashed on and
+        # never guessed at (QE G6). This is deliberately the FIRST substantive check:
+        # every branch below reconstructs a message, and there is no message to
+        # reconstruct for a schema this verifier does not know.
+        schema_refusal = self._schema_refusal(fact)
+        if schema_refusal is not None:
+            return self._result(fact, False, 0.0, TRUST_CLASS_UNVERIFIED, schema_refusal)
+
         embedded_pubkey_b64 = strip_ed25519_prefix(fact.issuer_pubkey)
 
+        legacy_refusal = self._legacy_reclaim_belt(fact)
+        if legacy_refusal is not None:
+            return self._result(fact, False, 0.0, TRUST_CLASS_UNVERIFIED, legacy_refusal)
+
         if fact.trust_class == TRUST_CLASS_SELF_ATTESTED:
             try:
                 public_key = decode_pubkey_b64(embedded_pubkey_b64)
@@ -887,12 +1247,23 @@ if __name__ == "__main__":
     verifier = Ed25519Verifier(trusted_issuers={"nature.com": {"pubkey_b64": issuer_pubkey, "status": "active"}})
     issuer.load_keypair(issuer._private_key, issuer._public_key)
 
+    # The demo is user-facing example code, so it must MODEL the required argument
+    # rather than route around it. This is the shape a caller should copy.
+    DEMO_POPULATION = {
+        "description": "adults aged 40-70 enrolled in the demo cohort",
+        "criteria": {
+            "age": {"op": "range", "value": [40, 70], "kind": "eligibility",
+                    "verbatim": "adults aged 40-70", "locator": "[Methods, Participants]"},
+        },
+    }
+
     fact = issuer.create_issuer_signed_fact(
         claim="The study found a 25% improvement in efficiency",
         source_url="https://nature.com/articles/example",
         source_content="Full article content here...",
         issuer="nature.com",
         research_context="demo-run",
+        study_population=DEMO_POPULATION,
     )
     result = verifier.verify_fact(fact)
     print("[1] Pinned issuer fact")
@@ -907,6 +1278,7 @@ if __name__ == "__main__":
         source_url="https://nature.com/articles/example",
         source_content="Fake content",
         issuer="nature.com",
+        study_population=DEMO_POPULATION,
     )
     forged_result = verifier.verify_fact(forged)
     print("[2] Attacker self-signed trusted string")
@@ -924,6 +1296,7 @@ if __name__ == "__main__":
                 source_content=f"Source content {i + 1}",
                 issuer="nature.com",
                 research_context="demo-run",
+                study_population=DEMO_POPULATION,
             )
         )
     issuer.sign_chain(chain)

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

@@ -0,0 +1,23 @@
+{
+ "fact": {
+  "claim": "Omega-3 raised LDL by 44.5% at baseline triglycerides >= 800 mg/dL",
+  "confidence": 0.5,
+  "evidence_class": "LISTING_ONLY",
+  "fetch_date": null,
+  "issuer": "researcher",
+  "issuer_pubkey": "ed25519:DDG6cj/Q0iJRBvk8lXHissMSQeV7GQQCnYSEysbhV74=",
+  "metadata": {
+   "evidence_note": "card seen in the search listing; the full text was never opened"
+  },
+  "parent_citation": null,
+  "parent_hash": null,
+  "research_context": null,
+  "signature": "i9kvNmONaCdlggJQRa5gaqMeQNDvChZ4ehEO9QFqYtRXFUk43ycHCu6aDdoxszOKuZY/uL8tYgsZ0GgbtOBaBA==",
+  "source_date": "2012-11-01",
+  "source_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "source_url": "https://pubmed.ncbi.nlm.nih.gov/23083789",
+  "timestamp": "2026-08-04T21:11:31.577264Z",
+  "trust_class": "SELF_ATTESTED"
+ },
+ "pubkey_b64": "DDG6cj/Q0iJRBvk8lXHissMSQeV7GQQCnYSEysbhV74="
+}