From fcc94eb9e94f6399c15c9e95a6528668f7ed9991 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 5 Nov 2026 04:21:13 +0000 Subject: [PATCH] Record direct ConfigKit value handoff decision --- docs/roadmap/audit/catalog.md | 91 +++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 36 deletions(-) diff --git a/docs/roadmap/audit/catalog.md b/docs/roadmap/audit/catalog.md index 40256ef..7310c0f 100644 --- a/docs/roadmap/audit/catalog.md +++ b/docs/roadmap/audit/catalog.md @@ -45,10 +45,12 @@ Sources: [Resources 1](05-resources.md#1-authentication-diagnostics-read-an-unbo **Confirmed resource defect.** `ProfileSource` and `BackendSource` conversion expand repeated references before ConfigKit performs its bounded snapshot. A small shared acyclic graph can therefore cause exponential work and -allocation. Preserve shared references during conversion, with suitable cycle -and slice-view handling, rather than duplicating ConfigKit's validation or -introducing PromptKit-side raw-source limits. Add focused shared-graph and -deferred-failure regressions for both convenience helpers. +allocation. [Decision 4](#decision-4-exact-numbers-and-the-source-conversion-boundary) +selects removal of the recursive compatibility adapter, passing ConfigKit-supported +values directly to its bounded snapshot. Do not add conversion memoization, +PromptKit-side raw-source limits, or duplicate ConfigKit validation. Cover direct +handoff, source ownership, and deferred unsupported/cyclic-value diagnostics for +both helpers. Implementation remains pending. Sources: [Resources 2](05-resources.md#2-convenience-source-conversion-expands-shared-graphs-before-bounded-loading), [Testing 3](08-testing.md#3-programmatic-provider-value-conversion-lacks-representative-value-cases). @@ -70,11 +72,13 @@ Sources: [Interfaces 1](09-interfaces.md#1-artifactreader-permits-buffer-reuse-b **Confirmed data-integrity defect.** Convenience source conversion falls back from integer parsing to `float64` without checking precision, silently changing -some accepted `json.Number` values. Preserve an exact ConfigKit-compatible -representation, or defer an unsupported-value error to ConfigKit instead of -rounding or converting the number into a string. Regression coverage should -include exact-number boundaries, nested typed collections, mutation isolation, -and deferred unsupported/cyclic-value errors for both source helpers. +some accepted `json.Number` values. +[Decision 4](#decision-4-exact-numbers-and-the-source-conversion-boundary) selects +removal of this conversion, not a new exact-number subsystem. Convenience-source +provider values must use ConfigKit-supported types; callers choose any necessary +conversion. Let ConfigKit report unsupported values during loading. Cover supported +value handoff and rejection of formerly converted unsupported types without adding +numeric precision guarantees. Runtime overrides remain a separate input path. Sources: [Correctness 1](01-correctness.md#1-provider-source-helpers-silently-change-exact-json-numbers), [Testing 3](08-testing.md#3-programmatic-provider-value-conversion-lacks-representative-value-cases). @@ -323,7 +327,8 @@ copying while retaining DTO projection at the facade and distinct source encoding/runtime validation policies. Preserve concrete types, nils, exact numbers, schema keys, and ownership. Infallible projection must not acquire new errors, panics, or silent zero-value fallbacks. Entries 3 and 5 remain -separate source-conversion defects, not reasons to reject pre-handoff sources. +separate source-conversion defects resolved by removing the adapter under +Decision 4; do not fold its compatibility conversions into the shared copier. Retain separate small traversals where ownership or validation policies differ enough that sharing would require a configurable reflection framework. Reducing @@ -548,6 +553,46 @@ in the diagnostic report and update its owning documentation. Keep this fix independent of adapter relocation so architectural cleanup does not delay the resource remedy. This record does not itself implement the change. +### Decision 4: Exact Numbers And The Source-Conversion Boundary + +**Related findings:** [3](#3-avoid-exponential-expansion-during-convenience-source-conversion), +[5](#5-preserve-exact-numbers-in-programmatic-provider-sources), and +[24](#24-centralize-compatible-json-copying-without-conflating-policies). + +**Status:** Accepted; implementation pending. + +**Decision:** Remove the recursive provider-value compatibility adapter from +`ProfileSource` and `BackendSource`. Supply their provider values directly to +ConfigKit `Mapping`, using its supported input types: nil, built-in strings, +booleans, signed and unsigned integers, finite floats, `map[string]any`, and +`[]any`, recursively. Retain the helpers' ordinary profile/backend field mapping. +ConfigKit owns snapshotting and deferred diagnostics for unsupported values and +cycles. Do not introduce an upstream extension or a PromptKit numeric conversion, +precision-checking, or raw-source validation subsystem for this remediation. + +**Consumer impact:** Values formerly accommodated by the adapter, including +`json.Number`, named scalar types, typed maps/slices, arrays, and pointers nested +inside provider values, must be supplied in supported forms. Callers choose any +conversion and handle its errors or acceptable approximation; PromptKit does +not silently make that choice. Ordinary typed profile fields already use +supported forms. This decision does not narrow runtime request overrides. + +**Rationale:** The root cause is a mismatch between PromptKit's broader provider +value representation and ConfigKit's mapping inputs. PromptKit's compatibility +adapter introduces both lossy numeric interpretation and pre-handoff graph +expansion. Removing it simplifies the boundary and addresses both defects +without imposing new numeric guarantees on an LLM library. + +**Alternatives considered:** Repairing and memoizing the adapter would preserve +more input forms but retain unnecessary conversion machinery. Extending ConfigKit +could move that responsibility upstream but is not needed for the selected scope. + +**Remediation follow-through:** Update convenience-source GoDoc, migration/release +notes, and focused tests for direct supported-value handoff, source capture, and +ConfigKit's deferred rejection of unsupported inputs. Remove obsolete adapter +code and tests. Preserve distinct runtime JSON-copying behavior. This is a +deliberate compatibility change; this record does not itself implement it. + ## Open Decisions Work through the remaining decisions below in order, retaining their original @@ -557,32 +602,6 @@ unrelated fixes. In particular, updating the maintainer toolchain need not wait for the consumer-minimum decision. Implementation details and optional cleanup do not become release gates merely by appearing in this catalog. -### Decision 4: Exact Numbers And The Source-Conversion Boundary - -**Related findings:** [3](#3-avoid-exponential-expansion-during-convenience-source-conversion), -[5](#5-preserve-exact-numbers-in-programmatic-provider-sources), and -[24](#24-centralize-compatible-json-copying-without-conflating-policies). - -**Question:** Which exact numeric values can the convenience helpers preserve -through the current ConfigKit mapping boundary, and what happens to others? - -**Recommendation:** Preserve supported values through the complete conversion, -load, and outbound-encoding path; defer an unsupported-value error when exact -preservation is unavailable. Compare numeric meaning rather than spelling or -successful parsing alone. Address shared-graph expansion in the same adapter -with completed-conversion memoization, distinct cycle tracking, and correct -slice-view identity, preserving source capture and deferred failures. - -**Alternative:** Request upstream support for additional exact numeric/value -forms, then simplify or remove the relevant PromptKit conversion. This may -provide a cleaner long-term boundary and broader preservation, but introduces -an upstream dependency and should not postpone fixing silent rounding or -exponential expansion. Runtime JSON copying remains a separate policy. - -**Resolve before implementation:** Establish the supported numeric round-trip -cases and whether broader upstream support is needed now. Do not substitute -numeric-looking strings or introduce a second raw-source validation system. - ### Decision 5: Consumer Go Minimum After The Toolchain Update **Related finding:** [1](#1-update-the-audited-maintainer-toolchain-for-applicable-security-fixes).