@smoothbricks/lmao 0.1.3 → 0.2.0

package/src/lib/cloudflare/diagnosticDrain.ts

@@ -0,0 +1,152 @@
+/**
+ * Diagnostic-class drain adapter.
+ *
+ * Per specs/lmao/01u_cloudflare_trace_segments.md §LMAO Sink Fit: no new abstraction — the base
+ * Tracer lifecycle (onTraceEnd queueing + flush) already models this. The drain tracer extends
+ * ArrayQueueTracer; flush() drains completed root buffers, flattens them to rows, and hands them
+ * to a constructor-injected transport.
+ *
+ * Transports (per 01u §Collection Lanes and Fallbacks):
+ * - primary: a Pipelines-stream-binding-shaped send fn (`env.TRACE_STREAM.send(rows)`) — rows,
+ *   because Pipelines owns batching and Parquet encoding for the raw tier
+ * - fallback: Cloudflare Queues — batched TraceChunkEnvelope messages built from the existing
+ *   lib/archive primitives (chunk_id idempotency); NEVER per-span messages (128 KB messages,
+ *   per-64 KB op billing make per-span ~160x more expensive)
+ *
+ * Delivery is fire-and-forget: flush() is scheduled via ctx.waitUntil and never rejects; enqueue
+ * failures surface through the onSendError hook (01s §Failure Handling — emit metrics, rely on
+ * queue policy/backoff), they never block.
+ */
+
+import { buildTraceChunkEnvelope, type TraceChunkEnvelope } from '../archive/chunkEnvelope.js';
+import type { OpContextBinding } from '../opContext/types.js';
+import type { TracerOptions } from '../tracer.js';
+import { ArrayQueueTracer } from '../tracers/ArrayQueueTracer.js';
+import { spanBufferToTraceRows, type TraceRow } from './traceRows.js';
+
+/** Shape of a Cloudflare Pipelines stream binding's send — promise resolves on confirmed ingest. */
+export type PipelinesStreamSend = (rows: TraceRow[]) => Promise<void>;
+
+/** Diagnostic-lane transport seam: delivers one drained batch of rows, at most best-effort. */
+export interface DiagnosticTransport {
+  send(rows: readonly TraceRow[]): Promise<void>;
+}
+
+/** Primary diagnostic transport: rows straight into the injected Pipelines stream binding. */
+export class PipelinesStreamTransport implements DiagnosticTransport {
+  constructor(private readonly sendToStream: PipelinesStreamSend) {}
+
+  send(rows: readonly TraceRow[]): Promise<void> {
+    // The binding signature takes a mutable array of records.
+    return this.sendToStream([...rows]);
+  }
+}
+
+/** One Queues-fallback message: chunk envelope (idempotency + routing metadata) plus its rows. */
+export interface TraceChunkQueueMessage {
+  readonly envelope: TraceChunkEnvelope;
+  readonly rows: readonly TraceRow[];
+}
+
+export interface QueuesFallbackOptions {
+  /** Logical file reference recorded in the envelopes, e.g. 'queue://worker-name'. */
+  fileRef: string;
+  /** Max rows per queue message — bounds message size under the 128 KB Queues limit. */
+  maxRowsPerMessage: number;
+  /** Injected queue producer, e.g. (msg) => env.TRACE_QUEUE.send(msg). */
+  sendMessage: (message: TraceChunkQueueMessage) => Promise<void>;
+}
+
+function fnv1a32Hex(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+function timestampBoundsMs(rows: readonly TraceRow[]): { startedAtMs: number; endedAtMs: number } {
+  let minNs = Number.POSITIVE_INFINITY;
+  let maxNs = Number.NEGATIVE_INFINITY;
+  for (const row of rows) {
+    const ts = row.timestamp_ns;
+    if (typeof ts !== 'number') continue;
+    if (ts < minNs) minNs = ts;
+    if (ts > maxNs) maxNs = ts;
+  }
+  if (minNs === Number.POSITIVE_INFINITY) return { startedAtMs: 0, endedAtMs: 0 };
+  return { startedAtMs: Math.floor(minNs / 1_000_000), endedAtMs: Math.floor(maxNs / 1_000_000) };
+}
+
+/**
+ * Queues-fallback transport: rows are batched into chunk-envelope messages.
+ *
+ * The chunk_ref is a deterministic content hash of the batch, so a retried send of the same
+ * batch produces the same chunk_id and the consumer's chunk_id dedup makes redelivery a no-op.
+ */
+export class QueuesFallbackTransport implements DiagnosticTransport {
+  constructor(private readonly options: QueuesFallbackOptions) {
+    if (options.maxRowsPerMessage < 1) {
+      throw new Error('QueuesFallbackTransport: maxRowsPerMessage must be >= 1');
+    }
+  }
+
+  async send(rows: readonly TraceRow[]): Promise<void> {
+    const { fileRef, maxRowsPerMessage, sendMessage } = this.options;
+    for (let offset = 0; offset < rows.length; offset += maxRowsPerMessage) {
+      const batch = rows.slice(offset, offset + maxRowsPerMessage);
+      const { startedAtMs, endedAtMs } = timestampBoundsMs(batch);
+      const envelope = buildTraceChunkEnvelope({
+        file_ref: fileRef,
+        chunk_ref: `rows_${fnv1a32Hex(JSON.stringify(batch))}`,
+        row_count: batch.length,
+        started_at_ms: startedAtMs,
+        ended_at_ms: endedAtMs,
+      });
+      await sendMessage({ envelope, rows: batch });
+    }
+  }
+}
+
+export interface DiagnosticDrainOptions<
+  T extends import('../schema/LogSchema.js').LogSchema = import('../schema/LogSchema.js').LogSchema,
+> extends TracerOptions<T> {
+  transport: DiagnosticTransport;
+  /** Failure hook (01s §Failure Handling): emit runtime metrics/alerts here; never rethrows. */
+  onSendError?: (error: unknown, rows: readonly TraceRow[]) => void;
+}
+
+/**
+ * Diagnostic-lane sink tracer: queue completed roots (ArrayQueueTracer), drain + send on flush().
+ *
+ * flush() is waitUntil-schedulable: it never rejects, and buffers are always released back to
+ * the strategy regardless of transport outcome.
+ */
+export class DiagnosticDrainTracer<B extends OpContextBinding = OpContextBinding> extends ArrayQueueTracer<B> {
+  private readonly transport: DiagnosticTransport;
+  private readonly onSendError: ((error: unknown, rows: readonly TraceRow[]) => void) | undefined;
+
+  constructor(binding: B, options: DiagnosticDrainOptions<B['logBinding']['logSchema']>) {
+    super(binding, options);
+    this.transport = options.transport;
+    this.onSendError = options.onSendError;
+  }
+
+  override async flush(): Promise<void> {
+    const buffers = this.drain();
+    for (const buffer of buffers) {
+      let rows: TraceRow[];
+      try {
+        rows = spanBufferToTraceRows(buffer);
+      } finally {
+        this.bufferStrategy.releaseBuffer(buffer);
+      }
+      try {
+        await this.transport.send(rows);
+      } catch (error) {
+        this.onSendError?.(error, rows);
+      }
+    }
+  }
+}

package/src/lib/cloudflare/traceRows.ts

@@ -0,0 +1,60 @@
+/**
+ * Trace-row conversion for the Cloudflare sink lanes.
+ *
+ * Per specs/lmao/01u_cloudflare_trace_segments.md §Collection Lanes: spans are sent as ROWS
+ * (JSON-serializable records), not pre-built Arrow chunks — Pipelines owns batching and Parquet
+ * encoding for the raw tier, and the collector DO reduces the same flat row shape.
+ *
+ * The row shape mirrors the SQLite `spans` table (01a schema system): system columns
+ * (trace_id, span_id, parent_span_id, row_index, entry_type, timestamp_ns, message) plus the
+ * buffer's user schema columns, flattened so downstream SQL transforms need no unnesting.
+ */
+
+import { readSpanFieldValue, walkSpanSegments } from '../sqlite/sqlite-common.js';
+import type { AnySpanBuffer } from '../types.js';
+
+/** JSON-serializable scalar — the only value kinds a trace row may carry across the sink boundary. */
+export type TraceRowValue = string | number | boolean | null;
+
+/** One flat, JSON-serializable trace record — the payload unit of both delivery lanes. */
+export type TraceRow = Record<string, TraceRowValue>;
+
+function toTraceRowValue(value: unknown): TraceRowValue {
+  if (value === undefined || value === null) return null;
+  switch (typeof value) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+      return value;
+    case 'bigint':
+      return Number(value);
+    default:
+      // Non-scalar buffer values (binary payloads etc.) have no JSON row representation.
+      return null;
+  }
+}
+
+/** Flatten a completed root span-buffer tree into JSON-serializable trace rows. */
+export function spanBufferToTraceRows(rootBuffer: AnySpanBuffer): TraceRow[] {
+  const rows: TraceRow[] = [];
+  for (const segment of walkSpanSegments(rootBuffer)) {
+    const { buffer, traceId, spanId, parentSpanId, rowOffset } = segment;
+    const fieldNames = buffer._logSchema._columnNames;
+    for (let row = 0; row < buffer._writeIndex; row++) {
+      const record: TraceRow = {
+        trace_id: traceId,
+        span_id: spanId,
+        parent_span_id: parentSpanId,
+        row_index: rowOffset + row,
+        entry_type: buffer.entry_type[row],
+        timestamp_ns: Number(buffer.timestamp[row]),
+        message: buffer.message_values[row] ?? null,
+      };
+      for (const fieldName of fieldNames) {
+        record[fieldName] = toTraceRowValue(readSpanFieldValue(buffer, fieldName, row));
+      }
+      rows.push(record);
+    }
+  }
+  return rows;
+}

