@smoothbricks/lmao 0.2.2 → 0.3.0

package/src/lib/__tests__/eager-columns.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it } from 'bun:test';
+import fc from 'fast-check';
+import { convertSpanTreeToArrowTable } from '../convertToArrow.js';
+import { defineOpContext } from '../defineOpContext.js';
+import { JsBufferStrategy } from '../JsBufferStrategy.js';
+import { createRemapDescriptor } from '../library.js';
+import type { OpContext } from '../opContext/types.js';
+import { type EagerColumnDescriptor, getPhysicalLayoutPlan, resolveEagerColumns } from '../physicalLayoutPlan.js';
+import {
+  RUNTIME_HINT_ANALYZED_VALID,
+  RUNTIME_HINT_LOG,
+  RUNTIME_HINT_RESULT,
+  RUNTIME_HINT_TAG,
+  runtimeHintInitialCapacity,
+} from '../runtimeHint.js';
+import { S } from '../schema/builder.js';
+import { defineLogSchema } from '../schema/defineLogSchema.js';
+import { LogSchema } from '../schema/LogSchema.js';
+import { createChildSpanBuffer, createOverflowBuffer, createSpanBuffer, getSpanBufferClass } from '../spanBuffer.js';
+import { createSpanContextClass } from '../spanContext.js';
+import { TestTracer } from '../tracers/TestTracer.js';
+import type { AnySpanBuffer } from '../types.js';
+import { createTestOpMetadata, createTestTraceRoot, createTestTracerOptions } from './test-helpers.js';
+
+const HINT = RUNTIME_HINT_ANALYZED_VALID | RUNTIME_HINT_LOG | RUNTIME_HINT_RESULT | 8;
+
+function descriptorBytes(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;
+}
+
+function expectCompilerEagerStorage(buffer: AnySpanBuffer, name: string): void {
+  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);
+  expect(Object.hasOwn(buffer, `${name}_values`)).toBe(false);
+  expect(Object.hasOwn(buffer, `${name}_nulls`)).toBe(false);
+}
+
+function expectLazyStorage(buffer: AnySpanBuffer, name: string): void {
+  expect(Reflect.get(buffer, `_${name}_values`)).toBeUndefined();
+  expect(Reflect.get(buffer, `_${name}_nulls`)).toBeUndefined();
+  expect(buffer.getColumnIfAllocated(name)).toBeUndefined();
+  expect(buffer.getNullsIfAllocated(name)).toBeUndefined();
+}
+
+describe('compiler-proven eager user columns', () => {
+  it('encodes exact schema-order descriptor words and bytes beyond 32 fields', () => {
+    const schema = new LogSchema({
+      f00: S.number(),
+      f01: S.number(),
+      f02: S.number(),
+      f03: S.number(),
+      f04: S.number(),
+      f05: S.number(),
+      f06: S.number(),
+      f07: S.number(),
+      f08: S.number(),
+      f09: S.number(),
+      f10: S.number(),
+      f11: S.number(),
+      f12: S.number(),
+      f13: S.number(),
+      f14: S.number(),
+      f15: S.number(),
+      f16: S.number(),
+      f17: S.number(),
+      f18: S.number(),
+      f19: S.number(),
+      f20: S.number(),
+      f21: S.number(),
+      f22: S.number(),
+      f23: S.number(),
+      f24: S.number(),
+      f25: S.number(),
+      f26: S.number(),
+      f27: S.number(),
+      f28: S.number(),
+      f29: S.number(),
+      f30: S.number(),
+      f31: S.number(),
+      f32: S.number(),
+      f33: S.number(),
+      f34: S.number(),
+      f35: S.number(),
+      f36: S.number(),
+      f37: S.number(),
+      f38: S.number(),
+      f39: S.number(),
+    });
+
+    const descriptor = resolveEagerColumns(schema, ['f39', 'f00', 'f32', 'f00']);
+
+    expect(descriptor.names).toEqual(['f00', 'f32', 'f39']);
+    expect(descriptor.words).toEqual([0x00000001, 0x00000081]);
+    expect(descriptor.key).toBe('0000000100000081');
+    expect([...descriptorBytes(descriptor)]).toEqual([1, 0, 0, 0, 129, 0, 0, 0]);
+    expect(Object.isFrozen(descriptor)).toBe(true);
+    expect(Object.isFrozen(descriptor.names)).toBe(true);
+    expect(Object.isFrozen(descriptor.words)).toBe(true);
+    expect(() => resolveEagerColumns(schema, ['missing'])).toThrow('Unknown eager column: missing');
+
+    fc.assert(
+      fc.property(
+        fc.uniqueArray(fc.integer({ min: 0, max: 39 }), { maxLength: 40 }),
+        fc.boolean(),
+        (ordinals, reverse) => {
+          const requested = ordinals.map((ordinal) => `f${ordinal.toString().padStart(2, '0')}`);
+          if (reverse) requested.reverse();
+          const resolved = resolveEagerColumns(schema, requested);
+          const expectedWords = [0, 0];
+          for (const ordinal of ordinals) {
+            expectedWords[ordinal >>> 5] = (expectedWords[ordinal >>> 5] | (1 << (ordinal & 31))) >>> 0;
+          }
+          while (expectedWords.length > 0 && expectedWords[expectedWords.length - 1] === 0) expectedWords.pop();
+          expect(resolved.words).toEqual(expectedWords);
+          expect(resolved.names).toEqual(schema._columnNames.filter((name) => requested.includes(name)));
+          expect(descriptorBytes(resolved).byteLength).toBe(resolved.words.length * 4);
+        },
+      ),
+      { numRuns: 80 },
+    );
+  });
+
+  it('selects one immutable plan and preallocates only proven nullable lanes across root, child, and overflow', () => {
+    const schema = defineLogSchema({
+      provenNumber: S.number(),
+      lazyString: S.category(),
+      provenString: S.category(),
+      lazyBoolean: S.boolean(),
+    });
+    const baseClass = getSpanBufferClass(schema);
+    const logBinding = { logSchema: schema, remapDescriptor: undefined };
+    const SpanContextClass = createSpanContextClass<OpContext<typeof schema>>(
+      schema,
+      logBinding,
+      RUNTIME_HINT_LOG | RUNTIME_HINT_RESULT,
+    );
+    const remap = createRemapDescriptor(schema, { local_number: 'provenNumber' });
+    const plan = getPhysicalLayoutPlan(baseClass, HINT, SpanContextClass, undefined, 'js-heap', '', [
+      'provenString',
+      'provenNumber',
+      'provenString',
+    ]);
+    const identical = getPhysicalLayoutPlan(baseClass, HINT, SpanContextClass, undefined, 'js-heap', '', [
+      'provenNumber',
+      'provenString',
+    ]);
+    const lazyPlan = getPhysicalLayoutPlan(baseClass, HINT, SpanContextClass, undefined, 'js-heap');
+    const remapped = getPhysicalLayoutPlan(baseClass, HINT, SpanContextClass, remap, 'js-heap', '', [
+      'provenNumber',
+      'provenString',
+    ]);
+
+    expect(identical).toBe(plan);
+    expect(lazyPlan).not.toBe(plan);
+    expect(remapped.eagerColumns).toBe(plan.eagerColumns);
+    expect(plan.eagerColumns.names).toEqual(['provenNumber', 'provenString']);
+    expect(plan.SpanBufferClass.eagerColumns).toBe(plan.eagerColumns);
+    expect(plan.wasmLayout.eagerColumns).toBe(plan.eagerColumns);
+
+    plan.SpanBufferClass.stats.capacity = 8;
+    const metadata = createTestOpMetadata();
+    const root = createSpanBuffer(schema, createTestTraceRoot('eager-root'), metadata, 8, plan.SpanBufferClass);
+    const child = createChildSpanBuffer(root, plan.SpanBufferClass, metadata, metadata, 8);
+    const overflow = createOverflowBuffer(child);
+
+    for (const buffer of [root, child, overflow]) {
+      expectCompilerEagerStorage(buffer, 'provenNumber');
+      expectCompilerEagerStorage(buffer, 'provenString');
+      expectLazyStorage(buffer, 'lazyString');
+      expectLazyStorage(buffer, 'lazyBoolean');
+      expect(buffer.constructor).toBe(plan.SpanBufferClass);
+    }
+    expect(child._parent).toBe(root);
+    expect(overflow._parent).toBe(root);
+    expect(overflow._identity).toBe(child._identity);
+    expect(child._identity).not.toBe(root._identity);
+
+    root.provenNumber(0, 42);
+    root.provenNumber(1, null);
+    child.provenString(2, 'child');
+    overflow.provenNumber(3, null);
+    root.lazyString(4, 'materialized lazily');
+
+    expect(root.getColumnIfAllocated('provenNumber')?.[0]).toBe(42);
+    const rootNumberNulls = root.getNullsIfAllocated('provenNumber');
+    if (!rootNumberNulls) throw new Error('expected provenNumber null bitmap');
+    expect(rootNumberNulls[0] & 0b00000001).toBe(1);
+    expect(rootNumberNulls[0] & 0b00000010).toBe(0);
+    expect(child.getColumnIfAllocated('provenString')?.[2]).toBe('child');
+    const childStringNulls = child.getNullsIfAllocated('provenString');
+    if (!childStringNulls) throw new Error('expected provenString null bitmap');
+    expect(childStringNulls[0] & 0b00000100).toBe(0b00000100);
+    const overflowNumberNulls = overflow.getNullsIfAllocated('provenNumber');
+    if (!overflowNumberNulls) throw new Error('expected overflow provenNumber null bitmap');
+    expect(overflowNumberNulls[0] & 0b00001000).toBe(0);
+    expect(root.getColumnIfAllocated('lazyString')?.[4]).toBe('materialized lazily');
+    expect(root.getColumnIfAllocated('lazyBoolean')).toBeUndefined();
+  });
+
+  it('uses exact analyzed capacities 2 through 7 with eager lanes while invalid and zero hints stay adaptive', async () => {
+    const schema = defineLogSchema({ proven: S.category(), lazy: S.category() });
+    const opContext = defineOpContext({ logSchema: schema });
+    const tracer = new TestTracer(opContext, createTestTracerOptions());
+
+    for (const capacity of [2, 3, 4, 5, 6, 7]) {
+      const observed: AnySpanBuffer[] = [];
+      const exactOp = opContext.defineOp(
+        `exact-${capacity}`,
+        (ctx) => {
+          observed.push(ctx.buffer);
+          for (let index = 0; index < 8; index++) {
+            ctx.log.debug(`capacity-${capacity}-${index}`).proven(`capacity-${capacity}-${index}`);
+          }
+          return ctx.ok(capacity);
+        },
+        undefined,
+        {
+          runtimeHint:
+            RUNTIME_HINT_ANALYZED_VALID | RUNTIME_HINT_LOG | RUNTIME_HINT_RESULT | RUNTIME_HINT_TAG | capacity,
+          eagerColumns: ['proven'],
+        },
+      );
+      const parentOp = opContext.defineOp(`parent-${capacity}`, async (ctx) => {
+        await ctx.span(`child-${capacity}`, exactOp);
+        return ctx.ok(capacity);
+      });
+
+      await tracer.trace(`root-${capacity}`, exactOp);
+      await tracer.trace(`parent-root-${capacity}`, parentOp);
+
+      expect(runtimeHintInitialCapacity(exactOp.callsitePlan.runtimeHint)).toBe(capacity);
+      expect(observed.map((buffer) => buffer._capacity)).toEqual([capacity, capacity]);
+      expect(observed).toHaveLength(2);
+      for (const buffer of observed) {
+        expect(buffer.constructor).toBe(exactOp.callsitePlan.SpanBufferClass);
+        const overflow = buffer._overflow;
+        if (!overflow) throw new Error(`Expected exact capacity ${capacity} to overflow`);
+        expect(overflow.constructor).toBe(exactOp.callsitePlan.SpanBufferClass);
+        expect(overflow._identity).toBe(buffer._identity);
+
+        const table = convertSpanTreeToArrowTable(buffer);
+        const proven = table.getChild('proven');
+        if (!proven) throw new Error('Expected proven Arrow column');
+        expect(
+          Array.from({ length: table.numRows }, (_, row) => proven.get(row)).filter(
+            (value): value is string => typeof value === 'string',
+          ),
+        ).toEqual(Array.from({ length: 8 }, (_, index) => `capacity-${capacity}-${index}`));
+        expectCompilerEagerStorage(buffer, 'proven');
+        expectLazyStorage(buffer, 'lazy');
+      }
+    }
+
+    const adaptiveBuffers: AnySpanBuffer[] = [];
+    const adaptiveOp = opContext.defineOp('adaptive-zero', (ctx) => {
+      adaptiveBuffers.push(ctx.buffer);
+      return ctx.ok('adaptive');
+    });
+    const invalidOneOp = opContext.defineOp(
+      'adaptive-invalid-one',
+      (ctx) => {
+        adaptiveBuffers.push(ctx.buffer);
+        return ctx.ok('adaptive');
+      },
+      undefined,
+      { runtimeHint: RUNTIME_HINT_ANALYZED_VALID | RUNTIME_HINT_RESULT | 1 },
+    );
+    const adaptiveStats = adaptiveOp.callsitePlan.SpanBufferClass.stats;
+    const invalidStats = invalidOneOp.callsitePlan.SpanBufferClass.stats;
+    const originalAdaptiveCapacity = adaptiveStats.capacity;
+    const originalInvalidCapacity = invalidStats.capacity;
+    try {
+      adaptiveStats.capacity = 5;
+      await tracer.trace('adaptive-minimum', adaptiveOp);
+      invalidStats.capacity = 13;
+      await tracer.trace('adaptive-stats', invalidOneOp);
+    } finally {
+      adaptiveStats.capacity = originalAdaptiveCapacity;
+      invalidStats.capacity = originalInvalidCapacity;
+    }
+
+    expect(runtimeHintInitialCapacity(0)).toBeUndefined();
+    expect(runtimeHintInitialCapacity(RUNTIME_HINT_ANALYZED_VALID)).toBeUndefined();
+    expect(runtimeHintInitialCapacity(RUNTIME_HINT_ANALYZED_VALID | 1)).toBeUndefined();
+    expect(adaptiveBuffers.map((buffer) => buffer._capacity)).toEqual([8, 13]);
+    for (const buffer of adaptiveBuffers) expectLazyStorage(buffer, 'proven');
+  });
+
+  it('rejects schema-incompatible planned classes before root or child allocation', () => {
+    const incompatibleContext = defineOpContext({ logSchema: defineLogSchema({ left: S.number() }) });
+    const compatibleContext = defineOpContext({ logSchema: defineLogSchema({ right: S.number() }) });
+    const incompatibleOp = incompatibleContext.defineOp('incompatible-plan', (ctx) => ctx.ok(null));
+    const compatibleOp = compatibleContext.defineOp('compatible-plan', (ctx) => ctx.ok(null));
+    const schema = compatibleOp.callsitePlan.schema;
+    const traceRoot = createTestTraceRoot('schema-mismatch');
+    const parent = createSpanBuffer(
+      schema,
+      traceRoot,
+      compatibleOp.metadata,
+      8,
+      compatibleOp.callsitePlan.SpanBufferClass,
+    );
+    const incompatibleStats = incompatibleOp.callsitePlan.SpanBufferClass.stats;
+    const spansCreated = incompatibleStats.spansCreated;
+
+    expect(() => createSpanBuffer(schema, traceRoot, incompatibleOp.metadata)).toThrow(
+      'Planned SpanBuffer class does not match schema',
+    );
+    const strategy = new JsBufferStrategy<typeof schema>();
+    expect(() =>
+      strategy.createChildSpanBuffer(parent, compatibleOp.metadata, incompatibleOp.metadata, undefined, schema),
+    ).toThrow('Planned SpanBuffer class does not match schema');
+    expect(incompatibleStats.spansCreated).toBe(spansCreated);
+  });
+
+  it('keeps plugin-off metadata all-lazy', () => {
+    const schema = defineLogSchema({ field: S.category() });
+    const SpanBufferClass = getSpanBufferClass(schema);
+    const SpanContextClass = createSpanContextClass<OpContext<typeof schema>>(
+      schema,
+      { logSchema: schema, remapDescriptor: undefined },
+      RUNTIME_HINT_LOG | RUNTIME_HINT_RESULT,
+    );
+    const plan = getPhysicalLayoutPlan(SpanBufferClass, HINT, SpanContextClass);
+    const buffer = createSpanBuffer(
+      schema,
+      createTestTraceRoot('plugin-off'),
+      createTestOpMetadata(),
+      8,
+      plan.SpanBufferClass,
+    );
+
+    expect(plan.eagerColumns.names).toEqual([]);
+    expect(plan.eagerColumns.words).toEqual([]);
+    expect(plan.eagerColumns.key).toBe('');
+    expectLazyStorage(buffer, 'field');
+  });
+});

