From 1798dcde2efcaed6055dc24e2404c463986efc32 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 7 Nov 2026 14:11:19 +0000 Subject: [PATCH] Record audit remediation decisions --- docs/roadmap/audit/catalog.md | 63 ++++++++++++++++++++++++++--------- 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index dbd47ed..a9e9a9c 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -4,11 +4,14 @@ Status: **27 distinct open findings: five P2 and 22 P3**, consolidated from 30 numbered entries in seven audit documents. Reviewed audit state: `db732e3a1de55c844f77870e1c6db683c2685d5d`. -This catalog owns grouping and recommended review order. The linked original -entries retain code locations, evidence, contract analysis, and detailed -remediation options. Consolidation does not resolve a finding or select a -proposed contract change. Original priorities are retained. Within those -priorities, incorrect outcomes and request isolation lead; blocked validation, +This catalog owns grouping, recommended review order, and subsequent remediation +decisions. The linked original entries retain code locations, evidence, +contract analysis, and detailed +remediation options. Consolidation alone does not resolve a finding or select a +proposed contract change. Explicit decisions recorded below supersede the +original entries' alternatives; all findings remain open until remediated. +Original priorities are retained. Within those priorities, incorrect outcomes +and request isolation lead; blocked validation, resource retention, and consumer contracts precede scaling and maintainability work; editorial and historical navigation issues follow. @@ -61,10 +64,16 @@ acceptance. A concurrent submission can return success while presentation is in progress, then be discarded when finalization clears the queue. The returned delivery evidence can still indicate success. -Make the transition out of deferred acceptance atomic, or drain every accepted -message before closing. Preserve the finalizer's own delivery path. The two -source entries describe the same logical ordering defect, rather than a data -race. +**Decision:** atomically close deferred-message acceptance when finalization +begins, deliver the already accepted batch under the existing presentation rules, +and return `ErrReporterClosed` for later deferred submissions. Preserve the +finalizer's own delivery path and document the acceptance cutoff. Repeatedly +draining newly arriving submissions is not selected; completion must not depend +on application producers eventually stopping. This does not add responsibility +for application goroutines or change ordinary message visibility. + +The two source entries describe the same logical ordering defect, rather than a +data race. **Originals:** [01-correctness C2](01-correctness.md#c2--p2-finalization-can-discard-a-successfully-queued-deferred-message); [04-concurrency N2](04-concurrency.md#n2--p2-deferred-message-acceptance-remains-open-after-the-final-batch-detaches). @@ -169,10 +178,15 @@ show/explain handlers acquire evidence with `Explain` and core renders it. This burdens custom providers and suggests a presentation responsibility that standard commands no longer use. -Consider narrowing the interface to acquisition and updating writer-only stubs -and assertions. This needs a deliberate public compatibility decision: callers -invoking the method through `View.Explanation` would stop compiling. Both audits -identify the same obsolete requirement. +**Decision:** remove `WriteExplanation` from `ExplanationReader`, leaving the +acquisition responsibility, and update GoDoc, writer-only stubs, and assertions. +Native provider objects may retain their own rendering methods. Do not add +compatibility scaffolding or restore provider-owned rendering to justify the +unused requirement. Both audits identify the same obsolete requirement. + +The interface change removes the ability to invoke that method through +`View.Explanation`. CommandKit is still pre-release with no consumers, so no +consumer compatibility or migration work is needed. **Originals:** [03-complexity M6](03-complexity.md#m6--p3-explanation-providers-must-implement-an-unused-rendering-capability); [A1-responsibility R1](A1-responsibility.md#r1--p3-explanation-providers-still-owe-an-unused-text-writer). @@ -201,6 +215,11 @@ become expected O(A) per context, with existing deterministic sorting retaining O(A log A) total work for these steps. Preserve scoped precedence, canonical endpoints, missing-target behavior, and cycle diagnostics. +**Decision for F13–F15:** the repeated-work and scaling analysis sufficiently +justifies remediation. Performance testing is not a prerequisite for selecting +or implementing these changes. Validate correctness and preservation of the +selected routing and discovery semantics. + **Original:** [02-efficiency E1](02-efficiency.md#e1--p3-flag-alias-compilation-repeatedly-resolves-shared-chain-suffixes). ## F14 — P3: Discovery-context preparation repeatedly rebuilds shared prefixes @@ -210,8 +229,12 @@ construction before result deduplication, with repeated classification as well. The source declarations contain only Θ(RD) tokens. Traverse distinct source prefixes once and classify each once. For the audited -shape, this phase can become O(RD + D²). An index can be shared with F15, but -the repeated preparation and help-time scan are distinct issues. +shape, this phase can become O(RD + D²). + +**Decision:** design F14 and F15 together around shared source-prefix processing, +preferably reusing the existing alias source structure rather than adding parallel +indexes. The repeated preparation and help-time scan remain distinct findings. +The performance-testing decision under F13 applies to both. **Original:** [02-efficiency E3](02-efficiency.md#e3--p3-discovery-context-preparation-rebuilds-shared-prefixes-repeatedly). @@ -224,7 +247,8 @@ on every such help request. Query an immutable source-prefix index for strict descendants. The identified discovery work becomes O(A) for that example; general cases still pay for -matching candidates, resolution, and output sorting. +matching candidates, resolution, and output sorting. Design this together with +F14 under the decisions recorded there and in F13. **Original:** [02-efficiency E2](02-efficiency.md#e2--p3-alias-help-scans-every-source-for-every-intermediate-route). @@ -305,6 +329,13 @@ diagnostic/explanation values. Any exported helper needs an API decision; preserve snapshot ownership, ordering, error identity, and diagnostic timing rather than introducing a universal framework. +**Decision context:** CommandKit is still pre-release with no consumers. +Compatibility and consumer migration are therefore not constraints on this +remediation. The remaining design question is whether a concrete, narrow CLI +adaptation API simplifies both integrations enough to justify maintaining it. +The helper's signature and scope remain to be selected; this clarification does +not itself approve a new public API or a separate reporting-scheduler helper. + **Original:** [03-complexity M5](03-complexity.md#m5--p3-configuration-diagnostic-adaptation-is-maintained-in-both-integrations). Also discussed in the [responsibility assessment](A1-responsibility.md#machinery-worth-retaining-under-the-selected-contracts).