📝 docs(plans): settled design and implementation plans for scheduled limits (#222)

[sodre]

Summary

Docs-only. Four commits adding the settled design for scheduled (cron) limits and the three implementation plans it decomposes into, all under docs/plans/.

• The design is settled and ready to implement. docs/plans/2026-09-13-scheduled-limits-design.md covers Sections 0–9 — data model, evaluation/enforcement, the evaluation core, the compact storage encoding, surface, failure handling, boundary-aware retries, testing, and known limitations. No open questions remain. The load-bearing claim: tk is the only materialised quantity, base cp/ra/rp on bucket items are never rewritten, and the fast path gains exactly one comparison (vu, valid-until) rather than ever evaluating a schedule or reading config.

• It subsumes 🐛 fix(repository): clamp bucket tokens when set_limits shrinks capacity #469, ✨ feat(limiter): reset bucket usage for an entity/resource pair #471 and ✨ feat(limiter): add check_availability() combining capacity and wait time #473 rather than landing them. Each parked primitive is replaced by something the schedule machinery needs anyway:

  Parked	Replaced by
  🐛 fix(repository): clamp bucket tokens when set_limits shrinks capacity #469 — clamp tk when set_limits shrinks capacity	§3.3: refill_bucket (and the aggregator, whose refill_delta <= 0 guard must go) clamps unconditionally on every refill path, rather than a targeted clamp bolted onto set_limits
  ✨ feat(limiter): reset bucket usage for an entity/resource pair #471 — reset_bucket() by deleting bucket items	§3.6: reset_schedule, a calendar-aligned token reset. 0 extra round trips, nothing deleted, tc left monotonic (✨ feat(limiter): reset bucket usage for an entity/resource pair #471 cleared it with the item)
  ✨ feat(limiter): add check_availability() combining capacity and wait time #473 — check_availability()	§7: acquire() already answers "can I proceed, and if not when?" in 1 WCU (0 RCU + 0 WCU on fast rejection), once retry_after_seconds becomes a piecewise walk across boundaries instead of a flat division

• It found and scoped 🐛 Provisioner never syncs bucket params, so manifest-applied entity limits never reach live buckets #481 — the provisioner's _apply_set never syncs bucket params, so zae-limiter limits apply writes config that never reaches live buckets. Entity-level limits carry no TTL and so keep enforcing whatever numbers they were born with, forever. It predates ✨ Support time-based dynamic rate limits with scheduling #222 and breaks plain limit numbers as well as schedules, so it lands first as its own plan and its own commit.

• Three plans, because the work decomposes into three independently shippable pieces, each producing working, testable software on its own:

  1. 2026-09-13-provisioner-bucket-sync-plan.md (6 tasks) — the 🐛 Provisioner never syncs bucket params, so manifest-applied entity limits never reach live buckets #481 fix. No scheduling content; verifiable alone.
  2. 2026-09-13-scheduled-limits-core-plan.md (14 tasks) — schedule.py, the compact encoding, the unconditional clamp, vu on the fast path, slow-path materialisation, aggregator awareness.
  3. 2026-09-13-scheduled-limits-surface-plan.md (12 tasks) — reset_schedule, manifest/CFN/CLI, boundary-aware retry_after, E2E, ADR-135.

  Ordering is 1 → 2 → 3. next_boundary takes its final two-tuple signature in plan 2 even though reset_sched is unused there, so plan 3 lands as a behaviour change inside one function rather than a signature change rippling through lease.py and processor.py.

Caveats recorded in the plans themselves

• Each plan ends with a Self-Review section that names exactly which tasks still need expanding against the then-current code, rather than inventing bodies now. Most notably the surface plan's Tasks 3–11, which depend on signatures the core plan has yet to produce (encode, _sync_bucket_params's final shape, LimitStatus construction) and on CFN/CLI code not yet read line by line. Expansion happens against post-♻️ Make Repository._now_ms() the single injectable clock seam #430 code — ♻️ Make Repository._now_ms() the single injectable clock seam #430 (Repository._now_ms() as the single injectable clock seam) is a hard prerequisite for testing anything time-varying, and is now milestoned v0.14.0 alongside this work.
• Notable findings folded into the plans: config items store whole tokens while bucket items store millitokens (a 1000x conversion the provisioner must make); manifest.py validates nothing but namespace, so capacity: 0 is accepted today and would newly crash inside the Lambda; refill_amounts is already a delta, so the slow path clamps for free once refill_bucket does.

Test plan

• Docs-only — no code changes, no source or test files touched (git diff --stat main...HEAD is four files, all docs/plans/*.md)
• No CI impact beyond markdown; lint, type check and the test suite are unaffected
• Design and plans read for internal consistency (cross-plan ordering, spec-section coverage, type signatures across plan boundaries)

Refs #222 — design and plans only; #222 stays open until the three plans land.
Scopes #481. Subsumes #469, #471, #473 (closed on implementation, not by this PR).
Blocked on #430.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QdVj8nPhUwTz2aNJzMFqt5

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.42%. Comparing base (d6bd456) to head (20effd8).
⚠️ Report is 9 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #482      +/-   ##
==========================================
- Coverage   93.47%   93.42%   -0.06%     
==========================================
  Files          47       47              
  Lines        9562     9562              
==========================================
- Hits         8938     8933       -5     
- Misses        624      629       +5     

Flag	Coverage Δ
doctest	30.50% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.