@voltro/env 0.28.0 → 0.30.0

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/env itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (49 packages).
+Generated from the resolved runtime dependency closure (52 packages).
 
 ---
 
@@ -3956,6 +3956,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
+## isomorphic.js@0.2.5
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2020 Kevin Jahns <kevin.jahns@protonmail.com>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## jose@6.2.4
 
 License: MIT
@@ -4018,6 +4046,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## lib0@0.2.117
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2019 Kevin Jahns <kevin.jahns@protonmail.com>.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## mime@3.0.0
 
 License: MIT
@@ -4566,3 +4622,33 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## yjs@13.6.31
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2023
+  - Kevin Jahns <kevin.jahns@protonmail.com>.
+  - Chair of Computer Science 5 (Databases & Information Systems), RWTH Aachen University, Germany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+

package/dist/index.d.ts

@@ -289,12 +289,18 @@ export declare const frameworkEnvNames: () => ReadonlyArray<string>;
 /** True once the boot gate has installed a snapshot. */
 export declare const hasEnvSnapshot: () => boolean;
 
+/** Whether a live rotation is in its overlap window for `key` (previous still
+ *  valid). Prunes an elapsed window as a side effect, same as the read. */
+export declare const hasLiveOverlap: (key: string) => boolean;
+
 /** Lift a field's optionality + value type to the accessor's value type. */
 export declare type InferEnvValue<F> = F extends EnvFieldSpec<infer A, infer O> ? (O extends true ? A | undefined : A) : never;
 
 /** Install the boot-resolved value map. Called once by the CLI after the
  *  env-validation gate passes. Idempotent: a second install replaces the
- *  first (a supervised dev restart re-resolves cleanly). */
+ *  first (a supervised dev restart re-resolves cleanly) AND clears any live
+ *  overlay — a fresh boot re-resolves every value, so a stale rotation must
+ *  not survive it. */
 export declare const installEnvSnapshot: (values: Record<string, unknown>) => void;
 
 /** Runtime type guard: is `value` an `EnvContract`? Used by the CLI loader,
@@ -327,9 +333,35 @@ export declare type PublicKeys<M extends EnvSchemaMap> = {
     [K in keyof M]: M[K]['access'] extends 'public' ? K : never;
 }[keyof M];
 
-/** Read a resolved value. Returns `undefined` for unknown / unset keys. */
+/** Read a resolved value. A live-rotated value wins over the frozen snapshot.
+ *  Returns `undefined` for unknown / unset keys. */
 export declare const readEnvValue: (key: string) => unknown;
 
+/**
+ * The PREVIOUS value of a live-rotated key, while its grace window is open.
+ *
+ * A verifier that must accept work created just before a rotation (a signature,
+ * a token, a ciphertext) reads BOTH the current value and this one during
+ * cutover — the same current/previous overlap sessions/webhooks use. Returns
+ * `undefined` once the window has elapsed (the value is REVOKED, and pruned on
+ * read so it cannot linger), or when the key was never rotated with an overlap.
+ */
+export declare const readEnvValuePrevious: (key: string) => unknown;
+
+/**
+ * Install a live-rotated value over the frozen snapshot.
+ *
+ * `previous` + `graceMs` record the pre-rotation value as valid for a grace
+ * window: `readEnvValuePrevious` returns it until the window elapses, then
+ * revokes it. Omit them for a hard cutover with no overlap. Requires a boot
+ * snapshot to already exist — a live refresh is a POST-boot operation, and
+ * refreshing before boot is the same wiring bug `requireEnvValue` names.
+ */
+export declare const refreshEnvValue: (key: string, value: unknown, options?: {
+    readonly previous?: unknown;
+    readonly graceMs?: number;
+}) => void;
+
 /**
  * Render a grouped `.env.example`. App + plugin entries come first (the things
  * a developer must fill in), then the framework catalog grouped by area.
@@ -351,7 +383,7 @@ export declare interface RenderDotEnvOptions {
  */
 export declare const requireEnvValue: (key: string) => unknown;
 
