@yadsh/dsh-kv-persist 0.2.3 → 0.2.5

package/docs/dsh-kv-persist.md

@@ -1,3312 +0,0 @@
-# dsh-kv-persist
-
-> Persistent KV-cache/session-state manager for DeepSeek Harness.
-
-**Status:** Draft / Initial Specification  
-**Target:** DeepSeek Harness + llama.cpp `llama-server`  
-**Initial version:** `0.1.0`  
-**Primary backend:** llama.cpp slot save/restore API  
-**Future backends:** vLLM / SGLang / other providers exposing reusable prefix/session state
-
----
-
-## 1. Summary
-
-`dsh-kv-persist` is a DeepSeek Harness infrastructure plugin that persists LLM runtime cache state between sessions and process restarts.
-
-The first implementation targets `llama-server` and its slot persistence API:
-
-- `GET /slots`
-- `POST /slots/{id}?action=save`
-- `POST /slots/{id}?action=restore`
-- `POST /slots/{id}?action=erase`
-
-llama.cpp can persist a slot's prompt/KV state into a file under `--slot-save-path`, then restore that state later.
-
-The plugin maps:
-
-```text
-DSH session
-    ↓
-provider + model + server instance
-    ↓
-llama.cpp slot
-    ↓
-persistent snapshot
-```
-
-Its main purpose is to avoid re-prefilling tens or hundreds of thousands of tokens whenever:
-
-- the user switches between DSH sessions;
-- `llama-server` evicts a session from its active slot;
-- DSH is restarted;
-- `llama-server` is restarted;
-- another request temporarily pollutes the active slot;
-- multiple projects share the same local model server.
-
-For a large agent prompt this can turn:
-
-```text
-restore session
-→ process 40K–100K prompt tokens again
-→ wait tens/hundreds of seconds
-```
-
-into:
-
-```text
-restore session
-→ load KV snapshot
-→ process only changed suffix
-```
-
----
-
-# 2. Goals
-
-The plugin MUST:
-
-1. Associate persistent cache snapshots with DSH `session.id`.
-2. Automatically restore the appropriate snapshot before a session resumes.
-3. Automatically save dirty cache state according to a configurable checkpoint policy.
-4. Prevent one DSH session from accidentally reusing another session's slot as authoritative state.
-5. Detect incompatible or stale snapshots and fail safely.
-6. Never make the model-visible conversation depend on the snapshot.
-7. Treat KV persistence purely as an optimization.
-8. Fall back to normal cold prompt processing whenever persistence is unavailable.
-9. Work with a normal OpenAI-compatible `llama-server`.
-10. Provide useful observability:
-   - restore hit/miss;
-   - bytes saved/read;
-   - save/restore latency;
-   - cache tokens;
-   - slot ownership;
-   - snapshot age;
-   - cold fallback count.
-11. Survive plugin hot reload and normal Cordis disposal cleanly.
-12. Be backend-agnostic internally even though llama.cpp is the first backend.
-
-DeepSeek Harness already treats sessions as append-only durable state and derives LLM messages from that state, so persisted KV MUST remain a disposable acceleration layer rather than a second source of truth.
-
----
-
-# 3. Non-goals
-
-Initial versions MUST NOT:
-
-- replace DSH session persistence;
-- store actual conversation history as the authoritative state;
-- attempt to reconstruct missing DSH events from KV;
-- modify model-visible prompts to improve cache hits;
-- expose KV management as an LLM tool;
-- assume snapshots are portable between different models;
-- assume snapshots are portable between arbitrary llama.cpp builds;
-- manage llama-server process startup itself;
-- transparently migrate a snapshot between machines;
-- promise persistence support for every recurrent/hybrid model;
-- require DSH UI modifications.
-
-The model should ideally never know this plugin exists.
-
----
-
-# 4. Core design principle
-
-The following relationship is fundamental:
-
-```text
-DSH session log = truth
-KV snapshot     = derived cache
-```
-
-A snapshot can always be deleted.
-
-Deleting:
-
-```text
-$DSH_HOME/cache/dsh-kv-persist/...
-```
-
-must never destroy the conversation.
-
-The worst possible consequence of missing or invalid KV state must be:
-
-```text
-cold prefill
-```
-
-not:
-
-```text
-corrupted conversation
-wrong session
-missing messages
-incorrect continuation
-```
-
----
-
-# 5. Relevant DSH architecture
-
-DSH exposes an in-memory `ctx.sessions` service.
-
-A `Session` has a stable `session.id` and an append-only sequence of `SessionEvent`s. LLM history is derived from those events rather than stored as a separate mutable chat history. DSH persistence plugins can observe `session/event`, `session/flush`, `session/created`, and `session/disposed`.
-
-Model calls eventually pass through:
-
-```text
-agent loop
-    ↓
-agent/request
-    ↓
-prepareCall()
-    ↓
-llm/stream
-    ↓
-LLM adapter
-    ↓
-llama-server
-```
-
-`llm/stream` is explicitly intended to support infrastructure such as caching/logging/routing. Loop-generated `GenerateOptions` are deep-frozen and must be observed rather than mutated.
-
-`GenerateOptions` also carries:
-
-```ts
-sessionId?: SessionId
-purpose?: 'compaction' | 'session-title'
-```
-
-which gives the plugin enough information to distinguish ordinary session inference from auxiliary LLM requests.
-
----
-
-# 6. llama.cpp backend
-
-## 6.1 Server requirements
-
-The llama server should be started with at least:
-
-```bash
-llama-server \
-  ... \
-  --slots \
-  --slot-save-path /some/path
-```
-
-For the initial MVP:
-
-```bash
---parallel 1
-```
-
-is strongly recommended.
-
-Example:
-
-```bash
-./llama-server \
-  -m Qwen3.8-27B-GSQ-RCO-IQ2_XS.gguf \
-  --ctx-size 131072 \
-  --parallel 1 \
-  --flash-attn on \
-  --cache-type-k q4_0 \
-  --cache-type-v q4_0 \
-  --n-gpu-layers all \
-  --slot-save-path E:/LLM/kv-cache \
-  --host 127.0.0.1 \
-  --port 8080
-```
-
----
-
-# 7. Why the MVP should use one slot
-
-With:
-
-```text
---parallel 1
-```
-
-there is one inference slot:
-
-```text
-slot 0
-```
-
-Therefore the plugin doesn't need to modify OpenAI request bodies.
-
-It can treat slot `0` as an expensive hardware-backed working register:
-
-```text
-                 ┌──────────────┐
-session A ─────► │              │
-session B ─────► │    slot 0    │
-session C ─────► │              │
-                 └──────────────┘
-                         ↕
-                   snapshots
-```
-
-Switching A → B becomes:
-
-```text
-save A if dirty
-restore B
-run B
-```
-
-Switching B → A:
-
-```text
-save B if dirty
-restore A
-run A
-```
-
-This makes an excellent first implementation because:
-
-- there is no slot allocator;
-- there are no slot races;
-- no llama-specific fields have to enter DSH `GenerateOptions`;
-- the existing DSH LLM adapter can remain untouched.
-
----
-
-# 8. Multi-slot limitation
-
-llama.cpp supports specifying:
-
-```json
-{
-  "id_slot": 2
-}
-```
-
-on inference requests, allowing a client to explicitly select a slot.
-
-However DSH's `GenerateOptions` deliberately contains provider-neutral fields and loop requests are immutable. `llm/stream` middleware therefore cannot safely do:
-
-```ts
-options.id_slot = 2
-```
-
-or otherwise inject arbitrary llama.cpp transport fields.
-
-Consequently:
-
-```text
-v0.1:
-parallel=1
-generic middleware
-slot 0
-
-v0.2+:
-managed multi-slot mode
-custom llama.cpp transport adapter
-```
-
-This separation should be intentional.
-
----
-
-# 9. High-level architecture
-
-```text
-┌──────────────────────────────────────────────────────┐
-│                DeepSeek Harness                      │
-│                                                      │
-│  ctx.sessions                                        │
-│      │                                               │
-│      ├──── session lifecycle ───────┐                │
-│      │                              │                │
-│  ctx.llm                            │                │
-│      │                              │                │
-│      └──── llm/stream ──────────────┤                │
-│                                     ▼                │
-│                           KvPersistService           │
-│                          /        │        \          │
-│                         /         │         \         │
-│                  Coordinator   Metadata   Metrics     │
-│                       │                              │
-│                       ▼                              │
-│                 KvBackend interface                 │
-│                       │                              │
-│                       ▼                              │
-│                LlamaCppBackend                      │
-└───────────────────────┼──────────────────────────────┘
-                        │ HTTP
-                        ▼
-                 ┌───────────────┐
-                 │ llama-server  │
-                 │               │
-                 │ slot 0        │
-                 │ /slots API    │
-                 └───────┬───────┘
-                         │
-                         ▼
-                 --slot-save-path
-                         │
-        ┌────────────────┼────────────────┐
-        ▼                ▼                ▼
-   session-A.bin    session-B.bin    session-C.bin
-```
-
----
-
-# 10. Package layout
-
-Recommended repository structure:
-
-```text
-dsh-kv-persist/
-├─ src/
-│  ├─ index.ts
-│  ├─ config.ts
-│  ├─ service.ts
-│  │
-│  ├─ coordinator/
-│  │  ├─ coordinator.ts
-│  │  ├─ slot-lease.ts
-│  │  ├─ state-machine.ts
-│  │  └─ checkpoint-policy.ts
-│  │
-│  ├─ backends/
-│  │  ├─ types.ts
-│  │  └─ llama-cpp/
-│  │     ├─ backend.ts
-│  │     ├─ client.ts
-│  │     ├─ discovery.ts
-│  │     ├─ compatibility.ts
-│  │     └─ types.ts
-│  │
-│  ├─ snapshots/
-│  │  ├─ manifest.ts
-│  │  ├─ naming.ts
-│  │  ├─ fingerprint.ts
-│  │  └─ repository.ts
-│  │
-│  ├─ observability/
-│  │  ├─ metrics.ts
-│  │  └─ diagnostics.ts
-│  │
-│  └─ errors.ts
-│
-├─ test/
-│  ├─ unit/
-│  ├─ integration/
-│  └─ fixtures/
-│
-├─ cordis.patch.yml
-├─ package.json
-├─ tsconfig.json
-├─ README.md
-└─ SPEC.md
-```
-
-Do not put the entire implementation into `index.ts`.
-
----
-
-# 11. Public service
-
-The plugin SHOULD expose:
-
-```ts
-ctx.kvPersist
-```
-
-through a Cordis `Service`.
-
-Approximate API:
-
-```ts
-interface KvPersistService {
-  status(): Promise<KvPersistStatus>
-
-  getSessionState(
-    sessionId: string,
-  ): Promise<SessionKvState | undefined>
-
-  save(
-    sessionId: string,
-    options?: SaveOptions,
-  ): Promise<SnapshotResult>
-
-  restore(
-    sessionId: string,
-    options?: RestoreOptions,
-  ): Promise<RestoreResult>
-
-  invalidate(
-    sessionId: string,
-    reason?: string,
-  ): Promise<void>
-
-  purge(
-    sessionId: string,
-  ): Promise<void>
-
-  flush(): Promise<void>
-}
-```
-
-The service makes future UI/CLI plugins possible without depending directly on llama.cpp.
-
----
-
-# 12. Backend abstraction
-
-Core code must NOT contain direct `/slots` HTTP calls.
-
-Define:
-
-```ts
-interface KvPersistenceBackend {
-  readonly kind: string
-
-  probe(signal?: AbortSignal): Promise<BackendCapabilities>
-
-  inspectSlots(
-    signal?: AbortSignal,
-  ): Promise<BackendSlot[]>
-
-  saveSlot(
-    slotId: number,
-    snapshotKey: string,
-    signal?: AbortSignal,
-  ): Promise<BackendSaveResult>
-
-  restoreSlot(
-    slotId: number,
-    snapshotKey: string,
-    signal?: AbortSignal,
-  ): Promise<BackendRestoreResult>
-
-  eraseSlot(
-    slotId: number,
-    signal?: AbortSignal,
-  ): Promise<BackendEraseResult>
-}
-```
-
-Initial implementation:
-
-```text
-KvPersistenceBackend
-└── LlamaCppBackend
-```
-
-Potential future implementations:
-
-```text
-KvPersistenceBackend
-├── LlamaCppBackend
-├── SglangBackend
-├── VllmBackend
-└── CustomGatewayBackend
-```
-
----
-
-# 13. Snapshot identity
-
-A snapshot must never be identified by `sessionId` alone.
-
-Conceptual key:
-
-```text
-SnapshotKey =
-  server instance
-+ provider
-+ model
-+ DSH session
-+ compatibility generation
-```
-
-Example:
-
-```ts
-interface SnapshotIdentity {
-  sessionId: string
-
-  provider: string
-  model: string
-
-  backend: 'llama.cpp'
-
-  serverInstanceKey: string
-  modelFingerprint: string
-
-  compatibilityVersion: number
-}
-```
-
----
-
-# 14. Snapshot metadata
-
-The plugin keeps its own small metadata record independently from the potentially huge `.bin` file.
-
-Example:
-
-```json
-{
-  "schemaVersion": 1,
-
-  "sessionId": "01991d...",
-  "sessionSeq": 341,
-
-  "provider": "local-qwen",
-  "model": "Qwen3.8-27B-GSQ-RCO-IQ2_XS.gguf",
-
-  "backend": "llama.cpp",
-  "serverInstanceKey": "local-3060",
-  "serverEndpointHash": "sha256:...",
-
-  "modelFingerprint": "sha256:...",
-  "runtimeFingerprint": "sha256:...",
-
-  "slotId": 0,
-
-  "createdAt": "2026-08-29T20:00:00Z",
-  "updatedAt": "2026-08-29T20:42:00Z",
-
-  "tokens": 48321,
-  "bytes": 2384203912,
-
-  "snapshotFilename": "b3-c5-....bin",
-
-  "state": "ready"
-}
-```
-
----
-
-# 15. Runtime fingerprint
-
-Restoring arbitrary binary model state is dangerous.
-
-Snapshots should therefore have a compatibility fingerprint.
-
-Suggested fingerprint inputs:
-
-```text
-backend type
-llama.cpp server/build version, when discoverable
-model identifier
-model file fingerprint/configured model key
-context size
-KV K type
-KV V type
-parallel/slot geometry
-relevant recurrent/hybrid mode
-LoRA configuration
-speculative decoding configuration
-plugin snapshot schema generation
-```
-
-For values the server cannot expose reliably, configuration should allow an explicit:
-
-```yaml
-runtimeKey: qwen38-27b-iq2xs-ctx128k-q4kv-v1
-```
-
-Changing `runtimeKey` makes old snapshots invisible.
-
-This provides a simple manual escape hatch.
-
----
-
-# 16. Filename generation
-
-Raw session IDs or titles SHOULD NOT become filenames.
-
-Use:
-
-```text
-sha256(
-  backendInstanceKey +
-  provider +
-  model +
-  sessionId
-)
-```
-
-Example:
-
-```text
-7c/7c856dc594.........bin
-```
-
-Benefits:
-
-- fixed filename length;
-- no unsafe characters;
-- no path traversal;
-- no leaking chat titles;
-- no collisions in normal operation.
-
----
-
-# 17. Snapshot storage
-
-Important distinction:
-
-```text
-metadata storage
-≠
-KV binary storage
-```
-
-The KV binary is created by `llama-server` itself inside:
-
-```text
---slot-save-path
-```
-
-The DSH plugin may not even have filesystem access to that directory.
-
-Therefore the architecture must support:
-
-### Metadata
-
-Stored locally by the plugin:
-
-```text
-<DSH home>/cache/dsh-kv-persist/
-```
-
-### Binary
-
-Stored by llama-server:
-
-```text
-<LLAMA_SLOT_SAVE_PATH>/
-```
-
-The plugin communicates using only the generated filename.
-
-This allows:
-
-```text
-DSH in container A
-llama-server in container B
-```
-
-provided the server owns its snapshot directory.
-
----
-
-# 18. Session state machine
-
-Each session can be:
-
-```text
-NONE
-    no known snapshot
-
-COLD
-    session exists but no state loaded
-
-RESTORING
-    snapshot restore in progress
-
-ACTIVE_CLEAN
-    current server slot corresponds to snapshot
-
-ACTIVE_DIRTY
-    model has advanced beyond saved snapshot
-
-SAVING
-    persistence operation in progress
-
-SAVED
-    latest runtime state has durable snapshot
-
-INVALID
-    snapshot exists but is incompatible/corrupted
-```
-
-Typical transitions:
-
-```text
-NONE
- ↓ first request
-COLD
- ↓ normal prefill
-ACTIVE_DIRTY
- ↓ checkpoint
-SAVING
- ↓
-SAVED
-```
-
-Resume:
-
-```text
-SAVED
- ↓ session request
-RESTORING
- ↓
-ACTIVE_CLEAN
- ↓ inference
-ACTIVE_DIRTY
-```
-
-Session switch:
-
-```text
-A ACTIVE_DIRTY
- ↓
-save A
- ↓
-A SAVED
- ↓
-restore B
- ↓
-B ACTIVE_CLEAN
-```
-
----
-
-# 19. Slot state
-
-The coordinator separately tracks the physical slot.
-
-```ts
-interface ManagedSlot {
-  id: number
-
-  ownerSessionId?: string
-
-  snapshotRevision?: string
-
-  state:
-    | 'unknown'
-    | 'idle'
-    | 'restoring'
-    | 'ready'
-    | 'inference'
-    | 'dirty'
-    | 'saving'
-    | 'broken'
-
-  lastUsedAt?: number
-}
-```
-
-For v0.1 there is simply:
-
-```ts
-slot[0]
-```
-
----
-
-# 20. Critical concurrency rule
-
-No two operations may concurrently mutate the same llama slot.
-
-The following must share one lock:
-
-```text
-restore
-erase
-inference
-save
-```
-
-For MVP:
-
-```ts
-serverMutex.runExclusive(...)
-```
-
-is sufficient.
-
-Conceptually:
-
-```text
-acquire slot lease
-      ↓
-prepare slot
-      ↓
-run inference
-      ↓
-update dirty state
-      ↓
-optional checkpoint
-      ↓
-release slot lease
-```
-
-This lock is absolutely critical.
-
-Without it:
-
-```text
-session A restoring
-        +
-session B starting request
-        =
-undefined cache ownership
-```
-
----
-
-# 21. Request interception
-
-The plugin listens to:
-
-```text
-llm/stream
-```
-
-For each request:
-
-```ts
-if (!isManagedProvider(options.provider)) {
-  return next()
-}
-
-if (!options.sessionId) {
-  return handleAuxiliaryRequest(...)
-}
-
-return coordinator.runSessionRequest({
-  sessionId: options.sessionId,
-  provider: options.provider,
-  model: options.model,
-  purpose: options.purpose,
-  next,
-})
-```
-
-`llm/stream` is an appropriate seam because it wraps every actual streaming model invocation, including adapter dispatch.
-
----
-
-# 22. Auxiliary requests
-
-DSH may make model calls for:
-
-```text
-session-title
-compaction
-other future purposes
-```
-
-They can pollute slot 0.
-
-Therefore they must explicitly participate in coordination.
-
-Default:
-
-```yaml
-auxiliaryRequests: isolate
-```
-
-In single-slot mode:
-
-```text
-main session dirty
-   ↓
-save current main session
-   ↓
-auxiliary request
-   ↓
-slot becomes unowned
-   ↓
-next main request restores its snapshot
-```
-
-Do NOT accidentally assign an auxiliary request to the currently active DSH session snapshot.
-
-`GenerateOptions.purpose` exists specifically to identify current auxiliary call categories.
-
----
-
-# 23. Restore algorithm
-
-Pseudo-code:
-
-```ts
-async function prepareSession(sessionId, route) {
-  const slot = slot0
-
-  if (
-    slot.ownerSessionId === sessionId &&
-    slot.state !== 'broken'
-  ) {
-    return { kind: 'already-active' }
-  }
-
-  if (slot.ownerSessionId) {
-    await checkpointIfNeeded(slot.ownerSessionId)
-  }
-
-  const snapshot = await repository.findCompatible(
-    sessionId,
-    route,
-  )
-
-  if (!snapshot) {
-    await backend.eraseSlot(slot.id)
-
-    slot.ownerSessionId = sessionId
-    slot.state = 'idle'
-
-    return { kind: 'cold' }
-  }
-
-  try {
-    const result = await backend.restoreSlot(
-      slot.id,
-      snapshot.filename,
-    )
-
-    verifyRestore(result, snapshot)
-
-    slot.ownerSessionId = sessionId
-    slot.state = 'ready'
-
-    return {
-      kind: 'restored',
-      tokens: result.tokens,
-      bytes: result.bytes,
-      durationMs: result.durationMs,
-    }
-  } catch (error) {
-    markSnapshotInvalid(snapshot, error)
-
-    await backend.eraseSlot(slot.id)
-
-    slot.ownerSessionId = sessionId
-    slot.state = 'idle'
-
-    return {
-      kind: 'cold-fallback',
-      error,
-    }
-  }
-}
-```
-
-The key policy:
-
-> Restore failure is never fatal to ordinary inference unless strict mode is explicitly enabled.
-
----
-
-# 24. Post-restore validation
-
-An HTTP `200` from llama.cpp is not enough.
-
-The plugin should validate:
-
-```text
-n_restored > 0
-expected snapshot existed
-slot endpoint remains healthy
-reported token count is plausible
-```
-
-Optionally inspect:
-
-```text
-GET /slots
-```
-
-after restore.
-
-For hybrid/recurrent models, introduce:
-
-```yaml
-restoreVerification: strict
-```
-
-which can require slot state to reflect restored token count before considering restore successful.
-
-This is useful because persistent state support can vary by llama.cpp model architecture/build.
-
----
-
-# 25. Inference algorithm
-
-After preparing the slot:
-
-```text
-slot owner = session
-        ↓
-call downstream LLM adapter
-        ↓
-consume stream normally
-        ↓
-terminal successful finish
-        ↓
-mark slot dirty
-```
-
-Important:
-
-The plugin MUST preserve streaming.
-
-It must not buffer the full model response merely to implement persistence.
-
-Conceptually:
-
-```ts
-const downstream = next()
-
-return async function* () {
-  let succeeded = false
-
-  try {
-    for await (const chunk of downstream) {
-      if (
-        chunk.type === 'finish' &&
-        chunk.reason.kind !== 'error' &&
-        chunk.reason.kind !== 'aborted'
-      ) {
-        succeeded = true
-      }
-
-      yield chunk
-    }
-  } finally {
-    if (succeeded) {
-      markDirty(sessionId)
-    }
-  }
-}
-```
-
-Care must be taken with Cordis waterfall semantics: resolve `next()` at the correct point and don't accidentally call a consumed waterfall continuation lazily.
-
----
-
-# 26. Checkpoint strategy
-
-Saving a multi-gigabyte KV file after every generation can destroy the performance win.
-
-Therefore checkpointing must be configurable.
-
-Supported strategies:
-
-```text
-switch
-turn
-step
-idle
-shutdown
-manual
-```
-
-### `switch`
-
-Save only when the physical slot must be reassigned.
-
-This should be the primary default.
-
-Example:
-
-```text
-A → A → A → A
-```
-
-No disk writes.
-
-Then:
-
-```text
-A → B
-```
-
-causes one save of A.
-
-### `turn`
-
-Persist after every completed user turn.
-
-Higher durability, much more disk I/O.
-
-### `step`
-
-Persist after every successful agent model step.
-
-Useful for crash-sensitive long autonomous jobs.
-
-Potentially very expensive.
-
-### `idle`
-
-Save dirty state after N seconds without another request.
-
-Recommended:
-
-```yaml
-idleCheckpointMs: 30000
-```
-
-### `shutdown`
-
-Attempt a final checkpoint during normal Cordis disposal.
-
-### Recommended default
-
-```text
-switch + idle + shutdown
-```
-
-This provides a good balance between speed and durability.
-
----
-
-# 27. Checkpoint coalescing
-
-Multiple save requests for the same revision should collapse.
-
-Example:
-
-```text
-turn/end
-idle timer
-session/flush
-plugin shutdown
-```
-
-may all happen near one another.
-
-Use:
-
-```ts
-interface SaveGeneration {
-  dirtyRevision: number
-  persistedRevision: number
-  inFlight?: Promise<SnapshotResult>
-}
-```
-
-If:
-
-```text
-dirtyRevision === persistedRevision
-```
-
-do nothing.
-
-If a save is already running for the current revision:
-
-```text
-await existing save
-```
-
-rather than starting another.
-
----
-
-# 28. Dirty generations
-
-Never use a single boolean if avoidable.
-
-Use monotonic generations:
-
-```text
-dirtyRevision = 31
-savedRevision = 30
-```
-
-Then:
-
-```text
-dirtyRevision > savedRevision
-```
-
-means dirty.
-
-If inference completes while a save is in progress:
-
-```text
-save revision 30
-new inference → revision 31
-save finishes
-savedRevision = 30
-```
-
-and state correctly remains dirty.
-
----
-
-# 29. Session sequence tracking
-
-Snapshot metadata SHOULD include the latest known DSH:
-
-```text
-session.seq
-```
-
-Example:
-
-```json
-{
-  "sessionSeq": 482
-}
-```
-
-This does NOT mean KV state is equivalent to every event through seq 482.
-
-It is primarily:
-
-- diagnostic metadata;
-- freshness information;
-- useful for invalidation;
-- useful for future exact request fingerprinting.
-
----
-
-# 30. Prompt/request fingerprints
-
-Future versions SHOULD record a fingerprint of the request that produced the snapshot.
-
-Conceptually:
-
-```text
-hash(
-  provider
-  model
-  system prompt
-  normalized messages
-  tool schemas
-  relevant template configuration
-)
-```
-
-However this SHOULD NOT be mandatory in v0.1.
-
-Why?
-
-Because llama.cpp itself compares the restored prompt cache with the next incoming prompt and can reuse the common prefix while processing the changed suffix.
-
-The plugin mainly needs to prevent gross incompatibility.
-
----
-
-# 31. Snapshot invalidation
-
-Snapshots must become invalid when any important runtime identity changes.
-
-Examples:
-
-```text
-model changed
-model GGUF replaced
-KV layout changed
-runtimeKey changed
-llama backend changed
-LoRA changed
-server instance changed incompatibly
-snapshot restore failed
-manifest malformed
-snapshot file missing
-```
-
-Invalidation must NOT delete data immediately.
-
-Prefer:
-
-```text
-state = invalid
-reason = MODEL_FINGERPRINT_CHANGED
-```
-
-Cleanup can happen separately.
-
----
-
-# 32. Failure policy
-
-Persistence is an optimization.
-
-Default failure behavior:
-
-```text
-save failed
-→ log warning
-→ continue session
-
-restore failed
-→ mark snapshot invalid
-→ erase slot
-→ cold prefill
-→ continue session
-
-server /slots unavailable
-→ disable persistence temporarily
-→ continue ordinary inference
-```
-
-Only configuration:
-
-```yaml
-strict: true
-```
-
-should turn persistence failure into request failure.
-
-Default:
-
-```yaml
-strict: false
-```
-
----
-
-# 33. Circuit breaker
-
-If llama slot persistence is broken, we don't want every request to waste seconds retrying it.
-
-Backend state:
-
-```text
-HEALTHY
-DEGRADED
-OPEN
-HALF_OPEN
-```
-
-Suggested behavior:
-
-```text
-3 consecutive persistence failures
-→ disable save/restore for 60s
-
-after 60s
-→ probe
-
-probe successful
-→ resume
-
-probe fails
-→ backoff
-```
-
-Inference itself remains active.
-
----
-
-# 34. Backend health probe
-
-At plugin initialization:
-
-```text
-GET /slots
-```
-
-Validate:
-
-```text
-server reachable
-slots endpoint available
-expected slot count
-slot 0 exists for single-slot mode
-```
-
-Optionally test persistence capability using a non-destructive mechanism where possible.
-
-The plugin SHOULD clearly distinguish:
-
-```text
-LLM endpoint alive
-```
-
-from:
-
-```text
-KV persistence supported
-```
-
----
-
-# 35. Configuration
-
-Initial configuration proposal:
-
-```yaml
-kv-persist:
-  enabled: true
-
-  backend:
-    type: llama.cpp
-    baseURL: http://127.0.0.1:8080
-
-  providers:
-    - local-qwen
-
-  mode: single-slot
-  slotId: 0
-
-  runtimeKey: qwen38-27b-iq2xs-ctx128k-q4kv
-
-  checkpoint:
-    onSwitch: true
-    onShutdown: true
-    onSessionFlush: true
-
-    idleMs: 30000
-
-    onTurnEnd: false
-    onStepEnd: false
-
-  restore:
-    enabled: true
-    verify: true
-
-  failure:
-    strict: false
-    maxConsecutiveFailures: 3
-    cooldownMs: 60000
-
-  metadata:
-    path: ${DSH_HOME}/cache/dsh-kv-persist
-
-  logging:
-    level: info
-```
-
----
-
-# 36. Config schema
-
-Using Schemastery-style validation:
-
-```ts
-interface Config {
-  enabled?: boolean
-
-  backend: {
-    type: 'llama.cpp'
-    baseURL: string
-    apiKey?: string
-    requestTimeoutMs?: number
-  }
-
-  providers?: string[]
-
-  mode?: 'single-slot' | 'managed-slots'
-
-  slotId?: number
-
-  runtimeKey?: string
-
-  checkpoint?: {
-    onSwitch?: boolean
-    onShutdown?: boolean
-    onSessionFlush?: boolean
-
-    idleMs?: number
-
-    onTurnEnd?: boolean
-    onStepEnd?: boolean
-  }
-
-  restore?: {
-    enabled?: boolean
-    verify?: boolean
-  }
-
-  failure?: {
-    strict?: boolean
-    maxConsecutiveFailures?: number
-    cooldownMs?: number
-  }
-
-  metadata?: {
-    path?: string
-  }
-}
-```
-
-Recommended defaults:
-
-```text
-enabled = true
-
-mode = single-slot
-slotId = 0
-
-onSwitch = true
-onShutdown = true
-onSessionFlush = true
-idleMs = 30000
-
-onTurnEnd = false
-onStepEnd = false
-
-restore.enabled = true
-restore.verify = true
-
-strict = false
-```
-
----
-
-# 37. Automatic provider filtering
-
-The plugin MUST NOT touch cloud providers by default.
-
-Example:
-
-```yaml
-providers:
-  - local-qwen
-  - local-coder
-```
-
-A request to:
-
-```text
-deepseek
-openai
-anthropic
-```
-
-passes straight through.
-
-Future configuration may support:
-
-```yaml
-providers:
-  local-qwen:
-    backend: local-llama
-```
-
-for multiple servers.
-
----
-
-# 38. Multiple llama servers
-
-Architecture should support this eventually:
-
-```yaml
-servers:
-  rtx3060:
-    type: llama.cpp
-    baseURL: http://127.0.0.1:8080
-    runtimeKey: qwen38
-
-  rtx4090:
-    type: llama.cpp
-    baseURL: http://192.168.1.42:8080
-    runtimeKey: qwen-coder
-
-routes:
-  local-qwen:
-    server: rtx3060
-
-  local-coder:
-    server: rtx4090
-```
-
-Internally:
-
-```text
-Coordinator
-    ↓
-ServerRuntime[]
-    ↓
-independent slot pools + locks
-```
-
-Do not use one global mutex across different servers.
-
----
-
-# 39. Metadata repository
-
-Default path (shared DSH home convention; a non-blank `$DSH_HOME` wins,
-otherwise DSH home is `~/.dsh`):
-
-```text
-$DSH_HOME/cache/dsh-kv-persist/
-```
-
-Layout:
-
-```text
-dsh-kv-persist/
-├─ instances/
-│  └─ local-3060/
-│     └─ sessions/
-│        ├─ 7c856d....json
-│        └─ d084fd....json
-│
-├─ index.json
-└─ plugin-state.json
-```
-
-Binary KV files SHOULD NOT be copied here automatically.
-
----
-
-# 40. Atomic metadata writes
-
-Manifest updates should use:
-
-```text
-write temp
-fsync/close
-rename
-```
-
-rather than overwriting JSON directly.
-
-Example:
-
-```text
-session.json.tmp
-      ↓
-rename
-      ↓
-session.json
-```
-
-A crash must not leave half-written metadata treated as valid.
-
----
-
-# 41. Snapshot naming generations
-
-Default strategy:
-
-```text
-one rolling snapshot per session
-```
-
-rather than:
-
-```text
-snapshot-000001.bin
-snapshot-000002.bin
-snapshot-000003.bin
-...
-```
-
-because KV snapshots can be enormous.
-
-Conceptually:
-
-```text
-<sessionHash>.bin
-```
-
-If llama.cpp cannot safely atomically replace an existing file in a particular build/backend, support two rotating names:
-
-```text
-<hash>.a.bin
-<hash>.b.bin
-```
-
-Manifest points to the latest completed generation.
-
-This prevents an interrupted write from destroying the previous valid checkpoint.
-
----
-
-# 42. Local vs remote server cleanup
-
-The llama slots API manages save/restore/erase of slot state, but binary file lifecycle may not always be remotely manageable.
-
-Therefore define:
-
-```text
-snapshotBinaryManagement:
-  server-owned
-  shared-filesystem
-```
-
-### `server-owned`
-
-Plugin only knows filenames.
-
-No direct delete.
-
-Use rolling filenames to limit growth.
-
-### `shared-filesystem`
-
-Plugin is configured with the same physical save directory and may:
-
-- inspect file size;
-- delete invalid snapshots;
-- enforce disk quota;
-- perform atomic rotation.
-
-This mode MUST be opt-in.
-
----
-
-# 43. Disk quota
-
-Future version:
-
-```yaml
-retention:
-  maxTotalBytes: 100GB
-  maxSessions: 50
-  maxAgeDays: 30
-```
-
-Eviction policy:
-
-```text
-invalid first
-then oldest unused
-then LRU
-```
-
-Never remove the active slot state as part of disk cleanup.
-
-Only stored snapshots.
-
----
-
-# 44. Security
-
-The plugin MUST assume the llama management endpoint is privileged.
-
-Recommended setup:
-
-```text
-127.0.0.1
-or
-trusted private network
-or
-authenticated reverse proxy
-```
-
-Do not expose slot management APIs publicly.
-
-Snapshot filenames must be generated by the plugin and sanitized.
-
-Never accept:
-
-```text
-../../foo
-C:\whatever
-/etc/passwd
-```
-
-as a raw snapshot filename.
-
-Only backend-generated opaque keys may reach:
-
-```text
-action=save
-action=restore
-```
-
----
-
-# 45. Logging
-
-Recommended structured events:
-
-```text
-kv.backend.ready
-kv.backend.unavailable
-
-kv.slot.acquire
-kv.slot.release
-
-kv.session.cold
-kv.session.restore.start
-kv.session.restore.success
-kv.session.restore.failed
-
-kv.session.save.start
-kv.session.save.success
-kv.session.save.failed
-
-kv.session.switch
-
-kv.snapshot.invalidated
-
-kv.persistence.circuit_open
-kv.persistence.circuit_recovered
-```
-
-Example:
-
-```text
-[kv-persist] restored
-session=7c856d
-slot=0
-tokens=48192
-bytes=2.31GiB
-duration=418ms
-```
-
-Avoid logging full session IDs at normal verbosity if unnecessary.
-
-Use abbreviated hashes.
-
----
-
-# 46. Metrics
-
-Expose internal counters through the service and later optional Prometheus integration:
-
-```text
-dsh_kv_restore_total
-dsh_kv_restore_hit_total
-dsh_kv_restore_miss_total
-dsh_kv_restore_failure_total
-
-dsh_kv_save_total
-dsh_kv_save_failure_total
-
-dsh_kv_restore_bytes_total
-dsh_kv_save_bytes_total
-
-dsh_kv_restore_duration_ms
-dsh_kv_save_duration_ms
-
-dsh_kv_cold_prefill_total
-
-dsh_kv_slot_switch_total
-
-dsh_kv_snapshot_count
-dsh_kv_snapshot_bytes
-```
-
-Especially useful derived metric:
-
-```text
-persistent-cache restore hit rate
-```
-
----
-
-# 47. Diagnostics API
-
-`ctx.kvPersist.status()` should return something like:
-
-```json
-{
-  "enabled": true,
-  "backend": {
-    "kind": "llama.cpp",
-    "state": "healthy",
-    "endpoint": "http://127.0.0.1:8080"
-  },
-
-  "mode": "single-slot",
-
-  "slots": [
-    {
-      "id": 0,
-      "owner": "7c856d",
-      "state": "dirty"
-    }
-  ],
-
-  "snapshots": {
-    "known": 14,
-    "valid": 13,
-    "invalid": 1
-  },
-
-  "stats": {
-    "restores": 23,
-    "restoreHits": 21,
-    "coldStarts": 2,
-    "saves": 18
-  }
-}
-```
-
----
-
-# 48. Optional CLI
-
-Eventually expose human-facing commands:
-
-```text
-dsh kv status
-dsh kv list
-dsh kv save <session>
-dsh kv restore <session>
-dsh kv invalidate <session>
-dsh kv purge <session>
-dsh kv gc
-dsh kv doctor
-```
-
-`doctor` should be particularly useful.
-
-Example:
-
-```text
-$ dsh kv doctor
-
-Backend: llama.cpp
-Endpoint: http://127.0.0.1:8080
-Slots API: OK
-Slots: 1
-Configured mode: single-slot
-Slot 0: idle
-Save path capability: OK
-Restore verification: OK
-Hybrid model persistence: unverified
-Metadata directory: writable
-Result: READY
-```
-
----
-
-# 49. No model-facing tool by default
-
-Do NOT register:
-
-```text
-save_kv_cache
-restore_kv_cache
-```
-
-with `ctx.tools`.
-
-There is almost no reason for the LLM itself to manage its infrastructure cache.
-
-It wastes tool schema tokens and introduces failure modes such as:
-
-```text
-model decides to purge its own cache
-```
-
-Management belongs to:
-
-```text
-plugin
-user CLI
-UI
-```
-
-not to the model.
-
----
-
-# 50. Session lifecycle integration
-
-Subscribe to session lifecycle for:
-
-```text
-session created
-session flush
-session disposed
-turn end
-```
-
-Use these events as persistence hints.
-
-DSH explicitly exposes session persistence hooks and `session/flush` as the durability checkpoint seam.
-
-Recommended semantics:
-
-### session created/resumed
-
-Do not restore immediately.
-
-Lazy restore on first actual LLM request.
-
-Reason:
-
-```text
-opening a chat in UI
-```
-
-should not evict another active KV session unless inference actually occurs.
-
-### session flush
-
-If the session currently owns a dirty slot:
-
-```text
-checkpoint
-```
-
-### session disposed
-
-If dirty:
-
-```text
-checkpoint if configured
-```
-
-then remove runtime ownership.
-
-### turn/end
-
-Checkpoint only when:
-
-```yaml
-checkpoint.onTurnEnd: true
-```
-
----
-
-# 51. Lazy restore
-
-This is important enough to be explicit.
-
-Bad:
-
-```text
-user clicks session B
-→ immediately save A
-→ restore 3GB B
-→ user clicks session C
-→ immediately save B
-→ restore C
-```
-
-Good:
-
-```text
-user clicks session B
-→ nothing
-
-user actually sends message in B
-→ switch slot
-```
-
-Snapshot management follows inference, not UI navigation.
-
----
-
-# 52. Save-before-evict invariant
-
-Before assigning a dirty slot to another owner:
-
-```text
-MUST attempt save
-```
-
-unless configured:
-
-```yaml
-checkpoint.onSwitch: false
-```
-
-Default invariant:
-
-```text
-dirty A
-+
-need B
-=
-save A before erase/restore B
-```
-
-This is the core of session switching.
-
----
-
-# 53. Cold-session behavior
-
-If no snapshot exists:
-
-```text
-erase slot
-assign owner
-let llama.cpp process full request
-mark dirty
-```
-
-Do not try to build a snapshot before inference.
-
-Snapshot will naturally be created by the next checkpoint.
-
----
-
-# 54. Snapshot restore and prompt divergence
-
-A restored KV snapshot is not assumed to perfectly equal the next DSH request.
-
-Example:
-
-Snapshot:
-
-```text
-system
-A
-assistant A
-B
-assistant B
-```
-
-Current request:
-
-```text
-system
-A
-assistant A
-B
-assistant B
-C
-```
-
-Ideal outcome:
-
-```text
-reuse existing prefix
-process only C
-```
-
-If the system prompt/tool schema changed:
-
-```text
-old prefix
-    ↓
-divergence detected by llama.cpp
-    ↓
-recompute changed suffix
-```
-
-Thus plugin-side fingerprints are mainly for runtime compatibility and diagnostics rather than replacing llama.cpp's prompt matching.
-
----
-
-# 55. Context compaction
-
-Compaction changes model-visible history substantially.
-
-The plugin does not need special correctness logic.
-
-After compaction:
-
-```text
-restored old snapshot
-        ↓
-incoming compacted prompt differs
-        ↓
-llama.cpp finds smaller common prefix
-        ↓
-new prompt is processed
-        ↓
-slot becomes dirty
-        ↓
-next checkpoint replaces snapshot
-```
-
-However the plugin should emit diagnostics:
-
-```text
-large restored cache
-low subsequent cache reuse
-possible compaction/prompt mutation
-```
-
-Future versions can proactively invalidate on known compaction events.
-
----
-
-# 56. Provider/model changes inside a session
-
-DSH allows the request route to change between steps.
-
-Therefore one DSH session can theoretically contain:
-
-```text
-model A
-→ model B
-→ model A
-```
-
-KV identity must therefore include:
-
-```text
-provider + model
-```
-
-not only session.
-
-Conceptually:
-
-```text
-session X
-├─ qwen snapshot
-└─ coder snapshot
-```
-
-MVP may simplify by allowing one current snapshot per:
-
-```text
-(session, provider, model)
-```
-
----
-
-# 57. LoRA and runtime mutations
-
-If llama-server changes:
-
-```text
-LoRA
-model
-chat template
-KV representation
-other state that affects serialized cache
-```
-
-the runtime fingerprint must change or snapshots must be invalidated.
-
-Never silently restore across obviously different model states.
-
----
-
-# 58. Plugin lifecycle
-
-Cordis plugins may be unloaded through configuration changes, HMR, explicit disposal, or loss of dependencies; resources external to Cordis should be tied to `ctx.effect()` and cleaned on unload.
-
-The plugin should therefore register:
-
-```text
-timers
-HTTP resources
-backend lifecycle
-shutdown save
-```
-
-through proper Cordis effects.
-
-On dispose:
-
-```text
-stop accepting new persistence work
-        ↓
-cancel idle timers
-        ↓
-wait for/abort safe pending operations
-        ↓
-checkpoint active dirty slot if configured
-        ↓
-dispose service
-```
-
----
-
-# 59. Cancellation
-
-User cancellation of generation MUST NOT be blocked by a slow snapshot write.
-
-Inference `AbortSignal` belongs to inference.
-
-Persistence operations should use their own bounded timeout.
-
-For example:
-
-```yaml
-backend:
-  requestTimeoutMs: 15000
-```
-
-If save exceeds timeout:
-
-```text
-log
-mark persistence degraded
-release workflow
-```
-
-Don't leave the agent permanently stuck because an NVMe/cache filesystem is unhappy.
-
----
-
-# 60. Crash semantics
-
-There are three relevant crashes:
-
-### DSH crashes
-
-llama-server remains alive.
-
-Active slot may still contain valid state.
-
-v0.1 may ignore this unsaved in-memory opportunity and restore the last durable snapshot.
-
-Future optimization:
-
-```text
-inspect current slot metadata
-re-associate if ownership can be proven
-```
-
-### llama-server crashes
-
-Only durable snapshots survive.
-
-After restart:
-
-```text
-probe
-restore snapshot
-```
-
-### Machine crashes during snapshot save
-
-Manifest must continue referencing the previous known-good generation.
-
-This is why two-file rotation may eventually be useful.
-
----
-
-# 61. Hybrid/recurrent model compatibility
-
-Qwen3.x hybrid/recurrent architectures make this especially important.
-
-Define compatibility states:
-
-```text
-supported
-experimental
-broken
-unknown
-```
-
-Example metadata:
-
-```json
-{
-  "persistenceCompatibility": "experimental"
-}
-```
-
-`dsh kv doctor` can perform an opt-in verification:
-
-```text
-1. cold prompt
-2. save
-3. erase
-4. restore
-5. inspect
-6. identical prompt
-7. confirm cache reuse
-```
-
-An even stronger test:
-
-```text
-save
-restart server manually
-restore
-same prompt
-verify hit
-```
-
-The plugin should never assume that receiving `n_restored` means a particular model/build definitely restored usable recurrent state.
-
----
-
-# 62. Compatibility database
-
-Future versions may contain small rules:
-
-```ts
-interface CompatibilityRule {
-  backend: 'llama.cpp'
-  architecture?: string
-  minBuild?: number
-  maxBuild?: number
-  status: 'supported' | 'experimental' | 'broken'
-  note?: string
-}
-```
-
-But avoid hardcoding large brittle version tables initially.
-
-Prefer runtime verification.
-
----
-
-# 63. Multi-slot architecture
-
-After MVP, support:
-
-```text
---parallel N
-```
-
-with a real slot pool.
-
-Example N=4:
-
-```text
-slot 0 → session A
-slot 1 → session B
-slot 2 → session C
-slot 3 → session D
-```
-
-Session E arrives:
-
-```text
-choose LRU clean/dirty slot
-        ↓
-save old owner if dirty
-        ↓
-restore E
-        ↓
-bind slot to E
-```
-
----
-
-# 64. Multi-slot slot selection
-
-Selection order:
-
-```text
-1. slot already owned by requested session
-2. empty slot
-3. clean least-recently-used slot
-4. dirty least-recently-used slot
-```
-
-Evicting a dirty slot requires save.
-
-Pseudo-code:
-
-```ts
-function selectSlot(sessionId) {
-  return (
-    ownedBy(sessionId) ??
-    emptySlot() ??
-    lruClean() ??
-    lruDirty()
-  )
-}
-```
-
----
-
-# 65. Multi-slot transport
-
-For managed multi-slot support, introduce:
-
-```text
-dsh-llama.cpp adapter
-```
-
-or a transport backend capable of injecting:
-
-```json
-{
-  "id_slot": 2,
-  "cache_prompt": true
-}
-```
-
-into llama-server requests.
-
-Potential package architecture:
-
-```text
-dsh-kv-persist
-└─ coordination/service
-
-dsh-llm-llama-cpp
-└─ llama-specific transport
-```
-
-The two can communicate through:
-
-```text
-ctx.kvPersist
-```
-
-This is preferable to making the persistence plugin own all OpenAI serialization logic.
-
----
-
-# 66. Alternative multi-slot sidecar
-
-Another possible backend:
-
-```text
-DSH
- ↓
-normal OpenAI adapter
- ↓
-local KV-aware reverse proxy
- ↓
-llama-server
-```
-
-Proxy receives a hidden session identifier and injects:
-
-```text
-id_slot
-```
-
-This is useful if DSH's adapter layer remains intentionally provider-neutral.
-
-However a native adapter is probably cleaner.
-
----
-
-# 67. Future upstream opportunity
-
-Potential DSH upstream proposal:
-
-```ts
-GenerateOptions.transportMetadata?
-```
-
-or an adapter-private request context carrying:
-
-```text
-sessionId
-```
-
-all the way into adapters.
-
-DSH already provides `sessionId` as model-hidden routing metadata, so a llama-specific adapter can naturally use that for slot assignment without exposing it to the model.
-
-Avoid adding llama-specific fields to core DSH vocabulary.
-
----
-
-# 68. MVP scope — v0.1
-
-The first usable release should contain only:
-
-```text
-llama.cpp backend
-single server
-single slot
-explicit managed provider list
-sessionId → snapshot mapping
-save on switch
-idle save
-save on shutdown/flush
-lazy restore
-restore fallback
-metadata manifests
-global slot mutex
-logging
-status API
-basic doctor/probe
-```
-
-Explicitly NOT in v0.1:
-
-```text
-multi-slot
-UI
-disk GC
-multiple servers
-snapshot migration
-Prometheus
-custom adapter
-automatic server startup
-```
-
-Keep v0.1 small enough to actually ship.
-
----
-
-# 69. v0.1 request flow
-
-Example: first ever session A request.
-
-```text
-DSH llm/stream(A)
-        ↓
-plugin sees managed provider
-        ↓
-acquire slot 0
-        ↓
-no current owner
-        ↓
-no snapshot A
-        ↓
-erase slot
-        ↓
-owner = A
-        ↓
-next()
-        ↓
-llama processes prompt
-        ↓
-stream response
-        ↓
-mark A dirty
-        ↓
-release
-```
-
-Second request A:
-
-```text
-llm/stream(A)
-        ↓
-slot already belongs to A
-        ↓
-no save/restore
-        ↓
-next()
-        ↓
-normal in-memory cache hit
-```
-
-This is very important:
-
-> The plugin must not save/restore when the requested session is already resident.
-
-Persistence must not make the happy path slower.
-
----
-
-# 70. v0.1 session switch
-
-A → B:
-
-```text
-request B
-   ↓
-acquire slot
-   ↓
-slot owner = A, A dirty
-   ↓
-save A.bin
-   ↓
-mark A saved
-   ↓
-find B snapshot
-   ↓
-restore B.bin
-   ↓
-owner = B
-   ↓
-request B
-```
-
-B → A:
-
-```text
-save B if dirty
-restore A
-run A
-```
-
----
-
-# 71. v0.1 idle save
-
-After request A finishes:
-
-```text
-A dirty
-   ↓
-start/reset 30s timer
-```
-
-If another A request comes within 30 seconds:
-
-```text
-cancel/reset timer
-```
-
-If idle timer fires:
-
-```text
-acquire slot
-   ↓
-confirm slot still owned by A
-   ↓
-confirm same dirty generation
-   ↓
-save
-   ↓
-release
-```
-
-Never save based purely on an old timer callback without rechecking ownership.
-
----
-
-# 72. v0.1 auxiliary request flow
-
-Suppose A is active and DSH starts session-title generation.
-
-```text
-A dirty
-   ↓
-aux request detected
-   ↓
-save A
-   ↓
-slot owner cleared
-   ↓
-run title request
-   ↓
-slot owner = auxiliary/unowned
-```
-
-Next A request:
-
-```text
-restore A
-```
-
-This is slower than having a separate aux slot but correct.
-
-v0.2 multi-slot can reserve:
-
-```text
-slot N-1 = auxiliary
-```
-
----
-
-# 73. Performance targets
-
-MVP should add almost zero overhead when a session remains resident.
-
-Resident request overhead target:
-
-```text
-< 1 ms plugin CPU overhead
-0 disk I/O
-0 extra llama management calls
-```
-
-Session restore cost is dominated by backend I/O.
-
-The plugin should record:
-
-```text
-save latency
-restore latency
-bytes
-tokens
-```
-
-so the user can compare:
-
-```text
-cold prefill time
-vs
-restore time
-```
-
----
-
-# 74. Acceptance criteria for v0.1
-
-Release `0.1.0` is acceptable when all of the following work:
-
-1. Start llama-server with slot save path.
-2. Start DSH with plugin.
-3. Open session A.
-4. Send large prompt.
-5. Slot becomes owned by A.
-6. Send another A turn.
-7. No disk save/restore occurs.
-8. Switch to session B.
-9. A is saved automatically.
-10. B runs.
-11. Switch back to A.
-12. A snapshot is restored.
-13. Next request demonstrates substantial prompt-cache reuse.
-14. Restart DSH.
-15. Open A and send another message.
-16. Plugin restores A snapshot.
-17. Conversation remains correct if snapshot file is manually deleted.
-18. Conversation remains correct if restore returns an error.
-19. Unmanaged providers are completely unaffected.
-20. Plugin hot unload cleans timers/resources.
-
----
-
-# 75. Integration tests
-
-Minimum integration test suite:
-
-### Cold start
-
-```text
-snapshot absent
-→ request succeeds
-→ state dirty
-```
-
-### Resident reuse
-
-```text
-A request
-A request
-→ no save
-→ no restore
-```
-
-### Switch
-
-```text
-A
-B
-→ save A
-```
-
-### Restore
-
-```text
-A
-B
-A
-→ restore A
-```
-
-### Corrupt snapshot
-
-```text
-restore fails
-→ snapshot invalidated
-→ cold request succeeds
-```
-
-### Backend unavailable
-
-```text
-/slots unreachable
-→ ordinary LLM request still works
-```
-
-### Save failure
-
-```text
-save A fails
-→ B still eventually runs in non-strict mode
-```
-
-### Auxiliary request
-
-```text
-A
-session-title
-A
-→ no incorrect slot ownership
-```
-
-### Cancellation
-
-```text
-cancel model request
-→ lock released
-→ next session still works
-```
-
-### HMR/disposal
-
-```text
-reload plugin
-→ no orphan timer
-→ no dead mutex
-```
-
----
-
-# 76. Unit tests
-
-Unit test:
-
-```text
-state-machine transitions
-slot selection
-snapshot compatibility
-filename sanitization
-fingerprint stability
-dirty revision logic
-save coalescing
-idle timer invalidation
-failure circuit breaker
-manifest atomicity
-provider filtering
-```
-
-No network should be necessary for these.
-
----
-
-# 77. Fake backend
-
-Create:
-
-```ts
-class FakeKvBackend
-```
-
-with deterministic state.
-
-Example capabilities:
-
-```ts
-backend.failNextSave()
-backend.failNextRestore()
-backend.delayRestore(100)
-backend.removeSnapshot(key)
-backend.corruptSnapshot(key)
-```
-
-Most coordinator tests should run against this rather than launching llama-server.
-
----
-
-# 78. Real llama integration test
-
-Optional test profile:
-
-```text
-DSH_KV_TEST_LLAMA_URL=http://127.0.0.1:8080
-```
-
-Tests only run when explicitly enabled.
-
-Never require a GPU in the ordinary CI pipeline.
-
----
-
-# 79. Error taxonomy
-
-Use stable codes.
-
-Suggested:
-
-```text
-KV_BACKEND_UNAVAILABLE
-KV_BACKEND_UNSUPPORTED
-
-KV_SLOT_NOT_FOUND
-KV_SLOT_BUSY
-KV_SLOT_STATE_INVALID
-
-KV_SNAPSHOT_NOT_FOUND
-KV_SNAPSHOT_INCOMPATIBLE
-KV_SNAPSHOT_CORRUPT
-
-KV_SAVE_FAILED
-KV_RESTORE_FAILED
-KV_ERASE_FAILED
-
-KV_MANIFEST_INVALID
-KV_METADATA_IO
-
-KV_OPERATION_TIMEOUT
-
-KV_INVARIANT
-```
-
-Infrastructure diagnostics become much easier than matching error strings.
-
----
-
-# 80. Example logs
-
-First request:
-
-```text
-[kv-persist] session cold
-session=7c856d slot=0
-```
-
-Idle checkpoint:
-
-```text
-[kv-persist] snapshot saved
-session=7c856d
-tokens=48712
-bytes=2.42GiB
-save=531ms
-```
-
-Resume:
-
-```text
-[kv-persist] snapshot restored
-session=7c856d
-tokens=48712
-bytes=2.42GiB
-restore=188ms
-```
-
-Failure:
-
-```text
-[kv-persist] restore failed; falling back to cold prefill
-session=7c856d
-code=KV_RESTORE_FAILED
-```
-
----
-
-# 81. User-visible UX
-
-Most of the time:
-
-```text
-nothing
-```
-
-It should simply make old local-model sessions resume quickly.
-
-Potential status line later:
-
-```text
-KV: restored 48.7K · 188ms
-```
-
-or:
-
-```text
-KV: resident
-```
-
-or:
-
-```text
-KV: cold
-```
-
-But this belongs to a later UI integration and should not block the core plugin.
-
----
-
-# 82. Suggested README pitch
-
-> `dsh-kv-persist` keeps local LLM sessions warm across session switches and restarts.
->
-> It maps DeepSeek Harness sessions to persistent inference-cache snapshots and restores them when a session becomes active again. The initial backend uses llama.cpp's slot save/restore API, allowing large agent contexts to resume without repeating a full prompt prefill.
->
-> KV state is treated strictly as an optimization: DSH's session log remains the source of truth, and any missing, stale, or incompatible cache automatically falls back to normal inference.
-
----
-
-# 83. Roadmap
-
-## Phase 0 — research/prototype
-
-- Validate llama.cpp save/restore with target Qwen3.8 build.
-- Verify restore within same server process.
-- Verify restore across llama-server restart.
-- Measure snapshot sizes.
-- Measure save/restore throughput.
-- Confirm cache hit after restore.
-- Document hybrid-model behavior.
-
-## Phase 1 — MVP / `0.1`
-
-- Cordis service.
-- llama.cpp client.
-- backend probe.
-- single-slot coordinator.
-- session mapping.
-- `llm/stream` wrapper.
-- lazy restore.
-- save-before-switch.
-- idle checkpoint.
-- shutdown/session-flush checkpoint.
-- local metadata.
-- logging.
-- cold fallback.
-- fake backend tests.
-
-## Phase 2 — reliability / `0.2`
-
-- compatibility fingerprints.
-- circuit breaker.
-- snapshot verification.
-- atomic snapshot rotation.
-- diagnostics API.
-- `doctor`.
-- cleanup tooling.
-- improved hybrid/recurrent testing.
-
-## Phase 3 — multi-slot / `0.3`
-
-- slot pool.
-- LRU assignment.
-- explicit slot leases.
-- llama-specific transport integration.
-- request `id_slot`.
-- auxiliary slot reservation.
-- concurrent sessions.
-
-## Phase 4 — observability / `0.4`
-
-- metrics.
-- cache hit statistics.
-- storage statistics.
-- performance comparisons.
-- optional DSH UI panel.
-
-## Phase 5 — generalized persistence / `1.0`
-
-- stable backend interface.
-- multiple servers.
-- multiple backends.
-- retention policies.
-- documented API for external plugins.
-- production-hardening.
-
----
-
-# 84. First implementation milestone
-
-The first prototype should intentionally do almost nothing clever.
-
-Hardcode/test:
-
-```text
-provider = local-qwen
-slot = 0
-server = localhost:8080
-```
-
-Implement only:
-
-```text
-request A
-request A
-request B
-request A
-```
-
-Expected management calls:
-
-```text
-A #1:
-erase
-
-A #2:
-none
-
-B:
-save A
-erase/restore B
-
-A #3:
-save B
-restore A
-```
-
-Once this works reliably, abstract it.
-
-Do not start by implementing:
-
-```text
-multi-server
-multi-slot
-GC
-UI
-dynamic provider discovery
-```
-
-before proving the fundamental cache lifecycle.
-
----
-
-# 85. Key architectural invariants
-
-These should eventually exist as comments/tests.
-
-**Invariant 1**
-
-```text
-DSH session state never depends on KV persistence.
-```
-
-**Invariant 2**
-
-```text
-At most one owner controls a physical slot at a time.
-```
-
-**Invariant 3**
-
-```text
-A dirty slot is checkpointed before reassignment unless policy explicitly disables it.
-```
-
-**Invariant 4**
-
-```text
-A snapshot is restored only when its runtime identity is compatible.
-```
-
-**Invariant 5**
-
-```text
-Persistence failure defaults to cold inference.
-```
-
-**Invariant 6**
-
-```text
-Resident-session requests incur no disk I/O.
-```
-
-**Invariant 7**
-
-```text
-Auxiliary LLM requests never become authoritative state for a conversation session.
-```
-
-**Invariant 8**
-
-```text
-All backend mutation operations are serialized per physical slot.
-```
-
-**Invariant 9**
-
-```text
-Snapshot filenames are plugin-generated opaque identifiers.
-```
-
-**Invariant 10**
-
-```text
-A successful HTTP restore is not automatically equivalent to a verified usable restore.
-```
-
----
-
-# 86. Recommended initial technical direction
-
-For the first release, use:
-
-```text
-Cordis plugin
-    +
-ctx.sessions lifecycle
-    +
-llm/stream observation
-    +
-single llama slot
-    +
-server-side snapshot files
-```
-
-Do NOT fork or patch DeepSeek Harness.
-
-Do NOT replace the existing OpenAI-compatible provider.
-
-Do NOT modify prompts.
-
-Do NOT make cache state part of SessionEvent history.
-
-Once the single-slot implementation proves useful, introduce the llama-specific transport adapter needed for explicit `id_slot` and proper multi-session concurrency.
-
-This yields a plugin that starts as a small, useful local optimization but has a clean path toward becoming a general persistence/cache coordinator for local inference runtimes.