LayerKeySort v3.0.0-rc.1

LayerKeySort v3.0.0-rc.1

v3.0.0-rc.1 is a public Release Candidate for the existing V3 architecture. It is a prerelease, not V3 Stable. Stable v2.0.0 remains the recommended release for normal use.

Goal

Freeze the V3 feature set and begin final release-candidate stabilization. RC.1 is intended for focused correctness, integration, and external-user validation rather than new architecture work.

Changes

• Retains the V3 separation between manual-coordinate LksTree and comparator-managed LksOrderedTree, together with the existing adaptive endpoint and relabel behavior.
• Keeps Path comparison, canonical display text, and LK1 v1 bytes unchanged.
• Adds focused regression coverage for documented invalid arguments, aliased locate outputs, duplicate and missing Paths, undersized formatting buffers, constructor allocation failures, and repeated create/destroy cycles.
• Clarifies version, prerelease status, compatibility, integration, migration, and benchmark documentation. The public API remains 59 functions.
• Does not change the production ordering algorithm or add product features.

Validation

The reviewed RC candidate passed a strict local GCC C17 build with -Wall -Wextra -Wpedantic -Werror, local MSVC x64 Debug and Release builds, and local MSVC AddressSanitizer tests. Local CTest passed 8/8 for GCC, MSVC Debug, and MSVC Release; the local MSVC AddressSanitizer configuration passed 5/5.

The reviewed candidate's GitHub Actions run passed Windows MSVC, Ubuntu GCC, Ubuntu Clang, Ubuntu Clang with sanitizers, and macOS AppleClang. Each job reported CTest 8/8. The final release-state commit was also required to pass branch CI before this tag was created.

During local RC preparation, three deterministic seeds each completed 150,000 manual-Tree and 200,000 ordered-Tree mixed-operation steps. Seven insertion distributions, including alternating extremes and a fixed interior hotspot, passed correctness checks at 100,000 items each. Three deterministic parser-torture seeds each completed 100,000 cases. Existing LK1 golden-vector, ordering-equivalence, deep-Path, and allocation-failure tests passed. These large local runs were not reproduced by every CI job.

Clean external consumers built and ran through add_subdirectory, SHA-pinned remote FetchContent, and direct documented C17 source integration. All three public examples also ran from the remote candidate source.

Known Limitations

• A comparator-managed insertion may relabel the full range of existing nodes.
• Large relabel work can cause significant synchronous tail latency.
• Path depth, memory use, and external key size depend on workload.
• No proven worst-case bound or formal amortized bound is claimed for complete managed insertion.
• Comparator-relevant fields of resident items must remain stable. To change such a field, remove the item by its exact Path, update it, then reinsert it.
• Paths and LK1 keys are ordering coordinates, not permanent item identities or distributed conflict-resolution records.

See docs/BENCHMARKS.md for measured workloads, methodology, and limitations. Its historical Preview measurements are not relabeled as RC measurements.

Feedback

Focused reports from external users are welcome, especially deterministic reproductions of correctness, integration, or latency problems. This release does not imply that a broad external testing community has already validated V3.