@smoothbricks/lmao 0.1.0

package/src/lib/threadId.ts

@@ -0,0 +1,135 @@
+/**
+ * Thread ID - Process-level unique identifier for distributed span identification
+ *
+ * Each worker/process gets a unique 64-bit random ID that remains constant
+ * for the lifetime of the process. Combined with a local incrementing counter,
+ * this provides globally unique span IDs without coordination.
+ *
+ * The thread ID is stored as raw bytes (Uint8Array) to enable zero-copy
+ * writes to SpanBuffer identity sections.
+ *
+ * ## Module-level = Per-Process/Worker Singleton
+ *
+ * ES modules are instantiated once per JavaScript realm:
+ * - **Node.js main process**: One thread ID per process
+ * - **Node.js worker_threads**: Each Worker gets its own module instance → own thread ID
+ * - **Browser main thread**: One thread ID
+ * - **Web Workers**: Each Worker gets its own module instance → own thread ID
+ *
+ * This is exactly what we want: each "thread of execution" automatically gets
+ * a unique ID without any explicit thread-local storage API.
+ *
+ * @module threadId
+ */
+
+/** Thread ID size in bytes */
+export const THREAD_ID_BYTES = 8;
+
+/** Process-level thread ID bytes (lazily initialized) */
+let threadIdBytes: Uint8Array | null = null;
+
+/** Cached BigInt representation (lazily computed) */
+let threadIdBigInt: bigint | null = null;
+
+/**
+ * Ensure thread ID is initialized.
+ * Called lazily on first access.
+ */
+function ensureInitialized(): void {
+  if (threadIdBytes !== null) return;
+
+  threadIdBytes = new Uint8Array(THREAD_ID_BYTES);
+
+  // Use Web Crypto API - available in browsers, Node 19+, Deno, Bun, Workers
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    crypto.getRandomValues(threadIdBytes);
+    return;
+  }
+
+  // For Node.js < 19, try to use node:crypto
+  try {
+    const nodeCrypto = require('node:crypto');
+    if (nodeCrypto && typeof nodeCrypto.randomFillSync === 'function') {
+      nodeCrypto.randomFillSync(threadIdBytes);
+      return;
+    }
+  } catch {
+    // node:crypto not available
+  }
+
+  throw new Error(
+    'crypto.getRandomValues is not available. ' +
+      'For React Native, install and import "react-native-get-random-values" before using this library.',
+  );
+}
+
+/**
+ * Copy the process thread ID bytes to a destination buffer.
+ * This is the primary hot-path API for SpanBuffer construction.
+ *
+ * @param dest - Destination Uint8Array
+ * @param offset - Byte offset in destination
+ */
+export function copyThreadIdTo(dest: Uint8Array, offset: number): void {
+  ensureInitialized();
+  if (!threadIdBytes) {
+    throw new Error('ThreadId bytes not initialized');
+  }
+  dest.set(threadIdBytes, offset);
+}
+
+/**
+ * Get the process thread ID as a BigInt.
+ * Use copyThreadIdTo() for hot-path writes; this is for Arrow conversion.
+ *
+ * @returns 64-bit thread ID as BigInt
+ */
+export function getThreadId(): bigint {
+  ensureInitialized();
+  if (threadIdBigInt === null) {
+    if (!threadIdBytes) {
+      throw new Error('ThreadId bytes not initialized');
+    }
+    const b = threadIdBytes;
+    // Little-endian conversion to match identity byte layout
+    threadIdBigInt =
+      BigInt(b[0]) |
+      (BigInt(b[1]) << 8n) |
+      (BigInt(b[2]) << 16n) |
+      (BigInt(b[3]) << 24n) |
+      (BigInt(b[4]) << 32n) |
+      (BigInt(b[5]) << 40n) |
+      (BigInt(b[6]) << 48n) |
+      (BigInt(b[7]) << 56n);
+  }
+  return threadIdBigInt;
+}
+
+/**
+ * Write the process thread ID to a BigUint64Array at the given index.
+ * Avoids BigInt conversion by writing bytes directly to the underlying buffer.
+ *
+ * @param dest - Destination BigUint64Array
+ * @param index - Element index (not byte offset)
+ */
+export function writeThreadIdToUint64Array(dest: BigUint64Array, index: number): void {
+  ensureInitialized();
+  if (!threadIdBytes) {
+    throw new Error('ThreadId bytes not initialized');
+  }
+  const byteView = new Uint8Array(dest.buffer, dest.byteOffset + index * 8, 8);
+  byteView.set(threadIdBytes);
+}
+
+/**
+ * Reset thread ID for testing purposes only.
+ *
+ * **WARNING**: Only use in tests! Resetting in production would break
+ * span ID uniqueness guarantees.
+ *
+ * @internal
+ */
+export function _resetThreadId(): void {
+  threadIdBytes = null;
+  threadIdBigInt = null;
+}

