Update native migration roadmap for reviewed upstream releases

This commit is contained in:
2026-11-21 21:51:23 +00:00
parent 5359cba98d
commit 3f51764f1e

View File

@@ -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