chore(adr): record raft-engine fork for lz4-sys feature-gate (W5)#48
Merged
Conversation
added 2 commits
April 24, 2026 15:44
ADR 0002 §W5 previously assumed upstream raft-engine's lz4-sys C FFI dependency could be mitigated purely at the data path - by disabling raft-engine's own compression and doing it above the engine in mango-raft using lz4_flex. That remains true for the data path, but the build-graph concern - upstream's unconditional lz4-sys dependency pulling the C toolchain into mango's supply chain - was unsolved by the data-path mitigation alone. This commit records the build-time fix: 1. ADR 0002 §W5 expanded to document the active fork (humancto/raft-engine at SHA e1d738d), the upstream PR that tracks its retirement (tikv/raft-engine#397), and the explicit consumer contract (default-features = false, feature list, and the Config::sanitize reject enforcing batch-compression-threshold = 0). 2. New file .planning/fork-raft-engine-lz4-verification.md records the full fork state: SHA pins, PR URL, commit footprint, how mango consumes the fork, rebase policy while the fork lives, retirement plan when #397 merges, and supply-chain audit posture. The fork itself was adversarially reviewed by rust-expert across two rounds (REVISE -> APPROVE_WITH_NITS). Upstream PR #397 is open. No mango Cargo.toml changes here - the workspace dep entry lands with PR-1 (mango-storage skeleton) which pins the fork SHA.
…tems rust-expert's review of PR #48 returned APPROVE_WITH_NITS with two must-fix items on .planning/fork-raft-engine-lz4-verification.md. Both are text-only and localized; applying them here to close out the review without another round. 1. Retirement branches for non-merge endings. Original text assumed upstream PR #397 merges. Added a new "What if upstream rejects the approach or stalls" section with two branches: (a) #397 closed without merge, upstream proposes a different shape - swap the tracked PR, follow the same 6-step retirement once the replacement merges. (b) #397 stalls for 12+ months - escalate to ADR 0002 §W4 escape hatch (b) and vendor the pinned fork SHA under crates/vendored-raft-engine/. 2. Supply-chain audit posture corrected. Original paragraph conflated cargo-vet's exemption-identity behavior with SHA pinning and review-by annotations. Rewritten to spell out the actual semantics: - Exemptions key on (crate_name, crate_version); the fork and upstream both ship package.version = "0.4.2", so one exemption line covers both while the fork is active and after retirement. - Patch-version bumps (raft-engine historically bumps on master without publishing) break matching and need a new version line. - SHA swaps are silent to vet - no re-exemption needed on rebase. - review-by is a mango convention, not a vet behavior; dates need manual refresh on rebase and on retirement. Per rust-expert's explicit guidance, no further review round is needed for these text-only edits.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Record the active
humancto/raft-enginefork and the upstream PR that tracks its retirement. Amends ADR 0002 §W5 (storage engine lz4-sys C FFI concern) and adds a dedicated tracking file.Closes no roadmap item directly — PR-0.5 of Phase 1, unblocking PR-1 (
mango-storageskeleton, ROADMAP:815) which will pin the fork SHA in a workspaceCargo.tomlentry.Context
Upstream
tikv/raft-enginemaster hadlz4-sys = "=1.9.5"as an unconditional dependency. ADR 0002 §W5 originally mitigated this purely at the data path (disable raft-engine's compression, do it above inmango-raftvialz4_flex). That addresses the CPU path but leaves the C toolchain in mango's supply chain.To preserve the ROADMAP's pure-Rust north-star end-to-end (build graph included, not just data path), I:
tikv/raft-enginetohumancto/raft-engine.lz4-compressionCargo feature that gateslz4-sysbehinddep:lz4-sys, default-on upstream to preserve BC.rust-expertacross two rounds — REVISE → APPROVE_WITH_NITS — folding in six correctness / docs / CI fixes between rounds.tikv/raft-engine#397with the same patch.This mango PR records the fork state in-tree so the build-time mitigation is auditable, the retirement plan is written down, and any future contributor can see the full picture without digging through history.
Changes
.planning/adr/0002-storage-engine.md§W5: existing "disable compression; lift to mango-raft" mitigation is kept as the data-path story. Added an "Active fork" primary mitigation that documents the build-time gate, the fork SHA, the upstream PR, and the exactCargo.tomlconsumer shape (default-features = false,features = ["internals", "scripting"])..planning/fork-raft-engine-lz4-verification.md(new): fork SHA pins, upstream PR URL, two-commit footprint, consumption pattern, rebase policy while the fork lives, retirement steps when #397 merges, and supply-chain audit posture.No Cargo.toml changes in this PR. The workspace dep entry pinning the fork lands with PR-1.
Test plan
humancto/raft-engine:feat/feature-gate-lz4-sysHEAD:e1d738d9ad1c1fc4f5b21c8c73bf605b5696f535.tikv/raft-engine#397..planning/exclude gate respected — files force-added in-tree like prior planning/ADR files.🤖 Generated with Claude Code