@smoothbricks/lmao 0.2.2 → 0.3.0

package/README.md

@@ -1,269 +1,269 @@
-# lmao
+# @smoothbricks/lmao
 
-This library was generated with [Nx](https://nx.dev).
+A high-performance, type-safe structured tracing and observability library for TypeScript.
 
-## Building
+Instrumented code writes spans directly into columnar [Apache Arrow](https://arrow.apache.org/) buffers — near-zero
+hot-path overhead — and emits queryable Arrow tables that persist to SQLite (a local file, Node, or Cloudflare D1). A
+headline feature is **trace-testing**: assert on the span tree your code emits instead of on return values.
 
-Run `nx build lmao` to build the library.
+- **Type-safe by construction.** Your log schema drives the types of `ctx.tag`, `ctx.log`, feature flags, and results —
+  autocomplete everywhere, no casts.
+- **Columnar & cheap.** Attributes are written to fixed buffer positions; string columns are dictionary-encoded. No
+  per-event object allocation on the hot path.
+- **Arrow-native.** Convert a trace to an Arrow table and persist it to SQLite/D1, or analyze it with the companion
+  inspector.
 
-## Trace Testing
+> Part of the `smoothbricks` monorepo. Full documentation lives in [`targets/lmao-docs/`](../../targets/lmao-docs) (an Astro Starlight
+> site). Runnable examples are in [`examples/`](./examples).
 
-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.
+## Install
 
-### 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));
+```bash
+bun add @smoothbricks/lmao
 ```
 
-`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`:
+## Quick start
+
+```ts
+import {
+  defineLogSchema,
+  defineOpContext,
+  JsBufferStrategy,
+  S,
+  StdioTracer,
+} from '@smoothbricks/lmao';
+import { createTraceRoot } from '@smoothbricks/lmao/node'; // or '/es' for browsers/Workers
+
+// 1. Describe your columns. Pick a string strategy per field:
+//    S.enum (known set, 1 byte) · S.category (repeating, dictionary) · S.text (mostly unique)
+const schema = defineLogSchema({
+  userId: S.category(),
+  operation: S.enum(['SELECT', 'INSERT', 'UPDATE', 'DELETE']),
+  duration: S.number(),
+});
 
-```toml
-[test]
-preload = ["./test-trace-setup.ts"]
-```
+// 2. Bundle the schema into an op context.
+const opContext = defineOpContext({ logSchema: schema });
+const { defineOp } = opContext;
 
-3. Write tests — import from `bun:test` as normal, `mock.module` intercepts transparently:
+// 3. Define an op. Its body receives a typed SpanContext (`ctx`).
+const createUser = defineOp('create-user', async (ctx, email: string) => {
+  ctx.tag.userId(email).operation('INSERT');
+  ctx.log.info('creating {{userId}}').userId(email); // {{field}} = template, value set via the chain
 
-```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();
+  const validated = await ctx.span('validate', async (child) => {
+    child.tag.operation('SELECT');
+    return child.ok({ valid: true });
+  });
+  if (!validated.success) return ctx.err(new Error('validation failed'));
 
-    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' });
-    });
+  return ctx.ok({ id: 'user-1', email }).with({ duration: 12 });
+});
 
-    // 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();
-  });
+// 4. Build a tracer and run at the request boundary.
+const { trace } = new StdioTracer(opContext, {
+  bufferStrategy: new JsBufferStrategy(),
+  createTraceRoot,
 });
