@yadsh/dsh-kv-persist 0.1.0

package/lib/snapshots/manifest.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Snapshot metadata manifest (SPEC §14).
+ *
+ * The manifest is small, local, and independent from the potentially huge
+ * binary snapshot file owned by llama-server (SPEC §17). Validation is
+ * strict: a malformed manifest is reported (`KV_MANIFEST_INVALID`) instead
+ * of being silently repaired or dropped.
+ */
+import type { SnapshotIdentity, SessionRoute } from "./fingerprint.js";
+/** Lifecycle state of a snapshot (SPEC §18, §31). */
+export type SnapshotState = "ready" | "invalid";
+/** On-disk manifest for one snapshot. */
+export interface SnapshotManifest {
+    readonly schemaVersion: 1;
+    readonly sessionId: string;
+    /** Latest known DSH session sequence at save time (SPEC §29, diagnostic). */
+    readonly sessionSeq: number | null;
+    readonly provider: string;
+    readonly model: string;
+    readonly backend: "llama.cpp";
+    readonly serverInstanceKey: string;
+    readonly compatibilityVersion: string;
+    readonly slotId: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** Server-reported token/byte counters when known. */
+    readonly tokens: number | null;
+    readonly bytes: number | null;
+    readonly snapshotFilename: string;
+    readonly state: SnapshotState;
+    readonly invalidReason: string | null;
+}
+/** Create a fresh manifest for an identity. */
+export declare function createManifest(options: {
+    readonly identity: SnapshotIdentity;
+    readonly slotId: number;
+    readonly snapshotFilename: string;
+    readonly sessionSeq: number | null;
+    readonly now: string;
+}): SnapshotManifest;
+/**
+ * Validate an unknown parsed manifest document.
+ * Throws `KV_MANIFEST_INVALID` on any schema violation.
+ */
+export declare function parseManifest(raw: unknown): SnapshotManifest;
+/** True when the manifest can serve the requested route (SPEC Invariant 4). */
+export declare function isManifestCompatible(manifest: SnapshotManifest, identity: SnapshotIdentity): boolean;
+/** Route key under which a manifest is stored. */
+export declare function manifestRouteKey(manifest: Pick<SnapshotManifest, "provider" | "model">): string;
+export type { SessionRoute };
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/snapshots/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEvE,qDAAqD;AACrD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IAEtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,GAAG,gBAAgB,CAoBnB;AAcD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAyC5D;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAeT;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,OAAO,CAAC,GAAG,MAAM,CAE/F;AAED,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/lib/snapshots/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/snapshots/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAoCxD,+CAA+C;AAC/C,MAAM,UAAU,cAAc,CAAC,OAM9B;IACC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;QAC7C,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB;QACnD,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,GAAG;QACtB,SAAS,EAAE,OAAO,CAAC,GAAG;QACtB,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,IAAI;QACX,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,KAAK,EAAE,OAAO;QACd,aAAa,EAAE,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,sBAAsB,CAAC,gCAAgC,CAAC,CAAC;IACvF,MAAM,IAAI,GAAG,CAAC,IAAY,EAAS,EAAE;QACnC,MAAM,IAAI,sBAAsB,CAAC,kBAAkB,IAAI,0BAA0B,CAAC,CAAC;IACrF,CAAC,CAAC;IACF,IAAI,GAAG,CAAC,aAAa,KAAK,CAAC;QAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IACnD,KAAK,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAU,EAAE,CAAC;QAC9D,IAAI,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAK,GAAG,CAAC,GAAG,CAAY,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,WAAW;QAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,OAAO,GAAG,CAAC,iBAAiB,KAAK,QAAQ;QAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACzE,IAAI,OAAO,GAAG,CAAC,oBAAoB,KAAK,QAAQ;QAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAC/E,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,QAAQ,IAAI,GAAG,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClF,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,KAAK,OAAO,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACpE,IAAI,GAAG,CAAC,aAAa,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ;QAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IAC/F,IAAI,GAAG,CAAC,UAAU,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;QAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACtF,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1E,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACvE,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,SAAS,EAAE,GAAG,CAAC,SAAmB;QAClC,UAAU,EAAE,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC;QACvC,QAAQ,EAAE,GAAG,CAAC,QAAkB;QAChC,KAAK,EAAE,GAAG,CAAC,KAAe;QAC1B,OAAO,EAAE,WAAW;QACpB,iBAAiB,EAAE,GAAG,CAAC,iBAA2B;QAClD,oBAAoB,EAAE,GAAG,CAAC,oBAA8B;QACxD,MAAM,EAAE,GAAG,CAAC,MAAgB;QAC5B,SAAS,EAAE,GAAG,CAAC,SAAmB;QAClC,SAAS,EAAE,GAAG,CAAC,SAAmB;QAClC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC;QAC/B,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;QAC7B,gBAAgB,EAAE,GAAG,CAAC,gBAA0B;QAChD,KAAK,EAAE,GAAG,CAAC,KAAsB;QACjC,aAAa,EAAE,GAAG,CAAC,aAA8B;KAClD,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAClC,QAA0B,EAC1B,QAA0B;IAE1B,OAAO,CACL,QAAQ,CAAC,KAAK,KAAK,OAAO;QAC1B,oBAAoB,CAClB;YACE,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;YAC7C,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB;SACpD,EACD,QAAQ,CACT,CACF,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,QAAsD;IACrF,OAAO,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;AAClD,CAAC"}

