Adopt shared history ownership in the interface roadmap

Plan interface contract remediation
Record API contract audit findings
2026-10-26 12:36:17 +00:00 · 2026-10-26 02:40:21 +00:00 · 2026-10-26 01:36:20 +00:00 · 2026-10-26 01:25:35 +00:00
6 changed files with 570 additions and 967 deletions
--- a/docs/development.md
+++ b/docs/development.md
@@ -43,7 +43,7 @@ public behavior.
 | Shared source-version checks | [Configuration contract](config.md#shared-source-version-checks), [ADR 0013](adr/0013-shared-source-version-checks.md), and the version/source-version tests below |
 | Documentation changes | The owning document |
 | Licensing, dependencies, attribution, or release-document changes | [Project grant](../COPYRIGHT) and [attribution](oss/attribution.md); release changes also follow the release procedure |
-| Architecture decisions or future work | [Future features](roadmap/future.md), [consolidated audit review](roadmap/audit.md), [remediation roadmap](roadmap/roadmap.md), and relevant ADRs listed below |
+| Architecture decisions or future work | [Future features](roadmap/future.md), [remediation roadmap](roadmap/roadmap.md), and relevant ADRs listed below |
 | Code and test changes | The owning contract and tests from the map below |
 | Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) |
 | Release preparation | [Release procedure](release.md) |
