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

# 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 completed filesystem and layered-loading request is preserved in Git history
at `b604aa1:docs/roadmap/feature-request-promptkit.md`. The implemented
[layered-loading contract](../config.md#layered-loading) covers acquiring
configuration from different sources and combining it under explicit composition
or precedence rules. The proposed ConfigKit design for this remaining request
is in the [named-inheritance roadmap](named-inheritance.md).

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.