@toggld/node 0.2.0 → 0.4.0

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

@@ -1,7 +1,10 @@
-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
+import { a as OfrepSuccess, i as OfrepFailure, n as SyncServerMessage, r as OfrepBulkResponse, t as FlagSnapshot } from "./src-B_M-Oix8.mjs";
+import { Context, Deferred, Duration, Effect, Layer, Schema, Semaphore } from "effect";
+import { readFile, watch } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import { Socket } from "effect/socket";
+// ../spec/src/index.ts
 /** True when `value` is assignable to a flag declared as `type`. */
 const valueMatchesType = (value, type) => {
 	switch (type) {
@@ -53,8 +56,7 @@ const Resolution = {
 		flagMetadata: args.flagMetadata ?? {}
 	})
 };
-//#endregion
-//#region ../engine/src/hash.ts
+// ../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
@@ -112,8 +114,7 @@ const BUCKET_SCALE = 1e4;
 const bucketFor = (flagKey, ruleId, subject) => {
 	return murmur3(`${flagKey}:${ruleId}:${subject}`) % BUCKET_SCALE;
 };
-//#endregion
-//#region ../engine/src/targeting.ts
+// ../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. */
@@ -149,8 +150,37 @@ const matchCondition = (condition, ctx) => {
 		}
 	}
 };