package/src/lib/__tests__/enum-metadata-aot.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'bun:test';
+import './test-helpers.js';
+import { resolveEnumLookupDescriptor } from '../enumMetadata.js';
+import { createRemapDescriptor } from '../library.js';
+import type { OpContext } from '../opContext/types.js';
+import { getPhysicalLayoutPlan } from '../physicalLayoutPlan.js';
+import {
+  RUNTIME_HINT_ANALYZED_VALID,
+  RUNTIME_HINT_LOG,
+  RUNTIME_HINT_RESULT,
+  RUNTIME_HINT_TAG,
+} from '../runtimeHint.js';
+import { S } from '../schema/builder.js';
+import { defineLogSchema } from '../schema/defineLogSchema.js';
+import { getSpanBufferClass } from '../spanBuffer.js';
+import { createSpanContextClass } from '../spanContext.js';
+
+const ENUM_CAPABILITIES = RUNTIME_HINT_TAG | RUNTIME_HINT_LOG | RUNTIME_HINT_RESULT;
+const ENUM_CALLSITE_HINT = RUNTIME_HINT_ANALYZED_VALID | ENUM_CAPABILITIES | 4;
+
+function countFunctionConstructorCalls(run: () => void): number {
+  const originalDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'Function');
+  if (!originalDescriptor) throw new Error('Expected global Function descriptor');
+
+  const originalFunction = globalThis.Function;
+  let calls = 0;
+  const functionProbe = new Proxy(originalFunction, {
+    apply(target, thisArgument, argumentList) {
+      calls++;
+      return Reflect.apply(target, thisArgument, argumentList);
+    },
+    construct(target, argumentList, newTarget) {
+      calls++;
+      return Reflect.construct(target, argumentList, newTarget);
+    },
+  });
+
+  Object.defineProperty(globalThis, 'Function', {
+    configurable: originalDescriptor.configurable,
+    enumerable: originalDescriptor.enumerable,
+    value: functionProbe,
+    writable: originalDescriptor.writable,
+  });
+  try {
+    run();
+  } finally {
+    Object.defineProperty(globalThis, 'Function', originalDescriptor);
+  }
+  return calls;
+}
+
+describe('AOT-safe enum metadata', () => {
+  it('encodes declaration order and every storage-width boundary without compiling a Function', () => {
+    const functionConstructorCalls = countFunctionConstructorCalls(() => {
+      const orderedValues = ['ZERO', '__proto__', 'constructor', 'toString', 'OMEGA'];
+      const orderedSchema = defineLogSchema({ state: S.enum(orderedValues) });
+      const ordered = resolveEnumLookupDescriptor(orderedSchema).byField.state;
+
+      expect(ordered.values).toEqual(orderedValues);
+      expect(orderedValues.map((value) => ordered.encode(value))).toEqual([0, 1, 2, 3, 4]);
+      expect([ordered.encode('MISSING'), ordered.encode('valueOf'), ordered.encode('')]).toEqual([0, 0, 0]);
+
+      const boundaries = [
+        { count: 1, indexArrayConstructor: Uint8Array },
+        { count: 256, indexArrayConstructor: Uint8Array },
+        { count: 257, indexArrayConstructor: Uint16Array },
+        { count: 65_536, indexArrayConstructor: Uint16Array },
+        { count: 65_537, indexArrayConstructor: Uint32Array },
+      ];
+      for (const { count, indexArrayConstructor } of boundaries) {
+        const values = Array.from({ length: count }, (_, index) => `VALUE_${index}`);
+        const schema = defineLogSchema({ boundary: S.enum(values) });
+        const descriptor = resolveEnumLookupDescriptor(schema).byField.boundary;
+        const midpoint = Math.floor((count - 1) / 2);
+
+        expect(descriptor.indexArrayConstructor).toBe(indexArrayConstructor);
+        expect(descriptor.values).toEqual(values);
+        expect([
+          descriptor.encode('VALUE_0'),
+          descriptor.encode(`VALUE_${midpoint}`),
+          descriptor.encode(`VALUE_${count - 1}`),
+          descriptor.encode(`VALUE_${count}`),
+        ]).toEqual([0, midpoint, count - 1, 0]);
+      }
+    });
+
+    expect(functionConstructorCalls).toBe(0);
+  });
+
+  it('maps non-string values to zero without coercion or Function compilation', () => {
+    const functionConstructorCalls = countFunctionConstructorCalls(() => {
+      const schema = defineLogSchema({
+        value: S.enum(['ZERO', '1', '[object Object]', 'Symbol(value)']),
+      });
+      const encode = resolveEnumLookupDescriptor(schema).byField.value.encode;
+      const invalidValues = [1, {}, Symbol('value')];
+
+      expect(invalidValues.map((value) => Reflect.apply(encode, undefined, [value]))).toEqual([0, 0, 0]);
+    });
+
+    expect(functionConstructorCalls).toBe(0);
+  });
+
+  it('reuses schema descriptors and field cores without compiling a Function', () => {
+    const functionConstructorCalls = countFunctionConstructorCalls(() => {
+      const sharedField = S.enum(['QUEUED', 'RUNNING', 'DONE']);
+      const primarySchema = defineLogSchema({ state: sharedField });
+      const renamedSchema = defineLogSchema({ renamedState: sharedField });
+
+      const primaryLookup = resolveEnumLookupDescriptor(primarySchema);
+      const primaryDescriptor = primaryLookup.byField.state;
+      const renamedDescriptor = resolveEnumLookupDescriptor(renamedSchema).byField.renamedState;
+
+      expect(resolveEnumLookupDescriptor(primarySchema)).toBe(primaryLookup);
+      expect(resolveEnumLookupDescriptor(primarySchema).byField.state).toBe(primaryDescriptor);
+      expect(renamedDescriptor).not.toBe(primaryDescriptor);
+      expect(renamedDescriptor.fieldName).toBe('renamedState');
+      expect(renamedDescriptor.values).toBe(primaryDescriptor.values);
+      expect(renamedDescriptor.encode).toBe(primaryDescriptor.encode);
+      expect(renamedDescriptor.encode('RUNNING')).toBe(1);
+      expect(renamedDescriptor.encode('UNKNOWN')).toBe(0);
+    });
+
+    expect(functionConstructorCalls).toBe(0);
+  });
+
+  it('shares the schema descriptor with remapped physical plans without compiling a Function', () => {
+    const schema = defineLogSchema({ operation: S.enum(['READ', 'WRITE']) });
+    const functionConstructorCalls = countFunctionConstructorCalls(() => {
+      const firstLookup = resolveEnumLookupDescriptor(schema);
+      expect(firstLookup.byField.operation.encode('WRITE')).toBe(1);
+      expect(firstLookup.byField.operation.encode('INVALID')).toBe(0);
+    });
+
+    expect(functionConstructorCalls).toBe(0);
+
+    const lookup = resolveEnumLookupDescriptor(schema);
+    const remap = createRemapDescriptor(schema, { library_operation: 'operation' });
+    const SpanBufferClass = getSpanBufferClass(schema);
+    const SpanContextClass = createSpanContextClass<OpContext<typeof schema>>(
+      schema,
+      { logSchema: schema, remapDescriptor: undefined },
+      ENUM_CAPABILITIES,
+    );
+
+    const basePlan = getPhysicalLayoutPlan(SpanBufferClass, ENUM_CALLSITE_HINT, SpanContextClass);
+    const remappedPlan = getPhysicalLayoutPlan(SpanBufferClass, ENUM_CALLSITE_HINT, SpanContextClass, remap);
+
+    expect(basePlan.enumLookup).toBe(lookup);
+    expect(remappedPlan.enumLookup).toBe(lookup);
+    expect(remappedPlan.enumLookup.byField.operation).toBe(lookup.byField.operation);
+  });
+});