@@ -199,11 +199,15 @@ git show 34cbc0d:docs/roadmap/remediation.md
 ```

 Potential enhancements are tracked in [future features](roadmap/future.md).
-The [consolidated audit review](roadmap/audit.md) owns the open findings from
-the nine 2026-10-25 audits, their evidence, and settled scope decisions. The
-[remediation roadmap](roadmap/roadmap.md) owns the combined target state and
-high-level dependency order. The original reports are preserved at `ecd5d5d`
-under `docs/roadmap/`.
+The completed audit remediation's scope is recorded in the
+[remediation roadmap](roadmap/roadmap.md). The consolidated audit, including
+findings, evidence, and settled scope decisions, is preserved at
+`453da68:docs/roadmap/audit.md`; the original nine reports are preserved at
+`ecd5d5d` under `docs/roadmap/`. Retrieve the consolidated record with:
+
+```sh
+git show 453da68:docs/roadmap/audit.md
+```

 Install the Go version required by `go.mod` or a compatible newer toolchain.
 Acquire declared dependencies explicitly before entering an offline
--- a/docs/roadmap/audit.md
+++ b/docs/roadmap/audit.md
@@ -1,949 +0,0 @@
-# Consolidated Audit Review
-
-Status: scope settled; 29 entries selected for implementation planning.
-Two refactors are deferred to `future.md`. Implementation has not begun.
-Consolidated: 2026-10-25. Baseline: `ecd5d5d`.
-
-This document consolidates nine sequential audits for maintainer review. It owns
-their open findings, supporting evidence, proposed remedies, and relationships.
-The settled decisions select the [remediation roadmap's](roadmap.md) scope.
-That document owns the combined target state and high-level dependency order;
-this review owns detailed finding evidence and acceptance cases. Neither is a
-staged implementation plan or a new set of release gates. The
-[configuration contract](../config.md), public Go declarations, and
-[architecture policy](../policy/architecture.md) continue to
-own behavior and guarantees.
-
-There are nine distinct reported defects: four from correctness, three from
-resources, one from error handling, and one from security. Concurrency adds
-evidence for an existing callback-lifetime defect. Other entries are cleanup,
-efficiency, maintainability, or test improvements. Regression recommendations
-are attached to the defects they protect rather than counted as additional
-product fixes.
-
-The 35 original numbered findings map to 31 review entries after deduplication
-and integration of related test work. All findings remain unresolved; the
-[settled scope decisions](#settled-scope-decisions) identify the 29 selected
-entries. C03 and F07 have moved to `future.md`, with reference entries retained
-here for traceability. All three scope questions are settled.
-Their medium/low priorities retain the original assessments; those labels do not
-imply severity certification or implementation order. IDs remain stable as work
-is selected or completed.
-
-## Evidence And Provenance
-
-All nine audits were dated 2026-10-25. Their sequential commits changed only the
-audit documents, so their production baseline is the same. This consolidation
-does not independently reproduce the findings or claim new runtime evidence.
-
-| Original report | Reviewed revision | Evidence contributed |
-| --- | --- | --- |
-| `correctness.md` | `47944d2` | Source review and standalone public-API reproductions of four defects. |
-| `efficiency.md` | `5098b56` | Source-derived scaling cases and proposed algorithm changes; no benchmarks. |
-| `complexity.md` | `320d0c5` | Responsibility/caller review, graph complexity estimates, and maintainability candidates. |
-| `concurrency.md` | `a802734` | Ownership review, race checks, and corroboration of callback lifetime after panic. |
-| `resources.md` | `0cca633` | Bounded allocation, retained-node, and host-handle diagnostics. |
-| `error-handling.md` | `5925066` | Directory read/close fault injection through the public API. |
-| `security.md` | `b30c9f1` | Trust-boundary review, bounded symlink operation counts, and a historical dependency spot-check. |
-| `testing.md` | `eb5a82f` | Aggregate statement coverage, assertion review, and regression/test-cleanup recommendations. |
-| `deadcode.md` | `b1c278b` | Type-aware reference inventory, graph/caller checks, and source review of private cleanup candidates. |
-
-The full original reports, including exact probes, commands, source line
-references, and validation limitations, are preserved at `ecd5d5d`. For example:
-
-```sh
-git show ecd5d5d:docs/roadmap/correctness.md
-git show ecd5d5d:docs/roadmap/security.md
-```
-
-The [original-finding map](#original-finding-map) accounts for every numbered
-finding, including duplicates and test recommendations integrated elsewhere.
-Source links below identify implementation owners; historical line numbers are
-left in the originals because later edits will move them.
-
-### Recorded Validation And Its Limits
-
-The audits report successful development checks, ordinary tests, full race tests,
-`go vet`, and focused suites as specified in their individual records, using
-Go 1.26.10 on Linux amd64. Concurrency additionally repeated six relevant engine
-tests with race instrumentation, count 20, and CPUs 1, 4, and 8. Testing ran the
-suite with shuffle enabled three times. These results did not detect the newly
-reported defects and are not evidence that those defects have been fixed.
-
-Testing recorded 771 ordinary test functions, three fuzz targets, and 29 executable
-examples. Aggregate cross-package coverage was 90.3%: root 81.3%, engine 91.0%,
-document 100%, YAML 89.9%, and maintained consumers 79.2%. Those figures locate
-gaps; they are not targets or a measure of assertion strength. Only checked-in
-fuzz seeds ran, not an extended campaign or mutation analysis.
-
-Standalone diagnostics stayed outside the repository. Some potentially fatal
-cases used disposable processes, small limits, or operation ceilings; larger
-scaling examples were derived rather than executed. The dead-code inventory
-considered Linux, Darwin, and Windows build configurations, but no audit reports
-native macOS or Windows execution. Graph scores and reachability results were
-triage aids, not proof that a function is unnecessary or a numerical refactoring
-threshold. Cached analysis tooling was used outside the repository; no new
-project tools or dependencies were introduced.
-
-The security report's module-path advisory spot-check and successful module
-integrity verification are historical evidence only. It recorded no listed
-advisories for the selected YAML v4, ReleaseKit, or Goldmark v2 module paths, and
-recorded the selected `x/mod` version as fixed for the two reports it found. It
-did not perform complete toolchain/transitive reachability analysis or supply-
-chain attestation; dedicated vulnerability, security, and secret scanners were
-unavailable. This consolidation neither refreshes nor broadens that conclusion.
-
-## Review Priorities And Dependencies
-
-Recommended review order is reported defects with their regression coverage,
-bounded cleanup, targeted efficiency changes, and then broader structural
-refactoring. Small prerequisite cleanups can accompany a defect fix. The order
-of the groups below is for navigation, not an execution sequence.
-
-| Relationship | Consequence for scope selection |
-| --- | --- |
-| A02 and A05 | Make descriptor construction safe before reusing successful dynamic-type eligibility results. |
-| B01 and B02 | Panic cleanup must close callback state and the owned host root independently. Neither fix substitutes for the other. |
-| C01 and its filesystem tests | Strengthen error/handle assertions while adding failure-phase regressions, using one shared test owner. |
-| C02 and deferred C03 | Complete link expansion remediation independently; reconsider glob readability extraction afterward through `future.md`. |
-| D01, D02, and D03 | Remove the confirmed unused copies, then account for the complete retained graph. Removing one unused tree does not fix the remaining omissions. |
-| E01, E02, and E03 | Address policy-state costs and responsibility boundaries together, preserving separate scaling and behavioral acceptance cases. |
-| F01 and F02 | Removing the test-only acquisition mode does not by itself simplify active lifecycle handoffs. |
-| F04, F09, and F12 | Replace useful facade ownership/query coverage before deleting disconnected or representation-coupled scaffolding. |
-| F05 and deferred F07 | Remove unused placement bridges in this scope; reconsider wider transport simplification afterward through `future.md`. |
-
-## A. Schema And Typed Values
-
-### A01. Terminate Pointer-Only Recursive Descriptor Traversal
-
-Type: reported defect. Priority: medium. Source: correctness 1; testing 1.
-
-**Problem and evidence.** In [schema.go](../../internal/engine/schema.go), a legal
-type such as `type Loop *Loop` produces a pointer descriptor whose element is
-itself. [decode.go](../../internal/engine/decode.go) unwraps that descriptor
-without consuming a non-null input node; `resolveSchemaPath` likewise assumes
-pointer traversal eventually reaches another kind. A public load with a `Loop`
-field and `value: {}` overflowed the stack in a process with a small stack limit.
-`value: null` succeeded, but resolving a normalization path for that field hung
-until the diagnostic process was stopped. The [schema
-contract](../config.md#application-schema-binding) permits recursive types with
-acyclic values; the inline-field restriction is not a blanket pointer restriction.
-
-**Recommendation and acceptance.** Detect repeated descriptors while unwrapping
-pointer-only chains in decoding and schema-path resolution, and review analogous
-helpers. Incompatible non-null input must fail safely; path traversal must
-terminate and reject unaddressable descendants. Preserve supported nil/null
-values and ordinary recursive structs. Do not add a blanket schema rejection or
-arbitrary depth cap. Add bounded regression coverage for both decoding and helper
-path resolution, keeping fatal/hanging probes out of the default test process.
-
-### A02. Make Failed Dynamic Descriptor Construction Transactional
-
-Type: reported defect. Priority: medium. Source: correctness 2; testing 1.
-
-**Problem and evidence.** `dynamicDescriptor` in
-[value_operation.go](../../internal/engine/value_operation.go) passes the load's
-descriptor cache to `schemaBuilder`. Failed construction leaves cached container
-placeholders. For a dynamic struct containing an unsupported channel field, two
-`Normalize` calls in one resolver, first with a typed nil pointer and then a
-non-nil pointer to that type, reproduced a nil-pointer panic on the second call.
-The first call reported a diagnostic but left a reusable partial descriptor.
-The application callback itself did not panic.
-
-**Recommendation and acceptance.** Stage new descriptors and commit only on
-successful construction, or roll back all additions from a failed build. Include
-recursive references among newly built descriptors; clearing only the immediate
-failed container or adding a projection nil guard is insufficient. Preserve
-previously valid descriptors, load-local ownership, and safe path-specific
-diagnostics under [typed projection](../config.md#typed-projection-and-ownership)
-and [resolution](../config.md#recorded-application-resolution). Test repeated
-operations after a failed build in the same load. Coordinate A05 only after this
-failure-state boundary is sound.
-
-### A03. Distinguish Acyclic Slice Views In Cycle Detection
-
-Type: reported defect. Priority: medium. Source: correctness 3; testing 1.
-
-**Problem and evidence.** `valueVisit` / `visitFor` in
-[value_operation.go](../../internal/engine/value_operation.go) identify slices by
-type, kind, and starting pointer, omitting length. The finite value built by
-`shared := []any{"leaf", nil}; shared[1] = shared[:1]` was rejected through mapping
-sources, typed defaults, and CLI overrides, while an equivalent independently
-allocated value succeeded. The nested view contains only the leaf, not its
-enclosing view. The same helper serves projection/cloning and
-[value.go](../../internal/engine/value.go).
-
-**Recommendation and acceptance.** Include visible slice length in active-visit
-identity, or use an equivalent distinction. Preserve rejection of actual self
-and mutual cycles, nil/empty behavior, and detached output; preserving alias
-identity is not required. Regressions should cover the shared source, override,
-projection, and cloning paths under the existing supported-acyclic-value contract,
-alongside true-cycle rejection.
-
-### A04. Enforce Existing Node Budgets Before Container Reservations
-
-Type: reported defect. Priority: medium. Source: resources 1; testing 1.
-
-**Problem and evidence.** `projectSequence` and `projectMap` in
-[projection.go](../../internal/engine/projection.go) reserve space for the full
-container, and maps collect all keys, before child charging in
-[value_operation.go](../../internal/engine/value_operation.go). Defaults containing
-a maximum-length slice of zero-sized structs caused a `makeslice: cap out of range`
-panic instead of `schema.projection_limit`; that diagnostic did not allocate a
-huge input backing array. Less extreme cases can allocate excessive temporary
-memory before rejection. Application resolution can reach these paths too.
-
-**Recommendation and acceptance.** Check the known minimum node cost against the
-remaining existing allowance with overflow-safe arithmetic, or bound initial
-capacity and grow as charging succeeds. Review map reservation/key collection as
-well as sequences. Preserve node/depth semantics, inline handling, and useful
-diagnostic paths. Use bounded regressions, including small controlled allowances,
-without enormous allocations. This enforces an existing budget, not a new length
-cap or universal heap-size guarantee.
-
-### A05. Reuse Successful Dynamic-Type Eligibility Checks Locally
-
-Type: optimization candidate. Priority: low. Source: efficiency 6.
-
-**Problem and evidence.** Each dynamic value in projection/cloning invokes
-`descriptorContainsSecret` with a new visited map, even when its descriptor is
-cached. N values of one concrete type with descriptor-graph size S therefore cost
-O(N × S) eligibility work. N interface values containing nil pointers to one wide
-supported struct can produce only N null values while repeating the full type
-walk. This is a source-derived bound, not measured runtime.
-
-**Recommendation and acceptance.** After A02, consider remembering successfully
-approved concrete descriptors within `valueOperation`, reducing repeated-type
-eligibility work to O(S + N). Cache only completed successful eligibility checks,
-not traversal-local visits, partial descriptors, or path-bearing failures.
-Preserve rejection of dynamic secret-reference types, including nil pointers and
-recursive descriptor cases. This does not select cross-load schema caching or a
-clone traversal redesign.
-
-## B. Callback And Filesystem Lifetime
-
-### B01. Deactivate Callback Contexts During Panic Unwinding
-
-Type: reported defect. Priority: low. Sources: correctness 4, concurrency 1;
-testing 1; corroborated by error-handling and security reviews.
-
-**Problem and evidence.** `runResolution` in
-[resolution.go](../../internal/engine/resolution.go) and `runValidation` /
-`reportVersion` in [validation.go](../../internal/engine/validation.go) deactivate
-contexts only after normal callback return. Public probes retained the context,
-panicked, recovered outside `Load`, and then successfully queried resolution or
-wrote validation/version diagnostics. The concurrency audit reproduced this
-with race instrumentation without reporting a data race. The defect violates
-callback lifetime, not a newly supported concurrent-use scenario.
-
-**Recommendation and acceptance.** Defer deactivation within each callback
-invocation, closing immediately at normal return and on unwinding, before later
-projection or metadata work. Preserve the original panic and prohibit retained
-context use through the established closed-context behavior. Test all three
-callback kinds with external recovery. No recovery service, lock, atomic flag,
-or broader callback thread-safety guarantee is needed. B02 separately owns root
-handle cleanup.
-
-### B02. Close The Owned Import Root When A Version Callback Panics
-
-Type: reported defect. Priority: medium. Source: resources 3; testing 1.
-
-**Problem and evidence.** Host import acquisition in
-[import_acquisition.go](../../internal/engine/import_acquisition.go) opens an
-`os.Root` through [filesystem_access.go](../../internal/engine/filesystem_access.go)
-but relies on explicit ordinary-path closes. An imported version-check panic
-bypasses them. A disposable Linux probe disabled GC, recovered outside `Load`,
-and observed one remaining root descriptor through `/proc/self/fd`; the normal
-control returned to zero. The imported file's own deferred close still ran.
-
-**Recommendation and acceptance.** Install deferred fallback cleanup at the
-owning boundary, preserving explicit normal close timing and diagnostics, as
-selected-overlay acquisition already does. Avoid double-close confusion, leave
-borrowed filesystems untouched, and propagate the original panic. A regression
-must observe the owned host root, not merely a native file-close counter, and
-document platform prerequisites. Context deactivation in B01 is a separate
-requirement. This restores load-scope cleanup without adding panic recovery.
-
-## C. Import Selection And Link Resolution
-
-### C01. Preserve Directory Failure Phase And Strengthen Its Tests
-
-Type: reported defect with test improvements. Priority: medium.
-Sources: error-handling 1, testing 3.
-
-**Problem and evidence.** `filesystemAccess.readDirectory` in
-[filesystem_access.go](../../internal/engine/filesystem_access.go) returns open,
-read, and close errors through one unqualified error channel.
-[import_selection.go](../../internal/engine/import_selection.go) and
-[glob.go](../../internal/engine/glob.go) treat any `fs.ErrNotExist` as absence.
-A borrowed filesystem probe selected a failing directory plus a good directory,
-using both `dir` and `glob` with `required: true`. Injecting `fs.ErrNotExist`
-alongside entries from `ReadDir`, or from `Close`, let loads succeed with the bad
-directory's contribution omitted. Permission-classified controls failed. All
-eight selector/phase/error cases ran. This violates the existing distinction
-between optional absence and failed acquisition.
-
-**Recommendation and acceptance.** Preserve missing-on-open versus post-open
-failure, for example with a small private failure record analogous to regular
-file acquisition. Keep genuine missing-target rules, entry budgets, first-error
-precedence, borrowed filesystem ownership, and safe existing traversal diagnostics.
-Review both batched `fs.ReadDirFile` and standard fallback paths. A successful
-second directory must not hide enumeration/close failure; raw backing error text
-must not leak. No retries or filesystem transaction are proposed.
-
-**Test improvements.** The shared fixture in
-[native_filesystem_test.go](../../internal/engine/native_filesystem_test.go) and
-[resource_context_test.go](../../internal/engine/resource_context_test.go) currently
-checks aggregate closes and often only non-nil errors. One leaked handle and
-one double-close can cancel out. Its canary check examines the terse error
-summary, not structured diagnostics. Track per-handle closure, assert nil result,
-diagnostic code and source, and inspect diagnostic messages/rendering for canaries.
-Add entries/data-plus-error and close-phase cases through narrow failure seams.
-Preserve intentionally ignored read-only regular-file close errors; this does
-not impose a universal close-error policy.
-
-### C02. Avoid Reexpanding Completed Finite Symlink Dependencies
-
-Type: reported availability defect. Priority: medium. Source: security 1;
-testing 1.
-
-**Problem and evidence.** Host/native resolvers in
-[filesystem_links.go](../../internal/engine/filesystem_links.go) track active links
-but reuse no completed resolution. A finite contained graph `s00 -> .`,
-`s01 -> s00/s00`, `s02 -> s01/s01`, and so on repeats completed dependencies.
-Its work follows T(N) = 2T(N-1) + O(1), despite linear graph size. Directory
-selection resolves discovered links before deciding on recursive descent, so
-`recursive: false` does not avoid it. Existing source/entry/node/import-depth
-budgets do not account for the repeated expansion.
-
-A real-link fixture exposed through a native `fs.ReadLinkFS` wrapper recorded
-32, 128, 512, 2,048, and 8,192 `Lstat` calls for 3, 5, 7, 9, and 11 entries;
-corresponding `ReadLink` counts were 11, 57, 247, 1,013, and 4,083. Thirteen
-entries reached a diagnostic ceiling of 12,000 `Lstat` calls. With following
-disabled, that fixture used 17 `Lstat` calls and no `ReadLink`. The host resolver's
-matching logic was reviewed, not separately operation-count tested.
-
-**Recommendation and acceptance.** Reuse fully resolved targets within the
-resolution operation, keyed for the rooted namespace and full link path, or use
-equivalent dependency evaluation. Retain active-path cycle detection, containment,
-finite reuse, relative/absolute host semantics, and the stable-input assumption.
-A global visited-means-cycle rule would incorrectly reject valid inputs. Cover
-both resolvers and directory/glob entry points with small fixtures and bounded
-operation observation, not timing thresholds or exhaustion tests. No arbitrary
-link cap, public cache, or default-follow change is selected.
-
-The availability risk requires influence over imported filesystem data; it is
-not an anonymous remote vulnerability by itself. No concurrent mutation or
-outside-root target is needed, and accidental graphs can cause the same work.
-
-### C03. Separate Glob Entry Preparation From Traversal
-
-Deferred under OQ-3. The evidence, proposed scope, and remaining questions now
-belong to [future work](future.md#1-separate-glob-entry-preparation-from-traversal),
-for consideration after this roadmap's selected work is complete.
-
-## D. Retained History And Unused Evidence
-
-### D01. Account For The Complete Published History Graph
-
-Type: reported defect. Priority: medium. Source: resources 2; testing 1.
-
-**Problem and evidence.** The checkpoint in [load.go](../../internal/engine/load.go)
-and [history.go](../../internal/engine/history.go) counts a different root set
-from [load_result.go](../../internal/engine/load_result.go) publication. Separately
-cloned post-CLI input, `structuralInput`, `preCLI`, and later inheritance copies
-are not all represented. A read-only diagnostic of a small successful load with
-a no-op resolver counted 14 distinct nodes before including the two published
-replay roots and 22 with them. Source inspection found that the checkpoint uses
-a different, same-sized decoded-final instance and also counts 14 in this case.
-Generalized to N scalar items, the reported counts were 3N + 8 versus 5N + 12;
-800,000 items would pass the checkpoint yet exceed the existing 4,000,000-node
-history allowance. That large case was derived, not allocated or executed.
-
-**Recommendation and acceptance.** Use pointer-aware accounting for every document
-root actually retained at publication, including replay and copied inheritance
-history, counting shared nodes once. Where practical, reserve/charge copies before
-allocation. Coordinate removal of unused trees under D03 and recalculate the
-retained set afterward; that removal alone does not establish complete accounting.
-Reuse already-owned immutable snapshots only where equivalence and ownership
-are demonstrated. This need not redesign public metadata copying.
-
-Use a small controlled allowance to test publication integration and the existing
-`explain.limit_exceeded` outcome, as well as count-once sharing. Helper-only tests
-cannot detect roots omitted by callers. Preserve [historical
-inspection](../config.md#historical-value-explanation), detached ownership, and
-the existing quota; no smaller limit or universal heap-size bound is proposed.
-
-### D02. Remove The Unconsumed Override-Result Pre-CLI Copy
-
-Type: cleanup. Priority: medium. Source: deadcode 1.
-
-**Problem and evidence.** `decodedOverrideResult.preCLI` in
-[override_decode.go](../../internal/engine/override_decode.go) clones the entire
-decoded final tree even without CLI assignments. Its readers are private tests;
-production independently clones `before.final` into the active context in
-[override_context.go](../../internal/engine/override_context.go).
-
-**Recommendation and acceptance.** Remove that result member, its clone, and
-assertions solely about it. Preserve the independently owned pre-CLI context
-that actually feeds resolution, publication, and explanation. Retain behavioral
-CLI/history/ownership coverage. The change removes a redundant traversal, not
-the active replay snapshot or its detachment boundary.
-
-### D03. Remove The Unqueried Published Structural-Input Copy
-
-Type: cleanup. Priority: medium. Source: deadcode 2.
-
-**Problem and evidence.** `Inspection.structuralInput` in
-[load.go](../../internal/engine/load.go) is cloned and indexed at publication,
-but has no production reader. [explain.go](../../internal/engine/explain.go)
-uses source/inheritance replay, `preCLI`, and `input`. The immutable lookup is
-addressed by supplied node pointers; indexing this otherwise unused root does
-not make it useful and keeps its mappings alive.
-
-**Recommendation and acceptance.** Remove the inspection member, final clone,
-and its `retainedTrees` inclusion. Keep earlier `resolved.structuralInput` uses
-for path finalization and sensitivity. Check explanation, historical paths,
-redaction, and ownership through active outputs. Coordinate D01 for all remaining
-retained roots; do not infer that structural evidence is globally unused.
-
-### D04. Stop Constructing Unconsumed Combination Evidence
-
-Type: cleanup. Priority: medium. Source: deadcode 5.
-
-**Problem and evidence.** `sequenceCombinationResult.discardedLower` in
-[sequence_combine.go](../../internal/engine/sequence_combine.go) allocates a list
-of all replaced lower indexes with no production reader. Three tests inspect it.
-`inheritanceReplacement.path`, `previous`, and `effective` in
-[inheritance.go](../../internal/engine/inheritance.go) are also unread, but their
-writers perform path/origin copies and displaced-subtree walks. Active inheritance
-history uses operations and projected changes elsewhere. Replacement `before`
-and `after` trees still feed node accounting.
-
-**Recommendation and acceptance.** Remove only unread members and work solely
-feeding them. Keep replacement trees, item projections, replacement mappings,
-`appendedHigher`, active provenance/history, and node accounting. Keep
-`sequenceIndexes` for append and `displacedOrigins` for overlay callers. Replace
-private unused-evidence assertions with existing behavior-level replacement,
-removed-descendant, and history protection where necessary. Coordinate D01 and
-E03 without deleting active evidence merely because another representation exists.
-
-## E. Collection Processing And Efficiency
-
-All complexity estimates here describe identified internal work with bounded-
-depth examples and expected hash lookup costs. Actual path processing, copied
-payload, and expanded output remain costs; no end-to-end complexity or timing
-guarantee is proposed.
-
-### E01. Avoid Scanning Every Policy For Each Replacement
-
-Type: optimization candidate. Priority: medium. Source: efficiency 1.
-
-**Problem and evidence.** `retireCollectionPoliciesAtOrBelow` in
-[collection_policy_state.go](../../internal/engine/collection_policy_state.go)
-scans all P policies for each of Q ordinary replacements in
-[overlay.go](../../internal/engine/overlay.go), even if the changed scalars are
-unrelated to every collection. P = Q = N gives O(N²) visits for linear-sized
-input and output within one tier.
-
-**Recommendation and acceptance.** Consider an operation-local semantic-path
-index with descendant queries, maintained as policies change, or batch retirement
-where timing remains equivalent. The disjoint case can approach O(P + Q), with
-additional work charged to affected entries/path lengths. Preserve explicit-mode
-persistence, record ownership, and the moment old identity retires; delayed
-retirement must not clear newly established higher-tier policy. Evaluate existing
-inheritance indexing without requiring identical interfaces. Retain a distinct
-disjoint-replacement case even if implementation is coordinated with E02/E03.
-
-### E02. Avoid Recopying Unrelated Policy Across Small Tiers
-
-Type: optimization candidate. Priority: medium. Source: efficiency 2.
-
-**Problem and evidence.** `lowerCollectionPoliciesForClaims` in
-[collection_retirement.go](../../internal/engine/collection_retirement.go) clones
-and scans lower policy, and `resolveStrictCollectionPolicies` in
-[compose.go](../../internal/engine/compose.go) clones it again. Overlay preparation
-repeats full-state work and checks retained destinations. P initial policies
-followed by T scalar-only tiers cost O(T × P) work/allocation although only O(P + T)
-material exists. Copies include record order and nested record policy; these
-are transient private copies, not independently published snapshots.
-
-**Recommendation and acceptance.** Separate read-only lower-policy lookup from
-owned current-tier changes, localize work to incoming claims/declarations, and
-apply changes to the assembly owner. Keep copies at actual mutable ownership
-boundaries. Removing the immediate duplicate copy helps but does not alone fix
-O(T × P) growth. Preserve pending declarations, replacement eligibility, and
-independent nested record policies. This case remains distinct from E01 and the
-deferred public metadata-copy experiment.
-
-### E03. Clarify Policy Preparation And Merge Evidence Application
-
-Type: selected refactor. Priority: medium. Source: complexity 3.
-
-**Problem and evidence.** [overlay.go](../../internal/engine/overlay.go) combines
-claim/declaration preparation, operation resolution, callbacks, diagnostics,
-origins/history, retirement, record policy rebuilding, and declaration-only
-finalization. Overlay and [inheritance](../../internal/engine/inheritance_collection.go)
-separately translate sequence results into history descriptors and reconstruct
-record order. `combineSequence` already owns shared value combination.
-
-**Recommendation and acceptance.** Consider explicit preparation, application,
-and finalization operations with a small result/owner for evidence and diagnostics.
-Share straightforward history-descriptor construction; assess projected-record
-selection sharing while keeping precedence and inheritance policy ownership
-explicit. Do not unify distinct origin or mode-lifetime rules behind a generic
-strategy framework. Coordinate E01/E02 so extraction does not preserve avoidable
-full-table work. Preserve pending declarations, replacement ordering, retained
-versus incoming record owners, and stable history. D04 can remove unused evidence
-without requiring this broader refactor.
-
-### E04. Index Tier-History Projection Lookups
-
-Type: optimization candidate. Priority: medium. Source: efficiency 3.
-
-**Problem and evidence.** `projectTierHistoryApplications` in
-[sequence_history_projection.go](../../internal/engine/sequence_history_projection.go)
-calls unindexed `documentAtPath` for each mapped sequence. N sibling collections
-selected by one wildcard identity registration incur O(N²) mapping comparisons
-while projecting linear-sized source/history material.
-
-**Recommendation and acceptance.** Lazily prepare one read-only `documentLookup`
-per original application value with mapped contributions, or collect needed nodes
-in one traversal. With V nodes, S contributions, depth D, and I projected items,
-that portion can be O(V + S × D + I). Preserve authored coordinates, sparse item
-projections, replacement evidence, and independent output storage. This is load-
-time coordinate projection, not branch-local explanation replay.
-
-### E05. Restore Compound Identity Without Repeated Mapping Scans
-
-Type: optimization candidate. Priority: medium. Source: efficiency 4.
-
-**Problem and evidence.** `preserveInheritanceIdentityFields` in
-[inheritance_scope.go](../../internal/engine/inheritance_scope.go) searches child
-and merged mappings for each identity field. K fields and C/M child/merged
-entries cost O(K × (C + M)) comparisons plus required clones. A wide compound
-identity can make this quadratic without expanding record output.
-
-**Recommendation and acceptance.** Index merged positions and walk child entries
-against an identity-field set, or use equivalent local mapping indexes, for
-O(K + C + M) lookup work plus copies. Preserve child-owned identity values and
-locations, mapping order, and detached nodes. Do not change identity equality or
-parent selection. Removing the restoration step instead requires a separate
-equivalence review; apparent duplication alone is insufficient.
-
-## F. Remaining Maintenance And Test Improvements
-
-### F01. Remove The Test-Only Eager Acquisition Mode
-
-Type: cleanup. Priority: medium. Sources: complexity 1, deadcode 8.
-
-**Problem and evidence.** Both production constructors of the request declared in
-[acquisition.go](../../internal/engine/acquisition.go) set
-`inputAcquisitionRequest.deferAssembly` to true. Only private
-test helpers select the eager composition branch in
-[import_acquisition.go](../../internal/engine/import_acquisition.go). Acquisition
-maintains two return protocols and tests can bypass the production phase handoff.
-
-**Recommendation and acceptance.** Return retained scopes consistently and remove
-the unused production mode. Tests needing composition should invoke the active
-composition phase through a small test-only helper; acquisition-only tests should
-remain acquisition-only. Preserve closure, pending-item reservation, accounting,
-diagnostics, and meaningful composition coverage. This does not retire public
-loading workflows or imply that every nil-state/directive context is unused.
-
-### F02. Clarify Active Acquisition And Coordinator Handoffs
-
-Type: selected refactor. Priority: medium. Source: complexity 2.
-
-**Problem and evidence.** `acquireInput` in
-[acquisition.go](../../internal/engine/acquisition.go) combines discovery, parsing,
-directive/version branches, placement/accounting, dispatch, and passive contexts.
-Version branches repeat source-ID/failure/result handling, and layered processing
-extracts and restores directives. [load.go](../../internal/engine/load.go) contains
-a substantial ordinary-load context fallback; [load_request.go](../../internal/engine/load_request.go)
-repeats tier declaration/application/projection handoffs. Parsed, local, composed,
-inherited, and version-path representations are difficult to follow together.
-
-**Recommendation and acceptance.** Consider cohesive parsed-input directive/version
-processing and standalone placement/registration operations, plus explicit context,
-structural-expansion, and repeated tier handoffs. Reuse existing state/results;
-helpers that merely share the same mutable surrounding locals do not resolve
-ownership. Preserve visible phase order, ordinary/layered overlay differences,
-default/enabled version timing, warnings, exactly-once callbacks, and load-wide
-versus tier-local state. F01 removes a different, inactive protocol; neither task
-requires a new context hierarchy or public request model.
-
-### F03. Retire The Parallel Test-Only Import Directive Parser
-
-Type: cleanup. Priority: low. Source: deadcode 7.
-
-**Problem and evidence.** `parseImportSpecificationDirective` in
-[import_spec.go](../../internal/engine/import_spec.go) is called only by the
-`parseImportSpecsYAML` test fixture. It duplicates mapping/field dispatch already
-owned by `parseRootDirectiveBlock` in [directives.go](../../internal/engine/directives.go).
-
-**Recommendation and acceptance.** Use the active parser with the appropriate
-context, or parse the declaration list directly when that is the tested boundary,
-then remove the obsolete implementation. Preserve malformed-declaration and
-selector coverage. Keep the active imports-only context used in layered version
-processing; thin test helpers delegating to production are not inherently dead.
-
-### F04. Remove The Disconnected Root Record-Clone Family
-
-Type: cleanup. Priority: low. Source: deadcode 3; related testing 6.
-
-**Problem and evidence.** The private family in root [records.go](../../records.go)
-has no production facade entry: `cloneLocation`, `cloneLocations`, `cloneSourceInfo`,
-`cloneImportSelections`, `cloneSourceVersionCheck`, `cloneSourceInfos`, `cloneOrigin`,
-`cloneFieldInfo`, `cloneChange`, `cloneDiagnostic`, and `cloneDiagnostics`.
-Helpers refer to each other; only tests call `cloneSourceInfo`. Active root-owned
-records come through [conversion.go](../../conversion.go).
-
-**Recommendation and acceptance.** Delete the disconnected family and tests solely
-protecting it. Keep conversion assertions and useful returned-record ownership
-coverage through repeated public queries and mutation of mutable nested results.
-Replacing an entire `Destination` field on a copied struct does not demonstrate
-nested detachment. Keep active engine clones and `Path.clone`; do not expose
-opaque path internals or invent a stronger copy guarantee. Coordinate F12.
-
-### F05. Remove Uncalled Engine Helpers
-
-Type: cleanup. Priority: low. Source: deadcode 4; placement subset also complexity 5.
-
-The type-aware audit found no callers or function-value uses in the inspected
-production/test build configurations for the following helpers:
-
-| Candidate | Active counterpart to preserve |
-| --- | --- |
-| `mergeDisjointMappings` in [compose.go](../../internal/engine/compose.go) | `mergeDisjointMappingsAtPath` and shared recursive merging; the old helper references only itself. |
-| `mergeHistoryDocument` in [history.go](../../internal/engine/history.go) | `mergeHistoryDocumentAtPath` with sequence evidence. |
-| `inheritanceDirectiveLocation` in [inheritance.go](../../internal/engine/inheritance.go) | Preparation's directive entry/location handling. |
-| `addSecretEvidencePath` in [secret.go](../../internal/engine/secret.go) | Projected version sensitivity evidence and the active path accumulator. |
-| `PlacementModeFromFacade`, `PlacementModeForFacade` in [destination.go](../../internal/engine/destination.go) | Input/options conversion and `SourceInfoPlacementModeForFacade`. |
-
-**Recommendation and acceptance.** Remove these definitions and imports/comments
-solely supporting them after confirming references at implementation time. Preserve
-active counterparts and public root APIs. The placement pair can be removed
-without selecting the broader transport work in F07.
-
-### F06. Trim Unread Private Result And Transport Members
-
-Type: cleanup. Priority: low. Source: deadcode 6.
-
-The audit identified the following populated members without production readers.
-Some private tests inspect them. Remove only these slots and computations solely
-feeding them, preserving validation and active outputs:
-
-| Owner and candidate members | Boundary to preserve |
-| --- | --- |
-| `collectionPolicyResolution.declarations`, `declarationsPresent`, `identityDeclarationPresent`, `applicationIdentityFields` in [collection_policy.go](../../internal/engine/collection_policy.go) | Local declaration normalization, `modeDeclarationPresent`, and `applicationIdentityPresent`. |
-| `inputPresence.null` in [decode.go](../../internal/engine/decode.go) | Presence/location and effective-node null reporting. |
-| `rootDirectiveExtraction.importsPresent`, `sequencesPresent` in [directives.go](../../internal/engine/directives.go) | Parsed declarations, diagnostics, and directive validation. |
-| `importSelection.outcome` in [import_selection.go](../../internal/engine/import_selection.go) and glob selection | Candidate/admission behavior and the distinct, active public `importSelectionEvidence.outcome`. |
-| `importDeclarationSpec.excludeSet` in [import_spec.go](../../internal/engine/import_spec.go) | Active `exclude` policy. |
-| `schemaPath.field`, `dynamic` in [schema.go](../../internal/engine/schema.go) | Descriptor and success result used by path consumers; coordinate A01. |
-| `selectedOverlayRequest.filesystem` in [selected_overlay.go](../../internal/engine/selected_overlay.go) | Explicit filesystem-access argument and borrowed ownership. |
-| `sequenceDeclarationSpec.destinationLocation` in [sequence_declaration.go](../../internal/engine/sequence_declaration.go) | Other active declaration/field diagnostic locations. |
-| `sourceVersionEvidence.absence`, `checked`; `sourceVersionAncestor.kind` in [source_version.go](../../internal/engine/source_version.go) | Actual checks, version/presence/location evidence, ancestor paths, and sensitivity. |
-| `postDecodeOverrideContext.sources` in [override_context.go](../../internal/engine/override_context.go) | Local source list used to build callback resolution input. |
-
-**Acceptance.** Preserve public presence, null, selection, version, diagnostic,
-and ownership behavior. Rework assertions on inactive annotations only where
-they protect a meaningful supported outcome. A lack of selector reads alone is
-not a general removal rule: map keys, embedded records, and interfaces require
-separate analysis.
-
-### F07. Simplify Redundant Facade-To-Engine Transport
-
-Deferred under OQ-3. The evidence, proposed scope, and remaining questions now
-belong to [future work](future.md#2-simplify-redundant-facade-to-engine-transport),
-for consideration after this roadmap's selected work is complete. F05's bounded
-removal of unused placement bridges remains selected.
-
-### F08. Index Secret-Failure Location Queries Lazily
-
-Type: optimization candidate. Priority: low. Source: efficiency 5.
-
-**Problem and evidence.** `secretDiagnostic` in
-[secret_reference.go](../../internal/engine/secret_reference.go) calls unindexed
-nearest-location traversal for each failed reference. N missing references in a
-wide mapping incur O(N²) comparisons, even when they use one cached environment
-name. Normal deterministic traversal/sorting does not require these scans.
-
-**Recommendation and acceptance.** Consider a lazy read-only `documentLookup`
-shared during secret resolution, or carry relevant location state through the
-walk. With V nodes, F failures, and depth D, attribution can be O(V + F × D),
-apart from sorting. Keep the successful path free of an unnecessary eager index.
-Preserve all diagnostics, ancestor fallback, source coordinates, and safe messages;
-failing fast would change behavior rather than optimize it.
-
-### F09. Cover Public Historical-Path Enumeration
-
-Type: test improvement. Priority: medium. Source: testing 2; related testing 6.
-
-**Problem and evidence.** Root `Metadata.HistoricalPaths` in
-[metadata.go](../../metadata.go) had no executed statements in the aggregate
-profile. Engine tests cover it thoroughly, but not root path conversion. An empty
-or incorrectly converted public result could leave engine tests green.
-
-**Recommendation and acceptance.** Add one external-package test enumerating
-effective and removed paths, using returned paths with `Lookup` and `History`,
-including a numeric-key/sequence shape change. Cover sorted unique pointer
-spelling, zero metadata, and replacement of a returned slice element without
-affecting later queries. Keep detailed path mutation/shape tests in the engine.
-This can replace F12's private segment-representation assertion without copying
-the complete internal matrix or exposing private segments.
-
-### F10. Strengthen Fuzz Detachment Assertions
-
-Type: test improvement. Priority: low. Source: testing 4.
-
-**Problem and evidence.** `FuzzCompositionAndOverlay` in
-[composition_fuzz_test.go](../../internal/engine/composition_fuzz_test.go) appends
-to the result root then compares inputs. A shallow root copy sharing existing
-descendants can pass because append changes neither the input's slice header nor
-elements within its old length. Existing deterministic merge tests already
-exercise meaningful nested mutation.
-
-**Recommendation and acceptance.** Mutate an existing result descendant or
-in-length element within the bounded fuzz target, then compare both inputs.
-Handle empty containers separately and retain input immutability/commutativity
-properties. Improve the existing assertion rather than adding another ownership
-matrix or claiming all ownership coverage is absent.
-
-### F11. Replace Exact Stat-Call Choreography With Observable Ordering
-
-Type: test cleanup. Priority: low. Source: testing 5.
-
-**Problem and evidence.** `TestSelectNamedImportsChecksNormalizedPathsLexically`
-in [import_selection_test.go](../../internal/engine/import_selection_test.go)
-requires `a.yaml,a.yaml,z.yaml,z.yaml` stat calls but checks candidate count only.
-Lexical handling matters; exactly two stats per file is not an established contract.
-
-**Recommendation and acceptance.** Assert ordered candidate paths and, where
-needed, the first diagnostic site using failing targets. Consolidate with existing
-selection tests and delete the standalone case if its protection is subsumed.
-Keep meaningful observations such as not opening excluded contents. Do not turn
-incidental helper call counts into an efficiency or behavior guarantee.
-
-### F12. Consolidate Facade Scaffolding Around Public Behavior
-
-Type: test cleanup. Priority: low. Source: testing 6; related deadcode 3.
-
-**Evidence and recommendations.**
-
- Remove the duplicate six-type ownership loop in
-  [facade_compatibility_test.go](../../facade_compatibility_test.go), retaining the
-  comprehensive owner in [facade_candidate_test.go](../../facade_candidate_test.go),
-  compile-time interfaces, public construction, and distinct lifecycle checks.
-  A literal assignment equality assertion on a new `Result.Config` adds no
-  protection beyond compilation and ordinary Go assignment.
- Replace the former `TestWrappedPathsRetainEngineSegmentIntent` internal
-  representation check with public contextual mapping/index behavior under F09.
-  Keep engine segment-intent coverage; public source-form behavior is consolidated
-  in [facade_equivalence_test.go](../../facade_equivalence_test.go).
- Move `TestWrappedSourcesPreserveEngineOwnership` from direct `engine.Load`
-  through `source.toEngine()` to public `Load` and root error assertions.
-  Consolidate reader cases with [facade_equivalence_test.go](../../facade_equivalence_test.go)
-  while preserving explicit copied-reader and byte-source mutation coverage.
- F04 owns removal of the disconnected clone family and the ineffective whole-
-  destination assignment assertion in [records_test.go](../../records_test.go).
-  Keep useful conversion and returned-record ownership protection there or in
-  existing public source-snapshot tests.
-
-**Acceptance.** Remove scaffolding only after preserving its distinct behavioral
-risks. Root integration tests still protect conversion, error typing, callbacks,
-source identity, disclosure, and ownership; engine coverage does not substitute
-for them. Static public/dependency-boundary tests remain useful.
-
-## Boundaries To Preserve
-
-The audits found the architecture coherent and did not establish a need for new
-public features, a replacement loading API, package proliferation, or a general
-visitor/strategy framework. Root-owned conversions, synchronous load-local state,
-shared dependency scheduling, indexed combination, separated inheritance phases,
-and passive resource contexts remain useful owners. The clone traversal was
-already reviewed and retained at `34cbc0d:docs/roadmap/consolidation.md`; a high
-complexity estimate does not reopen it.
-
-No additional supported-use data race, deadlock, background-work leak, credential
-disclosure, command injection, authority bypass, or host containment escape was
-established. These are limited audit observations, not absence guarantees.
-Caller-owned mutable objects, blocking operations, safe callback messages, and
-borrowed filesystem behavior retain their documented responsibilities. No new
-locking, cancellation, retry, authentication, permission, or environment-variable
-restriction follows from these findings.
-
-Preserve raw-error suppression, structured safe diagnostics, original application
-panic propagation, intentional bootstrap partial writes, allowed partial writer
-output, and documented read-only regular-file close handling. Regression tests
-must enforce existing contracts rather than broaden them. Optional absence must
-remain distinct from acquisition failure, and genuine finite reuse from cycles.
-
-Public APIs are not dead merely because repository examples omit them. Interface
-dispatch, reflection, build constraints, identity tokens, map-key equality, and
-uninstantiated generics require more than caller counts. In particular,
-`decodeInlineMapEntry` and import-cycle diagnostics remain active.
-`Inspection.resolution` retains recorded snapshots under the existing resolution
-contract even though replay uses a coalesced view; it is not a cleanup candidate.
-
-Selected stable Kahn ordering, deterministic sorting, exact numeric identity,
-and the expressly selected registration-overlap check are not reconsidered here.
-Required detached copies and genuinely expanding output remain legitimate costs.
-The broader replay, metadata-handoff, cross-load schema-cache, and contributor-
-trace experiments stay in [future.md](future.md#5-performance-experiments).
-Local fixes and removal of proven unused work do not select those experiments.
-
-## Validation Approach For Selected Work
-
-Use the existing [development guide](../development.md#baseline-validation) and
-[testing policy](../policy/testing.md). Add meaningful regressions with the
-selected fixes, at the narrowest stable boundary that detects the reported
-failure. Extend existing owners rather than duplicating internal matrices at
-every layer. Assert nil results and safe structured failures where relevant,
-and verify retained state/handles independently when they have distinct owners.
-
-Keep termination, allocation, and link-expansion probes bounded. Use small
-controlled budgets, disposable processes where necessary, and filesystem
-observation where it detects the specific defect. No wall-clock thresholds,
-coverage percentages, complexity-score limits, exact incidental syscall traces,
-new resource caps, or extra release gates are selected. Algorithmic evidence is
-not a measured speedup. Performance experiments need separate scope and suitable
-measurement conditions; no benchmarks were run for this consolidation.
-
-Once selected work changes behavior or structure, update its canonical contract
-or internal owner as appropriate. This review document remains the finding/status
-owner until an implementation plan is prepared; completed records can retire
-to Git history under the normal documentation lifecycle.
-
-## Original-Finding Map
-
-Original files are retrieved from `ecd5d5d:docs/roadmap/<filename>`. Every numbered
-finding is mapped below; repeated citations are corroboration or shared coverage,
-not extra fixes.
-
-| Original finding | Consolidated owner |
-| --- | --- |
-| correctness 1 | [A01](#a01-terminate-pointer-only-recursive-descriptor-traversal) |
-| correctness 2 | [A02](#a02-make-failed-dynamic-descriptor-construction-transactional) |
-| correctness 3 | [A03](#a03-distinguish-acyclic-slice-views-in-cycle-detection) |
-| correctness 4 | [B01](#b01-deactivate-callback-contexts-during-panic-unwinding) |
-| efficiency 1 | [E01](#e01-avoid-scanning-every-policy-for-each-replacement) |
-| efficiency 2 | [E02](#e02-avoid-recopying-unrelated-policy-across-small-tiers) |
-| efficiency 3 | [E04](#e04-index-tier-history-projection-lookups) |
-| efficiency 4 | [E05](#e05-restore-compound-identity-without-repeated-mapping-scans) |
-| efficiency 5 | [F08](#f08-index-secret-failure-location-queries-lazily) |
-| efficiency 6 | [A05](#a05-reuse-successful-dynamic-type-eligibility-checks-locally) |
-| complexity 1 | [F01](#f01-remove-the-test-only-eager-acquisition-mode) |
-| complexity 2 | [F02](#f02-clarify-active-acquisition-and-coordinator-handoffs) |
-| complexity 3 | [E03](#e03-clarify-policy-preparation-and-merge-evidence-application) |
-| complexity 4 | [C03](#c03-separate-glob-entry-preparation-from-traversal) |
-| complexity 5 | [F07](#f07-simplify-redundant-facade-to-engine-transport), with bounded bridge removal in [F05](#f05-remove-uncalled-engine-helpers) |
-| concurrency 1 | [B01](#b01-deactivate-callback-contexts-during-panic-unwinding), corroboration |
-| resources 1 | [A04](#a04-enforce-existing-node-budgets-before-container-reservations) |
-| resources 2 | [D01](#d01-account-for-the-complete-published-history-graph) |
-| resources 3 | [B02](#b02-close-the-owned-import-root-when-a-version-callback-panics) |
-| error-handling 1 | [C01](#c01-preserve-directory-failure-phase-and-strengthen-its-tests) |
-| security 1 | [C02](#c02-avoid-reexpanding-completed-finite-symlink-dependencies) |
-| testing 1 | Regression acceptance under A01–A04, B01–B02, C02, and D01 |
-| testing 2 | [F09](#f09-cover-public-historical-path-enumeration) |
-| testing 3 | [C01](#c01-preserve-directory-failure-phase-and-strengthen-its-tests), including shared fixture assertions |
-| testing 4 | [F10](#f10-strengthen-fuzz-detachment-assertions) |
-| testing 5 | [F11](#f11-replace-exact-stat-call-choreography-with-observable-ordering) |
-| testing 6 | [F12](#f12-consolidate-facade-scaffolding-around-public-behavior), with F04 and F09 |
-| deadcode 1 | [D02](#d02-remove-the-unconsumed-override-result-pre-cli-copy) |
-| deadcode 2 | [D03](#d03-remove-the-unqueried-published-structural-input-copy) |
-| deadcode 3 | [F04](#f04-remove-the-disconnected-root-record-clone-family) |
-| deadcode 4 | [F05](#f05-remove-uncalled-engine-helpers) |
-| deadcode 5 | [D04](#d04-stop-constructing-unconsumed-combination-evidence) |
-| deadcode 6 | [F06](#f06-trim-unread-private-result-and-transport-members) |
-| deadcode 7 | [F03](#f03-retire-the-parallel-test-only-import-directive-parser) |
-| deadcode 8 | [F01](#f01-remove-the-test-only-eager-acquisition-mode), duplicate of complexity 1 |
-
-## Settled Scope Decisions
-
-### OQ-1. What Should The First Implementation Scope Include?
-
-**Settled:** include all nine reported defects with their regression coverage,
-the bounded cleanup, and the identified independent test improvements.
-
-| Selected work | Finding IDs |
-| --- | --- |
-| Reported defects and accompanying regression coverage | A01–A04, B01–B02, C01–C02, D01 |
-| Removal of unused copies, evidence, helpers, fields, and test-only production paths | D02–D04, F01, F03–F06 |
-| Public coverage and stronger or less redundant test assertions | F09–F12 |
-
-This selects 21 review entries. Reconfirm cleanup evidence on the implementation
-baseline before removal, and preserve distinct behavioral protection when
-replacing tests. Coordinate unused history copies with D01's retained-graph
-accounting; verify callback-state closure and host-root closure independently.
-Keep fixes and cleanup in focused, reviewable commits, even if delivered in one
-sprint. Cleanup must not delay a consequential fix.
-
-The combined scope restores existing contracts and removes demonstrated
-maintenance burden while avoiding repeated work at the same ownership and test
-boundaries. Delivering defects first and cleanup separately would reduce the
-initial review surface, but would retain redundant work and revisit those
-boundaries. The combined approach is selected.
-
-Efficiency and broader structural choices are addressed separately below. This
-decision does not select new public behavior or establish an implementation
-sequence.
-
-### OQ-2. Which Efficiency Candidates Should Accompany Remediation?
-
-**Settled:** include the four localized efficiency improvements below. E01/E02
-are addressed separately with collection-policy preparation and evidence
-ownership (E03) under the settled OQ-3 decision.
-
-| Selected improvement | Scope and dependency |
-| --- | --- |
-| E04: tier-history projection lookups | Reuse a local lookup index or equivalent traversal while preserving authored coordinates and projection evidence. |
-| E05: compound identity restoration | Avoid repeated mapping scans while preserving child identity, mapping order, and detached nodes. |
-| A05: dynamic-type eligibility reuse | Reuse only completed successful checks within the operation, after A02 repairs descriptor construction failure state. |
-| F08: secret-failure location lookup | Include at lower priority; prepare lookup state lazily so successful loads avoid unnecessary indexing. |
-
-Together with OQ-1, this selects 25 review entries. These local changes address
-source-demonstrated repeated work without requiring public APIs, persistent
-caches, or a new architectural model. Preserve their behavioral acceptance
-cases and keep implementation proportionate. E01/E02 involve policy retirement
-timing and mutable ownership, so their scope belongs with the E03 discussion.
-
-Deferring all six until consumer profiling was considered. That would reduce
-initial scope and avoid optimizing uncommon workloads, but would retain known
-growth patterns with relatively direct remedies in the four selected cases.
-The selected approach does not promise a measured startup improvement; practical
-benefit depends on configuration shape and workload. Broader experiments in
-[future.md](future.md#5-performance-experiments) remain deferred. C02's availability
-fix and A04/D01's existing-budget enforcement remain selected independently.
-
-### OQ-3. How Much Structural Refactoring Should Be Selected?
-
-**Settled:** select E01, E02, E03, and F02. Defer C03 and F07 to the first two
-entries of [future.md](future.md) for consideration after the rest of this roadmap
-is complete. F01's removal of the test-only protocol remains selected under OQ-1.
-
-| Selected work | Scope |
-| --- | --- |
-| E01/E02/E03: collection-policy retirement, copying, and evidence ownership | Address the related costs and preparation/application boundaries together, retaining distinct scaling and behavioral acceptance cases. |
-| F02: active acquisition and coordinator handoffs | Extract cohesive repeated operations with clear inputs/results while preserving visible phase order and ordinary/layered differences. |
-
-For collection policy, distinguish read-only existing state, policy affected by
-incoming declarations or replacements, and the changes/evidence retained by the
-assembly. Preserve retirement timing, newly established policy, explicit-mode
-persistence, and nested record ownership. A smaller function or fewer copies
-alone does not establish success. For acquisition, moving blocks into helpers
-that continue sharing mutable surrounding state would not clarify the handoff;
-keep the existing loading model and named responsibilities.
-
-The selected combination offers a focused improvement in efficiency and
-maintainability at active ownership boundaries. Including C03/F07 now would
-broaden review for more modest readability benefits; neither is necessary for
-the selected fixes. They remain plausible follow-up work, not rejected proposals.
-Deferring all structural work would reduce immediate change scope but retain the
-policy inefficiencies and difficult acquisition handoffs. No new public API,
-generic framework, or configuration semantics are selected.
-
-Together, OQ-1 through OQ-3 select 29 entries. All scope questions are settled;
-the next step is to prepare the implementation plan with sequencing and focused
-validation. No implementation has been performed by these planning decisions.
--- a/docs/roadmap/interface-remediation.md
+++ b/docs/roadmap/interface-remediation.md
@@ -0,0 +1,346 @@
+# Interface Contract Remediation Roadmap
+
+Status: target settled, including shared history ownership; implementation has
+not begun.
+Planning baseline: `1f64673` (v0.10.2 implementation plus documentation changes).
+
+This roadmap covers the four findings in the [interface audit](interfaces.md).
+The audit owns reproductions, evidence, and finding numbers. This document owns
+the combined target, required changes, and general dependency order. A subsequent
+implementation plan should own concrete stages, private implementation choices,
+validation commands, and progress.
+
+## Purpose And Scope
+
+Restore agreement between ConfigKit's presence, metadata, history, and diagnostic
+interfaces under their existing contracts. The first three findings concern
+semantic paths that share a JSON Pointer spelling; the fourth concerns a
+composition claimant order that is lost during diagnostic canonicalization.
+
+Build one shared internal history model from which metadata history and
+explanation are derived. It will own the historical evidence and semantic
+attribution used by both views, replacing their independent reconstruction of
+that attribution. This is the selected resolution of OD-1.
+
+The [Path declarations](../../path.go), [metadata contract](../config.md#layered-metadata),
+[resolution contract](../config.md#recorded-application-resolution), and
+[strict-composition contract](../config.md#strict-document-composition) remain
+authoritative. This work changes the implementation of those contracts without
+selecting a new public API, path syntax, precedence rule, or configuration
+restriction. The existing root-owned facade and engine responsibilities remain.
+
+## Current Baseline And Targeted End State
+
+An explicit mapping-key path and an explicit sequence-index path can both render
+as `/shape/0`. `ParsePath` deliberately leaves numeric tokens contextual, whereas
+`Keys` and `Index` preserve the caller's explicit choice. The engine already has
+shape-aware effective/historical path indexes and a frozen resolution-entry view,
+but some queries and metadata updates still use pointer spelling alone.
+
+History currently reconstructs definition and previous-origin records, while
+explanation replays source contributions, inheritance, decoding checkpoints, CLI
+assignments, and grouped resolution snapshots. Neither public representation
+contains everything needed by the other. The target is shared underlying evidence
+with distinct projections for each interface, preserving their existing behavior.
+
+| Finding | Current discrepancy | Target |
+| --- | --- | --- |
+| 1: resolution presence | `IsExplicit` and `Default` consult string-keyed presence after schema validation, which cannot determine actual shape beneath dynamic values. | Presence decisions use the matching semantic path in the fixed resolution-entry state. |
+| 2: effective explicitness | Resolution retains old field information when pointer spelling survives a container-shape change. | Input explicitness carries forward for the same semantic path; a newly introduced key or index does not inherit another path's explicitness. |
+| 3: history attribution | A historical-shape check admits the query, then `History` returns the entire textual-pointer bucket; explanation selects evidence separately. | Both interfaces derive attribution from one shared history model, selecting exact definitions, previous origins, and applicable ancestor operations by semantic path. |
+| 4: claimant order | Composition constructs related locations in assembly order, then canonicalization sorts them by location. | Structured and rendered composition conflicts preserve the selected claimant order. |
+
+For example, if input contains `shape: {'0': old}` and recorded application
+resolution changes `shape` to a sequence, the old key remains an input path in
+the callback's entry view. The new index is effective in final metadata but was
+not explicitly supplied by that input. Its history must not present the old key's
+definition as its own. This distinction concerns container shape, not identity
+tracking for records that move within a sequence.
+
+## Required Changes
+
+### 1. Use Entry-State Shape For Resolution Presence
+
+In [resolution.go](../../internal/engine/resolution.go), align `IsExplicit` and
+the explicitness decision in `Default` with the frozen, shape-aware entry metadata
+already used by `InputInfo` in
+[load_metadata.go](../../internal/engine/load_metadata.go).
+
+Reuse the existing semantic-path matching machinery. A shared private lookup can
+avoid divergent presence decisions without requiring every public query to have
+identical error behavior. In particular:
+
+- Preserve `IsExplicit`'s schema-path validation and its existing diagnostics.
+  `InputInfo` remains a query that returns false for missing or mismatched paths
+  without those diagnostics.
+- Preserve `Default`'s helper-target validation, assignment, recording, and final
+  helper-value checks. Correct its presence gate; do not bypass the other checks.
+- Use entry-state shape even after application code changes the working value.
+  Explicit false, zero, empty, and null retain their existing presence meaning.
+- Keep callback lifetime and detached metadata behavior intact.
+
+A shape mismatch beneath a schema-valid dynamic path must not become explicit
+merely because its pointer spelling matches an input path. Contextually parsed
+numeric tokens continue to resolve against the entry state's actual containers.
+
+### 2. Preserve Explicitness By Semantic Path During Resolution
+
+Update resolution metadata application and field refresh in
+[load_metadata.go](../../internal/engine/load_metadata.go) to compare the relevant
+entry and final shapes before reusing presence information.
+
+The comparison must account for container kinds along the full path. A mapping
+key becoming a sequence index at an ancestor can change a descendant's semantic
+path even when its last segment and full pointer spelling stay unchanged.
+
+Keep explicitness for matching surviving paths, including descendants covered by
+an ancestor normalization record. New semantic paths introduced by resolution
+remain non-explicit, and retain the applicable recorded resolution origin.
+Removed paths leave effective metadata while remaining available to historical
+queries under the existing contract. Do not clear every descendant's presence
+just because its parent was normalized.
+
+Use the existing before/after projection and entry metadata where possible.
+This work does not require tracking every transient mutation inside a callback;
+the existing net-change and coalesced-record model continues to apply.
+
+### 3. Build A Shared Internal History Model
+
+#### Evidence And Ownership
+
+Give historical evidence one private owner in the engine. Composition,
+inheritance, decoding, CLI assignment, and resolution continue to perform their
+existing work and supply evidence to that owner. The model does not drive a
+second configuration load or repeat application callbacks.
+
+Organize the evidence into ordered groups with the phase boundaries required by
+the existing inspection contracts:
+
+| Evidence group | Information to preserve |
+| --- | --- |
+| Default baseline | Canonical typed application defaults or Go-zero values and their default attribution. |
+| Source contributions | Underlay, main-tier, and selected-overlay contributions in their existing order; exact definitions, composite origins, displaced definitions, raw policy-validated values, and sequence-position projections. |
+| Inheritance | Parent transfers, child contributions including equal-valued replacements, controlling directives and their consumption, identity-field preservation, and contribution origins/dependencies. |
+| Typed checkpoints | Pre-CLI and post-CLI typed projections and attribution needed to reconcile retained defaults and raw contributions with decoded values. |
+| CLI contributions | Explicit assignments, including equal-valued assignments, raw supplied representation, source attribution, and affected paths. |
+| Resolution | Original recorded operations, reasons, dependencies, and before/after evidence, with the grouping needed to explain overlapping records as net subtree changes. |
+
+The logical order remains baseline, source contributions, inheritance, pre-CLI
+decoding reconciliation, CLI contributions, post-CLI typed reconciliation, then
+recorded resolution. The two typed checkpoints belong on their respective sides
+of the CLI contribution phase.
+
+The groups describe logical inspection chronology, not a transcript of every
+physical mutation. Retain the existing net-change and coalescing rules for
+resolution. Preserve superseded raw input that need not decode into the final
+application type; typed checkpoints do not replace that evidence.
+
+Use a small set of ordinary private structures and existing document/path
+mechanisms. Exact types, indexes, and storage layout belong in the implementation
+plan. Complete evidence means enough for the existing history, explanation, and
+internal attribution consumers; it does not add persistence, a public event API,
+or recording of transient application effects.
+
+#### Shared Selection And Attribution
+
+Retain concrete semantic-path evidence when it is available. A query over the
+model must distinguish exact definitions from operations affecting an ancestor
+or descendant, determine the relevant previous origins, and apply sequence
+contribution coordinates at their assigned positions.
+
+The affected semantic path and the operation's reported path are distinct facts.
+For example, a replacement at `/shape` can remove a mapping key and introduce a
+sequence index with the same pointer spelling. Preserve enough before/after shape
+evidence to answer each explicit query correctly. Merely filtering `Change.Path`
+after concrete segment kinds have been discarded is insufficient.
+
+Make this selection and attribution common to both projections, including
+inheritance integration and `Previous` reconstruction. A false definition must
+not survive as a previous origin after it has been excluded from the query's
+history. Preserve genuine ancestor replacement/removal effects and chronology.
+A path that never existed does not acquire history solely because an ancestor
+changed.
+
+Keep the contextual meaning of parsed numeric tokens across historical states
+and the one-entry-per-canonical-pointer enumeration of `HistoricalPaths`.
+Indexes and compact derived records may remain, but their attribution must come
+from the shared evidence. Metadata queries should not require full configuration
+replay or YAML rendering to obtain definition and origin records.
+
+#### Distinct Public Projections
+
+`Metadata.History` produces detached definition, inheritance, and resolution
+records from the model. `Explain` reconstructs and safely renders values from
+the same evidence, retaining its existing decoding and grouping behavior. Neither
+public API should be implemented by translating the other's public result.
+
+Preserve these intentional differences:
+
+| Case | Metadata history | Explanation |
+| --- | --- | --- |
+| Several strict contributions to a mapping | Composite definition/origin information. | Each contribution's effect on the mapping. |
+| Raw input differs from canonical typed values | Definition and attribution records. | The applicable decoding reconciliation transition. |
+| Overlapping resolution records | Specific recorded attribution under the existing coverage rules. | One net subtree event with combined reasons and dependencies. |
+| Equal-valued input or inheritance operations | Explicit definition and operation attribution remains visible. | Relevant operations remain visible even when before and after values are equal. |
+
+Agreement means consistent semantic identity and attribution, not identical
+record lists. Retain original resolution records as evidence from which net
+replay groups are derived; a grouped explanation alone loses information needed
+by metadata.
+
+#### Replace Existing Attribution Machinery
+
+The common model must replace independent historical attribution, rather than
+become another representation alongside it. The implementation plan should map
+the following owners to their replacements:
+
+| Current owner | Required change |
+| --- | --- |
+| History-building portions of `metadataFromDecoded`, `applyOverlayMetadata`, and `appendPostDecodeCLIHistory` in [load_metadata.go](../../internal/engine/load_metadata.go) and [override_context.go](../../internal/engine/override_context.go) | Produce or project shared evidence instead of independently reconstructing pointer-keyed histories. Retain effective-field construction where it is still needed. |
+| Previous-origin reconstruction and inheritance insertion in [inheritance_history.go](../../internal/engine/inheritance_history.go) | Use common semantic selection and attribution while preserving the existing inheritance projection rules. |
+| Relevance and chronology orchestration in [explain.go](../../internal/engine/explain.go) | Consume the shared model; retain useful value reconstruction and redaction helpers. |
+| Separate published inheritance evidence for metadata and explanation in [load_result.go](../../internal/engine/load_result.go) | Consolidate under the frozen history owner where independent copies are unnecessary; keep required output detachment. |
+| Original and coalesced resolution evidence in [history.go](../../internal/engine/history.go) | Own original records in the model and derive the replay grouping without losing specific attribution or maintaining a second independently interpreted history. |
+
+Existing source, sequence-combination, and inheritance evidence producers may
+remain useful. Their algorithms need not be rewritten merely to contribute to
+the model. Likewise, final effective fields, the frozen resolution-entry view,
+source records, and final configuration snapshots retain their responsibilities.
+Findings 1 and 2 still require explicit presence corrections.
+
+#### Other Consumers, Lifetime, And Resource Accounting
+
+Move historical dependency reads in
+[secret classification](../../internal/engine/secret.go) and historical location
+fallbacks in [override_context.go](../../internal/engine/override_context.go) to
+the shared evidence. Do not retain the old history machinery solely for those
+readers. Preserve existing sensitivity propagation and historical classification;
+correcting attribution does not authorize narrowing redaction for paths that
+share a pointer spelling.
+
+Evidence must be available at the lifecycle stages where these internal readers
+need it, including diagnostic attribution before publication. Keep the callback's
+entry metadata fixed while later resolution evidence is added. Finalize the
+model for published queries without introducing lazy mutation of shared state.
+Private frozen evidence may be shared by the two views while their returned
+records remain detached under the existing ownership contract.
+
+Reuse retained trees and existing lookup machinery where practical. Review
+retained-history accounting against the resulting ownership graph, including
+typed checkpoints and inheritance/resolution evidence. The model does not require
+a full document copy per event, a new quota, or a new concurrency guarantee.
+Reduced duplication is a design benefit to evaluate, not a promised memory or
+speed improvement.
+
+### 4. Preserve Composition Claimant Order Through Diagnostics
+
+Keep the order produced by `compositionConflictDiagnostic` in
+[compose.go](../../internal/engine/compose.go) through accumulation, `LoadError`,
+facade conversion, and `WriteDiagnostics` in
+[diagnostic.go](../../internal/engine/diagnostic.go).
+
+Prefer a narrow internal canonicalization rule based on the diagnostic semantics
+already carried across these boundaries. Identify the composition diagnostic
+producers governed by the claimant-order contract rather than changing all
+related-location lists. Preserve canonical ordering of diagnostic records and
+the existing sorting of related locations for other diagnostics.
+
+The root renderer converts public diagnostic records back to engine records and
+canonicalizes them again. An engine-only marker discarded by facade conversion
+would therefore be insufficient. No public ordering option is needed for this
+correction. Keep primary selection, conflict detection, acquisition order, and
+dependency-ready scheduling unchanged.
+
+## General Implementation Order
+
+1. Prepare the concrete shared-evidence design and focused regression cases.
+   Map existing producers and consumers to the new owner, distinguish common
+   attribution from presentation rules, and identify the old paths to remove.
+   Select representations and indexes that preserve existing query and lifetime
+   needs without adding public contracts.
+2. Repair entry-state presence queries and `Default` (finding 1). This is a local
+   correction that can proceed independently of the larger history work.
+3. Repair final explicitness preservation (finding 2), retaining the shape evidence
+   needed by metadata updates. Coordinate this work with history construction so
+   the two fixes do not introduce competing definitions of path identity.
+4. Build the shared model and migrate metadata history, explanation, sensitivity
+   dependencies, and diagnostic-location readers. Preserve phase evidence and
+   derive both public projections through common semantic attribution. Remove
+   the superseded reconstruction paths and reconcile retained-history accounting.
+   Verify finding 3 and its interaction with final presence metadata; repairing
+   pointer buckets alone does not complete the selected architecture.
+5. Complete composition diagnostic ordering (finding 4) as an independent change;
+   it may proceed alongside the path work. Check rendering as well as the
+   structured error before considering it complete.
+6. Review the integrated result, run applicable development checks, and update
+   affected implementation documentation and finding status.
+
+These are high-level dependencies, not a requirement to combine unrelated fixes
+in one commit. The implementation plan should select concrete edits and test
+commands while keeping the four findings individually traceable.
+
+## Validation And Completion
+
+Follow the [testing policy](../policy/testing.md) and use the
+[development guide](../development.md#baseline-validation) for checks. Extend
+existing test owners rather than recreating full internal matrices at the facade.
+The focused cases should cover:
+
+- Both mapping-key/index mismatch directions beneath dynamic values, including
+  explicit paths and contextual parsed pointers. Check callback presence and
+  `Default` behavior, including the fixed entry view after working-value changes.
+- Both container-shape transitions during recorded resolution, a descendant
+  affected by an ancestor shape change, and a same-shape normalization control.
+  Check explicitness and recorded origins through final metadata and explanation.
+- Shape-changing CLI and resolution history, checking exact definitions,
+  `Previous`, and genuine ancestor replacement/removal. Include contextual
+  enumeration/query coverage and preserve existing inheritance and overlay cases;
+  add another case only where those integrations expose an unprotected risk.
+- Shared-model projections across composite mapping origins, typed decoding and
+  default reconciliation, equal-valued writes, inheritance controls/transfers,
+  mapped sequence replacements and removed descendants, and overlapping
+  resolution records. Reuse existing cases where they protect those semantics;
+  check the intentional differences between the public projections as well as
+  agreement on attribution.
+- Historical sensitivity/dependency propagation, diagnostic source-location
+  fallback, detached returned records, and complete retained-history accounting
+  under the new ownership graph. Use small controlled budget cases and existing
+  disclosure fixtures rather than memory or timing thresholds.
+- A composition conflict whose acquisition and assembly orders differ, using the
+  audit fixture. Check both published diagnostics and rendered related-location
+  order, while retaining coverage for ordinary diagnostic canonicalization.
+
+Retain existing checks for invalid schema paths, callback lifetime, detached
+records, safe historical rendering, and default/null presence semantics. Test
+observable behavior rather than a particular private index or number of copies.
+No benchmark campaign, broader audit, or new release gate is part of this roadmap.
+
+Completion requires all four findings to have implementation and regression
+evidence, appropriate development checks, and both history interfaces deriving
+semantic attribution from the shared model. Review the final producer/consumer
+map to confirm superseded independent reconstruction has been removed and
+internal attribution readers have migrated. Passing the four defect regressions
+while retaining the old parallel attribution machinery is not completion.
+
+The audit's previous passing suite is not validation of these future changes.
+Scope here does not promise identical output from different inspection interfaces
+or a universal guarantee about unrelated path-processing code.
+
+## Decision Status
+
+OD-1 is settled: build one shared internal history model with distinct metadata
+and explanation projections. The design investigation found that both views
+require evidence the other's public representation does not preserve. Shared
+ownership can replace independent attribution and redundant retained evidence,
+while keeping the current lifecycle and public contracts.
+
+The narrower repair of stored history events would leave the separate replay
+attribution owner in place. Promoting current explanation output to authoritative
+history would lose composite-definition and specific resolution information.
+The selected common underlying model addresses both concerns. This accepts a
+larger internal refactor than a local shape-filtering fix.
+
+No significant open decision remains at roadmap level. Private representation,
+indexing, and helper choices belong in the implementation plan. This roadmap
+records future implementation ownership; it does not revise accepted ADRs or
+declare the model implemented.
--- a/docs/roadmap/interfaces.md
+++ b/docs/roadmap/interfaces.md
@@ -0,0 +1,202 @@
+# API and Interface Contract Audit
+
+Reviewed baseline: `01b08e76a3fecc22c4414437bfeaa07b4b7a85aa`.
+
+Status: four open findings. This is an audit record, not an implementation plan.
+No production code or repository tests were changed.
+
+The [interface remediation roadmap](interface-remediation.md) describes the
+settled target, required changes, and dependencies, including a shared internal
+history model for metadata history and explanation. Implementation remains pending.
+This audit retains the findings and reproduction evidence.
+
+## Scope and evidence
+
+Reviewed the root-owned public facade and its conversions, engine loading and
+callback boundaries, source/discovery and filesystem ownership, schema and typed
+value handling, metadata/history, safe rendering and comparison, secrets, and
+the document/YAML boundary against declaration comments, the
+[configuration contract](../config.md), and applicable architectural decisions.
+The root delegates to the synchronous engine lifecycle; parser-independent
+documents support source assembly and inheritance, and completed results retain
+detached configuration and frozen inspection state.
+
+The findings below were reproduced through the public API with a disposable Go
+program outside the repository, using labeled byte sources and `fstest.MapFS`.
+The full existing suite passed with Go 1.26.10 on Linux:
+
+```sh
+GOTOOLCHAIN=local GOTELEMETRY=off GOPROXY=off go test ./... -count=1
+```
+
+The existing tests cover many ownership, lifetime, error, and zero-value cases,
+but do not detect these cross-interface discrepancies. No benchmarks, external
+service calls, or new test files were needed. The recommendations restore
+existing contracts rather than introduce new API restrictions or guarantees.
+
+## 1. Resolution presence queries confuse explicit keys with sequence indexes
+
+Priority: P2. Status: open.
+
+Relevant code:
+
+- [`Resolution.IsExplicit`](../../internal/engine/resolution.go), lines 75–82.
+- `Resolution.InputInfo` and `resolutionInput.lookup` in
+  [resolution.go](../../internal/engine/resolution.go) and
+  [load_metadata.go](../../internal/engine/load_metadata.go).
+- `resolveSchemaPath` in [schema.go](../../internal/engine/schema.go).
+
+The public [path contract](../../path.go) distinguishes explicit mapping keys
+from sequence indexes. The [resolution contract](../config.md#recorded-application-resolution)
+defines surviving-input presence and a fixed entry-state metadata view;
+[metadata queries](../config.md#layered-metadata) preserve container shapes.
+
+`IsExplicit` validates against the schema but then looks up presence using only
+`path.String()`. In dynamic `any` state, schema validation cannot establish the
+actual container shape. Consequently these distinct queries collide:
+
+```go
+key := configkit.Keys("shape", "0")
+index := configkit.Keys("shape").Index(0)
+```
+
+Load `map[string]any` from `shape: [input]` with a resolver that queries both
+paths, without changing the configuration. Observed results:
+
+| Query | `Resolution.IsExplicit` | `Resolution.InputInfo` found | Final `Metadata.IsExplicit` |
+| --- | --- | --- | --- |
+| Explicit mapping key | true | false | false |
+| Explicit sequence index | true | true | true |
+
+The mapping-key path never existed and should not be reported as explicit.
+Applications branching on presence receive inconsistent answers depending on
+which public query they use, even during an otherwise unchanged load.
+
+Potential remediation: use the retained entry-state semantic shape when checking
+resolution presence, consistently with `InputInfo` and `Metadata.IsExplicit`.
+Review the same string-only presence lookup in `Default` while preserving its
+existing assignment and callback-lifetime rules. Add focused public coverage for
+both mapping-to-index and index-to-mapping mismatches under dynamic values,
+including contextually parsed pointers. This does not require changing the
+documented treatment of invalid schema paths.
+
+## 2. Resolution can transfer explicitness to a different semantic path
+
+Priority: P2. Status: open.
+
+Relevant code: `applyResolutionMetadata`, `applyResolutionFieldOrigins`, and
+`refreshResolutionFields` in
+[load_metadata.go](../../internal/engine/load_metadata.go), especially lines
+371–387; final shape checking in
+[`Metadata.effectiveField`](../../internal/engine/metadata.go).
+
+The [metadata contract](../config.md#layered-metadata) distinguishes key/index
+shapes and keeps derived values for absent input non-explicit. Recorded
+resolution changes origins without creating input explicitness.
+
+Reproduction:
+
+1. Load `map[string]any` from `shape: {'0': old}`.
+2. In resolution, replace `configuration["shape"]` with `[]any{"new"}` and
+   record normalization at `Keys("shape")`.
+3. Query final metadata using the two paths from finding 1.
+
+The old explicit mapping-key path correctly stops being effective, but the newly
+created sequence index reports `Explicit: true`. That sequence index was never
+supplied by input. `refreshResolutionFields` reuses the old `FieldInfo` whenever
+its textual pointer survives; it updates null state without checking whether
+the old and new containers give that pointer different semantic shapes. Final
+lookup validates only the new shape, so it cannot recover the lost distinction.
+
+This can mislead consumers inspecting whether a final value was explicitly
+configured rather than introduced by application resolution. The converse
+sequence-to-numeric-key transition has the same underlying collision.
+
+Potential remediation: retain entry/effective shape evidence across resolution
+and carry input explicitness forward only for the matching semantic path.
+Preserve existing explicitness for same-shape paths and the recorded resolution
+origin; do not clear every descendant's presence merely because an ancestor was
+normalized. Cover both shape transitions and agreement among `Lookup`,
+`IsExplicit`, and explanation. Fixing finding 1's callback query alone does not
+repair this publication path.
+
+## 3. Metadata history mixes numeric-key and sequence-index definitions
+
+Priority: P2. Status: open.
+
+Relevant code:
+
+- [`Metadata.History`](../../internal/engine/metadata.go), lines 56–65.
+- `metadataFromDecoded`, `applyOverlayMetadata`, and history event construction
+  in [load_metadata.go](../../internal/engine/load_metadata.go).
+- Shape-aware replay in [`Inspection.Explain`](../../internal/engine/explain.go).
+
+The [metadata contract](../config.md#layered-metadata) promises semantic
+key/index distinctions for historical as well as effective queries. The
+historical-path index retains both shapes, but `History` uses that index only to
+check that the query was ever known. It then retrieves the entire history bucket
+by textual pointer, without selecting the query's shape.
+
+Reproduction: load `shape: {'0': old}` into `map[string]any`, then apply a CLI
+override at `Keys("shape")` with `[]any{"new"}`. Both explicit shapes were
+observed and share `/shape/0`.
+
+`History(Keys("shape").Index(0))` incorrectly includes the original base
+definition of the mapping key, and identifies that base origin as the previous
+origin of the CLI operation. The old input defined a key, not an index. In the
+same successful result, `Explain` for the explicit index correctly shows only
+its CLI introduction. `History` for the key and index returns identical records
+despite their different lifetimes.
+
+Consequences include false source attribution and disagreement between the two
+public history interfaces when consumers inspect removed or introduced paths.
+
+Potential remediation: retain enough container-shape evidence with stored
+history events, or select relevant events from existing shape-aware replay
+evidence. Filter exact definitions and previous origins by the queried semantic
+shape while retaining genuine ancestor replacement/removal events. Filtering
+only on the current `Change.Path` is insufficient where construction already
+replaced concrete segment kinds with parsed tokens. Preserve the intentional
+one-pointer-per-entry `HistoricalPaths` enumeration and contextual behavior of
+`ParsePath`; neither public contract needs redesign. Cover both direction changes
+and compare metadata history with explanation.
+
+## 4. Diagnostic canonicalization breaks composition claimant ordering
+
+Priority: P3. Status: open.
+
+Relevant code: `compositionConflictDiagnostic` in
+[compose.go](../../internal/engine/compose.go) and `canonicalDiagnostics` in
+[diagnostic.go](../../internal/engine/diagnostic.go), particularly lines 88–92.
+The latter runs both while constructing `LoadError` and in `WriteDiagnostics`.
+
+The [strict-composition contract](../config.md#strict-document-composition)
+specifies the first claim in scoped assembly order as primary and every remaining
+claim in the same order as related locations.
+
+A native-filesystem fixture demonstrates the discrepancy:
+
+```text
+main.yml imports a.yml, b.yml, c.yml
+a.yml imports z.yml
+b.yml, c.yml, and z.yml each define x
+```
+
+Acquisition assigns main=source-1, a=source-2, z=source-3, b=source-4,
+c=source-5. Dependency-ready assembly considers the three conflicting claims
+in b, c, z order. The composer correctly chooses b as primary and constructs
+related locations c, z. Generic canonicalization sorts those related locations
+by acquisition ID, publishing z, c instead. The reproduced public diagnostic
+has primary source-4 and related source-3, source-5.
+
+All claimants remain present and the conflict still fails loading, so this is
+lower impact than the presence/history defects. It nevertheless violates the
+documented reporting order and gives consumers two different ordering rules
+within one conflict report.
+
+Potential remediation: preserve the selected semantic ordering for composition
+claimant lists through accumulation and rendering, while retaining canonical
+ordering of diagnostic records and the established sorting of related locations
+for diagnostics without a semantic-order contract. Add one public failure-path
+case whose acquisition and claimant orders differ and verify both structured
+diagnostics and rendered output. No scheduler or precedence change is needed.
--- a/docs/roadmap/internal-boundaries.md
+++ b/docs/roadmap/internal-boundaries.md
@@ -8,7 +8,7 @@ remediation sprint: glob entry preparation (**C03**) and facade-to-engine
 transport simplification (**F07**). Their original motivation is retained in the
 [glob](future.md#1-separate-glob-entry-preparation-from-traversal) and
 [transport](future.md#2-simplify-redundant-facade-to-engine-transport) future-work
-entries and the [consolidated audit](audit.md).
+entries and the [consolidated audit](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md).

 The goal is clearer responsibility and ownership with fewer redundant internal
 representations. Both changes preserve the public API and configuration model.
--- a/docs/roadmap/roadmap.md
+++ b/docs/roadmap/roadmap.md
@@ -5,12 +5,12 @@ 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
-selected in the [consolidated audit review](audit.md#settled-scope-decisions).
+selected in the [consolidated audit review](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#settled-scope-decisions).
 It is intended for maintainers reviewing the remediation's scope and architecture.

 ## Document Ownership

- [audit.md](audit.md) owns finding IDs, original evidence, detailed remedies and
+- [Archived audit](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md) records finding IDs, original evidence, detailed remedies and
  acceptance cases, and the settled scope decisions. Its evidence has not been
  independently reproduced by writing this roadmap.
 - This document owns the combined target state, work areas, and design intent.
@@ -60,7 +60,7 @@ acceptance cases remain with their linked audit group.
 ### 1. Safe Typed-Value Traversal And Descriptor Reuse

 Selected entries: **A01, A02, A03, A04, A05** in
-[schema and typed values](audit.md#a-schema-and-typed-values).
+[schema and typed values](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#a-schema-and-typed-values).

 Make pointer-only descriptor traversal terminate in decoding and path resolution,
 while preserving supported null values and ordinary recursive structures. Make
@@ -86,8 +86,8 @@ This removes repeated descriptor-graph walks without a cross-load cache.

 ### 2. Callback, Filesystem, And Dependency Lifetimes

-Selected entries: **B01, B02** in [callback lifetime](audit.md#b-callback-and-filesystem-lifetime)
-and **C01, C02** in [filesystem traversal](audit.md#c-import-selection-and-link-resolution).
+Selected entries: **B01, B02** in [callback lifetime](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#b-callback-and-filesystem-lifetime)
+and **C01, C02** in [filesystem traversal](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#c-import-selection-and-link-resolution).

 Tie callback-context deactivation to the callback invocation with deferred cleanup
 so it runs on normal return and panic unwinding. Independently give the owned
@@ -114,7 +114,7 @@ arbitrary traversal cap or changed symlink defaults.
 ### 3. Retained History And Combination Evidence

 Selected entries: **D01, D02, D03, D04** in
-[history and retained state](audit.md#d-retained-history-and-unused-evidence).
+[history and retained state](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#d-retained-history-and-unused-evidence).

 Remove the unconsumed override-result pre-CLI copy and the unqueried published
 structural-input copy. Preserve the separate pre-CLI state used by active replay
@@ -138,7 +138,7 @@ on tests of an isolated counting helper.
 ### 4. Collection-Policy Preparation And Application

 Selected entries: **E01, E02, E03** in
-[collection policy and projection](audit.md#e-collection-processing-and-efficiency).
+[collection policy and projection](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#e-collection-processing-and-efficiency).

 Distinguish the existing policy state used for lookup, changes introduced by an
 incoming tier, and evidence retained by the assembly. Prepare incoming claims and
@@ -162,7 +162,7 @@ does not call for a generic merging framework.
 ### 5. Active Acquisition Handoffs And Private Cleanup

 Selected entries: **F01, F02, F03, F04, F05, F06** in
-[acquisition, cleanup, and test quality](audit.md#f-remaining-maintenance-and-test-improvements).
+[acquisition, cleanup, and test quality](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#f-remaining-maintenance-and-test-improvements).

 Remove the test-only eager acquisition mode so acquisition retains scopes through
 the active production protocol. Tests that need composition should invoke the
@@ -189,8 +189,8 @@ tests that only exercise disconnected helpers.
 ### 6. Local Lookup Improvements

 Selected entries: **E04, E05** in
-[collection policy and projection](audit.md#e-collection-processing-and-efficiency)
-and **F08** in [secret-failure lookup](audit.md#f08-index-secret-failure-location-queries-lazily).
+[collection policy and projection](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#e-collection-processing-and-efficiency)
+and **F08** in [secret-failure lookup](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#f08-index-secret-failure-location-queries-lazily).

 Reuse a local document lookup or equivalent traversal for tier-history projection
 instead of rescanning wide mappings for each sequence. Preserve authored
@@ -209,7 +209,7 @@ startup improvement.
 ### 7. Tests That Protect The Intended Behavior

 Selected entries: **F09, F10, F11, F12** in
-[acquisition, cleanup, and test quality](audit.md#f-remaining-maintenance-and-test-improvements),
+[acquisition, cleanup, and test quality](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/453da684d7c7d3843a5f505f5c468b4c889dc6e2/docs/roadmap/audit.md#f-remaining-maintenance-and-test-improvements),
 in addition to the regression coverage attached to each reported defect.

 Cover historical-path enumeration through the public API, including removed
Author	SHA1	Message	Date
Eric Rakestraw	f9ec66e867	Adopt shared history ownership in the interface roadmap	2026-10-26 12:36:17 +00:00
Eric Rakestraw	be5cdeb502	Plan interface contract remediation	2026-10-26 02:40:21 +00:00
Eric Rakestraw	1f64673d0d	Record API contract audit findings	2026-10-26 01:36:20 +00:00
Eric Rakestraw	01b08e76a3	Retire the completed consolidated audit	2026-10-26 01:25:35 +00:00