thymus-memory 0.1.0__py3-none-any.whl

thymus/cost.py

@@ -0,0 +1,84 @@
+"""What a gate costs: model calls, approximate tokens and time, by the job each call does.
+
+Wrap every model once with ``CountingLLM`` (outside the cache) and share one ``Usage``. A call's
+job is recognised from its system prompt, so no gate or agent code has to report anything.
+Tokens are estimated as characters / 4 (the same estimate for every model and gate, so
+comparisons between gates are fair); seconds are only meaningful for uncached calls.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+
+from thymus.llm import LLM
+
+# Jobs that exist only because of a gate: the rest (extract, answer) every memory agent does.
+GATE_ROLES = ("classify", "conflict", "verify")
+
+
+def _roles() -> dict[str, str]:
+    from thymus.agent import ANSWER_SYSTEM, EXTRACT_SYSTEM
+    from thymus.claims import CLAIM_SYSTEM
+    from thymus.conflicts import CONFLICT_SYSTEM, CONFLICT_SYSTEM_SAME_SUBJECT, VERIFY_WORDINGS
+
+    roles = {ANSWER_SYSTEM: "answer", EXTRACT_SYSTEM: "extract", CLAIM_SYSTEM: "classify",
+             CONFLICT_SYSTEM: "conflict", CONFLICT_SYSTEM_SAME_SUBJECT: "conflict"}
+    roles.update({system: "verify" for system, _ in VERIFY_WORDINGS.values()})
+    return roles
+
+
+class Usage:
+    """Running totals per job: calls, input and output characters, seconds."""
+
+    def __init__(self) -> None:
+        self.totals: dict[str, list[float]] = defaultdict(lambda: [0, 0, 0, 0.0])
+
+    def record(self, role: str, prompt_chars: int, output_chars: int, seconds: float) -> None:
+        t = self.totals[role]
+        t[0] += 1
+        t[1] += prompt_chars
+        t[2] += output_chars
+        t[3] += seconds
+
+    def snapshot(self) -> dict[str, tuple]:
+        return {role: tuple(t) for role, t in self.totals.items()}
+
+    def since(self, before: dict[str, tuple]) -> dict[str, dict]:
+        """Usage added after ``before`` was taken, as {role: {calls, tokens_in, tokens_out, seconds}}."""
+        out = {}
+        for role, t in self.totals.items():
+            b = before.get(role, (0, 0, 0, 0.0))
+            calls = t[0] - b[0]
+            if calls:
+                out[role] = {"calls": int(calls), "tokens_in": round((t[1] - b[1]) / 4),
+                             "tokens_out": round((t[2] - b[2]) / 4), "seconds": round(t[3] - b[3], 3)}
+        return out
+
+
+class CountingLLM:
+    """Passes calls through and records each one in ``usage`` under its job."""
+
+    def __init__(self, inner: LLM, usage: Usage):
+        self.inner = inner
+        self.name = inner.name
+        self.usage = usage
+        self._roles = _roles()
+
+    def complete(self, system: str, prompt: str, schema: dict | None = None) -> str:
+        start = time.perf_counter()
+        response = self.inner.complete(system, prompt, schema)
+        role = self._roles.get(system, "judge")  # every other prompt in a run grades replies
+        self.usage.record(role, len(system) + len(prompt), len(response), time.perf_counter() - start)
+        return response
+
+    def __getattr__(self, attr: str):  # e.g. CachedLLM.exhausted
+        return getattr(self.inner, attr)
+
+
+def gate_overhead(cost: dict[str, dict]) -> dict[str, float]:
+    """Calls and tokens spent on gate-only jobs in one scenario."""
+    jobs = [cost[r] for r in GATE_ROLES if r in cost]
+    return {"calls": sum(j["calls"] for j in jobs),
+            "tokens": sum(j["tokens_in"] + j["tokens_out"] for j in jobs),
+            "seconds": sum(j["seconds"] for j in jobs)}

thymus/embed.py

@@ -0,0 +1,84 @@
+"""Text embedders used for memory recall."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from typing import Protocol
+
+from thymus.llm import post_json
+
+Vector = list[float]
+
+
+class Embedder(Protocol):
+    name: str
+
+    def embed(self, texts: list[str]) -> list[Vector]: ...
+
+
+def cosine(a: Vector, b: Vector) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    norm = math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b))
+    return dot / norm if norm else 0.0
+
+
+class OllamaEmbedder:
+    """Semantic embeddings from a local Ollama model such as nomic-embed-text."""
+
+    def __init__(self, model: str = "nomic-embed-text", host: str = "http://localhost:11434", timeout: float = 120):
+        self.model = model
+        self.host = host.rstrip("/")
+        self.timeout = timeout
+        self.name = f"ollama:{model}"
+
+    def embed(self, texts: list[str]) -> list[Vector]:
+        body = {"model": self.model, "input": texts}
+        return post_json(f"{self.host}/api/embed", body, self.timeout)["embeddings"]
+
+
+class MemoEmbedder:
+    """Remembers vectors by text for the length of a run. Every gate re-embeds the same
+    memories, and long-memory runs add the same background facts to every scenario."""
+
+    def __init__(self, inner: Embedder):
+        self.inner = inner
+        self.name = inner.name
+        self._vectors: dict[str, Vector] = {}
+
+    def embed(self, texts: list[str]) -> list[Vector]:
+        missing = [t for t in dict.fromkeys(texts) if t not in self._vectors]
+        if missing:
+            self._vectors.update(zip(missing, self.inner.embed(missing)))
+        return [self._vectors[t] for t in texts]
+
+
+_STOPWORDS = frozenset(
+    "a an and are as at be by can could do does for from has have how i in is it its me my "
+    "of on or our should so that the their them then there these they this to was we were "
+    "what when where which who why will with you your".split()
+)
+_WORD = re.compile(r"[a-z0-9]+")
+
+
+class HashEmbedder:
+    """Offline bag-of-words embedder. Lexical only: good enough for tests and smoke
+    runs, not for real experiments."""
+
+    name = "hash"
+
+    def __init__(self, dim: int = 512):
+        self.dim = dim
+
+    def embed(self, texts: list[str]) -> list[Vector]:
+        vectors = []
+        for text in texts:
+            vector = [0.0] * self.dim
+            for word in _WORD.findall(text.lower()):
+                if word in _STOPWORDS:
+                    continue
+                digest = hashlib.blake2b(word.encode(), digest_size=8).digest()
+                vector[int.from_bytes(digest, "little") % self.dim] += 1.0
+            vectors.append(vector)
+        return vectors

