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.
|
||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
**Base Policy Version:** 1.3
|
**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)
|
**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
|
Each package must have one cohesive responsibility and a clear dependency
|
||||||
direction. Internal packages must not expose their types merely to simplify
|
direction. Internal packages must not expose their types merely to simplify
|
||||||
wiring, and the public facade must not leak internal representations through
|
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.
|
module root; the root facade may depend on internal implementation packages.
|
||||||
New public packages require a durable consumer need that cannot be served
|
New public packages require a durable consumer need that cannot be served
|
||||||
cleanly by the root facade.
|
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
|
The [internal component overview](../internal/overview.md) must be updated as
|
||||||
packages are implemented or their responsibilities change.
|
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
|
## Exported API Discipline
|
||||||
|
|
||||||
Export the smallest contract required by real consumers. Exported declarations
|
Export the smallest contract required by real consumers. Exported declarations
|
||||||
must have accurate GoDoc, stable semantics, and tests proportionate to their
|
must have accurate GoDoc, stable semantics, and tests proportionate to their
|
||||||
compatibility risk. Avoid speculative extension points, aliases for internal
|
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
|
Once an exported API exists, its Go declaration and GoDoc own its exact public
|
||||||
contract. Architecture documentation owns boundary rules, not a duplicate API
|
contract. Architecture documentation owns boundary rules, not a duplicate API
|
||||||
|
|||||||
@@ -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
|
generated conversion boilerplate and experimental names are not proposed as a
|
||||||
new generator or a finalized public API.
|
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
|
## Results
|
||||||
|
|
||||||
| Area | Evidence |
|
| 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.
|
another component afterward. No component registry was needed.
|
||||||
|
|
||||||
Keep actual normalization and validation in one internal rule implementation.
|
Keep actual normalization and validation in one internal rule implementation.
|
||||||
Public settings conversions are ordinary facade boundary work, not another
|
The prototype's public settings conversions were ordinary facade boundary work,
|
||||||
composition pass. Capture owned execution values after successful loading.
|
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
|
The existing public source-construction types need not become the decoding model
|
||||||
merely because some fields resemble it.
|
merely because some fields resemble it.
|
||||||
|
|
||||||
|
|||||||
@@ -38,24 +38,6 @@ consumers.
|
|||||||
|
|
||||||
## Ideas
|
## 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
|
### Schema Bundling
|
||||||
|
|
||||||
Allow consumers to author reusable schemas across multiple files and package
|
Allow consumers to author reusable schemas across multiple files and package
|
||||||
|
|||||||
@@ -15,7 +15,8 @@ Reinspect the working tree before starting. Preserve unrelated work. Read
|
|||||||
[agents](../policy/agents.md), [architecture](../policy/architecture.md),
|
[agents](../policy/agents.md), [architecture](../policy/architecture.md),
|
||||||
[testing](../policy/testing.md), [documentation](../policy/documentation.md), and
|
[testing](../policy/testing.md), [documentation](../policy/documentation.md), and
|
||||||
[OSS](../policy/oss.md). Preserve the accepted
|
[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
|
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
|
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
|
- 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.
|
consumer minimum at Go 1.27.0. No sibling-repository change is needed.
|
||||||
- Keep the root facade and internal implementation boundary. The shared-model
|
- Keep the root facade and internal implementation boundary, with ADR 0002's
|
||||||
proposal in [future.md](future.md#shared-configuration-data-model) is not part
|
narrow exception: define the public settings once in `internal/settings` and
|
||||||
of this sprint: no public aliases for internal settings and no new public
|
expose root aliases. The configuration adapter uses those declarations directly.
|
||||||
settings package. Use explicit facade data declarations and typed conversions.
|
No new public settings package or equivalent-model conversion layer is needed.
|
||||||
- ConfigKit owns acquisition, composition, inheritance, source-version policy,
|
- ConfigKit owns acquisition, composition, inheritance, source-version policy,
|
||||||
and native inspection. PromptKit interprets final values and captures its
|
and native inspection. PromptKit interprets final values and captures its
|
||||||
resources. Do not inspect raw contributions or replay history for execution.
|
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
|
### Settings Model
|
||||||
|
|
||||||
Add ordinary root-package structs with these fields, corresponding to the
|
Declare the following structs once in `internal/settings`, corresponding to the
|
||||||
current adapter records in `internal/configuration/load.go`. All configuration
|
current adapter records in `internal/configuration/load.go`. Expose each under
|
||||||
fields have explicit existing snake-case YAML tags; `Application` is the native
|
the same name in the root package with an alias, such as
|
||||||
`map[string]any` field tagged `yaml:",inline"`.
|
`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 |
|
| Public type | Fields |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
@@ -128,18 +132,33 @@ fields have explicit existing snake-case YAML tags; `Application` is the native
|
|||||||
| `PromptCacheControlSettings` | `Type, TTL *string` |
|
| `PromptCacheControlSettings` | `Type, TTL *string` |
|
||||||
| `PromptOutputSettings` | `Format, ValidationMode *string`; `Schema any`; `SchemaFile, SchemaPath *string`; `RepairAttempts *int` |
|
| `PromptOutputSettings` | `Format, ValidationMode *string`; `Schema any`; `SchemaFile, SchemaPath *string`; `RepairAttempts *int` |
|
||||||
|
|
||||||
Reuse the existing public backend smoke/probe data types, whose fields and YAML
|
Move the data declarations for `BackendSmokeTestConfig`,
|
||||||
bindings already match. Keep all nested PromptKit-owned objects strict. No
|
`ReachabilityProbeConfig`, and `AuthenticationProbeConfig` into the same shared
|
||||||
`Version` or `Extends` field is needed in this effective settings model: ConfigKit
|
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
|
handles inheritance controls before decoding, and resource `version` data can
|
||||||
reside in the allowed inline maps. Existing `PromptConfig`, `ProfileConfig`, and
|
reside in the allowed inline maps. Existing `PromptConfig`, `ProfileConfig`, and
|
||||||
`BackendConfig` remain source-construction values, including their `Extends`
|
`BackendConfig` remain source-construction values, including their `Extends`
|
||||||
fields; they are not substitutes for these decoding types.
|
fields; they are not substitutes for these decoding types.
|
||||||
|
|
||||||
Provide corresponding internal adapter data types where needed for typed
|
The shared package contains data declarations and their field documentation;
|
||||||
conversion; public signatures do not expose them. Conversions preserve nil versus
|
loading, normalization, validation, and resource capture stay in their existing
|
||||||
empty containers, pointers, all known fields, and application maps through
|
owners. It imports neither the facade nor configuration/engine/domain logic.
|
||||||
normalization. They do not serialize, decode again, or apply precedence.
|
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
|
### 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
|
accounting continue consuming resolved integers. Broader call-site migration is
|
||||||
assigned to Stages 11 and 12; do not retain a legacy request-input alternative.
|
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
|
1. Declare the nine settings structs in the model table in `internal/settings`,
|
||||||
GoDoc and YAML tags; reuse the existing backend smoke/probe structs.
|
with canonical field GoDoc and YAML tags. Add the three backend smoke/probe
|
||||||
2. Adapt the internal settings records to expose only the internal data boundary
|
declarations there with their existing fields and serialization tags.
|
||||||
needed for explicit conversions. Remove their obsolete `Version` field.
|
2. Expose root aliases for all twelve data types. Keep existing public smoke/probe
|
||||||
Add inline application maps at the five selected levels only.
|
names usable in source helpers and resource reports. The shared package has no
|
||||||
3. Implement straightforward typed conversion in both directions. Preserve all
|
loading, normalization, validation, capture, or execution behavior and no
|
||||||
values and unknown maps when returning normalized settings to the application.
|
dependency on the root facade.
|
||||||
Do not use JSON/YAML round-trips, reflection-based registration, or public
|
3. Replace equivalent adapter decoding records with the shared types, including
|
||||||
aliases to internal types. A new code-generation subsystem is unnecessary.
|
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
|
4. Keep existing source helpers independent. Do not add `Extends` to the effective
|
||||||
schema or silently change primitive/null rules such as `Required bool`.
|
schema or silently change primitive/null rules such as `Required bool`.
|
||||||
5. Add small decoding/conversion tests covering nested known fields, nil/empty
|
5. Use external-package decoding tests with nested root-name composite literals,
|
||||||
containers, and retained application maps. Resource provider maps and nested
|
including smoke/probe settings, nil/empty containers, and application maps.
|
||||||
owned object schemas retain their current validation.
|
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`
|
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
|
## 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.
|
4. Remove `checkConfigurationVersion` and PromptKit's `VersionRule` installation.
|
||||||
Do not preparse sources, strip version fields, or install a replacement
|
Do not preparse sources, strip version fields, or install a replacement
|
||||||
resource-version policy.
|
resource-version policy.
|
||||||
5. Implement `Configure` with the callback composition specified above. Convert
|
5. Implement `Configure` with the callback composition specified above. Pass the
|
||||||
selected public settings for the internal rules, write normalized settings
|
selected settings pointer directly to the internal rules. Normalize it in
|
||||||
back, and preserve application maps. Leave application defaults/version rules
|
place through ConfigKit's recorded operations, preserving application maps.
|
||||||
intact; component defaults such as queue and repair budgets use resolution.
|
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,
|
6. Cover callback error propagation, native sensitivity, application validation,
|
||||||
and registration preservation in focused tests. Do not add detection that a
|
and registration preservation in focused tests. Do not add detection that a
|
||||||
consumer registered a particular helper or used a particular callback order.
|
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
|
Focus: `internal/configuration/load.go`, `prompts.go`, `targets.go`, and
|
||||||
`resources.go`.
|
`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
|
native focused `configkit.Inspection` and detached load diagnostics. This
|
||||||
adapter operation is not another ConfigKit lifecycle.
|
adapter operation is not another ConfigKit lifecycle.
|
||||||
2. Read a final metadata snapshot once for construction and share it across
|
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
|
1. Add public `Configuration`, `RuntimeConfig`, and `NewFromConfig`. Select
|
||||||
`Value(Keys("promptkit"))`, handle the accepted terminal forms, obtain the
|
`Value(Keys("promptkit"))`, handle the accepted terminal forms, obtain the
|
||||||
focused view, and capture original-result diagnostics. Forward converted
|
focused view, and capture original-result diagnostics. Pass the selected shared
|
||||||
settings and native evidence to the internal capture operation.
|
settings and native evidence directly to the internal capture operation.
|
||||||
2. Map nil/unavailable inspection, wrong section type, invalid options, and
|
2. Map nil/unavailable inspection, wrong section type, invalid options, and
|
||||||
capture failures through `ErrInvalidConfig`. Preserve wrapped ConfigKit errors
|
capture failures through `ErrInvalidConfig`. Preserve wrapped ConfigKit errors
|
||||||
on the source-loading path. Do not run `Configure`, normalize again, inject
|
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.
|
same handoff/capture/assembly path. A nil main uses `NoSource` as before.
|
||||||
Use the standalone envelope and version behavior specified above.
|
Use the standalone envelope and version behavior specified above.
|
||||||
5. Remove the obsolete independent loader path and mutable typed-result storage.
|
5. Remove the obsolete independent loader path and mutable typed-result storage.
|
||||||
The internal engine need not import the facade: keep source loading and
|
The internal engine does not import the facade: keep source-loading orchestration
|
||||||
public model translation at the facade/configuration boundary and pass the
|
at the facade/configuration boundary, use the shared settings directly, and
|
||||||
captured adapter value inward for assembly.
|
pass the captured adapter value inward for assembly.
|
||||||
6. Document before-handoff mutation expectations rather than adding equality,
|
6. Document before-handoff mutation expectations rather than adding equality,
|
||||||
provenance-consistency, or registration checks. Existing after-construction
|
provenance-consistency, or registration checks. Existing after-construction
|
||||||
mutation protection remains.
|
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
|
1. Define an application with sibling settings, `Settings`, and a representative
|
||||||
second component. Preserve callbacks, defaults, version policy, registrations,
|
second component. Preserve callbacks, defaults, version policy, registrations,
|
||||||
sensitivity, normalization order, and validation diagnostics. Reuse the same
|
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
|
2. Load once and hand the entire result to `NewFromConfig`. Also use a wrapper
|
||||||
exposing only the three `Configuration` methods. Single-use/counted sources
|
exposing only the three `Configuration` methods. Single-use/counted sources
|
||||||
can prove construction does not reacquire configuration; expected message and
|
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.
|
Remove assertions that the report is exclusively a PromptKit configuration.
|
||||||
5. Update implemented package responsibilities and the architecture policy's
|
5. Update implemented package responsibilities and the architecture policy's
|
||||||
current engine-loading description to the shared registered-load/capture
|
current engine-loading description to the shared registered-load/capture
|
||||||
arrangement. Retain its facade and data-ownership constraints; do not adopt
|
arrangement. Document the implemented shared data package and root aliases
|
||||||
the future shared-model exception or alter the accepted ADR.
|
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
|
6. Search current documentation/examples for stale old paths, integer runtime
|
||||||
inputs, source-version enforcement, and old repair defaults. Preserve
|
inputs, source-version enforcement, and old repair defaults. Preserve
|
||||||
published release notes as historical records. This sprint does not prepare
|
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
|
## Stage 17 — Complete End-To-End Verification And Remove Superseded Machinery
|
||||||
|
|
||||||
1. Review the final code against both feature sections and the integration
|
1. Review the final code against both feature sections and the integration
|
||||||
assessment. Confirm one library rule implementation, one capture path, one
|
assessment, using ADR 0002 and this plan for the shared-model change from the
|
||||||
assembly path, and no original-result retention for mutable application config.
|
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,
|
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
|
2. Confirm application extensions stay in loaded settings and frozen native
|
||||||
inspection without needing to be carried into execution. Final capture uses
|
inspection without needing to be carried into execution. Final capture uses
|
||||||
effective metadata only; ordinary runs do not analyze provenance. Preserve
|
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
|
Completion requires implemented repair defaults for configuration and runtime
|
||||||
inputs, an application-owned single-load handoff, equivalent standalone loading,
|
inputs, an application-owned single-load handoff, equivalent standalone loading,
|
||||||
all selected extension/inspection behavior, owned execution capture, migrated
|
one shared public/adapter settings model, all selected extension/inspection behavior,
|
||||||
consumer examples/docs, and successful final validation. No product decision
|
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
|
remains open; private helper names and file organization may follow the existing
|
||||||
code without changing these public shapes or scope.
|
code without changing these public shapes or scope.
|
||||||
|
|||||||
@@ -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
|
two independent implementations of configuration semantics. Existing source
|
||||||
selection choices remain available subject to the accepted layout migration.
|
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
|
### Fixed Section And Clean Migration
|
||||||
|
|
||||||
Move all PromptKit-owned document settings beneath `promptkit`, including
|
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,
|
The [implementation plan](implementation.md) owns the concrete API choices,
|
||||||
ordered work, migration steps, and verification needed to reach this target.
|
ordered work, migration steps, and verification needed to reach this target.
|
||||||
The shared configuration-model simplification remains a separate
|
The prototype used separate public/internal settings and conversions; the
|
||||||
[future idea](future.md#shared-configuration-data-model), rather than a change to
|
accepted shared model replaces that experimental boundary arrangement. Its
|
||||||
the architecture policy or this feature's scope.
|
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
|
CommandKit and other consumers own their adapters and presentation. Their adoption
|
||||||
is not a prerequisite for implementing PromptKit's resource, inspection, and
|
is not a prerequisite for implementing PromptKit's resource, inspection, and
|
||||||
|
|||||||
Reference in New Issue
Block a user