@nebulr-group/bridge-auth-core 0.1.2 → 0.4.0-beta.1

package/dist/flags/dev-attribute-provider.d.ts

@@ -0,0 +1,67 @@
+export type AttributeGetter = () => unknown;
+export type AttributeBulkGetter = () => Record<string, unknown> | undefined | null;
+export interface SetOptions {
+    /**
+     * When false, this attribute's reads do NOT participate in
+     * `onAttributeObserved` telemetry. Default true.
+     *
+     * Useful for high-frequency keys (e.g. cursor position, scroll offset)
+     * where the dev needs the value in flag evals but doesn't need the
+     * telemetry overhead.
+     */
+    observed?: boolean;
+}
+/**
+ * Dev-managed AttributeProvider — the single backend for the `bridge.attributes`
+ * surface. One instance is created per SDK init and registered with the
+ * AttributeProviderRegistry. The order of registration determines whose
+ * keys win on collision via `collectSync` merge order (per-call attrs >
+ * setContext > providers — locked decision #20). Dev's provider is registered
+ * LAST so its keys beat the framework providers.
+ */
+export declare class DevAttributeProvider {
+    readonly name = "dev";
+    readonly namespace: 'custom';
+    private readonly _entries;
+    private readonly _bulkEntries;
+    private readonly _subscribers;
+    /** Static one-shot value. `opts.observed` defaults to true. */
+    set(key: string, value: unknown, opts?: SetOptions): void;
+    /** Live-bound: getter re-invoked on every flag eval. */
+    bind(key: string, getter: AttributeGetter, opts?: SetOptions): void;
+    /**
+     * Bulk getter returning `Record<string, unknown>`. Reserved keys inside
+     * the returned map are silently dropped (a `console.warn` fires once per
+     * reserved key per session to surface the typo).
+     */
+    bindMany(getter: AttributeBulkGetter, opts?: SetOptions): void;
+    /** Remove a key (static or bound). Bulk getters are removed via `clearBulk()`. */
+    unset(key: string): void;
+    /** Remove every bulk getter. */
+    clearBulk(): void;
+    /** Remove every entry (test/teardown). */
+    clear(): void;
+    /**
+     * AttributeProvider contract — invoked synchronously on the FF 2.0 hot
+     * eval path. Returns the merged attribute map.
+     *
+     * Merge order within the dev provider: bulk getters first (so individual
+     * `set`/`bind` calls win over a bulk that happens to repeat a key).
+     * Getter exceptions are isolated — one throwing key doesn't break the rest.
+     */
+    provide(): Record<string, unknown>;
+    /** Read-side convenience used by the public `bridge.attributes.get()`. */
+    get(): Record<string, unknown>;
+    /**
+     * Whether the key opts out of `onAttributeObserved` telemetry. Looked up
+     * by the framework SDK at observation time; bulk-supplied keys default to
+     * the bulk entry's `observed` flag (or true).
+     */
+    isObserved(key: string): boolean;
+    /** Svelte store contract — subscribe to attribute-map snapshots. */
+    subscribe(fn: (map: Record<string, unknown>) => void): () => void;
+    private _notify;
+}
+/** Exposed for tests in other packages that want to validate the reserved set. */
+export declare const __TEST_RESERVED_PREFIXES: readonly string[];
+//# sourceMappingURL=dev-attribute-provider.d.ts.map

package/dist/flags/dev-attribute-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-attribute-provider.d.ts","sourceRoot":"","sources":["../../src/flags/dev-attribute-provider.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC;AAC5C,MAAM,MAAM,mBAAmB,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnF,MAAM,WAAW,UAAU;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA4BD;;;;;;;GAOG;AACH,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,IAAI,SAAS;IACtB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAY;IAIxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IAGjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqD;IAElF,+DAA+D;IAC/D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI;IAczD,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI;IAcnE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI;IAS9D,kFAAkF;IAClF,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB,gCAAgC;IAChC,SAAS,IAAI,IAAI;IAMjB,0CAA0C;IAC1C,KAAK,IAAI,IAAI;IAMb;;;;;;;OAOG;IACH,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IA6BlC,0EAA0E;IAC1E,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI9B;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWhC,oEAAoE;IACpE,SAAS,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAYjE,OAAO,CAAC,OAAO;CAgBhB;AAED,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAsB,CAAC"}