package/src/lib/traceContext.ts

@@ -0,0 +1,182 @@
+/**
+ * TraceContext Types and Prototype System
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md and specs/lmao/01l_op_context_pattern.md:
+ * - TraceContext is created via module.traceContext() at request entry
+ * - Uses prototype-based inheritance for V8 hidden class optimization
+ * - Contains system properties (traceId, timestamps, threadId) + user Extra
+ */
+
+import type { OpContext } from './opContext/types.js';
+import type { Result } from './result.js';
+import type { FeatureFlagSchema } from './schema/defineFeatureFlags.js';
+import type { FlagEvaluator } from './schema/evaluator.js';
+import type { LogSchema } from './schema/types.js';
+import type { TraceId } from './traceId.js';
+
+// =============================================================================
+// Reserved Keys
+// =============================================================================
+
+/**
+ * Reserved keys that Extra cannot contain (compile-time enforcement)
+ *
+ * Per spec 01l lines 379-386
+ */
+export type ReservedTraceContextKeys = 'traceId' | 'anchorEpochMicros' | 'anchorPerfNow' | 'threadId' | 'ff' | 'span';
+
+// =============================================================================
+// Op Type (imported from op.ts)
+// =============================================================================
+
+/**
+ * Op type - traced operation
+ *
+ * Imported from op.ts to break circular dependency.
+ * The actual Op class is defined in op.ts.
+ */
+import type { Op } from './op.js';
+
+export type { Op } from './op.js';
+
+// =============================================================================
+// RootSpanFn Type
+// =============================================================================
+
+/**
+ * Function type for ctx.span() at the root level
+ *
+ * Per spec 01c lines 243-244 and experiment exp7-full-ctx.ts lines 253-259:
+ * Supports both with and without line number (transformer injects line number)
+ *
+ * The first argument (lineNumber) is injected by the transformer.
+ */
+export type RootSpanFn = {
+  // Overload 1: With line number (transformer output)
+  <Ctx extends OpContext, Args extends unknown[], S, E>(
+    line: number,
+    name: string,
+    op: Op<Ctx, Args, S, E>,
+    ...args: Args
+  ): Promise<Result<S, E>>;
+  // Overload 2: Without line number (user writes)
+  <Ctx extends OpContext, Args extends unknown[], S, E>(
+    name: string,
+    op: Op<Ctx, Args, S, E>,
+    ...args: Args
+  ): Promise<Result<S, E>>;
+};
+
+// =============================================================================
+// TraceContext Interface
+// =============================================================================
+
+/**
+ * TraceContext system properties - root context created via module.traceContext()
+ *
+ * Per spec 01c lines 206-216 and 01l lines 369-377:
+ * - System properties are auto-generated and cannot be overridden via Extra
+ *
+ * @typeParam FF - Feature flag schema type
+ * @typeParam T - LogSchema type (for typed evaluation context)
+ * @typeParam Env - Environment type
+ */
+export interface TraceContextSystem<
+  FF extends FeatureFlagSchema,
+  T extends LogSchema = LogSchema,
+  Env extends Record<string, unknown> = Record<string, unknown>,
+> {
+  // System properties (always present, auto-generated)
+  readonly anchorEpochMicros: number; // Nanoseconds.now() / 1000n at trace root (microsecond precision)
+  readonly anchorPerfNow: number; // performance.now() at trace root
+  /** Root flag evaluator - use forContext(spanCtx) to get span-bound evaluator */
+  readonly ff: FlagEvaluator<OpContext<T, FF, Record<string, never>, Env>>;
+  readonly span: RootSpanFn;
+}
+
+/**
+ * TraceContext - system properties + user Extra
+ *
+ * Per spec 01c lines 215-216:
+ * ```typescript
+ * interface TraceContext<FF, Extra> { ... } & Extra;
+ * ```
+ *
+ * Extra properties are spread via intersection at usage site.
+ *
+ * @typeParam FF - Feature flag schema type
+ * @typeParam Extra - User-defined properties (e.g., requestId, userId, env)
+ */
+export type TraceContext<FF extends FeatureFlagSchema, Extra extends Record<string, unknown>> = TraceContextSystem<FF> &
+  Extra;
+
+// =============================================================================
+// Prototype System for V8 Hidden Class Optimization
+// =============================================================================
+
+/**
+ * Internal symbol to mark contexts as prototype-based
+ * Used for type guards and instanceof-like checks
+ */
+export const TRACE_CONTEXT_MARKER = Symbol.for('lmao.TraceContext');
+
+/**
+ * Base prototype interface for all trace contexts.
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md:
+ * - Methods are defined ONCE on a shared prototype
+ * - Object.create() is used for inheritance (no object spreads)
+ * - Properties are assigned directly for stable hidden classes
+ *
+ * This is used internally and should not be accessed directly.
+ */
+export interface TraceContextBase {
+  /** Marker for prototype chain detection */
+  readonly [TRACE_CONTEXT_MARKER]: true;
+  /** Trace ID for this context */
+  trace_id: TraceId | undefined;
+  /** Epoch microseconds when trace started */
+  anchorEpochMicros: number | undefined;
+  /** performance.now() when trace started */
+  anchorPerfNow: number | undefined;
+  /** Feature flag evaluator */
+  ff: unknown;
+  /** Root span function */
+  span: unknown;
+  /** Pre-computed Extra keys for V8 optimization (avoid Object.keys in hot path) */
+  _extraKeys?: string[];
+}
+
+/**
+ * The shared prototype object for TraceContext.
+ *
+ * Per V8 optimization guidelines:
+ * - Define methods ONCE on prototype, not per-instance
+ * - Use Object.create() for inheritance chains
+ * - Avoid object spreads which break hidden classes
+ */
+export const TraceContextProto: TraceContextBase = {
+  [TRACE_CONTEXT_MARKER]: true,
+  trace_id: undefined,
+  anchorEpochMicros: undefined,
+  anchorPerfNow: undefined,
+  ff: undefined,
+  span: undefined,
+  _extraKeys: undefined,
+};
+
+// =============================================================================
+// Type Guard
+// =============================================================================
+
+/**
+ * Type guard to check if a value is a TraceContext
+ */
+export function isTraceContext(value: unknown): value is TraceContext<FeatureFlagSchema, Record<string, unknown>> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    TRACE_CONTEXT_MARKER in value &&
+    (value as Record<symbol, unknown>)[TRACE_CONTEXT_MARKER] === true
+  );
+}