package/lib/snapshots/naming.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Snapshot filename generation (SPEC §16, §41, Invariant 9).
+ *
+ * Filenames are plugin-generated opaque identifiers: sha256 over the
+ * identity tuple. Raw session ids, titles, or user input never become
+ * filenames, so there are no unsafe characters, no path traversal, and no
+ * leaked chat titles.
+ */
+import type { SnapshotIdentity } from "./fingerprint.js";
+/** One rolling snapshot per (session, route) pair by default (SPEC §41). */
+export declare function snapshotFilename(identity: SnapshotIdentity): string;
+/**
+ * Validate that a filename reaching the backend is plugin-shaped (SPEC §44):
+ * hex stem + `.bin`, no separators, no traversal. Defense in depth — the
+ * plugin never accepts external filenames, but the guard is cheap.
+ */
+export declare function assertPluginGeneratedFilename(filename: string): void;
+//# sourceMappingURL=naming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/snapshots/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAYnE;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMpE"}

package/lib/snapshots/naming.js

@@ -0,0 +1,33 @@
+/**
+ * Snapshot filename generation (SPEC §16, §41, Invariant 9).
+ *
+ * Filenames are plugin-generated opaque identifiers: sha256 over the
+ * identity tuple. Raw session ids, titles, or user input never become
+ * filenames, so there are no unsafe characters, no path traversal, and no
+ * leaked chat titles.
+ */
+import { sha256Hex } from "./fingerprint.js";
+import { KvInvariantError } from "../errors.js";
+/** One rolling snapshot per (session, route) pair by default (SPEC §41). */
+export function snapshotFilename(identity) {
+    const digest = sha256Hex([
+        identity.serverInstanceKey,
+        identity.provider,
+        identity.model,
+        identity.sessionId,
+    ].join("\u0000"));
+    // Sharded flat name: fixed length, safe characters, no directories needed
+    // by the server-side save path.
+    return `${digest}.bin`;
+}
+/**
+ * Validate that a filename reaching the backend is plugin-shaped (SPEC §44):
+ * hex stem + `.bin`, no separators, no traversal. Defense in depth — the
+ * plugin never accepts external filenames, but the guard is cheap.
+ */
+export function assertPluginGeneratedFilename(filename) {
+    if (!/^[0-9a-f]{64}\.bin$/.test(filename)) {
+        throw new KvInvariantError(`refusing non-plugin snapshot filename: ${JSON.stringify(filename.slice(0, 64))}`);
+    }
+}
+//# sourceMappingURL=naming.js.map

