Document PromptKit request validation

2026-10-12 22:25:43 +00:00
parent be8bd9c1ea
commit 88d4059e8d
10 changed files with 219 additions and 79 deletions
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -385,9 +385,8 @@ from its own inspection methods. Supported cancellation identity is preserved.
 ## PromptKit requirements

 When `Suite.InspectRequirements` is present,
-`ckprompt.Command(suite)` installs the following optional operation. It accepts
-one required prompt ID and uses PromptKit's native selection and discovery
-rules:
+`ckprompt.Command(suite)` installs `promptkit requirements show`. It accepts one
+required prompt ID and uses PromptKit's native selection and discovery rules:

 ```text
 example promptkit requirements show briefing --campaign spring
@@ -471,6 +470,78 @@ Provider errors, native selection errors, cancellation, and report delivery
 failures use the operational path (status `1`) with supported cause identity.
 Syntax, operand, variable-assignment, and format errors use usage status `2`.

+### Concrete request validation
+
+When `Suite.ValidateRequest` is present, `ckprompt.Command(suite)` also installs
+`promptkit requirements validate`. It can be installed without discovery, and
+discovery can remain installed without validation. The command accepts one
+required prompt ID and passes a concrete request to PromptKit's native
+`Engine.ValidateRequest` preparation path:
+
+```text
+example promptkit requirements validate briefing --campaign spring --input topic=topic.txt
+example promptkit requirements validate briefing --version 2 --profile editorial --session-id session-42 --var mode=full --input notes=notes.txt
+```
+
+The command accepts:
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
+| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
+| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
+| `--version` | string | empty | Pass the prompt version to PromptKit. |
+| `--profile` | string | empty | Pass the profile ID to PromptKit. |
+| `--session-id` | string | empty | Pass session context to PromptKit. |
+| `--var` | repeatable `KEY=VALUE` | none | Supply caller variables for the concrete request. |
+| `--input` | repeatable `NAME=PATH` | none | Bind a file-backed PromptKit artifact. |
+| `--format` | `yaml` | `yaml` | Select the success confirmation format. Other formats are usage errors. |
+
+The built-in flags other than repeatable `--var` and `--input` are singleton
+bindings; when repeated, the last value is used. Suite selectors retain their
+declared binding behavior. Explicit empty `--config` or `--overlay` values keep
+their supplied-presence information.
+
+The version, profile, and session fields use native empty-string semantics:
+an explicit empty string has the same meaning as omission. PromptKit owns their
+interpretation and selection errors. The `promptkit` namespace identifies the
+operation, so there is no built-in `--scope` flag.
+
+Each `--var` and `--input` occurrence must contain `=`. CommandKit splits at
+the first separator and preserves the exact key/name and remaining value/path.
+Empty variable keys and values are passed to PromptKit. Empty input names and
+paths are also passed to native validation. File paths are translated to
+`promptkit.File(PATH)` references without reading, normalizing, expanding, or
+rebasing them during argument binding. Duplicate keys or names use the last
+value, but all occurrences are parsed, so any malformed occurrence is a usage
+error even if a later assignment is valid. Syntax and path values after shell
+processing are otherwise preserved.
+
+On success, the YAML confirmation contains only the requested prompt ID and
+`valid: true`:
+
+```yaml
+prompt_id: briefing
+valid: true
+```
+
+Validation delegates concrete request preparation to PromptKit. Depending on
+the request and configuration, native preparation may resolve prompt/profile
+resources, load artifact and schema resources, render messages and session
+context, and perform applicable configuration and credential checks. Native
+errors are returned as encountered rather than as an exhaustive inventory.
+Validation does not make a model call or retain a prepared execution snapshot.
+A successful report means preparation passed for this invocation; it does not
+certify provider acceptance or guarantee that later execution will succeed.
+See PromptKit's [v0.15.0 `Engine.ValidateRequest` API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/635674c066d0b432187f96e72b9c03d085443ac5/engine.go)
+for the native contract.
+
+Builder, engine-loading, and native validation errors use the operational path
+(status `1`) with supported error identity and acquired diagnostics retained.
+Malformed syntax, missing operands, and unsupported formats use usage status
+`2`. Input-check failures keep their existing shared handling. Successful
+diagnostics and report-delivery failures follow the common delivery contract.
+
 ### PromptKit catalogs

 An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by
--- a/docs/consumers/guide.md
+++ b/docs/consumers/guide.md
@@ -11,7 +11,7 @@ through `commandkit.New` or `App.Register`.
 | --- | --- |
 | `gitea.maximumdirect.net/eric/CommandKit` | The application needs typed command declarations and common CLI behavior. |
 | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
-| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, or requirements discovery. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, requirements discovery, or concrete request validation. |

 The two integrations are independent optional imports. `ckprompt` uses the
 public scope and error contracts from `ckconfig`; importing it does not add the
@@ -119,22 +119,54 @@ source inventory, path explanation, and ConfigKit-backed comparison for the
 capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes)
 owns operator syntax and report details.

-## PromptKit configuration and definitions
+## PromptKit configuration, definitions, and requirements

 `ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit
 engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
 it under `config` with validate/show/sources/explain and native diff operations;
 it does not install PromptKit catalog, definition, or requirements commands.

