@smoothbricks/lmao 0.1.0

package/dist/lib/traceRoot.js

@@ -0,0 +1,19 @@
+// Re-export TraceId types from traceId.ts
+export { createTraceId, extractSpanIdentity, generateTraceId, isValidTraceId, MAX_TRACE_ID_LENGTH } from './traceId.js';
+/**
+ * TraceRoot._system memory layout (little-endian):
+ *
+ * Offset  Size   Field
+ * 0       8      anchorEpochNanos (i64) - epoch time in nanoseconds
+ * 8       8      anchorPerfNow (f64) - high-res timer anchor
+ * 16      1      trace_id_len (u8) - length of trace_id UTF-8 bytes
+ * 17      N      trace_id (UTF-8 bytes)
+ *
+ * Total: 17 + trace_id.length bytes
+ *
+ * This layout enables NAPI/WASM to read anchors directly without BigInt extraction.
+ */
+export const TRACE_ROOT_ANCHOR_EPOCH_OFFSET = 0;
+export const TRACE_ROOT_ANCHOR_PERF_OFFSET = 8;
+export const TRACE_ROOT_TRACE_ID_LEN_OFFSET = 16;
+export const TRACE_ROOT_TRACE_ID_OFFSET = 17;

package/dist/lib/traceRoot.node.d.ts

@@ -0,0 +1,77 @@
+/**
+ * TraceRoot - Node.js implementation.
+ *
+ * Uses process.hrtime.bigint() for true nanosecond precision and writes directly
+ * to SpanBuffer state from JavaScript.
+ *
+ * @module traceRoot.node
+ */
+import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import { type TraceId } from './traceId.js';
+import { type ITraceRoot, type TracerLifecycleHooks } from './traceRoot.js';
+import type { AnySpanBuffer } from './types.js';
+/**
+ * TraceRoot - Node.js implementation.
+ *
+ * Stores anchor data in _system ArrayBuffer and writes timestamps directly from JS.
+ */
+export declare class TraceRoot implements ITraceRoot {
+    /**
+     * Raw backing buffer containing anchor timestamps and trace_id.
+     */
+    readonly _system: ArrayBuffer;
+    /**
+     * Tracer reference for lifecycle hooks and event callbacks.
+     */
+    readonly tracer: TracerLifecycleHooks;
+    /**
+     * Cached TypedArray views for fast JS access.
+     */
+    private readonly _epochView;
+    private readonly _perfView;
+    /**
+     * Cached anchor hrtime as BigInt for JS timestamp fallback.
+     * Only used if NAPI addon is not available.
+     */
+    private readonly _anchorHrtimeBigInt;
+    constructor(trace_id: TraceId, anchorEpochNanos: bigint, anchorPerfNow: number, anchorHrtimeBigInt: bigint, tracer: TracerLifecycleHooks);
+    /**
+     * Epoch time in nanoseconds when trace was created.
+     */
+    get anchorEpochNanos(): bigint;
+    /**
+     * High-resolution timer anchor when trace was created.
+     */
+    get anchorPerfNow(): number;
+    /**
+     * Trace ID for this trace.
+     */
+    get trace_id(): TraceId;
+    /**
+     * Get current timestamp in nanoseconds since Unix epoch.
+     * Uses process.hrtime.bigint() for true nanosecond precision.
+     */
+    getTimestampNanos(): Nanoseconds;
+    /**
+     * Write span-start entry to buffer at row 0.
+     *
+     */
+    writeSpanStart(buffer: AnySpanBuffer, spanName: string): void;
+    /**
+     * Write span-end entry to buffer at row 1.
+     * Writes both timestamp and entry_type.
+     *
+     */
+    writeSpanEnd(buffer: AnySpanBuffer, entryType: number): void;
+    /**
+     * Write log entry: bump writeIndex, write timestamp + entry_type, return idx.
+     * SpanLogger uses returned idx for string column writes.
+     */
+    writeLogEntry(buffer: AnySpanBuffer, entryType: number): number;
+}
+/**
+ * Factory function for creating Node.js TraceRoot instances.
+ * Pass this to Tracer constructor for Node.js environments.
+ */
+export declare function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks): TraceRoot;
+//# sourceMappingURL=traceRoot.node.d.ts.map