package/lib/snapshots/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../src/snapshots/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,QAA0B;IACzD,MAAM,MAAM,GAAG,SAAS,CACtB;QACE,QAAQ,CAAC,iBAAiB;QAC1B,QAAQ,CAAC,QAAQ;QACjB,QAAQ,CAAC,KAAK;QACd,QAAQ,CAAC,SAAS;KACnB,CAAC,IAAI,CAAC,QAAQ,CAAC,CACjB,CAAC;IACF,0EAA0E;IAC1E,gCAAgC;IAChC,OAAO,GAAG,MAAM,MAAM,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAgB;IAC5D,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,gBAAgB,CACxB,0CAA0C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAClF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/lib/snapshots/repository.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Local metadata repository (SPEC §39-§40).
+ *
+ * Layout below the metadata root (default `<$DSH_HOME>/cache/dsh-kv-persist`):
+ *
+ *   instances/<serverInstanceKey>/sessions/<snapshotDigest>.json
+ *
+ * Binary KV files never live here — they are owned by llama-server's
+ * `--slot-save-path` (SPEC §17). All writes are atomic: temp file + rename
+ * (SPEC §40), so a crash cannot leave half-written metadata that parses.
+ */
+import type { SnapshotInvalidationReason } from "../errors.js";
+import type { SnapshotManifest } from "./manifest.js";
+import type { SnapshotIdentity } from "./fingerprint.js";
+export interface RepositoryPutInput {
+    readonly identity: SnapshotIdentity;
+    readonly slotId: number;
+    readonly sessionSeq: number | null;
+    readonly tokens: number | null;
+    readonly bytes: number | null;
+    readonly now: string;
+}
+/** Manifest storage for one metadata root. */
+export declare class SnapshotRepository {
+    #private;
+    readonly root: string;
+    constructor(root: string);
+    /** Load the manifest for an identity; null when none exists. */
+    load(identity: SnapshotIdentity): Promise<SnapshotManifest | null>;
+    /** Create-or-update the manifest for an identity (atomic). */
+    put(input: RepositoryPutInput): Promise<SnapshotManifest>;
+    /** Flip a manifest to invalid without deleting anything (SPEC §31). */
+    markInvalid(identity: SnapshotIdentity, reason: SnapshotInvalidationReason, now: string): Promise<void>;
+    /** Remove a manifest (purge, SPEC §11); binary cleanup is backend-owned. */
+    remove(identity: SnapshotIdentity): Promise<boolean>;
+    /** Flip every manifest of a session to invalid (SPEC §31). */
+    invalidateSession(sessionId: string, reason: SnapshotInvalidationReason, now: string): Promise<number>;
+    /** Remove every manifest of a session across routes and instances. */
+    removeSession(sessionId: string): Promise<number>;
+    /**
+     * Find a ready, runtime-compatible manifest for the identity; incompatible
+     * manifests are marked invalid (SPEC §31) and ignored.
+     */
+    findCompatible(identity: SnapshotIdentity): Promise<SnapshotManifest | null>;
+    /** Aggregate manifest counts for the status API (SPEC §47). */
+    counts(): Promise<{
+        known: number;
+        valid: number;
+        invalid: number;
+    }>;
+}
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/snapshots/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAQD,8CAA8C;AAC9C,qBAAa,kBAAkB;;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;IAaxB,gEAAgE;IAC1D,IAAI,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAgBxE,8DAA8D;IACxD,GAAG,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0B/D,uEAAuE;IACjE,WAAW,CACf,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,0BAA0B,EAClC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAWhB,4EAA4E;IACtE,MAAM,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAW1D,8DAA8D;IACxD,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,0BAA0B,EAClC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC;IAelB,sEAAsE;IAChE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkDvD;;;OAGG;IACG,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAwBlF,+DAA+D;IACzD,MAAM,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAuD3E"}

package/lib/snapshots/repository.js

