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

2.9 KiB

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 unchanged. The shared-loading guide describes the implemented consumer workflow; the internal overview describes its implementation.