@smoothbricks/lmao 0.1.0

package/dist/lib/spanContext.js

@@ -0,0 +1,763 @@
+import { createTagWriter } from './codegen/fixedPositionWriterGenerator.js';
+import { createSpanLogger as createSpanLoggerFromGenerator, } from './codegen/spanLoggerGenerator.js';
+import { Blocked } from './errors/Blocked.js';
+import { TransientError } from './errors/Transient.js';
+import { Op } from './op.js';
+import { Err, hasErrorCode, Ok } from './result.js';
+import { ENTRY_TYPE_SPAN_ERR, ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_OK, ENTRY_TYPE_SPAN_RETRY, } from './schema/systemSchema.js';
+// Note: TraceRoot.writeSpanStart() is used instead of direct timestamp writes.
+// The platform-specific TraceRoot (traceRoot.es.ts or traceRoot.node.ts) handles
+// timestamp calculation and writes to buffer._system columns.
+// =============================================================================
+// SpanContext Symbol Marker
+// =============================================================================
+/**
+ * Internal symbol to mark span contexts
+ * Used for type guards and prototype chain detection
+ */
+export const SPAN_CONTEXT_MARKER = Symbol.for('lmao.SpanContext');
+function isOpInstance(value) {
+    return value instanceof Op;
+}
+// WHY: resolveSpanTarget() accepts either an Op instance or a raw span
+// function. TypeScript needs an explicit predicate here to preserve the call
+// signature when the non-Op branch passes `value` through as `fn`.
+function isSpanDispatchFn(value) {
+    return typeof value === 'function';
+}
+function isSpanBufferConstructorForSchema(value, schema) {
+    return (typeof value === 'function' &&
+        Reflect.get(value, 'schema') === schema &&
+        typeof Reflect.get(value, 'stats') === 'object');
+}
+function getBufferConstructor(buffer) {
+    const ctor = buffer.constructor;
+    if (!isSpanBufferConstructorForSchema(ctor, buffer._logSchema)) {
+        throw new TypeError('Span buffer constructor does not match the buffer schema');
+    }
+    return ctor;
+}
+function isSpanBufferForSchema(buffer, schema) {
+    return (typeof buffer === 'object' &&
+        buffer !== null &&
+        Reflect.get(buffer, '_logSchema') === schema &&
+        isSpanBufferConstructorForSchema(Reflect.get(buffer, 'constructor'), schema));
+}
+function isSpanContextInstance(value) {
+    return (isSpanContext(value) &&
+        Reflect.has(value, '_buffer') &&
+        Reflect.has(value, '_spanLogger') &&
+        Reflect.has(value, '_schema'));
+}
+function createInheritedContext(parent) {
+    const child = Object.create(parent);
+    if (!isSpanContextInstance(child)) {
+        throw new TypeError('Failed to create child span context');
+    }
+    return child;
+}
+function createInheritedContextWithOverrides(parent, overrides) {
+    const child = Object.assign(Object.create(parent), overrides);
+    if (!isSpanContextInstance(child)) {
+        throw new TypeError('Failed to create overridden child span context');
+    }
+    return child;
+}
+function readStringArgument(args, index, label) {
+    const value = args[index];
+    if (typeof value !== 'string') {
+        throw new TypeError(`${label} must be a string`);
+    }
+    return value;
+}
+function resolveSpanTarget(value, fallbackBuffer) {
+    if (isOpInstance(value)) {
+        return {
+            SpanBufferClass: value.SpanBufferClass,
+            remappedViewClass: value.remappedViewClass,
+            opMetadata: value.metadata,
+            fn: value.fn,
+        };
+    }
+    if (!isSpanDispatchFn(value)) {
+        throw new TypeError('span() expects an Op or function');
+    }
+    return {
+        SpanBufferClass: getBufferConstructor(fallbackBuffer),
+        remappedViewClass: undefined,
+        opMetadata: fallbackBuffer._opMetadata,
+        fn: value,
+    };
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Write span-start entry to buffer at row 0 (fixed layout)
+ * Pre-initialize row 1 as span-exception (will be overwritten by ok/err)
+ * Set writeIndex to 2 (events start after reserved rows)
+ *
+ * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+ * - Row 0: span-start (written here)
+ * - Row 1: span-end (pre-initialized as exception, overwritten by ok/err)
+ * - Row 2+: events (ctx.log.* appends here)
+ *
+ * @param buffer - SpanBuffer to write to
+ * @param spanName - Name for this span
+ */
+export function writeSpanStart(buffer, spanName) {
+    // Delegate to TraceRoot - platform-specific implementation handles timestamps
+    buffer._traceRoot.writeSpanStart(buffer, spanName);
+}
+/**
+ * Create a SpanLogger for the given buffer.
+ *
+ * Per specs/lmao/01i_span_scope_attributes.md: Scope values are stored directly on buffer._scopeValues.
+ * The SpanLogger reads/writes scope via buffer._scopeValues - no separate Scope class needed.
+ *
+ * @param schema - Tag attribute schema with field definitions
+ * @param buffer - SpanBuffer to write entries to (per-span instance)
+ * @returns SpanLogger with typed methods matching schema
+ */
+export function createSpanLogger(schema, buffer) {
+    return createSpanLoggerFromGenerator(schema, buffer);
+}
+/**
+ * Calculate delay for retry based on policy and attempt number.
+ *
+ * @param policy - RetryPolicy from TransientError
+ * @param attempt - Current attempt number (1-indexed)
+ * @returns Delay in milliseconds before next retry
+ */
+function calculateDelay(policy, attempt) {
+    let delay;
+    switch (policy.backoff) {
+        case 'exponential':
+            // Delay doubles each attempt: baseDelay * 2^(attempt-1)
+            delay = Math.min(policy.baseDelayMs * 2 ** (attempt - 1), policy.maxDelayMs ?? 30000);
+            break;
+        case 'linear':
+            // Delay increases linearly: baseDelay * attempt
+            delay = Math.min(policy.baseDelayMs * attempt, policy.maxDelayMs ?? 30000);
+            break;
+        case 'fixed':
+            // Same delay between each attempt
+            delay = policy.baseDelayMs;
+            break;
+        default:
+            delay = policy.baseDelayMs;
+    }
+    // Apply jitter if enabled (default true) - random value between 0 and delay
+    if (policy.jitter !== false) {
+        delay = Math.floor(Math.random() * delay);
+    }
+    return delay;
+}
+/**
+ * Write span-retry entry to buffer.
+ *
+ * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+ * - span-retry appends to Row 2+ in parent span buffer (like log entries)
+ * - Trace-only entry (NOT written to event log)
+ * - Contains: attempt number, error code, and delay until next attempt
+ *
+ * @param buffer - SpanBuffer to write to (appends at _writeIndex)
+ * @param attempt - Attempt number (1-indexed)
+ * @param error - TransientError that triggered the retry
+ * @param delayMs - Delay before next attempt
+ */
+function writeRetryEntry(buffer, attempt, error, delayMs) {
+    // Get current write index and advance for next write
+    const index = buffer._writeIndex;
+    // Write entry via TraceRoot for timestamp handling
+    // TraceRoot.writeLogEntry writes timestamp and entry_type at the given index
+    buffer._traceRoot.writeLogEntry(buffer, ENTRY_TYPE_SPAN_RETRY);
+    // Write retry-specific message: retry:op:{opName} for prefix-based querying
+    const opName = buffer._opMetadata?.name ?? 'unknown';
+    buffer.message(index, `retry:op:${opName}`);
+    // Write error code if available
+    if (error.code) {
+        buffer.error_code(index, error.code);
+    }
+    // Retry metadata fields for direct queryability in Arrow output
+    buffer.retry_attempt(index, attempt);
+    buffer.retry_delay_ms(index, delayMs);
+}
+/**
+ * Sleep for the specified duration.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Promise that resolves after the delay
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute function with retry loop for TransientError handling.
+ *
+ * Per plan 19-03: Op class handles retry loop internally.
+ * - TransientError from op body triggers retry based on error.policy
+ * - Retry respects maxAttempts from TransientError.policy
+ * - span-retry entry written for each transient failure
+ * - Only final result written as span-ok or span-err
+ * - BlockedError returns immediately without retry
+ *
+ * @param buffer - SpanBuffer to write retry entries to
+ * @param fn - Function to execute (may be retried)
+ * @returns Final result (success, non-transient error, or exhausted transient error)
+ */
+async function executeWithRetry(buffer, fn) {
+    let attempt = 0;
+    while (true) {
+        attempt++;
+        // Execute the function
+        const result = await fn();
+        // Success - return immediately
+        if (result instanceof Ok) {
+            return result;
+        }
+        // Error result - check error type for retry behavior
+        const error = result.error;
+        // BlockedError - return immediately, no retry
+        if (error instanceof Blocked) {
+            return result;
+        }
+        // TransientError - check if we should retry
+        if (error instanceof TransientError) {
+            const { policy } = error;
+            // Check attempt limit (maxAttempts includes initial attempt)
+            if (attempt >= policy.maxAttempts) {
+                // Exhausted - return final error
+                return result;
+            }
+            // Calculate delay based on policy and attempt number
+            const delay = calculateDelay(policy, attempt);
+            // Write span-retry entry to buffer for observability
+            writeRetryEntry(buffer, attempt, error, delay);
+            // Wait before retry
+            await sleep(delay);
+            continue;
+        }
+        // Non-transient error - return immediately
+        return result;
+    }
+}
+/**
+ * Write span-end entry to buffer at row 1.
+ *
+ * Called by span methods after fn() returns to write:
+ * - entry_type (SPAN_OK or SPAN_ERR based on result instanceof)
+ * - timestamp
+ * - error_code (for Err only)
+ * - result row attributes already written eagerly by the fixed-position ResultWriter
+ *
+ * @param buffer - SpanBuffer to write to
+ * @param result - The result returned by the span function
+ */
+export function writeSpanEnd(buffer, result) {
+    // Write entry_type and timestamp via TraceRoot (platform-specific)
+    if (result instanceof Ok) {
+        buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_OK);
+    }
+    else if (result instanceof Err) {
+        buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_ERR);
+        // Write error_code if the error has a code property
+        if (hasErrorCode(result.error)) {
+            buffer.error_code(1, result.error.code);
+        }
+    }
+}
+// =============================================================================
+// SpanContext Class Factory
+// =============================================================================
+/**
+ * Create a SpanContext class for the given schema and logBinding.
+ *
+ * The returned class:
+ * - Closes over schema/logBinding (available to all methods)
+ * - Constructor takes buffer, spanLogger, tag directly (no temp object allocation)
+ * - Uses prototype methods for internal methods (_spanPre, _spanException, span0-span8)
+ * - Supports context inheritance via Object.create(parent) for child spans
+ * - Supports context overrides via own properties shadowing inherited ones
+ *
+ * @param schemaOnly - Tag attribute schema
+ * @param logBinding - LogBinding with schema and stats
+ * @returns Class constructor for SpanContext instances
+ */
+export function createSpanContextClass(_schemaOnly, logBinding) {
+    /**
+     * SpanContext implementation class.
+     *
+     * Constructor takes core values directly so arrow functions can close over them,
+     * avoiding both temp object allocation and property lookups in hot paths.
+     */
+    class SpanContextImpl {
+        // Core properties set via constructor
+        _buffer;
+        _schema;
+        _spanLogger;
+        _logBinding = logBinding;
+        // User-facing properties
+        tag;
+        log;
+        ff;
+        deps;
+        // Arrow functions that close over constructor args directly
+        setScope;
+        ok;
+        err;
+        span;
+        spanSync;
+        constructor(buffer, schema, spanLogger, tag) {
+            this._buffer = buffer;
+            this._schema = schema;
+            this._spanLogger = spanLogger;
+            this.tag = tag;
+            this.log = spanLogger;
+            // Regular functions close over constructor args directly - no property lookups
+            // Using regular function (not arrow) allows destructuring while closing over args
+            this.setScope = (attributes) => {
+                spanLogger._setScope(attributes ?? {});
+            };
+            this.ok = (value) => new Ok(value, schema, buffer);
+            this.err = (error) => new Err(error, schema, buffer);
+            // span uses regular function to access `arguments` (no ...rest spread allocation)
+            // Closes over `self` for calling prototype methods
+            // Named function for better stack traces
+            const self = this;
+            const span = function span(nameOrLine, _arg1, _arg2, _arg3, _arg4, _arg5, _arg6, _arg7, _arg8, _arg9, _arg10, _arg11) {
+                // Use arguments.length instead of ...rest to avoid array allocation
+                const len = arguments.length;
+                // Detect call pattern:
+                // - span(name, fn) - len=2, typeof arg0 === 'string'
+                // - span(line, name, fn) - len=3, typeof arg0 === 'number'
+                // - span(name, overrides, fn) - len=3, typeof arg0 === 'string', typeof arg1 === 'object'
+                // - span(line, name, overrides, fn) - len=4, typeof arg0 === 'number', typeof arg2 === 'object'
+                // Plus additional args for span arguments
+                const hasLine = typeof nameOrLine === 'number';
+                const spanLine = hasLine ? nameOrLine : 0;
+                const spanName = hasLine ? readStringArgument(arguments, 1, 'span name') : nameOrLine;
+                // Index where fn/op or overrides starts
+                const checkIdx = hasLine ? 2 : 1;
+                const maybeOverrides = arguments[checkIdx];
+                // Check if it's an overrides object (not Op, not function)
+                const hasOverrides = maybeOverrides !== null &&
+                    typeof maybeOverrides === 'object' &&
+                    !(maybeOverrides instanceof Op) &&
+                    typeof maybeOverrides !== 'function';
+                const fnIdx = checkIdx + (hasOverrides ? 1 : 0);
+                const target = resolveSpanTarget(arguments[fnIdx], self._buffer);
+                // Create child context - use _newCtx0 or _newCtx1 based on overrides
+                const childCtx = hasOverrides ? self._newCtx1(maybeOverrides) : self._newCtx0();
+                // Dispatch to monomorphic methods with all Op properties extracted
+                const argCount = len - fnIdx - 1;
+                switch (argCount) {
+                    case 0:
+                        return self.span0(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn);
+                    case 1:
+                        return self.span1(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1]);
+                    case 2:
+                        return self.span2(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2]);
+                    case 3:
+                        return self.span3(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3]);
+                    case 4:
+                        return self.span4(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4]);
+                    case 5:
+                        return self.span5(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5]);
+                    case 6:
+                        return self.span6(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5], arguments[fnIdx + 6]);
+                    case 7:
+                        return self.span7(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5], arguments[fnIdx + 6], arguments[fnIdx + 7]);
+                    case 8:
+                        return self.span8(spanLine, spanName, childCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5], arguments[fnIdx + 6], arguments[fnIdx + 7], arguments[fnIdx + 8]);
+                    default:
+                        throw new Error(`span() supports up to 8 arguments, got ${argCount}`);
+                }
+            };
+            this.span = span;
+            this.spanSync = function spanSync(name, fn) {
+                const childCtx = self._newCtx0();
+                return self.spanSync0(0, name, childCtx, getBufferConstructor(self._buffer), undefined, self._buffer._opMetadata, fn);
+            };
+        }
+        // =========================================================================
+        // Getters (on prototype, inherited by children)
+        // =========================================================================
+        get [SPAN_CONTEXT_MARKER]() {
+            return true;
+        }
+        get module() {
+            return this._buffer._opMetadata;
+        }
+        get callee_package() {
+            return this._buffer._opMetadata.package_name;
+        }
+        get callee_file() {
+            return this._buffer._opMetadata.package_file;
+        }
+        get callee_line() {
+            // Access the line_values array directly to read line number at row 0
+            // line_values is a Float64Array per the system schema (LazyNumberSchema)
+            return this._buffer.line_values[0];
+        }
+        get callee_git_sha() {
+            return this._buffer._opMetadata.git_sha;
+        }
+        get buffer() {
+            return this._buffer;
+        }
+        get scope() {
+            return this._buffer._scopeValues;
+        }
+        // =========================================================================
+        // Internal methods (on prototype)
+        // =========================================================================
+        /**
+         * Create a new child context with prototype chain inheritance.
+         * Called by transformer for spans without overrides.
+         *
+         * Transformer emits: ctx.span0(line, name, ctx._newCtx0(), fn)
+         */
+        _newCtx0() {
+            return createInheritedContext(this);
+        }
+        /**
+         * Create a new child context with prototype chain inheritance + user overrides.
+         * Called by transformer for spans with overrides.
+         *
+         * Transformer emits: ctx.span0(line, name, ctx._newCtx1({ requestId }), fn)
+         */
+        _newCtx1(overrides) {
+            return createInheritedContextWithOverrides(this, overrides);
+        }
+        /**
+         * Complete child span context setup - creates buffer, registers with parent.
+         * Called by span0-span8 after _newCtx0/_newCtx1 has created the prototype chain.
+         *
+         * Properties are set in HOT→COLD order per specs/lmao/01b1_buffer_performance_optimizations.md
+         * to ensure frequently-accessed properties get V8 in-object slots.
+         *
+         * @param childCtx - Child context created by _newCtx0 or _newCtx1
+         * @param line - Source line number (0 if not provided by transformer)
+         * @param name - Child span name
+         * @param SpanBufferClass - Buffer class to use (Op's class or parent's class for plain functions)
+         * @param remappedViewClass - Optional view class for prefixed ops (wraps buffer for Arrow conversion)
+         * @param opMetadata - Metadata for the executing op (Op's metadata or parent's for plain functions)
+         */
+        _spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata) {
+            // Get Op's schema for cross-library calls (child may have different schema than parent)
+            const childSchema = SpanBufferClass.schema;
+            // Use buffer strategy for child span creation (supports both JS and WASM buffers)
+            // Pass schema for cross-library calls where child has different schema than parent
+            const createdBuffer = this._buffer._traceRoot.tracer.bufferStrategy.createChildSpanBuffer(this._buffer, // parentBuffer
+            this._buffer._opMetadata, // callsiteMetadata - WHO called span() (for row 0)
+            opMetadata, // opMetadata - WHICH op is executing (for rows 1+)
+            undefined, // capacity - use default
+            childSchema);
+            if (!isSpanBufferForSchema(createdBuffer, childSchema)) {
+                throw new TypeError('Child span buffer does not match the requested schema');
+            }
+            const childBuffer = createdBuffer;
+            // Why wrap buffer: RemappedBufferView translates prefixed column names during Arrow conversion
+            // Parent sees remapped names, child sees unprefixed names (transparent to child)
+            const bufferOrView = remappedViewClass ? new remappedViewClass(childBuffer) : childBuffer;
+            // Why push wrapped buffer: Parent's _children see remapped names for Arrow conversion
+            this._buffer._children.push(bufferOrView);
+            // Write span-start for child span (row 0) and pre-initialize span-end (row 1)
+            writeSpanStart(childBuffer, name);
+            // Write line number to row 0 (line() takes pos and value)
+            childBuffer.line(0, line);
+            const childLogger = createSpanLogger(childSchema, childBuffer);
+            const childTagAPI = createTagWriter(childSchema, childBuffer);
+            // Cast to impl for property assignment
+            const ctx = childCtx;
+            // ═══════════════════════════════════════════════════════════════════
+            // PROPERTY ASSIGNMENT ORDER: HOT → COLD (V8 in-object slots optimization)
+            // First ~10-12 properties get fast in-object slots per spec
+            // ═══════════════════════════════════════════════════════════════════
+            // SLOT 1-4: HOTTEST - accessed on every span operation
+            ctx._buffer = childBuffer;
+            ctx._spanLogger = childLogger;
+            ctx.tag = childTagAPI;
+            ctx.log = childLogger;
+            // SLOT 5-7: HOT - reserved keys copied from parent for O(1) access
+            ctx.deps = this.deps;
+            // Create child-bound FF evaluator so flag access logs to child buffer
+            // If no evaluator (ff is EMPTY_SCOPE), just copy the reference
+            ctx.ff = this.ff.forContext ? this.ff.forContext(ctx) : this.ff;
+            // Note: user-defined extras (env, requestId, etc.) inherited via prototype chain
+            // SLOT 8-11: WARM - function properties (created per-context for destructuring)
+            // Regular functions close over local variables directly - no property lookups
+            const childSpan = function span(nameOrLine, _arg1, _arg2, _arg3, _arg4, _arg5, _arg6, _arg7, _arg8, _arg9, _arg10, _arg11) {
+                const len = arguments.length;
+                const hasLine = typeof nameOrLine === 'number';
+                const spanLine = hasLine ? nameOrLine : 0;
+                const spanName = hasLine ? readStringArgument(arguments, 1, 'span name') : nameOrLine;
+                const checkIdx = hasLine ? 2 : 1;
+                const maybeOverrides = arguments[checkIdx];
+                const hasOverrides = maybeOverrides !== null &&
+                    typeof maybeOverrides === 'object' &&
+                    !(maybeOverrides instanceof Op) &&
+                    typeof maybeOverrides !== 'function';
+                const fnIdx = checkIdx + (hasOverrides ? 1 : 0);
+                const target = resolveSpanTarget(arguments[fnIdx], childBuffer);
+                // Create child context - use _newCtx0 or _newCtx1 based on overrides
+                const newChildCtx = hasOverrides ? ctx._newCtx1(maybeOverrides) : ctx._newCtx0();
+                const argCount = len - fnIdx - 1;
+                switch (argCount) {
+                    case 0:
+                        return ctx.span0(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn);
+                    case 1:
+                        return ctx.span1(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1]);
+                    case 2:
+                        return ctx.span2(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2]);
+                    case 3:
+                        return ctx.span3(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3]);
+                    case 4:
+                        return ctx.span4(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4]);
+                    case 5:
+                        return ctx.span5(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5]);
+                    case 6:
+                        return ctx.span6(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5], arguments[fnIdx + 6]);
+                    case 7:
+                        return ctx.span7(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5], arguments[fnIdx + 6], arguments[fnIdx + 7]);
+                    case 8:
+                        return ctx.span8(spanLine, spanName, newChildCtx, target.SpanBufferClass, target.remappedViewClass, target.opMetadata, target.fn, arguments[fnIdx + 1], arguments[fnIdx + 2], arguments[fnIdx + 3], arguments[fnIdx + 4], arguments[fnIdx + 5], arguments[fnIdx + 6], arguments[fnIdx + 7], arguments[fnIdx + 8]);
+                    default:
+                        throw new Error(`span() supports up to 8 arguments, got ${argCount}`);
+                }
+            };
+            ctx.span = childSpan;
+            ctx.spanSync = function spanSync(name, fn) {
+                const newChildCtx = ctx._newCtx0();
+                return ctx.spanSync0(0, name, newChildCtx, getBufferConstructor(childBuffer), undefined, childBuffer._opMetadata, fn);
+            };
+            ctx.ok = function ok(value) {
+                return new Ok(value, childSchema, childBuffer);
+            };
+            ctx.err = function err(error) {
+                return new Err(error, childSchema, childBuffer);
+            };
+            ctx.setScope = function setScope(attributes) {
+                childLogger._setScope(attributes ?? {});
+            };
+            // SLOT 12+: COLD - internal/rarely accessed
+            ctx._schema = childSchema;
+            ctx._logBinding = logBinding;
+            return ctx;
+        }
+        /**
+         * Handle span exception - writes exception details to row 1.
+         * Called in catch blocks of span methods.
+         */
+        _spanException(childBuffer, error) {
+            // Write entry_type and timestamp via TraceRoot (platform-specific)
+            childBuffer._traceRoot.writeSpanEnd(childBuffer, ENTRY_TYPE_SPAN_EXCEPTION);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            childBuffer.message(1, errorMessage);
+            if (errorStack) {
+                childBuffer.exception_stack(1, errorStack);
+            }
+        }
+        // =========================================================================
+        // Monomorphic span methods (for transformer output)
+        // Transformer emits: ctx.span0(line, name, ctx, fn) or
+        //                    ctx.span0(line, name, Object.assign(Object.create(ctx), overrides), fn)
+        // childCtx inherits from parent via prototype chain, may have user overrides as own properties
+        // =========================================================================
+        spanSync0(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                const result = fn(ctx);
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span0(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span1(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span2(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1, a2) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1, a2));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span3(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1, a2, a3) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1, a2, a3));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span4(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1, a2, a3, a4) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1, a2, a3, a4));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span5(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1, a2, a3, a4, a5) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1, a2, a3, a4, a5));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span6(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1, a2, a3, a4, a5, a6) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1, a2, a3, a4, a5, a6));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span7(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1, a2, a3, a4, a5, a6, a7) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1, a2, a3, a4, a5, a6, a7));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+        async span8(line, name, childCtx, SpanBufferClass, remappedViewClass, opMetadata, fn, a1, a2, a3, a4, a5, a6, a7, a8) {
+            const ctx = this._spanPre(childCtx, line, name, SpanBufferClass, remappedViewClass, opMetadata);
+            const buffer = ctx._buffer;
+            buffer._traceRoot.tracer.onSpanStart(buffer);
+            try {
+                // Execute with retry loop - TransientError triggers retry, BlockedError returns immediately
+                const result = await executeWithRetry(buffer, () => fn(ctx, a1, a2, a3, a4, a5, a6, a7, a8));
+                writeSpanEnd(buffer, result);
+                return result;
+            }
+            catch (error) {
+                this._spanException(buffer, error);
+                throw error;
+            }
+            finally {
+                buffer._traceRoot.tracer.onSpanEnd(buffer);
+            }
+        }
+    }
+    const SpanContextCtor = SpanContextImpl;
+    return SpanContextCtor;
+}
+// =============================================================================
+// Type Guard
+// =============================================================================
+/**
+ * Type guard to check if a value is a SpanContext
+ */
+export function isSpanContext(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        SPAN_CONTEXT_MARKER in value &&
+        Reflect.get(value, SPAN_CONTEXT_MARKER) === true);
+}