diff --git a/docs/roadmap/invalid-configuration-outcomes.md b/docs/roadmap/invalid-configuration-outcomes.md index 503f01c..9d5c01e 100644 --- a/docs/roadmap/invalid-configuration-outcomes.md +++ b/docs/roadmap/invalid-configuration-outcomes.md @@ -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.