Plan the audit remediation assessment

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.