package/src/lib/traceId.ts

@@ -0,0 +1,142 @@
+/**
+ * TraceId - Branded string type for trace identification
+ *
+ * A TraceId is a string that uniquely identifies a distributed trace.
+ * It's validated to be non-empty and at most 128 characters (ASCII).
+ *
+ * Common formats:
+ * - W3C Trace Context: 32 hex chars (e.g., "0af7651916cd43dd8448eb211c80319c")
+ * - OpenTelemetry: same as W3C
+ * - Custom: any string up to 128 chars
+ *
+ * @module traceId
+ */
+
+/** Maximum length for a trace ID */
+export const MAX_TRACE_ID_LENGTH = 128;
+
+/** Branded type for validated trace IDs */
+export type TraceId = string & { readonly __brand: 'TraceId' };
+
+function brandTraceId(value: string): TraceId;
+function brandTraceId(value: string): string {
+  return value;
+}
+
+/** Precompiled regex for non-ASCII detection (2x faster than loop) */
+const NON_ASCII_REGEX = /[^\x20-\x7E]/;
+
+/**
+ * Validate and create a TraceId from a string.
+ * @throws Error if validation fails
+ */
+export function createTraceId(value: string): TraceId {
+  if (typeof value !== 'string') {
+    throw new Error('TraceId must be a string');
+  }
+  if (value.length === 0) {
+    throw new Error('TraceId cannot be empty');
+  }
+  if (value.length > MAX_TRACE_ID_LENGTH) {
+    throw new Error(`TraceId cannot exceed ${MAX_TRACE_ID_LENGTH} characters`);
+  }
+  if (NON_ASCII_REGEX.test(value)) {
+    throw new Error('TraceId must be ASCII printable characters only');
+  }
+  return brandTraceId(value);
+}
+
+/**
+ * Check if a value is a valid TraceId without throwing.
+ */
+export function isValidTraceId(value: unknown): value is TraceId {
+  return (
+    typeof value === 'string' && value.length > 0 && value.length <= MAX_TRACE_ID_LENGTH && !NON_ASCII_REGEX.test(value)
+  );
+}
+
+/**
+ * Generate a new random TraceId (W3C format: 32 hex chars).
+ */
+export function generateTraceId(): TraceId {
+  const bytes = new Uint8Array(16);
+
+  if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+    crypto.getRandomValues(bytes);
+  } else {
+    try {
+      const nodeCrypto = require('node:crypto');
+      if (nodeCrypto?.randomFillSync) {
+        nodeCrypto.randomFillSync(bytes);
+      }
+    } catch {
+      // Fallback to Math.random (not ideal but works)
+      for (let i = 0; i < 16; i++) {
+        bytes[i] = Math.floor(Math.random() * 256);
+      }
+    }
+  }
+
+  // Convert to hex string
+  let hex = '';
+  for (let i = 0; i < 16; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0');
+  }
+
+  return brandTraceId(hex);
+}
+
+// ============================================================================
+// SpanIdentity - Span identification for external systems
+// ============================================================================
+
+/**
+ * SpanIdentity - Identifies a specific span for external correlation.
+ *
+ * distributed tracing headers, error reporting). Contains the minimal fields needed
+ * to uniquely identify a span within a trace.
+ *
+ * **Usage:**
+ * ```typescript
+ * // Extract from buffer
+ * const identity: SpanIdentity = {
+ *   trace_id: buffer.trace_id,
+ *   span_id: buffer.span_id,
+ *   thread_id: buffer.thread_id,
+ * };
+ *
+ * // Use in signals/messages
+ * signalReportDown({ service, reporter, span: identity });
+ * ```
+ *
+ * **Fields:**
+ * - `trace_id`: 128-bit UUID identifying the entire trace (branded string)
+ * - `span_id`: 32-bit counter unique within the trace
+ * - `thread_id`: 64-bit identifier for execution thread/context
+ *
+ * @see specs/lmao/01b4_span_identity.md for full identity design
+ */
+export interface SpanIdentity {
+  /** Trace ID - 128-bit UUID identifying the entire trace */
+  readonly trace_id: TraceId;
+
+  /** Span ID - 32-bit counter unique within this trace */
+  readonly span_id: number;
+
+  /** Thread ID - 64-bit identifier for execution thread/context */
+  readonly thread_id: bigint;
+}
+
+/**
+ * Extract SpanIdentity from a span buffer.
+ *
+ * @param buffer - Any object with trace_id, span_id, thread_id properties
+ * @returns SpanIdentity for external correlation
+ */
+export function extractSpanIdentity(buffer: { trace_id: TraceId; span_id: number; thread_id: bigint }): SpanIdentity {
+  return {
+    trace_id: buffer.trace_id,
+    span_id: buffer.span_id,
+    thread_id: buffer.thread_id,
+  };
+}

