Parquet export for raw events (Phase D operability)

[pbudzik]

Summary

Bridges the internal billing-grade format to standard Parquet for warehouse / BI / debug. The reviewer's framing was "internal format optimized for billing; external format Parquet for everything else" — this is the bridge.

What's in

New module src/export/parquet.rs:

• export_raw_segments(state, output_path) — snapshots the manifest, reads every raw segment, builds an Arrow RecordBatch, writes a Parquet file with zstd compression.
• Flat schema — no nested types, so any Parquet consumer can read it without struct/map support:

Column	Type	Notes
event_id	Utf8
kind	Utf8	"Usage" / "Correction" / "Retraction"
correction_original_event_id	Utf8 nullable	flattened from correction_ref
correction_reason	Utf8 nullable	flattened from correction_ref
account_id	Utf8
subscription_id	Utf8 nullable
product_id	Utf8
meter_id	Utf8
model_id	Utf8 nullable
timestamp_ms	Int64
quantity	Decimal128(38, 0)	i128 fits exactly
unit	Utf8
source	Utf8
dimensions_canonical	Utf8	serde_json of SmallDimensions (BTreeMap → canonical order)
ingested_at_ms	Int64

Deps

arrow = 55 + parquet = 55 (with zstd feature). Compile-time cost is ~10 s on first build, cached afterward.

Scope notes

This is the simplest possible export — dump every segment in the manifest to one Parquet file. No partitioning, no filtering, no streaming row groups. Per-day partitioning + streaming for arbitrarily large exports land in a follow-up if/when needed.

The memtable is not included (only durably-flushed segments). For a full point-in-time export, the caller should drive a flush first.

Tests

tests/parquet_export.rs — 5 tests:

• write_parquet_round_trips_event_fields — including i128::MAX/4, a Correction with -100, and correction_ref flattening
• schema_matches_canonical_shape — column names, nullability, Decimal128(38, 0) for quantity
• empty_input_writes_valid_zero_row_parquet
• export_raw_segments_round_trips_through_manifest — full end-to-end
• export_empty_manifest_produces_zero_row_file

Test plan

• cargo build --all-targets clean with -D warnings
• cargo test --all-targets — 96 tests pass (was 91; +5)
• CI green

🤖 Generated with Claude Code