Plan full PromptKit v0.23.0 adoption
This commit is contained in:
136
docs/roadmap/promptkit.md
Normal file
136
docs/roadmap/promptkit.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# PromptKit v0.23.0 Adoption Roadmap
|
||||
|
||||
**Status:** Accepted target; implementation pending. This pass changes planning
|
||||
documents only. The [implementation plan](promptkit-implementation.md) owns the
|
||||
ordered tasks and verification.
|
||||
|
||||
## Objective and Baseline
|
||||
|
||||
Upgrade Audita directly from PromptKit v0.21.0 to v0.23.0 and fully adopt its
|
||||
conversation, coordinator, and execution-group APIs. Removing redundant local
|
||||
machinery is an explicit completion requirement. A dependency-only upgrade or
|
||||
continuation adoption with the old repair loop retained is an intermediate state.
|
||||
|
||||
The current [dependency manifest](../../go.mod) pins v0.21.0. Audita captures its
|
||||
own exchange and replay values, reconstructs and compares conversation prefixes,
|
||||
appends repair history, manages the revision loop, and aggregates terminal
|
||||
observations locally. Each role client wraps explicit preparation and execution
|
||||
in a local deadline. See the [LLM runtime](../internal/llm-runtime.md),
|
||||
[pipeline](../internal/pipeline.md), and
|
||||
[diagnostic implementation](../internal/diagnostics-reporting.md).
|
||||
|
||||
[PromptKit v0.23.0](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.0/docs/releases/v0.23.0.md)
|
||||
includes the v0.22.0 conversation and accounting capabilities plus the execution
|
||||
controls needed for full coordinator adoption. The former upstream timeout and
|
||||
prepared-request gaps are closed; no intermediate v0.22.0 rollout or further
|
||||
upstream feature gate is required. The Go minimum and dependency versions are
|
||||
unchanged by these upstream releases.
|
||||
|
||||
The release review verified Audita's existing suite against the tagged v0.23.0
|
||||
source through a temporary module override and selected upstream packages with
|
||||
race detection. That is compatibility evidence, not verification of the migration
|
||||
described here. Implementation must use the released dependency, without a local
|
||||
replacement or committed workspace file.
|
||||
|
||||
## Target Ownership
|
||||
|
||||
| Responsibility | Target owner |
|
||||
| --- | --- |
|
||||
| Immutable captured history, continuation assembly, and parent run identity | PromptKit `Exchange`, `CaptureExchange`, and `ContinueFrom` |
|
||||
| Sequential turns, additional-turn budget, callback delivery, and coordination termination | PromptKit `Engine.Coordinate` |
|
||||
| Whole-operation deadlines and timeout attribution | PromptKit `OperationTimeout` and `ErrOperationTimeout` |
|
||||
| Exact prepared-request notification before generation | PromptKit `OnPrepared` |
|
||||
| Selected run membership, deduplication, and terminal count/usage aggregation | PromptKit `ExecutionGroup` and `ComposeObservers` |
|
||||
| Candidate identity, actionable rejection, feedback, revision decoding, withdrawal, and full revalidation | Audita |
|
||||
| Branch scheduling, accepted sibling proposals, application order, and transcript mutation | Audita |
|
||||
| Domain operation labels, failure disposition, reports, redaction, and debug artifact storage | Audita |
|
||||
|
||||
Use the supported public API through Audita's framework adapter boundaries.
|
||||
Keep module and validator contracts domain-oriented. Any bridge needed by the
|
||||
runner must delegate to the real coordinator and retain opaque conversation
|
||||
state, rather than implementing another conversation engine or general workflow
|
||||
framework.
|
||||
|
||||
## Selected Behavior
|
||||
|
||||
### Execution and diagnostics
|
||||
|
||||
Use ordinary `Engine.Run` with per-request `OperationTimeout` and `OnPrepared`
|
||||
where explicit preparation currently serves only to inspect and execute the same
|
||||
request. Map the resolved Audita operation timeout onto each proposal, validation,
|
||||
and repair operation. Keep provider, transport-retry, structural-repair, and
|
||||
correction-revision budgets distinct.
|
||||
|
||||
Use `ErrOperationTimeout` to identify the selected local budget, while retaining
|
||||
Audita's parent-cancellation and recoverable-provider-failure handling. Do not
|
||||
classify every wrapped preparation error as fatal before considering its timeout
|
||||
identity. Ordinary configuration failures remain fatal. If split preparation is
|
||||
still needed for a concrete consumer, one caller context must cover both calls
|
||||
when a total preparation-plus-execution deadline is required; the upstream
|
||||
prepared-handle duration starts only at execution.
|
||||
|
||||
`OnPrepared` receives the actual detached snapshot. Retain the metadata needed
|
||||
for attribution and credential-source redaction, and capture content for optional
|
||||
debug evidence. Keep the callback short; application validation belongs in the
|
||||
next-turn callback after admission is released. Notification may be absent on
|
||||
preparation/admission failure or cancellation before delivery. Reports must not
|
||||
invent missing snapshots. Optional debug write failures remain nonfatal.
|
||||
|
||||
### Conversations and correction repair
|
||||
|
||||
Capture the proposal exchange when repair needs it. Every rejected candidate's
|
||||
branch starts from that same immutable exchange; subsequent turns remain private
|
||||
to that branch. Follow-ups select the module's repair prompt, role profile,
|
||||
variables, and repair output contract through ordinary PromptKit requests.
|
||||
Retain native operator prompt overrides and the existing domain prompt content.
|
||||
|
||||
Use one coordinator per actionable correction. Its initial callback uses existing
|
||||
rejection findings. Each newly delivered response must pass structural validation
|
||||
before decoding; captured content alone does not imply validity. A decoded
|
||||
revision is fully revalidated before acceptance. Withdrawal, unavailable results,
|
||||
and accepted revisions remain Audita outcomes; a normal coordinator stop is not
|
||||
itself an approval.
|
||||
|
||||
The last permitted response follows the same assessment path. Further requested
|
||||
work beyond the budget maps to exhaustion. Skip coordination when Audita's
|
||||
correction-repair setting disables it: upstream's zero budget still invokes an
|
||||
initial callback. Cancellation's `Undelivered` response is diagnostic evidence,
|
||||
not an approved correction, and must not trigger model work after cancellation.
|
||||
Recoverable branch failures preserve independent approvals; fatal failures and
|
||||
caller cancellation retain Audita's cancel-and-join behavior.
|
||||
|
||||
### Execution groups
|
||||
|
||||
Use native groups as the source of aggregate provider-attempt, retry, repair,
|
||||
and available token totals. Explicitly select membership for proposal calls,
|
||||
coordinated continuations, and validator calls. Coordinator observers cover its
|
||||
own turns; nested validators require their own observer selection.
|
||||
|
||||
Maintain an invocation group for combined execution totals. Add narrower groups
|
||||
only for accounting views Audita consumes. A shared initial proposal run belongs
|
||||
once to the invocation total; replaying its history does not enroll it again.
|
||||
Each new call's reported history tokens still count. Overlapping group totals
|
||||
must not be summed as disjoint work.
|
||||
|
||||
Preserve upstream usage presence/completeness and terminal coverage separately.
|
||||
Keep domain logical-call records and deterministic presentation where needed;
|
||||
their count need not equal observed run membership. Group summaries do not replace
|
||||
Audita's errors/recoveries, validation decisions, or per-operation failure facts.
|
||||
|
||||
## Delivery and Completion
|
||||
|
||||
Implement in ordered, reviewable stages: dependency and execution adapter;
|
||||
captured conversations and coordinator; execution groups; cleanup, integration
|
||||
verification, and canonical documentation. All stages belong to this adoption.
|
||||
|
||||
Completion requires removal of local exchange/replay history, prefix checks,
|
||||
repair turn-budget loops, and duplicate terminal aggregation where replaced by
|
||||
PromptKit. Retain local behavior only where it has a concrete Audita domain or
|
||||
presentation responsibility. Preserve transcript correctness, repair prompts,
|
||||
validation semantics, deterministic reports, standard inspection commands, and
|
||||
operator configuration unless a deliberate change is documented and tested.
|
||||
|
||||
No product-level open decisions remain. Exact internal bridge signatures are
|
||||
implementation choices governed by this ownership split. Future validator
|
||||
decision recovery and new scheduling behavior remain in the
|
||||
[deferred work catalog](future.md).
|
||||
Reference in New Issue
Block a user