aind-metadata-reader 0.2.0__py3-none-any.whl

aind_metadata_reader/document.py

@@ -0,0 +1,399 @@
+"""Preserved snapshots and JSON Pointer views, independent of upstream schema runtimes."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, fields
+from datetime import datetime, timezone
+from functools import cached_property
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Literal, cast
+
+from aind_metadata_reader._wire import canonical, digest, object_fields, parse_json, string, string_array, strings
+from aind_metadata_reader._wire import json_value as _json_value
+from aind_metadata_reader.diagnostics import FieldState, MetadataError
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, dict):
+        return MappingProxyType({key: _freeze(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+def _thaw(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _thaw(item) for key, item in value.items()}
+    if isinstance(value, tuple):
+        return [_thaw(item) for item in value]
+    return value
+
+
+def encode_segment(segment: str) -> str:
+    """Escape one JSON Pointer segment, including names containing slash or tilde."""
+    return segment.replace("~", "~0").replace("/", "~1")
+
+
+def _segments(pointer: str) -> list[str]:
+    if pointer == "":
+        return []
+    if not pointer.startswith("/"):
+        raise MetadataError("JSON Pointer must be empty or start with '/'", code="invalid_pointer", pointer=pointer)
+    result = []
+    for segment in pointer[1:].split("/"):
+        remaining = segment.replace("~0", "").replace("~1", "")
+        if "~" in remaining:
+            raise MetadataError("Invalid JSON Pointer escape", code="invalid_pointer", pointer=pointer)
+        result.append(segment.replace("~1", "/").replace("~0", "~"))
+    return result
+
+
+@dataclass(frozen=True)
+class Source:
+    """Caller-supplied source evidence; these fields make no assertion of authority."""
+
+    kind: Literal["mapping", "file", "s3", "docdb"] = "mapping"
+    locator: str | None = None
+    retrieved_at: str | None = None
+    revision: str | None = None
+    host: str | None = None
+    api_version: str | None = None
+    database: str | None = None
+    collection: str | None = None
+    record_id: str | None = None
+    asset_location: str | None = None
+    derived_from: tuple[str, ...] = ()
+    converter_version: str | None = None
+    interpretation_id: str | None = None
+
+    def __post_init__(self) -> None:
+        """Keep source evidence immutable and reject invalid provenance types."""
+        if self.kind not in ("mapping", "file", "s3", "docdb"):
+            raise MetadataError("Unknown source kind", code="invalid_source")
+        for item in fields(self):
+            value = getattr(self, item.name)
+            if item.name not in ("kind", "derived_from") and value is not None:
+                string(value, code="invalid_source")
+        object.__setattr__(self, "derived_from", strings(self.derived_from, code="invalid_source"))
+
+    def record(self, *, legacy: bool = False) -> dict[str, Any]:
+        """Export provenance separately from payload and source-aware identity."""
+        result = asdict(self)
+        result["derived_from"] = list(self.derived_from)
+        if legacy:
+            result.pop("interpretation_id")
+        return result
+
+    @classmethod
+    def from_record(cls, value: Any, *, legacy: bool = False) -> Source:
+        """Read exact source fields without converting malformed strings to arrays."""
+        names = {item.name for item in fields(cls)}
+        if legacy:
+            names.remove("interpretation_id")
+        data = dict(object_fields(value, names, code="invalid_source"))
+        data["derived_from"] = string_array(data["derived_from"], code="invalid_source")
+        return cls(**data)
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    """Immutable JSON storage with separate semantic-content and original-byte digests.
+
+    Canonicalization is Python JSON with sorted keys, ASCII escapes, no whitespace,
+    and no nonfinite numbers; it is not RFC 8785. Integers retain Python precision;
+    fractional values use binary64. Original bytes preserve number spellings.
+    """
+
+    _canonical: bytes
+    source: Source
+    original_bytes: bytes | None = None
+
+    @cached_property
+    def _tree(self) -> Any:
+        # Process/axis views select many small subtrees. Repeatedly decoding the
+        # entire aggregate for each field would scale quadratically.
+        return _freeze(json.loads(self._canonical))
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any], source: Source) -> Snapshot:
+        """Detach data into immutable storage, rejecting implicit JSON coercions."""
+        obj = dict(data)
+        _json_value(obj)
+        return cls(canonical(obj), source)
+
+    @classmethod
+    def from_bytes(cls, payload: bytes, source: Source) -> Snapshot:
+        """Keep exact transport bytes and reject duplicate keys or nonfinite numbers."""
+        obj = parse_json(payload)
+        if not isinstance(obj, dict):
+            raise MetadataError("Expected a JSON object", code="invalid_json")
+        snapshot = cls.from_mapping(obj, source)
+        return cls(snapshot._canonical, source, payload)
+
+    @property
+    def content_digest(self) -> str:
+        """Identify parsed content under the documented canonicalization scheme."""
+        return "python-json-v1:sha256:" + hashlib.sha256(self._canonical).hexdigest()
+
+    @property
+    def original_digest(self) -> str | None:
+        """Identify exact bytes when the caller supplied them."""
+        return None if self.original_bytes is None else "sha256:" + hashlib.sha256(self.original_bytes).hexdigest()
+
+    @property
+    def snapshot_id(self) -> str:
+        """Identify exact captured content, source evidence, bytes, and derivation."""
+        return digest(
+            "metadata-snapshot-v1",
+            {
+                "content_digest": self.content_digest,
+                "original_digest": self.original_digest,
+                "source": self.source.record(),
+            },
+        )
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        """Return an independent copy of the complete snapshot."""
+        return cast(dict[str, Any], json.loads(self._canonical))
+
+    def archive(self) -> dict[str, Any]:
+        """Export an offline snapshot with original bytes and source context intact."""
+        return {
+            "format": "metadata-snapshot/2",
+            "payload": self.raw,
+            "source": self.source.record(),
+            "original_bytes": None if self.original_bytes is None else base64.b64encode(self.original_bytes).decode(),
+            "content_digest": self.content_digest,
+            "original_digest": self.original_digest,
+            "snapshot_id": self.snapshot_id,
+        }
+
+    @classmethod
+    def from_archive(cls, archive: dict[str, Any]) -> Snapshot:
+        """Restore a retained snapshot, rejecting mismatched bytes, content, or digests."""
+        if not isinstance(archive, dict) or archive.get("format") not in ("metadata-snapshot/1", "metadata-snapshot/2"):
+            raise MetadataError("Unsupported snapshot archive", code="unsupported_archive")
+        legacy = archive["format"] == "metadata-snapshot/1"
+        names = {"format", "payload", "source", "original_bytes", "content_digest", "original_digest"}
+        object_fields(archive, names if legacy else names | {"snapshot_id"}, code="invalid_archive")
+        if not isinstance(archive["payload"], dict):
+            raise MetadataError("Archive payload must be an object", code="invalid_archive")
+        try:
+            source = Source.from_record(archive["source"], legacy=legacy)
+            snapshot = cls.from_mapping(archive["payload"], source)
+            if archive["original_bytes"] is not None:
+                payload = base64.b64decode(string(archive["original_bytes"], code="invalid_archive"), validate=True)
+                original = cls.from_bytes(payload, source)
+                if original.content_digest != snapshot.content_digest:
+                    raise MetadataError("Original bytes do not match archived content", code="archive_mismatch")
+                snapshot = original
+        except (KeyError, TypeError, ValueError) as error:
+            if isinstance(error, MetadataError):
+                raise
+            raise MetadataError(f"Invalid snapshot archive: {error}", code="invalid_archive") from error
+        if snapshot.content_digest != archive.get("content_digest") or snapshot.original_digest != archive.get(
+            "original_digest"
+        ):
+            raise MetadataError("Snapshot digest mismatch", code="archive_mismatch")
+        if not legacy and archive["snapshot_id"] != snapshot.snapshot_id:
+            raise MetadataError("Snapshot identity mismatch", code="archive_mismatch")
+        return snapshot
+
+    def field(self, pointer: str) -> Field:
+        """Locate a value in this snapshot, preserving its availability state."""
+        value: Any = self._tree
+        for segment in _segments(pointer):
+            if isinstance(value, Mapping) and segment in value:
+                value = value[segment]
+            elif isinstance(value, tuple) and segment.isascii() and segment.isdigit() and str(int(segment)) == segment:
+                if int(segment) >= len(value):
+                    return Field(self, pointer, FieldState.ABSENT)
+                value = value[int(segment)]
+            else:
+                return Field(self, pointer, FieldState.ABSENT)
+        state = FieldState.NULL if value is None else FieldState.PRESENT
+        return Field(self, pointer, state, json.dumps(_thaw(value), allow_nan=False))
+
+
+@dataclass(frozen=True)
+class Field:
+    """An immutable field reference retaining the parent snapshot and source pointer."""
+
+    snapshot: Snapshot
+    pointer: str
+    state: FieldState
+    _json: str = "null"
+
+    @property
+    def value(self) -> Any:
+        """Return the value, requiring callers to check state to distinguish missing/null."""
+        return json.loads(self._json)
+
+    def require(self) -> Any:
+        """Require a recorded non-null value with a structured failure otherwise."""
+        if self.state != FieldState.PRESENT:
+            raise MetadataError(
+                f"Required field is {self.state}",
+                code=self.state.value,
+                pointer=self.pointer,
+                snapshot_id=self.snapshot.snapshot_id,
+            )
+        return self.value
+
+
+@dataclass(frozen=True, init=False)
+class Document:
+    """An object view into a snapshot; child views retain aggregate identity and context."""
+
+    snapshot: Snapshot
+    pointer: str
+
+    def __init__(self, data: Mapping[str, Any], *, source: str | None = None, provenance: Source | None = None) -> None:
+        """Create a snapshot without inferring transport or authority from a locator."""
+        if source is not None and provenance is not None and source != provenance.locator:
+            raise MetadataError("Conflicting source and provenance locators", code="conflicting_source")
+        object.__setattr__(self, "snapshot", Snapshot.from_mapping(data, provenance or Source(locator=source)))
+        object.__setattr__(self, "pointer", "")
+
+    @classmethod
+    def from_snapshot(cls, snapshot: Snapshot, pointer: str = "") -> Document:
+        """Select an object without copying away its parent context."""
+        field = snapshot.field(pointer)
+        value = field.require()
+        if not isinstance(value, dict):
+            raise MetadataError("Expected an object", pointer=pointer, snapshot_id=snapshot.snapshot_id)
+        obj = object.__new__(cls)
+        object.__setattr__(obj, "snapshot", snapshot)
+        object.__setattr__(obj, "pointer", pointer)
+        return obj
+
+    @property
+    def source(self) -> str | None:
+        """Return the original source locator."""
+        return self.snapshot.source.locator
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        """Return the selected object, retaining unknown fields and source values."""
+        return cast(dict[str, Any], self.snapshot.field(self.pointer).require())
+
+    def field(self, pointer: str) -> Field:
+        """Resolve a JSON Pointer relative to this object, returning a root-qualified reference."""
+        _segments(pointer)
+        return self.snapshot.field(self.pointer + pointer)
+
+    def child(self, pointer: str) -> Document:
+        """Select a nested object with the same root snapshot."""
+        _segments(pointer)
+        return Document.from_snapshot(self.snapshot, self.pointer + pointer)
+
+    def core(self, name: str) -> Document:
+        """Select a core while retaining the aggregate's provenance and recorded IDs."""
+        return self.child("/" + encode_segment(name))
+
+    def reference(self) -> SnapshotReference:
+        """Retain a portable, source-qualified reference without copying the payload."""
+        return SnapshotReference(
+            self.snapshot.snapshot_id,
+            self.snapshot.content_digest,
+            self.snapshot.original_digest,
+            self.snapshot.source,
+            self.pointer,
+        )
+
+    def optional_string(self, pointer: str) -> str | None:
+        """Read an optional string, preserving absent/null distinctions through field()."""
+        field = self.field(pointer)
+        if field.state != FieldState.PRESENT:
+            return None
+        value = field.value
+        return value if isinstance(value, str) else None
+
+    @property
+    def schema_version(self) -> str | None:
+        """Return the recorded core version without manufacturing one."""
+        return self.optional_string("/schema_version")
+
+    @property
+    def described_by(self) -> str | None:
+        """Return the recorded schema identifier."""
+        return self.optional_string("/describedBy")
+
+    @property
+    def schema_family(self) -> str | None:
+        """Recognize the namespace, retaining unknown identifiers for dispatch diagnostics."""
+        identifier = self.described_by or ""
+        if "/biodata_schema/" in identifier:
+            return "biodata"
+        if "/aind_data_schema/" in identifier:
+            return "aind"
+        return None
+
+
+@dataclass(frozen=True)
+class SnapshotReference:
+    """An exact captured snapshot and an absolute pointer into its retained payload."""
+
+    snapshot_id: str
+    content_digest: str
+    original_digest: str | None
+    source: Source
+    pointer: str = ""
+
+    def __post_init__(self) -> None:
+        """Validate self-contained identity and pointer without claiming availability."""
+        string(self.snapshot_id, code="invalid_reference")
+        string(self.content_digest, code="invalid_reference")
+        if self.original_digest is not None:
+            string(self.original_digest, code="invalid_reference")
+        if not isinstance(self.source, Source):
+            raise MetadataError("Reference source must be Source", code="invalid_reference")
+        string(self.pointer, code="invalid_reference", empty=True)
+        _segments(self.pointer)
+        expected = digest(
+            "metadata-snapshot-v1",
+            {
+                "content_digest": self.content_digest,
+                "original_digest": self.original_digest,
+                "source": self.source.record(),
+            },
+        )
+        if self.snapshot_id != expected:
+            raise MetadataError("Reference identity does not match its source and digests", code="invalid_reference")
+
+    def record(self) -> dict[str, Any]:
+        """Export a structured reference; archives must be retained separately."""
+        return {
+            "snapshot_id": self.snapshot_id,
+            "content_digest": self.content_digest,
+            "original_digest": self.original_digest,
+            "source": self.source.record(),
+            "pointer": self.pointer,
+        }
+
+    @classmethod
+    def from_record(cls, value: Any) -> SnapshotReference:
+        """Restore a structured reference without resolving or fetching its source."""
+        data = dict(
+            object_fields(
+                value,
+                {"snapshot_id", "content_digest", "original_digest", "source", "pointer"},
+                code="invalid_reference",
+            )
+        )
+        data["source"] = Source.from_record(data["source"])
+        return cls(**data)
+
+
+def read_json(path: str | Path) -> Document:
+    """Read a local snapshot without modifying it or consulting metadata services."""
+    path = Path(path)
+    payload = path.read_bytes()
+    source = Source(kind="file", locator=str(path), retrieved_at=datetime.now(timezone.utc).isoformat())
+    return Document.from_snapshot(Snapshot.from_bytes(payload, source))

