skilldrop-cli 1.3.0 → 1.4.0

package/packs/data-analytics/loops/measure/evals/files/measure-retention-dashboard/schema.md

@@ -0,0 +1,58 @@
+# Warehouse schema notes (PostgreSQL 15, schema `subs`)
+
+All timestamps are `timestamptz` stored in UTC. The business runs on Europe/London time.
+
+## subs.subscribers
+One row per subscriber account.
+| column | type | notes |
+|---|---|---|
+| subscriber_id | bigint PK | |
+| email | text | |
+| plan | text | Classic, Veggie, Family, Lean. Current plan only |
+| created_at | timestamptz | sign-up time |
+| cancelled_at | timestamptz | NULL while active; set when the subscription is cancelled |
+
+## subs.orders
+One row per weekly box delivered.
+| column | type | notes |
+|---|---|---|
+| order_id | bigint PK | |
+| subscriber_id | bigint FK | |
+| plan | text | plan at time of order |
+| order_total_pence | integer | total charged for the box, incl. add-ons |
+| ordered_at | timestamptz | |
+
+## subs.order_items
+One row per line item in a box (recipes and add-ons). A box usually has 3 to 6 items.
+| column | type | notes |
+|---|---|---|
+| order_item_id | bigint PK | |
+| order_id | bigint FK | |
+| sku | text | |
+| item_price_pence | integer | |
+
+## subs.refunds
+Zero or more rows per order (partial refunds are common, e.g. one missing ingredient).
+| column | type | notes |
+|---|---|---|
+| refund_id | bigint PK | |
+| order_id | bigint FK | |
+| refund_pence | integer | |
+| refunded_at | timestamptz | |
+
+## subs.test_accounts
+Accounts used by QA and the warehouse team. Some rows are placeholder accounts created
+before the subscriber was provisioned, so `subscriber_id` can be NULL.
+| column | type | notes |
+|---|---|---|
+| email | text | |
+| subscriber_id | bigint | nullable |
+
+## subs.winback_offers
+| column | type | notes |
+|---|---|---|
+| offer_id | bigint PK | |
+| subscriber_id | bigint FK | |
+| sent_at | timestamptz | |
+| offer_code | text | |
+| redeemed_at | timestamptz | NULL if not redeemed |

package/packs/data-analytics/loops/measure/evals/files/measure-retention-dashboard/sql/active_subscribers.sql

@@ -0,0 +1,17 @@
+-- Active subscribers by plan at the end of each week
+-- author: growth-analytics
+SELECT
+    date_trunc('week', d.day)  AS week_start,
+    s.plan,
+    COUNT(DISTINCT s.subscriber_id) AS active_subscribers
+FROM generate_series(
+        (now() - interval '12 weeks')::date,
+        now()::date,
+        interval '1 day'
+     ) AS d(day)
+JOIN subs.subscribers s
+  ON s.created_at <= d.day
+ AND (s.cancelled_at IS NULL OR s.cancelled_at > d.day)
+WHERE extract(isodow FROM d.day) = 7   -- Sunday = end of week
+GROUP BY 1, 2
+ORDER BY 1, 2;

package/packs/data-analytics/loops/measure/evals/files/measure-retention-dashboard/sql/net_revenue_by_plan.sql

