@yadsh/dsh-kv-persist 0.1.0

package/lib/config.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Configuration surface of the kv-persist plugin (SPEC §35-§37).
+ *
+ * The Schemastery schema in `index.ts` is the user-facing contract; this
+ * module resolves raw config into fully defaulted, validated values so the
+ * rest of the plugin never deals with optional fields.
+ */
+import z from "@deepseek-ai/schemastery";
+/** Raw user-facing configuration (SPEC §36). */
+export interface KvPersistConfig {
+    /** Master switch; when false the plugin passes every request through. */
+    readonly enabled?: boolean;
+    /** llama.cpp server connection. */
+    readonly backend?: {
+        readonly type?: "llama.cpp";
+        readonly baseURL?: string;
+        /** Management-API key; never logged. */
+        readonly apiKey?: string;
+        /** Bounded timeout for every persistence HTTP call (SPEC §59). */
+        readonly requestTimeoutMs?: number;
+    };
+    /**
+     * Explicit managed provider routes (SPEC §37). Requests to any other
+     * provider pass through untouched. Default: none (plugin inert).
+     */
+    readonly providers?: readonly string[];
+    /** v0.1 supports single-slot only (SPEC §8). */
+    readonly mode?: "single-slot" | "managed-slots";
+    /** Physical slot used in single-slot mode. */
+    readonly slotId?: number;
+    /**
+     * Manual runtime identity escape hatch (SPEC §15): changing it makes all
+     * previously saved snapshots invisible without deleting them.
+     */
+    readonly runtimeKey?: string;
+    /** Checkpoint policy (SPEC §26). */
+    readonly checkpoint?: {
+        /** Save a dirty slot before reassigning it. Default: true. */
+        readonly onSwitch?: boolean;
+        /** Final checkpoint during Cordis disposal. Default: true. */
+        readonly onShutdown?: boolean;
+        /** Checkpoint on the session/flush durability event. Default: true. */
+        readonly onSessionFlush?: boolean;
+        /** Save dirty state after this many idle milliseconds; 0 disables. Default: 30000. */
+        readonly idleMs?: number;
+        /** Checkpoint after every completed user turn. Default: false. */
+        readonly onTurnEnd?: boolean;
+        /** Reserved for future per-step checkpoints. Default: false. */
+        readonly onStepEnd?: boolean;
+    };
+    /** Restore behavior (SPEC §23-§24). */
+    readonly restore?: {
+        /** Restore compatible snapshots before a session's first request. Default: true. */
+        readonly enabled?: boolean;
+        /** Validate restored state (n_restored) after an HTTP 200. Default: true. */
+        readonly verify?: boolean;
+    };
+    /** Failure policy and circuit breaker (SPEC §32-§33). */
+    readonly failure?: {
+        /** Turn persistence failures into request failures. Default: false. */
+        readonly strict?: boolean;
+        /** Consecutive failures before the circuit opens. Default: 3. */
+        readonly maxConsecutiveFailures?: number;
+        /** Circuit open duration in milliseconds. Default: 60000. */
+        readonly cooldownMs?: number;
+    };
+    /** Local metadata storage (SPEC §39). */
+    readonly metadata?: {
+        /** Absolute metadata directory; blank uses `<$DSH_HOME>/cache/dsh-kv-persist`. */
+        readonly path?: string;
+    };
+    /** Structured logging verbosity. */
+    readonly logging?: {
+        /** `debug`, `info`, or `off`. Default: `info`. */
+        readonly level?: "debug" | "info" | "off";
+    };
+}
+/** Fully resolved configuration. */
+export interface ResolvedKvPersistConfig {
+    readonly enabled: boolean;
+    readonly backendType: "llama.cpp";
+    readonly baseURL: string;
+    readonly apiKey: string | null;
+    readonly requestTimeoutMs: number;
+    readonly providers: readonly string[];
+    readonly mode: "single-slot" | "managed-slots";
+    readonly slotId: number;
+    readonly runtimeKey: string | null;
+    readonly checkpoint: {
+        readonly onSwitch: boolean;
+        readonly onShutdown: boolean;
+        readonly onSessionFlush: boolean;
+        readonly idleMs: number;
+        readonly onTurnEnd: boolean;
+        readonly onStepEnd: boolean;
+    };
+    readonly restore: {
+        readonly enabled: boolean;
+        readonly verify: boolean;
+    };
+    readonly failure: {
+        readonly strict: boolean;
+        readonly maxConsecutiveFailures: number;
+        readonly cooldownMs: number;
+    };
+    readonly metadataPath: string | null;
+    readonly logLevel: "debug" | "info" | "off";
+}
+export declare const KV_PERSIST_DEFAULTS: {
+    readonly enabled: true;
+    readonly baseURL: "http://127.0.0.1:8080";
+    readonly requestTimeoutMs: 15000;
+    readonly mode: "single-slot";
+    readonly slotId: 0;
+    readonly onSwitch: true;
+    readonly onShutdown: true;
+    readonly onSessionFlush: true;
+    readonly idleMs: 30000;
+    readonly onTurnEnd: false;
+    readonly onStepEnd: false;
+    readonly restoreEnabled: true;
+    readonly restoreVerify: true;
+    readonly strict: false;
+    readonly maxConsecutiveFailures: 3;
+    readonly cooldownMs: 60000;
+    readonly logLevel: "info";
+};
+/**
+ * Resolve raw config into validated values. Throws `KV_INVARIANT` failures
+ * for structurally impossible config so misconfiguration is loud (SPEC §32
+ * only applies to runtime persistence failures, not to broken config).
+ */
+export declare function resolveKvPersistConfig(input?: KvPersistConfig): ResolvedKvPersistConfig;
+/** True when the request route is explicitly managed (SPEC §37). */
+export declare function isManagedProvider(config: ResolvedKvPersistConfig, provider: string): boolean;
+/**
+ * Schemastery contract shown in DSH settings; every field is optional with a
+ * default so partial user config resolves. `resolveKvPersistConfig` remains
+ * the single source of truth for actual values (SPEC §36).
+ */
+export declare const KvPersistConfigSchema: z<Schemastery.ObjectS<{
+    enabled: z<boolean, boolean>;
+    backend: z<Schemastery.ObjectS<{
+        type: z<"llama.cpp", "llama.cpp">;
+        baseURL: z<string, string>;
+        apiKey: z<string, string>;
+        requestTimeoutMs: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        type: z<"llama.cpp", "llama.cpp">;
+        baseURL: z<string, string>;
+        apiKey: z<string, string>;
+        requestTimeoutMs: z<number, number>;
+    }>>;
+    providers: z<string[], string[]>;
+    mode: z<"single-slot", "single-slot">;
+    slotId: z<number, number>;
+    runtimeKey: z<string, string>;
+    checkpoint: z<Schemastery.ObjectS<{
+        onSwitch: z<boolean, boolean>;
+        onShutdown: z<boolean, boolean>;
+        onSessionFlush: z<boolean, boolean>;
+        idleMs: z<number, number>;
+        onTurnEnd: z<boolean, boolean>;
+        onStepEnd: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        onSwitch: z<boolean, boolean>;
+        onShutdown: z<boolean, boolean>;
+        onSessionFlush: z<boolean, boolean>;
+        idleMs: z<number, number>;
+        onTurnEnd: z<boolean, boolean>;
+        onStepEnd: z<boolean, boolean>;
+    }>>;
+    restore: z<Schemastery.ObjectS<{
+        enabled: z<boolean, boolean>;
+        verify: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: z<boolean, boolean>;
+        verify: z<boolean, boolean>;
+    }>>;
+    failure: z<Schemastery.ObjectS<{
+        strict: z<boolean, boolean>;
+        maxConsecutiveFailures: z<number, number>;
+        cooldownMs: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        strict: z<boolean, boolean>;
+        maxConsecutiveFailures: z<number, number>;
+        cooldownMs: z<number, number>;
+    }>>;
+    metadata: z<Schemastery.ObjectS<{
+        path: z<string, string>;
+    }>, Schemastery.ObjectT<{
+        path: z<string, string>;
+    }>>;
+    logging: z<Schemastery.ObjectS<{
+        level: z<"debug" | "info" | "off", "debug" | "info" | "off">;
+    }>, Schemastery.ObjectT<{
+        level: z<"debug" | "info" | "off", "debug" | "info" | "off">;
+    }>>;
+}>, Schemastery.ObjectT<{
+    enabled: z<boolean, boolean>;
+    backend: z<Schemastery.ObjectS<{
+        type: z<"llama.cpp", "llama.cpp">;
+        baseURL: z<string, string>;
+        apiKey: z<string, string>;
+        requestTimeoutMs: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        type: z<"llama.cpp", "llama.cpp">;
+        baseURL: z<string, string>;
+        apiKey: z<string, string>;
+        requestTimeoutMs: z<number, number>;
+    }>>;
+    providers: z<string[], string[]>;
+    mode: z<"single-slot", "single-slot">;
+    slotId: z<number, number>;
+    runtimeKey: z<string, string>;
+    checkpoint: z<Schemastery.ObjectS<{
+        onSwitch: z<boolean, boolean>;
+        onShutdown: z<boolean, boolean>;
+        onSessionFlush: z<boolean, boolean>;
+        idleMs: z<number, number>;
+        onTurnEnd: z<boolean, boolean>;
+        onStepEnd: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        onSwitch: z<boolean, boolean>;
+        onShutdown: z<boolean, boolean>;
+        onSessionFlush: z<boolean, boolean>;
+        idleMs: z<number, number>;
+        onTurnEnd: z<boolean, boolean>;
+        onStepEnd: z<boolean, boolean>;
+    }>>;
+    restore: z<Schemastery.ObjectS<{
+        enabled: z<boolean, boolean>;
+        verify: z<boolean, boolean>;
+    }>, Schemastery.ObjectT<{
+        enabled: z<boolean, boolean>;
+        verify: z<boolean, boolean>;
+    }>>;
+    failure: z<Schemastery.ObjectS<{
+        strict: z<boolean, boolean>;
+        maxConsecutiveFailures: z<number, number>;
+        cooldownMs: z<number, number>;
+    }>, Schemastery.ObjectT<{
+        strict: z<boolean, boolean>;
+        maxConsecutiveFailures: z<number, number>;
+        cooldownMs: z<number, number>;
+    }>>;
+    metadata: z<Schemastery.ObjectS<{
+        path: z<string, string>;
+    }>, Schemastery.ObjectT<{
+        path: z<string, string>;
+    }>>;
+    logging: z<Schemastery.ObjectS<{
+        level: z<"debug" | "info" | "off", "debug" | "info" | "off">;
+    }>, Schemastery.ObjectT<{
+        level: z<"debug" | "info" | "off", "debug" | "info" | "off">;
+    }>>;
+}>>;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

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

