@voltro/cache 0.86.0 → 0.88.0

package/dist/backendRedis.js

@@ -1,56 +1,171 @@
 import { CacheError as e } from "./errors.js";
 import { CacheStore as t } from "./CacheStore.js";
-import { Clock as n, Effect as r, Layer as i, Option as a } from "effect";
-import { commandRetry as o, connect as s } from "@voltro/kv/connection";
-//#region src/backendRedis.ts
-var c = (t) => s({
-	url: t.url,
-	driver: t.driver,
-	...t.token === void 0 ? {} : { token: t.token }
-}).pipe(r.mapError((t) => new e({
-	operation: "connect",
-	key: "",
-	cause: String(t)
-}))), l = "\nlocal NOEXP = 9000000000000000\nlocal ttl = tonumber(ARGV[1])\nlocal now = tonumber(ARGV[2])\nlocal score\nif ttl < 0 then score = NOEXP else score = now + ttl end\nredis.call('ZADD', KEYS[1], score, ARGV[3])\nlocal top = redis.call('ZREVRANGE', KEYS[1], 0, 0, 'WITHSCORES')\nlocal maxScore = tonumber(top[2])\nif maxScore >= NOEXP then\n  redis.call('PERSIST', KEYS[1])\nelse\n  local rem = maxScore - now\n  if rem < 1 then rem = 1 end\n  redis.call('PEXPIRE', KEYS[1], rem)\nend\nreturn 1\n", u = (t) => r.gen(function* () {
-	let i = yield* r.acquireRelease(c(t), (e) => r.promise(() => e.close().catch(() => void 0))), s = t.keyPrefix ?? "voltro:cache", u = (e) => `${s}:v:${e}`, d = (e) => `${s}:t:${e}`, f = (t, n, a) => r.tryPromise({
-		try: () => a(i),
-		catch: (r) => new e({
-			operation: t,
-			key: n,
-			cause: String(r)
-		})
-	}).pipe(r.retry(o)), p = (t, n) => r.try({
-		try: () => JSON.stringify(n),
-		catch: (n) => new e({
-			operation: "serialize",
-			key: t,
-			cause: String(n)
-		})
-	}), m = (t, n) => r.try({
-		try: () => a.some(JSON.parse(n)),
-		catch: (n) => new e({
-			operation: "deserialize",
-			key: t,
-			cause: String(n)
-		})
-	}), h = (e) => f("clear", "", (t) => t.scan(e, `${s}:*`, 200)).pipe(r.flatMap(({ cursor: e, keys: t }) => (t.length > 0 ? f("clear", "", (e) => e.del(t)) : r.succeed(0)).pipe(r.flatMap(() => e === "0" ? r.void : h(e))))), g = (e, t, n) => p(e, t).pipe(r.flatMap((t) => n !== void 0 && n > 0 ? f("set", e, (r) => r.psetex(u(e), Math.ceil(n), t)) : f("set", e, (n) => n.set(u(e), t))), r.asVoid);
+import { Effect as n, Layer as r, Option as i } from "effect";
+import { CACHE_ATOMIC_SCRIPT as a, RedisConnections as o, cacheAtomicArray as s, cacheAtomicComponent as c, cacheAtomicKeys as l, cacheAtomicMember as u, cacheAtomicRoot as d, cacheAtomicScanPage as f, cacheAtomicSnapshot as p, cacheAtomicTtl as m, cacheAtomicValueSnapshots as h, decodeCacheAtomicCommand as g, decodeCacheAtomicReply as _ } from "@voltro/kv/connection";
+// src/backendRedis.ts
+var v = (t, r = "voltro:cache") => {
+	let o = d(r), v = (t, n, r) => new e({
+		operation: t,
+		key: n,
+		cause: r
+	}), y = (e, t, r) => n.try({
+		try: r,
+		catch: () => v(e, t, "Cache command or stored metadata is invalid.")
+	}), b = (e, r, i) => n.gen(function* () {
+		let s = yield* y(e, r, () => {
+			let e = g(i);
+			return {
+				keys: l(o, e),
+				body: JSON.stringify(e)
+			};
+		}), c = yield* n.tryPromise({
+			try: () => t.eval(a, s.keys.length, ...s.keys, s.body),
+			catch: () => v(e, r, "Cache transport failed; a write outcome may be unknown.")
+		}).pipe(n.uninterruptible), u = yield* y(e, r, () => _(c));
+		return u.status === "limit" ? yield* n.fail(v(e, r, "Cache operation exceeds the server limit.")) : u;
+	}), x = (e, t, r) => b(e, t, r).pipe(n.flatMap((r) => r.status === "ok" ? n.succeed(r.value) : n.fail(v(e, t, "Cache observation unexpectedly conflicted.")))), S = (e, t, r) => x(e, t, {
+		op: "inspect",
+		key: r
+	}).pipe(n.flatMap((n) => y(e, t, () => p(n)))), C = (e, t, r) => n.gen(function* () {
+		for (let n = 0; n < 8; n++) {
+			let n = yield* r(), i = yield* b(e, t, n.command);
+			if (i.status !== "conflict") return yield* y(e, t, () => n.decode(i.value));
+		}
+		return yield* n.fail(v(e, t, "Cache changed during the operation; retry with a fresh observation."));
+	}), w = (e) => {
+		if (typeof e != "number" || !Number.isSafeInteger(e) || e < 0) throw Error("Invalid cache count");
+		return e;
+	}, T = (e) => C("get", e, () => n.gen(function* () {
+		let t = yield* y("get", e, () => c(e));
+		return {
+			command: {
+				op: "read",
+				key: t,
+				snapshot: yield* S("get", e, t)
+			},
+			decode: (e) => {
+				if (e !== null && typeof e != "string") throw Error("Invalid cache payload");
+				return e;
+			}
+		};
+	})), E = (e, t, r) => C("set", e, () => n.gen(function* () {
+		let n = yield* y("set", e, () => {
+			let n = JSON.stringify(t);
+			if (n === void 0) throw Error("Value is not JSON serializable");
+			return {
+				id: c(e),
+				tags: [...new Set((r?.tags ?? []).map(c))].sort(),
+				value: n,
+				ttlMs: m(r?.ttlMs),
+				version: globalThis.crypto.randomUUID(),
+				revision: globalThis.crypto.randomUUID(),
+				fence: r?.fence ?? null
+			};
+		}), i = yield* S("set", e, n.id);
+		return {
+			command: {
+				op: "write",
+				key: n.id,
+				snapshot: i,
+				version: n.version,
+				revision: n.revision,
+				tags: n.tags,
+				value: n.value,
+				ttlMs: n.ttlMs,
+				fence: n.fence
+			},
+			decode: (e) => w(e) > 0
+		};
+	}));
 	return {
-		get: (e) => f("get", e, (t) => t.get(u(e))).pipe(r.flatMap((t) => t === null ? r.succeed(a.none()) : m(e, t))),
-		set: (e, t, n) => g(e, t, n?.ttlMs),
-		setWithTags: (e, t, i) => g(e, t, i.ttlMs).pipe(r.flatMap(() => {
-			let t = i.tags ?? [];
-			if (t.length === 0) return r.void;
-			let a = i.ttlMs !== void 0 && i.ttlMs > 0 ? Math.ceil(i.ttlMs) : -1;
-			return n.currentTimeMillis.pipe(r.flatMap((n) => r.forEach(t, (t) => f("setWithTags", e, (r) => r.eval(l, 1, d(t), a, n, e)), { discard: !0 })));
+		get: (e) => T(e).pipe(n.flatMap((t) => t === null ? n.succeed(i.none()) : y("get", e, () => i.some(JSON.parse(t))))),
+		set: (e, t, r) => E(e, t, r).pipe(n.asVoid),
+		setWithTags: (e, t, n) => E(e, t, n),
+		fence: () => x("fence", "", { op: "fence" }).pipe(n.flatMap((e) => y("fence", "", () => w(e)))),
+		claim: (e, t) => n.gen(function* () {
+			let n = yield* y("claim", e, () => ({
+				op: "write",
+				key: c(e),
+				snapshot: null,
+				version: globalThis.crypto.randomUUID(),
+				revision: globalThis.crypto.randomUUID(),
+				tags: [],
+				value: "true",
+				ttlMs: m(t),
+				fence: null
+			}));
+			return (yield* b("claim", e, n)).status === "ok";
+		}),
+		has: (e) => T(e).pipe(n.map((e) => e !== null)),
+		remove: (e) => C("remove", e, () => n.gen(function* () {
+			let t = yield* y("remove", e, () => ({
+				id: c(e),
+				revision: globalThis.crypto.randomUUID()
+			})), n = yield* S("remove", e, t.id);
+			return {
+				command: {
+					op: "remove",
+					key: t.id,
+					snapshot: n,
+					revision: t.revision
+				},
+				decode: (e) => w(e) > 0
+			};
 		})),
-		remove: (e) => f("remove", e, (t) => t.del([u(e)])).pipe(r.map((e) => e > 0)),
-		has: (e) => f("has", e, (t) => t.exists(u(e))).pipe(r.map((e) => e > 0)),
-		clear: () => h("0"),
-		invalidateTag: (e) => f("invalidateTag", e, (t) => t.zrange(d(e))).pipe(r.flatMap((t) => f("invalidateTag", e, async (n) => {
-			let r = t.map(u), i = r.length > 0 ? await n.del(r) : 0;
-			return await n.del([d(e)]), i;
-		})))
+		invalidateTag: (e) => C("invalidateTag", e, () => n.gen(function* () {
+			let t = yield* y("invalidateTag", e, () => ({
+				id: c(e),
+				revision: globalThis.crypto.randomUUID()
+			})), n = yield* x("invalidateTag", e, {
+				op: "tag",
+				tag: t.id
+			}), r = yield* y("invalidateTag", e, () => s(n).map((e) => (u(e), String(e))).sort()), i = [...new Set(r.map((e) => u(e).key))].sort(), a = yield* x("invalidateTag", e, {
+				op: "inspect-values",
+				keys: i
+			}), o = yield* y("invalidateTag", e, () => h(a));
+			return {
+				command: {
+					op: "invalidate",
+					tag: t.id,
+					members: r,
+					snapshots: o,
+					revision: t.revision
+				},
+				decode: w
+			};
+		})),
+		clear: () => C("clear", "", () => n.gen(function* () {
+			let e = yield* x("clear", "", { op: "revision" });
+			yield* y("clear", "", () => g({
+				op: "clear",
+				keys: [],
+				revision: e
+			}));
+			let t = /* @__PURE__ */ new Set(), r = /* @__PURE__ */ new Set(), i = "0";
+			do {
+				if (r.has(i)) return yield* n.fail(v("clear", "", "Cache scan did not progress."));
+				r.add(i);
+				let e = yield* x("clear", "", {
+					op: "scan",
+					cursor: i
+				}), a = yield* y("clear", "", () => f(o, e));
+				a.keys.forEach((e) => t.add(e)), i = a.cursor;
+			} while (i !== "0");
+			return {
+				command: {
+					op: "clear",
+					keys: [...t].sort(),
+					revision: e
+				},
+				decode: () => {}
+			};
+		}))
 	};
-}), d = (e) => i.effect(t, u(e));
-//#endregion
-export { d as layerRedis };
+}, y = (i = {}) => r.effect(t, n.gen(function* () {
+	return v(yield* (yield* o).client(i.connectionName ?? "cache").pipe(n.mapError(() => new e({
+		operation: "connect",
+		key: "",
+		cause: "Connection unavailable"
+	}))), i.keyPrefix);
+}));
+export { y as layerRedis, v as makeRedisCacheStore };

package/dist/errors.js

@@ -1,9 +1,8 @@
 import { Schema as e } from "effect";
-//#region src/errors.ts
+// src/errors.ts
 var t = class extends e.TaggedError()("CacheError", {
 	operation: e.String,
 	key: e.String,
 	cause: e.String
 }) {};
-//#endregion
 export { t as CacheError };

package/dist/index.d.ts

@@ -1,8 +1,12 @@
+import { CACHE_FENCE_RETENTION_MS } from '@voltro/kv/connection';
 import { Config } from 'effect';
 import { Context } from 'effect';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
 import { Option } from 'effect';
+import { RedisConnections } from '@voltro/kv/connection';
+import { RespClient } from '@voltro/kv/connection';
+import { RespConnections } from '@voltro/kv/connection';
 import { Schema } from 'effect';
 import { Scope } from 'effect';
 import { Stream } from 'effect';
@@ -21,13 +25,26 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
     /** Write-through with the SAME storage shape `wrap` uses (incl. the
      *  SWR envelope) — so a value written here is read back identically
      *  by a later `wrap`. The dispatcher uses this to keep cached
-     *  snapshots warm from its live recompute. */
-    readonly put: <A>(key: string, options: WrapOptions, value: A) => Effect.Effect<void, CacheError>;
+     *  snapshots warm from its live recompute. Pass the `fence()` observed
+     *  before the value was read, so an earlier, slower read can never
+     *  overwrite a later one. Resolves `false` when the fence voided it. */
+    readonly put: <A>(key: string, options: WrapOptions, value: A, fence?: CacheFence) => Effect.Effect<boolean, CacheError>;
+    /** The store's invalidation position — observe it before reading the
+     *  value you will `put`. */
+    readonly fence: () => Effect.Effect<CacheFence, CacheError>;
     readonly remove: (key: string) => Effect.Effect<boolean, CacheError>;
     readonly has: (key: string) => Effect.Effect<boolean, CacheError>;
     readonly clear: () => Effect.Effect<void, CacheError>;
     readonly invalidateTag: (tag: string) => Effect.Effect<number, CacheError>;
     readonly wrap: <A, E, R>(key: string, options: WrapOptions, compute: Effect.Effect<A, E, R>) => Effect.Effect<A, E | CacheError, R>;
+    /** Cache-aside whose store decision the compute makes — see the
+     *  `wrapDynamic` note above. Best-effort: never fails on the cache. */
+    readonly wrapDynamic: <A, E, R>(key: string, options: DynamicWrapOptions, compute: Effect.Effect<DynamicComputed<A>, E, R>, read: (stored: unknown) => Effect.Effect<Option.Option<A>>) => Effect.Effect<{
+        readonly value: A;
+        readonly served: DynamicServed;
+    }, E, R>;
+    /** Per-label counters kept by `wrapDynamic`. */
+    readonly queryStats: () => Effect.Effect<Readonly<Record<string, DynamicLabelStats>>>;
     /** A named, key-prefixed partition with its own default ttl/swr/tags.
      *  Keys become `<name>:<key>`; per-call options override the defaults;
      *  tags stay global (unprefixed) so bus invalidation still reaches
@@ -39,6 +56,7 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
         hits: number;
         misses: number;
         hitRate: number;
+        voided: number;
     }>;
 }> & {
     readonly make: Effect.Effect<{
@@ -49,13 +67,26 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
         /** Write-through with the SAME storage shape `wrap` uses (incl. the
          *  SWR envelope) — so a value written here is read back identically
          *  by a later `wrap`. The dispatcher uses this to keep cached
-         *  snapshots warm from its live recompute. */
-        readonly put: <A>(key: string, options: WrapOptions, value: A) => Effect.Effect<void, CacheError>;
+         *  snapshots warm from its live recompute. Pass the `fence()` observed
+         *  before the value was read, so an earlier, slower read can never
+         *  overwrite a later one. Resolves `false` when the fence voided it. */
+        readonly put: <A>(key: string, options: WrapOptions, value: A, fence?: CacheFence) => Effect.Effect<boolean, CacheError>;
+        /** The store's invalidation position — observe it before reading the
+         *  value you will `put`. */
+        readonly fence: () => Effect.Effect<CacheFence, CacheError>;
         readonly remove: (key: string) => Effect.Effect<boolean, CacheError>;
         readonly has: (key: string) => Effect.Effect<boolean, CacheError>;
         readonly clear: () => Effect.Effect<void, CacheError>;
         readonly invalidateTag: (tag: string) => Effect.Effect<number, CacheError>;
         readonly wrap: <A, E, R>(key: string, options: WrapOptions, compute: Effect.Effect<A, E, R>) => Effect.Effect<A, E | CacheError, R>;
+        /** Cache-aside whose store decision the compute makes — see the
+         *  `wrapDynamic` note above. Best-effort: never fails on the cache. */
+        readonly wrapDynamic: <A, E, R>(key: string, options: DynamicWrapOptions, compute: Effect.Effect<DynamicComputed<A>, E, R>, read: (stored: unknown) => Effect.Effect<Option.Option<A>>) => Effect.Effect<{
+            readonly value: A;
+            readonly served: DynamicServed;
+        }, E, R>;
+        /** Per-label counters kept by `wrapDynamic`. */
+        readonly queryStats: () => Effect.Effect<Readonly<Record<string, DynamicLabelStats>>>;
         /** A named, key-prefixed partition with its own default ttl/swr/tags.
          *  Keys become `<name>:<key>`; per-call options override the defaults;
          *  tags stay global (unprefixed) so bus invalidation still reaches
@@ -67,10 +98,13 @@ declare const Cache_base: Context.ServiceClass<Cache, "@voltro/Cache", {
             hits: number;
             misses: number;
             hitRate: number;
+            voided: number;
         }>;
     }, never, CacheStore>;
 };
 
+export { CACHE_FENCE_RETENTION_MS }
+
 export declare class CacheError extends CacheError_base {
 }
 
@@ -84,8 +118,18 @@ declare const CacheError_base: Schema.Class<CacheError, Schema.TaggedStruct<"Cac
     readonly cause: Schema.String;
 }>, YieldableError>;
 
+/**
+ * The store's invalidation position, observed before a compute. Opaque: only
+ * hand it back to `setWithTags`. A fence older than
+ * `CACHE_FENCE_RETENTION_MS` proves nothing; `Cache.wrap` does not store such
+ * a compute.
+ */
+export declare type CacheFence = number;
+
 export declare namespace CacheLayer {
     export {
+        CacheStoreLayerOptions,
+        makeStoreLayer,
         storeLayer,
         layer
     }
@@ -126,6 +170,10 @@ export declare interface CacheSetWithTagsOptions extends CacheSetOptions {
     /** Tags this entry belongs to. `invalidateTag(tag)` drops every entry
      *  carrying that tag. */
     readonly tags?: ReadonlyArray<string>;
+    /** A `fence()` observed BEFORE the value was computed. When any of `tags`
+     *  was invalidated since — anywhere that shares this store — the write is
+     *  void: the value may predate the write behind that invalidation. */
+    readonly fence?: CacheFence;
 }
 
 export declare class CacheStore extends CacheStore_base {
@@ -133,6 +181,13 @@ export declare class CacheStore extends CacheStore_base {
 
 declare const CacheStore_base: Context.ServiceClass<CacheStore, "@voltro/CacheStore", CacheStoreShape>;
 
+declare interface CacheStoreLayerOptions {
+    readonly backend?: 'memory' | 'redis';
+    readonly connectionName?: string;
+    readonly keyPrefix?: string;
+    readonly connections?: RespConnections;
+}
+
 export declare interface CacheStoreShape {
     /** Read a value. `None` on miss OR expiry (expired entries are lazily
      *  evicted on read). */
@@ -140,8 +195,15 @@ export declare interface CacheStoreShape {
     /** Write a value with an optional ms TTL. Overwrites any existing entry
      *  (clearing its old tag memberships). */
     readonly set: (key: string, value: unknown, options?: CacheSetOptions) => Effect.Effect<void, CacheError>;
-    /** Write a value AND register it under the given tags. */
-    readonly setWithTags: (key: string, value: unknown, options: CacheSetWithTagsOptions) => Effect.Effect<void, CacheError>;
+    /** Write a value AND register it under the given tags. Resolves `false`
+     *  when `options.fence` voided the write (nothing was stored). */
+    readonly setWithTags: (key: string, value: unknown, options: CacheSetWithTagsOptions) => Effect.Effect<boolean, CacheError>;
+    /** Current invalidation position — see {@link CacheFence}. Every
+     *  `invalidateTag` advances it, for every participant sharing the store. */
+    readonly fence: () => Effect.Effect<CacheFence, CacheError>;
+    /** Claim `key` for `ttlMs` if nobody holds it — the cluster single-flight
+     *  lease. Optional: a process-local store has nothing to coordinate. */
+    readonly claim?: (key: string, ttlMs: number) => Effect.Effect<boolean, CacheError>;
     /** Delete one key (and its tag memberships). Resolves `true` if it existed. */
     readonly remove: (key: string) => Effect.Effect<boolean, CacheError>;
     /** Existence check honouring expiry, without deserializing the value. */
@@ -149,8 +211,9 @@ export declare interface CacheStoreShape {
     /** Drop every entry in this cache's namespace. Scoped to the backend's
      *  key-prefix — never a global flush on a shared server. */
     readonly clear: () => Effect.Effect<void, CacheError>;
-    /** Delete every key registered under `tag`, then drop the tag index.
-     *  Resolves the count of keys removed. */
+    /** Delete every key registered under `tag`, then drop the tag index, and
+     *  advance the fence for `tag` (also when nothing carried it). Resolves the
+     *  count of keys removed. `clear` does not reset the fence. */
     readonly invalidateTag: (tag: string) => Effect.Effect<number, CacheError>;
 }
 
@@ -187,6 +250,52 @@ export declare const cosineSimilarity: (a: ReadonlyArray<number>, b: ReadonlyArr
  */
 export declare const depsForChange: (c: ChangeSignal) => ReadonlyArray<string>;
 
+/** A `wrapDynamic` compute's result: the value for THIS caller, and whether
+ *  (and how) it may be stored for the next. */
+export declare interface DynamicComputed<A> {
+    readonly value: A;
+    readonly store?: DynamicStore | undefined;
+    /** The compute found the call is not a candidate for this cache at all (a
+     *  query whose handler returned a descriptor): nothing stored, and not
+     *  counted as a result the cache refused to keep. */
+    readonly notApplicable?: boolean | undefined;
+}
+
+export declare type DynamicEvent = keyof DynamicLabelStats;
+
+/** Per-label counters — `queryStats()`, the dashboard Cache panel and the
+ *  `voltro_query_cache_events_total{query,event}` series. */
+export declare interface DynamicLabelStats {
+    readonly hits: number;
+    readonly stale: number;
+    readonly misses: number;
+    readonly stored: number;
+    readonly voided: number;
+    readonly decodeMisses: number;
+    readonly uncacheable: number;
+    readonly oversized: number;
+}
+
+export declare type DynamicServed = 'hit' | 'stale' | 'miss';
+
+/** What a `wrapDynamic` compute stores, decided AFTER it ran: the encoded
+ *  value and the tags it actually depends on. Absent ⇒ not stored. */
+export declare interface DynamicStore {
+    readonly stored: unknown;
+    readonly tags: ReadonlyArray<string>;
+}
+
+export declare interface DynamicWrapOptions {
+    readonly ttlMs: number;
+    readonly swrMs?: number | undefined;
+    /** Cluster single-flight: on a miss, claim the key for this long on a
+     *  store that can (`CacheStore.claim`); other participants wait for the
+     *  claimant's value instead of computing it too, up to this bound. */
+    readonly leaseMs?: number | undefined;
+    /** Bounded label the per-label counters are kept under (a query name). */
+    readonly label: string;
+}
+
 export declare class InvalidationBus extends InvalidationBus_base {
     /** The bus with its own scope: sinks live as long as the layer. */
     static readonly layer: Layer.Layer<InvalidationBus, never, never>;
@@ -214,7 +323,10 @@ declare const layer: Layer.Layer<Cache, Config.ConfigError | CacheError>;
 export declare const layerMemory: (options?: MemoryCacheOptions) => Layer.Layer<CacheStore>;
 
 /** `Layer<CacheStore>` backed by a RESP server (Redis/Valkey/KeyDB/Dragonfly/Upstash). */
-export declare const layerRedis: (options: RedisCacheOptions) => Layer.Layer<CacheStore, CacheError>;
+export declare const layerRedis: (options?: RedisCacheOptions) => Layer.Layer<CacheStore, CacheError, RedisConnections>;
+
+/** Cache semantics over a registry-owned client; never closes its socket. */
+export declare const makeRedisCacheStore: (client: RespClient, prefix?: string) => CacheStoreShape;
 
 /**
  * Build a {@link SemanticCacheShape} over a resolved {@link CacheStoreShape}.
@@ -225,8 +337,19 @@ export declare const layerRedis: (options: RedisCacheOptions) => Layer.Layer<Cac
  */
 export declare const makeSemanticCache: (store: CacheStoreShape, _options?: SemanticCacheOptions) => Effect.Effect<SemanticCacheShape>;
 
+/**
+ * `Layer<CacheStore>` whose backend (memory | redis) + connection are chosen
+ * from the environment. This is the STORE — value/TTL/tag storage — one level
+ * below `Cache`. Exposed so a caller can build MORE than one service on ONE
+ * store instance: `Layer.provide(storeLayer)` on a merged layer memoises a
+ * SINGLE `CacheStore`, shared by every consumer in it (that is how the query
+ * `Cache` and a `SemanticCache` end up over the same backend — see
+ * `cli/src/cacheFacade.ts`).
+ */
+declare const makeStoreLayer: (options?: CacheStoreLayerOptions) => Layer.Layer<CacheStore, Config.ConfigError | CacheError>;
+
 export declare interface MemoryCacheOptions {
-    /** Hard cap on live entry count. When exceeded, oldest-by-insertion
+    /** Hard cap on live entry count. When exceeded, least-recently-used
      *  entries are evicted — the backstop for entries that expired but were
      *  never read (lazy eviction never fired). Omit for unbounded. */
     readonly maxEntries?: number;
@@ -247,11 +370,8 @@ export declare interface PartitionDefaults {
 }
 
 export declare interface RedisCacheOptions {
-    readonly driver: 'resp' | 'http';
-    /** Connection URL (`redis://…` / `rediss://…` for RESP, the REST URL for http). */
-    readonly url: string;
-    /** Auth token — http (Upstash REST) driver only. */
-    readonly token?: string;
+    /** Named pooled connection; defaults to cache's environment convention. */
+    readonly connectionName?: string;
     readonly keyPrefix?: string;
 }
 
@@ -340,15 +460,6 @@ export declare interface SemanticPutOptions {
     readonly key?: string;
 }
 
-/**
- * `Layer<CacheStore>` whose backend (memory | redis) + connection are chosen
- * from the environment. This is the STORE — value/TTL/tag storage — one level
- * below `Cache`. Exposed so a caller can build MORE than one service on ONE
- * store instance: `Layer.provide(storeLayer)` on a merged layer memoises a
- * SINGLE `CacheStore`, shared by every consumer in it (that is how the query
- * `Cache` and a `SemanticCache` end up over the same backend — see
- * `cli/src/cacheFacade.ts`).
- */
 declare const storeLayer: Layer.Layer<CacheStore, Config.ConfigError | CacheError>;
 
 /** The dependency tag for a whole table. Coarser than {@link rowDep}: it also

package/dist/index.js

@@ -1,9 +1,9 @@
 import { CacheError as e } from "./errors.js";
-import { CacheStore as t } from "./CacheStore.js";
-import { layerMemory as n } from "./backendMemory.js";
-import { layerRedis as r } from "./backendRedis.js";
-import { Cache as i } from "./Cache.js";
-import { SemanticCache as a, cosineSimilarity as o, depsForChange as s, makeSemanticCache as c, rowDep as l, tableDep as u } from "./semantic.js";
-import { InvalidationBus as d } from "./invalidationBus.js";
-import { layer_exports as f } from "./layer.js";
-export { i as Cache, e as CacheError, f as CacheLayer, t as CacheStore, d as InvalidationBus, a as SemanticCache, o as cosineSimilarity, s as depsForChange, n as layerMemory, r as layerRedis, c as makeSemanticCache, l as rowDep, u as tableDep };
+import { CACHE_FENCE_RETENTION_MS as t, CacheStore as n } from "./CacheStore.js";
+import { layerMemory as r } from "./backendMemory.js";
+import { layerRedis as i, makeRedisCacheStore as a } from "./backendRedis.js";
+import { Cache as o } from "./Cache.js";
+import { SemanticCache as s, cosineSimilarity as c, depsForChange as l, makeSemanticCache as u, rowDep as d, tableDep as f } from "./semantic.js";
+import { InvalidationBus as p } from "./invalidationBus.js";
+import { layer_exports as m } from "./layer.js";
+export { t as CACHE_FENCE_RETENTION_MS, o as Cache, e as CacheError, m as CacheLayer, n as CacheStore, p as InvalidationBus, s as SemanticCache, c as cosineSimilarity, l as depsForChange, r as layerMemory, i as layerRedis, a as makeRedisCacheStore, u as makeSemanticCache, d as rowDep, f as tableDep };

package/dist/invalidationBus.js

@@ -1,5 +1,5 @@
 import { Context as e, Effect as t, Layer as n, PubSub as r, Scope as i, Stream as a } from "effect";
-//#region src/invalidationBus.ts
+// src/invalidationBus.ts
 var o = class o extends e.Service()("@voltro/InvalidationBus", { make: t.gen(function* () {
 	let e = yield* r.unbounded(), n = yield* t.scope;
 	return {
@@ -10,5 +10,4 @@ var o = class o extends e.Service()("@voltro/InvalidationBus", { make: t.gen(fun
 }) }) {
 	static layer = n.effect(o, o.make);
 };
-//#endregion
 export { o as InvalidationBus };

package/dist/layer.js

@@ -3,23 +3,22 @@ import { layerMemory as t } from "./backendMemory.js";
 import { layerRedis as n } from "./backendRedis.js";
 import { Cache as r } from "./Cache.js";
 import { Config as i, Effect as a, Layer as o, Option as s } from "effect";
-//#region src/layer.ts
-var c = /* @__PURE__ */ e({
-	layer: () => f,
-	storeLayer: () => d
-}), l = a.gen(function* () {
+import { RedisConnections as c, layerConnections as l } from "@voltro/kv/connection";
+// src/layer.ts
+var u = /* @__PURE__ */ e({
+	layer: () => h,
+	makeStoreLayer: () => p,
+	storeLayer: () => m
+}), d = a.gen(function* () {
 	let e = yield* i.Int("CACHE_MAX_ENTRIES").pipe(i.option), n = s.isSome(e) ? { maxEntries: e.value } : {};
 	return t(n);
-}), u = a.gen(function* () {
-	let e = yield* i.String("CACHE_REDIS_URL").pipe(i.orElse(() => i.String("REDIS_URL"))), t = yield* i.Literals(["resp", "http"], "CACHE_REDIS_DRIVER").pipe(i.withDefault("resp")), r = yield* i.String("CACHE_REDIS_TOKEN").pipe(i.orElse(() => i.String("UPSTASH_REDIS_REST_TOKEN")), i.option), a = yield* i.String("CACHE_KEY_PREFIX").pipe(i.option), o = {
-		driver: t,
-		url: e,
-		...s.isSome(r) ? { token: r.value } : {},
-		...s.isSome(a) ? { keyPrefix: a.value } : {}
+}), f = (e) => a.gen(function* () {
+	let t = yield* i.String("CACHE_KEY_PREFIX").pipe(i.option), r = {
+		...e.connectionName === void 0 ? {} : { connectionName: e.connectionName },
+		...s.isSome(t) ? { keyPrefix: t.value } : e.keyPrefix === void 0 ? {} : { keyPrefix: e.keyPrefix }
 	};
-	return n(o);
-}), d = o.unwrap(a.gen(function* () {
-	return (yield* i.Literals(["memory", "redis"], "CACHE_BACKEND").pipe(i.withDefault("memory"))) === "redis" ? yield* u : yield* l;
-})), f = r.layer.pipe(o.provide(d));
-//#endregion
-export { f as layer, c as layer_exports, d as storeLayer };
+	return n(r).pipe(o.provide(e.connections === void 0 ? l : o.succeed(c, e.connections)));
+}), p = (e = {}) => o.unwrap(a.gen(function* () {
+	return (yield* i.Literals(["memory", "redis"], "CACHE_BACKEND").pipe(i.withDefault(e.backend ?? "memory"))) === "redis" ? yield* f(e) : yield* d;
+})), m = p(), h = r.layer.pipe(o.provide(m));
+export { h as layer, u as layer_exports, p as makeStoreLayer, m as storeLayer };

package/dist/semantic.js

@@ -1,6 +1,6 @@
 import { CacheStore as e } from "./CacheStore.js";
 import { Context as t, Effect as n, HashMap as r, HashSet as i, Layer as a, Option as o, Ref as s } from "effect";
-//#region src/semantic.ts
+// src/semantic.ts
 var c = (e, t) => `row:${e}:${t}`, l = (e) => `table:${e}`, u = (e) => {
 	let t = l(e.table);
 	return e.op === "insert" || e.id === void 0 ? [t] : [c(e.table, e.id), t];
@@ -127,5 +127,4 @@ var c = (e, t) => `row:${e}:${t}`, l = (e) => `table:${e}`, u = (e) => {
 }) }) {
 	static layer = a.effect(r, r.make);
 };
-//#endregion
 export { v as SemanticCache, d as cosineSimilarity, u as depsForChange, _ as makeSemanticCache, c as rowDep, l as tableDep };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cache",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "description": "Effect-native cache primitive — memory + RESP (Redis/Valkey/KeyDB/Dragonfly/Upstash) backends, tag invalidation, single-flight wrap.",
   "keywords": [
     "voltro",
@@ -33,10 +33,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/kv": "0.86.0"
+    "@voltro/kv": "0.88.0"
   },
   "peerDependencies": {
-    "effect": "4.0.1"
+    "effect": "4.1.0"
   },
   "publishConfig": {
     "access": "public"