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
|
repair accounting, exhaustion, cancellation, and transient-retry semantics remain
|
||||||
unchanged; the change does not promise successful correction.
|
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
|
**Accepted:** the application composes configuration once through ConfigKit and
|
||||||
`promptkit` key. This gives applications a distinct configuration section for
|
passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit
|
||||||
PromptKit alongside their other settings. Do not add a configurable mounting key.
|
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`,
|
The root-key migration supports this handoff; changing YAML paths alone does not
|
||||||
`promptkit.prompts`, `promptkit.collections`, and `promptkit.schema_root`.
|
fulfill the feature. The architectural benefit is a single composition lifecycle
|
||||||
Collection-local fields remain inside their collection. ConfigKit-owned source
|
with native source context and provenance, rather than an application bridge
|
||||||
headers and directives retain their native semantics and locations; they do not
|
between separately loaded configurations.
|
||||||
automatically move inside `promptkit`.
|
|
||||||
|
### 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
|
Make a clean breaking migration with one canonical resolved location. Do not
|
||||||
support legacy root-level resource locations through aliases, automatic detection,
|
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`,
|
with `id`, and collection files can still contain local `prompts`, `profiles`,
|
||||||
`backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit
|
`backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit
|
||||||
import destinations and PromptKit source helpers mount those fragments at the
|
import destinations and PromptKit source helpers mount those fragments at the
|
||||||
appropriate nested location. This is fragment composition, not support for two
|
appropriate nested location. Source-relative context follows the effective
|
||||||
alternative application configuration layouts. Source-relative resource context
|
contributing field, not the location of the application document or mount point.
|
||||||
must continue to follow the effective contributing field.
|
|
||||||
|
|
||||||
PromptKit owns validation of its section, not sibling application settings.
|
ConfigKit-owned headers and directives retain their native semantics. The
|
||||||
Implementation planning must verify the ConfigKit loading boundary so that
|
application owns its main configuration specification; PromptKit must not impose
|
||||||
unrelated application sections can coexist without PromptKit interpreting or
|
its standalone document version on the whole application. Planning must account
|
||||||
rejecting their contents. Keep field validation within PromptKit's section.
|
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
|
An absent `promptkit` section contributes no application-supplied PromptKit
|
||||||
settings; bundled defaults can still operate. Old root-level keys such as
|
settings; selected bundled underlays can still contribute defaults during the
|
||||||
`prompts` and `profiles` are neither consumed nor specially rejected by PromptKit:
|
original load. Old root-level keys such as `prompts` and `profiles` are neither
|
||||||
they may be legitimate application-owned settings. Unknown fields inside
|
consumed nor specially rejected by PromptKit: they may be application settings.
|
||||||
`promptkit` remain configuration errors. This does not bypass ConfigKit's own
|
Unknown fields inside `promptkit` remain configuration errors. The application's
|
||||||
document/composition validation. Migration documentation must explain that an
|
own validation and ConfigKit's document/composition rules still apply to the
|
||||||
unmigrated application document can load without contributing its intended
|
whole document. Migration guidance must explain that unmigrated resources are
|
||||||
resources, with a missing prompt becoming apparent when selected. Do not add
|
not loaded and can therefore produce missing-resource errors when selected.
|
||||||
legacy-layout detection to compensate for that consequence.
|
|
||||||
|
### Inspection Boundary
|
||||||
|
|
||||||
Scope `InspectConfiguration` value reports and comparisons to PromptKit's section,
|
Scope `InspectConfiguration` value reports and comparisons to PromptKit's section,
|
||||||
retaining actual `promptkit.…` paths and relevant source provenance. Unrelated
|
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
|
merely because they share an input document. Preserve native ConfigKit redaction
|
||||||
and explanation semantics. Resource inspection remains resource-scoped.
|
and explanation semantics. Resource inspection remains resource-scoped.
|
||||||
|
|
||||||
Implementation planning must cover:
|
Prefer native ConfigKit scoped inspection over PromptKit-maintained reporting
|
||||||
|
adapters. The requirement concerns the public scope and ownership of inspection;
|
||||||
- Updating bundled underlays, source helpers, import destinations, identity
|
it does not independently promise that ConfigKit never visits sibling data
|
||||||
registrations, normalization, and validation to the new paths using ordinary
|
internally. Do not silently substitute whole-application reporting, reconstruct
|
||||||
ConfigKit composition.
|
source history, or reload a copied section to manufacture a scoped result.
|
||||||
- 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.
|
|
||||||
|
|
||||||
## Guidance For Implementation Planning
|
## Guidance For Implementation Planning
|
||||||
|
|
||||||
The product decisions above are accepted. Begin planning with a focused feasibility
|
### Start With The Public Integration Contract
|
||||||
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.
|
|
||||||
|
|
||||||
Then specify the concrete input/resolved Go shapes, source-helper adaptations,
|
Prepare a concrete consumer sketch covering registration, one application-owned
|
||||||
and migration examples. Keep the repair-default and configuration-root changes
|
load, whole-result engine construction, and PromptKit-scoped inspection. Also show
|
||||||
separately reviewable even if delivered in the same release. Neither needs a new
|
the standalone source-loading convenience path using the same machinery. Verify
|
||||||
execution subsystem or a compatibility resolver.
|
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:
|
Include focused checks for:
|
||||||
|
|
||||||
@@ -129,15 +214,21 @@ Include focused checks for:
|
|||||||
budgets for `none`; cover typed and runtime inputs as well as YAML.
|
budgets for `none`; cover typed and runtime inputs as well as YAML.
|
||||||
- Concrete budgets in inspection and prepared snapshots, with actual repair
|
- Concrete budgets in inspection and prepared snapshots, with actual repair
|
||||||
counters retaining their existing meaning.
|
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
|
- Missing `promptkit` with bundled defaults enabled and disabled, application-owned
|
||||||
root keys that resemble legacy settings, and unknown fields inside `promptkit`.
|
root keys that resemble legacy settings, and unknown fields inside `promptkit`.
|
||||||
- Inspection and comparison excluding sibling application values, including a
|
- Inspection and comparison excluding sibling application values, including a
|
||||||
change confined to a sibling section, while PromptKit paths and explanations
|
sibling-only change, while preserving native paths, provenance, and redaction.
|
||||||
retain native provenance and redaction behavior.
|
|
||||||
|
|
||||||
No further product decisions are currently identified. Public API details and the
|
The product direction is accepted. Exact API shapes, upstream capability gaps,
|
||||||
ConfigKit feasibility check remain planning work, not evidence that implementation
|
and their consequences remain planning work. If feasibility requires changing the
|
||||||
has already been validated.
|
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
|
## Further Candidates
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user