@voltro/plugin-flags 0.32.0 → 0.34.0

package/dist/index.js

@@ -1,24 +1,25 @@
 import { evaluateDescriptor as e, evaluateVariantsDescriptor as t, flagsRpcClientImports as n } from "./rpc.js";
-import { FlagDisabled as r } from "./errors.js";
-import { Effect as i } from "effect";
-import { definePlugin as a } from "@voltro/protocol";
-import { boolean as o, id as s, integer as c, json as l, queryFor as u, table as d, text as f, timestamp as p } from "@voltro/database";
+import { i as r, n as i, r as a, t as o } from "./define-D9Eet7wA.js";
+import { FlagDisabled as s } from "./errors.js";
+import { Effect as c } from "effect";
+import { definePlugin as l, pluginInstanceName as u } from "@voltro/protocol";
+import { boolean as d, id as f, integer as p, json as m, queryFor as h, registerRetention as g, retentionTtlMsFromEnv as _, table as v, text as y, timestamp as b } from "@voltro/database";
 //#region src/evaluate.ts
-var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
+var x = (e) => typeof e == "boolean" ? { enabled: e } : e, S = (e, t) => {
 	let n = 2166136261, r = `${e}:${t}`;
 	for (let e = 0; e < r.length; e++) n ^= r.charCodeAt(e), n = Math.imul(n, 16777619);
 	return n >>> 0;
-}, g = (e, t) => h(e, t) % 100, _ = (e, t) => h(`${e}:variant`, t) % 1e4, v = (e, t) => {
+}, C = (e, t) => S(e, t) % 100, ee = (e, t) => S(`${e}:variant`, t) % 1e4, w = (e, t) => {
 	if (e.subjectIds && !(t.id != null && e.subjectIds.includes(t.id)) || e.tenantIds && !(t.tenantId != null && e.tenantIds.includes(t.tenantId)) || e.subjectTypes && !(t.type != null && e.subjectTypes.includes(t.type))) return !1;
 	if (e.metadata) {
 		let n = t.metadata ?? {};
 		for (let [t, r] of Object.entries(e.metadata)) if (String(n[t]) !== r) return !1;
 	}
 	return !0;
-}, y = (e) => typeof e == "number" ? e : Date.parse(e), b = (e, t) => (e.rolloutBy === "tenant" ? t.tenantId : t.id) ?? "anon", x = (e, t) => {
-	if (e.activateAt != null && t < y(e.activateAt) || e.deactivateAt != null && t >= y(e.deactivateAt)) return { active: !1 };
+}, T = (e) => typeof e == "number" ? e : Date.parse(e), E = (e, t) => (e.rolloutBy === "tenant" ? t.tenantId : t.id) ?? "anon", D = (e, t) => {
+	if (e.activateAt != null && t < T(e.activateAt) || e.deactivateAt != null && t >= T(e.deactivateAt)) return { active: !1 };
 	if (e.ramp) {
-		let { from: n, to: r, startAt: i, endAt: a } = e.ramp, o = y(i), s = y(a);
+		let { from: n, to: r, startAt: i, endAt: a } = e.ramp, o = T(i), s = T(a);
 		if (t <= o) return {
 			active: !0,
 			rollout: n
@@ -34,71 +35,71 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 		};
 	}
 	return { active: !0 };
-}, S = (e, t, n, r = Date.now()) => {
-	let i = m(t);
+}, O = (e, t, n, r = Date.now()) => {
+	let i = x(t);
 	if (i.enabled === !1) return !1;
 	let a;
 	if (i.schedule) {
-		let e = x(i.schedule, r);
+		let e = D(i.schedule, r);
 		if (!e.active) return !1;
 		a = e.rollout;
 	}
-	if (i.targeting && i.targeting.length > 0 && !i.targeting.some((e) => v(e, n))) return !1;
+	if (i.targeting && i.targeting.length > 0 && !i.targeting.some((e) => w(e, n))) return !1;
 	let o = a ?? i.rollout ?? 100;
 	if (o < 100 && o > 0) {
-		if (!(g(e, b(i, n)) < o)) return !1;
+		if (!(C(e, E(i, n)) < o)) return !1;
 	} else if (o <= 0) return !1;
-	return i.variants && i.variants.length > 0 && i.offVariant != null ? w(e, i, n).name !== i.offVariant : !0;
-}, C = (e) => {
+	return i.variants && i.variants.length > 0 && i.offVariant != null ? k(e, i, n).name !== i.offVariant : !0;
+}, te = (e) => {
 	let t = e.reduce((e, t) => e + (t.weight ?? 1), 0) || e.length, n = 0;
 	return e.map((r, i) => (n += r.weight ?? 1, i === e.length - 1 ? 1e4 : Math.round(n / t * 1e4)));
-}, w = (e, t, n) => {
+}, k = (e, t, n) => {
 	let r = t.variants ?? [];
 	if (r.length === 0) throw Error(`flag "${e}" has no variants`);
-	let i = _(e, b(t, n)), a = C(r);
+	let i = ee(e, E(t, n)), a = te(r);
 	for (let e = 0; e < r.length; e++) if (i < a[e]) return r[e];
 	return r[r.length - 1];
-}, T = (e, t, n, r = Date.now()) => {
-	let i = m(t), a = S(e, t, n, r);
+}, A = (e, t, n, r = Date.now()) => {
+	let i = x(t), a = O(e, t, n, r);
 	if (!i.variants || i.variants.length === 0) return {
 		name: a ? "on" : "off",
 		value: a,
 		enabled: a
 	};
-	let o = w(e, i, n);
+	let o = k(e, i, n);
 	return {
 		name: o.name,
 		value: o.value,
 		enabled: a
 	};
-}, E = (e, t, n = Date.now()) => {
+}, ne = (e, t, n = Date.now()) => {
 	let r = {};
-	for (let [i, a] of Object.entries(e)) r[i] = S(i, a, t, n);
+	for (let [i, a] of Object.entries(e)) r[i] = O(i, a, t, n);
 	return r;
-}, D = (e, t, n = Date.now()) => {
+}, re = (e, t, n = Date.now()) => {
 	let r = {};
-	for (let [i, a] of Object.entries(e)) r[i] = T(i, a, t, n);
+	for (let [i, a] of Object.entries(e)) r[i] = A(i, a, t, n);
 	return r;
-}, O = "_voltro_feature_flag_audit", k = "_voltro_feature_flags", A = d(k, {
-	id: s({ prefix: "flag" }),
-	key: f().unique(),
-	enabled: o().default(!0),
-	rollout: c().nullable(),
-	rolloutBy: f().nullable(),
-	targeting: l().nullable(),
-	variants: l().nullable(),
-	offVariant: f().nullable(),
-	schedule: l().nullable(),
-	description: f().nullable(),
-	updatedAt: p().default("now").onUpdate("now")
-}), j = d(O, {
-	id: s({ prefix: "flagaud" }),
-	flag: f(),
-	enabled: o(),
-	previousEnabled: o().nullable(),
-	actorId: f().nullable(),
-	at: p().default("now")
-}).index("byFlagAuditFlag", ["flag"]).index("byFlagAuditAt", ["at"]), M = (e, t) => {
+}, j = "_voltro_feature_flag_audit", M = "_voltro_feature_flags", N = v(M, {
+	id: f({ prefix: "flag" }),
+	key: y().unique(),
+	enabled: d().default(!0),
+	rollout: p().nullable(),
+	rolloutBy: y().nullable(),
+	targeting: m().nullable(),
+	variants: m().nullable(),
+	offVariant: y().nullable(),
+	schedule: m().nullable(),
+	description: y().nullable(),
+	updatedAt: b().default("now").onUpdate("now")
+}), P = v(j, {
+	id: f({ prefix: "flagaud" }),
+	flag: y(),
+	enabled: d(),
+	previousEnabled: d().nullable(),
+	actorId: y().nullable(),
+	at: b().default("now")
+}).index("byFlagAuditFlag", ["flag"]).index("byFlagAuditAt", ["at"]), F = (e, t) => {
 	let n = { ...e };
 	for (let e of t) {
 		let t = {
@@ -114,7 +115,7 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 		n[e.key] = t;
 	}
 	return n;
-}, N = new class {
+}, I = new class {
 	flags = {};
 	set(e) {
 		this.flags = e;
@@ -125,19 +126,19 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 	get(e) {
 		return this.flags[e];
 	}
-}(), P = (e, t) => F(e, t) !== null, F = (e, t) => {
-	let n = N.get(e);
+}(), L = (e, t) => R(e, t) !== null, R = (e, t) => {
+	let n = I.get(e);
 	if (n === void 0) return null;
-	let r = m(n), i = r.enabled !== !1;
-	return N.set({
-		...N.all(),
+	let r = x(n), i = r.enabled !== !1;
+	return I.set({
+		...I.all(),
 		[e]: {
 			...r,
 			enabled: t
 		}
 	}), i;
-}, I = (e) => Object.entries(e).map(([e, t]) => {
-	let n = m(t);
+}, z = (e) => Object.entries(e).map(([e, t]) => {
+	let n = x(t);
 	return {
 		key: e,
 		enabled: n.enabled !== !1,
@@ -146,8 +147,8 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 		scheduled: n.schedule != null,
 		description: n.description
 	};
-}), L = (e, t) => {
-	let n = m(t);
+}), ie = (e, t) => {
+	let n = x(t);
 	return {
 		key: e,
 		enabled: n.enabled !== !1,
@@ -159,8 +160,8 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 		schedule: n.schedule ?? null,
 		description: n.description ?? null
 	};
-}, R = (e) => ({
-	loadOverrides: async () => (await e.query(u(A).descriptor)).map((e) => ({
+}, ae = (e) => ({
+	loadOverrides: async () => (await e.query(h(N).descriptor)).map((e) => ({
 		key: String(e.key),
 		enabled: e.enabled === !0 || e.enabled === 1,
 		rollout: e.rollout == null ? null : Number(e.rollout),
@@ -185,17 +186,17 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 			description: t.description,
 			updatedAt: /* @__PURE__ */ new Date()
 		};
-		await e.upsert(k, n, { conflictColumns: ["key"] });
+		await e.upsert(M, n, { conflictColumns: ["key"] });
 	}
-}), z = (e) => ({
+}), oe = (e) => ({
 	flag: String(e.flag),
 	enabled: e.enabled === !0 || e.enabled === 1,
 	previousEnabled: e.previousEnabled == null ? null : e.previousEnabled === !0 || e.previousEnabled === 1,
 	actorId: e.actorId ?? null,
 	at: e.at instanceof Date ? e.at : new Date(String(e.at))
-}), B = (e) => ({
+}), se = (e) => ({
 	record: async (t) => {
-		await e.insert(O, {
+		await e.insert(j, {
 			id: `flagaud_${t.at.getTime()}_${Math.random().toString(36).slice(2, 10)}`,
 			flag: t.flag,
 			enabled: t.enabled,
@@ -205,69 +206,369 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 		});
 	},
 	list: async (t) => {
-		let n = u(j).orderBy("at", "desc");
+		let n = h(P).orderBy("at", "desc");
 		t?.limit != null && (n = n.limit(t.limit));
-		let r = (await e.query(n.descriptor)).map(z);
+		let r = (await e.query(n.descriptor)).map(oe);
 		return t?.flag == null ? r : r.filter((e) => e.flag === t.flag);
 	}
-}), V = (e) => "request" in e && e.request?.subject || "subject" in e && e.subject || {}, H = (e, t) => {
-	let n = N.get(t);
-	return n !== void 0 && S(t, n, V(e));
-}, U = (e, t) => H(e, t) ? i.void : i.fail(new r({ flag: t })), W = (e, t) => e === t || e.startsWith("/") && e.endsWith("/") && new RegExp(e.slice(1, -1)).test(t), G = (o = {}) => {
-	let s = { ...o.flags ?? {} }, c = o.gatedBy ?? {}, l = o.name ? `@voltro/plugin-flags#${o.name}` : "@voltro/plugin-flags", u = o.store === "postgres", d, f, p = async () => {
-		d && N.set(M(s, await d.loadOverrides()));
-	}, m = (e) => {
-		if (c[e] !== void 0) return c[e];
-		for (let [t, n] of Object.entries(c)) if (t !== e && W(t, e)) return n;
-	}, h = (e, t) => {
-		let n = m(t.tag);
-		return n === void 0 || H({ subject: t.subject }, n) ? e : i.fail(new r({ flag: n }));
-	}, g = Object.keys(c).length > 0, _ = {
+}), B = (e, t) => {
+	let n = new Map(t.map((e) => [e.name, e])), r = [];
+	for (let t of e) {
+		let e = t.experiment;
+		if (e === void 0) continue;
+		let i = n.get(e);
+		if (i === void 0) {
+			r.push({
+				flag: t.key,
+				experiment: e,
+				problem: `no experiment named ${JSON.stringify(e)} was passed to flagsPlugin({ experiments }). Pass the defineExperiment() definitions the app declares, or drop the \`experiment\` link.`
+			});
+			continue;
+		}
+		(i.variantFrom === void 0 || i.variantFrom === null) && r.push({
+			flag: t.key,
+			experiment: e,
+			problem: `the experiment assigns its own arms (\`subject\` mode), so it would measure a split this flag never served — the two bucketings are independent hashes. Persist the served arm (\`flagVariant(ctx, ${JSON.stringify(t.key)})\`) on the watched table and declare the experiment with \`variantFrom: <that column>\`.`
+		}), typeof i.holdout == "number" && i.holdout > 0 && r.push({
+			flag: t.key,
+			experiment: e,
+			problem: `holdout ${i.holdout} is carved at ASSIGNMENT, and this flag does the assigning — the experiment can never place a row there. Declare the holdout as a flag variant instead.`
+		});
+		let a = new Set(t.variants.map((e) => e.name)), o = new Set(i.variants.map((e) => e.name));
+		if (a.size === 0) r.push({
+			flag: t.key,
+			experiment: e,
+			problem: "the flag declares no variants, so it serves one value to everyone and there is nothing to compare."
+		});
+		else {
+			let n = [...a].filter((e) => !o.has(e)), i = [...o].filter((e) => !a.has(e));
+			(n.length > 0 || i.length > 0) && r.push({
+				flag: t.key,
+				experiment: e,
+				problem: `the arms disagree — ${n.length > 0 ? `served by the flag but not declared by the experiment: ${n.join(", ")}` : ""}${n.length > 0 && i.length > 0 ? "; " : ""}${i.length > 0 ? `declared by the experiment but never served: ${i.join(", ")}` : ""}. A row assigned to an arm the experiment does not declare is EXCLUDED, so the mismatch shows up as an empty arm rather than an error.`
+			});
+		}
+	}
+	return r;
+}, V = (e, t) => {
+	let n = B(e, t);
+	if (n.length === 0) return;
+	let r = n.map((e) => `  · flag "${e.flag}" → experiment "${e.experiment}": ${e.problem}`);
+	throw Error(`@voltro/plugin-flags: ${n.length} flag→experiment link problem(s):\n${r.join("\n")}`);
+}, H = 864e5, U = (e) => typeof e == "number" ? e : Date.parse(e), W = (e, t) => {
+	let n = x(e);
+	if (n.enabled === !1) return {
+		shape: "constantOff",
+		reason: "enabled: false — resolves false for every caller"
+	};
+	if (n.schedule) {
+		let { activateAt: e, deactivateAt: r } = n.schedule;
+		if (r != null && t >= U(r)) return {
+			shape: "expired",
+			reason: `schedule.deactivateAt (${String(r)}) has passed — the flag can never be on again`
+		};
+		if (e != null && t < U(e)) return {
+			shape: "notYetActive",
+			reason: `schedule.activateAt (${String(e)}) is in the future — pending, not dead`
+		};
+	}
+	let r = n.rollout ?? 100;
+	if (r <= 0) return {
+		shape: "constantOff",
+		reason: `rollout: ${r} — nobody is in the rollout`
+	};
+	let i = (n.targeting?.length ?? 0) > 0, a = (n.variants?.length ?? 0) > 1, o = n.schedule !== void 0 && (n.schedule.ramp !== void 0 || n.schedule.deactivateAt != null && t < U(n.schedule.deactivateAt));
+	return r >= 100 && !i && !a && !o ? {
+		shape: "constantOn",
+		reason: "rollout 100 with no targeting, no variants and no live schedule — resolves true for every caller"
+	} : {
+		shape: "conditional",
+		reason: `still selects between callers (${[
+			r < 100 ? `rollout ${r}%` : void 0,
+			i ? `${n.targeting?.length} targeting rule(s)` : void 0,
+			a ? `${n.variants?.length} variants` : void 0,
+			o ? "a live schedule" : void 0
+		].filter((e) => e !== void 0).join(", ")})`
+	};
+}, G = [
+	"Reachability is not decided. \"Not evaluated since <date>\" is a measurement; \"this code path is dead\" is not decidable in general. A seasonal flag, a flag behind a route nobody visited this month, and a flag whose last call site was deleted are indistinguishable from here.",
+	"Only SERVER-side reads are counted as use: isFlagEnabled / requireFlag / flagValue and a gatedBy interception. A flag consulted only in the browser via useFlag() / useFlagValue() reads from the bulk set the server already sent, so it never reaches this report as a named read.",
+	"A \"bulk\" observation means the flag was INCLUDED in a flags.evaluate / flags.variants response. It does not mean any client read that key — one useFlags() poll evaluates the whole registry.",
+	"The window is bounded by retention (see coverage.retentionDays). Nothing older is evidence: a flag last read BEFORE the window has no observation at all and reads \"neverObserved\", which is exactly what a flag declared this morning reads.",
+	"\"neverObserved\" is not a removal candidate. A flag declared yesterday and a flag abandoned last year produce the identical row; only a flag that WAS observed and then stopped (\"stale\") is proven unused."
+], K = (e) => {
+	let t = e.now ?? Date.now(), n = e.staleAfterDays, r = t - n * H, i = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map(), o;
+	for (let t of e.usage) {
+		let e = t.lastAt.getTime();
+		if (!Number.isFinite(e)) continue;
+		(o === void 0 || e < o) && (o = e);
+		let n = t.source === "bulk" ? a : i, r = n.get(t.flag);
+		(r === void 0 || e > r) && n.set(t.flag, e);
+	}
+	let s = o === void 0 ? 0 : Math.floor((t - o) / H);
+	return {
+		coverage: {
+			tracking: e.tracking,
+			observedSince: o === void 0 ? null : new Date(o).toISOString().slice(0, 10),
+			observedDays: s,
+			retentionDays: e.retentionDays,
+			staleAfterDays: n
+		},
+		findings: Object.entries(e.flags).map(([o, c]) => {
+			let { shape: l, reason: u } = W(c, t), d = i.get(o), f = a.get(o), p = [u], m;
+			e.tracking ? d !== void 0 && d >= r ? (m = "evaluated", p.push(`last server-side read ${new Date(d).toISOString()}`)) : d === void 0 ? (m = "neverObserved", p.push(s > 0 ? `no server-side read in the ${s}-day observation window` : "no server-side read observed yet (the observation window is empty)"), f !== void 0 && p.push("the flag WAS delivered to a client in a bulk flags.evaluate response — which does not prove it was read")) : (m = "stale", p.push(`last server-side read ${new Date(d).toISOString()}, more than ${n} day(s) ago, over an observation window of ${s} day(s)`)) : (m = "untracked", p.push("evaluation tracking is off — no usage evidence exists for this deployment"));
+			let h = l === "constantOn" || l === "constantOff" || l === "expired";
+			return h && p.push("the definition alone makes this flag a constant — it selects nothing"), {
+				key: o,
+				shape: l,
+				shapeReason: u,
+				usage: m,
+				lastTargetedAt: d === void 0 ? null : new Date(d).toISOString(),
+				lastBulkAt: f === void 0 ? null : new Date(f).toISOString(),
+				liveTargetedEvaluations: e.liveCounts?.get(o) ?? 0,
+				removalCandidate: h || m === "stale",
+				why: p
+			};
+		}),
+		limits: G
+	};
+}, q = "_voltro_feature_flag_usage", J = v(q, {
+	id: f({ prefix: "flagusg" }),
+	flag: y(),
+	day: y(),
+	source: y(),
+	lastAt: b()
+}).unique([
+	"flag",
+	"day",
+	"source"
+]).index("byFlagUsageLastAt", ["lastAt"]).index("byFlagUsageFlag", ["flag"]), ce = (e) => e.toISOString().slice(0, 10), le = (e) => {
+	let t = 2166136261;
+	for (let n = 0; n < e.length; n++) t ^= e.charCodeAt(n), t = Math.imul(t, 16777619);
+	return (t >>> 0).toString(16).padStart(8, "0");
+}, ue = (e, t, n) => `flagusg_${t.replace(/-/g, "")}_${n === "targeted" ? "t" : "b"}_${le(e)}`, Y = new class {
+	on = !1;
+	pending = /* @__PURE__ */ new Map();
+	liveCounts = /* @__PURE__ */ new Map();
+	enable() {
+		this.on = !0;
+	}
+	disable() {
+		this.on = !1, this.pending.clear();
+	}
+	get enabled() {
+		return this.on;
+	}
+	record(e, t, n = Date.now()) {
+		if (!this.on) return;
+		let r = `${t}\u0000${e}`, i = this.pending.get(r);
+		i ? i.lastAt = n : this.pending.set(r, {
+			flag: e,
+			source: t,
+			lastAt: n
+		}), t === "targeted" && this.liveCounts.set(e, (this.liveCounts.get(e) ?? 0) + 1);
+	}
+	drain() {
+		let e = [...this.pending.values()];
+		return this.pending.clear(), e;
+	}
+	restore(e) {
+		if (this.on) for (let t of e) {
+			let e = `${t.source}\u0000${t.flag}`, n = this.pending.get(e);
+			(!n || n.lastAt < t.lastAt) && this.pending.set(e, { ...t });
+		}
+	}
+	liveTargetedCounts() {
+		return this.liveCounts;
+	}
+	reset() {
+		this.on = !1, this.pending.clear(), this.liveCounts.clear();
+	}
+}(), X = (e, t, n) => Y.record(e, t, n), de = (e) => e === "bulk" ? "bulk" : "targeted", fe = (e) => ({
+	upsertMany: async (t) => {
+		for (let n of t) {
+			let t = ce(n.lastAt);
+			await e.upsert(q, {
+				id: ue(n.flag, t, n.source),
+				flag: n.flag,
+				day: t,
+				source: n.source,
+				lastAt: n.lastAt
+			}, { conflictColumns: [
+				"flag",
+				"day",
+				"source"
+			] });
+		}
+	},
+	load: async () => (await e.query(h(J).descriptor)).map((e) => ({
+		flag: String(e.flag),
+		day: String(e.day),
+		source: de(e.source),
+		lastAt: e.lastAt instanceof Date ? e.lastAt : new Date(String(e.lastAt))
+	}))
+}), pe = 3e5, me = (e) => {
+	let t = e.intervalMs ?? 3e5, n = !1, r = async () => {
+		let t = Y.drain();
+		if (t.length !== 0) try {
+			await e.store.upsertMany(t.map((e) => ({
+				flag: e.flag,
+				source: e.source,
+				lastAt: new Date(e.lastAt)
+			})));
+		} catch (n) {
+			Y.restore(t), e.log?.warn?.("flag usage flush failed — observations retained for the next pass", {
+				pending: t.length,
+				cause: n.message
+			});
+		}
+	}, i = setInterval(() => {
+		r();
+	}, t);
+	return typeof i.unref == "function" && i.unref(), {
+		flushNow: r,
+		stop: async () => {
+			n || (n = !0, clearInterval(i), await r());
+		}
+	};
+}, he = (e = process.env, t = 90) => {
+	let n = _(e.VOLTRO_FLAG_USAGE_TTL_HOURS, 24 * t);
+	return g({
+		table: q,
+		timeColumn: "lastAt",
+		source: "plugin",
+		ttlMs: n,
+		envVar: "VOLTRO_FLAG_USAGE_TTL_HOURS"
+	}), n;
+}, Z = (e) => "request" in e && e.request?.subject || "subject" in e && e.subject || {}, Q = (e, t) => {
+	let n = I.get(t);
+	return X(t, "targeted"), n !== void 0 && O(t, n, Z(e));
+}, ge = (e, t) => Q(e, t) ? c.void : c.fail(new s({ flag: t })), _e = (e, t) => {
+	let n = I.get(t.key);
+	return X(t.key, "targeted"), n === void 0 ? t.defaultValue : r(t, A(t.key, n, Z(e)));
+}, ve = (e, t) => {
+	let n = I.get(t.key);
+	return X(t.key, "targeted"), n === void 0 ? null : A(t.key, n, Z(e)).name;
+}, ye = (e, t) => e === t || e.startsWith("/") && e.endsWith("/") && new RegExp(e.slice(1, -1)).test(t), $ = "@voltro/plugin-flags", be = (r = {}) => {
+	let a = r.gatedBy ?? {}, o = u({
+		base: $,
+		alias: r.alias,
+		instance: r.name
+	}), d = r.typedFlags ?? [], f = /* @__PURE__ */ new Map();
+	for (let e of d) {
+		if (f.has(e.key)) throw Error(`${$}: two typedFlags declare the key ${JSON.stringify(e.key)}`);
+		if (r.flags?.[e.key] !== void 0) throw Error(`${$}: ${JSON.stringify(e.key)} is declared BOTH in \`flags\` and in \`typedFlags\`. One key, one declaration — the typed one would otherwise be silently overwritten by the untyped baseline.`);
+		f.set(e.key, e);
+	}
+	d.some((e) => e.experiment !== void 0) && V(d, r.experiments ?? []);
+	let p = { ...r.flags ?? {} };
+	for (let e of d) p[e.key] = e.definition;
+	let m = r.store === "postgres", h, g, _, v, y = [], b = r.usage ?? {}, x = b.track ?? m;
+	if (x && !m) throw Error(`${$}: usage.track requires store: 'postgres' — there is nowhere to record an evaluation on the memory tier, and a dead-flag report that silently observed nothing is exactly the defect it exists to find.`);
+	let S = b.staleAfterDays ?? 30, C = b.retentionDays ?? 90;
+	if (S > C) throw Error(`${$}: usage.staleAfterDays (${S}) exceeds usage.retentionDays (${C}), so the observation window can never be long enough to prove a flag stale and every verdict would be withheld.`);
+	let ee = (e) => {
+		let t = F(p, e), n = [];
+		for (let [e, r] of f) {
+			let a = t[e];
+			if (a === void 0) continue;
+			let o = i(r, typeof a == "boolean" ? { enabled: a } : a);
+			o.ok || (n.push(o.refusal), t[e] = r.definition);
+		}
+		y = n, I.set(t);
+	}, w = async () => {
+		h && ee(await h.loadOverrides());
+	}, T = (e) => {
+		if (a[e] !== void 0) return a[e];
+		for (let [t, n] of Object.entries(a)) if (t !== e && ye(t, e)) return n;
+	}, E = (e, t) => {
+		let n = T(t.tag);
+		return n === void 0 || Q({ subject: t.subject }, n) ? e : c.fail(new s({ flag: n }));
+	}, D = Object.keys(a).length > 0, O = (e) => {
+		for (let t of e) X(t, "bulk");
+	}, te = {
 		...e,
 		description: "Resolve every feature flag for the calling subject.",
-		execute: (e, t) => i.succeed(E(N.all(), t.request.subject ?? {}))
-	}, v = {
+		execute: (e, t) => c.sync(() => {
+			let e = I.all();
+			return O(Object.keys(e)), ne(e, t.request.subject ?? {});
+		})
+	}, k = {
 		...t,
 		description: "Resolve every feature flag to its served variant for the calling subject.",
-		execute: (e, t) => i.succeed(D(N.all(), t.request.subject ?? {}))
-	}, y = (e) => ({
+		execute: (e, t) => c.sync(() => {
+			let e = I.all();
+			return O(Object.keys(e)), re(e, t.request.subject ?? {});
+		})
+	}, A = (e) => ({
 		kind: "json",
 		data: e
-	}), b = (e, t) => ({
+	}), j = (e, t) => ({
 		kind: "json",
 		status: e,
 		data: { error: t }
-	}), x = [
+	}), M = async () => {
+		let e = [];
+		if (x && _) try {
+			e = await _.load();
+		} catch {
+			e = [];
+		}
+		return K({
+			flags: I.all(),
+			usage: e,
+			tracking: x,
+			liveCounts: Y.liveTargetedCounts(),
+			staleAfterDays: S,
+			retentionDays: C
+		});
+	}, L = () => {
+		let e = {};
+		for (let [t, n] of f) e[t] = {
+			valueType: n.valueType,
+			variants: n.variants.map((e) => e.name),
+			experiment: n.experiment ?? null
+		};
+		return e;
+	}, oe = [
 		{
 			method: "GET",
 			path: "/list",
-			description: "Every resolved flag (key, enabled, rollout, description).",
-			handler: () => i.succeed(y({ flags: I(N.all()) }))
+			description: "Every resolved flag (key, enabled, rollout, description) plus the dead-flag lifecycle report: per-flag shape + usage verdict, the observation coverage window, and the limits of what the report can prove.",
+			handler: () => c.promise(async () => {
+				let e = await M();
+				return A({
+					flags: z(I.all()),
+					lifecycle: e,
+					typed: L(),
+					overrideRefusals: y
+				});
+			})
 		},
 		{
 			method: "POST",
 			path: "/toggle",
 			description: "Flip a flag's kill-switch on/off (live registry; durable on the postgres tier). Logs an audit row.",
-			handler: (e) => i.gen(function* () {
+			handler: (e) => c.gen(function* () {
 				let t;
 				try {
 					t = JSON.parse(e.body || "{}");
 				} catch {
-					return b(400, "invalid JSON body");
+					return j(400, "invalid JSON body");
 				}
-				if (!t.key || typeof t.enabled != "boolean") return b(400, "key (string) + enabled (boolean) required");
-				let n = F(t.key, t.enabled);
-				if (n === null) return b(404, `unknown flag "${t.key}"`);
-				let r = d ? N.get(t.key) : void 0;
-				return d && r !== void 0 && (yield* i.promise(() => d.upsertOverride(L(t.key, r)))), f && (yield* i.promise(() => f.record({
+				if (!t.key || typeof t.enabled != "boolean") return j(400, "key (string) + enabled (boolean) required");
+				let n = R(t.key, t.enabled);
+				if (n === null) return j(404, `unknown flag "${t.key}"`);
+				let r = h ? I.get(t.key) : void 0;
+				return h && r !== void 0 && (yield* c.promise(() => h.upsertOverride(ie(t.key, r)))), g && (yield* c.promise(() => g.record({
 					flag: t.key,
 					enabled: t.enabled,
 					previousEnabled: n,
 					actorId: typeof t.actor == "string" ? t.actor : null,
 					at: /* @__PURE__ */ new Date()
-				}))), y({
+				}))), A({
 					ok: !0,
-					flags: I(N.all())
+					flags: z(I.all())
 				});
 			})
 		},
@@ -275,16 +576,16 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 			method: "GET",
 			path: "/audit",
 			description: "The kill-switch flip audit trail, newest-first. `?flag=<key>` filters; `?limit=<n>` caps (postgres tier only).",
-			handler: (e) => i.gen(function* () {
-				if (!f) return y({
+			handler: (e) => c.gen(function* () {
+				if (!g) return A({
 					audit: [],
 					note: "audit trail requires store: \"postgres\""
 				});
-				let t = new URL(e.url, "http://local"), n = t.searchParams.get("flag"), r = t.searchParams.get("limit"), a = r != null && Number.isFinite(Number(r)) ? Number(r) : 100, o = yield* i.promise(() => f.list({
+				let t = new URL(e.url, "http://local"), n = t.searchParams.get("flag"), r = t.searchParams.get("limit"), i = r != null && Number.isFinite(Number(r)) ? Number(r) : 100, a = yield* c.promise(() => g.list({
 					...n == null ? {} : { flag: n },
-					limit: a
+					limit: i
 				}));
-				return y({ audit: o.map((e) => ({
+				return A({ audit: a.map((e) => ({
 					flag: e.flag,
 					enabled: e.enabled,
 					previousEnabled: e.previousEnabled,
@@ -294,48 +595,68 @@ var m = (e) => typeof e == "boolean" ? { enabled: e } : e, h = (e, t) => {
 			})
 		}
 	];
-	return a({
-		name: l,
+	return l({
+		name: o,
+		baseName: $,
 		description: "Feature flags — targeting, % rollout, kill-switch, declarative gating + client evaluation.",
 		permissions: [
-			...g ? [
+			...D ? [
 				"rpc:intercept:mutation",
 				"rpc:intercept:query",
 				"rpc:intercept:action"
 			] : [],
-			...u ? ["store:write", "store:changes:read"] : [],
+			...m ? ["store:write", "store:changes:read"] : [],
 			"inspect:read",
 			"inspect:write"
 		],
-		routes: [_, v],
+		routes: [te, k],
 		rpcClientDescriptors: n,
-		inspectEndpoints: x,
+		inspectEndpoints: oe,
 		errorSchemas: [{
-			schema: r,
+			schema: s,
 			import: {
 				module: "@voltro/plugin-flags/errors",
 				name: "FlagDisabled"
 			}
 		}],
-		...g ? {
-			interceptMutation: h,
-			interceptQuery: h,
-			interceptAction: h
+		...D ? {
+			interceptMutation: E,
+			interceptQuery: E,
+			interceptAction: E
 		} : {},
-		...u ? { extendSchema: { tables: [A, j] } } : {},
-		...u ? { bindDataStore: (e) => {
-			d = R(e), f = B(e);
+		...m ? { extendSchema: { tables: x ? [
+			N,
+			P,
+			J
+		] : [N, P] } } : {},
+		...m ? { bindDataStore: (e) => {
+			h = ae(e), g = se(e), x && (_ = fe(e));
 		} } : {},
-		...u ? { onChangeEvent: (e) => e.table === "_voltro_feature_flags" ? i.tryPromise(() => p()) : i.void } : {},
-		onActivate: (e) => i.gen(function* () {
-			N.set(s), u && d && (yield* i.promise(p)), e.logger.info("feature flags active", {
-				count: Object.keys(s).length,
-				gated: Object.keys(c).length,
-				store: o.store ?? "memory"
+		...m ? { onChangeEvent: (e) => e.table === "_voltro_feature_flags" ? c.tryPromise(() => w()) : c.void } : {},
+		onActivate: (e) => c.gen(function* () {
+			I.set(p), m && h && (yield* c.promise(w));
+			let t;
+			x && _ && (t = he(process.env, C), Y.enable(), v = me({
+				store: _,
+				intervalMs: b.flushIntervalMs ?? 3e5,
+				log: { warn: (t, n) => e.logger.warn(t, n) }
+			}));
+			for (let t of y) e.logger.warn("feature flag override REFUSED — the code-declared definition stands", {
+				flag: t.key,
+				reason: t.reason
+			});
+			e.logger.info("feature flags active", {
+				count: Object.keys(p).length,
+				typed: f.size,
+				gated: Object.keys(a).length,
+				store: r.store ?? "memory",
+				usage: x ? `tracking (stale after ${S}d, observations kept ${Math.round((t ?? 0) / 864e5)}d)` : "off — no dead-flag evidence is collected"
 			});
 		}),
-		onDeactivate: () => i.sync(() => N.set({}))
+		onDeactivate: () => c.promise(async () => {
+			await v?.stop(), v = void 0, Y.disable(), I.set({});
+		})
 	});
 };
 //#endregion
-export { r as FlagDisabled, I as describeFlags, E as evaluateAll, D as evaluateAllVariants, S as evaluateFlag, x as evaluateSchedule, T as evaluateVariant, A as featureFlagsTable, j as flagAuditTable, N as flagRegistry, G as flagsPlugin, F as flipFlagEnabled, H as isFlagEnabled, M as mergeOverrides, U as requireFlag, w as resolveVariant, P as setFlagEnabled, m as toDefinition };
+export { pe as DEFAULT_FLAG_USAGE_FLUSH_MS, G as FLAG_LIFECYCLE_LIMITS, q as FLAG_USAGE_TABLE, s as FlagDisabled, V as assertFlagExperimentLinks, B as checkFlagExperimentLinks, W as classifyShape, fe as dataStoreFlagUsageStore, o as defineFlag, z as describeFlags, ne as evaluateAll, re as evaluateAllVariants, O as evaluateFlag, D as evaluateSchedule, A as evaluateVariant, N as featureFlagsTable, P as flagAuditTable, K as flagLifecycleReport, I as flagRegistry, Y as flagUsageBuffer, ue as flagUsageRowId, J as flagUsageTable, _e as flagValue, ve as flagVariant, be as flagsPlugin, R as flipFlagEnabled, i as gateOverride, Q as isFlagEnabled, a as isTypedFlag, F as mergeOverrides, X as recordFlagEvaluation, he as registerFlagUsageRetention, ge as requireFlag, k as resolveVariant, L as setFlagEnabled, me as startFlagUsageFlush, x as toDefinition, r as typedValueOf, ce as utcDay };