Adopt shared configuration model in architecture and implementation plan

This commit is contained in:
2026-11-21 13:51:26 +00:00
parent 515649fee0
commit 248d0dbcf5
6 changed files with 210 additions and 75 deletions

View File

@@ -38,6 +38,11 @@ The temporary copy is exploratory evidence, not a patch ready to merge. Its
generated conversion boilerplate and experimental names are not proposed as a
new generator or a finalized public API.
Subsequent design decision: [ADR 0002](../adr/0002-shared-configuration-data-model.md)
selects one shared settings model exposed through root aliases. The assessment
below records the experiment as run; its separate settings declarations and
conversions are superseded by the [implementation plan](implementation.md).
## Results
| Area | Evidence |
@@ -70,8 +75,9 @@ before library callbacks; a consumer could wrap the returned callbacks to run
another component afterward. No component registry was needed.
Keep actual normalization and validation in one internal rule implementation.
Public settings conversions are ordinary facade boundary work, not another
composition pass. Capture owned execution values after successful loading.
The prototype's public settings conversions were ordinary facade boundary work,
not another composition pass; the selected shared model removes them. Capture
owned execution values after successful loading.
The existing public source-construction types need not become the decoding model
merely because some fields resemble it.

View File

@@ -38,24 +38,6 @@ consumers.
## Ideas
### Shared Configuration Data Model
Use one canonical configuration data model for the public settings API and the
internal configuration adapter. This could reduce duplicate type declarations,
field-by-field conversions, construction-time allocations, and the maintenance
needed when configuration fields change.
- Consider a narrow architecture-policy exception allowing the root facade to
alias deliberately public, data-only settings types. A small public settings
package is an alternative if explicit public ownership is preferable.
- Treat shared settings types as intentional public contracts while retaining
loading, validation, and execution logic internally.
- Preserve owned runtime capture and independence from later caller mutation;
sharing type definitions does not eliminate necessary value copies.
Selection requires an explicit architecture-policy decision. Inclusion here does
not change that policy or expand the current configuration-handoff scope.
### Schema Bundling
Allow consumers to author reusable schemas across multiple files and package

View File

