Data model
Control State: counters, caps, and distinct sets.
Control State keeps the safety and throttling primitives close to the request path: bucketed counters, frequency caps, velocity checks, and distinct sets — for fraud, rate limits, ad frequency capping, and agent safety.
What it is
One request-time home for the "how many / how often / how unique" question.
Throttling and safety decisions all reduce to a small number read at request time. Control State keeps that number next to the request path so the check is a fast read, not a round trip to a separate rate-limit service or a warehouse.
- Counter — bucketed counts, sums, and rates over sliding or tumbling windows.
- Frequency cap — per-entity impression, action, or spend caps over an hour, a day, or a campaign, enforced at read time.
- Velocity check — how many events in the last N minutes, to catch bursts for fraud and abuse throttling.
- Distinct set — exact or approximate unique devices, merchants, IPs, sessions, or tools seen in a window.
- Selection state — chosen or blocked entities kept consistent across requests, including agent safety counters beside Context Management memory.
In practice
Increment, count against a cap, and count distinct.
ts.incr(
table="impressions",
entity="camp_5:user_42",
ts_ms=now_ms,
by=1,
)n = ts.count(
table="impressions",
entity="camp_5:user_42",
range="24h",
)
allow = n < DAILY_CAPu = ts.distinct(
table="card_touch",
entity="card_9",
field="merchant",
range="24h",
)When to use it
When a "yes / no" gate depends on recent activity.
Reach for Control State whenever an allow-or-block decision hinges on how much, how often, or how many distinct things an entity has done lately — and the check sits on the hot path.
| Use case | Primitive | Why it fits |
|---|---|---|
| Ad frequency caps | Frequency cap | Enforces per-user impression limits over hour/day/campaign windows. |
| API rate limits | Counter | Bucketed counts per key gate requests without a separate limiter. |
| Fraud velocity | Velocity + distinct | Flags bursts and unusual distinct-merchant fan-out in minutes. |
| Agent safety | Selection + counters | Rate limits and risky-action counters beside agent memory. |
Related models