@avsbhq/node 1.7.2 → 1.9.0

package/dist/index.js

@@ -1,23 +1,3 @@
-// src/AvsbServer.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import { evaluateFlag } from "@avsbhq/core/engine";
-import {
-  toLegacyEvalContext,
-  createFlag,
-  notFoundFlag as notFoundFlag2,
-  notReadyFlag,
-  mapLegacySource,
-  checkExpectedType,
-  findDatafileFlag,
-  contextSummary,
-  privateAttributesFrom,
-  bucketingKey as bucketingKey2,
-  resolveStreamEndpoint
-} from "@avsbhq/core";
-import { validateSdkKeyShape } from "@avsbhq/utils/sdkKey";
-import { jitteredInterval } from "@avsbhq/utils/backoff";
-import { redactExposure } from "@avsbhq/utils/exposure";
-
 // src/datasets.ts
 var DEFAULT_REQUEST_TIMEOUT = 1e4;
 function miss(slug, version) {
@@ -352,6 +332,126 @@ function appendDecisionLogEntry(log, input) {
   return entry;
 }
 
+// src/AvsbServer.ts
+import { bucketingKey as bucketingKey4 } from "@avsbhq/core";
+
+// src/UserBoundClient.ts
+import { bucketingKey } from "@avsbhq/core";
+function createUserBoundClient(server, context) {
+  const decisionLog = createDecisionLog();
+  const forcedDecisions = /* @__PURE__ */ new Map();
+  function evaluate(flagKey, defaultValue, expectedType, options) {
+    const forced = forcedDecisions.get(flagKey);
+    return server.evaluateInternal(flagKey, defaultValue, context, {
+      decideOptions: options?.decideOptions,
+      // A caller may point one evaluation at their own log; the bound log is
+      // the default so `getDecisionLog()` is complete without extra wiring.
+      decisionLog: options?.decisionLog ?? decisionLog,
+      ...expectedType ? { expectedType } : {},
+      ...forced ? { forcedVariationKey: forced.variationKey } : {}
+    });
+  }
+  return {
+    getFlag(flagKey, defaultValue, options) {
+      return evaluate(flagKey, defaultValue, void 0, options);
+    },
+    getBoolFlag(flagKey, defaultValue, options) {
+      return evaluate(flagKey, defaultValue, "boolean", options);
+    },
+    getStringFlag(flagKey, defaultValue, options) {
+      return evaluate(flagKey, defaultValue, "string", options);
+    },
+    getNumberFlag(flagKey, defaultValue, options) {
+      return evaluate(flagKey, defaultValue, "number", options);
+    },
+    getJsonFlag(flagKey, defaultValue, options) {
+      return evaluate(flagKey, defaultValue, "json", options);
+    },
+    getAllFlags(options) {
+      return server.getAllFlags(context, {
+        ...options,
+        decisionLog: options?.decisionLog ?? decisionLog
+      });
+    },
+    track(eventKey, payload) {
+      server.track(eventKey, { ...payload, context });
+    },
+    trackPurchase(order) {
+      return server.trackPurchase(bucketingKey(context), order);
+    },
+    manualExposure(flagKey) {
+      server.manualExposure(flagKey, context);
+    },
+    getContext() {
+      return context;
+    },
+    setForcedDecision(flagKey, opts) {
+      forcedDecisions.set(flagKey, opts);
+    },
+    clearForcedDecision(flagKey) {
+      forcedDecisions.delete(flagKey);
+    },
+    getDecisionLog() {
+      return decisionLog;
+    }
+  };
+}
+
+// src/utils.ts
+import { createUtils } from "@avsbhq/utils";
+import { notFoundFlag } from "@avsbhq/core";
+function buildServerUtils(server) {
+  const adapter = {
+    getFlag(flagKey, defaultValue) {
+      return notFoundFlag(
+        defaultValue,
+        "no bound context: call server.forUser(context) and use its flag methods"
+      );
+    },
+    getAllFlags(opts) {
+      const ctx = opts?.context;
+      if (!ctx) return {};
+      return server.getAllFlags(ctx, {
+        fireExposures: opts.fireExposures
+      });
+    },
+    track(eventKey, payload) {
+      if (!payload?.context) return;
+      server.track(eventKey, {
+        ...payload,
+        context: payload.context
+      });
+    },
+    on(event, cb) {
+      return server.on(event, cb);
+    },
+    getDatafile: () => server.getDatafile(),
+    getCurrentContext: () => null,
+    /**
+     * `snapshotFresh` and `refreshAndSnapshot` call this before they read, so
+     * a "fresh" snapshot really is taken against the datafile published right
+     * now. Without it both helpers quietly returned the in-memory datafile.
+     */
+    refresh: () => server.refreshDatafile(),
+    /**
+     * Real, not a comment: `client.utils.hydrateBootstrap(blob)` on the server
+     * adopts the blob's datafile and marks the SDK ready. That is the
+     * serverless cold-start path (read a datafile from KV or a file, hand it
+     * over, evaluate on the same tick).
+     */
+    applyDatafile: (df) => server.applyDatafileBootstrap(df)
+    // `applySnapshot` is deliberately ABSENT. A snapshot carries one context's
+    // evaluated values, and this client evaluates a different context per
+    // request, so adopting one process-wide would serve user A's values to user
+    // B. hydrateBootstrap throws with that explanation when it is handed a
+    // snapshot-only blob here, instead of quietly ignoring it.
+  };
+  return createUtils(adapter);
+}
+
+// src/serverState.ts
+import { validateSdkKeyShape } from "@avsbhq/utils/sdkKey";
+
 // src/decideOptions.ts
 import { DecideOption } from "@avsbhq/core";
 var KNOWN = Object.values(DecideOption);
@@ -427,7 +527,7 @@ function createOverrideStore() {
 }
 
 // src/datafileSource.ts
-import { datafileUrl, resolveHeartbeatEndpoint } from "@avsbhq/core";
+import { datafileShapeProblem, datafileUrl, resolveHeartbeatEndpoint } from "@avsbhq/core";
 async function fetchDatafile(input) {
   const url = datafileUrl(input.sdkKey, input.cdnHost);
   const headers = {};
@@ -441,8 +541,15 @@ async function fetchDatafile(input) {
       );
       return { status: "failed" };
     }
-    const datafile = await response.json();
-    return { status: "ok", datafile, etag: response.headers.get("etag") };
+    const body = await response.json();
+    const problem = datafileShapeProblem(body);
+    if (problem) {
+      input.logger.error(
+        `AvsB datafile from ${url} is not a datafile the SDK can read: ${problem}. The SDK keeps serving whatever datafile it already has and retries on the polling interval.`
+      );
+      return { status: "failed" };
+    }
+    return { status: "ok", datafile: body, etag: response.headers.get("etag") };
   } catch (error) {
     if (input.signal.aborted) return { status: "aborted" };
     input.logger.error(
@@ -451,6 +558,14 @@ async function fetchDatafile(input) {
     return { status: "failed" };
   }
 }
+function acceptDatafile(candidate, origin, logger) {
+  const problem = datafileShapeProblem(candidate);
+  if (problem === null) return candidate;
+  logger.error(
+    origin === "bootstrap" ? `AvsB ignored the bootstrap datafile passed to new AvsbServer(): ${problem}. Flags return the default you passed, with source "not_ready", until a datafile loads from the CDN. Pass the datafile JSON exactly as the CDN serves it for this SDK key.` : `AvsB ignored the datafile passed to applyDatafileBootstrap(): ${problem}. The SDK keeps serving the datafile it already has, if any. Pass the datafile JSON exactly as the CDN serves it for this SDK key.`
+  );
+  return null;
+}
 function sendHeartbeat(input) {
   const endpoint = resolveHeartbeatEndpoint(input.datafileHeartbeatEndpoint);
   if (!endpoint) return null;
@@ -494,6 +609,119 @@ function resolveServerLogger(options) {
   return defaultLogger();
 }
 
+// src/serverState.ts
+var DEFAULT_EVENTS = {
+  flushInterval: 2e3,
+  batchSize: 10,
+  maxQueueSize: 1e4,
+  retryAttempts: 3
+};
+function createServerState(options) {
+  const logger = resolveServerLogger(options);
+  const datafile = options.bootstrap ? acceptDatafile(options.bootstrap, "bootstrap", logger) : null;
+  const state = {
+    sdkKey: options.sdkKey,
+    pollingInterval: Math.max(options.pollingInterval ?? 6e4, 5e3),
+    cdnHost: options.cdnHost,
+    initTimeout: options.initTimeout ?? 1e4,
+    logger,
+    stickyBucketService: options.stickyBucketService ?? null,
+    eventOptions: { ...DEFAULT_EVENTS, ...options.events },
+    // Streaming is ON by default on the server (B12). Resolution happens once
+    // a datafile exists, because the endpoint is a datafile field.
+    streamingEnabled: options.streaming !== false,
+    streamingEndpointOption: options.streamingEndpoint ?? null,
+    overrides: createOverrideStore(),
+    resolveDecideOptions: createDecideOptionResolver(logger),
+    datafile,
+    datafileEtag: null,
+    ready: datafile !== null,
+    destroyed: false,
+    tracker: null,
+    streamingClient: null,
+    pollingTimer: null,
+    abortController: new AbortController(),
+    listeners: /* @__PURE__ */ new Map(),
+    readyPromise: null,
+    pendingEvents: [],
+    pendingPurchases: [],
+    pendingExposures: [],
+    lastHeartbeatAt: 0,
+    warnedOnce: /* @__PURE__ */ new Set()
+  };
+  const keyShape = validateSdkKeyShape(state.sdkKey);
+  if (!keyShape.valid && keyShape.message) {
+    logger.error(keyShape.message);
+  }
+  return state;
+}
+function warnOnce(s, key, message) {
+  if (s.warnedOnce.has(key)) return;
+  s.warnedOnce.add(key);
+  s.logger.warn(message);
+}
+function emit(s, event, ...args) {
+  const cbs = s.listeners.get(event);
+  if (!cbs) return;
+  for (const cb of cbs) {
+    try {
+      ;
+      cb(...args);
+    } catch (e) {
+      s.logger.error("Listener error", { event, error: String(e) });
+    }
+  }
+}
+function addListener(s, event, cb) {
+  if (!s.listeners.has(event)) s.listeners.set(event, /* @__PURE__ */ new Set());
+  s.listeners.get(event).add(cb);
+  return () => {
+    s.listeners.get(event)?.delete(cb);
+  };
+}
+function onSharedEvent(s, server, event, cb) {
+  if (event === "flagChange") {
+    warnOnce(
+      s,
+      "no-flag-change",
+      'The server SDK does not emit "flagChange": it holds one datafile for the whole process and does not diff individual flags. Subscribe to "configUpdate" for "a new datafile was published" instead.'
+    );
+    return () => void 0;
+  }
+  return server.on(
+    event,
+    cb
+  );
+}
+
+// src/serverDatafile.ts
+import { jitteredInterval } from "@avsbhq/utils/backoff";
+
+// src/initTimeout.ts
+async function raceInitTimeout(work, timeoutMs) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs);
+    if (typeof timer === "object" && timer !== null && "unref" in timer) timer.unref();
+  });
+  try {
+    return await Promise.race([
+      work.then((value) => ({ timedOut: false, value })),
+      timeout
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/version.ts
+var SDK_VERSION = "1.9.0";
+var SDK_TYPE = "@avsbhq/node";
+
+// src/serverTracking.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { bucketingKey as bucketingKey2 } from "@avsbhq/core";
+
 // src/serverTracker.ts
 import { randomUUID } from "crypto";
 import { collectUrl } from "@avsbhq/core";
@@ -608,7 +836,7 @@ function createServerTracker(options) {
       }
     }
   }
-  async function trackPurchase(visitorId, order) {
+  async function trackPurchase2(visitorId, order) {
     if (destroyed) return;
     const payload = {
       ...order,
@@ -657,169 +885,632 @@ function createServerTracker(options) {
     }
     await flush();
   }
-  return { queue, queueMetric, trackPurchase, flush, destroy };
+  return { queue, queueMetric, trackPurchase: trackPurchase2, flush, destroy };
+}
+
+// src/serverTracking.ts
+function trackMetric(s, eventKey, payload) {
+  if (payload.properties) {
+    warnOnce(
+      s,
+      "track-properties",
+      `track("${eventKey}") was called with properties, which are NOT stored for metric events: the ingestion contract for a conversion keeps the event name, the numeric value, the timestamp, and the visitor id. Exposure events do carry properties. Nothing else about the call is affected.`
+    );
+  }
+  if (!s.tracker) {
+    enqueuePending(s, eventKey, payload);
+    return;
+  }
+  s.tracker.queueMetric({
+    visitorId: bucketingKey2(payload.context),
+    eventName: eventKey,
+    // TWO columns, not one. `revenue` is money in decimal major units;
+    // `value` is the numeric metric value for average-value metrics. Storage
+    // declares both (`metric_events.revenue`, `metric_events.value`). This
+    // SDK used to ship `payload.value` into the revenue column and could
+    // never write the value column at all, so a quantity was recorded as
+    // money and every average-value metric read empty.
+    revenue: payload.revenue ?? null,
+    value: payload.value ?? null,
+    timestamp: Date.now(),
+    pageUrl: ""
+  });
+}
+async function trackPurchase(s, visitorId, order) {
+  if (s.destroyed) return;
+  if (!s.tracker) {
+    if (s.pendingPurchases.length >= s.eventOptions.maxQueueSize) {
+      s.pendingPurchases.shift();
+      warnOnce(
+        s,
+        "pending-purchase-full",
+        `Pre-ready purchase queue reached ${s.eventOptions.maxQueueSize} orders; the oldest is being dropped. This means the datafile never loaded: check the datafile error logged above.`
+      );
+    }
+    s.pendingPurchases.push({ visitorId, order });
+    return;
+  }
+  return s.tracker.trackPurchase(visitorId, order);
+}
+function deliverExposure(s, event) {
+  const stamped = event.eventId ? event : { ...event, eventId: randomUUID2() };
+  if (s.tracker) {
+    s.tracker.queue(stamped);
+  } else {
+    enqueuePendingExposure(s, stamped);
+  }
+  emit(s, "exposure", stamped);
+}
+function initTracker(s, server) {
+  if (!s.datafile || s.tracker) return;
+  const tracker = createServerTracker({
+    sdkKey: s.sdkKey,
+    collectEndpoint: s.datafile.collectEndpoint,
+    flushInterval: s.eventOptions.flushInterval,
+    batchSize: s.eventOptions.batchSize,
+    maxQueueSize: s.eventOptions.maxQueueSize,
+    retryAttempts: s.eventOptions.retryAttempts,
+    logger: s.logger
+  });
+  s.tracker = tracker;
+  if (s.pendingExposures.length > 0) {
+    const queued = s.pendingExposures;
+    s.pendingExposures = [];
+    for (const event of queued) tracker.queue(event);
+  }
+  if (s.pendingEvents.length > 0) {
+    const queued = s.pendingEvents;
+    s.pendingEvents = [];
+    for (const item of queued) server.track(item.eventKey, item.payload);
+  }
+  if (s.pendingPurchases.length > 0) {
+    const queued = s.pendingPurchases;
+    s.pendingPurchases = [];
+    for (const item of queued) void server.trackPurchase(item.visitorId, item.order);
+  }
+}
+function enqueuePendingExposure(s, event) {
+  if (s.pendingExposures.length >= s.eventOptions.maxQueueSize) {
+    s.pendingExposures.shift();
+    warnOnce(
+      s,
+      "pending-exposures-full",
+      `Pre-ready exposure queue reached ${s.eventOptions.maxQueueSize} events; the oldest are being dropped. This means the datafile never loaded, so nothing has been delivered yet: check the datafile error logged above.`
+    );
+  }
+  s.pendingExposures.push(event);
+}
+function enqueuePending(s, eventKey, payload) {
+  if (s.pendingEvents.length >= s.eventOptions.maxQueueSize) {
+    s.pendingEvents.shift();
+    warnOnce(
+      s,
+      "pending-events-full",
+      `Pre-ready event queue reached ${s.eventOptions.maxQueueSize} events; the oldest are being dropped. This means the datafile never loaded, so nothing has been delivered yet: check the datafile error logged above.`
+    );
+  }
+  s.pendingEvents.push({ eventKey, payload });
 }
 
+// src/serverStreaming.ts
+import { resolveStreamEndpoint } from "@avsbhq/core";
+
 // src/streaming.ts
 import {
   createStreamingClient,
   createBrowserStreamingClient
 } from "@avsbhq/utils/streaming";
 
-// src/version.ts
-var SDK_VERSION = "1.7.1";
+// src/serverStreaming.ts
+function startStreamingIfEnabled(s, onDatafileUpdated) {
+  if (!s.streamingEnabled || s.streamingClient || s.destroyed) return;
+  const resolution = resolveStreamEndpoint({
+    optionEndpoint: s.streamingEndpointOption,
+    datafileStreamEndpoint: s.datafile?.streamEndpoint ?? null
+  });
+  if (!resolution.available) {
+    s.logger.debug(`Streaming stays off, polling continues. ${resolution.reason}`);
+    return;
+  }
+  s.streamingClient = createStreamingClient({
+    endpoint: resolution.endpoint,
+    sdkKey: s.sdkKey,
+    onDatafileUpdated,
+    logger: s.logger
+  });
+  s.streamingClient.connect();
+  s.logger.debug(
+    `Streaming datafile updates from ${resolution.endpoint} (${resolution.source}).`
+  );
+}
 
-// src/UserBoundClient.ts
-import { bucketingKey } from "@avsbhq/core";
-function createUserBoundClient(server, context) {
-  const decisionLog = createDecisionLog();
-  const forcedDecisions = /* @__PURE__ */ new Map();
-  function evaluate(flagKey, defaultValue, expectedType, options) {
-    const forced = forcedDecisions.get(flagKey);
-    return server.evaluateInternal(flagKey, defaultValue, context, {
-      decideOptions: options?.decideOptions,
-      // A caller may point one evaluation at their own log; the bound log is
-      // the default so `getDecisionLog()` is complete without extra wiring.
-      decisionLog: options?.decisionLog ?? decisionLog,
-      ...expectedType ? { expectedType } : {},
-      ...forced ? { forcedVariationKey: forced.variationKey } : {}
-    });
+// src/serverDatafile.ts
+var HEARTBEAT_MIN_INTERVAL_MS = 12e4;
+async function initializeAndReady(s, server) {
+  if (s.ready && s.datafile) {
+    onDatafileReadable(s, server);
+    return { success: true, source: "bootstrap" };
   }
-  return {
-    getFlag(flagKey, defaultValue, options) {
-      return evaluate(flagKey, defaultValue, void 0, options);
-    },
-    getBoolFlag(flagKey, defaultValue, options) {
-      return evaluate(flagKey, defaultValue, "boolean", options);
-    },
-    getStringFlag(flagKey, defaultValue, options) {
-      return evaluate(flagKey, defaultValue, "string", options);
-    },
-    getNumberFlag(flagKey, defaultValue, options) {
-      return evaluate(flagKey, defaultValue, "number", options);
-    },
-    getJsonFlag(flagKey, defaultValue, options) {
-      return evaluate(flagKey, defaultValue, "json", options);
-    },
-    getAllFlags(options) {
-      return server.getAllFlags(context, {
-        ...options,
-        decisionLog: options?.decisionLog ?? decisionLog
-      });
-    },
-    track(eventKey, payload) {
-      server.track(eventKey, { ...payload, context });
-    },
-    trackPurchase(order) {
-      return server.trackPurchase(bucketingKey(context), order);
-    },
-    manualExposure(flagKey) {
-      server.manualExposure(flagKey, context);
-    },
-    getContext() {
-      return context;
-    },
-    setForcedDecision(flagKey, opts) {
-      forcedDecisions.set(flagKey, opts);
-    },
-    clearForcedDecision(flagKey) {
-      forcedDecisions.delete(flagKey);
-    },
-    getDecisionLog() {
-      return decisionLog;
+  try {
+    const outcome = await raceInitTimeout(
+      // At init there is no stored etag, so 'unchanged' cannot happen here;
+      // it is folded in anyway so a future caching layer cannot make init
+      // silently report failure.
+      loadDatafile(s).then((result) => result !== "failed"),
+      s.initTimeout
+    );
+    if (outcome.timedOut) {
+      startPolling(s, server);
+      const error2 = new Error(
+        `AvsB init timed out after ${s.initTimeout}ms waiting for the datafile. Polling continues in the background, so flags start working as soon as the request completes; raise initTimeout if your cold start is slower.`
+      );
+      emit(s, "error", error2);
+      return { success: false, source: "timeout", error: error2 };
     }
-  };
+    if (outcome.value) {
+      onDatafileReadable(s, server);
+      return { success: true, source: "network" };
+    }
+    startPolling(s, server);
+    const error = new Error(
+      'AvsB init failed: no datafile could be loaded, so every flag serves the default you passed and flag.source is "not_ready". The datafile request error is logged above with the URL and status. Polling continues.'
+    );
+    emit(s, "error", error);
+    return { success: false, source: "error", error };
+  } catch (e) {
+    startPolling(s, server);
+    const error = e instanceof Error ? e : new Error(String(e));
+    emit(s, "error", error);
+    return { success: false, source: "error", error };
+  }
+}
+function onDatafileReadable(s, server) {
+  initTracker(s, server);
+  s.ready = true;
+  startPolling(s, server);
+  startStreamingIfEnabled(s, () => {
+    void loadDatafile(s, "stream");
+  });
+  sendHeartbeat2(s);
+  emit(s, "ready");
+}
+async function closeServer(s, drainUtils) {
+  s.destroyed = true;
+  s.abortController.abort();
+  if (s.streamingClient) {
+    s.streamingClient.disconnect();
+    s.streamingClient = null;
+  }
+  if (s.pollingTimer) {
+    clearTimeout(s.pollingTimer);
+    s.pollingTimer = null;
+  }
+  if (s.tracker) {
+    await s.tracker.destroy();
+    s.tracker = null;
+  }
+  drainUtils();
+  s.datafile = null;
+  s.ready = false;
+}
+async function refreshDatafile(s, server) {
+  const result = await loadDatafile(s, "manual");
+  if (result === "failed") {
+    s.logger.warn(
+      "AvsB datafile refresh did not apply a new datafile; the SDK keeps serving the one it already has. The request error is logged above."
+    );
+    return;
+  }
+  if (result === "applied" && !s.ready) onDatafileReadable(s, server);
+}
+function applyDatafileBootstrap(s, server, datafile) {
+  if (s.destroyed) return;
+  if (!acceptDatafile(datafile, "applyDatafileBootstrap", s.logger)) return;
+  const changed = s.datafile?.publishedAt !== datafile.publishedAt;
+  s.datafile = datafile;
+  s.datafileEtag = null;
+  if (!s.ready) {
+    onDatafileReadable(s, server);
+    return;
+  }
+  initTracker(s, server);
+  if (changed) {
+    emit(s, "configUpdate", {
+      publishedAt: datafile.publishedAt,
+      reason: "manual"
+    });
+  }
+}
+async function loadDatafile(s, reason = "manual") {
+  const outcome = await fetchDatafile({
+    sdkKey: s.sdkKey,
+    cdnHost: s.cdnHost,
+    signal: s.abortController.signal,
+    logger: s.logger,
+    etag: s.datafileEtag
+  });
+  if (outcome.status === "ok" || outcome.status === "not-modified") {
+    sendHeartbeat2(s);
+  }
+  if (outcome.status === "not-modified") return "unchanged";
+  if (outcome.status !== "ok") return "failed";
+  const changed = !s.datafile || s.datafile.publishedAt !== outcome.datafile.publishedAt;
+  s.datafile = outcome.datafile;
+  s.datafileEtag = outcome.etag;
+  if (s.ready && changed) {
+    emit(s, "configUpdate", {
+      publishedAt: outcome.datafile.publishedAt,
+      reason
+    });
+    s.logger.info("Datafile updated", {
+      publishedAt: outcome.datafile.publishedAt,
+      reason
+    });
+    startStreamingIfEnabled(s, () => {
+      void loadDatafile(s, "stream");
+    });
+  }
+  return "applied";
+}
+function startPolling(s, server) {
+  if (s.pollingTimer || s.destroyed) return;
+  const schedule = () => {
+    s.pollingTimer = setTimeout(() => {
+      s.pollingTimer = null;
+      void (async () => {
+        const result = await loadDatafile(s, "poll");
+        if (result === "applied" && !s.ready) onDatafileReadable(s, server);
+        if (!s.destroyed) schedule();
+      })();
+    }, jitteredInterval(s.pollingInterval));
+  };
+  schedule();
+}
+function sendHeartbeat2(s) {
+  const now = Date.now();
+  if (now - s.lastHeartbeatAt < HEARTBEAT_MIN_INTERVAL_MS) return;
+  const posted = sendHeartbeat({
+    sdkKey: s.sdkKey,
+    sdkType: SDK_TYPE,
+    sdkVersion: SDK_VERSION,
+    datafileHeartbeatEndpoint: s.datafile?.heartbeatEndpoint,
+    signal: s.abortController.signal
+  });
+  if (posted) s.lastHeartbeatAt = now;
 }
 
-// src/utils.ts
-import { createUtils } from "@avsbhq/utils";
-import { notFoundFlag } from "@avsbhq/core";
-function buildServerUtils(server) {
-  const adapter = {
-    getFlag(flagKey, defaultValue) {
-      return notFoundFlag(
-        defaultValue,
-        "no bound context: call server.forUser(context) and use its flag methods"
-      );
-    },
-    getAllFlags(opts) {
-      const ctx = opts?.context;
-      if (!ctx) return {};
-      return server.getAllFlags(ctx, {
-        fireExposures: opts.fireExposures
-      });
-    },
-    track(eventKey, payload) {
-      if (!payload?.context) return;
-      server.track(eventKey, {
-        ...payload,
-        context: payload.context
+// src/serverEvaluation.ts
+import {
+  checkExpectedType,
+  contextSummary,
+  createFlag,
+  findDatafileFlag,
+  flagNotFoundMessage,
+  notFoundFlag as notFoundFlag2,
+  notReadyFlag
+} from "@avsbhq/core";
+
+// src/serverDecision.ts
+import { evaluateFlag } from "@avsbhq/core/engine";
+import {
+  bucketingKey as bucketingKey3,
+  mapLegacySource,
+  privateAttributesFrom,
+  toLegacyEvalContext
+} from "@avsbhq/core";
+import { redactExposure } from "@avsbhq/utils/exposure";
+function evaluateDecision(s, flagKey, uc, defaultValue) {
+  const reasons = [];
+  const overrideKey = s.overrides.resolve(flagKey, uc.userId);
+  const rtOver = overrideKey ? findVariation(s, flagKey, overrideKey) : null;
+  if (rtOver) {
+    reasons.push(`matched runtime override for flagKey="${flagKey}"`);
+    return {
+      value: rtOver.value,
+      variationKey: rtOver.key,
+      source: "runtimeOverride",
+      ruleId: null,
+      ruleType: null,
+      reasons
+    };
+  }
+  if (s.stickyBucketService) {
+    const sticky = resolveStickyBucket(s, flagKey, uc.userId);
+    if (sticky !== void 0) {
+      reasons.push(`matched sticky bucket assignment for userId="${uc.userId}"`);
+      if (!uc.suppressExposure) {
+        fireExposureForStickyAssignment(s, flagKey, sticky, uc);
+      }
+      return {
+        value: sticky.vref.value,
+        variationKey: sticky.vref.key,
+        source: "sticky",
+        ruleId: sticky.assignment.ruleId,
+        ruleType: sticky.assignment.ruleType,
+        reasons
+      };
+    }
+  }
+  const legacyCtx = { attributes: { userId: uc.userId, ...uc.attributes } };
+  const onExposure = uc.suppressExposure ? void 0 : (event) => {
+    deliverExposure(s, redactExposure(event, uc.privateAttributes));
+  };
+  const r = evaluateFlag(
+    flagKey,
+    defaultValue,
+    legacyCtx,
+    // Callers check readiness first, so a datafile is loaded here.
+    s.datafile,
+    onExposure,
+    reasons
+  );
+  if (s.stickyBucketService && r.variationKey && r.source === "rule" && r.ruleId && r.ruleType === "ab_test") {
+    const v = findVariation(s, flagKey, r.variationKey);
+    if (v) {
+      s.stickyBucketService.save(uc.userId, flagKey, {
+        variationId: v.id,
+        ruleId: r.ruleId,
+        ruleType: r.ruleType,
+        assignedAt: Date.now()
       });
-    },
-    on(event, cb) {
-      return server.on(event, cb);
-    },
-    getDatafile: () => server.getDatafile(),
-    getCurrentContext: () => null,
-    /**
-     * Real, not a comment: `client.utils.hydrateBootstrap(blob)` on the server
-     * adopts the blob's datafile and marks the SDK ready. That is the
-     * serverless cold-start path (read a datafile from KV or a file, hand it
-     * over, evaluate on the same tick).
-     */
-    applyDatafile: (df) => server.applyDatafileBootstrap(df)
-    // `applySnapshot` is deliberately ABSENT. A snapshot carries one context's
-    // evaluated values, and this client evaluates a different context per
-    // request, so adopting one process-wide would serve user A's values to user
-    // B. hydrateBootstrap throws with that explanation when it is handed a
-    // snapshot-only blob here, instead of quietly ignoring it.
+    }
+  }
+  return {
+    value: r.value,
+    variationKey: r.variationKey,
+    source: mapLegacySource(r.source),
+    ruleId: r.ruleId,
+    ruleType: r.ruleType,
+    reasons
+  };
+}
+function buildLegacyContext(context, suppressExposure) {
+  const legacy = toLegacyEvalContext(context);
+  const userId = legacy.attributes["userId"] ?? "";
+  const privateAttrs = privateAttributesFrom(context);
+  const { userId: _uid, ...rest } = legacy.attributes;
+  return {
+    userId,
+    attributes: rest,
+    suppressExposure,
+    privateAttributes: privateAttrs.size > 0 ? [...privateAttrs] : void 0
   };
-  return createUtils(adapter);
+}
+function manualExposure(s, server, flagKey, context) {
+  if (!server.isReady() || !s.datafile || !s.tracker) return;
+  const legacyCtx = buildLegacyContext(context, true);
+  const result = evaluateDecision(s, flagKey, legacyCtx, void 0);
+  if (result.source !== "rule" || !result.ruleId || !result.variationKey) return;
+  if (result.ruleType !== "ab_test" && result.ruleType !== "targeted_delivery") return;
+  const flag = s.datafile.flags.find((f) => f.key === flagKey);
+  if (!flag) return;
+  const variation = flag.variations.find((v) => v.key === result.variationKey);
+  if (!variation) return;
+  deliverExposure(s, {
+    visitorId: bucketingKey3(context),
+    experimentId: result.ruleId,
+    variationId: variation.id,
+    eventName: "flag_exposure",
+    revenue: null,
+    timestamp: Date.now(),
+    pageUrl: "",
+    properties: { flagKey, flagId: flag.id, manuallyFired: true }
+  });
+}
+function resolveStickyBucket(s, flagKey, userId) {
+  if (!s.stickyBucketService || !s.datafile) return void 0;
+  const assignment = s.stickyBucketService.lookup(userId, flagKey);
+  if (!assignment) return void 0;
+  const flag = s.datafile.flags.find((f) => f.key === flagKey);
+  if (!flag) return void 0;
+  const v = flag.variations.find((x) => x.id === assignment.variationId);
+  if (!v) return void 0;
+  return { vref: { value: v.value, key: v.key, id: v.id }, assignment };
+}
+function findVariation(s, flagKey, variationKey) {
+  if (!s.datafile) return null;
+  const flag = s.datafile.flags.find((f) => f.key === flagKey);
+  if (!flag) return null;
+  const v = flag.variations.find((x) => x.key === variationKey);
+  if (!v) return null;
+  return { value: v.value, key: v.key, id: v.id };
+}
+function fireExposureForStickyAssignment(s, flagKey, sticky, uc) {
+  if (!s.tracker || !s.datafile) return;
+  const flag = s.datafile.flags.find((f) => f.key === flagKey);
+  if (!flag) return;
+  const rule = flag.rules.find((r) => r.id === sticky.assignment.ruleId);
+  if (!rule || !rule.variations.some((rv) => rv.variationId === sticky.vref.id)) {
+    s.logger.warn(
+      "Sticky assignment references a rule no longer matching the datafile",
+      {
+        flagKey,
+        userId: uc.userId,
+        assignedRuleId: sticky.assignment.ruleId,
+        assignedVariationId: sticky.vref.id
+      }
+    );
+    emit(s, "stickyOrphan", {
+      flagKey,
+      userId: uc.userId,
+      assignment: sticky.assignment
+    });
+    return;
+  }
+  deliverExposure(s, {
+    visitorId: uc.userId,
+    experimentId: rule.id,
+    variationId: sticky.vref.id,
+    eventName: "flag_exposure",
+    revenue: null,
+    timestamp: Date.now(),
+    pageUrl: "",
+    properties: { flagKey, flagId: flag.id }
+  });
+}
+
+// src/serverEvaluation.ts
+function evaluateServerFlag(s, server, flagKey, defaultValue, context, options) {
+  if (!context) {
+    warnOnce(
+      s,
+      "no-context",
+      `getFlag("${flagKey}") was called without a context, so it cannot be evaluated and returns the default you passed. Bind one per request with server.forUser({ kind: "user", key: userId }), or pass it as the third argument: server.getFlag(key, default, { kind: "user", key: userId }).`
+    );
+    return notReadyFlag(
+      defaultValue,
+      "no context passed; call server.forUser(context) or pass the context positionally"
+    );
+  }
+  if (!server.isReady() || !s.datafile) {
+    warnOnce(
+      s,
+      "not-ready",
+      `getFlag("${flagKey}") was called before the datafile loaded, so it returns the default you passed and flag.source is "not_ready". Await server.onReady() during boot, or pass a bootstrap datafile to the constructor for an instant start.`
+    );
+    return notReadyFlag(defaultValue, "SDK not ready: no datafile loaded yet");
+  }
+  const decide = s.resolveDecideOptions(options?.decideOptions);
+  const flag = options?.forcedVariationKey ? buildForcedFlag(
+    s,
+    flagKey,
+    options.forcedVariationKey,
+    defaultValue,
+    context,
+    options
+  ) : evaluateAndBuild(
+    s,
+    flagKey,
+    defaultValue,
+    context,
+    decide,
+    options
+  );
+  return flag;
+}
+function evaluateAndBuild(s, flagKey, defaultValue, context, decide, options) {
+  const legacyCtx = buildLegacyContext(context, decide.suppressExposure);
+  const result = evaluateDecision(s, flagKey, legacyCtx, defaultValue);
+  if (result.source === "not_found") {
+    warnOnce(s, `missing:${flagKey}`, flagNotFoundMessage(flagKey));
+  }
+  const typeMismatch = checkType(s, flagKey, options?.expectedType, result);
+  if (typeMismatch) {
+    s.logger.warn(
+      `Type mismatch on flag "${flagKey}": ${typeMismatch}; returning the default.`
+    );
+    const fallback = notFoundFlag2(defaultValue, typeMismatch);
+    recordDecision(s, flagKey, fallback, context, options);
+    return fallback;
+  }
+  const flag = toFlag(result, defaultValue);
+  recordDecision(s, flagKey, flag, context, options);
+  return flag;
+}
+function checkType(s, flagKey, expectedType, result) {
+  if (!expectedType) return null;
+  if (result.source === "not_found" || result.source === "disabled") return null;
+  const datafileFlag = findDatafileFlag(s.datafile, flagKey);
+  return checkExpectedType(datafileFlag, expectedType, result.value) ?? null;
+}
+function toFlag(result, defaultValue) {
+  return createFlag({
+    value: result.value ?? defaultValue,
+    variationKey: result.variationKey,
+    source: result.source,
+    ruleId: result.ruleId,
+    ruleType: result.ruleType,
+    reasons: result.reasons,
+    evaluatedAt: Date.now(),
+    durationMicros: 0
+  });
+}
+function buildForcedFlag(s, flagKey, variationKey, defaultValue, context, options) {
+  const vref = findVariation(s, flagKey, variationKey);
+  const flag = createFlag({
+    value: vref ? vref.value : defaultValue,
+    variationKey: vref ? vref.key : null,
+    source: "runtimeOverride",
+    ruleId: null,
+    ruleType: null,
+    reasons: [`forced decision: variationKey="${variationKey}"`]
+  });
+  recordDecision(s, flagKey, flag, context, options);
+  return flag;
+}
+function recordDecision(s, flagKey, flag, context, options) {
+  const summary = contextSummary(context);
+  emit(s, "evaluation", {
+    flagKey,
+    flag,
+    contextKeys: summary.map((entry) => entry.key)
+  });
+  if (!options?.decisionLog) return;
+  appendDecisionLogEntry(options.decisionLog, {
+    flagKey,
+    value: flag.value,
+    variationKey: flag.variationKey,
+    source: flag.source,
+    ruleId: flag.ruleId,
+    ruleType: flag.ruleType,
+    reasons: flag.reasons,
+    evaluatedAt: flag.evaluatedAt,
+    durationMicros: flag.durationMicros,
+    contextSummary: summary,
+    privateValues: privateAttributeValues(context)
+  });
+}
+function evaluateAllServerFlags(s, server, context, options) {
+  if (!context) {
+    warnOnce(
+      s,
+      "get-all-no-context",
+      "getAllFlags() was called without a context and returned an empty object. Pass the context positionally, or use server.forUser(context).getAllFlags()."
+    );
+    return {};
+  }
+  if (!server.isReady() || !s.datafile) {
+    warnOnce(
+      s,
+      "get-all-not-ready",
+      "getAllFlags() was called before the datafile loaded and returned an empty object, which is indistinguishable from a project with no flags. Await server.onReady() first."
+    );
+    return {};
+  }
+  const fireExposures = options?.fireExposures === true;
+  const decideOptions = [...options?.decideOptions ?? []];
+  if (!fireExposures && !decideOptions.includes("DISABLE_EXPOSURE")) {
+    decideOptions.push("DISABLE_EXPOSURE");
+  }
+  const out = {};
+  for (const entry of s.datafile.flags) {
+    out[entry.key] = server.evaluateInternal(entry.key, void 0, context, {
+      decideOptions,
+      decisionLog: options?.decisionLog
+    });
+  }
+  return out;
 }
 
 // src/AvsbServer.ts
-var DEFAULT_EVENTS = {
-  flushInterval: 2e3,
-  batchSize: 10,
-  maxQueueSize: 1e4,
-  retryAttempts: 3
-};
-var SDK_TYPE = "@avsbhq/node";
-var HEARTBEAT_MIN_INTERVAL_MS = 12e4;
 var AvsbServer = class {
-  sdkKey;
-  cdnHost;
-  pollingInterval;
-  initTimeout;
-  logger;
-  stickyBucketService;
-  eventOptions;
-  streamingEnabled;
-  streamingEndpointOption;
-  overrides = createOverrideStore();
-  resolveDecideOptions;
-  datafile;
-  datafileEtag = null;
-  ready;
-  destroyed;
-  tracker;
-  streamingClient;
-  pollingTimer;
-  abortController = new AbortController();
-  listeners = /* @__PURE__ */ new Map();
-  readyPromise = null;
-  pendingEvents = [];
-  pendingPurchases = [];
-  /**
-   * Exposures produced before the tracker existed. Third member of the
-   * pre-ready family alongside `pendingEvents` and `pendingPurchases`; it used
-   * to be missing, and exposures were dropped on the floor instead.
-   */
-  pendingExposures = [];
-  /** ms-epoch of the last liveness heartbeat, for the throttle. */
-  lastHeartbeatAt = 0;
-  /** Keys of one-time warnings, so a request loop cannot flood a log. */
-  warnedOnce = /* @__PURE__ */ new Set();
+  /** Everything mutable about this client. See ./serverState. */
+  s;
+  // Private seams kept on the instance because
+  // AvsbServer.exposureDelivery.test.ts reaches them directly to stage a
+  // missing tracker. Each one is a straight pass-through to the state.
+  get tracker() {
+    return this.s.tracker;
+  }
+  set tracker(tracker) {
+    this.s.tracker = tracker;
+  }
+  deliverExposure(event) {
+    deliverExposure(this.s, event);
+  }
+  initTracker() {
+    initTracker(this.s, this);
+  }
   /**
    * `client.utils.*` surface, constructed lazily on first access so the utils
    * package is only imported when actually consumed.
@@ -831,9 +1522,10 @@ var AvsbServer = class {
         getAllFlags: (ctx, opts) => this.getAllFlags(ctx, opts),
         getFlag: (flagKey, defaultValue, context) => this.getFlag(flagKey, defaultValue, context),
         track: (eventKey, payload) => this.track(eventKey, payload),
-        on: (event, cb) => this.onSharedEvent(event, cb),
-        getDatafile: () => this.datafile,
-        applyDatafileBootstrap: (df) => this.applyDatafileBootstrap(df)
+        on: (event, cb) => onSharedEvent(this.s, this, event, cb),
+        getDatafile: () => this.s.datafile,
+        applyDatafileBootstrap: (df) => this.applyDatafileBootstrap(df),
+        refreshDatafile: () => this.refreshDatafile()
       });
     }
     return this._utils;
@@ -846,9 +1538,9 @@ var AvsbServer = class {
   get datasets() {
     if (!this._datasets) {
       this._datasets = createDatasetsClient({
-        sdkKey: this.sdkKey,
-        getDatafile: () => this.datafile,
-        logger: this.logger
+        sdkKey: this.s.sdkKey,
+        getDatafile: () => this.s.datafile,
+        logger: this.s.logger
       });
     }
     return this._datasets;
@@ -863,132 +1555,38 @@ var AvsbServer = class {
   get recs() {
     if (!this._recs) {
       this._recs = createRecsClient({
-        sdkKey: this.sdkKey,
-        getDatafile: () => this.datafile,
-        getTracker: () => this.tracker,
-        logger: this.logger
+        sdkKey: this.s.sdkKey,
+        getDatafile: () => this.s.datafile,
+        getTracker: () => this.s.tracker,
+        logger: this.s.logger
       });
     }
     return this._recs;
   }
   constructor(options) {
-    this.sdkKey = options.sdkKey;
-    this.pollingInterval = Math.max(options.pollingInterval ?? 6e4, 5e3);
-    this.cdnHost = options.cdnHost;
-    this.initTimeout = options.initTimeout ?? 1e4;
-    this.logger = resolveServerLogger(options);
-    this.stickyBucketService = options.stickyBucketService ?? null;
-    this.eventOptions = { ...DEFAULT_EVENTS, ...options.events };
-    this.streamingEnabled = options.streaming !== false;
-    this.streamingEndpointOption = options.streamingEndpoint ?? null;
-    this.datafile = options.bootstrap ?? null;
-    this.ready = !!options.bootstrap;
-    this.destroyed = false;
-    this.tracker = null;
-    this.streamingClient = null;
-    this.pollingTimer = null;
-    this.resolveDecideOptions = createDecideOptionResolver(this.logger);
-    const keyShape = validateSdkKeyShape(this.sdkKey);
-    if (!keyShape.valid && keyShape.message) {
-      this.logger.error(keyShape.message);
-    }
-    if (this.datafile) this.initTracker();
+    this.s = createServerState(options);
+    if (this.s.datafile) this.initTracker();
   }
-  // ---------------------------------------------------------------------------
-  // Readiness
-  // ---------------------------------------------------------------------------
+  // ---- Readiness ----
   /**
    * Await the init attempt. Never rejects; always resolves to an InitResult.
    * Calling it twice returns the same promise.
    */
   onReady() {
-    if (this.readyPromise) return this.readyPromise;
-    this.readyPromise = this.initializeAndReady();
-    return this.readyPromise;
+    if (this.s.readyPromise) return this.s.readyPromise;
+    this.s.readyPromise = initializeAndReady(this.s, this);
+    return this.s.readyPromise;
   }
   /** True when a datafile is loaded and flags are answerable right now. */
   isReady() {
-    return this.ready && this.datafile !== null;
-  }
-  async initializeAndReady() {
-    if (this.ready && this.datafile) {
-      this.onDatafileReadable();
-      return { success: true, source: "bootstrap" };
-    }
-    try {
-      const outcome = await Promise.race([
-        // At init there is no stored etag, so 'unchanged' cannot happen here;
-        // it is folded in anyway so a future caching layer cannot make init
-        // silently report failure.
-        this.loadDatafile().then((result) => ({
-          applied: result !== "failed",
-          timedOut: false
-        })),
-        new Promise(
-          (resolve) => setTimeout(
-            () => resolve({ applied: false, timedOut: true }),
-            this.initTimeout
-          )
-        )
-      ]);
-      if (outcome.timedOut) {
-        this.startPolling();
-        const error2 = new Error(
-          `AvsB init timed out after ${this.initTimeout}ms waiting for the datafile. Polling continues in the background, so flags start working as soon as the request completes; raise initTimeout if your cold start is slower.`
-        );
-        this.emit("error", error2);
-        return { success: false, source: "timeout", error: error2 };
-      }
-      if (outcome.applied) {
-        this.onDatafileReadable();
-        return { success: true, source: "network" };
-      }
-      this.startPolling();
-      const error = new Error(
-        'AvsB init failed: no datafile could be loaded, so every flag serves the default you passed and flag.source is "not_ready". The datafile request error is logged above with the URL and status. Polling continues.'
-      );
-      this.emit("error", error);
-      return { success: false, source: "error", error };
-    } catch (e) {
-      this.startPolling();
-      const error = e instanceof Error ? e : new Error(String(e));
-      this.emit("error", error);
-      return { success: false, source: "error", error };
-    }
+    return this.s.ready && this.s.datafile !== null;
   }
-  /** Wiring that runs once a datafile is readable, however it arrived. */
-  onDatafileReadable() {
-    this.initTracker();
-    this.ready = true;
-    this.startPolling();
-    this.startStreamingIfEnabled();
-    this.sendHeartbeat();
-    this.emit("ready");
-  }
-  // ---------------------------------------------------------------------------
-  // Lifecycle
-  // ---------------------------------------------------------------------------
-  async close() {
-    this.destroyed = true;
-    this.abortController.abort();
-    if (this.streamingClient) {
-      this.streamingClient.disconnect();
-      this.streamingClient = null;
-    }
-    if (this.pollingTimer) {
-      clearTimeout(this.pollingTimer);
-      this.pollingTimer = null;
-    }
-    if (this.tracker) {
-      await this.tracker.destroy();
-      this.tracker = null;
-    }
-    this._utils?._drain();
-    this.datafile = null;
-    this.ready = false;
+  // ---- Lifecycle ----
+  close() {
+    return closeServer(this.s, () => this._utils?._drain());
   }
   async flush() {
-    if (this.tracker) await this.tracker.flush();
+    if (this.s.tracker) await this.s.tracker.flush();
   }
   /**
    * Fetch the datafile now and apply it if it changed.
@@ -996,15 +1594,8 @@ var AvsbServer = class {
    * A 304 is not a problem and is not warned about: it means the datafile in
    * memory IS the published one.
    */
-  async refreshDatafile() {
-    const result = await this.loadDatafile("manual");
-    if (result === "failed") {
-      this.logger.warn(
-        "AvsB datafile refresh did not apply a new datafile; the SDK keeps serving the one it already has. The request error is logged above."
-      );
-      return;
-    }
-    if (result === "applied" && !this.ready) this.onDatafileReadable();
+  refreshDatafile() {
+    return refreshDatafile(this.s, this);
   }
   /**
    * Adopt a datafile received out of band: a bootstrap blob from
@@ -1016,33 +1607,16 @@ var AvsbServer = class {
    * handoff silently do nothing.
    */
   applyDatafileBootstrap(datafile) {
-    if (this.destroyed) return;
-    const changed = this.datafile?.publishedAt !== datafile.publishedAt;
-    this.datafile = datafile;
-    this.datafileEtag = null;
-    if (!this.ready) {
-      this.onDatafileReadable();
-      return;
-    }
-    this.initTracker();
-    if (changed) {
-      this.emit("configUpdate", {
-        publishedAt: datafile.publishedAt,
-        reason: "manual"
-      });
-    }
+    applyDatafileBootstrap(this.s, this, datafile);
   }
   /** The datafile currently in memory, or null before init completes. */
   getDatafile() {
-    return this.datafile;
+    return this.s.datafile;
   }
-  // ---------------------------------------------------------------------------
-  // Evaluation
-  //
+  // ---- Evaluation ----
   // Context is the THIRD POSITIONAL argument on every call (B3), matching
   // @avsbhq/edge. `forUser(ctx)` is the primary server pattern and binds it
   // once per request.
-  // ---------------------------------------------------------------------------
   getFlag(flagKey, defaultValue, context, options) {
     return this.evaluateInternal(flagKey, defaultValue, context, options);
   }
@@ -1076,60 +1650,7 @@ var AvsbServer = class {
    * published API: its options bag carries package-internal fields.
    */
   evaluateInternal(flagKey, defaultValue, context, options) {
-    if (!context) {
-      this.warnOnce(
-        "no-context",
-        `getFlag("${flagKey}") was called without a context, so it cannot be evaluated and returns the default you passed. Bind one per request with server.forUser({ kind: "user", key: userId }), or pass it as the third argument: server.getFlag(key, default, { kind: "user", key: userId }).`
-      );
-      return notReadyFlag(
-        defaultValue,
-        "no context passed; call server.forUser(context) or pass the context positionally"
-      );
-    }
-    if (!this.isReady() || !this.datafile) {
-      this.warnOnce(
-        "not-ready",
-        `getFlag("${flagKey}") was called before the datafile loaded, so it returns the default you passed and flag.source is "not_ready". Await server.onReady() during boot, or pass a bootstrap datafile to the constructor for an instant start.`
-      );
-      return notReadyFlag(defaultValue, "SDK not ready: no datafile loaded yet");
-    }
-    const decide = this.resolveDecideOptions(options?.decideOptions);
-    const flag = options?.forcedVariationKey ? this.buildForcedFlag(
-      flagKey,
-      options.forcedVariationKey,
-      defaultValue,
-      context,
-      options
-    ) : this.evaluateAndBuild(
-      flagKey,
-      defaultValue,
-      context,
-      decide,
-      options
-    );
-    return flag;
-  }
-  evaluateAndBuild(flagKey, defaultValue, context, decide, options) {
-    const legacyCtx = this.buildLegacyContext(context, decide.suppressExposure);
-    const result = this.evaluate(flagKey, legacyCtx, defaultValue);
-    const typeMismatch = this.checkType(flagKey, options?.expectedType, result);
-    if (typeMismatch) {
-      this.logger.warn(
-        `Type mismatch on flag "${flagKey}": ${typeMismatch}; returning the default.`
-      );
-      const fallback = notFoundFlag2(defaultValue, typeMismatch);
-      this.recordDecision(flagKey, fallback, context, options);
-      return fallback;
-    }
-    const flag = this.toFlag(result, defaultValue);
-    this.recordDecision(flagKey, flag, context, options);
-    return flag;
-  }
-  checkType(flagKey, expectedType, result) {
-    if (!expectedType) return null;
-    if (result.source === "not_found" || result.source === "disabled") return null;
-    const datafileFlag = findDatafileFlag(this.datafile, flagKey);
-    return checkExpectedType(datafileFlag, expectedType, result.value) ?? null;
+    return evaluateServerFlag(this.s, this, flagKey, defaultValue, context, options);
   }
   /**
    * Every flag in the environment, evaluated against one context.
@@ -1140,37 +1661,9 @@ var AvsbServer = class {
    * arguments.
    */
   getAllFlags(context, options) {
-    if (!context) {
-      this.warnOnce(
-        "get-all-no-context",
-        "getAllFlags() was called without a context and returned an empty object. Pass the context positionally, or use server.forUser(context).getAllFlags()."
-      );
-      return {};
-    }
-    if (!this.isReady() || !this.datafile) {
-      this.warnOnce(
-        "get-all-not-ready",
-        "getAllFlags() was called before the datafile loaded and returned an empty object, which is indistinguishable from a project with no flags. Await server.onReady() first."
-      );
-      return {};
-    }
-    const fireExposures = options?.fireExposures === true;
-    const decideOptions = [...options?.decideOptions ?? []];
-    if (!fireExposures && !decideOptions.includes("DISABLE_EXPOSURE")) {
-      decideOptions.push("DISABLE_EXPOSURE");
-    }
-    const out = {};
-    for (const entry of this.datafile.flags) {
-      out[entry.key] = this.evaluateInternal(entry.key, void 0, context, {
-        decideOptions,
-        decisionLog: options?.decisionLog
-      });
-    }
-    return out;
+    return evaluateAllServerFlags(this.s, this, context, options);
   }
-  // ---------------------------------------------------------------------------
-  // Tracking
-  // ---------------------------------------------------------------------------
+  // ---- Tracking ----
   /**
    * Queue a metric (conversion) event. Synchronous: it returns as soon as the
    * event is queued, and the tracker batches it.
@@ -1180,30 +1673,7 @@ var AvsbServer = class {
    * the server; see the README for why the two runtimes read differently here.
    */
   track(eventKey, payload) {
-    if (payload.properties) {
-      this.warnOnce(
-        "track-properties",
-        `track("${eventKey}") was called with properties, which are NOT stored for metric events: the ingestion contract for a conversion keeps the event name, the numeric value, the timestamp, and the visitor id. Exposure events do carry properties. Nothing else about the call is affected.`
-      );
-    }
-    if (!this.tracker) {
-      this.enqueuePending(eventKey, payload);
-      return;
-    }
-    this.tracker.queueMetric({
-      visitorId: bucketingKey2(payload.context),
-      eventName: eventKey,
-      // TWO columns, not one. `revenue` is money in decimal major units;
-      // `value` is the numeric metric value for average-value metrics. Storage
-      // declares both (`metric_events.revenue`, `metric_events.value`). This
-      // SDK used to ship `payload.value` into the revenue column and could
-      // never write the value column at all, so a quantity was recorded as
-      // money and every average-value metric read empty.
-      revenue: payload.revenue ?? null,
-      value: payload.value ?? null,
-      timestamp: Date.now(),
-      pageUrl: ""
-    });
+    trackMetric(this.s, eventKey, payload);
   }
   /**
    * Send a purchase to `/v1/collect/orders`.
@@ -1211,20 +1681,8 @@ var AvsbServer = class {
    * Queued before the tracker exists, exactly like `track` (they used to
    * disagree: one queued, the other warned and dropped the order).
    */
-  async trackPurchase(visitorId, order) {
-    if (this.destroyed) return;
-    if (!this.tracker) {
-      if (this.pendingPurchases.length >= this.eventOptions.maxQueueSize) {
-        this.pendingPurchases.shift();
-        this.warnOnce(
-          "pending-purchase-full",
-          `Pre-ready purchase queue reached ${this.eventOptions.maxQueueSize} orders; the oldest is being dropped. This means the datafile never loaded: check the datafile error logged above.`
-        );
-      }
-      this.pendingPurchases.push({ visitorId, order });
-      return;
-    }
-    return this.tracker.trackPurchase(visitorId, order);
+  trackPurchase(visitorId, order) {
+    return trackPurchase(this.s, visitorId, order);
   }
   /**
    * Mark the moment a signup or login claimed an anonymous session. Same shape
@@ -1245,8 +1703,8 @@ var AvsbServer = class {
    * the README for the cross-surface version of the same rule.
    */
   alias(previousContext, newContext) {
-    this.logger.debug(
-      `alias: ${bucketingKey2(previousContext)} to ${bucketingKey2(newContext)}`
+    this.s.logger.debug(
+      `alias: ${bucketingKey4(previousContext)} to ${bucketingKey4(newContext)}`
     );
     this.track("avsb_alias", { context: newContext });
   }
@@ -1256,29 +1714,9 @@ var AvsbServer = class {
    * now actually seen the result.
    */
   manualExposure(flagKey, context) {
-    if (!this.isReady() || !this.datafile || !this.tracker) return;
-    const legacyCtx = this.buildLegacyContext(context, true);
-    const result = this.evaluate(flagKey, legacyCtx, void 0);
-    if (result.source !== "rule" || !result.ruleId || !result.variationKey) return;
-    if (result.ruleType !== "ab_test" && result.ruleType !== "targeted_delivery") return;
-    const flag = this.datafile.flags.find((f) => f.key === flagKey);
-    if (!flag) return;
-    const variation = flag.variations.find((v) => v.key === result.variationKey);
-    if (!variation) return;
-    this.deliverExposure({
-      visitorId: bucketingKey2(context),
-      experimentId: result.ruleId,
-      variationId: variation.id,
-      eventName: "flag_exposure",
-      revenue: null,
-      timestamp: Date.now(),
-      pageUrl: "",
-      properties: { flagKey, flagId: flag.id, manuallyFired: true }
-    });
+    manualExposure(this.s, this, flagKey, context);
   }
-  // ---------------------------------------------------------------------------
-  // Per-request scoping
-  // ---------------------------------------------------------------------------
+  // ---- Per-request scoping ----
   /** A client with the context bound. The primary server pattern. */
   forUser(context) {
     return createUserBoundClient(this, context);
@@ -1287,437 +1725,32 @@ var AvsbServer = class {
   createUserContext(context) {
     return createUserBoundClient(this, context);
   }
-  // ---------------------------------------------------------------------------
-  // Overrides
-  // ---------------------------------------------------------------------------
+  // ---- Overrides ----
   setOverrideForUser(flagKey, contextKey, variationKey, contextKind = "user") {
-    this.overrides.setForContext(flagKey, contextKey, variationKey, contextKind);
+    this.s.overrides.setForContext(flagKey, contextKey, variationKey, contextKind);
   }
   setGlobalOverride(flagKey, variationKey) {
-    this.overrides.setGlobal(flagKey, variationKey);
+    this.s.overrides.setGlobal(flagKey, variationKey);
   }
   clearOverrideForUser(flagKey, contextKey, contextKind = "user") {
-    this.overrides.clearForContext(flagKey, contextKey, contextKind);
+    this.s.overrides.clearForContext(flagKey, contextKey, contextKind);
   }
   clearGlobalOverride(flagKey) {
-    this.overrides.clearGlobal(flagKey);
+    this.s.overrides.clearGlobal(flagKey);
   }
   clearAllOverrides() {
-    this.overrides.clearAll();
+    this.s.overrides.clearAll();
   }
   /** A fresh decision log to pass per call. `forUser` carries its own. */
   createDecisionLog() {
     return createDecisionLog();
   }
-  // ---------------------------------------------------------------------------
-  // Events
-  // ---------------------------------------------------------------------------
+  // ---- Events ----
   on(event, cb) {
-    if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
-    this.listeners.get(event).add(cb);
-    return () => {
-      this.listeners.get(event)?.delete(cb);
-    };
+    return addListener(this.s, event, cb);
   }
   off(event, cb) {
-    this.listeners.get(event)?.delete(cb);
-  }
-  /**
-   * `on` for the shared `ClientEventMap` names the utils layer speaks. The
-   * server emits every one of them except `flagChange`, which needs per-flag
-   * diffing the server does not do; subscribing to it warns and hands back a
-   * no-op disposer instead of pretending.
-   */
-  onSharedEvent(event, cb) {
-    if (event === "flagChange") {
-      this.warnOnce(
-        "no-flag-change",
-        'The server SDK does not emit "flagChange": it holds one datafile for the whole process and does not diff individual flags. Subscribe to "configUpdate" for "a new datafile was published" instead.'
-      );
-      return () => void 0;
-    }
-    return this.on(
-      event,
-      cb
-    );
-  }
-  emit(event, ...args) {
-    const cbs = this.listeners.get(event);
-    if (!cbs) return;
-    for (const cb of cbs) {
-      try {
-        ;
-        cb(...args);
-      } catch (e) {
-        this.logger.error("Listener error", { event, error: String(e) });
-      }
-    }
-  }
-  warnOnce(key, message) {
-    if (this.warnedOnce.has(key)) return;
-    this.warnedOnce.add(key);
-    this.logger.warn(message);
-  }
-  // ---------------------------------------------------------------------------
-  // Private — evaluation core
-  // ---------------------------------------------------------------------------
-  evaluate(flagKey, uc, defaultValue) {
-    const reasons = [];
-    const overrideKey = this.overrides.resolve(flagKey, uc.userId);
-    const rtOver = overrideKey ? this.findVariation(flagKey, overrideKey) : null;
-    if (rtOver) {
-      reasons.push(`matched runtime override for flagKey="${flagKey}"`);
-      return {
-        value: rtOver.value,
-        variationKey: rtOver.key,
-        source: "runtimeOverride",
-        ruleId: null,
-        ruleType: null,
-        reasons
-      };
-    }
-    if (this.stickyBucketService) {
-      const sticky = this.resolveStickyBucket(flagKey, uc.userId);
-      if (sticky !== void 0) {
-        reasons.push(`matched sticky bucket assignment for userId="${uc.userId}"`);
-        if (!uc.suppressExposure) {
-          this.fireExposureForStickyAssignment(flagKey, sticky, uc);
-        }
-        return {
-          value: sticky.vref.value,
-          variationKey: sticky.vref.key,
-          source: "sticky",
-          ruleId: sticky.assignment.ruleId,
-          ruleType: sticky.assignment.ruleType,
-          reasons
-        };
-      }
-    }
-    const legacyCtx = { attributes: { userId: uc.userId, ...uc.attributes } };
-    const onExposure = uc.suppressExposure ? void 0 : (event) => {
-      this.deliverExposure(redactExposure(event, uc.privateAttributes));
-    };
-    const r = evaluateFlag(
-      flagKey,
-      defaultValue,
-      legacyCtx,
-      this.datafile,
-      onExposure,
-      reasons
-    );
-    if (this.stickyBucketService && r.variationKey && r.source === "rule" && r.ruleId && r.ruleType === "ab_test") {
-      const v = this.findVariation(flagKey, r.variationKey);
-      if (v) {
-        this.stickyBucketService.save(uc.userId, flagKey, {
-          variationId: v.id,
-          ruleId: r.ruleId,
-          ruleType: r.ruleType,
-          assignedAt: Date.now()
-        });
-      }
-    }
-    return {
-      value: r.value,
-      variationKey: r.variationKey,
-      source: mapLegacySource(r.source),
-      ruleId: r.ruleId,
-      ruleType: r.ruleType,
-      reasons
-    };
-  }
-  /**
-   * One exposure, delivered everywhere: queued for ingestion AND emitted on
-   * the event bus with the SAME `eventId`, so a customer forwarding decisions
-   * to their own analytics can reconcile rows with A vs B results.
-   */
-  deliverExposure(event) {
-    const stamped = event.eventId ? event : { ...event, eventId: randomUUID2() };
-    if (this.tracker) {
-      this.tracker.queue(stamped);
-    } else {
-      this.enqueuePendingExposure(stamped);
-    }
-    this.emit("exposure", stamped);
-  }
-  toFlag(result, defaultValue) {
-    return createFlag({
-      value: result.value ?? defaultValue,
-      variationKey: result.variationKey,
-      source: result.source,
-      ruleId: result.ruleId,
-      ruleType: result.ruleType,
-      reasons: result.reasons,
-      evaluatedAt: Date.now(),
-      durationMicros: 0
-    });
-  }
-  /** Build a Flag from a forced variation key (per-request forced decision). */
-  buildForcedFlag(flagKey, variationKey, defaultValue, context, options) {
-    const vref = this.findVariation(flagKey, variationKey);
-    const flag = createFlag({
-      value: vref ? vref.value : defaultValue,
-      variationKey: vref ? vref.key : null,
-      source: "runtimeOverride",
-      ruleId: null,
-      ruleType: null,
-      reasons: [`forced decision: variationKey="${variationKey}"`]
-    });
-    this.recordDecision(flagKey, flag, context, options);
-    return flag;
-  }
-  /** Emit the evaluation event and append to a decision log if one was passed. */
-  recordDecision(flagKey, flag, context, options) {
-    const summary = contextSummary(context);
-    this.emit("evaluation", {
-      flagKey,
-      flag,
-      contextKeys: summary.map((entry) => entry.key)
-    });
-    if (!options?.decisionLog) return;
-    appendDecisionLogEntry(options.decisionLog, {
-      flagKey,
-      value: flag.value,
-      variationKey: flag.variationKey,
-      source: flag.source,
-      ruleId: flag.ruleId,
-      ruleType: flag.ruleType,
-      reasons: flag.reasons,
-      evaluatedAt: flag.evaluatedAt,
-      durationMicros: flag.durationMicros,
-      contextSummary: summary,
-      privateValues: privateAttributeValues(context)
-    });
-  }
-  buildLegacyContext(context, suppressExposure) {
-    const legacy = toLegacyEvalContext(context);
-    const userId = legacy.attributes["userId"] ?? "";
-    const privateAttrs = privateAttributesFrom(context);
-    const { userId: _uid, ...rest } = legacy.attributes;
-    return {
-      userId,
-      attributes: rest,
-      suppressExposure,
-      privateAttributes: privateAttrs.size > 0 ? [...privateAttrs] : void 0
-    };
-  }
-  // ---------------------------------------------------------------------------
-  // Private — sticky helpers
-  // ---------------------------------------------------------------------------
-  resolveStickyBucket(flagKey, userId) {
-    if (!this.stickyBucketService || !this.datafile) return void 0;
-    const assignment = this.stickyBucketService.lookup(userId, flagKey);
-    if (!assignment) return void 0;
-    const flag = this.datafile.flags.find((f) => f.key === flagKey);
-    if (!flag) return void 0;
-    const v = flag.variations.find((x) => x.id === assignment.variationId);
-    if (!v) return void 0;
-    return { vref: { value: v.value, key: v.key, id: v.id }, assignment };
-  }
-  findVariation(flagKey, variationKey) {
-    if (!this.datafile) return null;
-    const flag = this.datafile.flags.find((f) => f.key === flagKey);
-    if (!flag) return null;
-    const v = flag.variations.find((x) => x.key === variationKey);
-    if (!v) return null;
-    return { value: v.value, key: v.key, id: v.id };
-  }
-  fireExposureForStickyAssignment(flagKey, sticky, uc) {
-    if (!this.tracker || !this.datafile) return;
-    const flag = this.datafile.flags.find((f) => f.key === flagKey);
-    if (!flag) return;
-    const rule = flag.rules.find((r) => r.id === sticky.assignment.ruleId);
-    if (!rule || !rule.variations.some((rv) => rv.variationId === sticky.vref.id)) {
-      this.logger.warn(
-        "Sticky assignment references a rule no longer matching the datafile",
-        {
-          flagKey,
-          userId: uc.userId,
-          assignedRuleId: sticky.assignment.ruleId,
-          assignedVariationId: sticky.vref.id
-        }
-      );
-      this.emit("stickyOrphan", {
-        flagKey,
-        userId: uc.userId,
-        assignment: sticky.assignment
-      });
-      return;
-    }
-    this.deliverExposure({
-      visitorId: uc.userId,
-      experimentId: rule.id,
-      variationId: sticky.vref.id,
-      eventName: "flag_exposure",
-      revenue: null,
-      timestamp: Date.now(),
-      pageUrl: "",
-      properties: { flagKey, flagId: flag.id }
-    });
-  }
-  // ---------------------------------------------------------------------------
-  // Private — tracker, polling, streaming, heartbeat
-  // ---------------------------------------------------------------------------
-  initTracker() {
-    if (!this.datafile || this.tracker) return;
-    const tracker = createServerTracker({
-      sdkKey: this.sdkKey,
-      collectEndpoint: this.datafile.collectEndpoint,
-      flushInterval: this.eventOptions.flushInterval,
-      batchSize: this.eventOptions.batchSize,
-      maxQueueSize: this.eventOptions.maxQueueSize,
-      retryAttempts: this.eventOptions.retryAttempts,
-      logger: this.logger
-    });
-    this.tracker = tracker;
-    if (this.pendingExposures.length > 0) {
-      const queued = this.pendingExposures;
-      this.pendingExposures = [];
-      for (const event of queued) tracker.queue(event);
-    }
-    if (this.pendingEvents.length > 0) {
-      const queued = this.pendingEvents;
-      this.pendingEvents = [];
-      for (const item of queued) this.track(item.eventKey, item.payload);
-    }
-    if (this.pendingPurchases.length > 0) {
-      const queued = this.pendingPurchases;
-      this.pendingPurchases = [];
-      for (const item of queued) void this.trackPurchase(item.visitorId, item.order);
-    }
-  }
-  enqueuePendingExposure(event) {
-    if (this.pendingExposures.length >= this.eventOptions.maxQueueSize) {
-      this.pendingExposures.shift();
-      this.warnOnce(
-        "pending-exposures-full",
-        `Pre-ready exposure queue reached ${this.eventOptions.maxQueueSize} events; the oldest are being dropped. This means the datafile never loaded, so nothing has been delivered yet: check the datafile error logged above.`
-      );
-    }
-    this.pendingExposures.push(event);
-  }
-  enqueuePending(eventKey, payload) {
-    if (this.pendingEvents.length >= this.eventOptions.maxQueueSize) {
-      this.pendingEvents.shift();
-      this.warnOnce(
-        "pending-events-full",
-        `Pre-ready event queue reached ${this.eventOptions.maxQueueSize} events; the oldest are being dropped. This means the datafile never loaded, so nothing has been delivered yet: check the datafile error logged above.`
-      );
-    }
-    this.pendingEvents.push({ eventKey, payload });
-  }
-  /**
-   * Fetch and apply the datafile.
-   *
-   * Three outcomes, not two, because a conditional request has three:
-   *   'applied'   a datafile came back and is now in memory
-   *   'unchanged' the CDN answered 304: what we hold IS current
-   *   'failed'    nothing usable came back; the error is already logged
-   *
-   * 'unchanged' is a success. Collapsing it into 'failed' made
-   * `refreshDatafile()` warn that a refresh "did not apply a new datafile"
-   * every time the datafile was simply up to date.
-   */
-  async loadDatafile(reason = "manual") {
-    const outcome = await fetchDatafile({
-      sdkKey: this.sdkKey,
-      cdnHost: this.cdnHost,
-      signal: this.abortController.signal,
-      logger: this.logger,
-      etag: this.datafileEtag
-    });
-    if (outcome.status === "ok" || outcome.status === "not-modified") {
-      this.sendHeartbeat();
-    }
-    if (outcome.status === "not-modified") return "unchanged";
-    if (outcome.status !== "ok") return "failed";
-    const changed = !this.datafile || this.datafile.publishedAt !== outcome.datafile.publishedAt;
-    this.datafile = outcome.datafile;
-    this.datafileEtag = outcome.etag;
-    if (this.ready && changed) {
-      this.emit("configUpdate", {
-        publishedAt: outcome.datafile.publishedAt,
-        reason
-      });
-      this.logger.info("Datafile updated", {
-        publishedAt: outcome.datafile.publishedAt,
-        reason
-      });
-      this.startStreamingIfEnabled();
-    }
-    return "applied";
-  }
-  /**
-   * Poll on a JITTERED interval. Without the jitter every process that
-   * deployed together polls the CDN on the same tick forever.
-   */
-  startPolling() {
-    if (this.pollingTimer || this.destroyed) return;
-    const schedule = () => {
-      this.pollingTimer = setTimeout(() => {
-        this.pollingTimer = null;
-        void (async () => {
-          const result = await this.loadDatafile("poll");
-          if (result === "applied" && !this.ready) this.onDatafileReadable();
-          if (!this.destroyed) schedule();
-        })();
-      }, jitteredInterval(this.pollingInterval));
-    };
-    schedule();
-  }
-  /**
-   * Open the SSE stream when one is available, and fall back to polling in
-   * silence when it is not (B12). The endpoint comes from the datafile's
-   * `streamEndpoint` field, or an explicit option; it is never guessed from
-   * another host, which is what gave one port an infinite reconnect loop
-   * against DNS that does not resolve.
-   */
-  startStreamingIfEnabled() {
-    if (!this.streamingEnabled || this.streamingClient || this.destroyed) return;
-    const resolution = resolveStreamEndpoint({
-      optionEndpoint: this.streamingEndpointOption,
-      datafileStreamEndpoint: this.datafile?.streamEndpoint ?? null
-    });
-    if (!resolution.available) {
-      this.logger.debug(`Streaming stays off, polling continues. ${resolution.reason}`);
-      return;
-    }
-    this.streamingClient = createStreamingClient({
-      endpoint: resolution.endpoint,
-      sdkKey: this.sdkKey,
-      onDatafileUpdated: () => {
-        void this.loadDatafile("stream");
-      },
-      logger: this.logger
-    });
-    this.streamingClient.connect();
-    this.logger.debug(
-      `Streaming datafile updates from ${resolution.endpoint} (${resolution.source}).`
-    );
-  }
-  /**
-   * Report liveness, throttled.
-   *
-   * Called on every successful datafile load, not just at init: the dashboard
-   * marks an environment Stale after five minutes without a heartbeat, so an
-   * init-only heartbeat made every long-running process look dead a few
-   * minutes after it started. The throttle keeps a fast polling interval (or a
-   * burst of stream-triggered refreshes) from turning liveness into traffic.
-   *
-   * Fire and forget: a failed heartbeat never affects evaluation, and the
-   * throttle clock is stamped by the synchronous send below, so a hanging
-   * request cannot queue a second one.
-   */
-  sendHeartbeat() {
-    const now = Date.now();
-    if (now - this.lastHeartbeatAt < HEARTBEAT_MIN_INTERVAL_MS) return;
-    const posted = sendHeartbeat({
-      sdkKey: this.sdkKey,
-      sdkType: SDK_TYPE,
-      sdkVersion: SDK_VERSION,
-      datafileHeartbeatEndpoint: this.datafile?.heartbeatEndpoint,
-      signal: this.abortController.signal
-    });
-    if (posted) this.lastHeartbeatAt = now;
+    this.s.listeners.get(event)?.delete(cb);
   }
 };