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

@@ -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