eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan the performance improvements

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-09 03:13:22 +00:00
parent 0c77deed05
commit 52793301ba
2 changed files with 467 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/roadmap/performance-audit.md
View File

@@ -28,6 +28,26 @@ themselves grow substantially. An output-sensitive algorithm cannot avoid
producing the output required by the existing contract. Expected map lookup
costs and path processing costs also qualify any proposed linear bound.
## Target state and selected scope
The implementation target is the same public configuration model with less
avoidable auxiliary work: presence-only queries do not materialize provenance;
path comparisons and sorts avoid repeated formatting; resolution coverage,
override overlaps, and sensitivity propagation use local path indexes;
classification collects paths directly; and frozen inspection reuses prepared
resolution/inheritance lookup data. Inheritance detection does not construct
semantic paths merely to detect a keyword. Ordered provenance collections use
membership indexes where their equality rules are straightforward.
The [implementation plan](implementation.md) selects bounded revisions from
all nine candidates below. Whole-tree explanation replay remains in place;
branch-local replay, changing the public metadata-copy handoff, global schema
caching, and indexing complex contributor trace equality remain later
experiments. These have larger ownership, memory, or equivalence risks than the
selected changes. No new consumer-facing complexity bound or performance
threshold is part of the target. The candidate descriptions retain the broader
audit context; the plan owns the selected implementation details and sequence.
## Candidates
### 1. Avoid materializing provenance for presence-only queries
@@ -67,9 +87,9 @@ Many nested scans below repeatedly invoke it. Sorting comparators also repeatedl
format paths, making formatting/allocation work proportional to comparisons
rather than items. `Lookup` formats the same query for multiple lookups.
First reuse an already formatted pointer within a function or decorate sortable
items with a pointer once. Consider an allocation-free containment comparison
over token spellings as a separate experiment. Complexity remains proportional
Reusing an already formatted pointer within a function and decorating sortable
items with a pointer once avoid repeated formatting. Allocation-free containment
comparison over token spellings is also in the selected scope. Cost remains proportional
to path length, but repeated string allocations can disappear.
Containment currently compares canonical pointer spellings, while metadata
@@ -203,11 +223,11 @@ linearly scans each mapping on its path; querying every key in a wide mapping
can therefore add quadratic lookup work. These costs compound across queries,
even if each query asks about a small unrelated leaf.
First consider preparing immutable coalesced replay descriptors once when an
inspection is constructed, and indexing relevant inheritance operations and
frozen-tree lookups. Coalescing can use an ancestor index rather than a group
scan. A later, separate experiment could replay only the queried branch and its
necessary dependencies instead of cloning whole trees.
The selected target prepares immutable coalesced replay descriptors once when an
inspection is constructed and indexes relevant inheritance history operations
and frozen-tree lookups. Coalescing uses ancestor lookup rather than a group
scan. Replaying only the queried branch and its necessary dependencies remains
a deferred experiment; whole-tree replay remains in the selected target.
Preserve the first covering coalesced group, ordered reason/dependency unions,
normalization precedence, chronology, intermediate absence/replacement, typed
@@ -274,30 +294,18 @@ to change scope rules, traversal ordering during expansion, or resource budgets.
| Public facade and detached records | Root-owned wrappers and explicit conversions preserve the public/private boundary. Some records are copied in the engine and again during conversion; eliminating a copy needs a clear internal ownership handoff, not public aliases or borrowed mutable records. `Result.Metadata()` also clones the complete metadata before queries; consumers repeatedly obtaining it pay repeated full-copy costs. Treat redesign of that private handoff as a separate, lower-priority retained-memory/ownership experiment. |
| Effective YAML, diagnostics, examples, and release/development tooling | Deterministic rendering and diagnostics require ordering and output-sized work; path comparator allocation is covered above. Safe snapshots and YAML adaptation allocate separate trees. Maintained consumer examples and check tooling are not production library hot paths; no gate or tooling changes proposed. ReleaseKit internals are outside this repository audit. |
## Recommended follow-up
## Acceptance and boundaries
Start with candidate 1 or 9 as a small, reviewable optimization, then candidate
2's local formatting reuse and candidate 5's direct classification traversal.
These avoid work without demanding new architectural machinery. Next address
candidate 3 for many recorded changes and candidate 6 for large dependency
graphs. Candidates 4, 7, and 8 are useful follow-ups for consumers with many
overrides, inspection queries, or inherited contributions.
The selected revisions preserve the existing [configuration contract](../config.md)
and [architecture policy](../policy/architecture.md): complete load results,
effective versus historical path shapes, provenance, ownership, presence,
secret isolation, and synchronous completion remain unchanged. New caps,
input restrictions, composition rules, or performance promises are not part of
this work. The plan owns implementation sequencing, validation, and evidence.
This is a prioritized backlog, not a staged implementation plan or a requirement
to implement every candidate. Before each production change, confirm the proposed
algorithm against the existing [configuration contract](../config.md), relevant
tests, and [architecture policy](../policy/architecture.md). Preserve complete
load results, effective versus historical path shapes, provenance, ownership,
presence, secret isolation, and synchronous completion. Do not add caps, reject
previously valid inputs, change composition rules, or create performance promises
to simplify an optimization.
For a selected change, add only missing behavioral regressions, run the relevant
package tests and everyday [development check](../development.md), and use race
checks where ownership/shared state changes warrant them. Follow-up measurements
can reuse existing startup, composition, underlay, inheritance, and history
benchmarks, with targeted fixtures for record count, disjoint overrides,
dependency chains, and repeated queries where coverage is missing. Prefer
allocations and bytes on the busy host; defer CPU improvement claims until
timing is representative. Benchmarks help decide whether the implementation's
complexity is worthwhile, but are not new release gates or test thresholds.
Success is removal of the identified redundant work and broad pairwise scans
without disproportionate machinery or semantic regressions. Output-sized work,
deterministic ordering, and required ownership copies remain legitimate costs.
Benchmarks may inform the tradeoff, especially allocations on the busy host,
but are not new release gates or test thresholds. Unmeasured improvements
remain algorithmic expectations rather than quantified runtime claims.