Plan application-owned ConfigKit resolution and whole-result handoff
This commit is contained in:
@@ -48,17 +48,77 @@ only after failed validation and can add generation latency and usage. Existing
|
||||
repair accounting, exhaustion, cancellation, and transient-retry semantics remain
|
||||
unchanged; the change does not promise successful correction.
|
||||
|
||||
## 2. Place Configuration Under A Root-Level `promptkit` Key
|
||||
## 2. Consume Application-Resolved Configuration Under `promptkit`
|
||||
|
||||
**Accepted:** move all PromptKit-owned configuration beneath the fixed root-level
|
||||
`promptkit` key. This gives applications a distinct configuration section for
|
||||
PromptKit alongside their other settings. Do not add a configurable mounting key.
|
||||
**Accepted:** the application composes configuration once through ConfigKit and
|
||||
passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit
|
||||
locates the fixed root-level `promptkit` section and consumes only that section,
|
||||
ignoring sibling application settings. The application does not extract, reshape,
|
||||
serialize, or reload a PromptKit-specific view. Do not add a configurable mounting
|
||||
key.
|
||||
|
||||
The resolved structure includes `promptkit.backends`, `promptkit.profiles`,
|
||||
`promptkit.prompts`, `promptkit.collections`, and `promptkit.schema_root`.
|
||||
Collection-local fields remain inside their collection. ConfigKit-owned source
|
||||
headers and directives retain their native semantics and locations; they do not
|
||||
automatically move inside `promptkit`.
|
||||
The root-key migration supports this handoff; changing YAML paths alone does not
|
||||
fulfill the feature. The architectural benefit is a single composition lifecycle
|
||||
with native source context and provenance, rather than an application bridge
|
||||
between separately loaded configurations.
|
||||
|
||||
### Current Boundary And Intended Consumer Workflow
|
||||
|
||||
Today, PromptKit accepts configuration sources and runs its own ConfigKit load.
|
||||
Its typed root document rejects unrelated application fields. Audita, for example,
|
||||
loads application settings separately, then uses their recorded main-source
|
||||
context to assemble embedded and companion PromptKit sources for another load.
|
||||
It does not currently hand PromptKit its resolved application configuration.
|
||||
|
||||
The target workflow is:
|
||||
|
||||
1. The application includes PromptKit's configuration definition/registration and
|
||||
desired bundled or application sources in its ordinary ConfigKit setup.
|
||||
2. ConfigKit composes and resolves the complete application configuration once,
|
||||
applying each component's registered rules.
|
||||
3. The application passes the whole resolved result to PromptKit, together with
|
||||
runtime collaborators such as its HTTP client. PromptKit captures its effective
|
||||
resources and constructs the engine without another configuration load.
|
||||
|
||||
File discovery, source selection, imports, layering, and application overrides
|
||||
remain application policy. Embedded prompt selection and companion-file imports
|
||||
join the original load; they do not disappear. The change removes context-transfer
|
||||
and duplicate-loading machinery, not application-specific execution requests,
|
||||
profile selection, required-resource checks, or diagnostics policy.
|
||||
|
||||
### Configuration Rules And Handoff
|
||||
|
||||
Expose a small public integration surface for PromptKit's configuration rules to
|
||||
participate in the application's ConfigKit load. Defaults, normalization, field
|
||||
validation, collection identity constraints, and sensitivity declarations remain
|
||||
PromptKit-owned rules applied through ConfigKit's native lifecycle. Applications
|
||||
must not reproduce these rules or depend on PromptKit's internal types.
|
||||
|
||||
The exact public registration and result-accepting API shapes require planning.
|
||||
The handoff must work with an application-owned result type, not require replacing
|
||||
its configuration model with PromptKit's root document type. Preserve effective
|
||||
values, source contexts for relative message/schema files, provenance, and native
|
||||
redaction. A decoded map alone or a serialized section loaded again is not an
|
||||
equivalent handoff.
|
||||
|
||||
Register desired bundled defaults as ordinary underlays before composition;
|
||||
engine construction must not inject another configuration layer into an already
|
||||
resolved result. Apply configured repair defaults from item 1 during resolution,
|
||||
so inspection and execution agree. Runtime request defaulting remains separate.
|
||||
|
||||
Retain source-loading construction as a convenience for consumers that want
|
||||
PromptKit to select its own loading path. It should use the same configuration
|
||||
rules and engine-capture path: load once, then hand off the result. Do not maintain
|
||||
two independent implementations of configuration semantics. Existing source
|
||||
selection choices remain available subject to the accepted layout migration.
|
||||
|
||||
### Fixed Section And Clean Migration
|
||||
|
||||
Move all PromptKit-owned document settings beneath `promptkit`, including
|
||||
`promptkit.backends`, `promptkit.profiles`, `promptkit.prompts`,
|
||||
`promptkit.collections`, and `promptkit.schema_root`. Collection-local fields
|
||||
remain inside their collection. Runtime collaborators are Go API inputs, not new
|
||||
YAML fields.
|
||||
|
||||
Make a clean breaking migration with one canonical resolved location. Do not
|
||||
support legacy root-level resource locations through aliases, automatic detection,
|
||||
@@ -69,24 +129,26 @@ Preserve convenient standalone files. Individual resource files can still begin
|
||||
with `id`, and collection files can still contain local `prompts`, `profiles`,
|
||||
`backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit
|
||||
import destinations and PromptKit source helpers mount those fragments at the
|
||||
appropriate nested location. This is fragment composition, not support for two
|
||||
alternative application configuration layouts. Source-relative resource context
|
||||
must continue to follow the effective contributing field.
|
||||
appropriate nested location. Source-relative context follows the effective
|
||||
contributing field, not the location of the application document or mount point.
|
||||
|
||||
PromptKit owns validation of its section, not sibling application settings.
|
||||
Implementation planning must verify the ConfigKit loading boundary so that
|
||||
unrelated application sections can coexist without PromptKit interpreting or
|
||||
rejecting their contents. Keep field validation within PromptKit's section.
|
||||
ConfigKit-owned headers and directives retain their native semantics. The
|
||||
application owns its main configuration specification; PromptKit must not impose
|
||||
its standalone document version on the whole application. Planning must account
|
||||
for application headers and optional PromptKit fragment headers in the same load,
|
||||
including the standalone convenience path, without inventing a second header
|
||||
parser or version-composition pass.
|
||||
|
||||
An absent `promptkit` section contributes no application-supplied PromptKit
|
||||
settings; bundled defaults can still operate. Old root-level keys such as
|
||||
`prompts` and `profiles` are neither consumed nor specially rejected by PromptKit:
|
||||
they may be legitimate application-owned settings. Unknown fields inside
|
||||
`promptkit` remain configuration errors. This does not bypass ConfigKit's own
|
||||
document/composition validation. Migration documentation must explain that an
|
||||
unmigrated application document can load without contributing its intended
|
||||
resources, with a missing prompt becoming apparent when selected. Do not add
|
||||
legacy-layout detection to compensate for that consequence.
|
||||
settings; selected bundled underlays can still contribute defaults during the
|
||||
original load. Old root-level keys such as `prompts` and `profiles` are neither
|
||||
consumed nor specially rejected by PromptKit: they may be application settings.
|
||||
Unknown fields inside `promptkit` remain configuration errors. The application's
|
||||
own validation and ConfigKit's document/composition rules still apply to the
|
||||
whole document. Migration guidance must explain that unmigrated resources are
|
||||
not loaded and can therefore produce missing-resource errors when selected.
|
||||
|
||||
### Inspection Boundary
|
||||
|
||||
Scope `InspectConfiguration` value reports and comparisons to PromptKit's section,
|
||||
retaining actual `promptkit.…` paths and relevant source provenance. Unrelated
|
||||
@@ -94,33 +156,56 @@ application values must not become part of PromptKit's reports or comparisons
|
||||
merely because they share an input document. Preserve native ConfigKit redaction
|
||||
and explanation semantics. Resource inspection remains resource-scoped.
|
||||
|
||||
Implementation planning must cover:
|
||||
|
||||
- Updating bundled underlays, source helpers, import destinations, identity
|
||||
registrations, normalization, and validation to the new paths using ordinary
|
||||
ConfigKit composition.
|
||||
- Reflecting nested paths in configuration inspection and diagnostics while
|
||||
preserving resource inspection and runtime IDs.
|
||||
- Migration guidance for application documents and explicit import destinations,
|
||||
including schema roots; standalone fragments should not need extra wrappers.
|
||||
- Focused coverage for sibling application settings, mounted collections and
|
||||
resources, default overlays, and source-relative message/schema resolution.
|
||||
Prefer native ConfigKit scoped inspection over PromptKit-maintained reporting
|
||||
adapters. The requirement concerns the public scope and ownership of inspection;
|
||||
it does not independently promise that ConfigKit never visits sibling data
|
||||
internally. Do not silently substitute whole-application reporting, reconstruct
|
||||
source history, or reload a copied section to manufacture a scoped result.
|
||||
|
||||
## Guidance For Implementation Planning
|
||||
|
||||
The product decisions above are accepted. Begin planning with a focused feasibility
|
||||
check of ConfigKit's public loading and inspection APIs: establish how to validate
|
||||
the `promptkit` section while allowing siblings, and how to scope effective-value
|
||||
reports, explanations, and comparisons while retaining native paths, provenance,
|
||||
and redaction. Do not reconstruct resolved configuration or source history, add a
|
||||
second composition pass, or quietly broaden inspection to the whole application.
|
||||
If the public API cannot support this boundary, report the specific gap and options
|
||||
before committing to an implementation design.
|
||||
### Start With The Public Integration Contract
|
||||
|
||||
Then specify the concrete input/resolved Go shapes, source-helper adaptations,
|
||||
and migration examples. Keep the repair-default and configuration-root changes
|
||||
separately reviewable even if delivered in the same release. Neither needs a new
|
||||
execution subsystem or a compatibility resolver.
|
||||
Prepare a concrete consumer sketch covering registration, one application-owned
|
||||
load, whole-result engine construction, and PromptKit-scoped inspection. Also show
|
||||
the standalone source-loading convenience path using the same machinery. Verify
|
||||
against ConfigKit's selected public API before committing to an implementation
|
||||
structure. This sketch should demonstrate reduced integration work, not merely
|
||||
move source-context reconstruction or PromptKit validation into application code.
|
||||
|
||||
The earlier ConfigKit v1.3.0 feasibility assessment verified loading a typed
|
||||
`promptkit` envelope with arbitrary siblings and explaining a section with native
|
||||
paths, provenance, and redaction. It reported that effective-output writing,
|
||||
opaque metadata, and comparison APIs were whole-result operations. That assessment
|
||||
**does not establish support for the expanded application-owned load and
|
||||
whole-result handoff**. Recheck current capabilities rather than assume that the
|
||||
envelope alone solves the new integration contract.
|
||||
|
||||
Specifically establish:
|
||||
|
||||
- How PromptKit's rules compose with an application's configuration definition,
|
||||
including defaults, normalization, identities, validation, and sensitivity.
|
||||
- How the public handoff accepts an application-owned resolved result while
|
||||
retaining usable field contexts and native inspection evidence.
|
||||
- How selected bundled defaults and standalone fragments join the original load,
|
||||
with the intended header/version rules.
|
||||
- How native scoped effective output, metadata/history, explanations, and
|
||||
comparisons support the inspection boundary, including absent sections.
|
||||
|
||||
If public APIs cannot support these responsibilities cleanly, identify the
|
||||
specific gap and propose a focused upstream capability request before designing
|
||||
workarounds. Keep such requests about public consumer capabilities, not ConfigKit
|
||||
internals. A map-copy/reload adapter or an application-maintained duplicate of
|
||||
PromptKit's configuration rules would defeat the accepted design.
|
||||
|
||||
### Implementation Scope And Validation
|
||||
|
||||
Then specify input/resolved Go shapes, registration and constructor signatures,
|
||||
source-helper adaptations, and migration examples. Update identity registrations,
|
||||
normalization, validation, bundled underlays, and inspection paths together.
|
||||
Keep the repair-default and resolved-configuration changes separately reviewable;
|
||||
the repair work need not wait for upstream integration capabilities. Neither needs
|
||||
a new execution subsystem or a compatibility resolver.
|
||||
|
||||
Include focused checks for:
|
||||
|
||||
@@ -129,15 +214,21 @@ Include focused checks for:
|
||||
budgets for `none`; cover typed and runtime inputs as well as YAML.
|
||||
- Concrete budgets in inspection and prepared snapshots, with actual repair
|
||||
counters retaining their existing meaning.
|
||||
- An application-owned configuration type with sibling settings, one native load,
|
||||
and a whole-result handoff that performs no second configuration load.
|
||||
- Equivalent effective PromptKit resources through registered application loading
|
||||
and standalone convenience loading when supplied equivalent sources.
|
||||
- Mixed embedded/operator collections, source-relative message/schema references,
|
||||
native inheritance and overrides, and field provenance surviving the handoff.
|
||||
- Missing `promptkit` with bundled defaults enabled and disabled, application-owned
|
||||
root keys that resemble legacy settings, and unknown fields inside `promptkit`.
|
||||
- Inspection and comparison excluding sibling application values, including a
|
||||
change confined to a sibling section, while PromptKit paths and explanations
|
||||
retain native provenance and redaction behavior.
|
||||
sibling-only change, while preserving native paths, provenance, and redaction.
|
||||
|
||||
No further product decisions are currently identified. Public API details and the
|
||||
ConfigKit feasibility check remain planning work, not evidence that implementation
|
||||
has already been validated.
|
||||
The product direction is accepted. Exact API shapes, upstream capability gaps,
|
||||
and their consequences remain planning work. If feasibility requires changing the
|
||||
agreed consumer workflow, surface that decision rather than narrowing the goal to
|
||||
root-key relocation alone. No implementation feasibility is claimed by this roadmap.
|
||||
|
||||
## Further Candidates
|
||||
|
||||
|
||||
Reference in New Issue
Block a user