Defer operator diagnostics to CommandKit

This commit is contained in:
2026-11-18 18:38:34 +00:00
parent d1d2394729
commit 0ef079610e

View File

@@ -12,9 +12,8 @@ reuse.
This is a hard cutover for both the Notarius application configuration and This is a hard cutover for both the Notarius application configuration and
PromptKit resource definitions. Provide migration guidance and maintained PromptKit resource definitions. Provide migration guidance and maintained
examples; support only the new formats in the resulting application. This examples; support only the new formats in the resulting application. This
draft describes the target, assuming the recommendations under roadmap defines the PromptKit cutover. Operator interface standardization
[Open Decisions](#open-decisions). It does not select a release date or belongs to the subsequent CommandKit adoption.
implementation sequence.
## Reviewed Baseline ## Reviewed Baseline
@@ -126,12 +125,14 @@ self-contained-schema rule; this is not a redesign of durable D&D artifacts.
Use PromptKit's captured configuration reports for effective configuration Use PromptKit's captured configuration reports for effective configuration
and provenance. Use its resource inventory and inspection APIs for exact and provenance. Use its resource inventory and inspection APIs for exact
identities, presence-aware resource fields, and captured prompt hashes, rather identities, presence-aware resource fields, and captured prompt hashes, rather
than deriving an inventory from rendered configuration YAML. Change the than deriving an inventory from rendered configuration YAML. Make only the
`config profile` report to show the resolved profile and its selected backend, changes needed to keep the existing `config effective`, `config explain`, and
when present, as separate resources. Use upstream field semantics and retain `config profile` commands usable after the cutover. Report PromptKit's
the existing operator disclosure boundary, including redaction of resolved profile resource rather than rebuilding the former
credential-shaped provider parameters. Do not recreate backend default `effective_model_params` view or designing a combined profile/backend report.
resolution to produce the former `effective_model_params` view. Retain the existing disclosure boundary, including redaction of
credential-shaped provider parameters. Defer new operator commands and report
surfaces to the CommandKit work.
Retain a private, versioned Notarius checkpoint identity based on the engine's Retain a private, versioned Notarius checkpoint identity based on the engine's
captured state. Use native resource enumeration and prompt hashes, keeping captured state. Use native resource enumeration and prompt hashes, keeping
@@ -220,27 +221,23 @@ catches invalid effective definitions and unknown selected IDs without
requiring inputs or credentials, and does not reject a profile merely for requiring inputs or credentials, and does not reject a profile merely for
being partial. Exercise preparation, generation, structural repair, and being partial. Exercise preparation, generation, structural repair, and
semantic retries through the maintained fake-provider integration. Check semantic retries through the maintained fake-provider integration. Check
that real message or target changes affect that real message or target changes affect checkpoint reuse, and that session
checkpoint reuse, and that session routing, cache controls, diagnostics, and routing, cache controls, diagnostics, and durable outputs keep their existing
durable outputs keep their existing meaning. Live provider checks are useful meaning. Live provider checks are useful for deployment confidence, not a
for deployment confidence, not a requirement of the offline suite. requirement of the offline suite.
## Follow-Up: CommandKit
The planned follow-up adopts `go.maximumdirect.net/commandkit` with its
`ckconfig` and `ckprompt` integrations and replaces Notarius-owned
configuration and PromptKit commands where applicable. That work owns the
standardized CLI and decisions about exposing resource lists, configuration
diffs, request previews, and explicit provider smoke diagnostics. Leave
those commands and the CommandKit dependencies to the follow-up. This
deferral does not change offline pipeline preflight, internal use of native
inspection and observation APIs, or existing run diagnostics.
[release]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/releases/v0.23.2.md [release]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/releases/v0.23.2.md
[migration]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/consumers/configuration-migration.md [migration]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/consumers/configuration-migration.md
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/formats.md [formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/formats.md
[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/consumers/pkg-promptkit.md [consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.2/docs/consumers/pkg-promptkit.md
## Open Decisions
### Operator Diagnostics In This Upgrade
**Recommendation:** Migrate existing inspection commands and use native
inventory and observation APIs where they replace local work. Evaluate new
commands for provider smoke checks or effective-config diffs separately,
after identifying the operator workflows and output contracts they need.
**Alternative:** Include an explicitly invoked smoke command in the cutover.
This would help operators verify credentials and structured inference after
migrating a deployment, and it can delegate to `Engine.SmokeTest`. It adds a
network-capable CLI surface, with cost and output handling to define. Keep it
separate from ordinary offline validation in either case.