@smoothbricks/lmao 0.1.0

package/dist/lib/arrow/flechette.js

@@ -0,0 +1,67 @@
+import { batchType, bool, Column } from '@uwdata/flechette';
+const EMPTY_VALIDITY = new Uint8Array(0);
+const BOOL_TYPE_ID = bool().typeId;
+export function hasTypeId(value) {
+    return typeof value === 'object' && value !== null && 'typeId' in value;
+}
+export function isBoolType(value) {
+    return hasTypeId(value) && value.typeId === BOOL_TYPE_ID;
+}
+function isArrowIndexArrayConstructor(value) {
+    return value === Uint8Array || value === Uint16Array || value === Uint32Array;
+}
+export function hasArrowIndexType(value) {
+    return typeof value === 'object' && value !== null && '__arrow_index_type' in value;
+}
+export function hasArrowIndexMetadata(value) {
+    return (hasArrowIndexType(value) && '__index_array_ctor' in value && isArrowIndexArrayConstructor(value.__index_array_ctor));
+}
+export function getArrowIndexTypeOr(value, fallback) {
+    return hasArrowIndexType(value) ? value.__arrow_index_type : fallback;
+}
+export function getArrowIndexArrayConstructorOr(value, fallback = Uint8Array) {
+    return hasArrowIndexMetadata(value) ? value.__index_array_ctor : fallback;
+}
+export function makeArrowColumn(data) {
+    const validity = data.validity ?? EMPTY_VALIDITY;
+    if ('dictionary' in data) {
+        const batch = new (batchType(data.type))({
+            type: data.type,
+            length: data.length,
+            nullCount: data.nullCount,
+            validity,
+            values: data.values,
+        });
+        batch.setDictionary(data.dictionary);
+        return new Column([batch]);
+    }
+    if ('offsets' in data) {
+        const batch = new (batchType(data.type))({
+            type: data.type,
+            length: data.length,
+            nullCount: data.nullCount,
+            validity,
+            offsets: data.offsets,
+            values: data.values,
+        });
+        return new Column([batch]);
+    }
+    if (isBoolType(data.type)) {
+        const batch = new (batchType(data.type))({
+            type: data.type,
+            length: data.length,
+            nullCount: data.nullCount,
+            validity,
+            values: data.values,
+        });
+        return new Column([batch]);
+    }
+    const batch = new (batchType(data.type))({
+        type: data.type,
+        length: data.length,
+        nullCount: data.nullCount,
+        validity,
+        values: data.values,
+    });
+    return new Column([batch]);
+}

package/dist/lib/arrow/utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Utility functions for Arrow conversion
+ */
+import type { AnySpanBuffer } from '../types.js';
+type ConcatenatedNullBitmaps = {
+    nullBitmap: Uint8Array | undefined;
+    nullCount: number;
+};
+/**
+ * Encode an array of strings into a single UTF-8 Uint8Array
+ */
+export declare function encodeUtf8Strings(strings: readonly string[]): Uint8Array;
+/**
+ * Calculate UTF-8 byte offsets for an array of strings
+ */
+export declare function calculateUtf8Offsets(strings: readonly string[]): Int32Array;
+/**
+ * Concatenate Uint8 arrays without type casting.
+ */
+export declare function concatenateUint8Arrays(arrays: Uint8Array[]): Uint8Array;
+/**
+ * Concatenate Float64 arrays without type casting.
+ */
+export declare function concatenateFloat64Arrays(arrays: Float64Array[]): Float64Array;
+/**
+ * Concatenate null bitmaps from multiple buffers
+ */
+export declare function concatenateNullBitmaps(buffers: AnySpanBuffer[], columnName: string): ConcatenatedNullBitmaps;
+/**
+ * Get Arrow field name from LMAO field name
+ */
+export declare function getArrowFieldName(fieldName: string): string;
+/**
+ * Walk a SpanBuffer tree (including overflow chains and children)
+ */
+export declare function walkSpanTree(root: AnySpanBuffer, visitor: (buffer: AnySpanBuffer) => void): void;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/lib/arrow/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/arrow/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,KAAK,uBAAuB,GAAG;IAAE,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAUxE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAQ3E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAWvE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,YAAY,CAW7E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,uBAAuB,CA8B5G;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAShG"}

