feat(skippy-cache): raw codec identity in L3 manifests (#1652 first slice) by i386 · Pull Request #1750 · Mesh-LLM/mesh-llm

i386 · 2026-09-10T05:21:29Z

First slice of #1652 (codec versioning). Introduces an explicit raw codec identity + version in the L3 handoff manifest, enforces it by manifest version (not defaultable), and rejects unsupported codecs at every load path before segments are read or the LRU heats.

Stacked on scama/skippy-l3-streaming-restore (#1736 head 7247a397a). Payload-level, raw-only. No Q8/Q4 data path, no request-path performance work, no #1650/#1651 changes. Per-segment/mixed codec identity is later #1652 work.

What it does

Adds PayloadCodec { name, version } with CODEC_RAW / CODEC_RAW_VERSION. raw (uncompressed exact state) is the only implemented representation — segment bytes are unchanged.
Version-enforced identity (not a serde default). MANIFEST_VERSION is bumped to 3, which requires an explicit codec. LEGACY_MANIFEST_VERSION = 2 is decoded as raw through an explicit legacy path. HandoffManifest.codec is Option<PayloadCodec> purely so a v3 manifest with the codec stripped is detectable and rejected, rather than silently reinterpreted as raw (the whole-payload digest matches the stored bytes, so a serde default would bypass the gate — the downgrade hole this fixes).
Central capability gate in decode_manifest. Every load path enforces codec support before returning a manifest:
- startup reconcile_startup → validate_committed_manifest → load_manifest → quarantines an unsupported manifest;
- manifest_for_prefix prunes the bad prefix link and returns a miss, so locate_longest falls back to the shorter supported prefix;
- direct load_manifest fails.
Writer/in-memory guards remain: try_commit never persists an unassemblable manifest, and assemble refuses one before reassembly.
The identity travels in the portable manifest, so it is carried by the network handoff as well as the disk tier.

Tests (`skippy-cache`)

manifest_stamps_explicit_raw_codec_and_round_trips
legacy_manifest_without_codec_field_reads_and_assembles_as_raw
stripping_codec_from_current_version_rejects_but_legacy_v2_reads_as_raw (downgrade regression)
on_disk_unsupported_codec_fails_direct_load
startup_reconciliation_quarantines_unsupported_codec_manifest
locate_longest_skips_unsupported_codec_and_falls_back_to_shorter (tier fallback)
unknown_codec_is_refused_at_commit_and_leaves_no_manifest, unknown_codec_is_rejected_before_assembly, unknown_raw_codec_version_is_rejected_at_commit_and_assembly, codec_gate_does_not_mask_payload_corruption

Validation

cargo test -p skippy-cache: 131 passed / 1 ignored / 0 failed. cargo clippy -p skippy-cache --all-targets -- -D warnings: clean. cargo fmt: clean. (skippy-bench does not depend on skippy-cache on this base, so it is unaffected.)

🤖 Generated with Claude Code

…#1652) First slice of codec versioning: record an explicit codec name+version in the L3 handoff manifest so payload representations are namespaced rather than guessed, and refuse a payload this build cannot decode before assembly. - Add PayloadCodec { name, version } and CODEC_RAW / CODEC_RAW_VERSION. raw is the only implemented representation; the segment bytes are unchanged. - HandoffManifest gains a #[serde(default)] codec field, defaulting to raw. A manifest written before codec identity existed has no field and reads as raw — backward compatible, and MANIFEST_VERSION is unchanged so existing on-disk entries stay valid. - reject_unsupported_codec gates both try_commit (nothing unassemblable is ever persisted) and assemble (an unknown codec/version is a miss, never a silent misinterpretation of the bytes). Tests (skippy-cache, l3): explicit-raw round trip, legacy manifest without a codec field reads/assembles as raw, unknown codec refused at commit (no manifest left) and before assembly, unknown raw version refused on both paths, and a supported-codec payload whose bytes are corrupted still fails digest verification. No Q8/Q4 data path, request-path, or #1650/#1651 changes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-09-10T05:21:37Z

This pull request is currently a draft. Reviews will not take place until the PR is marked as ready for review.

coderabbitai · 2026-09-10T05:21:41Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 5e0d8a2c-018a-40ce-8727-011829e89427

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

…d paths (#1652 review) Addresses scama's two compatibility blockers on the raw codec slice. 1. Codec identity was downgradeable. With a serde-default codec at a fixed manifest version, the field could be stripped to force a raw reinterpretation of possibly non-raw bytes (the whole-payload digest still matches those bytes, bypassing the gate). Fix: bump MANIFEST_VERSION to 3, which *requires* an explicit codec, and add LEGACY_MANIFEST_VERSION (2) decoded as raw through an explicit legacy path. `codec` is now `Option<PayloadCodec>` so a stripped v3 codec is detectable and rejected instead of defaulted. 2. Unsupported codecs were locatable "hits". decode_manifest now centrally rejects an unsupported/absent codec, so every load path enforces it: startup reconciliation quarantines the manifest, manifest_for_prefix prunes the bad link and locate_longest falls back to a shorter supported prefix, and a direct load_manifest fails — all before segments are read or the LRU heats. Tests: downgrade (strip codec from a current-version manifest rejects; a genuine v2 legacy manifest still reads/assembles as raw), on-disk direct-load rejection, startup reconciliation quarantine, and locate_longest unsupported-longest/supported-shorter fallback — in addition to the existing round-trip, unknown-codec/version, and corruption-guard cases. Scope unchanged: payload-level raw-only; per-segment/mixed codec identity is later #1652 work. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…commit/assemble (#1652 review) try_commit and assemble checked codec support but not manifest.version, so a raw-codec manifest carrying an unknown future version could be persisted (and its segments read) even though decode_manifest/load_manifest reject it on the next read. Centralize both checks in validate_manifest_compatibility (supported current/legacy version + supported codec) and call it before commit and before any segment access. Regressions: a future-version raw manifest is refused by commit (leaving no persisted manifest) and before assembly. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

i386 · 2026-09-10T06:20:44Z

Exact-head code review and the required cache performance gate now pass at 5effeffb1a64e8b382a8a504cb75a9d5c8141ffc.

Compatibility review:

manifest v3 requires an explicit supported codec;
legacy v2 is normalized through the explicit raw path;
unsupported codec or manifest versions are rejected before commit, lookup, reconciliation, assembly, or segment access;
startup quarantine and longest-supported-prefix fallback are covered by on-disk regressions.

Validation:

cargo test -p skippy-cache: 133 passed, 1 ignored;
cargo clippy -p skippy-cache --all-targets -- -D warnings: clean;
cargo fmt --all --check and git diff --check: clean.

Matched performance gate:

exact release host SHA-256: c9daa526993f3ab84ef5f3e7d11519758a47c5bddffd7dc7593ea886f9476ddb;
matching locally packaged macOS Metal runtime, Skippy ABI 0.1.53, primary library SHA-256 fc8de19b58365b53255d1be948a3ce22b3c4d4119018f64e3a461ca287136a3a;
same M1 Ultra, SmolLM2 Q8 model bytes, 3,994-token workload manifest, disk-cache settings, and three-run restart method as accepted Stream and pipeline local KV state export and restore end to end #1649 evidence;
first-restore TTFT: 109.274 / 109.300 / 106.378 ms, median 109.274 ms;
baseline Stream and pipeline local KV state export and restore end to end #1649 treatment median: 109.5 ms;
every run restored 3,993 / 3,994 prompt tokens (99.975%), with zero failed requests;
median restore decode rate: 200.879 tok/s; median resident-warm TTFT: 18.179 ms.

The roughly 0.2% lower restore median is within normal run noise. No material restart, reuse, or throughput regression is visible from the manifest-version and codec-validation change.

i386 · 2026-09-12T04:10:12Z

Consolidated into #1816: #1816

This PR's head is an ancestor of the consolidated branch, so its commits and behavior remain in the combined review. Please continue review on #1816.

Bumps the L3 manifest format to v4 and moves codec identity down to the segment level, the contract #1652 needs before any non-raw codec exists: each segment names its codec, representation version, exact/lossy class, decoded length, and (lossy only) calibration digest. - MANIFEST_VERSION is now 4 and requires explicit identity on every segment; v3 (#1750, payload-level codec) and v2 (pre-codec) become explicit legacy read paths, never written. - The per-segment identity is Option only so a v4 manifest with the field stripped is detectable and rejected — it never falls back to the payload codec or to raw. The check runs in decode_manifest (load), try_commit (persist), and assemble (read), so nothing unloadable is ever persisted or partially served. - CodecClass distinguishes exact entries (payload-digest verified) from lossy ones (calibration-namespaced, never satisfy an exact lookup). A lossy identity must carry a calibration digest; an exact identity must decode to its own stored bytes. - Writers stamp SegmentCodecIdentity::raw on every segment; capability negotiation names the offending segment index on refusal. Regressions: v4 per-segment stamping round trip, v3 read compatibility, v4 stripped-segment rejection at load/commit/assemble (single and all segments), unsupported segment codec naming the segment, and decoded_len mismatch refusal.

i386 added the skippy-kv Work coordinated in Buzz #skippy-kv label Sep 10, 2026

i386 mentioned this pull request Sep 10, 2026

KV roadmap rollup: Skippy KV cache tiers, codecs, reuse, and observability #1732

Open

i386 mentioned this pull request Sep 10, 2026

skippy-cache: add codec identity to segment manifests (codec-identity slice for #1652) #1751

Closed

i386 marked this pull request as ready for review September 10, 2026 06:20

github-actions Bot requested a review from ndizazzo September 10, 2026 06:20

github-actions Bot assigned i386 Sep 10, 2026

This was referenced Sep 10, 2026

Version KV segments for native passthrough and CacheGen #1652

Open

feat(skippy-cache): per-segment codec contract, CPU golden CacheGen, CubeCL spike (#1652) #1752

Closed

ndizazzo added this to the 0.77.0 milestone Sep 10, 2026

Merge branch 'sync-tmp-1736' into sync-tmp-1750

a0876ee

i386 mentioned this pull request Sep 12, 2026

feat(skippy): add CacheGen compression and device restore #1816

Closed

i386 closed this Sep 12, 2026

Navigation Menu

Uh oh!

Uh oh!

feat(skippy-cache): raw codec identity in L3 manifests (#1652 first slice) - #1750

feat(skippy-cache): raw codec identity in L3 manifests (#1652 first slice)#1750
i386 wants to merge 4 commits into
scama/skippy-l3-streaming-restorefrom
erlich/skippy-codec-identity

i386 commented Sep 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 10, 2026

Uh oh!

coderabbitai Bot commented Sep 10, 2026 •

edited

Loading

Review skipped

Uh oh!

i386 commented Sep 10, 2026

Uh oh!

i386 commented Sep 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

i386 commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What it does

Tests (skippy-cache)

Validation

Uh oh!

github-actions Bot commented Sep 10, 2026

Uh oh!

coderabbitai Bot commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

i386 commented Sep 10, 2026

Uh oh!

i386 commented Sep 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

i386 commented Sep 10, 2026 •

edited

Loading

Tests (`skippy-cache`)

coderabbitai Bot commented Sep 10, 2026 •

edited

Loading