@smoothbricks/lmao 0.1.0

package/dist/lib/wasm/wasmSpanBuffer.js

@@ -0,0 +1,772 @@
+import { getSchemaType } from '@smoothbricks/arrow-builder';
+import { checkCapacityTuning } from '../capacityTuning.js';
+function getFieldEager(value) {
+    return typeof value === 'object' && value !== null && Reflect.get(value, '__eager') === true;
+}
+function getFieldEnumValues(value) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const enumValues = Reflect.get(value, '__enum_values');
+    return Array.isArray(enumValues) ? enumValues : undefined;
+}
+function isColumnValueType(value) {
+    return value === undefined || Array.isArray(value) || ArrayBuffer.isView(value);
+}
+function getFreeMethod(sizeClass) {
+    switch (sizeClass) {
+        case '1b':
+            return 'free1B';
+        case '4b':
+            return 'free4B';
+        case '8b':
+            return 'free8B';
+    }
+}
+function isWasmSpanBufferConstructor(value) {
+    return (typeof value === 'function' &&
+        typeof Reflect.get(value, 'schema') === 'object' &&
+        Reflect.get(value, 'schema') !== null &&
+        typeof Reflect.get(value, 'stats') === 'object' &&
+        Reflect.get(value, 'stats') !== null);
+}
+export function isWasmSpanBufferInstance(value) {
+    return typeof value === 'object' && value !== null && typeof Reflect.get(value, '_systemPtr') === 'number';
+}
+function getWasmSpanBufferConstructor(instance) {
+    if (!isWasmSpanBufferConstructor(instance.constructor)) {
+        throw new Error('Expected generated WasmSpanBuffer constructor');
+    }
+    return instance.constructor;
+}
+function isWasmSpanBufferFactory(value) {
+    return typeof value === 'function';
+}
+/**
+ * Build column metadata array from schema.
+ * Maps each schema field to its storage characteristics.
+ */
+function buildColumnMeta(schema) {
+    const result = [];
+    const fields = schema.fields;
+    let columnIndex = 0;
+    for (const name of schema._columnNames) {
+        const field = fields[name];
+        const schemaType = getSchemaType(field);
+        const isEager = getFieldEager(field);
+        const enumValues = getFieldEnumValues(field);
+        let sizeClass;
+        switch (schemaType) {
+            case 'enum':
+            case 'boolean':
+                sizeClass = '1b';
+                break;
+            case 'number':
+            case 'bigUint64':
+                sizeClass = '8b';
+                break;
+            case 'category':
+            case 'text':
+                sizeClass = 'string';
+                break;
+            default:
+                sizeClass = '8b'; // Default to largest for unknown types
+        }
+        result.push({
+            name,
+            sizeClass,
+            schemaType: schemaType ?? 'unknown',
+            columnIndex,
+            isEager,
+            enumValues,
+        });
+        columnIndex++;
+    }
+    return result;
+}
+// =============================================================================
+// Common WasmSpanBuffer Methods (shared via prototype)
+// =============================================================================
+/**
+ * Get timestamp column view from WASM memory.
+ * Assigned to prototype after class generation.
+ */
+function wasmGetTimestamp() {
+    return new BigInt64Array(this._allocator.memory.buffer, this._systemPtr, this._capacity);
+}
+/**
+ * Get entry_type column view from WASM memory.
+ * Assigned to prototype after class generation.
+ */
+function wasmGetEntryType() {
+    return new Uint8Array(this._allocator.memory.buffer, this._systemPtr + this._capacity * 8, this._capacity);
+}
+/**
+ * Get writeIndex from WASM identity block.
+ */
+function wasmGetWriteIndex() {
+    return this._allocator.readWriteIndex(this._identityPtr);
+}
+/**
+ * Set writeIndex in WASM identity block.
+ */
+function wasmSetWriteIndex(value) {
+    new DataView(this._allocator.memory.buffer).setUint32(this._identityPtr, value, true);
+}
+/**
+ * Get trace_id from WASM identity block.
+ */
+function wasmGetTraceId() {
+    const len = this._allocator.readIdentityTraceIdLen(this._identityPtr);
+    if (len === 0) {
+        let p = this._parent;
+        while (p?._parent)
+            p = p._parent;
+        return p ? p.trace_id : '';
+    }
+    const traceIdPtr = this._allocator.getIdentityTraceIdPtr(this._identityPtr);
+    return new TextDecoder().decode(new Uint8Array(this._allocator.memory.buffer, traceIdPtr, len));
+}
+function wasmGetSpanStartTime() {
+    return this.timestamp[0];
+}
+function wasmGetLastLoggedTime() {
+    const chain = [];
+    let current = this;
+    while (current) {
+        chain.push(current);
+        current = current._overflow;
+    }
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const buffer = chain[i];
+        for (let row = buffer._writeIndex - 1; row >= 0; row--) {
+            const ts = buffer.timestamp[row];
+            if (ts !== 0n) {
+                return ts;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Get thread_id from WASM identity block.
+ */
+function wasmGetThreadId() {
+    const high = this._allocator.getThreadIdHigh();
+    const low = this._allocator.getThreadIdLow();
+    return (BigInt(high) << 32n) | BigInt(low);
+}
+/**
+ * Get span_id from WASM identity block.
+ */
+function wasmGetSpanId() {
+    return this._allocator.readIdentitySpanId(this._identityPtr);
+}
+/**
+ * Get parent_thread_id.
+ */
+function wasmGetParentThreadId() {
+    return this._parent ? this._parent.thread_id : 0n;
+}
+/**
+ * Get parent_span_id.
+ */
+function wasmGetParentSpanId() {
+    return this._parent ? this._parent.span_id : 0;
+}
+/**
+ * Check if buffer has parent.
+ */
+function wasmGetHasParent() {
+    return this._parent !== null;
+}
+/**
+ * Message column setter.
+ */
+function wasmMessage(idx, value) {
+    this._message[idx] = value;
+    return this;
+}
+/**
+ * Get message column values.
+ */
+function wasmGetMessageValues() {
+    return this._message;
+}
+/**
+ * Get message column nulls (always undefined for eager column).
+ */
+function wasmGetMessageNulls() {
+    return undefined;
+}
+/**
+ * Free all WASM memory for this buffer.
+ */
+function wasmFree() {
+    // Free identity block
+    this._allocator.freeIdentity(this._identityPtr);
+    // Free system block
+    this._allocator.freeSpanSystem(this._systemPtr);
+    // Free column blocks
+    const columnMeta = buildColumnMeta(this._logSchema);
+    for (const col of columnMeta) {
+        if (col.sizeClass !== 'string' && this._columnPtrs[col.columnIndex] >= 0) {
+            const freeMethod = getFreeMethod(col.sizeClass);
+            this._allocator[freeMethod](this._columnPtrs[col.columnIndex]);
+        }
+    }
+}
+/**
+ * Check if column is allocated.
+ */
+function wasmIsColumnAllocated(columnIndex) {
+    return this._columnPtrs[columnIndex] >= 0;
+}
+/**
+ * Get column values if allocated.
+ */
+function wasmGetColumnIfAllocated(columnName) {
+    const idx = this._logSchema._columnNames.indexOf(columnName);
+    if (idx === -1)
+        return undefined;
+    const getter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(this), `${columnName}_values`);
+    if (getter?.get) {
+        const value = getter.get.call(this);
+        return isColumnValueType(value) ? value : undefined;
+    }
+    return undefined;
+}
+/**
+ * Get column nulls if allocated.
+ */
+function wasmGetNullsIfAllocated(columnName) {
+    const getter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(this), `${columnName}_nulls`);
+    if (getter?.get) {
+        return getter.get.call(this);
+    }
+    return undefined;
+}
+/**
+ * Get system ArrayBuffer for compatibility with AnySpanBuffer.
+ * WASM uses shared memory, so this returns the entire WASM memory buffer.
+ */
+function wasmGetSystem() {
+    return this._allocator.memory.buffer;
+}
+/**
+ * Get identity Uint8Array for compatibility with AnySpanBuffer.
+ * Returns a view of the identity block (48 bytes) in WASM memory.
+ */
+function wasmGetIdentity() {
+    // Identity block is 48 bytes: writeIndex(4) + reserved(4) + span_id(4) + trace_id_len(1) + trace_id(up to 35)
+    return new Uint8Array(this._allocator.memory.buffer, this._identityPtr, 48);
+}
+/**
+ * Get or create overflow buffer.
+ */
+function wasmGetOrCreateOverflow() {
+    if (this._overflow)
+        return this._overflow;
+    const tracer = this._traceRoot.tracer;
+    tracer.onStatsWillResetFor(this);
+    checkCapacityTuning(getWasmSpanBufferConstructor(this).stats);
+    // WasmSpanBufferInstance extends AnySpanBuffer and has all SpanBuffer properties at runtime
+    const overflow = tracer.bufferStrategy.createOverflowBuffer(this);
+    if (!isWasmSpanBufferInstance(overflow)) {
+        throw new Error('Expected overflow buffer to be WASM-backed');
+    }
+    return overflow;
+}
+/**
+ * Get _stats property.
+ */
+function wasmGetStats() {
+    return getWasmSpanBufferConstructor(this).stats;
+}
+/**
+ * Get _columns property.
+ */
+function wasmGetColumns() {
+    return getWasmSpanBufferConstructor(this).schema._columns;
+}
+/**
+ * Custom inspect for debugging.
+ */
+function wasmInspect() {
+    return `WasmSpanBuffer { _writeIndex: ${this._writeIndex}, _capacity: ${this._capacity}, trace_id: ${this.trace_id ?? 'N/A'}, _systemPtr: ${this._systemPtr} }`;
+}
+// =============================================================================
+// Code Generation Helpers
+// =============================================================================
+/**
+ * Generate eager column initialization code for constructor.
+ * Eager columns are pre-allocated, lazy columns start as undefined/-1.
+ */
+function generateEagerColumnInit(columnMeta) {
+    const lines = [];
+    for (const col of columnMeta) {
+        if (col.name === 'message')
+            continue; // Message handled separately
+        if (col.sizeClass === 'string') {
+            if (col.isEager) {
+                lines.push(`this._${col.name}_values = new Array(this._capacity);`);
+            }
+            else {
+                lines.push(`this._${col.name}_values = undefined;`);
+                lines.push(`this._${col.name}_nulls = undefined;`);
+            }
+        }
+        else if (col.isEager) {
+            lines.push(`this._columnPtrs[${col.columnIndex}] = this._allocator.alloc${col.sizeClass.toUpperCase()}();`);
+        }
+    }
+    return lines.join('\n    ');
+}
+/**
+ * Generate setter method for a numeric column (stored in WASM).
+ * Calls WASM exports directly for hot path optimization.
+ */
+function generateNumericSetter(col) {
+    const allocMethod = `alloc${col.sizeClass.toUpperCase()}`;
+    // Map to WASM export names
+    const writeExportName = col.schemaType === 'number' || col.schemaType === 'bigUint64'
+        ? 'write_col_f64'
+        : col.sizeClass === '1b'
+            ? 'write_col_u8'
+            : col.sizeClass === '4b'
+                ? 'write_col_u32'
+                : 'write_col_f64';
+    if (col.isEager) {
+        // Eager: column is pre-allocated, just write value (call WASM export directly)
+        return `${col.name}(idx, value) {
+    const ptr = this._columnPtrs[${col.columnIndex}];
+    this._allocator.exports.${writeExportName}(ptr, idx, value, this._capacity);
+    return this;
+  }`;
+    }
+    // Lazy: allocate on first write (call WASM export directly)
+    return `${col.name}(idx, value) {
+    let ptr = this._columnPtrs[${col.columnIndex}];
+    if (ptr < 0) {
+      ptr = this._allocator.${allocMethod}();
+      this._columnPtrs[${col.columnIndex}] = ptr;
+    }
+    this._allocator.exports.${writeExportName}(ptr, idx, value, this._capacity);
+    return this;
+  }`;
+}
+/**
+ * Generate getter for numeric column values (creates view on demand).
+ */
+function generateNumericValuesGetter(col) {
+    const arrayType = col.schemaType === 'number'
+        ? 'Float64Array'
+        : col.schemaType === 'bigUint64'
+            ? 'BigUint64Array'
+            : col.sizeClass === '1b'
+                ? 'Uint8Array'
+                : col.sizeClass === '4b'
+                    ? 'Uint32Array'
+                    : 'Float64Array';
+    const bytesPerElement = col.sizeClass === '1b' ? 1 : col.sizeClass === '4b' ? 4 : 8;
+    return `get ${col.name}_values() {
+    const ptr = this._columnPtrs[${col.columnIndex}];
+    if (ptr < 0) return ${col.isEager ? 'null' : 'undefined'};
+    const nullBitmapSize = Math.ceil(this._capacity / 8);
+    const valueOffset = ptr + nullBitmapSize;
+    // Align offset for typed array
+    const alignedOffset = (valueOffset + ${bytesPerElement - 1}) & ~${bytesPerElement - 1};
+    return new ${arrayType}(
+      this._allocator.memory.buffer,
+      alignedOffset,
+      this._capacity
+    );
+  }`;
+}
+/**
+ * Generate getter for numeric column nulls bitmap.
+ */
+function generateNumericNullsGetter(col) {
+    if (col.isEager) {
+        // Eager columns don't have null bitmaps
+        return `get ${col.name}_nulls() {
+    return undefined;
+  }`;
+    }
+    return `get ${col.name}_nulls() {
+    const ptr = this._columnPtrs[${col.columnIndex}];
+    if (ptr < 0) return undefined;
+    const nullBitmapSize = Math.ceil(this._capacity / 8);
+    return new Uint8Array(
+      this._allocator.memory.buffer,
+      ptr,
+      nullBitmapSize
+    );
+  }`;
+}
+/**
+ * Generate setter method for a string column (stored in JS).
+ */
+function generateStringSetter(col) {
+    if (col.isEager) {
+        return `${col.name}(idx, value) {
+    this._${col.name}_values[idx] = value;
+    return this;
+  }`;
+    }
+    // Lazy string column: allocate arrays on first write
+    return `${col.name}(idx, value) {
+    if (this._${col.name}_values === undefined) {
+      this._${col.name}_values = new Array(this._capacity);
+      const nullBitmapSize = Math.ceil(this._capacity / 8);
+      this._${col.name}_nulls = new Uint8Array(nullBitmapSize);
+    }
+    if (value == null) {
+      // Clear validity bit
+      this._${col.name}_nulls[idx >>> 3] &= ~(1 << (idx & 7));
+    } else {
+      this._${col.name}_values[idx] = value;
+      // Set validity bit
+      this._${col.name}_nulls[idx >>> 3] |= (1 << (idx & 7));
+    }
+    return this;
+  }`;
+}
+/**
+ * Generate getter for string column values.
+ */
+function generateStringValuesGetter(col) {
+    if (col.isEager) {
+        return `get ${col.name}_values() {
+    return this._${col.name}_values;
+  }`;
+    }
+    return `get ${col.name}_values() {
+    return this._${col.name}_values;
+  }`;
+}
+/**
+ * Generate getter for string column nulls.
+ */
+function generateStringNullsGetter(col) {
+    if (col.isEager) {
+        return `get ${col.name}_nulls() {
+    return undefined;
+  }`;
+    }
+    return `get ${col.name}_nulls() {
+    return this._${col.name}_nulls;
+  }`;
+}
+/**
+ * Generate column methods for all schema columns.
+ * Note: 'message' column is handled specially by generateMessageMethods() and excluded here.
+ */
+function generateColumnMethods(columnMeta) {
+    const methods = [];
+    for (const col of columnMeta) {
+        // Skip 'message' - handled specially by generateMessageMethods()
+        if (col.name === 'message') {
+            continue;
+        }
+        if (col.sizeClass === 'string') {
+            methods.push(generateStringSetter(col));
+            methods.push(generateStringValuesGetter(col));
+            methods.push(generateStringNullsGetter(col));
+        }
+        else {
+            methods.push(generateNumericSetter(col));
+            methods.push(generateNumericValuesGetter(col));
+            methods.push(generateNumericNullsGetter(col));
+        }
+    }
+    return methods.join('\n\n  ');
+}
+// =============================================================================
+// Class Cache and Generation
+// =============================================================================
+/**
+ * Cache for generated WASM SpanBuffer classes.
+ * Key is the schema object reference (WeakMap for GC).
+ */
+const wasmSpanBufferClassCache = new WeakMap();
+/**
+ * Generate a WASM SpanBuffer class for the given schema.
+ *
+ * Generates minimal constructor + column methods, then assigns common methods to prototype.
+ *
+ * @param schema - LogSchema defining the buffer structure
+ * @returns WasmSpanBufferConstructor for creating buffer instances
+ */
+export function getWasmSpanBufferClass(schema) {
+    const cached = wasmSpanBufferClassCache.get(schema);
+    if (cached) {
+        return cached;
+    }
+    // Pre-compute column metadata
+    const columnMeta = buildColumnMeta(schema);
+    // Generate ONLY schema-specific code (constructor + column methods)
+    const classCode = `
+class WasmSpanBuffer {
+  constructor(opts) {
+    // Store allocator and capacity
+    this._allocator = opts.allocator;
+    this._capacity = opts.capacity;
+    this._logSchema = opts.logSchema;
+
+    // Allocate identity block from WASM (root has trace_id, child does not)
+    if (opts.trace_id) {
+      const traceIdBytes = new TextEncoder().encode(opts.trace_id);
+      const packed = opts.allocator.allocIdentityRootForJsWrite(traceIdBytes.length);
+      this._identityPtr = Number(packed >> 32n);
+      const traceIdOffset = Number(packed & 0xFFFFFFFFn);
+      new Uint8Array(opts.allocator.memory.buffer).set(traceIdBytes, traceIdOffset);
+    } else {
+      this._identityPtr = opts.allocator.allocIdentityChild();
+    }
+
+    // Allocate system block from WASM
+    this._systemPtr = opts.allocator.allocSpanSystem();
+
+    // Initialize column pointers as unallocated (-1)
+    this._columnPtrs = new Int32Array(${columnMeta.length}).fill(-1);
+
+    // Tree structure
+    this._parent = null;
+    this._children = [];
+    this._overflow = null;
+
+    // Assign context properties from opts
+    this._traceRoot = opts._traceRoot;
+    this._scopeValues = opts._scopeValues;
+    this._opMetadata = opts._opMetadata;
+    this._callsiteMetadata = opts._callsiteMetadata;
+
+    // Initialize message array
+    this._message = new Array(opts.capacity);
+
+    // Initialize eager columns
+    ${generateEagerColumnInit(columnMeta)}
+  }
+
+  // Schema-specific column methods (ONLY part that differs per schema)
+  ${generateColumnMethods(columnMeta)}
+}
+
+return WasmSpanBuffer;
+`;
+    // Create the class using Function constructor
+    const factory = new Function(classCode);
+    if (!isWasmSpanBufferFactory(factory)) {
+        throw new Error('Expected WasmSpanBuffer factory function');
+    }
+    const WasmSpanBufferClass = factory();
+    // Assign common methods to prototype (shared by all schemas)
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'timestamp', {
+        get: wasmGetTimestamp,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'entry_type', {
+        get: wasmGetEntryType,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_writeIndex', {
+        get: wasmGetWriteIndex,
+        set: wasmSetWriteIndex,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'trace_id', {
+        get: wasmGetTraceId,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'thread_id', {
+        get: wasmGetThreadId,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'span_id', {
+        get: wasmGetSpanId,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'parent_thread_id', {
+        get: wasmGetParentThreadId,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'parent_span_id', {
+        get: wasmGetParentSpanId,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_hasParent', {
+        get: wasmGetHasParent,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'message_values', {
+        get: wasmGetMessageValues,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, 'message_nulls', {
+        get: wasmGetMessageNulls,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_stats', {
+        get: wasmGetStats,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_columns', {
+        get: wasmGetColumns,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_spanStartTime', {
+        get: wasmGetSpanStartTime,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_lastLoggedTime', {
+        get: wasmGetLastLoggedTime,
+        enumerable: true,
+        configurable: true,
+    });
+    // Assign compatibility getters for AnySpanBuffer interface
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_system', {
+        get: wasmGetSystem,
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(WasmSpanBufferClass.prototype, '_identity', {
+        get: wasmGetIdentity,
+        enumerable: true,
+        configurable: true,
+    });
+    WasmSpanBufferClass.prototype.message = wasmMessage;
+    WasmSpanBufferClass.prototype.free = wasmFree;
+    WasmSpanBufferClass.prototype.isColumnAllocated = wasmIsColumnAllocated;
+    WasmSpanBufferClass.prototype.getColumnIfAllocated = wasmGetColumnIfAllocated;
+    WasmSpanBufferClass.prototype.getNullsIfAllocated = wasmGetNullsIfAllocated;
+    WasmSpanBufferClass.prototype.getOrCreateOverflow = wasmGetOrCreateOverflow;
+    WasmSpanBufferClass.prototype[Symbol.for('nodejs.util.inspect.custom')] = wasmInspect;
+    // Add static schema property
+    Object.defineProperty(WasmSpanBufferClass, 'schema', {
+        value: schema,
+        writable: false,
+        enumerable: true,
+        configurable: false,
+    });
+    // Add static stats property (required by SpanContext and arrow-builder's ColumnWriter)
+    // This matches the structure in spanBuffer.ts
+    // IMPORTANT: stats object itself must be writable so totalWrites++ and spansCreated++ can modify it
+    const statsObject = {
+        capacity: 64, // Default capacity, will be overridden by allocator
+        totalWrites: 0,
+        spansCreated: 0,
+    };
+    Object.defineProperty(WasmSpanBufferClass, 'stats', {
+        value: statsObject,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+    // Cache the class
+    wasmSpanBufferClassCache.set(schema, WasmSpanBufferClass);
+    return WasmSpanBufferClass;
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create a WASM SpanBuffer instance.
+ *
+ * @param schema - LogSchema defining the buffer structure
+ * @param opts - Options for buffer creation
+ * @param _traceRoot - Trace root context
+ * @param _scopeValues - Scope values for this span
+ * @param _opMetadata - Op metadata for attribution
+ * @param _callsiteMetadata - Callsite metadata for attribution
+ * @returns WasmSpanBufferInstance
+ */
+export function createWasmSpanBuffer(schema, opts, _traceRoot, _scopeValues, _opMetadata, _callsiteMetadata) {
+    const WasmSpanBufferClass = getWasmSpanBufferClass(schema);
+    return new WasmSpanBufferClass({
+        ...opts,
+        logSchema: schema,
+        _traceRoot,
+        _scopeValues,
+        _opMetadata,
+        _callsiteMetadata,
+    });
+}
+/**
+ * Create a child WASM SpanBuffer linked to a parent.
+ *
+ * For cross-library calls, the child buffer may use a different schema than the parent.
+ * Pass the schema option to use a different schema.
+ *
+ * @param parent - Parent WASM SpanBuffer
+ * @param opts - Options for child buffer creation (schema is optional, defaults to parent's)
+ * @param _traceRoot - Trace root context
+ * @param _scopeValues - Scope values for this span
+ * @param _opMetadata - Op metadata for attribution
+ * @param _callsiteMetadata - Callsite metadata for attribution
+ * @returns WasmSpanBufferInstance linked to parent
+ */
+export function createWasmChildSpanBuffer(parent, opts, _traceRoot, _scopeValues, _opMetadata, _callsiteMetadata) {
+    // Use provided schema (for cross-library calls) or parent's schema
+    const childSchema = opts.schema ?? parent._logSchema;
+    const WasmSpanBufferClass = getWasmSpanBufferClass(childSchema);
+    const child = new WasmSpanBufferClass({
+        ...opts,
+        logSchema: childSchema, // Use the child's schema (may differ from parent)
+        trace_id: parent.trace_id,
+        parent_thread_id: parent.thread_id,
+        parent_span_id: parent.span_id,
+        _traceRoot,
+        _scopeValues,
+        _opMetadata,
+        _callsiteMetadata,
+    });
+    // Link to parent (SpanContext will push to parent._children with possible RemappedBufferView wrapper)
+    child._parent = parent;
+    return child;
+}
+/**
+ * Create an overflow WASM SpanBuffer for chaining.
+ *
+ * @param buffer - The full buffer that needs overflow handling
+ * @param _traceRoot - Trace root context
+ * @param _scopeValues - Scope values for this span
+ * @param _opMetadata - Op metadata for attribution
+ * @param _callsiteMetadata - Callsite metadata for attribution
+ * @returns WasmSpanBufferInstance linked as overflow
+ */
+export function createWasmOverflowBuffer(buffer, _traceRoot, _scopeValues, _opMetadata, _callsiteMetadata) {
+    const WasmSpanBufferClass = getWasmSpanBufferClass(buffer._logSchema);
+    const overflow = new WasmSpanBufferClass({
+        allocator: buffer._allocator,
+        capacity: buffer._capacity,
+        trace_id: buffer.trace_id,
+        thread_id: buffer.thread_id,
+        span_id: buffer.span_id,
+        parent_thread_id: buffer.parent_thread_id,
+        parent_span_id: buffer.parent_span_id,
+        logSchema: buffer._logSchema,
+        _traceRoot,
+        _scopeValues,
+        _opMetadata,
+        _callsiteMetadata,
+    });
+    // Link as overflow (not child - same logical span)
+    overflow._parent = buffer._parent;
+    buffer._overflow = overflow;
+    return overflow;
+}