@unitpad/modules 0.0.0-stage → 0.1.0

package/modules/latency.nbt

@@ -0,0 +1,72 @@
+# Latency numbers every programmer should know
+# Jeff Dean / Peter Norvig — gist.github.com/jboner/2841832 (~2012)
+# Kept verbatim as the classic reference. Several values are 2012 hardware and
+# disagree with the 2026 throughput modules by 4-14x (memory, SSD, disk reads);
+# for current hardware use latency::hardware, for geography use latency::network.
+# Import with:  use latency    then use the latency_* values
+# title: Latency (classic)
+# checked: unverified
+# description: Jeff Dean / Peter Norvig latency numbers, verbatim (~2012)
+# source: https://gist.github.com/jboner/2841832
+
+# highlight: L1
+@url("https://gist.github.com/jboner/2841832")
+@description("L1 cache reference")
+let latency_l1_cache = 0.5 ns
+
+@url("https://gist.github.com/jboner/2841832")
+@description("Branch mispredict")
+let latency_branch_mispredict = 5 ns
+
+@url("https://gist.github.com/jboner/2841832")
+@description("L2 cache reference (14× L1)")
+let latency_l2_cache = 7 ns
+
+@url("https://gist.github.com/jboner/2841832")
+@description("Mutex lock / unlock")
+let latency_mutex_lock = 25 ns
+
+# highlight: memory
+@url("https://gist.github.com/jboner/2841832")
+@description("Main memory reference (20× L2, 200× L1)")
+let latency_main_memory = 100 ns
+
+@url("https://gist.github.com/jboner/2841832")
+@description("Compress 1 KB with Zippy")
+let latency_compress_1kb = 3 us
+
+@url("https://gist.github.com/jboner/2841832")
+@description("Send 1 KB over a 1 Gbps network")
+let latency_send_1kb_1gbps = 10 us
+
+# highlight: SSD 4K
+@url("https://gist.github.com/jboner/2841832")
+@description("Read 4 KB randomly from SSD (~1 GB/s)")
+let latency_read_4kb_ssd = 150 us
+
+@url("https://gist.github.com/jboner/2841832")
+@description("Read 1 MB sequentially from memory")
+let latency_read_1mb_memory = 250 us
+
+# highlight: DC RTT
+@url("https://gist.github.com/jboner/2841832")
+@description("Round trip within the same datacenter")
+let latency_datacenter_roundtrip = 500 us
+
+@url("https://gist.github.com/jboner/2841832")
+@description("Read 1 MB sequentially from SSD (~1 GB/s, 4× memory)")
+let latency_read_1mb_ssd = 1 ms
+
+# highlight: disk seek
+@url("https://gist.github.com/jboner/2841832")
+@description("Disk seek (20× datacenter round trip)")
+let latency_disk_seek = 10 ms
+
+@url("https://gist.github.com/jboner/2841832")
+@description("Read 1 MB sequentially from disk (80× memory, 20× SSD)")
+let latency_read_1mb_disk = 20 ms
+
+# highlight: CA→NL
+@url("https://gist.github.com/jboner/2841832")
+@description("Send a packet California → Netherlands → California")
+let latency_send_packet_ca_nl_ca = 150 ms

package/modules/size.nbt

