Hyperscale-first
Toda decisão de implementação segue a tríade: escalabilidade (estruturas que funcionam em 100×), eficiência (menor overhead em I/O, cache, índice, streaming), sustentabilidade (código que um eng novo entende em 10 min). Esforço igual → escolher a que escala melhor. Esforço desproporcional → ship a simples + ticket de follow-up para promoção.
Policy: hyperscale-first
Every technical decision made during implementation must be guided by three criteria, in priority order:
1. Scalability
Prefer data structures, algorithms, and architectures that work correctly at 100× the current volume without a rewrite. Concrete anti-patterns to avoid:
- Coupling two components such that scaling one requires rewriting the other
- Global mutable state that becomes a bottleneck under concurrent load
- Designs that require the entire dataset to fit in memory
- Sequential processing where the work is trivially parallelisable
2. Efficiency
Choose the lowest-overhead path:
| Prefer | Over |
|---|---|
| Async I/O | Blockingsync IO |
| Pre-computed cache | Re-computing the same result |
| Index lookup | Full table/slice scan |
| Streaming | Full buffering before processing |
| A single round-trip | Multiple sequential round-trips |
3. Sustainability
Code that a new engineer understands in 10 minutes:
- No "clever" tricks that require deep context to read
- Interfaces clean enough that the implementation can be swapped without
touching consumers
- No hacks that accumulate debt — if you must compromise, open a ticket
Decision rule
When two approaches are equivalent in implementation effort: *lways choose the one that scales better*
When the scalable approach requires significantly more effort than the ticket justifies:
- Implement the simpler version
- Open a follow-up backlog ticket that explicitly names the hyperscale
path and the trigger condition (e.g., "migrate to TiKV when tenants > 10k")
What this policy does NOT require
- Premature optimisation — do not add complexity for hypothetical future
load that has no concrete signal.
- Over
engineering simple scripts or oneoff tools. - Rewriting working code solely to match this policy; apply it at the
boundary of what you're actively changing.
Relationship to other policies
This policy governs implementation choices. It is downstream of policies/reuse-first.kmd (which governs what to build) and upstream of specific specs (which govern how specific features should behave).
*ultitenant axis (companion policy)* hyperscalefirst cobre o eixo "escala de volume" (100×, eficiência, sustentabilidade). O eixo *rtogonal*"isolamento entre N koderuserid e N workspace_id" é governado por policies/multi-tenant-by-default.kmd. Os dois eixos são independentes: um sistema pode escalar bem mas vazar entre tenants (falha de multi-tenant), ou isolar bem mas não escalar (falha de hyperscale). Toda decisão de implementação *assa pelos dois*
*torage substrate* a aposta concreta da Koder Stack pra cobrir os dois eixos é kdb (Rust, TiKV substrate — historicamente kdb-next até o rename 20260522 ratificado em ticket #730) como unified data plane. Ver rfcs/stack-RFC-001-kdb-as-unified-data-plane.kmd pra a visão de convergência multi-model.