@qvac/sdk 0.10.2 → 0.12.0

package/dist/server/bare/plugins/llamacpp-completion/ops/kv-cache-session.js

@@ -0,0 +1,448 @@
+import { promises as fsPromises } from "bare-fs";
+import path from "bare-path";
+import { findMatchingCache, generateConfigHash, getCacheFilePath, getCurrentCacheInfo, renameCacheFile, deleteCache as deleteCacheUtil, } from "../../../ops/kv-cache-utils.js";
+import { logCacheSaveError, logCacheStatus, } from "./cache-logger.js";
+import { getServerLogger } from "../../../../../logging/index.js";
+// Used by cross-model paths that have no `RequestContext` (e.g.
+// `deleteKvCacheState`). Per-session call sites receive a logger from
+// the caller — typically `withRequestContext(...)`.
+const moduleLogger = getServerLogger();
+/**
+ * Single owner of the three KV-cache bookkeeping layers.
+ *
+ * The llama.cpp completion handler has three independent layers it must
+ * keep consistent across every cancel/error branch:
+ *
+ *   1. `cachedMessageCounts: Map<path, count>` — the "n messages
+ *      currently on disk" tracker.
+ *   2. `initializedCaches: Set<key>` — the "addon defers disk writes;
+ *      we know this cache is primed" tracker.
+ *   3. On-disk `.bin` files written by the addon.
+ *
+ * Without a single owner, every cancel / zero-token / rename-failed /
+ * tool-call exit would need to touch all three; any branch that forgets
+ * a layer produces three-layer drift bugs.
+ *
+ * `KvCacheSession` collapses the three layers behind one object with
+ * three operations:
+ *
+ *   - `beginTurn` — resolves the cache file path, primes the system
+ *     prompt cache if missing (delegated to a caller-supplied closure
+ *     so the session doesn't depend on the model addon), marks the
+ *     cache initialized, and returns a `TurnHandle` carrying the
+ *     resolved path + the snapshot of the on-disk saved count.
+ *   - `commitTurn` — records the new saved count (for custom-key
+ *     turns) or renames the addon's pre-response file to the
+ *     post-response path and records the count there (for auto-cache
+ *     turns). Flips the turn's internal `committed` flag so the
+ *     deferred `rollback` becomes a no-op on the happy path.
+ *   - `rollback` — atomically deletes the on-disk file, clears the
+ *     in-memory init entry, and forgets the saved count. **All three
+ *     layers, always, in one place.** Handlers call it once via
+ *     `ctx.scope.defer(() => session.rollback(turn))`; `commitTurn`
+ *     short-circuits it on success.
+ *
+ * The module-level `deleteKvCacheState(...)` function (below) provides
+ * an administrative cross-model delete API for the
+ * `handleDeleteCache` RPC handler.
+ *
+ * The module-scoped `cachedMessageCounts` and `initializedCaches` maps
+ * are *private* to this file — no other module reaches into them.
+ * Callers that need cache-status info do so through the session API.
+ */
+// ----- module-scoped state. The session is the single mutation point
+// for the in-memory KV-cache bookkeeping. -----
+/**
+ * Number of chat messages the kv-cache file on disk is known to cover,
+ * keyed by cache path. Written by `commitTurn`, read by `getSavedCount`,
+ * deleted by `rollback` / `delete` / `dropStaleSavedCount`. The same
+ * INVARIANT that existed in `kv-cache-state.ts` still holds: an entry is
+ * present only when the corresponding `.bin` file is considered
+ * trustworthy. Cancelled or zero-token turns must remove the entry so
+ * the next-turn slice doesn't read a stale boundary.
+ */
+const cachedMessageCounts = new Map();
+/**
+ * In-memory registry of caches initialized this session. The addon
+ * defers disk writes, so the absence of a `.bin` file on disk isn't
+ * proof that the cache hasn't been primed in this worker process. Keyed
+ * by `${modelId}:${configHash}:${cacheKey}`, so on-disk caches from
+ * older worker runs still hit the lazy-load path in `beginTurn`.
+ */
+const initializedCaches = new Set();
+function initRegistryKey(modelId, configHash, cacheKey) {
+    return `${modelId}:${configHash}:${cacheKey}`;
+}
+// ----- factory -----
+/**
+ * Construct a session bound to one `(modelId, turn-owning request)`
+ * scope. `options.logger` is the per-instance logger the session emits
+ * through (typically `withRequestContext(getServerLogger(), ctx)`);
+ * falls back to the module-scoped logger when omitted.
+ */
+export function createKvCacheSession(modelId, options) {
+    const logger = options?.logger ?? moduleLogger;
+    // Per-session map: each `TurnHandle` carries an opaque entry here. A
+    // WeakMap so handles drop their state once the handler scope releases
+    // the reference; the module-scoped maps above survive.
+    const turnState = new WeakMap();
+    function makeHandle(cachePath, registryKey) {
+        const handle = {
+            cachePath,
+            savedCount: cachedMessageCounts.get(cachePath) ?? 0,
+        };
+        turnState.set(handle, {
+            cachePath,
+            registryKey,
+            committed: false,
+            rolledBack: false,
+        });
+        return handle;
+    }
+    async function beginCustom(input) {
+        const cachePath = await getCacheFilePath(modelId, input.configHash, input.customKey);
+        const registryKey = initRegistryKey(modelId, input.configHash, input.customKey);
+        // In-memory registry check first — the addon defers disk writes, so
+        // a freshly-primed cache may not yet exist on disk. If the
+        // in-memory flag isn't set, fall back to a filesystem probe so
+        // caches surviving across worker restarts still hit the reuse path.
+        let exists = initializedCaches.has(registryKey);
+        if (!exists) {
+            try {
+                await fsPromises.access(cachePath);
+                exists = true;
+                initializedCaches.add(registryKey);
+            }
+            catch {
+                exists = false;
+            }
+        }
+        logCacheStatus(input.customKey, exists);
+        if (!exists) {
+            await input.primeIfMissing(cachePath);
+            await verifyPrimedFile(cachePath, logger);
+            initializedCaches.add(registryKey);
+        }
+        return makeHandle(cachePath, registryKey);
+    }
+    async function beginAuto(input) {
+        // The pre-response cache key is derived from
+        // `history.slice(0, -1)` — `findMatchingCache` does that
+        // internally. The post-response key (used after a successful turn)
+        // is computed by the caller and passed to `commitTurn` as
+        // `targetCachePath`.
+        const existingCache = await findMatchingCache(modelId, input.configHash, input.history);
+        const preResponseCacheInfo = await getCurrentCacheInfo(modelId, input.configHash, input.history);
+        const cachePath = existingCache !== null
+            ? existingCache.cachePath
+            : preResponseCacheInfo.cachePath;
+        const cacheKeyForRegistry = existingCache !== null
+            ? existingCache.cacheKey
+            : preResponseCacheInfo.cacheKey;
+        const registryKey = initRegistryKey(modelId, input.configHash, cacheKeyForRegistry);
+        const cacheExists = existingCache !== null;
+        logCacheStatus("auto", cacheExists);
+        if (!cacheExists) {
+            await input.primeIfMissing(cachePath);
+            await verifyPrimedFile(cachePath, logger);
+            initializedCaches.add(registryKey);
+        }
+        return makeHandle(cachePath, registryKey);
+    }
+    async function beginTurn(input) {
+        if (input.kind === "custom")
+            return beginCustom(input);
+        return beginAuto(input);
+    }
+    async function commitTurn(turn, result) {
+        const state = turnState.get(turn);
+        if (!state) {
+            // Handle from a different session or already torn down. Treat as
+            // no-op — caller shouldn't be reaching into another session's
+            // state, but failing loudly here punishes the rollback-after-end
+            // path more than it helps.
+            return;
+        }
+        if (state.committed || state.rolledBack)
+            return;
+        if (result.kind === "static") {
+            // Custom-key path: the addon wrote the new cache state inline
+            // at the same path. Verify the file persisted (the addon
+            // currently swallows save errors — see TODO in
+            // `verifySaveAndRecord`) and record the new boundary.
+            const ok = await verifySaveAndRecord(state.cachePath, result.messageCount);
+            if (!ok) {
+                // The expected save didn't land — treat the turn as a rollback
+                // so the next turn re-primes cleanly.
+                await runRollback(state);
+                return;
+            }
+            state.committed = true;
+            return;
+        }
+        // Auto-rename path: the pre-response file is now stale (its key
+        // refers to history minus the last user turn). Rename it to the
+        // post-response key and record the new count there.
+        if (!(await renameCacheFile(state.cachePath, result.targetCachePath))) {
+            logger.warn(`[kv-cache] Auto cache rename failed; rolling back. from=${state.cachePath} to=${result.targetCachePath}`);
+            await runRollback(state);
+            return;
+        }
+        // The source path's entry is gone (the file moved). Drop it and
+        // record the new count at the rename target.
+        cachedMessageCounts.delete(state.cachePath);
+        const ok = await verifySaveAndRecord(result.targetCachePath, result.messageCount);
+        if (!ok) {
+            // Rename succeeded but the file isn't where we expected. Roll
+            // back via the target path instead of the (now-empty) source.
+            state.cachePath = result.targetCachePath;
+            await runRollback(state);
+            return;
+        }
+        // Successful auto-rename. The handle's `cachePath` field still
+        // points at the (now-gone) source path — that's fine, the handle
+        // is committed and won't roll back. Future turns compute fresh
+        // paths.
+        state.committed = true;
+    }
+    async function rollback(turn) {
+        const state = turnState.get(turn);
+        if (!state)
+            return;
+        if (state.committed || state.rolledBack)
+            return;
+        await runRollback(state);
+    }
+    async function runRollback(state) {
+        // Order matters only weakly: unlink first so a partial disk-state
+        // can't be re-loaded by a sibling turn between the file delete and
+        // the in-memory clear. In practice handlers serialise per model;
+        // the order is belt-and-suspenders.
+        try {
+            await fsPromises.unlink(state.cachePath);
+        }
+        catch (unlinkError) {
+            logger.warn(`[kv-cache] Failed to remove cache file during rollback; next turn may load stale KV state. path=${state.cachePath} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
+        }
+        initializedCaches.delete(state.registryKey);
+        cachedMessageCounts.delete(state.cachePath);
+        state.rolledBack = true;
+    }
+    function dropStaleSavedCount(turn) {
+        const state = turnState.get(turn);
+        if (!state)
+            return;
+        cachedMessageCounts.delete(state.cachePath);
+    }
+    return {
+        beginTurn,
+        commitTurn,
+        rollback,
+        dropStaleSavedCount,
+    };
+}
+// ----- module-level administrative API -----
+/**
+ * Atomically delete every layer of KV-cache state for a
+ * `(kvCacheKey, modelId)` pair, or wipe everything. Single entry point
+ * — the only mutation point for cross-model state outside of
+ * turn-scoped `commitTurn`/`rollback`.
+ *
+ * Why this isn't a method on `KvCacheSession`: deletes are
+ * cross-model (`all: true` has no model; the keyed form has
+ * `modelId` optional on the wire). A session, by contrast, is
+ * created with a *fixed* `modelId` for the duration of a turn. Making
+ * delete a method would force callers to materialise an irrelevant
+ * session for cross-model administrative cleanups.
+ *
+ * Layers cleared, in order:
+ *   1. On-disk: `deleteCache(...)` removes the matching directory
+ *      tree (or wipes and recreates the root for `all: true`).
+ *   2. `cachedMessageCounts`: prefix-cleanup by the removed directory
+ *      so any per-cache count under the deleted tree is forgotten.
+ *   3. `initializedCaches`: scope clear by `(kvCacheKey[, modelId])`,
+ *      matching the on-disk scope.
+ *
+ * Concurrency with in-flight turns: this delete is wire-async with
+ * respect to any turn currently holding a `TurnHandle` for the same
+ * cache key. Worst case the on-disk `.bin` is removed while a turn is
+ * mid-write; the turn's eventual `commitTurn(...)` then fails the
+ * `verifySaveAndRecord` probe (file gone) and rolls back idempotently.
+ * No coordination primitive is needed because every layer's mutation
+ * is idempotent (`unlink` no-ops if missing, `Map.delete` / `Set.delete`
+ * no-op on absent keys).
+ */
+export async function deleteKvCacheState(target) {
+    if ("all" in target) {
+        const removed = await deleteCacheUtil({ all: true });
+        cachedMessageCounts.clear();
+        initializedCaches.clear();
+        // `removed` is the kv-cache root dir; surfaces it for ops
+        // visibility but isn't part of the contract.
+        moduleLogger.debug(`[kv-cache] Cleared all caches under ${removed}`);
+        return;
+    }
+    const removedPath = await deleteCacheUtil({
+        kvCacheKey: target.kvCacheKey,
+        ...(target.modelId !== undefined && { modelId: target.modelId }),
+    });
+    // Prefix-cleanup the in-memory counts. The on-disk directory tree
+    // is `{kvCacheRoot}/{kvCacheKey}[/{modelId}]/`, so every entry in
+    // `cachedMessageCounts` whose key is the removed directory itself
+    // or sits beneath it must go.
+    clearCachedMessageCountsByPrefix(removedPath, path.sep);
+    // The in-memory init-set keys are
+    // `${modelId}:${configHash}:${kvCacheKey}` — clear by the user-
+    // facing kvCacheKey (and optionally narrow by modelId).
+    clearInitializedCachesByScope({
+        cacheKey: target.kvCacheKey,
+        ...(target.modelId !== undefined && { modelId: target.modelId }),
+    });
+}
+// ----- private helpers -----
+/**
+ * Verify that the addon actually persisted a usable cache file after a
+ * prime. Mirrors the `verifySaveAndRecord` access-probe used at commit
+ * time, applied at prime time so the session doesn't mark a cache
+ * `initializedCaches.add(...)` against a path that's missing or empty
+ * on disk.
+ *
+ * Failure modes this catches:
+ *
+ *   - The addon's `model.run({ saveSessionPath })` was interrupted
+ *     before the save call ran (e.g. signal abort during prefill); the
+ *     prime closure resolves cleanly because addon save errors are not
+ *     propagated, but no file is on disk.
+ *   - The addon's `llama_state_save_file` was called but produced an
+ *     empty file (out-of-space / fs error swallowed by the addon).
+ *
+ * Failure modes this does **NOT** catch:
+ *
+ *   - A partial-but-nonzero file written by the addon (e.g. header +
+ *     truncated KV state). Catching this requires either an
+ *     addon-side change (have `CacheManager::writeCacheFile` check the
+ *     return value of `llama_state_save_file` and throw on failure) or
+ *     a structural hash check we can't currently compute from the
+ *     SDK. Filed as a follow-up — see `cache-api.md` in the addon
+ *     repo / tracking ticket.
+ *
+ * On failure we best-effort `unlink` an empty leftover file (so the
+ * next existence probe doesn't trust it) and throw — the handler in
+ * `completion-stream.ts` lets the error propagate up and no
+ * `initializedCaches` entry is recorded.
+ */
+async function verifyPrimedFile(cachePath, logger) {
+    let stats;
+    try {
+        stats = await fsPromises.stat(cachePath);
+    }
+    catch (statError) {
+        // ENOENT is the common case here — addon prime returned without
+        // calling save (most often: signal abort during prefill).
+        throw new Error(`[kv-cache] prime closure resolved but no cache file was written. path=${cachePath} cause=${statError instanceof Error ? statError.message : String(statError)}`);
+    }
+    if (stats.size === 0) {
+        // Best-effort cleanup so a future probe doesn't trust the empty
+        // file. Unlink failure is non-fatal — we still throw on the
+        // primary "prime didn't persist" condition.
+        try {
+            await fsPromises.unlink(cachePath);
+        }
+        catch (unlinkError) {
+            logger.warn(`[kv-cache] Failed to remove empty primed cache file. path=${cachePath} error=${unlinkError instanceof Error ? unlinkError.message : String(unlinkError)}`);
+        }
+        throw new Error(`[kv-cache] prime closure resolved but cache file is empty. path=${cachePath}`);
+    }
+}
+/**
+ * Verify the addon actually persisted the cache file before recording
+ * its message count. The addon currently swallows write errors
+ * silently, so a missing file means the next turn must resend the full
+ * history rather than slicing against a stale `savedCount`.
+ *
+ * TODO: once the addon surfaces save failures (e.g. throws
+ * `UnableToSaveSessionFile` when `llama_state_save_file` returns
+ * false), drop the `access()` probe and wrap the `model.run()` call in
+ * a real try/catch that forwards the error.
+ */
+async function verifySaveAndRecord(cachePath, messageCount) {
+    try {
+        await fsPromises.access(cachePath);
+        cachedMessageCounts.set(cachePath, messageCount);
+        return true;
+    }
+    catch (err) {
+        cachedMessageCounts.delete(cachePath);
+        logCacheSaveError(cachePath, err);
+        return false;
+    }
+}
+function clearCachedMessageCountsByPrefix(prefix, sep) {
+    if (!prefix) {
+        cachedMessageCounts.clear();
+        return;
+    }
+    for (const key of cachedMessageCounts.keys()) {
+        if (key === prefix) {
+            cachedMessageCounts.delete(key);
+            continue;
+        }
+        if (!key.startsWith(prefix + sep))
+            continue;
+        cachedMessageCounts.delete(key);
+    }
+}
+function clearInitializedCachesByScope(scope) {
+    if (scope.cacheKey === undefined && scope.modelId === undefined) {
+        initializedCaches.clear();
+        return;
+    }
+    for (const key of initializedCaches) {
+        const firstSep = key.indexOf(":");
+        const secondSep = key.indexOf(":", firstSep + 1);
+        if (firstSep === -1 || secondSep === -1)
+            continue;
+        const entryModelId = key.slice(0, firstSep);
+        const entryCacheKey = key.slice(secondSep + 1);
+        if (scope.cacheKey !== undefined && entryCacheKey !== scope.cacheKey) {
+            continue;
+        }
+        if (scope.modelId !== undefined && entryModelId !== scope.modelId) {
+            continue;
+        }
+        initializedCaches.delete(key);
+    }
+}
+// ----- test-only escape hatches -----
+/**
+ * Test-only access to the module-scoped state. Production code reaches
+ * for cache state exclusively through the session API; the unit suite
+ * for `kv-cache-session.test.ts` needs to seed and inspect raw state
+ * to assert the rollback / commit invariants. Not part of the public
+ * SDK surface.
+ *
+ * @internal
+ */
+export const __kvCacheSessionTestHooks = {
+    getSavedCount(cachePath) {
+        return cachedMessageCounts.get(cachePath);
+    },
+    setSavedCountForTest(cachePath, count) {
+        cachedMessageCounts.set(cachePath, count);
+    },
+    hasInitializedKey(modelId, configHash, cacheKey) {
+        return initializedCaches.has(initRegistryKey(modelId, configHash, cacheKey));
+    },
+    markInitializedForTest(modelId, configHash, cacheKey) {
+        initializedCaches.add(initRegistryKey(modelId, configHash, cacheKey));
+    },
+    resetForTest() {
+        cachedMessageCounts.clear();
+        initializedCaches.clear();
+    },
+};
+// Re-export `generateConfigHash` from the path utilities so callers of
+// the session can compute the hash without separately importing
+// `kv-cache-utils`. The function itself stays in `kv-cache-utils.ts`
+// (pure, no state) — only the re-export lives here.
+export { generateConfigHash };

package/dist/server/bare/plugins/llamacpp-completion/ops/kv-cache-state.d.ts

@@ -1,73 +1,19 @@
 /**
- * Pure state + decision helpers for kv-cache bookkeeping used by
- * `completion-stream.ts`.
+ * Pure decision helper for kv-cache history slicing used by
+ * `completion-stream.ts` (via the slice computed from
+ * `TurnHandle.savedCount`).
  *
  * This module intentionally has **no** `bare-*` imports so it can be
- * exercised directly from unit tests running under `bun` without pulling
- * in the Bare runtime (which is not available in that environment).
- * The file-system-dependent pieces (e.g. `recordCacheSaveCount`) live in
- * `completion-stream.ts` and consume the state exported here.
- */
-/**
- * Number of chat messages the kv-cache file on disk is known to cover, keyed
- * by cache path. Written after a successful completion records a save, read
- * by `prepareMessagesForCache` to slice the history on the next turn so a
- * consumer can stage multiple messages between completions (e.g. an
- * `[assistant, user]` recovery sequence) without resending the whole history.
- *
- * INVARIANT: an entry is only present if the corresponding kv-cache file is
- * considered trustworthy. On any turn where the SDK cannot prove the saved
- * count reflects the on-disk state (cancellation mid-decode, zero-token
- * reply, cache file missing after a save attempt), the entry MUST be
- * deleted; a stale entry causes the next turn to slice its history down to
- * an empty payload and the model returns zero tokens.
- *
- * Mode notes:
- *   - Static-mode turns are the only readers of this map. `clearStaleCount`
- *     in `decideCachedHistorySlice` exists so a stale-but-non-zero entry
- *     can be detected and dropped on the next read.
- *   - Dynamic-mode turns do NOT consume this map — the addon trims tools
- *     and the chain output from the kv-cache after each round, so the
- *     SDK falls back to role-based dispatch in `prepareMessagesForCache`.
- *     Writes still happen on dynamic-mode turns, but the recorded count
- *     reflects the messages the SDK shipped, not the (possibly trimmed)
- *     on-disk cache shape. The map is internally consistent within a
- *     single mode; a `kvCache` key should not be reused across modes.
- */
-export declare const cachedMessageCounts: Map<string, number>;
-/**
- * Clear bookkeeping entries. With no argument, clears the whole map. With a
- * `prefix`, removes any entry whose path is equal to it OR sits beneath it
- * as a directory (i.e. `key.startsWith(prefix + sep)`).
+ * exercised directly from unit tests running under `bun` without
+ * pulling in the Bare runtime (which is not available in that
+ * environment).
  *
- * Runtime callers MUST pass the platform path separator (e.g. `path.sep`
- * from `bare-path`) so directory-prefix matches are correct on every
- * target. The "/" default exists only for unit tests under `bun`, where
- * cache paths are POSIX-shaped and importing `bare-path` would pull in
- * the Bare runtime. The exported wrapper in `completion-stream.ts`
- * injects the real separator for in-process use.
- */
-export declare function clearCachedMessageCounts(prefix?: string, sep?: string): void;
-/**
- * Called from `server/bare/ops/cancel.ts` right before `addon.cancel()` so
- * that the in-flight `completion()` for this model can detect that its
- * current turn is being cancelled and skip poisoning `cachedMessageCounts`
- * with a `history.length + 1` entry that does not correspond to a real
- * assistant reply.
- */
-export declare function noteCancelRequested(modelId: string): void;
-export declare function snapshotCancelCount(modelId: string): number;
-/** Test-only. */
-export declare function _resetCancelCountersForTest(): void;
-/**
- * A completion's `savedCount` should only be recorded when the turn ran to
- * completion AND produced at least one token. Any other outcome —
- * cancelled mid-decode, legitimate zero-token reply, or an early EOS — must
- * clear the entry instead, because there is no guarantee that the kv-cache
- * file on disk matches the `history.length + 1` boundary the SDK would
- * otherwise record.
+ * Cancel detection flows through the per-request `AbortSignal` from
+ * `RequestRegistry`; the `cachedMessageCounts` map lives in
+ * `kv-cache-session.ts`, which owns all three KV-cache bookkeeping
+ * layers (saved counts, init flags, on-disk files). Only the pure
+ * slice-decision helper remains here.
  */
-export declare function shouldRecordSavedCount(wasCancelled: boolean, producedTokens: boolean): boolean;
 export interface HistoryMessage {
     role: string;
     content: string;
@@ -80,8 +26,9 @@ export interface HistorySliceDecision {
     messages: HistoryMessage[];
     /**
      * True when the decision path proves the current `savedCount` is stale
-     * and the caller should `cachedMessageCounts.delete(cachePath)` to avoid
-     * propagating the bad count to the next turn.
+     * and the caller should drop the cached entry (via
+     * `KvCacheSession.dropStaleSavedCount(turn)`) to avoid propagating the
+     * bad count to the next turn.
      */
     clearStaleCount: boolean;
 }
@@ -89,13 +36,14 @@ export interface HistorySliceDecision {
  * Pure slice decision for `prepareMessagesForCache`.
  *
  * Mirrors the shape of the logic in `completion-stream.ts` but without
- * calling `transformMessages` (which depends on `bare-fs` for attachment
- * probing). Kept here so the decision can be unit-tested in isolation.
+ * calling `transformMessages` (which depends on `bare-fs` for
+ * attachment probing). Kept here so the decision can be unit-tested in
+ * isolation.
  *
- * The key regression guard: when a non-zero `savedCount` would slice the
- * history down to an empty array, it is treated as stale — the caller
- * falls back to sending the system-stripped full history rather than
- * handing the model an empty payload.
+ * The key regression guard: when a non-zero `savedCount` would slice
+ * the history down to an empty array, it is treated as stale — the
+ * caller falls back to sending the system-stripped full history rather
+ * than handing the model an empty payload.
  */
 export declare function decideCachedHistorySlice(savedCount: number, cacheExists: boolean, history: HistoryMessage[]): HistorySliceDecision;
 //# sourceMappingURL=kv-cache-state.d.ts.map