@@ -0,0 +1,84 @@
+# Data sizes, overheads and ratios, plus platform size caps
+# Import with:  use size    then use the size_* values
+# title: Size
+# checked: unverified
+# description: IDs, packet overheads, media bitrates, compression ratios, replication overheads and platform size caps (max/min)
+# vendor: aws
+
+# --- Identifiers and records ---
+@url("https://www.rfc-editor.org/rfc/rfc9562")
+@description("UUID, binary (128 bits; 36 bytes as a hyphenated string)")
+let size_uuid = 16 B
+
+@url("https://en.wikipedia.org/wiki/64-bit_computing")
+@description("64-bit integer / timestamp / Snowflake-style ID")
+let size_int64 = 8 B
+
+# --- Network framing ---
+@url("https://en.wikipedia.org/wiki/Maximum_transmission_unit")
+@description("Ethernet MTU (1,500 B payload; 9,001 B jumbo frames inside AWS VPCs)")
+let size_mtu = 1500 B
+
+@url("https://www.rfc-editor.org/rfc/rfc9293")
+@description("IPv4 + TCP headers without options (20 + 20 B; ~52 B with common TCP options)")
+let size_tcp_ip_header = 40 B
+
+# --- Media bitrates (YouTube upload recommendations, SDR, 24-30 fps) ---
+# highlight: 1080p
+@url("https://support.google.com/youtube/answer/1722171")
+@description("1080p video bitrate (8 Mbps upload recommendation; delivered streams are often 3-6 Mbps)")
+let size_video_1080p = 8 Mbit/s
+
+@url("https://support.google.com/youtube/answer/1722171")
+@description("4K (2160p) video bitrate (35-45 Mbps upload recommendation)")
+let size_video_4k = 40 Mbit/s
+
+# --- Compression (Silesia corpus, single core) ---
+# highlight: zstd ratio
+@url("https://github.com/facebook/zstd")
+@description("zstd -1 compression ratio (2.9x; 510 MB/s compress, 1,550 MB/s decompress)")
+let size_ratio_zstd = 2.896
+
+@url("https://github.com/facebook/zstd")
+@description("LZ4 compression ratio (2.1x; 675 MB/s compress, 3,850 MB/s decompress)")
+let size_ratio_lz4 = 2.101
+
+@url("https://github.com/facebook/zstd")
+@description("zlib -1 (gzip) compression ratio (2.7x; 105 MB/s compress)")
+let size_ratio_zlib = 2.743
+
+# --- Redundancy overhead (raw bytes stored per logical byte) ---
+# highlight: replication
+@url("https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HDFSErasureCoding.html")
+@description("3x replication: 3 bytes stored per byte (200% overhead)")
+let size_replication_3x = 3
+
+@url("https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HDFSErasureCoding.html")
+@description("Reed-Solomon RS(6,3) erasure coding: 1.5 bytes stored per byte (50% overhead), tolerates 3 losses")
+let size_erasure_rs_6_3 = 1.5
+
+# --- Platform size caps (max / min) ---
+# highlight: S3 object max
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html")
+@description("S3 maximum object size (48.8 TiB, via multipart upload)")
+let size_s3_object_max = 48.8 TiB
+
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html")
+@description("S3 multipart minimum part size (5 MiB; the last part can be smaller; parts max out at 5 GiB)")
+let size_s3_part_min = 5 MiB
+
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Constraints.html")
+@description("DynamoDB maximum item size (400 KiB, binary units, attribute names included)")
+let size_dynamodb_item_max = 400 KiB
+
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Constraints.html")
+@description("DynamoDB maximum partition size (10 GiB; also the item-collection cap when a table has an LSI)")
+let size_dynamodb_partition_max = 10 GiB
+
+@url("https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html")
+@description("SQS maximum message size (1 MiB; larger payloads go to S3 via the extended client)")
+let size_sqs_message_max = 1 MiB
+
+@url("https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html")
+@description("Lambda synchronous invocation payload, request or response (6 MB each)")
+let size_lambda_payload_max = 6 MB

package/modules/throughput/aws.nbt

