@smoothbricks/lmao 0.2.2 → 0.3.0

package/dist/lib/spanBuffer.js

@@ -24,16 +24,16 @@
  *
  * @module spanBuffer
  */
-import { DEFAULT_BUFFER_CAPACITY, getColumnBufferClass } from '@smoothbricks/arrow-builder';
+import { activeMaterializerMode, DEFAULT_BUFFER_CAPACITY, getColumnBufferClass, } from '@smoothbricks/arrow-builder';
 import { checkCapacityTuning } from './capacityTuning.js';
-import { textEncoder } from './spanBufferHelpers.js';
-import { writeThreadIdToUint64Array } from './threadId.js';
+import { LogSchema } from './schema/LogSchema.js';
+import { copyThreadIdTo, getThreadId } from './threadId.js';
+import { getVocabularyGeneration } from './vocabularyRegistry.js';
 /**
  * Empty frozen scope object - shared singleton to avoid allocations.
  * Used as default _scopeValues for all buffers until setScope() is called.
  */
 export const EMPTY_SCOPE = Object.freeze({});
-const traceIdDecoder = new TextDecoder();
 // ============================================================================
 // Thread-local state (generated once per process/worker)
 // These are used by the generated class code via the constructorPreamble
@@ -91,6 +91,8 @@ function isGeneratedSpanBufferClass(ctor) {
         return false;
     }
     return (typeof Reflect.get(prototype, 'getOrCreateOverflow') === 'function' &&
+        typeof Reflect.get(prototype, '_sealStats') === 'function' &&
+        typeof Reflect.get(prototype, '_sealStatsChain') === 'function' &&
         typeof Reflect.get(prototype, 'isParentOf') === 'function' &&
         typeof Reflect.get(prototype, 'isChildOf') === 'function');
 }
@@ -106,21 +108,396 @@ function getSpanBufferConstructorForBuffer(buffer) {
     }
     return ctor;
 }
