diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index e6347de..bb16a7f 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -88,9 +88,10 @@ projections. Further presentation refinements should follow practical feedback. Transient acquisition overrides are included as an opt-in loader capability in [roadmap OD-11](promptkit-v0.19.0.md#od-11-transient-configuration-overrides). -Comparison overrides follow OD-9's independent-side model. Loader composition, -numeric conversion, and unusual path syntax remain design tasks. Persistent -configuration editing remains deferred. +Comparison overrides follow OD-9's independent-side model and use the same +ordinary Go numeric policy as CLI provider parameters. Loader composition and +unusual path syntax remain design tasks. Persistent configuration editing remains +deferred. Discovery, import defaults, collection identities, and field-level resolution recording remain available through application loaders. Discovery tracing, diff --git a/docs/roadmap/promptkit-v0.19.0.md b/docs/roadmap/promptkit-v0.19.0.md index 84db1ce..b6a9782 100644 --- a/docs/roadmap/promptkit-v0.19.0.md +++ b/docs/roadmap/promptkit-v0.19.0.md @@ -148,8 +148,8 @@ or diagnostics subcommand is planned. Transient configuration overrides are included under OD-11 as an opt-in loader capability. `config validate --set /workers=0` and `config show --set /server/port=8080` apply temporary overrides during acquisition -without editing source files. Numeric conversion, unusual pointer keys, loader -composition, and supplemental input grammar remain to be finalized. Comparison +without editing source files. Unusual pointer keys, loader composition, and +supplemental input grammar remain to be finalized. Comparison overrides follow OD-9's independent-side model: `--set` affects only the left side and `--against-set` only the right. @@ -573,8 +573,8 @@ selection, JSON conventions for core serialization, original Go values for text templates, no-template text rendering, universal formats, automatic selection, safe YAML input conversion, aggregate configuration presentation, or joint format delivery. -Report serialization is separate from the agreed CLI JSON number policy in OD-2 -and the remaining ConfigKit input-conversion decision in OD-11. +Report serialization is separate from the agreed CLI JSON number policy in OD-2, +also adopted for configuration overrides in OD-11. ## Initial report implementation approach @@ -751,7 +751,8 @@ Default tests remain offline and independent of real credentials. create/execute retained prepared handles. - [ ] New flags preserve selected omission/empty/zero semantics, parse malformed inputs through the existing usage path, and do not leak state between runs. - Numeric decoding of provider JSON matches the selected strategy in OD-2. + Numeric decoding of provider JSON and configuration overrides follows the same + policy in OD-2 and OD-11, including nested values and input-error behavior. - [ ] The small, centralized internal CLI JSON conversion helper documents the numeric policy and its rationale in code comments. Cover integer boundaries, decimal/exponent forms, nested objects/arrays, and range errors. Accept ordinary @@ -908,11 +909,11 @@ The core ownership, JSON representation conventions, text printing/templates, universal-format, automatic-selection, and joint format-delivery decisions are now agreed above. Remaining details are listed under [remaining core reporting implementation details](#remaining-core-reporting-implementation-details). -Provider JSON number decoding, namespace applicability, and independent comparison -defaults are agreed in OD-2, OD-3, and OD-9. Outstanding operator choices are +CLI JSON number decoding for both integrations, namespace applicability, and +independent comparison defaults are agreed. Outstanding operator choices are whether to standardize explicit empty collections when application defaults are -nonempty (OD-9), and configuration-override numeric conversion, unusual-path -grammar, and loader composition (OD-11). Inheritance-clearing flags are no longer +nonempty (OD-9), and unusual-path grammar and loader composition (OD-11). +Inheritance-clearing flags are no longer needed. Exact helper signatures, typed binding composition, flag collision handling, and report layouts remain implementation choices, not unresolved scope. @@ -946,7 +947,8 @@ on smoke tests, and add a singleton `--llm-extra-params JSON` object option to all three. Use native whole-map replacement, including native behavior for empty maps. The single-object form is selected over repeated key assignments. -**Agreed CLI JSON number policy:** pass ordinary Go numeric values to PromptKit. +**Agreed CLI JSON number policy:** pass ordinary Go numeric values to PromptKit +and to ConfigKit for the configuration overrides selected in OD-11. Classify numbers by their written JSON syntax, not by whether their mathematical value could be an integer: @@ -960,7 +962,7 @@ value could be an integer: - Apply the same rules recursively inside JSON objects and arrays, preserving other JSON value types. Decode with the standard library's `UseNumber` to avoid premature floating-point conversion, then convert the temporary `json.Number` - values before handing the object to PromptKit. + values before handing parsed values to either upstream library. Keep this in one small, centralized internal helper dedicated to CLI JSON input. Use standard Go numeric parsing; no arbitrary-precision fallback, general-purpose @@ -975,10 +977,12 @@ range-error behavior, and the rationale for this narrow boundary beside the helper. The comments must make clear that ordinary Go numeric limits are an intentional policy, not a missing feature to work around later. -This policy governs parsed CLI provider parameters, not application-supplied -runtime override values or core report serialization. ConfigKit input adaptation -remains a separate decision under OD-11; do not broaden the helper into a generic -conversion facility to anticipate that work. +This policy governs parsed CLI provider parameters and configuration override +values, not application-supplied runtime values or core report serialization. +Centralize the bounded CLI JSON conversion utility; its placement across the +independent modules is an implementation task that must respect module ownership. +Reusing number conversion does not unify the libraries' different override +semantics or introduce a general-purpose conversion facility. Retain the authoritative-builder rule: standard flags seed a request, and an application builder can return its complete replacement. Do not reapply CLI @@ -1422,6 +1426,15 @@ required. The loader contract must state how it combines these records with any existing application-owned overrides; the generic adapter cannot inject them into an arbitrary loader after the load has completed. +**Agreed numeric conversion:** adopt the ordinary Go numeric policy in OD-2 for +both `--set` and `--against-set`, including nested objects and arrays. Integer +syntax uses `int64`, with `uint64` for larger representable nonnegative values; +decimal or exponent syntax uses `float64`. Accept ordinary floating-point +approximation and report numeric range errors as input errors. Temporary +`json.Number` values are converted before forwarding to ConfigKit. Use the same +small, centralized internal CLI JSON utility and required policy comments; +no arbitrary-precision fallback or public numeric conversion API is selected. + **Agreed comparison behavior:** `--set` supplies override records only to the left side; `--against-set` supplies records only to the right. Each side starts from its ordinary configuration under OD-9. Omission supplies no CLI override @@ -1442,10 +1455,8 @@ the required acquisition changes prove disproportionate rather than silently dropping the agreed feature. Settle these details before implementation: - Split at the first `=`; JSON supplies typed null, boolean, string, numeric, - array, and object values. Specify numeric conversion to ConfigKit-supported - built-in forms rather than passing `json.Number` or silently promising - arbitrary numeric precision. An unambiguous alternate input form may be - needed for pointer keys containing `=`. + array, and object values, with the agreed numeric policy above. An unambiguous + alternate input form may be needed for pointer keys containing `=`. - Forward explicit records only, with safe display labels such as `--set`, never raw value-bearing arguments as provenance labels. Preserve native duplicate/overlap handling rather than silently collapsing assignments.