From 057475c4c522233d336a1b057e970eb81396d22e Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 08:55:55 +0200
Subject: [PATCH 1/9] Read an inventory from an authoring directory

An inventory can now be laid out as a directory of YAML or JSON object
files, which dc.inventory loads: file declares type, container agrees,
name implies identity, envelope implies version. Names are addresses, so
the nested tree materializes from a flat directory and a network or
fiber array mentioned only by an address exists.

Track CSVs and optical path epoch directories are refused by name until
they can be read, rather than loading an entity which silently lacks the
tracks its own directory states.
---
 dascore/__init__.py                      |   3 +-
 dascore/core/inventory.py                |  26 -
 dascore/core/inventory_loader.py         | 715 +++++++++++++++++++++++
 tests/test_core/test_inventory_loader.py | 674 +++++++++++++++++++++
 4 files changed, 1391 insertions(+), 27 deletions(-)
 create mode 100644 dascore/core/inventory_loader.py
 create mode 100644 tests/test_core/test_inventory_loader.py

diff --git a/dascore/__init__.py b/dascore/__init__.py
index 491f97617..814348f56 100644
--- a/dascore/__init__.py
+++ b/dascore/__init__.py
@@ -9,7 +9,8 @@
 from dascore.core.attrs import PatchAttrs
 from dascore.core.summary import PatchSummary
 from dascore.core.spool import BaseSpool, Spool, spool
