diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 809e6b7..32cdd90 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -114,6 +114,87 @@ recorded application-derived defaults. Compare `InspectPrompt`, and retain existing source-presence cases. Include a collection case if the fix introduces separate root/collection handling; the current capture logic is shared. +### 4. Avoid Expanding Inheritance Provenance For Input-Presence Flags + +Status: open for consideration. Priority: P3. Implementation stage: 6. +Related to finding 3; consider addressing them together. + +Locations: `internal/configuration/load.go:173–178` and `208–216`. + +Capture calls `Metadata.Lookup` three times per declared input, then retains only +the `Explicit` and `Null` flags. In the selected ConfigKit v1.4.0 implementation, +`Lookup` also materializes and copies the field's complete inheritance-step list. +ConfigKit keeps that evidence compact internally; the full projection is useful +for operator inspection, but unnecessary for these flags. Its public +`Metadata.IsExplicit` method performs the effective-field query without that +projection. + +Complexity: for `I` input declarations and inheritance depths `h_i`, these +presence queries perform `O(I + sum(h_i))` provenance work, apart from path +processing. A chain of `N` prompts inheriting a constant-sized input declaration +has depths `0..N-1`, producing quadratic ancestry-step work and cumulative +temporary allocations merely to capture linear-sized presence data. Reading one +metadata snapshot, as selected in the plan, does not eliminate this per-query +expansion. + +Refactoring opportunity: combine effective typed values/pointer presence with +`Metadata.IsExplicit` where source explicitness is actually needed. Nullable +content-type and description pointers already distinguish retained values from +absent/null metadata for their public reports. Avoid requesting a complete origin +solely to classify presence, while correcting the default-value handling in +finding 3. Presence classification can be linear in the number of declarations, +plus ordinary path-query costs, independent of inheritance-chain length. + +Keep full `Lookup` operations where source origins are genuinely needed for +resource binding. This finding does not propose a different inheritance algorithm, +metadata snapshot policy, inspection contract, or source-origin fallback. + +Verification: preserve inherited, omitted/null, explicit-false, empty-string, and +application-default metadata outcomes. Confirm from the call path that the +presence-only phase no longer projects inheritance steps. No timing threshold or +real-world benchmark is needed to establish that algorithmic change. + +### 5. Share Immutable Backend Defaults Across Profiles Without Overrides + +Status: open for consideration. Priority: P3. Implementation stage: 6. + +Locations: `internal/configuration/targets.go:27–29` and `68–78`, +`internal/backend/registry.go:39–48`, and +`internal/domain/smoke_diagnostics.go:124–128`. + +Every captured profile selecting a backend calls the registry's defensive-copy +lookup. That lookup deep-copies the backend's provider parameters, and the +profile retains the copied map even when it has no provider-parameter overrides. +Many profiles selecting one backend therefore retain many identical immutable +trees. This is an inherited cost reused by the new capture path, not a newly +introduced regression. The plan selects precomputed execution profiles and +ownership boundaries, not duplication of identical defaults within the owned +snapshot. + +Complexity: for `P` profiles sharing one backend with `S` provider-value nodes and +no profile-level provider maps, this step costs `Theta(P*S)` copying time and +retained parameter storage, despite only `O(P+S)` distinct input data. The cost is +quadratic when both dimensions grow together. Existing ID sorting is additional +work and is not the target of this finding. + +Refactoring opportunity: obtain an owned backend-default snapshot once per +backend and share its provider map read-only among profiles without overrides. +Keep separate merged maps when a profile needs its own provider parameters. +For the no-override case, default-map copying and storage can become `O(P+S)`; +the existing sorting and public result-copy costs remain unchanged. A small +construction-local cache or use of already owned immutable definitions is +sufficient; a general persistent-map framework is unnecessary. + +Preserve defensive `GetBackend` semantics and copies at runtime/caller/client +boundaries. `GetProfile` already detaches the selected target's provider map, so +sharing construction-owned defaults need not expose shared mutable state to +consumers or merge caller requests into retained configuration. + +Verification: review copy placement to establish the reduction, and retain +backend/profile mutation isolation, override-merge, prepared-state ownership, +and injected-client mutation coverage. Do not make internal pointer sharing a +public guarantee or introduce benchmark thresholds. + ## Initial Review Results And Validation - Stage 1: ConfigKit v1.4.0, unchanged Go minimum, and commit-pinned attribution @@ -160,3 +241,31 @@ generation, observation, rendering, and validation. No other integration defect was found. The prior full-suite and vet results remain applicable to unchanged implementation code. No repository implementation or test files were changed by this review. + +## Algorithmic Review + +The third review considered stages 1–17 in order, excluding algorithm choices +expressly selected by the plan. Findings 4 and 5 record two local optimization +opportunities; findings 1–3 remain unchanged. No additional ordinary correctness +bug was found. + +- Stages 1–3: checked the selected metadata API costs, constant-time budget + defaulting/conversion, and the unchanged bounded repair/preparation paths. +- Stages 4–6: checked shared data declarations, per-resource normalization and + validation, known-value ownership traversal, presence capture, and profile + construction. Nested resource/input loops traverse distinct data; the two + findings concern hidden work in helper calls rather than loop syntax. +- Stages 7–9: native reporting remains delegated; diagnostic copying is linear + in returned records/locations, and the constructors add no repeated load or + configuration-sized work to ordinary execution. +- Stages 10–15: checked migrated test and example helpers for additional passes + or algorithm changes; they do not introduce another production loader or + runtime resource scan. +- Stages 16–17: checked the findings against the accepted ownership, inspection, + ordering, and configuration-boundary decisions. Deliberate lexical inventories, + native ConfigKit algorithms, and full-prompt repair remain outside reconsideration. + +This was static complexity analysis of PromptKit and the relevant calls into the +selected ConfigKit release. No performance measurements or benchmarks were run. +Implementation code is unchanged, so prior functional validation remains +applicable; this pass validates the findings-document diff only.