@smoothbricks/lmao 0.1.0

package/dist/lib/library.js

@@ -0,0 +1,588 @@
+/**
+ * Library Prefix/Remapping Utilities
+ *
+ * WHY: Libraries need to write clean, domain-focused code (ctx.tag.status(200))
+ * while avoiding naming conflicts when composed with other libraries.
+ *
+ * HOW: At composition time (cold path), we generate a remapped SpanLogger class
+ * that exposes clean method names but writes to prefixed buffer columns.
+ *
+ * Per specs/lmao/01e_library_integration_pattern.md:
+ * - Libraries define clean schemas without prefixes (status, method, url)
+ * - Prefixing happens at composition time (http_status, http_method, http_url)
+ * - Zero hot path overhead - all remapping done via code generation at module creation
+ *
+ * WHAT: This module provides:
+ * - prefixSchema() - Rename schema fields with prefix
+ * - createPrefixMapping() - Build clean→prefixed name mapping
+ * - generateRemappedBufferViewClass() - Generate view for Arrow conversion
+ * - generateRemappedSpanLoggerClass() - Generate class with clean methods, prefixed writes
+ * - createRemappedSpanLoggerClass() - Compile and cache SpanLogger classes
+ */
+import { isRecord } from '@smoothbricks/validation';
+import { ENTRY_TYPE_DEBUG, ENTRY_TYPE_ERROR, ENTRY_TYPE_INFO, ENTRY_TYPE_TRACE, ENTRY_TYPE_WARN, } from './schema/systemSchema.js';
+import { getEnumValues, getSchemaType } from './schema/typeGuards.js';
+import { LogSchema } from './schema/types.js';
+function isSchemaField(value) {
+    return isRecord(value);
+}
+function isRemappedBufferViewClass(value) {
+    if (typeof value !== 'function') {
+        return false;
+    }
+    const prototype = Reflect.get(value, 'prototype');
+    return (typeof prototype === 'object' &&
+        prototype !== null &&
+        typeof Reflect.get(prototype, 'getColumnIfAllocated') === 'function' &&
+        typeof Reflect.get(prototype, 'getNullsIfAllocated') === 'function');
+}
+function isRemappedSpanLoggerClass(value) {
+    if (typeof value !== 'function') {
+        return false;
+    }
+    const prototype = Reflect.get(value, 'prototype');
+    return (typeof prototype === 'object' &&
+        prototype !== null &&
+        typeof Reflect.get(prototype, 'with') === 'function' &&
+        typeof Reflect.get(prototype, 'info') === 'function' &&
+        typeof Reflect.get(prototype, 'error') === 'function');
+}
+/**
+ * Prefix a tag attribute schema
+ * Renames all fields with a prefix to avoid conflicts
+ *
+ * Example:
+ * - Input: { status: S.number(), method: S.enum(['GET', 'POST']) }
+ * - Prefix: 'http'
+ * - Output: { http_status: S.number(), http_method: S.enum(['GET', 'POST']) }
+ */
+export function prefixSchema(schema, prefix) {
+    const prefixedFields = {};
+    const constructorFields = {};
+    for (const [fieldName, fieldSchema] of schema._columns) {
+        const prefixedName = `${prefix}_${fieldName}`;
+        prefixedFields[prefixedName] = fieldSchema;
+        if (isSchemaField(fieldSchema)) {
+            constructorFields[prefixedName] = fieldSchema;
+        }
+    }
+    // Create LogSchema and spread fields directly onto result for direct access
+    const logSchema = new LogSchema(constructorFields);
+    return Object.assign(logSchema, prefixedFields);
+}
+/**
+ * Create a mapping from clean field names to prefixed column names
+ *
+ * WHY: This mapping is used by generateRemappedSpanLoggerClass to create methods
+ * that write to prefixed columns but expose clean API names.
+ *
+ * @param schema - Clean schema (LogSchema instance)
+ * @param prefix - Prefix to apply (e.g., 'http')
+ * @returns Mapping from clean name to prefixed name
+ *
+ * @example
+ * const schema = defineLogSchema({ status: S.number() });
+ * const mapping = createPrefixMapping(schema, 'http');
+ * // Returns: { status: 'http_status' }
+ */
+export function createPrefixMapping(schema, prefix) {
+    const mapping = {};
+    // Use LogSchema.fieldNames directly (no conditional needed)
+    for (const fieldName of schema._columnNames) {
+        mapping[fieldName] = `${prefix}_${fieldName}`;
+    }
+    return mapping;
+}
+// ============================================================================
+// RemappedBufferView - Maps prefixed column names to unprefixed for tree traversal
+// ============================================================================
+/**
+ * Cache for generated RemappedBufferView classes.
+ * Key is a stable string representation of the mapping.
+ * This avoids regenerating classes for the same mapping.
+ */
+const remappedBufferViewClassCache = new Map();
+/**
+ * Cache for generated RemappedSpanLogger classes.
+ * Key is a stable string representation of schema fields + prefix mapping.
+ */
+const remappedSpanLoggerClassCache = new Map();
+/**
+ * Create a stable cache key from a prefix mapping.
+ * Sorts keys to ensure consistent ordering.
+ */
+function createMappingCacheKey(mapping) {
+    const sortedEntries = Object.entries(mapping).sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify(sortedEntries);
+}
+/**
+ * Create a stable cache key from schema and prefix mapping.
+ * Combines schema fields with sorted prefix mapping for consistent keys.
+ */
+function createSchemaAndMappingCacheKey(schema, mapping) {
+    const schemaKey = JSON.stringify(schema.fields);
+    const mappingKey = createMappingCacheKey(mapping);
+    return `${schemaKey}:${mappingKey}`;
+}
+/**
+ * Generate a RemappedBufferView class for library prefix support.
+ *
+ * WHY: Libraries write to unprefixed columns (status, method) but Arrow conversion
+ * iterates using prefixed names from the root schema (http_status, http_method).
+ * RemappedBufferView bridges this gap for tree traversal during cold-path Arrow conversion.
+ *
+ * HOW: Uses new Function() to generate a class at library composition time (cold path).
+ * The generated class wraps a SpanBuffer and remaps getColumnIfAllocated/getNullsIfAllocated
+ * calls from prefixed names to unprefixed names.
+ *
+ * WHAT: Returns a class constructor that:
+ * - Passes through tree traversal properties (children, next)
+ * - Passes through system columns (timestamps, operations, message, etc.)
+ * - Passes through identity properties (traceId, spanId, etc.)
+ * - Remaps getColumnIfAllocated() and getNullsIfAllocated() from prefixed→unprefixed
+ *
+ * Per specs/lmao/01e_library_integration_pattern.md:
+ * - Hot path: Library writes directly to unprefixed columns (zero overhead)
+ * - Cold path: Arrow conversion uses RemappedBufferView to access via prefixed names
+ *
+ * @param prefixToUnprefixedMapping - Maps prefixed names to unprefixed names
+ *   e.g., { 'http_status': 'status', 'http_method': 'method' }
+ *   NOTE: The mapping is prefixed→unprefixed (reverse of createPrefixMapping output)
+ *
+ * @returns Constructor for RemappedBufferView class
+ *
+ * @example
+ * ```typescript
+ * // Create mapping (prefixed → unprefixed)
+ * const mapping = { 'http_status': 'status', 'http_method': 'method' };
+ * const ViewClass = generateRemappedBufferViewClass(mapping);
+ *
+ * // Wrap library buffer
+ * const view = new ViewClass(libraryBuffer);
+ *
+ * // Access via prefixed name returns unprefixed column
+ * view.getColumnIfAllocated('http_status'); // Returns buffer.getColumnIfAllocated('status')
+ * ```
+ */
+export function generateRemappedBufferViewClass(prefixToUnprefixedMapping) {
+    // Check cache first
+    const cacheKey = createMappingCacheKey(prefixToUnprefixedMapping);
+    const cached = remappedBufferViewClassCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const mappingCode = JSON.stringify(prefixToUnprefixedMapping);
+    // Generate the class code
+    // Uses IIFE wrapper for clean scope, similar to generateRemappedSpanLoggerClass
+    const code = `(function() {
+  'use strict';
+  const mapping = ${mappingCode};
+  
+  class RemappedBufferView {
+    constructor(buffer) {
+      this._buffer = buffer;
+      // Build _columns with prefixed names from mapping
+      // mapping is { prefixedName: unprefixedName }
+      // _logSchema may be undefined in tests using mock buffers
+      const baseFields = buffer._logSchema?.fields ?? {};
+      this._columns = [];
+      for (const prefixedName in mapping) {
+        const unprefixedName = mapping[prefixedName];
+        const schema = baseFields[unprefixedName];
+        if (schema) this._columns.push([prefixedName, schema]);
+      }
+    }
+    
+    // Tree traversal (pass-through)
+    get _children() { return this._buffer._children; }
+    get _parent() { return this._buffer._parent; }
+    get _overflow() { return this._buffer._overflow; }
+
+    // Row count
+    get _writeIndex() { return this._buffer._writeIndex; }
+
+    // System columns (NOT remapped - same in all buffers)
+    get timestamp() { return this._buffer.timestamp; }
+    get entry_type() { return this._buffer.entry_type; }
+    get message_values() { return this._buffer.message_values; }
+    get message_nulls() { return this._buffer.message_nulls; }
+    get line_values() { return this._buffer.line_values; }
+    get line_nulls() { return this._buffer.line_nulls; }
+    get error_code_values() { return this._buffer.error_code_values; }
+    get error_code_nulls() { return this._buffer.error_code_nulls; }
+    get exception_stack_values() { return this._buffer.exception_stack_values; }
+    get exception_stack_nulls() { return this._buffer.exception_stack_nulls; }
+    get ff_value_values() { return this._buffer.ff_value_values; }
+    get ff_value_nulls() { return this._buffer.ff_value_nulls; }
+    
+    // Identity (pass-through)
+    get trace_id() { return this._buffer.trace_id; }
+    get thread_id() { return this._buffer.thread_id; }
+    get span_id() { return this._buffer.span_id; }
+    get parent_span_id() { return this._buffer.parent_span_id; }
+    get parent_thread_id() { return this._buffer.parent_thread_id; }
+    get _identity() { return this._buffer._identity; }
+    
+    // Metadata (pass-through)
+    get module() { return this._buffer._module; }
+    get _opMetadata() { return this._buffer._opMetadata; }
+    get _callsiteMetadata() { return this._buffer._callsiteMetadata; }
+    // Remapped column access (for Arrow conversion iteration)
+    // Maps prefixed name → unprefixed name before calling underlying buffer
+    getColumnIfAllocated(name) {
+      const unprefixedName = mapping[name] ?? name;
+      return this._buffer.getColumnIfAllocated(unprefixedName);
+    }
+    
+    getNullsIfAllocated(name) {
+      const unprefixedName = mapping[name] ?? name;
+      return this._buffer.getNullsIfAllocated(unprefixedName);
+    }
+  }
+  
+  return RemappedBufferView;
+})()`;
+    const GeneratedClass = new Function(`return ${code}`)();
+    if (!isRemappedBufferViewClass(GeneratedClass)) {
+        throw new TypeError('Generated remapped buffer view is missing column remapping methods');
+    }
+    // Cache for future use
+    remappedBufferViewClassCache.set(cacheKey, GeneratedClass);
+    return GeneratedClass;
+}
+/**
+ * Generate enum value mapping code for remapped class
+ * Creates a switch-case statement for compile-time enum mapping
+ *
+ * WHY: Enums need compile-time mapping to Uint8 values for 1-byte storage
+ */
+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 attribute writer method for remapped SpanLogger
+ *
+ * WHY: Each method must write to the PREFIXED column while being called by CLEAN name
+ * HOW: Method name is cleanName, but buffer access uses prefixedColumnName
+ *
+ * @param cleanName - Clean method name (e.g., 'status')
+ * @param prefixedColumnName - Prefixed column name (e.g., 'http_status')
+ * @param schema - Field schema for type-specific handling
+ * @param hasEnumMapping - Whether enum mapping function exists
+ */
+function generateRemappedAttributeWriter(cleanName, prefixedColumnName, schema, hasEnumMapping) {
+    const columnName = prefixedColumnName;
+    const lmaoType = getSchemaType(schema);
+    // For enums, use pre-generated mapping function (uses cleanName for function)
+    // Generated code: ALWAYS writes to row 0 (span-start) with overwrite semantics
+    // Maps clean method name to prefixed column, marks value as non-null (bit 0)
+    if (lmaoType === 'enum' && hasEnumMapping) {
+        return `
+    ${cleanName}(value) {
+      const idx = 0;
+      const enumIndex = getEnumIndex_${cleanName}(value);
+      this._buffer.${columnName}_values[idx] = enumIndex;
+      this._buffer.${columnName}_nulls[0] |= 1;
+      return this;
+    }`;
+    }
+    // For categories, store strings directly
+    // Generated code: writes to row 0, stores string directly, marks non-null
+    if (lmaoType === 'category') {
+        return `
+    ${cleanName}(value) {
+      const idx = 0;
+      if (value === null || value === undefined) {
+        this._buffer.${columnName}_nulls[0] &= ~1;
+        return this;
+      }
+      this._buffer.${columnName}_values[idx] = value;
+      this._buffer.${columnName}_nulls[0] |= 1;
+      return this;
+    }`;
+    }
+    // For text, store strings directly
+    // Generated code: writes to row 0, handles null/undefined by clearing bit and returning early,
+    // stores string directly, marks non-null
+    if (lmaoType === 'text') {
+        return `
+    ${cleanName}(value) {
+      const idx = 0;
+      if (value === null || value === undefined) {
+        this._buffer.${columnName}_nulls[0] &= ~1;
+        return this;
+      }
+      this._buffer.${columnName}_values[idx] = value;
+      this._buffer.${columnName}_nulls[0] |= 1;
+      return this;
+    }`;
+    }
+    // Boolean: bit-packed storage (8 values per byte)
+    // Generated code: writes to row 0, bit 0 of byte 0 is index 0,
+    // sets or clears value bit, marks non-null
+    if (lmaoType === 'boolean') {
+        return `
+    ${cleanName}(value) {
+      if (value) {
+        this._buffer.${columnName}_values[0] |= 1;
+      } else {
+        this._buffer.${columnName}_values[0] &= ~1;
+      }
+      this._buffer.${columnName}_nulls[0] |= 1;
+      return this;
+    }`;
+    }
+    // Generic writer for other types (number)
+    // Generated code: writes to row 0, direct value assignment, marks non-null
+    return `
+    ${cleanName}(value) {
+      const idx = 0;
+      this._buffer.${columnName}_values[idx] = value;
+      this._buffer.${columnName}_nulls[0] |= 1;
+      return this;
+    }`;
+}
+/**
+ * Generate a remapped SpanLogger class for library prefix support
+ *
+ * WHY: Library authors write clean code (ctx.tag.status(200)) but buffers use prefixed
+ * columns (http_status). This function generates a class at module creation time
+ * (cold path) that exposes clean method names but writes to prefixed columns.
+ *
+ * HOW: Uses new Function() to generate optimized JavaScript code. The generated class
+ * has methods named after clean schema fields but writes to prefixed buffer columns.
+ *
+ * WHAT: Returns executable JavaScript code string for a SpanLogger class with:
+ * - Clean method names (status, method, url)
+ * - Writes to prefixed columns (http_status, http_method, http_url)
+ * - Full support for enum/category/text type handling
+ * - Method chaining support
+ *
+ * @param cleanSchema - Original clean schema (without prefix)
+ * @param prefixMapping - Mapping from clean names to prefixed names
+ * @param className - Name for the generated class
+ * @returns Executable JavaScript code string
+ *
+ * @example
+ * const code = generateRemappedSpanLoggerClass(
+ *   { status: S.number(), method: S.enum(['GET', 'POST']) },
+ *   { status: 'http_status', method: 'http_method' },
+ *   'HttpSpanLogger'
+ * );
+ * // Generated class has .status() method that writes to http_status
+ */
+export function generateRemappedSpanLoggerClass(cleanSchema, prefixMapping, className = 'RemappedSpanLogger') {
+    // Use LogSchema.fieldEntries() to iterate schema fields
+    const schemaFields = cleanSchema._columns;
+    // Generate enum mapping functions (use cleanName for function names)
+    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 attribute writer methods with remapping
+    const attributeWriters = schemaFields.map(([cleanName, fieldSchema]) => {
+        const prefixedName = prefixMapping[cleanName] || cleanName;
+        return generateRemappedAttributeWriter(cleanName, prefixedName, fieldSchema, enumFieldNames.has(cleanName));
+    });
+    // Create schema type map for runtime type detection in scope()
+    const schemaTypeMap = Object.fromEntries(schemaFields.map(([fieldName, fieldSchema]) => {
+        return [fieldName, getSchemaType(fieldSchema) || 'unknown'];
+    }));
+    // Create clean-to-prefixed mapping for with() and scope() methods
+    const prefixMappingJson = JSON.stringify(prefixMapping);
+    // Entry type constants (imported from lmao.ts at module level, used here for code gen)
+    // These values are inlined into the generated code string below
+    // Generate the complete class
+    // Generated code: IIFE wrapper for clean scope
+    const classCode = `(function() {
+  'use strict';
+  ` +
+        // Generated code: getTimestampNanos - platform-aware timestamp function
+        // Node.js: uses process.hrtime.bigint() for true nanosecond precision
+        // Browser: uses performance.timeOrigin + performance.now() for microsecond precision
+        `const getTimestampNanos = (typeof process !== 'undefined' && process.hrtime)
+    ? (() => {
+        const anchorEpochNanos = BigInt(Date.now()) * 1000000n;
+        const anchorHrtime = process.hrtime.bigint();
+        return () => anchorEpochNanos + (process.hrtime.bigint() - anchorHrtime);
+      })()
+    : () => {
+        const epochMicros = Math.round((performance.timeOrigin + performance.now()) * 1000);
+        return BigInt(epochMicros) * 1000n;
+      };
+  ` +
+        // Generated code: enum mapping functions (getEnumIndex_${fieldName})
+        enumMappings.join('\n') +
+        `
+  ` +
+        // Generated code: SCHEMA_TYPES - maps clean field names to lmao types for runtime type detection
+        `const SCHEMA_TYPES = ${JSON.stringify(schemaTypeMap)};
+  ` +
+        // Generated code: PREFIX_MAPPING - maps clean names to prefixed column names
+        `const PREFIX_MAPPING = ${prefixMappingJson};
+  
+  class ${className} {
+    ` +
+        // Generated code: constructor stores buffer, createOverflowBuffer function, and scoped attributes
+        `constructor(buffer, createOverflowBuffer, initialScopedAttributes = {}) {
+      this._buffer = buffer;
+      this._createOverflowBuffer = createOverflowBuffer;
+      this._scopedAttributes = initialScopedAttributes;
+    }
+    ` +
+        // Generated code: tag getter returns this for chainable API (writes to row 0 = span-start)
+        `get tag() {
+      return this;
+    }
+    ` +
+        // Generated code: with() bulk attribute setting - maps clean names to prefixed columns,
+        // stores values directly (strings stored as-is), marks non-null (bit 0)
+        `with(attributes) {
+      const idx = 0;
+      for (const [cleanKey, value] of Object.entries(attributes)) {
+        const prefixedKey = PREFIX_MAPPING[cleanKey] || cleanKey;
+        const columnName = prefixedKey;
+        const column = this._buffer[columnName + '_values'];
+        if (column && value !== null && value !== undefined) {
+          column[idx] = value;
+          const nullBitmap = this._buffer[columnName + '_nulls'];
+          if (nullBitmap) {
+            nullBitmap[0] |= 1;
+          }
+        }
+      }
+      return this;
+    }
+    ` +
+        // Generated code: individual attribute setters (one per schema field)
+        attributeWriters.join('\n') +
+        `
+    ` +
+        // Generated code: scope() stores values in _scopedAttributes,
+        // then pre-fills remaining buffer capacity so future log entries inherit these values
+        `scope(attributes) {
+      for (const [cleanKey, value] of Object.entries(attributes)) {
+        if (value !== null && value !== undefined) {
+          this._scopedAttributes[cleanKey] = value;
+        }
+      }
+      const startIdx = this._buffer._writeIndex;
+      const endIdx = this._buffer._capacity;
+      for (let idx = startIdx; idx < endIdx; idx++) {
+        for (const [cleanKey, value] of Object.entries(this._scopedAttributes)) {
+          const prefixedKey = PREFIX_MAPPING[cleanKey] || cleanKey;
+          const columnName = prefixedKey;
+          const column = this._buffer[columnName + '_values'];
+          if (column) {
+            column[idx] = value;
+            const nullBitmap = this._buffer[columnName + '_nulls'];
+            if (nullBitmap) {
+              const byteIndex = Math.floor(idx / 8);
+              const bitOffset = idx % 8;
+              nullBitmap[byteIndex] |= (1 << bitOffset);
+            }
+          }
+        }
+      }
+    }
+    ` +
+        // Generated code: _writeMessage() writes a log entry - ensures buffer has space,
+        // writes entry type + timestamp + message, applies scoped attributes
+        `_writeMessage(entryType, message) {
+      // Check if buffer is full and create overflow buffer if needed
+      if (this._buffer._writeIndex >= this._buffer._capacity) {
+        const oldBuffer = this._buffer;
+        this._buffer = this._createOverflowBuffer(oldBuffer);
+        oldBuffer._overflow = this._buffer;
+      }
+      const idx = this._buffer._writeIndex;
+      this._buffer.entry_type[idx] = entryType;
+      this._buffer.timestamp[idx] = getTimestampNanos(this._buffer._traceRoot.anchorEpochNanos, this._buffer._traceRoot.anchorPerfNow);
+      const messageColumn = this._buffer.message_values;
+      if (messageColumn) {
+        messageColumn[idx] = message;
+        const nullBitmap = this._buffer.message_nulls;
+        if (nullBitmap) {
+          const byteIndex = Math.floor(idx / 8);
+          const bitOffset = idx % 8;
+          nullBitmap[byteIndex] |= (1 << bitOffset);
+        }
+      }
+      for (const [cleanKey, value] of Object.entries(this._scopedAttributes)) {
+        const prefixedKey = PREFIX_MAPPING[cleanKey] || cleanKey;
+        const columnName = prefixedKey;
+        const column = this._buffer[columnName + '_values'];
+        if (column) {
+          column[idx] = value;
+          const nullBitmap = this._buffer[columnName + '_nulls'];
+          if (nullBitmap) {
+            const byteIndex = Math.floor(idx / 8);
+            const bitOffset = idx % 8;
+            nullBitmap[byteIndex] |= (1 << bitOffset);
+          }
+        }
+      }
+      this._buffer._writeIndex++;
+    }
+    ` +
+        // Generated code: message() generic logging with level string mapping to entry type constants
+        `message(level, message) {
+      const entryTypeMap = {
+        'info': ${ENTRY_TYPE_INFO},
+        'debug': ${ENTRY_TYPE_DEBUG},
+        'warn': ${ENTRY_TYPE_WARN},
+        'error': ${ENTRY_TYPE_ERROR},
+        'trace': ${ENTRY_TYPE_TRACE}
+      };
+      this._writeMessage(entryTypeMap[level] || ${ENTRY_TYPE_INFO}, message);
+    }
+    ` +
+        // Generated code: convenience logging methods - each calls _writeMessage with entry type constant
+        `info(message) { this._writeMessage(${ENTRY_TYPE_INFO}, message); }
+    debug(message) { this._writeMessage(${ENTRY_TYPE_DEBUG}, message); }
+    warn(message) { this._writeMessage(${ENTRY_TYPE_WARN}, message); }
+    error(message) { this._writeMessage(${ENTRY_TYPE_ERROR}, message); }
+    trace(message) { this._writeMessage(${ENTRY_TYPE_TRACE}, message); }
+  }
+  return ${className};
+})()`;
+    return classCode;
+}
+/**
+ * Create a remapped SpanLogger class constructor from clean schema and prefix mapping
+ *
+ * WHY: This is the cold-path function called at module creation time. It compiles
+ * the generated class code once and caches the constructor.
+ *
+ * @param cleanSchema - Clean schema (without prefix)
+ * @param prefixMapping - Mapping from clean names to prefixed names
+ * @returns Constructor for the remapped SpanLogger class
+ */
+export function createRemappedSpanLoggerClass(cleanSchema, prefixMapping) {
+    // Check cache first
+    const cacheKey = createSchemaAndMappingCacheKey(cleanSchema, prefixMapping);
+    const cached = remappedSpanLoggerClassCache.get(cacheKey);
+    if (cached && isRemappedSpanLoggerClass(cached)) {
+        return cached;
+    }
+    const classCode = generateRemappedSpanLoggerClass(cleanSchema, prefixMapping).trim();
+    const GeneratedClass = new Function(`return ${classCode}`)();
+    if (!isRemappedSpanLoggerClass(GeneratedClass)) {
+        throw new TypeError('Generated remapped span logger is missing required logging methods');
+    }
+    remappedSpanLoggerClassCache.set(cacheKey, GeneratedClass);
+    return GeneratedClass;
+}