package/src/lib/__tests__/enum-metadata.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'bun:test';
+import './test-helpers.js';
+import { convertSpanTreeToArrowTable } from '../convertToArrow.js';
+import { defineOpContext } from '../defineOpContext.js';
+import { resolveEnumLookupDescriptor } from '../enumMetadata.js';
+import { createRemapDescriptor } from '../library.js';
+import type { OpContext } from '../opContext/types.js';
+import { getPhysicalLayoutPlan } from '../physicalLayoutPlan.js';
+import {
+  RUNTIME_HINT_ANALYZED_VALID,
+  RUNTIME_HINT_LOG,
+  RUNTIME_HINT_RESULT,
+  RUNTIME_HINT_SPAN,
+  RUNTIME_HINT_TAG,
+} from '../runtimeHint.js';
+import { S } from '../schema/builder.js';
+import { defineLogSchema } from '../schema/defineLogSchema.js';
+import { getSpanBufferClass } from '../spanBuffer.js';
+import { createSpanContextClass } from '../spanContext.js';
+import { TestTracer } from '../tracers/TestTracer.js';
+import { iterateSpanTree } from '../traceTopology.js';
+import { requireColumn } from './arrow-test-helpers.js';
+import { createTestTracerOptions } from './test-helpers.js';
+
+function makeValues(count: number): string[] {
+  return Array.from({ length: count }, (_, index) => `VALUE_${index}`);
+}
+
+function invokeEnumWriter(writer: object, value: string): void {
+  const method = Reflect.get(writer, 'operation');
+  if (typeof method !== 'function') throw new TypeError('Expected an operation enum writer');
+  Reflect.apply(method, writer, [value]);
+}
+
+const CHILD_HINT = RUNTIME_HINT_ANALYZED_VALID | RUNTIME_HINT_TAG | RUNTIME_HINT_LOG | RUNTIME_HINT_RESULT | 4;
+const PARENT_HINT = RUNTIME_HINT_ANALYZED_VALID | RUNTIME_HINT_SPAN | RUNTIME_HINT_RESULT | 4;
+
+describe('startup-hoisted enum lookup metadata', () => {
+  it.each([
+    [255, Uint8Array],
+    [256, Uint8Array],
+    [65_535, Uint16Array],
+    [65_536, Uint16Array],
+    [65_537, Uint32Array],
+  ])('preserves exact index width and boundary ordinal for %d values', (count, expectedConstructor) => {
+    const values = makeValues(count);
+    const schema = defineLogSchema({ boundary: S.enum(values) });
+    const descriptor = resolveEnumLookupDescriptor(schema).byField.boundary;
+
+    expect(descriptor.indexArrayConstructor).toBe(expectedConstructor);
+    expect(descriptor.values).toEqual(values);
+    expect(Object.isFrozen(descriptor.values)).toBe(true);
+    expect(descriptor.encode(values[0])).toBe(0);
+    expect(descriptor.encode(values[count - 1])).toBe(count - 1);
+    expect(descriptor.encode('NOT_IN_THE_ENUM')).toBe(0);
+  });
+
+  it('resolves once and reuses one descriptor through repeated trace, span, tag, log, result, overflow, and Arrow paths', async () => {
+    let valueMetadataReads = 0;
+    const values = new Proxy(['READ', 'WRITE'], {
+      get(target, property, receiver) {
+        if (property === Symbol.iterator || (typeof property === 'string' && /^\d+$/.test(property))) {
+          valueMetadataReads++;
+        }
+        return Reflect.get(target, property, receiver);
+      },
+    });
+    const schema = defineLogSchema({ operation: S.enum(values) });
+    const context = defineOpContext({ logSchema: schema });
+
+    valueMetadataReads = 0;
+    const child = context.defineOp(
+      'enum-child',
+      (ctx) => {
+        ctx.tag.operation('WRITE');
+        for (let index = 0; index < 10; index++) {
+          ctx.log.info(`enum-${index}`).operation(index % 2 === 0 ? 'READ' : 'WRITE');
+        }
+        return ctx.ok('done').with({ operation: 'WRITE' });
+      },
+      undefined,
+      { runtimeHint: CHILD_HINT },
+    );
+    const firstResolutionReads = valueMetadataReads;
+    const lookup = child.callsitePlan.enumLookup;
+    expect(firstResolutionReads).toBeGreaterThan(0);
+    expect(resolveEnumLookupDescriptor(child.callsitePlan.schema)).toBe(lookup);
+    const encode = lookup.byField.operation.encode;
+
+    valueMetadataReads = 0;
+    const parent = context.defineOp(
+      'enum-parent',
+      async (ctx) => {
+        for (let index = 0; index < 3; index++) await ctx.span(`child-${index}`, child);
+        return ctx.ok('done');
+      },
+      undefined,
+      { runtimeHint: PARENT_HINT },
+    );
+    expect(parent.callsitePlan.enumLookup).toBe(lookup);
+
+    const tracer = new TestTracer(context, createTestTracerOptions());
+    for (let index = 0; index < 4; index++) await tracer.trace(`trace-${index}`, parent);
+
+    expect(child.callsitePlan.enumLookup).toBe(lookup);
+    expect(parent.callsitePlan.enumLookup).toBe(lookup);
+    expect(valueMetadataReads).toBe(0);
+
+    let overflowCount = 0;
+    for (const root of tracer.rootBuffers) {
+      for (const segment of iterateSpanTree(root)) {
+        if (segment._overflow !== undefined) overflowCount++;
+      }
+      const table = convertSpanTreeToArrowTable(root);
+      const operations = requireColumn(table, 'operation');
+      expect(Array.from({ length: operations.length }, (_, row) => operations.get(row)).filter(Boolean)).toContain(
+        'WRITE',
+      );
+    }
+    expect(overflowCount).toBeGreaterThan(0);
+    expect(resolveEnumLookupDescriptor(child.callsitePlan.schema)).toBe(lookup);
+    expect(child.callsitePlan.enumLookup.byField.operation.encode).toBe(encode);
+  });
+
+  it('keeps invalid-value fallback and dictionary decoding exact for tag, log, and result writers', async () => {
+    const schema = defineLogSchema({ operation: S.enum(['READ', 'WRITE']) });
+    const context = defineOpContext({ logSchema: schema });
+    const op = context.defineOp('invalid-enum', (ctx) => {
+      invokeEnumWriter(ctx.tag, 'INVALID');
+      invokeEnumWriter(ctx.log.info('invalid-log'), 'INVALID');
+      return ctx.ok('done').with({ operation: JSON.parse('"INVALID"') });
+    });
+    const tracer = new TestTracer(context, createTestTracerOptions());
+
+    await tracer.trace('invalid-enum-root', op);
+
+    const root = tracer.rootBuffers[0];
+    if (!root) throw new Error('Expected invalid enum trace root');
+    const raw = root.operation_values;
+    expect([raw[0], raw[1], raw[2]]).toEqual([0, 0, 0]);
+    const decoded = requireColumn(convertSpanTreeToArrowTable(root), 'operation');
+    expect([decoded.get(0), decoded.get(1), decoded.get(2)]).toEqual(['READ', 'READ', 'READ']);
+    expect(op.callsitePlan.enumLookup.byField.operation.encode('INVALID')).toBe(0);
+  });
+
+  it('separates extended schemas while remapped plans reuse the extended schema descriptor', () => {
+    const base = defineLogSchema({ operation: S.enum(['READ', 'WRITE']) });
+    const extended = base.extend({ phase: S.enum(['QUEUED', 'RUNNING', 'DONE']) });
+    const baseLookup = resolveEnumLookupDescriptor(base);
+    const extendedLookup = resolveEnumLookupDescriptor(extended);
+
+    expect(baseLookup.ordered.map((descriptor) => descriptor.fieldName)).toEqual(['operation']);
+    expect(extendedLookup.ordered.map((descriptor) => descriptor.fieldName)).toEqual(['operation', 'phase']);
+    expect(extendedLookup).not.toBe(baseLookup);
+    expect(resolveEnumLookupDescriptor(base)).toBe(baseLookup);
+    expect(resolveEnumLookupDescriptor(extended)).toBe(extendedLookup);
+
+    const remap = createRemapDescriptor(extended, {
+      library_operation: 'operation',
+      library_phase: 'phase',
+    });
+    const SpanBufferClass = getSpanBufferClass(extended);
+    const SpanContextClass = createSpanContextClass<OpContext<typeof extended>>(
+      extended,
+      { logSchema: extended, remapDescriptor: undefined },
+      RUNTIME_HINT_TAG | RUNTIME_HINT_LOG | RUNTIME_HINT_RESULT,
+    );
+    const basePlan = getPhysicalLayoutPlan(SpanBufferClass, CHILD_HINT, SpanContextClass);
+    const remappedPlan = getPhysicalLayoutPlan(SpanBufferClass, CHILD_HINT, SpanContextClass, remap);
+
+    expect(basePlan.enumLookup).toBe(extendedLookup);
+    expect(remappedPlan.enumLookup).toBe(extendedLookup);
+    expect(remappedPlan.remapDescriptor).toBe(remap);
+    expect(remappedPlan.enumLookup.byField.operation.values).toEqual(['READ', 'WRITE']);
+    expect(remappedPlan.enumLookup.byField.phase.values).toEqual(['QUEUED', 'RUNNING', 'DONE']);
+  });
+});