proactive-gate 0.8.2__tar.gz → 0.9.0__tar.gz

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/.gitignore

@@ -12,3 +12,6 @@ __pycache__/
 
 # uv writes this when the Python package is run locally; the library pins nothing.
 python/uv.lock
+
+# Other tools downloaded by npm run compare:fetch: read and run, never committed.
+_upstream/

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: proactive-gate
-Version: 0.8.2
-Summary: Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package.
+Version: 0.9.0
+Summary: proactive-gate is a library that decides whether an AI agent may message a user right now (quiet hours, daily limit, consent, snooze) and records the reason when it may not.
 Project-URL: Homepage, https://bubblegunn.github.io/proactive-gate/
 Project-URL: Documentation, https://bubblegunn.github.io/proactive-gate/start/
 Project-URL: Playground, https://bubblegunn.github.io/proactive-gate/playground/
@@ -11,7 +11,7 @@ Project-URL: Specification, https://github.com/Bubblegunn/proactive-gate/tree/ma
 Project-URL: Changelog, https://github.com/Bubblegunn/proactive-gate/blob/main/CHANGELOG.md
 Author: Efe Genc
 License-Expression: MIT
-Keywords: agents,ai-agents,consent,guardrails,interruption,llm,notification-budget,notification-policy,notifications,policy,policy-engine,proactive,proactive-agents,proactive-ai,quiet-hours,rate-limit
+Keywords: agent-notification-policy,agents,ai-agents,consent,do-not-disturb,frequency-cap,guardrails,interruption,llm,notification-budget,notification-fatigue,notification-policy,notification-throttle,notifications,policy,policy-engine,proactive,proactive-agent,proactive-agents,proactive-ai,quiet-hours,rate-limit,tcpa,timezone
 Classifier: Development Status :: 4 - Beta
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -40,10 +40,7 @@ Description-Content-Type: text/markdown
 
 # proactive-gate for Python
 
