🤖 The free pool — a cost-governed budget for free & demo spaces

Design doc, 2026-07-14. Status: designed, not built. Companion docs: docs/demo-spaces.md (the demo tier the pool contains) and docs/pricing-bands.md (the pricing that funds it). This doc extends the docs/tier-economics.md discipline: formulas are the contract, numbers are a dated snapshot.

The idea in one paragraph

Run the free tier as an error budget for money. A small accounting loop inside the cloud provisioner's existing 6-hour meter sweep computes (a) the estimated daily cost of every free space and demo from a tiny published cost model, (b) a daily free-pool budget derived from a percent-of-total-cost ceiling, net revenue, and an operator floor, and (c) one scalar, pressure = spend / budget. Pre-agreed thresholds on that scalar drive graceful degradation — shorter demo TTLs, then a pause on new free creates — and never touch an existing space. Demos get a carve-out funded first from the floor, so the try-it path survives even a red pool; only physical box limits can ever actually block a demo. The pool is revenue-indexed — paid spaces fund it — and the gauge is publishable on the status page next to the books, making the subsidy a checkable claim.

Survey honesty: no SaaS publicly runs a free tier as an explicit %-of-cost invariant. Every part is established — SRE error budgets with pre-committed exhaustion policies, cloud budget actions that actuate, Borg/spot-style surplus tiers, the Neon/Render/Heroku-Eco idle-suspend + suspend-don't-bill pattern, and the FCC Universal Service Fund as a real revenue-indexed pool (whose uncapped ratio ratcheting to ~38% is precisely the failure the X-ceiling here prevents). The composition is novel; every part is boring.

The budget formula

net_revenue_day = Σ over paid ledger spaces of net_eur_year / 365   (smoothed ~90d)

invariant_cap   = (X/100) × total_cost_day        # free never exceeds X% of total cost
revenue_pool    = (Y/100) × net_revenue_day       # the growth engine
base_floor      = LCHAT_POOL_BASE_EUR_DAY         # a pool exists at zero revenue

budget_day      = min( invariant_cap , max(base_floor, revenue_pool) )
demo_budget     = (D/100) × budget_day            # reserved for demos, funded first
pressure        = free_cost_day / budget_day

Chosen parameters (Paul, 2026-07-14): X = 25, Y = 30, floor = €0.20/day, D = 20. All config; changing them is philosophy, not engineering.

Shape notes:

• X is a ceiling, revenue is the engine, the floor is the bootstrap. At zero revenue the sunk box subsidises the free tier (the spot-capacity logic: the capacity is already paid for). As revenue grows, the Y-term takes over. X clamps everything — the anti-ratchet guard: the ratio can never float upward with demand; admission control absorbs excess demand instead.
• Smoothing: revenue is computed over trailing ~90 days of entitlement state, so one big customer churning shrinks the pool gradually — and a shrink only ever gates admissions; existing spaces are grandfathered by construction, because no actuator touches them.
• Demos are the cheapest thing offered (~€0.01 lifetime each), so the demo carve-out is small in euros and huge in units.

The cost model

Per instance and day — awake time, storage, noise:

cost_day(i) = awake_frac(i) × (C_slot + C_req)   # RAM/CPU share + S3 request tail while awake
            + stored_gb(i)  × C_store            # S3 replica (× retention) or disk share
            + C_noise                            # registry row, cert, wakes (≈ 0)

free_cost_day  = Σ cost_day(i) over spaces with entitlement in ('free','demo')
total_cost_day = C_fixed + Σ cost_day(i) over ALL ledger spaces

