@smoothbricks/lmao 0.1.0

package/dist/lib/tracers/SQLiteTracer.d.ts

@@ -0,0 +1,42 @@
+import type { OpContextBinding } from '../opContext/types.js';
+import type { AsyncSQLiteDatabase, SyncSQLiteDatabase } from '../sqlite/sqlite-db.js';
+import { Tracer, type TracerOptions } from '../tracer.js';
+import type { SpanBuffer } from '../types.js';
+export interface SQLiteTracerOptions<T extends import('../schema/LogSchema.js').LogSchema = import('../schema/LogSchema.js').LogSchema> extends TracerOptions<T> {
+    db: SyncSQLiteDatabase;
+}
+export interface SQLiteAsyncTracerOptions<T extends import('../schema/LogSchema.js').LogSchema = import('../schema/LogSchema.js').LogSchema> extends TracerOptions<T> {
+    db: AsyncSQLiteDatabase | Promise<AsyncSQLiteDatabase>;
+}
+/**
+ * Tracer that persists completed root traces to SQLite synchronously.
+ */
+export declare class SQLiteTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+    private readonly writer;
+    constructor(binding: B, options: SQLiteTracerOptions<B['logBinding']['logSchema']>);
+    onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    close(): Promise<void>;
+}
+/**
+ * Tracer that persists completed root traces to SQLite asynchronously.
+ *
+ * onTraceEnd starts a background write pipeline; flush() awaits pipeline completion.
+ */
+export declare class SQLiteAsyncTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+    private readonly writerPromise;
+    private pendingWrites;
+    private pendingErrors;
+    constructor(binding: B, options: SQLiteAsyncTracerOptions<B['logBinding']['logSchema']>);
+    onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=SQLiteTracer.d.ts.map

package/dist/lib/tracers/SQLiteTracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SQLiteTracer.d.ts","sourceRoot":"","sources":["../../../src/lib/tracers/SQLiteTracer.ts"],"names":[],"mappings":"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"}

package/dist/lib/tracers/SQLiteTracer.js

@@ -0,0 +1,84 @@
+import { SQLiteAsyncTraceWriter } from '../sqlite/sqlite-async-writer.js';
+import { SQLiteTraceWriter } from '../sqlite/sqlite-writer.js';
+import { Tracer } from '../tracer.js';
+/**
+ * Tracer that persists completed root traces to SQLite synchronously.
+ */
+export class SQLiteTracer extends Tracer {
+    writer;
+    constructor(binding, options) {
+        super(binding, options);
+        this.writer = new SQLiteTraceWriter(options.db);
+    }
+    onTraceStart(_rootBuffer) {
+        // No-op
+    }
+    onTraceEnd(rootBuffer) {
+        this.writer.flush(rootBuffer);
+    }
+    onSpanStart(_childBuffer) {
+        // No-op
+    }
+    onSpanEnd(_childBuffer) {
+        // No-op
+    }
+    onStatsWillResetFor(_buffer) {
+        // No-op
+    }
+    async close() {
+        this.writer.close();
+    }
+}
+/**
+ * Tracer that persists completed root traces to SQLite asynchronously.
+ *
+ * onTraceEnd starts a background write pipeline; flush() awaits pipeline completion.
+ */
+export class SQLiteAsyncTracer extends Tracer {
+    writerPromise;
+    pendingWrites = Promise.resolve();
+    pendingErrors = [];
+    constructor(binding, options) {
+        super(binding, options);
+        this.writerPromise = Promise.resolve(options.db).then((db) => new SQLiteAsyncTraceWriter(db));
+    }
+    onTraceStart(_rootBuffer) {
+        // No-op
+    }
+    onTraceEnd(rootBuffer) {
+        this.pendingWrites = this.pendingWrites.then(async () => {
+            try {
+                const writer = await this.writerPromise;
+                await writer.flush(rootBuffer);
+            }
+            catch (error) {
+                this.pendingErrors.push(error);
+            }
+        });
+    }
+    onSpanStart(_childBuffer) {
+        // No-op
+    }
+    onSpanEnd(_childBuffer) {
+        // No-op
+    }
+    onStatsWillResetFor(_buffer) {
+        // No-op
+    }
+    async flush() {
+        await this.pendingWrites;
+        if (this.pendingErrors.length > 0) {
+            const errors = this.pendingErrors;
+            this.pendingErrors = [];
+            if (errors.length === 1) {
+                throw errors[0];
+            }
+            throw new AggregateError(errors, `SQLiteAsyncTracer flush failed for ${errors.length} trace writes`);
+        }
+    }
+    async close() {
+        await this.flush();
+        const writer = await this.writerPromise;
+        await writer.close();
+    }
+}

