@voltro/kv 0.85.0 → 0.87.0

package/dist/connectionDefinitions.js

@@ -0,0 +1,285 @@
+import { sqlDefinitionProblem as e } from "./connectionSqlConfig.js";
+import { analyticsDefinitionProblem as t } from "./connectionAnalyticsConfig.js";
+//#region src/connectionDefinitions.ts
+var n = (e) => {
+	if (!/^[A-Z][A-Z0-9_]*$/.test(e)) throw Error("Connection env names must use uppercase letters, digits and underscores");
+	return Object.freeze({
+		_tag: "ConnectionEnv",
+		name: e
+	});
+}, r = (e, t) => {
+	for (let n of ["connectTimeoutMs", "commandTimeoutMs"]) {
+		let r = e[n];
+		if (r !== void 0) {
+			if (!Number.isSafeInteger(r) || r < 1 || r > 2147483647) return `Redis ${n} must be an integer from 1 to 2147483647 milliseconds`;
+			if (t !== void 0 && t !== "resp") return "Native Redis timeouts require the RESP driver";
+		}
+	}
+}, i = (e = {}) => {
+	if (e.now !== void 0 && typeof e.now != "function") throw Error("Memory connection now must be a function");
+	return Object.freeze({
+		_tag: "MemoryRedisConnection",
+		...e.now === void 0 ? {} : { now: e.now }
+	});
+}, a = (e, t = {}) => {
+	let n = t.ttlMs ?? 6e4;
+	if (!Number.isSafeInteger(n) || n <= 0) throw Error("Dynamic connection ttlMs must be a positive safe integer");
+	return Object.freeze({
+		_tag: "DynamicRedisConnection",
+		resolve: e,
+		ttlMs: n
+	});
+}, o = (e, t = {}) => {
+	let n = t.ttlMs ?? 6e4;
+	if (!Number.isSafeInteger(n) || n <= 0) throw Error("Dynamic connection ttlMs must be a positive safe integer");
+	return Object.freeze({
+		_tag: "DynamicNatsConnection",
+		resolve: e,
+		ttlMs: n
+	});
+}, s = (e, t) => {
+	let n = e.startsWith("nats:") ? e.slice(5) : e, r = Object.keys(t.nats ?? {});
+	return n || t.defaults?.nats || (r.length === 1 ? r[0] : "");
+}, c = (e, t) => {
+	let n = e.startsWith("redis:") ? e.slice(6) : e, r = Object.keys(t.redis ?? {});
+	return n || t.defaults?.redis || (r.length === 1 ? r[0] : "");
+}, l = (n) => {
+	if (typeof n != "object" || !n || Array.isArray(n)) return "connections must be a named object";
+	if (Object.keys(n).some((e) => ![
+		"redis",
+		"nats",
+		"storage",
+		"analytics",
+		"sql",
+		"defaults",
+		"bindings",
+		"maxDynamicPools",
+		"rotationGraceMs"
+	].includes(e))) return "Connection declarations require an implemented registry kind or option";
+	if (n.defaults !== void 0) {
+		if (typeof n.defaults != "object" || n.defaults === null || Array.isArray(n.defaults)) return "Connection defaults must be a named object";
+		if (Object.keys(n.defaults).some((e) => ![
+			"redis",
+			"nats",
+			"storage",
+			"analytics",
+			"sql"
+		].includes(e))) return "Connection defaults require an implemented registry kind";
+		if (Object.values(n.defaults).some((e) => e !== void 0 && (typeof e != "string" || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(e)))) return "Connection defaults must name declared entries";
+	}
+	if (n.redis !== void 0 && (typeof n.redis != "object" || n.redis === null || Array.isArray(n.redis))) return "connections.redis must be a named object";
+	let i = /* @__PURE__ */ new Set(), a = (e) => typeof e == "object" && !!e && "_tag" in e && e._tag === "ConnectionEnv" && "name" in e && typeof e.name == "string" && /^[A-Z][A-Z0-9_]*$/.test(e.name);
+	for (let [e, t] of Object.entries(n.redis ?? {})) {
+		if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(e)) return "Connection names must start with a letter and contain only letters, digits, underscores or dashes";
+		let n = e.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+		if (i.has(n)) return "Connection names must not collide after environment-name normalization";
+		if (i.add(n), typeof t != "object" || !t || Array.isArray(t)) return "A connection definition must be a named object";
+		if ("_tag" in t) {
+			if ("connectTimeoutMs" in t || "commandTimeoutMs" in t) return "Native Redis timeouts belong to a RESP declaration or resolved dynamic configuration";
+			if (t._tag === "MemoryRedisConnection") {
+				if (t.now !== void 0 && typeof t.now != "function") return "Memory connection now must be a function";
+				continue;
+			}
+			if (t._tag !== "DynamicRedisConnection" || typeof t.resolve != "function" || !Number.isSafeInteger(t.ttlMs) || t.ttlMs <= 0) return "A dynamic connection needs a resolver and a positive ttlMs";
+			continue;
+		}
+		if (!a(t.url) || t.token !== void 0 && !a(t.token)) return "Connection endpoints and credentials must use env() declarations";
+		let o = u(t);
+		if (o) return o;
+		let s = r(t, t.driver);
+		if (s) return s;
+		if (t.driver !== void 0 && !["resp", "http"].includes(t.driver)) return "Redis driver must be resp or http";
+		if (t.cluster !== void 0 && typeof t.cluster != "boolean") return "Redis cluster must be a boolean";
+		if (t.readFrom !== void 0 && ![
+			"primary",
+			"replica",
+			"nearest"
+		].includes(t.readFrom)) return "Redis readFrom must be primary, replica or nearest";
+		if (t.maxmemoryPolicyHint !== void 0 && typeof t.maxmemoryPolicyHint != "string") return "Redis maxmemoryPolicyHint must be a string";
+		if (t.persistence !== void 0 && ![
+			"required",
+			"optional",
+			"none"
+		].includes(t.persistence)) return "Connection persistence must be required, optional or none";
+		if (t.replicas !== void 0 && (!Array.isArray(t.replicas) || !t.replicas.every(a))) return "Replica endpoints must use env() declarations";
+	}
+	if (n.defaults?.redis !== void 0 && !Object.hasOwn(n.redis ?? {}, n.defaults.redis)) return "The default Redis connection must name a declared entry";
+	if (n.nats !== void 0 && (typeof n.nats != "object" || n.nats === null || Array.isArray(n.nats))) return "connections.nats must be a named object";
+	i.clear();
+	for (let [e, t] of Object.entries(n.nats ?? {})) {
+		if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(e)) return "Connection names must start with a letter and contain only letters, digits, underscores or dashes";
+		let n = e.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+		if (i.has(n)) return "Connection names must not collide after environment-name normalization";
+		if (i.add(n), typeof t != "object" || !t || Array.isArray(t)) return "A connection definition must be a named object";
+		if ("_tag" in t) {
+			if (t._tag !== "DynamicNatsConnection" || typeof t.resolve != "function" || !Number.isSafeInteger(t.ttlMs) || t.ttlMs <= 0) return "A dynamic NATS connection needs a resolver and a positive ttlMs";
+			continue;
+		}
+		if (!a(t.url) || [
+			t.token,
+			t.user,
+			t.pass
+		].some((e) => e !== void 0 && !a(e))) return "Connection endpoints and credentials must use env() declarations";
+		let r = u(t);
+		if (r) return r;
+		if (t.user === void 0 != (t.pass === void 0)) return "NATS user and pass must be declared together";
+		if (t.token !== void 0 && t.user !== void 0) return "NATS token and user/pass authentication are exclusive";
+	}
+	if (n.defaults?.nats !== void 0 && !Object.hasOwn(n.nats ?? {}, n.defaults.nats)) return "The default NATS connection must name a declared entry";
+	if (n.storage !== void 0 && (typeof n.storage != "object" || n.storage === null || Array.isArray(n.storage))) return "connections.storage must be a named object";
+	i.clear();
+	for (let [e, t] of Object.entries(n.storage ?? {})) {
+		if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(e)) return "Storage connection names must be named identifiers";
+		let n = e.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+		if (i.has(n)) return "Connection names must not collide after environment-name normalization";
+		if (i.add(n), typeof t != "object" || !t || Array.isArray(t)) return "A storage connection definition must be a named object";
+		if ("_tag" in t) {
+			if (t._tag !== "DynamicStorageConnection" || typeof t.resolve != "function" || !Number.isSafeInteger(t.ttlMs) || t.ttlMs <= 0) return "Dynamic storage needs a resolver and positive ttlMs";
+			continue;
+		}
+		if (Object.keys(t).some((e) => ![
+			"provider",
+			"bucket",
+			"root",
+			"endpoint",
+			"accessKeyId",
+			"secretAccessKey",
+			"accountName",
+			"accountKey",
+			"connectionString",
+			"cdnBaseUrl",
+			"forcePathStyle",
+			"publicAcl",
+			"tls",
+			"persistence",
+			"keyPrefix",
+			"allowSharedNamespace",
+			"region",
+			"label",
+			"acl"
+		].includes(e))) return "Storage declarations contain an unknown field";
+		if (t.persistence !== void 0 && ![
+			"required",
+			"optional",
+			"none"
+		].includes(t.persistence)) return "Storage persistence must be required, optional or none";
+		if (![
+			"s3",
+			"minio",
+			"azure",
+			"filesystem",
+			"memory",
+			"database"
+		].includes(t.provider)) return "Storage requires an implemented provider";
+		let r = u(t);
+		if (r) return r;
+		for (let e of [
+			"endpoint",
+			"accessKeyId",
+			"secretAccessKey",
+			"accountKey",
+			"connectionString"
+		]) if (t[e] !== void 0 && !a(t[e])) return "Storage endpoints and credentials must use env() declarations";
+		for (let e of [
+			"bucket",
+			"root",
+			"accountName",
+			"cdnBaseUrl"
+		]) if (t[e] !== void 0 && typeof t[e] != "string" && !a(t[e])) return "Storage locations must use strings or env() declarations";
+		for (let e of ["publicAcl", "forcePathStyle"]) if (t[e] !== void 0 && typeof t[e] != "boolean") return "Storage policies must be boolean";
+		if (t.accessKeyId === void 0 != (t.secretAccessKey === void 0)) return "Storage access key and secret must be declared together";
+		if ((t.provider === "s3" || t.provider === "minio" || t.provider === "azure") && t.bucket === void 0) return "Object storage requires a declared bucket or container";
+		if (t.provider === "filesystem" && t.root === void 0) return "Filesystem storage requires a declared root";
+	}
+	if (n.defaults?.storage !== void 0 && !Object.hasOwn(n.storage ?? {}, n.defaults.storage)) return "The default storage connection must name a declared entry";
+	if (n.analytics !== void 0 && (typeof n.analytics != "object" || n.analytics === null || Array.isArray(n.analytics))) return "connections.analytics must be a named object";
+	i.clear();
+	for (let [e, r] of Object.entries(n.analytics ?? {})) {
+		if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(e)) return "Analytics connection names must be named identifiers";
+		let n = e.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+		if (i.has(n)) return "Connection names must not collide after environment-name normalization";
+		i.add(n);
+		let a = t(r);
+		if (a) return a;
+	}
+	if (n.defaults?.analytics !== void 0 && !Object.hasOwn(n.analytics ?? {}, n.defaults.analytics)) return "The default analytics connection must name a declared entry";
+	if (n.sql !== void 0 && (typeof n.sql != "object" || n.sql === null || Array.isArray(n.sql))) return "connections.sql must be a named object";
+	i.clear();
+	for (let [t, r] of Object.entries(n.sql ?? {})) {
+		if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(t)) return "SQL connection names must be named identifiers";
+		let n = t.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+		if (i.has(n)) return "Connection names must not collide after environment-name normalization";
+		i.add(n);
+		let a = e(r);
+		if (a) return a;
+	}
+	if (n.defaults?.sql !== void 0 && !Object.hasOwn(n.sql ?? {}, n.defaults.sql)) return "The default SQL connection must name a declared entry";
+	if (n.bindings !== void 0) {
+		if (typeof n.bindings != "object" || n.bindings === null || Array.isArray(n.bindings)) return "Connection bindings must be a named object";
+		for (let [e, t] of Object.entries(n.bindings)) {
+			if (!e.trim() || typeof t != "object" || !t || Array.isArray(t)) return "Connection bindings must map plugin names to role references";
+			for (let [e, n] of Object.entries(t)) if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(e) || typeof n != "string" || !/^(redis|nats|storage|analytics|sql):[A-Za-z][A-Za-z0-9_-]*$/.test(n)) return "Connection bindings require named roles and kind:name references";
+		}
+	}
+}, u = (e) => {
+	for (let t of [
+		"keyPrefix",
+		"region",
+		"label",
+		"acl"
+	]) if (e[t] !== void 0 && typeof e[t] != "string") return `Connection ${t} must be a string`;
+	if (e.allowSharedNamespace !== void 0 && typeof e.allowSharedNamespace != "boolean") return "Connection allowSharedNamespace must be a boolean";
+	if (e.tls !== void 0 && !["auto", "required"].includes(e.tls)) return "Connection tls must be auto or required";
+}, d = (e) => {
+	if (e.to.length === 0) throw Error("A connection route needs at least one target");
+	let t = Object.freeze([...e.to]);
+	return Object.freeze({
+		_tag: "ConnectionRoute",
+		keyAffinity: !0,
+		connections: t,
+		select: ({ key: n }) => {
+			let r = 2166136261;
+			for (let t of e.key(n)) r = Math.imul(r ^ t.codePointAt(0), 16777619) >>> 0;
+			return t[r % t.length];
+		}
+	});
+}, f = (e) => {
+	if (e.length === 0) throw Error("A connection route needs at least one target");
+	let t = Object.freeze([...e]), n = 0;
+	return Object.freeze({
+		_tag: "ConnectionRoute",
+		keyAffinity: !1,
+		connections: t,
+		select: () => {
+			let e = t[n];
+			return n = (n + 1) % t.length, e;
+		}
+	});
+}, p = (e) => Object.freeze({
+	_tag: "ConnectionRoute",
+	keyAffinity: !0,
+	connections: Object.freeze([e]),
+	select: ({ tenantId: t }) => {
+		if (!t) throw Error("A tenant connection route requires tenantId");
+		return e;
+	}
+}), m = (e) => {
+	let t = /* @__PURE__ */ new Set();
+	for (let n of Object.values(e.redis ?? {})) if (!("_tag" in n)) {
+		t.add(n.url.name), n.token && t.add(n.token.name);
+		for (let e of n.replicas ?? []) t.add(e.name);
+	}
+	for (let n of Object.values(e.nats ?? {})) if (!("_tag" in n)) {
+		t.add(n.url.name);
+		for (let e of [
+			n.token,
+			n.user,
+			n.pass
+		]) e !== void 0 && t.add(e.name);
+	}
+	for (let n of Object.values(e.storage ?? {})) if (!("_tag" in n)) for (let e of Object.values(n)) typeof e == "object" && e && "_tag" in e && e._tag === "ConnectionEnv" && t.add(e.name);
+	for (let n of [...Object.values(e.analytics ?? {}), ...Object.values(e.sql ?? {})]) if (!("_tag" in n)) for (let e of Object.values(n)) typeof e == "object" && e && "_tag" in e && e._tag === "ConnectionEnv" && t.add(e.name);
+	return [...t].sort();
+};
+//#endregion
+export { p as byTenant, l as connectionDefinitionsProblem, u as connectionMetadataProblem, m as declaredConnectionEnv, a as dynamic, o as dynamicNats, n as env, i as memory, s as natsConnectionName, c as redisConnectionName, r as redisTimeoutsProblem, f as roundRobin, d as shardBy };

