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

View File

@@ -244,7 +244,12 @@ Focused checks:
## Stage 5 — Integrate, Document, And Verify The Result
Findings: final acceptance for **C03, F07**. Status: **not started**.
Findings: final acceptance for **C03, F07**. Status: **complete**. Validation
passed on Linux/amd64 (Go 1.26.10):
`env GOTOOLCHAIN=local GOPROXY=off GOTELEMETRY=off ./scripts/check.sh`,
`env GOTOOLCHAIN=local GOPROXY=off GOTELEMETRY=off go test -race ./...`, and
`git diff --check`. Existing integration coverage was reviewed; no additional
case was needed.
1. Review both paths together: defaults resolving wildcard discovery in ordinary,
layered, and transitive imports; placement carrying the resulting sources

View File

@@ -1,6 +1,7 @@
# Audit Remediation Roadmap
Status: target accepted; execution is tracked in the [implementation plan](implementation.md).
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
@@ -14,9 +15,9 @@ It is intended for maintainers reviewing the remediation's scope and architectur
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 [implementation plan](implementation.md) owns concrete stages, private
implementation choices, edits, validation commands, and execution progress.
It carries the selected IDs through to completion evidence.
- 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
@@ -227,11 +228,12 @@ count are not acceptance criteria for this work.
## Implementation Plan
The [implementation plan](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 owns validation commands and the complete finding-to-stage
map. The audit remains the owner of original evidence and detailed acceptance cases.
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
@@ -244,27 +246,31 @@ 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 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.
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
implementation plan owns execution status without duplicate progress inventories.
Retire completed planning records under the normal documentation lifecycle.
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 implementation plan records
private design choices and sequencing, subject to the acceptance cases above.
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) remain the first two entries in [future.md](future.md), for consideration
after this selected work is complete. Other deferred features, clone-traversal
redesign, and broader performance experiments remain outside this effort. Keep
(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.