Skip to content

LAB-425: re-stamp cache-keys.json to cachekit-py v0.12.0 — now CI-enforced in cachekit-py #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
27Bslash6 merged 1 commit into from
Jul 21, 2026
+12 −2
Merged

LAB-425: re-stamp cache-keys.json to cachekit-py v0.12.0 — now CI-enforced in cachekit-py #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion spec/cache-key-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`)*

</div>

Expand All @@ -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)

---
Expand Down Expand Up @@ -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

<details>
Expand Down
3 changes: 2 additions & 1 deletion test-vectors/cache-keys.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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])",
Expand Down
Loading