@smoothbricks/lmao 0.2.2 → 0.3.0

package/src/lib/wasm/__tests__/wasmSpanBuffer.test.ts

@@ -1,11 +1,24 @@
 import { beforeEach, describe, expect, it } from 'bun:test';
 import { S as ArrowS, Nanoseconds } from '@smoothbricks/arrow-builder';
-import { createTestOpMetadata, TEST_TRACER } from '../../__tests__/test-helpers.js';
+import fc from 'fast-check';
+import { createTestOpMetadata, createTestTraceRoot, TEST_TRACER } from '../../__tests__/test-helpers.js';
+import { defineOpContext } from '../../defineOpContext.js';
+import { type EagerColumnDescriptor, resolveEagerColumns } from '../../physicalLayoutPlan.js';
+import { resolveEntryType, resolveMessage } from '../../resolveMessage.js';
+import { RUNTIME_HINT_ANALYZED_VALID, RUNTIME_HINT_RESULT, RUNTIME_HINT_TAG } from '../../runtimeHint.js';
 import { S } from '../../schema/builder.js';
 import { defineLogSchema } from '../../schema/defineLogSchema.js';
-import { EMPTY_SCOPE } from '../../spanBuffer.js';
+import {
+  ENTRY_TYPE_INFO,
+  ENTRY_TYPE_SPAN_EXCEPTION,
+  ENTRY_TYPE_SPAN_OK,
+  ENTRY_TYPE_SPAN_START,
+} from '../../schema/systemSchema.js';
+import { createSpanBuffer, EMPTY_SCOPE } from '../../spanBuffer.js';
 import { createTraceId } from '../../traceId.js';
+import { iterateSpanChildren, NO_NODE } from '../../traceTopology.js';
 import { createWasmAllocator, type WasmAllocator } from '../wasmAllocator.js';