@@ -0,0 +1,86 @@
+# AWS managed-service rate quotas
+# Per-second throughput ceilings, mostly adjustable. Byte caps live in `size`
+# and dimensionless caps in `count`; this module is only rates.
+# Import with:  use throughput::aws    then use the throughput_aws_* values
+# title: Throughput (AWS)
+# checked: unverified
+# description: AWS rate quotas: EC2 network, VPC packet limits, EBS, Kinesis, SQS, Lambda and API Gateway
+# vendor: aws
+
+# --- EC2 network ---
+# highlight: EC2 flow
+@url("https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html")
+@description("EC2 single TCP/UDP flow bandwidth outside a cluster placement group (5 Gbps; 10 Gbps inside one, 25 Gbps with ENA Express)")
+let throughput_aws_ec2_single_flow = 5 Gbit/s
+
+@url("https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-network-bandwidth.html")
+@description("EC2 bandwidth to the internet for instances under 32 vCPUs (5 Gbps; larger ones get 50% of instance bandwidth)")
+let throughput_aws_ec2_internet_small_instance = 5 Gbit/s
+
+# --- VPC packet limits ---
+# highlight: link-local pps
+@url("https://docs.aws.amazon.com/vpc/latest/userguide/AmazonDNS-concepts.html")
+@description("Packets per second to link-local services per network interface: Route 53 Resolver DNS, IMDS and NTP together (1,024; cannot be increased)")
+let throughput_aws_link_local_packets = 1_024 packet/s
+
+@url("https://docs.aws.amazon.com/vpc/latest/userguide/nat-gateway-basics.html")
+@description("NAT gateway packet rate before it scales (1 million packets/s; 5 Gbps of bandwidth)")
+let throughput_aws_nat_gateway_packets = 1_000_000 packet/s
+
+@url("https://docs.aws.amazon.com/vpc/latest/userguide/nat-gateway-basics.html")
+@description("NAT gateway maximum packet rate after scaling (10 million packets/s; beyond it packets drop, so split across subnets)")
+let throughput_aws_nat_gateway_packets_max = 10_000_000 packet/s
+
+# --- EBS gp3 ---
+# highlight: gp3 baseline
+@url("https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html")
+@description("EBS gp3 baseline IOPS included in the price")
+let throughput_aws_ebs_gp3_baseline_iops = 3_000 IOPS
+
+@url("https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html")
+@description("EBS gp3 baseline throughput included in the price (125 MiB/s)")
+let throughput_aws_ebs_gp3_baseline = 125 MiB/s
+
+@url("https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html")
+@description("EBS gp3 maximum provisioned IOPS per volume (80,000; 500 IOPS per GiB)")
+let throughput_aws_ebs_gp3_max_iops = 80_000 IOPS
+
+@url("https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html")
+@description("EBS gp3 maximum provisioned throughput per volume (2,000 MiB/s)")
+let throughput_aws_ebs_gp3_max = 2_000 MiB/s
+
+# --- Kinesis Data Streams (provisioned, per shard) ---
+# highlight: Kinesis shard
+@url("https://docs.aws.amazon.com/streams/latest/dev/service-sizes-and-limits.html")
+@description("Kinesis shard write limit (1 MB/s or 1,000 records/s, whichever hits first)")
+let throughput_aws_kinesis_shard_write = 1 MB/s
+
+@url("https://docs.aws.amazon.com/streams/latest/dev/service-sizes-and-limits.html")
+@description("Kinesis shard write record limit")
+let throughput_aws_kinesis_shard_records = 1_000 record/s
+
+@url("https://docs.aws.amazon.com/streams/latest/dev/service-sizes-and-limits.html")
+@description("Kinesis shard read limit, shared by consumers (2 MB/s; enhanced fan-out gives each consumer its own)")
+let throughput_aws_kinesis_shard_read = 2 MB/s
+
+# --- SQS ---
+# highlight: SQS FIFO
+@url("https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html")
+@description("SQS FIFO API calls per second per action, without high-throughput mode (3,000 messages/s with batches of 10)")
+let throughput_aws_sqs_fifo_requests = 300 request/s
+
+@url("https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/quotas-messages.html")
+@description("SQS FIFO high-throughput mode API calls per second (us-east-1; 700k messages/s batched; standard queues are nearly unlimited)")
+let throughput_aws_sqs_fifo_high_requests = 70_000 request/s
+
+# --- Lambda ---
+# highlight: Lambda scale
+@url("https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html")
+@description("Lambda concurrency scaling rate per function (1,000 execution environments every 10 s, i.e. 100/s); in requests in flight, like count_lambda_concurrency")
+let throughput_aws_lambda_scale_requests = 100 request/s
+
+# --- API Gateway ---
+# highlight: API GW
+@url("https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html")
+@description("API Gateway throttle per account per region (10,000 RPS, burst 5,000; adjustable)")
+let throughput_aws_apigw_requests = 10_000 request/s

package/modules/throughput/db.nbt

