base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Record direct ConfigKit value handoff decision

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-05 04:21:13 +00:00
parent 95730a3c11
commit fcc94eb9e9
1 changed files with 55 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/roadmap/audit/catalog.md
View File

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