@smoothbricks/lmao 0.2.2 → 0.3.0

package/src/lib/traceRoot.es.ts

@@ -11,40 +11,98 @@
  */
 
 import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import type { LogSchema } from './schema/LogSchema.js';
 import { ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_START } from './schema/systemSchema.js';
 import { createTraceId, type TraceId } from './traceId.js';
 import {
   type ITraceRoot,
+  type SpanEndPrimitive,
+  type SpanStartPrimitive,
+  type TimestampAppendPrimitive,
+  type TimestampNowPrimitive,
   TRACE_ROOT_ANCHOR_EPOCH_OFFSET,
   TRACE_ROOT_ANCHOR_PERF_OFFSET,
   TRACE_ROOT_TRACE_ID_LEN_OFFSET,
   TRACE_ROOT_TRACE_ID_OFFSET,
   type TracerLifecycleHooks,
 } from './traceRoot.js';
+import { TraceTopology } from './traceTopology.js';
 import type { AnySpanBuffer } from './types.js';
 
 /** Shared TextEncoder for trace_id encoding (stateless, reusable) */
 const textEncoder = new TextEncoder();
 
-/** Shared TextDecoder for trace_id decoding (stateless, reusable) */
-const textDecoder = new TextDecoder();
-
 /**
  * TraceRoot - Browser implementation with performance.now() timing.
  *
  * Stores anchor data in _system ArrayBuffer for consistency with Node.js layout,
  * but all timestamp calculations are done in pure JS.
  */
