io

def commit(
    path: Path | str,
    value: object,
    schema: type[CGType] | dict[str, JSONValue] | None = None,
) -> Path:
    """Write ``value`` rooted at ``path``, touching only the leaves that changed.

    The write is incremental (an unchanged leaf is left alone) and additive (no
    existing entry is removed), so it is safe to re-commit a modified value — only
    the changed parts hit disk — or to commit at a sub-path to update one slot.

    Args:
        path: Destination root (the schema appends its own suffixes/folders).
        value: The value to write — a types value matching ``schema``.
        schema: The type describing ``value``. Optional when ``value`` is itself a
            ``CGType`` (its own type is used); required — as a ``CGType`` subclass
            or a schema ``dict`` — when ``value`` is a bare ``Path``, or to port
            ``value`` onto a *different* target type.

    Returns:
        The destination ``Path``.
    """
    cgtype = _commit_type(value, schema)
    destination = Path(path)
    cgtype.store(destination, value)
    return destination

def copy(*, src: Array, dst: Array) -> Array:
    """Copy files from source paths to destination paths.

    Destination parent directories are created as needed. A missing or None
    source produces a Missing placeholder in the result instead of raising.

    Args:
        src: Array of source file paths.
        dst: Array of destination paths (same length as src).

    Returns:
        Array of destination paths that were created.
    """

    def _copy_one(src_path: object, dst_path: Path) -> Path | _Missing:
        if is_missing(src_path) or src_path is None:
            return _Missing(ValueError(f"Source path is missing: {src_path}"))
        if not isinstance(src_path, (str, Path)):
            return _Missing(TypeError(f"Source path is not a path: {src_path!r}"))
        dst_path = Path(dst_path)
        dst_path.parent.mkdir(parents=True, exist_ok=True)
        copy2(src_path, dst_path)
        return dst_path

    return Array(_copy_one(s, d) for s, d in zip(src, dst, strict=True))

def load(path: Path | str, schema: type[CGType] | dict[str, JSONValue]) -> object:
    """Load a captured value from ``path`` according to ``schema``.

    File leaves resolve to their path (the media is opened only on demand), so a
    load is metadata-weight; to read one slot of a large target without the rest,
    point ``path`` and ``schema`` at the sub-tree.

    Args:
        path: The capture root on disk.
        schema: The type describing the data — a ``cg.Struct`` subclass (or any
            ``CGType``), or a schema ``dict`` (rebuilt with ``cg.from_schema``).

    Returns:
        The loaded value — a ``Struct``/``Array``/``Map`` that broadcasts
        attribute access for vectorized analysis.
    """
    cgtype = from_schema(schema) if isinstance(schema, dict) else schema
    return cgtype.load(Path(path))