feat(okf): trust_tier derives three tiers from the actor prefix

Co-Authored-By: Claude <claude-opus-5>

src/portfolio_optimiser/okf.py

@@ -371,6 +371,53 @@ class SkippedLink:
     reason: SkipReason
 
 
+#: A concept's trust level, derived from its ``verified`` actors (SPEC §5.3), lowest to highest.
+#: Derived, never stored: OKF records objective signals and refuses to persist a subjective score,
+#: so this is a reading of the actors and not a field any document carries.
+TrustTier = Literal["unverified", "machine-confirmed", "human-reviewed"]
+
+#: The ONE actor prefix that raises a concept to the human tier (SPEC §7 actor convention).
+_HUMAN_ACTOR_PREFIX = "human:"
+
+
+def trust_tier(entries: tuple[dict[str, str], ...] | None) -> TrustTier:
+    """Derive the trust tier from ``verified`` entries (SPEC §5.3).
+
+    ``None`` or empty ⇒ ``unverified``; any actor whose ``by`` STARTS WITH ``human:`` ⇒
+    ``human-reviewed``; otherwise ⇒ ``machine-confirmed``.
+
+    **Prefix, never substring.** ``by: bot/human:2`` is a machine actor whose identifier merely
+    contains the token, and a substring test would promote it — minting a human sign-off nobody
+    gave, which is the fabricated-provenance defect one level down.
+
+    **An entry that names NO actor is REFUSED, never tiered.** "Otherwise ⇒ machine-confirmed"
+    would derive a trust level from an entry that identifies nobody. ``decode_flow_value`` already
+    refuses that shape when it reads a ``verified`` value; this function is public, so it ASSERTS
+    the invariant at its own door instead of assuming its caller came through that one. No new
+    exception type: the named refusal for this condition belongs to the decoder, and a second class
+    here would imply a second rule.
+
+    **Entry count is not a tier.** SPEC §5.3 derives the tier from the actor prefix alone, so a
+    two-entry machine list stays ``machine-confirmed``.
+
+    Gated by ``tests/test_provenance_decoder_loadbearing.py``."""
+    if not entries:
+        return "unverified"
+    actors: list[str] = []
+    for entry in entries:
+        actor = entry.get("by", "").strip()
+        if not actor:
+            raise ValueError(
+                f"a verification entry {entry!r} names no `by` actor — SPEC §5.2 makes it "
+                "required, and deriving a trust tier from an entry that identifies nobody would "
+                "mint the provenance it claims to read"
+            )
+        actors.append(actor)
+    if any(actor.startswith(_HUMAN_ACTOR_PREFIX) for actor in actors):
+        return "human-reviewed"
+    return "machine-confirmed"
+
+
 #: WHY a provenance value could not be read. The tokens name the SHAPE the value is written in
 #: and NOTHING else — the same discipline ``SkipReason`` carries. A block sequence and a block
 #: mapping are both CONFORMANT OKF (SPEC §5.2 writes ``verified`` in exactly those forms); they are