@energy8platform/stake-math-tools 0.5.0 → 0.6.0

package/src/transform-jsonl-zst.ts

@@ -0,0 +1,285 @@
+/**
+ * Streaming `*.jsonl.zst → *.jsonl.zst` transformer.
+ *
+ * Decompresses the input with zstd, runs each line through an optional user
+ * mapper, recompresses the result. Pipes everything — no temp files, memory
+ * footprint stays at one line regardless of input size, so gigabyte books
+ * files work fine.
+ *
+ * Why not `readline.createInterface`? readline accumulates each line as a
+ * growing JS string (`buffer += chunk`), which hits V8's ~512MB string-length
+ * limit on books files that contain very long event arrays — manifests as
+ * `RangeError: Invalid string length` deep in node:internal/readline. The
+ * Buffer-based splitter here keeps incomplete-line state as raw bytes and
+ * only materializes a string at the LF boundary (mapper mode) or never
+ * (identity mode), so any line that fits in OS memory is fine.
+ *
+ * In identity mode (no mapper) we don't split at all — we pipe decompressor
+ * output directly into compressor input as raw bytes. That's the fastest
+ * path: ~25 MB/s of compressed input on a single core, dominated by the
+ * zstd subprocesses, with zero JS string allocation.
+ *
+ * Requires the `zstd` binary on PATH (same precondition as the rest of the
+ * stake-bridge tooling).
+ */
+
+import { spawn } from 'node:child_process';
+
+export type LineMapper = (
+  line: string,
+  index: number,
+) => string | string[] | null | undefined;
+
+export type BinaryLineMapper = (
+  line: Buffer,
+  index: number,
+) => Buffer | string | Array<Buffer | string> | null | undefined;
+
+export interface TransformJsonlZstParams {
+  /** Path to a zstd-compressed `.jsonl.zst` file. */
+  inputPath: string;
+  /** Path where the transformed `.jsonl.zst` will be written (overwritten). */
+  outputPath: string;
+  /** Per-line transform with the line decoded as a JS string. Default =
+   *  identity passthrough (byte pipe, no per-line allocations).
+   *
+   *  - Return a `string` to replace the line with that content.
+   *  - Return a `string[]` to expand one input line into several output lines.
+   *  - Return `null` / `undefined` to drop the line entirely.
+   *
+   *  Mutually exclusive with `binaryMapper`. Use `binaryMapper` instead when
+   *  any single line could exceed V8's ~512 MB string-length cap (e.g. bonus
+   *  game books with massive event arrays) — `toString('utf8')` will throw
+   *  `ERR_STRING_TOO_LONG` on lines above that limit. */
+  mapper?: LineMapper;
+  /** Per-line transform with the line passed as a raw `Buffer`. Use this
+   *  for any line that may exceed V8's ~512 MB string limit, or when you
+   *  only need to peek at a small prefix (`line.subarray(0, 64).toString()`)
+   *  and want to pass the rest of the bytes through verbatim.
+   *
+   *  Return shape:
+   *    - `Buffer` or `string` — replace the line with that content.
+   *    - array of `Buffer | string` — expand to N output lines.
+   *    - `null` / `undefined` — drop.
+   *
+   *  Mutually exclusive with `mapper`. */
+  binaryMapper?: BinaryLineMapper;
+  /** zstd compression level for the output. 1 = fastest, 22 = smallest.
+   *  Default 9 — same level the kitsune optimize pipeline uses. */
+  zstdLevel?: number;
+  /** Called every `progressEveryLines` input lines with running counts.
+   *  Useful for progress bars on multi-million-row files. Identity mode
+   *  reports `linesRead == linesWritten == 0` because we don't split. */
+  onProgress?: (linesRead: number, linesWritten: number) => void;
+  /** How often to fire `onProgress`. Default 100_000. */
+  progressEveryLines?: number;
+}
+
+export interface TransformJsonlZstResult {
+  linesRead: number;
+  linesWritten: number;
+  /** True when identity mode was used: byte-pipe passthrough without
+   *  per-line counting (so `linesRead`/`linesWritten` will be 0). */
+  identityPassthrough: boolean;
+}
+
+const LF = 0x0a;
+const LF_BUFFER = Buffer.from([LF]);
+
+export async function transformJsonlZst(
+  params: TransformJsonlZstParams,
+): Promise<TransformJsonlZstResult> {
+  const {
+    inputPath,
+    outputPath,
+    mapper,
+    binaryMapper,
+    zstdLevel = 9,
+    onProgress,
+    progressEveryLines = 100_000,
+  } = params;
+
+  if (mapper && binaryMapper) {
+    throw new Error(
+      'transformJsonlZst: pass either `mapper` (string) or `binaryMapper` (Buffer), not both',
+    );
+  }
+  const anyMapper = mapper ?? binaryMapper;
+
+  const decompress = spawn('zstd', ['-dc', '-q', inputPath], {
+    stdio: ['ignore', 'pipe', 'inherit'],
+  });
+  const compress = spawn(
+    'zstd',
+    [`-${zstdLevel}`, '-q', '-f', '-o', outputPath],
+    { stdio: ['pipe', 'inherit', 'inherit'] },
+  );
+
+  const decompressDone = waitForExit(decompress, 'zstd -d');
+  const compressDone = waitForExit(compress, 'zstd -c');
+
+  const writeChunk = (chunk: Buffer | string): Promise<void> => {
+    if (compress.stdin.write(chunk)) return Promise.resolve();
+    return new Promise<void>((resolve, reject) => {
+      const onDrain = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (err: Error) => {
+        cleanup();
+        reject(err);
+      };
+      const cleanup = () => {
+        compress.stdin.off('drain', onDrain);
+        compress.stdin.off('error', onError);
+      };
+      compress.stdin.once('drain', onDrain);
+      compress.stdin.once('error', onError);
+    });
+  };
+
+  let linesRead = 0;
+  let linesWritten = 0;
+
+  try {
+    if (!anyMapper) {
+      // Identity mode: byte-pipe. Never split into lines, never materialize
+      // strings, never accumulate buffers. Constant memory regardless of how
+      // long individual lines are.
+      for await (const chunk of decompress.stdout!) {
+        await writeChunk(chunk);
+      }
+    } else {
+      // Mapper mode: split on LF boundaries by scanning raw bytes. We keep
+      // incomplete-line bytes in a small array of Buffers (no concatenation
+      // into a single growing JS string), then `Buffer.concat` + `toString`
+      // when the LF is finally seen (string mapper) or never (binary mapper).
+      let pending: Buffer[] = [];
+      let pendingLen = 0;
+
+      const writeMapperResult = async (out: Buffer | string): Promise<void> => {
+        await writeChunk(out);
+        await writeChunk(LF_BUFFER);
+        linesWritten++;
+      };
+
+      const flushLine = async (lineBuf: Buffer): Promise<void> => {
+        // Strip trailing CR for CRLF tolerance, matching readline behaviour.
+        const trimmed =
+          lineBuf.length > 0 && lineBuf[lineBuf.length - 1] === 0x0d
+            ? lineBuf.subarray(0, lineBuf.length - 1)
+            : lineBuf;
+
+        let result: string | string[] | Buffer | Array<Buffer | string> | null | undefined;
+        if (binaryMapper) {
+          result = binaryMapper(trimmed, linesRead);
+        } else {
+          // String mapper: decode the line. Lines above V8's ~512 MB string
+          // cap throw ERR_STRING_TOO_LONG here — re-throw with a pointer to
+          // `binaryMapper` so the failure mode is obvious.
+          let lineStr: string;
+          try {
+            lineStr = trimmed.toString('utf8');
+          } catch (err) {
+            if (
+              err instanceof Error &&
+              (err as NodeJS.ErrnoException).code === 'ERR_STRING_TOO_LONG'
+            ) {
+              const wrapped = new Error(
+                `transformJsonlZst: line ${linesRead} is ${trimmed.length} bytes — ` +
+                  `exceeds V8 max JS string length (~512 MB). Use the ` +
+                  '`binaryMapper` option to receive the line as a Buffer.',
+              );
+              (wrapped as { cause?: unknown }).cause = err;
+              throw wrapped;
+            }
+            throw err;
+          }
+          result = mapper!(lineStr, linesRead);
+        }
+        linesRead++;
+
+        if (result === null || result === undefined) {
+          // drop
+        } else if (Array.isArray(result)) {
+          for (const out of result) {
+            await writeMapperResult(out);
+          }
+        } else {
+          await writeMapperResult(result);
+        }
+
+        if (onProgress && linesRead % progressEveryLines === 0) {
+          onProgress(linesRead, linesWritten);
+        }
+      };
+
+      for await (const chunk of decompress.stdout! as AsyncIterable<Buffer>) {
+        let start = 0;
+        // Buffer.indexOf(LF) is a C++ scan, ~20× faster than a JS byte loop.
+        while (start < chunk.length) {
+          const lf = chunk.indexOf(LF, start);
+          if (lf < 0) {
+            // No LF in the remainder — stash as pending and move on.
+            const remainder = chunk.subarray(start);
+            const owned = Buffer.from(remainder);
+            pending.push(owned);
+            pendingLen += owned.length;
+            break;
+          }
+          const tail = chunk.subarray(start, lf);
+          let lineBuf: Buffer;
+          if (pendingLen === 0) {
+            lineBuf = tail;
+          } else {
+            pending.push(tail);
+            lineBuf = Buffer.concat(pending, pendingLen + tail.length);
+            pending = [];
+            pendingLen = 0;
+          }
+          await flushLine(lineBuf);
+          start = lf + 1;
+        }
+      }
+
+      // Trailing line without a terminating LF — emit it the same way readline
+      // would (so callers don't silently lose data when the input lacks a
+      // final newline).
+      if (pendingLen > 0) {
+        const lineBuf = Buffer.concat(pending, pendingLen);
+        await flushLine(lineBuf);
+      }
+    }
+  } catch (err) {
+    compress.stdin.destroy();
+    throw err;
+  }
+
+  compress.stdin.end();
+
+  await Promise.all([decompressDone, compressDone]);
+
+  if (mapper && onProgress) onProgress(linesRead, linesWritten);
+
+  return { linesRead, linesWritten, identityPassthrough: !mapper };
+}
+
+function waitForExit(
+  child: ReturnType<typeof spawn>,
+  label: string,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    child.on('error', (err) => {
+      reject(new Error(`${label} failed to spawn: ${err.message}`));
+    });
+    child.on('close', (code, signal) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(
+            `${label} exited with ${code === null ? `signal ${signal}` : `code ${code}`}`,
+          ),
+        );
+    });
+  });
+}

