@spooky-sync/core 0.0.1-canary.9 → 0.0.1-canary.91

package/src/modules/sync/utils.test.ts

@@ -5,8 +5,16 @@ import {
   applyRecordVersionDiff,
   createDiffFromDbOp,
   ArraySyncer,
+  resolveListRefPollInterval,
+  DEFAULT_LIST_REF_POLL_INTERVAL_MS,
+  buildListRefSelect,
+  buildSubqueryListRefSelect,
+  nextPollDelayMs,
+  listRefPollDelayMs,
+  LIST_REF_POLL_MAX_INTERVAL_MS,
+  recordVersionArraysEqual,
 } from './utils';
-import { RecordVersionArray, RecordVersionDiff } from '../../types';
+import type { RecordVersionArray, RecordVersionDiff } from '../../types';
 import { encodeRecordId } from '../../utils/index';
 
 function rid(table: string, id: string): RecordId<string> {
@@ -305,7 +313,266 @@ describe('ArraySyncer', () => {
     expect(diff!.removed).toHaveLength(3);
     // Check they come in sorted order
     const removedIds = diff!.removed.map((r) => encodeRecordId(r));
-    const sorted = [...removedIds].sort();
+    const sorted = [...removedIds].toSorted();
     expect(removedIds).toEqual(sorted);
   });
 });