package/dist/lib/arrow/utils.js

@@ -0,0 +1,112 @@
+/**
+ * Utility functions for Arrow conversion
+ */
+import { copyBits, countNulls } from '@smoothbricks/arrow-builder';
+const UTF8_ENCODER = new TextEncoder();
+/**
+ * Encode an array of strings into a single UTF-8 Uint8Array
+ */
+export function encodeUtf8Strings(strings) {
+    const encoded = strings.map((s) => UTF8_ENCODER.encode(s));
+    const totalLength = encoded.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of encoded) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+/**
+ * Calculate UTF-8 byte offsets for an array of strings
+ */
+export function calculateUtf8Offsets(strings) {
+    const offsets = new Int32Array(strings.length + 1);
+    offsets[0] = 0;
+    for (let i = 0; i < strings.length; i++) {
+        const byteLength = UTF8_ENCODER.encode(strings[i]).length;
+        offsets[i + 1] = offsets[i] + byteLength;
+    }
+    return offsets;
+}
+/**
+ * Concatenate Uint8 arrays without type casting.
+ */
+export function concatenateUint8Arrays(arrays) {
+    if (arrays.length === 0)
+        throw new Error('Cannot concatenate empty array list');
+    if (arrays.length === 1)
+        return arrays[0];
+    const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+/**
+ * Concatenate Float64 arrays without type casting.
+ */
+export function concatenateFloat64Arrays(arrays) {
+    if (arrays.length === 0)
+        throw new Error('Cannot concatenate empty array list');
+    if (arrays.length === 1)
+        return arrays[0];
+    const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Float64Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+/**
+ * Concatenate null bitmaps from multiple buffers
+ */
+export function concatenateNullBitmaps(buffers, columnName) {
+    const hasAnyNulls = buffers.some((buf) => buf.getNullsIfAllocated(columnName) !== undefined);
+    if (!hasAnyNulls)
+        return { nullBitmap: undefined, nullCount: 0 };
+    const totalRows = buffers.reduce((sum, buf) => sum + buf._writeIndex, 0);
+    const bitmapBytes = Math.ceil(totalRows / 8);
+    const nullBitmap = new Uint8Array(bitmapBytes);
+    nullBitmap.fill(0xff); // Default all valid
+    // Buffer chains: all buffers except the last are full (writeIndex == capacity).
+    // If capacity is a multiple of 8, each buffer starts at a byte boundary.
+    let rowOffset = 0;
+    let nullCount = 0;
+    for (const buf of buffers) {
+        const sourceBitmap = buf.getNullsIfAllocated(columnName);
+        const rowCount = buf._writeIndex;
+        if (sourceBitmap) {
+            copyBits(nullBitmap, rowOffset, sourceBitmap, 0, rowCount);
+            // Count nulls using countNulls from arrow-builder
+            nullCount += countNulls(sourceBitmap, rowCount);
+        }
+        // If no sourceBitmap, leave as 0xff (all valid)
+        rowOffset += rowCount;
+    }
+    return { nullBitmap, nullCount };
+}
+/**
+ * Get Arrow field name from LMAO field name
+ */
+export function getArrowFieldName(fieldName) {
+    return fieldName;
+}
+/**
+ * Walk a SpanBuffer tree (including overflow chains and children)
+ */
+export function walkSpanTree(root, visitor) {
+    let current = root;
+    while (current) {
+        visitor(current);
+        current = current._overflow;
+    }
+    for (const child of root._children) {
+        walkSpanTree(child, visitor);
+    }
+}

package/dist/lib/buffer/Nanoseconds.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Nanoseconds branded type for type-safe timestamp handling
+ *
+ * Prevents accidental unit mixing (milliseconds vs nanoseconds) and provides
+ * a centralized location for timestamp conversion utilities.
+ *
+ * This is a generic buffer concept used for high-precision time-series data.
+ *
+ * **Benefits:**
+ * - Type safety prevents mixing time units
+ * - Self-documenting code - units clear from type
+ * - Zero runtime overhead on hot path (BigInt operations are fast)
+ * - Conversion functions centralized and tested
+ * - Works with Arrow's TimestampNanosecond type
+ *
+ * **Precision:**
+ * - BigInt can represent arbitrarily large integers
+ * - Nanoseconds since epoch will never overflow
+ * - Node.js: Native nanosecond precision via process.hrtime.bigint()
+ * - Browser: Microsecond precision via performance.now() (last 3 digits are 000)
+ *
+ * @module nanoseconds
+ *
+ * @example
+ * ```typescript
+ * import { Nanoseconds } from '@smoothbricks/arrow-builder';
+ *
+ * // Node.js: Native nanoseconds
+ * const timestamp = Nanoseconds.now();
+ *
+ * // Store in buffer (BigInt64Array)
+ * buffer.timestamps[idx] = timestamp; // Type-safe!
+ * ```
+ */
+/**
+ * Nanoseconds branded type
+ *
+ * A `bigint` with a compile-time brand that prevents accidental mixing of time units.
+ * The brand is erased at runtime, so there is zero overhead.
+ */
+declare const nanosecondsBrand: unique symbol;
+export type Nanoseconds = bigint & {
+    readonly [nanosecondsBrand]: 'Nanoseconds';
+};
+/**
+ * Utility functions for working with Nanoseconds
+ */
+export declare namespace Nanoseconds {
+    /**
+     * Get current timestamp in nanoseconds since Unix epoch.
+     *
+     * Uses the most efficient method available:
+     * - Browser/generic: performance.timeOrigin + performance.now() (microsecond precision)
+     * - Browsers typically provide 5-20 microsecond precision
+     *
+     * For Node.js with true nanosecond precision, use the /node entry point.
+     *
+     * **Precision handling:**
+     * - Epoch milliseconds (~1.7 trillion) is safe as Number
+     * - Multiply by 1000 to get microseconds (~1.7 quadrillion) - still safe
+     * - Convert to BigInt, then multiply by 1000n for nanoseconds
+     *
+     * @returns Current timestamp in nanoseconds since Unix epoch
+     *
+     * @example
+     * ```typescript
+     * buffer.timestamps[idx] = Nanoseconds.now();
+     * ```
+     */
+    function now(): Nanoseconds;
+    /**
+     * Convert milliseconds to nanoseconds.
+     *
+     * @param millis - Time in milliseconds (e.g., from Date.now())
+     * @returns Time in nanoseconds
+     *
+     * @example
+     * ```typescript
+     * const epochNanos = Nanoseconds.fromMillis(Date.now());
+     * ```
+     */
+    function fromMillis(millis: number): Nanoseconds;
+    /**
+     * Cast a raw bigint to Nanoseconds (use with caution).
+     *
+     * **Warning:** This bypasses type safety. Only use when you're certain
+     * the value is already in nanoseconds.
+     *
+     * @param value - Raw bigint value in nanoseconds
+     * @returns Branded Nanoseconds value
+     */
+    function unsafe(value: bigint): Nanoseconds;
+    /**
+     * Convert nanoseconds to milliseconds.
+     *
+     * @param nanos - Time in nanoseconds
+     * @returns Time in milliseconds (as number)
+     */
+    function toMillis(nanos: Nanoseconds): number;
+    /**
+     * Convert nanoseconds to microseconds.
+     *
+     * @param nanos - Time in nanoseconds
+     * @returns Time in microseconds (as bigint)
+     */
+    function toMicros(nanos: Nanoseconds): bigint;
+}
+export {};
+//# sourceMappingURL=Nanoseconds.d.ts.map

package/dist/lib/buffer/Nanoseconds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Nanoseconds.d.ts","sourceRoot":"","sources":["../../../src/lib/buffer/Nanoseconds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;GAKG;AACH,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC;AAOlF;;GAEG;AACH,yBAAiB,WAAW,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAgB,GAAG,IAAI,WAAW,CAMjC;IAED;;;;;;;;;;OAUG;IACH,SAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAEtD;IAED;;;;;;;;OAQG;IACH,SAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAEjD;IAED;;;;;OAKG;IACH,SAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEnD;IAED;;;;;OAKG;IACH,SAAgB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEnD;CACF"}

package/dist/lib/buffer/Nanoseconds.js

@@ -0,0 +1,86 @@
+function toNanoseconds(value) {
+    return value;
+}
+/**
+ * Utility functions for working with Nanoseconds
+ */
+export var Nanoseconds;
+(function (Nanoseconds) {
+    /**
+     * Get current timestamp in nanoseconds since Unix epoch.
+     *
+     * Uses the most efficient method available:
+     * - Browser/generic: performance.timeOrigin + performance.now() (microsecond precision)
+     * - Browsers typically provide 5-20 microsecond precision
+     *
+     * For Node.js with true nanosecond precision, use the /node entry point.
+     *
+     * **Precision handling:**
+     * - Epoch milliseconds (~1.7 trillion) is safe as Number
+     * - Multiply by 1000 to get microseconds (~1.7 quadrillion) - still safe
+     * - Convert to BigInt, then multiply by 1000n for nanoseconds
+     *
+     * @returns Current timestamp in nanoseconds since Unix epoch
+     *
+     * @example
+     * ```typescript
+     * buffer.timestamps[idx] = Nanoseconds.now();
+     * ```
+     */
+    function now() {
+        // performance.timeOrigin + performance.now() gives epoch time in milliseconds
+        // with sub-millisecond precision (e.g., 1702789123456.789)
+        // Convert to microseconds first (safe as Number), then to nanoseconds as BigInt
+        const epochMicros = Math.round((performance.timeOrigin + performance.now()) * 1000);
+        return toNanoseconds(BigInt(epochMicros) * 1000n);
+    }
+    Nanoseconds.now = now;
+    /**
+     * Convert milliseconds to nanoseconds.
+     *
+     * @param millis - Time in milliseconds (e.g., from Date.now())
+     * @returns Time in nanoseconds
+     *
+     * @example
+     * ```typescript
+     * const epochNanos = Nanoseconds.fromMillis(Date.now());
+     * ```
+     */
+    function fromMillis(millis) {
+        return toNanoseconds(BigInt(Math.trunc(millis)) * 1000000n);
+    }
+    Nanoseconds.fromMillis = fromMillis;
+    /**
+     * Cast a raw bigint to Nanoseconds (use with caution).
+     *
+     * **Warning:** This bypasses type safety. Only use when you're certain
+     * the value is already in nanoseconds.
+     *
+     * @param value - Raw bigint value in nanoseconds
+     * @returns Branded Nanoseconds value
+     */
+    function unsafe(value) {
+        return toNanoseconds(value);
+    }
+    Nanoseconds.unsafe = unsafe;
+    /**
+     * Convert nanoseconds to milliseconds.
+     *
+     * @param nanos - Time in nanoseconds
+     * @returns Time in milliseconds (as number)
+     */
+    function toMillis(nanos) {
+        return Number(nanos / 1000000n);
+    }
+    Nanoseconds.toMillis = toMillis;
+    /**
+     * Convert nanoseconds to microseconds.
+     *
+     * @param nanos - Time in nanoseconds
+     * @returns Time in microseconds (as bigint)
+     */
+    function toMicros(nanos) {
+        return nanos / 1000n;
+    }
+    Nanoseconds.toMicros = toMicros;
+})(Nanoseconds || (Nanoseconds = {}));

package/dist/lib/bufferStrategy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * BufferStrategy - Abstraction for SpanBuffer memory management and Arrow conversion.
+ *
+ * This interface separates memory management concerns from sink concerns (Tracer):
+ * - BufferStrategy: HOW buffers are allocated and converted (JS TypedArrays vs WASM)
+ * - Tracer (sink): WHAT happens with completed buffers (stdio, queue, test accumulation)
+ *
+ * Key responsibilities:
+ * 1. Buffer creation (root, child, overflow)
+ * 2. Arrow conversion (strategy knows optimal path)
+ * 3. Buffer release (GC for JS, freelist for WASM)
+ *
+ * The sink (Tracer subclass) controls WHEN to convert and release:
+ * - StdioTracer: prints then releases immediately
+ * - TestTracer: holds buffers until clear()
+ * - SqsTracer: accumulates, converts on flush(), then releases
+ *
+ * @module bufferStrategy
+ */
+import type { Table } from '@uwdata/flechette';
+import type { OpMetadata } from './opContext/opTypes.js';
+import type { LogSchema } from './schema/LogSchema.js';
+import type { ITraceRoot } from './traceRoot.js';
+import type { AnySpanBuffer, SpanBuffer } from './types.js';
+/**
+ * BufferStrategy interface for memory management and Arrow conversion.
+ *
+ * Implementations:
+ * - JsBufferStrategy: GC-managed JS TypedArrays, zero-copy Arrow via flechette
+ * - WasmBufferStrategy: WASM memory with freelist, Arrow built in WASM
+ * - (future) NapiBufferStrategy: Native code with SharedArrayBuffer
+ *
+ * @typeParam T - LogSchema type for type-safe buffer access
+ */
+export interface BufferStrategy<T extends LogSchema = LogSchema> {
+    /**
+     * Create a root SpanBuffer for a new trace.
+     *
+     * @param schema - LogSchema defining column types
+     * @param traceRoot - Platform-specific trace root with timestamp anchors
+     * @param opMetadata - Metadata for the executing op
+     * @param capacity - Optional capacity override
+     * @returns New SpanBuffer for the root span
+     */
+    createSpanBuffer(schema: T, traceRoot: ITraceRoot, opMetadata: OpMetadata, capacity?: number): SpanBuffer<T>;
+    /**
+     * Create a child span buffer linked to a parent.
+     *
+     * @param parentBuffer - Parent buffer for tree linkage
+     * Note: Caller must call writeSpanStart() after this to set span name in message_values[0].
+     *
+     * @param callsiteMetadata - Metadata for WHERE span() was called (row 0)
+     * @param opMetadata - Metadata for WHAT op is executing (rows 1+)
+     * @param capacity - Optional capacity override
+     * @param schema - Optional schema for the child (if different from parent, e.g., library ops)
+     * @returns New SpanBuffer linked to parent
+     */
+    createChildSpanBuffer(parentBuffer: SpanBuffer<T>, callsiteMetadata: OpMetadata, opMetadata: OpMetadata, capacity?: number, schema?: T): SpanBuffer<T>;
+    /**
+     * Create an overflow buffer when current buffer is full.
+     *
+     * @param buffer - Full buffer that needs overflow storage
+     * @returns New SpanBuffer linked via buffer._overflow
+     */
+    createOverflowBuffer(buffer: SpanBuffer<T>): SpanBuffer<T>;
+    /**
+     * Convert a SpanBuffer tree to Arrow Table.
+     *
+     * Each strategy knows the optimal conversion path:
+     * - JS: Zero-copy wrap TypedArrays via flechette
+     * - WASM: Build Arrow in WASM memory, return table
+     * - NAPI: Call into native code for parallel conversion
+     *
+     * @param buffer - Root buffer to convert (includes children and overflow chain)
+     * @returns Arrow Table (sync) or Promise<Table> (async)
+     */
+    toArrowTable(buffer: AnySpanBuffer): Table | Promise<Table>;
+    /**
+     * Release a SpanBuffer's memory resources.
+     *
+     * Called by the sink when it's done with a buffer.
+     *
+     * - JsBufferStrategy: No-op (GC handles it)
+     * - WasmBufferStrategy: Returns blocks to freelist
+     *
+     * The sink decides WHEN to release:
+     * - After printing (StdioTracer)
+     * - On clear() (TestTracer)
+     * - After Arrow conversion (SqsTracer)
+     *
+     * @param buffer - Buffer to release (and its entire tree)
+     */
+    releaseBuffer(buffer: AnySpanBuffer): void;
+}
+//# sourceMappingURL=bufferStrategy.d.ts.map

package/dist/lib/bufferStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferStrategy.d.ts","sourceRoot":"","sources":["../../src/lib/bufferStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC7D;;;;;;;;OAQG;IACH,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAE7G;;;;;;;;;;;OAWG;IACH,qBAAqB,CACnB,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC,EAC3B,gBAAgB,EAAE,UAAU,EAC5B,UAAU,EAAE,UAAU,EACtB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,CAAC,GACT,UAAU,CAAC,CAAC,CAAC,CAAC;IAEjB;;;;;OAKG;IACH,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAE3D;;;;;;;;;;OAUG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAE5D;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;CAC5C"}

package/dist/lib/bufferStrategy.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/capacityTuning.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Capacity Tuning - Self-tuning buffer capacity based on utilization
+ *
+ * Per specs/lmao/01b2_buffer_self_tuning.md:
+ * - Track row utilization = totalWrites / (spansCreated * usableRowsPerSpan)
+ * - Increase capacity if utilization > 150% (regularly overflowing)
+ * - Decrease capacity if utilization < 50% (wasting space)
+ * - Maintain power-of-2 capacities between 8 and 1024
+ *
+ * ## Utilization Model
+ *
+ * - 100% = exactly filling first buffer per span (ideal)
+ * - 150% = filling 1.5x first buffer (some spans overflow)
+ * - 200% = filling 2x first buffer (every span overflows once)
+ * - 50% = only using half the first buffer (wasting space)
+ *
+ * The 3x gap between shrink (50%) and grow (150%) thresholds prevents flip-flopping:
+ * - After grow: utilization halves → lands in stable zone
+ * - After shrink: utilization doubles → lands in stable zone
+ *
+ * ## Architecture Note
+ *
+ * Stats are on SpanBufferClass.stats (static property), NOT on LogBinding.
+ * This reduces per-instance memory and avoids sync bugs from having two stat objects.
+ */
+import type { SpanBufferStats } from './spanBufferStats.js';
+/**
+ * Check if capacity should be tuned after an overflow event.
+ *
+ * Called when a buffer overflows and needs to chain to a new buffer.
+ *
+ * @param stats - SpanBufferStats from SpanBufferClass.stats
+ * @internal
+ */
+export declare function checkCapacityTuning(stats: SpanBufferStats): void;
+/**
+ * Check if capacity should be tuned based on utilization.
+ *
+ * Algorithm:
+ * - Requires minimum 10 spans before tuning
+ * - Compute utilization = totalWrites / (spansCreated * usableRowsPerSpan)
+ * - Increase capacity (×2, max 1024) if utilization > 150%
+ * - Decrease capacity (÷2, min 8) if utilization < 50%
+ * - Reset stats after tuning to start fresh measurement window
+ *
+ * @param stats - SpanBufferStats from SpanBufferClass.stats
+ * @internal Exported for testing
+ */
+export declare function shouldTuneCapacity(stats: SpanBufferStats): void;
+//# sourceMappingURL=capacityTuning.d.ts.map

package/dist/lib/capacityTuning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacityTuning.d.ts","sourceRoot":"","sources":["../../src/lib/capacityTuning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAiB5D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAEhE;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAmB/D"}

package/dist/lib/capacityTuning.js

@@ -0,0 +1,65 @@
+/** Minimum spans needed before tuning decisions */
+const MIN_SPANS_FOR_TUNING = 10;
+/** Grow capacity when utilization exceeds this (150% = regularly overflowing) */
+const GROW_THRESHOLD = 1.5;
+/** Shrink capacity when utilization falls below this (50% = wasting space) */
+const SHRINK_THRESHOLD = 0.5;
+/** Minimum capacity (must be power of 2, >= 8 for alignment) */
+const MIN_CAPACITY = 8;
+/** Maximum capacity (must be power of 2) */
+const MAX_CAPACITY = 1024;
+/**
+ * Check if capacity should be tuned after an overflow event.
+ *
+ * Called when a buffer overflows and needs to chain to a new buffer.
+ *
+ * @param stats - SpanBufferStats from SpanBufferClass.stats
+ * @internal
+ */
+export function checkCapacityTuning(stats) {
+    shouldTuneCapacity(stats);
+}
+/**
+ * Reset stats after capacity tuning.
+ *
+ * Called after a tuning decision to start fresh measurement window.
+ * This ensures the tuning algorithm responds to recent behavior, not cumulative history.
+ *
+ * Note: Tracer.onStatsWillResetFor() is called BEFORE this reset (in spanLoggerGenerator's
+ * _getNextBuffer method) to capture stats for observability before they're lost.
+ */
+function resetStats(stats) {
+    stats.totalWrites = 0;
+    stats.spansCreated = 0;
+}
+/**
+ * Check if capacity should be tuned based on utilization.
+ *
+ * Algorithm:
+ * - Requires minimum 10 spans before tuning
+ * - Compute utilization = totalWrites / (spansCreated * usableRowsPerSpan)
+ * - Increase capacity (×2, max 1024) if utilization > 150%
+ * - Decrease capacity (÷2, min 8) if utilization < 50%
+ * - Reset stats after tuning to start fresh measurement window
+ *
+ * @param stats - SpanBufferStats from SpanBufferClass.stats
+ * @internal Exported for testing
+ */
+export function shouldTuneCapacity(stats) {
+    if (stats.spansCreated < MIN_SPANS_FOR_TUNING)
+        return;
+    // Usable rows per span = capacity - 2 (rows 0-1 reserved for span-start/end)
+    const usableRowsPerSpan = stats.capacity - 2;
+    const utilization = stats.totalWrites / (stats.spansCreated * usableRowsPerSpan);
+    // Grow if utilization > 150% (regularly overflowing)
+    if (utilization > GROW_THRESHOLD && stats.capacity < MAX_CAPACITY) {
+        stats.capacity = Math.min(stats.capacity * 2, MAX_CAPACITY);
+        resetStats(stats);
+        return;
+    }
+    // Shrink if utilization < 50% (wasting space)
+    if (utilization < SHRINK_THRESHOLD && stats.capacity > MIN_CAPACITY) {
+        stats.capacity = Math.max(MIN_CAPACITY, stats.capacity / 2);
+        resetStats(stats);
+    }
+}

package/dist/lib/codegen/evaluatorGenerator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Worker-safe feature-flag evaluator generation.
+ *
+ * Getter descriptors still live on the prototype, but the class is assembled with
+ * normal closures and `Object.defineProperties()` instead of `new Function(...)`.
+ */
+import type { OpContext } from '../opContext/types.js';
+import type { FeatureFlagSchema } from '../schema/defineFeatureFlags.js';
+import type { FlagEvaluator, InferFeatureFlagsWithContext, SpanContextWithoutFf } from '../schema/evaluator.js';
+import type { Schema } from '../schema/types.js';
+/**
+ * Base interface for generated evaluator classes.
+ */
+export interface GeneratedEvaluatorBase<Ctx extends OpContext> {
+    get<K extends keyof InferFeatureFlagsWithContext<Ctx> & string>(flag: K): Promise<InferFeatureFlagsWithContext<Ctx>[K]>;
+    get(flag: string): Promise<unknown>;
+    forContext(ctx: SpanContextWithoutFf<Ctx>): GeneratedEvaluatorInstance<Ctx>;
+    readonly evaluator: FlagEvaluator<Ctx>;
+}
+export type GeneratedEvaluatorInstance<Ctx extends OpContext> = GeneratedEvaluatorBase<Ctx> & InferFeatureFlagsWithContext<Ctx>;
+type GeneratedEvaluatorConstructor<Ctx extends OpContext> = new (spanContext: SpanContextWithoutFf<Ctx>, evaluator: FlagEvaluator<Ctx>) => GeneratedEvaluatorInstance<Ctx>;
+type ValidateFlagValue = (value: unknown, schema: Schema<unknown, unknown>, defaultValue: unknown) => unknown;
+/**
+ * Render a debug view of the worker-safe generated class.
+ *
+ * This exists for snapshots/tests only; runtime assembly happens without eval.
+ */
+export declare function generateEvaluatorClass<T extends FeatureFlagSchema>(schema: T, className?: string): string;
+/**
+ * Create evaluator class constructor from schema.
+ * This is the cold-path function called at schema definition time.
+ */
+export declare function createEvaluatorClass<Ctx extends OpContext>(schema: Ctx['flags'], validateFlagValue: ValidateFlagValue, ENTRY_TYPE_FF_ACCESS: number): GeneratedEvaluatorConstructor<Ctx>;
+export {};
+//# sourceMappingURL=evaluatorGenerator.d.ts.map