# Audit Remediation Roadmap Status: target accepted; completed execution is recorded in the historical plan at `bb5540b:docs/roadmap/implementation.md`. Prepared: 2026-10-25. Planning baseline: `e1e94ee`. This roadmap describes the target state and related work for the 29 entries selected in the [consolidated audit review](audit.md#settled-scope-decisions). It is intended for maintainers reviewing the remediation's scope and architecture. ## Document Ownership - [audit.md](audit.md) owns finding IDs, original evidence, detailed remedies and acceptance cases, and the settled scope decisions. Its evidence has not been independently reproduced by writing this roadmap. - This document owns the combined target state, work areas, and design intent. Finding IDs below provide traceability without repeating the full audit inventory. - The historical implementation plan at `bb5540b:docs/roadmap/implementation.md` records concrete stages, private implementation choices, edits, validation commands, and completion evidence. The [configuration contract](../config.md), public Go declarations, and [architecture policy](../policy/architecture.md) remain the owners of behavior and guarantees. Update their applicable implementation documentation when work lands; this planning document does not redefine their contracts. ## Current Baseline And Targeted End State The existing loading model remains the foundation. Public loading APIs delegate to the shared engine lifecycle; acquisition retains source scopes for composition, then precedence, inheritance, decoding, CLI overrides, application resolution, secret lookup, and validation produce a detached result with inspection metadata. The [component overview](../internal/overview.md) describes the current owners. The audits identify failures at particular traversal, lifetime, error, and accounting boundaries, alongside redundant representations and repeated work. The target is to repair those boundaries and simplify their implementation while preserving ConfigKit's public API and configuration model. | Current gap | Targeted outcome | | --- | --- | | Recursive descriptors can fail to terminate, failed dynamic builds can leave partial state, and slice aliases can be mistaken for cycles. | Traversal terminates for the reported cases, failed construction leaves reusable state valid, and supported acyclic values remain accepted. | | Callback and owned-root cleanup can be skipped during panic unwinding; directory errors lose their failure phase. | Cleanup follows the lifetime of each owned resource, and selected-directory failures retain the information needed for correct error handling. | | Finite symlink dependencies can be expanded repeatedly. | Completed dependencies are reused within a resolution while active cycles remain detectable. | | Projection reservations and published history can escape existing accounting. | Existing budgets govern the relevant allocations and complete retained document graph. | | Collection-policy work repeatedly scans or copies unrelated state. | Policy preparation, application, and retained evidence have clear ownership, with work localized to affected policy. | | Acquisition has redundant paths and difficult handoffs; several private representations have no production consumer. | Production paths and their tests share the active protocol, with cohesive handoffs and unused representations removed. | | Some lookups repeat full scans, and some tests assert incidental representation or miss meaningful mutations. | Local indexing avoids the identified repeated work, and tests protect observable contracts at useful boundaries. | This is a bounded remediation effort, not a redesign of configuration semantics. Correcting erroneous acceptance, rejection, cleanup, or diagnostics in the reported cases restores existing contracts. It does not select new loading APIs, configuration options, limits, background work, or persistent caches. ## Selected Work The following areas account for all 29 selected entries. Detailed examples and acceptance cases remain with their linked audit group. ### 1. Safe Typed-Value Traversal And Descriptor Reuse Selected entries: **A01, A02, A03, A04, A05** in [schema and typed values](audit.md#a-schema-and-typed-values). Make pointer-only descriptor traversal terminate in decoding and path resolution, while preserving supported null values and ordinary recursive structures. Make dynamic descriptor construction transactional: a failed build must not leave partial descriptors available to subsequent operations. Staging successful additions or rolling back the complete failed addition set are implementation choices; both must handle recursive references and preserve prior valid entries. Correct active-path cycle detection to distinguish finite slice views sharing storage from actual cycles. Keep detachment and nil/empty behavior intact across the callers that share this traversal machinery. Enforce existing projection budgets before large container reservations. Include map-key materialization and overflow-safe lower-bound checks in the review; a check after the reservation does not address the reported failure. This work does not introduce a general heap limit or reject large containers independently of existing budgets. Dynamic-type eligibility reuse depends on safe descriptor construction and retains completed successful checks within the value operation. Keep failure diagnostics specific to their current path and distinguish completed results from traversal visits. This removes repeated descriptor-graph walks without a cross-load cache. ### 2. Callback, Filesystem, And Dependency Lifetimes Selected entries: **B01, B02** in [callback lifetime](audit.md#b-callback-and-filesystem-lifetime) and **C01, C02** in [filesystem traversal](audit.md#c-import-selection-and-link-resolution). Tie callback-context deactivation to the callback invocation with deferred cleanup so it runs on normal return and panic unwinding. Independently give the owned import root a deferred cleanup fallback. Preserve normal close-error handling, caller ownership, and propagation of the original callback panic. Fixing either state lifetime or handle lifetime does not fix the other. Preserve the phase of a directory failure. A genuinely absent directory before successful opening remains subject to existing permissiveness rules; a later read or close failure must not be treated as absence. Apply this distinction to both supported directory-reading paths. Strengthen the shared filesystem tests to check each handle's closure and structured, non-disclosing diagnostics, including partial reads and failures masked by another successful directory. Do not change regular-file close-error policy as a side effect. Avoid repeatedly expanding completed finite symlink dependencies in both host and native filesystem resolution. Use operation-local memoization of completed targets, or an equivalent dependency evaluation, with keys that respect the resolution namespace. Keep active-path cycle detection separate from completed work. Preserve containment, supported finite reuse, and existing host-path semantics. The fix must work for directory and glob selection without a new arbitrary traversal cap or changed symlink defaults. ### 3. Retained History And Combination Evidence Selected entries: **D01, D02, D03, D04** in [history and retained state](audit.md#d-retained-history-and-unused-evidence). Remove the unconsumed override-result pre-CLI copy and the unqueried published structural-input copy. Preserve the separate pre-CLI state used by active replay and the structural input still used before publication for metadata and secret classification. Remove unused combination-evidence members and the work needed solely to produce them, retaining projections, mappings, origins, and snapshots that have active consumers. With retained roots clarified, enforce the existing history allowance against the complete graph published through inspection, including replay and inheritance state and publication-created copies. Count shared nodes once by pointer identity; distinct retained copies still consume the allowance. Account for required copies before creating them where practical. Removing an unused tree alone does not resolve the accounting omissions. Keep required before/after evidence and existing inspection behavior. Validate the complete publication path with small controlled allowances, including the interaction of CLI, resolution replay, and inheritance, rather than relying only on tests of an isolated counting helper. ### 4. Collection-Policy Preparation And Application Selected entries: **E01, E02, E03** in [collection policy and projection](audit.md#e-collection-processing-and-efficiency). Distinguish the existing policy state used for lookup, changes introduced by an incoming tier, and evidence retained by the assembly. Prepare incoming claims and declarations against read-only lower state, then apply the owned changes at the appropriate combination boundary. Avoid copying every unrelated policy for small tiers and scanning all policies for each independent replacement. Use a semantic-path index, localized updates, or equivalent bounded lookup to find affected policy. Preserve retirement timing, policy established by the incoming contribution, pending declarations, persistent explicit modes, and nested record ownership. Copying remains appropriate wherever mutable ownership requires it. Removing only one duplicate clone or shortening a function does not address the identified growth patterns. Clarify preparation, evidence application, and finalization responsibilities. Share straightforward history-descriptor translation where useful; evaluate shared record-selection logic while keeping overlay and inheritance origin and mode lifetimes distinct. Retain the common sequence-combination owner. This work does not call for a generic merging framework. ### 5. Active Acquisition Handoffs And Private Cleanup Selected entries: **F01, F02, F03, F04, F05, F06** in [acquisition, cleanup, and test quality](audit.md#f-remaining-maintenance-and-test-improvements). Remove the test-only eager acquisition mode so acquisition retains scopes through the active production protocol. Tests that need composition should invoke the actual composition boundary explicitly. Retire the parallel test-only import parser and route relevant fixtures through the active directive parser or the appropriate declaration boundary, retaining malformed-input coverage. Clarify active acquisition and coordinator handoffs around cohesive tasks: parsed-input directive/version handling, standalone placement, and repeated tier application/projection. Use explicit inputs and results consistent with existing state owners. Extracting helpers that continue to share surrounding mutable state does not establish a clearer handoff. Preserve ordinary/layered differences, overlay and diff behavior, source identity, callback timing, diagnostics, and accounting scopes. Remove the disconnected root record-clone family, uncalled engine helpers, and unread private transport/result members identified in the audit. Reconfirm references on the implementation baseline, including function values and relevant build configurations. Preserve live conversion paths and validation side effects; the audit's absence of field reads is not a general rule for deleting state. Replace meaningful ownership coverage through the public boundary before removing tests that only exercise disconnected helpers. ### 6. Local Lookup Improvements Selected entries: **E04, E05** in [collection policy and projection](audit.md#e-collection-processing-and-efficiency) and **F08** in [secret-failure lookup](audit.md#f08-index-secret-failure-location-queries-lazily). Reuse a local document lookup or equivalent traversal for tier-history projection instead of rescanning wide mappings for each sequence. Preserve authored coordinates, sparse projections, and evidence ownership. Restore compound identity fields using indexed mapping positions and membership checks rather than rescanning child and merged mappings for every field. Preserve child-authored values and locations, mapping order, and detached nodes. Build secret-failure location lookup state lazily when failures need it. Preserve all diagnostics, nearest-location fallbacks, and confidentiality; successful loads should not incur an unnecessary index merely to support failure reporting. These changes address specific repeated work and do not promise a measured startup improvement. ### 7. Tests That Protect The Intended Behavior Selected entries: **F09, F10, F11, F12** in [acquisition, cleanup, and test quality](audit.md#f-remaining-maintenance-and-test-improvements), in addition to the regression coverage attached to each reported defect. Cover historical-path enumeration through the public API, including removed paths, queryability, ordering, and detached returned slices. Use those assertions to replace private representation checks where they address the same risk. Strengthen fuzz detachment checks by mutating existing descendants or in-length elements, so spare capacity cannot hide aliases. Replace exact filesystem stat call sequences with observable candidate ordering and meaningful failure selection, retaining relevant assertions such as not opening excluded inputs. Consolidate facade scaffolding around public construction, loading, errors, ownership, and lifecycle behavior. Preserve distinct integration risks and reader-byte snapshot coverage. Existing coverage percentages or a desired test count are not acceptance criteria for this work. ## Implementation Plan The historical implementation plan at `bb5540b:docs/roadmap/implementation.md` defines the sequential, Luna-scoped stages and their dependencies, including coordinated changes to descriptor state, history ownership/accounting, collection policy, acquisition, and replacement public coverage. It also records validation commands and the complete finding-to-stage map. The audit remains the owner of original evidence and detailed acceptance cases. ## Validation And Completion Validation follows the audit's detailed acceptance cases and the [testing policy](../policy/testing.md). For fatal or hanging regressions, use bounded subprocesses; for budget cases, use small controlled limits. For symlink expansion and repeated lookup work, prefer bounded operation evidence and algorithm review over timing thresholds. Use real filesystem fixtures where filesystem semantics matter and narrow fault injection for read/close failures. State platform limits. Applicable development checks come from the [development guide](../development.md), including appropriate race coverage for changed ownership and lifetime boundaries. The historical implementation plan owns their execution. Existing audit results are baseline evidence, not validation of the eventual changes. No performance benchmark campaign is required by this roadmap, and no new benchmark results are claimed. Completion means all 29 selected findings have implementation and acceptance evidence, the affected public behavior remains consistent with its contracts, and canonical internal documentation describes the resulting owners. The historical implementation plan records execution status without duplicate progress inventories. Retire completed planning records under the normal documentation lifecycle. ## Scope Boundaries And Decision Status All three audit scope questions are settled. No significant architectural or product decision remains open for this roadmap. The historical implementation plan records private design choices and sequencing, subject to the acceptance cases above. If that work exposes a need to change a public contract, bring the specific decision back for review rather than treating it as an implicit part of remediation. The glob preparation refactor (C03) and wider facade transport simplification (F07) have since been selected in the [internal-boundary roadmap](internal-boundaries.md). Other deferred features, clone-traversal redesign, and broader performance experiments remain outside this effort. Keep existing ownership boundaries and loading APIs; no ADR or architecture-policy change is proposed by this roadmap.