Files
promptkit/docs/adr/0002-shared-configuration-data-model.md

63 lines
2.8 KiB
Markdown
Raw Normal View History

# 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.