From 37582e9c30ef257fedee46c6d689288781a83864 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 16:13:53 +0000 Subject: [PATCH] Record schema copying efficiency finding --- docs/roadmap/remediation.md | 71 +++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 03d5340..aa92389 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -138,6 +138,57 @@ general ownership statements. Do not add bounds to schemas to make the old wording true. This is a documentation correction, not a request for new limit options, schema guarantees, or additional runtime validation. +## 4. P3 — Allocate Trusted Slice Copies By Length, Not Spare Capacity + +Status: open; efficiency improvement for consideration. Identified by the +algorithmic audit. Relevant stages: 1 and 6. + +Location: `internal/jsonvalue/trusted.go:50` in `cloneTrustedReflect`. + +### Complexity And Evidence + +The revised copier allocates slices with: + +```go +reflect.MakeSlice(value.Type(), value.Len(), value.Cap()) +``` + +It then copies only `value.Len()` elements. For a slice of length N and capacity +C, the backing allocation reserves O(C) element slots although the value being +detached contains only N elements. C can be arbitrarily larger than N, so this +allocation is not bounded by the logical slice contents. Repeated prepared-detail +or notification projections can repeat that excess allocation. + +Before this sprint, the `[]any` fast path used `make([]any, len(v))` and the +`[]string`/`[]byte` paths copied populated elements without reproducing arbitrary +spare capacity. Removing those paths routes them through the capacity-preserving +reflection branch. In particular, currently accepted inactive runtime schema +values can carry a caller-allocated slice directly into this path. + +A small public-API structural check prepared an inactive `Schema` containing a +`[]any` with length 1 and capacity 32. Its detached `Details()` copy also had +length 1 and capacity 32, confirming that unused capacity is allocated again. +This was a value-shape check, not a timing, profiling, or memory-usage benchmark. + +### Refactoring Opportunity + +Allocate detached slice storage from the populated length, e.g. +`reflect.MakeSlice(value.Type(), value.Len(), value.Len())`, and retain the +existing element-copy behavior. This reduces backing-storage space to O(N), +while element traversal remains O(N). Preserve concrete slice types, contents, +nil-versus-empty behavior, and independence from caller storage. Spare capacity +is not a requested public contract; do not add one. + +This is distinct from finding 1: the example's elements are already detached +correctly, but too much backing storage is allocated. Omitting inactive schema +values may remove this particular public entry path; restoring/simplifying the +shared copier as part of that fix can also address the allocation regression. +Do not introduce schema limits or a general object-graph facility to solve it. + +Use focused internal slice-copy coverage for small populated/empty slices with +large spare capacity, alongside existing ownership and nil/empty tests. No new +benchmark gate or public exact-capacity guarantee is needed. + ## Review Coverage And Validation The initial implementation review covered configuration/root capture, effective @@ -168,3 +219,23 @@ preparation failure. Those interactions passed. It also confirmed acceptance of the large inline annotation described in finding 3. The earlier race-suite/vet results apply to the unchanged implementation; no live provider calls or performance measurements were used. + +### Algorithmic Audit + +Reviewed the unchanged implementation at `4120d78` against the eight stages. +Finding 4 is additional; finding 2 already records the avoidable schema-sized +lookup traversal and is not duplicated here. + +Root capture uses a shared metadata snapshot and indexed root selection rather +than rescanning configuration per prompt. New schema selection/binding has no +growing nested scan. File reading grows its buffer amortized-linearly, and +decoded documents take linear copy passes through the selected ownership paths. +Prepared execution and repair reuse the captured plan instead of multiplying +schema reads/compilation by the number of attempts. Fixed test/example fixtures +add no unbounded algorithmic workload. + +The expressly selected JSON conversion, existing schema-location/portability +checks and compiler behavior, and existing hash algorithms were not reopened. +No additional ordinary correctness issue was found beyond the recorded findings. +No real-world performance data, timing measurements, or profiling were collected; +the earlier successful suite/vet results apply to unchanged implementation code.