diff --git a/docs/roadmap/consolidation.md b/docs/roadmap/consolidation.md index bafc93e..5613109 100644 --- a/docs/roadmap/consolidation.md +++ b/docs/roadmap/consolidation.md @@ -15,10 +15,10 @@ consumer workflows. Reducing a function's line count is useful only when it serves those outcomes. 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 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. ## 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 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 behind them. Keep common application rules in `Definition`; do not require applications to build a runtime loader or manually coordinate phases. A single public request type could place main input, underlays, and common options together. It would reduce duplicated option fields and make promotion -from ordinary to layered loading more uniform. However, a sole request-based -entry would add setup to the simplest call; retaining a convenience entry would -still leave two call forms. Either approach must explicitly resolve the existing -overlay-context differences. The maintained examples do not yet show enough -consumer benefit to justify that redesign. This recommendation is based on the -resulting API, rather than the amount of refactoring needed to achieve it. +from ordinary to layered loading more uniform. A convenience entry could preserve +the simplest call. Such a design would still need to resolve the existing +overlay-context differences and demonstrate a clearer consumer model. The +maintained examples do not show enough consumer benefit to justify that redesign +in this effort. Retaining the current APIs accepts some duplicated public option +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 @@ -377,7 +379,7 @@ the boundary rather than simplify it. The proposed work spans private engine code, private root-facade conversions, 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, 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 policy revision merely to introduce private helpers. Update the component overview and import internals when code moves. Accepted ADR decision content -remains unchanged. If review selects a materially different public loading model, -assess its behavioral consequences explicitly before implementation. +remains unchanged. A public loading-model redesign is outside this effort's +settled scope. 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 @@ -479,33 +481,27 @@ Completion requires reviewable evidence that: the resulting implementation. Current contracts continue to own behavior. Private type/helper names, final file splits, and exact stage boundaries belong -in the implementation plan. The questions below concern the public direction and -scope of the work. No additional feature semantics are needed to carry out the -recommended refactors. +in the implementation plan. The remaining question concerns the scope of clone +cleanup. No additional feature semantics are needed to carry out the recommended +refactors. -## Open Questions - -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. +## Settled Decisions ### OQ-1: Should The Public Loading APIs Change In This Effort? -**Recommendation:** retain `Load`/`Options` and `LoadLayered`/`LayeredOptions`, -and consolidate their private inputs, conversions, and acquisition machinery. -The current simple call needs little setup, while layered loading makes input -groups and independent overlay context explicit. The maintained consumer examples -demonstrate useful roles for both. Better guidance and shared private machinery -address the observed duplication without adding public concepts. +**Settled:** retain `Load`/`Options`, `LoadLayered`/`LayeredOptions`, `Input`, and +`Underlay`, including their existing overlay-context behavior. Consolidate their +private inputs, conversions, and acquisition machinery, and improve consumer +guidance. The [consumer-facing target](#consumer-facing-target) records the +rationale and tradeoffs. This decision governs the consolidation effort; it does +not establish a perpetual restriction on future API design. -**Alternative:** introduce one public request model for main input, underlays, -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 -more uniform. It is viable before 1.0, but needs concrete simple and advanced -examples to show an improvement, plus a deliberate choice about ordinary versus -layered overlay-context behavior. It would expand this effort into public API -design and consumer migration. If selected, revise the public target before -preparing the internal implementation plan. +## Open Questions + +OQ-2 remains open. The target above follows its recommended answer pending +discussion. Existing behavior and accepted architectural boundaries remain the +baseline; routine private design choices can be settled in the implementation +plan. ### OQ-2: How Much Clone Cleanup Should This Effort Commit To?