@toggld/node 0.1.0 → 0.2.0

package/README.md

@@ -9,11 +9,18 @@ Two API surfaces ship from one implementation:
 - **`@toggld/node/effect`** — the native [Effect](https://effect.website) API:
   the client as a service + `Layer`.
 
-> **Remote evaluation only (for now).** Every call hits the flag API, which
-> evaluates the flag against your context and returns the resolved value
-> (OpenFeature "remote evaluation" over the OFREP endpoints). Local in-process
-> evaluation with a background definition sync — the `@toggld/engine` path — is a
-> later milestone; see [ADR-0001](../../docs/adr/0001-packaging-and-sdk-strategy.md).
+Two evaluation modes:
+
+- **Remote** (default) — every call hits the flag API, which evaluates the flag
+  against your context and returns the resolved value (OpenFeature "remote
+  evaluation" over the OFREP endpoints).
+- **Local** (`mode: "local"`) — recommended for long-lived servers. Flag
+  definitions sync in the background (a snapshot fetch plus a live WebSocket
+  stream, with polling fallback) and every evaluation runs **in-process** on
+  the bundled engine: microsecond latency, zero server requests per
+  evaluation, and changes pushed to your process within milliseconds. Requires
+  a secret SDK key (`ffk_…`) — public browser tokens cannot read rulesets. See
+  [ADR-0012](../../docs/adr/0012-definition-sync-and-local-evaluation.md).
 
 ## Install
 
@@ -29,6 +36,7 @@ import { ToggldClient } from "@toggld/node"
 const client = await ToggldClient.create({
   sdkKey: process.env.TOGGLD_SDK_KEY!, // an evaluation API key
   endpoint: "https://your-flag-api.example.com",
+  mode: "local", // omit for remote evaluation
 })
 
 // Typed getters — return the default on any error, never throw.
@@ -77,10 +85,31 @@ scope.
 | ---------------- | --------------------- | ---------------- | ---------------------------------------------------------------- |
 | `sdkKey`         | `string`              | —                | Evaluation (or management) API key; sent as `Bearer`.            |
 | `endpoint`       | `string`              | —                | Base URL of the flag API, no trailing path.                      |
+| `mode`           | `"remote" \| "local"` | `"remote"`       | Local = background definition sync + in-process engine.          |
+| `sync.transport` | `"ws" \| "poll"`      | `"ws"`           | Live stream (with poll safety net) vs polling only.              |
+| `sync.pollIntervalMs` | `number`         | `30000`          | Snapshot poll cadence; cold start retries faster.                |
+| `sync.readyTimeoutMs` | `number`         | `5000`           | How long `create` waits for the first snapshot.                  |
 | `defaultContext` | `EvaluationContext`   | `{}`             | Merged under per-call context (per-call attributes win).         |
 | `timeoutMs`      | `number`              | `5000`           | Per-request timeout.                                             |
 | `fetch`          | `typeof fetch`        | `globalThis.fetch` | Custom fetch (tests, proxies, instrumentation).               |
 
+In local mode `create` resolves once the first snapshot has synced (or after
+`sync.readyTimeoutMs`); until a snapshot arrives, evaluations return your
+defaults with `errorCode: "PROVIDER_NOT_READY"` and sync keeps retrying.
+`client.ready()` awaits sync explicitly. Updates arrive as WebSocket pushes
+within milliseconds of a management change; on runtimes where the stream is
+unavailable the client polls instead, automatically.
+
+### How fast is local mode?
+
+`pnpm bench:sync` (from the repo root) runs the same workload with sync off vs
+on — representative numbers on a laptop, loopback server:
+
+```
+sync OFF (remote OFREP)        ~11,600 evals/s   p50 2.4 ms
+sync ON  (local engine)     ~1,090,000 evals/s   p50 27 µs   (0.6 µs single-caller)
+```
+
 ## Error semantics
 
 Evaluation never throws. On a network failure, timeout, unknown flag, server

package/dist/{core-zMjaOru1.mjs → core-Bx0PVoEm.mjs}

@@ -1,5 +1,6 @@
-import { Context, Duration, Effect, Layer, Schema } from "effect";
+import { Context, Deferred, Duration, Effect, Layer, Schema } from "effect";
 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) => {
@@ -10,6 +11,246 @@ const valueMatchesType = (value, type) => {
 		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 (logical AND). */
+const matchRule = (rule, ctx) => rule.conditions.every((c) => matchCondition(c, ctx));
+/**
+* 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`
+*/
+const evaluateFlag = (flag, ctx) => {
+	if (!flag.enabled) return serveVariant(flag, flag.offVariant ?? flag.defaultVariant, "DISABLED");
+	for (const rule of flag.targeting) {
+		if (!matchRule(rule, ctx)) 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 ../schema/src/audit.ts
 /**
@@ -102,6 +343,15 @@ const CreateEnvironmentInput = Schema.Struct({
 	key: Schema.String.check(Schema.isMinLength(1)),
 	name: Schema.String.check(Schema.isMinLength(1))
 });
+Schema.Struct({
+	id: Schema.String,
+	tenantId: Schema.String,
+	/** The single environment this token is scoped to. */
+	environmentId: Schema.String,
+	/** The full token value — intentionally exposed; it is non-secret. */
+	token: Schema.String,
+	createdAt: Schema.String
+});
 /**
 * Public view of an API key — safe to list. Never includes the secret token or
 * its hash; only a non-secret prefix for human identification.
@@ -434,24 +684,59 @@ Schema.Struct({
 	tags: Schema.optionalKey(Tags)
 });
 //#endregion
+//#region ../schema/src/sync.ts
+/**
+* Definition-sync wire schemas (ADR-0001 §4): the versioned full snapshot the
+* sync surface serves to locally-evaluating SDKs, and the messages exchanged on
+* the live sync stream. Like the OFREP schemas, these are shared by the server
+* (producer) and `@toggld/node` (consumer) so the contract cannot drift.
+*
+* `version` is opaque and equality-compared (ADR-0005 phase 1); the ordered
+* `config_version` lands in this same field later without a wire change.
+*/
+/** A versioned full snapshot of one environment's resolved flag set. */
+const FlagSnapshot = Schema.Struct({
+	version: Schema.String,
+	flags: Schema.Array(Flag)
+});
+/** Server→client: the current snapshot (connect greeting and change pushes). */
+const SyncSnapshotMessage = Schema.Struct({
+	type: Schema.Literal("snapshot"),
+	version: Schema.String,
+	flags: Schema.Array(Flag)
+});
+/**
+* Every server→client sync-stream message. A single-member union today; the
+* `type` discriminant is the extension point.
+*/
+const SyncServerMessage = Schema.Union([SyncSnapshotMessage]);
+Schema.Struct({ type: Schema.Literal("resync") });
+//#endregion
 //#region src/internal/core.ts
 /**
-* The Effect core of the Toggld Node SDK — a remote-evaluation client over the
-* server's OFREP endpoints.
+* 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`. The SDK performs **no
-* local evaluation** — every call hits the flag API, which evaluates the flag
-* against the supplied context and returns the resolved value (OpenFeature
-* "remote evaluation"). Local in-process evaluation via `@toggld/engine` is a
-* later milestone (see ADR-0001).
+* 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, or a value whose type doesn't
-* match the requested getter — resolves to the caller's default value with the
-* details carrying `reason: "ERROR"` and an `errorCode`.
+* 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);
@@ -483,6 +768,18 @@ const errorDetails = (key, value, errorCode, errorMessage, flagMetadata = {}) =>
 	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. */
@@ -492,14 +789,7 @@ const codeFor = (e) => typeof e === "object" && e !== null && "_tag" in e && e._
 * compose it into your runtime, then `yield* ToggldClient` to evaluate flags.
 */
 var ToggldClient = class extends Context.Service()("@toggld/node/ToggldClient") {};
-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 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) }));
@@ -518,6 +808,108 @@ const make = (options) => Effect.gen(function* () {
 			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
+	};
+};
+/** 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 makeLocal = (options, http, mergedContext, timeout) => Effect.gen(function* () {
+	const transport = options.sync?.transport ?? "ws";
+	const pollIntervalMs = options.sync?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	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]))
+		};
+		return Effect.asVoid(Deferred.succeed(firstSnapshot, void 0));
+	});
+	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 = epoch;
+		const snapshot = yield* fetchSnapshot;
+		if (epoch !== before) return;
+		if (current !== void 0 && current.version === snapshot.version) return;
+		yield* adopt(snapshot);
+	});
+	const ticker = Effect.gen(function* () {
+		let delay = 250;
+		while (current === void 0) {
+			yield* pollOnce.pipe(Effect.ignore);
+			if (current !== 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 (current !== void 0 && current.version === message.version) return;
+		yield* 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);
+	const evaluate = (key, defaultValue, context) => Effect.sync(() => {
+		if (current === void 0) return errorDetails(key, defaultValue, "PROVIDER_NOT_READY", "No flag snapshot synced yet");
+		const flag = current.byKey.get(key);
+		if (flag === void 0) return errorDetails(key, defaultValue, "FLAG_NOT_FOUND", `Flag '${key}' not found`);
+		return resolutionDetails(key, evaluateFlag(flag, mergedContext(context)), defaultValue);
+	});
+	const evaluateAll = (context) => Effect.sync(() => {
+		if (current === void 0) return [];
+		const ctx = mergedContext(context);
+		return current.flags.map((flag) => resolutionDetails(flag.key, evaluateFlag(flag, ctx), null));
+	});
+	return {
+		ready: Deferred.await(firstSnapshot),
+		evaluate,
+		evaluateAll
+	};
+});
+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" ? 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;
@@ -526,6 +918,7 @@ const make = (options) => Effect.gen(function* () {
 	});
 	const valueOf = (details) => Effect.map(details, (d) => d.value);
 	return {
+		ready,
 		evaluate,
 		evaluateAll,
 		getBooleanDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "boolean", isBoolean),
@@ -540,10 +933,14 @@ const make = (options) => Effect.gen(function* () {
 });
 /** 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 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.
 */