-/** A rule matches when every one of its conditions matches (logical AND). */
-const matchRule = (rule, ctx) => rule.conditions.every((c) => matchCondition(c, ctx));
+/**
+* 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
@@ -202,8 +232,7 @@ const deepEqual = (a, b) => {
 	}
 	return false;
 };
-//#endregion
-//#region ../engine/src/evaluate.ts
+// ../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
@@ -233,11 +262,15 @@ const serveVariant = (flag, variant, reason) => {
 *       - 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) => {
+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)) continue;
+		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({
@@ -251,468 +284,65 @@ const evaluateFlag = (flag, ctx) => {
 	}
 	return serveVariant(flag, flag.defaultVariant, "STATIC");
 };
-//#endregion
-//#region ../schema/src/audit.ts
-/**
-* Audit log wire contract (ADR-0009). Every management/control-plane mutation is
-* recorded as one append-only {@link AuditEvent}; a tenant reads its own trail
-* over `GET /api/v1/audit-log`. Evaluation (OFREP) reads are deliberately *not*
-* audited — this is a record of configuration *changes*, not traffic.
-*/
-/** Who performed the change. See the server's `Actor` for how each id is sourced. */
-const AuditActor = Schema.Struct({
-	type: Schema.Literals([
-		"apiKey",
-		"user",
-		"service"
-	]),
-	id: Schema.String
-});
-/**
-* Closed vocabulary of audited actions — a closed set (not free text) so filters
-* and downstream exports stay stable as resources are added. `flag.update` covers
-* both replace (PUT) and patch (PATCH); the before/after states show what moved.
-*/
-const AuditAction = Schema.Literals([
-	"flag.create",
-	"flag.update",
-	"flag.delete",
-	"environment.create",
-	"environment.delete",
-	"apiKey.create",
-	"apiKey.revoke",
-	"tenant.create",
-	"tenant.update"
-]);
-/** The kind of resource an event concerns; pairs with `resourceId`. */
-const AuditResourceType = Schema.Literals([
-	"flag",
-	"environment",
-	"apiKey",
-	"tenant"
-]);
-Schema.Struct({
-	id: Schema.String,
-	/** Owning tenant; null only for control-plane events (tenant provisioning). */
-	tenantId: Schema.NullOr(Schema.String),
-	/** The environment touched; null for tenant-wide / definition-level / control-plane events. */
-	environmentId: Schema.NullOr(Schema.String),
-	actor: AuditActor,
-	action: AuditAction,
-	resourceType: AuditResourceType,
-	/** Flag key, environment id, API-key id, or tenant id. */
-	resourceId: Schema.String,
-	before: Schema.NullOr(Schema.Unknown),
-	after: Schema.NullOr(Schema.Unknown),
-	/** Non-authoritative request context (request id, source ip, …); empty in v0. */
-	metadata: Schema.Record(Schema.String, Schema.Unknown),
-	/** ISO 8601 timestamp the change was recorded. */
-	occurredAt: Schema.String
-});
-//#endregion
-//#region ../schema/src/auth.ts
-/**
-* Authorization role carried by an API key.
-*
-* - `management` — full CRUD on the tenant's flags, plus evaluation.
-* - `evaluation` — read-only evaluation (OFREP) of the tenant's flags.
-*/
-const Role = Schema.Literals(["management", "evaluation"]);
-Schema.Struct({
-	id: Schema.String,
-	name: Schema.String,
-	createdAt: Schema.String,
-	/**
-	* Max number of flag *definitions* the tenant may hold; `null` = unlimited.
-	* The free tier is 10 (the DB column default). The flag API treats this as an
-	* opaque number — the web app owns the plan→limit mapping and pushes changes
-	* over the control plane (provision + PATCH). Enforced in `FlagService.create`.
-	*/
-	flagLimit: Schema.NullOr(Schema.Int)
-});
-Schema.Struct({
-	id: Schema.String,
-	tenantId: Schema.String,
-	/** Stable slug, unique within the tenant (e.g. `production`). */
-	key: Schema.String,
-	name: Schema.String,
-	createdAt: Schema.String
-});
-/** Body for creating an environment (POST /admin/v1/tenants/:tenantId/environments). */
-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.
-*/
-const ApiKeyInfo = Schema.Struct({
-	id: Schema.String,
-	tenantId: Schema.String,
-	/** The single environment this key is scoped to. */
-	environmentId: Schema.String,
-	name: Schema.optionalKey(Schema.String),
-	role: Role,
-	prefix: Schema.String,
-	createdAt: Schema.String
-});
-Schema.Struct({
-	...ApiKeyInfo.fields,
-	token: Schema.String
-});
-Schema.Struct({
-	id: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1))),
-	name: Schema.String.check(Schema.isMinLength(1)),
-	environments: Schema.optionalKey(Schema.Array(CreateEnvironmentInput)),
-	/** Flag cap for the new tenant; omitted → the free-tier default (10). */
-	flagLimit: Schema.optionalKey(Schema.Int)
-});
-Schema.Struct({
-	name: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1))),
-	flagLimit: Schema.optionalKey(Schema.NullOr(Schema.Int))
-});
-Schema.Struct({
-	role: Role,
-	name: Schema.optionalKey(Schema.String),
-	environment: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1)))
-});
-//#endregion
-//#region ../schema/src/value.ts
-/**
-* The OpenFeature flag value types. Every flag declares one of these; variant
-* values and resolved values are validated against it.
-*
-* @see https://openfeature.dev/specification/types
-*/
-const FlagType = Schema.Literals([
-	"boolean",
-	"string",
-	"number",
-	"object"
-]);
-/**
-* A resolved flag value. OpenFeature permits `boolean | string | number |
-* structure`; we store the union as JSON, which also covers arrays and null
-* for "object" typed flags.
-*/
-const FlagValue = Schema.Json;
-/**
-* Flag metadata: "a structure supporting the definition of arbitrary
-* properties, with keys of type string, and values of type boolean, string,
-* or number." (Requirement 2.2.10)
-*/
-const MetadataValue = Schema.Union([
-	Schema.String,
-	Schema.Finite,
-	Schema.Boolean
-]);
-const FlagMetadata = Schema.Record(Schema.String, MetadataValue);
-//#endregion
-//#region ../schema/src/context.ts
-/**
-* An OpenFeature evaluation context: an optional `targetingKey` "identifying
-* the subject of the flag evaluation" (Requirement 3.1.1) plus arbitrary
-* custom fields (Requirement 3.1.2). We accept any JSON-valued attributes.
-*/
-const EvaluationContext = Schema.Record(Schema.String, FlagValue);
-Schema.ErrorClass("FlagNotFound")({
-	_tag: Schema.tag("FlagNotFound"),
-	flagKey: Schema.String,
-	message: Schema.String
-});
-Schema.ErrorClass("FlagAlreadyExists")({
-	_tag: Schema.tag("FlagAlreadyExists"),
-	flagKey: Schema.String,
-	message: Schema.String
-});
-Schema.ErrorClass("FlagValidationError")({
-	_tag: Schema.tag("FlagValidationError"),
-	flagKey: Schema.String,
-	issues: Schema.Array(Schema.String),
-	message: Schema.String
-});
-Schema.ErrorClass("FlagLimitExceeded")({
-	_tag: Schema.tag("FlagLimitExceeded"),
-	/** The tenant's current flag cap. */
-	limit: Schema.Int,
-	/** How many flags the tenant has now (>= limit). */
-	current: Schema.Int,
-	message: Schema.String
-});
-Schema.ErrorClass("Unauthorized")({
-	_tag: Schema.tag("Unauthorized"),
-	message: Schema.String
-});
-Schema.ErrorClass("Forbidden")({
-	_tag: Schema.tag("Forbidden"),
-	message: Schema.String
-});
-Schema.ErrorClass("TenantNotFound")({
-	_tag: Schema.tag("TenantNotFound"),
-	tenantId: Schema.String,
-	message: Schema.String
-});
-Schema.ErrorClass("TenantAlreadyExists")({
-	_tag: Schema.tag("TenantAlreadyExists"),
-	tenantId: Schema.String,
-	message: Schema.String
-});
-Schema.ErrorClass("EnvironmentNotFound")({
-	_tag: Schema.tag("EnvironmentNotFound"),
-	environment: Schema.String,
-	message: Schema.String
-});
-Schema.ErrorClass("EnvironmentAlreadyExists")({
-	_tag: Schema.tag("EnvironmentAlreadyExists"),
-	environment: Schema.String,
-	message: Schema.String
-});
-Schema.ErrorClass("ApiKeyNotFound")({
-	_tag: Schema.tag("ApiKeyNotFound"),
-	keyId: Schema.String,
-	message: Schema.String
-});
-//#endregion
-//#region ../schema/src/flag.ts
-/**
-* Operators usable in a targeting condition. Comparisons coerce sensibly:
-* numeric operators require numbers, string operators require strings, and
-* `in`/`notIn` test membership in an array literal.
-*/
-const Operator = Schema.Literals([
-	"eq",
-	"ne",
-	"in",
-	"notIn",
-	"lt",
-	"lte",
-	"gt",
-	"gte",
-	"contains",
-	"startsWith",
-	"endsWith",
-	"exists",
-	"notExists"
-]);
-/**
-* A single targeting condition tested against an attribute of the evaluation
-* context (e.g. `targetingKey`, `email`, `plan`). All conditions in a rule are
-* ANDed together.
-*/
-const Condition = Schema.Struct({
-	attribute: Schema.String,
-	operator: Operator,
-	/** Comparison operand. Ignored for `exists`/`notExists`. */
-	value: Schema.optionalKey(FlagValue)
-});
-/** A weighted slice of a percentage rollout. */
-const Split = Schema.Struct({
-	variant: Schema.String,
-	/** Relative weight; the engine normalises weights across all splits. */
-	weight: Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0))
-});
-/** Serve a single fixed variant when the rule matches → `TARGETING_MATCH`. */
-const ServeVariant = Schema.Struct({
-	type: Schema.Literal("variant"),
-	variant: Schema.String
-});
-/**
-* Serve a deterministic percentage rollout when the rule matches → `SPLIT`.
-* Bucketing is consistent for a given subject (`bucketBy`, default
-* `targetingKey`) so a subject always lands in the same slice.
-*/
-const ServeRollout = Schema.Struct({
-	type: Schema.Literal("rollout"),
-	bucketBy: Schema.optionalKey(Schema.String),
-	splits: Schema.Array(Split)
-});
-const Serve = Schema.Union([ServeVariant, ServeRollout]);
-/** An ordered targeting rule. The first rule whose conditions all match wins. */
-const Rule = Schema.Struct({
-	id: Schema.String,
-	description: Schema.optionalKey(Schema.String),
-	/** ANDed conditions. An empty list always matches (useful as a catch-all). */
-	conditions: Schema.Array(Condition),
-	serve: Serve
-});
-/**
-* A feature flag definition.
-*
-* Evaluation order: if `enabled` is false → serve `offVariant` (default
-* `defaultVariant`) with reason `DISABLED`; otherwise walk `targeting` in
-* order and serve the first matching rule (`TARGETING_MATCH`/`SPLIT`); if no
-* rule matches, serve `defaultVariant` with reason `STATIC`.
-*/
-const Flag = Schema.Struct({
-	key: Schema.String,
-	name: Schema.optionalKey(Schema.String),
-	description: Schema.optionalKey(Schema.String),
-	type: FlagType,
-	enabled: Schema.Boolean,
-	/** Named values; every served variant name must be a key here. */
-	variants: Schema.Record(Schema.String, FlagValue),
-	/** Variant served on a normal evaluation with no targeting match. */
-	defaultVariant: Schema.String,
-	/** Variant served when the flag is disabled. Defaults to `defaultVariant`. */
-	offVariant: Schema.optionalKey(Schema.String),
-	targeting: Schema.Array(Rule),
-	metadata: FlagMetadata,
-	createdAt: Schema.String,
-	updatedAt: Schema.String
-});
-/**
-* Freeform organization labels for a flag (ADR-0008). A flag may carry any
-* number; they group/filter flags in the dashboard and have **no** effect on
-* evaluation. Deliberately separate from the spec `Flag` (and `metadata`) so
-* they never reach the OFREP wire or the engine.
-*/
-const Tags = Schema.Array(Schema.String.check(Schema.isMinLength(1)));
-Schema.Struct({
-	...Flag.fields,
-	tags: Tags
-});
-//#endregion
-//#region ../schema/src/resolution.ts
-/**
-* Resolution reasons. The provider "SHOULD populate the resolution details
-* structure's reason field with STATIC, DEFAULT, TARGETING_MATCH, SPLIT,
-* CACHED, DISABLED, UNKNOWN, STALE, ERROR or some other string."
-* (Requirement 2.2.5)
-*/
-const Reason = Schema.Literals([
-	"STATIC",
-	"DEFAULT",
-	"TARGETING_MATCH",
-	"SPLIT",
-	"CACHED",
-	"DISABLED",
-	"UNKNOWN",
-	"STALE",
-	"ERROR"
-]);
-/**
-* OpenFeature error codes.
-* @see https://openfeature.dev/specification/types
-*/
-const ErrorCode = Schema.Literals([
-	"PROVIDER_NOT_READY",
-	"PROVIDER_FATAL",
-	"FLAG_NOT_FOUND",
-	"PARSE_ERROR",
-	"TYPE_MISMATCH",
-	"TARGETING_KEY_MISSING",
-	"INVALID_CONTEXT",
-	"GENERAL"
-]);
-Schema.Struct({ context: Schema.optionalKey(EvaluationContext) });
-/** A successful single/bulk evaluation result. */
-const OfrepSuccess = Schema.Struct({
-	key: Schema.String,
-	value: FlagValue,
-	reason: Reason,
-	variant: Schema.optionalKey(Schema.String),
-	metadata: Schema.optionalKey(FlagMetadata)
-});
-/** A per-flag failure embedded in a bulk response. */
-const OfrepFailure = Schema.Struct({
-	key: Schema.String,
-	errorCode: ErrorCode,
-	errorDetails: Schema.optionalKey(Schema.String),
-	metadata: Schema.optionalKey(FlagMetadata)
-});
-/** Bulk evaluation response: a mixed list of successes and failures. */
-const OfrepBulkResponse = Schema.Struct({
-	flags: Schema.Array(Schema.Union([OfrepSuccess, OfrepFailure])),
-	metadata: Schema.optionalKey(FlagMetadata)
-});
-Schema.ErrorClass("OfrepFlagNotFound")({
-	key: Schema.String,
-	errorCode: Schema.Literal("FLAG_NOT_FOUND"),
-	errorDetails: Schema.optionalKey(Schema.String)
-});
-Schema.ErrorClass("OfrepEvaluationError")({
-	key: Schema.String,
-	errorCode: ErrorCode,
-	errorDetails: Schema.optionalKey(Schema.String)
-});
-Schema.Struct({
-	key: Schema.String.check(Schema.isMinLength(1)),
-	name: Schema.optionalKey(Schema.String),
-	description: Schema.optionalKey(Schema.String),
-	type: FlagType,
-	enabled: Schema.optionalKey(Schema.Boolean),
-	variants: Schema.Record(Schema.String, FlagValue),
-	defaultVariant: Schema.String,
-	offVariant: Schema.optionalKey(Schema.String),
-	targeting: Schema.optionalKey(Schema.Array(Rule)),
-	metadata: Schema.optionalKey(FlagMetadata),
-	/** Freeform organization labels (ADR-0008). Normalized server-side. */
-	tags: Schema.optionalKey(Tags)
-});
-Schema.Struct({
-	name: Schema.optionalKey(Schema.String),
-	description: Schema.optionalKey(Schema.String),
-	type: FlagType,
-	enabled: Schema.optionalKey(Schema.Boolean),
-	variants: Schema.Record(Schema.String, FlagValue),
-	defaultVariant: Schema.String,
-	offVariant: Schema.optionalKey(Schema.String),
-	targeting: Schema.optionalKey(Schema.Array(Rule)),
-	metadata: Schema.optionalKey(FlagMetadata),
-	tags: Schema.optionalKey(Tags)
-});
-Schema.Struct({
-	name: Schema.optionalKey(Schema.String),
-	description: Schema.optionalKey(Schema.String),
-	type: Schema.optionalKey(FlagType),
-	enabled: Schema.optionalKey(Schema.Boolean),
-	variants: Schema.optionalKey(Schema.Record(Schema.String, FlagValue)),
-	defaultVariant: Schema.optionalKey(Schema.String),
-	offVariant: Schema.optionalKey(Schema.String),
-	targeting: Schema.optionalKey(Schema.Array(Rule)),
-	metadata: Schema.optionalKey(FlagMetadata),
-	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)
+// src/internal/telemetry.ts
+const startTelemetry = (http, options) => Effect.gen(function* () {
+	const instanceId = crypto.randomUUID();
+	const lock = yield* Semaphore.make(1);
+	const interval = options.telemetry === false ? 3e4 : options.telemetry?.flushIntervalMs ?? 3e4;
+	const timeout = Duration.millis(options.timeoutMs ?? 5e3);
+	let cells = /* @__PURE__ */ new Map();
+	let pending = [];
+	const flush = lock.withPermit(Effect.gen(function* () {
+		for (let pass = 0; pass < 2; pass++) {
+			if (pending.length === 0) {
+				const rollups = [...cells.values()];
+				cells = /* @__PURE__ */ new Map();
+				for (let i = 0; i < rollups.length; i += 1e3) pending.push({
+					sdkInstanceId: instanceId,
+					windowId: crypto.randomUUID(),
+					rollups: rollups.slice(i, i + 1e3)
+				});
+			}
+			while (pending.length > 0) {
+				if (!(yield* Effect.gen(function* () {
+					const response = yield* http.execute(HttpClientRequest.post("/v1/telemetry").pipe(HttpClientRequest.bodyJsonUnsafe(pending[0])));
+					return response.status >= 200 && response.status < 300;
+				}).pipe(Effect.timeout(timeout), Effect.catchCause(() => Effect.succeed(false))))) return;
+				pending.shift();
+			}
+		}
+	}));
+	yield* Effect.addFinalizer(() => flush.pipe(Effect.timeout(timeout), Effect.catchCause(() => Effect.void)));
+	yield* Effect.forkScoped(Effect.forever(Effect.sleep(Duration.millis(Number.isFinite(interval) && interval > 0 ? interval : 3e4)).pipe(Effect.andThen(flush))));
+	return {
+		flush,
+		record: (flagKey, resolution) => {
+			if (flagKey.length === 0 || flagKey.length > 256 || (resolution.variant?.length ?? 0) > 256) return;
+			const variant = resolution.variant ?? "";
+			const bucketStart = (/* @__PURE__ */ new Date(Math.floor(Date.now() / 6e4) * 6e4)).toISOString();
+			const key = JSON.stringify([
+				flagKey,
+				variant,
+				resolution.reason,
+				bucketStart
+			]);
+			const cell = cells.get(key);
+			if (cell) {
+				if (cell.count < 1e9) cells.set(key, {
+					...cell,
+					count: cell.count + 1
+				});
+			} else if (cells.size < 1e4) cells.set(key, {
+				flagKey,
+				variant,
+				reason: resolution.reason,
+				bucketStart,
+				count: 1
+			});
+		}
+	};
 });
-/**
-* 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
+// src/internal/core.ts
 /**
 * The Effect core of the Toggld Node SDK.
 *
@@ -766,19 +396,19 @@ const errorDetails = (key, value, errorCode, errorMessage, flagMetadata = {}) =>
 	reason: "ERROR",
 	errorCode,
 	errorMessage,
-	flagMetadata
+	flagMetadata: { ...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,
+	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
+	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);
@@ -814,6 +444,7 @@ const makeRemote = (http, mergedContext, timeout) => {
 		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);
@@ -821,9 +452,7 @@ const toStreamUrl = (endpoint) => {
 	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;
+const makeSnapshotStore = (mergedContext, record) => Effect.gen(function* () {
 	let current;
 	let epoch = 0;
 	const firstSnapshot = yield* Deferred.make();
@@ -832,10 +461,62 @@ const makeLocal = (options, http, mergedContext, timeout) => Effect.gen(function
 		current = {
 			version: snapshot.version,
 			flags: snapshot.flags,
-			byKey: new Map(snapshot.flags.map((f) => [f.key, f]))
+			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);
+		const resolution = evaluateFlag(flag, ctx, memberOf(state, ctx));
+		record(key, resolution);
+		return resolutionDetails(key, resolution, 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) => {
+			const resolution = evaluateFlag(flag, ctx, isMemberOf);
+			record(flag.key, resolution);
+			return resolutionDetails(flag.key, resolution, 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, {
@@ -844,17 +525,17 @@ const makeLocal = (options, http, mergedContext, timeout) => Effect.gen(function
 		});
 	}).pipe(Effect.timeout(timeout));
 	const pollOnce = Effect.gen(function* () {
-		const before = epoch;
+		const before = store.epoch();
 		const snapshot = yield* fetchSnapshot;
-		if (epoch !== before) return;
-		if (current !== void 0 && current.version === snapshot.version) return;
-		yield* adopt(snapshot);
+		if (store.epoch() !== before) return;
+		if (store.version() === snapshot.version) return;
+		yield* store.adopt(snapshot);
 	});
 	const ticker = Effect.gen(function* () {
 		let delay = 250;
-		while (current === void 0) {
+		while (store.version() === void 0) {
 			yield* pollOnce.pipe(Effect.ignore);
-			if (current !== void 0) break;
+			if (store.version() !== void 0) break;
 			yield* Effect.sleep(Duration.millis(delay));
 			delay = Math.min(delay * 2, 5e3);
 		}
@@ -863,20 +544,25 @@ const makeLocal = (options, http, mergedContext, timeout) => Effect.gen(function
 	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);
+		if (store.version() === message.version) return;
+		yield* store.adopt(message);
 	}).pipe(Effect.ignore);
-	const streamUrl = toStreamUrl(options.endpoint);
+	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}`],
+			protocols: [SYNC_PROTOCOL, `${SYNC_BEARER_PROTOCOL_PREFIX}${options.sdkKey ?? ""}`],
 			openTimeout: timeout
 		});
 		yield* Effect.forever(Effect.gen(function* () {
-			yield* socket.runRaw(handleMessage, { onOpen: Effect.sync(() => {
+			yield* Effect.scoped(Effect.gen(function* () {
+				const pull = yield* Socket.readerString(socket);
 				consecutiveFailures = 0;
-			}) }).pipe(Effect.ignore);
+				while (true) {
+					const messages = yield* pull;
+					for (const message of messages) yield* handleMessage(message);
+				}
+			})).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)));
@@ -884,32 +570,114 @@ const makeLocal = (options, http, mergedContext, timeout) => Effect.gen(function
 	});
 	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);
+});
+/**
+* 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 json = yield* Effect.tryPromise(async () => JSON.parse(await readFile(path, "utf8")));
+		const snapshot = yield* decodeSnapshot(json);
+		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 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));
+	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));
+		}
 	});
-	return {
-		ready: Deferred.await(firstSnapshot),
-		evaluate,
-		evaluateAll
-	};
+	yield* Effect.forkScoped(watchLoop, { startImmediately: true });
+	yield* Effect.forkScoped(ticker);
+});
+/**
+* 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, record) => Effect.gen(function* () {
+	const store = yield* makeSnapshotStore(mergedContext, record);
+	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 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);
+	const local = options.mode === "local" || resolveFilePath(options) !== void 0;
+	const telemetry = local && resolveFilePath(options) === void 0 && options.telemetry !== false ? yield* startTelemetry(http, options) : {
+		record: (_key, _resolution) => {},
+		flush: Effect.void
+	};
+	const { evaluate, evaluateAll, ready } = local ? yield* makeLocal(options, http, mergedContext, timeout, telemetry.record) : 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;
@@ -919,6 +687,7 @@ const make = (options) => Effect.gen(function* () {
 	const valueOf = (details) => Effect.map(details, (d) => d.value);
 	return {
 		ready,
+		flushTelemetry: telemetry.flush,
 		evaluate,
 		evaluateAll,
 		getBooleanDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "boolean", isBoolean),
@@ -934,7 +703,7 @@ 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;
+const webSocketLayer = (ctor) => ctor ? Layer.succeed(Socket.WebSocketConstructor, (url, options) => new ctor(url, typeof options === "object" && !Array.isArray(options) ? options.protocols : options)) : 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
@@ -942,5 +711,4 @@ const webSocketLayer = (ctor) => ctor ? Layer.succeed(Socket.WebSocketConstructo
 * 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 };