Usage Quota Stale-Period and Race Automation: Last Month's Number, Still Counted

Storing a running total that represents "usage this billing period" and physically resetting it to zero only when the next increment happens to arrive is a common, reasonable-looking simplification — it avoids needing a separate scheduled job whose only purpose is zeroing counters at the start of every period. The simplification has one real cost: for the entire stretch of time between a new period starting and that organization's first metered action of the new period, the counter row on disk still holds the PREVIOUS period's final total. Any code reading that counter directly, without separately checking whether the period it belongs to has actually rolled over, is reading a number that is real, but stale — describing usage that has already legally expired against the plan's own terms.

Centriu Axiom enforces a monthly usage quota per organization and per metered resource by keeping a single counter row — an organization ID, a resource name, a running numeric value, and the date that value's current accounting period began. A check runs before any metered action, comparing the counter's stored current value against the plan's own configured limit for that resource, and denies the action if the limit has already been reached.

Before this fix, that check read `counter?.current_value ?? 0` directly and used it as-is. The counter itself is only ever physically zeroed as a side effect of the NEXT increment call — there is no separate, scheduled process that resets every organization's counters the moment a new calendar month begins. The practical consequence: for any organization that had not yet performed a single metered action since a new month started, the counter row still held the FINAL accumulated total from the PREVIOUS month, potentially sitting right at or near the plan's own limit — and the entitlement check, reading that value with no awareness that its own period had already expired, would treat a fresh, genuinely-zero-usage month as if the organization were already at or near its cap. A paying customer, entitled to a full new month of usage under their plan, could be denied an action in the opening days of that new month for no reason connected to their actual current usage at all.

A second, entirely independent defect lived in the same counter's own increment path. Incrementing it was implemented as two separate steps inside the application's own code: fetch the counter's current value with one query, compute the new value as current-plus-amount in JavaScript, then `upsert` that computed value back with a second query. Two increments for the same organization and resource arriving close enough together — a realistic scenario for any metered action a user is able to trigger twice within a short window, whether deliberately or through a retried request — could both execute their initial read before either one's write lands, both computing their "new" value from the SAME starting number. The second upsert to complete would overwrite the first's result, silently discarding one genuine increment and leaving the counter undercounting real usage — the opposite failure mode from the stale-period bug, letting real usage run ahead of what the counter reports rather than behind it.

Both were fixed, independently, on their own sides of the problem. The entitlement check now computes the start of the current calendar month in UTC and compares it against the counter's own stored period-start value; when the counter's period is older than the current month, the check treats current usage as zero, regardless of whatever value is still physically sitting in the `current_value` column until the next real increment gets around to resetting it. Separately, and more fundamentally, the increment path itself moved from a two-step application-level read-then-write to a single, atomic Postgres function — `axiom_quota_check_and_increment`, running with elevated (`SECURITY DEFINER`) privilege specifically so it can perform the operation server-side in one statement — using an `INSERT ... ON CONFLICT DO UPDATE` that reads, resets-if-stale, and increments the counter as one indivisible database operation, closing the race independently of the client-side stale-period compensation. The same investigation also corrected the separate decrement and reset code paths' own `upsert` conflict target, which had been written against a two-column key (`organization_id, resource`) that did not match the table's actual three-column composite unique constraint (`organization_id, resource, period`) already used correctly elsewhere in the same file — bringing all three write paths (increment, decrement, reset) onto a consistent, correct conflict target.

Before the fix, an organization on the first day of a new billing month, having taken zero metered actions so far that month, could still have its counter row showing the previous month's final total — say, a value sitting at the plan's own configured limit. The very first legitimate action of the new month would be checked against that stale number and denied, even though the organization's real usage for the new period was genuinely zero. After the fix, the same check recognizes the counter's stored period no longer matches the current month, treats current usage as zero, and allows the action — with the counter itself correctly reset the moment that first action is actually recorded.

Centriu Axiom's monthly usage-quota enforcement now correctly recognizes when a stored counter belongs to an already-expired billing period, and performs every increment as a single atomic, period-aware database operation — closing a gap where a paying organization could be denied a plan-entitled action based on a prior month's stale total, and an independent race where two near-simultaneous increments could silently undercount real usage.

This automation governs the internal correctness of Centriu Axiom's own monthly usage-counter enforcement — it does not change what any plan's actual usage limits are, which remain a separate, published commercial decision, and applies specifically to metered resources tracked on a monthly period; a resource with no monthly reset concept at all would not be exposed to the stale-period side of this specific defect.

Resetting a usage counter only as a side effect of its next increment, rather than through a separate scheduled process, avoids needing extra infrastructure whose only job is zeroing counters at the start of every period — a real simplification. The cost of that simplification is that any code reading the counter directly, without ALSO checking whether its stored period has actually expired, is trusting a number that can be real but stale. Adding that period comparison on the read path, and moving the write path to a single atomic, period-aware database operation, keeps the original simplification (no separate reset job is needed) while closing both the stale-read and the increment race it otherwise leaves open.