@@ -0,0 +1,97 @@
+# Per-database throughput, order of magnitude
+# Figures from each engine's own benchmark tooling. They swing by ~10x with
+# hardware, payload, durability (fsync) and cache hit rate, so treat them as
+# magnitudes, not specs. Some are in documents/rows per second (Elasticsearch,
+# ClickHouse), not operations; DynamoDB values are per-partition/per-table caps.
+# Byte caps and counts live in `size` and `count`.
+# Import with:  use throughput::db    then use the throughput_db_* values
+# title: Throughput (DB)
+# checked: unverified
+# description: Order-of-magnitude per-engine rates and DynamoDB caps: Redis, Cassandra, MongoDB, SQL, DynamoDB, Elasticsearch, ClickHouse
+# vendor: aws, redis, cassandra, mongodb, mysql, postgresql, elasticsearch, clickhouse
+
+# --- Redis (in-memory; command execution is single-threaded) ---
+# highlight: Redis
+@url("https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/benchmarks/")
+@description("Redis GET/SET on one instance, no pipelining (~10^5 ops/s)")
+let throughput_db_redis_ops = 150_000 operation/s
+
+@url("https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/benchmarks/")
+@description("Redis GET/SET with pipelining, network-bound (>10^6 ops/s)")
+let throughput_db_redis_pipelined_ops = 1_000_000 operation/s
+
+# --- Cassandra (wide-column, LSM) ---
+# highlight: Cassandra write
+@url("https://axonops.com/docs/data-platforms/cassandra/operations/performance/benchmarking")
+@description("Cassandra replica writes per node (~20k-100k/s); client-visible writes per node are this / replication factor")
+let throughput_db_cassandra_write_ops = 50_000 operation/s
+
+@url("https://netflixtechblog.com/benchmarking-cassandra-scalability-on-aws-over-a-million-writes-per-second-39f45f066c9e")
+@description("Cassandra client writes per node: throughput_db_cassandra_write_ops / replication factor (RF=3; Netflix 2011 on m1.xlarge: 1.1M client writes/s on 288 nodes, ~3.8k/node; modern nodes ~5k-20k)")
+let throughput_db_cassandra_client_write_ops = throughput_db_cassandra_write_ops / 3
+
+@url("https://axonops.com/docs/data-platforms/cassandra/operations/performance/benchmarking")
+@description("Cassandra reads per node (~10k-50k ops/s)")
+let throughput_db_cassandra_read_ops = 25_000 operation/s
+
+# --- MongoDB (document) ---
+# highlight: MongoDB
+@url("https://www.mongodb.com/company/blog/through-the-looking-glass-analyzing-the-interplay-between-memory-disk-and-read-performance")
+@description("MongoDB YCSB ops/s per node (~10^4-10^5; cache-resident)")
+let throughput_db_mongodb_ops = 50_000 operation/s
+
+# --- PostgreSQL / MySQL (relational OLTP) ---
+# highlight: SQL write
+@url("https://docs.aws.amazon.com/whitepapers/latest/optimizing-mysql-on-ec2-using-amazon-ebs/mysql-benchmark-observations-and-considerations.html")
+@description("Relational OLTP write transactions per node, conservative (~10^3-10^4 txn/s; small instance, multi-statement txns, fsync per commit)")
+let throughput_db_sql_write_ops = 5_000 operation/s
+
+@url("https://docs.aws.amazon.com/whitepapers/latest/optimizing-mysql-on-ec2-using-amazon-ebs/mysql-benchmark-observations-and-considerations.html")
+@description("Relational OLTP reads per node, conservative (~10^4-10^5 queries/s; see _high for a big tuned box)")
+let throughput_db_sql_read_ops = 20_000 operation/s
+
+@url("https://www.cybertec-postgresql.com/en/postgres-scaling-advice-for-2021/")
+@description("PostgreSQL point reads on a large tuned server (~25k-32k TPS per core; ~1M on a high-end box, in-memory)")
+let throughput_db_sql_read_ops_high = 500_000 operation/s
+
+@url("https://www.cybertec-postgresql.com/en/postgres-scaling-advice-for-2021/")
+@description("PostgreSQL write transactions on NVMe, tuned (pgbench TPC-B-like: ~45k TPS on a 6-core workstation)")
+let throughput_db_sql_write_ops_high = 45_000 operation/s
+
+@url("https://www.scylladb.com/2023/10/24/sql-vs-nosql-at-scale-lee-atchinson-dor-laors-take")
+@description("Rule of thumb: mixed read/write load a relational primary handles before you reach for replicas or sharding (~10k-50k ops/s)")
+let throughput_db_sql_node_ceiling_ops = 50_000 operation/s
+
+# --- DynamoDB (managed; caps, per partition and per table) ---
+# highlight: DynamoDB
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ServiceQuotas.html")
+@description("DynamoDB writes per partition: 1,000 WCU/s (1 KB items)")
+let throughput_db_dynamodb_wcu = 1_000 dynamodb_wru/s
+
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ServiceQuotas.html")
+@description("DynamoDB strongly consistent reads per partition: 3,000 RCU/s (4 KB items; eventually consistent reads count half)")
+let throughput_db_dynamodb_rcu = 3_000 dynamodb_rru/s
+
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ServiceQuotas.html")
+@description("DynamoDB default per-table write throughput: 40,000 WCU/s (on-demand and provisioned; adjustable)")
+let throughput_db_dynamodb_table_wcu = 40_000 dynamodb_wru/s
+
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ServiceQuotas.html")
+@description("DynamoDB default per-table read throughput: 40,000 RCU/s (on-demand and provisioned; adjustable)")
+let throughput_db_dynamodb_table_rcu = 40_000 dynamodb_rru/s
+
+# --- Elasticsearch / OpenSearch (search index; values are documents/s) ---
+# highlight: Elasticsearch
+@url("https://www.elastic.co/blog/benchmarking-and-sizing-your-elasticsearch-cluster-for-logs-and-metrics")
+@description("Elasticsearch indexing per shard/node (~20k docs/s, batched bulk)")
+let throughput_db_elasticsearch_index_records = 20_000 record/s
+
+# --- ClickHouse (columnar OLAP; values are rows/s) ---
+# highlight: ClickHouse
+@url("https://clickhouse.com/docs/concepts/features/operations/insert/inserting-data")
+@description("ClickHouse batched inserts (~10^6 rows/s on one server, order of magnitude)")
+let throughput_db_clickhouse_insert_rows = 1_000_000 row/s
+
+@url("https://clickhouse.com/docs/best-practices/selecting-an-insert-strategy")
+@description("ClickHouse recommended insert query rate (~1 insert/s, each 10k-100k rows; use async inserts for many small writers)")
+let throughput_db_clickhouse_insert_requests = 1 request/s