package/dist/lib/logApi.d.ts

@@ -0,0 +1,61 @@
+/**
+ * LogAPI - Simple logging interface for contexts that need structured logging
+ * without direct access to a SpanBuffer.
+ *
+ * Used by:
+ * - Other contexts where a simplified logging interface is needed
+ *
+ * Unlike SpanLogger which is tightly coupled to a SpanBuffer and returns
+ * FluentLogEntry for chaining, LogAPI is a simple fire-and-forget interface
+ * that can be backed by any logging implementation.
+ */
+/**
+ * Structured logging API.
+ *
+ * Provides info/warn/error/debug methods with optional structured data.
+ * Implementation determines where logs are written (span buffer, console, etc).
+ *
+ * @example
+ * ```typescript
+ * function decide(ctx) {
+ *   ctx.log.info('Processing order', { orderId: ctx.instanceId });
+ *   if (!ctx.state.inventory) {
+ *     ctx.log.warn('No inventory data', { state: ctx.state });
+ *   }
+ * }
+ * ```
+ */
+export interface LogAPI {
+    /**
+     * Log at info level.
+     * @param message - Log message
+     * @param data - Optional structured data to include with the log
+     */
+    info(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log at warn level.
+     * @param message - Log message
+     * @param data - Optional structured data to include with the log
+     */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log at error level.
+     * @param message - Log message
+     * @param data - Optional structured data to include with the log
+     */
+    error(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log at debug level.
+     * @param message - Log message
+     * @param data - Optional structured data to include with the log
+     */
+    debug(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * No-op LogAPI implementation.
+ *
+ * Used when tracing is disabled or for testing contexts that don't
+ * need actual logging.
+ */
+export declare const noopLogAPI: LogAPI;
+//# sourceMappingURL=logApi.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logApi.d.ts","sourceRoot":"","sources":["../../src/lib/logApi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE5D;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE5D;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7D;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9D;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,MAKxB,CAAC"}

package/dist/lib/logApi.js

@@ -0,0 +1,12 @@
+/**
+ * No-op LogAPI implementation.
+ *
+ * Used when tracing is disabled or for testing contexts that don't
+ * need actual logging.
+ */
+export const noopLogAPI = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    debug: () => { },
+};