aind_metadata_reader/formats.py

@@ -0,0 +1,171 @@
+"""Declared, capability-specific compatibility; package majors are not reader contracts."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib.metadata import version
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from aind_metadata_reader._wire import object_fields, string, string_array, strings
+from aind_metadata_reader.diagnostics import FieldState, MetadataError, UnsupportedVersionError
+from aind_metadata_reader.document import Document, SnapshotReference
+
+
+@dataclass(frozen=True)
+class Format:
+    """One supported representation and the exact core versions currently exercised."""
+
+    name: str
+    family: str
+    core: Literal["acquisition", "processing"]
+    layout: Literal["legacy", "configured", "flat"]
+    versions: tuple[str, ...]
+    capabilities: tuple[str, ...]
+
+
+FORMATS = (
+    Format(
+        "aind.acquisition.legacy",
+        "aind",
+        "acquisition",
+        "legacy",
+        ("1.0.0", "1.0.3", "1.0.4"),
+        ("axes", "array_dimensions"),
+    ),
+    Format(
+        "aind.acquisition.configured", "aind", "acquisition", "configured", ("2.0.0", "2.5.3", "2.5.4"), ("frames",)
+    ),
+    Format("biodata.acquisition.configured", "biodata", "acquisition", "configured", ("3.0.0",), ("frames",)),
+    Format(
+        "aind.processing.legacy", "aind", "processing", "legacy", ("1.1.0", "1.1.4"), ("processes", "input_locations")
+    ),
+    Format(
+        "aind.processing.flat",
+        "aind",
+        "processing",
+        "flat",
+        ("2.0.0", "2.2.5", "2.3.1", "2.3.2", "2.3.3"),
+        ("processes", "input_assets"),
+    ),
+    Format("biodata.processing.flat", "biodata", "processing", "flat", ("3.0.0",), ("processes", "input_assets")),
+)
+
+
+@dataclass(frozen=True)
+class ReaderSelection:
+    """Interpretation identity and evidence, without relabeling the source schema."""
+
+    format: Format
+    declared_version: str | None
+    basis: tuple[str, ...]
+
+    def record_for(self, document: Document) -> ReaderRecord:
+        """Attach the actual reader selection and installed package version to an input."""
+        return ReaderRecord(
+            document.reference(), self.format.name, self.declared_version, self.basis, version("aind-metadata-reader")
+        )
+
+
+@dataclass(frozen=True)
+class ReaderRecord:
+    """Historical reader provenance, restored without invoking today's dispatch table."""
+
+    document: SnapshotReference
+    format_name: str
+    declared_version: str | None
+    basis: tuple[str, ...]
+    reader_version: str
+
+    def __post_init__(self) -> None:
+        """Detach selection evidence and require explicit implementation attribution."""
+        if not isinstance(self.document, SnapshotReference):
+            raise MetadataError("Reader input must be a snapshot reference", code="invalid_reader_record")
+        string(self.format_name, code="invalid_reader_record")
+        string(self.reader_version, code="invalid_reader_record")
+        if self.declared_version is not None:
+            string(self.declared_version, code="invalid_reader_record")
+        object.__setattr__(self, "basis", strings(self.basis, code="invalid_reader_record"))
+
+    def record(self) -> dict[str, Any]:
+        """Export the selection without embedding a mutable current registry entry."""
+        return {
+            "document": self.document.record(),
+            "format_name": self.format_name,
+            "declared_version": self.declared_version,
+            "basis": list(self.basis),
+            "reader_version": self.reader_version,
+        }
+
+    @classmethod
+    def from_record(cls, value: Any) -> ReaderRecord:
+        """Restore saved reader provenance independently of present reader support."""
+        data = dict(
+            object_fields(
+                value,
+                {"document", "format_name", "declared_version", "basis", "reader_version"},
+                code="invalid_reader_record",
+            )
+        )
+        data["document"] = SnapshotReference.from_record(data["document"])
+        data["basis"] = string_array(data["basis"], code="invalid_reader_record")
+        return cls(**data)
+
+
+def select_reader(
+    document: Document, core: Literal["acquisition", "processing"], hint: str | None = None
+) -> ReaderSelection:
+    """Require consistent format identity; unversioned configured records need a hint."""
+    version = _declared_string(document, "/schema_version")
+    identifier = _declared_string(document, "/describedBy")
+    basis = []
+    if version is not None:
+        if not re.fullmatch(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.+-]+)?", version):
+            raise MetadataError(
+                "Invalid schema_version", code="invalid_version", pointer=document.field("/schema_version").pointer
+            )
+        basis.append("recorded core schema_version")
+    candidates = [f for f in FORMATS if f.core == core]
+    if identifier is not None:
+        stem = urlparse(identifier).path.rsplit("/", 1)[-1]
+        if document.schema_family is None or stem != core + ".py":
+            raise UnsupportedVersionError(
+                f"Unrecognized schema identifier for {core}: {identifier}",
+                code="unsupported_format",
+                pointer=document.field("/describedBy").pointer,
+                snapshot_id=document.snapshot.snapshot_id,
+            )
+        candidates = [f for f in candidates if f.family == document.schema_family]
+        basis.append("recorded schema namespace and core type")
+    if hint is not None:
+        candidates = [f for f in candidates if f.name == hint]
+        basis.append("caller-supplied format hint: " + hint)
+    if version is not None:
+        candidates = [f for f in candidates if version in f.versions]
+    elif hint is None:
+        marker = "/axes" if core == "acquisition" else "/processing_pipeline"
+        if document.field(marker).state == FieldState.PRESENT:
+            candidates = [f for f in candidates if f.layout == "legacy"]
+            basis.append("unversioned legacy structural marker: " + marker)
+        else:
+            candidates = []
+    if len(candidates) != 1:
+        raise UnsupportedVersionError(
+            f"No unique supported {core} format for schema_version {version!r}; format is not a registered format",
+            code="unsupported_format",
+            pointer=document.pointer,
+            snapshot_id=document.snapshot.snapshot_id,
+        )
+    return ReaderSelection(candidates[0], version, tuple(basis))
+
+
+def _declared_string(document: Document, pointer: str) -> str | None:
+    field = document.field(pointer)
+    if field.state != FieldState.PRESENT:
+        return None
+    if not isinstance(field.value, str):
+        raise MetadataError(
+            "Schema identity field must be a string", pointer=field.pointer, snapshot_id=document.snapshot.snapshot_id
+        )
+    return field.value

