Request named configuration inheritance for PromptKit

docs/roadmap/feature-request-promptkit-inheritance.md

@@ -0,0 +1,131 @@
+# PromptKit Feature Request: Opt-In Named Configuration Inheritance
+
+Status: downstream proposal for ConfigKit consideration, not an approved scope
+change, API design, or implementation plan.
+
+## Consumer Need
+
+PromptKit defines named execution profiles. A consumer can give an application
+profile a stable name, reference another profile as its base, and override only
+the settings it wants to change. Changing that base later does not require
+updating every prompt or application setting that selects the application name.
+
+For example, an application-owned `weather-light` profile might derive from a
+maintained standard profile and explicitly set a reasoning level or timeout.
+Another profile can derive from `weather-light`, creating a chain. Multiple
+children can share the same base. The selected child retains its own identity
+while obtaining effective settings from its ancestors.
+
+PromptKit requests consideration of a reusable, opt-in named-inheritance
+capability in ConfigKit. The goal is shared semantics for this structural
+relationship, not knowledge of LLM models, endpoints, or execution policy.
+ConfigKit should decide whether this belongs within its scope and what public
+contract, if any, would be appropriate.
+
+## Distinction From Layered Loading
+
+The separate [filesystem and layered-loading request](feature-request-promptkit.md)
+concerns acquiring configuration from different sources and combining it under
+explicit composition or precedence rules.
+
+Named inheritance concerns relationships between configuration entries: a child
+identifies a base, which may itself identify another base. The relationship
+determines which entries contribute to the child's effective settings. Source
+precedence and inheritance are different: choosing which definition owns an ID
+does not itself resolve that definition's relationship to another ID.
+
+The earlier request assumes PromptKit retains relationship interpretation. This
+proposal asks ConfigKit to reconsider that particular boundary; it does not
+replace or expand the two already-requested prerequisites by implication.
+Named inheritance remains optional for PromptKit's adoption of ConfigKit.
+
+## Desired Consumer Behavior
+
+- A caller can explicitly opt a collection of named entries into inheritance.
+  Ordinary configuration strings or similarly named fields must not acquire
+  reference semantics accidentally.
+- An entry can reference one base by name, inherit its effective settings, and
+  override selected values. Single inheritance is sufficient for PromptKit;
+  this request does not seek multiple-parent conflict resolution.
+- Chains and shared bases behave consistently regardless of declaration order.
+  A child's resolution does not mutate its base or change sibling results.
+- Missing bases, self-reference, and longer cycles produce actionable errors
+  identifying the relevant entries and source locations where available.
+- Omitted settings remain distinguishable from explicit zero, false, empty,
+  and null values. The chosen inheritance contract must explain which of these
+  inherit, replace, or clear rather than relying on Go zero-value heuristics.
+- Consumers can identify the origins of inherited and overridden settings.
+  Sources may be embedded, file-backed, or programmatic; a host file path is
+  not always available.
+- Callers can perform their domain validation on resolved settings without
+  teaching ConfigKit what those settings mean.
+
+These are behavior requests, not a proposed reserved `extends` key or API
+signature. How a caller declares the collection, identity, and relationship is
+for ConfigKit to decide. No automatic interpretation of arbitrary application
+relationships is requested.
+
+## PromptKit Semantics To Consider
+
+PromptKit's proposed refactor uses a single effective definition for each profile
+ID after source precedence has been applied. A base reference resolves within
+that effective collection, including application overrides of maintained profiles.
+Partial base profiles are useful even when they are not independently executable.
+
+Its current design direction is omission-based inheritance: explicit zero, false,
+and empty values replace inherited settings where meaningful, while null means
+unspecified for optional settings. Provider-parameter maps are atomic replacements,
+including an explicitly empty map, rather than recursive combinations of keys.
+
+These details expose questions a shared contract must address; they are not a
+request to build PromptKit-specific merge policies into ConfigKit. In particular,
+generic recursive mapping overlay may not have the same meaning as a complete
+provider-parameter replacement. PromptKit is pre-1.0 and can reconsider syntax
+and semantics when a coherent shared design warrants it. Any remaining domain
+exceptions should be explicit, not disguised as universal configuration rules.
+
+## Standardization Benefit
+
+The main benefit is consistency across consumers, not a large reduction in
+PromptKit's code size. Applications can each write a small resolver, but differ
+subtly in missing-reference handling, cycles, declaration-order dependence,
+precedence, empty/null behavior, collection replacement, or inherited origins.
+Those differences make configuration harder to transfer, explain, and maintain.
+
+A shared opt-in contract could let users learn these rules once and give
+libraries a common diagnostic and provenance model. Similar needs could arise
+in named processing presets, connection settings, or reusable job definitions;
+these are potential use cases, not claims of existing consumer demand.
+
+The benefit depends on consumers adopting a meaningful common contract. If the
+result requires arbitrary per-consumer merge and lookup strategies, much of that
+standardization disappears. ConfigKit may reasonably conclude that keeping
+relationship interpretation downstream is the better boundary.
+
+## Efficiency And Scope
+
+PromptKit expects to resolve definitions during construction and reuse the
+results for ordinary executions. Large collections with shared ancestors should
+not require repeated source loading, decoding, or avoidable repeated ancestor
+work. Evaluate processing cost relative to entries, relationships, materialized
+values, and retained provenance; this is not a fixed runtime or unconditional
+linear-memory guarantee. No internal algorithm or storage representation is
+prescribed here.
+
+The request excludes automatic hot reload, multiple inheritance, provider
+availability checks, model selection policy, credential lookup timing, and
+prompt execution. PromptKit continues to own LLM-specific validation and behavior
+whether or not ConfigKit adopts structural inheritance.
+
+## Decision Requested From ConfigKit
+
+Please evaluate whether explicit, domain-neutral named inheritance fits
+ConfigKit's scope, considering its [current configuration contract](../config.md)
+and [deliberate exclusions](deferred.md). This request does not assert that an
+earlier rejection exists or that any existing decision has been superseded.
+
+If accepted, define the shared consumer semantics and their relationship to
+layered loading, including presence, collection handling, and origins. If deferred
+or declined, PromptKit can retain its named-profile resolver while still adopting
+ConfigKit's generic filesystem and layered-loading capabilities. Neither outcome
+requires ConfigKit to understand the domain meaning of profile settings.