@smoothbricks/lmao 0.1.0

package/README.md

@@ -0,0 +1,269 @@
+# lmao
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build lmao` to build the library.
+
+## Trace Testing
+
+LMAO provides a trace-testing system where each test creates queryable trace spans. Instead of testing return values
+directly, you execute code that emits trace facts and assert on WHAT happened.
+
+### Quick Start (bun:test)
+
+1. Create a preload file:
+
+```typescript
+// test-trace-setup.ts (preload)
+import * as bunTest from 'bun:test';
+import { mock } from 'bun:test';
+import { createBunTestMock, initTraceTestRun } from '@smoothbricks/lmao/testing/bun';
+import { myOpContext } from './src/opContext.js';
+
+initTraceTestRun(myOpContext, { sqlite: { dbPath: '.trace-results.db' } });
+mock.module('bun:test', () => createBunTestMock(bunTest));
+```
+
+`mock.module` MUST be called from the preload file itself — bun only intercepts subsequent imports when the mock is
+registered from the entry module context.
+
+2. Add to `bunfig.toml`:
+
+```toml
+[test]
+preload = ["./test-trace-setup.ts"]
+```
+
+3. Write tests — import from `bun:test` as normal, `mock.module` intercepts transparently:
+
+```typescript
+import { describe, it, expect } from 'bun:test';
+import { useTestSpan } from '@smoothbricks/lmao/testing/bun';
+import { querySpan, findSpan } from '@smoothbricks/lmao/testing';
+
+describe('Order Processing', () => {
+  it('validates and saves order', async () => {
+    const ctx = useTestSpan();
+
+    await ctx.span('processOrder', async (child) => {
+      child.tag.orderId('123');
+      await child.span('validate', async (v) => v.ok(true));
+      await child.span('save', async (s) => s.ok({ id: 'order-123' }));
+      return child.ok({ status: 'saved' });
+    });
+
+    // Query the trace tree
+    const q = querySpan(ctx.buffer);
+    expect(q.names()).toEqual(['processOrder', 'validate', 'save']);
+    expect(q.find('validate')).toBeDefined();
+    expect(findSpan(ctx.buffer, 'save')).toBeDefined();
+  });
+});
+```
+
+Note: `describe`/`it`/`expect` are imported from `bun:test` as normal — `mock.module` intercepts transparently. Only
+`useTestSpan` comes from `@smoothbricks/lmao/testing/bun`.
+
+### Quick Start (vitest)
+
+1. Configure vitest:
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: { setupFiles: ['./test-setup.ts'] },
+});
+```
+
+2. Create the setup file with `vi.mock` for transparent interception:
+
+```typescript
+// test-setup.ts
+import { vi } from 'vitest';
+import { createNodeSQLiteDatabase } from '@smoothbricks/lmao/sqlite/node';
+import { myOpContext } from './src/opContext.js';
+
+vi.mock('vitest', async (importOriginal) => {
+  const [mod, { createVitestMock }] = await Promise.all([
+    importOriginal(),
+    import('@smoothbricks/lmao/testing/vitest'),
+  ]);
+  return createVitestMock(mod as Record<string, unknown>);
+});
+
+import { initTraceTestRun } from '@smoothbricks/lmao/testing/vitest';
+initTraceTestRun(myOpContext, {
+  sqlite: { dbPath: '.trace-results.db', createDatabase: createNodeSQLiteDatabase },
+});
+```
+
+3. Write tests — import from `vitest` as normal, `vi.mock` intercepts transparently:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { useTestSpan } from '@smoothbricks/lmao/testing/vitest';
+import { querySpan, findSpan } from '@smoothbricks/lmao/testing';
+
+describe('Order Processing', () => {
+  it('validates and saves order', async () => {
+    const ctx = useTestSpan();
+
+    await ctx.span('processOrder', async (child) => {
+      child.tag.orderId('123');
+      await child.span('validate', async (v) => v.ok(true));
+      return child.ok({ status: 'saved' });
+    });
+
+    const q = querySpan(ctx.buffer);
+    expect(q.names()).toContain('validate');
+    expect(findSpan(ctx.buffer, 'processOrder')).toBeDefined();
+  });
+});
+```
+
+Both bun:test and vitest use the same transparent interception pattern — tests import from their native test module as
+normal. Only `useTestSpan` (for accessing the it-local trace root) comes from the lmao testing module.
+
+#### Cloudflare Worker + Vitest notes
+
+- Keep the setup file wiring-only: call `setupVitestTestSuiteTracing(...)` and keep the `vi.mock('vitest', ...)` bridge
+  with `createVitestMock(...)`.
+- Configure SQLite sink in the package-local vitest tracer module (not in test files) so worker suites flush to a
+  worker-appropriate SQLite target (for example `d1://TRACE_RESULTS`).
+- Debug logging is harness-owned and toggled by `LMAO_VITEST_DEBUG`.
+- Verbose trace replay is toggled by `LMAO_TEST_TRACE_VERBOSE` (prints spans to stdout and still flushes SQLite).
+- In Worker tests, forward the debug env in `vitest.config.ts` via `define`, for example
+  `globalThis.__LMAO_VITEST_DEBUG_ENV__`, and do the same for `globalThis.__LMAO_TEST_TRACE_VERBOSE_ENV__` when verbose
+  replay is needed.
+- Enable debug for Cloudflare tests with:
+
+```bash
+```
+
+### Setting Up Trace Testing for a New Package
+
+1. Create the preload file (`test-trace-setup.ts`):
+
+```typescript
+import * as bunTest from 'bun:test';
+import { mock } from 'bun:test';
+import { createBunTestMock, initTraceTestRun } from '@smoothbricks/lmao/testing/bun';
+import { myOpContext } from './src/opContext.js';
+
+initTraceTestRun(myOpContext, { sqlite: { dbPath: '.trace-results.db' } });
+mock.module('bun:test', () => createBunTestMock(bunTest));
+```
+
+2. Add `bunfig.toml`:
+
+```toml
+[test]
+preload = ["./test-trace-setup.ts"]
+```
+
+3. Tests import `describe`/`it`/`expect` from `bun:test` as normal — the mock intercepts transparently.
+
+4. Add `.trace-results.db` to `.gitignore`.
+
+### Querying Trace Results
+
+After a test run, the trace database is written to the configured path. The `trace_id` is printed at the end:
+
+```
+[trace] trace_id: 550e8400-e29b-41d4-a716-446655440000 → .trace-results.db
+```
+
+The `trace_id` IS the run identifier — one root span per test run, with each `it()` as a child span.
+
+**SQLite CLI queries:**
+
+```bash
+# All spans for the latest trace (root span name = 'test-run')
+sqlite3 .trace-results.db "SELECT s0.message, s0.describe FROM spans s0 WHERE s0.row_index = 0 ORDER BY s0.timestamp_ns"
+
+# Find root span_id, then query it-level spans
+sqlite3 .trace-results.db "
+  SELECT s0.message AS test_name, s0.describe,
+         CASE WHEN s1.entry_type = 2 THEN 'ok'
+              WHEN s1.entry_type = 3 THEN 'err'
+              WHEN s1.entry_type = 4 THEN 'exception'
+              ELSE 'running' END AS status,
+         s1.timestamp_ns - s0.timestamp_ns AS duration_ns
+  FROM spans s0
+  LEFT JOIN spans s1 ON s1.trace_id = s0.trace_id AND s1.span_id = s0.span_id AND s1.row_index = 1
+  WHERE s0.trace_id = (SELECT trace_id FROM spans WHERE parent_span_id = 0 AND row_index = 0 ORDER BY timestamp_ns DESC LIMIT 1)
+    AND s0.parent_span_id = (SELECT span_id FROM spans WHERE parent_span_id = 0 AND row_index = 0 ORDER BY timestamp_ns DESC LIMIT 1)
+    AND s0.row_index = 0
+  ORDER BY s0.timestamp_ns"
+
+# All tests under a specific describe group
+sqlite3 .trace-results.db "SELECT message FROM spans WHERE describe = 'Order Processing > validation' AND row_index = 0"
+
+# Nested describe paths use ' > ' separator
+sqlite3 .trace-results.db "SELECT DISTINCT describe FROM spans WHERE describe IS NOT NULL AND row_index = 0"
+```
+
+**Schema:**
+
+| Column           | Description                                                      |
+| ---------------- | ---------------------------------------------------------------- |
+| `trace_id`       | Run identifier (= root span's trace_id)                          |
+| `span_id`        | Unique span counter within trace                                 |
+| `parent_span_id` | Parent span (0 = root, root's span_id = it-level)                |
+| `row_index`      | Row within span (0 = span-start, 1 = span-end, 2+ = log entries) |
+| `entry_type`     | 1=span-start, 2=span-ok, 3=span-err, 4=span-exception            |
+| `timestamp_ns`   | Nanosecond timestamp                                             |
+| `message`        | Span name (row 0), log message (rows 2+)                         |
+| `describe`       | `' > '`-separated describe path (user schema column)             |
+| `...`            | Additional user schema columns added dynamically via ALTER TABLE |
+
+Tree structure is encoded via `span_id` / `parent_span_id`. The root span (`parent_span_id = 0`) represents the entire
+test run. Each `it()` is a direct child of the root. User operations create deeper children.
+
+**TraceQuery API (programmatic access):**
+
+```typescript
+import { Database } from 'bun:sqlite';
+import { TraceQuery } from '@smoothbricks/lmao/testing';
+
+const query = new TraceQuery(new Database('.trace-results.db'));
+query.failures(); // all failed tests
+query.slowest(undefined, 10); // 10 slowest tests
+query.findSpans('%validate%'); // spans matching pattern
+query.testTree('my-test'); // full span tree for a test
+query.close();
+```
+
+### Querying Span Results (in-test)
+
+**QueryableSpan** wraps a SpanBuffer with ergonomic helpers:
+
+```typescript
+import { querySpan } from '@smoothbricks/lmao/testing';
+
+const q = querySpan(tracer.rootBuffers[0]);
+q.name; // span name
+q.facts(); // all facts from this span tree
+q.find('validate'); // first child span by name
+q.findAll('db-query'); // all matching descendants
+q.children; // direct child QueryableSpans
+q.names(); // all descendant span names
+```
+
+**Standalone functions** (tree-shakable):
+
+```typescript
+import { findSpan, extractFactsFor, spanNames } from '@smoothbricks/lmao/testing';
+
+const span = findSpan(rootBuffer, 'validate');
+const facts = extractFactsFor(rootBuffer, 'save');
+const names = spanNames(rootBuffer);
+```
+
+### SQLite Persistence
+
+When configured, the trace database is written after all tests complete. Schema columns evolve automatically based on
+your LogSchema fields.
+

package/dist/bun/preload.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Bun runtime preload — registers Typia validation codegen plugin.
+ *
+ * Re-exports from @smoothbricks/validation which owns the Typia integration.
+ * Packages that cannot depend on lmao should use @smoothbricks/validation/bun/preload directly.
+ *
+ * Usage in bunfig.toml:
+ *   preload = ["@smoothbricks/lmao/bun/preload"]
+ */
+import '@smoothbricks/validation/bun/preload';
+//# sourceMappingURL=preload.d.ts.map

package/dist/bun/preload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload.d.ts","sourceRoot":"","sources":["../../src/bun/preload.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,sCAAsC,CAAC"}

package/dist/bun/preload.js

@@ -0,0 +1,10 @@
+/**
+ * Bun runtime preload — registers Typia validation codegen plugin.
+ *
+ * Re-exports from @smoothbricks/validation which owns the Typia integration.
+ * Packages that cannot depend on lmao should use @smoothbricks/validation/bun/preload directly.
+ *
+ * Usage in bunfig.toml:
+ *   preload = ["@smoothbricks/lmao/bun/preload"]
+ */
+import '@smoothbricks/validation/bun/preload';

package/dist/bun/trace-preload.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bun test tracing preload.
+ *
+ * Registers LMAO SQLite-backed test tracing after the Typia preload has already
+ * been registered in bunfig.
+ */
+export {};
+//# sourceMappingURL=trace-preload.d.ts.map

package/dist/bun/trace-preload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-preload.d.ts","sourceRoot":"","sources":["../../src/bun/trace-preload.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/bun/trace-preload.js

@@ -0,0 +1,12 @@
+/**
+ * Bun test tracing preload.
+ *
+ * Registers LMAO SQLite-backed test tracing after the Typia preload has already
+ * been registered in bunfig.
+ */
+import { join } from 'node:path';
+import { autoSetupBunTestTracing } from '../lib/testing/bun-harness.js';
+// WHY: Find the monorepo packages dir relative to this file's location.
+// This file lives at packages/lmao/src/bun/trace-preload.ts (4 levels up to monorepo root).
+const monorepoRoot = join(import.meta.dir, '..', '..', '..', '..');
+await autoSetupBunTestTracing({ packagesDir: join(monorepoRoot, 'packages') });

package/dist/es.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ES/Browser entry point for @smoothbricks/lmao/es
+ * Uses performance.now() for high-precision timestamps
+ * Works in browsers, Deno, Cloudflare Workers, etc.
+ */
+export * from './index.js';
+export { createTraceRoot } from './lib/traceRoot.es.js';
+//# sourceMappingURL=es.d.ts.map

package/dist/es.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"es.d.ts","sourceRoot":"","sources":["../src/es.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/es.js

@@ -0,0 +1,9 @@
+/**
+ * ES/Browser entry point for @smoothbricks/lmao/es
+ * Uses performance.now() for high-precision timestamps
+ * Works in browsers, Deno, Cloudflare Workers, etc.
+ */
+// Re-export all main functionality
+export * from './index.js';
+// Export browser-specific TraceRoot factory for Tracer construction
+export { createTraceRoot } from './lib/traceRoot.es.js';

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+export * from './lib/defineOpContext.js';
+export { Op } from './lib/op.js';
+export { Blocked, type BlockedConfig, type BlockedReason } from './lib/errors/Blocked.js';
+export type { Result, TaggedError, TaggedErrorConstructor } from './lib/result.js';
+export { defineCodeError, Err, hasErrorCode, Ok } from './lib/result.js';
+export type { RootSpanFn, TraceContext, TraceContextSystem } from './lib/traceContext.js';
+export { isTraceContext, TRACE_CONTEXT_MARKER, TraceContextProto } from './lib/traceContext.js';
+export type { FluentLogEntry, SpanContext, SpanFn, SpanLogger } from './lib/spanContext.js';
+export { isSpanContext, SPAN_CONTEXT_MARKER } from './lib/spanContext.js';
+export type { LogAPI } from './lib/logApi.js';
+export { noopLogAPI } from './lib/logApi.js';
+export { ENTRY_TYPE_BUFFER_CAPACITY, ENTRY_TYPE_BUFFER_SPANS, ENTRY_TYPE_BUFFER_WRITES, ENTRY_TYPE_DEBUG, ENTRY_TYPE_ERROR, ENTRY_TYPE_FF_ACCESS, ENTRY_TYPE_FF_USAGE, ENTRY_TYPE_INFO, ENTRY_TYPE_NAMES, ENTRY_TYPE_OP_DURATION_ERR, ENTRY_TYPE_OP_DURATION_MAX, ENTRY_TYPE_OP_DURATION_MIN, ENTRY_TYPE_OP_DURATION_OK, ENTRY_TYPE_OP_DURATION_TOTAL, ENTRY_TYPE_OP_ERRORS, ENTRY_TYPE_OP_EXCEPTIONS, ENTRY_TYPE_OP_INVOCATIONS, ENTRY_TYPE_PERIOD_START, ENTRY_TYPE_SPAN_ERR, ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_OK, ENTRY_TYPE_SPAN_START, ENTRY_TYPE_TRACE, ENTRY_TYPE_WARN, mergeWithSystemSchema, systemSchema, } from './lib/schema/systemSchema.js';
+export type { Input, Output, Schema, SchemaFields, SchemaType, SchemaWithMetadata } from '@smoothbricks/arrow-builder';
+export * from './lib/schema/evaluator.js';
+export * from './lib/schema/extend.js';
+export * from './lib/schema/typeGuards.js';
+export type { ResultWriter, TagWriter } from './lib/codegen/fixedPositionWriterGenerator.js';
+export { createResultWriter, createTagWriter } from './lib/codegen/fixedPositionWriterGenerator.js';
+export type { BaseSpanLogger, SpanLoggerImpl } from './lib/codegen/spanLoggerGenerator.js';
+export { createSpanLogger, createSpanLoggerClass } from './lib/codegen/spanLoggerGenerator.js';
+export * from './lib/convertToArrow.js';
+export * from './lib/spanBuffer.js';
+export * from './lib/types.js';
+export * from './lib/flushScheduler.js';
+export type { BufferStrategy } from './lib/bufferStrategy.js';
+export { JsBufferStrategy } from './lib/JsBufferStrategy.js';
+export type { OpContextBinding } from './lib/opContext/types.js';
+export { type TraceFn, type TraceOverrides, Tracer, type TracerOptions } from './lib/tracer.js';
+export { ArrayQueueTracer } from './lib/tracers/ArrayQueueTracer.js';
+export { CompositeTracer } from './lib/tracers/CompositeTracer.js';
+export { NoOpTracer } from './lib/tracers/NoOpTracer.js';
+export { SQLiteAsyncTracer, SQLiteTracer } from './lib/tracers/SQLiteTracer.js';
+export { StdioTracer } from './lib/tracers/StdioTracer.js';
+export { type StatsSnapshot, TestTracer } from './lib/tracers/TestTracer.js';
+export * from './lib/library.js';
+export * from './lib/archive/index.js';
+export { _resetThreadId, copyThreadIdTo, getThreadId, THREAD_ID_BYTES, writeThreadIdToUint64Array, } from './lib/threadId.js';
+export { createTraceId, extractSpanIdentity, generateTraceId, isValidTraceId, MAX_TRACE_ID_LENGTH, type SpanIdentity, type TraceId, } from './lib/traceId.js';
+export type { ITraceRoot, TraceRootFactory, TracerLifecycleHooks } from './lib/traceRoot.js';
+export * from './lib/utf8Cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,84 @@
+// Main integration API - GREENFIELD - NO BACKWARDS COMPAT
+// =============================================================================
+// Primary API: defineOpContext (Op-Centric API)
+// =============================================================================
+// Op-Centric API - the module system (includes schema utilities and types)
+export * from './lib/defineOpContext.js';
+// Op class - used internally by defineOp()
+export { Op } from './lib/op.js';
+// =============================================================================
+// Result Types
+// =============================================================================
+export { Blocked } from './lib/errors/Blocked.js';
+export { defineCodeError, Err, hasErrorCode, Ok } from './lib/result.js';
+export { isTraceContext, TRACE_CONTEXT_MARKER, TraceContextProto } from './lib/traceContext.js';
+export { isSpanContext, SPAN_CONTEXT_MARKER } from './lib/spanContext.js';
+export { noopLogAPI } from './lib/logApi.js';
+// =============================================================================
+// System Schema & Entry Type Constants
+// =============================================================================
+export { 
+// Buffer metrics (utilization-based capacity tuning)
+ENTRY_TYPE_BUFFER_CAPACITY, ENTRY_TYPE_BUFFER_SPANS, ENTRY_TYPE_BUFFER_WRITES, ENTRY_TYPE_DEBUG, ENTRY_TYPE_ERROR, 
+// Feature flags
+ENTRY_TYPE_FF_ACCESS, ENTRY_TYPE_FF_USAGE, ENTRY_TYPE_INFO, 
+// Lookup
+ENTRY_TYPE_NAMES, ENTRY_TYPE_OP_DURATION_ERR, ENTRY_TYPE_OP_DURATION_MAX, ENTRY_TYPE_OP_DURATION_MIN, ENTRY_TYPE_OP_DURATION_OK, ENTRY_TYPE_OP_DURATION_TOTAL, ENTRY_TYPE_OP_ERRORS, ENTRY_TYPE_OP_EXCEPTIONS, 
+// Op metrics
+ENTRY_TYPE_OP_INVOCATIONS, 
+// Period markers
+ENTRY_TYPE_PERIOD_START, ENTRY_TYPE_SPAN_ERR, ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_OK, 
+// Span lifecycle
+ENTRY_TYPE_SPAN_START, 
+// Log levels (ordered by verbosity)
+ENTRY_TYPE_TRACE, ENTRY_TYPE_WARN, mergeWithSystemSchema, 
+// Schema helpers
+systemSchema, } from './lib/schema/systemSchema.js';
+// =============================================================================
+// Schema System (additional exports not in defineOpContext)
+// Note: defineOpContext already re-exports S, defineFeatureFlags, defineLogSchema, LogSchema
+// =============================================================================
+export * from './lib/schema/evaluator.js';
+export * from './lib/schema/extend.js';
+export * from './lib/schema/typeGuards.js';
+export { createResultWriter, createTagWriter } from './lib/codegen/fixedPositionWriterGenerator.js';
+export { createSpanLogger, createSpanLoggerClass } from './lib/codegen/spanLoggerGenerator.js';
+// =============================================================================
+// SpanBuffer & Arrow Conversion
+// =============================================================================
+export * from './lib/convertToArrow.js';
+export * from './lib/spanBuffer.js';
+export * from './lib/types.js';
+// =============================================================================
+// Flush Scheduler
+// =============================================================================
+export * from './lib/flushScheduler.js';
+export { JsBufferStrategy } from './lib/JsBufferStrategy.js';
+export { Tracer } from './lib/tracer.js';
+export { ArrayQueueTracer } from './lib/tracers/ArrayQueueTracer.js';
+export { CompositeTracer } from './lib/tracers/CompositeTracer.js';
+// Concrete tracer implementations
+export { NoOpTracer } from './lib/tracers/NoOpTracer.js';
+export { SQLiteAsyncTracer, SQLiteTracer } from './lib/tracers/SQLiteTracer.js';
+export { StdioTracer } from './lib/tracers/StdioTracer.js';
+export { TestTracer } from './lib/tracers/TestTracer.js';
+// =============================================================================
+// Library Integration
+// =============================================================================
+export * from './lib/library.js';
+// =============================================================================
+// Archive Data-Plane Primitives
+// =============================================================================
+export * from './lib/archive/index.js';
+// =============================================================================
+// Thread ID Generation
+// =============================================================================
+export { _resetThreadId, copyThreadIdTo, getThreadId, THREAD_ID_BYTES, writeThreadIdToUint64Array, } from './lib/threadId.js';
+// =============================================================================
+// Trace ID
+// =============================================================================
+export { createTraceId, extractSpanIdentity, generateTraceId, isValidTraceId, MAX_TRACE_ID_LENGTH, } from './lib/traceId.js';
+// =============================================================================
+// UTF-8 Cache (for Arrow conversion)
+// =============================================================================
+export * from './lib/utf8Cache.js';

package/dist/lib/JsBufferStrategy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * JsBufferStrategy - Default buffer strategy using JavaScript TypedArrays.
+ *
+ * Uses GC-managed memory with zero-copy Arrow conversion via flechette.
+ *
+ * Memory characteristics:
+ * - Buffers are regular JS objects with TypedArray properties
+ * - GC handles deallocation (no explicit release needed)
+ * - Arrow conversion shares ArrayBuffer references (zero-copy)
+ *
+ * @module JsBufferStrategy
+ */
+import type { Table } from '@uwdata/flechette';
+import type { BufferStrategy } from './bufferStrategy.js';
+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';
+/**
+ * JsBufferStrategy - Default buffer strategy using GC-managed TypedArrays.
+ *
+ * This is the standard strategy for most use cases:
+ * - Simple memory model (GC handles cleanup)
+ * - Zero-copy Arrow conversion (shares ArrayBuffer references)
+ * - No explicit release needed (but releaseBuffer is a no-op)
+ *
+ * @example
+ * ```typescript
+ * const strategy = new JsBufferStrategy<MySchema>();
+ * const tracer = new StdioTracer(binding, strategy, options);
+ * ```
+ */
+export declare class JsBufferStrategy<T extends LogSchema = LogSchema> implements BufferStrategy<T> {
+    /**
+     * Cache of SpanBuffer classes per schema.
+     * Populated lazily on first buffer creation.
+     */
+    private spanBufferClassCache;
+    /**
+     * Get or create SpanBuffer class for a schema.
+     */
+    private getSpanBufferClassForSchema;
+    createSpanBuffer(schema: T, traceRoot: ITraceRoot, opMetadata: OpMetadata, capacity?: number): SpanBuffer<T>;
+    createChildSpanBuffer(parentBuffer: SpanBuffer<T>, callsiteMetadata: OpMetadata, opMetadata: OpMetadata, capacity?: number, schema?: T): SpanBuffer<T>;
+    createOverflowBuffer(buffer: SpanBuffer<T>): SpanBuffer<T>;
+    toArrowTable(buffer: AnySpanBuffer): Table;
+    releaseBuffer(_buffer: AnySpanBuffer): void;
+}
+//# sourceMappingURL=JsBufferStrategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JsBufferStrategy.d.ts","sourceRoot":"","sources":["../../src/lib/JsBufferStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAQvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS5D;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,CAAE,YAAW,cAAc,CAAC,CAAC,CAAC;IACzF;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAAmD;IAE/E;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAYnC,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC;IAI5G,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;IAOhB,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAI1D,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,KAAK;IAK1C,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;CAI5C"}

package/dist/lib/JsBufferStrategy.js

@@ -0,0 +1,60 @@
+import { convertSpanTreeToArrowTable } from './convertToArrow.js';
+import { createChildSpanBuffer as createChildSpanBufferImpl, createOverflowBuffer as createOverflowBufferImpl, createSpanBuffer as createSpanBufferImpl, getSpanBufferClass, } from './spanBuffer.js';
+function isSpanBufferConstructorForSchema(ctor, schema) {
+    return ctor !== undefined && ctor.schema === schema;
+}
+/**
+ * JsBufferStrategy - Default buffer strategy using GC-managed TypedArrays.
+ *
+ * This is the standard strategy for most use cases:
+ * - Simple memory model (GC handles cleanup)
+ * - Zero-copy Arrow conversion (shares ArrayBuffer references)
+ * - No explicit release needed (but releaseBuffer is a no-op)
+ *
+ * @example
+ * ```typescript
+ * const strategy = new JsBufferStrategy<MySchema>();
+ * const tracer = new StdioTracer(binding, strategy, options);
+ * ```
+ */
+export class JsBufferStrategy {
+    /**
+     * Cache of SpanBuffer classes per schema.
+     * Populated lazily on first buffer creation.
+     */
+    spanBufferClassCache = new WeakMap();
+    /**
+     * Get or create SpanBuffer class for a schema.
+     */
+    getSpanBufferClassForSchema(schema) {
+        let cached = this.spanBufferClassCache.get(schema);
+        if (!cached) {
+            cached = getSpanBufferClass(schema);
+            this.spanBufferClassCache.set(schema, cached);
+        }
+        if (!isSpanBufferConstructorForSchema(cached, schema)) {
+            throw new TypeError('Cached SpanBuffer class does not match schema');
+        }
+        return cached;
+    }
+    createSpanBuffer(schema, traceRoot, opMetadata, capacity) {
+        return createSpanBufferImpl(schema, traceRoot, opMetadata, capacity);
+    }
+    createChildSpanBuffer(parentBuffer, callsiteMetadata, opMetadata, capacity, schema) {
+        // Use provided schema (for cross-library calls) or parent's schema
+        const childSchema = schema ?? parentBuffer._logSchema;
+        const SpanBufferClass = this.getSpanBufferClassForSchema(childSchema);
+        return createChildSpanBufferImpl(parentBuffer, SpanBufferClass, callsiteMetadata, opMetadata, capacity);
+    }
+    createOverflowBuffer(buffer) {
+        return createOverflowBufferImpl(buffer);
+    }
+    toArrowTable(buffer) {
+        // Uses existing tree conversion with shared dictionaries
+        return convertSpanTreeToArrowTable(buffer);
+    }
+    releaseBuffer(_buffer) {
+        // No-op for JS strategy - GC handles memory
+        // The buffer will be collected when no references remain
+    }
+}

package/dist/lib/archive/chunkCompaction.d.ts

@@ -0,0 +1,15 @@
+import type { TraceChunkEnvelope } from './chunkEnvelope.js';
+export interface CompactionWindow {
+    readonly started_at_ms: number;
+    readonly ended_at_ms: number;
+}
+export interface CompactedChunkSet {
+    readonly compaction_id: string;
+    readonly source_set_hash: string;
+    readonly source_chunk_ids: readonly string[];
+    readonly source_chunk_count: number;
+    readonly total_rows: number;
+    readonly window: CompactionWindow;
+}
+export declare function compactTraceChunks(chunks: readonly TraceChunkEnvelope[], window: CompactionWindow): CompactedChunkSet;
+//# sourceMappingURL=chunkCompaction.d.ts.map

package/dist/lib/archive/chunkCompaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkCompaction.d.ts","sourceRoot":"","sources":["../../../src/lib/archive/chunkCompaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAcrH"}

package/dist/lib/archive/chunkCompaction.js

@@ -0,0 +1,24 @@
+export function compactTraceChunks(chunks, window) {
+    const sourceChunkIds = [...new Set(chunks.map((chunk) => chunk.chunk_id))].sort();
+    const totalRows = chunks.reduce((sum, chunk) => sum + chunk.row_count, 0);
+    const source_set_hash = hashDeterministic(sourceChunkIds.join('|'));
+    const compaction_id = `compact_${hashDeterministic(`${source_set_hash}:${window.started_at_ms}:${window.ended_at_ms}`)}`;
+    return {
+        compaction_id,
+        source_set_hash,
+        source_chunk_ids: sourceChunkIds,
+        source_chunk_count: sourceChunkIds.length,
+        total_rows: totalRows,
+        window,
+    };
+}
+function hashDeterministic(input) {
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    const mod = 0xffffffffffffffffn;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= BigInt(input.charCodeAt(i));
+        hash = (hash * prime) & mod;
+    }
+    return hash.toString(16).padStart(16, '0');
+}