-export class TraceRoot implements ITraceRoot {
+function nextTimestamp(root: TraceRoot): Nanoseconds {
+  const elapsedNanos = BigInt(Math.floor((performance.now() - root._anchorPerformanceNow) * 1000)) * 1000n;
+  let timestamp = root._anchorEpochNanos + elapsedNanos;
+  if (timestamp <= root._lastTimestampNanos) timestamp = root._lastTimestampNanos + 1000n;
+  root._lastTimestampNanos = timestamp;
+  return Nanoseconds.unsafe(timestamp);
+}
+
+const timestampNow: TimestampNowPrimitive = (traceRoot) => {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ES primitive table is only installed on TraceRoot.es instances.
+  return nextTimestamp(traceRoot as TraceRoot);
+};
+
+const appendLogEntry: TimestampAppendPrimitive = (traceRoot, buffer, entryType) => {
+  const entryTypes = buffer.entry_type;
+  if (entryTypes === undefined) throw new TypeError('Split timestamp appender requires entry_type storage');
+  const idx = buffer._writeIndex;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ES primitive table is only installed on TraceRoot.es instances.
+  buffer.timestamp[idx] = nextTimestamp(traceRoot as TraceRoot);
+  entryTypes[idx] = entryType;
+  buffer._writeIndex = idx + 1;
+  return idx;
+};
+
+const writeSpanStartPrimitive: SpanStartPrimitive = (traceRoot, buffer, spanName) => {
+  const entryTypes = buffer.entry_type;
+  if (entryTypes === undefined) throw new TypeError('Split span-start appender requires entry_type storage');
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ES primitive table is only installed on TraceRoot.es instances.
+  buffer.timestamp[0] = nextTimestamp(traceRoot as TraceRoot);
+  entryTypes[0] = ENTRY_TYPE_SPAN_START;
+  if (buffer.message_values) buffer.message(0, spanName);
+  entryTypes[1] = ENTRY_TYPE_SPAN_EXCEPTION;
+  buffer.timestamp[1] = 0n;
+  buffer._writeIndex = 2;
+};
+
+const writeSpanEndPrimitive: SpanEndPrimitive = (traceRoot, buffer, entryType) => {
+  const entryTypes = buffer.entry_type;
+  if (entryTypes === undefined) throw new TypeError('Split span-end appender requires entry_type storage');
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ES primitive table is only installed on TraceRoot.es instances.
+  buffer.timestamp[1] = nextTimestamp(traceRoot as TraceRoot);
+  entryTypes[1] = entryType;
+  buffer._sealStatsChain();
+};
+
+export class TraceRoot<T extends LogSchema = LogSchema> implements ITraceRoot<T> {
   /**
    * Raw backing buffer containing anchor timestamps and trace_id.
    */
   readonly _system: ArrayBuffer;
+  readonly _traceIdBytes: Uint8Array;
+  readonly trace_id: TraceId;
 
   /**
    * Tracer reference for lifecycle hooks and event callbacks.
    */
-  readonly tracer: TracerLifecycleHooks;
+  readonly tracer: TracerLifecycleHooks<T>;
+  readonly _topology: TraceTopology;
+  readonly _timestampNow = timestampNow;
+  readonly _appendLogEntry = appendLogEntry;
+  readonly _writeSpanStart = writeSpanStartPrimitive;
+  readonly _writeSpanEnd = writeSpanEndPrimitive;
+  readonly _anchorEpochNanos: bigint;
+  readonly _anchorPerformanceNow: number;
+  _lastTimestampNanos = 0n;
 
   /**
    * Cached TypedArray views for fast JS access.
@@ -52,11 +110,16 @@ export class TraceRoot implements ITraceRoot {
   private readonly _epochView: BigInt64Array;
   private readonly _perfView: Float64Array;
 
-  constructor(trace_id: TraceId, anchorEpochNanos: bigint, anchorPerfNow: number, tracer: TracerLifecycleHooks) {
+  constructor(trace_id: TraceId, anchorEpochNanos: bigint, anchorPerfNow: number, tracer: TracerLifecycleHooks<T>) {
     // Allocate buffer: 17 bytes header + trace_id length
     // trace_id is validated to be ASCII (1 byte per char) so length === byte length
     this._system = new ArrayBuffer(TRACE_ROOT_TRACE_ID_OFFSET + trace_id.length);
+    this._traceIdBytes = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, trace_id.length);
+    this.trace_id = trace_id;
     this.tracer = tracer;
+    this._topology = new TraceTopology();
+    this._anchorEpochNanos = anchorEpochNanos;
+    this._anchorPerformanceNow = anchorPerfNow;
 
     // Create cached views (one-time allocation)
     this._epochView = new BigInt64Array(this._system, TRACE_ROOT_ANCHOR_EPOCH_OFFSET, 1);
@@ -66,11 +129,9 @@ export class TraceRoot implements ITraceRoot {
     this._epochView[0] = anchorEpochNanos;
     this._perfView[0] = anchorPerfNow;
 
-    // Encode trace_id directly into buffer (no intermediate allocation)
-    const u8View = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET);
-    const traceIdDest = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, trace_id.length);
-    const { written } = textEncoder.encodeInto(trace_id, traceIdDest);
-    u8View[0] = written;
+    // Encode once into the canonical trace-owned view used by root span identities.
+    const { written } = textEncoder.encodeInto(trace_id, this._traceIdBytes);
+    new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET, 1)[0] = written;
   }
 
   /**
@@ -87,24 +148,13 @@ export class TraceRoot implements ITraceRoot {
     return this._perfView[0];
   }
 
-  /**
-   * Trace ID for this trace.
-   */
-  get trace_id(): TraceId {
-    const len = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET, 1)[0];
-    return createTraceId(textDecoder.decode(new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, len)));
-  }
-
   //#region smoo/lmao!n/trace-root-timestamps #es
   /**
    * Get current timestamp in nanoseconds since Unix epoch.
    * Uses performance.now() - microsecond precision (last 3 digits = 000).
    */
   getTimestampNanos(): Nanoseconds {
-    const elapsedMs = performance.now() - this._perfView[0];
-    // Convert to nanoseconds (last 3 digits = 000 due to microsecond precision)
-    const elapsedNanos = BigInt(Math.floor(elapsedMs * 1000)) * 1000n;
-    return Nanoseconds.unsafe(this._epochView[0] + elapsedNanos);
+    return this._timestampNow(this);
   }
   //#endregion smoo/lmao!n/trace-root-timestamps
 
