Hyperscale-first

mandatory

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.

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: always choose the one that scales better.

When the scalable approach requires significantly more effort than the ticket justifies:

  1. Implement the simpler version
  2. Open a follow-up backlog ticket that explicitly names the hyperscale

    path and the trigger condition (e.g., "migrate to TiKV when tenants > 10k")

Subordinação ao Princípio #2 (Quality > Speed), absoluto desde 2026-05-29: este atalho "ship simples + ticket" só se ativa quando o usuário pede velocidade/economia explicitamente. Sem pedido explícito, a solução de longo prazo ganha mesmo a maior custo de esforço — em qualquer camada, inclusive produto. Ver policies/stack-principles.kmd §2.

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 one-off 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).

Multi-tenant axis (companion policy): hyperscale-first cobre o eixo "escala de volume" (100×, eficiência, sustentabilidade). O eixo ortogonal "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 passa pelos dois.

Storage substrate: a aposta concreta da Koder Stack pra cobrir os dois eixos é kdb (Rust, TiKV substrate — historicamente kdb-next até o rename 2026-05-22 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.