From 248d0dbcf5de55860f20606802d7f237ea59b24e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 13:51:26 +0000 Subject: [PATCH] Adopt shared configuration model in architecture and implementation plan --- .../0002-shared-configuration-data-model.md | 62 ++++++++ docs/policy/architecture.md | 29 +++- .../configuration-integration-check.md | 10 +- docs/roadmap/future.md | 18 --- docs/roadmap/implementation.md | 136 +++++++++++------- docs/roadmap/next-release-considerations.md | 30 +++- 6 files changed, 210 insertions(+), 75 deletions(-) create mode 100644 docs/adr/0002-shared-configuration-data-model.md diff --git a/docs/adr/0002-shared-configuration-data-model.md b/docs/adr/0002-shared-configuration-data-model.md new file mode 100644 index 0000000..7b50cd2 --- /dev/null +++ b/docs/adr/0002-shared-configuration-data-model.md @@ -0,0 +1,62 @@ +# 0002: Share Configuration Data Types Across The Public Boundary + +## Status + +Accepted. + +## Date + +2026-11-21 + +## Context + +PromptKit is a Go library that applications use to configure and run prompts. +Applications use its public package; the code that loads settings and runs +prompts lives in internal packages. This separation normally lets the internal +code change without changing the application's interface. + +The planned configuration API lets applications load settings once and pass them to +PromptKit. Keeping separate public and internal definitions of those same +settings would require duplicate declarations and code to copy each field back +and forth. That adds maintenance work and opportunities to miss a field without +changing what the settings mean. + +## Decision + +Define the public configuration settings and their nested data types once in a +small, data-only internal package. Expose them through type aliases in the public +`promptkit` package. An alias gives the same Go type a public name; consumers +continue to use names such as `promptkit.Settings` without importing an internal +package. The internal configuration code uses the same definitions directly. + +This is a narrow exception to the rule against exposing internal types. These +settings are intentional public contracts, including their fields and +configuration tags. Their location does not make them private implementation +details that can be changed independently of the public API. + +The rest of the public boundary stays in place. Loading, validation, and +execution logic remain internal. Source-building helpers, execution requests, +runtime objects, and inspection reports keep separate representations where +they serve different purposes. Internal packages still do not import the public +package. Sharing declarations does not remove the copies needed to keep a +running engine independent of later application changes. + +## Alternatives Considered + +- Keep separate public and internal settings. This allows independent changes, + but provides little benefit when both describe the same configuration and + must stay synchronized. +- Put the shared types in a new public settings package. This also removes + duplication, but adds a public package when the existing `promptkit` package + already provides a suitable consumer interface. + +## Consequences + +Configuration fields have one declaration, and registration and resource +capture no longer need conversions between equivalent settings types. The +primary benefit is simpler maintenance; performance improvements are secondary. +Conversion into execution-ready objects and necessary ownership copies remain. + +This decision leaves the [ConfigKit ownership boundary](0001-configuration-boundary.md) +unchanged. The [feature roadmap](../roadmap/next-release-considerations.md) and +[implementation plan](../roadmap/implementation.md) track implementation. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 743690e..b4b5c28 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-09-27 +**Last Updated**: 2026-11-21 **Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) @@ -128,7 +128,8 @@ consumer contract requires a public package. Each package must have one cohesive responsibility and a clear dependency direction. Internal packages must not expose their types merely to simplify wiring, and the public facade must not leak internal representations through -exported signatures. Production packages under `internal/` must not import the +exported signatures, except for the deliberately public configuration data model +specified below. Production packages under `internal/` must not import the module root; the root facade may depend on internal implementation packages. New public packages require a durable consumer need that cannot be served cleanly by the root facade. @@ -136,12 +137,34 @@ cleanly by the root facade. The [internal component overview](../internal/overview.md) must be updated as packages are implemented or their responsibilities change. +### Shared Configuration Data Exception + +[ADR 0002](../adr/0002-shared-configuration-data-model.md) permits one canonical +set of public configuration settings and their nested data types in a small, +data-only internal package, exposed through aliases in the root `promptkit` +package. The facade and internal configuration adapter may use those same +declarations directly. Their fields, tags, and nested types are intentional +public contracts and receive the same API review as root-defined types. + +The shared package owns data declarations, not loading, normalization, +validation, or execution behavior. This exception does not authorize aliases +for arbitrary internal implementation types or merging configuration settings +with source-construction helpers, execution requests, runtime objects, or +inspection reports that have different meanings. Internal packages still must +not import the root facade. Runtime capture still owns the values it retains; +shared declarations do not replace necessary ownership copies. + +All other facade, dependency, and ownership rules remain in force. Concrete +package placement and implementation status belong in the active plan and, +once implemented, the internal component inventory. + ## Exported API Discipline Export the smallest contract required by real consumers. Exported declarations must have accurate GoDoc, stable semantics, and tests proportionate to their compatibility risk. Avoid speculative extension points, aliases for internal -types, and public constructors that expose assembly details. +types outside the shared configuration data exception, and public constructors +that expose assembly details. Once an exported API exists, its Go declaration and GoDoc own its exact public contract. Architecture documentation owns boundary rules, not a duplicate API diff --git a/docs/roadmap/configuration-integration-check.md b/docs/roadmap/configuration-integration-check.md index 9c6555b..c871aa2 100644 --- a/docs/roadmap/configuration-integration-check.md +++ b/docs/roadmap/configuration-integration-check.md @@ -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. diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index e351111..938c954 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 12796c9..b200eba 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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. diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index 7d4f44b..26d8934 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -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