-from dascore.core.inventory import Inventory, inventory
+from dascore.core.inventory import Inventory
+from dascore.core.inventory_loader import inventory
 from dascore.core.coordmanager import get_coord_manager, CoordManager
 from dascore.core.coords import get_coord
 from dascore.config import (
diff --git a/dascore/core/inventory.py b/dascore/core/inventory.py
index 46511204e..47fae6b60 100644
--- a/dascore/core/inventory.py
+++ b/dascore/core/inventory.py
@@ -2307,29 +2307,3 @@ def from_yaml(cls, source) -> Self:
             msg = f"Could not parse an inventory mapping from {source!r}."
             raise InvalidInventoryError(msg)
         return cls(**data).check()
-
-
-def inventory(source=None) -> Inventory:
-    """
-    Load or create a DASDAE inventory.
-
-    Parameters
-    ----------
-    source
-        An existing Inventory (returned as is), a YAML file path or YAML
-        text, or None for an empty inventory.
-
-    Examples
-    --------
-    >>> import dascore as dc
-    >>> empty = dc.inventory()
-    >>> assert dc.inventory(empty) is empty
-    """
-    if source is None:
-        return Inventory()
-    if isinstance(source, Inventory):
-        return source
-    if isinstance(source, str | os.PathLike):
-        return Inventory.from_yaml(source)
-    msg = f"Could not get an inventory from {source!r}."
-    raise InvalidInventoryError(msg)
diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
new file mode 100644
index 000000000..f67f3688e
--- /dev/null
+++ b/dascore/core/inventory_loader.py
@@ -0,0 +1,715 @@
+"""
+Load a DASDAE inventory from an authoring directory.
+
+The authoring format splits an inventory along its natural grain: small
+heterogeneous objects (acquisitions, interrogators, cables) live in YAML or
+JSON files matching the models, while long row-shaped track data lives in
+CSV files a field crew can maintain as a spreadsheet. A directory of these
+files is itself a loadable inventory, and ``to_yaml`` exports the
+single-file interchange artifact for shipping beside a data archive.
+
+The contract, in one line: **file declares type, container agrees, name
+implies identity, envelope implies version.** Every object file states what
+it is, its container checks that statement rather than supplying it, its
+name decides which entity it is, and the top-level ``inventory.yaml``
+versions the whole document. An address restated inside a file must agree
+with the name; there is never a precedence rule between two spellings of
+one fact.
+
+Loading is strict about near-misses and indifferent to clean misses:
+anything which claims to participate in a convention and gets it wrong
+raises, while anything which does not participate -- photos, field notes,
+deployment logs -- is ignored where it lies.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections import defaultdict
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, NamedTuple
+
+import pandas as pd
+
+from dascore.core.inventory import (
+    Acquisition,
+    Cable,
+    Enclosure,
+    ExternalResource,
+    FiberArray,
+    Interrogator,
+    Inventory,
+    Network,
+    OpticalMeasurement,
+    Station,
+)
+from dascore.exceptions import InvalidInventoryError
+from dascore.utils.misc import optional_import
+from dascore.utils.models import InventoryModel, TimeRangedModel
+from dascore.utils.time import to_datetime64
+
+# One data model stands behind all three spellings, so they are accepted
+# identically -- but one identity may only be spelled once.
+_OBJECT_SUFFIXES = (".yaml", ".yml", ".json")
+
+# The object file of an entity directory, and the envelope at the root.
+_ATTRS_STEM = "attrs"
+_ENVELOPE_STEM = "inventory"
+
+# Separates an entity's name from the epoch it starts.
+_EPOCH_MARKER = "@"
+
+# The reserved container stem: unlike an attribute table, these directories
+# address a child entity whose name carries its epoch.
+_PATH_STEM = "path"
+
+# The document-level collections, which live in the directory structure
+# rather than in the envelope.
+_ENVELOPE_COLLECTIONS = ("networks", "resources")
+
+# Address levels which name a containing entity rather than a field of the
+# entity being named.
+_ADDRESS_LEVELS = ("network", "fiber_array")
+
+
+class _Container(NamedTuple):
+    """How one top-level directory maps entry names onto models."""
+
+    models: tuple[type[InventoryModel], ...]
+    # The dotted tokens an entry name holds, outermost first. A token which
+    # names a field of the model states that field; the rest are
+    # _ADDRESS_LEVELS naming the entity which contains it.
+    identity: tuple[str, ...]
+
+
+_CONTAINERS: Mapping[str, _Container] = {
+    "resources": _Container(
+        (Interrogator, Cable, Enclosure, ExternalResource, OpticalMeasurement),
+        ("resource_id",),
+    ),
+    "networks": _Container((Network,), ("code",)),
+    "fiber_arrays": _Container((FiberArray,), ("network", "code")),
+    "stations": _Container((Station,), ("network", "code")),
+    "acquisitions": _Container(
+        (Acquisition,), ("network", "fiber_array", "location_code", "code")
+    ),
+}
+
+
+class _Entry(NamedTuple):
+    """One loaded entity, with where it came from and what contains it."""
+
+    model: InventoryModel
+    source: Path
+    # This entry's _ADDRESS_LEVELS tokens, outermost first.
+    address: tuple[str, ...]
+
+
+def _model_names() -> frozenset[str]:
+    """
+    Return the name of every inventory model.
+
+    A file declaring one of these is claiming to be part of an inventory,
+    which is what makes it a near-miss rather than field material when it
+    turns up somewhere unrecognized.
+    """
+
+    def walk(model):
+        yield model.__name__
+        for sub in model.__subclasses__():
+            yield from walk(sub)
+
+    return frozenset(walk(InventoryModel)) | {Inventory.__name__}
+
+
+def _quote(path: Path) -> str:
+    """
+    Name a file for an error message.
+
+    Its container is included because a bare name is ambiguous across
+    containers and the full path is noise the reader already knows.
+    """
+    return str(Path(path.parent.name) / path.name)
+
+
+def _entry_name(path: Path) -> str:
+    """
+    Return the address an entry's name states.
+
+    ``Path.stem`` cannot be used: an address is full of dots, so it would
+    read ``DAS.L001`` as the stem ``DAS`` with a suffix.
+    """
+    if path.is_dir() or path.suffix not in _OBJECT_SUFFIXES:
+        return path.name
+    return path.name[: -len(path.suffix)]
+
+
+def _read_object(path: Path) -> dict[str, Any]:
+    """
+    Parse one YAML or JSON object file into a mapping.
+
+    Both spellings share one data model, so the suffix picks the parser
+    and decides nothing else.
+    """
+    try:
+        text = path.read_text()
+    except (OSError, UnicodeDecodeError) as error:
+        msg = f"Could not read {_quote(path)}: {error}."
+        raise InvalidInventoryError(msg) from error
+    if path.suffix == ".json":
+        try:
+            data = json.loads(text)
+        except ValueError as error:
+            msg = f"Could not parse JSON from {_quote(path)}: {error}."
+            raise InvalidInventoryError(msg) from error
+    else:
+        yaml = optional_import("yaml", required_for="YAML inventory serialization")
+        try:
+            data = yaml.safe_load(text)
+        except yaml.YAMLError as error:
+            msg = f"Could not parse YAML from {_quote(path)}: {error}."
+            raise InvalidInventoryError(msg) from error
+    if not isinstance(data, Mapping):
+        msg = f"{_quote(path)} holds no mapping, so it defines no object."
+        raise InvalidInventoryError(msg)
+    return dict(data)
+
+
+def _declared_type(path: Path) -> str | None:
+    """
+    Return the model type a file declares, or None if it declares none.
+
+    This tells field material from a misfiled object, so a file which does
+    not parse simply is not an object: a YAML-suffixed file under a photos
+    directory owes this format nothing.
+    """
+    try:
+        data = _read_object(path)
+    except InvalidInventoryError:
+        return None
+    declared = data.get("type")
+    return declared if isinstance(declared, str) else None
+
+
+# The date is extended ISO 8601 and the time is basic, because ':' is not a
+# legal filename character on Windows.
+_EPOCH_RE = re.compile(r"(?P<date>\d{4}-\d{2}-\d{2})(?:T(?P<time>\d{6}(?:\.\d+)?))?")
+
+
+def _parse_epoch(text: str, source: Path):
+    """
+    Parse the timestamp an entity name states after its ``@``.
+
+    All inventory timestamps are UTC, so a designator saying so -- or
+    saying otherwise -- is refused rather than ignored.
+    """
+    where = f"in the name of {_quote(source)}"
+    date, _, time = text.partition("T")
+    if text.endswith("Z") or "+" in text or "-" in time:
+        msg = (
+            f"Epoch timestamp {text!r} {where} carries a timezone designator. "
+            "Inventory timestamps are UTC and take none."
+        )
+        raise InvalidInventoryError(msg)
+    unreadable = (
+        f"Could not read an epoch timestamp from {text!r} {where}. Expected a "
+        "date (2024-06-01) or a date and an ISO basic time "
+        "(2024-05-12T103000, fractional seconds as T103000.12)"
+    )
+    if (match := _EPOCH_RE.fullmatch(text)) is None:
+        raise InvalidInventoryError(f"{unreadable}.")
+    time = match["time"] or "000000"
+    try:
+        return to_datetime64(f"{date}T{time[:2]}:{time[2:4]}:{time[4:]}")
+    except ValueError as error:
+        # The pattern admits digits which name no instant, e.g. a 13th month.
+        raise InvalidInventoryError(f"{unreadable}: {error}") from error
+
+
+def _split_epoch(source: Path, epochs_allowed: bool):
+    """Split an entry name into the address and the epoch it starts."""
+    name, marker, epoch_text = _entry_name(source).partition(_EPOCH_MARKER)
+    if not marker:
+        return name, None
+    if not epochs_allowed:
+        msg = (
+            f"{_quote(source)} names an epoch with {_EPOCH_MARKER!r}, but "
+            f"{source.parent.name} have none."
+        )
+        raise InvalidInventoryError(msg)
+    if _EPOCH_MARKER in epoch_text:
+        msg = (
+            f"{_quote(source)} states more than one {_EPOCH_MARKER!r}; a name "
+            "carries at most one epoch."
+        )
+        raise InvalidInventoryError(msg)
+    if not epoch_text:
+        msg = f"{_quote(source)} ends in {_EPOCH_MARKER!r} but names no epoch."
+        raise InvalidInventoryError(msg)
+    return name, _parse_epoch(epoch_text, source)
+
+
+def _pick_model(data: dict, container: _Container, source: Path):
+    """
+    Return the model a file declares, checking its container agrees.
+
+    The container never supplies the type: a file which does not say what
+    it is has not participated in the format, and one which says something
+    its container cannot hold is misfiled rather than reinterpreted.
+    """
+    declared = data.get("type")
+    legal = tuple(x.__name__ for x in container.models)
+    if declared is None:
+        msg = (
+            f"{_quote(source)} declares no type. Every object file states "
+            f"what it is, e.g. 'type: {legal[0]}'."
+        )
+        raise InvalidInventoryError(msg)
+    for model in container.models:
+        if model.__name__ == declared:
+            # The tag is a real, discriminating field only on the models
+            # which share a union; everywhere else it belongs to the format.
+            if "type" not in model.model_fields:
+                data.pop("type")
+            return model
+    known = "an inventory model" if declared in _model_names() else "unknown"
+    msg = (
+        f"{_quote(source)} declares type {declared!r} ({known}), which "
+        f"{source.parent.name} cannot hold. Expected one of {legal}."
+    )
+    raise InvalidInventoryError(msg)
+
+
+def _build(model, data: dict, source: Path):
+    """Validate one mapping into its model, naming the file if it fails."""
+    if "schema_version" in data:
+        msg = (
+            f"{_quote(source)} states a schema_version. The envelope versions "
+            "the document exactly once; individual files never do."
+        )
+        raise InvalidInventoryError(msg)
+    try:
+        return model(**data)
+    except Exception as error:
+        msg = f"Could not read {model.__name__} from {_quote(source)}: {error}"
+        raise InvalidInventoryError(msg) from error
+
+
+def _apply_identity(data: dict, container: _Container, name: str, source: Path):
+    """
+    Fill the fields an entry's name states, and return its address.
+
+    A name is an address, so the tokens it holds are facts about the
+    entity. A file may restate them, but a restatement which disagrees is
+    an error rather than an override.
+    """
+    # A single-token identity is the whole name: a resource_id is free-form
+    # and may hold the dots an address would have split on.
+    tokens = name.split(".") if len(container.identity) > 1 else [name]
+    if len(tokens) != len(container.identity):
+        spelled = ".".join(f"<{x}>" for x in container.identity)
+        msg = (
+            f"{_quote(source)} holds {len(tokens)} dot separated tokens, but "
+            f"its name is an address of {len(container.identity)}: {spelled}."
+        )
+        raise InvalidInventoryError(msg)
+    address = []
+    for token, field in zip(tokens, container.identity, strict=True):
+        if field in _ADDRESS_LEVELS:
+            address.append(token)
+            continue
+        stated = data.setdefault(field, token)
+        if stated != token:
+            msg = (
+                f"{_quote(source)} states {field}={stated!r} but its name says "
+                f"{token!r}. A restated address must agree with the name."
+            )
+            raise InvalidInventoryError(msg)
+    return tuple(address)
+
+
+def _load_entry(entry: Path, data_source: Path, container: _Container) -> _Entry:
+    """Load one entry of a container from its object file."""
+    data = _read_object(data_source)
+    model = _pick_model(data, container, data_source)
+    name, epoch = _split_epoch(entry, issubclass(model, TimeRangedModel))
+    address = _apply_identity(data, container, name, data_source)
+    if epoch is not None and "start_time" not in data:
+        data["start_time"] = epoch
+    built = _build(model, data, data_source)
+    if epoch is not None and built.start_time != epoch:
+        msg = (
+            f"{_quote(data_source)} states start_time {built.start_time} but "
+            f"its name says {epoch}. A restated address must agree with the "
+            "name."
+        )
+        raise InvalidInventoryError(msg)
+    return _Entry(built, data_source, address)
+
+
+def _refuse_tracks(entity: Path) -> None:
+    """
+    Refuse the parts of an entity directory which cannot be read yet.
+
+    Track tables and optical path epochs are the next piece of this
+    format. Refusing them by name beats loading an entity which silently
+    lacks the tracks its own directory states.
+    """
+    for child in sorted(entity.iterdir()):
+        if child.name.startswith("."):
+            continue
+        stem = child.name.partition(_EPOCH_MARKER)[0].partition(".")[0]
+        if child.is_dir() and stem == _PATH_STEM:
+            msg = (
+                f"{_quote(child)} is an optical path epoch, which cannot be "
+                "read yet. State optical_paths in the entity's "
+                f"{_ATTRS_STEM} file for now."
+            )
+            raise InvalidInventoryError(msg)
+        if child.suffix == ".csv":
+            msg = (
+                f"{_quote(child)} is a track table, which cannot be read yet. "
+                f"State {_entry_name(child)} in the entity's {_ATTRS_STEM} "
+                "file for now."
+            )
+            raise InvalidInventoryError(msg)
+
+
+def _attrs_file(entity: Path) -> Path:
+    """Return the object file of an entity directory, refusing strays."""
+    found = []
+    for child in sorted(entity.iterdir()):
+        if child.is_dir() or child.name.startswith("."):
+            continue
+        if child.suffix not in _OBJECT_SUFFIXES:
+            continue
+        if _entry_name(child) != _ATTRS_STEM:
+            msg = (
+                f"{_quote(child)} is not part of an entity directory, whose "
+                f"object file is named {_ATTRS_STEM}."
+            )
+            raise InvalidInventoryError(msg)
+        found.append(child)
+    if not found:
+        msg = (
+            f"{_quote(entity)} holds no {_ATTRS_STEM} file, so it states "
+            "nothing about the entity it names."
+        )
+        raise InvalidInventoryError(msg)
+    if len(found) > 1:
+        spelled = ", ".join(x.name for x in found)
+        msg = (
+            f"{_quote(entity)} spells its object file more than once "
+            f"({spelled}); one identity is spelled once."
+        )
+        raise InvalidInventoryError(msg)
+    return found[0]
+
+
+def _collide(first: Path, second: Path) -> str:
+    """Explain why two entries of one container name one identity."""
+    if _entry_name(first) != _entry_name(second):
+        return "differ only by case, which a case-insensitive filesystem cannot hold"
+    if first.is_dir() != second.is_dir():
+        return "spell one identity as both a file and a directory"
+    return "spell one identity with two extensions"
+
+
+def _container_entries(directory: Path) -> list[Path]:
+    """
+    Return the entries of a container directory, one per identity.
+
+    Identity is unique per container regardless of spelling, so two names
+    differing only by case, or one name spelled as both a file and a
+    directory, are two spellings of one thing rather than two things.
+    """
+    seen: dict[str, Path] = {}
+    for child in sorted(directory.iterdir()):
+        if child.name.startswith("."):
+            continue
+        if child.is_file() and child.suffix not in _OBJECT_SUFFIXES:
+            if child.suffix == ".csv":
+                msg = (
+                    f"{_quote(child)} is a track table outside an entity "
+                    "directory; a table lives beside the attrs file of the "
+                    "entity whose tracks it holds."
+                )
+                raise InvalidInventoryError(msg)
+            continue
+        key = _entry_name(child).casefold()
+        if (first := seen.get(key)) is not None:
+            msg = f"{_quote(first)} and {_quote(child)} {_collide(first, child)}."
+            raise InvalidInventoryError(msg)
+        seen[key] = child
+    return list(seen.values())
+
+
+def _load_container(directory: Path, container: _Container) -> list[_Entry]:
+    """Load every entry of one top-level container directory."""
+    out = []
+    for child in _container_entries(directory):
+        if child.is_dir():
+            _refuse_tracks(child)
+            data_source = _attrs_file(child)
+        else:
+            data_source = child
+        out.append(_load_entry(child, data_source, container))
+    return out
+
+
+def _check_epoch_duplicates(entries: list[_Entry]) -> None:
+    """
+    Refuse two entries which name one identity at one instant.
+
+    Epoch-name uniqueness is temporal rather than textual, so
+    ``@2024-06-01`` and ``@2024-06-01T000000`` are two spellings of one
+    epoch. The models catch the overlap; the files are what the author can
+    act on.
+    """
+    seen: dict[Any, Path] = {}
+    for entry in entries:
+        model = entry.model
+        key = (
+            *entry.address,
+            model.code,
+            getattr(model, "location_code", ""),
+            model.start_time,
+        )
+        if (first := seen.get(key)) is not None:
+            msg = (
+                f"{_quote(first)} and {_quote(entry.source)} name one entity "
+                "at one instant, so they are two spellings of one epoch."
+            )
+            raise InvalidInventoryError(msg)
+        seen[key] = entry.source
+    return None
+
+
+def _place(children: list[_Entry], parents: list[_Entry], kind: str):
+    """
+    Group children by the parent epoch each one falls in.
+
+    An epoch is chosen the way every other resolution chooses one, by
+    time. A child falling in no epoch of its container is misfiled, and
+    one falling in several -- including one whose own start is unset while
+    its container has more than one epoch -- is ambiguous rather than
+    resolved.
+    """
+    out = defaultdict(list)
+    for child in children:
+        matches = [
+            index
+            for index, parent in enumerate(parents)
+            if parent.model.is_effective_at(child.model.start_time)
+        ]
+        if len(matches) != 1:
+            start = child.model.start_time
+            when = "at any time" if pd.isnull(start) else f"at {start}"
+            named = ".".join(child.address)
+            msg = (
+                f"{_quote(child.source)} belongs to {kind} {named!r}, which "
+                f"has {len(matches)} epochs effective {when}."
+            )
+            raise InvalidInventoryError(msg)
+        out[matches[0]].append(child)
+    return out
+
+
+def _group(entries: list[_Entry]) -> Mapping[tuple, list[_Entry]]:
+    """Group entries by the address which names their container."""
+    out = defaultdict(list)
+    for entry in entries:
+        out[entry.address].append(entry)
+    return out
+
+
+def _fill_arrays(arrays: list[_Entry], acquisitions: list[_Entry]) -> list[_Entry]:
+    """
+    Put every acquisition in the fiber array epoch which held it.
+
+    An array named only by an acquisition's address exists, the same way a
+    network named only by an array's address does; the hierarchy is never
+    built by nesting.
+    """
+    # An acquisition's address names its array, so an array is grouped by the
+    # address it answers to rather than by the one which contains it.
+    by_address = _group(acquisitions)
+    grouped = defaultdict(list)
+    for entry in arrays:
+        grouped[(*entry.address, entry.model.code)].append(entry)
+    out = []
+    for address, entries in grouped.items():
+        placed = _place(by_address.pop(address, []), entries, "fiber array")
+        for index, entry in enumerate(entries):
+            if not (acqs := placed.get(index)):
+                out.append(entry)
+                continue
+            models = tuple(x.model for x in acqs)
+            out.append(entry._replace(model=entry.model.new(acquisitions=models)))
+    for address, entries in by_address.items():
+        model = FiberArray(
+            code=address[1], acquisitions=tuple(x.model for x in entries)
+        )
+        out.append(_Entry(model, entries[0].source, address[:1]))
+    return out
+
+
+def _assemble(entries: Mapping[str, list[_Entry]]) -> tuple[Network, ...]:
+    """
+    Build the network tree a flat directory addresses.
+
+    The hierarchy materializes from names rather than from nesting, so a
+    network mentioned by an address exists whether or not a file declares
+    it.
+    """
+    arrays = _fill_arrays(
+        entries.get("fiber_arrays", []), entries.get("acquisitions", [])
+    )
+    stations = entries.get("stations", [])
+    by_code = defaultdict(list)
+    for entry in entries.get("networks", []):
+        by_code[entry.model.code].append(entry)
+    for entry in (*arrays, *stations):
+        by_code.setdefault(entry.address[0], [])
+    out = []
+    for code, network_entries in by_code.items():
+        if not network_entries:
+            # A network named only by an address is an undated container.
+            network_entries = [_Entry(Network(code=code), Path(code), ())]
+        arrays_here = [x for x in arrays if x.address[0] == code]
+        stations_here = [x for x in stations if x.address[0] == code]
+        by_array = _place(arrays_here, network_entries, "network")
+        by_station = _place(stations_here, network_entries, "network")
+        for index, entry in enumerate(network_entries):
+            out.append(
+                entry.model.new(
+                    fiber_arrays=tuple(x.model for x in by_array.get(index, [])),
+                    stations=tuple(x.model for x in by_station.get(index, [])),
+                )
+            )
+    return tuple(out)
+
+
+def _load_envelope(root: Path) -> dict[str, Any]:
+    """
+    Read the document-level singletons from the envelope.
+
+    The envelope is optional while authoring -- a bare directory of fiber
+    arrays and acquisitions loads with defaults -- but it is the one place
+    the document's version and CRS may be stated.
+    """
+    found = [
+        candidate
+        for suffix in _OBJECT_SUFFIXES
+        if (candidate := root / f"{_ENVELOPE_STEM}{suffix}").is_file()
+    ]
+    if not found:
+        return {}
+    if len(found) > 1:
+        spelled = ", ".join(x.name for x in found)
+        msg = f"The envelope is spelled more than once ({spelled})."
+        raise InvalidInventoryError(msg)
+    source = found[0]
+    data = _read_object(source)
+    if (declared := data.pop("type", None)) != Inventory.__name__:
+        msg = (
+            f"{_quote(source)} declares type {declared!r}; the envelope "
+            f"declares 'type: {Inventory.__name__}'."
+        )
+        raise InvalidInventoryError(msg)
+    for field in _ENVELOPE_COLLECTIONS:
+        if field in data:
+            msg = (
+                f"{_quote(source)} states {field}, which live in the directory "
+                "structure rather than in the envelope."
+            )
+            raise InvalidInventoryError(msg)
+    return data
+
+
+def _check_strays(root: Path) -> None:
+    """
+    Refuse a model-declaring file which nothing contains.
+
+    A typo like ``aquisitions/`` must not quietly load an inventory with
+    no acquisitions, while the field material beside it stays welcome.
+    """
+    known = _model_names()
+
+    def check(path: Path):
+        if path.name.startswith("."):
+            return
+        if path.is_dir():
+            for child in sorted(path.iterdir()):
+                check(child)
+        elif path.suffix in _OBJECT_SUFFIXES:
+            if (declared := _declared_type(path)) in known:
+                msg = (
+                    f"{path.relative_to(root)} declares type {declared!r} but "
+                    "nothing contains it. Inventory objects live in "
+                    f"{tuple(_CONTAINERS)}."
+                )
+                raise InvalidInventoryError(msg)
+
+    for child in sorted(root.iterdir()):
+        if child.is_dir() and child.name in _CONTAINERS:
+            continue
+        if child.is_file() and _entry_name(child) == _ENVELOPE_STEM:
+            continue
+        check(child)
+
+
+def load_directory(path) -> Inventory:
+    """
+    Load an inventory from a directory in the authoring format.
+
+    Parameters
+    ----------
+    path
+        The inventory directory.
+    """
+    root = Path(path)
+    envelope = _load_envelope(root)
+    entries = {
+        name: _load_container(root / name, container)
+        for name, container in _CONTAINERS.items()
+        if (root / name).is_dir()
+    }
+    _check_strays(root)
+    for name in ("networks", "fiber_arrays", "stations", "acquisitions"):
+        _check_epoch_duplicates(entries.get(name, []))
+    resources = {x.model.resource_id: x.model for x in entries.get("resources", [])}
+    networks = _assemble(entries)
+    return Inventory(**envelope, resources=resources, networks=networks).check()
+
+
+def inventory(source=None) -> Inventory:
+    """
+    Load or create a DASDAE inventory.
+
+    Parameters
+    ----------
+    source
+        An existing Inventory (returned as is), a directory in the
+        authoring format, a YAML file path or YAML text, or None for an
+        empty inventory.
+
+    Examples
+    --------
+    >>> import dascore as dc
+    >>> empty = dc.inventory()
+    >>> assert dc.inventory(empty) is empty
+    """
+    if source is None:
+        return Inventory()
+    if isinstance(source, Inventory):
+        return source
+    if isinstance(source, str | os.PathLike):
+        if os.path.isdir(source):
+            return load_directory(source)
+        return Inventory.from_yaml(source)
+    msg = f"Could not get an inventory from {source!r}."
+    raise InvalidInventoryError(msg)
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
new file mode 100644
index 000000000..374b4a770
--- /dev/null
+++ b/tests/test_core/test_inventory_loader.py
@@ -0,0 +1,674 @@
+"""Tests for loading an inventory from an authoring directory."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+import dascore as dc
+from dascore.core import inventory as inv
+from dascore.core import inventory_loader as loader
+from dascore.exceptions import InvalidInventoryError
+from dascore.utils.models import InventoryModel, TimeRangedModel
+
+pytest.importorskip("yaml")
+
+
+# A minimal directory which loads: one acquisition names everything above it.
+MINIMAL = {
+    "acquisitions/DAS.L001..RAW.yaml": "type: Acquisition\ndata_category: DAS\n",
+}
+
+
+def write_inventory(root, files) -> object:
+    """Write a mapping of relative path to text under root."""
+    for name, text in files.items():
+        path = root / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text)
+    return root
+
+
+@pytest.fixture
+def make_inventory(tmp_path):
+    """Return a function which writes a directory and loads it."""
+
+    def build(files, name="my_inventory"):
+        return dc.inventory(write_inventory(tmp_path / name, files))
+
+    return build
+
+
+class TestRegistry:
+    """The container registry must stay pinned to the models."""
+
+    def test_identity_tokens_are_fields_or_levels(self):
+        """Every name token states a field or names a containing entity."""
+        for container in loader._CONTAINERS.values():
+            for model in container.models:
+                for token in container.identity:
+                    known = token in model.model_fields
+                    assert known or token in loader._ADDRESS_LEVELS
+
+    def test_resource_container_matches_the_union(self):
+        """The resources container holds exactly the resource union."""
+        union = inv.get_args(inv.get_args(inv._Resource)[0])
+        assert set(loader._CONTAINERS["resources"].models) == set(union)
+
+    def test_every_model_name_is_known(self):
+        """A model this loader can build counts as a model for near-misses."""
+        names = loader._model_names()
+        for container in loader._CONTAINERS.values():
+            assert {x.__name__ for x in container.models} <= names
+        assert "Inventory" in names
+
+
+class TestLoadDirectory:
+    """Tests for loading a well-formed directory."""
+
+    def test_minimal_directory(self, make_inventory):
+        """One acquisition file names the network and array which hold it."""
+        out = make_inventory(MINIMAL)
+        assert [x.code for x in out.networks] == ["DAS"]
+        array = out.networks[0].fiber_arrays[0]
+        assert array.code == "L001"
+        assert [x.code for x in array.acquisitions] == ["RAW"]
+        # The blank token is a location code, which may be blank.
+        assert array.acquisitions[0].location_code == ""
+
+    def test_resolves_like_any_inventory(self, make_inventory):
+        """A loaded inventory answers the key its directory spells."""
+        out = make_inventory(
+            {
+                "acquisitions/DAS.L001..RAW.yaml": (
+                    "type: Acquisition\ndata_category: DAS\ngauge_length: 10.0\n"
+                ),
+            }
+        )
+        assert out.resolve("DAS.L001..RAW").acquisition.gauge_length == 10.0
+
+    def test_full_directory(self, make_inventory):
+        """Every container contributes to one inventory."""
+        out = make_inventory(
+            {
+                "inventory.yaml": "type: Inventory\nschema_version: 1\n",
+                "resources/int_01.yaml": (
+                    "type: Interrogator\nmanufacturer: Fake\nmodel: FI-1\n"
+                ),
+                "networks/DAS.yaml": "type: Network\nname: test network\n",
+                "fiber_arrays/DAS.L001.yaml": "type: FiberArray\nname: first\n",
+                "stations/DAS.STA1.yaml": "type: Station\nname: a station\n",
+                "acquisitions/DAS.L001..RAW.yaml": (
+                    "type: Acquisition\ndata_category: DAS\ninterrogator: int_01\n"
+                ),
+            }
+        )
+        network = out.networks[0]
+        assert network.name == "test network"
+        assert [x.code for x in network.stations] == ["STA1"]
+        assert network.fiber_arrays[0].name == "first"
+        # The reference resolved against the pool the resources dir filled.
+        assert out.get_resource("int_01").model == "FI-1"
+
+    def test_json_and_yaml_are_interchangeable(self, tmp_path):
+        """One data model stands behind both spellings."""
+        as_yaml = dc.inventory(
+            write_inventory(
+                tmp_path / "yaml_form",
+                {
+                    "acquisitions/DAS.L001..RAW.yaml": (
+                        "type: Acquisition\ndata_category: DAS\ngauge_length: 4.0\n"
+                    )
+                },
+            )
+        )
+        as_json = dc.inventory(
+            write_inventory(
+                tmp_path / "json_form",
+                {
+                    "acquisitions/DAS.L001..RAW.json": (
+                        '{"type": "Acquisition", "data_category": "DAS", '
+                        '"gauge_length": 4.0}'
+                    )
+                },
+            )
+        )
+        assert as_yaml.networks == as_json.networks
+
+    def test_yml_suffix(self, make_inventory):
+        """The short YAML suffix is the same spelling."""
+        out = make_inventory({"acquisitions/DAS.L001..RAW.yml": "type: Acquisition\n"})
+        assert out.networks[0].fiber_arrays[0].acquisitions[0].code == "RAW"
+
+    def test_envelope_is_optional(self, make_inventory):
+        """A bare directory loads with envelope defaults."""
+        out = make_inventory(MINIMAL)
+        assert out.schema_version == inv.Inventory().schema_version
+
+    def test_envelope_states_the_singletons(self, make_inventory):
+        """The envelope is where the document's own facts live."""
+        out = make_inventory(
+            {
+                **MINIMAL,
+                "inventory.yaml": (
+                    "type: Inventory\n"
+                    "resource_id: my-inventory\n"
+                    "coordinate_reference_system:\n"
+                    "  authority: EPSG\n"
+                    "  code: '32611'\n"
+                    "  coordinate_labels: [easting, northing, elevation]\n"
+                ),
+            }
+        )
+        assert out.resource_id == "my-inventory"
+        assert out.coordinate_reference_system.code == "32611"
+
+    def test_entity_directory_form(self, make_inventory):
+        """An entity is a file until it needs tracks, then a directory."""
+        out = make_inventory(
+            {
+                **MINIMAL,
+                "fiber_arrays/DAS.L001/attrs.yaml": (
+                    "type: FiberArray\nname: from a directory\n"
+                ),
+            }
+        )
+        assert out.networks[0].fiber_arrays[0].name == "from a directory"
+
+    def test_non_participating_files_are_ignored(self, make_inventory):
+        """Field material lives happily inside the inventory directory."""
+        out = make_inventory(
+            {
+                **MINIMAL,
+                "photos/wellhead.jpg": "not text",
+                "notes/log.md": "# deployment log\n",
+                # A YAML file which declares nothing is not an object.
+                "notes/scratch.yaml": "just: a note\n",
+                # Nor is one which does not parse at all.
+                "notes/broken.yaml": "{[unclosed\n",
+                ".hidden/DAS.yaml": "type: Network\n",
+                "acquisitions/README.txt": "a note beside the objects\n",
+            }
+        )
+        assert [x.code for x in out.networks] == ["DAS"]
+
+    def test_resource_id_may_hold_dots(self, make_inventory):
+        """A single-token identity is the whole name, dots and all."""
+        out = make_inventory(
+            {
+                **MINIMAL,
+                "resources/cable.01.yaml": "type: Cable\nname: a cable\n",
+            }
+        )
+        assert out.get_resource("cable.01").name == "a cable"
+
+    def test_restated_address_may_agree(self, make_inventory):
+        """A name may be restated inside the file when the two agree."""
+        out = make_inventory(
+            {
+                "acquisitions/DAS.L001.01.RAW.yaml": (
+                    "type: Acquisition\ncode: RAW\nlocation_code: '01'\n"
+                )
+            }
+        )
+        acquisition = out.networks[0].fiber_arrays[0].acquisitions[0]
+        assert (acquisition.location_code, acquisition.code) == ("01", "RAW")
+
+
+class TestEpochNames:
+    """Tests for the ``@`` epoch suffix."""
+
+    def test_date_only_means_midnight_utc(self, make_inventory):
+        """A date-only suffix is valid when that precision suffices."""
+        out = make_inventory(
+            {"acquisitions/DAS.L001..RAW@2024-06-01.yaml": "type: Acquisition\n"}
+        )
+        acquisition = out.networks[0].fiber_arrays[0].acquisitions[0]
+        assert acquisition.start_time == np.datetime64("2024-06-01T00:00:00", "ns")
+
+    def test_basic_time_and_fractional_seconds(self, make_inventory):
+        """The time portion is ISO basic, since ':' is not a legal filename."""
+        out = make_inventory(
+            {
+                "acquisitions/DAS.L001..RAW@2024-05-12T103000.12.yaml": (
+                    "type: Acquisition\n"
+                )
+            }
+        )
+        acquisition = out.networks[0].fiber_arrays[0].acquisitions[0]
+        expected = np.datetime64("2024-05-12T10:30:00.12", "ns")
+        assert acquisition.start_time == expected
+
+    def test_suffix_agrees_with_stated_start(self, make_inventory):
+        """A restated start time is checked rather than overridden."""
+        out = make_inventory(
+            {
+                "acquisitions/DAS.L001..RAW@2024-06-01.yaml": (
+                    "type: Acquisition\nstart_time: '2024-06-01'\n"
+                )
+            }
+        )
+        acquisition = out.networks[0].fiber_arrays[0].acquisitions[0]
+        assert acquisition.start_time == np.datetime64("2024-06-01", "ns")
+
+    def test_epochs_of_one_acquisition(self, make_inventory):
+        """Two epochs of one acquisition are two entries under one array."""
+        out = make_inventory(
+            {
+                "acquisitions/DAS.L001..RAW.yaml": (
+                    "type: Acquisition\nend_time: '2024-06-01'\ngauge_length: 10.0\n"
+                ),
+                "acquisitions/DAS.L001..RAW@2024-06-01.yaml": (
+                    "type: Acquisition\ngauge_length: 5.0\n"
+                ),
+            }
+        )
+        acquisitions = out.networks[0].fiber_arrays[0].acquisitions
+        assert len(acquisitions) == 2
+        assert out.resolve("DAS.L001..RAW", "2024-01-01").acquisition.gauge_length == 10
+        assert out.resolve("DAS.L001..RAW", "2025-01-01").acquisition.gauge_length == 5
+
+    def test_acquisition_lands_in_its_array_epoch(self, make_inventory):
+        """A child is placed in the container epoch which held it."""
+        out = make_inventory(
+            {
+                "fiber_arrays/DAS.L001.yaml": (
+                    "type: FiberArray\nname: first\nend_time: '2024-06-01'\n"
+                ),
+                "fiber_arrays/DAS.L001@2024-06-01.yaml": (
+                    "type: FiberArray\nname: second\n"
+                ),
+                "acquisitions/DAS.L001..RAW@2024-07-01.yaml": "type: Acquisition\n",
+            }
+        )
+        arrays = {x.name: x for x in out.networks[0].fiber_arrays}
+        assert not arrays["first"].acquisitions
+        assert [x.code for x in arrays["second"].acquisitions] == ["RAW"]
+
+
+class TestNearMisses:
+    """Anything claiming to participate and getting it wrong raises."""
+
+    def test_typo_in_container_name(self, make_inventory):
+        """A typo must not quietly load an inventory with no acquisitions."""
+        files = {"aquisitions/DAS.L001..RAW.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="nothing contains it"):
+            make_inventory(files)
+
+    def test_model_file_at_the_root(self, make_inventory):
+        """An object at the root is outside every container."""
+        files = {**MINIMAL, "DAS.L001.yaml": "type: FiberArray\n"}
+        with pytest.raises(InvalidInventoryError, match="nothing contains it"):
+            make_inventory(files)
+
+    def test_missing_type(self, make_inventory):
+        """A file which does not say what it is has not participated."""
+        files = {"acquisitions/DAS.L001..RAW.yaml": "data_category: DAS\n"}
+        with pytest.raises(InvalidInventoryError, match="declares no type"):
+            make_inventory(files)
+
+    def test_wrong_container(self, make_inventory):
+        """The container checks the declared type rather than supplying it."""
+        files = {"fiber_arrays/DAS.L001.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="cannot hold"):
+            make_inventory(files)
+
+    def test_unknown_type(self, make_inventory):
+        """A type which names no model is unknown rather than misfiled."""
+        files = {"fiber_arrays/DAS.L001.yaml": "type: Telescope\n"}
+        with pytest.raises(InvalidInventoryError, match="unknown"):
+            make_inventory(files)
+
+    def test_restated_address_disagrees(self, make_inventory):
+        """There is never a precedence rule between two spellings."""
+        files = {"acquisitions/DAS.L001..RAW.yaml": "type: Acquisition\ncode: DEC\n"}
+        with pytest.raises(InvalidInventoryError, match="must agree with the name"):
+            make_inventory(files)
+
+    def test_restated_start_time_disagrees(self, make_inventory):
+        """The epoch suffix is a restated address, so it must agree."""
+        files = {
+            "acquisitions/DAS.L001..RAW@2024-06-01.yaml": (
+                "type: Acquisition\nstart_time: '2024-06-02'\n"
+            )
+        }
+        with pytest.raises(InvalidInventoryError, match="must agree with the name"):
+            make_inventory(files)
+
+    def test_wrong_token_count(self, make_inventory):
+        """An acquisition name is an address of four tokens."""
+        files = {"acquisitions/DAS.L001.RAW.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="address of 4"):
+            make_inventory(files)
+
+    def test_schema_version_outside_the_envelope(self, make_inventory):
+        """The envelope versions the document exactly once."""
+        files = {
+            "acquisitions/DAS.L001..RAW.yaml": (
+                "type: Acquisition\nschema_version: 1\n"
+            )
+        }
+        with pytest.raises(InvalidInventoryError, match="envelope versions"):
+            make_inventory(files)
+
+    def test_invalid_field_names_the_file(self, make_inventory):
+        """A model error says which file could not be read."""
+        files = {
+            "acquisitions/DAS.L001..RAW.yaml": (
+                "type: Acquisition\ngauge_length: not a number\n"
+            )
+        }
+        with pytest.raises(InvalidInventoryError, match=r"DAS\.L001\.\.RAW\.yaml"):
+            make_inventory(files)
+
+    def test_unparsable_file_in_a_container(self, make_inventory):
+        """A file which claims a place in a container must parse."""
+        files = {"acquisitions/DAS.L001..RAW.yaml": "{[unclosed\n"}
+        with pytest.raises(InvalidInventoryError, match="Could not parse YAML"):
+            make_inventory(files)
+
+    def test_unparsable_json_in_a_container(self, make_inventory):
+        """The JSON spelling is held to the same standard."""
+        files = {"acquisitions/DAS.L001..RAW.json": "{not json\n"}
+        with pytest.raises(InvalidInventoryError, match="Could not parse JSON"):
+            make_inventory(files)
+
+    def test_non_mapping_file_in_a_container(self, make_inventory):
+        """A document which is not a mapping defines no object."""
+        files = {"acquisitions/DAS.L001..RAW.yaml": "- a list\n"}
+        with pytest.raises(InvalidInventoryError, match="holds no mapping"):
+            make_inventory(files)
+
+
+class TestOneIdentityOneSpelling:
+    """Identity is unique per container regardless of spelling."""
+
+    def test_two_extensions(self, make_inventory):
+        """The same name with two extensions is one identity spelled twice."""
+        files = {
+            "resources/cable_01.yaml": "type: Cable\n",
+            "resources/cable_01.json": '{"type": "Cable"}',
+        }
+        with pytest.raises(InvalidInventoryError, match="two extensions"):
+            make_inventory(files)
+
+    def test_case_only_difference(self, make_inventory):
+        """A case-insensitive filesystem could not hold both."""
+        files = {
+            "fiber_arrays/DAS.L001.yaml": "type: FiberArray\n",
+            "fiber_arrays/das.l001.yaml": "type: FiberArray\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="differ only by case"):
+            make_inventory(files)
+
+    def test_file_and_directory(self, make_inventory):
+        """Both spellings of one identity at once raise."""
+        files = {
+            "fiber_arrays/DAS.L001.yaml": "type: FiberArray\n",
+            "fiber_arrays/DAS.L001/attrs.yaml": "type: FiberArray\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="file and a directory"):
+            make_inventory(files)
+
+    def test_envelope_spelled_twice(self, make_inventory):
+        """The envelope is one file however it is spelled."""
+        files = {
+            **MINIMAL,
+            "inventory.yaml": "type: Inventory\n",
+            "inventory.json": '{"type": "Inventory"}',
+        }
+        with pytest.raises(InvalidInventoryError, match="more than once"):
+            make_inventory(files)
+
+    def test_two_names_for_one_epoch(self, make_inventory):
+        """Epoch-name uniqueness is temporal rather than textual."""
+        files = {
+            "acquisitions/DAS.L001..RAW@2024-06-01.yaml": "type: Acquisition\n",
+            "acquisitions/DAS.L001..RAW@2024-06-01T000000.yaml": "type: Acquisition\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="one epoch"):
+            make_inventory(files)
+
+
+class TestEntityDirectories:
+    """Tests for the directory spelling of one entity."""
+
+    def test_missing_attrs_file(self, make_inventory):
+        """A directory with no attrs file states nothing."""
+        files = {**MINIMAL, "fiber_arrays/DAS.L001/notes.txt": "hi\n"}
+        with pytest.raises(InvalidInventoryError, match="holds no attrs file"):
+            make_inventory(files)
+
+    def test_stray_object_file(self, make_inventory):
+        """An entity directory's object file is named attrs."""
+        files = {"fiber_arrays/DAS.L001/array.yaml": "type: FiberArray\n"}
+        with pytest.raises(InvalidInventoryError, match="not part of an entity"):
+            make_inventory(files)
+
+    def test_attrs_spelled_twice(self, make_inventory):
+        """One identity is spelled once inside the directory too."""
+        files = {
+            "fiber_arrays/DAS.L001/attrs.yaml": "type: FiberArray\n",
+            "fiber_arrays/DAS.L001/attrs.json": '{"type": "FiberArray"}',
+        }
+        with pytest.raises(InvalidInventoryError, match="more than once"):
+            make_inventory(files)
+
+
+class TestIgnoredEntries:
+    """What a container and an entity directory step over."""
+
+    def test_hidden_files_in_a_container(self, make_inventory, tmp_path):
+        """A dotfile is the filesystem's business, not the inventory's."""
+        root = tmp_path / "with_dotfiles"
+        write_inventory(root, MINIMAL)
+        (root / "acquisitions" / ".DS_Store").write_text("junk\n")
+        assert dc.inventory(root).networks[0].code == "DAS"
+
+    def test_hidden_and_foreign_entries_in_an_entity(self, tmp_path):
+        """Field material lives happily inside an entity directory too."""
+        root = tmp_path / "with_material"
+        write_inventory(
+            root,
+            {
+                **MINIMAL,
+                "fiber_arrays/DAS.L001/attrs.yaml": (
+                    "type: FiberArray\nname: from a directory\n"
+                ),
+                "fiber_arrays/DAS.L001/photos/wellhead.jpg": "not text",
+                "fiber_arrays/DAS.L001/notes.txt": "a note\n",
+            },
+        )
+        (root / "fiber_arrays" / "DAS.L001" / ".DS_Store").write_text("junk\n")
+        out = dc.inventory(root)
+        assert out.networks[0].fiber_arrays[0].name == "from a directory"
+
+    def test_unreadable_file_names_itself(self, tmp_path):
+        """A file which cannot be read at all says which one it was."""
+        root = tmp_path / "unreadable"
+        write_inventory(root, MINIMAL)
+        (root / "acquisitions" / "DAS.L001..DEC.yaml").write_bytes(b"\xff\xfe\x00")
+        with pytest.raises(InvalidInventoryError, match="Could not read"):
+            dc.inventory(root)
+
+
+class TestSeams:
+    """The parts of the format which cannot be read yet are refused."""
+
+    def test_track_table_in_an_entity_directory(self, make_inventory):
+        """A track table is refused by name rather than ignored."""
+        files = {
+            "fiber_arrays/DAS.L001/attrs.yaml": "type: FiberArray\n",
+            "fiber_arrays/DAS.L001/coupling.csv": "start_distance\n0\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="track table"):
+            make_inventory(files)
+
+    def test_optical_path_epoch_directory(self, make_inventory):
+        """An optical path epoch is refused by name rather than ignored."""
+        files = {
+            "fiber_arrays/DAS.L001/attrs.yaml": "type: FiberArray\n",
+            "fiber_arrays/DAS.L001/path@2024-05-12T103000/attrs.yaml": (
+                "type: OpticalPath\n"
+            ),
+        }
+        with pytest.raises(InvalidInventoryError, match="optical path epoch"):
+            make_inventory(files)
+
+    def test_track_table_outside_an_entity_directory(self, make_inventory):
+        """A table lives beside the attrs file of the entity it describes."""
+        files = {**MINIMAL, "fiber_arrays/geometry.csv": "distance\n0\n"}
+        with pytest.raises(InvalidInventoryError, match="outside an entity"):
+            make_inventory(files)
+
+
+class TestEpochTimestamps:
+    """Timestamps in names are UTC and ISO 8601 basic."""
+
+    @pytest.mark.parametrize(
+        "stamp", ["2024-13-01", "2024-06", "not-a-time", "2024-06-01T1030"]
+    )
+    def test_malformed(self, make_inventory, stamp):
+        """A name which claims an epoch and gets it wrong raises."""
+        files = {f"acquisitions/DAS.L001..RAW@{stamp}.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="epoch timestamp"):
+            make_inventory(files)
+
+    @pytest.mark.parametrize(
+        "stamp", ["2024-06-01Z", "2024-05-12T103000Z", "2024-05-12T103000+0100"]
+    )
+    def test_timezone_designator(self, make_inventory, stamp):
+        """Naive means UTC, so a designator is refused rather than ignored."""
+        files = {f"acquisitions/DAS.L001..RAW@{stamp}.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="timezone designator"):
+            make_inventory(files)
+
+    def test_negative_offset(self, make_inventory):
+        """An offset in the time portion is a designator, not a malformed time."""
+        files = {
+            "acquisitions/DAS.L001..RAW@2024-05-12T103000-0600.yaml": (
+                "type: Acquisition\n"
+            )
+        }
+        with pytest.raises(InvalidInventoryError, match="timezone designator"):
+            make_inventory(files)
+
+    def test_two_epoch_markers(self, make_inventory):
+        """A name carries at most one epoch."""
+        files = {
+            "acquisitions/DAS.L001..RAW@2024-06-01@2024-07-01.yaml": (
+                "type: Acquisition\n"
+            )
+        }
+        with pytest.raises(InvalidInventoryError, match="more than one"):
+            make_inventory(files)
+
+    def test_empty_epoch(self, make_inventory):
+        """A trailing marker names no epoch."""
+        files = {"acquisitions/DAS.L001..RAW@.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="names no epoch"):
+            make_inventory(files)
+
+    def test_resources_have_no_epochs(self, make_inventory):
+        """A resource is not time-ranged, so its name states no epoch."""
+        files = {**MINIMAL, "resources/int_01@2024-06-01.yaml": "type: Interrogator\n"}
+        with pytest.raises(InvalidInventoryError, match="have none"):
+            make_inventory(files)
+
+
+class TestEpochPlacement:
+    """A child is placed in the container epoch which held it."""
+
+    def test_child_outside_every_epoch(self, make_inventory):
+        """A child falling in no epoch of its container is misfiled."""
+        files = {
+            "fiber_arrays/DAS.L001.yaml": (
+                "type: FiberArray\nend_time: '2024-06-01'\n"
+            ),
+            "acquisitions/DAS.L001..RAW@2024-07-01.yaml": "type: Acquisition\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="0 epochs effective"):
+            make_inventory(files)
+
+    def test_ambiguous_child(self, make_inventory):
+        """An unset start beside several container epochs is ambiguous."""
+        files = {
+            "fiber_arrays/DAS.L001.yaml": (
+                "type: FiberArray\nend_time: '2024-06-01'\n"
+            ),
+            "fiber_arrays/DAS.L001@2024-06-01.yaml": "type: FiberArray\n",
+            "acquisitions/DAS.L001..RAW.yaml": "type: Acquisition\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="2 epochs effective at any"):
+            make_inventory(files)
+
+    def test_station_placed_in_a_network_epoch(self, make_inventory):
+        """Networks epoch like everything else which is time-ranged."""
+        out = make_inventory(
+            {
+                "networks/DAS.yaml": "type: Network\nend_time: '2024-06-01'\n",
+                "networks/DAS@2024-06-01.yaml": "type: Network\nname: later\n",
+                "stations/DAS.STA1@2024-07-01.yaml": "type: Station\n",
+            }
+        )
+        by_name = {x.name: x for x in out.networks}
+        assert not by_name[""].stations
+        assert [x.code for x in by_name["later"].stations] == ["STA1"]
+
+
+class TestEnvelope:
+    """The envelope holds the document-level singletons and nothing else."""
+
+    def test_wrong_type(self, make_inventory):
+        """The envelope declares its type under the same rule as any file."""
+        files = {**MINIMAL, "inventory.yaml": "type: Network\n"}
+        with pytest.raises(InvalidInventoryError, match="envelope declares"):
+            make_inventory(files)
+
+    @pytest.mark.parametrize("field", ["networks", "resources"])
+    def test_collections_are_refused(self, make_inventory, field):
+        """The collections live in the directory structure."""
+        files = {**MINIMAL, "inventory.yaml": f"type: Inventory\n{field}: []\n"}
+        with pytest.raises(InvalidInventoryError, match="directory structure"):
+            make_inventory(files)
+
+
+class TestFactory:
+    """The public factory routes a directory to this loader."""
+
+    def test_directory(self, tmp_path):
+        """A directory loads through the authoring format."""
+        root = write_inventory(tmp_path / "as_directory", MINIMAL)
+        assert isinstance(dc.inventory(root), inv.Inventory)
+
+    def test_yaml_file_still_works(self, tmp_path):
+        """A file keeps going to the single-file reader."""
+        path = tmp_path / "inv.yaml"
+        dc.inventory().to_yaml(path)
+        assert isinstance(dc.inventory(path), inv.Inventory)
+
+    def test_empty_directory(self, tmp_path):
+        """A directory with nothing in it is an empty inventory."""
+        root = tmp_path / "empty"
+        root.mkdir()
+        assert not dc.inventory(root).networks
+
+
+class TestModelAssumptions:
+    """Pin what this loader assumes about the models it builds."""
+
+    def test_only_union_members_carry_a_type_field(self):
+        """The type tag is a real field only where it discriminates a union."""
+        for name, container in loader._CONTAINERS.items():
+            for model in container.models:
+                assert ("type" in model.model_fields) == (name == "resources")
+
+    def test_epoch_bearing_models_are_time_ranged(self):
+        """Only a time-ranged model can hold the epoch a name states."""
+        for name, container in loader._CONTAINERS.items():
+            ranged = all(issubclass(x, TimeRangedModel) for x in container.models)
+            assert ranged == (name != "resources")
+
+    def test_inventory_models_forbid_extra_fields(self):
+        """Type must be popped: an inventory model refuses unknown input."""
+        assert InventoryModel.model_config["extra"] == "forbid"

From 88dca2ed59789d5d2a12405a14ab7aeffc23672e Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 09:19:48 +0200
Subject: [PATCH 2/9] Name the file behind an envelope typo, and pin the
 registry counts

Two follow-ups to the loader. An unknown envelope key was the one error
which reached the reader as a bare pydantic message, so it now names its
file like the rest. And four registry tests asserted only inside a loop,
so an empty registry would have passed them; each now pins how many
things it checked.
---
 dascore/core/inventory_loader.py         | 12 +++++++--
 tests/test_core/test_inventory_loader.py | 31 ++++++++++++++++++++++--
 2 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
index f67f3688e..fe67ed96b 100644
--- a/dascore/core/inventory_loader.py
+++ b/dascore/core/inventory_loader.py
@@ -102,7 +102,10 @@ class _Container(NamedTuple):
 class _Entry(NamedTuple):
     """One loaded entity, with where it came from and what contains it."""
 
-    model: InventoryModel
+    # A resource or one of the time-ranged entities a network contains.
+    # Loosely typed because those two halves share only their base class,
+    # while assembling needs the fields of whichever half it holds.
+    model: Any
     source: Path
     # This entry's _ADDRESS_LEVELS tokens, outermost first.
     address: tuple[str, ...]
@@ -518,7 +521,7 @@ def _place(children: list[_Entry], parents: list[_Entry], kind: str):
     return out
 
 
-def _group(entries: list[_Entry]) -> Mapping[tuple, list[_Entry]]:
+def _group(entries: list[_Entry]) -> dict[tuple, list[_Entry]]:
     """Group entries by the address which names their container."""
     out = defaultdict(list)
     for entry in entries:
@@ -627,6 +630,11 @@ def _load_envelope(root: Path) -> dict[str, Any]:
                 "structure rather than in the envelope."
             )
             raise InvalidInventoryError(msg)
+    # Checked here rather than left to the model, so a typo names its file
+    # like every other error this format raises.
+    if unknown := sorted(set(data) - set(Inventory.model_fields)):
+        msg = f"{_quote(source)} states {unknown}, which an inventory has not."
+        raise InvalidInventoryError(msg)
     return data
 
 
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index 374b4a770..fa7c631b0 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -42,24 +42,39 @@ def build(files, name="my_inventory"):
 class TestRegistry:
     """The container registry must stay pinned to the models."""
 
+    def test_containers_are_the_ones_the_format_defines(self):
+        """Pinned so the loops below cannot pass over an empty registry."""
+        assert set(loader._CONTAINERS) == {
+            "resources",
+            "networks",
+            "fiber_arrays",
+            "stations",
+            "acquisitions",
+        }
+
     def test_identity_tokens_are_fields_or_levels(self):
         """Every name token states a field or names a containing entity."""
+        checked = []
         for container in loader._CONTAINERS.values():
             for model in container.models:
                 for token in container.identity:
                     known = token in model.model_fields
                     assert known or token in loader._ADDRESS_LEVELS
+                    checked.append((model, token))
+        assert len(checked) == 14
 
     def test_resource_container_matches_the_union(self):
         """The resources container holds exactly the resource union."""
         union = inv.get_args(inv.get_args(inv._Resource)[0])
         assert set(loader._CONTAINERS["resources"].models) == set(union)
+        assert len(union) == 5
 
     def test_every_model_name_is_known(self):
         """A model this loader can build counts as a model for near-misses."""
         names = loader._model_names()
-        for container in loader._CONTAINERS.values():
-            assert {x.__name__ for x in container.models} <= names
+        built = {x.__name__ for c in loader._CONTAINERS.values() for x in c.models}
+        assert built <= names
+        assert len(built) == 9
         assert "Inventory" in names
 
 
@@ -632,6 +647,12 @@ def test_collections_are_refused(self, make_inventory, field):
         with pytest.raises(InvalidInventoryError, match="directory structure"):
             make_inventory(files)
 
+    def test_unknown_field_names_the_file(self, make_inventory):
+        """A typo in the envelope says which file states it."""
+        files = {**MINIMAL, "inventory.yaml": "type: Inventory\nschema_verison: 1\n"}
+        with pytest.raises(InvalidInventoryError, match=r"inventory\.yaml"):
+            make_inventory(files)
+
 
 class TestFactory:
     """The public factory routes a directory to this loader."""
@@ -659,15 +680,21 @@ class TestModelAssumptions:
 
     def test_only_union_members_carry_a_type_field(self):
         """The type tag is a real field only where it discriminates a union."""
+        checked = []
         for name, container in loader._CONTAINERS.items():
             for model in container.models:
                 assert ("type" in model.model_fields) == (name == "resources")
+                checked.append(model)
+        assert len(checked) == 9
 
     def test_epoch_bearing_models_are_time_ranged(self):
         """Only a time-ranged model can hold the epoch a name states."""
+        checked = []
         for name, container in loader._CONTAINERS.items():
             ranged = all(issubclass(x, TimeRangedModel) for x in container.models)
             assert ranged == (name != "resources")
+            checked.append(name)
+        assert len(checked) == len(loader._CONTAINERS) == 5
 
     def test_inventory_models_forbid_extra_fields(self):
         """Type must be popped: an inventory model refuses unknown input."""

From 8103ef1c3573aa4da1ec140547a7d0f1205158dd Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 09:21:48 +0200
Subject: [PATCH 3/9] Blame the file for an illegal address token

A malformed network or fiber array token in a name failed when the
entity it addresses was built, which is after every file mentioning it
has been read, so the error named no file. The token is now checked
where it is read.
---
 dascore/core/inventory_loader.py         | 10 +++++++++-
 tests/test_core/test_inventory_loader.py |  6 ++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
index fe67ed96b..45ec805d6 100644
--- a/dascore/core/inventory_loader.py
+++ b/dascore/core/inventory_loader.py
@@ -47,7 +47,7 @@
     Station,
 )
 from dascore.exceptions import InvalidInventoryError
-from dascore.utils.misc import optional_import
+from dascore.utils.misc import check_code, optional_import
 from dascore.utils.models import InventoryModel, TimeRangedModel
 from dascore.utils.time import to_datetime64
 
@@ -322,6 +322,14 @@ def _apply_identity(data: dict, container: _Container, name: str, source: Path):
     address = []
     for token, field in zip(tokens, container.identity, strict=True):
         if field in _ADDRESS_LEVELS:
+            # Checked here because the entity this token names is built
+            # later, from every address which mentions it, and by then
+            # there is no one file to blame for the token being illegal.
+            try:
+                check_code(token)
+            except InvalidInventoryError as error:
+                msg = f"{_quote(source)} names {field} {token!r}: {error}"
+                raise InvalidInventoryError(msg) from error
             address.append(token)
             continue
         stated = data.setdefault(field, token)
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index fa7c631b0..6f103b4d8 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -350,6 +350,12 @@ def test_restated_start_time_disagrees(self, make_inventory):
         with pytest.raises(InvalidInventoryError, match="must agree with the name"):
             make_inventory(files)
 
+    def test_illegal_address_token_names_the_file(self, make_inventory):
+        """The entity a token names is built from every address, not one file."""
+        files = {"acquisitions/DAS.L0_01..RAW.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="names fiber_array"):
+            make_inventory(files)
+
     def test_wrong_token_count(self, make_inventory):
         """An acquisition name is an address of four tokens."""
         files = {"acquisitions/DAS.L001.RAW.yaml": "type: Acquisition\n"}

From 12aa44e1c8ad6d930174a03aee090f730f89d983 Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 09:24:21 +0200
Subject: [PATCH 4/9] Refuse an epoch name a nanosecond timestamp cannot hold

A datetime64 wraps silently outside about 1678 to 2262, so
'...@2500-01-01.yaml' read as 1915 and would have quietly misfiled every
child of that epoch. The name is now refused. The wrap itself is older
and wider than this loader -- Acquisition(start_time='2500-01-01') does
the same -- so only the name is guarded here.
---
 dascore/core/inventory_loader.py         | 12 +++++++++++-
 tests/test_core/test_inventory_loader.py | 23 +++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
index 45ec805d6..99770c626 100644
--- a/dascore/core/inventory_loader.py
+++ b/dascore/core/inventory_loader.py
@@ -226,10 +226,20 @@ def _parse_epoch(text: str, source: Path):
         raise InvalidInventoryError(f"{unreadable}.")
     time = match["time"] or "000000"
     try:
-        return to_datetime64(f"{date}T{time[:2]}:{time[2:4]}:{time[4:]}")
+        parsed = to_datetime64(f"{date}T{time[:2]}:{time[2:4]}:{time[4:]}")
     except ValueError as error:
         # The pattern admits digits which name no instant, e.g. a 13th month.
         raise InvalidInventoryError(f"{unreadable}: {error}") from error
+    # A nanosecond timestamp spans about 1678 to 2262 and numpy wraps around
+    # silently past either end, which would put this epoch centuries from
+    # where its name says and quietly misfile every child of it.
+    if not str(parsed).startswith(date):
+        msg = (
+            f"Epoch timestamp {text!r} {where} is outside the range a "
+            f"nanosecond timestamp can represent; it would read as {parsed}."
+        )
+        raise InvalidInventoryError(msg)
+    return parsed
 
 
 def _split_epoch(source: Path, epochs_allowed: bool):
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index 6f103b4d8..dd5797d47 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -574,6 +574,29 @@ def test_negative_offset(self, make_inventory):
         with pytest.raises(InvalidInventoryError, match="timezone designator"):
             make_inventory(files)
 
+    # The last is on the final representable day, so the guard cannot be
+    # passing by comparing dates alone.
+    @pytest.mark.parametrize(
+        "stamp", ["2500-01-01", "1000-01-01", "2262-04-12", "2262-04-11T235000"]
+    )
+    def test_outside_the_representable_range(self, make_inventory, stamp):
+        """A nanosecond timestamp wraps silently, so the name is refused."""
+        files = {f"acquisitions/DAS.L001..RAW@{stamp}.yaml": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match="outside the range"):
+            make_inventory(files)
+
+    def test_the_last_representable_instant(self, make_inventory):
+        """The check refuses what wraps without refusing what does not."""
+        out = make_inventory(
+            {
+                "acquisitions/DAS.L001..RAW@2262-04-11T234716.yaml": (
+                    "type: Acquisition\n"
+                )
+            }
+        )
+        acquisition = out.networks[0].fiber_arrays[0].acquisitions[0]
+        assert acquisition.start_time == np.datetime64("2262-04-11T23:47:16", "ns")
+
     def test_two_epoch_markers(self, make_inventory):
         """A name carries at most one epoch."""
         files = {

From 468e4fda56a2b86a73cac246fa836a22b9c3bd9d Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 09:43:43 +0200
Subject: [PATCH 5/9] Close the holes the counterpart review found

Five of seven findings, four of which could load a wrong inventory
rather than raising:

- An object filed inside an entity directory was silently dropped, since
  the stray scan skipped recognized containers wholesale and the entity
  reader ignored subdirectories. The scan now runs inside an entity too,
  skipping only its own attrs file.
- Suffixes matched case-sensitively, so an inventory holding only
  DAS.L001..RAW.YAML loaded as empty. A case-insensitive filesystem
  holds one file there, not two spellings.
- A child was placed by its start time alone, so an acquisition running
  past its fiber array's epoch went in the earlier one and became
  unreachable after the boundary, where resolution picks the later
  array. It is now refused, being a contradiction in the directory
  rather than a choice to make on the author's behalf.
- An envelope value which would not validate reached the final build and
  surfaced as a bare pydantic error naming no file.
- A type which is not a name at all, `type: [Acquisition]`, reached a
  hashed lookup and raised TypeError.

Declined: folding case across the hierarchy join, since codes are
case-sensitive to the models and to resolve, so a directory which folded
them would disagree with what it loads; and ignoring a container
subdirectory which holds no attrs file, since it is spelled exactly like
an entity, and ignoring it would silently drop one whose attrs file was
merely misnamed.
---
 dascore/core/inventory_loader.py         | 117 +++++++++++++++++------
 tests/test_core/test_inventory_loader.py |  75 +++++++++++++++
 2 files changed, 164 insertions(+), 28 deletions(-)

diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
index 99770c626..02ee7e0bd 100644
--- a/dascore/core/inventory_loader.py
+++ b/dascore/core/inventory_loader.py
@@ -138,6 +138,18 @@ def _quote(path: Path) -> str:
     return str(Path(path.parent.name) / path.name)
 
 
+def _object_suffix(path: Path) -> str | None:
+    """
+    Return a path's object-file suffix, or None if it has none.
+
+    Matched without regard to case, since a case-insensitive filesystem
+    holds ``DAS.YAML`` and ``DAS.yaml`` as one file and silently skipping
+    one spelling would load an inventory missing whatever it named.
+    """
+    suffix = path.suffix.casefold()
+    return suffix if suffix in _OBJECT_SUFFIXES else None
+
+
 def _entry_name(path: Path) -> str:
     """
     Return the address an entry's name states.
@@ -145,9 +157,9 @@ def _entry_name(path: Path) -> str:
     ``Path.stem`` cannot be used: an address is full of dots, so it would
     read ``DAS.L001`` as the stem ``DAS`` with a suffix.
     """
-    if path.is_dir() or path.suffix not in _OBJECT_SUFFIXES:
+    if path.is_dir() or (suffix := _object_suffix(path)) is None:
         return path.name
-    return path.name[: -len(path.suffix)]
+    return path.name[: -len(suffix)]
 
 
 def _read_object(path: Path) -> dict[str, Any]:
@@ -162,7 +174,7 @@ def _read_object(path: Path) -> dict[str, Any]:
     except (OSError, UnicodeDecodeError) as error:
         msg = f"Could not read {_quote(path)}: {error}."
         raise InvalidInventoryError(msg) from error
-    if path.suffix == ".json":
+    if _object_suffix(path) == ".json":
         try:
             data = json.loads(text)
         except ValueError as error:
@@ -275,7 +287,9 @@ def _pick_model(data: dict, container: _Container, source: Path):
     """
     declared = data.get("type")
     legal = tuple(x.__name__ for x in container.models)
-    if declared is None:
+    # Not merely absent: a type which is not a name at all -- a list, a
+    # mapping -- names no model either, and must not reach the lookups below.
+    if not isinstance(declared, str):
         msg = (
             f"{_quote(source)} declares no type. Every object file states "
             f"what it is, e.g. 'type: {legal[0]}'."
@@ -382,7 +396,7 @@ def _refuse_tracks(entity: Path) -> None:
     for child in sorted(entity.iterdir()):
         if child.name.startswith("."):
             continue
-        stem = child.name.partition(_EPOCH_MARKER)[0].partition(".")[0]
+        stem = child.name.partition(_EPOCH_MARKER)[0].partition(".")[0].casefold()
         if child.is_dir() and stem == _PATH_STEM:
             msg = (
                 f"{_quote(child)} is an optical path epoch, which cannot be "
@@ -390,7 +404,7 @@ def _refuse_tracks(entity: Path) -> None:
                 f"{_ATTRS_STEM} file for now."
             )
             raise InvalidInventoryError(msg)
-        if child.suffix == ".csv":
+        if child.suffix.casefold() == ".csv":
             msg = (
                 f"{_quote(child)} is a track table, which cannot be read yet. "
                 f"State {_entry_name(child)} in the entity's {_ATTRS_STEM} "
@@ -405,9 +419,9 @@ def _attrs_file(entity: Path) -> Path:
     for child in sorted(entity.iterdir()):
         if child.is_dir() or child.name.startswith("."):
             continue
-        if child.suffix not in _OBJECT_SUFFIXES:
+        if _object_suffix(child) is None:
             continue
-        if _entry_name(child) != _ATTRS_STEM:
+        if _entry_name(child).casefold() != _ATTRS_STEM:
             msg = (
                 f"{_quote(child)} is not part of an entity directory, whose "
                 f"object file is named {_ATTRS_STEM}."
@@ -451,8 +465,8 @@ def _container_entries(directory: Path) -> list[Path]:
     for child in sorted(directory.iterdir()):
         if child.name.startswith("."):
             continue
-        if child.is_file() and child.suffix not in _OBJECT_SUFFIXES:
-            if child.suffix == ".csv":
+        if child.is_file() and _object_suffix(child) is None:
+            if child.suffix.casefold() == ".csv":
                 msg = (
                     f"{_quote(child)} is a track table outside an entity "
                     "directory; a table lives beside the attrs file of the "
@@ -468,13 +482,17 @@ def _container_entries(directory: Path) -> list[Path]:
     return list(seen.values())
 
 
-def _load_container(directory: Path, container: _Container) -> list[_Entry]:
+def _load_container(directory: Path, container: _Container, root: Path):
     """Load every entry of one top-level container directory."""
     out = []
     for child in _container_entries(directory):
         if child.is_dir():
             _refuse_tracks(child)
             data_source = _attrs_file(child)
+            # An entity directory holds its own attrs and tracks; an object
+            # filed inside it belongs to a container and is not loaded from
+            # here, so it has to be refused rather than stepped over.
+            _refuse_stray_objects(child, root, skip=data_source)
         else:
             data_source = child
         out.append(_load_entry(child, data_source, container))
@@ -509,6 +527,18 @@ def _check_epoch_duplicates(entries: list[_Entry]) -> None:
     return None
 
 
+def _outlives(child, parent) -> bool:
+    """
+    Return True if a child stays valid past its parent epoch's end.
+
+    Half-open on both sides, so a child ending exactly where its parent
+    does fits: the instant they share belongs to neither.
+    """
+    if pd.isnull(parent.end_time):
+        return False
+    return pd.isnull(child.end_time) or child.end_time > parent.end_time
+
+
 def _place(children: list[_Entry], parents: list[_Entry], kind: str):
     """
     Group children by the parent epoch each one falls in.
@@ -518,6 +548,12 @@ def _place(children: list[_Entry], parents: list[_Entry], kind: str):
     one falling in several -- including one whose own start is unset while
     its container has more than one epoch -- is ambiguous rather than
     resolved.
+
+    Starting inside an epoch is not enough to belong to it: a child which
+    runs on past its container's epoch would be reachable only before the
+    boundary, since resolution past it selects the next epoch, which does
+    not hold the child. That is a contradiction in the directory rather
+    than a choice to make on the author's behalf.
     """
     out = defaultdict(list)
     for child in children:
@@ -535,6 +571,16 @@ def _place(children: list[_Entry], parents: list[_Entry], kind: str):
                 f"has {len(matches)} epochs effective {when}."
             )
             raise InvalidInventoryError(msg)
+        parent = parents[matches[0]]
+        if _outlives(child.model, parent.model):
+            ends = child.model.end_time
+            runs = "never ends" if pd.isnull(ends) else f"ends at {ends}"
+            msg = (
+                f"{_quote(child.source)} {runs}, so it runs past the {kind} "
+                f"epoch holding it, which ends at {parent.model.end_time}. "
+                "State it once per epoch it spans."
+            )
+            raise InvalidInventoryError(msg)
         out[matches[0]].append(child)
     return out
 
@@ -622,10 +668,15 @@ def _load_envelope(root: Path) -> dict[str, Any]:
     arrays and acquisitions loads with defaults -- but it is the one place
     the document's version and CRS may be stated.
     """
+    # Scanned rather than constructed from the known suffixes, so that a
+    # shouted spelling is found and, when both are present, reported as the
+    # two spellings of one envelope that they are.
     found = [
-        candidate
-        for suffix in _OBJECT_SUFFIXES
-        if (candidate := root / f"{_ENVELOPE_STEM}{suffix}").is_file()
+        child
+        for child in sorted(root.iterdir())
+        if child.is_file()
+        and _object_suffix(child) is not None
+        and _entry_name(child).casefold() == _ENVELOPE_STEM
     ]
     if not found:
         return {}
@@ -648,44 +699,54 @@ def _load_envelope(root: Path) -> dict[str, Any]:
                 "structure rather than in the envelope."
             )
             raise InvalidInventoryError(msg)
-    # Checked here rather than left to the model, so a typo names its file
-    # like every other error this format raises.
-    if unknown := sorted(set(data) - set(Inventory.model_fields)):
-        msg = f"{_quote(source)} states {unknown}, which an inventory has not."
-        raise InvalidInventoryError(msg)
+    # Validated here, discarding the result, so that a typo'd key or an
+    # unreadable value names its file like every other error this format
+    # raises rather than surfacing as a bare pydantic error at the end.
+    try:
+        Inventory(**data)
+    except Exception as error:
+        msg = f"Could not read the envelope from {_quote(source)}: {error}"
+        raise InvalidInventoryError(msg) from error
     return data
 
 
-def _check_strays(root: Path) -> None:
+def _refuse_stray_objects(start: Path, root: Path, skip: Path | None = None) -> None:
     """
     Refuse a model-declaring file which nothing contains.
 
     A typo like ``aquisitions/`` must not quietly load an inventory with
-    no acquisitions, while the field material beside it stays welcome.
+    no acquisitions, and neither must an object filed one level too deep,
+    inside an entity directory which holds only its own attrs and tracks.
+    Everything which declares nothing stays welcome where it lies.
     """
     known = _model_names()
 
     def check(path: Path):
-        if path.name.startswith("."):
+        if path.name.startswith(".") or path == skip:
             return
         if path.is_dir():
             for child in sorted(path.iterdir()):
                 check(child)
-        elif path.suffix in _OBJECT_SUFFIXES:
+        elif _object_suffix(path) is not None:
             if (declared := _declared_type(path)) in known:
                 msg = (
                     f"{path.relative_to(root)} declares type {declared!r} but "
-                    "nothing contains it. Inventory objects live in "
-                    f"{tuple(_CONTAINERS)}."
+                    "nothing contains it. An inventory object lives in one of "
+                    f"{tuple(_CONTAINERS)}, named for the entity it is."
                 )
                 raise InvalidInventoryError(msg)
 
+    check(start)
+
+
+def _check_strays(root: Path) -> None:
+    """Refuse a stray object anywhere outside a recognized container."""
     for child in sorted(root.iterdir()):
         if child.is_dir() and child.name in _CONTAINERS:
             continue
-        if child.is_file() and _entry_name(child) == _ENVELOPE_STEM:
+        if child.is_file() and _entry_name(child).casefold() == _ENVELOPE_STEM:
             continue
-        check(child)
+        _refuse_stray_objects(child, root)
 
 
 def load_directory(path) -> Inventory:
@@ -700,7 +761,7 @@ def load_directory(path) -> Inventory:
     root = Path(path)
     envelope = _load_envelope(root)
     entries = {
-        name: _load_container(root / name, container)
+        name: _load_container(root / name, container, root)
         for name, container in _CONTAINERS.items()
         if (root / name).is_dir()
     }
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index dd5797d47..13fb1551e 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -401,6 +401,81 @@ def test_non_mapping_file_in_a_container(self, make_inventory):
             make_inventory(files)
 
 
+class TestReviewFindings:
+    """Regressions for what the counterpart review found."""
+
+    def test_object_filed_inside_an_entity_directory(self, make_inventory):
+        """An object one level too deep must not be silently dropped."""
+        files = {
+            "fiber_arrays/DAS.L001/attrs.yaml": "type: FiberArray\n",
+            "fiber_arrays/DAS.L001/misplaced/DAS.L001..RAW.yaml": (
+                "type: Acquisition\n"
+            ),
+        }
+        with pytest.raises(InvalidInventoryError, match="nothing contains it"):
+            make_inventory(files)
+
+    @pytest.mark.parametrize("suffix", ["YAML", "YML", "JSON"])
+    def test_upper_case_suffixes(self, make_inventory, suffix):
+        """A case-insensitive filesystem holds one file, not two spellings."""
+        text = (
+            '{"type": "Acquisition"}'
+            if suffix == "JSON"
+            else "type: Acquisition\ndata_category: DAS\n"
+        )
+        out = make_inventory({f"acquisitions/DAS.L001..RAW.{suffix}": text})
+        assert out.networks[0].fiber_arrays[0].acquisitions[0].code == "RAW"
+
+    def test_upper_case_envelope(self, make_inventory):
+        """The envelope is found however its suffix is spelled."""
+        out = make_inventory(
+            {**MINIMAL, "inventory.YAML": "type: Inventory\nresource_id: shouted\n"}
+        )
+        assert out.resource_id == "shouted"
+
+    def test_child_outliving_its_parent_epoch(self, make_inventory):
+        """Starting inside an epoch is not enough to belong to it."""
+        files = {
+            "fiber_arrays/DAS.L001.yaml": (
+                "type: FiberArray\nend_time: '2024-06-01'\n"
+            ),
+            "fiber_arrays/DAS.L001@2024-06-01.yaml": "type: FiberArray\n",
+            # Starts inside the first epoch and never ends, so resolution
+            # after June would find the second array, which does not hold it.
+            "acquisitions/DAS.L001..RAW@2024-05-01.yaml": "type: Acquisition\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="runs past"):
+            make_inventory(files)
+
+    def test_child_ending_exactly_at_the_boundary_fits(self, make_inventory):
+        """Half-open on both sides, so the shared instant belongs to neither."""
+        out = make_inventory(
+            {
+                "fiber_arrays/DAS.L001.yaml": (
+                    "type: FiberArray\nend_time: '2024-06-01'\n"
+                ),
+                "fiber_arrays/DAS.L001@2024-06-01.yaml": "type: FiberArray\n",
+                "acquisitions/DAS.L001..RAW@2024-05-01.yaml": (
+                    "type: Acquisition\nend_time: '2024-06-01'\n"
+                ),
+            }
+        )
+        first = out.networks[0].fiber_arrays[0]
+        assert [x.code for x in first.acquisitions] == ["RAW"]
+
+    def test_unreadable_envelope_value_names_the_file(self, make_inventory):
+        """An envelope error reads like every other error this format raises."""
+        files = {**MINIMAL, "inventory.yaml": "type: Inventory\nschema_version: nope\n"}
+        with pytest.raises(InvalidInventoryError, match="Could not read the envelope"):
+            make_inventory(files)
+
+    def test_type_which_is_not_a_name(self, make_inventory):
+        """A type which is not a name at all names no model either."""
+        files = {"acquisitions/DAS.L001..RAW.yaml": "type: [Acquisition]\n"}
+        with pytest.raises(InvalidInventoryError, match="declares no type"):
+            make_inventory(files)
+
+
 class TestOneIdentityOneSpelling:
     """Identity is unique per container regardless of spelling."""
 

From ae69b6acb7766d649d85916818e9a27b8546fd9e Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 10:22:08 +0200
Subject: [PATCH 6/9] Say the address invariant once

A child's address is exactly its parent's full address, which is what
lets a flat directory nest. That was implicit, and the two places which
relied on it had drifted into different spellings -- one grouping by
`(*address, code)` and the other by `code` plus a filter -- which is how
the two disagreed in the first place. `_full_address` states it, and the
groupings either side of it are now visibly the same operation.

Also: `_place` returns a list aligned with its parents rather than a
dict keyed by their positions, so callers stop doing index arithmetic;
and the containers whose names may carry an epoch are derived from the
registry rather than restated as a literal list.
---
 dascore/core/inventory_loader.py         | 93 +++++++++++++++---------
 tests/test_core/test_inventory_loader.py |  4 +-
 2 files changed, 60 insertions(+), 37 deletions(-)

diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
index 02ee7e0bd..6a3824c6d 100644
--- a/dascore/core/inventory_loader.py
+++ b/dascore/core/inventory_loader.py
@@ -84,6 +84,11 @@ class _Container(NamedTuple):
     # _ADDRESS_LEVELS naming the entity which contains it.
     identity: tuple[str, ...]
 
+    @property
+    def epochs(self) -> bool:
+        """Whether names here may carry an epoch, which needs a time range."""
+        return all(issubclass(x, TimeRangedModel) for x in self.models)
+
 
 _CONTAINERS: Mapping[str, _Container] = {
     "resources": _Container(
@@ -370,7 +375,7 @@ def _load_entry(entry: Path, data_source: Path, container: _Container) -> _Entry
     """Load one entry of a container from its object file."""
     data = _read_object(data_source)
     model = _pick_model(data, container, data_source)
-    name, epoch = _split_epoch(entry, issubclass(model, TimeRangedModel))
+    name, epoch = _split_epoch(entry, container.epochs)
     address = _apply_identity(data, container, name, data_source)
     if epoch is not None and "start_time" not in data:
         data["start_time"] = epoch
@@ -541,7 +546,7 @@ def _outlives(child, parent) -> bool:
 
 def _place(children: list[_Entry], parents: list[_Entry], kind: str):
     """
-    Group children by the parent epoch each one falls in.
+    Group children by the parent epoch each one falls in, parents-aligned.
 
     An epoch is chosen the way every other resolution chooses one, by
     time. A child falling in no epoch of its container is misfiled, and
@@ -555,7 +560,7 @@ def _place(children: list[_Entry], parents: list[_Entry], kind: str):
     not hold the child. That is a contradiction in the directory rather
     than a choice to make on the author's behalf.
     """
-    out = defaultdict(list)
+    out: list[list[_Entry]] = [[] for _ in parents]
     for child in children:
         matches = [
             index
@@ -585,14 +590,33 @@ def _place(children: list[_Entry], parents: list[_Entry], kind: str):
     return out
 
 
-def _group(entries: list[_Entry]) -> dict[tuple, list[_Entry]]:
-    """Group entries by the address which names their container."""
+def _full_address(entry: _Entry) -> tuple[str, ...]:
+    """
+    Return the address naming this entry's own entity.
+
+    A child's ``address`` is exactly its parent's full address, and that is
+    what lets a flat directory nest: an acquisition addressed ``DAS.L001``
+    belongs to the fiber array whose own address is ``DAS.L001``.
+    """
+    return (*entry.address, entry.model.code)
+
+
+def _by_parent(entries: list[_Entry]) -> dict[tuple, list[_Entry]]:
+    """Group entries under the full address of the entity containing them."""
     out = defaultdict(list)
     for entry in entries:
         out[entry.address].append(entry)
     return out
 
 
+def _by_self(entries: list[_Entry]) -> dict[tuple, list[_Entry]]:
+    """Group entries, which may be epochs of one entity, by their own address."""
+    out = defaultdict(list)
+    for entry in entries:
+        out[_full_address(entry)].append(entry)
+    return out
+
+
 def _fill_arrays(arrays: list[_Entry], acquisitions: list[_Entry]) -> list[_Entry]:
     """
     Put every acquisition in the fiber array epoch which held it.
@@ -601,26 +625,23 @@ def _fill_arrays(arrays: list[_Entry], acquisitions: list[_Entry]) -> list[_Entr
     network named only by an array's address does; the hierarchy is never
     built by nesting.
     """
-    # An acquisition's address names its array, so an array is grouped by the
-    # address it answers to rather than by the one which contains it.
-    by_address = _group(acquisitions)
-    grouped = defaultdict(list)
-    for entry in arrays:
-        grouped[(*entry.address, entry.model.code)].append(entry)
+    by_parent = _by_parent(acquisitions)
     out = []
-    for address, entries in grouped.items():
-        placed = _place(by_address.pop(address, []), entries, "fiber array")
-        for index, entry in enumerate(entries):
-            if not (acqs := placed.get(index)):
+    for address, entries in _by_self(arrays).items():
+        placed = _place(by_parent.pop(address, []), entries, "fiber array")
+        for entry, acqs in zip(entries, placed, strict=True):
+            if not acqs:
                 out.append(entry)
                 continue
             models = tuple(x.model for x in acqs)
             out.append(entry._replace(model=entry.model.new(acquisitions=models)))
-    for address, entries in by_address.items():
+    # Whatever is left is addressed to an array no file declares, which the
+    # address itself brings into being.
+    for address, entries in by_parent.items():
         model = FiberArray(
-            code=address[1], acquisitions=tuple(x.model for x in entries)
+            code=address[-1], acquisitions=tuple(x.model for x in entries)
         )
-        out.append(_Entry(model, entries[0].source, address[:1]))
+        out.append(_Entry(model, entries[0].source, address[:-1]))
     return out
 
 
@@ -632,29 +653,28 @@ def _assemble(entries: Mapping[str, list[_Entry]]) -> tuple[Network, ...]:
     network mentioned by an address exists whether or not a file declares
     it.
     """
-    arrays = _fill_arrays(
-        entries.get("fiber_arrays", []), entries.get("acquisitions", [])
+    arrays = _by_parent(
+        _fill_arrays(entries.get("fiber_arrays", []), entries.get("acquisitions", []))
     )
-    stations = entries.get("stations", [])
-    by_code = defaultdict(list)
-    for entry in entries.get("networks", []):
-        by_code[entry.model.code].append(entry)
-    for entry in (*arrays, *stations):
-        by_code.setdefault(entry.address[0], [])
+    stations = _by_parent(entries.get("stations", []))
+    networks = _by_self(entries.get("networks", []))
+    for address in (*arrays, *stations):
+        networks.setdefault(address, [])
     out = []
-    for code, network_entries in by_code.items():
+    for address, network_entries in networks.items():
         if not network_entries:
             # A network named only by an address is an undated container.
+            code = address[-1]
             network_entries = [_Entry(Network(code=code), Path(code), ())]
-        arrays_here = [x for x in arrays if x.address[0] == code]
-        stations_here = [x for x in stations if x.address[0] == code]
-        by_array = _place(arrays_here, network_entries, "network")
-        by_station = _place(stations_here, network_entries, "network")
-        for index, entry in enumerate(network_entries):
+        by_array = _place(arrays.get(address, []), network_entries, "network")
+        by_station = _place(stations.get(address, []), network_entries, "network")
+        for entry, arrays_here, stations_here in zip(
+            network_entries, by_array, by_station, strict=True
+        ):
             out.append(
                 entry.model.new(
-                    fiber_arrays=tuple(x.model for x in by_array.get(index, [])),
-                    stations=tuple(x.model for x in by_station.get(index, [])),
+                    fiber_arrays=tuple(x.model for x in arrays_here),
+                    stations=tuple(x.model for x in stations_here),
                 )
             )
     return tuple(out)
@@ -766,8 +786,9 @@ def load_directory(path) -> Inventory:
         if (root / name).is_dir()
     }
     _check_strays(root)
-    for name in ("networks", "fiber_arrays", "stations", "acquisitions"):
-        _check_epoch_duplicates(entries.get(name, []))
+    for name, container in _CONTAINERS.items():
+        if container.epochs:
+            _check_epoch_duplicates(entries.get(name, []))
     resources = {x.model.resource_id: x.model for x in entries.get("resources", [])}
     networks = _assemble(entries)
     return Inventory(**envelope, resources=resources, networks=networks).check()
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index 13fb1551e..850fbfb25 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -796,7 +796,9 @@ def test_epoch_bearing_models_are_time_ranged(self):
         checked = []
         for name, container in loader._CONTAINERS.items():
             ranged = all(issubclass(x, TimeRangedModel) for x in container.models)
-            assert ranged == (name != "resources")
+            # The property decides both who may be named with an @ and who
+            # is checked for two names of one epoch, so pin it to the models.
+            assert container.epochs == ranged == (name != "resources")
             checked.append(name)
         assert len(checked) == len(loader._CONTAINERS) == 5
 

From 505998e6e6fb700ae34b734e319c5c84656901d4 Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 10:48:49 +0200
Subject: [PATCH 7/9] Close what six reviewers found

The worst of it was a file's own meaning depending on its neighbours. A
container file could state the collection its directory supplies, and
assembly replaced it: a network's inline stations vanished, and a fiber
array's inline acquisitions survived only until some unrelated file
addressed that array, at which point they disappeared. A file may now
state only what nothing else supplies, which is the rule the envelope
already followed.

Containment was checked at one end. A child was refused for outliving
its parent epoch but not for preceding it, and an unset start means the
unbounded past, so a station valid only until 2020 sat under a network
beginning in 2024. Both ends now, and the far end is tested against a
real end time rather than only an unset one -- deleting that clause
alone used to pass every test.

Also silent, each loading an inventory missing something it names:

- A shouted suffix. An inventory holding only DAS.L001..RAW.YAML loaded
  as empty, though a case-insensitive filesystem holds one file there.
- An object filed inside an entity directory, which the stray scan
  skipped along with the rest of its container.
- A hidden object file. Resource ids are free-form, so `.cable` is a
  legal one, and the file naming it disappeared. The two tests meant to
  cover this used `.DS_Store`, whose suffix is empty, so the suffix rule
  dropped it before the hidden-name branch was reached.
- A directory holding no inventory at all, which read as an empty one,
  so a mistyped path loaded.
- An epoch name finer than a nanosecond, which loaded as a different
  instant, its own restatement check comparing against the truncated
  value.

Two beyond the loader. An unquoted `end_time: 2024-07-01` is a date to
YAML, which `to_datetime64` refused outright -- and end times can only
be stated inside a file, so every closed epoch in a hand-authored
directory hit it, as did the single-file reader long before this branch.
And the API doc indexer tested `base_address not in key`, a substring
where a prefix was meant, so a module named after another claimed
everything it imported: 24 entries were credited to inventory_loader,
21 of them belonging to inventory, with unsorted glob order picking
which file survived. Three remain, which are its own.

Declined: folding case across the hierarchy join, since codes are
case-sensitive to the models and to resolve, and the rule here is about
what a filesystem can hold rather than about identity; and a doc page,
since the inventory has none yet by plan -- the docs migration is its
own phase, and the format is documented in the spec repo meanwhile.
---
 dascore/core/inventory_loader.py         | 170 +++++++++++++++++------
 dascore/utils/time.py                    |  15 +-
 scripts/_index_api.py                    |   6 +-
 tests/test_core/test_inventory_loader.py | 147 ++++++++++++++++++--
 tests/test_utils/test_time.py            |  13 +-
 5 files changed, 293 insertions(+), 58 deletions(-)

diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
index 6a3824c6d..55aced697 100644
--- a/dascore/core/inventory_loader.py
+++ b/dascore/core/inventory_loader.py
@@ -8,6 +8,11 @@
 files is itself a loadable inventory, and ``to_yaml`` exports the
 single-file interchange artifact for shipping beside a data archive.
 
+This module reads the object half. The track tables, and the optical path
+epoch directories which hold them, are refused by name rather than
+skipped, so a directory cannot load as an entity silently missing the
+tracks its own files state.
+
 The contract, in one line: **file declares type, container agrees, name
 implies identity, envelope implies version.** Every object file states what
 it is, its container checks that statement rather than supplying it, its
@@ -45,8 +50,12 @@
     Network,
     OpticalMeasurement,
     Station,
+    _overlapping_epochs,
+)
+from dascore.exceptions import (
+    InvalidInventoryError,
+    MissingOptionalDependencyError,
 )
-from dascore.exceptions import InvalidInventoryError
 from dascore.utils.misc import check_code, optional_import
 from dascore.utils.models import InventoryModel, TimeRangedModel
 from dascore.utils.time import to_datetime64
@@ -83,6 +92,10 @@ class _Container(NamedTuple):
     # names a field of the model states that field; the rest are
     # _ADDRESS_LEVELS naming the entity which contains it.
     identity: tuple[str, ...]
+    # Collections whose members are addressed by their own names, in their
+    # own container. A file here may not state them: assembly would replace
+    # whatever it said, so stating them is a fact the format cannot keep.
+    supplied: tuple[str, ...] = ()
 
     @property
     def epochs(self) -> bool:
@@ -95,8 +108,8 @@ def epochs(self) -> bool:
         (Interrogator, Cable, Enclosure, ExternalResource, OpticalMeasurement),
         ("resource_id",),
     ),
-    "networks": _Container((Network,), ("code",)),
-    "fiber_arrays": _Container((FiberArray,), ("network", "code")),
+    "networks": _Container((Network,), ("code",), ("fiber_arrays", "stations")),
+    "fiber_arrays": _Container((FiberArray,), ("network", "code"), ("acquisitions",)),
     "stations": _Container((Station,), ("network", "code")),
     "acquisitions": _Container(
         (Acquisition,), ("network", "fiber_array", "location_code", "code")
@@ -126,7 +139,11 @@ def _model_names() -> frozenset[str]:
     """
 
     def walk(model):
-        yield model.__name__
+        # Scoped to dascore's own models, so that what a caller happens to
+        # have subclassed and imported cannot change which files this
+        # format calls a near-miss.
+        if model.__module__.startswith("dascore."):
+            yield model.__name__
         for sub in model.__subclasses__():
             yield from walk(sub)
 
@@ -147,9 +164,9 @@ def _object_suffix(path: Path) -> str | None:
     """
     Return a path's object-file suffix, or None if it has none.
 
-    Matched without regard to case, since a case-insensitive filesystem
-    holds ``DAS.YAML`` and ``DAS.yaml`` as one file and silently skipping
-    one spelling would load an inventory missing whatever it named.
+    Matched without regard to case: a shouted ``DAS.L001.YAML`` is the file
+    ``DAS.L001.yaml`` would be, and skipping it for its spelling would load
+    an inventory silently missing whatever it named.
     """
     suffix = path.suffix.casefold()
     return suffix if suffix in _OBJECT_SUFFIXES else None
@@ -204,11 +221,13 @@ def _declared_type(path: Path) -> str | None:
 
     This tells field material from a misfiled object, so a file which does
     not parse simply is not an object: a YAML-suffixed file under a photos
-    directory owes this format nothing.
+    directory owes this format nothing. Nor does an unreadable one make an
+    inventory unloadable -- without PyYAML installed, a JSON inventory must
+    still load past whatever YAML happens to lie beside it.
     """
     try:
         data = _read_object(path)
-    except InvalidInventoryError:
+    except (InvalidInventoryError, MissingOptionalDependencyError):
         return None
     declared = data.get("type")
     return declared if isinstance(declared, str) else None
@@ -242,6 +261,15 @@ def _parse_epoch(text: str, source: Path):
     if (match := _EPOCH_RE.fullmatch(text)) is None:
         raise InvalidInventoryError(f"{unreadable}.")
     time = match["time"] or "000000"
+    # A datetime64 keeps nanoseconds, and quietly drops whatever is finer,
+    # so a name stating more precision than it can hold would load as an
+    # instant other than the one it names.
+    if len(time.partition(".")[2]) > 9:
+        msg = (
+            f"Epoch timestamp {text!r} {where} states a time finer than the "
+            "nanosecond an inventory timestamp keeps."
+        )
+        raise InvalidInventoryError(msg)
     try:
         parsed = to_datetime64(f"{date}T{time[:2]}:{time[2:4]}:{time[4:]}")
     except ValueError as error:
@@ -315,6 +343,25 @@ def _pick_model(data: dict, container: _Container, source: Path):
     raise InvalidInventoryError(msg)
 
 
+def _refuse_supplied(data: dict, fields, source: Path, held_by: str) -> None:
+    """
+    Refuse a collection which the directory structure supplies.
+
+    The hierarchy materializes from names, so the members of these
+    collections are addressed in their own container. Assembly replaces
+    whatever a file said about them, which would make a stated one vanish
+    -- and vanish only once some other file happened to address the same
+    entity, so the file's own meaning would depend on its neighbours.
+    """
+    for field in fields:
+        if field in data:
+            msg = (
+                f"{_quote(source)} states {field}, which live in the directory "
+                f"structure rather than in {held_by}."
+            )
+            raise InvalidInventoryError(msg)
+
+
 def _build(model, data: dict, source: Path):
     """Validate one mapping into its model, naming the file if it fails."""
     if "schema_version" in data:
@@ -375,6 +422,7 @@ def _load_entry(entry: Path, data_source: Path, container: _Container) -> _Entry
     """Load one entry of a container from its object file."""
     data = _read_object(data_source)
     model = _pick_model(data, container, data_source)
+    _refuse_supplied(data, container.supplied, data_source, "an object file")
     name, epoch = _split_epoch(entry, container.epochs)
     address = _apply_identity(data, container, name, data_source)
     if epoch is not None and "start_time" not in data:
@@ -465,10 +513,29 @@ def _container_entries(directory: Path) -> list[Path]:
     Identity is unique per container regardless of spelling, so two names
     differing only by case, or one name spelled as both a file and a
     directory, are two spellings of one thing rather than two things.
+
+    Case is folded here and nowhere else, because the rule is about the
+    filesystem rather than about identity: a case-insensitive one cannot
+    hold both files. Codes themselves stay case-sensitive, as they are to
+    the models and to ``Inventory.resolve``, so a directory which folded
+    them would disagree with what it loads.
     """
     seen: dict[str, Path] = {}
     for child in sorted(directory.iterdir()):
         if child.name.startswith("."):
+            # A resource id is free-form, so a leading dot could be meant as
+            # part of a name rather than as a hidden file. The filesystem
+            # disagrees, and an entity nothing can see would go missing in
+            # silence, so the ambiguity is refused rather than resolved.
+            if (
+                _object_suffix(child) is not None
+                and _declared_type(child) in _model_names()
+            ):
+                msg = (
+                    f"{_quote(child)} declares an inventory object, but a name "
+                    "beginning with '.' is hidden, so it cannot name one."
+                )
+                raise InvalidInventoryError(msg)
             continue
         if child.is_file() and _object_suffix(child) is None:
             if child.suffix.casefold() == ".csv":
@@ -506,42 +573,52 @@ def _load_container(directory: Path, container: _Container, root: Path):
 
 def _check_epoch_duplicates(entries: list[_Entry]) -> None:
     """
-    Refuse two entries which name one identity at one instant.
+    Refuse two entries whose epochs of one entity overlap in time.
 
     Epoch-name uniqueness is temporal rather than textual, so
     ``@2024-06-01`` and ``@2024-06-01T000000`` are two spellings of one
-    epoch. The models catch the overlap; the files are what the author can
-    act on.
-    """
-    seen: dict[Any, Path] = {}
+    epoch. The models reach the same verdict through the assembled tree,
+    but name the entity; the author can only act on the files, so the
+    overlap is found here while both are still in hand. The rule itself
+    is the models', borrowed rather than restated, since a check which
+    caught only identical instants would let a partial overlap through to
+    the fileless message this exists to replace.
+    """
+    sources = {id(x.model): x.source for x in entries}
+    grouped = defaultdict(list)
     for entry in entries:
-        model = entry.model
-        key = (
-            *entry.address,
-            model.code,
-            getattr(model, "location_code", ""),
-            model.start_time,
+        grouped[(*entry.address, getattr(entry.model, "location_code", ""))].append(
+            entry.model
         )
-        if (first := seen.get(key)) is not None:
+    for models in grouped.values():
+        for _, first, second in _overlapping_epochs(models, lambda x: x.code):
             msg = (
-                f"{_quote(first)} and {_quote(entry.source)} name one entity "
-                "at one instant, so they are two spellings of one epoch."
+                f"{_quote(sources[id(first)])} and {_quote(sources[id(second)])} "
+                "state epochs of one entity which overlap in time."
             )
             raise InvalidInventoryError(msg)
-        seen[key] = entry.source
     return None
 
 
-def _outlives(child, parent) -> bool:
+def _escapes(child, parent) -> str:
     """
-    Return True if a child stays valid past its parent epoch's end.
+    Say how a child's validity leaves its parent epoch, or "" if it fits.
 
-    Half-open on both sides, so a child ending exactly where its parent
-    does fits: the instant they share belongs to neither.
+    Half-open at both ends, so a child ending exactly where its parent
+    does fits: the instant they share belongs to neither. An unset bound
+    is unbounded, and unbounded is outside any epoch which states that
+    end -- which is how a child with no epoch of its own escapes a parent
+    which has one.
     """
-    if pd.isnull(parent.end_time):
-        return False
-    return pd.isnull(child.end_time) or child.end_time > parent.end_time
+    if not pd.isnull(parent.start_time) and (
+        pd.isnull(child.start_time) or child.start_time < parent.start_time
+    ):
+        return "starts before"
+    if not pd.isnull(parent.end_time) and (
+        pd.isnull(child.end_time) or child.end_time > parent.end_time
+    ):
+        return "runs past"
+    return ""
 
 
 def _place(children: list[_Entry], parents: list[_Entry], kind: str):
@@ -577,13 +654,13 @@ def _place(children: list[_Entry], parents: list[_Entry], kind: str):
             )
             raise InvalidInventoryError(msg)
         parent = parents[matches[0]]
-        if _outlives(child.model, parent.model):
-            ends = child.model.end_time
-            runs = "never ends" if pd.isnull(ends) else f"ends at {ends}"
+        if escape := _escapes(child.model, parent.model):
+            span = f"{parent.model.start_time} to {parent.model.end_time}"
             msg = (
-                f"{_quote(child.source)} {runs}, so it runs past the {kind} "
-                f"epoch holding it, which ends at {parent.model.end_time}. "
-                "State it once per epoch it spans."
+                f"{_quote(child.source)} is valid from {child.model.start_time} "
+                f"to {child.model.end_time}, so it {escape} the {kind} epoch "
+                f"holding it, which runs {span}. State it once per epoch it "
+                "spans."
             )
             raise InvalidInventoryError(msg)
         out[matches[0]].append(child)
@@ -712,13 +789,7 @@ def _load_envelope(root: Path) -> dict[str, Any]:
             f"declares 'type: {Inventory.__name__}'."
         )
         raise InvalidInventoryError(msg)
-    for field in _ENVELOPE_COLLECTIONS:
-        if field in data:
-            msg = (
-                f"{_quote(source)} states {field}, which live in the directory "
-                "structure rather than in the envelope."
-            )
-            raise InvalidInventoryError(msg)
+    _refuse_supplied(data, _ENVELOPE_COLLECTIONS, source, "the envelope")
     # Validated here, discarding the result, so that a typo'd key or an
     # unreadable value names its file like every other error this format
     # raises rather than surfacing as a bare pydantic error at the end.
@@ -786,6 +857,17 @@ def load_directory(path) -> Inventory:
         if (root / name).is_dir()
     }
     _check_strays(root)
+    # After the stray check, which knows why a directory holds no container:
+    # a mistyped `aquisitions/` can say so, rather than being reported as a
+    # directory holding nothing.
+    if not entries and not envelope:
+        # Every directory would otherwise be an empty inventory, so a
+        # mistyped path would load rather than say it holds nothing.
+        msg = (
+            f"{root} holds no inventory: it has neither an envelope nor any "
+            f"of the containers {tuple(_CONTAINERS)}."
+        )
+        raise InvalidInventoryError(msg)
     for name, container in _CONTAINERS.items():
         if container.epochs:
             _check_epoch_duplicates(entries.get(name, []))
diff --git a/dascore/utils/time.py b/dascore/utils/time.py
index 547dd6e40..dcd9eb79f 100644
--- a/dascore/utils/time.py
+++ b/dascore/utils/time.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import math
-from datetime import datetime, timedelta
+from datetime import date, datetime, timedelta
 from functools import singledispatch
 from typing import Any, SupportsFloat, cast, overload
 
@@ -186,6 +186,19 @@ def _datetime_to_datetime64(dt: datetime):
     return to_datetime64(np.datetime64(dt, "ns"))
 
 
+@to_datetime64.register(date)
+def _date_to_datetime64(value: date):
+    """
+    Convert a python date to the instant it starts.
+
+    YAML reads an unquoted ``2024-06-01`` as a date rather than a string,
+    so this is the ordinary spelling of a day in a hand-authored file, not
+    an exotic input. Registered after datetime, which is a subclass of
+    date and keeps its own more specific handler.
+    """
+    return np.datetime64(value.isoformat(), "ns")
+
+
 @to_datetime64.register(pd.Timestamp)
 def _pandas_timestamp(datetime: pd.Timestamp):
     return datetime.to_datetime64()
diff --git a/scripts/_index_api.py b/scripts/_index_api.py
index a09b3fa84..5e872db2b 100644
--- a/scripts/_index_api.py
+++ b/scripts/_index_api.py
@@ -198,7 +198,11 @@ def traverse(obj, data_dict, base_path, key=None, parent_is_class=False):
             base_address = _get_base_address(path, base_path)
 
             # this is referenced outside of its base address, skip this one.
-            if base_address not in key:
+            # A prefix test rather than a substring one: the address of
+            # dascore/core/inventory.py is a substring of every key under
+            # dascore/core/inventory_loader.py, so a module named after
+            # another would claim as its own everything it merely imports.
+            if key != base_address and not key.startswith(f"{base_address}."):
                 return
 
             data_dict[str(id(obj))] = get_data(obj, key, base_path, parent_is_class)
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index 850fbfb25..6f3fc31c0 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -8,7 +8,10 @@
 import dascore as dc
 from dascore.core import inventory as inv
 from dascore.core import inventory_loader as loader
-from dascore.exceptions import InvalidInventoryError
+from dascore.exceptions import (
+    InvalidInventoryError,
+    MissingOptionalDependencyError,
+)
 from dascore.utils.models import InventoryModel, TimeRangedModel
 
 pytest.importorskip("yaml")
@@ -350,11 +353,19 @@ def test_restated_start_time_disagrees(self, make_inventory):
         with pytest.raises(InvalidInventoryError, match="must agree with the name"):
             make_inventory(files)
 
-    def test_illegal_address_token_names_the_file(self, make_inventory):
+    @pytest.mark.parametrize(
+        ("name", "level"),
+        # Both address levels, since each is checked by the same loop and
+        # only one of them was ever exercised.
+        [("DAS.L0_01..RAW.yaml", "fiber_array"), ("D_AS.L001..RAW.yaml", "network")],
+    )
+    def test_illegal_address_token_names_the_file(self, make_inventory, name, level):
         """The entity a token names is built from every address, not one file."""
-        files = {"acquisitions/DAS.L0_01..RAW.yaml": "type: Acquisition\n"}
-        with pytest.raises(InvalidInventoryError, match="names fiber_array"):
+        files = {f"acquisitions/{name}": "type: Acquisition\n"}
+        with pytest.raises(InvalidInventoryError, match=f"names {level}") as info:
             make_inventory(files)
+        # The point of the check is which file to open, so assert the name.
+        assert name in str(info.value)
 
     def test_wrong_token_count(self, make_inventory):
         """An acquisition name is an address of four tokens."""
@@ -401,8 +412,8 @@ def test_non_mapping_file_in_a_container(self, make_inventory):
             make_inventory(files)
 
 
-class TestReviewFindings:
-    """Regressions for what the counterpart review found."""
+class TestOverlookedInput:
+    """Input the loader did not inspect, each of which loaded a wrong inventory."""
 
     def test_object_filed_inside_an_entity_directory(self, make_inventory):
         """An object one level too deep must not be silently dropped."""
@@ -469,6 +480,101 @@ def test_unreadable_envelope_value_names_the_file(self, make_inventory):
         with pytest.raises(InvalidInventoryError, match="Could not read the envelope"):
             make_inventory(files)
 
+    @pytest.mark.parametrize(
+        ("where", "field", "member"),
+        [
+            ("networks/DAS.yaml", "stations", "code: STA1"),
+            ("networks/DAS.yaml", "fiber_arrays", "code: L001"),
+            ("fiber_arrays/DAS.L001.yaml", "acquisitions", "code: RAW"),
+        ],
+    )
+    def test_nested_collections_are_refused(self, make_inventory, where, field, member):
+        """A file may not state what the directory supplies and would replace."""
+        declared = "Network" if where.startswith("networks") else "FiberArray"
+        text = f"type: {declared}\n{field}:\n  - {member}\n"
+        with pytest.raises(InvalidInventoryError, match=field):
+            make_inventory({**MINIMAL, where: text})
+
+    def test_child_predating_its_parent_epoch(self, make_inventory):
+        """Containment is checked at the near end as well as the far one."""
+        files = {
+            "networks/DAS@2024-01-01.yaml": "type: Network\n",
+            # No start of its own, so it claims the unbounded past, which is
+            # outside a network beginning in 2024.
+            "stations/DAS.STA1.yaml": "type: Station\nend_time: '2020-01-01'\n",
+        }
+        with pytest.raises(InvalidInventoryError, match="starts before"):
+            make_inventory(files)
+
+    def test_child_ending_after_its_parent_epoch(self, make_inventory):
+        """The far end refuses a real end time, not only an unset one."""
+        files = {
+            "fiber_arrays/DAS.L001.yaml": (
+                "type: FiberArray\nend_time: '2024-06-01'\n"
+            ),
+            "fiber_arrays/DAS.L001@2024-06-01.yaml": "type: FiberArray\n",
+            "acquisitions/DAS.L001..RAW@2024-05-01.yaml": (
+                "type: Acquisition\nend_time: '2024-07-01'\n"
+            ),
+        }
+        with pytest.raises(InvalidInventoryError, match="runs past"):
+            make_inventory(files)
+
+    def test_json_inventory_without_pyyaml(self, tmp_path, monkeypatch):
+        """A JSON inventory loads past whatever YAML lies beside it.
+
+        PyYAML is optional, and the tests which need it skip without it, so
+        this pins the JSON-only path here rather than leaving it to a
+        minimal install nothing in this file would exercise.
+        """
+
+        def no_yaml(name, **kwargs):
+            raise MissingOptionalDependencyError(f"no {name}")
+
+        monkeypatch.setattr(loader, "optional_import", no_yaml)
+        root = write_inventory(
+            tmp_path / "json_only",
+            {
+                "acquisitions/DAS.L001..RAW.json": '{"type": "Acquisition"}',
+                # Field material the loader must step over without reading.
+                "notes/log.yaml": "note: a deployment log\n",
+            },
+        )
+        out = dc.inventory(root)
+        assert out.networks[0].fiber_arrays[0].acquisitions[0].code == "RAW"
+
+    def test_hidden_object_file_in_a_container(self, make_inventory):
+        """A resource id may hold a dot, but a hidden file names no entity."""
+        files = {**MINIMAL, "resources/.cable.yaml": "type: Cable\n"}
+        with pytest.raises(InvalidInventoryError, match="hidden"):
+            make_inventory(files)
+
+    def test_epoch_finer_than_a_nanosecond(self, make_inventory):
+        """A name stating more precision than is kept would load as another instant."""
+        files = {
+            "acquisitions/DAS.L001..RAW@2024-05-12T103000.1234567899.yaml": (
+                "type: Acquisition\n"
+            )
+        }
+        with pytest.raises(InvalidInventoryError, match="finer than the nanosecond"):
+            make_inventory(files)
+
+    def test_unquoted_dates(self, make_inventory):
+        """YAML reads an unquoted date as a date, which is how one is written."""
+        out = make_inventory(
+            {
+                "fiber_arrays/DAS.L001.yaml": (
+                    "type: FiberArray\nstart_time: 2024-01-01\nend_time: 2024-07-01\n"
+                ),
+                "acquisitions/DAS.L001..RAW@2024-02-01.yaml": (
+                    "type: Acquisition\nend_time: 2024-03-01\n"
+                ),
+            }
+        )
+        array = out.networks[0].fiber_arrays[0]
+        assert array.end_time == np.datetime64("2024-07-01", "ns")
+        assert array.acquisitions[0].end_time == np.datetime64("2024-03-01", "ns")
+
     def test_type_which_is_not_a_name(self, make_inventory):
         """A type which is not a name at all names no model either."""
         files = {"acquisitions/DAS.L001..RAW.yaml": "type: [Acquisition]\n"}
@@ -522,7 +628,19 @@ def test_two_names_for_one_epoch(self, make_inventory):
             "acquisitions/DAS.L001..RAW@2024-06-01.yaml": "type: Acquisition\n",
             "acquisitions/DAS.L001..RAW@2024-06-01T000000.yaml": "type: Acquisition\n",
         }
-        with pytest.raises(InvalidInventoryError, match="one epoch"):
+        with pytest.raises(InvalidInventoryError, match="overlap in time"):
+            make_inventory(files)
+
+    def test_overlapping_epochs_of_one_entity(self, make_inventory):
+        """Two epochs of one entity may not overlap, not merely coincide."""
+        files = {
+            "acquisitions/DAS.L001..RAW@2024-01-01.yaml": (
+                "type: Acquisition\nend_time: '2024-08-01'\n"
+            ),
+            "acquisitions/DAS.L001..RAW@2024-06-01.yaml": "type: Acquisition\n",
+        }
+        # Both files are named, since the entity alone would not say which.
+        with pytest.raises(InvalidInventoryError, match="RAW@2024-01-01"):
             make_inventory(files)
 
 
@@ -584,7 +702,7 @@ def test_unreadable_file_names_itself(self, tmp_path):
         root = tmp_path / "unreadable"
         write_inventory(root, MINIMAL)
         (root / "acquisitions" / "DAS.L001..DEC.yaml").write_bytes(b"\xff\xfe\x00")
-        with pytest.raises(InvalidInventoryError, match="Could not read"):
+        with pytest.raises(InvalidInventoryError, match=r"DAS\.L001\.\.DEC\.yaml"):
             dc.inventory(root)
 
 
@@ -772,10 +890,17 @@ def test_yaml_file_still_works(self, tmp_path):
         dc.inventory().to_yaml(path)
         assert isinstance(dc.inventory(path), inv.Inventory)
 
-    def test_empty_directory(self, tmp_path):
-        """A directory with nothing in it is an empty inventory."""
+    def test_directory_which_holds_no_inventory(self, tmp_path):
+        """A mistyped path must not read as an inventory which is empty."""
+        root = tmp_path / "not_an_inventory"
+        (root / "photos").mkdir(parents=True)
+        with pytest.raises(InvalidInventoryError, match="holds no inventory"):
+            dc.inventory(root)
+
+    def test_empty_container_is_an_empty_inventory(self, tmp_path):
+        """A container, even an empty one, says the directory is an inventory."""
         root = tmp_path / "empty"
-        root.mkdir()
+        (root / "acquisitions").mkdir(parents=True)
         assert not dc.inventory(root).networks
 
 
diff --git a/tests/test_utils/test_time.py b/tests/test_utils/test_time.py
index 17bd264f5..6b55b3d4b 100644
--- a/tests/test_utils/test_time.py
+++ b/tests/test_utils/test_time.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import warnings
-from datetime import datetime, timedelta
+from datetime import date, datetime, timedelta
 from decimal import Decimal
 
 import numpy as np
@@ -184,6 +184,17 @@ def test_datetime(self):
         assert isinstance(out, np.datetime64)
         assert out == to_datetime64("2021-01-02")
 
+    def test_date(self):
+        """Ensure a date works, being the instant its day starts."""
+        out = to_datetime64(date.fromisoformat("2021-01-02"))
+        assert isinstance(out, np.datetime64)
+        assert out == to_datetime64("2021-01-02")
+
+    def test_date_does_not_shadow_datetime(self):
+        """A datetime is a date, so it must keep its own handler."""
+        stamp = datetime.fromisoformat("2021-01-02T03:04:05")
+        assert to_datetime64(stamp) == to_datetime64("2021-01-02T03:04:05")
+
     def test_unsupported_type(self):
         """Ensure unsupported types raise."""
         with pytest.raises(NotImplementedError):

From e72e6c33c726bc7234b4cb618e5e79a77f85e889 Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 11:22:19 +0200
Subject: [PATCH 8/9] Address the review bots

Five of eight, both bots having independently found the first:

- The new date handler wrapped silently outside the nanosecond range, so
  an unquoted `end_time: 2500-01-01` read as 1915. It is refused now, by
  reading the result back as text rather than through datetime64[D],
  which is itself unreliable at the boundary: 1677-09-22 is
  representable and converts back as 2262-04-11. Every other spelling of
  a time still wraps, which is #890; this one is guarded because it is
  new, not because it is special.
- A symlink pointing at the inventory root made a valid directory fail
  to load, since the walk found its own acquisition file a second time,
  in a place where nothing contained it. Symlinks are not part of the
  format and are stepped over.
- An envelope stating only its own type read as no envelope at all, so a
  directory holding just inventory.yaml was refused as holding nothing.
  Absence is None now, rather than an empty mapping.
- A field note beside an attrs file was refused for its suffix alone,
  while the same note one directory deeper was ignored. Only a file
  declaring an inventory object is misfiled there.
- `load_directory` and `inventory` are public and now say what they take.

Declined, with the reasons on the PR: adding `date` to `timeable_types`,
which already omits `datetime` -- a spelling `to_datetime64` has long
accepted -- so adding one and not the other would encode a new
inconsistency in a public alias; and applying epoch containment to
children stated inline in a file, since the loader checks containment
where it chooses the placement, and doing so for content a file nests
directly would make a directory refuse an inventory the models accept
and `to_yaml` round-trips.
---
 dascore/core/inventory_loader.py         | 38 +++++++++++++++++-------
 dascore/utils/time.py                    | 14 ++++++++-
 tests/test_core/test_inventory_loader.py | 35 +++++++++++++++++++++-
 tests/test_utils/test_time.py            | 11 +++++++
 4 files changed, 85 insertions(+), 13 deletions(-)

diff --git a/dascore/core/inventory_loader.py b/dascore/core/inventory_loader.py
index 55aced697..9c023f0d5 100644
--- a/dascore/core/inventory_loader.py
+++ b/dascore/core/inventory_loader.py
@@ -475,11 +475,18 @@ def _attrs_file(entity: Path) -> Path:
         if _object_suffix(child) is None:
             continue
         if _entry_name(child).casefold() != _ATTRS_STEM:
-            msg = (
-                f"{_quote(child)} is not part of an entity directory, whose "
-                f"object file is named {_ATTRS_STEM}."
-            )
-            raise InvalidInventoryError(msg)
+            # Only a file claiming to be an inventory object is misfiled
+            # here; a field note which happens to be YAML is no more
+            # participating than one nested a directory deeper, which the
+            # stray walk already steps over.
+            if _declared_type(child) in _model_names():
+                msg = (
+                    f"{_quote(child)} declares an inventory object, but an "
+                    f"entity directory holds only its {_ATTRS_STEM} file "
+                    "and its tracks."
+                )
+                raise InvalidInventoryError(msg)
+            continue
         found.append(child)
     if not found:
         msg = (
@@ -757,7 +764,7 @@ def _assemble(entries: Mapping[str, list[_Entry]]) -> tuple[Network, ...]:
     return tuple(out)
 
 
-def _load_envelope(root: Path) -> dict[str, Any]:
+def _load_envelope(root: Path) -> dict[str, Any] | None:
     """
     Read the document-level singletons from the envelope.
 
@@ -775,8 +782,11 @@ def _load_envelope(root: Path) -> dict[str, Any]:
         and _object_suffix(child) is not None
         and _entry_name(child).casefold() == _ENVELOPE_STEM
     ]
+    # None rather than an empty mapping: an envelope stating only its
+    # own type says the directory is an inventory, which is a different
+    # fact from there being no envelope at all.
     if not found:
-        return {}
+        return None
     if len(found) > 1:
         spelled = ", ".join(x.name for x in found)
         msg = f"The envelope is spelled more than once ({spelled})."
@@ -815,6 +825,12 @@ def _refuse_stray_objects(start: Path, root: Path, skip: Path | None = None) ->
     def check(path: Path):
         if path.name.startswith(".") or path == skip:
             return
+        # A symlink is not part of the format, and one pointing at an
+        # ancestor walks the inventory a second time -- where its own files
+        # are found with nothing containing them, so a valid directory
+        # reports itself as stray, and the walk recurses until it cannot.
+        if path.is_symlink():
+            return
         if path.is_dir():
             for child in sorted(path.iterdir()):
                 check(child)
@@ -840,7 +856,7 @@ def _check_strays(root: Path) -> None:
         _refuse_stray_objects(child, root)
 
 
-def load_directory(path) -> Inventory:
+def load_directory(path: str | os.PathLike) -> Inventory:
     """
     Load an inventory from a directory in the authoring format.
 
@@ -860,7 +876,7 @@ def load_directory(path) -> Inventory:
     # After the stray check, which knows why a directory holds no container:
     # a mistyped `aquisitions/` can say so, rather than being reported as a
     # directory holding nothing.
-    if not entries and not envelope:
+    if not entries and envelope is None:
         # Every directory would otherwise be an empty inventory, so a
         # mistyped path would load rather than say it holds nothing.
         msg = (
@@ -873,10 +889,10 @@ def load_directory(path) -> Inventory:
             _check_epoch_duplicates(entries.get(name, []))
     resources = {x.model.resource_id: x.model for x in entries.get("resources", [])}
     networks = _assemble(entries)
-    return Inventory(**envelope, resources=resources, networks=networks).check()
+    return Inventory(**(envelope or {}), resources=resources, networks=networks).check()
 
 
-def inventory(source=None) -> Inventory:
+def inventory(source: Inventory | str | os.PathLike | None = None) -> Inventory:
     """
     Load or create a DASDAE inventory.
 
diff --git a/dascore/utils/time.py b/dascore/utils/time.py
index dcd9eb79f..336a91b81 100644
--- a/dascore/utils/time.py
+++ b/dascore/utils/time.py
@@ -196,7 +196,19 @@ def _date_to_datetime64(value: date):
     an exotic input. Registered after datetime, which is a subclass of
     date and keeps its own more specific handler.
     """
-    return np.datetime64(value.isoformat(), "ns")
+    out = np.datetime64(value.isoformat(), "ns")
+    # A datetime64 spans about 1678 to 2262 and wraps silently past either
+    # end, so a day outside it would come back as one centuries away. Read
+    # back as text rather than through datetime64[D], which is itself
+    # unreliable at the boundary: 1677-09-22 is representable but converts
+    # to 2262-04-11. The other spellings of a time still wrap; see #890.
+    if not str(out).startswith(value.isoformat()):
+        msg = (
+            f"Date {value.isoformat()} is outside the range a nanosecond "
+            f"timestamp can represent; it would read as {out}."
+        )
+        raise ValueError(msg)
+    return out
 
 
 @to_datetime64.register(pd.Timestamp)
diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index 6f3fc31c0..151e491aa 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import os
+
 import numpy as np
 import pytest
 
@@ -520,6 +522,22 @@ def test_child_ending_after_its_parent_epoch(self, make_inventory):
         with pytest.raises(InvalidInventoryError, match="runs past"):
             make_inventory(files)
 
+    def test_symlink_pointing_at_the_inventory(self, tmp_path):
+        """Walking a loop would find the inventory's own files uncontained."""
+        root = write_inventory(tmp_path / "looped", MINIMAL)
+        (root / "photos").mkdir()
+        os.symlink(root, root / "photos" / "loop")
+        # Without skipping the link this reports DAS.L001..RAW.yaml, reached
+        # through it, as an object nothing contains.
+        assert dc.inventory(root).networks[0].code == "DAS"
+
+    def test_envelope_stating_only_its_type(self, tmp_path):
+        """An envelope says the directory is an inventory, whatever it holds."""
+        root = write_inventory(
+            tmp_path / "bare", {"inventory.yaml": "type: Inventory\n"}
+        )
+        assert not dc.inventory(root).networks
+
     def test_json_inventory_without_pyyaml(self, tmp_path, monkeypatch):
         """A JSON inventory loads past whatever YAML lies beside it.
 
@@ -656,9 +674,24 @@ def test_missing_attrs_file(self, make_inventory):
     def test_stray_object_file(self, make_inventory):
         """An entity directory's object file is named attrs."""
         files = {"fiber_arrays/DAS.L001/array.yaml": "type: FiberArray\n"}
-        with pytest.raises(InvalidInventoryError, match="not part of an entity"):
+        with pytest.raises(InvalidInventoryError, match="holds only its attrs"):
             make_inventory(files)
 
+    def test_field_note_beside_an_attrs_file(self, make_inventory):
+        """A note which happens to be YAML is not a misfiled object."""
+        out = make_inventory(
+            {
+                **MINIMAL,
+                "fiber_arrays/DAS.L001/attrs.yaml": (
+                    "type: FiberArray\nname: from a directory\n"
+                ),
+                # Declares nothing, so it participates in nothing -- exactly
+                # as it would one directory deeper.
+                "fiber_arrays/DAS.L001/notes.yaml": "site: wellhead\n",
+            }
+        )
+        assert out.networks[0].fiber_arrays[0].name == "from a directory"
+
     def test_attrs_spelled_twice(self, make_inventory):
         """One identity is spelled once inside the directory too."""
         files = {
diff --git a/tests/test_utils/test_time.py b/tests/test_utils/test_time.py
index 6b55b3d4b..0f6c6d145 100644
--- a/tests/test_utils/test_time.py
+++ b/tests/test_utils/test_time.py
@@ -195,6 +195,17 @@ def test_date_does_not_shadow_datetime(self):
         stamp = datetime.fromisoformat("2021-01-02T03:04:05")
         assert to_datetime64(stamp) == to_datetime64("2021-01-02T03:04:05")
 
+    @pytest.mark.parametrize("iso", ["2500-01-01", "1000-01-01"])
+    def test_date_outside_the_representable_range(self, iso):
+        """A datetime64 wraps silently, so such a date is refused."""
+        with pytest.raises(ValueError, match="outside the range"):
+            to_datetime64(date.fromisoformat(iso))
+
+    @pytest.mark.parametrize("iso", ["2262-04-11", "1677-09-22"])
+    def test_the_outermost_representable_days(self, iso):
+        """The check refuses what wraps without refusing what does not."""
+        assert to_datetime64(date.fromisoformat(iso)) == to_datetime64(iso)
+
     def test_unsupported_type(self):
         """Ensure unsupported types raise."""
         with pytest.raises(NotImplementedError):

From 508c95d77a4828c38d3797e62c9338368e5f790b Mon Sep 17 00:00:00 2001
From: Derrick Chambers <chambers.ja.derrick@gmail.com>
Date: Thu, 13 Aug 2026 11:35:49 +0200
Subject: [PATCH 9/9] Let the case rule be tested where case is folded

The test for two names differing only by case wrote both and expected a
collision, which cannot happen on a filesystem that folds case: the
second write replaces the first, so one file exists and nothing
collides. Five macOS and Windows jobs failed on it, all with the same
DID NOT RAISE, while the rule they were failing is the reason the guard
exists -- an inventory authored where both names fit must not quietly
lose one when it is copied somewhere they do not.

The collision test now skips where it cannot be built, decided once at
collection, and the half which can be checked anywhere -- that the two
are reported as differing by case rather than as some other collision --
is pinned separately, so no platform is left without coverage of the
rule.
---
 tests/test_core/test_inventory_loader.py | 31 ++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/tests/test_core/test_inventory_loader.py b/tests/test_core/test_inventory_loader.py
index 151e491aa..8bf316f1e 100644
--- a/tests/test_core/test_inventory_loader.py
+++ b/tests/test_core/test_inventory_loader.py
@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import os
+import tempfile
+from pathlib import Path
 
 import numpy as np
 import pytest
@@ -34,6 +36,19 @@ def write_inventory(root, files) -> object:
     return root
 
 
+def _folds_case() -> bool:
+    """Return True if this filesystem holds two case variants as one file."""
+    with tempfile.TemporaryDirectory() as name:
+        directory = Path(name)
+        (directory / "CaseProbe").write_text("")
+        return (directory / "caseprobe").exists()
+
+
+# Asked once, at collection. Windows and most macOS checkouts fold case, so
+# a name differing from another only by case is the same file there.
+FOLDS_CASE = _folds_case()
+
+
 @pytest.fixture
 def make_inventory(tmp_path):
     """Return a function which writes a directory and loads it."""
@@ -612,6 +627,12 @@ def test_two_extensions(self, make_inventory):
         with pytest.raises(InvalidInventoryError, match="two extensions"):
             make_inventory(files)
 
+    # Where case is folded, writing the second name replaces the first
+    # rather than joining it, so the collision this refuses cannot be built.
+    # That is the rule holding rather than failing: the guard exists so an
+    # inventory authored where both names fit does not quietly lose one when
+    # it is copied somewhere they do not.
+    @pytest.mark.skipif(FOLDS_CASE, reason="this filesystem holds one of the two")
     def test_case_only_difference(self, make_inventory):
         """A case-insensitive filesystem could not hold both."""
         files = {
@@ -621,6 +642,16 @@ def test_case_only_difference(self, make_inventory):
         with pytest.raises(InvalidInventoryError, match="differ only by case"):
             make_inventory(files)
 
+    def test_case_only_difference_is_named_as_such(self, tmp_path):
+        """The reason two entries collide, on every filesystem.
+
+        The test above cannot run where case is folded, which is every
+        Windows and most macOS checkouts, so the explaining half of the
+        rule is pinned here instead.
+        """
+        first, second = tmp_path / "DAS.L001.yaml", tmp_path / "das.l001.yaml"
+        assert "differ only by case" in loader._collide(first, second)
+
     def test_file_and_directory(self, make_inventory):
         """Both spellings of one identity at once raise."""
         files = {