Document import and facade boundaries

This commit is contained in:
2026-10-26 00:21:40 +00:00
parent d66338a1c5
commit a71413ce67
5 changed files with 59 additions and 83 deletions

View File

@@ -8,67 +8,11 @@ in ADRs; this document does not maintain a list of rejected proposals.
## 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?
Implemented in the [internal-boundary roadmap](internal-boundaries.md#glob-entry-preparation) (C03).
## 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?
Implemented in the [internal-boundary roadmap](internal-boundaries.md#facade-to-engine-transport) (F07).
## 3. Recursive body merging for identified records