proactive-gate 0.3.1__tar.gz → 0.4.0__tar.gz

{proactive_gate-0.3.1 → proactive_gate-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proactive-gate
-Version: 0.3.1
+Version: 0.4.0
 Summary: Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package.
 Project-URL: Homepage, https://bubblegunn.github.io/proactive-gate/
 Project-URL: Documentation, https://bubblegunn.github.io/proactive-gate/start/
@@ -84,6 +84,12 @@ else:
 `evaluate` reads; `commit` is the atomic increment right before you send, and it is
 idempotent on `decision.id`. Every decision carries `trace`, one entry per check that ran.
 
+`explain(decision)` renders a decision as sentences a non-engineer follows, a pure function
+of the trace with the same wording as the TypeScript catalog: `explain(decision).summary`
+for the decision as one sentence, `.checks` for one per check that ran. `language` defaults
+to `"en"`; another language is a mapping over the same keys in `catalogs`, merged over
+English so a partial translation still renders.
+
 ## A policy is data
 
 ```python

{proactive_gate-0.3.1 → proactive_gate-0.4.0}/README.md

@@ -47,6 +47,12 @@ else:
 `evaluate` reads; `commit` is the atomic increment right before you send, and it is
 idempotent on `decision.id`. Every decision carries `trace`, one entry per check that ran.
 
+`explain(decision)` renders a decision as sentences a non-engineer follows, a pure function
+of the trace with the same wording as the TypeScript catalog: `explain(decision).summary`
+for the decision as one sentence, `.checks` for one per check that ran. `language` defaults
+to `"en"`; another language is a mapping over the same keys in `catalogs`, merged over
+English so a partial translation still renders.
+
 ## A policy is data
 
 ```python

{proactive_gate-0.3.1 → proactive_gate-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "proactive-gate"
-version = "0.3.1"
+version = "0.4.0"
 description = "Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package."
 readme = "README.md"
 requires-python = ">=3.11"

{proactive_gate-0.3.1 → proactive_gate-0.4.0}/src/proactive_gate/__init__.py

@@ -5,6 +5,7 @@ contract in ``spec/`` and the same fixtures.
 """
 from . import checks, presets
 from .checks import Check, default_checks
+from .explain import EN, CheckSentence, Explanation, explain
 from .gate import AsyncGate, Evaluation, Gate, Hooks, decide
 from .policy import KNOWN_CHECKS, CompiledPolicy, compile_policy, load_policy
 from .presets import Preset
@@ -24,8 +25,9 @@ from .types import (
 __version__ = "0.2.0"
 
 __all__ = [
-    "PRIORITY_RANK", "KNOWN_CHECKS", "AsyncGate", "AsyncMemoryStore", "AsyncStore", "Candidate", "Check",
-    "CompiledPolicy", "Context", "Decision", "EvaluateInput", "Evaluation", "Gate", "Hooks", "MemoryStore",
+    "EN", "PRIORITY_RANK", "KNOWN_CHECKS", "AsyncGate", "AsyncMemoryStore", "AsyncStore", "Candidate", "Check",
+    "CheckSentence", "CompiledPolicy", "Context", "Decision", "EvaluateInput", "Evaluation", "Explanation",
+    "Gate", "Hooks", "MemoryStore",
     "Outcome", "Preset", "Priority", "RedisStore", "SqliteStore", "Store", "TraceEntry", "UserState",
-    "__version__", "checks", "compile_policy", "decide", "default_checks", "load_policy", "presets",
+    "__version__", "checks", "compile_policy", "decide", "default_checks", "explain", "load_policy", "presets",
 ]

proactive_gate-0.4.0/src/proactive_gate/explain.py

@@ -0,0 +1,517 @@
+"""explain(): a decision rendered as sentences a non-engineer can read.
+
+The renderer is a pure function of the decision. Every fact in a sentence
+comes from a trace entry's own reason or from a decision field, so it can
+only describe a decision the gate actually made; a check that never ran has
+no sentence. The machine reasons are the contract both implementations pin
+word for word, which is what makes them safe to read back here. When a
+reason does not match what a check emits, the sentence quotes it verbatim
+rather than guessing.
+
+``decision.reason`` is unchanged: the plain sentence and the machine reason
+sit side by side and neither replaces the other.
+
+Language is a parameter: English ships as ``EN``, and another language is a
+mapping over the same keys, merged over English so a partial translation
+still renders. The sentences match the TypeScript catalog word for word.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from .types import Decision, TraceEntry, iso_z
+
+# A template reads the fields a parser pulled out of a machine reason.
+SentenceTemplate = Callable[[Mapping[str, str]], str]
+Sentences = dict[str, SentenceTemplate]
+Facts = dict[str, str]
+
+
+@dataclass(frozen=True, slots=True)
+class CheckSentence:
+    """One trace entry rendered: which check, what it said, and the sentence for it."""
+
+    id: str
+    outcome: str
+    sentence: str
+    shadow: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class Explanation:
+    """``summary`` is the decision as one sentence; ``checks`` is one sentence per check that ran, in order."""
+
+    summary: str
+    checks: tuple[CheckSentence, ...]
+
+
+# English ------------------------------------------------------------------
+
+
+def _plural(n: int, unit: str) -> str:
+    return f"{n} {unit}{'' if n == 1 else 's'}"
+
+
+def _span_words(label: str) -> str:
+    """'1d' to 'within the last day', '24h' to 'within the last 24 hours'."""
+    m = re.fullmatch(r"(\d+)([dhms])", label)
+    if not m:
+        return f"within the last {label}"
+    unit = {"d": "day", "h": "hour", "m": "minute", "s": "second"}[m.group(2)]
+    n = int(m.group(1))
+    return f"within the last {unit}" if n == 1 else f"within the last {_plural(n, unit)}"
+
+
+def _seconds_words(text: str) -> str:
+    """'86400' to 'day', '7200' to '2 hours': a rate-limit period in seconds, said long."""
+    try:
+        n = int(text)
+    except ValueError:
+        return f"{text} seconds"
+
+    # "per hour", not "per 1 hour": the same singular _span_words already says as "the last day".
+    def period(count: int, unit: str) -> str:
+        return unit if count == 1 else _plural(count, unit)
+
+    if n % 86400 == 0:
+        return period(n // 86400, "day")
+    if n % 3600 == 0:
+        return period(n // 3600, "hour")
+    if n % 60 == 0:
+        return period(n // 60, "minute")
+    return period(n, "second")
+
+
+def _budget_pass(label: str) -> SentenceTemplate:
+    # The spend note is true only when the pass really read the counter: a
+    # bypassed budget returns a bare pass, a near-limit pass cannot be a bypass.
+    def render(f: Mapping[str, str]) -> str:
+        if "used" in f:
+            return f"the {label} had room, but only just: {f['used']} of {f['limit']} already used; the unit is spent when the message actually goes out"
+        return f"the {label} did not stop it"
+
+    return render
+
+
+def _budget_reject(label: str) -> SentenceTemplate:
+    return lambda f: f"the {label} of {f['limit']} was already spent ({f['used']} used)"
+
+
+def _held(f: Mapping[str, str]) -> str:
+    until = f.get("until")
+    return f"held{' until ' + until if until else ''} because {f['clause']}"
+
+
+def _allowed(f: Mapping[str, str]) -> str:
+    return f"allowed at {f['at']} because no check stopped it{f.get('notes', '')}"
+
+
+def _quiet_reject(f: Mapping[str, str]) -> str:
+    owned = f", a window belonging to {f['from']}," if "from" in f else ""
+    return f"the user's quiet hours run {f['start']} to {f['end']} {f['tz']}{owned} and {f['priority']} priority is below the {f['floor']} floor needed to override them"
+
+
+def _timing_adjust(f: Mapping[str, str]) -> str:
+    surfaces = (f.get("surfaces") or "").replace(",", ", ")
+    if "at" in f and "surfaces" in f:
+        return f"delivery was moved to {f['at']} and narrowed to {surfaces}"
+    if "at" in f:
+        return f"delivery was moved to {f['at']}"
+    return f"delivery was narrowed to {surfaces}"
+
+
+def _window_pass(f: Mapping[str, str]) -> str:
+    name = f.get("name")
+    return f'the "{name}" allowed window did not block it' if name else "the allowed window did not block it"
+
+
+def _consent_pass(f: Mapping[str, str]) -> str:
+    name = f.get("name")
+    return f'the "{name}" consent the check needs was in place' if name else "the consent the check needs was in place"
+
+
+def _consent_reject(f: Mapping[str, str]) -> str:
+    hours = f", which applies between {f['start']} and {f['end']}" if "start" in f else ""
+    return f'the user has not given the required "{f["name"]}" consent{hours}'
+
+
+def _recent_reject(f: Mapping[str, str]) -> str:
+    if "age" in f:
+        return f"the user's last message to the assistant was {f['age']} h ago, outside the {f['within']} h window"
+    return "the user has never written to the assistant, and this rule allows messages only after they do"
+
+
+def _fallback_pass(f: Mapping[str, str]) -> str:
+    reason = f.get("reason")
+    return f'the "{f["id"]}" check let it through{f" ({reason})" if reason else ""}'
+
+
+EN: Sentences = {
+    "summary.held": _held,
+    "summary.allowed": _allowed,
+    "summary.allowedEmpty": lambda f: "allowed; no checks ran",
+    "summary.heldUnknown": lambda f: "held; the trace does not name the check that stopped it",
+    "note.deliverAt": lambda f: f"delivery waits until {f['at']}",
+    "note.nearLimit": lambda f: f"{f['check']} was close to its limit ({f['used']} of {f['limit']} used)",
+    "note.shadowed": lambda f: f"{f['check']} would have stopped it but ran in shadow mode",
+    "entry.shadow": lambda f: f"it would have stopped the message ({f['body']}), but the check ran in shadow mode so evaluation continued",
+    "killSwitch.pass": lambda f: "the kill switch was off",
+    "killSwitch.reject": lambda f: "the kill switch is on, which stops every message",
+    "consent.pass": lambda f: "the user has agreed to proactive messages",
+    "consent.reject": lambda f: "the user has not agreed to proactive messages",
+    "enabled.pass": lambda f: "proactive messages are switched on for this profile",
+    "enabled.reject": lambda f: "proactive messages are switched off on this user's profile",
+    "mode.pass": lambda f: "the user's operating mode did not block it",
+    "mode.reject": lambda f: f'the user\'s operating mode is "{f["mode"]}", which does not allow proactive messages',
+    "snooze.pass": lambda f: "no snooze was in effect",
+    "snooze.reject": lambda f: f"the user has snoozed the assistant until {f['until']}",
+    "mute.pass": lambda f: "this type of message is not muted",
+    "mute.reject": lambda f: f'the user has muted "{f["type"]}" messages',
+    "intensity.pass": lambda f: "the message's priority satisfied the user's intensity setting",
+    "intensity.reject": lambda f: f"the message was {f['priority']} priority, and the user's \"{f['level']}\" intensity setting allows only {f['floor']} and above",
+    "quietHours.pass": lambda f: "quiet hours did not block it",
+    "quietHours.reject": _quiet_reject,
+    "quietHours.skip": lambda f: "the user has quiet hours but no time zone, so the check could not run",
+    "trustRamp.pass": lambda f: "the new-user trust period did not block it",
+    "trustRamp.reject": lambda f: f"the user is on day {f['day']} of a {f['days']}-day trust period for new users, which allows only {f['floor']} priority and above, and the message was {f['priority']}",
+    "trustRamp.skip": lambda f: "the user's sign-up date is not on record, so the new-user trust period could not be checked",
+    "dismissalCooldown.pass": lambda f: "the user has not dismissed this type enough to silence it",
+    "dismissalCooldown.reject": lambda f: f"the user has dismissed \"{f['type']}\" messages {f['count']} times in {f['within']} days, so this type stays silent until {f['until']}",
+    "adaptiveTiming.pass": lambda f: "the timing check left the message as it was",
+    "adaptiveTiming.adjust": _timing_adjust,
+    "dedupe.pass": lambda f: "this event had not already produced a message; the event is claimed when the message actually goes out",
+    "dedupe.reject": lambda f: f"the same event already produced a message {_span_words(f.get('window', ''))}",
+    "dedupe.skip": lambda f: "the candidate carried no event key, so duplicate detection could not run",
+    "dailyBudget.pass": _budget_pass("daily budget"),
+    "dailyBudget.reject": _budget_reject("user's daily budget"),
+    "weeklyBudget.pass": _budget_pass("weekly budget"),
+    "weeklyBudget.reject": _budget_reject("user's weekly budget"),
+    "monthlyBudget.pass": _budget_pass("monthly budget"),
+    "monthlyBudget.reject": _budget_reject("user's monthly budget"),
+    "windowBudget.pass": _budget_pass("window budget"),
+    "windowBudget.reject": lambda f: f"the budget for the window opened by the user's last message was already spent ({f['used']} of {f['limit']} used)",
+    "rateLimit.pass": lambda f: "the rate limit did not stop it",
+    "rateLimit.reject": lambda f: f"the rate limit of {f['limit']} messages per {_seconds_words(f.get('per', ''))} was already reached ({f['used']} used)",
+    "budget.pass": lambda f: f"the budget had room, but only just: {f['used']} of {f['limit']} already used; the unit is spent when the message actually goes out",
+    "budget.reject": lambda f: f"the {f['label']} was already used up ({f['used']} of {f['limit']} used)",
+    "utilityFloor.pass": lambda f: "the estimated acceptance chance cleared the utility floor",
+    "utilityFloor.reject": lambda f: f"the estimated chance the user would accept this message was {f['pAccept']}, below the utility floor of {f['tau']}",
+    "utilityFloor.skip": lambda f: "the candidate carried no acceptance estimate, so the utility floor could not run",
+    "boundedDeferral.pass": lambda f: "the user did not look busy",
+    "boundedDeferral.adjust": lambda f: f"the user looked busy, so delivery was deferred {f['tStar']} seconds to {f['at']}",
+    "allowedWindow.pass": _window_pass,
+    "allowedWindow.reject": lambda f: f"messages may only go out between {f['start']} and {f['end']} ({f['zone']}), and the local time was outside that window",
+    "allowedWindow.skip": lambda f: "the user has no time zone, so the allowed window could not be checked",
+    "requiresConsent.pass": _consent_pass,
+    "requiresConsent.reject": _consent_reject,
+    "requiresConsent.skip": lambda f: "the user has no time zone, so the hours this consent applies could not be checked",
+    "recentInteraction.pass": lambda f: "the user had written to the assistant recently enough",
+    "recentInteraction.reject": _recent_reject,
+    "gate.failOpen": lambda f: f"the \"{f['id']}\" check failed with \"{f['error']}\", and the gate is set to let messages through when a check fails",
+    "gate.failClosed": lambda f: f"the \"{f['id']}\" check failed with \"{f['error']}\", and the gate is set to stop messages when a check fails",
+    "gate.nonRejecting": lambda f: f"the \"{f['id']}\" check tried to {f['kind']} (\"{f['reason']}\") but is marked non-rejecting, so the gate ignored it",
+    "fallback.stop": lambda f: f"the \"{f['id']}\" check stopped it: {f['reason']}",
+    "fallback.pass": _fallback_pass,
+    "fallback.skip": lambda f: f"the \"{f['id']}\" check did not weigh in: {f['reason']}",
+    "fallback.adjust": lambda f: f"the \"{f['id']}\" check adjusted it: {f['reason']}",
+}
+
+
+# Reading the machine reasons back into facts ------------------------------ #
+
+Parser = Callable[[str], "Facts | None"]
+
+
+def _match(pattern: str, keys: tuple[str, ...]) -> Parser:
+    compiled = re.compile(pattern)
+
+    def parse(reason: str) -> Facts | None:
+        m = compiled.fullmatch(reason)
+        if not m:
+            return None
+        facts: Facts = {}
+        for key, value in zip(keys, m.groups()):
+            if value is not None:
+                facts[key] = value
+        return facts
+
+    return parse
+
+
+def _fixed(text: str) -> Parser:
+    return lambda reason: {} if reason == text else None
+
+
+def _first(*parsers: Parser) -> Parser:
+    def parse(reason: str) -> Facts | None:
+        for p in parsers:
+            facts = p(reason)
+            if facts is not None:
+                return facts
+        return None
+
+    return parse
+
+
+_BUDGET_STOP = _match(r".* of (\d+) used \((\d+)\)", ("limit", "used"))
+_BUDGET_NEAR = _match(r"(\d+) of (\d+) used", ("used", "limit"))
+
+
+def _parse_quiet_hours(reason: str) -> Facts | None:
+    m = re.fullmatch(r"quiet hours (\S+) to (\S+)(?: \((\w+) (\S+)\))? (\S+); priority (\w+) is below the floor \((\w+)\)", reason)
+    if not m:
+        return None
+    # holdUntil is the fact the summary headlines ("held until 08:00"); checks
+    # whose clause already says the instant (snooze, cooldown) leave it unset.
+    facts: Facts = {"start": m.group(1), "end": m.group(2), "tz": m.group(5), "priority": m.group(6), "floor": m.group(7), "holdUntil": m.group(2)}
+    if m.group(3) is not None:
+        facts["from"] = f"{m.group(3)} {m.group(4)}"
+    return facts
+
+
+def _consent_id_facts(check_id: str) -> Facts:
+    return {"name": check_id[len("consent:"):]} if check_id.startswith("consent:") else {}
+
+
+def _window_id_facts(check_id: str) -> Facts:
+    return {"name": check_id[len("window:"):]} if check_id.startswith("window:") else {}
+
+
+PARSERS: dict[str, dict[str, Parser | Callable[[str], Facts]]] = {
+    "killSwitch": {"stop": _fixed("engine kill switch is on")},
+    "consent": {"stop": _fixed("user has not consented to proactive behaviour")},
+    "enabled": {"stop": _fixed("proactive behaviour is disabled on this profile")},
+    "mode": {"stop": _match(r'operating mode "(.+)" does not allow proactive messages', ("mode",))},
+    "snooze": {"stop": _match(r"snoozed until (.+)", ("until",))},
+    "mute": {"stop": _match(r'type "(.+)" is muted by the user', ("type",))},
+    "intensity": {"stop": _match(r'priority (\w+) is below the "(\w+)" intensity floor \((\w+)\)', ("priority", "level", "floor"))},
+    "quietHours": {"stop": _parse_quiet_hours, "skip": _fixed("quiet hours set but no timezone on the user; cannot evaluate")},
+    "trustRamp": {
+        "stop": _match(r"trust ramp: day (\d+) of (\S+), priority (\w+) is below (\w+)", ("day", "days", "priority", "floor")),
+        "skip": _fixed("no createdAt on the user; ramp cannot be evaluated"),
+    },
+    "dismissalCooldown": {"stop": _match(r'(\d+) dismissals of "(.+)" in (\S+) days; silent until (.+)', ("count", "type", "within", "until"))},
+    "adaptiveTiming": {
+        "adjust": _first(
+            _match(r"deliver at (\S+); surfaces (.+)", ("at", "surfaces")),
+            _match(r"deliver at (\S+)", ("at",)),
+            _match(r"surfaces (.+)", ("surfaces",)),
+        )
+    },
+    "dedupe": {"stop": _match(r"already delivered within the last (.+)", ("window",)), "skip": _fixed("no dedupeKey on the candidate; deduplication cannot be evaluated")},
+    "dailyBudget": {"stop": _BUDGET_STOP, "passReason": _BUDGET_NEAR},
+    "weeklyBudget": {"stop": _BUDGET_STOP, "passReason": _BUDGET_NEAR},
+    "monthlyBudget": {"stop": _BUDGET_STOP, "passReason": _BUDGET_NEAR},
+    "windowBudget": {"stop": _BUDGET_STOP, "passReason": _BUDGET_NEAR},
+    "rateLimit": {"stop": _match(r"rate limit (\d+) per (\d+) s of \d+ used \((\d+)\)", ("limit", "per", "used")), "passReason": _BUDGET_NEAR},
+    "utilityFloor": {"stop": _match(r"pAccept (\S+) < tau (\S+)", ("pAccept", "tau")), "skip": _fixed("no pAccept on the candidate; utility floor cannot be evaluated")},
+    "boundedDeferral": {"adjust": _match(r"user busy; deliver at (\S+) \(t\* (\d+) s\)", ("at", "tStar"))},
+    "allowedWindow": {
+        "stop": _match(r"outside the allowed window (\S+) to (\S+) (.+)", ("start", "end", "zone")),
+        "idFacts": _window_id_facts,
+        "skip": _fixed("no timezone on the user; window cannot be evaluated"),
+    },
+    "requiresConsent": {
+        "stop": _match(r'consent "(.+)" is missing(?: \(required (\S+) to (\S+)\))?', ("name", "start", "end")),
+        "idFacts": _consent_id_facts,
+        "skip": _fixed("no timezone on the user; consent window cannot be evaluated"),
+    },
+    "recentInteraction": {
+        "stop": _first(
+            _fixed("no inbound message from the user on record"),
+            _match(r"last inbound message (\d+) h ago, window is (\S+) h", ("age", "within")),
+        )
+    },
+}
+
+
+def _key_for_id(check_id: str) -> str | None:
+    """The ids the package itself emits: the fixed check ids, plus consent:<name>, rate:<limit>/<period>s and window:<name>."""
+    if check_id in PARSERS:
+        return check_id
+    if check_id.startswith("consent:"):
+        return "requiresConsent"
+    if check_id.startswith("rate:"):
+        return "rateLimit"
+    if check_id.startswith("window:"):
+        return "allowedWindow"
+    return None
+
+
+# The gate's own trace entries: a store failure, or a non-rejecting check that
+# tried to stop evaluation anyway.
+_GATE_ENTRIES: tuple[tuple[str, Parser], ...] = (
+    ("gate.failOpen", _match(r"check threw \((.*)\); failing open", ("error",))),
+    ("gate.failClosed", _match(r"check threw \((.*)\); failing closed", ("error",))),
+    ("gate.nonRejecting", _match(r"non-rejecting check returned (\w+) \((.*)\); ignored", ("kind", "reason"))),
+)
+
+# Custom ids (a preset's "window:kakao", a caller's own wrapper) still emit the
+# check's reason, so an unmatched id falls back to recognizing the reason's
+# shape. Order is distinctiveness: each pattern names the check it sounds like.
+_STOP_SCAN = ("quietHours", "allowedWindow", "requiresConsent", "rateLimit", "dismissalCooldown", "snooze", "mute", "mode", "intensity", "trustRamp", "dedupe", "utilityFloor", "recentInteraction", "killSwitch", "consent", "enabled")
+_SKIP_SCAN = ("quietHours", "trustRamp", "dedupe", "utilityFloor", "allowedWindow", "requiresConsent")
+_ADJUST_SCAN = ("adaptiveTiming", "boundedDeferral")
+
+_BUDGET_LABELS = {"daily budget": "dailyBudget", "weekly budget": "weeklyBudget", "monthly budget": "monthlyBudget", "window budget": "windowBudget"}
+
+
+def _scan_budget(reason: str) -> tuple[str, Facts] | None:
+    """A 'label of N used (M)' reason from a budget whose id we do not know."""
+    m = re.fullmatch(r"(.+) of (\d+) used \((\d+)\)", reason)
+    if not m:
+        return None
+    key = _BUDGET_LABELS.get(m.group(1), "budget")
+    return key, {"label": m.group(1), "limit": m.group(2), "used": m.group(3)}
+
+
+def _cap(text: str) -> str:
+    return text[:1].upper() + text[1:] if text else text
+
+
+def _sentence_of(fragment: str) -> str:
+    return f"{_cap(fragment)}."
+
+
+def _t(sentences: Mapping[str, SentenceTemplate], key: str, facts: Facts) -> str:
+    template = sentences.get(key) or EN.get(key)
+    return template(facts) if template else facts.get("reason", "")
+
+
+def _stop_facts(entry: TraceEntry) -> tuple[str, Facts]:
+    """The stopping entry's clause and, when the trace names it, the instant the hold lifts."""
+    reason = entry.reason or ""
+    for gkey, parse in _GATE_ENTRIES:
+        gate_facts = parse(reason)
+        if gate_facts is not None:
+            return gkey, {"id": entry.id, **gate_facts}
+    check_key = _key_for_id(entry.id)
+    if check_key is not None:
+        parser = PARSERS[check_key].get("stop")
+        if parser is not None:
+            own = parser(reason)
+            if own is not None:
+                return f"{check_key}.reject", own
+    for k in _STOP_SCAN:
+        parser = PARSERS[k].get("stop")
+        if parser is None:
+            continue
+        scanned = parser(reason)
+        if scanned is not None:
+            return f"{k}.reject", scanned
+    budget = _scan_budget(reason)
+    if budget is not None:
+        return f"{budget[0]}.reject", budget[1]
+    return "fallback.stop", {"id": entry.id, "reason": reason}
+
+
+def _entry_body(entry: TraceEntry, sentences: Mapping[str, SentenceTemplate]) -> str:
+    reason = entry.reason or ""
+    check_key = _key_for_id(entry.id)
+    facts: Facts | None
+    if entry.outcome in ("reject", "defer"):
+        template, stop = _stop_facts(entry)
+        return _t(sentences, template, stop)
+    if entry.outcome == "pass":
+        if reason:
+            if check_key is not None:
+                parser = PARSERS[check_key].get("passReason")
+                facts = parser(reason) if parser is not None else None
+            else:
+                facts = _BUDGET_NEAR(reason)
+            if facts is not None:
+                return _t(sentences, f"{check_key or 'budget'}.pass", facts)
+            return _t(sentences, "fallback.pass", {"id": entry.id, "reason": reason})
+        base: Facts = {}
+        if check_key is not None:
+            id_facts = PARSERS[check_key].get("idFacts")
+            if id_facts is not None:
+                base = dict(id_facts(entry.id) or {})
+        return _t(sentences, f"{check_key}.pass" if check_key else "fallback.pass", {"id": entry.id, **base})
+    if entry.outcome == "skip":
+        for gkey, parse in _GATE_ENTRIES:
+            facts = parse(reason)
+            if facts is not None:
+                return _t(sentences, gkey, {"id": entry.id, **facts})
+        if check_key is not None:
+            parser = PARSERS[check_key].get("skip")
+            if parser is not None:
+                facts = parser(reason)
+                if facts is not None:
+                    return _t(sentences, f"{check_key}.skip", facts)
+        for k in _SKIP_SCAN:
+            parser = PARSERS[k].get("skip")
+            if parser is None:
+                continue
+            facts = parser(reason)
+            if facts is not None:
+                return _t(sentences, f"{k}.skip", facts)
+        return _t(sentences, "fallback.skip", {"id": entry.id, "reason": reason})
+    # adjust
+    if check_key is not None:
+        parser = PARSERS[check_key].get("adjust")
+        if parser is not None:
+            facts = parser(reason)
+            if facts is not None:
+                return _t(sentences, f"{check_key}.adjust", facts)
+    for k in _ADJUST_SCAN:
+        parser = PARSERS[k].get("adjust")
+        if parser is None:
+            continue
+        facts = parser(reason)
+        if facts is not None:
+            return _t(sentences, f"{k}.adjust", facts)
+    return _t(sentences, "fallback.adjust", {"id": entry.id, "reason": reason})
+
+
+def _explain_entry(entry: TraceEntry, sentences: Mapping[str, SentenceTemplate]) -> CheckSentence:
+    body = _entry_body(entry, sentences)
+    # Shadow is only a would-have-stopped when the outcome could have stopped.
+    if entry.shadow and entry.outcome in ("reject", "defer"):
+        body = _t(sentences, "entry.shadow", {"body": body})
+    return CheckSentence(id=entry.id, outcome=entry.outcome, sentence=_sentence_of(body), shadow=entry.shadow)
+
+
+def _summarize(decision: Decision, sentences: Mapping[str, SentenceTemplate]) -> str:
+    if decision.allowed:
+        if not decision.trace:
+            return _sentence_of(_t(sentences, "summary.allowedEmpty", {}))
+        notes: list[str] = []
+        if decision.deliver_at is not None:
+            notes.append(_t(sentences, "note.deliverAt", {"at": iso_z(decision.deliver_at)}))
+        for n in decision.near_limit:
+            notes.append(_t(sentences, "note.nearLimit", {"check": n.check, "used": str(n.used), "limit": str(n.limit)}))
+        for check_id in decision.shadowed:
+            notes.append(_t(sentences, "note.shadowed", {"check": check_id}))
+        return _sentence_of(_t(sentences, "summary.allowed", {"at": iso_z(decision.evaluated_at), "notes": "; " + "; ".join(notes) if notes else ""}))
+    stop_id = decision.rejected_by or decision.deferred_by
+    entry = next((e for e in reversed(decision.trace) if e.id == stop_id and e.outcome in ("reject", "defer")), None) if stop_id else None
+    if entry is None:
+        return _sentence_of(_t(sentences, "summary.heldUnknown", {}))
+    template, facts = _stop_facts(entry)
+    clause = _t(sentences, template, facts)
+    # For a deferral the hold ends at retryAt; when the clause already names the
+    # instant (snooze's reason is "snoozed until X"), naming it twice reads worse.
+    clause_says_when = "until" in facts
+    until = facts.get("holdUntil")
+    if until is None and not clause_says_when and decision.deferred_by and decision.retry_at is not None:
+        until = iso_z(decision.retry_at)
+    held_facts: Facts = {"clause": clause}
+    if until is not None:
+        held_facts["until"] = until
+    return _sentence_of(_t(sentences, "summary.held", held_facts))
+
+
+def explain(decision: Decision, language: str = "en", catalogs: Mapping[str, Mapping[str, SentenceTemplate]] | None = None) -> Explanation:
+    """Render a decision as sentences. Deterministic: the same decision always
+    produces the same explanation, and nothing outside the decision is read."""
+    overlay = (catalogs or {}).get(language)
+    if language != "en" and overlay is None:
+        raise ValueError(f'no sentence catalog for language "{language}"; pass one with the catalogs argument')
+    sentences: Sentences = {**EN, **(overlay or {})}
+    return Explanation(summary=_summarize(decision, sentences), checks=tuple(_explain_entry(e, sentences) for e in decision.trace))
+
+
+__all__ = ["EN", "CheckSentence", "Explanation", "SentenceTemplate", "Sentences", "explain"]

proactive_gate-0.4.0/tests/test_explain.py

@@ -0,0 +1,473 @@
+"""explain(): the same sentences as the TypeScript catalog, word for word."""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+import pytest
+
+from proactive_gate import (
+    EN,
+    Candidate,
+    Decision,
+    EvaluateInput,
+    Gate,
+    MemoryStore,
+    TraceEntry,
+    UserState,
+    checks,
+    explain,
+)
+from proactive_gate.types import QuietSchedule, QuietWindow
+
+UTC = timezone.utc
+NOON = datetime(2026, 9, 4, 9, 0, tzinfo=UTC)  # 12:00 in Istanbul (UTC+3)
+NIGHT = datetime(2026, 9, 4, 20, 30, tzinfo=UTC)  # 23:30 in Istanbul
+
+
+def user(**overrides: Any) -> UserState:
+    base: dict[str, Any] = {
+        "id": "u1",
+        "consent": True,
+        "proactive_enabled": True,
+        "mode": "normal",
+        "intensity": "normal",
+        "timezone": "Europe/Istanbul",
+        "quiet_hours": QuietWindow("22:00", "08:00"),
+        "created_at": datetime(2026, 1, 1, tzinfo=UTC),
+    }
+    base.update(overrides)
+    return UserState(**base)
+
+
+def candidate(**overrides: Any) -> Candidate:
+    base: dict[str, Any] = {"id": "c1", "type": "reminder", "priority": "normal", "surfaces": ("push", "feed")}
+    base.update(overrides)
+    return Candidate(**base)
+
+
+def evaluate(checks_list: Any, u: UserState | None = None, c: Candidate | None = None, now: datetime = NOON, store: MemoryStore | None = None, **gate_kw: Any) -> Decision:
+    gate = Gate(checks_list, store=store or MemoryStore(), **gate_kw)
+    return gate.evaluate(EvaluateInput(u or user(), c or candidate(), now))
+
+
+def test_pure_function_of_the_decision() -> None:
+    d = evaluate(checks.default_checks(), now=NIGHT)
+    first = explain(d)
+    second = explain(d)
+    assert first == second
+
+
+def test_plain_sentence_and_machine_reason_are_both_on_hand() -> None:
+    d = evaluate([checks.QuietHours()], now=NIGHT)
+    e = explain(d)
+    assert d.reason == "quiet hours 22:00 to 08:00 Europe/Istanbul; priority normal is below the floor (critical)"
+    assert e.summary == "Held until 08:00 because the user's quiet hours run 22:00 to 08:00 Europe/Istanbul and normal priority is below the critical floor needed to override them."
+
+
+def test_not_stopped_every_check_gets_a_sentence() -> None:
+    d = evaluate(checks.default_checks(), now=NOON)
+    e = explain(d)
+    assert e.summary == "Allowed at 2026-09-04T09:00:00.000Z because no check stopped it."
+    assert [c.id for c in e.checks] == [t.id for t in d.trace]
+    assert all(c.sentence for c in e.checks)
+
+
+def test_kill_switch() -> None:
+    d = evaluate([checks.KillSwitch(True)], now=NOON)
+    assert explain(d).summary == "Held because the kill switch is on, which stops every message."
+
+
+@pytest.mark.parametrize(
+    ("overrides", "clause"),
+    [
+        ({"consent": False}, "the user has not agreed to proactive messages"),
+        ({"proactive_enabled": False}, "proactive messages are switched off on this user's profile"),
+        ({"mode": "focus"}, 'the user\'s operating mode is "focus", which does not allow proactive messages'),
+        ({"muted_types": ("reminder",)}, 'the user has muted "reminder" messages'),
+    ],
+)
+def test_preference_checks_name_what_the_user_set(overrides: dict[str, Any], clause: str) -> None:
+    d = evaluate(checks.default_checks(), u=user(**overrides), now=NOON)
+    assert explain(d).summary == f"Held because {clause}."
+
+
+def test_snooze_reject_and_defer() -> None:
+    d = evaluate([checks.Snooze()], u=user(snoozed_until=datetime(2026, 9, 4, 12, 0, tzinfo=UTC)), now=NOON)
+    assert explain(d).summary == "Held because the user has snoozed the assistant until 2026-09-04T12:00:00.000Z."
+    deferred = evaluate([checks.Snooze(defer=True)], u=user(snoozed_until=datetime(2026, 9, 4, 12, 0, tzinfo=UTC)), now=NOON)
+    assert deferred.deferred_by == "snooze"
+    assert explain(deferred).summary == "Held because the user has snoozed the assistant until 2026-09-04T12:00:00.000Z."
+
+
+def test_intensity() -> None:
+    d = evaluate([checks.Intensity()], u=user(intensity="low"), now=NOON)
+    assert explain(d).summary == 'Held because the message was normal priority, and the user\'s "low" intensity setting allows only high and above.'
+
+
+def test_quiet_hours_window_owned_by_yesterday_says_so() -> None:
+    # Friday's 18:00 to 06:00 window is what silences Saturday 00:30 local.
+    scheduled = user(quiet_hours=QuietSchedule(default=None, days={"fri": QuietWindow("18:00", "06:00")}))
+    d = evaluate([checks.QuietHours()], u=scheduled, now=datetime(2026, 9, 4, 21, 30, tzinfo=UTC))
+    assert d.rejected_by == "quietHours"
+    assert "a window belonging to fri 2026-09-04" in explain(d).summary
+
+
+def test_quiet_hours_skip_without_timezone() -> None:
+    d = evaluate([checks.QuietHours()], u=user(timezone=None), now=NIGHT)
+    assert explain(d).checks[0].sentence == "The user has quiet hours but no time zone, so the check could not run."
+
+
+def test_trust_ramp_names_the_day() -> None:
+    d = evaluate([checks.TrustRamp()], u=user(created_at=datetime(2026, 9, 2, tzinfo=UTC)), now=NOON)
+    assert explain(d).summary == "Held because the user is on day 3 of a 7-day trust period for new users, which allows only high priority and above, and the message was normal."
+    skip = evaluate([checks.TrustRamp()], u=user(created_at=None), now=NOON)
+    assert explain(skip).checks[0].sentence == "The user's sign-up date is not on record, so the new-user trust period could not be checked."
+
+
+def test_dismissal_cooldown_said_plainly() -> None:
+    store = MemoryStore()
+    gate = Gate([checks.DismissalCooldown()], store=store)
+    u = user()
+    for day in (1, 2, 3):
+        gate.record(u, Candidate(id=f"c{day}", type="reminder"), "dismissed", datetime(2026, 9, day, 10, 0, tzinfo=UTC))
+    d = gate.evaluate(EvaluateInput(u, candidate(), datetime(2026, 9, 5, 10, 0, tzinfo=UTC)))
+    assert explain(d).summary == 'Held because the user has dismissed "reminder" messages 3 times in 30 days, so this type stays silent until 2026-09-10T10:00:00.000Z.'
+
+
+def test_adaptive_timing_adjust() -> None:
+    d = evaluate(
+        [checks.AdaptiveTiming(next_good_moment=lambda ctx: datetime(2026, 9, 4, 10, 0, tzinfo=UTC), surfaces_for=lambda ctx: ("feed",))],
+        now=NOON,
+    )
+    assert d.allowed
+    e = explain(d)
+    assert e.checks[0].sentence == "Delivery was moved to 2026-09-04T10:00:00.000Z and narrowed to feed."
+    assert "delivery waits until 2026-09-04T10:00:00.000Z" in e.summary
+
+
+def test_budget_spent_at_send_time() -> None:
+    store = MemoryStore()
+    gate = Gate([checks.DailyBudget(limit=5), checks.WeeklyBudget(limit=20)], store=store)
+    store.set("pg:budget:u1:2026-09-04", "4")
+    near = gate.evaluate(EvaluateInput(user(), candidate(), NOON))
+    e = explain(near)
+    assert e.checks[0].sentence == "The daily budget had room, but only just: 4 of 5 already used; the unit is spent when the message actually goes out."
+    assert "dailyBudget was close to its limit (4 of 5 used)" in e.summary
+
+    store.set("pg:budget:u1:2026-09-04", "5")
+    out = gate.evaluate(EvaluateInput(user(), candidate(), NOON))
+    assert explain(out).summary == "Held because the user's daily budget of 5 was already spent (5 used)."
+
+
+def test_rate_limit_custom_id() -> None:
+    store = MemoryStore()
+    window = int(NOON.timestamp() // 60)
+    store.set(f"pg:rate:channel:general:60:{window}", "20")
+    d = evaluate([checks.RateLimit(limit=20, per_seconds=60, key_by="channel", id="rate:20/min")], c=candidate(channel="general"), store=store, now=NOON)
+    assert explain(d).summary == "Held because the rate limit of 20 messages per minute was already reached (20 used)."
+
+
+@pytest.mark.parametrize(
+    ("per_seconds", "limit", "said"),
+    [(60, 20, "per minute"), (3600, 1000, "per hour"), (24 * 3600, 3, "per day"), (7200, 5, "per 2 hours"), (90, 2, "per 90 seconds")],
+)
+def test_rate_limit_periods(per_seconds: int, limit: int, said: str) -> None:
+    """One of a unit drops the number; kakao_brand_message ships the hour and line_messaging_api the day."""
+    store = MemoryStore()
+    store.set(f"pg:rate:user:u1:{per_seconds}:{int(NOON.timestamp() // per_seconds)}", str(limit))
+    d = evaluate([checks.RateLimit(limit=limit, per_seconds=per_seconds)], store=store, now=NOON)
+    assert explain(d).summary == f"Held because the rate limit of {limit} messages {said} was already reached ({limit} used)."
+
+
+def test_dedupe_delivered_and_missing_key() -> None:
+    store = MemoryStore()
+    store.set("pg:dedupe:u1:order:42", "1")
+    seen = evaluate([checks.Dedupe()], c=candidate(dedupe_key="order:42"), store=store, now=NOON)
+    assert explain(seen).summary == "Held because the same event already produced a message within the last day."
+    no_key = evaluate([checks.Dedupe()], now=NOON)
+    assert explain(no_key).checks[0].sentence == "The candidate carried no event key, so duplicate detection could not run."
+
+
+def test_utility_floor() -> None:
+    d = evaluate([checks.UtilityFloor(1, 1)], c=candidate(p_accept=0.3), now=NOON)
+    assert explain(d).summary == "Held because the estimated chance the user would accept this message was 0.3, below the utility floor of 0.5."
+    skip = evaluate([checks.UtilityFloor(1, 1)], now=NOON)
+    assert explain(skip).checks[0].sentence == "The candidate carried no acceptance estimate, so the utility floor could not run."
+
+
+def test_bounded_deferral_adjust() -> None:
+    d = evaluate([checks.BoundedDeferral()], c=candidate(busy=True), now=NOON)
+    assert d.allowed
+    e = explain(d)
+    assert e.checks[0].sentence.startswith("The user looked busy, so delivery was deferred 116")
+    assert "delivery waits until" in e.summary
+
+
+def test_allowed_window_custom_id() -> None:
+    d = evaluate([checks.AllowedWindow("08:00", "21:00", timezone="user", id="window:tcpa")], now=NIGHT)
+    assert d.rejected_by == "window:tcpa"
+    assert explain(d).summary == "Held because messages may only go out between 08:00 and 21:00 (Europe/Istanbul), and the local time was outside that window."
+
+
+def test_allowed_window_preset_id_names_the_window() -> None:
+    """us_tcpa, kakao_brand_message and cn_minor_mode each give the window an id of its own."""
+    named = evaluate([checks.AllowedWindow("08:00", "21:00", timezone="user", id="window:tcpa")], now=NOON)
+    assert named.allowed is True
+    assert explain(named).checks[0].sentence == 'The "tcpa" allowed window did not block it.'
+
+    plain = evaluate([checks.AllowedWindow("08:00", "21:00", timezone="user")], now=NOON)
+    assert explain(plain).checks[0].sentence == "The allowed window did not block it."
+
+    no_zone = evaluate([checks.AllowedWindow("08:00", "21:00", timezone="user", id="window:tcpa")], u=user(timezone=None), now=NOON)
+    assert explain(no_zone).checks[0].sentence == "The user has no time zone, so the allowed window could not be checked."
+
+
+def test_requires_consent_with_and_without_hours() -> None:
+    d = evaluate([checks.RequiresConsent("ad")], now=NOON)
+    assert explain(d).summary == 'Held because the user has not given the required "ad" consent.'
+    dn = evaluate([checks.RequiresConsent("night", when={"start": "21:00", "end": "08:00", "timezone": "user"})], now=NIGHT)
+    assert explain(dn).summary == 'Held because the user has not given the required "night" consent, which applies between 21:00 and 08:00.'
+    ok = evaluate([checks.RequiresConsent("ad")], u=user(consents={"ad": True}), now=NOON)
+    assert explain(ok).checks[0].sentence == 'The "ad" consent the check needs was in place.'
+
+
+def test_recent_interaction() -> None:
+    never = evaluate([checks.RecentInteraction(48)], now=NOON)
+    assert explain(never).summary == "Held because the user has never written to the assistant, and this rule allows messages only after they do."
+    old = evaluate([checks.RecentInteraction(48)], u=user(last_inbound_at=datetime(2026, 9, 1, 8, 0, tzinfo=UTC)), now=NOON)
+    assert explain(old).summary == "Held because the user's last message to the assistant was 73 h ago, outside the 48 h window."
+
+
+def test_window_budget() -> None:
+    store = MemoryStore()
+    last = datetime(2026, 9, 4, 8, 0, tzinfo=UTC)
+    store.set(f"pg:windowBudget:u1:{int(last.timestamp())}", "1")
+    d = evaluate([checks.WindowBudget(limit=1, within_hours=48)], u=user(last_inbound_at=last), store=store, now=NOON)
+    assert explain(d).summary == "Held because the budget for the window opened by the user's last message was already spent (1 of 1 used)."
+
+
+def test_gate_entries_fail_open_closed_and_ignored_non_rejecting() -> None:
+    class Boom(checks.BaseCheck):
+        id = "mystery"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            raise RuntimeError("boom")
+
+    opened = evaluate([Boom(), checks.Consent()], now=NOON)
+    assert explain(opened).checks[0].sentence == 'The "mystery" check failed with "boom", and the gate is set to let messages through when a check fails.'
+    closed = evaluate([Boom(), checks.Consent()], now=NOON, on_store_error="closed")
+    assert explain(closed).summary == 'Held because the "mystery" check failed with "boom", and the gate is set to stop messages when a check fails.'
+
+    class Polite(checks.BaseCheck):
+        id = "polite"
+        non_rejecting = True
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            from proactive_gate.types import Outcome
+
+            return Outcome("reject", "felt like it")
+
+    ignored = evaluate([Polite(), checks.Consent()], now=NOON)
+    assert explain(ignored).checks[0].sentence == 'The "polite" check tried to reject ("felt like it") but is marked non-rejecting, so the gate ignored it.'
+
+
+def test_shadowed_stop_is_what_would_have_happened() -> None:
+    class Shadowed(checks.BaseCheck):
+        id = "quietHours"
+        shadow = True
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            from proactive_gate.types import Outcome
+
+            return Outcome("reject", "quiet hours 22:00 to 08:00 Europe/Istanbul; priority normal is below the floor (critical)")
+
+    d = evaluate([Shadowed(), checks.Consent()], now=NIGHT)
+    e = explain(d)
+    assert e.checks[0].shadow
+    assert e.checks[0].sentence == (
+        "It would have stopped the message (the user's quiet hours run 22:00 to 08:00 Europe/Istanbul "
+        "and normal priority is below the critical floor needed to override them), but the check ran in shadow mode so evaluation continued."
+    )
+    assert "quietHours would have stopped it but ran in shadow mode" in e.summary
+
+
+def test_shadowed_pass_does_not_claim_it_would_have_stopped() -> None:
+    d = Decision(
+        id="u1:c1:2026-09-04T09:00:00.000Z#1",
+        allowed=True,
+        user_id="u1",
+        candidate_id="c1",
+        surfaces=("feed",),
+        trace=(TraceEntry(id="dailyBudget", outcome="pass", ms=0.0, reason="4 of 5 used", shadow=True),),
+        evaluated_at=NOON,
+    )
+    assert explain(d).checks[0].sentence == (
+        "The daily budget had room, but only just: 4 of 5 already used; "
+        "the unit is spent when the message actually goes out."
+    )
+
+
+def test_unknown_check_quotes_its_own_reason() -> None:
+    class Weekend(checks.BaseCheck):
+        id = "weekend"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            from proactive_gate.types import Outcome
+
+            return Outcome("reject", "weekend: only high priority")
+
+    d = evaluate([Weekend()], now=NOON)
+    assert explain(d).summary == 'Held because the "weekend" check stopped it: weekend: only high priority.'
+
+    class Weather(checks.BaseCheck):
+        id = "weather"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            from proactive_gate.types import Outcome
+
+            return Outcome("pass", "sunny out")
+
+    passing = evaluate([Weather(), Weekend()], now=NOON)
+    assert explain(passing).checks[0].sentence == 'The "weather" check let it through (sunny out).'
+
+
+def test_language_is_a_parameter() -> None:
+    d = evaluate([checks.QuietHours()], now=NIGHT)
+    assert explain(d).summary == explain(d, language="en").summary
+    with pytest.raises(ValueError, match='no sentence catalog for language "tr"'):
+        explain(d, language="tr")
+    tr = {"summary.held": lambda f: f"{f['until']} kadar bekletildi, çünkü {f['clause']}"}
+    e = explain(d, language="tr", catalogs={"tr": tr})
+    assert e.summary.startswith("08:00 kadar bekletildi, çünkü")
+    assert len(EN) > 0
+
+
+def test_hand_built_decision_without_a_stopping_check() -> None:
+    odd = Decision(
+        id="u1:c1:2026-09-04T09:00:00.000Z#1",
+        allowed=False,
+        user_id="u1",
+        candidate_id="c1",
+        surfaces=(),
+        trace=(),
+        evaluated_at=NOON,
+    )
+    assert explain(odd).summary == "Held; the trace does not name the check that stopped it."
+
+
+def test_the_templates_nothing_else_in_this_file_reaches() -> None:
+    """Each of these was silent until it was asked for; the first person to read an unrendered sentence should not be a user."""
+    from proactive_gate.types import Outcome
+
+    monthly = MemoryStore()
+    monthly.set("pg:monthlyBudget:u1:2026-09", "60")
+    spent = evaluate([checks.MonthlyBudget()], store=monthly, now=NOON)
+    assert explain(spent).summary == "Held because the user's monthly budget of 60 was already spent (60 used)."
+
+    weekly = MemoryStore()
+    weekly.set("pg:weeklyBudget:u1:2026-W36", "20")
+    week_spent = evaluate([checks.WeeklyBudget()], store=weekly, now=NOON)
+    assert explain(week_spent).summary == "Held because the user's weekly budget of 20 was already spent (20 used)."
+
+    # A budget nowhere near its limit passes without a reason, which is a
+    # different sentence from the near-limit one.
+    room = evaluate([checks.DailyBudget(limit=5)], now=NOON)
+    assert explain(room).checks[0].sentence == "The daily budget did not stop it."
+
+    rate = evaluate([checks.RateLimit(limit=20, per_seconds=60)], now=NOON)
+    assert explain(rate).checks[0].sentence == "The rate limit did not stop it."
+
+    unplaced = evaluate(
+        [checks.RequiresConsent("night", when={"start": "21:00", "end": "08:00", "timezone": "user"})],
+        u=user(timezone=None, consents={"night": True}),
+        now=NOON,
+    )
+    assert explain(unplaced).checks[0].sentence == "The user has no time zone, so the hours this consent applies could not be checked."
+
+    # Somebody else's budget: a reason shaped like one, under a label this
+    # package does not ship, keeps the caller's own words.
+    class TeamQuota(checks.BaseCheck):
+        id = "teamQuota"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            return Outcome("reject", "team quota of 5 used (5)")
+
+    assert explain(evaluate([TeamQuota()], now=NOON)).summary == "Held because the team quota was already used up (5 of 5 used)."
+
+    class TeamQuotaNear(checks.BaseCheck):
+        id = "teamQuota"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            return Outcome("pass", "4 of 5 used")
+
+    near = evaluate([TeamQuotaNear()], now=NOON)
+    assert explain(near).checks[0].sentence == (
+        "The budget had room, but only just: 4 of 5 already used; the unit is spent when the message actually goes out."
+    )
+
+    class Weather(checks.BaseCheck):
+        id = "weather"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            return Outcome("skip", "forecast service is down")
+
+    class Router(checks.BaseCheck):
+        id = "router"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            return Outcome("adjust", "sent via SMS instead")
+
+    odd = explain(evaluate([Weather(), Router()], now=NOON))
+    assert odd.checks[0].sentence == 'The "weather" check did not weigh in: forecast service is down.'
+    assert odd.checks[1].sentence == 'The "router" check adjusted it: sent via SMS instead.'
+
+    # A deferral whose clause does not say when: the hold instant comes from retry_at.
+    class Queue(checks.BaseCheck):
+        id = "queue"
+
+        def run(self, ctx: Any, values: Any) -> Any:
+            return Outcome("defer", "the send queue is draining", retry_at=datetime(2026, 9, 4, 10, 30, tzinfo=UTC))
+
+    deferred = evaluate([Queue()], now=NOON)
+    assert explain(deferred).summary == 'Held until 2026-09-04T10:30:00.000Z because the "queue" check stopped it: the send queue is draining.'
+
+    empty = Decision(
+        id="u1:c1:2026-09-04T09:00:00.000Z#1",
+        allowed=True,
+        user_id="u1",
+        candidate_id="c1",
+        surfaces=("feed",),
+        trace=(),
+        evaluated_at=NOON,
+    )
+    assert explain(empty).summary == "Allowed; no checks ran."
+
+
+def test_every_trace_entry_renders() -> None:
+    store = MemoryStore()
+    gate = Gate(
+        [
+            *checks.default_checks(weekly_limit=20),
+            checks.Dedupe(),
+            checks.MonthlyBudget(),
+            checks.UtilityFloor(1, 1),
+            checks.BoundedDeferral(),
+            checks.AllowedWindow("08:00", "21:00", timezone="user"),
+            checks.RecentInteraction(48),
+            checks.WindowBudget(limit=1, within_hours=48),
+        ],
+        store=store,
+    )
+    for now in (NOON, NIGHT, datetime(2026, 9, 6, 7, 0, tzinfo=UTC)):
+        d = gate.evaluate(EvaluateInput(user(last_inbound_at=datetime(2026, 9, 4, 8, 0, tzinfo=UTC)), candidate(dedupe_key="evt:1", p_accept=0.7), now))
+        e = explain(d)
+        assert len(e.checks) == len(d.trace)
+        for c in e.checks:
+            assert len(c.sentence) > 10, f"empty sentence for {c.id}"
+            assert c.sentence[0].isupper(), f"not a sentence for {c.id}: {c.sentence}"
+            # A check this package ships must have a template. Quoting its machine
+            # reason back is the honest answer for somebody else's check, and a
+            # silent regression for one of ours.
+            assert not re.search(r'" check (stopped it|let it through|did not weigh in|adjusted it)', c.sentence), f"{c.id} fell back to its machine reason: {c.sentence}"