diff --git a/docs/roadmap/listing.md b/docs/roadmap/listing.md new file mode 100644 index 0000000..e19cc3f --- /dev/null +++ b/docs/roadmap/listing.md @@ -0,0 +1,118 @@ +# Profile And Prompt Listing + +Status: Accepted; implementation pending. + +## Purpose + +Let consumers discover the profiles and prompt versions available in an engine +without knowing their identifiers in advance or interpreting configuration +history. This supports application selectors, CLI discovery, and configuration +editors while keeping PromptKit's public API small. + +Listing supplies identities; the existing inspection methods supply details. +A separate implementation plan will define staged work. This roadmap describes +the intended feature, not currently available methods. + +## Current Baseline + +Review baseline: `03c44923c8a14565dca30f65d93bde79e0962ea2`. + +- `Engine.InspectProfile` and `Engine.InspectPrompt` inspect a known identity. + Neither enumerates available entries. +- `Engine.InspectConfiguration` exposes ConfigKit's captured inspection view. + Consumers can enumerate historical paths and filter for surviving effective + entries, but that is an indirect configuration-inspection workflow. +- The configuration adapter already captures profiles by literal ID and prompts + by literal ID/version pair. Those execution-facing indexes are sufficient + for listing; no new configuration loading or registry is needed. + +The [consumer guide](../consumers/pkg-promptkit.md) describes existing inspection +workflows. The [format reference](../formats.md) owns keyed definitions and +literal identifier semantics. Preserve the final-configuration boundary in +[ADR 0001](../adr/0001-configuration-boundary.md) and the facade ownership in +the [architecture policy](../policy/architecture.md). + +## Target End State + +### Small Public Listing API + +Add two engine methods, following the context and error conventions of the +existing prompt/profile inspection methods: + +- `ListProfiles(ctx)` returns profile IDs. +- `ListPrompts(ctx)` returns small identity values containing `ID` and `Version`. + +Expose only the identity value needed for prompt listing. GoDoc will own the +exact signatures and behavior when implemented. Callers can pass the returned +identities to `InspectProfile`, `InspectPrompt`, or their execution requests. +Bulk inspection results, prompt text, execution targets, source provenance, +and credential information do not belong in these results. + +### Effective Captured Inventory + +List the identities present in the engine's final captured configuration, +including maintained catalog profiles and consumer-defined profiles and +prompts after ConfigKit layering and inheritance. A profile's configured alias +or inherited identity remains its own list entry, not its base profile's name. +Historical or superseded contributions do not create additional entries. + +Each effective profile ID appears once. Each effective prompt ID/version pair +appears once, including every configured version of a multi-version prompt. +Listing does not choose a default or latest version; the existing omitted-version +selection behavior remains unchanged. + +Preserve exact identifier spelling. Return profiles in ascending lexical ID +order and prompts in ascending lexical ID order, then lexical version order. +Version ordering is for deterministic presentation, not semantic-version +comparison or a recommendation about which version to execute. + +### Lightweight Snapshot Read + +Listing reads the engine's captured identity indexes. It does not reload sources +or files, analyze configuration provenance, resolve credentials, read artifacts +or schemas, render, acquire backend capacity, or contact providers. + +A profile need not be execution-ready to be listed. Presence in the inventory +does not promise valid credentials, provider availability, or successful +execution. Catalog entries remain subject to the existing +[catalog compatibility policy](../policy/release.md#catalog-profile-compatibility). + +Returned slices are caller-owned; modifying one result cannot change the +engine or later results. Listing supports concurrent engine use without adding +mutable registry state. An empty inventory is a successful result. A nil engine +uses `ErrInvalidConfig`, and cancellation preserves the context error under the +existing inspection conventions. + +## Work Needed From The Baseline + +- Add identity-only enumeration to the captured configuration adapter and route + it through the internal engine to the public facade. Keep internal + representations behind the existing package boundary. +- Add the two public methods and the small prompt identity value, with GoDoc. + Avoid obtaining each item's full inspection or copying profile parameters + and prompt content merely to list its identity. +- Keep traversal and allocation proportional to the inventory returned. + Prefer straightforward reuse of captured indexes; ordering can be prepared + during construction rather than repeatedly sorting unchanged identities. + Exact storage layouts and allocation counts are implementation choices. +- Add focused tests for effective inventory membership, multiple prompt + versions, literal identities and ordering, caller ownership, empty results, + and the selected error/cancellation behavior. Include a representative public + workflow that lists entries and inspects a returned identity. Reuse existing + construction coverage rather than retesting ConfigKit's resolution machinery. +- Add concise listing guidance to the consumer guide and update the relevant + internal documentation when implemented. Preserve existing inspection and + execution contracts. + +Backend enumeration, filtering, pagination, runtime registration, and live +catalog/provider discovery are outside this feature's scope. No new caller +limits, readiness checks, release gates, or performance guarantees are needed. + +## Completion + +Consumers can enumerate effective profiles and exact prompt versions through +the public facade, obtain independent deterministic results, and use those +identities with existing operations. Verification follows the +[testing policy](../policy/testing.md), including focused ownership and +concurrent-use checks proportionate to the implementation. Current documentation +describes the implemented API without duplicating ConfigKit history semantics.