docs(reference): add the benchmarks page

[coderdan]

Adds /docs/reference/benchmarks — the performance numbers with methodology, per the IA. Closes the gap where these figures existed only in the external benches repo.

Source

Numbers distilled from the public cipherstash/benches EQL v3 suite (PR: eql-v3-benches), specifically the report/BENCHMARK_REPORT.md "vs plaintext PostgreSQL" table and report/V3_COMPARISON.md. Every figure is cross-checked against the plaintext baseline; nothing is restated without a source.

What the page covers

• Query latency @ 1M rows with the ratio to plaintext Postgres on the same shape with an equivalent index: exact match 0.12 ms (1.3x), OPE range 0.12 ms (1.2x), ORE range 0.52 ms (5.2x), JSON @> 0.40 ms (1.4x), GROUP BY 83 ms (2.2x).
• Scaling — the fast-path ratios stay flat 10k → 10M.
• OPE-vs-ORE range/order tradeoff (incl. index build 1 s vs 44 s), free-text bloom match (100-400x vs seq scan), ingest throughput, methodology, caveats, and repro steps.
• Cross-links to Searchable encryption and EQL indexes.

Verification

• bun run build green (694 pages); validate-links reports no broken links.
• Environment noted on the page: Apple M1 Max, PostgreSQL 17, EQL v3.

Notes / scope

• ZeroKMS-vs-AWS-KMS throughput (the listing's "14x" claim) is not included: it isn't in the benches suite I was pointed at, and there's no /concepts/compare/aws-kms page yet to cross-link. Left it out rather than restate an unsourced number — happy to add a "key-management throughput" section once that benchmark/page lands.
• Charts not embedded — the benches report has ~60 PNGs; I linked to it rather than copy binary assets. Can embed a couple of hero charts as a follow-up if you want them inline.
• One honest caveat carried onto the page: the JSON contains 10M outlier is a documented plan artifact, flagged as such.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Error		Jul 14, 2026 6:24am

[freshtonic]

Got the docs running locally and checked this branch out.

The breakdown of latency versus scaling is really well thought out - and the link to the raw benchmarks will satisfy those craving more detail.

[coderdan]

Fixed the OPE/ORE variant labels, which were inverted relative to shipped EQL 3.0.0 (commit a29c286).

The page attributed OPE (fast, ~1 s index build) to _ord_ope only, and called _ord the ORE variant. Shipped, it is the other way around:

• _ord is the OPE default — op term, eql_v3.ord_term, indexes under the built-in btree opclass, ~0.12 ms
• _ord_ore is the ORE-pinned variant — ob term, eql_v3.ord_term_ore, needs a superuser opclass, ~0.52 ms

Verified against the EQL 3.0.0 install SQL (CREATE DOMAIN public.eql_v3_integer_ord … VALUE ? 'op'). Only the labels were wrong; every latency and build-time figure was already correct and is unchanged.

[freshtonic]

@coderdan nice!