package/src/types.ts

@@ -82,6 +82,29 @@ export interface OptimizeParams {
    *  Default true. */
   ensureRangeCoverage?: boolean;
 
+  /** Tier-based only: reshape the high-tier sampling so the per-bucket row
+   *  counts follow a log-decay curve across Stake hit-rate ranges — each
+   *  bucket above the lowest one in the high tier targets `ratio × prev`
+   *  rows. Turns the typical sparse tail of `…18 → 1 → 1 → 1 → 4` into
+   *  a smooth `…18 → 9 → 4 → 2 → 1` instead.
+   *
+   *  When true and `largePmThreshold` is unset, auto-sets it to
+   *  `max(50, capPmThreshold / 20)` so the decay covers multiple Stake
+   *  buckets, not just the single cap bucket. Default false. */
+  shapeDistribution?: boolean;
+
+  /** Tier-based only: ratio between adjacent Stake-bucket row counts when
+   *  `shapeDistribution=true`. 0.5 = each higher bucket has half the rows
+   *  of the one below it. Default 0.5. */
+  shapeDecayRatio?: number;
+
+  /** Tier-based only: auto-pick `shapeDecayRatio` by binary search so the
+   *  achieved CV lands at `targetCV` within `toleranceCV`. Requires
+   *  `shapeDistribution=true` and a `targetCV > 0`. Runs the full pipeline
+   *  up to 6 times (one per bisection step) — expect a 5×-6× wall-clock
+   *  hit on builds where it triggers. Default false. */
+  shapeAutoMatchCV?: boolean;
+
   /** Tier-based only: minimum fraction of nRowsOut that must be distinct payoutCents
    *  values in the output. Stake Engine rejects "Insufficient Unique Events" when
    *  too few distinct outcomes exist (same events repeat in a session). Default 0.01

package/test/transform-jsonl-zst.test.ts

@@ -0,0 +1,343 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { transformJsonlZst } from '../src/transform-jsonl-zst.js';
+
+let workDir: string;
+
+beforeEach(() => {
+  workDir = mkdtempSync(join(tmpdir(), 'transform-jsonl-zst-'));
+});
+
+afterEach(() => {
+  rmSync(workDir, { recursive: true, force: true });
+});
+
+function writeJsonlZst(name: string, lines: string[]): string {
+  const jsonlPath = join(workDir, `${name}.jsonl`);
+  const zstPath = join(workDir, `${name}.jsonl.zst`);
+  writeFileSync(jsonlPath, lines.join('\n') + (lines.length > 0 ? '\n' : ''));
+  execFileSync('zstd', ['-q', '-f', '-o', zstPath, jsonlPath]);
+  return zstPath;
+}
+
+function readJsonlZst(zstPath: string): string[] {
+  // Bump maxBuffer well past the 1 MiB default — some tests round-trip
+  // multi-megabyte payloads.
+  const jsonl = execFileSync('zstd', ['-dc', '-q', zstPath], {
+    maxBuffer: 64 * 1024 * 1024,
+  }).toString('utf8');
+  if (jsonl.length === 0) return [];
+  return jsonl.endsWith('\n') ? jsonl.slice(0, -1).split('\n') : jsonl.split('\n');
+}
+
+describe('transformJsonlZst', () => {
+  it('round-trips identity as a pure byte passthrough', async () => {
+    const lines = [
+      '{"id":0,"payoutMultiplier":120}',
+      '{"id":1,"payoutMultiplier":0}',
+      '{"id":2,"payoutMultiplier":500}',
+    ];
+    const input = writeJsonlZst('in', lines);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const result = await transformJsonlZst({ inputPath: input, outputPath: output });
+
+    // Identity mode does not split into lines, so the counters stay at zero —
+    // by design, to keep the path allocation-free.
+    expect(result.identityPassthrough).toBe(true);
+    expect(result.linesRead).toBe(0);
+    expect(result.linesWritten).toBe(0);
+    expect(readJsonlZst(output)).toEqual(lines);
+  });
+
+  it('applies a line mapper as a 1:1 transform', async () => {
+    const input = writeJsonlZst('in', [
+      '{"id":0,"v":1}',
+      '{"id":1,"v":2}',
+      '{"id":2,"v":3}',
+    ]);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      mapper: (line, i) => {
+        const obj = JSON.parse(line);
+        return JSON.stringify({ ...obj, idx: i, doubled: obj.v * 2 });
+      },
+    });
+
+    expect(result.identityPassthrough).toBe(false);
+    expect(result.linesWritten).toBe(3);
+    expect(readJsonlZst(output)).toEqual([
+      '{"id":0,"v":1,"idx":0,"doubled":2}',
+      '{"id":1,"v":2,"idx":1,"doubled":4}',
+      '{"id":2,"v":3,"idx":2,"doubled":6}',
+    ]);
+  });
+
+  it('drops lines when mapper returns null', async () => {
+    const input = writeJsonlZst('in', [
+      '{"keep":true,"id":0}',
+      '{"keep":false,"id":1}',
+      '{"keep":true,"id":2}',
+      '{"keep":false,"id":3}',
+    ]);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      mapper: (line) => (JSON.parse(line).keep ? line : null),
+    });
+
+    expect(result.linesRead).toBe(4);
+    expect(result.linesWritten).toBe(2);
+    expect(readJsonlZst(output)).toEqual([
+      '{"keep":true,"id":0}',
+      '{"keep":true,"id":2}',
+    ]);
+  });
+
+  it('expands a single input line into multiple outputs when mapper returns an array', async () => {
+    const input = writeJsonlZst('in', ['{"id":0}', '{"id":1}']);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      mapper: (line) => [line, line],
+    });
+
+    expect(result.linesRead).toBe(2);
+    expect(result.linesWritten).toBe(4);
+    expect(readJsonlZst(output)).toEqual([
+      '{"id":0}',
+      '{"id":0}',
+      '{"id":1}',
+      '{"id":1}',
+    ]);
+  });
+
+  it('handles an empty input file', async () => {
+    const input = writeJsonlZst('in', []);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const result = await transformJsonlZst({ inputPath: input, outputPath: output });
+
+    expect(result.linesRead).toBe(0);
+    expect(result.linesWritten).toBe(0);
+    expect(existsSync(output)).toBe(true);
+    expect(readJsonlZst(output)).toEqual([]);
+  });
+
+  it('emits a trailing line that lacks a final newline', async () => {
+    // Build a raw jsonl with no terminating \n, compress it manually so we
+    // exercise the trailing-flush path in the mapper branch.
+    const jsonlPath = join(workDir, 'no-final-lf.jsonl');
+    writeFileSync(jsonlPath, '{"id":0}\n{"id":1}');
+    const input = join(workDir, 'no-final-lf.jsonl.zst');
+    execFileSync('zstd', ['-q', '-f', '-o', input, jsonlPath]);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      mapper: (line) => line,
+    });
+
+    expect(result.linesRead).toBe(2);
+    expect(result.linesWritten).toBe(2);
+    expect(readJsonlZst(output)).toEqual(['{"id":0}', '{"id":1}']);
+  });
+
+  it('rejects when the input file does not exist', async () => {
+    const output = join(workDir, 'out.jsonl.zst');
+    await expect(
+      transformJsonlZst({
+        inputPath: join(workDir, 'does-not-exist.jsonl.zst'),
+        outputPath: output,
+      }),
+    ).rejects.toThrow(/zstd -d/);
+  });
+
+  it('calls onProgress with the running counts (mapper mode)', async () => {
+    const lines = Array.from({ length: 250 }, (_, i) => `{"i":${i}}`);
+    const input = writeJsonlZst('in', lines);
+    const output = join(workDir, 'out.jsonl.zst');
+    const calls: Array<[number, number]> = [];
+
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      mapper: (line) => line,
+      progressEveryLines: 100,
+      onProgress: (r, w) => calls.push([r, w]),
+    });
+
+    expect(result.linesRead).toBe(250);
+    // Mid-stream ticks at 100 / 200 + a final flush at 250.
+    expect(calls).toEqual([
+      [100, 100],
+      [200, 200],
+      [250, 250],
+    ]);
+  });
+
+  it('supports a large stream (identity byte-pipe) without per-line allocations', async () => {
+    const N = 50_000;
+    const lines = Array.from({ length: N }, (_, i) =>
+      JSON.stringify({ id: i, payload: 'x'.repeat(40) }),
+    );
+    const input = writeJsonlZst('in', lines);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const result = await transformJsonlZst({ inputPath: input, outputPath: output });
+
+    expect(result.identityPassthrough).toBe(true);
+    const out = readJsonlZst(output);
+    expect(out.length).toBe(N);
+    expect(out[0]).toBe(lines[0]);
+    expect(out[N - 1]).toBe(lines[N - 1]);
+  });
+
+  it('processes a single line larger than a default stream chunk (128 KiB) via mapper', async () => {
+    // Construct a line of ~512 KiB so it spans many decompressor chunks. This
+    // is the failure mode that `readline += string` hits at scale; the
+    // Buffer-based splitter must concatenate transparently.
+    const bigLine = '{"id":0,"payload":"' + 'x'.repeat(500_000) + '"}';
+    const input = writeJsonlZst('in', [bigLine, '{"id":1}']);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const sizes: number[] = [];
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      mapper: (line) => {
+        sizes.push(line.length);
+        return line;
+      },
+    });
+
+    expect(result.linesRead).toBe(2);
+    expect(result.linesWritten).toBe(2);
+    expect(sizes[0]).toBe(bigLine.length);
+    expect(sizes[1]).toBe('{"id":1}'.length);
+    const out = readJsonlZst(output);
+    expect(out[0].length).toBe(bigLine.length);
+    expect(out[1]).toBe('{"id":1}');
+  });
+
+  it('passes raw Buffer to binaryMapper and lets it emit Buffer or string', async () => {
+    const input = writeJsonlZst('in', [
+      '{"id":0,"v":1}',
+      '{"id":1,"v":2}',
+      '{"id":2,"v":3}',
+    ]);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const seen: Array<{ isBuffer: boolean; byteLength: number; firstByte: number }> = [];
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      binaryMapper: (lineBuf, i) => {
+        seen.push({
+          isBuffer: Buffer.isBuffer(lineBuf),
+          byteLength: lineBuf.length,
+          firstByte: lineBuf[0],
+        });
+        // Mix Buffer + string returns: even indices stay as Buffer, odd as string.
+        return i % 2 === 0 ? lineBuf : lineBuf.toString('utf8');
+      },
+    });
+
+    expect(result.linesRead).toBe(3);
+    expect(result.linesWritten).toBe(3);
+    expect(seen.every((s) => s.isBuffer)).toBe(true);
+    expect(seen[0].firstByte).toBe('{'.charCodeAt(0));
+    expect(readJsonlZst(output)).toEqual([
+      '{"id":0,"v":1}',
+      '{"id":1,"v":2}',
+      '{"id":2,"v":3}',
+    ]);
+  });
+
+  it('binaryMapper rewrites a multi-megabyte line via prefix-only string conversion', async () => {
+    // Mimic the curate use case: id-prefix lookup + verbatim tail. Build a
+    // ~3 MB line so the test stays fast but the path is identical to what a
+    // 1 GB book line would exercise — only the prefix becomes a string.
+    const bigTail = '"events":[' + '0,'.repeat(1_500_000) + '0]';
+    const bigLine = `{"id":42,${bigTail}}`;
+    const input = writeJsonlZst('in', [
+      `{"id":1,"keep":false}`,
+      bigLine,
+      `{"id":99,"keep":true}`,
+    ]);
+    const output = join(workDir, 'out.jsonl.zst');
+
+    const selected = new Map<number, number>([
+      [42, 0],
+      [99, 1],
+    ]);
+    const idPrefix = /^\{"id":(\d+),/;
+
+    const result = await transformJsonlZst({
+      inputPath: input,
+      outputPath: output,
+      binaryMapper: (lineBuf) => {
+        // Peek only the first 32 bytes — works regardless of full line size.
+        const head = lineBuf.subarray(0, 32).toString('utf8');
+        const m = idPrefix.exec(head);
+        if (!m) return null;
+        const newId = selected.get(Number(m[1]));
+        if (newId === undefined) return null;
+        const prefix = Buffer.from(`{"id":${newId},`);
+        const tail = lineBuf.subarray(m[0].length);
+        return Buffer.concat([prefix, tail], prefix.length + tail.length);
+      },
+    });
+
+    expect(result.linesRead).toBe(3);
+    expect(result.linesWritten).toBe(2);
+    const out = readJsonlZst(output);
+    expect(out.length).toBe(2);
+    // First written line is the rewritten big one (id 42 → 0).
+    expect(out[0].startsWith('{"id":0,"events":[')).toBe(true);
+    expect(out[0].length).toBe(bigLine.length - `{"id":42,`.length + `{"id":0,`.length);
+    expect(out[1]).toBe('{"id":1,"keep":true}');
+  });
+
+  it('rejects when both mapper and binaryMapper are provided', async () => {
+    const input = writeJsonlZst('in', ['{"id":0}']);
+    const output = join(workDir, 'out.jsonl.zst');
+    await expect(
+      transformJsonlZst({
+        inputPath: input,
+        outputPath: output,
+        mapper: (l) => l,
+        binaryMapper: (b) => b,
+      }),
+    ).rejects.toThrow(/either.*mapper.*binaryMapper/);
+  });
+
+  it('honors the zstdLevel parameter', async () => {
+    const lines = Array.from({ length: 1000 }, (_, i) =>
+      JSON.stringify({ id: i, lots: 'of repeating text '.repeat(5) }),
+    );
+    const input = writeJsonlZst('in', lines);
+    const outFast = join(workDir, 'fast.jsonl.zst');
+    const outSmall = join(workDir, 'small.jsonl.zst');
+
+    await transformJsonlZst({ inputPath: input, outputPath: outFast, zstdLevel: 1 });
+    await transformJsonlZst({ inputPath: input, outputPath: outSmall, zstdLevel: 19 });
+
+    expect(readJsonlZst(outFast)).toEqual(readJsonlZst(outSmall));
+    const fastSize = statSync(outFast).size;
+    const smallSize = statSync(outSmall).size;
+    expect(smallSize).toBeLessThanOrEqual(fastSize);
+  });
+});