aind_metadata_reader/inspection.py

@@ -0,0 +1,109 @@
+"""Partial interpretations retain their raw fields and explain unavailable meanings."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from aind_metadata_reader._enum import StringEnum
+from aind_metadata_reader.diagnostics import Diagnostic, FieldState, MetadataError
+from aind_metadata_reader.document import Document, Field
+
+T = TypeVar("T")
+
+
+class ReadStatus(StringEnum):
+    """Availability of an interpretation, independent of schema validation."""
+
+    AVAILABLE = "available"
+    ABSENT = "absent"
+    NULL = "null"
+    INVALID = "invalid"
+    UNSUPPORTED = "unsupported"
+    AMBIGUOUS = "ambiguous"
+
+
+@dataclass(frozen=True)
+class ReadValue(Generic[T]):
+    """A raw field and its optional interpretation; inspection itself never requires it."""
+
+    field: Field
+    status: ReadStatus
+    value: T | None = None
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    def require(self) -> T:
+        """Assert an operation's requirement explicitly, without gating ordinary reading."""
+        if self.status != ReadStatus.AVAILABLE:
+            diagnostic = (
+                self.diagnostics[0] if self.diagnostics else issue(self.field, self.status.value, "Value unavailable")
+            )
+            raise MetadataError(
+                diagnostic.message, code=diagnostic.code, pointer=diagnostic.pointer, snapshot_id=diagnostic.snapshot_id
+            )
+        from typing import cast
+
+        return cast(T, self.value)
+
+
+def issue(field: Field, code: str, message: str) -> Diagnostic:
+    """Keep diagnostics tied to the actual recorded field and complete capture."""
+    return Diagnostic(code, message, field.pointer, field.snapshot.snapshot_id)
+
+
+def unavailable(field: Field, status: ReadStatus, message: str, code: str | None = None) -> ReadValue[Any]:
+    """Describe a limitation without discarding the source field or inventing a value."""
+    return ReadValue(field, status, diagnostics=(issue(field, code or status.value, message),))
+
+
+def observe(field: Field, decoder: Callable[[Any], T]) -> ReadValue[T]:
+    """Interpret one field independently of sibling validity."""
+    if field.state != FieldState.PRESENT:
+        status = ReadStatus.ABSENT if field.state == FieldState.ABSENT else ReadStatus.NULL
+        return ReadValue(field, status)
+    try:
+        return ReadValue(field, ReadStatus.AVAILABLE, decoder(field.value))
+    except (ValueError, TypeError) as error:
+        message = error.diagnostic.message if isinstance(error, MetadataError) else str(error)
+        code = error.diagnostic.code if isinstance(error, MetadataError) else "invalid_structure"
+        return unavailable(field, ReadStatus.INVALID, message, code)
+
+
+def as_string(value: Any) -> str:
+    """Keep vocabulary values open while rejecting implicit string conversions."""
+    if not isinstance(value, str):
+        raise MetadataError("Expected a string")
+    return value
+
+
+def as_object(value: Any) -> dict[str, Any]:
+    """Recognize an object without enforcing today's complete schema."""
+    if not isinstance(value, dict):
+        raise MetadataError("Expected an object")
+    return value
+
+
+def object_view(field: Field) -> ReadValue[Document]:
+    """Preserve non-object entries as unavailable views of their actual raw fields."""
+    obj = observe(field, as_object)
+    if obj.status != ReadStatus.AVAILABLE:
+        return ReadValue(field, obj.status, diagnostics=obj.diagnostics)
+    return ReadValue(field, ReadStatus.AVAILABLE, Document.from_snapshot(field.snapshot, field.pointer))
+
+
+def children(document: Document, pointer: str) -> ReadValue[tuple[ReadValue[Document], ...]]:
+    """Retain every list position, including malformed entries between valid siblings."""
+    field = document.field(pointer)
+    if field.state != FieldState.PRESENT:
+        return observe(field, lambda _: ())
+    raw = field.value
+    if not isinstance(raw, list):
+        return unavailable(field, ReadStatus.INVALID, "Expected a list of objects")
+    entries = tuple(object_view(document.field(f"{pointer}/{i}")) for i in range(len(raw)))
+    return ReadValue(field, ReadStatus.AVAILABLE, entries, tuple(d for entry in entries for d in entry.diagnostics))
+
+
+def diagnostics(*values: ReadValue[Any]) -> tuple[Diagnostic, ...]:
+    """Collect local interpretation issues; absence/null are availability, not schema verdicts."""
+    return tuple(d for value in values for d in value.diagnostics)