@smoothbricks/lmao 0.1.2 → 0.1.4

package/src/lib/tracers/CompositeTracer.ts

@@ -1,3 +1,4 @@
+import { cleanupDebug } from '../cleanupDiagnostics.js';
 import type { OpContextBinding } from '../opContext/types.js';
 import { Tracer, type TracerOptions } from '../tracer.js';
 import type { SpanBuffer } from '../types.js';
@@ -19,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>[];
 
@@ -59,7 +61,9 @@ export class CompositeTracer<B extends OpContextBinding = OpContextBinding> exte
 
   override async flush(): Promise<void> {
     for (const tracer of this.delegates) {
+      cleanupDebug('compositeTracer.flush:delegate:start', { tracer: tracer.constructor.name });
       await tracer.flush();
+      cleanupDebug('compositeTracer.flush:delegate:end', { tracer: tracer.constructor.name });
     }
   }
 
@@ -68,9 +72,12 @@ export class CompositeTracer<B extends OpContextBinding = OpContextBinding> exte
       if (hasClose(tracer)) {
         const { close } = tracer;
         if (close) {
+          cleanupDebug('compositeTracer.close:delegate:start', { tracer: tracer.constructor.name });
           await close.call(tracer);
+          cleanupDebug('compositeTracer.close:delegate:end', { tracer: tracer.constructor.name });
         }
       }
     }
   }
 }
+//#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

@@ -1,3 +1,4 @@
+import { cleanupDebug } from '../cleanupDiagnostics.js';
 import type { OpContextBinding } from '../opContext/types.js';
 import { SQLiteAsyncTraceWriter } from '../sqlite/sqlite-async-writer.js';
 import type { AsyncSQLiteDatabase, SyncSQLiteDatabase } from '../sqlite/sqlite-db.js';
@@ -20,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;
 
@@ -33,7 +35,9 @@ export class SQLiteTracer<B extends OpContextBinding = OpContextBinding> extends
   }
 
   onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    cleanupDebug('sqliteTracer.onTraceEnd:flush:start', { rows: rootBuffer._writeIndex });
     this.writer.flush(rootBuffer);
+    cleanupDebug('sqliteTracer.onTraceEnd:flush:end');
   }
 
   onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
@@ -49,9 +53,12 @@ export class SQLiteTracer<B extends OpContextBinding = OpContextBinding> extends
   }
 
   async close(): Promise<void> {
+    cleanupDebug('sqliteTracer.close:start');
     this.writer.close();
+    cleanupDebug('sqliteTracer.close:end');
   }
 }
+//#endregion smoo/lmao!n/tracer-implementations.sqlite
 
 /**
  * Tracer that persists completed root traces to SQLite asynchronously.
@@ -96,6 +103,7 @@ export class SQLiteAsyncTracer<B extends OpContextBinding = OpContextBinding> ex
   }
 
   override async flush(): Promise<void> {
+    cleanupDebug('sqliteAsyncTracer.flush:start');
     await this.pendingWrites;
     if (this.pendingErrors.length > 0) {
       const errors = this.pendingErrors;
@@ -105,11 +113,14 @@ export class SQLiteAsyncTracer<B extends OpContextBinding = OpContextBinding> ex
       }
       throw new AggregateError(errors, `SQLiteAsyncTracer flush failed for ${errors.length} trace writes`);
     }
+    cleanupDebug('sqliteAsyncTracer.flush:end');
   }
 
   async close(): Promise<void> {
+    cleanupDebug('sqliteAsyncTracer.close:start');
     await this.flush();
     const writer = await this.writerPromise;
     await writer.close();
+    cleanupDebug('sqliteAsyncTracer.close:end');
   }
 }

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