V2 Roadmap and Known Technical Debt
Status and baseline
Status: Active post-2.0 V2 technical-debt roadmap
Current baseline: v2.0.0
Release commit: 9fb7a9b0ae8d71cbd7410822e37702f6a6dc4d88
Stable v2.0.0 was integrated into main, validated by five-platform GitHub Actions and Pages, tagged, and published as the first stable V2 GitHub Release. RC.1 observation found no confirmed release blocker. This issue remains open for post-2.0 technical debt. Earlier comments are the chronological release audit trail; Issue #1 remains historical v1 context.
Current V2 model
A Path is a mutable ordering coordinate, not permanent application item identity. Caller items are borrowed; published Groups are immutable. The mutable Tree uses a Path-keyed AVL index, whose physical parent/child links do not represent Path-prefix hierarchy. Logical Path order is defined by lks_path_compare(). Actual Tree mutations invalidate borrowed Tree nodes, Paths, and navigation observations as documented; equal-Path rekey is a successful no-op.
Readable display text is not a lexical sort key. Canonical same-version LK1 keys persist one Path coordinate and sort in Path order under bytewise ASCII collation. LK1 does not serialize a Tree or item payload, assign permanent identity, or provide distributed conflict resolution. The documented 2.x source/API and semantic compatibility contract is active from v2.0.0. Stable status does not imply a formal insertion bound or universal performance guarantee.
Completed V2 milestones
Preview.1 — V2 baseline
Established re-encodable Path semantics, sparse bulk construction, immutable Group/Batch merge behavior, stable sort convenience, CMake/CI, and production/diagnostic allocation separation.
Preview.2 — bounded local repair
Added bounded local congestion repair, prepare/validate/commit failure behavior, diagnostics, and full-rebuild fallback hardening.
Preview.3 — wider coordinates and compact display text
Expanded slots to 0..65535, introduced three-character radix-54 slot tokens, and spread sparse bulk coordinates across the wider domain.
Preview.4 — core architecture convergence
Decoupled mutable Tree topology from Path prefixes, replaced ChildBlock storage with a Path-keyed AVL index, removed linear equal-run successor scanning, and moved local repair to logical-order windows. Added exact-Path remove, failure-atomic rekey, strict display parsing, and the versioned sortable LK1 key. A reproducible benchmark harness records workload-specific evidence, including regressions and full-rebuild costs. These Preview.3-era gaps are completed, not active debt.
Preview.5 — usability, integration, and validation
Added a compilable dynamic layer-list example; when-to-use and when-not-to-use guidance; an integration guide for add_subdirectory, FetchContent, and direct C17 sources; a deterministic mixed-operation mutation soak; and macOS AppleClang CI. A 500,000-operation manual soak passed. A function-by-function documentation audit now covers all 52 public functions. Five CI configurations each passed CTest 5/5, including the soak and benchmark smoke tests; both examples ran. Preview.5 changed no public API, LK1 grammar, or production algorithm relative to Preview.4.
RC.1 — feature, API, and format freeze candidate
RC.1 freezes the intended V2 feature set, 52-function public C API, canonical Path display contract, and LK1 v1 format. The new 2.x compatibility contract separates stable source/semantic promises from generated Path values and private implementation details. Clean local checkouts, add_subdirectory, direct C17 source integration, and FetchContent pinned to the exact candidate commit passed. After publication, FetchContent using the real RC.1 tag also passed. Windows MSVC, Ubuntu GCC, Ubuntu Clang, Ubuntu Clang with sanitizers, and macOS AppleClang each passed CTest 5/5, including the mutation soak; both examples ran. RC.1 changed no production algorithm or LK1 bytes from Preview.5 and does not attempt to solve the remaining research or performance debts.
Stable 2.0.0 — first stable V2 release
Stable 2.0.0 preserves RC.1's production implementation, 52-function public API, canonical Path display grammar, and LK1 v1 bytes. The RC.1 observation commit 5715b82a054e8ac2f73973193999a91322720cc6 is retained in main. It added a business-ID/LK1 persistence round trip, deterministic parser torture, multi-seed mutation-soak support, and Path-growth OOM rollback coverage without changing production code. The manual observation passed 20 soak seeds × 100,000 operations and 16 parser seeds × 100,000 cases. The final release-state commit passed five CI configurations, each with CTest 7/7, and Pages. The real v2.0.0 FetchContent consumer checked out the release commit and ran successfully.
See benchmark evidence for measured Preview.3/Preview.4 comparisons and their limitations. Preview.5 did not replace the captured timing data or claim a universal speedup.
Active post-2.0 technical debt
- Full-rebuild fallback cost: A failure-atomic full rebuild remains possible and can dominate an individual comparator-driven insertion. Study frequency, affected-node totals, and coordinate growth before changing policy.
- Formal operation bounds: Balanced AVL search alone does not bound complete comparator-driven insertion. No worst-case O(log n) or formal amortized bound is claimed for the full operation.
- Comparator invariant safety: Comparator-driven operations require existing items to be compatible with the supplied comparator/context in Path order. The low-level Tree does not bind one comparator as permanent state; a future facade could address this API footgun.
- Higher-level movement convenience: Rekey supplies the low-level coordinate change, but application-facing move-before/move-after helpers are absent.
- External application validation: The new example and soak improve internal evidence; real integrations, long-running usage, and feedback from external users are still needed.
Persistence and optional scope
Stable v2.0.0 preserves canonical display parsing and a versioned, sortable LK1 representation of one Path coordinate. It does not provide whole-Tree or caller-item serialization, permanent item IDs, fixed-size ranks, distributed replica identity, or CRDT convergence. Incompatible future external keys require a new format version, not reinterpretation of LK1.
Package-manager recipes, a public custom allocator, alternative index architectures, compact key variants, and specialized sorting optimizations remain optional work requiring separate justification. They are not part of stable v2.0.0.
Next decision point
No v2.1 or V3 scope is committed. Future work should be selected from evidence about full-rebuild cost, rigorous operation bounds, comparator-invariant API ergonomics, movement helpers, and external application usage. These open items were not prerequisites for stable v2.0.0.
References
V2 Roadmap and Known Technical Debt
Status and baseline
Status: Active post-2.0 V2 technical-debt roadmap
Current baseline: v2.0.0
Release commit:
9fb7a9b0ae8d71cbd7410822e37702f6a6dc4d88Stable v2.0.0 was integrated into main, validated by five-platform GitHub Actions and Pages, tagged, and published as the first stable V2 GitHub Release. RC.1 observation found no confirmed release blocker. This issue remains open for post-2.0 technical debt. Earlier comments are the chronological release audit trail; Issue #1 remains historical v1 context.
Current V2 model
A Path is a mutable ordering coordinate, not permanent application item identity. Caller items are borrowed; published Groups are immutable. The mutable Tree uses a Path-keyed AVL index, whose physical parent/child links do not represent Path-prefix hierarchy. Logical Path order is defined by lks_path_compare(). Actual Tree mutations invalidate borrowed Tree nodes, Paths, and navigation observations as documented; equal-Path rekey is a successful no-op.
Readable display text is not a lexical sort key. Canonical same-version LK1 keys persist one Path coordinate and sort in Path order under bytewise ASCII collation. LK1 does not serialize a Tree or item payload, assign permanent identity, or provide distributed conflict resolution. The documented 2.x source/API and semantic compatibility contract is active from v2.0.0. Stable status does not imply a formal insertion bound or universal performance guarantee.
Completed V2 milestones
Preview.1 — V2 baseline
Established re-encodable Path semantics, sparse bulk construction, immutable Group/Batch merge behavior, stable sort convenience, CMake/CI, and production/diagnostic allocation separation.
Preview.2 — bounded local repair
Added bounded local congestion repair, prepare/validate/commit failure behavior, diagnostics, and full-rebuild fallback hardening.
Preview.3 — wider coordinates and compact display text
Expanded slots to 0..65535, introduced three-character radix-54 slot tokens, and spread sparse bulk coordinates across the wider domain.
Preview.4 — core architecture convergence
Decoupled mutable Tree topology from Path prefixes, replaced ChildBlock storage with a Path-keyed AVL index, removed linear equal-run successor scanning, and moved local repair to logical-order windows. Added exact-Path remove, failure-atomic rekey, strict display parsing, and the versioned sortable LK1 key. A reproducible benchmark harness records workload-specific evidence, including regressions and full-rebuild costs. These Preview.3-era gaps are completed, not active debt.
Preview.5 — usability, integration, and validation
Added a compilable dynamic layer-list example; when-to-use and when-not-to-use guidance; an integration guide for add_subdirectory, FetchContent, and direct C17 sources; a deterministic mixed-operation mutation soak; and macOS AppleClang CI. A 500,000-operation manual soak passed. A function-by-function documentation audit now covers all 52 public functions. Five CI configurations each passed CTest 5/5, including the soak and benchmark smoke tests; both examples ran. Preview.5 changed no public API, LK1 grammar, or production algorithm relative to Preview.4.
RC.1 — feature, API, and format freeze candidate
RC.1 freezes the intended V2 feature set, 52-function public C API, canonical Path display contract, and LK1 v1 format. The new 2.x compatibility contract separates stable source/semantic promises from generated Path values and private implementation details. Clean local checkouts, add_subdirectory, direct C17 source integration, and FetchContent pinned to the exact candidate commit passed. After publication, FetchContent using the real RC.1 tag also passed. Windows MSVC, Ubuntu GCC, Ubuntu Clang, Ubuntu Clang with sanitizers, and macOS AppleClang each passed CTest 5/5, including the mutation soak; both examples ran. RC.1 changed no production algorithm or LK1 bytes from Preview.5 and does not attempt to solve the remaining research or performance debts.
Stable 2.0.0 — first stable V2 release
Stable 2.0.0 preserves RC.1's production implementation, 52-function public API, canonical Path display grammar, and LK1 v1 bytes. The RC.1 observation commit
5715b82a054e8ac2f73973193999a91322720cc6is retained in main. It added a business-ID/LK1 persistence round trip, deterministic parser torture, multi-seed mutation-soak support, and Path-growth OOM rollback coverage without changing production code. The manual observation passed 20 soak seeds × 100,000 operations and 16 parser seeds × 100,000 cases. The final release-state commit passed five CI configurations, each with CTest 7/7, and Pages. The realv2.0.0FetchContent consumer checked out the release commit and ran successfully.See benchmark evidence for measured Preview.3/Preview.4 comparisons and their limitations. Preview.5 did not replace the captured timing data or claim a universal speedup.
Active post-2.0 technical debt
Persistence and optional scope
Stable v2.0.0 preserves canonical display parsing and a versioned, sortable LK1 representation of one Path coordinate. It does not provide whole-Tree or caller-item serialization, permanent item IDs, fixed-size ranks, distributed replica identity, or CRDT convergence. Incompatible future external keys require a new format version, not reinterpretation of LK1.
Package-manager recipes, a public custom allocator, alternative index architectures, compact key variants, and specialized sorting optimizations remain optional work requiring separate justification. They are not part of stable v2.0.0.
Next decision point
No v2.1 or V3 scope is committed. Future work should be selected from evidence about full-rebuild cost, rigorous operation bounds, comparator-invariant API ergonomics, movement helpers, and external application usage. These open items were not prerequisites for stable v2.0.0.
References