@smoothbricks/lmao 0.2.2 → 0.2.3

package/src/lib/tracer.ts

@@ -60,27 +60,29 @@
  */
 
 import type { BufferStrategy } from './bufferStrategy.js';
-import type { TagWriter } from './codegen/fixedPositionWriterGenerator.js';
-import { createTagWriter } from './codegen/fixedPositionWriterGenerator.js';
-import { createSpanLogger as createSpanLoggerFromGenerator } from './codegen/spanLoggerGenerator.js';
 import type { LogBinding } from './logBinding.js';
 import { Op } from './op.js';
 import { createOpMetadata } from './opContext/defineOp.js';
 import type { OpContext, OpContextBinding, OpContextOf, SpanContext } from './opContext/types.js';
+import {
+  type CallsitePlan,
+  getPhysicalLayoutPlan,
+  type PhysicalLayoutPlan,
+  sealCallsitePlan,
+} from './physicalLayoutPlan.js';
 import { Err, Ok, type Result } from './result.js';
 import { createFeatureFlagEvaluator, type FlagEvaluator, InMemoryFlagEvaluator } from './schema/evaluator.js';
 import { ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_OK } from './schema/systemSchema.js';
-
-import { EMPTY_SCOPE } from './spanBuffer.js';
+import { EMPTY_SCOPE, getSpanBufferClass } from './spanBuffer.js';
 import {
   createSpanContextClass,
+  isPhysicalLayoutPlanForContext,
   type SpanContextClass,
   type SpanContextInstance,
   writeSpanEnd,
-  writeSpanStart,
 } from './spanContext.js';
 import { generateTraceId, isValidTraceId, type TraceId } from './traceId.js';
-import type { TraceRootFactory } from './traceRoot.js';
+import type { TraceRootFactory, TracerLifecycleHooks } from './traceRoot.js';
 import type { SpanBuffer } from './types.js';
 
 // =============================================================================
@@ -110,7 +112,7 @@ export interface TracerOptions<
    * Factory for creating platform-specific TraceRoot instances.
    * Import from '@smoothbricks/lmao/node' or '@smoothbricks/lmao/es'.
    */
-  createTraceRoot: TraceRootFactory;
+  createTraceRoot: TraceRootFactory<T>;
 
   /** Feature flag evaluator - provides flag values at runtime */
   flagEvaluator?: FlagEvaluator<OpContext>;
