137 lines
7.8 KiB
Markdown
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).
|