diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 657ec69..3b56b7d 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -75,3 +75,97 @@ overlay, and passive-resource-context tests. Add a focused behavioral regression only for a consequential gap exposed by the change; do not assert incidental canonicalization/stat call counts. Run the development check and applicable ownership race checks after remediation. + +## Algorithmic Audit Scope + +Audited worktree: `d898cb1`, with production code at the reviewed implementation +revision above. This follow-up used source inspection and graph caller traces, +not benchmarks or new runtime measurements. It covered acquisition and import +bookkeeping, scope scheduling and projection, filesystem context handoffs, +inheritance preparation/combination/finalization, and reflective projection and +schema construction. + +Findings 2–3 are retained inefficiencies in paths carried through the refactor, +not algorithmic regressions introduced by the consolidation. They warrant +focused follow-up without changing the selected configuration model. The audit +did not identify an additional correctness defect. Finding 1 remains open. + +The selected stable Kahn scheduler, deterministic sorting, composition rules, +scope boundaries, and required ownership copies are not reconsidered here. +Previously deferred experiments in [future.md](future.md#3-performance-experiments) +and the [clone review](future.md#4-clone-traversal-review) retain their separate +disposition. These findings do not establish new public complexity guarantees, +input restrictions, performance thresholds, or release gates. + +## 2. Avoid Searching All Sources For Each Empty Import Selection + +Status: open. Priority: low. Category: algorithmic efficiency. + +**Evidence.** `walkDeclarations` calls `recordEmptyImportSelection` for each +optional declaration that admits no source. In +[import_acquisition.go](../../internal/engine/import_acquisition.go), lines +289–300, the latter finds the declaring source by scanning `s.sources` from the +beginning, even though traversal already knows which source owns the declaration. + +**Complexity.** With S acquired sources and D empty declarations, source lookup +takes O(S × D) comparisons in the worst case, excluding path-copying and source +selection itself. A broad main import of N constant-size fragments, each with +one empty optional declaration, visits source positions 1 through N: the sum of +lookup work is Θ(N²), despite linear source and selection-evidence volume and +constant import depth. Existing input budgets bound the workload but do not +remove this avoidable scaling within those budgets. + +**Potential refactoring.** Carry the declaring source's integer index through +the declaration traversal, or maintain a traversal-local source-ID-to-index map. +Either approach makes each evidence-owner lookup O(1), with O(S + D) total +bookkeeping for the map alternative. Keep source order and IDs unchanged. Use +indices rather than retained pointers into the appendable source slice, and +preserve optional-missing rollback and failed-source retention if maintaining +an index across admission. + +**Verification.** Reuse the source-local/detached empty-selection and partial +failure coverage in [import_evidence_test.go](../../internal/engine/import_evidence_test.go). +A broad-fragment behavioral case is useful if existing coverage does not protect +the chosen index handoff. Verify the removed scan by source review rather than +adding timing thresholds or assertions about private lookup counts. + +## 3. Restrict Import-Scope Edge Preparation To Relevant Nodes + +Status: open. Priority: medium. Category: algorithmic efficiency and allocation +scaling. + +**Evidence.** `scheduleAcquisitionScopes` in +[imports.go](../../internal/engine/imports.go), lines 57–64, recursively schedules +the outer scope and every pending item-local scope using the same complete +inclusion graph. `scheduleContributionSlots` in +[import_graph.go](../../internal/engine/import_graph.go), lines 185–213, constructs +a local identity-to-slot map but then scans every graph edge and allocates an +edge slice with capacity `len(graph.edges)` for each scope with at least two +eligible contributions. Most edges need not touch that scope. + +**Complexity.** For Q such scopes and E inclusion edges, preparing the scheduler +inputs takes O(Q × E) edge inspections and requests O(Q × E) edge-slice capacity +over the operation. This is cumulative allocation demand, not a claim that all +those slices remain live together. For N sibling item imports, each with one +distinct mapping helper, Q and E are both Θ(N), making this preparation Θ(N²) +even at constant nesting depth. The selected scheduler itself is not the +problem: each small item-local graph has constant size, and the outer graph +requires its normal deterministic scheduling work. + +**Potential refactoring.** Build a traversal-local adjacency index once after +acquisition, then gather edges for a scope by its participating source identities +and retain only edges whose endpoints both have local slots. Alternatively, +partition the existing edges by their applicable scopes once. Preserve the +current endpoint-membership rule, item-boundary representation, slot placement, +group scheduling, and stable Kahn tie-breaking. For the broad sibling family, +this reduces edge preparation to O(E + P), where P is the total number of local +slots, followed by the unchanged scheduler cost. Keep this an indexing change +around the agreed scheduler, not a different ordering algorithm or a cross-load +cache. + +**Verification.** Reuse item/helper interleaving and grouped import scheduling +coverage in [imports_test.go](../../internal/engine/imports_test.go) and +[load_request_test.go](../../internal/engine/load_request_test.go), together with +existing destination/provenance evidence tests. Cover broad independent item +scopes if a consequential gap remains; verify index construction and edge +visitation bounds by source review without new performance gates.