@sdxc/flags-engine 0.0.0-pre.1

package/dist/lib/hash.js

@@ -0,0 +1,74 @@
+/**
+ * MurmurHash3 x86 32-bit at seed 0, the hash a percentage split buckets a
+ * subject with. The reference engine hashes the same way, so a rollout
+ * percentage written here selects the same subjects it selects there.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Held for the life of the module so bucketing a subject allocates only the
+ * byte array it hashes.
+ */
+const TEXT_ENCODER = new TextEncoder();
+/**
+ * Hashes a subject string to an unsigned 32-bit integer, spread evenly enough
+ * that a ten percent bucket holds ten percent of subjects. The string is hashed
+ * as its UTF-8 bytes, so a subject outside ASCII lands where the reference puts it.
+ *
+ * @param input The subject string, already assembled from seed and context field.
+ * @returns A value in `[0, 2^32)`.
+ * @example murmurHash3("welcome-banneruser-42") // 2364819184
+ */
+export function murmurHash3(input) {
+    let bytes = TEXT_ENCODER.encode(input);
+    let tailLength = bytes.length % 4;
+    let blockEnd = bytes.length - tailLength;
+    let hash = 0;
+    for (let index = 0; index < blockEnd; index += 4) {
+        hash = mixBlock(hash, readBlock(bytes, index));
+    }
+    hash ^= scramble(readTail(bytes, blockEnd, tailLength));
+    hash ^= bytes.length;
+    return avalanche(hash) >>> 0;
+}
+/** Rotates within 32 bits, which is where the algorithm's diffusion comes from. */
+function rotateLeft(value, bits) {
+    return (value << bits) | (value >>> (32 - bits));
+}
+/** Spreads one word's bits before it reaches the running hash. */
+function scramble(block) {
+    return Math.imul(rotateLeft(Math.imul(block, 0xcc_9e_2d_51), 15), 0x1b_87_35_93);
+}
+/** Folds one whole word into the running hash, ordering-sensitively. */
+function mixBlock(hash, block) {
+    return (Math.imul(rotateLeft(hash ^ scramble(block), 13), 5) + 0xe6_54_6b_64) | 0;
+}
+/** Finishes the hash so every input bit reaches every output bit. */
+function avalanche(hash) {
+    let mixed = Math.imul(hash ^ (hash >>> 16), 0x85_eb_ca_6b);
+    mixed = Math.imul(mixed ^ (mixed >>> 13), 0xc2_b2_ae_35);
+    return mixed ^ (mixed >>> 16);
+}
+/** Reads a whole word little-endian, the byte order the algorithm is defined in. */
+function readBlock(bytes, start) {
+    return ((bytes[start] ?? 0) |
+        ((bytes[start + 1] ?? 0) << 8) |
+        ((bytes[start + 2] ?? 0) << 16) |
+        ((bytes[start + 3] ?? 0) << 24));
+}
+/**
+ * Packs the trailing bytes that do not fill a word into one, keeping their
+ * little-endian positions so a one-byte tail differs from the same byte in
+ * second position. A length of zero answers with zero, which mixes into nothing.
+ */
+function readTail(bytes, start, length) {
+    let block = 0;
+    if (length > 2)
+        block ^= (bytes[start + 2] ?? 0) << 16;
+    if (length > 1)
+        block ^= (bytes[start + 1] ?? 0) << 8;
+    if (length > 0)
+        block ^= bytes[start] ?? 0;
+    return block;
+}

