@smoothbricks/lmao 0.1.0

package/dist/lib/codegen/spanLoggerGenerator.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Runtime code generation for SpanLogger classes
+ *
+ * Per specs/lmao/01g_trace_context_api_codegen.md and 01j_module_context_and_spanlogger_generation.md:
+ * - SpanLogger extends ColumnWriter from arrow-builder via codegen extension
+ * - Handles log entries (rows 2+) - tag writing is in TagWriter (row 0)
+ * - Uses _nextRow() to advance position, then fluent setters write at _writeIndex
+ * - Compile-time enum mapping for 1-byte storage
+ * - Direct buffer writes without intermediate objects
+ *
+ * Row layout in SpanBuffer:
+ * - Row 0: tag attributes (written by TagWriter)
+ * - Row 1: result (ok/err) entry
+ * - Rows 2+: log entries (info/debug/warn/error)
+ *
+ * SpanLogger starts with _writeIndex = 1, so first _nextRow() makes it 2.
+ */
+import { type ColumnWriter } from '@smoothbricks/arrow-builder';
+import type { InferSchema, LogSchema } from '../schema/types.js';
+import type { AnySpanBuffer, SpanBuffer } from '../types.js';
+/**
+ * Helper functions injected into generated SpanLogger code.
+ * Singleton - same object shared by all generated SpanLogger classes.
+ */
+export declare const SPAN_LOGGER_HELPERS: {
+    setNullBit: (bitmap: Uint8Array, idx: number) => void;
+    fillNullBitmapRange: (bitmap: Uint8Array, startIdx: number, endIdx: number) => void;
+    fillBooleanBitmapRange: (bitmap: Uint8Array, startIdx: number, endIdx: number, value: boolean) => void;
+};
+/**
+ * Base SpanLogger interface - core logging methods.
+ * Extended by generated implementations with schema-specific methods.
+ */
+export interface BaseSpanLogger<T extends LogSchema> {
+    /** Log info-level message */
+    info(message: string): FluentLogEntry<T>;
+    /** Log debug-level message */
+    debug(message: string): FluentLogEntry<T>;
+    /** Log warning message */
+    warn(message: string): FluentLogEntry<T>;
+    /** Log error message */
+    error(message: string): FluentLogEntry<T>;
+}
+/**
+ * Fluent interface returned by log methods (info, debug, warn, error, trace).
+ * Includes system columns (line) plus all schema fields from T.
+ * Also includes logging methods for continued chaining (e.g., ctx.log.info('x').info('y'))
+ */
+export type FluentLogEntry<T extends LogSchema> = {
+    /** Set multiple attributes for this entry */
+    with(attributes: Partial<InferSchema<T>>): FluentLogEntry<T>;
+    /**
+     * Set the source code line number for this log entry.
+     * Injected by the LMAO transformer.
+     */
+    line(lineNumber: number): FluentLogEntry<T>;
+    /** Set error code for this entry */
+    error_code(code: string): FluentLogEntry<T>;
+    /** Set exception stack for this entry */
+    exception_stack(stack: string): FluentLogEntry<T>;
+    /** Set feature flag value for this entry */
+    ff_value(value: string): FluentLogEntry<T>;
+    /** Set uint64 value for this entry */
+    uint64_value(value: bigint): FluentLogEntry<T>;
+    info(message: string): FluentLogEntry<T>;
+    debug(message: string): FluentLogEntry<T>;
+    warn(message: string): FluentLogEntry<T>;
+    error(message: string): FluentLogEntry<T>;
+    trace(message: string): FluentLogEntry<T>;
+} & {
+    [K in keyof InferSchema<T>]: (value: InferSchema<T>[K]) => FluentLogEntry<T>;
+};
+/**
+ * Complete SpanLogger implementation type (runtime-generated class).
+ *
+ * Includes:
+ * - Core methods (info/debug/warn/error) from BaseSpanLogger
+ * - Schema-specific methods from ColumnWriter<T>
+ * - Internal methods (_setScope, _writeEntry, etc.)
+ *
+ * This is the FULL type returned by createSpanLogger().
+ * Users see SpanLogger<T> which hides internal methods.
+ */
+export type SpanLoggerImpl<T extends LogSchema> = ColumnWriter<T> & {
+    info(message: string): FluentLogEntry<T>;
+    debug(message: string): FluentLogEntry<T>;
+    warn(message: string): FluentLogEntry<T>;
+    error(message: string): FluentLogEntry<T>;
+    trace(message: string): FluentLogEntry<T>;
+    readonly scope: Readonly<Record<string, unknown>>;
+    _setScope(attributes: ScopeUpdate<T>): void;
+};
+export type ScopeUpdate<T extends LogSchema> = {
+    [K in keyof InferSchema<T>]?: InferSchema<T>[K] | null;
+};
+/**
+ * Create SpanLogger class constructor from schema.
+ * This is the cold-path function called at module creation time.
+ *
+ * SpanLogger extends ColumnWriter and adds:
+ * - info(), debug(), warn(), error() methods for log entries
+ * - _setScope() for setting scoped attributes
+ * - _getNextBuffer() override for SpanBuffer creation on overflow
+ *
+ * Note: Fluent attribute setters are inherited from ColumnWriter and write at _writeIndex.
+ */
+export declare function createSpanLoggerClass<T extends LogSchema>(schema: T): new (buffer: AnySpanBuffer) => SpanLoggerImpl<T>;
+/**
+ * Create a SpanLogger instance for the given buffer.
+ *
+ * @param schema - Tag attribute schema
+ * @param buffer - SpanBuffer to write to
+ */
+export declare function createSpanLogger<T extends LogSchema>(schema: T, buffer: SpanBuffer<T>): SpanLoggerImpl<T>;
+//# sourceMappingURL=spanLoggerGenerator.d.ts.map

