@@ -56,3 +56,28 @@ jobs:
 
       - name: Test with pytest
         run: pytest
+
+  wheel-smoke:
+    # A pytest run imports from the source tree, so it cannot catch missing
+    # package DATA (example_schema/*.json) in the built distribution. Build a
+    # wheel, install it into a clean environment, and construct a document from
+    # OUTSIDE the repo so a broken package-data config fails here.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel --outdir dist
+
+      - name: Install wheel and construct a document from outside the repo
+        run: |
+          python -m pip install dist/*.whl
+          cd "$RUNNER_TEMP"
+          python -c "from did.document import Document; Document('demoA'); Document('base'); print('wheel smoke OK')"
@@ -80,6 +80,14 @@ jobs:
         run: pytest -m make_artifacts -v
 
       - name: "Step 2: Python readArtifact tests"
+        # Artifacts are produced by earlier steps in THIS job (MATLAB
+        # makeArtifacts in Step 1, Python makeArtifacts above), so a missing
+        # artifact dir/file here is a real failure, not a reason to skip green.
+        # This env var makes the readArtifact test fail hard on absence instead
+        # of skipping (skips exit 0 and let the badge go green having compared
+        # nothing across languages).
+        env:
+          DID_SYMMETRY_REQUIRE_ARTIFACTS: "1"
         run: pytest -m read_artifacts -v
 
       # --- Step 3: MATLAB readArtifacts ---
 
@@ -11,11 +11,11 @@ authors = [
   { name = "Author", email = "vanhoosr@brandeis.edu" },
 ]
 dependencies = [
-    "numpy",
-    "pandas",
-    "portalocker",
-    "networkx",
-    "matplotlib",
+    "numpy>=1.20",
+    "pandas>=2.0,<4",
+    "portalocker>=2.0",
+    "networkx>=2.6",
+    "matplotlib>=3.5",
 ]
 requires-python = ">=3.10"
 
@@ -40,3 +40,14 @@ where = ["src"]
 
 [tool.setuptools.package-dir]
 "" = "src"
+
+# Ship the example schema/document JSON in the built distribution. Without this
+# a pip-installed `did` has no example_schema/ under site-packages, so
+# PathConstants.DEFPATH points at a nonexistent directory and Document('demoA')
+# raises FileNotFoundError. example_schema/ is a data directory (no __init__.py),
+# so packages.find does not discover it and its JSON must be declared here.
+[tool.setuptools.package-data]
+"did" = ["example_schema/**/*.json"]
+
+[tool.setuptools]
+include-package-data = true
@@ -93,16 +93,35 @@ def validate_docs(self, document_objs):
 
         _validate_docs(document_objs, all_ids, debug=self.debug)
 
-    def add_docs(self, document_objs, branch_id=None, validate=True, **kwargs):
+    #: Allowed values for the ``OnDuplicate`` option, mirroring DID-matlab's
+    #: ``did.database.add_docs`` ``OnDuplicate {mustBeMember(...)} = 'error'``.
+    _ON_DUPLICATE_CHOICES = ("ignore", "warn", "error")
+
+    def add_docs(
+        self,
+        document_objs,
+        branch_id=None,
+        validate=True,
+        OnDuplicate="error",
+        **kwargs,
+    ):
         if branch_id is None:
             branch_id = self.current_branch_id
 
+        # Reject invalid OnDuplicate up front (mirror MATLAB mustBeMember) so a
+        # typo cannot silently fall through to default behaviour.
+        if str(OnDuplicate).lower() not in self._ON_DUPLICATE_CHOICES:
+            raise ValueError(
+                "OnDuplicate must be one of "
+                f"{self._ON_DUPLICATE_CHOICES}; got {OnDuplicate!r}."
+            )
+
         # Ensure all input docs pass schema validation (unless requested not to)
         if validate:
             self.validate_docs(document_objs)
 
         for doc in document_objs:
-            self._do_add_doc(doc, branch_id, **kwargs)
+            self._do_add_doc(doc, branch_id, OnDuplicate=OnDuplicate, **kwargs)
 
     # ... other document-related methods would follow ...
 
 
@@ -6,9 +6,21 @@
 from .common import PathConstants
 
 
-def _utcnow():
-    """Naive UTC timestamp, identical to the deprecated datetime.utcnow()."""
-    return datetime.now(timezone.utc).replace(tzinfo=None)
+def _utc_timestamp():
+    """Return the current UTC time as an ISO-8601 millisecond string with 'Z'.
+
+    Ported from NDI-python (ndi.fun.timestamp) with the leap-second guard.
+    ``str(datetime.utcnow())`` previously emitted a space-separated,
+    timezone-less string ('2026-07-20 22:36:19.611068') that diverges from the
+    DID-matlab UTCLeapSeconds ISO-8601 output and from base.schema.json's own
+    default ('2018-12-05T18:36:47.241Z'); a JS ``new Date()`` parses the
+    tz-less form as LOCAL time. Emit '%Y-%m-%dT%H:%M:%S.%fZ' truncated to
+    milliseconds, clamping the (theoretical) leap-second :60 to :59.999.
+    """
+    now = datetime.now(timezone.utc)
+    ts = now.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+    ts = ts.replace(":60.", ":59.999")
+    return ts + "Z"
 
 
 class Document:
@@ -18,7 +30,7 @@ def __init__(self, document_type="base", **kwargs):
         else:
             self.document_properties = self.read_blank_definition(document_type)
             self.document_properties["base"]["id"] = ido.IDO.unique_id()
-            self.document_properties["base"]["datestamp"] = str(_utcnow())
+            self.document_properties["base"]["datestamp"] = _utc_timestamp()
 
             for key, value in kwargs.items():
                 path = key.split(".")
@@ -165,9 +177,22 @@ def read_blank_definition(json_file_location_string):
         if os.path.exists(filepath):
             with open(filepath, "r") as f:
                 data = json.load(f)
+                # Ensure the 'base' key is a dict the constructor can stamp
+                # base.id / base.datestamp onto. base.schema.json stores 'base'
+                # as a LIST of field descriptors (unlike demoA.schema.json,
+                # which has no top-level 'base'), so Document('base') /
+                # Document() used to raise "TypeError: list indices must be
+                # integers". Convert that descriptor list to a {name:
+                # default_value} defaults dict. (This is the narrow constructor
+                # fix only; the broader build-from-database_documents rework is
+                # tracked separately.)
                 if "base" not in data:
                     data["base"] = {}
-                return Document._normalize_to_document_class(data)
+                elif isinstance(data["base"], list):
+                    data["base"] = Document._field_descriptors_to_defaults(data["base"])
+                # Convert flat classname/superclasses to document_class format
+                data = Document._normalize_to_document_class(data)
+                return data
 
         # Fallback for base
         if json_file_location_string == "base":
@@ -263,6 +288,20 @@ def _merge_superclasses(data):
         data["document_class"] = class_props
         return data
 
+    @staticmethod
+    def _field_descriptors_to_defaults(descriptors):
+        """Convert a schema field-descriptor list to a {name: default_value} dict.
+
+        Each descriptor is a dict with at least a 'name' and (usually) a
+        'default_value'. Used to turn base.schema.json's 'base' list into a
+        blank base group the constructor can stamp id/datestamp onto.
+        """
+        defaults = {}
+        for field in descriptors:
+            if isinstance(field, dict) and "name" in field:
+                defaults[field["name"]] = field.get("default_value", "")
+        return defaults
+
     @staticmethod
     def _normalize_to_document_class(data):
         """Convert flat schema format to MATLAB-compatible document_class format."""
 
@@ -2,7 +2,14 @@
 from ..file import Fileobj
 
 
-class BinaryDocMatfid(BinaryDoc, Fileobj):
+class BinaryDocMatfid(Fileobj, BinaryDoc):
+    # NOTE: base order is (Fileobj, BinaryDoc). Previously it was
+    # (BinaryDoc, Fileobj): BinaryDoc.__init__ is a bare ``pass`` that never
+    # calls super().__init__(), so Fileobj.__init__ never ran (fullpathfilename
+    # / permission / fid were unset) and every ``super().f*`` call resolved to
+    # BinaryDoc's abstract no-op stub, so fopen() silently returned None without
+    # opening anything. With Fileobj first in the MRO, __init__ initializes the
+    # file object and the f* methods delegate to real implementations.
     def __init__(self, key="", doc_unique_id="", **kwargs):
         super().__init__(**kwargs)
         self.key = key
@@ -31,11 +38,22 @@ def feof(self):
         return super().feof()
 
     def fwrite(self, data, precision=None, skip=0):
-        # The precision and skip parameters would need to be handled
-        # using Python's struct module for a full implementation.
+        # precision/skip (MATLAB struct-format writes) are not implemented yet.
+        # Fail loudly rather than silently ignoring them and writing raw bytes.
+        if precision is not None or skip:
+            raise NotImplementedError(
+                "BinaryDocMatfid.fwrite does not yet support precision/skip; "
+                "only raw byte writes are supported."
+            )
         return super().fwrite(data)
 
     def fread(self, count=-1, precision=None, skip=0):
-        # The precision and skip parameters would need to be handled
-        # using Python's struct module for a full implementation.
+        # precision/skip (MATLAB struct-format reads) are not implemented yet.
+        # Raise rather than returning None so a caller can't mistake an
+        # unimplemented typed read for an empty file.
+        if precision is not None or skip:
+            raise NotImplementedError(
+                "BinaryDocMatfid.fread does not yet support precision/skip; "
+                "only raw byte reads are supported."
+            )
         return super().fread(count)