@@ -15,7 +15,8 @@ Reinspect the working tree before starting. Preserve unrelated work. Read
[agents](../policy/agents.md), [architecture](../policy/architecture.md),
[testing](../policy/testing.md), [documentation](../policy/documentation.md), and
[OSS](../policy/oss.md). Preserve the accepted
[configuration boundary ADR](../adr/0001-configuration-boundary.md).
[configuration boundary ADR](../adr/0001-configuration-boundary.md) and apply
[ADR 0002's shared configuration data exception](../adr/0002-shared-configuration-data-model.md).
The audience is a Luna coding agent. Execute the numbered stages in order as a
single end-to-end sprint. Each stage bounds one prompt's work; it is not a
@@ -31,10 +32,10 @@ completed, nonempty units; do not create empty commits.
- Use the published ConfigKit v1.4.0 module without local replacements. Keep the
consumer minimum at Go 1.27.0. No sibling-repository change is needed.
- Keep the root facade and internal implementation boundary. The shared-model
proposal in [future.md](future.md#shared-configuration-data-model) is not part
of this sprint: no public aliases for internal settings and no new public
settings package. Use explicit facade data declarations and typed conversions.
- Keep the root facade and internal implementation boundary, with ADR 0002's
narrow exception: define the public settings once in `internal/settings` and
expose root aliases. The configuration adapter uses those declarations directly.
No new public settings package or equivalent-model conversion layer is needed.
- ConfigKit owns acquisition, composition, inheritance, source-version policy,
and native inspection. PromptKit interprets final values and captures its
resources. Do not inspect raw contributions or replay history for execution.
@@ -111,10 +112,13 @@ does not rerun that lifecycle or track which helper registered the rules.
### Settings Model
Add ordinary root-package structs with these fields, corresponding to the
current adapter records in `internal/configuration/load.go`. All configuration
fields have explicit existing snake-case YAML tags; `Application` is the native
`map[string]any` field tagged `yaml:",inline"`.
Declare the following structs once in `internal/settings`, corresponding to the
current adapter records in `internal/configuration/load.go`. Expose each under
the same name in the root package with an alias, such as
`type Settings = settings.Settings`. All configuration fields have explicit
existing snake-case YAML tags; `Application` is the native `map[string]any` field
tagged `yaml:",inline"`. Consumers use the root names in their own typed
configuration and nested composite literals.
| Public type | Fields |
| --- | --- |
@@ -128,18 +132,33 @@ fields have explicit existing snake-case YAML tags; `Application` is the native
| `PromptCacheControlSettings` | `Type, TTL *string` |
| `PromptOutputSettings` | `Format, ValidationMode *string`; `Schema any`; `SchemaFile, SchemaPath *string`; `RepairAttempts *int` |
Reuse the existing public backend smoke/probe data types, whose fields and YAML
bindings already match. Keep all nested PromptKit-owned objects strict. No
`Version` or `Extends` field is needed in this effective settings model: ConfigKit
Move the data declarations for `BackendSmokeTestConfig`,
`ReachabilityProbeConfig`, and `AuthenticationProbeConfig` into the same shared
package and expose their existing root names as aliases. Preserve their fields,
JSON/YAML tags, and documented behavior. These types are nested in settings and
already used by source helpers and reports; moving their declarations avoids an
import cycle without merging those helpers or reports into the settings model.
Keep domain smoke values and meaningful conversions to them separate.
Keep all nested PromptKit-owned objects strict. No `Version` or `Extends` field
is needed in this effective settings model: ConfigKit
handles inheritance controls before decoding, and resource `version` data can
reside in the allowed inline maps. Existing `PromptConfig`, `ProfileConfig`, and
`BackendConfig` remain source-construction values, including their `Extends`
fields; they are not substitutes for these decoding types.
Provide corresponding internal adapter data types where needed for typed
conversion; public signatures do not expose them. Conversions preserve nil versus
empty containers, pointers, all known fields, and application maps through
normalization. They do not serialize, decode again, or apply precedence.
The shared package contains data declarations and their field documentation;
loading, normalization, validation, and resource capture stay in their existing
owners. It imports neither the facade nor configuration/engine/domain logic.
The adapter consumes the same settings types as the public API, preserving
nil/empty containers, pointers, and application fields without a settings
conversion round-trip. Root aliases have public GoDoc directing consumers to the
canonical field declarations. Treat the shared declarations as public API, not
as independently changeable private structs.
Keep necessary conversion and ownership copying into execution values and
resource reports. Runtime requests and resolved output contracts remain outside
this exception; their changes are described separately below.
### Repair Input And Resolved Types
@@ -263,27 +282,34 @@ Evidence: the input API distinguishes default from zero while execution and
accounting continue consuming resolved integers. Broader call-site migration is
assigned to Stages 11 and 12; do not retain a legacy request-input alternative.
## Stage 4 — Add The Public Settings Schema And Facade Conversions
## Stage 4 — Add The Shared Settings Schema And Root Aliases
Focus: a root settings file and internal configuration data declarations.
Focus: `internal/settings`, root settings aliases, `backends.go`, and the
configuration adapter's data declarations.
1. Declare the nine public settings structs in the model table, with precise
GoDoc and YAML tags; reuse the existing backend smoke/probe structs.
2. Adapt the internal settings records to expose only the internal data boundary
needed for explicit conversions. Remove their obsolete `Version` field.
Add inline application maps at the five selected levels only.
3. Implement straightforward typed conversion in both directions. Preserve all
values and unknown maps when returning normalized settings to the application.
Do not use JSON/YAML round-trips, reflection-based registration, or public
aliases to internal types. A new code-generation subsystem is unnecessary.
1. Declare the nine settings structs in the model table in `internal/settings`,
with canonical field GoDoc and YAML tags. Add the three backend smoke/probe
declarations there with their existing fields and serialization tags.
2. Expose root aliases for all twelve data types. Keep existing public smoke/probe
names usable in source helpers and resource reports. The shared package has no
loading, normalization, validation, capture, or execution behavior and no
dependency on the root facade.
3. Replace equivalent adapter decoding records with the shared types, including
nested settings. Remove the obsolete `Version` field and retain the inline
application maps at the five selected levels. Preserve Stage 2's pointer
budgets. Do not add duplicate public/internal settings or conversion helpers;
keep settings-to-domain conversion and owned capture where they do real work.
4. Keep existing source helpers independent. Do not add `Extends` to the effective
schema or silently change primitive/null rules such as `Required bool`.
5. Add small decoding/conversion tests covering nested known fields, nil/empty
containers, and retained application maps. Resource provider maps and nested
owned object schemas retain their current validation.
5. Use external-package decoding tests with nested root-name composite literals,
including smoke/probe settings, nil/empty containers, and application maps.
Verify the existing smoke/probe serialization shape and source-helper use
remain supported. Retain known-field and nested-object validation tests;
normalization and post-capture ownership are exercised in subsequent stages.
Evidence: an external application can declare its field as `promptkit.Settings`
without importing internal packages, and normalization can round-trip all fields.
and construct its nested values without importing internal packages. Public and
adapter settings share one declaration set with no conversion layer between them.
## Stage 5 — Extract Stateless Component Rules At Native Paths
@@ -302,10 +328,12 @@ Focus: `internal/configuration/load.go`, `resolve_prompts.go`,
4. Remove `checkConfigurationVersion` and PromptKit's `VersionRule` installation.
Do not preparse sources, strip version fields, or install a replacement
resource-version policy.
5. Implement `Configure` with the callback composition specified above. Convert
selected public settings for the internal rules, write normalized settings
back, and preserve application maps. Leave application defaults/version rules
intact; component defaults such as queue and repair budgets use resolution.
5. Implement `Configure` with the callback composition specified above. Pass the
selected settings pointer directly to the internal rules. Normalize it in
place through ConfigKit's recorded operations, preserving application maps.
Leave application defaults/version rules intact; component defaults such as
queue and repair budgets use resolution. No settings conversion or write-back
reconstruction is needed.
6. Cover callback error propagation, native sensitivity, application validation,
and registration preservation in focused tests. Do not add detection that a
consumer registered a particular helper or used a particular callback order.
@@ -318,7 +346,7 @@ capturing another load's resource state or taking over application version polic
Focus: `internal/configuration/load.go`, `prompts.go`, `targets.go`, and
`resources.go`.
1. Extract capture from loading: accept converted effective settings plus the
1. Extract capture from loading: accept the shared effective settings plus the
native focused `configkit.Inspection` and detached load diagnostics. This
adapter operation is not another ConfigKit lifecycle.
2. Read a final metadata snapshot once for construction and share it across
@@ -396,8 +424,8 @@ Focus: root `engine.go`, new configuration facade wiring,
1. Add public `Configuration`, `RuntimeConfig`, and `NewFromConfig`. Select
`Value(Keys("promptkit"))`, handle the accepted terminal forms, obtain the
focused view, and capture original-result diagnostics. Forward converted
settings and native evidence to the internal capture operation.
focused view, and capture original-result diagnostics. Pass the selected shared
settings and native evidence directly to the internal capture operation.
2. Map nil/unavailable inspection, wrong section type, invalid options, and
capture failures through `ErrInvalidConfig`. Preserve wrapped ConfigKit errors
on the source-loading path. Do not run `Configure`, normalize again, inject
@@ -410,9 +438,9 @@ Focus: root `engine.go`, new configuration facade wiring,
same handoff/capture/assembly path. A nil main uses `NoSource` as before.
Use the standalone envelope and version behavior specified above.
5. Remove the obsolete independent loader path and mutable typed-result storage.
The internal engine need not import the facade: keep source loading and
public model translation at the facade/configuration boundary and pass the
captured adapter value inward for assembly.
The internal engine does not import the facade: keep source-loading orchestration
at the facade/configuration boundary, use the shared settings directly, and
pass the captured adapter value inward for assembly.
6. Document before-handoff mutation expectations rather than adding equality,
provenance-consistency, or registration checks. Existing after-construction
mutation protection remains.
@@ -495,7 +523,10 @@ and PromptKit collaborators and an offline model client.
1. Define an application with sibling settings, `Settings`, and a representative
second component. Preserve callbacks, defaults, version policy, registrations,
sensitivity, normalization order, and validation diagnostics. Reuse the same
configured definition across independent and concurrent loads.
configured definition across independent and concurrent loads. Use only root
aliases in consumer declarations; verify normalized fields and retained
application maps are visible to subsequent application callbacks and in the
final result without public/internal settings conversions.
2. Load once and hand the entire result to `NewFromConfig`. Also use a wrapper
exposing only the three `Configuration` methods. Single-use/counted sources
can prove construction does not reacquire configuration; expected message and
@@ -587,8 +618,10 @@ and `docs/internal/{overview,sources,runner}.md`.
Remove assertions that the report is exclusively a PromptKit configuration.
5. Update implemented package responsibilities and the architecture policy's
current engine-loading description to the shared registered-load/capture
arrangement. Retain its facade and data-ownership constraints; do not adopt
the future shared-model exception or alter the accepted ADR.
arrangement. Document the implemented shared data package and root aliases
under ADR 0002, preserving its narrow scope and all remaining facade and
ownership constraints. Keep the accepted ADR decisions unchanged; the
ConfigKit handoff boundary in ADR 0001 still applies.
6. Search current documentation/examples for stale old paths, integer runtime
inputs, source-version enforcement, and old repair defaults. Preserve
published release notes as historical records. This sprint does not prepare
@@ -601,10 +634,14 @@ path, with no future behavior described as implemented before it lands.
## Stage 17 — Complete End-To-End Verification And Remove Superseded Machinery
1. Review the final code against both feature sections and the integration
assessment. Confirm one library rule implementation, one capture path, one
assembly path, and no original-result retention for mutable application config.
assessment, using ADR 0002 and this plan for the shared-model change from the
prototype. Confirm one settings declaration set, one library rule implementation,
one capture path, one assembly path, and no original-result retention for mutable
application config. Check that root aliases cover only the selected settings
and nested data types and that internal packages do not import the facade.
Remove dead generic-result bridges, version checks, resolver side maps,
temporary conversion scaffolding, and compatibility code left during staging.
equivalent-settings conversion scaffolding, and compatibility code left during
staging. Preserve meaningful domain conversions and ownership copies.
2. Confirm application extensions stay in loaded settings and frozen native
inspection without needing to be carried into execution. Final capture uses
effective metadata only; ordinary runs do not analyze provenance. Preserve
@@ -629,7 +666,8 @@ path, with no future behavior described as implemented before it lands.
Completion requires implemented repair defaults for configuration and runtime
inputs, an application-owned single-load handoff, equivalent standalone loading,
all selected extension/inspection behavior, owned execution capture, migrated
consumer examples/docs, and successful final validation. No product decision
one shared public/adapter settings model, all selected extension/inspection behavior,
owned execution capture, migrated consumer examples/docs, and successful final
validation. No product decision
remains open; private helper names and file organization may follow the existing
code without changing these public shapes or scope.

View File

@@ -180,6 +180,29 @@ rules and engine-capture path: load once, then hand off the result. Do not maint
two independent implementations of configuration semantics. Existing source
selection choices remain available subject to the accepted layout migration.
### Shared Configuration Data Model
**Accepted:** use one canonical set of configuration settings for the public API
and internal configuration adapter, under the narrow exception in
[ADR 0002](../adr/0002-shared-configuration-data-model.md) and the
[architecture policy](../policy/architecture.md#shared-configuration-data-exception).
Define the data types in a small internal package and expose them through root
aliases such as `promptkit.Settings`. Include the nested settings and backend
smoke/probe data types so both consumers and the adapter use the same declarations
without an internal dependency on the root package.
Registration and resource capture use that model directly. Remove duplicate
settings declarations and conversions that only copy equivalent fields between
the facade and adapter. The benefit is simpler field maintenance and fewer
opportunities for the two representations to diverge.
Source-building helpers retain their composition-oriented values. Runtime
requests, execution objects, and resource reports retain their distinct
representations and useful conversions. Preserve the ownership copies needed
when capturing executable resources. Loading, normalization, validation, and
execution behavior stay outside the shared data package. This is part of the
current configuration migration, not a later facade-wide refactor.
### Fixed Section And Clean Migration
Move all PromptKit-owned document settings beneath `promptkit`, including
@@ -321,9 +344,10 @@ and limits. This establishes feasibility, not completed production implementatio
The [implementation plan](implementation.md) owns the concrete API choices,
ordered work, migration steps, and verification needed to reach this target.
The shared configuration-model simplification remains a separate
[future idea](future.md#shared-configuration-data-model), rather than a change to
the architecture policy or this feature's scope.
The prototype used separate public/internal settings and conversions; the
accepted shared model replaces that experimental boundary arrangement. Its
external-package decoding, registration, and capture paths will be verified
during implementation alongside the existing ownership checks.
CommandKit and other consumers own their adapters and presentation. Their adoption
is not a prerequisite for implementing PromptKit's resource, inspection, and