package/dist/lib/codegen/spanLoggerGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spanLoggerGenerator.d.ts","sourceRoot":"","sources":["../../../src/lib/codegen/spanLoggerGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,YAAY,EAGlB,MAAM,6BAA6B,CAAC;AAWrC,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQ7D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE;IAChC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,mBAAmB,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpF,sBAAsB,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAkGxG,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,SAAS;IACjD,6BAA6B;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC,8BAA8B;IAC9B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1C,0BAA0B;IAC1B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC,wBAAwB;IACxB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,SAAS,IAAI;IAChD,6CAA6C;IAC7C,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC7D;;;OAGG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC5C,oCAAoC;IACpC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC5C,yCAAyC;IACzC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAClD,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC3C,sCAAsC;IACtC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAG/C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1C,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;CAC3C,GAAG;KACD,CAAC,IAAI,MAAM,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC;CAC7E,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,SAAS,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG;IAClE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1C,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,SAAS,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI;KAC5C,CAAC,IAAI,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;CACvD,CAAC;AA2bF;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,SAAS,EACvD,MAAM,EAAE,CAAC,GACR,KACD,MAAM,EAAE,aAAa,KAClB,cAAc,CAAC,CAAC,CAAC,CAwBrB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAGzG"}

package/dist/lib/codegen/spanLoggerGenerator.js

