@toggld/node 0.2.0 → 0.3.0

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

@@ -1,4 +1,7 @@
+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
@@ -149,8 +152,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
@@ -233,11 +265,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({
@@ -252,466 +288,6 @@ 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)
-});
-/**
-* 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.
@@ -814,6 +390,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 +398,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) => Effect.gen(function* () {
 	let current;
 	let epoch = 0;
 	const firstSnapshot = yield* Deferred.make();
@@ -832,10 +407,56 @@ 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);
+		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, {
@@ -844,17 +465,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,14 +484,14 @@ 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* () {
@@ -884,32 +505,109 @@ 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 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 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(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 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 { 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;