@@ -114,17 +164,7 @@ export class TraceRoot implements ITraceRoot {
    * Pure JS implementation - writes timestamp, entry_type, message, and sets _writeIndex.
    */
   writeSpanStart(buffer: AnySpanBuffer, spanName: string): void {
-    // Row 0: span-start
-    buffer.timestamp[0] = this.getTimestampNanos();
-    buffer.entry_type[0] = ENTRY_TYPE_SPAN_START;
-    buffer.message(0, spanName);
-
-    // Row 1: pre-initialize as span-exception (will be overwritten on ok/err)
-    buffer.entry_type[1] = ENTRY_TYPE_SPAN_EXCEPTION;
-    buffer.timestamp[1] = 0n;
-
-    // Events start at row 2
-    buffer._writeIndex = 2;
+    this._writeSpanStart(this, buffer, spanName);
   }
 
   /**
@@ -132,8 +172,7 @@ export class TraceRoot implements ITraceRoot {
    * Writes both timestamp and entry_type.
    */
   writeSpanEnd(buffer: AnySpanBuffer, entryType: number): void {
-    buffer.timestamp[1] = this.getTimestampNanos();
-    buffer.entry_type[1] = entryType;
+    this._writeSpanEnd(this, buffer, entryType);
   }
 
   /**
@@ -141,11 +180,7 @@ export class TraceRoot implements ITraceRoot {
    * SpanLogger uses returned idx for string column writes.
    */
   writeLogEntry(buffer: AnySpanBuffer, entryType: number): number {
-    const idx = buffer._writeIndex;
-    buffer.timestamp[idx] = this.getTimestampNanos();
-    buffer.entry_type[idx] = entryType;
-    buffer._writeIndex = idx + 1;
-    return idx;
+    return this._appendLogEntry(this, buffer, entryType);
   }
 }
 
