eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Settle audit refactoring scope and defer follow-up work

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-25 20:17:47 +00:00
parent 176e9a5d90
commit e1e94eeec7
4 changed files with 126 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
docs/roadmap/audit.md
View File

@@ -1,15 +1,15 @@
# Consolidated Audit Review
Status: initial scope and four localized efficiency improvements selected;
collection-policy and structural-refactoring scope remain under review.
Implementation has not begun.
Status: scope settled; 29 entries selected for implementation planning.
Two refactors are deferred to `future.md`. Implementation has not begun.
Consolidated: 2026-10-25. Baseline: `ecd5d5d`.
This document consolidates nine sequential audits for maintainer review. It owns
their open findings, supporting evidence, proposed remedies, and relationships.
It is not an implementation plan, an acceptance of every recommendation, or a
new set of release gates. The [configuration contract](../config.md), public Go
declarations, and [architecture policy](../policy/architecture.md) continue to
The settled decisions select the remediation roadmap's scope; this document is
not a staged implementation plan or a new set of release gates. The
[configuration contract](../config.md), public Go declarations, and
[architecture policy](../policy/architecture.md) continue to
own behavior and guarantees.
There are nine distinct reported defects: four from correctness, three from
@@ -21,8 +21,9 @@ 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 decisions](#settled-scope-decisions) identify the 25 selected
entries. OQ-3 remains open, covering E01/E02 and the four broader refactors.
[settled scope decisions](#settled-scope-decisions) identify the 29 selected
entries. C03 and F07 have moved to `future.md`, with reference entries retained
here for traceability. All three scope questions are settled.
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.
@@ -102,12 +103,12 @@ of the groups below is for navigation, not an execution sequence.
| A02 and A05 | Make descriptor construction safe before reusing successful dynamic-type eligibility results. |
| B01 and B02 | Panic cleanup must close callback state and the owned host root independently. Neither fix substitutes for the other. |
| C01 and its filesystem tests | Strengthen error/handle assertions while adding failure-phase regressions, using one shared test owner. |
| C02 and C03 | Link expansion correctness is independent of optional glob readability extraction. Do not make the latter a prerequisite. |
| C02 and deferred C03 | Complete link expansion remediation independently; reconsider glob readability extraction afterward through `future.md`. |
| D01, D02, and D03 | Remove the confirmed unused copies, then account for the complete retained graph. Removing one unused tree does not fix the remaining omissions. |
| E01, E02, and E03 | Consider policy-state costs and responsibility boundaries together, but preserve separate scaling and behavioral acceptance cases. |
| E01, E02, and E03 | Address policy-state costs and responsibility boundaries together, preserving separate scaling and behavioral acceptance cases. |
| F01 and F02 | Removing the test-only acquisition mode does not by itself simplify active lifecycle handoffs. |
| F04, F09, and F12 | Replace useful facade ownership/query coverage before deleting disconnected or representation-coupled scaffolding. |
| F05 and F07 | Removing unused placement bridges is a bounded cleanup independent of the wider transport refactor. |
| F05 and deferred F07 | Remove unused placement bridges in this scope; reconsider wider transport simplification afterward through `future.md`. |
## A. Schema And Typed Values
@@ -335,21 +336,9 @@ outside-root target is needed, and accidental graphs can cause the same work.
### C03. Separate Glob Entry Preparation From Traversal
Type: optional refactor. Priority: medium. Source: complexity 4.
**Problem and evidence.** The patterned branch of `selectGlobImportCandidates`
in [glob.go](../../internal/engine/glob.go) interleaves component traversal and
union/sorting with hidden/match rules, lexical/access paths, containment, links,
directory eligibility, namespace differences, labels, and candidate construction.
Directory selection already has a named entry-preparation operation.
**Recommendation and acceptance.** Consider a glob-specific preparation helper
returning an admitted candidate, ordinary skip, or diagnostic. Keep literal
segments, component advancement, union/sorting, exclusions, and requiredness in
the selector. Preserve inspection/error order, budgets, native spelling, and
selected-file validation. Share low-level facts only where semantics agree;
no general visitor framework, discovery-algorithm change, or caching is implied.
C01/C02 can be fixed independently of this readability change.
Deferred under OQ-3. The evidence, proposed scope, and remaining questions now
belong to [future work](future.md#1-separate-glob-entry-preparation-from-traversal),
for consideration after this roadmap's selected work is complete.
## D. Retained History And Unused Evidence
@@ -487,7 +476,7 @@ deferred public metadata-copy experiment.
### E03. Clarify Policy Preparation And Merge Evidence Application
Type: optional refactor. Priority: medium. Source: complexity 3.
Type: selected refactor. Priority: medium. Source: complexity 3.
**Problem and evidence.** [overlay.go](../../internal/engine/overlay.go) combines
claim/declaration preparation, operation resolution, callbacks, diagnostics,
@@ -562,7 +551,7 @@ loading workflows or imply that every nil-state/directive context is unused.
### F02. Clarify Active Acquisition And Coordinator Handoffs
Type: optional refactor. Priority: medium. Source: complexity 2.
Type: selected refactor. Priority: medium. Source: complexity 2.
**Problem and evidence.** `acquireInput` in
[acquisition.go](../../internal/engine/acquisition.go) combines discovery, parsing,
@@ -664,24 +653,10 @@ separate analysis.
### F07. Simplify Redundant Facade-To-Engine Transport
Type: optional refactor. Priority: low. Source: complexity 5, excluding F05's
bounded placement-bridge removal.
**Problem and evidence.** Root conversion, engine facade-transport records, engine
private defaults, decorators, and load normalization provide several mapping
sites for the same import-default fields. Placement likewise uses a record plus
a setter-style bridge. See [conversion.go](../../conversion.go),
[lifecycle.go](../../lifecycle.go), [layered.go](../../layered.go),
[import_spec.go](../../internal/engine/import_spec.go), and
[destination.go](../../internal/engine/destination.go).
**Recommendation and acceptance.** Consider one engine representation for
import-default input and straightforward construction on existing option/input
records, only if this reduces total concepts and mapping sites. Keep domain-rule
and ownership conversions and separate registration compilation. Preserve
root-owned types/signatures, both loading APIs, invalid-enum validation,
nil-versus-empty patterns, and pointer/slice snapshots. No universal request DTO,
generated mapper, public internal aliases, or adapter framework is proposed.
Deferred under OQ-3. The evidence, proposed scope, and remaining questions now
belong to [future work](future.md#2-simplify-redundant-facade-to-engine-transport),
for consideration after this roadmap's selected work is complete. F05's bounded
removal of unused placement bridges remains selected.
### F08. Index Secret-Failure Location Queries Lazily
@@ -814,7 +789,7 @@ Selected stable Kahn ordering, deterministic sorting, exact numeric identity,
and the expressly selected registration-overlap check are not reconsidered here.
Required detached copies and genuinely expanding output remain legitimate costs.
The broader replay, metadata-handoff, cross-load schema-cache, and contributor-
trace experiments stay in [future.md](future.md#3-performance-experiments).
trace experiments stay in [future.md](future.md#5-performance-experiments).
Local fixes and removal of proven unused work do not select those experiments.
## Validation Approach For Selected Work
@@ -915,9 +890,9 @@ sequence.
### OQ-2. Which Efficiency Candidates Should Accompany Remediation?
**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.
**Settled:** include the four localized efficiency improvements below. E01/E02
are addressed separately with collection-policy preparation and evidence
ownership (E03) under the settled OQ-3 decision.
| Selected improvement | Scope and dependency |
| --- | --- |
@@ -937,25 +912,36 @@ 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
[future.md](future.md#5-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.
**Settled:** select E01, E02, E03, and F02. Defer C03 and F07 to the first two
entries of [future.md](future.md) for consideration after the rest of this roadmap
is complete. F01's removal of the test-only protocol remains selected under OQ-1.
**Recommendation:** assess active acquisition handoffs (F02) and policy/evidence
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.
| Selected work | Scope |
| --- | --- |
| E01/E02/E03: collection-policy retirement, copying, and evidence ownership | Address the related costs and preparation/application boundaries together, retaining distinct scaling and behavioral acceptance cases. |
| F02: active acquisition and coordinator handoffs | Extract cohesive repeated operations with clear inputs/results while preserving visible phase order and ordinary/layered differences. |
**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.
For collection policy, distinguish read-only existing state, policy affected by
incoming declarations or replacements, and the changes/evidence retained by the
assembly. Preserve retirement timing, newly established policy, explicit-mode
persistence, and nested record ownership. A smaller function or fewer copies
alone does not establish success. For acquisition, moving blocks into helpers
that continue sharing mutable surrounding state would not clarify the handoff;
keep the existing loading model and named responsibilities.
The selected combination offers a focused improvement in efficiency and
maintainability at active ownership boundaries. Including C03/F07 now would
broaden review for more modest readability benefits; neither is necessary for
the selected fixes. They remain plausible follow-up work, not rejected proposals.
Deferring all structural work would reduce immediate change scope but retain the
policy inefficiencies and difficult acquisition handoffs. No new public API,
generic framework, or configuration semantics are selected.
Together, OQ-1 through OQ-3 select 29 entries. All scope questions are settled;
the next step is to prepare the implementation plan with sequencing and focused
validation. No implementation has been performed by these planning decisions.

80
docs/roadmap/future.md
View File

@@ -1,12 +1,76 @@
# Potential Future Features
# Potential Future Work
This document lists potential enhancements for consideration in future ConfigKit
releases. Entries are not accepted contracts, implementation plans, or release
commitments. Adopting a candidate requires an explicit design decision and a
separate plan. Significant architectural exclusions and their rationale belong
This document lists potential enhancements and maintenance work for consideration
in future ConfigKit releases. Entries are not accepted contracts, implementation
plans, or release commitments. Adopting a candidate requires an explicit design
decision and a separate plan. Significant architectural exclusions and their rationale belong
in ADRs; this document does not maintain a list of rejected proposals.
## 1. Recursive body merging for identified records
## 1. Separate glob entry preparation from traversal
Status: deferred; consider after the selected work in the
[consolidated audit roadmap](audit.md) is complete. Audit ID: C03.
Original source: complexity finding 4 at
`ecd5d5d:docs/roadmap/complexity.md`; assessed priority: medium.
The patterned branch of `selectGlobImportCandidates` in
[glob.go](../../internal/engine/glob.go) interleaves component traversal and
union/sorting with hidden/match rules, lexical/access paths, containment, links,
directory eligibility, namespace differences, labels, and candidate construction.
Directory selection already has a named entry-preparation operation.
Consider a glob-specific preparation helper returning an admitted candidate,
ordinary skip, or diagnostic. Keep literal segments, component advancement,
union/sorting, exclusions, and requiredness in the selector. Preserve inspection
and error order, budgets, native namespace spelling, and selected-file validation.
Share low-level filesystem facts only where semantics agree; the proposal does
not require a general visitor framework, discovery-algorithm change, or caching.
The selected directory-failure and link-resolution fixes do not depend on this
readability refactor.
### Questions to resolve before implementation
- After the selected import fixes, does the entry-preparation boundary still
reduce complexity and clarify lexical versus canonical path handling?
- Which low-level operations can be shared with directory selection while
keeping their distinct admission and traversal rules explicit?
- Can existing behavioral tests protect ordering, diagnostics, and resource
accounting without assertions about the new private helper structure?
## 2. Simplify redundant facade-to-engine transport
Status: deferred; consider after the selected work in the
[consolidated audit roadmap](audit.md) is complete. Audit ID: F07.
Original source: complexity finding 5 at
`ecd5d5d:docs/roadmap/complexity.md`; assessed priority: low. The unused placement
bridge removal is separately selected as audit F05.
Root conversion, engine facade-transport records, engine private defaults,
decorators, and load normalization provide several mapping sites for the same
import-default fields. Placement likewise uses a record plus a setter-style
bridge. See [conversion.go](../../conversion.go),
[lifecycle.go](../../lifecycle.go), [layered.go](../../layered.go),
[import_spec.go](../../internal/engine/import_spec.go), and
[destination.go](../../internal/engine/destination.go).
Consider one engine representation for import-default input and straightforward
construction on existing option/input records, only if this reduces total
concepts and mapping sites. Keep domain-rule and ownership conversions and
separate registration compilation. Preserve root-owned types/signatures, both
loading APIs, invalid-enum validation, nil-versus-empty patterns, and pointer/slice
snapshots. A universal request DTO, generated mapper, public internal aliases,
or adapter framework is not part of this proposal.
### Questions to resolve before implementation
- After unused bridges and fields are removed, does the remaining transport
duplication still justify a refactor?
- Which representations can be combined without losing ownership snapshots,
presence distinctions, validation, or root-owned public types?
- Would the proposed construction surface reduce total concepts and conversion
sites, rather than relocate the same work behind another abstraction?
## 3. Recursive body merging for identified records
Status: deferred. The implemented
[collection policy](../config.md#strict-document-composition) uses `upsert` to
@@ -20,7 +84,7 @@ presence and ordering, and how provenance, history, sensitivity, and resource
context follow partially retained records. Any change requires a new decision and
implementation plan; this entry does not alter current upsert behavior.
## 2. Required version declarations for selected sources
## 4. Required version declarations for selected sources
Status: deferred. PromptKit requested a way to require version declarations on
a selected subset of source files while permitting other fragments to omit them.
@@ -56,7 +120,7 @@ compatible version or replace final configuration validation.
behavior for absent optional inputs and preserve source-local diagnostics,
inspection evidence, and existing sensitivity handling.
## 3. Performance experiments
## 5. Performance experiments
Status: deferred pending evidence. The completed performance audit identified
four internal optimization candidates for separate investigation: