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

Settle retaining the public loading APIs

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 23:07:09 +00:00
parent 26771dc03e
commit de7513d488
1 changed files with 30 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/roadmap/consolidation.md
View File

@@ -15,10 +15,10 @@ consumer workflows. Reducing a function's line count is useful only when it
serves those outcomes. serves those outcomes.
The review considered public API consolidation as well as internal extraction. The review considered public API consolidation as well as internal extraction.
The recommended scope retains the existing simple and layered loading APIs, The settled public direction retains the existing simple and layered loading APIs,
consolidates their private translation and acquisition machinery, and removes consolidates their private translation and acquisition machinery, and removes
unused reverse inspection conversions. No public signature or configuration unused reverse inspection conversions. No public signature or configuration
semantic change is currently recommended. This is an assessment of the reviewed semantic change is planned in this effort. This is an assessment of the reviewed
consumer workflows, not a requirement to preserve every beta API in perpetuity. consumer workflows, not a requirement to preserve every beta API in perpetuity.
## Evidence And Baseline ## Evidence And Baseline
@@ -130,19 +130,21 @@ separate overlay filesystem. Ordinary overlay context follows its selected
source, whereas layered overlay context is independently specified. These are source, whereas layered overlay context is independently specified. These are
observable conventions, not interchangeable forwarding spellings. observable conventions, not interchangeable forwarding spellings.
**Recommendation:** retain `Load`, `LoadLayered`, `Options`, `LayeredOptions`, **Decision (OQ-1, settled):** retain `Load`, `LoadLayered`, `Options`, `LayeredOptions`,
`Input`, and `Underlay`. Remove repeated translation and option reconstruction `Input`, and `Underlay`. Remove repeated translation and option reconstruction
behind them. Keep common application rules in `Definition`; do not require behind them. Keep common application rules in `Definition`; do not require
applications to build a runtime loader or manually coordinate phases. applications to build a runtime loader or manually coordinate phases.
A single public request type could place main input, underlays, and common A single public request type could place main input, underlays, and common
options together. It would reduce duplicated option fields and make promotion options together. It would reduce duplicated option fields and make promotion
from ordinary to layered loading more uniform. However, a sole request-based from ordinary to layered loading more uniform. A convenience entry could preserve
entry would add setup to the simplest call; retaining a convenience entry would the simplest call. Such a design would still need to resolve the existing
still leave two call forms. Either approach must explicitly resolve the existing overlay-context differences and demonstrate a clearer consumer model. The
overlay-context differences. The maintained examples do not yet show enough maintained examples do not show enough consumer benefit to justify that redesign
consumer benefit to justify that redesign. This recommendation is based on the in this effort. Retaining the current APIs accepts some duplicated public option
resulting API, rather than the amount of refactoring needed to achieve it. fields and setup changes when adopting underlays; internal consolidation and
clearer guidance address the observed maintenance needs. The decision is based on
the resulting API, rather than the amount of refactoring needed to achieve it.
### Preserve Useful Convenience And Ownership Boundaries ### Preserve Useful Convenience And Ownership Boundaries
@@ -377,7 +379,7 @@ the boundary rather than simplify it.
The proposed work spans private engine code, private root-facade conversions, The proposed work spans private engine code, private root-facade conversions,
affected tests, consumer guidance, and implementation documentation. Under the affected tests, consumer guidance, and implementation documentation. Under the
recommended answer to [OQ-1](#oq-1-should-the-public-loading-apis-change-in-this-effort), settled answer to [OQ-1](#oq-1-should-the-public-loading-apis-change-in-this-effort),
preserve public types/signatures and the behavior owned by the current contracts, preserve public types/signatures and the behavior owned by the current contracts,
including: including:
@@ -400,8 +402,8 @@ The recommendation fits the existing architecture policy and ADRs 0006,
0015, 0017, 0018, and 0019. It needs no new architectural ownership decision or 0015, 0017, 0018, and 0019. It needs no new architectural ownership decision or
policy revision merely to introduce private helpers. Update the component policy revision merely to introduce private helpers. Update the component
overview and import internals when code moves. Accepted ADR decision content overview and import internals when code moves. Accepted ADR decision content
remains unchanged. If review selects a materially different public loading model, remains unchanged. A public loading-model redesign is outside this effort's
assess its behavioral consequences explicitly before implementation. settled scope.
Pre-1.0 public changes are possible under the [release policy](../policy/release.md), Pre-1.0 public changes are possible under the [release policy](../policy/release.md),
but they must have a consumer benefit and documented impact. This draft does not but they must have a consumer benefit and documented impact. This draft does not
@@ -479,33 +481,27 @@ Completion requires reviewable evidence that:
the resulting implementation. Current contracts continue to own behavior. the resulting implementation. Current contracts continue to own behavior.
Private type/helper names, final file splits, and exact stage boundaries belong Private type/helper names, final file splits, and exact stage boundaries belong
in the implementation plan. The questions below concern the public direction and in the implementation plan. The remaining question concerns the scope of clone
scope of the work. No additional feature semantics are needed to carry out the cleanup. No additional feature semantics are needed to carry out the recommended
recommended refactors. refactors.
## Open Questions ## Settled Decisions
The target above follows the recommended answers below, pending discussion.
Existing behavior and accepted architectural boundaries remain the baseline;
routine private design choices can be settled in the implementation plan.
### OQ-1: Should The Public Loading APIs Change In This Effort? ### OQ-1: Should The Public Loading APIs Change In This Effort?
**Recommendation:** retain `Load`/`Options` and `LoadLayered`/`LayeredOptions`, **Settled:** retain `Load`/`Options`, `LoadLayered`/`LayeredOptions`, `Input`, and
and consolidate their private inputs, conversions, and acquisition machinery. `Underlay`, including their existing overlay-context behavior. Consolidate their
The current simple call needs little setup, while layered loading makes input private inputs, conversions, and acquisition machinery, and improve consumer
groups and independent overlay context explicit. The maintained consumer examples guidance. The [consumer-facing target](#consumer-facing-target) records the
demonstrate useful roles for both. Better guidance and shared private machinery rationale and tradeoffs. This decision governs the consolidation effort; it does
address the observed duplication without adding public concepts. not establish a perpetual restriction on future API design.
**Alternative:** introduce one public request model for main input, underlays, ## Open Questions
and load-wide options, with a convenience entry for simple loading. This could
reduce repeated option declarations and make a consumer's move to layered loading OQ-2 remains open. The target above follows its recommended answer pending
more uniform. It is viable before 1.0, but needs concrete simple and advanced discussion. Existing behavior and accepted architectural boundaries remain the
examples to show an improvement, plus a deliberate choice about ordinary versus baseline; routine private design choices can be settled in the implementation
layered overlay-context behavior. It would expand this effort into public API plan.
design and consumer migration. If selected, revise the public target before
preparing the internal implementation plan.
### OQ-2: How Much Clone Cleanup Should This Effort Commit To? ### OQ-2: How Much Clone Cleanup Should This Effort Commit To?