From 3f51764f1ec9ac67e877a463cfe53e5836380a55 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 21:51:23 +0000 Subject: [PATCH] Update native migration roadmap for reviewed upstream releases --- docs/roadmap/promptkit.md | 325 +++++++++++++++++++++++--------------- 1 file changed, 199 insertions(+), 126 deletions(-) diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index d759ac07..20f489d7 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -10,7 +10,7 @@ behavior is not a requirement to preserve it. This is the single migration plan for PromptKit, ConfigKit, CommandKit, accepted-artifact caching, and artifact-first output. It owns the selected target, -remaining choices, implementation sequence, removal inventory, acceptance +decision status, implementation sequence, removal inventory, acceptance criteria, and supporting evidence. The earlier discussion documents are retired; Git history preserves the discussion. All implementation phases are pending. Recording these decisions has not changed application behavior. Unrelated future @@ -45,30 +45,31 @@ The selected reviewed baseline is: | Module | Version | | --- | --- | | `go.maximumdirect.net/commandkit` | `v0.7.0` | -| `go.maximumdirect.net/ckconfig` | `v0.9.0` | -| `go.maximumdirect.net/ckprompt` | `v0.10.0` | -| `go.maximumdirect.net/configkit` | `v1.2.1` | -| `go.maximumdirect.net/promptkit` | `v0.23.3`, subject to U1's hash-capable release review | +| `go.maximumdirect.net/ckconfig` | `v0.10.0` | +| `go.maximumdirect.net/ckprompt` | `v0.11.0` | +| `go.maximumdirect.net/configkit` | `v1.4.0` | +| `go.maximumdirect.net/promptkit` | `v0.24.0` | -Keep Go's consumer minimum at 1.27, adopt stable go-yaml v4, and resolve compatible -validation dependencies. The selected CommandKit integration releases document -compatibility with PromptKit v0.23.2. Select v0.23.3 explicitly for its timeout -attribution and cancellation/error identity fixes; that patch requires no -configuration or request API migration from v0.23.2 and retains its dependencies. -The original review used local release tags and tagged dependency manifests; -remote release lookup was unavailable, so these are selected versions, not a -claim that they are the latest releases. See the +Keep Go's consumer minimum at 1.27.0. The reviewed set resolves stable +`go.yaml.in/yaml/v4` v4.0.0 and `github.com/santhosh-tekuri/jsonschema/v6` v6.0.3. +Published tags and dependency manifests were verified, and the modules resolved +together without local replacements in an isolated consumer module. Maintained +composed-CLI and offline-preparation examples and focused message-hash, +configuration-handoff, and schema tests passed without live provider calls. +These checks verify the upstream combination, not the unfinished Notarius +migration. See the [integration version guidance](../../../commandkit/docs/consumers/guide.md#module-selection) and tagged [release notes][release], [migration guide][migration], [format reference][formats], and [Go consumer guide][consumer]. -The cache requires native `MessageContentHash`; v0.23.3's `RenderedPromptHash` -is not a substitute. The sibling PromptKit repository has retired the original -feature request, and its [v0.24.0 release notes](../../../promptkit/docs/releases/v0.24.0.md) -document the addition and a ConfigKit v1.3.0 dependency. U1 remains open to review -the supplying API/release and verify a compatible assembled dependency set before -changing the selected baseline. Independent work can proceed; completed cache -integration must use the upstream capability. Do not add a local hash-policy fork. +U1 is resolved: PromptKit v0.24.0 supplies the prepared `MessageContentHash` +required by the cache, and ConfigKit v1.4.0 supplies typed result handoff and +focused inspection. Adopt these with the selected CommandKit integrations as +one baseline. The migration includes one application-owned load, +`promptkit`-rooted resources, native schema configuration, and the request API +changes described below; it is not just a dependency-version update. PromptKit's +v0.23.3 timeout and cancellation fixes remain included. Do not add a local +hash-policy fork or substitute `RenderedPromptHash` for message-content identity. Neither a cross-backend global limit nor a comprehensive execution fingerprint is required. Remove obsolete imports and catalog dependencies when unused; avoid permanent `replace` directives and update [attribution](../oss/attribution.md) @@ -86,7 +87,7 @@ Notarius's artifact and recovery policies. | Part | Responsibility | | --- | --- | -| Application composition | Load configuration and native sources; construct one shared PromptKit engine for producers, validators, and continuation runs. | +| Application composition | Load application and PromptKit settings together through ConfigKit; hand the completed result to one shared PromptKit engine for producers, validators, and continuation runs. | | Artifact-family modules | Prepare domain inputs, select prompt IDs and response requirements, interpret responses, apply deterministic domain rules, and provide supported fallbacks. | | Pipeline execution | Connect generation to configured validation and strict/permissive handling; 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. | @@ -121,10 +122,12 @@ Place one small shared producer helper alongside assessment in cache/debug collaborators. For cacheable work it prepares the initial request and looks up the accepted-artifact cache; on a miss it executes the retained request. Otherwise it uses ordinary native execution. -4. For each executed response, the helper invokes module interpretation and - pipeline assessment. When correction is appropriate, it supplies the module's - next request to native coordination. PromptKit owns conversation state and - turn iteration; the helper does not implement another retry engine. +4. For each usable executed response, the helper invokes module interpretation and + pipeline assessment. Recognize native errors and failed validation results as + terminal failures before interpretation. When domain correction is appropriate, + it supplies the module's next request to native coordination. PromptKit owns + conversation state and turn iteration; the helper does not implement another + retry engine. 5. Return a typed application outcome. Cache only final accepted artifacts under the initial request's key. A cache hit follows the existing direct-reuse policy without model execution or renewed semantic assessment. @@ -222,24 +225,38 @@ One constructor registers application commands, the native alias, ckconfig's It does not load configuration, build an engine, or initialize run storage. Help, version, and completion work without application configuration. -Share two loading responsibilities across application and standard commands: +Share one application-owned configuration load and a separate engine-construction +step across application and standard commands: 1. Select application configuration through explicit `--config`, then existing - environment/discovery policy. Let ConfigKit apply overlays, imports, - inheritance, overrides, defaults, normalization, and structural validation. - Retain its native result and selected main-source context. Validate an + environment/discovery policy. Embed `promptkit.Settings` under `yaml:"promptkit"` + in the application configuration and compose its ConfigKit definition with + `promptkit.Configure`. Assemble the native sources below before calling + `configkit.LoadLayered` once for that selection. Let ConfigKit apply overlays, + imports, inheritance, overrides, defaults, normalization, and structural + validation. Retain its native result and selected main-source context. Validate an explicitly empty configuration path rather than falling through to discovery. -2. Build the native engine from that application's source context using the source - assembly below. Across commands, `--config` selects the application document; - the PromptKit scope inspects the engine assembled for it. Request overrides - do not mutate captured engine configuration. Do not emulate unsupported - arbitrary `--set` overrides for the PromptKit scope. +2. Pass the successful whole result to `promptkit.NewFromConfig`, with native + `RuntimeConfig` for runtime client/timeout/transient-retry options. Construction + captures the resolved resources without loading sources or running ConfigKit + callbacks again. Select `BundledOpenRouterUnderlay` before loading; this + constructor does not implicitly add the bundle. Across commands, `--config` + selects the application document. Request overrides do not mutate captured + engine configuration or the result's frozen inspection evidence. + +Use ConfigKit's native typed-value and subtree-inspection handoff. ckconfig's +application scope and ckprompt's focused `/promptkit` inspection share that same +result; use native adapters, including `FromConfigKitSubtree` where a focused +scope is needed. Keep native configuration paths, override capabilities, and +whole-load source/diagnostic evidence. A focused view is not a separately loaded +document. Remove separate PromptKit source loading, reparsing, and inspection +conversion rather than wrapping the new handoff in an application abstraction. Use small invocation-owned state through CommandKit's facilities to reuse loaded -values. A pipeline shares one engine across all roles. `config diff` may load two -distinct configurations within one invocation: keep their selections separate, -including overlays/overrides. No persistent loader cache or configuration hash -framework is needed. +results and constructed engines. A pipeline shares one engine across all roles. +`config diff` may load two distinct configurations within one invocation: keep +their selections separate, including overlays/overrides. No persistent loader +cache or configuration hash framework is needed. Reuse the application resolver for module/options checks, typed compatibility, ordered dependencies, validator chains, and reference bindings. `pipeline list` @@ -284,14 +301,23 @@ controls; U7 selects the shared worker pool and retired global-limit migration. U8 replaces the nested legacy cache settings with root-level `cache_directory` and pipeline/module-binding `cache` modes. -Use one source assembly for runtime, preflight, and inspection: +Use one source assembly in the shared ConfigKit load for runtime, preflight, +and inspection: 1. PromptKit's bundled OpenRouter underlay. -2. Notarius's embedded native prompts and profiles under `collections.notarius`. +2. Notarius's embedded native prompts and profiles under + `promptkit.collections.notarius`. 3. An optional, higher-priority operator underlay containing `prompts.yml` and recursive `.yml`/`.yaml` files under `prompts/`, beside the main application configuration actually selected by ConfigKit. +Complete documents place native resources and `schema_root` beneath `promptkit`. +Use `SettingsInput` for wrapperless settings fragments and `CollectionInput` for +collection fragments; discovered fragments need an explicit destination because +discovery helpers return root-mounted inputs. Keep resource IDs and exact +references unchanged by the configuration path. Old root-level prompt/profile +lists are not consumed as PromptKit resources; do not translate them implicitly. + Anchor companion discovery to that selected main source, whether explicit or discovered. Configurations in the same directory share companions; there is no working-directory fallback. The two companion locations are strict peers, so @@ -311,9 +337,11 @@ Convert maintained resources, examples, and fixtures to native identified lists, `config:` source controls, and sibling inheritance (`extends: {id: parent}`). Same-ID replacement supplies a complete record; distinct inherited variants can customize an existing resource. Explain native profile-null/backend fallback -semantics. The optional PromptKit source header is version 2, independently of -Notarius's application version. Do not translate legacy resource formats or -synthesize compatibility aliases. +semantics. Notarius owns application version 6 through its ConfigKit definition; +PromptKit adds no resource-version rule. Retire the planned PromptKit version-2 +source header. Collection `release_version` is optional descriptive +metadata, not a selector or validation gate. Do not translate legacy resource +formats or synthesize compatibility aliases. Select prompts by ID alone; remove obsolete PromptKit version selectors and related request/debug metadata. Retain current local resource IDs and use exact @@ -350,31 +378,43 @@ then use the same declared contract without repeating schema selection in Go. U4 selects prompt roles and contracts; exact prose is implementation work. U5 selects budget ownership and defaults. -Use a request-level native `OutputContract` only for a demonstrated runtime- -dependent contract. It replaces the whole configured contract, so supply the -intended format, validation mode, and schema together while leaving structural -repair at its native default. Do not inject a repair count merely to construct -the override, or introduce a wrapper or per-call registry solely to reproduce -Audita's approach. Operator prompt replacements must still produce responses the -selected module can interpret; that module boundary does not require duplicating -each prompt's schema selection in Go. +Use a request-level native `*promptkit.OutputContractInput` only for a demonstrated +runtime-dependent contract. It replaces the whole configured contract, so supply +the intended format, validation mode, and schema together while leaving structural +repair at its native default by leaving `RepairAttempts` nil. `OutputContract` +remains the resolved type in native prepared details. Do not inject a repair count +merely to construct the override, or introduce a wrapper or per-call registry +solely to reproduce Audita's approach. Operator prompt replacements must still +produce responses the selected module can interpret; that module boundary does +not require duplicating each prompt's schema selection in Go. -Default to native `WithSchemaFS(assets.FS(), ".")`. Schema paths are relative to -that selected root, for example `dnd/spells/schemas/dnd_spells_llm.v1.json`. -They are separate from message-file source contexts: prompt underlays do not -implicitly overlay schema files. When an operator configures an external schema -directory, select PromptKit's native directory source instead of the embedded -root. It replaces the whole schema source and must supply the schemas used by -the selected prompts. Do not build an application filesystem overlay to mix -embedded and external schemas. Transparent layering would be a separate upstream -capability, not a requirement for this migration. Concrete configuration binding -is an implementation detail within this selected source policy. +Declare the bundled collection's native `schema_root` in an embedded ConfigKit +source whose filesystem context points at the assets root. Bundled prompts use +`output.schema_path` relative to that root, for example +`dnd/spells/schemas/dnd_spells_llm.v1.json`. An operator can replace +`promptkit.collections.notarius.schema_root` with an external directory supplied +from the operator configuration's filesystem context. That replaces the whole +root for those schema-path lookups and must supply their selected schemas; +missing files do not fall back to the embedded root. Do not retain the removed +`WithSchemaFS`, `WithSchemaFile`, or `Config.SchemaDir` APIs or introduce an +application filesystem overlay. + +Support native prompt-owned inline `schema` and source-relative `schema_file` +selections as well, including operator prompts packaged with their own schemas. +Exactly one schema selection applies in JSON Schema mode. A nonnull collection +root takes precedence over `promptkit.schema_root`; an absent/null collection +root inherits it. Roots and file references retain the effective contributing +ConfigKit source's filesystem/base directory. There is no implicit working- +directory root. Request replacements use inline `Schema` or `SchemaPath` under +the selected prompt's applicable root; they do not inherit a configured +`schema_file` context. Native source composition owns these rules. Keep private response schemas as self-contained JSON documents. PromptKit owns loading, compilation, structural validation, provider structured-output settings, -and structural repair. Remove Notarius's response-schema byte registry, copied -schema wrappers, defensive-copy layer, digest calculation, and duplicate -structural-validation machinery. Native prepared snapshots provide diagnostic +and structural repair. It loads and compiles schemas during preparation and +retains them in prepared execution. Remove Notarius's response-schema byte +registry, copied schema wrappers, defensive-copy layer, digest calculation, and +duplicate structural-validation machinery. Native prepared snapshots provide diagnostic schema details; no schema fingerprint is added to the message-content cache key. Keep typed decoding, source/reference checks, reconciliation safety, semantic @@ -387,9 +427,10 @@ or reporting. No independent schema metadata system replaces them. Implementation is pending. Verify native preparation of embedded and operator prompt definitions, shared-file paths, schema selection from embedded and external -roots, and complete request-contract replacement where actually used. Missing or -invalid schemas should follow native preparation behavior. No new schema check -requiring synthetic requests is added to offline pipeline preflight. +roots, source-relative/inline selection, and complete request-contract replacement +where actually used. Missing or invalid schemas follow native preparation +behavior. No new schema check requiring synthetic requests is added to offline +pipeline preflight. ### Native Production, Continuation, And Assessment @@ -484,8 +525,11 @@ The application flow is: before execution as described below; execute the retained request on a miss. Otherwise use ordinary `Engine.Run`. Capture an exchange when continuation or debug inspection needs one. -2. Consume the native usable response or terminal failure, decode, and apply - module interpretation and safety checks. A module can supply actionable +2. Check the native error and public validation status before treating a response + as usable. PromptKit may return `ValidationFailed` with a nil Go error after + exhausting structural repair; that is a terminal failure, not a candidate for + application structural repair or cache storage. Decode a usable response and + apply module interpretation and safety checks. A module can supply actionable findings before it has a materialized candidate. Assess each candidate through all applicable configured validators and collect their actionable guidance before requesting correction, as selected in U4. @@ -557,12 +601,16 @@ Do not replace them with a hard-coded default, including zero, in request construction or a native output-contract override. Explicit operator customization remains available through native PromptKit prompt configuration. -Notarius deliberately inherits future upstream default changes. An anticipated -PromptKit default change is not a migration prerequisite, and its timing or -chosen count is not a Notarius contract. Notarius still declares response format, +PromptKit v0.24.0 defaults omitted/null budgets to one structural repair for +`basic`, `json`, and `json_schema`, and zero for `none`. These are upstream +defaults, not Notarius-pinned counts; Notarius deliberately inherits future +changes. Nil request budgets inherit the native default, while explicit zero +disables repair. Notarius still declares response format, validation mode, and schema; PromptKit owns the mechanics of obtaining a valid response. At the public boundary, handle a usable result or terminal failure, -including a returned result reporting unsuccessful structural validation. +including a returned result reporting `ValidationFailed` with a nil Go error. +Apply that boundary to producers, continuations, and LLM validators; consume the +native terminal status without inspecting or reproducing internal attempts. Do not restart the operation to extend PromptKit's exhausted repair budget. Remove blanket outer LLM retries, including repeated LLM validator invocations in @@ -786,12 +834,13 @@ message content; metadata outside those messages does not. | Change a prompt ID, model, or settings without changing messages | Cache hit remains possible. | | Change deterministic interpretation or validation | Existing accepted artifacts remain reusable; explicit bypass/refresh applies the new policy. | -Obtain the key before model execution through native preparation. Preserve the -prepared snapshot for execution on a miss using `PrepareExecution`/`RunPrepared` -where supported, and discard the handle on a hit. `OnPrepared` execution hooks -alone cannot short-circuit execution. v0.23.3's `RenderedPromptHash` includes -session identity and cache hints; it is not the requested hash. The upstream -API/release review in U1 must finish before completing this cache integration. +Call `PrepareExecution` before model execution and obtain the key from the returned +handle's `Details().MessageContentHash`. Treat this native value as +opaque and filename-safe. Preserve the prepared snapshot for execution on a miss +using `RunPrepared`, and discard the handle on a hit. `OnPrepared` execution hooks +alone cannot short-circuit execution. `RenderedPromptHash` includes session +identity and cache hints; it is not the cache key. U1's reviewed release supplies +the required API, with no local hash implementation or extra key dimensions. Keep the initial key throughout corrections. Cache the final Notarius artifact through its existing codec, not an intermediate response, `RunResult`, exchange, @@ -899,8 +948,8 @@ source partition to request-content-based plan reuse. Remove checkpoint identities, dependency fingerprints, invocation-wide barriers, recovery bookkeeping, and the separate canonical-plan lookup/publication policy. Retain domain plan interpretation and materialization without retaining a second -cache mechanism. U8 is resolved; implementation remains pending in Phases 3–5, -with completion dependent on verification of U1's upstream hash capability. +cache mechanism. U8 is resolved; implementation remains pending in Phases 3–5 +using U1's selected upstream hash capability. ### Inspection And Execution Bookkeeping @@ -1157,20 +1206,21 @@ pipeline debug bundles. Operators may redirect those reports. Neither debug mode nor capture initiates provider probes. Explicit smoke checks retain native support, applicability, and outcome distinctions. -## Unresolved Choices +## Decision Status -The architecture and public direction above are selected. Resolve each remaining -choice before its dependent work; independent work need not wait. Routine API -placement and serialization choices are implementation details, not reasons to -reopen the architecture. IDs retain continuity with the earlier roadmap. +U1–U10 are resolved. There are no remaining open architectural or dependency +choices in this roadmap. Observer wiring, debug filenames, routine API placement, +and serialization details remain implementation work within the selected designs. +IDs retain continuity with the earlier roadmap; all implementation phases remain +pending. -| ID | Remaining choice or dependency | Resolve for | -| --- | --- | --- | -| U1 | Review the message-content hash API/release documented upstream in v0.24.0, including its ConfigKit dependency; verify the final compatible dependency set against the selected baseline. | Track in Phase 1; required to finish cache integration in Phase 5. | - -U1 is the only remaining unresolved dependency decision. Observer wiring, debug -filenames, and other routine implementation details are delegated under the -resolved designs below; all implementation phases remain pending. +**U1 resolved:** The [reviewed dependency set](#baseline-and-dependency-target) +selects PromptKit v0.24.0, ConfigKit v1.4.0, ckconfig v0.10.0, ckprompt v0.11.0, +and CommandKit v0.7.0. Native `MessageContentHash` satisfies the cache requirement; +typed result handoff and focused inspection enable one application-owned load. +Adopt the native resource layout, schema selections, and `OutputContractInput` +API in Phase 2 and complete cache use in Phase 5. Upstream combination checks +passed; assembled Notarius acceptance remains implementation work. **U2 resolved:** Ordinary embedded assets, prompt-declared output contracts, native schema-source selection, and removal of duplicate schema/filesystem @@ -1226,7 +1276,7 @@ includes LLM chunk plans and replaces both legacy caches. Root-level explicit `--cache`, module-binding `cache`, pipeline `cache`, then `auto`. `auto` reads/writes, `bypass` does neither, and `refresh` writes newly accepted results without reading. Cache I/O is best effort; legacy records remain untouched -and are not imported. Implement in Phases 3–5, subject to U1's hash dependency. +and are not imported. Implement in Phases 3–5 using U1's selected native hash API. **U9 resolved:** [Execution bookkeeping](#inspection-and-execution-bookkeeping) uses one native execution group per invocation, with all actual initial, @@ -1255,32 +1305,36 @@ major boundary changes in successor ADRs without rewriting accepted decisions. ### Phase 1: Establish The Migration Baseline -- Record the selected dependency set and review U1 against the upstream release. - Keep the cache dependency explicit without blocking independent work. +- Use U1's reviewed dependency set and release/API evidence as the implementation + baseline; the upstream cache dependency is available and resolved. - Map affected ADRs, current callers, contracts, and removal inventory. Carry forward Audita evidence without adopting its application wrappers. -- Carry resolved U2–U10 designs into their dependent phases without reopening +- Carry resolved U1–U10 designs into their dependent phases without reopening ownership. Leave observer wiring and debug filenames to implementation. -**Completion evidence:** reviewed dependency baseline, upstream dependency, scope, -and outstanding choices are explicit. Upstream availability alone does not -establish compatibility of the assembled Notarius dependencies or completion -of the migration. +**Completion evidence:** reviewed dependency baseline, affected callers/ADRs, +scope, and removals are mapped to implementation work. The upstream review is +complete; applying those dependencies to Notarius and verifying the migration +remain separate work. ### Phase 2: Build Native Composition, Sources, And Preflight -- Implement the resolved U2 design, update available dependencies, introduce - configuration version 6, convert native embedded/companion resources, and use - native schema loading with embedded/default or operator-selected roots. Omit - bundled structural-repair settings and remove their application override fields. -- Build the small CommandKit application, shared ConfigKit/engine loaders, - standard suites, pipeline declarations/native alias, and `internal/preflight`. +- Apply U1's dependency set and implement U2: introduce configuration version 6, + mount native embedded/companion resources beneath `promptkit`, and replace the + old schema constructor options with native prompt selections and schema roots. + Use `OutputContractInput` for necessary runtime replacements. Omit bundled + structural-repair settings and remove their application override fields. +- Build the small CommandKit application with one application-owned ConfigKit + load, composed PromptKit rules, explicit bundled underlay, and `NewFromConfig` + engine construction. Share that result with native inspection and standard + suites; add pipeline declarations/native alias and `internal/preflight`. - Add maintained embedded-only and operator-override examples. Remove duplicated loading and asset assembly as callers migrate. -**Completion evidence:** runtime/inspection/preflight share intended definitions; -source contexts, shared message paths, prompt-declared output contracts, selected -schema roots, strict peer conflicts, and replacement work offline. Help, +**Completion evidence:** runtime/inspection/preflight share the same loaded result +and intended definitions without a second PromptKit load. Source contexts, shared +message paths, prompt-declared output contracts, selected schema roots, +source-relative schemas, strict peer conflicts, and replacement work offline. Help, version, and completion need no configuration. Preflight checks known dependencies without credentials or synthetic requests. `config diff` handles two selections. @@ -1294,6 +1348,8 @@ without credentials or synthetic requests. `config diff` handles two selections. default profile, supplied overrides, and validator-owned correction guidance. Resolve `max_additional_turns` with omission/zero distinctions and pass it to native coordination; inherit native transport and structural-repair defaults. + Treat a native failed-validation result as a terminal failure even when its + Go error is nil, including in continuation and validator paths. - Exercise an LLM validator on the same engine and normalization with fixed handles and fresh plan application. Wire U9's single invocation execution group with application scope for initial, continuation, and validator executions. @@ -1306,8 +1362,10 @@ without credentials or synthetic requests. `config diff` handles two selections. collection of independent validator findings without rejection short-circuiting, full candidate revalidation through the same assessor, final-turn acceptance without duplicate final validation, strict failure, permissive fallback, and useful -failures. Unavailable assessments remain distinct from actionable defects. The -executable publishes artifacts and reports them through native presentation +failures. Native failed-validation results never become accepted artifacts or +trigger an application extension of structural repair. Unavailable assessments +remain distinct from actionable defects. The executable publishes artifacts and +reports them through native presentation without the private completion/correction API. ### Phase 4: Migrate All Roles And Remove Superseded Machinery @@ -1336,8 +1394,8 @@ requirements remain. ### Phase 5: Complete Cache, Output, And Capture Integration -- Resolve U1's supplying release and implement U8's unified lookup at initial - preparation, accepted-artifact/plan storage under that hash, directory and mode +- Implement U8's unified lookup using the native prepared `MessageContentHash`, + accepted-artifact/plan storage under that initial hash, directory and mode precedence, and best-effort cache I/O. Retire both legacy cache mechanisms. - Complete U9's artifact-first publication/report contract. Preserve domain paths and schemas, add `fallback_count`, and retire index/reporting sidecars. Remove @@ -1378,9 +1436,10 @@ Release preparation/publication is governed separately by release policy. | Retire or replace | Retained application responsibility | | --- | --- | +| Separate application/PromptKit loading, duplicated source interpretation and inspection conversion | One composed ConfigKit load and native result handoff to engine construction and focused inspection. | | `StructuredLLMClient`, private request/response types, adapter conversions, emptied `internal/framework/llm` package | Composition-root engine construction, native module request/interpretation functions, and pipeline assessment/helper. | | `AssetRegistry`, `PromptAssetManifest`, `ModulePromptFS`, synthetic mounts, flattened schema namespaces, `readonlyfs`, manual fingerprint enumeration | Ordinary embedded content, native source assembly, and module meaning. | -| Private response-schema registry/wrappers, byte copies, digest and reporting-only identity metadata, duplicate structural validation | Native prompt output contracts and schema loading; application interpretation and durable artifact contracts. | +| Private response-schema registry/wrappers, byte copies, digest and reporting-only identity metadata, duplicate structural validation, old schema constructor options | Native prompt output contracts, schema selections and roots; application interpretation and durable artifact contracts. | | `single_response_v1`, raw `ModelCandidate`/`SemanticCorrection`, manual replay, correction capability checks | Typed candidates, actionable findings, native exchanges, assessment. | | Generic `runProducerAttempts` outer loop, repeated validator executions in `executeValidationChain`, all producer/validator `retries` fields, module rerun directives, hard-coded `CorrectionRequest` message builder | Ordinary deterministic execution, native LLM execution/continuation, ordered validators, validator/module-owned guidance, native domain correction templates, and domain acceptance/rejection/fallback. | | Application `structured_output_repair_attempts` fields/resolution and explicit bundled `output.repair_attempts` | Native upstream structural-repair default, with operator customization through native prompt configuration. | @@ -1404,14 +1463,14 @@ retry tests or freeze complete help text and native debug snapshots. | Area | Required evidence | | --- | --- | -| Configuration/assets | Version 6/new resources work; old formats intentionally rejected; companions/native imports retain main-source context; peer conflicts fail; same-ID replacement, real shared-file paths, prompt-declared contracts, and embedded/external schema roots work; necessary request overrides replace the complete contract. | -| Commands/loaders | Required operands, native alias, supplied-value distinctions, references, and run-wide overrides reach intended handlers/roles; help/version/completion need no config; diff selections remain distinct. | +| Configuration/assets | Application version 6 and resources beneath `promptkit` work without a separate PromptKit resource-version gate or legacy translation; companions/native imports retain main-source context; peer conflicts fail; same-ID replacement, real shared-file paths, prompt-declared contracts, embedded/external roots and source-relative/inline schemas work. Root replacement has no missing-file fallback. Necessary `OutputContractInput` overrides replace the complete contract. | +| Commands/loaders | One composed ConfigKit load supplies engine construction and native inspection, including explicit bundled resources, source evidence, and focused paths; no duplicate PromptKit load. Required operands, native alias, supplied-value distinctions, references, and run-wide overrides reach intended handlers/roles; help/version/completion need no config; diff selections remain distinct. | | Preflight/inspection | Same definitions across execution and inspection; missing statically selected resources fail with context; partial profiles alone pass; no provider calls, transcript, or credential requirement for offline preflight. | | Domain workflow | Representative extraction and normalization preserve source/reference identity, fixed handles, safe plan application, ordered validators, artifact schemas, and stable output ordering; one assessor checks initial/corrected candidates without an extra final pass; deterministic stages and LLM validators need no producer conversation loop. | | Prompt/guidance contracts | Domain-specific initial/correction pairs use the same response schema and default profile; explicit profile/execution overrides reach both; operator correction-profile defaults work when not overridden; all applicable validators assess the same candidate despite earlier rejection; their actionable findings reach the correction template; module interpretation defects and unavailable assessments remain distinct. | | Retry controls | `max_additional_turns` resolves binding, pipeline, then application default `2`; explicit zero disables correction; acceptance stops early and the final allowed turn is assessed. Bundled declarations/application overrides leave structural repair unspecified, native operator customization remains effective, and tests do not freeze upstream default attempt counts. | | Non-LLM failure handling | Deterministic errors propagate without generic retries; rejected deterministic candidates reach terminal policy without regeneration; cancellation stops work. Producer/validator `retries` fields and the generic outer attempt loop are retired. | -| Continuation/failures | Accumulated history, full revalidation and final-turn assessment; no blanket retries beyond native exhaustion; validator failure differs from rejection; no earlier-candidate recovery or cross-turn proposal union; cancellation stops without fallback work. | +| Continuation/failures | Accumulated history, full revalidation and final-turn assessment; native failed validation with a nil Go error reaches terminal handling before domain interpretation or caching in producer, continuation, and validator paths. No blanket retries beyond native exhaustion; validator failure differs from rejection; no earlier-candidate recovery or cross-turn proposal union; cancellation stops without fallback work. | | Strict/permissive outcomes | `mode` resolves module binding, pipeline, then strict; omission inherits and either explicit value overrides. Strict is the default for every role, including normalization, without module-specific defaults. Strict failure when no acceptable result is obtained; permissive handling produces module fallback with required artifact/downstream invariants, without rerunning the ordinary full validation chain or claiming normal acceptance. Chunking fallback is one whole-transcript chunk preserving source order/references. Fallback construction failure fails execution; successful fallback use is disclosed in human/machine completion reports. | | Admission/workers | One shared extraction/lane completion pool obeys `concurrency.workers`, default `64`; explicit `1` runs serially without dependency or nested-validator deadlock. Only ready jobs occupy slots; result ordering remains stable. Backend limits remain independent with no application-injected defaults. Producer/validator admission failures use U6's mode, preserve useful diagnostics, and add no retries; cancellation releases capacity. No separate global LLM ceiling. | | Accepted-artifact cache | Downstream recovery; initial-message keys; corrected final artifact stored late under the initial key; changed messages miss; settings/ID-only changes can hit; no model/revalidation on hits; unusable entries miss. Failed/rejected/incomplete work is not stored; fallbacks and affected downstream work skip lookup/storage while unaffected accepted predecessors remain reusable; no required history. | @@ -1444,9 +1503,12 @@ Provide practical release guidance for operators and subprocess callers: - New commands/flags, native `run` alias, `--format`, stdout/stderr, outcomes, and saving optional reports by redirection. No legacy CLI compatibility promise. -- Version 6 and native resources, embedded-only versus companion examples in - appropriate directories, imports, qualified IDs, replacement/inheritance, - native local backends, removed catalogs/versions, and separate source versions. +- Application version 6 and native resources beneath `promptkit`, embedded-only + versus companion examples in appropriate directories, imports, qualified IDs, + replacement/inheritance, native local backends, and removed catalogs/version + selectors. Explain native schema selections and collection/application roots, + external root replacement, + and the removal of a separate PromptKit source-version requirement. - Shared `concurrency.workers` default `64`, ready-job scope, explicit serial execution, native backend concurrency/queue settings, and removal of the global limit and old extraction-worker field without automatic backend translation. @@ -1506,7 +1568,14 @@ tagged PromptKit links below preserve the reviewed baseline. - [ckconfig](../../../commandkit/integrations/ckconfig/README.md) and [ckprompt](../../../commandkit/integrations/ckprompt/README.md): standard suites supplied with application loaders and request builders. -- [ConfigKit](../../../ConfigKit/README.md): native loading and inspection. +- [ConfigKit v1.4.0 release notes][configkit-release]: typed result handoff and + focused inspection over the original load's provenance and resource contexts. +- [ckconfig v0.10.0][ckconfig-release] and [ckprompt v0.11.0][ckprompt-release]: + the selected integration compatibility and API changes. +- [Shared-loading guidance][consumer-loading] and the + [composed CLI example](../../../commandkit/integrations/ckprompt/examples/composed/main.go): + composed rules, explicit bundled resources, one application result, native + engine construction, and focused standard scopes. - [PromptKit consumer guide][consumer] and [capacity behavior](../../../promptkit/docs/internal/capacity.md): native preparation/execution, continuation, observations, and admission. @@ -1537,7 +1606,11 @@ cancellation during repair, and repair-disabled/output selections using a local fake provider. These historical checks do not establish live-model quality or completion of Notarius's migration acceptance checks. -[release]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/releases/v0.23.3.md -[migration]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/consumers/configuration-migration.md -[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/formats.md -[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.3/docs/consumers/pkg-promptkit.md +[release]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/releases/v0.24.0.md +[migration]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/configuration-migration.md +[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md +[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md +[consumer-loading]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load +[configkit-release]: https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/releases/v1.4.0.md +[ckconfig-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.10.0/integrations/ckconfig/docs/releases/v0.10.0.md +[ckprompt-release]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckprompt/v0.11.0/integrations/ckprompt/docs/releases/v0.11.0.md