fix(reader): O_DIRECT path triggers on uri_scheme=direct (mlcommons/storage#567)

[FileSystemGuy]

Summary

Fixes a storage_library sentinel mismatch that made --o-direct / storage_type=direct_fs crash on every local NPZ / NPY / JPEG workload (UNet3D, ResNet, …) in the warmup batch with FileNotFoundError: 'direct:///mnt/…/foo.npz'.

• dlio_benchmark/utils/config.py validates that storage_type=direct_fs requires storage_options.storage_library == "s3dlio".
• dlio_benchmark/reader/_local_fs_iterable_mixin.py previously selected the s3dlio O_DIRECT prefetch path only when storage_options.storage_library == "direct".

No value of storage_library satisfied both, so _use_direct was always False for direct_fs runs. The buffered path was taken, plain open() was handed a direct://… URI, and the run crashed.

The fix

Select the O_DIRECT path when EITHER:

• storage_options.uri_scheme == "direct" — canonical signal, matches what direct_fs validation produces (and what mlpstorage's --o-direct emits).
• storage_options.storage_library == "direct" — legacy single-knob form, preserved for backward compatibility.

uri_scheme is the semantically honest gate: it directly asks "is this a direct:// URI?" — exactly the precondition _prefetch_direct needs. storage_library is a coarser library-selector that must keep meaning something different for real S3 callers, where storage_library=s3dlio + uri_scheme=s3 is correct and must NOT trigger local O_DIRECT.

Test plan

• New unit suite tests/test_direct_fs_iterable_mixin_gate.py — 13 tests, all pass:
  • Locks the exact storage#567 config shape (storage_library=s3dlio + uri_scheme=direct) → _use_direct=True.
  • uri_scheme=direct alone is sufficient.
  • Legacy storage_library=direct alone still works.
  • storage_library=s3dlio + uri_scheme in {s3, file} does NOT spuriously trigger local O_DIRECT (S3 / file:// regression guards).
  • Empty / None storage_options → buffered fallback, no crash.
  • Bookkeeping counters seeded on every path.
• Fast CI suite: tests/test_fast_ci.py — 84 passed, 1 skipped.
• Adjacent suites unaffected: test_data_generator_improvements.py, test_odirect_preflight.py, test_issue_regressions.py, test_skip_listing_config.py — 47 passed.
• On-cluster (recommended before merge): reproducer from mlcommons/storage#567 should now reach the workload instead of crashing in warmup.

Linked

• mlcommons/storage#567 — the original report, with full FileNotFoundError trace and the s3dlio / config.py vs. mixin disagreement diagnosed.
• Once this lands, the downstream pin in mlcommons/storage's pyproject.toml should be bumped (the file already has a comment block for tracking DLIO PR history at pyproject.toml:131-145).

Notes for reviewers

• Behavior change is strictly additive: every config that selected _use_direct=True before still does. Only the previously-broken direct_fs shape becomes reachable.
• Docstrings (module-level and _localfs_init) updated to describe both signals and explain why uri_scheme is the canonical one.
• Marked draft because the issue reporter still owes a re-test confirming the reproducer holds on mlcommons/storage@6553c0e. Open for early review meanwhile.

[FileSystemGuy]

@russfellows You've been very productive today! Could you please do the needful here too?

[russfellows]

Seems correct, I guess now that we have someone to test O_DIRECT we should be able to make progress. Fingers crossed.