Polars sharp edges

Most of polars is well covered by training data. This skill documents only the edges that don't surface in small-data tests and so get missed.

join does not preserve row order by default

DataFrame.join and LazyFrame.join take a keyword-only maintain_order argument that defaults to 'none':

# ❌ Result row order is NOT guaranteed. It may match the left frame on small
#    data, then differ on larger data, across runs, or across polars versions.
result = df.join(meta, on="sample_id", how="left")

# ✅ Preserve the left frame's order explicitly when downstream code relies on it.
result = df.join(meta, on="sample_id", how="left", maintain_order="left")