@smoothbricks/lmao 0.1.2 → 0.1.4

package/src/lib/spanBuffer.ts

@@ -122,6 +122,7 @@ export const SpanBufferTestUtils = {
  *
  * traceRoot is ALWAYS provided - factories extract it from parent when needed.
  */
+//#region smoo/lmao!n/spanbuffer-layout.class-signature
 export interface SpanBufferConstructor<T extends LogSchema = LogSchema> {
   new (
     capacity: number,
@@ -137,6 +138,7 @@ export interface SpanBufferConstructor<T extends LogSchema = LogSchema> {
   readonly schema: T;
   readonly stats: SpanBufferStats;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.class-signature
 
 type GeneratedSpanBufferClass<T extends LogSchema> = new (
   capacity: number,
@@ -214,6 +216,7 @@ const spanBufferClassCache = new WeakMap<LogSchema, SpanBufferConstructor>();
  * @param schema - LogSchema defining the buffer structure
  * @returns SpanBufferConstructor with static schema and stats properties
  */
+//#region smoo/lmao!n/spanbuffer-layout.constructor
 export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferConstructor<T> {
   const cached = spanBufferClassCache.get(schema);
   if (isSpanBufferConstructorForSchema(cached, schema)) {
@@ -439,6 +442,7 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
 
   return SpanBufferClass;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.constructor
 
 // ============================================================================
 // SpanBuffer factory functions
@@ -458,6 +462,7 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
  */
 const MIN_CAPACITY = 8;
 
+//#region smoo/lmao!n/spanbuffer-layout.create-root
 export function createSpanBuffer<T extends LogSchema>(
   schema: T,
   traceRoot: ITraceRoot,
@@ -485,6 +490,7 @@ export function createSpanBuffer<T extends LogSchema>(
     traceRoot, // pre-built TraceRoot with trace_id, anchors, tracer
   );
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.create-root
 
 /**
  * Creates a continuation buffer when the current buffer overflows.
@@ -496,6 +502,7 @@ export function createSpanBuffer<T extends LogSchema>(
  *
  * @returns New SpanBuffer linked via `buffer._overflow`, with same schema type
  */
+//#region smoo/lmao!n/spanbuffer-layout.create-overflow
 export function createOverflowBuffer<T extends LogSchema>(buffer: SpanBuffer<T>): SpanBuffer<T> {
   const SpanBufferClass = getSpanBufferConstructorForBuffer(buffer);
   const stats = SpanBufferClass.stats;
@@ -520,6 +527,7 @@ export function createOverflowBuffer<T extends LogSchema>(buffer: SpanBuffer<T>)
 
   return nextBuffer;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.create-overflow
 
 /**
  * Creates a child span buffer with parent linkage.
@@ -537,6 +545,7 @@ export function createOverflowBuffer<T extends LogSchema>(buffer: SpanBuffer<T>)
  *
  * @returns New SpanBuffer linked to parent
  */
+//#region smoo/lmao!n/spanbuffer-layout.create-child
 export function createChildSpanBuffer<T extends LogSchema>(
   parentBuffer: AnySpanBuffer,
   SpanBufferClass: SpanBufferConstructor<T>,
@@ -563,6 +572,7 @@ export function createChildSpanBuffer<T extends LogSchema>(
 
   return childBuffer;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.create-child
 
 // ============================================================================
 // Constants for Arrow conversion

package/src/lib/spanBufferHelpers.ts

@@ -10,6 +10,7 @@
 
 import { copyThreadIdTo } from './threadId.js';
 
+//#region smoo/lmao!n/spanbuffer-layout.helpers
 /**
  * Shared TextEncoder instance for traceId encoding.
  * TextEncoder is stateless and thread-safe, so one instance suffices.
@@ -71,3 +72,4 @@ export const spanBufferHelpers = {
 } as const;
 
 export type SpanBufferHelpers = typeof spanBufferHelpers;
+//#endregion smoo/lmao!n/spanbuffer-layout.helpers

package/src/lib/spanBufferStats.ts

@@ -28,6 +28,7 @@
  * Created once per `defineOpContext`, stored as static property on generated
  * SpanBuffer class. All buffers from same context share these stats.
  */
+//#region smoo/lmao!n/spanbuffer-layout.stats
 export interface SpanBufferStats {
   /** Current buffer capacity for new buffers (grows/shrinks based on utilization) */
   capacity: number;
@@ -38,3 +39,4 @@ export interface SpanBufferStats {
   /** Number of non-chained spans created (root + child spans, NOT overflow buffers) */
   spansCreated: number;
 }
+//#endregion smoo/lmao!n/spanbuffer-layout.stats

package/src/lib/spanContext.ts

@@ -69,9 +69,14 @@ export const SPAN_CONTEXT_MARKER = Symbol.for('lmao.SpanContext');
 // Type Exports
 // =============================================================================
 
+//#region smoo/lmao!n/codegen-spanlogger.ff
 /**
  * Internal SpanLogger type with FF methods and internal methods exposed.
  * Used by FeatureFlagEvaluator and internal span management code.
+ *
+ * The 01g "SpanLoggerInternal Type Pattern": the public SpanLogger<T> hides
+ * ffAccess/ffUsage; the evaluator casts to this internal type to reach them.
+ * The methods themselves are generated in codegen/spanLoggerGenerator.ts.
  */
 export type SpanLoggerInternal<T extends LogSchema> = SpanLoggerImpl<T> & {
   /**
@@ -85,6 +90,7 @@ export type SpanLoggerInternal<T extends LogSchema> = SpanLoggerImpl<T> & {
    */
   ffUsage(flagName: string, context?: Record<string, unknown>): FluentLogEntry<T>;
 };
+//#endregion smoo/lmao!n/codegen-spanlogger.ff
 
 type SpanDispatchFn<Ctx extends OpContext, Args extends unknown[] = unknown[], S = unknown, E = unknown> = (
   ctx: SpanContext<Ctx>,
@@ -202,6 +208,7 @@ function resolveSpanTarget<Ctx extends OpContext>(
 // Helper Functions
 // =============================================================================
 
+//#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.start
 /**
  * Write span-start entry to buffer at row 0 (fixed layout)
  * Pre-initialize row 1 as span-exception (will be overwritten by ok/err)
@@ -219,6 +226,7 @@ export function writeSpanStart<T extends LogSchema>(buffer: SpanBuffer<T>, spanN
   // Delegate to TraceRoot - platform-specific implementation handles timestamps
   buffer._traceRoot.writeSpanStart(buffer, spanName);
 }
+//#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.start
 
 /**
  * Create a SpanLogger for the given buffer.
@@ -234,6 +242,7 @@ export function createSpanLogger<T extends LogSchema>(schema: T, buffer: SpanBuf
   return createSpanLoggerFromGenerator(schema, buffer);
 }
 
+//#region smoo/lmao!n/op-retry.delay
 /**
  * Calculate delay for retry based on policy and attempt number.
  *
@@ -268,7 +277,9 @@ function calculateDelay(policy: RetryPolicy, attempt: number): number {
 
   return delay;
 }
+//#endregion smoo/lmao!n/op-retry.delay
 
+//#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.retry
 /**
  * Write span-retry entry to buffer.
  *
@@ -308,7 +319,9 @@ function writeRetryEntry<T extends LogSchema>(
   buffer.retry_attempt(index, attempt);
   buffer.retry_delay_ms(index, delayMs);
 }
+//#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.retry
 
+//#region smoo/lmao!n/op-retry.loop
 /**
  * Sleep for the specified duration.
  *
@@ -383,7 +396,9 @@ async function executeWithRetry<T extends LogSchema, S, E>(
     return result;
   }
 }
+//#endregion smoo/lmao!n/op-retry.loop
 
+//#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.end
 /**
  * Write span-end entry to buffer at row 1.
  *
@@ -408,14 +423,20 @@ export function writeSpanEnd<T extends LogSchema, S, E>(buffer: SpanBuffer<T>, r
     }
   }
 }
+//#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.end
 
 // =============================================================================
 // SpanContext Class Types
 // =============================================================================
 
+//#region smoo/lmao!n/spancontext-type
 /**
  * Constructor type for SpanContext classes created by createSpanContextClass.
  * Takes buffer, schema, spanLogger, tag directly (no temp object allocation).
+ *
+ * 01j "SpanContext Type Definition": the runtime SpanContext shape, parameterised by a single
+ * bundled OpContext (logSchema/flags/deps/...) rather than separate Schema/Deps/FF/Extra params,
+ * and SpanFn realized as the monomorphic span0-span8 overloads + variadic span() dispatcher.
  */
 export type SpanContextClass<Ctx extends OpContext> = new (
   buffer: SpanBuffer<Ctx['logSchema']>,
@@ -596,6 +617,7 @@ export type SpanContextInstance<Ctx extends OpContext> = SpanContext<Ctx> & {
     a8: A8,
   ): Promise<Result<S, E, Ctx['logSchema']>>;
 };
+//#endregion smoo/lmao!n/spancontext-type
 
 // =============================================================================
 // SpanContext Class Factory
@@ -654,6 +676,10 @@ export function createSpanContextClass<Ctx extends OpContext>(
       spanLogger: SpanLoggerImpl<Ctx['logSchema']>,
       tag: TagWriter<Ctx['logSchema']>,
     ) {
+      //#region smoo/lmao!n/codegen-destructured-context
+      // Destructured-context assembly (01g): every property an op destructures —
+      // tag, log, scope (setScope), ok, err, span — is wired here as a closed-over
+      // field/closure so `op(({ tag, log, span, ok, err }) => ...)` needs no ctx drilling.
       this._buffer = buffer;
       this._schema = schema;
       this._spanLogger = spanLogger;
@@ -669,7 +695,14 @@ export function createSpanContextClass<Ctx extends OpContext>(
       this.ok = <V>(value: V): Ok<V, Ctx['logSchema']> => new Ok<V, Ctx['logSchema']>(value, schema, buffer);
 
       this.err = <E>(error: E): Err<E, Ctx['logSchema']> => new Err<E, Ctx['logSchema']>(error, schema, buffer);
-
+      //#endregion smoo/lmao!n/codegen-destructured-context
+
+      //#region smoo/lmao!n/context-flow-span-promise
+      // 01c "Why span() Is Promise-Based" + "Child Span Creation via span()" + "spanSync()".
+      // span() is the variadic, line-number-aware Promise-based dispatcher: it detects the
+      // (line?, name, overrides?, op|fn, ...args) pattern via arguments.length (no rest-spread
+      // allocation) and routes to the monomorphic span0-span8. spanSync() is the sync-only
+      // sibling (returns Result, no Promise, no async retry loop) for guaranteed-sync callbacks.
       // span uses regular function to access `arguments` (no ...rest spread allocation)
       // Closes over `self` for calling prototype methods
       // Named function for better stack traces
@@ -866,6 +899,7 @@ export function createSpanContextClass<Ctx extends OpContext>(
           fn,
         );
       };
+      //#endregion smoo/lmao!n/context-flow-span-promise
     }
 
     // =========================================================================
@@ -902,9 +936,13 @@ export function createSpanContextClass<Ctx extends OpContext>(
       return this._buffer;
     }
 
+    //#region smoo/lmao!n/scope-attributes.read
+    // 01i read-only scope view: the immutable _scopeValues snapshot (setScope is wired in the
+    // destructured-context region; the immutable merge is _setScope in spanLoggerGenerator).
     get scope(): Readonly<Partial<InferSchema<Ctx['logSchema']>>> {
       return this._buffer._scopeValues;
     }
+    //#endregion smoo/lmao!n/scope-attributes.read
 
     // =========================================================================
     // Internal methods (on prototype)
@@ -944,6 +982,12 @@ export function createSpanContextClass<Ctx extends OpContext>(
      * @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)
      */
+    //#region smoo/lmao!n/context-flow-child-span
+    // 01c "Child Span Creation via span()" / "How span() Works" and 01e "Op's Responsibility:
+    // Buffer Creation and Registration": _spanPre is where the child SpanBuffer is created
+    // (via the buffer strategy, using the Op's SpanBufferClass for cross-library schema),
+    // wrapped in a RemappedBufferView when the dep is prefixed/mapped, registered in the
+    // parent's _children, and span-start (row 0) is written with the caller's line number.
     _spanPre(
       childCtx: SpanContextInstance<Ctx>,
       line: number,
@@ -1203,7 +1247,9 @@ export function createSpanContextClass<Ctx extends OpContext>(
 
       return ctx;
     }
+    //#endregion smoo/lmao!n/context-flow-child-span
 
+    //#region smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.exception
     /**
      * Handle span exception - writes exception details to row 1.
      * Called in catch blocks of span methods.
@@ -1218,6 +1264,7 @@ export function createSpanContextClass<Ctx extends OpContext>(
         childBuffer.exception_stack(1, errorStack);
       }
     }
+    //#endregion smoo/lmao!n/lmao-entry-span-lifecycle-entry-types.exception
 
     // =========================================================================
     // Monomorphic span methods (for transformer output)

package/src/lib/sqlite/__tests__/sqlite-common.test.ts

@@ -1,3 +1,4 @@
+import { Database } from 'bun:sqlite';
 import { describe, expect, it } from 'bun:test';
 import { createTestTracerOptions } from '../../__tests__/test-helpers.js';
 import { defineOpContext } from '../../defineOpContext.js';
@@ -5,7 +6,13 @@ import { S } from '../../schema/builder.js';
 import { defineLogSchema } from '../../schema/defineLogSchema.js';
 import { TestTracer } from '../../tracers/TestTracer.js';
 import type { AnySpanBuffer } from '../../types.js';
-import { buildInsertParams, parseSqliteTableInfoRows, type SpanSegment } from '../sqlite-common.js';
+import {
+  buildInsertParams,
+  buildInsertSql,
+  parseSqliteTableInfoRows,
+  SPANS_TABLE_INIT_SQL,
+  type SpanSegment,
+} from '../sqlite-common.js';
 
 const opContext = defineOpContext({
   logSchema: defineLogSchema({
@@ -87,3 +94,35 @@ describe('parseSqliteTableInfoRows', () => {
     ).toThrow('PRAGMA table_info(spans) returned an invalid SQLite row 0: type expected string, got number');
   });
 });
+
+describe('buildInsertSql', () => {
+  it('quotes user column identifiers so reserved words do not break the INSERT', () => {
+    // `check` and `order` are SQLite reserved words; a LogSchema field may use
+    // either (e.g. a `check` column). Unquoted, these produce
+    // `near "check": syntax error` at flush time.
+    const sql = buildInsertSql(['check', 'order', 'node']);
+    expect(sql).toContain('"check"');
+    expect(sql).toContain('"order"');
+    expect(sql).toContain('"node"');
+  });
+
+  it('omits the user-column clause entirely when there are no active fields', () => {
+    const sql = buildInsertSql([]);
+    expect(sql).toContain(
+      'INSERT INTO spans (trace_id, span_id, parent_span_id, row_index, entry_type, timestamp_ns, message)',
+    );
+  });
+
+  it('prepares against a real SQLite spans table with a reserved-word column', () => {
+    const db = new Database(':memory:');
+    db.exec(SPANS_TABLE_INIT_SQL);
+    db.exec('ALTER TABLE spans ADD COLUMN "check" TEXT');
+    // The bug: db.prepare(buildInsertSql(['check'])) threw `near "check": syntax error`.
+    const stmt = db.prepare(buildInsertSql(['check']));
+    stmt.run('trace-1', 1, 0, 0, 0, 0, 'msg', 'pass');
+    // .values() yields raw cell arrays (no object shape to assert / no cast).
+    const rows = db.query('SELECT "check" FROM spans').values();
+    expect(rows).toEqual([['pass']]);
+    db.close();
+  });
+});

package/src/lib/sqlite/index.ts

@@ -8,6 +8,7 @@
  */
 
 export { SQLiteAsyncTraceWriter } from './sqlite-async-writer.js';
+export type { SQLiteTableInfoRow } from './sqlite-common.js';
 export {
   buildAddColumnSql,
   extractSqliteColumnsFromTableInfo,

package/src/lib/sqlite/sqlite-async-writer.ts

@@ -7,6 +7,7 @@
  * @module sqlite-async-writer
  */
 
+import { cleanupDebug } from '../cleanupDiagnostics.js';
 import type { LogSchema } from '../schema/LogSchema.js';
 import type { AnySpanBuffer } from '../types.js';
 import {
@@ -82,6 +83,10 @@ export class SQLiteAsyncTraceWriter {
   }
 
   async flush(rootBuffer: AnySpanBuffer): Promise<void> {
+    cleanupDebug('sqliteAsyncWriter.flush:start', {
+      initialized: this.initialized,
+      statementCacheSize: this.insertStmtCache.size,
+    });
     await this.init();
     for (const segment of walkSpanSegments(rootBuffer)) {
       await this.ensureColumns(segment.buffer._logSchema);
@@ -93,9 +98,12 @@ export class SQLiteAsyncTraceWriter {
         await insertStmt.run(...buildInsertParams(segment, row, activeUserFields));
       }
     }
+    cleanupDebug('sqliteAsyncWriter.flush:end', { statementCacheSize: this.insertStmtCache.size });
   }
 
   async close(): Promise<void> {
+    cleanupDebug('sqliteAsyncWriter.close:start', { statementCacheSize: this.insertStmtCache.size });
     await this.db.close();
+    cleanupDebug('sqliteAsyncWriter.close:end');
   }
 }

package/src/lib/sqlite/sqlite-common.ts

@@ -284,7 +284,11 @@ export function getInsertStatementCacheKey(activeUserFields: readonly string[]):
 }
 
 export function buildInsertSql(activeUserFields: readonly string[]): string {
-  const userColsSql = activeUserFields.length > 0 ? `, ${activeUserFields.join(', ')}` : '';
+  // WHY quote: user column names come from arbitrary LogSchema fields and may
+  // collide with SQLite reserved words (e.g. a `check` or `order` trace column).
+  // buildAddColumnSql already quotes via quoteSqlIdentifier; the INSERT column
+  // list must too, or `near "check": syntax error` at flush time.
+  const userColsSql = activeUserFields.length > 0 ? `, ${activeUserFields.map(quoteSqlIdentifier).join(', ')}` : '';
   const userPlaceholders = activeUserFields.length > 0 ? `, ${activeUserFields.map(() => '?').join(', ')}` : '';
   return `INSERT INTO spans (trace_id, span_id, parent_span_id, row_index, entry_type, timestamp_ns, message${userColsSql})
    VALUES (?, ?, ?, ?, ?, ?, ?${userPlaceholders})`;

package/src/lib/sqlite/sqlite-writer.ts

@@ -15,6 +15,7 @@
  * @module sqlite-writer
  */
 
+import { cleanupDebug } from '../cleanupDiagnostics.js';
 import type { LogSchema } from '../schema/LogSchema.js';
 import type { AnySpanBuffer } from '../types.js';
 import {
@@ -112,17 +113,22 @@ export class SQLiteTraceWriter {
 
   /** Write a root SpanBuffer tree to the database */
   flush(rootBuffer: AnySpanBuffer): void {
+    cleanupDebug('sqliteWriter.flush:start', { statementCacheSize: this.insertStmtCache.size });
     this.db.exec('BEGIN IMMEDIATE');
     try {
       this.flushAllSegments(rootBuffer);
       this.db.exec('COMMIT');
+      cleanupDebug('sqliteWriter.flush:end', { statementCacheSize: this.insertStmtCache.size });
     } catch (error) {
       this.db.exec('ROLLBACK');
+      cleanupDebug('sqliteWriter.flush:error', { statementCacheSize: this.insertStmtCache.size });
       throw error;
     }
   }
 
   close(): void {
+    cleanupDebug('sqliteWriter.close:start', { statementCacheSize: this.insertStmtCache.size });
     this.db.close();
+    cleanupDebug('sqliteWriter.close:end');
   }
 }

package/src/lib/testing/bun-harness.ts

@@ -54,6 +54,7 @@ import {
   mock,
 } from 'bun:test';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { cleanupDebug, cleanupDebugActiveHandles } from '../cleanupDiagnostics.js';
 import { defineOpContext } from '../defineOpContext.js';
 import { JsBufferStrategy } from '../JsBufferStrategy.js';
 import type { SpanContext } from '../opContext/spanContextTypes.js';
@@ -270,7 +271,9 @@ function createRootTracer<B extends OpContextBinding>({
 async function closeTracer<B extends OpContextBinding>(tracer: Tracer<B>): Promise<void> {
   const close = Reflect.get(tracer, 'close');
   if (typeof close === 'function') {
+    cleanupDebug('tracer.close:start', { tracer: tracer.constructor.name });
     await close.call(tracer);
+    cleanupDebug('tracer.close:end', { tracer: tracer.constructor.name });
   }
 }
 
@@ -531,19 +534,26 @@ function createTestTracerInstance<B extends OpContextBinding, TExt extends Schem
       });
 
       _afterAll(async () => {
+        cleanupDebug('instance.afterAll:start');
+        cleanupDebugActiveHandles('instance.afterAll:handles:start');
         if (resolveTestRun) {
+          cleanupDebug('instance.rootTrace:resolve');
           resolveTestRun();
           resolveTestRun = null;
         }
 
         if (rootTracePromise) {
+          cleanupDebug('instance.rootTrace:await:start');
           await rootTracePromise;
+          cleanupDebug('instance.rootTrace:await:end');
           rootTracePromise = null;
         }
 
         if (tracer) {
           try {
+            cleanupDebug('instance.tracer.flush:start', { tracer: tracer.constructor.name });
             await tracer.flush();
+            cleanupDebug('instance.tracer.flush:end', { tracer: tracer.constructor.name });
             if (options?.sqlite && rootCtx) {
               const traceId = rootCtx.buffer.trace_id;
               const dbPath = options.sqlite.dbPath ?? '.trace-results.db';
@@ -553,6 +563,8 @@ function createTestTracerInstance<B extends OpContextBinding, TExt extends Schem
             console.error('[lmao/testing] SQLite flush error:', e);
           } finally {
             await closeTracer(tracer);
+            cleanupDebugActiveHandles('instance.afterAll:handles:end');
+            cleanupDebug('instance.afterAll:end');
           }
         }
       });
@@ -635,20 +647,27 @@ export function initTraceTestRun<B extends OpContextBinding>(opContext: B, optio
 
   // Register global teardown — resolve root, wait for span-end, then flush tracer outputs
   _afterAll(async () => {
+    cleanupDebug('global.afterAll:start');
+    cleanupDebugActiveHandles('global.afterAll:handles:start');
     // Resolve the root promise — triggers span-end write via _executeWithContext .then()
     if (_resolveTestRun) {
+      cleanupDebug('global.rootTrace:resolve');
       _resolveTestRun();
       _resolveTestRun = null;
     }
     // Await the trace promise so span-end is written to the buffer before flushing
     if (_rootTracePromise) {
+      cleanupDebug('global.rootTrace:await:start');
       await _rootTracePromise;
+      cleanupDebug('global.rootTrace:await:end');
       _rootTracePromise = null;
     }
 
     if (_tracer) {
       try {
+        cleanupDebug('global.tracer.flush:start', { tracer: _tracer.constructor.name });
         await _tracer.flush();
+        cleanupDebug('global.tracer.flush:end', { tracer: _tracer.constructor.name });
         if (options?.sqlite && _rootCtx) {
           const traceId = _rootCtx.buffer.trace_id;
           const dbPath = options.sqlite.dbPath ?? '.trace-results.db';
@@ -658,6 +677,8 @@ export function initTraceTestRun<B extends OpContextBinding>(opContext: B, optio
         console.error('[lmao/testing] SQLite flush error:', e);
       } finally {
         await closeTracer(_tracer);
+        cleanupDebugActiveHandles('global.afterAll:handles:end');
+        cleanupDebug('global.afterAll:end');
       }
     }
   });

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 corpos/billing!n/audit-pricing-metering.lmao-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 corpos/billing!n/audit-pricing-metering.lmao-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.
  *
@@ -168,3 +169,4 @@ export function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks):
   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

@@ -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):
@@ -61,6 +63,7 @@ export interface TracerLifecycleHooks {
  *
  * This layout enables NAPI/WASM 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;
@@ -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 corpos/billing!n/audit-pricing-metering.lmao-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 corpos/billing!n/audit-pricing-metering.lmao-array-queue-tracer