-const layer = (options) => Layer.effect(ToggldClient, make(options)).pipe(Layer.provide(httpLayer(options.fetch)));
+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-DItF1mIU.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-Bx0PVoEm.mjs";
 export { ToggldClient, layer };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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-DItF1mIU.mjs";
 
 //#region src/index.d.ts
 /**
@@ -9,8 +9,19 @@ import { a as FlagMetadata, i as EvaluationContext, n as ToggldClientOptions, o
 declare class ToggldClient {
   #private;
   private constructor();
-  /** Create a client. Resolves once the underlying runtime is ready. */
+  /**
+   * Create a client. Resolves once the underlying runtime is ready — and, in
+   * local mode, once the first flag snapshot has synced (or `readyTimeoutMs`,
+   * default 5 s, has elapsed; the client then serves caller defaults with
+   * `PROVIDER_NOT_READY` while sync keeps retrying in the background).
+   */
   static create(options: ToggldClientOptions): Promise<ToggldClient>;
+  /**
+   * Resolves once the client has flag data to evaluate with (immediately in
+   * remote mode). Useful if `create` resolved on the ready timeout and you
+   * want to await sync explicitly.
+   */
+  ready(): Promise<void>;
   /** Resolve a flag, returning full details with an untyped (JSON) value. */
   evaluate(key: string, defaultValue: FlagValue, context?: EvaluationContext): Promise<EvaluationDetails<FlagValue>>;
   /** Resolve every flag for the environment in one request (OFREP bulk). */
