Resolve unified cache configuration and legacy migration

This commit is contained in:
2026-11-20 18:59:02 +00:00
parent 254401e5f6
commit 058703abe5
2 changed files with 124 additions and 31 deletions

View File

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

View File

@@ -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/<hash>.json
Prepare initial request -> obtain MessageContentHash -> look up <cache_directory>/<hash>.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/<hash>.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. `<cache_directory>/<hash>.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.