@@ -153,7 +188,7 @@ export class TraceRoot implements ITraceRoot {
  * Factory function for creating browser TraceRoot instances.
  * Pass this to Tracer constructor for browser/ES environments.
  */
-export function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks): TraceRoot {
+export function createTraceRoot<T extends LogSchema>(trace_id: string, tracer: TracerLifecycleHooks<T>): TraceRoot<T> {
   const anchorEpochNanos = BigInt(Date.now()) * 1_000_000n;
   const anchorPerfNow = performance.now();
   return new TraceRoot(createTraceId(trace_id), anchorEpochNanos, anchorPerfNow, tracer);

package/src/lib/traceRoot.node.ts

@@ -10,40 +10,94 @@
  */
 
 import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import type { LogSchema } from './schema/LogSchema.js';
 import { ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_START } from './schema/systemSchema.js';
 import { createTraceId, type TraceId } from './traceId.js';
 import {
   type ITraceRoot,
+  type SpanEndPrimitive,
+  type SpanStartPrimitive,
+  type TimestampAppendPrimitive,
+  type TimestampNowPrimitive,
   TRACE_ROOT_ANCHOR_EPOCH_OFFSET,
   TRACE_ROOT_ANCHOR_PERF_OFFSET,
   TRACE_ROOT_TRACE_ID_LEN_OFFSET,
   TRACE_ROOT_TRACE_ID_OFFSET,
   type TracerLifecycleHooks,
 } from './traceRoot.js';
+import { TraceTopology } from './traceTopology.js';
 import type { AnySpanBuffer } from './types.js';
 
 /** Shared TextEncoder for trace_id encoding (stateless, reusable) */
 const textEncoder = new TextEncoder();
 
-/** Shared TextDecoder for trace_id decoding (stateless, reusable) */
-const textDecoder = new TextDecoder();
-
 //#region smoo/lmao!n/trace-root-timestamps #node
 /**
  * TraceRoot - Node.js implementation.
  *
  * Stores anchor data in _system ArrayBuffer and writes timestamps directly from JS.
  */
-export class TraceRoot implements ITraceRoot {
+function nextTimestamp(root: TraceRoot): Nanoseconds {
+  let timestamp = root._epochHrtimeOffset + process.hrtime.bigint();
+  if (timestamp <= root._lastTimestampNanos) timestamp = root._lastTimestampNanos + 1n;
+  root._lastTimestampNanos = timestamp;
+  return Nanoseconds.unsafe(timestamp);
+}
+
+const timestampNow: TimestampNowPrimitive = (traceRoot) => {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Node primitive table is only installed on TraceRoot.node instances.
+  return nextTimestamp(traceRoot as TraceRoot);
+};
+
+const appendLogEntry: TimestampAppendPrimitive = (traceRoot, buffer, entryType) => {
+  const entryTypes = buffer.entry_type;
+  if (entryTypes === undefined) throw new TypeError('Split timestamp appender requires entry_type storage');
+  const idx = buffer._writeIndex;
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Node primitive table is only installed on TraceRoot.node instances.
+  buffer.timestamp[idx] = nextTimestamp(traceRoot as TraceRoot);
+  entryTypes[idx] = entryType;
+  buffer._writeIndex = idx + 1;
+  return idx;
+};
+
+const writeSpanStartPrimitive: SpanStartPrimitive = (traceRoot, buffer, spanName) => {
+  const entryTypes = buffer.entry_type;
+  if (entryTypes === undefined) throw new TypeError('Split span-start appender requires entry_type storage');
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Node primitive table is only installed on TraceRoot.node instances.
+  buffer.timestamp[0] = nextTimestamp(traceRoot as TraceRoot);
+  entryTypes[0] = ENTRY_TYPE_SPAN_START;
+  if (buffer.message_values) buffer.message(0, spanName);
+  entryTypes[1] = ENTRY_TYPE_SPAN_EXCEPTION;
+  buffer.timestamp[1] = 0n;
+  buffer._writeIndex = 2;
+};
+
+const writeSpanEndPrimitive: SpanEndPrimitive = (traceRoot, buffer, entryType) => {
+  const entryTypes = buffer.entry_type;
+  if (entryTypes === undefined) throw new TypeError('Split span-end appender requires entry_type storage');
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Node primitive table is only installed on TraceRoot.node instances.
+  buffer.timestamp[1] = nextTimestamp(traceRoot as TraceRoot);
+  entryTypes[1] = entryType;
+  buffer._sealStatsChain();
+};
+
+export class TraceRoot<T extends LogSchema = LogSchema> implements ITraceRoot<T> {
   /**
    * Raw backing buffer containing anchor timestamps and trace_id.
    */
   readonly _system: ArrayBuffer;
+  readonly _traceIdBytes: Uint8Array;
+  readonly trace_id: TraceId;
 
   /**
    * Tracer reference for lifecycle hooks and event callbacks.
    */
-  readonly tracer: TracerLifecycleHooks;
+  readonly tracer: TracerLifecycleHooks<T>;
+  readonly _topology: TraceTopology;
+  readonly _timestampNow = timestampNow;
+  readonly _appendLogEntry = appendLogEntry;
+  readonly _writeSpanStart = writeSpanStartPrimitive;
+  readonly _writeSpanEnd = writeSpanEndPrimitive;
 
   /**
    * Cached TypedArray views for fast JS access.
@@ -51,23 +105,24 @@ export class TraceRoot implements ITraceRoot {
   private readonly _epochView: BigInt64Array;
   private readonly _perfView: Float64Array;
 
-  /**
-   * Cached anchor hrtime as the exact BigInt, so the JS timestamp delta stays
-   * correct after the f64 `anchorPerfNow` loses integer precision (~104 days uptime).
-   */
-  private readonly _anchorHrtimeBigInt: bigint;
+  /** Epoch offset makes each exact timestamp one clock read plus one BigInt addition. */
+  readonly _epochHrtimeOffset: bigint;
+  _lastTimestampNanos = 0n;
 
   constructor(
     trace_id: TraceId,
     anchorEpochNanos: bigint,
     anchorPerfNow: number,
     anchorHrtimeBigInt: bigint,
-    tracer: TracerLifecycleHooks,
+    tracer: TracerLifecycleHooks<T>,
   ) {
     // Allocate buffer: 17 bytes header + trace_id length
     // trace_id is validated to be ASCII (1 byte per char) so length === byte length
     this._system = new ArrayBuffer(TRACE_ROOT_TRACE_ID_OFFSET + trace_id.length);
+    this._traceIdBytes = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, trace_id.length);
+    this.trace_id = trace_id;
     this.tracer = tracer;
+    this._topology = new TraceTopology();
 
     // Create cached views (one-time allocation)
     this._epochView = new BigInt64Array(this._system, TRACE_ROOT_ANCHOR_EPOCH_OFFSET, 1);
@@ -77,14 +132,11 @@ export class TraceRoot implements ITraceRoot {
     this._epochView[0] = anchorEpochNanos;
     this._perfView[0] = anchorPerfNow;
 
-    // Keep exact monotonic anchor for JS fallback (avoid Number precision loss after ~104 days uptime)
-    this._anchorHrtimeBigInt = anchorHrtimeBigInt;
+    this._epochHrtimeOffset = anchorEpochNanos - anchorHrtimeBigInt;
 
-    // Encode trace_id directly into buffer (no intermediate allocation)
-    const u8View = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET);
-    const traceIdDest = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, trace_id.length);
-    const { written } = textEncoder.encodeInto(trace_id, traceIdDest);
-    u8View[0] = written;
+    // Encode once into the canonical trace-owned view used by root span identities.
+    const { written } = textEncoder.encodeInto(trace_id, this._traceIdBytes);
+    new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET, 1)[0] = written;
   }
 
   /**
@@ -101,22 +153,12 @@ export class TraceRoot implements ITraceRoot {
     return this._perfView[0];
   }
 
-  /**
-   * Trace ID for this trace.
-   */
-  get trace_id(): TraceId {
-    const len = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET, 1)[0];
-    return createTraceId(textDecoder.decode(new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, len)));
-  }
-
   /**
    * Get current timestamp in nanoseconds since Unix epoch.
    * Uses process.hrtime.bigint() for true nanosecond precision.
    */
   getTimestampNanos(): Nanoseconds {
-    const currentHrtime = process.hrtime.bigint();
-    const elapsedNanos = currentHrtime - this._anchorHrtimeBigInt;
-    return Nanoseconds.unsafe(this._epochView[0] + elapsedNanos);
+    return this._timestampNow(this);
   }
 
   /**
@@ -124,15 +166,7 @@ export class TraceRoot implements ITraceRoot {
    *
    */
   writeSpanStart(buffer: AnySpanBuffer, spanName: string): void {
-    buffer.timestamp[0] = this.getTimestampNanos();
-    buffer.entry_type[0] = ENTRY_TYPE_SPAN_START;
-    buffer.message(0, spanName);
-
-    // Pre-initialize row 1 as span-exception
-    buffer.entry_type[1] = ENTRY_TYPE_SPAN_EXCEPTION;
-    buffer.timestamp[1] = 0n;
-
-    buffer._writeIndex = 2;
+    this._writeSpanStart(this, buffer, spanName);
   }
 
   /**
@@ -141,8 +175,7 @@ export class TraceRoot implements ITraceRoot {
    *
    */
   writeSpanEnd(buffer: AnySpanBuffer, entryType: number): void {
-    buffer.timestamp[1] = this.getTimestampNanos();
-    buffer.entry_type[1] = entryType;
+    this._writeSpanEnd(this, buffer, entryType);
   }
 
   /**
@@ -150,11 +183,7 @@ export class TraceRoot implements ITraceRoot {
    * SpanLogger uses returned idx for string column writes.
    */
   writeLogEntry(buffer: AnySpanBuffer, entryType: number): number {
-    const idx = buffer._writeIndex;
-    buffer.timestamp[idx] = this.getTimestampNanos();
-    buffer.entry_type[idx] = entryType;
-    buffer._writeIndex = idx + 1;
-    return idx;
+    return this._appendLogEntry(this, buffer, entryType);
   }
 }
 