package/lib/config.js

@@ -0,0 +1,169 @@
+/**
+ * Configuration surface of the kv-persist plugin (SPEC §35-§37).
+ *
+ * The Schemastery schema in `index.ts` is the user-facing contract; this
+ * module resolves raw config into fully defaulted, validated values so the
+ * rest of the plugin never deals with optional fields.
+ */
+import z from "@deepseek-ai/schemastery";
+import { KvPersistError } from "./errors.js";
+export const KV_PERSIST_DEFAULTS = {
+    enabled: true,
+    baseURL: "http://127.0.0.1:8080",
+    requestTimeoutMs: 15_000,
+    mode: "single-slot",
+    slotId: 0,
+    onSwitch: true,
+    onShutdown: true,
+    onSessionFlush: true,
+    idleMs: 30_000,
+    onTurnEnd: false,
+    onStepEnd: false,
+    restoreEnabled: true,
+    restoreVerify: true,
+    strict: false,
+    maxConsecutiveFailures: 3,
+    cooldownMs: 60_000,
+    logLevel: "info",
+};
+function requireInt(name, value, fallback, minimum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new KvPersistError("KV_INVARIANT", `config "${name}" must be an integer >= ${minimum}`);
+    }
+    return value;
+}
+function requirePositiveMs(name, value, fallback) {
+    return requireInt(name, value, fallback, 1);
+}
+/**
+ * Resolve raw config into validated values. Throws `KV_INVARIANT` failures
+ * for structurally impossible config so misconfiguration is loud (SPEC §32
+ * only applies to runtime persistence failures, not to broken config).
+ */
+export function resolveKvPersistConfig(input = {}) {
+    if (input.backend?.type !== undefined && input.backend.type !== "llama.cpp") {
+        throw new KvPersistError("KV_BACKEND_UNSUPPORTED", `backend type "${String(input.backend.type)}" is not supported in v0.1 (SPEC §12)`);
+    }
+    if (input.mode !== undefined && input.mode !== "single-slot" && input.mode !== "managed-slots") {
+        throw new KvPersistError("KV_INVARIANT", `unknown mode "${String(input.mode)}"`);
+    }
+    if (input.mode === "managed-slots") {
+        throw new KvPersistError("KV_BACKEND_UNSUPPORTED", 'mode "managed-slots" is planned for v0.3 (SPEC §63); v0.1 supports only "single-slot"');
+    }
+    const logLevel = input.logging?.level ?? KV_PERSIST_DEFAULTS.logLevel;
+    if (logLevel !== "debug" && logLevel !== "info" && logLevel !== "off") {
+        throw new KvPersistError("KV_INVARIANT", `unknown logging.level "${String(logLevel)}"`);
+    }
+    const baseURL = (input.backend?.baseURL ?? KV_PERSIST_DEFAULTS.baseURL).trim();
+    if (baseURL.length === 0) {
+        throw new KvPersistError("KV_INVARIANT", "backend.baseURL must not be blank");
+    }
+    return {
+        enabled: input.enabled ?? KV_PERSIST_DEFAULTS.enabled,
+        backendType: input.backend?.type ?? "llama.cpp",
+        baseURL: baseURL.replace(/\/+$/, ""),
+        apiKey: input.backend?.apiKey && input.backend.apiKey.length > 0 ? input.backend.apiKey : null,
+        requestTimeoutMs: requirePositiveMs("backend.requestTimeoutMs", input.backend?.requestTimeoutMs, KV_PERSIST_DEFAULTS.requestTimeoutMs),
+        providers: (input.providers ?? []).filter((p) => p.length > 0),
+        mode: input.mode ?? KV_PERSIST_DEFAULTS.mode,
+        slotId: requireInt("slotId", input.slotId, KV_PERSIST_DEFAULTS.slotId, 0),
+        runtimeKey: input.runtimeKey && input.runtimeKey.length > 0 ? input.runtimeKey : null,
+        checkpoint: {
+            onSwitch: input.checkpoint?.onSwitch ?? KV_PERSIST_DEFAULTS.onSwitch,
+            onShutdown: input.checkpoint?.onShutdown ?? KV_PERSIST_DEFAULTS.onShutdown,
+            onSessionFlush: input.checkpoint?.onSessionFlush ?? KV_PERSIST_DEFAULTS.onSessionFlush,
+            idleMs: requireInt("checkpoint.idleMs", input.checkpoint?.idleMs, KV_PERSIST_DEFAULTS.idleMs, 0),
+            onTurnEnd: input.checkpoint?.onTurnEnd ?? KV_PERSIST_DEFAULTS.onTurnEnd,
+            onStepEnd: input.checkpoint?.onStepEnd ?? KV_PERSIST_DEFAULTS.onStepEnd,
+        },
+        restore: {
+            enabled: input.restore?.enabled ?? KV_PERSIST_DEFAULTS.restoreEnabled,
+            verify: input.restore?.verify ?? KV_PERSIST_DEFAULTS.restoreVerify,
+        },
+        failure: {
+            strict: input.failure?.strict ?? KV_PERSIST_DEFAULTS.strict,
+            maxConsecutiveFailures: requireInt("failure.maxConsecutiveFailures", input.failure?.maxConsecutiveFailures, KV_PERSIST_DEFAULTS.maxConsecutiveFailures, 1),
+            cooldownMs: requireInt("failure.cooldownMs", input.failure?.cooldownMs, KV_PERSIST_DEFAULTS.cooldownMs, 1),
+        },
+        metadataPath: input.metadata?.path && input.metadata.path.trim().length > 0
+            ? input.metadata.path.trim()
+            : null,
+        logLevel,
+    };
+}
+/** True when the request route is explicitly managed (SPEC §37). */
+export function isManagedProvider(config, provider) {
+    return config.providers.includes(provider);
+}
+/**
+ * Schemastery contract shown in DSH settings; every field is optional with a
+ * default so partial user config resolves. `resolveKvPersistConfig` remains
+ * the single source of truth for actual values (SPEC §36).
+ */
+export const KvPersistConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    backend: z
+        .object({
+        type: z.const("llama.cpp").default("llama.cpp"),
+        baseURL: z.string().default(KV_PERSIST_DEFAULTS.baseURL),
+        apiKey: z.string().default(""),
+        requestTimeoutMs: z.number().default(KV_PERSIST_DEFAULTS.requestTimeoutMs),
+    })
+        .default({
+        type: "llama.cpp",
+        baseURL: KV_PERSIST_DEFAULTS.baseURL,
+        apiKey: "",
+        requestTimeoutMs: KV_PERSIST_DEFAULTS.requestTimeoutMs,
+    }),
+    providers: z.array(z.string()).default([]),
+    mode: z.const("single-slot").default("single-slot"),
+    slotId: z.number().default(KV_PERSIST_DEFAULTS.slotId),
+    runtimeKey: z.string().default(""),
+    checkpoint: z
+        .object({
+        onSwitch: z.boolean().default(KV_PERSIST_DEFAULTS.onSwitch),
+        onShutdown: z.boolean().default(KV_PERSIST_DEFAULTS.onShutdown),
+        onSessionFlush: z.boolean().default(KV_PERSIST_DEFAULTS.onSessionFlush),
+        idleMs: z.number().default(KV_PERSIST_DEFAULTS.idleMs),
+        onTurnEnd: z.boolean().default(KV_PERSIST_DEFAULTS.onTurnEnd),
+        onStepEnd: z.boolean().default(KV_PERSIST_DEFAULTS.onStepEnd),
+    })
+        .default({
+        onSwitch: KV_PERSIST_DEFAULTS.onSwitch,
+        onShutdown: KV_PERSIST_DEFAULTS.onShutdown,
+        onSessionFlush: KV_PERSIST_DEFAULTS.onSessionFlush,
+        idleMs: KV_PERSIST_DEFAULTS.idleMs,
+        onTurnEnd: KV_PERSIST_DEFAULTS.onTurnEnd,
+        onStepEnd: KV_PERSIST_DEFAULTS.onStepEnd,
+    }),
+    restore: z
+        .object({
+        enabled: z.boolean().default(KV_PERSIST_DEFAULTS.restoreEnabled),
+        verify: z.boolean().default(KV_PERSIST_DEFAULTS.restoreVerify),
+    })
+        .default({ enabled: KV_PERSIST_DEFAULTS.restoreEnabled, verify: KV_PERSIST_DEFAULTS.restoreVerify }),
+    failure: z
+        .object({
+        strict: z.boolean().default(KV_PERSIST_DEFAULTS.strict),
+        maxConsecutiveFailures: z.number().default(KV_PERSIST_DEFAULTS.maxConsecutiveFailures),
+        cooldownMs: z.number().default(KV_PERSIST_DEFAULTS.cooldownMs),
+    })
+        .default({
+        strict: KV_PERSIST_DEFAULTS.strict,
+        maxConsecutiveFailures: KV_PERSIST_DEFAULTS.maxConsecutiveFailures,
+        cooldownMs: KV_PERSIST_DEFAULTS.cooldownMs,
+    }),
+    metadata: z
+        .object({
+        path: z.string().default(""),
+    })
+        .default({ path: "" }),
+    logging: z
+        .object({
+        level: z.union([z.const("debug"), z.const("info"), z.const("off")]).default("info"),
+    })
+        .default({ level: "info" }),
+});
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

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