@@ -0,0 +1,270 @@
+/**
+ * Local metadata repository (SPEC §39-§40).
+ *
+ * Layout below the metadata root (default `<$DSH_HOME>/cache/dsh-kv-persist`):
+ *
+ *   instances/<serverInstanceKey>/sessions/<snapshotDigest>.json
+ *
+ * Binary KV files never live here — they are owned by llama-server's
+ * `--slot-save-path` (SPEC §17). All writes are atomic: temp file + rename
+ * (SPEC §40), so a crash cannot leave half-written metadata that parses.
+ */
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { KvMetadataIoError } from "../errors.js";
+import { parseManifest, createManifest } from "./manifest.js";
+import { snapshotFilename } from "./naming.js";
+function isNotFoundError(error) {
+    return (typeof error === "object" && error !== null && error.code === "ENOENT");
+}
+/** Manifest storage for one metadata root. */
+export class SnapshotRepository {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    #sessionsDir(instanceKey) {
+        return join(this.root, "instances", instanceKey, "sessions");
+    }
+    #manifestPath(identity) {
+        const digest = snapshotFilename(identity).replace(/\.bin$/, "");
+        return join(this.#sessionsDir(identity.serverInstanceKey), `${digest}.json`);
+    }
+    /** Load the manifest for an identity; null when none exists. */
+    async load(identity) {
+        const path = this.#manifestPath(identity);
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw new KvMetadataIoError(`cannot read manifest ${path}`, { cause: error });
+        }
+        try {
+            return parseManifest(JSON.parse(text));
+        }
+        catch (error) {
+            throw new KvMetadataIoError(`cannot parse manifest ${path}`, { cause: error });
+        }
+    }
+    /** Create-or-update the manifest for an identity (atomic). */
+    async put(input) {
+        const existing = await this.load(input.identity);
+        const manifest = existing
+            ? {
+                ...existing,
+                updatedAt: input.now,
+                slotId: input.slotId,
+                sessionSeq: input.sessionSeq,
+                tokens: input.tokens ?? existing.tokens,
+                bytes: input.bytes ?? existing.bytes,
+            }
+            : {
+                ...createManifest({
+                    identity: input.identity,
+                    slotId: input.slotId,
+                    snapshotFilename: snapshotFilename(input.identity),
+                    sessionSeq: input.sessionSeq,
+                    now: input.now,
+                }),
+                tokens: input.tokens,
+                bytes: input.bytes,
+            };
+        await this.#write(manifest);
+        return manifest;
+    }
+    /** Flip a manifest to invalid without deleting anything (SPEC §31). */
+    async markInvalid(identity, reason, now) {
+        const existing = await this.load(identity);
+        if (!existing || existing.state === "invalid")
+            return;
+        await this.#write({
+            ...existing,
+            state: "invalid",
+            invalidReason: reason,
+            updatedAt: now,
+        });
+    }
+    /** Remove a manifest (purge, SPEC §11); binary cleanup is backend-owned. */
+    async remove(identity) {
+        const path = this.#manifestPath(identity);
+        try {
+            await rm(path, { force: false });
+            return true;
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return false;
+            throw new KvMetadataIoError(`cannot remove manifest ${path}`, { cause: error });
+        }
+    }
+    /** Flip every manifest of a session to invalid (SPEC §31). */
+    async invalidateSession(sessionId, reason, now) {
+        let count = 0;
+        for (const manifest of await this.#listSessionManifests(sessionId)) {
+            if (manifest.state === "invalid")
+                continue;
+            await this.#write({
+                ...manifest,
+                state: "invalid",
+                invalidReason: reason,
+                updatedAt: now,
+            });
+            count += 1;
+        }
+        return count;
+    }
+    /** Remove every manifest of a session across routes and instances. */
+    async removeSession(sessionId) {
+        let count = 0;
+        for (const manifest of await this.#listSessionManifests(sessionId)) {
+            const identity = {
+                sessionId: manifest.sessionId,
+                provider: manifest.provider,
+                model: manifest.model,
+                backend: manifest.backend,
+                serverInstanceKey: manifest.serverInstanceKey,
+                compatibilityVersion: manifest.compatibilityVersion,
+            };
+            if (await this.remove(identity))
+                count += 1;
+        }
+        return count;
+    }
+    /** Every readable manifest of a session; unreadable entries are skipped. */
+    async #listSessionManifests(sessionId) {
+        const result = [];
+        const instancesDir = join(this.root, "instances");
+        let instanceKeys;
+        try {
+            instanceKeys = await readdir(instancesDir);
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return result;
+            throw new KvMetadataIoError(`cannot list ${instancesDir}`, { cause: error });
+        }
+        for (const instanceKey of instanceKeys) {
+            const sessionsDir = join(instancesDir, instanceKey, "sessions");
+            let files;
+            try {
+                files = await readdir(sessionsDir);
+            }
+            catch (error) {
+                if (isNotFoundError(error))
+                    continue;
+                throw new KvMetadataIoError(`cannot list ${sessionsDir}`, { cause: error });
+            }
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const path = join(sessionsDir, file);
+                try {
+                    const manifest = parseManifest(JSON.parse(await readFile(path, "utf8")));
+                    if (manifest.sessionId === sessionId)
+                        result.push(manifest);
+                }
+                catch {
+                    // Unreadable manifests are not session state; ignore here.
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Find a ready, runtime-compatible manifest for the identity; incompatible
+     * manifests are marked invalid (SPEC §31) and ignored.
+     */
+    async findCompatible(identity) {
+        const manifest = await this.load(identity);
+        if (!manifest)
+            return null;
+        const storedIdentity = {
+            sessionId: manifest.sessionId,
+            provider: manifest.provider,
+            model: manifest.model,
+            backend: manifest.backend,
+            serverInstanceKey: manifest.serverInstanceKey,
+            compatibilityVersion: manifest.compatibilityVersion,
+        };
+        const compatibleShape = storedIdentity.serverInstanceKey === identity.serverInstanceKey &&
+            storedIdentity.provider === identity.provider &&
+            storedIdentity.model === identity.model;
+        if (!compatibleShape)
+            return null;
+        if (manifest.state !== "ready")
+            return null;
+        if (storedIdentity.compatibilityVersion !== identity.compatibilityVersion) {
+            await this.markInvalid(identity, "MODEL_FINGERPRINT_CHANGED", new Date().toISOString());
+            return null;
+        }
+        return manifest;
+    }
+    /** Aggregate manifest counts for the status API (SPEC §47). */
+    async counts() {
+        const result = { known: 0, valid: 0, invalid: 0 };
+        const instancesDir = join(this.root, "instances");
+        let instanceKeys;
+        try {
+            instanceKeys = await readdir(instancesDir);
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return result;
+            throw new KvMetadataIoError(`cannot list ${instancesDir}`, { cause: error });
+        }
+        for (const instanceKey of instanceKeys) {
+            const sessionsDir = join(instancesDir, instanceKey, "sessions");
+            let files;
+            try {
+                files = await readdir(sessionsDir);
+            }
+            catch (error) {
+                if (isNotFoundError(error))
+                    continue;
+                throw new KvMetadataIoError(`cannot list ${sessionsDir}`, { cause: error });
+            }
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                result.known += 1;
+                try {
+                    const text = await readFile(join(sessionsDir, file), "utf8");
+                    const manifest = parseManifest(JSON.parse(text));
+                    if (manifest.state === "ready")
+                        result.valid += 1;
+                    else
+                        result.invalid += 1;
+                }
+                catch {
+                    result.invalid += 1;
+                }
+            }
+        }
+        return result;
+    }
+    async #write(manifest) {
+        const identity = {
+            sessionId: manifest.sessionId,
+            provider: manifest.provider,
+            model: manifest.model,
+            backend: manifest.backend,
+            serverInstanceKey: manifest.serverInstanceKey,
+            compatibilityVersion: manifest.compatibilityVersion,
+        };
+        const path = this.#manifestPath(identity);
+        const tmpPath = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`;
+        try {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(tmpPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+            await rename(tmpPath, path);
+        }
+        catch (error) {
+            await rm(tmpPath, { force: true }).catch(() => { });
+            throw new KvMetadataIoError(`cannot write manifest ${path}`, { cause: error });
+        }
+    }
+}
+//# sourceMappingURL=repository.js.map

package/lib/snapshots/repository.js.map

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

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@yadsh/dsh-kv-persist",
+  "version": "0.1.0",
+  "description": "Persistent KV-cache/session-state manager for DeepSeek Harness (llama.cpp slot snapshots)",
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "kv-cache",
+    "llama-cpp",
+    "persistence"
+  ],
+  "homepage": "https://github.com/xarleyn/dsh-plugins/tree/main/plugins/dsh-kv-persist#readme",
+  "bugs": {
+    "url": "https://github.com/xarleyn/dsh-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xarleyn/dsh-plugins.git",
+    "directory": "plugins/dsh-kv-persist"
+  },
+  "license": "MIT",
+  "author": "xarleyn",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "compatibility.json",
+    "docs/dsh-kv-persist.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:llama": "vitest run test/integration/llama-server.test.ts",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify": "npm run verify:package",
+    "check": "npm run typecheck && npm test && npm run build && npm run verify"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "catalog:dsh",
+    "@deepseek-ai/dsh-llm": "catalog:dsh",
+    "@deepseek-ai/schemastery": "catalog:dsh"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-llm": "catalog:dsh-dev",
+    "@deepseek-ai/schemastery": "catalog:dsh-dev",
+    "@types/node": "catalog:tooling",
+    "@yadsh/dsh-config": "workspace:^",
+    "eslint": "catalog:tooling",
+    "typescript": "catalog:tooling",
+    "vitest": "catalog:tooling"
+  },
+  "dependencies": {
+    "pino": "^10.3.1"
+  }
+}