package/dist/lib/path.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Reads the dotted path a targeting condition names out of an evaluation
+ * context. A rule written against a field the caller did not send has to see
+ * nothing there rather than fail, so every miss answers with `undefined`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { EvaluationContext } from "@sdxc/flags";
+import type { JSONValue } from "@sdxc/types";
+/** Whatever a context field may hold, plus the absence a miss answers with. */
+export type ContextValue = Date | JSONValue | undefined;
+/**
+ * Walks `path` segment by segment, so `plan.tier` reads a nested structure,
+ * `country` a scalar and `roles.0` an array element. Every dot separates, so a
+ * field is addressed by the shape it sits inside.
+ *
+ * @param context The merged context an evaluation was given.
+ * @param path A dotted path; an empty one resolves to nothing.
+ * @returns The value at the path, or `undefined` when it resolves to nothing; a
+ * field explicitly holding `null` reads back as `null`.
+ * @example read({ plan: { tier: "pro" } }, "plan.tier") // "pro"
+ */
+export declare function read(context: EvaluationContext, path: string): ContextValue;

package/dist/lib/path.js

@@ -0,0 +1,49 @@
+/**
+ * Reads the dotted path a targeting condition names out of an evaluation
+ * context. A rule written against a field the caller did not send has to see
+ * nothing there rather than fail, so every miss answers with `undefined`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** A canonical array index: no sign, no leading zero, so `roles.01` reads nothing. */
+const ARRAY_INDEX = /^(?:0|[1-9]\d*)$/;
+/**
+ * Walks `path` segment by segment, so `plan.tier` reads a nested structure,
+ * `country` a scalar and `roles.0` an array element. Every dot separates, so a
+ * field is addressed by the shape it sits inside.
+ *
+ * @param context The merged context an evaluation was given.
+ * @param path A dotted path; an empty one resolves to nothing.
+ * @returns The value at the path, or `undefined` when it resolves to nothing; a
+ * field explicitly holding `null` reads back as `null`.
+ * @example read({ plan: { tier: "pro" } }, "plan.tier") // "pro"
+ */
+export function read(context, path) {
+    if (path === "")
+        return undefined;
+    let current = context;
+    for (let segment of path.split("."))
+        current = step(current, segment);
+    return current;
+}
+/**
+ * Descends one segment, answering with nothing whenever the value in hand has
+ * no such member — a primitive, an array under a non-index segment, or an
+ * object without the key.
+ */
+function step(value, segment) {
+    if (Array.isArray(value)) {
+        return ARRAY_INDEX.test(segment) ? value[Number(segment)] : undefined;
+    }
+    if (!isTraversable(value))
+        return undefined;
+    return Object.hasOwn(value, segment) ? value[segment] : undefined;
+}
+/**
+ * Recognizes the structures a path descends into, which keeps a context field
+ * carrying a `Date` a value a condition compares whole.
+ */
+function isTraversable(value) {
+    return typeof value === "object" && value !== null && !(value instanceof Date);
+}

package/dist/lib/split.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which arm of a percentage split a subject lands in, from a hash of that
+ * subject and nothing else, so a rollout covers the same people on every
+ * request, in every isolate, for as long as the weights stay put.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { EvaluationContext } from "@sdxc/flags";
+import type { Result } from "@sdxc/result";
+import type { Split } from "../definition.js";
+/**
+ * Puts a subject in one arm of a split, hashing the seed — or the flag key,
+ * which is what makes two flags at ten percent cover different tenths — with
+ * the subject read out of the context.
+ *
+ * @param split The weights to spread subjects across, and where to read one from.
+ * @param flagKey Mixed into the hash for a split that names no `seed`.
+ * @param context The merged context an evaluation was given.
+ * @returns The variant that won the bucket, or a failure when the field the
+ * split buckets on carries nothing to hash, which the caller reports as
+ * `TARGETING_KEY_MISSING` rather than serving an arm nobody was assigned to.
+ * @example selectVariant({ weights: { on: 10, off: 90 } }, "beta", { targetingKey: "u-1" })
+ */
+export declare function selectVariant(split: Split, flagKey: string, context: EvaluationContext): Result<string, Error>;

package/dist/lib/split.js

