Store Stats, Prune and the Community Caps

ELI5

The hosted engine keeps a shelf of Pellets. You can ask how full the shelf is and clear out old ones. On the free plan, the convenience jobs (packing a Pellet, running a workspace operation) are rationed to 50 each a month; checking and unpacking a Pellet is never rationed, because that is the security part.

Technical Deep Dive

Source: nestr-tools/engine internal/server/pellet_handlers.go:236-290, internal/server/rest.go:146-164, internal/server/usage.go:80-110, internal/pellets/pellets.go:901-912, internal/usage/usage.go:61-71,84-131 @e9180e4; nestr-tools/web src/hooks/useCacheStatus.ts:28-46 @6f42cca; nestr-tools docs/decisions/2026-10-22-early-access-design-partner-seat.md §3 (countersigned 2026-10-23) @b8f0585; read 2026-10-25.

Stats

GET /api/pellets/stats returns totalSize, pelletCount, originalSize, compressedSize, compressionRatio. It returns no hit count, miss count or hit rate. The web hook useCacheStatus still computes a health badge from stats.hitRate (thresholds 0.8 / 0.5 / 0.2) and utilisation against a hard-coded 1024 MB; with no hitRate in the response that badge has nothing real to read. The 1024 MB “free tier” figure is a client constant, not a plan limit.

Prune

flowchart TD
  A["POST /api/pellets/prune"] --> B{"all true?"}
  B -- "yes" --> Z["days = 0"]
  B -- "no" --> D["days = body.days, 0 if omitted"]
  Z --> P["Store.Prune(days)"]
  D --> P
  P --> Q{"days at most 0, or created before the cutoff?"}
  Q -- "yes" --> R["remove pellet"]
  Q -- "no" --> K["keep"]
  R --> W["broadcast pellet:pruned with removed count"]

Omitting days is a full wipe, the same as all: true (pellets.go:906-909). Prune is rate-limited but not quota-capped.

Community caps

flowchart LR
  REQ["capped route"] --> M{"usage meter configured?"}
  M -- "no" --> U["503 E_USAGE_UNAVAILABLE, one WARN"]
  M -- "yes" --> C["atomic consume one unit for org and month"]
  C -- "over cap" --> X["402 E_FREE_QUOTA_EXCEEDED"]
  C -- "ok" --> H["handler runs, unit refunded if refused before work"]

Caps come from env with those defaults (NESTR_COMMUNITY_COMPRESS_MONTHLY_LIMIT, NESTR_COMMUNITY_OPERATIONS_MONTHLY_LIMIT; negative means unlimited). An unknown plan is treated as Community. The landing page says the units act “on the shared demo workspace”.

Key Terms

• withQuota → middleware that takes a unit before the handler and refunds it on a no-charge refusal.
• E_FREE_QUOTA_EXCEEDED → the 402 refusal code for an exhausted Community allowance.
• E_USAGE_UNAVAILABLE → 503 when the meter cannot answer; capped routes fail closed.

Q&A

Q: What fields does GET /api/pellets/stats return, and does it include a hit rate? A: Total size, pellet count, original size, compressed size and compression ratio. No hit rate; the dashboard’s hit-rate badge has no engine field behind it.

Q: What does prune remove when days is 0 or omitted? A: Everything. Store.Prune removes a pellet when days <= 0 or when it was created before the cutoff.

Q: Which hosted routes are capped on Community, and which are never capped? A: Compress and the three workspace operations, 50 each a month. Extract, which runs the verification gate, is never capped on any plan.

Examples

A Community organisation hits 50 compressions on the 20th. The 51st POST /api/pellets/compress gets 402 E_FREE_QUOTA_EXCEEDED; its POST /api/pellets/extract calls keep working, and the counter resets at the start of the next UTC month.