@@ -162,7 +191,7 @@ export class TraceRoot implements ITraceRoot {
  * Factory function for creating Node.js TraceRoot instances.
  * Pass this to Tracer constructor for Node.js environments.
  */
-export function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks): TraceRoot {
+export function createTraceRoot<T extends LogSchema>(trace_id: string, tracer: TracerLifecycleHooks<T>): TraceRoot<T> {
   const anchorEpochNanos = BigInt(Date.now()) * 1_000_000n;
   const anchorHrtimeBigInt = process.hrtime.bigint();
   // Also store as f64 in the shared _system layout (WASM reads it without BigInt extraction)

package/src/lib/traceRoot.ts

@@ -14,39 +14,46 @@
  */
 
 import type { Nanoseconds } from '@smoothbricks/arrow-builder';
+import type { BufferStrategy } from './bufferStrategy.js';
+import type { LogSchema } from './schema/LogSchema.js';
+import type { TraceTopology } from './traceTopology.js';
 import type { AnySpanBuffer } from './types.js';
 
 export type { SpanIdentity, TraceId } from './traceId.js';
 // Re-export TraceId types from traceId.ts
 export { createTraceId, extractSpanIdentity, generateTraceId, isValidTraceId, MAX_TRACE_ID_LENGTH } from './traceId.js';
 
+/**
+ * Consume the one-shot marker set when a WASM allocation export already
+ * initialized the system lifecycle rows. Message storage is still populated
+ * by the selected physical appender after this returns.
+ */
+export function consumeSpanStartedAtAllocation(buffer: AnySpanBuffer): boolean {
+  if (buffer._spanStartedAtAllocation !== true) return false;
+  buffer._spanStartedAtAllocation = false;
+  return true;
+}
+
 /**
  * Tracer lifecycle hooks interface.
  * Extracted to avoid circular dependency - Tracer implements this.
  */
 //#region smoo/lmao!n/buffer-tuning-observability
-export interface TracerLifecycleHooks {
+export interface TracerLifecycleHooks<T extends LogSchema = LogSchema> {
   onTraceStart(buffer: unknown): void;
   onTraceEnd(buffer: unknown): void;
   onSpanStart(buffer: unknown): void;
   onSpanEnd(buffer: unknown): void;
   onStatsWillResetFor(buffer: unknown): void;
+  /** Internal evaluator source used when a specialized parent omits the public ff slot. */
+  getFlagEvaluatorForContext(): unknown;
 
   /**
    * Buffer strategy for creating child and overflow buffers.
    * SpanContext uses this to create child spans with the correct strategy (JS or WASM).
    * Note: Caller must call writeSpanStart() after createChildSpanBuffer() to set span name.
    */
-  readonly bufferStrategy: {
-    createChildSpanBuffer(
-      parentBuffer: AnySpanBuffer,
-      callsiteMetadata: unknown,
-      opMetadata: unknown,
-      capacity?: number,
-      schema?: unknown,
-    ): AnySpanBuffer;
-    createOverflowBuffer(buffer: AnySpanBuffer): AnySpanBuffer;
-  };
+  readonly bufferStrategy: BufferStrategy<T>;
 }
 //#endregion smoo/lmao!n/buffer-tuning-observability
 
@@ -82,19 +89,33 @@ export const TRACE_ROOT_TRACE_ID_OFFSET = 17;
  *
  * The factory creates anchor timestamps internally using platform-specific APIs.
  */
-export type TraceRootFactory = (trace_id: string, tracer: TracerLifecycleHooks) => ITraceRoot;
+export type TraceRootFactory<T extends LogSchema = LogSchema> = (
+  trace_id: string,
+  tracer: TracerLifecycleHooks<T>,
+) => ITraceRoot<T>;
 
-export interface ITraceRoot {
+/** Platform-fixed primitives copied into the physical plan/generated writer hot path. */
+export type TimestampNowPrimitive = (traceRoot: ITraceRoot) => Nanoseconds;
+export type TimestampAppendPrimitive = (traceRoot: ITraceRoot, buffer: AnySpanBuffer, entryType: number) => number;
+export type SpanStartPrimitive = (traceRoot: ITraceRoot, buffer: AnySpanBuffer, spanName: string) => void;
+export type SpanEndPrimitive = (traceRoot: ITraceRoot, buffer: AnySpanBuffer, entryType: number) => void;
+
+export interface ITraceRoot<T extends LogSchema = LogSchema> {
   /**
    * Raw backing buffer containing anchor timestamps and trace_id.
    * The WASM path can read this directly without BigInt extraction.
    */
   readonly _system: ArrayBuffer;
+  /** Canonical immutable UTF-8 trace ID bytes, shared by span identity construction. */
+  readonly _traceIdBytes: Uint8Array;
 
   /**
    * Tracer reference for lifecycle hooks and event callbacks.
    */
-  readonly tracer: TracerLifecycleHooks;
+  readonly tracer: TracerLifecycleHooks<T>;
+
+  /** Trace-owned arena for logical span topology. */
+  readonly _topology: TraceTopology;
 
   /**
    * Trace ID for this trace.
@@ -114,6 +135,12 @@ export interface ITraceRoot {
    */
   readonly anchorPerfNow: number;
 
+  /** Monomorphic platform implementations cached by plans and generated writers. */
+  readonly _timestampNow: TimestampNowPrimitive;
+  readonly _appendLogEntry: TimestampAppendPrimitive;
+  readonly _writeSpanStart: SpanStartPrimitive;
+  readonly _writeSpanEnd: SpanEndPrimitive;
+
   /**
    * Get current timestamp in nanoseconds since Unix epoch.
    * Platform-specific implementation.