@@ -12,6 +12,7 @@
 """
 
 import json
+import warnings
 from copy import deepcopy
 from datetime import datetime, timezone
 from pathlib import Path
@@ -33,6 +34,26 @@
 from .ido import ndi_ido
 
 
+def _definition_to_doc_type(definition: str) -> str:
+    """Turn a superclass ``definition`` path into a document type name.
+
+    Definitions name their target through a path VARIABLE:
+    ``$NDIDOCUMENTPATH/element.json`` for NDI's own documents,
+    ``$NDICALCDOCUMENTPATH/vision/contrast_tuning.json`` for ones shipped
+    by NDIcalc-vis-matlab. MATLAB registers both as DID globals
+    (ndi.common.PathConstants), so both resolve there.
+
+    Here they resolve to the same folder, because ndi_install.py copies
+    each dependency's ``ndi_common`` tree into NDI-python's own. So every
+    variable is stripped rather than only ``$NDIDOCUMENTPATH`` -- which is
+    what previously left ``$NDICALCDOCUMENTPATH/...`` as a literal path,
+    unfindable, and silently skipped.
+    """
+    import re
+
+    return re.sub(r"^\$[A-Z]+PATH/", "", definition).replace(".json", "")
+
+
 class ndi_document:
     """NDI document class for database storage.
 
@@ -496,9 +517,7 @@ def doc_superclass(self) -> list[str]:
             definition = sc.get("definition", "")
             if definition:
                 try:
-                    sc_doc = ndi_document(
-                        definition.replace("$NDIDOCUMENTPATH/", "").replace(".json", "")
-                    )
+                    sc_doc = ndi_document(_definition_to_doc_type(definition))
                     sc_names.append(sc_doc.doc_class())
                 except Exception:
                     pass