package/dist/flags/dev-attribute-provider.js

@@ -0,0 +1,200 @@
+// Phase 5 (TBP-288/328/329/330) — dev-managed AttributeProvider.
+//
+// Backs the `bridge.attributes` surface in framework SDKs (bridge-svelte etc.).
+// Three contribution modes — all coexist in one provider instance:
+//
+//   set(key, value)        → static one-shot value
+//   bind(key, getter)      → live; getter is called on every flag eval
+//   bindMany(getter)       → bulk; getter returns Record<string, unknown>
+//
+// Reserved namespace: keys starting with `bridge:` (and the legacy aliases
+// `app:`, `tenant:`, `user:` reserved for bridge-managed attribute scopes)
+// are REJECTED at write time with a clear console.warn — they don't end up
+// in the provider map. Reads via get() return only the dev-contributed keys.
+const RESERVED_PREFIXES = ['bridge:'];
+function isReserved(key) {
+    for (const p of RESERVED_PREFIXES) {
+        if (key.startsWith(p))
+            return true;
+    }
+    return false;
+}
+function warnReserved(key, context) {
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+        // eslint-disable-next-line no-console
+        console.warn(`[bridge.attributes.${context}] key "${key}" is in the reserved \`bridge:\` namespace — write rejected. ` +
+            `Use a custom prefix (e.g. \`app.${key.split(':')[1] ?? key}\`) instead.`);
+    }
+}
+/**
+ * Dev-managed AttributeProvider — the single backend for the `bridge.attributes`
+ * surface. One instance is created per SDK init and registered with the
+ * AttributeProviderRegistry. The order of registration determines whose
+ * keys win on collision via `collectSync` merge order (per-call attrs >
+ * setContext > providers — locked decision #20). Dev's provider is registered
+ * LAST so its keys beat the framework providers.
+ */
+export class DevAttributeProvider {
+    name = 'dev';
+    namespace = 'custom';
+    // Single map keyed by attribute key for `static` + `bound` entries.
+    // Bulk entries are kept in a parallel list (no single key).
+    _entries = new Map();
+    _bulkEntries = [];
+    // Subscriptions for the Svelte store contract (TBP-328 AC: "subscribable").
+    _subscribers = new Set();
+    /** Static one-shot value. `opts.observed` defaults to true. */
+    set(key, value, opts) {
+        if (isReserved(key)) {
+            warnReserved(key, 'set');
+            return;
+        }
+        this._entries.set(key, {
+            kind: 'static',
+            key,
+            value,
+            observed: opts?.observed ?? true,
+        });
+        this._notify();
+    }
+    /** Live-bound: getter re-invoked on every flag eval. */
+    bind(key, getter, opts) {
+        if (isReserved(key)) {
+            warnReserved(key, 'bind');
+            return;
+        }
+        this._entries.set(key, {
+            kind: 'bound',
+            key,
+            getter,
+            observed: opts?.observed ?? true,
+        });
+        this._notify();
+    }
+    /**
+     * Bulk getter returning `Record<string, unknown>`. Reserved keys inside
+     * the returned map are silently dropped (a `console.warn` fires once per
+     * reserved key per session to surface the typo).
+     */
+    bindMany(getter, opts) {
+        this._bulkEntries.push({
+            kind: 'bulk',
+            bulkGetter: getter,
+            observed: opts?.observed ?? true,
+        });
+        this._notify();
+    }
+    /** Remove a key (static or bound). Bulk getters are removed via `clearBulk()`. */
+    unset(key) {
+        if (this._entries.delete(key))
+            this._notify();
+    }
+    /** Remove every bulk getter. */
+    clearBulk() {
+        if (this._bulkEntries.length === 0)
+            return;
+        this._bulkEntries.length = 0;
+        this._notify();
+    }
+    /** Remove every entry (test/teardown). */
+    clear() {
+        this._entries.clear();
+        this._bulkEntries.length = 0;
+        this._notify();
+    }
+    /**
+     * AttributeProvider contract — invoked synchronously on the FF 2.0 hot
+     * eval path. Returns the merged attribute map.
+     *
+     * Merge order within the dev provider: bulk getters first (so individual
+     * `set`/`bind` calls win over a bulk that happens to repeat a key).
+     * Getter exceptions are isolated — one throwing key doesn't break the rest.
+     */
+    provide() {
+        const out = {};
+        for (const entry of this._bulkEntries) {
+            try {
+                const m = entry.bulkGetter();
+                if (m && typeof m === 'object') {
+                    for (const [k, v] of Object.entries(m)) {
+                        if (isReserved(k))
+                            continue;
+                        out[k] = v;
+                    }
+                }
+            }
+            catch {
+                // Skip a throwing bulk getter for this eval.
+            }
+        }
+        for (const entry of this._entries.values()) {
+            try {
+                if (entry.kind === 'static') {
+                    out[entry.key] = entry.value;
+                }
+                else if (entry.kind === 'bound') {
+                    out[entry.key] = entry.getter();
+                }
+            }
+            catch {
+                // Skip a throwing getter; other keys still flow through.
+            }
+        }
+        return out;
+    }
+    /** Read-side convenience used by the public `bridge.attributes.get()`. */
+    get() {
+        return this.provide();
+    }
+    /**
+     * Whether the key opts out of `onAttributeObserved` telemetry. Looked up
+     * by the framework SDK at observation time; bulk-supplied keys default to
+     * the bulk entry's `observed` flag (or true).
+     */
+    isObserved(key) {
+        const direct = this._entries.get(key);
+        if (direct)
+            return direct.observed;
+        // Bulk entries don't track per-key observation; use the most-recently
+        // added bulk entry's flag if any, else default true.
+        if (this._bulkEntries.length > 0) {
+            return this._bulkEntries[this._bulkEntries.length - 1].observed;
+        }
+        return true;
+    }
+    /** Svelte store contract — subscribe to attribute-map snapshots. */
+    subscribe(fn) {
+        this._subscribers.add(fn);
+        try {
+            fn(this.provide());
+        }
+        catch {
+            // ignore subscriber errors
+        }
+        return () => {
+            this._subscribers.delete(fn);
+        };
+    }
+    _notify() {
+        if (this._subscribers.size === 0)
+            return;
+        let snapshot;
+        try {
+            snapshot = this.provide();
+        }
+        catch {
+            return;
+        }
+        for (const fn of this._subscribers) {
+            try {
+                fn(snapshot);
+            }
+            catch {
+                // ignore subscriber errors
+            }
+        }
+    }
+}
+/** Exposed for tests in other packages that want to validate the reserved set. */
+export const __TEST_RESERVED_PREFIXES = RESERVED_PREFIXES;
+//# sourceMappingURL=dev-attribute-provider.js.map