+
+describe('resolveListRefPollInterval', () => {
+  it('returns the default when no option is provided', () => {
+    expect(resolveListRefPollInterval()).toBe(DEFAULT_LIST_REF_POLL_INTERVAL_MS);
+    expect(resolveListRefPollInterval(undefined)).toBe(
+      DEFAULT_LIST_REF_POLL_INTERVAL_MS
+    );
+  });
+
+  it('respects a positive override', () => {
+    expect(resolveListRefPollInterval(1000)).toBe(1000);
+    expect(resolveListRefPollInterval(5000)).toBe(5000);
+  });
+
+  it('falls back to default for zero, negative, NaN, or Infinity', () => {
+    // Accepting these would either silently disable polling or busy-loop
+    // the event loop, so they fall back to the default.
+    expect(resolveListRefPollInterval(0)).toBe(DEFAULT_LIST_REF_POLL_INTERVAL_MS);
+    expect(resolveListRefPollInterval(-500)).toBe(
+      DEFAULT_LIST_REF_POLL_INTERVAL_MS
+    );
+    expect(resolveListRefPollInterval(NaN)).toBe(
+      DEFAULT_LIST_REF_POLL_INTERVAL_MS
+    );
+    expect(resolveListRefPollInterval(Infinity)).toBe(
+      DEFAULT_LIST_REF_POLL_INTERVAL_MS
+    );
+  });
+
+  it('locks the default at 500ms so accidental tuning trips this test', () => {
+    expect(DEFAULT_LIST_REF_POLL_INTERVAL_MS).toBe(500);
+  });
+});
+
+describe('buildListRefSelect', () => {
+  it('substitutes the table name', () => {
+    expect(buildListRefSelect('_00_list_ref')).toContain('FROM _00_list_ref ');
+    expect(buildListRefSelect('_00_list_ref_user_abc')).toContain(
+      'FROM _00_list_ref_user_abc '
+    );
+  });
+
+  it('filters by the bound query id', () => {
+    expect(buildListRefSelect('_00_list_ref')).toContain('WHERE in = $in');
+  });
+
+  it('excludes subquery rows via parent IS NONE', () => {
+    // Without this predicate the poll would surface child records (the
+    // subquery-projection rows the SSP also writes into list_ref) as
+    // spurious "added" diffs against `localArray` every tick.
+    expect(buildListRefSelect('_00_list_ref')).toContain('parent IS NONE');
+  });
+
+  it('selects only `out` and `version`', () => {
+    // The diff only needs the record id and its version; pulling more
+    // fields would bloat the per-tick query traffic.
+    const sql = buildListRefSelect('_00_list_ref');
+    expect(sql.startsWith('SELECT out, version FROM ')).toBe(true);
+  });
+});
+
+describe('buildSubqueryListRefSelect', () => {
+  it('substitutes the table name', () => {
+    expect(buildSubqueryListRefSelect('_00_list_ref')).toContain('FROM _00_list_ref ');
+    expect(buildSubqueryListRefSelect('_00_list_ref_user_abc')).toContain(
+      'FROM _00_list_ref_user_abc '
+    );
+  });
+
+  it('filters by the bound query id', () => {
+    expect(buildSubqueryListRefSelect('_00_list_ref')).toContain('WHERE in = $in');
+  });
+
+  it('selects ONLY subquery child rows via parent IS NOT NONE', () => {
+    // The mirror of `buildListRefSelect`'s `parent IS NONE`: the SSP writes
+    // `.related()` child rows into list_ref tagged with `parent`/`parent_rel`;
+    // this select pulls exactly those so their bodies can be synced into the
+    // local cache (separately from the primary window) and the correlated
+    // surql re-materializes with related data on a cold reload.
+    const sql = buildSubqueryListRefSelect('_00_list_ref');
+    expect(sql).toContain('parent IS NOT NONE');
+    expect(sql).not.toContain('parent IS NONE ');
+  });
+
+  it('selects only `out` and `version`', () => {
+    const sql = buildSubqueryListRefSelect('_00_list_ref');
+    expect(sql.startsWith('SELECT out, version FROM ')).toBe(true);
+  });
+});
+
+describe('nextPollDelayMs', () => {
+  it('returns the base interval when LIVE has never delivered', () => {
+    expect(
+      nextPollDelayMs({
+        now: 10_000,
+        lastLiveEventAt: null,
+        baseIntervalMs: 500,
+      })
+    ).toBe(500);
+  });
+
+  it('returns the healthy interval when a LIVE event fired within the cooldown', () => {
+    expect(
+      nextPollDelayMs({
+        now: 10_000,
+        lastLiveEventAt: 8_000, // 2s ago, well within 5s cooldown
+        baseIntervalMs: 500,
+      })
+    ).toBe(5_000);
+  });
+
+  it('snaps back to the base interval after the cooldown elapses', () => {
+    expect(
+      nextPollDelayMs({
+        now: 20_000,
+        lastLiveEventAt: 10_000, // 10s ago, well past cooldown
+        baseIntervalMs: 500,
+      })
+    ).toBe(500);
+  });
+
+  it('treats the cooldown boundary as expired (>= cooldownMs returns base)', () => {
+    // Exactly at the boundary, the LIVE feed is considered cold so we
+    // resume the aggressive cadence. Picks the same direction as
+    // `if (sinceLive >= cooldownMs)`.
+    expect(
+      nextPollDelayMs({
+        now: 15_000,
+        lastLiveEventAt: 10_000, // exactly 5s ago
+        baseIntervalMs: 500,
+        cooldownMs: 5_000,
+      })
+    ).toBe(500);
+  });
+
+  it('clamps a clock-skew negative sinceLive to the base interval', () => {
+    // If a stale timestamp puts the LIVE event in the future, we
+    // should not interpret that as "LIVE healthy" — treat it as
+    // unknown and use the conservative aggressive cadence.
+    expect(
+      nextPollDelayMs({
+        now: 10_000,
+        lastLiveEventAt: 20_000, // future timestamp
+        baseIntervalMs: 500,
+      })
+    ).toBe(500);
+  });
+
+  it('never widens below an aggressively-configured base interval', () => {
+    // If the caller picked a faster base (e.g. 100ms) on purpose,
+    // the healthy path should not silently slow things back to 5s.
+    // The healthy interval is clamped to at least base.
+    expect(
+      nextPollDelayMs({
+        now: 10_000,
+        lastLiveEventAt: 9_500,
+        baseIntervalMs: 8_000,
+      })
+    ).toBe(8_000);
+  });
+
+  it('respects custom cooldown and healthy-interval values', () => {
+    expect(
+      nextPollDelayMs({
+        now: 10_000,
+        lastLiveEventAt: 9_500, // 0.5s ago
+        baseIntervalMs: 250,
+        cooldownMs: 1_000,
+        healthyIntervalMs: 2_000,
+      })
+    ).toBe(2_000);
+    expect(
+      nextPollDelayMs({
+        now: 10_000,
+        lastLiveEventAt: 8_500, // 1.5s ago > cooldown
+        baseIntervalMs: 250,
+        cooldownMs: 1_000,
+        healthyIntervalMs: 2_000,
+      })
+    ).toBe(250);
+  });
+});
+
+describe('listRefPollDelayMs', () => {
+  it('returns the base interval at idle streak 0 (something just happened)', () => {
+    expect(listRefPollDelayMs({ idleStreak: 0, baseIntervalMs: 500 })).toBe(500);
+    // Negative streak is defensively treated as "active" too.
+    expect(listRefPollDelayMs({ idleStreak: -3, baseIntervalMs: 500 })).toBe(500);
+  });
+
+  it('doubles per idle streak (exponential backoff)', () => {
+    expect(listRefPollDelayMs({ idleStreak: 1, baseIntervalMs: 500 })).toBe(1_000);
+    expect(listRefPollDelayMs({ idleStreak: 2, baseIntervalMs: 500 })).toBe(2_000);
+    expect(listRefPollDelayMs({ idleStreak: 3, baseIntervalMs: 500 })).toBe(4_000);
+  });
+
+  it('caps at LIST_REF_POLL_MAX_INTERVAL_MS (5s) once the doubling exceeds it', () => {
+    // streak 4 would be 8000ms uncapped → clamped to 5000.
+    expect(listRefPollDelayMs({ idleStreak: 4, baseIntervalMs: 500 })).toBe(5_000);
+    expect(listRefPollDelayMs({ idleStreak: 50, baseIntervalMs: 500 })).toBe(5_000);
+    expect(LIST_REF_POLL_MAX_INTERVAL_MS).toBe(5_000);
+  });
+
+  it('never returns below the configured base, even when base exceeds the cap', () => {
+    // An aggressively-large base must not be implicitly shrunk by the cap.
+    expect(listRefPollDelayMs({ idleStreak: 0, baseIntervalMs: 8_000 })).toBe(8_000);
+    expect(listRefPollDelayMs({ idleStreak: 5, baseIntervalMs: 8_000 })).toBe(8_000);
+  });
+
+  it('respects a custom max interval', () => {
+    expect(
+      listRefPollDelayMs({ idleStreak: 10, baseIntervalMs: 500, maxIntervalMs: 3_000 })
+    ).toBe(3_000);
+  });
+
+  it('does not overflow for a very long idle streak', () => {
+    // 2^1000 would be Infinity; the exponent clamp keeps it finite and capped.
+    expect(listRefPollDelayMs({ idleStreak: 1_000, baseIntervalMs: 500 })).toBe(5_000);
+  });
+});
+
+describe('recordVersionArraysEqual', () => {
+  it('treats the same reference and identical contents as equal', () => {
+    const a: RecordVersionArray = [['game:1', 1], ['game:2', 3]];
+    expect(recordVersionArraysEqual(a, a)).toBe(true);
+    expect(recordVersionArraysEqual(a, [['game:1', 1], ['game:2', 3]])).toBe(true);
+  });
+
+  it('is order-insensitive (the list_ref SELECT has no ORDER BY)', () => {
+    expect(
+      recordVersionArraysEqual(
+        [['game:1', 1], ['game:2', 3]],
+        [['game:2', 3], ['game:1', 1]]
+      )
+    ).toBe(true);
+  });
+
+  it('returns false when a version differs for the same id', () => {
+    expect(
+      recordVersionArraysEqual([['game:1', 1]], [['game:1', 2]])
+    ).toBe(false);
+  });
+
+  it('returns false on length mismatch', () => {
+    expect(
+      recordVersionArraysEqual([['game:1', 1]], [['game:1', 1], ['game:2', 1]])
+    ).toBe(false);
+  });
+
+  it('returns false when an id is present in one but not the other', () => {
+    expect(
+      recordVersionArraysEqual([['game:1', 1]], [['game:2', 1]])
+    ).toBe(false);
+  });
+
+  it('treats two empty arrays as equal', () => {
+    expect(recordVersionArraysEqual([], [])).toBe(true);
+  });
+});