package/dist/connectionMemory.js

@@ -0,0 +1,207 @@
+import "./connectionScripts.js";
+import { decodeCacheAtomicCommand as e, isCacheAtomicRead as t } from "./cacheAtomicProtocol.js";
+import { CACHE_ATOMIC_SCRIPT as n } from "./cacheAtomicScript.js";
+import { isHotReadOperation as r } from "./hotOperations.js";
+import { applyHotOperations as i, compareHotMembers as a } from "./hotState.js";
+import { HotError as o } from "./hot-contract.js";
+import "./hotRedisScript.js";
+import { applyCacheAtomicCommand as s } from "./cacheAtomicState.js";
+//#region src/connectionMemory.ts
+var c = (c = Date.now) => {
+	let l = /* @__PURE__ */ new Map(), u = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new Map(), f = /* @__PURE__ */ new Set(), p = !1, m = () => {
+		if (p) throw Error("Memory connection is closed");
+	}, h = (e, t = c()) => {
+		(l.get(e)?.expiresAt ?? Infinity) <= t && l.delete(e), (u.get(e)?.expiresAt ?? Infinity) <= t && u.delete(e), (d.get(e)?.expiresAt ?? Infinity) <= t && d.delete(e);
+	}, g = (e) => (h(e), l.has(e) || u.has(e) || d.has(e)), _ = (e) => {
+		let t = g(e);
+		return l.delete(e), u.delete(e), d.delete(e), +!!t;
+	}, v = () => [.../* @__PURE__ */ new Set([
+		...l.keys(),
+		...u.keys(),
+		...d.keys()
+	])].filter(g).sort(a), y = (e, t) => {
+		let n = "^";
+		for (let t = 0; t < e.length; t++) {
+			let r = e[t];
+			if (r === "\\" && t + 1 < e.length) n += e[++t].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			else if (r === "*") n += ".*";
+			else if (r === "?") n += ".";
+			else if (r === "[") throw Error("Memory SCAN requires literal keys or * and ? patterns");
+			else n += r.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		}
+		return RegExp(n + "$", "su").test(t);
+	};
+	return {
+		command: () => {
+			let p = !1, b = () => {
+				if (m(), p) throw Error("Memory command generation is closed");
+			}, x = (e, t, n = Infinity) => (b(), _(e), l.set(e, {
+				value: t,
+				expiresAt: n
+			}), "OK"), S = {
+				readOnly: {
+					get: (e) => S.get(e),
+					exists: (e) => S.exists(e),
+					zrange: (e) => S.zrange(e),
+					eval: async (i, a, ...o) => {
+						if (b(), i === n) {
+							let n = e(JSON.parse(String(o[a])));
+							if (!t(n)) throw Error("Memory read-only Lua refuses mutations");
+							return S.eval(i, a, ...o);
+						}
+						if (i !== "\nlocal ops = cjson.decode(ARGV[1])\nlocal tm = redis.call('TIME')\nlocal now = tonumber(tm[1]) * 1000 + math.floor(tonumber(tm[2]) / 1000)\nlocal out = {}\nlocal function fail(op, reason)\n  return cjson.encode({ failure = { operation = op.op, key = op.key, reason = reason } })\nend\nlocal function ttl(k, o)\n  if o and o.ttlMs then redis.call('PEXPIRE', k, string.format('%.0f', o.ttlMs)) end\nend\nlocal function numberString(k, prefix)\n  local raw = redis.call('GET', k)\n  if not raw then return nil end\n  if string.sub(raw, 1, 2) ~= prefix then error('WRONGTYPE') end\n  return string.sub(raw, 3)\nend\nlocal function run(o, k)\n  local op = o.op\n  local expected\n  if string.sub(op, 1, 1) == 'z' then expected = 'zset'\n  elseif string.sub(op, 1, 1) == 'h' then expected = 'hash'\n  elseif op == 'sadd' or op == 'srem' or op == 'smembers' or op == 'sismember' then expected = 'set' end\n  if expected then\n    local actual = redis.call('TYPE', k).ok\n    if actual ~= 'none' and actual ~= expected then error('WRONGTYPE') end\n  end\n  if op == 'zadd' then\n    local pending = {}\n    local mode = o.options and o.options.mode or 'set'\n    for _, m in ipairs(o.members) do\n      local old\n      if mode ~= 'set' then old = pending[m.member] or tonumber(redis.call('ZSCORE', k, m.member)) end\n      local score = m.score\n      if old then\n        if mode == 'max' then score = math.max(old, score)\n        elseif mode == 'min' then score = math.min(old, score)\n        elseif mode == 'incr' then score = old + score end\n      end\n      if score == math.huge or score == -math.huge or score ~= score then error('HOT_INVALID') end\n      pending[m.member] = score\n    end\n    -- RESP-family Lua bridges differ in number-to-argument precision.\n    for member, score in pairs(pending) do redis.call('ZADD', k, string.format('%.17g', score), member) end\n    ttl(k, o.options); return cjson.null\n  elseif op == 'zrem' then\n    local count = 0\n    for _, member in ipairs(o.members) do count = count + redis.call('ZREM', k, member) end\n    return count\n  elseif op == 'zrank' then\n    local cmd = o.order == 'desc' and 'ZREVRANK' or 'ZRANK'\n    return redis.call(cmd, k, o.member) or cjson.null\n  elseif op == 'zscore' then\n    return tonumber(redis.call('ZSCORE', k, o.member)) or cjson.null\n  elseif op == 'zcard' then return redis.call('ZCARD', k)\n  elseif op == 'zrange' then\n    local raw\n    local limit = o.options and o.options.limit\n    if limit == 0 then return {} end\n    if o.range.byRank then\n      local cmd = o.order == 'desc' and 'ZREVRANGE' or 'ZRANGE'\n      local lo, hi = o.range.byRank[1], o.range.byRank[2]\n      if limit then\n        local count = redis.call('ZCARD', k)\n        if lo < 0 then lo = count + lo end\n        if hi < 0 then hi = count + hi end\n        lo = math.max(0, lo)\n        hi = math.min(hi, lo + limit - 1)\n        if hi < lo then return {} end\n      end\n      raw = redis.call(cmd, k, string.format('%.0f', lo), string.format('%.0f', hi), 'WITHSCORES')\n    else\n      local cmd = o.order == 'desc' and 'ZREVRANGEBYSCORE' or 'ZRANGEBYSCORE'\n      local lo, hi = o.range.byScore[1], o.range.byScore[2]\n      if lo > hi then return {} end\n      if o.order == 'desc' then lo, hi = hi, lo end\n      if limit then raw = redis.call(cmd, k, string.format('%.17g', lo), string.format('%.17g', hi), 'WITHSCORES', 'LIMIT', 0, limit)\n      else raw = redis.call(cmd, k, string.format('%.17g', lo), string.format('%.17g', hi), 'WITHSCORES') end\n    end\n    local result = {}\n    for i = 1, #raw / 2 do\n      local score = raw[i * 2]\n      if type(score) == 'number' then score = string.format('%.17g', score) end\n      table.insert(result, { member = raw[i * 2 - 1], score = score })\n    end\n    return result\n  elseif op == 'zremRange' then\n    local pair = o.range.byRank or o.range.byScore\n    local cmd = o.range.byRank and 'ZREMRANGEBYRANK' or 'ZREMRANGEBYSCORE'\n    local format = o.range.byRank and '%.0f' or '%.17g'\n    return redis.call(cmd, k, string.format(format, pair[1]), string.format(format, pair[2]))\n  elseif op == 'incrBy' then\n    local value = tonumber(numberString(k, 'c:')) or 0\n    value = value + o.delta\n    if math.abs(value) > 9007199254740991 then error('HOT_INVALID') end\n    if o.options and o.options.max and value > o.options.max then error('HOT_LIMIT') end\n    redis.call('SET', k, 'c:' .. string.format('%.0f', value), 'KEEPTTL')\n    ttl(k, o.options); return value\n  elseif op == 'tokenBucket' then\n    local raw = numberString(k, 'b:')\n    local old = raw and cjson.decode(raw) or { tokens = o.config.capacity, updatedAt = now }\n    local available = math.min(o.config.capacity, tonumber(old.tokens) + math.max(0, now - tonumber(old.updatedAt)) * o.config.refillPerSec / 1000)\n    local allowed = available >= o.cost\n    local remaining = available\n    if allowed then remaining = remaining - o.cost end\n    local retry = allowed and 0 or math.ceil((o.cost - available) / o.config.refillPerSec * 1000)\n    local life = math.max(1, math.ceil(o.config.capacity / o.config.refillPerSec * 1000))\n    redis.call('SET', k, 'b:' .. cjson.encode({ tokens = string.format('%.17g', remaining), updatedAt = string.format('%.0f', math.max(now, tonumber(old.updatedAt))) }), 'PX', string.format('%.0f', life))\n    return { allowed = allowed, remaining = string.format('%.17g', remaining), retryAfterMs = string.format('%.0f', retry) }\n  elseif op == 'rateLimit' then\n    local raw = numberString(k, 'r:')\n    local s = raw and cjson.decode(raw) or nil\n    local cfg = o.config\n    local at = o.nowMs or now\n    local limit, windowMs, capacity = cfg.limit, cfg.windowMs, cfg.burst\n    local allowed, remaining, resetAt, retryAfter\n    local state\n    if cfg.algorithm == 'fixed-window' then\n      local start = s and s.kind == 'fixed' and tonumber(s.windowStart) or at\n      local count = s and s.kind == 'fixed' and tonumber(s.count) or 0\n      if at - start >= windowMs then start = at; count = 0 end\n      resetAt = start + windowMs\n      allowed = count < limit\n      if allowed then count = count + 1 end\n      remaining = allowed and limit - count or 0\n      retryAfter = allowed and 0 or resetAt - at\n      state = { kind = 'fixed', windowStart = start, count = count }\n    elseif cfg.algorithm == 'sliding-window' then\n      local start = s and s.kind == 'sliding' and tonumber(s.currStart) or at\n      local current = s and s.kind == 'sliding' and tonumber(s.currCount) or 0\n      local previous = s and s.kind == 'sliding' and tonumber(s.prevCount) or 0\n      local elapsed = math.floor((at - start) / windowMs)\n      if elapsed >= 2 then previous = 0; current = 0; start = at\n      elseif elapsed == 1 then previous = current; current = 0; start = start + windowMs end\n      local weight = (windowMs - (at - start)) / windowMs\n      local estimate = previous * weight + current\n      resetAt = start + windowMs\n      allowed = estimate < limit\n      if allowed then current = current + 1 end\n      remaining = allowed and math.max(0, math.floor(limit - estimate - 1)) or 0\n      retryAfter = allowed and 0 or resetAt - at\n      state = { kind = 'sliding', currStart = start, currCount = current, prevCount = previous }\n    else\n      local tokens = s and s.kind == 'token' and tonumber(s.tokens) or capacity\n      local last = s and s.kind == 'token' and tonumber(s.lastRefill) or at\n      local refill = limit / windowMs\n      tokens = math.min(capacity, tokens + (at - last) * refill)\n      allowed = tokens >= 1\n      if allowed then tokens = tokens - 1 end\n      retryAfter = allowed and 0 or math.ceil((1 - tokens) / refill)\n      remaining = allowed and math.floor(tokens) or 0\n      resetAt = at + (allowed and math.ceil((capacity - tokens) / refill) or retryAfter)\n      state = { kind = 'token', tokens = tokens, lastRefill = at }\n    end\n    for field, value in pairs(state) do\n      if type(value) == 'number' then state[field] = string.format('%.17g', value) end\n    end\n    redis.call('SET', k, 'r:' .. cjson.encode(state), 'PX', string.format('%.0f', math.ceil(math.max(windowMs * 2, 60000) + 1000)))\n    return { allowed = allowed, remaining = string.format('%.17g', remaining), resetAtMs = string.format('%.17g', resetAt), retryAfterMs = string.format('%.17g', retryAfter) }\n  elseif op == 'hset' then\n    for f, v in pairs(o.fields) do redis.call('HSET', k, f, v) end\n    ttl(k, o.options); return cjson.null\n  elseif op == 'hget' then return redis.call('HGET', k, o.field) or cjson.null\n  elseif op == 'hgetAll' then\n    local raw = redis.call('HGETALL', k)\n    local fields = {}\n    for i = 1, #raw, 2 do fields[raw[i]] = raw[i + 1] end\n    return fields\n  elseif op == 'hdel' then\n    local count = 0\n    for _, field in ipairs(o.fields) do count = count + redis.call('HDEL', k, field) end\n    return count\n  elseif op == 'sadd' or op == 'srem' then\n    local count = 0\n    for _, member in ipairs(o.members) do count = count + redis.call(op == 'sadd' and 'SADD' or 'SREM', k, member) end\n    if op == 'sadd' then ttl(k, o.options) end\n    return count\n  elseif op == 'smembers' then\n    local members = redis.call('SMEMBERS', k); table.sort(members); return members\n  elseif op == 'sismember' then return redis.call('SISMEMBER', k, o.member) == 1\n  elseif op == 'setNx' then return redis.call('SET', k, 'l:' .. o.value, 'NX', 'PX', string.format('%.0f', o.ttlMs)) ~= false\n  elseif op == 'compareDelete' or op == 'compareExpire' then\n    local value = numberString(k, 'l:')\n    if value == nil or value ~= o.value then return false end\n    if op == 'compareDelete' then return redis.call('DEL', k) == 1 end\n    return redis.call('PEXPIRE', k, string.format('%.0f', o.ttlMs)) == 1\n  elseif op == 'expire' then redis.call('PEXPIRE', k, string.format('%.0f', o.ttlMs)); return cjson.null\n  elseif op == 'delete' then return redis.call('DEL', k) == 1 end\n  error('HOT_INVALID')\nend\nfor i, op in ipairs(ops) do\n  local ok, result = pcall(run, op, KEYS[i])\n  if not ok then\n    local reason = 'unavailable'\n    if string.find(result, 'WRONGTYPE', 1, true) then reason = 'wrongType'\n    elseif string.find(result, 'HOT_LIMIT', 1, true) then reason = 'limit'\n    elseif string.find(result, 'HOT_INVALID', 1, true) then reason = 'invalid' end\n    return fail(op, reason)\n  end\n  -- Redis cjson numbers have only 14 significant digits. Use strings on\n  -- known numeric result slots so safe integers and fractional scores survive.\n  if type(result) == 'number' then result = string.format('%.17g', result) end\n  table.insert(out, { value = result })\nend\nreturn cjson.encode({ results = out })\n") throw Error("Memory read-only Lua requires a framework read script");
+						let s = JSON.parse(String(o[a]));
+						if (!Array.isArray(s) || !s.every((e) => r(e))) throw Error("Memory read-only Lua refuses mutations");
+						return S.eval(i, a, ...o);
+					}
+				},
+				crossNode: !1,
+				ping: async () => (b(), "PONG"),
+				get: async (e) => {
+					if (b(), h(e), u.has(e) || d.has(e)) throw Error("Memory key does not contain a plain string");
+					return l.get(e)?.value ?? null;
+				},
+				set: async (e, t) => x(e, t),
+				psetex: async (e, t, n) => {
+					if (!Number.isSafeInteger(t) || t <= 0) throw Error("Memory PSETEX requires a positive integer");
+					return x(e, n, c() + t);
+				},
+				del: async (e) => (b(), [...new Set(e)].reduce((e, t) => e + _(t), 0)),
+				exists: async (e) => (b(), +!!g(e)),
+				zrange: async (e) => {
+					if (b(), h(e), l.has(e) || d.has(e)) throw Error("Memory key is not a tag sorted set");
+					return [...u.get(e)?.values.entries() ?? []].sort((e, t) => e[1] - t[1] || a(e[0], t[0])).map(([e]) => e);
+				},
+				scan: async (e, t, n) => {
+					if (b(), e !== "0") throw Error("Memory SCAN requires its terminal cursor 0");
+					if (!Number.isSafeInteger(n) || n <= 0) throw Error("Memory SCAN requires a positive count");
+					return {
+						cursor: "0",
+						keys: v().filter((e) => y(t, e))
+					};
+				},
+				eval: async (e, t, ...r) => {
+					if (b(), !Number.isSafeInteger(t) || t < 0 || t > r.length) throw Error("Memory EVAL requires a valid key count");
+					if (e === n) {
+						if (r.length !== t + 1 && r.length !== t + 2) throw Error("Invalid atomic cache arguments");
+						let e = c(), n = (t) => (h(t, e), l.has(t) ? "string" : u.has(t) ? "zset" : d.has(t) ? "other" : "none");
+						return s({
+							now: e,
+							kind: n,
+							get: (e) => {
+								if (!["none", "string"].includes(n(e))) throw Error("Invalid cache string state");
+								return l.get(e)?.value ?? null;
+							},
+							set: (t, n, r) => {
+								l.set(t, {
+									value: n,
+									expiresAt: r === void 0 ? Infinity : e + r
+								}), u.delete(t), d.delete(t);
+							},
+							remove: (e) => {
+								let t = n(e) === "none" ? 0 : 1;
+								return l.delete(e), u.delete(e), d.delete(e), t;
+							},
+							members: (e) => (n(e), [...u.get(e)?.values ?? []].map(([e, t]) => ({
+								member: e,
+								score: t
+							}))),
+							addMember: (e, t, n) => {
+								let r = u.get(e) ?? {
+									values: /* @__PURE__ */ new Map(),
+									expiresAt: Infinity
+								};
+								r.values.set(t, n), u.set(e, r);
+							},
+							removeMember: (e, t) => {
+								u.get(e)?.values.delete(t);
+							},
+							expire: (t, n) => {
+								let r = u.get(t);
+								r !== void 0 && (r.expiresAt = n === null ? Infinity : e + n);
+							},
+							keys: () => [.../* @__PURE__ */ new Set([
+								...l.keys(),
+								...u.keys(),
+								...d.keys()
+							])].filter((e) => n(e) !== "none").sort(a)
+						}, r.slice(0, t).map(String), JSON.parse(String(r[t])), r.length === t + 2 ? JSON.parse(String(r[t + 1])) : {});
+					}
+					if (e === "return redis.call('PUBLISH', ARGV[1], ARGV[2])") {
+						if (t !== 0 || r.length !== 2) throw Error("Invalid publication arguments");
+						let e = String(r[0]), n = String(r[1]), i = 0;
+						for (let t of [...f]) t.channels.has(e) && (i++, t.deliver(e, n));
+						return i;
+					}
+					if (e === "\nlocal ops = cjson.decode(ARGV[1])\nlocal tm = redis.call('TIME')\nlocal now = tonumber(tm[1]) * 1000 + math.floor(tonumber(tm[2]) / 1000)\nlocal out = {}\nlocal function fail(op, reason)\n  return cjson.encode({ failure = { operation = op.op, key = op.key, reason = reason } })\nend\nlocal function ttl(k, o)\n  if o and o.ttlMs then redis.call('PEXPIRE', k, string.format('%.0f', o.ttlMs)) end\nend\nlocal function numberString(k, prefix)\n  local raw = redis.call('GET', k)\n  if not raw then return nil end\n  if string.sub(raw, 1, 2) ~= prefix then error('WRONGTYPE') end\n  return string.sub(raw, 3)\nend\nlocal function run(o, k)\n  local op = o.op\n  local expected\n  if string.sub(op, 1, 1) == 'z' then expected = 'zset'\n  elseif string.sub(op, 1, 1) == 'h' then expected = 'hash'\n  elseif op == 'sadd' or op == 'srem' or op == 'smembers' or op == 'sismember' then expected = 'set' end\n  if expected then\n    local actual = redis.call('TYPE', k).ok\n    if actual ~= 'none' and actual ~= expected then error('WRONGTYPE') end\n  end\n  if op == 'zadd' then\n    local pending = {}\n    local mode = o.options and o.options.mode or 'set'\n    for _, m in ipairs(o.members) do\n      local old\n      if mode ~= 'set' then old = pending[m.member] or tonumber(redis.call('ZSCORE', k, m.member)) end\n      local score = m.score\n      if old then\n        if mode == 'max' then score = math.max(old, score)\n        elseif mode == 'min' then score = math.min(old, score)\n        elseif mode == 'incr' then score = old + score end\n      end\n      if score == math.huge or score == -math.huge or score ~= score then error('HOT_INVALID') end\n      pending[m.member] = score\n    end\n    -- RESP-family Lua bridges differ in number-to-argument precision.\n    for member, score in pairs(pending) do redis.call('ZADD', k, string.format('%.17g', score), member) end\n    ttl(k, o.options); return cjson.null\n  elseif op == 'zrem' then\n    local count = 0\n    for _, member in ipairs(o.members) do count = count + redis.call('ZREM', k, member) end\n    return count\n  elseif op == 'zrank' then\n    local cmd = o.order == 'desc' and 'ZREVRANK' or 'ZRANK'\n    return redis.call(cmd, k, o.member) or cjson.null\n  elseif op == 'zscore' then\n    return tonumber(redis.call('ZSCORE', k, o.member)) or cjson.null\n  elseif op == 'zcard' then return redis.call('ZCARD', k)\n  elseif op == 'zrange' then\n    local raw\n    local limit = o.options and o.options.limit\n    if limit == 0 then return {} end\n    if o.range.byRank then\n      local cmd = o.order == 'desc' and 'ZREVRANGE' or 'ZRANGE'\n      local lo, hi = o.range.byRank[1], o.range.byRank[2]\n      if limit then\n        local count = redis.call('ZCARD', k)\n        if lo < 0 then lo = count + lo end\n        if hi < 0 then hi = count + hi end\n        lo = math.max(0, lo)\n        hi = math.min(hi, lo + limit - 1)\n        if hi < lo then return {} end\n      end\n      raw = redis.call(cmd, k, string.format('%.0f', lo), string.format('%.0f', hi), 'WITHSCORES')\n    else\n      local cmd = o.order == 'desc' and 'ZREVRANGEBYSCORE' or 'ZRANGEBYSCORE'\n      local lo, hi = o.range.byScore[1], o.range.byScore[2]\n      if lo > hi then return {} end\n      if o.order == 'desc' then lo, hi = hi, lo end\n      if limit then raw = redis.call(cmd, k, string.format('%.17g', lo), string.format('%.17g', hi), 'WITHSCORES', 'LIMIT', 0, limit)\n      else raw = redis.call(cmd, k, string.format('%.17g', lo), string.format('%.17g', hi), 'WITHSCORES') end\n    end\n    local result = {}\n    for i = 1, #raw / 2 do\n      local score = raw[i * 2]\n      if type(score) == 'number' then score = string.format('%.17g', score) end\n      table.insert(result, { member = raw[i * 2 - 1], score = score })\n    end\n    return result\n  elseif op == 'zremRange' then\n    local pair = o.range.byRank or o.range.byScore\n    local cmd = o.range.byRank and 'ZREMRANGEBYRANK' or 'ZREMRANGEBYSCORE'\n    local format = o.range.byRank and '%.0f' or '%.17g'\n    return redis.call(cmd, k, string.format(format, pair[1]), string.format(format, pair[2]))\n  elseif op == 'incrBy' then\n    local value = tonumber(numberString(k, 'c:')) or 0\n    value = value + o.delta\n    if math.abs(value) > 9007199254740991 then error('HOT_INVALID') end\n    if o.options and o.options.max and value > o.options.max then error('HOT_LIMIT') end\n    redis.call('SET', k, 'c:' .. string.format('%.0f', value), 'KEEPTTL')\n    ttl(k, o.options); return value\n  elseif op == 'tokenBucket' then\n    local raw = numberString(k, 'b:')\n    local old = raw and cjson.decode(raw) or { tokens = o.config.capacity, updatedAt = now }\n    local available = math.min(o.config.capacity, tonumber(old.tokens) + math.max(0, now - tonumber(old.updatedAt)) * o.config.refillPerSec / 1000)\n    local allowed = available >= o.cost\n    local remaining = available\n    if allowed then remaining = remaining - o.cost end\n    local retry = allowed and 0 or math.ceil((o.cost - available) / o.config.refillPerSec * 1000)\n    local life = math.max(1, math.ceil(o.config.capacity / o.config.refillPerSec * 1000))\n    redis.call('SET', k, 'b:' .. cjson.encode({ tokens = string.format('%.17g', remaining), updatedAt = string.format('%.0f', math.max(now, tonumber(old.updatedAt))) }), 'PX', string.format('%.0f', life))\n    return { allowed = allowed, remaining = string.format('%.17g', remaining), retryAfterMs = string.format('%.0f', retry) }\n  elseif op == 'rateLimit' then\n    local raw = numberString(k, 'r:')\n    local s = raw and cjson.decode(raw) or nil\n    local cfg = o.config\n    local at = o.nowMs or now\n    local limit, windowMs, capacity = cfg.limit, cfg.windowMs, cfg.burst\n    local allowed, remaining, resetAt, retryAfter\n    local state\n    if cfg.algorithm == 'fixed-window' then\n      local start = s and s.kind == 'fixed' and tonumber(s.windowStart) or at\n      local count = s and s.kind == 'fixed' and tonumber(s.count) or 0\n      if at - start >= windowMs then start = at; count = 0 end\n      resetAt = start + windowMs\n      allowed = count < limit\n      if allowed then count = count + 1 end\n      remaining = allowed and limit - count or 0\n      retryAfter = allowed and 0 or resetAt - at\n      state = { kind = 'fixed', windowStart = start, count = count }\n    elseif cfg.algorithm == 'sliding-window' then\n      local start = s and s.kind == 'sliding' and tonumber(s.currStart) or at\n      local current = s and s.kind == 'sliding' and tonumber(s.currCount) or 0\n      local previous = s and s.kind == 'sliding' and tonumber(s.prevCount) or 0\n      local elapsed = math.floor((at - start) / windowMs)\n      if elapsed >= 2 then previous = 0; current = 0; start = at\n      elseif elapsed == 1 then previous = current; current = 0; start = start + windowMs end\n      local weight = (windowMs - (at - start)) / windowMs\n      local estimate = previous * weight + current\n      resetAt = start + windowMs\n      allowed = estimate < limit\n      if allowed then current = current + 1 end\n      remaining = allowed and math.max(0, math.floor(limit - estimate - 1)) or 0\n      retryAfter = allowed and 0 or resetAt - at\n      state = { kind = 'sliding', currStart = start, currCount = current, prevCount = previous }\n    else\n      local tokens = s and s.kind == 'token' and tonumber(s.tokens) or capacity\n      local last = s and s.kind == 'token' and tonumber(s.lastRefill) or at\n      local refill = limit / windowMs\n      tokens = math.min(capacity, tokens + (at - last) * refill)\n      allowed = tokens >= 1\n      if allowed then tokens = tokens - 1 end\n      retryAfter = allowed and 0 or math.ceil((1 - tokens) / refill)\n      remaining = allowed and math.floor(tokens) or 0\n      resetAt = at + (allowed and math.ceil((capacity - tokens) / refill) or retryAfter)\n      state = { kind = 'token', tokens = tokens, lastRefill = at }\n    end\n    for field, value in pairs(state) do\n      if type(value) == 'number' then state[field] = string.format('%.17g', value) end\n    end\n    redis.call('SET', k, 'r:' .. cjson.encode(state), 'PX', string.format('%.0f', math.ceil(math.max(windowMs * 2, 60000) + 1000)))\n    return { allowed = allowed, remaining = string.format('%.17g', remaining), resetAtMs = string.format('%.17g', resetAt), retryAfterMs = string.format('%.17g', retryAfter) }\n  elseif op == 'hset' then\n    for f, v in pairs(o.fields) do redis.call('HSET', k, f, v) end\n    ttl(k, o.options); return cjson.null\n  elseif op == 'hget' then return redis.call('HGET', k, o.field) or cjson.null\n  elseif op == 'hgetAll' then\n    local raw = redis.call('HGETALL', k)\n    local fields = {}\n    for i = 1, #raw, 2 do fields[raw[i]] = raw[i + 1] end\n    return fields\n  elseif op == 'hdel' then\n    local count = 0\n    for _, field in ipairs(o.fields) do count = count + redis.call('HDEL', k, field) end\n    return count\n  elseif op == 'sadd' or op == 'srem' then\n    local count = 0\n    for _, member in ipairs(o.members) do count = count + redis.call(op == 'sadd' and 'SADD' or 'SREM', k, member) end\n    if op == 'sadd' then ttl(k, o.options) end\n    return count\n  elseif op == 'smembers' then\n    local members = redis.call('SMEMBERS', k); table.sort(members); return members\n  elseif op == 'sismember' then return redis.call('SISMEMBER', k, o.member) == 1\n  elseif op == 'setNx' then return redis.call('SET', k, 'l:' .. o.value, 'NX', 'PX', string.format('%.0f', o.ttlMs)) ~= false\n  elseif op == 'compareDelete' or op == 'compareExpire' then\n    local value = numberString(k, 'l:')\n    if value == nil or value ~= o.value then return false end\n    if op == 'compareDelete' then return redis.call('DEL', k) == 1 end\n    return redis.call('PEXPIRE', k, string.format('%.0f', o.ttlMs)) == 1\n  elseif op == 'expire' then redis.call('PEXPIRE', k, string.format('%.0f', o.ttlMs)); return cjson.null\n  elseif op == 'delete' then return redis.call('DEL', k) == 1 end\n  error('HOT_INVALID')\nend\nfor i, op in ipairs(ops) do\n  local ok, result = pcall(run, op, KEYS[i])\n  if not ok then\n    local reason = 'unavailable'\n    if string.find(result, 'WRONGTYPE', 1, true) then reason = 'wrongType'\n    elseif string.find(result, 'HOT_LIMIT', 1, true) then reason = 'limit'\n    elseif string.find(result, 'HOT_INVALID', 1, true) then reason = 'invalid' end\n    return fail(op, reason)\n  end\n  -- Redis cjson numbers have only 14 significant digits. Use strings on\n  -- known numeric result slots so safe integers and fractional scores survive.\n  if type(result) == 'number' then result = string.format('%.17g', result) end\n  table.insert(out, { value = result })\nend\nreturn cjson.encode({ results = out })\n") {
+						let e = JSON.parse(String(r[t]));
+						if (!Array.isArray(e) || e.length !== t || r.length !== t + 1) throw Error("Invalid HotStore batch");
+						try {
+							let t = e.map((e, t) => {
+								let n = String(r[t]);
+								if (h(n), l.has(n) || u.has(n)) throw new o({
+									operation: e.op,
+									key: e.key,
+									reason: "wrongType"
+								});
+								return {
+									...e,
+									key: n
+								};
+							}), n = i(d, t, c());
+							return JSON.stringify({ results: n.map((e) => ({ value: e })) });
+						} catch (n) {
+							if (!(n instanceof o)) throw n;
+							let i = r.slice(0, t).findIndex((e) => e === n.key);
+							return JSON.stringify({ failure: {
+								operation: n.operation,
+								key: i < 0 ? n.key : e[i].key,
+								reason: n.reason
+							} });
+						}
+					}
+					throw Error("Memory connections execute framework scripts only; arbitrary Lua requires a Redis transport");
+				},
+				close: async () => {
+					p = !0;
+				}
+			};
+			return S;
+		},
+		subscriber: () => {
+			m();
+			let e = !1, t = /* @__PURE__ */ new Set(), n = /* @__PURE__ */ new Set(), r = {
+				channels: n,
+				deliver: (e, n) => {
+					for (let r of [...t]) try {
+						r(e, n);
+					} catch {}
+				}
+			};
+			f.add(r);
+			let i = () => {
+				if (m(), e) throw Error("Memory subscriber is closed");
+			};
+			return {
+				subscribe: async (e) => {
+					i(), n.add(e);
+				},
+				unsubscribe: async (e) => {
+					i(), n.delete(e);
+				},
+				onMessage: (e) => (i(), t.add(e), () => {
+					t.delete(e);
+				}),
+				onTransportEvent: () => (i(), () => {}),
+				close: async () => {
+					e || (e = !0, f.delete(r), n.clear(), t.clear());
+				}
+			};
+		},
+		dispose: () => {
+			p = !0, l.clear(), u.clear(), d.clear(), f.clear();
+		}
+	};
+};
+//#endregion
+export { c as makeMemoryConnectionState };

