From f0672c1cf2a3bbd2ba3f4760b6d1406a4357aab9 Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Tue, 21 Jul 2026 01:26:25 +1000 Subject: [PATCH] =?UTF-8?q?LAB-425:=20cache-keys.json=20=E2=80=94=20re-sta?= =?UTF-8?q?mp=20to=20cachekit-py=20v0.12.0,=20document=20CI=20enforcement?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 10 auto-mode key vectors byte-verified against current cachekit-py (v0.12.0) — content unchanged since the v0.5.0 stamp, so this is a metadata-only re-stamp, not a regeneration. The vectors are now vendored (sha256-pinned) into cachekit-py and asserted against CacheKeyGenerator in its default CI (tests/unit/protocol/test_cache_key_vectors.py), closing the gap where no CI anywhere enforced auto-mode key stability. Spec header updated from the stale v0.5.0 verification claim; new Test Vectors section points at the file and its enforcement. Co-authored-by: multica-agent --- spec/cache-key-format.md | 11 ++++++++++- test-vectors/cache-keys.json | 3 ++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/spec/cache-key-format.md b/spec/cache-key-format.md index 483fdfd..172bc7d 100644 --- a/spec/cache-key-format.md +++ b/spec/cache-key-format.md @@ -6,7 +6,7 @@ **Deterministic key generation from function identity and arguments.** -*Protocol Version 1.0 · Verified against `cachekit-py` v0.5.0 (`src/cachekit/key_generator.py`)* +*Protocol Version 1.0 · Verified against `cachekit-py` v0.12.0 (`src/cachekit/key_generator.py`)* @@ -18,6 +18,7 @@ - [Cross-SDK Key Generation Strategy](#cross-sdk-key-generation-strategy) - [Argument Hashing Algorithm](#argument-hashing-algorithm) - [Character Normalization](#character-normalization) +- [Test Vectors](#test-vectors) - [Pseudocode for SDK Implementors](#pseudocode-for-sdk-implementors) --- @@ -188,6 +189,14 @@ After key construction, the following characters are replaced: --- +## Test Vectors + +[`test-vectors/cache-keys.json`](../test-vectors/cache-keys.json) contains 10 auto-mode key vectors (`args` + `kwargs` + metadata → `expected_key`) covering primitives, mixed args/kwargs, `null`, booleans, nested dicts, and the no-namespace form. Keys were generated at top level, so the `func:` segment is `__main__.{qualname}` — cross-SDK implementations substitute their own module path; only the args-hash segment must match byte-for-byte. + +Enforcement: the vectors are vendored (sha256-pinned) into cachekit-py and byte-verified against `CacheKeyGenerator` on every default CI run (`tests/unit/protocol/test_cache_key_vectors.py`). A vector failing there is a key-stability break to triage — never silently regenerate: a changed key orphans every existing cache entry and turns the fleet's hits into billed misses. + +--- + ## Pseudocode for SDK Implementors
diff --git a/test-vectors/cache-keys.json b/test-vectors/cache-keys.json index b63fbe6..304fae8 100644 --- a/test-vectors/cache-keys.json +++ b/test-vectors/cache-keys.json @@ -1,6 +1,7 @@ { "version": "1.0.0", - "generator": "cachekit-py v0.5.0", + "generator": "cachekit-py v0.12.0", + "ci_verification": "Vendored (sha256-pinned) and byte-verified against CacheKeyGenerator in cachekit-py default CI: tests/unit/protocol/test_cache_key_vectors.py", "note": "Keys include __main__ module because vectors were generated at top level. Cross-SDK implementations should substitute their own module path \u2014 only the args hash portion must match.", "key_format": "ns:{namespace}:func:{module}.{qualname}:args:{blake2b_256_hex}:{ic_flag}{serializer_code}", "hash_algorithm": "blake2b-256 of msgpack([normalized_args, sorted_kwargs])",