@factoredui/core 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -13,6 +13,10 @@ interface CaptureAdapter {
     loadSessionId(): string | null;
     clearSessionId(): void;
     registerUnloadHandler(onUnload: () => void): void;
+    /** Persist queued events to survive app restarts. JSON string of event array. */
+    persistQueue?(serialized: string): void;
+    /** Load previously persisted queue. Returns null if empty. */
+    loadQueue?(): string | null;
 }
 
 type EventType = "click" | "scroll" | "error" | "navigation" | "impression" | "input" | "focus" | "blur" | "submit" | "resize" | "visibility" | "rage_click" | "dead_click" | "scroll_reversal";
@@ -309,20 +313,45 @@ interface KMeansResult {
  */
 declare function kMeans(points: number[][], k: number, seed?: number): KMeansResult;
 
-/**
- * Flag evaluation: reads experiment assignments for the current user.
- * If not yet assigned to a running experiment, assigns deterministically via hash bucketing.
- * Optional platform parameter filters experiments to those targeting the current platform.
- */
-declare function evaluateFlag(supabase: SupabaseClient, experimentName: string, platform?: Platform): Promise<ExperimentAssignment | null>;
-
 type TargetingOperator = "gt" | "gte" | "lt" | "lte" | "eq";
-interface TargetingRule {
+interface FactorTargetingRule {
+    type: "factor";
+    factor: string;
+    operator: TargetingOperator;
+    threshold: number;
+}
+type MetadataField = "os_name" | "os_version" | "manufacturer" | "model" | "app_version" | "app_build" | "platform";
+type MetadataOperator = "eq" | "neq" | "contains" | "gte" | "lte";
+interface MetadataTargetingRule {
+    type: "metadata";
+    field: MetadataField;
+    operator: MetadataOperator;
+    value: string;
+}
+/** Legacy format (factor-only) for backward compatibility with existing experiments */
+interface LegacyTargetingRule {
     factor: string;
     operator: TargetingOperator;
     threshold: number;
 }
-declare function evaluateTargeting(factors: Factor[], rules: TargetingRule[]): boolean;
+type TargetingRule = FactorTargetingRule | MetadataTargetingRule | LegacyTargetingRule;
+interface DeviceMetadata {
+    os_name?: string;
+    os_version?: string;
+    manufacturer?: string;
+    model?: string;
+    app_version?: string;
+    app_build?: string;
+    platform?: string;
+}
+declare function evaluateTargeting(factors: Factor[], rules: TargetingRule[], deviceMetadata?: DeviceMetadata): boolean;
+
+/**
+ * Flag evaluation: reads experiment assignments for the current user.
+ * If not yet assigned to a running experiment, assigns deterministically via hash bucketing.
+ * Optional platform parameter filters experiments to those targeting the current platform.
+ */
+declare function evaluateFlag(supabase: SupabaseClient, experimentName: string, platform?: Platform, deviceMetadata?: DeviceMetadata): Promise<ExperimentAssignment | null>;
 
 interface VariantDefinition {
     variant_key: string;
@@ -557,4 +586,4 @@ declare function generateEd25519Keypair(): Promise<{
     privateKey: string;
 }>;
 
-export { type ActionHandler, type ActionRef, type ActionRegistry, type ButtonProps, type CaptureAdapter, type CaptureEvent, type CaptureHandle, type CardProps, type ChipProps, type ComponentFactorAggregate, type ComponentRegistry, type ComponentRenderer, type Config, type CreatedExperiment, type DataSourceCache, type DataSourceConfig, type DataSourceRegistry, type DividerProps, type EventType, type ExperimentAssignment, type ExperimentDefinition, type ExperimentSummaryFilters, type ExperimentSummaryRow, type Factor, type FactorDelta, type FactorSnapshot, type FactorTier, type FactorVerdict, type GovernanceAction, type GovernanceLogRow, type GovernanceVerdict, type GridProps, type IconProps, type ImageProps, type KMeansResult, type KVStorage, type LayoutProps, type ListProps, type LoadedSpec, type ModalProps, type Platform, RENDERER_VERSION, type ResolvedSources, type ScrollViewProps, type SelectProps, type Session, type SignatureVerifier, type SignedSpec, type SliderProps, type SpacerProps, type Spec, type SpecNode, type SpecNodeType, type SpecSigner, type SpecStorage, type SpecValue, type TabsProps, type TargetingOperator, type TargetingRule, type TextInputProps, type TextProps, type Threshold, type ToggleProps, type UserCluster, type VariantDefinition, type VariantResult, buildFactorDashboardSpec, componentFactorSource, concludeExperiment, createDataSourceCache, createEd25519Signer, createEd25519Verifier, createExperiment, createSpecStorage, createWebAdapter, devSignatureVerifier, dispatchAction, evaluateExperimentThresholds, evaluateFlag, evaluateTargeting, factorHistorySource, factorSource, generateEd25519Keypair, initCapture, isBindingRef, kMeans, loadSpec, logGovernanceVerdict, queryClusterMembers, queryComponentFactors, queryExperimentResults, queryExperimentSummaries, queryFactorDelta, queryFactorHistory, queryFactors, queryGovernanceLog, queryRecentGovernanceLog, queryUserCluster, resolveAllSources, resolveBinding, resolveComponentPath, resolveProps, resolveTextWithBindings, runGovernanceCheck, startExperiment, validateSpec };
+export { type ActionHandler, type ActionRef, type ActionRegistry, type ButtonProps, type CaptureAdapter, type CaptureEvent, type CaptureHandle, type CardProps, type ChipProps, type ComponentFactorAggregate, type ComponentRegistry, type ComponentRenderer, type Config, type CreatedExperiment, type DataSourceCache, type DataSourceConfig, type DataSourceRegistry, type DeviceMetadata, type DividerProps, type EventType, type ExperimentAssignment, type ExperimentDefinition, type ExperimentSummaryFilters, type ExperimentSummaryRow, type Factor, type FactorDelta, type FactorSnapshot, type FactorTargetingRule, type FactorTier, type FactorVerdict, type GovernanceAction, type GovernanceLogRow, type GovernanceVerdict, type GridProps, type IconProps, type ImageProps, type KMeansResult, type KVStorage, type LayoutProps, type ListProps, type LoadedSpec, type MetadataField, type MetadataOperator, type MetadataTargetingRule, type ModalProps, type Platform, RENDERER_VERSION, type ResolvedSources, type ScrollViewProps, type SelectProps, type Session, type SignatureVerifier, type SignedSpec, type SliderProps, type SpacerProps, type Spec, type SpecNode, type SpecNodeType, type SpecSigner, type SpecStorage, type SpecValue, type TabsProps, type TargetingOperator, type TargetingRule, type TextInputProps, type TextProps, type Threshold, type ToggleProps, type UserCluster, type VariantDefinition, type VariantResult, buildFactorDashboardSpec, componentFactorSource, concludeExperiment, createDataSourceCache, createEd25519Signer, createEd25519Verifier, createExperiment, createSpecStorage, createWebAdapter, devSignatureVerifier, dispatchAction, evaluateExperimentThresholds, evaluateFlag, evaluateTargeting, factorHistorySource, factorSource, generateEd25519Keypair, initCapture, isBindingRef, kMeans, loadSpec, logGovernanceVerdict, queryClusterMembers, queryComponentFactors, queryExperimentResults, queryExperimentSummaries, queryFactorDelta, queryFactorHistory, queryFactors, queryGovernanceLog, queryRecentGovernanceLog, queryUserCluster, resolveAllSources, resolveBinding, resolveComponentPath, resolveProps, resolveTextWithBindings, runGovernanceCheck, startExperiment, validateSpec };

package/dist/index.d.ts

@@ -13,6 +13,10 @@ interface CaptureAdapter {
     loadSessionId(): string | null;
     clearSessionId(): void;
     registerUnloadHandler(onUnload: () => void): void;
+    /** Persist queued events to survive app restarts. JSON string of event array. */
+    persistQueue?(serialized: string): void;
+    /** Load previously persisted queue. Returns null if empty. */
+    loadQueue?(): string | null;
 }
 
 type EventType = "click" | "scroll" | "error" | "navigation" | "impression" | "input" | "focus" | "blur" | "submit" | "resize" | "visibility" | "rage_click" | "dead_click" | "scroll_reversal";
@@ -309,20 +313,45 @@ interface KMeansResult {
  */
 declare function kMeans(points: number[][], k: number, seed?: number): KMeansResult;
 
-/**
- * Flag evaluation: reads experiment assignments for the current user.
- * If not yet assigned to a running experiment, assigns deterministically via hash bucketing.
- * Optional platform parameter filters experiments to those targeting the current platform.
- */
-declare function evaluateFlag(supabase: SupabaseClient, experimentName: string, platform?: Platform): Promise<ExperimentAssignment | null>;
-
 type TargetingOperator = "gt" | "gte" | "lt" | "lte" | "eq";
-interface TargetingRule {
+interface FactorTargetingRule {
+    type: "factor";
+    factor: string;
+    operator: TargetingOperator;
+    threshold: number;
+}
+type MetadataField = "os_name" | "os_version" | "manufacturer" | "model" | "app_version" | "app_build" | "platform";
+type MetadataOperator = "eq" | "neq" | "contains" | "gte" | "lte";
+interface MetadataTargetingRule {
+    type: "metadata";
+    field: MetadataField;
+    operator: MetadataOperator;
+    value: string;
+}
+/** Legacy format (factor-only) for backward compatibility with existing experiments */
+interface LegacyTargetingRule {
     factor: string;
     operator: TargetingOperator;
     threshold: number;
 }
-declare function evaluateTargeting(factors: Factor[], rules: TargetingRule[]): boolean;
+type TargetingRule = FactorTargetingRule | MetadataTargetingRule | LegacyTargetingRule;
+interface DeviceMetadata {
+    os_name?: string;
+    os_version?: string;
+    manufacturer?: string;
+    model?: string;
+    app_version?: string;
+    app_build?: string;
+    platform?: string;
+}
+declare function evaluateTargeting(factors: Factor[], rules: TargetingRule[], deviceMetadata?: DeviceMetadata): boolean;
+
+/**
+ * Flag evaluation: reads experiment assignments for the current user.
+ * If not yet assigned to a running experiment, assigns deterministically via hash bucketing.
+ * Optional platform parameter filters experiments to those targeting the current platform.
+ */
+declare function evaluateFlag(supabase: SupabaseClient, experimentName: string, platform?: Platform, deviceMetadata?: DeviceMetadata): Promise<ExperimentAssignment | null>;
 
 interface VariantDefinition {
     variant_key: string;
@@ -557,4 +586,4 @@ declare function generateEd25519Keypair(): Promise<{
     privateKey: string;
 }>;
 
-export { type ActionHandler, type ActionRef, type ActionRegistry, type ButtonProps, type CaptureAdapter, type CaptureEvent, type CaptureHandle, type CardProps, type ChipProps, type ComponentFactorAggregate, type ComponentRegistry, type ComponentRenderer, type Config, type CreatedExperiment, type DataSourceCache, type DataSourceConfig, type DataSourceRegistry, type DividerProps, type EventType, type ExperimentAssignment, type ExperimentDefinition, type ExperimentSummaryFilters, type ExperimentSummaryRow, type Factor, type FactorDelta, type FactorSnapshot, type FactorTier, type FactorVerdict, type GovernanceAction, type GovernanceLogRow, type GovernanceVerdict, type GridProps, type IconProps, type ImageProps, type KMeansResult, type KVStorage, type LayoutProps, type ListProps, type LoadedSpec, type ModalProps, type Platform, RENDERER_VERSION, type ResolvedSources, type ScrollViewProps, type SelectProps, type Session, type SignatureVerifier, type SignedSpec, type SliderProps, type SpacerProps, type Spec, type SpecNode, type SpecNodeType, type SpecSigner, type SpecStorage, type SpecValue, type TabsProps, type TargetingOperator, type TargetingRule, type TextInputProps, type TextProps, type Threshold, type ToggleProps, type UserCluster, type VariantDefinition, type VariantResult, buildFactorDashboardSpec, componentFactorSource, concludeExperiment, createDataSourceCache, createEd25519Signer, createEd25519Verifier, createExperiment, createSpecStorage, createWebAdapter, devSignatureVerifier, dispatchAction, evaluateExperimentThresholds, evaluateFlag, evaluateTargeting, factorHistorySource, factorSource, generateEd25519Keypair, initCapture, isBindingRef, kMeans, loadSpec, logGovernanceVerdict, queryClusterMembers, queryComponentFactors, queryExperimentResults, queryExperimentSummaries, queryFactorDelta, queryFactorHistory, queryFactors, queryGovernanceLog, queryRecentGovernanceLog, queryUserCluster, resolveAllSources, resolveBinding, resolveComponentPath, resolveProps, resolveTextWithBindings, runGovernanceCheck, startExperiment, validateSpec };
+export { type ActionHandler, type ActionRef, type ActionRegistry, type ButtonProps, type CaptureAdapter, type CaptureEvent, type CaptureHandle, type CardProps, type ChipProps, type ComponentFactorAggregate, type ComponentRegistry, type ComponentRenderer, type Config, type CreatedExperiment, type DataSourceCache, type DataSourceConfig, type DataSourceRegistry, type DeviceMetadata, type DividerProps, type EventType, type ExperimentAssignment, type ExperimentDefinition, type ExperimentSummaryFilters, type ExperimentSummaryRow, type Factor, type FactorDelta, type FactorSnapshot, type FactorTargetingRule, type FactorTier, type FactorVerdict, type GovernanceAction, type GovernanceLogRow, type GovernanceVerdict, type GridProps, type IconProps, type ImageProps, type KMeansResult, type KVStorage, type LayoutProps, type ListProps, type LoadedSpec, type MetadataField, type MetadataOperator, type MetadataTargetingRule, type ModalProps, type Platform, RENDERER_VERSION, type ResolvedSources, type ScrollViewProps, type SelectProps, type Session, type SignatureVerifier, type SignedSpec, type SliderProps, type SpacerProps, type Spec, type SpecNode, type SpecNodeType, type SpecSigner, type SpecStorage, type SpecValue, type TabsProps, type TargetingOperator, type TargetingRule, type TextInputProps, type TextProps, type Threshold, type ToggleProps, type UserCluster, type VariantDefinition, type VariantResult, buildFactorDashboardSpec, componentFactorSource, concludeExperiment, createDataSourceCache, createEd25519Signer, createEd25519Verifier, createExperiment, createSpecStorage, createWebAdapter, devSignatureVerifier, dispatchAction, evaluateExperimentThresholds, evaluateFlag, evaluateTargeting, factorHistorySource, factorSource, generateEd25519Keypair, initCapture, isBindingRef, kMeans, loadSpec, logGovernanceVerdict, queryClusterMembers, queryComponentFactors, queryExperimentResults, queryExperimentSummaries, queryFactorDelta, queryFactorHistory, queryFactors, queryGovernanceLog, queryRecentGovernanceLog, queryUserCluster, resolveAllSources, resolveBinding, resolveComponentPath, resolveProps, resolveTextWithBindings, runGovernanceCheck, startExperiment, validateSpec };

package/dist/index.js

@@ -39,7 +39,7 @@ function createSessionManager(supabase, adapter, platform, timeoutMs = DEFAULT_T
 // src/capture/writer.ts
 var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_FLUSH_BATCH_SIZE = 50;
-function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS, flushBatchSize = DEFAULT_FLUSH_BATCH_SIZE) {
+function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS, flushBatchSize = DEFAULT_FLUSH_BATCH_SIZE, adapter) {
   let queue = [];
   let flushTimer = null;
   let isFlushing = false;
@@ -63,15 +63,37 @@ function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS
       const { error } = await supabase.from("events").insert(batch);
       if (error) {
         queue.unshift(...batch);
+        persistQueueToAdapter();
         console.error("factoredui: flush failed:", error.message);
       }
     } catch (err) {
       queue.unshift(...batch);
+      persistQueueToAdapter();
       console.error("factoredui: flush error:", err);
     } finally {
       isFlushing = false;
     }
   }
+  function persistQueueToAdapter() {
+    if (!adapter?.persistQueue || queue.length === 0) return;
+    try {
+      adapter.persistQueue(JSON.stringify(queue));
+    } catch {
+    }
+  }
+  function drainPersistedQueue() {
+    if (!adapter?.loadQueue) return;
+    try {
+      const serialized = adapter.loadQueue();
+      if (!serialized) return;
+      const persisted = JSON.parse(serialized);
+      if (persisted.length > 0) {
+        queue.unshift(...persisted);
+        adapter.persistQueue?.("");
+      }
+    } catch {
+    }
+  }
   function startAutoFlush() {
     if (flushTimer) return;
     flushTimer = setInterval(flush, flushIntervalMs);
@@ -82,7 +104,7 @@ function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS
       flushTimer = null;
     }
   }
-  return { enqueue, flush, startAutoFlush, stopAutoFlush };
+  return { enqueue, flush, startAutoFlush, stopAutoFlush, drainPersistedQueue };
 }
 
 // src/capture/path.ts
@@ -159,6 +181,7 @@ function detectScrollReversal(state, scrollY, now) {
 var THROTTLE_INTERVAL_MS = 100;
 var DEAD_CLICK_WAIT_MS = 1e3;
 var SESSION_STORAGE_KEY = "factoredui:session_id";
+var QUEUE_STORAGE_KEY = "factoredui:offline_queue";
 function createWebAdapter() {
   const handlers = /* @__PURE__ */ new Map();
   const rageClickState = createRageClickState();
@@ -243,9 +266,28 @@ function createWebAdapter() {
     storeSessionId,
     loadSessionId,
     clearSessionId,
-    registerUnloadHandler
+    registerUnloadHandler,
+    persistQueue,
+    loadQueue
   };
 }
+function persistQueue(serialized) {
+  try {
+    if (!serialized || serialized === "") {
+      localStorage.removeItem(QUEUE_STORAGE_KEY);
+    } else {
+      localStorage.setItem(QUEUE_STORAGE_KEY, serialized);
+    }
+  } catch {
+  }
+}
+function loadQueue() {
+  try {
+    return localStorage.getItem(QUEUE_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
 function collectSessionMetadata() {
   if (typeof window === "undefined") return {};
   return {
@@ -767,10 +809,10 @@ function createSeededRng(seed) {
 }
 
 // src/experiment/targeting.ts
-function evaluateTargeting(factors, rules) {
+function evaluateTargeting(factors, rules, deviceMetadata) {
   if (rules.length === 0) return true;
   const factorsByName = indexFactorsByName(factors);
-  return rules.every((rule) => evaluateRule(factorsByName, rule));
+  return rules.every((rule) => evaluateRule(factorsByName, rule, deviceMetadata));
 }
 function indexFactorsByName(factors) {
   const indexed = /* @__PURE__ */ new Map();
@@ -779,12 +821,32 @@ function indexFactorsByName(factors) {
   }
   return indexed;
 }
-function evaluateRule(factorsByName, rule) {
-  const value = factorsByName.get(rule.factor);
-  if (value === void 0) return false;
-  return compareValue(value, rule.operator, rule.threshold);
+function isMetadataRule(rule) {
+  return "type" in rule && rule.type === "metadata";
+}
+function isFactorRule(rule) {
+  return !("type" in rule) || rule.type === "factor";
+}
+function evaluateRule(factorsByName, rule, deviceMetadata) {
+  if (isMetadataRule(rule)) {
+    return evaluateMetadataRule(rule, deviceMetadata);
+  }
+  if (isFactorRule(rule)) {
+    const threshold = "threshold" in rule ? rule.threshold : 0;
+    const factorName = rule.factor;
+    const value = factorsByName.get(factorName);
+    if (value === void 0) return false;
+    return compareNumeric(value, rule.operator, threshold);
+  }
+  return false;
+}
+function evaluateMetadataRule(rule, metadata) {
+  if (!metadata) return false;
+  const fieldValue = metadata[rule.field];
+  if (fieldValue === void 0 || fieldValue === null) return false;
+  return compareString(fieldValue, rule.operator, rule.value);
 }
-function compareValue(value, operator, threshold) {
+function compareNumeric(value, operator, threshold) {
   switch (operator) {
     case "gt":
       return value > threshold;
@@ -798,9 +860,25 @@ function compareValue(value, operator, threshold) {
       return value === threshold;
   }
 }
+function compareString(value, operator, target) {
+  const lower = value.toLowerCase();
+  const targetLower = target.toLowerCase();
+  switch (operator) {
+    case "eq":
+      return lower === targetLower;
+    case "neq":
+      return lower !== targetLower;
+    case "contains":
+      return lower.includes(targetLower);
+    case "gte":
+      return lower >= targetLower;
+    case "lte":
+      return lower <= targetLower;
+  }
+}
 
 // src/experiment/flags.ts
-async function evaluateFlag(supabase, experimentName, platform) {
+async function evaluateFlag(supabase, experimentName, platform, deviceMetadata) {
   const userId = await resolveUserId2(supabase);
   if (!userId) return null;
   const existingAssignment = await fetchAssignment(supabase, userId, experimentName);
@@ -808,7 +886,7 @@ async function evaluateFlag(supabase, experimentName, platform) {
     await recordExposure(supabase, userId, existingAssignment);
     return existingAssignment;
   }
-  const newAssignment = await assignToExperiment(supabase, userId, experimentName, platform);
+  const newAssignment = await assignToExperiment(supabase, userId, experimentName, platform, deviceMetadata);
   if (newAssignment) {
     await recordExposure(supabase, userId, newAssignment);
   }
@@ -833,10 +911,17 @@ async function fetchAssignment(supabase, userId, experimentName) {
     config: row.experiment_variants?.config ?? {}
   };
 }
-async function assignToExperiment(supabase, userId, experimentName, platform) {
+async function assignToExperiment(supabase, userId, experimentName, platform, deviceMetadata) {
   const experiment = await fetchRunningExperiment(supabase, experimentName, platform);
   if (!experiment) return null;
-  const isTargeted = await checkTargeting(supabase, userId, experiment);
+  const hasConflict = await hasConflictingAssignment(
+    supabase,
+    userId,
+    experiment.component_path,
+    experiment.id
+  );
+  if (hasConflict) return null;
+  const isTargeted = await checkTargeting(supabase, userId, experiment, deviceMetadata);
   if (!isTargeted) return null;
   const variants = await fetchExperimentVariants(supabase, experiment.id);
   if (variants.length === 0) return null;
@@ -854,6 +939,11 @@ async function assignToExperiment(supabase, userId, experimentName, platform) {
     config: selectedVariant.config
   };
 }
+async function hasConflictingAssignment(supabase, userId, componentPath, currentExperimentId) {
+  const { data, error } = await supabase.from("experiment_assignments").select("experiment_id, experiments!inner ( id, status, component_path )").eq("user_id", userId).eq("experiments.status", "running").eq("experiments.component_path", componentPath).neq("experiment_id", currentExperimentId).limit(1);
+  if (error) return false;
+  return (data?.length ?? 0) > 0;
+}
 async function fetchRunningExperiment(supabase, experimentName, platform) {
   const { data, error } = await supabase.from("experiments").select("id, name, component_path, targeting_rules, platforms").eq("name", experimentName).eq("status", "running").maybeSingle();
   if (error || !data) return null;
@@ -863,10 +953,10 @@ async function fetchRunningExperiment(supabase, experimentName, platform) {
   }
   return experiment;
 }
-async function checkTargeting(supabase, userId, experiment) {
+async function checkTargeting(supabase, userId, experiment, deviceMetadata) {
   if (!experiment.targeting_rules || experiment.targeting_rules.length === 0) return true;
   const factors = await queryFactors(supabase, userId, experiment.component_path);
-  return evaluateTargeting(factors, experiment.targeting_rules);
+  return evaluateTargeting(factors, experiment.targeting_rules, deviceMetadata);
 }
 async function fetchExperimentVariants(supabase, experimentId) {
   const { data, error } = await supabase.from("experiment_variants").select("variant_key, config, traffic_percentage").eq("experiment_id", experimentId).order("variant_key");
@@ -908,8 +998,11 @@ async function createExperiment(client, definition) {
   return experiment;
 }
 async function startExperiment(client, experimentId) {
-  const { error } = await client.from("experiments").update({ status: "running" }).eq("id", experimentId).eq("status", "draft");
+  const { data, error } = await client.from("experiments").update({ status: "running" }).eq("id", experimentId).eq("status", "draft").select("id");
   if (error) throw new Error(`startExperiment failed: ${error.message}`);
+  if (!data || data.length === 0) {
+    throw new Error(`startExperiment: experiment ${experimentId} not found or not in draft status`);
+  }
 }
 function validateDefinition(definition) {
   if (definition.variants.length < 2) {