ag-ai 0.1.0

package/runtime/store.mjs

@@ -0,0 +1,568 @@
+import { randomUUID } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { mkdir, open, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const STORE_VERSION = 1;
+const MAX_ERROR_LENGTH = 10_000;
+const MAX_QUEUED_JOBS = 8;
+const MAX_QUEUED_REQUEST_BYTES = 128 * 1024 * 1024;
+const MAX_RETAINED_TERMINAL_JOBS = 256;
+const TERMINAL_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const TOMBSTONE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_TOMBSTONES = 1024;
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const RECORD_FILE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}\.json$/;
+const TOMBSTONE_FILE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}\.tombstone\.json$/;
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled', 'unknown']);
+const ALL_STATUSES = new Set([
+  'queued',
+  'running',
+  'cancelling',
+  'completed',
+  'failed',
+  'cancelled',
+  'unknown',
+]);
+
+class GenerationStoreError extends Error {
+  constructor(message, code = 'store_error') {
+    super(message);
+    this.name = 'GenerationStoreError';
+    this.code = code;
+  }
+}
+
+const clone = (value) => JSON.parse(JSON.stringify(value));
+
+const safeId = (value) => {
+  if (typeof value !== 'string' || !SAFE_ID.test(value)) {
+    throw new GenerationStoreError('job id is invalid', 'invalid_job');
+  }
+  return value;
+};
+
+const safeRoot = async (root) => {
+  const resolvedRoot = path.resolve(root);
+  await mkdir(resolvedRoot, { recursive: true, mode: 0o700 });
+  const canonical = await realpath(resolvedRoot);
+  if (canonical !== resolvedRoot) {
+    throw new GenerationStoreError('generation store path resolves unexpectedly', 'unsafe_store');
+  }
+  const rootStat = await stat(canonical);
+  if (!rootStat.isDirectory()) {
+    throw new GenerationStoreError('generation store path is not a directory', 'unsafe_store');
+  }
+  return canonical;
+};
+
+const safePath = (root, id, suffix) => {
+  safeId(id);
+  const name = `${id}${suffix}`;
+  const target = path.join(root, name);
+  const relative = path.relative(root, target);
+  if (relative !== name || path.isAbsolute(relative)) {
+    throw new GenerationStoreError('job record escaped its store', 'unsafe_store');
+  }
+  return target;
+};
+
+const checkHashes = (record, fileName) => {
+  if (
+    typeof record.idempotencyKeyHash !== 'string' ||
+    !/^[a-f0-9]{64}$/.test(record.idempotencyKeyHash)
+  ) {
+    throw new GenerationStoreError(`invalid idempotency hash ${fileName}`, 'corrupt_store');
+  }
+  if (typeof record.requestHash !== 'string' || !/^[a-f0-9]{64}$/.test(record.requestHash)) {
+    throw new GenerationStoreError(`invalid request hash ${fileName}`, 'corrupt_store');
+  }
+};
+
+const validateMetadata = (value, fileName, { body = true } = {}) => {
+  if (!value || typeof value !== 'object' || value.version !== STORE_VERSION) {
+    throw new GenerationStoreError(`invalid generation record ${fileName}`, 'corrupt_store');
+  }
+  const record = value;
+  safeId(record.id);
+  checkHashes(record, fileName);
+  if (!ALL_STATUSES.has(record.status)) {
+    throw new GenerationStoreError(`invalid generation status ${fileName}`, 'corrupt_store');
+  }
+  if (!Number.isInteger(record.createdAt) || !Number.isInteger(record.updatedAt)) {
+    throw new GenerationStoreError(`invalid generation timestamps ${fileName}`, 'corrupt_store');
+  }
+  if (typeof record.model !== 'string' || typeof record.reasoningEffort !== 'string') {
+    throw new GenerationStoreError(
+      `generation model metadata is missing ${fileName}`,
+      'corrupt_store',
+    );
+  }
+  if (
+    record.requestBytes !== undefined &&
+    (!Number.isInteger(record.requestBytes) || record.requestBytes < 0)
+  ) {
+    throw new GenerationStoreError(
+      `generation request size is invalid ${fileName}`,
+      'corrupt_store',
+    );
+  }
+  if (record.error !== undefined && (!record.error || typeof record.error !== 'object')) {
+    throw new GenerationStoreError(`generation error is invalid ${fileName}`, 'corrupt_store');
+  }
+  if (body && (!record.request || typeof record.request !== 'object')) {
+    throw new GenerationStoreError(`generation request missing ${fileName}`, 'corrupt_store');
+  }
+  if (body && record.result !== undefined && typeof record.result !== 'object') {
+    throw new GenerationStoreError(`generation result is invalid ${fileName}`, 'corrupt_store');
+  }
+  return record;
+};
+
+const toMetadata = (record, bodyPresent = true) => ({
+  version: STORE_VERSION,
+  id: record.id,
+  idempotencyKeyHash: record.idempotencyKeyHash,
+  requestHash: record.requestHash,
+  model: record.model,
+  reasoningEffort: record.reasoningEffort,
+  requestBytes: record.requestBytes ?? 0,
+  status: record.status,
+  createdAt: record.createdAt,
+  updatedAt: record.updatedAt,
+  ...(record.startedAt === undefined ? {} : { startedAt: record.startedAt }),
+  ...(record.completedAt === undefined ? {} : { completedAt: record.completedAt }),
+  cancelRequested: record.cancelRequested === true,
+  ...(record.error === undefined ? {} : { error: clone(record.error) }),
+  bodyPresent,
+});
+
+const publicFromRecord = (record) => {
+  const value = { id: record.id, status: record.status };
+  if (record.result !== undefined) value.result = clone(record.result);
+  if (record.error !== undefined) value.error = clone(record.error);
+  return value;
+};
+
+const terminalSort = (a, b) => a.updatedAt - b.updatedAt || a.createdAt - b.createdAt;
+
+class GenerationStore {
+  constructor(root) {
+    this.rootInput = root;
+    this.root = undefined;
+    // Keep only bounded metadata in memory. Requests and results stay on disk.
+    this.records = new Map();
+    this.idempotency = new Map();
+    this.mutation = Promise.resolve();
+    this.initialized = false;
+  }
+
+  async init() {
+    if (this.initialized) return;
+    this.root = await safeRoot(this.rootInput);
+    const entries = await readdir(this.root, { withFileTypes: true });
+    const candidates = new Map();
+    for (const entry of entries) {
+      if (!entry.isFile() || (!RECORD_FILE.test(entry.name) && !TOMBSTONE_FILE.test(entry.name))) {
+        continue;
+      }
+      const isTombstone = TOMBSTONE_FILE.test(entry.name);
+      const id = isTombstone
+        ? entry.name.slice(0, -'.tombstone.json'.length)
+        : entry.name.slice(0, -'.json'.length);
+      safeId(id);
+      const recordPath = path.join(this.root, entry.name);
+      // eslint-disable-next-line no-await-in-loop -- Read records in deterministic order.
+      const handle = await open(recordPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+      let parsed;
+      try {
+        // eslint-disable-next-line no-await-in-loop -- Preserve deterministic record validation.
+        parsed = JSON.parse(await handle.readFile('utf8'));
+      } catch {
+        throw new GenerationStoreError(
+          `could not read generation record ${entry.name}`,
+          'corrupt_store',
+        );
+      } finally {
+        // eslint-disable-next-line no-await-in-loop -- Close each record before advancing.
+        await handle.close();
+      }
+      const record = validateMetadata(parsed, entry.name, { body: !isTombstone });
+      if (record.id !== id) {
+        throw new GenerationStoreError('generation record identity mismatch', 'corrupt_store');
+      }
+      const candidate = candidates.get(id) ?? {};
+      if (isTombstone ? candidate.tombstone : candidate.body) {
+        throw new GenerationStoreError('duplicate generation record', 'corrupt_store');
+      }
+      candidate[isTombstone ? 'tombstone' : 'body'] = { record, entry: entry.name };
+      candidates.set(id, candidate);
+    }
+
+    const staleBodies = [];
+    for (const [id, candidate] of candidates) {
+      let selected;
+      let bodyPresent;
+      if (candidate.tombstone && candidate.body) {
+        const tombstone = candidate.tombstone.record;
+        const body = candidate.body.record;
+        if (
+          tombstone.idempotencyKeyHash !== body.idempotencyKeyHash ||
+          tombstone.requestHash !== body.requestHash ||
+          tombstone.model !== body.model ||
+          tombstone.reasoningEffort !== body.reasoningEffort ||
+          tombstone.status !== body.status ||
+          tombstone.updatedAt !== body.updatedAt
+        ) {
+          throw new GenerationStoreError('generation compaction records disagree', 'corrupt_store');
+        }
+        // A tombstone is written before its body is removed. Treat it as the
+        // committed state and finish the cleanup left by that crash window.
+        selected = tombstone;
+        bodyPresent = false;
+        staleBodies.push(id);
+      } else if (candidate.tombstone) {
+        selected = candidate.tombstone.record;
+        bodyPresent = false;
+      } else {
+        selected = candidate.body.record;
+        bodyPresent = true;
+      }
+      if (this.idempotency.has(selected.idempotencyKeyHash)) {
+        throw new GenerationStoreError('duplicate generation idempotency key', 'corrupt_store');
+      }
+      this.records.set(id, toMetadata(selected, bodyPresent));
+      this.idempotency.set(selected.idempotencyKeyHash, id);
+    }
+    this.initialized = true;
+    await this._mutate(async () => {
+      for (const id of staleBodies) {
+        // eslint-disable-next-line no-await-in-loop -- Finish tombstone cleanup sequentially.
+        await rm(safePath(this.root, id, '.json'), { force: true });
+      }
+      for (const metadata of this.records.values()) {
+        if (
+          metadata.bodyPresent &&
+          (metadata.status === 'running' || metadata.status === 'cancelling')
+        ) {
+          // eslint-disable-next-line no-await-in-loop -- Recover running records one at a time.
+          const record = await this._readFull(metadata.id);
+          record.status = 'unknown';
+          record.cancelRequested = false;
+          record.error = {
+            code: 'unknown_after_restart',
+            message: 'Execution outcome is unknown after bridge restart',
+          };
+          record.updatedAt = Date.now();
+          // eslint-disable-next-line no-await-in-loop -- Persist each recovery before pruning.
+          await this._persist(record);
+          this._replaceMetadata(record, true);
+        }
+      }
+      await this._prune();
+    });
+  }
+
+  async _mutate(operation) {
+    const next = this.mutation.then(operation, operation);
+    this.mutation = next.catch(() => undefined);
+    return next;
+  }
+
+  _replaceMetadata(record, bodyPresent = true) {
+    const metadata = toMetadata(record, bodyPresent);
+    this.records.set(record.id, metadata);
+    this.idempotency.set(record.idempotencyKeyHash, record.id);
+    return metadata;
+  }
+
+  async _readFull(id) {
+    const metadata = this.records.get(id);
+    if (!metadata) return undefined;
+    if (!metadata.bodyPresent) return { ...metadata };
+    const target = safePath(this.root, id, '.json');
+    const handle = await open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+      return validateMetadata(JSON.parse(await handle.readFile('utf8')), `${id}.json`, {
+        body: true,
+      });
+    } catch (error) {
+      if (error instanceof GenerationStoreError) throw error;
+      throw new GenerationStoreError(
+        `could not read generation record ${id}.json`,
+        'corrupt_store',
+      );
+    } finally {
+      await handle.close();
+    }
+  }
+
+  async _persist(record) {
+    if (!this.root) throw new GenerationStoreError('generation store is not initialized');
+    const target = safePath(this.root, record.id, '.json');
+    const temporary = path.join(this.root, `.${record.id}.${randomUUID()}.tmp`);
+    const serialized = JSON.stringify(record);
+    try {
+      await writeFile(temporary, serialized, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      await rename(temporary, target);
+    } finally {
+      await rm(temporary, { force: true }).catch(() => undefined);
+    }
+  }
+
+  async _persistTombstone(metadata) {
+    const target = safePath(this.root, metadata.id, '.tombstone.json');
+    const temporary = path.join(this.root, `.${metadata.id}.${randomUUID()}.tombstone.tmp`);
+    const tombstone = { ...metadata, bodyPresent: false };
+    try {
+      await writeFile(temporary, JSON.stringify(tombstone), {
+        encoding: 'utf8',
+        mode: 0o600,
+        flag: 'wx',
+      });
+      await rename(temporary, target);
+    } finally {
+      await rm(temporary, { force: true }).catch(() => undefined);
+    }
+  }
+
+  async _compact(metadata) {
+    if (!metadata.bodyPresent || !TERMINAL_STATUSES.has(metadata.status)) return;
+    await this._persistTombstone(metadata);
+    await rm(safePath(this.root, metadata.id, '.json'), { force: true });
+    this.records.set(metadata.id, { ...metadata, bodyPresent: false });
+  }
+
+  async _remove(metadata) {
+    await rm(
+      metadata.bodyPresent
+        ? safePath(this.root, metadata.id, '.json')
+        : safePath(this.root, metadata.id, '.tombstone.json'),
+      { force: true },
+    );
+    this.records.delete(metadata.id);
+    if (this.idempotency.get(metadata.idempotencyKeyHash) === metadata.id) {
+      this.idempotency.delete(metadata.idempotencyKeyHash);
+    }
+  }
+
+  async _prune() {
+    const now = Date.now();
+    const terminal = [...this.records.values()]
+      .filter((record) => TERMINAL_STATUSES.has(record.status))
+      .sort(terminalSort);
+    const terminalBodies = terminal.filter((record) => record.bodyPresent);
+    const compact = terminalBodies.filter(
+      (record, index) =>
+        now - record.updatedAt > TERMINAL_RETENTION_MS ||
+        index < Math.max(0, terminalBodies.length - MAX_RETAINED_TERMINAL_JOBS),
+    );
+    for (const record of compact) {
+      // eslint-disable-next-line no-await-in-loop -- Tombstones must precede body removal.
+      await this._compact(record);
+    }
+    const tombstones = [...this.records.values()]
+      .filter((record) => !record.bodyPresent)
+      .sort(terminalSort);
+    const remove = tombstones.filter(
+      (record, index) =>
+        now - record.updatedAt > TOMBSTONE_RETENTION_MS ||
+        index < Math.max(0, tombstones.length - MAX_TOMBSTONES),
+    );
+    for (const record of remove) {
+      // eslint-disable-next-line no-await-in-loop -- Remove records sequentially after compaction.
+      await this._remove(record);
+    }
+  }
+
+  async create({ idempotencyKeyHash, requestHash, request, model, reasoningEffort }) {
+    await this._ready();
+    return this._mutate(async () => {
+      const existingId = this.idempotency.get(idempotencyKeyHash);
+      if (existingId) {
+        const existing = this.records.get(existingId);
+        if (!existing) {
+          throw new GenerationStoreError('idempotency index is corrupt', 'corrupt_store');
+        }
+        if (existing.requestHash !== requestHash) {
+          throw new GenerationStoreError(
+            'idempotency key was already used for a different request',
+            'idempotency_conflict',
+          );
+        }
+        return { record: clone(existing), created: false };
+      }
+      const requestBytes = Buffer.byteLength(JSON.stringify(request));
+      const queued = [...this.records.values()].filter((record) => record.status === 'queued');
+      const queuedBytes = queued.reduce((sum, record) => sum + (record.requestBytes ?? 0), 0);
+      if (
+        queued.length >= MAX_QUEUED_JOBS ||
+        queuedBytes + requestBytes > MAX_QUEUED_REQUEST_BYTES
+      ) {
+        throw new GenerationStoreError('generation queue is full', 'queue_full');
+      }
+      const id = randomUUID();
+      const now = Date.now();
+      const record = {
+        version: STORE_VERSION,
+        id,
+        idempotencyKeyHash,
+        requestHash,
+        request: clone(request),
+        model,
+        reasoningEffort,
+        requestBytes,
+        status: 'queued',
+        createdAt: now,
+        updatedAt: now,
+        cancelRequested: false,
+      };
+      this._replaceMetadata(record, true);
+      try {
+        await this._persist(record);
+      } catch (error) {
+        this.records.delete(id);
+        this.idempotency.delete(idempotencyKeyHash);
+        throw error;
+      }
+      await this._prune();
+      return { record: clone(this.records.get(id)), created: true };
+    });
+  }
+
+  async _ready() {
+    if (!this.initialized) throw new GenerationStoreError('generation store is not initialized');
+  }
+
+  async get(id) {
+    await this._ready();
+    safeId(id);
+    const record = await this._readFull(id);
+    return record ? clone(record) : undefined;
+  }
+
+  async findByIdempotencyKeyHash(idempotencyKeyHash) {
+    await this._ready();
+    const id = this.idempotency.get(idempotencyKeyHash);
+    const record = id ? this.records.get(id) : undefined;
+    return record ? clone(record) : undefined;
+  }
+
+  async claimNext() {
+    await this._ready();
+    return this._mutate(async () => {
+      const queued = [...this.records.values()]
+        .filter((record) => record.status === 'queued' && record.bodyPresent)
+        .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id))[0];
+      if (!queued) return undefined;
+      const record = await this._readFull(queued.id);
+      record.status = 'running';
+      record.startedAt = Date.now();
+      record.updatedAt = record.startedAt;
+      await this._persist(record);
+      this._replaceMetadata(record, true);
+      return clone(record);
+    });
+  }
+
+  async complete(id, result) {
+    await this._ready();
+    return this._mutate(async () => {
+      safeId(id);
+      const metadata = this.records.get(id);
+      if (!metadata) throw new GenerationStoreError('generation job was not found', 'not_found');
+      if (TERMINAL_STATUSES.has(metadata.status)) return clone(metadata);
+      const record = await this._readFull(id);
+      record.status = 'completed';
+      record.cancelRequested = false;
+      record.result = clone(result);
+      record.error = undefined;
+      record.completedAt = Date.now();
+      record.updatedAt = record.completedAt;
+      await this._persist(record);
+      this._replaceMetadata(record, true);
+      await this._prune();
+      return clone(record);
+    });
+  }
+
+  async fail(id, message, outcome = 'failed') {
+    await this._ready();
+    return this._mutate(async () => {
+      safeId(id);
+      const metadata = this.records.get(id);
+      if (!metadata) throw new GenerationStoreError('generation job was not found', 'not_found');
+      if (TERMINAL_STATUSES.has(metadata.status)) return clone(metadata);
+      const record = await this._readFull(id);
+      const status =
+        outcome === 'cancelled' ? 'cancelled' : outcome === 'unknown' ? 'unknown' : 'failed';
+      record.status = status;
+      record.cancelRequested = false;
+      record.error = {
+        code: status === 'cancelled' ? 'cancelled' : status,
+        message: String(message ?? 'Generation failed').slice(0, MAX_ERROR_LENGTH),
+      };
+      record.completedAt = Date.now();
+      record.updatedAt = record.completedAt;
+      await this._persist(record);
+      this._replaceMetadata(record, true);
+      await this._prune();
+      return clone(record);
+    });
+  }
+
+  async cancel(id) {
+    await this._ready();
+    return this._mutate(async () => {
+      safeId(id);
+      const metadata = this.records.get(id);
+      if (!metadata) return undefined;
+      if (metadata.status === 'queued') {
+        const record = await this._readFull(id);
+        record.status = 'cancelled';
+        record.cancelRequested = false;
+        record.error = {
+          code: 'cancelled',
+          message: 'Generation was cancelled before execution',
+        };
+        record.completedAt = Date.now();
+        record.updatedAt = record.completedAt;
+        await this._persist(record);
+        this._replaceMetadata(record, true);
+      } else if (metadata.status === 'running') {
+        const record = await this._readFull(id);
+        record.status = 'cancelling';
+        record.cancelRequested = true;
+        record.updatedAt = Date.now();
+        await this._persist(record);
+        this._replaceMetadata(record, true);
+      }
+      await this._prune();
+      return clone(this.records.get(id));
+    });
+  }
+
+  async isCancellationRequested(id) {
+    await this._ready();
+    const record = this.records.get(id);
+    return Boolean(record?.cancelRequested || record?.status === 'cancelling');
+  }
+
+  publicJob(record) {
+    return record ? publicFromRecord(record) : undefined;
+  }
+
+  async close() {
+    await this.mutation;
+  }
+}
+
+export {
+  GenerationStore,
+  GenerationStoreError,
+  MAX_QUEUED_JOBS,
+  MAX_QUEUED_REQUEST_BYTES,
+  MAX_RETAINED_TERMINAL_JOBS,
+  TERMINAL_RETENTION_MS,
+  TOMBSTONE_RETENTION_MS,
+};

