LayerKeySort Mini — Post-v1.0.0 Roadmap and Technical Debt

Scope and verified baseline

Status reviewed on 2026-10-08. This is the active Mini-only roadmap, not a defect list for Full and not authorization to start a new release. Separate confirmed defects, evidence gaps, accepted costs, non-goals and optional proposals; do not mark planned work as completed.

Two independently implemented products share this repository:

• Full v4.0.0 Stable, published 2026-10-07 (GitHub UTC publication date), remains the repository-wide Latest. Full provides the complete ordering model, historical snapshots/export and advanced workflows. See the Full Release and Full active roadmap #3.
• Mini v1.0.0 Stable, published 2026-10-08 (GitHub UTC publication date), provides small local mutable orders. Mini Release; annotated tag mini-v1.0.0 resolves to 3f52798. Historical Full v1.0.0 is a different release.

Versions, public APIs, implementations and release histories remain independent. Mini must not depend on Full production sources. Product-line rules define the monorepo and separate v* / mini-v* tags. Embedded remains an uncommitted future idea, not an existing product or scheduled implementation.

Historical Full V1–V4 problem ledger #4 preserves its original historical entries. Do not put new Mini defects into that algorithmic ledger. Mini's existence does not resolve Full's allocator, block, snapshot/export, retained-history or real-application evidence costs.

Completed capabilities and traceable evidence

Accepted architecture costs

These are documented tradeoffs, not unresolved bugs merely because they exist:

• Arbitrary current-order comparison is O(n); no persistent ranks or index are maintained.
• Each occurrence has its own allocation, in addition to the order allocation.
• Pointer chasing limits locality; its actual workload impact requires measurement, not an assumed slowdown on every workload.
• Known-handle insertion/removal/movement and basic queries are O(1) structural work excluding allocator/system cost; traversal/destruction are O(n).
• No numeric-index random access. A consumer that maps positions to handles must account for its own mapping/traversal cost.

The performance/memory record is a qualified RC.1 baseline retained for unchanged Stable source: Windows x64 GCC 16.2.0 Release, one measured run at 128/2,048/32,768 occurrences, insertion/removal, known-handle movement, traversal, comparison and mixed workloads. The UTC wall clock may adjust; short times have quantization/scheduling/cache/allocator noise. It is not a cross-platform latency guarantee or a Full-versus-Mini superiority claim.

Measured private sizeof values on that ABI were order=24 and node=32 bytes, producing a struct-only estimate of 24 + 32n. Allocator metadata/size classes, fragmentation, reserved/resident pages, application payloads and consumer handle arrays are excluded. Actual allocator-inclusive memory remains an evidence gap, not a proven leak or justification for a pool.

Explicit non-goals

• Automatic sorting or comparator-managed ordering.
• Full snapshots, persistence/restore, immutable Group/Batch and advanced workflows.
• Numeric-index/random-access indexing.
• Automatic thread synchronization; callers synchronize shared mutable orders.
• Detection of freed/invalid handles or persistent business identity.
• Database transactions, storage engines or distributed/CRDT ordering.

Do not classify these as unfixed defects or silently promise them for 1.x. Never dereference or test a retired handle as if stale-pointer rejection were supported.

Priority 1 — Real editor integration and implementation-independent workload evidence

First consumer: Local Layer Order Workbench. Originally proposed in this issue on 2026-10-08, the command-line C17 consumer and its independent measurement tooling were subsequently implemented and merged via PRs #8, #9 and #15. A graphical renderer is not required for this bounded integration; real human sessions and representative downstream workloads are still unverified.

Boundaries and responsibilities

• Application owns layer objects, an occurrence-ID-to-live-handle map, command history and trace capture. Occurrence IDs are application identities; duplicate occurrences may reference the same layer object, and placeholders may have NULL payloads.
• Mini adapter uses only the public header and real library. Do not expose private nodes, change the frozen API, add an allocator extension or depend on Full production code.
• Start with a Mini consumer and independent ordered-array oracle. An optional separate Full adapter may replay the supported common explicit-order subset with documented mapping/normalization. Do not pretend complete product equivalence or route Full-only operations through Mini.
• Mini fits local live layer/task/playlist ordering without history/export requirements. Full fits additional managed ordering, historical snapshots/export/restore or batch workflows. Full-only scenarios must be reported separately; application-owned undo by reinsertion creates new live handles and is not Mini snapshot persistence.
• Exclude rendering, collaboration, database integration, persistent live handles, new release scheduling and library architecture changes from the first consumer.

Required commands and semantic trace

Support front/back/before/after insertion; removal; adjacent moves and moves across a measured distance; self/already-adjacent/endpoint no-ops; forward/reverse listing; and exact pair comparison. Include duplicate payload pointers and NULL placeholders.

Record each command as an implementation-independent event: sequence number, application occurrence IDs and optional payload ID/NULL, before/after anchor or endpoint, expected status and intended logical result. Record initial order, active size, move distance, traversal/comparison requests and removed-ID retirement. Do not log raw handle addresses as semantic identity. Preserve provenance: manually executed application session, explicitly scripted demonstration, or generated stress case; never relabel a synthetic replay as a real-user trace.

Failure handling must distinguish malformed application commands, supported library argument/foreign-order errors and allocation failure. Publish expected status precedence/output defaults from the contract. Exercise OOM through reproducible test-only instrumentation isolated from the shipped consumer if ordinary application runs cannot trigger it; disclose that method and never claim normal interactive sessions naturally covered OOM. Do not invent a public allocator hook. No failure may silently alter the application/library order or retire a still-live handle.

Current execution evidence (2026-10-14; additions after the original 2026-10-08 baseline)

