Add a repeatable performance and scale benchmark suite

[lan17]

Priority

P2 — Medium — measurement infrastructure for performance-sensitive work, not a correctness blocker by itself.

Current state

DialCache now has a checked-in benchmark command:

pnpm benchmark:request-local

#69 expanded the harness from three to five semantic scenarios:

• sequential request-local hits
• sequential process-local hits
• enabled bounded fallbacks
• request-local coalescing
• process-scoped coalescing with state assertions

Current evidence:

• DialCache/package.json

  Lines 77 to 86 in 34a45fa

  	],
  	"scripts": {
  	"benchmark:request-local": "pnpm build && node scripts/benchmark-request-local.mjs",
  	"build": "tsup src/index.ts src/datadog.ts src/node-redis.ts src/prometheus.ts src/redis-protocol.ts src/valkey-glide.ts --format esm,cjs --dts --clean",
  	"check": "pnpm typecheck && pnpm test && pnpm build && pnpm test:package",
  	"typecheck": "tsc --noEmit",
  	"test": "vitest run --coverage",
  	"test:integration": "vitest run --config vitest.integration.config.ts",
  	"test:package": "node scripts/test-package.mjs",
  	"test:watch": "vitest"

• https://github.com/lan17/DialCache/blob/34a45facfc4cb11ca7c08d5506e74b3dbcef4dd2/scripts/benchmark-request-local.mjs
• https://github.com/lan17/DialCache/blob/34a45facfc4cb11ca7c08d5506e74b3dbcef4dd2/README.md#cache-path-benchmark

The existing timings remain informational. Output is only a console table; it captures no environment metadata, latency distribution, Redis/payload matrix, metrics comparison, heap/allocation data, or regression budget. CI does not run even a semantic smoke version.

Phase 1 — comparable harness

• Emit machine-readable JSON alongside readable output.
• Record Node, platform, architecture, dependency/Redis versions, iteration counts, and relevant configuration.
• Cover representative local hit/miss paths with metrics disabled and enabled.
• Cover tracked and untracked Redis read/write paths across a small payload matrix.
• Add a small deterministic semantic CI smoke run without noisy timing gates.

Phase 2 — evidence for a selected design

Add focused scenarios only when a concrete issue needs them. Cluster skew, heap profiling, failure injection, compression, and large batch matrices belong here rather than in a universal first harness.

Dependencies

Use this harness before selecting performance-sensitive behavior in #40, #42, #43, or #60. Keep lower-copy Redis protocol research in #37.

Acceptance criteria for Phase 1

• Reproducible JSON and human-readable output with captured environment/configuration.
• Local hit/miss and tracked/untracked Redis coverage.
• Metrics-on/off comparison and representative payload sizes.
• Deterministic semantic assertions.
• Lightweight CI smoke without unstable performance thresholds.
• Baselines recorded before any regression budget is selected.