@toggld/node 0.1.0 → 0.3.0

package/dist/core-DBVGNtur.mjs

@@ -0,0 +1,644 @@
+import { a as OfrepSuccess, i as OfrepFailure, n as SyncServerMessage, r as OfrepBulkResponse, t as FlagSnapshot } from "./src-CCPvsrli.mjs";
+import { Context, Deferred, Duration, Effect, Layer, Schema } from "effect";
+import { readFile, watch } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+import { Socket } from "effect/unstable/socket";
+//#region ../spec/src/index.ts
+/** True when `value` is assignable to a flag declared as `type`. */
+const valueMatchesType = (value, type) => {
+	switch (type) {
+		case "boolean": return typeof value === "boolean";
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number" && Number.isFinite(value);
+		case "object": return typeof value === "object" && value !== null;
+	}
+};
+/**
+* The sync stream's WebSocket subprotocol name. Offered first by clients (the
+* server echoes the first offer back, completing the RFC 6455 negotiation).
+*/
+const SYNC_PROTOCOL = "toggld.sync.v1";
+/**
+* Subprotocol entry carrying the bearer credential on a sync WebSocket
+* upgrade: `toggld.bearer.<token>`. The standard `WebSocket` constructor
+* cannot set an `Authorization` header, so the token rides the
+* `Sec-WebSocket-Protocol` offer instead (a recognized pattern — it stays out
+* of URLs and access logs). Servers accept either this or a real
+* `Authorization: Bearer` header.
+*/
+const SYNC_BEARER_PROTOCOL_PREFIX = "toggld.bearer.";
+const TARGETING_KEY = "targetingKey";
+/** Reads the targeting key from a context, if present and a non-empty string. */
+const targetingKeyOf = (ctx) => {
+	const v = ctx[TARGETING_KEY];
+	return typeof v === "string" && v.length > 0 ? v : void 0;
+};
+/** Reads an arbitrary attribute, treating `targetingKey` like any other field. */
+const attributeOf = (ctx, attribute) => Object.prototype.hasOwnProperty.call(ctx, attribute) ? ctx[attribute] : void 0;
+const Resolution = {
+	/** A successful resolution. */
+	ok: (args) => ({
+		value: args.value,
+		variant: args.variant,
+		reason: args.reason,
+		errorCode: void 0,
+		errorMessage: void 0,
+		flagMetadata: args.flagMetadata ?? {}
+	}),
+	/** An abnormal resolution carrying an error code and a fallback value. */
+	error: (args) => ({
+		value: args.value,
+		variant: args.variant,
+		reason: "ERROR",
+		errorCode: args.errorCode,
+		errorMessage: args.errorMessage,
+		flagMetadata: args.flagMetadata ?? {}
+	})
+};
+//#endregion
+//#region ../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;
+};
+//#endregion
+//#region ../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;
+};
+//#endregion
+//#region ../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");
+};
+//#endregion
+//#region src/internal/core.ts
+/**
+* The Effect core of the Toggld Node SDK.
+*
+* This is the canonical implementation; `../index.ts` (the plain Promise API) is
+* a thin facade that runs this under a `ManagedRuntime`. Two evaluation modes
+* share one client surface (ADR-0001):
+*
+* - **Remote** (default): every call hits the flag API's OFREP endpoints, which
+*   evaluate the flag against the supplied context and return the resolved
+*   value (OpenFeature "remote evaluation").
+* - **Local** (`mode: "local"`): the client backgrounds a **definition sync** —
+*   a versioned snapshot fetch (`GET /sync/v1/flags`) plus a live WebSocket
+*   stream (`/sync/v1/stream`) with polling fallback — and evaluates flags
+*   in-process with `@toggld/engine`. Zero server requests per evaluation; the
+*   engine is the same code the server runs, so resolutions are identical.
+*
+* OpenFeature semantics: evaluation never throws. Any failure — network error,
+* timeout, unknown flag, a server-reported error, a value whose type doesn't
+* match the requested getter, or (local mode) no snapshot received yet —
+* resolves to the caller's default value with the details carrying
+* `reason: "ERROR"` and an `errorCode`.
+*/
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_POLL_INTERVAL_MS = 3e4;
+const isBoolean = (v) => typeof v === "boolean";
+const isString = (v) => typeof v === "string";
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const isObject = (v) => valueMatchesType(v, "object");
+const okDetails = (key, s) => ({
+	flagKey: key,
+	value: s.value,
+	variant: s.variant,
+	reason: s.reason,
+	errorCode: void 0,
+	errorMessage: void 0,
+	flagMetadata: s.metadata ?? {}
+});
+const wireErrorDetails = (fallback, e) => ({
+	flagKey: e.key,
+	value: fallback,
+	variant: void 0,
+	reason: "ERROR",
+	errorCode: e.errorCode,
+	errorMessage: e.errorDetails,
+	flagMetadata: e.metadata ?? {}
+});
+const errorDetails = (key, value, errorCode, errorMessage, flagMetadata = {}) => ({
+	flagKey: key,
+	value,
+	variant: void 0,
+	reason: "ERROR",
+	errorCode,
+	errorMessage,
+	flagMetadata
+});
+/** 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: resolution.value,
+	variant: resolution.variant,
+	reason: resolution.reason,
+	errorCode: void 0,
+	errorMessage: void 0,
+	flagMetadata: resolution.flagMetadata
+};
+/** A readable message for an arbitrary thrown/failed value. */
+const describe = (e) => typeof e === "object" && e !== null && "message" in e && typeof e.message === "string" ? e.message : String(e);
+/** Map a transport/decoding failure to an OpenFeature error code. */
+const codeFor = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag === "SchemaError" ? "PARSE_ERROR" : "GENERAL";
+/**
+* The Toggld client as an Effect service. Build a {@link layer} from options and
+* compose it into your runtime, then `yield* ToggldClient` to evaluate flags.
+*/
+var ToggldClient = class extends Context.Service()("@toggld/node/ToggldClient") {};
+const makeRemote = (http, mergedContext, timeout) => {
+	const decode = HttpClientResponse.schemaBodyJson;
+	const evaluate = (key, defaultValue, context) => Effect.gen(function* () {
+		const request = HttpClientRequest.post(`/ofrep/v1/evaluate/flags/${encodeURIComponent(key)}`).pipe(HttpClientRequest.bodyJsonUnsafe({ context: mergedContext(context) }));
+		const response = yield* http.execute(request);
+		return yield* HttpClientResponse.matchStatus(response, {
+			"2xx": (r) => Effect.map(decode(OfrepSuccess)(r), (s) => okDetails(key, s)),
+			"4xx": (r) => Effect.map(decode(OfrepFailure)(r), (e) => wireErrorDetails(defaultValue, e)),
+			orElse: (r) => Effect.succeed(errorDetails(key, defaultValue, "GENERAL", `Unexpected response status ${r.status}`))
+		});
+	}).pipe(Effect.timeout(timeout), Effect.catch((error) => Effect.succeed(errorDetails(key, defaultValue, codeFor(error), describe(error)))));
+	const evaluateAll = (context) => Effect.gen(function* () {
+		const request = HttpClientRequest.post("/ofrep/v1/evaluate/flags").pipe(HttpClientRequest.bodyJsonUnsafe({ context: mergedContext(context) }));
+		const response = yield* http.execute(request);
+		return (yield* HttpClientResponse.matchStatus(response, {
+			"2xx": (r) => decode(OfrepBulkResponse)(r),
+			orElse: (r) => Effect.fail(/* @__PURE__ */ new Error(`Unexpected response status ${r.status}`))
+		})).flags.map((entry) => "errorCode" in entry ? wireErrorDetails(null, entry) : okDetails(entry.key, entry));
+	}).pipe(Effect.timeout(timeout), Effect.catch(() => Effect.succeed([])));
+	return {
+		ready: Effect.void,
+		evaluate,
+		evaluateAll
+	};
+};
+const DEFAULT_FLAGS_FILE = "./toggld.flags.json";
+/** The endpoint's `ws(s)://` form for the sync stream. */
+const toStreamUrl = (endpoint) => {
+	const url = new URL(endpoint);
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	url.pathname = url.pathname.replace(/\/$/, "") + "/sync/v1/stream";
+	return url.toString();
+};
+const makeSnapshotStore = (mergedContext) => Effect.gen(function* () {
+	let current;
+	let epoch = 0;
+	const firstSnapshot = yield* Deferred.make();
+	const adopt = (snapshot) => Effect.suspend(() => {
+		epoch++;
+		current = {
+			version: snapshot.version,
+			flags: snapshot.flags,
+			byKey: new Map(snapshot.flags.map((f) => [f.key, f])),
+			segmentsByKey: new Map((snapshot.segments ?? []).map((s) => [s.key, s]))
+		};
+		return Effect.asVoid(Deferred.succeed(firstSnapshot, void 0));
+	});
+	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 local evaluation yet — treating subjects its rules don't match as non-members.`);
+		}
+		return false;
+	};
+	const evaluate = (key, defaultValue, context) => Effect.sync(() => {
+		const state = current;
+		if (state === void 0) return errorDetails(key, defaultValue, "PROVIDER_NOT_READY", "No flag snapshot loaded yet");
+		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);
+		return resolutionDetails(key, evaluateFlag(flag, ctx, memberOf(state, ctx)), defaultValue);
+	});
+	const evaluateAll = (context) => Effect.sync(() => {
+		const state = current;
+		if (state === void 0) return [];
+		const ctx = mergedContext(context);
+		const isMemberOf = memberOf(state, ctx);
+		return state.flags.map((flag) => resolutionDetails(flag.key, evaluateFlag(flag, ctx, isMemberOf), null));
+	});
+	return {
+		adopt,
+		epoch: () => epoch,
+		version: () => current?.version,
+		impl: {
+			ready: Deferred.await(firstSnapshot),
+			evaluate,
+			evaluateAll
+		}
+	};
+});
+/**
+* The network source (ADR-0012): bootstrap + safety-net poll over
+* `GET /sync/v1/flags`, plus a live WebSocket stream. Forks its fibers into the
+* caller's scope and feeds `store.adopt`.
+*/
+const startNetworkSource = (options, http, store, timeout) => Effect.gen(function* () {
+	const transport = options.sync?.transport ?? "ws";
+	const pollIntervalMs = options.sync?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const fetchSnapshot = Effect.gen(function* () {
+		const response = yield* http.execute(HttpClientRequest.get("/sync/v1/flags"));
+		return yield* HttpClientResponse.matchStatus(response, {
+			"2xx": HttpClientResponse.schemaBodyJson(FlagSnapshot),
+			orElse: (r) => Effect.fail(/* @__PURE__ */ new Error(`Unexpected response status ${r.status}`))
+		});
+	}).pipe(Effect.timeout(timeout));
+	const pollOnce = Effect.gen(function* () {
+		const before = store.epoch();
+		const snapshot = yield* fetchSnapshot;
+		if (store.epoch() !== before) return;
+		if (store.version() === snapshot.version) return;
+		yield* store.adopt(snapshot);
+	});
+	const ticker = Effect.gen(function* () {
+		let delay = 250;
+		while (store.version() === void 0) {
+			yield* pollOnce.pipe(Effect.ignore);
+			if (store.version() !== void 0) break;
+			yield* Effect.sleep(Duration.millis(delay));
+			delay = Math.min(delay * 2, 5e3);
+		}
+		yield* Effect.forever(Effect.sleep(Duration.millis(pollIntervalMs)).pipe(Effect.andThen(Effect.ignore(pollOnce))));
+	});
+	const decodeMessage = Schema.decodeUnknownEffect(SyncServerMessage);
+	const handleMessage = (raw) => Effect.gen(function* () {
+		const message = yield* decodeMessage(JSON.parse(String(raw)));
+		if (store.version() === message.version) return;
+		yield* store.adopt(message);
+	}).pipe(Effect.ignore);
+	const streamUrl = toStreamUrl(options.endpoint ?? "");
+	let consecutiveFailures = 0;
+	const streamLoop = Effect.gen(function* () {
+		const socket = yield* Socket.makeWebSocket(streamUrl, {
+			protocols: [SYNC_PROTOCOL, `${SYNC_BEARER_PROTOCOL_PREFIX}${options.sdkKey ?? ""}`],
+			openTimeout: timeout
+		});
+		yield* Effect.forever(Effect.gen(function* () {
+			yield* socket.runRaw(handleMessage, { onOpen: Effect.sync(() => {
+				consecutiveFailures = 0;
+			}) }).pipe(Effect.ignore);
+			consecutiveFailures++;
+			const base = Math.min(3e4, 1e3 * 2 ** Math.min(consecutiveFailures - 1, 5));
+			yield* Effect.sleep(Duration.millis(base * (.5 + Math.random() * .5)));
+		}));
+	});
+	yield* Effect.forkScoped(ticker);
+	if (transport === "ws") yield* Effect.forkScoped(streamLoop);
+});
+/**
+* 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 — purely local. Forks its fibers into the caller's scope.
+*/
+const startFileSource = (path, store, options) => Effect.gen(function* () {
+	const pollIntervalMs = options.sync?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const decodeSnapshot = Schema.decodeUnknownEffect(FlagSnapshot);
+	let lastError;
+	const readOnce = Effect.gen(function* () {
+		const text = yield* Effect.tryPromise(() => readFile(path, "utf8"));
+		const snapshot = yield* decodeSnapshot(JSON.parse(text));
+		lastError = void 0;
+		if (store.version() === snapshot.version) return;
+		yield* store.adopt(snapshot);
+	}).pipe(Effect.catch((error) => Effect.sync(() => {
+		const message = describe(error);
+		if (message === lastError) return;
+		lastError = message;
+		console.warn(`[toggld] Could not load flags file '${path}': ${message}`);
+	})));
+	const ticker = Effect.gen(function* () {
+		let delay = 100;
+		while (store.version() === void 0) {
+			yield* readOnce;
+			if (store.version() !== void 0) break;
+			yield* Effect.sleep(Duration.millis(delay));
+			delay = Math.min(delay * 2, 2e3);
+		}
+		yield* Effect.forever(Effect.sleep(Duration.millis(pollIntervalMs)).pipe(Effect.andThen(readOnce)));
+	});
+	const dir = dirname(path);
+	const base = basename(path);
+	const controller = new AbortController();
+	yield* Effect.addFinalizer(() => Effect.sync(() => controller.abort()));
+	const watchLoop = Effect.gen(function* () {
+		while (!controller.signal.aborted) {
+			const iterator = yield* Effect.sync(() => {
+				try {
+					return watch(dir, { signal: controller.signal })[Symbol.asyncIterator]();
+				} catch {
+					return;
+				}
+			});
+			if (iterator === void 0) {
+				yield* Effect.sleep(Duration.millis(1e3));
+				continue;
+			}
+			let live = true;
+			while (live) {
+				const next = yield* Effect.tryPromise(() => iterator.next()).pipe(Effect.catch(() => Effect.succeed({
+					done: true,
+					value: void 0
+				})));
+				if (next.done) {
+					live = false;
+					break;
+				}
+				const filename = next.value?.filename;
+				if (filename === base || filename === null || filename === void 0) yield* readOnce;
+			}
+			if (controller.signal.aborted) break;
+			yield* Effect.sleep(Duration.millis(500));
+		}
+	});
+	yield* Effect.forkScoped(ticker);
+	yield* Effect.forkScoped(watchLoop);
+});
+/**
+* Resolve a local flag-file path, or `undefined` for network sync. Highest
+* precedence first: the `TOGGLD_FLAGS_FILE` env var (so a deployed app can be
+* redirected at a file with no code change), then an explicit `sync.file`, then
+* `./toggld.flags.json` when `sync.file` is `true`.
+*/
+const resolveFilePath = (options) => {
+	const env = process.env.TOGGLD_FLAGS_FILE;
+	if (typeof env === "string" && env.length > 0) return env;
+	const file = options.sync?.file;
+	if (typeof file === "string" && file.length > 0) return file;
+	if (file === true) return DEFAULT_FLAGS_FILE;
+};
+/**
+* Assemble the local-mode evaluation surface, choosing the file source when a
+* path resolves (env var or `sync.file`) and the network source otherwise.
+*/
+const makeLocal = (options, http, mergedContext, timeout) => Effect.gen(function* () {
+	const store = yield* makeSnapshotStore(mergedContext);
+	const filePath = resolveFilePath(options);
+	if (filePath !== void 0) yield* startFileSource(filePath, store, options);
+	else yield* startNetworkSource(options, http, store, timeout);
+	return store.impl;
+});
+const make = (options) => Effect.gen(function* () {
+	const base = yield* HttpClient.HttpClient;
+	const timeout = Duration.millis(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	const http = base.pipe(HttpClient.mapRequest(HttpClientRequest.prependUrl(options.endpoint ?? "")), HttpClient.mapRequest(HttpClientRequest.bearerToken(options.sdkKey ?? "")));
+	const mergedContext = (context) => ({
+		...options.defaultContext,
+		...context
+	});
+	const { evaluate, evaluateAll, ready } = options.mode === "local" || resolveFilePath(options) !== void 0 ? yield* makeLocal(options, http, mergedContext, timeout) : makeRemote(http, mergedContext, timeout);
+	/** Resolve, then enforce the requested value type (else `TYPE_MISMATCH`). */
+	const typed = (key, defaultValue, context, type, guard) => Effect.map(evaluate(key, defaultValue, context), (d) => {
+		if (d.errorCode !== void 0) return d;
+		if (guard(d.value)) return d;
+		return errorDetails(key, defaultValue, "TYPE_MISMATCH", `Flag '${key}' value is not of type ${type}`, d.flagMetadata);
+	});
+	const valueOf = (details) => Effect.map(details, (d) => d.value);
+	return {
+		ready,
+		evaluate,
+		evaluateAll,
+		getBooleanDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "boolean", isBoolean),
+		getBooleanValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "boolean", isBoolean)),
+		getStringDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "string", isString),
+		getStringValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "string", isString)),
+		getNumberDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "number", isNumber),
+		getNumberValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "number", isNumber)),
+		getObjectDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "object", isObject),
+		getObjectValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "object", isObject))
+	};
+});
+/** The HttpClient layer, optionally backed by a caller-supplied `fetch`. */
+const httpLayer = (fetchImpl) => fetchImpl ? FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch, fetchImpl))) : FetchHttpClient.layer;
+/** The WebSocket constructor for the sync stream, optionally caller-supplied. */
+const webSocketLayer = (ctor) => ctor ? Layer.succeed(Socket.WebSocketConstructor, (url, protocols) => new ctor(url, protocols)) : Socket.layerWebSocketConstructorGlobal;
+/**
+* A self-contained `Layer` providing {@link ToggldClient} — it wires its own
+* HTTP and WebSocket backends, so Effect users need only provide this one
+* layer. In local mode the background sync fibers live in the layer's scope:
+* closing it (e.g. `ManagedRuntime.dispose`) stops sync and closes the stream.
+*/
+const layer = (options) => Layer.effect(ToggldClient, make(options)).pipe(Layer.provide(httpLayer(options.fetch)), Layer.provide(webSocketLayer(options.sync?.webSocketConstructor)));
+//#endregion
+export { layer as n, ToggldClient as t };