package/modules/throughput/s3.nbt

@@ -0,0 +1,44 @@
+# Amazon S3 request-rate and throughput numbers
+# Sources: AWS S3 performance documentation. Object/multipart caps live in `size` and `count`.
+# Import with:  use throughput::s3    then use the throughput_s3_* values
+# title: Throughput (S3)
+# checked: unverified
+# description: Amazon S3 request rates, connections and throughput
+# vendor: aws
+# source: https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html
+
+# highlight: GET/s per prefix
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html")
+@description("S3 Standard: GET/HEAD requests per second per prefix (at least)")
+let throughput_s3_get_requests_per_prefix = 5_500 request/s
+
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html")
+@description("S3 Standard: PUT/COPY/POST/DELETE per second per prefix (at least)")
+let throughput_s3_put_requests_per_prefix = 3_500 request/s
+
+# highlight: per connection
+@url("https://d1.awsstatic.com/whitepapers/AmazonS3BestPractices.pdf")
+@description("S3 Standard: one concurrent request per ~85-90 MB/s of desired throughput (legacy whitepaper; no longer in current docs)")
+let throughput_s3_per_connection = 90 MB/s
+
+@url("https://d1.awsstatic.com/whitepapers/AmazonS3BestPractices.pdf")
+@description("S3 Standard: ~15 concurrent connections to saturate a 10 Gb/s NIC (legacy whitepaper)")
+let throughput_s3_connections_10gbe = 15
+
+# highlight: Express GET/s
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-performance.html")
+@description("S3 Express One Zone: default GET TPS per directory bucket")
+let throughput_s3_express_get_requests_default = 200_000 request/s
+
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-optimizing-performance-design-patterns.html")
+@description("S3 Express One Zone: max GET TPS per directory bucket (up to)")
+let throughput_s3_express_get_requests_max = 2_000_000 request/s
+
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-performance.html")
+@description("S3 Express One Zone: default PUT TPS per directory bucket")
+let throughput_s3_express_put_requests_default = 100_000 request/s
+
+@url("https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-optimizing-performance-design-patterns.html")
+@description("S3 Express One Zone: max PUT TPS per directory bucket (up to)")
+let throughput_s3_express_put_requests_max = 200_000 request/s
+

package/modules/throughput/service.nbt