@@ -1,3 +1,4 @@
+import json
 import re
 
 
@@ -49,6 +50,14 @@ def _get_superclass_str(doc_props):
     MATLAB produces comma-space separated, sorted unique superclass names.
     For MATLAB-style definitions like "$PATH/base.json", strip path and extension.
     For DID-python style ["base", "demoA"], use directly.
+
+    Schema-v2 (DID-schema V_delta / V_epsilon) names a superclass directly with a
+    bare ``{"class_name": ...}`` object. Read ``class_name`` first but UNION in the
+    ``definition``-derived name rather than short-circuiting, so a mixed-shape entry
+    never silently narrows the superclass set. This mirrors the reference contract
+    in ndi-cloud-node ``api/src/dal/class_lineage.ts`` (``computeClassLineage``) and
+    NDI-python ``ndi.document.doc_superclass``, keeping the SQL ``meta.superclass``
+    column (and both isa paths that read it) consistent across all three stacks.
     """
     # DID-python schema format: top-level 'superclasses' list of strings
     if "superclasses" in doc_props and isinstance(
@@ -65,12 +74,16 @@ def _get_superclass_str(doc_props):
         for sc in superclasses:
             if isinstance(sc, str):
                 names.append(sc)
-            elif isinstance(sc, dict) and "definition" in sc:
-                # MATLAB-style: extract name from definition path
-                defn = sc["definition"]
-                name = re.sub(r".+/", "", defn)
-                name = re.sub(r"\..+$", "", name)
-                names.append(name)
+            elif isinstance(sc, dict):
+                # class_name-first, UNION with the definition-derived name.
+                if sc.get("class_name"):
+                    names.append(sc["class_name"])
+                if sc.get("definition"):
+                    # MATLAB-style: extract name from definition path
+                    defn = sc["definition"]
+                    name = re.sub(r".+/", "", defn)
+                    name = re.sub(r"\..+$", "", name)
+                    names.append(name)
         names = sorted(set(names))
         return ", ".join(names)
 
@@ -82,11 +95,15 @@ def _get_superclass_str(doc_props):
     if isinstance(superclasses, list):
         names = []
         for sc in superclasses:
-            if isinstance(sc, dict) and "definition" in sc:
-                defn = sc["definition"]
-                name = re.sub(r".+/", "", defn)
-                name = re.sub(r"\..+$", "", name)
-                names.append(name)
+            if isinstance(sc, dict):
+                # class_name-first, UNION with the definition-derived name.
+                if sc.get("class_name"):
+                    names.append(sc["class_name"])
+                if sc.get("definition"):
+                    defn = sc["definition"]
+                    name = re.sub(r".+/", "", defn)
+                    name = re.sub(r"\..+$", "", name)
+                    names.append(name)
             elif isinstance(sc, str):
                 names.append(sc)
         names = sorted(set(names))
@@ -115,15 +132,39 @@ def _serialize_depends_on(doc_props):
 
 
 def _flatten_dict(d, prefix=""):
-    """Flatten a nested dict using ___ separator for nested keys (matching MATLAB's getMetaTableFrom)."""
+    """Flatten a nested dict using ___ separator for nested keys.
+
+    Matches DID-matlab getMetaTableFrom/recurseFields:
+
+    * nested dicts recurse with a ``___`` separator;
+    * a list of dicts (a struct array) expands into one column per element,
+      each element's flattened column suffixed ``_<1-based idx>`` — but ONLY
+      when the list has more than one element (a single-element list is
+      unsuffixed, mirroring doc2sql.m's ``numElements > 1`` rule);
+    * any residual scalar/mixed list is JSON-encoded (not ``str()``-repr'd) so
+      the stored value is valid JSON parseable by MATLAB/JS consumers instead
+      of a Python repr with single quotes.
+
+    Previously every list was ``str(value)``'d into one column, so per-element
+    fields were unsearchable and the stored string disagreed with what
+    DID-matlab writes for the same document.
+    """
     items = []
     for key, value in d.items():
         col_name = f"{prefix}___{key}" if prefix else key
         if isinstance(value, dict):
             items.extend(_flatten_dict(value, col_name))
         elif isinstance(value, list):
-            # Convert lists to string representation
-            items.append((col_name, str(value)))
+            if value and all(isinstance(el, dict) for el in value):
+                # Struct array: expand per element.
+                multi = len(value) > 1
+                for idx, el in enumerate(value, start=1):
+                    for sub_name, sub_val in _flatten_dict(el, col_name):
+                        name = f"{sub_name}_{idx}" if multi else sub_name
+                        items.append((name, sub_val))
+            else:
+                # Scalar / empty / mixed list: JSON-encode.
+                items.append((col_name, json.dumps(value)))
         else:
             items.append((col_name, value))
     return items