@@ -27,4 +38,4 @@ declare class ToggldClient {
   close(): Promise<void>;
 }
 //#endregion
-export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type FlagMetadata, type FlagValue, type Reason, ToggldClient, type ToggldClientOptions };
+export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type EvaluationMode, type FlagMetadata, type FlagValue, type Reason, type SyncOptions, ToggldClient, type ToggldClientOptions };

package/dist/index.mjs

@@ -1,23 +1,27 @@
-import { n as layer, t as ToggldClient$1 } from "./core-zMjaOru1.mjs";
-import { ManagedRuntime } from "effect";
+import { n as layer, t as ToggldClient$1 } from "./core-Bx0PVoEm.mjs";
+import { Duration, Effect, ManagedRuntime } from "effect";
 //#region src/index.ts
 /**
 * `@toggld/node` — the default entry: a plain Promise API.
 *
-* Remote flag evaluation over the server's OFREP endpoints, with **no Effect in
-* any signature**. Internally it runs the Effect implementation from `./effect`
-* under a `ManagedRuntime`.
+* Flag evaluation with **no Effect in any signature**. Internally it runs the
+* Effect implementation from `./effect` under a `ManagedRuntime`.
 *
 * ```ts
 * import { ToggldClient } from "@toggld/node"
 *
-* const client = await ToggldClient.create({ sdkKey, endpoint })
+* // Local evaluation (recommended for long-lived servers): flag definitions
+* // sync in the background and every evaluation is in-process — microseconds,
+* // zero server requests.
+* const client = await ToggldClient.create({ sdkKey, endpoint, mode: "local" })
 * const on = await client.getBooleanValue("new-checkout", false, { targetingKey: "user-123" })
 * await client.close()
 * ```
 *
-* Evaluation never throws: any failure resolves to the supplied default value,
-* with the reason/error available via the `*Details` methods.
+* Omitting `mode` keeps the default **remote** evaluation (each call asks the
+* flag API over OFREP). Evaluation never throws: any failure resolves to the
+* supplied default value, with the reason/error available via the `*Details`
+* methods.
 */
 /**
 * A Toggld client backed by a private Effect runtime. Create one with {@link
@@ -31,10 +35,28 @@ var ToggldClient = class ToggldClient {
 		this.#runtime = runtime;
 		this.#client = client;
 	}
-	/** Create a client. Resolves once the underlying runtime is ready. */
+	/**
+	* Create a client. Resolves once the underlying runtime is ready — and, in
+	* local mode, once the first flag snapshot has synced (or `readyTimeoutMs`,
+	* default 5 s, has elapsed; the client then serves caller defaults with
+	* `PROVIDER_NOT_READY` while sync keeps retrying in the background).
+	*/
 	static async create(options) {
 		const runtime = ManagedRuntime.make(layer(options));
-		return new ToggldClient(runtime, await runtime.runPromise(ToggldClient$1));
+		const client = await runtime.runPromise(ToggldClient$1);
+		if (options.mode === "local") {
+			const readyTimeoutMs = options.sync?.readyTimeoutMs ?? 5e3;
+			await runtime.runPromise(client.ready.pipe(Effect.timeout(Duration.millis(readyTimeoutMs)), Effect.ignore));
+		}
+		return new ToggldClient(runtime, client);
+	}
+	/**
+	* Resolves once the client has flag data to evaluate with (immediately in
+	* remote mode). Useful if `create` resolved on the ready timeout and you
+	* want to await sync explicitly.
+	*/
+	ready() {
+		return this.#runtime.runPromise(this.#client.ready);
 	}
 	/** Resolve a flag, returning full details with an untyped (JSON) value. */
 	evaluate(key, defaultValue, context) {

package/dist/{types-RmWNnA7-.d.mts → types-DItF1mIU.d.mts}

@@ -34,20 +34,72 @@ type Reason = "STATIC" | "DEFAULT" | "TARGETING_MATCH" | "SPLIT" | "CACHED" | "D
 type ErrorCode = "PROVIDER_NOT_READY" | "PROVIDER_FATAL" | "FLAG_NOT_FOUND" | "PARSE_ERROR" | "TYPE_MISMATCH" | "TARGETING_KEY_MISSING" | "INVALID_CONTEXT" | "GENERAL";
 //#endregion
 //#region src/internal/types.d.ts
+/**
+ * How the client resolves flags.
+ *
+ * - `"remote"` — every evaluation is an HTTP request to the flag API's OFREP
+ *   endpoints; the server evaluates and returns the value.
+ * - `"local"` — the client backgrounds a **definition sync** (a snapshot fetch
+ *   plus a live WebSocket stream with polling fallback) and evaluates flags
+ *   **in-process** with the bundled engine: zero server requests per
+ *   evaluation, microsecond latency, identical resolutions to the server. The
+ *   mode for long-lived servers.
+ */
+type EvaluationMode = "remote" | "local";
+/** Tuning for the background definition sync (`mode: "local"`). */
+interface SyncOptions {
+  /**
+   * How updates reach the client.
+   *
+   * - `"ws"` (default) — a live WebSocket stream (`/sync/v1/stream`) pushes a
+   *   fresh snapshot on every change, with the snapshot poll below as a
+   *   safety net (it also serves runtimes where the stream is unavailable —
+   *   the client degrades to polling automatically).
+   * - `"poll"` — no stream; only the periodic snapshot poll.
+   */
+  readonly transport?: "ws" | "poll";
+  /**
+   * Interval between snapshot polls in milliseconds. Default `30000`. Until
+   * the first snapshot arrives, the client retries faster (exponential from
+   * 250 ms) so cold starts aren't gated on this interval.
+   */
+  readonly pollIntervalMs?: number;
+  /**
+   * How long `ToggldClient.create` waits for the first snapshot before
+   * resolving anyway, in milliseconds. Default `5000`. A client that isn't
+   * ready evaluates to caller defaults (`PROVIDER_NOT_READY`) while sync keeps
+   * retrying in the background.
+   */
+  readonly readyTimeoutMs?: number;
+  /**
+   * Custom `WebSocket` constructor for the stream transport. Defaults to the
+   * global `WebSocket` (Node ≥ 22). Useful for tests or proxies.
+   */
+  readonly webSocketConstructor?: typeof globalThis.WebSocket;
+}
 /** Configuration for a {@link https://toggld.io Toggld} client. */
 interface ToggldClientOptions {
   /**
    * An **evaluation** (or management) API key, sent as `Authorization: Bearer
    * <sdkKey>`. The key is scoped to one tenant + environment server-side, so a
-   * client always evaluates against exactly that environment.
+   * client always evaluates against exactly that environment. Local evaluation
+   * requires a secret key (`ffk_…`) — public browser tokens cannot read flag
+   * definitions.
    */
   readonly sdkKey: string;
   /**
    * Base URL of the flag API, e.g. `https://toggld-api.example.workers.dev` or
    * `http://localhost:3000` in local development. No trailing path — the client
-   * appends the OFREP routes (`/ofrep/v1/...`).
+   * appends the OFREP and sync routes (`/ofrep/v1/...`, `/sync/v1/...`).
    */
   readonly endpoint: string;
+  /**
+   * Evaluation mode. Defaults to `"remote"`; prefer `"local"` on long-lived
+   * servers. See {@link EvaluationMode}.
+   */
+  readonly mode?: EvaluationMode;
+  /** Background sync tuning for `mode: "local"`. Ignored in remote mode. */
+  readonly sync?: SyncOptions;
   /**
    * Attributes merged into the evaluation context of **every** request, under
    * any per-call context (per-call attributes win on key collision). Handy for
@@ -82,4 +134,4 @@ interface EvaluationDetails<T extends FlagValue> {
   readonly flagMetadata: FlagMetadata;
 }
 //#endregion
-export { FlagMetadata as a, EvaluationContext as i, ToggldClientOptions as n, FlagValue as o, ErrorCode as r, Reason as s, EvaluationDetails as t };
+export { ErrorCode as a, FlagValue as c, ToggldClientOptions as i, Reason as l, EvaluationMode as n, EvaluationContext as o, SyncOptions as r, FlagMetadata as s, EvaluationDetails as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toggld/node",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Toggld SDK for Node.js — local flag evaluation with a background definition sync. Plain Promise API by default; native Effect API via @toggld/node/effect.",
   "license": "Apache-2.0",
   "homepage": "https://toggld.io",
@@ -41,8 +41,11 @@
   },
   "devDependencies": {
     "tsdown": "^0.22.2",
+    "typescript": "5.8.3",
     "unrun": "^0.3.1",
+    "@toggld/engine": "0.1.0",
     "@toggld/schema": "0.1.0",
+    "@toggld/server": "0.1.0",
     "@toggld/spec": "0.1.0"
   },
   "scripts": {