package/dist/effect.d.mts

@@ -1,12 +1,18 @@
-import { a as FlagMetadata, i as EvaluationContext, n as ToggldClientOptions, o as FlagValue, r as ErrorCode, s as Reason, t as EvaluationDetails } from "./types-RmWNnA7-.mjs";
+import { a as ErrorCode, c as FlagValue, i as ToggldClientOptions, l as Reason, n as EvaluationMode, o as EvaluationContext, r as SyncOptions, s as FlagMetadata, t as EvaluationDetails } from "./types-CPtRV5-5.mjs";
 import { Context, Effect, Layer } from "effect";
 
 //#region src/internal/core.d.ts
 /** The evaluation surface of a Toggld client. Every method is non-failing. */
 interface ToggldClientShape {
+  /**
+   * Resolves once the client is ready to evaluate: immediately in remote mode;
+   * on the first synced snapshot in local mode. Until then local evaluations
+   * resolve to the caller's default with `PROVIDER_NOT_READY`.
+   */
+  readonly ready: Effect.Effect<void>;
   /** Resolve a flag, returning full details with an untyped (JSON) value. */
   readonly evaluate: (key: string, defaultValue: FlagValue, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<FlagValue>>;
-  /** Resolve every flag for the environment in one request (OFREP bulk). */
+  /** Resolve every flag for the environment (one request in remote mode; in-process in local mode). */
   readonly evaluateAll: (context?: EvaluationContext) => Effect.Effect<ReadonlyArray<EvaluationDetails<FlagValue>>>;
   readonly getBooleanValue: (key: string, defaultValue: boolean, context?: EvaluationContext) => Effect.Effect<boolean>;
   readonly getBooleanDetails: (key: string, defaultValue: boolean, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<boolean>>;
@@ -25,8 +31,10 @@ declare const ToggldClient_base: Context.ServiceClass<ToggldClient, "@toggld/nod
 declare class ToggldClient extends ToggldClient_base {}
 /**
  * A self-contained `Layer` providing {@link ToggldClient} — it wires its own
- * HTTP backend, so Effect users need only provide this one layer.
+ * HTTP and WebSocket backends, so Effect users need only provide this one
+ * layer. In local mode the background sync fibers live in the layer's scope:
+ * closing it (e.g. `ManagedRuntime.dispose`) stops sync and closes the stream.
  */
 declare const layer: (options: ToggldClientOptions) => Layer.Layer<ToggldClient>;
 //#endregion
-export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type FlagMetadata, type FlagValue, type Reason, ToggldClient, type ToggldClientOptions, type ToggldClientShape, layer };
+export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type EvaluationMode, type FlagMetadata, type FlagValue, type Reason, type SyncOptions, ToggldClient, type ToggldClientOptions, type ToggldClientShape, layer };

package/dist/effect.mjs

@@ -1,2 +1,2 @@
-import { n as layer, t as ToggldClient } from "./core-zMjaOru1.mjs";
+import { n as layer, t as ToggldClient } from "./core-DBVGNtur.mjs";
 export { ToggldClient, layer };