+
+const result = await trace('create-user', createUser, 'ada@example.com');
+console.log(result.success ? result.value : result.error);
 ```
 
-Note: `describe`/`it`/`expect` are imported from `bun:test` as normal — `mock.module` intercepts transparently. Only
-`useTestSpan` comes from `@smoothbricks/lmao/testing/bun`.
+## Core API
+
+### Schema (`S` + `defineLogSchema`)
 
-### Quick Start (vitest)
+| Builder | Use |
+|---|---|
+| `S.enum([...])` | A fixed set of known values (stored as 1 byte). |
+| `S.category()` | Repeating strings (dictionary-encoded). |
+| `S.text()` | Mostly-unique strings (no dictionary). |
+| `S.number()` | Numeric column. |
+| `S.boolean()` | Boolean column (bit-packed). |
 
-1. Configure vitest:
+### `defineOpContext`
 
-```typescript
-// vitest.config.ts
-export default defineConfig({
-  test: { setupFiles: ['./test-setup.ts'] },
+```ts
+const opContext = defineOpContext({
+  logSchema,        // required
+  flags,            // optional: defineFeatureFlags(...).schema
+  deps,             // optional: other op groups, wired with .prefix()/.mapColumns()
+  ctx: {            // optional: user context carried on every span
+    requestId: undefined as string | undefined,
+  },
 });
+const { defineOp, defineOps } = opContext;
 ```
 
-2. Create the setup file with `vi.mock` for transparent interception:
+`defineOp(name, fn)` creates a single op; `defineOps({ ... })` batches ops into a reusable group.
 
-```typescript
-// test-setup.ts
-import { vi } from 'vitest';
-import { createNodeSQLiteDatabase } from '@smoothbricks/lmao/sqlite/node';
-import { myOpContext } from './src/opContext.js';
+### `SpanContext` (`ctx`)
 
-vi.mock('vitest', async (importOriginal) => {
-  const [mod, { createVitestMock }] = await Promise.all([
-    importOriginal(),
-    import('@smoothbricks/lmao/testing/vitest'),
-  ]);
-  return createVitestMock(mod as Record<string, unknown>);
-});
+The object every op body receives:
 
-import { initTraceTestRun } from '@smoothbricks/lmao/testing/vitest';
-initTraceTestRun(myOpContext, {
-  sqlite: { dbPath: '.trace-results.db', createDatabase: createNodeSQLiteDatabase },
-});
-```
+| Member | What it does |
+|---|---|
+| `ctx.tag.field(value)` | Set span-start attributes (row 0). Chainable; `ctx.tag.with({...})` sets several. |
+| `ctx.log.info/debug/warn/error(msg)` | Append a log event. `msg` is a `{{field}}` template; attach values via the chain. |
+| `ctx.span(name, opOrFn, ...args)` | Open a child span; returns `Promise<Result>`. |
+| `ctx.spanSync(name, fn)` | Open a **synchronous** child span; `fn` returns a `Result` directly (no `await`). |
+| `ctx.ok(value)` / `ctx.err(error)` | Complete the span. Both chain `.with({...})` and `.message('...')`. |
+| `ctx.setScope({...})` / `ctx.scope` | Set/read attributes inherited by all subsequent logs and child spans. |
+| `ctx.ff` | Feature-flag access (present when `flags` is declared). |
+| `ctx.deps` | Declared dependency op groups. |
+| `ctx.buffer` | The underlying span buffer (used in tests and for Arrow conversion). |
+| user context | Anything declared in `ctx: {...}` (e.g. `ctx.requestId`). |
 
-3. Write tests — import from `vitest` as normal, `vi.mock` intercepts transparently:
+### Results & typed errors
 
-```typescript
-import { describe, it, expect } from 'vitest';
-import { useTestSpan } from '@smoothbricks/lmao/testing/vitest';
-import { querySpan, findSpan } from '@smoothbricks/lmao/testing';
+Ops return a `Result` — check `result.success`, then read `result.value` or `result.error`. Error codes are typed
+factories:
 
-describe('Order Processing', () => {
-  it('validates and saves order', async () => {
-    const ctx = useTestSpan();
+```ts
+import { defineCodeError } from '@smoothbricks/lmao';
 
-    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 NOT_FOUND = defineCodeError('NOT_FOUND')<{ userId: string }>();
 
-    const q = querySpan(ctx.buffer);
-    expect(q.names()).toContain('validate');
-    expect(findSpan(ctx.buffer, 'processOrder')).toBeDefined();
-  });
+const getUser = defineOp('get-user', async (ctx, id: string) => {
+  const user = await lookup(id);
+  return user ? ctx.ok(user) : ctx.err(NOT_FOUND({ userId: id }));
 });
+
+const r = await trace('get-user', getUser, 'u1');
+if (r.success) {
+  console.log(r.value);
+} else {
+  console.log(r.error.code, r.error.userId); // 'NOT_FOUND' + the typed payload field
+}
 ```
 
-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.
+## Tracers
+
+Construct a tracer with `new SomeTracer(opContext, options)`, then destructure `trace`. Every tracer needs a
+`bufferStrategy` (`new JsBufferStrategy()`) and a `createTraceRoot` (from `@smoothbricks/lmao/node` for Node, or `/es`
+for browsers/Deno/Workers).
+
+| Tracer | Use |
+|---|---|
+| `StdioTracer` | Print the span tree to the console. |
+| `TestTracer` | Keep completed traces in memory (`tracer.rootBuffers`) for inspection/tests. |
+| `ArrayQueueTracer` | Queue completed traces for batch processing (`tracer.drain()`). |
+| `SQLiteTracer` / `SQLiteAsyncTracer` | Persist to a synchronous SQLite DB, or an async one (e.g. D1). |
+| `CompositeTracer` | Fan out to several tracers. |
+| `NoOpTracer` | Execute ops without emitting. |
+
+```ts
+// trace() runs an op (or an inline fn) as the root span; overrides carry user-context values.
+await trace('greet', greet);
+await trace('greet', { requestId: 'req-1' }, greet, ...args);
+```
 
-#### Cloudflare Worker + Vitest notes
+## Feature flags
 
-- 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:
+Declare flags, pass the schema to `defineOpContext`, and supply an evaluator **to the tracer**:
 
-```bash
-```
+```ts
+import { defineFeatureFlags, InMemoryFlagEvaluator, S } from '@smoothbricks/lmao';
 