package/lib/coordinator/checkpoint-policy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Checkpoint policy (SPEC §26, §52).
+ *
+ * Answers "should we checkpoint now?" for every trigger the v0.1 plugin
+ * wires: slot switch, session flush, session disposal, turn end, idle
+ * timer, and shutdown. The default recommendation is switch + idle +
+ * shutdown (+ flush), per SPEC §26.
+ */
+import type { ResolvedKvPersistConfig } from "../config.js";
+import type { SessionRuntime } from "./state-machine.js";
+export type CheckpointTrigger = "switch" | "idle" | "session-flush" | "session-disposed" | "turn-end" | "shutdown" | "manual";
+/** Pure decision helper over config + runtime state. */
+export declare class CheckpointPolicy {
+    #private;
+    constructor(config: ResolvedKvPersistConfig);
+    /** True when the trigger is enabled and the session actually needs a save. */
+    shouldCheckpoint(runtime: SessionRuntime | undefined, trigger: CheckpointTrigger): boolean;
+}
+//# sourceMappingURL=checkpoint-policy.d.ts.map

package/lib/coordinator/checkpoint-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-policy.d.ts","sourceRoot":"","sources":["../../src/coordinator/checkpoint-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,MAAM,GACN,eAAe,GACf,kBAAkB,GAClB,UAAU,GACV,UAAU,GACV,QAAQ,CAAC;AAEb,wDAAwD;AACxD,qBAAa,gBAAgB;;gBAGf,MAAM,EAAE,uBAAuB;IAI3C,8EAA8E;IAC9E,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO;CAoB3F"}