-`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks,
-named inspection callbacks, and native requirements callback. Set its
-`NewInput`, `NewState`, selectors, or validation when the application needs
-them, then pass `ckprompt.Command(suite)` to core. All five callbacks are
-independently optional; `Command` creates each operation group only when its
-callbacks are present. Applications can use the requirements callback alone,
-clear it while retaining other operations, wrap it, or replace it with their
-own provider. For catalogs without named or requirements inspection, narrow the
-suite before command capture:
+`ckprompt.FromEngine(loadEngine)` supplies five callbacks: prompt and profile
+catalogs, named prompt and profile inspection, and native requirements
+discovery. Concrete request validation is a sixth, independently optional
+capability and is added explicitly with `ckprompt.WithRequestValidation`.
+`ckprompt.Command(suite)` creates only operations whose callbacks are present;
+discovery and validation share `promptkit requirements` but can be installed
+independently. A composed suite can keep the standard five and add validation:
+
+```go
+suite := ckprompt.FromEngine(loadEngine)
+suite = ckprompt.WithRequestValidation(suite, loadEngine, buildRequest)
+suite.NewInput = newInput
+suite.NewState = newState
+suite.Selectors = selectors
+definitionCommand := ckprompt.Command(suite)
+```
+
+A validation-only suite can start empty. With application types named `Input`
+and `State`, a nil builder forwards the request fields populated by standard
+flags directly to PromptKit:
+
+```go
+suite := ckprompt.WithRequestValidation(
+	ckprompt.Suite[Input, State]{}, loadEngine, nil,
+)
+validationCommand := ckprompt.Command(suite)
+```
+
+If the loader is nil, the returned suite retains a wiring issue for installation
+to report, even if capabilities are narrowed later. A builder runs before the
+engine loader and receives the seed request, selection, typed input, shared
+state, and invocation context. It returns the
+concrete request; the adapter does not merge seed fields back afterward. The
+loader receives the original selection. Builders should start from the seed,
+preserve operator values and bindings, and apply defaults only when a map key is
+absent, so explicitly supplied empty values stay meaningful. Applications that
+validate and then execute a request are encouraged to share their request
+construction logic between those paths.
+
+All six suite capabilities are independently optional. For catalogs without
+named or requirements inspection, narrow the suite before command capture:

 ```go
 definitions := ckprompt.FromEngine(loadEngine)