package/runtime/telemetry.mjs

@@ -0,0 +1,137 @@
+/* eslint-disable no-console */
+
+const ANALYTICA_EVENT_URL = 'https://analytica.click/api/site/event';
+const DEFAULT_ANALYTICA_EVENT_PREFIX = 'andreigec/ag-ai';
+const DEFAULT_ANALYTICA_PAGE_LOCATION = 'cluster://ag-ai';
+const ANALYTICA_REQUEST_TIMEOUT_MS = 5_000;
+const ANALYTICA_MAX_CONCURRENT_REQUESTS = 4;
+const ANALYTICA_MAX_QUEUED_REQUESTS = 256;
+
+const normalizeSegment = (value) =>
+  String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'unknown';
+
+const analyticaEventName = (prefix, ...segments) =>
+  [prefix, ...segments.map(normalizeSegment)].join('/');
+
+class AnalyticaEvents {
+  constructor({
+    token,
+    source,
+    eventUrl = ANALYTICA_EVENT_URL,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = ANALYTICA_REQUEST_TIMEOUT_MS,
+    maxConcurrent = ANALYTICA_MAX_CONCURRENT_REQUESTS,
+    maxQueued = ANALYTICA_MAX_QUEUED_REQUESTS,
+    eventPrefix = process.env.AG_AI_ANALYTICA_EVENT_PREFIX ?? DEFAULT_ANALYTICA_EVENT_PREFIX,
+    pageLocation = process.env.AG_AI_ANALYTICA_PAGE_LOCATION ?? DEFAULT_ANALYTICA_PAGE_LOCATION,
+  } = {}) {
+    if (typeof token !== 'string' || token.trim().length === 0) {
+      throw new Error('Analytica token is required');
+    }
+    if (typeof source !== 'string' || source.trim().length === 0) {
+      throw new Error('Analytica source is required');
+    }
+    if (typeof eventPrefix !== 'string' || eventPrefix.trim().length === 0) {
+      throw new Error('Analytica event prefix is required');
+    }
+    if (typeof fetchImpl !== 'function')
+      throw new Error('Analytica fetch implementation is required');
+    if (!Number.isInteger(maxConcurrent) || maxConcurrent < 1)
+      throw new Error('Analytica concurrency must be a positive integer');
+    if (!Number.isInteger(maxQueued) || maxQueued < 0)
+      throw new Error('Analytica queue limit must be a non-negative integer');
+    this.token = token.trim();
+    this.source = source.trim().slice(0, 160);
+    this.eventUrl = new URL(eventUrl).toString();
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+    this.maxConcurrent = maxConcurrent;
+    this.maxQueued = maxQueued;
+    this.eventPrefix = eventPrefix.trim();
+    this.pageLocation = String(pageLocation).trim().slice(0, 200);
+    this.active = 0;
+    this.queue = [];
+    this.pending = new Set();
+  }
+
+  emit(...segments) {
+    const eventName = analyticaEventName(this.eventPrefix, ...segments);
+    console.log(`[analytica] ${JSON.stringify({ eventName })}`);
+    if (this.active >= this.maxConcurrent && this.queue.length >= this.maxQueued) {
+      console.error('[analytica] delivery dropped because the bounded queue is full');
+      return Promise.resolve(false);
+    }
+
+    let resolveDelivery;
+    const delivery = new Promise((resolve) => {
+      resolveDelivery = resolve;
+    });
+    this.pending.add(delivery);
+    void delivery.finally(() => this.pending.delete(delivery));
+    const queued = { eventName, resolve: resolveDelivery };
+    if (this.active < this.maxConcurrent) this.start(queued);
+    else this.queue.push(queued);
+    return delivery;
+  }
+
+  start(queued) {
+    this.active += 1;
+    void this.deliver(queued.eventName)
+      .then(queued.resolve)
+      .finally(() => {
+        this.active -= 1;
+        const next = this.queue.shift();
+        if (next) this.start(next);
+      });
+  }
+
+  async deliver(eventName) {
+    try {
+      const response = await this.fetchImpl(this.eventUrl, {
+        method: 'POST',
+        headers: {
+          authorization: '',
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+          key: this.token,
+          data: {
+            eventName,
+            browserFingerprint: this.source,
+            pageLocation: this.pageLocation,
+          },
+        }),
+        redirect: 'error',
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+      if (!response.ok) {
+        console.error(`[analytica] delivery failed with status ${response.status}`);
+        return false;
+      }
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'unknown error';
+      console.error(`[analytica] delivery failed: ${message}`);
+      return false;
+    }
+  }
+
+  async flush() {
+    await Promise.allSettled(this.pending);
+    if (this.pending.size > 0) return this.flush();
+    return undefined;
+  }
+}
+
+export {
+  ANALYTICA_EVENT_URL,
+  DEFAULT_ANALYTICA_EVENT_PREFIX,
+  DEFAULT_ANALYTICA_PAGE_LOCATION,
+  AnalyticaEvents,
+  analyticaEventName,
+};