@@ -0,0 +1,64 @@
+/**
+ * Which arm of a percentage split a subject lands in, from a hash of that
+ * subject and nothing else, so a rollout covers the same people on every
+ * request, in every isolate, for as long as the weights stay put.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { murmurHash3 } from "./hash.js";
+import { read } from "./path.js";
+/** Where a split reads its subject from when it names no field of its own. */
+const SUBJECT_FIELD = "targetingKey";
+/** The width of the hash the bucket is scaled down from by a multiply-high. */
+const HASH_BITS = 32n;
+/**
+ * Puts a subject in one arm of a split, hashing the seed — or the flag key,
+ * which is what makes two flags at ten percent cover different tenths — with
+ * the subject read out of the context.
+ *
+ * @param split The weights to spread subjects across, and where to read one from.
+ * @param flagKey Mixed into the hash for a split that names no `seed`.
+ * @param context The merged context an evaluation was given.
+ * @returns The variant that won the bucket, or a failure when the field the
+ * split buckets on carries nothing to hash, which the caller reports as
+ * `TARGETING_KEY_MISSING` rather than serving an arm nobody was assigned to.
+ * @example selectVariant({ weights: { on: 10, off: 90 } }, "beta", { targetingKey: "u-1" })
+ */
+export function selectVariant(split, flagKey, context) {
+    let field = split.by ?? SUBJECT_FIELD;
+    let subject = read(context, field);
+    if (!isSubject(subject)) {
+        return failure(new Error(`The context carries no "${field}" to bucket on`));
+    }
+    let weights = orderedWeights(split.weights);
+    let total = weights.reduce((sum, [, weight]) => sum + weight, 0);
+    let hash = murmurHash3(`${split.seed ?? flagKey}${subject}`);
+    let bucket = Number((BigInt(hash) * BigInt(total)) >> HASH_BITS);
+    let cumulative = 0;
+    for (let [variant, weight] of weights) {
+        cumulative += weight;
+        if (bucket < cumulative)
+            return success(variant);
+    }
+    return failure(new Error(`The split on "${flagKey}" declares no weight above zero`));
+}
+/**
+ * Recognizes the values a subject string can be built from, so an account id
+ * buckets the same whether the caller sent it as a number or as text, and a
+ * structure is reported as no subject instead of hashing as one.
+ */
+function isSubject(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/**
+ * Walks the arms in variant-name order, which is the only order two isolates
+ * are guaranteed to agree on: a store, an editor or a JSON round trip is free
+ * to hand the same weights back with their keys in another sequence.
+ */
+function orderedWeights(weights) {
+    return Object.keys(weights)
+        .sort()
+        .map((variant) => [variant, weights[variant] ?? 0]);
+}

package/dist/parse.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Turns a stored definition set into the snapshot the engine evaluates
+ * against. Each flag is parsed on its own, so a mistyped rule costs the flag
+ * someone just edited and every sibling in the set still resolves.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { FlagSnapshot } from "./snapshot.js";
+import type { StoredFlagSet } from "./store/index.js";
+/**
+ * Reads a stored set into the snapshot evaluation runs against, answering for
+ * any input at all: a flag that cannot be parsed lands in `failures` under its
+ * own key with the reason, and every other flag lands in `flags` ready to
+ * evaluate.
+ *
+ * @param stored The set as a `FlagStore` handed it over, validated by nobody yet.
+ * @returns A snapshot stamped with the time it was built and the store's revision.
+ *
+ * @example
+ * let snapshot = parseFlagSet({ flags: { beta: { variants: { on: true } } } });
+ */
+export declare function parseFlagSet(stored: StoredFlagSet): FlagSnapshot;

package/dist/parse.js

@@ -0,0 +1,200 @@
+/**
+ * Turns a stored definition set into the snapshot the engine evaluates
+ * against. Each flag is parsed on its own, so a mistyped rule costs the flag
+ * someone just edited and every sibling in the set still resolves.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, isSuccess, success, wrap } from "@sdxc/result";
+import * as s from "remix/data-schema";
+import { CONDITION_SCHEMA, FLAG_DEFINITION_SCHEMA } from "./schema.js";
+/** Names the position an issue was raised at, whichever form the segment takes. */
+function segmentKey(segment) {
+    return String(typeof segment === "object" ? segment.key : segment);
+}
+/**
+ * Reads a value against a schema and reports the refusal as one message, so
+ * every failure in this module is an `Error` a snapshot can record verbatim.
+ */
+function parseInto(schema, value) {
+    let result = s.parseSafe(schema, value);
+    if (result.success)
+        return success(result.value);
+    let message = result.issues
+        .map((issue) => {
+        let path = (issue.path ?? []).map(segmentKey).join(".");
+        return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+    return failure(new Error(message.length > 0 ? message : "Expected a flag definition"));
+}
+/** Reads the entries of whatever a store handed over, treating anything else as empty. */
+function entriesOf(value) {
+    if (typeof value !== "object" || value === null)
+        return [];
+    return Object.entries(value);
+}
+/**
+ * Reads the segment map one entry at a time. A segment that does not parse is
+ * absent from the result, which reaches the flags referencing it as an unknown
+ * name and leaves the rest of the set untouched.
+ */
+function readSegments(segments) {
+    let declared = new Map();
+    for (let [name, value] of entriesOf(segments)) {
+        let parsed = parseInto(CONDITION_SCHEMA, value);
+        if (isSuccess(parsed))
+            declared.set(name, parsed.data);
+    }
+    return declared;
+}
+/**
+ * Resolves one segment to the condition it stands for, memoizing it so twenty
+ * flags naming it share one compiled tree. `visiting` holds the chain currently
+ * being walked, which is what turns a cycle into a failure here rather than an
+ * infinite walk on the first request that reaches it.
+ */
+function resolveSegment(name, declared, resolved, visiting) {
+    let already = resolved.get(name);
+    if (already !== undefined)
+        return success(already);
+    if (visiting.has(name)) {
+        return failure(new Error(`Segment "${name}" takes part in a reference cycle`));
+    }
+    let condition = declared.get(name);
+    if (condition === undefined)
+        return failure(new Error(`Unknown segment "${name}"`));
+    visiting.add(name);
+    let compiled = compileCondition(condition, declared, resolved, visiting);
+    visiting.delete(name);
+    if (isFailure(compiled))
+        return compiled;
+    resolved.set(name, compiled.data);
+    return compiled;
+}
+/**
+ * Compiles the work evaluation would otherwise repeat: a pattern becomes an
+ * expression the `v` flag accepts, and a segment carries the condition it
+ * names. Every other operator is already in its evaluable form.
+ */
+function compileCondition(condition, declared, resolved, visiting) {
+    switch (condition.op) {
+        case "all":
+        case "any": {
+            let of = [];
+            for (let member of condition.of) {
+                let compiled = compileCondition(member, declared, resolved, visiting);
+                if (isFailure(compiled))
+                    return compiled;
+                of.push(compiled.data);
+            }
+            if (condition.op === "all")
+                return success({ op: "all", of });
+            return success({ op: "any", of });
+        }
+        case "not": {
+            let compiled = compileCondition(condition.of, declared, resolved, visiting);
+            if (isFailure(compiled))
+                return compiled;
+            return success({ op: "not", of: compiled.data });
+        }
+        case "matches": {
+            let pattern = wrap(() => new RegExp(condition.pattern, "v"));
+            if (isFailure(pattern)) {
+                return failure(new Error(`Pattern ${JSON.stringify(condition.pattern)} does not compile`, {
+                    cause: pattern.error,
+                }));
+            }
+            return success({ op: "matches", field: condition.field, pattern: pattern.data });
+        }
+        case "segment": {
+            let segment = resolveSegment(condition.name, declared, resolved, visiting);
+            if (isFailure(segment))
+                return segment;
+            return success({ op: "segment", name: condition.name, of: segment.data });
+        }
+        default:
+            return success(condition);
+    }
+}
+/**
+ * Checks that a rule can only select a value the flag holds, so evaluation
+ * reaches a variant lookup that hits rather than a reason table entry for a
+ * name nobody declared.
+ */
+function checkServe(serve, variants) {
+    if (typeof serve === "string") {
+        if (variants.has(serve))
+            return success(serve);
+        return failure(new Error(`Rule serves "${serve}", which the flag does not declare`));
+    }
+    for (let name of Object.keys(serve.weights)) {
+        if (variants.has(name))
+            continue;
+        return failure(new Error(`Split weight "${name}" does not name a declared variant`));
+    }
+    return success(serve);
+}
+/**
+ * Parses one flag and compiles its rules. Every refusal here is the whole flag,
+ * because a definition half of whose rules were dropped would resolve subjects
+ * to variants its author never chose.
+ */
+function compileFlag(key, value, declared, resolved) {
+    let parsed = parseInto(FLAG_DEFINITION_SCHEMA, value);
+    if (isFailure(parsed))
+        return parsed;
+    let definition = parsed.data;
+    let variants = new Map(Object.entries(definition.variants));
+    if (definition.defaultVariant !== undefined && !variants.has(definition.defaultVariant)) {
+        let name = definition.defaultVariant;
+        return failure(new Error(`defaultVariant "${name}" is not a declared variant`));
+    }
+    let targeting = [];
+    for (let rule of definition.targeting ?? []) {
+        let when = compileCondition(rule.when, declared, resolved, new Set());
+        if (isFailure(when))
+            return when;
+        let serve = checkServe(rule.serve, variants);
+        if (isFailure(serve))
+            return serve;
+        targeting.push({ when: when.data, serve: serve.data });
+    }
+    return success({
+        key,
+        variants,
+        defaultVariant: definition.defaultVariant,
+        state: definition.state ?? "enabled",
+        targeting,
+        metadata: definition.metadata,
+    });
+}
+/**
+ * Reads a stored set into the snapshot evaluation runs against, answering for
+ * any input at all: a flag that cannot be parsed lands in `failures` under its
+ * own key with the reason, and every other flag lands in `flags` ready to
+ * evaluate.
+ *
+ * @param stored The set as a `FlagStore` handed it over, validated by nobody yet.
+ * @returns A snapshot stamped with the time it was built and the store's revision.
+ *
+ * @example
+ * let snapshot = parseFlagSet({ flags: { beta: { variants: { on: true } } } });
+ */
+export function parseFlagSet(stored) {
+    let declared = readSegments(stored.segments);
+    let resolved = new Map();
+    for (let name of declared.keys())
+        resolveSegment(name, declared, resolved, new Set());
+    let flags = new Map();
+    let failures = new Map();
+    for (let [key, value] of entriesOf(stored.flags)) {
+        let compiled = compileFlag(key, value, declared, resolved);
+        if (isFailure(compiled))
+            failures.set(key, { key, message: compiled.error.message });
+        else
+            flags.set(key, compiled.data);
+    }
+    return { flags, failures, segments: resolved, version: stored.version, createdAt: Date.now() };
+}

package/dist/provider/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The adapter that makes an engine answer as a flag provider: a lifecycle over
+ * `load`, four resolvers over `evaluate`, and the status an application already
+ * subscribes to. It is the one module here that knows OpenFeature.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { EvaluationContext, ProviderMetadata, ResolutionDetails } from "@sdxc/flags";
+import type { Provider } from "@sdxc/flags/provider";
+import type { Result } from "@sdxc/result";
+import type { JSONValue } from "@sdxc/types";
+import { ProviderEvents } from "@sdxc/flags/provider";
+import type { Engine } from "../engine.js";
+import type { FlagSnapshot } from "../snapshot.js";
+import type { FlagStoreError } from "../store/index.js";
+/**
+ * Resolves flags through an engine the caller builds and reloads, so one
+ * snapshot serves this provider and whatever else evaluates against the same
+ * engine, and an application registers a whole rule set as one provider.
+ *
+ * @example
+ * let provider = new EngineProvider(createEngine({ store: new WorkerKVFlagStore(env.FLAGS) }));
+ */
+export declare class EngineProvider implements Provider {
+    #private;
+    readonly metadata: ProviderMetadata;
+    readonly events: ProviderEvents;
+    /**
+     * @param engine The engine every resolution reads, loaded by `initialize` and
+     * reloaded by `refresh`.
+     */
+    constructor(engine: Engine);
+    /**
+     * Reads the definitions once, so every resolution that follows walks memory,
+     * and announces readiness before it returns.
+     *
+     * @throws ProviderError When the store could not hand its set over, which is a
+     * configuration failure announced on the status channel first.
+     */
+    initialize(_context?: EvaluationContext, _domain?: string): Promise<void>;
+    /**
+     * Reads the definitions again, on whatever schedule the caller keeps, and
+     * names every key either the outgoing set or the incoming one answers for, so
+     * a listener caching per key drops both sides of a whole-set replacement.
+     *
+     * @returns The snapshot now held, or why the store could not hand its set over.
+     */
+    refresh(): Promise<Result<FlagSnapshot, FlagStoreError>>;
+    resolveBoolean(key: string, defaultValue: boolean, context?: EvaluationContext): ResolutionDetails<boolean>;
+    resolveString(key: string, defaultValue: string, context?: EvaluationContext): ResolutionDetails<string>;
+    resolveNumber(key: string, defaultValue: number, context?: EvaluationContext): ResolutionDetails<number>;
+    resolveObject(key: string, defaultValue: JSONValue, context?: EvaluationContext): ResolutionDetails<JSONValue>;
+}

package/dist/provider/index.js

@@ -0,0 +1,117 @@
+/**
+ * The adapter that makes an engine answer as a flag provider: a lifecycle over
+ * `load`, four resolvers over `evaluate`, and the status an application already
+ * subscribes to. It is the one module here that knows OpenFeature.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { ProviderError, ProviderEvents } from "@sdxc/flags/provider";
+import { isFailure } from "@sdxc/result";
+/** What a store's own failure is called once it reaches the evaluation surface. */
+const STORE_ERROR_CODES = {
+    unavailable: "GENERAL",
+    invalid_value: "PARSE_ERROR",
+};
+/**
+ * Resolves flags through an engine the caller builds and reloads, so one
+ * snapshot serves this provider and whatever else evaluates against the same
+ * engine, and an application registers a whole rule set as one provider.
+ *
+ * @example
+ * let provider = new EngineProvider(createEngine({ store: new WorkerKVFlagStore(env.FLAGS) }));
+ */
+export class EngineProvider {
+    metadata = { name: "flags-engine" };
+    events = new ProviderEvents();
+    #engine;
+    /**
+     * Whether the status channel has been told the definitions aged, so one aging
+     * is one announcement and the reload that ends it says so once.
+     */
+    #announced = false;
+    /**
+     * @param engine The engine every resolution reads, loaded by `initialize` and
+     * reloaded by `refresh`.
+     */
+    constructor(engine) {
+        this.#engine = engine;
+    }
+    /**
+     * Reads the definitions once, so every resolution that follows walks memory,
+     * and announces readiness before it returns.
+     *
+     * @throws ProviderError When the store could not hand its set over, which is a
+     * configuration failure announced on the status channel first.
+     */
+    async initialize(_context = {}, _domain) {
+        let result = await this.#engine.load();
+        if (isFailure(result)) {
+            let errorCode = STORE_ERROR_CODES[result.error.code];
+            let message = result.error.message;
+            this.events.emit("PROVIDER_ERROR", { errorCode, message });
+            throw new ProviderError(errorCode, message, { cause: result.error });
+        }
+        this.#announced = false;
+        this.events.emit("PROVIDER_READY");
+    }
+    /**
+     * Reads the definitions again, on whatever schedule the caller keeps, and
+     * names every key either the outgoing set or the incoming one answers for, so
+     * a listener caching per key drops both sides of a whole-set replacement.
+     *
+     * @returns The snapshot now held, or why the store could not hand its set over.
+     */
+    async refresh() {
+        let previous = this.#engine.snapshot;
+        let result = await this.#engine.load();
+        if (isFailure(result)) {
+            this.#announceStale();
+            return result;
+        }
+        if (this.#announced) {
+            this.#announced = false;
+            this.events.emit("PROVIDER_READY");
+        }
+        this.events.emit("PROVIDER_CONFIGURATION_CHANGED", {
+            flagsChanged: [...new Set([...answeredBy(previous), ...answeredBy(result.data)])],
+        });
+        return result;
+    }
+    resolveBoolean(key, defaultValue, context = {}) {
+        return this.#engine.evaluate(key, defaultValue, context);
+    }
+    resolveString(key, defaultValue, context = {}) {
+        return this.#engine.evaluate(key, defaultValue, context);
+    }
+    resolveNumber(key, defaultValue, context = {}) {
+        return this.#engine.evaluate(key, defaultValue, context);
+    }
+    resolveObject(key, defaultValue, context = {}) {
+        return this.#engine.evaluate(key, defaultValue, context);
+    }
+    /**
+     * Says the definitions are aging at the one moment the provider reads the
+     * engine away from the evaluation path: a reload that kept a snapshot already
+     * past `maxAge`, which is where an age a caller can act on becomes visible.
+     */
+    #announceStale() {
+        if (this.#announced)
+            return;
+        if (this.#engine.snapshot === undefined || !this.#engine.stale)
+            return;
+        this.#announced = true;
+        this.events.emit("PROVIDER_STALE", {
+            message: "Serving definitions older than maxAge until a reload replaces them",
+        });
+    }
+}
+/**
+ * Every key a snapshot has an answer for, the definitions it refused included,
+ * since a flag that failed to parse resolves as `PARSE_ERROR` under its own key.
+ */
+function answeredBy(snapshot) {
+    if (snapshot === undefined)
+        return [];
+    return [...snapshot.flags.keys(), ...snapshot.failures.keys()];
+}

package/dist/schema.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The parsers that turn stored, untrusted JSON into definitions. They are the
+ * package's published contract for what a flag is, so an admin UI validates a
+ * rule against the same schema before writing what the engine would refuse.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Schema } from "remix/data-schema";
+import type { Condition, FlagDefinition, SegmentSet, Split, TargetingRule } from "./definition.js";
+/**
+ * Reads one targeting condition. Annotated rather than inferred because
+ * `s.variant` widens the discriminant it merges, which would cost every
+ * consumer the narrowing the union exists for.
+ */
+export declare const CONDITION_SCHEMA: Schema<unknown, Condition>;
+/** Reads the weighted spread a rule serves instead of naming one variant. */
+export declare const SPLIT_SCHEMA: Schema<unknown, Split>;
+/** Reads one targeting row, whose `serve` is either a variant name or a split. */
+export declare const TARGETING_RULE_SCHEMA: Schema<unknown, TargetingRule>;
+/**
+ * Reads one flag. A flag with no variants is refused here, so every later step
+ * is choosing among values that exist.
+ */
+export declare const FLAG_DEFINITION_SCHEMA: Schema<unknown, FlagDefinition>;
+/**
+ * Reads a whole segment map at once, for an editor validating what it is about
+ * to write. The engine reads segments one at a time so a bad one costs only the
+ * flags that reference it.
+ */
+export declare const SEGMENT_SET_SCHEMA: Schema<unknown, SegmentSet>;