spec(interop): promote interop mode to specified (interop/v1) with canonical test vectors

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to the CacheKit Protocol Specification.
 
+## [Unreleased]
+
+### Specs
+- Interop mode promoted from draft to specified (interop/v1): flat canonical argument
+  array (named→positional binding), number canonicalization (integral float64 → int,
+  the only rule implementable in JS), code-point map-key ordering, encoded-byte set
+  ordering, bit-deterministic datetime rule, canonical (shortest-form) MessagePack
+  encoding, plain-MessagePack value format, unchanged AAD v0x03. Design rationale
+  recorded in the spec's Design Decisions section. ([#1](https://github.com/cachekit-io/protocol/issues/1))
+
+### Test Vectors
+- 22 interop key vectors, 4 value vectors, 1 AAD vector, 7 must-reject error vectors
+  (`test-vectors/interop-mode.json`), generated by a stdlib-only Python reference
+  implementation (`tools/interop-reference.py`) and byte-verified by an independent
+  JavaScript encoder using `@noble/hashes` (`tools/interop-crosscheck.mjs`).
+
 ## [1.0.0] - 2026-03-28
 
 Initial protocol specification.

README.md

@@ -104,7 +104,7 @@ User data restored
 | [spec/wire-format.md](spec/wire-format.md) | ByteStorage envelope — LZ4 block compression, xxHash3-64 integrity, decompression bomb protection |
 | [spec/encryption.md](spec/encryption.md) | AES-256-GCM encryption, HKDF-SHA256 key derivation, AAD v0x03, counter-based nonces, key rotation |
 | [spec/saas-api.md](spec/saas-api.md) | REST API endpoints, binary wire protocol, error codes, metrics headers |
-| [spec/interop-mode.md](spec/interop-mode.md) | Cross-SDK cache sharing — language-neutral key format, canonical argument normalization *(draft)* |
+| [spec/interop-mode.md](spec/interop-mode.md) | Cross-SDK cache sharing — language-neutral key format, canonical argument normalization *(specified, not yet implemented in any SDK)* |
 | [sdk-feature-matrix.md](sdk-feature-matrix.md) | Feature parity tracking across Python, Rust, TypeScript, and PHP SDKs |
 
 ---
@@ -160,7 +160,7 @@ An SDK is protocol-compliant when:
 3. Encrypted payloads can be decrypted by any SDK with the same master key and tenant ID
 4. SaaS API integration follows the documented endpoint contracts
 
-Test vectors are published in [`test-vectors/`](test-vectors/) as YAML files.
+Test vectors are published in [`test-vectors/`](test-vectors/) as JSON files.
 
 > [!CAUTION]
 > Self-referential tests (SDK encrypts and decrypts its own output) are not sufficient for compliance certification. Use the canonical cross-SDK test vectors to validate interoperability.

sdk-feature-matrix.md

@@ -128,6 +128,7 @@ For cross-SDK interoperability, all SDKs MUST implement:
 | AAD v0x03 | ✅ Compliant | ✅ Compliant | ✅ Compliant | ❌ Not implemented |
 | SaaS API | ✅ Compliant | ✅ Compliant (CachekitIO backend) | ✅ Compliant | ❌ Not implemented |
 | Test vectors | ⚠️ Pending | ⚠️ Pending | ✅ Python cross-SDK vectors | ⚠️ Pending |
+| Interop mode ([spec](spec/interop-mode.md), opt-in) | ❌ Not implemented | ❌ Not implemented | ❌ Not implemented | ❌ Not implemented |
 
 > [!NOTE]
 > "N/A" for Rust key generation means `cachekit-core` is a protocol primitive library. Key generation (Blake2b) is an SDK-level concern — `cachekit-rs` delegates cache key construction to the caller via the `key` parameter on `get`/`set`/`#[cachekit]`.