package/dist/connectionMetrics.js

@@ -0,0 +1,79 @@
+import { Effect as e, Metric as t } from "effect";
+//#region src/connectionMetrics.ts
+var n = /* @__PURE__ */ new Map(), r = t.gauge("voltro_connection_up", { description: "Whether every current pool for this reference has observed readiness and admits commands; not a persistence or capacity measurement." }), i = t.gauge("voltro_connection_pools", { description: "Owned physical generations, including draining generations." }), a = t.gauge("voltro_connection_active_commands", { description: "Borrowed generation leases, including complete streams and transactions." }), o = t.counter("voltro_connection_commands_total", { description: "Admitted commands and scoped streams; includes read-only probes." }), s = t.counter("voltro_connection_errors_total", { description: "Failed registry operations; includes rejected circuit admission and connection construction." }), c = t.gauge("voltro_connection_latency_ms", { description: "Duration of the most recently completed command or scoped stream in milliseconds." }), l = t.histogram("voltro_connection_duration_seconds", {
+	boundaries: t.exponentialBoundaries({
+		start: .001,
+		factor: 2,
+		count: 16
+	}),
+	description: "Complete command and scoped stream duration in seconds."
+}), u = t.counter("voltro_connection_rotations_total", { description: "Completed whole-registry rotations by outcome, including rolled-back attempts." }), d = t.histogram("voltro_connection_rotation_duration_seconds", {
+	boundaries: t.exponentialBoundaries({
+		start: .001,
+		factor: 2,
+		count: 16
+	}),
+	description: "Whole-registry rotation duration in seconds."
+}), f = (f) => {
+	let p = /* @__PURE__ */ new WeakMap(), m = (e, n) => t.withAttributes(t.withAttributes(e, { namespace: f }), { connection: n }), h = (o, s) => {
+		let c = [...n.get(o)?.values() ?? []], l = c.filter((e) => e.current);
+		e.runSync(e.all([
+			t.update(m(r, s), l.length > 0 && l.every((e) => e.available) ? 1 : 0),
+			t.update(m(i, s), c.length),
+			t.update(m(a, s), c.reduce((e, t) => e + t.active, 0))
+		], { discard: !0 }));
+	}, g = (e, t) => {
+		let n = p.get(e);
+		n !== void 0 && (t(n.measurement), h(n.key, n.reference));
+	};
+	return {
+		register: (r, i) => {
+			let a = JSON.stringify([f, i]), c = {}, l = {
+				current: !1,
+				available: !1,
+				active: 0
+			}, u = n.get(a) ?? /* @__PURE__ */ new Map();
+			u.set(c, l), n.set(a, u), p.set(r, {
+				key: a,
+				reference: i,
+				token: c,
+				measurement: l
+			}), e.runSync(e.andThen(t.update(m(o, i), 0), t.update(m(s, i), 0))), h(a, i);
+		},
+		available: (e, t) => g(e, (e) => {
+			e.available = t;
+		}),
+		activate: (e) => g(e, (e) => {
+			e.current = !0;
+		}),
+		retire: (e) => g(e, (e) => {
+			e.current = !1;
+		}),
+		acquire: (e) => g(e, (e) => {
+			e.active++;
+		}),
+		release: (e) => g(e, (e) => {
+			e.active--;
+		}),
+		close: (e) => {
+			let t = p.get(e);
+			if (t === void 0) return;
+			let r = n.get(t.key);
+			r?.delete(t.token), r?.size === 0 && n.delete(t.key), p.delete(e), h(t.key, t.reference);
+		},
+		command: (n) => {
+			e.runSync(t.update(m(o, n), 1));
+		},
+		error: (n) => {
+			e.runSync(t.update(m(s, n), 1));
+		},
+		completed: (n, r) => {
+			e.runSync(e.andThen(t.update(m(c, n), r), t.update(m(l, n), r / 1e3)));
+		},
+		rotated: (n, r) => {
+			e.runSync(e.andThen(t.update(t.withAttributes(t.withAttributes(u, { namespace: f }), { outcome: n }), 1), t.update(t.withAttributes(d, { namespace: f }), r / 1e3)));
+		}
+	};
+};
+//#endregion
+export { f as makeConnectionMetrics };

