Record configuration migration review findings

This commit is contained in:
2026-11-21 16:48:34 +00:00
parent 40f8a68253
commit 4a9def2138

View File

@@ -0,0 +1,83 @@
# Configuration Handoff And Repair Review
Reviewed implementation stages 1–17 against
[the implementation plan](implementation.md),
[the feature roadmap](next-release-considerations.md), and accepted ADRs
[0001](../adr/0001-configuration-boundary.md) and
[0002](../adr/0002-shared-configuration-data-model.md).
Implementation baseline: `40f8a6825359b4923645256e230a050dfdb00710`;
reviewed changes begin after `248d0db`.
## Findings
### 1. Narrow The Pre-Handoff Mutation Wording To The Accepted Expectation
Status: open. Priority: P3. Implementation stage: 16.
Locations: `engine.go:280` and `docs/consumers/pkg-promptkit.md:132`.
`NewFromConfig` says callers **must not mutate** selected settings between loading
and handoff; the consumer guide repeats that blanket instruction. The accepted
roadmap instead asks callers to hand off before changes that invalidate the
frozen inspection/provenance evidence, and expressly treats this as a usage
expectation rather than a new enforcement mechanism. The published wording
prohibits even value-preserving reassignment or copying, which needs no such
restriction.
Required change: describe the narrower consistency expectation in both owners.
Explain that construction consumes the resolved settings while inspection retains
the completed load's frozen evidence, so callers should keep those consistent at
handoff. Preserve the existing protection against mutation after construction.
No mutation detection, extra validation pass, or new error is needed.
Verification: review both passages against the feature roadmap's ownership
paragraph; ensure they no longer impose an unconditional mutation prohibition.
This is a documentation correction and does not require a new runtime test.
### 2. Keep Application-Field Sensitivity Policy With The Application
Status: open. Priority: P3. Implementation stage: 16.
Location: `docs/formats.md:235–236`.
The backend format reference says an unrecognized backend field is application
data and **must not contain secrets**. The accepted extension-point contract
assigns interpretation, validation, and sensitivity rules for those fields to
the application. The implementation follows that contract: inline fields remain
in native inspection, application sensitivity predicates compose with PromptKit's,
and those fields are omitted from resource reports and provider parameters.
The added prohibition unnecessarily narrows the application-owned data contract.
Required change: retain the useful warning that a raw `api_key` extension is not
a PromptKit credential input and is not automatically redacted by PromptKit.
State that the application owns sensitivity declarations and disclosure policy
for its extension fields, rather than prohibiting their contents. Review the
adjacent profile wording for the same distinction between PromptKit credentials
and application-owned data. Do not add automatic credential behavior or a new
validator for application fields.
Verification: compare the revised text with the feature roadmap's
application-specific-fields contract and existing focused-inspection sensitivity
coverage. No change to execution or redaction implementation is needed.
## Review Results And Validation
- Stage 1: ConfigKit v1.4.0, unchanged Go minimum, and commit-pinned attribution
match the selected module and its notices.
- Stages 2–3: configuration and runtime inputs resolve mode-dependent repair
budgets; explicit zero and null/omission, whole-contract replacement, prepared
retention, and existing repair accounting are covered.
- Stages 4–9: shared settings aliases, composed stateless rules, final-metadata
resource capture, native focused inspection, explicit source mounting, and
shared constructor/assembly paths match the target architecture.
- Stages 10–15: migrated tests and maintained offline examples exercise the
changed boundaries, including concurrent loads, cross-filesystem inheritance,
application extensions, ownership, and standalone/handoff equivalence.
- Stages 16–17: canonical documentation is updated, subject to the two wording
corrections above. No additional functional or architectural defect was found.
Fresh checks passed with Go 1.27.4, `GOTOOLCHAIN=local`, and `GOWORK=off`:
`go test -race ./...` and `go vet ./...`. Changed Go files have no `gofmt`
differences, and the implementation diff passes `git diff --check`.
This review changes only this findings document; it does not implement fixes.