coconutlabs

working drawings

Diagrams you could build from.

Real values, failure modes, revision blocks. Marketing diagrams lie by omission; these are the drawings we work from.

01 · kvwarden admission path

How a quiet tenant stays quiet: fairness enforced before a tenant-blind engine, with the measured cost of not doing it drawn dashed.

REQUESTRESPONSETOKEN BUCKETrefill = rate_limit_rpm / 60tokens per secondburst = bucket capacityADMISSION GATEmax_concurrent in flightqueue wait ≤ 30 sover the wait: shedVLLM ENGINEvLLM 0.19.1continuous batchingno tenant identitytenant-blind past this lineFIFO baseline · no bucket, no gate61.5 ms p99 · quiet tenant · post-warmup · n=3111,585 ms p99 · same tenant when FIFO meets a flood · 26xregime: 1x A100 · Llama-3.1-8B · vLLM 0.19.1 · 300 s windowTITLE kvwarden admission pathSCALE NTS · DATE 2026-08 · REV ADRAWN coconut labs · SHEET 01 of 03
dwg-01 · kvwarden admission path1x A100 · Llama-3.1-8B · vLLM 0.19.1 · 300 s
Path: request, then token bucket, then admission gate, then vLLM engine, then response. The token bucket refills at rate_limit_rpm over 60 tokens per second with burst up to bucket capacity. The admission gate holds max_concurrent requests in flight with a queue wait of up to 30 seconds, then sheds. The engine is tenant-blind. Measured: 61.5 milliseconds p99 for a quiet tenant post-warmup, n equals 311. The dashed FIFO bypass measures 1,585 milliseconds p99, 26 times slower. Regime: one A100, Llama-3.1-8B, vLLM 0.19.1, 300 second window.
Read this drawing
  1. A request enters at the left carrying a tenant id. Everything past the boundary line has no idea tenants exist, so fairness has to be enforced before the engine.
  2. The token bucket refills at rate_limit_rpm divided by 60 tokens per second, and the bucket depth is the burst allowance: a tenant can spend saved tokens in a spike but cannot beat the refill rate for long.
  3. The admission gate caps requests in flight at max_concurrent. A request that cannot get a slot waits up to 30 seconds, then is shed instead of queueing forever.
  4. The vLLM engine runs continuous batching and is tenant-blind by design; the dash-dot line marks where tenant identity stops existing.
  5. The accent dimension is the measured result: 61.5 ms p99 for a quiet tenant post-warmup, n=311, on 1x A100, Llama-3.1-8B, vLLM 0.19.1, over a 300 s window.
  6. The dashed dimension is the control: the same quiet tenant behind a flood sees 1,585 ms p99 when requests go straight to the engine FIFO, 26x the gated figure.

provenance for the dimensions: /benchmarks →

02 · the gated library

How a private library on a laptop serves the public internet with no open port, and what each status code means when it breaks.

BROWSERany deviceno vpn clientCLOUDFLARE EDGEaccess policy checkemail allowlist n=4or service tokenTUNNELcloudflared · quicoutbound-onlyno open inbound portORIGINlocalhost:8000python http.serverSTATIC WINGShtml + assetsread-onlyno auth → 302 to access loginwrong email → 403 denytunnel down → 530 from edgehttp.server down → 502missing file → 404debug from the status code:302 auth · 403 identity · 530 tunnel · 502 origin · 404 pathregime: origin is a laptop behind nat · no inbound port is ever openTITLE the gated librarySCALE NTS · DATE 2026-08 · REV ADRAWN coconut labs · SHEET 02 of 03
dwg-02 · the gated librarycloudflare access · quic · outbound-only
Path: browser, then Cloudflare edge, then cloudflared tunnel, then origin at localhost 8000, then static wings. The edge runs a Cloudflare Access check: an email allowlist of four people plus a service token for automation. The tunnel is cloudflared over QUIC, outbound-only, no open inbound port. The origin is python http dot server serving read-only files. Failure modes by hop: no auth gives 302 to the Access login, wrong email gives 403, tunnel down gives 530 from the edge, origin down gives 502, missing file gives 404.
Read this drawing
  1. A browser asks for the library from any device; there is no VPN client. DNS is proxied, so the origin address is never public.
  2. The Cloudflare edge runs the Access check first: a four-address email allowlist for people, a service token for automation. No auth means a 302 to the Access login; a valid session with the wrong email is a 403.
  3. Traffic that passes rides a cloudflared tunnel over QUIC. The tunnel is outbound-only: the laptop dials out, nothing dials in, so there is no inbound port to scan.
  4. The origin is python http.server on localhost:8000 serving static wings of files. It never sees unauthenticated traffic.
  5. When it breaks, the status code names the failing layer, which is why this drawing is also the runbook: 302 auth, 403 identity, 530 tunnel, 502 origin, 404 path.

03 · the deterministic gate

What stands between a commit and production on this site. Nothing lands on a red gate.

any red gate: fix, recommit · nothing lands on a red gateCOMMITby hand or agentTYPECHECKtsc --noEmitDESIGN-LINThex · dashes · fontsUNITvitest · 32 testsBUILDnext buildagent ranges:agent-audit before mergeE2E · 3 ENGINESchromium ff webkitPIXEL GATE14 routes · 4 shots eachmaxDiffPixels 0DEPLOYmain → productionVERIFY-LIVE9 surfaces+ post-auth probeLIVEpixel diff intended? baseline update must state what changed and whyregime: coconutlabs.org · npm run test:all + npm run test:visual · darwin local, linux in ciTITLE the deterministic gateSCALE NTS · DATE 2026-08 · REV ADRAWN coconut labs · SHEET 03 of 03
dwg-03 · the deterministic gatemaxDiffPixels 0 · darwin + linux baselines
Path: commit, then typecheck, then design-lint, then 32 unit tests, then production build, then end-to-end tests in Chromium, Firefox and WebKit, then the pixel gate screenshotting 14 routes four ways each at maxDiffPixels zero, then deploy, then verify-live probing nine production surfaces plus a post-auth path. Dashed rails return every failing gate to commit. A pixel diff is only allowed through as a deliberate baseline update with a stated reason, and commits in agent ranges get agent-audit before merge.
Read this drawing
  1. Every change starts as a commit, by hand or by agent; commits in agent ranges also get agent-audit before merge.
  2. Four static gates run first: typecheck, design-lint (raw hex, em dashes, icon libraries, font literals), the vitest unit suite at 32 tests, and a production build.
  3. Playwright then drives the built site in three engines: Chromium, Firefox, WebKit.
  4. The pixel gate screenshots 14 routes four ways each (two viewports, light and dark) and compares at maxDiffPixels 0 against committed baselines, darwin locally and linux in CI. One changed pixel is a red gate.
  5. A red gate loops back to commit. A pixel diff has exactly one legitimate exit: an intended change, a deliberate baseline update, and a commit message stating what changed visually and why.
  6. After deploy, verify-live probes 9 production surfaces plus a post-auth path; a failure there loops back like any other red gate.
← All projectsBenchmarks