@smoothbricks/lmao 0.1.0

package/src/lib/tracers/StdioTracer.ts

@@ -0,0 +1,380 @@
+/**
+ * StdioTracer - A tracer that prints spans to stdout/stderr
+ *
+ * Features:
+ * - Color-coded trace IDs based on trace_id for visual separation of concurrent traces
+ * - Per-trace indent tracking using Map<TraceId, number> for correct nesting
+ * - Human-readable timestamps (ISO 8601) and durations
+ * - Tree-style output with ├─ for start and └─ for end
+ * - Exceptions written to stderr
+ *
+ * Useful for development/debugging to see span execution in real-time.
+ *
+ * @example
+ * ```typescript
+ * import { createTraceRoot } from '@smoothbricks/lmao/node';
+ * import { JsBufferStrategy } from '@smoothbricks/lmao';
+ *
+ * const ctx = defineOpContext({ logSchema: mySchema });
+ * const { trace } = new StdioTracer(ctx, {
+ *   bufferStrategy: new JsBufferStrategy(),
+ *   createTraceRoot,
+ * });
+ *
+ * await trace('fetch-user', fetchOp);
+ *
+ * // Output:
+ * // [2025-12-25T10:30:45.123Z] [123456] fetch-user
+ * // [2025-12-25T10:30:45.125Z] [123456]   ├─ db-query
+ * // [2025-12-25T10:30:45.225Z] [123456]   └─ db-query [OK] (100.00ms)
+ * // [2025-12-25T10:30:45.226Z] [123456] fetch-user (103.00ms) ========
+ * ```
+ */
+
+import type { OpContextBinding } from '../opContext/types.js';
+import {
+  ENTRY_TYPE_DEBUG,
+  ENTRY_TYPE_ERROR,
+  ENTRY_TYPE_INFO,
+  ENTRY_TYPE_SPAN_ERR,
+  ENTRY_TYPE_SPAN_EXCEPTION,
+  ENTRY_TYPE_SPAN_OK,
+  ENTRY_TYPE_TRACE,
+  ENTRY_TYPE_WARN,
+} from '../schema/systemSchema.js';
+import type { TraceId } from '../traceId.js';
+import type { TracerOptions } from '../tracer.js';
+import { Tracer } from '../tracer.js';
+import type { AnySpanBuffer, SpanBuffer } from '../types.js';
+
+export interface StdioWritable {
+  write(chunk: string): boolean;
+}
+
+// ============================================================================
+// Formatting Helpers
+// ============================================================================
+
+/**
+ * Format nanosecond timestamp to ISO 8601 string with millisecond precision.
+ */
+function formatTimestamp(nanos: bigint): string {
+  const millis = Number(nanos / 1_000_000n);
+  return new Date(millis).toISOString();
+}
+
+/**
+ * Format duration in nanoseconds to human-readable string.
+ */
+function formatDuration(nanos: bigint): string {
+  const n = Number(nanos);
+  if (n >= 1_000_000_000) {
+    return `${(n / 1_000_000_000).toFixed(2)}s`;
+  }
+  if (n >= 1_000_000) {
+    return `${(n / 1_000_000).toFixed(2)}ms`;
+  }
+  if (n >= 1_000) {
+    return `${(n / 1_000).toFixed(2)}µs`;
+  }
+  return `${n}ns`;
+}
+
+/**
+ * ANSI color codes for visual trace separation.
+ * Each trace gets a consistent color based on trace_id hash.
+ */
+const COLORS = [
+  '\u001b[31m', // Red
+  '\u001b[32m', // Green
+  '\u001b[33m', // Yellow
+  '\u001b[34m', // Blue
+  '\u001b[35m', // Magenta
+  '\u001b[36m', // Cyan
+  '\u001b[91m', // Bright Red
+  '\u001b[92m', // Bright Green
+  '\u001b[93m', // Bright Yellow
+  '\u001b[94m', // Bright Blue
+  '\u001b[95m', // Bright Magenta
+  '\u001b[96m', // Bright Cyan
+] as const;
+
+const RESET = '\u001b[0m';
+
+/**
+ * Get consistent color for a trace_id.
+ * Uses modulo arithmetic to map 128-bit trace_id to one of the colors.
+ */
+function getTraceColor(traceId: TraceId): string {
+  // Convert TraceId (string representation) to a number for coloring
+  // Use simple hash of the string to pick a color
+  let hash = 0;
+  const str = String(traceId);
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    // Simple hash function
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  const index = Math.abs(hash) % COLORS.length;
+  return COLORS[index];
+}
+
+/**
+ * Get status string from entry type.
+ */
+function getStatus(entryType: number): string {
+  switch (entryType) {
+    case ENTRY_TYPE_SPAN_OK:
+      return 'OK';
+    case ENTRY_TYPE_SPAN_ERR:
+      return 'ERR';
+    case ENTRY_TYPE_SPAN_EXCEPTION:
+      return 'EXCEPTION';
+    default:
+      return 'UNKNOWN';
+  }
+}
+
+function getLogLevel(entryType: number): string | null {
+  switch (entryType) {
+    case ENTRY_TYPE_TRACE:
+      return 'TRACE';
+    case ENTRY_TYPE_DEBUG:
+      return 'DEBUG';
+    case ENTRY_TYPE_INFO:
+      return 'INFO';
+    case ENTRY_TYPE_WARN:
+      return 'WARN';
+    case ENTRY_TYPE_ERROR:
+      return 'ERROR';
+    default:
+      return null;
+  }
+}
+
+function formatTemplateMessage(buffer: AnySpanBuffer, row: number, template: string): string {
+  return template.replace(/\{\{([A-Za-z0-9_]+)\}\}/g, (_full, key: string) => {
+    const values = Reflect.get(buffer, `${key}_values`) as unknown;
+    if (values == null) return `{{${key}}}`;
+
+    if (Array.isArray(values)) {
+      const value = values[row];
+      return value === null || value === undefined ? `{{${key}}}` : String(value);
+    }
+
+    if (ArrayBuffer.isView(values)) {
+      const value = Reflect.get(values, row) as unknown;
+      return value === null || value === undefined ? `{{${key}}}` : String(value);
+    }
+
+    return `{{${key}}}`;
+  });
+}
+
+// ============================================================================
+// StdioTracer Options
+// ============================================================================
+
+/**
+ * Options for StdioTracer
+ */
+export interface StdioTracerOptions<
+  T extends import('../schema/LogSchema.js').LogSchema = import('../schema/LogSchema.js').LogSchema,
+> extends TracerOptions<T> {
+  /** Output stream (defaults to process.stdout) */
+  out?: StdioWritable;
+  /** Error stream (defaults to process.stderr) */
+  err?: StdioWritable;
+  /** Enable ANSI colors (defaults to true) */
+  colorEnabled?: boolean;
+}
+
+// ============================================================================
+// StdioTracer
+// ============================================================================
+
+/**
+ * Tracer that prints spans to stdout/stderr with colored, indented output.
+ *
+ * Features:
+ * - Color-coded trace IDs for visual separation of concurrent traces
+ * - Per-trace indent tracking (concurrent-safe via Map)
+ * - Tree-style output (├─ for start, └─ for end)
+ * - Human-readable timestamps and durations
+ * - Exceptions go to stderr
+ */
+export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+  /**
+   * Per-trace indent levels for concurrent-safe nesting.
+   * Key is trace_id string representation, value is current indent level.
+   */
+  private readonly indents = new Map<string, number>();
+
+  private readonly out: StdioWritable;
+  private readonly err: StdioWritable;
+  private readonly colorEnabled: boolean;
+
+  constructor(binding: B, options: StdioTracerOptions<B['logBinding']['logSchema']>) {
+    super(binding, options);
+    this.out = options.out ?? process.stdout;
+    this.err = options.err ?? process.stderr;
+    this.colorEnabled = options.colorEnabled ?? true;
+  }
+
+  // --------------------------------------------------------------------------
+  // Indent Management
+  // --------------------------------------------------------------------------
+
+  private getIndent(traceId: TraceId): number {
+    const key = String(traceId);
+    return this.indents.get(key) ?? 0;
+  }
+
+  private incrementIndent(traceId: TraceId): void {
+    const key = String(traceId);
+    this.indents.set(key, this.getIndent(traceId) + 1);
+  }
+
+  private decrementIndent(traceId: TraceId): void {
+    const key = String(traceId);
+    const current = this.getIndent(traceId);
+    if (current <= 1) {
+      this.indents.delete(key); // Cleanup when trace ends
+    } else {
+      this.indents.set(key, current - 1);
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Color Helpers
+  // --------------------------------------------------------------------------
+
+  private color(traceId: TraceId): string {
+    return this.colorEnabled ? getTraceColor(traceId) : '';
+  }
+
+  private reset(): string {
+    return this.colorEnabled ? RESET : '';
+  }
+
+  private printLogRows(buffer: AnySpanBuffer, indent: number): void {
+    let current: AnySpanBuffer | null = buffer;
+    let isRootSegment = true;
+
+    while (current) {
+      const start = isRootSegment ? 2 : 0;
+      const end = current._writeIndex;
+
+      for (let i = start; i < end; i++) {
+        const level = getLogLevel(current.entry_type[i]);
+        if (!level) continue;
+
+        const template = current.message_values[i] ?? '';
+        const message = formatTemplateMessage(current, i, template);
+        const ts = formatTimestamp(current.timestamp[i]);
+        const traceId = current.trace_id;
+        const line =
+          `[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ` +
+          `${'  '.repeat(indent)}· ${level} ${message}\n`;
+
+        if (level === 'ERROR') {
+          this.err.write(line);
+        } else {
+          this.out.write(line);
+        }
+      }
+
+      current = current._overflow ?? null;
+      isRootSegment = false;
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Lifecycle Hooks
+  // --------------------------------------------------------------------------
+
+  onTraceStart(rootBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void {
+    const traceId = rootBuffer.trace_id;
+    const name = rootBuffer.message_values[0];
+    const ts = formatTimestamp(rootBuffer.timestamp[0]);
+
+    this.out.write(`[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ${name}\n`);
+    this.incrementIndent(traceId);
+  }
+
+  onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void {
+    const traceId = rootBuffer.trace_id;
+    this.printLogRows(rootBuffer, 1);
+    this.decrementIndent(traceId);
+
+    const name = rootBuffer.message_values[0];
+    const startTs = rootBuffer.timestamp[0];
+    const endTs = rootBuffer.timestamp[1];
+    const duration = formatDuration(endTs - startTs);
+    const entryType = rootBuffer.entry_type[1];
+    const status = getStatus(entryType);
+    const ts = formatTimestamp(endTs);
+
+    const line = `[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ${name} [${status}] (${duration}) ${'='.repeat(40)}\n`;
+
+    // Write exceptions to stderr
+    if (entryType === ENTRY_TYPE_SPAN_EXCEPTION) {
+      this.err.write(line);
+    } else {
+      this.out.write(line);
+    }
+  }
+
+  onSpanStart(childBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void {
+    const traceId = childBuffer.trace_id;
+    const indent = this.getIndent(traceId);
+    const name = childBuffer.message_values[0];
+    const ts = formatTimestamp(childBuffer.timestamp[0]);
+
+    this.out.write(`[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ${'  '.repeat(indent)}├─ ${name}\n`);
+    this.incrementIndent(traceId);
+  }
+
+  onSpanEnd(childBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void {
+    const traceId = childBuffer.trace_id;
+    this.decrementIndent(traceId);
+    const indent = this.getIndent(traceId);
+    this.printLogRows(childBuffer, indent + 1);
+
+    const name = childBuffer.message_values[0];
+    const startTs = childBuffer.timestamp[0];
+    const endTs = childBuffer.timestamp[1];
+    const duration = formatDuration(endTs - startTs);
+    const entryType = childBuffer.entry_type[1];
+    const status = getStatus(entryType);
+    const ts = formatTimestamp(endTs);
+
+    const line = `[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ${'  '.repeat(indent)}└─ ${name} [${status}] (${duration})\n`;
+
+    // Write exceptions to stderr
+    if (entryType === ENTRY_TYPE_SPAN_EXCEPTION) {
+      this.err.write(line);
+    } else {
+      this.out.write(line);
+    }
+  }
+
+  onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    const stats = _buffer._stats;
+    // Compute utilization = totalWrites / (spansCreated * usableRowsPerSpan)
+    const usableRowsPerSpan = stats.capacity - 2;
+    const utilization =
+      stats.spansCreated > 0
+        ? ((stats.totalWrites / (stats.spansCreated * usableRowsPerSpan)) * 100).toFixed(1)
+        : '0.0';
+    const traceId = _buffer.trace_id;
+    const ts = formatTimestamp(_buffer.timestamp[0]);
+
+    this.out.write(
+      `[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ` +
+        `[CAPACITY] writes=${stats.totalWrites} spans=${stats.spansCreated} utilization=${utilization}% ` +
+        `capacity=${stats.capacity}\n`,
+    );
+  }
+}

package/src/lib/tracers/TestTracer.ts

@@ -0,0 +1,146 @@
+/**
+ * TestTracer - A tracer that accumulates completed root trace buffers for test inspection.
+ *
+ * Child spans are accessible via the buffer's `_children` tree - no need to track them separately.
+ * This is the primary tracer for tests that need to inspect trace output, convert to Arrow tables,
+ * or verify buffer contents.
+ *
+ * @example
+ * ```typescript
+ * import { createTraceRoot } from '@smoothbricks/lmao/node';
+ * import { JsBufferStrategy } from '@smoothbricks/lmao';
+ *
+ * const ctx = defineOpContext({ logSchema });
+ * const tracer = new TestTracer(ctx, {
+ *   bufferStrategy: new JsBufferStrategy(),
+ *   createTraceRoot,
+ * });
+ *
+ * await tracer.trace('my-op', myOp);
+ *
+ * // Inspect buffers
+ * expect(tracer.rootBuffers).toHaveLength(1);
+ *
+ * // Convert to Arrow using strategy
+ * const table = await tracer.bufferStrategy.toArrowTable(tracer.rootBuffers[0]);
+ * ```
+ *
+ * @module tracers/TestTracer
+ */
+
+import type { OpContextBinding } from '../opContext/types.js';
+import type { LogSchema } from '../schema/LogSchema.js';
+import { Tracer } from '../tracer.js';
+import type { SpanBuffer } from '../types.js';
+
+type ResettableBufferStrategy = {
+  reset: () => void;
+};
+
+function isResettableBufferStrategy(value: unknown): value is ResettableBufferStrategy {
+  return typeof value === 'object' && value !== null && typeof Reflect.get(value, 'reset') === 'function';
+}
+
+/**
+ * Snapshot of buffer stats captured before reset during capacity tuning.
+ */
+export interface StatsSnapshot<T extends LogSchema = LogSchema> {
+  buffer: SpanBuffer<T>;
+  totalWrites: number;
+  spansCreated: number;
+  capacity: number;
+}
+
+/**
+ * Test tracer that accumulates root buffers for inspection.
+ *
+ * Collects all completed root trace buffers in `rootBuffers` array.
+ * Child spans are accessible via the buffer's `_children` tree -
+ * no need to track them separately.
+ *
+ * Also tracks capacity tuning events via `statsSnapshots` to verify
+ * that `onStatsWillResetFor` is called before stats are reset.
+ *
+ * @example
+ * ```typescript
+ * const ctx = defineOpContext({ logSchema });
+ * const tracer = new TestTracer(ctx);
+ * const { trace } = tracer;
+ *
+ * await trace('my-op', myOp);
+ *
+ * // Inspect buffer
+ * expect(tracer.rootBuffers).toHaveLength(1);
+ * expect(tracer.rootBuffers[0].message_values[0]).toBe('my-op');
+ *
+ * // Convert to Arrow for detailed inspection
+ * const table = convertSpanTreeToArrowTable(tracer.rootBuffers[0]);
+ * expect(table.numRows).toBe(2); // span-start + span-ok
+ *
+ * // Verify capacity tuning was captured
+ * expect(tracer.statsSnapshots.length).toBeGreaterThan(0);
+ * ```
+ */
+export class TestTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+  /**
+   * All completed root trace buffers.
+   * Child spans are accessible via each buffer's `_children` tree.
+   */
+  readonly rootBuffers: SpanBuffer<B['logBinding']['logSchema']>[] = [];
+
+  /**
+   * Stats snapshots captured before reset during capacity tuning.
+   * Used to verify onStatsWillResetFor hook is called correctly.
+   */
+  readonly statsSnapshots: StatsSnapshot<B['logBinding']['logSchema']>[] = [];
+
+  // ===========================================================================
+  // Lifecycle hook implementations
+  // ===========================================================================
+
+  onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op - we collect on end, not start
+  }
+
+  onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // Collect the root buffer when trace completes
+    this.rootBuffers.push(rootBuffer);
+  }
+
+  onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op - children are in tree, accessed via rootBuffer._children
+  }
+
+  onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op - children are in tree, accessed via rootBuffer._children
+  }
+
+  onStatsWillResetFor(buffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // Capture stats snapshot before they're reset
+    const stats = buffer._stats;
+    this.statsSnapshots.push({
+      buffer,
+      totalWrites: stats.totalWrites,
+      spansCreated: stats.spansCreated,
+      capacity: stats.capacity,
+    });
+  }
+
+  // ===========================================================================
+  // Test utilities
+  // ===========================================================================
+
+  /**
+   * Clear all collected buffers and stats snapshots.
+   * Useful for cleanup between tests.
+   */
+  clear(): void {
+    this.rootBuffers.length = 0;
+    this.statsSnapshots.length = 0;
+
+    // Reset the buffer strategy if it supports it (e.g., WasmBufferStrategy)
+    if (isResettableBufferStrategy(this.bufferStrategy)) {
+      this.bufferStrategy.reset();
+    }
+  }
+}

