Summary

All known real-world implementations of the COS API call requestFileHandles() with exactly one hash and read back exactly one handle. The plural form is never used as intended. This issue proposes renaming the method to requestFileHandle() (singular) to better match actual usage.

Evidence

A broad code search across GitHub (31 total results) was conducted across all known independent implementations. Every single call site passes a single-element array and reads back a single handle:

Zero implementations pass more than one hash in a single call.

Problems with the current plural form

1. Misleading ergonomics. Every consumer is forced to write const [handle] = await ...requestFileHandles([singleHash]) — wrapping a single item in an array only to destructure it back out is pure boilerplate noise.
2. False promise of batching. The plural signature implies atomicity or efficiency gains from batching multiple hashes, but no implementer found this useful. AI model files are large and handled one at a time.
3. Explicit workarounds. The TVM family explicitly does const handles = ...; const handle = handles[0] — actively fighting the plural shape.
4. Precedent. Web APIs conventionally reflect actual usage. If batching is ever needed in the future, a separate method or overload can be introduced.

Proposal

Rename the method:

// Before
Promise<sequence<FileSystemFileHandle>> requestFileHandles(
  sequence<HashDescriptor> hashes,
  optional CrossOriginStorageOptions options = {}
);

// After
Promise<FileSystemFileHandle> requestFileHandle(
  HashDescriptor hash,
  optional CrossOriginStorageOptions options = {}
);

Callers wanting multiple handles in parallel can use Promise.all(), which is idiomatic JS and gives better per-file error granularity.

References

• huggingface/transformers.js PR #1549
• ngxson/wllama PR #248
• flutter/flutter PR #184149
• mlc-ai/web-llm PR #748
• apache/tvm web/src/artifact_cache.ts
• emscripten-core/emscripten PR #27066