Update native migration roadmap for reviewed upstream releases
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user