-### Setting Up Trace Testing for a New Package
+const flags = defineFeatureFlags({
+  advancedValidation: S.boolean().default(false).sync(),
+  maxRetries: S.number().default(3).sync(),
+});
 
-1. Create the preload file (`test-trace-setup.ts`):
+const opContext = defineOpContext({ logSchema: schema, flags: flags.schema });
 
-```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';
+const { trace } = new StdioTracer(opContext, {
+  bufferStrategy: new JsBufferStrategy(),
+  createTraceRoot,
+  flagEvaluator: new InMemoryFlagEvaluator(flags.schema, { advancedValidation: true, maxRetries: 5 }),
+});
 
-initTraceTestRun(myOpContext, { sqlite: { dbPath: '.trace-results.db' } });
-mock.module('bun:test', () => createBunTestMock(bunTest));
+// Inside an op — sync flags are read as `ctx.ff.<name>?.value`:
+if (ctx.ff.advancedValidation?.value) { /* ... */ }
 ```
 
-2. Add `bunfig.toml`:
+## Persist & analyze
 
-```toml
-[test]
-preload = ["./test-trace-setup.ts"]
-```
+Convert a completed trace to an Arrow table, then persist or query it:
 
-3. Tests import `describe`/`it`/`expect` from `bun:test` as normal — the mock intercepts transparently.
+```ts
+import { convertSpanTreeToArrowTable } from '@smoothbricks/lmao';
 
-4. Add `.trace-results.db` to `.gitignore`.
+const table = convertSpanTreeToArrowTable(tracer.rootBuffers[0]);
+console.log(table.numRows, table.names);
+```
 
-### Querying Trace Results
+- **SQLite / D1** — use `SQLiteTracer`/`SQLiteAsyncTracer` with `createNodeSQLiteDatabase` (`@smoothbricks/lmao/sqlite/node`)
+  or `createD1SQLiteDatabase` (`@smoothbricks/lmao/sqlite`).
+- **Query engine** — the companion package [`@smoothbricks/lmao-inspector`](../lmao-inspector) runs SQL over exported
+  Arrow data in the browser.
 
-After a test run, the trace database is written to the configured path. The `trace_id` is printed at the end:
+## Trace-testing
 
-```
-[trace] trace_id: 550e8400-e29b-41d4-a716-446655440000 → .trace-results.db
-```
+Assert on **what your code did**, not just what it returned. Each test's ops emit a queryable span tree.
 
-The `trace_id` IS the run identifier — one root span per test run, with each `it()` as a child span.
+```ts
+import { describe, it, expect } from 'bun:test';
+import { useTestSpan } from '@smoothbricks/lmao/testing/bun';
+import { querySpan, findSpan } from '@smoothbricks/lmao/testing';
 
-**SQLite CLI queries:**
+describe('order processing', () => {
+  it('validates and saves', async () => {
+    const ctx = useTestSpan();
 
-```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"
-```
+    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' });
+    });
 
-**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();
+    const q = querySpan(ctx.buffer);
+    expect(q.names()).toEqual(['processOrder', 'validate', 'save']);
+    expect(findSpan(ctx.buffer, 'save')).toBeDefined();
+  });
+});
 ```
 
-### Querying Span Results (in-test)
+Setup is wiring-only: a preload/setup file calls `initTraceTestRun(opContext, { sqlite: { dbPath: '.trace-results.db' } })`
+and installs a transparent mock so tests import `describe`/`it`/`expect` from their native runner as usual. Bun and
+Vitest are both supported (`@smoothbricks/lmao/testing/bun` · `@smoothbricks/lmao/testing/vitest`). Traces flush to a
+SQLite sink you can query with the `TraceQuery` API or the `sqlite3` CLI. See the docs for the full harness setup, the
+SQLite schema, and query recipes.
 
-**QueryableSpan** wraps a SpanBuffer with ergonomic helpers:
+## Package exports
 