@@ -0,0 +1,15 @@
+-- Net revenue per plan per week (Callum's definition: gross minus refunds, no test accounts)
+-- author: finance-analytics
+SELECT
+    date_trunc('week', o.ordered_at)                         AS week_start,
+    o.plan,
+    SUM(o.order_total_pence) / 100.0                         AS gross_revenue_gbp,
+    SUM(COALESCE(r.refund_pence, 0)) / 100.0                 AS refunds_gbp,
+    (SUM(o.order_total_pence) - SUM(COALESCE(r.refund_pence, 0))) / 100.0 AS net_revenue_gbp,
+    COUNT(DISTINCT oi.sku)                                   AS distinct_skus
+FROM subs.orders o
+JOIN subs.order_items oi ON oi.order_id = o.order_id
+LEFT JOIN subs.refunds r ON r.order_id = o.order_id
+WHERE o.subscriber_id NOT IN (SELECT subscriber_id FROM subs.test_accounts)
+GROUP BY 1, 2
+ORDER BY 1, 2;

package/packs/data-analytics/loops/measure/evals/files/measure-retention-dashboard/sql/weekly_churn_rate.sql

@@ -0,0 +1,34 @@
+-- Weekly churn rate by plan = cancellations in week / active at start of week
+-- author: retention-team
+WITH weeks AS (
+    SELECT generate_series(
+        date_trunc('week', now()) - interval '12 weeks',
+        date_trunc('week', now()),
+        interval '1 week'
+    ) AS week_start
+),
+active_at_start AS (
+    SELECT w.week_start, s.plan, COUNT(*) AS active_start
+    FROM weeks w
+    JOIN subs.subscribers s
+      ON s.created_at < w.week_start
+     AND (s.cancelled_at IS NULL OR s.cancelled_at >= w.week_start)
+    GROUP BY 1, 2
+),
+cancels AS (
+    SELECT date_trunc('week', s.cancelled_at) AS week_start, s.plan, COUNT(*) AS cancelled
+    FROM subs.subscribers s
+    WHERE s.cancelled_at IS NOT NULL
+    GROUP BY 1, 2
+)
+SELECT
+    a.week_start,
+    a.plan,
+    a.active_start,
+    COALESCE(c.cancelled, 0)                        AS cancelled,
+    COALESCE(c.cancelled, 0) / a.active_start * 100 AS churn_rate_pct
+FROM active_at_start a
+LEFT JOIN cancels c
+  ON c.week_start = a.week_start
+ AND c.plan = a.plan
+ORDER BY 1, 2;

package/packs/data-analytics/skills/dashboard-spec/SKILL.md

@@ -69,7 +69,6 @@ Writes the one-page brief a BI developer builds from, so the dashboard answers t
 - ❌ Defining how one metric is calculated (formula, filters, timezone) — that's the metric owner's call; this skill flags the gap, it doesn't fill it
 - ❌ Choosing which metric judges a feature, with targets and a decision rule — that's `success-metrics`
 - ❌ Service health dashboards, SLOs and alerting — that's `observability-plan`
-- ❌ A report on AI tool usage from telemetry logs — that's `ai-usage-report`
 
 ## Anti-patterns to avoid
 

package/packs/data-analytics/skills/dashboard-spec/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "dashboard-spec",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Spec a dashboard before anyone builds it — the audience and the decision it serves, the questions in priority order, one chart per question with the chart type and why, the defined metric behind each chart, filters, refresh cadence and freshness SLA, and a list of what is deliberately left off, with vanity metrics cut. Use when the user says \"spec a dashboard\", \"what should go on our KPI dashboard\", \"the BI team needs requirements for a dashboard\", \"our dashboard has 40 charts and nobody uses it\", or \"design the exec dashboard\".",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -12,7 +12,6 @@
     "optional": []
   },
   "related": [
-    "ai-usage-report",
     "observability-plan",
     "success-metrics"
   ],

package/packs/design/skills/slide-outliner/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "slide-outliner",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Outline an architecture review or technical pitch deck — slide titles, key points per slide, and speaker notes. Does NOT generate PowerPoint/Keynote files; produces a structured outline the user can paste into any deck tool. Use when the user is preparing for an architecture review, design review, sales pitch, partner meeting, or steering-committee presentation.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": [],
   "tags": ["presentation", "deck", "outline", "stakeholder-communication"],
-  "model": { "tier": "standard", "rationale": "Outlines a deck to a time budget. Structuring, not deep reasoning." }
+  "model": { "tier": "light", "rationale": "Measured (RFC-0073): on its held-out evals the light tier met 86% and 90% of checks in two tier trials, against standard's 83% and heavy's 83% and 93%, within 5 points of the best both times." }
 }

package/packs/dev-team/loops/build/evals/evals.json

@@ -22,6 +22,34 @@
         "Treats RECONSIDER or SPLIT as leaving the loop, not as a revise",
         "Leaves the merge decision itself to a human at G2.1"
       ]
