| Pipeline execution | Connect generation to configured validation and terminal policy; manage ordered dependencies, typed handoffs, bounded workers, and stable result ordering. |
| PromptKit | Prepare and execute requests; maintain captured exchanges and conversations; enforce native retry, repair, turn, and admission budgets; report execution facts. |
| Application state and records | Store artifacts, apply checkpoint reuse policy, preserve acceptance provenance, and attach pipeline context to execution facts. |
| ConfigKit and CommandKit | ConfigKit owns configuration mechanics; CommandKit and ckconfig/ckprompt own standardized commands and presentation. Notarius supplies loaders, request builders, report content, and outcome mapping. |
Use native PromptKit requests, results, exchanges, errors, and observers in
model-executing application code. Remove the private provider-neutral completion
API. Pure domain models, codecs, source-reference resolution, and deterministic
transformations need no PromptKit dependency. Application interfaces continue to
express artifact production, typed validation, output encoding, and state access.
A small shared application function connects module request construction and
response interpretation to pipeline validation and terminal policy. It calls
native `Run` and `Coordinate` and returns a typed application outcome. It owns no
replacement completion API, conversation protocol, or general retry engine.
Exact signatures and helper placement remain open. The current
`internal/framework/llm` package may shrink to engine assembly and focused helpers
diagnostics, formatting, visibility, and progress presentation. Notarius supplies
loaders, request builders, report content, pipeline meaning, and outcome mapping.
Keep machine-output receipts deliberate and presentation delivery failures
distinguishable from operation outcomes. Until that follow-up lands, make only
the changes needed to keep existing inspection commands usable through native
APIs; do not build temporary custom commands or a new reporting framework.
## Unresolved Choices
The directions above are selected. The following details are not. Resolve and
record each choice before implementing the work that depends on it; independent
work need not wait for every choice. Candidates here are not implicit defaults.
| ID | Choice still needed | Resolve for |
| --- | --- | --- |
| U1 | Final compatible tagged PromptKit/ConfigKit/dependency set; any specific unmet need requiring an upstream request. v0.23.2 is the initial target, not a restriction on useful upstream work. | Phase 1; revisit if the target or upstream needs change. |
| U2 | Remaining custom read-only filesystem responsibilities; schema root/path and assembly, prompt-declared versus per-request contracts, removable wrappers, and metadata useful for manifests/artifact compatibility. | Phase 2 source and schema assembly. |
| U3 | Concrete module/pipeline signatures and placement of engine assembly, request construction, interpretation, assessment, and focused helpers. | Phase 3 representative workflow, refined during Phase 4. |
| U4 | Initial and repair prompt definitions, response contracts, and profile selection within complete replacement and fixed operation inputs. | Phases 3–4 for each producer role. |
| U5 | Mapping producer/validator retry settings to native controls; names, defaults, compatibility, non-LLM failure handling, and any explicitly justified recovery beyond native exhaustion. | Phases 3–4 and configuration migration. |
| U6 | Detailed terminal/fallback dispositions, especially whether any earlier safe candidate survives a later failed turn. | Phases 3–4; no implicit best-so-far acceptance. |
| U7 | Independent worker defaults, native backend/queue defaults where supplied, retired `total_llm` migration, and admission-failure handling by role. | Phase 4 shared-engine cutover. |
| U9 | Minimal durable fields and their compatibility treatment; observer/group enrollment, application scope, and debug write/disclosure handling. | Design with Phase 3, complete in Phase 5. |
| U10 | CommandKit/ckconfig/ckprompt versions, command exposure and compatibility, and application wiring for the follow-up. | Phase 7; do not recreate its machinery earlier. |
## Implementation Sequence
Each phase is pending. Phases describe reviewable outcomes and dependencies,
not separate releases. The supported core result is the hard cutover; any
intermediate migration scaffolding must retire before that result is complete.
Update affected canonical documentation as behavior lands. Record significant
boundary decisions in successor ADRs without rewriting accepted decision text.
### Phase 1: Establish The Migration Baseline
- Confirm U1 against the tagged APIs and dependency graph. Carry forward the
Audita evidence without treating its wrappers as requirements.
- Map the changed architecture and ADRs, and identify concrete decisions needed
for the next phase. Keep unresolved entries visible until actually settled.
- Identify the production callers and old contracts covered by the removal
inventory below; use that inventory to track complete cutover coverage.
**Completion evidence:** selected dependency baseline and decision/implementation
scope are recorded; unresolved choices have a clear dependent phase. No new
upstream feature is assumed necessary without an identified requirement.
### Phase 2: Assemble Native Sources And A Shared Engine
- Resolve U2, update dependencies, and implement version 6 and companion-source
composition. Convert embedded resources and establish the schema loading path.
- Construct the shared native engine and use the same assembly for execution,
preflight, and inspection. Remove duplicate prompt assembly as callers migrate.
- Add maintained embedded-only and operator-override examples with the new format.
| `single_response_v1`, raw `ModelCandidate`/`SemanticCorrection`, manual replay, correction capability checks | Typed candidates, actionable findings, native exchanges, and assessment. |
| LLM retry portions of `runProducerAttempts` and `executeValidationChain`, module rerun directives | Ordered validators, acceptance/rejection/fallback policy, and useful provenance. |
| `Scheduler`, `scheduledClient`, `concurrency.total_llm`, worker coupling | Bounded pipeline work and native per-backend admission. |
| Broad configuration/prompt/catalog/implementation checkpoint fingerprints and invocation-wide lookup barriers | Logical work, consumed-input identity, load checks, and explicit recomputation. |
| Inspection wrappers, copied effective parameters, `LLMExecutionSummary` and usage conversions/accumulators, debug completion wrapper, redundant call IDs, adapter profile recorder | Native facts with application scope and selected durable projections. |
| Custom standard inspection commands/presentation in the CommandKit phase | Application loaders, request builders, report content, and outcome mapping. |
## Acceptance And Verification
Use focused behavioral tests with real deterministic collaborators, a native
engine, and injected clients or a fake HTTP provider. Test domain interpretation
and assessment directly; pipeline tests can use fake stages. Replace tests that
preserve removed mechanics rather than reproducing a private LLM interface for
testing. Default tests remain offline and independent of real credentials.
| Area | Required evidence |
| --- | --- |
| Configuration and assets | Version 6/new resources work; legacy formats are rejected intentionally; main-relative companions and native imports work independently of working directory; peer conflicts fail; same-ID replacement affects only the intended default; ordering/cache controls and selected schema contracts survive assembly. |
| Preflight and inspection | Runtime, inspection, and preflight share effective definitions; unknown statically selected IDs and invalid definitions fail offline; partial profiles alone pass; completed target checks occur on concrete requests; actual-run overrides appear in provenance. |
| Native artifact workflow | Representative extraction and normalization produce typed candidates, invoke ordered validators, and preserve source/reference identity, safe plan application, artifact-schema checks, and stable output ordering. |
| Continuation and failures | Multiple turns accumulate history with fixed input/handle meanings; every revised candidate and final allowed response is assessed; native transport/structural exhaustion is not silently retried outside PromptKit; validator failure differs from rejection; selected safe fallback and cancellation policy hold. |
| Admission and workers | All roles share the selected backend pool; independent backends remain independent; pipeline work stays bounded; queue exhaustion, nested validators, and cancellation settle without leaked capacity or a retained global ceiling. |
| Checkpoints | Successful predecessors survive downstream fixes and prompt/model/validation-setting changes; changed prompt IDs or consumed source/reference/upstream data miss; recompute forces selected work/dependents; corrupt/incompatible or unaccepted/incomplete artifacts and ineligible derivatives are unusable; compatible schema changes do not require exact hash equality. |
| Reuse provenance | Original acceptance and execution provenance survive resume without new semantic validation claims or historical token usage counted as current; recording remains separate from reuse; canonical chunk-plan caching retains its distinct policy. |
| Execution records | Initial/continuation/nested validator accounting preserves terminal coverage and unknown-versus-zero usage without double counting; failures without a result remain observable; native success is distinct from acceptance; debug is opt-in and ordinary records exclude sensitive response/history content. |
| Published behavior | Maintained minimal and complete D&D workflows, session routing, artifact output, manifest/receipt compatibility, and selected migration diagnostics work through the assembled CLI. CommandKit-phase tests cover its own command/presentation changes. |
Run focused checks while implementing and the repository-wide commands for the
completed application cutover, following the [testing policy](../policy/testing.md):
```sh
go test ./...
go vet ./...
go build ./cmd/notarius
```
Check maintained examples, dependency removal, links, and attribution alongside
those commands. Live provider checks and human model-quality evaluation can
inform deployment and prompt refinement; they are not requirements of the
deterministic offline suite. Planning/documentation completion does not claim
that these implementation acceptance checks have already passed.
## Migration Guidance And Documentation
Maintain examples that distinguish embedded-only operation from companion
configuration, using separate directories when needed. Explain moving/importing
old sources, qualified IDs, complete replacement versus inheritance, native local
backends, removed catalogs and prompt versions, and the separate application and