@@ -251,13 +253,17 @@ export type TraceFn<Ctx extends OpContext> = {
  *
  * @typeParam B - OpContextBinding type (inferred from constructor argument)
  */
-export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
+export abstract class Tracer<B extends OpContextBinding = OpContextBinding>
+  implements TracerLifecycleHooks<B['logBinding']['logSchema']>
+{
   private readonly logBinding: LogBinding<B['logBinding']['logSchema']>;
   private readonly SpanContextClass: SpanContextClass<OpContextOf<B>>;
+  private readonly physicalLayoutPlan: PhysicalLayoutPlan<B['logBinding']['logSchema'], OpContextOf<B>>;
   private readonly flagEvaluator: FlagEvaluator<OpContextOf<B>>;
   private readonly ctxDefaults: Record<string, unknown>;
+  private readonly requiredCtxKeys: readonly string[];
   private readonly deps: Record<string, unknown>;
-  private readonly createTraceRoot: TraceRootFactory;
+  private readonly createTraceRoot: TraceRootFactory<B['logBinding']['logSchema']>;
 
   /**
    * Buffer strategy for memory management and Arrow conversion.
@@ -270,13 +276,32 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     this.logBinding = binding.logBinding;
     this.bufferStrategy = options.bufferStrategy;
     this.ctxDefaults = binding.ctxDefaults ?? EMPTY_SCOPE;
+    const userContextKeys = Object.keys(this.ctxDefaults).sort();
+    const requiredCtxKeys: string[] = [];
+    for (const key of userContextKeys) {
+      if (this.ctxDefaults[key] === null) requiredCtxKeys.push(key);
+    }
+    this.requiredCtxKeys = requiredCtxKeys;
     this.deps = binding.deps ?? EMPTY_SCOPE;
     this.flagEvaluator = this._createFlagEvaluator(binding.flags, options.flagEvaluator);
     this.createTraceRoot = options.createTraceRoot;
 
     // Create SpanContext class for all contexts created by this tracer
     // The class closes over schema/logBinding and provides typed methods
-    this.SpanContextClass = createSpanContextClass<OpContextOf<B>>(binding.logBinding.logSchema, binding.logBinding);
+    this.SpanContextClass = createSpanContextClass<OpContextOf<B>>(
+      binding.logBinding.logSchema,
+      binding.logBinding,
+      undefined,
+      userContextKeys,
+    );
+    this.physicalLayoutPlan = getPhysicalLayoutPlan(
+      getSpanBufferClass(binding.logBinding.logSchema),
+      0,
+      this.SpanContextClass,
+      undefined,
+      'strategy-selected',
+      userContextKeys.join('\u0000'),
+    );
 
     // Bind methods for destructuring (per AGENTS.md - "Always destructure")
     this.trace = this.trace.bind(this);
@@ -285,6 +310,10 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     this.flush = this.flush.bind(this);
   }
 
+  getFlagEvaluatorForContext(): FlagEvaluator<OpContextOf<B>> {
+    return this.flagEvaluator;
+  }
+
   private _createFlagEvaluator(
     flags: B['flags'],
     evaluator: FlagEvaluator<OpContext> | undefined,
@@ -441,15 +470,15 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     if (fnOrOp instanceof Op) {
       switch (argCount) {
         case 0:
-          return this._trace_unknown_op(line, name, overrides, fnOrOp.metadata, fnOrOp.fn);
+          return this._trace_unknown_op(line, name, overrides, fnOrOp.callsitePlan, fnOrOp.fn);
         case 1:
-          return this._trace_unknown_op(line, name, overrides, fnOrOp.metadata, fnOrOp.fn, args[fnIdx + 1]);
+          return this._trace_unknown_op(line, name, overrides, fnOrOp.callsitePlan, fnOrOp.fn, args[fnIdx + 1]);
         case 2:
           return this._trace_unknown_op(
             line,
             name,
             overrides,
-            fnOrOp.metadata,
+            fnOrOp.callsitePlan,
             fnOrOp.fn,
             args[fnIdx + 1],
             args[fnIdx + 2],
@@ -459,7 +488,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
             line,
             name,
             overrides,
-            fnOrOp.metadata,
+            fnOrOp.callsitePlan,
             fnOrOp.fn,
             args[fnIdx + 1],
             args[fnIdx + 2],
@@ -470,7 +499,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
             line,
             name,
             overrides,
-            fnOrOp.metadata,
+            fnOrOp.callsitePlan,
             fnOrOp.fn,
             args[fnIdx + 1],
             args[fnIdx + 2],
@@ -482,7 +511,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
             line,
             name,
             overrides,
-            fnOrOp.metadata,
+            fnOrOp.callsitePlan,
             fnOrOp.fn,
             args[fnIdx + 1],
             args[fnIdx + 2],
@@ -495,7 +524,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
             line,
             name,
             overrides,
-            fnOrOp.metadata,
+            fnOrOp.callsitePlan,
             fnOrOp.fn,
             args[fnIdx + 1],
             args[fnIdx + 2],
@@ -509,7 +538,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
             line,
             name,
             overrides,
-            fnOrOp.metadata,
+            fnOrOp.callsitePlan,
             fnOrOp.fn,
             args[fnIdx + 1],
             args[fnIdx + 2],
@@ -524,7 +553,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
             line,
             name,
             overrides,
-            fnOrOp.metadata,
+            fnOrOp.callsitePlan,
             fnOrOp.fn,
             args[fnIdx + 1],
             args[fnIdx + 2],
@@ -566,7 +595,10 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     op: Op<OpContextOf<B>, Args, S, E>,
     ...opArgs: Args
   ): Result<S, E> | Promise<Result<S, E>> {
-    const ctx = this._createRootContext(line, name, overrides, op.metadata);
+    if (!isPhysicalLayoutPlanForContext<OpContextOf<B>>(op.callsitePlan, this.logBinding.logSchema)) {
+      throw new TypeError('Op physical layout plan does not match this tracer context');
+    }
+    const ctx = this._createRootContext(line, name, overrides, op.callsitePlan);
     return this._executeResultWithContext(ctx, (c) => op.fn(c, ...opArgs));
   }
 
@@ -574,14 +606,14 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     line: number,
     name: string,
     overrides: Record<string, unknown>,
-    metadata: ReturnType<typeof createOpMetadata>,
+    callsitePlan: CallsitePlan<B['logBinding']['logSchema'], OpContextOf<B>>,
     fn: (
       ctx: SpanContext<OpContextOf<B>>,
       ...opArgs: unknown[]
     ) => Result<unknown, unknown> | Promise<Result<unknown, unknown>>,
     ...opArgs: unknown[]
   ): Result<unknown, unknown> | Promise<Result<unknown, unknown>> {
-    const ctx = this._createRootContext(line, name, overrides, metadata);
+    const ctx = this._createRootContext(line, name, overrides, callsitePlan);
     return this._executeResultWithContext(ctx, (childCtx) => fn(childCtx, ...opArgs));
   }
 
@@ -607,12 +639,11 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     overrides: Record<string, unknown>,
     fn: (ctx: SpanContext<OpContextOf<B>>) => unknown,
   ): unknown {
-    const ctx = this._createRootContext(
-      line,
-      name,
-      overrides,
-      createOpMetadata('root', 'tracer', 'runtime', 'unknown', 0),
-    );
+    const metadata = Object.freeze({
+      ...createOpMetadata('root', 'tracer', 'runtime', 'unknown', 0),
+      _physicalLayoutPlan: this.physicalLayoutPlan,
+    });
+    const ctx = this._createRootContext(line, name, overrides, sealCallsitePlan(this.physicalLayoutPlan, metadata));
     return this._executeUnknownWithContext(ctx, fn);
   }
 
@@ -676,16 +707,14 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     _line: number,
     name: string,
     overrides: Record<string, unknown>,
-    metadata: ReturnType<typeof createOpMetadata>,
+    callsitePlan: CallsitePlan<B['logBinding']['logSchema'], OpContextOf<B>>,
   ): SpanContextInstance<OpContextOf<B>> {
     // Extract trace_id from overrides if present
     const traceId: TraceId = isValidTraceId(overrides.trace_id) ? overrides.trace_id : generateTraceId();
-    const schema = this.logBinding.logSchema;
+    const schema = callsitePlan.schema;
 
-    // Validate null-sentinel required fields and merge user context.
-    // _resolveUserContext ignores trace_id (transport-only field).
-    const overrideRecord: Record<string, unknown> = { ...overrides };
-    const resolvedUserCtx = this._resolveUserContext(overrideRecord);
+    // Validate required null-sentinel fields before allocating the trace root or buffer.
+    this._validateRequiredUserContext(overrides);
 
     // Create TraceRoot via platform-specific factory
     const traceRoot = this.createTraceRoot(traceId, this);
@@ -693,71 +722,51 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     // Create root SpanBuffer with pre-built TraceRoot via strategy
     const buffer = this.bufferStrategy.createSpanBuffer(
       schema,
-      traceRoot, // pre-built TraceRoot with trace_id, anchors, tracer
-      metadata, // opMetadata (for both callsite and op at root level)
+      traceRoot,
+      callsitePlan.metadata,
+      callsitePlan.capacityTier,
+      callsitePlan.SpanBufferClass,
     );
 
     // Write span-start entry (row 0)
-    writeSpanStart(buffer, name);
-
-    // Create tag writer and span logger (needed for constructor)
-    const tagWriter: TagWriter<B['logBinding']['logSchema']> = createTagWriter(schema, buffer);
-    const spanLogger = createSpanLoggerFromGenerator(schema, buffer);
-
-    // Instantiate SpanContext class with direct arguments (no temp object allocation)
-    const ctx = new this.SpanContextClass(buffer, schema, spanLogger, tagWriter);
+    callsitePlan.appenders.writeSpanStart(buffer, name);
 
-    // Set up deps from config (may be EMPTY_SCOPE if none provided)
-    ctx.deps = this.deps;
-
-    ctx.ff = this.flagEvaluator.forContext(ctx);
-
-    // Copy resolved user context onto SpanContext.
-    for (const key in resolvedUserCtx) {
-      (ctx as Record<string, unknown>)[key] = resolvedUserCtx[key];
-    }
-
-    return ctx;
+    return new callsitePlan.SpanContextClass(
+      buffer,
+      schema,
+      callsitePlan,
+      this.ctxDefaults,
+      overrides,
+      this.deps,
+      this.flagEvaluator,
+    );
   }
 
   /**
-   * Validate null-sentinel required fields and merge with provided overrides.
+   * Validate null-sentinel required fields without materializing a merged
+   * user-context carrier.
    *
    * Per the ctx config pattern:
    * - Properties with null values in ctxDefaults must be provided in overrides
    * - Properties with default values can optionally be overridden
    * - undefined is allowed for optional fields
    */
-  private _resolveUserContext(overrides: Record<string, unknown>): Record<string, unknown> {
-    const ctxDefaults = this.ctxDefaults;
-
-    // Check that all null-sentinel keys are provided in overrides
-    for (const key of Object.keys(ctxDefaults)) {
-      const defaultValue = ctxDefaults[key];
-      if (defaultValue === null) {
-        const providedValue = overrides[key];
-        if (providedValue === null || providedValue === undefined) {
-          throw new Error(
-            `Required context parameter '${key}' must be provided. ` +
-              'Properties with null values in ctx config are required.',
-          );
-        }
-      }
-    }
-
-    // Merge defaults with provided overrides (provided values win)
-    const resolvedUserCtx: Record<string, unknown> = { ...ctxDefaults };
-    for (const key of Object.keys(overrides)) {
-      if (key === 'trace_id') {
-        continue;
+  private _validateRequiredUserContext(overrides: Record<string, unknown>): void {
+    for (const key of this.requiredCtxKeys) {
+      if (!Object.prototype.propertyIsEnumerable.call(overrides, key)) {
+        throw new Error(
+          `Required context parameter '${key}' must be provided. ` +
+            'Properties with null values in ctx config are required.',
+        );
       }
-      const value = overrides[key];
-      if (value !== undefined) {
-        resolvedUserCtx[key] = value;
+      const providedValue = overrides[key];
+      if (providedValue === null || providedValue === undefined) {
+        throw new Error(
+          `Required context parameter '${key}' must be provided. ` +
+            'Properties with null values in ctx config are required.',
+        );
       }
     }
-
-    return resolvedUserCtx;
   }
 
   /**
@@ -771,9 +780,10 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     ctx: SpanContextInstance<OpContextOf<B>>,
     fn: (ctx: SpanContext<OpContextOf<B>>) => Result<S, E> | Promise<Result<S, E>>,
   ): Result<S, E> | Promise<Result<S, E>> {
-    const buffer = ctx._buffer;
+    const buffer = ctx._spanBuffer;
+    const writeSpanEndEntry = ctx._physicalLayoutPlan.appenders.writeSpanEnd;
 
-    this.onTraceStart(buffer as SpanBuffer<B['logBinding']['logSchema']>);
+    this.onTraceStart(buffer);
 
     let isAsync = false;
     try {
@@ -788,7 +798,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
               return resolved;
             },
             (error: unknown) => {
-              buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
+              writeSpanEndEntry(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
 
               const errorMessage = error instanceof Error ? error.message : String(error);
               const errorStack = error instanceof Error ? error.stack : undefined;
@@ -801,13 +811,13 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
               throw error;
             },
           )
-          .finally(() => this.onTraceEnd(buffer as SpanBuffer<B['logBinding']['logSchema']>));
+          .finally(() => this.onTraceEnd(buffer));
       }
 
       writeSpanEnd(buffer, result);
       return result;
     } catch (error) {
-      buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
+      writeSpanEndEntry(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
 
       const errorMessage = error instanceof Error ? error.message : String(error);
       const errorStack = error instanceof Error ? error.stack : undefined;
@@ -820,7 +830,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
       throw error;
     } finally {
       if (!isAsync) {
-        this.onTraceEnd(buffer as SpanBuffer<B['logBinding']['logSchema']>);
+        this.onTraceEnd(buffer);
       }
     }
   }
@@ -829,10 +839,11 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     ctx: SpanContextInstance<OpContextOf<B>>,
     fn: (ctx: SpanContext<OpContextOf<B>>) => unknown,
   ): unknown {
-    const buffer = ctx._buffer;
+    const buffer = ctx._spanBuffer;
+    const writeSpanEndEntry = ctx._physicalLayoutPlan.appenders.writeSpanEnd;
 
     // Call trace start hook
-    this.onTraceStart(buffer as SpanBuffer<B['logBinding']['logSchema']>);
+    this.onTraceStart(buffer);
 
     let isAsync = false;
     try {
@@ -846,12 +857,12 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
               if (resolved instanceof Ok || resolved instanceof Err) {
                 writeSpanEnd(buffer, resolved);
               } else {
-                buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_OK);
+                writeSpanEndEntry(buffer, ENTRY_TYPE_SPAN_OK);
               }
               return resolved;
             },
             (error: unknown) => {
-              buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
+              writeSpanEndEntry(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
 
               const errorMessage = error instanceof Error ? error.message : String(error);
               const errorStack = error instanceof Error ? error.stack : undefined;
@@ -864,20 +875,20 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
               throw error;
             },
           )
-          .finally(() => this.onTraceEnd(buffer as SpanBuffer<B['logBinding']['logSchema']>));
+          .finally(() => this.onTraceEnd(buffer));
       }
 
       // Sync path - write span-end
       if (result instanceof Ok || result instanceof Err) {
         writeSpanEnd(buffer, result);
       } else {
-        buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_OK);
+        writeSpanEndEntry(buffer, ENTRY_TYPE_SPAN_OK);
       }
 
       return result;
     } catch (error) {
       // Sync exception path
-      buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
+      writeSpanEndEntry(buffer, ENTRY_TYPE_SPAN_EXCEPTION);
 
       // Write exception details
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -892,7 +903,7 @@ export abstract class Tracer<B extends OpContextBinding = OpContextBinding> {
     } finally {
       // Only call for sync path - async uses .finally() on promise
       if (!isAsync) {
-        this.onTraceEnd(buffer as SpanBuffer<B['logBinding']['logSchema']>);
+        this.onTraceEnd(buffer);
       }
     }
   }

package/src/lib/tracers/ArrayQueueTracer.ts

@@ -67,7 +67,7 @@ export class ArrayQueueTracer<B extends OpContextBinding = OpContextBinding> ext
    * Consume all queued buffers and clear the queue.
    * Returns an independent copy of the queue contents.
    *
-   * @returns Array of root buffers (with child spans in _children tree)
+   * @returns Array of root buffers whose children live in the trace topology arena
    */
   drain(): SpanBuffer<B['logBinding']['logSchema']>[] {
     const buffers = [...this.queue];

package/src/lib/tracers/StdioTracer.ts

@@ -32,6 +32,7 @@
  */
 
 import type { OpContextBinding } from '../opContext/types.js';
+import { resolveEntryType, resolveMessage } from '../resolveMessage.js';
 import {
   ENTRY_TYPE_DEBUG,
   ENTRY_TYPE_ERROR,
@@ -154,21 +155,22 @@ function getLogLevel(entryType: number): string | null {
 }
 
 function formatTemplateMessage(buffer: AnySpanBuffer, row: number, template: string): string {
-  return template.replace(/\{\{([A-Za-z0-9_]+)\}\}/g, (_full, key: string) => {
+  return template.replace(/\{([A-Za-z0-9_]+)\}/g, (_full, key: string) => {
+    const placeholder = `{${key}}`;
     const values = Reflect.get(buffer, `${key}_values`) as unknown;
-    if (values == null) return `{{${key}}}`;
+    if (values == null) return placeholder;
 
     if (Array.isArray(values)) {
       const value = values[row];
-      return value === null || value === undefined ? `{{${key}}}` : String(value);
+      return value === null || value === undefined ? placeholder : String(value);
     }
 
     if (ArrayBuffer.isView(values)) {
       const value = Reflect.get(values, row) as unknown;
-      return value === null || value === undefined ? `{{${key}}}` : String(value);
+      return value === null || value === undefined ? placeholder : String(value);
     }
 
-    return `{{${key}}}`;
+    return placeholder;
   });
 }
 
@@ -268,10 +270,10 @@ export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends
       const end = current._writeIndex;
 
       for (let i = start; i < end; i++) {
-        const level = getLogLevel(current.entry_type[i]);
+        const level = getLogLevel(resolveEntryType(current, i));
         if (!level) continue;
 
-        const template = current.message_values[i] ?? '';
+        const template = resolveMessage(current, i) ?? '';
         const message = formatTemplateMessage(current, i, template);
         const ts = formatTimestamp(current.timestamp[i]);
         const traceId = current.trace_id;
@@ -297,7 +299,7 @@ export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends
 
   onTraceStart(rootBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void {
     const traceId = rootBuffer.trace_id;
-    const name = rootBuffer.message_values[0];
+    const name = resolveMessage(rootBuffer, 0);
     const ts = formatTimestamp(rootBuffer.timestamp[0]);
 
     this.out.write(`[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ${name}\n`);
@@ -309,11 +311,11 @@ export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends
     this.printLogRows(rootBuffer, 1);
     this.decrementIndent(traceId);
 
-    const name = rootBuffer.message_values[0];
+    const name = resolveMessage(rootBuffer, 0);
     const startTs = rootBuffer.timestamp[0];
     const endTs = rootBuffer.timestamp[1];
     const duration = formatDuration(endTs - startTs);
-    const entryType = rootBuffer.entry_type[1];
+    const entryType = resolveEntryType(rootBuffer, 1);
     const status = getStatus(entryType);
     const ts = formatTimestamp(endTs);
 
@@ -330,7 +332,7 @@ export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends
   onSpanStart(childBuffer: SpanBuffer<B['logBinding']['logSchema']> | AnySpanBuffer): void {
     const traceId = childBuffer.trace_id;
     const indent = this.getIndent(traceId);
-    const name = childBuffer.message_values[0];
+    const name = resolveMessage(childBuffer, 0);
     const ts = formatTimestamp(childBuffer.timestamp[0]);
 
     this.out.write(`[${ts}] ${this.color(traceId)}[${traceId}]${this.reset()} ${'  '.repeat(indent)}├─ ${name}\n`);
@@ -343,11 +345,11 @@ export class StdioTracer<B extends OpContextBinding = OpContextBinding> extends
     const indent = this.getIndent(traceId);
     this.printLogRows(childBuffer, indent + 1);
 
-    const name = childBuffer.message_values[0];
+    const name = resolveMessage(childBuffer, 0);
     const startTs = childBuffer.timestamp[0];
     const endTs = childBuffer.timestamp[1];
     const duration = formatDuration(endTs - startTs);
-    const entryType = childBuffer.entry_type[1];
+    const entryType = resolveEntryType(childBuffer, 1);
     const status = getStatus(entryType);
     const ts = formatTimestamp(endTs);
 

package/src/lib/tracers/TestTracer.ts

@@ -1,7 +1,7 @@
 /**
  * TestTracer - A tracer that accumulates completed root trace buffers for test inspection.
  *
- * Child spans are accessible via the buffer's `_children` tree - no need to track them separately.
+ * Child spans are accessible through the trace topology arena; no duplicate tracking is needed.
  * This is the primary tracer for tests that need to inspect trace output, convert to Arrow tables,
  * or verify buffer contents.
  *
@@ -54,9 +54,8 @@ export interface StatsSnapshot<T extends LogSchema = LogSchema> {
 /**
  * Test tracer that accumulates root buffers for inspection.
  *
- * Collects all completed root trace buffers in `rootBuffers` array.
- * Child spans are accessible via the buffer's `_children` tree -
- * no need to track them separately.
+ * Collects all completed root trace buffers in `rootBuffers`; child spans remain reachable
+ * through each root's trace topology arena.
  *
  * Also tracks capacity tuning events via `statsSnapshots` to verify
  * that `onStatsWillResetFor` is called before stats are reset.
@@ -84,8 +83,7 @@ export interface StatsSnapshot<T extends LogSchema = LogSchema> {
 //#region smoo/lmao!n/tracer-implementations.test
 export class TestTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
   /**
-   * All completed root trace buffers.
-   * Child spans are accessible via each buffer's `_children` tree.
+   * All completed root trace buffers. Child spans remain in each root's topology arena.
    */
   readonly rootBuffers: SpanBuffer<B['logBinding']['logSchema']>[] = [];
 
@@ -109,11 +107,11 @@ export class TestTracer<B extends OpContextBinding = OpContextBinding> extends T
   }
 
   onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
-    // No-op - children are in tree, accessed via rootBuffer._children
+    // No-op - children are registered in the trace topology arena
   }
 
   onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
-    // No-op - children are in tree, accessed via rootBuffer._children
+    // No-op - children are registered in the trace topology arena
   }
 
   onStatsWillResetFor(buffer: SpanBuffer<B['logBinding']['logSchema']>): void {