• Phase 1 — Consumer integration: DONE. PR #8, merge commit 7f17331297e88618a71257ebc65b04cb6b4b8c25. Standalone C17 Workbench, public Mini API integration, independent array oracle, semantic replay, supported error/OOM instrumentation, duplicate/NULL payload and safe occurrence-ID retirement. Three authored script traces of 32/31/30 commands and a 23-command Codex-driven terminal session were executed; none is a human-operated user session.
• Phase 2 — Quantified consumer evidence: DONE. Consumer PR #9, merge 11ea341855b6350f111883c911ab15b7332a3038; separate Repo-owned evidence workflow PR #15, merge 51c011d4a6e20492ed52be0d8d6eb5b9f974cb8a. Twelve generated operation families at 16/128/2,048 active occurrences, independent correctness checks, 15 fresh-process measurement repeats, Windows/Linux timing/RSS evidence and Linux scoped allocation tracking; do not interpret generated work as real user distributions.
• Post-merge main evidence: 51c011d4a6e20492ed52be0d8d6eb5b9f974cb8a; Full CI, Mini CI, Workbench CI, and Linux/Windows measurement evidence all completed successfully at that SHA. Measurement artifacts are time-limited CI evidence, not permanent archival research data.
• Phase 3 — Genuine manual use: IN PROGRESS. Step 3.1 reconciles this issue and prepares Windows instructions. Step 3.2 still requires three distinct genuine human-operated terminal sessions, 20+ processed commands each, separately captured/replayed and actually reviewed. No such sessions have yet been verified. A human-terminal label is a user declaration, not identity authentication.
• Remaining evidence gaps: real human observations, representative downstream editor workloads, complete allocator metadata/fragmentation attribution. An independent Full adapter comparison is optional and not performed; no Full/Mini speed winner is asserted. No confirmed Mini v1.0.0 production defect follows from the present evidence. Stable Mini v1.0.0 / Full v4.0.0 source APIs and releases remain unchanged.

Acceptance checklist — evidence reconciled 2026-10-14

• Build/run instructions reproduce a real public-API consumer from the published Mini-only package, without Full sources; direct compilation and add_subdirectory integration work.
• At least three locally executed interactive sessions of 20+ commands each demonstrate create/reorder/delete, duplicate/NULL occurrences and recovery from legal errors. Store the actual command trace and provenance; no external-user adoption claim. Pending: existing three saved 32/31/30-command sessions are Codex-executed scripts, not human-operated sessions.
• After every mutating command, independent oracle and adapter agree on full forward/reverse occurrence sequence, size and endpoint results. Compare results are exactly -1/0/+1; enumerate all pairs for small cases and fixed sampled pairs for larger cases.
• Every required command, valid no-op, adjacent/distant move and error scenario has at least one explicit trace case. Retired IDs are removed from the live-handle map immediately; no freed handle is dereferenced. Reinsertion produces a new occurrence identity.
• Payload ownership is verified: Mini never frees business objects; shared pointers remain valid until the application releases them after all referencing occurrences are removed; NULL payloads are valid.
• Test-only OOM/recovery replay verifies insertion output defaults and unchanged sequence/ownership on failure; foreign-order probes use live handles from a second order. Test instrumentation and untriggered runtime cases are disclosed.
• Replays are deterministic and bounded: explicit fixtures at 16/128/2,048 active occurrences, fixed seeds where used, exact command counts and limits. Larger generated fixtures are labeled stress evidence; actual session size/mix is reported unchanged rather than inflated.
• Correctness runs use supported sanitizers; measurements use separate optimized, non-sanitized builds. Keep compiler/options, machine/OS, operation mix, active-size history and timing method. Run timing repetitions, report their distribution and retain raw results; account separately for library, oracle, application mapping and trace/UI work.
• If comparing adapters, replay the same common semantic input without changing it to favor either product. Document operation/status mapping, independently verify both results, and separate Full-only features and their cost. A comparison is optional; correctness and real semantics are mandatory. Optional, not exercised; no Full adapter comparison was performed.
• Report allocator/RSS measurements only with an actual stated method; keep structural estimates separate. End with supported use-case findings, observed bottlenecks/defects or absence of evidence, and explicit limitations rather than declaring a winner. Partial: actual RSS and scoped allocations were measured; human-supported use-case findings and complete allocator-overhead attribution remain pending.

The first decision gate is whether observed application operations expose a reproducible correctness/integration defect or a material measured cost. A command-line workbench demonstrates actual integration but still does not establish representative real-user editor distributions; collecting consented downstream traces remains a later evidence opportunity.

Version and maintenance decisions

• Do not immediately start Mini v1.1.0, or add features to create a version number.
• Do not replace the linked list to chase O(1) for every operation.
• Do not introduce pools, allocator APIs or additional indexes without a demonstrated workload need, maintenance cost and compatibility review.
• Do not mechanically transplant Full features into Mini.
• A reproducible supported-operation defect needs its own evidence and focused regression; an accepted cost needs measurement before optimization. Compatible improvements, if justified, receive a separate bounded proposal/version decision.
• Broader ABI/toolchain checks, statistical benchmarks and allocator-inclusive measurements are optional evidence improvements, not confirmed defects or release commitments.

Tracking and triage rules

No new confirmed blocking Mini defect is asserted by this record. This is an evidence-based summary of the published baseline, not proof of the absence of all defects.

For future entries record: category (confirmed defect / evidence gap / accepted tradeoff / non-goal / optional proposal), reproduction or source, affected product/version, user impact, status and next evidence/decision gate. Do not infer severity from headline complexity. Keep unrelated work, market-share estimates and speculative performance advantages out of the record.

Maintain the bidirectional link with Full roadmap #3; preserve Full historical ledger #4. No Mini entry changes the historical severity or resolution status of a Full entry.