package/lib/coordinator/checkpoint-policy.js

@@ -0,0 +1,40 @@
+/**
+ * Checkpoint policy (SPEC §26, §52).
+ *
+ * Answers "should we checkpoint now?" for every trigger the v0.1 plugin
+ * wires: slot switch, session flush, session disposal, turn end, idle
+ * timer, and shutdown. The default recommendation is switch + idle +
+ * shutdown (+ flush), per SPEC §26.
+ */
+import { isDirty } from "./state-machine.js";
+/** Pure decision helper over config + runtime state. */
+export class CheckpointPolicy {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    /** True when the trigger is enabled and the session actually needs a save. */
+    shouldCheckpoint(runtime, trigger) {
+        if (runtime === undefined)
+            return false;
+        if (!isDirty(runtime))
+            return false;
+        switch (trigger) {
+            case "switch":
+                return this.#config.checkpoint.onSwitch;
+            case "idle":
+                return this.#config.checkpoint.idleMs > 0;
+            case "session-flush":
+                return this.#config.checkpoint.onSessionFlush;
+            case "session-disposed":
+                return this.#config.checkpoint.onSwitch || this.#config.checkpoint.onShutdown;
+            case "turn-end":
+                return this.#config.checkpoint.onTurnEnd;
+            case "shutdown":
+                return this.#config.checkpoint.onShutdown;
+            case "manual":
+                return true;
+        }
+    }
+}
+//# sourceMappingURL=checkpoint-policy.js.map

