@yadsh/dsh-kv-persist 0.1.0

package/lib/coordinator/slot-lease.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Slot mutex (SPEC §20, Invariant 8).
+ *
+ * No two operations may concurrently mutate the same physical slot:
+ * restore, erase, inference, and save all run inside one exclusive lease.
+ * For v0.1 a single promise-chain mutex per server is sufficient.
+ */
+/**
+ * Serialize async work: every `runExclusive` body starts only after all
+ * previously queued bodies finished (successfully or not). Bodies must not
+ * re-enter `runExclusive` on the same mutex — that deadlocks by design, and
+ * the invariant violation would be a plugin bug, not a runtime condition.
+ */
+export declare class SlotMutex {
+    #private;
+    constructor(name: string);
+    /** Diagnostic: whether any lease is queued or running. */
+    get held(): boolean;
+    get name(): string;
+    runExclusive<T>(body: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=slot-lease.d.ts.map

package/lib/coordinator/slot-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-lease.d.ts","sourceRoot":"","sources":["../../src/coordinator/slot-lease.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,qBAAa,SAAS;;gBAKR,IAAI,EAAE,MAAM;IAIxB,0DAA0D;IAC1D,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAYpD"}

package/lib/coordinator/slot-lease.js

@@ -0,0 +1,38 @@
+/**
+ * Slot mutex (SPEC §20, Invariant 8).
+ *
+ * No two operations may concurrently mutate the same physical slot:
+ * restore, erase, inference, and save all run inside one exclusive lease.
+ * For v0.1 a single promise-chain mutex per server is sufficient.
+ */
+/**
+ * Serialize async work: every `runExclusive` body starts only after all
+ * previously queued bodies finished (successfully or not). Bodies must not
+ * re-enter `runExclusive` on the same mutex — that deadlocks by design, and
+ * the invariant violation would be a plugin bug, not a runtime condition.
+ */
+export class SlotMutex {
+    #name;
+    #tail = Promise.resolve();
+    #depth = 0;
+    constructor(name) {
+        this.#name = name;
+    }
+    /** Diagnostic: whether any lease is queued or running. */
+    get held() {
+        return this.#depth > 0;
+    }
+    get name() {
+        return this.#name;
+    }
+    runExclusive(body) {
+        this.#depth += 1;
+        const result = this.#tail.then(body, body);
+        this.#tail = result.then(() => undefined, () => undefined);
+        void this.#tail.then(() => {
+            this.#depth = Math.max(0, this.#depth - 1);
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=slot-lease.js.map

package/lib/coordinator/slot-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-lease.js","sourceRoot":"","sources":["../../src/coordinator/slot-lease.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IACX,KAAK,CAAS;IACvB,KAAK,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5C,MAAM,GAAG,CAAC,CAAC;IAEX,YAAY,IAAY;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,0DAA0D;IAC1D,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,YAAY,CAAI,IAAsB;QACpC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CACtB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE;YACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/lib/coordinator/state-machine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Session and slot state machines (SPEC §18-§19).
+ *
+ * Pure state + transition helpers; the coordinator owns the transitions.
+ * These types also back the status/diagnostics API (SPEC §47).
+ */
+/** Session-side lifecycle state (SPEC §18). */
+export type SessionKvLifecycle = "none" | "cold" | "restoring" | "active-clean" | "active-dirty" | "saving" | "saved" | "invalid";
+/** Physical slot state (SPEC §19). */
+export type SlotState = "unknown" | "idle" | "restoring" | "ready" | "inference" | "dirty" | "saving" | "broken";
+/** The one managed physical slot of v0.1 (SPEC §19, §7). */
+export interface ManagedSlot {
+    readonly id: number;
+    /** Session that currently owns the slot, when any. */
+    ownerSessionId: string | null;
+    /** Dirty generation at the time the slot state was last established. */
+    snapshotRevision: string | null;
+    state: SlotState;
+    lastUsedAt: number | null;
+}
+/** Runtime bookkeeping for one known session (SPEC §27-§28). */
+export interface SessionRuntime {
+    readonly sessionId: string;
+    /** Route of the latest request (provider + model, SPEC §56). */
+    route: {
+        provider: string;
+        model: string;
+    };
+    /** Monotonic dirty generation: increments on every successful inference. */
+    dirtyRevision: number;
+    /** Generation covered by the latest durable snapshot. */
+    persistedRevision: number;
+    /** In-flight save for the current generation, when any (SPEC §27). */
+    saveInFlight: Promise<SnapshotResult> | null;
+    lifecycle: SessionKvLifecycle;
+}
+/** Result of a save operation (SPEC §11). */
+export interface SnapshotResult {
+    readonly kind: "saved" | "skipped-clean" | "skipped-not-owner" | "failed";
+    readonly sessionId: string;
+    readonly revision: number;
+    readonly bytes: number | null;
+    readonly error: string | null;
+}
+/** Result of a restore attempt (SPEC §23). */
+export interface RestoreOutcome {
+    readonly kind: "already-active" | "cold" | "restored" | "cold-fallback";
+    readonly sessionId: string;
+    readonly tokens: number | null;
+    readonly bytes: number | null;
+    readonly durationMs: number | null;
+    readonly error: string | null;
+}
+export declare function createManagedSlot(id: number): ManagedSlot;
+export declare function createSessionRuntime(sessionId: string, route: {
+    provider: string;
+    model: string;
+}): SessionRuntime;
+/** Dirty in the generation sense (SPEC §28), not a boolean. */
+export declare function isDirty(runtime: SessionRuntime): boolean;
+/** Record a completed successful inference: bump the dirty generation. */
+export declare function markDirty(runtime: SessionRuntime): void;
+/** Record a durable snapshot covering `revision`. */
+export declare function markPersisted(runtime: SessionRuntime, revision: number): void;
+//# sourceMappingURL=state-machine.d.ts.map

package/lib/coordinator/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/coordinator/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,MAAM,GACN,WAAW,GACX,cAAc,GACd,cAAc,GACd,QAAQ,GACR,OAAO,GACP,SAAS,CAAC;AAEd,sCAAsC;AACtC,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,MAAM,GACN,WAAW,GACX,OAAO,GACP,WAAW,GACX,OAAO,GACP,QAAQ,GACR,QAAQ,CAAC;AAEb,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;IAC7C,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,mBAAmB,GAAG,QAAQ,CAAC;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,eAAe,CAAC;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAQzD;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC,cAAc,CAShB;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAExD;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAGvD;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAG7E"}

package/lib/coordinator/state-machine.js

@@ -0,0 +1,40 @@
+/**
+ * Session and slot state machines (SPEC §18-§19).
+ *
+ * Pure state + transition helpers; the coordinator owns the transitions.
+ * These types also back the status/diagnostics API (SPEC §47).
+ */
+export function createManagedSlot(id) {
+    return {
+        id,
+        ownerSessionId: null,
+        snapshotRevision: null,
+        state: "unknown",
+        lastUsedAt: null,
+    };
+}
+export function createSessionRuntime(sessionId, route) {
+    return {
+        sessionId,
+        route: { ...route },
+        dirtyRevision: 0,
+        persistedRevision: 0,
+        saveInFlight: null,
+        lifecycle: "none",
+    };
+}
+/** Dirty in the generation sense (SPEC §28), not a boolean. */
+export function isDirty(runtime) {
+    return runtime.dirtyRevision > runtime.persistedRevision;
+}
+/** Record a completed successful inference: bump the dirty generation. */
+export function markDirty(runtime) {
+    runtime.dirtyRevision += 1;
+    runtime.lifecycle = "active-dirty";
+}
+/** Record a durable snapshot covering `revision`. */
+export function markPersisted(runtime, revision) {
+    runtime.persistedRevision = Math.max(runtime.persistedRevision, revision);
+    runtime.lifecycle = isDirty(runtime) ? "active-dirty" : "saved";
+}
+//# sourceMappingURL=state-machine.js.map

package/lib/coordinator/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/coordinator/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoEH,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,OAAO;QACL,EAAE;QACF,cAAc,EAAE,IAAI;QACpB,gBAAgB,EAAE,IAAI;QACtB,KAAK,EAAE,SAAS;QAChB,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,KAA0C;IAE1C,OAAO;QACL,SAAS;QACT,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE;QACnB,aAAa,EAAE,CAAC;QAChB,iBAAiB,EAAE,CAAC;QACpB,YAAY,EAAE,IAAI;QAClB,SAAS,EAAE,MAAM;KAClB,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,OAAO,CAAC,OAAuB;IAC7C,OAAO,OAAO,CAAC,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;AAC3D,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,OAAuB;IAC/C,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,SAAS,GAAG,cAAc,CAAC;AACrC,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,OAAuB,EAAE,QAAgB;IACrE,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;IAC1E,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC;AAClE,CAAC"}

package/lib/errors.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Error taxonomy for the kv-persist plugin (SPEC §79).
+ *
+ * Every failure carries a stable machine-readable `code`; messages are for
+ * humans. Per the failure policy (SPEC §32) these errors normally degrade to
+ * cold inference — only `strict: true` turns them into request failures.
+ */
+export type KvPersistErrorCode = "KV_BACKEND_UNAVAILABLE" | "KV_BACKEND_UNSUPPORTED" | "KV_SLOT_NOT_FOUND" | "KV_SLOT_BUSY" | "KV_SLOT_STATE_INVALID" | "KV_SNAPSHOT_NOT_FOUND" | "KV_SNAPSHOT_INCOMPATIBLE" | "KV_SNAPSHOT_CORRUPT" | "KV_SAVE_FAILED" | "KV_RESTORE_FAILED" | "KV_ERASE_FAILED" | "KV_MANIFEST_INVALID" | "KV_METADATA_IO" | "KV_OPERATION_TIMEOUT" | "KV_INVARIANT";
+/** Base class of every typed kv-persist error. */
+export declare class KvPersistError extends Error {
+    readonly code: KvPersistErrorCode;
+    constructor(code: KvPersistErrorCode, message: string, options?: ErrorOptions);
+}
+/** The llama server or its slots endpoint cannot be reached. */
+export declare class KvBackendUnavailableError extends KvPersistError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The configured backend type does not expose the required slot surface. */
+export declare class KvBackendUnsupportedError extends KvPersistError {
+    constructor(message: string);
+}
+/** A slot operation referenced a slot the server does not have. */
+export declare class KvSlotNotFoundError extends KvPersistError {
+    readonly slotId: number;
+    constructor(slotId: number, message?: string);
+}
+/** A slot is busy with another exclusive operation. */
+export declare class KvSlotBusyError extends KvPersistError {
+    readonly slotId: number;
+    constructor(slotId: number, message?: string);
+}
+/** The slot exists but its reported state cannot be used safely. */
+export declare class KvSlotStateInvalidError extends KvPersistError {
+    readonly slotId: number;
+    constructor(slotId: number, message: string);
+}
+/** The requested snapshot does not exist. */
+export declare class KvSnapshotNotFoundError extends KvPersistError {
+    constructor(message: string);
+}
+/** A snapshot exists but its runtime identity is incompatible. */
+export declare class KvSnapshotIncompatibleError extends KvPersistError {
+    constructor(message: string);
+}
+/** A snapshot exists but cannot be used (corrupt, truncated, failed restore). */
+export declare class KvSnapshotCorruptError extends KvPersistError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A save operation failed on the backend. */
+export declare class KvSaveFailedError extends KvPersistError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A restore operation failed on the backend. */
+export declare class KvRestoreFailedError extends KvPersistError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** An erase operation failed on the backend. */
+export declare class KvEraseFailedError extends KvPersistError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A snapshot manifest exists but fails schema validation. */
+export declare class KvManifestInvalidError extends KvPersistError {
+    constructor(message: string);
+}
+/** Local metadata storage could not be read or written. */
+export declare class KvMetadataIoError extends KvPersistError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** A persistence operation exceeded its own bounded timeout (SPEC §59). */
+export declare class KvOperationTimeoutError extends KvPersistError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** An internal invariant was violated; always a plugin bug. */
+export declare class KvInvariantError extends KvPersistError {
+    constructor(message: string);
+}
+/**
+ * Why a snapshot was invalidated (SPEC §31). Invalidation never deletes
+ * binary data; it only flips manifest state so cleanup can happen later.
+ */
+export type SnapshotInvalidationReason = "MODEL_FINGERPRINT_CHANGED" | "RESTORE_FAILED" | "MANIFEST_MALFORMED" | "SNAPSHOT_FILE_MISSING" | "EXPLICIT";
+//# sourceMappingURL=errors.d.ts.map

package/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,wBAAwB,GACxB,wBAAwB,GACxB,mBAAmB,GACnB,cAAc,GACd,uBAAuB,GACvB,uBAAuB,GACvB,0BAA0B,GAC1B,qBAAqB,GACrB,gBAAgB,GAChB,mBAAmB,GACnB,iBAAiB,GACjB,qBAAqB,GACrB,gBAAgB,GAChB,sBAAsB,GACtB,cAAc,CAAC;AAEnB,kDAAkD;AAClD,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;gBAEtB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAK9E;AAED,gEAAgE;AAChE,qBAAa,yBAA0B,SAAQ,cAAc;gBAC/C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,6EAA6E;AAC7E,qBAAa,yBAA0B,SAAQ,cAAc;gBAC/C,OAAO,EAAE,MAAM;CAG5B;AAED,mEAAmE;AACnE,qBAAa,mBAAoB,SAAQ,cAAc;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAI7C;AAED,uDAAuD;AACvD,qBAAa,eAAgB,SAAQ,cAAc;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAI7C;AAED,oEAAoE;AACpE,qBAAa,uBAAwB,SAAQ,cAAc;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI5C;AAED,6CAA6C;AAC7C,qBAAa,uBAAwB,SAAQ,cAAc;gBAC7C,OAAO,EAAE,MAAM;CAG5B;AAED,kEAAkE;AAClE,qBAAa,2BAA4B,SAAQ,cAAc;gBACjD,OAAO,EAAE,MAAM;CAG5B;AAED,iFAAiF;AACjF,qBAAa,sBAAuB,SAAQ,cAAc;gBAC5C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,8CAA8C;AAC9C,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,iDAAiD;AACjD,qBAAa,oBAAqB,SAAQ,cAAc;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,gDAAgD;AAChD,qBAAa,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,8DAA8D;AAC9D,qBAAa,sBAAuB,SAAQ,cAAc;gBAC5C,OAAO,EAAE,MAAM;CAG5B;AAED,2DAA2D;AAC3D,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,2EAA2E;AAC3E,qBAAa,uBAAwB,SAAQ,cAAc;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAGpD;AAED,+DAA+D;AAC/D,qBAAa,gBAAiB,SAAQ,cAAc;gBACtC,OAAO,EAAE,MAAM;CAG5B;AAED;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAClC,2BAA2B,GAC3B,gBAAgB,GAChB,oBAAoB,GACpB,uBAAuB,GACvB,UAAU,CAAC"}

package/lib/errors.js

@@ -0,0 +1,113 @@
+/**
+ * Error taxonomy for the kv-persist plugin (SPEC §79).
+ *
+ * Every failure carries a stable machine-readable `code`; messages are for
+ * humans. Per the failure policy (SPEC §32) these errors normally degrade to
+ * cold inference — only `strict: true` turns them into request failures.
+ */
+/** Base class of every typed kv-persist error. */
+export class KvPersistError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+/** The llama server or its slots endpoint cannot be reached. */
+export class KvBackendUnavailableError extends KvPersistError {
+    constructor(message, options) {
+        super("KV_BACKEND_UNAVAILABLE", message, options);
+    }
+}
+/** The configured backend type does not expose the required slot surface. */
+export class KvBackendUnsupportedError extends KvPersistError {
+    constructor(message) {
+        super("KV_BACKEND_UNSUPPORTED", message);
+    }
+}
+/** A slot operation referenced a slot the server does not have. */
+export class KvSlotNotFoundError extends KvPersistError {
+    slotId;
+    constructor(slotId, message) {
+        super("KV_SLOT_NOT_FOUND", message ?? `slot ${slotId} not found on the server`);
+        this.slotId = slotId;
+    }
+}
+/** A slot is busy with another exclusive operation. */
+export class KvSlotBusyError extends KvPersistError {
+    slotId;
+    constructor(slotId, message) {
+        super("KV_SLOT_BUSY", message ?? `slot ${slotId} is busy`);
+        this.slotId = slotId;
+    }
+}
+/** The slot exists but its reported state cannot be used safely. */
+export class KvSlotStateInvalidError extends KvPersistError {
+    slotId;
+    constructor(slotId, message) {
+        super("KV_SLOT_STATE_INVALID", message);
+        this.slotId = slotId;
+    }
+}
+/** The requested snapshot does not exist. */
+export class KvSnapshotNotFoundError extends KvPersistError {
+    constructor(message) {
+        super("KV_SNAPSHOT_NOT_FOUND", message);
+    }
+}
+/** A snapshot exists but its runtime identity is incompatible. */
+export class KvSnapshotIncompatibleError extends KvPersistError {
+    constructor(message) {
+        super("KV_SNAPSHOT_INCOMPATIBLE", message);
+    }
+}
+/** A snapshot exists but cannot be used (corrupt, truncated, failed restore). */
+export class KvSnapshotCorruptError extends KvPersistError {
+    constructor(message, options) {
+        super("KV_SNAPSHOT_CORRUPT", message, options);
+    }
+}
+/** A save operation failed on the backend. */
+export class KvSaveFailedError extends KvPersistError {
+    constructor(message, options) {
+        super("KV_SAVE_FAILED", message, options);
+    }
+}
+/** A restore operation failed on the backend. */
+export class KvRestoreFailedError extends KvPersistError {
+    constructor(message, options) {
+        super("KV_RESTORE_FAILED", message, options);
+    }
+}
+/** An erase operation failed on the backend. */
+export class KvEraseFailedError extends KvPersistError {
+    constructor(message, options) {
+        super("KV_ERASE_FAILED", message, options);
+    }
+}
+/** A snapshot manifest exists but fails schema validation. */
+export class KvManifestInvalidError extends KvPersistError {
+    constructor(message) {
+        super("KV_MANIFEST_INVALID", message);
+    }
+}
+/** Local metadata storage could not be read or written. */
+export class KvMetadataIoError extends KvPersistError {
+    constructor(message, options) {
+        super("KV_METADATA_IO", message, options);
+    }
+}
+/** A persistence operation exceeded its own bounded timeout (SPEC §59). */
+export class KvOperationTimeoutError extends KvPersistError {
+    constructor(message, options) {
+        super("KV_OPERATION_TIMEOUT", message, options);
+    }
+}
+/** An internal invariant was violated; always a plugin bug. */
+export class KvInvariantError extends KvPersistError {
+    constructor(message) {
+        super("KV_INVARIANT", message);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/lib/errors.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * dsh-kv-persist — persistent KV-cache/session-state manager (SPEC §1).
+ *
+ * The Cordis entrypoint: registers `ctx.kvPersist`, the `llm/stream`
+ * coordination wrapper, and the session lifecycle listeners. All logic
+ * lives in the domain modules (SPEC §10).
+ */
+import { KvPersistService } from "./service.js";
+export { KvPersistService } from "./service.js";
+export type { KvPersistStatus, SessionKvState, KvPersistDoctorReport, KvPersistServiceDeps, } from "./service.js";
+export { resolveKvPersistConfig, isManagedProvider, KvPersistConfigSchema } from "./config.js";
+export type { KvPersistConfig, ResolvedKvPersistConfig } from "./config.js";
+export { KvPersistError, KvBackendUnavailableError, KvBackendUnsupportedError, KvSaveFailedError, KvRestoreFailedError, KvEraseFailedError, } from "./errors.js";
+export type { KvPersistErrorCode, SnapshotInvalidationReason } from "./errors.js";
+export type { KvPersistenceBackend, BackendCapabilities } from "./backends/types.js";
+export { LlamaCppBackend } from "./backends/llama-cpp/backend.js";
+export { SingleSlotCoordinator } from "./coordinator/coordinator.js";
+export { SnapshotRepository } from "./snapshots/repository.js";
+export { snapshotFilename } from "./snapshots/naming.js";
+declare module "@deepseek-ai/cordis" {
+    interface Context {
+        kvPersist: KvPersistService;
+    }
+}
+export default KvPersistService;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EACV,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC/F,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAClF,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,SAAS,EAAE,gBAAgB,CAAC;KAC7B;CACF;AAED,eAAe,gBAAgB,CAAC"}

package/lib/index.js

@@ -0,0 +1,17 @@
+/**
+ * dsh-kv-persist — persistent KV-cache/session-state manager (SPEC §1).
+ *
+ * The Cordis entrypoint: registers `ctx.kvPersist`, the `llm/stream`
+ * coordination wrapper, and the session lifecycle listeners. All logic
+ * lives in the domain modules (SPEC §10).
+ */
+import { KvPersistService } from "./service.js";
+export { KvPersistService } from "./service.js";
+export { resolveKvPersistConfig, isManagedProvider, KvPersistConfigSchema } from "./config.js";
+export { KvPersistError, KvBackendUnavailableError, KvBackendUnsupportedError, KvSaveFailedError, KvRestoreFailedError, KvEraseFailedError, } from "./errors.js";
+export { LlamaCppBackend } from "./backends/llama-cpp/backend.js";
+export { SingleSlotCoordinator } from "./coordinator/coordinator.js";
+export { SnapshotRepository } from "./snapshots/repository.js";
+export { snapshotFilename } from "./snapshots/naming.js";
+export default KvPersistService;
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOhD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE/F,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAQzD,eAAe,gBAAgB,CAAC"}

package/lib/logging/dsh-home.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DSH home resolution for plugin runtime helpers.
+ *
+ * Part of the future `@yadsh/dsh-plugin-log` package seed: this folder is a
+ * verbatim, self-contained copy in every adopting plugin (guidelines §5.2),
+ * so keep it free of imports outside `./`.
+ */
+/**
+ * Resolve the DSH home directory: `$DSH_HOME` when set to a non-blank value,
+ * otherwise `~/.dsh` (the same convention as `dsh-draft-sessions` storage).
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=dsh-home.d.ts.map

package/lib/logging/dsh-home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh-home.d.ts","sourceRoot":"","sources":["../../src/logging/dsh-home.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG3E"}

package/lib/logging/dsh-home.js

@@ -0,0 +1,18 @@
+/**
+ * DSH home resolution for plugin runtime helpers.
+ *
+ * Part of the future `@yadsh/dsh-plugin-log` package seed: this folder is a
+ * verbatim, self-contained copy in every adopting plugin (guidelines §5.2),
+ * so keep it free of imports outside `./`.
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/**
+ * Resolve the DSH home directory: `$DSH_HOME` when set to a non-blank value,
+ * otherwise `~/.dsh` (the same convention as `dsh-draft-sessions` storage).
+ */
+export function resolveDshHome(env = process.env) {
+    const configured = env.DSH_HOME?.trim();
+    return configured ? resolve(configured) : join(homedir(), ".dsh");
+}
+//# sourceMappingURL=dsh-home.js.map

package/lib/logging/dsh-home.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh-home.js","sourceRoot":"","sources":["../../src/logging/dsh-home.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAyB,OAAO,CAAC,GAAG;IACjE,MAAM,UAAU,GAAG,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxC,OAAO,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC"}

package/lib/logging/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Plugin logging bundle (future `@yadsh/dsh-plugin-log`).
+ *
+ * Self-contained by design: every import stays inside this folder so the
+ * whole directory can be copied between plugins verbatim, or replaced by the
+ * extracted package import once it exists.
+ */
+export * from "./dsh-home.js";
+export * from "./plugin-logger.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/logging/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/lib/logging/index.js

@@ -0,0 +1,10 @@
+/**
+ * Plugin logging bundle (future `@yadsh/dsh-plugin-log`).
+ *
+ * Self-contained by design: every import stays inside this folder so the
+ * whole directory can be copied between plugins verbatim, or replaced by the
+ * extracted package import once it exists.
+ */
+export * from "./dsh-home.js";
+export * from "./plugin-logger.js";
+//# sourceMappingURL=index.js.map

package/lib/logging/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/lib/logging/plugin-logger.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Plugin file logger — the seed of the future `@yadsh/dsh-plugin-log` package.
+ *
+ * Every plugin currently carries its own verbatim copy of `src/logging/`
+ * (guidelines §5.2); the exported API below is frozen so that switching to
+ * the extracted package later is a one-line import change. The wrapper:
+ *
+ * - wraps `pino` for severity levels and NDJSON serialization;
+ * - writes daily files `<dir>/<YYYY-MM-DD>.log`, by default under
+ *   `<$DSH_HOME>/logs/<pluginId>`;
+ * - mirrors selected records to an injectable console sink (default level
+ *   `warn`) so operators still see problems live;
+ * - never throws at runtime: file-system failures degrade to console-only
+ *   logging (fail-open), and closed loggers silently drop records;
+ * - disables file output when `DSH_LOG_DISABLED=1`, and under `NODE_ENV=test`
+ *   unless `dir` is set explicitly (unit tests never touch a real home).
+ *
+ * Record shape (one JSON object per line): pino's `level` (numeric),
+ * `time` (epoch ms) and `msg` (= the event code), plus `plugin` and the
+ * caller's fields; `child(module)` adds `module`. Reserved pino keys
+ * (`level`, `time`, `msg`, `plugin`, `module`) must not be used as field
+ * names.
+ */
+/** Ordered severity levels; `silent` disables the logger entirely. */
+export declare const PLUGIN_LOG_LEVELS: readonly ["trace", "debug", "info", "warn", "error", "fatal", "silent"];
+export type PluginLogLevel = (typeof PLUGIN_LOG_LEVELS)[number];
+/** Every level except `silent` (which also disables the console mirror). */
+export type ConsoleLevel = Exclude<PluginLogLevel, "silent">;
+/**
+ * Receives console-mirrored records. Must not throw; the wrapper guards every
+ * call regardless.
+ */
+export type PluginConsoleSink = (level: ConsoleLevel, message: string) => void;
+/** Default console mirror threshold. */
+export declare const DEFAULT_CONSOLE_LEVEL: PluginLogLevel;
+/** Daily log files kept per plugin by default (0 = keep forever). */
+export declare const DEFAULT_LOG_RETENTION_DAYS = 14;
+/** Type guard for level strings (config parsing, env overrides). */
+export declare function isPluginLogLevel(value: unknown): value is PluginLogLevel;
+/** Logger configuration; every field except `pluginId` is optional. */
+export interface PluginLoggerOptions {
+    /**
+     * Plugin id: directory name, `plugin` record field and env-prefix source
+     * (`DSH_LOG_LEVEL_<ID>`). Must match `[A-Za-z0-9][A-Za-z0-9._-]*`.
+     */
+    readonly pluginId: string;
+    /** Severity threshold. Default: `DSH_LOG_LEVEL_<ID>` / `DSH_LOG_LEVEL` env, else `info`. */
+    readonly level?: PluginLogLevel;
+    /** Absolute log directory. Default: `<$DSH_HOME>/logs/<pluginId>`. */
+    readonly dir?: string;
+    /** Overrides the DSH home used to build the default `dir` (tests). */
+    readonly dshHome?: string;
+    /** Console mirror threshold; `silent` disables mirroring. Default: `warn`. */
+    readonly console?: PluginLogLevel;
+    /** Mirror target. Default: the global `console`. */
+    readonly consoleSink?: PluginConsoleSink;
+    /** Daily files older than this are deleted on rollover. Default: 14; 0 disables. */
+    readonly retentionDays?: number;
+    /** Master switch for file output. Default: auto (see the module docs). */
+    readonly file?: boolean;
+    /** Record fields to redact (pino `redact` paths), e.g. `["apiKey"]`. */
+    readonly redact?: readonly string[];
+    /** Clock for file naming, rollover and retention (tests). */
+    readonly now?: () => number;
+}
+/** Stable logging surface shared by every plugin (future package contract). */
+export interface PluginLogger {
+    trace(event: string, fields?: Record<string, unknown>): void;
+    debug(event: string, fields?: Record<string, unknown>): void;
+    info(event: string, fields?: Record<string, unknown>): void;
+    warn(event: string, fields?: Record<string, unknown>): void;
+    error(event: string, fields?: Record<string, unknown>): void;
+    fatal(event: string, fields?: Record<string, unknown>): void;
+    /** Bound sub-logger that adds a `module` field to every record. */
+    child(module: string): PluginLogger;
+    /** Current severity threshold. */
+    get level(): PluginLogLevel;
+    /** Change the severity threshold at runtime. */
+    setLevel(level: PluginLogLevel): void;
+    /** Best-effort synchronous flush of buffered file output. */
+    flush(): void;
+    /** Flush and close the destination; idempotent; later writes are dropped. */
+    close(): Promise<void>;
+}
+/** Create a standalone logger instance (no caching). */
+export declare function createPluginLogger(options: PluginLoggerOptions): PluginLogger;
+/**
+ * Create or return the cached logger for `pluginId` + resolved `dir`. A later
+ * call with an explicit `level` updates the cached instance's threshold, so
+ * plugin config reloads take effect. `close()` evicts the cache entry; the
+ * next call creates a fresh instance.
+ */
+export declare function getPluginLogger(options: PluginLoggerOptions): PluginLogger;
+//# sourceMappingURL=plugin-logger.d.ts.map

package/lib/logging/plugin-logger.d.ts.map

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