@avsbhq/node 1.6.2 → 1.7.0

package/dist/index.js

@@ -1,17 +1,22 @@
 // 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,
-  noopLogger
+  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;
@@ -265,42 +270,238 @@ function createRecsClient(options) {
 }
 
 // src/decisionLog.ts
+import { isMultiContext } from "@avsbhq/core";
+var REDACTED = "[REDACTED]";
+var MIN_SUBSTRING_LENGTH = 2;
 function createDecisionLog() {
   const entries = [];
   return { entries };
 }
+function privateAttributeValues(ctx) {
+  const out = /* @__PURE__ */ new Set();
+  const collect = (sub) => {
+    const names = sub._meta?.privateAttributes ?? [];
+    for (const name of names) {
+      const raw = sub[name];
+      if (raw === void 0 || raw === null) continue;
+      const text = typeof raw === "string" ? raw : stringify(raw);
+      if (text) out.add(text);
+    }
+  };
+  if (isMultiContext(ctx)) {
+    for (const [kind, value] of Object.entries(ctx)) {
+      if (kind === "kind") continue;
+      if (!value || typeof value !== "object") continue;
+      collect(value);
+    }
+  } else {
+    collect(ctx);
+  }
+  return [...out].sort((a, b) => b.length - a.length);
+}
+function stringify(value) {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+function matches(haystack, needle) {
+  if (haystack === needle) return true;
+  if (needle.length < MIN_SUBSTRING_LENGTH) return false;
+  return haystack.includes(needle);
+}
+function redactValue(value, privateValues) {
+  if (privateValues.length === 0) return value;
+  if (value === void 0 || value === null) return value;
+  const serialised = stringify(value);
+  if (!serialised) return value;
+  for (const priv of privateValues) {
+    if (matches(serialised, priv)) return REDACTED;
+  }
+  return value;
+}
+function redactReasons(reasons, privateValues) {
+  if (privateValues.length === 0) return [...reasons];
+  return reasons.map((reason) => {
+    let out = reason;
+    for (const priv of privateValues) {
+      if (out === priv) return REDACTED;
+      if (priv.length < MIN_SUBSTRING_LENGTH) continue;
+      out = out.split(priv).join(REDACTED);
+    }
+    return out;
+  });
+}
+function appendDecisionLogEntry(log, input) {
+  const entry = {
+    flagKey: input.flagKey,
+    value: redactValue(input.value, input.privateValues),
+    variationKey: input.variationKey,
+    source: input.source,
+    ruleId: input.ruleId,
+    ruleType: input.ruleType,
+    reasons: redactReasons(input.reasons, input.privateValues),
+    evaluatedAt: input.evaluatedAt,
+    durationMicros: input.durationMicros,
+    contextSummary: input.contextSummary,
+    ...input.manuallyFired ? { manuallyFired: true } : {}
+  };
+  log.entries.push(entry);
+  return entry;
+}
 
-// src/serverTracker.ts
-import { randomUUID } from "crypto";
+// src/decideOptions.ts
+import { DecideOption } from "@avsbhq/core";
+var KNOWN = Object.values(DecideOption);
+function createDecideOptionResolver(logger) {
+  const warned = /* @__PURE__ */ new Set();
+  return function resolve(options) {
+    if (!options || options.length === 0) return { suppressExposure: false };
+    let suppressExposure = false;
+    for (const option of options) {
+      if (option === DecideOption.DISABLE_EXPOSURE) {
+        suppressExposure = true;
+        continue;
+      }
+      if (option === DecideOption.INCLUDE_REASONS) {
+        continue;
+      }
+      const unknown = String(option);
+      if (!warned.has(unknown)) {
+        warned.add(unknown);
+        logger.warn(
+          `Unknown decide option "${unknown}" ignored. Accepted values are ${KNOWN.join(", ")}. EXCLUDE_VARIABLES, IGNORE_STICKY_BUCKET and ENABLED_FLAGS_ONLY were deleted because no SDK ever implemented them.`
+        );
+      }
+    }
+    return { suppressExposure };
+  };
+}
 
-// src/reconnectBackoff.ts
-var BASE_DELAY_MS = 1e3;
-var MAX_DELAY_MS = 6e4;
-var MIN_DELAY_MS = 500;
-var JITTER = 0.2;
-function nextBackoff(prev, retryAfterMs) {
-  const attempt = (prev?.attempt ?? 0) + 1;
-  if (typeof retryAfterMs === "number" && retryAfterMs > 0) {
-    return { attempt, delayMs: retryAfterMs };
-  }
-  const base = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** (attempt - 1));
-  const jitter = base * JITTER * (Math.random() * 2 - 1);
-  const delayMs = Math.max(MIN_DELAY_MS, Math.round(base + jitter));
-  return { attempt, delayMs };
+// src/overrideStore.ts
+function createOverrideStore() {
+  const byFlagKey = /* @__PURE__ */ new Map();
+  function ensure(flagKey) {
+    const existing = byFlagKey.get(flagKey);
+    if (existing) return existing;
+    const created = { perKindKey: /* @__PURE__ */ new Map() };
+    byFlagKey.set(flagKey, created);
+    return created;
+  }
+  function prune(flagKey, entry) {
+    if (!entry.global && entry.perKindKey.size === 0) byFlagKey.delete(flagKey);
+  }
+  return {
+    resolve(flagKey, contextKey, contextKind = "user") {
+      const entry = byFlagKey.get(flagKey);
+      if (!entry) return void 0;
+      return entry.perKindKey.get(`${contextKind}:${contextKey}`) ?? entry.global;
+    },
+    setForContext(flagKey, contextKey, variationKey, contextKind = "user") {
+      ensure(flagKey).perKindKey.set(`${contextKind}:${contextKey}`, variationKey);
+    },
+    setGlobal(flagKey, variationKey) {
+      ensure(flagKey).global = variationKey;
+    },
+    clearForContext(flagKey, contextKey, contextKind = "user") {
+      const entry = byFlagKey.get(flagKey);
+      if (!entry) return;
+      entry.perKindKey.delete(`${contextKind}:${contextKey}`);
+      prune(flagKey, entry);
+    },
+    clearGlobal(flagKey) {
+      const entry = byFlagKey.get(flagKey);
+      if (!entry) return;
+      entry.global = void 0;
+      prune(flagKey, entry);
+    },
+    clearAll() {
+      byFlagKey.clear();
+    },
+    size() {
+      return byFlagKey.size;
+    }
+  };
 }
-function resetBackoff() {
-  return null;
+
+// src/datafileSource.ts
+import { datafileUrl, resolveHeartbeatEndpoint } from "@avsbhq/core";
+async function fetchDatafile(input) {
+  const url = datafileUrl(input.sdkKey, input.cdnHost);
+  const headers = {};
+  if (input.etag) headers["If-None-Match"] = input.etag;
+  try {
+    const response = await fetch(url, { signal: input.signal, headers });
+    if (response.status === 304) return { status: "not-modified" };
+    if (!response.ok) {
+      input.logger.error(
+        `AvsB datafile request failed with HTTP ${response.status} for ${url}. ` + (response.status === 404 ? "That SDK key has no published datafile: check the key belongs to this environment and that the environment has been published at least once (app.avsb.cloud, then Settings, then Environments)." : "The SDK keeps serving whatever datafile it already has and retries on the polling interval.")
+      );
+      return { status: "failed" };
+    }
+    const datafile = await response.json();
+    return { status: "ok", datafile, etag: response.headers.get("etag") };
+  } catch (error) {
+    if (input.signal.aborted) return { status: "aborted" };
+    input.logger.error(
+      `AvsB datafile request to ${url} could not complete: ${String(error)}. This is a network, DNS, or TLS failure rather than a rejected key; the SDK retries on the polling interval.`
+    );
+    return { status: "failed" };
+  }
 }
-function parseRetryAfter(headerValue) {
-  if (!headerValue) return null;
-  const trimmed = headerValue.trim();
-  if (!trimmed) return null;
-  const n = Number(trimmed);
-  if (!Number.isFinite(n) || n < 0) return null;
-  return Math.round(n * 1e3);
+function sendHeartbeat(input) {
+  const endpoint = resolveHeartbeatEndpoint(input.datafileHeartbeatEndpoint);
+  if (!endpoint) return null;
+  void fetch(endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      sdkKey: input.sdkKey,
+      sdkType: input.sdkType,
+      sdkVersion: input.sdkVersion
+    }),
+    signal: input.signal
+  }).catch(() => void 0);
+  return endpoint;
+}
+
+// src/logger.ts
+import { consoleLogger, noopLogger, createLogger, consoleTransport } from "@avsbhq/core";
+function readDevGlobal() {
+  const flag = globalThis.__AVSB_DEV__;
+  return typeof flag === "boolean" ? flag : null;
+}
+function readNodeEnv() {
+  const value = globalThis.process?.env?.NODE_ENV;
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function isDevEnvironment() {
+  const explicit = readDevGlobal();
+  if (explicit !== null) return explicit;
+  const nodeEnv = readNodeEnv();
+  if (nodeEnv === null) return true;
+  return nodeEnv !== "production" && nodeEnv !== "test";
+}
+function defaultLogger() {
+  return isDevEnvironment() ? consoleLogger("warn") : noopLogger;
+}
+function resolveServerLogger(options) {
+  if (options.logger) return options.logger;
+  if (options.logLevel === "silent") return noopLogger;
+  if (options.logLevel) return consoleLogger(options.logLevel);
+  return defaultLogger();
 }
 
 // src/serverTracker.ts
+import { randomUUID } from "crypto";
+import { collectUrl } from "@avsbhq/core";
+import {
+  nextBackoff,
+  resetBackoff,
+  parseRetryAfter
+} from "@avsbhq/utils/backoff";
 function stampExposure(event) {
   return event.eventId ? event : { ...event, eventId: randomUUID() };
 }
@@ -317,9 +518,9 @@ function createServerTracker(options) {
     retryAttempts,
     logger
   } = options;
-  const batchEndpoint = collectEndpoint.replace(/\/?$/, "/v1/collect/batch");
-  const metricEndpoint = collectEndpoint.replace(/\/?$/, "/v1/collect/metric-batch");
-  const ordersEndpoint = collectEndpoint.replace(/\/?$/, "/v1/collect/orders");
+  const batchEndpoint = collectUrl("batch", collectEndpoint);
+  const metricEndpoint = collectUrl("metricBatch", collectEndpoint);
+  const ordersEndpoint = collectUrl("orders", collectEndpoint);
   let exposureQueue = [];
   let metricQueue = [];
   let flushTimer = null;
@@ -466,76 +667,58 @@ import {
 } from "@avsbhq/utils/streaming";
 
 // src/version.ts
-var SDK_VERSION = "1.6.2";
+var SDK_VERSION = "1.7.0";
 
 // src/UserBoundClient.ts
+import { bucketingKey } from "@avsbhq/core";
 function createUserBoundClient(server, context) {
   const decisionLog = createDecisionLog();
   const forcedDecisions = /* @__PURE__ */ new Map();
-  function buildOptions(options) {
-    return {
-      context,
+  function evaluate(flagKey, defaultValue, expectedType, options) {
+    const forced = forcedDecisions.get(flagKey);
+    return server.evaluateInternal(flagKey, defaultValue, context, {
       decideOptions: options?.decideOptions,
-      decisionLog
-    };
+      // 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) {
-      const forced = forcedDecisions.get(flagKey);
-      if (forced) {
-        return server.getFlag(flagKey, defaultValue, {
-          ...buildOptions(options),
-          forcedVariationKey: forced.variationKey
-        });
-      }
-      return server.getFlag(flagKey, defaultValue, buildOptions(options));
+      return evaluate(flagKey, defaultValue, void 0, options);
     },
     getBoolFlag(flagKey, defaultValue, options) {
-      const forced = forcedDecisions.get(flagKey);
-      if (forced) {
-        return server.getBoolFlag(flagKey, defaultValue, {
-          ...buildOptions(options),
-          forcedVariationKey: forced.variationKey
-        });
-      }
-      return server.getBoolFlag(flagKey, defaultValue, buildOptions(options));
+      return evaluate(flagKey, defaultValue, "boolean", options);
     },
     getStringFlag(flagKey, defaultValue, options) {
-      const forced = forcedDecisions.get(flagKey);
-      if (forced) {
-        return server.getStringFlag(flagKey, defaultValue, {
-          ...buildOptions(options),
-          forcedVariationKey: forced.variationKey
-        });
-      }
-      return server.getStringFlag(flagKey, defaultValue, buildOptions(options));
+      return evaluate(flagKey, defaultValue, "string", options);
     },
     getNumberFlag(flagKey, defaultValue, options) {
-      const forced = forcedDecisions.get(flagKey);
-      if (forced) {
-        return server.getNumberFlag(flagKey, defaultValue, {
-          ...buildOptions(options),
-          forcedVariationKey: forced.variationKey
-        });
-      }
-      return server.getNumberFlag(flagKey, defaultValue, buildOptions(options));
+      return evaluate(flagKey, defaultValue, "number", options);
     },
     getJsonFlag(flagKey, defaultValue, options) {
-      const forced = forcedDecisions.get(flagKey);
-      if (forced) {
-        return server.getJsonFlag(flagKey, defaultValue, {
-          ...buildOptions(options),
-          forcedVariationKey: forced.variationKey
-        });
-      }
-      return server.getJsonFlag(flagKey, defaultValue, buildOptions(options));
+      return evaluate(flagKey, defaultValue, "json", options);
     },
     getAllFlags(options) {
-      return server.getAllFlags(context, 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);
     },
@@ -554,7 +737,10 @@ import { notFoundFlag } from "@avsbhq/core";
 function buildServerUtils(server) {
   const adapter = {
     getFlag(flagKey, defaultValue) {
-      return notFoundFlag(defaultValue, "no bound context");
+      return notFoundFlag(
+        defaultValue,
+        "no bound context: call server.forUser(context) and use its flag methods"
+      );
     },
     getAllFlags(opts) {
       const ctx = opts?.context;
@@ -575,10 +761,18 @@ function buildServerUtils(server) {
     },
     getDatafile: () => server.getDatafile(),
     getCurrentContext: () => null,
-    applyDatafile() {
-    },
-    applySnapshot() {
-    }
+    /**
+     * 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);
 }
@@ -590,63 +784,57 @@ var DEFAULT_EVENTS = {
   maxQueueSize: 1e4,
   retryAttempts: 3
 };
-var DEFAULT_STREAMING_ENDPOINT = "https://app.avsb.cloud/api/sdk/stream";
+var SDK_TYPE = "@avsbhq/node";
+var HEARTBEAT_MIN_INTERVAL_MS = 12e4;
 var AvsbServer = class {
   sdkKey;
-  pollingInterval;
   cdnHost;
+  pollingInterval;
   initTimeout;
   logger;
   stickyBucketService;
   eventOptions;
   streamingEnabled;
-  streamingEndpoint;
+  streamingEndpointOption;
+  overrides = createOverrideStore();
+  resolveDecideOptions;
   datafile;
+  datafileEtag = null;
   ready;
   destroyed;
   tracker;
   streamingClient;
-  pollingId;
+  pollingTimer;
   abortController = new AbortController();
-  overrides = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Map();
   readyPromise = null;
   pendingEvents = [];
+  pendingPurchases = [];
+  /** 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();
   /**
-   * §6: `client.utils.*` surface. Constructed lazily on first access so
-   * the utils package is only imported when actually consumed.
-   *
-   * The server's event surface (`ServerEventMap`) is a subset of the
-   * shared `ClientEventMap`; the utils-adapter `on` here ignores events
-   * the server doesn't emit (e.g. `flagChange`). Workstream 5 (CoW 6)
-   * harmonises the two maps when the streaming evaluator lands.
+   * `client.utils.*` surface, constructed lazily on first access so the utils
+   * package is only imported when actually consumed.
    */
   _utils = null;
   get utils() {
     if (!this._utils) {
       this._utils = buildServerUtils({
         getAllFlags: (ctx, opts) => this.getAllFlags(ctx, opts),
-        getFlag: (flagKey, defaultValue, opts) => this.getFlag(flagKey, defaultValue, opts),
+        getFlag: (flagKey, defaultValue, context) => this.getFlag(flagKey, defaultValue, context),
         track: (eventKey, payload) => this.track(eventKey, payload),
-        on: (event, cb) => {
-          if (event === "ready" || event === "configUpdate" || event === "evaluation" || event === "error" || event === "stickyOrphan") {
-            return this.on(
-              event,
-              cb
-            );
-          }
-          return () => void 0;
-        },
-        getDatafile: () => this.datafile
+        on: (event, cb) => this.onSharedEvent(event, cb),
+        getDatafile: () => this.datafile,
+        applyDatafileBootstrap: (df) => this.applyDatafileBootstrap(df)
       });
     }
     return this._utils;
   }
   /**
-   * Server-side datasets read surface (e-commerce suite Phase 2).
-   * Constructed lazily on first access, mirroring the `utils` getter.
-   * `client.datasets.get(slug, key)` resolves the live version from the
-   * current datafile and never throws; see ./datasets.ts.
+   * Server-side datasets read surface. `client.datasets.get(slug, key)`
+   * resolves the live version from the current datafile and never throws.
    */
   _datasets = null;
   get datasets() {
@@ -660,11 +848,10 @@ var AvsbServer = class {
     return this._datasets;
   }
   /**
-   * Server-side recommendations surface (e-commerce suite overhaul, C3).
-   * Constructed lazily on first access, mirroring the `datasets` getter.
-   * `client.recs.get({ recipe, … })` resolves the recipe registry from the
-   * current datafile and never throws; impressions/clicks ride the server
-   * tracker's queue and revenue attaches via the existing `trackPurchase`.
+   * Server-side recommendations surface. `client.recs.get({ recipe, … })`
+   * resolves the recipe registry from the current datafile and never throws;
+   * impressions and clicks ride the server tracker's queue and revenue
+   * attaches via `trackPurchase`.
    */
   _recs = null;
   get recs() {
@@ -681,75 +868,96 @@ var AvsbServer = class {
   constructor(options) {
     this.sdkKey = options.sdkKey;
     this.pollingInterval = Math.max(options.pollingInterval ?? 6e4, 5e3);
-    const rawCdnHost = options.cdnHost ?? "https://cdn.avsb.cloud";
-    this.cdnHost = rawCdnHost.endsWith("/") ? rawCdnHost.slice(0, -1) : rawCdnHost;
+    this.cdnHost = options.cdnHost;
     this.initTimeout = options.initTimeout ?? 1e4;
-    this.logger = options.logger ?? noopLogger;
+    this.logger = resolveServerLogger(options);
     this.stickyBucketService = options.stickyBucketService ?? null;
     this.eventOptions = { ...DEFAULT_EVENTS, ...options.events };
-    this.streamingEnabled = options.streaming ?? false;
-    this.streamingEndpoint = options.streamingEndpoint ?? DEFAULT_STREAMING_ENDPOINT;
+    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.pollingId = null;
+    this.pollingTimer = null;
+    this.resolveDecideOptions = createDecideOptionResolver(this.logger);
+    const keyShape = validateSdkKeyShape(this.sdkKey);
+    if (!keyShape.valid && keyShape.message) {
+      this.logger.error(keyShape.message);
+    }
   }
   // ---------------------------------------------------------------------------
-  // §5.4 onReady — never rejects, always resolves to InitResult
+  // 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;
   }
+  /** 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.initTracker();
-      this.startPolling();
-      this.startStreamingIfEnabled();
-      this.sendHeartbeat();
-      this.emit("ready");
+      this.onDatafileReadable();
       return { success: true, source: "bootstrap" };
     }
     try {
-      const result = await Promise.race([
-        this.fetchDatafile().then((df) => ({ df, timedOut: false })),
+      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({ df: null, timedOut: true }), this.initTimeout)
+          (resolve) => setTimeout(
+            () => resolve({ applied: false, timedOut: true }),
+            this.initTimeout
+          )
         )
       ]);
-      if (result.timedOut) {
+      if (outcome.timedOut) {
         this.startPolling();
-        this.startStreamingIfEnabled();
-        const error2 = new Error(`SDK initialization timed out after ${this.initTimeout}ms`);
+        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 (result.df) {
-        this.datafile = result.df;
-        this.initTracker();
-        this.ready = true;
-        this.startPolling();
-        this.startStreamingIfEnabled();
-        this.sendHeartbeat();
-        this.emit("ready");
+      if (outcome.applied) {
+        this.onDatafileReadable();
         return { success: true, source: "network" };
       }
       this.startPolling();
-      this.startStreamingIfEnabled();
-      const error = new Error("Failed to fetch datafile");
+      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();
-      this.startStreamingIfEnabled();
       const error = e instanceof Error ? e : new Error(String(e));
       this.emit("error", error);
       return { success: false, source: "error", error };
     }
   }
+  /** 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
   // ---------------------------------------------------------------------------
@@ -760,9 +968,9 @@ var AvsbServer = class {
       this.streamingClient.disconnect();
       this.streamingClient = null;
     }
-    if (this.pollingId) {
-      clearInterval(this.pollingId);
-      this.pollingId = null;
+    if (this.pollingTimer) {
+      clearTimeout(this.pollingTimer);
+      this.pollingTimer = null;
     }
     if (this.tracker) {
       await this.tracker.destroy();
@@ -775,127 +983,271 @@ var AvsbServer = class {
   async flush() {
     if (this.tracker) await this.tracker.flush();
   }
+  /**
+   * Fetch the datafile now and apply it if it changed.
+   *
+   * A 304 is not a problem and is not warned about: it means the datafile in
+   * memory IS the published one.
+   */
   async refreshDatafile() {
-    const df = await this.fetchDatafile();
-    if (!df) {
-      this.logger.warn("Datafile refresh failed, keeping current datafile");
-      return;
+    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."
+      );
     }
-    const changed = !this.datafile || this.datafile.publishedAt !== df.publishedAt;
-    this.datafile = df;
+  }
+  /**
+   * Adopt a datafile received out of band: a bootstrap blob from
+   * `client.utils.hydrateBootstrap`, a file on disk, a KV read at cold start.
+   *
+   * Marks the SDK ready, drains anything queued before it, and starts polling
+   * and streaming exactly as a network arrival would. This used to be a no-op
+   * comment inside the utils adapter, which made the documented bootstrap
+   * 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.initTracker();
-      this.ready = true;
-      this.emit("ready");
-    } else if (changed) {
-      this.emit("configUpdate", { publishedAt: df.publishedAt });
-      this.logger.info("Datafile updated", { publishedAt: df.publishedAt });
+      this.onDatafileReadable();
+      return;
+    }
+    if (changed) {
+      this.emit("configUpdate", {
+        publishedAt: datafile.publishedAt,
+        reason: "manual"
+      });
     }
   }
+  /** The datafile currently in memory, or null before init completes. */
+  getDatafile() {
+    return this.datafile;
+  }
   // ---------------------------------------------------------------------------
-  // §5.3 getFlag — required defaultValue, returns Flag<T>
+  // 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, options) {
-    const context = options?.context;
-    const decisionLog = options?.decisionLog;
+  getFlag(flagKey, defaultValue, context, options) {
+    return this.evaluateInternal(flagKey, defaultValue, context, options);
+  }
+  getBoolFlag(flagKey, defaultValue, context, options) {
+    return this.evaluateInternal(flagKey, defaultValue, context, {
+      ...options,
+      expectedType: "boolean"
+    });
+  }
+  getStringFlag(flagKey, defaultValue, context, options) {
+    return this.evaluateInternal(flagKey, defaultValue, context, {
+      ...options,
+      expectedType: "string"
+    });
+  }
+  getNumberFlag(flagKey, defaultValue, context, options) {
+    return this.evaluateInternal(flagKey, defaultValue, context, {
+      ...options,
+      expectedType: "number"
+    });
+  }
+  getJsonFlag(flagKey, defaultValue, context, options) {
+    return this.evaluateInternal(flagKey, defaultValue, context, {
+      ...options,
+      expectedType: "json"
+    });
+  }
+  /**
+   * @internal Single evaluation entry point for this package. `UserBoundClient`
+   * calls it with a bound context and forced decisions. Not part of the
+   * published API: its options bag carries package-internal fields.
+   */
+  evaluateInternal(flagKey, defaultValue, context, options) {
     if (!context) {
-      this.logger.warn(
-        `getFlag called without context for flagKey="${flagKey}"; returning default`
+      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 notFoundFlag2(defaultValue, "no context provided");
-    }
-    if (!this.ready || !this.datafile) {
-      this.logger.debug(`SDK not ready, returning default for ${flagKey}`);
-      return notFoundFlag2(defaultValue, "SDK not ready");
-    }
-    if (options?.forcedVariationKey) {
-      return this.buildFlagFromVariationKey(
-        flagKey,
-        options.forcedVariationKey,
+      return notReadyFlag(
         defaultValue,
-        "runtimeOverride",
-        context,
-        decisionLog
+        "no context passed; call server.forUser(context) or pass the context positionally"
       );
     }
-    const legacyCtx = this.buildLegacyContext(context, options);
-    const result = this.evaluate(flagKey, legacyCtx, defaultValue);
-    this.emitEvaluation(flagKey, result.value, bucketingKey(context), result.source);
-    return this.toFlag(result, defaultValue, flagKey, context, decisionLog);
-  }
-  // ---------------------------------------------------------------------------
-  // §5.11 Typed evaluator variants
-  // ---------------------------------------------------------------------------
-  getBoolFlag(flagKey, defaultValue, options) {
-    return this.getTypedFlag(flagKey, defaultValue, "boolean", options);
-  }
-  getStringFlag(flagKey, defaultValue, options) {
-    return this.getTypedFlag(flagKey, defaultValue, "string", options);
+    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;
   }
-  getNumberFlag(flagKey, defaultValue, options) {
-    return this.getTypedFlag(flagKey, defaultValue, "number", options);
+  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;
   }
-  getJsonFlag(flagKey, defaultValue, options) {
-    return this.getTypedFlag(flagKey, defaultValue, "json", options);
+  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;
   }
-  // ---------------------------------------------------------------------------
-  // §5.7 getAllFlags — returns Record<string, Flag>
-  // ---------------------------------------------------------------------------
+  /**
+   * Every flag in the environment, evaluated against one context.
+   *
+   * Positional context (B3). Note the deliberate difference from
+   * `@avsbhq/browser`, which keeps an options bag (`getAllFlags({context})`)
+   * because it is context-bound and the bag disambiguates its optional
+   * arguments.
+   */
   getAllFlags(context, options) {
-    if (!this.ready || !this.datafile) return {};
+    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 flagEntry of this.datafile.flags) {
-      const flagOptions = {
-        context,
-        decideOptions: options?.decideOptions
-      };
-      if (!fireExposures) {
-        const suppressCtx = this.buildLegacyContext(context, flagOptions);
-        suppressCtx.suppressExposure = true;
-        const result = this.evaluate(flagEntry.key, suppressCtx, void 0);
-        out[flagEntry.key] = this.toFlagNoLog(result, void 0, flagEntry.key);
-      } else {
-        out[flagEntry.key] = this.getFlag(flagEntry.key, void 0, flagOptions);
-      }
+    for (const entry of this.datafile.flags) {
+      out[entry.key] = this.evaluateInternal(entry.key, void 0, context, {
+        decideOptions,
+        decisionLog: options?.decisionLog
+      });
     }
     return out;
   }
   // ---------------------------------------------------------------------------
-  // Purchase tracking — fires immediately to /v1/collect/orders
-  // ---------------------------------------------------------------------------
-  async trackPurchase(visitorId, order) {
-    if (!this.tracker) {
-      this.logger.warn("trackPurchase called before tracker is ready; order dropped");
-      return;
-    }
-    return this.tracker.trackPurchase(visitorId, order);
-  }
-  // ---------------------------------------------------------------------------
-  // §5.6 Unified track — context required
+  // Tracking
   // ---------------------------------------------------------------------------
+  /**
+   * Queue a metric (conversion) event. Synchronous: it returns as soon as the
+   * event is queued, and the tracker batches it.
+   *
+   * The context rides in the payload rather than positionally because it is
+   * OPTIONAL vocabulary on the shared `TrackPayload` type and required only on
+   * the server; see the README for why the two runtimes read differently here.
+   */
   track(eventKey, payload) {
-    const context = payload.context;
-    const userId = bucketingKey(context);
+    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.pendingEvents.push({ eventKey, payload });
+      this.enqueuePending(eventKey, payload);
       return;
     }
     this.tracker.queueMetric({
-      visitorId: userId,
+      visitorId: bucketingKey2(payload.context),
       eventName: eventKey,
-      revenue: payload.value ?? null,
+      // 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: "",
-      ...payload.properties ? { properties: payload.properties } : {}
+      pageUrl: ""
     });
   }
-  // ---------------------------------------------------------------------------
-  // §5.13 manualExposure — updated to EvalContext
-  // ---------------------------------------------------------------------------
+  /**
+   * Send a purchase to `/v1/collect/orders`.
+   *
+   * 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);
+  }
+  /**
+   * Mark the moment a signup or login claimed an anonymous session. Same shape
+   * and same honesty as the browser client's `alias`.
+   *
+   * WHAT IT DOES: queues one `avsb_alias` event attributed to the NEW
+   * identity's key.
+   *
+   * WHAT IT DOES NOT DO, precisely:
+   *   - It does not rewrite sticky assignments or move past exposures. Nothing
+   *     already decided for either identity changes.
+   *   - It does not store the PREVIOUS key. The conversion wire
+   *     (`/v1/collect/metric-batch`) carries no properties column, so a
+   *     retroactive session join is not available yet.
+   *
+   * To keep one visitor's bucketing across a login, evaluate with the SAME
+   * context key on both sides. See "Sharing identity with the web snippet" in
+   * the README for the cross-surface version of the same rule.
+   */
+  alias(previousContext, newContext) {
+    this.logger.debug(
+      `alias: ${bucketingKey2(previousContext)} to ${bucketingKey2(newContext)}`
+    );
+    this.track("avsb_alias", { context: newContext });
+  }
+  /**
+   * Record an exposure for a flag without re-serving its value. Use it when
+   * the decision was read earlier with exposures suppressed and the visitor has
+   * now actually seen the result.
+   */
   manualExposure(flagKey, context) {
-    if (!this.ready || !this.datafile || !this.tracker) return;
-    const legacyCtx = this.buildLegacyContext(context, { suppressExposure: true });
+    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;
@@ -903,9 +1255,8 @@ var AvsbServer = class {
     if (!flag) return;
     const variation = flag.variations.find((v) => v.key === result.variationKey);
     if (!variation) return;
-    const userId = bucketingKey(context);
-    this.tracker.queue({
-      visitorId: userId,
+    this.deliverExposure({
+      visitorId: bucketingKey2(context),
       experimentId: result.ruleId,
       variationId: variation.id,
       eventName: "flag_exposure",
@@ -916,57 +1267,40 @@ var AvsbServer = class {
     });
   }
   // ---------------------------------------------------------------------------
-  // §5.8 forUser / createUserContext — UserBoundClient factory
+  // Per-request scoping
   // ---------------------------------------------------------------------------
+  /** A client with the context bound. The primary server pattern. */
   forUser(context) {
     return createUserBoundClient(this, context);
   }
+  /** Ergonomic alias for `forUser`. */
   createUserContext(context) {
     return createUserBoundClient(this, context);
   }
   // ---------------------------------------------------------------------------
-  // §5.9 Override methods — restructured storage
+  // Overrides
   // ---------------------------------------------------------------------------
   setOverrideForUser(flagKey, contextKey, variationKey, contextKind = "user") {
-    if (!this.overrides.has(flagKey)) {
-      this.overrides.set(flagKey, { perKindKey: /* @__PURE__ */ new Map() });
-    }
-    const entry = this.overrides.get(flagKey);
-    entry.perKindKey.set(`${contextKind}:${contextKey}`, variationKey);
+    this.overrides.setForContext(flagKey, contextKey, variationKey, contextKind);
   }
   setGlobalOverride(flagKey, variationKey) {
-    if (!this.overrides.has(flagKey)) {
-      this.overrides.set(flagKey, { perKindKey: /* @__PURE__ */ new Map() });
-    }
-    this.overrides.get(flagKey).global = variationKey;
+    this.overrides.setGlobal(flagKey, variationKey);
   }
   clearOverrideForUser(flagKey, contextKey, contextKind = "user") {
-    const entry = this.overrides.get(flagKey);
-    if (!entry) return;
-    entry.perKindKey.delete(`${contextKind}:${contextKey}`);
-    if (!entry.global && entry.perKindKey.size === 0) {
-      this.overrides.delete(flagKey);
-    }
+    this.overrides.clearForContext(flagKey, contextKey, contextKind);
   }
   clearGlobalOverride(flagKey) {
-    const entry = this.overrides.get(flagKey);
-    if (!entry) return;
-    entry.global = void 0;
-    if (entry.perKindKey.size === 0) {
-      this.overrides.delete(flagKey);
-    }
+    this.overrides.clearGlobal(flagKey);
   }
   clearAllOverrides() {
-    this.overrides.clear();
+    this.overrides.clearAll();
   }
-  // ---------------------------------------------------------------------------
-  // Decision log factory (convenience)
-  // ---------------------------------------------------------------------------
+  /** A fresh decision log to pass per call. `forUser` carries its own. */
   createDecisionLog() {
     return createDecisionLog();
   }
   // ---------------------------------------------------------------------------
-  // Event listener API — on() returns unsubscribe; off() kept for compat
+  // Events
   // ---------------------------------------------------------------------------
   on(event, cb) {
     if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
@@ -978,13 +1312,50 @@ var AvsbServer = class {
   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 — core evaluate
+  // Private — evaluation core
   // ---------------------------------------------------------------------------
   evaluate(flagKey, uc, defaultValue) {
     const reasons = [];
-    const rtOver = this.resolveRuntimeOverride(flagKey, uc.userId);
-    if (rtOver !== void 0) {
+    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,
@@ -1013,15 +1384,9 @@ var AvsbServer = class {
       }
     }
     const legacyCtx = { attributes: { userId: uc.userId, ...uc.attributes } };
-    const shouldFire = !uc.suppressExposure;
-    const onExposure = shouldFire ? (event) => {
-      if (uc.privateAttributes?.length && event.properties) {
-        const cleaned = { ...event.properties };
-        for (const k of uc.privateAttributes) delete cleaned[k];
-        event = { ...event, properties: cleaned };
-      }
-      this.tracker?.queue(event);
-    } : void 0;
+    const onExposure = uc.suppressExposure ? void 0 : (event) => {
+      this.deliverExposure(redactExposure(event, uc.privateAttributes));
+    };
     const r = evaluateFlag(
       flagKey,
       defaultValue,
@@ -1050,61 +1415,17 @@ var AvsbServer = class {
       reasons
     };
   }
-  // ---------------------------------------------------------------------------
-  // Private — typed evaluation helper
-  // ---------------------------------------------------------------------------
-  getTypedFlag(flagKey, defaultValue, expectedType, options) {
-    const flag = this.getFlag(flagKey, defaultValue, options);
-    if (flag.source === "not_found" || flag.source === "disabled") {
-      return flag;
-    }
-    const datafileFlag = findDatafileFlag(this.datafile, flagKey);
-    const mismatch = checkExpectedType(datafileFlag, expectedType, flag.value);
-    if (mismatch) {
-      this.logger.warn(
-        `Type mismatch on flag "${flagKey}": ${mismatch}; returning default`
-      );
-      return notFoundFlag2(defaultValue, mismatch);
-    }
-    return flag;
-  }
-  // ---------------------------------------------------------------------------
-  // Private — build Flag<T> from an EvalResult
-  // ---------------------------------------------------------------------------
-  toFlag(result, defaultValue, flagKey, context, decisionLog, startMicros) {
-    const evaluatedAt = Date.now();
-    const durationMicros = startMicros !== void 0 ? performance.now() * 1e3 - startMicros : 0;
-    const flag = createFlag({
-      value: result.value ?? defaultValue,
-      variationKey: result.variationKey,
-      source: result.source,
-      ruleId: result.ruleId,
-      ruleType: result.ruleType,
-      reasons: result.reasons,
-      evaluatedAt,
-      durationMicros: Math.round(durationMicros)
-    });
-    if (decisionLog) {
-      const privateAttrs = privateAttributesFrom(context);
-      const summary = contextSummary(context);
-      const redactedValue = privateAttrs.size > 0 && typeof result.value === "string" && privateAttrs.has(result.value) ? "[REDACTED]" : result.value;
-      decisionLog.entries.push({
-        flagKey,
-        value: redactedValue,
-        variationKey: result.variationKey,
-        source: result.source,
-        ruleId: result.ruleId,
-        ruleType: result.ruleType,
-        reasons: [...result.reasons],
-        evaluatedAt,
-        durationMicros: Math.round(durationMicros),
-        contextSummary: summary
-      });
-    }
-    return flag;
+  /**
+   * 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() };
+    this.tracker?.queue(stamped);
+    this.emit("exposure", stamped);
   }
-  /** toFlag variant that never writes a decision log (used by getAllFlags suppressed path). */
-  toFlagNoLog(result, defaultValue, _flagKey) {
+  toFlag(result, defaultValue) {
     return createFlag({
       value: result.value ?? defaultValue,
       variationKey: result.variationKey,
@@ -1116,28 +1437,47 @@ var AvsbServer = class {
       durationMicros: 0
     });
   }
-  /** Build a Flag<T> from a forced variation key (per-request override). */
-  buildFlagFromVariationKey(flagKey, variationKey, defaultValue, source, context, decisionLog) {
+  /** 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 value = vref ? vref.value : defaultValue;
-    const result = {
-      value,
+    const flag = createFlag({
+      value: vref ? vref.value : defaultValue,
       variationKey: vref ? vref.key : null,
-      source,
+      source: "runtimeOverride",
       ruleId: null,
       ruleType: null,
       reasons: [`forced decision: variationKey="${variationKey}"`]
-    };
-    return this.toFlag(result, defaultValue, flagKey, context, decisionLog);
+    });
+    this.recordDecision(flagKey, flag, context, options);
+    return flag;
   }
-  // ---------------------------------------------------------------------------
-  // Private — build LegacyUserContext from EvalContext
-  // ---------------------------------------------------------------------------
-  buildLegacyContext(context, options) {
+  /** 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 suppressExposure = options?.suppressExposure === true || options?.decideOptions?.includes("DISABLE_EXPOSURE") === true;
     const { userId: _uid, ...rest } = legacy.attributes;
     return {
       userId,
@@ -1147,18 +1487,7 @@ var AvsbServer = class {
     };
   }
   // ---------------------------------------------------------------------------
-  // Private — override resolution
-  // ---------------------------------------------------------------------------
-  resolveRuntimeOverride(flagKey, userId) {
-    const entry = this.overrides.get(flagKey);
-    if (!entry) return void 0;
-    const userVk = entry.perKindKey.get(`user:${userId}`);
-    const vk = userVk ?? entry.global;
-    if (!vk) return void 0;
-    return this.findVariation(flagKey, vk) ?? void 0;
-  }
-  // ---------------------------------------------------------------------------
-  // Private — sticky bucket helpers
+  // Private — sticky helpers
   // ---------------------------------------------------------------------------
   resolveStickyBucket(flagKey, userId) {
     if (!this.stickyBucketService || !this.datafile) return void 0;
@@ -1200,7 +1529,7 @@ var AvsbServer = class {
       });
       return;
     }
-    this.tracker.queue({
+    this.deliverExposure({
       visitorId: uc.userId,
       experimentId: rule.id,
       variationId: sticky.vref.id,
@@ -1212,25 +1541,7 @@ var AvsbServer = class {
     });
   }
   // ---------------------------------------------------------------------------
-  // Private — event emission
-  // ---------------------------------------------------------------------------
-  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) });
-      }
-    }
-  }
-  emitEvaluation(flagKey, value, userId, source) {
-    this.emit("evaluation", { flagKey, value, userId, source });
-  }
-  // ---------------------------------------------------------------------------
-  // Private — tracker + polling + streaming
+  // Private — tracker, polling, streaming, heartbeat
   // ---------------------------------------------------------------------------
   initTracker() {
     if (!this.datafile || this.tracker) return;
@@ -1246,152 +1557,143 @@ var AvsbServer = class {
     if (this.pendingEvents.length > 0) {
       const queued = this.pendingEvents;
       this.pendingEvents = [];
-      for (const item of queued) {
-        this.track(item.eventKey, item.payload);
-      }
+      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);
+    }
+  }
+  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: this.streamingEndpoint,
+      endpoint: resolution.endpoint,
       sdkKey: this.sdkKey,
       onDatafileUpdated: () => {
-        void this.refreshDatafile();
+        void this.loadDatafile("stream");
       },
       logger: this.logger
     });
     this.streamingClient.connect();
+    this.logger.debug(
+      `Streaming datafile updates from ${resolution.endpoint} (${resolution.source}).`
+    );
   }
-  async fetchDatafile() {
-    const url = `${this.cdnHost}/${this.sdkKey}/datafile.json`;
-    try {
-      const res = await fetch(url, { signal: this.abortController.signal });
-      if (!res.ok) {
-        this.logger.warn("Datafile fetch failed", { status: res.status, url });
-        return null;
-      }
-      return await res.json();
-    } catch (e) {
-      if (this.abortController.signal.aborted) return null;
-      this.logger.warn("Datafile fetch error", { error: String(e), url });
-      return null;
-    }
-  }
-  startPolling() {
-    if (this.pollingId || this.destroyed) return;
-    this.pollingId = setInterval(async () => {
-      const df = await this.fetchDatafile();
-      if (!df) return;
-      const changed = !this.datafile || this.datafile.publishedAt !== df.publishedAt;
-      if (!this.ready) {
-        this.datafile = df;
-        this.initTracker();
-        this.ready = true;
-        this.emit("ready");
-      } else if (changed) {
-        this.datafile = df;
-        this.emit("configUpdate", { publishedAt: df.publishedAt });
-        this.logger.info("Datafile updated", { publishedAt: df.publishedAt });
-      }
-    }, this.pollingInterval);
-  }
+  /**
+   * 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() {
-    if (!this.datafile?.heartbeatEndpoint) return;
-    fetch(this.datafile.heartbeatEndpoint, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        sdkKey: this.sdkKey,
-        sdkType: "@avsbhq/node",
-        sdkVersion: SDK_VERSION
-      }),
+    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
-    }).catch(() => {
     });
+    if (posted) this.lastHeartbeatAt = now;
   }
 };
 
-// src/middleware.ts
-function createNoopUserBoundClient() {
-  const noopFlag = (defaultValue) => ({
-    value: defaultValue,
-    variationKey: null,
-    source: "not_found",
-    ruleId: null,
-    ruleType: null,
-    reasons: ["no userId available"],
-    evaluatedAt: Date.now(),
-    durationMicros: 0,
-    isEnabled: () => false,
-    exists: () => false
-  });
-  return {
-    getFlag(_flagKey, defaultValue) {
-      return noopFlag(defaultValue);
-    },
-    getBoolFlag(_flagKey, defaultValue) {
-      return noopFlag(defaultValue);
-    },
-    getStringFlag(_flagKey, defaultValue) {
-      return noopFlag(defaultValue);
-    },
-    getNumberFlag(_flagKey, defaultValue) {
-      return noopFlag(defaultValue);
-    },
-    getJsonFlag(_flagKey, defaultValue) {
-      return noopFlag(defaultValue);
-    },
-    getAllFlags() {
-      return {};
-    },
-    track() {
-    },
-    setForcedDecision() {
-    },
-    clearForcedDecision() {
-    },
-    getDecisionLog() {
-      return { entries: [] };
-    }
-  };
-}
-function expressMiddleware(client, config) {
-  return (req, res, next) => {
-    const userId = config.userIdFrom(req);
-    if (!userId) {
-      ;
-      req.avsb = createNoopUserBoundClient();
-      return next();
-    }
-    const attributes = config.attributesFrom?.(req) ?? {};
-    const context = { kind: "user", key: userId, ...attributes };
-    req.avsb = client.forUser(context);
-    next();
-  };
-}
-function fastifyPlugin(instance, opts, done) {
-  const fastify = instance;
-  fastify.decorateRequest("avsb", null);
-  fastify.addHook("onRequest", (...args) => {
-    const req = args[0];
-    const hookDone = args[2];
-    const userId = opts.userIdFrom(req);
-    if (!userId) {
-      ;
-      req.avsb = createNoopUserBoundClient();
-      return hookDone();
-    }
-    const attributes = opts.attributesFrom?.(req) ?? {};
-    const context = { kind: "user", key: userId, ...attributes };
-    req.avsb = opts.client.forUser(context);
-    hookDone();
-  });
-  done();
-}
-
-// src/logger.ts
-import { noopLogger as noopLogger2, createLogger, consoleLogger, consoleTransport } from "@avsbhq/core";
+// src/index.ts
+import { expressMiddleware } from "@avsbhq/utils/middleware/express";
+import { fastifyPlugin } from "@avsbhq/utils/middleware/fastify";
 
 // src/stickyBucket.ts
 var InMemoryStickyBucketService = class {
@@ -1423,7 +1725,7 @@ var RedisStickyBucketService = class {
     this.prefix = options.prefix ?? "avsb:sticky:";
     this.ttl = options.ttl ?? 2592e3;
     this.maxCacheSize = options.cacheSize ?? 1e4;
-    this.logger = options.logger ?? noopLogger2;
+    this.logger = options.logger ?? noopLogger;
   }
   redisKey(userId, flagKey) {
     return `${this.prefix}${userId}:${flagKey}`;
@@ -1485,11 +1787,88 @@ var RedisStickyBucketService = class {
   }
 };
 
+// src/webhookSignature.ts
+import crypto from "crypto";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var HEADER_ID = "x-avsb-delivery-id";
+var HEADER_TIMESTAMP = "x-avsb-timestamp";
+var HEADER_SIGNATURE = "x-avsb-signature";
+function readHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  const bag = headers;
+  const value = bag[name] ?? bag[name.toUpperCase()] ?? findCaseInsensitive(bag, name);
+  if (value === void 0) return null;
+  return Array.isArray(value) ? value[0] ?? null : value;
+}
+function findCaseInsensitive(bag, name) {
+  for (const key of Object.keys(bag)) {
+    if (key.toLowerCase() === name) return bag[key];
+  }
+  return void 0;
+}
+function digestsMatch(a, b) {
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+function verifyWebhookSignature(payload, headers, secret, options = {}) {
+  const deliveryId = readHeader(headers, HEADER_ID);
+  const timestamp = readHeader(headers, HEADER_TIMESTAMP);
+  const signatureHeader = readHeader(headers, HEADER_SIGNATURE);
+  if (!deliveryId || !timestamp || !signatureHeader) {
+    return {
+      ok: false,
+      reason: "missing_headers",
+      message: `Expected ${HEADER_ID}, ${HEADER_TIMESTAMP} and ${HEADER_SIGNATURE} headers. Got id=${Boolean(deliveryId)} timestamp=${Boolean(timestamp)} signature=${Boolean(signatureHeader)}.`
+    };
+  }
+  if (!signatureHeader.startsWith("sha256=")) {
+    return {
+      ok: false,
+      reason: "malformed_signature",
+      message: `${HEADER_SIGNATURE} must look like "sha256=<hex>", got "${signatureHeader.slice(0, 16)}\u2026".`
+    };
+  }
+  const provided = signatureHeader.slice("sha256=".length);
+  const signedAtMs = Date.parse(timestamp);
+  if (Number.isNaN(signedAtMs)) {
+    return {
+      ok: false,
+      reason: "malformed_timestamp",
+      message: `${HEADER_TIMESTAMP} is not an ISO-8601 instant: "${timestamp}".`
+    };
+  }
+  const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (tolerance > 0) {
+    const nowMs = (options.now ?? Date.now)();
+    const ageSeconds = Math.abs(nowMs - signedAtMs) / 1e3;
+    if (ageSeconds > tolerance) {
+      return {
+        ok: false,
+        reason: "timestamp_out_of_tolerance",
+        message: `Delivery signed ${Math.round(ageSeconds)}s from now, outside the ${tolerance}s tolerance. Check your server clock, or raise toleranceSeconds.`
+      };
+    }
+  }
+  const body = typeof payload === "string" ? payload : payload.toString("utf8");
+  const expected = crypto.createHmac("sha256", secret).update(`${deliveryId}.${timestamp}.${body}`).digest("hex");
+  if (!digestsMatch(provided, expected)) {
+    return {
+      ok: false,
+      reason: "signature_mismatch",
+      message: "Signature does not match. Most common causes: the body was parsed and re-serialised before verification (use the raw bytes), or the secret is from a different webhook."
+    };
+  }
+  return { ok: true, deliveryId, timestamp };
+}
+
 // src/index.ts
-import { DecideOption } from "@avsbhq/core";
+import { DecideOption as DecideOption2 } from "@avsbhq/core";
 export {
   AvsbServer,
-  DecideOption,
+  DEFAULT_TOLERANCE_SECONDS,
+  DecideOption2 as DecideOption,
   InMemoryStickyBucketService,
   RedisStickyBucketService,
   SDK_VERSION,
@@ -1498,7 +1877,11 @@ export {
   createDecisionLog,
   createLogger,
   createStreamingClient,
+  defaultLogger,
   expressMiddleware,
   fastifyPlugin,
-  noopLogger2 as noopLogger
+  isDevEnvironment,
+  noopLogger,
+  resolveServerLogger,
+  verifyWebhookSignature
 };