@smoothbricks/lmao 0.1.0

package/src/lib/__tests__/test-helpers.ts

@@ -0,0 +1,318 @@
+/**
+ * Test helpers for creating test buffers using the new Op-centric API.
+ *
+ * These helpers create LogBinding instances and SpanBuffers for testing
+ * without requiring full Op/trace context setup.
+ */
+
+import { DEFAULT_BUFFER_CAPACITY } from '@smoothbricks/arrow-builder';
+import { createSpanLogger, type SpanLoggerImpl } from '../codegen/spanLoggerGenerator.js';
+import { defineOpContext } from '../defineOpContext.js';
+import { JsBufferStrategy } from '../JsBufferStrategy.js';
+import { createOpMetadata, DEFAULT_METADATA } from '../opContext/defineOp.js';
+import type {
+  ColumnMapping,
+  MappedOpGroup,
+  MappedOpGroupInternal,
+  OpGroup,
+  OpGroupInternal,
+  SchemaFieldsOf,
+} from '../opContext/opGroupTypes.js';
+import type { OpMetadata } from '../opContext/opTypes.js';
+import type { OpContext } from '../opContext/types.js';
+import { LogSchema } from '../schema/LogSchema.js';
+import { mergeWithSystemSchema, type SystemSchemaFieldTypes } from '../schema/systemSchema.js';
+import type { SchemaFields } from '../schema/types.js';
+import { createSpanBuffer } from '../spanBuffer.js';
+import { createTraceId, type TraceId } from '../traceId.js';
+import type { ITraceRoot, TracerLifecycleHooks } from '../traceRoot.js';
+import { createTraceRoot } from '../traceRoot.node.js';
+import type { TracerOptions } from '../tracer.js';
+import { TestTracer } from '../tracers/TestTracer.js';
+import type { LogBinding, SpanBuffer } from '../types.js';
+
+// Create a minimal OpContextBinding for shared test trace roots.
+const minimalOpContext = defineOpContext({ logSchema: new LogSchema({}) });
+
+function requireLogSchema(value: unknown, label: string): LogSchema {
+  if (!(value instanceof LogSchema)) {
+    throw new Error(`Expected ${label} to be a LogSchema`);
+  }
+  return value;
+}
+
+function assertColumnMapping<LibSchema extends SchemaFields>(
+  value: unknown,
+  label: string,
+): asserts value is ColumnMapping<LibSchema> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`Expected ${label} to be a column mapping record`);
+  }
+  for (const [key, mappingValue] of Object.entries(value)) {
+    if (typeof mappingValue !== 'string' && mappingValue !== null) {
+      throw new Error(`Expected column mapping '${key}' in ${label} to be a string or null`);
+    }
+  }
+}
+
+function assertOpGroupInternals<Ctx extends OpContext>(
+  opGroup: OpGroup<Ctx>,
+  label: string,
+): asserts opGroup is OpGroupInternal<Ctx> {
+  requireLogSchema(Reflect.get(opGroup, '_logSchema'), `${label}._logSchema`);
+}
+
+function assertMappedOpGroupInternals<Ctx extends OpContext, ContributedSchema extends SchemaFields>(
+  opGroup: MappedOpGroup<Ctx, ContributedSchema>,
+  label: string,
+): asserts opGroup is MappedOpGroupInternal<Ctx, ContributedSchema> {
+  requireLogSchema(Reflect.get(opGroup, '_logSchema'), `${label}._logSchema`);
+  const columnMapping = Reflect.get(opGroup, '_columnMapping');
+  assertColumnMapping<SchemaFieldsOf<Ctx['logSchema']>>(columnMapping, `${label}._columnMapping`);
+}
+
+export function requireStringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+    throw new Error(`Expected ${label} to be a string[]`);
+  }
+  return value;
+}
+
+export function requireFloat64Array(value: unknown, label: string): Float64Array {
+  if (!(value instanceof Float64Array)) {
+    throw new Error(`Expected ${label} to be a Float64Array`);
+  }
+  return value;
+}
+
+export function requireUint8Array(value: unknown, label: string): Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw new Error(`Expected ${label} to be a Uint8Array`);
+  }
+  return value;
+}
+
+/**
+ * Default TracerOptions for tests.
+ * Includes JsBufferStrategy and createTraceRoot.
+ */
+export function createTestTracerOptions<T extends LogSchema>(): TracerOptions<T> {
+  return {
+    bufferStrategy: new JsBufferStrategy<T>(),
+    createTraceRoot,
+  };
+}
+
+/**
+ * Shared TestTracer instance for tests that create buffers directly.
+ * Typed as TracerLifecycleHooks because that's what TraceRoot expects.
+ */
+export const TEST_TRACER: TracerLifecycleHooks = new TestTracer(minimalOpContext, createTestTracerOptions());
+
+type TestSpanBufferBundle<T extends SchemaFields> = {
+  logBinding: LogBinding;
+  spanBuffer: SpanBuffer<LogSchema<T>>;
+};
+
+type TestLoggerBundle<T extends LogSchema> = {
+  buffer: SpanBuffer<T>;
+  logger: SpanLoggerImpl<T>;
+  logBinding: LogBinding;
+};
+
+/**
+ * Create a TraceRoot for testing.
+ *
+ * TraceRoot contains trace_id, timestamp anchors, and tracer reference.
+ * This helper creates one with sensible defaults for tests.
+ *
+ * @param traceId - Optional trace ID (defaults to 'test-trace')
+ * @param tracer - Optional tracer (defaults to TEST_TRACER)
+ */
+export function createTestTraceRoot(traceId?: TraceId | string, tracer?: TracerLifecycleHooks): ITraceRoot {
+  // Accept string or TraceId - convert string to TraceId
+  const resolvedTraceId = traceId
+    ? typeof traceId === 'string'
+      ? createTraceId(traceId)
+      : traceId
+    : createTraceId('test-trace');
+
+  return createTraceRoot(resolvedTraceId, tracer ?? TEST_TRACER);
+}
+
+/**
+ * Create a test OpMetadata with pre-encoded entries.
+ * Uses createOpMetadata to ensure pre-encoded entries match the string values.
+ */
+export function createTestOpMetadata(overrides: Partial<OpMetadata> = {}): OpMetadata {
+  const name = overrides.name ?? DEFAULT_METADATA.name;
+  const package_name = overrides.package_name ?? DEFAULT_METADATA.package_name;
+  const package_file = overrides.package_file ?? DEFAULT_METADATA.package_file;
+  const git_sha = overrides.git_sha ?? DEFAULT_METADATA.git_sha;
+  const line = overrides.line ?? DEFAULT_METADATA.line;
+  return createOpMetadata(name, package_name, package_file, git_sha, line);
+}
+
+/**
+ * Create a LogSchema with system fields merged for testing.
+ * Use this when calling createSpanBuffer directly in tests.
+ */
+export function createTestSchema<T extends SchemaFields>(fields: T): LogSchema<SystemSchemaFieldTypes & T> {
+  const merged = mergeWithSystemSchema(fields);
+  return new LogSchema(merged);
+}
+
+/**
+ * Create a LogBinding for testing.
+ *
+ * LogBinding is the infrastructure object that ops use to create buffers.
+ * It contains the schema and optional remapping class.
+ *
+ * NOTE: Stats are NO LONGER on LogBinding - they are on SpanBufferClass.stats (static property).
+ * See agent-todo/opgroup-refactor.md lines 58-70, 525-547 for rationale.
+ *
+ * @param schema - LogSchema or SchemaFields to use (will be wrapped in LogSchema if needed)
+ * @returns LogBinding ready for use with createSpanBuffer
+ */
+export function createTestLogBinding<T extends SchemaFields>(schema: LogSchema<T>): LogBinding;
+export function createTestLogBinding<T extends SchemaFields>(schema: T): LogBinding;
+export function createTestLogBinding<T extends SchemaFields>(schema: T | LogSchema<T>): LogBinding {
+  // Wrap in LogSchema if plain SchemaFields provided
+  const logSchema = schema instanceof LogSchema ? schema : createTestSchema(schema);
+
+  return {
+    logSchema,
+    remappedViewClass: undefined,
+  };
+}
+
+/**
+ * Test-only helper that creates a LogBinding and SpanBuffer in one call.
+ *
+ * This is a convenience helper for tests that need both objects.
+ * Creates a root span buffer (no parent).
+ *
+ * @param schema - LogSchema or SchemaFields to use
+ * @param options - Configuration for the buffer
+ * @returns Object with logBinding and spanBuffer
+ */
+export function createTestSpanBuffer<T extends SchemaFields>(
+  schema: LogSchema<T>,
+  options?: {
+    trace_id?: TraceId;
+    capacity?: number;
+  },
+): TestSpanBufferBundle<T>;
+export function createTestSpanBuffer<T extends SchemaFields>(
+  schema: T,
+  options?: {
+    trace_id?: TraceId;
+    capacity?: number;
+  },
+): TestSpanBufferBundle<SystemSchemaFieldTypes & T>;
+export function createTestSpanBuffer<T extends SchemaFields>(
+  schema: T | LogSchema<T>,
+  options: {
+    trace_id?: TraceId;
+    capacity?: number;
+  } = {},
+) {
+  // Wrap in LogSchema if plain SchemaFields provided
+  const logSchema = schema instanceof LogSchema ? schema : createTestSchema(schema);
+
+  // Create LogBinding (stats are on SpanBufferClass.stats, not LogBinding)
+  const logBinding = createTestLogBinding(logSchema);
+
+  // Create TraceRoot with provided or default trace_id
+  const traceRoot = createTestTraceRoot(options.trace_id);
+
+  // Create SpanBuffer using the Phase 2 API (no LogBinding parameter)
+  const spanBuffer = createSpanBuffer(
+    logSchema,
+    traceRoot,
+    DEFAULT_METADATA,
+    options.capacity ?? DEFAULT_BUFFER_CAPACITY,
+  );
+
+  return { logBinding, spanBuffer };
+}
+
+/**
+ * Create a properly typed SpanLogger for testing.
+ *
+ * Returns buffer and logger so tests can verify buffer contents directly.
+ * Uses the real createSpanLogger API - no mocks.
+ *
+ * @param schema - LogSchema to use
+ * @returns Object with buffer and logger, both properly typed
+ */
+export function createTestLogger<T extends LogSchema>(schema: T): TestLoggerBundle<T> {
+  const logBinding = createTestLogBinding(schema);
+  const traceRoot = createTestTraceRoot();
+  const buffer = createSpanBuffer(schema, traceRoot, DEFAULT_METADATA);
+  const logger = createSpanLogger(schema, buffer);
+  return { buffer, logger, logBinding };
+}
+
+// =============================================================================
+// OPGROUP INTERNAL ACCESS HELPERS
+// =============================================================================
+
+/**
+ * Get internal properties from an OpGroup.
+ *
+ * OpGroup's internal properties (_logSchema, _flags) are hidden from
+ * intellisense but accessible at runtime. This helper provides typed
+ * access for tests that need to verify internal state.
+ *
+ * @param opGroup - The OpGroup to access
+ * @returns Internal interface with _logSchema and _flags
+ */
+export function getOpGroupInternals<Ctx extends OpContext>(
+  opGroup: OpGroup<Ctx>,
+): Pick<OpGroupInternal<Ctx>, '_logSchema'> {
+  assertOpGroupInternals(opGroup, 'OpGroup');
+  return { _logSchema: opGroup._logSchema };
+}
+
+/**
+ * Get internal properties from a MappedOpGroup.
+ *
+ * MappedOpGroup's internal properties (_logSchema, _flags, _columnMapping,
+ * _contributedSchema) are hidden from intellisense but accessible at runtime.
+ * This helper provides typed access for tests.
+ *
+ * @param opGroup - The MappedOpGroup to access
+ * @returns Internal interface with all internal properties
+ */
+export function getMappedOpGroupInternals<Ctx extends OpContext, ContributedSchema extends SchemaFields>(
+  opGroup: MappedOpGroup<Ctx, ContributedSchema>,
+): Pick<MappedOpGroupInternal<Ctx, ContributedSchema>, '_logSchema' | '_columnMapping'> {
+  assertMappedOpGroupInternals(opGroup, 'MappedOpGroup');
+  return {
+    _logSchema: opGroup._logSchema,
+    _columnMapping: opGroup._columnMapping,
+  };
+}
+
+/**
+ * Convenience type alias for accessing column mapping from a MappedOpGroup.
+ */
+export type { ColumnMapping, SchemaFieldsOf };
+
+// Re-export createTraceId for tests that need it
+export { createTraceId };
+
+/**
+ * Simple buffer creation helper for tests.
+ *
+ * This provides a simpler API than createSpanBuffer by using defaults for
+ * trace_id and opMetadata. Tests that need specific values should use
+ * createSpanBuffer directly.
+ *
+ * @param schema - LogSchema to use
+ * @param capacity - Buffer capacity (optional, uses default from class stats)
+ */
+export function createBuffer<T extends LogSchema>(schema: T, capacity?: number): SpanBuffer<T> {
+  return createSpanBuffer(schema, createTestTraceRoot(), DEFAULT_METADATA, capacity);
+}