-```typescript
-import { querySpan } from '@smoothbricks/lmao/testing';
+| Import | Provides |
+|---|---|
+| `@smoothbricks/lmao` | Core API: `defineOpContext`, `defineLogSchema`, `defineFeatureFlags`, `S`, `JsBufferStrategy`, all tracers, Arrow conversion, results (`Ok`/`Err`/`defineCodeError`), `InMemoryFlagEvaluator`, entry-type constants. |
+| `@smoothbricks/lmao/node` | `createTraceRoot` using `process.hrtime.bigint()`. |
+| `@smoothbricks/lmao/es` | `createTraceRoot` using `performance.now()` (browser/Deno/Workers). |
+| `@smoothbricks/lmao/sqlite`, `/sqlite/node` | SQLite/D1 tracers and database factories. |
+| `@smoothbricks/lmao/cloudflare` | Cloudflare trace-sink adapters (`DiagnosticDrainTracer`, `ClassSplitTracer`, transports). *Partially implemented.* |
+| `@smoothbricks/lmao/errors*` | `Transient`, `Blocked`, `defineCodeError`, backoff/retry helpers. |
+| `@smoothbricks/lmao/testing`, `/testing/bun`, `/testing/vitest` | Trace-testing query API and runner harnesses. |
 
-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
-```
+### Companion packages
 
-**Standalone functions** (tree-shakable):
+- [`@smoothbricks/lmao-inspector`](../lmao-inspector) — client-side Arrow query engine and trace sources.
+- [`@smoothbricks/lmao-transformer`](../lmao-transformer) — optional build-time TypeScript transformer (source-line
+  injection and `ctx.tag` inlining).
 
-```typescript
-import { findSpan, extractFactsFor, spanNames } from '@smoothbricks/lmao/testing';
+## Examples
 
-const span = findSpan(rootBuffer, 'validate');
-const facts = extractFactsFor(rootBuffer, 'save');
-const names = spanNames(rootBuffer);
-```
+Runnable with `bun run examples/<name>.ts`:
 
-### SQLite Persistence
+| Example | Shows |
+|---|---|
+| `basic-usage.ts` | Schema, feature flags, user context, fluent tags, child spans. |
+| `fluent-result-api.ts` | `ok`/`err` with `.with()`/`.message()`, typed error codes, exceptions. |
+| `chaining-showcase.ts` | Tag/log fluent chaining patterns. |
+| `middleware-pattern.ts` | Wrapping ops with cross-cutting behavior. |
+| `library-integration.ts` | Composing op groups across packages with `.prefix()`/`.mapColumns()`. |
+| `complete-example.ts` | An end-to-end request flow. |
+| `arrow-export.ts` | Converting a trace to an Arrow table. |
 
-When configured, the trace database is written after all tests complete. Schema columns evolve automatically based on
-your LogSchema fields.
+## License
 
+MIT

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export type { BaseSpanLogger, SpanLoggerImpl } from './lib/codegen/spanLoggerGen
 export { createSpanLogger, createSpanLoggerClass } from './lib/codegen/spanLoggerGenerator.js';
 export * from './lib/convertToArrow.js';
 export * from './lib/spanBuffer.js';
+export * from './lib/traceTopology.js';
 export * from './lib/types.js';
 export * from './lib/flushScheduler.js';
 export type { BufferStrategy } from './lib/bufferStrategy.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -48,6 +48,7 @@ export { createSpanLogger, createSpanLoggerClass } from './lib/codegen/spanLogge
 // =============================================================================
 export * from './lib/convertToArrow.js';
 export * from './lib/spanBuffer.js';
+export * from './lib/traceTopology.js';
 export * from './lib/types.js';
 // =============================================================================
 // Flush Scheduler

package/dist/lib/JsBufferStrategy.d.ts