package/src/lib/tracers/__tests__/ArrayQueueTracer.test.ts

@@ -0,0 +1,184 @@
+// Configure Node.js timestamp implementation - MUST be first import
+import '../../__tests__/test-helpers.js';
+
+import { describe, expect, it } from 'bun:test';
+import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
+import { convertSpanTreeToArrowTable } from '../../convertToArrow.js';
+import { defineLogSchema, defineOpContext, S } from '../../defineOpContext.js';
+import { ArrayQueueTracer } from '../ArrayQueueTracer.js';
+
+describe('ArrayQueueTracer', () => {
+  const testSchema = defineLogSchema({
+    userId: S.category(),
+  });
+
+  const ctx = defineOpContext({
+    logSchema: testSchema,
+  });
+  const { defineOp } = ctx;
+
+  describe('queue accumulation', () => {
+    it('should start with empty queue', () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      expect(tracer.queue).toHaveLength(0);
+    });
+
+    it('should queue root buffer after trace completes', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+      await trace('queued-trace', testOp);
+
+      expect(tracer.queue).toHaveLength(1);
+      expect(tracer.queue[0].message_values[0]).toBe('queued-trace');
+    });
+
+    it('should queue multiple traces in order', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+
+      await trace('first', testOp);
+      await trace('second', testOp);
+      await trace('third', testOp);
+
+      expect(tracer.queue).toHaveLength(3);
+      expect(tracer.queue[0].message_values[0]).toBe('first');
+      expect(tracer.queue[1].message_values[0]).toBe('second');
+      expect(tracer.queue[2].message_values[0]).toBe('third');
+    });
+
+    it('should queue buffer even if trace throws', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const failOp = defineOp('fail', async () => {
+        throw new Error('boom');
+      });
+
+      await expect(trace('failing', failOp)).rejects.toThrow('boom');
+
+      expect(tracer.queue).toHaveLength(1);
+      expect(tracer.queue[0].message_values[0]).toBe('failing');
+    });
+  });
+
+  describe('drain()', () => {
+    it('should return all queued buffers', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+
+      await trace('a', testOp);
+      await trace('b', testOp);
+
+      const drained = tracer.drain();
+
+      expect(drained).toHaveLength(2);
+      expect(drained[0].message_values[0]).toBe('a');
+      expect(drained[1].message_values[0]).toBe('b');
+    });
+
+    it('should clear queue after drain', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+
+      await trace('x', testOp);
+      await trace('y', testOp);
+
+      tracer.drain();
+
+      expect(tracer.queue).toHaveLength(0);
+    });
+
+    it('should return empty array when queue is empty', () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+
+      const drained = tracer.drain();
+
+      expect(drained).toHaveLength(0);
+      expect(Array.isArray(drained)).toBe(true);
+    });
+
+    it('should allow new traces after drain', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+
+      await trace('before', testOp);
+      tracer.drain();
+      await trace('after', testOp);
+
+      expect(tracer.queue).toHaveLength(1);
+      expect(tracer.queue[0].message_values[0]).toBe('after');
+    });
+
+    it('should return independent array (not reference to internal queue)', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+
+      await trace('test', testOp);
+
+      const drained = tracer.drain();
+
+      // Modify returned array
+      drained.push(drained[0]);
+
+      // Internal queue should be unaffected
+      expect(tracer.queue).toHaveLength(0);
+    });
+  });
+
+  describe('production pattern: batch processing', () => {
+    it('should support batch-then-process pattern', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const testOp = defineOp('test', (ctx) => ctx.ok('done'));
+
+      // Simulate batching traces
+      await trace('req-1', testOp);
+      await trace('req-2', testOp);
+      await trace('req-3', testOp);
+
+      // Process batch
+      const batch = tracer.drain();
+      const tables = batch.map((buf) => convertSpanTreeToArrowTable(buf));
+
+      expect(tables).toHaveLength(3);
+      for (const table of tables) {
+        expect(table.numRows).toBe(2); // span-start + span-ok
+      }
+
+      // Queue is now empty, ready for next batch
+      expect(tracer.queue).toHaveLength(0);
+    });
+  });
+
+  describe('child spans', () => {
+    it('should include child spans in queued buffer tree', async () => {
+      const tracer = new ArrayQueueTracer(ctx, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const childOp = defineOp('child', (ctx) => ctx.ok('c'));
+      const parentOp = defineOp('parent', async (ctx) => {
+        await ctx.span('child-span', childOp);
+        return ctx.ok('p');
+      });
+
+      await trace('root', parentOp);
+
+      const [buffer] = tracer.drain();
+      expect(buffer._children).toHaveLength(1);
+      expect(buffer._children[0].message_values[0]).toBe('child-span');
+    });
+  });
+});