@@ -0,0 +1,40 @@
+# Per-node service throughput calibration
+# Order-of-magnitude rates for one machine: service, cache, database, queue.
+# The database figures mirror throughput::db (modules can't import each other).
+# Import with:  use throughput::service    then use the throughput_service_* values
+# title: Throughput (Service)
+# checked: unverified
+# description: Per-node request rates for services, caches, databases and queues
+# vendor: aws, redis, kafka, mysql
+
+# highlight: service
+@url("https://www.techempower.com/benchmarks/")
+@description("Rule-of-thumb capacity per service node for business logic plus one database round trip (~10^3-10^4 requests/s); workload and hardware vary. Framework-only benchmarks reach 10^5-10^6 requests/s")
+let throughput_service_requests = 10_000 request/s
+
+# highlight: cache
+@url("https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/benchmarks/")
+@description("Rule-of-thumb capacity per in-memory cache node (~10^5 operations/s); one Redis process without pipelining is ~150k, while multi-threaded memcached can go higher")
+let throughput_service_cache_ops = 100_000 operation/s
+
+@url("https://docs.aws.amazon.com/whitepapers/latest/optimizing-mysql-on-ec2-using-amazon-ebs/mysql-benchmark-observations-and-considerations.html")
+@description("Relational node reads, well-indexed, conservative (~10^4-10^5 QPS; same as throughput_db_sql_read_ops)")
+let throughput_service_db_read_ops = 20_000 operation/s
+
+# highlight: DB writes
+@url("https://docs.aws.amazon.com/whitepapers/latest/optimizing-mysql-on-ec2-using-amazon-ebs/mysql-benchmark-observations-and-considerations.html")
+@description("Relational node writes, conservative (~10^3-10^4/s; same as throughput_db_sql_write_ops)")
+let throughput_service_db_write_ops = 5_000 operation/s
+
+# highlight: Kafka
+@url("https://engineering.linkedin.com/kafka/benchmarking-apache-kafka-2-million-writes-second-three-cheap-machines")
+@description("Kafka broker, small messages (~10^5-10^6/s; LinkedIn: 821k 100-byte records/s from one producer)")
+let throughput_service_kafka_msgs = 500_000 message/s
+
+@url("https://www.confluent.io/blog/how-choose-number-topics-partitions-kafka-cluster/")
+@description("Kafka produce throughput per partition (Confluent: 10s of MB/s on one partition; plan ~10 MB/s)")
+let throughput_service_kafka_partition = 10 MB/s
+
+@url("https://www.confluent.io/blog/how-choose-number-topics-partitions-kafka-cluster/")
+@description("Kafka partitions per broker before availability suffers (Confluent: 2,000-4,000; KRaft clusters raise this)")
+let throughput_service_kafka_partitions_per_broker = 4_000

package/modules/throughput/storage.nbt

