| 1. Import entry points and responsibilities | Higher | Main refactor. Include shared acquisition normalization, import-default ownership, declaration parsing, and directory admission. |
| 2. Shared inheritance executor | Higher | Main refactor. Expose meaningful phases and explicit combination results while retaining one executor. |
| 3. Projection and cloning | Higher for projection; secondary for cloning | Main refactor for projection; conditional, bounded follow-up for substantial clone handlers, preserving the distinction between the operations. |
| 4. Schema field discovery and inline assembly | Medium | Include a focused refactor coordinated with projection. Keep one schema builder and its two descriptor views. |
| 5. Resolved filesystem context | Medium | Include alongside acquisition work. Reuse resolved facts without merging resource lifetimes or changing validation timing. |
| 6. Unused reverse inspection conversions | Small, independently reviewable cleanup | Include in the root facade and engine. Retain useful forward-conversion and detached-result coverage. |
Findings 1–3 confirm the earlier roadmap's main opportunities; findings 4–6 add
focused work. The following sections own their rationale and intended changes.
Implementation and validation will establish each finding's disposition.
Completed correctness and algorithmic remediations remain part of the baseline,
including sequence records preserved at `ea46001:docs/roadmap/remediation.md`
and discovery records preserved at `0369111:docs/roadmap/remediation.md`.
Item-scope application matching and inheritance policy localization are examples
of completed corrections that overlap this work and whose regressions should
`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.
### Preserve Useful Convenience And Ownership Boundaries
| Surface reviewed | Recommended public end state |
| --- | --- |
| `Source`, `Filesystem`, `Search`, filename groups and presets | Retain typed, reusable source/search descriptions. Discovery selects a concrete source during loading; applications do not loop over complete loads. |
| `FilesystemContext` | Retain the public description and current host/native rules. Consolidate its resolved private representation; do not expose acquisition handles or engine context records. |
| `SequenceIdentityAt` and `SequenceIdentityMatching` | Retain the exact-path convenience and dynamic selector form over the common registration model. Both serve distinct consumer shapes. |
| `Definition`, resolution and validation callbacks | Retain application-owned domain rules inside one recorded lifecycle. Preserve the distinction between mutable recorded resolution and read-only validation. |
| Results, metadata, explanations, source context and diff | Retain detached, safe inspection with consumer-owned presentation. Remove unused inverse conversions without removing supported queries. |
| Root wrappers and private conversions | Retain root-owned public types and explicit ownership conversion under ADR 0006. Consolidate repeated real conversions and delete unused ones. |
The consumer-facing work is to make the ordinary path easier to find and show
how additional features compose, using the existing maintained examples. Update
the adoption guide with a concise choice between simple loading, discovery, and
layered loading, and show which options belong to an input versus a whole load.
Keep exact behavior in its canonical owners. Examples should make application
rules recognizable and avoid requiring consumers to recreate generic merging,
presence, or provenance machinery.
Use the current simple README call, bundled-file and layered catalog examples,
the import-focused prompt catalog, and the discovered sequence catalog to assess
the end state. The latter exercises imports, underlays, independent overlay
context, CLI assignment, and recorded resolution in one workflow. A high number
of options in that example does not by itself justify a new abstraction.
## Internal Target
Keep the root facade, cohesive `internal/engine`, ordered document model, and
private YAML adapter. Use ordinary private records, functions, and focused files
to express responsibilities. Existing mapping combination, sequence combination,
dependency scheduling, schema descriptors, and traversal accounting remain shared.
`executeLoadRequest` stays the visible lifecycle coordinator. It should show
Introduce cohesive private acquisition inputs and explicit state ownership,
reusing `loadRequest`, `loadInput`, `acquisitionScope`, and `importTraversal`
where they fit. Translate ordinary and layered public declarations into the
shared loading model once. Acquisition should receive the source, input role,
placement, context, and policies it needs without a fabricated application type
or a reconstructed broad options object. Small adapters may preserve meaningful
entry operations while callers migrate; remove obsolete forwarding variants
within the completed refactor.
Separate immutable policy, mutable processing state, and results. Move import
defaults out of `sourceVersionState` and into the load/acquisition policy owner.
Version state continues to own version processing, projected effective version
location, evidence, and diagnostics. Local and effective version rules have
different meanings and must remain distinguishable.
The state boundaries are especially important:
| Lifetime or scope | State and responsibility |
| --- | --- |
| Whole load | Aggregate resource accounting, application definition/registrations, import defaults, shared version evidence and diagnostics. |
| One strict tier | Repetition tracking shared by that tier's inputs, namespace scheduling anchors, and its inclusion/composition graph relationship. A later tier may reuse a file. |
| Active import traversal | Active routes and inclusion edges, filesystem access ownership, and cycle detection, including edges crossing item-scope boundaries. |
| One composition scope | Peer contributions, pending collection declarations, item-local helpers, and deferred item placement. Nested scopes do not become separate precedence tiers. |
| Retained result | Source records, effective destinations, origins, history, and passive resource-context descriptions. |
6. Consolidate real facade adapters, finish consumer/internal navigation, and run
the applicable integration and ownership checks on the combined result.
Steps 4 and 5 have no necessary implementation dependency on each other. Keep
correctness fixes discovered during refactoring identifiable with their own
regression evidence rather than hiding behavior changes inside code movement.
## Validation And Completion
Use the [development guide](../development.md) and
[testing policy](../policy/testing.md) for focused checks and the ordinary full
development check. Preserve existing behavior tests; rewrite tests coupled only
to removed plumbing. Add a test when a consequential handoff risk lacks coverage,
not for every new helper.
| Work area | Existing protection and review focus |
| --- | --- |
| Acquisition and imports | Selection, defaults, scheduling, relative/item placement, source-version evidence, aggregate limits, repetition within versus across tiers, and ordinary/layered equivalence. |
| Inheritance | Mapping and record inheritance, nested destination-local evaluation, child identity, policy lifetime, version movement, history ordering, sensitivity, and retained-node budgets. |
| Projection/schema/clone | Inline fields, recursive schemas, dynamic values, nil/empty values, cycles and limits, text codecs, secret states, callback ownership, and independent loads. |
| Facade and consumers | Forward conversion, detached records, supported API boundaries, source-form equivalence, maintained simple/catalog/discovery examples, and safe explanation/diff. |
