Resolve unified cache configuration and legacy migration
This commit is contained in:
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user