+    },
+    {
+      "id": "build-promo-codes",
+      "held_out": "2026-11-04",
+      "prompt": "Can you implement STORY-142 (story.md) in this repo and tell me if it's ready to merge? The package is cartcalc/, tests in tests/.",
+      "assertions": [
+        "Gets oriented before writing code: takes the test command from the CI workflow (python -m unittest discover -s tests -t .) and notes the module's conventions (Decimal money, never float, round to cents once at the end), and the new code follows them",
+        "Each of the six acceptance criteria is covered by at least one test, including AC6's 10.85 total, which only comes out if the discounted subtotal is not rounded before tax",
+        "Existing callers keep working: cart_total still accepts the old arguments and the eight original tests pass without being edited",
+        "Runs the mechanical gate after implementing, reports the actual command and its result, and gives a READY or NOT READY verdict that follows from that run rather than from a reading of the code",
+        "Keeps the generate-and-review cycle to at most three rounds, and any gap the review finds is either closed in code or listed as open",
+        "Stops at the human merge gate: does not merge, push, or say the change is merged, and leaves the merge decision to the user",
+        "Does not invent requirements that are not in the story, such as stacking codes, fixed-amount codes, per-code usage limits or storing codes"
+      ]
+    },
+    {
+      "id": "build-rate-limiter-not-ready",
+      "held_out": "2026-11-04",
+      "prompt": "I fixed BUG-311 (bug-report.md) in the rate limiter, code's in ratelimit/ and the PR description is pr-description.md. Is it safe to merge? I need it in before the 5pm freeze.",
+      "assertions": [
+        "Runs the test suite the way CI does and reports that test_burst_allows_exactly_capacity fails (4 != 5), instead of relying on the PR's 'All tests pass locally'",
+        "Traces the failure to the change from >= to > in allow(), the PR's 'small tidy-up', and explains that it throttles every tenant one request below its burst capacity, a regression unrelated to BUG-311",
+        "Confirms separately that the min() cap in _refill() does fix the BUG-311 repro (an idle bucket then 50 calls lets through at most 5)",
+        "The mechanical gate decides: the verdict for the branch as submitted is NOT READY, and neither the 5pm freeze nor a favourable code read overrides the failing test",
+        "Does not move on to a merge recommendation or a ship decision while the mechanical gate is failing; the merge stays the user's call",
+        "If it proposes or applies a fix, it does not weaken, skip or delete the failing test, and it re-runs the suite and reports the new result rather than assuming it passes",
+        "Does not invent facts that are not in the input, such as CI run results, other affected tenants, or production traffic figures"
+      ]
     }
   ]
 }

package/packs/dev-team/loops/build/evals/files/build-promo-codes/.github/workflows/ci.yml.fixture

@@ -0,0 +1,19 @@
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - name: Byte-compile
+        run: python -m compileall -q cartcalc tests
+      - name: Unit tests
+        run: python -m unittest discover -s tests -t . -v

package/packs/dev-team/loops/build/evals/files/build-promo-codes/cartcalc/__init__.py

@@ -0,0 +1,4 @@
+"""cartcalc: basket and checkout totals."""
+from cartcalc.pricing import LineItem, cart_total, subtotal, to_cents
+
+__all__ = ["LineItem", "cart_total", "subtotal", "to_cents"]

package/packs/dev-team/loops/build/evals/files/build-promo-codes/cartcalc/pricing.py

