@yadsh/dsh-kv-persist 0.1.0

package/lib/backends/llama-cpp/backend.d.ts

@@ -0,0 +1,20 @@
+/**
+ * llama.cpp backend (SPEC §6, §12): maps the backend-neutral persistence
+ * interface onto the llama-server slot save/restore/erase API.
+ */
+import type { LlamaCppClientOptions } from "./client.js";
+import type { BackendCapabilities, BackendEraseResult, BackendRestoreResult, BackendSaveResult, BackendSlot, KvPersistenceBackend } from "../types.js";
+/** The only backend kind of v0.1 (SPEC §12). */
+export declare const LLAMA_CPP_BACKEND_KIND = "llama.cpp";
+export declare class LlamaCppBackend implements KvPersistenceBackend {
+    #private;
+    readonly kind = "llama.cpp";
+    constructor(clientOptions: LlamaCppClientOptions, requiredSlotId: number);
+    /** Health/capability probe (SPEC §34). */
+    probe(): Promise<BackendCapabilities>;
+    inspectSlots(): Promise<readonly BackendSlot[]>;
+    saveSlot(slotId: number, snapshotKey: string): Promise<BackendSaveResult>;
+    restoreSlot(slotId: number, snapshotKey: string): Promise<BackendRestoreResult>;
+    eraseSlot(slotId: number): Promise<BackendEraseResult>;
+}
+//# sourceMappingURL=backend.d.ts.map

package/lib/backends/llama-cpp/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/backends/llama-cpp/backend.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD,qBAAa,eAAgB,YAAW,oBAAoB;;IAC1D,QAAQ,CAAC,IAAI,eAA0B;gBAK3B,aAAa,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM;IAKxE,0CAA0C;IAC1C,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAIrC,YAAY,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC;IAMzC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKzE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAK/E,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAI7D"}

package/lib/backends/llama-cpp/backend.js