@@ -0,0 +1,117 @@
+# Storage throughput and IOPS
+# Per-device sequential and random (4 KB) performance, plus link rates.
+# Import with:  use throughput::storage    then use the throughput_storage_* values
+# title: Throughput (Storage)
+# checked: unverified
+# description: Sequential and random (4 KB) throughput and IOPS for HDD, SSD, NVMe and tape
+# source: https://en.wikipedia.org/wiki/IOPS
+
+# --- HDD (7,200 RPM) ---
+# highlight: HDD seq
+@url("https://en.wikipedia.org/wiki/Hard_disk_drive")
+@description("HDD sequential read (~100-200 MB/s)")
+let throughput_storage_hdd_seq_read = 200 MB/s
+
+@url("https://en.wikipedia.org/wiki/Hard_disk_drive")
+@description("HDD sequential write (~100-200 MB/s)")
+let throughput_storage_hdd_seq_write = 200 MB/s
+
+# highlight: HDD 4K read
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("HDD random 4 KB read IOPS (Wikipedia: 73-79 for 7,200 RPM SATA; 10k RPM is ~140-150)")
+let throughput_storage_hdd_rand_read_iops = 80 IOPS
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("HDD random 4 KB write IOPS (7,200 RPM; same mechanics as reads)")
+let throughput_storage_hdd_rand_write_iops = 80 IOPS
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("HDD random 4 KB read throughput (throughput_storage_hdd_rand_read_iops × 4 KB)")
+let throughput_storage_hdd_rand_read = throughput_storage_hdd_rand_read_iops * 4 KiB/io -> MiB/s
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("HDD random 4 KB write throughput (throughput_storage_hdd_rand_write_iops × 4 KB)")
+let throughput_storage_hdd_rand_write = throughput_storage_hdd_rand_write_iops * 4 KiB/io -> MiB/s
+
+# --- SATA SSD ---
+# highlight: SATA seq
+@url("https://en.wikipedia.org/wiki/Solid-state_drive")
+@description("SATA SSD sequential read (~550 MB/s)")
+let throughput_storage_sata_ssd_seq_read = 550 MB/s
+
+@url("https://en.wikipedia.org/wiki/Solid-state_drive")
+@description("SATA SSD sequential write (~520 MB/s)")
+let throughput_storage_sata_ssd_seq_write = 520 MB/s
+
+# highlight: SATA 4K read
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("SATA SSD random 4 KB read IOPS (~100k)")
+let throughput_storage_sata_ssd_rand_read_iops = 100_000 IOPS
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("SATA SSD random 4 KB write IOPS (~90k)")
+let throughput_storage_sata_ssd_rand_write_iops = 90_000 IOPS
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("SATA SSD random 4 KB read throughput (throughput_storage_sata_ssd_rand_read_iops × 4 KB)")
+let throughput_storage_sata_ssd_rand_read = throughput_storage_sata_ssd_rand_read_iops * 4 KiB/io -> MiB/s
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("SATA SSD random 4 KB write throughput (throughput_storage_sata_ssd_rand_write_iops × 4 KB)")
+let throughput_storage_sata_ssd_rand_write = throughput_storage_sata_ssd_rand_write_iops * 4 KiB/io -> MiB/s
+
+# --- NVMe SSD (PCIe 5.0 x4) ---
+# highlight: NVMe seq
+@url("https://semiconductor.samsung.com/ssd/enterprise-ssd/pm1743/")
+@description("NVMe SSD sequential read (~14 GB/s, PCIe 5.0 x4; Samsung PM1743: up to 14,000 MB/s)")
+let throughput_storage_nvme_seq_read = 14 GB/s
+
+@url("https://en.wikipedia.org/wiki/Solid-state_drive")
+@description("NVMe SSD sequential write (~12 GB/s on fast consumer Gen5; many enterprise Gen5 drives list ~6-10 GB/s)")
+let throughput_storage_nvme_seq_write = 12 GB/s
+
+# highlight: NVMe 4K read
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("NVMe SSD random 4 KB read IOPS at high queue depth (~1M Gen4, 2M+ Gen5 enterprise; see _qd1 for a single thread)")
+let throughput_storage_nvme_rand_read_iops = 1_000_000 IOPS
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("NVMe SSD random 4 KB write IOPS, sustained (~200k-400k steady state; ~1M only in burst / fresh-out-of-box)")
+let throughput_storage_nvme_rand_write_iops = 300_000 IOPS
+
+# highlight: NVMe QD1
+@url("https://simplyblock.io/glossary/nvme-latency/")
+@description("NVMe random 4 KB read IOPS at queue depth 1 (~1 / 60 us latency, 10k-50k; what one synchronous thread sees)")
+let throughput_storage_nvme_rand_read_qd1_iops = 16_000 IOPS
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("NVMe SSD random 4 KB read throughput (throughput_storage_nvme_rand_read_iops × 4 KB)")
+let throughput_storage_nvme_rand_read = throughput_storage_nvme_rand_read_iops * 4 KiB/io -> MiB/s
+
+@url("https://en.wikipedia.org/wiki/IOPS")
+@description("NVMe SSD random 4 KB write throughput (throughput_storage_nvme_rand_write_iops × 4 KB)")
+let throughput_storage_nvme_rand_write = throughput_storage_nvme_rand_write_iops * 4 KiB/io -> MiB/s
+
+# --- Tape ---
+# highlight: tape
+@url("https://en.wikipedia.org/wiki/Linear_Tape-Open")
+@description("LTO-9 tape sequential (~400 MB/s)")
+let throughput_storage_tape_seq = 400 MB/s
+
+# --- Link rates ---
+# highlight: SATA III
+@url("https://en.wikipedia.org/wiki/Serial_ATA")
+@description("SATA III link rate (~600 MB/s, 6 Gbit/s)")
+let throughput_storage_interface_sata3 = 600 MB/s
+
+@url("https://en.wikipedia.org/wiki/Serial_Attached_SCSI")
+@description("SAS-3 link rate (~1.2 GB/s, 12 Gbit/s)")
+let throughput_storage_interface_sas3 = 1.2 GB/s
+
+@url("https://en.wikipedia.org/wiki/PCI_Express")
+@description("PCIe 4.0 x4 link (a Gen4 NVMe SSD, ~7.88 GB/s)")
+let throughput_storage_interface_pcie4_x4 = 7.88 GB/s
+
+@url("https://en.wikipedia.org/wiki/PCI_Express")
+@description("PCIe 5.0 x4 link (a Gen5 NVMe SSD, ~15.75 GB/s)")
+let throughput_storage_interface_pcie5_x4 = 15.75 GB/s

package/modules/throughput.nbt