+import { getWasmPhysicalLayout } from '../wasmPhysicalLayout.js';
 import {
   createWasmChildSpanBuffer,
   createWasmOverflowBuffer,
@@ -31,6 +44,15 @@ function getColumn<T>(target: object, name: string): T {
   return Reflect.get(target, name);
 }
 
+function eagerDescriptorBytes(descriptor: EagerColumnDescriptor): Uint8Array {
+  const bytes = new Uint8Array(descriptor.words.length * Uint32Array.BYTES_PER_ELEMENT);
+  const view = new DataView(bytes.buffer);
+  for (let index = 0; index < descriptor.words.length; index++) {
+    view.setUint32(index * Uint32Array.BYTES_PER_ELEMENT, descriptor.words[index], true);
+  }
+  return bytes;
+}
+
 describe('WasmSpanBuffer', () => {
   let allocator: WasmAllocator;
   const CAPACITY = 64;
@@ -40,18 +62,15 @@ describe('WasmSpanBuffer', () => {
     allocator = await createWasmAllocator({ capacity: CAPACITY });
     allocator.reset();
     allocator.setThreadId(0, 42); // high=0, low=42 -> thread_id = 42n
-    traceRoot = new WasmTraceRoot(allocator, testTraceId('test-trace'), TEST_TRACER);
+    traceRoot = new WasmTraceRoot(allocator, testTraceId('trace-123'), TEST_TRACER);
   });
 
-  function createTestWasmBuffer(overrides: { trace_id?: string; thread_id?: bigint; span_id?: number } = {}) {
+  function createTestWasmBuffer() {
     return createWasmSpanBuffer(
       testSchema,
       {
         allocator,
         capacity: CAPACITY,
-        trace_id: overrides.trace_id ? testTraceId(overrides.trace_id) : testTraceId('trace-123'),
-        thread_id: overrides.thread_id ?? 42n,
-        span_id: overrides.span_id ?? 1,
       },
       traceRoot,
       EMPTY_SCOPE,
@@ -72,31 +91,150 @@ describe('WasmSpanBuffer', () => {
     duration: ArrowS.bigUint64(),
     errorMessage: S.text(),
   });
+  const testEagerColumns = resolveEagerColumns(testSchema);
+
+  const compilerEagerSchema = defineLogSchema({
+    provenNumber: S.number(),
+    lazyNumber: S.number(),
+    provenString: S.category(),
+    lazyString: S.category(),
+  });
+  const compilerEagerContext = defineOpContext({ logSchema: compilerEagerSchema });
+  const compilerEagerOp = compilerEagerContext.defineOp('compiler-eager-wasm', (ctx) => ctx.ok(null), undefined, {
+    runtimeHint: RUNTIME_HINT_ANALYZED_VALID | RUNTIME_HINT_TAG | RUNTIME_HINT_RESULT | 8,
+    eagerColumns: ['provenString', 'provenNumber', 'provenString'],
+  });
+
+  function createCompilerEagerWasmBuffer() {
+    return createWasmSpanBuffer(
+      compilerEagerSchema,
+      {
+        allocator,
+        capacity: CAPACITY,
+      },
+      traceRoot,
+      EMPTY_SCOPE,
+      compilerEagerOp.metadata,
+      compilerEagerOp.metadata,
+    );
+  }
 
   describe('getWasmSpanBufferClass', () => {
     it('generates a class constructor', () => {
-      const WasmSpanBufferClass = getWasmSpanBufferClass(testSchema);
+      const WasmSpanBufferClass = getWasmSpanBufferClass(testSchema, 'mixed', 'current', testEagerColumns);
       expect(typeof WasmSpanBufferClass).toBe('function');
       expect(WasmSpanBufferClass.schema).toBe(testSchema);
     });
 
     it('caches classes per schema', () => {
-      const class1 = getWasmSpanBufferClass(testSchema);
-      const class2 = getWasmSpanBufferClass(testSchema);
+      const class1 = getWasmSpanBufferClass(testSchema, 'mixed', 'current', testEagerColumns);
+      const class2 = getWasmSpanBufferClass(testSchema, 'mixed', 'current', testEagerColumns);
       expect(class1).toBe(class2);
     });
 
     it('creates different classes for different schemas', () => {
       const schema2 = defineLogSchema({ otherField: S.number() });
-      const class1 = getWasmSpanBufferClass(testSchema);
-      const class2 = getWasmSpanBufferClass(schema2);
+      const class1 = getWasmSpanBufferClass(testSchema, 'mixed', 'current', testEagerColumns);
+      const class2 = getWasmSpanBufferClass(schema2, 'mixed', 'current', resolveEagerColumns(schema2));
       expect(class1).not.toBe(class2);
     });
   });
 
+  describe('exact physical layout', () => {
+    it('produces aligned, exact, non-overlapping family descriptors for arbitrary capacities', () => {
+      fc.assert(
+        fc.property(fc.integer({ min: 1, max: 512 }), (capacity) => {
+          const layout = getWasmPhysicalLayout(testSchema, capacity, 'mixed', 'current', testEagerColumns);
+          expect(layout).toBe(getWasmPhysicalLayout(testSchema, capacity, 'mixed', 'current', testEagerColumns));
+          expect(Object.isFrozen(layout)).toBe(true);
+          expect(layout.system.timestampOffset).toBe(0);
+          expect(layout.system.entryTypeOffset).toBe(capacity * 8);
+          const messageIdOffset = (capacity * 9 + 1) & ~1;
+          const expectedByteLength = (messageIdOffset + capacity * Uint16Array.BYTES_PER_ELEMENT + 7) & ~7;
+          expect(layout.messageLayoutFamily).toBe('mixed');
+          expect(layout.messagePhysicalLayout).toBe('current');
+          expect(layout.system.messageIdOffset).toBe(messageIdOffset);
+          expect('messageIdValidityOffset' in layout.system).toBe(false);
+          expect(layout.system.messageDenseIndexOffset).toBeNull();
+          expect('messageValidityOffset' in layout.system).toBe(false);
+          expect(layout.system.rowHeaderOffset).toBeNull();
+          expect(layout.system.byteLength).toBe(expectedByteLength);
+
+          expect(Object.isFrozen(layout.spanSuperblock)).toBe(true);
+          expect(Object.isFrozen(layout.overflowSuperblock)).toBe(true);
+          expect(layout.spanSuperblock.identityOffset).toBe(0);
+          expect(layout.overflowSuperblock.identityOffset).toBeNull();
+          expect(layout.spanSuperblock.systemOffset % layout.system.alignment).toBe(0);
+          expect(layout.overflowSuperblock.systemOffset % layout.system.alignment).toBe(0);
+          expect(layout.spanSuperblock.byteLength).toBeLessThanOrEqual(layout.spanSuperblock.legacyByteLength);
+          expect(layout.overflowSuperblock.byteLength).toBeLessThanOrEqual(layout.overflowSuperblock.legacyByteLength);
+
+          for (const family of ['u8', 'u32', 'f64'] as const) {
+            const slab = layout.slabs[family];
+            const columns = layout.columns.filter((column) => column.family === family);
+            expect(slab === null).toBe(columns.length === 0);
+            if (slab === null) continue;
+
+            const ranges: Array<readonly [number, number]> = [];
+            for (const column of columns) {
+              expect(column.valueOffset % column.alignment).toBe(0);
+              expect(column.nullByteLength).toBe(Math.ceil(capacity / 8));
+              expect(column.valueLength).toBe(capacity * column.byteWidth);
+              expect(column.nullOffset + column.nullByteLength).toBeLessThanOrEqual(column.valueOffset);
+              expect(column.valueOffset + column.valueLength).toBeLessThanOrEqual(slab.byteLength);
+
+              const columnRanges = [
+                [column.nullOffset, column.nullOffset + column.nullByteLength],
+                [column.valueOffset, column.valueOffset + column.valueLength],
+              ] as const;
+              for (const [start, end] of columnRanges) {
+                for (const [otherStart, otherEnd] of ranges) {
+                  expect(end <= otherStart || start >= otherEnd).toBe(true);
+                }
+                ranges.push([start, end]);
+              }
+            }
+          }
+        }),
+      );
+    });
+
+    it('allocates one packed superblock and no further blocks on numeric writes', () => {
+      const allocsBefore = allocator.getAllocCount();
+      const buffer = createTestWasmBuffer();
+      expect(allocator.getAllocCount() - allocsBefore).toBe(1);
+      expect(buffer._allocationPtr).toBe(buffer._identityPtr);
+      expect(buffer._systemPtr).toBe(buffer._allocationPtr + buffer._layout.spanSuperblock.systemOffset);
+      expect(buffer._allocationByteLength).toBe(buffer._layout.spanSuperblock.byteLength);
+
+      const ranges: Array<readonly [number, number]> = [
+        [buffer._identityPtr, buffer._identityPtr + 128],
+        [buffer._systemPtr, buffer._systemPtr + buffer._layout.system.byteLength],
+      ];
+      for (const family of ['u8', 'u32', 'f64'] as const) {
+        const slab = buffer._layout.slabs[family];
+        if (slab === null) continue;
+        const start = buffer._familyPtrs[family];
+        const end = start + slab.byteLength;
+        expect(start % slab.alignment).toBe(0);
+        expect(start).toBe(buffer._allocationPtr + buffer._layout.spanSuperblock.familyOffsets[family]);
+        for (const [otherStart, otherEnd] of ranges) {
+          expect(end <= otherStart || start >= otherEnd).toBe(true);
+        }
+        ranges.push([start, end]);
+      }
+
+      const count = getMethod<[idx: number, val: number], WasmSpanBufferInstance>(buffer, 'count');
+      const isAdmin = getMethod<[idx: number, val: boolean], WasmSpanBufferInstance>(buffer, 'isAdmin');
+      count(3, 42);
+      isAdmin(4, true);
+      expect(allocator.getAllocCount() - allocsBefore).toBe(1);
+    });
+  });
+
   describe('instance creation', () => {
     it('creates instance with correct identity', () => {
-      const buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 42n, span_id: 1 });
+      const buffer = createTestWasmBuffer();
 
       expect(buffer.trace_id).toBe(testTraceId('trace-123'));
       expect(buffer.thread_id).toBe(42n);
@@ -106,14 +244,60 @@ describe('WasmSpanBuffer', () => {
       expect(buffer._hasParent).toBe(false);
     });
 
+    it('consumes native lifecycle initialization without restamping row 0', () => {
+      const buffer = createTestWasmBuffer();
+      const entryTypes = buffer.entry_type;
+      if (entryTypes === undefined) throw new Error('missing entry types');
+
+      expect(buffer._spanStartedAtAllocation).toBe(true);
+      expect(buffer._writeIndex).toBe(2);
+      expect(entryTypes[0]).toBe(ENTRY_TYPE_SPAN_START);
+      expect(entryTypes[1]).toBe(ENTRY_TYPE_SPAN_EXCEPTION);
+      buffer.timestamp[0] = 123_456_789n;
+
+      traceRoot.writeSpanStart(buffer, 'prestarted-span');
+
+      expect(buffer._spanStartedAtAllocation).toBe(false);
+      expect(buffer.timestamp[0]).toBe(123_456_789n);
+      const messages = buffer.message_values;
+      if (messages === undefined) throw new Error('missing messages');
+      expect(messages[0]).toBe('prestarted-span');
+      expect(buffer._writeIndex).toBe(2);
+    });
+
+    it('uses each buffer capacity for native lifecycle writes', () => {
+      const seededCapacity = 6;
+      const metadata = createTestOpMetadata();
+      const buffer = createWasmSpanBuffer(
+        testSchema,
+        { allocator, capacity: seededCapacity },
+        traceRoot,
+        EMPTY_SCOPE,
+        metadata,
+        metadata,
+      );
+
+      traceRoot.writeSpanStart(buffer, 'seeded-capacity');
+      const row = traceRoot.writeLogEntry(buffer, ENTRY_TYPE_INFO);
+      traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_OK);
+
+      expect(buffer._capacity).toBe(seededCapacity);
+      expect(row).toBe(2);
+      expect(buffer.entry_type?.[0]).toBe(ENTRY_TYPE_SPAN_START);
+      expect(buffer.entry_type?.[1]).toBe(ENTRY_TYPE_SPAN_OK);
+      expect(buffer.entry_type?.[2]).toBe(ENTRY_TYPE_INFO);
+      expect(buffer.timestamp[1]).toBeGreaterThan(0n);
+      expect(buffer.timestamp[2]).toBeGreaterThan(0n);
+    });
+
     it('creates instance with parent identity via child buffer', () => {
       // Parent identity is now set by linking buffers, not via opts
       // Create parent first, then create child that references it
-      const parent = createTestWasmBuffer({ trace_id: 'trace-456', thread_id: 100n, span_id: 2 });
+      const parent = createTestWasmBuffer();
 
       const child = createWasmChildSpanBuffer(
         parent,
-        { allocator, capacity: CAPACITY, thread_id: 100n, span_id: 5 },
+        { allocator, capacity: CAPACITY },
         traceRoot,
         EMPTY_SCOPE,
         createTestOpMetadata(),
@@ -129,17 +313,20 @@ describe('WasmSpanBuffer', () => {
     it('allocates system block from WASM', () => {
       const beforeAllocs = allocator.getAllocCount();
 
-      createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      createTestWasmBuffer();
 
       // Should have allocated at least the system block
       expect(allocator.getAllocCount()).toBeGreaterThan(beforeAllocs);
     });
 
     it('initializes tree structure', () => {
-      const buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      const buffer = createTestWasmBuffer();
+      traceRoot._topology.registerRoot(buffer);
 
       expect(buffer._parent).toBeNull();
-      expect(buffer._children).toEqual([]);
+      expect(buffer._nodeIndex).toBe(traceRoot._topology.root);
+      expect(traceRoot._topology.buffers[buffer._nodeIndex]).toBe(buffer);
+      expect(traceRoot._topology.firstChild[buffer._nodeIndex]).toBe(NO_NODE);
       expect(buffer._overflow).toBeNull();
     });
   });
@@ -148,7 +335,7 @@ describe('WasmSpanBuffer', () => {
     let buffer: WasmSpanBufferInstance;
 
     beforeEach(() => {
-      buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      buffer = createTestWasmBuffer();
     });
 
     it('provides timestamp view into WASM memory', () => {
@@ -159,6 +346,7 @@ describe('WasmSpanBuffer', () => {
 
     it('provides entry_type view into WASM memory', () => {
       const entryType = buffer.entry_type;
+      if (entryType === undefined) throw new Error('Expected split entry-type lane');
       expect(entryType).toBeInstanceOf(Uint8Array);
       expect(entryType.length).toBe(CAPACITY);
     });
@@ -171,17 +359,55 @@ describe('WasmSpanBuffer', () => {
 
     it('can write to entry_type array', () => {
       const entryType = buffer.entry_type;
+      if (entryType === undefined) throw new Error('Expected split entry-type lane');
       entryType[0] = 1; // SPAN_START
       entryType[1] = 2; // SPAN_OK
-      expect(buffer.entry_type[0]).toBe(1);
-      expect(buffer.entry_type[1]).toBe(2);
+      expect(resolveEntryType(buffer, 0)).toBe(1);
+      expect(resolveEntryType(buffer, 1)).toBe(2);
+    });
+
+    it('reuses canonical typed views while memory is stable', () => {
+      const timestamp = buffer.timestamp;
+      const entryType = buffer.entry_type;
+      const identity = buffer._identity;
+      const countValues = getColumn<Float64Array>(buffer, 'count_values');
+      const countNulls = getColumn<Uint8Array>(buffer, 'count_nulls');
+      const count = getMethod<[idx: number, val: number], WasmSpanBufferInstance>(buffer, 'count');
+
+      count(5, 999);
+
+      expect(buffer.timestamp).toBe(timestamp);
+      expect(buffer.entry_type).toBe(entryType);
+      expect(buffer._identity).toBe(identity);
+      expect(getColumn<Float64Array>(buffer, 'count_values')).toBe(countValues);
+      expect(getColumn<Uint8Array>(buffer, 'count_nulls')).toBe(countNulls);
+      expect(countValues[5]).toBe(999);
     });
 
-    it('views reflect same WASM memory', () => {
-      buffer.timestamp[5] = 999n;
-      // Get a new view and verify it sees the same data
-      const newView = buffer.timestamp;
-      expect(newView[5]).toBe(999n);
+    it('rebuilds every canonical view once after memory growth and preserves data', () => {
+      buffer.timestamp[3] = 123n;
+      const count = getMethod<[idx: number, val: number], WasmSpanBufferInstance>(buffer, 'count');
+      count(4, 456);
+      const timestampBefore = buffer.timestamp;
+      const identityBefore = buffer._identity;
+      const countBefore = getColumn<Float64Array>(buffer, 'count_values');
+      const versionBefore = buffer._descriptor.memoryVersion;
+
+      const growthAllocation = allocator.allocExact(allocator.memory.buffer.byteLength, 8);
+      expect(growthAllocation).toBeGreaterThan(0);
+      const timestampAfter = buffer.timestamp;
+      const identityAfter = buffer._identity;
+      const countAfter = getColumn<Float64Array>(buffer, 'count_values');
+
+      expect(buffer._descriptor.memoryVersion).toBeGreaterThan(versionBefore);
+      expect(timestampAfter).not.toBe(timestampBefore);
+      expect(identityAfter).not.toBe(identityBefore);
+      expect(countAfter).not.toBe(countBefore);
+      expect(buffer.timestamp).toBe(timestampAfter);
+      expect(buffer._identity).toBe(identityAfter);
+      expect(getColumn<Float64Array>(buffer, 'count_values')).toBe(countAfter);
+      expect(timestampAfter[3]).toBe(123n);
+      expect(countAfter[4]).toBe(456);
     });
 
     it('exposes _spanStartTime from row 0', () => {
@@ -215,17 +441,17 @@ describe('WasmSpanBuffer', () => {
     let buffer: WasmSpanBufferInstance;
 
     beforeEach(() => {
-      buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      buffer = createTestWasmBuffer();
     });
 
     it('can write message values', () => {
       buffer.message(0, 'span-start message');
       buffer.message(1, 'span-end message');
       buffer.message(2, 'log entry');
-
-      expect(buffer._message[0]).toBe('span-start message');
-      expect(buffer._message[1]).toBe('span-end message');
-      expect(buffer._message[2]).toBe('log entry');
+      expect('message_nulls' in buffer).toBe(false);
+      expect(resolveMessage(buffer, 0)).toBe('span-start message');
+      expect(resolveMessage(buffer, 1)).toBe('span-end message');
+      expect(resolveMessage(buffer, 2)).toBe('log entry');
     });
 
     it('returns this for chaining', () => {
@@ -238,7 +464,7 @@ describe('WasmSpanBuffer', () => {
     let buffer: WasmSpanBufferInstance;
 
     beforeEach(() => {
-      buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      buffer = createTestWasmBuffer();
     });
 
     it('userId column starts undefined', () => {
@@ -254,6 +480,19 @@ describe('WasmSpanBuffer', () => {
       expect(buffer.getNullsIfAllocated('userId')).toBeDefined();
     });
 
+    it('allocates lazy storage for transformer-style direct writes', () => {
+      const userIdNulls = getColumn<Uint8Array>(buffer, 'userId_nulls');
+      const userIdValues = getColumn<string[]>(buffer, 'userId_values');
+
+      userIdNulls[0] |= 1;
+      userIdValues[0] = 'direct-write';
+
+      expect(buffer.getColumnIfAllocated('userId')).toBe(userIdValues);
+      expect(buffer.getNullsIfAllocated('userId')).toBe(userIdNulls);
+      expect(userIdValues[0]).toBe('direct-write');
+      expect(userIdNulls[0] & 1).toBe(1);
+    });
+
     it('writes values to category column', () => {
       const userId = getMethod<[idx: number, val: string], WasmSpanBufferInstance>(buffer, 'userId');
 
@@ -304,18 +543,26 @@ describe('WasmSpanBuffer', () => {
     let buffer: WasmSpanBufferInstance;
 
     beforeEach(() => {
-      buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      buffer = createTestWasmBuffer();
     });
 
-    it('count column starts unallocated', () => {
-      expect(buffer.isColumnAllocated(2)).toBe(false); // count is at index 2
+    it('reserves numeric bytes in the family slab without materializing the lazy lane', () => {
+      const countIndex = testSchema._columnNames.indexOf('count');
+      if (countIndex < 0) throw new Error('missing count schema field');
+      expect(buffer._layout.columns.some((column) => column.name === 'count')).toBe(true);
+      expect(buffer.isColumnAllocated(countIndex)).toBe(false);
+      expect(buffer.getColumnIfAllocated('count')).toBeUndefined();
+      expect(Reflect.get(buffer, '_count_values')).toBeUndefined();
+      expect(Reflect.get(buffer, '_count_nulls')).toBeUndefined();
     });
 
-    it('allocates count column on first write', () => {
+    it('writes without allocating another block', () => {
       const count = getMethod<[idx: number, val: number], WasmSpanBufferInstance>(buffer, 'count');
+      const allocsBefore = allocator.getAllocCount();
       count(0, 42);
-
-      expect(buffer.isColumnAllocated(2)).toBe(true);
+      expect(allocator.getAllocCount()).toBe(allocsBefore);
+      expect(buffer.getColumnIfAllocated('count')).toBeInstanceOf(Float64Array);
+      expect(buffer.getNullsIfAllocated('count')).toBeInstanceOf(Uint8Array);
     });
 
     it('writes to numeric column', () => {
@@ -339,37 +586,135 @@ describe('WasmSpanBuffer', () => {
 
   describe('eager numeric columns', () => {
     it('statusCode column is pre-allocated', () => {
-      const buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      const buffer = createTestWasmBuffer();
 
       // statusCode is at index 3 and marked eager
       expect(buffer.isColumnAllocated(3)).toBe(true);
     });
   });
 
-  describe('free()', () => {
-    it('frees system block', () => {
-      const buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+  describe('compiler-proven eager columns', () => {
+    it('shares exact frozen descriptor bytes and eager storage across root, child, and overflow', () => {
+      const descriptor = compilerEagerOp.callsitePlan.eagerColumns;
+      const planSchema = compilerEagerOp.callsitePlan.schema;
+      const expectedWords = new Array<number>(Math.ceil(planSchema._columnNames.length / 32)).fill(0);
+      for (const name of ['provenNumber', 'provenString']) {
+        const ordinal = planSchema._columnNames.indexOf(name);
+        if (ordinal < 0) throw new Error(`missing compiler eager schema field ${name}`);
+        expectedWords[ordinal >>> 5] = (expectedWords[ordinal >>> 5] | (1 << (ordinal & 31))) >>> 0;
+      }
+      while (expectedWords.length > 0 && expectedWords[expectedWords.length - 1] === 0) expectedWords.pop();
 
+      expect(descriptor.names).toEqual(['provenNumber', 'provenString']);
+      expect(descriptor.words).toEqual(expectedWords);
+      expect(eagerDescriptorBytes(descriptor).byteLength).toBe(descriptor.words.length * 4);
+      expect(Object.isFrozen(descriptor)).toBe(true);
+      expect(Object.isFrozen(descriptor.names)).toBe(true);
+      expect(Object.isFrozen(descriptor.words)).toBe(true);
+      expect(compilerEagerOp.callsitePlan.wasmLayout.eagerColumns).toBe(descriptor);
+
+      const root = createCompilerEagerWasmBuffer();
+      const child = createWasmChildSpanBuffer(
+        root,
+        { allocator, capacity: CAPACITY },
+        traceRoot,
+        EMPTY_SCOPE,
+        compilerEagerOp.metadata,
+        compilerEagerOp.metadata,
+      );
+      const overflow = createWasmOverflowBuffer(
+        child,
+        traceRoot,
+        EMPTY_SCOPE,
+        compilerEagerOp.metadata,
+        compilerEagerOp.metadata,
+      );
+
+      for (const buffer of [root, child, overflow]) {
+        expect(buffer._layout.eagerColumns).toBe(descriptor);
+        for (const name of ['provenNumber', 'provenString']) {
+          expect(Object.hasOwn(buffer, `_${name}_values`)).toBe(true);
+          expect(Object.hasOwn(buffer, `_${name}_nulls`)).toBe(true);
+          expect(Reflect.get(buffer, `_${name}_values`)).toBeDefined();
+          expect(Reflect.get(buffer, `_${name}_nulls`)).toBeInstanceOf(Uint8Array);
+        }
+        for (const name of ['lazyNumber', 'lazyString']) {
+          expect(Reflect.get(buffer, `_${name}_values`)).toBeUndefined();
+          expect(Reflect.get(buffer, `_${name}_nulls`)).toBeUndefined();
+          expect(buffer.getColumnIfAllocated(name)).toBeUndefined();
+          expect(buffer.getNullsIfAllocated(name)).toBeUndefined();
+        }
+      }
+      expect(child._parent).toBe(root);
+      expect(overflow._parent).toBe(root);
+      expect(overflow._identityPtr).toBe(child._identityPtr);
+      expect(overflow._descriptor.layout).toBe(child._descriptor.layout);
+
+      root.provenNumber(0, 73);
+      root.provenNumber(1, null);
+      root.provenString(2, 'wasm-value');
+      overflow.provenNumber(3, null);
+
+      const jsBuffer = createSpanBuffer(
+        planSchema,
+        createTestTraceRoot('compiler-eager-js'),
+        compilerEagerOp.metadata,
+        CAPACITY,
+        compilerEagerOp.callsitePlan.SpanBufferClass,
+      );
+      jsBuffer.provenNumber(0, 73);
+      jsBuffer.provenNumber(1, null);
+      jsBuffer.provenString(2, 'wasm-value');
+
+      for (const name of ['provenNumber', 'provenString']) {
+        const wasmValues = root.getColumnIfAllocated(name);
+        const jsValues = jsBuffer.getColumnIfAllocated(name);
+        const wasmNulls = root.getNullsIfAllocated(name);
+        const jsNulls = jsBuffer.getNullsIfAllocated(name);
+        if (!wasmValues || !jsValues || !wasmNulls || !jsNulls) {
+          throw new Error(`missing eager JS/WASM parity storage for ${name}`);
+        }
+        for (const row of [0, 1, 2, 3]) expect(wasmValues[row]).toEqual(jsValues[row]);
+        expect([...wasmNulls]).toEqual([...jsNulls]);
+      }
+
+      const lazyString = getMethod<[index: number, value: string], WasmSpanBufferInstance>(root, 'lazyString');
+      lazyString(4, 'first lazy write');
+      expect(root.getColumnIfAllocated('lazyString')?.[4]).toBe('first lazy write');
+      const lazyStringNulls = root.getNullsIfAllocated('lazyString');
+      if (!lazyStringNulls) throw new Error('missing lazy string null bitmap after first write');
+      expect(lazyStringNulls[0] & 0b00010000).toBe(0b00010000);
+
+      const schemaEager = createTestWasmBuffer();
+      expect(schemaEager.getColumnIfAllocated('statusCode')).toBeDefined();
+      expect(schemaEager.getNullsIfAllocated('statusCode')).toBeUndefined();
+    });
+  });
+
+  describe('free()', () => {
+    it('releases its owned superblock once', () => {
+      const buffer = createTestWasmBuffer();
       const freesBefore = allocator.getFreeCount();
+
       buffer.free();
 
-      expect(allocator.getFreeCount()).toBeGreaterThan(freesBefore);
+      expect(allocator.getFreeCount() - freesBefore).toBe(1);
+      expect(buffer._descriptor.state).toBe('freed');
     });
 
-    it('frees allocated column blocks', () => {
-      const buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
-
-      // Write to lazy columns to allocate them
+    it('is idempotent and rejects every stale accessor and writer', () => {
+      const buffer = createTestWasmBuffer();
       const count = getMethod<[idx: number, val: number], WasmSpanBufferInstance>(buffer, 'count');
-      const isAdmin = getMethod<[idx: number, val: boolean], WasmSpanBufferInstance>(buffer, 'isAdmin');
-      count(0, 42);
-      isAdmin(0, true);
+      buffer.free();
+      const freesAfterFirstRelease = allocator.getFreeCount();
 
-      const freesBefore = allocator.getFreeCount();
       buffer.free();
 
-      // Should free system block + statusCode (eager) + count + isAdmin
-      expect(allocator.getFreeCount()).toBeGreaterThan(freesBefore + 1);
+      expect(allocator.getFreeCount()).toBe(freesAfterFirstRelease);
+      expect(() => buffer.timestamp).toThrow(/generation .* released/);
+      expect(() => buffer.entry_type).toThrow(/generation .* released/);
+      expect(() => buffer._identity).toThrow(/generation .* released/);
+      expect(() => count(0, 42)).toThrow(/generation .* released/);
     });
   });
 
@@ -378,26 +723,31 @@ describe('WasmSpanBuffer', () => {
       // thread_id is global in WASM header, shared by parent and child
       allocator.setThreadId(0, 1); // thread_id = 1n
 
-      const parent = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      const parent = createTestWasmBuffer();
+      traceRoot._topology.registerRoot(parent);
 
       const child = createWasmChildSpanBuffer(
         parent,
-        { allocator, capacity: CAPACITY, thread_id: 2n, span_id: 2 },
+        { allocator, capacity: CAPACITY },
         traceRoot,
         EMPTY_SCOPE,
         createTestOpMetadata(),
         createTestOpMetadata({ name: 'child-span', line: 0 }),
       );
 
-      // Manually push to _children - SpanContext does this with possible RemappedBufferView wrapper
-      parent._children.push(child);
+      traceRoot._topology.registerChild(parent, child);
 
       expect(child._parent).toBe(parent);
-      expect(parent._children).toContain(child);
+      expect(Array.from(iterateSpanChildren(parent))).toEqual([child]);
       expect(child.trace_id).toBe(testTraceId('trace-123'));
       // Parent and child share thread_id from global header
       expect(child.parent_thread_id).toBe(1n);
       expect(child.parent_span_id).toBe(1);
+      expect(child._identityPtr).not.toBe(parent._identityPtr);
+      expect(child._identityOwner).toBe(true);
+      expect(child._descriptor.kind).toBe('child');
+      expect(child._descriptor.parent).toBe(parent._descriptor);
+      expect(child._descriptor.generation).toBeGreaterThan(parent._descriptor.generation);
     });
   });
 
@@ -406,7 +756,8 @@ describe('WasmSpanBuffer', () => {
       // thread_id is global in WASM header
       allocator.setThreadId(0, 1); // thread_id = 1n
 
-      const buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      const buffer = createTestWasmBuffer();
+      const allocsBefore = allocator.getAllocCount();
 
       const overflow = createWasmOverflowBuffer(
         buffer,
@@ -415,14 +766,19 @@ describe('WasmSpanBuffer', () => {
         createTestOpMetadata(),
         createTestOpMetadata(),
       );
+      expect(allocator.getAllocCount() - allocsBefore).toBe(1);
 
       expect(buffer._overflow).toBe(overflow);
       expect(overflow._parent).toBe(buffer._parent); // Same parent (null for root)
       expect(overflow.trace_id).toBe(testTraceId('trace-123'));
       expect(overflow.thread_id).toBe(1n);
-      // Note: span_id is unique per identity block, not shared with original
-      // overflow has its own span_id from allocIdentityChild
-      expect(overflow.span_id).toBeGreaterThan(0);
+      expect(overflow.span_id).toBe(buffer.span_id);
+      expect(overflow._identityPtr).toBe(buffer._identityPtr);
+      expect(overflow._identityOwner).toBe(false);
+      expect(overflow._descriptor.kind).toBe('overflow');
+      expect(overflow._descriptor.parent).toBeUndefined();
+      expect(buffer._descriptor.overflow).toBe(overflow._descriptor);
+      expect(overflow._descriptor.generation).toBeGreaterThan(buffer._descriptor.generation);
     });
   });
 
@@ -431,7 +787,7 @@ describe('WasmSpanBuffer', () => {
       // thread_id is global in WASM header
       allocator.setThreadId(0, 1); // thread_id = 1n
 
-      const buffer = createTestWasmBuffer({ trace_id: 'trace-123', thread_id: 1n, span_id: 1 });
+      const buffer = createTestWasmBuffer();
 
       // Get custom inspect
       const inspectSymbol = Symbol.for('nodejs.util.inspect.custom');