diff --git a/docs/internal/imports.md b/docs/internal/imports.md index fde72d6..55f07be 100644 --- a/docs/internal/imports.md +++ b/docs/internal/imports.md @@ -42,6 +42,17 @@ directory can be treated as optional, while enumeration and close failures remain selection errors, including errors from the standard `fs.ReadDir` fallback. +Glob selection keeps traversal coordination in `selectGlobImportCandidates`: +it advances literal and patterned segments, reads directories, unions and sorts +candidates, validates final targets, then applies exclusions and requiredness. +For each patterned directory entry, `prepareGlobEntry` handles matching and +hidden filtering, containment, target and link inspection, intermediate-directory +eligibility, host/native access-path selection, and candidate identity and label. +It returns a candidate, an ordinary skip, or a diagnostic without mutating the +selector's candidate set or traversal state. Directory entry preparation remains +separate because its matching, absence, recursion, and traversal-state rules +differ. + Acquisition remains authored: declarations are visited in source order and each selected candidate set in namespace-path lexical order. This preserves source records, IDs, source-local version checks, and callback ordering. The acquired diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 966c1aa..0f8161d 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -20,9 +20,13 @@ Implemented component owners: inheritance and decoding, before application resolution. The engine also owns shared source-version checking with sanitized declaration evidence. Explicit import discovery supports declared paths, directory searches, and - globs; load-wide defaults and source-local empty-selection evidence cross the - root facade without changing acquisition order. Import and inheritance - resolution share dependency-ready scheduling within their composition scopes. + globs; root-owned defaults are converted to the engine's single defaults input + and snapshotted during load preflight before acquisition, while source-local + empty-selection evidence crosses the facade without changing acquisition + order. The root constructs placement directly on engine options and inputs + using explicit enum conversion; public types and fields remain root-owned. + Import and inheritance resolution share dependency-ready scheduling within + their composition scopes. It retains each source's effective placement alongside physical source identity and owns schema inspection, lifecycle coordination, callback auditing, @@ -91,8 +95,14 @@ bounded algorithms. ## Implementation flow -The root facade converts caller-owned values into engine-owned requests. The -ordinary and grouped entry points share a normalized `loadRequest`: see +The root facade converts caller-owned values into engine-owned requests. Its +`ImportDefaults` conversion maps fields without taking ownership; engine load +preflight snapshots the defaults once before source acquisition or callbacks. +Ordinary and grouped loading then carry that read-only value through their +normalized `loadRequest` and acquisition policy, while declaration resolution +copies values needed by its independently owned effective policy. Placement is +constructed directly on the engine's options and input records after explicit +root-to-engine enum conversion. See [`lifecycle.go`](../../lifecycle.go), [`layered.go`](../../layered.go), and [`load_request.go`](../../internal/engine/load_request.go). Load-wide definition, version, default-import, and override policy stays distinct from each input's diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index fa90f08..7b9252e 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 836f3ef..f79f740 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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 diff --git a/docs/roadmap/roadmap.md b/docs/roadmap/roadmap.md index 0900af6..55994cf 100644 --- a/docs/roadmap/roadmap.md +++ b/docs/roadmap/roadmap.md @@ -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.