@toggld/js 0.0.0-stage → 0.9.0

package/dist/core-BQfyNOoT.mjs

@@ -0,0 +1,921 @@
+import { a as decodeOfrepSuccess, d as discard, f as makeSend, h as withTimeout, i as decodeOfrepFailure, l as apiUrl, m as refusalMessage, n as decodeOfrepBulk, o as decodeSnapshot, p as readJson, s as decodeStreamMessage, u as describe } from "./wire-CrkBeqnM.mjs";
+import { _ as wireErrorDetails, a as Resolution, b as noTelemetry, d as SYNC_PROTOCOL, f as attributeOf, g as rejectedMessage, h as okDetails, i as syncCredentialProblem, l as STREAM_PONG_TIMEOUT_MS, m as codeFor, n as errorDetails, o as STREAM_PING, p as targetingKeyOf, r as invalidEndpointMessage, s as STREAM_PING_INTERVAL_MS, t as enforceType, u as SYNC_BEARER_PROTOCOL_PREFIX, v as lazyTelemetry, x as startTelemetry } from "./details-AiMdctXB.mjs";
+import { readFile, watch } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+// ../engine/src/hash.ts
+/**
+* MurmurHash3 (x86, 32-bit). A fast, well-distributed, non-cryptographic hash.
+* Used to deterministically bucket a subject into a percentage rollout slice so
+* that a given subject always lands in the same slice for a given flag/rule.
+*/
+const murmur3 = (key, seed = 0) => {
+	const data = new TextEncoder().encode(key);
+	const len = data.length;
+	const c1 = 3432918353;
+	const c2 = 461845907;
+	let h1 = seed >>> 0;
+	const nblocks = len >>> 2;
+	const mul32 = (a, b) => {
+		const aHi = a >>> 16 & 65535;
+		return ((a & 65535) * b >>> 0) + ((aHi * b & 65535) << 16) >>> 0;
+	};
+	const rotl32 = (x, r) => (x << r | x >>> 32 - r) >>> 0;
+	for (let i = 0; i < nblocks; i++) {
+		const o = i * 4;
+		let k1 = (data[o] | data[o + 1] << 8 | data[o + 2] << 16 | data[o + 3] << 24) >>> 0;
+		k1 = mul32(k1, c1);
+		k1 = rotl32(k1, 15);
+		k1 = mul32(k1, c2);
+		h1 = (h1 ^ k1) >>> 0;
+		h1 = rotl32(h1, 13);
+		h1 = mul32(h1, 5) + 3864292196 >>> 0;
+	}
+	let k1 = 0;
+	const tail = nblocks * 4;
+	const rem = len & 3;
+	if (rem === 3) k1 ^= data[tail + 2] << 16;
+	if (rem >= 2) k1 ^= data[tail + 1] << 8;
+	if (rem >= 1) {
+		k1 ^= data[tail];
+		k1 = mul32(k1, c1);
+		k1 = rotl32(k1, 15);
+		k1 = mul32(k1, c2);
+		h1 = (h1 ^ k1) >>> 0;
+	}
+	h1 = (h1 ^ len) >>> 0;
+	h1 = (h1 ^ h1 >>> 16) >>> 0;
+	h1 = mul32(h1, 2246822507);
+	h1 = (h1 ^ h1 >>> 13) >>> 0;
+	h1 = mul32(h1, 3266489909);
+	h1 = (h1 ^ h1 >>> 16) >>> 0;
+	return h1 >>> 0;
+};
+/** Resolution of a bucket: a subject maps to an integer in `[0, BUCKET_SCALE)`. */
+const BUCKET_SCALE = 1e4;
+/**
+* Deterministically maps a subject to a bucket in `[0, BUCKET_SCALE)`. The hash
+* input combines the flag key, rule id, and subject so that the same subject
+* gets independent buckets across different flags/rules (no correlation).
+*/
+const bucketFor = (flagKey, ruleId, subject) => {
+	return murmur3(`${flagKey}:${ruleId}:${subject}`) % BUCKET_SCALE;
+};
+// ../engine/src/targeting.ts
+const asNumber = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+const asString = (v) => typeof v === "string" ? v : void 0;
+/** Evaluates a single condition against the context. */
+const matchCondition = (condition, ctx) => {
+	const actual = attributeOf(ctx, condition.attribute);
+	const operand = condition.value;
+	switch (condition.operator) {
+		case "exists": return actual !== void 0 && actual !== null;
+		case "notExists": return actual === void 0 || actual === null;
+	}
+	if (actual === void 0 || actual === null) return false;
+	switch (condition.operator) {
+		case "eq": return deepEqual(actual, operand ?? null);
+		case "ne": return !deepEqual(actual, operand ?? null);
+		case "in": return Array.isArray(operand) && operand.some((o) => deepEqual(actual, o));
+		case "notIn": return !Array.isArray(operand) || !operand.some((o) => deepEqual(actual, o));
+		case "lt":
+		case "lte":
+		case "gt":
+		case "gte": {
+			const a = asNumber(actual);
+			const b = asNumber(operand);
+			if (a === void 0 || b === void 0) return false;
+			return condition.operator === "lt" ? a < b : condition.operator === "lte" ? a <= b : condition.operator === "gt" ? a > b : a >= b;
+		}
+		case "contains":
+		case "startsWith":
+		case "endsWith": {
+			const a = asString(actual);
+			const b = asString(operand);
+			if (a === void 0 || b === void 0) return false;
+			return condition.operator === "contains" ? a.includes(b) : condition.operator === "startsWith" ? a.startsWith(b) : a.endsWith(b);
+		}
+	}
+};
+/**
+* A rule matches when every one of its conditions matches **and** every
+* referenced segment resolves (member XOR `negate`) through `isMemberOf`
+* (logical AND throughout). A rule with no segment references behaves exactly as
+* conditions-only. `isMemberOf` is consulted only when the rule has segments;
+* when absent, any segment reference resolves `false` (closed).
+*/
+const matchRule = (rule, ctx, isMemberOf) => {
+	if (!rule.conditions.every((c) => matchCondition(c, ctx))) return false;
+	if (rule.segments === void 0 || rule.segments.length === 0) return true;
+	return rule.segments.every((ref) => {
+		const member = isMemberOf?.(ref.segment) ?? false;
+		return ref.negate ? !member : member;
+	});
+};
+/**
+* Resolves segment membership for a subject from a synced segment *definition*
+* (ADR-0006) — the local path for rule-based and `inline`-list segments. Pure
+* and isomorphic: the server and the Node SDK build their `isMemberOf` over
+* this. Membership is the union of a rule match (OR of rules, each an AND of
+* conditions) and presence in the inline member list (keyed by `keyAttribute`).
+* `remote` segments carry no `members` here and must be resolved out of band.
+*/
+const matchSegment = (segment, ctx) => {
+	if (segment.rules.some((r) => r.conditions.every((c) => matchCondition(c, ctx)))) return true;
+	if (segment.members !== void 0 && segment.members.length > 0) {
+		const subject = attributeOf(ctx, segment.keyAttribute);
+		if (typeof subject === "string" && segment.members.includes(subject)) return true;
+	}
+	return false;
+};
+/**
+* Selects a rollout variant for a subject. Weights are normalised across all
+* splits, and the subject's bucket (consistent for the flag/rule/subject) is
+* mapped onto the cumulative weight ranges. Returns `MissingSubject` when no
+* bucketing value is available (→ `TARGETING_KEY_MISSING`).
+*/
+const selectRolloutVariant = (flagKey, ruleId, splits, bucketBy, ctx) => {
+	const subject = bucketBy === void 0 ? targetingKeyOf(ctx) : asString(attributeOf(ctx, bucketBy));
+	if (subject === void 0) return { _tag: "MissingSubject" };
+	const total = splits.reduce((sum, s) => sum + s.weight, 0);
+	if (total <= 0) {
+		const first = splits[0];
+		if (first === void 0) return { _tag: "MissingSubject" };
+		return {
+			_tag: "Variant",
+			variant: first.variant,
+			bucket: 0
+		};
+	}
+	const bucket = bucketFor(flagKey, ruleId, subject);
+	let cumulative = 0;
+	for (const split of splits) {
+		cumulative += split.weight / total * BUCKET_SCALE;
+		if (bucket < cumulative) return {
+			_tag: "Variant",
+			variant: split.variant,
+			bucket
+		};
+	}
+	return {
+		_tag: "Variant",
+		variant: splits[splits.length - 1].variant,
+		bucket
+	};
+};
+const deepEqual = (a, b) => {
+	if (a === b) return true;
+	if (typeof a !== typeof b) return false;
+	if (a === null || b === null) return a === b;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((x, i) => deepEqual(x, b[i]));
+	}
+	if (typeof a === "object" && typeof b === "object") {
+		const ak = Object.keys(a);
+		const bk = Object.keys(b);
+		if (ak.length !== bk.length) return false;
+		return ak.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+	}
+	return false;
+};
+// ../engine/src/evaluate.ts
+/**
+* Looks up a variant's value and returns a successful resolution, or an
+* abnormal `GENERAL` resolution if the variant is not declared (a
+* misconfiguration that validation should have caught).
+*/
+const serveVariant = (flag, variant, reason) => {
+	if (!Object.prototype.hasOwnProperty.call(flag.variants, variant)) return Resolution.error({
+		value: null,
+		errorCode: "GENERAL",
+		errorMessage: `Flag '${flag.key}' references undeclared variant '${variant}'`,
+		flagMetadata: flag.metadata
+	});
+	return Resolution.ok({
+		value: flag.variants[variant],
+		variant,
+		reason,
+		flagMetadata: flag.metadata
+	});
+};
+/**
+* Evaluates a flag against an evaluation context, producing OpenFeature
+* resolution details. This is the pure heart of the service.
+*
+* Order of resolution:
+*  1. disabled flag → `offVariant` (or `defaultVariant`) with reason `DISABLED`
+*  2. first matching targeting rule:
+*       - fixed variant → `TARGETING_MATCH`
+*       - rollout       → `SPLIT` (or `TARGETING_KEY_MISSING` if no subject)
+*  3. no rule matches → `defaultVariant` with reason `STATIC`
+*
+* `isMemberOf` resolves any {@link SegmentRef} a rule references (ADR-0006). It
+* is optional: flags with no segment references never call it, and when it is
+* omitted a segment reference resolves `false` (closed).
+*/
+const evaluateFlag = (flag, ctx, isMemberOf) => {
+	if (!flag.enabled) return serveVariant(flag, flag.offVariant ?? flag.defaultVariant, "DISABLED");
+	for (const rule of flag.targeting) {
+		if (!matchRule(rule, ctx, isMemberOf)) continue;
+		if (rule.serve.type === "variant") return serveVariant(flag, rule.serve.variant, "TARGETING_MATCH");
+		const outcome = selectRolloutVariant(flag.key, rule.id, rule.serve.splits, rule.serve.bucketBy, ctx);
+		if (outcome._tag === "MissingSubject") return Resolution.error({
+			value: flag.variants[flag.defaultVariant] ?? null,
+			variant: flag.defaultVariant,
+			errorCode: "TARGETING_KEY_MISSING",
+			errorMessage: `Flag '${flag.key}' rule '${rule.id}' requires a bucketing key but none was provided`,
+			flagMetadata: flag.metadata
+		});
+		return serveVariant(flag, outcome.variant, "SPLIT");
+	}
+	return serveVariant(flag, flag.defaultVariant, "STATIC");
+};
+// src/internal/evaluate.ts
+/** Map an engine {@link Resolution} to evaluation details, OpenFeature-style:
+* an abnormal resolution serves the **caller's** default, not the engine's
+* internal fallback — exactly what the remote wire does on a 400. */
+const resolutionDetails = (key, resolution, fallback) => resolution.errorCode !== void 0 ? errorDetails(key, fallback, resolution.errorCode, resolution.errorMessage ?? "", resolution.flagMetadata) : {
+	flagKey: key,
+	value: typeof resolution.value === "object" && resolution.value !== null ? structuredClone(resolution.value) : resolution.value,
+	variant: resolution.variant,
+	reason: resolution.reason,
+	errorCode: void 0,
+	errorMessage: void 0,
+	flagMetadata: { ...resolution.flagMetadata }
+};
+/**
+* Whether a fetched snapshot may replace the held one. Without a
+* `configVersion` on either side (an older server, a file), versions can't be
+* ordered, so the fetch wins. Stream messages are not gated: one connection
+* delivers them in order, and its greeting resets the order after a reconnect.
+*/
+const isNewer = (incoming, held) => incoming === void 0 || held === void 0 || incoming > held;
+/**
+* A snapshot version that can travel as a strong entity tag: visible ASCII
+* without `"`. The server only sends an `ETag` for such versions, so the
+* clients only send `If-None-Match` for them.
+*/
+const etagFor = (version) => version !== void 0 && /^[\x21\x23-\x7e]+$/.test(version) ? `"${version}"` : void 0;
+/**
+* The in-memory snapshot a source feeds and the engine reads, plus the
+* evaluation surface over it. Sources (network, file, serverless refresh) differ
+* only in how they produce snapshots; everything downstream of `adopt` is
+* shared.
+*/
+const makeSnapshotStore = (mergedContext, record) => {
+	let current;
+	let epoch = 0;
+	let lastError;
+	let markReady;
+	const ready = new Promise((resolve) => {
+		markReady = resolve;
+	});
+	const notReadyMessage = () => lastError === void 0 ? "No flag snapshot loaded yet" : `No flag snapshot loaded yet. Last error: ${lastError}`;
+	const sink = {
+		adopt: (snapshot) => {
+			epoch++;
+			lastError = void 0;
+			current = {
+				version: snapshot.version,
+				configVersion: snapshot.configVersion,
+				flags: snapshot.flags,
+				byKey: new Map(snapshot.flags.map((f) => [f.key, f])),
+				segmentsByKey: new Map((snapshot.segments ?? []).map((s) => [s.key, s]))
+			};
+			markReady();
+		},
+		fail: (message) => {
+			lastError = message;
+		},
+		epoch: () => epoch,
+		version: () => current?.version,
+		configVersion: () => current?.configVersion
+	};
+	const warnedRemoteSegments = /* @__PURE__ */ new Set();
+	const memberOf = (state, ctx) => (segmentKey) => {
+		const segment = state.segmentsByKey.get(segmentKey);
+		if (segment === void 0) return false;
+		if (matchSegment(segment, ctx)) return true;
+		if (segment.listMode === "remote" && !warnedRemoteSegments.has(segmentKey)) {
+			warnedRemoteSegments.add(segmentKey);
+			console.warn(`[toggld] Segment '${segmentKey}' uses a remote member list, which is not available to in-process evaluation yet — treating subjects its rules don't match as non-members.`);
+		}
+		return false;
+	};
+	const evaluate = (key, defaultValue, context) => {
+		const state = current;
+		if (state === void 0) return errorDetails(key, defaultValue, "PROVIDER_NOT_READY", notReadyMessage());
+		const flag = state.byKey.get(key);
+		if (flag === void 0) return errorDetails(key, defaultValue, "FLAG_NOT_FOUND", `Flag '${key}' not found`);
+		const ctx = mergedContext(context);
+		const resolution = evaluateFlag(flag, ctx, memberOf(state, ctx));
+		record(key, resolution);
+		return resolutionDetails(key, resolution, defaultValue);
+	};
+	const evaluateAll = (context) => {
+		const state = current;
+		if (state === void 0) return [];
+		const ctx = mergedContext(context);
+		const isMemberOf = memberOf(state, ctx);
+		return state.flags.map((flag) => {
+			const resolution = evaluateFlag(flag, ctx, isMemberOf);
+			record(flag.key, resolution);
+			return resolutionDetails(flag.key, resolution, null);
+		});
+	};
+	return {
+		sink,
+		ready,
+		evaluate,
+		evaluateAll,
+		isReady: () => current !== void 0,
+		lastError: () => lastError
+	};
+};
+// src/internal/sync.ts
+/**
+* The two in-process snapshot sources, on plain timers and callbacks:
+*
+* - the network source for sync mode (ADR-0012): bootstrap + safety-net poll
+*   over `GET /sync/v1/flags`, plus a live WebSocket stream (`/sync/v1/stream`);
+* - the file source for file mode (ADR-0013): a snapshot on disk, watched for
+*   edits.
+*
+* Each `start…` function begins work at once and returns a `stop` function
+* that cancels every timer, socket, and watcher it owns. Work that is already
+* in flight when `stop` runs is abandoned, and never adopts.
+*/
+const DEFAULT_POLL_INTERVAL_MS = 3e4;
+/** The relaxed safety poll while a durable server's stream is healthy. */
+const DEFAULT_STREAM_POLL_INTERVAL_MS = 3e5;
+/** The default flag file in file mode. */
+const DEFAULT_FLAGS_FILE = "./toggld.flags.json";
+/** File mode's safety-net re-read; the directory watcher adopts edits sooner. */
+const FILE_RELOAD_INTERVAL_MS = 3e4;
+const NORMAL_CLOSURE = 1e3;
+/**
+* Timers that all die with their owner. `sleep` resolves early (and `after`
+* callbacks never run) once `stop` is called, so loops end by checking
+* `stopped` after each wait.
+*/
+var Lifetime = class {
+	stopped = false;
+	controller = new AbortController();
+	#timers = /* @__PURE__ */ new Set();
+	#sleepers = /* @__PURE__ */ new Set();
+	after(ms, f) {
+		const timer = setTimeout(() => {
+			this.#timers.delete(timer);
+			if (!this.stopped) f();
+		}, ms);
+		this.#timers.add(timer);
+		return timer;
+	}
+	cancel(timer) {
+		if (timer === void 0) return;
+		clearTimeout(timer);
+		this.#timers.delete(timer);
+	}
+	sleep(ms) {
+		return new Promise((resolve) => {
+			const wake = () => {
+				this.#sleepers.delete(wake);
+				resolve();
+			};
+			this.#sleepers.add(wake);
+			const timer = setTimeout(() => {
+				this.#timers.delete(timer);
+				wake();
+			}, ms);
+			this.#timers.add(timer);
+		});
+	}
+	stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		for (const timer of this.#timers) clearTimeout(timer);
+		this.#timers.clear();
+		for (const wake of [...this.#sleepers]) wake();
+		this.controller.abort();
+	}
+};
+/** The sync stream's `ws(s)://` URL under the endpoint, keeping any path prefix. Exported for tests. */
+const toStreamUrl = (endpoint) => {
+	const url = apiUrl(endpoint, "/sync/v1/stream");
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	return url.toString();
+};
+/** Whether `incoming` is a known version above the held one (or the first one). */
+const isNewerLabel = (incoming, held) => incoming !== void 0 && (held === void 0 || incoming > held);
+const textDecoder = new TextDecoder();
+/**
+* The network source (ADR-0012): bootstrap + safety-net poll over
+* `GET /sync/v1/flags`, plus a live WebSocket stream. Feeds `sink.adopt`.
+*/
+const startNetworkSource = (options, send, sink, timeoutMs) => {
+	const life = new Lifetime();
+	const transport = options.sync?.transport ?? "ws";
+	const pollIntervalMs = options.sync?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const streamPollIntervalMs = Math.max(pollIntervalMs, options.sync?.streamPollIntervalMs ?? DEFAULT_STREAM_POLL_INTERVAL_MS);
+	const health = {
+		open: false,
+		durable: false,
+		heartbeat: false,
+		answered: false
+	};
+	const isRelaxed = () => health.open && health.durable && health.heartbeat && health.answered;
+	let relaxedNow = false;
+	const updateHealth = (change) => {
+		Object.assign(health, change);
+		const relaxed = isRelaxed();
+		if (relaxed === relaxedNow) return;
+		relaxedNow = relaxed;
+		if (pollTimer !== void 0) schedulePoll();
+	};
+	const fetchSnapshot = () => withTimeout(timeoutMs, async (signal) => {
+		const etag = etagFor(sink.version());
+		const response = await send("GET", "/sync/v1/flags", void 0, signal, etag === void 0 ? void 0 : { "if-none-match": etag });
+		if (response.status === 304) {
+			discard(response);
+			return;
+		}
+		if (response.status < 200 || response.status >= 300) {
+			discard(response);
+			throw new Error(refusalMessage(response, "The key cannot read flag definitions (HTTP 403). Sync mode needs a secret SDK key (ffk_…)."));
+		}
+		return decodeSnapshot(await readJson(response, "GET /sync/v1/flags"));
+	}, life.controller.signal);
+	const report = (error) => {
+		if (!life.stopped) sink.fail(describe(error));
+	};
+	const pollOnce = async () => {
+		const before = sink.epoch();
+		const snapshot = await fetchSnapshot();
+		if (life.stopped || snapshot === void 0) return;
+		if (sink.epoch() !== before) return;
+		if (sink.version() === snapshot.version) return;
+		if (!isNewer(snapshot.configVersion, sink.configVersion())) return;
+		sink.adopt(snapshot);
+	};
+	let pollTimer;
+	let lastPollAt = 0;
+	const schedulePoll = () => {
+		life.cancel(pollTimer);
+		pollTimer = void 0;
+		if (life.stopped) return;
+		const waitMs = Math.max(0, lastPollAt + (relaxedNow ? streamPollIntervalMs : pollIntervalMs) - Date.now());
+		if (waitMs === 0) runPoll();
+		else pollTimer = life.after(waitMs, () => void runPoll());
+	};
+	const runPoll = async () => {
+		pollTimer = void 0;
+		await pollOnce().catch(report);
+		lastPollAt = Date.now();
+		schedulePoll();
+	};
+	const startPolling = async () => {
+		let delay = 250;
+		while (!life.stopped && sink.version() === void 0) {
+			await pollOnce().catch(report);
+			if (life.stopped || sink.version() !== void 0) break;
+			await life.sleep(delay);
+			delay = Math.min(delay * 2, 5e3);
+		}
+		if (life.stopped) return;
+		lastPollAt = Date.now();
+		schedulePoll();
+	};
+	const handleMessage = (raw) => {
+		if (raw === "pong") return;
+		let message;
+		try {
+			message = decodeStreamMessage(JSON.parse(raw));
+		} catch {
+			return;
+		}
+		updateHealth({
+			durable: message.durable,
+			heartbeat: message.heartbeat
+		});
+		const { snapshot } = message;
+		if (sink.version() === snapshot.version && !isNewerLabel(snapshot.configVersion, sink.configVersion())) return;
+		sink.adopt(snapshot);
+	};
+	const streamUrl = toStreamUrl(options.endpoint ?? "");
+	const WebSocketImpl = options.sync?.webSocketConstructor ?? globalThis.WebSocket;
+	const protocols = [SYNC_PROTOCOL, `${SYNC_BEARER_PROTOCOL_PREFIX}${options.sdkKey ?? ""}`];
+	let consecutiveFailures = 0;
+	let endConnection;
+	/**
+	* One connection: open (within the request timeout), read, and heartbeat,
+	* until it closes, errors, or misses a pong. Then reconnect with backoff.
+	*/
+	const connect = () => {
+		if (life.stopped) return;
+		let ws;
+		try {
+			ws = new WebSocketImpl(streamUrl, protocols);
+		} catch {
+			reconnectLater();
+			return;
+		}
+		try {
+			ws.binaryType = "arraybuffer";
+		} catch {}
+		let opened = false;
+		let ended = false;
+		let awaitingPong = false;
+		let heartbeatTimer;
+		const openTimer = life.after(timeoutMs, () => end());
+		const beatIn = (ms) => {
+			heartbeatTimer = life.after(ms, () => {
+				if (!health.heartbeat) return beatIn(STREAM_PING_INTERVAL_MS);
+				awaitingPong = true;
+				try {
+					ws.send(STREAM_PING);
+				} catch {
+					return end();
+				}
+				heartbeatTimer = life.after(STREAM_PONG_TIMEOUT_MS, () => {
+					if (awaitingPong) return end();
+					beatIn(STREAM_PING_INTERVAL_MS - STREAM_PONG_TIMEOUT_MS);
+				});
+			});
+		};
+		const onOpen = () => {
+			if (ended || opened) return;
+			opened = true;
+			life.cancel(openTimer);
+			consecutiveFailures = 0;
+			updateHealth({ open: true });
+			beatIn(STREAM_PING_INTERVAL_MS);
+		};
+		const onFrame = (text) => {
+			if (ended) return;
+			if (awaitingPong) {
+				awaitingPong = false;
+				updateHealth({ answered: true });
+			}
+			handleMessage(text);
+		};
+		const onMessage = (event) => {
+			const data = event.data;
+			if (typeof data === "string") onFrame(data);
+			else if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) onFrame(textDecoder.decode(data));
+			else if (typeof Blob !== "undefined" && data instanceof Blob) data.text().then(onFrame, () => end());
+		};
+		const onEnd = () => end();
+		const end = () => {
+			if (ended) return;
+			ended = true;
+			endConnection = void 0;
+			life.cancel(openTimer);
+			life.cancel(heartbeatTimer);
+			ws.removeEventListener("open", onOpen);
+			ws.removeEventListener("message", onMessage);
+			ws.removeEventListener("error", onEnd);
+			ws.removeEventListener("close", onEnd);
+			ws.addEventListener("error", () => {});
+			try {
+				ws.close(NORMAL_CLOSURE);
+			} catch {}
+			if (opened) updateHealth({
+				open: false,
+				durable: false,
+				heartbeat: false,
+				answered: false
+			});
+			reconnectLater();
+		};
+		endConnection = end;
+		ws.addEventListener("open", onOpen);
+		ws.addEventListener("message", onMessage);
+		ws.addEventListener("error", onEnd);
+		ws.addEventListener("close", onEnd);
+		if (ws.readyState >= 2) end();
+		else if (ws.readyState === 1) onOpen();
+	};
+	const reconnectLater = () => {
+		if (life.stopped) return;
+		consecutiveFailures++;
+		const base = Math.min(3e4, 1e3 * 2 ** Math.min(consecutiveFailures - 1, 5));
+		life.after(base * (.5 + Math.random() * .5), connect);
+	};
+	startPolling();
+	if (transport === "ws") connect();
+	return () => {
+		if (life.stopped) return;
+		life.stop();
+		endConnection?.();
+	};
+};
+/**
+* The file source (ADR-0013): read a `FlagSnapshot` from disk, watch it for
+* edits, and adopt on change. The envelope keys a `pull`-generated file carries
+* (`$schema`, `toggld`) are ignored by the snapshot decoder. No network, key, or
+* stream. Re-reads on a fixed safety interval; `sync` options do not apply.
+*/
+const startFileSource = (path, sink) => {
+	const life = new Lifetime();
+	let lastError;
+	let loadedText;
+	const readOnce = async () => {
+		try {
+			const text = await readFile(path, "utf8");
+			if (life.stopped) return;
+			if (text === loadedText) {
+				lastError = void 0;
+				return;
+			}
+			const snapshot = decodeSnapshot(JSON.parse(text));
+			lastError = void 0;
+			loadedText = text;
+			sink.adopt(snapshot);
+		} catch (error) {
+			if (life.stopped) return;
+			const message = describe(error);
+			sink.fail(`Could not load flags file '${path}': ${message}`);
+			if (message === lastError) return;
+			lastError = message;
+			console.warn(`[toggld] Could not load flags file '${path}': ${message}`);
+		}
+	};
+	const firstRead = readOnce();
+	const ticker = async () => {
+		await firstRead;
+		let delay = 100;
+		while (!life.stopped && sink.version() === void 0) {
+			await life.sleep(delay);
+			if (life.stopped) break;
+			delay = Math.min(delay * 2, 2e3);
+			await readOnce();
+		}
+		while (!life.stopped) {
+			await life.sleep(FILE_RELOAD_INTERVAL_MS);
+			if (life.stopped) break;
+			await readOnce();
+		}
+	};
+	const dir = dirname(path);
+	const base = basename(path);
+	const watchLoop = async () => {
+		while (!life.stopped) {
+			let iterator;
+			try {
+				iterator = watch(dir, { signal: life.controller.signal })[Symbol.asyncIterator]();
+			} catch {
+				iterator = void 0;
+			}
+			if (iterator === void 0) {
+				await life.sleep(1e3);
+				continue;
+			}
+			for (;;) {
+				let next;
+				try {
+					next = await iterator.next();
+				} catch {
+					break;
+				}
+				if (next.done) break;
+				const filename = next.value?.filename;
+				if (filename === base || filename === null || filename === void 0) await readOnce();
+			}
+			if (life.stopped) break;
+			await life.sleep(500);
+		}
+	};
+	watchLoop();
+	ticker();
+	return {
+		stop: () => life.stop(),
+		firstRead
+	};
+};
+// src/internal/core.ts
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_READY_TIMEOUT_MS = 5e3;
+/**
+* Refuse, at creation, a sync-mode client that can never sync: no key, a
+* public token (the API answers `/sync/v1/*` with 403 for those, so the client
+* would serve fallback values forever), or no usable endpoint. Sync is the
+* default mode, so each message also names the way out.
+*/
+const assertCanSync = (options) => {
+	switch (syncCredentialProblem(options)) {
+		case "missing-key": throw new TypeError("[toggld] `sdkKey` is required. Sync mode (`mode: \"sync\"`, the default) downloads flag definitions with a secret SDK key (ffk_…). To evaluate from a flag file instead, set `mode: \"file\"` or TOGGLD_FLAGS_FILE.");
+		case "public-token": throw new TypeError("[toggld] `sdkKey` is a public token (ffp_…). Public tokens cannot download flag definitions, so they cannot run in sync mode (`mode: \"sync\"`, the default). Use a secret SDK key (ffk_…), or set `mode: \"remote\"` to send each evaluation to the API.");
+		case "invalid-endpoint": throw new TypeError(invalidEndpointMessage(options.endpoint));
+		case void 0: return;
+	}
+};
+/**
+* The runtime handles one request at a time per I/O context and cannot keep a
+* WebSocket, timers, or a background poll between requests: Cloudflare Workers
+* (`navigator.userAgent`) and Vercel Edge (the `EdgeRuntime` global). Sync
+* mode needs all three, so it refuses to start there.
+*/
+const requestScopedRuntime = () => {
+	const g = globalThis;
+	if (g.navigator?.userAgent === "Cloudflare-Workers") return "Cloudflare Workers";
+	if (typeof g.EdgeRuntime === "string") return "an edge runtime";
+};
+const assertLongLivedRuntime = () => {
+	const runtime = requestScopedRuntime();
+	if (runtime === void 0) return warnOnLambda();
+	throw new TypeError(`[toggld] Sync mode (\`mode: "sync"\`, the default) keeps a WebSocket, timers, and a background poll, which ${runtime} cannot hold between requests. Use "@toggld/js/serverless", the remote client for serverless runtimes (one bulk request per incoming request), or set \`mode: "remote"\` to send each evaluation to the API.`);
+};
+/**
+* AWS Lambda freezes the process between invocations. Sync mode still works
+* there, but its stream and poll stall while frozen, so after a
+* freeze an evaluation can use a snapshot of any age until the stream
+* reconnects. Warn once per process; the serverless client (remote, one bulk
+* request per invocation) fits better.
+*/
+let warnedLambda = false;
+const warnOnLambda = () => {
+	if (warnedLambda) return;
+	const name = typeof process === "undefined" ? void 0 : process.env.AWS_LAMBDA_FUNCTION_NAME;
+	if (name === void 0 || name === "") return;
+	warnedLambda = true;
+	console.warn("[toggld] Sync mode (`mode: \"sync\"`, the default) is running on AWS Lambda. Lambda freezes the process between invocations, so the sync stream and poll stall, and after a freeze evaluations can use a flag snapshot of any age. Use \"@toggld/js/serverless\", the remote client for serverless runtimes (one bulk request per incoming request), or set `mode: \"remote\"`.");
+};
+/** Apply `f` to a value that may still be on its way. */
+const mapMaybe = (a, f) => a instanceof Promise ? a.then(f) : f(a);
+const makeRemote = (send, mergedContext, timeoutMs, telemetry) => {
+	const evaluate = async (key, defaultValue, context, signal) => {
+		const path = `/ofrep/v1/evaluate/flags/${encodeURIComponent(key)}`;
+		try {
+			return await withTimeout(timeoutMs, async (s) => {
+				const response = await send("POST", path, { context: mergedContext(context) }, s);
+				const status = response.status;
+				if (status >= 200 && status < 300) return okDetails(key, decodeOfrepSuccess(await readJson(response, `POST ${path}`)));
+				if (status >= 400 && status < 500) {
+					let failure;
+					try {
+						failure = decodeOfrepFailure(await response.json());
+					} catch {
+						return errorDetails(key, defaultValue, "GENERAL", rejectedMessage(response));
+					}
+					return wireErrorDetails(defaultValue, failure);
+				}
+				return errorDetails(key, defaultValue, "GENERAL", `Unexpected response status ${status}`);
+			}, signal);
+		} catch (error) {
+			return errorDetails(key, defaultValue, codeFor(error), describe(error));
+		}
+	};
+	const evaluateAll = async (context, signal) => {
+		try {
+			return await withTimeout(timeoutMs, async (s) => {
+				const path = "/ofrep/v1/evaluate/flags";
+				const response = await send("POST", path, { context: mergedContext(context) }, s);
+				if (response.status < 200 || response.status >= 300) throw new Error(`Unexpected response status ${response.status}`);
+				const bulk = decodeOfrepBulk(await readJson(response, `POST ${path}`));
+				for (const entry of bulk) telemetry.record(entry.key, entry.ok ? {
+					variant: entry.variant,
+					reason: entry.reason
+				} : {
+					variant: void 0,
+					reason: "ERROR"
+				});
+				return bulk.map((entry) => entry.ok ? okDetails(entry.key, entry) : wireErrorDetails(null, entry));
+			}, signal);
+		} catch {
+			return [];
+		}
+	};
+	return {
+		ready: Promise.resolve(),
+		evaluate,
+		evaluateAll,
+		stop: () => {}
+	};
+};
+const MODES = /* @__PURE__ */ new Set([
+	"sync",
+	"file",
+	"remote"
+]);
+/**
+* Validate `mode`, `file`, and `sync.file`, then apply `TOGGLD_FLAGS_FILE`.
+* Throws a `TypeError` for the renamed `"local"` mode, an unknown mode, the
+* removed `sync.file`, and `file` outside file mode, so a migration mistake
+* fails at creation instead of being ignored. The env var, when set and not
+* empty, makes any client run in file mode from that path (the "redirect with
+* no code change" path, ADR-0013), overriding `file`.
+*/
+const resolveMode = (options) => {
+	const mode = options.mode ?? "sync";
+	if (mode === "local") throw new TypeError("[toggld] mode \"local\" was renamed: use \"sync\" to keep flag rules in sync with Toggld, or \"file\" to read a flag file.");
+	if (typeof mode !== "string" || !MODES.has(mode)) throw new TypeError(`[toggld] Unknown mode ${JSON.stringify(mode)}: use "sync" (the default), "file", or "remote".`);
+	const legacyFile = options.sync?.file;
+	if (legacyFile !== void 0) {
+		const path = typeof legacyFile === "string" && legacyFile.length > 0 ? legacyFile : DEFAULT_FLAGS_FILE;
+		throw new TypeError(`[toggld] \`sync.file\` was removed: to evaluate from a flag file, set \`mode: "file", file: ${JSON.stringify(path)}\`.`);
+	}
+	const file = options.file;
+	if (file !== void 0) {
+		if (mode !== "file") throw new TypeError(`[toggld] \`file\` only applies to file mode, but mode is "${mode}". Set \`mode: "file"\` to evaluate from ${JSON.stringify(file)}, or remove \`file\`.`);
+		if (typeof file !== "string" || file.length === 0) throw new TypeError(`[toggld] \`file\` must be a path to a flag file, got ${JSON.stringify(file)}.`);
+	}
+	const env = typeof process === "undefined" ? void 0 : process.env.TOGGLD_FLAGS_FILE;
+	if (typeof env === "string" && env.length > 0) return {
+		mode: "file",
+		path: env
+	};
+	if (mode === "file") return {
+		mode: "file",
+		path: file ?? "./toggld.flags.json"
+	};
+	return { mode };
+};
+/**
+* Start a client: sync (or the file watch) begins at once; nothing waits for
+* readiness. Throws a `TypeError` for invalid mode options (see {@link
+* resolveMode}) and for a sync-mode client that can never sync (see {@link
+* assertCanSync}), before any timer or request starts.
+*/
+const makeCore = (options) => {
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const resolved = resolveMode(options);
+	const local = resolved.mode !== "remote";
+	const networkSync = resolved.mode === "sync";
+	if (networkSync) {
+		assertLongLivedRuntime();
+		assertCanSync(options);
+	}
+	const send = makeSend(options, (json) => Buffer.from(json, "utf8"));
+	const mergedContext = (context) => ({
+		...options.defaultContext,
+		...context
+	});
+	const telemetry = options.telemetry === false ? noTelemetry : networkSync ? startTelemetry(send, options) : resolved.mode === "remote" && requestScopedRuntime() === void 0 ? lazyTelemetry(() => startTelemetry(send, {
+		...options,
+		unref: true
+	})) : noTelemetry;
+	let impl;
+	let probe;
+	let firstRead;
+	if (local) {
+		const store = makeSnapshotStore(mergedContext, telemetry.record);
+		let stop;
+		if (resolved.mode === "file") {
+			const source = startFileSource(resolved.path, store.sink);
+			stop = source.stop;
+			firstRead = source.firstRead;
+		} else stop = startNetworkSource(options, send, store.sink, timeoutMs);
+		impl = {
+			ready: store.ready,
+			evaluate: (key, defaultValue, context) => store.evaluate(key, defaultValue, context),
+			evaluateAll: (context) => store.evaluateAll(context),
+			stop
+		};
+		probe = store;
+	} else impl = makeRemote(send, mergedContext, timeoutMs, telemetry);
+	let closing;
+	let rejectClosed;
+	const closedSignal = new Promise((_, reject) => {
+		rejectClosed = reject;
+	});
+	closedSignal.catch(() => {});
+	const readyOrClosed = Promise.race([impl.ready, closedSignal]);
+	readyOrClosed.catch(() => {});
+	let warnedNotReady = false;
+	const waitForReady = async () => {
+		if (probe === void 0) return;
+		if (firstRead !== void 0) {
+			await Promise.race([firstRead, readyOrClosed.catch(() => {})]);
+			return;
+		}
+		const waitMs = options.sync?.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+		let timer;
+		await Promise.race([readyOrClosed.catch(() => {}), new Promise((resolve) => {
+			timer = setTimeout(resolve, waitMs);
+		})]);
+		clearTimeout(timer);
+		if (closing !== void 0 || probe.isReady() || warnedNotReady) return;
+		warnedNotReady = true;
+		const last = probe.lastError();
+		console.warn(`[toggld] No flag snapshot after ${waitMs} ms. Evaluations return your fallback values (PROVIDER_NOT_READY) until the first sync succeeds; sync keeps retrying in the background.` + (last === void 0 ? "" : ` Last error: ${last}`));
+	};
+	const typed = (key, defaultValue, context, type, signal) => {
+		return mapMaybe(impl.evaluate(key, defaultValue, context, signal), (d) => enforceType(d, key, defaultValue, type));
+	};
+	return {
+		synchronous: local,
+		ready: () => readyOrClosed,
+		waitForReady,
+		flushTelemetry: () => telemetry.flush(),
+		evaluate: (key, defaultValue, context, signal) => impl.evaluate(key, defaultValue, context, signal),
+		evaluateAll: (context, signal) => impl.evaluateAll(context, signal),
+		typed,
+		closed: () => closing !== void 0,
+		close: () => closing ??= (async () => {
+			rejectClosed(/* @__PURE__ */ new Error("[toggld] The client was closed."));
+			impl.stop();
+			await telemetry.close();
+		})()
+	};
+};
+export { mapMaybe as n, makeCore as t };