@smoothbricks/lmao 0.1.3 → 0.1.4

package/src/lib/schema/defineLogSchema.ts

@@ -229,6 +229,7 @@ function assertValidatedObject<T extends SchemaFields>(
   }
 }
 
+//#region smoo/lmao!n/schema-log-schema
 export function defineLogSchema<T extends SchemaFields>(
   schema: T,
   options?: DefineLogSchemaOptions,
@@ -289,3 +290,4 @@ export function defineLogSchema<T extends SchemaFields>(
   // Return logSchema (still a LogSchema instance with added methods)
   return result;
 }
+//#endregion smoo/lmao!n/schema-log-schema

package/src/lib/schema/evaluator.ts

@@ -1,3 +1,4 @@
+//#region corpos/billing!n/audit-flag-evaluator.lmao-evaluator
 import type { Schema, SchemaWithMetadata } from '@smoothbricks/arrow-builder';
 import { createEvaluatorClass, type GeneratedEvaluatorInstance } from '../codegen/evaluatorGenerator.js';
 import type { FluentLogEntry } from '../codegen/spanLoggerGenerator.js';
@@ -402,3 +403,4 @@ export class InMemoryFlagEvaluator<Ctx extends OpContext = OpContext> implements
     return createFeatureFlagEvaluator(this.ffSchema, ctx, this);
   }
 }
+//#endregion corpos/billing!n/audit-flag-evaluator.lmao-evaluator

package/src/lib/schema/systemSchema.ts

@@ -203,6 +203,7 @@ export function mergeWithSystemSchema<T extends Record<string, unknown>>(userSch
   return merged;
 }
 
+//#region smoo/lmao!n/lmao-entry-entry-type-definitions
 // =============================================================================
 // Entry Type Constants
 // =============================================================================
@@ -337,3 +338,4 @@ export const ENTRY_TYPE_NAMES = [
   'buffer-spans', // 23
   'buffer-capacity', // 24
 ] as const;
+//#endregion smoo/lmao!n/lmao-entry-entry-type-definitions

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-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/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

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