docs(fsst): module docs, ADR, TODO follow-ups#297
Merged
Conversation
PR 8 of #287, the final PR of the FSST rewrite sequence. Documentation-only. - CLAUDE.md: add the fsst module to the module-structure block (zero dependency on core/reader/writer, writer/reader depend on it). - docs/reference.md: new "FSST" subsection under the API reference documenting the module's public surface (CompressorBuilder, Compressor, Decompressor, Symbol) for anyone using it standalone. - TODO.md: follow-up entries for what this rewrite deliberately left out of scope — AVX512/SIMD kernel, true per-row lazy/random-access decode (cross-referencing ADR 0010), and OptFSST (2026 DP-based training follow-up paper, not adopted since it trades training speed for compression ratio in a way that moves off the classic greedy-FSST tradeoff vortex-jni itself uses). - adr/0022-fsst-module-extraction.md (new, Accepted): the architectural record — why a standalone module, why MemorySegment not ByteBuffer at the boundary, the measured before/after numbers, and the risk class the boundary-overrun bug (found and fixed in PR 3) represents for future callers of the branch-free matcher. Added to adr/ADR.md's index. The CHANGELOG entry for this rewrite (with the before/after benchmark table) was already added directly to main in b218740 during the session, so this PR does not duplicate it. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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
PR 8 (final) of #287 — documentation-only, closing out the FSST rewrite sequence.
fsstadded to the module-structure block.CompressorBuilder/Compressor/Decompressor/Symbolpublic surface).adr/0022-fsst-module-extraction.md(Accepted): the full architectural record — why a standalone module, whyMemorySegmentnotByteBufferat the boundary, the measured before/after numbers, and the boundary-overrun bug found during the rewrite as a risk class future callers of the branch-free matcher need to watch for. Added to the ADR index.The CHANGELOG entry (with the before/after benchmark table) was already added directly to
mainearlier in the session (b218740f) — not duplicated here.This closes out the 8-PR #287 sequence: standalone
vortex-fsstmodule, paper-faithful branch-free matching and adaptive-sample training, rewired production adapters, golden test, and now full documentation.Test plan
./mvnw javadoc:javadoc -pl core— unaffected (pre-existing unrelated warning, confirmed no.javafiles touched)./mvnw verify -DskipTestsat root — full reactor SUCCESS🤖 Generated with Claude Code