Clarify resource version policy and roadmap planning scope

This commit is contained in:
2026-11-21 04:09:32 +00:00
parent f80ec1c42c
commit bb8ec2c792

View File

@@ -201,9 +201,9 @@ appropriate nested location. Source-relative context follows the effective
contributing field, not the location of the application document or mount point. contributing field, not the location of the application document or mount point.
ConfigKit-owned headers and directives retain their native semantics. The ConfigKit-owned headers and directives retain their native semantics. The
application owns its main configuration specification; PromptKit's registration application owns its configuration version policy. PromptKit's registration
must not replace that policy with its standalone document version rule. preserves that policy; PromptKit-specific resource version validation is removed
Independent source-version policies are deferred as described below. as described below.
An absent `promptkit` section contributes no application-supplied PromptKit An absent `promptkit` section contributes no application-supplied PromptKit
settings; selected bundled underlays can still contribute defaults during the settings; selected bundled underlays can still contribute defaults during the
@@ -226,8 +226,7 @@ inspection, ok := result.InspectSubtree(configkit.Keys("promptkit"))
PromptKit's `InspectConfiguration()` forwards the view's capabilities without PromptKit's `InspectConfiguration()` forwards the view's capabilities without
loading another configuration or rebuilding history, redaction, or comparison. loading another configuration or rebuilding history, redaction, or comparison.
Both application-owned loading and standalone construction use this reporting Both application-owned loading and standalone construction use this reporting
path. This replaces the earlier inspection deferral; independent source-version path. This replaces the earlier inspection deferral.
policies remain deferred.
The view is a reporting focus, not an isolation or access-control boundary. The view is a reporting focus, not an isolation or access-control boundary.
Accept ConfigKit's native behavior: Accept ConfigKit's native behavior:
@@ -261,28 +260,29 @@ claiming exclusive access to PromptKit information. Resource APIs continue to
select and describe logical prompts, profiles, and backends independently of select and describe logical prompts, profiles, and backends independently of
configuration-tree paths. configuration-tree paths.
### Deferred Independent Source-Version Policies ### Resource Version Validation
Different application and component header policies within one load are outside **Accepted:** this migration gives up PromptKit-specific validation of `version`
this initial addition. ConfigKit's existing shared-policy limitation remains. fields in resource documents, including collection, prompt, and profile
Planning must document a supported definitions. This is an intentional simplification with a small practical cost,
source/header arrangement using current semantics, including the consequence for not an unresolved compatibility requirement or a prerequisite for an upstream
application and collection documents declaring different specification versions. version-policy feature.
Do not imply those headers are independently checked, overwrite the application's
policy, preparse/strip headers, or perform a second load to simulate the deferred
capability. Standalone construction retains its applicable native version policy.
This remains outside both the accepted upstream addition and this migration; The application retains ownership of ConfigKit's version policy. ConfigKit-owned
neither typed lookup nor focused inspection provides independent version checks. headers and directives follow that policy and native composition semantics;
PromptKit adds no separate resource-version checks. Apply this resource decision
to both application-owned loading and standalone construction. Update examples
and migration guidance accordingly, without preparsing or stripping headers or
adding a second load.
## Guidance For Implementation Planning ## Guidance For Implementation Planning
### Validate The Pattern Against PromptKit ### Validate The Pattern Against PromptKit
First confirm the final upstream lookup and inspection contracts and availability. First confirm the final upstream lookup and inspection contracts and availability.
The ConfigKit agent exercised representative one-library and two-library prototypes using The ConfigKit agent exercised representative one-library and two-library
existing public callbacks plus a limited top-level lookup shim. Those passed prototypes using existing public callbacks plus a limited top-level lookup shim.
checks for defaults, normalization, validation, identities, sensitive inspection, Those passed checks for defaults, normalization, validation, identities, sensitive inspection,
trusted secret access, and mounted resource lookup. They were not a production trusted secret access, and mounted resource lookup. They were not a production
`Value` implementation or a real PromptKit integration. `Value` implementation or a real PromptKit integration.
@@ -307,23 +307,22 @@ the standalone convenience path through the same rules. Focus on these checks:
mounting, inheritance, and overrides. Document mutation-before-handoff behavior; mounting, inheritance, and overrides. Document mutation-before-handoff behavior;
no mutation-detection subsystem or ConfigKit deep-copy guarantee is required. no mutation-detection subsystem or ConfigKit deep-copy guarantee is required.
4. **Inspection facade and diagnostics.** Retain the native focused view and specify 4. **Inspection facade and diagnostics.** Retain the native focused view and specify
any public signature changes needed to forward it. `Value` can succeed without public signatures for its operations and load-diagnostic forwarding. Obtain
completed-load evidence; do not treat that as proof of a valid inspection view. diagnostics from the original result through PromptKit's consumer-owned
The proposed upstream method list does not explicitly include `Diagnostics`. interface, or use an upstream view method if supplied. Expose focused enumeration
Resolve forwarding from the original result through PromptKit's consumer-owned alongside native metadata and query operations. A PromptKit overview explanation
interface, or use an upstream view method if supplied. Preserve useful load selects `/promptkit`; the native empty path selects the whole application.
evidence without inventing component-specific diagnostic classification.
5. **CommandKit integration.** Coordinate migration of `ckprompt.ConfigScope` and Document what the interfaces do: their inputs, operations, outputs, and errors,
resource adapters. Its shared loader currently calls `InspectConfiguration()` and how registration, loading, and engine construction fit together. Keep this
for sources and diagnostics even for resource commands; preserve those commands guidance concrete; hypothetical misuse does not call for registration tracking,
and their diagnostics during migration. `ckconfig.View` currently accepts a another validation lifecycle, or defensive caveats.
concrete `*configkit.Metadata`; forwarding that alone would expose unfiltered
path discovery. Use the view's focused enumeration or apply the selected scope CommandKit neutrally exposes upstream PromptKit APIs. Any adapter updates are
in the adapter. A PromptKit overview explanation must request `/promptkit`: routine downstream adoption, not a constraint on PromptKit's public API or a
the native empty path still selects the whole application. Keep explicit query prerequisite for completing this migration. PromptKit's implementation plan covers
paths native and document the broader contextual evidence and ancestor-diff its own resource, inspection, and diagnostic capabilities; CommandKit owns how
semantics. Preserve operator capabilities rather than promise unchanged method those are presented through CLI commands.
signatures or rebuild ConfigKit behavior in CommandKit.
Specify the concrete registration, settings, and constructor shapes, source-helper Specify the concrete registration, settings, and constructor shapes, source-helper
adaptations, and migration examples after these checks. Identify any remaining adaptations, and migration examples after these checks. Identify any remaining
@@ -354,21 +353,20 @@ compatibility resolver.
inside `promptkit`. inside `promptkit`.
- Engine independence from later caller mutation of settings, including nested - Engine independence from later caller mutation of settings, including nested
maps and slices; trusted lookup does not replace redacted inspection. maps and slices; trusted lookup does not replace redacted inspection.
- Resource listings, resource reports, and load diagnostics through the migrated - Resource listings, resource reports, and load diagnostics through PromptKit's
CommandKit adapters; configuration output and overview explanations focused on public APIs; configuration output and overview explanations focused on
`/promptkit`, with native paths and redaction preserved. `/promptkit`, with native paths and redaction preserved.
- Focused discovery through the adapter despite unfiltered metadata; explicit - Focused enumeration alongside unfiltered metadata; explicit
queries outside the focus and shared source/history context retain native behavior. queries outside the focus and shared source/history context retain native behavior.
- Inspection remains frozen after settings mutation; absent, null, historical-only, - Inspection remains frozen after settings mutation; absent, null, historical-only,
and added/removed sections follow upstream semantics. Sibling difference records and added/removed sections follow upstream semantics. Sibling difference records
are excluded while ancestor differences remain; comparison works across different are excluded while ancestor differences remain; comparison works across different
application root types selecting the same scope. application root types selecting the same scope.
The product direction, including focused inspection, is accepted. Actual PromptKit The product direction, including focused inspection and removal of resource-version
integration, concrete public API shapes, diagnostic forwarding, CommandKit adapter validation, is settled. No product decisions remain before implementation planning.
migration, and the supported shared header policy remain planning work. Strict Concrete public API shapes, diagnostic forwarding, and verification of the actual
subtree isolation, a new comparison engine, and independent source-version policies PromptKit integration are implementation-planning work.
are not required by this design.
## Further Candidates ## Further Candidates