access

@make_procedure
class GetRoot(Procedure[Path]):
    """The root position of the target schema (``Path[Schema]``).

    A target ``schema`` is required: every path is concretely typed, so there is
    no untargeted root. The schema is consumed at construction — moved into the
    return type and cleared — so ``GetRoot`` serializes compactly (the schema is
    carried once at the top of the wire form, not per node).

    Attributes:
        schema: The target ``Struct`` type this roots at. Required, then consumed
            into the return type and never serialized as a setting.
    """

    schema: Setting[type] | None = None

    def _resolve_type(self) -> type[CGType]:
        """``Path`` at the target ``schema``, consuming the setting."""
        if self.schema is None:
            raise TypeError(
                "GetRoot requires a target schema; there is no untargeted root "
                "(every path carries a concrete target)"
            )
        rooted = Path[self.schema]
        object.__setattr__(self, "schema", None)
        return rooted

@make_procedure
class LoadPath(Procedure[CGType]):
    """Read the value stored at a position, with a fallback for an empty one.

    Reads ``Procedure[Path[T]]`` → ``Procedure[T]``, with an explicit fallback
    for a position holding nothing.

    Loading is explicit: the authoring surface builds this only through
    ``path.load()`` / ``path.load_or(default)`` (an unassigned position used as a
    value never lowers to a silent disk read). The read goes to disk regardless of
    any value cached at the slot this run — it sees what was already present
    before the run — so reading and then ``&=``-overwriting the same slot is
    acyclic by construction.

    The ``default`` runs only on a *definitive* "nothing stored here" answer,
    never while the value is still loading, so a slow remote read cannot be
    mistaken for an absent one. The default ``NullProcedure`` produces no value,
    which leaves an absent read pending — waiting on whatever will write the slot.

    Attributes:
        source: The ``Path`` to the value to read.
        default: The procedure whose value stands in when nothing is stored at
            ``source``. Omitted, it becomes a ``NullProcedure`` of the target type.
    """

    source: Procedure[Path]
    default: Procedure[CGType] | None = None

    def _resolve_type(self) -> type[CGType]:
        """The source position's target type, filling in an absent ``default``."""
        target = path_target(self.source)
        if self.default is None:
            from capturegraph.procedures.nodes.process.control import (
                NullProcedure,
            )

            object.__setattr__(self, "default", NullProcedure(output_type=target))
        else:
            check_type(self.default.return_type, target, "LoadPath default")
        return target

@make_procedure
class PathAppend(Procedure[Path]):
    """A fresh element slot at the end of an array (used by the loop).

    Returns ``Path[E]``.

    Attributes:
        source: The ``Path`` to the ``Array`` to append into.
    """

    source: Procedure[Path]

    def _resolve_type(self) -> type[CGType]:
        """The position of a fresh element of the source array."""
        return Path[array_element(path_target(self.source), "PathAppend")]

@make_procedure
class PathField(Procedure[Path]):
    """Descend into a named struct field. Returns ``Path[FieldType]``.

    Attributes:
        source: The ``Path`` to the struct.
        field: The field name to descend into.
    """

    source: Procedure[Path]
    field: Setting[str]

    def _resolve_type(self) -> type[CGType]:
        """The position of the source's named field."""
        return Path[struct_field(path_target(self.source), self.field, "PathField")]

@make_procedure
class PathIndex(Procedure[Path]):
    """Index one array element (negative indexes from the end). Returns ``Path[E]``.

    Attributes:
        source: The ``Path`` to the ``Array``.
        index: The integer position (e.g. ``-1`` for the last entry).
    """

    source: Procedure[Path]
    index: Setting[int]

    def _resolve_type(self) -> type[CGType]:
        """The position of one of the source array's elements."""
        return Path[array_element(path_target(self.source), "PathIndex")]

@make_procedure
class PathKey(Procedure[Path]):
    """Select a map entry by a runtime key value. Returns ``Path[V]``.

    Attributes:
        source: The ``Path`` to the ``Map``.
        key: A procedure producing the key value (a keyable scalar matching the
            map's key type).
    """

    source: Procedure[Path]
    key: Procedure[CGType]

    def _resolve_type(self) -> type[CGType]:
        """The position of the source map's entry for this key."""
        return Path[map_entry(path_target(self.source), self.key.return_type, "PathKey")]

@make_procedure
class PathKeys(Procedure[Array]):
    """Enumerate a map's keys. Returns ``Array[KeyScalar]``.

    A value, since keys are read-only (index it with ``ArrayIndex`` to select
    one).

    Attributes:
        source: The ``Path`` to the ``Map``.
    """

    source: Procedure[Path]

    def _resolve_type(self) -> type[CGType]:
        """An ``Array`` of the source map's key type."""
        key, _ = map_types(path_target(self.source), "PathKeys")
        return Array[key]

@make_procedure
class PathValues(Procedure[Array]):
    """Enumerate a map's entry positions. Returns ``Array[Path[V]]``.

    An array of positions to fan out over (or index with ``ArrayIndex`` to
    select one, which stays navigable as ``Path[V]``).

    Attributes:
        source: The ``Path`` to the ``Map``.
    """

    source: Procedure[Path]

    def _resolve_type(self) -> type[CGType]:
        """An ``Array`` of the source map's entry positions."""
        _, value = map_types(path_target(self.source), "PathValues")
        return Array[Path[value]]