Fetch a remote-only series manifest through the custom_file_handler (#87)

[stevevanhooser]

Summary

Closes #87. Companion port of the DID-matlab fix in VH-Lab/DID-matlab#201 (PR VH-Lab/DID-matlab#202).

A series document that arrived from a store keeping bytes remote — a SyncFiles=false round trip through NDI Cloud, say — lands with its manifest's file_info naming an ndic:// address and no manifest bytes on this machine. _open_series_member's local-only manifest lookup then raised DID:SQLITEDB:FileSeries:ManifestNotLocal without ever offering the manifest's location to the handler, even when the caller had passed one.

This PR adds a dedicated fetch path so a cloud-only manifest resolves the same way every other remote file already does, without changing the fast local path or the no-network contract of cached_path_for_file.

What changed

• SQLiteDB._fetch_series_manifest_bytes (src/did/implementations/sqlitedb.py) — new protected method, one level up from the existing _fetch_remote_to_cache with the same call shape. Reads the manifest's file_info straight from the document, offers every non-'file' location to the custom_file_handler with the manifest's own uid in the context (seriesName="", mode="open"), and lands the bytes at filecachepath/<manifestUid> under the same single-flight lock the member fetch already holds. Failure returns None so the caller can raise the ordinary ManifestNotLocal.
• _open_series_member — when _series_manifest_path returns None AND a custom_file_handler was supplied, calls the helper before raising. Fast local path unchanged; exist_doc, no-handler, and no-remote-location cases still get the same ManifestNotLocal shape as before.
• _series_manifest_path (src/did/database.py) — docstring updated: it is deliberately no-network so cached_path_for_file stays callable from any thread and any process, and the retrieval-authorized path lives on the sqlite implementation.

Tests (tests/test_open_doc_file_series.py)

New TestFetchingAnAbsentManifest class with a stored_series_cloud_only fixture (ndicloud location, ingest=0 — the shape SyncFiles=false produces, uid-keyed handler serves the bytes):

• test_a_cloud_only_manifest_is_retrieved_through_the_handler — acceptance case. Handler receives the manifest's ndic:// sourcePath with the manifest's own uid in the context, ctx.seriesName="", ctx.mode="open"; the member then reads back byte-for-byte.
• test_the_manifest_lands_at_filecachepath_after_the_fetch — pins the cache placement (filecachepath/<manifestUid>) that makes the second open cheap.
• test_different_members_share_one_manifest_fetch — three different member opens result in exactly one manifest handler call.
• test_a_handler_that_serves_nothing_raises_manifest_not_local — handler-refused case still raises DID:SQLITEDB:FileSeries:ManifestNotLocal, so callers pattern-matching on the identifier keep working.
• test_no_handler_still_raises_manifest_not_local — the no-handler path is unchanged.

All 41 tests in the file pass; the whole suite (686 passed, 10 skipped, 1 xfailed) passes locally (the bridge-contract module is skipped because pyyaml isn't installed in the run environment — pre-existing, unrelated).

Not this PR

• Persisting series_info.ingest_locations — rejected in localSeriesManifestPath cannot fetch a remote manifest — series reads fail on cloud-only downloads DID-matlab#201 for the same reason; would defeat the manifest-as-address-book design and inflate documents linearly with member count.
• Any DID-matlab changes — those live in Fetch a remote-only series manifest through the customFileHandler (#201) DID-matlab#202 (green, waiting on review).

Related

• Fetch a remote-only series manifest through the customFileHandler (#201) DID-matlab#202 — the MATLAB PR this ports (green CI, waiting on review).
• localSeriesManifestPath cannot fetch a remote manifest — series reads fail on cloud-only downloads DID-matlab#201 — the MATLAB-side issue with the design write-up.
• Retire the manifest cloud-reference workaround and add an offline SyncFiles=false round-trip test once DID-matlab#201 lands NDI-matlab#986 — follow-up to add an offline SyncFiles=false round-trip test and audit the updateFileInfoForLocalFiles cloud-reference workaround once this lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_015dKpDXCo8VTS4AHiibNnCp

---

Generated by Claude Code