diff --git a/docs/roadmap/performance.md b/docs/roadmap/performance.md index b34bbda..581dad7 100644 --- a/docs/roadmap/performance.md +++ b/docs/roadmap/performance.md @@ -263,3 +263,46 @@ Provider caching, consumer loader redesign, removing copies required for value ownership, and replacing Cobra are outside this target. They require their own concrete motivation and review rather than following automatically from a performance optimization. + +## Open Decisions + +The first-pass formatting, lookup, and prefix-scanning changes have a clear +recommended direction. Two broader implementation choices remain dependent on +performance evidence. Resolve them when preparing the corresponding work; they +do not require a public API change. + +### OD-1: How far should backend reuse extend? + +**Recommendation:** Initially reuse the prepared backend within one invocation +and cache immutable metadata between invocations, while constructing fresh +mutable backend state for each `Execute`. This removes repeated help/usage work +and metadata translation while keeping invocation isolation straightforward. +Measure the remaining backend construction cost before expanding reuse. This is +the recommended PF-03 target, not a permanent restriction on implementation. + +**Alternative:** Retain a mutable backend tree per `App` and reset it before each +invocation. This can remove more command and flag-set construction work for +consumers that execute repeatedly. It also retains more memory and requires +careful reset of parsed values, presence, operands, contexts, streams, and other +backend state, plus refresh after registration. Choose it if measurements show +that the remaining construction cost warrants the added lifecycle complexity +and behavioral evidence establishes independent invocations. A CLI that executes +only once receives little benefit from this additional reuse. + +### OD-2: How much buffering should aggregate YAML retain? + +**Recommendation:** After prefix scanning is improved, favor retaining the native +render buffer and delivering framing and native slices as separate segments if +measurements confirm a useful memory reduction. This removes the second complete +document copy while keeping native rendering complete before that document's +delivery begins. The work includes correct accounting for cancellation and +partial output across segment writes, without changing aggregate acquisition +timing. Compare allocation savings with any additional writer-call overhead. + +**Alternative:** Retain a complete framed buffer after replacing the line splits +with prefix scanning. This keeps delivery simple and avoids additional writes +for each document. It still allocates and copies the document a second time, +which matters for large reports. Prefer it if representative documents are small +or segmented delivery provides insufficient benefit to justify its extra error +handling. Either choice can deliver PF-04's initial prefix-scanning improvement; +record the selected buffering approach and its evidence.