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