package/src/lib/__tests__/timestamp.test.ts

@@ -0,0 +1,259 @@
+import { describe, expect, it } from 'bun:test';
+
+import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import { defineLogSchema } from '../schema/defineLogSchema.js';
+import type { AnySpanBuffer } from '../types.js';
+import { createBuffer } from './test-helpers.js';
+
+function createMockSpanBuffer(): AnySpanBuffer {
+  return createBuffer(defineLogSchema({}));
+}
+
+describe('Node.js TraceRoot Timestamps (process.hrtime.bigint)', () => {
+  it('should return a bigint from getTimestampNanos()', async () => {
+    const { createTraceRoot } = await import('../traceRoot.node.js');
+    const mockTracer = {
+      onTraceStart: () => {},
+      onTraceEnd: () => {},
+      onSpanStart: () => {},
+      onSpanEnd: () => {},
+      onStatsWillResetFor: () => {},
+      bufferStrategy: {
+        createChildSpanBuffer: createMockSpanBuffer,
+        createOverflowBuffer: createMockSpanBuffer,
+      },
+    };
+    const traceRoot = createTraceRoot('test-trace', mockTracer);
+
+    const ts = traceRoot.getTimestampNanos();
+    expect(typeof ts).toBe('bigint');
+  });
+
+  it('should return increasing timestamps', async () => {
+    const { createTraceRoot } = await import('../traceRoot.node.js');
+    const mockTracer = {
+      onTraceStart: () => {},
+      onTraceEnd: () => {},
+      onSpanStart: () => {},
+      onSpanEnd: () => {},
+      onStatsWillResetFor: () => {},
+      bufferStrategy: {
+        createChildSpanBuffer: createMockSpanBuffer,
+        createOverflowBuffer: createMockSpanBuffer,
+      },
+    };
+    const traceRoot = createTraceRoot('test-trace', mockTracer);
+
+    const ts1 = traceRoot.getTimestampNanos();
+    await new Promise((r) => setTimeout(r, 10));
+    const ts2 = traceRoot.getTimestampNanos();
+
+    expect(ts2).toBeGreaterThan(ts1);
+    // Should be roughly 10ms apart
+    const diff = ts2 - ts1;
+    expect(diff).toBeGreaterThan(5_000_000n); // > 5ms
+    expect(diff).toBeLessThan(50_000_000n); // < 50ms
+  });
+
+  it('should be within 1ms of Date.now()', async () => {
+    const { createTraceRoot } = await import('../traceRoot.node.js');
+    const mockTracer = {
+      onTraceStart: () => {},
+      onTraceEnd: () => {},
+      onSpanStart: () => {},
+      onSpanEnd: () => {},
+      onStatsWillResetFor: () => {},
+      bufferStrategy: {
+        createChildSpanBuffer: createMockSpanBuffer,
+        createOverflowBuffer: createMockSpanBuffer,
+      },
+    };
+
+    // Sample multiple times and check they're all close
+    for (let i = 0; i < 10; i++) {
+      const traceRoot = createTraceRoot('test-trace', mockTracer);
+      const dateNowMs = Date.now();
+      const ts = traceRoot.getTimestampNanos();
+      const tsMs = Nanoseconds.toMillis(ts);
+
+      const diffMs = Math.abs(tsMs - dateNowMs);
+      expect(diffMs).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('should have sub-millisecond precision (true nanoseconds)', async () => {
+    const { createTraceRoot } = await import('../traceRoot.node.js');
+    const mockTracer = {
+      onTraceStart: () => {},
+      onTraceEnd: () => {},
+      onSpanStart: () => {},
+      onSpanEnd: () => {},
+      onStatsWillResetFor: () => {},
+      bufferStrategy: {
+        createChildSpanBuffer: createMockSpanBuffer,
+        createOverflowBuffer: createMockSpanBuffer,
+      },
+    };
+    const traceRoot = createTraceRoot('test-trace', mockTracer);
+    const timestamps: bigint[] = [];
+
+    // Rapid-fire timestamps
+    for (let i = 0; i < 100; i++) {
+      timestamps.push(traceRoot.getTimestampNanos());
+    }
+
+    // Should see sub-millisecond differences (< 1_000_000 nanoseconds)
+    let hasSubMillisecond = false;
+    for (let i = 1; i < timestamps.length; i++) {
+      const diff = timestamps[i] - timestamps[i - 1];
+      if (diff > 0n && diff < 1_000_000n) {
+        hasSubMillisecond = true;
+        break;
+      }
+    }
+    expect(hasSubMillisecond).toBe(true);
+  });
+
+  it('should preserve nanosecond deltas in JS fallback above Number.MAX_SAFE_INTEGER', async () => {
+    const originalHrtimeBigint = process.hrtime.bigint;
+    const base = 9_007_199_254_740_993n; // Number.MAX_SAFE_INTEGER + 2
+    const sequence = [base, base + 1n, base + 2n];
+    let idx = 0;
+
+    process.hrtime.bigint = () => sequence[idx++] ?? sequence[sequence.length - 1];
+
+    try {
+      const { createTraceRoot } = await import('../traceRoot.node.js');
+      const mockTracer = {
+        onTraceStart: () => {},
+        onTraceEnd: () => {},
+        onSpanStart: () => {},
+        onSpanEnd: () => {},
+        onStatsWillResetFor: () => {},
+        bufferStrategy: {
+          createChildSpanBuffer: createMockSpanBuffer,
+          createOverflowBuffer: createMockSpanBuffer,
+        },
+      };
+
+      const traceRoot = createTraceRoot('test-trace', mockTracer);
+      const ts0 = traceRoot.getTimestampNanos();
+      const ts1 = traceRoot.getTimestampNanos();
+
+      expect(ts1 - ts0).toBe(1n);
+    } finally {
+      process.hrtime.bigint = originalHrtimeBigint;
+    }
+  });
+});
+
+describe('Browser TraceRoot Timestamps (performance.now)', () => {
+  it('should return a bigint from getTimestampNanos()', async () => {
+    const { createTraceRoot } = await import('../traceRoot.es.js');
+    const mockTracer = {
+      onTraceStart: () => {},
+      onTraceEnd: () => {},
+      onSpanStart: () => {},
+      onSpanEnd: () => {},
+      onStatsWillResetFor: () => {},
+      bufferStrategy: {
+        createChildSpanBuffer: createMockSpanBuffer,
+        createOverflowBuffer: createMockSpanBuffer,
+      },
+    };
+    const traceRoot = createTraceRoot('test-trace', mockTracer);
+
+    const ts = traceRoot.getTimestampNanos();
+    expect(typeof ts).toBe('bigint');
+  });
+
+  it('should return increasing timestamps', async () => {
+    const { createTraceRoot } = await import('../traceRoot.es.js');
+    const mockTracer = {
+      onTraceStart: () => {},
+      onTraceEnd: () => {},
+      onSpanStart: () => {},
+      onSpanEnd: () => {},
+      onStatsWillResetFor: () => {},
+      bufferStrategy: {
+        createChildSpanBuffer: createMockSpanBuffer,
+        createOverflowBuffer: createMockSpanBuffer,
+      },
+    };
+    const traceRoot = createTraceRoot('test-trace', mockTracer);
+
+    const ts1 = traceRoot.getTimestampNanos();
+    await new Promise((r) => setTimeout(r, 10));
+    const ts2 = traceRoot.getTimestampNanos();
+
+    expect(ts2).toBeGreaterThan(ts1);
+    // Should be roughly 10ms apart
+    const diff = ts2 - ts1;
+    expect(diff).toBeGreaterThan(5_000_000n); // > 5ms
+    expect(diff).toBeLessThan(50_000_000n); // < 50ms
+  });
+
+  it('should be within 1ms of Date.now()', async () => {
+    const { createTraceRoot } = await import('../traceRoot.es.js');
+    const mockTracer = {
+      onTraceStart: () => {},
+      onTraceEnd: () => {},
+      onSpanStart: () => {},
+      onSpanEnd: () => {},
+      onStatsWillResetFor: () => {},
+      bufferStrategy: {
+        createChildSpanBuffer: createMockSpanBuffer,
+        createOverflowBuffer: createMockSpanBuffer,
+      },
+    };
+
+    // Sample multiple times and check they're all close
+    for (let i = 0; i < 10; i++) {
+      const traceRoot = createTraceRoot('test-trace', mockTracer);
+      const dateNowMs = Date.now();
+      const ts = traceRoot.getTimestampNanos();
+      const tsMs = Nanoseconds.toMillis(ts);
+
+      const diffMs = Math.abs(tsMs - dateNowMs);
+      // Browser performance API should be very close to Date.now()
+      expect(diffMs).toBeLessThanOrEqual(1);
+    }
+  });
+});
+
+describe('Nanoseconds utilities', () => {
+  it('fromMillis converts correctly', () => {
+    const ns = Nanoseconds.fromMillis(1000);
+    expect(ns).toBe(Nanoseconds.unsafe(1_000_000_000n));
+  });
+
+  it('toMillis converts correctly', () => {
+    const ns = Nanoseconds.fromMillis(1234);
+    expect(Nanoseconds.toMillis(ns)).toBe(1234);
+  });
+
+  it('toMicros converts correctly', () => {
+    const ns = Nanoseconds.fromMillis(1);
+    expect(Nanoseconds.toMicros(ns)).toBe(1000n);
+  });
+
+  it('unsafe casts bigint', () => {
+    const raw = 123456789n;
+    const ns = Nanoseconds.unsafe(raw);
+    expect(ns).toBe(Nanoseconds.unsafe(raw));
+  });
+});
+
+describe('Platform entry points export createTraceRoot', () => {
+  it('should export createTraceRoot from /node', async () => {
+    const nodeModule = await import('../../node.js');
+    expect(nodeModule.createTraceRoot).toBeDefined();
+    expect(typeof nodeModule.createTraceRoot).toBe('function');
+  });
+
+  it('should export createTraceRoot from /es', async () => {
+    const esModule = await import('../../es.js');
+    expect(esModule.createTraceRoot).toBeDefined();
+    expect(typeof esModule.createTraceRoot).toBe('function');
+  });
+});

package/src/lib/__tests__/trace-archive-primitives.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'bun:test';
+import { compactTraceChunks } from '../archive/chunkCompaction.js';
+import { buildTraceChunkEnvelope } from '../archive/chunkEnvelope.js';
+import { inspectPartitionCardinality, splitChunkByPartition } from '../archive/chunkRouting.js';
+import { extractChunkStats } from '../archive/chunkStats.js';
+
+describe('trace archive primitives', () => {
+  it('buildTraceChunkEnvelope produces stable chunk_id', () => {
+    const a = buildTraceChunkEnvelope({
+      file_ref: 's3://bucket/trace.arrow',
+      chunk_ref: 'chunk-001',
+      row_count: 4,
+      started_at_ms: 100,
+      ended_at_ms: 240,
+      partition_keys: ['group_b', 'group_a'],
+      metadata: { z: 1, a: 'x' },
+    });
+
+    const b = buildTraceChunkEnvelope({
+      file_ref: 's3://bucket/trace.arrow',
+      chunk_ref: 'chunk-001',
+      row_count: 4,
+      started_at_ms: 100,
+      ended_at_ms: 240,
+      partition_keys: ['group_a', 'group_b'],
+      metadata: { a: 'x', z: 1 },
+    });
+
+    expect(a.chunk_id).toBe(b.chunk_id);
+  });
+
+  it('inspectPartitionCardinality returns single, mixed, unknown', () => {
+    const singleRows = [{ group: 'g1' }, { group: 'g1' }];
+    const mixedRows = [{ group: 'g1' }, { group: 'g2' }];
+    const unknownRows = [{ group: 'g1' }, { group: '' }];
+
+    expect(inspectPartitionCardinality(singleRows, (row) => row.group)).toBe('single');
+    expect(inspectPartitionCardinality(mixedRows, (row) => row.group)).toBe('mixed');
+    expect(inspectPartitionCardinality(unknownRows, (row) => row.group)).toBe('unknown');
+  });
+
+  it('splitChunkByPartition emits deterministic selectors', () => {
+    const rows = [
+      { id: 1, group: 'g2' },
+      { id: 2, group: 'g1' },
+      { id: 3, group: 'g2' },
+      { id: 4, group: 'g1' },
+    ];
+
+    const splits = splitChunkByPartition(rows, (row) => row.group, 'listener_group');
+
+    expect(splits.map((split) => split.partition)).toEqual(['g1', 'g2']);
+    expect(splits.map((split) => split.selector)).toEqual(['listener_group == "g1"', 'listener_group == "g2"']);
+    expect(splits[0].row_indexes).toEqual([1, 3]);
+    expect(splits[1].row_indexes).toEqual([0, 2]);
+  });
+
+  it('compactTraceChunks is idempotent for source order', () => {
+    const c1 = buildTraceChunkEnvelope({
+      file_ref: 'f',
+      chunk_ref: 'a',
+      row_count: 2,
+      started_at_ms: 10,
+      ended_at_ms: 20,
+    });
+    const c2 = buildTraceChunkEnvelope({
+      file_ref: 'f',
+      chunk_ref: 'b',
+      row_count: 3,
+      started_at_ms: 21,
+      ended_at_ms: 40,
+    });
+
+    const x = compactTraceChunks([c1, c2], { started_at_ms: 0, ended_at_ms: 100 });
+    const y = compactTraceChunks([c2, c1], { started_at_ms: 0, ended_at_ms: 100 });
+
+    expect(x.source_set_hash).toBe(y.source_set_hash);
+    expect(x.compaction_id).toBe(y.compaction_id);
+    expect(x.total_rows).toBe(5);
+  });
+
+  it('extractChunkStats reports chunk level metrics', () => {
+    const envelope = buildTraceChunkEnvelope({
+      file_ref: 'f',
+      chunk_ref: 'x',
+      row_count: 7,
+      started_at_ms: 100,
+      ended_at_ms: 190,
+    });
+
+    const splits = splitChunkByPartition([{ group: 'g1' }, { group: 'g1' }, { group: 'g2' }], (row) => row.group);
+
+    const stats = extractChunkStats(envelope, splits);
+    expect(stats.chunk_id).toBe(envelope.chunk_id);
+    expect(stats.partition_count).toBe(2);
+    expect(stats.duration_ms).toBe(90);
+  });
+});