Adopt shared configuration model in architecture and implementation plan
This commit is contained in:
62
docs/adr/0002-shared-configuration-data-model.md
Normal file
62
docs/adr/0002-shared-configuration-data-model.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user