From 058703abe5af8c8b147a619f2d8e451f0cd38756 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 18:59:02 +0000 Subject: [PATCH] Resolve unified cache configuration and legacy migration --- docs/roadmap/future.md | 4 +- docs/roadmap/promptkit.md | 151 ++++++++++++++++++++++++++++++-------- 2 files changed, 124 insertions(+), 31 deletions(-) diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index e3798d18..b05cab3f 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -56,7 +56,7 @@ The sections below keep broader extensions deferred. deterministic safety rules. Define any additional configuration and domain compatibility checks from that workflow; do not recreate asset registration, prompt fingerprints, or checkpoint dependency tracking. -- Reuse the selected [accepted-artifact cache policy](promptkit.md#accepted-artifact-cache) +- Reuse the selected [accepted-artifact cache policy](promptkit.md#accepted-artifact-cache-u8-resolved) when evaluating policy changes and the need for explicit refresh. ### Broader Reconciliation Inputs And Module Selection @@ -121,7 +121,7 @@ Define compatibility and migration policy before generated-reference chains must span multiple schema versions or long-lived historical artifacts. The policy should address stable identifier semantics, when an older artifact may be decoded or adapted, and when consumers need regenerated artifacts. For cached -artifacts, use the [selected reuse policy](promptkit.md#accepted-artifact-cache) +artifacts, use the [selected reuse policy](promptkit.md#accepted-artifact-cache-u8-resolved) and explicit refresh where needed. Do not add a general migration framework until an actual contract change requires one. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 2f4686c6..18873f56 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -190,8 +190,7 @@ a singleton flag and use the last successfully parsed value. | Pipeline input | Required pipeline-ID operand and `--input-file PATH`. | | Lanes | Repeatable `--lane ID`; omission selects the normal lane set. Commas are literal values, not separators. | | Output | Application `--output-dir PATH`. | -| Chunk-plan cache | `--chunk-cache auto\|bypass\|refresh`. | -| Accepted-artifact cache | Reuse/bypass/refresh controls; spelling, scope, and defaults remain U8. | +| Cache | `--cache auto\|bypass\|refresh` overrides caching for the entire invocation, including chunk generation. Otherwise resolve module-binding `cache`, pipeline `cache`, then `auto`. | | References | Repeatable `--reference SELECTOR=PATH` and `--without-reference SELECTOR`. | | Presentation | Native `--format`, `--quiet`, `--verbose`, `--debug`, and `--progress`. | | Capture destination | Application `--debug-dir PATH`, with the semantics below. | @@ -282,6 +281,8 @@ native companion sources; do not introduce a separate `promptkit.config_file`. Retire `concurrency.total_llm` and revise retry/worker settings as described below. U5 selects `max_additional_turns` and removes application structural-repair 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: @@ -755,15 +756,16 @@ inheritance/caps from that field. Provide a native limited-backend example with usable queue capacity, without requiring operators to override the upstream queue default. U7 is resolved; implementation remains in Phase 4. -### Accepted-Artifact Cache +### Accepted-Artifact Cache (U8 Resolved) -Replace the checkpoint subsystem with a cache around the complete Notarius -producer operation. Its value is an accepted answer to the original task. This -avoids repeating expensive model work after a downstream failure without caching -every cheap deterministic pipeline step. +Replace both the checkpoint subsystem and the separate source-keyed chunk-plan +store with one cache around the complete Notarius producer operation. Its value +is an accepted answer to the original task, including an accepted chunk plan for +LLM-backed chunk generation. This avoids repeating expensive model work after a +downstream failure without caching every cheap deterministic pipeline step. ```text -Prepare initial request -> obtain MessageContentHash -> look up cache/.json +Prepare initial request -> obtain MessageContentHash -> look up /.json Hit: decode the accepted artifact and continue the pipeline Miss: execute the retained request and complete the Notarius operation -> interpret, validate, and perform application-directed corrections @@ -809,6 +811,25 @@ validation merely because the artifact was cached. It makes no claim of acceptan under changed validation policy and contributes no historical token usage to current execution totals. +For an LLM chunker, cache the final accepted plan after materialization, configured +validation, and any application-directed corrections succeed. On a hit, decode +the plan and deterministically materialize chunks from the current source. +Retain ordinary structural and source-reference usability checks; an unusable +plan is a miss. Do not rerun semantic validators merely because the plan was +cached. The plan remains a domain result, without the old provenance envelope or +a cached copy of the full transcript. Deterministic chunkers execute normally; +do not manufacture a PromptKit request or a second hash policy to cache them. + +Retire the guarantee of one canonical partition per source regardless of the +configured chunking request. Matching initial messages reuse the same accepted +plan; changed prompt/reference/input text can produce a miss and a different +partition. Model/settings-only changes can still hit under the shared hash +policy. Source identity alone no longer selects a plan. This deliberately +supersedes the policy in [ADR-0005](../adr/0005-cache-canonical-chunk-plans-by-source.md) +as the migration lands; preserve the accepted ADR and record a successor decision. +Chunk-plan semantics and deterministic materialization remain application-owned; +their storage and reuse use the same mechanism as other accepted results. + PromptKit owns everything inside each native request, including structural validation, transport retries, and repairs. Notarius consumes its public response or terminal failure and owns domain acceptance. Internal PromptKit attempts do @@ -816,15 +837,70 @@ not determine cache eligibility. Native diagnostic evidence does not transfer that ownership. No cached-response injection, replay API, exchange restoration, or PromptKit-owned write-through cache is requested. +#### Cache Configuration And Reuse Controls + +Use root-level `cache_directory` for the shared cache root. Omission or an empty +value selects `os.UserCacheDir()/notarius`: normally `~/.cache/notarius` on Linux, +respecting `XDG_CACHE_HOME`. An explicit directory is the exact root, independent +of output/debug roots and run IDs. Document `/var/cache/notarius` as the convention +for an explicitly configured system-wide installation. Directory selection does +not enable or disable caching; modes govern cache I/O. + +Use `cache: auto|bypass|refresh` at pipeline level, with optional module-binding +overrides. Resolve an explicitly supplied `--cache` first, then module-binding +`cache`, then pipeline `cache`, then default `auto`. Omission inherits. An explicit +CLI value governs all cacheable work in the invocation, including chunk generation; +without it, module overrides take precedence over the pipeline setting. Ordinary +configuration and `--set` can select more specific bindings. No independent +recording switch, separate chunk-cache control, or per-step recomputation selector +is needed. + +| Mode | Read existing entries | Store newly accepted results | +| --- | --- | --- | +| `auto` (default) | Yes | Yes | +| `bypass` | No | No | +| `refresh` | No | Yes | + +Modes never override the accepted-result eligibility rules. `refresh` replaces an +entry only after a newly accepted result is obtained; failure or fallback leaves +an existing entry untouched. `bypass` performs no cache I/O or directory creation. +Rerunning with default `auto` reuses successful predecessors and executes previously +unsuccessful work without a separate resume request. + Use a small filesystem lookup/write facility and ordinary temporary-file/rename -publication. `cache/.json` contains the artifact, with no required manifest, -acceptance ledger, historical provenance, or versioned checkpoint envelope. -Lookup does not require original output or debug directories. Remove checkpoint -identities, dependency fingerprints, invocation-wide barriers, and recovery -bookkeeping. Preserve the separate canonical chunk-plan cache and its materialized -chunk validation. Cache directory configuration, reuse/bypass/refresh controls, -and handling of old checkpoint files remain U8; old `--resume`/`--recompute-step` -conventions are not compatibility requirements. +publication. `/.json` contains the accepted artifact or +chunk plan, with no required manifest, acceptance ledger, historical provenance, +or versioned checkpoint envelope. Lookup does not require original output or +debug directories. + +Missing entries are ordinary misses. Unreadable, malformed, or unusable entries +are misses with useful diagnostics. Cache write failures warn and preserve the +successful application result; do not rerun model work to compensate for a failed +cache write. Cache I/O failures do not fail otherwise successful pipeline work. +Invalid configuration still follows ordinary configuration-error handling. +No expiration policy, garbage collector, or cache migration command is required. + +#### Migration From Both Legacy Caches + +Start the unified cache empty and populate it through ordinary execution. Ignore +legacy checkpoint and source-keyed chunk-plan records; do not import, reinterpret, +rewrite, or automatically delete them, even when their directories are beneath +the new root. They do not supply the new message-content keys. Operators may +remove obsolete directories when convenient. + +Retire `cache.checkpoints` and `cache.chunk_plans`, including their separate +directories and checkpoint recording switch. Remove `--resume`, +`--recompute-step`, and the separate chunk-cache flag, including the previously +planned `--chunk-cache`. Release guidance maps those intentions to root-level +`cache_directory`, pipeline/module `cache`, and invocation-wide `--cache`. +Explain automatic reuse, first-run population, and the move from a canonical +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. ### Inspection And Execution Bookkeeping @@ -1052,7 +1128,6 @@ reopen the architecture. IDs retain continuity with the earlier roadmap. | 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. | -| U8 | Cache directory configuration and reuse/bypass/refresh controls (names, defaults, scope); old-checkpoint treatment and unusable-entry diagnostics. Hash inputs, lookup timing, accepted value, and ownership are settled. | Design with Phase 3; finish in Phase 5. | | U9 | Observer/group enrollment and application scope; concrete conditional report fields and debug filenames/serialization within the agreed contracts; publication-layout/consumer migration details preserving intrinsic artifact schemas. | Implementation details in Phases 3–5; no new receipt/manifest inventory or capture-policy decision required. | **U2 resolved:** Ordinary embedded assets, prompt-declared output contracts, @@ -1102,6 +1177,15 @@ backend capacity with no injected application defaults; admission failures use U6's mode without extra retries or queues. Retire `total_llm` and the old extraction worker field with explicit migration guidance. Implement in Phase 4. +**U8 resolved:** [The unified accepted-result cache](#accepted-artifact-cache-u8-resolved) +includes LLM chunk plans and replaces both legacy caches. Root-level +`cache_directory` selects a per-user default or an explicit root, with +`/var/cache/notarius` documented for system-wide installation. Mode precedence is +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. + **U10 resolved:** CommandKit versions, capabilities, commands, loaders/preflight, output, debug policy, and coordinated cutover sequencing are selected above. The former later CommandKit phase is retired. CLI compatibility is a non-goal; @@ -1122,7 +1206,7 @@ major boundary changes in successor ADRs without rewriting accepted decisions. Keep the cache dependency explicit without blocking independent work. - Map affected ADRs, current callers, contracts, and removal inventory. Carry forward Audita evidence without adopting its application wrappers. -- Preserve U8–U9 with their dependent phases; do not reopen resolved module +- Preserve U9 with its dependent phases; do not reopen resolved module execution, prompt/guidance ownership, retry controls/defaults, assets/schemas, worker/admission policy, CommandKit, debug, cache, or output ownership. @@ -1162,7 +1246,8 @@ without credentials or synthetic requests. `config diff` handles two selections. handles and fresh plan application. Select actual observer/group enrollment. - Run through the new command surface and alias, using the small completion report, native outcomes/streams, and useful debug capture from the outset. - Begin U8/U9 integration without a provisional local message hash. + Begin the resolved U8 cache integration and U9 details without a provisional + local message hash. **Completion evidence:** fake-provider workflows exercise accumulated history, collection of independent validator findings without rejection short-circuiting, @@ -1198,9 +1283,9 @@ requirements remain. ### Phase 5: Complete Cache, Output, And Capture Integration -- Resolve U1's supplying release and complete U8. Implement lookup at initial - preparation, accepted-artifact storage under that hash, explicit cache controls, - and deliberate old-checkpoint handling. Keep canonical chunk caching separate. +- Resolve U1's supplying release and implement U8's unified lookup at initial + preparation, accepted-artifact/plan storage under that hash, directory and mode + precedence, and best-effort cache I/O. Retire both legacy cache mechanisms. - Complete the artifact-first publication/report contract and U9 details. Remove checkpoint fingerprint graphs, mandatory manifests/receipts, durable execution ledgers, and duplicate accounting; do not retain them to populate summaries. @@ -1211,9 +1296,11 @@ requirements remain. message changes miss and settings-only changes can hit; corrected answers use the initial key; hits make no model calls or fresh validation claims. Fallbacks and affected downstream work skip cache lookup/storage; unaffected accepted work -remains reusable. Artifacts need no metadata bundle. Machine output and debug -capture obey the selected contracts, including failures after publication and -quiet-mode capture. +remains reusable. Chunk plans use the same cache, rematerialize against current +source, and no longer pin one partition across changed messages. Mode precedence, +cache I/O failures, and leaving both legacy stores untouched are verified. +Artifacts need no metadata bundle. Machine output and debug capture obey the +selected contracts, including failures after publication and quiet-mode capture. ### Phase 6: Verify And Document The Coordinated Cutover @@ -1243,6 +1330,7 @@ Release preparation/publication is governed separately by release policy. | Failure-category `validation_policy` fields and separate `fail_run`/`reject_output`/`warn_continue` actions | Strict/permissive selection, module-owned fallback construction, and explicit fallback outcomes. | | `Scheduler`, `scheduledClient`, `concurrency.total_llm`, `concurrency.stage_workers.extract`, separate extraction/lane worker pools | One ready-job pool controlled by `concurrency.workers`, default `64`, and native backend admission. | | Checkpoint stage/dependency/configuration fingerprints, invocation-wide barriers, manifests, acceptance/provenance envelopes | Small accepted-artifact cache using the upstream message hash, ordinary load checks, explicit controls. | +| Separate source-keyed chunk-plan store, canonical-plan provenance/publication policy, nested legacy cache configuration, `--resume`, `--recompute-step`, separate chunk-cache flag | Unified message-content lookup/storage, domain chunk-plan interpretation/materialization, `cache_directory`, pipeline/module `cache`, and invocation-wide `--cache`. | | Inspection wrappers, copied effective parameters, usage summaries/conversions/accumulators, debug completion wrapper, synthetic IDs, profile recorder | Native facts with application scope for diagnostics. | | Custom dispatch/help/version/parsing, command-specific loading, copied inspection, legacy aliases/flags, parallel encoders and verbosity handling | Native declarations/loaders, pipeline handlers, domain input checks. | | Mandatory run manifests, reporting-only metadata bundles, extensive receipts and durable execution ledgers | Domain artifact files, one small native completion report, optional debug evidence. | @@ -1270,7 +1358,8 @@ retry tests or freeze complete help text and native debug snapshots. | 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. | -| Cache migration | Selected reuse/bypass/refresh and old-record treatment work; invocation configuration no longer blocks lookup; canonical chunk caching retains its distinct policy. | +| Chunk-plan reuse | Final accepted plan stored under the initial request hash after materialization/validation/correction; hits rematerialize with structural/source-reference usability checks and no renewed semantic validation. Changed messages can select a new partition; deterministic chunkers run without synthetic cache requests. | +| Cache controls and migration | Root-level directory default/explicit selection; mode precedence CLI, module binding, pipeline, then `auto`. `auto` reads/writes; `bypass` does no I/O or directory creation; `refresh` only replaces entries after new acceptance. Unusable entries miss; cache I/O failures preserve successful pipeline results. Both legacy stores remain untouched and unread; no conversion or separate canonical-plan mechanism. | | Output/outcomes | Artifact files independent of report format; native text/JSON/YAML summary and qualified outcomes; no mandatory metadata bundle; quiet suppression, verbose stderr, debug path; native nonzero failures and useful explanations. Publication survives later capture/report failure without model reruns. | | Execution observations | Initial/continuation/validator totals preserve unknown-versus-zero usage without double counts; result-less failures observable; reuse does not count historical work; native execution success remains distinct from acceptance. | | Debug controls/lifecycle | Default/CLI/config/explicit-empty paths and native mode ordering; quiet capture; allocation before engine/preflight; start-time relative `latest`, no completion retarget; disabled runs leave it untouched; capture failures preserve primary causes and publication facts. | @@ -1313,9 +1402,12 @@ Provide practical release guidance for operators and subprocess callers: costs, the universal strict default, pipeline `mode` with module-binding overrides, and each module's fallback behavior and downstream guarantees, including the whole-transcript chunking fallback. -- Accepted-artifact caching, message-based misses, settings-only reuse, refresh/ - bypass for changed interpretation or validation, fallback/affected-work exclusion, - and old-checkpoint handling. +- Unified accepted-artifact and chunk-plan caching, message-based misses, + settings-only reuse, root-level `cache_directory` and the per-user/system-wide + conventions, pipeline/module `cache`, and invocation-wide `--cache` precedence. + Explain refresh/bypass, best-effort I/O, fallback/affected-work exclusion, removal + of both legacy mechanisms without importing/deleting records, and retirement of + canonical-source partition reuse. - Artifact delivery without mandatory manifests/receipts; preserve intrinsic artifact schemas and document any explicitly selected format change. - Debug root/default/empty behavior, `latest`, native mode ordering, failure @@ -1335,6 +1427,7 @@ Record significant changes in successor ADRs, including [validation retries](../adr/0014-feedback-aware-validation-retries.md), [module retries](../adr/0016-feedback-aware-module-requested-retries.md), [PromptKit configuration](../adr/0019-adopt-native-promptkit-configuration.md), +the [canonical chunk-plan policy](../adr/0005-cache-canonical-chunk-plans-by-source.md), admission, caching, and CLI/reporting ownership. Preserve accepted decision text and update supersession status under [documentation policy](../policy/documentation.md#architecture-decision-records). This roadmap owns implementation status; Git history retains earlier discussions.