diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 6201140..9adc0f2 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -97,7 +97,10 @@ causes in a global priority order, allowing a collaborator's sentinel to hide the enclosing operation's category. Map the owning boundary independently while retaining the original cause for `errors.Is`/`errors.As`. Add composed cause regressions; simply reordering global checks can break legitimate direct -not-found versus load-failure distinctions. +not-found versus load-failure distinctions. Carry explicit owning-operation +information through translation. Retaining nested causes may legitimately make +multiple public categories match through `errors.Is`; the remedy preserves the +owning category rather than requiring category exclusivity. Sources: [Error handling 1](06-error-handling.md#1-nested-collaborator-errors-can-hide-the-owning-operations-public-category), [Testing 4](08-testing.md#4-error-tests-miss-composed-causes-and-pre-dispatch-diagnostic-failures). @@ -123,6 +126,8 @@ local request-construction failures through `ErrInvalidRequest` and add a no-dispatch regression. Preserve intentionally completed diagnostic outcomes for missing credentials, capacity outcomes, and unsupported or inapplicable operations; not every no-dispatch outcome is invalid configuration. +Use explicit preparation-stage failure information rather than inferring the +stage from a sentinel alone or from an empty attempt list. Sources: [Error handling 3](06-error-handling.md#3-inference-diagnostics-swallow-some-invalid-request-construction-errors), [Testing 4](08-testing.md#4-error-tests-miss-composed-causes-and-pre-dispatch-diagnostic-failures). @@ -200,6 +205,12 @@ safely. Preserve foreign-owner rejection, one-time claim, namespace-view behavior, and available details. This is unnecessary retention when a handle outlives its engine, not evidence of an ever-growing global leak. +Prefer a small standalone ownership token that preserves identity after +use/discard without retaining the runner graph. Its distinct identity must not +depend on zero-sized allocations comparing unequal. If clearing the owner +pointer instead, synchronize the currently unlocked ownership check with that +mutation and preserve ownership/state behavior under concurrent claim/discard. + Sources: [Resources 3](05-resources.md#3-inert-prepared-handles-retain-their-entire-execution-owner). ## 17. Bound Repair Feedback's Temporary Serialization @@ -211,6 +222,11 @@ incrementally, preserving the existing output semantics and complete stored validation diagnostics and previous candidate. A new raw-diagnostic input limit is not implied. +Use representative allocation measurements for large and heavily escaped +diagnostics to assess the remedy, alongside the existing output-behavior tests. +Keep the encoder proportionate; the output bound does not establish an exact +peak-heap guarantee or justify a general-purpose encoding framework. + Sources: [Resources 4](05-resources.md#4-repair-feedbacks-output-bound-does-not-bound-its-temporary-serialization). ## 18. Detach Normalized Session IDs From Large Input Strings @@ -232,6 +248,10 @@ Clone ownership once or use a single traversal while retaining recursive-map, null, and array semantics. Coordinate with entry 24 without assuming all JSON walkers have interchangeable policies. +Compare representative nested overlays before and after the change for +allocation/work reduction. Balance the measured benefit against implementation +complexity, preserving input isolation instead of removing necessary copies. + Sources: [Efficiency 2](02-efficiency.md#2-recursive-provider-overlay-repeatedly-clones-descendant-subtrees). ## 20. Index Filtered Listings By Namespace @@ -242,6 +262,12 @@ buckets or equivalent ranges so queries operate on the relevant subset. Preserve ordering, exact identity matching, cancellation, and caller-owned results. A pagination API or runtime cache is not needed for this improvement. +Evaluate representative namespace counts and match sizes, including absent +namespaces, and account for additional construction cost and retained indexing +memory. Choose buckets or ranges based on that tradeoff. These measurements and +those for entries 17 and 19 inform the changes; they add no performance contract +or recurring release gate. + Sources: [Efficiency 3](02-efficiency.md#3-filtered-listings-copy-and-scan-the-complete-inventory). ## 21. Share Schema Compilation And Declare The Runner's Real Dependency @@ -264,8 +290,9 @@ validation, resource capture, and effective-profile construction. Extract focused helpers with visible inputs and ownership, rather than another generic validation framework. Preserve final-handoff validation, presence/null rules, origins, and meaningful fail-fast/error-precedence behavior. Do not turn -incidental ordering of independent validation failures into a new guarantee. The configuration-boundary ADR remains -authoritative; this is not a proposal to inspect raw ConfigKit sources. +incidental ordering of independent validation failures into a new guarantee. +The configuration-boundary ADR remains authoritative; this is not a proposal +to inspect raw ConfigKit sources. Sources: [Complexity 2](03-complexity.md#2-decompose-configuration-validation-and-resource-materialization). @@ -292,6 +319,10 @@ numbers, schema keys, and ownership. Infallible projection must not acquire new errors, panics, or silent zero-value fallbacks. Entries 3 and 5 remain separate source-conversion defects, not reasons to reject pre-handoff sources. +Retain separate small traversals where ownership or validation policies differ +enough that sharing would require a configurable reflection framework. Reducing +duplicate code is useful only when it also simplifies the supported behavior. + Sources: [Complexity 4](03-complexity.md#4-clarify-ownership-and-policies-across-the-json-value-walkers), [Equivalence 2](10-equivalence.md#2-centralize-structural-copying-of-already-normalized-json-values). @@ -370,7 +401,9 @@ materialization. Use the captured output contract and text as their respective sources of truth. Preserve real YAML `content_file` loading, origins, and the request-override default rule. Removing serialized internal fields changes current definition hashes: retain documented opaque equality relationships, -not an invented bit-identical encoding promise. +not an invented bit-identical encoding promise. Record the observable hash +change in release notes so consumers can account for invalidated comparisons +or caches, without establishing a permanent hash algorithm or encoding contract. Sources: [Dead code 2](12-deadcode.md#2-retire-legacy-fields-in-the-captured-prompt-representation).