package/dist/flags/dev-attribute-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-attribute-provider.js","sourceRoot":"","sources":["../../src/flags/dev-attribute-provider.ts"],"names":[],"mappings":"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"}

package/dist/flags/evaluator.d.ts

@@ -0,0 +1,58 @@
+import type { AttributeType, Condition, Operator } from './operators.js';
+/** A branch is a list of conditions (AND-ed) + the value returned on match. */
+export interface Branch {
+    conditions: Condition[];
+    returnValue: unknown;
+}
+export interface Rule {
+    /** First-match-wins. */
+    branches: Branch[];
+    /** Returned when no branch matches. */
+    otherwiseValue: unknown;
+    /** 0-100. Applies to the whole rule. */
+    rolloutPct: number;
+    /** When set, the flag uses a saved group's branches; `branches` is ignored. */
+    groupRef?: string;
+}
+export type FlagState = 'off' | 'on' | 'on-with-rule';
+export interface EvalContext {
+    /** Stable per-eval identity. Required when rolloutPct < 100. */
+    identity?: string;
+    /** Flat or nested attribute map. */
+    attributes: Record<string, unknown>;
+}
+export interface EvalResult {
+    value: unknown;
+    /** Which branch fired, 0-indexed. -1 if otherwise was returned. */
+    variantIndex: number;
+    matched: boolean;
+    excludedByRollout: boolean;
+}
+/**
+ * Resolve a dotted-path attribute name against the eval context.
+ * Tries the flat key first, then walks dots.
+ */
+export declare function resolveAttribute(ctx: EvalContext, attribute: string): unknown;
+/**
+ * 32-bit FNV-1a hash of `${flagKey}|${identity}` mod 100. Same bucket for same
+ * inputs across server and SDK. Used for rule-level rollout and (future)
+ * variant assignment in L: Experiments.
+ */
+export declare function bucket(flagKey: string, identity: string): number;
+/** Evaluate a single branch's conditions against the context. AND between conditions. */
+export declare function evaluateBranch(branch: Branch, ctx: EvalContext): boolean;
+/**
+ * Evaluate a Rule (branches + otherwise + rollout). First-match-wins; rollout
+ * applies to the whole rule (excluded users fall through to otherwise).
+ */
+export declare function evaluateRule(rule: Rule, flagKey: string, ctx: EvalContext): EvalResult;
+export interface RuleValidationError {
+    branchIndex: number;
+    conditionIndex: number;
+    attribute?: string;
+    operator?: string;
+    message: string;
+}
+export declare function validateRule(rule: Rule, attributeTypes?: Readonly<Record<string, AttributeType>>): RuleValidationError[];
+export type { Operator, AttributeType, Condition };
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/flags/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/flags/evaluator.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AASzE,+EAA+E;AAC/E,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,IAAI;IACnB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uCAAuC;IACvC,cAAc,EAAE,OAAO,CAAC;IACxB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,IAAI,GAAG,cAAc,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAY7E;AAID;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQhE;AAID,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAGxE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,CAwBtF;AAWD,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,cAAc,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAM,GAC3D,mBAAmB,EAAE,CAsEvB;AAGD,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC"}

