base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Record audit remediation decisions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 14:11:19 +00:00
parent f00fe1909d
commit 1798dcde2e
1 changed files with 47 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/roadmap/audit/catalog.md
View File

@@ -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: numbered entries in seven audit documents. Reviewed audit state:
`db732e3a1de55c844f77870e1c6db683c2685d5d`. `db732e3a1de55c844f77870e1c6db683c2685d5d`.
This catalog owns grouping and recommended review order. The linked original This catalog owns grouping, recommended review order, and subsequent remediation
entries retain code locations, evidence, contract analysis, and detailed decisions. The linked original entries retain code locations, evidence,
remediation options. Consolidation does not resolve a finding or select a contract analysis, and detailed
proposed contract change. Original priorities are retained. Within those remediation options. Consolidation alone does not resolve a finding or select a
priorities, incorrect outcomes and request isolation lead; blocked validation, 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 resource retention, and consumer contracts precede scaling and maintainability
work; editorial and historical navigation issues follow. 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 progress, then be discarded when finalization clears the queue. The returned
delivery evidence can still indicate success. delivery evidence can still indicate success.
Make the transition out of deferred acceptance atomic, or drain every accepted **Decision:** atomically close deferred-message acceptance when finalization
message before closing. Preserve the finalizer's own delivery path. The two begins, deliver the already accepted batch under the existing presentation rules,
source entries describe the same logical ordering defect, rather than a data and return `ErrReporterClosed` for later deferred submissions. Preserve the
race. 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); **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). [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 burdens custom providers and suggests a presentation responsibility that
standard commands no longer use. standard commands no longer use.
Consider narrowing the interface to acquisition and updating writer-only stubs **Decision:** remove `WriteExplanation` from `ExplanationReader`, leaving the
and assertions. This needs a deliberate public compatibility decision: callers acquisition responsibility, and update GoDoc, writer-only stubs, and assertions.
invoking the method through `View.Explanation` would stop compiling. Both audits Native provider objects may retain their own rendering methods. Do not add
identify the same obsolete requirement. 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); **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). [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 O(A log A) total work for these steps. Preserve scoped precedence, canonical
endpoints, missing-target behavior, and cycle diagnostics. 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). **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 ## 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. The source declarations contain only Θ(RD) tokens.
Traverse distinct source prefixes once and classify each once. For the audited 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 shape, this phase can become O(RD + D²).
the repeated preparation and help-time scan are distinct issues.
**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). **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 Query an immutable source-prefix index for strict descendants. The identified
discovery work becomes O(A) for that example; general cases still pay for 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). **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 preserve snapshot ownership, ordering, error identity, and diagnostic timing
rather than introducing a universal framework. 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). **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). Also discussed in the [responsibility assessment](A1-responsibility.md#machinery-worth-retaining-under-the-selected-contracts).