-function createSpanBufferConstructor(schema, generatedClass) {
-    return Object.assign(generatedClass, {
-        schema,
+function createSpanBufferConstructor(schema, messageLayoutFamily, messagePhysicalLayout, generatedClass, eagerColumns) {
+    Object.defineProperties(generatedClass, {
+        schema: { value: schema, enumerable: true },
+        messageLayoutFamily: { value: messageLayoutFamily, enumerable: true },
+        messagePhysicalLayout: { value: messagePhysicalLayout, enumerable: true },
+        eagerColumns: { value: eagerColumns, enumerable: true },
         stats: {
-            capacity: DEFAULT_BUFFER_CAPACITY,
-            totalWrites: 0,
-            spansCreated: 0,
+            value: {
+                capacity: DEFAULT_BUFFER_CAPACITY,
+                totalWrites: 0,
+                spansCreated: 0,
+            },
+            enumerable: true,
         },
     });
+    if (!isSpanBufferConstructorForSchema(generatedClass, schema)) {
+        throw new TypeError('Generated column buffer constructor initialization failed');
+    }
+    return generatedClass;
 }
 /**
  * Cache for generated SpanBuffer classes per schema.
  * Key is the schema object reference (WeakMap for GC).
  */
 const spanBufferClassCache = new WeakMap();
+const messageStorageSchemas = new WeakMap();
+const EMPTY_EAGER_COLUMNS = Object.freeze({
+    names: Object.freeze([]),
+    words: Object.freeze([]),
+    key: '',
+});
+function resolveCompiledEagerColumns(schema, requestedNames) {
+    if (requestedNames.length === 0)
+        return EMPTY_EAGER_COLUMNS;
+    const requested = new Set(requestedNames);
+    const names = [];
+    const words = new Array(Math.ceil(schema._columnNames.length / 32)).fill(0);
+    for (let columnIndex = 0; columnIndex < schema._columnNames.length; columnIndex++) {
+        const name = schema._columnNames[columnIndex];
+        if (!requested.delete(name))
+            continue;
+        names.push(name);
+        const wordIndex = columnIndex >>> 5;
+        words[wordIndex] = (words[wordIndex] | (1 << (columnIndex & 31))) >>> 0;
+    }
+    if (requested.size !== 0) {
+        throw new TypeError(`Unknown compiled eager column${requested.size === 1 ? '' : 's'}: ${[...requested].join(', ')}`);
+    }
+    while (words.length !== 0 && words[words.length - 1] === 0)
+        words.pop();
+    const frozenWords = Object.freeze(words);
+    return Object.freeze({
+        names: Object.freeze(names),
+        words: frozenWords,
+        key: frozenWords.map((word) => word.toString(16).padStart(8, '0')).join(''),
+    });
+}
+function getStorageSchema(schema, messageLayoutFamily, messagePhysicalLayout) {
+    let byLayout = messageStorageSchemas.get(schema);
+    const key = `${messageLayoutFamily}:${messagePhysicalLayout}`;
+    let storageSchema = byLayout?.get(key);
+    if (storageSchema === undefined) {
+        const fields = {};
+        for (const [name, field] of schema._columns) {
+            if (name !== 'message')
+                fields[name] = field;
+        }
+        storageSchema = new LogSchema(fields);
+        byLayout ??= new Map();
+        byLayout.set(key, storageSchema);
+        messageStorageSchemas.set(schema, byLayout);
+    }
+    return storageSchema;
+}
+/**
+ * Canonicalize a ttsc-emitted SpanBuffer class into the same schema/layout cache
+ * used by the dynamic fallback. The factory is lazy so an already materialized
+ * class wins without allocating a duplicate constructor.
+ */
+export function materializeCompiledSpanBufferClass(schema, messageLayoutFamily, messagePhysicalLayout, eagerColumnNames, factory) {
+    const eagerColumns = resolveCompiledEagerColumns(schema, eagerColumnNames);
+    // Mode-prefixed like arrow-builder's class caches: the materializer mode is fixed for a process,
+    // but the parity suite flips it via override and must never see the other mode's class.
+    const cacheKey = `${activeMaterializerMode()}:${messageLayoutFamily}:${messagePhysicalLayout}:${eagerColumns.key}`;
+    let familyClasses = spanBufferClassCache.get(schema);
+    const cached = familyClasses?.get(cacheKey);
+    if (isSpanBufferConstructorForSchema(cached, schema) &&
+        cached.messageLayoutFamily === messageLayoutFamily &&
+        cached.messagePhysicalLayout === messagePhysicalLayout) {
+        return cached;
+    }
+    const compiledClass = factory();
+    if (!isGeneratedSpanBufferClass(compiledClass)) {
+        throw new TypeError('Compiled SpanBuffer class is missing the required buffer contract');
+    }
+    const SpanBufferClass = createSpanBufferConstructor(schema, messageLayoutFamily, messagePhysicalLayout, compiledClass, eagerColumns);
+    familyClasses ??= new Map();
+    familyClasses.set(cacheKey, SpanBufferClass);
+    spanBufferClassCache.set(schema, familyClasses);
+    return SpanBufferClass;
+}
+function isSpanBufferConstructorValue(value) {
+    return typeof value === 'function';
+}
+function spanBufferStatics(self) {
+    const ctor = self.constructor;
+    if (!isSpanBufferConstructorValue(ctor))
+        throw new TypeError('SpanBuffer constructor is not initialized');
+    return ctor;
+}
+/** Constructor arguments arrive untyped through the materializer; every real buffer/traceRoot is an object. */
+function isSpanBufferValue(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isTraceRootValue(value) {
+    return typeof value === 'object' && value !== null;
+}
+function requireParent(parent) {
+    if (parent === undefined)
+        throw new TypeError('Chained/child SpanBuffer construction requires a parent buffer');
+    return parent;
+}
+/** Every runtime SpanBuffer instance satisfies the typed SpanBuffer contract (dynamic column lanes included). */
+function isTypedSpanBuffer(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Mirrors the generated `_sealStats` body (shared with getOrCreateOverflow). */
+function sealStatsFor(self) {
+    if (self._statsSealed)
+        return;
+    const completedRows = self._writeIndex - self._statsReservedRows;
+    if (completedRows > 0)
+        spanBufferStatics(self).stats.totalWrites += completedRows;
+    self._statsSealed = true;
+}
+/**
+ * No-eval counterpart of the extension `constructorPreamble` (and its
+ * `constructorParams` signature): identical buffer-type branches (root /
+ * child / chained), identical physical system layout math, identical
+ * property-assignment order (V8 in-object slots).
+ */
+function createSpanBufferClosureInit(messageLayoutFamily, messagePhysicalLayout) {
+    return (self, requestedCapacity, ctorArgs) => {
+        // ctorArgs mirror constructorParams: stats, parent, isChained, callsiteMetadata, opMetadata, traceRoot, vocabularyGeneration
+        const parent = isSpanBufferValue(ctorArgs[1]) ? ctorArgs[1] : undefined;
+        const isChained = Boolean(ctorArgs[2]);
+        const callsiteMetadata = ctorArgs[3];
+        const opMetadata = ctorArgs[4];
+        const traceRootArg = ctorArgs[5];
+        if (!isTraceRootValue(traceRootArg))
+            throw new TypeError('SpanBuffer construction requires a traceRoot');
+        const traceRoot = traceRootArg;
+        const vocabularyGeneration = ctorArgs[6];
+        // Thread-local span counter (per-process/worker, see threadId.ts docs)
+        globalThis.globalSpanCounter = (globalThis.globalSpanCounter ?? 0) + 1;
+        const spanId = globalThis.globalSpanCounter;
+        const threadId = isChained ? requireParent(parent).thread_id : getThreadId();
+        // Calculate exact physical system storage (same math as the preamble variants).
+        let systemSize;
+        let rowHeaderOffset = 0;
+        let messageIdOffset = 0;
+        let logHeaderOffset = 0;
+        if (messagePhysicalLayout === 'packed') {
+            rowHeaderOffset = requestedCapacity * 8;
+            systemSize = (requestedCapacity * 12 + 7) & ~7;
+        }
+        else if (messageLayoutFamily === 'dynamic-only') {
+            systemSize = (requestedCapacity * 9 + 7) & ~7;
+        }
+        else if (messagePhysicalLayout === 'current') {
+            messageIdOffset = (requestedCapacity * 9 + 1) & ~1;
+            systemSize = (messageIdOffset + requestedCapacity * 2 + 7) & ~7;
+        }
+        else {
+            logHeaderOffset = (requestedCapacity * 9 + 3) & ~3;
+            systemSize = (logHeaderOffset + requestedCapacity * 4 + 7) & ~7;
+        }
+        // CHAINED: shares parent._identity; CHILD: identity without traceId; ROOT: identity with traceId bytes.
+        let systemBuffer;
+        let identityView;
+        if (isChained) {
+            systemBuffer = new ArrayBuffer(systemSize);
+            identityView = requireParent(parent)._identity;
+        }
+        else if (parent) {
+            const identitySize = 12;
+            systemBuffer = new ArrayBuffer(systemSize + identitySize);
+            identityView = new Uint8Array(systemBuffer, systemSize, identitySize);
+            copyThreadIdTo(identityView, 0);
+            identityView[8] = spanId;
+            identityView[9] = spanId >>> 8;
+            identityView[10] = spanId >>> 16;
+            identityView[11] = spanId >>> 24;
+        }
+        else {
+            const traceIdBytes = traceRoot._traceIdBytes;
+            const identitySize = 13 + traceIdBytes.length;
+            systemBuffer = new ArrayBuffer(systemSize + identitySize);
+            identityView = new Uint8Array(systemBuffer, systemSize, identitySize);
+            copyThreadIdTo(identityView, 0);
+            identityView[8] = spanId;
+            identityView[9] = spanId >>> 8;
+            identityView[10] = spanId >>> 16;
+            identityView[11] = spanId >>> 24;
+            identityView[12] = traceIdBytes.length;
+            identityView.set(traceIdBytes, 13);
+        }
+        // Assign properties in the optimal V8 in-object slot order (same as the preamble).
+        self._writeIndex = 0;
+        self._capacity = requestedCapacity;
+        self._overflow = undefined;
+        self.timestamp = new BigInt64Array(systemBuffer, 0, requestedCapacity);
+        if (messagePhysicalLayout === 'packed') {
+            self._rowHeaders = new Uint32Array(systemBuffer, rowHeaderOffset, requestedCapacity);
+        }
+        else {
+            self.entry_type = new Uint8Array(systemBuffer, requestedCapacity * 8, requestedCapacity);
+            if (messageLayoutFamily !== 'dynamic-only') {
+                if (messagePhysicalLayout === 'current') {
+                    self._messageIds = new Uint16Array(systemBuffer, messageIdOffset, requestedCapacity);
+                }
+                else {
+                    self._logHeaders = new Uint32Array(systemBuffer, logHeaderOffset, requestedCapacity);
+                }
+            }
+        }
+        self._vocabularyGeneration = vocabularyGeneration;
+        if (messageLayoutFamily === 'static-only') {
+            self._spanName = undefined;
+            self._terminalMessage = undefined;
+        }
+        else if (messageLayoutFamily === 'dynamic-only') {
+            self._spanName = undefined;
+        }
+        self._nodeIndex = 4294967295;
+        self._topologyGeneration = 0;
+        self._parent = isChained ? requireParent(parent)._parent : parent;
+        self._traceRoot = traceRoot;
+        self._scopeValues = parent ? parent._scopeValues : EMPTY_SCOPE;
+        self._threadId = threadId;
+        self._identity = identityView;
+        self._system = systemBuffer;
+        self._callsiteMetadata = callsiteMetadata;
+        self._opMetadata = opMetadata;
+        self._statsSealed = false;
+        self._statsReservedRows = isChained ? 0 : 2;
+        if (messageLayoutFamily !== 'static-only') {
+            self.message_values = new Array(requestedCapacity);
+        }
+    };
+}
+/**
+ * No-eval counterpart of the extension `methods` string: same members, same
+ * kinds (getter vs method), installed after the generated per-column members
+ * so same-named members override exactly like the compiled class body.
+ */
+function createSpanBufferClosureMethods(messageLayoutFamily) {
+    return (prototype) => {
+        const defineMethod = (name, value) => {
+            Object.defineProperty(prototype, name, { value, writable: true, configurable: true, enumerable: false });
+        };
+        const defineGetter = (name, get) => {
+            Object.defineProperty(prototype, name, { get, configurable: true, enumerable: false });
+        };
+        defineGetter('span_id', function () {
+            const b = this._identity;
+            return b ? (b[8] | (b[9] << 8) | (b[10] << 16) | (b[11] << 24)) >>> 0 : 0;
+        });
+        defineGetter('thread_id', function () {
+            return this._threadId;
+        });
+        defineGetter('trace_id', function () {
+            return this._traceRoot.trace_id;
+        });
+        defineGetter('_spanStartTime', function () {
+            return this.timestamp[0];
+        });
+        defineGetter('_lastLoggedTime', function () {
+            const chain = [];
+            let current = this;
+            while (current) {
+                chain.push(current);
+                current = current._overflow;
+            }
+            for (let i = chain.length - 1; i >= 0; i--) {
+                const buffer = chain[i];
+                for (let row = buffer._writeIndex - 1; row >= 0; row--) {
+                    const ts = buffer.timestamp[row];
+                    if (ts !== 0n) {
+                        return ts;
+                    }
+                }
+            }
+            return null;
+        });
+        defineGetter('_hasParent', function () {
+            return this._parent !== undefined;
+        });
+        defineGetter('parent_span_id', function () {
+            return this._parent?.span_id ?? 0;
+        });
+        defineGetter('parent_thread_id', function () {
+            return this._parent?.thread_id ?? 0n;
+        });
+        defineMethod('isParentOf', function (other) {
+            return this === other._parent;
+        });
+        defineMethod('isChildOf', function (other) {
+            return this._parent === other;
+        });
+        defineMethod('copyThreadIdTo', function (dest, offset) {
+            const source = this._identity;
+            if (source) {
+                dest[offset] = source[0];
+                dest[offset + 1] = source[1];
+                dest[offset + 2] = source[2];
+                dest[offset + 3] = source[3];
+                dest[offset + 4] = source[4];
+                dest[offset + 5] = source[5];
+                dest[offset + 6] = source[6];
+                dest[offset + 7] = source[7];
+            }
+            else {
+                dest.fill(0, offset, offset + 8);
+            }
+        });
+        defineMethod('copyParentThreadIdTo', function (dest, offset) {
+            if (this._parent)
+                this._parent.copyThreadIdTo(dest, offset);
+            else
+                dest.fill(0, offset, offset + 8);
+        });
+        defineGetter('_logSchema', function () {
+            return spanBufferStatics(this).schema;
+        });
+        defineGetter('_messageLayoutFamily', function () {
+            return spanBufferStatics(this).messageLayoutFamily;
+        });
+        defineGetter('_messagePhysicalLayout', function () {
+            return spanBufferStatics(this).messagePhysicalLayout;
+        });
+        defineGetter('_columns', function () {
+            return spanBufferStatics(this).schema._columns;
+        });
+        defineGetter('_stats', function () {
+            return spanBufferStatics(this).stats;
+        });
+        defineMethod('_sealStats', function () {
+            sealStatsFor(this);
+        });
+        defineMethod('_sealStatsChain', function () {
+            let current = this;
+            while (current) {
+                sealStatsFor(current);
+                current = current._overflow;
+            }
+        });
+        defineMethod('getOrCreateOverflow', function () {
+            if (this._overflow)
+                return this._overflow;
+            sealStatsFor(this);
+            const tracer = this._traceRoot.tracer;
+            tracer.onStatsWillResetFor(this);
+            checkCapacityTuning(spanBufferStatics(this).stats);
+            if (!isTypedSpanBuffer(this))
+                throw new TypeError('SpanBuffer instance is not initialized');
+            return tracer.bufferStrategy.createOverflowBuffer(this);
+        });
+        if (messageLayoutFamily === 'static-only') {
+            defineMethod('message', function (pos, val) {
+                if (pos === 0)
+                    this._spanName = val;
+                else if (pos === 1)
+                    this._terminalMessage = val;
+                else
+                    throw new RangeError('Static-only buffers only accept raw system messages at rows 0 and 1');
+                return this;
+            });
+        }
+        else {
+            defineMethod('message', function (pos, val) {
+                const lane = this.message_values;
+                if (!Array.isArray(lane))
+                    throw new TypeError('message_values lane is not allocated');
+                lane[pos] = val;
+                return this;
+            });
+        }
+    };
+}
 /**
  * Get or create a SpanBuffer class for the given schema.
  *
@@ -134,9 +511,13 @@ const spanBufferClassCache = new WeakMap();
  * @returns SpanBufferConstructor with static schema and stats properties
  */
 //#region smoo/lmao!n/spanbuffer-layout.constructor
-export function getSpanBufferClass(schema) {
-    const cached = spanBufferClassCache.get(schema);
-    if (isSpanBufferConstructorForSchema(cached, schema)) {
+export function getSpanBufferClass(schema, messageLayoutFamily = 'mixed', messagePhysicalLayout = 'current', eagerColumns = EMPTY_EAGER_COLUMNS) {
+    const cacheKey = `${activeMaterializerMode()}:${messageLayoutFamily}:${messagePhysicalLayout}:${eagerColumns.key}`;
+    let familyClasses = spanBufferClassCache.get(schema);
+    const cached = familyClasses?.get(cacheKey);
+    if (isSpanBufferConstructorForSchema(cached, schema) &&
+        cached.messageLayoutFamily === messageLayoutFamily &&
+        cached.messagePhysicalLayout === messagePhysicalLayout) {
         return cached;
     }
     // ==========================================================================
@@ -159,21 +540,27 @@ export function getSpanBufferClass(schema) {
     // 2. _capacity - compared on EVERY write (overflow check)
     // 3. _overflow - checked when overflow occurs
     // 4. timestamp/entry_type - TypedArray refs accessed on EVERY write
-    // 5. _children/_parent - modified/accessed during span creation
+    // 5. _nodeIndex/_parent - modified/accessed during span creation
     // 6. _traceRoot - accessed for timestamp anchors on EVERY write
     // 7. _identity/_logBinding - accessed during span operations
     // 8-N. Cold properties - only accessed during Arrow conversion
     // ==========================================================================
     // Define extension for arrow-builder's class generator
     const extension = {
-        constructorParams: 'stats, parent, isChained, callsiteMetadata, opMetadata, traceRoot',
+        preallocatedColumns: eagerColumns.names,
+        constructorParams: 'stats, parent, isChained, callsiteMetadata, opMetadata, traceRoot, vocabularyGeneration',
         dependencies: {
-            writeThreadIdToUint64Array,
-            textDecoder: traceIdDecoder,
-            textEncoder,
+            copyThreadIdTo,
+            getThreadId,
             EMPTY_SCOPE,
             checkCapacityTuning,
         },
+        // No-eval counterparts consumed by arrow-builder's closure-composed
+        // materializer on runtimes without string codegen (workerd). They MUST
+        // mirror constructorPreamble/methods below exactly — see the factories
+        // above and spanbuffer-materializer-parity.test.ts.
+        closureInit: createSpanBufferClosureInit(messageLayoutFamily, messagePhysicalLayout),
+        closureMethods: createSpanBufferClosureMethods(messageLayoutFamily),
         // ==========================================================================
         // GENERATED CONSTRUCTOR PREAMBLE
         // ==========================================================================
@@ -199,12 +586,11 @@ export function getSpanBufferClass(schema) {
         // V8 IN-OBJECT PROPERTY OPTIMIZATION:
         // Property assignment order determines which properties get fast in-object slots.
         // First ~10-12 properties are stored directly on the object (fastest access).
-        // Slots 1-3: HOTTEST (every log entry) - _writeIndex, _capacity, _overflow
-        // Slots 4-5: HOT (TypedArray refs) - timestamp, entry_type
-        // Slots 6-7: WARM (tree structure) - _children, _parent
-        // Slots 8-10: WARM (context) - _traceRoot, _scopeValues, _identity
-        // Slots 11: WARM (system) - _system
-        // Slots 12+: COLD (Arrow conversion only) - _callsiteMetadata, _opMetadata
+        // Slots 0-2: HOTTEST (every log entry) - _writeIndex, _capacity, _overflow
+        // Slots 3-6: HOT (storage refs) - timestamp, entry_type/header, message identity, vocabulary
+        // Slots 7-10: WARM (tree structure) - _nodeIndex, _topologyGeneration, _parent, _traceRoot
+        // Slots 11-14: WARM (context/identity) - _scopeValues, _threadId, _identity, _system
+        // Slots 15+: COLD (Arrow/stats/raw message) - metadata, stats, message_values
         // ==========================================================================
         constructorPreamble: 
         // Thread-local span counter (per-process/worker, see threadId.ts docs)
@@ -212,84 +598,133 @@ export function getSpanBufferClass(schema) {
          globalThis.globalSpanCounter = 0;
        }
        const spanId = ++globalThis.globalSpanCounter;
+       const threadId = isChained ? parent.thread_id : getThreadId();
 ` +
-            // Calculate system buffer size: timestamps (8 bytes * cap) + entry_type (1 byte * cap)
-            // Align to 8 bytes so identity's BigUint64Array offset is aligned
-            `const rawSystemSize = requestedCapacity * 9;
-       const systemSize = (rawSystemSize + 7) & ~7;
+            // Calculate exact physical system storage once for the generated class.
+            (messagePhysicalLayout === 'packed'
+                ? `const rowHeaderOffset = requestedCapacity * 8;
+       const systemSize = (requestedCapacity * 12 + 7) & ~7;
        let systemBuffer;
        let identityView;
-` +
+`
+                : messageLayoutFamily === 'dynamic-only'
+                    ? `const systemSize = (requestedCapacity * 9 + 7) & ~7;
+       let systemBuffer;
+       let identityView;
+`
+                    : messagePhysicalLayout === 'current'
+                        ? `const messageIdOffset = (requestedCapacity * 9 + 1) & ~1;
+       const systemSize = (messageIdOffset + requestedCapacity * 2 + 7) & ~7;
+       let systemBuffer;
+       let identityView;
+`
+                        : `const logHeaderOffset = (requestedCapacity * 9 + 3) & ~3;
+       const systemSize = (logHeaderOffset + requestedCapacity * 4 + 7) & ~7;
+       let systemBuffer;
+       let identityView;
+`) +
             // CHAINED BUFFER: overflow storage for same logical span - shares parent identity
             `if (isChained) {
           systemBuffer = new ArrayBuffer(systemSize);
           identityView = parent._identity;
         }` +
             // CHILD BUFFER: new span in existing trace - gets identity without traceId
-            // (traceId accessed via parent chain walk in trace_id getter)
             ` else if (parent) {
          const identitySize = 12;
          systemBuffer = new ArrayBuffer(systemSize + identitySize);
          identityView = new Uint8Array(systemBuffer, systemSize, identitySize);
-         const threadIdArray = new BigUint64Array(systemBuffer, systemSize, 1);
-         writeThreadIdToUint64Array(threadIdArray, 0);
-         new DataView(systemBuffer, systemSize).setUint32(8, spanId, true);
+         copyThreadIdTo(identityView, 0);
+         identityView[8] = spanId;
+         identityView[9] = spanId >>> 8;
+         identityView[10] = spanId >>> 16;
+         identityView[11] = spanId >>> 24;
        }` +
-            // ROOT BUFFER: new trace - gets identity with traceId from TraceRoot
+            // ROOT BUFFER: new trace - copies the trace-owned canonical bytes once into its public identity.
             ` else {
-          const traceIdUtf8 = textEncoder.encode(traceRoot.trace_id);
-          const identitySize = 13 + traceIdUtf8.length;
+          const traceIdBytes = traceRoot._traceIdBytes;
+          const identitySize = 13 + traceIdBytes.length;
           systemBuffer = new ArrayBuffer(systemSize + identitySize);
           identityView = new Uint8Array(systemBuffer, systemSize, identitySize);
-          const view = new DataView(systemBuffer, systemSize);
-         const threadIdArray = new BigUint64Array(systemBuffer, systemSize, 1);
-         writeThreadIdToUint64Array(threadIdArray, 0);
-          view.setUint32(8, spanId, true);
-          identityView[12] = traceIdUtf8.length;
-          identityView.set(traceIdUtf8, 13);
+          copyThreadIdTo(identityView, 0);
+          identityView[8] = spanId;
+          identityView[9] = spanId >>> 8;
+          identityView[10] = spanId >>> 16;
+          identityView[11] = spanId >>> 24;
+          identityView[12] = traceIdBytes.length;
+          identityView.set(traceIdBytes, 13);
         }
 ` +
-            // Create TypedArray views for timestamps and entry_type
-            `const timestampView = new BigInt64Array(systemBuffer, 0, requestedCapacity);
+            // Create exact physical views. Packed classes never create split entry/header views.
+            (messagePhysicalLayout === 'packed'
+                ? `const timestampView = new BigInt64Array(systemBuffer, 0, requestedCapacity);
+       const rowHeaderView = new Uint32Array(systemBuffer, rowHeaderOffset, requestedCapacity);
+`
+                : `const timestampView = new BigInt64Array(systemBuffer, 0, requestedCapacity);
        const entryTypeView = new Uint8Array(systemBuffer, requestedCapacity * 8, requestedCapacity);
-       timestampView.fill(0n);
-       entryTypeView.fill(0);
 ` +
-            // Assign properties in optimal order for V8 in-object slots (see comment above)
+                    (messageLayoutFamily === 'dynamic-only'
+                        ? ''
+                        : messagePhysicalLayout === 'current'
+                            ? `       const messageIdView = new Uint16Array(systemBuffer, messageIdOffset, requestedCapacity);
+`
+                            : `       const logHeaderView = new Uint32Array(systemBuffer, logHeaderOffset, requestedCapacity);
+`)) +
+            // Assign properties in optimal order for V8 in-object slots.
             `this._writeIndex = 0;
        this._capacity = requestedCapacity;
        this._overflow = undefined;
        this.timestamp = timestampView;
-       this.entry_type = entryTypeView;
-       this._children = [];
+` +
+            (messagePhysicalLayout === 'packed'
+                ? `       this._rowHeaders = rowHeaderView;
+`
+                : `       this.entry_type = entryTypeView;
+` +
+                    (messageLayoutFamily === 'dynamic-only'
+                        ? ''
+                        : messagePhysicalLayout === 'current'
+                            ? `       this._messageIds = messageIdView;
+`
+                            : `       this._logHeaders = logHeaderView;
+`)) +
+            `       this._vocabularyGeneration = vocabularyGeneration;
+` +
+            (messageLayoutFamily === 'static-only'
+                ? `       this._spanName = undefined;
+       this._terminalMessage = undefined;
+`
+                : messageLayoutFamily === 'dynamic-only'
+                    ? `       this._spanName = undefined;
+`
+                    : '') +
+            `       this._nodeIndex = 4294967295;
+       this._topologyGeneration = 0;
        this._parent = isChained ? parent._parent : parent;
        this._traceRoot = traceRoot;
        this._scopeValues = parent ? parent._scopeValues : EMPTY_SCOPE;
+       this._threadId = threadId;
         this._identity = identityView;
         this._system = systemBuffer;
         this._callsiteMetadata = callsiteMetadata;
         this._opMetadata = opMetadata;
-    `,
-        // Generated methods for SpanBuffer - no comments in output
-        // span_id: extract from identity bytes [8:12]
-        // thread_id: extract from identity bytes [0:8]
-        // trace_id: walk up parent chain to root, decode trace_id from identity
-        // parent_span_id/parent_thread_id: delegate to parent
-        // isParentOf/isChildOf: pointer comparison
-        // copyThreadIdTo/copyParentThreadIdTo: copy thread_id bytes to destination
+        this._statsSealed = false;
+        this._statsReservedRows = isChained ? 0 : 2;
+` +
+            (messageLayoutFamily === 'static-only'
+                ? ''
+                : `       this.message_values = new Array(requestedCapacity);
+`) +
+            '    ',
+        // Generated identity methods use canonical primitives/direct offsets without temporary views.
         methods: `get span_id() {
-      return this._identity ? new DataView(this._identity.buffer, this._identity.byteOffset + 8).getUint32(0, true) : 0;
+      const b = this._identity;
+      return b ? (b[8] | (b[9] << 8) | (b[10] << 16) | (b[11] << 24)) >>> 0 : 0;
     }
     get thread_id() {
-      return this._identity ? new DataView(this._identity.buffer, this._identity.byteOffset).getBigUint64(0, true) : 0n;
+      return this._threadId;
     }
     get trace_id() {
-      let current = this;
-      while (current._parent) { current = current._parent; }
-      if (!current._identity) { return undefined; }
-      const len = current._identity[12];
-      const traceIdBytes = current._identity.subarray(13, 13 + len);
-      return textDecoder.decode(traceIdBytes);
+      return this._traceRoot.trace_id;
     }
     get _spanStartTime() {
       return this.timestamp[0];
@@ -318,39 +753,78 @@ export function getSpanBufferClass(schema) {
     isParentOf(other) { return this === other._parent; }
     isChildOf(other) { return this._parent === other; }
     copyThreadIdTo(dest, offset) {
-      if (this._identity) {
-        const view = new DataView(this._identity.buffer, this._identity.byteOffset);
-        const threadId = view.getBigUint64(0, true);
-        new DataView(dest.buffer, dest.byteOffset + offset).setBigUint64(0, threadId, true);
+      const source = this._identity;
+      if (source) {
+        dest[offset] = source[0];
+        dest[offset + 1] = source[1];
+        dest[offset + 2] = source[2];
+        dest[offset + 3] = source[3];
+        dest[offset + 4] = source[4];
+        dest[offset + 5] = source[5];
+        dest[offset + 6] = source[6];
+        dest[offset + 7] = source[7];
       } else {
-        new DataView(dest.buffer, dest.byteOffset + offset).setBigUint64(0, 0n, true);
+        dest.fill(0, offset, offset + 8);
       }
     }
     copyParentThreadIdTo(dest, offset) {
-      this._parent?.copyThreadIdTo(dest, offset) ?? new DataView(dest.buffer, dest.byteOffset + offset).setBigUint64(0, 0n, true);
+      if (this._parent) this._parent.copyThreadIdTo(dest, offset);
+      else dest.fill(0, offset, offset + 8);
     }
     get _logSchema() { return this.constructor.schema; }
+    get _messageLayoutFamily() { return this.constructor.messageLayoutFamily; }
+    get _messagePhysicalLayout() { return this.constructor.messagePhysicalLayout; }
     get _columns() { return this.constructor.schema._columns; }
     get _stats() { return this.constructor.stats; }
+    _sealStats() {
+      if (this._statsSealed) return;
+      const completedRows = this._writeIndex - this._statsReservedRows;
+      if (completedRows > 0) this.constructor.stats.totalWrites += completedRows;
+      this._statsSealed = true;
+    }
+    _sealStatsChain() {
+      let current = this;
+      while (current) {
+        current._sealStats();
+        current = current._overflow;
+      }
+    }
     getOrCreateOverflow() {
       if (this._overflow) return this._overflow;
+      this._sealStats();
       const tracer = this._traceRoot.tracer;
       tracer.onStatsWillResetFor(this);
       checkCapacityTuning(this.constructor.stats);
       return tracer.bufferStrategy.createOverflowBuffer(this);
     }
+    ${messageLayoutFamily === 'static-only'
+            ? `message(pos, val) {
+      if (pos === 0) this._spanName = val;
+      else if (pos === 1) this._terminalMessage = val;
+      else throw new RangeError('Static-only buffers only accept raw system messages at rows 0 and 1');
+      return this;
+    }`
+            : `message(pos, val) {
+      this.message_values[pos] = val;
+      return this;
+    }`}
     `,
     };
+    // Storage schema identity partitions source schema/family/physical classes; the extension cache key
+    // partitions eager-column selections without adding another dedicated cache object.
+    const storageSchema = getStorageSchema(schema, messageLayoutFamily, messagePhysicalLayout);
     // Generate class with arrow-builder
-    const generatedClass = getColumnBufferClass(schema, extension);
+    const generatedClass = getColumnBufferClass(storageSchema, extension, storageSchema);
     if (!isGeneratedSpanBufferClass(generatedClass)) {
         throw new TypeError('Generated column buffer is missing SpanBuffer methods');
     }
-    // Add static properties to the generated class
-    // These are shared across all instances from the same defineOpContext
-    const SpanBufferClass = createSpanBufferConstructor(schema, generatedClass);
+    // Initialize immutable static discriminators before publishing the constructor in the LMAO cache.
+    // The mutable stats object remains shared by every instance of this exact class dimension.
+    const SpanBufferClass = createSpanBufferConstructor(schema, messageLayoutFamily, messagePhysicalLayout, generatedClass, eagerColumns);
     // Cache for future use
-    spanBufferClassCache.set(schema, SpanBufferClass);
+    familyClasses ??= new Map();
+    familyClasses.set(cacheKey, SpanBufferClass);
+    spanBufferClassCache.set(schema, familyClasses);
     return SpanBufferClass;
 }
 //#endregion smoo/lmao!n/spanbuffer-layout.constructor
@@ -369,22 +843,35 @@ export function getSpanBufferClass(schema) {
  *
  * @returns SpanBuffer with typed setters for schema fields
  */
-const MIN_CAPACITY = 8;
+export const MIN_ADAPTIVE_BUFFER_CAPACITY = 8;
+export function resolveSpanBufferCapacity(explicitCapacity, adaptiveCapacity) {
+    if (explicitCapacity === undefined)
+        return Math.max(MIN_ADAPTIVE_BUFFER_CAPACITY, adaptiveCapacity);
+    if (!Number.isSafeInteger(explicitCapacity) || explicitCapacity < 2) {
+        throw new RangeError('Explicit span buffer capacity must be a safe integer of at least 2');
+    }
+    return explicitCapacity;
+}
 //#region smoo/lmao!n/spanbuffer-layout.create-root
-export function createSpanBuffer(schema, traceRoot, opMetadata, capacity) {
-    const SpanBufferClass = getSpanBufferClass(schema);
+export function createSpanBuffer(schema, traceRoot, opMetadata, capacity, plannedClass) {
+    const metadataPlan = opMetadata._physicalLayoutPlan;
+    const metadataSpanBufferClass = metadataPlan?.SpanBufferClass;
+    if (metadataSpanBufferClass !== undefined && !isSpanBufferConstructorForSchema(metadataSpanBufferClass, schema)) {
+        throw new TypeError('Planned SpanBuffer class does not match schema');
+    }
+    const plannedSpanBufferClass = plannedClass ?? metadataSpanBufferClass;
+    const SpanBufferClass = plannedSpanBufferClass ?? getSpanBufferClass(schema);
     const stats = SpanBufferClass.stats;
-    // Use provided capacity or default from class stats, enforce minimum
-    const actualCapacity = Math.max(MIN_CAPACITY, capacity ?? stats.capacity);
+    // Compiler-planned capacities are validated when the runtime hint is decoded. Keep direct external calls strict.
+    const actualCapacity = plannedSpanBufferClass === undefined
+        ? resolveSpanBufferCapacity(capacity, stats.capacity)
+        : (capacity ?? Math.max(MIN_ADAPTIVE_BUFFER_CAPACITY, stats.capacity));
     // Track non-chained buffer creation for capacity tuning
     stats.spansCreated++;
-    // Create root buffer (no parent)
-    // Root spans use same metadata for both callsite and op (no distinction at root)
-    return new SpanBufferClass(actualCapacity, stats, undefined, // no parent
-    false, // not chained
-    opMetadata, // callsiteMetadata for row 0
-    opMetadata, // opMetadata for rows 1+ (same as callsite for root)
-    traceRoot);
+    // Create root buffer (no parent), then register its stable logical node.
+    const buffer = new SpanBufferClass(actualCapacity, stats, undefined, false, opMetadata, opMetadata, traceRoot, metadataPlan?.vocabularyGeneration ?? getVocabularyGeneration());
+    traceRoot._topology.registerRoot(buffer);
+    return buffer;
 }
 //#endregion smoo/lmao!n/spanbuffer-layout.create-root
 /**
@@ -407,9 +894,11 @@ export function createOverflowBuffer(buffer) {
     // Pass buffer as parent - used for identity sharing; _parent set to buffer._parent in constructor
     const nextBuffer = new SpanBufferClass(capacity, stats, buffer, // Used for identity sharing, _parent set to buffer._parent in constructor
     true, // isChained
-    buffer._callsiteMetadata, buffer._opMetadata, buffer._traceRoot);
+    buffer._callsiteMetadata, buffer._opMetadata, buffer._traceRoot, // traceRoot from parent
+    buffer._vocabularyGeneration);
     // Link current buffer to next
     buffer._overflow = nextBuffer;
+    buffer._traceRoot._topology.adoptOverflow(buffer, nextBuffer);
     return nextBuffer;
 }
 //#endregion smoo/lmao!n/spanbuffer-layout.create-overflow
@@ -432,7 +921,8 @@ export function createOverflowBuffer(buffer) {
 //#region smoo/lmao!n/spanbuffer-layout.create-child
 export function createChildSpanBuffer(parentBuffer, SpanBufferClass, callsiteMetadata, opMetadata, capacity) {
     const stats = SpanBufferClass.stats;
-    const actualCapacity = capacity ?? stats.capacity;
+    // Child capacities arrive through a validated callsite plan; preserve exact values including 2..7.
+    const actualCapacity = capacity ?? Math.max(MIN_ADAPTIVE_BUFFER_CAPACITY, stats.capacity);
     // Track non-chained buffer creation for capacity tuning
     stats.spansCreated++;
     // Create child buffer with parent reference
@@ -440,7 +930,9 @@ export function createChildSpanBuffer(parentBuffer, SpanBufferClass, callsiteMet
     false, // not chained
     callsiteMetadata, // callsiteMetadata - CALLER's op metadata (for row 0)
     opMetadata, // opMetadata - EXECUTING op metadata (for rows 1+)
-    parentBuffer._traceRoot);
+    parentBuffer._traceRoot, // traceRoot from parent
+    opMetadata._physicalLayoutPlan?.vocabularyGeneration ?? getVocabularyGeneration());
+    parentBuffer._traceRoot._topology.registerChild(parentBuffer, childBuffer);
     return childBuffer;
 }
 //#endregion smoo/lmao!n/spanbuffer-layout.create-child