Governor: proactive rate enforcement​

Hard limits now support an optional token bucket governor — a rate ceiling below the hard limit that shapes consumption before the wall is reached. Instead of cutting customers off, the governor throttles them.

limit:
  credit: ai_token
  mode: hard
  value: 1000000
  resets: true
  reset_sch: 'monthly:1'
  governor_enabled: true
  governor_capacity: 50000       # max burst
  governor_refill_rate: 0.5      # tokens per ms (~500/sec sustained)

When the governor fires, a new meter-governed event fires with token balance, capacity, and requested amount — distinct from meter-limit so you can route them differently.

Use policy.allowance() to pre-size operations against the current governor state before submitting them.

Calendar reset schedules​

Meters and grants can now reset on calendar boundaries rather than fixed durations. Set reset_sch instead of reset_inc on any limit or topup:

reset_sch: 'monthly:1'           # 1st of every month
reset_sch: 'monthly:last'        # last day of every month
reset_sch: 'weekly:mon'          # every Monday
reset_sch: 'nth_weekday:1:tue'   # first Tuesday of every month

All schedules use UTC. Calendar resets are mutually exclusive with reset_inc — the schema validator enforces this at policy load time.

Grant resets now also support reset_sch. Calendar-based grants reset exactly once per period with no catch-up behavior — the right default for billing-aligned credit allocations.

Rate intelligence​

Every meter now tracks a short consumption history, exposing:

• policy.rate(customer, entitlement) — instantaneous consumption rate (units/ms)
• policy.acceleration(customer, entitlement) — rate of change between recent intervals
• policy.projectedExhaustion(customer, entitlement, smoothed?) — estimated ms until the meter is exhausted. Pass smoothed: true for an EWMA-based projection that doesn't overreact to bursts — suitable for alerting from meter-changed notification handlers
• policy.allowance(customer, entitlement) — binding constraint of governor token balance and period remaining; use to pre-size operations

grants_apply on limits​

Hard and soft limits now support grants_apply: false to prevent credit grants from extending the limit. Set this on enforcement entitlements (governors, rate ceilings) where grants should never punch through, or on observe-mode entitlements where you want a clean, unmodified consumption signal.

Stof Time library​

The Stof Time library now includes calendar primitives used by the reset scheduling layer:

Time.year, Time.month, Time.hour, Time.minute, Time.second, Time.day_of_month, Time.day_of_week, Time.days_in_month, Time.start_of_day, Time.start_of_week, Time.start_of_month, Time.add_days, Time.add_months, Time.start_of_period

Breaking changes​

None. All changes are additive and backward compatible. Existing policies with reset_inc, no governor, and no grants_apply field continue to work exactly as before.