@yadsh/dsh-kv-persist 0.1.0

package/lib/service.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Public `ctx.kvPersist` service (SPEC §11, §47).
+ *
+ * A Cordis `Service` that wires the coordinator, backend, repository, and
+ * lifecycle listeners together. Future UI/CLI plugins can depend on this
+ * surface without knowing anything about llama.cpp.
+ *
+ * Members use TypeScript `private` (not `#private`): the host exposes the
+ * service through a Cordis accessor proxy, and `#private` branding breaks
+ * when methods are invoked with a proxy receiver — the same convention the
+ * reference plugins follow.
+ */
+import { Context, Service } from "@deepseek-ai/cordis";
+import type { KvPersistConfig, ResolvedKvPersistConfig } from "./config.js";
+import type { SnapshotInvalidationReason } from "./errors.js";
+import type { KvPersistenceBackend } from "./backends/types.js";
+import type { RestoreOutcome, SnapshotResult } from "./coordinator/state-machine.js";
+import type { KvPersistLogger } from "./observability/diagnostics.js";
+import { SnapshotRepository } from "./snapshots/repository.js";
+/**
+ * Metadata root resolution (SPEC §39): explicit config path wins, otherwise
+ * `<$DSH_HOME>/cache/dsh-kv-persist` (cwd fallback for dev/test).
+ */
+export declare function resolveMetadataDir(config: ResolvedKvPersistConfig): string;
+/** Overridable internals for tests (fake backend, temp repository, …). */
+export interface KvPersistServiceDeps {
+    readonly backend?: KvPersistenceBackend;
+    readonly repository?: SnapshotRepository;
+    readonly logger?: KvPersistLogger;
+    readonly now?: () => number;
+}
+/** Status payload (SPEC §47). */
+export interface KvPersistStatus {
+    readonly enabled: boolean;
+    readonly backend: {
+        readonly kind: "llama.cpp";
+        readonly state: string;
+        readonly endpoint: string;
+    };
+    readonly mode: "single-slot";
+    readonly slots: readonly {
+        readonly id: number;
+        readonly owner: string | null;
+        readonly state: string;
+    }[];
+    readonly snapshots: {
+        readonly known: number;
+        readonly valid: number;
+        readonly invalid: number;
+    };
+    readonly stats: {
+        readonly restores: number;
+        readonly restoreHits: number;
+        readonly coldStarts: number;
+        readonly saves: number;
+    };
+}
+/** Per-session state view (SPEC §11 `getSessionState`). */
+export interface SessionKvState {
+    readonly sessionId: string;
+    readonly lifecycle: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly dirtyRevision: number;
+    readonly persistedRevision: number;
+    readonly ownsSlot: boolean;
+}
+/** Doctor report (SPEC §34, §48-lite). */
+export interface KvPersistDoctorReport {
+    readonly result: "READY" | "BLOCKED";
+    readonly checks: readonly {
+        readonly name: string;
+        readonly ok: boolean;
+        readonly detail: string;
+    }[];
+}
+export declare class KvPersistService extends Service {
+    static Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+        enabled: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        backend: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            type: import("@deepseek-ai/schemastery").default<"llama.cpp", "llama.cpp">;
+            baseURL: import("@deepseek-ai/schemastery").default<string, string>;
+            apiKey: import("@deepseek-ai/schemastery").default<string, string>;
+            requestTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>, Schemastery.ObjectT<{
+            type: import("@deepseek-ai/schemastery").default<"llama.cpp", "llama.cpp">;
+            baseURL: import("@deepseek-ai/schemastery").default<string, string>;
+            apiKey: import("@deepseek-ai/schemastery").default<string, string>;
+            requestTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>>;
+        providers: import("@deepseek-ai/schemastery").default<string[], string[]>;
+        mode: import("@deepseek-ai/schemastery").default<"single-slot", "single-slot">;
+        slotId: import("@deepseek-ai/schemastery").default<number, number>;
+        runtimeKey: import("@deepseek-ai/schemastery").default<string, string>;
+        checkpoint: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            onSwitch: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onShutdown: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onSessionFlush: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            idleMs: import("@deepseek-ai/schemastery").default<number, number>;
+            onTurnEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onStepEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>, Schemastery.ObjectT<{
+            onSwitch: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onShutdown: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onSessionFlush: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            idleMs: import("@deepseek-ai/schemastery").default<number, number>;
+            onTurnEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onStepEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>>;
+        restore: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            enabled: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            verify: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>, Schemastery.ObjectT<{
+            enabled: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            verify: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>>;
+        failure: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            strict: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            maxConsecutiveFailures: import("@deepseek-ai/schemastery").default<number, number>;
+            cooldownMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>, Schemastery.ObjectT<{
+            strict: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            maxConsecutiveFailures: import("@deepseek-ai/schemastery").default<number, number>;
+            cooldownMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>>;
+        metadata: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            path: import("@deepseek-ai/schemastery").default<string, string>;
+        }>, Schemastery.ObjectT<{
+            path: import("@deepseek-ai/schemastery").default<string, string>;
+        }>>;
+        logging: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            level: import("@deepseek-ai/schemastery").default<"debug" | "info" | "off", "debug" | "info" | "off">;
+        }>, Schemastery.ObjectT<{
+            level: import("@deepseek-ai/schemastery").default<"debug" | "info" | "off", "debug" | "info" | "off">;
+        }>>;
+    }>, Schemastery.ObjectT<{
+        enabled: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        backend: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            type: import("@deepseek-ai/schemastery").default<"llama.cpp", "llama.cpp">;
+            baseURL: import("@deepseek-ai/schemastery").default<string, string>;
+            apiKey: import("@deepseek-ai/schemastery").default<string, string>;
+            requestTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>, Schemastery.ObjectT<{
+            type: import("@deepseek-ai/schemastery").default<"llama.cpp", "llama.cpp">;
+            baseURL: import("@deepseek-ai/schemastery").default<string, string>;
+            apiKey: import("@deepseek-ai/schemastery").default<string, string>;
+            requestTimeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>>;
+        providers: import("@deepseek-ai/schemastery").default<string[], string[]>;
+        mode: import("@deepseek-ai/schemastery").default<"single-slot", "single-slot">;
+        slotId: import("@deepseek-ai/schemastery").default<number, number>;
+        runtimeKey: import("@deepseek-ai/schemastery").default<string, string>;
+        checkpoint: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            onSwitch: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onShutdown: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onSessionFlush: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            idleMs: import("@deepseek-ai/schemastery").default<number, number>;
+            onTurnEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onStepEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>, Schemastery.ObjectT<{
+            onSwitch: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onShutdown: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onSessionFlush: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            idleMs: import("@deepseek-ai/schemastery").default<number, number>;
+            onTurnEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            onStepEnd: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>>;
+        restore: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            enabled: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            verify: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>, Schemastery.ObjectT<{
+            enabled: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            verify: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+        }>>;
+        failure: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            strict: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            maxConsecutiveFailures: import("@deepseek-ai/schemastery").default<number, number>;
+            cooldownMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>, Schemastery.ObjectT<{
+            strict: import("@deepseek-ai/schemastery").default<boolean, boolean>;
+            maxConsecutiveFailures: import("@deepseek-ai/schemastery").default<number, number>;
+            cooldownMs: import("@deepseek-ai/schemastery").default<number, number>;
+        }>>;
+        metadata: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            path: import("@deepseek-ai/schemastery").default<string, string>;
+        }>, Schemastery.ObjectT<{
+            path: import("@deepseek-ai/schemastery").default<string, string>;
+        }>>;
+        logging: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+            level: import("@deepseek-ai/schemastery").default<"debug" | "info" | "off", "debug" | "info" | "off">;
+        }>, Schemastery.ObjectT<{
+            level: import("@deepseek-ai/schemastery").default<"debug" | "info" | "off", "debug" | "info" | "off">;
+        }>>;
+    }>>;
+    private readonly config;
+    private readonly backend;
+    private readonly repository;
+    private readonly logger;
+    private readonly metrics;
+    private readonly coordinator;
+    constructor(ctx: Context, config?: KvPersistConfig, deps?: KvPersistServiceDeps);
+    /** Config access for diagnostics. */
+    get resolvedConfig(): ResolvedKvPersistConfig;
+    /** Diagnostics snapshot (SPEC §47). */
+    status(): Promise<KvPersistStatus>;
+    /** Runtime state of one session, when known. */
+    getSessionState(sessionId: string): SessionKvState | undefined;
+    /** Force a checkpoint of the session (SPEC §11 `save`). */
+    save(sessionId: string): Promise<SnapshotResult>;
+    /** Force a restore for the session (SPEC §11 `restore`). */
+    restore(sessionId: string): Promise<RestoreOutcome>;
+    /** Mark every snapshot of the session invalid, without deleting (§31). */
+    invalidate(sessionId: string, reason?: SnapshotInvalidationReason): Promise<void>;
+    /** Remove all metadata of the session (binary cleanup is server-owned). */
+    purge(sessionId: string): Promise<void>;
+    /** Checkpoint the dirty owned session now, if any (SPEC §11 `flush`). */
+    flush(): Promise<void>;
+    /** Managed-provider filter (SPEC §37): only explicit providers are coordinated. */
+    handles(provider: string): boolean;
+    /** Backend + metadata probe (SPEC §34; CLI `doctor` basis, §48). */
+    doctor(): Promise<KvPersistDoctorReport>;
+    private register;
+    /**
+     * Prepare the slot, then wrap the downstream stream (SPEC §23, §25).
+     * `next()` is invoked exactly once, after preparation, inside the slot
+     * lease; chunks pass through unchanged and unbuffered.
+     */
+    private handleStream;
+    private checkMetadataWritable;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/service.d.ts.map

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

package/lib/service.js

@@ -0,0 +1,232 @@
+/**
+ * Public `ctx.kvPersist` service (SPEC §11, §47).
+ *
+ * A Cordis `Service` that wires the coordinator, backend, repository, and
+ * lifecycle listeners together. Future UI/CLI plugins can depend on this
+ * surface without knowing anything about llama.cpp.
+ *
+ * Members use TypeScript `private` (not `#private`): the host exposes the
+ * service through a Cordis accessor proxy, and `#private` branding breaks
+ * when methods are invoked with a proxy receiver — the same convention the
+ * reference plugins follow.
+ */
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { KvPersistConfigSchema, resolveKvPersistConfig, isManagedProvider } from "./config.js";
+import { LlamaCppBackend } from "./backends/llama-cpp/backend.js";
+import { SingleSlotCoordinator } from "./coordinator/coordinator.js";
+import { createKvPersistLogger } from "./observability/diagnostics.js";
+import { KvPersistMetrics } from "./observability/metrics.js";
+import { SnapshotRepository } from "./snapshots/repository.js";
+/**
+ * Metadata root resolution (SPEC §39): explicit config path wins, otherwise
+ * `<$DSH_HOME>/cache/dsh-kv-persist` (cwd fallback for dev/test).
+ */
+export function resolveMetadataDir(config) {
+    if (config.metadataPath !== null)
+        return config.metadataPath;
+    const dshHome = process.env.DSH_HOME?.trim() ?? "";
+    return join(dshHome.length > 0 ? dshHome : process.cwd(), "cache", "dsh-kv-persist");
+}
+/**
+ * Register a host event whose name lives in the host's session-service
+ * vocabulary rather than the plugin-visible `Events` interface. The cast
+ * mirrors the structural lifecycle-registration pattern used across this
+ * monorepo (guidelines §3.3; reference: dsh-doc-impact lifecycle wiring).
+ */
+function registerHostEvent(ctx, event, listener) {
+    ctx.on(event, listener);
+}
+export class KvPersistService extends Service {
+    static Config = KvPersistConfigSchema;
+    config;
+    backend;
+    repository;
+    logger;
+    metrics = new KvPersistMetrics();
+    coordinator;
+    constructor(ctx, config = {}, deps = {}) {
+        super(ctx, "kvPersist");
+        const resolved = resolveKvPersistConfig(config);
+        this.config = resolved;
+        this.logger =
+            deps.logger ??
+                createKvPersistLogger(ctx.logger, resolved.logLevel);
+        this.repository =
+            deps.repository ?? new SnapshotRepository(resolveMetadataDir(resolved));
+        this.backend =
+            deps.backend ??
+                new LlamaCppBackend({
+                    baseURL: resolved.baseURL,
+                    apiKey: resolved.apiKey,
+                    requestTimeoutMs: resolved.requestTimeoutMs,
+                }, resolved.slotId);
+        this.coordinator = new SingleSlotCoordinator({
+            config: resolved,
+            backend: this.backend,
+            repository: this.repository,
+            metrics: this.metrics,
+            logger: this.logger,
+            now: deps.now,
+        });
+        this.register(ctx);
+    }
+    /** Config access for diagnostics. */
+    get resolvedConfig() {
+        return this.config;
+    }
+    // ——— public API (SPEC §11) ————————————————————————————————————————————
+    /** Diagnostics snapshot (SPEC §47). */
+    async status() {
+        const counts = await this.repository.counts().catch(() => ({ known: 0, valid: 0, invalid: 0 }));
+        const counters = this.metrics.snapshot();
+        const slot = this.coordinator.slot;
+        return {
+            enabled: this.config.enabled,
+            backend: {
+                kind: "llama.cpp",
+                state: this.coordinator.circuitState,
+                endpoint: this.config.baseURL,
+            },
+            mode: "single-slot",
+            slots: [
+                {
+                    id: slot.id,
+                    owner: slot.ownerSessionId,
+                    state: slot.state,
+                },
+            ],
+            snapshots: counts,
+            stats: {
+                restores: counters.restores,
+                restoreHits: counters.restoreHits,
+                coldStarts: counters.coldPrefills,
+                saves: counters.saves,
+            },
+        };
+    }
+    /** Runtime state of one session, when known. */
+    getSessionState(sessionId) {
+        const runtime = this.coordinator.getSessionState(sessionId);
+        if (runtime === undefined)
+            return undefined;
+        return {
+            sessionId,
+            lifecycle: runtime.lifecycle,
+            provider: runtime.route.provider,
+            model: runtime.route.model,
+            dirtyRevision: runtime.dirtyRevision,
+            persistedRevision: runtime.persistedRevision,
+            ownsSlot: this.coordinator.slot.ownerSessionId === sessionId,
+        };
+    }
+    /** Force a checkpoint of the session (SPEC §11 `save`). */
+    save(sessionId) {
+        return this.coordinator.saveNow(sessionId);
+    }
+    /** Force a restore for the session (SPEC §11 `restore`). */
+    restore(sessionId) {
+        return this.coordinator.restoreNow(sessionId);
+    }
+    /** Mark every snapshot of the session invalid, without deleting (§31). */
+    invalidate(sessionId, reason) {
+        return this.coordinator.invalidate(sessionId, reason ?? "EXPLICIT");
+    }
+    /** Remove all metadata of the session (binary cleanup is server-owned). */
+    purge(sessionId) {
+        return this.coordinator.purge(sessionId);
+    }
+    /** Checkpoint the dirty owned session now, if any (SPEC §11 `flush`). */
+    flush() {
+        return this.coordinator.flushOwned("manual");
+    }
+    /** Managed-provider filter (SPEC §37): only explicit providers are coordinated. */
+    handles(provider) {
+        return this.config.enabled && isManagedProvider(this.config, provider);
+    }
+    /** Backend + metadata probe (SPEC §34; CLI `doctor` basis, §48). */
+    async doctor() {
+        const checks = [];
+        const probe = await this.coordinator.probeBackend();
+        checks.push({
+            name: "slots-api",
+            ok: probe.healthy,
+            detail: probe.healthy
+                ? `reachable, slots: [${probe.slotIds.join(", ")}]`
+                : (probe.error ?? "unreachable"),
+        });
+        checks.push({
+            name: "configured-slot",
+            ok: probe.slotIds.includes(this.config.slotId),
+            detail: `slot ${this.config.slotId} required (mode: ${this.config.mode})`,
+        });
+        checks.push(await this.checkMetadataWritable());
+        return {
+            result: checks.every((check) => check.ok) ? "READY" : "BLOCKED",
+            checks,
+        };
+    }
+    // ——— lifecycle wiring (SPEC §21, §50, §58) —————————————————————————————
+    register(ctx) {
+        // `llm/stream` is a waterfall around every streaming model call (§21).
+        // The listener awaits slot preparation (lazy restore, save-before-switch)
+        // before invoking `next()`, then returns the transparent stream wrapper.
+        ctx.on("llm/stream", ((options, next) => this.handleStream(options, next)), { global: true });
+        // Session lifecycle hooks through a structural registration (the
+        // `session/*` event vocabulary belongs to the host's session service).
+        registerHostEvent(ctx, "session/flush", (session) => this.coordinator.checkpoint(String(session.id), "session-flush").catch(() => undefined));
+        registerHostEvent(ctx, "session/disposed", (session) => {
+            void this.coordinator.handleSessionDisposed(String(session.id)).catch(() => undefined);
+        });
+        registerHostEvent(ctx, "session/event", (session, event) => {
+            if (event.type !== "turn/end")
+                return;
+            void this.coordinator.checkpoint(String(session.id), "turn-end").catch(() => undefined);
+        });
+        // Backend probe + shutdown checkpoint through a proper Cordis effect
+        // (SPEC §34, §58): the disposer runs when the owning fiber unloads.
+        ctx.effect(() => {
+            void this.coordinator.probeBackend().catch(() => undefined);
+            return async () => {
+                await this.coordinator.dispose();
+                // Flush and release the log file handle (no-op for injected loggers).
+                await this.logger.close?.();
+            };
+        }, "dsh-kv-persist.lifecycle");
+    }
+    /**
+     * Prepare the slot, then wrap the downstream stream (SPEC §23, §25).
+     * `next()` is invoked exactly once, after preparation, inside the slot
+     * lease; chunks pass through unchanged and unbuffered.
+     */
+    async handleStream(options, next) {
+        if (!this.handles(options.provider))
+            return next();
+        return this.coordinator.runSessionRequest({
+            sessionId: options.sessionId === undefined ? null : String(options.sessionId),
+            provider: options.provider,
+            model: options.model,
+            purpose: options.purpose,
+            next,
+        });
+    }
+    async checkMetadataWritable() {
+        const dir = resolveMetadataDir(this.config);
+        const probeFile = join(dir, `.probe-${process.pid}-${Date.now().toString(36)}`);
+        try {
+            await mkdir(dir, { recursive: true });
+            await writeFile(probeFile, "probe\n", "utf8");
+            await rm(probeFile, { force: true });
+            return { name: "metadata-dir", ok: true, detail: `${dir} is writable` };
+        }
+        catch (error) {
+            return {
+                name: "metadata-dir",
+                ok: false,
+                detail: `${dir} is not writable: ${String(error?.message ?? error)}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=service.js.map

package/lib/service.js.map

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

package/lib/snapshots/fingerprint.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Runtime fingerprints and snapshot identity (SPEC §13-§15).
+ *
+ * A snapshot is never identified by sessionId alone: the identity binds the
+ * server instance, provider, model, and a compatibility generation. The
+ * runtime fingerprint is the compatibility gate (SPEC Invariant 4) — a
+ * snapshot is restored only when the fingerprint matches.
+ */
+/** Plugin snapshot schema generation; bump on incompatible manifest changes. */
+export declare const SNAPSHOT_SCHEMA_GENERATION = 1;
+/** Identity of one snapshot (SPEC §13). */
+export interface SnapshotIdentity {
+    readonly sessionId: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly backend: "llama.cpp";
+    /** Stable key of the server instance (v0.1: derived from the endpoint). */
+    readonly serverInstanceKey: string;
+    /** Compatibility generation (SPEC §15). */
+    readonly compatibilityVersion: string;
+}
+/** The request route a session is currently using. */
+export interface SessionRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+/** sha256 hex digest of a string. */
+export declare function sha256Hex(input: string): string;
+/**
+ * Server instance key for v0.1: one configured endpoint, keyed by its
+ * origin (`method://host:port`). Multiple servers arrive with v0.3.
+ */
+export declare function deriveServerInstanceKey(baseURL: string): string;
+/**
+ * Compatibility generation (SPEC §15): runtimeKey escape hatch + model +
+ * schema generation. Changing `runtimeKey` makes old snapshots invisible
+ * without deleting them.
+ */
+export declare function compatibilityVersion(options: {
+    readonly backend: "llama.cpp";
+    readonly runtimeKey: string | null;
+    readonly model: string;
+}): string;
+/** Build the full snapshot identity for one (session, route) pair. */
+export declare function buildSnapshotIdentity(options: {
+    readonly sessionId: string;
+    readonly route: SessionRoute;
+    readonly baseURL: string;
+    readonly runtimeKey: string | null;
+}): SnapshotIdentity;
+/** True when a stored identity is compatible with the requested one (SPEC §31). */
+export declare function isIdentityCompatible(stored: SnapshotIdentity, requested: SnapshotIdentity): boolean;
+//# sourceMappingURL=fingerprint.d.ts.map

package/lib/snapshots/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/snapshots/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAUT;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC,GAAG,gBAAgB,CAcnB;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,gBAAgB,GAC1B,OAAO,CAQT"}

package/lib/snapshots/fingerprint.js

@@ -0,0 +1,69 @@
+/**
+ * Runtime fingerprints and snapshot identity (SPEC §13-§15).
+ *
+ * A snapshot is never identified by sessionId alone: the identity binds the
+ * server instance, provider, model, and a compatibility generation. The
+ * runtime fingerprint is the compatibility gate (SPEC Invariant 4) — a
+ * snapshot is restored only when the fingerprint matches.
+ */
+import { createHash } from "node:crypto";
+import { KvInvariantError } from "../errors.js";
+/** Plugin snapshot schema generation; bump on incompatible manifest changes. */
+export const SNAPSHOT_SCHEMA_GENERATION = 1;
+/** sha256 hex digest of a string. */
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+/**
+ * Server instance key for v0.1: one configured endpoint, keyed by its
+ * origin (`method://host:port`). Multiple servers arrive with v0.3.
+ */
+export function deriveServerInstanceKey(baseURL) {
+    let origin;
+    try {
+        origin = new URL(baseURL).origin;
+    }
+    catch {
+        throw new KvInvariantError(`backend.baseURL is not a valid URL: "${baseURL}"`);
+    }
+    return `llama-${sha256Hex(origin).slice(0, 12)}`;
+}
+/**
+ * Compatibility generation (SPEC §15): runtimeKey escape hatch + model +
+ * schema generation. Changing `runtimeKey` makes old snapshots invisible
+ * without deleting them.
+ */
+export function compatibilityVersion(options) {
+    return sha256Hex(JSON.stringify([
+        options.backend,
+        // null and "" mean "no explicit runtime key" and must hash identically.
+        options.runtimeKey ?? "",
+        options.model,
+        SNAPSHOT_SCHEMA_GENERATION,
+    ])).slice(0, 16);
+}
+/** Build the full snapshot identity for one (session, route) pair. */
+export function buildSnapshotIdentity(options) {
+    const backend = "llama.cpp";
+    return {
+        sessionId: options.sessionId,
+        provider: options.route.provider,
+        model: options.route.model,
+        backend,
+        serverInstanceKey: deriveServerInstanceKey(options.baseURL),
+        compatibilityVersion: compatibilityVersion({
+            backend,
+            runtimeKey: options.runtimeKey,
+            model: options.route.model,
+        }),
+    };
+}
+/** True when a stored identity is compatible with the requested one (SPEC §31). */
+export function isIdentityCompatible(stored, requested) {
+    return (stored.backend === requested.backend &&
+        stored.serverInstanceKey === requested.serverInstanceKey &&
+        stored.provider === requested.provider &&
+        stored.model === requested.model &&
+        stored.compatibilityVersion === requested.compatibilityVersion);
+}
+//# sourceMappingURL=fingerprint.js.map

package/lib/snapshots/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/snapshots/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,gFAAgF;AAChF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAoB5C,qCAAqC;AACrC,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,gBAAgB,CAAC,wCAAwC,OAAO,GAAG,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAIpC;IACC,OAAO,SAAS,CACd,IAAI,CAAC,SAAS,CAAC;QACb,OAAO,CAAC,OAAO;QACf,wEAAwE;QACxE,OAAO,CAAC,UAAU,IAAI,EAAE;QACxB,OAAO,CAAC,KAAK;QACb,0BAA0B;KAC3B,CAAC,CACH,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACjB,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,qBAAqB,CAAC,OAKrC;IACC,MAAM,OAAO,GAAG,WAAoB,CAAC;IACrC,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK;QAC1B,OAAO;QACP,iBAAiB,EAAE,uBAAuB,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3D,oBAAoB,EAAE,oBAAoB,CAAC;YACzC,OAAO;YACP,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK;SAC3B,CAAC;KACH,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAClC,MAAwB,EACxB,SAA2B;IAE3B,OAAO,CACL,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,OAAO;QACpC,MAAM,CAAC,iBAAiB,KAAK,SAAS,CAAC,iBAAiB;QACxD,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,QAAQ;QACtC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,KAAK;QAChC,MAAM,CAAC,oBAAoB,KAAK,SAAS,CAAC,oBAAoB,CAC/D,CAAC;AACJ,CAAC"}