@@ -0,0 +1,74 @@
+# Throughput numbers every programmer should know
+# Memory, interconnect and network bandwidth.
+# Import with:  use throughput    then use the throughput_* values
+# title: Throughput
+# checked: unverified
+# description: Cache, DRAM, PCIe and network bandwidth
+# source: https://en.wikipedia.org/wiki/List_of_interface_bit_rates
+
+# --- CPU caches (per core, measured; varies ~2x by microarchitecture) ---
+@url("https://en.wikipedia.org/wiki/CPU_cache")
+@description("L1 cache bandwidth per core (~1 TB/s; estimate: 2 x 64 B loads/cycle at ~5 GHz is 640 GB/s, more with AVX-512)")
+let throughput_l1 = 1 TB/s
+
+@url("https://en.wikipedia.org/wiki/CPU_cache")
+@description("L2 cache bandwidth per core (~200-500 GB/s; estimate: 64 B/cycle at ~5 GHz)")
+let throughput_l2 = 300 GB/s
+
+@url("https://en.wikipedia.org/wiki/CPU_cache")
+@description("L3 cache bandwidth seen by one core (~100-200 GB/s; whole-chip aggregate is much higher)")
+let throughput_l3 = 150 GB/s
+
+# --- DRAM: per channel, per core, per socket differ by ~10x ---
+# highlight: DRAM/socket
+@url("https://www.amd.com/content/dam/amd/en/documents/epyc-business-docs/datasheets/amd-epyc-9005-series-processor-datasheet.pdf")
+@description("DRAM bandwidth per server socket, peak (12 x DDR5-6000 channels = 576 GB/s on AMD EPYC 9005)")
+let throughput_dram_socket = 576 GB/s
+
+@url("https://en.wikipedia.org/wiki/DDR5_SDRAM")
+@description("DRAM bandwidth per DDR5-4800 channel/DIMM (4.8 GT/s x 8 B = 38.4 GB/s; DDR5-6400 is 51.2 GB/s)")
+let throughput_dram_channel = 38.4 GB/s
+
+@url("https://www.cs.virginia.edu/stream/")
+@description("DRAM bandwidth one core can pull (~10-30 GB/s; estimate, measure with STREAM)")
+let throughput_dram_core = 20 GB/s
+
+@url("https://en.wikipedia.org/wiki/DDR5_SDRAM")
+@description("Alias of throughput_dram_channel; prefer the explicit _core / _channel / _socket values")
+let throughput_dram = throughput_dram_channel
+
+# --- PCIe (x16, per direction) ---
+@url("https://en.wikipedia.org/wiki/PCI_Express")
+@description("PCIe 3.0 x16 interconnect (15.75 GB/s per direction)")
+let throughput_pcie3_x16 = 15.75 GB/s
+
+@url("https://en.wikipedia.org/wiki/PCI_Express")
+@description("PCIe 4.0 x16 interconnect (31.5 GB/s per direction)")
+let throughput_pcie4_x16 = 31.5 GB/s
+
+# highlight: PCIe 5
+@url("https://en.wikipedia.org/wiki/PCI_Express")
+@description("PCIe 5.0 x16 interconnect (63 GB/s per direction)")
+let throughput_pcie5_x16 = 63 GB/s
+
+# --- Ethernet line rates (TCP goodput is ~90-95% of these) ---
+@url("https://en.wikipedia.org/wiki/List_of_interface_bit_rates")
+@description("1 Gigabit Ethernet (125 MB/s)")
+let throughput_lan_1gbe = 125 MB/s
+
+@url("https://en.wikipedia.org/wiki/List_of_interface_bit_rates")
+@description("10 Gigabit Ethernet")
+let throughput_lan_10gbe = 1.25 GB/s
+
+@url("https://en.wikipedia.org/wiki/List_of_interface_bit_rates")
+@description("25 Gigabit Ethernet (a common cloud server NIC)")
+let throughput_lan_25gbe = 3.125 GB/s
+
+# highlight: 100 GbE
+@url("https://en.wikipedia.org/wiki/List_of_interface_bit_rates")
+@description("100 Gigabit Ethernet")
+let throughput_lan_100gbe = 12.5 GB/s
+
+@url("https://en.wikipedia.org/wiki/List_of_interface_bit_rates")
+@description("400 Gigabit Ethernet (datacenter spine / AI cluster links)")
+let throughput_lan_400gbe = 50 GB/s

package/modules/units/systems/aws.nbt

@@ -0,0 +1,21 @@
+# Shared units for AWS metering. In every session (via `units::systems`), not importable.
+# title: Shared units (AWS)
+# description: DynamoDB read and write request units
+
+# DynamoDB read and write request units: what AWS meters, prices and caps, not raw
+# API calls (item size and consistency can make one call consume several). Shared
+# so `cost` prices and `throughput::db` caps multiply. A capacity unit (RCU/WCU)
+# is one request unit per second.
+dimension DynamodbReadRequestUnit
+
+@name("DynamoDB read request unit")
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/read-write-operations.html")
+@aliases(dynamodb_rru)
+unit dynamodb_read_request_unit: DynamodbReadRequestUnit
+
+dimension DynamodbWriteRequestUnit
+
+@name("DynamoDB write request unit")
+@url("https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/read-write-operations.html")
+@aliases(dynamodb_wru)
+unit dynamodb_write_request_unit: DynamodbWriteRequestUnit