Reverse-conversion (h5ad → Seurat) integrity overhaul

[mianaz]

Hardens readH5AD() and the h5ad writers against the known failure modes of full-object reverse conversion, so the read direction gets the same read-back discipline the write direction already has.

What changed

Counts-layer ambiguity (version-aware resolution). Where raw counts live is now resolved explicitly, in priority order: a new /uns/scConvert/counts_location stamp → /layers/counts (modern convention) → /raw/X (legacy scanpy) → /X. The resolved slot lands in the Seurat counts layer and X in data in every path — in-memory, components subsets, the C-reader fallback, and BPCells on-disk mode (which previously only knew raw/X and silently served log-normalized X as on-disk "counts" for layers['counts'] files). Failing to relocate counts out of layers/counts is now a hard scConvert_data_error instead of a swallowed message.

Counts integrality guard. A counts layer left holding non-integer values raises a classed scConvert_counts_warning naming the slot it came from.

Writer provenance stamp. All three h5ad writers (.writeH5AD_c post-pass, DirectSeuratToH5AD, H5SeuratToH5AD) stamp /uns/scConvert/{version, counts_location} by inspecting the file just written — not the writer's intent — so readers branch on recorded fact instead of layout heuristics. Verified the stamp reads back cleanly in Python anndata as a plain uns dict.

Post-read verification. Before returning, the loaded object is asserted against the file: dims vs the file's obs/var counts (transpose/orientation check), cell names identical to the obs index in order, feature names identical to the var index modulo Seurat's documented underscore→dash replacement, and no duplicate barcodes/genes. Violations raise scConvert_data_error; what the reader did is recorded in misc$scConvert_read.

Duplicate names are loud. Duplicate barcodes/features dedupe with a classed scConvert_names_warning instead of silently.

Gene identity is never lost. When final feature names differ from the file's var index (dedup or underscore mangling), the original identifiers are preserved in an orig_var_index feature-metadata column. Var metadata and layer matrices are now keyed by the object's final rownames — fixing a real pre-existing bug where underscore gene names silently misaligned var columns and dropped layers (including layers/counts itself).

Reduction keys. Colliding obsm keys (e.g. X_pca + pca) no longer silently overwrite each other; later claimants keep their raw key with a scConvert_reduction_warning. New readH5AD(reductions = c(scvi = "X_scVI")) argument selects and renames obsm keys explicitly.

Categoricals. Stored category order stays the factor level order (now pinned by tests against non-alphabetical orders), and the AnnData ordered flag round-trips into ordered factors in both reader paths (DecodeCategorical() gains ordered=; the C path restores the flag post-hoc).

Shared helpers live in the new R/VerifyH5AD.R; the sparse/dense matrix reader moved there unchanged from the readH5AD closure so all paths share one implementation.

Testing

• New tests/testthat/test-reverse-conversion.R: 80 assertions pinning the contract across both reader paths (hdf5r and C) — counts resolution incl. components subsets and the stamp override, warning classes, verification errors, dedup + orig_var_index, collision/remap behavior, category order/orderedness, and a full write→read round trip.
• Full suite: 843 pass; the only 6 failures (h5mu, zarr vlen-utf8) reproduce identically on unmodified main in the dev container (HDF5 1.10 there vs the required 1.14+) and are unrelated.
• R CMD check Rd/usage/code checks clean; a writeH5AD output with the new stamp loads cleanly in Python anndata with layers['counts'] and uns['scConvert'] intact.

---

Generated by Claude Code