Route links through the backend reader and writer interfaces

[ehennestad]

Motivation

Background — MatNWB's storage backends are described by io.backend.base.Reader and io.backend.base.Writer, with HDF5 as the only implementation today, but a Zarr reader in development. This PR closes a hole where the abstraction did not fully cover link types (SoftLink, ExternalLink).

Problem —types.untyped.SoftLink and types.untyped.ExternalLink reached past the abstraction and called HDF5 directly: both export methods took the writer's raw file id and called H5L.create_soft / H5L.create_external, and ExternalLink.deref opened the target file itself with H5F.open, h5info and H5L.get_val. The Writer interface had no link API at all, so there was nothing for a new backend to implement — supporting links would have meant special-casing these two classes.

Solution — Links are now expressed as capabilities of the backend. Writing a link asks the writer; reading one asks the reader. A new backend supports links by implementing interface methods, and neither link class contains a storage-specific call any more.

What changed

• Writer gains writeSoftLink and writeExternalLink; Reader gains readLinkInfo and isReferenceDataset. All four are implemented for HDF5.
• SoftLink and ExternalLink no longer contain any H5F., H5L., h5info or H5T_REFERENCE reference. A backend that has not implemented link support now fails naming the method it is missing, rather than failing inside HDF5.
• No behaviour change for HDF5 files: links are written, read and dereferenced exactly as before.
• Two smaller fixes came along with the rewrite:
  • SoftLink.exportScalar contained an unreachable second if isempty(obj.path) branch, dead after the early return above it.
  • ExternalLink.export declared a refs output that it never assigned, so requesting that output errored. It now returns {}, matching SoftLink.export.

Implementation notes

ExternalLink.deref previously opened the target file with H5F.open and h5info. It now resolves a reader through io.backend.BackendFactory and calls readNodeInfo, which returns the same h5info-style struct for any backend, so the group/dataset/link classification is unchanged.

The retry that SoftLink performed by catching an "name already exists" message is now an explicit check in the HDF5 writer: an identical link is left alone, a differing one is replaced. Rewriting a link is routine rather than exceptional, since an object whose link target is not resolvable on the first pass is exported again by NwbFile.resolveReferences.

isReferenceDataset was added because deref decided how to handle a linked dataset by testing LinkedInfo.Datatype.Class against 'H5T_REFERENCE'. HDF5Reader already made the same test inside readDatasetValue, so this was reaching around an existing abstraction rather than filling a gap in one; readDatasetValue now calls the new method too, so a single place decides. How a dataset is marked as holding references is backend specific — a reference datatype class in HDF5, a zarr_dtype attribute of "object" in hdmf-zarr.

deref checks for its target with isfile or isfolder, since a store is a single file for some backends and a directory for others.

How to test

Soft and external links round-trip unchanged:

nwb = NwbFile('identifier', 'LINKS', 'session_description', 'link round trip', ...
    'session_start_time', datetime(2026, 1, 1, 'TimeZone', 'local'));
device = types.core.Device('description', 'a device');
nwb.general_devices.set('dev', device);
nwb.general_extracellular_ephys.set('grp', types.core.ElectrodeGroup( ...
    'description', 'a group', 'location', 'somewhere', ...
    'device', types.untyped.SoftLink(device)));
nwb.acquisition.set('ts', types.core.TimeSeries( ...
    'data', 1:5, 'data_unit', 'n/a', 'timestamps', 1:5));
nwbExport(nwb, 'links.nwb');

other = NwbFile('identifier', 'OTHER', 'session_description', 'external link', ...
    'session_start_time', datetime(2026, 1, 1, 'TimeZone', 'local'));
other.acquisition.set('linked_ts', types.untyped.ExternalLink( ...
    fullfile(pwd, 'links.nwb'), '/acquisition/ts'));
nwbExport(other, 'other.nwb');

back = nwbRead('links.nwb');
disp(class(back.general_extracellular_ephys.get('grp').device))
disp(class(back.general_extracellular_ephys.get('grp').device.deref(back)))

linked = nwbRead('other.nwb').acquisition.get('linked_ts');
disp(class(linked.deref()))
disp(linked.deref().data.load()')

types.untyped.SoftLink
types.core.Device
types.core.TimeSeries
     1     2     3     4     5

Not included

ExternalLink resolves a relative target filename against the current working directory rather than against the file containing the link, which can silently dereference the wrong file. That is reported separately in #865 and deliberately left alone here, since fixing it changes what deref returns rather than where the call is routed.

Checklist

• Have you ensured the PR description clearly describes the problem and solutions?
• Have you checked to ensure that there aren't other open or previously closed Pull Requests for the same change?
• If this PR fixes an issue, is the first line of the PR description fix #XX where XX is the issue number?

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 99.04762% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 95.27%. Comparing base (382d71c) to head (51c9ff7).

Files with missing lines	Patch %	Lines
+types/+untyped/ExternalLink.m	97.67%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #866      +/-   ##
==========================================
+ Coverage   95.21%   95.27%   +0.05%     
==========================================
  Files         231      232       +1     
  Lines        8252     8292      +40     
==========================================
+ Hits         7857     7900      +43     
+ Misses        395      392       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.