Record configuration classification decisions
This commit is contained in:
@@ -1,8 +1,10 @@
|
||||
# Invalid configuration outcomes
|
||||
|
||||
Status — proposed implementation roadmap. The user has accepted the targeted
|
||||
integration behavior. The decisions at the end identify remaining policy and
|
||||
API choices for the implementation plan.
|
||||
Status — accepted roadmap, pending implementation planning. The user has
|
||||
accepted the targeted integration behavior, the built-in diagnostic mapping
|
||||
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
|
||||
|
||||
@@ -69,8 +71,8 @@ change to that published status behavior.
|
||||
| Successful acquisition with warnings | Follow the command's successful-result behavior |
|
||||
|
||||
Classification uses upstream structured evidence. Diagnostic text, filenames,
|
||||
and source labels serve presentation and provenance. The exact input-error code
|
||||
mapping is proposed under Open Decisions.
|
||||
and source labels serve presentation and provenance. The input-error code
|
||||
mapping follows the accepted decisions below.
|
||||
|
||||
The selected outcome retains the original returned cause, including ordinary
|
||||
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
|
||||
checkpoint observes cancellation alongside an acquisition failure, preserve
|
||||
both causes using the established error-joining approach.
|
||||
- Keep classification within integration ownership, using the sharing approach
|
||||
selected below. Existing core outcome constructors and reporting provide the
|
||||
required mechanics.
|
||||
- Implement the built-in mapping and error-chain classification in one exported
|
||||
ckconfig function, shared by both integrations. Existing core outcome
|
||||
constructors and reporting provide the required mechanics. Invocation-specific
|
||||
cancellation checks belong in the handlers.
|
||||
|
||||
### 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
|
||||
release work.
|
||||
|
||||
## Open Decisions
|
||||
## Accepted decisions
|
||||
|
||||
### 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
|
||||
`version.error`, `resolve.error`, and `validate.error` findings, and other codes
|
||||
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
|
||||
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
|
||||
|
||||
**Recommendation.** Place one narrowly documented classification function in
|
||||
ckconfig and have ckprompt call it through its existing dependency. Keep command
|
||||
explanation construction and reporting in their owning handlers. Select its
|
||||
exact signature during implementation planning based on the needed cause and
|
||||
cancellation inputs. A shared implementation reduces drift across the two
|
||||
standard families and fits ckconfig's ownership of ConfigKit adaptation. The
|
||||
public function adds an API maintenance obligation.
|
||||
Place one narrowly documented, exported classification function in ckconfig.
|
||||
Both integrations use it, with ckprompt accessing it through its existing
|
||||
dependency. The function inspects the returned error and its ConfigKit
|
||||
diagnostics and returns the appropriate outcome classification. Its
|
||||
responsibilities include the
|
||||
diagnostic mapping, operational fallback, and joined-error precedence.
|
||||
|
||||
**Alternative.** Maintain small private classifiers in both integration modules,
|
||||
with matching behavioral cases. This keeps the helper private and supports
|
||||
package-local evolution, but duplicates the diagnostic mapping and joined-error
|
||||
rules. Future upstream code changes would require coordinated edits in both
|
||||
modules. Prefer this approach if the shared signature would expose more policy
|
||||
or machinery than the demonstrated integration need warrants.
|
||||
Keep command explanation construction, cause attachment, reporting, and
|
||||
invocation-specific cancellation checks in their owning handlers. Select the
|
||||
function's exact name and signature during implementation planning.
|
||||
|
||||
A shared implementation reduces drift across the two standard families and
|
||||
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