package/dist/flags/evaluator.js

@@ -0,0 +1,160 @@
+// Bridge Feature Flags 2.0 rule evaluator.
+//
+// This module is the SINGLE SOURCE OF TRUTH for both:
+//   - bridge-api server-side eval
+//   - bridge-* SDK client-side eval
+//
+// Imports `evaluateCondition` from the operator module in the same package
+// (./operators.js). Server-side bridge-api imports from
+// `@nebulr-group/bridge-auth-core` and gets identical semantics.
+//
+// Companion module: ./operators.ts (operator set + per-condition eval +
+// save-time validation). This file builds the rule layer (branches + rollout)
+// on top of those primitives.
+import { evaluateCondition } from './operators.js';
+import { isOperator, isOperatorValidForType, validOperatorsForType, } from './operators.js';
+// ── Attribute resolution ────────────────────────────────────────────────────
+/**
+ * Resolve a dotted-path attribute name against the eval context.
+ * Tries the flat key first, then walks dots.
+ */
+export function resolveAttribute(ctx, attribute) {
+    if (Object.prototype.hasOwnProperty.call(ctx.attributes, attribute)) {
+        return ctx.attributes[attribute];
+    }
+    const parts = attribute.split('.');
+    let current = ctx.attributes;
+    for (const part of parts) {
+        if (current === undefined || current === null)
+            return undefined;
+        if (typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+// ── Stable hash bucketing ───────────────────────────────────────────────────
+/**
+ * 32-bit FNV-1a hash of `${flagKey}|${identity}` mod 100. Same bucket for same
+ * inputs across server and SDK. Used for rule-level rollout and (future)
+ * variant assignment in L: Experiments.
+ */
+export function bucket(flagKey, identity) {
+    const input = `${flagKey}|${identity}`;
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = (hash + (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)) >>> 0;
+    }
+    return hash % 100;
+}
+// ── Branch + rule evaluation ────────────────────────────────────────────────
+/** Evaluate a single branch's conditions against the context. AND between conditions. */
+export function evaluateBranch(branch, ctx) {
+    if (!branch.conditions || branch.conditions.length === 0)
+        return false;
+    return branch.conditions.every((c) => evaluateCondition(c, resolveAttribute(ctx, c.attribute)));
+}
+/**
+ * Evaluate a Rule (branches + otherwise + rollout). First-match-wins; rollout
+ * applies to the whole rule (excluded users fall through to otherwise).
+ */
+export function evaluateRule(rule, flagKey, ctx) {
+    const rolloutPct = clampPct(rule.rolloutPct ?? 100);
+    if (rolloutPct < 100) {
+        if (!ctx.identity) {
+            return { value: rule.otherwiseValue, variantIndex: -1, matched: false, excludedByRollout: true };
+        }
+        if (bucket(flagKey, ctx.identity) >= rolloutPct) {
+            return { value: rule.otherwiseValue, variantIndex: -1, matched: false, excludedByRollout: true };
+        }
+    }
+    const branches = rule.branches ?? [];
+    for (let i = 0; i < branches.length; i++) {
+        if (evaluateBranch(branches[i], ctx)) {
+            return {
+                value: branches[i].returnValue,
+                variantIndex: i,
+                matched: true,
+                excludedByRollout: false,
+            };
+        }
+    }
+    return { value: rule.otherwiseValue, variantIndex: -1, matched: false, excludedByRollout: false };
+}
+function clampPct(p) {
+    if (!Number.isFinite(p))
+        return 100;
+    if (p < 0)
+        return 0;
+    if (p > 100)
+        return 100;
+    return p;
+}
+const RULE_CONDITIONS_HARD_MAX = 50;
+export function validateRule(rule, attributeTypes = {}) {
+    const errors = [];
+    if (!rule || typeof rule !== 'object') {
+        return [{ branchIndex: -1, conditionIndex: -1, message: 'Rule must be an object.' }];
+    }
+    const branches = rule.branches ?? [];
+    let totalConditions = 0;
+    branches.forEach((branch, bi) => {
+        if (!branch.conditions || branch.conditions.length === 0) {
+            errors.push({
+                branchIndex: bi,
+                conditionIndex: -1,
+                message: `Branch ${bi} has no conditions.`,
+            });
+            return;
+        }
+        branch.conditions.forEach((c, ci) => {
+            totalConditions++;
+            if (!isOperator(c.operator)) {
+                errors.push({
+                    branchIndex: bi,
+                    conditionIndex: ci,
+                    attribute: c.attribute,
+                    operator: c.operator,
+                    message: `Unknown operator "${c.operator}".`,
+                });
+                return;
+            }
+            const opType = attributeTypes[c.attribute];
+            if (opType && !isOperatorValidForType(c.operator, opType)) {
+                errors.push({
+                    branchIndex: bi,
+                    conditionIndex: ci,
+                    attribute: c.attribute,
+                    operator: c.operator,
+                    message: `Operator "${c.operator}" not valid for type ${opType}. Valid: ${validOperatorsForType(opType).join(', ')}.`,
+                });
+            }
+        });
+    });
+    if (totalConditions > RULE_CONDITIONS_HARD_MAX) {
+        errors.push({
+            branchIndex: -1,
+            conditionIndex: -1,
+            message: `Rule has ${totalConditions} conditions; max is ${RULE_CONDITIONS_HARD_MAX}.`,
+        });
+    }
+    if (rule.rolloutPct !== undefined) {
+        if (typeof rule.rolloutPct !== 'number' || rule.rolloutPct < 0 || rule.rolloutPct > 100) {
+            errors.push({
+                branchIndex: -1,
+                conditionIndex: -1,
+                message: `rolloutPct must be a number in [0, 100], got ${rule.rolloutPct}.`,
+            });
+        }
+    }
+    if (rule.groupRef && branches.length > 0) {
+        errors.push({
+            branchIndex: -1,
+            conditionIndex: -1,
+            message: 'Rule cannot have both an inline `branches` and a `groupRef`.',
+        });
+    }
+    return errors;
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/flags/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../src/flags/evaluator.ts"],"names":[],"mappings":"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"}