@smoothbricks/lmao 0.2.2 → 0.2.3

package/src/lib/spanBuffer.ts

@@ -25,15 +25,23 @@
  * @module spanBuffer
  */
 
-import { type ColumnBufferExtension, DEFAULT_BUFFER_CAPACITY, getColumnBufferClass } from '@smoothbricks/arrow-builder';
+import {
+  activeMaterializerMode,
+  type ColumnBufferExtension,
+  DEFAULT_BUFFER_CAPACITY,
+  getColumnBufferClass,
+  type SchemaWithMetadata,
+} from '@smoothbricks/arrow-builder';
 import { checkCapacityTuning } from './capacityTuning.js';
 import type { OpMetadata } from './opContext/opTypes.js';
-import type { LogSchema } from './schema/LogSchema.js';
-import { textEncoder } from './spanBufferHelpers.js';
+import type { EagerColumnDescriptor } from './physicalLayoutPlan.js';
+import type { MessageLayoutFamily, MessagePhysicalLayout } from './runtimeHint.js';
+import { LogSchema } from './schema/LogSchema.js';
 import type { SpanBufferStats } from './spanBufferStats.js';
-import { writeThreadIdToUint64Array } from './threadId.js';
+import { copyThreadIdTo, getThreadId } from './threadId.js';
 import type { ITraceRoot } from './traceRoot.js';
 import type { AnySpanBuffer, SpanBuffer } from './types.js';
+import { getVocabularyGeneration, type VocabularyGeneration } from './vocabularyRegistry.js';
 
 // Re-export ITraceRoot for external consumers (and to satisfy linter - it's used in generated code)
 export type { ITraceRoot };
@@ -44,8 +52,6 @@ export type { ITraceRoot };
  */
 export const EMPTY_SCOPE: Readonly<Record<string, unknown>> = 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
@@ -132,11 +138,15 @@ export interface SpanBufferConstructor<T extends LogSchema = LogSchema> {
     callsiteMetadata: OpMetadata | undefined,
     opMetadata: OpMetadata | undefined,
     traceRoot: ITraceRoot,
+    vocabularyGeneration: VocabularyGeneration,
   ): SpanBuffer<T>;
 
   // Static properties added after class generation
   readonly schema: T;
   readonly stats: SpanBufferStats;
+  readonly messageLayoutFamily: MessageLayoutFamily;
+  readonly messagePhysicalLayout: MessagePhysicalLayout;
+  readonly eagerColumns: EagerColumnDescriptor;
 }
 //#endregion smoo/lmao!n/spanbuffer-layout.class-signature
 