package/src/lib/codegen/__tests__/fixedPositionWriter-uint64.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Behavioral tests for the fluent `uint64_value(value)` writer on TagWriter (row 0)
+ * and ResultWriter (row 1).
+ *
+ * `uint64_value` is a RESERVED system column (systemSchema), stored as a LAZY
+ * BigUint64Array multiplexed by row. Both writers route through the buffer's own
+ * lazy setter `buffer.uint64_value(pos, val)`, which allocates-then-writes and
+ * flips the Arrow null bit (1 = valid, 0 = null).
+ *
+ * These tests defend the observable contract:
+ *  - the value lands at the writer's fixed row (0 for tag, 1 for result),
+ *  - the null bit is set for a written value and cleared for `null`,
+ *  - rows 0 and 1 hold INDEPENDENT values (the load-bearing no-collision invariant,
+ *    since span lifecycle writes never touch `uint64_value`),
+ *  - allocation is lazy, chaining returns the writer, call order is irrelevant,
+ *  - and large near-2^64 bigints round-trip without precision loss while `0n`
+ *    is a distinct non-null zero (not "absent").
+ *
+ * `packages/lmao` is exempt from the traced-suite requirement, so this is a plain
+ * bun:test file (matches ../../__tests__/arrow-builder-integration/lazy-columns.test.ts).
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { createResultWriter, createTagWriter, ENTRY_TYPE_SPAN_OK, ENTRY_TYPE_SPAN_START, S } from '@smoothbricks/lmao';
+import { createTestOpMetadata, createTestSchema, createTestTraceRoot } from '../../__tests__/test-helpers.js';
+import { createSpanBuffer } from '../../spanBuffer.js';
+import type { AnySpanBuffer } from '../../types.js';
+
+// ---------------------------------------------------------------------------
+// Fixtures & readers
+// ---------------------------------------------------------------------------
+
+// Schema carries sibling user columns (batchId/count) so tests can prove that
+// `uint64_value` neither interferes with nor is clobbered by other columns.
+// One schema instance is shared between the buffer and its writers so their
+// column sets are guaranteed identical.
+function setup() {
+  const schema = createTestSchema({ batchId: S.category(), count: S.number() });
+  const buffer = createSpanBuffer(schema, createTestTraceRoot('t'), createTestOpMetadata(), 8);
+  return { schema, buffer };
+}
+
+// Read the allocated `uint64_value` values, narrowed to BigUint64Array.
+// Uses getColumnIfAllocated so it never triggers allocation as a side effect.
+function uint64Column(buffer: AnySpanBuffer): BigUint64Array {
+  const col = buffer.getColumnIfAllocated('uint64_value');
+  if (!(col instanceof BigUint64Array)) {
+    throw new Error('uint64_value column was not allocated as a BigUint64Array');
+  }
+  return col;
+}
+
+function uint64Nulls(buffer: AnySpanBuffer): Uint8Array {
+  const nulls = buffer.getNullsIfAllocated('uint64_value');
+  if (!(nulls instanceof Uint8Array)) {
+    throw new Error('uint64_value null bitmap was not allocated');
+  }
+  return nulls;
+}
+
+// Arrow null bitmap: bit set (1) => valid/non-null; bit clear (0) => null/absent.
+// Named because the bit-extraction formula is not self-explanatory inline and is
+// asserted at many call sites in lockstep.
+function isNonNull(nulls: Uint8Array, pos: number): boolean {
+  return (nulls[pos >>> 3] & (1 << (pos & 7))) !== 0;
+}
+
+// Invoke a writer's uint64_value at runtime with a value TypeScript would reject
+// (null), to exercise the setter's null-clearing branch without an unsafe `as` cast
+// (the repo's eslint bans no-unsafe-type-assertion). Mirrors the Reflect pattern in
+// arrow-builder's columnBufferSetters.test.ts.
+function writeUint64Runtime(writer: object, value: bigint | null): void {
+  const method = Reflect.get(writer, 'uint64_value');
+  if (typeof method !== 'function') {
+    throw new Error('writer is missing a uint64_value method');
+  }
+  Reflect.apply(method, writer, [value]);
+}
+
+// ---------------------------------------------------------------------------
+// Row placement
+// ---------------------------------------------------------------------------
+
+describe('uint64_value row placement', () => {
+  it('TagWriter writes to row 0 (span-start)', () => {
+    const { schema, buffer } = setup();
+
+    createTagWriter(schema, buffer).uint64_value(123n);
+
+    const values = uint64Column(buffer);
+    const nulls = uint64Nulls(buffer);
+    expect(values[0]).toBe(123n);
+    expect(isNonNull(nulls, 0)).toBe(true);
+    // Row 1 must be untouched by a tag write.
+    expect(isNonNull(nulls, 1)).toBe(false);
+  });
+
+  it('ResultWriter writes to row 1 (span-completion)', () => {
+    const { schema, buffer } = setup();
+
+    createResultWriter(schema, buffer, { ok: true }, false).uint64_value(456n);
+
+    const values = uint64Column(buffer);
+    const nulls = uint64Nulls(buffer);
+    expect(values[1]).toBe(456n);
+    expect(isNonNull(nulls, 1)).toBe(true);
+    // Row 0 must be untouched by a result write.
+    expect(isNonNull(nulls, 0)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The load-bearing invariant: rows 0 and 1 never collide
+// ---------------------------------------------------------------------------
+
+describe('uint64_value cross-row independence (no collision)', () => {
+  it('tag row 0 and result row 1 hold distinct values on one buffer', () => {
+    const { schema, buffer } = setup();
+    const rowZero = 111n;
+    const rowOne = 222n;
+
+    createTagWriter(schema, buffer).uint64_value(rowZero);
+    createResultWriter(schema, buffer, { ok: true }, false).uint64_value(rowOne);
+
+    const values = uint64Column(buffer);
+    const nulls = uint64Nulls(buffer);
+    // Neither write overwrote the other.
+    expect(values[0]).toBe(rowZero);
+    expect(values[1]).toBe(rowOne);
+    expect(isNonNull(nulls, 0)).toBe(true);
+    expect(isNonNull(nulls, 1)).toBe(true);
+  });
+
+  it('is order-independent: result-first then tag yields the same layout', () => {
+    const { schema, buffer } = setup();
+    const rowZero = 333n;
+    const rowOne = 444n;
+
+    // Reverse the write order relative to the previous case.
+    createResultWriter(schema, buffer, { ok: true }, false).uint64_value(rowOne);
+    createTagWriter(schema, buffer).uint64_value(rowZero);
+
+    const values = uint64Column(buffer);
+    expect(values[0]).toBe(rowZero);
+    expect(values[1]).toBe(rowOne);
+  });
+
+  it('survives the span lifecycle: writeSpanStart/writeSpanEnd never touch uint64_value', () => {
+    const { schema, buffer } = setup();
+    const rowZero = 900n;
+    const rowOne = 901n;
+
+    const tag = createTagWriter(schema, buffer);
+    const result = createResultWriter(schema, buffer, { ok: true }, false);
+
+    // Reproduce the production sequence: lifecycle start, user tags, user result, lifecycle end.
+    buffer._traceRoot.writeSpanStart(buffer, 'lifecycle-span');
+    tag.uint64_value(rowZero);
+    result.uint64_value(rowOne);
+    buffer._traceRoot.writeSpanEnd(buffer, ENTRY_TYPE_SPAN_OK);
+
+    // The lifecycle actually ran and wrote its OWN columns (entry_type)...
+    expect(buffer.entry_type[0]).toBe(ENTRY_TYPE_SPAN_START);
+    expect(buffer.entry_type[1]).toBe(ENTRY_TYPE_SPAN_OK);
+    // ...without clobbering the user uint64 values in either row.
+    const values = uint64Column(buffer);
+    const nulls = uint64Nulls(buffer);
+    expect(values[0]).toBe(rowZero);
+    expect(values[1]).toBe(rowOne);
+    expect(isNonNull(nulls, 0)).toBe(true);
+    expect(isNonNull(nulls, 1)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Lazy allocation
+// ---------------------------------------------------------------------------
+
+describe('uint64_value lazy allocation', () => {
+  it('is unallocated until first write, then allocated', () => {
+    const { schema, buffer } = setup();
+
+    expect(buffer.getColumnIfAllocated('uint64_value')).toBeUndefined();
+    expect(buffer.getNullsIfAllocated('uint64_value')).toBeUndefined();
+
+    createTagWriter(schema, buffer).uint64_value(7n);
+
+    expect(buffer.getColumnIfAllocated('uint64_value')).toBeDefined();
+    expect(uint64Column(buffer)[0]).toBe(7n);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Chaining & call-order independence with a sibling column
+// ---------------------------------------------------------------------------
+
+describe('uint64_value chaining and sibling non-interference', () => {
+  it('returns the writer for chaining', () => {
+    const { schema, buffer } = setup();
+    const tag = createTagWriter(schema, buffer);
+    expect(tag.uint64_value(1n)).toBe(tag);
+  });
+
+  it('batchId(...).uint64_value(...) lands both values', () => {
+    const { schema, buffer } = setup();
+
+    createTagWriter(schema, buffer).batchId('batch-A').uint64_value(10n);
+
+    expect(uint64Column(buffer)[0]).toBe(10n);
+    const batch = buffer.getColumnIfAllocated('batchId');
+    if (!Array.isArray(batch)) {
+      throw new Error('batchId column was not allocated as an array');
+    }
+    expect(batch[0]).toBe('batch-A');
+  });
+
+  it('uint64_value(...).batchId(...) lands both values (reverse order)', () => {
+    const { schema, buffer } = setup();
+
+    createTagWriter(schema, buffer).uint64_value(20n).batchId('batch-B');
+
+    expect(uint64Column(buffer)[0]).toBe(20n);
+    const batch = buffer.getColumnIfAllocated('batchId');
+    if (!Array.isArray(batch)) {
+      throw new Error('batchId column was not allocated as an array');
+    }
+    expect(batch[0]).toBe('batch-B');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// null clears the null bit
+// ---------------------------------------------------------------------------
+
+describe('uint64_value null handling', () => {
+  it('writing null clears the null bit (value marked absent), not sets it', () => {
+    const { schema, buffer } = setup();
+    const tag = createTagWriter(schema, buffer);
+
+    // First set a real value so the null bit is on...
+    tag.uint64_value(99n);
+    expect(isNonNull(uint64Nulls(buffer), 0)).toBe(true);
+
+    // ...then clear it via the runtime null path.
+    writeUint64Runtime(tag, null);
+    expect(isNonNull(uint64Nulls(buffer), 0)).toBe(false);
+  });
+
+  it('null at row 1 clears row 1 only, leaving a non-null row 0 intact', () => {
+    const { schema, buffer } = setup();
+    const tag = createTagWriter(schema, buffer);
+    const result = createResultWriter(schema, buffer, { ok: true }, false);
+
+    tag.uint64_value(5n);
+    result.uint64_value(6n);
+    expect(isNonNull(uint64Nulls(buffer), 0)).toBe(true);
+    expect(isNonNull(uint64Nulls(buffer), 1)).toBe(true);
+
+    writeUint64Runtime(result, null);
+
+    const nulls = uint64Nulls(buffer);
+    expect(isNonNull(nulls, 1)).toBe(false); // row 1 cleared
+    expect(isNonNull(nulls, 0)).toBe(true); // row 0 untouched
+    expect(uint64Column(buffer)[0]).toBe(5n);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Boundary values
+// ---------------------------------------------------------------------------
+
+describe('uint64_value boundary values', () => {
+  const cases: ReadonlyArray<{ name: string; value: bigint }> = [
+    { name: 'max uint64 (2^64 - 1)', value: 2n ** 64n - 1n },
+    { name: 'one below max', value: 2n ** 64n - 2n },
+    { name: '2^63 (above JS safe-integer precision)', value: 2n ** 63n },
+    { name: '2^53 + 1 (first value not exactly representable as a JS number)', value: 2n ** 53n + 1n },
+    { name: 'one', value: 1n },
+  ];
+
+  for (const { name, value } of cases) {
+    it(`round-trips ${name} exactly`, () => {
+      const { schema, buffer } = setup();
+      createTagWriter(schema, buffer).uint64_value(value);
+
+      const values = uint64Column(buffer);
+      expect(values[0]).toBe(value);
+      expect(isNonNull(uint64Nulls(buffer), 0)).toBe(true);
+    });
+  }
+
+  it('stores 0n as a non-null zero, distinct from absent', () => {
+    const { schema, buffer } = setup();
+    createTagWriter(schema, buffer).uint64_value(0n);
+
+    const values = uint64Column(buffer);
+    const nulls = uint64Nulls(buffer);
+    expect(values[0]).toBe(0n);
+    // The crux: 0n is a written value, so the null bit MUST be set (non-null),
+    // distinguishing an explicit zero from an unwritten/absent row (row 1 here).
+    expect(isNonNull(nulls, 0)).toBe(true);
+    expect(isNonNull(nulls, 1)).toBe(false);
+  });
+});

package/src/lib/codegen/evaluatorGenerator.ts

@@ -1,3 +1,4 @@
+//#region smoo/lmao!n/flag-evaluator-generator
 /**
  * Worker-safe feature-flag evaluator generation.
  *
@@ -307,3 +308,4 @@ export function createEvaluatorClass<Ctx extends OpContext>(
 
   return generatedEvaluatorClass;
 }
+//#endregion smoo/lmao!n/flag-evaluator-generator

package/src/lib/codegen/fixedPositionWriterGenerator.ts

@@ -55,6 +55,10 @@ export type TagWriter<T extends LogSchema> = {
    * Bulk set multiple attributes at once.
    */
   with(attributes: Partial<InferSchema<T>>): TagWriter<T>;
+  /**
+   * Set the reserved `uint64_value` column for this span-start row.
+   */
+  uint64_value(value: bigint): TagWriter<T>;
 } & {
   /**
    * Individual attribute setters - each returns `this` for chaining.
@@ -97,6 +101,10 @@ export type ResultWriter<T extends LogSchema, R = unknown, E = unknown> = {
    * Set the result-row source line (row 1).
    */
   line(lineNumber: number): ResultWriter<T, R, E>;
+  /**
+   * Set the reserved `uint64_value` column for this result row.
+   */
+  uint64_value(value: bigint): ResultWriter<T, R, E>;
 } & {
   /**
    * Individual attribute setters - each returns `this` for chaining.
@@ -183,6 +191,7 @@ function generateWithMethod(schemaFields: readonly ColumnEntry[], enumFieldNames
     }`;
 }
 
+//#region smoo/lmao!n/codegen-architecture
 /**
  * Generate the complete fixed-position writer class code.
  *
@@ -295,12 +304,24 @@ const resultWriterClassCache = new WeakMap<LogSchema, unknown>();
 // TagWriter API
 // ============================================================================
 
+/**
+ * TagWriter extension - adds the reserved system `uint64_value` writer (row 0).
+ */
+const tagWriterExtension: FixedPositionWriterExtension = {
+  methods: `
+uint64_value(value) {
+  this._buffer.uint64_value(this._pos, value);
+  return this;
+}
+`,
+};
+
 /**
  * Generate TagWriter class code for a schema.
  * TagWriter writes to position 0 (span-start row).
  */
 export function generateTagWriterClass(schema: LogSchema): string {
-  return generateFixedPositionWriterClass(schema, 0, 'GeneratedTagWriter');
+  return generateFixedPositionWriterClass(schema, 0, 'GeneratedTagWriter', tagWriterExtension);
 }
 
 /**
@@ -377,6 +398,11 @@ line(lineNumber) {
   this._buffer.line(this._pos, lineNumber);
   return this;
 }
+
+uint64_value(value) {
+  this._buffer.uint64_value(this._pos, value);
+  return this;
+}
 `,
 };
 
@@ -442,3 +468,4 @@ export function createResultWriter<T extends LogSchema, R = unknown, E = unknown
   const WriterClass = getResultWriterClass(schema);
   return new WriterClass(buffer, resultOrError, isError);
 }
+//#endregion smoo/lmao!n/codegen-architecture

package/src/lib/codegen/spanLoggerGenerator.ts

@@ -261,6 +261,7 @@ function generateEnumFluentSetters(enumFieldNames: Set<string>): string {
   return setters.join('\n');
 }
 
+//#region smoo/lmao!n/codegen-spanlogger.scope
 /**
  * Generate _setScope() method code - IMMUTABLE scope semantics
  *
@@ -365,7 +366,9 @@ function generatePrefillScopedAttributesMethod(
       ${columnFills.join('\n')}
     }`;
 }
+//#endregion smoo/lmao!n/codegen-spanlogger.scope
 
+//#region smoo/lmao!n/codegen-spanlogger
 /**
  * Build the extension for SpanLogger that extends ColumnWriter
  */
@@ -713,3 +716,4 @@ export function createSpanLogger<T extends LogSchema>(schema: T, buffer: SpanBuf
   const SpanLoggerClass = createSpanLoggerClass(schema);
   return new SpanLoggerClass(buffer);
 }
+//#endregion smoo/lmao!n/codegen-spanlogger

package/src/lib/convertToArrow.ts

@@ -186,6 +186,11 @@ function getAllocatedBinaryColumn(buffer: AnySpanBuffer, columnName: string): un
   return Array.isArray(column) ? column : undefined;
 }
 
+//#region smoo/lmao!n/scope-attributes.arrow-fill
+// Cold-path scope materialization (01i): scope values fill NULL cells (no direct write) at
+// Arrow conversion. These typed readers pull from the buffer's immutable _scopeValues; the
+// per-column fill loops below call them so a row with a direct write keeps its value and scope
+// only fills the gaps.
 function getStringScopeValue(buffer: AnySpanBuffer, fieldName: string): string | undefined {
   const value = buffer._scopeValues?.[fieldName];
   return typeof value === 'string' ? value : undefined;
@@ -200,6 +205,7 @@ function getBooleanScopeValue(buffer: AnySpanBuffer, fieldName: string): boolean
   const value = buffer._scopeValues?.[fieldName];
   return typeof value === 'boolean' ? value : undefined;
 }
+//#endregion smoo/lmao!n/scope-attributes.arrow-fill
 
 function requireUint8Array(value: unknown, message: string): Uint8Array {
   if (!(value instanceof Uint8Array)) {