Usage Metering: Community Caps and the Security Record

ELI5

The hosted engine keeps two notebooks per organisation. One counts the free-plan allowance for convenience jobs. The other is a security record: how many Pellets it verified and how many it refused, which every plan sees as running totals and Early Access also sees day by day for 90 days.

Technical Deep Dive

Source: nestr-tools/engine internal/usage/usage.go:61-71,80-131, internal/usage/meter.go:15-37,68-226,186-224,275-296, internal/usage/postgres.go:61, internal/server/usage.go:80-130, internal/server/rest.go:146-162 @e9180e4; nestr-tools docs/decisions/2026-10-22-early-access-design-partner-seat.md §2-§3 (countersigned 2026-10-23) @b8f0585; read 2026-10-25.

classDiagram
  class Meter {
    +Consume(ctx, id, feature) Decision
    +Refund(ctx, decision)
    +RecordVerifiedExtraction(ctx, id, pid)
    +RecordRefusal(ctx, id, code)
    +Report(ctx, id) Report
  }
  class Report {
    +string org
    +string plan
    +string plan_source
    +time resets_at
    +map quotas
    +map quotas_person
    +SecurityRecord security_record
    +DailyPoint[] history
    +bool history_locked
    +string[] never_limited
  }
  class SecurityRecord {
    +Totals totals
    +int days_on_record
  }
  class PostgresStore
  Meter --> PostgresStore : DATABASE_URL
  Meter --> Report
  Report --> SecurityRecord

Caps

withQuota takes a unit atomically before the handler (racing requests cannot overshoot) and refunds it only when the handler signals it refused before doing any work. Over the cap is 402 E_FREE_QUOTA_EXCEEDED; a missing or failing meter is 503 E_USAGE_UNAVAILABLE with a one-time WARN, so capped routes fail closed (I-7). Community is also counted per person across all of that user’s Community organisations (quotas_person); a request is refused when either the organisation’s or the person’s counter runs out (meter.go:206-210). Defaults are overridable by env; a negative value means unlimited; an unknown plan gets Community’s allowance. The report’s never_limited list names verification, extract_and_install, quarantine, refusal_explanations and account_security.

Security record

flowchart LR
  EX["POST /api/pellets/extract"] --> GATE["verification gate decides"]
  GATE -- "pass" --> RV["RecordVerifiedExtraction"]
  GATE -- "refuse" --> RR["RecordRefusal with code"]
  RV --> ST[("usage store, per org subject")]
  RR --> ST
  ST --> REP["GET /api/usage"]
  REP --> ALL["every plan: running totals, days on record"]
  REP --> EA["Early Access only: 90 days of daily history"]

Extract is never capped: it reports its outcome to the record only after deciding it (rest.go:160-162). On Community the report sets history_locked: true instead of returning history (meter.go:283-294); the web Security Record card offers JSON export of that history to Early Access.

Key Terms

• Decision → the result of Consume: allowed or not, with usage and limit, refundable.
• security record → per-organisation totals of verified extractions and refusals.
• history_locked → Community flag in the usage report in place of daily points.

Q&A

Q: Which operations consume a Community unit, and when is a unit handed back? A: POST /api/pellets/compress (compress allowance) and POST /api/operations/run, /sync, /assemble (operations allowance). A unit is refunded only if the handler refused the request before doing any work.

Q: What does GET /api/usage return on Community versus Early Access? A: Both get quota usage (organisation, and per person on Community), plan and plan source, and security-record running totals with days on record. Early Access also gets 90 days of daily history; Community gets history_locked: true.

Q: Where is usage stored, and what happens if the meter is missing? A: In Postgres on the engine’s DATABASE_URL (PostgresStore). Without a meter, capped routes answer 503 E_USAGE_UNAVAILABLE after a one-time WARN, and /api/usage answers 503.

Examples

A Community organisation runs assemble 50 times by the 15th. The 51st call is 402 with the allowance and usage in the body; extracts that verify or refuse keep updating its security-record totals, and on the 1st of the next month UTC the operations counter starts again.