@variantlab/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,223 @@
+import { E as Experiment, a as ExperimentsConfig } from './types-BkXPpEyg.js';
+export { A as AssignmentStrategy, R as RollbackConfig, T as Targeting, V as Variant, b as VariantContext } from './types-BkXPpEyg.js';
+export { C as ConfigIssue, a as ConfigValidationError, I as IssueCode, v as validateConfig } from './config-B3DTOt1J.js';
+export { E as EngineEvent, a as EngineOptions, F as FailMode, L as Listener, b as ListenerSet, U as UnknownExperimentError, V as VariantChangeSource, c as VariantEngine, d as createEngine } from './engine-BoNBfZBL.js';
+export { EvalContext, EvaluableTargeting, ExplainField, ExplainResult, ExplainStep, TargetingResult, evaluate, explain, hashUserId, matchRoute, matchSemver, matchTargeting } from './_size/targeting.js';
+
+/**
+ * Default assignment: always returns the experiment's `default`
+ * variant. Used when no strategy is configured, when the user is
+ * not yet bucketable (no `userId`), or as the fallback in
+ * fail-open error paths.
+ */
+
+declare function assignDefault(experiment: Experiment): string;
+
+/**
+ * Synchronous 32-bit string hash for deterministic assignment.
+ *
+ * `getVariant` is required to be synchronous and O(1) (see
+ * `ARCHITECTURE.md` runtime data flow and the design principle
+ * of cheap, render-safe reads). Web Crypto's `subtle.digest` is
+ * always async, so we hand-roll a tiny hash here:
+ *
+ *   - FNV-1a (32-bit) core for fast streaming.
+ *   - Murmur3 finalizer for avalanche (uniform bit distribution).
+ *
+ * Total: ~150 bytes gzipped. Deterministic across every runtime we
+ * target (Node 18+, browsers, RN, Deno, Bun, Edge) because every
+ * step is a 32-bit integer operation with defined overflow semantics
+ * via `Math.imul` and `>>> 0`.
+ *
+ * This is **not** cryptographic — do not use for signing. The async
+ * sha256 path in `../targeting/hash.ts` remains available for
+ * advanced use cases. The phase-0 "which hash algorithm" open
+ * question in `docs/phases/phase-0-foundation.md` resolves here.
+ */
+/** FNV-1a 32-bit hash + Murmur3 finalizer. Returns a uint32. */
+declare function hash32(input: string): number;
+/** Map a userId to a [0, 100) bucket. Used by user-id hash-mod targeting. */
+declare function bucketUserId(userId: string): number;
+
+declare function resolveMutex(userId: string, mutexGroup: string, candidateIds: readonly string[]): string | undefined;
+
+/**
+ * "Random" assignment.
+ *
+ * In phase 1 MVP this is behaviorally identical to `sticky-hash`:
+ * a deterministic function of `(userId, experimentId)`. The two
+ * strategies exist as distinct config values because the contract
+ * differs:
+ *
+ *   - `sticky-hash` — promised to be stable across devices for the
+ *     same `userId`, zero storage needed.
+ *   - `random`      — the engine is allowed to bucket the user
+ *     however it likes as long as each user sees a consistent
+ *     answer. Future phases may back this with storage-cached
+ *     uniform-random assignments.
+ *
+ * The non-negotiable rule (design-principles.md §performance &
+ * ARCHITECTURE.md §core invariants): **no `Math.random` in the hot
+ * path**. Delegating to `assignStickyHash` keeps us honest and
+ * collapses both paths to the same tree-shaken code.
+ */
+
+declare function assignRandom(experiment: Experiment, userId: string): string;
+
+/**
+ * Sticky-hash assignment.
+ *
+ * Deterministic from `(userId, experimentId)`: hash the pair with
+ * the sync 32-bit hash and map the result modulo the sorted variant
+ * count. Sort order is lexicographic on `variant.id` so that the
+ * mapping is stable across processes, devices, and restarts.
+ *
+ * Adding a new variant renumbers existing users (the classic
+ * hash-mod trade-off). This is acceptable for phase 1 — the
+ * config-format doc calls out that variant additions are effectively
+ * a new experiment. Rendezvous hashing would fix this but costs
+ * ~300 bytes we don't want to spend before someone asks for it.
+ */
+
+declare function assignStickyHash(experiment: Experiment, userId: string): string;
+
+/**
+ * Weighted assignment.
+ *
+ * Maps `(userId, experimentId)` to a `[0, 10000)` bucket via the
+ * sync hash, then walks the split's cumulative boundaries in
+ * sorted-key order. `split` is validated at config-load time to
+ * sum to exactly 100, so we multiply by 100 internally to get an
+ * integer 10000-unit range without floating point.
+ *
+ * Determinism: same user, same experiment, same split → same
+ * variant forever. Changing the split re-buckets everyone, which
+ * is the documented behavior in `config-format.md`.
+ */
+
+declare function assignWeighted(experiment: Experiment, userId: string): string;
+
+/**
+ * Assignment barrel.
+ *
+ * `assignVariant` is the single entry point used by the engine hot
+ * path. It dispatches on `experiment.assignment` and falls back to
+ * the default variant whenever the user isn't bucketable (missing
+ * `userId`) — every non-`default` strategy depends on a stable
+ * identity to be deterministic.
+ */
+
+declare function assignVariant(experiment: Experiment, userId: string | undefined): string;
+
+/**
+ * Deterministic JSON serializer (RFC 8785-inspired, not strict).
+ *
+ * - Object keys are sorted by UTF-16 code unit (`Array#sort` default).
+ * - Only own enumerable keys are serialized.
+ * - `undefined` values on objects are dropped; `undefined` in arrays
+ *   is emitted as `null` (matches `JSON.stringify`).
+ * - Finite numbers only; `NaN`/`Infinity`/`-Infinity` throw.
+ * - `BigInt`, functions, and symbols throw.
+ * - No whitespace in the output.
+ * - A depth cap of 512 guards against accidental unbounded recursion.
+ *
+ * The output is the canonical form used as input to HMAC signing
+ * (Phase 2). It is **not** used for the 1 MB size check — that is
+ * measured against the raw input bytes.
+ */
+declare function canonicalStringify(value: unknown): string;
+
+/**
+ * Recursively freeze a plain-JSON-shaped value.
+ *
+ * - Primitives (including `null`/`undefined`) are returned as-is.
+ * - Arrays and plain objects are frozen in-place with `Object.freeze`.
+ * - Already-frozen subtrees are skipped (short-circuit) so this is
+ *   cheap to call on shared references and idempotent.
+ *
+ * Sanitized config trees are tree-shaped (no cycles, no class
+ * instances) so no cycle detection is required.
+ */
+declare function deepFreeze<T>(value: T): T;
+
+/**
+ * In-memory crash counter for crash-rollback.
+ *
+ * For each experiment, we maintain a sliding window of crash
+ * timestamps. `record()` appends, `countWithin()` drops expired
+ * entries and returns the current count. Persistence across
+ * process restarts is phase 4 (`rollback.persistent`) — the phase 1
+ * MVP only protects users within a single session.
+ */
+declare class CrashCounter {
+    private readonly crashes;
+    /** Record a crash; returns the new in-window count (post-prune). */
+    record(experimentId: string, now: number, window: number): number;
+    countWithin(experimentId: string, now: number, window: number): number;
+    clear(experimentId?: string): void;
+}
+
+/**
+ * Kill-switch logic.
+ *
+ * Returns `true` when an experiment should short-circuit to its
+ * default variant for a reason that isn't context-specific:
+ *
+ *   - Global `config.enabled === false` — admin kill switch for
+ *     fast incident response.
+ *   - `status === "archived"` — the experiment is over, keep the
+ *     config around for history but never evaluate it.
+ *   - `status === "draft"` — the experiment is being authored; in
+ *     production this behaves the same as archived (returns the
+ *     default), the debug overlay shows it with a badge so devs
+ *     can still preview it.
+ */
+
+declare function isKilled(config: ExperimentsConfig, experiment: Experiment): boolean;
+
+/**
+ * Start/end date gate.
+ *
+ * `startDate` is inclusive, `endDate` is exclusive. Matches the
+ * semantics documented in `config-format.md` §`startDate / endDate`.
+ *
+ * `now` is injected (not read via `Date.now()` here) so that the
+ * engine can snapshot time at a single point per resolution and
+ * so that tests can pin time without mocking globals. The engine
+ * calls `Date.now()` once per `getVariant` call at the outer
+ * boundary.
+ *
+ * Malformed ISO strings fail-closed (the gate returns `true` to
+ * keep the experiment inactive) — a broken date is a config
+ * mistake the validator catches at load time, but defending in
+ * depth here is ~10 bytes we're happy to spend.
+ */
+
+declare function isTimeGated(experiment: Experiment, now: number): boolean;
+
+/**
+ * Fixed-size ring buffer for engine event history.
+ *
+ * Overwrites the oldest entry when full. `toArray()` returns the
+ * stored entries in chronological order (oldest → newest) which is
+ * the order the debug overlay and time-travel replayer expect.
+ *
+ * Default capacity is 500 — at ~200 bytes per event this caps
+ * in-memory history at ~100 KB per engine, which is negligible
+ * compared to any other memory cost the app already pays.
+ */
+declare class RingBuffer<T> {
+    readonly capacity: number;
+    private buffer;
+    private head;
+    private count;
+    constructor(capacity?: number);
+    push(item: T): void;
+    toArray(): T[];
+    clear(): void;
+    get size(): number;
+}
+
+declare const VERSION = "0.0.0";
+
+export { CrashCounter, Experiment, ExperimentsConfig, RingBuffer, VERSION, assignDefault, assignRandom, assignStickyHash, assignVariant, assignWeighted, bucketUserId, canonicalStringify, deepFreeze, hash32, isKilled, isTimeGated, resolveMutex };