cgtype

class CGType:
    """Base of every CaptureGraph type."""

    __slots__ = ()

    # False only for ``Path``/``Void``, which are addresses and side effects.
    storable: ClassVar[bool] = True

    # Usable in recipes but banned from procedure/target schemas (no platform mirror).
    analysis_only: ClassVar[bool] = False

    @classmethod
    def schema(cls) -> dict[str, JSONValue]:
        """This type's structural wire form."""
        raise NotImplementedError(f"{cls.__name__} has no wire form")

    @classmethod
    def load(cls, base: Path) -> Self:
        """The value stored at ``base``.

        Raises:
            FileNotFoundError: If nothing is stored there.
        """
        raise TypeError(f"{cls.__name__} has no on-disk form to load")

    @classmethod
    def store(cls, base: Path, value: object) -> None:
        """Write ``value`` at ``base``, touching only leaves whose bytes change.

        Raises:
            TypeError: If ``value`` cannot be stored as this type.
        """
        raise TypeError(f"{cls.__name__} has no on-disk form to store")

    @classmethod
    def _children(cls) -> list[tuple[str, type[CGType]]]:
        """The child types this one declares, each labelled by its position.

        A struct field is ``.name``, a container element ``[*]``, and a ``Path``
        target shares its address (``""``); a leaf declares none.
        """
        return []

    @classmethod
    def _descend(cls, component: str) -> type[CGType]:
        """The child type one on-disk ``component`` reaches from this type.

        Raises:
            SchemaPathError: If this type is a leaf, or ``component`` is not one
                of its declared entries.
        """
        raise SchemaPathError(f"cannot descend into {cls.__name__!r} at {component!r}")

class SchemaPathError(ValueError):
    """A path component is not a declared entry of the schema at its position."""