@@ -771,11 +790,33 @@ def read_blank_definition(document_type: str) -> dict:
         Returns:
             Dictionary with blank document structure.
         """
-        # Try to find the JSON definition
-        json_path = ndi_common_PathConstants.DOCUMENT_PATH / f"{document_type}.json"
+        root = ndi_common_PathConstants.DOCUMENT_PATH
+        json_path = root / f"{document_type}.json"
+
+        if not json_path.exists() and "/" not in document_type:
+            # Fall back to a recursive search for a BARE class name.
+            #
+            # MATLAB resolves a bare name against the whole document tree,
+            # so ndi.document('image') finds data/image.json. Here only the
+            # top level was tried, so the same call needed 'data/image' --
+            # a difference affecting every document in a subdirectory
+            # (image, generic_file, the whole stimulus family) and one that
+            # made otherwise-symmetric code diverge at the call site.
+            #
+            # Only for a bare name: a caller who wrote 'data/image'
+            # expects that exact file, and should not silently get a
+            # same-named document from elsewhere in the tree.
+            matches = sorted(root.rglob(f"{document_type}.json"))
+            if len(matches) == 1:
+                json_path = matches[0]
+            elif len(matches) > 1:
+                rel = ", ".join(str(m.relative_to(root)) for m in matches)
+                raise FileNotFoundError(
+                    f"ndi_document type {document_type!r} is ambiguous: {rel}. "
+                    f"Give the path, e.g. {matches[0].relative_to(root).with_suffix('')}."
+                )
 
         if not json_path.exists():
-            # Try without path constants (for testing)
             raise FileNotFoundError(
                 f"ndi_document definition not found: {json_path}. "
                 f"Make sure NDI is properly installed."
@@ -808,19 +849,36 @@ def read_blank_definition(document_type: str) -> dict:
                     continue
 
                 entry = dict(sc) if isinstance(sc, dict) else {"definition": sc_def}
+                merged_superclasses.append(entry)
 
-                # Extract document type from definition path
-                sc_type = sc_def.replace("$NDIDOCUMENTPATH/", "").replace(".json", "")
+                # Strip whatever $...PATH/ prefix the definition carries, not
+                # just $NDIDOCUMENTPATH: calculator documents name their
+                # superclasses through $NDICALCDOCUMENTPATH, and ndi_install.py
+                # merges every dependency's ndi_common into one tree.
+                sc_type = _definition_to_doc_type(sc_def)
                 try:
                     sc_props = ndi_document.read_blank_definition(sc_type)
                 except FileNotFoundError:
-                    # Skip missing superclass definitions, but keep the entry:
-                    # dropping it would silently shorten the superclass list.
-                    merged_superclasses.append(entry)
+                    # Warn rather than swallow. A declared superclass that
+                    # cannot be found is a broken definition, and the document
+                    # silently loses everything that superclass would have
+                    # contributed -- including 'base'. That surfaced far away
+                    # as KeyError: 'base' at construction and took a bisect to
+                    # trace back here. Raising would be better still, but is a
+                    # wider behavioural change than this fix.
+                    #
+                    # The entry stays in the list either way: dropping it would
+                    # silently shorten the superclass list the schema is
+                    # validated against, trading one quiet failure for another.
+                    warnings.warn(
+                        f"superclass {sc_def!r} of {document_type!r} could "
+                        f"not be resolved (looked for {sc_type!r}); the "
+                        f"document will be missing whatever it defines",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
                     continue
 
-                merged_superclasses.append(entry)
-
                 # The superclass's own superclasses join ours.  sc_props is
                 # already merged, so this is the whole transitive closure.
                 sc_class = sc_props.get("document_class") or {}
 
@@ -0,0 +1,15 @@
+{
+	"document_class": {
+		"definition":						"$NDIDOCUMENTPATH\/calculator.json",
+		"validation":						"$NDISCHEMAPATH\/calculator_schema.json",
+		"class_name":						"calculator",
+		"property_list_name":					"calculator",
+		"class_version":					1,
+		"superclasses": [
+			{ "definition":					"$NDIDOCUMENTPATH\/base.json" },
+			{ "definition":					"$NDIDOCUMENTPATH\/app.json" }
+		]
+	},
+	"calculator": {
+	}
+}
@@ -0,0 +1,7 @@
+{
+	"classname":	"calculator",
+	"superclasses": [ "base", "app" ],
+	"depends_on": [ ],
+	"calculator": [
+	]
+}
@@ -40,6 +40,29 @@ def empty_id() -> str:
     return "".join("0" if c != "_" else "_" for c in base_id)
 
 
+def _binary_handle(file_path):
+    """Open a binary document file with MATLAB's attribute name on it.
+
+    MATLAB's ``database_openbinarydoc`` returns an ``ndi.database.binarydoc``
+    carrying ``fullpathfilename`` -- session.m uses it itself, as the key
+    for its autoclose listeners. Python returned a bare file object, so
+    code written against the documented MATLAB API broke here even though
+    the information was present the whole time under a different name
+    (``.name``).
+
+    The returned object is still an ordinary file object, so every existing
+    caller is unaffected; it simply also answers to the MATLAB name.
+
+    Not yet symmetric: MATLAB takes an ``autoClose`` option implemented
+    with object-destruction listeners. The Python idiom would be a context
+    manager rather than a listener, which is a design decision rather than
+    an attribute, so it is left for its own change.
+    """
+    fh = open(file_path, "rb")
+    fh.fullpathfilename = str(file_path)
+    return fh
+
+
 class ndi_session(ABC):
     """
     Abstract base class for NDI sessions.