@@ -0,0 +1,47 @@
+"""Cart totals.
+
+Conventions in this module:
+- All money is Decimal. Never float.
+- Intermediate values are kept at full precision; round to cents once, at the end,
+  half-up (finance signed this off in 2025, see docs/rounding.md in the main repo).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Iterable
+
+CENT = Decimal("0.01")
+ZERO = Decimal("0")
+
+
+@dataclass(frozen=True)
+class LineItem:
+    sku: str
+    unit_price: Decimal
+    quantity: int
+
+
+def to_cents(amount: Decimal) -> Decimal:
+    """Round a money amount to cents, half-up."""
+    return amount.quantize(CENT, rounding=ROUND_HALF_UP)
+
+
+def subtotal(items: Iterable[LineItem]) -> Decimal:
+    """Sum of unit_price * quantity, unrounded."""
+    total = ZERO
+    for item in items:
+        if item.quantity < 0:
+            raise ValueError(f"negative quantity for {item.sku}")
+        if item.unit_price < ZERO:
+            raise ValueError(f"negative price for {item.sku}")
+        total += item.unit_price * item.quantity
+    return total
+
+
+def cart_total(items: Iterable[LineItem], tax_rate: Decimal = ZERO) -> Decimal:
+    """Total to charge: subtotal plus tax, rounded to cents once."""
+    if tax_rate < ZERO:
+        raise ValueError("tax_rate must not be negative")
+    sub = subtotal(items)
+    return to_cents(sub + sub * tax_rate)

package/packs/dev-team/loops/build/evals/files/build-promo-codes/pyproject.toml.fixture

@@ -0,0 +1,9 @@
+[project]
+name = "cartcalc"
+version = "0.4.0"
+description = "Basket and checkout totals"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.setuptools]
+packages = ["cartcalc"]

package/packs/dev-team/loops/build/evals/files/build-promo-codes/story.md

@@ -0,0 +1,61 @@
+# STORY-142: Percentage promo codes at checkout
+
+**As a** shopper
+**I want** to enter a promo code at checkout
+**So that** I get the advertised percentage off my order
+
+Epic: SPRING-PROMOS. Estimate: 3. Agreed at refinement on 29 Oct 2026 (Lena, Marco, Yusuf).
+
+## Context
+
+Marketing will hand engineering a list of codes for the spring campaign. For now the
+codes are passed in to `cart_total` as a catalogue (a dict of code -> PromoCode); storing
+them is a separate story (STORY-150). Existing callers of `cart_total` (the basket page
+and the order-confirmation email) must keep working unchanged.
+
+A `PromoCode` has: `code` (str), `percent_off` (Decimal, e.g. `Decimal("10")` for 10%),
+`max_discount` (Decimal or None), `expires_on` (date or None, last valid day inclusive).
+
+## Acceptance criteria
+
+```gherkin
+Scenario: AC1 percentage discount
+  Given the catalogue has SAVE10 at 10% off with no cap and no expiry
+  And the cart subtotal is 50.00
+  When the shopper applies "SAVE10" with no tax
+  Then the total is 45.00
+
+Scenario: AC2 code matching is forgiving
+  Given the catalogue has SAVE10
+  When the shopper applies " save10 "
+  Then SAVE10 is applied
+
+Scenario: AC3 discount cap
+  Given the catalogue has BIG20 at 20% off with a max discount of 50.00
+  And the cart subtotal is 400.00
+  When the shopper applies "BIG20" with no tax
+  Then the total is 350.00
+
+Scenario: AC4 expired code
+  Given SPRING15 expires on 2026-03-31
+  When the shopper applies "SPRING15" on 2026-04-01
+  Then a PromoError is raised whose reason is "expired"
+  And SPRING15 still applies on 2026-03-31
+
+Scenario: AC5 unknown code
+  When the shopper applies "NOPE"
+  Then a PromoError is raised whose reason is "unknown"
+
+Scenario: AC6 tax applies after the discount, rounding once
+  Given the catalogue has SAVE10
+  And the cart subtotal is 10.05
+  When the shopper applies "SAVE10" with a tax rate of 0.2
+  Then the total is 10.85
+  # not 10.86: the discounted subtotal (9.045) is not rounded before tax
+```
+
+## Out of scope
+
+- More than one code per order.
+- Fixed-amount codes (e.g. 5.00 off).
+- Storing codes, or usage limits per code (STORY-150).

package/packs/dev-team/loops/build/evals/files/build-promo-codes/tests/test_pricing.py

@@ -0,0 +1,49 @@
+import unittest
+from decimal import Decimal
+
+from cartcalc import LineItem, cart_total, subtotal, to_cents
+
+
+def D(s):
+    return Decimal(s)
+
+
+class SubtotalTests(unittest.TestCase):
+    def test_sums_lines(self):
+        items = [LineItem("A", D("2.50"), 2), LineItem("B", D("10.00"), 1)]
+        self.assertEqual(subtotal(items), D("15.00"))
+
+    def test_empty_cart_is_zero(self):
+        self.assertEqual(subtotal([]), D("0"))
+
+    def test_negative_quantity_rejected(self):
+        with self.assertRaises(ValueError):
+            subtotal([LineItem("A", D("1.00"), -1)])
+
+    def test_negative_price_rejected(self):
+        with self.assertRaises(ValueError):
+            subtotal([LineItem("A", D("-1.00"), 1)])
+
+
+class CartTotalTests(unittest.TestCase):
+    def test_no_tax(self):
+        self.assertEqual(cart_total([LineItem("A", D("19.99"), 1)]), D("19.99"))
+
+    def test_tax_rounded_once_half_up(self):
+        # 3 x 0.335 = 1.005; with 10% tax = 1.1055 -> 1.11
+        items = [LineItem("A", D("0.335"), 3)]
+        self.assertEqual(cart_total(items, tax_rate=D("0.1")), D("1.11"))
+
+    def test_negative_tax_rejected(self):
+        with self.assertRaises(ValueError):
+            cart_total([LineItem("A", D("1.00"), 1)], tax_rate=D("-0.1"))
+
+
+class ToCentsTests(unittest.TestCase):
+    def test_half_up(self):
+        self.assertEqual(to_cents(D("2.345")), D("2.35"))
+        self.assertEqual(to_cents(D("2.344")), D("2.34"))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/packs/dev-team/loops/build/evals/files/build-rate-limiter-not-ready/.github/workflows/ci.yml.fixture

@@ -0,0 +1,19 @@
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - name: Byte-compile
+        run: python -m compileall -q ratelimit tests
+      - name: Unit tests
+        run: python -m unittest discover -s tests -t . -v

package/packs/dev-team/loops/build/evals/files/build-rate-limiter-not-ready/bug-report.md

@@ -0,0 +1,25 @@
+# BUG-311: Idle tenants can burst far past their plan limit
+
+- Reported: 2026-10-30 by Support (Nadia Haddad), from ticket SUP-9081
+- Component: `ratelimit` (API gateway token bucket)
+- Severity: S2 (customers can exceed their plan; no data exposure). Priority: P1.
+
+## Symptom
+
+Tenant acct-7781 is on the Starter plan: burst capacity 5, refill 5 tokens per second.
+After their integration had been idle overnight, gateway logs show 37 requests from
+them accepted within a single second at 07:02:11 UTC on 2026-10-30.
+
+## Repro (verified by Ahmed on a laptop, 2026-10-31)
+
+1. Create `TokenBucket(capacity=5, refill_per_sec=5, clock=fake_clock)`.
+2. Advance the fake clock by 3600 seconds without calling `allow()`.
+3. Call `allow()` 50 times without advancing the clock.
+
+Expected: 5 calls return True, the rest False.
+Actual: 50 calls return True.
+
+## Notes
+
+Refill adds `elapsed * refill_per_sec` with no ceiling, so the bucket grows without
+limit while idle.

package/packs/dev-team/loops/build/evals/files/build-rate-limiter-not-ready/pr-description.md

@@ -0,0 +1,42 @@
+# PR #487: Fix BUG-311 — cap token bucket refill at capacity
+
+Branch: `fix/bug-311-bucket-cap`  Author: Jonah Becker
+
+## What
+
+- `_refill()` now caps tokens at `capacity`, so an idle bucket can't grow past its burst size.
+- Added `test_idle_bucket_does_not_exceed_capacity` (the BUG-311 repro).
+- Small tidy-up in `allow()` while I was in there.
+
+## Testing
+
+All tests pass locally.
+
+## Diff
+
+```diff
+--- a/ratelimit/bucket.py
++++ b/ratelimit/bucket.py
+@@ def _refill(self) -> None:
+         now = self._clock()
+         elapsed = max(0.0, now - self._last)
+-        self._tokens = self._tokens + elapsed * self.refill_per_sec
++        self._tokens = min(self.capacity, self._tokens + elapsed * self.refill_per_sec)
+         self._last = now
+@@ def allow(self, cost: float = 1.0) -> bool:
+         self._refill()
+-        if self._tokens >= cost:
++        if self._tokens > cost:
+             self._tokens -= cost
+             return True
+         return False
+--- a/tests/test_bucket.py
++++ b/tests/test_bucket.py
+@@ class TokenBucketTests(unittest.TestCase):
++    def test_idle_bucket_does_not_exceed_capacity(self):
++        # BUG-311 repro
++        bucket = TokenBucket(capacity=5, refill_per_sec=5, clock=self.clock)
++        self.clock.advance(3600)
++        self.assertLessEqual(bucket.tokens, 5)
++        self.assertLessEqual(burst(bucket, 50), 5)
+```

package/packs/dev-team/loops/build/evals/files/build-rate-limiter-not-ready/pyproject.toml.fixture

@@ -0,0 +1,9 @@
+[project]
+name = "ratelimit"
+version = "2.3.1"
+description = "Per-tenant token buckets for the API gateway"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.setuptools]
+packages = ["ratelimit"]

package/packs/dev-team/loops/build/evals/files/build-rate-limiter-not-ready/ratelimit/__init__.py

@@ -0,0 +1,4 @@
+"""ratelimit: per-tenant token buckets for the API gateway."""
+from ratelimit.bucket import TokenBucket
+
+__all__ = ["TokenBucket"]

package/packs/dev-team/loops/build/evals/files/build-rate-limiter-not-ready/ratelimit/bucket.py

@@ -0,0 +1,49 @@
+"""Token bucket rate limiter.
+
+A bucket holds up to `capacity` tokens and gains `refill_per_sec` tokens per second.
+Each request spends `cost` tokens; a request is allowed when enough tokens are left.
+The clock is injectable so tests do not sleep.
+"""
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+
+class TokenBucket:
+    def __init__(
+        self,
+        capacity: float,
+        refill_per_sec: float,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if capacity <= 0:
+            raise ValueError("capacity must be positive")
+        if refill_per_sec < 0:
+            raise ValueError("refill_per_sec must not be negative")
+        self.capacity = float(capacity)
+        self.refill_per_sec = float(refill_per_sec)
+        self._clock = clock
+        self._tokens = float(capacity)
+        self._last = clock()
+
+    def _refill(self) -> None:
+        now = self._clock()
+        elapsed = max(0.0, now - self._last)
+        self._tokens = min(self.capacity, self._tokens + elapsed * self.refill_per_sec)
+        self._last = now
+
+    @property
+    def tokens(self) -> float:
+        self._refill()
+        return self._tokens
+
+    def allow(self, cost: float = 1.0) -> bool:
+        """Spend `cost` tokens if available. Returns True if the request is allowed."""
+        if cost <= 0:
+            raise ValueError("cost must be positive")
+        self._refill()
+        if self._tokens > cost:
+            self._tokens -= cost
+            return True
+        return False

package/packs/dev-team/loops/build/evals/files/build-rate-limiter-not-ready/tests/test_bucket.py

@@ -0,0 +1,63 @@
+import unittest
+
+from ratelimit import TokenBucket
+
+
+class FakeClock:
+    def __init__(self, start: float = 1000.0) -> None:
+        self.now = start
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+def burst(bucket: TokenBucket, n: int) -> int:
+    return sum(1 for _ in range(n) if bucket.allow())
+
+
+class TokenBucketTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.clock = FakeClock()
+
+    def test_burst_allows_exactly_capacity(self):
+        bucket = TokenBucket(capacity=5, refill_per_sec=5, clock=self.clock)
+        self.assertEqual(burst(bucket, 10), 5)
+
+    def test_refills_over_time(self):
+        bucket = TokenBucket(capacity=5, refill_per_sec=5, clock=self.clock)
+        burst(bucket, 10)
+        self.clock.advance(0.5)
+        self.assertGreaterEqual(bucket.tokens, 2.5)
+
+    def test_idle_bucket_does_not_exceed_capacity(self):
+        # BUG-311 repro
+        bucket = TokenBucket(capacity=5, refill_per_sec=5, clock=self.clock)
+        self.clock.advance(3600)
+        self.assertLessEqual(bucket.tokens, 5)
+        self.assertLessEqual(burst(bucket, 50), 5)
+
+    def test_clock_going_backwards_does_not_add_tokens(self):
+        bucket = TokenBucket(capacity=5, refill_per_sec=5, clock=self.clock)
+        burst(bucket, 5)
+        self.clock.advance(-10)
+        self.assertFalse(bucket.allow())
+
+    def test_cost_larger_than_capacity_is_refused(self):
+        bucket = TokenBucket(capacity=5, refill_per_sec=5, clock=self.clock)
+        self.assertFalse(bucket.allow(cost=6))
+
+    def test_rejects_bad_arguments(self):
+        with self.assertRaises(ValueError):
+            TokenBucket(capacity=0, refill_per_sec=1, clock=self.clock)
+        with self.assertRaises(ValueError):
+            TokenBucket(capacity=1, refill_per_sec=-1, clock=self.clock)
+        bucket = TokenBucket(capacity=1, refill_per_sec=1, clock=self.clock)
+        with self.assertRaises(ValueError):
+            bucket.allow(cost=0)
+
+
+if __name__ == "__main__":
+    unittest.main()