package/lib/coordinator/checkpoint-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-policy.js","sourceRoot":"","sources":["../../src/coordinator/checkpoint-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAY7C,wDAAwD;AACxD,MAAM,OAAO,gBAAgB;IAClB,OAAO,CAA0B;IAE1C,YAAY,MAA+B;QACzC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,8EAA8E;IAC9E,gBAAgB,CAAC,OAAmC,EAAE,OAA0B;QAC9E,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;QACpC,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC1C,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;YAC5C,KAAK,eAAe;gBAClB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC;YAChD,KAAK,kBAAkB;gBACrB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;YAChF,KAAK,UAAU;gBACb,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC;YAC3C,KAAK,UAAU;gBACb,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;YAC5C,KAAK,QAAQ;gBACX,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;CACF"}

package/lib/coordinator/circuit-breaker.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Persistence circuit breaker (SPEC §33).
+ *
+ * When llama slot persistence is broken, retrying it on every request would
+ * waste seconds each time. After N consecutive persistence failures the
+ * breaker opens for a cooldown; while open, requests pass straight through
+ * to ordinary inference (which stays active). After the cooldown one probe
+ * attempt is allowed (half-open).
+ */
+export type CircuitState = "healthy" | "degraded" | "open" | "half-open";
+export interface CircuitBreakerOptions {
+    readonly maxConsecutiveFailures: number;
+    readonly cooldownMs: number;
+}
+export declare class CircuitBreaker {
+    #private;
+    constructor(options: CircuitBreakerOptions);
+    get state(): CircuitState;
+    get consecutiveFailures(): number;
+    /** True when a persistence operation may be attempted at `now`. */
+    allows(now: number): boolean;
+    /** Whether persistence is currently skipped entirely (open without probe). */
+    isOpen(now: number): boolean;
+    recordSuccess(): void;
+    recordFailure(now: number): void;
+    /** Manual recovery hook (e.g. a successful probe). */
+    reset(): void;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/lib/coordinator/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/coordinator/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC;AAEzE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,cAAc;;gBAOb,OAAO,EAAE,qBAAqB;IAK1C,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED,mEAAmE;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAS5B,8EAA8E;IAC9E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,aAAa,IAAI,IAAI;IAKrB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAUhC,sDAAsD;IACtD,KAAK,IAAI,IAAI;CAKd"}

package/lib/coordinator/circuit-breaker.js

@@ -0,0 +1,62 @@
+/**
+ * Persistence circuit breaker (SPEC §33).
+ *
+ * When llama slot persistence is broken, retrying it on every request would
+ * waste seconds each time. After N consecutive persistence failures the
+ * breaker opens for a cooldown; while open, requests pass straight through
+ * to ordinary inference (which stays active). After the cooldown one probe
+ * attempt is allowed (half-open).
+ */
+export class CircuitBreaker {
+    #maxConsecutiveFailures;
+    #cooldownMs;
+    #consecutiveFailures = 0;
+    #openUntil = 0;
+    #state = "healthy";
+    constructor(options) {
+        this.#maxConsecutiveFailures = options.maxConsecutiveFailures;
+        this.#cooldownMs = options.cooldownMs;
+    }
+    get state() {
+        return this.#state;
+    }
+    get consecutiveFailures() {
+        return this.#consecutiveFailures;
+    }
+    /** True when a persistence operation may be attempted at `now`. */
+    allows(now) {
+        if (this.#state === "open") {
+            if (now < this.#openUntil)
+                return false;
+            this.#state = "half-open";
+            return true;
+        }
+        return true;
+    }
+    /** Whether persistence is currently skipped entirely (open without probe). */
+    isOpen(now) {
+        return this.#state === "open" && now < this.#openUntil;
+    }
+    recordSuccess() {
+        this.#consecutiveFailures = 0;
+        if (this.#state !== "healthy")
+            this.#state = "healthy";
+    }
+    recordFailure(now) {
+        this.#consecutiveFailures += 1;
+        if (this.#consecutiveFailures >= this.#maxConsecutiveFailures) {
+            this.#state = "open";
+            this.#openUntil = now + this.#cooldownMs;
+        }
+        else if (this.#state === "healthy") {
+            this.#state = "degraded";
+        }
+    }
+    /** Manual recovery hook (e.g. a successful probe). */
+    reset() {
+        this.#consecutiveFailures = 0;
+        this.#openUntil = 0;
+        this.#state = "healthy";
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/lib/coordinator/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/coordinator/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,OAAO,cAAc;IAChB,uBAAuB,CAAS;IAChC,WAAW,CAAS;IAC7B,oBAAoB,GAAG,CAAC,CAAC;IACzB,UAAU,GAAG,CAAC,CAAC;IACf,MAAM,GAAiB,SAAS,CAAC;IAEjC,YAAY,OAA8B;QACxC,IAAI,CAAC,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;QAC9D,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IACxC,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,mBAAmB;QACrB,OAAO,IAAI,CAAC,oBAAoB,CAAC;IACnC,CAAC;IAED,mEAAmE;IACnE,MAAM,CAAC,GAAW;QAChB,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,IAAI,GAAG,GAAG,IAAI,CAAC,UAAU;gBAAE,OAAO,KAAK,CAAC;YACxC,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;IACzD,CAAC;IAED,aAAa;QACX,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IACzD,CAAC;IAED,aAAa,CAAC,GAAW;QACvB,IAAI,CAAC,oBAAoB,IAAI,CAAC,CAAC;QAC/B,IAAI,IAAI,CAAC,oBAAoB,IAAI,IAAI,CAAC,uBAAuB,EAAE,CAAC;YAC9D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YACrB,IAAI,CAAC,UAAU,GAAG,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC;QAC3C,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACrC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,KAAK;QACH,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF"}