Files
audita/docs/roadmap/promptkit.md

137 lines
7.8 KiB
Markdown

# 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).