Record configuration classification decisions

This commit is contained in:
2026-11-16 17:46:31 +00:00
parent ed6060f344
commit a53bf9f916

View File

@@ -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.