Repository navigation
LayerKeySort v4.0.0
V4.0.0 is the current recommended Stable release after Preview.1–5 and independently reviewed RC.1. Promotion changes release metadata and current presentation only; production algorithms, policy, tests and frozen contracts are unchanged.
What LayerKeySort V4 is
Dynamic ordering for changing collections in C17. Live order uses stable contextual handles; historical/persistent order uses immutable snapshots and sortable snapshot keys. Business identity and item payloads remain application-owned.
Live ordering
LksOrder supports relative/end insertion, logical traversal, removal, before/after moves and same-source contextual comparison. Handles survive unrelated mutations and moves; own removal/source destruction expires them. No live Path/LK1 coordinate rewrite or public physical topology.
Managed ordering
LksManagedOrder binds a copied comparator descriptor to the same core, preserving stable equality. Context/items are borrowed. Keep comparison semantics and resident comparison data stable: remove, edit, then reinsert when keys change. No arbitrary manual move facade.
Immutable Group/Batch
Flat immutable LksGroup / LksGroupBatch copy pointer arrays and borrow payloads. Stable build preserves equal input order; merge preserves Base-before-Incoming and Batch source-chunk equality precedence. Sources remain unchanged; no per-item Path/Tree representation.
Snapshot/export
Immutable snapshots copy namespace and application associations. Canonical LS1 version 1 keys preserve bytewise ordinal order within a namespace; semantic comparison rejects cross-domain keys. LKS4SNP1 provides strict canonical big-endian serialization without native structs. Restore resolves associations to caller items and creates fresh handles. Snapshots outlive sources/items; loaded snapshots do not restore provenance/currentness. Historical keys are not live positions or permanent item IDs.
V3 migration
V4 is a major source break from V3. The primary header no longer exports Path, Tree, OrderedTree or transitional immutable_group APIs. Strict published-V3-LK1 import supports existing coordinate data. Applications requiring Path/Tree may stay on unchanged historical Stable v3.1.0. See migration.
Reliability
Frozen 64 functions / 14 types and unchanged numeric statuses. Strong failure atomicity, OOM/failpoint coverage and allocation-free assertions remain for mutation, cursors, snapshots, persistence/restore, migration and Group/Batch.
Five local configurations passed 39/39 tests and seven examples: GCC16.2 strict C17 Release; MSVC x64 Debug, Release with symbols, ASan and Win32 Debug. Clean GCC/MSVC x64/Win32 C17/C++17 consumers reference all64 APIs through public headers across source, offline FetchContent, installed and amalgamated builds. Local Clang/GCC sanitizer runtimes are unavailable; remote sanitizer gates supply that coverage.
The exact candidate and separate main push passed six CI configurations: Windows x64/Win32, Ubuntu GCC/Clang/Clang ASan+UBSan and macOS AppleClang. Each passed39 tests, seven examples, manifest and distribution consumers. GCC validated assets; Clang sanitizer retained RC extended mutation/parser/distant-move/churn coverage. Seven LS1, four wire and17 V3 LK1 vectors remain exact, including identical x86/x64 wire expectations.
Performance
V4 avoids collection-wide live-coordinate relabel and Path growth. Local block maintenance is bounded; balanced index updates remain. Move structural work is independent of logical distance in this representation.
Preview.4 evidence on one documented machine includes a100k-initial/100k-operation timeline at28.912ms, observing maxima95 assignments/2 arrays/15 index-block updates. These are observations, not latency bounds. Stable performed no timing/tuning experiment;16 focused replays matched16 frozen maintenance/comparison/cleanup counters. See captured evidence and methodology. No universal speedup, realtime, universal O(1) mutation, whole-operation O(log N) latency or optimality claim.
Compatibility
V4 4.x source/layout and LS1/LKS4SNP1 contracts are frozen. Rebuild the static library for compiler, architecture and CRT; no universal binary/shared-library ABI. Private archive symbols are not supported APIs. Wire formats and signatures must not be silently reinterpreted.
Known costs
Per-resident allocation, block slack/local writes, comparator/callback/allocator/OS cost remain. Full snapshot/export is O(N+A); retained history, associations and Group scratch can dominate memory. Caller lifetimes and mutable serialization remain required. Dangling handles cannot be safely probed. No persistent live handles, incremental export or CRDT guarantee. Real-user traces, formal whole-library bounds, pooling/slabs, defensive registry, broader platforms, Mini/MCU remain deferred; no new research cycle begins here.
Assets
LayerKeySort-4.0.0-amalgamation.zip: exactlylayerkeysort.h,layerkeysort.c,example.c,LICENSE,README.txt. Compile implementation as C17; C++17 clients link it. No binaries, private headers or runtime Python.LayerKeySort-4.0.0-SHA256SUMS.txt: source ZIP SHA-256.
Independent package generations are byte-identical; normalized metadata, membership, checksum/tamper/extra-file rejection and packaged example passed. Uploaded sizes/digests and downloaded bytes match local assets.
Release identity
Starting RC.1: 9ad636fb2e292070505a86f59011d433296651b1.
Final Stable commit: 80004ae732daf696f7e9192e417de0edb0b2aafa.
Annotated tag: v4.0.0.