-/** Reset the snapshot (tests). */
+/** Reset the snapshot + any live overlay + the clock (tests). */
 export declare const resetEnvSnapshot: () => void;
 
 export declare interface ResolvedEnv {
@@ -395,4 +427,7 @@ declare interface SecretFieldOptions {
     readonly generate?: 'base64url' | 'hex';
 }
 
+/** Test seam — override the clock the grace window measures against. */
+export declare const setEnvClock: (fn: () => number) => void;
+
 export { }

package/dist/index.js

@@ -1,10 +1,10 @@
-import { a as e, i as t, n, r, t as i } from "./snapshot-qX0GrQfx.js";
-import { Either as a, ParseResult as o, Schema as s } from "effect";
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c } from "./snapshot-DLnTMXyV.js";
+import { Either as l, ParseResult as u, Schema as d } from "effect";
 //#region src/define.ts
-var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
+var f = "VOLTRO_PUBLIC_", p = (e, t) => Object.freeze({
 	vars: Object.freeze({ ...e }),
 	publicPrefix: t?.publicPrefix ?? "VOLTRO_PUBLIC_"
-}), u = (e) => typeof e == "object" && !!e && "vars" in e && typeof e.vars == "object" && e.vars !== null, d = (e, t, n, r) => ({
+}), m = (e) => typeof e == "object" && !!e && "vars" in e && typeof e.vars == "object" && e.vars !== null, h = (e, t, n, r) => ({
 	kind: e,
 	access: r.access,
 	schema: t,
@@ -13,65 +13,65 @@ var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
 	...r.default === void 0 ? {} : { default: r.default },
 	...r.description === void 0 ? {} : { description: r.description },
 	...r.example === void 0 ? {} : { example: r.example }
-}), f = s.transformOrFail(s.String, s.Boolean, {
+}), g = d.transformOrFail(d.String, d.Boolean, {
 	strict: !0,
 	decode: (e, t, n) => {
 		let r = e.trim().toLowerCase();
-		return r === "true" || r === "1" || r === "yes" || r === "on" ? o.succeed(!0) : r === "false" || r === "0" || r === "no" || r === "off" || r === "" ? o.succeed(!1) : o.fail(new o.Type(n, e, `expected a boolean (true/false/1/0/yes/no/on/off), got "${e}"`));
+		return r === "true" || r === "1" || r === "yes" || r === "on" ? u.succeed(!0) : r === "false" || r === "0" || r === "no" || r === "off" || r === "" ? u.succeed(!1) : u.fail(new u.Type(n, e, `expected a boolean (true/false/1/0/yes/no/on/off), got "${e}"`));
 	},
-	encode: (e) => o.succeed(e ? "true" : "false")
-}), p = (e) => URL.canParse(e), m = {
-	string: (e) => d("string", s.String, "string", e),
-	number: (e) => d("number", s.NumberFromString, "number", e),
-	port: (e) => d("port", s.NumberFromString.pipe(s.int(), s.between(1, 65535)), "number", e),
-	boolean: (e) => d("boolean", f, "boolean", e),
+	encode: (e) => u.succeed(e ? "true" : "false")
+}), _ = (e) => URL.canParse(e), v = {
+	string: (e) => h("string", d.String, "string", e),
+	number: (e) => h("number", d.NumberFromString, "number", e),
+	port: (e) => h("port", d.NumberFromString.pipe(d.int(), d.between(1, 65535)), "number", e),
+	boolean: (e) => h("boolean", g, "boolean", e),
 	secret: (e) => {
 		let t = e.minLength ?? 32;
 		return {
-			...d("secret", s.String.pipe(s.filter((e) => e.trim().length >= t || `expected at least ${t} characters — this looks like a placeholder, not a secret. Generate one with \`voltro secret generate\``)), "string", {
+			...h("secret", d.String.pipe(d.filter((e) => e.trim().length >= t || `expected at least ${t} characters — this looks like a placeholder, not a secret. Generate one with \`voltro secret generate\``)), "string", {
 				...e,
 				access: "secret"
 			}),
 			...e.generate === void 0 ? {} : { generate: e.generate }
 		};
 	},
-	url: (e) => d("url", s.String.pipe(s.filter((e) => p(e) || `expected a valid URL, got "${e}"`)), "string", e),
-	enum: (e, t) => d("enum", s.Literal(...e), e.map((e) => `'${e}'`).join(" | "), t)
-}, h = (e, t, n) => {
-	let r = t.schema, i = s.decodeUnknownEither(r)(n);
-	return a.mapLeft(i, (n) => ({
+	url: (e) => h("url", d.String.pipe(d.filter((e) => _(e) || `expected a valid URL, got "${e}"`)), "string", e),
+	enum: (e, t) => h("enum", d.Literal(...e), e.map((e) => `'${e}'`).join(" | "), t)
+}, y = (e, t, n) => {
+	let r = t.schema, i = d.decodeUnknownEither(r)(n);
+	return l.mapLeft(i, (n) => ({
 		key: e,
 		access: t.access,
 		reason: "invalid",
 		message: n.message
 	}));
-}, g = async (e) => {
-	let t = e.readEnv ?? ((e) => process.env[e]), n = e.resolveSecret ?? ((e) => Promise.resolve(t(e))), r = {}, i = {}, o = [], s = e.contract ? Object.entries(e.contract.vars) : [];
-	for (let [e, c] of s) {
-		let s = (c.access === "secret" ? await n(e) : t(e)) ?? c.default;
-		if (s === void 0) {
-			c.optional ? (r[e] = void 0, c.access === "public" && (i[e] = void 0)) : o.push({
+}, b = async (e) => {
+	let t = e.readEnv ?? ((e) => process.env[e]), n = e.resolveSecret ?? ((e) => Promise.resolve(t(e))), r = {}, i = {}, a = [], o = e.contract ? Object.entries(e.contract.vars) : [];
+	for (let [e, s] of o) {
+		let o = (s.access === "secret" ? await n(e) : t(e)) ?? s.default;
+		if (o === void 0) {
+			s.optional ? (r[e] = void 0, s.access === "public" && (i[e] = void 0)) : a.push({
 				key: e,
-				access: c.access,
+				access: s.access,
 				reason: "missing",
-				message: `required ${c.access} env var "${e}" is unset` + (c.description ? ` — ${c.description}` : "")
+				message: `required ${s.access} env var "${e}" is unset` + (s.description ? ` — ${s.description}` : "")
 			});
 			continue;
 		}
-		let l = h(e, c, s);
-		if (a.isLeft(l)) {
-			o.push(l.left);
+		let c = y(e, s, o);
+		if (l.isLeft(c)) {
+			a.push(c.left);
 			continue;
 		}
-		r[e] = l.right, c.access === "public" && (i[e] = l.right);
+		r[e] = c.right, s.access === "public" && (i[e] = c.right);
 	}
 	return {
 		values: r,
 		publicValues: i,
-		errors: o,
-		ok: o.length === 0
+		errors: a,
+		ok: a.length === 0
 	};
-}, _ = (e, t) => {
+}, x = (e, t) => {
 	let n = e?.publicPrefix;
 	if (!e || typeof n != "string") return [];
 	let r = [];
@@ -87,10 +87,10 @@ var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
 		message: `public env var "${i}" on a web app ships to the browser and must be named "${n}…" (e.g. "${n}${i}"). Rename it, mark it access:'secret' to keep it server-only, or set publicPrefix:false in defineEnv to opt out.`
 	});
 	return r;
-}, v = (e) => {
+}, S = (e) => {
 	let t = e.map((e) => `  • ${e.key} (${e.access}, ${e.reason}): ${e.message}`);
 	return `environment validation failed (${e.length} ${e.length === 1 ? "error" : "errors"}):\n${t.join("\n")}`;
-}, y = (e) => e ? Object.entries(e.vars).map(([e, t]) => ({
+}, C = (e) => e ? Object.entries(e.vars).map(([e, t]) => ({
 	key: e,
 	owner: "app",
 	access: t.access,
@@ -99,14 +99,14 @@ var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
 	...t.example === void 0 ? {} : { example: t.example },
 	...t.default === void 0 ? {} : { default: t.default },
 	kind: t.kind
-})) : [], b = (e, t) => t ? t.map((t) => ({
+})) : [], w = (e, t) => t ? t.map((t) => ({
 	key: t.name,
 	owner: `plugin:${e}`,
 	access: t.secret ? "secret" : "public",
 	required: t.required,
 	...t.description === void 0 ? {} : { description: t.description },
 	...t.example === void 0 ? {} : { example: t.example }
-})) : [], x = (e, t, n, r, i) => ({
+})) : [], T = (e, t, n, r, i) => ({
 	key: e,
 	owner: "framework",
 	access: n,
@@ -114,37 +114,37 @@ var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
 	description: r,
 	group: t,
 	...i === void 0 ? {} : { example: i }
-}), S = [
-	x("NODE_ENV", "runtime", "public", "Node environment (development | production).", "development"),
-	x("PORT", "runtime", "public", "Port the api/web server binds to. Overrides app.config `port`.", "4000"),
-	x("VOLTRO_REGION", "runtime", "public", "Region tag for replica locality (else AWS_REGION/FLY_REGION/…).", "us-east-1"),
-	x("VOLTRO_AUTO_MIGRATE", "runtime", "public", "Set 0 to skip boot auto-migrate (CI-applied migrations).", "1"),
-	x("DB_DIALECT", "database", "public", "postgres | mysql | mariadb | mssql | sqlite | memory.", "postgres"),
-	x("DB_URL", "database", "secret", "Connection URL (carries credentials). Preferred over discrete DB_* fields.", "postgres://user:pw@localhost:5432/app"),
-	x("DB_HOST", "database", "public", "Database host (discrete-field form; DB_URL preferred).", "localhost"),
-	x("DB_PORT", "database", "public", "Database port.", "5432"),
-	x("DB_USER", "database", "public", "Database user.", "postgres"),
-	x("DB_PASSWORD", "database", "secret", "Database password."),
-	x("DB_DATABASE", "database", "public", "Database name.", "app"),
-	x("DB_MAX_CONNECTIONS", "database", "public", "Per-process connection pool cap.", "10"),
-	x("DB_REPLICA_URLS", "database", "secret", "Comma-separated read-replica URLs (carry credentials)."),
-	x("DB_REPLICA_REGIONS", "database", "public", "Comma-separated region tags matching DB_REPLICA_URLS order."),
-	x("RYW_STORE", "database", "public", "Read-your-writes position store: memory | redis.", "memory"),
-	x("CACHE_BACKEND", "cache", "public", "@voltro/cache backend: memory | redis.", "memory"),
-	x("CACHE_REDIS_URL", "cache", "secret", "Redis/Valkey/KeyDB/Dragonfly/Upstash URL (may carry credentials).", "redis://localhost:6379"),
-	x("CACHE_REDIS_DRIVER", "cache", "public", "resp (ioredis TCP) | http (Upstash REST, edge).", "resp"),
-	x("CACHE_REDIS_TOKEN", "cache", "secret", "Upstash REST token (http driver)."),
-	x("CACHE_KEY_PREFIX", "cache", "public", "Cache key namespace.", "voltro:cache"),
-	x("REDIS_URL", "cache", "secret", "Generic Redis URL fallback (cache / ryw / ratelimit).", "redis://localhost:6379"),
-	x("VOLTRO_SESSION_SECRET", "security", "secret", "HMAC signing key for session cookies. REQUIRED in production."),
-	x("VOLTRO_INSPECT", "security", "public", "Set off to disable the /_voltro/inspect surface entirely.", "on"),
-	x("VOLTRO_INSPECT_TOKEN", "security", "secret", "Bearer token gating /_voltro/inspect/* on public deploys."),
-	x("VOLTRO_TENANT_ISOLATION", "security", "public", "shared-schema (default) | namespace (physical per-tenant)."),
-	x("FRAMEWORK_TRACING", "observability", "public", "off | console | otlp. Auto-otlp when OTEL_* is set."),
-	x("OTEL_EXPORTER_OTLP_ENDPOINT", "observability", "public", "OTLP/HTTP collector endpoint (traces + metrics).", "http://localhost:4318"),
-	x("OTEL_SERVICE_NAME", "observability", "public", "OTel service name.", "voltro-api"),
-	x("SSR_CACHE", "web", "public", "ISR cache backend for `voltro start`: memory | postgres.", "memory")
-], C = () => S.map((e) => e.key), w = (e) => {
+}), E = [
+	T("NODE_ENV", "runtime", "public", "Node environment (development | production).", "development"),
+	T("PORT", "runtime", "public", "Port the api/web server binds to. Overrides app.config `port`.", "4000"),
+	T("VOLTRO_REGION", "runtime", "public", "Region tag for replica locality (else AWS_REGION/FLY_REGION/…).", "us-east-1"),
+	T("VOLTRO_AUTO_MIGRATE", "runtime", "public", "Set 0 to skip boot auto-migrate (CI-applied migrations).", "1"),
+	T("DB_DIALECT", "database", "public", "postgres | mysql | mariadb | mssql | sqlite | memory.", "postgres"),
+	T("DB_URL", "database", "secret", "Connection URL (carries credentials). Preferred over discrete DB_* fields.", "postgres://user:pw@localhost:5432/app"),
+	T("DB_HOST", "database", "public", "Database host (discrete-field form; DB_URL preferred).", "localhost"),
+	T("DB_PORT", "database", "public", "Database port.", "5432"),
+	T("DB_USER", "database", "public", "Database user.", "postgres"),
+	T("DB_PASSWORD", "database", "secret", "Database password."),
+	T("DB_DATABASE", "database", "public", "Database name.", "app"),
+	T("DB_MAX_CONNECTIONS", "database", "public", "Per-process connection pool cap.", "10"),
+	T("DB_REPLICA_URLS", "database", "secret", "Comma-separated read-replica URLs (carry credentials)."),
+	T("DB_REPLICA_REGIONS", "database", "public", "Comma-separated region tags matching DB_REPLICA_URLS order."),
+	T("RYW_STORE", "database", "public", "Read-your-writes position store: memory | redis.", "memory"),
+	T("CACHE_BACKEND", "cache", "public", "@voltro/cache backend: memory | redis.", "memory"),
+	T("CACHE_REDIS_URL", "cache", "secret", "Redis/Valkey/KeyDB/Dragonfly/Upstash URL (may carry credentials).", "redis://localhost:6379"),
+	T("CACHE_REDIS_DRIVER", "cache", "public", "resp (ioredis TCP) | http (Upstash REST, edge).", "resp"),
+	T("CACHE_REDIS_TOKEN", "cache", "secret", "Upstash REST token (http driver)."),
+	T("CACHE_KEY_PREFIX", "cache", "public", "Cache key namespace.", "voltro:cache"),
+	T("REDIS_URL", "cache", "secret", "Generic Redis URL fallback (cache / ryw / ratelimit).", "redis://localhost:6379"),
+	T("VOLTRO_SESSION_SECRET", "security", "secret", "HMAC signing key for session cookies. REQUIRED in production."),
+	T("VOLTRO_INSPECT", "security", "public", "Set off to disable the /_voltro/inspect surface entirely.", "on"),
+	T("VOLTRO_INSPECT_TOKEN", "security", "secret", "Bearer token gating /_voltro/inspect/* on public deploys."),
+	T("VOLTRO_TENANT_ISOLATION", "security", "public", "shared-schema (default) | namespace (physical per-tenant)."),
+	T("FRAMEWORK_TRACING", "observability", "public", "off | console | otlp. Auto-otlp when OTEL_* is set."),
+	T("OTEL_EXPORTER_OTLP_ENDPOINT", "observability", "public", "OTLP/HTTP collector endpoint (traces + metrics).", "http://localhost:4318"),
+	T("OTEL_SERVICE_NAME", "observability", "public", "OTel service name.", "voltro-api"),
+	T("SSR_CACHE", "web", "public", "ISR cache backend for `voltro start`: memory | postgres.", "memory")
+], D = () => E.map((e) => e.key), O = (e) => {
 	let t = [];
 	e.description && t.push(`# ${e.description}`);
 	let n = [
@@ -155,17 +155,17 @@ var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
 	t.push(`# (${n})`);
 	let r = e.example ?? e.default ?? "";
 	return t.push(`${e.key}=${e.access === "secret" && !e.example ? "" : r}`), t.join("\n");
-}, T = (e, t = {}) => {
+}, k = (e, t = {}) => {
 	let n = [], r = t.header ?? ["Environment for this app — generated from app.config.ts `env` + plugin declarations.", "Regenerate with `voltro env sync`. Copy to `.env` and fill in the blanks."];
 	n.push(...r.map((e) => `# ${e}`), "");
 	let i = e.filter((e) => e.owner === "app"), a = e.filter((e) => e.owner.startsWith("plugin:"));
-	if (i.length > 0 && (n.push("# ── App ──────────────────────────────────────────────", ""), n.push(...i.map(w).flatMap((e) => [e, ""]))), a.length > 0 && (n.push("# ── Plugins ──────────────────────────────────────────", ""), n.push(...a.map(w).flatMap((e) => [e, ""]))), t.includeFramework !== !1) {
-		let e = [...new Set(S.map((e) => e.group))];
+	if (i.length > 0 && (n.push("# ── App ──────────────────────────────────────────────", ""), n.push(...i.map(O).flatMap((e) => [e, ""]))), a.length > 0 && (n.push("# ── Plugins ──────────────────────────────────────────", ""), n.push(...a.map(O).flatMap((e) => [e, ""]))), t.includeFramework !== !1) {
+		let e = [...new Set(E.map((e) => e.group))];
 		n.push("# ── Framework ────────────────────────────────────────", "");
-		for (let t of e) n.push(`# [${t}]`), n.push(...S.filter((e) => e.group === t).map(w).flatMap((e) => [e, ""]));
+		for (let t of e) n.push(`# [${t}]`), n.push(...E.filter((e) => e.group === t).map(O).flatMap((e) => [e, ""]));
 	}
 	return n.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
-}, E = (e) => {
+}, A = (e) => {
 	let t = new Set(e.map((e) => e.name));
 	return {
 		declared: e,
@@ -176,4 +176,4 @@ var c = "VOLTRO_PUBLIC_", l = (e, t) => Object.freeze({
 	};
 };
 //#endregion
-export { c as DEFAULT_PUBLIC_PREFIX, S as FRAMEWORK_ENV_CATALOG, y as appEnvEntries, _ as checkEnvNaming, l as defineEnv, m as envVar, v as formatEnvErrors, C as frameworkEnvNames, i as hasEnvSnapshot, n as installEnvSnapshot, u as isEnvContract, E as pluginEnv, b as pluginEnvEntries, r as readEnvValue, T as renderDotEnvExample, t as requireEnvValue, e as resetEnvSnapshot, g as resolveEnv };
+export { f as DEFAULT_PUBLIC_PREFIX, E as FRAMEWORK_ENV_CATALOG, C as appEnvEntries, x as checkEnvNaming, p as defineEnv, v as envVar, S as formatEnvErrors, D as frameworkEnvNames, c as hasEnvSnapshot, i as hasLiveOverlap, o as installEnvSnapshot, m as isEnvContract, A as pluginEnv, w as pluginEnvEntries, n as readEnvValue, e as readEnvValuePrevious, a as refreshEnvValue, k as renderDotEnvExample, s as requireEnvValue, t as resetEnvSnapshot, b as resolveEnv, r as setEnvClock };

package/dist/server.d.ts

@@ -10,6 +10,19 @@
  */
 export declare const getSecret: (key: string) => string | undefined;
 
+/**
+ * Read a secret together with its previous value during a rotation overlap.
+ *
+ * `current` is what everything else now sees; `previous` is present only while
+ * a `rotateSecretLive` grace window is open (then `undefined` — revoked). A
+ * verifier tries `current` first and falls back to `previous`, exactly like
+ * session verification honoring `VOLTRO_SESSION_SECRET` + `_PREVIOUS`.
+ */
+export declare const getSecretWithOverlap: (key: string) => {
+    readonly current: string | undefined;
+    readonly previous: string | undefined;
+};
+
 /**
  * Resolve a secret LIVE through the configured backend (Vault / Doppler / http
  * / env), bypassing the boot snapshot. Use this only when you genuinely need a
@@ -18,6 +31,47 @@ export declare const getSecret: (key: string) => string | undefined;
  */
 export declare const resolveSecretLive: (key: string) => Promise<string | undefined>;
 
+/**
+ * The blessed live-rotation flow: re-resolve `key` through the configured
+ * backend, install the NEW value over the boot snapshot so a running process
+ * serves it immediately, and hold the OLD value for `graceMs` so work
+ * created just before the rotation still verifies during cutover.
+ *
+ * This is the "set new → overlap → revoke" runbook made mechanical: after
+ * `graceMs` the previous value is revoked automatically (pruned on read — no
+ * timer, no dev/serve boot wiring), so an operator drives only the ONE call and
+ * the grace duration, not a sequence of manual `.env` edits. Reads through
+ * `getSecret` / `serverEnv` see the new value at once; a verifier that must
+ * accept both during cutover reads `getSecretWithOverlap`.
+ *
+ * IMPORTANT — scope of "without a restart". This updates what CODE that reads a
+ * secret PER USE sees (an outbound API key, a webhook-signing secret, a
+ * field-encryption key). It does NOT re-establish a connection that captured the
+ * old value at construction — a live DB pool built with the old `DB_URL`
+ * password keeps that connection until it is rebuilt (still a restart, or a
+ * pool-level reconnect). Rotate connection credentials with that in mind.
+ *
+ * The default grace is 5 minutes — long enough for in-flight requests and
+ * short-TTL tokens to drain, short enough that a leaked value's window closes
+ * promptly. Pass `graceMs: 0` for a hard cutover with no overlap.
+ */
+export declare const rotateSecretLive: (key: string, options?: {
+    readonly graceMs?: number;
+}) => Promise<SecretRotation>;
+
+/** The outcome of a live rotation — what `getSecret` now returns and, while the
+ *  grace window is open, the value that still verifies during cutover. */
+export declare interface SecretRotation {
+    readonly key: string;
+    /** The freshly-resolved value now served by `getSecret` / `serverEnv`. */
+    readonly current: string | undefined;
+    /** The pre-rotation value, valid until `graceMs` elapses (`undefined` on a
+     *  hard cutover, or when there was no prior value). */
+    readonly previous: string | undefined;
+    /** The overlap window, in ms, during which `previous` still verifies. */
+    readonly graceMs: number;
+}
+
 /**
  * The typed server env accessor. The framework's codegen augments this
  * interface in a generated `.d.ts` so `serverEnv.MY_VAR` autocompletes to the

package/dist/server.js

@@ -1,12 +1,29 @@
-import { i as e, r as t } from "./snapshot-qX0GrQfx.js";
-import { resolveSecret as n } from "@voltro/runtime";
+import { a as e, i as t, o as n, s as r } from "./snapshot-DLnTMXyV.js";
+import { resolveSecret as i } from "@voltro/runtime";
 //#region src/server.ts
-var r = new Proxy({}, {
-	get: (t, n) => typeof n == "string" ? e(n) : void 0,
+var a = new Proxy({}, {
+	get: (e, t) => typeof t == "string" ? r(t) : void 0,
 	has: (e, n) => typeof n == "string" && t(n) !== void 0
-}), i = (t) => {
+}), o = (e) => {
+	let t = r(e);
+	return t === void 0 ? void 0 : String(t);
+}, s = (e) => i(e), c = async (e, r) => {
+	let a = r?.graceMs ?? 5 * 6e4, o = t(e), s = o === void 0 ? void 0 : String(o), c = await i(e);
+	return n(e, c, {
+		...s === void 0 ? {} : { previous: s },
+		graceMs: a
+	}), {
+		key: e,
+		current: c,
+		previous: s,
+		graceMs: a
+	};
+}, l = (t) => {
 	let n = e(t);
-	return n === void 0 ? void 0 : String(n);
-}, a = (e) => n(e);
+	return {
+		current: o(t),
+		previous: n === void 0 ? void 0 : String(n)
+	};
+};
 //#endregion
-export { i as getSecret, a as resolveSecretLive, r as serverEnv };
+export { o as getSecret, l as getSecretWithOverlap, s as resolveSecretLive, c as rotateSecretLive, a as serverEnv };

package/dist/snapshot-DLnTMXyV.js

@@ -0,0 +1,38 @@
+//#region src/snapshot.ts
+var e = null, t = null, n = () => Date.now(), r = (n) => {
+	e = Object.freeze({ ...n }), t = null;
+}, i = () => e !== null, a = (n) => {
+	let r = t?.get(n);
+	return r === void 0 ? e === null ? void 0 : e[n] : r.value;
+}, o = (n) => {
+	let r = t?.get(n);
+	if (r !== void 0) return r.value;
+	if (e === null) throw Error(`@voltro/env: read of "${n}" before the boot env gate ran. Env values are only available after the framework validates them at startup — read them inside a handler / loader / startup hook, not at module top-level.`);
+	return e[n];
+}, s = (r, i, a) => {
+	if (e === null) throw Error(`@voltro/env: refreshEnvValue("${r}") before the boot env gate ran. A live secret rotation is a post-boot operation — it replaces a value the boot gate already resolved.`);
+	t === null && (t = /* @__PURE__ */ new Map());
+	let o = a?.previous !== void 0 && a.graceMs !== void 0 && a.graceMs > 0;
+	t.set(r, {
+		value: i,
+		...o ? {
+			previous: a.previous,
+			previousExpiresAt: n() + a.graceMs
+		} : {}
+	});
+}, c = (e) => {
+	let r = t?.get(e);
+	if (!(r === void 0 || r.previousExpiresAt === void 0)) {
+		if (n() >= r.previousExpiresAt) {
+			t.set(e, { value: r.value });
+			return;
+		}
+		return r.previous;
+	}
+}, l = (e) => c(e) !== void 0, u = (e) => {
+	n = e;
+}, d = () => {
+	e = null, t = null, n = () => Date.now();
+};
+//#endregion
+export { c as a, d as c, a as i, u as l, l as n, s as o, r, o as s, i as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/env",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Typed, schema-validated environment variables with a structural public/secret boundary. Declare once in app.config.ts; read public vars in the browser, secrets only on the server.",
   "keywords": [
     "voltro",
@@ -42,7 +42,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/runtime": "0.28.0"
+    "@voltro/runtime": "0.30.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"

package/dist/snapshot-qX0GrQfx.js

@@ -1,11 +0,0 @@
-//#region src/snapshot.ts
-var e = null, t = (t) => {
-	e = Object.freeze({ ...t });
-}, n = () => e !== null, r = (t) => e === null ? void 0 : e[t], i = (t) => {
-	if (e === null) throw Error(`@voltro/env: read of "${t}" before the boot env gate ran. Env values are only available after the framework validates them at startup — read them inside a handler / loader / startup hook, not at module top-level.`);
-	return e[t];
-}, a = () => {
-	e = null;
-};
-//#endregion
-export { a, i, t as n, r, n as t };