package/dist/lib/traceRoot.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceRoot.node.d.ts","sourceRoot":"","sources":["../../src/lib/traceRoot.node.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,KAAK,UAAU,EAKf,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAQhD;;;;GAIG;AACH,qBAAa,SAAU,YAAW,UAAU;IAC1C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAEtC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;gBAG3C,QAAQ,EAAE,OAAO,EACjB,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAC1B,MAAM,EAAE,oBAAoB;IAyB9B;;OAEG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAGtB;IAED;;;OAGG;IACH,iBAAiB,IAAI,WAAW;IAMhC;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAY7D;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAK5D;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;CAOhE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAMzF"}

package/dist/lib/traceRoot.node.js

@@ -0,0 +1,133 @@
+/// <reference types="node" />
+/**
+ * TraceRoot - Node.js implementation.
+ *
+ * Uses process.hrtime.bigint() for true nanosecond precision and writes directly
+ * to SpanBuffer state from JavaScript.
+ *
+ * @module traceRoot.node
+ */
+import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import { ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_START } from './schema/systemSchema.js';
+import { createTraceId } from './traceId.js';
+import { TRACE_ROOT_ANCHOR_EPOCH_OFFSET, TRACE_ROOT_ANCHOR_PERF_OFFSET, TRACE_ROOT_TRACE_ID_LEN_OFFSET, TRACE_ROOT_TRACE_ID_OFFSET, } from './traceRoot.js';
+/** Shared TextEncoder for trace_id encoding (stateless, reusable) */
+const textEncoder = new TextEncoder();
+/** Shared TextDecoder for trace_id decoding (stateless, reusable) */
+const textDecoder = new TextDecoder();
+/**
+ * TraceRoot - Node.js implementation.
+ *
+ * Stores anchor data in _system ArrayBuffer and writes timestamps directly from JS.
+ */
+export class TraceRoot {
+    /**
+     * Raw backing buffer containing anchor timestamps and trace_id.
+     */
+    _system;
+    /**
+     * Tracer reference for lifecycle hooks and event callbacks.
+     */
+    tracer;
+    /**
+     * Cached TypedArray views for fast JS access.
+     */
+    _epochView;
+    _perfView;
+    /**
+     * Cached anchor hrtime as BigInt for JS timestamp fallback.
+     * Only used if NAPI addon is not available.
+     */
+    _anchorHrtimeBigInt;
+    constructor(trace_id, anchorEpochNanos, anchorPerfNow, anchorHrtimeBigInt, tracer) {
+        // Allocate buffer: 17 bytes header + trace_id length
+        // trace_id is validated to be ASCII (1 byte per char) so length === byte length
+        this._system = new ArrayBuffer(TRACE_ROOT_TRACE_ID_OFFSET + trace_id.length);
+        this.tracer = tracer;
+        // Create cached views (one-time allocation)
+        this._epochView = new BigInt64Array(this._system, TRACE_ROOT_ANCHOR_EPOCH_OFFSET, 1);
+        this._perfView = new Float64Array(this._system, TRACE_ROOT_ANCHOR_PERF_OFFSET, 1);
+        // Write anchor data directly
+        this._epochView[0] = anchorEpochNanos;
+        this._perfView[0] = anchorPerfNow;
+        // Keep exact monotonic anchor for JS fallback (avoid Number precision loss after ~104 days uptime)
+        this._anchorHrtimeBigInt = anchorHrtimeBigInt;
+        // Encode trace_id directly into buffer (no intermediate allocation)
+        const u8View = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET);
+        const traceIdDest = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, trace_id.length);
+        const { written } = textEncoder.encodeInto(trace_id, traceIdDest);
+        u8View[0] = written;
+    }
+    /**
+     * Epoch time in nanoseconds when trace was created.
+     */
+    get anchorEpochNanos() {
+        return this._epochView[0];
+    }
+    /**
+     * High-resolution timer anchor when trace was created.
+     */
+    get anchorPerfNow() {
+        return this._perfView[0];
+    }
+    /**
+     * Trace ID for this trace.
+     */
+    get trace_id() {
+        const len = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET, 1)[0];
+        return createTraceId(textDecoder.decode(new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, len)));
+    }
+    /**
+     * Get current timestamp in nanoseconds since Unix epoch.
+     * Uses process.hrtime.bigint() for true nanosecond precision.
+     */
+    getTimestampNanos() {
+        const currentHrtime = process.hrtime.bigint();
+        const elapsedNanos = currentHrtime - this._anchorHrtimeBigInt;
+        return Nanoseconds.unsafe(this._epochView[0] + elapsedNanos);
+    }
+    /**
+     * Write span-start entry to buffer at row 0.
+     *
+     */
+    writeSpanStart(buffer, spanName) {
+        buffer.timestamp[0] = this.getTimestampNanos();
+        buffer.entry_type[0] = ENTRY_TYPE_SPAN_START;
+        buffer.message(0, spanName);
+        // Pre-initialize row 1 as span-exception
+        buffer.entry_type[1] = ENTRY_TYPE_SPAN_EXCEPTION;
+        buffer.timestamp[1] = 0n;
+        buffer._writeIndex = 2;
+    }
+    /**
+     * Write span-end entry to buffer at row 1.
+     * Writes both timestamp and entry_type.
+     *
+     */
+    writeSpanEnd(buffer, entryType) {
+        buffer.timestamp[1] = this.getTimestampNanos();
+        buffer.entry_type[1] = entryType;
+    }
+    /**
+     * Write log entry: bump writeIndex, write timestamp + entry_type, return idx.
+     * SpanLogger uses returned idx for string column writes.
+     */
+    writeLogEntry(buffer, entryType) {
+        const idx = buffer._writeIndex;
+        buffer.timestamp[idx] = this.getTimestampNanos();
+        buffer.entry_type[idx] = entryType;
+        buffer._writeIndex = idx + 1;
+        return idx;
+    }
+}
+/**
+ * Factory function for creating Node.js TraceRoot instances.
+ * Pass this to Tracer constructor for Node.js environments.
+ */
+export function createTraceRoot(trace_id, tracer) {
+    const anchorEpochNanos = BigInt(Date.now()) * 1000000n;
+    const anchorHrtimeBigInt = process.hrtime.bigint();
+    // Store as number for NAPI to read as f64
+    const anchorPerfNow = Number(anchorHrtimeBigInt);
+    return new TraceRoot(createTraceId(trace_id), anchorEpochNanos, anchorPerfNow, anchorHrtimeBigInt, tracer);
+}