package/src/modules/sync/utils.ts

@@ -1,5 +1,5 @@
-import { RecordId } from 'surrealdb';
-import { RecordVersionArray, RecordVersionDiff } from '../../types';
+import type { RecordId } from 'surrealdb';
+import type { RecordVersionArray, RecordVersionDiff } from '../../types';
 import { parseRecordIdString, encodeRecordId } from '../../utils/index';
 
 export class ArraySyncer {
@@ -8,8 +8,8 @@ export class ArraySyncer {
   private needsSort = false;
 
   constructor(localArray: RecordVersionArray, remoteArray: RecordVersionArray) {
-    this.remoteArray = remoteArray.sort((a, b) => a[0].localeCompare(b[0]));
-    this.localArray = localArray.sort((a, b) => a[0].localeCompare(b[0]));
+    this.remoteArray = remoteArray.toSorted((a, b) => a[0].localeCompare(b[0]));
+    this.localArray = localArray.toSorted((a, b) => a[0].localeCompare(b[0]));
   }
 
   /**
@@ -49,7 +49,6 @@ export class ArraySyncer {
       this.localArray.sort((a, b) => a[0].localeCompare(b[0]));
       this.needsSort = false;
     }
-    console.log('xxxx555', this.localArray, this.remoteArray);
     const diff = diffRecordVersionArray(this.localArray, this.remoteArray);
     return diff;
   }
@@ -93,10 +92,12 @@ export function diffRecordVersionArray(
   return {
     added: added.map((id) => ({
       id: parseRecordIdString(id),
+      // oxlint-disable-next-line no-non-null-assertion
       version: remoteMap.get(id)!,
     })),
     updated: updated.map((id) => ({
       id: parseRecordIdString(id),
+      // oxlint-disable-next-line no-non-null-assertion
       version: remoteMap.get(id)!,
     })),
     removed: removed.map(parseRecordIdString),
@@ -127,7 +128,7 @@ export function applyRecordVersionDiff(
     currentMap.set(encodeRecordId(item.id), item.version);
   }
 
-  return Array.from(currentMap).sort((a, b) => a[0].localeCompare(b[0]));
+  return Array.from(currentMap).toSorted((a, b) => a[0].localeCompare(b[0]));
 }
 
 export function createDiffFromDbOp(
@@ -136,17 +137,14 @@ export function createDiffFromDbOp(
   version: number,
   versions?: RecordVersionArray
 ): RecordVersionDiff {
-  // Version guard: skip stale CREATE/UPDATE, but always process DELETE
-  if (op !== 'DELETE') {
-    const old = versions?.find((record) => record[0] === encodeRecordId(recordId));
-
-    if (old && old[1] >= version) {
-      return {
-        added: [],
-        updated: [],
-        removed: [],
-      };
-    }
+  const old = versions?.find((record) => record[0] === encodeRecordId(recordId));
+
+  if (old && old[1] >= version) {
+    return {
+      added: [],
+      updated: [],
+      removed: [],
+    };
   }
 
   if (op === 'CREATE') {
@@ -169,3 +167,170 @@ export function createDiffFromDbOp(
     };
   }
 }
+
+/**
+ * Default cadence for the `_00_list_ref_user_<id>` poll fallback. The
+ * poll is the safety net for SurrealDB v3's occasionally-dropped LIVE
+ * deliveries; 500ms is aggressive enough to feel real-time on the
+ * happy path while keeping the per-session query load bounded.
+ */
+export const DEFAULT_LIST_REF_POLL_INTERVAL_MS = 500;
+
+/**
+ * Build the SurrealQL select that powers both the initial-fetch and
+ * the periodic poll of `_00_list_ref[_user_<id>]`. The `parent IS NONE`
+ * predicate excludes subquery entries (rows with `parent_rel` set)
+ * because the client's `RecordVersionArray` only tracks primary rows;
+ * including subquery rows would surface them as spurious "added"
+ * diffs every tick.
+ */
+export function buildListRefSelect(table: string): string {
+  return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NONE`;
+}
+
+/**
+ * Build the SurrealQL select for a query's SUBQUERY child edges — the
+ * mirror of {@link buildListRefSelect}. `.related()` queries register a
+ * correlated subquery; the SSP materializes each matched child as a
+ * `_00_list_ref` edge tagged with `parent`/`parent_rel` (see
+ * `apps/ssp` edge writer). `parent IS NONE` (the primary select) drops
+ * these, so their bodies never reach the local cache and a cold-reload
+ * re-materialization of the correlated surql yields empty related
+ * fields. This `parent IS NOT NONE` variant pulls the child `out`+`version`
+ * pairs (any nesting depth) so we can sync their bodies into the local
+ * store SEPARATELY from the primary window array.
+ */
+export function buildSubqueryListRefSelect(table: string): string {
+  return `SELECT out, version FROM ${table} WHERE in = $in AND parent IS NOT NONE`;
+}
+
+/**
+ * Resolve the effective list-ref poll interval. Negative or zero
+ * values fall back to the default — accepting them would either
+ * disable polling silently or busy-loop the event loop.
+ */
+export function resolveListRefPollInterval(opt?: number): number {
+  if (typeof opt !== 'number' || !Number.isFinite(opt) || opt <= 0) {
+    return DEFAULT_LIST_REF_POLL_INTERVAL_MS;
+  }
+  return opt;
+}
+
+/**
+ * When the LIVE feed has delivered an event within this window, treat
+ * the LIVE subscription as healthy and back the poll off to
+ * {@link LIVE_HEALTHY_POLL_INTERVAL_MS}. As soon as LIVE quiets for
+ * longer than this, the poll snaps back to the aggressive default.
+ */
+export const LIVE_HEALTHY_COOLDOWN_MS = 5_000;
+
+/**
+ * Poll interval while LIVE is delivering events. The aggressive
+ * default 500ms costs ~120 queries / minute / session — wasted work
+ * when LIVE is already covering us. 5s keeps the safety net in place
+ * at 1/10th the load.
+ */
+export const LIVE_HEALTHY_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Pick the next poll delay based on whether LIVE has been healthy
+ * recently. If a LIVE event fired within `cooldownMs`, use the slow
+ * (`healthyIntervalMs`) cadence; otherwise the fast (`baseIntervalMs`)
+ * cadence. Pure so it's unit-testable; `Sp00kySync.startListRefPoll`
+ * calls it from a self-rescheduling timer.
+ *
+ * The healthy interval is clamped to at least `baseIntervalMs` so
+ * configuring an aggressive base (e.g. 100ms) never gets implicitly
+ * widened by this helper.
+ *
+ * @deprecated Superseded by {@link listRefPollDelayMs}, which backs the
+ * poll off based on observed change activity (LIVE *or* poll-detected)
+ * rather than LIVE liveness alone — the cross-session LIVE-permission gap
+ * means LIVE often never fires, so this helper would keep the poll pinned
+ * at the aggressive base forever even on a fully idle page. Kept (and
+ * tested) for reference.
+ */
+export function nextPollDelayMs(args: {
+  now: number;
+  lastLiveEventAt: number | null;
+  baseIntervalMs: number;
+  cooldownMs?: number;
+  healthyIntervalMs?: number;
+}): number {
+  const {
+    now,
+    lastLiveEventAt,
+    baseIntervalMs,
+    cooldownMs = LIVE_HEALTHY_COOLDOWN_MS,
+    healthyIntervalMs = LIVE_HEALTHY_POLL_INTERVAL_MS,
+  } = args;
+  if (lastLiveEventAt === null) return baseIntervalMs;
+  const sinceLive = now - lastLiveEventAt;
+  if (sinceLive < 0 || sinceLive >= cooldownMs) return baseIntervalMs;
+  return Math.max(healthyIntervalMs, baseIntervalMs);
+}
+
+/**
+ * Ceiling for the adaptive list_ref poll backoff. An idle page (no LIVE
+ * events, no poll-detected list_ref changes) coasts up to this cadence;
+ * the existing healthy-LIVE safety net runs at the same 5s, so this keeps
+ * the worst-case catch-up latency for a missed cross-session change at the
+ * cadence the codebase already treats as acceptable.
+ */
+export const LIST_REF_POLL_MAX_INTERVAL_MS = 5_000;
+
+/**
+ * Adaptive poll delay: stay at the responsive `baseIntervalMs` while
+ * changes are arriving, and exponentially back off toward `maxIntervalMs`
+ * while the `_00_list_ref` is quiet.
+ *
+ * `idleStreak` is the count of consecutive poll cycles that observed *no*
+ * change. `Sp00kySync` resets it to 0 whenever a poll detects a real
+ * remoteArray change OR a LIVE event lands, so any activity snaps the poll
+ * straight back to `baseIntervalMs`. A streak of 0 (something just
+ * happened) → base; otherwise `base * 2^streak` capped at `maxIntervalMs`.
+ *
+ * This replaces {@link nextPollDelayMs}: the old helper slowed the poll
+ * only while LIVE was *delivering*, but the cross-session LIVE-permission
+ * gap means LIVE frequently never fires here, so it left a fully idle page
+ * polling every `base` ms forever (the "continuous queries while idle"
+ * symptom). Backing off on observed idleness instead covers the
+ * LIVE-healthy case for free (LIVE applies the change → the next poll sees
+ * nothing new → the streak grows → it backs off).
+ */
+export function listRefPollDelayMs(args: {
+  idleStreak: number;
+  baseIntervalMs: number;
+  maxIntervalMs?: number;
+}): number {
+  const { idleStreak, baseIntervalMs, maxIntervalMs = LIST_REF_POLL_MAX_INTERVAL_MS } = args;
+  const cap = Math.max(baseIntervalMs, maxIntervalMs);
+  if (idleStreak <= 0) return baseIntervalMs;
+  // 2^streak grows fast; clamp the exponent so it can't overflow on a
+  // page left idle for a very long time.
+  const exponent = Math.min(idleStreak, 30);
+  return Math.min(baseIntervalMs * 2 ** exponent, cap);
+}
+
+/**
+ * Order-insensitive equality for two `RecordVersionArray`s (each a list of
+ * `[recordIdString, version]`). The `_00_list_ref` SELECT has no `ORDER
+ * BY`, so row order can differ between polls without anything having
+ * actually changed — comparing as an id→version map avoids false
+ * "changed" verdicts that would defeat the idle backoff. Record ids are
+ * unique within a query's list_ref, so a map is a faithful representation.
+ */
+export function recordVersionArraysEqual(
+  a: RecordVersionArray,
+  b: RecordVersionArray
+): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  const byId = new Map<string, number>();
+  for (const [id, version] of a) byId.set(id, version);
+  for (const [id, version] of b) {
+    // `get` returns undefined for a missing id, which never === a number.
+    if (byId.get(id) !== version) return false;
+  }
+  return true;
+}

package/src/otel/index.ts

@@ -0,0 +1,127 @@
+import type { Level } from 'pino';
+import type { PinoTransmit } from '../types';
+
+// Map pino levels to OTEL severity numbers
+// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#severity-fields
+function mapLevelToSeverityNumber(level: string): number {
+  switch (level) {
+    case 'trace':
+      return 1;
+    case 'debug':
+      return 5;
+    case 'info':
+      return 9;
+    case 'warn':
+      return 13;
+    case 'error':
+      return 17;
+    case 'fatal':
+      return 21;
+    default:
+      return 9;
+  }
+}
+
+async function loadOtelModules(otelEndpoint: string) {
+  const [{ LoggerProvider, BatchLogRecordProcessor }, { OTLPLogExporter }, { resourceFromAttributes }, { ATTR_SERVICE_NAME }] =
+    await Promise.all([
+      import('@opentelemetry/sdk-logs'),
+      import('@opentelemetry/exporter-logs-otlp-proto'),
+      import('@opentelemetry/resources'),
+      import('@opentelemetry/semantic-conventions'),
+    ]);
+
+  const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: 'sp00ky-client',
+  });
+
+  const exporter = new OTLPLogExporter({
+    url: otelEndpoint,
+  });
+
+  const loggerProvider = new LoggerProvider({
+    resource,
+    processors: [new BatchLogRecordProcessor(exporter)],
+  });
+
+  const otelLoggerCache: Record<string, ReturnType<typeof loggerProvider.getLogger>> = {};
+
+  return (category: string) => {
+    if (!otelLoggerCache[category]) {
+      otelLoggerCache[category] = loggerProvider.getLogger(category);
+    }
+    return otelLoggerCache[category];
+  };
+}
+
+/**
+ * Creates a pino browser transmit object that forwards logs to an OpenTelemetry collector.
+ *
+ * @example
+ * ```ts
+ * import { createOtelTransmit } from '@spooky-sync/core/otel';
+ *
+ * new Sp00kyClient({
+ *   // ...
+ *   otelTransmit: createOtelTransmit('http://localhost:4318/v1/logs'),
+ * });
+ * ```
+ */
+export function createOtelTransmit(endpoint: string, level: Level = 'info'): PinoTransmit {
+  // Start loading OTel modules eagerly (don't await — we're synchronous)
+  const otelReady = loadOtelModules(endpoint);
+
+  return {
+    level: level,
+    send: (levelLabel: string, logEvent: any) => {
+      // oxlint-disable-next-line promise/always-return
+      otelReady.then((getOtelLogger) => {
+        try {
+          const messages = [...logEvent.messages];
+          const severityNumber = mapLevelToSeverityNumber(levelLabel);
+
+          // Construct the message body
+          let body = '';
+          const lastMsg = messages.pop();
+
+          if (typeof lastMsg === 'string') {
+            body = lastMsg;
+          } else if (lastMsg) {
+            body = JSON.stringify(lastMsg);
+          }
+
+          let category = 'sp00ky-client::unknown';
+
+          const attributes = {};
+          for (const msg of messages) {
+            if (typeof msg === 'object') {
+              if (msg.Category) {
+                category = msg.Category;
+                delete msg.Category;
+              }
+              Object.assign(attributes, msg);
+            }
+          }
+
+          // Emit to OTEL SDK
+          getOtelLogger(category).emit({
+            severityNumber: severityNumber,
+            severityText: levelLabel.toUpperCase(),
+            body: body,
+            attributes: {
+              ...logEvent.bindings[0],
+              ...attributes,
+            },
+            timestamp: new Date(logEvent.ts),
+          });
+        } catch (e) {
+          // oxlint-disable-next-line no-console
+          console.warn('Failed to transmit log to OTEL endpoint', e);
+        }
+      }).catch((e) => {
+        // oxlint-disable-next-line no-console
+        console.warn('Failed to load OpenTelemetry modules', e);
+      });
+    },
+  };
+}