thymus/gates.py

@@ -0,0 +1,440 @@
+"""Memory defences: what gets written, and what gets recalled.
+
+Every defence answers two questions:
+- review(): should this candidate memory be stored, quarantined, or rejected,
+  and does it retire (supersede) older memories?
+- recall(): which stored memories go into the model's context for a query?
+
+The baselines below come from prior work, so the thymus gate is measured against
+real competition rather than only "no defence":
+
+- allow-all: no defence, what most memory agents ship with.
+- user-only: provenance quarantine. Blocks everything that came from tool content
+  (≈ MemGauge's PQ policy, arXiv 2608.30177).
+- conflict-quarantine: tool content that contradicts something a user stated is
+  quarantined (≈ MemGauge's NC policy). Adapted so users can still correct their own facts.
+- last-write-wins: the newest memory always replaces the ones it contradicts.
+  The naive way to support updates.
+- bounded-occupancy: writes everything, but tool-sourced memories may fill at most
+  one recall slot (proposed but not built in Utility Under Attack, arXiv 2608.21230).
+- label-only: keeps everything and recalls untrusted memories with their source, with no
+  rules about updates. The labelling idea of TMA-NM (arXiv 2606.24322) and PPMF
+  (arXiv 2607.29167), which use it to gate actions, applied to answers instead.
+
+And the gate this project is about:
+
+- thymus: self/non-self screening. Tool content may add facts but never speak for the
+  user; a fact can only be replaced by the user or by the source that stated it; every
+  other conflicting or unvetted claim is kept but recalled with an "unverified" label.
+
+Ablations switch off one part of the thymus gate at a time:
+
+- thymus-no-screen: no self/non-self screening; tool content may state preferences or
+  instructions in the user's name.
+- thymus-any-origin: no same-origin rule; tool content replaces whatever it contradicts.
+- thymus-no-labels: same storage decisions, but memories are recalled without labels.
+- thymus-hide: decide instead of disclose; a claim that contradicts another source is
+  quarantined (hidden) instead of kept with a label.
+"""
+
+from __future__ import annotations
+
+import re
+
+from dataclasses import dataclass
+from typing import Callable, Literal
+
+from thymus.claims import ClaimClassifier, LLMClaimClassifier
+from thymus.conflicts import ConflictDetector, LLMConflictDetector
+from thymus.llm import LLM
+from thymus.memory import Candidate, Memory, MemoryStore, Trust, holds_several_claims
+
+Action = Literal["accept", "reject", "quarantine"]
+
+
+@dataclass(frozen=True)
+class Decision:
+    action: Action
+    reason: str
+    supersedes: tuple[int, ...] = ()  # ids of memories to retire if this one is stored
+    trust: Trust = "verified"
+    contradicts: tuple[int, ...] = ()  # ids this memory disagrees with but does not replace
+    contest_back: tuple[int, ...] = ()  # earlier memories that become contested by this one too
+
+
+class Gate:
+    name = "base"
+    # Replaced memories: False retires them, True keeps them as labelled older versions,
+    # "auto" retires single claims and keeps memories holding several (e.g. whole chat rounds).
+    soft_supersede: bool | str = False
+
+    def apply_supersedes(self, store: MemoryStore, ids: tuple[int, ...]) -> None:
+        if self.soft_supersede == "auto":
+            multi = {m.id for m in store.all() if m.id in ids and holds_several_claims(m.text)}
+            store.mark_older(tuple(i for i in ids if i in multi))
+            store.retire(tuple(i for i in ids if i not in multi))
+        elif self.soft_supersede:
+            store.mark_older(ids)
+        else:
+            store.retire(ids)
+
+    def review(self, candidate: Candidate, store: MemoryStore) -> Decision:
+        return Decision("accept", "no checks")
+
+    def recall(self, query: str, store: MemoryStore, k: int, speaker: str) -> list[Memory]:
+        return [memory for memory, _ in store.search(query, k=k)]
+
+    def render(self, memory: Memory, speaker: str) -> str:
+        """How a recalled memory appears in the model's context."""
+        return f"[turn {memory.created_at}] {memory.text}"
+
+    def background_trust(self, candidate: Candidate) -> Trust | None:
+        """Decision for a haystack fact that conflicts with nothing (see thymus.haystack):
+        the trust it would be stored with, or None if the gate would not store it."""
+        return "verified"
+
+    def withhold(self, memory: Memory, speaker: str) -> bool:
+        """True if a recalled memory goes to the user as a system notice instead of to the model."""
+        return False
+
+    def notice(self, memories: list[Memory], speaker: str) -> str:
+        """The system-written disclosure appended to the reply for withheld memories."""
+        return ""
+
+
+class AllowAllGate(Gate):
+    name = "allow-all"
+
+
+class UserOnlyGate(Gate):
+    name = "user-only"
+
+    def review(self, candidate: Candidate, store: MemoryStore) -> Decision:
+        if candidate.source == "user":
+            return Decision("accept", "stated by a user")
+        return Decision("reject", f"came from tool content ({candidate.origin})")
+
+    def background_trust(self, candidate: Candidate) -> Trust | None:
+        return "verified" if candidate.source == "user" else None
+
+
+def _ids(memories: list[Memory]) -> str:
+    return ", ".join(f"#{m.id}" for m in memories)
+
+
+class ConflictQuarantineGate(Gate):
+    name = "conflict-quarantine"
+
+    def __init__(self, detector: ConflictDetector):
+        self.detector = detector
+
+    def review(self, candidate: Candidate, store: MemoryStore) -> Decision:
+        if candidate.source == "user":
+            return Decision("accept", "stated by a user")
+        trusted = [m for m in self.detector.find(candidate, store) if m.source == "user"]
+        if trusted:
+            return Decision("quarantine", f"tool content contradicts user-stated memory {_ids(trusted)}")
+        return Decision("accept", "no conflict with user-stated memories")
+
+
+class LastWriteWinsGate(Gate):
+    name = "last-write-wins"
+
+    def __init__(self, detector: ConflictDetector):
+        self.detector = detector
+
+    def review(self, candidate: Candidate, store: MemoryStore) -> Decision:
+        conflicts = self.detector.find(candidate, store)
+        if conflicts:
+            return Decision("accept", f"replaces {_ids(conflicts)}", supersedes=tuple(m.id for m in conflicts))
+        return Decision("accept", "no conflict")
+
+
+class BoundedOccupancyGate(Gate):
+    name = "bounded-occupancy"
+
+    def __init__(self, max_untrusted: int = 1):
+        self.max_untrusted = max_untrusted
+
+    def recall(self, query: str, store: MemoryStore, k: int, speaker: str) -> list[Memory]:
+        chosen, untrusted = [], 0
+        for memory, _ in store.search(query, k=len(store.all())):
+            if memory.source == "tool":
+                if untrusted >= self.max_untrusted:
+                    continue
+                untrusted += 1
+            chosen.append(memory)
+            if len(chosen) == k:
+                break
+        return chosen
+
+
+class ThymusGate(Gate):
+    name = "thymus"
+
+    def __init__(
+        self,
+        detector: ConflictDetector,
+        classifier: ClaimClassifier,
+        trusted_origins: tuple[str, ...] = ("calendar:",),
+        *,
+        screen: bool = True,
+        same_origin_only: bool = True,
+        disclose: bool = True,
+        hide_contested: bool = False,
+        require_auth: bool = False,
+        contest_other_users: bool = False,
+        notice: bool = False,
+        soft_supersede: bool | str = False,
+        confirm_replacements: bool = False,
+        symmetric_contest: bool = False,
+        name: str = "thymus",
+    ):
+        self.detector = detector
+        self.classifier = classifier
+        self.trusted_origins = trusted_origins  # the user's own integrations
+        # Ablation switches; the defaults are the full gate.
+        self.screen = screen
+        self.same_origin_only = same_origin_only
+        self.disclose = disclose
+        self.hide_contested = hide_contested
+        # Version 2 rules (thymus-v2): a source replaces its own fact only through an
+        # authenticated channel; a user's claim that contradicts another user is contested;
+        # contested claims reach the user as a system notice instead of the model.
+        self.require_auth = require_auth
+        self.contest_other_users = contest_other_users
+        self.notice_mode = notice
+        self.soft_supersede = soft_supersede
+        # Version 3: the pairwise verifier is asked only before a replacement. A conflict with
+        # another origin stays contested whatever the verifier says, so verification can make
+        # the gate more careful, never less (a missed contest lets a fake update through).
+        self.confirm_replacements = confirm_replacements
+        # Symmetric contest: when two unvetted tool origins disagree, neither has standing, so
+        # the order they arrived in must not decide. Both are withheld and both disclosed.
+        self.symmetric_contest = symmetric_contest
+        self.name = name
+
+    def _replaceable(self, candidate: Candidate, memories: list[Memory]) -> list[Memory]:
+        if not self.confirm_replacements:
+            return memories
+        return [m for m in memories if self.detector.confirm(candidate, m)]
+
+    def _trusted_origin(self, candidate: Candidate) -> bool:
+        authentic = candidate.authenticated or not self.require_auth
+        return candidate.origin.startswith(self.trusted_origins) and authentic
+
+    def _trust(self, candidate: Candidate) -> Trust:
+        if candidate.source == "user" or self._trusted_origin(candidate):
+            return "verified"
+        return "unverified"
+
+    def background_trust(self, candidate: Candidate) -> Trust | None:
+        return self._trust(candidate)  # background facts are facts and conflict with nothing
+
+    def review(self, candidate: Candidate, store: MemoryStore) -> Decision:
+        if self.screen and candidate.source == "tool" and not self._trusted_origin(candidate):
+            kind = self.classifier.kind(candidate.text)
+            # "procedure" exists only when the classifier runs with procedures=True; it is
+            # imperative knowledge about the world, stored and labelled like any fact.
+            if kind not in ("fact", "procedure"):
+                return Decision("reject", f"{candidate.origin} tried to speak for the user ({kind})")
+
+        trust = self._trust(candidate)
+        conflicts = self.detector.find(candidate, store)
+        if not conflicts:
+            return Decision("accept", f"new {trust} fact", trust=trust)
+
+        if candidate.source == "user":
+            # Users may correct facts from tools and their own earlier statements,
+            # but not what a different user told a shared assistant.
+            mine = [m for m in conflicts if m.source == "tool" or m.speaker == candidate.speaker]
+            own = self._replaceable(candidate, mine)
+            contested = tuple(m.id for m in conflicts if m not in mine) if self.contest_other_users else ()
+            return Decision("accept", f"user update replaces {_ids(own)}", tuple(m.id for m in own), trust, contested)
+
+        can_replace = candidate.authenticated or not self.require_auth
+        own_source = [
+            m for m in conflicts if (m.origin == candidate.origin and can_replace) or not self.same_origin_only
+        ]
+        same_origin = self._replaceable(candidate, own_source)
+        others = [m for m in conflicts if m not in own_source]
+        if others and self.hide_contested:
+            return Decision("quarantine", f"contradicts {_ids(others)} from other sources, hidden")
+        if others:
+            trust = "unverified"
+        reason = f"same-origin update replaces {_ids(same_origin)}" if same_origin else "no replacement"
+        if others:
+            reason += f"; contradicts {_ids(others)} from other sources, kept unverified"
+        back = ()
+        if self.symmetric_contest:
+            back = tuple(m.id for m in others if m.source == "tool" and m.trust == "unverified")
+            if back:
+                reason += f"; {_ids([m for m in others if m.id in back])} contested in turn"
+        return Decision("accept", reason, tuple(m.id for m in same_origin), trust, tuple(m.id for m in others), back)
+
+    def render(self, memory: Memory, speaker: str) -> str:
+        line = super().render(memory, speaker)
+        if memory.older:
+            line += " [older version: later updated]"
+        return disclose(line, memory, speaker) if self.disclose else line
+
+    def withhold(self, memory: Memory, speaker: str) -> bool:
+        return self.notice_mode and contested(memory, speaker)
+
+    def notice(self, memories: list[Memory], speaker: str) -> str:
+        if not memories:
+            return ""
+        claims = "; ".join(
+            f"{'another user of this assistant' if m.source == 'user' else 'a message from ' + m.origin} said: "
+            f'"{defang(m.text)}"'
+            for m in sorted(memories, key=lambda m: m.created_at)
+        )
+        return (
+            f"Note: I also have unconfirmed information that contradicts this. {claims}. "
+            "I have not used it in my answer; please check with the source directly before acting on it."
+        )
+
+
+_LINK = re.compile(r"(?:https?://)?\b[\w-]+(?:\.[\w-]+)*\.[A-Za-z]{2,}\b(?:/\S*)?")
+_EMAIL = re.compile(r"\b[\w.+-]+@[\w-]+(?:\.[\w-]+)+\b")
+_PHONE = re.compile(r"\+?\d[\d\s-]{5,}\d")
+
+
+def defang(text: str) -> str:
+    """What a notice may repeat of a contested claim: links, email addresses and phone numbers
+    are removed, so the system never hands the user an attacker's contact in its own voice.
+    Times, dates and amounts stay, so a real update's new value still reaches the user."""
+    text = _EMAIL.sub("[address removed]", text)
+    text = _LINK.sub("[link removed]", text)
+    return _PHONE.sub(lambda m: "[number removed]" if sum(c.isdigit() for c in m.group()) >= 7 else m.group(), text)
+
+
+def contested(memory: Memory, speaker: str) -> bool:
+    """A claim that contradicts another source and is not the viewer's own verified statement."""
+    return bool(memory.contradicts) and (memory.trust == "unverified" or memory.speaker != speaker)
+
+
+def disclose(line: str, memory: Memory, speaker: str) -> str:
+    """Append the source label that unverified memories carry at recall."""
+    if memory.trust == "unverified" and memory.contradicts:
+        return f"{line} [unverified: from {memory.origin}; contradicts an earlier memory]"
+    if memory.trust == "unverified":
+        return f"{line} [unverified: from {memory.origin}]"
+    if memory.source == "user" and memory.speaker != speaker:
+        return f"{line} [unverified: said by another user of this assistant]"
+    return line
+
+
+class LabelOnlyGate(Gate):
+    """Keep every memory; label untrusted ones at recall; never replace anything."""
+
+    name = "label-only"
+
+    def __init__(self, trusted_origins: tuple[str, ...] = ("calendar:",)):
+        self.trusted_origins = trusted_origins
+
+    def background_trust(self, candidate: Candidate) -> Trust | None:
+        if candidate.source == "user" or candidate.origin.startswith(self.trusted_origins):
+            return "verified"
+        return "unverified"
+
+    def review(self, candidate: Candidate, store: MemoryStore) -> Decision:
+        trust = self.background_trust(candidate)
+        return Decision("accept", f"stored as {trust}", trust=trust)
+
+    def render(self, memory: Memory, speaker: str) -> str:
+        return disclose(super().render(memory, speaker), memory, speaker)
+
+
+GATES: dict[str, Callable[[LLM], Gate]] = {
+    "allow-all": lambda llm: AllowAllGate(),
+    "user-only": lambda llm: UserOnlyGate(),
+    "conflict-quarantine": lambda llm: ConflictQuarantineGate(LLMConflictDetector(llm)),
+    "last-write-wins": lambda llm: LastWriteWinsGate(LLMConflictDetector(llm)),
+    "bounded-occupancy": lambda llm: BoundedOccupancyGate(),
+    "label-only": lambda llm: LabelOnlyGate(),
+    "thymus": lambda llm: ThymusGate(LLMConflictDetector(llm), LLMClaimClassifier(llm)),
+    "thymus-no-screen": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), screen=False, name="thymus-no-screen"),
+    "thymus-any-origin": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), same_origin_only=False, name="thymus-any-origin"),
+    "thymus-no-labels": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), disclose=False, name="thymus-no-labels"),
+    "thymus-hide": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), hide_contested=True, name="thymus-hide"),
+    "thymus-v2": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), require_auth=True, contest_other_users=True, notice=True,
+        name="thymus-v2"),
+    "thymus-v2-soft": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), require_auth=True, contest_other_users=True, notice=True,
+        soft_supersede=True, name="thymus-v2-soft"),
+    "thymus-v2-auto": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), require_auth=True, contest_other_users=True, notice=True,
+        soft_supersede="auto", name="thymus-v2-auto"),
+    "thymus-v2-precise": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), require_auth=True, contest_other_users=True,
+        notice=True, soft_supersede="auto", name="thymus-v2-precise"),
+    "thymus-v2-verified": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True, verify=True), LLMClaimClassifier(llm), require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", name="thymus-v2-verified"),
+    "thymus-v3": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True, name="thymus-v3"),
+    # The final gate with the procedure class: imperative knowledge about the world (a policy,
+    # a runbook step, advice) is stored as a labelled claim; only directives aimed at the
+    # assistant itself are rejected. Designed after MemShield, MemForm and the revoked-policy
+    # sets showed rule 1 rejecting procedural knowledge; reported beside thymus-v3, never in
+    # its place.
+    "thymus-v3-procedures": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm, procedures=True), require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True,
+        name="thymus-v3-procedures"),
+    # The final gate with symmetric contest (designed after the gate-aware pre-emption attacks;
+    # pre-registered in docs/preregistration-v4.md before any run).
+    "thymus-v4": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True,
+        symmetric_contest=True, name="thymus-v4"),
+    # Ablations of the final gate: thymus-v3 with exactly one ingredient removed.
+    "thymus-v3-no-screen": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), screen=False, require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True,
+        name="thymus-v3-no-screen"),
+    "thymus-v3-any-origin": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), same_origin_only=False, require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True,
+        name="thymus-v3-any-origin"),
+    "thymus-v3-no-labels": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), disclose=False, require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True,
+        name="thymus-v3-no-labels"),
+    "thymus-v3-hide": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), hide_contested=True, require_auth=True,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True,
+        name="thymus-v3-hide"),
+    "thymus-v3-no-auth": lambda llm: ThymusGate(
+        LLMConflictDetector(llm, same_subject=True), LLMClaimClassifier(llm), require_auth=False,
+        contest_other_users=True, notice=True, soft_supersede="auto", confirm_replacements=True,
+        name="thymus-v3-no-auth"),
+    "thymus-v2-inline": lambda llm: ThymusGate(
+        LLMConflictDetector(llm), LLMClaimClassifier(llm), require_auth=True, contest_other_users=True,
+        name="thymus-v2-inline"),
+}
+
+# The gates compared in the main experiment; the ablations are run separately.
+MAIN_GATES = (
+    "allow-all", "user-only", "conflict-quarantine", "last-write-wins", "bounded-occupancy", "label-only", "thymus",
+)
+ABLATIONS = ("thymus-no-screen", "thymus-any-origin", "thymus-no-labels", "thymus-hide")
+ABLATIONS_V3 = ("thymus-v3-no-screen", "thymus-v3-any-origin", "thymus-v3-no-labels", "thymus-v3-hide", "thymus-v3-no-auth",
+                "thymus-v3-procedures")
+# Version 2 of the gate and its inline-label variant (see ThymusGate).
+VERSION_2 = ("thymus-v2", "thymus-v2-inline", "thymus-v2-soft", "thymus-v2-auto", "thymus-v2-precise", "thymus-v2-verified",
+             "thymus-v3", "thymus-v4")
+
+
+def make_gate(name: str, llm: LLM) -> Gate:
+    try:
+        return GATES[name](llm)
+    except KeyError:
+        raise ValueError(f"unknown gate {name!r}; choose from {', '.join(GATES)}") from None