@@ -144,20 +176,28 @@ definitions.InspectRequirements = nil
 definitionCommand := ckprompt.Command(definitions)
 ```

-Each selected inspection, requirements, or catalog operation prepares one input,
-applies its captured selectors, checks that input, and initializes one state
-value when those steps are reached. See
+Each selected inspection, requirements, validation, or catalog operation
+prepares one input, applies its captured selectors, checks that input, and
+initializes one state value when those steps are reached. The bundled validation
+adapter delegates concrete request preparation to PromptKit and carries its
+native errors plus engine-loading diagnostics through the acquisition. It does
+not call the model or retain a prepared execution snapshot. See
 [ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
 timing, omitted-factory zero values, and caller-owned objects and effects.
 The loader receives invocation context, explicitly supplied selection, input,
-and state. The adapter uses PromptKit's public listing and inspection methods,
-including `Engine.InspectRequirements`, and preserves acquisition diagnostics
-and supported error identity.
+and state. `FromEngine` uses PromptKit's public listing and inspection methods,
+including `Engine.InspectRequirements`; validation must be opted into separately
+and uses `Engine.ValidateRequest`.

-CommandKit-owned listing and inspection code does not execute prompts, contact model
-providers, or resolve credential values; application loaders and direct callbacks
-retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
-owns the command and report contracts.
+Catalog, named definition inspection, and requirements discovery do not render
+messages or load request artifacts. Concrete request validation follows native
+PromptKit preparation, which can resolve prompt/profile resources, load
+artifacts and schemas, render messages, and perform applicable configuration
+and credential checks. It does not make a model call or certify that a later
+execution will succeed. Application loaders and direct callbacks retain their
+own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
+and [requirements contract](../cli.md#promptkit-requirements) own operator
+syntax and reports.

 The [composed example](../../integrations/ckprompt/examples/composed/README.md)
 combines app and PromptKit config scopes, comparison and catalogs, named and
--- a/docs/development.md
+++ b/docs/development.md
@@ -4,8 +4,9 @@ CommandKit is distributed as a core Go module and two optional integration
 modules. Core owns captured declarations, typed input preparation, installation,
 dispatch, outcomes, help, and version. `integrations/ckconfig` owns ConfigKit
 scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine,
-definition inspection, and requirements discovery adapters. The maintained
-[consumer guide](consumers/guide.md) links to the three maintained consumers.
+definition inspection, requirements discovery, and concrete request validation.
+The maintained [consumer guide](consumers/guide.md) links to the three maintained
+consumers.
 The [README](../README.md) provides project orientation; the
 [documentation policy](policy/documentation.md#canonical-ownership) assigns
 canonical documentation owners.
@@ -144,6 +145,8 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second
 (cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml)
 (cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring)
 (cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
+(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt)
+(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml)
 (cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
 ```

--- a/docs/internal/overview.md
+++ b/docs/internal/overview.md
@@ -48,11 +48,13 @@ acquisitions or comparison callback.

 `integrations/ckprompt` owns PromptKit engine loading, configuration-scope
 adaptation and native comparison, plus optional prompt/profile catalogs, named
-inspection, and native requirements discovery. It uses public core and ckconfig
-contracts plus PromptKit's public APIs. It does not add a configuration family
-when its declaration is installed; callers compose `ckprompt.ConfigScope` with
-`ckconfig.Command` separately when they want configuration operations alongside
-PromptKit commands.
+inspection, native requirements discovery, and concrete request validation.
+Validation delegates request preparation to PromptKit and is independently
+opted into a suite. It uses public core and ckconfig contracts plus PromptKit's
+public APIs. It does not add a configuration family when its declaration is
+installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command`
+separately when they want configuration operations alongside PromptKit
+commands.

 The three maintained consumers live at `examples/core`,
 `integrations/ckconfig/examples/simple`, and
@@ -67,7 +69,9 @@ graph isolation.

 ConfigKit owns configuration decoding, validation, source history, and path
 explanations. PromptKit owns its captured engine configuration, prompt
-definitions, profile inheritance, and named inspection semantics. CommandKit
-adapts those public contracts without maintaining parallel schemas or invoking
-prompt execution. Application loaders and domain behavior remain application
-owned.
+definitions, profile inheritance, named inspection, requirements discovery,
+and concrete request validation semantics. CommandKit adapts those public
+contracts without maintaining parallel schemas or invoking model generation.
+Native request validation may load resources and artifacts, render messages,
+and perform applicable configuration or credential checks through PromptKit.
+Application loaders and domain behavior remain application owned.
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,6 +1,6 @@
 # PromptKit request validation implementation plan

-Status: Stages 1–7 complete; implementation is ongoing.
+Status: Stages 1–8 complete; implementation is ongoing.

 ## Authority, scope, and baseline

@@ -462,6 +462,15 @@ mandates.
 capability under its assigned owners, with no stale five-callback or
 metadata-only claims covering request validation.

+**Completed:** 2026-10-12. Updated ckprompt GoDoc, the CLI reference, consumer
+guidance, README module summary, development orientation and examples, and the
+internal component inventory. The docs distinguish `FromEngine`'s five
+callbacks from explicit validation composition, describe native preparation and
+the minimal success YAML, and scope discovery-only statements to discovery.
+`GOTOOLCHAIN=local go test -count=1 ./...` passed from `integrations/ckprompt`;
+the Stage 7 consumer tests and commands remain unchanged and passed. Changed
+Markdown links and anchors and Markdown whitespace checks passed.
+
 ## Stage 9: Validate the complete end state and finish

 1. Format changed Go files and inspect the final diff for scope, generated junk,