diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index da2bca7..8478588 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -1,7 +1,8 @@ # Consolidated Audit Review -Status: initial scope selected; efficiency and structural-refactoring scope -remain under review. Implementation has not begun. +Status: initial scope and four localized efficiency improvements selected; +collection-policy and structural-refactoring scope remain under review. +Implementation has not begun. Consolidated: 2026-10-25. Baseline: `ecd5d5d`. This document consolidates nine sequential audits for maintainer review. It owns @@ -20,8 +21,8 @@ product fixes. The 35 original numbered findings map to 31 review entries after deduplication and integration of related test work. All findings remain unresolved; the -[settled scope decision](#oq-1-what-should-the-first-implementation-scope-include) -identifies the selected work. OQ-2 and OQ-3 remain open. +[settled scope decisions](#settled-scope-decisions) identify the 25 selected +entries. OQ-3 remains open, covering E01/E02 and the four broader refactors. Their medium/low priorities retain the original assessments; those labels do not imply severity certification or implementation order. IDs remain stable as work is selected or completed. @@ -908,38 +909,53 @@ boundaries. Delivering defects first and cleanup separately would reduce the initial review surface, but would retain redundant work and revisit those boundaries. The combined approach is selected. -The six efficiency candidates and four broader structural refactors remain -unselected pending OQ-2 and OQ-3. This decision does not select new public behavior -or establish an implementation sequence. - -## Open Questions +Efficiency and broader structural choices are addressed separately below. This +decision does not select new public behavior or establish an implementation +sequence. ### OQ-2. Which Efficiency Candidates Should Accompany Remediation? -**Recommendation:** consider E04/E05 as narrow local improvements, and A05/F08 -as lower-priority options after their correctness/diagnostic boundaries are sound. -Evaluate E01/E02 together with E03 before committing to a policy-state redesign: -their distinct scaling cases need preserved acceptance even if they share an -implementation. These candidates have source-level evidence of avoidable work, -but no new measured speedup claim. +**Settled:** include the four localized efficiency improvements below. Decide +E01/E02 together with collection-policy preparation and evidence ownership (E03) +under OQ-3; those two efficiency candidates remain unselected. -**Alternative:** defer all six efficiency candidates until representative consumer -profiling establishes their practical cost. This concentrates the first effort -on correctness and cleanup, at the cost of retaining demonstrated growth patterns. -It does not block C02's availability fix or A04/D01's enforcement of existing -resource budgets. Broader experiments in `future.md` remain separately deferred. +| Selected improvement | Scope and dependency | +| --- | --- | +| E04: tier-history projection lookups | Reuse a local lookup index or equivalent traversal while preserving authored coordinates and projection evidence. | +| E05: compound identity restoration | Avoid repeated mapping scans while preserving child identity, mapping order, and detached nodes. | +| A05: dynamic-type eligibility reuse | Reuse only completed successful checks within the operation, after A02 repairs descriptor construction failure state. | +| F08: secret-failure location lookup | Include at lower priority; prepare lookup state lazily so successful loads avoid unnecessary indexing. | + +Together with OQ-1, this selects 25 review entries. These local changes address +source-demonstrated repeated work without requiring public APIs, persistent +caches, or a new architectural model. Preserve their behavioral acceptance +cases and keep implementation proportionate. E01/E02 involve policy retirement +timing and mutable ownership, so their scope belongs with the E03 discussion. + +Deferring all six until consumer profiling was considered. That would reduce +initial scope and avoid optimizing uncommon workloads, but would retain known +growth patterns with relatively direct remedies in the four selected cases. +The selected approach does not promise a measured startup improvement; practical +benefit depends on configuration shape and workload. Broader experiments in +[future.md](future.md#3-performance-experiments) remain deferred. C02's availability +fix and A04/D01's existing-budget enforcement remain selected independently. + +## Open Questions ### OQ-3. How Much Structural Refactoring Should Be Selected? F01's removal of the test-only protocol is already selected under OQ-1. +OQ-2 leaves E01/E02's policy retirement and copying improvements for this decision, +alongside E03's policy preparation and evidence responsibilities. Their distinct +scaling cases must remain visible even if implemented together. **Recommendation:** assess active acquisition handoffs (F02) and policy/evidence -ownership (E03) with their affected fixes before selecting a wider extraction. Leave glob -entry extraction (C03) and transport simplification (F07) optional unless a -concrete design reduces concepts and clarifies ownership. +ownership (E03), including E01/E02, with their affected fixes before selecting a +wider extraction. Leave glob entry extraction (C03) and transport simplification +(F07) optional unless a concrete design reduces concepts and clarifies ownership. -**Alternative:** include all four structural refactors in the same effort for a -more uniform maintenance result. This offers broader readability improvements +**Alternative:** include all four structural refactors alongside E01/E02 in the +same effort for a more uniform maintenance result. This offers broader readability improvements but increases review scope and the chance of moving complexity rather than removing it. Neither approach calls for a new public API, generic framework, or changes to the established configuration model.