package/dist/lib/traceRoot.universal.d.ts

@@ -0,0 +1,3 @@
+import type { TraceRootFactory } from './traceRoot.js';
+export declare const createTraceRoot: TraceRootFactory;
+//# sourceMappingURL=traceRoot.universal.d.ts.map

package/dist/lib/traceRoot.universal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceRoot.universal.d.ts","sourceRoot":"","sources":["../../src/lib/traceRoot.universal.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKvD,eAAO,MAAM,eAAe,EAAE,gBAC4E,CAAC"}

package/dist/lib/traceRoot.universal.js

@@ -0,0 +1,17 @@
+/// <reference types="node" />
+/**
+ * TraceRoot - Universal implementation with runtime platform detection.
+ *
+ * Selects between Node.js (nanosecond hrtime) and ES (performance.now()) based
+ * on whether process.hrtime.bigint is available at runtime.
+ *
+ * Both modules are safe to import — platform-specific calls (process.hrtime.bigint(),
+ * NAPI addon) happen inside the factory function, not at module scope.
+ *
+ * @module traceRoot.universal
+ */
+import { createTraceRoot as esFactory } from './traceRoot.es.js';
+import { createTraceRoot as nodeFactory } from './traceRoot.node.js';
+// Node/Bun → nanosecond precision via hrtime.bigint()
+// CF Workers/browsers → performance.now() microsecond precision
+export const createTraceRoot = typeof process !== 'undefined' && typeof process.hrtime?.bigint === 'function' ? nodeFactory : esFactory;

