@unitpad/modules 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bowen Deng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @unitpad/modules
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The numbers that [UnitPad](https://unitpad.app) sheets import with `use`: latencies, throughputs, sizes, prices and limits for
+system design, each with its source. They are plain [Numbat](https://numbat.dev) modules, so they work in UnitPad and in the Numbat
+command line.
+
+```numbat
+use latency::hardware
+use throughput::s3
+
+latency_main_memory / latency_l1_cache
+throughput_s3_get_requests_per_prefix * 4
+```
+
+## In UnitPad
+
+Open the Modules menu, or type `use` in a sheet. The module's card shows its source and the month its numbers were last checked.
+
+## In the Numbat command line
+
+```bash
+npm install @unitpad/modules
+export NUMBAT_MODULES_PATH="$PWD/node_modules/@unitpad/modules/modules"
+```
+
+Not run yet. To have the shared count units (`request`, `message`, `IOPS`) in every session, put `use units::systems` in your `init.nbt`.
+
+## Licence
+
+MIT. See [`LICENSE`](LICENSE).
+
+## Contribute
+
+Fix an outdated number, add a module, or replace a dead source. [`CONTRIBUTING.md`](CONTRIBUTING.md) says how, and
+[`docs/style.md`](docs/style.md) says how a module is written.

package/modules/availability.nbt

@@ -0,0 +1,66 @@
+# Availability and durability
+# Nines, downtime budgets, composing components, and real failure rates.
+# availability_serial / availability_parallel assume independent failures;
+# correlated failures (same rack, AZ, deploy, config push) make reality worse.
+# Import with:  use availability    then use the availability_* values and functions
+# title: Availability
+# checked: unverified
+# description: Nines and downtime budgets, serial/parallel composition, disk AFR, S3/EC2 durability and SLAs
+# vendor: aws, backblaze
+
+@url("https://en.wikipedia.org/wiki/High_availability")
+@description("Availability with n nines (n ≥ 0): availability_nines(4) is 0.9999")
+@example("availability_nines(4)")
+fn availability_nines(n: Scalar) -> Scalar = 1 - 10^(-n)
+
+@url("https://en.wikipedia.org/wiki/High_availability")
+@description("Downtime per year at availability fraction a (0 ≤ a ≤ 1; pass 0.999 or 99.9%, not 99.9). 99.9% is ~8.8 h, 99.99% is ~53 min, 99.999% is ~5.3 min")
+@example("availability_downtime_year(0.999)")
+fn availability_downtime_year(a: Scalar) -> Time = (1 - a) * 1 year
+
+@url("https://en.wikipedia.org/wiki/High_availability")
+@description("Average downtime per month at availability fraction a (0 ≤ a ≤ 1; pass 0.999 or 99.9%, not 99.9), using Numbat's average month unit. 99.9% is ~44 min, 99.99% is ~4.4 min")
+@example("availability_downtime_month(0.999)")
+fn availability_downtime_month(a: Scalar) -> Time = (1 - a) * 1 month
+
+@url("https://en.wikipedia.org/wiki/Reliability_engineering")
+@description("Availability of two components in series (both must work): multiply their availability fractions a and b, each from 0 to 1")
+@example("availability_serial(0.99, 0.999)")
+fn availability_serial(a: Scalar, b: Scalar) -> Scalar = a * b
+
+@url("https://en.wikipedia.org/wiki/Reliability_engineering")
+@description("Availability of n independent replicas where any one suffices: 1 - (1 - a)^n. Pass availability a from 0 to 1 and a nonnegative replica count n")
+@example("availability_parallel(0.99, 3)")
+fn availability_parallel(a: Scalar, n: Scalar) -> Scalar = 1 - (1 - a)^n
+
+# --- Measured failure rates ---
+# highlight: HDD AFR
+@url("https://www.backblaze.com/blog/backblaze-drive-stats-for-2025/")
+@description("Hard drive annualized failure rate (Backblaze 2025: 1.36% across ~344k drives; lifetime 1.30%)")
+let availability_hdd_afr = 0.0136
+
+@url("https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html")
+@description("EBS gp3/gp2 volume annual failure rate (AWS: no higher than 0.2%)")
+let availability_ebs_afr = 0.002
+
+# --- Provider design targets and SLAs ---
+# highlight: S3 durability
+@url("https://aws.amazon.com/s3/storage-classes/")
+@description("S3 Standard designed durability (11 nines)")
+let availability_s3_durability = 0.99999999999
+
+@url("https://aws.amazon.com/s3/storage-classes/")
+@description("S3 Standard designed availability (99.99%)")
+let availability_s3_designed = 0.9999
+
+@url("https://aws.amazon.com/s3/sla/")
+@description("S3 Standard availability SLA, what AWS credits against (99.9%)")
+let availability_s3_sla = 0.999
+
+@url("https://aws.amazon.com/compute/sla/")
+@description("EC2 region-level SLA for instances spread over multiple AZs (99.99%)")
+let availability_ec2_region_sla = 0.9999
+
+@url("https://aws.amazon.com/compute/sla/")
+@description("EC2 single-instance SLA (99.5%, ~3.6 h/month)")
+let availability_ec2_instance_sla = 0.995

package/modules/capacity.nbt

@@ -0,0 +1,67 @@
+# Capacity-planning rules of thumb
+# Peak traffic, utilization headroom, Little's Law, queueing, fan-out tails and USL.
+# Import with:  use capacity    then use the capacity_* values and functions
+# title: Capacity
+# checked: unverified
+# description: Peak factor, utilization target, node sizing, queueing (Little's Law, M/M/1, USL) and fan-out tail math
+
+# highlight: peak factor
+@description("Peak-to-average traffic factor (2-5; rule of thumb with no primary source, replace with your measured peak/avg)")
+let capacity_peak_factor = 3
+
+# highlight: target util
+@url("https://en.wikipedia.org/wiki/M/M/1_queue")
+@description("Keep steady-state utilization below this; single-server queueing delay grows as rho/(1-rho)")
+let capacity_target_utilization = 0.7
+
+# highlight: seconds/day
+@url("https://en.wikipedia.org/wiki/Day")
+@description("Seconds per day (~10^5 s, so QPS is roughly daily actions / 86_400 s)")
+let capacity_seconds_per_day = 86_400 s
+
+@url("https://en.wikipedia.org/wiki/Little%27s_law")
+@description("Concurrency in flight (Little's Law, L = lambda * W): rate times time")
+@example("capacity_concurrency(200 request/s, 0.5 s)")
+fn capacity_concurrency<R: Dim>(rate: R / Time, w: Time) -> R = rate * w
+
+@url("https://en.wikipedia.org/wiki/M/M/1_queue")
+@description("M/M/1 mean queueing delay in units of service time, rho/(1-rho); requires 0 ≤ rho < 1. Values: 1.0 at 50%, 2.3 at 70%, 9.0 at 90%. A pool of many workers (M/M/c) queues far less at the same rho")
+@example("capacity_wait_multiplier(0.7)")
+fn capacity_wait_multiplier(rho: Scalar) -> Scalar = rho / (1 - rho)
+
+@url("https://en.wikipedia.org/wiki/M/M/1_queue")
+@description("M/M/1 mean response time in units of service time, 1/(1-rho); requires 0 ≤ rho < 1. Values: 2x at 50%, 3.3x at 70%, 10x at 90%")
+@example("capacity_response_multiplier(0.7)")
+fn capacity_response_multiplier(rho: Scalar) -> Scalar = 1 / (1 - rho)
+
+@url("https://en.wikipedia.org/wiki/M/M/c_queue")
+@description("Nodes so each runs at or below a given utilization (0 < utilization ≤ 1): ceil(load / (per_node * utilization))")
+@example("capacity_nodes_with_utilization(5000 request/s, 1000 request/s, 0.7)")
+fn capacity_nodes_with_utilization<D: Dim>(load: D, per_node: D, utilization: Scalar) -> Scalar =
+  ceil(load / (per_node * utilization))
+
+@url("https://en.wikipedia.org/wiki/M/M/c_queue")
+@description("Nodes so each runs at or below capacity_target_utilization (the module default). Pass your own utilization with capacity_nodes_with_utilization")
+@example("capacity_nodes(5000 request/s, 1000 request/s)")
+fn capacity_nodes<D: Dim>(load: D, per_node: D) -> Scalar =
+  capacity_nodes_with_utilization(load, per_node, capacity_target_utilization)
+
+@url("https://cacm.acm.org/research/the-tail-at-scale/")
+@description("Fraction of fan-out requests that hit at least one slow backend: 1 - (1 - p_slow)^n. 1% slow over 100 backends is 63%")
+@example("capacity_fanout_slow(0.01, 100)")
+fn capacity_fanout_slow(p_slow: Scalar, n: Scalar) -> Scalar = 1 - (1 - p_slow)^n
+
+@url("https://sre.google/sre-book/addressing-cascading-failures/")
+@description("Load amplification when every layer retries: attempts^depth (Google SRE: 3 retries = 4 attempts at 3 layers is 64x)")
+@example("capacity_retry_amplification(4, 3)")
+fn capacity_retry_amplification(attempts: Scalar, depth: Scalar) -> Scalar = attempts^depth
+
+@url("http://www.perfdynamics.com/Manifesto/USLscalability.html")
+@description("Universal Scalability Law relative throughput C(N) for node count N > 0, contention alpha ≥ 0, and coherency beta ≥ 0")
+@example("capacity_usl(8, 0.1, 0.01)")
+fn capacity_usl(n: Scalar, alpha: Scalar, beta: Scalar) -> Scalar = n / (1 + alpha * (n - 1) + beta * n * (n - 1))
+
+@url("http://www.perfdynamics.com/Manifesto/USLscalability.html")
+@description("Node count where USL throughput peaks, N* = sqrt((1 - alpha) / beta). Requires 0 ≤ alpha < 1 and beta > 0")
+@example("capacity_usl_peak_nodes(0.1, 0.01)")
+fn capacity_usl_peak_nodes(alpha: Scalar, beta: Scalar) -> Scalar = sqrt((1 - alpha) / beta)

package/modules/cost.nbt

@@ -0,0 +1,74 @@
+# AWS list prices, us-east-1
+# On-demand list prices; tiers, savings plans and other regions differ.
+# Prices use the built-in `USD` unit (dimension Money).
+# Import with:  use cost    then use the cost_* values
+# usage: cost_s3_storage * 10 TB * 1 year -> USD
+# usage: cost_ec2_vcpu * 8 vcpu * 1 hour -> USD
+# usage: cost_s3_put * 100_000 request -> USD
+# usage: cost_ebs_gp3_iops * 1_000 IOPS * 1 month -> USD
+# usage: cost_dynamodb_write * 1_000_000 dynamodb_write_request_unit -> USD
+# title: Cost (AWS)
+# checked: 2026-10
+# description: AWS us-east-1 list prices: compute, S3, EBS, DynamoDB and data transfer
+# vendor: aws
+# source: https://aws.amazon.com/pricing/
+
+# --- Compute ---
+# `vcpu` is a shared unit (`units::systems::compute`), so per-vCPU prices scale by a typed vCPU count.
+
+# highlight: m7i.large
+@url("https://instances.vantage.sh/aws/ec2/m7i.large")
+@description("EC2 m7i.large on-demand, Linux (2 vCPU, 8 GiB)")
+let cost_ec2_m7i_large = 0.1008 USD / hour
+
+@url("https://instances.vantage.sh/aws/ec2/m7i.large")
+@description("EC2 general-purpose price per vCPU-hour, 4 GiB RAM per vCPU (cost_ec2_m7i_large / (2 vcpu))")
+let cost_ec2_vcpu = cost_ec2_m7i_large / (2 vcpu)
+
+# --- S3 Standard ---
+# highlight: S3 storage
+@url("https://aws.amazon.com/s3/pricing/")
+@description("S3 Standard storage, first 50 TB")
+let cost_s3_storage = 0.023 USD / GB / month
+
+# S3 request prices are billed per request, so multiplying by a typed request
+# count produces USD.
+@url("https://aws.amazon.com/s3/pricing/")
+@description("S3 PUT/COPY/POST/LIST, per request ($0.005 per 1,000)")
+let cost_s3_put = 0.005 USD / (1000 request)
+
+@url("https://aws.amazon.com/s3/pricing/")
+@description("S3 GET, per request ($0.0004 per 1,000)")
+let cost_s3_get = 0.0004 USD / (1000 request)
+
+# --- EBS ---
+@url("https://aws.amazon.com/ebs/pricing/")
+@description("EBS gp3 storage (includes 3,000 IOPS and 125 MB/s)")
+let cost_ebs_gp3 = 0.08 USD / GB / month
+
+@url("https://aws.amazon.com/ebs/pricing/")
+@description("EBS gp3 IOPS above the 3,000 baseline, per provisioned IOPS-month")
+let cost_ebs_gp3_iops = 0.005 USD / IOPS / month
+
+# --- DynamoDB on-demand ---
+# Priced per read and write request unit (`dynamodb_rru`, `dynamodb_wru`), which
+# the shared `units` module defines so `throughput::db` caps use them too.
+
+@url("https://aws.amazon.com/dynamodb/pricing/on-demand/")
+@description("DynamoDB on-demand write, per write request unit ($0.625 per million)")
+let cost_dynamodb_write = 0.625 USD / (1_000_000 dynamodb_write_request_unit)
+
+@url("https://aws.amazon.com/dynamodb/pricing/on-demand/")
+@description("DynamoDB on-demand read, per read request unit ($0.125 per million)")
+let cost_dynamodb_read = 0.125 USD / (1_000_000 dynamodb_read_request_unit)
+
+# --- Data transfer ---
+# highlight: egress
+@url("https://aws.amazon.com/s3/pricing/")
+@description("Data transfer out to the internet, first 10 TB/month")
+let cost_egress_internet = 0.09 USD / GB
+
+# highlight: cross-AZ
+@url("https://aws.amazon.com/ec2/pricing/on-demand/")
+@description("Data transfer between AZs in a region, charged in each direction (so $0.02/GB per round trip; often dominates replication cost)")
+let cost_cross_az = 0.01 USD / GB

package/modules/count.nbt

@@ -0,0 +1,18 @@
+# Dimensionless platform caps
+# Counts that are neither time, rate nor bytes: concurrency and item counts.
+# A count of something the shared units cover carries that unit; others are plain.
+# Import with:  use count    then use the count_* values
+# title: Count
+# checked: unverified
+# description: Dimensionless caps: concurrent executions and items per object
+# vendor: aws
+
+# highlight: Lambda concurrency
+@url("https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html")
+@description("Lambda default concurrent executions per region (adjustable to tens of thousands); in requests, so it compares with capacity_concurrency")
+let count_lambda_concurrency = 1_000 request
+
+# highlight: parts per object
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html")
+@description("S3 maximum parts per multipart upload")
+let count_s3_parts_max = 10_000

package/modules/latency/hardware.nbt

@@ -0,0 +1,70 @@
+# Modern hardware latencies (2026)
+# Bulk reads are derived from the throughput modules (size / bandwidth) so the
+# two stay consistent; modules can't import each other, so the bandwidth is
+# repeated inline and named in each description.
+# Import with:  use latency::hardware    then use the latency_hardware_* values
+# title: Latency (hardware)
+# checked: unverified
+# description: Current memory, NVMe, SSD, HDD, fsync, EBS and context-switch latencies (2026)
+
+# --- Memory ---
+# highlight: 1 MB memory
+@url("https://www.cs.virginia.edu/stream/")
+@description("Read 1 MB sequentially from memory on one core (1 MB / throughput_dram_core 20 GB/s)")
+let latency_hardware_read_1mb_memory = 1 MB / (20 GB/s)
+
+@url("https://eli.thegreenplace.net/2018/measuring-context-switching-and-memory-overheads-for-linux-threads/")
+@description("Linux thread context switch, direct cost (measured 1.2-1.5 us pinned, ~2.2 us unpinned)")
+let latency_hardware_context_switch = 1.5 us
+
+# --- NVMe / SSD ---
+# highlight: NVMe 4K QD1
+@url("https://simplyblock.io/glossary/nvme-latency/")
+@description("NVMe random 4 KB read at queue depth 1 (20-100 us; set by NAND read time, not PCIe generation)")
+let latency_hardware_nvme_read_4kb = 60 us
+
+@url("https://semiconductor.samsung.com/ssd/enterprise-ssd/pm1743/")
+@description("Read 1 MB sequentially from a PCIe 5.0 NVMe SSD (1 MB / 14 GB/s)")
+let latency_hardware_read_1mb_nvme = 1 MB / (14 GB/s)
+
+@url("https://en.wikipedia.org/wiki/Solid-state_drive")
+@description("Read 1 MB sequentially from a SATA SSD (1 MB / 550 MB/s)")
+let latency_hardware_read_1mb_sata_ssd = 1 MB / (550 MB/s)
+
+# highlight: fsync SSD
+@url("https://etcd.io/docs/v3.5/op-guide/performance/")
+@description("fsync/fdatasync on SSD (etcd docs: often under 1 ms; enterprise drives with power-loss protection are ~tens of us)")
+let latency_hardware_fsync_ssd = 1 ms
+
+# --- HDD (7,200 RPM) ---
+# highlight: HDD random
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("HDD random 4 KB access, seek + rotation (1 / 75-80 IOPS; half a rotation alone is 4.17 ms)")
+let latency_hardware_hdd_random_access = 13 ms
+
+@url("https://en.wikipedia.org/wiki/Hard_disk_drive")
+@description("Read 1 MB sequentially from HDD (1 MB / 200 MB/s)")
+let latency_hardware_read_1mb_hdd = 1 MB / (200 MB/s)
+
+@url("https://etcd.io/docs/v3.5/op-guide/performance/")
+@description("fsync/fdatasync on a spinning disk (etcd docs: about 10 ms)")
+let latency_hardware_fsync_hdd = 10 ms
+
+# --- Cloud block storage ---
+# highlight: EBS io2
+@url("https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html")
+@description("EBS io2 Block Express I/O, average for 16 KiB (AWS: under 500 us)")
+let latency_hardware_ebs_io2 = 500 us
+
+@url("https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html")
+@description("EBS gp3 I/O (AWS: single-digit millisecond; ~1 ms typical)")
+let latency_hardware_ebs_gp3 = 1 ms
+
+# --- CPU work ---
+@url("https://github.com/facebook/zstd")
+@description("Compress 1 MB with zstd -1 on one core (1 MB / 510 MB/s; ratio ~2.9 on Silesia)")
+let latency_hardware_compress_1mb_zstd = 1 MB / (510 MB/s)
+
+@url("https://github.com/facebook/zstd")
+@description("Decompress 1 MB with zstd on one core (1 MB / 1,550 MB/s)")
+let latency_hardware_decompress_1mb_zstd = 1 MB / (1550 MB/s)

package/modules/latency/llm.nbt

@@ -0,0 +1,98 @@
+# LLM latency numbers (2026)
+# Hosted-model speeds move every few months: re-check per model on Artificial
+# Analysis, which measures output tokens/s and time to first token per API.
+# Decode is memory-bandwidth bound, so latency_llm_decode_token gives a floor
+# from first principles.
+# Import with:  use latency::llm    then use the latency_llm_* values and functions
+# title: Latency (LLM)
+# checked: unverified
+# description: Token generation and first-token latencies, GPU memory bandwidth and compute, and decode/prefill/KV-cache math (2026)
+# vendor: nvidia
+# source: https://artificialanalysis.ai/
+
+# --- Measured magnitudes (order of magnitude; varies ~3x by model and provider) ---
+# highlight: token
+@url("https://artificialanalysis.ai/")
+@description("Generate one token on a small local model on a GPU (~50-150 tokens/s)")
+let latency_llm_local_token = 15 ms
+
+@url("https://artificialanalysis.ai/")
+@description("Generate one token on a hosted frontier model (~30-150 tokens/s)")
+let latency_llm_frontier_token = 20 ms
+
+@url("https://artificialanalysis.ai/")
+@description("Time to first token, small local model, short prompt")
+let latency_llm_local_first_token = 75 ms
+
+@url("https://artificialanalysis.ai/")
+@description("Generate one token on a small local model (CPU only, ~10 tokens/s)")
+let latency_llm_local_cpu_token = 100 ms
+
+@url("https://artificialanalysis.ai/")
+@description("Time to first token on specialized inference hardware")
+let latency_llm_fast_first_token = 250 ms
+
+# highlight: first token
+@url("https://artificialanalysis.ai/")
+@description("Time to first token, frontier model, short prompt, no cache (~0.5-2 s)")
+let latency_llm_frontier_first_token = 1 s
+
+# highlight: reply
+@url("https://artificialanalysis.ai/")
+@description("Short response (~100 output tokens): first token + 100 x token time")
+let latency_llm_frontier_response = 3 s
+
+@url("https://artificialanalysis.ai/")
+@description("Long context prefill (~100K input tokens, no cache; prefill runs ~5k-20k tokens/s)")
+let latency_llm_frontier_prefill = 10 s
+
+# highlight: reasoning
+@url("https://artificialanalysis.ai/")
+@description("Reasoning response (single call with thinking; 5 s to minutes)")
+let latency_llm_frontier_reasoning = 30 s
+
+# --- Tokens ---
+@url("https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them")
+@description("Tokens per English word (~1.3; 1 token is ~0.75 words or ~4 characters; tokenizer-specific)")
+let latency_llm_tokens_per_word = 1.33
+
+# --- GPU memory bandwidth (decode reads every weight once per token) ---
+@url("https://www.nvidia.com/en-us/data-center/h100/")
+@description("NVIDIA H100 SXM HBM bandwidth (3.35 TB/s, 80 GB)")
+let latency_llm_hbm_h100 = 3.35 TB/s
+
+# highlight: H200 HBM
+@url("https://www.nvidia.com/en-us/data-center/h200/")
+@description("NVIDIA H200 HBM bandwidth (4.8 TB/s, 141 GB)")
+let latency_llm_hbm_h200 = 4.8 TB/s
+
+@url("https://www.nvidia.com/en-us/data-center/dgx-b200/")
+@description("NVIDIA B200 HBM bandwidth per GPU (DGX B200: 64 TB/s across 8 GPUs, 1,440 GB total)")
+let latency_llm_hbm_b200 = 8 TB/s
+
+@url("https://www.nvidia.com/en-us/data-center/h100/")
+@description("Decode floor per token at batch size 1: weight bytes / memory bandwidth (70B params x 2 B on one H100: ~42 ms)")
+@example("latency_llm_decode_token(140 GB, 3.35 TB/s)")
+fn latency_llm_decode_token(weights: DigitalInformation, bandwidth: DigitalInformation / Time) -> Time = weights / bandwidth
+
+# --- GPU compute (prefill is compute bound: every prompt token runs every weight) ---
+# highlight: H100 BF16
+@url("https://www.nvidia.com/en-us/data-center/h100/")
+@description("NVIDIA H100 SXM dense BF16 tensor compute (~989 TFLOP/s; the spec sheet's 1,979 is with sparsity). Real kernels reach ~40-60% of it")
+let latency_llm_flop_h100 = 989 TFLOP/s
+
+@url("https://arxiv.org/abs/2001.08361")
+@description("Forward-pass compute for a dense transformer: 2 x params x tokens (Kaplan et al. 2020, C_forward ≈ 2N per token; attention adds a little at long context)")
+@example("latency_llm_forward_flop(70e9, 1_000) -> TFLOP")
+fn latency_llm_forward_flop(params: Scalar, tokens: Scalar) -> FloatingPointOperation = 2 * params * tokens * FLOP
+
+@url("https://arxiv.org/abs/2001.08361")
+@description("Prefill floor: latency_llm_forward_flop(params, tokens) / (compute x utilization), with 0 < utilization ≤ 1 (70B params, 10K tokens, one H100 at 50%: ~2.8 s)")
+@example("latency_llm_prefill(70e9, 10_000, latency_llm_flop_h100, 0.5)")
+fn latency_llm_prefill(params: Scalar, tokens: Scalar, compute: FloatingPointOperation / Time, utilization: Scalar) -> Time =
+  latency_llm_forward_flop(params, tokens) / (compute * utilization)
+
+@url("https://arxiv.org/abs/2309.06180")
+@description("KV cache bytes per token: 2 (K and V) x layers x kv_heads x head_dim x bytes per value")
+@example("latency_llm_kv_bytes_per_token(32, 8, 128, 2 B)")
+fn latency_llm_kv_bytes_per_token(layers: Scalar, kv_heads: Scalar, head_dim: Scalar, bytes: DigitalInformation) -> DigitalInformation = 2 * layers * kv_heads * head_dim * bytes

package/modules/latency/network.nbt

@@ -0,0 +1,74 @@
+# Network latency by geography, plus protocol round trips and clock error
+# Physics sets the floor: light in fiber covers ~200 km per ms.
+# Import with:  use latency::network    then use the latency_network_* values and functions
+# title: Latency (network)
+# checked: unverified
+# description: Fiber speed, same-AZ / cross-AZ / cross-region RTTs, handshakes and clock uncertainty
+# vendor: aws
+# source: https://etcd.io/docs/v3.5/op-guide/performance/
+
+# --- Physics ---
+@url("https://en.wikipedia.org/wiki/Optical_fiber")
+@description("Speed of light in fiber (c / refractive index ~1.47, about 204,000 km/s or ~5 us per km)")
+let latency_network_fiber_speed = 299_792_458 m/s / 1.47
+
+@url("https://en.wikipedia.org/wiki/Optical_fiber")
+@description("Round-trip floor over fiber for a straight-line distance: 2 × distance / latency_network_fiber_speed; real routes are ~1.5-2x longer")
+@example("latency_network_fiber_rtt(100 km)")
+fn latency_network_fiber_rtt(distance: Length) -> Time = 2 * distance / latency_network_fiber_speed
+
+# --- Cloud geography (AWS) ---
+# highlight: same AZ
+@url("https://www.bitsand.cloud/posts/cross-az-latencies")
+@description("RTT within one availability zone (~50-200 us; estimate, AWS publishes no figure, measure with ping)")
+let latency_network_same_az_rtt = 100 us
+
+# highlight: cross AZ
+@url("https://www.bitsand.cloud/posts/cross-az-latencies")
+@description("RTT between AZs in one region (measured 0.39-2.42 ms across 28 regions, most under 1 ms; AWS: single-digit ms)")
+let latency_network_cross_az_rtt = 1 ms
+
+@url("https://www.cloudping.co/")
+@description("RTT US East <-> US West (us-east-1 <-> us-west-2, ~60-70 ms; etcd docs: ~50 ms within the US)")
+let latency_network_us_coast_rtt = 65 ms
+
+# highlight: transatlantic
+@url("https://www.cloudping.co/")
+@description("RTT US East <-> Western Europe (us-east-1 <-> eu-west-1, ~70-80 ms)")
+let latency_network_transatlantic_rtt = 75 ms
+
+@url("https://www.cloudping.co/")
+@description("RTT US West <-> Japan (us-west-2 <-> ap-northeast-1, ~100 ms)")
+let latency_network_transpacific_rtt = 100 ms
+
+@url("https://www.cloudping.co/")
+@description("RTT US East <-> Australia (us-east-1 <-> ap-southeast-2, ~200 ms; etcd docs: up to 400 ms between continents)")
+let latency_network_antipodal_rtt = 200 ms
+
+# --- Last mile ---
+@url("https://hpbn.co/mobile-networks/")
+@description("Mobile (4G LTE) RTT to the first internet hop (~50 ms; 3G is several hundred ms)")
+let latency_network_mobile_rtt = 50 ms
+
+# --- Protocol round trips (multiply by the RTT) ---
+@url("https://www.rfc-editor.org/rfc/rfc9293")
+@description("Round trips for a TCP handshake before the first request byte")
+let latency_network_tcp_handshake_rtts = 1
+
+@url("https://www.rfc-editor.org/rfc/rfc8446")
+@description("Extra round trips for a TLS 1.3 handshake (TLS 1.2 needs 2; 0-RTT resumption needs 0)")
+let latency_network_tls13_handshake_rtts = 1
+
+@url("https://www.rfc-editor.org/rfc/rfc8446")
+@description("Time to the first response on a new TCP + TLS 1.3 connection: (latency_network_tcp_handshake_rtts + latency_network_tls13_handshake_rtts + 1) × rtt")
+@example("latency_network_new_connection(20 ms)")
+fn latency_network_new_connection(rtt: Time) -> Time = (latency_network_tcp_handshake_rtts + latency_network_tls13_handshake_rtts + 1) * rtt
+
+# --- Clocks ---
+@url("https://static.googleusercontent.com/media/research.google.com/en//archive/spanner-osdi2012.pdf")
+@description("Spanner TrueTime uncertainty epsilon (sawtooth 1-7 ms, ~4 ms most of the time); NTP over the internet is similar or worse")
+let latency_network_clock_uncertainty_truetime = 4 ms
+
+@url("https://aws.amazon.com/about-aws/whats-new/2023/11/amazon-time-sync-service-microsecond-accurate-time/")
+@description("Amazon Time Sync with PTP hardware clocks: microsecond-range accuracy on supported EC2 instances")
+let latency_network_clock_uncertainty_ptp = 1 us

package/modules/latency/service.nbt

@@ -0,0 +1,67 @@
+# Per-operation latencies of common infrastructure, as seen by a client in-region
+# These are the numbers you add up in a request's latency budget. Medians unless noted.
+# Import with:  use latency::service    then use the latency_service_* values
+# title: Latency (service)
+# checked: unverified
+# description: Typical request latencies: Redis, SQL, DynamoDB, S3, Kafka, etcd/Raft, Lambda cold start
+# vendor: aws, redis, kafka, etcd
+
+# highlight: Redis GET
+@url("https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/benchmarks/")
+@description("Redis GET/SET p50 in-AZ (~0.1-0.2 ms server-side on loopback plus one same-AZ RTT)")
+let latency_service_redis_get = 0.3 ms
+
+@url("https://www.cybertec-postgresql.com/en/postgres-scaling-advice-for-2021/")
+@description("Relational point query by primary key, cached, in-AZ (~1 ms; estimate: tens of us of work plus RTT and driver overhead)")
+let latency_service_sql_point_query = 1 ms
+
+# highlight: DynamoDB
+@url("https://aws.amazon.com/dynamodb/")
+@description("DynamoDB GetItem/PutItem (AWS: single-digit millisecond at any scale)")
+let latency_service_dynamodb = 5 ms
+
+# highlight: S3 first byte
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html")
+@description("S3 Standard small-object / first-byte latency (AWS: roughly 100-200 ms)")
+let latency_service_s3_first_byte = 150 ms
+
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-performance.html")
+@description("S3 Express One Zone first-byte latency (AWS: consistent single-digit ms, up to 10x faster than Standard)")
+let latency_service_s3_express_first_byte = 5 ms
+
+# highlight: Kafka e2e
+@url("https://engineering.linkedin.com/kafka/benchmarking-apache-kafka-2-million-writes-second-three-cheap-machines")
+@description("Kafka produce-to-consume end to end, p50 (LinkedIn: 2 ms p50, 3 ms p99, 14 ms p99.9)")
+let latency_service_kafka_e2e = 2 ms
+
+@url("https://engineering.linkedin.com/kafka/benchmarking-apache-kafka-2-million-writes-second-three-cheap-machines")
+@description("Kafka produce-to-consume end to end, p99.9 (LinkedIn benchmark)")
+let latency_service_kafka_e2e_p999 = 14 ms
+
+@url("https://developer.confluent.io/learn/kafka-performance/")
+@description("Kafka produce-to-consume end to end, p99 (Confluent benchmark: 5 ms at 200 MB/s, 3 brokers, 1 KB messages, acks=all, min.insync.replicas=2, fsync off)")
+let latency_service_kafka_e2e_p99 = 5 ms
+
+# The produce / publish / commit / fetch split is config- and load-dependent (acks,
+# ISR spread); only the config defaults below are documented bounds. See Confluent's
+# breakdown: https://www.confluent.io/blog/configure-kafka-to-minimize-latency
+@url("https://kafka.apache.org/documentation/#consumerconfigs")
+@description("Kafka consumer fetch long-poll bound: fetch.max.wait.ms default (the broker waits up to this for fetch.min.bytes)")
+let latency_service_kafka_fetch_max_wait = 500 ms
+
+@url("https://kafka.apache.org/documentation/#brokerconfigs")
+@description("Kafka ISR eviction threshold: replica.lag.time.max.ms default (a follower lagging longer is dropped from the in-sync replicas)")
+let latency_service_kafka_replica_lag_max = 30 s
+
+# highlight: consensus write
+@url("https://etcd.io/docs/v3.5/op-guide/performance/")
+@description("Consensus (Raft/etcd) write, light load: one member RTT plus fsync (etcd benchmark: 1.6 ms avg)")
+let latency_service_consensus_write = 1.6 ms
+
+@url("https://etcd.io/docs/v3.5/op-guide/performance/")
+@description("etcd linearizable read, single connection (etcd benchmark: 0.7 ms; serializable 0.3 ms)")
+let latency_service_consensus_read = 0.7 ms
+
+@url("https://aws.amazon.com/blogs/compute/operating-lambda-performance-optimization-part-1/")
+@description("AWS Lambda cold start (AWS: under 100 ms to over 1 s; under 1% of invocations)")
+let latency_service_lambda_cold_start = 500 ms