[Code0987]

Summary

Official Python and Node clients for the existing Cache gRPC port. No server, proto, or data-path change.

• clients/python (supercache, sync, Python 3.11+) and clients/node (@code0987/supercache, Promises, Node 22+). Not published.
• clients/conformance is the Go engine plus Cache gRPC server the language tests dial.
• CI job clients-up-to-date regenerates stubs from api/proto/cache.proto and fails on diff, then scripts/check-client-surface.py fails unless every Cache RPC has a Python method, a Node method, and a mention in docs/API.md.

Design: docs/design/2026-10-08-polyglot-clients.md

Product docs: README.md, docs/API.md, PLAN.md §3, both client READMEs. No OpenAPI or sc help change. No public RPC was added.

Release

• This PR should not cut a release
• Release via commit front matter (--- / release: vX.Y.Z / ---)
• Release via PR title containing [release: vX.Y.Z]
• Target version: v..__

Test plan

• go test ./...
• pytest clients/python/tests
• npm test in clients/node
• python3 scripts/check-client-surface.py
• CI clients-up-to-date and clients

Notes for reviewers

Bench risk: none on the hot path. Get-hit allocs should stay flat. Local bench was not re-run because pkg/engine and pkg/store are unchanged.

Do not dial the peer port from these clients.

[github-actions]

SuperCache bench vs main

Both sides ran once on this same GitHub runner (main, then this PR). Not a merge gate.

Baseline: 745e087 (2026-10-08T11:00:42Z) → this run: 745e087 (2026-10-08T10:59:58Z)

scbench smoke

cell	ops/s (main → PR)	Δ ops/s	p50	p99
get/hit n=1 c=1 uniform	17938 → 18333	+2.2%	57µs → 55µs	105µs → 91µs
get/hit n=1 c=10 uniform	62580 → 62324	-0.4%	144µs → 146µs	436µs → 421µs
get/hit n=3 c=10 uniform	72446 → 70725	-2.4%	123µs → 125µs	451µs → 454µs
miss/miss-cacheonly n=1 c=1 uniform	17480 → 17040	-2.5%	58µs → 59µs	106µs → 110µs
miss/miss-cacheonly n=1 c=10 uniform	62928 → 62983	+0.1%	144µs → 143µs	447µs → 456µs
set/put n=1 c=1 uniform	16841 → 17005	+1.0%	59µs → 59µs	99µs → 101µs
set/put n=1 c=10 uniform	63019 → 61483	-2.4%	144µs → 147µs	430µs → 448µs

Δ ops/s: green-ish is higher throughput. Latency: lower is better.

go test -bench (ns/op)

benchmark	ns/op (main → PR)	Δ	allocs/op
BenchmarkEngineDelete	506 → 505	-0.1%	6 → 6
BenchmarkEngineGetHit	675 → 698	+3.4%	15 → 15
BenchmarkEngineGetHitParallel	557 → 556	-0.2%	15 → 15
BenchmarkEngineGetMissCacheOnly	489 → 519	+6.3%	14 → 14
BenchmarkEngineGetMissCacheOnlyParallel	405 → 399	-1.6%	14 → 14
BenchmarkEngineGetMissLoadThrough	969 → 960	-0.9%	24 → 24
BenchmarkEngineGetMissLoadThroughParallel	1101 → 1100	-0.1%	23 → 23
BenchmarkEnginePut	891 → 872	-2.2%	18 → 18
BenchmarkEnginePutParallel	861 → 842	-2.2%	18 → 18
BenchmarkStoreBitSet	81 → 77	-5.0%	1 → 1
BenchmarkStoreCGetHit	57 → 56	-1.3%	0 → 0
BenchmarkStoreCIncr	74 → 73	-1.2%	1 → 1
BenchmarkStoreCMSIncr	89 → 85	-5.3%	0 → 0
BenchmarkStoreCMSIncrN	90 → 84	-6.2%	0 → 0
BenchmarkStoreGeoAdd	8578 → 6668	-22.3%	2 → 2
BenchmarkStoreGeoPosHit	65 → 64	-1.7%	0 → 0
BenchmarkStoreGeoPosMiss	65 → 64	-0.6%	0 → 0
BenchmarkStoreGetHit	179 → 180	+0.6%	2 → 2
BenchmarkStoreGetHitParallel	218 → 212	-2.4%	2 → 2
BenchmarkStoreHGetHit	69 → 66	-3.7%	1 → 1
BenchmarkStoreHGetMiss	65 → 63	-3.3%	0 → 0
BenchmarkStoreHLLAdd	74 → 72	-1.6%	0 → 0
BenchmarkStoreHSet	7526 → 7413	-1.5%	3 → 3
BenchmarkStoreJsonSet	16282 → 15638	-4.0%	207 → 207
BenchmarkStorePut	184 → 194	+5.4%	2 → 2
BenchmarkStorePutParallel	213 → 211	-1.0%	2 → 2
BenchmarkStoreSetAdd	6689 → 6844	+2.3%	2 → 2
BenchmarkStoreSetContainsHit	62 → 62	+0.3%	0 → 0
BenchmarkStoreSetContainsMiss	62 → 61	-3.0%	0 → 0
BenchmarkStoreTopKAdd	582 → 592	+1.8%	20 → 20
BenchmarkStoreVAdd	62114 → 63734	+2.6%	515 → 515
BenchmarkStoreVSim	53377 → 54193	+1.5%	530 → 530
BenchmarkStoreZAdd	6676 → 6871	+2.9%	2 → 2
BenchmarkStoreZScoreHit	62 → 65	+3.7%	0 → 0
BenchmarkStoreZScoreMiss	64 → 64	-0.4%	0 → 0

_{Posted by CI bench job. Not a merge gate.}