Record configuration classification decisions
This commit is contained in:
@@ -1,8 +1,10 @@
|
|||||||
# Invalid configuration outcomes
|
# Invalid configuration outcomes
|
||||||
|
|
||||||
Status — proposed implementation roadmap. The user has accepted the targeted
|
Status — accepted roadmap, pending implementation planning. The user has
|
||||||
integration behavior. The decisions at the end identify remaining policy and
|
accepted the targeted integration behavior, the built-in diagnostic mapping
|
||||||
API choices for the implementation plan.
|
with operational fallback, and a shared exported classification function in
|
||||||
|
ckconfig. The implementation plan will enumerate the mapped codes and select
|
||||||
|
the function's exact name and signature.
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
@@ -69,8 +71,8 @@ change to that published status behavior.
|
|||||||
| Successful acquisition with warnings | Follow the command's successful-result behavior |
|
| Successful acquisition with warnings | Follow the command's successful-result behavior |
|
||||||
|
|
||||||
Classification uses upstream structured evidence. Diagnostic text, filenames,
|
Classification uses upstream structured evidence. Diagnostic text, filenames,
|
||||||
and source labels serve presentation and provenance. The exact input-error code
|
and source labels serve presentation and provenance. The input-error code
|
||||||
mapping is proposed under Open Decisions.
|
mapping follows the accepted decisions below.
|
||||||
|
|
||||||
The selected outcome retains the original returned cause, including ordinary
|
The selected outcome retains the original returned cause, including ordinary
|
||||||
wrapping and joined errors, so supported `errors.Is` and `errors.As` queries
|
wrapping and joined errors, so supported `errors.Is` and `errors.As` queries
|
||||||
@@ -104,9 +106,10 @@ boundary.
|
|||||||
- Account for cancellation and deadlines before choosing usage. When an existing
|
- Account for cancellation and deadlines before choosing usage. When an existing
|
||||||
checkpoint observes cancellation alongside an acquisition failure, preserve
|
checkpoint observes cancellation alongside an acquisition failure, preserve
|
||||||
both causes using the established error-joining approach.
|
both causes using the established error-joining approach.
|
||||||
- Keep classification within integration ownership, using the sharing approach
|
- Implement the built-in mapping and error-chain classification in one exported
|
||||||
selected below. Existing core outcome constructors and reporting provide the
|
ckconfig function, shared by both integrations. Existing core outcome
|
||||||
required mechanics.
|
constructors and reporting provide the required mechanics. Invocation-specific
|
||||||
|
cancellation checks belong in the handlers.
|
||||||
|
|
||||||
### 2. Apply it throughout ckconfig
|
### 2. Apply it throughout ckconfig
|
||||||
|
|
||||||
@@ -191,11 +194,11 @@ implemented behavior. Review the final diff for the agreed scope and retire this
|
|||||||
roadmap under the normal documentation lifecycle after recording any unfinished
|
roadmap under the normal documentation lifecycle after recording any unfinished
|
||||||
release work.
|
release work.
|
||||||
|
|
||||||
## Open Decisions
|
## Accepted decisions
|
||||||
|
|
||||||
### Exact diagnostic-code mapping
|
### Exact diagnostic-code mapping
|
||||||
|
|
||||||
**Recommendation.** Use an explicit mapping based on ConfigKit v1.2.0's public
|
Use a built-in, explicit mapping based on ConfigKit v1.2.0's public
|
||||||
code semantics. Include YAML-content and decoding errors, explicit
|
code semantics. Include YAML-content and decoding errors, explicit
|
||||||
`version.error`, `resolve.error`, and `validate.error` findings, and other codes
|
`version.error`, `resolve.error`, and `validate.error` findings, and other codes
|
||||||
whose documented meaning clearly identifies invalid configuration content.
|
whose documented meaning clearly identifies invalid configuration content.
|
||||||
@@ -211,27 +214,20 @@ alone may be insufficient to establish whether application-supplied data came
|
|||||||
from an operator, so the rule follows the meaning recorded in upstream
|
from an operator, so the rule follows the meaning recorded in upstream
|
||||||
diagnostics.
|
diagnostics.
|
||||||
|
|
||||||
**Alternative.** Add an application-supplied classification hook for cases that
|
|
||||||
depend on source ownership or application policy, alongside the built-in mapping.
|
|
||||||
Applications can then identify input failures using knowledge their loaders
|
|
||||||
possess. This supports genuinely contextual cases, but expands the public
|
|
||||||
integration contracts and creates additional configuration and precedence rules.
|
|
||||||
The current reproduction is addressable through existing typed diagnostics, so
|
|
||||||
the additional hook has limited demonstrated value in this scope.
|
|
||||||
|
|
||||||
### Shared classification interface
|
### Shared classification interface
|
||||||
|
|
||||||
**Recommendation.** Place one narrowly documented classification function in
|
Place one narrowly documented, exported classification function in ckconfig.
|
||||||
ckconfig and have ckprompt call it through its existing dependency. Keep command
|
Both integrations use it, with ckprompt accessing it through its existing
|
||||||
explanation construction and reporting in their owning handlers. Select its
|
dependency. The function inspects the returned error and its ConfigKit
|
||||||
exact signature during implementation planning based on the needed cause and
|
diagnostics and returns the appropriate outcome classification. Its
|
||||||
cancellation inputs. A shared implementation reduces drift across the two
|
responsibilities include the
|
||||||
standard families and fits ckconfig's ownership of ConfigKit adaptation. The
|
diagnostic mapping, operational fallback, and joined-error precedence.
|
||||||
public function adds an API maintenance obligation.
|
|
||||||
|
|
||||||
**Alternative.** Maintain small private classifiers in both integration modules,
|
Keep command explanation construction, cause attachment, reporting, and
|
||||||
with matching behavioral cases. This keeps the helper private and supports
|
invocation-specific cancellation checks in their owning handlers. Select the
|
||||||
package-local evolution, but duplicates the diagnostic mapping and joined-error
|
function's exact name and signature during implementation planning.
|
||||||
rules. Future upstream code changes would require coordinated edits in both
|
|
||||||
modules. Prefer this approach if the shared signature would expose more policy
|
A shared implementation reduces drift across the two standard families and
|
||||||
or machinery than the demonstrated integration need warrants.
|
fits ckconfig's ownership of ConfigKit adaptation. The narrowly scoped public
|
||||||
|
function adds an API maintenance obligation while allowing the mapping and
|
||||||
|
error-chain rules to be maintained in one place.
|
||||||
|
|||||||
Reference in New Issue
Block a user