@@ -0,0 +1,37 @@
+/**
+ * llama.cpp backend (SPEC §6, §12): maps the backend-neutral persistence
+ * interface onto the llama-server slot save/restore/erase API.
+ */
+import { LlamaCppClient } from "./client.js";
+import { probeServer } from "./discovery.js";
+/** The only backend kind of v0.1 (SPEC §12). */
+export const LLAMA_CPP_BACKEND_KIND = "llama.cpp";
+export class LlamaCppBackend {
+    kind = LLAMA_CPP_BACKEND_KIND;
+    #client;
+    #expectation;
+    constructor(clientOptions, requiredSlotId) {
+        this.#client = new LlamaCppClient(clientOptions);
+        this.#expectation = { requiredSlotId };
+    }
+    /** Health/capability probe (SPEC §34). */
+    probe() {
+        return probeServer(this.#client, this.#expectation);
+    }
+    inspectSlots() {
+        return this.#client.inspectSlots().then((response) => response.slots.map((slot) => ({ id: slot.id })));
+    }
+    async saveSlot(slotId, snapshotKey) {
+        const result = await this.#client.saveSlot(slotId, snapshotKey);
+        return { success: result.success, bytes: null };
+    }
+    async restoreSlot(slotId, snapshotKey) {
+        const result = await this.#client.restoreSlot(slotId, snapshotKey);
+        return { success: result.success, nRestored: result.nRestored };
+    }
+    async eraseSlot(slotId) {
+        const result = await this.#client.eraseSlot(slotId);
+        return { success: result.success };
+    }
+}
+//# sourceMappingURL=backend.js.map

package/lib/backends/llama-cpp/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../../src/backends/llama-cpp/backend.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAW7C,gDAAgD;AAChD,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAElD,MAAM,OAAO,eAAe;IACjB,IAAI,GAAG,sBAAsB,CAAC;IAE9B,OAAO,CAAiB;IACxB,YAAY,CAAmB;IAExC,YAAY,aAAoC,EAAE,cAAsB;QACtE,IAAI,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,YAAY,GAAG,EAAE,cAAc,EAAE,CAAC;IACzC,CAAC;IAED,0CAA0C;IAC1C,KAAK;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACtD,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CACnD,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAe,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAC7D,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,WAAmB;QAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAChE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,WAAmB;QACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACnE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAc;QAC5B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACpD,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC;CACF"}

package/lib/backends/llama-cpp/client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal HTTP client for the llama.cpp slots management API (SPEC §6).
+ *
+ * Every call is bounded by its own timeout (SPEC §59): persistence latency
+ * must never block or outlive the inference path. Only plugin-generated
+ * opaque filenames reach `action=save`/`action=restore` (SPEC §44).
+ */
+import type { LlamaCppEraseResponse, LlamaCppRestoreResponse, LlamaCppSaveResponse, LlamaCppSlotsResponse } from "./types.js";
+export interface LlamaCppClientOptions {
+    readonly baseURL: string;
+    readonly apiKey: string | null;
+    readonly requestTimeoutMs: number;
+    /** Injectable fetch for tests. */
+    readonly fetchImpl?: typeof fetch;
+}
+/** Normalize the GET /slots payload (array or `{ slots: [...] }`). */
+export declare function normalizeSlotsResponse(payload: unknown): LlamaCppSlotsResponse;
+export declare class LlamaCppClient {
+    #private;
+    constructor(options: LlamaCppClientOptions);
+    get baseURL(): string;
+    /** GET /slots — slot discovery and health probing (SPEC §34). */
+    inspectSlots(timeoutMs?: number): Promise<LlamaCppSlotsResponse>;
+    /** POST /slots/{id}?action=save — persist slot KV state into a file. */
+    saveSlot(slotId: number, snapshotFilename: string, timeoutMs?: number): Promise<LlamaCppSaveResponse>;
+    /** POST /slots/{id}?action=restore — load a snapshot back into the slot. */
+    restoreSlot(slotId: number, snapshotFilename: string, timeoutMs?: number): Promise<LlamaCppRestoreResponse>;
+    /** POST /slots/{id}?action=erase — clear slot KV state. */
+    eraseSlot(slotId: number, timeoutMs?: number): Promise<LlamaCppEraseResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/backends/llama-cpp/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/backends/llama-cpp/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE9H,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAuBD,sEAAsE;AACtE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,qBAAqB,CAS9E;AAED,qBAAa,cAAc;;gBAMb,OAAO,EAAE,qBAAqB;IAO1C,IAAI,OAAO,IAAI,MAAM,CAEpB;IA8BD,iEAAiE;IAC3D,YAAY,CAAC,SAAS,GAAE,MAA+B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAQ9F,wEAAwE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,GAAE,MAA+B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAenI,4EAA4E;IACtE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,GAAE,MAA+B,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAmBzI,2DAA2D;IACrD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,MAA+B,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAY5G"}

package/lib/backends/llama-cpp/client.js

@@ -0,0 +1,120 @@
+/**
+ * Minimal HTTP client for the llama.cpp slots management API (SPEC §6).
+ *
+ * Every call is bounded by its own timeout (SPEC §59): persistence latency
+ * must never block or outlive the inference path. Only plugin-generated
+ * opaque filenames reach `action=save`/`action=restore` (SPEC §44).
+ */
+import { KvBackendUnavailableError, KvEraseFailedError, KvRestoreFailedError, KvSaveFailedError } from "../../errors.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function optionalCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Defensive response parsing: llama.cpp builds differ; anything missing
+ * degrades to `null`/`false` rather than throwing parse errors.
+ */
+function parseJsonBody(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) || Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Normalize the GET /slots payload (array or `{ slots: [...] }`). */
+export function normalizeSlotsResponse(payload) {
+    const rawSlots = Array.isArray(payload) ? payload : (isRecord(payload) ? payload.slots : undefined);
+    if (!Array.isArray(rawSlots))
+        return { slots: [] };
+    const slots = rawSlots.flatMap((entry) => {
+        if (isRecord(entry) && typeof entry.id === "number")
+            return [{ id: entry.id }];
+        if (typeof entry === "number")
+            return [{ id: entry }];
+        return [];
+    });
+    return { slots };
+}
+export class LlamaCppClient {
+    #baseURL;
+    #apiKey;
+    #requestTimeoutMs;
+    #fetchImpl;
+    constructor(options) {
+        this.#baseURL = options.baseURL.replace(/\/+$/, "");
+        this.#apiKey = options.apiKey;
+        this.#requestTimeoutMs = options.requestTimeoutMs;
+        this.#fetchImpl = options.fetchImpl ?? fetch;
+    }
+    get baseURL() {
+        return this.#baseURL;
+    }
+    async #request(path, init, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const headers = {};
+        if (this.#apiKey !== null)
+            headers["Authorization"] = `Bearer ${this.#apiKey}`;
+        if (init.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        try {
+            const response = await this.#fetchImpl(`${this.#baseURL}${path}`, {
+                ...init,
+                headers: { ...headers, ...init.headers },
+                signal: controller.signal,
+            });
+            const body = await response.text();
+            return { status: response.status, body };
+        }
+        catch (error) {
+            throw new KvBackendUnavailableError(`llama.cpp server at ${this.#baseURL} is unreachable: ${String(error?.message ?? error)}`, { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** GET /slots — slot discovery and health probing (SPEC §34). */
+    async inspectSlots(timeoutMs = this.#requestTimeoutMs) {
+        const { status, body } = await this.#request("/slots", { method: "GET" }, timeoutMs);
+        if (status !== 200) {
+            throw new KvBackendUnavailableError(`GET /slots returned HTTP ${status}`);
+        }
+        return normalizeSlotsResponse(parseJsonBody(body));
+    }
+    /** POST /slots/{id}?action=save — persist slot KV state into a file. */
+    async saveSlot(slotId, snapshotFilename, timeoutMs = this.#requestTimeoutMs) {
+        const { status, body } = await this.#request(`/slots/${slotId}?action=save`, { method: "POST", body: JSON.stringify({ filepath: snapshotFilename }) }, timeoutMs);
+        const payload = parseJsonBody(body);
+        if (status !== 200 || !isRecord(payload) || payload.success !== true) {
+            throw new KvSaveFailedError(`save of slot ${slotId} failed (HTTP ${status}): ${body.slice(0, 200)}`);
+        }
+        return { success: true };
+    }
+    /** POST /slots/{id}?action=restore — load a snapshot back into the slot. */
+    async restoreSlot(slotId, snapshotFilename, timeoutMs = this.#requestTimeoutMs) {
+        const { status, body } = await this.#request(`/slots/${slotId}?action=restore`, { method: "POST", body: JSON.stringify({ filepath: snapshotFilename }) }, timeoutMs);
+        const payload = parseJsonBody(body);
+        if (status !== 200 || !isRecord(payload)) {
+            throw new KvRestoreFailedError(`restore of slot ${slotId} failed (HTTP ${status}): ${body.slice(0, 200)}`);
+        }
+        const nRestored = optionalCount(payload.n_restored) ?? optionalCount(payload.nRestored);
+        if (payload.success === false) {
+            throw new KvRestoreFailedError(`restore of slot ${slotId} reported success=false`);
+        }
+        return { success: true, nRestored };
+    }
+    /** POST /slots/{id}?action=erase — clear slot KV state. */
+    async eraseSlot(slotId, timeoutMs = this.#requestTimeoutMs) {
+        const { status, body } = await this.#request(`/slots/${slotId}?action=erase`, { method: "POST", body: JSON.stringify({}) }, timeoutMs);
+        const payload = parseJsonBody(body);
+        if (status !== 200 || (isRecord(payload) && payload.success === false)) {
+            throw new KvEraseFailedError(`erase of slot ${slotId} failed (HTTP ${status}): ${body.slice(0, 200)}`);
+        }
+        return { success: true };
+    }
+}
+//# sourceMappingURL=client.js.map

package/lib/backends/llama-cpp/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/backends/llama-cpp/client.ts"],"names":[],"mappings":"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"}

package/lib/backends/llama-cpp/discovery.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Backend discovery / health probe (SPEC §34).
+ *
+ * The probe explicitly distinguishes "LLM endpoint alive" from "KV
+ * persistence supported": the plugin degrades to cold inference unless the
+ * slots endpoint answers with the expected geometry.
+ */
+import type { LlamaCppClient } from "./client.js";
+import type { BackendCapabilities } from "../types.js";
+export interface ProbeExpectation {
+    /** Slot that single-slot mode requires (usually 0). */
+    readonly requiredSlotId: number;
+}
+/**
+ * Probe the server: reachable, `/slots` available, expected slot present.
+ * Throws `KV_BACKEND_UNAVAILABLE` on any hard failure; capability details
+ * are returned otherwise.
+ */
+export declare function probeServer(client: LlamaCppClient, expectation: ProbeExpectation): Promise<BackendCapabilities>;
+//# sourceMappingURL=discovery.d.ts.map

package/lib/backends/llama-cpp/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/backends/llama-cpp/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAsB9B"}

package/lib/backends/llama-cpp/discovery.js

@@ -0,0 +1,33 @@
+/**
+ * Backend discovery / health probe (SPEC §34).
+ *
+ * The probe explicitly distinguishes "LLM endpoint alive" from "KV
+ * persistence supported": the plugin degrades to cold inference unless the
+ * slots endpoint answers with the expected geometry.
+ */
+import { KvBackendUnavailableError } from "../../errors.js";
+/**
+ * Probe the server: reachable, `/slots` available, expected slot present.
+ * Throws `KV_BACKEND_UNAVAILABLE` on any hard failure; capability details
+ * are returned otherwise.
+ */
+export async function probeServer(client, expectation) {
+    let response;
+    try {
+        response = await client.inspectSlots();
+    }
+    catch (error) {
+        throw new KvBackendUnavailableError(`slot probing failed: ${String(error?.message ?? error)}`, { cause: error });
+    }
+    const slotIds = response.slots.map((slot) => slot.id);
+    if (!slotIds.includes(expectation.requiredSlotId)) {
+        throw new KvBackendUnavailableError(`server exposes slots [${slotIds.join(", ")}] but configured slot ${expectation.requiredSlotId} is missing; start llama-server with --slots/--parallel >= ${expectation.requiredSlotId + 1}`);
+    }
+    return {
+        kind: "llama.cpp",
+        slotsAvailable: true,
+        slotIds,
+        serverVersion: null,
+    };
+}
+//# sourceMappingURL=discovery.js.map

package/lib/backends/llama-cpp/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/backends/llama-cpp/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAS5D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAsB,EACtB,WAA6B;IAE7B,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,yBAAyB,CACjC,wBAAwB,MAAM,CAAE,KAAe,EAAE,OAAO,IAAI,KAAK,CAAC,EAAE,EACpE,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,cAAc,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,yBAAyB,CACjC,yBAAyB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,yBAAyB,WAAW,CAAC,cAAc,8DAA8D,WAAW,CAAC,cAAc,GAAG,CAAC,EAAE,CAC7L,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,cAAc,EAAE,IAAI;QACpB,OAAO;QACP,aAAa,EAAE,IAAI;KACpB,CAAC;AACJ,CAAC"}

package/lib/backends/llama-cpp/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wire types of the llama.cpp `/slots` management API (SPEC §6).
+ *
+ * Parsing is defensive: fields the plugin cannot rely on across llama.cpp
+ * builds are optional, and unknown response shapes degrade to `null`
+ * instead of throwing.
+ */
+/** GET /slots response entry (defensive view). */
+export interface LlamaCppSlotView {
+    readonly id: number;
+}
+/** Normalized GET /slots response. */
+export interface LlamaCppSlotsResponse {
+    readonly slots: readonly LlamaCppSlotView[];
+}
+/** POST /slots/{id}?action=save response. */
+export interface LlamaCppSaveResponse {
+    readonly success: boolean;
+}
+/** POST /slots/{id}?action=restore response. */
+export interface LlamaCppRestoreResponse {
+    readonly success: boolean;
+    /** Token count reported by the server, when present (SPEC §24). */
+    readonly nRestored: number | null;
+}
+/** POST /slots/{id}?action=erase response. */
+export interface LlamaCppEraseResponse {
+    readonly success: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/backends/llama-cpp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/backends/llama-cpp/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,sCAAsC;AACtC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC7C;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,gDAAgD;AAChD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B"}

package/lib/backends/llama-cpp/types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types of the llama.cpp `/slots` management API (SPEC §6).
+ *
+ * Parsing is defensive: fields the plugin cannot rely on across llama.cpp
+ * builds are optional, and unknown response shapes degrade to `null`
+ * instead of throwing.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/backends/llama-cpp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/backends/llama-cpp/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/lib/backends/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Backend abstraction (SPEC §12): the coordinator never issues `/slots`
+ * HTTP calls directly; it only talks to `KvPersistenceBackend`.
+ */
+/** Server-reported slot view (SPEC §19 input). */
+export interface BackendSlot {
+    readonly id: number;
+}
+/** Static + probed capabilities of one backend instance. */
+export interface BackendCapabilities {
+    readonly kind: string;
+    /** The slots endpoint answered and slot geometry looks usable. */
+    readonly slotsAvailable: boolean;
+    /** Slot ids the server currently exposes. */
+    readonly slotIds: readonly number[];
+    /** Raw server build/version string when discoverable, else null. */
+    readonly serverVersion: string | null;
+}
+export interface BackendSaveResult {
+    readonly success: boolean;
+    /** Server-reported snapshot size in bytes when discoverable. */
+    readonly bytes: number | null;
+}
+export interface BackendRestoreResult {
+    readonly success: boolean;
+    /** llama.cpp reports how many tokens were restored (SPEC §24). */
+    readonly nRestored: number | null;
+}
+export interface BackendEraseResult {
+    readonly success: boolean;
+}
+/**
+ * Backend-neutral persistence surface (SPEC §12). Core code never issues
+ * `/slots` HTTP calls; it only talks to this interface.
+ */
+export interface KvPersistenceBackend {
+    readonly kind: string;
+    /** Health/capability probe (SPEC §34). */
+    probe(signal?: AbortSignal): Promise<BackendCapabilities>;
+    /** List the physical slots the server currently exposes. */
+    inspectSlots(signal?: AbortSignal): Promise<readonly BackendSlot[]>;
+    /**
+     * Persist slot KV state into a server-side snapshot file.
+     * `snapshotKey` is the opaque plugin-generated filename (SPEC §16, §44).
+     */
+    saveSlot(slotId: number, snapshotKey: string, signal?: AbortSignal): Promise<BackendSaveResult>;
+    /** Load a snapshot back into the slot. */
+    restoreSlot(slotId: number, snapshotKey: string, signal?: AbortSignal): Promise<BackendRestoreResult>;
+    /** Clear the slot KV state. */
+    eraseSlot(slotId: number, signal?: AbortSignal): Promise<BackendEraseResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/backends/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/backends/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0CAA0C;IAC1C,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAE1D,4DAA4D;IAC5D,YAAY,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IAEpE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEhG,0CAA0C;IAC1C,WAAW,CACT,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC,+BAA+B;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC9E"}

package/lib/backends/types.js

@@ -0,0 +1,6 @@
+/**
+ * Backend abstraction (SPEC §12): the coordinator never issues `/slots`
+ * HTTP calls directly; it only talks to `KvPersistenceBackend`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/backends/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/backends/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}