@@ -14,6 +14,7 @@ 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 SpanBufferConstructor } from './spanBuffer.js';
 import type { ITraceRoot } from './traceRoot.js';
 import type { AnySpanBuffer, SpanBuffer } from './types.js';
 /**
@@ -40,10 +41,10 @@ export declare class JsBufferStrategy<T extends LogSchema = LogSchema> implement
      * 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>;
+    createSpanBuffer(schema: T, traceRoot: ITraceRoot, opMetadata: OpMetadata, capacity?: number, plannedClass?: SpanBufferConstructor<T>): SpanBuffer<T>;
+    createChildSpanBuffer(parentBuffer: SpanBuffer<T>, callsiteMetadata: OpMetadata, opMetadata: OpMetadata, capacity?: number, schema?: T, plannedClass?: SpanBufferConstructor<T>): SpanBuffer<T>;
     createOverflowBuffer(buffer: SpanBuffer<T>): SpanBuffer<T>;
     toArrowTable(buffer: AnySpanBuffer): Table;
-    releaseBuffer(_buffer: AnySpanBuffer): void;
+    releaseBuffer(buffer: AnySpanBuffer): void;
 }
 //# sourceMappingURL=JsBufferStrategy.d.ts.map

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

@@ -1 +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,CAE3G;IAED,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,CAKf;IAED,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAEzD;IAED,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,KAAK,CAGzC;IAED,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAG1C;CACF"}
+{"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;AACvD,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AACzB,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,CACd,MAAM,EAAE,CAAC,EACT,SAAS,EAAE,UAAU,EACrB,UAAU,EAAE,UAAU,EACtB,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACtC,UAAU,CAAC,CAAC,CAAC,CAEf;IAED,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,EACV,YAAY,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACtC,UAAU,CAAC,CAAC,CAAC,CAgBf;IAED,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAEzD;IAED,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,KAAK,CAGzC;IAED,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAEzC;CACF"}

package/dist/lib/JsBufferStrategy.js

@@ -11,7 +11,7 @@
  * @module JsBufferStrategy
  */
 import { convertSpanTreeToArrowTable } from './convertToArrow.js';
-import { createChildSpanBuffer as createChildSpanBufferImpl, createOverflowBuffer as createOverflowBufferImpl, createSpanBuffer as createSpanBufferImpl, getSpanBufferClass, } from './spanBuffer.js';
+import { createChildSpanBuffer as createChildSpanBufferImpl, createOverflowBuffer as createOverflowBufferImpl, createSpanBuffer as createSpanBufferImpl, getSpanBufferClass, resolveSpanBufferCapacity, } from './spanBuffer.js';
 function isSpanBufferConstructorForSchema(ctor, schema) {
     return ctor !== undefined && ctor.schema === schema;
 }
@@ -49,14 +49,22 @@ export class JsBufferStrategy {
         }
         return cached;
     }
-    createSpanBuffer(schema, traceRoot, opMetadata, capacity) {
-        return createSpanBufferImpl(schema, traceRoot, opMetadata, capacity);
+    createSpanBuffer(schema, traceRoot, opMetadata, capacity, plannedClass) {
+        return createSpanBufferImpl(schema, traceRoot, opMetadata, capacity, plannedClass);
     }
-    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);
+    createChildSpanBuffer(parentBuffer, callsiteMetadata, opMetadata, capacity, schema, plannedClass) {
+        const targetSchema = schema ?? parentBuffer._logSchema;
+        const metadataSpanBufferClass = opMetadata._physicalLayoutPlan?.SpanBufferClass;
+        if (metadataSpanBufferClass !== undefined &&
+            !isSpanBufferConstructorForSchema(metadataSpanBufferClass, targetSchema)) {
+            throw new TypeError('Planned SpanBuffer class does not match schema');
+        }
+        const plannedSpanBufferClass = plannedClass ?? metadataSpanBufferClass;
+        const SpanBufferClass = plannedSpanBufferClass ?? this.getSpanBufferClassForSchema(targetSchema);
+        const actualCapacity = plannedSpanBufferClass === undefined
+            ? resolveSpanBufferCapacity(capacity, SpanBufferClass.stats.capacity)
+            : capacity;
+        return createChildSpanBufferImpl(parentBuffer, SpanBufferClass, callsiteMetadata, opMetadata, actualCapacity);
     }
     createOverflowBuffer(buffer) {
         return createOverflowBufferImpl(buffer);
@@ -65,8 +73,7 @@ export class JsBufferStrategy {
         // 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
+    releaseBuffer(buffer) {
+        buffer._traceRoot._topology.release();
     }
 }

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

@@ -0,0 +1,10 @@
+import type { Table } from '@uwdata/flechette';
+export interface ArrowLease {
+    readonly table: Table;
+    readonly released: boolean;
+    release(): void;
+    [Symbol.dispose](): void;
+}
+/** Internal constructor for a lease over borrowed Arrow source chunks. */
+export declare function createArrowLease(table: Table, pinned: readonly unknown[], releases: readonly (() => void)[]): ArrowLease;
+//# sourceMappingURL=lease.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../../src/lib/arrow/lease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,SAAS,OAAO,EAAE,EAC1B,QAAQ,EAAE,SAAS,CAAC,MAAM,IAAI,CAAC,EAAE,GAChC,UAAU,CA4BZ"}