@@ -148,6 +158,7 @@ type GeneratedSpanBufferClass<T extends LogSchema> = new (
   callsiteMetadata: OpMetadata | undefined,
   opMetadata: OpMetadata | undefined,
   traceRoot: ITraceRoot,
+  vocabularyGeneration: VocabularyGeneration,
 ) => SpanBuffer<T>;
 
 function isGeneratedSpanBufferClass<T extends LogSchema>(
@@ -160,6 +171,8 @@ function isGeneratedSpanBufferClass<T extends LogSchema>(
 
   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'
   );
@@ -186,23 +199,438 @@ function getSpanBufferConstructorForBuffer<T extends LogSchema>(buffer: SpanBuff
 
 function createSpanBufferConstructor<T extends LogSchema>(
   schema: T,
+  messageLayoutFamily: MessageLayoutFamily,
+  messagePhysicalLayout: MessagePhysicalLayout,
   generatedClass: GeneratedSpanBufferClass<T>,
+  eagerColumns: EagerColumnDescriptor,
 ): SpanBufferConstructor<T> {
-  return Object.assign(generatedClass, {
-    schema,
+  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,
-    } satisfies SpanBufferStats,
+      value: {
+        capacity: DEFAULT_BUFFER_CAPACITY,
+        totalWrites: 0,
+        spansCreated: 0,
+      } satisfies SpanBufferStats,
+      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<LogSchema, SpanBufferConstructor>();
+const spanBufferClassCache = new WeakMap<LogSchema, Map<string, object>>();
+const messageStorageSchemas = new WeakMap<LogSchema, Map<string, LogSchema>>();
+const EMPTY_EAGER_COLUMNS: EagerColumnDescriptor = Object.freeze({
+  names: Object.freeze([]),
+  words: Object.freeze([]),
+  key: '',
+});
+
+function resolveCompiledEagerColumns(schema: LogSchema, requestedNames: readonly string[]): EagerColumnDescriptor {
+  if (requestedNames.length === 0) return EMPTY_EAGER_COLUMNS;
+  const requested = new Set(requestedNames);
+  const names: string[] = [];
+  const words = new Array<number>(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: LogSchema,
+  messageLayoutFamily: MessageLayoutFamily,
+  messagePhysicalLayout: MessagePhysicalLayout,
+): LogSchema {
+  let byLayout = messageStorageSchemas.get(schema);
+  const key = `${messageLayoutFamily}:${messagePhysicalLayout}`;
+  let storageSchema = byLayout?.get(key);
+  if (storageSchema === undefined) {
+    const fields: Record<string, SchemaWithMetadata> = {};
+    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<T extends LogSchema>(
+  schema: T,
+  messageLayoutFamily: MessageLayoutFamily,
+  messagePhysicalLayout: MessagePhysicalLayout,
+  eagerColumnNames: readonly string[],
+  factory: () => new (...args: never[]) => unknown,
+): SpanBufferConstructor<T> {
+  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<T>(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;
+}
+
+// ============================================================================
+// No-eval (closure-composed) extension counterparts
+// ============================================================================
+// Production workerd forbids code generation from strings, so arrow-builder
+// materializes the buffer class from closures there (see arrow-builder's
+// closureMaterializers). The two factories below are the EXACT no-eval
+// re-expressions of the code-string constructorPreamble/methods passed in the
+// extension inside getSpanBufferClass — any change to one side MUST be
+// mirrored on the other (spanbuffer-materializer-parity.test.ts compares the
+// resulting buffers byte for byte).
+
+/** Prototype/instance view used by the closure-composed members. */
+type ClosureSelf = AnySpanBuffer & Record<string, unknown>;
+
+// Thread-local span counter contract shared with the generated constructorPreamble
+// (`globalThis.globalSpanCounter`), see threadId.ts docs.
+declare global {
+  var globalSpanCounter: number | undefined;
+}
+
+function isSpanBufferConstructorValue(value: unknown): value is SpanBufferConstructor {
+  return typeof value === 'function';
+}
+
+function spanBufferStatics(self: AnySpanBuffer): SpanBufferConstructor {
+  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: unknown): value is AnySpanBuffer {
+  return typeof value === 'object' && value !== null;
+}
+
+function isTraceRootValue(value: unknown): value is ITraceRoot {
+  return typeof value === 'object' && value !== null;
+}
+
+function requireParent(parent: AnySpanBuffer | undefined): AnySpanBuffer {
+  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: AnySpanBuffer): value is SpanBuffer<LogSchema> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Mirrors the generated `_sealStats` body (shared with getOrCreateOverflow). */
+function sealStatsFor(self: AnySpanBuffer): void {
+  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: MessageLayoutFamily,
+  messagePhysicalLayout: MessagePhysicalLayout,
+): NonNullable<ColumnBufferExtension['closureInit']> {
+  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: number;
+    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: ArrayBuffer;
+    let identityView: Uint8Array;
+    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: MessageLayoutFamily,
+): NonNullable<ColumnBufferExtension['closureMethods']> {
+  return (prototype) => {
+    const defineMethod = (name: string, value: unknown): void => {
+      Object.defineProperty(prototype, name, { value, writable: true, configurable: true, enumerable: false });
+    };
+    const defineGetter = (name: string, get: (this: ClosureSelf) => unknown): void => {
+      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: AnySpanBuffer[] = [];
+      let current: AnySpanBuffer | undefined = 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 (this: ClosureSelf, other: AnySpanBuffer) {
+      return this === other._parent;
+    });
+    defineMethod('isChildOf', function (this: ClosureSelf, other: AnySpanBuffer) {
+      return this._parent === other;
+    });
+    defineMethod('copyThreadIdTo', function (this: ClosureSelf, dest: Uint8Array, offset: number) {
+      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 (this: ClosureSelf, dest: Uint8Array, offset: number) {
+      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 (this: ClosureSelf) {
+      sealStatsFor(this);
+    });
+    defineMethod('_sealStatsChain', function (this: ClosureSelf) {
+      let current: AnySpanBuffer | undefined = this;
+      while (current) {
+        sealStatsFor(current);
+        current = current._overflow;
+      }
+    });
+    defineMethod('getOrCreateOverflow', function (this: ClosureSelf) {
+      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 (this: ClosureSelf, pos: number, val: string) {
+        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 (this: ClosureSelf, pos: number, val: string) {
+        const lane: unknown = 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.
@@ -217,9 +645,20 @@ const spanBufferClassCache = new WeakMap<LogSchema, SpanBufferConstructor>();
  * @returns SpanBufferConstructor with static schema and stats properties
  */
 //#region smoo/lmao!n/spanbuffer-layout.constructor
-export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferConstructor<T> {
-  const cached = spanBufferClassCache.get(schema);
-  if (isSpanBufferConstructorForSchema(cached, schema)) {
+export function getSpanBufferClass<T extends LogSchema>(
+  schema: T,
+  messageLayoutFamily: MessageLayoutFamily = 'mixed',
+  messagePhysicalLayout: MessagePhysicalLayout = 'current',
+  eagerColumns: EagerColumnDescriptor = EMPTY_EAGER_COLUMNS,
+): SpanBufferConstructor<T> {
+  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;
   }
 
@@ -243,7 +682,7 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
   // 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
@@ -251,14 +690,20 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
 
   // Define extension for arrow-builder's class generator
   const extension: ColumnBufferExtension = {
-    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
     // ==========================================================================
@@ -284,12 +729,11 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
     // 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)
@@ -297,84 +741,133 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
          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];
@@ -403,42 +896,90 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
     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<T>(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;
 }
@@ -460,7 +1001,15 @@ export function getSpanBufferClass<T extends LogSchema>(schema: T): SpanBufferCo
  *
  * @returns SpanBuffer with typed setters for schema fields
  */
-const MIN_CAPACITY = 8;
+export const MIN_ADAPTIVE_BUFFER_CAPACITY = 8;
+
+export function resolveSpanBufferCapacity(explicitCapacity: number | undefined, adaptiveCapacity: number): number {
+  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<T extends LogSchema>(
@@ -468,27 +1017,39 @@ export function createSpanBuffer<T extends LogSchema>(
   traceRoot: ITraceRoot,
   opMetadata: OpMetadata,
   capacity?: number,
+  plannedClass?: SpanBufferConstructor<T>,
 ): SpanBuffer<T> {
-  const SpanBufferClass = getSpanBufferClass(schema);
+  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(
+  // Create root buffer (no parent), then register its stable logical node.
+  const buffer = 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, // pre-built TraceRoot with trace_id, anchors, tracer
+    undefined,
+    false,
+    opMetadata,
+    opMetadata,
+    traceRoot,
+    metadataPlan?.vocabularyGeneration ?? getVocabularyGeneration(),
   );
+  traceRoot._topology.registerRoot(buffer);
+  return buffer;
 }
 //#endregion smoo/lmao!n/spanbuffer-layout.create-root
 
@@ -520,10 +1081,12 @@ export function createOverflowBuffer<T extends LogSchema>(buffer: SpanBuffer<T>)
     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;
 }
@@ -554,7 +1117,8 @@ export function createChildSpanBuffer<T extends LogSchema>(
   capacity?: number,
 ): SpanBuffer<T> {
   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++;
@@ -568,8 +1132,10 @@ export function createChildSpanBuffer<T extends LogSchema>(
     callsiteMetadata, // callsiteMetadata - CALLER's op metadata (for row 0)
     opMetadata, // opMetadata - EXECUTING op metadata (for rows 1+)
     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