package/dist/lib/tracers/StdioTracer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 type { TracerOptions } from '../tracer.js';
+import { Tracer } from '../tracer.js';
+import type { AnySpanBuffer, SpanBuffer } from '../types.js';
+export interface StdioWritable {
+    write(chunk: string): boolean;
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare 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;
+    private readonly out;
+    private readonly err;
+    private readonly colorEnabled;
+    constructor(binding: B, options: StdioTracerOptions<B['logBinding']['logSchema']>);
+    private getIndent;
+    private incrementIndent;
+    private decrementIndent;
+    private color;
+    private reset;
+    private printLogRows;
+    onTraceStart(rootBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void;
+    onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void;
+    onSpanStart(childBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void;
+    onSpanEnd(childBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void;
+    onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+}
+//# sourceMappingURL=StdioTracer.d.ts.map

package/dist/lib/tracers/StdioTracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StdioTracer.d.ts","sourceRoot":"","sources":["../../../src/lib/tracers/StdioTracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAY9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AA+HD;;GAEG;AACH,MAAM,WAAW,kBAAkB,CACjC,CAAC,SAAS,OAAO,wBAAwB,EAAE,SAAS,GAAG,OAAO,wBAAwB,EAAE,SAAS,CACjG,SAAQ,aAAa,CAAC,CAAC,CAAC;IACxB,iDAAiD;IACjD,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,gDAAgD;IAChD,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAMD;;;;;;;;;GASG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,CAAE,SAAQ,MAAM,CAAC,CAAC,CAAC;IACvF;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;gBAE3B,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC;IAWjF,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,YAAY;IAoCpB,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,aAAa,GAAG,IAAI;IASxF,UAAU,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,aAAa,GAAG,IAAI;IAuBtF,WAAW,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,aAAa,GAAG,IAAI;IAUxF,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,aAAa,GAAG,IAAI;IAwBtF,mBAAmB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI;CAiB7E"}

package/dist/lib/tracers/StdioTracer.js

@@ -0,0 +1,270 @@
+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 { Tracer } from '../tracer.js';
+// ============================================================================
+// Formatting Helpers
+// ============================================================================
+/**
+ * Format nanosecond timestamp to ISO 8601 string with millisecond precision.
+ */
+function formatTimestamp(nanos) {
+    const millis = Number(nanos / 1000000n);
+    return new Date(millis).toISOString();
+}
+/**
+ * Format duration in nanoseconds to human-readable string.
+ */
+function formatDuration(nanos) {
+    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
+];
+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) {
+    // 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) {
+    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) {
+    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, row, template) {
+    return template.replace(/\{\{([A-Za-z0-9_]+)\}\}/g, (_full, key) => {
+        const values = Reflect.get(buffer, `${key}_values`);
+        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);
+            return value === null || value === undefined ? `{{${key}}}` : String(value);
+        }
+        return `{{${key}}}`;
+    });
+}
+// ============================================================================
+// 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 extends Tracer {
+    /**
+     * Per-trace indent levels for concurrent-safe nesting.
+     * Key is trace_id string representation, value is current indent level.
+     */
+    indents = new Map();
+    out;
+    err;
+    colorEnabled;
+    constructor(binding, options) {
+        super(binding, options);
+        this.out = options.out ?? process.stdout;
+        this.err = options.err ?? process.stderr;
+        this.colorEnabled = options.colorEnabled ?? true;
+    }
+    // --------------------------------------------------------------------------
+    // Indent Management
+    // --------------------------------------------------------------------------
+    getIndent(traceId) {
+        const key = String(traceId);
+        return this.indents.get(key) ?? 0;
+    }
+    incrementIndent(traceId) {
+        const key = String(traceId);
+        this.indents.set(key, this.getIndent(traceId) + 1);
+    }
+    decrementIndent(traceId) {
+        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
+    // --------------------------------------------------------------------------
+    color(traceId) {
+        return this.colorEnabled ? getTraceColor(traceId) : '';
+    }
+    reset() {
+        return this.colorEnabled ? RESET : '';
+    }
+    printLogRows(buffer, indent) {
+        let current = 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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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/dist/lib/tracers/TestTracer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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';
+/**
+ * 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 declare 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']>[];
+    onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    onStatsWillResetFor(buffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    /**
+     * Clear all collected buffers and stats snapshots.
+     * Useful for cleanup between tests.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=TestTracer.d.ts.map

package/dist/lib/tracers/TestTracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestTracer.d.ts","sourceRoot":"","sources":["../../../src/lib/tracers/TestTracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAU9C;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC5D,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,CAAE,SAAQ,MAAM,CAAC,CAAC,CAAC;IACtF;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,CAAM;IAEtE;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,CAAM;IAM5E,YAAY,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI;IAIzE,UAAU,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI;IAKtE,WAAW,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI;IAIzE,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI;IAIvE,mBAAmB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI;IAe3E;;;OAGG;IACH,KAAK,IAAI,IAAI;CASd"}

package/dist/lib/tracers/TestTracer.js

@@ -0,0 +1,87 @@
+import { Tracer } from '../tracer.js';
+function isResettableBufferStrategy(value) {
+    return typeof value === 'object' && value !== null && typeof Reflect.get(value, 'reset') === 'function';
+}
+/**
+ * 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 extends Tracer {
+    /**
+     * All completed root trace buffers.
+     * Child spans are accessible via each buffer's `_children` tree.
+     */
+    rootBuffers = [];
+    /**
+     * Stats snapshots captured before reset during capacity tuning.
+     * Used to verify onStatsWillResetFor hook is called correctly.
+     */
+    statsSnapshots = [];
+    // ===========================================================================
+    // Lifecycle hook implementations
+    // ===========================================================================
+    onTraceStart(_rootBuffer) {
+        // No-op - we collect on end, not start
+    }
+    onTraceEnd(rootBuffer) {
+        // Collect the root buffer when trace completes
+        this.rootBuffers.push(rootBuffer);
+    }
+    onSpanStart(_childBuffer) {
+        // No-op - children are in tree, accessed via rootBuffer._children
+    }
+    onSpanEnd(_childBuffer) {
+        // No-op - children are in tree, accessed via rootBuffer._children
+    }
+    onStatsWillResetFor(buffer) {
+        // 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() {
+        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();
+        }
+    }
+}