-Decide whether a proactive assistant may speak to this person right now. Ordered checks
-(consent, mode, snooze, mute, intensity, quiet hours, trust ramp, dismissal cooldown,
-budgets), JSON policies, platform and regulatory presets, and a trace that says which check
-stopped the message and why.
+proactive-gate is a library that decides whether an AI agent may message a user right now (quiet hours, daily limit, consent, snooze) and records the reason when it may not. It has ordered checks (consent, mode, snooze, mute, intensity, quiet hours, trust ramp, dismissal cooldown, budgets), JSON policies, platform and regulatory presets, and a trace that says which check stopped the message and why.
 
 This is the Python sibling of the TypeScript package. Both implement the same behaviour
 contract in [`spec/`](https://github.com/Bubblegunn/proactive-gate/tree/main/spec) and run

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/README.md

@@ -1,9 +1,6 @@
 # proactive-gate for Python
 
-Decide whether a proactive assistant may speak to this person right now. Ordered checks
-(consent, mode, snooze, mute, intensity, quiet hours, trust ramp, dismissal cooldown,
-budgets), JSON policies, platform and regulatory presets, and a trace that says which check
-stopped the message and why.
+proactive-gate is a library that decides whether an AI agent may message a user right now (quiet hours, daily limit, consent, snooze) and records the reason when it may not. It has ordered checks (consent, mode, snooze, mute, intensity, quiet hours, trust ramp, dismissal cooldown, budgets), JSON policies, platform and regulatory presets, and a trace that says which check stopped the message and why.
 
 This is the Python sibling of the TypeScript package. Both implement the same behaviour
 contract in [`spec/`](https://github.com/Bubblegunn/proactive-gate/tree/main/spec) and run

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "proactive-gate"
-version = "0.8.2"
-description = "Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package."
+version = "0.9.0"
+description = "proactive-gate is a library that decides whether an AI agent may message a user right now (quiet hours, daily limit, consent, snooze) and records the reason when it may not."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
@@ -14,6 +14,8 @@ keywords = [
   "proactive", "proactive-ai", "proactive-agents", "ai-agents", "llm", "agents",
   "notifications", "notification-policy", "notification-budget", "quiet-hours",
   "consent", "rate-limit", "policy", "policy-engine", "guardrails", "interruption",
+  "notification-throttle", "frequency-cap", "notification-fatigue", "proactive-agent",
+  "do-not-disturb", "tcpa", "timezone", "agent-notification-policy",
 ]
 classifiers = [
   "Development Status :: 4 - Beta",

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/src/proactive_gate/__init__.py

@@ -22,7 +22,7 @@ from .types import (
     UserState,
 )
 
-__version__ = "0.8.2"
+__version__ = "0.9.0"
 
 __all__ = [
     "EN", "PRIORITY_RANK", "KNOWN_CHECKS", "AsyncGate", "AsyncMemoryStore", "AsyncSqliteStore", "AsyncStore", "Candidate", "Check",

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/src/proactive_gate/checks.py

@@ -7,10 +7,10 @@ from __future__ import annotations
 import json
 import math
 from collections.abc import Callable, Mapping, Sequence
-from datetime import datetime, timedelta
+from datetime import UTC, datetime, timedelta
 from typing import Protocol, runtime_checkable
 
-from .clock import DAY_SECONDS, day_before, in_window, iso_week_key, local_clock, local_day, parse_hhmm, weekday_of
+from .clock import DAY_SECONDS, day_before, in_window, iso_week_key, local_clock, local_day, next_key_change, parse_hhmm, weekday_of
 from .types import (
     PASS,
     ConsumePlan,
@@ -128,6 +128,9 @@ class Snooze(BaseCheck):
         reason = f"snoozed until {iso_z(until)}"
         return defer(reason, until) if self.defer else reject(reason)
 
+    def next_allowed_at(self, ctx: Context) -> datetime | None:
+        return ctx.user.snoozed_until
+
 
 class Mute(BaseCheck):
     id = "mute"
@@ -185,6 +188,37 @@ def quiet_at(quiet: QuietWindow | QuietSchedule, day: str, minutes: int) -> tupl
     return None
 
 
+_MINUTE = timedelta(minutes=1)
+
+
+def quiet_ends_at(quiet: QuietWindow | QuietSchedule, tz: str, now: datetime) -> datetime | None:
+    """The earliest minute after ``now`` at which quiet hours stop applying, or ``None``.
+
+    Each jump moves to the end of the window silencing the current local time. A daylight-saving
+    change between the two instants lands the jump an hour early (still quiet, so it jumps again)
+    or an hour late (so it steps back a minute at a time to the first open minute). Same
+    algorithm as ``quietEndsAt`` in the TypeScript package, held to the same fixtures.
+    """
+    start = now.astimezone(UTC).replace(second=0, microsecond=0)
+    at = start
+    for _ in range(16):
+        minutes, day = local_clock(at, tz)
+        hit = quiet_at(quiet, day, minutes)
+        if hit is None:
+            for _back in range(180):
+                earlier = at - _MINUTE
+                if earlier <= start:
+                    break
+                before_minutes, before_day = local_clock(earlier, tz)
+                if quiet_at(quiet, before_day, before_minutes) is not None:
+                    break
+                at = earlier
+            return at if at > now else None
+        until_end = (parse_hhmm(hit[0].end) - minutes) % 1440 or 1
+        at = at + timedelta(minutes=until_end)
+    return None
+
+
 class QuietHours(BaseCheck):
     id = "quietHours"
 
@@ -209,6 +243,12 @@ class QuietHours(BaseCheck):
         whose = "" if from_day == day else f" ({weekday_of(from_day)} {from_day})"
         return reject(f"quiet hours {window.start} to {window.end}{whose} {ctx.user.timezone}; priority {ctx.priority} is below the floor ({self.floor})")
 
+    def next_allowed_at(self, ctx: Context) -> datetime | None:
+        qh = ctx.user.quiet_hours
+        if qh is None or not ctx.user.timezone:
+            return None
+        return quiet_ends_at(qh, ctx.user.timezone, ctx.now)
+
 
 class TrustRamp(BaseCheck):
     id = "trustRamp"
@@ -321,6 +361,17 @@ class Budget(BaseCheck):
             return None
         return ConsumePlan(self.key_for(ctx), self.ttl_seconds, self.limit)
 
+    def key_at(self, user_id: str, at: datetime, tz: str | None) -> str:
+        """The counter key in force at ``at``; the reset is the first minute this answers differently."""
+        raise NotImplementedError
+
+    def next_allowed_at(self, ctx: Context) -> datetime | None:
+        user = ctx.user
+        try:
+            return next_key_change(ctx.now, user.timezone, lambda at: self.key_at(user.id, at, user.timezone))
+        except NotImplementedError:
+            return None
+
 
 def budget_key(user_id: str, now: datetime, tz: str | None = None) -> str:
     return f"budget:{user_id}:{local_day(now, tz)}"
@@ -343,6 +394,9 @@ class DailyBudget(Budget):
     def key_for(self, ctx: Context) -> str:
         return budget_key(ctx.user.id, ctx.now, ctx.user.timezone)
 
+    def key_at(self, user_id: str, at: datetime, tz: str | None) -> str:
+        return budget_key(user_id, at, tz)
+
 
 class WeeklyBudget(Budget):
     id = "weeklyBudget"
@@ -353,6 +407,9 @@ class WeeklyBudget(Budget):
     def key_for(self, ctx: Context) -> str:
         return weekly_budget_key(ctx.user.id, ctx.now, ctx.user.timezone)
 
+    def key_at(self, user_id: str, at: datetime, tz: str | None) -> str:
+        return weekly_budget_key(user_id, at, tz)
+
 
 class MonthlyBudget(Budget):
     id = "monthlyBudget"
@@ -363,6 +420,9 @@ class MonthlyBudget(Budget):
     def key_for(self, ctx: Context) -> str:
         return monthly_budget_key(ctx.user.id, ctx.now, ctx.user.timezone)
 
+    def key_at(self, user_id: str, at: datetime, tz: str | None) -> str:
+        return monthly_budget_key(user_id, at, tz)
+
 
 class UtilityFloor(BaseCheck):
     """Act only when the caller's pAccept clears tau = cFA / (cFA + pNeed * cFN)."""

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/src/proactive_gate/clock.py

@@ -1,7 +1,8 @@
 """Local-time arithmetic with the standard library only."""
 from __future__ import annotations
 
-from datetime import date, datetime, timedelta
+from collections.abc import Callable
+from datetime import UTC, date, datetime, timedelta
 from zoneinfo import ZoneInfo
 
 DAY_SECONDS = 24 * 60 * 60
@@ -54,3 +55,33 @@ def weekday_of(day: str) -> str:
 
 def day_before(day: str) -> str:
     return (date.fromisoformat(day) - timedelta(days=1)).isoformat()
+
+
+_MINUTE = timedelta(minutes=1)
+
+
+def _floor_minute(at: datetime) -> datetime:
+    return at.astimezone(UTC).replace(second=0, microsecond=0)
+
+
+def next_key_change(now: datetime, tz: str | None, key_at: Callable[[datetime], str]) -> datetime | None:
+    """The first minute after ``now`` at which ``key_at`` answers differently.
+
+    Found by jumping to successive local midnights, then stepping back a minute at a time to the
+    first minute of the new key, which is what a daylight-saving change before midnight needs.
+    ``None`` when the key does not change within forty days.
+    """
+    base = key_at(now)
+    start = _floor_minute(now)
+    at = start
+    for _ in range(40):
+        minutes = local_clock(at, tz)[0] if tz else at.hour * 60 + at.minute
+        at = at + timedelta(minutes=1440 - minutes)
+        if key_at(at) != base:
+            for _back in range(180):
+                earlier = at - _MINUTE
+                if earlier <= start or key_at(earlier) == base:
+                    break
+                at = earlier
+            return at
+    return None

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/src/proactive_gate/conformance.py

@@ -53,6 +53,8 @@ def _compare(failures: list[str], at: str, decision: Decision, expect: Mapping[s
     check("rejectedBy", decision.rejected_by, expect.get("rejectedBy"))
     check("deferredBy", decision.deferred_by, expect.get("deferredBy"))
     check("retryAt", iso_z(decision.retry_at) if decision.retry_at else None, expect.get("retryAt"))
+    if "nextAllowedAt" in expect:
+        check("nextAllowedAt", iso_z(decision.next_allowed_at) if decision.next_allowed_at else None, expect["nextAllowedAt"])
     if "surfaces" in expect:
         check("surfaces", list(decision.surfaces), expect["surfaces"])
     check("deliverAt", iso_z(decision.deliver_at) if decision.deliver_at else None, expect.get("deliverAt"))

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/src/proactive_gate/gate.py

@@ -140,10 +140,16 @@ class Evaluation:
             self._maybe_finish()
             return
         if outcome.kind == "reject":
-            self._finish(rejected_by=check.id, reason=outcome.reason)
+            self._finish(rejected_by=check.id, reason=outcome.reason, next_allowed_at=self._hold_for(check, ctx))
             return
         if outcome.kind == "defer":
-            self._finish(deferred_by=check.id, retry_at=outcome.retry_at, reason=outcome.reason)
+            retry_at = outcome.retry_at
+            self._finish(
+                deferred_by=check.id,
+                retry_at=retry_at,
+                reason=outcome.reason,
+                next_allowed_at=retry_at if retry_at is not None and retry_at > self.now else None,
+            )
             return
         if outcome.kind == "adjust":
             if outcome.deliver_at is not None:
@@ -152,6 +158,17 @@ class Evaluation:
                 self._surfaces = tuple(outcome.surfaces)
         self._maybe_finish()
 
+    def _hold_for(self, check: Check, ctx: Context) -> datetime | None:
+        """What the denying check says about when it would stop denying; a failure or a past instant is no answer."""
+        hook: Callable[[Context], datetime | None] | None = getattr(check, "next_allowed_at", None)
+        if hook is None:
+            return None
+        try:
+            at = hook(ctx)
+            return at if at is not None and at > self.now else None
+        except BaseException:  # noqa: BLE001 - an answer that fails is no answer, never a failed decision
+            return None
+
     def _maybe_finish(self) -> None:
         if self._index >= len(self.checks):
             self._finish(allowed=True)
@@ -163,6 +180,7 @@ class Evaluation:
         deferred_by: str | None = None,
         retry_at: datetime | None = None,
         reason: str | None = None,
+        next_allowed_at: datetime | None = None,
     ) -> None:
         user, candidate = self.input.user, self.input.candidate
         self._result = Decision(
@@ -180,6 +198,7 @@ class Evaluation:
             deferred_by=deferred_by,
             retry_at=retry_at,
             reason=reason,
+            next_allowed_at=next_allowed_at,
         )
         self._call("finally_", self._result)
 

{proactive_gate-0.8.2 → proactive_gate-0.9.0}/src/proactive_gate/types.py

@@ -228,6 +228,13 @@ class Decision:
     deferred_by: str | None = None
     retry_at: datetime | None = None
     reason: str | None = None
+    next_allowed_at: datetime | None = None
+    """Earliest instant at which the check that denied this candidate would stop denying it.
+
+    A lower bound, not a promise: a later check can still deny then. ``None`` when allowed, when
+    the denying check cannot say, and when a shadowed check would have denied. For a deferred
+    decision it equals ``retry_at``.
+    """
 
 
 @dataclass(frozen=True, slots=True)

proactive_gate-0.9.0/tests/test_next_allowed_at.py

@@ -0,0 +1,175 @@
+"""``Decision.next_allowed_at``: the gate takes it from the check that denied, and only then.
+
+The shared fixtures under spec/fixtures/hold hold the instants; these tests cover what a
+fixture cannot say: a check of your own, a hook that fails, and the brute-force comparison.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from proactive_gate import Candidate, Context, EvaluateInput, Gate, Outcome, UserState
+from proactive_gate.checks import BaseCheck, budget_key, monthly_budget_key, quiet_at, quiet_ends_at, weekly_budget_key
+from proactive_gate.clock import local_clock, next_key_change
+from proactive_gate.types import QuietSchedule, QuietWindow, defer, reject
+
+MINUTE = timedelta(minutes=1)
+NOW = datetime(2026, 9, 4, 9, 0, tzinfo=UTC)
+USER = UserState(id="u1", consent=True, timezone="Europe/Istanbul")
+CANDIDATE = Candidate(id="c1", type="reminder")
+
+
+class Denies(BaseCheck):
+    """Rejects every candidate and answers ``answer`` when asked when it would stop."""
+
+    def __init__(self, id: str, answer: datetime | BaseException | None = None, shadow: bool = False) -> None:
+        self.id = id
+        self._answer = answer
+        self.shadow = shadow
+        self.calls = 0
+
+    def run(self, ctx: Context, values: object) -> Outcome:
+        return reject("no")
+
+    def next_allowed_at(self, ctx: Context) -> datetime | None:
+        self.calls += 1
+        if isinstance(self._answer, BaseException):
+            raise self._answer
+        return self._answer
+
+
+class DeniesWithoutAnAnswer(BaseCheck):
+    """Rejects, and has no ``next_allowed_at`` at all, like every check written before 1.5.0."""
+
+    id = "plain"
+
+    def run(self, ctx: Context, values: object) -> Outcome:
+        return reject("no")
+
+
+class Passes(BaseCheck):
+    id = "passes"
+    calls = 0
+
+    def next_allowed_at(self, ctx: Context) -> datetime | None:
+        self.calls += 1
+        return NOW + timedelta(days=1)
+
+
+def evaluate(checks: Sequence[BaseCheck], now: datetime = NOW) -> tuple[bool, str | None, datetime | None]:
+    decision = Gate(checks).evaluate(EvaluateInput(USER, CANDIDATE, now))
+    return decision.allowed, decision.rejected_by, decision.next_allowed_at
+
+
+def test_the_answer_comes_from_the_check_that_rejected_and_only_after_it_rejected() -> None:
+    first, second, third = Passes(), Denies("second", NOW + timedelta(hours=3)), Denies("third", NOW + timedelta(days=9))
+    allowed, by, answer = evaluate([first, second, third])
+    assert (allowed, by, answer) == (False, "second", NOW + timedelta(hours=3))
+    assert (first.calls, second.calls, third.calls) == (0, 1, 0)
+
+
+@pytest.mark.parametrize(
+    "answer",
+    [None, NOW, NOW - timedelta(hours=1), RuntimeError("boom")],
+    ids=["none", "now itself", "the past", "a raise"],
+)
+def test_an_answer_that_is_none_not_after_now_or_raises_is_no_answer(answer: datetime | BaseException | None) -> None:
+    allowed, by, got = evaluate([Denies("c", answer)])
+    assert (allowed, by, got) == (False, "c", None)
+
+
+def test_allowed_shadowed_and_unanswering_checks_carry_none() -> None:
+    assert evaluate([Denies("s", NOW + MINUTE, shadow=True)]) == (True, None, None)
+    assert evaluate([DeniesWithoutAnAnswer()]) == (False, "plain", None)
+
+
+def test_a_naive_datetime_answer_is_no_answer_and_the_decision_is_still_produced() -> None:
+    naive = datetime(2026, 9, 4, 12, 0)
+    decision = Gate([Denies("c", naive)]).evaluate(EvaluateInput(USER, CANDIDATE, NOW))
+    assert (decision.allowed, decision.rejected_by, decision.next_allowed_at) == (False, "c", None)
+
+
+class Deferring(BaseCheck):
+    id = "d"
+
+    def __init__(self, retry_at: datetime) -> None:
+        self.retry_at = retry_at
+
+    def run(self, ctx: Context, values: object) -> Outcome:
+        return defer("later", self.retry_at)
+
+
+def test_a_deferred_decision_carries_retry_at_as_its_answer() -> None:
+    until = NOW + timedelta(hours=1)
+    decision = Gate([Deferring(until)]).evaluate(EvaluateInput(USER, CANDIDATE, NOW))
+    assert decision.next_allowed_at == until == decision.retry_at
+    past = Gate([Deferring(NOW - MINUTE)]).evaluate(EvaluateInput(USER, CANDIDATE, NOW))
+    assert past.next_allowed_at is None
+
+
+def first_open_minute(quiet: QuietWindow | QuietSchedule, zone: str, now: datetime) -> datetime | None:
+    at = now.astimezone(UTC).replace(second=0, microsecond=0)
+    for _ in range(60 * 48):
+        at += MINUTE
+        minutes, day = local_clock(at, zone)
+        if quiet_at(quiet, day, minutes) is None:
+            return at
+    return None
+
+
+def test_quiet_ends_at_equals_a_minute_by_minute_scan_across_daylight_saving_changes() -> None:
+    zones = ["America/New_York", "Europe/London", "Australia/Lord_Howe", "Asia/Kathmandu", "America/Havana"]
+    windows = [QuietWindow("22:00", "08:00"), QuietWindow("22:00", "02:30"), QuietWindow("23:30", "01:30"), QuietWindow("13:00", "14:00")]
+    starts = [datetime(2026, 3, 7, tzinfo=UTC), datetime(2026, 3, 28, tzinfo=UTC), datetime(2026, 10, 3, tzinfo=UTC), datetime(2026, 10, 31, tzinfo=UTC)]
+    compared = 0
+    for zone in zones:
+        for window in windows:
+            for start in starts:
+                for step in range(0, 48 * 60, 71):
+                    now = start + timedelta(minutes=step, seconds=17)
+                    minutes, day = local_clock(now, zone)
+                    if quiet_at(window, day, minutes) is None:
+                        continue
+                    assert quiet_ends_at(window, zone, now) == first_open_minute(window, zone, now), (zone, window, now)
+                    compared += 1
+    assert compared > 100
+
+
+def test_quiet_ends_at_inside_the_second_pass_of_a_repeated_hour() -> None:
+    # 2026-11-01 01:00-02:00 happens twice in New York; 06:10 UTC is 01:10 EST, the second pass.
+    window = QuietWindow("23:00", "01:30")
+    now = datetime(2026, 11, 1, 6, 10, tzinfo=UTC)
+    expected = datetime(2026, 11, 1, 6, 30, tzinfo=UTC)
+    assert quiet_ends_at(window, "America/New_York", now) == expected
+    assert first_open_minute(window, "America/New_York", now) == expected
+
+
+def test_quiet_ends_at_follows_a_schedule_and_gives_up_on_a_window_that_never_opens() -> None:
+    chain = QuietSchedule(days={"fri": QuietWindow("18:00", "00:00"), "sat": QuietWindow("00:00", "20:00")})
+    assert quiet_ends_at(chain, "Europe/Istanbul", datetime(2026, 9, 4, 16, 0, tzinfo=UTC)) == datetime(2026, 9, 5, 17, 0, tzinfo=UTC)
+    all_day = QuietSchedule(default=QuietWindow("00:00", "24:00"))
+    assert quiet_ends_at(all_day, "Europe/Istanbul", datetime(2026, 9, 4, 16, 0, tzinfo=UTC)) is None
+
+
+KeyFor = Callable[[str, datetime, str | None], str]
+
+
+def assert_resets_at_the_first_new_key(zone: str, now: datetime, key_for: KeyFor) -> None:
+    found = next_key_change(now, zone, lambda at: key_for("u", at, zone))
+    assert found is not None, (zone, now)
+    assert key_for("u", found, zone) != key_for("u", now, zone)
+    assert key_for("u", found - MINUTE, zone) == key_for("u", now, zone)
+
+
+def test_next_key_change_is_the_first_minute_whose_key_differs() -> None:
+    assert_resets_at_the_first_new_key("America/Havana", datetime(2026, 3, 7, 20, 0, tzinfo=UTC), budget_key)
+    assert_resets_at_the_first_new_key("America/New_York", datetime(2026, 11, 1, 4, 30, tzinfo=UTC), budget_key)
+    assert_resets_at_the_first_new_key("America/New_York", datetime(2026, 3, 8, 5, 30, tzinfo=UTC), budget_key)
+    assert_resets_at_the_first_new_key("Pacific/Apia", datetime(2011, 12, 29, 10, 0, tzinfo=UTC), budget_key)
+    assert_resets_at_the_first_new_key("Europe/Istanbul", datetime(2026, 9, 2, 9, 0, tzinfo=UTC), weekly_budget_key)
+    assert_resets_at_the_first_new_key("Europe/Istanbul", datetime(2026, 9, 15, 9, 0, tzinfo=UTC), monthly_budget_key)
+    assert_resets_at_the_first_new_key("America/New_York", datetime(2026, 12, 31, 20, 0, tzinfo=UTC), monthly_budget_key)
+    utc = next_key_change(datetime(2026, 9, 4, 9, 0, 30, tzinfo=UTC), None, lambda at: budget_key("u", at, None))
+    assert utc == datetime(2026, 9, 5, tzinfo=UTC)