@octomil/browser 1.0.0

package/dist/index.cjs

@@ -0,0 +1,2148 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DeviceAuthManager: () => DeviceAuthManager,
+  ExperimentsClient: () => ExperimentsClient,
+  FederatedClient: () => FederatedClient,
+  InferenceEngine: () => InferenceEngine,
+  ModelLoader: () => ModelLoader,
+  Octomil: () => Octomil,
+  OctomilError: () => OctomilError,
+  RolloutsManager: () => RolloutsManager,
+  SecAggPlus: () => SecAggPlus,
+  SecureAggregation: () => SecureAggregation,
+  StreamingInferenceEngine: () => StreamingInferenceEngine,
+  TelemetryReporter: () => TelemetryReporter,
+  WeightExtractor: () => WeightExtractor,
+  addGaussianNoise: () => addGaussianNoise,
+  assertModelIntegrity: () => assertModelIntegrity,
+  clipGradients: () => clipGradients,
+  computeHash: () => computeHash,
+  createModelCache: () => createModelCache,
+  dequantize: () => dequantize,
+  disposeTelemetry: () => disposeTelemetry,
+  getTelemetry: () => getTelemetry,
+  initTelemetry: () => initTelemetry,
+  quantize: () => quantize,
+  shamirReconstruct: () => shamirReconstruct,
+  shamirSplit: () => shamirSplit,
+  verifyModelIntegrity: () => verifyModelIntegrity
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var OctomilError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "OctomilError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+
+// src/cache.ts
+var CACHE_NAME = "octomil-models-v1";
+var IDB_DB_NAME = "octomil-models";
+var IDB_STORE_NAME = "blobs";
+var IDB_VERSION = 1;
+var CacheApiModelCache = class {
+  async open() {
+    return caches.open(CACHE_NAME);
+  }
+  async get(key) {
+    const cache = await this.open();
+    const response = await cache.match(key);
+    if (!response) return null;
+    return response.arrayBuffer();
+  }
+  async put(key, data) {
+    const cache = await this.open();
+    const response = new Response(data, {
+      headers: {
+        "x-octomil-cached-at": (/* @__PURE__ */ new Date()).toISOString(),
+        "x-octomil-size": String(data.byteLength)
+      }
+    });
+    await cache.put(key, response);
+  }
+  async has(key) {
+    const cache = await this.open();
+    const match = await cache.match(key);
+    return match !== void 0;
+  }
+  async remove(key) {
+    const cache = await this.open();
+    await cache.delete(key);
+  }
+  async info(key) {
+    const cache = await this.open();
+    const response = await cache.match(key);
+    if (!response) {
+      return { cached: false, sizeBytes: 0 };
+    }
+    const sizeHeader = response.headers.get("x-octomil-size");
+    const cachedAtHeader = response.headers.get("x-octomil-cached-at");
+    return {
+      cached: true,
+      sizeBytes: sizeHeader ? parseInt(sizeHeader, 10) : 0,
+      cachedAt: cachedAtHeader ?? void 0
+    };
+  }
+};
+var IndexedDBModelCache = class {
+  dbPromise = null;
+  openDB() {
+    if (this.dbPromise) return this.dbPromise;
+    this.dbPromise = new Promise((resolve, reject) => {
+      const request = indexedDB.open(IDB_DB_NAME, IDB_VERSION);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(IDB_STORE_NAME)) {
+          db.createObjectStore(IDB_STORE_NAME, { keyPath: "key" });
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+    return this.dbPromise;
+  }
+  async tx(mode) {
+    const db = await this.openDB();
+    const transaction = db.transaction(IDB_STORE_NAME, mode);
+    return transaction.objectStore(IDB_STORE_NAME);
+  }
+  async get(key) {
+    const store = await this.tx("readonly");
+    return new Promise((resolve, reject) => {
+      const request = store.get(key);
+      request.onsuccess = () => {
+        const entry = request.result;
+        resolve(entry?.data ?? null);
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async put(key, data) {
+    const store = await this.tx("readwrite");
+    const entry = {
+      key,
+      data,
+      sizeBytes: data.byteLength,
+      cachedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return new Promise((resolve, reject) => {
+      const request = store.put(entry);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async has(key) {
+    const store = await this.tx("readonly");
+    return new Promise((resolve, reject) => {
+      const request = store.count(key);
+      request.onsuccess = () => resolve(request.result > 0);
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async remove(key) {
+    const store = await this.tx("readwrite");
+    return new Promise((resolve, reject) => {
+      const request = store.delete(key);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+  async info(key) {
+    const store = await this.tx("readonly");
+    return new Promise((resolve, reject) => {
+      const request = store.get(key);
+      request.onsuccess = () => {
+        const entry = request.result;
+        if (!entry) {
+          resolve({ cached: false, sizeBytes: 0 });
+        } else {
+          resolve({
+            cached: true,
+            sizeBytes: entry.sizeBytes,
+            cachedAt: entry.cachedAt
+          });
+        }
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+};
+var NoopModelCache = class {
+  async get(_key) {
+    return null;
+  }
+  async put(_key, _data) {
+  }
+  async has(_key) {
+    return false;
+  }
+  async remove(_key) {
+  }
+  async info(_key) {
+    return { cached: false, sizeBytes: 0 };
+  }
+};
+function createModelCache(strategy) {
+  if (strategy === "none") {
+    return new NoopModelCache();
+  }
+  if (strategy === "cache-api") {
+    if (typeof caches !== "undefined") {
+      return new CacheApiModelCache();
+    }
+    if (typeof indexedDB !== "undefined") {
+      return new IndexedDBModelCache();
+    }
+    return new NoopModelCache();
+  }
+  if (strategy === "indexeddb") {
+    if (typeof indexedDB !== "undefined") {
+      return new IndexedDBModelCache();
+    }
+    return new NoopModelCache();
+  }
+  throw new OctomilError(
+    "CACHE_ERROR",
+    `Unknown cache strategy: ${strategy}`
+  );
+}
+
+// src/inference.ts
+var InferenceEngine = class {
+  session = null;
+  ortModule = null;
+  resolvedBackend = null;
+  // -----------------------------------------------------------------------
+  // Public
+  // -----------------------------------------------------------------------
+  /**
+   * Create an ONNX Runtime session from the given model bytes.
+   *
+   * @param modelData  Raw ONNX model ArrayBuffer.
+   * @param backend    Requested backend (`"webgpu"`, `"wasm"`, or `undefined` for auto).
+   */
+  async createSession(modelData, backend) {
+    const ortMod = await this.loadOrt();
+    const provider = await this.resolveProvider(ortMod, backend);
+    this.resolvedBackend = provider === "webgpu" ? "webgpu" : "wasm";
+    const sessionOptions = {
+      executionProviders: [provider],
+      graphOptimizationLevel: "all"
+    };
+    try {
+      this.session = await ortMod.InferenceSession.create(
+        modelData,
+        sessionOptions
+      );
+    } catch (err) {
+      if (provider === "webgpu") {
+        try {
+          this.session = await ortMod.InferenceSession.create(modelData, {
+            executionProviders: ["wasm"],
+            graphOptimizationLevel: "all"
+          });
+          this.resolvedBackend = "wasm";
+        } catch (wasmErr) {
+          throw new OctomilError(
+            "MODEL_LOAD_FAILED",
+            "Failed to create ONNX session with both WebGPU and WASM backends.",
+            wasmErr
+          );
+        }
+      } else {
+        throw new OctomilError(
+          "MODEL_LOAD_FAILED",
+          `Failed to create ONNX session: ${String(err)}`,
+          err
+        );
+      }
+    }
+  }
+  /**
+   * Run inference and return the output tensors plus timing info.
+   */
+  async run(inputs) {
+    this.ensureSession();
+    const ortMod = this.ortModule;
+    const session = this.session;
+    const feeds = {};
+    for (const [name, tensor] of Object.entries(inputs)) {
+      feeds[name] = new ortMod.Tensor(
+        inferOrtType(tensor.data),
+        tensor.data,
+        tensor.dims
+      );
+    }
+    const start = performance.now();
+    let results;
+    try {
+      results = await session.run(feeds);
+    } catch (err) {
+      throw new OctomilError(
+        "INFERENCE_FAILED",
+        `Inference run failed: ${String(err)}`,
+        err
+      );
+    }
+    const latencyMs = performance.now() - start;
+    const tensors = this.convertOutputs(results);
+    const convenience = this.extractConvenience(tensors);
+    return {
+      tensors,
+      latencyMs,
+      ...convenience
+    };
+  }
+  /** Names of the model's input tensors. */
+  get inputNames() {
+    this.ensureSession();
+    return this.session.inputNames;
+  }
+  /** Names of the model's output tensors. */
+  get outputNames() {
+    this.ensureSession();
+    return this.session.outputNames;
+  }
+  /** The backend that was actually used after negotiation. */
+  get activeBackend() {
+    return this.resolvedBackend;
+  }
+  /** Release WASM / WebGPU resources. */
+  dispose() {
+    if (this.session) {
+      void this.session.release();
+      this.session = null;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  async loadOrt() {
+    if (this.ortModule) return this.ortModule;
+    try {
+      this.ortModule = await import("onnxruntime-web");
+      return this.ortModule;
+    } catch (err) {
+      throw new OctomilError(
+        "BACKEND_UNAVAILABLE",
+        "Failed to import onnxruntime-web. Make sure the package is installed: npm i onnxruntime-web",
+        err
+      );
+    }
+  }
+  async resolveProvider(_ortMod, backend) {
+    if (backend === "wasm") return "wasm";
+    if (backend === "webgpu" || backend === void 0) {
+      const hasWebGPU = await this.detectWebGPU();
+      if (hasWebGPU) return "webgpu";
+      if (backend === "webgpu") {
+        throw new OctomilError(
+          "BACKEND_UNAVAILABLE",
+          "WebGPU was explicitly requested but is not available in this browser."
+        );
+      }
+    }
+    return "wasm";
+  }
+  async detectWebGPU() {
+    if (typeof navigator === "undefined") return false;
+    try {
+      const gpu = navigator.gpu;
+      if (!gpu) return false;
+      const adapter = await gpu.requestAdapter();
+      return adapter !== null;
+    } catch {
+      return false;
+    }
+  }
+  ensureSession() {
+    if (!this.session) {
+      throw new OctomilError(
+        "SESSION_DISPOSED",
+        "No active session. Call load() before running inference."
+      );
+    }
+  }
+  convertOutputs(results) {
+    const tensors = {};
+    for (const name of Object.keys(results)) {
+      const ortTensor = results[name];
+      tensors[name] = {
+        data: ortTensor.data,
+        dims: Array.from(ortTensor.dims)
+      };
+    }
+    return tensors;
+  }
+  /**
+   * Best-effort extraction of `label` / `score` / `scores` from the
+   * first output tensor — only if it looks like a classification head.
+   */
+  extractConvenience(tensors) {
+    const names = Object.keys(tensors);
+    if (names.length === 0) return {};
+    const first = tensors[names[0]];
+    const data = first.data;
+    if (!(data instanceof Float32Array)) return {};
+    if (data.length === 0) return {};
+    const scores = Array.from(data);
+    let maxIdx = 0;
+    let maxVal = -Infinity;
+    for (let i = 0; i < scores.length; i++) {
+      if (scores[i] > maxVal) {
+        maxVal = scores[i];
+        maxIdx = i;
+      }
+    }
+    return {
+      label: String(maxIdx),
+      score: maxVal,
+      scores
+    };
+  }
+};
+function inferOrtType(data) {
+  if (data instanceof Float32Array) return "float32";
+  if (data instanceof Int32Array) return "int32";
+  if (data instanceof BigInt64Array) return "int64";
+  if (data instanceof Uint8Array) return "uint8";
+  return "float32";
+}
+
+// src/model-loader.ts
+var MAX_RETRIES = 3;
+var RETRY_DELAY_MS = 1e3;
+var ModelLoader = class {
+  modelId;
+  serverUrl;
+  apiKey;
+  onProgress;
+  cache;
+  constructor(options, cache) {
+    this.modelId = options.model;
+    this.serverUrl = options.serverUrl;
+    this.apiKey = options.apiKey;
+    this.onProgress = options.onProgress;
+    this.cache = cache;
+  }
+  // -----------------------------------------------------------------------
+  // Public
+  // -----------------------------------------------------------------------
+  /**
+   * Resolve the model URL, check the cache, download if needed,
+   * and return the ONNX model bytes.
+   */
+  async load() {
+    const url = await this.resolveModelUrl();
+    const cached = await this.cache.get(url);
+    if (cached) {
+      return cached;
+    }
+    const data = await this.download(url);
+    this.validate(data);
+    await this.cache.put(url, data);
+    return data;
+  }
+  /** Check whether the model is already cached. */
+  async isCached() {
+    const url = await this.resolveModelUrl();
+    return this.cache.has(url);
+  }
+  /** Remove the cached model. */
+  async clearCache() {
+    const url = await this.resolveModelUrl();
+    await this.cache.remove(url);
+  }
+  /** Get cache info for the model. */
+  async getCacheInfo() {
+    const url = await this.resolveModelUrl();
+    return this.cache.info(url);
+  }
+  // -----------------------------------------------------------------------
+  // Internal — URL resolution
+  // -----------------------------------------------------------------------
+  /**
+   * If `modelId` looks like a URL (starts with http:// or https://) use it
+   * directly.  Otherwise treat it as a registry model name and resolve via
+   * the Octomil server.
+   */
+  async resolveModelUrl() {
+    if (this.modelId.startsWith("http://") || this.modelId.startsWith("https://")) {
+      return this.modelId;
+    }
+    if (!this.serverUrl) {
+      throw new OctomilError(
+        "MODEL_NOT_FOUND",
+        `Cannot resolve model "${this.modelId}": no serverUrl configured.`
+      );
+    }
+    return this.fetchRegistryUrl(this.modelId);
+  }
+  async fetchRegistryUrl(name) {
+    const registryUrl = `${this.serverUrl}/api/v1/models/${encodeURIComponent(name)}/metadata`;
+    const headers = {
+      Accept: "application/json"
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    let response;
+    try {
+      response = await fetch(registryUrl, { headers });
+    } catch (err) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Failed to reach model registry at ${registryUrl}`,
+        err
+      );
+    }
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new OctomilError(
+          "MODEL_NOT_FOUND",
+          `Model "${name}" not found in registry.`
+        );
+      }
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Registry returned HTTP ${response.status}: ${response.statusText}`
+      );
+    }
+    const metadata = await response.json();
+    return metadata.url;
+  }
+  // -----------------------------------------------------------------------
+  // Internal — download
+  // -----------------------------------------------------------------------
+  buildHeaders(extra = {}) {
+    const headers = {
+      "Accept-Encoding": "gzip, deflate, br",
+      ...extra
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+  async download(url) {
+    const chunks = [];
+    let loaded = 0;
+    let totalSize = 0;
+    let attempt = 0;
+    while (attempt <= MAX_RETRIES) {
+      const headers = this.buildHeaders(
+        loaded > 0 ? { Range: `bytes=${loaded}-` } : {}
+      );
+      let response;
+      try {
+        response = await fetch(url, { headers });
+      } catch (err) {
+        attempt++;
+        if (attempt > MAX_RETRIES) {
+          throw new OctomilError(
+            "NETWORK_ERROR",
+            `Failed to download model from ${url} after ${MAX_RETRIES} retries`,
+            err
+          );
+        }
+        await this.delay(RETRY_DELAY_MS * attempt);
+        continue;
+      }
+      if (response.status === 416) {
+        chunks.length = 0;
+        loaded = 0;
+        attempt++;
+        if (attempt > MAX_RETRIES) {
+          throw new OctomilError(
+            "MODEL_LOAD_FAILED",
+            `Model download failed: range request rejected after ${MAX_RETRIES} retries`
+          );
+        }
+        await this.delay(RETRY_DELAY_MS * attempt);
+        continue;
+      }
+      if (!response.ok && response.status !== 206) {
+        throw new OctomilError(
+          "MODEL_LOAD_FAILED",
+          `Model download failed: HTTP ${response.status} ${response.statusText}`
+        );
+      }
+      if (totalSize === 0) {
+        const contentRange = response.headers.get("Content-Range");
+        if (contentRange) {
+          const match = contentRange.match(/\/(\d+)$/);
+          if (match) totalSize = parseInt(match[1], 10);
+        } else {
+          totalSize = parseInt(response.headers.get("Content-Length") ?? "0", 10);
+        }
+      }
+      if (!response.body) {
+        const buf = await response.arrayBuffer();
+        return buf;
+      }
+      const reader = response.body.getReader();
+      let streamFailed = false;
+      try {
+        for (; ; ) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          chunks.push(value);
+          loaded += value.byteLength;
+          this.onProgress?.({
+            loaded,
+            total: totalSize,
+            percent: totalSize > 0 ? loaded / totalSize * 100 : NaN
+          });
+        }
+      } catch (err) {
+        streamFailed = true;
+        attempt++;
+        if (attempt > MAX_RETRIES) {
+          throw new OctomilError(
+            "NETWORK_ERROR",
+            `Model download interrupted after ${MAX_RETRIES} retries`,
+            err
+          );
+        }
+        await this.delay(RETRY_DELAY_MS * attempt);
+      } finally {
+        reader.releaseLock();
+      }
+      if (!streamFailed) break;
+    }
+    const combined = new Uint8Array(loaded);
+    let offset = 0;
+    for (const chunk of chunks) {
+      combined.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return combined.buffer;
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // -----------------------------------------------------------------------
+  // Internal — validation
+  // -----------------------------------------------------------------------
+  validate(data) {
+    if (data.byteLength === 0) {
+      throw new OctomilError(
+        "MODEL_LOAD_FAILED",
+        "Downloaded model is empty (0 bytes)."
+      );
+    }
+    const header = new Uint8Array(data, 0, Math.min(4, data.byteLength));
+    if (header[0] !== 8) {
+      throw new OctomilError(
+        "MODEL_LOAD_FAILED",
+        "Downloaded file does not appear to be a valid ONNX model."
+      );
+    }
+  }
+};
+
+// src/telemetry.ts
+var DEFAULT_FLUSH_INTERVAL_MS = 3e4;
+var DEFAULT_MAX_BATCH_SIZE = 50;
+var DEFAULT_TELEMETRY_URL = "https://api.octomil.io/v1/telemetry";
+var TelemetryReporter = class {
+  url;
+  flushIntervalMs;
+  maxBatchSize;
+  apiKey;
+  queue = [];
+  timerId = null;
+  disposed = false;
+  constructor(options = {}) {
+    this.url = options.url ?? DEFAULT_TELEMETRY_URL;
+    this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+    this.apiKey = options.apiKey;
+    this.startAutoFlush();
+  }
+  // -----------------------------------------------------------------------
+  // Public
+  // -----------------------------------------------------------------------
+  /** Enqueue a telemetry event. Non-blocking, never throws. */
+  track(event) {
+    if (this.disposed) return;
+    this.queue.push(event);
+    if (this.queue.length >= this.maxBatchSize) {
+      void this.flush();
+    }
+  }
+  /** Flush all queued events immediately. */
+  async flush() {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.maxBatchSize);
+    await this.send(batch);
+  }
+  /** Stop the flush timer and send remaining events. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.timerId !== null) {
+      clearInterval(this.timerId);
+      this.timerId = null;
+    }
+    if (this.queue.length > 0) {
+      this.sendBeacon(this.queue.splice(0));
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  startAutoFlush() {
+    if (typeof setInterval === "undefined") return;
+    this.timerId = setInterval(() => {
+      void this.flush();
+    }, this.flushIntervalMs);
+  }
+  async send(events) {
+    const body = JSON.stringify({ events });
+    try {
+      if (this.sendBeacon(events)) return;
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
+      await fetch(this.url, {
+        method: "POST",
+        headers,
+        body,
+        keepalive: true
+      });
+    } catch {
+    }
+  }
+  sendBeacon(events) {
+    if (typeof navigator === "undefined" || !navigator.sendBeacon) {
+      return false;
+    }
+    try {
+      const blob = new Blob([JSON.stringify({ events })], {
+        type: "application/json"
+      });
+      return navigator.sendBeacon(this.url, blob);
+    } catch {
+      return false;
+    }
+  }
+};
+var _reporter = null;
+function initTelemetry(options = {}) {
+  if (_reporter) {
+    _reporter.dispose();
+  }
+  _reporter = new TelemetryReporter(options);
+  return _reporter;
+}
+function getTelemetry() {
+  return _reporter;
+}
+function disposeTelemetry() {
+  _reporter?.dispose();
+  _reporter = null;
+}
+
+// src/streaming.ts
+var StreamingInferenceEngine = class {
+  serverUrl;
+  apiKey;
+  onTelemetry;
+  constructor(options) {
+    this.serverUrl = options.serverUrl;
+    this.apiKey = options.apiKey;
+    this.onTelemetry = options.onTelemetry;
+  }
+  /**
+   * Stream inference results from the server.
+   *
+   * Returns an async iterable of chunks. Supports cancellation via AbortSignal.
+   */
+  async *stream(modelId, input, options = {}) {
+    const abortController = new AbortController();
+    const signal = options.signal ? this.combineSignals(options.signal, abortController.signal) : abortController.signal;
+    const url = `${this.serverUrl}/api/v1/models/${encodeURIComponent(modelId)}/stream`;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "text/event-stream"
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const startTime = performance.now();
+    let ttfc = null;
+    let chunkCount = 0;
+    let totalBytes = 0;
+    this.onTelemetry?.({
+      type: "streaming_start",
+      model: modelId,
+      metadata: { modality: options.modality ?? "text" },
+      timestamp: Date.now()
+    });
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          input,
+          modality: options.modality ?? "text",
+          ...options.params
+        }),
+        signal
+      });
+    } catch (err) {
+      this.onTelemetry?.({
+        type: "streaming_error",
+        model: modelId,
+        metadata: { error: String(err) },
+        timestamp: Date.now()
+      });
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Streaming request failed: ${String(err)}`,
+        err
+      );
+    }
+    if (!response.ok) {
+      throw new OctomilError(
+        "INFERENCE_FAILED",
+        `Streaming inference failed: HTTP ${response.status}`
+      );
+    }
+    if (!response.body) {
+      throw new OctomilError(
+        "INFERENCE_FAILED",
+        "Server did not return a streaming body."
+      );
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const data = line.slice(6).trim();
+          if (data === "[DONE]") break;
+          let parsed;
+          try {
+            parsed = JSON.parse(data);
+          } catch {
+            continue;
+          }
+          chunkCount++;
+          totalBytes += data.length;
+          if (ttfc === null) {
+            ttfc = performance.now() - startTime;
+            this.onTelemetry?.({
+              type: "streaming_chunk",
+              model: modelId,
+              durationMs: ttfc,
+              metadata: { chunkIndex: 0, ttfc: true },
+              timestamp: Date.now()
+            });
+          }
+          yield parsed;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    const totalMs = performance.now() - startTime;
+    this.onTelemetry?.({
+      type: "streaming_complete",
+      model: modelId,
+      durationMs: totalMs,
+      metadata: { chunkCount, totalBytes, ttfcMs: ttfc },
+      timestamp: Date.now()
+    });
+    return {
+      totalChunks: chunkCount,
+      totalBytes,
+      durationMs: totalMs,
+      ttfcMs: ttfc ?? totalMs
+    };
+  }
+  combineSignals(...signals) {
+    const controller = new AbortController();
+    for (const signal of signals) {
+      if (signal.aborted) {
+        controller.abort(signal.reason);
+        return controller.signal;
+      }
+      signal.addEventListener("abort", () => controller.abort(signal.reason), {
+        once: true
+      });
+    }
+    return controller.signal;
+  }
+};
+
+// src/octomil.ts
+var Octomil = class {
+  options;
+  cache;
+  loader;
+  engine;
+  telemetry = null;
+  loaded = false;
+  disposed = false;
+  constructor(options) {
+    this.options = {
+      telemetry: false,
+      cacheStrategy: "cache-api",
+      ...options
+    };
+    this.cache = createModelCache(this.options.cacheStrategy);
+    this.loader = new ModelLoader(this.options, this.cache);
+    this.engine = new InferenceEngine();
+    if (this.options.telemetry) {
+      this.telemetry = new TelemetryReporter({
+        url: this.options.telemetryUrl,
+        apiKey: this.options.apiKey
+      });
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  /**
+   * Download (or load from cache) the ONNX model and create the
+   * inference session.  Must be called before `predict()` or `chat()`.
+   */
+  async load() {
+    this.ensureNotDisposed();
+    const start = performance.now();
+    const wasCached = await this.loader.isCached();
+    const modelData = await this.loader.load();
+    await this.engine.createSession(modelData, this.options.backend);
+    this.loaded = true;
+    const durationMs = performance.now() - start;
+    this.trackEvent({
+      type: "model_load",
+      model: this.options.model,
+      durationMs,
+      metadata: {
+        backend: this.engine.activeBackend,
+        cached: wasCached,
+        sizeBytes: modelData.byteLength
+      },
+      timestamp: Date.now()
+    });
+    if (wasCached) {
+      this.trackEvent({
+        type: "cache_hit",
+        model: this.options.model,
+        timestamp: Date.now()
+      });
+    } else {
+      this.trackEvent({
+        type: "cache_miss",
+        model: this.options.model,
+        timestamp: Date.now()
+      });
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Inference
+  // -----------------------------------------------------------------------
+  /**
+   * Run a single inference pass.
+   *
+   * Accepts either raw named tensors or convenience payloads
+   * (`{ text }`, `{ image }`, `{ raw, dims }`).
+   */
+  async predict(input) {
+    this.ensureReady();
+    const tensors = this.prepareTensors(input);
+    const result = await this.engine.run(tensors);
+    this.trackEvent({
+      type: "inference",
+      model: this.options.model,
+      durationMs: result.latencyMs,
+      metadata: { backend: this.engine.activeBackend },
+      timestamp: Date.now()
+    });
+    return result;
+  }
+  /**
+   * Run inference on multiple inputs sequentially.
+   * ONNX Runtime Web doesn't handle concurrent sessions well,
+   * so we process one at a time.
+   */
+  async predictBatch(inputs) {
+    this.ensureReady();
+    const start = performance.now();
+    const results = [];
+    for (const input of inputs) {
+      const tensors = this.prepareTensors(input);
+      const result = await this.engine.run(tensors);
+      results.push(result);
+    }
+    const totalMs = performance.now() - start;
+    this.trackEvent({
+      type: "inference",
+      model: this.options.model,
+      durationMs: totalMs,
+      metadata: {
+        backend: this.engine.activeBackend,
+        batchSize: inputs.length
+      },
+      timestamp: Date.now()
+    });
+    return results;
+  }
+  /**
+   * OpenAI-compatible chat completion.
+   * Requires a server with streaming endpoint. Uses StreamingInferenceEngine
+   * under the hood to collect the full response.
+   */
+  async chat(messages, options = {}) {
+    this.ensureReady();
+    if (!this.options.serverUrl) {
+      throw new OctomilError(
+        "INFERENCE_FAILED",
+        "chat() requires serverUrl to be configured."
+      );
+    }
+    const streaming = new StreamingInferenceEngine({
+      serverUrl: this.options.serverUrl,
+      apiKey: this.options.apiKey,
+      onTelemetry: (e) => this.trackEvent(e)
+    });
+    const start = performance.now();
+    let content = "";
+    const generator = streaming.stream(this.options.model, {
+      messages,
+      temperature: options.temperature,
+      max_tokens: options.maxTokens,
+      top_p: options.topP
+    }, { modality: "text", signal: options.signal });
+    for await (const chunk of generator) {
+      if (typeof chunk.data === "string") {
+        content += chunk.data;
+      }
+    }
+    return {
+      message: { role: "assistant", content },
+      latencyMs: performance.now() - start
+    };
+  }
+  /**
+   * Streaming chat — yields chunks as they arrive.
+   */
+  async *chatStream(messages, options = {}) {
+    this.ensureReady();
+    if (!this.options.serverUrl) {
+      throw new OctomilError(
+        "INFERENCE_FAILED",
+        "chatStream() requires serverUrl to be configured."
+      );
+    }
+    const streaming = new StreamingInferenceEngine({
+      serverUrl: this.options.serverUrl,
+      apiKey: this.options.apiKey,
+      onTelemetry: (e) => this.trackEvent(e)
+    });
+    const generator = streaming.stream(this.options.model, {
+      messages,
+      temperature: options.temperature,
+      max_tokens: options.maxTokens,
+      top_p: options.topP
+    }, { modality: "text", signal: options.signal });
+    for await (const chunk of generator) {
+      yield {
+        index: chunk.index,
+        content: typeof chunk.data === "string" ? chunk.data : JSON.stringify(chunk.data),
+        done: chunk.done,
+        role: "assistant"
+      };
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Cache
+  // -----------------------------------------------------------------------
+  /** Check whether the model binary is currently cached locally. */
+  async isCached() {
+    this.ensureNotDisposed();
+    return this.loader.isCached();
+  }
+  /** Remove the cached model binary. */
+  async clearCache() {
+    this.ensureNotDisposed();
+    return this.loader.clearCache();
+  }
+  /** Get cache metadata for the model. */
+  async cacheInfo() {
+    this.ensureNotDisposed();
+    return this.loader.getCacheInfo();
+  }
+  // -----------------------------------------------------------------------
+  // Introspection
+  // -----------------------------------------------------------------------
+  /** The inference backend currently in use (after `load()`). */
+  get activeBackend() {
+    return this.engine.activeBackend;
+  }
+  /** Input tensor names defined by the loaded model. */
+  get inputNames() {
+    this.ensureReady();
+    return this.engine.inputNames;
+  }
+  /** Output tensor names defined by the loaded model. */
+  get outputNames() {
+    this.ensureReady();
+    return this.engine.outputNames;
+  }
+  /** Whether `load()` has been called successfully. */
+  get isLoaded() {
+    return this.loaded;
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+  /** Release all resources (WASM memory, WebGPU device, telemetry). */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.loaded = false;
+    this.engine.dispose();
+    this.telemetry?.dispose();
+    this.telemetry = null;
+  }
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+  ensureNotDisposed() {
+    if (this.disposed) {
+      throw new OctomilError(
+        "SESSION_DISPOSED",
+        "This Octomil instance has been disposed. Create a new one."
+      );
+    }
+  }
+  ensureReady() {
+    this.ensureNotDisposed();
+    if (!this.loaded) {
+      throw new OctomilError(
+        "NOT_LOADED",
+        "Model not loaded. Call load() before predict() or chat()."
+      );
+    }
+  }
+  /**
+   * Normalise the various `PredictInput` shapes into a flat
+   * `NamedTensors` map suitable for the inference engine.
+   */
+  prepareTensors(input) {
+    if (this.isNamedTensors(input)) {
+      return input;
+    }
+    if ("raw" in input && "dims" in input) {
+      const name = this.engine.inputNames[0];
+      if (!name) {
+        throw new OctomilError(
+          "INVALID_INPUT",
+          "Model has no input tensors defined."
+        );
+      }
+      return { [name]: { data: input.raw, dims: input.dims } };
+    }
+    if ("text" in input) {
+      const name = this.engine.inputNames[0];
+      if (!name) {
+        throw new OctomilError(
+          "INVALID_INPUT",
+          "Model has no input tensors defined."
+        );
+      }
+      const codes = new Int32Array(
+        Array.from(input.text).map((ch) => ch.codePointAt(0) ?? 0)
+      );
+      return { [name]: { data: codes, dims: [1, codes.length] } };
+    }
+    if ("image" in input) {
+      return this.imageToTensors(input.image);
+    }
+    throw new OctomilError(
+      "INVALID_INPUT",
+      "Unrecognised PredictInput format. Provide named tensors, { text }, { image }, or { raw, dims }."
+    );
+  }
+  /** Type guard for NamedTensors. */
+  isNamedTensors(input) {
+    if ("text" in input || "image" in input || "raw" in input) return false;
+    const firstValue = Object.values(input)[0];
+    return firstValue !== void 0 && typeof firstValue === "object" && "data" in firstValue && "dims" in firstValue;
+  }
+  /**
+   * Convert an image source to a Float32Array in NCHW format
+   * (batch=1, channels=3, H, W) normalised to [0, 1].
+   */
+  imageToTensors(source) {
+    let imageData;
+    if (source instanceof ImageData) {
+      imageData = source;
+    } else {
+      const canvas = source instanceof HTMLCanvasElement ? source : (() => {
+        const c = document.createElement("canvas");
+        c.width = source.naturalWidth || source.width;
+        c.height = source.naturalHeight || source.height;
+        const ctx2 = c.getContext("2d");
+        ctx2.drawImage(source, 0, 0);
+        return c;
+      })();
+      const ctx = canvas.getContext("2d");
+      if (!ctx) {
+        throw new OctomilError(
+          "INVALID_INPUT",
+          "Could not get 2D context from canvas."
+        );
+      }
+      imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    }
+    const { width, height, data: rgba } = imageData;
+    const pixels = width * height;
+    const float = new Float32Array(3 * pixels);
+    for (let i = 0; i < pixels; i++) {
+      float[i] = rgba[i * 4] / 255;
+      float[pixels + i] = rgba[i * 4 + 1] / 255;
+      float[2 * pixels + i] = rgba[i * 4 + 2] / 255;
+    }
+    const name = this.engine.inputNames[0];
+    if (!name) {
+      throw new OctomilError(
+        "INVALID_INPUT",
+        "Model has no input tensors defined."
+      );
+    }
+    return {
+      [name]: {
+        data: float,
+        dims: [1, 3, height, width]
+      }
+    };
+  }
+  trackEvent(event) {
+    this.telemetry?.track(event);
+  }
+};
+
+// src/device-auth.ts
+var REFRESH_BUFFER_MS = 3e4;
+var DeviceAuthManager = class {
+  serverUrl;
+  apiKey;
+  token = null;
+  deviceId = null;
+  refreshTimer = null;
+  disposed = false;
+  constructor(config) {
+    this.serverUrl = config.serverUrl;
+    this.apiKey = config.apiKey;
+  }
+  // -----------------------------------------------------------------------
+  // Public
+  // -----------------------------------------------------------------------
+  /** Register this device and obtain an initial auth token. */
+  async bootstrap(orgId) {
+    this.ensureNotDisposed();
+    this.deviceId = await this.generateDeviceId();
+    const deviceInfo = this.collectDeviceInfo();
+    const response = await this.request("/api/v1/devices/register", {
+      method: "POST",
+      body: JSON.stringify({
+        org_id: orgId,
+        device_id: this.deviceId,
+        platform: "browser",
+        info: deviceInfo
+      })
+    });
+    if (!response.ok) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Device registration failed: HTTP ${response.status}`
+      );
+    }
+    const data = await response.json();
+    this.token = {
+      accessToken: data.token,
+      refreshToken: data.refresh_token,
+      expiresAt: new Date(data.expires_at).getTime()
+    };
+    this.scheduleRefresh();
+  }
+  /** Get a valid access token, refreshing if needed. */
+  async getToken() {
+    this.ensureNotDisposed();
+    if (!this.token) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        "Not authenticated. Call bootstrap() first."
+      );
+    }
+    if (this.isTokenExpiringSoon()) {
+      await this.refreshToken();
+    }
+    return this.token.accessToken;
+  }
+  /** Refresh the current token. */
+  async refreshToken() {
+    this.ensureNotDisposed();
+    if (!this.token) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        "No token to refresh. Call bootstrap() first."
+      );
+    }
+    const response = await this.request("/api/v1/auth/refresh", {
+      method: "POST",
+      body: JSON.stringify({
+        refresh_token: this.token.refreshToken,
+        device_id: this.deviceId
+      })
+    });
+    if (!response.ok) {
+      this.token = null;
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Token refresh failed: HTTP ${response.status}`
+      );
+    }
+    const data = await response.json();
+    this.token = {
+      accessToken: data.token,
+      refreshToken: data.refresh_token,
+      expiresAt: new Date(data.expires_at).getTime()
+    };
+    this.scheduleRefresh();
+  }
+  /** Revoke the current token and clear local state. */
+  async revokeToken() {
+    this.ensureNotDisposed();
+    if (!this.token) return;
+    try {
+      await this.request("/api/v1/auth/revoke", {
+        method: "POST",
+        body: JSON.stringify({
+          token: this.token.accessToken,
+          device_id: this.deviceId
+        })
+      });
+    } finally {
+      this.clearState();
+    }
+  }
+  /** Whether we currently hold a valid token. */
+  get isAuthenticated() {
+    return this.token !== null && !this.isTokenExpired();
+  }
+  /** Current device identifier. */
+  get currentDeviceId() {
+    return this.deviceId;
+  }
+  /** Release timers. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.clearRefreshTimer();
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  async request(path, init) {
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    return fetch(`${this.serverUrl}${path}`, {
+      ...init,
+      headers: { ...headers, ...init.headers }
+    });
+  }
+  isTokenExpired() {
+    if (!this.token) return true;
+    return Date.now() >= this.token.expiresAt;
+  }
+  isTokenExpiringSoon() {
+    if (!this.token) return true;
+    return Date.now() >= this.token.expiresAt - REFRESH_BUFFER_MS;
+  }
+  scheduleRefresh() {
+    this.clearRefreshTimer();
+    if (!this.token) return;
+    const delay = Math.max(0, this.token.expiresAt - Date.now() - REFRESH_BUFFER_MS);
+    this.refreshTimer = setTimeout(() => {
+      void this.refreshToken().catch(() => {
+      });
+    }, delay);
+  }
+  clearRefreshTimer() {
+    if (this.refreshTimer !== null) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+  clearState() {
+    this.token = null;
+    this.clearRefreshTimer();
+  }
+  /** Generate a stable device ID by hashing browser fingerprint data. */
+  async generateDeviceId() {
+    const raw = [
+      typeof navigator !== "undefined" ? navigator.userAgent : "unknown",
+      typeof screen !== "undefined" ? `${screen.width}x${screen.height}` : "0x0",
+      typeof Intl !== "undefined" ? Intl.DateTimeFormat().resolvedOptions().timeZone : "UTC",
+      typeof navigator !== "undefined" ? navigator.language : "en"
+    ].join("|");
+    const data = new TextEncoder().encode(raw);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+    const hashArray = new Uint8Array(hashBuffer);
+    return Array.from(hashArray).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  collectDeviceInfo() {
+    return {
+      userAgent: typeof navigator !== "undefined" ? navigator.userAgent : "unknown",
+      language: typeof navigator !== "undefined" ? navigator.language : "en",
+      screenWidth: typeof screen !== "undefined" ? screen.width : 0,
+      screenHeight: typeof screen !== "undefined" ? screen.height : 0,
+      timezone: typeof Intl !== "undefined" ? Intl.DateTimeFormat().resolvedOptions().timeZone : "UTC",
+      webgpu: typeof navigator !== "undefined" && "gpu" in navigator
+    };
+  }
+  ensureNotDisposed() {
+    if (this.disposed) {
+      throw new OctomilError(
+        "SESSION_DISPOSED",
+        "DeviceAuthManager has been disposed."
+      );
+    }
+  }
+};
+
+// src/integrity.ts
+async function computeHash(data) {
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = new Uint8Array(hashBuffer);
+  return Array.from(hashArray).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function verifyModelIntegrity(data, expectedHash) {
+  const actual = await computeHash(data);
+  return actual === expectedHash.toLowerCase();
+}
+async function assertModelIntegrity(data, expectedHash) {
+  const match = await verifyModelIntegrity(data, expectedHash);
+  if (!match) {
+    throw new OctomilError(
+      "MODEL_LOAD_FAILED",
+      "Model integrity check failed: SHA-256 hash mismatch. The downloaded model may be corrupted or tampered with."
+    );
+  }
+}
+
+// src/federated.ts
+var WeightExtractor = class {
+  /**
+   * Compute element-wise delta between two weight maps.
+   * `delta = after - before`
+   */
+  static computeDelta(before, after) {
+    const delta = {};
+    for (const key of Object.keys(before)) {
+      const b = before[key];
+      const a = after[key];
+      if (!b || !a || b.length !== a.length) {
+        throw new OctomilError(
+          "INVALID_INPUT",
+          `Weight dimension mismatch for "${key}".`
+        );
+      }
+      const d = new Float32Array(b.length);
+      for (let i = 0; i < b.length; i++) {
+        d[i] = a[i] - b[i];
+      }
+      delta[key] = d;
+    }
+    return delta;
+  }
+  /** Apply a delta to weights: `result = weights + delta`. */
+  static applyDelta(weights, delta) {
+    const result = {};
+    for (const key of Object.keys(weights)) {
+      const w = weights[key];
+      const d = delta[key];
+      if (!w) continue;
+      if (!d || w.length !== d.length) {
+        result[key] = new Float32Array(w);
+        continue;
+      }
+      const r = new Float32Array(w.length);
+      for (let i = 0; i < w.length; i++) {
+        r[i] = w[i] + d[i];
+      }
+      result[key] = r;
+    }
+    return result;
+  }
+  /** Compute L2 norm of a weight map (flattened). */
+  static l2Norm(weights) {
+    let sumSq = 0;
+    for (const arr of Object.values(weights)) {
+      if (!arr) continue;
+      for (let i = 0; i < arr.length; i++) {
+        sumSq += arr[i] * arr[i];
+      }
+    }
+    return Math.sqrt(sumSq);
+  }
+};
+var FederatedClient = class {
+  serverUrl;
+  apiKey;
+  deviceId;
+  onTelemetry;
+  constructor(options) {
+    this.serverUrl = options.serverUrl;
+    this.apiKey = options.apiKey;
+    this.deviceId = options.deviceId;
+    this.onTelemetry = options.onTelemetry;
+  }
+  /** Fetch the current training round from the server. */
+  async getTrainingRound(federationId) {
+    const response = await this.request(
+      `/api/v1/federations/${encodeURIComponent(federationId)}/rounds/current`
+    );
+    if (!response.ok) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Failed to fetch training round: HTTP ${response.status}`
+      );
+    }
+    return await response.json();
+  }
+  /** Join a training round. */
+  async joinRound(federationId, roundId) {
+    const response = await this.request(
+      `/api/v1/federations/${encodeURIComponent(federationId)}/rounds/${encodeURIComponent(roundId)}/join`,
+      {
+        method: "POST",
+        body: JSON.stringify({ device_id: this.deviceId })
+      }
+    );
+    if (!response.ok) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Failed to join round: HTTP ${response.status}`
+      );
+    }
+  }
+  /**
+   * Run local training using a user-provided step function.
+   *
+   * Browser ONNX Runtime Web does not support training natively, so the
+   * caller provides `onTrainStep` which receives the current weights and
+   * a batch of data, and returns updated weights.
+   */
+  async train(initialWeights, config) {
+    const start = performance.now();
+    let weights = this.cloneWeights(initialWeights);
+    for (let epoch = 0; epoch < config.epochs; epoch++) {
+      const stepResult = await config.onTrainStep(weights, {
+        epoch,
+        batchSize: config.batchSize,
+        learningRate: config.learningRate
+      });
+      weights = stepResult.weights;
+    }
+    const delta = WeightExtractor.computeDelta(initialWeights, weights);
+    const durationMs = performance.now() - start;
+    this.onTelemetry?.({
+      type: "training_complete",
+      model: config.modelId ?? "unknown",
+      durationMs,
+      metadata: {
+        epochs: config.epochs,
+        deltaNorm: WeightExtractor.l2Norm(delta)
+      },
+      timestamp: Date.now()
+    });
+    return { finalWeights: weights, delta };
+  }
+  /** Submit a weight update to the aggregation server. */
+  async submitUpdate(federationId, roundId, delta, metrics) {
+    const serialized = {};
+    for (const [key, arr] of Object.entries(delta)) {
+      if (!arr) continue;
+      serialized[key] = {
+        data: Array.from(arr),
+        shape: [arr.length]
+      };
+    }
+    const response = await this.request(
+      `/api/v1/federations/${encodeURIComponent(federationId)}/rounds/${encodeURIComponent(roundId)}/submit`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          device_id: this.deviceId,
+          delta: serialized,
+          metrics
+        })
+      }
+    );
+    if (!response.ok) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Failed to submit update: HTTP ${response.status}`
+      );
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  async request(path, init) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    return fetch(`${this.serverUrl}${path}`, {
+      ...init,
+      headers: { ...headers, ...init?.headers }
+    });
+  }
+  cloneWeights(weights) {
+    const cloned = {};
+    for (const [key, arr] of Object.entries(weights)) {
+      if (arr) cloned[key] = new Float32Array(arr);
+    }
+    return cloned;
+  }
+};
+
+// src/secure-aggregation.ts
+var SecureAggregation = class {
+  keyPair = null;
+  /** Generate an ECDH key pair for this round. */
+  async generateKeyPair() {
+    this.keyPair = await crypto.subtle.generateKey(
+      { name: "ECDH", namedCurve: "P-256" },
+      true,
+      ["deriveBits"]
+    );
+    const publicKey = await crypto.subtle.exportKey(
+      "jwk",
+      this.keyPair.publicKey
+    );
+    return { publicKey };
+  }
+  /** Derive a shared secret with a peer using ECDH. */
+  async deriveSharedSecret(peerPublicKeyJwk) {
+    if (!this.keyPair) {
+      throw new Error("Call generateKeyPair() first.");
+    }
+    const peerKey = await crypto.subtle.importKey(
+      "jwk",
+      peerPublicKeyJwk,
+      { name: "ECDH", namedCurve: "P-256" },
+      false,
+      []
+    );
+    return crypto.subtle.deriveBits(
+      { name: "ECDH", public: peerKey },
+      this.keyPair.privateKey,
+      256
+    );
+  }
+  /**
+   * Generate a deterministic PRG mask from a shared secret.
+   * Uses the secret as a seed to produce `length` float values.
+   */
+  async createMask(secret, length) {
+    const keyMaterial = await crypto.subtle.importKey(
+      "raw",
+      secret,
+      "HKDF",
+      false,
+      ["deriveBits"]
+    );
+    const bitsNeeded = length * 4 * 8;
+    const bits = await crypto.subtle.deriveBits(
+      {
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: new Uint8Array(32),
+        info: new TextEncoder().encode("octomil-secagg-mask")
+      },
+      keyMaterial,
+      Math.min(bitsNeeded, 8160)
+      // deriveBits max
+    );
+    const mask = new Float32Array(length);
+    const source = new Float32Array(bits);
+    for (let i = 0; i < length; i++) {
+      mask[i] = source[i % source.length];
+    }
+    return mask;
+  }
+  /** Add masks to a weight update: masked = delta + sum(masks). */
+  maskUpdate(delta, masks) {
+    const masked = {};
+    for (const [key, arr] of Object.entries(delta)) {
+      if (!arr) continue;
+      const result = new Float32Array(arr);
+      const mask = masks.get(key);
+      if (mask) {
+        for (let i = 0; i < result.length; i++) {
+          result[i] = result[i] + (mask[i] ?? 0);
+        }
+      }
+      masked[key] = result;
+    }
+    return masked;
+  }
+  /** Remove masks of dropped peers from the aggregated sum. */
+  unmask(maskedSum, droppedMasks) {
+    const unmasked = {};
+    for (const [key, arr] of Object.entries(maskedSum)) {
+      if (!arr) continue;
+      const result = new Float32Array(arr);
+      const mask = droppedMasks.get(key);
+      if (mask) {
+        for (let i = 0; i < result.length; i++) {
+          result[i] = result[i] - (mask[i] ?? 0);
+        }
+      }
+      unmasked[key] = result;
+    }
+    return unmasked;
+  }
+};
+var PRIME = 2147483647;
+function modPow(base, exp, mod) {
+  let result = 1;
+  base = base % mod;
+  while (exp > 0) {
+    if (exp % 2 === 1) {
+      result = Number(BigInt(result) * BigInt(base) % BigInt(mod));
+    }
+    exp = Math.floor(exp / 2);
+    base = Number(BigInt(base) * BigInt(base) % BigInt(mod));
+  }
+  return result;
+}
+function modInverse(a, mod) {
+  return modPow(a, mod - 2, mod);
+}
+function shamirSplit(secret, threshold, numShares) {
+  const coeffs = [secret % PRIME];
+  for (let i = 1; i < threshold; i++) {
+    const randomBytes = new Uint32Array(1);
+    crypto.getRandomValues(randomBytes);
+    coeffs.push(randomBytes[0] % PRIME);
+  }
+  const shares = [];
+  for (let x = 1; x <= numShares; x++) {
+    let y = 0;
+    for (let i = 0; i < coeffs.length; i++) {
+      y = Number(
+        (BigInt(y) + BigInt(coeffs[i]) * BigInt(modPow(x, i, PRIME))) % BigInt(PRIME)
+      );
+    }
+    shares.push({ x, y });
+  }
+  return shares;
+}
+function shamirReconstruct(shares) {
+  let secret = 0;
+  const n = shares.length;
+  for (let i = 0; i < n; i++) {
+    let num = 1;
+    let den = 1;
+    for (let j = 0; j < n; j++) {
+      if (i === j) continue;
+      num = Number(
+        BigInt(num) * BigInt(PRIME - shares[j].x) % BigInt(PRIME)
+      );
+      den = Number(
+        BigInt(den) * BigInt((shares[i].x - shares[j].x + PRIME) % PRIME) % BigInt(PRIME)
+      );
+    }
+    const lagrange = Number(
+      BigInt(num) * BigInt(modInverse(den, PRIME)) % BigInt(PRIME)
+    );
+    secret = Number(
+      (BigInt(secret) + BigInt(shares[i].y) * BigInt(lagrange)) % BigInt(PRIME)
+    );
+  }
+  return secret;
+}
+var SecAggPlus = class extends SecureAggregation {
+  threshold;
+  constructor(threshold) {
+    super();
+    this.threshold = threshold;
+  }
+  /**
+   * Split a shared secret into Shamir shares so that any `threshold`
+   * surviving peers can reconstruct the mask of a dropped peer.
+   */
+  splitSecret(secret, numPeers) {
+    return shamirSplit(secret, this.threshold, numPeers);
+  }
+  /** Reconstruct a dropped peer's secret from collected shares. */
+  reconstructSecret(shares) {
+    if (shares.length < this.threshold) {
+      throw new Error(
+        `Need at least ${this.threshold} shares, got ${shares.length}.`
+      );
+    }
+    return shamirReconstruct(shares.slice(0, this.threshold));
+  }
+};
+
+// src/privacy.ts
+function clipGradients(delta, maxNorm) {
+  let sumSq = 0;
+  for (const arr of Object.values(delta)) {
+    if (!arr) continue;
+    for (let i = 0; i < arr.length; i++) {
+      sumSq += arr[i] * arr[i];
+    }
+  }
+  const norm = Math.sqrt(sumSq);
+  if (norm <= maxNorm) {
+    return delta;
+  }
+  const scale = maxNorm / norm;
+  const clipped = {};
+  for (const [key, arr] of Object.entries(delta)) {
+    if (!arr) continue;
+    const c = new Float32Array(arr.length);
+    for (let i = 0; i < arr.length; i++) {
+      c[i] = arr[i] * scale;
+    }
+    clipped[key] = c;
+  }
+  return clipped;
+}
+function addGaussianNoise(delta, epsilon, sensitivity, deltaDP) {
+  const sigma = sensitivity * Math.sqrt(2 * Math.log(1.25 / deltaDP)) / epsilon;
+  const noisy = {};
+  for (const [key, arr] of Object.entries(delta)) {
+    if (!arr) continue;
+    const n = new Float32Array(arr.length);
+    for (let i = 0; i < arr.length; i++) {
+      n[i] = arr[i] + gaussianRandom() * sigma;
+    }
+    noisy[key] = n;
+  }
+  return noisy;
+}
+function gaussianRandom() {
+  let u1;
+  let u2;
+  do {
+    u1 = Math.random();
+    u2 = Math.random();
+  } while (u1 === 0);
+  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+function quantize(delta, bits = 8) {
+  const maxVal = bits === 8 ? 127 : 32767;
+  const result = {};
+  for (const [key, arr] of Object.entries(delta)) {
+    if (!arr) continue;
+    let absMax = 0;
+    for (let i = 0; i < arr.length; i++) {
+      const abs = Math.abs(arr[i]);
+      if (abs > absMax) absMax = abs;
+    }
+    const scale = absMax > 0 ? absMax / maxVal : 1;
+    const quantized = bits === 8 ? new Int8Array(arr.length) : new Int16Array(arr.length);
+    for (let i = 0; i < arr.length; i++) {
+      quantized[i] = Math.round(arr[i] / scale);
+    }
+    result[key] = { data: quantized, scale, zeroPoint: 0 };
+  }
+  return result;
+}
+function dequantize(quantized) {
+  const result = {};
+  for (const [key, entry] of Object.entries(quantized)) {
+    if (!entry) continue;
+    const arr = new Float32Array(entry.data.length);
+    for (let i = 0; i < entry.data.length; i++) {
+      arr[i] = (entry.data[i] - entry.zeroPoint) * entry.scale;
+    }
+    result[key] = arr;
+  }
+  return result;
+}
+
+// src/rollouts.ts
+var RolloutsManager = class {
+  serverUrl;
+  apiKey;
+  cacheTtlMs;
+  onTelemetry;
+  configCache = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.serverUrl = options.serverUrl;
+    this.apiKey = options.apiKey;
+    this.cacheTtlMs = options.cacheTtlMs ?? 5 * 60 * 1e3;
+    this.onTelemetry = options.onTelemetry;
+  }
+  /**
+   * Resolve which version a device should use.
+   *
+   * Logic:
+   *  1. If a canary version exists, check if device is in canary group.
+   *  2. Otherwise return the active version.
+   */
+  async resolveVersion(modelId, deviceId) {
+    const config = await this.getRolloutConfig(modelId);
+    const canary = config.versions.find((v) => v.status === "canary");
+    if (canary && this.isInCanaryGroup(modelId, deviceId, canary.percentage)) {
+      return canary.version;
+    }
+    const active = config.versions.find((v) => v.status === "active");
+    if (active) return active.version;
+    throw new OctomilError(
+      "MODEL_NOT_FOUND",
+      `No active version found for model "${modelId}".`
+    );
+  }
+  /** Fetch rollout configuration, with caching. */
+  async getRolloutConfig(modelId) {
+    const cached = this.configCache.get(modelId);
+    if (cached && Date.now() - cached.fetchedAt < this.cacheTtlMs) {
+      return cached.config;
+    }
+    const url = `${this.serverUrl}/api/v1/models/${encodeURIComponent(modelId)}/rollout`;
+    const headers = { Accept: "application/json" };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Failed to fetch rollout config: HTTP ${response.status}`
+      );
+    }
+    const config = await response.json();
+    this.configCache.set(modelId, { config, fetchedAt: Date.now() });
+    return config;
+  }
+  /**
+   * Deterministic check: is this device in the canary group?
+   * Uses a simple hash of (deviceId + modelId) to assign a 0-99 bucket.
+   */
+  isInCanaryGroup(modelId, deviceId, canaryPercentage) {
+    const bucket = deterministicBucket(deviceId + modelId);
+    return bucket < canaryPercentage;
+  }
+  /** Get all available versions for a model. */
+  async getAvailableVersions(modelId) {
+    const config = await this.getRolloutConfig(modelId);
+    return config.versions;
+  }
+  /** Report rollout success/failure to the server. */
+  async reportRolloutStatus(modelId, version, status) {
+    const url = `${this.serverUrl}/api/v1/models/${encodeURIComponent(modelId)}/rollout/status`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ version, status })
+    });
+    this.onTelemetry?.({
+      type: "rollout_status",
+      model: modelId,
+      metadata: { version, status },
+      timestamp: Date.now()
+    });
+  }
+  /** Clear the rollout config cache. */
+  clearCache() {
+    this.configCache.clear();
+  }
+};
+function deterministicBucket(input) {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
+  }
+  return Math.abs(hash) % 100;
+}
+
+// src/experiments.ts
+var ExperimentsClient = class {
+  serverUrl;
+  apiKey;
+  cacheTtlMs;
+  onTelemetry;
+  experimentsCache = null;
+  constructor(options) {
+    this.serverUrl = options.serverUrl;
+    this.apiKey = options.apiKey;
+    this.cacheTtlMs = options.cacheTtlMs ?? 5 * 60 * 1e3;
+    this.onTelemetry = options.onTelemetry;
+  }
+  /** Fetch all active experiments (cached). */
+  async getActiveExperiments() {
+    if (this.experimentsCache && Date.now() - this.experimentsCache.fetchedAt < this.cacheTtlMs) {
+      return this.experimentsCache.experiments;
+    }
+    const url = `${this.serverUrl}/api/v1/experiments?status=active`;
+    const headers = { Accept: "application/json" };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Failed to fetch experiments: HTTP ${response.status}`
+      );
+    }
+    const data = await response.json();
+    this.experimentsCache = {
+      experiments: data.experiments,
+      fetchedAt: Date.now()
+    };
+    return data.experiments;
+  }
+  /** Get full experiment config by ID. */
+  async getExperimentConfig(experimentId) {
+    const url = `${this.serverUrl}/api/v1/experiments/${encodeURIComponent(experimentId)}`;
+    const headers = { Accept: "application/json" };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+      throw new OctomilError(
+        "NETWORK_ERROR",
+        `Failed to fetch experiment: HTTP ${response.status}`
+      );
+    }
+    return await response.json();
+  }
+  /**
+   * Deterministic variant assignment.
+   * Hash(deviceId + experimentId) → bucket → variant by cumulative traffic %.
+   */
+  getVariant(experiment, deviceId) {
+    if (experiment.variants.length === 0) return null;
+    const bucket = deterministicBucket2(deviceId + experiment.id);
+    let cumulative = 0;
+    for (const variant of experiment.variants) {
+      cumulative += variant.trafficPercentage;
+      if (bucket < cumulative) {
+        return variant;
+      }
+    }
+    return experiment.variants[experiment.variants.length - 1] ?? null;
+  }
+  /** Check if a device is enrolled in a specific experiment. */
+  isEnrolled(experiment, deviceId) {
+    return this.getVariant(experiment, deviceId) !== null;
+  }
+  /**
+   * Find which experiment (if any) affects a given model, and return
+   * the variant this device should use.
+   */
+  async resolveModelExperiment(modelId, deviceId) {
+    const experiments = await this.getActiveExperiments();
+    for (const exp of experiments) {
+      const affectsModel = exp.variants.some((v) => v.modelId === modelId);
+      if (!affectsModel) continue;
+      const variant = this.getVariant(exp, deviceId);
+      if (variant) {
+        return { experiment: exp, variant };
+      }
+    }
+    return null;
+  }
+  /** Report a metric for an experiment. */
+  async trackMetric(experimentId, metricName, value, deviceId) {
+    const url = `${this.serverUrl}/api/v1/experiments/${encodeURIComponent(experimentId)}/metrics`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        metric_name: metricName,
+        value,
+        device_id: deviceId,
+        timestamp: Date.now()
+      })
+    });
+    this.onTelemetry?.({
+      type: "experiment_metric",
+      model: experimentId,
+      metadata: { metricName, value },
+      timestamp: Date.now()
+    });
+  }
+  /** Clear the experiment cache. */
+  clearCache() {
+    this.experimentsCache = null;
+  }
+};
+function deterministicBucket2(input) {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
+  }
+  return Math.abs(hash) % 100;
+}
+//# sourceMappingURL=index.cjs.map