package/src/lib/traceRoot.es.ts

@@ -0,0 +1,157 @@
+/**
+ * TraceRoot - Browser/ES implementation.
+ *
+ * Uses performance.now() for timing with microsecond precision (~5-20μs).
+ * Last 3 digits of nanoseconds are always 000.
+ *
+ * For Node.js with NAPI-optimized writes, use traceRoot.node.ts instead.
+ *
+ * @module traceRoot.es
+ */
+
+import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import { ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_START } from './schema/systemSchema.js';
+import { createTraceId, type TraceId } from './traceId.js';
+import {
+  type ITraceRoot,
+  TRACE_ROOT_ANCHOR_EPOCH_OFFSET,
+  TRACE_ROOT_ANCHOR_PERF_OFFSET,
+  TRACE_ROOT_TRACE_ID_LEN_OFFSET,
+  TRACE_ROOT_TRACE_ID_OFFSET,
+  type TracerLifecycleHooks,
+} from './traceRoot.js';
+import type { AnySpanBuffer } from './types.js';
+
+/** Shared TextEncoder for trace_id encoding (stateless, reusable) */
+const textEncoder = new TextEncoder();
+
+/** Shared TextDecoder for trace_id decoding (stateless, reusable) */
+const textDecoder = new TextDecoder();
+
+/**
+ * TraceRoot - Browser implementation with performance.now() timing.
+ *
+ * Stores anchor data in _system ArrayBuffer for consistency with Node.js layout,
+ * but all timestamp calculations are done in pure JS.
+ */
+export class TraceRoot implements ITraceRoot {
+  /**
+   * Raw backing buffer containing anchor timestamps and trace_id.
+   */
+  readonly _system: ArrayBuffer;
+
+  /**
+   * Tracer reference for lifecycle hooks and event callbacks.
+   */
+  readonly tracer: TracerLifecycleHooks;
+
+  /**
+   * Cached TypedArray views for fast JS access.
+   */
+  private readonly _epochView: BigInt64Array;
+  private readonly _perfView: Float64Array;
+
+  constructor(trace_id: TraceId, anchorEpochNanos: bigint, anchorPerfNow: number, tracer: TracerLifecycleHooks) {
+    // Allocate buffer: 17 bytes header + trace_id length
+    // trace_id is validated to be ASCII (1 byte per char) so length === byte length
+    this._system = new ArrayBuffer(TRACE_ROOT_TRACE_ID_OFFSET + trace_id.length);
+    this.tracer = tracer;
+
+    // Create cached views (one-time allocation)
+    this._epochView = new BigInt64Array(this._system, TRACE_ROOT_ANCHOR_EPOCH_OFFSET, 1);
+    this._perfView = new Float64Array(this._system, TRACE_ROOT_ANCHOR_PERF_OFFSET, 1);
+
+    // Write anchor data directly
+    this._epochView[0] = anchorEpochNanos;
+    this._perfView[0] = anchorPerfNow;
+
+    // Encode trace_id directly into buffer (no intermediate allocation)
+    const u8View = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET);
+    const traceIdDest = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, trace_id.length);
+    const { written } = textEncoder.encodeInto(trace_id, traceIdDest);
+    u8View[0] = written;
+  }
+
+  /**
+   * Epoch time in nanoseconds when trace was created.
+   */
+  get anchorEpochNanos(): bigint {
+    return this._epochView[0];
+  }
+
+  /**
+   * High-resolution timer anchor when trace was created (performance.now() value).
+   */
+  get anchorPerfNow(): number {
+    return this._perfView[0];
+  }
+
+  /**
+   * Trace ID for this trace.
+   */
+  get trace_id(): TraceId {
+    const len = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET, 1)[0];
+    return createTraceId(textDecoder.decode(new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, len)));
+  }
+
+  /**
+   * Get current timestamp in nanoseconds since Unix epoch.
+   * Uses performance.now() - microsecond precision (last 3 digits = 000).
+   */
+  getTimestampNanos(): Nanoseconds {
+    const elapsedMs = performance.now() - this._perfView[0];
+    // Convert to nanoseconds (last 3 digits = 000 due to microsecond precision)
+    const elapsedNanos = BigInt(Math.floor(elapsedMs * 1000)) * 1000n;
+    return Nanoseconds.unsafe(this._epochView[0] + elapsedNanos);
+  }
+
+  /**
+   * Write span-start entry to buffer at row 0.
+   *
+   * Pure JS implementation - writes timestamp, entry_type, message, and sets _writeIndex.
+   */
+  writeSpanStart(buffer: AnySpanBuffer, spanName: string): void {
+    // Row 0: span-start
+    buffer.timestamp[0] = this.getTimestampNanos();
+    buffer.entry_type[0] = ENTRY_TYPE_SPAN_START;
+    buffer.message(0, spanName);
+
+    // Row 1: pre-initialize as span-exception (will be overwritten on ok/err)
+    buffer.entry_type[1] = ENTRY_TYPE_SPAN_EXCEPTION;
+    buffer.timestamp[1] = 0n;
+
+    // Events start at row 2
+    buffer._writeIndex = 2;
+  }
+
+  /**
+   * Write span-end entry to buffer at row 1.
+   * Writes both timestamp and entry_type.
+   */
+  writeSpanEnd(buffer: AnySpanBuffer, entryType: number): void {
+    buffer.timestamp[1] = this.getTimestampNanos();
+    buffer.entry_type[1] = entryType;
+  }
+
+  /**
+   * Write log entry: bump writeIndex, write timestamp + entry_type, return idx.
+   * SpanLogger uses returned idx for string column writes.
+   */
+  writeLogEntry(buffer: AnySpanBuffer, entryType: number): number {
+    const idx = buffer._writeIndex;
+    buffer.timestamp[idx] = this.getTimestampNanos();
+    buffer.entry_type[idx] = entryType;
+    buffer._writeIndex = idx + 1;
+    return idx;
+  }
+}
+
+/**
+ * Factory function for creating browser TraceRoot instances.
+ * Pass this to Tracer constructor for browser/ES environments.
+ */
+export function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks): TraceRoot {
+  const anchorEpochNanos = BigInt(Date.now()) * 1_000_000n;
+  const anchorPerfNow = performance.now();
+  return new TraceRoot(createTraceId(trace_id), anchorEpochNanos, anchorPerfNow, tracer);
+}