diff --git a/docs/roadmap/planning-assessment.md b/docs/roadmap/planning-assessment.md new file mode 100644 index 0000000..e5fc559 --- /dev/null +++ b/docs/roadmap/planning-assessment.md @@ -0,0 +1,292 @@ +# Audit Remediation Planning Assessment + +## Purpose And Authority + +Work through the unresolved design and evidence-dependent choices in the +[audit remediation roadmap](audit-remediation.md) before writing its staged +implementation plan. Each numbered topic below is an assessment unit: gather +the stated evidence, compare viable approaches, and record a recommendation +before proceeding to the next topic. + +The [catalog's six accepted decisions](audit/catalog.md#resolved-decisions) +remain authoritative. This assessment selects ways to implement those decisions; +it does not reopen them or repeat the repository-wide audits. Catalog numbers +below identify the relevant findings, not additional implementation stages. +All assessment topics are initially pending. + +## Assessment Method And Outputs + +Read the [contributor guide](../development.md) and applicable policies before +each topic. Reuse existing audit evidence, source inspection, and successful +checks where sufficient. Prefer graph discovery for callers and dependencies, +then inspect the relevant code, contracts, and tests. Follow the +[configuration-boundary ADR](../adr/0001-configuration-boundary.md). + +This is analysis, not remediation. Do not change production code, dependencies, +installed toolchains, public contracts, or repository tests during the +assessment. No prototype or alternative implementation is needed. Use existing +offline benchmarks and tools where helpful; temporary measurement harnesses +outside the repository are appropriate only when needed to answer a specific +question. Record their setup sufficiently to interpret or repeat the results. +Do not use live inference, credentials, or private production data. + +Append an assessment record beneath each completed topic containing: + +- **Evidence:** repository commit, concrete declarations/callers/tests, relevant + dependency version, and measurements or commands actually used. +- **Alternatives:** plausible approaches and their semantic, maintenance, and + resource tradeoffs. Do not manufacture alternatives to an obvious correction. +- **Recommendation:** the selected design or a justified proposed deferral, + affected boundaries, and reasoning. Distinguish observed results from inference. +- **Plan handoff:** consequential signatures, fields, algorithms, or ownership + transitions to specify; dependencies; migration/documentation impact; and + implementation-time validation needed. +- **Status:** assessed, or a specific remaining uncertainty and the next bounded + investigation needed. Assessment completion does not mean remediation complete. + +For measurements, record the selected Go version, workload size/shape, and the +relevant time, allocations, bytes, or retention evidence. Use small ordinary +cases and larger valid cases to distinguish fixed overhead from scaling. +Repeat noisy measurements only as needed; do not introduce benchmark thresholds, +a generalized benchmark project, or a recurring release gate. Code-based work +counts can establish avoidable traversal without timing every helper. Do not +present estimated improvements as measured results from unimplemented code. + +Recommendations should settle consequential implementation choices, not private +helper names or equivalent coding details. Proceed between topics without new +human-review or publication gates. If evidence requires changing an accepted +decision or broadening scope, identify that question for the maintainer rather +than silently selecting a new contract. + +## 1. Establish The Evidence And Toolchain Baseline + +**Catalog:** 1; applies to subsequent measurements. + +Collect the current commit and worktree state, dependency versions, available +Go installations, and the effective toolchain used by existing development and +release commands. Compare the selected local toolchain against the specific +networking fixes identified in the security audit, using authoritative upstream +information where needed. Distinguish library/client applicability from server +or platform-only findings and uncertainty about downstream builds. + +Recommend the toolchain to use and any environment update needed before +remediation validation. Record an unavailable patched toolchain as environment +work to schedule, not permission to install one during assessment or to stop +independent source analysis. Retain the accepted separation between maintainer +selection and consumer minimum; do not add consumer advisories or scan gates. + +## 2. Specify Direct ConfigKit Source Handoff + +**Catalog:** 3, 5; informs 24. + +Inspect the pinned ConfigKit `Mapping` contract and implementation at the +snapshot/error boundary, plus both PromptKit convenience helpers and their +callers. Establish which ordinary field projections remain, when values are +captured, and how unsupported values, cycles, and shared graphs reach deferred +diagnostics. Inventory existing fixtures using formerly converted types. + +Recommend the exact removal boundary for the compatibility converter, supported +handoff cases, and migration examples. Identify which current tests remain +meaningful and which assert intentionally removed accommodation. Do not design +a replacement converter, pre-validation pass, or upstream feature. Existing +upstream ownership evidence is sufficient; exhaustive ConfigKit limit testing +is not an assessment deliverable. + +## 3. Specify Self-Contained Schema Resolution And Compilation + +**Catalog:** 6, 15, 21; coordinates with 32. + +Inspect the pinned schema compiler's resource registration/loading facilities, +the four direct/prepared and host-file/`fs.FS` paths, native-schema projection, +and runner validation interfaces. Establish where root loading, reference +resolution, compilation, cancellation, and malformed-output short-circuiting +occur. + +Use a compact semantic case inventory to distinguish references resolved inside +the supplied document from references needing another document. Include local +fragments, anchors, recursion, and supported identifiers/base-URI behavior; +preserve existing dialect support rather than adding it. Do not equate an +external-looking reference string with external resource loading without +checking resolution semantics. + +Recommend the shared compilation boundary, needed source adapters and internal +interface signatures, and external-resource rejection/error path. Identify +obsolete loaders/tests and retained containment, single-file, freezing, and +direct-validation cases. Specify how the provider receives the self-contained +document unchanged in meaning. No bundler, schema rewriting prototype, or +live provider compatibility experiment is needed. + +## 4. Specify Ownership And Retention Remedies + +**Catalog:** 4, 16, 18. + +Trace public artifact adaptation and prepared-handle creation, claim, discard, +details, and namespace-view operations. Inspect which references keep an engine +alive and which synchronization owns state changes. Trace session normalization +to its retained copies. Use reference/lifetime analysis first; use an existing +allocation profile only if the retained graph is unclear. + +Recommend the artifact contract/documentation changes under accepted ownership +transfer, retaining the defensive copy initially. Specify the prepared-handle +ownership identity and state transitions without relying on distinct zero-sized +allocations comparing unequal. Identify the session-string detachment point. +List relevant concurrent and mutation regressions for implementation, without +building a new ownership framework or changing lifetimes during assessment. + +## 5. Specify Error Ownership And Preparation-Stage Information + +**Catalog:** 7, 8, 9; informs 25. + +Trace representative collaborator failures through internal wrapping and public +translation, including direct lookup failures and nested public sentinels. +Inspect body-reader errors at initial decoding and end verification, current +redaction, context precedence, and retry classification. Trace diagnostic +preparation versus dispatch, including legitimate completed no-dispatch cases. + +Recommend how owning-operation information and preparation-stage failures are +represented and propagated. Specify the distinction between stream I/O failure, +malformed/truncated content, size overflow, and cancellation using existing +boundaries where possible. Give a small expected-outcome matrix of public +category, retained cause, diagnostic completion, and dispatch behavior. Retained +causes may match multiple sentinels; category exclusivity is not the target. + +## 6. Specify Authentication Overflow Reporting And Adapter Ownership + +**Catalog:** 2, 26, 27; uses topic 5's error/stage conclusions. + +Inspect public/domain diagnostic DTOs, outcome labels, body ownership, HTTP +evidence, authentication recognition, and facade projection. Determine whether +the selected overflow outcome fits existing fields or needs an explicit +additive representation. Inventory actual smoke-copy consumers rather than +assuming full reports need cloning. + +Recommend concrete field/type or outcome changes and their public/internal +mapping. State the facts reported for overflow: acceptance unknown, explicit +limit evidence, and independently available HTTP status/timing. Explain the +interaction with non-success statuses and cancellation without discarding +established independently known evidence. Preserve neutral reporting and privacy. + +Specify the bounded read/overflow detection operation around the accepted 1 MiB +allowance, including exact-boundary, missing/inaccurate length, and close behavior. +Recommend the outbound protocol-adapter seam and narrow target-copy operation. +Keep the body-bound fix independently implementable before adapter relocation; +do not add a public budget option or general diagnostic plugin framework. + +## 7. Assess JSON Copying Compatibility And Provider Overlay Cost + +**Catalog:** 19, 24; uses topic 2's converter-removal boundary. + +Inventory callers of facade copying, runtime JSON validation/copying, prepared +snapshots, and configuration overlay. Build a compact compatibility matrix for +accepted concrete types, nil/indirection handling, exact numbers, empty keys, +error behavior, bounds, and mutable ownership. Separate trusted-value copying +from fallible input acceptance and source encoding. + +Collect existing overlay benchmark/allocation evidence, supplemented only where +needed with representative depth, breadth, overlapping/disjoint maps, and array +replacement cases within current limits. Identify repeated visits/copies and +their construction-time cost; respect the existing bounded-depth qualification. + +Recommend which traversal can actually be removed, the shared operation's +contract, and the overlay algorithm/ownership model. Prefer retaining a small +distinct walker over a configurable framework when policies differ. Recommend +implementing or explicitly deferring the optional overlay optimization based on +expected benefit and complexity; identify estimates as such. Do not add errors, +panics, or silent fallbacks to an infallible facade projection. + +## 8. Assess Requirement Evidence Accumulation And Traversal + +**Catalog:** 10, 23. + +Trace ownership and merging of condition-evidence sets and the shared versus +node-specific responsibilities of `if`/`with`. Inspect real-renderer comparison +tests and scope/reachability cases. Collect operation counts or targeted +baseline measurements across increasing left-heavy recognized conditions; +include a small ordinary case so pathological scaling is not the only input. + +Recommend an accumulation/merge algorithm and a narrow branch-orchestration +boundary, explaining expected work without promising a new universal complexity +contract. Keep the algorithmic fix distinct from traversal cleanup. Specify +preserved dot/root scopes, inactive computed names, and conservative incomplete +analysis. No interpreter, expanded grammar, or expression limit is proposed. + +## 9. Assess Bounded Repair-Feedback Encoding + +**Catalog:** 17. + +Inspect feedback framing, JSON escaping, truncation, and the locations retaining +full diagnostics and prior output. Measure current formatting with ordinary, +large, and heavily escaped synthetic diagnostic strings, separating final output +size from temporary allocations. Identify which complete serializations account +for the avoidable memory cost. + +Compare a bounded incremental approach with the current implementation using +source-level algorithm and complexity reasoning; no alternative encoder needs +to be built. Recommend an encoding/truncation approach and its preservation +cases, or a justified proposed deferral if benefit does not warrant complexity. +Any deferral must acknowledge the outstanding allocation issue. Do not cap raw +diagnostics, discard stored errors, or assert an exact peak-heap guarantee. + +## 10. Assess Namespace Listing Index Tradeoffs + +**Catalog:** 20. + +Inspect inventory capture, namespace identity, ordering, filtered retrieval, +cancellation, and result detachment. Gather baseline time/allocation evidence for +unfiltered listings and sparse, dense, and absent namespace matches at ordinary +and larger valid inventory sizes. Consider both a single request and repeated +namespace inspection, without assuming every consumer repeatedly lists entries. + +Compare captured buckets/ranges with the existing scan. Account for construction +work, retained index memory, and query output copying; do not optimize query time +while ignoring its construction/retention tradeoff. Recommend a specific layout +and query algorithm, or a justified proposed deferral. No pagination, runtime +cache, or new ordering/cancellation guarantee is needed. + +## 11. Select Remaining Refactoring, Test, And Cleanup Boundaries + +**Catalog:** 11–14, 22, 25, 28–34; consolidate related conclusions above. + +Reuse existing audit evidence and perform targeted caller checks rather than +reauditing these findings. Identify the configuration helper boundaries, +generation attempt-result fields, and accounting seam consistent with topics +2–8. Locate the real coordinator assembly to use in scheduling tests and the +behavioral coverage that must survive wrapper retirement. + +Select one independent bundled-catalog test oracle and the smaller distinct +risks owned elsewhere. Identify privacy-formatting cases, public schema-file +coverage from topic 3, and replacement assertions for opaque hashes. Map obsolete +fields/helpers to actual callers and tests, including serialized definition-hash +effects. Record the owning documentation for each correction/migration. + +Recommend a concrete removal/extraction inventory, preservation tests, and +ordering dependencies. Do not infer that self-tests justify production helpers, +or that lack of example coverage makes supported APIs obsolete. This is not a +new deletion sweep, exact helper-design exercise, or complexity-metric target. + +## 12. Consolidate Recommendations For Implementation Planning + +Review the assessment records in order and reconcile cross-topic choices. +Produce a compact handoff covering all 34 catalog entries: selected remedy or +explicit proposed deferral, supporting assessment topic, consequential design +choice, dependencies, and implementation-time validation. Findings whose remedy +was already settled need only a brief mapping, not another investigation. + +Ensure source conversion disappears rather than migrating into shared copying; +schema simplification and compilation agree; errors/stages precede accounting +refactoring; the authentication fix can precede relocation; and actual +coordinator tests precede wrapper removal. Separate optional cleanup from fixes +so a deferral does not obstruct unrelated remediation. + +Record any scope/contract question that still needs maintainer direction with a +recommendation and viable alternative. A deferral is a recommendation, not +silent authorization to drop accepted work. Unavailable measurements or tooling +must be identified, together with whether they could change the recommendation; +do not present a conditional choice as a settled implementation instruction. + +Once consequential choices are settled, the subsequent implementation plan can +define focused ordered stages, selected designs, migration/documentation work, +and proportionate validation. Implementation correctness, race regressions, +post-change measurements, and release checks remain work for implementation and +release preparation. No claim of remediation completion follows from this +assessment, and no new recurring release or human-review gate is introduced.