Awake-hours (wall-clock) is deliberately the metered thing, not "activity": utilization thresholds spawn keep-alive arms races (Oracle's free-tier idle detector did); wall-clock awake time is what the activator already measures, and the one gaming vector — holding a WebSocket open — makes that space expensive on paper, which is exactly what a later per-space awake-hours cap would key on.

Snapshot constants (2026-07, re-measure at tier-economics re-derivations):

| Constant | Placeholder | Source | |---|---|---| | C_fixed | ~€1.17/day | whole cloud plane: box + router/home/push/cloud | | C_slot | ~€0.027/day | box ÷ 40-instance materialized capacity | | C_req | ~€0.002/day | post-#836 always-awake S3 request tail | | C_store | ~€0.0014/GB-day | S3 × ~2 Litestream retention | | awake_frac free | 0.05 (assumed) | hibernate-by-default | | awake_frac demo | 0.30 (assumed) | 24h life, actively poked |

Worked typicals: a hibernation-dominant free space costs ~€0.6–0.9/year; a 24h demo ~€0.01 total; a Community & Friends subscription nets ~€39/year. The arithmetic is comfortable — even a 30% revenue share funds tens of free spaces per C&F subscription. At today's one-box scale the euro budget is not the binding constraint (RAM slots and disk are); the pool exists to be legible now and binding at scale.

Deriving cost from a config-declared model instead of metering is a deliberate trade: real per-instance cost attribution is heavy machinery for cents. It means the gauge is an estimate and must say so wherever published.

The control loop

Measured every existing meter sweep (6h) from the ledger + cost model; one row per sweep in a new additive pool_meter table (ts, free_count, demo_count, paid_count, free_cost_day, total_cost_day, budget_day, pressure, pruned to ~a year). Creates are gated against the latest reading; spikes are caught by the existing create breaker and controld's physical caps, and a correlated wake-storm shows up next sweep as a fast burn.

The pre-agreed policy (written before the budget is ever spent — SRE-style):

| Pressure | State | Behavior | |---|---|---| | < 0.8 | green | nothing. Surplus exists — this is the "free capacity available to anyone" signal docs/pricing-bands.md consumes | | 0.8 – 1.0 | amber | new demos get shorter TTL (24h → ~8h); status gauge amber; loud log line per sweep | | ≥ 1.0 | red | pause new free creates — stable error free_pool_full, honest copy below. Demos continue at amber settings | | ≥ 1.5 | deep red | demos shorten further / small retry-wait. Existing spaces: still untouched |

Never actuated, ever: suspending or deleting an existing space because of pool pressure. The only lifecycle ends remain the reaper's never-set-up rule and the demo TTL — pre-declared lifecycle, not budget enforcement.

At red, a free create answers 503 free_pool_full:

> "The free pool is full right now. Paying supports free spaces for those > who can't — as more people upgrade, the pool grows. Check back soon, or > upgrade to create a space now."

• Paid creates are never pool-gated (they fund the pool); the upgrade path stays open at red.
• No waitlist (decided): accounts are anonymous passkeys with no contact channel, and the survey found no product running a free-tier waitlist. Honest-no + the live public gauge instead — a refusal that's a checkable claim, not a shrug.
• Self-reclaim of the account's own dead slot still works at red (it creates no net-new spend).

Messaging (decided 2026-07-14)

Aggregate form only. The canonical line is:

> "Paying supports free spaces for those who can't."

The gauge publishes the aggregate ("paid spaces currently fund the free pool M× over"), never a per-space "your €5 funds these two spaces" — the personal link isn't mechanically true and invites weird expectations. M is re-derived with the tier-economics numbers and is verifiable against the public books.

Knobs and placement

LCHAT_POOL_MAX_SHARE=25          # X (0/unset = pool off)
LCHAT_POOL_REVENUE_SHARE=30      # Y
LCHAT_POOL_BASE_EUR_DAY=0.20     # floor
LCHAT_POOL_DEMO_SHARE=20         # D
LCHAT_POOL_COSTS="fixed_day=1.17,slot_day=0.027,req_day=0.002,storage_gb_day=0.0014,awake_free=0.05,awake_demo=0.30"
LCHAT_POOL_DRY_RUN=1             # rollout: compute, log, publish — gate nothing

Revenue input: an additive net_eur_year field per entry in the existing LCHAT_STRIPE_PRICES JSON (unknown fields are ignored by today's decode; entries without it contribute 0 and log a warning). With pricing bands (docs/pricing-bands.md), each band×tier entry carries its own net_eur_year — discounted spaces grow the pool exactly in proportion to what they actually pay, which is also the honest version of the marketing line. Once Stripe Tax ships (tax-inclusive prices), net_eur_year figures are net-of-VAT approximations; the pool tolerates that error comfortably.

| Layer | Enforces | |---|---| | home | nothing pool-related (IP/PoW gates are the demo doc's) | | cloud | the pool: budget math, pressure, free_pool_full admission, demo carve-out + dynamic TTL, pool_meter, the reap | | controld | physical capacity only; the awake stat (phase 4). Never learns about money | | router/activator | hibernation; (phase 4) per-entitlement idle-window override |

Existing knobs keep their jobs: LCHAT_CLOUD_MAX_CREATES_PER_DAY (blunt spike breaker), LCHAT_CLOUD_QUOTA, the physical caps, LCHAT_POW_BITS, the reaper family, storage caps.

Interfaces

• Demos (docs/demo-spaces.md): live in the same spaces ledger as entitlement='demo'; draw from the carve-out; TTL and live-cap are pressure-tunable; never S3-replicate (decided — the flag is the demo doc's PR 1).
• Pricing (docs/pricing-bands.md): the pool consumes one number per paid space (net_eur_year). "Free capacity exists" is defined as pressure < 0.8, exposed read-only (GET /api/pool) so the pricing surfaces and the status page share one source of truth.

Phasing

1. PR 1 — the gauge, no behavior change. Parse LCHAT_POOL_* + net_eur_year; compute spend/budget/pressure in the meter sweep; pool_meter table; log line; admin-token GET /api/pool. Ships dark (pool off unless LCHAT_POOL_MAX_SHARE is set). Pure budget-math unit tests + a seeded meter-sweep test.
2. PR 2 — admission control. free_pool_full at pressure ≥ 1 in createSpaceHandler (free creates only); home relays the message; LCHAT_POOL_DRY_RUN gates. Tests mirror the createBudget ones.
3. PR 3 — demo integration. Carve-out budget, pressure-tuned TTL. (Sequenced with the demo doc's PRs.)
4. PR 4 — measurement. controld stats gain awake; the meter samples a trailing per-space awake_frac; measured beats assumed. Optional idle-window tightening at amber.
5. PR 5 — publish. The gauge on the status page next to the books ("the free pool: N spaces, funded M× over, state: green"), estimate caveat included.

Each PR is independently revertible; nothing before PR 2 can refuse anyone. The rollout follows the reaper's proven dry-run-then-arm pattern.