Prepare v0.18.0 release documentation
This commit is contained in:
@@ -43,6 +43,10 @@ boundary and constraints that framework work must preserve.
|
||||
|
||||
## Release Guidance
|
||||
|
||||
The [v0.18.0 release notes](docs/releases/v0.18.0.md) cover recorded field
|
||||
normalization, derived defaults in configuration inspection, and ConfigKit v1.1.
|
||||
Execution behavior and the Go 1.27 minimum remain unchanged.
|
||||
|
||||
The [v0.17.0 release notes](docs/releases/v0.17.0.md) cover the vanity module
|
||||
path, ConfigKit v1, identified resource lists, removal of prompt-version
|
||||
metadata, and the Go 1.27 minimum. This is a breaking pre-v1 migration.
|
||||
|
||||
@@ -1,14 +1,35 @@
|
||||
# Promptkit v0.18.0
|
||||
|
||||
Configuration inspection now exposes Promptkit's recorded field normalization
|
||||
and derived queue-capacity defaults. ConfigKit is updated to v1.1.0. Existing
|
||||
source evidence remains available, and unchanged content-file origins continue
|
||||
to select their resource context.
|
||||
and derived queue-capacity defaults through ConfigKit v1.1.0. Execution behavior
|
||||
is unchanged, and the minimum supported Go version remains 1.27.0.
|
||||
|
||||
## Recorded Configuration Normalization
|
||||
|
||||
Inspection shows normalized backend and profile settings, prompt metadata, and
|
||||
configured message roles and cache controls, with field-level resolution
|
||||
history. Existing source evidence remains available, and unchanged content-file
|
||||
origins continue to select their resource context.
|
||||
|
||||
Configuration diffs compare normalized effective values, so spelling-only
|
||||
changes that normalize identically may no longer appear. Lists remain atomic in
|
||||
diffs. Inspection does not include backend-to-profile completion or request
|
||||
overrides; see the [configuration inspection guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration).
|
||||
No configuration format or public API change is required to upgrade.
|
||||
|
||||
## Compatibility And Upgrade
|
||||
|
||||
No application-code or configuration-format migration is required from v0.17.0.
|
||||
Consumers that display or compare configuration inspection results should account
|
||||
for normalized values and derived defaults replacing their earlier authored
|
||||
representations. Request-time overrides and caller-appended messages retain
|
||||
their existing processing.
|
||||
|
||||
```sh
|
||||
go get go.maximumdirect.net/promptkit@v0.18.0
|
||||
```
|
||||
|
||||
See the [framework format reference](../formats.md) for current configuration
|
||||
semantics. Consumers upgrading from versions before v0.17.0 should also follow
|
||||
the [configuration and API migration guide](../consumers/configuration-migration.md).
|
||||
|
||||
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.18.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.18.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.18.0/docs/oss/attribution.md)
|
||||
|
||||
@@ -1,192 +0,0 @@
|
||||
# Field-Level Configuration Normalization
|
||||
|
||||
## Status And Purpose
|
||||
|
||||
Implemented: PromptKit uses ConfigKit v1.1.0 and records the selected field
|
||||
normalizations and queue default in its resolved configuration.
|
||||
|
||||
Move PromptKit's existing configuration-time normalization and derived defaults
|
||||
into ConfigKit's recorded application resolution. Configuration inspection should
|
||||
then show the normalized values used to construct execution settings, with
|
||||
explanations of the changes, while unchanged resource references retain the
|
||||
source context needed to read their files.
|
||||
|
||||
The benefit is a more useful inspection view and removal of the parallel
|
||||
interpreted configuration maintained for execution. This is a focused loading
|
||||
change, not a new configuration format, normalization policy, or execution API.
|
||||
|
||||
## Historical Baseline
|
||||
|
||||
PromptKit already uses identified lists for backends, profiles, and prompts at
|
||||
the root and within named collections. Six ConfigKit identity registrations
|
||||
cover those destinations. This roadmap does not repeat that migration.
|
||||
|
||||
At the baseline, the configuration adapter's `Definition.Resolve` captured input
|
||||
presence information. During validation, `interpretConfiguration` constructs
|
||||
detached backend, profile, and prompt interpretations and applies normalization
|
||||
and a conditional backend queue default. Runtime construction uses those
|
||||
interpretations; configuration inspection retains ConfigKit's composed values.
|
||||
Configured message roles and cache-control values are normalized later during
|
||||
prompt materialization.
|
||||
|
||||
This separation avoided recording whole resource lists as normalized under
|
||||
ConfigKit v1.0.0. Such a record would replace the effective origins of unchanged
|
||||
fields, including `content_file`, whose origin selects the filesystem and
|
||||
directory used to load message text.
|
||||
|
||||
The implemented behavior is documented in the [format reference](../formats.md) and
|
||||
[source-loading implementation](../internal/sources.md). The
|
||||
[configuration ownership decision](../adr/0001-configuration-boundary.md)
|
||||
continues to govern the division of responsibility: ConfigKit owns composition;
|
||||
PromptKit interprets effective values and supplies domain rules.
|
||||
|
||||
## Released Upstream Capability
|
||||
|
||||
[ConfigKit v1.1.0](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.1.0/docs/releases/v1.1.0.md)
|
||||
allows individual field records inside lists through the existing `Normalize`,
|
||||
`RecordNormalization`, and derived-default APIs:
|
||||
|
||||
- Equal-length ordinary lists are compared recursively by position. This covers
|
||||
nested prompt messages and inputs without registering new identities for them.
|
||||
- Registered collections with valid, unique entry and final identities support
|
||||
matched field comparison. PromptKit already registers its resource lists.
|
||||
- List length changes, and registered identity order or membership changes,
|
||||
still need list or ancestor coverage. Matching is conservative when identities
|
||||
are unsuitable. Final identity validation remains ConfigKit's responsibility.
|
||||
- Entry queries retain their fixed resolution-entry meaning; records address
|
||||
final positions. Public effective-configuration diffs remain atomic for lists.
|
||||
|
||||
These capabilities support the proposed in-place field transformations. No
|
||||
additional ConfigKit API is a prerequisite. Historical source evidence retained
|
||||
for a matched record is distinct from its effective origin: a whole-list
|
||||
resolution record can still replace descendant effective origins. The migration
|
||||
should use individual field records for individual changes.
|
||||
|
||||
## Target End State
|
||||
|
||||
### One Normalized Configuration For Loading And Inspection
|
||||
|
||||
PromptKit's `Definition.Resolve` captures the entry metadata needed for existing
|
||||
presence/null semantics, then applies configuration-time transformations to the
|
||||
working configuration and records their effects at the affected fields.
|
||||
`Definition.Validate` examines the resulting values without mutating them.
|
||||
Runtime indexes and prompt materialization consume that same normalized
|
||||
configuration, producing the execution-owned domain values they need.
|
||||
|
||||
Remove `state.interpreted` and the detached interpretation copies once their
|
||||
normalization work has moved. Retain copies needed for runtime ownership and
|
||||
public detached results; removing the duplicate configuration is not a reason
|
||||
to expose shared mutable runtime state.
|
||||
|
||||
PromptKit continues to own normalization rules. ConfigKit records their effects
|
||||
and provenance. Composition, inheritance, precedence, and source acquisition
|
||||
remain upstream responsibilities; this work adds no source-level validation or
|
||||
history-based domain enforcement.
|
||||
|
||||
### Transformation Scope
|
||||
|
||||
Use the existing transformations as the migration inventory, rather than
|
||||
introducing general trimming or case-folding across the configuration:
|
||||
|
||||
| Area | Existing behavior to move into recorded resolution |
|
||||
| --- | --- |
|
||||
| Backends | Normalize base endpoints and diagnostic endpoints; trim API-key environment names; trim and lowercase smoke-test authentication kinds. |
|
||||
| Backend capacity | Apply the existing conditional queue-capacity default. |
|
||||
| Profiles | Normalize configured nonempty endpoint overrides; trim service tier, reasoning effort, and API-key environment names. |
|
||||
| Prompt metadata | Trim descriptions and session-ID templates. |
|
||||
| Prompt inputs | Trim names and supplied content-type and description values. |
|
||||
| Prompt output | Trim a supplied schema path. |
|
||||
| Configured messages | Normalize roles and supplied cache-control type/TTL values using the shared domain rules. |
|
||||
|
||||
Preserve the rules' existing distinctions. For example, roles are lowercased,
|
||||
but cache-control type normalization only trims; the move should not make new
|
||||
spellings acceptable. Preserve optional pointers and existing empty/null
|
||||
interpretation rather than creating fields merely to record an event.
|
||||
|
||||
The backend queue default currently applies when concurrency is enabled and
|
||||
the decoded queue-capacity pointer is nil, including explicit null. ConfigKit's
|
||||
`Default` helper skips explicit input, so substituting it mechanically would
|
||||
change behavior. Retain the existing condition and record the resulting
|
||||
assignment with `RecordDerivedDefault`, including its concurrency dependency.
|
||||
|
||||
Resource IDs, namespaces, and resource references keep their existing exact
|
||||
matching rules. Message content and `content_file` values are not new
|
||||
normalization targets. Schema paths continue to address the selected schema
|
||||
source, rather than acquiring a configuration-file-relative meaning.
|
||||
|
||||
Request overrides, profile completion from backend settings, and caller-appended
|
||||
messages still need their existing runtime processing. Share domain normalizers
|
||||
where appropriate; avoid moving request-dependent work into loading merely to
|
||||
make inspection look fully executable.
|
||||
|
||||
### Provenance And Resource Handling
|
||||
|
||||
Record changed scalar fields at their exact paths with concise, value-free
|
||||
reasons. A role edit, for example, belongs at the role field within the message,
|
||||
not at the message or prompt list. Avoid recording unchanged values needlessly.
|
||||
|
||||
Keep the current origin-based lookup for unchanged `content_file` values,
|
||||
including values inherited or retained from another source. Normalizing a sibling
|
||||
role or cache-control field should not change which file is opened.
|
||||
|
||||
A normalized field acquires a resolution origin; its earlier source evidence is
|
||||
available for inspection. This does not promise that every normalized value
|
||||
retains a file-backed effective origin. If implementation discovers a transformed
|
||||
field that itself requires a source-relative resource lookup, preserve the
|
||||
relevant entry context explicitly before changing that field, using ConfigKit's
|
||||
public context APIs. Do not infer a runtime resource base from arbitrary history.
|
||||
|
||||
The planned normalizer does not need to reorder, add, or remove resource or
|
||||
message entries. That describes this implementation's scope, not a new
|
||||
restriction on operators' ConfigKit composition workflows.
|
||||
|
||||
### Observable Changes
|
||||
|
||||
Configuration inspection will show normalized configuration values and recorded
|
||||
derived defaults. Explanations will expose the associated resolution operations
|
||||
and retained source evidence through ConfigKit's existing inspection behavior.
|
||||
This remains configuration inspection, not a rendering of a request after
|
||||
profile completion, variable substitution, or caller overrides.
|
||||
|
||||
Configuration diffs will compare these normalized effective values. Two inputs
|
||||
that differ only in a normalized spelling may no longer produce a value diff;
|
||||
list changes that remain are still reported atomically. Existing redaction
|
||||
continues to apply to inspection and explanations.
|
||||
|
||||
The intended execution behavior, accepted configuration values, resource
|
||||
selection, and presence/null handling remain the same. Preserve public error
|
||||
classification where applicable while integrating normalization failures with
|
||||
the existing validation path. Do not add a promise of identical diagnostic
|
||||
wording, ordering, or internal callback timing. No YAML syntax or collection
|
||||
specification-version change is planned.
|
||||
|
||||
## Acceptance And Documentation
|
||||
|
||||
Adopt the released ConfigKit v1.1.0 module without a committed local replacement,
|
||||
with applicable attribution updated. The companion
|
||||
[implementation plan](implementation.md) owns sequencing and implementation steps.
|
||||
|
||||
Ordinary invalid resources should retain useful rejection rather than becoming
|
||||
unrecorded-mutation failures because a sibling field needed normalization.
|
||||
ConfigKit's conservative list audit does not justify new identity rules or a
|
||||
separate source audit.
|
||||
|
||||
Focused boundary coverage should demonstrate:
|
||||
|
||||
- Normalized effective values and explanations for representative backend,
|
||||
profile, prompt, and nested message fields at root and collection destinations.
|
||||
- Relative content-file loading after sibling normalization, including inherited
|
||||
values and values retained from a different contributing source.
|
||||
- Existing absence, explicit null, empty, and zero handling, especially the queue
|
||||
default and optional input/message metadata.
|
||||
- Existing invalid-value and identity rejection through useful public errors,
|
||||
without broadening accepted values or adding new restrictions.
|
||||
- Execution-relevant equivalence for normalized definitions, including prompt
|
||||
hashes, and continued normalization of caller-appended messages.
|
||||
- Existing redaction, normalized-value diff behavior, and atomic list diffs.
|
||||
|
||||
Coverage should target PromptKit integration rather than reproduce ConfigKit's
|
||||
correspondence test suite. The format reference, consumer inspection guidance,
|
||||
source-loading documentation, affected GoDoc, and release notes should describe
|
||||
the implemented inspection change and its limits. Architecture wording should
|
||||
reflect the callback flow without turning implementation details into contracts.
|
||||
@@ -38,11 +38,8 @@ consumers.
|
||||
|
||||
## Ideas
|
||||
|
||||
### Field-Level Normalization With Preserved List Provenance
|
||||
|
||||
Selected for planning following ConfigKit v1.1.0. The
|
||||
[field-level normalization roadmap](field-normalization.md) owns the target
|
||||
behavior and scope; its companion implementation plan owns the staged work.
|
||||
No unselected ideas are currently recorded here. Deliberately postponed ideas
|
||||
remain in the [deferred catalog](deferred.md).
|
||||
|
||||
## Entry Format
|
||||
|
||||
|
||||
@@ -1,274 +0,0 @@
|
||||
# Recorded Field Normalization Implementation Plan
|
||||
|
||||
Implement [field-normalization.md](field-normalization.md) in the sequential
|
||||
stages below. Each stage is sized for one Luna coding-agent prompt. The feature
|
||||
roadmap owns intent and target behavior; this plan owns implementation steps.
|
||||
|
||||
## Baseline And Sprint Rules
|
||||
|
||||
The baseline is `fb7ebe6`: ConfigKit v1.0.0, Go 1.27.0, six registered resource
|
||||
list identities, and execution-owned interpretations in `internal/configuration`.
|
||||
`configurationDefinition` captures presence in `Resolve`, then populates
|
||||
`state.interpreted` in `Validate`. `load.go`, `targets.go`, and `prompts.go`
|
||||
consume that second configuration. Message roles/cache controls are normalized
|
||||
in `materializePrompt`.
|
||||
|
||||
Read `docs/development.md` and the applicable agent, architecture, testing,
|
||||
documentation, and OSS policies. Follow ADR
|
||||
[0001](../adr/0001-configuration-boundary.md). Use ConfigKit's released public
|
||||
API and documentation, including its v1.1.0 resolution-recording rules.
|
||||
|
||||
This is one end-to-end sprint. Intermediate stages need not compile or be
|
||||
coherent; do not add compatibility scaffolding, human approval gates, or external
|
||||
publication dependencies to make them independently deployable. Keep dependency
|
||||
adoption in a focused commit for diagnosis, not as a review gate. Run checks
|
||||
when their dependencies are present and record incomplete verification honestly.
|
||||
Reuse successful checks for unchanged content. Do not publish a release.
|
||||
|
||||
## Implementation Decisions
|
||||
|
||||
- Keep the existing identity registrations, configuration specification version,
|
||||
public APIs, and normalization rules. Do not normalize resource IDs, namespaces,
|
||||
references, model names, content, or `content_file` paths.
|
||||
- Capture existing backend/profile field states and prompt-input metadata from
|
||||
`Resolution.EntryInfo` before any assignment. Preserve omission, inherited
|
||||
explicitness, null, empty strings, false, and zero independently of normalized
|
||||
values. Do not retain callback contexts beyond their lifetime.
|
||||
- Perform changed-field assignments in `Resolve` and record exact final-index
|
||||
paths. Compare old/new scalar values before recording; preserve nil pointers
|
||||
and absent optional containers. Use concise value-free reasons. A small typed
|
||||
helper for optional strings is appropriate; a reflective traversal framework
|
||||
or a second configuration tree is not needed.
|
||||
- Resource lists inside `Collections` need map-entry copy/writeback. Modify the
|
||||
actual slices/pointers and write collection values back; helper targets and
|
||||
recorded paths must agree with the final typed document.
|
||||
- Visit records and nested fields directly. Build a uniqueness set once per
|
||||
resource list for the eligibility check below; avoid a metadata snapshot or
|
||||
full-resource search per scalar. Retain the existing lazy shared origin lookup
|
||||
for content materialization.
|
||||
- Before changing a registered list, check its final typed IDs once using the
|
||||
existing local-ID predicate and an exact-ID uniqueness set. If any ID is invalid
|
||||
or duplicated, leave that entire resource list unmodified by normalization and
|
||||
defaulting. ConfigKit's final identity validation and PromptKit's existing
|
||||
domain validation then reject it at their ordinary boundaries. This is an
|
||||
internal mutation-eligibility check on final values, not source prevalidation,
|
||||
identity repair, or a new acceptance rule. Test the invalid-ID-plus-padding
|
||||
combination so it cannot become an unrecorded-list-mutation error.
|
||||
- Successful endpoint normalization is assigned and recorded. If normalization
|
||||
fails, leave the original field unchanged; pure semantic validation reports
|
||||
the endpoint error using the existing validation boundary. Do not use a generic
|
||||
returned resolver error that hides the useful field diagnostic. Shared domain
|
||||
functions may be used for pure checks without assigning in validation.
|
||||
- Queue defaulting remains `concurrency_limit != nil && > 0 && queue_capacity ==
|
||||
nil`. Assign 1024 and call `RecordDerivedDefault` at `queue_capacity`, with
|
||||
`concurrency_limit` as dependency. Do not substitute `Default`: explicit null
|
||||
currently receives this default too. Explicit zero remains zero.
|
||||
- `Validate` checks the resolved document without mutation. Domain construction,
|
||||
prompt compilation, and file loading remain at their current appropriate
|
||||
boundaries. Preserve public error identities where applicable, not exact text,
|
||||
diagnostic ordering, or callback timing.
|
||||
- Retain request-time normalization, backend-to-profile completion, runtime-owned
|
||||
copies, and detached public results. They serve different purposes from the
|
||||
duplicate interpreted configuration being removed.
|
||||
|
||||
## Stage 1: Adopt Released ConfigKit v1.1.0
|
||||
|
||||
Scope: module metadata and applicable attribution only.
|
||||
|
||||
1. Update `go.maximumdirect.net/configkit` to v1.1.0 using the compatible local
|
||||
Go installation. Update sums without unrelated dependency upgrades or a
|
||||
committed filesystem replacement. Keep Go 1.27.0 unless the actual dependency
|
||||
metadata requires a change; no increase is planned.
|
||||
2. Review the selected release's license and notices. Update its House Format
|
||||
entry in `docs/oss/attribution.md`, including version and commit-pinned links.
|
||||
The local upstream v1.1.0 tag currently resolves to
|
||||
`191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9`; verify against the selected source.
|
||||
3. Run `go test ./...` with caches prepared. Resolve only actual compatibility
|
||||
failures; do not start the normalization refactor in this dependency unit.
|
||||
|
||||
Acceptance: module and notices select the release, the existing suite works,
|
||||
and no local replacement or unrelated upgrade was introduced.
|
||||
|
||||
Completion: ConfigKit v1.1.0 and its commit-pinned notices are selected; the
|
||||
complete Go test suite passed with Go 1.27.0.
|
||||
|
||||
## Stage 2: Record Backend And Profile Transformations
|
||||
|
||||
Scope: `internal/configuration/load.go`, focused normalization helpers if useful,
|
||||
and backend/profile loading tests.
|
||||
|
||||
1. Keep presence capture first in `Resolve`. Add the final-list eligibility check
|
||||
and in-place traversal for root and collection backends/profiles.
|
||||
2. Replace detached backend interpretation with field records for base endpoint,
|
||||
API-key environment name, smoke reachability/authentication endpoints, and
|
||||
authentication kind. Preserve existing endpoint helper behavior, including
|
||||
diagnostic endpoints' distinct rules. Authentication kind trims/lowercases;
|
||||
environment names only trim.
|
||||
3. Record the conditional queue assignment exactly as specified above. Do not
|
||||
manufacture absent smoke-test containers or fields.
|
||||
4. Normalize profiles' nonempty endpoint overrides and supplied service-tier,
|
||||
reasoning-effort, and API-key environment strings. An exactly empty endpoint
|
||||
override remains distinct from whitespace which fails endpoint normalization.
|
||||
5. Move endpoint failure checks into pure validation on effective fields.
|
||||
Temporarily remaining interpretation helpers must not repeat mutation or
|
||||
maintain a second backend/profile normalization policy.
|
||||
6. Adapt `TestLoadInterpretsBackendNormalizationAndNullDefault` and the target
|
||||
case in `interpretation_test.go`: inspection now contains normalized values
|
||||
and defaulted capacity, while execution settings remain as before. Add exact
|
||||
field-operation assertions and one unchanged-field/no-new-event assertion.
|
||||
|
||||
Validation: focused `go test ./internal/configuration`, once the intermediate
|
||||
callback wiring supports it. Cover absent/null/zero capacity and missing/zero/
|
||||
positive concurrency, optional endpoint overrides, and invalid endpoints.
|
||||
|
||||
Completion: backend and profile fields are normalized during resolution with
|
||||
field-level records and queue-default dependency evidence; endpoint validation
|
||||
is non-mutating. Focused configuration tests pass on Go 1.27.0.
|
||||
|
||||
## Stage 3: Record Prompt Metadata And Configured Messages
|
||||
|
||||
Scope: prompt resolution helpers, `prompts.go`, and prompt loading tests.
|
||||
|
||||
1. Traverse root/collection prompt lists with the same eligibility handling.
|
||||
Move description/session-template trimming, input-name trimming, optional
|
||||
input content-type/description trimming, and optional output schema-path
|
||||
trimming from `interpretPrompts` into exact field records.
|
||||
2. For configured messages, reuse `domain.NormalizeMessageRole` and
|
||||
`domain.NormalizeCacheControl`. Write back only changed supplied scalar
|
||||
fields at `messages/<index>/role` or `cache_control/type` and `cache_control/ttl`.
|
||||
Preserve required-field errors for absent role/type. Do not allocate an
|
||||
omitted cache control or TTL, lowercase cache-control types, trim content,
|
||||
or record an entire message/list merely to cover a scalar change.
|
||||
3. If a message normalizer rejects a value, leave that field/group unchanged and
|
||||
let existing message validation/construction reject it with useful context.
|
||||
Keep shared domain checks where needed for validation; remove redundant
|
||||
configuration-specific assignment logic from materialization. Caller-appended
|
||||
messages continue using their runtime normalizers.
|
||||
4. Keep content-file opening, template compilation, output-contract construction,
|
||||
duplicate normalized input-name checks, and hash construction in their existing
|
||||
owning paths. A trimmed schema path still addresses the selected schema source.
|
||||
5. Adapt prompt interpretation tests to the new inspection view. Add focused
|
||||
cases for padded roles, trim-only cache-control spelling, optional/null input
|
||||
metadata, and normalized input-name collisions. Compare padded and canonical
|
||||
definitions with the same identities for equivalent materialized definitions
|
||||
and hashes; do not freeze a new hash encoding.
|
||||
|
||||
Validation: prompt/configuration tests plus existing domain-message tests. Invalid
|
||||
roles, cache-control values, and missing required message fields still fail;
|
||||
explicit empty inline content retains its existing behavior.
|
||||
|
||||
Completion: prompt metadata and configured message fields are normalized and
|
||||
recorded during resolution. Focused configuration and domain tests pass,
|
||||
including equivalent prompt hashes and retained input presence.
|
||||
|
||||
## Stage 4: Use The Single Resolved Configuration
|
||||
|
||||
Scope: loader/target/materialization wiring and affected tests.
|
||||
|
||||
1. Change `Validate` to validate its supplied resolved document directly.
|
||||
Remove `loaded.interpreted`, `interpretConfiguration`, and obsolete detached
|
||||
interpretation helpers/copies after their transformations have moved.
|
||||
2. Route backend inventory/index construction, execution-profile construction,
|
||||
and prompt materialization through `state.result.Config`. Keep the captured
|
||||
entry field-state maps and prompt metadata needed for runtime presence/null
|
||||
semantics. Do not derive those states from newly defaulted pointer values.
|
||||
3. Preserve domain/runtime copying and public detachment. Keep the existing
|
||||
source-origin lookup for `content_file`; none of the selected transformations
|
||||
changes that field. No history scan or origin fallback is needed.
|
||||
4. Remove or rename tests whose old assertion was preservation of authored
|
||||
whitespace in configuration inspection. Retain their meaningful execution,
|
||||
ownership, and rejection assertions rather than weakening coverage wholesale.
|
||||
5. Check existing partial-profile completion, inherited endpoint/key settings,
|
||||
prepared execution, requirement metadata, and scoped inventories through the
|
||||
new single-configuration path.
|
||||
|
||||
Validation: `go test ./internal/configuration ./internal/engine` and the affected
|
||||
root API tests. Search for remaining interpreted-state consumers and confirm
|
||||
validation does not mutate the working configuration.
|
||||
|
||||
Completion: validation, inventories, execution profiles, and prompt construction
|
||||
use the single resolved configuration. The configuration, engine, and root API
|
||||
tests pass; no interpreted-state consumers remain.
|
||||
|
||||
## Stage 5: Verify Provenance And Inspection Integration
|
||||
|
||||
Scope: focused configuration tests and existing public inspection/diff tests.
|
||||
|
||||
1. Add representative root and collection cases covering field normalization
|
||||
operations and queue-derived-default dependency evidence. Check operation,
|
||||
path, effective value, and relevant retained source evidence without freezing
|
||||
whole histories, reason wording, source ordering, or upstream internals.
|
||||
2. Extend the inherited/imported content fixtures so a message role/cache-control
|
||||
edit occurs beside a `content_file` originating in another source directory
|
||||
or filesystem. Include later retained fields from a different contributor.
|
||||
Assert the expected file's captured content and unchanged effective origin;
|
||||
do not substitute a common directory that hides wrong-origin resolution.
|
||||
3. Combine invalid/duplicate final resource identities with fields needing
|
||||
normalization/defaulting. Assert useful rejection and absence of an accidental
|
||||
unrecorded-mutation failure. Retain existing tests that replaced lower-layer
|
||||
invalid values are not independently validated.
|
||||
4. Verify configuration diffs omit a value change when two otherwise identical
|
||||
definitions normalize to the same value, while genuinely changed list values
|
||||
still use ConfigKit's atomic list diff. Exercise the public passthrough rather
|
||||
than implementing PromptKit-specific diff equivalence.
|
||||
5. Extend existing sensitive-provider inspection coverage to normalized records
|
||||
and explanations as relevant. Reasons must not interpolate configuration
|
||||
values. Keep exact input metadata presence distinctions and public detachment.
|
||||
6. Reuse existing runtime/appended-message tests; add only missing boundary cases.
|
||||
Do not reproduce ConfigKit's generic identity-correspondence suite, add live
|
||||
provider tests, or introduce performance thresholds.
|
||||
|
||||
Validation: focused configuration, public inspection/diff, preparation, and
|
||||
execution tests. All new tests use deterministic offline sources/collaborators.
|
||||
|
||||
Completion: focused tests cover recorded target dependencies, imported content
|
||||
origins, invalid identities, normalized-value diffs, and sensitive inspection.
|
||||
Configuration, engine, and public API tests pass on Go 1.27.0.
|
||||
|
||||
## Stage 6: Align Documentation And Verify The Sprint
|
||||
|
||||
Scope: current contract/implementation documentation and final integration.
|
||||
|
||||
1. Update `docs/formats.md`, `docs/consumers/pkg-promptkit.md`,
|
||||
`docs/consumers/configuration-migration.md`, and `docs/internal/sources.md`
|
||||
where they describe authored/composed values excluding PromptKit normalization.
|
||||
Explain recorded effective normalization and defaults, retained provenance,
|
||||
normalized-value diff behavior, and the boundary with request completion.
|
||||
2. Review affected public GoDoc and architecture wording against the new callback
|
||||
flow. Change only stale claims; no new public API, YAML version, normalizer
|
||||
policy, origin guarantee, or execution-readiness promise is needed.
|
||||
3. Document the inspection/dependency change and its limits in the next release's
|
||||
`docs/releases/v0.18.0.md`, creating the note if needed under the release
|
||||
procedure. Keep canonical detail in the format/inspection guides. v0.17.0
|
||||
has been published: preserve its note, including its historical two-view
|
||||
normalization description. Do not publish, retag, or edit published notes
|
||||
for this work.
|
||||
4. Format changed Go files and run the integrated checks with the compatible
|
||||
local toolchain and prepared caches:
|
||||
|
||||
```sh
|
||||
go test -race -vet=off ./...
|
||||
go vet ./...
|
||||
go run ./examples/go-library/prepare
|
||||
go run ./examples/go-library/run
|
||||
go run ./examples/go-library/observe
|
||||
git diff --check
|
||||
```
|
||||
|
||||
The examples' successful output semantics should remain unchanged. No release
|
||||
launcher/profile change is planned, so the separate Python release-wiring
|
||||
diagnostic need not be rerun merely for this refactor.
|
||||
5. Review the full diff for presence loss, mutation outside resolution, broad
|
||||
list records, duplicate configuration state, stale docs, and unintended API
|
||||
changes. Record completion in the feature roadmap; retire it and its catalog
|
||||
pointer during normal completed-roadmap cleanup. Follow focused commit policy.
|
||||
|
||||
Completion means the one resolved configuration drives inspection and runtime
|
||||
construction; all selected transformations have field-level records; unchanged
|
||||
resource origins and runtime semantics are preserved; tests and documentation
|
||||
cover the intentional inspection change. There are no unresolved product
|
||||
decisions or upstream publication steps required by this plan.
|
||||
|
||||
Completion: current guides and the next release note describe recorded effective
|
||||
normalization and its limits. The race-enabled full suite, vet, and all three
|
||||
example commands passed with Go 1.27.0; the full diff and formatting were reviewed.
|
||||
Reference in New Issue
Block a user