package/dist/lib/tracer.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Tracer - Abstract base class for trace collection
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md:
+ * - Tracer owns trace() function for creating root spans
+ * - Collects SpanBuffers in pendingBuffers array
+ * - Subclasses implement flush() to define persistence strategy
+ *
+ * ## Design Philosophy
+ *
+ * Tracer separates two concerns:
+ * 1. **BufferStrategy**: HOW buffers are allocated (JS TypedArrays vs WASM memory)
+ * 2. **Sink behavior** (lifecycle hooks): WHAT happens with completed buffers
+ *
+ * Tracer is ABSTRACT - subclasses implement lifecycle hooks:
+ * - `onTraceEnd()` - called when root trace completes
+ * - `onSpanEnd()` - called when child span completes
+ * - `flush()` - optional, for batching strategies
+ *
+ * BufferStrategy is INJECTED via constructor:
+ * - `JsBufferStrategy` - GC-managed TypedArrays, zero-copy Arrow
+ * - `WasmBufferStrategy` - WASM memory with freelist, Arrow built in WASM
+ *
+ * The sink controls WHEN to convert/release:
+ * - StdioTracer: prints then releases immediately
+ * - TestTracer: holds buffers until clear()
+ * - SqsTracer: accumulates, converts on flush(), then releases
+ *
+ * @example
+ * ```typescript
+ * // Concrete implementation - Cloudflare Queue
+ * class QueueTracer extends Tracer {
+ *   constructor(binding, strategy, options, private queue: Queue) {
+ *     super(binding, strategy, options);
+ *   }
+ *
+ *   async flush() {
+ *     const buffers = [...this.pending];
+ *     this.pending.length = 0;
+ *     for (const buffer of buffers) {
+ *       const table = await this.bufferStrategy.toArrowTable(buffer);
+ *       await this.queue.send(table);
+ *       this.bufferStrategy.releaseBuffer(buffer);
+ *     }
+ *   }
+ * }
+ *
+ * // Usage
+ * const ctx = defineOpContext({ logSchema, ctx: { env: null as Env } });
+ * const strategy = new JsBufferStrategy();
+ * const { trace, flush } = new QueueTracer(ctx, strategy, options, env.TRACES);
+ * await trace('fetch', { env: myEnv }, async (ctx) => {
+ *   ctx.tag.userId('user-123');
+ *   return ctx.ok('done');
+ * });
+ * executionContext.waitUntil(flush());
+ * ```
+ *
+ * @module tracer
+ */
+import type { BufferStrategy } from './bufferStrategy.js';
+import { Op } from './op.js';
+import type { OpContext, OpContextBinding, OpContextOf, SpanContext } from './opContext/types.js';
+import { type Result } from './result.js';
+import { type FlagEvaluator } from './schema/evaluator.js';
+import { type TraceId } from './traceId.js';
+import type { TraceRootFactory } from './traceRoot.js';
+import type { SpanBuffer } from './types.js';
+/**
+ * Base tracer options (can be extended by subclasses)
+ *
+ * Flag evaluator typing is intentionally loose - the evaluator just needs to
+ * implement the FlagEvaluator interface. Type safety for flag access comes from
+ * the OpContext's flags schema, not from the evaluator's type parameter.
+ */
+export interface TracerOptions<T extends import('./schema/LogSchema.js').LogSchema = import('./schema/LogSchema.js').LogSchema> {
+    /**
+     * Buffer strategy for memory management and Arrow conversion.
+     *
+     * Controls HOW buffers are allocated:
+     * - JsBufferStrategy: GC-managed TypedArrays, zero-copy Arrow
+     * - WasmBufferStrategy: WASM memory with freelist, Arrow built in WASM
+     */
+    bufferStrategy: BufferStrategy<T>;
+    /**
+     * Factory for creating platform-specific TraceRoot instances.
+     * Import from '@smoothbricks/lmao/node' or '@smoothbricks/lmao/es'.
+     */
+    createTraceRoot: TraceRootFactory;
+    /** Feature flag evaluator - provides flag values at runtime */
+    flagEvaluator?: FlagEvaluator<OpContext>;
+}
+/**
+ * Trace overrides - userCtx values plus optional trace_id.
+ *
+ * Like span() overrides, but with optional trace_id for distributed tracing.
+ * The trace_id must be a branded TraceId (use createTraceId() to validate).
+ *
+ * When UserCtx is empty (Record<string, never>), only trace_id is available.
+ * Otherwise, allows partial userCtx values plus trace_id.
+ *
+ * We use a conditional type to avoid issues with Partial<Record<string, never>>
+ * which creates an index signature where all values must be undefined.
+ *
+ * @typeParam UserCtx - User context type from OpContext
+ */
+export type TraceOverrides<UserCtx> = [UserCtx] extends [Record<string, never>] ? {
+    trace_id?: TraceId;
+} : Partial<UserCtx> & {
+    trace_id?: TraceId;
+};
+/**
+ * TraceFn - overloaded trace creation function.
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md:
+ * Creates root spans with type-safe Op invocation or inline closures.
+ * Mirrors SpanFn but for root traces.
+ *
+ * Pattern:
+ * - With/without line numbers (transformer injection)
+ * - Always requires name (unlike span which can use op.metadata.name)
+ * - With/without overrides (userCtx + optional trace_id)
+ * - With/without Op arguments (0-8 args supported)
+ *
+ * @template Ctx - Full OpContext type from the tracer's binding
+ */
+export type TraceFn<Ctx extends OpContext> = {
+    /**
+     * Trace Op with line + name + args.
+     */
+    <S, E, Args extends unknown[]>(line: number, name: string, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    /**
+     * Trace Op with line + name + overrides + args.
+     */
+    <S, E, Args extends unknown[]>(line: number, name: string, overrides: TraceOverrides<Ctx['userCtx']>, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    /**
+     * Trace inline function with line + name.
+     */
+    <R>(line: number, name: string, fn: (ctx: SpanContext<Ctx>) => R): R;
+    /**
+     * Trace inline function with line + name + overrides.
+     */
+    <R>(line: number, name: string, overrides: TraceOverrides<Ctx['userCtx']>, fn: (ctx: SpanContext<Ctx>) => R): R;
+    /**
+     * Trace Op with name + args.
+     */
+    <S, E, Args extends unknown[]>(name: string, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    /**
+     * Trace Op with name + overrides + args.
+     */
+    <S, E, Args extends unknown[]>(name: string, overrides: TraceOverrides<Ctx['userCtx']>, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    /**
+     * Trace inline function with name.
+     */
+    <R>(name: string, fn: (ctx: SpanContext<Ctx>) => R): R;
+    /**
+     * Trace inline function with name + overrides.
+     */
+    <R>(name: string, overrides: TraceOverrides<Ctx['userCtx']>, fn: (ctx: SpanContext<Ctx>) => R): R;
+};
+/**
+ * Tracer - Abstract base class for trace collection
+ *
+ * Provides trace execution with lifecycle hooks for buffer management.
+ * Subclasses implement onTraceStart, onTraceEnd, onSpanStart, onSpanEnd to define
+ * how spans are collected and processed.
+ *
+ * BufferStrategy is injected to control memory management and Arrow conversion.
+ *
+ * @typeParam B - OpContextBinding type (inferred from constructor argument)
+ */
+export declare abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
+    private readonly logBinding;
+    private readonly SpanContextClass;
+    private readonly flagEvaluator;
+    private readonly ctxDefaults;
+    private readonly deps;
+    private readonly createTraceRoot;
+    /**
+     * Buffer strategy for memory management and Arrow conversion.
+     * Public because SpanContext needs access for child span creation.
+     * Also accessible to subclasses for toArrowTable/releaseBuffer calls.
+     */
+    readonly bufferStrategy: BufferStrategy<B['logBinding']['logSchema']>;
+    constructor(binding: B, options: TracerOptions<B['logBinding']['logSchema']>);
+    private _createFlagEvaluator;
+    /**
+     * Called when a root trace starts (before fn execution).
+     * Only called for root spans created via trace(), not child spans.
+     * Subclasses implement to handle trace lifecycle events (e.g., collect for batching).
+     */
+    abstract onTraceStart(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    /**
+     * Called when a root trace ends (after fn completes, in finally).
+     * Always called, even if fn threw an exception.
+     * Only called for root spans created via trace(), not child spans.
+     * Subclasses implement to handle trace completion (e.g., queue for sending).
+     */
+    abstract onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    /**
+     * Called when a child span starts (before fn execution).
+     * Only called for child spans created via ctx.span(), not root traces.
+     * Subclasses implement if child span lifecycle needs special handling.
+     */
+    abstract onSpanStart(childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    /**
+     * Called when a child span ends (after fn completes, in finally).
+     * Always called, even if fn threw an exception.
+     * Only called for child spans created via ctx.span(), not root traces.
+     * Subclasses implement if child span lifecycle needs special handling.
+     */
+    abstract onSpanEnd(childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    /**
+     * Called before stats are reset during capacity tuning.
+     * Allows tracer to capture stats for observability before they're lost.
+     *
+     * The buffer provides all necessary context:
+     * - buffer._stats → SpanBufferStats about to be reset
+     * - buffer._opMetadata → which Op/module these stats belong to
+     * - buffer.constructor → SpanBufferClass (schema info)
+     *
+     * @param buffer - The buffer that triggered overflow
+     */
+    abstract onStatsWillResetFor(buffer: SpanBuffer<B['logBinding']['logSchema']>): void;
+    /**
+     * Flush any pending data. Default is no-op.
+     * Subclasses override if they batch data (e.g., collecting in onTraceEnd then flushing here).
+     */
+    flush(): Promise<void>;
+    /**
+     * Polymorphic trace dispatcher.
+     *
+     * Parses overloaded arguments and dispatches to monomorphic methods.
+     * Uses argument type detection for clean pattern matching.
+     *
+     * Patterns supported:
+     * - (name, fn)
+     * - (name, overrides, fn)
+     * - (name, op, ...args)
+     * - (name, overrides, op, ...args)
+     * - Plus line number prefix variants for transformer
+     *
+     * @see TraceFn for type-level documentation of all overloads
+     */
+    trace<S, E, Args extends unknown[]>(line: number, name: string, op: Op<OpContextOf<B>, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    trace<S, E, Args extends unknown[]>(line: number, name: string, overrides: TraceOverrides<OpContextOf<B>['userCtx']>, op: Op<OpContextOf<B>, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    trace<R>(line: number, name: string, fn: (ctx: SpanContext<OpContextOf<B>>) => R): R;
+    trace<R>(line: number, name: string, overrides: TraceOverrides<OpContextOf<B>['userCtx']>, fn: (ctx: SpanContext<OpContextOf<B>>) => R): R;
+    trace<S, E, Args extends unknown[]>(name: string, op: Op<OpContextOf<B>, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    trace<S, E, Args extends unknown[]>(name: string, overrides: TraceOverrides<OpContextOf<B>['userCtx']>, op: Op<OpContextOf<B>, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    trace<R>(name: string, fn: (ctx: SpanContext<OpContextOf<B>>) => R): R;
+    trace<R>(name: string, overrides: TraceOverrides<OpContextOf<B>['userCtx']>, fn: (ctx: SpanContext<OpContextOf<B>>) => R): R;
+    /**
+     * Execute an Op as a root trace (internal monomorphic method).
+     * Supports 0-8 arguments. The transformer rewrites trace() calls to this.
+     */
+    private _trace_op;
+    private _trace_unknown_op;
+    /**
+     * Execute a function as a root trace (internal monomorphic method).
+     * The transformer rewrites trace() calls to this.
+     */
+    private _trace_fn;
+    private _trace_unknown_fn;
+    /**
+     * Execute an Op as a root trace (monomorphic - for transformer optimization).
+     * Public API for transformer to call directly, bypassing polymorphic dispatch.
+     */
+    trace_op<S, E, Args extends unknown[]>(line: number, name: string, overrides: TraceOverrides<OpContextOf<B>['userCtx']>, op: Op<OpContextOf<B>, Args, S, E>, ...opArgs: Args): Result<S, E> | Promise<Result<S, E>>;
+    /**
+     * Execute a function as a root trace (monomorphic - for transformer optimization).
+     * Public API for transformer to call directly, bypassing polymorphic dispatch.
+     */
+    trace_fn<R>(line: number, name: string, overrides: TraceOverrides<OpContextOf<B>['userCtx']>, fn: (ctx: SpanContext<OpContextOf<B>>) => Promise<R>): Promise<R>;
+    trace_fn<R>(line: number, name: string, overrides: TraceOverrides<OpContextOf<B>['userCtx']>, fn: (ctx: SpanContext<OpContextOf<B>>) => R): R;
+    private _createRootContext;
+    /**
+     * Validate null-sentinel required fields and merge with provided overrides.
+     *
+     * Per the ctx config pattern:
+     * - Properties with null values in ctxDefaults must be provided in overrides
+     * - Properties with default values can optionally be overridden
+     * - undefined is allowed for optional fields
+     */
+    private _resolveUserContext;
+    /**
+     * Execute function with context and handle span-ok/span-err/span-exception writes
+     * Promise-agnostic: returns sync for sync fn, Promise for async fn
+     *
+     * Writes span-end entry (entry_type, timestamp, error_code) and applies deferred tags
+     * when the function returns an Ok/Err result.
+     */
+    private _executeResultWithContext;
+    private _executeUnknownWithContext;
+}
+//# sourceMappingURL=tracer.d.ts.map

package/dist/lib/tracer.d.ts.map

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