package/dist/connectionNamespace.js

@@ -0,0 +1,19 @@
+//#region src/connectionNamespace.ts
+var e = (e) => encodeURIComponent(e).replace(/[!'()*]/g, (e) => `%${e.charCodeAt(0).toString(16).toUpperCase()}`), t = (t) => {
+	if (typeof t.appName != "string" || !t.appName.trim() || typeof t.environment != "string" || !t.environment.trim()) throw Error("Connection namespace requires a nonempty app name and environment");
+	return `voltro:${e(t.appName)}:${e(t.environment)}:`;
+}, n = (e, n) => {
+	let r = t(n), i = e.keyPrefix ?? r;
+	if (typeof i != "string") throw Error("Connection keyPrefix must be a string");
+	if (e.allowSharedNamespace !== void 0 && typeof e.allowSharedNamespace != "boolean") throw Error("Connection allowSharedNamespace must be a boolean");
+	if (n.environment === "production") {
+		if (!i.trim()) throw Error("Production connection keyPrefix must be nonempty");
+		if (i !== r && e.allowSharedNamespace !== !0) throw Error("A custom production connection keyPrefix requires allowSharedNamespace: true");
+	}
+	return {
+		...e,
+		keyPrefix: i
+	};
+};
+//#endregion
+export { n as applyConnectionNamespace, t as connectionNamespace };