diff --git a/docs/roadmap/inspect-backend.md b/docs/roadmap/inspect-backend.md index 0637e63..53fc336 100644 --- a/docs/roadmap/inspect-backend.md +++ b/docs/roadmap/inspect-backend.md @@ -1,10 +1,13 @@ -# Backend Inspection Roadmap +# Backend Inspection And Configuration API Roadmap ## Purpose And Status Add `Engine.InspectBackend` so applications can retrieve one backend's effective -definition by its runtime identity. The direction is accepted for planning; -implementation has not begun. The open decisions below remain to be resolved. +definition by its runtime identity, and expose existing backend inheritance +through `BackendConfig` and `BackendSource`. These additions are selected for +planning; implementation has not begun. The open decisions below remain to be +resolved. Typed prompt construction is a separate discussion item, and listing +return-type consistency is a possible later cleanup. The consumer benefit is backend-detail reporting without selecting an arbitrary profile or reconstructing domain settings from ConfigKit paths and list indexes. @@ -13,9 +16,10 @@ capacity settings, provider defaults, and diagnostic configuration. Promptkit owns this reusable interpretation; downstream applications own presentation, disclosure, CLI commands, and exit codes. -API symmetry alone does not justify the addition. The scope is a small typed -view over captured information that Promptkit already owns, with no new source -composition, validation framework, or execution lifecycle. +API symmetry alone does not justify additions. Prioritize backend inspection +with the recommended missing-backend error, followed by typed backend +inheritance. Both expose behavior or information Promptkit already owns, with +no new source composition, validation framework, or execution lifecycle. ## Relationship To Existing APIs @@ -31,7 +35,7 @@ See the [consumer guide](../consumers/pkg-promptkit.md#discover-available-resour for the implemented inspection and discovery boundaries, and the [architecture policy](../policy/architecture.md) for library responsibilities. -## Proposed Public Contract +## Proposed Backend Inspection Contract ```go func (e *Engine) InspectBackend( @@ -103,6 +107,57 @@ credentials or silently substitute ConfigKit's redacted reporting values for the typed settings. Operator provenance and redacted configuration reporting remain available through `InspectConfiguration`. +## Typed Backend Inheritance + +Add `Extends *string` to `BackendConfig`, matching `ProfileConfig.Extends`. +When non-nil, `BackendSource` should encode it as `extends: {id: value}` in the +backend record. Nil omits the field. Preserve the supplied value and let +ConfigKit resolve and validate inheritance through the existing source-loading +path, just as it does for profiles. + +The purpose is to let programmatic callers derive a backend variant without +switching from `BackendSource` to a raw mapping. The helper must not resolve a +parent, fill inherited fields, or become a second inheritance implementation. +It remains a source constructor rather than an engine registry mutation API. + +This exposes existing sibling inheritance, not a new configuration feature. +Parent IDs select siblings in the same root or collection resource list; +namespace views do not qualify these configuration references. Existing +same-ID replacement, omitted-field, and explicit-null behavior remain owned by +ConfigKit composition. Raw mappings remain available when callers need explicit +null or other generic configuration controls that the typed helper cannot express. +See the [inheritance reference](../formats.md#resource-inheritance) and the +existing [profile source helper](../../profiles.go). + +## Scope Of API Consistency + +Backends, profiles, and prompts already share source layering, collection +membership, namespace selection, sibling inheritance, and construction-time +definition validation. The gaps addressed here are in public convenience and +inspection APIs, not in those underlying configuration capabilities. + +Inspection remains purpose-specific: `InspectPrompt` reports prompt interface +metadata, `InspectProfile` reports backend-completed execution settings, and +`InspectBackend` will describe an effective backend. This work does not turn +them into uniform complete-definition retrieval APIs. Expanding prompt inspection +to return descriptions, message templates, or session templates should follow a +concrete consumer need rather than the new backend result's shape. + +`ListPrompts` currently returns `[]PromptIdentity`, whose only field is `ID`; +`ListProfiles` and `ListBackends` return `[]string`. At a suitable breaking-change +window, prefer considering `[]string` for all three over adding thin identity +wrappers for backends and profiles. That would simplify consumer code, but +requires a deliberate compatibility decision and migration instructions. Keep +the existing return types in this work; listing consistency does not block the +backend additions. + +Collections, schemas, and engine configuration remain distinct concepts rather +than additional peers requiring identical resource APIs. Prompt requirement +inspection and backend capacity/diagnostic settings retain their specialized +roles. Profile/backend hashes are not added for symmetry; the existing +[deferred fingerprint proposal](deferred.md#semantic-execution-target-fingerprints) +owns that separate question. + ## Open Decisions ### 1. Declared Diagnostic Settings Or Derived Destinations? @@ -143,9 +198,29 @@ invalid selection. Consumers needing different presentation would then require an inventory lookup or additional error detail. A sentinel is the smaller consumer-facing solution when that distinction matters. +### 3. Should Typed Prompt Construction Be Added In This Round? + +**Recommendation:** Keep `PromptConfig` and `PromptSource` as a separate +discussion item until a programmatic prompt-authoring use case establishes +their value. File sources and ConfigKit mappings already support prompt +definitions. The absence of a helper is a Go convenience gap, not a missing +configuration capability, and does not block the backend additions. + +**Alternative:** Add a typed prompt source alongside the existing backend and +profile helpers. It would improve discoverability, compiler assistance, and +consistency for applications constructing prompts in Go. Its cost is a larger +public input model covering messages, inline/file content, inputs, output +contracts, session templates, and omission semantics. If selected, define that +scope separately, including sibling inheritance and source context for relative +content files, while retaining ConfigKit's ownership of composition and raw +mapping support for explicit null. Do not implement a second prompt parser or +validation path merely to provide the helper. + ## Implementation Scope And Verification -1. Resolve the two public-contract decisions and define the result and GoDoc. +1. Resolve backend inspection decisions 1–2 and define the result and GoDoc. + Decide separately whether to expand this round for typed prompt construction; + the recommended backend scope does not depend on that expansion. 2. Connect namespace-aware engine selection to the existing captured backend lookup and project the result at the public facade. Introduce only the private collaborators needed for this path; no new backend cache or loader. @@ -155,15 +230,24 @@ consumer-facing solution when that distinction matters. Cover a missing smoke default profile and absent credential environment variable to establish that inspection does not perform execution readiness checks. Use controlled local fixtures; no live provider calls are needed. -4. Update the consumer guide and relevant internal documentation when the API +4. Add `BackendConfig.Extends` and encode it through `BackendSource`. Verify + an inherited backend through real ConfigKit composition, including an + overridden field and a retained parent field. Reuse existing inheritance + coverage for generic missing-parent, cycle, and replacement semantics rather + than retesting ConfigKit's entire feature set. +5. Update the consumer guide and relevant internal documentation when the API lands, with a short `ListBackends` followed by `InspectBackend` example. - Record the additive API and selected error behavior in release notes. + Include typed backend inheritance guidance. Record the additive APIs and + selected error behavior in release notes. Reuse meaningful existing namespace, configuration, and ownership coverage; avoid tests that merely mirror private projection helpers. Run checks appropriate to the implementation under the [testing policy](../policy/testing.md). Completion means consumers can inspect a backend without selecting a profile or -navigating raw configuration, while existing execution, inspection, diagnostic, -and configuration-composition behavior remains intact. No separate provider -capability registry, live capacity monitor, or backend health API is included. +navigating raw configuration, and derive a backend through the typed source +helper without constructing a raw mapping. Existing execution, inspection, +diagnostic, and configuration-composition behavior remains intact. No separate +provider capability registry, live capacity monitor, or backend health API is +included. Typed prompt construction and listing return-type changes are not +completion requirements for the selected backend scope.