@@ -0,0 +1,575 @@
+/**
+ * Runtime code generation for SpanLogger classes
+ *
+ * Per specs/lmao/01g_trace_context_api_codegen.md and 01j_module_context_and_spanlogger_generation.md:
+ * - SpanLogger extends ColumnWriter from arrow-builder via codegen extension
+ * - Handles log entries (rows 2+) - tag writing is in TagWriter (row 0)
+ * - Uses _nextRow() to advance position, then fluent setters write at _writeIndex
+ * - Compile-time enum mapping for 1-byte storage
+ * - Direct buffer writes without intermediate objects
+ *
+ * Row layout in SpanBuffer:
+ * - Row 0: tag attributes (written by TagWriter)
+ * - Row 1: result (ok/err) entry
+ * - Rows 2+: log entries (info/debug/warn/error)
+ *
+ * SpanLogger starts with _writeIndex = 1, so first _nextRow() makes it 2.
+ */
+import { getColumnWriterClass, } from '@smoothbricks/arrow-builder';
+import { ENTRY_TYPE_DEBUG, ENTRY_TYPE_ERROR, ENTRY_TYPE_FF_ACCESS, ENTRY_TYPE_FF_USAGE, ENTRY_TYPE_INFO, ENTRY_TYPE_TRACE, ENTRY_TYPE_WARN, } from '../schema/systemSchema.js';
+import { getEnumValues, getSchemaType } from '../schema/typeGuards.js';
+// =============================================================================
+// SINGLETON HELPERS OBJECT
+// =============================================================================
+// Created once at module load, closed over by all generated SpanLogger classes.
+// This avoids recreating the helpers object for each schema.
+/**
+ * Helper functions injected into generated SpanLogger code.
+ * Singleton - same object shared by all generated SpanLogger classes.
+ */
+export const SPAN_LOGGER_HELPERS = {
+    setNullBit: (bitmap, idx) => {
+        bitmap[idx >>> 3] |= 1 << (idx & 7);
+    },
+    fillNullBitmapRange: (bitmap, startIdx, endIdx) => {
+        // Fill null bitmap for range [startIdx, endIdx)
+        const startByte = startIdx >>> 3;
+        const endByte = (endIdx - 1) >>> 3;
+        if (startByte === endByte) {
+            // All bits in same byte
+            for (let i = startIdx; i < endIdx; i++) {
+                bitmap[i >>> 3] |= 1 << (i & 7);
+            }
+        }
+        else {
+            // Handle first partial byte
+            const startBit = startIdx & 7;
+            if (startBit !== 0) {
+                bitmap[startByte] |= 0xff << startBit;
+            }
+            else {
+                bitmap[startByte] = 0xff;
+            }
+            // Fill middle bytes
+            for (let b = startByte + 1; b < endByte; b++) {
+                bitmap[b] = 0xff;
+            }
+            // Handle last partial byte
+            const endBit = endIdx & 7;
+            if (endBit !== 0) {
+                bitmap[endByte] |= (1 << endBit) - 1;
+            }
+            else {
+                bitmap[endByte] = 0xff;
+            }
+        }
+    },
+    fillBooleanBitmapRange: (bitmap, startIdx, endIdx, value) => {
+        // Fill boolean bitmap for range with value
+        if (value) {
+            // Same as fillNullBitmapRange - set bits to 1
+            const startByte = startIdx >>> 3;
+            const endByte = (endIdx - 1) >>> 3;
+            if (startByte === endByte) {
+                for (let i = startIdx; i < endIdx; i++) {
+                    bitmap[i >>> 3] |= 1 << (i & 7);
+                }
+            }
+            else {
+                const startBit = startIdx & 7;
+                if (startBit !== 0) {
+                    bitmap[startByte] |= 0xff << startBit;
+                }
+                else {
+                    bitmap[startByte] = 0xff;
+                }
+                for (let b = startByte + 1; b < endByte; b++) {
+                    bitmap[b] = 0xff;
+                }
+                const endBit = endIdx & 7;
+                if (endBit !== 0) {
+                    bitmap[endByte] |= (1 << endBit) - 1;
+                }
+                else {
+                    bitmap[endByte] = 0xff;
+                }
+            }
+        }
+        else {
+            // Clear bits to 0
+            const startByte = startIdx >>> 3;
+            const endByte = (endIdx - 1) >>> 3;
+            if (startByte === endByte) {
+                for (let i = startIdx; i < endIdx; i++) {
+                    bitmap[i >>> 3] &= ~(1 << (i & 7));
+                }
+            }
+            else {
+                const startBit = startIdx & 7;
+                if (startBit !== 0) {
+                    bitmap[startByte] &= ~(0xff << startBit);
+                }
+                else {
+                    bitmap[startByte] = 0;
+                }
+                for (let b = startByte + 1; b < endByte; b++) {
+                    bitmap[b] = 0;
+                }
+                const endBit = endIdx & 7;
+                if (endBit !== 0) {
+                    bitmap[endByte] &= ~((1 << endBit) - 1);
+                }
+                else {
+                    bitmap[endByte] = 0;
+                }
+            }
+        }
+    },
+};
+/**
+ * Generate enum value mapping code
+ * Creates a switch-case statement for compile-time enum mapping
+ */
+function generateEnumMapping(fieldName, enumValues) {
+    const cases = enumValues.map((value, index) => `    case ${JSON.stringify(value)}: return ${index};`).join('\n');
+    return `
+  function getEnumIndex_${fieldName}(value) {
+    switch(value) {
+${cases}
+      default: return 0;
+    }
+  }`;
+}
+/**
+ * Generate override fluent setters for enum fields.
+ * These convert string values to numeric indices before writing to the buffer.
+ * The buffer expects numeric indices (after the enum map removal change).
+ */
+function generateEnumFluentSetters(enumFieldNames) {
+    const setters = [];
+    for (const fieldName of enumFieldNames) {
+        setters.push(`
+    /**
+     * Override fluent setter for ${fieldName} to convert string → index.
+     * Buffer expects numeric index, not string value.
+     */
+    ${fieldName}(value) {
+      const idx = getEnumIndex_${fieldName}(value);
+      this._buffer.${fieldName}(this._writeIndex, idx);
+      return this;
+    }`);
+    }
+    return setters.join('\n');
+}
+/**
+ * Generate _setScope() method code - IMMUTABLE scope semantics
+ *
+ * Per specs/lmao/01i_span_scope_attributes.md:
+ * - Creates NEW frozen object (never mutates existing)
+ * - Merge semantics: new values merge with existing
+ * - null clears a key, undefined is ignored
+ * - Child spans inherit parent scope by reference (safe because immutable)
+ * - Scope filling happens at Arrow conversion time, NOT during span execution
+ */
+function generateSetScopeMethod() {
+    // Immutable scope: create new frozen object with merge semantics and null clearing
+    // No buffer pre-filling - scope values are filled at Arrow conversion time via SIMD
+    return `
+    _setScope(attributes) {
+      const current = this._buffer._scopeValues || {};
+      const next = { ...current };
+      
+      for (const key of Object.keys(attributes)) {
+        const value = attributes[key];
+        if (value === null) {
+          delete next[key];
+        } else if (value !== undefined) {
+          next[key] = value;
+        }
+      }
+      
+      this._buffer._scopeValues = Object.freeze(next);
+    }`;
+}
+/**
+ * Generate _prefillScopedAttributesOn(buffer) method - UNROLLED per-column with BULK null bitmap fill
+ *
+ * Takes buffer as argument instead of using this._buffer. This avoids the convoluted
+ * pattern of temporarily switching this._buffer for prefill then switching back.
+ * Called by _checkOverflow after getting overflow buffer.
+ */
+function generatePrefillScopedAttributesMethod(schemaFields, enumFieldNames) {
+    const columnFills = schemaFields.map(([fieldName, fieldSchema]) => {
+        const columnName = fieldName;
+        const lmaoType = getSchemaType(fieldSchema);
+        // Binary columns are not scope-fillable (object payloads can't be bulk-filled)
+        if (lmaoType === 'binary') {
+            return '';
+        }
+        // Boolean uses bit-packed storage - bulk fill using helper
+        if (lmaoType === 'boolean') {
+            return `
+      {
+        const scopeValue = buffer._scopeValues?.${fieldName};
+        if (scopeValue !== null && scopeValue !== undefined && buffer._${columnName}_values !== undefined) {
+          helpers.fillBooleanBitmapRange(buffer.${columnName}_values, startIdx, endIdx, scopeValue);
+          helpers.fillNullBitmapRange(buffer.${columnName}_nulls, startIdx, endIdx);
+        }
+      }`;
+        }
+        // Value processing based on type
+        let valueExpr = 'scopeValue';
+        if (lmaoType === 'enum' && enumFieldNames.has(fieldName)) {
+            valueExpr = `getEnumIndex_${fieldName}(scopeValue)`;
+        }
+        // For string arrays (category/text), use manual loop instead of fill()
+        if (lmaoType === 'category' || lmaoType === 'text') {
+            return `
+      {
+        const scopeValue = buffer._scopeValues?.${fieldName};
+        if (scopeValue !== null && scopeValue !== undefined && buffer._${columnName}_values !== undefined) {
+          const values = buffer.${columnName}_values;
+          for (let i = startIdx; i < endIdx; i++) {
+            values[i] = scopeValue;
+          }
+          helpers.fillNullBitmapRange(buffer.${columnName}_nulls, startIdx, endIdx);
+        }
+      }`;
+        }
+        return `
+      {
+        const scopeValue = buffer._scopeValues?.${fieldName};
+        if (scopeValue !== null && scopeValue !== undefined && buffer._${columnName}_values !== undefined) {
+          buffer.${columnName}_values.fill(${valueExpr}, startIdx, endIdx);
+          helpers.fillNullBitmapRange(buffer.${columnName}_nulls, startIdx, endIdx);
+        }
+      }`;
+    });
+    // Initial buffer: rows 0-1 reserved for span-start/end, data starts at _writeIndex=2
+    // Overflow buffer: no reserved rows, data starts at _writeIndex=0
+    // Use buffer._writeIndex as startIdx to handle both cases correctly
+    return `
+    _prefillScopedAttributesOn(buffer) {
+      const startIdx = buffer._writeIndex;
+      const endIdx = buffer._capacity;
+      ${columnFills.join('\n')}
+    }`;
+}
+/**
+ * Build the extension for SpanLogger that extends ColumnWriter
+ */
+function buildSpanLoggerExtension(schema) {
+    const schemaFields = schema._columns;
+    // Collect enum mappings
+    const enumMappings = [];
+    const enumFieldNames = new Set();
+    for (const [fieldName, fieldSchema] of schemaFields) {
+        const lmaoType = getSchemaType(fieldSchema);
+        const enumValues = getEnumValues(fieldSchema);
+        if (lmaoType === 'enum' && enumValues) {
+            enumMappings.push(generateEnumMapping(fieldName, enumValues));
+            enumFieldNames.add(fieldName);
+        }
+    }
+    // Generate methods
+    const setScopeMethod = generateSetScopeMethod();
+    const prefillMethod = generatePrefillScopedAttributesMethod(schemaFields, enumFieldNames);
+    const enumFluentSetters = generateEnumFluentSetters(enumFieldNames);
+    return {
+        constructorParams: '',
+        // Entry type constants (inlined from lmao.ts)
+        classPreamble: `
+  const ENTRY_TYPE_INFO = ${ENTRY_TYPE_INFO};
+  const ENTRY_TYPE_DEBUG = ${ENTRY_TYPE_DEBUG};
+  const ENTRY_TYPE_WARN = ${ENTRY_TYPE_WARN};
+  const ENTRY_TYPE_ERROR = ${ENTRY_TYPE_ERROR};
+  const ENTRY_TYPE_TRACE = ${ENTRY_TYPE_TRACE};
+  const ENTRY_TYPE_FF_ACCESS = ${ENTRY_TYPE_FF_ACCESS};
+  const ENTRY_TYPE_FF_USAGE = ${ENTRY_TYPE_FF_USAGE};
+
+  ${enumMappings.join('\n')}
+`,
+        // SpanLogger starts at writeIndex 1, so first nextRow() makes it 2
+        // (Rows 0 and 1 are reserved for span-start and span-end)
+        // Sync buffer's writeIndex - needed for Arrow conversion
+        constructorCode: `
+      this._writeIndex = 1;
+      this._buffer._writeIndex = 2;
+`,
+        // Check for overflow before writing, switch to overflow buffer if needed.
+        // Overflow when _writeIndex >= capacity (buffer is full, no room for this write).
+        // Buffer.getOrCreateOverflow() handles: stats notification, capacity tuning, buffer creation.
+        // We just need to switch this._buffer and prefill scope on the new buffer.
+        methods: `_checkOverflow() {
+      if (this._buffer._writeIndex >= this._buffer._capacity) {
+        this._buffer = this._buffer.getOrCreateOverflow();
+        this._prefillScopedAttributesOn(this._buffer);
+      }
+    }
+
+    ` +
+            // Write an info log entry.
+            // writeLogEntry bumps buffer._writeIndex, writes timestamp+entry_type, returns idx.
+            // We sync this._writeIndex so fluent setters write at correct row.
+            `info(message) {
+      this._checkOverflow();
+      const idx = this._buffer._traceRoot.writeLogEntry(this._buffer, ENTRY_TYPE_INFO);
+      this._writeIndex = idx;
+      if (this._buffer.message_values) {
+        this._buffer.message_values[idx] = message;
+        if (this._buffer.message_nulls) {
+          helpers.setNullBit(this._buffer.message_nulls, idx);
+        }
+      }
+      this._buffer.constructor.stats.totalWrites++;
+      return this;
+    }
+
+    ` +
+            // Write a debug log entry.
+            `debug(message) {
+      this._checkOverflow();
+      const idx = this._buffer._traceRoot.writeLogEntry(this._buffer, ENTRY_TYPE_DEBUG);
+      this._writeIndex = idx;
+      if (this._buffer.message_values) {
+        this._buffer.message_values[idx] = message;
+        if (this._buffer.message_nulls) {
+          helpers.setNullBit(this._buffer.message_nulls, idx);
+        }
+      }
+      this._buffer.constructor.stats.totalWrites++;
+      return this;
+    }
+
+    ` +
+            // Write a warn log entry.
+            `warn(message) {
+      this._checkOverflow();
+      const idx = this._buffer._traceRoot.writeLogEntry(this._buffer, ENTRY_TYPE_WARN);
+      this._writeIndex = idx;
+      if (this._buffer.message_values) {
+        this._buffer.message_values[idx] = message;
+        if (this._buffer.message_nulls) {
+          helpers.setNullBit(this._buffer.message_nulls, idx);
+        }
+      }
+      this._buffer.constructor.stats.totalWrites++;
+      return this;
+    }
+
+    ` +
+            // Write an error log entry.
+            `error(message) {
+      this._checkOverflow();
+      const idx = this._buffer._traceRoot.writeLogEntry(this._buffer, ENTRY_TYPE_ERROR);
+      this._writeIndex = idx;
+      if (this._buffer.message_values) {
+        this._buffer.message_values[idx] = message;
+        if (this._buffer.message_nulls) {
+          helpers.setNullBit(this._buffer.message_nulls, idx);
+        }
+      }
+      this._buffer.constructor.stats.totalWrites++;
+      return this;
+    }
+
+    ` +
+            // Write a trace log entry.
+            `trace(message) {
+      this._checkOverflow();
+      const idx = this._buffer._traceRoot.writeLogEntry(this._buffer, ENTRY_TYPE_TRACE);
+      this._writeIndex = idx;
+      if (this._buffer.message_values) {
+        this._buffer.message_values[idx] = message;
+        if (this._buffer.message_nulls) {
+          helpers.setNullBit(this._buffer.message_nulls, idx);
+        }
+      }
+      this._buffer.constructor.stats.totalWrites++;
+      return this;
+    }
+
+    ` +
+            // Set multiple attributes on the current log entry.
+            `with(attributes) {
+      for (const key in attributes) {
+        const value = attributes[key];
+        if (value === null || value === undefined) {
+          continue;
+        }
+        const setter = this[key];
+        if (typeof setter === 'function') {
+          setter.call(this, value);
+        }
+      }
+      return this;
+    }
+
+    ` +
+            // Write a feature flag access entry (internal method, not on public type).
+            // Called by FeatureFlagEvaluator to log flag access.
+            `ffAccess(flagName, value) {
+      this._checkOverflow();
+      const idx = this._buffer._traceRoot.writeLogEntry(this._buffer, ENTRY_TYPE_FF_ACCESS);
+      this._writeIndex = idx;
+      if (this._buffer.message_values) {
+        this._buffer.message_values[idx] = flagName;
+        if (this._buffer.message_nulls) {
+          helpers.setNullBit(this._buffer.message_nulls, idx);
+        }
+      }
+      if (this._buffer.ff_value_values) {
+        const strValue = value === null || value === undefined ? 'null' : String(value);
+        this._buffer.ff_value_values[idx] = strValue;
+        if (this._buffer.ff_value_nulls) {
+          helpers.setNullBit(this._buffer.ff_value_nulls, idx);
+        }
+      }
+      this._buffer.constructor.stats.totalWrites++;
+    }
+
+    ` +
+            // Write a feature flag usage entry (internal method, not on public type).
+            // Called by FeatureFlagEvaluator to log flag usage.
+            `ffUsage(flagName, context) {
+      this._checkOverflow();
+      const idx = this._buffer._traceRoot.writeLogEntry(this._buffer, ENTRY_TYPE_FF_USAGE);
+      this._writeIndex = idx;
+      if (this._buffer.message_values) {
+        this._buffer.message_values[idx] = flagName;
+        if (this._buffer.message_nulls) {
+          helpers.setNullBit(this._buffer.message_nulls, idx);
+        }
+      }
+      this._buffer.constructor.stats.totalWrites++;
+      if (context) {
+        this.with(context);
+      }
+      return this;
+    }
+
+    ` +
+            // Set the source code line number for the current log entry.
+            // Injected by the LMAO transformer after info/debug/warn/error/trace calls.
+            // Writes to _writeIndex (the current row).
+            `line(lineNumber) {
+      const idx = this._writeIndex;
+      if (this._buffer.line_values) {
+        this._buffer.line_values[idx] = lineNumber;
+        if (this._buffer.line_nulls) {
+          helpers.setNullBit(this._buffer.line_nulls, idx);
+        }
+      }
+      return this;
+    }
+
+    error_code(code) {
+      const idx = this._writeIndex;
+      if (this._buffer.error_code_values) {
+        this._buffer.error_code_values[idx] = code;
+        if (this._buffer.error_code_nulls) {
+          helpers.setNullBit(this._buffer.error_code_nulls, idx);
+        }
+      }
+      return this;
+    }
+
+    exception_stack(stack) {
+      const idx = this._writeIndex;
+      if (this._buffer.exception_stack_values) {
+        this._buffer.exception_stack_values[idx] = stack;
+        if (this._buffer.exception_stack_nulls) {
+          helpers.setNullBit(this._buffer.exception_stack_nulls, idx);
+        }
+      }
+      return this;
+    }
+
+    ff_value(value) {
+      const idx = this._writeIndex;
+      if (this._buffer.ff_value_values) {
+        this._buffer.ff_value_values[idx] = value;
+        if (this._buffer.ff_value_nulls) {
+          helpers.setNullBit(this._buffer.ff_value_nulls, idx);
+        }
+      }
+      return this;
+    }
+
+    uint64_value(value) {
+      const idx = this._writeIndex;
+      if (this._buffer.uint64_value_values) {
+        this._buffer.uint64_value_values[idx] = value;
+        if (this._buffer.uint64_value_nulls) {
+          helpers.setNullBit(this._buffer.uint64_value_nulls, idx);
+        }
+      }
+      return this;
+    }
+
+    ` +
+            // Get the scope values from buffer directly.
+            `get scope() {
+      return this._buffer._scopeValues;
+    }
+
+    ${setScopeMethod}
+
+    ${prefillMethod}
+
+    ` +
+            // Override fluent setters for enum fields to convert string → index
+            `${enumFluentSetters}
+`,
+        // Use singleton helpers object (created once at module load)
+        dependencies: {
+            helpers: SPAN_LOGGER_HELPERS,
+        },
+    };
+}
+/**
+ * Cache for generated SpanLogger classes per schema.
+ */
+const spanLoggerClassCache = new WeakMap();
+function isSpanLoggerConstructor(value) {
+    return typeof value === 'function';
+}
+/**
+ * Create SpanLogger class constructor from schema.
+ * This is the cold-path function called at module creation time.
+ *
+ * SpanLogger extends ColumnWriter and adds:
+ * - info(), debug(), warn(), error() methods for log entries
+ * - _setScope() for setting scoped attributes
+ * - _getNextBuffer() override for SpanBuffer creation on overflow
+ *
+ * Note: Fluent attribute setters are inherited from ColumnWriter and write at _writeIndex.
+ */
+export function createSpanLoggerClass(schema) {
+    // Check cache first
+    let SpanLoggerClass = spanLoggerClassCache.get(schema);
+    if (!SpanLoggerClass) {
+        const extension = buildSpanLoggerExtension(schema);
+        // Use arrow-builder's getColumnWriterClass with our extension
+        const WriterClass = getColumnWriterClass(schema, extension);
+        SpanLoggerClass = WriterClass;
+        if (!isSpanLoggerConstructor(SpanLoggerClass)) {
+            throw new Error('Failed to generate SpanLogger constructor');
+        }
+        spanLoggerClassCache.set(schema, SpanLoggerClass);
+    }
+    if (!isSpanLoggerConstructor(SpanLoggerClass)) {
+        throw new Error('Invalid cached SpanLogger constructor');
+    }
+    return SpanLoggerClass;
+}
+/**
+ * Create a SpanLogger instance for the given buffer.
+ *
+ * @param schema - Tag attribute schema
+ * @param buffer - SpanBuffer to write to
+ */
+export function createSpanLogger(schema, buffer) {
+    const SpanLoggerClass = createSpanLoggerClass(schema);
+    return new SpanLoggerClass(buffer);
+}