@@ -504,15 +527,15 @@ def database_openbinarydoc(
         if not file_path.exists():
             # Attempt on-demand fetch from cloud via ndic:// protocol
             if self._try_cloud_fetch(doc, filename, file_path):
-                return open(file_path, "rb")
+                return _binary_handle(file_path)
             raise FileNotFoundError(
                 f"Binary file '{filename}' not found for document {doc_id}. "
                 f"If this is a cloud dataset, ensure NDI_CLOUD_USERNAME and "
                 f"NDI_CLOUD_PASSWORD environment variables are set, or pass "
                 f"a cloud_client to the session/dataset."
             )
 
-        return open(file_path, "rb")
+        return _binary_handle(file_path)
 
     def database_existbinarydoc(
         self,
 
@@ -28,19 +28,6 @@
 class TestNDIDocument:
     """Test full document create-add-search-read-binary workflow."""
 
-    @pytest.mark.xfail(
-        strict=True,
-        reason=(
-            "Upstream DID-python bug: sqlitedb's new 'files' table has "
-            "FOREIGN KEY(doc_idx) REFERENCES docs(doc_idx), but _do_remove_doc "
-            "never deletes from it, so database_rm on a document carrying a "
-            "binary raises sqlite3.IntegrityError. No NDI-side fix exists; "
-            "fixed upstream in VH-Lab/DID-python#39. "
-            "Tracked, with a minimal repro, in "
-            "tests/test_did_integration.py::test_removing_a_file_bearing_document "
-            "and docs/developer_notes/DEPENDENCY_DRIFT_2026-08.md."
-        ),
-    )
     def test_document_creation_and_io(self, tmp_path):
         """Full lifecycle: create → add → search → read binary → remove.
 
 
@@ -0,0 +1,77 @@
+"""database_openbinarydoc must answer to the MATLAB attribute name.
+
+MATLAB's returns an ndi.database.binarydoc carrying ``fullpathfilename``
+-- session.m uses it itself, as the key for its autoclose listeners.
+Python returned a bare file object, so code written against the documented
+MATLAB API broke here even though the path was present all along under a
+different name.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from ndi.document import ndi_document
+from ndi.session.dir import ndi_session_dir
+
+PAYLOAD = b"binary payload for the symmetry test\x00\xff"
+
+
+@pytest.fixture
+def session_with_binary(tmp_path):
+    d = tmp_path / "sess"
+    d.mkdir(parents=True, exist_ok=True)
+    S = ndi_session_dir("bin_test", str(d))
+
+    payload = tmp_path / "payload.bin"
+    payload.write_bytes(PAYLOAD)
+
+    doc = ndi_document("data/generic_file") + S.newdocument()
+    # generic_file.json ships "" for two double fields whose schema allows no
+    # empty value (parameters [0,10000000,1] -- three entries, so can-be-empty
+    # is off), so a blank generic_file document cannot be added in either
+    # language. The defect is in the shared ndi_common JSON and is reported
+    # upstream; worked around here rather than patched in NDI-python's copy.
+    # See docs/developer_notes/DEPENDENCY_DRIFT_2026-08.md.
+    doc.document_properties["generic_file"]["dateCreated"] = 0
+    doc.document_properties["generic_file"]["dateUpdated"] = 0
+    doc = doc.add_file("generic_file.ext", str(payload))
+    S.database_add(doc)
+    return S, doc, "generic_file.ext"
+
+
+def test_handle_carries_fullpathfilename(session_with_binary):
+    S, doc, name = session_with_binary
+    fh = S.database_openbinarydoc(doc, name)
+    try:
+        assert hasattr(fh, "fullpathfilename"), (
+            "MATLAB's binarydoc exposes fullpathfilename; code written "
+            "against that API must work here too"
+        )
+        assert fh.fullpathfilename == fh.name
+        assert fh.fullpathfilename.endswith(name)
+    finally:
+        S.database_closebinarydoc(fh)
+
+
+def test_handle_is_still_an_ordinary_file_object(session_with_binary):
+    """The attribute is additive. Every existing caller reads bytes from
+    this object and must be unaffected."""
+    S, doc, name = session_with_binary
+    fh = S.database_openbinarydoc(doc, name)
+    try:
+        assert fh.read() == PAYLOAD
+    finally:
+        S.database_closebinarydoc(fh)
+
+
+def test_path_can_be_reopened_by_name(session_with_binary):
+    """The whole point: a caller can hand the path to something that
+    wants a filename rather than a handle."""
+    S, doc, name = session_with_binary
+    fh = S.database_openbinarydoc(doc, name)
+    path = fh.fullpathfilename
+    S.database_closebinarydoc(fh)
+    # Reopened by path alone, with no handle and no session involved.
+    with open(path, "rb") as f2:
+        assert f2.read() == PAYLOAD