Module ordering_sim 

Measured blob-ordering picker: simulate per-ordering HTTP range-read cost.

BlobOrdering::choose is a cheap cardinality heuristic. This module is the honest alternative it references: over the real native-tier tiles, lay each candidate ordering’s byte string down (with the writer’s exact total sort key), simulate the two canonical access patterns — scrub a viewport across all time and pan one instant across space — under HTTP range coalescing, and rank the orderings by the range-read cost they actually incur. It is a faithful Rust port of the showcase probe (examples/showcase/src/lib/spaceCurve.ts), sharpened to sort with the production crate::curve::space_time_key so the simulated layout is byte-identical to what the writer lays down.

Two callers share it: the opt-in --blob-ordering measured build mode (PackWriter::with_measured_ordering) and the stt-optimize order-audit subcommand. It is a pure, deterministic function of its inputs — all integer arithmetic, stable sorts, no RNG — because the resolved ordering sets every content-addressed pack name; any nondeterminism would churn pack hashes and break immutable-CDN caching.

Structs

OrderingCost

Aggregate cost of one ordering across the canonical query mix.

QueryCost

Cost of one access pattern under one ordering.

SimOptions

Simulation knobs. The build path always uses the default so pack hashes stay reproducible; coalesce_gap_bytes is exposed for offline sweeps.

TileSample

One tile as the simulator sees it. len is the blob byte weight — the uncompressed payload.len() at finalize, or the compressed entry.length in the advisor; because range count (the primary cost) is weight-insensitive both call sites pick the same winner.

Constants

CANDIDATES

The orderings evaluated, in final-tiebreak priority order: a genuine cost tie resolves to the earliest entry, so SpatialMajor wins ties (which reproduces the shallow-time choose rule for free) and Morton3 sits dead-last and can never win a tie.

DEFAULT_COALESCE_GAP_BYTES

Default range-read coalescing gap: two needed blobs fuse into one request when at most this many unneeded bytes lie between them. Matches the production reader’s DEFAULT_RANGE_COALESCE_GAP (packages/core, archive.ts) so the simulation models what the client actually does.

SELECTABLE

Orderings the pickers may select. Morton3 is deliberately absent — it is offered only as an explicit --blob-ordering morton3 for research; its long jumps hurt locality and its rare measured “wins” are marginal over-read edges on tiny datasets. It is still evaluated and reported for comparison.

Functions

evaluate

Rank every candidate ordering cheapest-first for these tiles by the blended OrderingCost::cost (bytes read + reads × gap), with the stable sort keeping CANDIDATES order as the final tiebreak (so SpatialMajor wins genuine ties). Morton3 is included for reporting but never selected by measured_ordering (see SELECTABLE).

measured_ordering

The measured-best selectable ordering for these tiles — the cheapest that is not Morton3 (SpatialMajor on empty input). Morton3 is reported by evaluate but never chosen (see SELECTABLE).