@smoothbricks/lmao 0.1.3 → 0.2.0

package/src/lib/testing/__tests__/facts.test.ts

@@ -286,10 +286,10 @@ describe('trace-testing example', () => {
     // Simulate facts collected from a trace
     const facts = createFactArray([
       spanStarted('execute-loop'),
-      spanStarted('reduce'),
+      spanStarted('prepare'),
       tagFact('event_count', 5),
-      spanOk('reduce'),
-      spanStarted('decide'),
+      spanOk('prepare'),
+      spanStarted('plan'),
       spanStarted('op:reserveInventory'),
       tagFact('sku', 'SKU-A'),
       tagFact('quantity', 2),
@@ -297,7 +297,7 @@ describe('trace-testing example', () => {
       spanStarted('op:chargePayment'),
       logInfo('Charging $49.99'),
       spanOk('op:chargePayment'),
-      spanOk('decide'),
+      spanOk('plan'),
       spanOk('execute-loop'),
     ]);
 
@@ -307,8 +307,8 @@ describe('trace-testing example', () => {
     // The execution completed successfully
     expect(facts.has(spanOk('execute-loop'))).toBe(true);
 
-    // Reduce happened before decide
-    expect(facts.hasInOrder([spanOk('reduce'), spanStarted('decide')])).toBe(true);
+    // Preparation happened before planning
+    expect(facts.hasInOrder([spanOk('prepare'), spanStarted('plan')])).toBe(true);
 
     // Inventory was reserved before payment was charged
     expect(facts.hasInOrder([spanOk('op:reserveInventory'), spanStarted('op:chargePayment')])).toBe(true);

package/src/lib/threadId.ts

@@ -22,6 +22,7 @@
  * @module threadId
  */
 
+//#region smoo/lmao!n/spanbuffer-layout.thread-id
 /** Thread ID size in bytes */
 export const THREAD_ID_BYTES = 8;
 
@@ -120,6 +121,7 @@ export function writeThreadIdToUint64Array(dest: BigUint64Array, index: number):
   const byteView = new Uint8Array(dest.buffer, dest.byteOffset + index * 8, 8);
   byteView.set(threadIdBytes);
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.thread-id
 
 /**
  * Reset thread ID for testing purposes only.

package/src/lib/traceId.ts

@@ -12,6 +12,7 @@
  * @module traceId
  */
 
+//#region smoo/lmao!n/span-identity.trace-id
 /** Maximum length for a trace ID */
 export const MAX_TRACE_ID_LENGTH = 128;
 
@@ -85,10 +86,12 @@ export function generateTraceId(): TraceId {
 
   return brandTraceId(hex);
 }
+//#endregion smoo/lmao!n/span-identity.trace-id
 
 // ============================================================================
 // SpanIdentity - Span identification for external systems
 // ============================================================================
+//#region smoo/lmao!n/span-identity.external-correlation
 
 /**
  * SpanIdentity - Identifies a specific span for external correlation.
@@ -140,3 +143,4 @@ export function extractSpanIdentity(buffer: { trace_id: TraceId; span_id: number
     thread_id: buffer.thread_id,
   };
 }
+//#endregion smoo/lmao!n/span-identity.external-correlation

package/src/lib/traceRoot.es.ts

@@ -1,3 +1,4 @@
+//#region smoo/lmao!n/es-trace-root
 /**
  * TraceRoot - Browser/ES implementation.
  *
@@ -94,6 +95,7 @@ export class TraceRoot implements ITraceRoot {
     return createTraceId(textDecoder.decode(new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, len)));
   }
 
+  //#region smoo/lmao!n/trace-root-timestamps #es
   /**
    * Get current timestamp in nanoseconds since Unix epoch.
    * Uses performance.now() - microsecond precision (last 3 digits = 000).
@@ -104,6 +106,7 @@ export class TraceRoot implements ITraceRoot {
     const elapsedNanos = BigInt(Math.floor(elapsedMs * 1000)) * 1000n;
     return Nanoseconds.unsafe(this._epochView[0] + elapsedNanos);
   }
+  //#endregion smoo/lmao!n/trace-root-timestamps
 
   /**
    * Write span-start entry to buffer at row 0.
@@ -155,3 +158,4 @@ export function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks):
   const anchorPerfNow = performance.now();
   return new TraceRoot(createTraceId(trace_id), anchorEpochNanos, anchorPerfNow, tracer);
 }
+//#endregion smoo/lmao!n/es-trace-root

package/src/lib/traceRoot.node.ts

@@ -28,6 +28,7 @@ const textEncoder = new TextEncoder();
 /** Shared TextDecoder for trace_id decoding (stateless, reusable) */
 const textDecoder = new TextDecoder();
 
+//#region smoo/lmao!n/trace-root-timestamps #node
 /**
  * TraceRoot - Node.js implementation.
  *
@@ -51,8 +52,8 @@ export class TraceRoot implements ITraceRoot {
   private readonly _perfView: Float64Array;
 
   /**
-   * Cached anchor hrtime as BigInt for JS timestamp fallback.
-   * Only used if NAPI addon is not available.
+   * Cached anchor hrtime as the exact BigInt, so the JS timestamp delta stays
+   * correct after the f64 `anchorPerfNow` loses integer precision (~104 days uptime).
    */
   private readonly _anchorHrtimeBigInt: bigint;
 
@@ -164,7 +165,8 @@ export class TraceRoot implements ITraceRoot {
 export function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks): TraceRoot {
   const anchorEpochNanos = BigInt(Date.now()) * 1_000_000n;
   const anchorHrtimeBigInt = process.hrtime.bigint();
-  // Store as number for NAPI to read as f64
+  // Also store as f64 in the shared _system layout (WASM reads it without BigInt extraction)
   const anchorPerfNow = Number(anchorHrtimeBigInt);
   return new TraceRoot(createTraceId(trace_id), anchorEpochNanos, anchorPerfNow, anchorHrtimeBigInt, tracer);
 }
+//#endregion smoo/lmao!n/trace-root-timestamps

package/src/lib/traceRoot.ts

@@ -8,7 +8,7 @@
  *
  * Platform-specific implementations:
  * - TraceRoot.es.ts: Browser - uses performance.now() for timing
- * - TraceRoot.node.ts: Node.js - delegates to NAPI addon for optimized writes
+ * - TraceRoot.node.ts: Node.js - process.hrtime.bigint(), pure-JS writes to SpanBuffer state
  *
  * @module traceRoot
  */
@@ -24,6 +24,7 @@ export { createTraceId, extractSpanIdentity, generateTraceId, isValidTraceId, MA
  * Tracer lifecycle hooks interface.
  * Extracted to avoid circular dependency - Tracer implements this.
  */
+//#region smoo/lmao!n/buffer-tuning-observability
 export interface TracerLifecycleHooks {
   onTraceStart(buffer: unknown): void;
   onTraceEnd(buffer: unknown): void;
@@ -47,6 +48,7 @@ export interface TracerLifecycleHooks {
     createOverflowBuffer(buffer: AnySpanBuffer): AnySpanBuffer;
   };
 }
+//#endregion smoo/lmao!n/buffer-tuning-observability
 
 /**
  * TraceRoot._system memory layout (little-endian):
@@ -59,8 +61,9 @@ export interface TracerLifecycleHooks {
  *
  * Total: 17 + trace_id.length bytes
  *
- * This layout enables NAPI/WASM to read anchors directly without BigInt extraction.
+ * This layout enables the WASM path to read anchors directly without BigInt extraction.
  */
+//#region smoo/lmao!n/trace-root-timestamps #contract
 export const TRACE_ROOT_ANCHOR_EPOCH_OFFSET = 0;
 export const TRACE_ROOT_ANCHOR_PERF_OFFSET = 8;
 export const TRACE_ROOT_TRACE_ID_LEN_OFFSET = 16;
@@ -71,7 +74,7 @@ export const TRACE_ROOT_TRACE_ID_OFFSET = 17;
  *
  * Each implementation handles timestamp calculation and span writes differently:
  * - Browser: Pure JS with performance.now()
- * - Node.js: NAPI addon with mach_absolute_time() / clock_gettime()
+ * - Node.js: process.hrtime.bigint() (pure JS; a NAPI addon was benchmarked slower than WASM and removed)
  */
 /**
  * Factory function type for creating platform-specific TraceRoot instances.
@@ -84,7 +87,7 @@ export type TraceRootFactory = (trace_id: string, tracer: TracerLifecycleHooks)
 export interface ITraceRoot {
   /**
    * Raw backing buffer containing anchor timestamps and trace_id.
-   * NAPI/WASM can read this directly without BigInt extraction.
+   * The WASM path can read this directly without BigInt extraction.
    */
   readonly _system: ArrayBuffer;
 
@@ -107,7 +110,7 @@ export interface ITraceRoot {
   /**
    * High-resolution timer anchor when trace was created.
    * Browser: performance.now() value (number)
-   * Node.js: stored as number for NAPI compatibility, but represents hrtime
+   * Node.js: stored as number in the shared layout (WASM-readable), but represents hrtime
    */
   readonly anchorPerfNow: number;
 
@@ -152,3 +155,4 @@ export interface ITraceRoot {
    */
   writeLogEntry(buffer: AnySpanBuffer, entryType: number): number;
 }
+//#endregion smoo/lmao!n/trace-root-timestamps

package/src/lib/tracer.ts

@@ -239,6 +239,7 @@ export type TraceFn<Ctx extends OpContext> = {
 // Tracer Class
 // =============================================================================
 
+//#region smoo/lmao!n/tracer-architecture #contract
 /**
  * Tracer - Abstract base class for trace collection
  *
@@ -357,6 +358,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
   // trace() - Polymorphic dispatcher (like span())
   // ===========================================================================
 
+  //#region smoo/lmao!n/tracer-architecture.trace-overloads
   /**
    * Polymorphic trace dispatcher.
    *
@@ -547,6 +549,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     }
     return this._trace_unknown_fn(line, name, overrides, fnOrOp);
   }
+  //#endregion smoo/lmao!n/tracer-architecture.trace-overloads
 
   // ===========================================================================
   // Monomorphic trace methods (for transformer optimization)
@@ -894,3 +897,4 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     }
   }
 }
+//#endregion smoo/lmao!n/tracer-architecture

package/src/lib/tracers/ArrayQueueTracer.ts

@@ -1,3 +1,4 @@
+//#region smoo/lmao!n/array-queue-tracer
 import type { OpContextBinding } from '../opContext/types.js';
 import { Tracer } from '../tracer.js';
 import type { SpanBuffer } from '../types.js';
@@ -74,3 +75,4 @@ export class ArrayQueueTracer<B extends OpContextBinding = OpContextBinding> ext
     return buffers;
   }
 }
+//#endregion smoo/lmao!n/array-queue-tracer

package/src/lib/tracers/CompositeTracer.ts

@@ -20,6 +20,7 @@ export interface CompositeTracerOptions<B extends OpContextBinding = OpContextBi
  * Useful when you want multiple outputs from a single trace run,
  * for example Stdio + SQLite.
  */
+//#region smoo/lmao!n/tracer-implementations.composite
 export class CompositeTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
   private readonly delegates: Tracer<B>[];
 
@@ -79,3 +80,4 @@ export class CompositeTracer<B extends OpContextBinding = OpContextBinding> exte
     }
   }
 }
+//#endregion smoo/lmao!n/tracer-implementations.composite

package/src/lib/tracers/NoOpTracer.ts

@@ -35,6 +35,7 @@ import type { SpanBuffer } from '../types.js';
  *
  * @typeParam B - OpContextBinding type
  */
+//#region smoo/lmao!n/tracer-implementations.noop
 export class NoOpTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
   /**
    * No-op hook for trace start.
@@ -71,3 +72,4 @@ export class NoOpTracer<B extends OpContextBinding = OpContextBinding> extends T
     // No-op
   }
 }
+//#endregion smoo/lmao!n/tracer-implementations.noop

package/src/lib/tracers/SQLiteTracer.ts

@@ -21,6 +21,7 @@ export interface SQLiteAsyncTracerOptions<
 /**
  * Tracer that persists completed root traces to SQLite synchronously.
  */
+//#region smoo/lmao!n/tracer-implementations.sqlite
 export class SQLiteTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
   private readonly writer: SQLiteTraceWriter;
 
@@ -57,6 +58,7 @@ export class SQLiteTracer<B extends OpContextBinding = OpContextBinding> extends
     cleanupDebug('sqliteTracer.close:end');
   }
 }
+//#endregion smoo/lmao!n/tracer-implementations.sqlite
 
 /**
  * Tracer that persists completed root traces to SQLite asynchronously.

package/src/lib/tracers/StdioTracer.ts

@@ -204,6 +204,7 @@ export interface StdioTracerOptions<
  * - Human-readable timestamps and durations
  * - Exceptions go to stderr
  */
+//#region smoo/lmao!n/tracer-implementations.stdio
 export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
   /**
    * Per-trace indent levels for concurrent-safe nesting.
@@ -378,3 +379,4 @@ export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends
     );
   }
 }
+//#endregion smoo/lmao!n/tracer-implementations.stdio

package/src/lib/tracers/TestTracer.ts

@@ -81,6 +81,7 @@ export interface StatsSnapshot<T extends LogSchema = LogSchema> {
  * expect(tracer.statsSnapshots.length).toBeGreaterThan(0);
  * ```
  */
+//#region smoo/lmao!n/tracer-implementations.test
 export class TestTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
   /**
    * All completed root trace buffers.
@@ -144,3 +145,4 @@ export class TestTracer<B extends OpContextBinding = OpContextBinding> extends T
     }
   }
 }
+//#endregion smoo/lmao!n/tracer-implementations.test

package/src/lib/types.ts

@@ -74,6 +74,7 @@ export type { AnyColumnBuffer, ColumnBuffer, ColumnValueType, TypedArray };
  *
  * @see SpanBuffer<T> for schema-typed version with index signatures
  */
+//#region smoo/lmao!n/spanbuffer-layout.interface
 export interface AnySpanBuffer extends AnyColumnBuffer {
   // ===========================================================================
   // System Memory (cache-aligned, per specs/lmao/01b1)
@@ -414,6 +415,7 @@ export interface AnySpanBuffer extends AnyColumnBuffer {
    */
   copyParentThreadIdTo(dest: Uint8Array, offset: number): void;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.interface
 
 // ============================================================================
 // Schema Type Helpers

package/src/lib/utf8Cache.ts

@@ -39,6 +39,7 @@ type Utf8CacheStats = { hits: number; misses: number; hitRate: number; size: num
  * The cache is safe to use in async contexts since JS awaits don't
  * allow concurrent access to the same cache instance.
  */
+//#region smoo/lmao!n/buffer-perf-utf8-cache
 export class Utf8Cache implements Utf8Encoder {
   private readonly cache: SieveCache<string, Uint8Array>;
   private readonly encoder = new TextEncoder();
@@ -199,3 +200,4 @@ export const globalUtf8Cache = new Utf8Cache();
 export function createUtf8Cache(maxSize?: number): Utf8Cache {
   return new Utf8Cache(maxSize);
 }
+//#endregion smoo/lmao!n/buffer-perf-utf8-cache

package/src/lib/wasm/WasmBufferStrategy.ts

@@ -30,6 +30,9 @@ import {
   type WasmSpanBufferInstance,
 } from './wasmSpanBuffer.js';
 
+// Spec link (88): realizes specs/lmao/01q_wasm_memory_architecture.md#smoo/lmao!n/wasm-mem (OpContext integration + trace completion).
+//#region smoo/lmao!n/wasm-mem.strategy
+
 function requireWasmSpanBuffer(buffer: AnySpanBuffer): WasmSpanBufferInstance {
   if (!isWasmSpanBufferInstance(buffer)) {
     throw new Error('Expected WASM-backed span buffer');
@@ -217,3 +220,4 @@ export class WasmBufferStrategy<T extends LogSchema = LogSchema> implements Buff
     };
   }
 }
+//#endregion smoo/lmao!n/wasm-mem.strategy

package/src/lib/wasm/allocator.zig

@@ -6,7 +6,7 @@
 //
 // Memory Layout:
 // ┌─────────────────────────────────────────────────────────────────────────────┐
-// │ Header (64 bytes, cache-aligned)                                            │
+// │ Header (192 bytes, 3 cache lines)                                           │
 // ├─────────────────────────────────────────────────────────────────────────────┤
 // │ Allocated Blocks (spans + columns)                                          │
 // ├─────────────────────────────────────────────────────────────────────────────┤
@@ -22,7 +22,9 @@
 //
 // Freelist: Zero-overhead, uses block's memory for next pointer + cascading stats when free.
 //
+// Spec link (88): realizes specs/lmao/01q_wasm_memory_architecture.md#smoo/lmao!n/wasm-mem (the Zig allocator region).
 
+//#region smoo/lmao!n/wasm-mem.allocator
 const std = @import("std");
 
 // =============================================================================
@@ -943,3 +945,4 @@ export fn read_col_is_valid(col_offset: u32, row_idx: u32) u8 {
     const bit: u8 = @as(u8, 1) << @intCast(row_idx & 7);
     return if ((byte & bit) != 0) 1 else 0;
 }
+//#endregion smoo/lmao!n/wasm-mem.allocator

package/src/lib/wasm/wasmAllocator.ts

@@ -10,8 +10,12 @@
  * - Blocks are organized by tier (capacity 8, 16, 32, 64, 128, 256, 512)
  * - When freelist is empty, splits from larger tier
  * - When freeing, merges with adjacent blocks if both are free (address-based buddy merge)
+ *
+ * Spec link (88): realizes specs/lmao/01q_wasm_memory_architecture.md#smoo/lmao!n/wasm-mem (TS allocator wrapper).
  */
 
+//#region smoo/lmao!n/wasm-mem.ts-allocator
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -467,3 +471,4 @@ export function createWasmAllocatorSync(wasmModule: WebAssembly.Module, options?
 
   return wrapWasmInstance(instance, memory, capacity);
 }
+//#endregion smoo/lmao!n/wasm-mem.ts-allocator

package/src/lib/wasm/wasmSpanBuffer.ts

@@ -20,6 +20,9 @@ import type { ITraceRoot } from '../traceRoot.js';
 import type { AnySpanBuffer } from '../types.js';
 import type { WasmAllocator } from './wasmAllocator.js';
 
+// Spec link (88): realizes specs/lmao/01q_wasm_memory_architecture.md#smoo/lmao!n/wasm-mem (SpanBuffer + SpanLogger codegen).
+//#region smoo/lmao!n/wasm-mem.spanbuffer
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -1012,3 +1015,4 @@ export function createWasmOverflowBuffer(
 
   return overflow;
 }
+//#endregion smoo/lmao!n/wasm-mem.spanbuffer

package/src/lib/wasm/wasmTraceRoot.ts

@@ -16,6 +16,9 @@ import type { ITraceRoot, TracerLifecycleHooks } from '../traceRoot.js';
 import type { AnySpanBuffer } from '../types.js';
 import type { WasmAllocator } from './wasmAllocator.js';
 
+// Spec link (88): realizes specs/lmao/01q_wasm_memory_architecture.md#smoo/lmao!n/wasm-mem (span lifecycle writer).
+//#region smoo/lmao!n/wasm-mem.trace-root
+
 // =============================================================================
 // WASM Buffer Detection
 // =============================================================================
@@ -313,3 +316,4 @@ export function createWasmTraceRootFactory(allocator: WasmAllocator) {
     return new WasmTraceRoot(allocator, createTraceId(trace_id), tracer);
   };
 }
+//#endregion smoo/lmao!n/wasm-mem.trace-root

package/src/node.ts

@@ -7,4 +7,6 @@
 export * from './index.js';
 
 // Export Node.js-specific TraceRoot factory for Tracer construction
+//#region smoo/lmao!n/trace-root-timestamps.entry-points #node
 export { createTraceRoot } from './lib/traceRoot.node.js';
+//#endregion smoo/lmao!n/trace-root-timestamps.entry-points